gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/calldata-review.ts

@@ -0,0 +1,126 @@
+/** Pure ABI review. Expected arguments come from planning, never from decoding submitted bytes. */
+import { AbiCoder, Interface, ParamType, type InterfaceAbi } from 'ethers';
+import { canonicalJson, deepFreeze } from '../workflow/lib/canonicalData';
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { strictData } from './data';
+
+export interface CalldataPayload {
+    argumentPath: number[];
+    invocation: CalldataInvocation;
+}
+export interface CalldataInvocation {
+    kind: 'function' | 'constructor';
+    abi: unknown[];
+    method: string;
+    selector: string | null;
+    bytecode: string | null;
+    expectedArguments: unknown[];
+    decodedArguments: unknown[];
+    data: string;
+    payloads: CalldataPayload[];
+    check: 'matches-frozen-intent';
+}
+export interface CalldataTransactionReview {
+    transactionId: string;
+    to: string;
+    value: string;
+    operation: 0 | 1;
+    invocation: CalldataInvocation;
+}
+export interface CalldataReviewSink {
+    record(transaction: ReleaseExecutionTransaction, input: { abi: InterfaceAbi; method: string; args: readonly unknown[] }): void;
+}
+function bytes(value: unknown): string {
+    if (typeof value !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(value)) throw Error('Invalid ABI review bytes');
+    return value.toLowerCase();
+}
+/** Decimal strings retain uint256 precision; positional tuples are unambiguous even with duplicate names. */
+function argument(type: ParamType, value: any): unknown {
+    if (type.baseType === 'array') {
+        if (!Array.isArray(value) || (type.arrayLength !== -1 && value.length !== type.arrayLength)) throw Error('Invalid ABI review array');
+        return Array.from(value, v => argument(type.arrayChildren!, v));
+    }
+    if (type.baseType === 'tuple') {
+        if (!value || typeof value !== 'object') throw Error('Invalid ABI review tuple');
+        return type.components!.map((p, i) => argument(p, Array.isArray(value) ? value[i] : value[p.name]));
+    }
+    if (/^u?int\d*$/.test(type.type)) {
+        if (typeof value === 'number' && !Number.isSafeInteger(value)) throw Error('Unsafe ABI review integer');
+        if (!['bigint', 'number', 'string'].includes(typeof value) || (typeof value === 'string' && !value.trim())) throw Error('Invalid ABI review integer');
+        return BigInt(value).toString();
+    }
+    if (type.type === 'address') return String(value).toLowerCase();
+    if (/^bytes\d*$/.test(type.type)) return bytes(value);
+    if ((type.type === 'bool' && typeof value !== 'boolean') || (type.type === 'string' && typeof value !== 'string')) throw Error('Invalid ABI review scalar');
+    return value;
+}
+function argumentsOf(types: readonly ParamType[], args: readonly unknown[]): unknown[] {
+    if (!Array.isArray(args) || types.length !== args.length) throw Error('ABI review argument count mismatch');
+    return types.map((p, i) => argument(p, args[i]));
+}
+export function createCalldataInvocation(input: {
+    abi: InterfaceAbi; method: string | null; args: readonly unknown[]; data: string;
+    bytecode?: string; payloads?: CalldataPayload[];
+}): CalldataInvocation {
+    const iface = new Interface(input.abi), fragment = input.method === null ? iface.deploy : iface.getFunction(input.method);
+    if (!fragment) throw Error('ABI review method missing');
+    const expectedArguments = argumentsOf(fragment.inputs, input.args), data = bytes(input.data);
+    const bytecode = input.method === null ? bytes(input.bytecode) : null;
+    if (input.method !== null && input.bytecode !== undefined) throw Error('Function review cannot contain constructor bytecode');
+    const encoded = input.method === null ? bytecode + iface.encodeDeploy(expectedArguments).slice(2) : iface.encodeFunctionData(input.method, expectedArguments).toLowerCase();
+    if (encoded !== data) throw Error('Calldata differs from expected ABI encoding');
+    const decoded = input.method === null
+        ? AbiCoder.defaultAbiCoder().decode(fragment.inputs, '0x' + data.slice(bytecode!.length))
+        : iface.decodeFunctionData(input.method, data);
+    const decodedArguments = argumentsOf(fragment.inputs, Array.from(decoded));
+    if (canonicalJson(expectedArguments) !== canonicalJson(decodedArguments)) throw Error('Decoded calldata differs from frozen intent');
+    const payloads = (input.payloads ?? []).map(p => {
+        if (!Array.isArray(p.argumentPath) || !p.argumentPath.length || p.argumentPath.some(i => !Number.isSafeInteger(i) || i < 0)) throw Error('Invalid nested calldata argument path');
+        let value: any = expectedArguments;
+        for (const index of p.argumentPath) {
+            if (!Array.isArray(value) || index >= value.length) throw Error('Nested calldata argument path missing');
+            value = value[index];
+        }
+        const invocation = parseCalldataInvocation(p.invocation);
+        if (value !== invocation.data) throw Error('Nested calldata differs from enclosing payload');
+        return { argumentPath: p.argumentPath, invocation };
+    });
+    if (new Set(payloads.map(p => canonicalJson(p.argumentPath))).size !== payloads.length) throw Error('Duplicate nested calldata payload');
+    const method = input.method === null ? 'constructor' : fragment.format('sighash');
+    const required: number[][] = [];
+    if (method === 'deploy(bytes32,bytes,bytes,uint256,uint256)') {
+        required.push([1]);
+        if (expectedArguments[2] !== '0x') required.push([2]);
+        if (payloads.find(p => canonicalJson(p.argumentPath) === '[1]')?.invocation.kind !== 'constructor') throw Error('CREATE2 constructor ABI review required');
+    } else if (method === 'upgradeToAndCall(address,bytes)' && expectedArguments[1] !== '0x') required.push([1]);
+    else if (method === 'upgradeAndCall(address,address,bytes)' && expectedArguments[2] !== '0x') required.push([2]);
+    else if (['aggregate3((address,bool,bytes)[])', 'aggregate3Value((address,bool,uint256,bytes)[])'].includes(method)) {
+        const index = method.startsWith('aggregate3Value') ? 3 : 2;
+        (expectedArguments[0] as unknown[]).forEach((_, i) => required.push([0, i, index]));
+    }
+    for (const path of required) if (!payloads.some(p => canonicalJson(p.argumentPath) === canonicalJson(path))) throw Error('Nested calldata ABI review required');
+    return deepFreeze({ kind: input.method === null ? 'constructor' : 'function', abi: [JSON.parse(fragment.format('json'))],
+        method, selector: input.method === null ? null : iface.getFunction(input.method)!.selector,
+        bytecode, expectedArguments, decodedArguments, data, payloads, check: 'matches-frozen-intent' });
+}
+export function parseCalldataInvocation(raw: unknown): CalldataInvocation {
+    const v = strictData(raw) as CalldataInvocation;
+    if (!v || !['function', 'constructor'].includes(v.kind) || !Array.isArray(v.payloads)) throw Error('Invalid calldata invocation');
+    const parsed = createCalldataInvocation({ abi: v.abi as InterfaceAbi, method: v.kind === 'constructor' ? null : v.method,
+        args: v.expectedArguments, data: v.data, ...(v.kind === 'constructor' ? { bytecode: v.bytecode! } : {}), payloads: v.payloads });
+    if (canonicalJson(parsed) !== canonicalJson(v)) throw Error('Noncanonical or modified ABI review');
+    return parsed;
+}
+export function reviewTransaction(tx: ReleaseExecutionTransaction, invocation: CalldataInvocation): CalldataTransactionReview {
+    const parsed = parseCalldataInvocation(invocation);
+    if (parsed.kind !== 'function' || parsed.data !== tx.data) throw Error('ABI review transaction calldata mismatch');
+    return deepFreeze({ transactionId: tx.transactionId, to: tx.to, value: tx.value, operation: tx.operation, invocation: parsed });
+}
+export function parseCalldataReviews(raw: unknown, transactions: readonly ReleaseExecutionTransaction[]): CalldataTransactionReview[] {
+    if (!Array.isArray(raw) || raw.length !== transactions.length) throw Error('Complete calldata ABI review required');
+    return deepFreeze(raw.map((value, index) => {
+        const v = strictData(value) as CalldataTransactionReview, expected = reviewTransaction(transactions[index], v.invocation);
+        if (canonicalJson(v) !== canonicalJson(expected)) throw Error('ABI review transaction binding mismatch');
+        return expected;
+    }));
+}

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 canonical codec; rebuilt from the recorded SmartFlow sources.
+export const PLAN_CODEC_SOURCE_COMMIT = "ee0f90991ca1a94c3f58c8893df16d0c8c41b230";
+export const PLAN_CODEC_PROVENANCE_SHA256 = "212e560b26b7560a73df1f20bd789fce1e5c3f409afba2d5a5c5c39cb2518ce7";

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