gate-evm-tools 1.0.28 → 1.0.31

package/docs/delivery-safe.md

@@ -0,0 +1,72 @@
+# Official Safe 1.4.1 delivery
+
+The supported adapter is `safe-1.4.1-call-only/v1`: the published ordinary Safe
+singleton and SafeProxy, with either a single CALL or DELEGATECALL to the official
+MultiSendCallOnly containing only CALL entries. SafeL2, modules, ordinary MultiSend,
+arbitrary delegatecall and nested Safe execution are unsupported. Reviewed runtime
+hashes are code-owned; caller-provided hashes cannot add implementations.
+
+The developer delivers this optional target policy in the existing `config.yaml`.
+It is included in the captured release inputs, with no production business override:
+
+```yaml
+production:
+  environment: prod
+  finality: { confirmations: 1 }
+  openzeppelin: { manifestDir: .openzeppelin }
+  safe:
+    adapter: safe-1.4.1-call-only/v1
+    multiSendCallOnly: '0x<deployed official MultiSendCallOnly address>'
+    safeTxGas: '500000'
+    submitterPolicy: { kind: any }
+```
+
+Safe address is the current original plan executor. After final plan preparation,
+the host retains READY, exits the project simulation, and starts a separate static
+worker. Only that worker receives the observation provider and durable store. It
+checks the actual proxy/singleton/batch identities and nonce at one canonical block
+and freezes the current contiguous external segment, complete Safe envelope,
+transaction IDs, EIP-712 hash, explicit finality and zero-refund policy. It never
+allocates a future segment's nonce. Existing published bindings are immutable;
+consumed nonces require reconciliation of the original hash, not rebasing.
+
+Pure renderers perform zero provider, signer or broadcast calls. JSON and Markdown
+contain the full plan and frozen Safe payload, with signatures left for external
+collection. An unprepared current Safe segment reports `preparation-required` and
+still exports the complete ordinary plan. Later segments await preparation when
+executable. The existing host export boundary separately revalidates completed
+progress using readonly RPC; this is distinct from pure rendering.
+
+Reconciliation requires an explicit original outer transaction hash. The collector
+strictly checks all execTransaction fields, ABI canonicality, packed CALL lengths,
+values and complete range coverage. Signatures may vary. The outer sender can be a
+distinct relayer under the sealed any-relayer policy. Base gas/gas price are zero,
+gas token/refund receiver are zero addresses, and actual payment must be zero.
+Exactly the expected SafeTxHash ExecutionSuccess, canonical inclusion and finality
+are required. ExecutionFailure never advances, even when receipt status is one.
+One verified Safe batch is committed atomically to its exact inner indices. The
+EOA duplicate-hash rule is unchanged, and only a complete finalized prefix allows
+the original operator continuation. Successful calls do not replace business
+assertions or production finalization.
+
+The finite evidence collector supports Geth 1.15.11 prestateTracer plus its default
+opcode trace. It requests its own fixed options for the same hash, checks full
+address-keyed transaction-time code and proxy slot zero, binds proxy pc 28 SLOAD /
+pc 94 DELEGATECALL and singleton/batch call frames, and tracks CALL versus
+DELEGATECALL storage context. Missing, malformed, incomplete, oversized or
+unavailable evidence is refused. No VERSION/block-end identity fallback exists.
+Type-4 authorization transactions and delegation-designator assets are unsupported.
+The client's declared version is a compatibility gate, not remote binary attestation;
+ordinary configured-RPC trust applies. The host limits both options and response
+size and retains its request/scope/effect guards.
+
+Local acceptance uses the already prepared official native Geth 1.15.11 source
+build, dev mode with Prague enabled, and vendored official Safe artifacts. Set
+`GATE_SAFE_GETH_ACCEPTANCE=1` for `node --test test/delivery-safe-geth.test.mjs` after
+starting the pinned isolated fixture at 127.0.0.1:19545. The fixture retains its
+own deployment state under `/tmp/gate-r5-20261023-implementation`; it never clears
+historic accepted chains. The gated suite covers real owners/signatures, value,
+relayers, batch failures, extra calls, same-block fake switch/restore, later-index
+execution, reentry/slot-zero refusal, malformed provider evidence and original
+operator continuation. Local confirmations/finalized tags do not prove production
+consensus finality. R6 owns the final frozen-version packaged lifecycle.

package/docs/delivery-setup.md

@@ -0,0 +1,146 @@
+# Core 项目的按需部署接入
+
+`gate-delivery` 只接受已完成生成的 `gateflow-evm-core@1` / `profile: core` 项目。
+它不迁移 full/旧模板，不复制 workflow 源码，也不管理项目的 RPC 网络目录。
+正常的 `compile`、`test`、`typecheck`、`clean` 在接入前后均不需要 `config.yaml`、钱包或外部 RPC。
+
+## 本地接入
+
+创建 JSON 选项文件，例如：
+
+```json
+{
+  "workspaceRoot": "/absolute/workspace",
+  "projectRoot": "contracts",
+  "toolPackage": "/absolute/build/gate-evm-tools-1.0.29.tgz",
+  "targets": [
+    {
+      "network": "sepolia",
+      "environment": "dev",
+      "finality": { "confirmations": 1 },
+      "create2": {
+        "scheme": "evm",
+        "factory": "0x1111111111111111111111111111111111111111"
+      }
+    }
+  ]
+}
+```
+
+工厂地址只是格式示例，应填写项目实际设施地址。`create2`、
+`uups: { placeholderImplementation }` 和 `multicall: { controlledMulticall }`
+都可省略；call/view/check 类项目无需部署设施。提供设施配置时，setup 和 `loadDeliveryTarget` 均校验其地址为非零 EVM 地址。
+`loadDeliveryTarget` 保留 YAML 中的额外人工字段，不采用 setup 选项的严格字段白名单。具体操作需要哪些设施由执行输入验证决定。
+
+```sh
+gate-delivery inspect --options delivery-options.json
+gate-delivery setup --options delivery-options.json
+```
+
+`inspect` 是只读诊断。`setup` 完成冲突预检后，仅补充缺失的选中目标配置、
+缺失的 `contractInfo.json`（内容为 `{}`）和所需的开发依赖声明。
+已有 YAML 注释、其他目标、自定义字段、业务代码、注册表、Git 元数据和生成器 marker 均保留。
+已有值与明确请求冲突、路径包含 symlink、模板不受支持时，在写入前拒绝。
+
+依赖未就绪时返回 `dependencies_pending`，CLI 退出码为 `2`；不会安装依赖或添加失败的插件 import。
+用户在目标项目显式安装依赖后再次运行 setup，才会把
+`import "gate-evm-tools/delivery-hardhat";` 放在其他 import 之前。
+重复 setup 不改写已满足要求的文件。退出码 `0` / `ready` 只表示接入完成，
+不表示 source 已验证、RPC 已连接、部署获准或合约已部署。`setup_pending` 是 inspect 发现仍有配置修改待完成。
+
+当前未发布的 API 应使用显式本地构建 tarball：在 GateTool 仓库运行 `npm run build` 和
+`npm pack --pack-destination /absolute/build`，并把 tarball 绝对路径写入 `toolPackage`。
+该字段可省略，但仅有 `gate-evm-tools@1.0.29` 版本号不能证明 API 已存在；诊断会检查本地 exports。
+如 package.json 已声明另一来源，先显式调整该依赖，不会静默覆盖人工声明。
+
+验证的 core 工具链是 Hardhat `2.26.3`、ethers `6.15.0`、hardhat-ethers `3.1.0`、
+TypeScript `5.9.3`、ts-node `10.9.2`。按需声明 OZ hardhat-upgrades `3.9.1`、
+upgrades-core `1.44.2`、contracts `5.4.0`；业务 Solidity 源码引用 contracts-upgradeable 时才声明 `5.4.0`。
+诊断检查实际本地包、delivery exports 和本地 npm 依赖树，不把祖先目录的依赖当作本项目就绪。
+不添加 toolbox、zkSync、Foundry、patch-package 或 postinstall 补丁。
+
+网络仍只定义在项目 `hardhat.config.ts`。接入读取静态 const/default-export 对象中的选中网络，
+支持字面 URL、`process.env.NAME`、`||` 和 `??`；动态计算的选中网络需要人工改为可验证的静态定义。业务依赖扫描遵循静态 `paths.sources`（默认 `contracts`），且只读取项目内目录。
+诊断只输出 network、chainId 和 rpcConfigured，不输出解析后的 RPC URL。
+可通过项目生成器或手工增加网络，无需发布 GateTool。
+
+## 公共 API
+
+- `gate-evm-tools/delivery-setup`：`inspectDeliveryProject(options)`、`setupDeliveryProject(options)`、
+  `readProjectNetworkSnapshots(root, aliases, env?)`、`loadDeliveryTarget(root, network, environment?)`、
+  `configureDeliveryEnvironment({ root, env?, argv? })`。
+- `gate-evm-tools/delivery-protocol`：`parseDeliveryRequest(input)`、
+  `validateDeliveryRpc(input, selectedProjectSnapshot, loadProvider)` 及请求类型。
+- `gate-evm-tools/delivery-hardhat`：项目配置的薄插件入口，带 Hardhat ethers/upgrades 类型扩展。
+- `gate-evm-tools/delivery-policy`：不加载 OZ 的共享 manifest 策略。
+
+`readProjectNetworkSnapshots` 提供给本地 provider 装配使用，包含解析后的 URL，
+不要把它写入交付文件或日志。`validateDeliveryRpc` 首先校验请求语法，之后才调用
+注入的 `loadProvider(snapshot)`；provider 的 `request({ method: "eth_chainId", params: [] })`
+必须返回与项目快照一致的真实 chain ID。RPC 失败或链 ID 不符直接拒绝，没有备用网络。
+
+## 显式 runtime 请求协议
+
+```json
+{
+  "version": 1,
+  "environment": "dev",
+  "purpose": "dev-execution",
+  "mode": "simulate",
+  "network": "sepolia",
+  "sourceRef": {
+    "path": "handoff/task-1/handoff.md",
+    "taskId": "task-1",
+    "planKey": "rollout",
+    "rev": 1
+  },
+  "devSigner": "0x2222222222222222222222222222222222222222"
+}
+```
+
+所有字段严格校验，不存在默认 execute。environment、purpose、mode 必须是字符串，不接受数组或对象的隐式转换。
+sourceRef.path 必须是 workspace-relative POSIX 路径，releaseRef.path 必须是 project-relative POSIX 路径；
+ID、network alias 和路径禁止 traversal/prototype 名称。
+
+| purpose | environment | mode | 额外约束 |
+| --- | --- | --- | --- |
+| dev-execution | dev | simulate / execute / reconcile / verify | devSigner；禁止 operator |
+| prod-qualification | prod | simulate / verify | operator；simulate 必需 fork `{ blockNumber, blockHash, readOnly: true }`；verify 不带 fork/releaseRef，只读、不广播 |
+| prod-execution | prod | simulate / execute / export-calldata / reconcile / verify | operator；必需 releaseRef `{ path, releaseId, inputsHash }` |
+
+`inputsHash` 是 64 位小写 hex，不含 `0x`。fork blockNumber 是非负安全整数；只有 simulate 可带 fork。
+qualification verify 不需要伪造 fork 或 releaseRef，不接受 execute/export-calldata/reconcile；具体只读 verification orchestration 在后续阶段实现。
+所有 signer/operator 地址只是请求约束，不是授权证明。业务 owner 留在冻结 source 的业务参数中，
+不会从 devSigner/operator 推导，也不接受 `businessOwner` 或参数覆盖字段。
+不支持 `admin_release`、旧 SuperTask 字段、`mergeCommit`、`parameterOverrides`、`authorized: true`。
+
+这一步只定义语法、路由和 RPC 一致性验证；canonical source 文件内容核验、输入冻结、prod host 授权、
+执行/finalize/export CLI 在后续交付阶段实现。这里没有把新请求转译给旧 `workflow/run.ts`。
+
+## Manifest 与普通开发命令
+
+插件只有在显式设置 `GATE_DELIVERY_CONTEXT`（上述请求的 JSON）时读取选中目标。
+它在任何 OZ import 之前设置 `MANIFEST_DEFAULT_DIR` 和 `GATE_WORKFLOW_TARGET`；
+`prod` 必须使用 `.openzeppelin`，`dev` 必须使用隔离目录（默认 `.openzeppelin.dev`）。
+两种环境可以使用同一 chain ID。每个 runtime target 应使用全新子进程；继承的目录/目标冲突、
+不同的 Hardhat config/tsconfig、网络路由冲突或已提前加载 OZ 均拒绝。
+所有重复 CLI 参数和对应环境变量都会逐一核对，不能用 CLI 掩盖继承的冲突值。
+无显式 network selector 时读取项目的静态 `defaultNetwork`；插件还会在 HRE 初始化时核对实际
+`hre.network.name`、project root 和 configFile，拒绝 config extender 改写后的不一致。
+只有 simulate 可一致地选择本地 hardhat；该例外不会覆盖显式 selector 冲突或错误的默认网络。
+
+没有 delivery context 时不读取 YAML。插件启用 OZ 原生 storageLayout 和 canonical ERC1967Proxy
+依赖编译，不重写 compiler、optimizer、viaIR、artifact/cache 路径，也不读取钱包。
+旧 workflow 配置入口仅接受 local/development/production，拒绝 dev/prod；新协议通过独立 loader 只接受 dev/prod。
+共享 manifest/preparation 策略支持两套环境名称，但不会将新环境转换为旧 workflow 请求。
+
+真实本地验收：`npm run test:delivery:core`。测试需要相邻的 `EvmHardhatCli` checkout 已构建。该测试生成全新 core、安装本地 tarball、
+编译临时 UUPS 合约并验证 canonical prepare，确认重复 setup 稳定及删除 YAML 后普通命令正常；
+它不发布 npm 包，也不连接真实链。
+
+The read-only [`delivery-source` API](delivery-source.md) binds actual confined handoff tasks and canonical definitions before RPC validation. It is separate from setup, lifecycle persistence and host authorization.
+
+Owned multi-target input qualification is available through
+`gate-evm-tools/delivery-aggregate`; see [aggregate lifecycle and API](delivery-aggregate.md).
+
+Node 最低版本为 22.13.0（node:sqlite）；本次本地组合使用 Node 24.3.0 / npm 11.4.2。

package/docs/delivery-source.md

@@ -0,0 +1,67 @@
+# Actual handoff source binding
+
+`gate-evm-tools/delivery-source` is a read-only API for the new template delivery protocol. It reads the actual workspace handoff using the vendored canonical `gateflow-plan/v2` codec. It does not load HRE, a provider, a signer, or SmartFlowAI, and does not persist lifecycle state or grant execution authority.
+
+```ts
+import { readDeliverySource, validateDeliverySourceRpc } from 'gate-evm-tools/delivery-source';
+
+const source = readDeliverySource({
+  workspaceRoot: '/absolute/workspace',
+  projectRoot: 'contracts/vault', // workspace-relative; '.' is supported
+  sourceRoots: ['qualify-mainnet'], // upstream selection owned by caller policy
+  request, // DeliveryRequest from delivery-protocol
+});
+
+// If RPC validation is needed, this wrapper checks actual source first.
+const bound = await validateDeliverySourceRpc(options, selectedNetworkSnapshot, loadProvider);
+```
+
+`request.sourceRef.path` is workspace-relative. The reference identifies the **invocation task** using taskId, planKey and rev. The selected task's deployment projectRoot must exactly equal the configured workspace-relative projectRoot. Its environment, targetNetwork, allowedActions and exact releaseRef must match the request. The project must carry the supported completed core-template marker. A disabled or cancelled invocation is refused.
+
+Purpose is bound to task steps:
+
+| Purpose | Steps |
+| --- | --- |
+| dev-execution | deploy, check-code |
+| prod-qualification | deploy-test |
+| prod-execution | release-prepare, release-execute, release-verify |
+
+The Task 4 protocol still controls legal modes: dev reconcile is valid; qualification verify needs neither fork nor releaseRef; qualification simulate requires a pinned read-only fork. Source binding adds the actual task's allowedActions constraint. The release reference's path remains **project-relative**; source checking does not read or validate release package contents.
+
+Traversal, symlinks, hardlinks, nonregular files, missing/invalid handoffs, incorrect task identity/revision and route/ref mismatches fail before the wrapper invokes `loadProvider`. The file is opened without following a final symlink, and its identity and modification metadata are checked across the read. Parsing and projections use the same observed text. Subsequent lifecycle operations must revalidate against their freeze policy; this is not a filesystem lock.
+
+## Definition identity
+
+`sourceRoots` is separate from the invocation reference. The caller's trusted selection policy chooses upstream roots; the canonical projector includes their dependency closure and refuses any generated release-prepare/release-execute/release-verify root or dependency. Qualification tasks may be upstream. Selected deployment contracts belonging to another projectRoot are rejected, including those found only through dependencies. Generic source tasks remain available for dependency closure.
+
+The returned recursively immutable binding contains:
+
+- `request` and `invocation` (lane and complete parsed task).
+- `sourceDefinition`, `sourceDefinitionBytes` and SHA-256 `sourceDefinitionHash`.
+- For prod execution, `prodTaskGraph`, `prodTaskGraphBytes` and `prodTaskGraphHash`: all matching-release tasks for the selected project, across target networks, with full dependency closure and full releaseRef data.
+- `observation.path` and raw file SHA-256 for audit observation only.
+
+Definition bytes bind schema/taskId/flow, chosen roots, planKey/rev/lane, selected relative task order, used lane state/skill/step IDs, and objective/acceptance/dependsOn/step/scope/parameters/expectedArtifacts/allowedChanges. They exclude presentation, tools, progress and unrelated tasks. Thus ordinary progress updates change the observation hash without changing the upstream definition hash; an updated rev still binds when semantics return to their prior value.
+
+The later lifecycle must construct `inputsHash` from sourceDefinitionHash plus operation/parameter/artifact/script/config/executor bindings. It must keep the production task graph hash independent of inputsHash, because production task definitions contain releaseRef.inputsHash. **Neither the raw handoff hash nor prodTaskGraphHash is an inputsHash substitute.**
+
+The wrapper verifies source constraints; it does not replace host approval, root selection/freeze policy, revision adoption, progress ordering, release sealing, or release package checks. No runtime actor information is inserted into portable task definitions.
+
+`parseCanonicalPlan(text)` and `projectCanonicalDefinitions(text, { roots, mode: 'upstream' | 'full' })` also expose the canonical read-only surface. The projector reparses text rather than accepting a mutable parsed snapshot. Full mode permits complete independent prod projections. Canonical JSON uses sorted mapping keys and preserves prototype-named own metadata as data.
+
+## Vendor provenance and build
+
+The checked-in files are under `runtime/vendor/plan-codec`: a standalone CJS bundle, `.d.cts` declarations and provenance manifest. SmartFlowAI's `scripts/build-plan-codec.mjs` produces them from committed sources using its existing esbuild. The manifest records the actual commit, relevant source SHA-256s, schema/definition contract, version, builder version and artifact hashes. Its recorded source commit continues to be valid after unrelated SmartFlow commits; `--verify` uses that commit, not current HEAD.
+
+Maintainer refresh, from a SmartFlowAI checkout with the corresponding committed sources:
+
+```sh
+node scripts/build-plan-codec.mjs --out ../EvmGateTools/runtime/vendor/plan-codec
+node scripts/build-plan-codec.mjs --out ../EvmGateTools/runtime/vendor/plan-codec --verify
+```
+
+After reviewing the rebuilt artifact, explicitly update `runtime/delivery/codec-pin.ts` with its manifest SHA-256 and sourceCommit, and copy the canonical `definition-golden.json` and `evm-cases.json` into `test/fixtures/plan-codec`. The pin is a reviewed repository/package integrity anchor; changing all trusted package code is outside its threat boundary.
+
+`npm run build` compiles TypeScript, runs `scripts/stage-plan-codec.mjs` to verify the pinned manifest and both artifact digests, copies them into `dist-runtime/vendor/plan-codec`, verifies staged bytes, and only then writes runtime identity. Normal builds never fetch or rebuild/re-pin canonical sources. Runtime source entry points verify the same pin and artifact hashes before loading the codec. The compiled pin binds the manifest to runtime identity; the staged CJS bundle is also hashed directly.
+
+Both vendor locations are included by existing npm package file rules. Pack tests extract an isolated tarball and read actual source plus shared complete-object/exact-byte golden fixtures with no SmartFlow checkout and no installed dependencies. Tampering with bundle, declarations or provenance fails in runtime and staging checks. Tracked `dist-runtime` files must accompany source changes.

package/docs/superpowers/plans/2026-09-24-scheme-aware-static-validation.md

@@ -0,0 +1,193 @@
+# Scheme-Aware Dual Static Validation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the canonical static-validation command run and record the required EVM and zkSync compile checks while preserving the existing zkSync project configuration and fail-closed evidence contract.
+
+**Architecture:** Keep `hardhat.config.ts` and its zkSync compiler/network settings untouched. Extend GateTool's static-validation API with explicit compile targets for `evm` and `zksync-eravm`; the CLI resolves those targets from task/workflow inputs and records scheme-aware checks in `static-validation.json`. Existing TypeScript, test, and task-document checks remain shared checks. No deploy/upgrade adapter rewrite is included in this phase.
+
+**Tech Stack:** TypeScript, Node.js `spawnSync`, YAML/JSON evidence, Node test runner, GateTool runtime package.
+
+---
+
+### Task 1: Define scheme-aware static-validation evidence and target inputs
+
+**Files:**
+- Modify: `runtime/workflow/lib/staticValidation.ts`
+- Test: `test/static-validation.test.mjs`
+
+- [ ] **Step 1: Write failing tests**
+
+Add tests proving that `runStaticValidation` accepts explicit compile targets and emits:
+
+```json
+{
+  "scheme": "evm",
+  "network": "gtDev"
+}
+```
+
+and
+
+```json
+{
+  "scheme": "zksync-eravm",
+  "network": "zk"
+}
+```
+
+for the two compile checks, while `compiledSchemes` contains both schemes. Add a failure test proving a failed zkSync compile creates a blocking reason naming the scheme and network.
+
+- [ ] **Step 2: Run the focused test and verify it fails**
+
+Run:
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: the new assertions fail because compile evidence currently has no scheme/network fields and only one compile command is run.
+
+- [ ] **Step 3: Implement the minimal evidence model**
+
+Add explicit compile-target types and extend compile check evidence with optional `scheme` and `network`. Add `compiledSchemes` and `compileTargets` to the structured evidence. Preserve the existing report paths and fail-closed status calculation.
+
+- [ ] **Step 4: Run the focused test and verify it passes**
+
+Run the same build and test command. Expected: all static-validation tests pass.
+
+- [ ] **Step 5: Commit the focused GateTool change**
+
+```bash
+git add runtime/workflow/lib/staticValidation.ts test/static-validation.test.mjs
+git commit -m "feat: record scheme-aware static validation"
+```
+
+### Task 2: Make the static-validation CLI run explicit EVM and zkSync compiles
+
+**Files:**
+- Modify: `runtime/workflow/staticValidate.ts`
+- Modify: `runtime/workflow/lib/staticValidation.ts`
+- Test: `test/static-validation.test.mjs`
+
+- [ ] **Step 1: Write failing CLI/runner tests**
+
+Add a test that supplies two compile targets and asserts the runner invokes exactly:
+
+```text
+npm run compile -- --network <evm-network>
+npm run compile -- --network <zksync-network>
+```
+
+before `tsc`, tests, and document parsing. Add a test that omits either required target and verifies the runner fails before claiming `passed`.
+
+- [ ] **Step 2: Run tests to verify the new behavior fails**
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: the invocation and missing-target assertions fail against the current single-network implementation.
+
+- [ ] **Step 3: Implement target-driven compile execution**
+
+Add `compileTargets` to `StaticValidationOptions`. For this phase require one `evm` and one `zksync-eravm` target from the canonical CLI path. Execute each target with its own `--network` value, preserve command errors, and record target-specific evidence. Keep the existing optional test command and shared checks unchanged.
+
+- [ ] **Step 4: Run the focused tests**
+
+```bash
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: all tests pass and evidence contains both compile checks and both compiled schemes.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add runtime/workflow/staticValidate.ts runtime/workflow/lib/staticValidation.ts test/static-validation.test.mjs
+ git commit -m "feat: require EVM and zkSync static compiles"
+```
+
+### Task 3: Wire workflow inputs and preserve the project zkSync configuration
+
+**Files:**
+- Modify: `runtime/workflow/staticValidate.ts`
+- Modify: `ai-workflows/workflows/v2/deployment/contract-deployment-developer-role-v2.yaml`
+- Modify: `ai-workflows/tests/deployment-runtime-context-policy.test.mjs`
+
+- [ ] **Step 1: Add policy regression assertions**
+
+Require the canonical command to pass explicit EVM and zkSync network arguments/targets and require both scheme results in structured evidence. Assert that the policy retains the project's `zksolc` configuration rather than asking the developer to delete it.
+
+- [ ] **Step 2: Run the policy test to verify it fails**
+
+```bash
+cd /Users/vector/gate/ai-workflows
+node --test tests/deployment-runtime-context-policy.test.mjs
+```
+
+Expected: the new dual-target assertions fail before the workflow text is updated.
+
+- [ ] **Step 3: Update the canonical workflow instructions**
+
+Document that `hardhat.config.ts` keeps its zkSync plugin, network, and `zksolc` settings; the developer must run isolated EVM and zkSync compiles using the selected configured network names; and `static-validation.json` must contain passed evidence for both schemes. Do not add a new user-facing scheme selector or infer scheme from a network name.
+
+- [ ] **Step 4: Run policy tests**
+
+```bash
+node --test tests/deployment-runtime-context-policy.test.mjs tests/zksync-create2-policy.test.mjs
+```
+
+Expected: all relevant policy tests pass.
+
+- [ ] **Step 5: Commit and push workflow policy**
+
+```bash
+git add workflows/v2/deployment/contract-deployment-developer-role-v2.yaml tests/deployment-runtime-context-policy.test.mjs
+git commit -m "docs: require dual-scheme static validation"
+git push origin main
+```
+
+### Task 4: Validate compiler compatibility and package the result
+
+**Files:**
+- Modify only if the compatibility test proves the current project combination is invalid: the SuperTask worktree's project-owned `hardhat.config.ts` and dependency manifest; do not alter GateTool's shared runtime config.
+- Test: current SuperTask worktree compile commands and generated evidence.
+
+- [ ] **Step 1: Run the exact EVM and zkSync compile commands in the current SuperTask worktree**
+
+```bash
+cd /Users/vector/gate/repo_migrate/GateFun/.worktrees/supertask-muf4zhlc-l4a7e-gatefun4
+npm run compile -- --network gtDev
+npm run compile -- --network zk
+```
+
+Expected: EVM compile passes; zkSync compile either passes or produces the exact plugin/compiler incompatibility needed for a project-owned version update.
+
+- [ ] **Step 2: If zkSync compile fails, verify the installed plugin's supported compiler range before changing config**
+
+Inspect the installed `@matterlabs/hardhat-zksync-solc` constants and compile error. Only update `zksolc` to an officially supported version if the current `1.3.22` is actually rejected by the installed plugin; preserve the plugin and network declarations.
+
+- [ ] **Step 3: Run GateTool's complete test suite and build**
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm test
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 4: Pack and install the resulting local package into the current SuperTask worktree**
+
+```bash
+mkdir -p /tmp/gateflow-local-packages
+npm pack --pack-destination /tmp/gateflow-local-packages
+cd /Users/vector/gate/repo_migrate/GateFun/.worktrees/supertask-muf4zhlc-l4a7e-gatefun4
+npm install --no-save --ignore-scripts /tmp/gateflow-local-packages/gate-evm-tools-1.0.28.tgz
+```
+
+- [ ] **Step 5: Verify structured evidence and repository status**
+
+Run the canonical static validation with explicit targets, inspect `docs/static-validation.json`, and confirm the evidence is current-run and contains both schemes. Do not modify or delete failed SuperTask state automatically. Confirm all intended repositories are clean or contain only explicitly documented changes.

package/docs/superpowers/plans/2026-10-28-create2-miner.md

@@ -0,0 +1,82 @@
+# GateTool CREATE2 Miner Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.
+
+**Goal:** Add an independently callable, packaged CREATE2 miner to GateTool while retaining the existing GateFlow miner unchanged.
+
+**Architecture:** Reuse the existing create2Crunch macOS executables, with a GateTool-owned typed request/result API, binary resolver, bounded child-process lifecycle and independent cryptographic verification. Mining is explicit preparation work: no automatic deployment hooks, transaction signing, DB/state migration or parameter mutation. Publish a `gate-evm-tools/create2-miner` subpath and `gate-tool miner` CLI; distribute both binaries offline in the npm archive.
+
+**Tech Stack:** TypeScript, Node child_process, existing ethers v6 runtime/hash helpers, Rust Mach-O binaries, node:test, npm pack.
+
+**Workspace:** `/Users/vector/gate/.worktrees/evm-delivery/EvmGateTools`, existing clean branch `feat/evm-delivery`, base `31c709a6bf7eb69ecad99a3f49ec08f332819cd5`. No changes in SmartFlowAI, EvmHardhatCli or create2Crunch; no npm publication/version bump/App rebuild.
+
+## Task 1: Miner API, CLI and offline distribution
+
+**Files:**
+- Create `runtime/miner/{types,request,verify,binary,runner,index,cli}.ts` with one responsibility per module.
+- Create `resources/create2/{darwin-arm64,darwin-x64}/smartflow_miner`, `resources/create2/{LICENSE,manifest.json,README.md}`.
+- Modify `package.json` exports/typesVersions/files; `bin/cli.js` may route the `miner` command before heavyweight legacy CLI loading. Add help integration in `src/index.ts` if needed.
+- Create `test/create2-miner.test.mjs`, `test/create2-miner-process.test.mjs`, `test/create2-miner-package.test.mjs` and small executable test fixtures as needed.
+- Modify `README.md`, add `docs/create2-miner.md`; regenerate tracked build artifacts with the existing build.
+
+### Public contract
+
+```ts
+// Export typed requests, normalized requests/results and options from the subpath.
+normalizeCreate2MinerRequest(input: unknown): NormalizedCreate2MinerRequest;
+create2MinerRequestFromArtifact(input: {
+  scheme?: 'evm' | 'zksync-eravm'; artifact: Create2HashArtifact;
+  args: unknown[]; factory: string; caller: string;
+  leadingZeroBytes?: number; leadingPattern?: number; targetCount?: number;
+  backend?: 'auto' | 'cpu' | 'gpu' | 'metal' | 'opencl';
+}): NormalizedCreate2MinerRequest;
+resolveCreate2MinerBinary(options?: { binaryPath?: string }): string;
+verifyCreate2MinerResponse(request: Create2MinerRequest, response: unknown): Create2MinerRunResult;
+mineCreate2(request: Create2MinerRequest, options?: {
+  binaryPath?: string; signal?: AbortSignal; timeoutMs?: number;
+  onProgress?: (progress: { status: 'running'; elapsedMs: number }) => void;
+}): Promise<Create2MinerRunResult>;
+```
+
+Contract details:
+- Normalize EVM default scheme and explicit EraVM, strict address/hash lengths, separate scheme-specific hashes, required caller salt prefix, positive bounded targetCount (1–100), leadingZeroBytes 0–20, leadingPattern 0–255. Default backend auto, targetCount 1, difficulty/pattern 0. Unknown/irrelevant fields must not silently change intent. Do not expose Rust debugging nonce/prefix controls yet.
+- GPU supports only repeated-nibble patterns (00,11,...,ff); reject other patterns before spawn unless CPU selected. Validate platform-incompatible backend selection clearly.
+- Artifact helper reuses existing canonicalCreate2Hashes (actual ABI constructor encoding, artifact format and linked bytecode validation); no HRE/RPC/compiler/secret needed.
+- Return normalized request identity plus verified results, actual backend, attempts/duration/rate from binary, explicit status found. Strictly require status, scheme, count, unique salts/addresses and all identity fields. Reject forged/missing/foreign hashes, caller mismatch, leading policy mismatch, nonmatching computed addresses/patterns and partial results. EVM address uses ff/factory/salt/initCodeHash; EraVM uses zksyncCreate2 domain/factory padding/salt/bytecodeHash/constructorInputHash. Metrics must be finite nonnegative; they are reported telemetry, not proof.
+- Resolver uses explicit binaryPath, then GATE_TOOL_CREATE2_MINER_BIN, then package-relative resources for host platform/architecture. Unsupported hosts get an actionable override/build error. Validate bundled file SHA-256 against a trusted manifest pin and executable permissions. Explicit overrides are trusted executable paths; do not fall back silently when invalid. No cwd-based discovery/download/postinstall.
+- Manifest records actual file lengths/SHA-256 and honest provenance (copied from SmartFlow repository resources at its inspected commit; Rust reference checkout is not proof of the binary build revision). Include upstream MIT license, preserve executable bits.
+- Spawn without shell; send JSON over stdin. Bounded stdout/stderr, handle spawn/nonzero exit/malformed JSON/stalled processes. Abort/timeout kills and reaps child (TERM with bounded KILL fallback), clears timers/listeners, settles once, no orphan process. Progress reports elapsed time only. Catch callback errors and terminate cleanly. Pre-aborted calls must not spawn.
+- CLI: `gate-tool miner --request request.json [--output result.json] [--binary /absolute/path] [--timeout-ms N]`; request `-` accepts stdin. JSON result on stdout, diagnostics on stderr, optional output written only after successful verification (avoid truncating existing files on failure; reject overwriting request). SIGINT/SIGTERM must cancel child and exit nonzero. Help must be discoverable through both `gate-tool --help` and `gate-tool miner --help`.
+- This API uses the existing ethers v6 runtime requirement; document it. No changes to old SuperTask adapters, handoff tasks, release sealing, frozen salts, setup version pin or deployment executors.
+
+### Execution steps
+
+- [x] Write failing functional tests for request normalization, artifact hash construction, EVM known address and EraVM reference vectors, and forged response rejection. Assert exports exist before importing lazily so the initial failure identifies missing capability. Run `node --test test/create2-miner.test.mjs` and record expected RED.
+- [x] Implement request/types/verification and API exports; run `npm run build` and the functional test to GREEN.
+- [x] Write lifecycle and CLI tests before implementation: real fixture subprocess stdout/failure/hang/oversized output, AbortSignal, timeout, callback failure, executable resolution and invalid paths. Run new tests to expected RED; then implement process runner/resolver/CLI.
+- [x] Copy the two authorized existing executables (do not remove originals), license and manifest with source/hash evidence. Write package acceptance test before packaging changes: pack into a temp directory, extract away from checkout, verify both binary bytes/modes and API types/exports/help, invoke bundled native CPU mining for EVM and EraVM on supported hosts. Tests may use isolated installed dependencies or explicit symlinks to dependencies, but must not resolve the miner from a checkout path. Test failure diagnostics and clean temporary resources.
+- [x] Wire package and help; add usage docs and verified-result JSON example. Run `npm run build`, `node --test test/create2-miner*.test.mjs test/delivery-source-package.test.mjs test/runtime-version.test.mjs` once all source changes are ready. Record actual tar size. Smoke real native GPU if the current Mac supports it, separately from required deterministic CPU acceptance.
+- [x] Review source and spec independently, resolve concrete findings, and rerun affected checks only. Record evidence here. Commit only these changes locally after verification; do not push/publish/update App runtime archives.
+
+## Acceptance record
+
+Implementation and independent reviews complete. The GateFlow application continues using its original miner until a separately authorized integration.
+
+Parent baseline checks (before new wrapper implementation):
+- Existing runtime identity binding regression: 1 passed.
+- Existing macOS arm64 executable: CPU EVM and EraVM requests returned complete `found` responses.
+- Existing macOS arm64 executable: GPU EVM request with one leading zero byte returned a qualifying address through Metal (~5.8 seconds); reported attempts/hashRate were zero, confirming these counters are unavailable on GPU.
+- Existing x64 executable cannot run on this arm64 host (`Bad CPU type in executable`); x64 runtime acceptance remains outside this host's coverage.
+- Both executables link to macOS system libraries/frameworks, not developer checkout paths.
+- Source resource SHA-256: arm64 `9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954` (1,297,616 bytes); x64 `a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82` (1,306,112 bytes).
+
+Feature commit `8f7a8a2d1d9cb7106ac53b0dcb2b2beefa2ddc32`:
+- Functional RED (5 missing-export failures), lifecycle/CLI RED (15 missing-runner failures), package/type RED (missing resources and raw-input type) were observed before corresponding implementation. Result type alias also received a consumer RED/GREEN check.
+- Full build succeeded. Focused command passed 25 tests, 0 failures/skips. Raw logs are preserved outside the published package at `../setup-logs/create2-miner-20261028/{build.log,focused-tests.log}`.
+- Extracted npm package CPU runs: EVM and EraVM each returned two unique, verified addresses with a leading zero byte; CJS/ESM imports and `.cts`/`.mts` consumers passed. Both architectures' binary hashes, modes and tamper rejection passed.
+- Implementer's separate extracted-package Metal smoke passed EVM (5,117 ms, address `0x001f764470407c723db31f0f490c2edaed0fed70`) and EraVM (11,733 ms, address `0x0012736ec2bc4d20068df1bc6bd9676663a02e2b`). Native GPU attempts/rate remained zero/unavailable.
+- Acceptance tar at this stage was 2,448,819 bytes compressed; final delivery tar may differ due to review fixes and this record.
+- Independent specification review identified a CLI cancellation window during asynchronous output writing. Fix `86daf843d44486561dc60ea3f1541e4f47a99fb9` checks cancellation around output commit and before success reporting. All 16 process tests passed, including SIGINT/SIGTERM at three real filesystem-operation boundaries. The reviewer independently rechecked and issued specification PASS. Raw logs: `output-cancellation-{build,red-original,green}.log` in the same evidence directory.
+- Quality review found that the exported verifier's array `map` could skip sparse result slots from JavaScript callers (native JSON cannot encode holes). Fix `c21667ffd7151db2b6316d2fcb3d414c22285306` validates every expected index, independent of array holes/custom iterators. Full build and affected functional tests passed (5/5); the reviewer independently reproduced rejection and issued quality PASS. Raw logs: `sparse-response-{red,iterator-red,build,green}.log`.
+- No remaining critical/important review findings. Final source has 26 focused tests; the full 25-test run preceded review corrections, which were verified with affected suites (16 process/CLI and 5 functional tests). No production-chain execution, npm publication, App build/toolchain replacement, or changes to other repositories were performed.
+- A local installation archive and machine-readable receipt are produced at `../artifacts/create2-miner-20261028/`. `ACCEPTANCE.json` records final package SHA-256, bytes, source commit and extracted-package CLI acceptance for both schemes. Reproduction script: `../setup-logs/create2-miner-20261028/verify-local-package.mjs`. Package-only checks reuse the worktree's dependencies by symlink; miner code and native resources come exclusively from the extracted archive.