gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/production-finalization.ts

@@ -0,0 +1,172 @@
+/** Static production acceptance. No project module, HRE, compiler process or signing port is loaded. */
+import path from 'node:path';
+import {getCreate2Address,Interface} from 'ethers';
+import {withDefaults} from '@openzeppelin/hardhat-upgrades/dist/utils/options';
+import {BytecodeChecker,artifactIdentity,hashStorageLayout,mergeEvmManifestCandidate,parseTargetManifest,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
+import {canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
+import {validateContractInfo,resolveDeployment} from '../workflow/lib/deployments';
+import {validateDeploymentInfo} from '../workflow/lib/deploymentInfo';
+import {mergeDevelopmentRegistration} from './development';
+import {parsePreparationJournal} from './journal';
+import {validateDevelopmentCheckReport,type ExpectedDevelopmentCode} from './check-code';
+import {atomicDevelopmentWrite,byteHash,fileBytes,readDevelopmentJournal,withDevelopmentFileLock,commitDevelopmentFilesLocked,type DevelopmentFile} from './materialization';
+import type {CompilerEvidence} from './compiler';
+import type {DeliveryCollection} from './planning';
+import type {EoaExecutionOptions} from './eoa';
+import {parseObservation} from './observations';
+export interface ProductionFinalizationInputs {compiler:CompilerEvidence;registration:{registry:unknown;metadata:unknown};manifests?:Array<{path:string;contents:string|null}>}
+export interface ProductionFinalizationReady {plan:DeliveryCollection['plan'];collection:DeliveryCollection;artifactHash:string;releaseHash:string;finalization?:ProductionFinalizationInputs}
+export interface FinalizedAnchor {hash:string;number:string;timestamp:string}
+const json=(v:unknown)=>canonicalJson(v)+'\n';
+const same=(a:unknown,b:unknown,label:string)=>{if(canonicalJson(a)!==canonicalJson(b))throw Error(`${label} mismatch`);};
+const slot='0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc';
+const recordPath=(r:ProductionFinalizationReady)=>`scripts/tasks/${r.plan.deploymentId}/results/${r.plan.target}/${r.plan.executionId}/deployment.json`;
+function identity(r:ProductionFinalizationReady){return semanticHash({protocol:'static-production-finalizer@1',executionId:r.plan.executionId,planHash:r.plan.planHash,releaseHash:r.releaseHash,artifactHash:r.artifactHash});}
+/** A file retry uses the original canonical state anchor, never a new business execution. */
+export function retainedProductionFinalizationAnchor(root:string,ready:ProductionFinalizationReady):FinalizedAnchor|undefined {
+ const journal=readDevelopmentJournal(root,ready.plan.executionId);if(!journal)return;
+ if(journal.identity!==identity(ready))throw Error('Production finalization identity conflict');
+ const record=journal.files.find((f:any)=>f.path===recordPath(ready));if(!record)throw Error('Production finalization record missing');
+ const value=JSON.parse(record.after);if(value.identity!==journal.identity||value.planHash!==ready.plan.planHash||value.releaseHash!==ready.releaseHash)throw Error('Production finalization record conflict');
+ return value.anchor;
+}
+export async function finalizeProductionExecution(input:{root:string;ready:ProductionFinalizationReady;provider:EoaExecutionOptions['provider'];anchor:FinalizedAnchor;finalized:unknown[];assertions:unknown[];assertCurrent():void;assertInputs():void}){
+ const {root,ready,provider,anchor}=input,{plan}=ready,configuration=ready.finalization;
+ if(!configuration)throw Error('Production finalization inputs missing; explicit recovery required');
+ if(!/^0x[0-9a-fA-F]{64}$/.test(anchor.hash)||!/^0x[0-9a-fA-F]+$/.test(anchor.number)||!/^0x[0-9a-fA-F]+$/.test(anchor.timestamp)||input.finalized.length!==plan.transactions.length||!input.finalized.length)throw Error('Incomplete production finalized evidence');
+ const rpc=async(method:string,params:readonly unknown[])=>{input.assertCurrent();const result=await provider.request(method,params);input.assertCurrent();return result;};
+ const block={blockHash:anchor.hash,requireCanonical:true};
+ const finalized=input.finalized.map((o,i)=>parseObservation(o,plan,i));
+ if(finalized.some(o=>o.state!=='finalized-success'||BigInt(o.blockNumber!)>BigInt(anchor.number)))throw Error('Production anchor precedes finalized execution');
+ if(BigInt(await rpc('eth_chainId',[]) as string).toString()!==plan.chainId)throw Error('Production finalization chain mismatch');
+ const finalBlock:any=await rpc('eth_getBlockByNumber',['finalized',false]);if(!finalBlock?.number||BigInt(finalBlock.number)<BigInt(anchor.number))throw Error('Production code anchor is not finalized');
+ const assertAnchor=async()=>{const current:any=await rpc('eth_getBlockByNumber',[anchor.number,false]);if(current?.hash!==anchor.hash)throw Error('Production finalization anchor changed');};
+ await assertAnchor();
+ const preparations=parsePreparationJournal(ready.collection.preparations,plan.transactions,plan.derivedBindings,{target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(b=>b.stepId)});
+ const compiler=configuration.compiler,base={registry:validateContractInfo(configuration.registration.registry),metadata:validateDeploymentInfo(configuration.registration.metadata)};
+ // Only pure comparison/report methods are used. No HRE object or filesystem artifact loader exists.
+ const checker=new BytecodeChecker(undefined as never,{},'evm');
+ function local(name:string){
+  const matches=compiler.artifacts.filter(a=>name.includes(':')?a.fqn===name:a.artifact.contractName===name);
+  if(matches.length!==1)throw Error(`Missing unique sealed compiler artifact: ${name}`);
+  const entry=matches[0],artifact=entry.artifact,build=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)throw Error('Sealed compiler artifact/build mismatch');
+  const output=JSON.parse(build.contents).output?.contracts?.[artifact.sourceName]?.[artifact.contractName];if(!output)throw Error('Missing sealed compiler output');
+  return {entry,artifact,immutableReferences:output.evm?.deployedBytecode?.immutableReferences??{}};
+ }
+ async function compare(address:string,name:string,key:string){
+  const compiled=local(name),code=await rpc('eth_getCode',[address,block]);
+  if(typeof code!=='string'||!/^0x(?:[0-9a-fA-F]{2})+$/.test(code))throw Error(`Production code missing: ${key}`);
+  const localCode=compiled.artifact.deployedBytecode;if(typeof localCode!=='string'||!/^0x(?:[0-9a-fA-F]{2})+$/.test(localCode))throw Error('Missing sealed runtime bytecode');
+  const comparison=checker.compareBytecode(code,localCode,compiled.artifact.abi as any[],compiled.immutableReferences);
+  if(!comparison.matches)throw Error(`Production CheckCode mismatch: ${key}: ${comparison.reason}`);
+  return {contract:compiled.artifact.contractName,contractName:key,network:plan.target,scheme:'evm',address:address.toLowerCase(),matches:true,error:null,reason:comparison.reason,onChainBytecodeLength:code.length,localBytecodeLength:localCode.length,onChainBytecodeHash:byteHash(code),localBytecodeHash:byteHash(localCode),onChainBytecodeHashNormalized:byteHash(checker.normalizeBytecode(code)),localBytecodeHashNormalized:byteHash(checker.normalizeBytecode(localCode))};
+ }
+ const changes=new Map<string,any>();
+ for(const entry of preparations){
+  const p=entry.prepared.plan,r=entry.prepared.request;const compiled=local(p.contract);same(artifactIdentity(compiled.artifact,'evm'),p.artifact,'Prepared sealed artifact');
+  for(const deployment of p.deployments){
+   if(deployment.initCodeHash&&getCreate2Address(r.factory,deployment.salt,deployment.initCodeHash).toLowerCase()!==deployment.address.toLowerCase())throw Error('Production CREATE2 address mismatch');
+   await compare(deployment.address,deployment.role==='proxy'?'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy':p.contract,`${entry.change.instanceId}:${deployment.role}`);
+  }
+  const address=p.deployments.find(d=>d.role==='proxy')?.address??('proxy' in r?r.proxy:p.deployments.find(d=>d.role==='contract')?.address);
+  if(!address)throw Error('Production prepared address missing');
+  changes.set(entry.change.instanceId,{...entry.change,address,...(p.proxyKind==='uups'?{proxyAddress:address,proxyKind:'uups'}:{})});
+ }
+ const candidates:any[]=[],expected:ExpectedDevelopmentCode[]=[],effective:Record<string,Record<string,string>>={[plan.target]:{}},checked=new Map<string,{address:string;contract:string;key:string}>();
+ function expect(address:string,contract:string,key:string){const row={key,contract,address:address.toLowerCase()},old=checked.get(key);if(old)same(old,row,'Production CheckCode key');else{checked.set(key,row);expected.push(row);}}
+ const deployed=[...changes.values()],unchangedAliases=new Set<string>();
+ const registrationContext={base,target:plan.target,deploymentId:plan.deploymentId,executionId:plan.executionId,recordPath:recordPath(ready),updatedAt:new Date(Number(BigInt(anchor.timestamp))*1000).toISOString(),changes:deployed,preparations};
+ // Apply the same validated upgrade replacement before resolving code coverage.
+ const candidate=mergeDevelopmentRegistration({...base,...registrationContext}),registry=candidate.registry[plan.target],metadata=candidate.metadata.networks[plan.target];
+ const requiredAddresses=new Set([...deployed.map(c=>c.address.toLowerCase()),...ready.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())]);
+ for(const address of requiredAddresses){
+  const rows=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(rows.length!==1)throw Error('Production code target requires unique frozen registration');
+  const [key]=rows[0],alias=key.split(':')[0],m=metadata[alias],contract=m?.actualContract??key.split(':').at(-1)!;
+  effective[plan.target][key]=address;if(!changes.has(alias))unchangedAliases.add(alias);
+  if(m?.proxyKind&&m.proxyKind!=='uups')throw Error('Unsupported production proxy kind');
+  if(m?.proxyKind==='uups'){
+   const storage=await rpc('eth_getStorageAt',[address,slot,block]);if(typeof storage!=='string'||!/^0x0{24}[a-fA-F0-9]{40}$/.test(storage))throw Error('Invalid finalized UUPS implementation slot');
+   const implementation='0x'+storage.slice(-40).toLowerCase();if(implementation!==m.implementationAddress?.toLowerCase())throw Error('Final production UUPS implementation mismatch');
+   expect(implementation,contract,alias);expect(address,'ERC1967Proxy',`${alias}_Proxy`);
+   const artifact=local(contract).entry;
+   const paths=resolveTargetManifestPaths(root,plan.target,Number(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');
+   let versionKey:string,layout:any;
+   if(changes.has(alias)){
+    const preparation=preparations.find(p=>p.stepId===changes.get(alias).stepId&&p.change.instanceId===alias),request=preparation?.prepared.request;
+    if(!request||request.kind==='create2-deploy')throw Error('Missing UUPS preparation selection request');
+    // Match the compiler's preparationSelection identity. Canonical request data
+    // contains no undefined values; omit official optional top-level safety flags.
+    const options=Object.fromEntries(Object.entries(withDefaults({kind:'uups',constructorArgs:request.constructorArgs,...(request.unsafeAllow?{unsafeAllow:request.unsafeAllow}: {})} as Parameters<typeof withDefaults>[0])).filter(([,value])=>value!==undefined));
+    const encodedArgs=new Interface(artifact.artifact.abi).encodeDeploy(request.constructorArgs),optionsHash=semanticHash(options);
+    const selections=compiler.selections.filter(s=>s.fqn===artifact.fqn&&s.artifactDigest===artifact.digest&&s.encodedArgs===encodedArgs&&semanticHash(s.options)===optionsHash);
+    if(selections.length!==1)throw Error('Missing unique frozen OZ implementation selection');
+    const selected=selections[0];versionKey=selected.version.linkedWithoutMetadata;layout=selected.layout;if(!selected.validation)throw Error('Invalid frozen OZ validation');
+   }else{
+    // Unchanged UUPS instances retain their own sealed official registration,
+    // regardless of selections made for other instances of the same artifact.
+    const frozen=configuration.manifests?.filter(f=>f.path===manifestPath);if(frozen?.length!==1||frozen[0].contents===null)throw Error('Missing frozen existing UUPS manifest');
+    const manifest=parseTargetManifest(Buffer.from(frozen[0].contents)),proxies=manifest.proxies.filter(p=>p.address.toLowerCase()===address),implementations=Object.entries(manifest.impls).filter(([,v])=>v&&[v.address,...(v.allAddresses??[])].some(a=>a.toLowerCase()===implementation));
+    if(proxies.length!==1||proxies[0].kind!=='uups'||implementations.length!==1)throw Error('Invalid frozen existing UUPS manifest registration');
+    versionKey=implementations[0][0];layout=implementations[0][1]!.layout;
+   }
+   if(typeof versionKey!=='string'||!/^[a-f0-9]{64}$/.test(versionKey))throw Error('Invalid frozen OZ version');
+   candidates.push({path:manifestPath,proxy:address,implementation,versionKey,layout,layoutHash:hashStorageLayout(layout)});
+  }else expect(address,contract,alias);
+ }
+ if(!expected.length)throw Error('Empty production CheckCode coverage');
+ // Validate all business code before promoting any address, then check again after commit for the raw report.
+ for(const row of expected)await compare(row.address,row.contract,row.key);
+ await assertAnchor();
+ function verifyCommitted(journal:any){
+  const reg=validateContractInfo(JSON.parse(fileBytes(root,'contractInfo.json')??'{}')),meta=validateDeploymentInfo(JSON.parse(fileBytes(root,'deploymentInfo.json')??'{}'));
+  const oldReg=validateContractInfo(JSON.parse(journal.files.find((f:any)=>f.path==='contractInfo.json').after)),oldMeta=validateDeploymentInfo(JSON.parse(journal.files.find((f:any)=>f.path==='deploymentInfo.json').after));
+  for(const key of Object.keys(effective[plan.target])){const alias=key.split(':')[0];same(resolveDeployment(reg,plan.target,alias),resolveDeployment(oldReg,plan.target,alias),'Committed production registration');same(meta.networks[plan.target]?.[alias]??null,oldMeta.networks[plan.target]?.[alias]??null,'Committed production metadata');}
+  for(const f of journal.files){
+   if(['contractInfo.json','deploymentInfo.json'].includes(f.path))continue;
+   const owned=candidates.filter(c=>c.path===f.path);
+   if(!owned.length){if(fileBytes(root,f.path)!==f.after)throw Error('Committed production file changed');continue;}
+   const currentBytes=fileBytes(root,f.path);if(currentBytes===null)throw Error('Committed production manifest missing');
+   const current=parseTargetManifest(Buffer.from(currentBytes)),original=parseTargetManifest(Buffer.from(f.after));
+   for(const c of owned){
+    const proxies=current.proxies.filter(p=>p.address.toLowerCase()===c.proxy),oldProxies=original.proxies.filter(p=>p.address.toLowerCase()===c.proxy);
+    if(proxies.length!==1||oldProxies.length!==1)throw Error('Committed production manifest proxy missing or ambiguous');
+    same(proxies[0],oldProxies[0],'Committed production manifest proxy');
+    const actual=current.impls[c.versionKey],expected=original.impls[c.versionKey];
+    if(!actual||!expected)throw Error('Committed production manifest implementation missing');
+    const {allAddresses:actualAddresses,...actualEntry}=actual,{allAddresses:expectedAddresses,...expectedEntry}=expected;
+    same(actualEntry,expectedEntry,'Committed production manifest implementation');
+    const addresses=new Set([actual.address,...(actualAddresses??[])].map(a=>a.toLowerCase()));
+    if([expected.address,...(expectedAddresses??[]),c.implementation].some(a=>!addresses.has(a.toLowerCase())))throw Error('Committed production manifest address removed');
+   }
+  }
+ }
+ const executionIdentity=identity(ready),record=recordPath(ready),evidence={version:1,identity:executionIdentity,executionId:plan.executionId,planHash:plan.planHash,releaseHash:ready.releaseHash,artifactHash:ready.artifactHash,inputsHash:plan.inputsHash,sourceDefinitionHash:plan.sourceDefinitionHash,planRuntimeIdentity:plan.runtimeIdentity,finalizer:'static-production-finalizer@1',anchor,preparations,finalized,assertions:input.assertions,changes:deployed};
+ const journal=await withDevelopmentFileLock(root,async()=>{
+  input.assertInputs();const prior=readDevelopmentJournal(root,plan.executionId);
+  const currentRegistry=validateContractInfo(JSON.parse(fileBytes(root,'contractInfo.json')??'{}')),currentMetadata=validateDeploymentInfo(JSON.parse(fileBytes(root,'deploymentInfo.json')??'{"version":1,"networks":{}}'));
+  for(const alias of unchangedAliases){
+   same(resolveDeployment(currentRegistry,plan.target,alias)??null,resolveDeployment(base.registry,plan.target,alias)??null,'Unchanged production registration');
+   same(currentMetadata.networks[plan.target]?.[alias]??null,base.metadata.networks[plan.target]?.[alias]??null,'Unchanged production metadata');
+  }
+  const before=(name:string)=>prior?prior.files.find((f:any)=>f.path===name)?.before:fileBytes(root,name);
+  const registryBefore=before('contractInfo.json'),metadataBefore=before('deploymentInfo.json');
+  if(registryBefore===undefined||metadataBefore===undefined)throw Error('Production journal registry missing');
+  const merged=mergeDevelopmentRegistration({registry:JSON.parse(registryBefore??'{}'),metadata:JSON.parse(metadataBefore??'{"version":1,"networks":{}}'),...registrationContext});
+  // Keep exact original containers for pure-call plans; no unrelated metadata is invented.
+  const files:DevelopmentFile[]=[{path:record,before:before(record),after:json(evidence)},{path:'contractInfo.json',before:registryBefore,after:deployed.length?json(merged.registry):registryBefore??json(merged.registry)},{path:'deploymentInfo.json',before:metadataBefore,after:deployed.length?json(merged.metadata):metadataBefore??json(merged.metadata)}];
+  for(const c of candidates){const old=files.find(f=>f.path===c.path),bytes=old?.after??before(c.path),document=bytes===null?{manifestVersion:'3.2',impls:{},proxies:[]}:parseTargetManifest(Buffer.from(bytes));const after=json(mergeEvmManifestCandidate(document,c));if(old)old.after=after;else files.push({path:c.path,before:bytes,after});}
+  if(prior){if(prior.identity!==executionIdentity)throw Error('Production journal identity conflict');same(prior.files.map(({path,before,after}:DevelopmentFile)=>({path,before,after})),files,'Production finalization journal');if(prior.state==='committed'){verifyCommitted(prior);return prior;}}
+  else if(files[0].before!==null)throw Error('Production deployment record already exists without journal');
+  return commitDevelopmentFilesLocked({root,executionId:plan.executionId,identity:executionIdentity,files});
+ });
+ const rows=[];for(const row of expected)rows.push(await compare(row.address,row.contract,row.key));
+ const report=checker.generateNetworkContractResults(rows as any);validateDevelopmentCheckReport(report,plan.target,expected);await assertAnchor();input.assertInputs();
+ verifyCommitted(journal);
+ const reportPath=`.gate-delivery/check-code/${plan.executionId}/production.raw.json`,reportBytes=json(report),acceptancePath=`.gate-delivery/production/${plan.executionId}.acceptance.json`;
+ const acceptance={...evidence,status:'accepted',materialization:{intentHash:journal.intentHash,recordPath:record,recordHash:byteHash(json(evidence)),manifests:candidates.map(c=>({file:c.path,hash:byteHash(journal.files.find((f:any)=>f.path===c.path).after),layoutHash:c.layoutHash,proxy:c.proxy,implementation:c.implementation}))},checkCode:{version:1,executionId:plan.executionId,planHash:plan.planHash,target:plan.target,anchor,rawFile:reportPath,rawHash:byteHash(reportBytes),registryHash:byteHash(journal.files.find((f:any)=>f.path==='contractInfo.json').after),metadataHash:byteHash(journal.files.find((f:any)=>f.path==='deploymentInfo.json').after),effectiveHash:byteHash(json(effective)),expected,artifacts:compiler.artifacts.map(a=>artifactIdentity(a.artifact,'evm'))},receiptPath:acceptancePath};
+ const saved=fileBytes(root,acceptancePath);if(saved!==null){same(JSON.parse(saved),acceptance,'Production acceptance');if(fileBytes(root,reportPath)!==reportBytes)throw Error('Production CheckCode report changed');}
+ else{atomicDevelopmentWrite(root,reportPath,reportBytes);atomicDevelopmentWrite(root,acceptancePath,json(acceptance));}
+ return deepFreeze(acceptance);
+}

package/runtime/delivery/production.ts

@@ -0,0 +1,375 @@
+/** Public release-only production boundary. Host capabilities never enter JSON options. */
+import fs from 'node:fs';
+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 { 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);
+    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, 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');
+        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, 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 candidate = JSON.parse(fs.readFileSync(path.join(root, release.candidate.path), 'utf8'));
+        const expected = candidate.aggregate.inputs.targets.find((t: any) => t.target === input.target);
+        for (const [actual, wanted] of [[checked.compiler.stableDigest, expected.compiler.stableDigest], [checked.custom, 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();
+        expectedDevelopmentAssertions(collection, release.operations);
+        if (collection.plan.executionId !== input.executionId || collection.plan.operator !== input.operator.toLowerCase())
+            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 body = { schema: 'gate-delivery-production', version: 1, status: 'READY', generation: 'complete', releaseHash: current.releaseHash, collection, 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 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 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';
+export function renderProductionExport(ready: Extract<ReturnType<typeof inspectDeliveryProduction>, {
+    status: 'ready';
+}>, exported = renderDeliveryExport(ready.plan)) {
+    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 model = deepFreeze({ ...exported.model, ...(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 = canonicalJson(model);
+    const artifact = deepFreeze({ status: 'artifact-delivered' as const, model, json, markdown: `# Production calldata\n\nRelease: ${ready.releaseHash}\nExecution: ${ready.plan.executionId}\n\n\`\`\`json\n${json}\n\`\`\`\n` });
+    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,58 @@
+// 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 coreMarker(root: string): void {
+  parseCoreMarker(readFile(root, '.gate-template.json') ?? 'null');
+}
+/** Validate the same captured marker bytes whose digest is being bound. */
+export function parseCoreMarker(bytes: string | Buffer): void {
+  const marker = JSON.parse(bytes.toString());
+  if (!marker || marker.template !== 'gateflow-evm-core@1' || marker.templateVersion !== 1 || marker.profile !== 'core') throw new Error('Unsupported core 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 core generator provenance');
+  if (marker.generation.state !== 'complete') throw new Error('Core generation is pending or invalid');
+  const inputs = object(marker.generation.inputs, 'core generation provenance inputs');
+  const files = object(marker.generation.files, 'core generation provenance files');
+  const preserved = marker.generation.preserved as unknown[];
+  const optional = ['README.md', 'AGENTS.md', '.gitignore'];
+  const assets = ['package.json', 'hardhat.config.ts', 'tsconfig.json', ...optional, 'contracts/.gitkeep', 'test/.gitkeep'];
+  if (typeof inputs.projectName !== 'string' || !inputs.projectName || !Array.isArray(inputs.networks)
+    || 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 core generation provenance');
+}