gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/release.ts

@@ -0,0 +1,128 @@
+/** 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,sameReleaseData as same,type ReleaseGraphOptions} from './release-graph';
+import {aggregateInputHash,validateHistoricalDevelopmentFiles,verifyHistoricalDevelopmentChain,type HistoricalDevelopmentFiles} from './release-history';
+import {atomicDevelopmentWrite,fileBytes,withDevelopmentFileLock,byteHash} from './materialization';
+import {canonicalJson,deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import {strictData} from './data';
+import {historicalRegistrationFile} from './history-registration';
+export {readReleaseGraph} from './release-graph';
+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 artifacts=result.evidence.map((entry:any)=>{if(!entry||typeof entry.ref!=='string')throw Error('Prerequisite report ref missing');portablePath(entry.ref,'prerequisite artifact');const bytes=readInputBytes(root,entry.ref);if(!bytes.length)throw Error('Empty prerequisite report');return {path:entry.ref,sha256:inputDigest(bytes)};});
+ for(const expected of row.task.expectedArtifacts??[])if(!artifacts.some(a=>a.path===expected))throw Error('Missing declared prerequisite artifact');
+ if(new Set(artifacts.map(a=>a.path)).size!==artifacts.length)throw Error('Duplicate prerequisite artifact');
+ if(row.lane==='audit'&&!artifacts.some(a=>a.path==='audit-reports/security-audit-report.md'))throw Error('Audit prerequisite requires actual security audit report');
+ 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(['deploy','check-code'].includes(task.step??'')){const d=task.scope?.deployment as any;if(d?.environment!=='dev'||d.targetNetwork!==history.plan.target||d.deploymentId!==history.plan.deploymentId)throw Error('Development prerequisite scope mismatch');if(task.step==='deploy'&&(task.planKey!==history.source.targets[0].request.sourceRef.planKey||task.rev!==history.source.targets[0].request.sourceRef.rev))throw Error('Stale development prerequisite revision');const evidence=task.result?.evidence;if(!Array.isArray(evidence)||!evidence.some((e:any)=>e.ref===scopePath(history,task.step!)))throw Error('Development prerequisite must reference actual acceptance/CheckCode');receipts.push({planKey:task.planKey,rev:task.rev,definitionHash:semanticHash(projectCanonicalDefinitions(current.text,{roots:[task.planKey],mode:'full'}).snapshot),evidenceHash:semanticHash(task.step==='deploy'?history.acceptance:history.acceptance.checkCode)});}
+  else receipts.push(validateDeliveryPrerequisite({...scope,planKey:task.planKey}));}
+ return receipts;
+}
+function scopePath(history:ReturnType<typeof validateHistoricalDevelopmentFiles>,step:string){return step==='check-code'?history.acceptance.checkCode.rawFile:`.gate-delivery/development/${history.plan.executionId}.acceptance.json`;}
+function 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;
+  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){
+ 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');
+ const root=projectRoot(scope.workspaceRoot,scope.projectRoot),source={workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,selection:'release' as const,targets:c.targets};
+ verifyQualification(c.aggregate,source);currentFiles(root,c.aggregate.inputs.files);currentFiles(root,c.historical.files.filter((f:any)=>!historicalRegistrationFile(f.path)));
+ same(openAggregateSources({workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,requests:c.targets.map((t:any)=>t.request)}).definitions,c.aggregate.inputs.sourceDefinitions,'Current full upstream source');
+ const h=validateHistoricalDevelopmentFiles({root,workspaceRoot:scope.workspaceRoot,projectRoot:scope.projectRoot,history:c.development});same(h.association,c.historical.association,'Historical development association');same(prerequisites(scope,h),c.prerequisites,'Current prerequisite evidence');
+ same(h.files.filter(f=>historicalRegistrationFile(f.path)),c.historical.files.filter((f:any)=>historicalRegistrationFile(f.path)),'Original historical registry baseline');
+ same(readReleaseUniverse(scope).targets,c.aggregate.inputs.business.targets.map((t:any)=>t.id),'Current full selected target set');
+ const docs=readInputBytes(root,'docs/prod-execution-plan.md');same(inputDigest(docs),c.explanationHash,'Production execution explanation');
+ return {root,source,history:h};
+}
+/** Qualification is generated by the actual owned aggregate, never accepted from caller JSON. */
+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);
+ await verifyHistoricalDevelopmentChain(history,root);
+ const explanation=readInputBytes(root,'docs/prod-execution-plan.md').toString();for(const ref of ['manifest.yaml','parameters.yaml','recovery'])if(!explanation.includes(ref))throw Error('Production explanation must reference canonical inputs and recovery instructions');
+ const source:DeliveryAggregateOptions={workspaceRoot,projectRoot:relative,selection:'release',targets:input.targets};
+ const aggregate=await collectDeliveryAggregate(source);verifyQualification(aggregate,source);
+ const releaseRef={path:`scripts/tasks/${deploymentId}/releases/${input.releaseId}/release.json`,releaseId:input.releaseId,inputsHash:aggregate.inputsHash};
+ const body={schema:'gate-delivery-release-candidate',version:1,generation:'complete',producer:'gate-evm-tools/delivery-release',releaseRef,scope:{projectRoot:relative,handoff,taskId,deploymentId},targets:input.targets,development:input.development,aggregate,historical:{files:history.files,association:history.association,acceptanceHash:semanticHash(history.acceptance)},prerequisites:prerequisiteEvidence,explanationHash:inputDigest(Buffer.from(explanation))};
+ const candidate=deepFreeze({...body,candidateHash:semanticHash(body)});currentCandidate(scope,candidate);
+ await withDevelopmentFileLock(root,async()=>{const previous=fileBytes(root,candidatePath(input.releaseId));if(previous!==null&&previous!==encode(candidate))throw Error('Release ID already belongs to a different frozen generation');atomicDevelopmentWrite(root,candidatePath(input.releaseId),encode(candidate));});
+ return deepFreeze({status:'prepared' as const,releaseRef,sourceDefinitionHash:aggregate.sourceDefinitionHash,inputsHash:aggregate.inputsHash,candidateHash:candidate.candidateHash});
+}
+function bundleFor(c:any,graph:ReturnType<typeof readReleaseGraph>){return {schema:'gate-delivery-release',version:1,releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,prodTaskGraph:graph.graph,targets:c.aggregate.inputs.business.targets,operations:c.aggregate.inputs.business.steps,parameters:c.aggregate.inputs.business.parameters,qualification:c.aggregate.collections,runtime:c.aggregate.inputs.runtime,immutableFiles:c.aggregate.inputs.files,sourceDefinitions:c.aggregate.inputs.sourceDefinitions,historicalDevelopment:{...c.historical.association,acceptanceHash:c.historical.acceptanceHash},prerequisites:c.prerequisites,explanation:{path:'docs/prod-execution-plan.md',sha256:c.explanationHash},candidate:{path:candidatePath(c.releaseRef.releaseId),sha256:byteHash(encode(c))}};}
+/** 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);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);
+  const graph=readReleaseGraph({...input,releaseRef:c.releaseRef}),bundle=bundleFor(c,graph),bundleHash=semanticHash(bundle),bundlePath=`scripts/tasks/${input.deploymentId}/releases/${input.releaseId}/bundle.json`;
+  const marker={schema:'gate-delivery-release-ready',version:1,status:'release_ready',generation:'complete',releaseRef:c.releaseRef,sourceDefinitionHash:c.aggregate.sourceDefinitionHash,inputsHash:c.aggregate.inputsHash,prodTaskGraphHash:graph.prodTaskGraphHash,bundle:{path:bundlePath,hash:bundleHash,sha256:byteHash(encode(bundle))}};
+  const previous=fileBytes(root,c.releaseRef.path);if(previous!==null){same(JSON.parse(previous),marker,'Published release is immutable');return inspectDeliveryRelease({...input,releaseRef:c.releaseRef});}
+  const existing=fileBytes(root,bundlePath);if(existing!==null&&existing!==encode(bundle))throw Error('Immutable release bundle conflict');
+  atomicDevelopmentWrite(root,bundlePath,encode(bundle));onFileCommitted?.(bundlePath);
+  // Async notification or competing edits cannot publish stale graph/evidence. Authoritative marker comes last.
+  currentCandidate(input,c);same(readReleaseGraph({...input,releaseRef:c.releaseRef}),graph,'Current production graph');
+  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});
+}

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",
+});