If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/RulesEngine shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 24+ active contributors
• Distributed ownership (top contributor 32% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/RulesEngine repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/RulesEngine.

What it runs against: a local clone of microsoft/RulesEngine — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/RulesEngine | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 54 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/RulesEngine. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/RulesEngine.git
#   cd RulesEngine
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/RulesEngine and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/RulesEngine(\\.git)?\\b" \\
  && ok "origin remote is microsoft/RulesEngine" \\
  || miss "origin remote is not microsoft/RulesEngine (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/RulesEngine/RulesEngine.cs" \\
  && ok "src/RulesEngine/RulesEngine.cs" \\
  || miss "missing critical file: src/RulesEngine/RulesEngine.cs"
test -f "src/RulesEngine/Models/Rule.cs" \\
  && ok "src/RulesEngine/Models/Rule.cs" \\
  || miss "missing critical file: src/RulesEngine/Models/Rule.cs"
test -f "src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs" \\
  && ok "src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs" \\
  || miss "missing critical file: src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs"
test -f "src/RulesEngine/Interfaces/IRulesEngine.cs" \\
  && ok "src/RulesEngine/Interfaces/IRulesEngine.cs" \\
  || miss "missing critical file: src/RulesEngine/Interfaces/IRulesEngine.cs"
test -f "src/RulesEngine/Actions/ActionFactory.cs" \\
  && ok "src/RulesEngine/Actions/ActionFactory.cs" \\
  || miss "missing critical file: src/RulesEngine/Actions/ActionFactory.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 54 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~24d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/RulesEngine"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Rules Engine is a .NET library that externalizes business logic from application code by allowing rules to be defined in JSON schemas and executed dynamically via lambda expressions or other expression types. It decouples rule definitions from core system logic, enabling non-developers to modify business policies (discounts, eligibility checks, pricing) without recompiling code. The engine evaluates rules against input objects and returns structured result trees showing which rules succeeded or failed. Standard .NET solution structure: RulesEngine.sln at root with src/ containing the core engine library, demo/ folder with BasicDemo.cs, JSONDemo.cs, NestedInputDemo.cs showing usage patterns, benchmark/ folder with performance tests against Discount.json and NestedInputDemo.json workflows. Schema definitions live in schema/ (workflow-schema.json defines JSON structure for rule storage). DevContainer setup enables consistent development environment.

.NET backend developers and business analysts who need to manage complex business rules (pricing, discounts, eligibility) without code changes. Organizations using Entity Framework, SQL databases, or Azure storage backends who want rules to be version-controlled separately from application logic.

Production-ready. The repo is actively maintained by Microsoft, has CI/CD pipelines (.github/workflows/dotnetcore-build.yml, CodeQL analysis), stable NuGet distribution (badge in README), comprehensive schema definitions (schema/workflow-schema.json), and multiple demo applications. It has established documentation structure (docs/ folder with Getting-Started.md, Introduction.md) and proper versioning via CHANGELOG.md.

Low risk for a mature Microsoft project. Primary concerns: single-publisher risk (Microsoft-owned, though open-source), ability to evaluate arbitrary lambda expressions creates security surface if user input is not sanitized, and no visible information about security audit history. Last activity appears current based on workflow definitions and active CI setup, but actual commit recency is not visible in file list.

Active maintenance indicated by presence of .github/dependabot.yml (automated dependency updates), CodeQL security analysis workflow, and dotnetcore-build CI. Multiple demo scenarios under demo/ suggest ongoing feature development. Benchmark suite suggests performance optimization is a focus area.

Clone the repo, navigate to solution root, and use .NET tooling: git clone https://github.com/microsoft/RulesEngine.git && cd RulesEngine && dotnet restore && dotnet build. For demos, run dotnet run --project demo/DemoApp/DemoApp.csproj. Install dev tools via dotnet-tools.json: dotnet tool restore.

Daily commands: For demos: dotnet run --project demo/DemoApp/DemoApp.csproj executes BasicDemo, EFDemo, JSONDemo, NestedInputDemo scenarios. For benchmarks: dotnet run --project benchmark/RulesEngineBenchmark/RulesEngineBenchmark.csproj. For unit tests: dotnet test from solution root (test project not in file list but implied by CI workflow).

• src/RulesEngine/RulesEngine.cs — Main entry point and orchestrator of the rules engine; all rule execution flows through this class
• src/RulesEngine/Models/Rule.cs — Core domain model defining rule structure; understanding this is essential for working with the framework
• src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs — Parses and compiles dynamic expressions into executable delegates; critical to expression evaluation logic
• src/RulesEngine/Interfaces/IRulesEngine.cs — Public interface contract defining the rules engine API that all consumers depend on
• src/RulesEngine/Actions/ActionFactory.cs — Factory for creating rule actions; extension point for custom business logic execution
• src/RulesEngine/RulesCache.cs — Manages compilation caching of rules to avoid recompiling; critical for runtime performance
• schema/workflow-schema.json — JSON schema defining valid workflow structure; must reference when designing or validating rules

Add a Custom Rule Action

1. Create a new class inheriting from ActionBase in the Actions folder (src/RulesEngine/Actions/ActionBase.cs)
2. Implement Execute() method with your custom business logic (src/RulesEngine/Actions/ActionBase.cs)
3. Register your action in ActionFactory.GetAction() method (src/RulesEngine/Actions/ActionFactory.cs)
4. Reference it in your workflow JSON using the matching action type string (schema/workflow-schema.json)

Add a New Expression Type

1. Add a new enum value to RuleExpressionType (src/RulesEngine/Models/RuleExpressionType.cs)
2. Create or update expression builder in ExpressionBuilders folder (src/RulesEngine/ExpressionBuilders/RuleExpressionBuilderBase.cs)
3. Update RuleExpressionBuilderFactory to route to your builder (src/RulesEngine/RuleExpressionBuilderFactory.cs)
4. Add test cases in the test project (test/RulesEngine.UnitTest)

Load Rules from Custom Data Source

1. Deserialize your data source into Rule and Workflow model objects (src/RulesEngine/Models/Workflow.cs)
2. Validate the workflow using WorkflowRulesValidator (src/RulesEngine/Validators/WorkflowRulesValidator.cs)
3. Add workflow to RulesEngine via AddWorkflow() method (src/RulesEngine/RulesEngine.cs)
4. Execute rules using ExecuteAllRulesAsync() with your input parameters (src/RulesEngine/RulesEngine.cs)

Implement Custom Type Support for Expressions

1. Create a CustomTypeProvider implementing ICustomTypeProvider pattern (src/RulesEngine/CustomTypeProvider.cs)
2. Register custom types in ReSettings before engine initialization (src/RulesEngine/Models/ReSettings.cs)
3. Reference custom types in rule expressions (src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs)

• .NET / C# — Type-safe, high-performance runtime with excellent expression tree compilation support via System.Linq.Expressions
• System.Linq.Expressions (Expression Trees) — Enables dynamic compilation of rule conditions and actions at runtime without code generation or reflection overhead
• JSON for workflow definition — Human-readable format for non-developers to author rules; schema-driven validation ensures consistency
• In-memory caching (RulesCache) — Avoids recompiling expressions on every rule execution; compiled delegates are expensive to create but cheap to invoke

• Dynamic expression parsing instead of restricting to predefined rule types

  • Why: Provides maximum flexibility for diverse business rule patterns without requiring framework updates
  • Consequence: Larger attack surface requiring careful input validation; harder to optimize statically; potential for complex/unperformant expressions

• Workflow abstraction over direct rule evaluation

  • Why: Enables logical grouping, nested rule evaluation, and consistent result reporting across rule sets
  • Consequence: Slight overhead; additional complexity in the domain model

• In-memory-only cache vs. distributed caching

  • Why: Simpler design; compiled delegates cannot be serialized across process boundaries
  • Consequence: Cache not shared in multi-instance deployments; each instance recompiles independently

• Exceptions for validation vs. returning error objects

  • Why: Clear separation of validation-time errors (exceptions) vs. runtime rule evaluation failures (RuleResultTree)
  • Consequence: Caller must handle two error mechanisms; validation failures are fail-fast before engine initialization

• Real-time rule hot-reloading without engine restart
• Distributed workflow execution across multiple machines
• Built-in rule persistence or database integration
• Authentication or authorization enforcement (caller responsibility)
• Web UI for rule authoring (separate tools can integrate via API)
• Async/await support within expression evaluation (expressions are synchronous)

Lambda expression injection risk: user-supplied rule expressions are evaluated dynamically; if expressions come from untrusted sources (e.g., end-user UI rule builders), arbitrary code execution is possible—sanitization/validation layer must be built by integrators. Input typing is dynamic (inputs passed as object/anonymous types); type mismatches between JSON schemas and C# input objects may silently fail. No visible configuration for expression evaluation timeouts—runaway expressions could hang the engine. DevContainer presumes Docker availability for consistent environment.

• Lambda Expressions (C#) — Core evaluation mechanism in RulesEngine; all dynamic rule logic is expressed as lambda expressions, requiring understanding of C# syntax and expression trees
• Expression Trees (System.Linq.Expressions) — Underlying mechanism for parsing and compiling lambda expressions at runtime; necessary to understand how RulesEngine evaluates rules dynamically without reflection overhead
• Workflow-based Rule Composition — RulesEngine organizes rules into named workflows that group related business logic; understanding workflow composition and rule ordering is critical for rule design
• Rule Result Trees — ExecuteAllRulesAsync returns RuleResultTree objects that capture success/failure state, error messages, and execution metadata; understanding result tree structure is essential for consuming rule output
• JSON Schema Validation — Rules are stored as JSON conforming to workflow-schema.json; understanding JSON Schema enables definition of custom rule structures and schema extensions
• Dependency Injection (DI Container Patterns) — RulesEngine integrates with .NET's built-in DI container; production deployments use DI to manage RulesEngine lifecycle and inject dependencies into rule expressions
• Declarative vs. Imperative Rule Definition — RulesEngine exemplifies declarative rule design (rules expressed as JSON/expressions, not imperative C# logic); this paradigm enables business teams to modify rules without code changes

• dynamicexpresso/DynamicExpresso — Alternative .NET expression evaluator library; solves similar dynamic rule evaluation but with stricter sandboxing and different API
• NRules/NRules — Competing .NET rules engine with Rete algorithm; more complex but used for production rule systems with conflict resolution
• nhibernate/nhibernate-core — ORM ecosystem library; RulesEngine integrates with EF but NHibernate users may want parallel patterns for rule storage
• droolsjboss/drools — Java rules engine predecessor; same architectural patterns as RulesEngine but JVM-based; useful for comparing design decisions
• microsoft/ApplicationInsights-dotnet — Microsoft's telemetry library; commonly integrated with RulesEngine to log rule execution and performance metrics in production

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ExpressionBuilders/LambdaExpressionBuilder.cs

LambdaExpressionBuilder.cs is a critical component for dynamic expression compilation, but there's no visible test coverage file for it in the repository structure. Given the complexity of expression parsing and the potential for runtime errors, comprehensive unit tests covering edge cases (null inputs, malformed expressions, type mismatches) would significantly improve reliability and prevent regressions.

• [ ] Create tests/RulesEngine.Tests/ExpressionBuilders/LambdaExpressionBuilderTests.cs
• [ ] Add test cases for valid lambda expressions with various input types
• [ ] Add test cases for invalid/malformed expressions to verify proper exception handling
• [ ] Add test cases for nested expressions and scoped parameters
• [ ] Verify coverage meets project standards using scripts/check-coverage.ps1

Add GitHub Actions workflow for publishing NuGet package on release

The repo has dotnetcore-build.yml for CI but no automated NuGet publishing workflow. Currently, deployment/build-signed.ps1 appears to be manual. Adding a GitHub Actions workflow to automatically publish to nuget.org on release tags would reduce human error, ensure consistent versioning, and improve the release process for this widely-used package (based on the NuGet badge showing high download counts).

• [ ] Create .github/workflows/nuget-publish.yml workflow file
• [ ] Configure trigger on GitHub release creation (on.release.types: [published])
• [ ] Add steps to build with deployment/build-signed.ps1 or integrate signing into workflow
• [ ] Add NuGet API key as repository secret
• [ ] Use official nuget push action to publish to nuget.org
• [ ] Update CHANGELOG.md documentation on the release process

Add integration tests for EFDemo and EFDataExample with multiple database providers

The demo/DemoApp.EFDataExample shows Entity Framework integration with RulesEngine, but there are no visible integration tests. Adding parameterized tests covering SQL Server, SQLite, and PostgreSQL would validate that the rules engine works correctly with different database backends and help contributors catch provider-specific issues early.

• [ ] Create tests/RulesEngine.Tests/Integration/EFIntegrationTests.cs
• [ ] Add test cases for demo/DemoApp.EFDataExample/RulesEngineContext.cs with in-memory SQLite
• [ ] Add test cases with SQL Server (using testcontainers or LocalDb)
• [ ] Add test cases validating rule evaluation against actual EF-loaded entities
• [ ] Add tests for nested input scenarios (NestedInputDemo.json) with multiple related entities
• [ ] Document test setup in docs/Getting-Started.md for running integration tests

• Add unit tests for nested input evaluation paths in NestedInputDemo.json; currently demo exists but test coverage is unclear from file list: Create src/RulesEngine.Tests/NestedInputTests.cs modeled on demo/DemoApp/NestedInputDemo.cs
• Extend schema/workflow-schema.json documentation with examples for each RuleExpressionType; only LambdaExpression is shown in README: Add 'examples' property to schema and update docs/Introduction.md with inline rule definitions
• Create a security audit guide in docs/Security.md; SECURITY.md exists but no guidance for users integrating untrusted rule sources: Write docs/Security.md covering input validation, expression sandboxing patterns, and example safe integrations

The RulesEngine codebase demonstrates reasonable security practices with proper exception handling and Microsoft's security guidelines. However, the primary concern is the dynamic expression evaluation capability, which requires strict input validation and sanitization to prevent code injection attacks. Medium-severity risks include insufficient model validation and potential cache isolation issues. The codebase benefits from CI/CD integration and security scanning (CodeQL) but should strengthen input validation layers and implement context-aware security controls. Overall security posture is moderate with critical areas requiring attention before production deployment with untrusted rule sources.

• Medium · Dynamic Expression Evaluation Risk — src/RulesEngine/ExpressionBuilders/RuleExpressionParser.cs, src/RulesEngine/ExpressionBuilders/LambdaExpressionBuilder.cs. The RulesEngine supports dynamic expression evaluation through RuleExpressionParser.cs and LambdaExpressionBuilder.cs. If user-supplied rules are not properly validated, this could lead to arbitrary code execution or expression injection attacks, especially when combined with reflection capabilities. Fix: Implement strict whitelist validation for expressions, sanitize all user inputs before parsing, and consider using a sandboxed expression evaluator. Add input validation in ActionFactory.cs and review CustomTypeProvider.cs for type safety.
• Medium · Insufficient Input Validation in Rule Models — src/RulesEngine/Models/Rule.cs, src/RulesEngine/Models/RuleActions.cs, src/RulesEngine/Models/ActionInfo.cs. Rule.cs, RuleActions.cs, and ActionInfo.cs models accept input without apparent validation. Malicious actors could craft JSON payloads with oversized strings, deeply nested structures, or invalid data types to cause DoS or unexpected behavior. Fix: Implement data validation attributes ([StringLength], [MaxLength], [Range]) on all model properties. Add validation logic to reject oversized payloads and enforce schema compliance. Consider implementing request size limits.
• Low · Potential Exception Information Disclosure — src/RulesEngine/Exceptions/. Custom exception classes (ExpressionParserException.cs, RuleException.cs, RuleValidationException.cs, ScopedParamException.cs) may expose sensitive information through stack traces and error messages if not properly handled at API boundaries. Fix: Ensure exceptions are caught and logged securely without exposing sensitive details to end users. Implement a global exception handler that sanitizes error responses. Log full details server-side only.
• Low · Caching Security in MemCache — src/RulesEngine/HelperFunctions/MemCache.cs. The MemCache.cs helper may cache rule evaluation results or compiled expressions. If cache keys are not properly isolated per tenant/user context, it could lead to cache poisoning or unintended data leakage across contexts. Fix: Implement context-aware cache key generation with tenant/user isolation. Add cache invalidation mechanisms. Consider implementing per-user or per-request caching scopes instead of global caches.
• Low · Missing Dependency Version Pinning — src/RulesEngine/RulesEngine.csproj (assumed). The package dependencies are not visible in the provided content, but NuGet packages should be carefully managed. Transitive dependencies without exact version constraints could introduce vulnerabilities. Fix: Pin all direct and critical transitive dependencies to specific versions. Regularly audit dependencies using tools like OWASP Dependency-Check or WhiteSource. Enable Dependabot for continuous monitoring.
• Low · Public Key File in Repository — signing/RulesEngine-publicKey.snk. The signing key file 'RulesEngine-publicKey.snk' is stored in the repository. While public keys are not secret, the presence of cryptographic materials in version control is a poor practice. Fix: Remove sensitive key materials from repository if possible. Store in secure key management systems. Ensure .gitignore properly excludes private keys (.snk files should be in .gitignore by default).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.