gate-evm-tools 1.0.31 → 1.2.1

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-capture.ts

@@ -1,32 +1,42 @@
-/** Narrow R1→R2 handoff: capture the currently installed producer and changing containers BEFORE prod edits. */
+/** Preserve accepted development inputs and one shared, compressed producer snapshot. */
 import fs from 'node:fs';
 import path from 'node:path';
 import {gzipSync} from 'node:zlib';
 import {readInputBytes} from './input-files';
 import {confinedFile,projectRoot} from './project-files';
-import {atomicDevelopmentWrite,byteHash,developmentPath} from './materialization';
+import {byteHash,developmentPath} from './materialization';
 import {canonicalJson,semanticHash} from '../workflow/lib/canonicalData';
 import {parseDeliveryPlan} from './plan';
 import {safeId} from './protocol';
+import {persistDevelopmentInputs,writeImmutableDeliveryFile} from './development-inputs';
 import type {DeliveryAggregate,DeliveryAggregateOptions} from './aggregate';
 import type {HistoricalDevelopmentFiles} from './release-history';
 export function captureDevelopmentReleaseHistory(input:{root:string;source:DeliveryAggregateOptions;aggregate:DeliveryAggregate}):HistoricalDevelopmentFiles {
  const root=fs.realpathSync(input.root),a=input.aggregate,plan=parseDeliveryPlan(a.collections[0]?.plan);
  if(input.source.selection!=='development'||a.collections.length!==1||plan.environment!=='dev'||projectRoot(input.source.workspaceRoot,input.source.projectRoot)!==root)throw Error('Historical capture requires original development source');
  safeId(plan.executionId,'executionId');
- const base=`.gate-delivery/history/${plan.executionId}`,readyPath=`${base}/READY.json`;
+ const base=`.gate-delivery/history/${plan.executionId}`,readyFile=`${base}/READY.json`;
  const acceptanceFile=`.gate-delivery/development/${plan.executionId}.acceptance.json`,acceptance=JSON.parse(readInputBytes(root,acceptanceFile).toString());
  if(acceptance.status!=='accepted'||acceptance.planHash!==plan.planHash||acceptance.inputsHash!==a.inputsHash||semanticHash(acceptance.runtimeIdentity)!==semanticHash(plan.runtimeIdentity))throw Error('Historical capture requires actual accepted development');
  const original=a.inputs.runtime.package;if(original.name!=='gate-evm-tools'||original.lockLocation!=='node_modules/gate-evm-tools')throw Error('Unsupported historical producer location');
+ // A completed capture can be reused after the installed producer changes.
+ if(fs.existsSync(developmentPath(root,readyFile))){
+  const ready=JSON.parse(readInputBytes(root,readyFile).toString());
+  if(ready.schema!=='gate-delivery-history-ready'||ready.version!==2||ready.generation!=='complete'||ready.planHash!==plan.planHash||ready.aggregateHash!==semanticHash(a)||ready.sourceHash!==semanticHash(input.source)||ready.descriptor?.version!==2||ready.descriptor.readyFile!==readyFile||!Array.isArray(ready.files)||!ready.files.length)throw Error('Conflicting historical capture');
+  for(const f of ready.files)if(byteHash(readInputBytes(root,f.path))!==f.sha256)throw Error('Captured historical file drift');
+  return ready.descriptor;
+ }
  const files:Array<{path:string;digest:string;base64:string}>=[];
  const visit=(relative:string)=>{const dir=confinedFile(root,`${original.lockLocation}/${relative}`.replace(/\/$/,''),'directory');for(const name of fs.readdirSync(dir).sort()){const rel=relative?`${relative}/${name}`:name;const stat=fs.lstatSync(path.join(dir,name));if(stat.isDirectory()){if(name==='node_modules')continue;visit(rel);}else{const bytes=readInputBytes(root,`${original.lockLocation}/${rel}`);files.push({path:rel,digest:byteHash(bytes),base64:bytes.toString('base64')});}}};visit('');files.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
  if(semanticHash(files.map(({path,digest})=>({path,digest})))!==semanticHash(original.payload))throw Error('Historical capture must precede producer/runtime replacement');
- const descriptor:HistoricalDevelopmentFiles={aggregateFile:`${base}/aggregate.json`,sourceFile:`${base}/source.json`,acceptanceFile,packageRoot:`${base}/package`,inputsRoot:`${base}/inputs`,archiveFile:`${base}/package.snapshot.json.gz`};
- if(fs.existsSync(developmentPath(root,readyPath))){const ready=JSON.parse(readInputBytes(root,readyPath).toString());if(ready.schema!=='gate-delivery-history-ready'||ready.generation!=='complete'||ready.planHash!==plan.planHash||ready.aggregateHash!==semanticHash(a))throw Error('Conflicting historical capture');for(const f of ready.files)if(byteHash(readInputBytes(root,f.path))!==f.sha256)throw Error('Captured historical file drift');return descriptor;}
+ const archive=gzipSync(Buffer.from(canonicalJson({schema:'gate-delivery-package-snapshot',version:2,runtimeIdentity:plan.runtimeIdentity,observedPackage:original,files})));
+ const archiveFile=`.gate-delivery/packages/${byteHash(archive)}.json.gz`;
  const saved:Array<{path:string;sha256:string}>=[];
- const write=(relative:string,bytes:Buffer)=>{const file=developmentPath(root,relative);fs.mkdirSync(path.dirname(file),{recursive:true,mode:0o700});if(fs.existsSync(file)&&!readInputBytes(root,relative).equals(bytes))throw Error('Partial historical capture conflict');const fd=fs.openSync(file,'w',0o600);try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}saved.push({path:relative,sha256:byteHash(bytes)});};
- for(const file of files)write(`${base}/package/${file.path}`,Buffer.from(file.base64,'base64'));
+ const write=(relative:string,bytes:Buffer)=>saved.push(writeImmutableDeliveryFile(root,relative,bytes));
+ const {sourcePath:sourceFile,aggregatePath:aggregateFile}=persistDevelopmentInputs(input);
+ const descriptor:HistoricalDevelopmentFiles={version:2,aggregateFile,sourceFile,acceptanceFile,readyFile,inputsRoot:`${base}/inputs`,archiveFile};
+ for(const relative of [sourceFile,aggregateFile,acceptanceFile])saved.push({path:relative,sha256:byteHash(readInputBytes(root,relative))});
  for(const name of [`${a.inputs.business.businessRoot}/task.yaml`,`${a.inputs.business.businessRoot}/parameters.yaml`,`${a.inputs.business.businessRoot}/parameters.provenance.json`,'config.yaml','hardhat.config.ts','package-lock.json','contractInfo.json','deploymentInfo.json'])write(`${base}/inputs/${name}`,readInputBytes(root,name));
- write(descriptor.aggregateFile,Buffer.from(canonicalJson(a)+'\n'));write(descriptor.sourceFile,Buffer.from(canonicalJson(input.source)+'\n'));write(descriptor.archiveFile,gzipSync(Buffer.from(canonicalJson({schema:'gate-delivery-package-snapshot',version:1,runtimeIdentity:plan.runtimeIdentity,observedPackage:original,files}))));
- atomicDevelopmentWrite(root,readyPath,canonicalJson({schema:'gate-delivery-history-ready',version:1,generation:'complete',planHash:plan.planHash,aggregateHash:semanticHash(a),descriptor,files:saved})+'\n');return descriptor;
+ write(archiveFile,archive);
+ writeImmutableDeliveryFile(root,readyFile,Buffer.from(canonicalJson({schema:'gate-delivery-history-ready',version:2,generation:'complete',planHash:plan.planHash,aggregateHash:semanticHash(a),sourceHash:semanticHash(input.source),descriptor,files:saved})+'\n'));return descriptor;
 }

package/runtime/delivery/release-history.ts

@@ -1,15 +1,18 @@
 /** 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 {projectRoot} from './project-files';
 import {parseCanonicalPlan,projectCanonicalDefinitions} from './source';
 import {parseConfigurationDefinition} from './configuration-definition';
 import {parseDeliveryPublicTargets} from './config';
+import {object,safeId} from './protocol';
+import {readHistoricalPackage} from './history-package';
 import {readProjectNetworkSnapshots} from './project';
 import {parseDeliveryPlan} from './plan';
 import {parsePreparationJournal} from './journal';
@@ -25,48 +28,79 @@ 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';
-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}))});}
+import {resolveParameterTargets} from './parameter-defaults';
+import {validateHistoricalParameterExtension,type ParameterInputs} from './parameters';
+import {validateHistoricalBusinessExtension} from './business-extension';
+import {parseNativeOperation} from './custom';
+export interface HistoricalDevelopmentFiles {version:2;aggregateFile:string;sourceFile:string;acceptanceFile:string;readyFile:string;inputsRoot:string;archiveFile:string}
 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}){
  const workspace=projectRoot(input.workspaceRoot,'.'),root=projectRoot(workspace,input.projectRoot),{history}=input,files=new Map<string,string>();
  if(fs.realpathSync(input.root)!==root)throw Error('Historical current project root mismatch');
+ object(history,'historical descriptor',['version','aggregateFile','sourceFile','acceptanceFile','readyFile','inputsRoot','archiveFile']);
+ if(history.version!==2)throw Error('Unsupported historical descriptor version');
  const read=(relative:string)=>{const bytes=readInputBytes(root,relative);files.set(relative,inputDigest(bytes));return bytes;};
  const aggregate=JSON.parse(read(history.aggregateFile).toString()) as DeliveryAggregate,source=JSON.parse(read(history.sourceFile).toString()) as DeliveryAggregateOptions,acceptance=JSON.parse(read(history.acceptanceFile).toString());
  if(source.projectRoot!==input.projectRoot)throw Error('Historical relative project scope mismatch');
  if(source.selection!=='development'||source.targets.length!==1||aggregate.collections.length!==1||aggregate.inputs.business.targets.length!==1)throw Error('Historical development scope mismatch');
  same(aggregateInputHash(aggregate),aggregate.inputsHash,'Historical aggregate inputs');same(semanticHash(aggregate.inputs.sourceDefinitions),aggregate.sourceDefinitionHash,'Historical source hash');
  const collection=aggregate.collections[0],plan=parseDeliveryPlan(collection.plan),target=aggregate.inputs.business.targets[0];
+ const id=safeId(plan.executionId,'executionId'),base=`.gate-delivery/history/${id}`;
+ if(history.aggregateFile!==`.gate-delivery/development/${id}.aggregate.json`||history.sourceFile!==`.gate-delivery/development/${id}.source.json`||history.acceptanceFile!==`.gate-delivery/development/${id}.acceptance.json`||history.readyFile!==`${base}/READY.json`||history.inputsRoot!==`${base}/inputs`||!/^\.gate-delivery\/packages\/[a-f0-9]{64}\.json\.gz$/.test(history.archiveFile))throw Error('Noncanonical historical descriptor');
  if(plan.environment!=='dev'||plan.target!==target.id||source.targets[0].request.network!==plan.target||source.targets[0].executionId!==plan.executionId)throw Error('Historical development identity mismatch');
  for(const key of ['executionId','planHash','target','inputsHash','sourceDefinitionHash','runtimeIdentity'] as const)same(acceptance[key],plan[key],`Historical acceptance ${key}`);
  if(acceptance.version!==1||acceptance.status!=='accepted')throw Error('Missing historical acceptance');
- const readyPath=path.posix.dirname(history.aggregateFile)+'/READY.json',ready=JSON.parse(read(readyPath).toString());
- if(ready.schema!=='gate-delivery-history-ready'||ready.version!==1||ready.generation!=='complete'||ready.planHash!==plan.planHash||ready.aggregateHash!==semanticHash(aggregate)||!Array.isArray(ready.files)||!ready.files.length)throw Error('Historical snapshot generation is not READY');
+ const ready=JSON.parse(read(history.readyFile).toString());
+ if(ready.schema!=='gate-delivery-history-ready'||ready.version!==2||ready.generation!=='complete'||ready.planHash!==plan.planHash||ready.aggregateHash!==semanticHash(aggregate)||ready.sourceHash!==semanticHash(source)||!Array.isArray(ready.files)||!ready.files.length)throw Error('Historical snapshot generation is not READY');
  same(ready.descriptor,history,'Historical READY descriptor');for(const file of ready.files)if(byteHash(read(file.path))!==file.sha256)throw Error('Historical READY file binding mismatch');
  const original=aggregate.inputs.runtime.package;
  same(aggregate.inputs.runtime.declared,plan.runtimeIdentity,'Historical runtime identity');
  if(original.name!=='gate-evm-tools'||original.version!==plan.runtimeIdentity.version||original.source.identity!==original.integrity)throw Error('Historical producer provenance mismatch');
- const archive=read(history.archiveFile),snapshot=JSON.parse(gunzipSync(archive).toString());
- if(snapshot.schema!=='gate-delivery-package-snapshot'||snapshot.version!==1||!Array.isArray(snapshot.files))throw Error('Invalid historical package snapshot archive');
- const archived=snapshot.files.map((f:any)=>{const bytes=Buffer.from(f.base64,'base64');if(bytes.toString('base64')!==f.base64||byteHash(bytes)!==f.digest)throw Error('Historical snapshot archive bytes mismatch');return {path:f.path,digest:f.digest};});
- same(archived,original.payload,'Historical archive complete payload');same(snapshot.observedPackage,original,'Historical snapshot provenance');same(snapshot.runtimeIdentity,plan.runtimeIdentity,'Historical snapshot runtime');
- const payload:Array<{path:string;digest:string}>=[];
- const visit=(relative:string)=>{const dir=confinedFile(root,`${history.packageRoot}/${relative}`.replace(/\/$/,''),'directory');for(const name of fs.readdirSync(dir).sort()){if(name==='node_modules')throw Error('Historical producer nested package unsupported');const rel=relative?`${relative}/${name}`:name,p=confinedFile(root,`${history.packageRoot}/${rel}`,fs.lstatSync(path.join(dir,name)).isDirectory()?'directory':'file');if(fs.lstatSync(p).isDirectory())visit(rel);else payload.push({path:rel,digest:inputDigest(read(`${history.packageRoot}/${rel}`))});}};
- visit('');payload.sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);same(payload,original.payload,'Historical producer actual payload');same(byteHash(payload.map(f=>`${f.path}\0${f.digest}\n`).join('')),original.payloadDigest,'Historical payload digest');
- 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 archive=read(history.archiveFile),packageFiles=readHistoricalPackage(archive,history.archiveFile,aggregate);
  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)?packageFiles.get(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 +112,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 +135,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 +149,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; }
+}