gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/aggregate-inputs.ts

@@ -0,0 +1,39 @@
+/** Actual multi-root codec projections; selected task order belongs to the canonical codec. */
+import {readDeliverySource,readOwnedDeliverySource} from './source';
+import type {DeliveryRequest} from './protocol';
+import {canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
+export function openAggregateSources(input:{workspaceRoot:string;projectRoot:string;requests:readonly DeliveryRequest[]}) {
+  const read=()=>{
+    const sources=input.requests.map(request=>readOwnedDeliverySource({workspaceRoot:input.workspaceRoot,projectRoot:input.projectRoot,request}));
+    const groups=new Map<string,typeof sources>();
+    for(const source of sources){const key=source.request.sourceRef.path+'\0'+source.request.sourceRef.taskId;const group=groups.get(key)??[];group.push(source);groups.set(key,group);}
+    const definitions=[];const tasks=new Map<string,unknown>(),lanes=new Map<string,unknown>();
+    let identity:string|undefined;
+    for(const group of groups.values()){
+      const first=group[0];
+      const projection=readDeliverySource({workspaceRoot:input.workspaceRoot,projectRoot:input.projectRoot,request:first.request,
+        sourceRoots:group.map(source=>source.invocation.task.planKey)});
+      if(group.some(source=>source.observation.sha256!==projection.observation.sha256))throw new Error('Handoff changed during multi-root source capture');
+      const definition=projection.sourceDefinition;
+      const currentIdentity=canonicalJson([definition.contract,definition.schema,definition.taskId,definition.flow??null]);
+      if(identity!==undefined&&identity!==currentIdentity)throw new Error('Conflicting aggregate handoff identity');
+      identity=currentIdentity;
+      for(const [key,lane] of Object.entries(definition.lanes)){
+        if(lanes.has(key)&&canonicalJson(lanes.get(key))!==canonicalJson(lane))throw new Error('Conflicting aggregate lane definition');
+        lanes.set(key,lane);
+      }
+      // Detect conflicting duplicates across documents without sorting/reconstructing any codec task list.
+      for(const task of projection.sourceDefinition.tasks){const key=first.request.sourceRef.taskId+'\0'+task.planKey;
+        if(tasks.has(key)&&canonicalJson(tasks.get(key))!==canonicalJson(task))throw new Error('Conflicting aggregate source definition');tasks.set(key,task);
+      }
+      definitions.push({path:first.request.sourceRef.path,definition:projection.sourceDefinition});
+    }
+    return {sources,definitions:deepFreeze(definitions)};
+  };
+  const initial=read();
+  return Object.freeze({...initial,sourceDefinitionHash:semanticHash(initial.definitions),assertUnchanged(){
+    const current=read();
+    if(canonicalJson(current.definitions)!==canonicalJson(initial.definitions))throw new Error('Aggregate source definition drift');
+    for(let i=0;i<current.sources.length;i++)if(canonicalJson(current.sources[i].invocation.task.scope)!==canonicalJson(initial.sources[i].invocation.task.scope))throw new Error('Aggregate invocation drift');
+  }});
+}

package/runtime/delivery/aggregate-source.ts

@@ -0,0 +1,53 @@
+/** Package-owned EVM source read capability, using the workflow's reviewed allowlist. */
+import http from 'node:http';
+import {randomUUID} from 'node:crypto';
+import {isAllowedSourceRpcMethod} from '../workflow/lib/sourceRpcPolicy';
+import type {DeliveryRequest} from './protocol';
+import type {HardhatRuntimeEnvironment} from 'hardhat/types';
+export interface SourceHandshake {
+  version:1;session:string;epoch:string;target:string;proxyUrl:string;
+  snapshot:{version:1;sourceNetwork:string;chainId:number;blockNumber:number;blockHash:string;runner:{kind:'hardhat';version:'2.26.3'}};
+}
+export async function openOwnedSource(hre:HardhatRuntimeEnvironment,request:DeliveryRequest,session:string,epoch:string):Promise<{
+  handshake:SourceHandshake;check():Promise<void>;close():Promise<void>;
+}> {
+  if(hre.network.name!==request.network)throw new Error('Source HRE network mismatch');
+  const provider=hre.network.provider;
+  const rpc=(method:string,params:unknown[]=[])=>provider.request({method,params});
+  const chainId=Number(BigInt(await rpc('eth_chainId') as string));
+  if(!Number.isSafeInteger(chainId)||chainId!==hre.network.config.chainId)throw new Error('Source chain identity mismatch');
+  const tag=request.fork?'0x'+request.fork.blockNumber.toString(16):'latest';
+  const block=await rpc('eth_getBlockByNumber',[tag,false]) as any;
+  if(!block||!/^0x[a-fA-F0-9]{64}$/.test(block.hash)||!/^0x[\da-f]+$/i.test(block.number))throw new Error('Source pinned block unavailable');
+  const blockNumber=Number(BigInt(block.number)),blockHash=block.hash.toLowerCase();
+  if(request.fork&&(request.fork.blockNumber!==blockNumber||request.fork.blockHash.toLowerCase()!==blockHash))throw new Error('Source pinned block mismatch');
+  const token=randomUUID(),endpoint='/'+token;
+  const reply=(res:http.ServerResponse,status:number,value:unknown)=>{const body=JSON.stringify(value);res.writeHead(status,{'content-type':'application/json','content-length':Buffer.byteLength(body)});res.end(body);};
+  const forward=async(raw:any)=>{
+    const error=(code:number,message:string)=>({jsonrpc:'2.0',id:raw?.id??null,error:{code,message}});
+    if(!raw||typeof raw!=='object'||Array.isArray(raw)||raw.jsonrpc!=='2.0'||typeof raw.method!=='string'||(raw.params!==undefined&&!Array.isArray(raw.params)))return error(-32600,'Invalid JSON-RPC request');
+    if(!isAllowedSourceRpcMethod(raw.method))return error(-32601,'Source RPC method is not allowed');
+    try{return {jsonrpc:'2.0',id:raw.id??null,result:await rpc(raw.method,raw.params??[])};}catch{return error(-32000,'Source RPC request failed');}
+  };
+  const server=http.createServer(async(req,res)=>{
+    if(req.method!=='POST'||req.url!==endpoint){reply(res,404,{error:'Unknown JSON-RPC endpoint'});return;}
+    try{
+      const chunks:Buffer[]=[];let size=0;
+      for await(const chunk of req){size+=chunk.length;if(size>10*1024*1024)throw new Error();chunks.push(Buffer.from(chunk));}
+      const raw=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      reply(res,200,Array.isArray(raw)?await Promise.all(raw.map(forward)):await forward(raw));
+    }catch{reply(res,400,{error:'Invalid JSON-RPC payload'});}
+  });
+  await new Promise<void>((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  const address=server.address();if(!address||typeof address==='string')throw new Error('Source proxy did not bind');
+  return {
+    handshake:{version:1,session,epoch,target:request.network,proxyUrl:`http://127.0.0.1:${address.port}${endpoint}`,
+      snapshot:{version:1,sourceNetwork:request.network,chainId,blockNumber,blockHash,runner:{kind:'hardhat',version:'2.26.3'}}},
+    async check(){
+      if(hre.network.provider!==provider||hre.network.name!==request.network)throw new Error('Source provider changed');
+      const [chain,current]=await Promise.all([rpc('eth_chainId'),rpc('eth_getBlockByNumber',['0x'+blockNumber.toString(16),false])]) as any[];
+      if(Number(BigInt(chain))!==chainId||current?.hash?.toLowerCase()!==blockHash||Number(BigInt(current.number))!==blockNumber)throw new Error('Source pinned block drift');
+    },
+    close:()=>new Promise<void>((resolve,reject)=>{server.close(error=>error?reject(error):resolve());server.closeAllConnections();}),
+  };
+}

package/runtime/delivery/aggregate-worker.ts

@@ -0,0 +1,133 @@
+/** Fixed package entry; business modules are loaded only after the private stage command. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {parseWorkerMessage,type WorkerMessage} from './aggregate-channel';
+import {strictData} from './data';
+import {canonicalJson,deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import type {StagedDeliveryCollection,DeliveryCollection} from './planning';
+import type {DeliveryConfigurationHandle,DeliveryConfigurationEvidence} from './configuration';
+import type {DeliveryCompilerCollector,CompilerEvidence} from './compiler';
+import type {openOwnedSource} from './aggregate-source';
+
+if(!process.send||!process.connected||require.main!==module){console.error('Aggregate worker requires an owned channel');process.exit(1);}
+let state:'new'|'staging'|'staged'|'checked'|'bound'|'closed'|'failed'='new',last=0;
+let association:{session:string;epoch:string;target:string}|undefined;
+let role:'source'|'target',config:DeliveryConfigurationHandle|undefined,stage:StagedDeliveryCollection|undefined;
+let source:Awaited<ReturnType<typeof openOwnedSource>>|undefined,compiler:DeliveryCompilerCollector|undefined;
+let stagedCompiler:CompilerEvidence|undefined,finalConfiguration:DeliveryConfigurationEvidence|undefined;
+let busy=false,initial:any,contribution:any;
+let phase='protocol';
+async function cleanup(){stage?.close();config?.close();await source?.close();}
+async function dispatch(message:WorkerMessage):Promise<unknown>{
+  if(!['stage','bind'].includes(message.command)&&message.data!==null)throw new Error('Unexpected worker command data');
+  if(message.command==='stage'){
+    if(state!=='new')throw new Error('Duplicate worker stage');
+    state='staging';initial=deepFreeze(strictData(message.data)) as any;
+    exactObject(initial,initial.role==='source'?['root','workspaceRoot','projectRoot','request','role','handshakePath']:['root','workspaceRoot','projectRoot','request','role','handshake','target','params','steps','deploymentId','businessRoot','executionId','sourceDefinitionHash'],'worker stage input');
+    const {parseDeliveryRequest}=require('./protocol') as typeof import('./protocol');
+    const request=parseDeliveryRequest(initial.request);role=initial.role;
+    if(!['source','target'].includes(role)||request.network!==message.target||request.mode!=='simulate')throw new Error('Worker target mismatch');
+    const root=fs.realpathSync(process.cwd());
+    if(root!==initial.root)throw new Error('Worker root mismatch');
+    process.env.GATE_DELIVERY_CONTEXT=JSON.stringify(request);
+    process.env.HARDHAT_NETWORK=role==='source'?request.network:'hardhat';
+    if(role==='target'){
+      const handshake=initial.handshake;
+      if(handshake?.version!==1||handshake.session!==message.session||handshake.target!==message.target||handshake.snapshot.chainId!==initial.target.chainId)throw new Error('Source handshake association mismatch');
+      require('./aggregate-bootstrap').establishOwnedFork({network:request.network,chainId:initial.target.chainId,url:handshake.proxyUrl,blockNumber:handshake.snapshot.blockNumber});
+    }
+    // This is the only project loader; same original project/config/module resolution.
+    const req=createRequire(path.join(root,'package.json'));
+    phase='project-loader';req('ts-node/register');
+    const hre=req('hardhat') as typeof import('hardhat');
+    if(role==='source'){
+      const {openOwnedSource}=require('./aggregate-source') as typeof import('./aggregate-source');
+      phase='source-open';source=await openOwnedSource(hre,request,message.session,message.epoch);
+      phase='source-configuration';config=require('./configuration').openDeliveryConfiguration({workspaceRoot:initial.workspaceRoot,projectRoot:initial.projectRoot,network:request.network});
+      fs.writeFileSync(initial.handshakePath,JSON.stringify(source.handshake),{flag:'wx',mode:0o600});
+      state='staged';return {ready:true,handshake:source.handshake};
+    }
+    const {stageDeliveryPlan}=require('./planning') as typeof import('./planning');
+    const {setupSimulationFork,verifySimulationForkSnapshot}=require('../workflow/lib/simulation') as typeof import('../workflow/lib/simulation');
+    const {impersonateWorkflowSimulationSigner}=require('../workflow/lib/signer') as typeof import('../workflow/lib/signer');
+    const {WorkflowState}=require('../workflow/lib/state') as typeof import('../workflow/lib/state');
+    const {qualifyDeliveryCompiler}=require('./compiler') as typeof import('./compiler');
+    phase='fork-setup';const simulation=await setupSimulationFork(hre,request.network,{snapshotJson:JSON.stringify(initial.handshake.snapshot),sourceRpcUrl:initial.handshake.proxyUrl});
+    await verifySimulationForkSnapshot(hre,simulation);
+    const operator=(request.devSigner??request.operator)!.toLowerCase();
+    const signer=await impersonateWorkflowSimulationSigner(hre,operator);
+    phase='target-configuration';config=require('./configuration').openDeliveryConfiguration({workspaceRoot:initial.workspaceRoot,projectRoot:initial.projectRoot,network:request.network});
+    phase='compile';compiler=await qualifyDeliveryCompiler(hre);
+    const header={version:1 as const,schema:'gate-delivery-plan' as const,deploymentId:initial.deploymentId,environment:request.environment,target:request.network,
+      chainId:String(initial.target.chainId),executionId:initial.executionId,operator,sourceDefinitionHash:initial.sourceDefinitionHash,runtimeIdentity:config!.snapshot.runtime.declared};
+    const context={root,taskDir:path.join(root,initial.businessRoot),taskId:initial.deploymentId,executionId:initial.executionId,targetId:request.network,target:initial.target,targetParams:initial.params,
+      existingDeploymentPolicies:{},config:{},mode:'simulate' as const,simulation,signer,signerAddress:operator,
+      runtime:{hre,localFork:{provider:hre.network.provider,impersonate:(address:string)=>impersonateWorkflowSimulationSigner(hre,address)}},
+      state:new WorkflowState(),externalCalls:[],operatorReceipts:[],reporter:{event(){},result(){}}};
+    const identities={read:async()=>header,readSourceBlock:async(blockNumber:number)=>{
+      const rpc=async(method:string,params:unknown[])=>{
+        const response=await fetch(initial.handshake.proxyUrl,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({jsonrpc:'2.0',id:1,method,params}),signal:AbortSignal.timeout(30000)});
+        const data=await response.json() as any;if(data.error)throw new Error('Source read failed');return data.result;
+      };
+      const [chain,block]=await Promise.all([rpc('eth_chainId',[]),rpc('eth_getBlockByNumber',['0x'+blockNumber.toString(16),false])]);
+      return {chainId:BigInt(chain).toString(),blockNumber:Number(BigInt(block.number)),blockHash:block.hash};
+    }};
+    phase='planning';stage=await stageDeliveryPlan({context,header,identities,steps:initial.steps,derivationSeed:initial.executionId});
+    if(!stage.snapshot.preparations.length){
+      phase='existing-code-artifacts';
+      const {collectExistingCodeArtifacts,requiredExistingAddresses}=require('./existing-code') as typeof import('./existing-code');
+      const {fileBytes}=require('./materialization') as typeof import('./materialization');
+      await collectExistingCodeArtifacts({target:request.network,addresses:requiredExistingAddresses({plan:stage.payload,verification:stage.snapshot.verification}),registry:JSON.parse(fileBytes(root,'contractInfo.json')??'{}'),metadata:JSON.parse(fileBytes(root,'deploymentInfo.json')??'{"version":1,"networks":{}}'),readArtifact:name=>hre.artifacts.readArtifact(name)});
+    }
+    phase='staged-reread';stagedCompiler=compiler.evidence();config!.assertUnchanged();
+    contribution={compiler:stagedCompiler,custom:stage.payload.customInputClosure,payloadHash:semanticHash(stage.payload),invariantHash:stage.invariantHash,snapshot:stage.snapshot};
+    state='staged';return {ready:true,...contribution,observation:{pid:process.pid,manifestDir:process.env.MANIFEST_DEFAULT_DIR,operator,executionId:initial.executionId}};
+  }
+  if(message.command==='check'){
+    phase='barrier';await (require('./compiler-io') as typeof import('./compiler-io')).yieldCompilerIo();
+    if(state!=='staged')throw new Error('Worker check order violation');
+    if(role==='source'){await source!.check();finalConfiguration=config!.seal() as DeliveryConfigurationEvidence;state='checked';return {configuration:finalConfiguration};}
+    await stage!.assertUnchanged();
+    if(canonicalJson(compiler!.evidence())!==canonicalJson(stagedCompiler))throw new Error('Compiler contribution drift');
+    phase='configuration-seal';finalConfiguration=config!.seal() as DeliveryConfigurationEvidence;
+    state='checked';return {configuration:finalConfiguration,...contribution};
+  }
+  if(message.command==='bind'){
+    if(state!=='checked'||role!=='target')throw new Error('Worker bind order violation');
+    const input=exactObject(message.data,['inputsHash'],'binding');
+    phase='binding';const result=stage!.bind(input.inputsHash as string);
+    const {inputsHash:_,planHash:__,...payload}=result.plan;
+    if(semanticHash(payload)!==contribution.payloadHash)throw new Error('Final binding changed staged payload');
+    state='bound';return result;
+  }
+  if(message.command==='close'){
+    if(!((role==='source'&&state==='checked')||(role==='target'&&state==='bound')))throw new Error('Worker close order violation');
+    await cleanup();state='closed';return {closed:true};
+  }
+  throw new Error('Unsupported worker command');
+}
+process.on('message',async raw=>{
+  let message:WorkerMessage;
+  try{
+    message=parseWorkerMessage(raw);
+    if(busy||state==='closed'||state==='failed'||message.id!==last+1)throw new Error('Worker protocol order violation');
+    if(!association){if(message.command!=='stage')throw new Error('Worker stage required');association={session:message.session,epoch:message.epoch,target:message.target};}
+    if(message.session!==association.session||message.epoch!==association.epoch||message.target!==association.target)throw new Error('Worker protocol association mismatch');
+    last=message.id;busy=true;
+    const value=await dispatch(message);
+    process.send!({...message,data:{ok:true,value}},(error:Error|null)=>{
+      if(error){state='failed';process.exit(1);}
+      if(state==='closed'){process.disconnect();process.exit(0);}
+    });
+    busy=false;
+  }catch(error){
+    state='failed';
+    const active=association;
+
+    if(active&&process.connected)await new Promise<void>(resolve=>process.send!({version:1,...active,id:last,command:(raw as any)?.command,data:{ok:false,value:{phase}}},()=>resolve()));
+    await cleanup().catch(()=>{});process.exit(1);
+  }
+});
+process.on('disconnect',()=>{if(state!=='closed')process.exit(1);});
+process.once('SIGTERM',()=>{state='failed';void cleanup().finally(()=>process.exit(1));});

package/runtime/delivery/aggregate.ts

@@ -0,0 +1,139 @@
+/** Owned multi-target input qualification. This grants no release-ready or broadcast authority. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {openDeliveryInputs,consumeDeliveryInputParameters,type DeliveryInputEvidence} from './inputs';
+import {openAggregateSources} from './aggregate-inputs';
+import {parseDeliveryRequest,safeId,type DeliveryRequest} from './protocol';
+import {strictData} from './data';
+import {inputDigest} from './input-files';
+import {projectRoot} from './project-files';
+import {RuntimeObservation} from './configuration-runtime';
+import {OwnedWorker,OwnedWorkerFailure} from './aggregate-channel';
+import {deepFreeze,canonicalJson,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import type {DeliveryCollection} from './planning';
+import type {DeliveryConfigurationEvidence} from './configuration';
+import type {CompilerEvidence} from './compiler';
+import type {CustomInputClosure} from './custom-closure';
+export interface DeliveryAggregateOptions {
+  workspaceRoot:string;projectRoot:string;selection:'development'|'release'|'all';
+  targets:Array<{request:DeliveryRequest;executionId:string}>;
+}
+export interface DeliveryAggregate {
+  version:1;inputsHash:string;sourceDefinitionHash:string;
+  inputs:{business:DeliveryInputEvidence;sourceDefinitions:unknown;runtime:ReturnType<RuntimeObservation['observe']>;
+    targets:Array<{target:string;configuration:DeliveryConfigurationEvidence;sourceConfiguration:DeliveryConfigurationEvidence;compiler:CompilerEvidence;custom:CustomInputClosure|null}>;
+    files:Array<{path:string;digest:string}>};
+  collections:DeliveryCollection[];
+  /** Runtime diagnostics stay outside the immutable-input preimage. */
+  observations:Array<{target:string;pid:number;sourcePid:number;manifestDir:string;operator:string;executionId:string;payloadHash:string;invariantHash:string;exited:true}>;
+}
+function same(a:unknown,b:unknown,label:string):void{if(canonicalJson(a)!==canonicalJson(b))throw new Error(`${label} drift or mismatch`);}
+/** Derives business data once; only actual worker channels can contribute staged authority. */
+class DiscoveryReplayError extends Error {}
+export async function collectDeliveryAggregate(raw:DeliveryAggregateOptions):Promise<Readonly<DeliveryAggregate>> {
+  try{return await collectOwnedAggregate(raw);}
+  catch(error){if(error instanceof OwnedWorkerFailure||error instanceof DiscoveryReplayError)throw error;throw new Error('Delivery aggregate input qualification failed');}
+}
+async function collectOwnedAggregate(raw:DeliveryAggregateOptions):Promise<Readonly<DeliveryAggregate>> {
+  const input=strictData(raw);
+  exactObject(input,['workspaceRoot','projectRoot','selection','targets'],'aggregate options');
+  if(!['development','release','all'].includes(input.selection)||!Array.isArray(input.targets)||!input.targets.length)throw new Error('Aggregate requires selected target requests');
+  const root=projectRoot(input.workspaceRoot,input.projectRoot),workspace=projectRoot(input.workspaceRoot,'.');
+  if(path.resolve(process.cwd())!==root)throw new Error('Aggregate must run from the original project root');
+  const targets=input.targets.map(value=>{
+    if(!value||Object.keys(value).some(k=>!['request','executionId','expected'].includes(k)))throw new Error('Invalid aggregate target');
+    if(Object.hasOwn(value,'expected'))throw new DiscoveryReplayError('Staged replay requires independently closed current inputs; use known-final collection');
+    const request=parseDeliveryRequest(value.request);safeId(value.executionId,'executionId');
+    if(request.mode!=='simulate'||request.purpose==='prod-execution')throw new Error('Aggregate input qualification requires simulation');
+    return {...value,request};
+  });
+  if(new Set(targets.map(x=>x.request.network)).size!==targets.length||new Set(targets.map(x=>x.executionId)).size!==targets.length)throw new Error('Aggregate target and execution IDs must be distinct');
+  // Every invocation gets its own actual environment/network/step/sourceRef validation.
+  const sourceOwner=openAggregateSources({workspaceRoot:workspace,projectRoot:input.projectRoot,requests:targets.map(x=>x.request)});
+  const {sources,definitions:sourceDefinitions,sourceDefinitionHash}=sourceOwner;
+  for(const source of sources){const scope=source.invocation.task.scope!.deployment as any,first=sources[0].invocation.task.scope!.deployment as any;
+    for(const key of ['deploymentId','developmentNetwork','releaseTargetNetworks','projectRoot'])same(scope[key],first[key],'Aggregate business scope');
+  }
+  let runtime:RuntimeObservation|undefined,business:ReturnType<typeof openDeliveryInputs>|undefined;
+  const workers:OwnedWorker[]=[];let failure:Error|undefined;
+  const session=randomUUID(),directory=fs.mkdtempSync(path.join(os.tmpdir(),'gate-delivery-aggregate-'));
+  const live=()=>{if(failure)throw failure;for(const worker of workers)worker.assertLive();};
+  const checkSources=()=>sourceOwner.assertUnchanged();
+  try{
+    runtime=new RuntimeObservation(root);
+    business=openDeliveryInputs({workspaceRoot:workspace,projectRoot:input.projectRoot,request:targets[0].request,selection:input.selection});
+    same(targets.map(x=>x.request.network),business.snapshot.targets.map(x=>x.id),'Selected target request order');
+    const receipts=targets.map(({request})=>business!.parameters(request.network));
+    const rows:any[]=[];
+    for(const [index,target] of targets.entries()){
+      live();checkSources();
+      const publicTarget=business.snapshot.targets[index];
+      if(publicTarget.environment!==target.request.environment)throw new Error('Selected request environment mismatch');
+      const common={root,workspaceRoot:workspace,projectRoot:input.projectRoot,request:target.request};
+      const source=new OwnedWorker(root,session,target.request.network,'source',error=>{failure??=error;});workers.push(source);
+      const handshakePath=path.join(directory,`${index}.json`);
+      const ready=await source.request('stage',{...common,role:'source',handshakePath});
+      if(ready.ready!==true||!fs.existsSync(handshakePath))throw new Error('Source handshake is not READY');
+      const bytes=fs.readFileSync(handshakePath,'utf8'),handshake=JSON.parse(bytes);
+      same(handshake,ready.handshake,'Source handshake');
+      if(handshake.version!==1||handshake.session!==session||handshake.epoch!==source.epoch||handshake.target!==target.request.network)throw new Error('Source handshake association mismatch');
+      const worker=new OwnedWorker(root,session,target.request.network,'target',error=>{failure??=error;});workers.push(worker);
+      const staged=await worker.request('stage',{...common,role:'target',handshake,target:publicTarget,params:business.values(publicTarget.id),steps:business.snapshot.steps,
+        deploymentId:business.snapshot.deploymentId,businessRoot:business.snapshot.businessRoot,executionId:target.executionId,sourceDefinitionHash});
+      if(staged.ready!==true)throw new Error('Target stage is not READY');
+      rows.push({target:publicTarget.id,source,worker,staged});
+    }
+    // Producer/evaluation ports terminate before the final union. No producer runs below this point.
+    checkSources();const sealed=business.seal() as DeliveryInputEvidence;
+    for(const [index,receipt] of receipts.entries())same(consumeDeliveryInputParameters(receipt),sealed.parameters[index].resolved.values,'Owned parameter receipt');
+    const contributions:DeliveryAggregate['inputs']['targets']=[];
+    for(const row of rows){
+      live();
+      const checked=await row.worker.request('check');
+      same(checked.compiler,row.staged.compiler,'Compiler stage');same(checked.custom,row.staged.custom,'Target custom closure');same(checked.payloadHash,row.staged.payloadHash,'Staged payload');same(checked.invariantHash,row.staged.invariantHash,'Staged invariant');
+      const sourceChecked=await row.source.request('check');
+      contributions.push({target:row.target,configuration:checked.configuration,sourceConfiguration:sourceChecked.configuration,compiler:checked.compiler,custom:checked.custom});
+    }
+    checkSources();runtime.assertUnchanged();const parentRuntime=runtime.observe();
+    const files=new Map<string,string>();
+    const add=(path:string,digest:string)=>{if(files.has(path)&&files.get(path)!==digest)throw new Error('Conflicting aggregate immutable input');files.set(path,digest);};
+    for(const file of sealed.files)add(file.path,file.digest);
+    for(const parameter of sealed.parameters)for(const file of parameter.closure?.files??[])add(file.path,file.digest);
+    for(const row of contributions){
+      for(const file of row.custom?.files??[])add(file.path,file.digest);
+      for(const artifact of row.compiler.artifacts){add(artifact.path,inputDigest(artifact.contents));add(artifact.debugPath,inputDigest(artifact.debugContents));}
+      for(const build of row.compiler.builds)add(build.path,inputDigest(build.contents));
+      for(const job of row.compiler.jobs)for(const file of job.sources)add(file.path,file.digest);
+      for(const file of row.compiler.toolchain.modules)add(file.path,file.digest);
+      for(const config of [row.configuration,row.sourceConfiguration]){
+        for(const file of config.files)add(file.path,file.digest);
+        for(const file of config.runtime.modules)add(file.path,file.digest);
+        for(const pkg of [config.runtime.package,...config.runtime.dependencies])for(const file of pkg.payload)add(`${pkg.lockLocation}/${file.path}`,file.digest);
+      }
+    }
+    const union=[...files].sort(([a],[b])=>a.localeCompare(b,'en')).map(([path,digest])=>({path,digest}));
+    // No runtime state, observation, plan hash or randomized compiler exact evidence enters this preimage.
+    const inputsHash=semanticHash({version:1,business:sealed,sourceDefinitions,runtime:parentRuntime,files:union,
+      targets:contributions.map(row=>({target:row.target,configuration:row.configuration.configurationRuntimeHash,sourceConfiguration:row.sourceConfiguration.configurationRuntimeHash,compiler:row.compiler.stableDigest,custom:row.custom}))});
+    live();
+    const collections:DeliveryCollection[]=[];
+    for(const row of rows){
+      const collection=await row.worker.request('bind',{inputsHash}) as DeliveryCollection;
+      if(collection.plan.inputsHash!==inputsHash||collection.plan.sourceDefinitionHash!==sourceDefinitionHash)throw new Error('Final target identity mismatch');
+      const {inputsHash:_,planHash:__,...payload}=collection.plan;
+      same(semanticHash(payload),row.staged.payloadHash,'Final staged payload');collections.push(collection);
+    }
+    // No externally reachable plan exists until every actual child has exited successfully.
+    for(const row of rows){if(failure)throw failure;await row.worker.request('close');await row.source.request('close');}
+    if(failure)throw failure;
+    return deepFreeze({version:1,inputsHash,sourceDefinitionHash,inputs:{business:sealed,sourceDefinitions,runtime:parentRuntime,targets:contributions,files:union},collections,
+      observations:rows.map(row=>({target:row.target,...row.staged.observation,sourcePid:row.source.pid,payloadHash:row.staged.payloadHash,invariantHash:row.staged.invariantHash,exited:true}))}) as DeliveryAggregate;
+  }finally{
+    business?.close();runtime?.close();
+    const results=await Promise.allSettled(workers.map(worker=>worker.reap()));
+    fs.rmSync(directory,{recursive:true,force:true});
+    if(results.some(x=>x.status==='rejected'))throw new Error('Aggregate worker cleanup failed');
+  }
+}

package/runtime/delivery/bindings.ts

@@ -0,0 +1,37 @@
+import type { ExecutionBindings } from '../workflow/lib/context';
+import { canonicalData, exactObject, nonempty, deepFreeze } from '../workflow/lib/canonicalData';
+export interface DerivedBindings { executionId: string; derivationSeed: string; values: Record<string, string> }
+export function parseDerivedBindings(raw: unknown): DerivedBindings {
+  const input = exactObject(raw, ['executionId', 'derivationSeed', 'values'], 'derived bindings');
+  const values = canonicalData(input.values) as Record<string, unknown>;
+  if (!values || typeof values !== 'object' || Array.isArray(values)) throw new Error('derived values must be an object');
+  for (const [key, value] of Object.entries(values)) { nonempty(key, 'derived key'); nonempty(value, 'derived value'); }
+  return deepFreeze({ executionId: nonempty(input.executionId, 'executionId'), derivationSeed: nonempty(input.derivationSeed, 'derivationSeed'), values: values as Record<string, string> });
+}
+export class DeliveryExecutionBindings implements ExecutionBindings {
+  readonly derivationSeed: string;
+  private readonly executionId: string;
+  private readonly expected?: DerivedBindings;
+  private readonly values: Record<string, string> = Object.create(null);
+  private sealed = false;
+  constructor(input: { executionId: string; derivationSeed: string; expected?: DerivedBindings }) {
+    this.executionId = nonempty(input.executionId, 'executionId'); this.derivationSeed = nonempty(input.derivationSeed, 'derivationSeed');
+    this.expected = input.expected && parseDerivedBindings(input.expected);
+    if (this.expected && (this.expected.executionId !== this.executionId || this.expected.derivationSeed !== this.derivationSeed)) throw new Error('derived binding identity mismatch');
+  }
+  recordOrAssertDerivedValue(key: string, value: string): void {
+    if (this.sealed) throw new Error('derived bindings are sealed');
+    nonempty(key, 'derived key'); nonempty(value, 'derived value');
+    if (Object.hasOwn(this.values, key)) throw new Error(`duplicate derived binding ${key}`);
+    if (this.expected) {
+      if (!Object.hasOwn(this.expected.values, key)) throw new Error(`unexpected derived binding ${key}`);
+      if (this.expected.values[key] !== value) throw new Error(`derived binding ${key} differs`);
+    }
+    this.values[key] = value;
+  }
+  seal(): DerivedBindings {
+    if (this.expected && Object.keys(this.expected.values).some(key => !Object.hasOwn(this.values, key))) throw new Error('missing expected derived bindings');
+    this.sealed = true;
+    return parseDerivedBindings({ executionId: this.executionId, derivationSeed: this.derivationSeed, values: this.values });
+  }
+}

package/runtime/delivery/check-code.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {canonicalData,canonicalJson} from '../workflow/lib/canonicalData';
+import {byteHash,developmentPath,atomicDevelopmentWrite} from './materialization';
+export interface ExpectedDevelopmentCode {key:string;contract:string;address:string}
+/** The checker incrementally merges output. A fresh private output file is mandatory. */
+export function validateDevelopmentCheckReport(raw:unknown,target:string,expected:readonly ExpectedDevelopmentCode[]):unknown {
+ const value=canonicalData(raw) as any;
+ if(!expected.length||new Set(expected.map(e=>e.key)).size!==expected.length)throw Error('Empty expected CheckCode set or key collision');
+ if(!value||Array.isArray(value)||canonicalJson(Object.keys(value))!==canonicalJson([target]))throw Error('CheckCode target mismatch');
+ const entries=value[target];if(!entries||Array.isArray(entries)||canonicalJson(Object.keys(entries).sort())!==canonicalJson(expected.map(e=>e.key).sort()))throw Error('CheckCode missing/extra entries');
+ for(const e of expected){const row=entries[e.key];if(!row||row.contract!==e.contract||row.scheme!=='evm'||typeof row.address!=='string'||row.address.toLowerCase()!==e.address.toLowerCase()||row.matches!==true||row.error!==null||typeof row.reason!=='string'||!Number.isSafeInteger(row.onChainBytecodeLength)||row.onChainBytecodeLength<=0||!Number.isSafeInteger(row.localBytecodeLength)||row.localBytecodeLength<=0)throw Error(`CheckCode identity/match failure: ${e.key}`);}
+ return value;
+}
+function command(root:string,cmd:string,args:string[],env:NodeJS.ProcessEnv,log:string):Promise<void> {
+ return new Promise((resolve,reject)=>{const output=fs.createWriteStream(log,{flags:'wx',mode:0o600});const child=spawn(cmd,args,{cwd:root,env,stdio:['ignore','pipe','pipe']});child.stdout.pipe(output,{end:false});child.stderr.pipe(output,{end:false});child.on('error',error=>{output.end();reject(error);});child.on('close',code=>{output.end(()=>code===0?resolve():reject(Error(`CheckCode command failed (${code}): ${cmd}; see ${log}`)));});});
+}
+export async function runDevelopmentCheckCode(input:{root:string;target:string;executionId:string;planHash:string;manifestDir:string;registry:string;metadata:string;effective:Record<string,Record<string,string>>;expected:ExpectedDevelopmentCode[];assertArtifacts:()=>Promise<unknown>}):Promise<unknown> {
+ const relative=`.gate-delivery/check-code/${input.executionId}/${randomUUID()}`,directory=developmentPath(input.root,relative);fs.mkdirSync(directory,{recursive:true,mode:0o700});
+ const effective=canonicalJson(input.effective)+'\n';atomicDevelopmentWrite(input.root,`${relative}/effective.json`,effective);
+ const raw=path.join(directory,`${input.target}.raw.json`),env:NodeJS.ProcessEnv={...process.env,HARDHAT_NETWORK:input.target,GATE_WORKFLOW_TARGET:input.target,MANIFEST_DEFAULT_DIR:input.manifestDir};
+ // Configuration's runtime loader selects the actual named target, never a fork.
+ delete env.GATE_DELIVERY_CONTEXT;
+ const snapshot=async()=>{
+  if(fs.readFileSync(path.join(input.root,'contractInfo.json'),'utf8')!==input.registry||fs.readFileSync(path.join(input.root,'deploymentInfo.json'),'utf8')!==input.metadata)throw Error('Registry/metadata changed during CheckCode');
+  return await input.assertArtifacts();
+ };
+ await snapshot();await command(input.root,'npm',['run','compile','--','--network',input.target],env,path.join(directory,'compile.log'));await snapshot();
+ if(fs.existsSync(raw))throw Error('CheckCode raw output must be fresh');
+ await command(input.root,process.execPath,[path.join(input.root,'node_modules/gate-evm-tools/bin/cli.js'),'check','--scheme','evm','--network',input.target,'--config',path.join(directory,'effective.json'),'--output',raw],env,path.join(directory,'check.log'));
+ const artifacts=await snapshot();
+ if(!fs.existsSync(raw))throw Error('CheckCode completed without raw output');
+ const stat=fs.lstatSync(raw);if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)throw Error('Invalid CheckCode raw output');
+ const bytes=fs.readFileSync(raw);validateDevelopmentCheckReport(JSON.parse(bytes.toString('utf8')),input.target,input.expected);
+ return {version:1,executionId:input.executionId,planHash:input.planHash,target:input.target,rawFile:`${relative}/${input.target}.raw.json`,rawHash:byteHash(bytes),registryHash:byteHash(input.registry),metadataHash:byteHash(input.metadata),effectiveHash:byteHash(effective),artifacts};
+}