gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/aggregate-worker.ts

@@ -0,0 +1,143 @@
+/** 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';
+import {workerFailureReason,sourceRpcFailures} from './aggregate-diagnostics';
+
+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',...(Object.hasOwn(initial,'derivationSeed')?['derivationSeed']:[])],'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});
+    phase='fork-verify';
+    await verifySimulationForkSnapshot(hre,simulation);
+    const operator=(request.devSigner??request.operator)!.toLowerCase();
+    phase='fork-signer';
+    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(Object.values(sourceRpcFailures).includes(data.error.message)?data.error.message:'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.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'){
+      phase='source-recheck';await source!.check();
+      phase='source-seal';finalConfiguration=config!.seal() as DeliveryConfigurationEvidence;
+      state='checked';return {configuration:finalConfiguration};
+    }
+    phase='plan-recheck';
+    await stage!.assertUnchanged();
+    phase='compiler-recheck';
+    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;
+
+    const reason=workerFailureReason(error);
+    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,...(reason?{reason}:{})}}},()=>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 {aggregateInputHash} from './execution-identity';
+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=aggregateInputHash({inputs:{business:sealed,sourceDefinitions,runtime:parentRuntime,files:union,targets:contributions}});
+    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/business-extension.ts

@@ -0,0 +1,33 @@
+/** Shared declarative steps may gain network parameters without changing accepted dev behavior. */
+import {resolveValue, type WorkflowStep} from '../workflow/lib/parameters';
+import {canonicalJson} from '../workflow/lib/canonicalData';
+import {pointerPart} from './data';
+import type {ResolvedDeliveryParameters} from './parameters';
+
+export function validateHistoricalBusinessExtension(input: {
+  before: readonly WorkflowStep[]; after: readonly WorkflowStep[];
+  previous: ResolvedDeliveryParameters; current: ResolvedDeliveryParameters; target: Record<string, unknown>;
+}): void {
+  if ([...input.before, ...input.after].some(step => step.kind === 'custom')) throw Error('Historical custom steps require unchanged manifest/schema and parameters');
+  const symbolicState = {get: (key: string) => ({$ref: `state.${key}`})};
+  const project = (steps: readonly WorkflowStep[], params: unknown) => steps.map(step => {
+    const {name: _name, description: _description, ...operation} = step;
+    return resolveValue(operation, {targetId: input.previous.target, target: input.target,
+      params: params as Record<string, unknown>, state: symbolicState as never});
+  });
+  if (canonicalJson(project(input.before, input.previous.values)) !== canonicalJson(project(input.after, input.current.values))) throw Error('Historical resolved development operations changed');
+  const references = new Set<string>();
+  const visit = (value: unknown): void => {
+    if (typeof value === 'string' && value.startsWith('$param.')) references.add('/' + value.slice(7).split('.').map(pointerPart).join('/'));
+    else if (value && typeof value === 'object') {
+      const ref = (value as any).$ref;
+      if (typeof ref === 'string' && ref.startsWith('param.')) references.add('/' + ref.slice(6).split('.').map(pointerPart).join('/'));
+      else Object.values(value).forEach(visit);
+    }
+  };
+  input.after.forEach(visit);
+  for (const leaf of input.current.provenance) {
+    if (!input.previous.provenance.some(old => old.path === leaf.path)
+      && ![...references].some(ref => leaf.path === ref || leaf.path.startsWith(ref + '/'))) throw Error('Historical added parameter is not used by the shared steps');
+  }
+}

package/runtime/delivery/calldata-archive.ts

@@ -0,0 +1,25 @@
+/** Immutable project-local file publication. This is not execution authority. */
+import { projectRoot } from './project-files';
+import { atomicDevelopmentWrite, withDevelopmentFileLock, fileBytes, byteHash } from './materialization';
+import { canonicalJson, semanticHash } from '../workflow/lib/canonicalData';
+import { safeId } from './protocol';
+import { serializeDeliveryCalls, deliveryCalldataPath } from './calldata-format';
+import type { DeliveryCall } from './public-calldata';
+export async function archiveDeliveryCalls(input:{workspaceRoot:string;projectRoot:string;deploymentId:string;calls:readonly DeliveryCall[];provenance:unknown;assertCurrent():void}){
+ const root=projectRoot(input.workspaceRoot,input.projectRoot),deployment=safeId(input.deploymentId,'deploymentId');
+ const bytes=serializeDeliveryCalls(input.calls)+'\n',sha256=byteHash(bytes);
+ const path=deliveryCalldataPath(deployment,sha256);
+ const body={version:1,path,sha256,provenance:input.provenance};
+ const record=canonicalJson(body)+'\n',provenancePath=`.gate-delivery/deliveries/${deployment}/${sha256}-${semanticHash(body)}.json`;
+ return withDevelopmentFileLock(root,async()=>{
+  input.assertCurrent();
+  for(const [file,content] of [[path,bytes],[provenancePath,record]]){
+   const existing=fileBytes(root,file);
+   if(existing!==null&&existing!==content)throw Error('Immutable calldata archive conflict');
+   if(existing===null)atomicDevelopmentWrite(root,file,content);
+  }
+  input.assertCurrent();
+  if(fileBytes(root,path)!==bytes)throw Error('Published calldata changed');
+  return {status:'READY' as const,path,sha256,size:Buffer.byteLength(bytes),provenance:{path:provenancePath,sha256:byteHash(record)}};
+ });
+}

package/runtime/delivery/calldata-details.ts

@@ -0,0 +1,90 @@
+/** Explanations of verified wrapper ABI payloads; never additional transactions. */
+import { Interface, getCreate2Address, keccak256, type ParamType } from 'ethers';
+import { parseCalldataInvocation, type CalldataInvocation } from './calldata-review';
+import type { PreparationEntry } from './journal';
+import { canonicalJson } from '../workflow/lib/canonicalData';
+export interface ExpandedCall {
+  to: string; name: string; description: string; abi: string[]; calldata: string;
+  value?: string; allowFailure?: boolean; details?: ExpandedDetails;
+}
+export type ExpandedDetails =
+  | { type: 'multicall'; calls: ExpandedCall[] }
+  | { type: 'create2'; contract: string; role: string; factory: string; salt: string; saltDescription: string;
+      constructor: { abi: string[]; args: unknown[]; initialization?: ExpandedCall };
+      initCodeHash: string; predictedAddress: string; create2ForwardValue?: string; callForwardValue?: string;
+      placeholderImplementation?: string; afterDeployment?: ExpandedCall }
+  | { type: 'upgrade'; proxy: string; newImplementation: string; initialization: ExpandedCall | null };
+const childAt = (i: CalldataInvocation, path: number[]) => i.payloads.find(p => JSON.stringify(p.argumentPath) === JSON.stringify(path))?.invocation;
+export function readableInvocationAbi(i: CalldataInvocation): string[] {
+  const iface=new Interface(i.abi as any);
+  const fragment=i.kind==='constructor'?iface.deploy:iface.getFunction(i.method);
+  if (!fragment) throw Error('Readable invocation ABI missing');
+  return [fragment.format('full')];
+}
+/** Keep authored business intent, append exact verified arguments without copying wrapper bytecode. */
+export function describeDeliveryInvocation(description: string, raw: CalldataInvocation): string {
+  const invocation = parseCalldataInvocation(raw);
+  function argumentsText(i: CalldataInvocation, depth: number): string {
+    if (depth > 24) throw Error('Nested calldata description exceeds supported depth');
+    const iface = new Interface(i.abi as any);
+    const fragment = i.kind === 'constructor' ? iface.deploy : iface.getFunction(i.method);
+    if (!fragment) throw Error('Description invocation ABI missing');
+    const named = (type: ParamType, value: unknown, path: number[]): string =>
+      `${type.name || `arg${path[path.length - 1]}`}(${type.format('sighash')})=${render(type, value, path)}`;
+    const render = (type: ParamType, value: unknown, path: number[]): string => {
+      const payload = i.payloads.find(p => canonicalJson(p.argumentPath) === canonicalJson(path));
+      if (payload) {
+        const nested = payload.invocation;
+        const call = `${nested.method}(${argumentsText(nested, depth + 1)})`;
+        return nested.kind === 'constructor' ? `{initCodeHash=${keccak256(nested.data)}, ${call}}` : call;
+      }
+      if (type.baseType === 'array') return '[' + (value as unknown[])
+        .map((item, index) => render(type.arrayChildren!, item, [...path, index])).join(', ') + ']';
+      if (type.baseType === 'tuple') return '(' + type.components!
+        .map((component, index) => named(component, (value as unknown[])[index], [...path, index])).join(', ') + ')';
+      return canonicalJson(value);
+    };
+    return fragment.inputs.map((type, index) => named(type, i.expectedArguments[index], [index])).join(', ');
+  }
+  const args = argumentsText(invocation, 0);
+  return args ? `${description}\n执行参数：${args}` : description;
+}
+/** Caller validates its preparation journal against the frozen plan first. */
+export function expandDeliveryInvocation(raw: CalldataInvocation, to: string, intent: {name:string;description:string}, entry?: PreparationEntry, depth=0): ExpandedDetails | undefined {
+  if(depth>24)throw Error('Nested calldata exceeds supported depth');
+  const i=parseCalldataInvocation(raw),args=i.expectedArguments;
+  const child=(invocation:CalldataInvocation,target:string,name:string,value='0'):ExpandedCall=>({to:target,name,description:describeDeliveryInvocation(`${intent.description}；内部动作：${name}`,invocation),abi:readableInvocationAbi(invocation),calldata:invocation.data,
+    ...(BigInt(value)===0n?{}:{value}),...((details=>details?{details}:{})(expandDeliveryInvocation(invocation,target,{name,description:intent.description},entry,depth+1)))});
+  if(['aggregate3((address,bool,bytes)[])','aggregate3Value((address,bool,uint256,bytes)[])'].includes(i.method)) {
+    const withValue=i.method.startsWith('aggregate3Value');
+    return {type:'multicall',calls:(args[0] as any[]).map((row,index)=>{
+      const invocation=childAt(i,[0,index,withValue?3:2]);
+      if(!invocation)throw Error('Multicall child ABI missing');
+      const known=entry?.prepared.plan.transactions.find(tx=>tx.to.toLowerCase()===row[0].toLowerCase()&&tx.data.toLowerCase()===invocation.data);
+      const names:Record<string,string>={'deploy-implementation':'部署业务实现','deploy-proxy':'部署代理','deploy-contract':'CREATE2 部署合约','upgrade-proxy':'升级代理并按既定参数初始化'};
+      return {...child(invocation,row[0],known?names[known.purpose]??known.purpose:`${intent.name} / ${index+1}`,withValue?row[2]:'0'),allowFailure:row[1]};
+    })};
+  }
+  if(i.method==='deploy(bytes32,bytes,bytes,uint256,uint256)') {
+    const ctor=childAt(i,[1]);
+    if(!entry||!ctor||ctor.kind!=='constructor')throw Error('CREATE2 explanation requires frozen preparation and constructor ABI');
+    const initCodeHash=keccak256(ctor.data),predictedAddress=getCreate2Address(to,String(args[0]),initCodeHash).toLowerCase();
+    const deployed=entry.prepared.plan.deployments.find(d=>d.salt.toLowerCase()===String(args[0]).toLowerCase()&&d.address.toLowerCase()===predictedAddress);
+    if(!deployed||deployed.initCodeHash&&deployed.initCodeHash.toLowerCase()!==initCodeHash)throw Error('CREATE2 salt, initCode or predicted address differs from frozen preparation');
+    const request=entry.prepared.request,placeholder=request.kind==='uups-placeholder-deploy'&&deployed.role==='proxy';
+    const initialization=deployed.role==='proxy'?childAt(ctor,[request.kind==='transparent-deploy'?2:1]):undefined;
+    if(ctor.payloads.length&&!initialization)throw Error('Constructor executable payload has no registered adapter');
+    const forward=childAt(i,[2]);
+    return {type:'create2',contract:deployed.role==='proxy'?(request.kind==='transparent-deploy'?'TransparentUpgradeableProxy':'ERC1967Proxy'):request.contract,
+      role:deployed.role,factory:to,salt:String(args[0]),saltDescription:deployed.role==='proxy'?'proxySalt：确定代理地址的 CREATE2 盐值，与实现盐值分离':deployed.role==='implementation'?'implementationSalt：本轮业务实现的 CREATE2 盐值，与代理盐值分离':'本轮合约的 CREATE2 盐值',
+      constructor:{abi:readableInvocationAbi(ctor),args:ctor.expectedArguments,...(initialization?{initialization:child(initialization,predictedAddress,'构造期间初始化')}: {})},
+      initCodeHash,predictedAddress,...(BigInt(String(args[3]))===0n?{}:{create2ForwardValue:String(args[3])}),...(BigInt(String(args[4]))===0n?{}:{callForwardValue:String(args[4])}),
+      ...(placeholder?{placeholderImplementation:request.placeholderImplementation}:{}),...(forward?{afterDeployment:child(forward,predictedAddress,'部署后调用',String(args[4]))}:{})};
+  }
+  if(['upgradeToAndCall(address,bytes)','upgradeAndCall(address,address,bytes)'].includes(i.method)) {
+    const transparent=i.method.startsWith('upgradeAndCall'),proxy=transparent?String(args[0]):to,newImplementation=String(args[transparent?1:0]),initializer=childAt(i,[transparent?2:1]);
+    return {type:'upgrade',proxy,newImplementation,initialization:initializer?child(initializer,proxy,'升级附带初始化'):null};
+  }
+  if(i.payloads.length)throw Error('Executable nested payload has no registered explanation adapter');
+  return undefined;
+}

package/runtime/delivery/calldata-format.ts

@@ -0,0 +1,14 @@
+/** One readable, deterministic file format and path for every public delivery. */
+import { canonicalJson } from '../workflow/lib/canonicalData';
+import { safeId } from './protocol';
+import type { DeliveryCall } from './public-calldata';
+
+/** No trailing newline: file publishers append exactly one before hashing. */
+export function serializeDeliveryCalls(calls: readonly DeliveryCall[]): string {
+  return JSON.stringify(JSON.parse(canonicalJson(calls)), null, 2);
+}
+
+export function deliveryCalldataPath(deploymentId: string, sha256: string): string {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) throw Error('Invalid calldata content digest');
+  return `scripts/tasks/${safeId(deploymentId, 'deploymentId')}/deliveries/${sha256}/calldata.json`;
+}

package/runtime/delivery/calldata-preparations.ts

@@ -0,0 +1,76 @@
+/** Planning-only adapter: reconstruct deployment intent from frozen requests and compiled artifacts. */
+import { Interface, concat, type InterfaceAbi } from 'ethers';
+import type { PreparationEntry } from './journal';
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { createCalldataInvocation, reviewTransaction, type CalldataInvocation, type CalldataTransactionReview } from './calldata-review';
+
+const factoryAbi = ['function deploy(bytes32 salt,bytes initCode,bytes data,uint256 create2ForwardValue,uint256 callForwardValue) payable returns(address)'];
+const upgradeAbi = ['function upgradeToAndCall(address newImplementation,bytes data) payable'];
+const adminAbi = ['function upgradeAndCall(address proxy,address implementation,bytes data) payable'];
+const multicallAbi = [
+    'function aggregate3(tuple(address target,bool allowFailure,bytes callData)[] calls) payable returns(tuple(bool success,bytes returnData)[])',
+    'function aggregate3Value(tuple(address target,bool allowFailure,uint256 value,bytes callData)[] calls) payable returns(tuple(bool success,bytes returnData)[])',
+];
+type ArtifactReader = { readArtifact(name: string): Promise<{ abi: InterfaceAbi; bytecode: string }> };
+export async function preparationCalldataReviews(entries: readonly PreparationEntry[], transactions: readonly ReleaseExecutionTransaction[], artifacts: ArtifactReader): Promise<CalldataTransactionReview[]> {
+    const result: CalldataTransactionReview[] = [];
+    for (const entry of entries) {
+        const { request, plan } = entry.prepared;
+        const artifact = await artifacts.readArtifact(request.contract);
+        const implementation = plan.deployments.find(d => d.role === 'implementation');
+        const initializer = request.kind !== 'create2-deploy' && request.call
+            ? createCalldataInvocation({ abi: artifact.abi, method: request.call.method, args: request.call.args,
+                data: new Interface(artifact.abi).encodeFunctionData(request.call.method, request.call.args) }) : undefined;
+        const inner = new Map<string, CalldataInvocation>();
+        for (const tx of plan.transactions) {
+            let invocation: CalldataInvocation;
+            if (tx.purpose === 'upgrade-proxy') {
+                if (request.kind === 'create2-deploy' || !implementation) throw Error('Upgrade ABI intent missing');
+                const transparent = request.kind === 'transparent-upgrade';
+                const args = transparent ? [request.proxy, implementation.address, initializer?.data ?? '0x'] : [implementation.address, initializer?.data ?? '0x'];
+                invocation = createCalldataInvocation({ abi: transparent ? adminAbi : upgradeAbi, method: transparent ? 'upgradeAndCall' : 'upgradeToAndCall', args, data: tx.data,
+                    payloads: initializer ? [{ argumentPath: [transparent ? 2 : 1], invocation: initializer }] : [] });
+            } else {
+                const role = tx.purpose === 'deploy-proxy' ? 'proxy' : tx.purpose === 'deploy-implementation' ? 'implementation' : 'contract';
+                const deployed = plan.deployments.find(d => d.role === role);
+                if (!deployed) throw Error('Deployment ABI intent missing');
+                const proxy = role === 'proxy';
+                const transparent = request.kind === 'transparent-deploy';
+                const code = proxy ? await artifacts.readArtifact(transparent
+                    ? '@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol:TransparentUpgradeableProxy'
+                    : '@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy') : artifact;
+                const args = !proxy ? request.constructorArgs : request.kind === 'uups-placeholder-deploy'
+                    ? [request.placeholderImplementation, '0x'] : transparent
+                    ? [implementation!.address, request.proxyAdminOwner, initializer?.data ?? '0x'] : undefined;
+                if (!args) throw Error('Proxy constructor ABI intent missing');
+                const constructor = createCalldataInvocation({ abi: code.abi, method: null, args, bytecode: code.bytecode,
+                    data: concat([code.bytecode, new Interface(code.abi).encodeDeploy(args)]),
+                    payloads: proxy && transparent && initializer ? [{ argumentPath: [2], invocation: initializer }] : [] });
+                if (new Interface(code.abi).encodeDeploy(args).toLowerCase() !== deployed.constructorInput.toLowerCase()) throw Error('Constructor calldata differs from preparation');
+                const forward = request.kind === 'create2-deploy' ? [request.create2ForwardValue ?? '0', request.callForwardValue ?? '0'] : ['0', '0'];
+                invocation = createCalldataInvocation({ abi: factoryAbi, method: 'deploy', args: [deployed.salt, constructor.data, '0x', ...forward], data: tx.data,
+                    payloads: [{ argumentPath: [1], invocation: constructor }] });
+            }
+            inner.set(tx.id, invocation);
+        }
+        for (const mapping of entry.mappings) {
+            const tx = transactions.find(t => t.transactionId === mapping.transactionId);
+            if (!tx) throw Error('Calldata preparation mapping missing');
+            const calls = mapping.gateToolTransactionIds.map(id => {
+                const intent = inner.get(id), prepared = plan.transactions.find(t => t.id === id);
+                if (!intent || !prepared) throw Error('Inner calldata ABI intent missing');
+                return { intent, prepared };
+            });
+            if (mapping.kind === 'direct') {
+                if (calls.length !== 1) throw Error('Direct calldata mapping must contain one invocation');
+                result.push(reviewTransaction(tx, calls[0].intent));
+            } else {
+                const withValue = calls.some(c => BigInt(c.prepared.value) !== 0n), method = withValue ? 'aggregate3Value' : 'aggregate3';
+                const args = [calls.map(({ prepared: p }) => withValue ? [p.to, false, p.value, p.data] : [p.to, false, p.data])];
+                result.push(reviewTransaction(tx, createCalldataInvocation({ abi: multicallAbi, method, args, data: tx.data,
+                    payloads: calls.map((c, index) => ({ argumentPath: [0, index, withValue ? 3 : 2], invocation: c.intent })) })));
+            }
+        }
+    }
+    return result;
+}