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

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.17",
     "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.17",
+        "@gobing-ai/ts-infra": "^0.3.17",
+        "@gobing-ai/ts-runtime": "^0.3.17",
+        "@gobing-ai/ts-db": "^0.3.17",
         "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/evaluators/file-utils.ts

@@ -124,12 +124,28 @@ export function relativeParent(path: string): string {
     return parent === '.' ? '' : parent;
 }
 
-/** Return true when a path matches any supplied fragment or suffix. */
+/**
+ * Return true when a path matches any supplied pattern.
+ *
+ * Each pattern is matched in two passes, most-specific first:
+ *  1. If it contains a glob metachar (`*`), try anchored {@link matchesGlob} —
+ *     so `packages/**\/*.ts` resolves segment-by-segment instead of collapsing
+ *     to a bare fragment (the latter silently matched nothing, leaving every
+ *     glob-scoped loose-mode rule scanning zero files).
+ *  2. Otherwise (or if the glob did not match), fall back to the legacy
+ *     fragment/suffix substring test, where stars are stripped — preserving
+ *     bare fragments like `.ts`, `src/`, `/tests/` that loose-mode evaluators
+ *     have always accepted, and keeping unanchored patterns like `*.ts`
+ *     (→ suffix `.ts`) matching nested paths.
+ */
 export function matchesAny(path: string, patterns: string[] | undefined): boolean {
     if (patterns === undefined || patterns.length === 0) return true;
+    const normalizedPath = path.replaceAll('\\', '/');
     return patterns.some((pattern) => {
-        const clean = pattern.replaceAll('\\', '/').replaceAll('**/', '').replaceAll('*', '');
-        return clean.length === 0 || path.includes(clean) || path.endsWith(clean);
+        const normalized = pattern.replaceAll('\\', '/');
+        if (normalized.includes('*') && matchesGlob(normalizedPath, normalized)) return true;
+        const clean = normalized.replaceAll('**/', '').replaceAll('*', '');
+        return clean.length === 0 || normalizedPath.includes(clean) || normalizedPath.endsWith(clean);
     });
 }
 

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);
+`;