gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/project.ts

@@ -0,0 +1,129 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { positiveInteger, type ProjectNetworkSnapshot } from './protocol';
+import { validateNetworkAlias } from './policy';
+
+export { stat, confinedFile, projectRoot, readFile, deliveryProjectMarker } from './project-files';
+import { confinedFile, readFile } from './project-files';
+import { projectRpcSyntax, projectRpcOptions, resolveProjectRpc, projectRpcEnvironment, projectPublicRpcEnvironment } from './project-rpc';
+
+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, helper: boolean): 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, helper);
+    return node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
+      ? left ?? rpcValue(node.right, env, helper) : left || rpcValue(node.right, env, helper);
+  }
+  if (helper && ts.isCallExpression(node)) {
+    const options = projectRpcOptions(node);
+    return resolveProjectRpc(options.route, rpcValue(options.publicFallback, env, false), options.useBaseRpc, 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[] {
+  const source = readFile(root, 'hardhat.config.ts') ?? '';
+  return parseProjectNetworkSnapshots(source, aliases, projectRpcEnvironment(root, source, env));
+}
+/** Public preflight only: RPCs must be in rpc.env or the supplied environment, never .env. */
+export function readPublicProjectNetworkSnapshots(root: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
+  const source = readFile(root, 'hardhat.config.ts') ?? '';
+  return parseProjectNetworkSnapshots(source, aliases, projectPublicRpcEnvironment(root, source, 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 { file, networks } = parseProjectConfig(source);
+  const { helper } = projectRpcSyntax(file);
+  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, helper) ?? '' };
+  });
+}
+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/public-calldata.ts

@@ -0,0 +1,74 @@
+/** Public business projection. Internal provenance and runtime progress stay separate. */
+import { immutableDeliveryPlan } from './export';
+import { parseCalldataReviews } from './calldata-review';
+import type { PreparationEntry } from './journal';
+import { expandDeliveryInvocation, readableInvocationAbi, describeDeliveryInvocation, type ExpandedDetails } from './calldata-details';
+import { nonempty, deepFreeze, canonicalJson, semanticHash } from '../workflow/lib/canonicalData';
+import type { WorkflowStep } from '../workflow/lib/parameters';
+
+export { archiveDeliveryCalls } from './calldata-archive';
+export { serializeDeliveryCalls, deliveryCalldataPath } from './calldata-format';
+
+export interface DeliveryCall {
+  chains: string[]; executor: string; to: string; name: string; description: string;
+  abi: string[]; calldata: string; value?: string;
+  details?: ExpandedDetails;
+}
+export interface PublicCalldataInput { plan: unknown; calldata: unknown; operations: readonly WorkflowStep[]; preparations?: unknown }
+/** Frozen parameters independently re-encode and compare before any public projection. */
+export function projectDeliveryCalls(input: PublicCalldataInput): readonly DeliveryCall[] {
+  const plan = immutableDeliveryPlan(input.plan);
+  const reviews = parseCalldataReviews(input.calldata, plan.transactions);
+  const journal=input.preparations??[];
+  const preparations: PreparationEntry[] = Array.isArray(journal)&&!journal.length&&!plan.deploymentBindings.length?[]
+    : (require('./journal') as typeof import('./journal')).parsePreparationJournal(journal, plan.transactions, plan.derivedBindings, {target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(d=>d.stepId)});
+  return deepFreeze(plan.transactions.map((tx, index) => {
+    if (tx.operation !== 0) throw Error('Public calldata supports ordinary CALL only');
+    const binding = plan.transactionBindings[index], operation = plan.operationBindings.find(o => o.stepId === binding.stepId);
+    if (!operation) throw Error('Public calldata operation binding missing');
+    const source = operation.operationId === null ? input.operations.find(s => s.id === operation.sourceStepId)
+      : plan.customBindings.find(s => s.sourceStepId === operation.sourceStepId)?.operations.find(s => s.id === operation.operationId);
+    if (!source) throw Error('Frozen operation intent missing');
+    const call = binding.callIndex === null ? undefined : (source.calls as any[] | undefined)?.[binding.callIndex];
+    const name = nonempty(call?.name ?? source.name, 'operation name');
+    const description = nonempty(call?.description ?? source.description, 'operation description');
+    const invocation = reviews[index].invocation;
+    if (invocation.kind !== 'function') throw Error('Outer public transaction requires function ABI');
+    const entry=preparations.find(p=>p.mappings.some(m=>m.transactionId===tx.transactionId));
+    const details=expandDeliveryInvocation(invocation,tx.to,{name,description},entry);
+    return { chains: [plan.chainId], executor: tx.executor, to: tx.to, name, description:describeDeliveryInvocation(description,invocation),
+      abi: readableInvocationAbi(invocation), calldata: tx.data, ...(BigInt(tx.value) === 0n ? {} : { value: tx.value }),...(details?{details}:{}) };
+  }));
+}
+
+/** Merge matching logical occurrences, never globally deduplicate calldata. */
+export function mergeDeliveryCalls(inputs: readonly PublicCalldataInput[]): readonly DeliveryCall[] {
+  if(!inputs.length)throw Error('At least one independently frozen network is required');
+  const chains=new Set<string>(), sequences:Array<{chain:string;calls:readonly DeliveryCall[];keys:string[]}>=[];
+  const nodes=new Map<string,{call:DeliveryCall;next:Set<string>;incoming:number}>();
+  for(const input of inputs){
+    const plan=immutableDeliveryPlan(input.plan),chain=plan.chainId,calls=projectDeliveryCalls(input);
+    if(chains.has(chain))throw Error('Duplicate chain projection');chains.add(chain);
+    const keys=calls.map((call,index)=>{
+      const binding=plan.transactionBindings[index],operation=plan.operationBindings.find(o=>o.stepId===binding.stepId)!;
+      const {chains:_,...content}=call;
+      const key=semanticHash({logical:[operation.sourceStepId,operation.operationId,binding.role,binding.callIndex],content});
+      const existing=nodes.get(key);
+      if(existing){if(existing.call.chains.includes(chain))throw Error('Duplicate logical occurrence on one chain');existing.call.chains.push(chain);}
+      else nodes.set(key,{call:{...call,chains:[chain]},next:new Set(),incoming:0});
+      return key;
+    });
+    sequences.push({chain,calls,keys});
+    for(let i=1;i<keys.length;i++){const a=nodes.get(keys[i-1])!,b=nodes.get(keys[i])!;if(!a.next.has(keys[i])){a.next.add(keys[i]);b.incoming++;}}
+  }
+  const queue=[...nodes].filter(([,n])=>n.incoming===0).map(([key])=>key),ordered:DeliveryCall[]=[];
+  for(let at=0;at<queue.length;at++){
+    const node=nodes.get(queue[at])!;ordered.push(node.call);
+    for(const key of node.next){const next=nodes.get(key)!;if(--next.incoming===0)queue.push(key);}
+  }
+  // Conflicting cross-chain ordering cannot share occurrences; keep exact per-chain sequences.
+  const result=ordered.length===nodes.size?ordered:sequences.flatMap(s=>s.calls.map(call=>({...call,chains:[s.chain]})));
+  const content=(call:DeliveryCall)=>{const {chains:_,...rest}=call;return rest;};
+  for(const sequence of sequences)if(canonicalJson(result.filter(c=>c.chains.includes(sequence.chain)).map(content))!==canonicalJson(sequence.calls.map(content)))throw Error('Merged calldata changed per-chain order or coverage');
+  return deepFreeze(result);
+}

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

package/runtime/delivery/release-history-capture.ts

@@ -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;
+}