@gobing-ai/ts-rule-engine 0.3.14 → 0.3.16

package/README.md

@@ -31,7 +31,7 @@ erDiagram
 
 | Entity | One-line Description |
 |--------|----------------------|
-| `RuleEngine` | Orchestrates evaluation of enabled rules against a workspace directory. Supports opt-in early exit via `stopOnFirst` parameter. Accepts an optional `EventBus<RuleEngineEvents>` for structured in-process observability. |
+| `RuleEngine` | Orchestrates evaluation of enabled rules against a workspace directory. Constructor accepts `RuleEngineOptions` (host, persistence, events, runId, runMeta, etc.). Supports opt-in early exit via `stopOnFirst` parameter. |
 | `RuleEngineHost` | Capability host backed by `CapabilityRegistry` from `@gobing-ai/ts-runtime/extension` — holds evaluators, resolvers, formatters, and fixer providers, each with origin tracking for safe override detection. |
 | `CapabilityRegistry<T>` | Generic named registry (shared with `ts-rule-engine`, `ts-dual-workflow-engine`) that tags each entry with its `origin` (`'builtin'`, `'extension'`, `'caller'`). |
 | `ConstraintRule` | Declarative policy unit: id, severity, include/exclude globs, evaluator type + config, and optional fix config. |
@@ -45,6 +45,8 @@ erDiagram
 | `Fix` | Candidate byte-range replacement; collected separately from findings, written only on explicit `applyFixes()`. |
 | `RuleEngineResult` | Aggregate `{ findings, fixes }` returned from a single evaluation run. |
 | `RuleEngineEvents` | Typed event map for rule-engine observability. All events prefixed `rule.` — see [Observability](#observability). |
+| `RulePersistenceAdapter` | Durable adapter contract. Engine calls `insertRun`/`updateRunStatus` for the run, `insertEvalRun`/`updateEvalRun` per rule. DB-backed and memory-backed implementations included. |
+| `RULE_ENGINE_SCHEMA_SQL` | Engine-owned DDL export: `rule_runs` + `rule_eval_runs` tables plus the FK index. Consumers apply it up-front before creating a `DbRulePersistenceAdapter`. |
 | `bundledRulesRoot()` | Resolves the absolute path to the bundled `rules/` directory shipped with this package — portable defaults usable as the lowest-priority preset root. |
 ## Mental Model
 
@@ -65,11 +67,12 @@ flowchart TD
 Core concepts:
 
 - `ConstraintRule`: one policy check. It has an `id`, `severity`, evaluator type/config, optional include/exclude globs, and optional fix config.
-- `RuleEngine`: runs enabled rules against a `workdir`. The constructor auto-registers built-in evaluators, formatters, resolvers, and fixer providers.
+- `RuleEngine`: runs enabled rules against a `workdir`. The constructor auto-registers built-in evaluators, formatters, resolvers, and fixer providers. Accepts `RuleEngineOptions` for a custom host, `EventBus`, `processExecutor`, `persistence` adapter, `runId`, and `runMeta`.
 - `RuleEngineHost`: capability container backed by four `CapabilityRegistry` instances from `@gobing-ai/ts-runtime/extension`. Each entry tracks its origin (`'builtin'` / `'extension'` / `'caller'`) so the engine can detect and report conflicting registrations.
 - `RuleEvaluator`: implementation of one rule type, such as `regex`, `path`, or `coverage-gate`.
 - `Fix`: byte-range replacement candidate. Fixes are collected separately from findings and only written when you call `applyFixes()`.
 - Preset: YAML/JSON file that composes rule categories and can expose extension modules.
+- `RulePersistenceAdapter`: durable run/eval history. The engine writes directly to the adapter at lifecycle boundaries; a DB-backed adapter and a test-friendly memory adapter ship with the package.
 - `bundledRulesRoot()`: resolves the path to the `rules/` directory shipped with this package. Pass it as the lowest-priority root to `loadPreset()` so project-local and user-global roots shadow individual files while inheriting the rest.
 
 ## Execution Flow
@@ -819,15 +822,121 @@ When no `events` option is provided, the engine incurs zero observability overhe
 
 `rule.eval.error` is emitted when an evaluator **throws** — it signals a crash, not a policy violation. The engine still produces a `kind: 'error'` finding for the thrown rule. A normal policy violation emits **no** `rule.eval.error`. Don't conflate the two: subscribe to `rule.eval.error` for crash alerting, and inspect findings for policy results.
 
+## Persistence
+
+The engine supports a **durable persistence adapter** pattern (mirrors `@gobing-ai/ts-dual-workflow-engine`). When a `RulePersistenceAdapter` is injected via `RuleEngineOptions`, the engine writes run and per-rule evaluation rows directly — no EventBus subscriber needed.
+
+### DB Schema
+
+```mermaid
+erDiagram
+    RULE_RUNS ||--o{ RULE_EVAL_RUNS : "run_id → id"
+    RULE_RUNS {
+        TEXT       id                PK
+        TEXT       preset
+        TEXT       source_kind       "preset | file"
+        TEXT       source_value
+        TEXT       status            "running | done | failed"
+        INTEGER    rule_count
+        INTEGER    finding_count
+        INTEGER    fix_count
+        INTEGER    applied_fix_count
+        TEXT       fail_on
+        TEXT       stop_on_first
+        TEXT       fix_mode          "none | suggest | auto"
+        INTEGER    dry_run
+        TEXT       started_at        "ISO 8601"
+        TEXT       completed_at      "ISO 8601"
+        INTEGER    duration_ms
+        TEXT       metadata_json     "{}"
+        TEXT       created_at        "ISO 8601"
+        TEXT       updated_at        "ISO 8601"
+    }
+    RULE_EVAL_RUNS {
+        TEXT       id                PK
+        TEXT       run_id            FK
+        TEXT       rule_id
+        TEXT       severity          "error | warning | info"
+        TEXT       evaluator
+        TEXT       status            "running | done | failed | skipped"
+        INTEGER    finding_count
+        INTEGER    fix_count
+        INTEGER    duration_ms
+        TEXT       error
+        TEXT       findings_json
+        TEXT       fixes_json
+        TEXT       started_at        "ISO 8601"
+        TEXT       completed_at      "ISO 8601"
+        TEXT       created_at        "ISO 8601"
+        TEXT       updated_at        "ISO 8601"
+    }
+```
+
+- **`rule_runs`** is the list/query unit — one row per engine invocation.
+- **`rule_eval_runs`** is the per-rule detail unit — one row per evaluated rule, FK'd to `rule_runs`.
+- Timestamps are `TEXT` (ISO 8601) for portability across SQLite drivers including D1.
+- `status`: `running` during evaluation, `done` on normal completion (including policy failures), `failed` for engine/runtime errors. `skipped` when `stopOnFirst` prevents later rules from running.
+
+### Adapter Contract
+
+```ts
+interface RulePersistenceAdapter {
+    insertRun(input: RuleRunInput): Promise<void>;
+    updateRunStatus(runId, status, findingCount, fixCount, appliedFixCount, durationMs): Promise<void>;
+    insertEvalRun(input: RuleEvalRunInput): Promise<void>;
+    updateEvalRun(input: RuleEvalRunUpdate): Promise<void>;
+}
+```
+
+Two implementations ship with the package:
+
+| Adapter | What it does |
+|---------|-------------|
+| `DbRulePersistenceAdapter` | Writes directly to SQLite via a `@gobing-ai/ts-db` `DbAdapter`. Consumers apply the schema up-front with `RULE_ENGINE_SCHEMA_SQL`. |
+| `MemoryRulePersistenceAdapter` | Stores rows in `Map<string, Row>` — designed for unit tests. Lets test code assert on persisted run/eval state. |
+
+### Usage
+
+```ts
+import { RuleEngine, DbRulePersistenceAdapter, RULE_ENGINE_SCHEMA_SQL } from '@gobing-ai/ts-rule-engine';
+import { createDbAdapter } from '@gobing-ai/ts-db';
+
+const db = await createDbAdapter({ driver: 'bun-sqlite', url: ':memory:' });
+await db.exec(RULE_ENGINE_SCHEMA_SQL);
+
+const engine = new RuleEngine({
+    persistence: new DbRulePersistenceAdapter(db),
+    runId: 'my-run-1',
+    runMeta: {
+        sourceKind: 'preset',
+        sourceValue: 'recommended',
+        preset: 'recommended',
+        failOn: 'error',
+        stopOnFirst: 'false',
+        fixMode: 'none',
+        dryRun: false,
+    },
+});
+
+const result = await engine.evaluate(rules, process.cwd());
+// At this point, rule_runs has 'my-run-1' with status='done', findings, and duration.
+```
+
+- `runId`: caller-provided or engine-generated (`crypto.randomUUID()`). Persisted so downstream tools like `spur rule trace` can query history.
+- `runMeta`: metadata written to the initial run row — preset name, source/file info, fix mode, dry-run flag.
+- Persistence is **incremental**: the run row is inserted before the first rule, finalized after the last. Per-rule eval rows are inserted as each rule starts and updated when it finishes. A polling `trace` can surface partial progress.
+- When `persistence` is absent, the engine works normally — zero persistence overhead.
+
 ## Package Boundary
 
-This package owns rule definitions, preset loading, evaluators, formatters, test-path resolvers, fixer providers, extension loading, the `CapabilityRegistry` re-export from `@gobing-ai/ts-runtime/extension`, and bundled rule presets.
+This package owns rule definitions, preset loading, evaluators, formatters, test-path resolvers, fixer providers, extension loading, the `CapabilityRegistry` re-export from `@gobing-ai/ts-runtime/extension`, the persistence adapter contract and implementations, the engine-owned schema SQL, and bundled rule presets.
 
 It does **not** own:
 
 - CLI argument parsing or process exit policy
 - `ProcessExecutor` implementation (injected via `RuleEngineOptions`)
+- `DbAdapter` creation and lifecycle (injected via `RulePersistenceAdapter`)
 - Repository-specific rule catalogs (project rules live in `.spur/rules/`)
 - CI integration or publishing workflows
 
-Downstream tools (e.g. `spur`) consume the library and add their own CLI, config discovery, and execution policy.
+Downstream tools (e.g. `spur`) consume the library and add their own CLI, config discovery, run-id stamping, and execution policy.

package/dist/engine.d.ts

@@ -3,6 +3,7 @@ import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { RuleEngineEvents } from './events';
 import { type FixApplicationResult } from './fixers/fixers';
 import { RuleEngineHost } from './host/rule-engine-host';
+import type { RulePersistenceAdapter } from './persistence/adapter';
 import type { ConstraintRule, Fix, FixMode, RuleEngineResult, RuleEvaluator } from './types';
 /** Options for constructing a RuleEngine. */
 export interface RuleEngineOptions {
@@ -14,6 +15,12 @@ export interface RuleEngineOptions {
     events?: EventBus<RuleEngineEvents>;
     /** Optional logger; defaults to the shared `rule-engine` category logger. */
     logger?: Logger;
+    /** Optional persistence adapter for durable run/eval history. */
+    persistence?: RulePersistenceAdapter;
+    /** Caller-provided run ID; engine generates one if absent. */
+    runId?: string;
+    /** Caller metadata for the run row (preset, failOn, source info, etc.). */
+    runMeta?: Record<string, unknown>;
 }
 /** Orchestrates enabled constraint rules through a typed evaluator host. */
 export declare class RuleEngine {
@@ -21,6 +28,9 @@ export declare class RuleEngine {
     readonly host: RuleEngineHost;
     private readonly events;
     private readonly logger;
+    private readonly persistence;
+    private readonly runId;
+    private readonly runMeta;
     constructor(options?: RuleEngineOptions);
     /** Register or replace an evaluator. */
     registerEvaluator(type: string, evaluator: RuleEvaluator): void;
@@ -40,6 +50,10 @@ export declare class RuleEngine {
      * provider by evaluator type and calls `createFixes`. The effective fix mode
      * is the minimum of the rule's configured mode and `maxFixMode`.
      *
+     * When `options.persistence` is set, this method writes a run row before
+     * evaluation and per-rule eval rows during the loop. A `done`/`failed`
+     * status is written after the loop completes.
+     *
      * @param rules - Normalized rule definitions to evaluate.
      * @param workdir - Working directory to scan.
      * @param maxFixMode - Highest fix authority requested by the caller.

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAIH,KAAK,oBAAoB,EAE5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAqB,cAAc,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGhH,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mCAAmC;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,kEAAkE;IAClE,MAAM,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACpC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,qBAAa,UAAU;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,iBAAsB;IAQ3C,wCAAwC;IACxC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAI/D;;;;;;;OAOG;IACG,QAAQ,CACV,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAC3C,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;;;;;;;;;;;;;OAcG;IACG,iBAAiB,CACnB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,OAAgB,EAC5B,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAC3C,OAAO,CAAC,gBAAgB,CAAC;IAoH5B;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAG1G"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAIH,KAAK,oBAAoB,EAE5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAqB,cAAc,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGhH,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mCAAmC;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,kEAAkE;IAClE,MAAM,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACpC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,4EAA4E;AAC5E,qBAAa,UAAU;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;gBAElD,OAAO,GAAE,iBAAsB;IAW3C,wCAAwC;IACxC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAI/D;;;;;;;OAOG;IACG,QAAQ,CACV,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAC3C,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACnB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,OAAgB,EAC5B,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAC3C,OAAO,CAAC,gBAAgB,CAAC;IAkK5B;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAG1G"}

package/dist/engine.js

@@ -9,12 +9,18 @@ export class RuleEngine {
     host;
     events;
     logger;
+    persistence;
+    runId;
+    runMeta;
     constructor(options = {}) {
         this.host = options.host ?? new RuleEngineHost();
         registerBuiltins(this.host, options.processExecutor);
         registerBuiltinFixers(this.host, options.processExecutor);
         this.events = options.events;
         this.logger = options.logger ?? getLogger('rule-engine');
+        this.persistence = options.persistence;
+        this.runId = options.runId ?? crypto.randomUUID();
+        this.runMeta = options.runMeta;
     }
     /** Register or replace an evaluator. */
     registerEvaluator(type, evaluator) {
@@ -38,6 +44,10 @@ export class RuleEngine {
      * provider by evaluator type and calls `createFixes`. The effective fix mode
      * is the minimum of the rule's configured mode and `maxFixMode`.
      *
+     * When `options.persistence` is set, this method writes a run row before
+     * evaluation and per-rule eval rows during the loop. A `done`/`failed`
+     * status is written after the loop completes.
+     *
      * @param rules - Normalized rule definitions to evaluate.
      * @param workdir - Working directory to scan.
      * @param maxFixMode - Highest fix authority requested by the caller.
@@ -49,6 +59,20 @@ export class RuleEngine {
     async evaluateWithFixes(rules, workdir, maxFixMode = 'auto', stopOnFirst) {
         const enabledRules = rules.filter((r) => r.enabled !== false);
         const runStartMs = Date.now();
+        // Insert the run row before any evaluation.
+        const runMeta = this.runMeta ?? {};
+        await this.persistence?.insertRun({
+            id: this.runId,
+            sourceKind: runMeta.sourceKind ?? 'preset',
+            sourceValue: runMeta.sourceValue,
+            preset: runMeta.preset,
+            ruleCount: enabledRules.length,
+            failOn: runMeta.failOn,
+            stopOnFirst: runMeta.stopOnFirst,
+            fixMode: maxFixMode,
+            dryRun: runMeta.dryRun ?? false,
+            metadataJson: runMeta.metadataJson,
+        });
         return await traceAsync('rule.run', async () => {
             this.logger.info('rule run started', { enabled: enabledRules.length, total: rules.length });
             addSpanEvent('rule.run.start', { rules: enabledRules.length, total: rules.length });
@@ -61,12 +85,21 @@ export class RuleEngine {
                 if (rule.enabled === false)
                     continue;
                 index++;
+                // Persist eval start.
+                await this.persistence?.insertEvalRun({
+                    id: `${this.runId}:${rule.id}`,
+                    runId: this.runId,
+                    ruleId: rule.id,
+                    severity: rule.severity,
+                    evaluator: rule.evaluator.type,
+                });
                 const evalStartMs = Date.now();
                 this.logger.debug('eval start', { ruleId: rule.id, index, total: enabledRules.length });
                 addSpanEvent('rule.eval.start', { ruleId: rule.id, index, total: enabledRules.length });
                 void this.events?.emit('rule.eval.start', { ruleId: rule.id, index, total: enabledRules.length });
                 let ruleFindings = [];
                 let ruleEvalFixes = [];
+                let evalError;
                 try {
                     const result = await this.host.evaluators
                         .get(rule.evaluator.type)
@@ -75,15 +108,15 @@ export class RuleEngine {
                     ruleEvalFixes = result.fixes;
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    evalError = error instanceof Error ? error.message : String(error);
                     ruleFindings = [
-                        createFinding(rule, message, null, {
+                        createFinding(rule, evalError, null, {
                             code: `evaluator:${rule.evaluator.type}`,
                             kind: 'error',
                         }),
                     ];
-                    addSpanEvent('rule.eval.error', { ruleId: rule.id, error: message });
-                    void this.events?.emit('rule.eval.error', { ruleId: rule.id, error: message });
+                    addSpanEvent('rule.eval.error', { ruleId: rule.id, error: evalError });
+                    void this.events?.emit('rule.eval.error', { ruleId: rule.id, error: evalError });
                 }
                 const durationMs = Date.now() - evalStartMs;
                 addSpanEvent('rule.eval.done', {
@@ -96,6 +129,16 @@ export class RuleEngine {
                     findings: ruleFindings.length,
                     durationMs,
                 });
+                // Persist eval completion.
+                await this.persistence?.updateEvalRun({
+                    runId: this.runId,
+                    ruleId: rule.id,
+                    status: evalError ? 'failed' : 'done',
+                    findingCount: ruleFindings.length,
+                    fixCount: ruleEvalFixes.length,
+                    durationMs,
+                    ...(evalError ? { error: evalError } : {}),
+                });
                 findings.push(...ruleFindings);
                 fixes.push(...ruleEvalFixes);
                 const ruleMode = rule.fix?.mode ?? 'none';
@@ -142,6 +185,9 @@ export class RuleEngine {
                 durationMs: runDurationMs,
                 stoppedEarly: stoppedEarlyLocal,
             });
+            // Finalize the run row.
+            await this.persistence?.updateRunStatus(this.runId, 'done', findings.length, fixes.length, 0, // appliedFixCount — set by the caller after applying fixes
+            runDurationMs);
             return { findings, fixes };
         }, { attributes: { 'rule.count': enabledRules.length } });
     }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/bundled-rules';
 export * from './host/rule-engine-host';
+export * from './persistence';
 export * from './resolvers/test-path-resolver';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAClH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAClH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -14,5 +14,6 @@ export * from './formatters/json.js';
 export * from './formatters/text.js';
 export * from './host/bundled-rules.js';
 export * from './host/rule-engine-host.js';
+export * from './persistence/index.js';
 export * from './resolvers/test-path-resolver.js';
 export * from './types.js';

package/dist/persistence/adapter.d.ts

@@ -0,0 +1,53 @@
+import type { FixMode } from '../types';
+/** Input for inserting a rule run row (engine caller provides run metadata). */
+export interface RuleRunInput {
+    id: string;
+    preset?: string;
+    sourceKind: 'preset' | 'file';
+    sourceValue?: string;
+    ruleCount: number;
+    failOn?: string;
+    stopOnFirst?: string;
+    fixMode: FixMode;
+    dryRun: boolean;
+    metadataJson?: string;
+}
+/** Input for inserting a per-rule eval row. */
+export interface RuleEvalRunInput {
+    id: string;
+    runId: string;
+    ruleId: string;
+    severity: string;
+    evaluator: string;
+}
+/** Input for updating a per-rule eval row after evaluation completes. */
+export interface RuleEvalRunUpdate {
+    runId: string;
+    ruleId: string;
+    status: 'done' | 'failed' | 'skipped';
+    findingCount: number;
+    fixCount: number;
+    durationMs: number;
+    /** Evaluator error message, if status is 'failed'. */
+    error?: string;
+    /** Bounded JSON for findings. */
+    findingsJson?: string;
+    /** Bounded JSON for fixes. */
+    fixesJson?: string;
+}
+/**
+ * Persistence adapter contract for the rule engine.
+ * Implementations write directly to a durable store; the engine does NOT
+ * use EventBus subscribers for durability.
+ */
+export interface RulePersistenceAdapter {
+    /** Insert a run row as 'running'. Must be idempotent. */
+    insertRun(input: RuleRunInput): Promise<void>;
+    /** Finalize a run row after evaluation completes. */
+    updateRunStatus(runId: string, status: 'done' | 'failed', findingCount: number, fixCount: number, appliedFixCount: number, durationMs: number): Promise<void>;
+    /** Insert a per-rule eval row as 'running'. Must be idempotent. */
+    insertEvalRun(input: RuleEvalRunInput): Promise<void>;
+    /** Finalize a per-rule eval row after evaluation completes. */
+    updateEvalRun(input: RuleEvalRunUpdate): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/persistence/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/persistence/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,gFAAgF;AAChF,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC,yDAAyD;IACzD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,qDAAqD;IACrD,eAAe,CACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,QAAQ,EACzB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,mEAAmE;IACnE,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD,+DAA+D;IAC/D,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D"}

package/dist/persistence/db-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { DbAdapter } from '@gobing-ai/ts-db';
+import type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+/** Persist engine run/eval rows to SQLite via a ts-db DbAdapter. */
+export declare class DbRulePersistenceAdapter implements RulePersistenceAdapter {
+    private readonly db;
+    constructor(db: DbAdapter);
+    insertRun(input: RuleRunInput): Promise<void>;
+    updateRunStatus(runId: string, status: 'done' | 'failed', findingCount: number, fixCount: number, appliedFixCount: number, durationMs: number): Promise<void>;
+    insertEvalRun(input: RuleEvalRunInput): Promise<void>;
+    updateEvalRun(input: RuleEvalRunUpdate): Promise<void>;
+}
+//# sourceMappingURL=db-adapter.d.ts.map

package/dist/persistence/db-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-adapter.d.ts","sourceRoot":"","sources":["../../src/persistence/db-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE3G,oEAAoE;AACpE,qBAAa,wBAAyB,YAAW,sBAAsB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,SAAS;IAEpC,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB7C,eAAe,CACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,QAAQ,EACzB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAkBV,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBrD,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAoB/D"}

package/dist/persistence/db-adapter.js

@@ -0,0 +1,33 @@
+/** Persist engine run/eval rows to SQLite via a ts-db DbAdapter. */
+export class DbRulePersistenceAdapter {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async insertRun(input) {
+        const now = new Date().toISOString();
+        await this.db.run(`INSERT INTO rule_runs (id, preset, source_kind, source_value, status, rule_count,
+             fail_on, stop_on_first, fix_mode, dry_run, metadata_json, started_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, ?, ?, ?)`, input.id, input.preset ?? null, input.sourceKind, input.sourceValue ?? null, input.ruleCount, input.failOn ?? null, input.stopOnFirst ?? null, input.fixMode, input.dryRun ? 1 : 0, input.metadataJson ?? '{}', now, now, now);
+    }
+    async updateRunStatus(runId, status, findingCount, fixCount, appliedFixCount, durationMs) {
+        const now = new Date().toISOString();
+        await this.db.run(`UPDATE rule_runs
+             SET status = ?, finding_count = ?, fix_count = ?, applied_fix_count = ?,
+                 duration_ms = ?, completed_at = ?, updated_at = ?
+             WHERE id = ?`, status, findingCount, fixCount, appliedFixCount, durationMs, now, now, runId);
+    }
+    async insertEvalRun(input) {
+        const now = new Date().toISOString();
+        await this.db.run(`INSERT INTO rule_eval_runs (id, run_id, rule_id, severity, evaluator, status,
+             started_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, 'running', ?, ?, ?)`, input.id, input.runId, input.ruleId, input.severity, input.evaluator, now, now, now);
+    }
+    async updateEvalRun(input) {
+        const now = new Date().toISOString();
+        await this.db.run(`UPDATE rule_eval_runs
+             SET status = ?, finding_count = ?, fix_count = ?, duration_ms = ?,
+                 error = ?, findings_json = ?, fixes_json = ?, completed_at = ?, updated_at = ?
+             WHERE run_id = ? AND rule_id = ?`, input.status, input.findingCount, input.fixCount, input.durationMs, input.error ?? null, input.findingsJson ?? null, input.fixesJson ?? null, now, now, input.runId, input.ruleId);
+    }
+}

package/dist/persistence/index.d.ts

@@ -0,0 +1,5 @@
+export type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+export { DbRulePersistenceAdapter } from './db-adapter';
+export { MemoryRulePersistenceAdapter } from './memory-adapter';
+export { RULE_ENGINE_SCHEMA_SQL } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC3G,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC"}

package/dist/persistence/index.js

@@ -0,0 +1,3 @@
+export { DbRulePersistenceAdapter } from './db-adapter.js';
+export { MemoryRulePersistenceAdapter } from './memory-adapter.js';
+export { RULE_ENGINE_SCHEMA_SQL } from './schema.js';

package/dist/persistence/memory-adapter.d.ts

@@ -0,0 +1,39 @@
+import type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+/** Runtime row shape for the memory adapter. */
+interface RuleRunRow extends RuleRunInput {
+    status: 'running' | 'done' | 'failed';
+    findingCount: number;
+    fixCount: number;
+    appliedFixCount: number;
+    durationMs: number | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RuleEvalRow extends RuleEvalRunInput {
+    status: 'running' | 'done' | 'failed' | 'skipped';
+    findingCount: number;
+    fixCount: number;
+    durationMs: number | null;
+    error: string | null;
+    findingsJson: string | null;
+    fixesJson: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * In-memory persistence adapter for unit tests.
+ * Stores rows in Maps so tests can assert on persisted state.
+ */
+export declare class MemoryRulePersistenceAdapter implements RulePersistenceAdapter {
+    constructor();
+    readonly runs: Map<string, RuleRunRow>;
+    readonly evals: Map<string, RuleEvalRow>;
+    insertRun(input: RuleRunInput): Promise<void>;
+    updateRunStatus(runId: string, status: 'done' | 'failed', findingCount: number, fixCount: number, appliedFixCount: number, durationMs: number): Promise<void>;
+    insertEvalRun(input: RuleEvalRunInput): Promise<void>;
+    updateEvalRun(input: RuleEvalRunUpdate): Promise<void>;
+}
+export {};
+//# sourceMappingURL=memory-adapter.d.ts.map

package/dist/persistence/memory-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-adapter.d.ts","sourceRoot":"","sources":["../../src/persistence/memory-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE3G,gDAAgD;AAChD,UAAU,UAAW,SAAQ,YAAY;IACrC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,WAAY,SAAQ,gBAAgB;IAC1C,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,4BAA6B,YAAW,sBAAsB;;IAKvE,QAAQ,CAAC,IAAI,0BAAiC;IAC9C,QAAQ,CAAC,KAAK,2BAAkC;IAE1C,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C,eAAe,CACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,QAAQ,EACzB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAYV,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrD,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAc/D"}

package/dist/persistence/memory-adapter.js

@@ -0,0 +1,69 @@
+/**
+ * In-memory persistence adapter for unit tests.
+ * Stores rows in Maps so tests can assert on persisted state.
+ */
+export class MemoryRulePersistenceAdapter {
+    constructor() {
+        // Explicit constructor for V8 function coverage — class implements an interface, no super().
+    }
+    runs = new Map();
+    evals = new Map();
+    async insertRun(input) {
+        const now = new Date().toISOString();
+        this.runs.set(input.id, {
+            ...input,
+            status: 'running',
+            findingCount: 0,
+            fixCount: 0,
+            appliedFixCount: 0,
+            durationMs: null,
+            completedAt: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async updateRunStatus(runId, status, findingCount, fixCount, appliedFixCount, durationMs) {
+        const row = this.runs.get(runId);
+        if (!row)
+            throw new Error(`Run not found: ${runId}`);
+        row.status = status;
+        row.findingCount = findingCount;
+        row.fixCount = fixCount;
+        row.appliedFixCount = appliedFixCount;
+        row.durationMs = durationMs;
+        row.completedAt = new Date().toISOString();
+        row.updatedAt = new Date().toISOString();
+    }
+    async insertEvalRun(input) {
+        const now = new Date().toISOString();
+        const key = `${input.runId}:${input.ruleId}`;
+        this.evals.set(key, {
+            ...input,
+            status: 'running',
+            findingCount: 0,
+            fixCount: 0,
+            durationMs: null,
+            error: null,
+            findingsJson: null,
+            fixesJson: null,
+            completedAt: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async updateEvalRun(input) {
+        const key = `${input.runId}:${input.ruleId}`;
+        const row = this.evals.get(key);
+        if (!row)
+            throw new Error(`Eval run not found: ${key}`);
+        row.status = input.status;
+        row.findingCount = input.findingCount;
+        row.fixCount = input.fixCount;
+        row.durationMs = input.durationMs;
+        row.error = input.error ?? null;
+        row.findingsJson = input.findingsJson ?? null;
+        row.fixesJson = input.fixesJson ?? null;
+        row.completedAt = new Date().toISOString();
+        row.updatedAt = new Date().toISOString();
+    }
+}

package/dist/persistence/schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Rule-engine persistence schema.
+ *
+ * Mirrors the workflow-engine persistence pattern: the engine owns the DDL and
+ * direct writes; consumers query the resulting tables through their own DAOs.
+ * `rule_runs` is the list/query unit; `rule_eval_runs` is the per-rule detail
+ * unit. Timestamps are TEXT (ISO 8601) for portability across SQLite drivers
+ * including D1.
+ */
+export declare const RULE_ENGINE_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS rule_runs (\n    id TEXT PRIMARY KEY,\n    preset TEXT,\n    source_kind TEXT NOT NULL,\n    source_value TEXT,\n    status TEXT NOT NULL DEFAULT 'running',\n    rule_count INTEGER NOT NULL DEFAULT 0,\n    finding_count INTEGER NOT NULL DEFAULT 0,\n    fix_count INTEGER NOT NULL DEFAULT 0,\n    applied_fix_count INTEGER NOT NULL DEFAULT 0,\n    fail_on TEXT,\n    stop_on_first TEXT,\n    fix_mode TEXT NOT NULL DEFAULT 'none',\n    dry_run INTEGER NOT NULL DEFAULT 0,\n    started_at TEXT NOT NULL,\n    completed_at TEXT,\n    duration_ms INTEGER,\n    metadata_json TEXT NOT NULL DEFAULT '{}',\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS rule_eval_runs (\n    id TEXT PRIMARY KEY,\n    run_id TEXT NOT NULL REFERENCES rule_runs(id),\n    rule_id TEXT NOT NULL,\n    severity TEXT NOT NULL,\n    evaluator TEXT NOT NULL,\n    status TEXT NOT NULL DEFAULT 'running',\n    finding_count INTEGER NOT NULL DEFAULT 0,\n    fix_count INTEGER NOT NULL DEFAULT 0,\n    duration_ms INTEGER,\n    error TEXT,\n    findings_json TEXT,\n    fixes_json TEXT,\n    started_at TEXT NOT NULL,\n    completed_at TEXT,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_rule_eval_runs_run_id ON rule_eval_runs (run_id);\n";
+//# sourceMappingURL=schema.d.ts.map

package/dist/persistence/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/persistence/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,sBAAsB,4zCA2ClC,CAAC"}

package/dist/persistence/schema.js

@@ -0,0 +1,53 @@
+/**
+ * Rule-engine persistence schema.
+ *
+ * Mirrors the workflow-engine persistence pattern: the engine owns the DDL and
+ * direct writes; consumers query the resulting tables through their own DAOs.
+ * `rule_runs` is the list/query unit; `rule_eval_runs` is the per-rule detail
+ * unit. Timestamps are TEXT (ISO 8601) for portability across SQLite drivers
+ * including D1.
+ */
+export const RULE_ENGINE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS rule_runs (
+    id TEXT PRIMARY KEY,
+    preset TEXT,
+    source_kind TEXT NOT NULL,
+    source_value TEXT,
+    status TEXT NOT NULL DEFAULT 'running',
+    rule_count INTEGER NOT NULL DEFAULT 0,
+    finding_count INTEGER NOT NULL DEFAULT 0,
+    fix_count INTEGER NOT NULL DEFAULT 0,
+    applied_fix_count INTEGER NOT NULL DEFAULT 0,
+    fail_on TEXT,
+    stop_on_first TEXT,
+    fix_mode TEXT NOT NULL DEFAULT 'none',
+    dry_run INTEGER NOT NULL DEFAULT 0,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    duration_ms INTEGER,
+    metadata_json TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS rule_eval_runs (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES rule_runs(id),
+    rule_id TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    evaluator TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'running',
+    finding_count INTEGER NOT NULL DEFAULT 0,
+    fix_count INTEGER NOT NULL DEFAULT 0,
+    duration_ms INTEGER,
+    error TEXT,
+    findings_json TEXT,
+    fixes_json TEXT,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_rule_eval_runs_run_id ON rule_eval_runs (run_id);
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.3.14",
+    "version": "0.3.16",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -49,9 +49,10 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-rule-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.3.14",
-        "@gobing-ai/ts-infra": "^0.3.14",
-        "@gobing-ai/ts-runtime": "^0.3.14",
+        "@gobing-ai/ts-ai-runner": "^0.3.16",
+        "@gobing-ai/ts-infra": "^0.3.16",
+        "@gobing-ai/ts-runtime": "^0.3.16",
+        "@gobing-ai/ts-db": "^0.3.16",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/src/engine.ts

@@ -11,6 +11,7 @@ import {
 } from './fixers/fixers';
 import { registerBuiltins } from './host/builtins';
 import { RuleEngineHost } from './host/rule-engine-host';
+import type { RulePersistenceAdapter } from './persistence/adapter';
 import type { ConstraintFinding, ConstraintRule, Fix, FixMode, RuleEngineResult, RuleEvaluator } from './types';
 import { createFinding, SEVERITY_RANK } from './types';
 
@@ -24,6 +25,12 @@ export interface RuleEngineOptions {
     events?: EventBus<RuleEngineEvents>;
     /** Optional logger; defaults to the shared `rule-engine` category logger. */
     logger?: Logger;
+    /** Optional persistence adapter for durable run/eval history. */
+    persistence?: RulePersistenceAdapter;
+    /** Caller-provided run ID; engine generates one if absent. */
+    runId?: string;
+    /** Caller metadata for the run row (preset, failOn, source info, etc.). */
+    runMeta?: Record<string, unknown>;
 }
 
 /** Orchestrates enabled constraint rules through a typed evaluator host. */
@@ -33,6 +40,9 @@ export class RuleEngine {
 
     private readonly events: EventBus<RuleEngineEvents> | undefined;
     private readonly logger: Logger;
+    private readonly persistence: RulePersistenceAdapter | undefined;
+    private readonly runId: string;
+    private readonly runMeta: Record<string, unknown> | undefined;
 
     constructor(options: RuleEngineOptions = {}) {
         this.host = options.host ?? new RuleEngineHost();
@@ -40,6 +50,9 @@ export class RuleEngine {
         registerBuiltinFixers(this.host, options.processExecutor);
         this.events = options.events;
         this.logger = options.logger ?? getLogger('rule-engine');
+        this.persistence = options.persistence;
+        this.runId = options.runId ?? crypto.randomUUID();
+        this.runMeta = options.runMeta;
     }
 
     /** Register or replace an evaluator. */
@@ -70,6 +83,10 @@ export class RuleEngine {
      * provider by evaluator type and calls `createFixes`. The effective fix mode
      * is the minimum of the rule's configured mode and `maxFixMode`.
      *
+     * When `options.persistence` is set, this method writes a run row before
+     * evaluation and per-rule eval rows during the loop. A `done`/`failed`
+     * status is written after the loop completes.
+     *
      * @param rules - Normalized rule definitions to evaluate.
      * @param workdir - Working directory to scan.
      * @param maxFixMode - Highest fix authority requested by the caller.
@@ -87,6 +104,21 @@ export class RuleEngine {
         const enabledRules = rules.filter((r) => r.enabled !== false);
         const runStartMs = Date.now();
 
+        // Insert the run row before any evaluation.
+        const runMeta = this.runMeta ?? {};
+        await this.persistence?.insertRun({
+            id: this.runId,
+            sourceKind: (runMeta.sourceKind as 'preset' | 'file') ?? 'preset',
+            sourceValue: runMeta.sourceValue as string | undefined,
+            preset: runMeta.preset as string | undefined,
+            ruleCount: enabledRules.length,
+            failOn: runMeta.failOn as string | undefined,
+            stopOnFirst: runMeta.stopOnFirst as string | undefined,
+            fixMode: maxFixMode,
+            dryRun: (runMeta.dryRun as boolean) ?? false,
+            metadataJson: runMeta.metadataJson as string | undefined,
+        });
+
         return await traceAsync(
             'rule.run',
             async () => {
@@ -103,6 +135,15 @@ export class RuleEngine {
                     if (rule.enabled === false) continue;
                     index++;
 
+                    // Persist eval start.
+                    await this.persistence?.insertEvalRun({
+                        id: `${this.runId}:${rule.id}`,
+                        runId: this.runId,
+                        ruleId: rule.id,
+                        severity: rule.severity,
+                        evaluator: rule.evaluator.type,
+                    });
+
                     const evalStartMs = Date.now();
                     this.logger.debug('eval start', { ruleId: rule.id, index, total: enabledRules.length });
                     addSpanEvent('rule.eval.start', { ruleId: rule.id, index, total: enabledRules.length });
@@ -110,6 +151,7 @@ export class RuleEngine {
 
                     let ruleFindings: ConstraintFinding[] = [];
                     let ruleEvalFixes: Fix[] = [];
+                    let evalError: string | undefined;
                     try {
                         const result = await this.host.evaluators
                             .get(rule.evaluator.type)
@@ -117,15 +159,15 @@ export class RuleEngine {
                         ruleFindings = result.findings;
                         ruleEvalFixes = result.fixes;
                     } catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
+                        evalError = error instanceof Error ? error.message : String(error);
                         ruleFindings = [
-                            createFinding(rule, message, null, {
+                            createFinding(rule, evalError, null, {
                                 code: `evaluator:${rule.evaluator.type}`,
                                 kind: 'error',
                             }),
                         ];
-                        addSpanEvent('rule.eval.error', { ruleId: rule.id, error: message });
-                        void this.events?.emit('rule.eval.error', { ruleId: rule.id, error: message });
+                        addSpanEvent('rule.eval.error', { ruleId: rule.id, error: evalError });
+                        void this.events?.emit('rule.eval.error', { ruleId: rule.id, error: evalError });
                     }
 
                     const durationMs = Date.now() - evalStartMs;
@@ -140,6 +182,17 @@ export class RuleEngine {
                         durationMs,
                     });
 
+                    // Persist eval completion.
+                    await this.persistence?.updateEvalRun({
+                        runId: this.runId,
+                        ruleId: rule.id,
+                        status: evalError ? 'failed' : 'done',
+                        findingCount: ruleFindings.length,
+                        fixCount: ruleEvalFixes.length,
+                        durationMs,
+                        ...(evalError ? { error: evalError } : {}),
+                    });
+
                     findings.push(...ruleFindings);
                     fixes.push(...ruleEvalFixes);
 
@@ -193,6 +246,16 @@ export class RuleEngine {
                     stoppedEarly: stoppedEarlyLocal,
                 });
 
+                // Finalize the run row.
+                await this.persistence?.updateRunStatus(
+                    this.runId,
+                    'done',
+                    findings.length,
+                    fixes.length,
+                    0, // appliedFixCount — set by the caller after applying fixes
+                    runDurationMs,
+                );
+
                 return { findings, fixes };
             },
             { attributes: { 'rule.count': enabledRules.length } },

package/src/index.ts

@@ -15,5 +15,6 @@ export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/bundled-rules';
 export * from './host/rule-engine-host';
+export * from './persistence';
 export * from './resolvers/test-path-resolver';
 export * from './types';

package/src/persistence/adapter.ts

@@ -0,0 +1,66 @@
+import type { FixMode } from '../types';
+
+/** Input for inserting a rule run row (engine caller provides run metadata). */
+export interface RuleRunInput {
+    id: string;
+    preset?: string;
+    sourceKind: 'preset' | 'file';
+    sourceValue?: string;
+    ruleCount: number;
+    failOn?: string;
+    stopOnFirst?: string;
+    fixMode: FixMode;
+    dryRun: boolean;
+    metadataJson?: string;
+}
+
+/** Input for inserting a per-rule eval row. */
+export interface RuleEvalRunInput {
+    id: string;
+    runId: string;
+    ruleId: string;
+    severity: string;
+    evaluator: string;
+}
+
+/** Input for updating a per-rule eval row after evaluation completes. */
+export interface RuleEvalRunUpdate {
+    runId: string;
+    ruleId: string;
+    status: 'done' | 'failed' | 'skipped';
+    findingCount: number;
+    fixCount: number;
+    durationMs: number;
+    /** Evaluator error message, if status is 'failed'. */
+    error?: string;
+    /** Bounded JSON for findings. */
+    findingsJson?: string;
+    /** Bounded JSON for fixes. */
+    fixesJson?: string;
+}
+
+/**
+ * Persistence adapter contract for the rule engine.
+ * Implementations write directly to a durable store; the engine does NOT
+ * use EventBus subscribers for durability.
+ */
+export interface RulePersistenceAdapter {
+    /** Insert a run row as 'running'. Must be idempotent. */
+    insertRun(input: RuleRunInput): Promise<void>;
+
+    /** Finalize a run row after evaluation completes. */
+    updateRunStatus(
+        runId: string,
+        status: 'done' | 'failed',
+        findingCount: number,
+        fixCount: number,
+        appliedFixCount: number,
+        durationMs: number,
+    ): Promise<void>;
+
+    /** Insert a per-rule eval row as 'running'. Must be idempotent. */
+    insertEvalRun(input: RuleEvalRunInput): Promise<void>;
+
+    /** Finalize a per-rule eval row after evaluation completes. */
+    updateEvalRun(input: RuleEvalRunUpdate): Promise<void>;
+}

package/src/persistence/db-adapter.ts

@@ -0,0 +1,93 @@
+import type { DbAdapter } from '@gobing-ai/ts-db';
+
+import type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+
+/** Persist engine run/eval rows to SQLite via a ts-db DbAdapter. */
+export class DbRulePersistenceAdapter implements RulePersistenceAdapter {
+    constructor(private readonly db: DbAdapter) {}
+
+    async insertRun(input: RuleRunInput): Promise<void> {
+        const now = new Date().toISOString();
+        await this.db.run(
+            `INSERT INTO rule_runs (id, preset, source_kind, source_value, status, rule_count,
+             fail_on, stop_on_first, fix_mode, dry_run, metadata_json, started_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            input.id,
+            input.preset ?? null,
+            input.sourceKind,
+            input.sourceValue ?? null,
+            input.ruleCount,
+            input.failOn ?? null,
+            input.stopOnFirst ?? null,
+            input.fixMode,
+            input.dryRun ? 1 : 0,
+            input.metadataJson ?? '{}',
+            now,
+            now,
+            now,
+        );
+    }
+
+    async updateRunStatus(
+        runId: string,
+        status: 'done' | 'failed',
+        findingCount: number,
+        fixCount: number,
+        appliedFixCount: number,
+        durationMs: number,
+    ): Promise<void> {
+        const now = new Date().toISOString();
+        await this.db.run(
+            `UPDATE rule_runs
+             SET status = ?, finding_count = ?, fix_count = ?, applied_fix_count = ?,
+                 duration_ms = ?, completed_at = ?, updated_at = ?
+             WHERE id = ?`,
+            status,
+            findingCount,
+            fixCount,
+            appliedFixCount,
+            durationMs,
+            now,
+            now,
+            runId,
+        );
+    }
+
+    async insertEvalRun(input: RuleEvalRunInput): Promise<void> {
+        const now = new Date().toISOString();
+        await this.db.run(
+            `INSERT INTO rule_eval_runs (id, run_id, rule_id, severity, evaluator, status,
+             started_at, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, 'running', ?, ?, ?)`,
+            input.id,
+            input.runId,
+            input.ruleId,
+            input.severity,
+            input.evaluator,
+            now,
+            now,
+            now,
+        );
+    }
+
+    async updateEvalRun(input: RuleEvalRunUpdate): Promise<void> {
+        const now = new Date().toISOString();
+        await this.db.run(
+            `UPDATE rule_eval_runs
+             SET status = ?, finding_count = ?, fix_count = ?, duration_ms = ?,
+                 error = ?, findings_json = ?, fixes_json = ?, completed_at = ?, updated_at = ?
+             WHERE run_id = ? AND rule_id = ?`,
+            input.status,
+            input.findingCount,
+            input.fixCount,
+            input.durationMs,
+            input.error ?? null,
+            input.findingsJson ?? null,
+            input.fixesJson ?? null,
+            now,
+            now,
+            input.runId,
+            input.ruleId,
+        );
+    }
+}

package/src/persistence/index.ts

@@ -0,0 +1,4 @@
+export type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+export { DbRulePersistenceAdapter } from './db-adapter';
+export { MemoryRulePersistenceAdapter } from './memory-adapter';
+export { RULE_ENGINE_SCHEMA_SQL } from './schema';

package/src/persistence/memory-adapter.ts

@@ -0,0 +1,106 @@
+import type { RuleEvalRunInput, RuleEvalRunUpdate, RulePersistenceAdapter, RuleRunInput } from './adapter';
+
+/** Runtime row shape for the memory adapter. */
+interface RuleRunRow extends RuleRunInput {
+    status: 'running' | 'done' | 'failed';
+    findingCount: number;
+    fixCount: number;
+    appliedFixCount: number;
+    durationMs: number | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface RuleEvalRow extends RuleEvalRunInput {
+    status: 'running' | 'done' | 'failed' | 'skipped';
+    findingCount: number;
+    fixCount: number;
+    durationMs: number | null;
+    error: string | null;
+    findingsJson: string | null;
+    fixesJson: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * In-memory persistence adapter for unit tests.
+ * Stores rows in Maps so tests can assert on persisted state.
+ */
+export class MemoryRulePersistenceAdapter implements RulePersistenceAdapter {
+    constructor() {
+        // Explicit constructor for V8 function coverage — class implements an interface, no super().
+    }
+
+    readonly runs = new Map<string, RuleRunRow>();
+    readonly evals = new Map<string, RuleEvalRow>();
+
+    async insertRun(input: RuleRunInput): Promise<void> {
+        const now = new Date().toISOString();
+        this.runs.set(input.id, {
+            ...input,
+            status: 'running',
+            findingCount: 0,
+            fixCount: 0,
+            appliedFixCount: 0,
+            durationMs: null,
+            completedAt: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+
+    async updateRunStatus(
+        runId: string,
+        status: 'done' | 'failed',
+        findingCount: number,
+        fixCount: number,
+        appliedFixCount: number,
+        durationMs: number,
+    ): Promise<void> {
+        const row = this.runs.get(runId);
+        if (!row) throw new Error(`Run not found: ${runId}`);
+        row.status = status;
+        row.findingCount = findingCount;
+        row.fixCount = fixCount;
+        row.appliedFixCount = appliedFixCount;
+        row.durationMs = durationMs;
+        row.completedAt = new Date().toISOString();
+        row.updatedAt = new Date().toISOString();
+    }
+
+    async insertEvalRun(input: RuleEvalRunInput): Promise<void> {
+        const now = new Date().toISOString();
+        const key = `${input.runId}:${input.ruleId}`;
+        this.evals.set(key, {
+            ...input,
+            status: 'running',
+            findingCount: 0,
+            fixCount: 0,
+            durationMs: null,
+            error: null,
+            findingsJson: null,
+            fixesJson: null,
+            completedAt: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+
+    async updateEvalRun(input: RuleEvalRunUpdate): Promise<void> {
+        const key = `${input.runId}:${input.ruleId}`;
+        const row = this.evals.get(key);
+        if (!row) throw new Error(`Eval run not found: ${key}`);
+        row.status = input.status;
+        row.findingCount = input.findingCount;
+        row.fixCount = input.fixCount;
+        row.durationMs = input.durationMs;
+        row.error = input.error ?? null;
+        row.findingsJson = input.findingsJson ?? null;
+        row.fixesJson = input.fixesJson ?? null;
+        row.completedAt = new Date().toISOString();
+        row.updatedAt = new Date().toISOString();
+    }
+}

package/src/persistence/schema.ts

@@ -0,0 +1,54 @@
+/**
+ * Rule-engine persistence schema.
+ *
+ * Mirrors the workflow-engine persistence pattern: the engine owns the DDL and
+ * direct writes; consumers query the resulting tables through their own DAOs.
+ * `rule_runs` is the list/query unit; `rule_eval_runs` is the per-rule detail
+ * unit. Timestamps are TEXT (ISO 8601) for portability across SQLite drivers
+ * including D1.
+ */
+
+export const RULE_ENGINE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS rule_runs (
+    id TEXT PRIMARY KEY,
+    preset TEXT,
+    source_kind TEXT NOT NULL,
+    source_value TEXT,
+    status TEXT NOT NULL DEFAULT 'running',
+    rule_count INTEGER NOT NULL DEFAULT 0,
+    finding_count INTEGER NOT NULL DEFAULT 0,
+    fix_count INTEGER NOT NULL DEFAULT 0,
+    applied_fix_count INTEGER NOT NULL DEFAULT 0,
+    fail_on TEXT,
+    stop_on_first TEXT,
+    fix_mode TEXT NOT NULL DEFAULT 'none',
+    dry_run INTEGER NOT NULL DEFAULT 0,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    duration_ms INTEGER,
+    metadata_json TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS rule_eval_runs (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES rule_runs(id),
+    rule_id TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    evaluator TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'running',
+    finding_count INTEGER NOT NULL DEFAULT 0,
+    fix_count INTEGER NOT NULL DEFAULT 0,
+    duration_ms INTEGER,
+    error TEXT,
+    findings_json TEXT,
+    fixes_json TEXT,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_rule_eval_runs_run_id ON rule_eval_runs (run_id);
+`;