gate-evm-tools 1.0.31 → 1.2.1

package/runtime/delivery/aggregate-channel.ts

@@ -5,6 +5,7 @@ import {randomUUID} from 'node:crypto';
 import path from 'node:path';
 import {strictData} from './data';
 import {exactObject} from '../workflow/lib/canonicalData';
+import {workerFailures} from './aggregate-diagnostics';
 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}
@@ -32,10 +33,12 @@ export class OwnedWorker {
         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'];
+          const hasReason=Object.hasOwn(value.value as object,'reason');
+          const details=exactObject(value.value,['phase',...(hasReason?['reason']:[])],'worker failure');
+          const phases=['protocol','project-loader','source-open','source-configuration','fork-setup','fork-verify','fork-signer','target-configuration','compile','planning','existing-code-artifacts','staged-reread','barrier','source-recheck','source-seal','plan-recheck','compiler-recheck','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;
+          if(hasReason&&(typeof details.reason!=='string'||!Object.hasOwn(workerFailures,details.reason)))throw new Error('Invalid worker failure reason');
+          this.fail(new OwnedWorkerFailure('Owned worker failed during '+details.phase+' ('+role+')'+(hasReason?': '+workerFailures[details.reason as string]:'')));return;
         }
         clearTimeout(pending.timer);this.#pending=undefined;pending.resolve(value.value);
       }catch{this.fail(new OwnedWorkerFailure('Owned worker failed or sent an invalid reply'));}

package/runtime/delivery/aggregate-diagnostics.ts

@@ -0,0 +1,63 @@
+/** Finite diagnostics only: provider errors can contain RPC credentials and payloads. */
+export const sourceRpcFailures = {
+  'source-history-unavailable': 'Source RPC cannot read historical state at the pinned block; configure an RPC with historical-state access without changing the pinned block.',
+  'source-access-denied': 'Source RPC denied access; check the configured RPC access without exposing credentials.',
+  'source-rate-limited': 'Source RPC rate limit exceeded; use an RPC with sufficient read capacity for the pinned fork.',
+  'source-transport-failed': 'Source RPC transport failed; check connectivity and the RPC response timeout for the pinned fork.',
+  'source-request-failed': 'Source RPC request failed.',
+} as const;
+export type SourceRpcFailure = keyof typeof sourceRpcFailures;
+
+const invariantMessages = [
+  'Source read failed',
+  'Planning source/input/runtime identity drift',
+  'Planning pinned fork/source identity mismatch',
+  'Captured fork interval drift',
+  'Captured fork interval closed or bound',
+  'Fork audit provider mutation/identity violation',
+  'Fork audit baseline/provider identity changed',
+  'Pending or unobservable fork transactions',
+  'Fork audit changed while enumerating',
+  'Audit transaction lookup mismatch',
+  'Custom input closure drift at collection completion',
+  'Compiler contribution drift',
+  'Compiler effective config drift',
+  'Compiler package payload drift',
+  'Compiler package resolution drift',
+  'Compiler npm lock drift',
+  'Delivery configuration/runtime drift or mismatch',
+  'Source provider changed',
+  'Source pinned block drift',
+] as const;
+export const workerFailures: Readonly<Record<string, string>> = Object.freeze({
+  ...sourceRpcFailures,
+  ...Object.fromEntries(invariantMessages.map((message, index) => ['invariant-'+index,message])),
+  'compiler-input-drift': 'Compiler input bytes changed during qualification.',
+});
+
+/** Only exact reviewed messages or a fixed category may cross the worker channel. */
+export function workerFailureReason(error: unknown): string | undefined {
+  const source = workerSourceFailure(error);
+  if (source) return source;
+  const message = error instanceof Error ? error.message : '';
+  const index = invariantMessages.findIndex(known => known === message);
+  if (index >= 0) return 'invariant-'+index;
+  if (message.startsWith('Compiler input drift: ')) return 'compiler-input-drift';
+  return undefined;
+}
+
+export function sourceRpcFailure(error: unknown): SourceRpcFailure {
+  const known = workerSourceFailure(error);
+  if (known) return known;
+  const message = error instanceof Error ? error.message : '';
+  if (/archive|historical\s+state|missing trie node|state.*(?:unavailable|not available)/i.test(message)) return 'source-history-unavailable';
+  if (/too many requests|rate.?limit/i.test(message) || (error as {code?:unknown} | null)?.code === -32005) return 'source-rate-limited';
+  if (/\b(?:401|403)\b|unauthorized|forbidden|authentication|invalid api key/i.test(message)) return 'source-access-denied';
+  if (/socket|ECONNRESET|ECONNREFUSED|UND_ERR_|timed? ?out|timeout|fetch failed/i.test(message)) return 'source-transport-failed';
+  return 'source-request-failed';
+}
+
+export function workerSourceFailure(error: unknown): SourceRpcFailure | undefined {
+  const message = error instanceof Error ? error.message : '';
+  return (Object.keys(sourceRpcFailures) as SourceRpcFailure[]).find(reason => message.includes(sourceRpcFailures[reason]));
+}

package/runtime/delivery/aggregate-source.ts

@@ -4,6 +4,7 @@ import {randomUUID} from 'node:crypto';
 import {isAllowedSourceRpcMethod} from '../workflow/lib/sourceRpcPolicy';
 import type {DeliveryRequest} from './protocol';
 import type {HardhatRuntimeEnvironment} from 'hardhat/types';
+import {sourceRpcFailure,sourceRpcFailures} from './aggregate-diagnostics';
 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'}};
@@ -13,7 +14,10 @@ export async function openOwnedSource(hre:HardhatRuntimeEnvironment,request:Deli
 }> {
   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 rpc=async(method:string,params:unknown[]=[])=>{
+    try{return await provider.request({method,params});}
+    catch(cause){throw new Error(sourceRpcFailures[sourceRpcFailure(cause)]);}
+  };
   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';
@@ -27,7 +31,7 @@ export async function openOwnedSource(hre:HardhatRuntimeEnvironment,request:Deli
     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');}
+    try{return {jsonrpc:'2.0',id:raw.id??null,result:await rpc(raw.method,raw.params??[])};}catch(cause){return error(-32000,sourceRpcFailures[sourceRpcFailure(cause)]);}
   };
   const server=http.createServer(async(req,res)=>{
     if(req.method!=='POST'||req.url!==endpoint){reply(res,404,{error:'Unknown JSON-RPC endpoint'});return;}

package/runtime/delivery/aggregate-worker.ts

@@ -9,6 +9,7 @@ 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;
@@ -24,7 +25,7 @@ async function dispatch(message:WorkerMessage):Promise<unknown>{
   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');
+    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');
@@ -54,8 +55,10 @@ async function dispatch(message:WorkerMessage):Promise<unknown>{
     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);
@@ -68,12 +71,12 @@ async function dispatch(message:WorkerMessage):Promise<unknown>{
     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 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.executionId});
+    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');
@@ -87,8 +90,14 @@ async function dispatch(message:WorkerMessage):Promise<unknown>{
   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};}
+    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};
@@ -125,7 +134,8 @@ process.on('message',async raw=>{
     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()));
+    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);
   }
 });

package/runtime/delivery/aggregate.ts

@@ -1,5 +1,6 @@
 /** 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';
@@ -115,8 +116,7 @@ async function collectOwnedAggregate(raw:DeliveryAggregateOptions):Promise<Reado
     }
     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}))});
+    const inputsHash=aggregateInputHash({inputs:{business:sealed,sourceDefinitions,runtime:parentRuntime,files:union,targets:contributions}});
     live();
     const collections:DeliveryCollection[]=[];
     for(const row of rows){

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

package/runtime/delivery/calldata-review.ts

@@ -0,0 +1,126 @@
+/** Pure ABI review. Expected arguments come from planning, never from decoding submitted bytes. */
+import { AbiCoder, Interface, ParamType, type InterfaceAbi } from 'ethers';
+import { canonicalJson, deepFreeze } from '../workflow/lib/canonicalData';
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { strictData } from './data';
+
+export interface CalldataPayload {
+    argumentPath: number[];
+    invocation: CalldataInvocation;
+}
+export interface CalldataInvocation {
+    kind: 'function' | 'constructor';
+    abi: unknown[];
+    method: string;
+    selector: string | null;
+    bytecode: string | null;
+    expectedArguments: unknown[];
+    decodedArguments: unknown[];
+    data: string;
+    payloads: CalldataPayload[];
+    check: 'matches-frozen-intent';
+}
+export interface CalldataTransactionReview {
+    transactionId: string;
+    to: string;
+    value: string;
+    operation: 0 | 1;
+    invocation: CalldataInvocation;
+}
+export interface CalldataReviewSink {
+    record(transaction: ReleaseExecutionTransaction, input: { abi: InterfaceAbi; method: string; args: readonly unknown[] }): void;
+}
+function bytes(value: unknown): string {
+    if (typeof value !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(value)) throw Error('Invalid ABI review bytes');
+    return value.toLowerCase();
+}
+/** Decimal strings retain uint256 precision; positional tuples are unambiguous even with duplicate names. */
+function argument(type: ParamType, value: any): unknown {
+    if (type.baseType === 'array') {
+        if (!Array.isArray(value) || (type.arrayLength !== -1 && value.length !== type.arrayLength)) throw Error('Invalid ABI review array');
+        return Array.from(value, v => argument(type.arrayChildren!, v));
+    }
+    if (type.baseType === 'tuple') {
+        if (!value || typeof value !== 'object') throw Error('Invalid ABI review tuple');
+        return type.components!.map((p, i) => argument(p, Array.isArray(value) ? value[i] : value[p.name]));
+    }
+    if (/^u?int\d*$/.test(type.type)) {
+        if (typeof value === 'number' && !Number.isSafeInteger(value)) throw Error('Unsafe ABI review integer');
+        if (!['bigint', 'number', 'string'].includes(typeof value) || (typeof value === 'string' && !value.trim())) throw Error('Invalid ABI review integer');
+        return BigInt(value).toString();
+    }
+    if (type.type === 'address') return String(value).toLowerCase();
+    if (/^bytes\d*$/.test(type.type)) return bytes(value);
+    if ((type.type === 'bool' && typeof value !== 'boolean') || (type.type === 'string' && typeof value !== 'string')) throw Error('Invalid ABI review scalar');
+    return value;
+}
+function argumentsOf(types: readonly ParamType[], args: readonly unknown[]): unknown[] {
+    if (!Array.isArray(args) || types.length !== args.length) throw Error('ABI review argument count mismatch');
+    return types.map((p, i) => argument(p, args[i]));
+}
+export function createCalldataInvocation(input: {
+    abi: InterfaceAbi; method: string | null; args: readonly unknown[]; data: string;
+    bytecode?: string; payloads?: CalldataPayload[];
+}): CalldataInvocation {
+    const iface = new Interface(input.abi), fragment = input.method === null ? iface.deploy : iface.getFunction(input.method);
+    if (!fragment) throw Error('ABI review method missing');
+    const expectedArguments = argumentsOf(fragment.inputs, input.args), data = bytes(input.data);
+    const bytecode = input.method === null ? bytes(input.bytecode) : null;
+    if (input.method !== null && input.bytecode !== undefined) throw Error('Function review cannot contain constructor bytecode');
+    const encoded = input.method === null ? bytecode + iface.encodeDeploy(expectedArguments).slice(2) : iface.encodeFunctionData(input.method, expectedArguments).toLowerCase();
+    if (encoded !== data) throw Error('Calldata differs from expected ABI encoding');
+    const decoded = input.method === null
+        ? AbiCoder.defaultAbiCoder().decode(fragment.inputs, '0x' + data.slice(bytecode!.length))
+        : iface.decodeFunctionData(input.method, data);
+    const decodedArguments = argumentsOf(fragment.inputs, Array.from(decoded));
+    if (canonicalJson(expectedArguments) !== canonicalJson(decodedArguments)) throw Error('Decoded calldata differs from frozen intent');
+    const payloads = (input.payloads ?? []).map(p => {
+        if (!Array.isArray(p.argumentPath) || !p.argumentPath.length || p.argumentPath.some(i => !Number.isSafeInteger(i) || i < 0)) throw Error('Invalid nested calldata argument path');
+        let value: any = expectedArguments;
+        for (const index of p.argumentPath) {
+            if (!Array.isArray(value) || index >= value.length) throw Error('Nested calldata argument path missing');
+            value = value[index];
+        }
+        const invocation = parseCalldataInvocation(p.invocation);
+        if (value !== invocation.data) throw Error('Nested calldata differs from enclosing payload');
+        return { argumentPath: p.argumentPath, invocation };
+    });
+    if (new Set(payloads.map(p => canonicalJson(p.argumentPath))).size !== payloads.length) throw Error('Duplicate nested calldata payload');
+    const method = input.method === null ? 'constructor' : fragment.format('sighash');
+    const required: number[][] = [];
+    if (method === 'deploy(bytes32,bytes,bytes,uint256,uint256)') {
+        required.push([1]);
+        if (expectedArguments[2] !== '0x') required.push([2]);
+        if (payloads.find(p => canonicalJson(p.argumentPath) === '[1]')?.invocation.kind !== 'constructor') throw Error('CREATE2 constructor ABI review required');
+    } else if (method === 'upgradeToAndCall(address,bytes)' && expectedArguments[1] !== '0x') required.push([1]);
+    else if (method === 'upgradeAndCall(address,address,bytes)' && expectedArguments[2] !== '0x') required.push([2]);
+    else if (['aggregate3((address,bool,bytes)[])', 'aggregate3Value((address,bool,uint256,bytes)[])'].includes(method)) {
+        const index = method.startsWith('aggregate3Value') ? 3 : 2;
+        (expectedArguments[0] as unknown[]).forEach((_, i) => required.push([0, i, index]));
+    }
+    for (const path of required) if (!payloads.some(p => canonicalJson(p.argumentPath) === canonicalJson(path))) throw Error('Nested calldata ABI review required');
+    return deepFreeze({ kind: input.method === null ? 'constructor' : 'function', abi: [JSON.parse(fragment.format('json'))],
+        method, selector: input.method === null ? null : iface.getFunction(input.method)!.selector,
+        bytecode, expectedArguments, decodedArguments, data, payloads, check: 'matches-frozen-intent' });
+}
+export function parseCalldataInvocation(raw: unknown): CalldataInvocation {
+    const v = strictData(raw) as CalldataInvocation;
+    if (!v || !['function', 'constructor'].includes(v.kind) || !Array.isArray(v.payloads)) throw Error('Invalid calldata invocation');
+    const parsed = createCalldataInvocation({ abi: v.abi as InterfaceAbi, method: v.kind === 'constructor' ? null : v.method,
+        args: v.expectedArguments, data: v.data, ...(v.kind === 'constructor' ? { bytecode: v.bytecode! } : {}), payloads: v.payloads });
+    if (canonicalJson(parsed) !== canonicalJson(v)) throw Error('Noncanonical or modified ABI review');
+    return parsed;
+}
+export function reviewTransaction(tx: ReleaseExecutionTransaction, invocation: CalldataInvocation): CalldataTransactionReview {
+    const parsed = parseCalldataInvocation(invocation);
+    if (parsed.kind !== 'function' || parsed.data !== tx.data) throw Error('ABI review transaction calldata mismatch');
+    return deepFreeze({ transactionId: tx.transactionId, to: tx.to, value: tx.value, operation: tx.operation, invocation: parsed });
+}
+export function parseCalldataReviews(raw: unknown, transactions: readonly ReleaseExecutionTransaction[]): CalldataTransactionReview[] {
+    if (!Array.isArray(raw) || raw.length !== transactions.length) throw Error('Complete calldata ABI review required');
+    return deepFreeze(raw.map((value, index) => {
+        const v = strictData(value) as CalldataTransactionReview, expected = reviewTransaction(transactions[index], v.invocation);
+        if (canonicalJson(v) !== canonicalJson(expected)) throw Error('ABI review transaction binding mismatch');
+        return expected;
+    }));
+}

package/runtime/delivery/codec-pin.ts

@@ -1,3 +1,3 @@
-// Reviewed vendor identity. Refresh explicitly after rebuilding from committed canonical sources.
-export const PLAN_CODEC_PROVENANCE_SHA256 = '63bc721e90943e08478a67a72d1bef8ce69a034552f225b90ee2c6e5396785ce';
-export const PLAN_CODEC_SOURCE_COMMIT = '9b175e7906ca6735aeca92b50ce7cf716d980f17';
+// Reviewed canonical codec; rebuilt from the recorded SmartFlow sources.
+export const PLAN_CODEC_SOURCE_COMMIT = "ee0f90991ca1a94c3f58c8893df16d0c8c41b230";
+export const PLAN_CODEC_PROVENANCE_SHA256 = "212e560b26b7560a73df1f20bd789fce1e5c3f409afba2d5a5c5c39cb2518ce7";

package/runtime/delivery/compiler-files.ts

@@ -83,7 +83,9 @@ export class CompilerFiles {
     const dependency = compilerDependencyPins[`${metadata.name}@${metadata.version}`];
     if ((enforceReviewed && !pin && !dependency) || (pin && (pin.version !== metadata.version || pin.integrity !== entry.integrity || pin.payloadDigest !== payloadDigest)) || (dependency && (dependency.integrity !== entry.integrity || dependency.payloadDigest !== payloadDigest))) throw new Error(`Unapproved compiler adapter package payload: ${metadata.name}`);
     const tarball = typeof entry.resolved === 'string' && entry.resolved.startsWith('file:') && entry.resolved.endsWith('.tgz');
-    if (!tarball && (typeof entry.resolved !== 'string' || !entry.resolved.startsWith('https://registry.npmjs.org/'))) throw new Error('Unsupported compiler package source');
+    const registry = typeof entry.resolved === 'string'
+      && ['https://registry.npmjs.org/', 'https://registry.npmmirror.com/'].some(prefix => entry.resolved.startsWith(prefix));
+    if (!tarball && !registry) throw new Error('Unsupported compiler package source');
     const value: CompilerPackage = { lockLocation, name: metadata.name, version: metadata.version, integrity: entry.integrity, source: { kind: tarball ? 'tarball' : 'registry', identity: entry.integrity }, payload, payloadDigest };
     if (this.packages.has(lockLocation) && semanticHash(this.packages.get(lockLocation)) !== semanticHash(value)) throw new Error('Compiler package payload drift');
     this.packages.set(lockLocation, value);

package/runtime/delivery/compiler-pins.ts

@@ -39,7 +39,7 @@ export const compilerTaskPins: Record<string, string[]> = {
     "086f478dc6172a8ad8053f21b47637cde5ed55e76fd68f4d19b957ca2ba89356"
   ],
   "compile:solidity:get-source-names": [
-    "a1b8fb51de8eafdf94e28fac8ba9402e0e6e01268a07118bb1b9c30f029abce9",
+    "cde87b363a60ee09606119b95a59091d185514660b13b860a9d1fd72586034c4",
     "9583d07a487241a306f8f3664134538b3090a176a3f21deffac38351f3b67221"
   ],
   "compile:solidity:read-file": [