gate-evm-tools 1.0.28 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gate-evm-tools",
-  "version": "1.0.28",
+  "version": "1.0.31",
   "description": "Gate 智能合约工具集 - 字节码检查、合约升级验证、合约状态同步",
   "type": "module",
   "exports": {
@@ -32,7 +32,76 @@
       "types": "./dist-runtime/config/*.d.ts",
       "default": "./dist-runtime/config/*.js"
     },
-    "./runtime-source/*": "./runtime/*.ts"
+    "./runtime-source/*": "./runtime/*.ts",
+    "./delivery-setup": {
+      "types": "./dist-runtime/delivery/setup.d.ts",
+      "default": "./dist-runtime/delivery/setup.js"
+    },
+    "./delivery-protocol": {
+      "types": "./dist-runtime/delivery/protocol.d.ts",
+      "default": "./dist-runtime/delivery/protocol.js"
+    },
+    "./delivery-hardhat": {
+      "types": "./dist-runtime/delivery/hardhat.d.ts",
+      "default": "./dist-runtime/delivery/hardhat.js"
+    },
+    "./delivery-policy": {
+      "types": "./dist/delivery/policy.d.ts",
+      "import": "./dist/delivery/policy.js",
+      "require": "./dist-cjs/delivery/policy.js"
+    },
+    "./delivery-source": {
+      "types": "./dist-runtime/delivery/source.d.ts",
+      "default": "./dist-runtime/delivery/source.js"
+    },
+    "./delivery-parameters": {
+      "types": "./dist-runtime/delivery/parameters.d.ts",
+      "default": "./dist-runtime/delivery/parameters.js"
+    },
+    "./delivery-inputs": {
+      "types": "./dist-runtime/delivery/inputs.d.ts",
+      "default": "./dist-runtime/delivery/inputs.js"
+    },
+    "./delivery-configuration": {
+      "types": "./dist-runtime/delivery/configuration.d.ts",
+      "default": "./dist-runtime/delivery/configuration.js"
+    },
+    "./delivery-aggregate": {
+      "types": "./dist-runtime/delivery/aggregate.d.ts",
+      "default": "./dist-runtime/delivery/aggregate.js"
+    },
+    "./delivery-export": {
+      "types": "./dist-runtime/delivery/export.d.ts",
+      "default": "./dist-runtime/delivery/export.js"
+    },
+    "./delivery-execution-store": {
+      "types": "./dist-runtime/delivery/execution-store.d.ts",
+      "default": "./dist-runtime/delivery/execution-store.js"
+    },
+    "./delivery-eoa": {
+      "types": "./dist-runtime/delivery/eoa.d.ts",
+      "default": "./dist-runtime/delivery/eoa.js"
+    },
+    "./delivery-development": {
+      "types": "./dist-runtime/delivery/development.d.ts",
+      "default": "./dist-runtime/delivery/development.js"
+    },
+    "./delivery-release": {
+      "types": "./dist-runtime/delivery/release.d.ts",
+      "default": "./dist-runtime/delivery/release.js"
+    },
+    "./delivery-production": {
+      "types": "./dist-runtime/delivery/production.d.ts",
+      "default": "./dist-runtime/delivery/production.js"
+    },
+    "./delivery-safe": {
+      "types": "./dist-runtime/delivery/safe.d.ts",
+      "default": "./dist-runtime/delivery/safe.js"
+    },
+    "./create2-miner": {
+      "types": "./dist-runtime/miner/index.d.ts",
+      "default": "./dist-runtime/miner/index.js"
+    }
   },
   "typesVersions": {
     "*": {
@@ -53,12 +122,64 @@
       ],
       "runtime-config/*": [
         "dist-runtime/config/*.d.ts"
+      ],
+      "delivery-setup": [
+        "dist-runtime/delivery/setup.d.ts"
+      ],
+      "delivery-protocol": [
+        "dist-runtime/delivery/protocol.d.ts"
+      ],
+      "delivery-hardhat": [
+        "dist-runtime/delivery/hardhat.d.ts"
+      ],
+      "delivery-policy": [
+        "dist/delivery/policy.d.ts"
+      ],
+      "delivery-source": [
+        "dist-runtime/delivery/source.d.ts"
+      ],
+      "delivery-parameters": [
+        "dist-runtime/delivery/parameters.d.ts"
+      ],
+      "delivery-inputs": [
+        "dist-runtime/delivery/inputs.d.ts"
+      ],
+      "delivery-configuration": [
+        "dist-runtime/delivery/configuration.d.ts"
+      ],
+      "delivery-aggregate": [
+        "dist-runtime/delivery/aggregate.d.ts"
+      ],
+      "delivery-export": [
+        "dist-runtime/delivery/export.d.ts"
+      ],
+      "delivery-execution-store": [
+        "dist-runtime/delivery/execution-store.d.ts"
+      ],
+      "delivery-eoa": [
+        "dist-runtime/delivery/eoa.d.ts"
+      ],
+      "delivery-development": [
+        "dist-runtime/delivery/development.d.ts"
+      ],
+      "delivery-release": [
+        "dist-runtime/delivery/release.d.ts"
+      ],
+      "delivery-production": [
+        "dist-runtime/delivery/production.d.ts"
+      ],
+      "delivery-safe": [
+        "dist-runtime/delivery/safe.d.ts"
+      ],
+      "create2-miner": [
+        "dist-runtime/miner/index.d.ts"
       ]
     }
   },
   "bin": {
     "gate-tool": "./bin/cli.js",
-    "gate-workflow": "./bin/workflow.cjs"
+    "gate-workflow": "./bin/workflow.cjs",
+    "gate-delivery": "./bin/delivery.cjs"
   },
   "files": [
     "bin/",
@@ -68,15 +189,17 @@
     "contractInfo.example.json",
     "dist-runtime/",
     "runtime/",
-    "docs/"
+    "docs/",
+    "resources/create2/"
   ],
   "scripts": {
-    "build": "tsc && tsc -p tsconfig.custody-cjs.json && node scripts/write-cjs-package.mjs && tsc -p tsconfig.runtime.json && node scripts/write-runtime-package.mjs",
+    "build": "tsc && tsc -p tsconfig.custody-cjs.json && node scripts/write-cjs-package.mjs && tsc -p tsconfig.runtime.json && node scripts/stage-plan-codec.mjs && node scripts/write-runtime-package.mjs",
     "dev": "tsc --watch",
     "start": "node bin/cli.js",
     "pretest": "npm run build",
     "test": "node --test test/*.test.mjs",
-    "test:custody:hardhat-v6": "npm run build && node scripts/test-custody-hardhat-v6.mjs"
+    "test:custody:hardhat-v6": "npm run build && node scripts/test-custody-hardhat-v6.mjs",
+    "test:delivery:core": "npm run build && node --test test/integration/delivery-core.test.mjs"
   },
   "keywords": [
     "bytecode",
@@ -93,12 +216,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "ajv": "8.17.1",
     "chalk": "^5.3.0",
     "commander": "^11.1.0",
     "fs-extra": "^11.2.0",
     "ora": "^7.0.1",
     "prompts": "^2.4.2",
     "semver": "^7.8.5",
+    "typescript": "5.9.3",
     "yaml": "2.8.1",
     "zksync-ethers": "6.15.0"
   },
@@ -117,8 +242,7 @@
     "ethers": "^6.15.0",
     "ethers5": "npm:ethers@5.7.2",
     "hardhat": "2.27.1",
-    "ts-node": "10.9.2",
-    "typescript": "^5.9.3"
+    "ts-node": "10.9.2"
   },
   "peerDependencies": {
     "@matterlabs/hardhat-zksync-deploy": "1.8.0",
@@ -145,6 +269,6 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   }
 }

package/resources/create2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 0age
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/resources/create2/README.md

@@ -0,0 +1,9 @@
+# Bundled CREATE2 miner
+
+`smartflow_miner` accepts a single JSON request on stdin and emits a single final JSON response. These macOS arm64 and x64 executables are copied byte-for-byte from SmartFlowAI `resources/create2`, whose last resource commit was `a31308bdbe81c02181ff4bcd2b992681c184d40f`. The original application resources are unchanged.
+
+`manifest.json` records sizes, SHA-256 digests and provenance. The runtime also embeds the trusted digests and checks executable permissions before invoking a bundled binary. Editing the manifest cannot authorize a replacement binary.
+
+The local create2Crunch source reference is `38b2dcd55c45cc79947fb9bf5f363222adf24ab0`. It describes the JSON protocol, but is **not a proven build revision** for these existing executable artifacts. The exact build revision is unknown. The upstream MIT license is retained in `LICENSE`.
+
+No downloads, postinstall hooks, or application resource lookups are used. Other hosts require a compatible user-supplied build via `GATE_TOOL_CREATE2_MINER_BIN` or `binaryPath`. See [the API and CLI documentation](../../docs/create2-miner.md).

package/resources/create2/manifest.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "SmartFlowAI",
+    "resourceCommit": "a31308bdbe81c02181ff4bcd2b992681c184d40f",
+    "resourceDirectory": "resources/create2"
+  },
+  "rustReference": {
+    "repository": "create2Crunch",
+    "revision": "38b2dcd55c45cc79947fb9bf5f363222adf24ab0",
+    "provenBuildRevision": false
+  },
+  "binaryBuildRevision": null,
+  "provenanceNote": "Copied byte-for-byte from the existing SmartFlowAI resources. The Rust checkout is a protocol/source reference, not a proven revision used to build these binaries.",
+  "binaries": {
+    "darwin-arm64": {
+      "path": "darwin-arm64/smartflow_miner",
+      "sha256": "9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954",
+      "bytes": 1297616
+    },
+    "darwin-x64": {
+      "path": "darwin-x64/smartflow_miner",
+      "sha256": "a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82",
+      "bytes": 1306112
+    }
+  }
+}

package/runtime/config/openzeppelin.ts

@@ -3,20 +3,14 @@ import path from "path";
 import YAML from "yaml";
 import { parseForkSnapshotJson } from "../workflow/lib/forkSnapshot";
 
-export type DeploymentEnvironment = "local" | "development" | "production";
+import { validateManifestPolicy, type ManifestEnvironment } from "../delivery/policy";
+export type DeploymentEnvironment = ManifestEnvironment;
 
 export interface OpenZeppelinTargetConfig {
   environment: DeploymentEnvironment;
   openzeppelin?: { manifestDir?: unknown };
 }
 
-const TARGET_ENVIRONMENTS = new Set<DeploymentEnvironment>([
-  "local",
-  "development",
-  "production",
-]);
-const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
-
 const assertConfinedManifestDirectory = (root: string, manifestDir: string): void => {
   const rootPath = fs.realpathSync(root);
   const candidatePath = path.resolve(root, manifestDir);
@@ -37,19 +31,7 @@ export function resolveOpenZeppelinManifestDir(
   network: string,
   target: OpenZeppelinTargetConfig,
 ): string {
-  if (!TARGET_ENVIRONMENTS.has(target?.environment)) {
-    throw new Error(`Network ${network} must declare a valid deployment environment`);
-  }
-  const manifestDir = target.openzeppelin?.manifestDir;
-  if (typeof manifestDir !== "string" || !SAFE_MANIFEST_DIR.test(manifestDir)) {
-    throw new Error(`Network ${network} must declare one safe OpenZeppelin manifest directory segment`);
-  }
-  if (target.environment === "production" && manifestDir !== ".openzeppelin") {
-    throw new Error(`Production network ${network} must use exactly .openzeppelin`);
-  }
-  if (target.environment !== "production" && manifestDir === ".openzeppelin") {
-    throw new Error(`Non-production network ${network} must not use .openzeppelin`);
-  }
+  const manifestDir = validateManifestPolicy(target?.environment, target.openzeppelin?.manifestDir);
   assertConfinedManifestDirectory(root, manifestDir);
   return manifestDir;
 }

package/runtime/delivery/abi.ts

@@ -0,0 +1,225 @@
+import {
+  Interface,
+  ParamType,
+  Result,
+  isAddress,
+  getAddress,
+  type InterfaceAbi,
+} from "ethers";
+import { strictData, copyOwnData } from "./data";
+import { DEFERRED } from "./references";
+/** Explicit runtime return boundary. Only bigint and ethers Result extend own JSON data. */
+export function normalizeRuntimeValue(value: unknown): unknown {
+  if (typeof value === "bigint") return value.toString(10);
+  if (value instanceof Result)
+    return value.toArray(true).map(normalizeRuntimeValue);
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype)
+      throw new Error("Invalid runtime array prototype");
+    // Check shape/descriptors before reading; bigint is deliberately normalized afterwards.
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (
+      Object.getOwnPropertySymbols(value).length ||
+      Object.keys(descriptors).length !== value.length + 1
+    )
+      throw new Error("Invalid runtime array");
+    return Array.from({ length: value.length }, (_, i) => {
+      const d = descriptors[String(i)];
+      if (!d || !d.enumerable || !("value" in d))
+        throw new Error("Invalid runtime array");
+      return normalizeRuntimeValue(d.value);
+    });
+  }
+  return strictData(value);
+}
+export function validateAbiValue(
+  type: ParamType,
+  value: unknown,
+  label = "ABI value",
+  allowDeferred = false,
+): void {
+  value = copyOwnData(value, label, allowDeferred ? DEFERRED : undefined);
+  if (value === DEFERRED && allowDeferred) return;
+  const fail = () => {
+    throw new Error(`${label} must match ABI ${type.format("sighash")}`);
+  };
+  if (type.baseType === "array") {
+    if (
+      !Array.isArray(value) ||
+      (type.arrayLength !== -1 && value.length !== type.arrayLength)
+    )
+      return fail();
+    value.forEach((v, i) =>
+      validateAbiValue(type.arrayChildren!, v, `${label}[${i}]`, allowDeferred),
+    );
+    return;
+  }
+  if (type.baseType === "tuple") {
+    const components = type.components!;
+    if (Array.isArray(value)) {
+      if (value.length !== components.length) return fail();
+      components.forEach((c, i) =>
+        validateAbiValue(c, value[i], `${label}[${i}]`, allowDeferred),
+      );
+      return;
+    }
+    if (!value || typeof value !== "object") return fail();
+    const names = components.map((c) => c.name);
+    if (
+      names.some((n) => !n) ||
+      new Set(names).size !== names.length ||
+      Object.keys(value).sort().join("\0") !== names.slice().sort().join("\0")
+    )
+      return fail();
+    components.forEach((c) =>
+      validateAbiValue(
+        c,
+        (value as Record<string, unknown>)[c.name],
+        `${label}.${c.name}`,
+        allowDeferred,
+      ),
+    );
+    return;
+  }
+  if (type.type === "bool") {
+    if (typeof value !== "boolean") fail();
+    return;
+  }
+  const integer = /^(u?int)([0-9]+)$/.exec(type.type);
+  if (integer) {
+    if (
+      !(typeof value === "number" && Number.isSafeInteger(value)) &&
+      !(typeof value === "string" && /^(0|-?[1-9][0-9]*)$/.test(value))
+    )
+      return fail();
+    const bits = BigInt(integer[2]),
+      signed = integer[1] === "int",
+      n = BigInt(value as string | number);
+    if (
+      n < (signed ? -(1n << (bits - 1n)) : 0n) ||
+      n > (signed ? (1n << (bits - 1n)) - 1n : (1n << bits) - 1n)
+    )
+      fail();
+    return;
+  }
+  if (type.type === "address") {
+    if (typeof value !== "string" || !isAddress(value)) fail();
+    return;
+  }
+  if (type.type === "string") {
+    if (typeof value !== "string") fail();
+    return;
+  }
+  const bytes = /^bytes([0-9]*)$/.exec(type.type);
+  if (bytes) {
+    if (
+      typeof value !== "string" ||
+      !/^0x(?:[a-fA-F0-9]{2})*$/.test(value) ||
+      (bytes[1] && value.length !== 2 + 2 * Number(bytes[1]))
+    )
+      fail();
+    return;
+  }
+  throw new Error(`Unsupported ABI type ${type.type}`);
+}
+function boundary(value: unknown, allowDeferred: boolean): unknown {
+  return copyOwnData(value, "ABI input", allowDeferred ? DEFERRED : undefined);
+}
+export function validateAbiArguments(
+  abi: InterfaceAbi,
+  method: string | null,
+  args: unknown,
+  options: { allowDeferred?: boolean } = {},
+): void {
+  const allow = options.allowDeferred === true;
+  const input = boundary(args, allow),
+    iface = new Interface(abi);
+  const fragment = method === null ? iface.deploy : iface.getFunction(method);
+  if (!fragment) throw new Error(`Unknown ABI method ${method}`);
+  if (input === DEFERRED)
+    throw new Error(
+      "Future state requires explicit ABI argument count and shape",
+    );
+  if (!Array.isArray(input) || input.length !== fragment.inputs.length)
+    throw new Error(
+      `ABI argument count mismatch for ${method ?? "constructor"}`,
+    );
+  fragment.inputs.forEach((type, i) =>
+    validateAbiValue(
+      type,
+      input[i],
+      `${method ?? "constructor"} args[${i}]`,
+      allow,
+    ),
+  );
+}
+export function validateTransactionValue(
+  value: unknown,
+  allowDeferred = false,
+): void {
+  validateAbiValue(
+    ParamType.from("uint256"),
+    value,
+    "transaction value",
+    allowDeferred,
+  );
+}
+
+export function validateAbiResult(
+  abi: InterfaceAbi,
+  method: string,
+  raw: unknown,
+  allowDeferred = false,
+): void {
+  const value = boundary(raw, allowDeferred),
+    fragment = new Interface(abi).getFunction(method);
+  if (!fragment) throw new Error("Unknown ABI method");
+  if (fragment.outputs.length === 1)
+    validateAbiValue(
+      fragment.outputs[0],
+      value,
+      "expected result",
+      allowDeferred,
+    );
+  else {
+    if (!Array.isArray(value) || value.length !== fragment.outputs.length)
+      throw new Error("ABI result count mismatch");
+    fragment.outputs.forEach((p, i) =>
+      validateAbiValue(p, value[i], `expected result[${i}]`, allowDeferred),
+    );
+  }
+}
+function comparable(type: ParamType, value: any): unknown {
+  if (type.baseType === "array")
+    return value.map((v: unknown) => comparable(type.arrayChildren!, v));
+  if (type.baseType === "tuple")
+    return type.components!.map((p, i) =>
+      comparable(p, Array.isArray(value) ? value[i] : value[p.name]),
+    );
+  if (/^(u?int)[0-9]+$/.test(type.type)) return BigInt(value).toString();
+  if (type.type === "address") return getAddress(value).toLowerCase();
+  if (type.type.startsWith("bytes")) return value.toLowerCase();
+  return value;
+}
+export function stringifyRuntimeValue(value: unknown): string {
+  const data = normalizeRuntimeValue(value);
+  return typeof data === "string" ? data : JSON.stringify(data);
+}
+export function compareAbiResults(
+  abi: InterfaceAbi,
+  method: string,
+  actual: unknown,
+  expected: unknown,
+): { actual: string; expected: string } {
+  const normalized = normalizeRuntimeValue(actual);
+  validateAbiResult(abi, method, normalized);
+  validateAbiResult(abi, method, expected);
+  const outputs = new Interface(abi).getFunction(method)!.outputs;
+  const encode = (v: any) =>
+    stringifyRuntimeValue(
+      outputs.length === 1
+        ? comparable(outputs[0], v)
+        : outputs.map((p, i) => comparable(p, v[i])),
+    );
+  return { actual: encode(normalized), expected: encode(expected) };
+}

package/runtime/delivery/aggregate-bootstrap.ts

@@ -0,0 +1,29 @@
+/** Private fixed-worker bootstrap. Never accepts caller config overrides. */
+import path from 'node:path';
+import type { HardhatConfig } from 'hardhat/types';
+let fork:Readonly<{network:string;chainId:number;url:string;blockNumber:number}>|undefined;
+const policies=new WeakMap<object,HardhatConfig['networks']['hardhat']>();
+export function establishOwnedFork(input:NonNullable<typeof fork>):void {
+  if(fork||require.main?.filename!==path.join(__dirname,'aggregate-worker.js')||!process.send||!process.connected)
+    throw new Error('Owned worker fork bootstrap required');
+  const url=new URL(input.url);
+  if(url.protocol!=='http:'||url.hostname!=='127.0.0.1'||!/^\/[a-f0-9-]{36}$/.test(url.pathname)||url.username||url.password||url.search||url.hash)
+    throw new Error('Owned source proxy required');
+  fork=Object.freeze({...input});
+}
+export function registerOwnedFork(extendConfig:typeof import('hardhat/config').extendConfig):void {
+  if(!fork)return;
+  extendConfig(config=>{
+    if(config.networks[fork!.network]?.chainId!==fork!.chainId)throw new Error('Owned fork target chain mismatch');
+    policies.set(config,config.networks.hardhat);
+    config.networks.hardhat={...config.networks.hardhat,chainId:fork!.chainId,
+      forking:{enabled:true,url:fork!.url,blockNumber:fork!.blockNumber,httpHeaders:{}}};
+  });
+}
+export function originalRunnerPolicy(config:HardhatConfig):HardhatConfig['networks']['hardhat'] {
+  return policies.get(config)??config.networks.hardhat;
+}
+
+export function assertOwnedTargetWorker():void {
+  if(!fork||require.main?.filename!==path.join(__dirname,'aggregate-worker.js')||!process.send||!process.connected)throw new Error('Owned target worker required');
+}

package/runtime/delivery/aggregate-channel.ts

@@ -0,0 +1,85 @@
+/** Finite private protocol. A nonce correlates an actual child; it is not process attestation. */
+import {productionChildEnvironment} from './production-environment';
+import {fork,type ChildProcess} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {strictData} from './data';
+import {exactObject} from '../workflow/lib/canonicalData';
+export class OwnedWorkerFailure extends Error {}
+export type Command='stage'|'check'|'bind'|'close'|'abort';
+export interface WorkerMessage {version:1;session:string;epoch:string;target:string;id:number;command:Command;data:unknown}
+export function parseWorkerMessage(raw:unknown):WorkerMessage {
+  const x=exactObject(strictData(raw),['version','session','epoch','target','id','command','data'],'worker message');
+  if(x.version!==1||typeof x.session!=='string'||typeof x.epoch!=='string'||typeof x.target!=='string'||!Number.isSafeInteger(x.id)||Number(x.id)<1||!['stage','check','bind','close','abort'].includes(String(x.command)))throw new OwnedWorkerFailure('Invalid worker protocol');
+  return x as unknown as WorkerMessage;
+}
+export class OwnedWorker {
+  readonly #child:ChildProcess;
+  readonly epoch=randomUUID();
+  #id=0;#state:'new'|'staging'|'staged'|'checked'|'bound'|'closing'|'closed'|'failed'='new';
+  #pending?:{message:WorkerMessage;resolve:(v:any)=>void;reject:(e:Error)=>void;timer:NodeJS.Timeout};
+  #failure?:Error;
+  readonly #exit:Promise<void>;
+  #exited=false;
+  constructor(readonly root:string,readonly session:string,readonly target:string,readonly role:'source'|'target',readonly failAggregate:(error:Error)=>void){
+    const env=productionChildEnvironment(process.env);
+    for(const key of ['GATE_DELIVERY_CONTEXT','GATE_WORKFLOW_TARGET','MANIFEST_DEFAULT_DIR','HARDHAT_NETWORK','GATE_FORK_PROXY_HANDSHAKE','GATE_WORKFLOW_SIMULATION_FORK','GATE_WORKFLOW_SIMULATION_SOURCE_RPC'])delete env[key];
+    Object.assign(env,{HARDHAT_CONFIG:path.join(root,'hardhat.config.ts'),HARDHAT_TSCONFIG:path.join(root,'tsconfig.json'),HARDHAT_DISABLE_TELEMETRY_PROMPT:'true'});
+    this.#child=fork(path.join(__dirname,'aggregate-worker.js'),[],{cwd:root,env,execArgv:[],stdio:['ignore','ignore','ignore','ipc'],serialization:'json'});
+    this.#child.on('message',raw=>{
+      try{
+        const reply=parseWorkerMessage(raw),pending=this.#pending;
+        if(!pending||reply.session!==session||reply.target!==target||reply.epoch!==this.epoch||reply.id!==pending.message.id||reply.command!==pending.message.command)throw new OwnedWorkerFailure('Unexpected worker protocol reply');
+        const value=exactObject(reply.data,['ok','value'],'worker reply');
+        if(value.ok!==true){
+          const details=exactObject(value.value,['phase'],'worker failure');
+          const phases=['protocol','project-loader','source-open','source-configuration','fork-setup','target-configuration','compile','planning','staged-reread','barrier','configuration-seal','binding'];
+          if(!phases.includes(String(details.phase)))throw new Error('Invalid worker failure');
+          this.fail(new OwnedWorkerFailure('Owned worker failed during '+details.phase));return;
+        }
+        clearTimeout(pending.timer);this.#pending=undefined;pending.resolve(value.value);
+      }catch{this.fail(new OwnedWorkerFailure('Owned worker failed or sent an invalid reply'));}
+    });
+    this.#child.on('error',()=>this.fail(new OwnedWorkerFailure('Owned worker process failed')));
+    this.#child.on('disconnect',()=>{if(!['closing','closed','failed'].includes(this.#state))this.fail(new OwnedWorkerFailure('Unexpected worker disconnect'));});
+    this.#exit=new Promise(resolve=>this.#child.once('exit',(code,signal)=>{
+      this.#exited=true;
+      if(this.#state!=='closing'||code!==0||signal!==null)this.fail(new OwnedWorkerFailure('Unexpected worker exit'));
+      else this.#state='closed';
+      resolve();
+    }));
+  }
+  get pid():number|undefined{return this.#child.pid;}
+  assertLive():void {if(this.#failure||this.#exited||!this.#child.connected)throw this.#failure??new OwnedWorkerFailure('Worker is not live');}
+  private fail(error:Error):void {
+    if(this.#failure)return;this.#failure=error;this.#state='failed';
+    if(this.#pending){clearTimeout(this.#pending.timer);this.#pending.reject(error);this.#pending=undefined;}
+    this.failAggregate(error);
+  }
+  async request(command:Command,data:unknown=null):Promise<any>{
+    this.assertLive();
+    const allowed=command==='stage'?this.#state==='new':command==='check'?this.#state==='staged':command==='bind'?this.role==='target'&&this.#state==='checked':command==='close'?(this.role==='source'?this.#state==='checked':this.#state==='bound'):false;
+    if(!allowed||this.#pending){const error=new OwnedWorkerFailure('Worker protocol order violation');this.fail(error);throw error;}
+    const next=command==='stage'?'staged':command==='check'?'checked':command==='bind'?'bound':'closed';
+    this.#state=command==='stage'?'staging':command==='close'?'closing':this.#state;
+    const message:WorkerMessage={version:1,session:this.session,epoch:this.epoch,target:this.target,id:++this.#id,command,data:strictData(data)};
+    const result=await new Promise<any>((resolve,reject)=>{
+      const timer=setTimeout(()=>this.fail(new OwnedWorkerFailure('Owned worker request timed out')),180000);
+      this.#pending={message,resolve,reject,timer};
+      this.#child.send(message,error=>{if(error)this.fail(new OwnedWorkerFailure('Owned worker channel failed'));});
+    });
+    if(command==='close'){
+      await this.reap(false);if(this.#failure)throw this.#failure;
+    }else{this.assertLive();this.#state=next as 'staged'|'checked'|'bound'|'closed';}
+    return result;
+  }
+  async reap(abort=true):Promise<void>{
+    if(this.#exited)return;
+    if(abort){this.#state='failed';if(this.#pending){clearTimeout(this.#pending.timer);this.#pending.reject(new OwnedWorkerFailure('Aggregate aborted'));this.#pending=undefined;}this.#child.kill('SIGTERM');}
+    let timer:NodeJS.Timeout|undefined;
+    try{await Promise.race([this.#exit,new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new OwnedWorkerFailure('Worker did not exit')),5000);})]);}
+    catch{this.#child.kill('SIGKILL');await Promise.race([this.#exit,new Promise<never>((_,reject)=>{timer=setTimeout(()=>reject(new OwnedWorkerFailure('Worker could not be reaped')),5000);})]);}
+    finally{if(timer)clearTimeout(timer);}
+    if(!this.#exited)throw new OwnedWorkerFailure('Worker exit unproven');
+  }
+}