gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/release-history.ts

@@ -0,0 +1,178 @@
+/** 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';
+import {expectedDevelopmentAssertions} from './development';
+import {parseObservation} from './observations';
+import {observeEoaTransaction} from './eoa-observation';
+import {parseVerificationObservation} from './verification';
+import {compareAbiResults} from './abi';
+import {parseTypedValue} from '../workflow/lib/typedValue';
+import {canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
+import {readDevelopmentJournal,byteHash} from './materialization';
+import {validateDevelopmentCheckReport,type ExpectedDevelopmentCode} from './check-code';
+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}
+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');
+ 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];
+ 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');
+ 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 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){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;
+ 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';
+  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;
+ // 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');
+ if(Object.keys(current.networks).some(k=>!Object.hasOwn(previous.networks,k)&&!prod.has(k)))throw Error('Unknown added historical network');
+ same({...current,networks:previous.networks},previous,'Historical compiler/plugins/configuration');
+ same(parseDeliveryPublicTargets(now('config.yaml'),now('hardhat.config.ts'),[{network:plan.target,environment:'dev'}])[0],target,'Historical public dev target');
+ // A custom script reading a whole changed container makes the relaxed projection unsafe.
+ const dependencyFiles=[...aggregate.inputs.targets.flatMap(t=>t.custom?.files??[]),...aggregate.inputs.business.parameters.flatMap(p=>p.closure?.files??[])];
+ 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&&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');
+ for(const [index,raw] of acceptance.assertions.entries()){const assertion=parseVerificationObservation(raw);same({...assertion,actual:expected[index].actual},expected[index],'Historical complete typed assertion');const comparable=compareAbiResults(assertion.abi,assertion.method,decode(assertion.actual),decode(assertion.expected));if(comparable.actual!==comparable.expected)throw Error('Historical business assertion failed');}
+ const preparations=parsePreparationJournal(collection.preparations,plan.transactions,plan.derivedBindings,{target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(b=>b.stepId)});
+ if(!plan.transactions.length||!Array.isArray(acceptance.finalized)||acceptance.finalized.length!==plan.transactions.length)throw Error('Missing finalized development transactions');
+ const finalized=acceptance.finalized.map((v:any,index:number)=>parseObservation(v,plan,index));if(finalized.some((v:any)=>v.state!=='finalized-success')||new Set(finalized.map((v:any)=>v.transactionHash)).size!==finalized.length)throw Error('Invalid finalized development evidence');
+ const journal=readDevelopmentJournal(root,plan.executionId);if(!journal||journal.state!=='committed'||journal.identity!==acceptance.identity||journal.intentHash!==acceptance.materialization?.intentHash)throw Error('Missing committed development materialization');
+ read(`.gate-delivery/materialization/${plan.executionId}.json`);
+ const historicalRegistration=(name:string)=>{
+  const entry=journal.files.find((f:any)=>f.path===name);if(!entry)throw Error('Historical registration baseline missing');
+  // The original committed journal and accepted raw report bind these exact baseline bytes.
+  validateHistoricalRegistration(name,entry.after,readInputBytes(root,name).toString(),[...prod]);
+  const captured=`${history.inputsRoot}/${name}`;
+  if(fs.existsSync(path.join(root,captured))&&read(captured).toString()!==entry.after)throw Error('Historical captured registration differs from accepted baseline');
+  files.set(name,inputDigest(Buffer.from(entry.after)));return Buffer.from(entry.after);
+ };
+ for(const file of journal.files)if(byteHash(historicalRegistrationFile(file.path)?historicalRegistration(file.path):now(file.path))!==file.afterHash)throw Error('Current development materialization mismatch');
+ const record=JSON.parse(now(acceptance.materialization.recordPath).toString());
+ 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)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'||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. */
+export async function verifyHistoricalDevelopmentChain(result:ReturnType<typeof validateHistoricalDevelopmentFiles>,root:string){
+ 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

@@ -0,0 +1,166 @@
+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';
+import {collectDeliveryAggregate,type DeliveryAggregate,type DeliveryAggregateOptions} from './aggregate';
+import {openAggregateSources} from './aggregate-inputs';
+import {readInputBytes,inputDigest} from './input-files';
+import {projectRoot} from './project-files';
+import {safeId,portablePath} from './protocol';
+import {parseDeliveryPlan} from './plan';
+import {parsePreparationJournal} from './journal';
+import {expectedDevelopmentAssertions} from './development';
+import {verifyCapturedForkAudit} from './forkAudit';
+import {parseCanonicalPlan,projectCanonicalDefinitions} from './source';
+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';
+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'>;
+export interface ReleasePreparationOptions extends Scope {releaseId:string;targets:DeliveryAggregateOptions['targets'];development:HistoricalDevelopmentFiles}
+const encode=(data:unknown)=>canonicalJson(data)+'\n';
+const candidatePath=(id:string)=>`.gate-delivery/releases/${safeId(id,'releaseId')}/candidate.json`;
+const prerequisitePath=(taskId:string,key:string)=>`.gate-delivery/prerequisites/${safeId(taskId,'taskId')}/${safeId(key,'planKey')}.json`;
+function taskEvidence(input:Scope&{planKey:string}){
+ const workspace=projectRoot(input.workspaceRoot,'.'),root=projectRoot(workspace,input.projectRoot),text=readInputBytes(workspace,input.handoff).toString(),plan=parseCanonicalPlan(text);
+ if(plan.taskId!==input.taskId)throw Error('Prerequisite task identity mismatch');
+ const row=Object.entries(plan.tasks).flatMap(([lane,tasks])=>tasks.map(task=>({lane,task}))).find(r=>r.task.planKey===input.planKey);
+ 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 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.
+ * This binds provenance and current eligibility; it does not certify semantic audit quality. */
+export function recordDeliveryPrerequisite(input:Scope&{planKey:string}){const {root,envelope}=taskEvidence(input);atomicDevelopmentWrite(root,prerequisitePath(input.taskId,input.planKey),encode(envelope));return deepFreeze(envelope);}
+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(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 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)});
+  verifyCapturedForkAudit(c.runtimeEvidence.forkAudit,{transactions:plan.transactions,planHash:plan.planHash,chainId:plan.chainId,sourceSnapshot:{blockNumber:request.fork.blockNumber,blockHash:request.fork.blockHash}});
+ }
+}
+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,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');
+ return {root,source,history:h};
+}
+/** Qualification is generated by the actual owned aggregate, never accepted from caller JSON. */
+export async function prepareDeliveryRelease(raw:ReleasePreparationOptions){
+ const input=strictData(raw);exactObject(input,['workspaceRoot','projectRoot','handoff','taskId','deploymentId','releaseId','targets','development'],'release preparation');safeId(input.releaseId,'releaseId');
+ const {workspaceRoot,projectRoot:relative,handoff,taskId,deploymentId}=input,scope={workspaceRoot,projectRoot:relative,handoff,taskId,deploymentId},u=readReleaseUniverse(scope),root=u.root;
+ if(path.resolve(process.cwd())!==root)throw Error('Release preparation must run from actual project root');
+ 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 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,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,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.
+ const fields=Object.getOwnPropertyDescriptors(raw),hook=fields.onFileCommitted;delete fields.onFileCommitted;
+ if(hook&&(!hook.enumerable||!('value' in hook)||(hook.value!==undefined&&typeof hook.value!=='function')))throw Error('Invalid release finalization notification');
+ const onFileCommitted=hook?.value as ((file:string)=>void)|undefined;
+ const input=deepFreeze(strictData(Object.create(Object.getPrototypeOf(raw),fields))) as Scope&{releaseId:string};
+ exactObject(input,['workspaceRoot','projectRoot','handoff','taskId','deploymentId','releaseId'],'release finalization');
+ 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,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,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,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});
+ });
+}
+/** Pure file inspection: absent marker is pending, never a write or business recomputation. */
+export function inspectDeliveryRelease(input:Scope&{releaseRef:ReleaseGraphOptions['releaseRef']}){
+ const root=projectRoot(input.workspaceRoot,input.projectRoot),bytes=fileBytes(root,input.releaseRef.path);if(bytes===null)return {status:'pending' as const};
+ const marker=JSON.parse(bytes);if(marker.schema!=='gate-delivery-release-ready'||marker.version!==1||marker.status!=='release_ready'||marker.generation!=='complete')throw Error('Invalid authoritative release marker');same(marker.releaseRef,input.releaseRef,'Requested release reference');
+ const c=JSON.parse(readInputBytes(root,candidatePath(input.releaseRef.releaseId)).toString());same(c.releaseRef,input.releaseRef,'Ready candidate reference');currentCandidate(input,c);
+ const graph=readReleaseGraph(input),bundle=bundleFor(c,graph),bundlePath=`scripts/tasks/${input.deploymentId}/releases/${input.releaseRef.releaseId}/bundle.json`;
+ 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-manifest.ts

@@ -0,0 +1,11 @@
+/** Reviewed official @safe-global/safe-contracts@1.4.1 runtime identities.
+ * Source bf943f80fec5ac647159d26161446ac5d716a294, LGPL-3.0-only.
+ * Archive SHA256 8803f7cf26e2c58300b8136342faa7b8bce59436e300f52115fa25b095e0bf79.
+ * No user-supplied hash can add an implementation. */
+export const SAFE_RUNTIME_HASHES = Object.freeze({
+  Safe: "0x1fe2df852ba3299d6534ef416eefa406e56ced995bca886ab7a553e6d0c5e1c4",
+  SafeProxy:
+    "0xd7d408ebcd99b2b70be43e20253d6d92a8ea8fab29bd3be7f55b10032331fb4c",
+  MultiSendCallOnly:
+    "0xecd5bd14a08c5d2122379900b2f272bdf107a7e92423c10dd5fe3254386c9939",
+});