gate-evm-tools 1.0.28 → 1.2.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/hardhatAdapters.ts

@@ -53,6 +53,7 @@ export function withTemplateArtifactPaths(config: HardhatUserConfig, argv: strin
 export function registerWorkflowDependencyCompiler(subtask: typeof import("hardhat/config").subtask, taskName: string): void {
   subtask(taskName).setAction(async (args, _hre, runSuper) => {
     const sourceNames: string[] = await runSuper(args);
-    return [...new Set([...sourceNames, "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol"])];
+    return [...new Set([...sourceNames, "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol",
+      ...((_hre.network.config as {zksync?:boolean}).zksync === true ? [] : ["@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol"])])];
   });
 }

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,31 @@
+/** 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);
+    // Only the explicitly selected simulation operator is impersonated later. Avoid
+    // hydrating Hardhat's unrelated default wallets from the historical source RPC.
+    config.networks.hardhat={...config.networks.hardhat,chainId:fork!.chainId,accounts:[],
+      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,88 @@
+/** 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';
+import {workerFailures} from './aggregate-diagnostics';
+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 hasReason=Object.hasOwn(value.value as object,'reason');
+          const details=exactObject(value.value,['phase',...(hasReason?['reason']:[])],'worker failure');
+          const phases=['protocol','project-loader','source-open','source-configuration','fork-setup','fork-verify','fork-signer','target-configuration','compile','planning','existing-code-artifacts','staged-reread','barrier','source-recheck','source-seal','plan-recheck','compiler-recheck','configuration-seal','binding'];
+          if(!phases.includes(String(details.phase)))throw new Error('Invalid worker failure');
+          if(hasReason&&(typeof details.reason!=='string'||!Object.hasOwn(workerFailures,details.reason)))throw new Error('Invalid worker failure reason');
+          this.fail(new OwnedWorkerFailure('Owned worker failed during '+details.phase+' ('+role+')'+(hasReason?': '+workerFailures[details.reason as string]:'')));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');
+  }
+}

package/runtime/delivery/aggregate-diagnostics.ts

@@ -0,0 +1,63 @@
+/** Finite diagnostics only: provider errors can contain RPC credentials and payloads. */
+export const sourceRpcFailures = {
+  'source-history-unavailable': 'Source RPC cannot read historical state at the pinned block; configure an RPC with historical-state access without changing the pinned block.',
+  'source-access-denied': 'Source RPC denied access; check the configured RPC access without exposing credentials.',
+  'source-rate-limited': 'Source RPC rate limit exceeded; use an RPC with sufficient read capacity for the pinned fork.',
+  'source-transport-failed': 'Source RPC transport failed; check connectivity and the RPC response timeout for the pinned fork.',
+  'source-request-failed': 'Source RPC request failed.',
+} as const;
+export type SourceRpcFailure = keyof typeof sourceRpcFailures;
+
+const invariantMessages = [
+  'Source read failed',
+  'Planning source/input/runtime identity drift',
+  'Planning pinned fork/source identity mismatch',
+  'Captured fork interval drift',
+  'Captured fork interval closed or bound',
+  'Fork audit provider mutation/identity violation',
+  'Fork audit baseline/provider identity changed',
+  'Pending or unobservable fork transactions',
+  'Fork audit changed while enumerating',
+  'Audit transaction lookup mismatch',
+  'Custom input closure drift at collection completion',
+  'Compiler contribution drift',
+  'Compiler effective config drift',
+  'Compiler package payload drift',
+  'Compiler package resolution drift',
+  'Compiler npm lock drift',
+  'Delivery configuration/runtime drift or mismatch',
+  'Source provider changed',
+  'Source pinned block drift',
+] as const;
+export const workerFailures: Readonly<Record<string, string>> = Object.freeze({
+  ...sourceRpcFailures,
+  ...Object.fromEntries(invariantMessages.map((message, index) => ['invariant-'+index,message])),
+  'compiler-input-drift': 'Compiler input bytes changed during qualification.',
+});
+
+/** Only exact reviewed messages or a fixed category may cross the worker channel. */
+export function workerFailureReason(error: unknown): string | undefined {
+  const source = workerSourceFailure(error);
+  if (source) return source;
+  const message = error instanceof Error ? error.message : '';
+  const index = invariantMessages.findIndex(known => known === message);
+  if (index >= 0) return 'invariant-'+index;
+  if (message.startsWith('Compiler input drift: ')) return 'compiler-input-drift';
+  return undefined;
+}
+
+export function sourceRpcFailure(error: unknown): SourceRpcFailure {
+  const known = workerSourceFailure(error);
+  if (known) return known;
+  const message = error instanceof Error ? error.message : '';
+  if (/archive|historical\s+state|missing trie node|state.*(?:unavailable|not available)/i.test(message)) return 'source-history-unavailable';
+  if (/too many requests|rate.?limit/i.test(message) || (error as {code?:unknown} | null)?.code === -32005) return 'source-rate-limited';
+  if (/\b(?:401|403)\b|unauthorized|forbidden|authentication|invalid api key/i.test(message)) return 'source-access-denied';
+  if (/socket|ECONNRESET|ECONNREFUSED|UND_ERR_|timed? ?out|timeout|fetch failed/i.test(message)) return 'source-transport-failed';
+  return 'source-request-failed';
+}
+
+export function workerSourceFailure(error: unknown): SourceRpcFailure | undefined {
+  const message = error instanceof Error ? error.message : '';
+  return (Object.keys(sourceRpcFailures) as SourceRpcFailure[]).find(reason => message.includes(sourceRpcFailures[reason]));
+}

package/runtime/delivery/aggregate-inputs.ts

@@ -0,0 +1,39 @@
+/** Actual multi-root codec projections; selected task order belongs to the canonical codec. */
+import {readDeliverySource,readOwnedDeliverySource} from './source';
+import type {DeliveryRequest} from './protocol';
+import {canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
+export function openAggregateSources(input:{workspaceRoot:string;projectRoot:string;requests:readonly DeliveryRequest[]}) {
+  const read=()=>{
+    const sources=input.requests.map(request=>readOwnedDeliverySource({workspaceRoot:input.workspaceRoot,projectRoot:input.projectRoot,request}));
+    const groups=new Map<string,typeof sources>();
+    for(const source of sources){const key=source.request.sourceRef.path+'\0'+source.request.sourceRef.taskId;const group=groups.get(key)??[];group.push(source);groups.set(key,group);}
+    const definitions=[];const tasks=new Map<string,unknown>(),lanes=new Map<string,unknown>();
+    let identity:string|undefined;
+    for(const group of groups.values()){
+      const first=group[0];
+      const projection=readDeliverySource({workspaceRoot:input.workspaceRoot,projectRoot:input.projectRoot,request:first.request,
+        sourceRoots:group.map(source=>source.invocation.task.planKey)});
+      if(group.some(source=>source.observation.sha256!==projection.observation.sha256))throw new Error('Handoff changed during multi-root source capture');
+      const definition=projection.sourceDefinition;
+      const currentIdentity=canonicalJson([definition.contract,definition.schema,definition.taskId,definition.flow??null]);
+      if(identity!==undefined&&identity!==currentIdentity)throw new Error('Conflicting aggregate handoff identity');
+      identity=currentIdentity;
+      for(const [key,lane] of Object.entries(definition.lanes)){
+        if(lanes.has(key)&&canonicalJson(lanes.get(key))!==canonicalJson(lane))throw new Error('Conflicting aggregate lane definition');
+        lanes.set(key,lane);
+      }
+      // Detect conflicting duplicates across documents without sorting/reconstructing any codec task list.
+      for(const task of projection.sourceDefinition.tasks){const key=first.request.sourceRef.taskId+'\0'+task.planKey;
+        if(tasks.has(key)&&canonicalJson(tasks.get(key))!==canonicalJson(task))throw new Error('Conflicting aggregate source definition');tasks.set(key,task);
+      }
+      definitions.push({path:first.request.sourceRef.path,definition:projection.sourceDefinition});
+    }
+    return {sources,definitions:deepFreeze(definitions)};
+  };
+  const initial=read();
+  return Object.freeze({...initial,sourceDefinitionHash:semanticHash(initial.definitions),assertUnchanged(){
+    const current=read();
+    if(canonicalJson(current.definitions)!==canonicalJson(initial.definitions))throw new Error('Aggregate source definition drift');
+    for(let i=0;i<current.sources.length;i++)if(canonicalJson(current.sources[i].invocation.task.scope)!==canonicalJson(initial.sources[i].invocation.task.scope))throw new Error('Aggregate invocation drift');
+  }});
+}

package/runtime/delivery/aggregate-source.ts

@@ -0,0 +1,57 @@
+/** Package-owned EVM source read capability, using the workflow's reviewed allowlist. */
+import http from 'node:http';
+import {randomUUID} from 'node:crypto';
+import {isAllowedSourceRpcMethod} from '../workflow/lib/sourceRpcPolicy';
+import type {DeliveryRequest} from './protocol';
+import type {HardhatRuntimeEnvironment} from 'hardhat/types';
+import {sourceRpcFailure,sourceRpcFailures} from './aggregate-diagnostics';
+export interface SourceHandshake {
+  version:1;session:string;epoch:string;target:string;proxyUrl:string;
+  snapshot:{version:1;sourceNetwork:string;chainId:number;blockNumber:number;blockHash:string;runner:{kind:'hardhat';version:'2.26.3'}};
+}
+export async function openOwnedSource(hre:HardhatRuntimeEnvironment,request:DeliveryRequest,session:string,epoch:string):Promise<{
+  handshake:SourceHandshake;check():Promise<void>;close():Promise<void>;
+}> {
+  if(hre.network.name!==request.network)throw new Error('Source HRE network mismatch');
+  const provider=hre.network.provider;
+  const rpc=async(method:string,params:unknown[]=[])=>{
+    try{return await provider.request({method,params});}
+    catch(cause){throw new Error(sourceRpcFailures[sourceRpcFailure(cause)]);}
+  };
+  const chainId=Number(BigInt(await rpc('eth_chainId') as string));
+  if(!Number.isSafeInteger(chainId)||chainId!==hre.network.config.chainId)throw new Error('Source chain identity mismatch');
+  const tag=request.fork?'0x'+request.fork.blockNumber.toString(16):'latest';
+  const block=await rpc('eth_getBlockByNumber',[tag,false]) as any;
+  if(!block||!/^0x[a-fA-F0-9]{64}$/.test(block.hash)||!/^0x[\da-f]+$/i.test(block.number))throw new Error('Source pinned block unavailable');
+  const blockNumber=Number(BigInt(block.number)),blockHash=block.hash.toLowerCase();
+  if(request.fork&&(request.fork.blockNumber!==blockNumber||request.fork.blockHash.toLowerCase()!==blockHash))throw new Error('Source pinned block mismatch');
+  const token=randomUUID(),endpoint='/'+token;
+  const reply=(res:http.ServerResponse,status:number,value:unknown)=>{const body=JSON.stringify(value);res.writeHead(status,{'content-type':'application/json','content-length':Buffer.byteLength(body)});res.end(body);};
+  const forward=async(raw:any)=>{
+    const error=(code:number,message:string)=>({jsonrpc:'2.0',id:raw?.id??null,error:{code,message}});
+    if(!raw||typeof raw!=='object'||Array.isArray(raw)||raw.jsonrpc!=='2.0'||typeof raw.method!=='string'||(raw.params!==undefined&&!Array.isArray(raw.params)))return error(-32600,'Invalid JSON-RPC request');
+    if(!isAllowedSourceRpcMethod(raw.method))return error(-32601,'Source RPC method is not allowed');
+    try{return {jsonrpc:'2.0',id:raw.id??null,result:await rpc(raw.method,raw.params??[])};}catch(cause){return error(-32000,sourceRpcFailures[sourceRpcFailure(cause)]);}
+  };
+  const server=http.createServer(async(req,res)=>{
+    if(req.method!=='POST'||req.url!==endpoint){reply(res,404,{error:'Unknown JSON-RPC endpoint'});return;}
+    try{
+      const chunks:Buffer[]=[];let size=0;
+      for await(const chunk of req){size+=chunk.length;if(size>10*1024*1024)throw new Error();chunks.push(Buffer.from(chunk));}
+      const raw=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      reply(res,200,Array.isArray(raw)?await Promise.all(raw.map(forward)):await forward(raw));
+    }catch{reply(res,400,{error:'Invalid JSON-RPC payload'});}
+  });
+  await new Promise<void>((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  const address=server.address();if(!address||typeof address==='string')throw new Error('Source proxy did not bind');
+  return {
+    handshake:{version:1,session,epoch,target:request.network,proxyUrl:`http://127.0.0.1:${address.port}${endpoint}`,
+      snapshot:{version:1,sourceNetwork:request.network,chainId,blockNumber,blockHash,runner:{kind:'hardhat',version:'2.26.3'}}},
+    async check(){
+      if(hre.network.provider!==provider||hre.network.name!==request.network)throw new Error('Source provider changed');
+      const [chain,current]=await Promise.all([rpc('eth_chainId'),rpc('eth_getBlockByNumber',['0x'+blockNumber.toString(16),false])]) as any[];
+      if(Number(BigInt(chain))!==chainId||current?.hash?.toLowerCase()!==blockHash||Number(BigInt(current.number))!==blockNumber)throw new Error('Source pinned block drift');
+    },
+    close:()=>new Promise<void>((resolve,reject)=>{server.close(error=>error?reject(error):resolve());server.closeAllConnections();}),
+  };
+}