Muonroi.RuleEngine.Abstractions 1.0.0-alpha.16

Muonroi.RuleEngine.Abstractions

Contracts-only package that defines the rule engine interfaces, execution model, and shared value types used across the entire Muonroi Rule Engine ecosystem.

This package ships contracts only — interfaces, records, enums, and attributes. It contains no orchestration runtime, DI registrations, or rule-execution logic. Depend on it when authoring rules or writing code that consumes orchestration results without a direct dependency on a concrete engine.

For a working rule engine, add Muonroi.RuleEngine.Core (base orchestrator + DI wiring) or one of the specialised adapters such as Muonroi.AspNetCore.RuleEngine.

Installation

dotnet add package Muonroi.RuleEngine.Abstractions --prerelease

Quick Start

Implement IRule<TContext> to define a rule. The context type must implement IRuleContext.

using Muonroi.RuleEngine.Abstractions;

// 1. Define the context
public sealed class OrderContext : IRuleContext
{
    public decimal Amount { get; init; }
    public string CustomerType { get; init; } = "";

    private bool _halted;
    public void HaltGroup() => _halted = true;
}

// 2. Implement a rule
[RuleGroup("order-discount")]
public sealed class HighValueOrderRule : IRule<OrderContext>
{
    public string Code => "HIGH_VALUE_ORDER";
    public int Order => 0;

    public Task<RuleResult> EvaluateAsync(OrderContext ctx, FactBag facts, CancellationToken ct)
    {
        bool isHighValue = ctx.Amount >= 1000m;
        decimal discount = isHighValue ? 0.10m : 0m;
        facts.Set("discountRate", discount);
        facts.Set("isHighValueOrder", isHighValue);
        return Task.FromResult(RuleResult.Passed());
    }
}

Register and execute via Muonroi.RuleEngine.Core:

// Program.cs (requires Muonroi.RuleEngine.Core)
using Muonroi.RuleEngine.Core;

builder.Services.AddRuleEngine<OrderContext>();
builder.Services.AddRulesFromAssemblies(typeof(Program).Assembly);

See Quickstart.RuleEngine for a complete working example.

Features

• IRule<TContext> — base rule contract with Code, Order, DependsOn, HookPoint, and EvaluateAsync / ExecuteAsync
• ICompensatableRule<TContext> — extends IRule<TContext> with CompensateAsync for Saga-pattern rollback
• IRuleContext — minimal context marker with HaltGroup() to short-circuit a rule group
• FactBag — typed key/value store shared between rules during a single orchestration run; supports Set<T>, Get<T>, TryGet<T>, Remove, and JsonElement auto-conversion
• IMRuleOrchestrator<TContext> — primary orchestration entry point; returns OrchestratorResult
• OrchestratorResult — immutable execution summary with IsSuccess, ExecutionMode, per-rule RuleResults, aggregated Errors, and CompensationErrors
• ExecutionMode — three strategies: AllOrNothing (default, stops on first failure), BestEffort (aggregates all failures), CompensateOnFailure (stops + compensates in reverse order)
• RuleExecutionMode — routing enum for gradual migration: Traditional, Rules, Hybrid, Shadow
• IRuleFactory<TContext> — DI-based rule instantiation contract
• IRuleEventListener<TContext> — hook interface for observing rule lifecycle events
• IHookHandler<TContext> — interface for pre/post rule execution hooks
• Authoring attributes — [RuleGroup], [TenantRuleGroupAttribute], [ExtractAsRuleAttribute], [RuleModeAttribute], [MRuleCatalogEntryAttribute], [MRuleContextDescriptionAttribute], [MRuleFactDescriptionAttribute]
• Authoring manifest models — MRuleAuthoringManifest, MRuleAuthoringEntry, MFactEntry, MFactSchemaNode, MFactSchemaField
• Decision table models — RawDecisionTable, RawHitPolicy, FEEL expression types
• Canary rollout contracts — ICanaryRolloutService, CanaryRolloutRecord, StartCanaryRequest
• Rule set approval contracts — IRuleSetApprovalService, RuleSetRecord, RuleSetStatus

Configuration

This package contains no DI registrations or runtime configuration. Configuration (options, assembly scanning, quota hooks) lives in Muonroi.RuleEngine.Core. See that package's README for AddRuleEngine<TContext> and MRuleEngineOptions.

API Reference

Samples

• Quickstart.RuleEngine — minimal rule with IRule<TContext>, FactBag, and RuleResult
• Quickstart.AspNetCore.RuleEngine — ASP.NET Core integration with middleware pipeline
• Quickstart.RuleEngine.EntityFrameworkCore — persisted rule sets via EF Core
• Quickstart.RuleEngine.NRules — NRules backend adapter
• Quickstart.RuleEngine.Proliferation — rule proliferation and catalog management
• Quickstart.RuleEngine.Runtime.Web — runtime web API for rule management

Compatibility

• Target framework: net8.0
• License: Apache-2.0 (OSS)

Related Packages

• Muonroi.RuleEngine.Core — concrete orchestrator, DI extensions (AddRuleEngine<T>, AddRulesFromAssemblies), and MRuleEngineOptions
• Muonroi.AspNetCore.RuleEngine — ASP.NET Core middleware integration
• Muonroi.RuleEngine.Runtime — full runtime with rule set persistence, FEEL expressions, and workflow cache
• Muonroi.RuleEngine.Runtime.Web — REST API layer for runtime rule management
• Muonroi.RuleEngine.EntityFrameworkCore — EF Core rule set store
• Muonroi.RuleEngine.DecisionTable — decision table evaluation engine
• Muonroi.RuleEngine.NRules — NRules backend adapter
• Muonroi.RuleEngine.SourceGenerators — source generator that scaffolds rule registrations from [ExtractAsRuleAttribute]
• Muonroi.RuleEngine.Testing — fluent test helpers and MFactBagAssertions

License

Apache-2.0. See LICENSE-APACHE for the full text.