gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/custom-closure.ts

@@ -0,0 +1,993 @@
+import { closureRuntimeOptions, parseCustomInputClosure, type HostAdapter, type ClosureFile, type ClosureEdge, type ClosurePackage, type CustomInputClosure } from "./closure-format";
+export { parseCustomInputClosure, type ClosureFile, type ClosureEdge, type ClosurePackage, type CustomInputClosure } from "./closure-format";
+/** Bounded deterministic CJS input collector. Supported-code validation, not a hostile-code sandbox. */
+import fs from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import ts from "typescript";
+import { confinedFile, stat } from "./project-files";
+import { strictData } from "./data";
+import { parseInputDocument } from './input-files';
+import { portablePath } from "./protocol";
+import {
+  canonicalJson,
+  deepFreeze,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+
+const hash = (bytes: Buffer | string) =>
+  createHash("sha256").update(bytes).digest("hex");
+const portable = (name: string) => name.split(path.sep).join("/");
+const compare = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const extensions = [".ts", ".cts", ".js", ".cjs", ".json"];
+const policy = "gate-custom-cjs@1" as const;
+/** Validate before normalization; only the supplied project root and its realpath are aliases. */
+export function customBusinessRoot(root: string, businessRoot: string): string {
+  if (
+    typeof businessRoot !== "string" ||
+    !path.isAbsolute(businessRoot) ||
+    businessRoot.includes("\\") ||
+    businessRoot.split(path.sep).some((part) => part === "." || part === "..")
+  )
+    throw new Error("Unsafe custom business root directory");
+  const canonicalRoot = fs.realpathSync(root);
+  const base = path.resolve(businessRoot);
+  const alias = [path.resolve(root), canonicalRoot].find(
+    (candidate) => base === candidate || base.startsWith(candidate + path.sep)
+  );
+  if (!alias)
+    throw new Error("Custom business root must be confined to the project");
+  const relative = portable(path.relative(alias, base));
+  // A not-yet-created task directory is valid when the script uses no file ports.
+  return relative
+    ? confinedFile(canonicalRoot, relative, "directory")
+    : canonicalRoot;
+}
+interface Captured {
+  identity: ClosureFile;
+  bytes: Buffer;
+  emitted?: string;
+}
+const runtimeOptions: ts.CompilerOptions = closureRuntimeOptions;
+const ambient = new Set([
+  "process",
+  "global",
+  "globalThis",
+  "window",
+  "self",
+  "document",
+  "Deno",
+  "Bun",
+  "Date",
+  "performance",
+  "crypto",
+  "fetch",
+  "WebSocket",
+  "XMLHttpRequest",
+  "Worker",
+  "SharedArrayBuffer",
+  "Atomics",
+  "Buffer",
+  "console",
+  "setTimeout",
+  "setInterval",
+  "setImmediate",
+  "queueMicrotask",
+  "eval",
+  "Function",
+  "AsyncFunction",
+  "WebAssembly",
+  "createRequire",
+  "__dirname",
+  "__filename",
+  "Intl",
+  "Reflect",
+  "Proxy",
+  "WeakRef",
+  "FinalizationRegistry",
+]);
+const forbiddenMembers = new Set([
+  "constructor",
+  "__proto__",
+  "getPrototypeOf",
+  "setPrototypeOf",
+  "getOwnPropertyDescriptor",
+  "getOwnPropertyDescriptors",
+  "random",
+  "stack",
+  "captureStackTrace",
+  "prepareStackTrace",
+]);
+/** Same restrictions for business ports and project imports: config/provenance is a separate future projection. */
+export function assertBusinessInput(
+  relative: string,
+  packageCode = false
+): void {
+  portablePath(relative, "business input path");
+  if (/[*?\[\]{}]/.test(relative))
+    throw new Error("Unsupported directory/glob business input");
+  if (
+    relative
+      .split("/")
+      .some(
+        (segment) =>
+          /^(?:\.env.*|\.npmrc(?:\..*)?|\.yarnrc(?:\..*)?|\.git|\.ssh|\.aws|\.openzeppelin(?:\..*)?|keys?|keystores?|credentials?|secrets?|wallets?|results?|reports?|status|releases?|candidates?|handoffs?|manifests?)(?:\..*)?$/i.test(
+            segment
+          ) ||
+          /^(?:contractInfo|deploymentInfo|state|release|pending|handoff|manifest|status|private[-_]?keys?|package-lock|npm-shrinkwrap|yarn\.lock|pnpm-lock|deploy(?:ment)?[-_.]?(?:config|settings)|\.gate-template|hardhat\.config|foundry)(?:\..*)?$/i.test(
+            segment
+          ) ||
+          /\.(?:pem|key|p12|pfx)$/i.test(segment) ||
+          (!packageCode &&
+            /^(?:artifacts?|cache|dist(?:-.*)?|node_modules|config|configs|deployments?)(?:\..*)?$/i.test(
+              segment
+            ))
+      )
+  )
+    throw new Error(
+      "Business input cannot access sensitive, generated-state or private config paths"
+    );
+}
+function packageName(specifier: string): string {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+function propertyText(node: ts.Node): string {
+  if (ts.isComputedPropertyName(node)) return propertyText(node.expression);
+  return ts.isIdentifier(node) ||
+    ts.isStringLiteral(node) ||
+    ts.isNumericLiteral(node)
+    ? node.text
+    : "";
+}
+function staticEdges(source: string, name: string): string[] {
+  const ast = ts.createSourceFile(
+    name,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    name.endsWith(".ts") || name.endsWith(".cts")
+      ? ts.ScriptKind.TS
+      : ts.ScriptKind.JS
+  );
+  if (
+    (ast as ts.SourceFile & { parseDiagnostics: readonly ts.Diagnostic[] })
+      .parseDiagnostics.length
+  )
+    throw new Error(`Unsupported module syntax: ${name}`);
+  const edges = new Set<string>();
+  const literal = (node: ts.Node | undefined) => {
+    if (!node || !ts.isStringLiteral(node))
+      throw new Error(`Unsupported nonliteral loader: ${name}`);
+    edges.add(node.text);
+  };
+  const visit = (node: ts.Node): void => {
+    // Transpile-only type edges are deliberately absent from the runtime graph.
+    if (
+      ts.isTypeNode(node) ||
+      ts.isInterfaceDeclaration(node) ||
+      ts.isTypeAliasDeclaration(node)
+    )
+      return;
+    if (ts.isImportDeclaration(node)) {
+      const clause = node.importClause;
+      if (
+        clause?.isTypeOnly ||
+        (clause &&
+          !clause.name &&
+          clause.namedBindings &&
+          ts.isNamedImports(clause.namedBindings) &&
+          clause.namedBindings.elements.every((e) => e.isTypeOnly))
+      )
+        return;
+      literal(node.moduleSpecifier);
+      return;
+    }
+    if (ts.isExportDeclaration(node)) {
+      if (
+        node.isTypeOnly ||
+        (node.exportClause &&
+          ts.isNamedExports(node.exportClause) &&
+          node.exportClause.elements.length > 0 &&
+          node.exportClause.elements.every((e) => e.isTypeOnly))
+      )
+        return;
+      if (node.moduleSpecifier) literal(node.moduleSpecifier);
+      return;
+    }
+    if (ts.isImportEqualsDeclaration(node)) {
+      if (node.isTypeOnly) return;
+      if (!ts.isExternalModuleReference(node.moduleReference))
+        throw new Error(`Unsupported import alias: ${name}`);
+      literal(node.moduleReference.expression);
+      return;
+    }
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword
+    )
+      throw new Error(`Unsupported runtime import loader: ${name}`);
+    if (ts.isIdentifier(node)) {
+      if (ambient.has(node.text))
+        throw new Error(`Unsupported ambient capability ${node.text}: ${name}`);
+      if (node.text === "require") {
+        const p = node.parent;
+        if (
+          !ts.isCallExpression(p) ||
+          p.expression !== node ||
+          p.arguments.length !== 1
+        )
+          throw new Error(`Unsupported require loader access: ${name}`);
+        literal(p.arguments[0]);
+      }
+      if (
+        node.text === "module" &&
+        !(
+          ts.isPropertyAccessExpression(node.parent) &&
+          node.parent.expression === node &&
+          node.parent.name.text === "exports"
+        )
+      )
+        throw new Error(`Unsupported module loader access: ${name}`);
+    }
+    if (
+      (ts.isElementAccessExpression(node) &&
+        !ts.isStringLiteral(node.argumentExpression) &&
+        !ts.isNumericLiteral(node.argumentExpression)) ||
+      (ts.isComputedPropertyName(node) &&
+        ((!ts.isStringLiteral(node.expression) &&
+          !ts.isNumericLiteral(node.expression)) ||
+          forbiddenMembers.has(propertyText(node)))) ||
+      (ts.isBindingElement(node) &&
+        forbiddenMembers.has(propertyText(node.propertyName ?? node.name)))
+    )
+      throw new Error(`Unsupported dynamic reflective access: ${name}`);
+    if (
+      (ts.isPropertyAccessExpression(node) &&
+        forbiddenMembers.has(node.name.text)) ||
+      (ts.isElementAccessExpression(node) &&
+        node.argumentExpression &&
+        ts.isStringLiteral(node.argumentExpression) &&
+        forbiddenMembers.has(node.argumentExpression.text))
+    )
+      throw new Error(`Unsupported reflective or ambient access: ${name}`);
+    ts.forEachChild(node, visit);
+  };
+  visit(ast);
+  return [...edges].sort();
+}
+
+/** A fresh Node process avoids require.resolve's path and package-json caches during drift checks. */
+function nodeResolve(
+  root: string,
+  importer: string,
+  specifier: string
+): string {
+  const output = spawnSync(
+    process.execPath,
+    [
+      "--preserve-symlinks",
+      "-e",
+      `const fs=require('node:fs'),{createRequire}=require('node:module');const q=JSON.parse(fs.readFileSync(0,'utf8'));try{process.stdout.write(createRequire(q.importer).resolve(q.specifier))}catch{process.exitCode=1}`,
+    ],
+    {
+      cwd: root,
+      env: {},
+      input: JSON.stringify({ importer, specifier }),
+      encoding: "utf8",
+      timeout: 10000,
+      maxBuffer: 1024 * 1024,
+    }
+  );
+  if (output.status !== 0 || !path.isAbsolute(output.stdout))
+    throw new Error(
+      "Unsupported ambient package or missing Node CJS resolution"
+    );
+  return output.stdout;
+}
+function validateHost(root: string): CustomInputClosure["hostAdapter"] {
+  if (
+    process.env.NODE_PATH ||
+    process.env.NODE_OPTIONS ||
+    Object.keys(process.env).some((k) => k.startsWith("TS_NODE_"))
+  )
+    throw new Error("Unsupported ambient loader environment");
+  const args = process.execArgv;
+  // Node's test runner may pass only test-related switches, which do not install loaders.
+  const relevant = args.filter((a) => !/^--test(?:=|$|-)/.test(a));
+  if (!relevant.length)
+    return { kind: "isolated-cjs", preload: null, packages: [] };
+  if (
+    relevant.length !== 2 ||
+    !["-r", "--require"].includes(relevant[0]) ||
+    relevant[1] !== "ts-node/register"
+  )
+    throw new Error("Unsupported preload, loader or conditions");
+  try {
+    const packages: HostAdapter["packages"] = [];
+    const lock = JSON.parse(
+      fs.readFileSync(confinedFile(root, "package-lock.json"), "utf8")
+    );
+    for (const [name, version] of [
+      ["ts-node", "10.9.2"],
+      ["hardhat", "2.26.3"],
+    ]) {
+      const bytes = fs.readFileSync(
+        confinedFile(root, `node_modules/${name}/package.json`)
+      );
+      const metadata = JSON.parse(bytes.toString("utf8"));
+      const locked = lock.packages?.[`node_modules/${name}`];
+      if (
+        ![2, 3].includes(lock.lockfileVersion) ||
+        metadata.name !== name ||
+        metadata.version !== version ||
+        locked?.version !== version ||
+        locked?.link
+      )
+        throw new Error();
+      packages.push({ name, version, metadataDigest: hash(bytes) });
+    }
+    const actual = nodeResolve(
+      root,
+      path.join(root, "package.json"),
+      "ts-node/register"
+    );
+    if (
+      actual !== confinedFile(root, "node_modules/ts-node/register/index.js") ||
+      !require.cache[actual]?.loaded
+    )
+      throw new Error();
+    if (
+      process.env.HARDHAT_TSCONFIG &&
+      path.resolve(process.env.HARDHAT_TSCONFIG) !==
+        path.join(root, "tsconfig.json")
+    )
+      throw new Error();
+    return {
+      kind: "hardhat-2.26.3-ts-node-10.9.2",
+      preload: {
+        path: "node_modules/ts-node/register/index.js",
+        digest: hash(fs.readFileSync(actual)),
+      },
+      packages,
+    };
+  } catch {
+    throw new Error(
+      "Unsupported pinned Hardhat preload adapter identity/location"
+    );
+  }
+}
+
+export class CustomModuleClosure {
+  readonly #root: string;
+  readonly #inputRoot: string;
+  readonly #files = new Map<string, Captured>();
+  readonly #edges = new Map<string, ClosureEdge>();
+  readonly #packages = new Map<string, ClosurePackage>();
+  readonly #roots = new Set<string>();
+  #failure: Error | undefined;
+  readonly #absent = new Set<string>();
+  readonly #cache = new Map<string, { exports: unknown }>();
+  readonly #context = vm.createContext(Object.create(null), {
+    codeGeneration: { strings: false, wasm: false },
+  });
+  readonly #realm: { object: object; array: object };
+  readonly #options: ts.CompilerOptions = { ...runtimeOptions };
+  readonly #adapter: CustomInputClosure["hostAdapter"];
+  #config: string | null = null;
+  constructor(root: string) {
+    if (ts.version !== "5.9.3")
+      throw new Error("Unsupported custom TypeScript compiler version");
+    this.#inputRoot = path.resolve(root);
+    this.#root = fs.realpathSync(root);
+    this.#adapter = validateHost(this.#root);
+    this.#realm = vm.runInContext(
+      "({object:Object.prototype,array:Array.prototype})",
+      this.#context
+    );
+    vm.runInContext(
+      'Object.defineProperty(Math,"random",{value:undefined});Object.freeze(Math);',
+      this.#context
+    );
+    this.#readConfig();
+  }
+  #relative(file: string): string {
+    const relative = portable(path.relative(this.#root, file));
+    portablePath(relative, "confined module path");
+    return relative;
+  }
+  #file(relative: string): string {
+    return confinedFile(this.#root, relative);
+  }
+  #capture(relative: string, kind: ClosureFile["kind"]): Captured {
+    const bytes = fs.readFileSync(this.#file(relative));
+    const previous = this.#files.get(relative);
+    if (previous) {
+      if (hash(bytes) !== previous.identity.digest)
+        throw new Error(`Custom input changed during session: ${relative}`);
+      if (
+        kind === "module" ||
+        kind === "json" ||
+        (kind === "config" && previous.identity.kind === "metadata")
+      )
+        previous.identity.kind = kind;
+      return previous;
+    }
+    const captured: Captured = {
+      identity: {
+        path: relative,
+        kind,
+        digest: hash(bytes),
+        emittedDigest: null,
+      },
+      bytes,
+    };
+    this.#files.set(relative, captured);
+    return captured;
+  }
+  #metadata(relative: string): Record<string, unknown> {
+    try {
+      return strictData(
+        JSON.parse(this.#capture(relative, "metadata").bytes.toString("utf8"))
+      );
+    } catch {
+      throw new Error("Invalid package metadata");
+    }
+  }
+  #sourceFormat(relative: string): void {
+    let dir = path.posix.dirname(relative);
+    while (true) {
+      const name = dir === "." ? "package.json" : `${dir}/package.json`;
+      if (stat(this.#file(name))) {
+        const metadata = this.#metadata(name);
+        if (
+          (relative.endsWith(".js") || relative.endsWith(".ts")) &&
+          metadata.type === "module"
+        )
+          throw new Error("Unsupported native ESM source format");
+        break;
+      }
+      this.#absent.add(name);
+      if (dir === ".") break;
+      dir = path.posix.dirname(dir);
+    }
+  }
+  #packageFor(relative: string): string | null {
+    const parts = relative.split("/");
+    const i = parts.lastIndexOf("node_modules");
+    if (i < 0) return null;
+    const count = parts[i + 1]?.startsWith("@") ? 3 : 2;
+    if (parts.length <= i + count)
+      throw new Error("Invalid package runtime path");
+    return parts.slice(0, i + count).join("/");
+  }
+  #payload(location: string): ClosurePackage["payload"] {
+    const entries: ClosurePackage["payload"] = [];
+    const walk = (dir: string) => {
+      for (const name of fs
+        .readdirSync(
+          confinedFile(
+            this.#root,
+            `${location}${dir ? "/" + dir : ""}`,
+            "directory"
+          )
+        )
+        .sort()) {
+        if (name === "node_modules") continue; // Independently resolved nested packages; never merge identities.
+        const relative = dir ? `${dir}/${name}` : name;
+        const info = stat(path.join(this.#root, location, relative))!;
+        if (info.isSymbolicLink())
+          throw new Error("Unsafe symlink in package payload");
+        if (info.isDirectory()) walk(relative);
+        else {
+          const file = this.#file(`${location}/${relative}`);
+          if (name.endsWith(".node"))
+            throw new Error("Unsupported native package payload");
+          entries.push({ path: relative, digest: hash(fs.readFileSync(file)) });
+        }
+      }
+    };
+    walk("");
+    return entries.sort((a, b) => compare(a.path, b.path));
+  }
+  #package(location: string): ClosurePackage {
+    const metadata = this.#metadata(`${location}/package.json`);
+    let lock: Record<string, any>;
+    try {
+      lock = strictData(
+        JSON.parse(fs.readFileSync(this.#file("package-lock.json"), "utf8"))
+      );
+    } catch {
+      throw new Error("Custom packages require a local npm lock v2/v3");
+    }
+    if (
+      ![2, 3].includes(lock.lockfileVersion) ||
+      !lock.packages ||
+      typeof lock.packages !== "object"
+    )
+      throw new Error("Unsupported npm lock");
+    const entry = Object.getOwnPropertyDescriptor(
+      lock.packages,
+      location
+    )?.value;
+    const installedName = location
+      .split("/node_modules/")
+      .at(-1)!
+      .replace(/^node_modules\//, "");
+    if (
+      !entry ||
+      entry.link ||
+      entry.extraneous ||
+      typeof metadata.name !== "string" ||
+      metadata.name !== installedName ||
+      (entry.name !== undefined && entry.name !== metadata.name) ||
+      entry.version !== metadata.version ||
+      typeof metadata.version !== "string" ||
+      !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(metadata.version)
+    )
+      throw new Error(
+        "Package lock identity/version mismatch or extraneous package"
+      );
+    if (
+      typeof entry.integrity !== "string" ||
+      !/^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/.test(entry.integrity) ||
+      Buffer.from(entry.integrity.split("-")[1], "base64").length !==
+        Number(entry.integrity.slice(3).split("-")[0]) / 8 ||
+      typeof entry.resolved !== "string"
+    )
+      throw new Error("Package requires locked source integrity");
+    const tarball = /^file:.*\.tgz$/.test(entry.resolved);
+    if (!tarball && !/^https?:\/\//.test(entry.resolved))
+      throw new Error(
+        "Unsupported package source: directory/workspace links are not supported"
+      );
+    const resolution = Object.fromEntries(
+      ["type", "main", "exports", "imports"]
+        .filter((k) => Object.hasOwn(metadata, k))
+        .map((k) => [k, metadata[k]])
+    );
+    const payload = this.#payload(location);
+    const result: ClosurePackage = {
+      lockLocation: location,
+      name: metadata.name,
+      version: metadata.version,
+      integrity: entry.integrity,
+      // Never serialize URLs or local tarball paths; installed payload and tarball SRI are separate identities.
+      source: {
+        kind: tarball ? "tarball" : "registry",
+        identity: tarball ? hash(entry.integrity) : hash(entry.resolved),
+      },
+      metadataDigest: this.#files.get(`${location}/package.json`)!.identity
+        .digest,
+      resolution,
+      payload,
+      payloadDigest: semanticHash(payload),
+    };
+    const previous = this.#packages.get(location);
+    if (previous && canonicalJson(previous) !== canonicalJson(result))
+      throw new Error(`Package payload/lock drift: ${location}`);
+    this.#packages.set(location, result);
+    return result;
+  }
+  #resolve(
+    importer: string,
+    specifier: string,
+    kind: ClosureEdge["kind"]
+  ): string {
+    if (
+      !specifier ||
+      specifier.includes("\\") ||
+      specifier.startsWith("#") ||
+      path.isAbsolute(specifier) ||
+      /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(specifier)
+    )
+      throw new Error("Unsupported loader specifier");
+    if (specifier.startsWith(".")) {
+      const base = this.#relative(
+        path.resolve(this.#root, path.posix.dirname(importer), specifier)
+      );
+      const importerPackage = this.#packageFor(importer);
+      assertBusinessInput(base, !!importerPackage);
+      if (importerPackage) {
+        const selected = this.#relative(
+          nodeResolve(this.#root, path.join(this.#root, importer), specifier)
+        );
+        const location = this.#packageFor(selected);
+        if (!location)
+          throw new Error("Unsupported package relative resolution escape");
+        this.#file(selected);
+        this.#package(location);
+        return selected;
+      }
+      const candidates = path.posix.extname(base)
+        ? [base]
+        : [
+            base,
+            ...extensions.map((ext) => base + ext),
+            ...extensions.map((ext) => `${base}/index${ext}`),
+          ];
+      const present = candidates.filter((name) => {
+        const info = stat(path.join(this.#root, name));
+        if (!info) return false;
+        if (info.isDirectory()) {
+          confinedFile(this.#root, name, "directory");
+          return false;
+        }
+        this.#file(name);
+        return info.isFile();
+      });
+      if (present.length !== 1)
+        throw new Error(`Missing or ambiguous runtime target: ${importer}`);
+      return present[0];
+    }
+    if (
+      specifier.split("/").some((p) => !p || p === "." || p === "..") ||
+      !/^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9_-][A-Za-z0-9._-]*(\/.*)?$/.test(
+        specifier
+      )
+    )
+      throw new Error("Unsupported package specifier");
+    const selected = this.#relative(
+      nodeResolve(this.#root, path.join(this.#root, importer), specifier)
+    );
+    const location = this.#packageFor(selected);
+    if (!location || !selected.startsWith(location + "/"))
+      throw new Error("Unsupported ancestor/global package resolution");
+    this.#file(selected);
+    const metadata = this.#package(location);
+    if (metadata.name !== packageName(specifier))
+      throw new Error("Package resolution identity mismatch");
+    if (
+      kind === "runtime" &&
+      (selected.endsWith(".mjs") ||
+        selected.endsWith(".node") ||
+        (selected.endsWith(".js") && metadata.resolution.type === "module"))
+    )
+      throw new Error("Unsupported native ESM or addon package");
+    return selected;
+  }
+  #edge(
+    importer: string,
+    specifier: string,
+    kind: ClosureEdge["kind"]
+  ): string {
+    const target = this.#resolve(importer, specifier, kind);
+    const key = canonicalJson([importer, specifier, kind]);
+    const previous = this.#edges.get(key);
+    if (previous && previous.target !== target)
+      throw new Error("Custom resolution drift");
+    this.#edges.set(key, { importer, specifier, target, kind });
+    return target;
+  }
+  #readConfig(): void {
+    const rootConfig = "tsconfig.json";
+    const active = new Set<string>();
+    const read = (name: string): Record<string, unknown> => {
+      assertBusinessInput(name, true);
+      const location = this.#packageFor(name);
+      if (location) this.#package(location);
+      if (active.has(name))
+        throw new Error("Unsupported tsconfig extends cycle");
+      active.add(name);
+      const raw = ts.parseConfigFileTextToJson(
+        name,
+        this.#capture(name, "config").bytes.toString("utf8")
+      );
+      if (raw.error) throw new Error("Invalid tsconfig JSONC");
+      const value = strictData(raw.config) as Record<string, any>;
+      if (Object.hasOwn(value, "ts-node") || Object.hasOwn(value, "plugins"))
+        throw new Error("Unsupported tsconfig loader hooks");
+      let inherited: Record<string, unknown> = {};
+      if (value.extends !== undefined) {
+        if (typeof value.extends !== "string")
+          throw new Error("Unsupported tsconfig extends");
+        const spec = value.extends;
+        const parent = spec.startsWith(".")
+          ? this.#relative(
+              path.resolve(
+                this.#root,
+                path.posix.dirname(name),
+                spec.endsWith(".json") ? spec : spec + ".json"
+              )
+            )
+          : this.#edge(name, spec, "config");
+        if (spec.startsWith(".")) {
+          this.#edges.set(canonicalJson([name, spec, "config"]), {
+            importer: name,
+            specifier: spec,
+            target: parent,
+            kind: "config",
+          });
+        }
+        inherited = read(parent);
+      }
+      const options = value.compilerOptions ?? {};
+      if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new Error("Invalid compiler options");
+      for (const key of [
+        "baseUrl",
+        "paths",
+        "rootDirs",
+        "plugins",
+        "customConditions",
+        "moduleSuffixes",
+        "outFile",
+        "jsx",
+        "jsxFactory",
+        "jsxImportSource",
+        "experimentalDecorators",
+        "emitDecoratorMetadata",
+        "importHelpers",
+        "noResolve",
+      ])
+        if (Object.hasOwn(options, key))
+          throw new Error(`Unsupported runtime compiler option/alias: ${key}`);
+      active.delete(name);
+      return { ...inherited, ...options };
+    };
+    if (stat(this.#file(rootConfig))) {
+      this.#config = rootConfig;
+      const options = read(rootConfig);
+      const parsed = ts.convertCompilerOptionsFromJson(options, ".");
+      if (parsed.errors.length)
+        throw new Error("Unsupported or invalid tsconfig options");
+      if (
+        parsed.options.module !== undefined &&
+        ![
+          ts.ModuleKind.CommonJS,
+          ts.ModuleKind.Node16,
+          ts.ModuleKind.NodeNext,
+        ].includes(parsed.options.module)
+      )
+        throw new Error("Unsupported runtime module option");
+      if (parsed.options.target !== undefined)
+        this.#options.target = parsed.options.target;
+      if (parsed.options.esModuleInterop !== undefined)
+        this.#options.esModuleInterop = parsed.options.esModuleInterop;
+      if (parsed.options.useDefineForClassFields !== undefined)
+        this.#options.useDefineForClassFields =
+          parsed.options.useDefineForClassFields;
+    } else this.#absent.add(rootConfig);
+  }
+  #collect(relative: string): void {
+    if (
+      this.#files.get(relative)?.identity.kind === "module" ||
+      this.#files.get(relative)?.identity.kind === "json"
+    )
+      return;
+    const location = this.#packageFor(relative);
+    assertBusinessInput(
+      location ? relative.slice(location.length + 1) : relative,
+      !!location
+    );
+    if (location) this.#package(location);
+    const ext = path.posix.extname(relative);
+    if (!extensions.includes(ext) || /\.d\.(?:ts|cts)$/.test(relative))
+      throw new Error("Unsupported runtime module extension");
+    if (location && [".ts", ".cts"].includes(ext))
+      throw new Error("Unsupported package TypeScript runtime adapter");
+    this.#sourceFormat(relative);
+    const captured = this.#capture(
+      relative,
+      ext === ".json" ? "json" : "module"
+    );
+    if (ext === ".json") {
+      parseInputDocument(captured.bytes, 'json');
+      return;
+    }
+    const dependencies = staticEdges(captured.bytes.toString("utf8"), relative);
+    const emitted = ts.transpileModule(captured.bytes.toString("utf8"), {
+      compilerOptions: this.#options,
+      fileName: relative,
+      reportDiagnostics: true,
+    });
+    if (
+      emitted.diagnostics?.some(
+        (d) => d.category === ts.DiagnosticCategory.Error
+      )
+    )
+      throw new Error(`Unsupported transpilation: ${relative}`);
+    captured.emitted = emitted.outputText;
+    captured.identity.emittedDigest = hash(emitted.outputText);
+    for (const specifier of dependencies)
+      this.#collect(this.#edge(relative, specifier, "runtime"));
+  }
+  #load(relative: string): any {
+    const previous = this.#cache.get(relative);
+    if (previous) return previous.exports; // Node CJS cycle semantics: publish partial exports before evaluation.
+    const captured = this.#files.get(relative)!;
+    const module = { exports: {} as unknown };
+    this.#cache.set(relative, module);
+    try {
+      if (captured.identity.kind === "json")
+        module.exports = deepFreeze(
+          parseInputDocument(captured.bytes, 'json')
+        );
+      else {
+        const ownedRequire = (specifier: string) => {
+          const edge = this.#edges.get(
+            canonicalJson([relative, specifier, "runtime"])
+          );
+          if (!edge) throw new Error("Unsupported uncaptured loader access");
+          return this.#load(edge.target);
+        };
+        const wrapper = new vm.Script(
+          `(function(exports,module,require){"use strict";\n${captured.emitted}\n})`,
+          { filename: relative }
+        ).runInContext(this.#context);
+        wrapper(module.exports, module, ownedRequire);
+      }
+      return module.exports;
+    } catch (error) {
+      // CJS retries failed initializers, retaining any successfully loaded dependencies.
+      this.#cache.delete(relative);
+      throw error;
+    }
+  }
+  /** Normalize only this collector's own VM prototypes; never invoke getters or toJSON. */
+  normalize(raw: unknown): unknown {
+    const active = new Set<object>();
+    const visit = (value: unknown): unknown => {
+      if (
+        value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isSafeInteger(value))
+      )
+        return value;
+      if (
+        !value ||
+        typeof value !== "object" ||
+        active.has(value) ||
+        Object.getOwnPropertySymbols(value).length
+      )
+        throw new Error("Custom result requires acyclic own JSON data");
+      const array = Array.isArray(value),
+        proto = Object.getPrototypeOf(value);
+      if (
+        !(
+          array
+            ? [this.#realm.array, Array.prototype]
+            : [this.#realm.object, Object.prototype, null]
+        ).includes(proto)
+      )
+        throw new Error("Custom result requires plain own data");
+      const keys = Object.getOwnPropertyNames(value);
+      if (
+        array &&
+        (keys.length !== value.length + 1 ||
+          keys.some(
+            (k) =>
+              k !== "length" &&
+              (!/^(0|[1-9][0-9]*)$/.test(k) || Number(k) >= value.length)
+          ))
+      )
+        throw new Error("Custom result requires dense own array data");
+      active.add(value);
+      const out: Record<string, unknown> | unknown[] = array ? [] : {};
+      for (const key of keys) {
+        if (array && key === "length") continue;
+        const d = Object.getOwnPropertyDescriptor(value, key)!;
+        if (!d.enumerable || !("value" in d))
+          throw new Error("Custom result requires enumerable own data");
+        Object.defineProperty(out, key, {
+          value: visit(d.value),
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        });
+      }
+      active.delete(value);
+      return out;
+    };
+    return strictData(visit(raw));
+  }
+  #readsClosed=false;
+  closeReads(): void {this.#readsClosed=true;}
+  load(relative: string): {
+    module: any;
+    identity: { path: string; digest: string };
+  } {
+    try {
+      if(this.#readsClosed)throw new Error("Custom input reads closed");
+      portablePath(relative, "custom module");
+      this.assertUnchanged();
+      this.#collect(relative);
+      this.#roots.add(relative);
+      return {
+        module: this.#load(relative),
+        identity: {
+          path: relative,
+          digest: this.#files.get(relative)!.identity.digest,
+        },
+      };
+    } catch (error) {
+      this.#failure =
+        error instanceof Error
+          ? error
+          : new Error("Unsupported module evaluation");
+      throw error;
+    }
+  }
+  readData(root: string, relative: string): { bytes: Buffer; path: string } {
+    if(this.#readsClosed)throw new Error("Custom input reads closed");
+    assertBusinessInput(relative);
+    const base = customBusinessRoot(this.#inputRoot, root);
+    const name = portable(path.relative(this.#root, path.join(base, relative)));
+    portablePath(name, "business input");
+    assertBusinessInput(name);
+    return {
+      bytes: Buffer.from(this.#capture(name, "data").bytes),
+      path: name,
+    };
+  }
+  assertUnchanged(): void {
+    if (this.#failure)
+      throw new Error(
+        `Custom closure collection failed: ${this.#failure.message}`
+      );
+    if (
+      canonicalJson(validateHost(this.#root)) !== canonicalJson(this.#adapter)
+    )
+      throw new Error("Host loader adapter drift");
+    for (const name of this.#absent)
+      if (stat(this.#file(name)))
+        throw new Error(`Custom resolution metadata changed: ${name}`);
+    for (const [name, value] of this.#files)
+      if (hash(fs.readFileSync(this.#file(name))) !== value.identity.digest)
+        throw new Error(`Custom input drift: ${name}`);
+    for (const edge of this.#edges.values()) {
+      const selected =
+        edge.kind === "config" && edge.specifier.startsWith(".")
+          ? this.#relative(
+              path.resolve(
+                this.#root,
+                path.posix.dirname(edge.importer),
+                edge.specifier.endsWith(".json")
+                  ? edge.specifier
+                  : edge.specifier + ".json"
+              )
+            )
+          : this.#resolve(edge.importer, edge.specifier, edge.kind);
+      if (selected !== edge.target)
+        throw new Error("Custom resolution changed during session");
+    }
+    for (const location of this.#packages.keys()) this.#package(location);
+  }
+  seal(): CustomInputClosure {
+    this.assertUnchanged();
+    const body = {
+      version: 1 as const,
+      policy,
+      roots: [...this.#roots].sort(),
+      files: [...this.#files.values()]
+        .map((f) => ({ ...f.identity }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+      edges: [...this.#edges.values()].sort((a, b) =>
+        compare(canonicalJson(a), canonicalJson(b))
+      ),
+      packages: [...this.#packages.values()].sort((a, b) =>
+        compare(a.lockLocation, b.lockLocation)
+      ),
+      compiler: {
+        version: ts.version,
+        options: { ...this.#options },
+        config: this.#config,
+      },
+      hostAdapter: this.#adapter,
+      resolver: {
+        policy: "node-default-cjs" as const,
+        version: process.versions.node,
+        flags: ["--preserve-symlinks"],
+        environment: "empty" as const,
+      },
+    };
+    return deepFreeze({ ...body, closureHash: semanticHash(body) });
+  }
+}
+
+Object.freeze(CustomModuleClosure.prototype);
+
+/** Pure structural parser; only collector-owned sessions establish collection authority. */