gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/execution-store.ts

@@ -0,0 +1,411 @@
+/** Local durable record/claim kernel. No signer, broadcaster or production chain-verification adapter. */
+import { canonicalJson, deepFreeze, digest, nonempty } from '../workflow/lib/canonicalData';
+import { immutableDeliveryPlan } from './export';
+import { prepareStoreFiles, type StoreFiles } from './execution-files';
+import { sqliteConstructor, configure, bootstrapAuthority, initializeBusiness, commit, type Database } from './execution-db';
+import { decimal, parseUnsigned, parseSigned, unsignedHash, same, type ExecutionSnapshot, type TransactionRecord, type TransactionState } from './execution-model';
+import { parseSafeEnvelope } from './safe';
+import { parseObservation, type TransactionObservation, type TrustedObservationPort } from './observations';
+import type { DeliveryPlan } from './plan';
+export { assertExecutionRuntime } from './execution-db';
+export type { ExecutionSnapshot, TransactionRecord, TransactionState, UnsignedEnvelope, SignedRecord } from './execution-model';
+export type { TrustedObservationPort, TransactionObservation } from './observations';
+declare const claimBrand: unique symbol;
+/** Only the original live object issued to an awaited callback is authority. */
+export interface ExecutionClaim {
+    readonly [claimBrand]: true;
+}
+interface Session {
+    db: Database;
+    live: boolean;
+    accepting: boolean;
+    epoch: string;
+    executionId: string;
+    pending: Set<Promise<unknown>>;
+}
+interface ExecutionRow {
+    execution_id: string;
+    context_hash: string;
+    plan_hash: string;
+    plan_json: string;
+    revision: string;
+    epoch: string;
+    active_transaction_id: string | null;
+    completed_count: number;
+    blocked_reason: string | null;
+}
+interface TransactionRow {
+    execution_id: string;
+    transaction_id: string;
+    transaction_index: number;
+    state: TransactionState;
+    unsigned_json: string | null;
+    unsigned_digest: string | null;
+    signing_request_id: string | null;
+    signed_json: string | null;
+    observation_json: string | null;
+}
+export interface ClaimRequest {
+    plan: unknown;
+    contextHash: string;
+    expectedRevision: string | null;
+}
+export interface ExecutionStoreOptions {
+    /** Canonical absolute private directory selected by the trusted host, shared across CLI/projects/environments.
+     * Supported only on a local filesystem implementing SQLite locks and strict file/directory fsync. */
+    trustedRoot: string;
+    /** Waiting is bounded; expiration reports busy and NEVER steals a lifetime lock. */
+    busyTimeoutMs?: number;
+}
+const states = new Set(['claimed', 'signing', 'signed', 'submission-uncertain', 'included-unfinalized', 'finalized-success', 'finalized-reverted', 'blocked']);
+const changes = (result: {
+    changes: number | bigint;
+}) => {
+    if (BigInt(result.changes) !== 1n)
+        throw new Error('Execution revision/epoch/active-transaction CAS conflict');
+};
+function snapshot(db: Database, id: string): ExecutionSnapshot | undefined {
+    const row = db.prepare('SELECT * FROM executions WHERE execution_id=?').get(id) as unknown as ExecutionRow | undefined;
+    if (!row)
+        return;
+    const plan = immutableDeliveryPlan(JSON.parse(row.plan_json));
+    if (row.blocked_reason !== null)
+        nonempty(row.blocked_reason, 'execution block reason');
+    digest(row.context_hash, 'context');
+    decimal(row.revision, 'revision');
+    decimal(row.epoch, 'epoch');
+    if (plan.executionId !== row.execution_id || plan.planHash !== row.plan_hash)
+        throw new Error('Corrupt execution identity');
+    const rows = db.prepare('SELECT * FROM transactions WHERE execution_id=? ORDER BY transaction_index').all(id) as unknown as TransactionRow[];
+    if (rows.length !== plan.transactions.length || !Number.isSafeInteger(row.completed_count) || row.completed_count < 0 || row.completed_count > rows.length)
+        throw new Error('Corrupt execution transaction prefix');
+    const safeEnvelopes = (db.prepare('SELECT * FROM safe_envelopes WHERE execution_id=? ORDER BY start_index').all(id) as {
+        envelope_json: string;
+        envelope_id: string;
+        start_index: number;
+        chain_id: string;
+        safe_address: string;
+        safe_nonce: string;
+        outer_hash: string | null;
+    }[]).map(r => { const e = parseSafeEnvelope(JSON.parse(r.envelope_json), plan); if (e.envelopeId !== r.envelope_id || e.start !== r.start_index || e.chainId !== r.chain_id || e.safe !== r.safe_address || e.nonce !== r.safe_nonce)
+        throw Error('Corrupt Safe envelope reservation'); return e; });
+    for (let i = 1; i < safeEnvelopes.length; i++)
+        if (safeEnvelopes[i].start < safeEnvelopes[i - 1].start + safeEnvelopes[i - 1].count)
+            throw Error('Corrupt overlapping Safe envelopes');
+    const transactions: TransactionRecord[] = rows.map((r, i) => {
+        if (r.transaction_index !== i || r.transaction_id !== plan.transactions[i].transactionId || !states.has(r.state))
+            throw new Error('Corrupt transaction identity/state');
+        const unsigned = r.unsigned_json === null ? null : parseUnsigned(JSON.parse(r.unsigned_json), plan, i);
+        if ((unsigned ? unsignedHash(unsigned) : null) !== r.unsigned_digest)
+            throw new Error('Corrupt unsigned digest');
+        if (unsigned) {
+            const n = db.prepare('SELECT * FROM nonce_reservations WHERE chain_id=? AND signer=? AND nonce=?').get(unsigned.chainId, unsigned.signer, unsigned.nonce) as {
+                execution_id: string;
+                transaction_id: string;
+                unsigned_digest: string;
+            } | undefined;
+            if (!n || n.execution_id !== id || n.transaction_id !== r.transaction_id || n.unsigned_digest !== r.unsigned_digest)
+                throw new Error('Corrupt nonce reservation');
+        }
+        const signed = r.signed_json === null ? null : parseSigned(JSON.parse(r.signed_json), r.unsigned_digest ?? '');
+        const observation = r.observation_json === null ? null : parseObservation(JSON.parse(r.observation_json), plan, i);
+        if (observation?.safe) {
+            const e = safeEnvelopes.find(e => e.envelopeId === observation.safe!.envelopeId);
+            if (!e || i !== e.start + observation.safe.innerCallIndex || observation.safe.innerCallIndex >= e.count)
+                throw Error('Corrupt Safe observation range');
+        }
+        if (r.signing_request_id !== null)
+            nonempty(r.signing_request_id, 'signing request');
+        if ((r.state === 'signing' && (!unsigned || !r.signing_request_id || signed)) || (['signed', 'submission-uncertain'].includes(r.state) && !signed) || (signed && (!unsigned || !r.signing_request_id)))
+            throw new Error('Corrupt signing state');
+        if ((r.state === 'finalized-success') !== (i < row.completed_count) || (['included-unfinalized', 'finalized-success', 'finalized-reverted'].includes(r.state) && observation?.state !== r.state))
+            throw new Error('Corrupt observation prefix');
+        if (signed && observation && signed.transactionHash !== observation.transactionHash)
+            throw new Error('Corrupt signed observation binding');
+        return { transactionId: r.transaction_id, index: i, state: r.state, unsigned, unsignedDigest: r.unsigned_digest, signingRequestId: r.signing_request_id, signed, observation };
+    });
+    if (row.active_transaction_id !== null && row.active_transaction_id !== transactions[row.completed_count]?.transactionId)
+        throw new Error('Corrupt active transaction');
+    if (transactions.some((t, i) => i > row.completed_count && (t.unsigned || t.signed || t.observation || t.state !== 'claimed')))
+        throw new Error('Corrupt noncontiguous progress');
+    return deepFreeze({ executionId: id, contextHash: row.context_hash, planHash: row.plan_hash, plan, revision: row.revision, epoch: row.epoch, activeTransactionId: row.active_transaction_id, completedCount: row.completed_count, blockedReason: row.blocked_reason, transactions, safeEnvelopes });
+}
+/** Connections and claim maps never leave this object; JSON snapshots convey no live authority. */
+export class ExecutionStore {
+    readonly #files: StoreFiles;
+    readonly #busy: number;
+    readonly #claims = new WeakMap<object, Session>();
+    constructor(files: StoreFiles, busy: number, private readonly DatabaseSync: Awaited<ReturnType<typeof sqliteConstructor>>) { this.#files = files; this.#busy = busy; }
+    async #locked<T>(callback: (db: Database) => Promise<T>): Promise<T> {
+        this.#files.verify();
+        const authority = new this.DatabaseSync(this.#files.authority);
+        let business: Database | undefined;
+        let held = false;
+        try {
+            configure(authority, this.#busy);
+            const protocol = bootstrapAuthority(authority, this.#files);
+            authority.exec('BEGIN IMMEDIATE');
+            held = true;
+            // Refresh under the bootstrap lock: a competitor may have completed initialization in the gap.
+            const actual = authority.prepare('SELECT * FROM protocol WHERE version=1').get() as unknown as typeof protocol;
+            if (actual.store_id !== protocol.store_id)
+                throw new Error('Authority bootstrap identity changed');
+            this.#files.ensureExecution(actual.phase === 'initializing');
+            business = new this.DatabaseSync(this.#files.execution);
+            configure(business, this.#busy);
+            initializeBusiness(authority, business, this.#files, actual);
+            authority.exec('COMMIT');
+            held = false;
+            this.#files.sync();
+            // The lifetime lock begins only after all bootstrap writes settle. No SQL on authority
+            // during the awaited callback, so business commits cannot end its private transaction.
+            authority.exec('BEGIN IMMEDIATE');
+            held = true;
+            this.#files.verify();
+            return await callback(business);
+        }
+        finally {
+            try {
+                business?.close();
+            }
+            finally {
+                try {
+                    if (held)
+                        authority.exec('ROLLBACK');
+                }
+                finally {
+                    authority.close();
+                }
+            }
+        }
+    }
+    async initialize(): Promise<void> { await this.#locked(async () => { }); }
+    async readExecution(executionId: string): Promise<ExecutionSnapshot | undefined> { nonempty(executionId, 'executionId'); return this.#locked(async (db) => snapshot(db, executionId)); }
+    async withExecutionClaim<T>(request: ClaimRequest, callback: (claim: ExecutionClaim, snapshot: ExecutionSnapshot) => Promise<T> | T): Promise<T> {
+        const plan = immutableDeliveryPlan(request.plan), contextHash = digest(request.contextHash, 'immutable execution context');
+        if (request.expectedRevision !== null)
+            decimal(request.expectedRevision, 'expected revision');
+        return this.#locked(async (db) => {
+            const initial = commit(db, this.#files, () => {
+                let previous = snapshot(db, plan.executionId);
+                if (previous) {
+                    if (previous.planHash !== plan.planHash || !same(previous.plan, plan) || previous.contextHash !== contextHash)
+                        throw new Error('Execution immutable identity conflict');
+                    if (previous.revision !== request.expectedRevision)
+                        throw new Error('Execution revision conflict');
+                    changes(db.prepare('UPDATE executions SET epoch=?,revision=? WHERE execution_id=? AND revision=? AND epoch=? AND active_transaction_id IS ?').run((BigInt(previous.epoch) + 1n).toString(), (BigInt(previous.revision) + 1n).toString(), plan.executionId, previous.revision, previous.epoch, previous.activeTransactionId));
+                }
+                else {
+                    if (request.expectedRevision !== null)
+                        throw new Error('Execution revision conflict');
+                    db.prepare('INSERT INTO executions VALUES(?,?,?,?,?,?,?,?,?)').run(plan.executionId, contextHash, plan.planHash, canonicalJson(plan), '1', '1', null, 0, null);
+                    for (const tx of plan.transactions)
+                        db.prepare('INSERT INTO transactions VALUES(?,?,?,?,?,?,?,?,?)').run(plan.executionId, tx.transactionId, tx.transactionIndex, 'claimed', null, null, null, null, null);
+                }
+                return snapshot(db, plan.executionId)!;
+            });
+            const session: Session = { db, live: true, accepting: true, epoch: initial.epoch, executionId: plan.executionId, pending: new Set() };
+            const claim = Object.freeze(Object.create(null)) as ExecutionClaim;
+            this.#claims.set(claim, session);
+            try {
+                return await callback(claim, initial);
+            }
+            finally {
+                session.accepting = false;
+                session.live = false;
+                // A detached verification promise may not mutate after callback settlement. Retain the lock
+                // until all already-started trusted calls settle, and consume their rejections.
+                await Promise.allSettled([...session.pending]);
+                this.#claims.delete(claim);
+            }
+        });
+    }
+    #session(claim: ExecutionClaim): Session {
+        const s = claim && typeof claim === 'object' ? this.#claims.get(claim) : undefined;
+        if (!s?.live || !s.accepting)
+            throw new Error('Invalid or revoked live execution claim');
+        return s;
+    }
+    #current(claim: ExecutionClaim, revision: string): {
+        session: Session;
+        current: ExecutionSnapshot;
+    } {
+        const session = this.#session(claim);
+        decimal(revision, 'expected revision');
+        const current = snapshot(session.db, session.executionId)!;
+        if (current.blockedReason !== null)
+            throw new Error(`Execution blocked: ${current.blockedReason}`);
+        if (current.revision !== revision || current.epoch !== session.epoch)
+            throw new Error('Execution revision/epoch conflict');
+        return { session, current };
+    }
+    #mutate(session: Session, current: ExecutionSnapshot, active: string | null, completed: number, write: () => void): ExecutionSnapshot {
+        try {
+            return commit(session.db, this.#files, () => {
+                if (!session.live || !session.accepting)
+                    throw new Error('Revoked execution claim');
+                changes(session.db.prepare('UPDATE executions SET revision=?,active_transaction_id=?,completed_count=? WHERE execution_id=? AND revision=? AND epoch=? AND active_transaction_id IS ?').run((BigInt(current.revision) + 1n).toString(), active, completed, current.executionId, current.revision, session.epoch, current.activeTransactionId));
+                write();
+                return snapshot(session.db, current.executionId)!;
+            });
+        }
+        catch (e) {
+            session.live = false;
+            throw e;
+        }
+    }
+    /** Permanent fail-closed marker after a trusted verifier detects lost finalized progress. */
+    blockExecution(claim: ExecutionClaim, revision: string, reason: string): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision);
+        nonempty(reason, 'execution block reason');
+        return this.#mutate(session, current, current.activeTransactionId, current.completedCount, () => {
+            changes(session.db.prepare('UPDATE executions SET blocked_reason=? WHERE execution_id=? AND blocked_reason IS NULL').run(reason, current.executionId));
+        });
+    }
+    freezeAndReserve(claim: ExecutionClaim, revision: string, transactionId: string, raw: unknown): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision), tx = current.transactions[current.completedCount];
+        if (!tx || transactionId !== tx.transactionId || (current.activeTransactionId !== null && current.activeTransactionId !== transactionId))
+            throw new Error('Only the active contiguous-prefix transaction may freeze');
+        const unsigned = parseUnsigned(raw, current.plan, tx.index), unsignedDigest = unsignedHash(unsigned);
+        if (tx.unsigned) {
+            if (!same(tx.unsigned, unsigned))
+                throw new Error('Frozen unsigned envelope conflict');
+            return current;
+        }
+        if (tx.state !== 'claimed')
+            throw new Error('Transaction is blocked from freezing');
+        const reservation = session.db.prepare('SELECT * FROM nonce_reservations WHERE chain_id=? AND signer=? AND nonce=?').get(unsigned.chainId, unsigned.signer, unsigned.nonce);
+        if (reservation)
+            throw new Error('Nonce reservation conflict');
+        return this.#mutate(session, current, transactionId, current.completedCount, () => {
+            changes(session.db.prepare('UPDATE transactions SET unsigned_json=?,unsigned_digest=? WHERE execution_id=? AND transaction_id=? AND unsigned_json IS NULL').run(canonicalJson(unsigned), unsignedDigest, current.executionId, transactionId));
+            session.db.prepare('INSERT INTO nonce_reservations VALUES(?,?,?,?,?,?)').run(unsigned.chainId, unsigned.signer, unsigned.nonce, current.executionId, transactionId, unsignedDigest);
+        });
+    }
+    markSigning(claim: ExecutionClaim, revision: string, stableRequestId: string): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision), tx = this.#active(current);
+        nonempty(stableRequestId, 'stable signing request');
+        if (tx.state !== 'claimed' || !tx.unsigned)
+            throw new Error('Signing uncertainty or existing state forbids new signing permission');
+        return this.#mutate(session, current, tx.transactionId, current.completedCount, () => { changes(session.db.prepare("UPDATE transactions SET state='signing',signing_request_id=? WHERE execution_id=? AND transaction_id=? AND state='claimed'").run(stableRequestId, current.executionId, tx.transactionId)); });
+    }
+    commitSigned(claim: ExecutionClaim, revision: string, raw: unknown): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision), tx = this.#active(current), signed = parseSigned(raw, tx.unsignedDigest ?? '');
+        if (tx.signed) {
+            if (!same(tx.signed, signed))
+                throw new Error('Original signed record conflict');
+            return current;
+        }
+        if (tx.state !== 'signing')
+            throw new Error('Signed record requires durable signing intent');
+        return this.#mutate(session, current, tx.transactionId, current.completedCount, () => { changes(session.db.prepare("UPDATE transactions SET state='signed',signed_json=? WHERE execution_id=? AND transaction_id=? AND signed_json IS NULL AND state='signing'").run(canonicalJson(signed), current.executionId, tx.transactionId)); });
+    }
+    recordSubmissionIntent(claim: ExecutionClaim, revision: string): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision), tx = this.#active(current);
+        if (!tx.signed || tx.state !== 'signed')
+            throw new Error('Submission intent requires the original signed record and is not resend permission');
+        return this.#mutate(session, current, tx.transactionId, current.completedCount, () => { changes(session.db.prepare("UPDATE transactions SET state='submission-uncertain' WHERE execution_id=? AND transaction_id=? AND state='signed'").run(current.executionId, tx.transactionId)); });
+    }
+    /** The port, not this structural store, establishes chain truth. Caller-supplied JSON alone is rejected. */
+    recordObservation(claim: ExecutionClaim, revision: string, reference: string, trusted?: TrustedObservationPort): Promise<ExecutionSnapshot> {
+        let session: Session;
+        try {
+            session = this.#session(claim);
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+        const run = async () => {
+            const { current } = this.#current(claim, revision);
+            nonempty(reference, 'observation reference');
+            if (typeof trusted?.readObservation !== 'function')
+                throw new Error('Observation requires trusted producer port');
+            const index = current.completedCount, tx = current.transactions[index];
+            if (!tx || tx.state === 'finalized-reverted' || tx.state === 'blocked')
+                throw new Error('Finalized or blocked execution cannot advance');
+            const observation = parseObservation(await trusted.readObservation(reference), current.plan, index);
+            this.#current(claim, revision);
+            if (observation.safe || current.safeEnvelopes.some(e => index >= e.start && index < e.start + e.count))
+                throw Error('Safe mapping requires atomic envelope observation');
+            if (observation.observationId !== reference)
+                throw new Error('Observation reference mismatch');
+            if (current.transactions.some((t, i) => i < index && t.observation?.transactionHash === observation.transactionHash))
+                throw new Error('Duplicate transaction hash already completed another plan entry');
+            if (tx.signed && tx.signed.transactionHash !== observation.transactionHash)
+                throw new Error('Observation differs from original signed hash');
+            if (tx.observation && same(tx.observation, observation))
+                return current;
+            const success = observation.state === 'finalized-success';
+            return this.#mutate(session, current, success ? null : tx.transactionId, index + (success ? 1 : 0), () => {
+                changes(session.db.prepare('UPDATE transactions SET state=?,observation_json=? WHERE execution_id=? AND transaction_id=?').run(observation.state, canonicalJson(observation), current.executionId, tx.transactionId));
+            });
+        };
+        const pending = run();
+        session.pending.add(pending);
+        pending.then(() => session.pending.delete(pending), () => session.pending.delete(pending));
+        return pending;
+    }
+    /** Freeze only the active original contiguous range; never replace a published nonce/envelope. */
+    freezeSafeEnvelope(claim: ExecutionClaim, revision: string, raw: unknown): ExecutionSnapshot {
+        const { session, current } = this.#current(claim, revision), e = parseSafeEnvelope(raw, current.plan), old = current.safeEnvelopes.find(x => x.start === e.start);
+        if (old) {
+            if (!same(old, e))
+                throw Error('Frozen Safe envelope conflict');
+            return current;
+        }
+        if (e.start !== current.completedCount || current.transactions.slice(e.start, e.start + e.count).some(t => t.state !== 'claimed' || t.unsigned || t.signed || t.observation) || current.safeEnvelopes.some(x => e.start < x.start + x.count && x.start < e.start + e.count))
+            throw Error('Only active pristine Safe range may freeze');
+        return this.#mutate(session, current, current.activeTransactionId, current.completedCount, () => { session.db.prepare('INSERT INTO safe_envelopes VALUES(?,?,?,?,?,?,?,?)').run(current.executionId, e.envelopeId, e.start, canonicalJson(e), e.chainId, e.safe, e.nonce, null); });
+    }
+    /** The complete batch is verified before one SQL commit; pending/reverted batches never map a prefix. */
+    recordSafeObservations(claim: ExecutionClaim, revision: string, envelopeId: string, trusted?: {
+        readSafeObservations(id: string): Promise<TransactionObservation[] | undefined>;
+    }): Promise<ExecutionSnapshot> {
+        let session: Session;
+        try {
+            session = this.#session(claim);
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+        const run = async () => {
+            const { current } = this.#current(claim, revision), e = current.safeEnvelopes.find(e => e.envelopeId === envelopeId);
+            if (!e || e.start !== current.completedCount || typeof trusted?.readSafeObservations !== 'function')
+                throw Error('Active frozen Safe envelope and trusted observer required');
+            const raw = await trusted.readSafeObservations(envelopeId);
+            this.#current(claim, revision);
+            if (!Array.isArray(raw) || raw.length !== e.count)
+                throw Error('Incomplete Safe batch observation');
+            const observations = raw.map((o, i) => parseObservation(o, current.plan, e.start + i)), first = observations[0];
+            if (observations.some((o, i) => !o.safe || o.safe.envelopeId !== e.envelopeId || o.safe.innerCallIndex !== i || o.safe.transactionIndex !== first.safe?.transactionIndex || o.transactionHash !== first.transactionHash || o.blockHash !== first.blockHash || o.blockNumber !== first.blockNumber || o.state !== first.state || o.observationId !== `${e.envelopeId}@${o.transactionHash}/${i}`))
+                throw Error('Safe atomic batch identity mismatch');
+            if (current.transactions.some(t => t.observation?.transactionHash === first.transactionHash))
+                throw Error('Safe outer hash already consumed');
+            if (current.transactions.slice(e.start, e.start + e.count).some(t => t.state !== 'claimed' || t.unsigned || t.signed || t.observation))
+                throw Error('Safe range has existing independent effects');
+            if (first.state !== 'finalized-success')
+                return current;
+            return this.#mutate(session, current, null, e.start + e.count, () => { changes(session.db.prepare('UPDATE safe_envelopes SET outer_hash=? WHERE envelope_id=? AND outer_hash IS NULL').run(first.transactionHash, e.envelopeId)); for (const o of observations)
+                changes(session.db.prepare('UPDATE transactions SET state=?,observation_json=? WHERE execution_id=? AND transaction_id=?').run(o.state, canonicalJson(o), current.executionId, o.transaction.transactionId)); });
+        };
+        const pending = run();
+        session.pending.add(pending);
+        pending.then(() => session.pending.delete(pending), () => session.pending.delete(pending));
+        return pending;
+    }
+    #active(current: ExecutionSnapshot): TransactionRecord {
+        const tx = current.transactions[current.completedCount];
+        if (!tx || current.activeTransactionId !== tx.transactionId)
+            throw new Error('No active transaction');
+        return tx;
+    }
+}
+export async function openExecutionStore(options: ExecutionStoreOptions): Promise<ExecutionStore> {
+    const DatabaseSync = await sqliteConstructor();
+    const timeout = options.busyTimeoutMs ?? 0;
+    if (!Number.isSafeInteger(timeout) || timeout < 0 || timeout > 60000)
+        throw new Error('Invalid busy timeout');
+    const store = new ExecutionStore(prepareStoreFiles(options.trustedRoot), timeout, DatabaseSync);
+    await store.initialize();
+    return store;
+}

package/runtime/delivery/existing-code.ts

@@ -0,0 +1,44 @@
+/** Pure-call coverage from the accepted registration and owned compiler witness. No deployments are invented. */
+import {artifactIdentity,parseTargetManifest,hashStorageLayout} from 'gate-evm-tools/workflow';
+import {canonicalJson,semanticHash} from '../workflow/lib/canonicalData';
+import {validateContractInfo} from '../workflow/lib/deployments';
+import {validateDeploymentInfo} from '../workflow/lib/deploymentInfo';
+import {byteHash} from './materialization';
+import type {CompilerEvidence} from './compiler';
+import type {DeliveryCollection} from './planning';
+import type {ExpectedDevelopmentCode} from './check-code';
+export function requiredExistingAddresses(collection:Pick<DeliveryCollection,'verification'>&{plan:Pick<DeliveryCollection['plan'],'transactions'|'transactionBindings'>}):string[]{
+ const {plan}=collection;return [...new Set([...collection.verification.map(a=>a.address.toLowerCase()),...plan.transactionBindings.filter(b=>b.role==='call').map(b=>plan.transactions.find(t=>t.transactionId===b.transactionId)!.to.toLowerCase())])];
+}
+export function existingCodeCoverage(input:{target:string;addresses:string[];registry:unknown;metadata:unknown;compiler:CompilerEvidence;manifests:Array<{path:string;contents:string}>}){
+ const registry=validateContractInfo(input.registry)[input.target]??{},metadata=validateDeploymentInfo(input.metadata).networks[input.target]??{};
+ const effective:Record<string,Record<string,string>>={[input.target]:{}},expected:ExpectedDevelopmentCode[]=[],artifacts:ReturnType<typeof artifactIdentity>[]=[],aliases:string[]=[],manifests:Array<{file:string;hash:string;layoutHash:string;proxy:string;implementation:string}>=[];
+ const local=(name:string)=>{
+  const entries=input.compiler.artifacts.filter(a=>name.includes(':')?a.fqn===name:a.artifact.contractName===name);if(entries.length!==1)throw Error('Missing unique compiled artifact for existing code');
+  const entry=entries[0],artifact=entry.artifact,build=input.compiler.builds.find(b=>b.digest===entry.buildInfo);
+  if(semanticHash(artifact)!==entry.digest||canonicalJson(JSON.parse(entry.contents))!==canonicalJson(artifact)||!build||byteHash(build.contents)!==build.digest||!JSON.parse(build.contents).output?.contracts?.[artifact.sourceName]?.[artifact.contractName])throw Error('Existing compiled artifact/build mismatch');
+  if(typeof artifact.deployedBytecode!=='string'||!/^0x(?:[a-fA-F0-9]{2})+$/.test(artifact.deployedBytecode))throw Error('Existing compiled runtime bytecode missing');
+  return artifact;
+ };
+ const add=(key:string,contract:string,address:string)=>{if(expected.some(e=>e.key===key))throw Error('Existing code coverage key collision');const artifact=local(contract);expected.push({key,contract:artifact.contractName,address:address.toLowerCase()});const identity=artifactIdentity(artifact,'evm');if(!artifacts.some(a=>canonicalJson(a)===canonicalJson(identity)))artifacts.push(identity);};
+ for(const address of new Set(input.addresses.map(a=>a.toLowerCase()))){
+  const matches=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(matches.length!==1)throw Error('Existing code target requires unique frozen registration');
+  const [key]=matches[0],alias=key.split(':')[0],m=metadata[alias],contract=m?.actualContract??key.split(':').at(-1)!;
+  if(m&&(m.contractInfoKey!==key||m.address.toLowerCase()!==address))throw Error('Existing code metadata registration mismatch');
+  aliases.push(alias);effective[input.target][key]=address;
+  if(m?.proxyKind&&m.proxyKind!=='uups')throw Error('Unsupported existing proxy kind');
+  if(m?.proxyKind==='uups'){
+   const implementation=m.implementationAddress!.toLowerCase();add(alias,contract,implementation);add(`${alias}_Proxy`,'ERC1967Proxy',address);
+   const owned=input.manifests.flatMap(file=>{const manifest=parseTargetManifest(Buffer.from(file.contents));const proxies=manifest.proxies.filter(p=>p.address.toLowerCase()===address),impls=Object.entries(manifest.impls).filter(([,v])=>v&&[v.address,...(v.allAddresses??[])].some(a=>a.toLowerCase()===implementation));return proxies.length===1&&proxies[0].kind==='uups'&&impls.length===1?[{file:file.path,hash:byteHash(file.contents),layoutHash:hashStorageLayout(impls[0][1]!.layout),proxy:address,implementation}]:[];});
+   if(owned.length!==1)throw Error('Missing unique sealed existing UUPS manifest');manifests.push(owned[0]);
+  }else add(alias,contract,address);
+ }
+ if(!expected.length)throw Error('Empty existing code coverage');return {effective,expected,artifacts,aliases,manifests};
+}
+
+/** Called only by the owned worker while the actual compiler artifact reader is installed. */
+export async function collectExistingCodeArtifacts(input:{target:string;addresses:string[];registry:unknown;metadata:unknown;readArtifact(name:string):Promise<unknown>}){
+ const registry=validateContractInfo(input.registry)[input.target]??{},metadata=validateDeploymentInfo(input.metadata).networks[input.target]??{},names=new Set<string>();
+ for(const address of new Set(input.addresses.map(a=>a.toLowerCase()))){const entries=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(entries.length!==1)throw Error('Existing code target requires unique frozen registration');const [key]=entries[0],m=metadata[key.split(':')[0]];names.add(m?.actualContract??key.split(':').at(-1)!);if(m?.proxyKind==='uups')names.add('@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy');}
+ for(const name of names)await input.readArtifact(name);
+}

package/runtime/delivery/export.ts

@@ -0,0 +1,99 @@
+/** Independent artifact delivery: no planning, execution, chain access or filesystem effects. */
+import { canonicalJson, deepFreeze, nonempty } from '../workflow/lib/canonicalData';
+import { strictData } from './data';
+import { parseDeliveryPlan, type DeliveryPlan } from './plan';
+import { parseObservation, type TransactionObservation, type TrustedFinalizedProgressPort } from './observations';
+export type { TrustedFinalizedProgressPort, TransactionObservation } from './observations';
+export interface DeliveryExportModel {
+    version: 1;
+    schema: 'gate-delivery-export';
+    status: 'artifact-delivered';
+    /** Self-consistency is not host authorization or externally validated release readiness. */
+    plan: DeliveryPlan;
+    fullRange: {
+        start: number;
+        end: number;
+    };
+    actionableRange: {
+        start: number;
+        end: number;
+    } | null;
+    completed: TransactionObservation[];
+    dependencies: {
+        transactionId: string;
+        after: string[];
+    }[];
+}
+/** Require canonical sealed input without silently normalizing quantities, case or ordering. */
+export function immutableDeliveryPlan(raw: unknown): DeliveryPlan {
+    const data = strictData(raw, 'sealed delivery plan'), plan = parseDeliveryPlan(data);
+    if (canonicalJson(data) !== canonicalJson(plan))
+        throw new Error('Expected canonical immutable delivery plan');
+    return plan;
+}
+declare const progressBrand: unique symbol;
+export interface ValidatedDeliveryProgress {
+    readonly [progressBrand]: true;
+}
+const trustedProgress = new WeakMap<object, TransactionObservation[]>();
+const progressPlans = new WeakMap<object, string>();
+/** Explicit trusted I/O boundary, separate from formatting. Only this live result can mark completion. */
+export async function validateDeliveryProgress(input: {
+    plan: unknown;
+    completed?: readonly string[];
+    finalized?: TrustedFinalizedProgressPort;
+}): Promise<ValidatedDeliveryProgress> {
+    const plan = immutableDeliveryPlan(input.plan), references = strictData(input.completed ?? [], 'completed observation references');
+    if (!Array.isArray(references) || references.length > plan.transactions.length)
+        throw new Error('Invalid completed prefix');
+    if (references.length && typeof input.finalized?.readFinalized !== 'function')
+        throw new Error('Completed progress requires trusted finalized provenance');
+    const completed: TransactionObservation[] = [];
+    const seen = new Set<string>();
+    for (const [i, ref] of references.entries()) {
+        nonempty(ref, 'observation reference');
+        if (seen.has(ref))
+            throw new Error('Duplicate completed observation');
+        seen.add(ref);
+        const o = parseObservation(await input.finalized!.readFinalized(ref), plan, i);
+        if (o.observationId !== ref || o.state !== 'finalized-success')
+            throw new Error('Completed prefix requires verified finalized success');
+        completed.push(o);
+    }
+    const token = Object.freeze(Object.create(null)) as ValidatedDeliveryProgress;
+    trustedProgress.set(token, deepFreeze(completed));
+    progressPlans.set(token, plan.planHash);
+    return token;
+}
+/** Pure renderer. No callback, filesystem or chain access; serialized tokens convey no provenance. */
+export function renderDeliveryExport(rawPlan: unknown, progress?: ValidatedDeliveryProgress): {
+    model: DeliveryExportModel;
+    json: string;
+    markdown: string;
+} {
+    const plan = immutableDeliveryPlan(rawPlan);
+    const completed = progress === undefined ? [] : trustedProgress.get(progress);
+    if (!completed || (progress !== undefined && progressPlans.get(progress) !== plan.planHash))
+        throw new Error('Untrusted or mismatched validated progress');
+    const start = completed.length;
+    let end = start;
+    if (start < plan.transactions.length) {
+        const first = plan.transactions[start];
+        while (end < plan.transactions.length && plan.transactions[end].route === first.route && plan.transactions[end].executor === first.executor)
+            end++;
+    }
+    const model: DeliveryExportModel = deepFreeze({ version: 1, schema: 'gate-delivery-export', status: 'artifact-delivered', plan, fullRange: { start: 0, end: plan.transactions.length }, actionableRange: start === end ? null : { start, end }, completed, dependencies: plan.transactions.map((tx, i) => ({ transactionId: tx.transactionId, after: i ? [plan.transactions[i - 1].transactionId] : [] })) });
+    const json = canonicalJson(model);
+    // One complete canonical model in both formats prevents abbreviated calldata or split projections.
+    const markdown = `# Delivery calldata\n\nArtifact delivered. This export does not indicate deployment or grant execution authority.\n\nFull range: [${model.fullRange.start}, ${model.fullRange.end}).\nCurrent actionable range: ${model.actionableRange ? `[${start}, ${end})` : 'none'}. All transactions follow their predecessors.\n\n\`\`\`json\n${json}\n\`\`\`\n`;
+    return deepFreeze({ model, json, markdown });
+}
+/** Convenience wrapper: resolves trusted provenance first, then invokes the pure renderer. */
+export async function exportDelivery(input: {
+    plan: unknown;
+    completed?: readonly string[];
+    finalized?: TrustedFinalizedProgressPort;
+}) {
+    const plan = immutableDeliveryPlan(input.plan);
+    return renderDeliveryExport(plan, await validateDeliveryProgress({ ...input, plan }));
+}