opensquid 0.5.395

package/dist/runtime/durable/checkpoint_store.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Durable-execution checkpoint store (DURABLE.1).
+ *
+ * Every durable primitive call writes one row keyed by `(run_id, step_idx)`.
+ * On resume the evaluator queries `lastCompletedStep` + `loadBindings` to
+ * restore the `as:` variable scope and skip already-completed steps. The
+ * per-primitive boundary (finer than LangGraph's per-node, looser than
+ * Temporal's per-activity-with-manual-marks) is the architectural moat:
+ * `process:` is already a sequence of atomic primitive calls, so we get
+ * resumable execution for free without asking pack authors to annotate
+ * anything.
+ *
+ * Scope of DURABLE.1: STORAGE ONLY. This module ships the table, the
+ * `append` / `lastCompletedStep` / `loadBindings` / `pruneOlderThan` API,
+ * and canonical-JSON round-trip. It does NOT wire the evaluator. DURABLE.2
+ * adds the `durable: boolean` flag to `PrimitiveDescriptor` and wraps each
+ * primitive call in the evaluator.
+ *
+ * Atomicity: every `append` is a single `INSERT OR REPLACE` — SQLite makes
+ * single-statement writes atomic, so no explicit BEGIN/COMMIT is needed.
+ * `INSERT OR REPLACE` (rather than plain INSERT) gives us the idempotent
+ * retry semantics: a primitive that errored at step 3 records
+ * `status='errored'`; the resume retries step 3 and overwrites that row
+ * with the new outcome. Replay-with-same-input writes the same row a
+ * second time without corruption.
+ *
+ * Fail-mode: any libsql error in `append` re-throws (caller decides). We
+ * do NOT swallow errors and continue — silent fail-open on checkpoint
+ * write would defeat the entire feature (a crash after the "successful"
+ * primitive but before a missing checkpoint would skip the step on
+ * resume, breaking exactly-once semantics).
+ *
+ * Imports from: @libsql/client, ./canonical_json.js.
+ * Imported by: DURABLE.2 evaluator wrap, DURABLE.4 resumer, future
+ * `opensquid checkpoints` CLI.
+ */
+import type { Client } from '@libsql/client';
+/**
+ * Args to `append`. Mirrors the `checkpoints` row 1:1 except `outputs`
+ * arrives as an unknown JS value — the store handles canonical-JSON
+ * encoding.
+ */
+export interface CheckpointWrite {
+    runId: string;
+    stepIdx: number;
+    fn: string;
+    inputsHash: string;
+    outputs: unknown;
+    /** Variable name the step's `as:` clause binds to. `undefined` if no binding. */
+    asBinding?: string;
+    startedAtMs: number;
+    completedAtMs: number;
+    status: 'completed' | 'errored';
+    /** Set when `status === 'errored'`; null otherwise. */
+    errorMessage?: string;
+}
+/**
+ * One row read back from the store. `outputs` has already been
+ * canonical-JSON-revived (base64 → Buffer; ISO date strings stay strings).
+ */
+export interface CheckpointRow {
+    runId: string;
+    stepIdx: number;
+    fn: string;
+    inputsHash: string;
+    outputs: unknown;
+    asBinding: string | undefined;
+    startedAtMs: number;
+    completedAtMs: number;
+    status: 'completed' | 'errored';
+    errorMessage: string | undefined;
+}
+/**
+ * Identity of a run captured at process entry. The Resumer (DURABLE.4)
+ * needs `(packId, skill, ruleId, eventKind, eventPayload, packVersion)` to
+ * reconstruct a `ProcessContext` on resume — the checkpoint table only
+ * stores the hashed `inputsHash`, never the raw event payload, so the
+ * manifest is the load-bearing record for restart.
+ *
+ * `packVersion` is compared at resume time to detect drift; if the pack
+ * version diverges between crash and resume the run is skipped + audited
+ * (see Resumer.resume).
+ */
+export interface RunManifest {
+    runId: string;
+    packId: string;
+    packVersion: string;
+    skill: string;
+    ruleId: string;
+    eventKind: string;
+    eventPayload: unknown;
+    startedAtMs: number;
+}
+export declare class CheckpointStore {
+    private readonly db;
+    private initialized;
+    constructor(db: Client);
+    /**
+     * Idempotent DDL — `CREATE TABLE IF NOT EXISTS` + indexes. Same posture
+     * as `RateLimiter.init` (AUTO.2) and the libsql RAG backends. Safe to
+     * call repeatedly; only the first call hits libsql.
+     */
+    init(): Promise<void>;
+    /**
+     * Atomic write of a single checkpoint row. `INSERT OR REPLACE` makes
+     * the call idempotent on `(run_id, step_idx)` — a retried step
+     * overwrites its prior errored row with the new outcome, and a
+     * replay-with-same-inputs writes the same row twice without corruption.
+     *
+     * Throws on libsql error. The caller (evaluator in DURABLE.2) is the
+     * right place to decide fail-closed vs fail-open semantics; the store
+     * never silently swallows.
+     */
+    append(write: CheckpointWrite): Promise<void>;
+    /**
+     * Highest step_idx for which the run has a `status='completed'` row.
+     * Errored rows are excluded so the resume cursor naturally re-runs
+     * errored steps (the spec's retry-not-skip rule).
+     *
+     * Returns `null` when the run has no completed steps yet — caller starts
+     * the process from `step_idx = 0`.
+     */
+    lastCompletedStep(runId: string): Promise<CheckpointRow | null>;
+    /**
+     * Replay every `status='completed'` checkpoint that owns an `as:`
+     * binding into a name→value map. The evaluator hydrates its
+     * `ctx.bindings` from this map before resuming.
+     *
+     * Errored steps and steps without `asBinding` are skipped — they
+     * contribute nothing to the rule's variable scope.
+     *
+     * Order: ascending `step_idx`. If two completed steps somehow share a
+     * binding name (a primitive author bug — the same `as:` reused in two
+     * places), the later step's value wins, matching the in-memory
+     * evaluator semantics.
+     */
+    loadBindings(runId: string): Promise<Record<string, unknown>>;
+    /**
+     * Fetch every row for a run in ascending `step_idx` order. Used by the
+     * evaluator's checkpoint wrap (DURABLE.2) to build a per-step lookup map
+     * once at process entry, then dispatch each durable step against the
+     * pre-fetched row without per-step libsql queries.
+     *
+     * Returns BOTH completed and errored rows — the evaluator decides what to
+     * do with each: completed + matching inputsHash → skip; everything else
+     * → re-execute and overwrite via `INSERT OR REPLACE`.
+     *
+     * Returns `[]` when the run has no checkpoints (fresh run).
+     */
+    fetchRun(runId: string): Promise<CheckpointRow[]>;
+    /**
+     * Delete every row whose `completed_at_ms` falls before `now - ms`.
+     * Returns the affected-row count for audit-log surfacing. Used by the
+     * future `opensquid checkpoints clean --older-than 7d` CLI verb.
+     *
+     * `nowMs` is optional and injected for tests; production callers pass
+     * `Date.now()`.
+     */
+    pruneOlderThan(ms: number, nowMs?: number): Promise<number>;
+    /**
+     * Record a run-start manifest. Called by the rule dispatcher BEFORE
+     * `evaluateProcess` so that a crash mid-process leaves the manifest
+     * behind for the Resumer (DURABLE.4) to find.
+     *
+     * `INSERT OR REPLACE` — idempotent on `runId`. A retried run with the
+     * same identity overwrites the prior manifest (timestamps refresh,
+     * event payload re-canonicalizes to the same JSON anyway). The Resumer
+     * uses the latest manifest in any case.
+     */
+    recordRunStart(manifest: RunManifest): Promise<void>;
+    /**
+     * Look up the manifest for a runId. Returns `null` when the run was
+     * never registered via `recordRunStart` — the Resumer treats those
+     * runs as orphan checkpoints and skips them with audit reason
+     * `manifest_missing`.
+     */
+    getRunManifest(runId: string): Promise<RunManifest | null>;
+    /**
+     * Record terminal outcome for a run. Called by the rule dispatcher
+     * AFTER `evaluateProcess` returns (regardless of `verdict` / `no_verdict`
+     * / `error`). The Resumer treats a row in `terminal_markers` as
+     * "this run finished — do not resume".
+     *
+     * `outcome` is stored as free-form text for audit visibility
+     * (verdict / no_verdict / error). The Resumer doesn't switch on it —
+     * presence of the row is what gates resume.
+     */
+    recordRunTerminal(runId: string, outcome: string, nowMs: number): Promise<void>;
+    /**
+     * Has the run terminated? `true` when a `terminal_markers` row exists
+     * for the runId. Used by tests + the Resumer's own scan to short-circuit
+     * cleanly without a second SELECT.
+     */
+    hasTerminalMarker(runId: string): Promise<boolean>;
+    /**
+     * Scan for runs the Resumer (DURABLE.4) should consider resuming.
+     *
+     * A run is "interrupted" when:
+     *   - It has at least one row in `checkpoints` (we ran something), AND
+     *   - It has NO row in `terminal_markers` (process didn't finish), AND
+     *   - The most-recent completed_at_ms is within `withinMs` of now
+     *     (the resume window — older runs are "stale" and skipped by the
+     *     Resumer with audit reason `stale`).
+     *
+     * Returns rows in ascending-age order (most recent first) so the
+     * Resumer drains the freshest interrupted runs before stale ones in
+     * pathological 100+-interrupted-runs cases.
+     *
+     * `withinMs <= 0` disables the window — useful for explicit
+     * `opensquid checkpoints resume <run_id>` which bypasses the default.
+     * The Resumer's own implementation passes `Number.POSITIVE_INFINITY`
+     * for that path; this method clamps to a "no window" semantic when
+     * the value is non-finite or non-positive.
+     */
+    scanInterrupted(withinMs: number, nowMs?: number): Promise<InterruptedSummary[]>;
+}
+/**
+ * One row returned by `CheckpointStore.scanInterrupted` — the resumable
+ * runs in the store. The Resumer joins this with `getRunManifest` to
+ * build the full `InterruptedRun` shape (with packId / skill / ruleId /
+ * eventPayload).
+ */
+export interface InterruptedSummary {
+    runId: string;
+    lastCompletedStep: number;
+    lastCompletedAtMs: number;
+}
+//# sourceMappingURL=checkpoint_store.d.ts.map

package/dist/runtime/durable/checkpoint_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint_store.d.ts","sourceRoot":"","sources":["../../../src/runtime/durable/checkpoint_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAI7C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAwED,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,EAAE;IAF/B,OAAO,CAAC,WAAW,CAAS;gBAEC,EAAE,EAAE,MAAM;IAEvC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBnD;;;;;;;OAOG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAgBrE;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAmBnE;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAavD;;;;;;;OAOG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAU7E;;;;;;;;;OASG;IACG,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB1D;;;;;OAKG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAahE;;;;;;;;;OASG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrF;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAmB,GACzB,OAAO,CAAC,kBAAkB,EAAE,CAAC;CA2BjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B"}

package/dist/runtime/durable/checkpoint_store.js

@@ -0,0 +1,415 @@
+/**
+ * Durable-execution checkpoint store (DURABLE.1).
+ *
+ * Every durable primitive call writes one row keyed by `(run_id, step_idx)`.
+ * On resume the evaluator queries `lastCompletedStep` + `loadBindings` to
+ * restore the `as:` variable scope and skip already-completed steps. The
+ * per-primitive boundary (finer than LangGraph's per-node, looser than
+ * Temporal's per-activity-with-manual-marks) is the architectural moat:
+ * `process:` is already a sequence of atomic primitive calls, so we get
+ * resumable execution for free without asking pack authors to annotate
+ * anything.
+ *
+ * Scope of DURABLE.1: STORAGE ONLY. This module ships the table, the
+ * `append` / `lastCompletedStep` / `loadBindings` / `pruneOlderThan` API,
+ * and canonical-JSON round-trip. It does NOT wire the evaluator. DURABLE.2
+ * adds the `durable: boolean` flag to `PrimitiveDescriptor` and wraps each
+ * primitive call in the evaluator.
+ *
+ * Atomicity: every `append` is a single `INSERT OR REPLACE` — SQLite makes
+ * single-statement writes atomic, so no explicit BEGIN/COMMIT is needed.
+ * `INSERT OR REPLACE` (rather than plain INSERT) gives us the idempotent
+ * retry semantics: a primitive that errored at step 3 records
+ * `status='errored'`; the resume retries step 3 and overwrites that row
+ * with the new outcome. Replay-with-same-input writes the same row a
+ * second time without corruption.
+ *
+ * Fail-mode: any libsql error in `append` re-throws (caller decides). We
+ * do NOT swallow errors and continue — silent fail-open on checkpoint
+ * write would defeat the entire feature (a crash after the "successful"
+ * primitive but before a missing checkpoint would skip the step on
+ * resume, breaking exactly-once semantics).
+ *
+ * Imports from: @libsql/client, ./canonical_json.js.
+ * Imported by: DURABLE.2 evaluator wrap, DURABLE.4 resumer, future
+ * `opensquid checkpoints` CLI.
+ */
+import { canonicalJsonParse, canonicalJsonStringify } from './canonical_json.js';
+const CREATE_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS checkpoints (
+    run_id TEXT NOT NULL,
+    step_idx INTEGER NOT NULL,
+    fn TEXT NOT NULL,
+    inputs_hash TEXT NOT NULL,
+    outputs_json TEXT NOT NULL,
+    as_binding TEXT,
+    started_at_ms INTEGER NOT NULL,
+    completed_at_ms INTEGER NOT NULL,
+    status TEXT NOT NULL,
+    error_message TEXT,
+    PRIMARY KEY (run_id, step_idx)
+  );
+`;
+const CREATE_INDEX_RUN_ID_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_checkpoints_run_id ON checkpoints(run_id);
+`;
+const CREATE_INDEX_COMPLETED_AT_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_checkpoints_completed_at ON checkpoints(completed_at_ms);
+`;
+// ---------------------------------------------------------------------------
+// `run_manifests` — one row per run-start. Written by the rule dispatcher
+// before it calls evaluateProcess; consumed by the Resumer (DURABLE.4) to
+// reconstruct the ProcessContext for an interrupted run.
+//
+// `event_payload_json` is the canonical-JSON encoding of the inbound event
+// payload that triggered the run. Storing it here is what lets us replay
+// across daemon restart — the checkpoint rows themselves only carry the
+// hashed `inputsHash` of each primitive's args, not the original event.
+// ---------------------------------------------------------------------------
+const CREATE_TABLE_MANIFESTS_SQL = `
+  CREATE TABLE IF NOT EXISTS run_manifests (
+    run_id TEXT PRIMARY KEY,
+    pack_id TEXT NOT NULL,
+    pack_version TEXT NOT NULL,
+    skill TEXT NOT NULL,
+    rule_id TEXT NOT NULL,
+    event_kind TEXT NOT NULL,
+    event_payload_json TEXT NOT NULL,
+    started_at_ms INTEGER NOT NULL
+  );
+`;
+const CREATE_INDEX_MANIFEST_STARTED_AT_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_run_manifests_started_at ON run_manifests(started_at_ms);
+`;
+// ---------------------------------------------------------------------------
+// `terminal_markers` — one row written when a run finishes (success OR
+// terminal error). Resumer treats the presence of a row as "do not resume".
+//
+// Option 2 from the DURABLE.4 spec: explicit marker. Cheaper than Option 1
+// (which would require the resumer to load every pack at scan time and
+// compare `lastCompletedStep === totalSteps - 1`). One small insert per
+// terminal outcome; sub-ms write cost.
+// ---------------------------------------------------------------------------
+const CREATE_TABLE_TERMINALS_SQL = `
+  CREATE TABLE IF NOT EXISTS terminal_markers (
+    run_id TEXT PRIMARY KEY,
+    outcome TEXT NOT NULL,
+    terminated_at_ms INTEGER NOT NULL
+  );
+`;
+export class CheckpointStore {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Idempotent DDL — `CREATE TABLE IF NOT EXISTS` + indexes. Same posture
+     * as `RateLimiter.init` (AUTO.2) and the libsql RAG backends. Safe to
+     * call repeatedly; only the first call hits libsql.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await this.db.execute(CREATE_TABLE_SQL);
+        await this.db.execute(CREATE_INDEX_RUN_ID_SQL);
+        await this.db.execute(CREATE_INDEX_COMPLETED_AT_SQL);
+        await this.db.execute(CREATE_TABLE_MANIFESTS_SQL);
+        await this.db.execute(CREATE_INDEX_MANIFEST_STARTED_AT_SQL);
+        await this.db.execute(CREATE_TABLE_TERMINALS_SQL);
+        this.initialized = true;
+    }
+    /**
+     * Atomic write of a single checkpoint row. `INSERT OR REPLACE` makes
+     * the call idempotent on `(run_id, step_idx)` — a retried step
+     * overwrites its prior errored row with the new outcome, and a
+     * replay-with-same-inputs writes the same row twice without corruption.
+     *
+     * Throws on libsql error. The caller (evaluator in DURABLE.2) is the
+     * right place to decide fail-closed vs fail-open semantics; the store
+     * never silently swallows.
+     */
+    async append(write) {
+        await this.init();
+        const outputsJson = canonicalJsonStringify(write.outputs);
+        await this.db.execute({
+            sql: `INSERT OR REPLACE INTO checkpoints
+              (run_id, step_idx, fn, inputs_hash, outputs_json, as_binding,
+               started_at_ms, completed_at_ms, status, error_message)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [
+                write.runId,
+                write.stepIdx,
+                write.fn,
+                write.inputsHash,
+                outputsJson,
+                write.asBinding ?? null,
+                write.startedAtMs,
+                write.completedAtMs,
+                write.status,
+                write.errorMessage ?? null,
+            ],
+        });
+    }
+    /**
+     * Highest step_idx for which the run has a `status='completed'` row.
+     * Errored rows are excluded so the resume cursor naturally re-runs
+     * errored steps (the spec's retry-not-skip rule).
+     *
+     * Returns `null` when the run has no completed steps yet — caller starts
+     * the process from `step_idx = 0`.
+     */
+    async lastCompletedStep(runId) {
+        await this.init();
+        const rs = await this.db.execute({
+            sql: `SELECT run_id, step_idx, fn, inputs_hash, outputs_json, as_binding,
+                   started_at_ms, completed_at_ms, status, error_message
+            FROM checkpoints
+            WHERE run_id = ? AND status = 'completed'
+            ORDER BY step_idx DESC
+            LIMIT 1`,
+            args: [runId],
+        });
+        const row = rs.rows[0];
+        if (!row)
+            return null;
+        return rowToCheckpoint(row);
+    }
+    /**
+     * Replay every `status='completed'` checkpoint that owns an `as:`
+     * binding into a name→value map. The evaluator hydrates its
+     * `ctx.bindings` from this map before resuming.
+     *
+     * Errored steps and steps without `asBinding` are skipped — they
+     * contribute nothing to the rule's variable scope.
+     *
+     * Order: ascending `step_idx`. If two completed steps somehow share a
+     * binding name (a primitive author bug — the same `as:` reused in two
+     * places), the later step's value wins, matching the in-memory
+     * evaluator semantics.
+     */
+    async loadBindings(runId) {
+        await this.init();
+        const rs = await this.db.execute({
+            sql: `SELECT as_binding, outputs_json
+            FROM checkpoints
+            WHERE run_id = ? AND status = 'completed' AND as_binding IS NOT NULL
+            ORDER BY step_idx ASC`,
+            args: [runId],
+        });
+        const out = {};
+        for (const row of rs.rows) {
+            const asBinding = row.as_binding;
+            const outputsJson = row.outputs_json;
+            if (typeof asBinding !== 'string' || typeof outputsJson !== 'string')
+                continue;
+            out[asBinding] = canonicalJsonParse(outputsJson);
+        }
+        return out;
+    }
+    /**
+     * Fetch every row for a run in ascending `step_idx` order. Used by the
+     * evaluator's checkpoint wrap (DURABLE.2) to build a per-step lookup map
+     * once at process entry, then dispatch each durable step against the
+     * pre-fetched row without per-step libsql queries.
+     *
+     * Returns BOTH completed and errored rows — the evaluator decides what to
+     * do with each: completed + matching inputsHash → skip; everything else
+     * → re-execute and overwrite via `INSERT OR REPLACE`.
+     *
+     * Returns `[]` when the run has no checkpoints (fresh run).
+     */
+    async fetchRun(runId) {
+        await this.init();
+        const rs = await this.db.execute({
+            sql: `SELECT run_id, step_idx, fn, inputs_hash, outputs_json, as_binding,
+                   started_at_ms, completed_at_ms, status, error_message
+            FROM checkpoints
+            WHERE run_id = ?
+            ORDER BY step_idx ASC`,
+            args: [runId],
+        });
+        return rs.rows.map(rowToCheckpoint);
+    }
+    /**
+     * Delete every row whose `completed_at_ms` falls before `now - ms`.
+     * Returns the affected-row count for audit-log surfacing. Used by the
+     * future `opensquid checkpoints clean --older-than 7d` CLI verb.
+     *
+     * `nowMs` is optional and injected for tests; production callers pass
+     * `Date.now()`.
+     */
+    async pruneOlderThan(ms, nowMs = Date.now()) {
+        await this.init();
+        const cutoff = nowMs - ms;
+        const rs = await this.db.execute({
+            sql: `DELETE FROM checkpoints WHERE completed_at_ms < ?`,
+            args: [cutoff],
+        });
+        return Number(rs.rowsAffected);
+    }
+    /**
+     * Record a run-start manifest. Called by the rule dispatcher BEFORE
+     * `evaluateProcess` so that a crash mid-process leaves the manifest
+     * behind for the Resumer (DURABLE.4) to find.
+     *
+     * `INSERT OR REPLACE` — idempotent on `runId`. A retried run with the
+     * same identity overwrites the prior manifest (timestamps refresh,
+     * event payload re-canonicalizes to the same JSON anyway). The Resumer
+     * uses the latest manifest in any case.
+     */
+    async recordRunStart(manifest) {
+        await this.init();
+        const eventJson = canonicalJsonStringify(manifest.eventPayload);
+        await this.db.execute({
+            sql: `INSERT OR REPLACE INTO run_manifests
+              (run_id, pack_id, pack_version, skill, rule_id,
+               event_kind, event_payload_json, started_at_ms)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [
+                manifest.runId,
+                manifest.packId,
+                manifest.packVersion,
+                manifest.skill,
+                manifest.ruleId,
+                manifest.eventKind,
+                eventJson,
+                manifest.startedAtMs,
+            ],
+        });
+    }
+    /**
+     * Look up the manifest for a runId. Returns `null` when the run was
+     * never registered via `recordRunStart` — the Resumer treats those
+     * runs as orphan checkpoints and skips them with audit reason
+     * `manifest_missing`.
+     */
+    async getRunManifest(runId) {
+        await this.init();
+        const rs = await this.db.execute({
+            sql: `SELECT run_id, pack_id, pack_version, skill, rule_id,
+                   event_kind, event_payload_json, started_at_ms
+            FROM run_manifests WHERE run_id = ?`,
+            args: [runId],
+        });
+        const row = rs.rows[0];
+        if (!row)
+            return null;
+        return rowToManifest(row);
+    }
+    /**
+     * Record terminal outcome for a run. Called by the rule dispatcher
+     * AFTER `evaluateProcess` returns (regardless of `verdict` / `no_verdict`
+     * / `error`). The Resumer treats a row in `terminal_markers` as
+     * "this run finished — do not resume".
+     *
+     * `outcome` is stored as free-form text for audit visibility
+     * (verdict / no_verdict / error). The Resumer doesn't switch on it —
+     * presence of the row is what gates resume.
+     */
+    async recordRunTerminal(runId, outcome, nowMs) {
+        await this.init();
+        await this.db.execute({
+            sql: `INSERT OR REPLACE INTO terminal_markers
+              (run_id, outcome, terminated_at_ms)
+            VALUES (?, ?, ?)`,
+            args: [runId, outcome, nowMs],
+        });
+    }
+    /**
+     * Has the run terminated? `true` when a `terminal_markers` row exists
+     * for the runId. Used by tests + the Resumer's own scan to short-circuit
+     * cleanly without a second SELECT.
+     */
+    async hasTerminalMarker(runId) {
+        await this.init();
+        const rs = await this.db.execute({
+            sql: `SELECT 1 FROM terminal_markers WHERE run_id = ? LIMIT 1`,
+            args: [runId],
+        });
+        return rs.rows.length > 0;
+    }
+    /**
+     * Scan for runs the Resumer (DURABLE.4) should consider resuming.
+     *
+     * A run is "interrupted" when:
+     *   - It has at least one row in `checkpoints` (we ran something), AND
+     *   - It has NO row in `terminal_markers` (process didn't finish), AND
+     *   - The most-recent completed_at_ms is within `withinMs` of now
+     *     (the resume window — older runs are "stale" and skipped by the
+     *     Resumer with audit reason `stale`).
+     *
+     * Returns rows in ascending-age order (most recent first) so the
+     * Resumer drains the freshest interrupted runs before stale ones in
+     * pathological 100+-interrupted-runs cases.
+     *
+     * `withinMs <= 0` disables the window — useful for explicit
+     * `opensquid checkpoints resume <run_id>` which bypasses the default.
+     * The Resumer's own implementation passes `Number.POSITIVE_INFINITY`
+     * for that path; this method clamps to a "no window" semantic when
+     * the value is non-finite or non-positive.
+     */
+    async scanInterrupted(withinMs, nowMs = Date.now()) {
+        await this.init();
+        const useWindow = Number.isFinite(withinMs) && withinMs > 0;
+        const cutoff = useWindow ? nowMs - withinMs : 0;
+        const sql = `
+      SELECT c.run_id AS run_id,
+             MAX(c.step_idx) AS last_step_idx,
+             MAX(c.completed_at_ms) AS last_at_ms
+      FROM checkpoints c
+      LEFT JOIN terminal_markers t ON t.run_id = c.run_id
+      WHERE t.run_id IS NULL
+        ${useWindow ? 'AND c.completed_at_ms >= ?' : ''}
+        AND c.status = 'completed'
+      GROUP BY c.run_id
+      ORDER BY last_at_ms DESC
+    `;
+        const args = useWindow ? [cutoff] : [];
+        const rs = await this.db.execute({ sql, args });
+        return rs.rows.map((row) => {
+            const runIdRaw = row.run_id;
+            return {
+                runId: typeof runIdRaw === 'string' ? runIdRaw : '',
+                lastCompletedStep: Number(row.last_step_idx),
+                lastCompletedAtMs: Number(row.last_at_ms),
+            };
+        });
+    }
+}
+/**
+ * Map a libsql row to the typed `CheckpointRow`. `outputs_json` round-trips
+ * through `canonicalJsonParse` so base64 envelopes restore as Buffers.
+ */
+function rowToManifest(row) {
+    const eventJson = row.event_payload_json;
+    return {
+        runId: String(row.run_id),
+        packId: String(row.pack_id),
+        packVersion: String(row.pack_version),
+        skill: String(row.skill),
+        ruleId: String(row.rule_id),
+        eventKind: String(row.event_kind),
+        eventPayload: typeof eventJson === 'string' ? canonicalJsonParse(eventJson) : null,
+        startedAtMs: Number(row.started_at_ms),
+    };
+}
+function rowToCheckpoint(row) {
+    const status = row.status === 'errored' ? 'errored' : 'completed';
+    const asBindingRaw = row.as_binding;
+    const errorRaw = row.error_message;
+    const outputsJsonRaw = row.outputs_json;
+    return {
+        runId: String(row.run_id),
+        stepIdx: Number(row.step_idx),
+        fn: String(row.fn),
+        inputsHash: String(row.inputs_hash),
+        outputs: typeof outputsJsonRaw === 'string' ? canonicalJsonParse(outputsJsonRaw) : null,
+        asBinding: typeof asBindingRaw === 'string' ? asBindingRaw : undefined,
+        startedAtMs: Number(row.started_at_ms),
+        completedAtMs: Number(row.completed_at_ms),
+        status,
+        errorMessage: typeof errorRaw === 'string' ? errorRaw : undefined,
+    };
+}
+//# sourceMappingURL=checkpoint_store.js.map

package/dist/runtime/durable/checkpoint_store.js.map

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