gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/eoa.ts

@@ -0,0 +1,288 @@
+/** Host-injected EOA execution kernel. It is not a production host or Safe adapter. */
+import { observeSafeTransaction } from './safe-observation';
+import { prepareSafeEnvelope, parseSafeTarget } from './safe-prepare';
+import { renderSafeExport } from './safe';
+import { deepFreeze, semanticHash } from '../workflow/lib/canonicalData';
+import { immutableDeliveryPlan, renderDeliveryExport, validateDeliveryProgress } from './export';
+import { parseUnsigned, same, type ExecutionSnapshot, type UnsignedEnvelope, type TransactionRecord } from './execution-model';
+import type { ExecutionClaim, ExecutionStore } from './execution-store';
+import { hash32, type TransactionObservation } from './observations';
+import { EoaRpcFailure, executionContext, observeEoaTransaction, verifyEoaChain, verifyEoaCode, type EoaExecutionContext, type EoaRpc } from './eoa-observation';
+import { verifyEoaSigned } from './eoa-signed';
+export { verifyEoaSigned } from './eoa-signed';
+export { observeEoaTransaction, eoaObservationReference } from './eoa-observation';
+export type { EoaRpc, EoaExecutionContext, EoaFinality, EoaObservationRequest } from './eoa-observation';
+export interface EoaApprovalSnapshot {
+    context: EoaExecutionContext;
+    transaction: ExecutionSnapshot['plan']['transactions'][number];
+    unsigned: UnsignedEnvelope;
+    signingRequestId: string;
+}
+/** Supplied only by controlled trusted host code. JSON flags and agent-provided functions confer no authority. */
+export interface EoaApprovalCapability {
+    withApproval<T>(snapshot: EoaApprovalSnapshot, controlledWork: () => Promise<T>): Promise<T>;
+}
+export interface EoaSignOnlySigner {
+    address: string;
+    /** Must sign only, retain the result under this immutable request ID, and NEVER broadcast. */
+    sign(signingRequestId: string, unsigned: UnsignedEnvelope): Promise<string>;
+    /** Read-only original-result lookup. Never start new signing when the intent is uncertain. */
+    recover?(signingRequestId: string): Promise<string | undefined>;
+}
+export interface EoaExecutionOptions {
+    plan: unknown;
+    context: EoaExecutionContext;
+    store: ExecutionStore;
+    provider: EoaRpc;
+    signer?: EoaSignOnlySigner;
+    approval?: EoaApprovalCapability;
+}
+export interface EoaExecutionResult {
+    status: 'submitted' | 'pending' | 'advanced' | 'complete' | 'reverted' | 'signing-result-unavailable';
+    snapshot: ExecutionSnapshot;
+}
+/** Explicit finite hash sets by plan transaction ID. No discovery, scanning, or implicit resend. */
+export type EoaHashReferences = Readonly<Record<string, readonly string[]>>;
+export function createDeliveryEoaExecution(options: EoaExecutionOptions) {
+    const plan = immutableDeliveryPlan(options.plan), context = executionContext(options.context, plan);
+    const contextHash = semanticHash({ schema: 'gate-delivery-eoa-context', version: 1, context });
+    const { store, provider, signer, approval } = options;
+    async function claim<T>(work: (claim: ExecutionClaim, snapshot: ExecutionSnapshot) => Promise<T>): Promise<T> {
+        const previous = await store.readExecution(plan.executionId);
+        return store.withExecutionClaim({ plan, contextHash, expectedRevision: previous?.revision ?? null }, async (c, s) => {
+            if (s.blockedReason !== null)
+                throw new Error(`Execution blocked: ${s.blockedReason}`);
+            await verifyPrefix(c, s);
+            return work(c, s);
+        });
+    }
+    function read(tx: TransactionRecord, transactionHash: string): Promise<TransactionObservation | undefined> {
+        return observeEoaTransaction({ plan, context, provider, index: tx.index, transactionHash, original: tx.signed && tx.unsigned ? { unsigned: tx.unsigned, signed: tx.signed } : undefined });
+    }
+    async function verifyPrefix(c: ExecutionClaim, s: ExecutionSnapshot): Promise<TransactionObservation[]> {
+        const completed: TransactionObservation[] = [], hashes = new Set<string>(), batches = new Map<string, TransactionObservation[]>();
+        for (const tx of s.transactions.slice(0, s.completedCount)) {
+            // Transport errors stop this invocation. A successful query showing lost evidence is durable finality loss.
+            let current: TransactionObservation | undefined;
+            try {
+                if (tx.observation?.safe) {
+                    const id = tx.observation.safe.envelopeId, e = s.safeEnvelopes.find(e => e.envelopeId === id);
+                    if (!e)
+                        throw Error('Missing frozen Safe prefix');
+                    let rows = batches.get(id);
+                    if (!rows) {
+                        rows = await observeSafeTransaction({ plan, envelope: e, provider, transactionHash: tx.observation.transactionHash });
+                        if (rows)
+                            batches.set(id, rows);
+                    }
+                    current = rows?.[tx.observation.safe.innerCallIndex];
+                }
+                else
+                    current = await read(tx, tx.observation!.transactionHash);
+            }
+            catch (error) {
+                if (error instanceof EoaRpcFailure)
+                    throw error;
+                store.blockExecution(c, s.revision, 'Previously finalized execution identity no longer verifies');
+                throw new Error('Previously finalized execution identity no longer verifies; execution blocked', { cause: error });
+            }
+            if (!current || current.state !== 'finalized-success' || !same(current, tx.observation) || (hashes.has(current.transactionHash) && (!current.safe || current.safe.innerCallIndex === 0))) {
+                store.blockExecution(c, s.revision, 'Previously finalized execution progress lost canonical finality');
+                throw new Error('Previously finalized execution progress lost canonical finality; execution blocked');
+            }
+            hashes.add(current.transactionHash);
+            completed.push(current);
+        }
+        return completed;
+    }
+    async function reconcileActive(c: ExecutionClaim, s: ExecutionSnapshot, references: EoaHashReferences): Promise<EoaExecutionResult> {
+        const start = s.completedCount;
+        while (s.completedCount < s.transactions.length) {
+            const tx = s.transactions[s.completedCount];
+            if (tx.state === 'finalized-reverted')
+                return { status: 'reverted', snapshot: s };
+            if (tx.state === 'blocked')
+                throw new Error('Transaction blocked');
+            const safe = s.safeEnvelopes.find(e => e.start === tx.index);
+            if (safe) {
+                const supplied = safe.transactionIds.flatMap(id => references[id] ?? []), candidates = [...new Set(supplied)];
+                if (candidates.length > 1)
+                    throw Error('Supply one original outer Safe hash per envelope');
+                if (!candidates.length)
+                    break;
+                const hash = hash32(candidates[0], 'Safe original hash');
+                if (s.transactions.some(t => t.observation?.transactionHash === hash))
+                    throw Error('Safe hash already consumed');
+                const rows = await observeSafeTransaction({ plan, envelope: safe, provider, transactionHash: hash });
+                if (!rows)
+                    break;
+                if (rows[0].state === 'finalized-reverted')
+                    return { status: 'reverted', snapshot: s };
+                if (rows[0].state !== 'finalized-success')
+                    break;
+                s = await store.recordSafeObservations(c, s.revision, safe.envelopeId, { readSafeObservations: async () => rows });
+                await verifyPrefix(c, s);
+                continue;
+            }
+            const supplied = references[tx.transactionId] ?? [];
+            if (!Array.isArray(supplied))
+                throw new Error('Expected explicit transaction hash set');
+            const candidates = tx.signed ? [tx.signed.transactionHash] : [...new Set([...supplied, ...(tx.observation ? [tx.observation.transactionHash] : [])])];
+            if (tx.signed && supplied.some(h => h !== tx.signed!.transactionHash))
+                throw new Error('Hash reference differs from original signed identity');
+            // Signing intent without durable bytes may only recover the original signature first.
+            if (tx.state === 'signing')
+                return { status: 'signing-result-unavailable', snapshot: s };
+            let selected: TransactionObservation | undefined;
+            for (const hash of candidates) {
+                hash32(hash, 'explicit transaction hash');
+                if (s.transactions.slice(0, s.completedCount).some(t => t.observation?.transactionHash === hash))
+                    throw new Error('Duplicate hash already completed a plan entry');
+                const observation = await read(tx, hash);
+                if (!observation)
+                    continue;
+                if (selected && selected.transactionHash !== observation.transactionHash)
+                    throw new Error('Ambiguous matching transaction hash set; supply one reference');
+                selected = observation;
+            }
+            if (!selected)
+                break;
+            const observed = selected;
+            s = await store.recordObservation(c, s.revision, observed.observationId, { readObservation: async () => observed });
+            if (observed.state === 'finalized-reverted')
+                return { status: 'reverted', snapshot: s };
+            if (observed.state !== 'finalized-success')
+                break;
+            // Recheck the entire accepted prefix before a subsequent advancement.
+            await verifyPrefix(c, s);
+        }
+        return { status: s.completedCount === s.transactions.length ? 'complete' : s.completedCount > start ? 'advanced' : 'pending', snapshot: s };
+    }
+    async function approved<T>(snapshot: EoaApprovalSnapshot, work: (assertApproval: () => void) => Promise<T>): Promise<T> {
+        if (typeof approval?.withApproval !== 'function')
+            throw new Error('Trusted host approval capability unavailable');
+        let started = false, accepting = true, pending: Promise<T> | undefined;
+        try {
+            await approval.withApproval(snapshot, () => {
+                if (!accepting || started)
+                    throw new Error('Approval work is revoked or already consumed');
+                started = true;
+                pending = work(() => { if (!accepting)
+                    throw new Error('Host approval scope revoked'); });
+                return pending;
+            });
+            accepting = false;
+            if (!pending)
+                throw new Error('Host approval did not authorize controlled work');
+            return await pending;
+        }
+        finally {
+            accepting = false;
+            if (pending)
+                await pending.catch(() => undefined);
+        }
+    }
+    return Object.freeze({
+        /** Current segment only; an existing frozen payload is returned without nonce rebasing. */
+        async prepareSafe(rawProfile: unknown) { const profile = parseSafeTarget(rawProfile); return claim(async (c, s) => { const prior = s.safeEnvelopes.find(e => e.start === s.completedCount); if (prior) {
+            if (prior.adapter !== profile.adapter || prior.multiSend !== profile.multiSendCallOnly || prior.safeTxGas !== profile.safeTxGas || !same(prior.submitter, profile.submitterPolicy) || !same(prior.finality, context.finality))
+                throw Error('Frozen Safe policy conflict');
+            const live = await prepareSafeEnvelope(plan, s.completedCount, profile, provider, context.finality);
+            if (live.nonce !== prior.nonce)
+                throw Error('Frozen Safe nonce consumed; reconcile the original hash without rebasing');
+            if (!same(live, prior))
+                throw Error('Frozen Safe execution identity changed');
+            return { envelope: prior, snapshot: s };
+        } const envelope = await prepareSafeEnvelope(plan, s.completedCount, profile, provider, context.finality); s = store.freezeSafeEnvelope(c, s.revision, envelope); return { envelope, snapshot: s }; }); },
+        /** One active operator transaction per call. Frozen envelopes are explicit; no implicit gas/nonce defaults. */
+        async execute(rawUnsigned?: unknown): Promise<EoaExecutionResult> {
+            return claim(async (c, initial) => {
+                let s = initial, tx = s.transactions[s.completedCount];
+                if (!tx)
+                    return { status: 'complete', snapshot: s };
+                if (tx.state === 'finalized-reverted' || tx.state === 'blocked')
+                    throw new Error('Reverted or blocked transaction');
+                if (['submission-uncertain', 'included-unfinalized'].includes(tx.state))
+                    return reconcileActive(c, s, {});
+                const planned = plan.transactions[tx.index];
+                if (planned.operation !== 0)
+                    throw new Error('Unsupported EOA operation');
+                if (planned.route !== 'operator' || planned.executor !== context.operator)
+                    throw new Error('Only active operator-route executor may sign');
+                if (!signer || typeof signer.sign !== 'function' || signer.address !== context.operator)
+                    throw new Error('Approved EOA signer unavailable or mismatched');
+                if (typeof approval?.withApproval !== 'function')
+                    throw new Error('Trusted host approval capability unavailable');
+                await verifyEoaChain(provider, context);
+                await verifyEoaCode(provider, planned.executor, 'latest');
+                const unsigned = rawUnsigned === undefined ? tx.unsigned : parseUnsigned(rawUnsigned, plan, tx.index);
+                if (!unsigned)
+                    throw new Error('Complete explicit unsigned approval snapshot required');
+                if (tx.unsigned && !same(unsigned, tx.unsigned))
+                    throw new Error('Frozen approval snapshot mismatch');
+                s = store.freezeAndReserve(c, s.revision, tx.transactionId, unsigned);
+                tx = s.transactions[s.completedCount];
+                const signingRequestId = semanticHash({ schema: 'gate-delivery-eoa-signing-request', version: 1, context, transaction: planned, unsigned });
+                if (tx.signingRequestId && tx.signingRequestId !== signingRequestId)
+                    throw new Error('Stable signing request identity mismatch');
+                const approvalSnapshot = deepFreeze({ context, transaction: planned, unsigned, signingRequestId });
+                return approved<EoaExecutionResult>(approvalSnapshot, async (assertApproval) => {
+                    // Approval may await user interaction; revalidate chain and finalized prefix immediately before controlled signing/send.
+                    await verifyPrefix(c, s);
+                    await verifyEoaChain(provider, context);
+                    await verifyEoaCode(provider, planned.executor, 'latest');
+                    assertApproval();
+                    if (tx.state === 'claimed') {
+                        s = store.markSigning(c, s.revision, signingRequestId);
+                        const raw = await signer.sign(signingRequestId, unsigned);
+                        assertApproval();
+                        s = store.commitSigned(c, s.revision, verifyEoaSigned(raw, unsigned));
+                    }
+                    else if (tx.state === 'signing') {
+                        const recovered = await signer.recover?.(signingRequestId);
+                        assertApproval();
+                        if (recovered === undefined)
+                            return { status: 'signing-result-unavailable', snapshot: s };
+                        s = store.commitSigned(c, s.revision, verifyEoaSigned(recovered, unsigned));
+                    }
+                    tx = s.transactions[s.completedCount];
+                    if (tx.state !== 'signed' || !tx.signed)
+                        throw new Error('Original durable signed bytes required');
+                    const signed = verifyEoaSigned(tx.signed.rawTransaction, unsigned);
+                    if (!same(signed, tx.signed))
+                        throw new Error('Durable signed identity mismatch');
+                    await verifyPrefix(c, s);
+                    await verifyEoaChain(provider, context);
+                    await verifyEoaCode(provider, planned.executor, 'latest');
+                    assertApproval();
+                    s = store.recordSubmissionIntent(c, s.revision);
+                    const returnedHash = await provider.request('eth_sendRawTransaction', [signed.rawTransaction]);
+                    if (returnedHash !== signed.transactionHash)
+                        throw new Error('Broadcast returned wrong hash; original submission remains uncertain');
+                    return { status: 'submitted', snapshot: s };
+                });
+            });
+        },
+        async reconcile(references: EoaHashReferences = {}): Promise<EoaExecutionResult> {
+            // Copy only explicit data before any awaited calls; caller mutation cannot change the route/hash set.
+            const refs = deepFreeze(JSON.parse(JSON.stringify(references))) as EoaHashReferences;
+            for (const [id, hashes] of Object.entries(refs)) {
+                if (!plan.transactions.some(tx => tx.transactionId === id) || !Array.isArray(hashes))
+                    throw new Error('Unknown transaction hash reference');
+                hashes.forEach(h => hash32(h, 'explicit transaction hash'));
+            }
+            return claim((c, s) => reconcileActive(c, s, refs));
+        },
+        /** Revalidates the durable contiguous prefix under the claim before producing trusted export progress. */
+        async export() {
+            return claim(async (c, s) => {
+                const completed = await verifyPrefix(c, s), byId = new Map(completed.map(o => [o.observationId, o]));
+                const progress = await validateDeliveryProgress({ plan, completed: completed.map(o => o.observationId), finalized: { readFinalized: async (ref) => byId.get(ref) } });
+                const exported = renderDeliveryExport(plan, progress);
+                const model = deepFreeze({ ...exported.model, safeEnvelopes: s.safeEnvelopes.map(e => renderSafeExport(plan, e).model), safePreparation: plan.transactions[s.completedCount]?.route !== 'external' ? 'not-applicable' : s.safeEnvelopes.some(e => e.start === s.completedCount) ? 'ready' : 'preparation-required' });
+                const json = JSON.stringify(model);
+                return deepFreeze({ model, json, markdown: `# Delivery calldata\n\nFrozen Safe envelopes cover only prepared segments. Future segments remain pending.\n\n\`\`\`json\n${json}\n\`\`\`\n` });
+            });
+        },
+    });
+}

package/runtime/delivery/execution-db.ts

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import type { DatabaseSync } from 'node:sqlite';
+import { type StoreFiles } from './execution-files';
+export type Database = Pick<DatabaseSync, 'exec' | 'prepare' | 'close'>;
+const marker = `CREATE TABLE protocol (version INTEGER PRIMARY KEY CHECK(version=1), kind TEXT NOT NULL, store_id TEXT NOT NULL, phase TEXT NOT NULL)`;
+const tables = [
+    marker,
+    `CREATE TABLE executions (execution_id TEXT PRIMARY KEY, context_hash TEXT NOT NULL, plan_hash TEXT NOT NULL, plan_json TEXT NOT NULL, revision TEXT NOT NULL, epoch TEXT NOT NULL, active_transaction_id TEXT, completed_count INTEGER NOT NULL)`,
+    `CREATE TABLE transactions (execution_id TEXT NOT NULL REFERENCES executions(execution_id), transaction_id TEXT NOT NULL, transaction_index INTEGER NOT NULL, state TEXT NOT NULL, unsigned_json TEXT, unsigned_digest TEXT, signing_request_id TEXT, signed_json TEXT, observation_json TEXT, PRIMARY KEY(execution_id,transaction_id), UNIQUE(execution_id,transaction_index))`,
+    `CREATE TABLE nonce_reservations (chain_id TEXT NOT NULL, signer TEXT NOT NULL, nonce TEXT NOT NULL, execution_id TEXT NOT NULL, transaction_id TEXT NOT NULL, unsigned_digest TEXT NOT NULL, PRIMARY KEY(chain_id,signer,nonce), FOREIGN KEY(execution_id,transaction_id) REFERENCES transactions(execution_id,transaction_id))`
+];
+const previousTables = [...tables];
+tables[1] = tables[1].replace('completed_count INTEGER NOT NULL)', 'completed_count INTEGER NOT NULL, blocked_reason TEXT)');
+const v2Tables = [...tables];
+tables.push(`CREATE TABLE safe_envelopes (execution_id TEXT NOT NULL REFERENCES executions(execution_id), envelope_id TEXT PRIMARY KEY, start_index INTEGER NOT NULL, envelope_json TEXT NOT NULL, chain_id TEXT NOT NULL, safe_address TEXT NOT NULL, safe_nonce TEXT NOT NULL, outer_hash TEXT, UNIQUE(execution_id,start_index), UNIQUE(chain_id,safe_address,safe_nonce), UNIQUE(chain_id,outer_hash))`);
+const normalize = (s: string) => s.replace(/\s+/g, ' ').trim();
+/** Entry-specific runtime guard, before loading node:sqlite. Global package engines are separate. */
+export function assertExecutionRuntime(version = process.versions.node): void {
+    if (!/^(?:22\.(?:1[3-9]|[2-9][0-9]|[1-9][0-9]{2,})\.\d+|24\.\d+\.\d+)$/.test(version))
+        throw new Error('Durable delivery execution requires Node ^22.13.0 || ^24.0.0');
+}
+export async function sqliteConstructor(): Promise<typeof DatabaseSync> { assertExecutionRuntime(); return (await import('node:sqlite')).DatabaseSync; }
+export function configure(db: Database, busyTimeout: number): void {
+    db.exec(`PRAGMA busy_timeout=${busyTimeout}; PRAGMA foreign_keys=ON`);
+    const mode = db.prepare('PRAGMA journal_mode').get() as {
+        journal_mode: string;
+    };
+    if (mode.journal_mode.toLowerCase() !== 'delete')
+        throw new Error('Unsupported store journal mode; DELETE required');
+    db.exec('PRAGMA synchronous=EXTRA');
+    if (process.platform === 'darwin')
+        db.exec('PRAGMA fullfsync=ON');
+}
+/** Synchronous SQL only. A committed-but-unsynced result is uncertain and must be reread. */
+export function commit<T>(db: Database, files: StoreFiles, work: () => T): T {
+    files.verify();
+    db.exec('BEGIN IMMEDIATE');
+    let committed = false;
+    try {
+        const value = work();
+        if (value && typeof (value as {
+            then?: unknown;
+        }).then === 'function')
+            throw new Error('Async work is forbidden inside a SQL transaction');
+        files.verify();
+        db.exec('COMMIT');
+        committed = true;
+        files.sync();
+        return value;
+    }
+    catch (error) {
+        if (!committed) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+        }
+        throw error;
+    }
+}
+interface Protocol {
+    version: number;
+    kind: string;
+    store_id: string;
+    phase: 'initializing' | 'ready';
+}
+function readSchema(db: Database, kind: 'authority' | 'execution', allowCreate: boolean, storeId?: string): Protocol {
+    const expected = kind === 'authority' ? [marker] : tables;
+    let rows = db.prepare("SELECT sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name").all() as {
+        sql: string;
+    }[];
+    let version = Number((db.prepare('PRAGMA user_version').get() as {
+        user_version: number;
+    }).user_version);
+    const targetVersion = kind === 'authority' ? 1 : 3;
+    if (kind === 'execution' && version === 1 && JSON.stringify(rows.map(r => normalize(r.sql)).sort()) === JSON.stringify(previousTables.map(normalize).sort())) {
+        db.exec('ALTER TABLE executions ADD COLUMN blocked_reason TEXT');
+        db.exec('PRAGMA user_version=2');
+        version = 2;
+        rows = db.prepare("SELECT sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name").all() as {
+            sql: string;
+        }[];
+    }
+    if (kind === 'execution' && version === 2 && JSON.stringify(rows.map(r => normalize(r.sql)).sort()) === JSON.stringify(v2Tables.map(normalize).sort())) {
+        db.exec(tables[tables.length - 1]);
+        db.exec('PRAGMA user_version=3');
+        version = 3;
+        rows = db.prepare("SELECT sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name").all() as {
+            sql: string;
+        }[];
+    }
+    if (rows.length === 0 && version === 0) {
+        if (!allowCreate)
+            throw new Error('Ready store cannot recreate a pristine business schema');
+        for (const sql of expected)
+            db.exec(sql);
+        db.prepare('INSERT INTO protocol(version,kind,store_id,phase) VALUES(1,?,?,?)').run(kind, storeId ?? randomUUID(), kind === 'authority' ? 'initializing' : 'ready');
+        db.exec(`PRAGMA user_version=${targetVersion}`);
+        rows = db.prepare("SELECT sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name").all() as {
+            sql: string;
+        }[];
+    }
+    else if (version !== targetVersion)
+        throw new Error('Unknown store schema version');
+    if (JSON.stringify(rows.map(r => normalize(r.sql)).sort()) !== JSON.stringify(expected.map(normalize).sort()))
+        throw new Error('Unknown store schema');
+    const protocol = db.prepare('SELECT * FROM protocol').all() as unknown as Protocol[];
+    if (protocol.length !== 1 || protocol[0].version !== 1 || protocol[0].kind !== kind || !(/^[0-9a-f-]{36}$/.test(protocol[0].store_id)) || !['initializing', 'ready'].includes(protocol[0].phase))
+        throw new Error('Unknown store protocol marker');
+    if (storeId !== undefined && protocol[0].store_id !== storeId)
+        throw new Error('Store UUID identity mismatch');
+    return protocol[0];
+}
+/** Bootstrap marker commits before business creation. No execution work is allowed until both UUIDs
+ * are synced and the authority marker is ready. A ready marker never reinitializes business data. */
+export function bootstrapAuthority(db: Database, files: StoreFiles): Protocol {
+    return commit(db, files, () => readSchema(db, 'authority', !fs.existsSync(files.execution) || fs.statSync(files.execution).size === 0));
+}
+export function initializeBusiness(authority: Database, business: Database, files: StoreFiles, protocol: Protocol): void {
+    commit(business, files, () => {
+        const p = readSchema(business, 'execution', protocol.phase === 'initializing', protocol.store_id);
+        if (p.phase !== 'ready')
+            throw new Error('Invalid business bootstrap phase');
+    });
+    if (protocol.phase === 'initializing') {
+        const result = authority.prepare("UPDATE protocol SET phase='ready' WHERE version=1 AND store_id=? AND phase='initializing'").run(protocol.store_id);
+        if (BigInt(result.changes) !== 1n)
+            throw new Error('Bootstrap marker CAS conflict');
+    }
+}

package/runtime/delivery/execution-files.ts

@@ -0,0 +1,135 @@
+/** Fixed private local store paths. Callers supply the shared host/CLI anchor, never a project cache. */
+import fs from 'node:fs';
+import path from 'node:path';
+export interface StoreFiles {
+    root: string;
+    authority: string;
+    execution: string;
+    verify(): void;
+    sync(): void;
+    ensureExecution(allowCreate: boolean): void;
+}
+function stat(name: string): fs.Stats | undefined { try {
+    return fs.lstatSync(name);
+}
+catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT')
+        return;
+    throw e;
+} }
+function owner(s: fs.Stats): boolean { return process.getuid === undefined || s.uid === process.getuid(); }
+function directory(name: string, privateDir = false): fs.Stats {
+    const s = fs.lstatSync(name);
+    if (!s.isDirectory() || s.isSymbolicLink())
+        throw new Error('Store path has a non-directory or symlink component');
+    if (privateDir && (!owner(s) || (s.mode & 0o777) !== 0o700))
+        throw new Error('Store root must be private 0700 and owned by this user');
+    return s;
+}
+function components(name: string): void {
+    const parts = name.split(path.sep);
+    let current = path.parse(name).root;
+    for (const part of parts.filter(Boolean)) {
+        current = path.join(current, part);
+        directory(current);
+    }
+}
+function syncDirectory(name: string): void {
+    const fd = fs.openSync(name, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function file(name: string): fs.Stats {
+    const s = fs.lstatSync(name);
+    if (!s.isFile() || s.isSymbolicLink() || s.nlink !== 1 || !owner(s) || (s.mode & 0o777) !== 0o600)
+        throw new Error('Store database/side file must be regular private 0600, owned, with one link');
+    return s;
+}
+function create(name: string): void {
+    let fd: number;
+    try {
+        fd = fs.openSync(name, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW, 0o600);
+    }
+    catch (e) {
+        if ((e as NodeJS.ErrnoException).code === 'EEXIST') {
+            file(name);
+            return;
+        }
+        throw e;
+    }
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    syncDirectory(path.dirname(name));
+}
+export function prepareStoreFiles(root: string): StoreFiles {
+    if (typeof root !== 'string' || !path.isAbsolute(root) || root !== path.normalize(root) || root.split(path.sep).some(p => p === '.' || p === '..'))
+        throw new Error('Trusted store root must be a canonical absolute path');
+    if (!stat(root)) {
+        components(path.dirname(root));
+        directory(path.dirname(root), true);
+        try {
+            fs.mkdirSync(root, { mode: 0o700 });
+        }
+        catch (e) {
+            if ((e as NodeJS.ErrnoException).code !== 'EEXIST')
+                throw e;
+        }
+        syncDirectory(path.dirname(root));
+    }
+    components(root);
+    const anchor = directory(root, true);
+    const authority = path.join(root, 'authority.sqlite'), execution = path.join(root, 'execution.sqlite');
+    const sideFiles = () => {
+        for (const db of [authority, execution]) {
+            for (const suffix of ['-wal', '-shm'])
+                if (stat(db + suffix))
+                    throw new Error('Unexpected WAL side file');
+            if (stat(db + '-journal'))
+                file(db + '-journal'); // SQLite alone recovers hot rollback journals.
+        }
+    };
+    sideFiles();
+    if (!stat(authority) && stat(execution))
+        throw new Error('Established store authority database is missing');
+    create(authority);
+    const a = file(authority);
+    let b = stat(execution) ? file(execution) : undefined;
+    const distinct = () => { if (b && a.dev === b.dev && a.ino === b.ino)
+        throw new Error('Database inode alias'); };
+    distinct();
+    const verify = () => {
+        components(root);
+        const d = directory(root, true);
+        if (d.dev !== anchor.dev || d.ino !== anchor.ino)
+            throw new Error('Store root inode changed');
+        sideFiles();
+        for (const [name, original] of [[authority, a], [execution, b]] as const) {
+            if (!original) {
+                if (stat(name))
+                    throw new Error("Unexpected database appeared before bootstrap");
+                continue;
+            }
+            const s = file(name);
+            if (s.dev !== original.dev || s.ino !== original.ino)
+                throw new Error('Store database inode changed');
+        }
+    };
+    return { root, authority, execution, verify, ensureExecution(allowCreate) {
+            if (!b) {
+                if (!allowCreate)
+                    throw new Error('Ready store business database is missing');
+                create(execution);
+                b = file(execution);
+                distinct();
+            }
+            verify();
+        }, sync() { verify(); syncDirectory(root); verify(); } };
+}

package/runtime/delivery/execution-model.ts

@@ -0,0 +1,102 @@
+import { canonicalJson, deepFreeze, digest, exactObject, semanticHash } from '../workflow/lib/canonicalData';
+import { strictData } from './data';
+import type { DeliveryPlan } from './plan';
+import type { SafeEnvelope } from './safe';
+import { uint256, hash32, type TransactionObservation } from './observations';
+export type TransactionState = 'claimed' | 'signing' | 'signed' | 'submission-uncertain' | 'included-unfinalized' | 'finalized-success' | 'finalized-reverted' | 'blocked';
+export interface UnsignedEnvelope {
+    chainId: string;
+    signer: string;
+    nonce: string;
+    to: string;
+    value: string;
+    data: string;
+    operation: 0 | 1;
+    type: 0 | 1 | 2;
+    gasLimit: string;
+    gasPrice: string | null;
+    maxFeePerGas: string | null;
+    maxPriorityFeePerGas: string | null;
+    accessList: {
+        address: string;
+        storageKeys: string[];
+    }[];
+}
+/** A durable byte record, deliberately not a signature-validation or send-authorization capability. */
+export interface SignedRecord {
+    rawTransaction: string;
+    transactionHash: string;
+    unsignedDigest: string;
+}
+export interface TransactionRecord {
+    transactionId: string;
+    index: number;
+    state: TransactionState;
+    unsigned: UnsignedEnvelope | null;
+    unsignedDigest: string | null;
+    signingRequestId: string | null;
+    signed: SignedRecord | null;
+    observation: TransactionObservation | null;
+}
+export interface ExecutionSnapshot {
+    executionId: string;
+    contextHash: string;
+    planHash: string;
+    plan: DeliveryPlan;
+    revision: string;
+    epoch: string;
+    activeTransactionId: string | null;
+    completedCount: number;
+    blockedReason: string | null;
+    transactions: TransactionRecord[];
+    safeEnvelopes: SafeEnvelope[];
+}
+export function decimal(raw: unknown, label: string): string { if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw))
+    throw new Error(`Invalid ${label}`); return raw; }
+function address(v: unknown): string { if (typeof v !== 'string' || !/^0x[0-9a-f]{40}$/.test(v))
+    throw new Error('Expected normalized signer/address'); return v; }
+export function parseUnsigned(raw: unknown, plan: DeliveryPlan, index: number): UnsignedEnvelope {
+    const v = exactObject(strictData(raw), ['chainId', 'signer', 'nonce', 'to', 'value', 'data', 'operation', 'type', 'gasLimit', 'gasPrice', 'maxFeePerGas', 'maxPriorityFeePerGas', 'accessList'], 'unsigned envelope');
+    for (const key of ['chainId', 'nonce', 'value', 'gasLimit'])
+        uint256(v[key], key);
+    address(v.signer);
+    address(v.to);
+    const tx = plan.transactions[index];
+    if (!tx || v.chainId !== plan.chainId || v.signer !== tx.executor || v.to !== tx.to || v.value !== tx.value || v.data !== tx.data || v.operation !== tx.operation)
+        throw new Error('Unsigned envelope differs from immutable transaction');
+    if (![0, 1, 2].includes(v.type as number))
+        throw new Error('Unsupported transaction type');
+    if (v.type === 2) {
+        uint256(v.maxFeePerGas, 'maxFeePerGas');
+        uint256(v.maxPriorityFeePerGas, 'maxPriorityFeePerGas');
+        if (v.gasPrice !== null || BigInt(v.maxPriorityFeePerGas as string) > BigInt(v.maxFeePerGas as string))
+            throw new Error('Invalid EIP-1559 fees');
+    }
+    else {
+        uint256(v.gasPrice, 'gasPrice');
+        if (v.maxFeePerGas !== null || v.maxPriorityFeePerGas !== null)
+            throw new Error('Invalid legacy fees');
+    }
+    if (!Array.isArray(v.accessList) || (v.type === 0 && v.accessList.length))
+        throw new Error('Invalid access list');
+    for (const item of v.accessList) {
+        const a = exactObject(item, ['address', 'storageKeys'], 'access list');
+        address(a.address);
+        if (!Array.isArray(a.storageKeys))
+            throw new Error('Invalid storage keys');
+        a.storageKeys.forEach(k => hash32(k, 'storage key'));
+    }
+    return deepFreeze(v as unknown as UnsignedEnvelope);
+}
+export function unsignedHash(envelope: UnsignedEnvelope): string { return semanticHash({ schema: 'gate-unsigned-envelope', version: 1, envelope }); }
+export function parseSigned(raw: unknown, unsignedDigest: string): SignedRecord {
+    const v = exactObject(strictData(raw), ['rawTransaction', 'transactionHash', 'unsignedDigest'], 'signed record');
+    if (typeof v.rawTransaction !== 'string' || !/^0x(?:[0-9a-f]{2})+$/.test(v.rawTransaction))
+        throw new Error('Invalid raw signed bytes');
+    hash32(v.transactionHash, 'signed transaction hash');
+    digest(v.unsignedDigest, 'unsigned');
+    if (v.unsignedDigest !== unsignedDigest)
+        throw new Error('Signed unsigned digest mismatch');
+    return deepFreeze(v as unknown as SignedRecord);
+}
+export function same(a: unknown, b: unknown): boolean { return canonicalJson(a) === canonicalJson(b); }