# Architecture

MoonRule separates compilation from evaluation. A rule is parsed once, stored as an immutable `Program`, and evaluated repeatedly against JSON inputs.

## Pipeline

```text
source expression
      |
      v
    lexer  ---- structured lexical diagnostics
      |
      v
 precedence parser ---- structured parser diagnostics
      |
      v
 immutable AST / Program
      |
      +----------------------+----------------------+
      |                      |                      |
      v                      v                      v
 evaluator              traced evaluator      static analyzer
      |                      |                      |
      v                      v                      v
 JSON result          result + steps       paths/cost/findings
                                                    |
                                                    v
                                            admission policy
      |
      v
 RuleSet aggregation and report
```

## Components

- `span.mbt`: half-open source ranges used by diagnostics and traces.
- `token.mbt`, `lexer.mbt`: token model and single-pass lexer.
- `ast.mbt`, `parser.mbt`: immutable expression model and recursive-descent parser.
- `evaluator.mbt`: strict JSON evaluation semantics and built-in functions.
- `diagnostic.mbt`: stable error codes, source locations and actionable hints.
- `trace.mbt`: deterministic evaluation trace for explanations and auditing.
- `ruleset.mbt`: reusable multi-rule compilation and complete report aggregation.
- `api.mbt`: small public entry points: `compile`, `compile_with_limits`, `evaluate`, `check`.
- `resource_limits.mbt`: defensive source-length and AST-complexity limits for untrusted rules.
- `evaluation_limits.mbt`: deterministic execution-step budgets.
- `function_catalog.mbt`: machine-readable metadata for every built-in function.
- `validators.mbt`: deterministic date, timestamp, address and identifier validators.
- `analyzer.mbt`, `ruleset_analysis.mbt`: static analysis for programs and rule sets.
- `analysis_policy.mbt`: CI-oriented static-analysis admission decisions.
- `rule_test_suite.mbt`: version-controlled rule expectations and regression reports.
- `policy.mbt`: severity-aware policy evaluation and batch reports.
- `ruleset_limits.mbt`: defensive limits and validation for external rule configuration.
- `cmd/main`: file and inline command-line interface.

## Design decisions

### Strict types

MoonRule does not treat arbitrary values as truthy. This prevents common policy mistakes such as accepting the string `"false"` as a boolean.

### No side effects in the language

Expressions cannot mutate input, access the filesystem, perform network calls or execute arbitrary code. A program is deterministic for a given JSON input.

### Compilation is reusable

Parsing is kept out of the request-time evaluation path. Services can compile their rules during startup and reuse the resulting programs.

### Untrusted input is bounded

`compile` applies conservative defaults. Integrators accepting user-authored rules can call
`compile_with_limits` to set maximum source length, AST node count, and AST depth. Limit
violations use stable `P020`–`P022` diagnostics; invalid limit configuration uses `C010`.

### Errors are data

Public APIs return `Result` values. Diagnostics have stable codes and source ranges, making them suitable for CLIs, editors and API responses.

### Complete batch reports

`RuleSet` evaluates all configured rules by default. `evaluate_with_options` can apply a severity threshold or stop early, while `evaluate_batch` reuses compiled programs across many records.

### Rules are testable configuration

`RuleTestSuite` treats independently deployed rule files as version-controlled behavior. It reuses one compiled `RuleSet` for all named inputs, distinguishes ordinary false outcomes from evaluation errors, and produces a deterministic CI report.

## Security boundary

MoonRule evaluates a deliberately small expression language rather than embedding a general-purpose interpreter. There are no loops or recursion, so execution cost is bounded primarily by expression size, input collection size and regular-expression behavior.

Before accepting untrusted rules, applications should still enforce application-level limits on:

- JSON input depth and size;
- number of configured rules;
- JSON collection sizes and total input size.

Expression length, AST node count, AST depth, rule count, combined source size, evaluation steps, and regular-expression text sizes are enforced by the engine. `AnalysisPolicy` adds an earlier CI admission layer for complexity, warnings, and dynamic regular expressions.