@alisio/core 0.5.2 → 0.6.0

package/dist/forge/javascript/vm-runner.js

@@ -0,0 +1,301 @@
+/**
+ * The guest side of the JavaScript engine (spec §6, D-26): runs INSIDE the isolate (a worker
+ * thread or a child process). It creates one QuickJS VM per execution, evaluates the prelude,
+ * bridges `tools.call`, `catalog.*`, `state.*`, `text`, `progress` to protocol messages and drives
+ * the VM's job queue until the root promise settles.
+ *
+ * The host never trusts anything produced here: every message is validated against the protocol,
+ * the call budget and the sizes again on the other side. This runner only has to be a faithful
+ * and well-behaved guest; if it is not, the host ends the execution.
+ *
+ * Erasable TypeScript only (D-33): the isolate entry loads this file under Node's type stripping.
+ */
+import { JSValueHandle, QuickJS } from "quickjs-wasi";
+import { PRELUDE_HASH, PRELUDE_SOURCE } from "./prelude.js";
+import { FORGE_PROTOCOL_VERSION } from "./runtime-manifest.js";
+/** What a failed script reports: a limit only when the engine's own error type said so (L7). */
+const classify = (info) => {
+    const message = info.message ?? "";
+    if (info.limit === "MEMORY_LIMIT" || info.limit === "STACK_LIMIT")
+        return { code: info.limit, message };
+    return { code: info.code ?? "SCRIPT_RUNTIME", message };
+};
+/** The VM itself failed outside the script (the exception comes from the engine, not from guest text). */
+const classifyEngineFailure = (message) => {
+    if (/out of memory/i.test(message))
+        return "MEMORY_LIMIT";
+    if (/call stack size/i.test(message))
+        return "STACK_LIMIT";
+    return "SCRIPT_RUNTIME";
+};
+/**
+ * Runs one execution to its terminal message (`complete` or `fatal`) and returns. The caller closes
+ * the transport (and exits the process) afterwards.
+ */
+export function runGuest(options) {
+    const { transport, module } = options;
+    const now = options.now ?? (() => performance.now());
+    return new Promise((finish) => {
+        let seq = 0;
+        let started = false;
+        let done = false;
+        const send = (type, payload) => {
+            if (done && type !== "complete" && type !== "fatal")
+                return;
+            transport.send({ protocol: FORGE_PROTOCOL_VERSION, type, seq: seq++, payload });
+        };
+        let vm;
+        let api;
+        let root;
+        let deadline = Number.POSITIVE_INFINITY;
+        let interrupted;
+        const calls = new Map();
+        const catalogs = new Map();
+        let nextCatalogId = 0;
+        /** Credits that arrive while the VM is still being created. */
+        let earlyCredits = 0;
+        /** A terminal condition the prelude asked for (a spent call budget). */
+        let requested;
+        const end = (type, payload) => {
+            if (done)
+                return;
+            send(type, payload);
+            done = true;
+            try {
+                vm?.dispose();
+            }
+            catch {
+                /* The VM is going away with the isolate. */
+            }
+            finish();
+        };
+        const fatal = (code, message) => end("fatal", { code, message });
+        const interruptHandler = () => {
+            const flag = options.flag ? Atomics.load(options.flag, 0) : 0;
+            if (flag !== 0) {
+                interrupted = flag === 2 ? "timeout" : "cancelled";
+                return true;
+            }
+            if (now() >= deadline) {
+                interrupted = "timeout";
+                return true;
+            }
+            return false;
+        };
+        const bridge = (kind, data) => {
+            const machine = vm;
+            const body = JSON.parse(data);
+            switch (kind) {
+                case "call": {
+                    const callId = Number(body.callId);
+                    const deferred = machine.newPromise();
+                    calls.set(callId, deferred);
+                    send("call", { callId, tool: body.tool, input: JSON.parse(String(body.input)) });
+                    return deferred.handle;
+                }
+                case "catalog": {
+                    const requestId = nextCatalogId++;
+                    const deferred = machine.newPromise();
+                    catalogs.set(requestId, deferred);
+                    send("catalog", {
+                        requestId,
+                        op: body.op,
+                        query: body.query,
+                        ...(typeof body.limit === "number" ? { limit: body.limit } : {}),
+                    });
+                    return deferred.handle;
+                }
+                case "output":
+                    send("output", body);
+                    return undefined;
+                case "progress":
+                    send("progress", {
+                        message: body.message,
+                        ...(typeof body.completed === "number" ? { completed: body.completed } : {}),
+                        ...(typeof body.total === "number" ? { total: body.total } : {}),
+                    });
+                    return undefined;
+                case "state.set":
+                    send("state.set", { key: body.key, value: JSON.parse(String(body.value)) });
+                    return undefined;
+                case "state.delete":
+                    send("state.delete", { key: body.key });
+                    return undefined;
+                case "fatal":
+                    // Ends the execution once the VM is back on the host stack (`pump` looks, never here).
+                    requested ??= { code: String(body.code), message: String(body.message) };
+                    return undefined;
+                default:
+                    throw new Error(`unknown bridge request ${kind}`);
+            }
+        };
+        const applyGrant = (credits) => {
+            const machine = vm;
+            const count = machine.newNumber(credits);
+            machine
+                .callFunction(api.grant, machine.undefined, count)
+                .dispose();
+            count.dispose();
+        };
+        /** Runs queued promise jobs, then checks how the root promise stands. */
+        const pump = () => {
+            if (done || !vm || !root)
+                return;
+            try {
+                vm.executePendingJobs();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (interrupted)
+                    return fatal(interrupted === "timeout" ? "TIMEOUT" : "CANCELLED", "interrupted");
+                if (requested)
+                    return fatal(requested.code, requested.message);
+                return fatal(classifyEngineFailure(message), message);
+            }
+            if (done)
+                return;
+            if (requested)
+                return fatal(requested.code, requested.message);
+            const exports = vm._getExports();
+            const state = exports.qjs_promise_state(root.ptr);
+            if (state === 0) {
+                if (calls.size + catalogs.size > 0)
+                    return;
+                const waiting = vm.callFunction(api?.waiting, vm.undefined);
+                const queued = Number(vm.dump(waiting));
+                waiting.dispose();
+                if (queued === 0)
+                    fatal("UNRESOLVABLE_PROMISE", "the script is waiting on a promise that nothing can settle");
+                return;
+            }
+            const resultHandle = new JSValueHandle(vm, exports.qjs_promise_result(root.ptr));
+            const text = vm.dump(resultHandle);
+            resultHandle.dispose();
+            if (state === 2) {
+                // `run` never rejects; a rejection here means the VM itself failed.
+                return fatal("SCRIPT_RUNTIME", `script failed: ${String(text)}`);
+            }
+            const info = JSON.parse(String(text));
+            if (info.ok)
+                end("complete", info.value === undefined ? {} : { value: info.value });
+            else {
+                const { code, message } = classify(info);
+                fatal(code, message);
+            }
+        };
+        const start = async (payload) => {
+            try {
+                deadline = now() + payload.limits.timeoutMs;
+                vm = await QuickJS.create({
+                    wasm: module,
+                    memoryLimit: payload.limits.memoryBytes,
+                    maxStackSize: payload.limits.stackBytes,
+                    interruptHandler,
+                    moduleLoader: {
+                        load: () => {
+                            throw new Error("modules are not available");
+                        },
+                    },
+                });
+                const machine = vm;
+                const bridgeFn = machine.newFunction("__forge_bridge", (kind, data) => {
+                    const result = bridge(String(machine.dump(kind)), String(machine.dump(data)));
+                    return result ?? machine.undefined;
+                });
+                const preludeFn = machine.evalCode(PRELUDE_SOURCE, "prelude.js");
+                const exported = machine.callFunction(preludeFn, machine.undefined, bridgeFn);
+                api = {
+                    init: exported.getProp("init"),
+                    run: exported.getProp("run"),
+                    grant: exported.getProp("grant"),
+                    waiting: exported.getProp("waiting"),
+                };
+                const limitsJson = machine.newString(JSON.stringify(payload.limits));
+                const stateJson = machine.newString(JSON.stringify(payload.state));
+                machine.callFunction(api.init, machine.undefined, limitsJson, stateJson).dispose();
+                limitsJson.dispose();
+                stateJson.dispose();
+                if (earlyCredits > 0)
+                    applyGrant(earlyCredits);
+                earlyCredits = 0;
+                let body;
+                try {
+                    body = machine.evalCode(`(async function () {\n${payload.source}\n})`, "js_run.js");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return fatal("SCRIPT_SYNTAX", message);
+                }
+                root = machine.callFunction(api.run, machine.undefined, body);
+                pump();
+            }
+            catch (error) {
+                if (done)
+                    return;
+                if (interrupted)
+                    return fatal(interrupted === "timeout" ? "TIMEOUT" : "CANCELLED", "interrupted");
+                fatal("ISOLATE_FAILURE", error instanceof Error ? error.message : String(error));
+            }
+        };
+        transport.onMessage((raw) => {
+            if (done)
+                return;
+            const message = raw;
+            try {
+                switch (message.type) {
+                    case "start":
+                        if (started)
+                            return;
+                        started = true;
+                        void start(message.payload);
+                        return;
+                    case "result": {
+                        const payload = message.payload;
+                        const deferred = calls.get(payload.callId);
+                        if (!deferred || !vm)
+                            return;
+                        calls.delete(payload.callId);
+                        const value = vm.newString(JSON.stringify(payload.ok ? payload.value : payload.error));
+                        if (payload.ok)
+                            deferred.resolve(value);
+                        else
+                            deferred.reject(value);
+                        value.dispose();
+                        pump();
+                        return;
+                    }
+                    case "catalog.result": {
+                        const payload = message.payload;
+                        const deferred = catalogs.get(payload.requestId);
+                        if (!deferred || !vm)
+                            return;
+                        catalogs.delete(payload.requestId);
+                        const value = vm.newString(JSON.stringify(payload.entries));
+                        deferred.resolve(value);
+                        value.dispose();
+                        pump();
+                        return;
+                    }
+                    case "grant": {
+                        const payload = message.payload;
+                        if (!vm || !api) {
+                            earlyCredits += payload.calls;
+                            return;
+                        }
+                        applyGrant(payload.calls);
+                        pump();
+                        return;
+                    }
+                    default:
+                        return;
+                }
+            }
+            catch (error) {
+                if (interrupted)
+                    return fatal(interrupted === "timeout" ? "TIMEOUT" : "CANCELLED", "interrupted");
+                fatal("ISOLATE_FAILURE", error instanceof Error ? error.message : String(error));
+            }
+        });
+        send("ready", { engine: "javascript-quickjs", preludeHash: PRELUDE_HASH });
+    });
+}

package/dist/forge/javascript/wasm-asset.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bun-only: the WASM as an embedded asset. Imported dynamically, and only when `process.versions.bun`
+ * is set (`wasm.ts`), so Node never touches it. In a compiled binary the default export is a path
+ * into the binary's virtual file system that `node:fs` can read; running from sources it is the
+ * real file.
+ */
+import path from "quickjs-wasi/quickjs.wasm";
+export default path;

package/dist/forge/javascript/wasm-asset.js

@@ -0,0 +1,8 @@
+/**
+ * Bun-only: the WASM as an embedded asset. Imported dynamically, and only when `process.versions.bun`
+ * is set (`wasm.ts`), so Node never touches it. In a compiled binary the default export is a path
+ * into the binary's virtual file system that `node:fs` can read; running from sources it is the
+ * real file.
+ */
+import path from "quickjs-wasi/quickjs.wasm" with { type: "file" };
+export default path;

package/dist/forge/javascript/wasm.d.ts

@@ -0,0 +1,15 @@
+export declare const sha256Hex: (data: Uint8Array | string) => string;
+/** Why `bytes` is not the pinned WASM, or undefined when it is. */
+export declare function wasmProblem(bytes: Uint8Array): string | undefined;
+/** The path of the WASM: the Bun asset on Bun, the package file on Node. */
+export declare function resolveWasmPath(): Promise<string>;
+export type WasmBytesLoader = () => Promise<Uint8Array>;
+/**
+ * Reads, verifies and compiles. Throws an `Error` whose message says why when the bytes are not the
+ * pinned build. Not cached: see `loadQuickJsModule`.
+ */
+export declare function compileVerifiedModule(loader?: WasmBytesLoader): Promise<WebAssembly.Module>;
+/** The process-wide compiled module. A failure is cached too: the engine stays not ready. */
+export declare function loadQuickJsModule(): Promise<WebAssembly.Module>;
+/** Test seam: forgets the cached module. */
+export declare function resetQuickJsModuleCache(): void;

package/dist/forge/javascript/wasm.js

@@ -0,0 +1,54 @@
+/**
+ * Loads, verifies and compiles the QuickJS WASM (spec D3, D17, D-22).
+ *
+ * The bytes come from the Bun asset (guarded dynamic import) or, on Node, from
+ * `quickjs-wasi/quickjs.wasm`. Their SHA-256 is compared with the manifest BEFORE compiling: a
+ * mismatch means the engine is not ready. The compiled `WebAssembly.Module` is cached per process
+ * and reused by every execution (the memory and globals of a VM never are).
+ *
+ * Erasable TypeScript only (D-33): the isolate entry imports this file under Node's type stripping.
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { QUICKJS_WASM_BYTES, QUICKJS_WASM_SHA256 } from "./runtime-manifest.js";
+export const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
+/** Why `bytes` is not the pinned WASM, or undefined when it is. */
+export function wasmProblem(bytes) {
+    if (bytes.byteLength !== QUICKJS_WASM_BYTES)
+        return `quickjs.wasm has ${bytes.byteLength} bytes, expected ${QUICKJS_WASM_BYTES}`;
+    const actual = sha256Hex(bytes);
+    if (actual !== QUICKJS_WASM_SHA256)
+        return `quickjs.wasm hash ${actual} does not match the pinned ${QUICKJS_WASM_SHA256}`;
+    return undefined;
+}
+/** The path of the WASM: the Bun asset on Bun, the package file on Node. */
+export async function resolveWasmPath() {
+    if (process.versions.bun) {
+        const asset = await import("./wasm-asset.js");
+        return asset.default;
+    }
+    return createRequire(import.meta.url).resolve("quickjs-wasi/quickjs.wasm");
+}
+const defaultLoader = async () => readFile(await resolveWasmPath());
+/**
+ * Reads, verifies and compiles. Throws an `Error` whose message says why when the bytes are not the
+ * pinned build. Not cached: see `loadQuickJsModule`.
+ */
+export async function compileVerifiedModule(loader = defaultLoader) {
+    const bytes = await loader();
+    const problem = wasmProblem(bytes);
+    if (problem)
+        throw new Error(problem);
+    return WebAssembly.compile(bytes);
+}
+let cached;
+/** The process-wide compiled module. A failure is cached too: the engine stays not ready. */
+export function loadQuickJsModule() {
+    cached ??= compileVerifiedModule();
+    return cached;
+}
+/** Test seam: forgets the cached module. */
+export function resetQuickJsModuleCache() {
+    cached = undefined;
+}

package/dist/forge/journal.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The Forja execution journal (spec §9.1, §9.3) over the shared SQLite store.
+ *
+ * One `forge_executions` row per execution whose status follows the Phase 1 state machine, one
+ * `forge_calls` row per nested call, and a restart reconciliation for rows a dead process left
+ * non-terminal. Only hashes of inputs are stored, never inputs or results. Every status change is
+ * a compare-and-set on the previous status, so a terminal state is reached exactly once even with
+ * several processes sharing the database.
+ */
+import type { EngineId, IsolationLevel, SqlDatabase } from "@alisio/sdk";
+import type { ForgeErrorCode } from "./errors.ts";
+import { type ExecutionState } from "./state-machine.ts";
+export type TerminalExecutionState = "succeeded" | "failed" | "cancelled" | "timed_out";
+/** Effect class of a nested call, as the gate classifies it. */
+export type CallEffect = "read" | "write" | "process" | "external" | "internal";
+export type CallStatus = "started" | "succeeded" | "failed";
+export interface OpenExecutionInput {
+    id: string;
+    rootSessionId: string;
+    sessionId: string;
+    toolCallId: string;
+    engine: EngineId;
+    isolation: IsolationLevel;
+    selectionReason: string;
+    codeSha256: string;
+    analysisExecutionId?: string | undefined;
+}
+export interface ExecutionRecord extends Omit<OpenExecutionInput, "analysisExecutionId"> {
+    status: ExecutionState;
+    startedAt: number;
+    endedAt?: number;
+    metrics?: Record<string, unknown>;
+    errorCode?: ForgeErrorCode;
+    terminationUnconfirmed: boolean;
+    analysisExecutionId?: string;
+    ownerPid?: number;
+}
+export interface CloseOutcome {
+    status: TerminalExecutionState;
+    errorCode?: ForgeErrorCode;
+    metrics?: Record<string, unknown>;
+    /** The host could not verify that the guest stopped (D-21). */
+    terminationUnconfirmed?: boolean;
+}
+export interface StartCallInput {
+    executionId: string;
+    /** 1-based position of the call within its execution. */
+    n: number;
+    toolName: string;
+    effect: CallEffect;
+    inputSha256: string;
+    /** Only kept for the `write` effect (D-31). */
+    paths?: string[];
+}
+export interface CallRecord {
+    executionId: string;
+    callId: string;
+    toolName: string;
+    effect: CallEffect;
+    status: CallStatus;
+    durationMs?: number;
+    inputSha256: string;
+    errorCode?: ForgeErrorCode;
+    paths?: string[];
+}
+export interface EndCallOutcome {
+    status: "succeeded" | "failed";
+    durationMs?: number;
+    errorCode?: ForgeErrorCode;
+}
+/** The id of the n-th nested call of a tool call (D-24). It never enters `tool_calls`. */
+export declare const forgeCallId: (toolCallId: string, n: number) => string;
+export declare class SqliteExecutionJournal {
+    #private;
+    constructor(db: SqlDatabase, options?: {
+        now?: () => number;
+        ownerPid?: number;
+    });
+    /** Records a new execution in `validating`. */
+    open(input: OpenExecutionInput): ExecutionRecord;
+    /** Links the execution to the `analysis_executions` row its engine created while preparing. */
+    linkAnalysisExecution(id: string, analysisExecutionId: string): void;
+    get(id: string): ExecutionRecord | undefined;
+    listByRoot(rootSessionId: string): ExecutionRecord[];
+    /** Moves to a non-terminal state the diagram allows. Terminal states go through `close()`. */
+    transition(id: string, to: ExecutionState): void;
+    /** Reaches a terminal state, once. A second close throws and changes nothing. */
+    close(id: string, outcome: CloseOutcome): void;
+    /** Records the start of a nested call and returns its id. */
+    startCall(input: StartCallInput): string;
+    /** Ends a call that is still `started`; false when it already ended (or does not exist). */
+    endCall(executionId: string, callId: string, outcome: EndCallOutcome): boolean;
+    calls(executionId: string): CallRecord[];
+}
+/**
+ * Restart reconciliation (§9.3, FJ-AC-25): every non-terminal execution whose owner process is
+ * gone (or unknown) becomes `failed` with `ISOLATE_FAILURE` and reason `interrupted`. Nothing is
+ * relaunched. Executions of another live process are left alone. Returns the rows reconciled.
+ *
+ * Call it once when the application opens the store (Phase 3 wires it next to the runner).
+ */
+export declare function reconcileInterruptedExecutions(db: SqlDatabase, options?: {
+    now?: () => number;
+    isAlive?: (pid: number) => boolean;
+}): number;

package/dist/forge/journal.js

@@ -0,0 +1,174 @@
+import { isProcessAlive } from "../runtime/process.js";
+import { canTransition, InvalidTransitionError } from "./state-machine.js";
+const TERMINAL = ["succeeded", "failed", "cancelled", "timed_out"];
+const isTerminal = (state) => TERMINAL.includes(state);
+/** The id of the n-th nested call of a tool call (D-24). It never enters `tool_calls`. */
+export const forgeCallId = (toolCallId, n) => `${toolCallId}:forge:${n}`;
+function toRecord(row) {
+    return {
+        id: String(row.id),
+        rootSessionId: String(row.root_session_id),
+        sessionId: String(row.session_id),
+        toolCallId: String(row.tool_call_id),
+        engine: row.engine,
+        isolation: row.isolation,
+        selectionReason: String(row.selection_reason),
+        status: row.status,
+        codeSha256: String(row.code_sha256),
+        startedAt: Number(row.started_at),
+        ...(row.ended_at != null ? { endedAt: Number(row.ended_at) } : {}),
+        ...(row.metrics_json != null
+            ? { metrics: JSON.parse(String(row.metrics_json)) }
+            : {}),
+        ...(row.error_code != null ? { errorCode: row.error_code } : {}),
+        terminationUnconfirmed: Number(row.termination_unconfirmed) === 1,
+        ...(row.analysis_execution_id != null
+            ? { analysisExecutionId: String(row.analysis_execution_id) }
+            : {}),
+        ...(row.owner_pid != null ? { ownerPid: Number(row.owner_pid) } : {}),
+    };
+}
+function toCall(row) {
+    return {
+        executionId: String(row.execution_id),
+        callId: String(row.call_id),
+        toolName: String(row.tool_name),
+        effect: row.effect,
+        status: row.status,
+        ...(row.duration_ms != null ? { durationMs: Number(row.duration_ms) } : {}),
+        inputSha256: String(row.input_sha256),
+        ...(row.error_code != null ? { errorCode: row.error_code } : {}),
+        ...(row.paths_json != null ? { paths: JSON.parse(String(row.paths_json)) } : {}),
+    };
+}
+export class SqliteExecutionJournal {
+    #db;
+    #now;
+    #ownerPid;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#now = options.now ?? Date.now;
+        this.#ownerPid = options.ownerPid ?? process.pid;
+    }
+    /** Records a new execution in `validating`. */
+    open(input) {
+        this.#db
+            .prepare(`INSERT INTO forge_executions(id,root_session_id,session_id,tool_call_id,engine,isolation,
+           selection_reason,status,code_sha256,started_at,analysis_execution_id,owner_pid)
+         VALUES(?,?,?,?,?,?,?,'validating',?,?,?,?)`)
+            .run(input.id, input.rootSessionId, input.sessionId, input.toolCallId, input.engine, input.isolation, input.selectionReason, input.codeSha256, this.#now(), input.analysisExecutionId ?? null, this.#ownerPid);
+        return this.#required(input.id);
+    }
+    /** Links the execution to the `analysis_executions` row its engine created while preparing. */
+    linkAnalysisExecution(id, analysisExecutionId) {
+        const result = this.#db
+            .prepare("UPDATE forge_executions SET analysis_execution_id=? WHERE id=?")
+            .run(analysisExecutionId, id);
+        if (Number(result.changes) === 0)
+            throw new Error(`Unknown Forja execution: ${id}`);
+    }
+    get(id) {
+        const row = this.#db.prepare("SELECT * FROM forge_executions WHERE id=?").get(id);
+        return row ? toRecord(row) : undefined;
+    }
+    listByRoot(rootSessionId) {
+        return this.#db
+            .prepare("SELECT * FROM forge_executions WHERE root_session_id=? ORDER BY started_at, id")
+            .all(rootSessionId).map(toRecord);
+    }
+    /** Moves to a non-terminal state the diagram allows. Terminal states go through `close()`. */
+    transition(id, to) {
+        if (isTerminal(to))
+            throw new Error(`Terminal state ${to} is reached through close(), not transition()`);
+        this.#advance(id, to, {});
+    }
+    /** Reaches a terminal state, once. A second close throws and changes nothing. */
+    close(id, outcome) {
+        if (!isTerminal(outcome.status))
+            throw new Error(`close() needs a terminal state, got ${String(outcome.status)}`);
+        this.#advance(id, outcome.status, {
+            endedAt: this.#now(),
+            errorCode: outcome.errorCode ?? null,
+            metrics: outcome.metrics ? JSON.stringify(outcome.metrics) : null,
+            unconfirmed: outcome.terminationUnconfirmed ? 1 : 0,
+        });
+    }
+    #advance(id, to, terminal) {
+        this.#db.transaction(() => {
+            const row = this.#db.prepare("SELECT status FROM forge_executions WHERE id=?").get(id);
+            if (!row)
+                throw new Error(`Unknown Forja execution: ${id}`);
+            if (!canTransition(row.status, to))
+                throw new InvalidTransitionError(row.status, to);
+            if (terminal.endedAt === undefined) {
+                this.#db
+                    .prepare("UPDATE forge_executions SET status=? WHERE id=? AND status=?")
+                    .run(to, id, row.status);
+                return;
+            }
+            this.#db
+                .prepare(`UPDATE forge_executions SET status=?, ended_at=?, error_code=?, metrics_json=?,
+             termination_unconfirmed=? WHERE id=? AND status=?`)
+                .run(to, terminal.endedAt, terminal.errorCode ?? null, terminal.metrics ?? null, terminal.unconfirmed ?? 0, id, row.status);
+        });
+    }
+    /** Records the start of a nested call and returns its id. */
+    startCall(input) {
+        const execution = this.#required(input.executionId);
+        const callId = forgeCallId(execution.toolCallId, input.n);
+        this.#db
+            .prepare(`INSERT INTO forge_calls(execution_id,call_id,tool_name,effect,status,input_sha256,paths_json)
+         VALUES(?,?,?,?,'started',?,?)`)
+            .run(input.executionId, callId, input.toolName, input.effect, input.inputSha256, input.effect === "write" && input.paths ? JSON.stringify(input.paths) : null);
+        return callId;
+    }
+    /** Ends a call that is still `started`; false when it already ended (or does not exist). */
+    endCall(executionId, callId, outcome) {
+        const result = this.#db
+            .prepare(`UPDATE forge_calls SET status=?, duration_ms=?, error_code=?
+         WHERE execution_id=? AND call_id=? AND status='started'`)
+            .run(outcome.status, outcome.durationMs ?? null, outcome.errorCode ?? null, executionId, callId);
+        return Number(result.changes) > 0;
+    }
+    calls(executionId) {
+        const rows = this.#db
+            .prepare("SELECT * FROM forge_calls WHERE execution_id=?")
+            .all(executionId);
+        const position = (callId) => Number(callId.slice(callId.lastIndexOf(":") + 1));
+        return rows.map(toCall).sort((a, b) => position(a.callId) - position(b.callId));
+    }
+    #required(id) {
+        const record = this.get(id);
+        if (!record)
+            throw new Error(`Unknown Forja execution: ${id}`);
+        return record;
+    }
+}
+/**
+ * Restart reconciliation (§9.3, FJ-AC-25): every non-terminal execution whose owner process is
+ * gone (or unknown) becomes `failed` with `ISOLATE_FAILURE` and reason `interrupted`. Nothing is
+ * relaunched. Executions of another live process are left alone. Returns the rows reconciled.
+ *
+ * Call it once when the application opens the store (Phase 3 wires it next to the runner).
+ */
+export function reconcileInterruptedExecutions(db, options = {}) {
+    const now = (options.now ?? Date.now)();
+    const isAlive = options.isAlive ?? isProcessAlive;
+    return db.transaction(() => {
+        const rows = db
+            .prepare(`SELECT id, status, owner_pid FROM forge_executions
+         WHERE status NOT IN ('succeeded','failed','cancelled','timed_out')`)
+            .all();
+        const update = db.prepare(`UPDATE forge_executions SET status='failed', error_code='ISOLATE_FAILURE', ended_at=?,
+         metrics_json=? WHERE id=? AND status=?`);
+        let reconciled = 0;
+        for (const row of rows) {
+            if (row.owner_pid != null && isAlive(row.owner_pid))
+                continue;
+            const result = update.run(now, JSON.stringify({ reason: "interrupted" }), row.id, row.status);
+            if (Number(result.changes) > 0)
+                reconciled++;
+        }
+        return reconciled;
+    });
+}