@sensigo/realm 0.1.0

package/dist/pipeline/processing-pipeline.d.ts

@@ -0,0 +1,24 @@
+import type { ProcessorInput, ProcessorOutput } from '../extensions/processor.js';
+import type { ExtensionRegistry } from '../extensions/registry.js';
+export interface PipelineResult {
+    output: ProcessorOutput;
+    /** Each entry records which processor ran and its output text length. */
+    trace: Array<{
+        processorId: string;
+        outputLength: number;
+    }>;
+}
+/**
+ * Runs content through a sequence of named processors from the registry.
+ *
+ * If 'compute_hash' is not the last entry in processorNames, it is appended
+ * automatically. This guarantees the hash reflects the final content.
+ *
+ * @param content  Initial ProcessorInput.
+ * @param processorNames  Ordered list of processor ids to apply.
+ * @param registry  Registry to look up processors by name.
+ * @param configs  Optional per-processor config map keyed by processor id.
+ * @throws WorkflowError(ENGINE_PROCESSOR_FAILED) if a processor is not found or throws.
+ */
+export declare function runPipeline(content: ProcessorInput, processorNames: string[], registry: ExtensionRegistry, configs?: Record<string, Record<string, unknown>>): Promise<PipelineResult>;
+//# sourceMappingURL=processing-pipeline.d.ts.map

package/dist/pipeline/processing-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-pipeline.d.ts","sourceRoot":"","sources":["../../src/pipeline/processing-pipeline.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,yEAAyE;IACzE,KAAK,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EAAE,EACxB,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC,CAyCzB"}

package/dist/pipeline/processing-pipeline.js

@@ -0,0 +1,53 @@
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * Runs content through a sequence of named processors from the registry.
+ *
+ * If 'compute_hash' is not the last entry in processorNames, it is appended
+ * automatically. This guarantees the hash reflects the final content.
+ *
+ * @param content  Initial ProcessorInput.
+ * @param processorNames  Ordered list of processor ids to apply.
+ * @param registry  Registry to look up processors by name.
+ * @param configs  Optional per-processor config map keyed by processor id.
+ * @throws WorkflowError(ENGINE_PROCESSOR_FAILED) if a processor is not found or throws.
+ */
+export async function runPipeline(content, processorNames, registry, configs) {
+    const names = [...processorNames];
+    if (names[names.length - 1] !== 'compute_hash') {
+        names.push('compute_hash');
+    }
+    const trace = [];
+    let current = content;
+    for (const name of names) {
+        const processor = registry.getProcessor(name);
+        if (processor === undefined) {
+            throw new WorkflowError(`Processor not found: ${name}`, {
+                code: 'ENGINE_PROCESSOR_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        const config = configs?.[name] ?? {};
+        let result;
+        try {
+            result = await processor.process(current, config);
+        }
+        catch (err) {
+            if (err instanceof WorkflowError)
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new WorkflowError(`Processor '${name}' failed: ${message}`, {
+                code: 'ENGINE_PROCESSOR_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        }
+        trace.push({ processorId: name, outputLength: result.text.length });
+        current = result;
+    }
+    // current is guaranteed to be a ProcessorOutput since names is non-empty after appending compute_hash
+    return { output: current, trace };
+}
+//# sourceMappingURL=processing-pipeline.js.map

package/dist/pipeline/processing-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-pipeline.js","sourceRoot":"","sources":["../../src/pipeline/processing-pipeline.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAQ3D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAuB,EACvB,cAAwB,EACxB,QAA2B,EAC3B,OAAiD;IAEjD,MAAM,KAAK,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,cAAc,EAAE,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,KAAK,GAAyD,EAAE,CAAC;IACvE,IAAI,OAAO,GAAmB,OAAO,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAA0B,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACrE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,aAAa,CAAC,wBAAwB,IAAI,EAAE,EAAE;gBACtD,IAAI,EAAE,yBAAyB;gBAC/B,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,MAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,aAAa;gBAAE,MAAM,GAAG,CAAC;YAC5C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,IAAI,aAAa,CAAC,cAAc,IAAI,aAAa,OAAO,EAAE,EAAE;gBAChE,IAAI,EAAE,yBAAyB;gBAC/B,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpE,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IAED,sGAAsG;IACtG,OAAO,EAAE,MAAM,EAAE,OAA0B,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC"}

package/dist/processors/compute-hash.d.ts

@@ -0,0 +1,4 @@
+import type { Processor } from '../extensions/processor.js';
+/** Computes SHA-256 of the input text and stores it as metadata.hash in 'sha256:{hex}' format. */
+export declare const computeHash: Processor;
+//# sourceMappingURL=compute-hash.d.ts.map

package/dist/processors/compute-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-hash.d.ts","sourceRoot":"","sources":["../../src/processors/compute-hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAmC,MAAM,4BAA4B,CAAC;AAE7F,kGAAkG;AAClG,eAAO,MAAM,WAAW,EAAE,SAYzB,CAAC"}

package/dist/processors/compute-hash.js

@@ -0,0 +1,14 @@
+// compute-hash processor — appends a SHA-256 hash of the text to metadata.
+import { createHash } from 'node:crypto';
+/** Computes SHA-256 of the input text and stores it as metadata.hash in 'sha256:{hex}' format. */
+export const computeHash = {
+    id: 'compute_hash',
+    async process(content, _config) {
+        const hash = `sha256:${createHash('sha256').update(content.text).digest('hex')}`;
+        return {
+            text: content.text,
+            metadata: { ...content.metadata, hash },
+        };
+    },
+};
+//# sourceMappingURL=compute-hash.js.map

package/dist/processors/compute-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-hash.js","sourceRoot":"","sources":["../../src/processors/compute-hash.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,kGAAkG;AAClG,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC,EAAE,EAAE,cAAc;IAClB,KAAK,CAAC,OAAO,CACX,OAAuB,EACvB,OAAgC;QAEhC,MAAM,IAAI,GAAG,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACjF,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,QAAQ,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE;SACxC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/processors/normalize-text.d.ts

@@ -0,0 +1,8 @@
+import type { Processor } from '../extensions/processor.js';
+export interface NormalizeTextConfig {
+    smart_quotes?: boolean;
+    dashes?: boolean;
+}
+/** Replaces Unicode smart quotes and dashes with plain ASCII equivalents. */
+export declare const normalizeText: Processor;
+//# sourceMappingURL=normalize-text.d.ts.map

package/dist/processors/normalize-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-text.d.ts","sourceRoot":"","sources":["../../src/processors/normalize-text.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAmC,MAAM,4BAA4B,CAAC;AAE7F,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,SA0C3B,CAAC"}

package/dist/processors/normalize-text.js

@@ -0,0 +1,47 @@
+/** Replaces Unicode smart quotes and dashes with plain ASCII equivalents. */
+export const normalizeText = {
+    id: 'normalize_text',
+    async process(content, config) {
+        const cfg = config;
+        const smartQuotes = cfg.smart_quotes !== false;
+        const dashes = cfg.dashes !== false;
+        let text = content.text;
+        let normalizedQuotes = 0;
+        let normalizedDashes = 0;
+        if (smartQuotes) {
+            for (const ch of ['“', '”', '‘', '’']) {
+                const replacement = ch === '“' || ch === '”' ? '"' : "'";
+                const regex = new RegExp(ch, 'g');
+                const before = text;
+                text = text.replace(regex, replacement);
+                normalizedQuotes += countOccurrences(before, ch);
+            }
+        }
+        if (dashes) {
+            const emBefore = text;
+            text = text.replace(/—/g, '--');
+            normalizedDashes += countOccurrences(emBefore, '—');
+            const enBefore = text;
+            text = text.replace(/–/g, '-');
+            normalizedDashes += countOccurrences(enBefore, '–');
+        }
+        return {
+            text,
+            metadata: {
+                ...content.metadata,
+                normalized_quotes: normalizedQuotes,
+                normalized_dashes: normalizedDashes,
+            },
+        };
+    },
+};
+function countOccurrences(str, ch) {
+    let count = 0;
+    let idx = 0;
+    while ((idx = str.indexOf(ch, idx)) !== -1) {
+        count++;
+        idx += ch.length;
+    }
+    return count;
+}
+//# sourceMappingURL=normalize-text.js.map

package/dist/processors/normalize-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-text.js","sourceRoot":"","sources":["../../src/processors/normalize-text.ts"],"names":[],"mappings":"AAQA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,EAAE,EAAE,gBAAgB;IACpB,KAAK,CAAC,OAAO,CACX,OAAuB,EACvB,MAA+B;QAE/B,MAAM,GAAG,GAAG,MAA6B,CAAC;QAC1C,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,KAAK,KAAK,CAAC;QAC/C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC;QAEpC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACxB,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,IAAI,gBAAgB,GAAG,CAAC,CAAC;QAEzB,IAAI,WAAW,EAAE,CAAC;YAChB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtC,MAAM,WAAW,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBACzD,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBAClC,MAAM,MAAM,GAAG,IAAI,CAAC;gBACpB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;gBACxC,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QAED,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,IAAI,CAAC;YACtB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAChC,gBAAgB,IAAI,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACpD,MAAM,QAAQ,GAAG,IAAI,CAAC;YACtB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC/B,gBAAgB,IAAI,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;QAED,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE;gBACR,GAAG,OAAO,CAAC,QAAQ;gBACnB,iBAAiB,EAAE,gBAAgB;gBACnC,iBAAiB,EAAE,gBAAgB;aACpC;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,SAAS,gBAAgB,CAAC,GAAW,EAAE,EAAU;IAC/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3C,KAAK,EAAE,CAAC;QACR,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/store/json-file-store.d.ts

@@ -0,0 +1,24 @@
+import type { RunRecord } from '../types/run-record.js';
+import type { WorkflowDefinition } from '../types/workflow-definition.js';
+import type { RunStore, CreateRunOptions } from './store-interface.js';
+export declare class JsonFileStore implements RunStore {
+    private readonly runsDir;
+    constructor(runsDir?: string);
+    /** The directory where run JSON files are stored. */
+    get runsDirPath(): string;
+    private filePath;
+    private ensureDir;
+    create(options: CreateRunOptions): Promise<RunRecord>;
+    get(runId: string): Promise<RunRecord>;
+    update(record: RunRecord): Promise<RunRecord>;
+    claimStep(runId: string, stepName: string, definition: WorkflowDefinition): Promise<RunRecord>;
+    /**
+     * Writes a run record with its existing ID to local storage.
+     * Used for importing records fetched from a remote store.
+     * Idempotent: if the record already exists with the same version, this is a no-op.
+     * Does NOT increment version or apply the optimistic lock — this is an import, not an update.
+     */
+    save(record: RunRecord): Promise<void>;
+    list(workflowId?: string): Promise<RunRecord[]>;
+}
+//# sourceMappingURL=json-file-store.d.ts.map

package/dist/store/json-file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-store.d.ts","sourceRoot":"","sources":["../../src/store/json-file-store.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAKvE,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,MAAM;IAI5B,qDAAqD;IACrD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,OAAO,CAAC,QAAQ;YAIF,SAAS;IAIjB,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC;IAuBrD,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgCtC,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IA0C7C,SAAS,CACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,SAAS,CAAC;IAoErB;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBtC,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAiBtD"}

package/dist/store/json-file-store.js

@@ -0,0 +1,210 @@
+// Local file-backed run store. Stores each run as a JSON file in ~/.realm/runs/.
+// Uses proper-lockfile to prevent concurrent writes.
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { v4 as uuidv4 } from 'uuid';
+import lockfile from 'proper-lockfile';
+import { WorkflowError } from '../types/workflow-error.js';
+import { findEligibleSteps, deriveRunPhase } from '../engine/eligibility.js';
+const DEFAULT_RUNS_DIR = join(homedir(), '.realm', 'runs');
+export class JsonFileStore {
+    runsDir;
+    constructor(runsDir) {
+        this.runsDir = runsDir ?? DEFAULT_RUNS_DIR;
+    }
+    /** The directory where run JSON files are stored. */
+    get runsDirPath() {
+        return this.runsDir;
+    }
+    filePath(runId) {
+        return join(this.runsDir, `${runId}.json`);
+    }
+    async ensureDir() {
+        await mkdir(this.runsDir, { recursive: true });
+    }
+    async create(options) {
+        await this.ensureDir();
+        const now = new Date().toISOString();
+        const record = {
+            id: uuidv4(),
+            workflow_id: options.workflowId,
+            workflow_version: options.workflowVersion,
+            completed_steps: [],
+            in_progress_steps: [],
+            failed_steps: [],
+            skipped_steps: [],
+            run_phase: 'running',
+            version: 0,
+            params: options.params,
+            evidence: [],
+            created_at: now,
+            updated_at: now,
+            terminal_state: false,
+        };
+        await writeFile(this.filePath(record.id), JSON.stringify(record, null, 2), 'utf8');
+        return record;
+    }
+    async get(runId) {
+        const path = this.filePath(runId);
+        if (!existsSync(path)) {
+            throw new WorkflowError(`Run not found: ${runId}`, {
+                code: 'STATE_RUN_NOT_FOUND',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { runId },
+            });
+        }
+        const raw = await readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        // Legacy format detection: runs written before Phase 35 have `state` but no `completed_steps`.
+        if ('state' in parsed && !('completed_steps' in parsed)) {
+            throw new WorkflowError('This run was created with an older version of Realm that used a state-machine model. ' +
+                'Delete ~/.realm/runs/ and start fresh.', {
+                code: 'STATE_LEGACY_FORMAT',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { runId },
+            });
+        }
+        return parsed;
+    }
+    async update(record) {
+        await this.ensureDir();
+        const path = this.filePath(record.id);
+        if (!existsSync(path)) {
+            throw new WorkflowError(`Run not found: ${record.id}`, {
+                code: 'STATE_RUN_NOT_FOUND',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { runId: record.id },
+            });
+        }
+        const release = await lockfile.lock(path, { retries: { retries: 3, minTimeout: 50 } });
+        try {
+            const raw = await readFile(path, 'utf8');
+            const stored = JSON.parse(raw);
+            if (stored.version !== record.version) {
+                throw new WorkflowError('Version conflict — run was modified by another process', {
+                    code: 'STATE_SNAPSHOT_MISMATCH',
+                    category: 'STATE',
+                    agentAction: 'report_to_user',
+                    retryable: true,
+                    details: { runId: record.id, expected: record.version, actual: stored.version },
+                });
+            }
+            const updated = {
+                ...record,
+                run_phase: deriveRunPhase(record),
+                version: record.version + 1,
+                updated_at: new Date().toISOString(),
+            };
+            await writeFile(path, JSON.stringify(updated, null, 2), 'utf8');
+            return updated;
+        }
+        finally {
+            await release();
+        }
+    }
+    async claimStep(runId, stepName, definition) {
+        await this.ensureDir();
+        const path = this.filePath(runId);
+        if (!existsSync(path)) {
+            throw new WorkflowError(`Run not found: ${runId}`, {
+                code: 'STATE_RUN_NOT_FOUND',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { runId },
+            });
+        }
+        const release = await lockfile.lock(path, { retries: { retries: 3, minTimeout: 50 } });
+        try {
+            // Re-read the freshest version under lock.
+            const raw = await readFile(path, 'utf8');
+            const run = JSON.parse(raw);
+            // Guard: step must not already be claimed.
+            if (run.in_progress_steps.includes(stepName) ||
+                run.completed_steps.includes(stepName) ||
+                run.failed_steps.includes(stepName) ||
+                run.skipped_steps.includes(stepName)) {
+                throw new WorkflowError(`Step '${stepName}' is already claimed or completed on run '${runId}'.`, {
+                    code: 'STATE_STEP_ALREADY_CLAIMED',
+                    category: 'STATE',
+                    agentAction: 'resolve_precondition',
+                    retryable: false,
+                    details: { runId, stepName },
+                });
+            }
+            // Guard: step must still be eligible under the current run state.
+            const eligible = findEligibleSteps(definition, run);
+            if (!eligible.includes(stepName)) {
+                throw new WorkflowError(`Step '${stepName}' is not eligible for execution on run '${runId}'.`, {
+                    code: 'STATE_STEP_NOT_ELIGIBLE',
+                    category: 'STATE',
+                    agentAction: 'resolve_precondition',
+                    retryable: false,
+                    details: { runId, stepName, eligible },
+                });
+            }
+            const claimed = {
+                ...run,
+                in_progress_steps: [...run.in_progress_steps, stepName],
+                run_phase: deriveRunPhase(run),
+                version: run.version + 1,
+                updated_at: new Date().toISOString(),
+            };
+            await writeFile(path, JSON.stringify(claimed, null, 2), 'utf8');
+            return claimed;
+        }
+        finally {
+            await release();
+        }
+    }
+    /**
+     * Writes a run record with its existing ID to local storage.
+     * Used for importing records fetched from a remote store.
+     * Idempotent: if the record already exists with the same version, this is a no-op.
+     * Does NOT increment version or apply the optimistic lock — this is an import, not an update.
+     */
+    async save(record) {
+        await this.ensureDir();
+        const path = this.filePath(record.id);
+        if (existsSync(path)) {
+            const raw = await readFile(path, 'utf8');
+            const stored = JSON.parse(raw);
+            if (stored.version === record.version)
+                return;
+            throw new WorkflowError(`Run '${record.id}' exists locally with a different version (local: ${stored.version}, incoming: ${record.version}). Manual resolution required.`, {
+                code: 'STATE_RUN_DIVERGED',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: {
+                    runId: record.id,
+                    localVersion: stored.version,
+                    incomingVersion: record.version,
+                },
+            });
+        }
+        await writeFile(path, JSON.stringify(record, null, 2), 'utf8');
+    }
+    async list(workflowId) {
+        await this.ensureDir();
+        const entries = await readdir(this.runsDir);
+        const jsonFiles = entries.filter((f) => f.endsWith('.json'));
+        const records = await Promise.all(jsonFiles.map(async (file) => {
+            const raw = await readFile(join(this.runsDir, file), 'utf8');
+            return JSON.parse(raw);
+        }));
+        if (workflowId !== undefined) {
+            return records.filter((r) => r.workflow_id === workflowId);
+        }
+        return records;
+    }
+}
+//# sourceMappingURL=json-file-store.js.map

package/dist/store/json-file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-store.js","sourceRoot":"","sources":["../../src/store/json-file-store.ts"],"names":[],"mappings":"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"}

package/dist/store/store-interface.d.ts

@@ -0,0 +1,33 @@
+import type { RunRecord } from '../types/run-record.js';
+import type { WorkflowDefinition } from '../types/workflow-definition.js';
+export interface CreateRunOptions {
+    workflowId: string;
+    workflowVersion: number;
+    params: Record<string, unknown>;
+}
+export interface RunStore {
+    /** Create a new run record. Returns the created record. */
+    create(options: CreateRunOptions): Promise<RunRecord>;
+    /** Get a run record by ID. Throws WorkflowError(STATE_RUN_NOT_FOUND) if not found. */
+    get(runId: string): Promise<RunRecord>;
+    /**
+     * Update a run record. Checks that record.version matches the stored version
+     * before writing. Throws WorkflowError(STATE_SNAPSHOT_MISMATCH) on version conflict.
+     * Increments version on successful write.
+     */
+    update(record: RunRecord): Promise<RunRecord>;
+    /** List all run records, optionally filtered by workflowId. */
+    list(workflowId?: string): Promise<RunRecord[]>;
+    /**
+     * Atomically marks a step as in_progress. Under file lock:
+     * 1. Re-reads the current record (ignores caller's version).
+     * 2. Checks the step is not already in in_progress_steps, completed_steps,
+     *    failed_steps, or skipped_steps. If it is, throws STATE_STEP_ALREADY_CLAIMED.
+     * 3. Re-evaluates trigger rule and when-condition. If no longer satisfied,
+     *    throws STATE_STEP_NOT_ELIGIBLE.
+     * 4. Adds step to in_progress_steps, increments version, writes.
+     * Returns the updated record.
+     */
+    claimStep(runId: string, stepName: string, definition: WorkflowDefinition): Promise<RunRecord>;
+}
+//# sourceMappingURL=store-interface.d.ts.map

package/dist/store/store-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-interface.d.ts","sourceRoot":"","sources":["../../src/store/store-interface.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtD,sFAAsF;IACtF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEvC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE9C,+DAA+D;IAC/D,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAEhD;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAChG"}

package/dist/store/store-interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=store-interface.js.map

package/dist/store/store-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-interface.js","sourceRoot":"","sources":["../../src/store/store-interface.ts"],"names":[],"mappings":""}

package/dist/store/trace-buffer-store.d.ts

@@ -0,0 +1,55 @@
+import type { AgentTraceEntry } from '../types/run-record.js';
+export interface AppendResult {
+    buffer_count: number;
+    buffer_bytes: number;
+    limit_count: number;
+    limit_bytes: number;
+    final_limit_entries: number;
+    final_limit_bytes: number;
+}
+export interface TraceBufferStore {
+    /**
+     * Appends normalized entries to the buffer for (runId, stepId).
+     * Each entry is per-entry normalized at append time (reserved prefix drop, field caps).
+     * Batch timestamp (_internalTs) is assigned at write time.
+     * Throws BUFFER_FULL WorkflowError if the WAL limit would be exceeded.
+     */
+    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    /**
+     * Reads all buffered entries for (runId, stepId) with their batch timestamps attached.
+     * Returns empty array if no buffer exists.
+     * Entries carry _internalTs for ordering at finalization.
+     */
+    read(runId: string, stepId: string): Promise<BufferedEntry[]>;
+    /** Deletes the buffer for (runId, stepId). No-op if absent. */
+    delete(runId: string, stepId: string): Promise<void>;
+    /** Deletes all buffers for a run. Called when the run is deleted. */
+    deleteAllForRun(runId: string): Promise<void>;
+}
+/** An AgentTraceEntry extended with engine-assigned ordering timestamp (milliseconds). */
+export interface BufferedEntry extends AgentTraceEntry {
+    _internalTs: number;
+}
+export declare const BUFFER_LIMIT_COUNT = 200;
+export declare const BUFFER_LIMIT_BYTES: number;
+export declare const FINAL_LIMIT_ENTRIES = 100;
+export declare const FINAL_LIMIT_BYTES: number;
+/**
+ * Per-entry normalization run at append time (not at finalization).
+ * Mirrors the normalization in normalizeTrace for the parts that don't need seq or byte-budget context.
+ * Returns null if the entry should be dropped (reserved prefix).
+ */
+export declare function normalizeEntryForBuffer(entry: AgentTraceEntry): AgentTraceEntry | null;
+/**
+ * In-memory TraceBufferStore for use in tests and non-persistent environments.
+ * Entries are lost on process restart (no file I/O).
+ */
+export declare class InMemoryTraceBufferStore implements TraceBufferStore {
+    private buffers;
+    private key;
+    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    read(runId: string, stepId: string): Promise<BufferedEntry[]>;
+    delete(runId: string, stepId: string): Promise<void>;
+    deleteAllForRun(runId: string): Promise<void>;
+}
+//# sourceMappingURL=trace-buffer-store.d.ts.map

package/dist/store/trace-buffer-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-buffer-store.d.ts","sourceRoot":"","sources":["../../src/store/trace-buffer-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzF;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAE9D,+DAA+D;IAC/D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,qEAAqE;IACrE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAC7C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAO3C;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CA+BtF;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,OAAO,CAAsC;IAErD,OAAO,CAAC,GAAG;IAIL,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IA+CxF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAI7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpD"}