gate-evm-tools 1.0.31 → 1.2.0

package/runtime/delivery/release-graph.ts

@@ -1,24 +1,33 @@
 /** Actual-file release graph classification. No caller-selected roots or target subsets. */
-import {parseCanonicalPlan,projectCanonicalDefinitions} from './source';
+import {parseCanonicalPlan,projectCanonicalDefinitions,deploymentPurpose} from './source';
 import {projectRoot} from './project-files';
 import {readInputBytes,parseInputDocument,assertUnambiguousHandoff} from './input-files';
 import {canonicalJson,deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
-import {safeId,portablePath} from './protocol';
+import {safeId,portablePath,object} from './protocol';
 export interface ReleaseGraphOptions {workspaceRoot:string;projectRoot:string;handoff:string;taskId:string;deploymentId:string;releaseRef:{path:string;releaseId:string;inputsHash:string}}
 export const sameReleaseData=(a:unknown,b:unknown,label:string):void=>{if(canonicalJson(a)!==canonicalJson(b))throw Error(`${label} mismatch`);};
-const stages=['release-prepare','release-execute','release-verify'];
+/** A completed simulation-only script task supplies reports, never on-chain acceptance. */
+export function isDevelopmentAcceptancePrerequisite(task:Parameters<typeof deploymentPurpose>[0]){
+ const d=task.scope?.deployment as any;
+ return deploymentPurpose(task)==='dev-execution'&&Array.isArray(d?.allowedActions)&&d.allowedActions.some((action:string)=>action!=='simulate');
+}
 export function readReleaseUniverse(input:Omit<ReleaseGraphOptions,'releaseRef'>){
  const workspace=projectRoot(input.workspaceRoot,'.'),root=projectRoot(workspace,input.projectRoot);
  safeId(input.deploymentId,'deploymentId');portablePath(input.handoff,'handoff');
  const text=readInputBytes(workspace,input.handoff).toString();assertUnambiguousHandoff(text);
  const plan=parseCanonicalPlan(text);if(plan.taskId!==input.taskId)throw Error('Current task identity mismatch');
- const task=exactObject(parseInputDocument(readInputBytes(root,`scripts/tasks/${input.deploymentId}/task.yaml`),'yaml'),['version','id','developmentNetwork','releaseTargetNetworks'],'task.yaml');
+ const task=object(parseInputDocument(readInputBytes(root,`scripts/tasks/${input.deploymentId}/task.yaml`),'yaml'),'task.yaml',['version','id','developmentNetwork','releaseTargetNetworks','requirementRef','productionRequirementRef','referenceDeploymentId']);
  if(task.version!==1||task.id!==input.deploymentId||!Array.isArray(task.releaseTargetNetworks)||!task.releaseTargetNetworks.length)throw Error('Invalid release target scope');
  const targets=task.releaseTargetNetworks as string[];if(new Set(targets).size!==targets.length)throw Error('Duplicate release target');
  const entries=Object.entries(plan.tasks).flatMap(([lane,tasks])=>tasks.map(task=>({lane,task}))),relevant=entries.filter(({task:t})=>{const d=t.scope?.deployment as any;return d?.projectRoot===input.projectRoot&&d?.deploymentId===input.deploymentId;});
- for(const {task:t} of relevant){const d=t.scope!.deployment as any;sameReleaseData(d.developmentNetwork,task.developmentNetwork,'Current development target');sameReleaseData(d.releaseTargetNetworks,targets,'Current selected targets');}
- const qualifications=targets.map(target=>{const rows=relevant.filter(({task:t})=>t.step==='deploy-test'&&(t.scope!.deployment as any).targetNetwork===target);if(rows.length!==1)throw Error('Missing or ambiguous qualification target');const row=rows[0],d=row.task.scope!.deployment as any;if(plan.lanes[row.lane].state!=='enabled'||row.task.status==='cancelled'||d.environment!=='prod'||d.releaseRef!==undefined)throw Error('Ineligible qualification task');sameReleaseData(d.allowedActions,['simulate','verify'],'Qualification allowedActions');return row.task;});
- if(relevant.some(({task:t})=>t.step==='deploy-test'&&!targets.includes((t.scope!.deployment as any).targetNetwork)))throw Error('Unknown qualification target');
+ for(const {task:t} of relevant){const d=t.scope!.deployment as any;sameReleaseData(d.developmentNetwork,task.developmentNetwork,'Current development target');
+  if(['prod-qualification','prod-execution'].includes(deploymentPurpose(t)!)){
+   sameReleaseData(d.releaseTargetNetworks,targets,'Current selected targets');
+   sameReleaseData(d.productionRequirementRef??null,task.productionRequirementRef??null,'Current production confirmation');
+  }else if((d.releaseTargetNetworks??[]).some((network:string)=>!targets.includes(network)))throw Error('Current selected targets removed a development-declared target');
+ }
+ const qualifications=targets.map(target=>{const rows=relevant.filter(({task:t})=>deploymentPurpose(t)==='prod-qualification'&&(t.scope!.deployment as any).targetNetwork===target);if(rows.length!==1)throw Error('Missing or ambiguous qualification target');const row=rows[0],d=row.task.scope!.deployment as any;if(plan.lanes[row.lane].state!=='enabled'||row.task.status==='cancelled'||d.environment!=='prod'||d.releaseRef!==undefined)throw Error('Ineligible qualification task');sameReleaseData([...d.allowedActions].sort(),['simulate','verify'],'Qualification allowedActions');return row.task;});
+ if(relevant.some(({task:t})=>deploymentPurpose(t)==='prod-qualification'&&!targets.includes((t.scope!.deployment as any).targetNetwork)))throw Error('Unknown qualification target');
  const upstream=projectCanonicalDefinitions(text,{roots:qualifications.map(t=>t.planKey),mode:'upstream'});
  return {workspace,root,text,plan,entries,relevant,targets,qualifications,upstream,developmentNetwork:task.developmentNetwork as string};
 }
@@ -26,12 +35,31 @@ export function readReleaseGraph(input:ReleaseGraphOptions){
  const u=readReleaseUniverse(input);safeId(input.releaseRef.releaseId,'releaseId');portablePath(input.releaseRef.path,'releaseRef.path');if(!/^[a-f0-9]{64}$/.test(input.releaseRef.inputsHash))throw Error('Invalid release input hash');
  // Classify ALL relevant production tasks first. Filtering a good ref first conceals split/wrong bindings.
  const groups=new Map<string,typeof u.relevant>();
- for(const row of u.relevant.filter(({task})=>stages.includes(task.step??''))){const d=row.task.scope!.deployment as any,ref=d.releaseRef;if(!ref)throw Error('Missing release binding');const key=canonicalJson(ref),rows=groups.get(key)??[];rows.push(row);groups.set(key,rows);}
+ for(const row of u.relevant.filter(({task})=>deploymentPurpose(task)==='prod-execution')){const d=row.task.scope!.deployment as any,ref=d.releaseRef;if(!ref)throw Error('Missing release binding');const key=canonicalJson(ref),rows=groups.get(key)??[];rows.push(row);groups.set(key,rows);}
  const selectedKey=canonicalJson(input.releaseRef);
  for(const [key,rows] of groups){const ref=(rows[0].task.scope!.deployment as any).releaseRef;if(ref.releaseId===input.releaseRef.releaseId&&key!==selectedKey)throw Error('Split release binding');
-  if(rows.length!==u.targets.length*3)throw Error('Incomplete or duplicate production stage graph');
-  for(const target of u.targets){const chain=stages.map(step=>{const matches=rows.filter(({task})=>task.step===step&&(task.scope!.deployment as any).targetNetwork===target);if(matches.length!==1)throw Error('Missing or duplicate release stage');return matches[0];});
-   for(const [index,{lane,task}] of chain.entries()){const d=task.scope!.deployment as any;if(u.plan.lanes[lane].state!=='enabled'||task.status==='cancelled'||d.environment!=='prod')throw Error('Ineligible production task');const required=index===0?u.qualifications.find(t=>(t.scope!.deployment as any).targetNetwork===target)!.planKey:chain[index-1].task.planKey;if(!task.dependsOn.includes(required))throw Error('Split release dependency graph');const allowed=index===0?['simulate']:index===1?['execute','export-calldata','reconcile']:['verify'];sameReleaseData(d.allowedActions,allowed,'Release allowedActions');}
+  if(rows.some(({task})=>!u.targets.includes((task.scope!.deployment as any).targetNetwork)))throw Error('Unknown production target');
+  const byKey=new Map(u.entries.map(row=>[row.task.planKey,row.task]));
+  const ancestors=(task:typeof rows[number]['task'],seen=new Set<string>()):Set<string>=>{for(const id of task.dependsOn){if(seen.has(id))continue;seen.add(id);const prior=byKey.get(id);if(prior)ancestors(prior,seen);}return seen;};
+  for(const target of u.targets){
+   const tasks=rows.filter(({task})=>(task.scope!.deployment as any).targetNetwork===target).sort((a,b)=>a.task.no-b.task.no);
+   if(!tasks.length)throw Error('Missing complete release stage graph');
+   const qualification=u.qualifications.find(t=>(t.scope!.deployment as any).targetNetwork===target)!;
+   const actions=(task:typeof rows[number]['task'])=>(task.scope!.deployment as any).allowedActions as string[];
+   const prepares=tasks.filter(({task})=>actions(task).includes('simulate'));
+   const effects=tasks.filter(({task})=>actions(task).some(a=>['execute','export-calldata'].includes(a)));
+   const verifies=tasks.filter(({task})=>actions(task).includes('verify'));
+   if(!prepares.length||!effects.length||!verifies.length)throw Error('Incomplete production stage graph: simulate, execute/export and verify required');
+   for(let index=1;index<tasks.length;index++)if(!ancestors(tasks[index].task).has(tasks[index-1].task.planKey))throw Error('Split or duplicate release dependency graph');
+   if(!actions(tasks.at(-1)!.task).includes('verify'))throw Error('Production graph must finish with verification');
+   for(const {lane,task} of tasks){
+    const d=task.scope!.deployment as any,upstream=ancestors(task);
+    if(u.plan.lanes[lane].state!=='enabled'||task.status==='cancelled'||d.environment!=='prod')throw Error('Ineligible production task');
+    if(actions(task).some(a=>['execute','export-calldata'].includes(a))&&!actions(task).some(a=>['reconcile','verify'].includes(a)))throw Error('Production effect task requires reconcile or verify to observe completion');
+    if(!upstream.has(qualification.planKey))throw Error('Split release dependency graph');
+    if(actions(task).some(a=>['execute','export-calldata'].includes(a))&&!prepares.some(p=>p.task.planKey===task.planKey||upstream.has(p.task.planKey)))throw Error('Missing production preparation dependency');
+    if(actions(task).includes('verify')&&effects.some(e=>e.task.planKey!==task.planKey&&!upstream.has(e.task.planKey)))throw Error('Missing production verification dependency');
+   }
   }
  }
  const selected=groups.get(selectedKey);if(!selected)throw Error('Missing complete release graph');
@@ -41,9 +69,11 @@ export function readReleaseGraph(input:ReleaseGraphOptions){
 /** Progress is deliberately outside sourceDefinitionHash: eligibility is checked anew. */
 export function currentReleasePrerequisites(input:Omit<ReleaseGraphOptions,'releaseRef'>){
  const u=readReleaseUniverse(input),keys=new Set(u.upstream.snapshot.tasks.map(t=>t.planKey)),qual=new Set(u.qualifications.map(t=>t.planKey));
- const required=u.entries.filter(({lane,task})=>keys.has(task.planKey)&&!qual.has(task.planKey)&&u.plan.lanes[lane].state==='enabled');
- for(const row of u.entries){if(['development','audit'].includes(row.lane)&&u.plan.lanes[row.lane].state==='enabled'&&!keys.has(row.task.planKey))throw Error('Mandatory prerequisite missing from current closure');}
- for(const step of ['deploy','check-code'])if(!required.some(r=>r.task.step===step))throw Error(`Missing development acceptance prerequisite: ${step}`);
+ const requirementKeys=new Set(u.relevant.map(({task})=>(task.scope?.deployment as any)?.requirementRef?.planKey).filter(Boolean));
+ const required=u.entries.filter(({lane,task})=>keys.has(task.planKey)&&!qual.has(task.planKey)&&!requirementKeys.has(task.planKey)&&u.plan.lanes[lane].state==='enabled');
+ // Explicit dependencies (including the requirement's prerequisites) define this
+ // round. Unrelated development/audit work appended later is not a prerequisite.
+ if(!required.some(({task})=>{const d=task.scope?.deployment as any;return isDevelopmentAcceptancePrerequisite(task)&&d.deploymentId===input.deploymentId&&d.projectRoot===input.projectRoot&&d.environment==='dev'&&d.targetNetwork===u.developmentNetwork&&d.allowedActions.includes('verify');}))throw Error('Missing development acceptance prerequisite: verify');
  for(const {task} of required)if(task.status!=='completed'||task.result?.kind!=='success'||task.adoptedRev!==task.rev)throw Error(`Current prerequisite is incomplete or stale: ${task.planKey}`);
  return {...u,required};
 }

package/runtime/delivery/release-history.ts

@@ -1,15 +1,19 @@
 /** Read-only consumption of R1 evidence. Historical runtime is verified, never executed or relabelled. */
 import {existingCodeCoverage,requiredExistingAddresses} from './existing-code';
 import fs from 'node:fs';
+import {aggregateInputHash} from './execution-identity';
+export {aggregateInputHash} from './execution-identity';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {gzipSync,gunzipSync} from 'node:zlib';
 import {Contract,JsonRpcProvider} from 'ethers';
+import {BytecodeChecker,TRANSPARENT_PROXY_ARTIFACT,PROXY_ADMIN_ARTIFACT,ERC1967_ADMIN_SLOT,PROXY_ADMIN_INTERFACE,transparentAdminAddress,assertTransparentAdminImmutable} from 'gate-evm-tools/workflow';
 import {readInputBytes,inputDigest,parseInputDocument} from './input-files';
 import {confinedFile,projectRoot} from './project-files';
 import {parseCanonicalPlan,projectCanonicalDefinitions} from './source';
 import {parseConfigurationDefinition} from './configuration-definition';
 import {parseDeliveryPublicTargets} from './config';
+import {object} from './protocol';
 import {readProjectNetworkSnapshots} from './project';
 import {parseDeliveryPlan} from './plan';
 import {parsePreparationJournal} from './journal';
@@ -25,8 +29,11 @@ import {validateDevelopmentCheckReport,type ExpectedDevelopmentCode} from './che
 import {sameReleaseData as same} from './release-graph';
 import type {DeliveryAggregate,DeliveryAggregateOptions} from './aggregate';
 import {historicalRegistrationFile,validateHistoricalRegistration} from './history-registration';
+import {resolveParameterTargets} from './parameter-defaults';
+import {validateHistoricalParameterExtension,type ParameterInputs} from './parameters';
+import {validateHistoricalBusinessExtension} from './business-extension';
+import {parseNativeOperation} from './custom';
 export interface HistoricalDevelopmentFiles {aggregateFile:string;sourceFile:string;acceptanceFile:string;packageRoot:string;inputsRoot:string;archiveFile:string}
-export function aggregateInputHash(a:DeliveryAggregate){return semanticHash({version:1,business:a.inputs.business,sourceDefinitions:a.inputs.sourceDefinitions,runtime:a.inputs.runtime,files:a.inputs.files,targets:a.inputs.targets.map(r=>({target:r.target,configuration:r.configuration.configurationRuntimeHash,sourceConfiguration:r.sourceConfiguration.configurationRuntimeHash,compiler:r.compiler.stableDigest,custom:r.custom}))});}
 function decode(raw:any):any{const v=parseTypedValue(raw);switch(v.type){case 'bigint':return BigInt(v.value);case 'number':return Number(v.value);case 'array':return v.value.map(decode);case 'object':return Object.fromEntries(Object.entries(v.value).map(([k,x])=>[k,decode(x)]));default:return v.value;}}
 /** Every mutable historical container is retained with its ORIGINAL digest; allowed deltas are explicit. */
 export function validateHistoricalDevelopmentFiles(input:{root:string;workspaceRoot:string;projectRoot:string;history:HistoricalDevelopmentFiles}){
@@ -57,16 +64,47 @@ export function validateHistoricalDevelopmentFiles(input:{root:string;workspaceR
  const digest=createHash('sha256');const hashDir=(dir:string)=>{for(const name of fs.readdirSync(confinedFile(root,`${history.packageRoot}/${dir}`,'directory')).sort()){const rel=`${dir}/${name}`,file=confinedFile(root,`${history.packageRoot}/${rel}`,fs.lstatSync(path.join(root,history.packageRoot,rel)).isDirectory()?'directory':'file');if(fs.lstatSync(file).isDirectory())hashDir(rel);else if(/\.(?:c?js)$/.test(rel)){digest.update(rel);digest.update(read(`${history.packageRoot}/${rel}`));}}};for(const dir of ['dist-runtime','dist','dist-cjs','bin'])hashDir(dir);same(digest.digest('hex'),plan.runtimeIdentity.digest,'Historical executable runtime digest');
  const business=aggregate.inputs.business.businessRoot,mutable=new Set([`${business}/task.yaml`,`${business}/parameters.yaml`,`${business}/parameters.provenance.json`,'config.yaml','hardhat.config.ts']);
  const old=(file:string)=>read(`${history.inputsRoot}/${file}`),now=(file:string)=>read(file);
+ const evolving=new Set([`${business}/manifest.yaml`,`${business}/parameters.schema.json`].filter(file=>{
+  const originalFile=aggregate.inputs.files.find(entry=>entry.path===file);
+  return originalFile!==undefined&&inputDigest(now(file))!==originalFile.digest;
+ }));
+ if(evolving.size){
+  const previous=aggregate.inputs.business.parameters.find(entry=>entry.target===plan.target)?.resolved;
+  if(!previous)throw Error('Historical shared-step evolution requires complete accepted parameter evidence');
+  const metadata=parseInputDocument(now(`${business}/task.yaml`),'yaml') as any;
+  const resolved=resolveParameterTargets(parseInputDocument(now(`${business}/parameters.yaml`),'yaml'),parseInputDocument(now(`${business}/parameters.provenance.json`),'json'),[plan.target,...metadata.releaseTargetNetworks]);
+  const current=validateHistoricalParameterExtension(previous,{schema:parseInputDocument(now(`${business}/parameters.schema.json`),'json') as any,
+   target:plan.target,values:resolved.params[plan.target],sources:resolved.params,...resolved.observations[plan.target]} as ParameterInputs);
+  const manifest=object(parseInputDocument(now(`${business}/manifest.yaml`),'yaml'),'manifest.yaml',['id','description','steps']);
+  if(manifest.id!==plan.deploymentId||!Array.isArray(manifest.steps))throw Error('Historical shared manifest identity changed');
+  validateHistoricalBusinessExtension({before:aggregate.inputs.business.steps,after:manifest.steps.map(parseNativeOperation),previous,current,target:target as unknown as Record<string,unknown>});
+ }
  const ownPayload=new Set(original.payload.map(file=>`${original.lockLocation}/${file.path}`));
  // The entire old frozen file union is verified. Only owned producer bytes and bounded containers have historical locations.
- for(const file of aggregate.inputs.files){const bytes=ownPayload.has(file.path)?read(`${history.packageRoot}/${file.path.slice(original.lockLocation.length+1)}`):mutable.has(file.path)?old(file.path):now(file.path);if(inputDigest(bytes)!==file.digest)throw Error(`Historical immutable input drift: ${file.path}`);}
+ for(const file of aggregate.inputs.files){if(evolving.has(file.path))continue;const bytes=ownPayload.has(file.path)?read(`${history.packageRoot}/${file.path.slice(original.lockLocation.length+1)}`):mutable.has(file.path)?old(file.path):now(file.path);if(inputDigest(bytes)!==file.digest)throw Error(`Historical immutable input drift: ${file.path}`);}
  const oldTask=parseInputDocument(old(`${business}/task.yaml`),'yaml') as any,newTask=parseInputDocument(now(`${business}/task.yaml`),'yaml') as any;
- same({...newTask,releaseTargetNetworks:oldTask.releaseTargetNetworks},oldTask,'Historical development task container');
+ const {productionRequirementRef:_production,...newBase}=newTask;
+ same({...newBase,releaseTargetNetworks:oldTask.releaseTargetNetworks,...(oldTask.productionRequirementRef===undefined?{}:{productionRequirementRef:oldTask.productionRequirementRef})},oldTask,'Historical development task container');
  if(!Array.isArray(newTask.releaseTargetNetworks)||oldTask.releaseTargetNetworks.some((x:string)=>!newTask.releaseTargetNetworks.includes(x)))throw Error('Historical production target removal');
  const prod=new Set<string>(newTask.releaseTargetNetworks);
- for(const file of ['parameters.yaml','parameters.provenance.json']){const before=parseInputDocument(old(`${business}/${file}`),file.endsWith('.json')?'json':'yaml') as any,after=parseInputDocument(now(`${business}/${file}`),file.endsWith('.json')?'json':'yaml') as any;const container=file==='parameters.yaml'?'params':'targets';const projection=(value:any)=>({...value,[container]:Object.fromEntries(Object.entries(value[container]).filter(([k])=>!prod.has(k)))});same(projection(after),projection(before),'Historical dev parameter values/provenance');}
+ for(const file of ['parameters.yaml','parameters.provenance.json']){
+  const before=parseInputDocument(old(`${business}/${file}`),file.endsWith('.json')?'json':'yaml') as any,after=parseInputDocument(now(`${business}/${file}`),file.endsWith('.json')?'json':'yaml') as any;
+  const container=file==='parameters.yaml'?'params':'targets';
+  if(file.endsWith('.json'))for(const [id,definition] of Object.entries(before.producers))same(after.producers[id],definition,'Historical existing producer definition');
+  const projection=(value:any)=>({...value,...(file.endsWith('.json')?{producers:before.producers}:{}),[container]:Object.fromEntries(Object.entries(value[container]).filter(([k])=>!prod.has(k)&&!(evolving.size&&k===plan.target)))});
+  same(projection(after),projection(before),'Historical dev parameter values/provenance');
+ }
  const oldConfig=parseInputDocument(old('config.yaml'),'yaml') as any,newConfig=parseInputDocument(now('config.yaml'),'yaml') as any;
- same(Object.fromEntries(Object.entries(newConfig).filter(([k])=>!prod.has(k))),Object.fromEntries(Object.entries(oldConfig).filter(([k])=>!prod.has(k))),'Historical development configuration');
+ // Prod defaults do not participate in dev inheritance. Keep shared/dev defaults and network overrides bound.
+ const devConfig=(value:unknown)=>{
+  const config=object(value,'config.yaml'),projected=Object.fromEntries(Object.entries(config).filter(([k])=>k!=='_profiles'&&!prod.has(k)));
+  if(config._profiles!==undefined){
+   const {prod:_prod,...profiles}=object(config._profiles,'_profiles',['baseProfile','dev','prod']);
+   if(Object.keys(profiles).length)projected._profiles=profiles;
+  }
+  return projected;
+ };
+ same(devConfig(newConfig),devConfig(oldConfig),'Historical development configuration');
  const previous=parseConfigurationDefinition(old('hardhat.config.ts'),plan.target).definition,current=parseConfigurationDefinition(now('hardhat.config.ts'),plan.target).definition;
  // Existing Hardhat networks remain identical; only newly selected production aliases may be added.
  for(const [name,value] of Object.entries(previous.networks))same(current.networks[name],value,'Historical effective network');
@@ -78,7 +116,7 @@ export function validateHistoricalDevelopmentFiles(input:{root:string;workspaceR
  for(const file of dependencyFiles)if(inputDigest(now(file.path))!==file.digest)throw Error('Historical custom/producer dependency changed');
  const handoff=source.targets[0].request.sourceRef.path,text=readInputBytes(workspace,handoff).toString(),actual=parseCanonicalPlan(text);if(actual.taskId!==source.targets[0].request.sourceRef.taskId)throw Error('Historical task source identity mismatch');
  const projection=projectCanonicalDefinitions(text,{roots:[source.targets[0].request.sourceRef.planKey],mode:'upstream'}).snapshot;
- const normalize=(v:any)=>{const copy=JSON.parse(canonicalJson(v));for(const t of copy.tasks)if(t.scope?.deployment)t.scope.deployment.releaseTargetNetworks=oldTask.releaseTargetNetworks;return copy;};
+ const normalize=(v:any)=>{const copy=JSON.parse(canonicalJson(v));for(const t of copy.tasks)if(t.scope?.deployment&&Object.hasOwn(t.scope.deployment,'releaseTargetNetworks'))t.scope.deployment.releaseTargetNetworks=oldTask.releaseTargetNetworks;return copy;};
  const historical=(aggregate.inputs.sourceDefinitions as any[]);if(historical.length!==1||historical[0].path!==handoff)throw Error('Historical source document mismatch');same(normalize(projection),historical[0].definition,'Historical upstream definition with bounded prod expansion');
  const expected=expectedDevelopmentAssertions(collection,aggregate.inputs.business.steps);
  if(!Array.isArray(acceptance.assertions)||acceptance.assertions.length!==expected.length)throw Error('Missing development business assertions');
@@ -101,13 +139,13 @@ export function validateHistoricalDevelopmentFiles(input:{root:string;workspaceR
  for(const [key,value] of Object.entries({identity:acceptance.identity,executionId:plan.executionId,planHash:plan.planHash,inputsHash:plan.inputsHash,sourceDefinitionHash:plan.sourceDefinitionHash,runtimeIdentity:plan.runtimeIdentity,preparations,finalized,assertions:acceptance.assertions}))same(record[key],value,`Historical deployment record ${key}`);
  if(!Array.isArray(record.changes))throw Error('Missing development registry changes');
  const expectedCode:ExpectedDevelopmentCode[]=[],effective:any={[plan.target]:{}};
- for(const change of record.changes){effective[plan.target][change.contractInfoKey]=change.address;const key=change.contractInfoKey.split(':')[0];expectedCode.push({key,contract:change.actualContract,address:change.implementationAddress??change.address});if(change.proxyKind==='uups')expectedCode.push({key:`${key}_Proxy`,contract:'ERC1967Proxy',address:change.address});}
+ for(const change of record.changes){effective[plan.target][change.contractInfoKey]=change.address;const key=change.contractInfoKey.split(':')[0];expectedCode.push({key,contract:change.actualContract,address:change.implementationAddress??change.address});if(change.proxyKind)expectedCode.push({key:`${key}_Proxy`,contract:change.proxyKind==='transparent'?'TransparentUpgradeableProxy':'ERC1967Proxy',address:change.address});if(change.proxyKind==='transparent')expectedCode.push({key:`${key}_ProxyAdmin`,contract:'ProxyAdmin',address:change.proxyAdminAddress});}
  const pure=!preparations.length?existingCodeCoverage({target:plan.target,addresses:requiredExistingAddresses(collection),registry:JSON.parse(historicalRegistration('contractInfo.json').toString()),metadata:JSON.parse(historicalRegistration('deploymentInfo.json').toString()),compiler:aggregate.inputs.targets.find(t=>t.target===plan.target)!.compiler,manifests:(acceptance.materialization.manifests??[]).map((m:any)=>({path:m.file,contents:now(m.file).toString()}))}):null;
  if(pure){if(record.changes.length)throw Error('Pure-call history cannot invent deployment changes');Object.assign(effective,pure.effective);expectedCode.push(...pure.expected);same(acceptance.materialization.manifests,pure.manifests,'Historical existing manifests');}
  const code=acceptance.checkCode;if(code?.version!==1||code.executionId!==plan.executionId||code.planHash!==plan.planHash||code.target!==plan.target||typeof code.rawFile!=='string'||!code.rawFile.startsWith(`.gate-delivery/check-code/${plan.executionId}/`))throw Error('Missing real CheckCode identity');
  same(byteHash(historicalRegistration('contractInfo.json')),code.registryHash,'Historical registry');same(byteHash(historicalRegistration('deploymentInfo.json')),code.metadataHash,'Historical deployment metadata');same(byteHash(canonicalJson(effective)+'\n'),code.effectiveHash,'Historical CheckCode effective registry');
  const raw=now(code.rawFile);same(byteHash(raw),code.rawHash,'Historical real raw CheckCode');validateDevelopmentCheckReport(JSON.parse(raw.toString()),plan.target,expectedCode);same(code.artifacts,pure?.artifacts??preparations.map(p=>p.prepared.plan.artifact),'Historical CheckCode artifacts');
- const manifests=acceptance.materialization.manifests;if(!Array.isArray(manifests)||record.changes.some((c:any)=>c.proxyKind==='uups')&&!manifests.length)throw Error('Missing official manifest evidence');for(const m of manifests)same(byteHash(now(m.file)),m.hash,'Historical official manifest');
+ const manifests=acceptance.materialization.manifests;if(!Array.isArray(manifests)||record.changes.some((c:any)=>(c.proxyKind==='uups'||c.proxyKind==='transparent'))&&!manifests.length)throw Error('Missing official manifest evidence');for(const m of manifests)same(byteHash(now(m.file)),m.hash,'Historical official manifest');
  return deepFreeze({aggregate,source,acceptance,plan,files:[...files].map(([path,digest])=>({path,digest})),association:{version:1,historicalInputsHash:aggregate.inputsHash,historicalRuntime:plan.runtimeIdentity,historicalSnapshotSha256:byteHash(archive),observedLockIntegrity:original.integrity,installation:'owned-installed-payload-snapshot@1',developmentTarget:plan.target,oldProductionTargets:oldTask.releaseTargetNetworks,currentProductionTargets:newTask.releaseTargetNetworks,rule:'dev-preserving-prod-container-extension@1'}});
 }
 /** Actual read-only receipts and business state. No signing, compilation, mutation or old-runtime execution. */
@@ -115,6 +153,26 @@ export async function verifyHistoricalDevelopmentChain(result:ReturnType<typeof
  const {plan,acceptance,aggregate}=result,snapshot=readProjectNetworkSnapshots(root,[plan.target])[0],provider=new JsonRpcProvider(snapshot.url,undefined,{staticNetwork:false});
  try{const rpc={request:(method:string,params:readonly unknown[])=>provider.send(method,[...params])};const context={executionId:plan.executionId,planHash:plan.planHash,releaseHash:plan.inputsHash,operator:plan.operator,policyHash:semanticHash({historical:true}),chainId:plan.chainId,target:plan.target,finality:{kind:'confirmations' as const,depth:String(Math.max(1,aggregate.inputs.business.targets[0].finality.confirmations))}};
  for(const [index,observation] of acceptance.finalized.entries())same(await observeEoaTransaction({plan,context,provider:rpc,index,transactionHash:observation.transactionHash}),observation,'Current historical finalized receipt');
+ // Recheck exercised Transparent administration from the accepted metadata and sealed
+ // compiler output. No project code or historical runtime is loaded.
+ const journal=readDevelopmentJournal(root,plan.executionId),metadataFile=journal?.files.find((f:{path:string;after:string})=>f.path==='deploymentInfo.json');
+ if(!metadataFile)throw Error('Historical deployment metadata missing');
+ const metadata=JSON.parse(metadataFile.after).networks?.[plan.target]??{},raw=JSON.parse(readInputBytes(root,acceptance.checkCode.rawFile).toString())[plan.target];
+ const compiler=aggregate.inputs.targets.find(t=>t.target===plan.target)!.compiler,checker=new BytecodeChecker(undefined as never,{},'evm');
+ for(const [alias,m] of Object.entries(metadata) as Array<[string,any]>)if(m.proxyKind==='transparent'&&Object.hasOwn(raw,`${alias}_ProxyAdmin`)){
+  const admin=m.proxyAdminAddress?.toLowerCase();if(!admin||admin!==transparentAdminAddress(m.address)||!m.proxyAdminOwner)throw Error('Historical Transparent admin identity mismatch');
+  const slot=await provider.getStorage(m.address,ERC1967_ADMIN_SLOT);if(!/^0x0{24}[a-fA-F0-9]{40}$/.test(slot)||'0x'+slot.slice(-40).toLowerCase()!==admin)throw Error('Historical Transparent admin slot mismatch');
+  for(const name of [TRANSPARENT_PROXY_ARTIFACT,PROXY_ADMIN_ARTIFACT]){
+   const matches=compiler.artifacts.filter(a=>a.fqn===name);if(matches.length!==1)throw Error('Historical Transparent artifact missing');
+   const entry=matches[0],artifact=entry.artifact,build=compiler.builds.find(b=>b.digest===entry.buildInfo),refs=build&&JSON.parse(build.contents).output?.contracts?.[artifact.sourceName]?.[artifact.contractName]?.evm?.deployedBytecode?.immutableReferences;
+   if(!refs)throw Error('Historical Transparent compiler output missing');
+   const code=await provider.getCode(name===PROXY_ADMIN_ARTIFACT?admin:m.address);if(code==='0x'||!checker.compareBytecode(code,artifact.deployedBytecode!,artifact.abi as any[],refs).matches)throw Error('Historical Transparent runtime mismatch');
+   if(name===TRANSPARENT_PROXY_ARTIFACT)assertTransparentAdminImmutable(code,refs,admin);
+  }
+  const owner=PROXY_ADMIN_INTERFACE.decodeFunctionResult('owner',await provider.call({to:admin,data:PROXY_ADMIN_INTERFACE.encodeFunctionData('owner')}))[0];
+  const version=PROXY_ADMIN_INTERFACE.decodeFunctionResult('UPGRADE_INTERFACE_VERSION',await provider.call({to:admin,data:PROXY_ADMIN_INTERFACE.encodeFunctionData('UPGRADE_INTERFACE_VERSION')}))[0];
+  if(owner.toLowerCase()!==m.proxyAdminOwner.toLowerCase()||version!=='5.0.0')throw Error('Historical ProxyAdmin owner/version mismatch');
+ }
  for(const assertion of acceptance.assertions){const contract=new Contract(assertion.address,assertion.abi,provider),actual=await contract.getFunction(assertion.method).staticCall(...decode(assertion.args)),comparison=compareAbiResults(assertion.abi,assertion.method,actual,decode(assertion.expected));if(comparison.actual!==comparison.expected)throw Error('Current historical development business assertion failed');}
  }finally{provider.destroy();}
 }

package/runtime/delivery/release-inputs.ts

@@ -0,0 +1,107 @@
+/** Exact deployment input bytes, independent of whether deployment scripts were committed. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readInputBytes, inputDigest } from './input-files';
+import { confinedFile } from './project-files';
+import { portablePath } from './protocol';
+import { strictData } from './data';
+import { canonicalJson, deepFreeze, exactObject, semanticHash } from '../workflow/lib/canonicalData';
+import type { ContractSourceIdentity } from './contract-source';
+import type { DeliveryAggregate } from './aggregate';
+
+export interface ReleaseInputSnapshot {
+  schema: 'gate-delivery-input-snapshot';
+  version: 1;
+  contractSource: ContractSourceIdentity;
+  files: Array<{ path: string; digest: string; base64: string }>;
+  snapshotHash: string;
+}
+export interface ReleaseInputSnapshotRef { path: string; hash: string; sha256: string }
+const encode = (value: unknown) => canonicalJson(value) + '\n';
+function inputPath(raw: unknown): string {
+  const file=portablePath(raw, 'release input path');
+  if (file.split('/').some(part => /^(?:node_modules|\.git|\.gate-delivery|rpc\.env|\.env(?:\..*)?|\.npmrc|\.ssh)$/.test(part))
+    || /^scripts\/tasks\/[^/]+\/(?:releases|results)(?:\/|$)/.test(file)) throw Error('Unsupported release snapshot input path');
+  return file;
+}
+export function captureReleaseInputs(root: string, aggregate: DeliveryAggregate, contractSource: ContractSourceIdentity): Readonly<ReleaseInputSnapshot> {
+  // Config snapshots retain source expressions, never evaluated signing credentials.
+  const literalCredential=(value:any):boolean=>value&&typeof value==='object'&&(value.kind==='literal'
+    ? value.definitionHash!==inputDigest('gate-delivery-secret-definition@1\0')
+    : Object.values(value).some(literalCredential));
+  for(const target of aggregate.inputs.targets)for(const network of Object.values(target.configuration.configuration.definition?.networks??{}) as any[])
+    if(literalCredential(network.accounts))throw Error('Signing credentials must use environment references before deployment inputs are archived');
+  const wanted = new Map<string, string | undefined>();
+  for (const file of [...aggregate.inputs.files, ...contractSource.files]) {
+    if (file.path.split('/').includes('node_modules')) continue;
+    inputPath(file.path);
+    if (wanted.has(file.path) && wanted.get(file.path) !== file.digest) throw Error('Conflicting release snapshot input');
+    wanted.set(file.path, file.digest);
+  }
+  for (const file of ['package.json', 'package-lock.json', 'tsconfig.json']) {
+    if (!wanted.has(file) && fs.existsSync(confinedFile(root, file))) wanted.set(file, undefined);
+  }
+  const files = [...wanted].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([file, expected]) => {
+    const bytes = readInputBytes(root, file), digest = inputDigest(bytes);
+    if (expected !== undefined && expected !== digest) throw Error(`Release snapshot input changed: ${file}`);
+    return { path: file, digest, base64: bytes.toString('base64') };
+  });
+  const body = { schema: 'gate-delivery-input-snapshot' as const, version: 1 as const, contractSource, files };
+  return deepFreeze({ ...body, snapshotHash: semanticHash(body) });
+}
+/** Validate the entire payload before inspecting current inputs or writing any restored files. */
+export function parseReleaseInputSnapshot(raw: unknown): Readonly<ReleaseInputSnapshot> {
+  const data = exactObject(strictData(raw), ['schema', 'version', 'contractSource', 'files', 'snapshotHash'], 'release input snapshot');
+  const { snapshotHash, ...body } = data;
+  if (data.schema !== 'gate-delivery-input-snapshot' || data.version !== 1 || semanticHash(body) !== snapshotHash || !Array.isArray(data.files) || !data.files.length)
+    throw Error('Invalid release input snapshot identity');
+  const source = exactObject(data.contractSource, ['version', 'commit', 'projectPath', 'sourcesDirectory', 'files', 'sourceHash'], 'contract source identity');
+  if (source.version !== 1 || typeof source.commit!=='string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(source.commit) || !Array.isArray(source.files) || !source.files.length
+    || source.sourceHash !== semanticHash({ sourcesDirectory: source.sourcesDirectory, files: source.files })) throw Error('Invalid release contract source identity');
+  for (const directory of [source.projectPath, source.sourcesDirectory]) if (directory !== '.') portablePath(directory, 'contract source directory');
+  const files = new Map<string, string>();
+  let previous = '';
+  for (const rawFile of data.files) {
+    const file = exactObject(rawFile, ['path', 'digest', 'base64'], 'snapshot file');
+    const filePath=inputPath(file.path);
+    if (typeof file.base64 !== 'string' || typeof file.digest!=='string' || !/^[a-f0-9]{64}$/.test(file.digest) || filePath <= previous) throw Error('Invalid or duplicate release snapshot file');
+    const bytes = Buffer.from(file.base64, 'base64');
+    if (bytes.toString('base64') !== file.base64 || inputDigest(bytes) !== file.digest) throw Error('Release snapshot file bytes changed');
+    previous = filePath; files.set(filePath, file.digest);
+  }
+  const seen = new Set<string>();
+  for (const rawFile of source.files) {
+    const file = exactObject(rawFile, ['path', 'digest'], 'contract source file');
+    const filePath=inputPath(file.path);
+    if (seen.has(filePath) || files.get(filePath) !== file.digest) throw Error('Missing or conflicting snapshotted contract source');
+    seen.add(filePath);
+  }
+  return deepFreeze(data as unknown as ReleaseInputSnapshot);
+}
+export function readReleaseInputSnapshot(root: string, ref: ReleaseInputSnapshotRef): Readonly<ReleaseInputSnapshot> {
+  exactObject(ref, ['path', 'hash', 'sha256'], 'release input snapshot reference');
+  const bytes = readInputBytes(root, ref.path);
+  if (inputDigest(bytes) !== ref.sha256) throw Error('Release input snapshot bytes changed');
+  const snapshot = parseReleaseInputSnapshot(JSON.parse(bytes.toString()));
+  if (snapshot.snapshotHash !== ref.hash || bytes.toString() !== encode(snapshot)) throw Error('Release input snapshot reference mismatch');
+  return snapshot;
+}
+/** Restore into a new external directory only. This grants no execution/readiness authority. */
+export function restoreReleaseInputs(root: string, ref: ReleaseInputSnapshotRef, destination: string) {
+  const snapshot = readReleaseInputSnapshot(root, ref);
+  if (typeof destination !== 'string' || !path.isAbsolute(destination)) throw Error('Release restore destination must be absolute');
+  const output = path.join(fs.realpathSync(path.dirname(destination)), path.basename(destination));
+  const source = fs.realpathSync(root);
+  if (output === source || output.startsWith(source + path.sep)) throw Error('Release inputs must be restored outside the current project');
+  if (fs.existsSync(output)) throw Error('Release restore destination already exists');
+  fs.mkdirSync(output, { mode: 0o700 });
+  try {
+    for (const file of snapshot.files) {
+      const target = confinedFile(output, file.path);
+      fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(target, Buffer.from(file.base64, 'base64'), { flag: 'wx', mode: 0o600 });
+    }
+    return deepFreeze({ status: 'inputs-restored' as const, destination: output, contractSource: snapshot.contractSource,
+      snapshotHash: snapshot.snapshotHash, files: snapshot.files.map(({ path, digest }) => ({ path, digest })) });
+  } catch (error) { fs.rmSync(output, { recursive: true, force: true }); throw error; }
+}

package/runtime/delivery/release.ts

@@ -1,3 +1,5 @@
+import {deploymentPurpose} from './source';
+import {parseCalldataReviews} from './calldata-review';
 /** Developer-owned production qualification and two-phase, marker-last release publication. */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11,13 +13,16 @@ import {parsePreparationJournal} from './journal';
 import {expectedDevelopmentAssertions} from './development';
 import {verifyCapturedForkAudit} from './forkAudit';
 import {parseCanonicalPlan,projectCanonicalDefinitions} from './source';
-import {readReleaseUniverse,currentReleasePrerequisites,readReleaseGraph,sameReleaseData as same,type ReleaseGraphOptions} from './release-graph';
+import {readReleaseUniverse,currentReleasePrerequisites,readReleaseGraph,isDevelopmentAcceptancePrerequisite,sameReleaseData as same,type ReleaseGraphOptions} from './release-graph';
 import {aggregateInputHash,validateHistoricalDevelopmentFiles,verifyHistoricalDevelopmentChain,type HistoricalDevelopmentFiles} from './release-history';
 import {atomicDevelopmentWrite,fileBytes,withDevelopmentFileLock,byteHash} from './materialization';
 import {canonicalJson,deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
 import {strictData} from './data';
 import {historicalRegistrationFile} from './history-registration';
-export {readReleaseGraph} from './release-graph';
+import {captureCommittedContractSource} from './contract-source';
+import {captureReleaseInputs,readReleaseInputSnapshot,restoreReleaseInputs} from './release-inputs';
+export type {ContractSourceIdentity} from './contract-source';
+export {readReleaseGraph,isDevelopmentAcceptancePrerequisite} from './release-graph';
 export {captureDevelopmentReleaseHistory} from './release-history-capture';
 export type {HistoricalDevelopmentFiles} from './release-history';
 type Scope=Omit<ReleaseGraphOptions,'releaseRef'>;
@@ -32,10 +37,11 @@ function taskEvidence(input:Scope&{planKey:string}){
  if(!row||plan.lanes[row.lane].state!=='enabled'||row.task.status!=='completed'||row.task.result?.kind!=='success'||row.task.adoptedRev!==row.task.rev)throw Error('Prerequisite current task is incomplete or stale');
  const result=row.task.result,codeRef=result.codeRef??(row.task.scope?.deployment as any)?.sourceCodeRef;
  if(typeof codeRef!=='string'||!codeRef.trim()||!Array.isArray(result.evidence)||!result.evidence.length)throw Error('Prerequisite requires codeRef and actual report evidence');
- const artifacts=result.evidence.map((entry:any)=>{if(!entry||typeof entry.ref!=='string')throw Error('Prerequisite report ref missing');portablePath(entry.ref,'prerequisite artifact');const bytes=readInputBytes(root,entry.ref);if(!bytes.length)throw Error('Empty prerequisite report');return {path:entry.ref,sha256:inputDigest(bytes)};});
- for(const expected of row.task.expectedArtifacts??[])if(!artifacts.some(a=>a.path===expected))throw Error('Missing declared prerequisite artifact');
- if(new Set(artifacts.map(a=>a.path)).size!==artifacts.length)throw Error('Duplicate prerequisite artifact');
- if(row.lane==='audit'&&!artifacts.some(a=>a.path==='audit-reports/security-audit-report.md'))throw Error('Audit prerequisite requires actual security audit report');
+ const refs=result.evidence.map((entry:any)=>{if(!entry||typeof entry.ref!=='string')throw Error('Prerequisite report ref missing');return entry.ref as string;});
+ if(new Set(refs).size!==refs.length)throw Error('Duplicate prerequisite artifact');
+ for(const expected of row.task.expectedArtifacts??[])if(!refs.includes(expected))refs.push(expected);
+ const artifacts=refs.map(ref=>{portablePath(ref,'prerequisite artifact');const bytes=readInputBytes(root,ref);if(!bytes.length)throw Error('Empty prerequisite report/artifact');return {path:ref,sha256:inputDigest(bytes)};});
+ if(row.lane==='audit'&&!result.evidence.some((entry:any)=>entry.ref==='audit-reports/security-audit-report.md'))throw Error('Audit prerequisite requires actual security audit report');
  return {root,envelope:{schema:'gate-delivery-prerequisite',version:1,producer:'gate-evm-tools/delivery-release',taskId:plan.taskId,planKey:row.task.planKey,rev:row.task.rev,definitionHash:semanticHash(projectCanonicalDefinitions(text,{roots:[row.task.planKey],mode:'full'}).snapshot),codeRef,artifacts}};
 }
 /** Invoke after the corresponding skill has produced its report and completed the current task.
@@ -44,15 +50,17 @@ export function recordDeliveryPrerequisite(input:Scope&{planKey:string}){const {
 export function validateDeliveryPrerequisite(input:Scope&{planKey:string}){const {root,envelope}=taskEvidence(input),actual=JSON.parse(readInputBytes(root,prerequisitePath(input.taskId,input.planKey)).toString());same(actual,envelope,'Current prerequisite report/artifact binding');return deepFreeze(actual);}
 function prerequisites(scope:Scope,history:ReturnType<typeof validateHistoricalDevelopmentFiles>){
  const current=currentReleasePrerequisites(scope),receipts=[];
- for(const {task} of current.required){if(['deploy','check-code'].includes(task.step??'')){const d=task.scope?.deployment as any;if(d?.environment!=='dev'||d.targetNetwork!==history.plan.target||d.deploymentId!==history.plan.deploymentId)throw Error('Development prerequisite scope mismatch');if(task.step==='deploy'&&(task.planKey!==history.source.targets[0].request.sourceRef.planKey||task.rev!==history.source.targets[0].request.sourceRef.rev))throw Error('Stale development prerequisite revision');const evidence=task.result?.evidence;if(!Array.isArray(evidence)||!evidence.some((e:any)=>e.ref===scopePath(history,task.step!)))throw Error('Development prerequisite must reference actual acceptance/CheckCode');receipts.push({planKey:task.planKey,rev:task.rev,definitionHash:semanticHash(projectCanonicalDefinitions(current.text,{roots:[task.planKey],mode:'full'}).snapshot),evidenceHash:semanticHash(task.step==='deploy'?history.acceptance:history.acceptance.checkCode)});}
+ for(const {task} of current.required){if(isDevelopmentAcceptancePrerequisite(task)){const d=task.scope?.deployment as any;if(d?.environment!=='dev'||d.targetNetwork!==history.plan.target||d.deploymentId!==history.plan.deploymentId)throw Error('Development prerequisite scope mismatch');if(!verificationOnly(task)&&(task.planKey!==history.source.targets[0].request.sourceRef.planKey||task.rev!==history.source.targets[0].request.sourceRef.rev))throw Error('Stale development prerequisite revision');const evidence=task.result?.evidence;if(!Array.isArray(evidence)||!evidence.some((e:any)=>e.ref===scopePath(history,verificationOnly(task))))throw Error('Development prerequisite must reference actual acceptance/CheckCode');receipts.push({planKey:task.planKey,rev:task.rev,definitionHash:semanticHash(projectCanonicalDefinitions(current.text,{roots:[task.planKey],mode:'full'}).snapshot),evidenceHash:semanticHash(verificationOnly(task)?history.acceptance.checkCode:history.acceptance)});}
   else receipts.push(validateDeliveryPrerequisite({...scope,planKey:task.planKey}));}
  return receipts;
 }
-function scopePath(history:ReturnType<typeof validateHistoricalDevelopmentFiles>,step:string){return step==='check-code'?history.acceptance.checkCode.rawFile:`.gate-delivery/development/${history.plan.executionId}.acceptance.json`;}
+function verificationOnly(task:any){const actions=task.scope?.deployment?.allowedActions;return Array.isArray(actions)&&actions.length===1&&actions[0]==='verify';}
+function scopePath(history:ReturnType<typeof validateHistoricalDevelopmentFiles>,verifyOnly:boolean){return verifyOnly?history.acceptance.checkCode.rawFile:`.gate-delivery/development/${history.plan.executionId}.acceptance.json`;}
 function verifyQualification(aggregate:DeliveryAggregate,source:DeliveryAggregateOptions){
  if(aggregate.version!==1||aggregateInputHash(aggregate)!==aggregate.inputsHash||semanticHash(aggregate.inputs.sourceDefinitions)!==aggregate.sourceDefinitionHash)throw Error('Qualification aggregate identity mismatch');
  same(aggregate.collections.map(c=>c.plan.target),aggregate.inputs.business.targets.map(t=>t.id),'Complete target qualification');same(source.targets.map(t=>t.request.network),aggregate.inputs.business.targets.map(t=>t.id),'Current selected target order');
  for(const [i,c] of aggregate.collections.entries()){const plan=parseDeliveryPlan(c.plan),request=source.targets[i].request;
+  parseCalldataReviews(c.calldata,plan.transactions);
   if(plan.environment!=='prod'||plan.inputsHash!==aggregate.inputsHash||plan.sourceDefinitionHash!==aggregate.sourceDefinitionHash||plan.executionId!==source.targets[i].executionId||plan.operator!==request.operator?.toLowerCase()||!request.fork||!plan.transactions.length)throw Error('Invalid production qualification identity');
   same(plan.runtimeIdentity,aggregate.inputs.runtime.declared,'Qualification runtime');expectedDevelopmentAssertions(c,aggregate.inputs.business.steps);
   parsePreparationJournal(c.preparations,plan.transactions,plan.derivedBindings,{target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(b=>b.stepId)});
@@ -60,17 +68,22 @@ function verifyQualification(aggregate:DeliveryAggregate,source:DeliveryAggregat
  }
 }
 function currentFiles(root:string,files:readonly {path:string;digest:string}[]){for(const file of files)if(inputDigest(readInputBytes(root,file.path))!==file.digest)throw Error(`Current release input changed: ${file.path}`);}
-function currentCandidate(scope:Scope,c:any){
+function currentCandidate(scope:Scope,c:any,requireCommittedSources=false){
  if(c.schema!=='gate-delivery-release-candidate'||c.version!==1||c.generation!=='complete'||c.producer!=='gate-evm-tools/delivery-release')throw Error('Invalid completed release candidate');
  same(c.scope,{projectRoot:scope.projectRoot,handoff:scope.handoff,taskId:scope.taskId,deploymentId:scope.deploymentId},'Release current scope');
  const {candidateHash,...body}=c;same(semanticHash(body),candidateHash,'Release candidate hash');
+ if(c.inputSnapshot?.path!==`scripts/tasks/${scope.deploymentId}/releases/${c.releaseRef.releaseId}/inputs.snapshot.json`)throw Error('Noncanonical release input snapshot reference');
  const root=projectRoot(scope.workspaceRoot,scope.projectRoot),source={workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,selection:'release' as const,targets:c.targets};
+ if(requireCommittedSources)same(captureCommittedContractSource(root,c.aggregate),c.contractSource,'Current committed contract source');
+ const snapshot=readReleaseInputSnapshot(root,c.inputSnapshot);same(snapshot.contractSource,c.contractSource,'Release snapshot contract source');
+ const snapshotFiles=new Map(snapshot.files.map(file=>[file.path,file.digest]));
+ for(const file of c.aggregate.inputs.files)if(!file.path.split('/').includes('node_modules')&&snapshotFiles.get(file.path)!==file.digest)throw Error('Release snapshot does not cover qualified input');
+ for(const file of snapshot.files)if(inputDigest(readInputBytes(root,file.path))!==file.digest)throw Error(`Current release snapshot input changed: ${file.path}`);
  verifyQualification(c.aggregate,source);currentFiles(root,c.aggregate.inputs.files);currentFiles(root,c.historical.files.filter((f:any)=>!historicalRegistrationFile(f.path)));
  same(openAggregateSources({workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,requests:c.targets.map((t:any)=>t.request)}).definitions,c.aggregate.inputs.sourceDefinitions,'Current full upstream source');
  const h=validateHistoricalDevelopmentFiles({root,workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,history:c.development});same(h.association,c.historical.association,'Historical development association');same(prerequisites(scope,h),c.prerequisites,'Current prerequisite evidence');
  same(h.files.filter(f=>historicalRegistrationFile(f.path)),c.historical.files.filter((f:any)=>historicalRegistrationFile(f.path)),'Original historical registry baseline');
  same(readReleaseUniverse(scope).targets,c.aggregate.inputs.business.targets.map((t:any)=>t.id),'Current full selected target set');
- const docs=readInputBytes(root,'docs/prod-execution-plan.md');same(inputDigest(docs),c.explanationHash,'Production execution explanation');
  return {root,source,history:h};
 }
 /** Qualification is generated by the actual owned aggregate, never accepted from caller JSON. */
@@ -81,17 +94,25 @@ export async function prepareDeliveryRelease(raw:ReleasePreparationOptions){
  if(fileBytes(root,`scripts/tasks/${deploymentId}/releases/${input.releaseId}/release.json`)!==null)throw Error('Release already has a ready marker');
  same(input.targets.map(t=>({network:t.request.network,sourceRef:t.request.sourceRef,purpose:t.request.purpose,environment:t.request.environment,mode:t.request.mode})),u.qualifications.map(t=>({network:(t.scope!.deployment as any).targetNetwork,sourceRef:{path:handoff,taskId,planKey:t.planKey,rev:t.rev},purpose:'prod-qualification',environment:'prod',mode:'simulate'})),'Exact current qualification tasks');
  const history=validateHistoricalDevelopmentFiles({root,workspaceRoot,projectRoot:relative,history:input.development}),prerequisiteEvidence=prerequisites(scope,history);
+ const committedBefore=captureCommittedContractSource(root,history.aggregate);
  await verifyHistoricalDevelopmentChain(history,root);
- const explanation=readInputBytes(root,'docs/prod-execution-plan.md').toString();for(const ref of ['manifest.yaml','parameters.yaml','recovery'])if(!explanation.includes(ref))throw Error('Production explanation must reference canonical inputs and recovery instructions');
  const source:DeliveryAggregateOptions={workspaceRoot,projectRoot:relative,selection:'release',targets:input.targets};
  const aggregate=await collectDeliveryAggregate(source);verifyQualification(aggregate,source);
+ const contractSource=captureCommittedContractSource(root,aggregate),snapshot=captureReleaseInputs(root,aggregate,contractSource);
+ same(contractSource,committedBefore,'Contract source during release qualification');
+ const inputSnapshot={path:`scripts/tasks/${deploymentId}/releases/${input.releaseId}/inputs.snapshot.json`,hash:snapshot.snapshotHash,sha256:byteHash(encode(snapshot))};
  const releaseRef={path:`scripts/tasks/${deploymentId}/releases/${input.releaseId}/release.json`,releaseId:input.releaseId,inputsHash:aggregate.inputsHash};
- const body={schema:'gate-delivery-release-candidate',version:1,generation:'complete',producer:'gate-evm-tools/delivery-release',releaseRef,scope:{projectRoot:relative,handoff,taskId,deploymentId},targets:input.targets,development:input.development,aggregate,historical:{files:history.files,association:history.association,acceptanceHash:semanticHash(history.acceptance)},prerequisites:prerequisiteEvidence,explanationHash:inputDigest(Buffer.from(explanation))};
- const candidate=deepFreeze({...body,candidateHash:semanticHash(body)});currentCandidate(scope,candidate);
- await withDevelopmentFileLock(root,async()=>{const previous=fileBytes(root,candidatePath(input.releaseId));if(previous!==null&&previous!==encode(candidate))throw Error('Release ID already belongs to a different frozen generation');atomicDevelopmentWrite(root,candidatePath(input.releaseId),encode(candidate));});
+ const body={schema:'gate-delivery-release-candidate',version:1,generation:'complete',producer:'gate-evm-tools/delivery-release',releaseRef,scope:{projectRoot:relative,handoff,taskId,deploymentId},targets:input.targets,development:input.development,aggregate,contractSource,inputSnapshot,historical:{files:history.files,association:history.association,acceptanceHash:semanticHash(history.acceptance)},prerequisites:prerequisiteEvidence};
+ const candidate=deepFreeze({...body,candidateHash:semanticHash(body)});
+ await withDevelopmentFileLock(root,async()=>{
+  const previous=fileBytes(root,candidatePath(input.releaseId));if(previous!==null&&previous!==encode(candidate))throw Error('Release ID already belongs to a different frozen generation');
+  const saved=fileBytes(root,inputSnapshot.path);if(saved!==null&&saved!==encode(snapshot))throw Error('Immutable release input snapshot conflict');
+  atomicDevelopmentWrite(root,inputSnapshot.path,encode(snapshot));currentCandidate(scope,candidate,true);
+  atomicDevelopmentWrite(root,candidatePath(input.releaseId),encode(candidate));
+ });
  return deepFreeze({status:'prepared' as const,releaseRef,sourceDefinitionHash:aggregate.sourceDefinitionHash,inputsHash:aggregate.inputsHash,candidateHash:candidate.candidateHash});
 }
-function bundleFor(c:any,graph:ReturnType<typeof readReleaseGraph>){return {schema:'gate-delivery-release',version:1,releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,prodTaskGraph:graph.graph,targets:c.aggregate.inputs.business.targets,operations:c.aggregate.inputs.business.steps,parameters:c.aggregate.inputs.business.parameters,qualification:c.aggregate.collections,runtime:c.aggregate.inputs.runtime,immutableFiles:c.aggregate.inputs.files,sourceDefinitions:c.aggregate.inputs.sourceDefinitions,historicalDevelopment:{...c.historical.association,acceptanceHash:c.historical.acceptanceHash},prerequisites:c.prerequisites,explanation:{path:'docs/prod-execution-plan.md',sha256:c.explanationHash},candidate:{path:candidatePath(c.releaseRef.releaseId),sha256:byteHash(encode(c))}};}
+function bundleFor(c:any,graph:ReturnType<typeof readReleaseGraph>){return {schema:'gate-delivery-release',version:1,releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,prodTaskGraph:graph.graph,targets:c.aggregate.inputs.business.targets,operations:c.aggregate.inputs.business.steps,parameters:c.aggregate.inputs.business.parameters,qualification:c.aggregate.collections,runtime:c.aggregate.inputs.runtime,immutableFiles:c.aggregate.inputs.files,sourceDefinitions:c.aggregate.inputs.sourceDefinitions,contractSource:c.contractSource,inputSnapshot:c.inputSnapshot,historicalDevelopment:{...c.historical.association,acceptanceHash:c.historical.acceptanceHash},prerequisites:c.prerequisites,recovery:{strategy:'resume-original-execution',instructions:'Reconcile the original per-network executionId before retrying; preserve submitted transactions, receipts and finality records. Never replay completed operations as a new execution.'},candidate:{path:candidatePath(c.releaseRef.releaseId),sha256:byteHash(encode(c))}};}
 /** Finalizer rereads the actual handoff AFTER mainAgent writes all existing production stages. */
 export async function finalizeDeliveryRelease(raw:Scope&{releaseId:string;onFileCommitted?:(file:string)=>void}){
  // Detach own scalar data before the RPC boundary; caller options may be reused while it awaits.
@@ -103,16 +124,16 @@ export async function finalizeDeliveryRelease(raw:Scope&{releaseId:string;onFile
  if(Object.values(input).some(value=>typeof value!=='string'))throw Error('Release finalization scope requires strings');
  safeId(input.taskId,'taskId');safeId(input.deploymentId,'deploymentId');portablePath(input.handoff,'handoff');
  const root=projectRoot(input.workspaceRoot,input.projectRoot),c=JSON.parse(readInputBytes(root,candidatePath(input.releaseId)).toString());
- const initial=currentCandidate(input,c);await verifyHistoricalDevelopmentChain(initial.history,root);
+ const initial=currentCandidate(input,c,true);await verifyHistoricalDevelopmentChain(initial.history,root);
  return withDevelopmentFileLock(root,async()=>{
-  same(JSON.parse(readInputBytes(root,candidatePath(input.releaseId)).toString()),c,'Current candidate generation');currentCandidate(input,c);
+  same(JSON.parse(readInputBytes(root,candidatePath(input.releaseId)).toString()),c,'Current candidate generation');currentCandidate(input,c,true);
   const graph=readReleaseGraph({...input,releaseRef:c.releaseRef}),bundle=bundleFor(c,graph),bundleHash=semanticHash(bundle),bundlePath=`scripts/tasks/${input.deploymentId}/releases/${input.releaseId}/bundle.json`;
   const marker={schema:'gate-delivery-release-ready',version:1,status:'release_ready',generation:'complete',releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,bundle:{path:bundlePath,hash:bundleHash,sha256:byteHash(encode(bundle))}};
   const previous=fileBytes(root,c.releaseRef.path);if(previous!==null){same(JSON.parse(previous),marker,'Published release is immutable');return inspectDeliveryRelease({...input,releaseRef:c.releaseRef});}
   const existing=fileBytes(root,bundlePath);if(existing!==null&&existing!==encode(bundle))throw Error('Immutable release bundle conflict');
   atomicDevelopmentWrite(root,bundlePath,encode(bundle));onFileCommitted?.(bundlePath);
   // Async notification or competing edits cannot publish stale graph/evidence. Authoritative marker comes last.
-  currentCandidate(input,c);same(readReleaseGraph({...input,releaseRef:c.releaseRef}),graph,'Current production graph');
+  currentCandidate(input,c,true);same(readReleaseGraph({...input,releaseRef:c.releaseRef}),graph,'Current production graph');
   if(fileBytes(root,bundlePath)!==encode(bundle))throw Error('Prepared bundle changed before publication');
   atomicDevelopmentWrite(root,c.releaseRef.path,encode(marker));return inspectDeliveryRelease({...input,releaseRef:c.releaseRef});
  });
@@ -126,3 +147,20 @@ export function inspectDeliveryRelease(input:Scope&{releaseRef:ReleaseGraphOptio
  const expected={schema:'gate-delivery-release-ready',version:1,status:'release_ready',generation:'complete',releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,bundle:{path:bundlePath,hash:semanticHash(bundle),sha256:byteHash(encode(bundle))}};
  same(marker,expected,'Complete ready content identity');same(readInputBytes(root,bundlePath).toString(),encode(bundle),'Immutable published bundle bytes');return deepFreeze({status:'release_ready' as const,release:bundle,bundleHash:marker.bundle.hash});
 }
+/** File-only historical input recovery; current project edits do not rewrite the old release. */
+export function restoreDeliveryReleaseInputs(raw:Scope&{releaseRef:ReleaseGraphOptions['releaseRef'];destination:string}){
+ const input=strictData(raw);exactObject(input,['workspaceRoot','projectRoot','handoff','taskId','deploymentId','releaseRef','destination'],'release input restore');
+ const root=projectRoot(input.workspaceRoot,input.projectRoot),ref=input.releaseRef;
+ safeId(input.deploymentId,'deploymentId');safeId(ref.releaseId,'releaseId');
+ const base=`scripts/tasks/${input.deploymentId}/releases/${ref.releaseId}`;
+ if(ref.path!==`${base}/release.json`)throw Error('Noncanonical release restore reference');
+ const marker=JSON.parse(readInputBytes(root,ref.path).toString());
+ if(marker.schema!=='gate-delivery-release-ready'||marker.version!==1||marker.status!=='release_ready'||marker.generation!=='complete')throw Error('Release restore requires a completed published release');
+ same(marker.releaseRef,ref,'Restore release reference');
+ const bytes=readInputBytes(root,`${base}/bundle.json`),bundle=JSON.parse(bytes.toString());
+ if(marker.bundle.path!==`${base}/bundle.json`||marker.bundle.sha256!==byteHash(bytes)||marker.bundle.hash!==semanticHash(bundle)||bytes.toString()!==encode(bundle))throw Error('Published release bundle changed');
+ if(bundle.schema!=='gate-delivery-release'||bundle.version!==1||bundle.inputSnapshot.path!==`${base}/inputs.snapshot.json`)throw Error('Invalid release restore bundle');
+ same(bundle.releaseRef,ref,'Restore bundle release reference');same(bundle.inputsHash,ref.inputsHash,'Restore bundle input identity');
+ const snapshot=readReleaseInputSnapshot(root,bundle.inputSnapshot);same(snapshot.contractSource,bundle.contractSource,'Restore committed contract source');
+ return {...restoreReleaseInputs(root,bundle.inputSnapshot,input.destination),releaseRef:ref};
+}

package/runtime/delivery/safe.ts

@@ -12,6 +12,7 @@ import { uint256 } from "./observations";
 import type { EoaFinality } from "./eoa-observation";
 import type { DeliveryPlan } from "./plan";
 import { SAFE_RUNTIME_HASHES } from "./safe-manifest";
+import { createCalldataInvocation } from './calldata-review';
 export const SAFE_ADAPTER = deepFreeze({
   id: "safe-1.4.1-call-only/v1",
   version: "1.4.1",
@@ -326,14 +327,24 @@ export function verifySafeExec(
 }
 export function renderSafeExport(rawPlan: unknown, raw: unknown) {
   const plan = immutableDeliveryPlan(rawPlan),
-    envelope = parseSafeEnvelope(raw, plan),
-    model = deepFreeze({
+    envelope = parseSafeEnvelope(raw, plan);
+  const unsignedExecTransaction = encodeSafeExec(envelope, '0x');
+  const payloads = envelope.operation === 1 ? [{ argumentPath: [2], invocation: createCalldataInvocation({
+    abi: multi.fragments, method: 'multiSend', args: [
+      '0x' + plan.transactions.slice(envelope.start, envelope.start + envelope.count).map(c =>
+        solidityPacked(['uint8', 'address', 'uint256', 'uint256', 'bytes'], [0, c.to, c.value, (c.data.length - 2) / 2, c.data]).slice(2)).join(''),
+    ], data: envelope.data,
+  }) }] : [];
+  const unsignedExecReview = createCalldataInvocation({ abi: SAFE_INTERFACE.fragments, method: 'execTransaction',
+    args: [...execKeys.map(k => (envelope as any)[k]), '0x'], data: unsignedExecTransaction, payloads });
+  const model = deepFreeze({
       schema: "gate-safe-export",
       version: 1,
       status: "artifact-delivered",
       plan,
       envelope,
-      unsignedExecTransaction: encodeSafeExec(envelope, "0x"),
+      unsignedExecTransaction,
+      unsignedExecReview,
     });
   const json = canonicalJson(model);
   return deepFreeze({