gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/aggregate.ts

@@ -0,0 +1,139 @@
+/** Owned multi-target input qualification. This grants no release-ready or broadcast authority. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {openDeliveryInputs,consumeDeliveryInputParameters,type DeliveryInputEvidence} from './inputs';
+import {openAggregateSources} from './aggregate-inputs';
+import {parseDeliveryRequest,safeId,type DeliveryRequest} from './protocol';
+import {strictData} from './data';
+import {inputDigest} from './input-files';
+import {projectRoot} from './project-files';
+import {RuntimeObservation} from './configuration-runtime';
+import {OwnedWorker,OwnedWorkerFailure} from './aggregate-channel';
+import {deepFreeze,canonicalJson,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import type {DeliveryCollection} from './planning';
+import type {DeliveryConfigurationEvidence} from './configuration';
+import type {CompilerEvidence} from './compiler';
+import type {CustomInputClosure} from './custom-closure';
+export interface DeliveryAggregateOptions {
+  workspaceRoot:string;projectRoot:string;selection:'development'|'release'|'all';
+  targets:Array<{request:DeliveryRequest;executionId:string}>;
+}
+export interface DeliveryAggregate {
+  version:1;inputsHash:string;sourceDefinitionHash:string;
+  inputs:{business:DeliveryInputEvidence;sourceDefinitions:unknown;runtime:ReturnType<RuntimeObservation['observe']>;
+    targets:Array<{target:string;configuration:DeliveryConfigurationEvidence;sourceConfiguration:DeliveryConfigurationEvidence;compiler:CompilerEvidence;custom:CustomInputClosure|null}>;
+    files:Array<{path:string;digest:string}>};
+  collections:DeliveryCollection[];
+  /** Runtime diagnostics stay outside the immutable-input preimage. */
+  observations:Array<{target:string;pid:number;sourcePid:number;manifestDir:string;operator:string;executionId:string;payloadHash:string;invariantHash:string;exited:true}>;
+}
+function same(a:unknown,b:unknown,label:string):void{if(canonicalJson(a)!==canonicalJson(b))throw new Error(`${label} drift or mismatch`);}
+/** Derives business data once; only actual worker channels can contribute staged authority. */
+class DiscoveryReplayError extends Error {}
+export async function collectDeliveryAggregate(raw:DeliveryAggregateOptions):Promise<Readonly<DeliveryAggregate>> {
+  try{return await collectOwnedAggregate(raw);}
+  catch(error){if(error instanceof OwnedWorkerFailure||error instanceof DiscoveryReplayError)throw error;throw new Error('Delivery aggregate input qualification failed');}
+}
+async function collectOwnedAggregate(raw:DeliveryAggregateOptions):Promise<Readonly<DeliveryAggregate>> {
+  const input=strictData(raw);
+  exactObject(input,['workspaceRoot','projectRoot','selection','targets'],'aggregate options');
+  if(!['development','release','all'].includes(input.selection)||!Array.isArray(input.targets)||!input.targets.length)throw new Error('Aggregate requires selected target requests');
+  const root=projectRoot(input.workspaceRoot,input.projectRoot),workspace=projectRoot(input.workspaceRoot,'.');
+  if(path.resolve(process.cwd())!==root)throw new Error('Aggregate must run from the original project root');
+  const targets=input.targets.map(value=>{
+    if(!value||Object.keys(value).some(k=>!['request','executionId','expected'].includes(k)))throw new Error('Invalid aggregate target');
+    if(Object.hasOwn(value,'expected'))throw new DiscoveryReplayError('Staged replay requires independently closed current inputs; use known-final collection');
+    const request=parseDeliveryRequest(value.request);safeId(value.executionId,'executionId');
+    if(request.mode!=='simulate'||request.purpose==='prod-execution')throw new Error('Aggregate input qualification requires simulation');
+    return {...value,request};
+  });
+  if(new Set(targets.map(x=>x.request.network)).size!==targets.length||new Set(targets.map(x=>x.executionId)).size!==targets.length)throw new Error('Aggregate target and execution IDs must be distinct');
+  // Every invocation gets its own actual environment/network/step/sourceRef validation.
+  const sourceOwner=openAggregateSources({workspaceRoot:workspace,projectRoot:input.projectRoot,requests:targets.map(x=>x.request)});
+  const {sources,definitions:sourceDefinitions,sourceDefinitionHash}=sourceOwner;
+  for(const source of sources){const scope=source.invocation.task.scope!.deployment as any,first=sources[0].invocation.task.scope!.deployment as any;
+    for(const key of ['deploymentId','developmentNetwork','releaseTargetNetworks','projectRoot'])same(scope[key],first[key],'Aggregate business scope');
+  }
+  let runtime:RuntimeObservation|undefined,business:ReturnType<typeof openDeliveryInputs>|undefined;
+  const workers:OwnedWorker[]=[];let failure:Error|undefined;
+  const session=randomUUID(),directory=fs.mkdtempSync(path.join(os.tmpdir(),'gate-delivery-aggregate-'));
+  const live=()=>{if(failure)throw failure;for(const worker of workers)worker.assertLive();};
+  const checkSources=()=>sourceOwner.assertUnchanged();
+  try{
+    runtime=new RuntimeObservation(root);
+    business=openDeliveryInputs({workspaceRoot:workspace,projectRoot:input.projectRoot,request:targets[0].request,selection:input.selection});
+    same(targets.map(x=>x.request.network),business.snapshot.targets.map(x=>x.id),'Selected target request order');
+    const receipts=targets.map(({request})=>business!.parameters(request.network));
+    const rows:any[]=[];
+    for(const [index,target] of targets.entries()){
+      live();checkSources();
+      const publicTarget=business.snapshot.targets[index];
+      if(publicTarget.environment!==target.request.environment)throw new Error('Selected request environment mismatch');
+      const common={root,workspaceRoot:workspace,projectRoot:input.projectRoot,request:target.request};
+      const source=new OwnedWorker(root,session,target.request.network,'source',error=>{failure??=error;});workers.push(source);
+      const handshakePath=path.join(directory,`${index}.json`);
+      const ready=await source.request('stage',{...common,role:'source',handshakePath});
+      if(ready.ready!==true||!fs.existsSync(handshakePath))throw new Error('Source handshake is not READY');
+      const bytes=fs.readFileSync(handshakePath,'utf8'),handshake=JSON.parse(bytes);
+      same(handshake,ready.handshake,'Source handshake');
+      if(handshake.version!==1||handshake.session!==session||handshake.epoch!==source.epoch||handshake.target!==target.request.network)throw new Error('Source handshake association mismatch');
+      const worker=new OwnedWorker(root,session,target.request.network,'target',error=>{failure??=error;});workers.push(worker);
+      const staged=await worker.request('stage',{...common,role:'target',handshake,target:publicTarget,params:business.values(publicTarget.id),steps:business.snapshot.steps,
+        deploymentId:business.snapshot.deploymentId,businessRoot:business.snapshot.businessRoot,executionId:target.executionId,sourceDefinitionHash});
+      if(staged.ready!==true)throw new Error('Target stage is not READY');
+      rows.push({target:publicTarget.id,source,worker,staged});
+    }
+    // Producer/evaluation ports terminate before the final union. No producer runs below this point.
+    checkSources();const sealed=business.seal() as DeliveryInputEvidence;
+    for(const [index,receipt] of receipts.entries())same(consumeDeliveryInputParameters(receipt),sealed.parameters[index].resolved.values,'Owned parameter receipt');
+    const contributions:DeliveryAggregate['inputs']['targets']=[];
+    for(const row of rows){
+      live();
+      const checked=await row.worker.request('check');
+      same(checked.compiler,row.staged.compiler,'Compiler stage');same(checked.custom,row.staged.custom,'Target custom closure');same(checked.payloadHash,row.staged.payloadHash,'Staged payload');same(checked.invariantHash,row.staged.invariantHash,'Staged invariant');
+      const sourceChecked=await row.source.request('check');
+      contributions.push({target:row.target,configuration:checked.configuration,sourceConfiguration:sourceChecked.configuration,compiler:checked.compiler,custom:checked.custom});
+    }
+    checkSources();runtime.assertUnchanged();const parentRuntime=runtime.observe();
+    const files=new Map<string,string>();
+    const add=(path:string,digest:string)=>{if(files.has(path)&&files.get(path)!==digest)throw new Error('Conflicting aggregate immutable input');files.set(path,digest);};
+    for(const file of sealed.files)add(file.path,file.digest);
+    for(const parameter of sealed.parameters)for(const file of parameter.closure?.files??[])add(file.path,file.digest);
+    for(const row of contributions){
+      for(const file of row.custom?.files??[])add(file.path,file.digest);
+      for(const artifact of row.compiler.artifacts){add(artifact.path,inputDigest(artifact.contents));add(artifact.debugPath,inputDigest(artifact.debugContents));}
+      for(const build of row.compiler.builds)add(build.path,inputDigest(build.contents));
+      for(const job of row.compiler.jobs)for(const file of job.sources)add(file.path,file.digest);
+      for(const file of row.compiler.toolchain.modules)add(file.path,file.digest);
+      for(const config of [row.configuration,row.sourceConfiguration]){
+        for(const file of config.files)add(file.path,file.digest);
+        for(const file of config.runtime.modules)add(file.path,file.digest);
+        for(const pkg of [config.runtime.package,...config.runtime.dependencies])for(const file of pkg.payload)add(`${pkg.lockLocation}/${file.path}`,file.digest);
+      }
+    }
+    const union=[...files].sort(([a],[b])=>a.localeCompare(b,'en')).map(([path,digest])=>({path,digest}));
+    // No runtime state, observation, plan hash or randomized compiler exact evidence enters this preimage.
+    const inputsHash=semanticHash({version:1,business:sealed,sourceDefinitions,runtime:parentRuntime,files:union,
+      targets:contributions.map(row=>({target:row.target,configuration:row.configuration.configurationRuntimeHash,sourceConfiguration:row.sourceConfiguration.configurationRuntimeHash,compiler:row.compiler.stableDigest,custom:row.custom}))});
+    live();
+    const collections:DeliveryCollection[]=[];
+    for(const row of rows){
+      const collection=await row.worker.request('bind',{inputsHash}) as DeliveryCollection;
+      if(collection.plan.inputsHash!==inputsHash||collection.plan.sourceDefinitionHash!==sourceDefinitionHash)throw new Error('Final target identity mismatch');
+      const {inputsHash:_,planHash:__,...payload}=collection.plan;
+      same(semanticHash(payload),row.staged.payloadHash,'Final staged payload');collections.push(collection);
+    }
+    // No externally reachable plan exists until every actual child has exited successfully.
+    for(const row of rows){if(failure)throw failure;await row.worker.request('close');await row.source.request('close');}
+    if(failure)throw failure;
+    return deepFreeze({version:1,inputsHash,sourceDefinitionHash,inputs:{business:sealed,sourceDefinitions,runtime:parentRuntime,targets:contributions,files:union},collections,
+      observations:rows.map(row=>({target:row.target,...row.staged.observation,sourcePid:row.source.pid,payloadHash:row.staged.payloadHash,invariantHash:row.staged.invariantHash,exited:true}))}) as DeliveryAggregate;
+  }finally{
+    business?.close();runtime?.close();
+    const results=await Promise.allSettled(workers.map(worker=>worker.reap()));
+    fs.rmSync(directory,{recursive:true,force:true});
+    if(results.some(x=>x.status==='rejected'))throw new Error('Aggregate worker cleanup failed');
+  }
+}

package/runtime/delivery/bindings.ts

@@ -0,0 +1,37 @@
+import type { ExecutionBindings } from '../workflow/lib/context';
+import { canonicalData, exactObject, nonempty, deepFreeze } from '../workflow/lib/canonicalData';
+export interface DerivedBindings { executionId: string; derivationSeed: string; values: Record<string, string> }
+export function parseDerivedBindings(raw: unknown): DerivedBindings {
+  const input = exactObject(raw, ['executionId', 'derivationSeed', 'values'], 'derived bindings');
+  const values = canonicalData(input.values) as Record<string, unknown>;
+  if (!values || typeof values !== 'object' || Array.isArray(values)) throw new Error('derived values must be an object');
+  for (const [key, value] of Object.entries(values)) { nonempty(key, 'derived key'); nonempty(value, 'derived value'); }
+  return deepFreeze({ executionId: nonempty(input.executionId, 'executionId'), derivationSeed: nonempty(input.derivationSeed, 'derivationSeed'), values: values as Record<string, string> });
+}
+export class DeliveryExecutionBindings implements ExecutionBindings {
+  readonly derivationSeed: string;
+  private readonly executionId: string;
+  private readonly expected?: DerivedBindings;
+  private readonly values: Record<string, string> = Object.create(null);
+  private sealed = false;
+  constructor(input: { executionId: string; derivationSeed: string; expected?: DerivedBindings }) {
+    this.executionId = nonempty(input.executionId, 'executionId'); this.derivationSeed = nonempty(input.derivationSeed, 'derivationSeed');
+    this.expected = input.expected && parseDerivedBindings(input.expected);
+    if (this.expected && (this.expected.executionId !== this.executionId || this.expected.derivationSeed !== this.derivationSeed)) throw new Error('derived binding identity mismatch');
+  }
+  recordOrAssertDerivedValue(key: string, value: string): void {
+    if (this.sealed) throw new Error('derived bindings are sealed');
+    nonempty(key, 'derived key'); nonempty(value, 'derived value');
+    if (Object.hasOwn(this.values, key)) throw new Error(`duplicate derived binding ${key}`);
+    if (this.expected) {
+      if (!Object.hasOwn(this.expected.values, key)) throw new Error(`unexpected derived binding ${key}`);
+      if (this.expected.values[key] !== value) throw new Error(`derived binding ${key} differs`);
+    }
+    this.values[key] = value;
+  }
+  seal(): DerivedBindings {
+    if (this.expected && Object.keys(this.expected.values).some(key => !Object.hasOwn(this.values, key))) throw new Error('missing expected derived bindings');
+    this.sealed = true;
+    return parseDerivedBindings({ executionId: this.executionId, derivationSeed: this.derivationSeed, values: this.values });
+  }
+}

package/runtime/delivery/check-code.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {canonicalData,canonicalJson} from '../workflow/lib/canonicalData';
+import {byteHash,developmentPath,atomicDevelopmentWrite} from './materialization';
+export interface ExpectedDevelopmentCode {key:string;contract:string;address:string}
+/** The checker incrementally merges output. A fresh private output file is mandatory. */
+export function validateDevelopmentCheckReport(raw:unknown,target:string,expected:readonly ExpectedDevelopmentCode[]):unknown {
+ const value=canonicalData(raw) as any;
+ if(!expected.length||new Set(expected.map(e=>e.key)).size!==expected.length)throw Error('Empty expected CheckCode set or key collision');
+ if(!value||Array.isArray(value)||canonicalJson(Object.keys(value))!==canonicalJson([target]))throw Error('CheckCode target mismatch');
+ const entries=value[target];if(!entries||Array.isArray(entries)||canonicalJson(Object.keys(entries).sort())!==canonicalJson(expected.map(e=>e.key).sort()))throw Error('CheckCode missing/extra entries');
+ for(const e of expected){const row=entries[e.key];if(!row||row.contract!==e.contract||row.scheme!=='evm'||typeof row.address!=='string'||row.address.toLowerCase()!==e.address.toLowerCase()||row.matches!==true||row.error!==null||typeof row.reason!=='string'||!Number.isSafeInteger(row.onChainBytecodeLength)||row.onChainBytecodeLength<=0||!Number.isSafeInteger(row.localBytecodeLength)||row.localBytecodeLength<=0)throw Error(`CheckCode identity/match failure: ${e.key}`);}
+ return value;
+}
+function command(root:string,cmd:string,args:string[],env:NodeJS.ProcessEnv,log:string):Promise<void> {
+ return new Promise((resolve,reject)=>{const output=fs.createWriteStream(log,{flags:'wx',mode:0o600});const child=spawn(cmd,args,{cwd:root,env,stdio:['ignore','pipe','pipe']});child.stdout.pipe(output,{end:false});child.stderr.pipe(output,{end:false});child.on('error',error=>{output.end();reject(error);});child.on('close',code=>{output.end(()=>code===0?resolve():reject(Error(`CheckCode command failed (${code}): ${cmd}; see ${log}`)));});});
+}
+export async function runDevelopmentCheckCode(input:{root:string;target:string;executionId:string;planHash:string;manifestDir:string;registry:string;metadata:string;effective:Record<string,Record<string,string>>;expected:ExpectedDevelopmentCode[];assertArtifacts:()=>Promise<unknown>}):Promise<unknown> {
+ const relative=`.gate-delivery/check-code/${input.executionId}/${randomUUID()}`,directory=developmentPath(input.root,relative);fs.mkdirSync(directory,{recursive:true,mode:0o700});
+ const effective=canonicalJson(input.effective)+'\n';atomicDevelopmentWrite(input.root,`${relative}/effective.json`,effective);
+ const raw=path.join(directory,`${input.target}.raw.json`),env:NodeJS.ProcessEnv={...process.env,HARDHAT_NETWORK:input.target,GATE_WORKFLOW_TARGET:input.target,MANIFEST_DEFAULT_DIR:input.manifestDir};
+ // Configuration's runtime loader selects the actual named target, never a fork.
+ delete env.GATE_DELIVERY_CONTEXT;
+ const snapshot=async()=>{
+  if(fs.readFileSync(path.join(input.root,'contractInfo.json'),'utf8')!==input.registry||fs.readFileSync(path.join(input.root,'deploymentInfo.json'),'utf8')!==input.metadata)throw Error('Registry/metadata changed during CheckCode');
+  return await input.assertArtifacts();
+ };
+ await snapshot();await command(input.root,'npm',['run','compile','--','--network',input.target],env,path.join(directory,'compile.log'));await snapshot();
+ if(fs.existsSync(raw))throw Error('CheckCode raw output must be fresh');
+ await command(input.root,process.execPath,[path.join(input.root,'node_modules/gate-evm-tools/bin/cli.js'),'check','--scheme','evm','--network',input.target,'--config',path.join(directory,'effective.json'),'--output',raw],env,path.join(directory,'check.log'));
+ const artifacts=await snapshot();
+ if(!fs.existsSync(raw))throw Error('CheckCode completed without raw output');
+ const stat=fs.lstatSync(raw);if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)throw Error('Invalid CheckCode raw output');
+ const bytes=fs.readFileSync(raw);validateDevelopmentCheckReport(JSON.parse(bytes.toString('utf8')),input.target,input.expected);
+ return {version:1,executionId:input.executionId,planHash:input.planHash,target:input.target,rawFile:`${relative}/${input.target}.raw.json`,rawHash:byteHash(bytes),registryHash:byteHash(input.registry),metadataHash:byteHash(input.metadata),effectiveHash:byteHash(effective),artifacts};
+}

package/runtime/delivery/closure-format.ts

@@ -0,0 +1,350 @@
+/** Pure parser for the collector's existing sealed closure format. Numeric compiler enums are pinned to TypeScript 5.9.3. */
+import { createHash } from 'node:crypto';
+import { strictData } from './data';
+import { portablePath } from './protocol';
+import { canonicalJson, deepFreeze, digest, exactObject, semanticHash } from '../workflow/lib/canonicalData';
+const policy = 'gate-custom-cjs@1' as const;
+const hash = (bytes: Buffer | string) => createHash('sha256').update(bytes).digest('hex');
+export interface ClosureFile {
+  path: string;
+  kind: "module" | "json" | "data" | "config" | "metadata";
+  digest: string;
+  emittedDigest: string | null;
+}
+export interface ClosureEdge {
+  importer: string;
+  specifier: string;
+  target: string;
+  kind: "runtime" | "config";
+}
+export interface ClosurePackage {
+  lockLocation: string;
+  name: string;
+  version: string;
+  integrity: string;
+  source: { kind: "registry" | "tarball"; identity: string };
+  metadataDigest: string;
+  resolution: Record<string, unknown>;
+  payload: { path: string; digest: string }[];
+  payloadDigest: string;
+}
+export interface HostAdapter {
+  kind: "isolated-cjs" | "hardhat-2.26.3-ts-node-10.9.2";
+  preload: { path: string; digest: string } | null;
+  packages: { name: string; version: string; metadataDigest: string }[];
+}
+export interface CustomInputClosure {
+  version: 1;
+  policy: typeof policy;
+  roots: string[];
+  files: ClosureFile[];
+  edges: ClosureEdge[];
+  packages: ClosurePackage[];
+  compiler: {
+    version: string;
+    options: Record<string, unknown>;
+    config: string | null;
+  };
+  hostAdapter: HostAdapter;
+  resolver: {
+    policy: "node-default-cjs";
+    version: string;
+    flags: string[];
+    environment: "empty";
+  };
+  closureHash: string;
+}
+export const closureRuntimeOptions = {
+  target: 9,
+  module: 1,
+  esModuleInterop: true,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  sourceMap: false,
+  inlineSourceMap: false,
+  importHelpers: false,
+  removeComments: false,
+  newLine: 1,
+};
+export function parseCustomInputClosure(raw: unknown): CustomInputClosure {
+  const e = exactObject(
+    strictData(raw),
+    [
+      "version",
+      "policy",
+      "roots",
+      "files",
+      "edges",
+      "packages",
+      "compiler",
+      "hostAdapter",
+      "resolver",
+      "closureHash",
+    ],
+    "custom input closure"
+  );
+  const { closureHash, ...body } = e;
+  if (
+    e.version !== 1 ||
+    e.policy !== policy ||
+    digest(closureHash, "closure") !== semanticHash(body)
+  )
+    throw new Error("Custom closure identity mismatch");
+  if (
+    !Array.isArray(e.roots) ||
+    !e.roots.length ||
+    !Array.isArray(e.files) ||
+    !Array.isArray(e.edges) ||
+    !Array.isArray(e.packages)
+  )
+    throw new Error("Missing custom closure entries");
+  const kinds = new Map<string, ClosureFile["kind"]>();
+  for (const raw of e.files) {
+    const f = exactObject(
+      raw,
+      ["path", "kind", "digest", "emittedDigest"],
+      "closure file"
+    );
+    portablePath(f.path, "closure file");
+    digest(f.digest, "file");
+    if (
+      kinds.has(f.path as string) ||
+      typeof f.kind !== "string" ||
+      !["module", "json", "data", "config", "metadata"].includes(f.kind)
+    )
+      throw new Error("Invalid closure file");
+    kinds.set(f.path as string, f.kind as ClosureFile["kind"]);
+    if (f.kind === "module") digest(f.emittedDigest, "emitted module");
+    else if (f.emittedDigest !== null)
+      throw new Error("Invalid nonmodule emission");
+  }
+  if (
+    new Set(e.roots).size !== e.roots.length ||
+    e.roots.some((r) => typeof r !== "string" || kinds.get(r) !== "module")
+  )
+    throw new Error("Missing closure root");
+  // Config JSON can also be imported at runtime, which promotes its file kind to json.
+  const configFile = (name: string) =>
+    name.endsWith(".json") &&
+    ["config", "json"].includes(kinds.get(name) ?? "");
+  const edgeKeys = new Set<string>();
+  for (const raw of e.edges) {
+    const edge = exactObject(
+      raw,
+      ["importer", "specifier", "target", "kind"],
+      "closure edge"
+    );
+    if (
+      typeof edge.importer !== "string" ||
+      typeof edge.target !== "string" ||
+      typeof edge.specifier !== "string" ||
+      !edge.specifier ||
+      (edge.kind !== "runtime" && edge.kind !== "config")
+    )
+      throw new Error("Invalid closure edge");
+    const key = canonicalJson([edge.importer, edge.specifier, edge.kind]);
+    if (edgeKeys.has(key)) throw new Error("Duplicate closure edge");
+    edgeKeys.add(key);
+    if (
+      edge.kind === "runtime"
+        ? kinds.get(edge.importer) !== "module" ||
+          !["module", "json"].includes(kinds.get(edge.target) ?? "")
+        : !configFile(edge.importer) || !configFile(edge.target)
+    )
+      throw new Error("Invalid closure edge file relationship");
+  }
+  const files = e.files as ClosureFile[];
+  const packages = new Map<string, ClosurePackage>();
+  for (const raw of e.packages) {
+    const p = exactObject(
+      raw,
+      [
+        "lockLocation",
+        "name",
+        "version",
+        "integrity",
+        "source",
+        "metadataDigest",
+        "resolution",
+        "payload",
+        "payloadDigest",
+      ],
+      "closure package"
+    );
+    portablePath(p.lockLocation, "lock location");
+    digest(p.metadataDigest, "metadata");
+    digest(p.payloadDigest, "payload");
+    const s = exactObject(p.source, ["kind", "identity"], "package source");
+    if (s.kind !== "registry" && s.kind !== "tarball")
+      throw new Error("Invalid package source");
+    digest(s.identity, "source");
+    if (
+      typeof p.name !== "string" ||
+      typeof p.version !== "string" ||
+      typeof p.integrity !== "string" ||
+      !/^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/.test(p.integrity) ||
+      Buffer.from(p.integrity.split("-")[1], "base64").length !==
+        Number(p.integrity.slice(3).split("-")[0]) / 8 ||
+      !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(p.version) ||
+      !Array.isArray(p.payload) ||
+      semanticHash(p.payload) !== p.payloadDigest
+    )
+      throw new Error("Invalid package closure");
+    if (
+      !p.resolution ||
+      typeof p.resolution !== "object" ||
+      Array.isArray(p.resolution) ||
+      Object.keys(p.resolution).some(
+        (k) => !["type", "main", "exports", "imports"].includes(k)
+      )
+    )
+      throw new Error("Invalid package resolution metadata");
+    if (s.kind === "tarball" && s.identity !== hash(p.integrity))
+      throw new Error("Invalid tarball content identity");
+    const payloadNames = new Set<string>();
+    for (const raw of p.payload) {
+      const f = exactObject(raw, ["path", "digest"], "payload file");
+      const name = portablePath(f.path, "payload path");
+      digest(f.digest, "payload file");
+      if (payloadNames.has(name)) throw new Error("Duplicate payload path");
+      payloadNames.add(name);
+    }
+    const location = p.lockLocation as string;
+    if (
+      packages.has(location) ||
+      location
+        .split("/node_modules/")
+        .at(-1)!
+        .replace(/^node_modules\//, "") !== p.name ||
+      !location.split("/").includes("node_modules")
+    )
+      throw new Error("Invalid package lock location");
+    if (
+      !files.some(
+        (file) =>
+          file.path === `${location}/package.json` &&
+          file.digest === p.metadataDigest
+      ) ||
+      !(p.payload as ClosurePackage["payload"]).some(
+        (file) =>
+          file.path === "package.json" && file.digest === p.metadataDigest
+      )
+    )
+      throw new Error("Package metadata missing from payload/closure");
+    packages.set(location, p as unknown as ClosurePackage);
+  }
+  for (const file of files) {
+    const parts = file.path.split("/"),
+      index = parts.lastIndexOf("node_modules");
+    if (index < 0) continue;
+    const location = parts
+      .slice(0, index + (parts[index + 1]?.startsWith("@") ? 3 : 2))
+      .join("/");
+    const identity = packages.get(location);
+    if (
+      !identity?.payload.some(
+        (entry) =>
+          entry.path === file.path.slice(location.length + 1) &&
+          entry.digest === file.digest
+      )
+    )
+      throw new Error("Package file missing from locked payload");
+  }
+  const compiler = exactObject(
+    e.compiler,
+    ["version", "options", "config"],
+    "closure compiler"
+  );
+  if (
+    compiler.version !== "5.9.3" ||
+    (compiler.config !== null &&
+      (typeof compiler.config !== "string" || !configFile(compiler.config)))
+  )
+    throw new Error("Unsupported closure compiler/adapter");
+  const options = exactObject(
+    compiler.options,
+    [
+      ...Object.keys(closureRuntimeOptions),
+      ...(compiler.options &&
+      typeof compiler.options === "object" &&
+      Object.hasOwn(compiler.options, "useDefineForClassFields")
+        ? ["useDefineForClassFields"]
+        : []),
+    ],
+    "effective compiler options"
+  );
+  for (const [key, value] of Object.entries(closureRuntimeOptions)) {
+    if (!["target", "esModuleInterop"].includes(key) && options[key] !== value)
+      throw new Error("Unsupported effective compiler option");
+  }
+  if (
+    typeof options.esModuleInterop !== "boolean" ||
+    typeof options.target !== "number" ||
+    ![0,1,2,3,4,5,6,7,8,9,10,11,99,100].includes(options.target) ||
+    [0,100].includes(options.target) ||
+    (Object.hasOwn(options, "useDefineForClassFields") &&
+      typeof options.useDefineForClassFields !== "boolean")
+  )
+    throw new Error("Invalid effective compiler options");
+  const adapter = exactObject(
+    e.hostAdapter,
+    ["kind", "preload", "packages"],
+    "host adapter"
+  );
+  if (
+    (adapter.kind !== "isolated-cjs" &&
+      adapter.kind !== "hardhat-2.26.3-ts-node-10.9.2") ||
+    !Array.isArray(adapter.packages)
+  )
+    throw new Error("Unsupported host adapter");
+  if (
+    adapter.kind === "isolated-cjs" &&
+    (adapter.preload !== null || adapter.packages.length)
+  )
+    throw new Error("Invalid isolated loader");
+  if (adapter.preload !== null) {
+    const p = exactObject(adapter.preload, ["path", "digest"], "preload");
+    portablePath(p.path, "preload");
+    digest(p.digest, "preload");
+  }
+  for (const raw of adapter.packages) {
+    const p = exactObject(
+      raw,
+      ["name", "version", "metadataDigest"],
+      "adapter package"
+    );
+    digest(p.metadataDigest, "adapter metadata");
+  }
+  if (adapter.kind === "hardhat-2.26.3-ts-node-10.9.2") {
+    if (
+      adapter.preload === null ||
+      (adapter.preload as { path: string }).path !==
+        "node_modules/ts-node/register/index.js" ||
+      canonicalJson(
+        (adapter.packages as HostAdapter["packages"]).map((p) => [
+          p.name,
+          p.version,
+        ])
+      ) !==
+        canonicalJson([
+          ["ts-node", "10.9.2"],
+          ["hardhat", "2.26.3"],
+        ])
+    )
+      throw new Error("Invalid pinned preload adapter");
+  }
+  const resolver = exactObject(
+    e.resolver,
+    ["policy", "version", "flags", "environment"],
+    "resolver"
+  );
+  if (
+    resolver.policy !== "node-default-cjs" ||
+    typeof resolver.version !== "string" ||
+    !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(resolver.version) ||
+    resolver.environment !== "empty" ||
+    canonicalJson(resolver.flags) !== canonicalJson(["--preserve-symlinks"])
+  )
+    throw new Error("Unsupported resolver policy");
+  return deepFreeze(e as unknown as CustomInputClosure);
+}

package/runtime/delivery/codec-pin.ts

@@ -0,0 +1,3 @@
+// Reviewed vendor identity. Refresh explicitly after rebuilding from committed canonical sources.
+export const PLAN_CODEC_PROVENANCE_SHA256 = '63bc721e90943e08478a67a72d1bef8ce69a034552f225b90ee2c6e5396785ce';
+export const PLAN_CODEC_SOURCE_COMMIT = '9b175e7906ca6735aeca92b50ce7cf716d980f17';

package/runtime/delivery/codec.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { PLAN_CODEC_PROVENANCE_SHA256, PLAN_CODEC_SOURCE_COMMIT } from './codec-pin';
+import type * as Canonical from '../vendor/plan-codec/index.cjs';
+
+const sha256 = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
+function regularBytes(directory: string, name: string): Buffer {
+  const file = path.join(directory, name);
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error(`Unsafe codec artifact: ${name}`);
+  return fs.readFileSync(file);
+}
+/** The reviewed pin protects provenance as well as the bundle. No checkout or network is used. */
+export function verifyPlanCodec(directory: string): void {
+  if (fs.lstatSync(directory).isSymbolicLink()) throw new Error('Unsafe codec directory');
+  const bytes = regularBytes(directory, 'provenance.json');
+  if (sha256(bytes) !== PLAN_CODEC_PROVENANCE_SHA256) throw new Error('Plan codec provenance digest mismatch');
+  const manifest = JSON.parse(bytes.toString('utf8'));
+  if (manifest.formatVersion !== 1 || manifest.name !== 'gateflow-plan-read-only' || manifest.version !== 1
+    || manifest.schema !== 'gateflow-plan/v2' || manifest.definitionContract !== 'gateflow-plan/definition@1'
+    || manifest.sourceCommit !== PLAN_CODEC_SOURCE_COMMIT) throw new Error('Unsupported plan codec provenance');
+  for (const name of ['index.cjs', 'index.d.cts']) {
+    if (sha256(regularBytes(directory, name)) !== manifest.artifacts[name]) throw new Error(`Plan codec artifact digest mismatch: ${name}`);
+  }
+}
+export function loadPlanCodec(): typeof Canonical {
+  const directory = path.join(__dirname, '..', 'vendor', 'plan-codec');
+  verifyPlanCodec(directory);
+  return require(path.join(directory, 'index.cjs')) as typeof Canonical;
+}
+
+export interface PlanCodecObservation {
+  schema: 'gateflow-plan/v2'; definitionContract: 'gateflow-plan/definition@1'; sourceCommit: string;
+  provenanceHash: string; bundleHash: string; declarationHash: string;
+}
+/** Own the actual loader seam, including a cached bundle's continued file/module association. */
+export function openPlanCodecObservation(): {readonly snapshot: Readonly<PlanCodecObservation>; assertUnchanged():void; seal():Readonly<PlanCodecObservation>; close():void} {
+  const directory=path.join(__dirname,'..','vendor','plan-codec');
+  const loaded=loadPlanCodec(),entry=path.join(directory,'index.cjs');
+  const observe=():Readonly<PlanCodecObservation>=>{
+    verifyPlanCodec(directory);
+    if(require.cache[entry]?.exports!==loaded)throw new Error('Plan codec loaded module drift');
+    return Object.freeze({schema:'gateflow-plan/v2',definitionContract:'gateflow-plan/definition@1',sourceCommit:PLAN_CODEC_SOURCE_COMMIT,
+      provenanceHash:sha256(regularBytes(directory,'provenance.json')),bundleHash:sha256(regularBytes(directory,'index.cjs')),declarationHash:sha256(regularBytes(directory,'index.d.cts'))});
+  };
+  const snapshot=observe();let open=true;
+  const check=()=>{if(!open)throw new Error('Plan codec observation closed');if(JSON.stringify(observe())!==JSON.stringify(snapshot))throw new Error('Plan codec observation drift');};
+  return Object.freeze({snapshot,assertUnchanged(){try{check();}catch(error){open=false;throw error;}},seal(){try{check();return snapshot;}finally{open=false;}},close(){open=false;}});
+}