gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/abi.ts

@@ -0,0 +1,225 @@
+import {
+  Interface,
+  ParamType,
+  Result,
+  isAddress,
+  getAddress,
+  type InterfaceAbi,
+} from "ethers";
+import { strictData, copyOwnData } from "./data";
+import { DEFERRED } from "./references";
+/** Explicit runtime return boundary. Only bigint and ethers Result extend own JSON data. */
+export function normalizeRuntimeValue(value: unknown): unknown {
+  if (typeof value === "bigint") return value.toString(10);
+  if (value instanceof Result)
+    return value.toArray(true).map(normalizeRuntimeValue);
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype)
+      throw new Error("Invalid runtime array prototype");
+    // Check shape/descriptors before reading; bigint is deliberately normalized afterwards.
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (
+      Object.getOwnPropertySymbols(value).length ||
+      Object.keys(descriptors).length !== value.length + 1
+    )
+      throw new Error("Invalid runtime array");
+    return Array.from({ length: value.length }, (_, i) => {
+      const d = descriptors[String(i)];
+      if (!d || !d.enumerable || !("value" in d))
+        throw new Error("Invalid runtime array");
+      return normalizeRuntimeValue(d.value);
+    });
+  }
+  return strictData(value);
+}
+export function validateAbiValue(
+  type: ParamType,
+  value: unknown,
+  label = "ABI value",
+  allowDeferred = false,
+): void {
+  value = copyOwnData(value, label, allowDeferred ? DEFERRED : undefined);
+  if (value === DEFERRED && allowDeferred) return;
+  const fail = () => {
+    throw new Error(`${label} must match ABI ${type.format("sighash")}`);
+  };
+  if (type.baseType === "array") {
+    if (
+      !Array.isArray(value) ||
+      (type.arrayLength !== -1 && value.length !== type.arrayLength)
+    )
+      return fail();
+    value.forEach((v, i) =>
+      validateAbiValue(type.arrayChildren!, v, `${label}[${i}]`, allowDeferred),
+    );
+    return;
+  }
+  if (type.baseType === "tuple") {
+    const components = type.components!;
+    if (Array.isArray(value)) {
+      if (value.length !== components.length) return fail();
+      components.forEach((c, i) =>
+        validateAbiValue(c, value[i], `${label}[${i}]`, allowDeferred),
+      );
+      return;
+    }
+    if (!value || typeof value !== "object") return fail();
+    const names = components.map((c) => c.name);
+    if (
+      names.some((n) => !n) ||
+      new Set(names).size !== names.length ||
+      Object.keys(value).sort().join("\0") !== names.slice().sort().join("\0")
+    )
+      return fail();
+    components.forEach((c) =>
+      validateAbiValue(
+        c,
+        (value as Record<string, unknown>)[c.name],
+        `${label}.${c.name}`,
+        allowDeferred,
+      ),
+    );
+    return;
+  }
+  if (type.type === "bool") {
+    if (typeof value !== "boolean") fail();
+    return;
+  }
+  const integer = /^(u?int)([0-9]+)$/.exec(type.type);
+  if (integer) {
+    if (
+      !(typeof value === "number" && Number.isSafeInteger(value)) &&
+      !(typeof value === "string" && /^(0|-?[1-9][0-9]*)$/.test(value))
+    )
+      return fail();
+    const bits = BigInt(integer[2]),
+      signed = integer[1] === "int",
+      n = BigInt(value as string | number);
+    if (
+      n < (signed ? -(1n << (bits - 1n)) : 0n) ||
+      n > (signed ? (1n << (bits - 1n)) - 1n : (1n << bits) - 1n)
+    )
+      fail();
+    return;
+  }
+  if (type.type === "address") {
+    if (typeof value !== "string" || !isAddress(value)) fail();
+    return;
+  }
+  if (type.type === "string") {
+    if (typeof value !== "string") fail();
+    return;
+  }
+  const bytes = /^bytes([0-9]*)$/.exec(type.type);
+  if (bytes) {
+    if (
+      typeof value !== "string" ||
+      !/^0x(?:[a-fA-F0-9]{2})*$/.test(value) ||
+      (bytes[1] && value.length !== 2 + 2 * Number(bytes[1]))
+    )
+      fail();
+    return;
+  }
+  throw new Error(`Unsupported ABI type ${type.type}`);
+}
+function boundary(value: unknown, allowDeferred: boolean): unknown {
+  return copyOwnData(value, "ABI input", allowDeferred ? DEFERRED : undefined);
+}
+export function validateAbiArguments(
+  abi: InterfaceAbi,
+  method: string | null,
+  args: unknown,
+  options: { allowDeferred?: boolean } = {},
+): void {
+  const allow = options.allowDeferred === true;
+  const input = boundary(args, allow),
+    iface = new Interface(abi);
+  const fragment = method === null ? iface.deploy : iface.getFunction(method);
+  if (!fragment) throw new Error(`Unknown ABI method ${method}`);
+  if (input === DEFERRED)
+    throw new Error(
+      "Future state requires explicit ABI argument count and shape",
+    );
+  if (!Array.isArray(input) || input.length !== fragment.inputs.length)
+    throw new Error(
+      `ABI argument count mismatch for ${method ?? "constructor"}`,
+    );
+  fragment.inputs.forEach((type, i) =>
+    validateAbiValue(
+      type,
+      input[i],
+      `${method ?? "constructor"} args[${i}]`,
+      allow,
+    ),
+  );
+}
+export function validateTransactionValue(
+  value: unknown,
+  allowDeferred = false,
+): void {
+  validateAbiValue(
+    ParamType.from("uint256"),
+    value,
+    "transaction value",
+    allowDeferred,
+  );
+}
+
+export function validateAbiResult(
+  abi: InterfaceAbi,
+  method: string,
+  raw: unknown,
+  allowDeferred = false,
+): void {
+  const value = boundary(raw, allowDeferred),
+    fragment = new Interface(abi).getFunction(method);
+  if (!fragment) throw new Error("Unknown ABI method");
+  if (fragment.outputs.length === 1)
+    validateAbiValue(
+      fragment.outputs[0],
+      value,
+      "expected result",
+      allowDeferred,
+    );
+  else {
+    if (!Array.isArray(value) || value.length !== fragment.outputs.length)
+      throw new Error("ABI result count mismatch");
+    fragment.outputs.forEach((p, i) =>
+      validateAbiValue(p, value[i], `expected result[${i}]`, allowDeferred),
+    );
+  }
+}
+function comparable(type: ParamType, value: any): unknown {
+  if (type.baseType === "array")
+    return value.map((v: unknown) => comparable(type.arrayChildren!, v));
+  if (type.baseType === "tuple")
+    return type.components!.map((p, i) =>
+      comparable(p, Array.isArray(value) ? value[i] : value[p.name]),
+    );
+  if (/^(u?int)[0-9]+$/.test(type.type)) return BigInt(value).toString();
+  if (type.type === "address") return getAddress(value).toLowerCase();
+  if (type.type.startsWith("bytes")) return value.toLowerCase();
+  return value;
+}
+export function stringifyRuntimeValue(value: unknown): string {
+  const data = normalizeRuntimeValue(value);
+  return typeof data === "string" ? data : JSON.stringify(data);
+}
+export function compareAbiResults(
+  abi: InterfaceAbi,
+  method: string,
+  actual: unknown,
+  expected: unknown,
+): { actual: string; expected: string } {
+  const normalized = normalizeRuntimeValue(actual);
+  validateAbiResult(abi, method, normalized);
+  validateAbiResult(abi, method, expected);
+  const outputs = new Interface(abi).getFunction(method)!.outputs;
+  const encode = (v: any) =>
+    stringifyRuntimeValue(
+      outputs.length === 1
+        ? comparable(outputs[0], v)
+        : outputs.map((p, i) => comparable(p, v[i])),
+    );
+  return { actual: encode(normalized), expected: encode(expected) };
+}

package/runtime/delivery/aggregate-bootstrap.ts

@@ -0,0 +1,29 @@
+/** Private fixed-worker bootstrap. Never accepts caller config overrides. */
+import path from 'node:path';
+import type { HardhatConfig } from 'hardhat/types';
+let fork:Readonly<{network:string;chainId:number;url:string;blockNumber:number}>|undefined;
+const policies=new WeakMap<object,HardhatConfig['networks']['hardhat']>();
+export function establishOwnedFork(input:NonNullable<typeof fork>):void {
+  if(fork||require.main?.filename!==path.join(__dirname,'aggregate-worker.js')||!process.send||!process.connected)
+    throw new Error('Owned worker fork bootstrap required');
+  const url=new URL(input.url);
+  if(url.protocol!=='http:'||url.hostname!=='127.0.0.1'||!/^\/[a-f0-9-]{36}$/.test(url.pathname)||url.username||url.password||url.search||url.hash)
+    throw new Error('Owned source proxy required');
+  fork=Object.freeze({...input});
+}
+export function registerOwnedFork(extendConfig:typeof import('hardhat/config').extendConfig):void {
+  if(!fork)return;
+  extendConfig(config=>{
+    if(config.networks[fork!.network]?.chainId!==fork!.chainId)throw new Error('Owned fork target chain mismatch');
+    policies.set(config,config.networks.hardhat);
+    config.networks.hardhat={...config.networks.hardhat,chainId:fork!.chainId,
+      forking:{enabled:true,url:fork!.url,blockNumber:fork!.blockNumber,httpHeaders:{}}};
+  });
+}
+export function originalRunnerPolicy(config:HardhatConfig):HardhatConfig['networks']['hardhat'] {
+  return policies.get(config)??config.networks.hardhat;
+}
+
+export function assertOwnedTargetWorker():void {
+  if(!fork||require.main?.filename!==path.join(__dirname,'aggregate-worker.js')||!process.send||!process.connected)throw new Error('Owned target worker required');
+}

package/runtime/delivery/aggregate-channel.ts

@@ -0,0 +1,85 @@
+/** Finite private protocol. A nonce correlates an actual child; it is not process attestation. */
+import {productionChildEnvironment} from './production-environment';
+import {fork,type ChildProcess} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {strictData} from './data';
+import {exactObject} from '../workflow/lib/canonicalData';
+export class OwnedWorkerFailure extends Error {}
+export type Command='stage'|'check'|'bind'|'close'|'abort';
+export interface WorkerMessage {version:1;session:string;epoch:string;target:string;id:number;command:Command;data:unknown}
+export function parseWorkerMessage(raw:unknown):WorkerMessage {
+  const x=exactObject(strictData(raw),['version','session','epoch','target','id','command','data'],'worker message');
+  if(x.version!==1||typeof x.session!=='string'||typeof x.epoch!=='string'||typeof x.target!=='string'||!Number.isSafeInteger(x.id)||Number(x.id)<1||!['stage','check','bind','close','abort'].includes(String(x.command)))throw new OwnedWorkerFailure('Invalid worker protocol');
+  return x as unknown as WorkerMessage;
+}
+export class OwnedWorker {
+  readonly #child:ChildProcess;
+  readonly epoch=randomUUID();
+  #id=0;#state:'new'|'staging'|'staged'|'checked'|'bound'|'closing'|'closed'|'failed'='new';
+  #pending?:{message:WorkerMessage;resolve:(v:any)=>void;reject:(e:Error)=>void;timer:NodeJS.Timeout};
+  #failure?:Error;
+  readonly #exit:Promise<void>;
+  #exited=false;
+  constructor(readonly root:string,readonly session:string,readonly target:string,readonly role:'source'|'target',readonly failAggregate:(error:Error)=>void){
+    const env=productionChildEnvironment(process.env);
+    for(const key of ['GATE_DELIVERY_CONTEXT','GATE_WORKFLOW_TARGET','MANIFEST_DEFAULT_DIR','HARDHAT_NETWORK','GATE_FORK_PROXY_HANDSHAKE','GATE_WORKFLOW_SIMULATION_FORK','GATE_WORKFLOW_SIMULATION_SOURCE_RPC'])delete env[key];
+    Object.assign(env,{HARDHAT_CONFIG:path.join(root,'hardhat.config.ts'),HARDHAT_TSCONFIG:path.join(root,'tsconfig.json'),HARDHAT_DISABLE_TELEMETRY_PROMPT:'true'});
+    this.#child=fork(path.join(__dirname,'aggregate-worker.js'),[],{cwd:root,env,execArgv:[],stdio:['ignore','ignore','ignore','ipc'],serialization:'json'});
+    this.#child.on('message',raw=>{
+      try{
+        const reply=parseWorkerMessage(raw),pending=this.#pending;
+        if(!pending||reply.session!==session||reply.target!==target||reply.epoch!==this.epoch||reply.id!==pending.message.id||reply.command!==pending.message.command)throw new OwnedWorkerFailure('Unexpected worker protocol reply');
+        const value=exactObject(reply.data,['ok','value'],'worker reply');
+        if(value.ok!==true){
+          const details=exactObject(value.value,['phase'],'worker failure');
+          const phases=['protocol','project-loader','source-open','source-configuration','fork-setup','target-configuration','compile','planning','staged-reread','barrier','configuration-seal','binding'];
+          if(!phases.includes(String(details.phase)))throw new Error('Invalid worker failure');
+          this.fail(new OwnedWorkerFailure('Owned worker failed during '+details.phase));return;
+        }
+        clearTimeout(pending.timer);this.#pending=undefined;pending.resolve(value.value);
+      }catch{this.fail(new OwnedWorkerFailure('Owned worker failed or sent an invalid reply'));}
+    });
+    this.#child.on('error',()=>this.fail(new OwnedWorkerFailure('Owned worker process failed')));
+    this.#child.on('disconnect',()=>{if(!['closing','closed','failed'].includes(this.#state))this.fail(new OwnedWorkerFailure('Unexpected worker disconnect'));});
+    this.#exit=new Promise(resolve=>this.#child.once('exit',(code,signal)=>{
+      this.#exited=true;
+      if(this.#state!=='closing'||code!==0||signal!==null)this.fail(new OwnedWorkerFailure('Unexpected worker exit'));
+      else this.#state='closed';
+      resolve();
+    }));
+  }
+  get pid():number|undefined{return this.#child.pid;}
+  assertLive():void {if(this.#failure||this.#exited||!this.#child.connected)throw this.#failure??new OwnedWorkerFailure('Worker is not live');}
+  private fail(error:Error):void {
+    if(this.#failure)return;this.#failure=error;this.#state='failed';
+    if(this.#pending){clearTimeout(this.#pending.timer);this.#pending.reject(error);this.#pending=undefined;}
+    this.failAggregate(error);
+  }
+  async request(command:Command,data:unknown=null):Promise<any>{
+    this.assertLive();
+    const allowed=command==='stage'?this.#state==='new':command==='check'?this.#state==='staged':command==='bind'?this.role==='target'&&this.#state==='checked':command==='close'?(this.role==='source'?this.#state==='checked':this.#state==='bound'):false;
+    if(!allowed||this.#pending){const error=new OwnedWorkerFailure('Worker protocol order violation');this.fail(error);throw error;}
+    const next=command==='stage'?'staged':command==='check'?'checked':command==='bind'?'bound':'closed';
+    this.#state=command==='stage'?'staging':command==='close'?'closing':this.#state;
+    const message:WorkerMessage={version:1,session:this.session,epoch:this.epoch,target:this.target,id:++this.#id,command,data:strictData(data)};
+    const result=await new Promise<any>((resolve,reject)=>{
+      const timer=setTimeout(()=>this.fail(new OwnedWorkerFailure('Owned worker request timed out')),180000);
+      this.#pending={message,resolve,reject,timer};
+      this.#child.send(message,error=>{if(error)this.fail(new OwnedWorkerFailure('Owned worker channel failed'));});
+    });
+    if(command==='close'){
+      await this.reap(false);if(this.#failure)throw this.#failure;
+    }else{this.assertLive();this.#state=next as 'staged'|'checked'|'bound'|'closed';}
+    return result;
+  }
+  async reap(abort=true):Promise<void>{
+    if(this.#exited)return;
+    if(abort){this.#state='failed';if(this.#pending){clearTimeout(this.#pending.timer);this.#pending.reject(new OwnedWorkerFailure('Aggregate aborted'));this.#pending=undefined;}this.#child.kill('SIGTERM');}
+    let timer:NodeJS.Timeout|undefined;
+    try{await Promise.race([this.#exit,new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new OwnedWorkerFailure('Worker did not exit')),5000);})]);}
+    catch{this.#child.kill('SIGKILL');await Promise.race([this.#exit,new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new OwnedWorkerFailure('Worker could not be reaped')),5000);})]);}
+    finally{if(timer)clearTimeout(timer);}
+    if(!this.#exited)throw new OwnedWorkerFailure('Worker exit unproven');
+  }
+}

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));});