specrails-core 6.0.0 → 6.1.0

package/dist/agent-runtime/engine/checkpoint/database.js

@@ -0,0 +1,304 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import { EngineError } from '../contracts.js';
+import { PersistenceError, privateSqlitePath } from '../storage/private-path.js';
+export { PersistenceError, ensurePrivateDirectory as ensurePrivateRunDirectory } from '../storage/private-path.js';
+/** Every identifier interpolated into SQL comes from this closed adapter-owned map. */
+const keys = {
+    runs: ['run_id'], visits: ['visit_id'], steps: ['run_id', 'node_path', 'scope_id'], attempts: ['attempt_id'],
+    invocations: ['invocation_id'], receipts: ['receipt_id'], budget: ['run_id'], interrupts: ['interrupt_id'],
+    control_inbox: ['request_id'], role_sessions: ['session_key'], piece_state: ['run_id', 'scope_id', 'node_path', 'key'], reservations: ['reservation_id'],
+    events: ['run_id', 'sequence'], checkpoints: ['thread_id', 'checkpoint_ns', 'checkpoint_id'],
+    writes: ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'idx'],
+};
+const schema = `
+CREATE TABLE runs (
+ run_id TEXT PRIMARY KEY, singleton INTEGER NOT NULL DEFAULT 1 UNIQUE CHECK(singleton=1),
+ workflow_id TEXT NOT NULL, definition_hash TEXT NOT NULL, definition_json TEXT NOT NULL, request_json TEXT NOT NULL,
+ source TEXT NOT NULL CHECK(source IN ('definition','builtin')), engine_version INTEGER NOT NULL,
+ runtime_identity_json TEXT NOT NULL, status TEXT NOT NULL, fork_of TEXT, completion_json TEXT,
+ checkpoint_thread_id TEXT NOT NULL, head_checkpoint_json TEXT, current_revision INTEGER NOT NULL DEFAULT 0,
+ transitions INTEGER NOT NULL DEFAULT 0, candidate_revision INTEGER NOT NULL DEFAULT 0,
+ candidate_json TEXT, verified_json TEXT, lease_epoch INTEGER NOT NULL DEFAULT 0,
+ next_event_sequence INTEGER NOT NULL DEFAULT 1, consecutive_failures INTEGER NOT NULL DEFAULT 0,
+ active_duration_ms REAL NOT NULL DEFAULT 0, active_started_at TEXT,
+ created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
+CREATE TABLE visits (
+ visit_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), node_path TEXT NOT NULL,
+ scope_id TEXT NOT NULL, branch_id TEXT, kind TEXT NOT NULL, effect TEXT NOT NULL CHECK(effect IN ('read','write')),
+ requires_ai INTEGER NOT NULL, local_visit INTEGER NOT NULL, global_transition INTEGER NOT NULL,
+ thread_id TEXT NOT NULL, checkpoint_ns TEXT NOT NULL, checkpoint_id TEXT NOT NULL, task_id TEXT NOT NULL, saver_checkpoint_ns TEXT,
+ before_revision INTEGER NOT NULL, created_at TEXT NOT NULL,
+ UNIQUE(thread_id,checkpoint_ns,checkpoint_id,task_id), UNIQUE(run_id,node_path,scope_id,local_visit));
+CREATE TABLE steps (
+ run_id TEXT NOT NULL REFERENCES runs(run_id), node_path TEXT NOT NULL, scope_id TEXT NOT NULL, branch_id TEXT,
+ kind TEXT NOT NULL, visits INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL, last_attempt_id TEXT, updated_at TEXT NOT NULL,
+ PRIMARY KEY(run_id,node_path,scope_id));
+CREATE TABLE attempts (
+ attempt_id TEXT PRIMARY KEY, visit_id TEXT NOT NULL REFERENCES visits(visit_id), run_id TEXT NOT NULL REFERENCES runs(run_id),
+ node_path TEXT NOT NULL, scope_id TEXT NOT NULL, visit INTEGER NOT NULL, attempt INTEGER NOT NULL, branch TEXT,
+ status TEXT NOT NULL, lease_epoch INTEGER NOT NULL, frame_json TEXT NOT NULL, started_at TEXT NOT NULL, ended_at TEXT,
+ error_code TEXT, error_message TEXT, outcome TEXT, output_json TEXT, usage_json TEXT, terminal_digest TEXT,
+ recovery_authorized INTEGER NOT NULL DEFAULT 0, interruption_json TEXT, inherited INTEGER NOT NULL DEFAULT 0,
+ UNIQUE(visit_id,attempt));
+CREATE TABLE invocations (
+ invocation_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), attempt_id TEXT NOT NULL REFERENCES attempts(attempt_id),
+ node_path TEXT NOT NULL, role TEXT, provider TEXT NOT NULL, model TEXT, kind TEXT, status TEXT NOT NULL,
+ started_at TEXT NOT NULL, ended_at TEXT, duration_ms REAL, tool_calls INTEGER, usage_json TEXT NOT NULL,
+ prompt_bytes INTEGER, context_bytes INTEGER, result_json TEXT, inherited INTEGER NOT NULL DEFAULT 0, ordinal INTEGER NOT NULL,
+ UNIQUE(attempt_id,ordinal));
+CREATE TABLE receipts (
+ receipt_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), node_path TEXT NOT NULL,
+ attempt_id TEXT NOT NULL REFERENCES attempts(attempt_id), kind TEXT NOT NULL, valid INTEGER NOT NULL,
+ candidate_hash TEXT NOT NULL, candidate_revision INTEGER NOT NULL, receipt_json TEXT NOT NULL, created_at TEXT NOT NULL);
+CREATE TABLE budget (
+ run_id TEXT PRIMARY KEY REFERENCES runs(run_id), max_cost_usd REAL, max_tokens INTEGER, max_duration_ms REAL,
+ known_cost_usd REAL NOT NULL DEFAULT 0, known_tokens INTEGER NOT NULL DEFAULT 0, duration_ms REAL NOT NULL DEFAULT 0,
+ input_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0,
+ cost_unknown INTEGER NOT NULL DEFAULT 0, input_unknown INTEGER NOT NULL DEFAULT 0, output_unknown INTEGER NOT NULL DEFAULT 0);
+CREATE TABLE interrupts (
+ interrupt_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), visit_id TEXT NOT NULL REFERENCES visits(visit_id),
+ attempt_id TEXT NOT NULL REFERENCES attempts(attempt_id), node_path TEXT NOT NULL, scope_id TEXT NOT NULL, branch_id TEXT,
+ kind TEXT NOT NULL, requested_at TEXT NOT NULL, payload_json TEXT NOT NULL, answered_at TEXT, answer_json TEXT);
+CREATE TABLE control_inbox (
+ request_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), kind TEXT NOT NULL CHECK(kind IN ('cancel','steer')),
+ payload_json TEXT NOT NULL, created_at TEXT NOT NULL, received_sequence INTEGER NOT NULL DEFAULT 0, consumed_by_attempt_id TEXT, consumed_at TEXT);
+CREATE TABLE role_sessions (
+ session_key TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), scope_id TEXT NOT NULL, node_path TEXT NOT NULL,
+ role TEXT NOT NULL, identity TEXT NOT NULL, state_json TEXT NOT NULL, updated_at TEXT NOT NULL);
+CREATE TABLE reservations (
+ reservation_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), attempt_id TEXT NOT NULL REFERENCES attempts(attempt_id),
+ max_tokens INTEGER, max_cost_usd REAL, created_at TEXT NOT NULL);
+CREATE TABLE piece_state (
+ run_id TEXT NOT NULL REFERENCES runs(run_id), scope_id TEXT NOT NULL, node_path TEXT NOT NULL, key TEXT NOT NULL,
+ visit_id TEXT REFERENCES visits(visit_id), value_json TEXT NOT NULL, updated_at TEXT NOT NULL,
+ PRIMARY KEY(run_id,scope_id,node_path,key));
+CREATE TABLE lease (
+ run_id TEXT PRIMARY KEY REFERENCES runs(run_id), owner TEXT NOT NULL, epoch INTEGER NOT NULL,
+ acquired_at TEXT NOT NULL, heartbeat_at TEXT NOT NULL, expires_at TEXT NOT NULL);
+CREATE TABLE events (
+ run_id TEXT NOT NULL REFERENCES runs(run_id), sequence INTEGER NOT NULL, event_id TEXT NOT NULL UNIQUE,
+ type TEXT NOT NULL, at TEXT NOT NULL, payload_json TEXT NOT NULL, inherited INTEGER NOT NULL DEFAULT 0, PRIMARY KEY(run_id,sequence));
+CREATE TABLE checkpoints (
+ thread_id TEXT NOT NULL, checkpoint_ns TEXT NOT NULL, checkpoint_id TEXT NOT NULL, parent_checkpoint_id TEXT,
+ type TEXT NOT NULL, checkpoint BLOB NOT NULL, metadata BLOB NOT NULL, metadata_type TEXT NOT NULL,
+ PRIMARY KEY(thread_id,checkpoint_ns,checkpoint_id));
+CREATE TABLE writes (
+ thread_id TEXT NOT NULL, checkpoint_ns TEXT NOT NULL, checkpoint_id TEXT NOT NULL, task_id TEXT NOT NULL,
+ idx INTEGER NOT NULL, channel TEXT NOT NULL, type TEXT NOT NULL, value BLOB NOT NULL,
+ PRIMARY KEY(thread_id,checkpoint_ns,checkpoint_id,task_id,idx));
+CREATE TABLE durable_revisions (revision INTEGER PRIMARY KEY AUTOINCREMENT, reason TEXT NOT NULL, at TEXT NOT NULL);
+CREATE TABLE row_versions (
+ table_name TEXT NOT NULL, row_key TEXT NOT NULL, revision INTEGER NOT NULL REFERENCES durable_revisions(revision),
+ row_json TEXT, PRIMARY KEY(table_name,row_key,revision));
+CREATE INDEX visits_run ON visits(run_id,node_path,scope_id,local_visit);
+CREATE INDEX attempts_visit ON attempts(visit_id,attempt);
+CREATE INDEX events_cursor ON events(run_id,sequence);
+CREATE INDEX revisions_cut ON row_versions(revision,table_name);
+PRAGMA user_version=1;
+`;
+function encodeRow(row) {
+    return JSON.stringify(Object.fromEntries(Object.entries(row).map(([key, value]) => [key,
+        ArrayBuffer.isView(value) ? { $sqliteBlob: Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('base64') } :
+            typeof value === 'bigint' ? { $sqliteInteger: value.toString() } : value])));
+}
+function decodeRow(json) {
+    const row = JSON.parse(json);
+    return Object.fromEntries(Object.entries(row).map(([key, value]) => [key, value && typeof value === 'object' && '$sqliteBlob' in value
+            ? Buffer.from(value.$sqliteBlob, 'base64') : value && typeof value === 'object' && '$sqliteInteger' in value ? BigInt(value.$sqliteInteger) : value]));
+}
+/** Short synchronous transactions own graph writes and ledger evidence together. */
+export class RunDatabase {
+    filename;
+    sqlite;
+    activeRevision;
+    inTransaction = false;
+    closed = false;
+    constructor(filename, sqlite) {
+        this.filename = filename;
+        this.sqlite = sqlite;
+    }
+    static async open(filename, options = {}) {
+        const target = await privateSqlitePath(filename, options);
+        const sqlite = new DatabaseSync(target, { readOnly: options.readOnly ?? false });
+        try {
+            sqlite.exec('PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;');
+            if (!options.readOnly)
+                sqlite.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
+            const version = Number(sqlite.prepare('PRAGMA user_version').get()?.user_version);
+            if (version === 0 && options.create) {
+                sqlite.exec('BEGIN IMMEDIATE');
+                try {
+                    sqlite.exec(schema);
+                    sqlite.exec('COMMIT');
+                }
+                catch (error) {
+                    sqlite.exec('ROLLBACK');
+                    throw error;
+                }
+            }
+            else if (version !== 1)
+                throw new PersistenceError('resume_incompatible', `Unsupported run database schema ${version}`);
+            return new RunDatabase(target, sqlite);
+        }
+        catch (error) {
+            sqlite.close();
+            throw error;
+        }
+    }
+    get revision() { return Number(this.sqlite.prepare('SELECT COALESCE(MAX(revision),0) AS value FROM durable_revisions').get().value); }
+    get transactionRevision() {
+        if (this.activeRevision === undefined)
+            throw new PersistenceError('internal', 'A revision transaction is required');
+        return this.activeRevision;
+    }
+    /** Undefined reason is reserved for leases/read reservations, which do not change graph history. */
+    transaction(reason, operation) {
+        if (this.inTransaction)
+            throw new PersistenceError('internal', 'Nested database transactions are not supported');
+        this.sqlite.exec('BEGIN IMMEDIATE');
+        this.inTransaction = true;
+        try {
+            if (reason !== undefined)
+                this.activeRevision = Number(this.sqlite.prepare('INSERT INTO durable_revisions(reason,at) VALUES (?,?)').run(reason, new Date().toISOString()).lastInsertRowid);
+            const result = operation();
+            if (result && typeof result.then === 'function')
+                throw new PersistenceError('internal', 'Database transactions cannot await effects');
+            this.sqlite.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.sqlite.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            this.activeRevision = undefined;
+            this.inTransaction = false;
+        }
+    }
+    get(table, key) {
+        const primary = keys[table];
+        return this.sqlite.prepare(`SELECT * FROM ${table} WHERE ${primary.map(name => `${name}=?`).join(' AND ')}`).get(...primary.map(name => key[name]));
+    }
+    put(table, row) {
+        const revision = this.transactionRevision, primary = keys[table], columns = Object.keys(row);
+        const allowed = new Set(this.sqlite.prepare(`PRAGMA table_info(${table})`).all().map(info => String(info.name)));
+        if (columns.some(column => !allowed.has(column)) || primary.some(column => row[column] === undefined))
+            throw new PersistenceError('internal', `Invalid ${table} row`);
+        const update = columns.filter(column => !primary.includes(column));
+        this.sqlite.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')}) ON CONFLICT(${primary.join(',')}) DO ${update.length ? `UPDATE SET ${update.map(column => `${column}=excluded.${column}`).join(',')}` : 'NOTHING'}`).run(...columns.map(column => row[column]));
+        const stored = this.get(table, row);
+        this.sqlite.prepare('INSERT OR REPLACE INTO row_versions(table_name,row_key,revision,row_json) VALUES (?,?,?,?)').run(table, JSON.stringify(primary.map(key => stored[key])), revision, encodeRow(stored));
+    }
+    delete(table, key) {
+        const revision = this.transactionRevision, primary = keys[table];
+        this.sqlite.prepare(`DELETE FROM ${table} WHERE ${primary.map(name => `${name}=?`).join(' AND ')}`).run(...primary.map(name => key[name]));
+        this.sqlite.prepare('INSERT OR REPLACE INTO row_versions(table_name,row_key,revision,row_json) VALUES (?,?,?,NULL)').run(table, JSON.stringify(primary.map(name => key[name])), revision);
+    }
+    /** Immutable cut includes overwritten pending writes and all child namespaces. Caller holds an inactive-source reservation. */
+    rowsAt(revision) {
+        if (!this.inTransaction)
+            throw new PersistenceError('internal', 'Historical reads require a source transaction');
+        if (!Number.isSafeInteger(revision) || revision < 1 || revision > this.revision)
+            throw new PersistenceError('invalid_arguments', 'Invalid historical revision');
+        const rows = this.sqlite.prepare(`SELECT v.table_name,v.row_json FROM row_versions v JOIN (
+      SELECT table_name,row_key,MAX(revision) revision FROM row_versions WHERE revision<=? GROUP BY table_name,row_key
+    ) cut ON v.table_name=cut.table_name AND v.row_key=cut.row_key AND v.revision=cut.revision WHERE v.row_json IS NOT NULL`).all(revision);
+        const order = Object.keys(keys);
+        return rows.map(row => ({ table: String(row.table_name), row: decodeRow(String(row.row_json)) }))
+            .sort((a, b) => order.indexOf(a.table) - order.indexOf(b.table));
+    }
+    /**
+     * Copies a complete historical cut into an empty, separately staged database.
+     * The source writer reservation prevents takeover/steering while rows are read;
+     * serialized graph blobs, opaque thread IDs and child namespaces stay unchanged.
+     */
+    forkAt(destination, options) {
+        if (destination.filename === this.filename || destination.sqlite.prepare('SELECT run_id FROM runs').get())
+            throw new EngineError('run_exists', 'Fork destination must be an empty separate database');
+        if (!options.runId)
+            throw new EngineError('invalid_arguments', 'A fork needs a new run ID');
+        return this.transaction(undefined, () => {
+            const source = this.sqlite.prepare('SELECT * FROM runs').get();
+            if (!source)
+                throw new EngineError('run_not_found', 'Source run does not exist');
+            if (source.run_id === options.runId)
+                throw new EngineError('invalid_arguments', 'Fork must have a new run ID');
+            const lease = this.sqlite.prepare('SELECT expires_at FROM lease WHERE run_id=?').get(source.run_id);
+            if (lease && Date.parse(String(lease.expires_at)) > Date.now())
+                throw new EngineError('lease_held', 'Cannot fork an actively leased run');
+            const activeRows = this.rowsAt(options.revision);
+            const revisions = this.sqlite.prepare('SELECT * FROM durable_revisions WHERE revision<=? ORDER BY revision').all(options.revision);
+            const versions = this.sqlite.prepare('SELECT * FROM row_versions WHERE revision<=? ORDER BY revision').all(options.revision);
+            const cutAt = Date.parse(String(revisions.at(-1)?.at)), omitted = options.omitPieceStatePrefixes ?? ['session:'];
+            const keep = (table, row) => table !== 'control_inbox' && table !== 'role_sessions' &&
+                !(table === 'piece_state' && row && omitted.some(prefix => String(row.key).startsWith(prefix)));
+            const revisionTimes = new Map(revisions.map(row => [Number(row.revision), Date.parse(String(row.at))]));
+            const rewrite = (table, original, at = cutAt) => {
+                const row = { ...original };
+                if ('run_id' in row)
+                    row.run_id = options.runId;
+                if (table === 'runs') {
+                    row.fork_of = source.run_id;
+                    row.lease_epoch = 0;
+                    row.active_duration_ms = Number(row.active_duration_ms) + (row.active_started_at ? Math.max(0, at - Date.parse(String(row.active_started_at))) : 0);
+                    row.active_started_at = null;
+                }
+                if (table === 'events') {
+                    row.inherited = 1;
+                    row.payload_json = JSON.stringify({ ...JSON.parse(String(row.payload_json)), runId: options.runId });
+                }
+                if (table === 'invocations' || table === 'attempts')
+                    row.inherited = 1;
+                return row;
+            };
+            destination.transaction(undefined, () => {
+                for (const row of revisions)
+                    destination.sqlite.prepare('INSERT INTO durable_revisions(revision,reason,at) VALUES (?,?,?)').run(row.revision, row.reason, row.at);
+                for (const version of versions) {
+                    const table = String(version.table_name);
+                    if (!(table in keys))
+                        throw new EngineError('storage_corrupt', 'Unknown revision table');
+                    const original = version.row_json ? decodeRow(String(version.row_json)) : undefined;
+                    if (!keep(table, original))
+                        continue;
+                    const row = original ? rewrite(table, original, revisionTimes.get(Number(version.revision))) : undefined;
+                    const key = row ? keys[table].map(name => row[name]) : JSON.parse(String(version.row_key)).map((value, index) => keys[table][index] === 'run_id' ? options.runId : value);
+                    destination.sqlite.prepare('INSERT INTO row_versions(table_name,row_key,revision,row_json) VALUES (?,?,?,?)')
+                        .run(table, JSON.stringify(key), version.revision, row ? encodeRow(row) : null);
+                }
+                for (const { table, row: original } of activeRows) {
+                    if (!keep(table, original))
+                        continue;
+                    const row = rewrite(table, original), columns = Object.keys(row);
+                    const allowed = new Set(destination.sqlite.prepare(`PRAGMA table_info(${table})`).all().map(info => String(info.name)));
+                    if (columns.some(column => !allowed.has(column)))
+                        throw new EngineError('storage_corrupt', 'Historical row has unknown fields');
+                    destination.sqlite.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')})`).run(...columns.map(column => row[column]));
+                }
+                destination.checkIntegrity();
+            });
+            destination.transaction('workflow-forked', () => { appendRunEvent(destination, options.runId, 'workflow_forked', { forkOf: String(source.run_id), beforeRevision: options.revision }); });
+            return { sourceRunId: String(source.run_id), checkpointThreadId: String(source.checkpoint_thread_id), revision: options.revision };
+        });
+    }
+    checkIntegrity() {
+        if (this.sqlite.prepare('PRAGMA integrity_check').get()?.integrity_check !== 'ok' || this.sqlite.prepare('PRAGMA foreign_key_check').all().length)
+            throw new PersistenceError('storage_corrupt', 'Run database integrity check failed');
+    }
+    close() { if (!this.closed) {
+        this.sqlite.close();
+        this.closed = true;
+    } }
+}
+/** Called inside the business transaction. Delivery/replay happens only after commit. */
+export function appendRunEvent(db, runId, type, payload, context = {}, timestamp = new Date().toISOString()) {
+    const run = db.get('runs', { run_id: runId });
+    if (!run)
+        throw new EngineError('run_not_found', 'Run does not exist');
+    const sequence = Number(run.next_event_sequence);
+    const event = { sequence, runId, type, timestamp, ...context, payload };
+    db.put('events', { run_id: runId, sequence, event_id: randomUUID(), type, at: timestamp, payload_json: JSON.stringify(event) });
+    db.put('runs', { ...run, next_event_sequence: sequence + 1, current_revision: db.transactionRevision, updated_at: timestamp });
+    return event;
+}

package/dist/agent-runtime/engine/checkpoint/lease.d.ts

@@ -0,0 +1,17 @@
+import { EngineError, type ExecutionLease } from '../contracts.js';
+import { RunDatabase } from './database.js';
+export declare const LEASE_HEARTBEAT_MS = 15000;
+/** Fencing is checked in the same SQLite transaction as every execution mutation. */
+export declare class RunLease {
+    private readonly db;
+    readonly runId: string;
+    private readonly now;
+    constructor(db: RunDatabase, runId: string, now?: () => number);
+    current(): ExecutionLease | undefined;
+    acquire(owner: string, ttlMs?: number): ExecutionLease;
+    assert(token: ExecutionLease): void;
+    renew(token: ExecutionLease, ttlMs?: number): ExecutionLease;
+    release(token: ExecutionLease): boolean;
+    /** An observer aborts all effects on loss. It must never leave an unhandled timer exception. */
+    heartbeat(token: ExecutionLease, onLost: (error: EngineError) => void): () => void;
+}

package/dist/agent-runtime/engine/checkpoint/lease.js

@@ -0,0 +1,82 @@
+import { EngineError } from '../contracts.js';
+import { appendRunEvent } from './database.js';
+const LEASE_MS = 60_000;
+export const LEASE_HEARTBEAT_MS = 15_000;
+/** Fencing is checked in the same SQLite transaction as every execution mutation. */
+export class RunLease {
+    db;
+    runId;
+    now;
+    constructor(db, runId, now = Date.now) {
+        this.db = db;
+        this.runId = runId;
+        this.now = now;
+    }
+    current() {
+        const row = this.db.sqlite.prepare('SELECT * FROM lease WHERE run_id=?').get(this.runId);
+        return row ? { runId: this.runId, owner: String(row.owner), epoch: Number(row.epoch), expiresAt: Date.parse(String(row.expires_at)) } : undefined;
+    }
+    acquire(owner, ttlMs = LEASE_MS) {
+        if (!owner || !Number.isFinite(ttlMs) || ttlMs <= 0)
+            throw new EngineError('invalid_arguments', 'Lease owner and positive TTL are required');
+        return this.db.transaction('lease-acquired', () => {
+            const now = this.now(), prior = this.current(), run = this.db.get('runs', { run_id: this.runId });
+            if (!run)
+                throw new EngineError('run_not_found', 'Run does not exist');
+            if (prior && prior.expiresAt > now)
+                throw new EngineError('lease_held', 'Another executor holds this run lease', { expiresAt: prior.expiresAt });
+            const epoch = Number(run.lease_epoch) + 1, at = new Date(now).toISOString(), expiresAt = now + ttlMs;
+            this.db.sqlite.prepare('INSERT OR REPLACE INTO lease(run_id,owner,epoch,acquired_at,heartbeat_at,expires_at) VALUES (?,?,?,?,?,?)')
+                .run(this.runId, owner, epoch, at, at, new Date(expiresAt).toISOString());
+            const previousActive = run.active_started_at ? Math.max(0, Math.min(now, prior?.expiresAt ?? now) - Date.parse(String(run.active_started_at))) : 0;
+            this.db.put('runs', { ...run, lease_epoch: epoch, current_revision: this.db.transactionRevision, updated_at: at,
+                active_duration_ms: Number(run.active_duration_ms) + previousActive, active_started_at: at });
+            if (prior)
+                appendRunEvent(this.db, this.runId, 'lease_recovered', { previousEpoch: prior.epoch, epoch }, {}, at);
+            return { runId: this.runId, owner, epoch, expiresAt };
+        });
+    }
+    assert(token) {
+        const current = this.current();
+        if (token.runId !== this.runId || !current || current.owner !== token.owner || current.epoch !== token.epoch || current.expiresAt <= this.now()) {
+            throw new EngineError('lease_lost', 'Execution lease expired or was replaced; late effects cannot commit');
+        }
+    }
+    renew(token, ttlMs = LEASE_MS) {
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0)
+            throw new EngineError('invalid_arguments', 'Lease TTL must be positive');
+        return this.db.transaction(undefined, () => {
+            this.assert(token);
+            const now = this.now(), expiresAt = now + ttlMs;
+            this.db.sqlite.prepare('UPDATE lease SET heartbeat_at=?,expires_at=? WHERE run_id=? AND owner=? AND epoch=?')
+                .run(new Date(now).toISOString(), new Date(expiresAt).toISOString(), this.runId, token.owner, token.epoch);
+            return { ...token, expiresAt };
+        });
+    }
+    release(token) {
+        return this.db.transaction('lease-released', () => {
+            const current = this.current();
+            if (!current || current.owner !== token.owner || current.epoch !== token.epoch)
+                return false;
+            const run = this.db.get('runs', { run_id: this.runId });
+            const active = run.active_started_at ? Math.max(0, Math.min(this.now(), current.expiresAt) - Date.parse(String(run.active_started_at))) : 0;
+            this.db.put('runs', { ...run, active_duration_ms: Number(run.active_duration_ms) + active, active_started_at: null });
+            this.db.sqlite.prepare('DELETE FROM lease WHERE run_id=? AND owner=? AND epoch=?').run(this.runId, token.owner, token.epoch);
+            return true;
+        });
+    }
+    /** An observer aborts all effects on loss. It must never leave an unhandled timer exception. */
+    heartbeat(token, onLost) {
+        const timer = setInterval(() => {
+            try {
+                this.renew(token);
+            }
+            catch (error) {
+                clearInterval(timer);
+                onLost(error instanceof EngineError ? error : new EngineError('lease_lost', String(error)));
+            }
+        }, LEASE_HEARTBEAT_MS);
+        timer.unref();
+        return () => clearInterval(timer);
+    }
+}

package/dist/agent-runtime/engine/checkpoint/ledger.d.ts

@@ -0,0 +1,133 @@
+import type { ProviderInvocation, PendingProviderInvocation } from '../../efficiency-types.js';
+import { type AttemptFrame, type DurableEngineEvent, type EngineUsage, type ExecutionLease, type JsonValue, type NodeAdmission, type PieceResult, type TaskIdentity, type TerminalCommit, type WorkflowBudget } from '../contracts.js';
+import { RunDatabase, type DatabaseRow } from './database.js';
+import { RunLease } from './lease.js';
+export interface FrozenLedgerInput {
+    runId: string;
+    workflowId: string;
+    definitionHash: string;
+    definition: unknown;
+    request: unknown;
+    runtimeIdentity: unknown;
+    source: 'definition' | 'builtin';
+    budget?: WorkflowBudget;
+    checkpointThreadId?: string;
+    forkOf?: string;
+}
+/** The ledger is authoritative for visits, attempts, usage, receipts and durable event cursors. */
+export declare class RunLedger {
+    readonly db: RunDatabase;
+    readonly token: ExecutionLease;
+    private readonly options;
+    readonly lease: RunLease;
+    private readonly now;
+    constructor(db: RunDatabase, token: ExecutionLease, options: {
+        maxTransitions: number;
+        now?: () => number;
+        failFast?: number;
+    });
+    static initialize(db: RunDatabase, input: FrozenLedgerInput): void;
+    get runId(): string;
+    run(): DatabaseRow;
+    private assertFrame;
+    private event;
+    /** Public node namespace differs from the parent saver namespace; never parse opaque namespace strings. */
+    private bindPendingTask;
+    private checkAdmission;
+    enter(input: NodeAdmission): AttemptFrame;
+    resultFor(frame: AttemptFrame): PieceResult | undefined;
+    terminal(frame: AttemptFrame, result: PieceResult): TerminalCommit;
+    /** Saver-only synchronous settlement; it shares the already-open pending-write transaction. */
+    commitTerminal(marker: TerminalCommit, task: TaskIdentity): DurableEngineEvent[];
+    fail(frame: AttemptFrame, error: {
+        code: string;
+        message: string;
+    }, retryable: boolean): void;
+    /** Stages evidence before an error is rethrown; saver owns its terminal __error__ transaction. */
+    prepareInterruption(frame: AttemptFrame, error: {
+        code: string;
+        message: string;
+    }): void;
+    commitError(task: TaskIdentity, error: unknown): DurableEngineEvent[];
+    /** Called by saver when LangGraph records the actual public interrupt IDs. */
+    commitInterrupts(task: TaskIdentity, values: Array<{
+        id: string;
+        value: JsonValue;
+    }>): DurableEngineEvent[];
+    /** Actual LangGraph interrupt identities, with answers retained across crashes before resume. */
+    interrupts(): Array<{
+        id: string;
+        nodePath: string;
+        scopeId: string;
+        branchId?: string;
+        attemptId: string;
+        kind: string;
+        requestedAt: string;
+        value: JsonValue;
+        answer?: JsonValue;
+    }>;
+    pendingInterrupts(): ReturnType<RunLedger['interrupts']>;
+    /** Persist validated answers before invoking Command; a retry must reuse exactly those answers. */
+    answerInterrupts(answers: Record<string, JsonValue>): void;
+    /** The run owner calls this only after graph.invoke has reached an idle interrupt barrier. */
+    settlePause(): void;
+    authorizeRecovery(attemptId: string): void;
+    startInvocation(frame: AttemptFrame, input: Omit<PendingProviderInvocation, 'ordinal'> & {
+        role?: string;
+    }, reservation?: {
+        maxTokens?: number;
+        maxCostUsd?: number;
+    }): number;
+    settleInvocation(frame: AttemptFrame, rawInvocation: ProviderInvocation & {
+        invocationId: string;
+    }, memo?: {
+        key: string;
+        value: JsonValue;
+    }): void;
+    /** Only a new fenced owner can close calls abandoned by an earlier executor.
+     * Keep unknown usage reservations: a lost response does not prove zero spend.
+     * This records accounting, never authorizes replay of an uncertain write. */
+    settleAbandonedInvocations(): number;
+    /** Caller owns the transaction and has checked either the current frame or
+     * exclusive recovery ownership of the earlier epoch. */
+    private commitInvocation;
+    readPieceState(frame: AttemptFrame, key: string): JsonValue | undefined;
+    private storePieceState;
+    writePieceState(frame: AttemptFrame, key: string, value: JsonValue): void;
+    private sessionOwner;
+    readScopedPieceState(frame: AttemptFrame, ownerNodePath: string, key: string): JsonValue | undefined;
+    writeScopedPieceState(frame: AttemptFrame, ownerNodePath: string, key: string, value: JsonValue): void;
+    usage(): EngineUsage;
+    /** Unreported spend keeps its reservation through recovery; bounds remain distinct from known usage. */
+    reservationStatus(): {
+        pendingInvocations: number;
+        knownTokens: number;
+        knownCostUsd: number;
+        tokensUnknown: boolean;
+        costUnknown: boolean;
+    };
+    activeDurationMs(): number;
+    scopeSnapshot(scopeId?: string): {
+        runId: string;
+        scopeId: string;
+        status: string;
+        transitions: number;
+        usage: EngineUsage;
+        candidate: import('../contracts.js').CandidateState | null;
+        verified: import('../contracts.js').VerifiedState | null;
+        consecutiveFailures: {
+            revision: number;
+            count: number;
+        };
+        attempts: Array<{
+            frame: AttemptFrame;
+            status: string;
+            result?: PieceResult;
+            error?: {
+                code: string;
+                message: string;
+            };
+        }>;
+    };
+    events(after?: number): DurableEngineEvent[];
+}