gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/project.ts

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { positiveInteger, type ProjectNetworkSnapshot } from './protocol';
+import { validateNetworkAlias } from './policy';
+
+export { stat, confinedFile, projectRoot, readFile, coreMarker } from './project-files';
+import { confinedFile, readFile } from './project-files';
+
+function unwrap(node: ts.Expression): ts.Expression {
+  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) node = node.expression;
+  return node;
+}
+function properties(node: ts.Expression, label: string): Map<string, ts.Expression> {
+  node = unwrap(node);
+  if (!ts.isObjectLiteralExpression(node)) throw new Error(`${label} must be a static object literal`);
+  const map = new Map<string, ts.Expression>();
+  for (const item of node.properties) {
+    if (!ts.isPropertyAssignment(item) || (!ts.isIdentifier(item.name) && !ts.isStringLiteral(item.name))) throw new Error(`${label} has unsupported computed or spread fields`);
+    const key = item.name.text;
+    if (['__proto__', 'constructor', 'prototype'].includes(key)) throw new Error(`Reserved prototype property in ${label}`);
+    if (map.has(key)) throw new Error(`Duplicate ${label} field: ${key}`);
+    map.set(key, unwrap(item.initializer));
+  }
+  return map;
+}
+export function parseProjectConfig(source: string): { file: ts.SourceFile; networks: Map<string, ts.Expression>; fields: Map<string, ts.Expression> } {
+  const file = ts.createSourceFile('hardhat.config.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const diagnostics = (file as ts.SourceFile & { parseDiagnostics: ts.Diagnostic[] }).parseDiagnostics;
+  if (diagnostics.length) throw new Error('Invalid hardhat.config.ts syntax');
+  const exports = file.statements.filter(ts.isExportAssignment);
+  if (exports.length !== 1 || exports[0].isExportEquals) throw new Error('Config requires one default export');
+  let config = unwrap(exports[0].expression);
+  if (ts.isIdentifier(config)) {
+    const name = config.text;
+    const declarations = file.statements.filter(ts.isVariableStatement).flatMap(statement => [...statement.declarationList.declarations]
+      .map(declaration => ({ declaration, statement }))).filter(({ declaration }) => ts.isIdentifier(declaration.name) && declaration.name.text === name);
+    if (declarations.length !== 1 || !(declarations[0].statement.declarationList.flags & ts.NodeFlags.Const) || !declarations[0].declaration.initializer) throw new Error('Config requires a static const object');
+    const declaration = declarations[0].declaration;
+    const references: ts.Identifier[] = [];
+    const visit = (node: ts.Node): void => { if (ts.isIdentifier(node) && node.text === name) references.push(node); ts.forEachChild(node, visit); };
+    visit(file);
+    if (references.some(node => node !== declaration.name && node !== config)) throw new Error('Ambiguous mutable config references');
+    config = unwrap(declaration.initializer!);
+  }
+  const fields = properties(config, 'config');
+  const networkNode = fields.get('networks');
+  if (!networkNode) throw new Error('Project config must declare networks');
+  return { file, networks: properties(networkNode, 'networks'), fields };
+}
+export function projectSourcesDirectory(root: string): string {
+  const { fields } = parseProjectConfig(readFile(root, 'hardhat.config.ts') ?? '');
+  const paths = fields.get('paths');
+  const sources = paths && properties(paths, 'paths').get('sources');
+  if (sources && !ts.isStringLiteral(sources)) throw new Error('Project paths.sources must be a static string for dependency inspection');
+  const sourcePath = sources && ts.isStringLiteral(sources) ? sources.text : 'contracts';
+  const relative = path.relative(root, path.resolve(root, sourcePath)).split(path.sep).join('/');
+  return confinedFile(root, relative, 'directory');
+}
+export function projectDefaultNetwork(root: string): string {
+  const { fields } = parseProjectConfig(readFile(root, 'hardhat.config.ts') ?? '');
+  const network = fields.get('defaultNetwork');
+  if (!network) return 'hardhat';
+  if (!ts.isStringLiteral(network)) throw new Error('Project defaultNetwork must be a static string for delivery routing');
+  return validateNetworkAlias(network.text, 'defaultNetwork');
+}
+function rpcValue(node: ts.Expression, env: NodeJS.ProcessEnv): string | undefined {
+  node = unwrap(node);
+  if (ts.isStringLiteral(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression)
+    && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process'
+    && node.expression.name.text === 'env') return env[node.name.text];
+  if (ts.isElementAccessExpression(node) && ts.isPropertyAccessExpression(node.expression)
+    && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process'
+    && node.expression.name.text === 'env' && ts.isStringLiteral(node.argumentExpression)) return env[node.argumentExpression.text];
+  if (ts.isBinaryExpression(node) && [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) {
+    const left = rpcValue(node.left, env);
+    return node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
+      ? left ?? rpcValue(node.right, env) : left || rpcValue(node.right, env);
+  }
+  throw new Error('Selected network URL must be a literal or process.env reference');
+}
+/** Read the project-owned definitions without evaluating the config, plugins or HRE. */
+export function readProjectNetworkSnapshots(root: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
+  return parseProjectNetworkSnapshots(readFile(root, 'hardhat.config.ts') ?? '', aliases, env);
+}
+/** Parse one captured project definition without rereading files or evaluating plugins/HRE. */
+export function parseProjectNetworkSnapshots(source: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
+  const { networks } = parseProjectConfig(source);
+  return aliases.map(network => {
+    validateNetworkAlias(network, 'network', false);
+    const selected = networks.get(network);
+    if (!selected || network === 'hardhat') throw new Error(`Selected project network is missing or not an RPC target: ${network}`);
+    const fields = properties(selected, `network ${network}`);
+    const chainId = fields.get('chainId');
+    if (!chainId || !ts.isNumericLiteral(chainId)) throw new Error(`Selected network ${network} requires a static chainId`);
+    if (fields.has('zksync') && fields.get('zksync')!.kind !== ts.SyntaxKind.FalseKeyword) throw new Error('Delivery requires an EVM network');
+    const url = fields.get('url');
+    if (!url) throw new Error(`Selected network ${network} requires an RPC URL definition`);
+    return { network, chainId: positiveInteger(Number(chainId.text), 'network chainId'), url: rpcValue(url, env) ?? '' };
+  });
+}
+export function integratedConfig(source: string): string {
+  const { file } = parseProjectConfig(source);
+  const imports = file.statements.filter(ts.isImportDeclaration);
+  const delivery = imports.filter(node => ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === 'gate-evm-tools/delivery-hardhat');
+  if (delivery.length > 1 || delivery.some(node => node.importClause)) throw new Error('Conflicting manual delivery plugin import');
+  // Place bootstrap before all imports, after leading comments/shebang/directives.
+  const first = file.statements.find(node => !(ts.isExpressionStatement(node) && ts.isStringLiteral(node.expression)));
+  if (!first) throw new Error('Missing project config statements');
+  if (delivery.length) {
+    if (delivery[0] !== first) throw new Error('Delivery plugin must be the first import; move it before other imports');
+    return source;
+  }
+  const at = first.getStart(file);
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  return source.slice(0, at) + `import "gate-evm-tools/delivery-hardhat";${newline}` + source.slice(at);
+}

package/runtime/delivery/protocol.ts

@@ -0,0 +1,94 @@
+/** Syntax and routing constraints only. Source verification and host authorization are separate gates. */
+import { validateNetworkAlias } from './policy';
+export type DeliveryEnvironment = 'dev' | 'prod';
+export type DeliveryMode = 'simulate' | 'execute' | 'export-calldata' | 'reconcile' | 'verify';
+export interface DeliveryRequest {
+  version: 1;
+  environment: DeliveryEnvironment;
+  purpose: 'dev-execution' | 'prod-qualification' | 'prod-execution';
+  mode: DeliveryMode;
+  network: string;
+  sourceRef: { path: string; taskId: string; planKey: string; rev: number };
+  releaseRef?: { path: string; releaseId: string; inputsHash: string };
+  fork?: { blockNumber: number; blockHash: string; readOnly: true };
+  devSigner?: string;
+  operator?: string;
+}
+export interface ProjectNetworkSnapshot { network: string; chainId: number; url: string }
+export function object(value: unknown, label: string, keys?: string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new Error(`${label} must be an object`);
+  const result = value as Record<string, unknown>;
+  if (keys && Object.keys(result).some(key => !keys.includes(key))) throw new Error(`${label} has unknown fields`);
+  return result;
+}
+export function safeId(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/.test(value)
+    || ['__proto__', 'prototype', 'constructor'].includes(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+export function portablePath(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || /[\\\0:]/.test(value)
+    || value.split('/').some(part => !part || part === '.' || part === '..'
+      || ['__proto__', 'prototype', 'constructor'].includes(part))) throw new Error(`Invalid relative ${label}`);
+  return value;
+}
+export function address(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !/^0x[\da-fA-F]{40}$/.test(value) || /^0x0{40}$/.test(value)) throw new Error(`Invalid ${label} address`);
+  return value;
+}
+export function positiveInteger(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) throw new Error(`Invalid ${label}`);
+  return value;
+}
+export function parseDeliveryRequest(input: unknown): DeliveryRequest {
+  const value = object(input, 'delivery request', ['version', 'environment', 'purpose', 'mode', 'network', 'sourceRef', 'releaseRef', 'fork', 'devSigner', 'operator']);
+  if (value.version !== 1) throw new Error('Unsupported delivery request version');
+  if (typeof value.environment !== 'string' || !['dev', 'prod'].includes(value.environment)) throw new Error('environment must be dev or prod');
+  if (typeof value.purpose !== 'string' || !['dev-execution', 'prod-qualification', 'prod-execution'].includes(value.purpose)) throw new Error('Invalid purpose');
+  const dev = value.purpose === 'dev-execution';
+  if (value.environment !== (dev ? 'dev' : 'prod')) throw new Error('purpose conflicts with environment');
+  const modes = dev ? ['simulate', 'execute', 'reconcile', 'verify'] : value.purpose === 'prod-qualification' ? ['simulate', 'verify'] : ['simulate', 'execute', 'export-calldata', 'reconcile', 'verify'];
+  if (typeof value.mode !== 'string' || !modes.includes(value.mode)) throw new Error('Explicit valid mode is required for purpose');
+  validateNetworkAlias(value.network, 'network', false);
+  const source = object(value.sourceRef, 'sourceRef', ['path', 'taskId', 'planKey', 'rev']);
+  portablePath(source.path, 'sourceRef.path'); safeId(source.taskId, 'taskId'); safeId(source.planKey, 'planKey'); positiveInteger(source.rev, 'rev');
+  if (dev) {
+    address(value.devSigner, 'devSigner');
+    if ('operator' in value) throw new Error('devSigner and prod operator are separate roles');
+  } else {
+    address(value.operator, 'operator');
+    if ('devSigner' in value) throw new Error('prod operator cannot inherit devSigner');
+  }
+  if (value.purpose === 'prod-execution') {
+    const release = object(value.releaseRef, 'releaseRef', ['path', 'releaseId', 'inputsHash']);
+    portablePath(release.path, 'releaseRef.path'); safeId(release.releaseId, 'releaseId');
+    if (typeof release.inputsHash !== 'string' || !/^[a-f0-9]{64}$/.test(release.inputsHash)) throw new Error('Invalid releaseRef.inputsHash');
+  } else if ('releaseRef' in value) throw new Error('releaseRef requires prod-execution');
+  if (value.purpose === 'prod-qualification' && value.mode === 'simulate' && !value.fork) throw new Error('prod-qualification simulate requires a pinned read-only fork');
+  if ('fork' in value) {
+    const fork = object(value.fork, 'fork', ['blockNumber', 'blockHash', 'readOnly']);
+    if (typeof fork.blockNumber !== 'number' || !Number.isSafeInteger(fork.blockNumber) || fork.blockNumber < 0) throw new Error('Invalid fork.blockNumber');
+    if (fork.readOnly !== true || typeof fork.blockHash !== 'string' || !/^0x[\da-fA-F]{64}$/.test(fork.blockHash)) throw new Error('fork must pin a block hash and be readOnly');
+    if (value.mode !== 'simulate') throw new Error('fork is only valid for simulate mode');
+  }
+  // Return detached data so callers cannot change routing during an asynchronous provider load.
+  return JSON.parse(JSON.stringify(value)) as DeliveryRequest;
+}
+export interface ChainIdProvider { request(args: { method: 'eth_chainId'; params: [] }): Promise<unknown> }
+/** Does not load HRE, signers, verify source contents, or grant execution authority. */
+export async function validateDeliveryRpc(
+  input: unknown,
+  snapshot: ProjectNetworkSnapshot,
+  loadProvider: (snapshot: ProjectNetworkSnapshot) => Promise<ChainIdProvider>,
+): Promise<{ request: DeliveryRequest; chainId: number }> {
+  const request = parseDeliveryRequest(input);
+  if (snapshot.network !== request.network) throw new Error('Selected project network snapshot mismatch');
+  const expected = positiveInteger(snapshot.chainId, 'snapshot.chainId');
+  const provider = await loadProvider({ ...snapshot });
+  const raw = await provider.request({ method: 'eth_chainId', params: [] });
+  if (typeof raw !== 'string' || !/^0x[\da-fA-F]+$/.test(raw)) throw new Error('Invalid RPC eth_chainId response');
+  const actual = BigInt(raw);
+  if (actual !== BigInt(expected)) throw new Error(`RPC chainId mismatch: expected ${expected}, actual ${actual}`);
+  return { request, chainId: expected };
+}

package/runtime/delivery/references.ts

@@ -0,0 +1,106 @@
+import { deepFreeze, semanticHash } from "../workflow/lib/canonicalData";
+import { strictData, ownPath } from "./data";
+import { PUBLIC_TARGET_FIELDS } from './target-fields';
+export const DEFERRED = Symbol("delivery.future-state");
+export interface ReferenceObservation {
+  reference: string;
+  contentIdentity: string;
+  resolvedIdentity: string;
+}
+export interface BusinessReferenceContext {
+  params: unknown;
+  target: unknown;
+  state(): unknown;
+}
+const PUBLIC_TARGET = PUBLIC_TARGET_FIELDS;
+export function parseBusinessReference(raw: unknown): string | null {
+  const value = strictData(raw);
+  let ref: unknown;
+  if (typeof value === "string" && value.startsWith("$")) ref = value.slice(1);
+  else if (
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.hasOwn(value, "$ref")
+  ) {
+    if (Object.keys(value).length !== 1)
+      throw new Error("Business $ref requires exact shape");
+    ref = (value as Record<string, unknown>).$ref;
+  } else return null;
+  if (
+    typeof ref !== "string" ||
+    !/^(param|target|state)\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(ref)
+  )
+    throw new Error("Invalid business reference namespace or path");
+  if (ref.startsWith("target.") && !PUBLIC_TARGET.has(ref.slice(7)))
+    throw new Error("Reference is outside public target boundary");
+  return ref;
+}
+export function resolveBusinessValue(
+  raw: unknown,
+  context: BusinessReferenceContext,
+  options: { deferState?: boolean } = {},
+): { value: unknown; observations: ReferenceObservation[] } {
+  const params = strictData(context.params),
+    input = strictData(raw),
+    active = new Set<string>();
+  const observations: ReferenceObservation[] = [];
+  let state: unknown,
+    stateRead = false;
+  const visit = (value: unknown): unknown => {
+    const ref = parseBusinessReference(value);
+    if (ref) {
+      if (active.has(ref)) throw new Error(`Business reference cycle: ${ref}`);
+      const [ns, ...parts] = ref.split(".");
+      if (ns === "state" && options.deferState) return DEFERRED;
+      if (ns === "state" && !stateRead) {
+        // Runtime producers may retain unrelated optional undefined metadata.
+        // Validate the selected subtree below, never invoke descriptors on the path.
+        state = context.state();
+        stateRead = true;
+      }
+      // Read only the allowlisted target leaf; secret fields are never traversed or observed.
+      const source = strictData(
+        ownPath(
+          ns === "param" ? params : ns === "state" ? state : context.target,
+          parts,
+          ref,
+        ),
+      );
+      if (ns === "target" && (source === null || typeof source === "object"))
+        throw new Error("Public target references require scalar leaves");
+      active.add(ref);
+      const resolved = visit(source);
+      active.delete(ref);
+      if (!containsDeferred(resolved))
+        observations.push({
+          reference: ref,
+          contentIdentity: semanticHash(source),
+          resolvedIdentity: semanticHash(resolved),
+        });
+      return resolved;
+    }
+    if (Array.isArray(value)) return value.map(visit);
+    if (value && typeof value === "object")
+      return Object.fromEntries(
+        Object.entries(value).map(([k, v]) => [k, visit(v)]),
+      );
+    return value;
+  };
+  return deepFreeze({
+    value: visit(input),
+    observations: observations.sort((a, b) =>
+      a.reference < b.reference ? -1 : a.reference > b.reference ? 1 : 0,
+    ),
+  });
+}
+export function containsDeferred(value: unknown): boolean {
+  return (
+    value === DEFERRED ||
+    !!(
+      value &&
+      typeof value === "object" &&
+      Object.values(value).some(containsDeferred)
+    )
+  );
+}

package/runtime/delivery/release-graph.ts

@@ -0,0 +1,49 @@
+/** Actual-file release graph classification. No caller-selected roots or target subsets. */
+import {parseCanonicalPlan,projectCanonicalDefinitions} 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';
+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'];
+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');
+ 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');
+ 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};
+}
+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);}
+ 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');}
+  }
+ }
+ const selected=groups.get(selectedKey);if(!selected)throw Error('Missing complete release graph');
+ const graph=projectCanonicalDefinitions(u.text,{roots:selected.map(r=>r.task.planKey),mode:'full'});
+ return deepFreeze({targets:u.targets,graph:graph.snapshot,prodTaskGraphHash:semanticHash(graph.snapshot)});
+}
+/** 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}`);
+ 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

@@ -0,0 +1,32 @@
+/** Narrow R1→R2 handoff: capture the currently installed producer and changing containers BEFORE prod edits. */
+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 {canonicalJson,semanticHash} from '../workflow/lib/canonicalData';
+import {parseDeliveryPlan} from './plan';
+import {safeId} from './protocol';
+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 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');
+ 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 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'));
+ 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;
+}

package/runtime/delivery/release-history.ts

@@ -0,0 +1,120 @@
+/** 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 path from 'node:path';
+import {createHash} from 'node:crypto';
+import {gzipSync,gunzipSync} from 'node:zlib';
+import {Contract,JsonRpcProvider} from 'ethers';
+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 {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';
+export interface HistoricalDevelopmentFiles {aggregateFile:string;sourceFile:string;acceptanceFile:string;packageRoot:string;inputsRoot:string;archiveFile:string}
+export function aggregateInputHash(a:DeliveryAggregate){return semanticHash({version:1,business:a.inputs.business,sourceDefinitions:a.inputs.sourceDefinitions,runtime:a.inputs.runtime,files:a.inputs.files,targets:a.inputs.targets.map(r=>({target:r.target,configuration:r.configuration.configurationRuntimeHash,sourceConfiguration:r.sourceConfiguration.configurationRuntimeHash,compiler:r.compiler.stableDigest,custom:r.custom}))});}
+function decode(raw:any):any{const v=parseTypedValue(raw);switch(v.type){case 'bigint':return BigInt(v.value);case 'number':return Number(v.value);case 'array':return v.value.map(decode);case 'object':return Object.fromEntries(Object.entries(v.value).map(([k,x])=>[k,decode(x)]));default:return v.value;}}
+/** Every mutable historical container is retained with its ORIGINAL digest; allowed deltas are explicit. */
+export function validateHistoricalDevelopmentFiles(input:{root:string;workspaceRoot:string;projectRoot:string;history:HistoricalDevelopmentFiles}){
+ 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 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}`);}
+ 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');
+ 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');}
+ 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');
+ 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)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==='uups')expectedCode.push({key:`${key}_Proxy`,contract:'ERC1967Proxy',address:change.address});}
+ 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');
+ 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');
+ 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();}
+}