gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/production.ts

@@ -0,0 +1,415 @@
+/** Public release-only production boundary. Host capabilities never enter JSON options. */
+import fs from 'node:fs';
+import {customExecutionInput} from './execution-identity';
+import {assertReleasedCalldataIntent} from './production-intent';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { resolveTargetManifestPaths } from 'gate-evm-tools/workflow';
+import { inspectDeliveryRelease } from './release';
+import { readOwnedDeliverySource } from './source';
+import { projectRoot } from './project-files';
+import { safeId, parseDeliveryRequest, type DeliveryRequest } from './protocol';
+import { strictData } from './data';
+import { parseDeliveryPlan } from './plan';
+import { OwnedWorker } from './aggregate-channel';
+import { atomicDevelopmentWrite, fileBytes, byteHash, withDevelopmentFileLock } from './materialization';
+import { canonicalJson, deepFreeze, exactObject, semanticHash } from '../workflow/lib/canonicalData';
+import { createDeliveryEoaExecution, type EoaExecutionOptions, type EoaHashReferences } from './eoa';
+import type { ReleaseGraphOptions } from './release-graph';
+import type { DeliveryCollection } from './planning';
+import { parseCalldataReviews } from './calldata-review';
+import { projectDeliveryCalls, mergeDeliveryCalls } from './public-calldata';
+import { archiveDeliveryCalls } from './calldata-archive';
+import { serializeDeliveryCalls } from './calldata-format';
+import { finalizeProductionExecution, retainedProductionFinalizationAnchor, type FinalizedAnchor } from './production-finalization';
+export { productionChildEnvironment } from './production-environment';
+export interface ProductionOptions extends ReleaseGraphOptions {
+    planKey: string;
+    rev: number;
+    target: string;
+    operator: string;
+    executionId: string;
+}
+export type ProductionCommand = 'prepare' | 'execute' | 'export-calldata' | 'reconcile' | 'verify';
+const keys = ['workspaceRoot', 'projectRoot', 'handoff', 'taskId', 'deploymentId', 'releaseRef', 'planKey', 'rev', 'target', 'operator', 'executionId'];
+const encode = (v: unknown) => canonicalJson(v) + '\n';
+const artifactPath = (id: string) => `.gate-delivery/production/${safeId(id, 'executionId')}.json`;
+function inspect(raw: ProductionOptions, command: ProductionCommand) {
+    const input = deepFreeze(strictData(raw));
+    exactObject(input, keys, 'production options');
+    safeId(input.executionId, 'executionId');
+    const mode = command === 'prepare' ? 'simulate' : command;
+    const request = parseDeliveryRequest({ version: 1, environment: 'prod', purpose: 'prod-execution', mode, network: input.target, operator: input.operator, releaseRef: input.releaseRef, sourceRef: { path: input.handoff, taskId: input.taskId, planKey: input.planKey, rev: input.rev } });
+    const release = inspectDeliveryRelease(input);
+    if (release.status === 'pending')
+        return { status: 'pending' as const, input };
+    const source = readOwnedDeliverySource({ workspaceRoot: input.workspaceRoot, projectRoot: input.projectRoot, request });
+    if ((source.invocation.task.scope!.deployment as any).deploymentId !== input.deploymentId)
+        throw Error('Production deployment mismatch');
+    const target = release.release.targets.find((t: any) => t.id === input.target);
+    if (!target)
+        throw Error('Unknown production target');
+    return { status: 'ready' as const, input, request, source, release: release.release, releaseHash: release.bundleHash, target, root: projectRoot(input.workspaceRoot, input.projectRoot) };
+}
+/** Read the marker before consuming generated output; no missing-file error while pending. */
+export function inspectDeliveryProduction(raw: ProductionOptions, command: ProductionCommand = 'prepare') {
+    const current = inspect(raw, command);
+    if (current.status === 'pending')
+        return current;
+    const bytes = fileBytes(current.root, artifactPath(current.input.executionId));
+    if (bytes === null)
+        return { status: 'pending' as const };
+    const record = JSON.parse(bytes), { artifactHash, ...body } = record;
+    if (record.schema !== 'gate-delivery-production' || record.version !== 1 || record.status !== 'READY' || record.generation !== 'complete' || semanticHash(body) !== artifactHash)
+        throw Error('Invalid production READY artifact');
+    const plan = parseDeliveryPlan(record.collection.plan);
+    parseCalldataReviews(record.collection.calldata, plan.transactions);
+    const deliveryCalls=projectDeliveryCalls({plan,calldata:record.collection.calldata,operations:current.release.operations as any[],preparations:record.collection.preparations});
+    if(canonicalJson(deliveryCalls)!==canonicalJson(record.deliveryCalls))throw Error('Frozen production public projection mismatch');
+    if (record.releaseHash !== current.releaseHash || plan.inputsHash !== current.release.inputsHash || plan.sourceDefinitionHash !== current.release.sourceDefinitionHash || plan.executionId !== current.input.executionId || plan.target !== current.input.target || plan.operator !== current.input.operator.toLowerCase() || plan.environment !== 'prod' || plan.chainId !== String(current.target.chainId))
+        throw Error('Production artifact context mismatch');
+    return deepFreeze({ status: 'ready' as const, plan, collection: record.collection as DeliveryCollection, deliveryCalls, operations: current.release.operations as any[], finalization: record.finalization, releaseHash: current.releaseHash, artifactHash, sha256: byteHash(bytes), path: artifactPath(current.input.executionId), ...(current.target.safe ? { safeTarget: current.target.safe } : {}) });
+}
+/** Instantiate the delivered business operations, never accept replacement operations or parameters. */
+export async function prepareDeliveryProduction(raw: ProductionOptions) {
+    const current = inspect(raw, 'prepare');
+    if (current.status === 'pending')
+        return { status: 'pending' as const };
+    const existing = inspectDeliveryProduction(current.input);
+    if (existing.status === 'ready')
+        return existing;
+    if (path.resolve(process.cwd()) !== current.root)
+        throw Error('Production prepare must run from actual project root');
+    const { input, request, release, root } = current, session = randomUUID(), dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gate-production-'));
+    const workers: OwnedWorker[] = [];
+    let failure: Error | undefined;
+    const check = () => { if (failure)
+        throw failure; const now = inspect(input, 'prepare'); if (now.status !== 'ready' || now.releaseHash !== current.releaseHash)
+        throw Error('Production release changed during generation'); };
+    try {
+        const source = new OwnedWorker(root, session, input.target, 'source', e => { failure ??= e; });
+        workers.push(source);
+        const common = { root, workspaceRoot: input.workspaceRoot, projectRoot: input.projectRoot, request }, handshakePath = path.join(dir, 'source.json');
+        const ready = await source.request('stage', { ...common, role: 'source', handshakePath });
+        check();
+        if (ready.ready !== true || !fs.existsSync(handshakePath) || canonicalJson(JSON.parse(fs.readFileSync(handshakePath, 'utf8'))) !== canonicalJson(ready.handshake))
+            throw Error('Source generation not READY');
+        const worker = new OwnedWorker(root, session, input.target, 'target', e => { failure ??= e; });
+        workers.push(worker);
+        const parameter = release.parameters.find((p: any) => p.target === input.target);
+        if (!parameter)
+            throw Error('Release parameters missing');
+        // Production consumes the released CREATE2 derivation, while its execution
+        // identity and durable progress remain local to this execution.
+        const candidate = JSON.parse(fs.readFileSync(path.join(root, release.candidate.path), 'utf8'));
+        const qualification = candidate.aggregate.collections.find((c: any) => c.plan.target === input.target);
+        if (!qualification) throw Error('Released target qualification missing');
+        const qualificationPlan = parseDeliveryPlan(qualification.plan);
+        if (qualificationPlan.inputsHash !== release.inputsHash || qualificationPlan.target !== input.target)
+            throw Error('Released derivation context mismatch');
+        const derivationSeed = qualificationPlan.derivedBindings.derivationSeed;
+        const staged = await worker.request('stage', { ...common, role: 'target', handshake: ready.handshake, target: current.target, params: parameter.resolved.values, steps: release.operations, deploymentId: input.deploymentId, businessRoot: `scripts/tasks/${input.deploymentId}`, executionId: input.executionId, derivationSeed, sourceDefinitionHash: release.sourceDefinitionHash });
+        check();
+        if (staged.ready !== true)
+            throw Error('Production generation not READY');
+        const checked = await worker.request('check');
+        check();
+        const sourceChecked = await source.request('check');
+        check();
+        const expected = candidate.aggregate.inputs.targets.find((t: any) => t.target === input.target);
+        for (const [actual, wanted] of [[checked.compiler.stableDigest, expected.compiler.stableDigest], [customExecutionInput(checked.custom), customExecutionInput(expected.custom)], [checked.configuration.configurationRuntimeHash, expected.configuration.configurationRuntimeHash], [sourceChecked.configuration.configurationRuntimeHash, expected.sourceConfiguration.configurationRuntimeHash]])
+            if (canonicalJson(actual) !== canonicalJson(wanted))
+                throw Error('Final simulation changed released input closure');
+        const collection = await worker.request('bind', { inputsHash: release.inputsHash }) as DeliveryCollection;
+        check();
+        assertReleasedCalldataIntent(collection, qualification);
+        expectedDevelopmentAssertions(collection, release.operations);
+        if (collection.plan.executionId !== input.executionId || collection.plan.operator !== input.operator.toLowerCase() || collection.plan.derivedBindings.derivationSeed !== derivationSeed)
+            throw Error('Final simulation context mismatch');
+        await worker.request('close');
+        await source.request('close');
+        check();
+        await withDevelopmentFileLock(root, async () => {
+            check();
+            const paths = resolveTargetManifestPaths(root, input.target, Number(collection.plan.chainId), {}), manifestPath = path.relative(root, paths.file).split(path.sep).join('/');
+            if (paths.file !== paths.fallbackFile && fileBytes(root, path.relative(root, paths.fallbackFile)) !== null)
+                throw Error('Noncanonical manifest fallback requires explicit migration');
+            const finalization = { compiler: checked.compiler, registration: { registry: JSON.parse(fileBytes(root, 'contractInfo.json') ?? '{}'), metadata: JSON.parse(fileBytes(root, 'deploymentInfo.json') ?? '{"version":1,"networks":{}}') }, manifests: [{ path: manifestPath, contents: fileBytes(root, manifestPath) }] };
+            const deliveryCalls=projectDeliveryCalls({plan:collection.plan,calldata:collection.calldata,operations:release.operations,preparations:collection.preparations});
+            const body = { schema: 'gate-delivery-production', version: 1, status: 'READY', generation: 'complete', releaseHash: current.releaseHash, collection, deliveryCalls, finalization }, record = { ...body, artifactHash: semanticHash(body) };
+            const prior = fileBytes(root, artifactPath(input.executionId));
+            if (prior !== null && prior !== encode(record))
+                throw Error('Execution ID already has immutable final simulation');
+            atomicDevelopmentWrite(root, artifactPath(input.executionId), encode(record));
+        });
+        return inspectDeliveryProduction(input);
+    }
+    finally {
+        await Promise.all(workers.map(w => w.reap()));
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+export interface ProductionHostPorts extends Omit<EoaExecutionOptions, 'plan' | 'context'> {
+    finality: EoaExecutionOptions['context']['finality'];
+    assertCurrent(): void;
+}
+/** Capture trusted callback identities once. Caller-mutable options cannot replace ports after awaits. */
+function productionPorts(host: ProductionHostPorts) {
+    const { store, signer, approval } = host;
+    return { store, finality: deepFreeze(strictData(host.finality)), guard: host.assertCurrent.bind(host), request: host.provider.request.bind(host.provider),
+        signer: signer ? { address: signer.address, sign: signer.sign.bind(signer), recover: signer.recover?.bind(signer) } : undefined,
+        approval: approval ? { withApproval: approval.withApproval.bind(approval) } : undefined };
+}
+/** Explicit commands share validation; only in-process trusted ports can sign or send. */
+export async function runDeliveryProduction(command: Exclude<ProductionCommand, 'prepare'>, raw: ProductionOptions, host?: ProductionHostPorts, detail?: {
+    unsigned?: unknown;
+    hashes?: EoaHashReferences;
+}) {
+    if (!['execute', 'export-calldata', 'reconcile', 'verify'].includes(command))
+        throw Error('Explicit production command required');
+    const ports = host ? productionPorts(host) : undefined;
+    ports?.guard();
+    const input = deepFreeze(strictData(raw)), captured = detail ? deepFreeze(strictData(detail)) : undefined, ready = inspectDeliveryProduction(input, command);
+    ports?.guard();
+    if (ready.status === 'pending')
+        return { status: 'pending' as const };
+    if (!ports) {
+        if (command === 'execute')
+            throw Error('PRODUCTION_SIGNER_UNAVAILABLE: trusted host required');
+        if (command !== 'export-calldata')
+            throw Error('Trusted host observation provider required');
+        return persistProductionExport(input,ready,renderProductionExport(ready));
+    }
+    const { guard, request, store, finality, signer, approval } = ports;
+    const check = () => { guard(); const current = inspectDeliveryProduction(input, command); if (current.status !== 'ready' || current.artifactHash !== ready.artifactHash)
+        throw Error('Production artifact changed'); guard(); };
+    const plan = ready.plan, context = { executionId: plan.executionId, planHash: plan.planHash, releaseHash: ready.releaseHash, operator: plan.operator, chainId: plan.chainId, target: plan.target, finality, policyHash: semanticHash(finality) };
+    // Read-only observations consume the immutable plan. Full release hashing belongs at effect
+    // boundaries, while the live host capability/expiry check still surrounds every RPC await.
+    const provider = { async request(method: string, params: readonly unknown[]) { const current = method === 'eth_sendRawTransaction' ? check : guard; current(); const result = await request(method, params); current(); return result; } };
+    const controlledSigner = signer ? { address: signer.address, async sign(id: string, unsigned: Parameters<typeof signer.sign>[1]) { check(); const raw = await signer.sign(id, unsigned); check(); return raw; }, ...(signer.recover ? { async recover(id: string) { check(); const raw = await signer.recover!(id); check(); return raw; } } : {}) } : undefined;
+    const controlledApproval: ProductionHostPorts['approval'] = approval ? { async withApproval<T>(snapshot: Parameters<typeof approval.withApproval>[0], work: () => Promise<T>) { check(); const result = await approval.withApproval(snapshot, async () => { check(); return work(); }); guard(); return result; } } : undefined;
+    const kernel = createDeliveryEoaExecution({ store, plan, context, provider, signer: controlledSigner, approval: controlledApproval });
+    const result = command === 'execute' ? await kernel.execute(captured?.unsigned) : command === 'export-calldata' ? await kernel.export() : await kernel.reconcile(captured?.hashes ?? {});
+    check();
+    if (command === 'export-calldata')
+        return persistProductionExport(input,ready,renderProductionExport(ready, result as Awaited<ReturnType<typeof kernel.export>>));
+    if (command === 'verify' && (result as any).status === 'complete') {
+        try {
+            const root = projectRoot(input.workspaceRoot, input.projectRoot), priorAnchor = retainedProductionFinalizationAnchor(root, ready);
+            const { assertions, anchor } = await verifyProductionAssertions(ready, provider, priorAnchor);
+            check();
+            const acceptance = await finalizeProductionExecution({ root, ready, provider, anchor, assertions, finalized: (result as any).snapshot.transactions.map((t: any) => t.observation), assertCurrent: guard, assertInputs: check });
+            check();
+            return deepFreeze({ ...(result as object), status: 'accepted', assertions, acceptance });
+        }
+        catch (error) {
+            guard();
+            return deepFreeze({ ...(result as object), status: 'finalization-required', error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return result;
+}
+import { renderDeliveryExport } from './export';
+async function persistProductionExport(input:ProductionOptions,ready:Extract<ReturnType<typeof inspectDeliveryProduction>,{status:'ready'}>,result:ReturnType<typeof renderProductionExport>){
+ const exported=result.status==='preparation-required'?result.export:result;
+ const deliveryFile=await archiveDeliveryCalls({...input,calls:JSON.parse(exported.json),provenance:{releaseRef:input.releaseRef,sources:[{planHash:ready.plan.planHash,chainId:ready.plan.chainId,artifactHash:ready.artifactHash,releaseHash:ready.releaseHash,executionId:ready.plan.executionId}]},assertCurrent(){const now=inspectDeliveryProduction(input,'export-calldata');if(now.status!=='ready'||now.artifactHash!==ready.artifactHash||now.releaseHash!==ready.releaseHash)throw Error('Production changed during calldata publication');}});
+ const artifact=deepFreeze({...exported,deliveryFile});
+ return result.status==='preparation-required'?deepFreeze({...result,export:artifact}):artifact;
+}
+
+/** Each network is validated independently before one combined immutable JSON is published. */
+export async function exportProductionCalldata(productions:readonly ProductionOptions[]){
+ if(!productions.length)throw Error('Production targets required');
+ const inputs=productions.map(p=>deepFreeze(strictData(p))),first=inputs[0];
+ for(const p of inputs)if(canonicalJson([p.workspaceRoot,p.projectRoot,p.taskId,p.deploymentId,p.releaseRef])!==canonicalJson([first.workspaceRoot,first.projectRoot,first.taskId,first.deploymentId,first.releaseRef]))throw Error('Multi-network delivery must belong to one deployment release');
+ const ready=inputs.map(input=>{const r=inspectDeliveryProduction(input,'export-calldata');if(r.status!=='ready')throw Error('Production calldata generation is pending');return r;});
+ const calls=mergeDeliveryCalls(ready.map(r=>({plan:r.plan,calldata:r.collection.calldata,operations:r.operations,preparations:r.collection.preparations})));
+ const deliveryFile=await archiveDeliveryCalls({...first,calls,provenance:{releaseRef:first.releaseRef,sources:ready.map(r=>({planHash:r.plan.planHash,chainId:r.plan.chainId,artifactHash:r.artifactHash,releaseHash:r.releaseHash,executionId:r.plan.executionId}))},assertCurrent(){inputs.forEach((input,i)=>{const now=inspectDeliveryProduction(input,'export-calldata');if(now.status!=='ready'||now.artifactHash!==ready[i].artifactHash||now.releaseHash!==ready[i].releaseHash)throw Error('Multi-network production changed during publication');});}});
+ return deepFreeze({status:'artifact-delivered' as const,json:serializeDeliveryCalls(calls),deliveryFile});
+}
+export function renderProductionExport(ready: Extract<ReturnType<typeof inspectDeliveryProduction>, {
+    status: 'ready';
+}>, exported = renderDeliveryExport(ready.plan)) {
+    if (canonicalJson(exported.model.plan) !== canonicalJson(ready.plan)) throw Error('Exported plan differs from frozen production plan');
+    const calldataReview = { version: 1, planHash: ready.plan.planHash, chainId: ready.plan.chainId,
+        transactions: parseCalldataReviews(ready.collection.calldata, ready.plan.transactions), check: 'matches-frozen-intent' };
+    const start = exported.model.completed.length, active = ready.plan.transactions[start], frozen = (exported.model as any).safeEnvelopes ?? [];
+    const needsPreparation = !!ready.safeTarget && active?.route === 'external' && !frozen.some((x: any) => x.envelope.start === start);
+    const deliveryContext = { operations: ready.operations, preparations: ready.collection.preparations };
+    const model = deepFreeze({ ...exported.model, calldataReview, deliveryContext, ...(ready.safeTarget ? { safePreparation: needsPreparation ? 'preparation-required' : active?.route === 'external' ? 'ready' : 'not-applicable', futureSafeEnvelopes: 'pending until their segment becomes executable' } : {}), releaseHash: ready.releaseHash, artifactHash: ready.artifactHash });
+    const json = serializeDeliveryCalls(projectDeliveryCalls({ plan: ready.plan, calldata: ready.collection.calldata, operations: ready.operations, preparations: ready.collection.preparations }));
+    const artifact = deepFreeze({ status: 'artifact-delivered' as const, model, json });
+    return needsPreparation ? deepFreeze({ status: 'preparation-required' as const, export: artifact }) : artifact;
+}
+import { parseConfigurationDefinition } from './configuration-definition';
+import { productionChildEnvironment } from './production-environment';
+import { rpcQuantity } from './eoa-observation';
+import { parseUnsigned } from './execution-model';
+import { SAFE_TRACE_MAX_BYTES } from './safe-observation';
+/** Static config parser only. No HRE, project imports, accounts or signing environment are evaluated. */
+export function productionRpc(raw: ProductionOptions, command: ProductionCommand) {
+    const current = inspect(raw, command);
+    if (current.status !== 'ready')
+        throw Error('Production release pending');
+    const config = parseConfigurationDefinition(fs.readFileSync(path.join(current.root, 'hardhat.config.ts')), raw.target, productionChildEnvironment(process.env)).userConfig.networks[raw.target];
+    const url = new URL(config.url);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw Error('Unsupported production RPC');
+    return Object.freeze({ async request(method: string, params: readonly unknown[]): Promise<unknown> {
+            const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 30000);
+            try {
+                const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...config.httpHeaders }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: controller.signal });
+                if (!response.ok || !response.body)
+                    throw Error('Production RPC transport failed');
+                const maxBytes = method === 'debug_traceTransaction' ? SAFE_TRACE_MAX_BYTES : 2 * 1024 * 1024;
+                const reader = response.body.getReader(), chunks: Uint8Array[] = [];
+                let size = 0;
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        size += value.byteLength;
+                        if (size > maxBytes)
+                            throw Error('Production RPC response exceeds bounded budget');
+                        chunks.push(value);
+                    }
+                } catch (error) {
+                    controller.abort();
+                    await reader.cancel().catch(() => {});
+                    throw error;
+                } finally {
+                    reader.releaseLock();
+                }
+                // Parse only after the entire bounded stream completed successfully.
+                const result = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, size)));
+                if (!result || result.error || !Object.hasOwn(result, 'result'))
+                    throw Error('Production RPC rejected request');
+                return result.result;
+            } catch (error) {
+                controller.abort();
+                throw error;
+            } finally {
+                clearTimeout(timer);
+            }
+        } });
+}
+/** Separate final preparation: policy comes only from the validated release target. No signing/send. */
+export async function prepareDeliveryProductionSafe(raw: ProductionOptions, host: ProductionHostPorts) {
+    return prepareProductionSafe(raw, host, 'prepare');
+}
+/** The owning entry fixes its stage; callers cannot select a weaker task permission. */
+async function prepareProductionSafe(raw: ProductionOptions, host: ProductionHostPorts, command: 'prepare' | 'execute') {
+    const ports = productionPorts(host);
+    ports.guard();
+    const input = deepFreeze(strictData(raw)), ready = inspectDeliveryProduction(input, command), current = inspect(input, command);
+    ports.guard();
+    if (ready.status !== 'ready' || current.status !== 'ready')
+        return { status: 'pending' as const };
+    const check = () => { ports.guard(); const now = inspectDeliveryProduction(input, command); if (now.status !== 'ready' || now.artifactHash !== ready.artifactHash)
+        throw Error('Production Safe preparation changed'); ports.guard(); };
+    const prior = await ports.store.readExecution(input.executionId);
+    ports.guard();
+    if (prior && prior.planHash !== ready.plan.planHash)
+        throw Error('Original execution plan mismatch');
+    const first = ready.plan.transactions[prior?.completedCount ?? 0];
+    if (!first || first.route !== 'external')
+        return { status: 'not-applicable' as const };
+    if (!current.target.safe) {
+        const code = await ports.request('eth_getCode', [first.executor, 'latest']);
+        check();
+        if (code !== '0x')
+            throw Error('Developer-delivered Safe target policy required');
+        return { status: 'not-applicable' as const };
+    }
+    const plan = ready.plan, context = { executionId: plan.executionId, planHash: plan.planHash, releaseHash: ready.releaseHash, operator: plan.operator, chainId: plan.chainId, target: plan.target, finality: ports.finality, policyHash: semanticHash(ports.finality) };
+    const provider = { async request(method: string, params: readonly unknown[]) { ports.guard(); const result = await ports.request(method, params); ports.guard(); return result; } };
+    const result = await createDeliveryEoaExecution({ plan, context, store: ports.store, provider }).prepareSafe(current.target.safe);
+    check();
+    return deepFreeze({ status: 'safe-prepared' as const, envelope: result.envelope });
+}
+export async function freezeDeliveryProduction(raw: ProductionOptions, host: ProductionHostPorts) {
+    const { guard, request, store, signer } = productionPorts(host);
+    guard();
+    const input = deepFreeze(strictData(raw)), ready = inspectDeliveryProduction(input, 'execute');
+    guard();
+    if (ready.status !== 'ready')
+        return { status: 'pending' as const };
+    const check = () => { guard(); const now = inspectDeliveryProduction(input, 'execute'); if (now.status !== 'ready' || now.artifactHash !== ready.artifactHash)
+        throw Error('Production snapshot context changed'); guard(); };
+    const rpc = async (method: string, params: unknown[]) => { guard(); const v = await request(method, params); guard(); return v; };
+    const s = await store.readExecution(input.executionId);
+    guard();
+    if (s && s.planHash !== ready.plan.planHash)
+        throw Error('Original execution plan mismatch');
+    const tx = ready.plan.transactions[s?.completedCount ?? 0];
+    if (!tx) {
+        check();
+        return { status: 'complete' as const };
+    }
+    if (rpcQuantity(await rpc('eth_chainId', [])) !== ready.plan.chainId)
+        throw Error('Production chain mismatch');
+    const code = await rpc('eth_getCode', [tx.executor, 'latest']);
+    if (typeof code !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(code))
+        throw Error('Unknown executor permissions');
+    if (tx.route !== 'operator') {
+        await prepareProductionSafe(input, host, 'execute');
+        return { status: 'external-executor' as const, export: await runDeliveryProduction('export-calldata', input, host) };
+    }
+    if (code !== '0x' || tx.operation !== 0)
+        throw Error('Unsupported contract executor; EOA operation 0 required');
+    if (!signer || signer.address !== input.operator.toLowerCase())
+        throw Error('PRODUCTION_SIGNER_UNAVAILABLE');
+    if (s?.transactions[s.completedCount]?.state && s.transactions[s.completedCount].state !== 'claimed')
+        return { status: 'reconcile-required' as const, executionId: input.executionId, planHash: ready.plan.planHash };
+    const unsigned = parseUnsigned({ chainId: ready.plan.chainId, signer: tx.executor, nonce: rpcQuantity(await rpc('eth_getTransactionCount', [tx.executor, 'pending'])), to: tx.to, value: tx.value, data: tx.data, operation: tx.operation, type: 0, gasLimit: rpcQuantity(await rpc('eth_estimateGas', [{ from: tx.executor, to: tx.to, data: tx.data, value: '0x' + BigInt(tx.value).toString(16) }])), gasPrice: rpcQuantity(await rpc('eth_gasPrice', [])), maxFeePerGas: null, maxPriorityFeePerGas: null, accessList: [] }, ready.plan, s?.completedCount ?? 0);
+    check();
+    return deepFreeze({ status: 'frozen' as const, releaseHash: ready.releaseHash, plan: ready.plan, artifactHash: ready.artifactHash, unsigned });
+}
+import { Interface } from 'ethers';
+import { expectedDevelopmentAssertions } from './development';
+import { parseTypedValue } from '../workflow/lib/typedValue';
+import { compareAbiResults, normalizeRuntimeValue } from './abi';
+function assertionValue(raw: any): any { const v = parseTypedValue(raw); switch (v.type) {
+    case 'bigint': return v.value;
+    case 'number': return Number(v.value);
+    case 'array': return v.value.map(assertionValue);
+    case 'object': return Object.fromEntries(Object.entries(v.value).map(([k, x]) => [k, assertionValue(x)]));
+    default: return v.value;
+} }
+async function verifyProductionAssertions(ready: Extract<ReturnType<typeof inspectDeliveryProduction>, {
+    status: 'ready';
+}>, provider: EoaExecutionOptions['provider'], priorAnchor?: FinalizedAnchor) {
+    const assertions = ready.collection.verification;
+    if (!assertions.length)
+        throw Error('Production acceptance requires business assertions');
+    for (const binding of ready.plan.verificationBindings) {
+        const rows = assertions.filter(o => o.stepId === binding.stepId);
+        if (canonicalJson(rows.map(o => o.assertionId)) !== canonicalJson(binding.assertionIds) || semanticHash(rows) !== binding.verificationHash)
+            throw Error('Frozen assertion set mismatch');
+    }
+    if (ready.plan.verificationBindings.reduce((n, b) => n + b.assertionIds.length, 0) !== assertions.length)
+        throw Error('Incomplete production assertions');
+    const finalized: any = await provider.request('eth_getBlockByNumber', ['finalized', false]);
+    if (!finalized?.hash || !finalized?.number)
+        throw Error('Finalized business state unavailable');
+    const block: any = priorAnchor ?? finalized;
+    if (BigInt(block.number) > BigInt(finalized.number))
+        throw Error('Production acceptance anchor is not finalized');
+    const results = [];
+    for (const assertion of assertions) {
+        const iface = new Interface(assertion.abi), data = iface.encodeFunctionData(assertion.method, assertionValue(assertion.args));
+        const raw = await provider.request('eth_call', [{ to: assertion.address, data }, { blockHash: block.hash, requireCanonical: true }]);
+        if (typeof raw !== 'string')
+            throw Error('Invalid assertion RPC response');
+        const decoded = iface.decodeFunctionResult(assertion.method, raw), actual = decoded.length === 1 ? decoded[0] : decoded, comparison = compareAbiResults(assertion.abi, assertion.method, actual, assertionValue(assertion.expected));
+        if (comparison.actual !== comparison.expected)
+            throw Error(`Production business assertion failed: ${assertion.assertionId}`);
+        results.push({ assertionId: assertion.assertionId, actual: normalizeRuntimeValue(actual), expected: assertion.expected, blockHash: block.hash });
+    }
+    const end: any = await provider.request('eth_getBlockByNumber', [block.number, false]);
+    if (end?.hash !== block.hash)
+        throw Error('Production assertion finality changed');
+    return { assertions: results, anchor: { hash: block.hash, number: block.number, timestamp: end.timestamp } };
+}

package/runtime/delivery/project-files.ts

@@ -0,0 +1,63 @@
+// Filesystem-only project boundary helpers; safe to use before loading config tooling.
+import fs from 'node:fs';
+import path from 'node:path';
+import { object, portablePath } from './protocol';
+
+export function stat(file: string): fs.Stats | undefined {
+  try { return fs.lstatSync(file); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+export function confinedFile(root: string, relative: string, kind: 'file' | 'directory' = 'file'): string {
+  portablePath(relative, 'project path');
+  let current = root;
+  const parts = relative.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    current = path.join(current, parts[i]);
+    const info = stat(current);
+    if (!info) continue;
+    if (info.isSymbolicLink()) throw new Error(`Unsafe symlink: ${relative}`);
+    const file = i === parts.length - 1 && kind === 'file';
+    if (file ? !info.isFile() || info.nlink !== 1 : !info.isDirectory()) throw new Error(`Unsafe path type: ${relative}`);
+  }
+  return current;
+}
+export function projectRoot(workspaceRoot: string, relative: string): string {
+  if (typeof workspaceRoot !== 'string' || !path.isAbsolute(workspaceRoot)) throw new Error('workspaceRoot path must be absolute');
+  const workspace = fs.realpathSync(workspaceRoot);
+  const root = relative === '.' ? workspace : confinedFile(workspace, relative, 'directory');
+  if (!stat(root)?.isDirectory()) throw new Error('Project path must be an existing directory');
+  return root;
+}
+export function readFile(root: string, relative: string): string | undefined {
+  const file = confinedFile(root, relative);
+  return stat(file) ? fs.readFileSync(file, 'utf8') : undefined;
+}
+export function deliveryProjectMarker(root: string): void {
+  parseDeliveryProjectMarker(readFile(root, '.gate-template.json') ?? 'null');
+}
+/** Validate the same captured marker bytes whose digest is bound to current inputs. */
+export function parseDeliveryProjectMarker(bytes: string | Buffer): void {
+  const marker = JSON.parse(bytes.toString());
+  if (!marker || marker.profile !== 'full' || marker.templateVersion !== 1
+    || marker.template !== `gateflow-evm-${marker.profile}@1`) throw new Error('Unsupported EVM template; no legacy migration is performed');
+  if (marker.generator?.name !== 'gate-evm-hardhat-foundry' || typeof marker.generator?.version !== 'string'
+    || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(marker.generator.version)
+    || !marker.generation?.inputs || !marker.generation?.files || !Array.isArray(marker.generation?.preserved)) throw new Error('Invalid EVM generator provenance');
+  if (marker.generation.state !== 'complete') throw new Error('EVM generation is pending or invalid');
+  const inputs = object(marker.generation.inputs, 'EVM generation provenance inputs', ['projectName', 'networks', 'examples']);
+  const files = object(marker.generation.files, 'EVM generation provenance files');
+  const preserved = marker.generation.preserved as unknown[];
+  const optional = ['README.md', 'AGENTS.md', '.gitignore'];
+  const assets = ['package.json', 'package-lock.json', 'hardhat.config.ts', 'rpc.env', '.env.example', 'tsconfig.json', ...optional, 'contracts/.gitkeep', 'test/.gitkeep',
+    'foundry.toml', 'config.yaml',
+    ...(Object.hasOwn(files, 'vendor/gate-evm-tools-1.2.0.tgz') ? ['vendor/gate-evm-tools-1.2.0.tgz'] : []),
+    ...(inputs.examples === true ? ['contracts/Counter.sol', 'test/Counter.ts', 'test/Counter.t.sol'] : [])];
+  if (typeof inputs.projectName !== 'string' || !inputs.projectName || !Array.isArray(inputs.networks)
+    || typeof inputs.examples !== 'boolean'
+    || preserved.some(file => typeof file !== 'string' || !optional.includes(file))
+    || new Set(preserved).size !== preserved.length
+    || Object.keys(files).sort().join('\n') !== assets.filter(file => !preserved.includes(file)).sort().join('\n')
+    || Object.values(files).some(hash => typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))) throw new Error('Invalid EVM generation provenance');
+}

package/runtime/delivery/project-rpc.ts

@@ -0,0 +1,116 @@
+/** Fixed template RPC syntax. Inspection reads local env data without evaluating project code. */
+import ts from 'typescript';
+import { parseEnv } from 'node:util';
+import { readFile } from './project-files';
+
+export const PROJECT_ENV_BOOTSTRAP = `for (const file of ["rpc.env", ".env"]) {
+  const envFile = join(__dirname, file);
+  if (existsSync(envFile)) {
+    try {
+      process.loadEnvFile(envFile);
+    } catch (error) {
+      if (file !== ".env" || !["ENOENT", "EPERM", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+      console.warn("Project credentials are unavailable; compilation and public checks can continue. Use the application host for credential-bearing delivery operations.");
+    }
+  }
+}`;
+export const PROJECT_RPC_HELPER = [
+  "function rpcUrl(options: { route: string; publicFallback: string | undefined; useBaseRpc: boolean }): string {",
+  "  const fallback = options.publicFallback?.trim() || \"\";",
+  "  const base = process.env.BASE_RPC_URI?.trim();",
+  "  if (!options.useBaseRpc || !base) return fallback;",
+  "  return `${base.replace(/\\/+$/, \"\")}/${options.route}/`;",
+  "}",
+].join('\n');
+const printer = ts.createPrinter({ removeComments: true });
+function syntax(node: ts.Node, file: ts.SourceFile): string {
+  return printer.printNode(ts.EmitHint.Unspecified, node, file);
+}
+function statement(source: string): string {
+  const file = ts.createSourceFile('rpc.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  return syntax(file.statements[0], file);
+}
+const bootstrapSyntax = statement(PROJECT_ENV_BOOTSTRAP), helperSyntax = statement(PROJECT_RPC_HELPER);
+
+export function projectRpcSyntax(file: ts.SourceFile): { statements: Set<ts.Statement>; bootstrap: boolean; helper: boolean } {
+  const statements = new Set<ts.Statement>();
+  let bootstrap = false, helper = false;
+  const imports = new Set<string>();
+  for (const node of file.statements) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)
+      && ['node:fs', 'node:path'].includes(node.moduleSpecifier.text)) {
+      const name = node.moduleSpecifier.text, clause = node.importClause;
+      const wanted = name === 'node:fs' ? 'existsSync' : 'join';
+      if (imports.has(name) || node.attributes || !clause || clause.name || clause.isTypeOnly
+        || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings)
+        || clause.namedBindings.elements.length !== 1 || clause.namedBindings.elements[0].name.text !== wanted
+        || clause.namedBindings.elements[0].propertyName) throw Error('Unsupported project RPC import');
+      imports.add(name); statements.add(node);
+    } else if (ts.isForOfStatement(node) && syntax(node, file) === bootstrapSyntax) {
+      if (bootstrap) throw Error('Duplicate project RPC loader');
+      bootstrap = true; statements.add(node);
+    } else if (ts.isFunctionDeclaration(node) && node.name?.text === 'rpcUrl') {
+      if (helper || syntax(node, file) !== helperSyntax) throw Error('Unsupported project RPC helper');
+      helper = true; statements.add(node);
+    }
+  }
+  if (bootstrap !== (imports.size === 2) || (!bootstrap && imports.size)) throw Error('Incomplete project RPC loader');
+  const config = file.statements.findIndex(node => ts.isVariableStatement(node) || ts.isExportAssignment(node));
+  if (bootstrap && config >= 0 && [...statements].some(node => ts.isForOfStatement(node) && file.statements.indexOf(node) > config))
+    throw Error('Project RPC loader must precede configuration');
+  return { statements, bootstrap, helper };
+}
+
+export function projectRpcOptions(node: ts.CallExpression): { route: string; publicFallback: ts.Expression; useBaseRpc: boolean } {
+  if (!ts.isIdentifier(node.expression) || node.expression.text !== 'rpcUrl' || node.arguments.length !== 1 || node.typeArguments)
+    throw Error('Unsupported project RPC call');
+  const options = node.arguments[0];
+  if (!ts.isObjectLiteralExpression(options)) throw Error('Unsupported project RPC options');
+  const fields = new Map<string, ts.Expression>();
+  for (const property of options.properties) {
+    if (!ts.isPropertyAssignment(property) || (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)))
+      throw Error('Unsupported project RPC option');
+    const name = property.name.text;
+    if (!['route', 'publicFallback', 'useBaseRpc'].includes(name) || fields.has(name)) throw Error('Unsupported project RPC option');
+    fields.set(name, property.initializer);
+  }
+  const route = fields.get('route'), useBaseRpc = fields.get('useBaseRpc'), publicFallback = fields.get('publicFallback');
+  if (!route || !ts.isStringLiteral(route) || !/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(route.text)) throw Error('Unsupported project RPC route');
+  if (!publicFallback || !useBaseRpc || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(useBaseRpc.kind))
+    throw Error('Project RPC requires a literal useBaseRpc boolean and publicFallback');
+  return { route: route.text, publicFallback, useBaseRpc: useBaseRpc.kind === ts.SyntaxKind.TrueKeyword };
+}
+
+export function resolveProjectRpc(route: string, publicFallback: string | undefined, useBaseRpc: boolean, env: NodeJS.ProcessEnv): string {
+  const base = env.BASE_RPC_URI?.trim();
+  return useBaseRpc && base ? `${base.replace(/\/+$/, '')}/${route}/` : publicFallback?.trim() || '';
+}
+
+function projectEnvironment(root: string, source: string, env: NodeJS.ProcessEnv, files: readonly string[]): NodeJS.ProcessEnv {
+  const file = ts.createSourceFile('hardhat.config.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  if (!projectRpcSyntax(file).bootstrap) return env;
+  const effective = { ...env };
+  for (const name of files) {
+    try {
+      const contents = readFile(root, name);
+      if (contents === undefined) continue;
+      for (const [key, value] of Object.entries(parseEnv(contents))) if (effective[key] === undefined) effective[key] = value;
+    } catch (error) {
+      if (name === '.env' && ['EPERM', 'EACCES'].includes((error as NodeJS.ErrnoException).code ?? '')) {
+        throw Error('Project credential environment is protected; run credential-bearing delivery operations through the trusted application host. Configure public RPCs in rpc.env.');
+      }
+      throw Error(`Cannot read local project RPC environment (${name})`);
+    }
+  }
+  return effective;
+}
+
+/** Static diagnostics never access the credential file, even when it is readable. */
+export function projectPublicRpcEnvironment(root: string, source: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return projectEnvironment(root, source, env, ['rpc.env']);
+}
+
+/** Actual runtime observation must retain the same environment semantics as Hardhat. */
+export function projectRpcEnvironment(root: string, source: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return projectEnvironment(root, source, env, ['rpc.env', '.env']);
+}