gate-evm-tools 1.0.28 → 1.2.0

package/docs/delivery-planning.md

@@ -0,0 +1,140 @@
+# Internal delivery planning
+
+`runtime/delivery/planning.ts` collects canonical plans from the shared simulation
+steps. It is an internal API: the launcher owns the local fork, signer,
+read-only source connection and validated source/input/runtime identities.
+Collection rechecks those identities and the pinned source/local block before
+and after all steps. It does not expose execution or grant release readiness.
+
+`plan.ts` is a pure parser with no engine, provider or signer imports. Its header
+uses the source deployment's `deploymentId`, explicit `dev`/`prod`, target,
+chain ID, original execution ID, operator, source definition and input hashes,
+and `{ version, digest }` runtime identity. Transaction order is a total order,
+including external transactions. Canonical content hashes exclude timestamps,
+receipts, progress and the downstream production graph. The supplied identity
+ports are trusted inputs; this parser does not verify every project file.
+
+The protocol-neutral transaction planner owns normalization, transaction IDs,
+routes, exact expected comparisons, contiguous replay and segment boundaries.
+The legacy release planner delegates to that kernel and retains its old header,
+file and segmented completion APIs. Delivery seals only a complete expected list.
+A changed operator is a different plan identity; replay never silently reclassifies
+routes. Derived values use the original derivation seed and the shared salt
+algorithm, independent of the wallet. Missing, additional or changed replay values
+fail collection.
+
+The preparation journal receives actual `DeploymentChange` objects from shared
+CREATE2, placeholder/first-upgrade and upgrade algorithms. It stores canonical
+GateTool requests and plans with relative evidence references, hashes, artifact
+identity, derived keys, and exact mappings from GateTool purposes to outer
+transactions. One multicall can cover several purposes. Replay uses the original
+complete preparation; currently deployed code does not shorten its transaction
+list. A registered address reuse that would bypass preparation is explicitly
+unsupported for collection. Simulation never stages candidates or synchronizes
+manifests. Check observations preserve the definition, ABI, resolved address,
+method, arguments, typed actual/expected values, and stable step/call assertion ID
+separately from reporter events. Empty checks are not business acceptance.
+
+Pending UUPS reuse is an explicit evidence port. The common preparation and
+current-code/ERC1967 predicates are also used by the legacy file adapter, which
+lives behind `run.ts`. Delivery evidence binds the original execution, target,
+inputs/artifact/plan hashes, selected steps, infrastructure and derived values.
+Every transaction must have a matching finalized observation from a trusted query
+capability. This unit consumes that capability; it does not implement durable
+receipt production or establish finality from arbitrary JSON flags.
+Each collection retains its validated reuse bindings in immutable
+`runtimeEvidence.pendingUupsReuse`, outside canonical preparation and plan hashes.
+`runtimeEvidence` is a required output; its reuse list is empty when no reuse was
+validated. The replay `expected` type requires only `plan`, `preparations` and
+`verification`, so callers need not supply runtime evidence.
+Replay validates the current evidence again while comparing the complete original
+preparation, transaction mappings and derived bindings exactly. A previous
+collection's `runtimeEvidence` is neither compared nor carried forward.
+
+A same-fork deployment followed by an upgrade is refused until a complete,
+validated immutable OpenZeppelin layout baseline is available. Ordinary build
+info and the preparation plan's layout hashes do not establish that baseline,
+particularly for namespaced storage. Registered baseline upgrades continue
+through the existing official OpenZeppelin validator.
+
+Custom planning uses a separate named `planOperations(ports, input)` export and
+returns `{ version: 1, operations: [...] }`. Legacy `default`, `main`, and `run`
+exports remain exclusive to the legacy full-context runner. The complete emitted
+list is validated before its first operation dispatches: all five native kinds,
+canonical data, unique operation IDs/deploy aliases, literal address/salt/value
+constraints, method syntax, and known field shapes. Parameter and state references
+remain available for dependent operations. In upgrade proxy selectors, the `0x`
+prefix is reserved for valid nonzero addresses, including the string, `name` and
+`contract` forms; ordinary registry aliases and `instance:Contract` keys remain
+supported. Artifact-dependent ABI compatibility and full reference closure remain
+later validation gates. UUPS descriptors name
+the business implementation in both `contract` and `firstUpgrade.contract`, or
+name the canonical `ERC1967Proxy` in `contract` and the business implementation in
+`firstUpgrade.contract`. No old-project placeholder path is required.
+
+The default version-1 `CustomPlanningInputSession` evaluates captured source bytes
+with the bounded `gate-custom-cjs@1` loader. It automatically follows supported
+static module/package inputs, including dead branches, and captures exact business
+read bytes and configuration inputs. `customInputClosure` binds the full session
+union into the plan. Ordered parameter/state/public-target observations and emitted
+operation order remain separate from immutable files. See [the loader policy](delivery-custom-input-closure.md)
+for supported syntax, npm lock/payload identity, configuration, host-adapter limits,
+sealing, and the collector-owned session seam.
+
+A custom step declares `reads: { files, params, state, target }` and may supply
+canonical `input`. Read declarations grant permissions; they are not a completeness
+proof. File paths remain inside the task/business root and pass the same sensitive,
+generated-state and project-file checks as imports. Public target resolution allows
+only `id`, `environment`, `chainId`, `admin`, `create2.scheme`, `create2.factory`,
+`uups.placeholderImplementation`, and `multicall.controlledMulticall`. This whitelist
+also applies to emitted descriptor references. Ports expose no HRE, signer, mutation,
+RPC or chain-read capability. This module/data/package contribution does not establish
+aggregate compiler/artifact/OZ/public-config freeze or release readiness.
+
+Delivery alone derives bounded engine IDs from framed source-step/custom-operation
+identity. `operationBindings` reverses those IDs, and `transactionBindings` binds
+each ordered outer transaction to its operation, native role or call ordinal.
+Full ABI signatures remain in descriptors/calldata/checks. Grouped calls retain
+one authority decision. Legacy locked-plan IDs are unchanged. Preparation mappings
+and derived keys consistently use the generated engine IDs; launcher pending-reuse
+selection therefore uses the plan's mapped IDs.
+
+`runtimeEvidence.forkAudit` captures the local Hardhat instance and chain identity,
+pinned source snapshot, post-setup baseline block/hash, complete ordered local
+blocks/transactions/receipts through the settled end, and trusted send observations.
+The audit is installed before custom module evaluation and is restored in `finally`.
+It rejects missing, extra, pending, duplicate or mismatched sends and receipts,
+changed ancestry/provider identity, and reset/revert/code/storage/nonce mutations
+at the supported provider's public `request`/`send` boundary. Automine is required
+so shared sends cannot wait indefinitely on manually mined receipts. Only the
+launcher's impersonation callback receives a scoped allowance for the requested
+account's impersonation and funding; the asynchronous allowance cannot authorize
+unrelated concurrent or detached calls. These setup calls do not mine transactions.
+Multicall inner operations are counted through their single actual outer envelope.
+
+`verifyCapturedForkAudit` is pure: it consumes captured local evidence and expected
+plan/source/chain identities without evaluating project scripts or claiming that
+fork deployments exist on the source chain. Its caller supplies any independently
+validated completed prefix (default empty); evidence cannot exempt its own prefix.
+This run audits only the remaining suffix. Runtime observations are kept outside
+canonical replay plan/preparation identity. This is an audit of the supported
+provider/API boundary, not an isolation boundary against hostile code running as
+the same OS user, retained internal RPC capabilities or arbitrary module imports.
+
+The packed acceptance fixture runs the exact Hardhat 2.26.3, ethers 6.15.0,
+OpenZeppelin upgrades 3.9.1 and upgrades-core 1.44.2 stack. It verifies actual
+CREATE2 and atomic firstUpgrade transactions, business writes and multicall,
+code/ERC1967/owner/value checks, a separate fork V2 upgrade against an actually
+synced proxy, and extra/pending transaction refusal while source state, registry
+and manifests remain unchanged. After qualification, a distinct disposable
+`localhost` execution verifies two shared V2 upgrade transactions, official layout
+validation and real development manifest synchronization. It preserves the
+source/fork identity guard instead of syncing a fork under the source target's
+name. This validates shared execution/sync capabilities; it does not implement the
+complete durable development lifecycle.
+
+Remaining gates belong to later units: full qualification/release readiness,
+complete frozen business inputs and recursive ABI validation (5c.1),
+registry/evidence acceptance (5c.2), and durable finalized observation
+production/query (6a). The collection returned here is an immutable internal
+plan, not `release_ready` or execution authority.

package/docs/delivery-release.md

@@ -0,0 +1,119 @@
+# Developer production delivery
+
+`gate-evm-tools/delivery-release` completes the developer side of the new EVM full delivery flow. Run it from the actual project root using the installed, locked package. It generates qualification through `collectDeliveryAggregate`; callers cannot submit an aggregate or choose upstream roots. Every production target in `scripts/tasks/<deploymentId>/task.yaml` must have one current `prod-qualification` task in the same canonical handoff.
+
+## Contract commit and deployment input snapshots
+
+Before a production release can be prepared or finalized, project contract sources must be committed. The tool discovers the configured Hardhat source directory and actual compiled local imports, checks their Git tree, index and physical bytes, and rejects staged, uncommitted, untracked (including ignored), deleted or conflicted contract sources. This requirement does not block ordinary development or local simulation.
+
+`contractSource.commit` is the full SHA of the most recent source-changing commit on the current first-parent history, including source-changing merges. Later script or documentation commits do not change it. The referenced commit must reproduce the current project source set; the source fingerprint must also match the actual qualified compiler inputs. Installed contract dependencies, compilation configuration and runtime identity remain bound by the existing qualified input evidence. No separate deployment-script commit is required.
+
+Preparation writes `scripts/tasks/<deploymentId>/releases/<releaseId>/inputs.snapshot.json` before publishing its candidate. The snapshot preserves exact project input bytes: deployment operations, parameters, custom scripts, parameter producers and their observed local dependencies, contract sources, qualified artifacts/configuration, and existing package/TypeScript configuration and production explanation. Installed `node_modules` payloads are not duplicated here; their existing runtime/package evidence remains authoritative. Signing credentials in Hardhat configuration must use environment references, and environment values are never evaluated into the snapshot.
+
+The candidate and final bundle bind the snapshot's content hash and exact byte hash. Finalization and production inspection continue checking the current files against the qualified inputs and snapshot. A frozen release cannot be overwritten; changing deployment logic, parameters or checks requires validation and a new release ID. Changes affecting accepted development semantics also require a new development acceptance. A failed execution with unchanged inputs keeps its existing execution ID and reconciles first.
+
+Git submission/history checks run during developer preparation and finalization. An administrator consuming a completed release validates its frozen bytes and existing delivery evidence; this does not require Git metadata or a new script commit.
+
+The editable `scripts/tasks/<deploymentId>/` files can advance after release. Historical input recovery reads the original published bundle and snapshot, without substituting the latest task files:
+
+```js
+const recovered = release.restoreDeliveryReleaseInputs({
+  ...scope, releaseRef,
+  destination: '/absolute/new-directory-outside-the-current-project',
+});
+// recovered.status === 'inputs-restored'; recovered.contractSource.commit identifies the source version.
+```
+
+Recovery validates all snapshot bytes before writing, requires a new external directory and never overwrites the current project. It restores inputs only: original handoff/prerequisite/history evidence, locked dependencies and execution records must still be retained for historical execution and verification. Recovery itself grants no release readiness, signing or broadcast authority, and does not alter chain history.
+
+## Preserve accepted development before editing production inputs
+
+After `createDevelopmentDelivery(...).continue()` returns `accepted`, preserve its original `source` and `aggregate` with the public capture method **before changing the package, configuration, or production containers**:
+
+```js
+const release = require('gate-evm-tools/delivery-release');
+const development = release.captureDevelopmentReleaseHistory({
+  root: process.cwd(), source: developmentSource, aggregate: developmentAggregate,
+});
+// Persist `development` as JSON; it contains confined project-relative file references.
+```
+
+Capture reads the actual installed package and refuses any payload that differs from the accepted aggregate. It saves the original aggregate, source, changing input containers, full package payload, and a compressed snapshot archive. Its READY file is written last. The archive is a tool-produced installed-payload snapshot, not an npm distribution tarball: the observed npm lock integrity remains separate metadata. The consumer compares the complete snapshot contents with the original package payload, payload digest, and executable runtime identity. No old runtime executes, and no historical digest is rewritten to name a newer runtime.
+
+Only production-only container additions/completions are compatible with the existing development acceptance. Development parameters and provenance, public target configuration, existing Hardhat network definitions, compiler/plugins, source, artifacts, scripts and custom dependencies remain bound. A custom dependency on an entire changed container is rejected. Historical task definitions retain all fields except the explicit production-target-list extension. Changed development semantics require a new development acceptance.
+
+Public facilities resolve as `baseProfile → dev/prod profile → network overrides`. History checks allow changes to `_profiles.prod` and the selected production network entries without invalidating development acceptance. Shared `_profiles.baseProfile`, `_profiles.dev` and all non-production network entries remain bound, and the resolved development target must still match the accepted target. If a development custom script or parameter producer depends on the complete `config.yaml`, its original file digest remains required even for production-only edits.
+
+## Complete prerequisites and production inputs
+
+Finish all selected production parameter leaves and provenance through the existing strict parameter resolver. Record concrete public executors, operation order, permissions, checks and adaptations in this round's canonical inputs. Requirements, operation intent and input bytes are frozen per round. A shared `docs/prod-execution-plan.md` is neither required nor automatically archived. Recovery resumes the original per-network executionId after reconciliation and preserves submitted transactions and finality evidence.
+
+Development and enabled audit dependencies must appear in each qualification's upstream closure. Each current prerequisite must be completed/successful with `adoptedRev === rev`. Use `release.isDevelopmentAcceptancePrerequisite(task)` to classify development evidence: execution/verification tasks reference actual acceptance or raw CheckCode; completed simulation-only script tasks use report receipts, including script tasks from a referenced earlier round. Simulation-only work cannot replace this round's required verified development acceptance. Other prerequisite skills first produce their actual reports and complete the task with `result.codeRef` and `result.evidence` file refs, then invoke:
+
+```js
+release.recordDeliveryPrerequisite({
+  workspaceRoot, projectRoot: '.', handoff: 'handoff.md',
+  taskId, deploymentId, planKey: 'security-audit',
+});
+```
+
+The tool binds the current canonical task/revision/definition, code reference, and the actual bytes of the union of report refs and declared `expectedArtifacts`. Existing outputs do not need to be added to an already-completed result. Missing or empty files and changed bound bytes still fail. Audit results must explicitly reference `audit-reports/security-audit-report.md`. This receipt establishes provenance and eligibility, not semantic audit quality. Disabled audit lanes do not acquire new requirements. Missing, revised, cancelled, disabled or unsuccessful mandatory prerequisites block readiness.
+
+## Two-phase release
+
+```js
+const scope = {workspaceRoot, projectRoot: '.', handoff: 'handoff.md', taskId, deploymentId};
+const prepared = await release.prepareDeliveryRelease({
+  ...scope, releaseId: 'vault-2026-10', development,
+  targets: [
+    {executionId: 'qual-mainnet', request: {
+      version: 1, environment: 'prod', purpose: 'prod-qualification', mode: 'simulate',
+      network: 'mainnet', operator: publicExecutor,
+      sourceRef: {path: 'handoff.md', taskId, planKey: 'qual-mainnet', rev: 1},
+      fork: {blockNumber, blockHash, readOnly: true},
+    }},
+    // Every task.yaml release target, in canonical order.
+  ],
+});
+```
+
+The returned `releaseRef` is preliminary: there is no release-ready marker. The actual owner qualifies every target on an isolated read-only fork, retains preparations, full typed assertions and fork audit, then freezes the current business inputs and prerequisite evidence. Nonces, fees and administrator approval belong to the later execution snapshot.
+
+The developer mainAgent uses canonical Plan commands to create production tasks
+for each selected target in the same handoff. Each task declares
+`purpose: prod-execution`, prod environment, target, revision and the preliminary
+releaseRef. One task can cover all capabilities; split tasks form an explicit
+dependency chain. Each target's graph covers simulate, execute or export-calldata,
+and verify, and depends on its qualification task. Qualification has
+`purpose: prod-qualification`, actions simulate/verify and no releaseRef.
+The deployment Agent implements and qualifies; mainAgent plans and dispatches.
+Split execute/export tasks also allow reconcile or verify so they can observe
+completion after external execution; simulation or calldata delivery alone cannot
+complete those tasks. A merged task including verify completes only on acceptance.
+The production operator later selects these existing tasks.
+
+```js
+const ready = await release.finalizeDeliveryRelease({...scope, releaseId: 'vault-2026-10'});
+const inspected = release.inspectDeliveryRelease({...scope, releaseRef: prepared.releaseRef});
+```
+
+`sourceDefinitionHash`, `inputsHash`, and `prodTaskGraphHash` are separate. Inputs exclude release definitions, refs, progress and published files. The final bundle binds all three plus its own hash. Classification examines the complete task universe before selecting the desired ref, so wrong-bound, split bindings or missing capability/dependency coverage cannot hide behind ref filtering. Independently complete other releases remain separate.
+
+Finalization rereads current source/input/evidence files and task eligibility after asynchronous work, writes the immutable bundle, verifies everything again, then fsyncs the authoritative `release.json` marker last. An interrupted attempt has no ready marker and can retry finalization from its existing candidate. Inspection performs no writes or business recomputation: absent marker returns `{status:'pending'}`; malformed, incomplete or changed ready content throws. A successful result is `{status:'release_ready', release, bundleHash}`. This denotes developer qualification only; R2 provides no production broadcast or host approval capability.
+
+## Agent-planned production tasks
+
+New tasks use explicit `scope.deployment.purpose` (`analysis`, `dev-execution`,
+`prod-qualification`, `prod-execution`) and `allowedActions`. A step name is a
+planning label. Each selected production target has one qualification task and
+an ordered production dependency chain; it may be one task covering simulate,
+execute/export and verify. All target tasks bind the same frozen release. Split
+tasks explicitly depend on preceding work and the target qualification.
+
+Finalization checks complete action coverage and actual prerequisite evidence,
+not a fixed three-node shape. A merged task that includes verify remains open
+through preparation, transaction finality and export; only accepted business
+verification completes it. GateFlow owns dispatch and authorization; these APIs
+never schedule business tasks or grant signing capabilities.
+
+Node/npm only need to be compatible with the project tools; an exact host version is not a release prerequisite. Node/OS/architecture/ABI labels remain in evidence, while execution fingerprints bind actual dependency payloads, module resolution, project TypeScript emission, compiler inputs and artifacts. Production re-simulation also checks released calldata and ABI intent before producing an executable plan. The existing reviewed compiler backend restrictions still apply.

package/docs/delivery-safe.md

@@ -0,0 +1,75 @@
+# 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. The internal model
+retains the full plan and frozen Safe payload, with signatures left for external
+collection. Production delivery publishes one business CALL array JSON, including
+the readable ABI and reviewed nested intent. The low-level Safe envelope renderer
+still exposes its internal envelope model separately. An unprepared current Safe
+segment reports `preparation-required` and still exports the complete CALL array.
+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,198 @@
+# EVM full 项目的按需部署接入
+
+`gate-tool delivery` 接受已完成生成的 `gateflow-evm-full@1` / `profile: full` 项目。
+新版 full 增加 Foundry 测试配置，部署仍使用受资格校验的 Hardhat 产物。
+它不迁移旧 full/旧模板，不复制 workflow 源码，也不管理项目的 RPC 网络目录。
+正常的 `compile`、`test`、`typecheck`、`clean` 在接入前后均不需要 `config.yaml`、钱包或外部 RPC。
+
+## 本地接入
+
+创建 JSON 选项文件，例如：
+
+```json
+{
+  "workspaceRoot": "/absolute/workspace",
+  "projectRoot": "contracts",
+  "targets": [
+    {
+      "network": "sepoliaDev",
+      "environment": "dev",
+      "finality": { "confirmations": 1 },
+      "create2": {
+        "scheme": "evm",
+        "factory": "0x1111111111111111111111111111111111111111"
+      }
+    }
+  ]
+}
+```
+
+新 full 已声明 GateTool 与 OZ 升级工具；本地发行版把配套 GateTool 归档保存在项目
+`vendor/` 并使用相对 `file:` 依赖。先在项目安装依赖，setup 保留已有归档声明，
+只接入选中的目标配置与插件，不必再传 `toolPackage`。保留归档和 lockfile，项目移动后仍可重装。
+`gate-tool` 是 `gate-evm-tools` 提供的命令，模板生成器不需要作为业务项目依赖。
+
+工厂地址只是格式示例。新 full 已默认写入公共设施，普通目标可省略选项中的 `create2`、
+`uups` 和 `multicall`，仅特殊网络提供覆盖值。无设施默认的工程仍可只使用 call/view/check。
+setup、`loadDeliveryTarget` 与实际输入冻结采用同一套严格字段和非零地址校验。
+具体操作需要哪些设施由执行输入验证决定。
+
+### 默认设施继承
+
+full 的 `config.yaml` 只定义一份公共地址：
+
+```yaml
+_profiles:
+  baseProfile:
+    uups:
+      placeholderImplementation: "0x000000009F21E08bE874b78F40A6d038587E0C54"
+    multicall:
+      controlledMulticall: "0x00000000bD2f006A24b6d99baaD1323D5809948f"
+  dev:
+    create2:
+      scheme: evm
+      factory: "0x2370B48f20FFd75A46B14A9888B3E79677eFC28c"
+  prod:
+    create2:
+      scheme: evm
+      factory: "0x6497eC1A66A2dF192179A760e8D35f8d30ddaA06"
+```
+
+每个选中目标按 **baseProfile → 对应 environment（dev/prod）→ 网络自身字段** 合并，后者优先，
+按设施内部字段覆盖。setup 默认只写选中目标的 environment、finality 和 manifest 等目标配置，
+不复制继承地址；运行时自动解析，所以修改公共地址会影响所有未覆盖的网络。
+特殊网络可手工添加 `multicall.controlledMulticall` 等覆盖，或通过 setup 明确传入。
+重复 setup 保留手工覆盖；明确请求与已存目标值冲突仍拒绝。无需 YAML anchor 或 `<<`。
+
+只有 create2、uups、multicall 设施可以继承。environment、finality、admin、manifest、Safe 策略和
+授权不从 profile 继承；环境必须由目标显式选择。当前继承后的设施纳入规范输入及冻结指纹；
+修改 base/profile/目标会触发输入变化检查，不能改变已冻结 release 后直接继续生产执行。
+这些地址来自历史模板，仍须核验所选链的代码、接口和权限。
+
+```sh
+gate-tool delivery inspect --options delivery-options.json
+gate-tool 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：full/App 已提供配套归档时直接使用项目声明。
+显式切换工具包时，在 GateTool 仓库运行 `npm run build` 和
+`npm pack --pack-destination /absolute/build`，更新项目本地归档、依赖声明与实际 lockfile。
+`toolPackage` 仅供尚无工具包声明的接入选项使用，不覆盖已有不同的包选择。
+该字段可省略，但仅有 `gate-evm-tools@1.2.0` 版本号不能证明 API 已存在；诊断会检查本地 exports。
+如 package.json 已声明另一来源，先显式调整该依赖，不会静默覆盖人工声明。
+
+验证的项目工具链是 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 补丁。
+
+setup 同时写入编译依赖的已审核版本约束，包括 semver 5/6/7 各自的版本和 ansi-regex 6。
+首次安装无需临时添加 overrides；已有冲突选择会在写入前拒绝。安装后提交项目 lock，
+后续使用 `npm ci` 复现依赖。版本锁定不替代编译依赖内容校验，未审核的包内容仍会被拒绝。
+
+编译来源校验接受 npm 官方源和 `https://registry.npmmirror.com/`，以及显式本地 tgz。
+镜像安装仍须匹配 lock 中的 SHA-512 完整性和已审核的包版本、实际文件内容；不会因镜像地址跳过校验。
+
+网络仍只定义在项目 `hardhat.config.ts`。接入读取静态 const/default-export 对象中的选中网络，
+支持字面 URL、`process.env.NAME`、`||` 和 `??`，以及配套 full 模板固定的 `rpcUrl({ route, publicFallback, useBaseRpc })`。模板从项目目录加载 `rpc.env`、`.env`，优先级为进程变量 → `rpc.env` → `.env`。`rpc.env` 默认包含公开 RPC（含 Sepolia）和空的 `BASE_RPC_URI=`；网络显式声明 `useBaseRpc`：`true` 且前缀非空时共用 `BASE_RPC_URI/<route>/`，否则使用 `<CHAIN>_RPC_URL` 备用 URL；`false` 始终使用备用 URL。dev/prod 共用同链路由和备用 URL。Sepolia、Fantom 默认设为 `false`。有限解析器只接受字面布尔值并将开关写入配置定义。静态读取器只识别固定 loader/helper，不执行项目代码；其他动态计算的选中网络需要人工改为可验证的定义。本地 env 不进入交付证据或 release 输入快照。业务依赖扫描遵循静态 `paths.sources`（默认 `contracts`），且只读取项目内目录。
+
+full 预设 `ethDev`/`ethProd` 等成对别名，`config.yaml` 显式绑定 dev/prod，设施继续按 profile 继承。dev 的 `resolveHardhatAccounts(process.env.PRIVATE_KEY)` 由可信的 `gate-evm-tools/custody` 导入提供；静态定义只记录环境引用。prod 的项目 accounts 保持为空，通过正式运行时核验权限后执行或导出带 ABI 的 calldata。预设列表不自动成为部署目标。
+诊断只输出 network、chainId 和 rpcConfigured，不输出解析后的 RPC URL。
+`inspect/setup` 只检查进程变量和 `rpc.env`，始终不访问 `.env`；把所选网络的 RPC 配置放在 `rpc.env`。只在 `.env` 中提供 RPC 不算公开预检配置完成，缺少时返回 `rpcConfigured: false`。这使预检在 Agent 禁止读取凭证文件的沙箱中仍可运行；依赖未安装时继续返回 `dependencies_pending`，不伪造 ready。
+实际运行时观察仍按完整的进程变量 → `rpc.env` → `.env` 规则核对 Hardhat 配置，不因沙箱拒绝访问而跳过校验。需要凭证的执行使用 App 已有的受控宿主入口；开发执行由宿主进程加载项目 `.env`，生产签名使用宿主签名器。Agent 不读取、打印或复制私钥，也不关闭沙箱。普通 Hardhat 编译／测试在 `.env` 被保护时不要求钱包。
+可通过项目生成器或手工增加网络，无需发布 GateTool。
+
+## 公共 API
+
+- `gate-evm-tools/delivery-setup`：`inspectDeliveryProject(options)`、`setupDeliveryProject(options)`、
+  `readPublicProjectNetworkSnapshots(root, aliases, env?)`、`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，
+保留完整运行时环境读取语义；`readPublicProjectNetworkSnapshots` 用于不访问 `.env` 的公开预检，不能替代实际执行的运行时观察。两者都不要写入交付文件或日志。`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": "sepoliaDev",
+  "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:evm`。测试需要相邻的 `EvmHardhatCli` checkout 已构建。该测试生成全新 full、安装本地 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。
+
+Setup 同时补齐已验收编译适配器所需的 npm overrides，限定实际依赖版本；不同 undici/tslib 主版本分别约束。已有同名 override 冲突会在写入前返回错误。依赖树、lock SRI 和实际包内容校验继续生效，不以 overrides 代替包身份验证。项目应保存真实安装后的 lockfile，并使用 npm ci 复现。

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 explicitly bound by `scope.deployment.purpose`. Main Agent may use
+custom step labels or combine capabilities in one task. The supported execution
+purposes are dev-execution, prod-qualification and prod-execution; analysis is
+planning only. Allowed actions, environment, target and release references are
+validated independently of task labels.
+
+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 prod-execution 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.
+
+Task purpose is read from scope.deployment.purpose; custom step names and merged tasks are supported. allowedActions, target, source revision and release binding remain mandatory gates.

package/docs/direct-package-acceptance.md

@@ -1,3 +1,5 @@
+> 历史文档：其中的 gate-workflow 命令已移除。新项目使用 gate-tool delivery 与 delivery API，见 [部署接入](delivery-setup.md)。
+
 # Direct-package template acceptance — 2026-09-09
 
 New full projects use `gate-workflow` directly through the existing npm command names. Hardhat and tests import `gate-evm-tools/runtime-config/*` and `runtime/*`; the template no longer contains `scripts/workflow` or `scripts/config` forwarding directories. Business contracts, task/custom scripts, configuration and state remain project-owned.