gate-evm-tools 1.0.31 → 1.2.1

package/docs/delivery-setup.md

@@ -1,7 +1,8 @@
-# Core 项目的按需部署接入
+# EVM full 项目的按需部署接入
 
-`gate-delivery` 只接受已完成生成的 `gateflow-evm-core@1` / `profile: core` 项目。
-它不迁移 full/旧模板，不复制 workflow 源码，也不管理项目的 RPC 网络目录。
+`gate-tool delivery` 接受已完成生成的 `gateflow-evm-full@1` / `profile: full` 项目。
+新版 full 增加 Foundry 测试配置，部署仍使用受资格校验的 Hardhat 产物。
+它不迁移旧 full/旧模板，不复制 workflow 源码，也不管理项目的 RPC 网络目录。
 正常的 `compile`、`test`、`typecheck`、`clean` 在接入前后均不需要 `config.yaml`、钱包或外部 RPC。
 
 ## 本地接入
@@ -12,10 +13,9 @@
 {
   "workspaceRoot": "/absolute/workspace",
   "projectRoot": "contracts",
-  "toolPackage": "/absolute/build/gate-evm-tools-1.0.29.tgz",
   "targets": [
     {
-      "network": "sepolia",
+      "network": "sepoliaDev",
       "environment": "dev",
       "finality": { "confirmations": 1 },
       "create2": {
@@ -27,14 +27,51 @@
 }
 ```
 
-工厂地址只是格式示例，应填写项目实际设施地址。`create2`、
-`uups: { placeholderImplementation }` 和 `multicall: { controlledMulticall }`
-都可省略；call/view/check 类项目无需部署设施。提供设施配置时，setup 和 `loadDeliveryTarget` 均校验其地址为非零 EVM 地址。
-`loadDeliveryTarget` 保留 YAML 中的额外人工字段，不采用 setup 选项的严格字段白名单。具体操作需要哪些设施由执行输入验证决定。
+新 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-delivery inspect --options delivery-options.json
-gate-delivery setup --options delivery-options.json
+gate-tool delivery inspect --options delivery-options.json
+gate-tool delivery setup --options delivery-options.json
 ```
 
 `inspect` 是只读诊断。`setup` 完成冲突预检后，仅补充缺失的选中目标配置、
@@ -48,26 +85,39 @@ gate-delivery setup --options delivery-options.json
 重复 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。
+当前未发布的 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 已声明另一来源，先显式调整该依赖，不会静默覆盖人工声明。
 
-验证的 core 工具链是 Hardhat `2.26.3`、ethers `6.15.0`、hardhat-ethers `3.1.0`、
+验证的项目工具链是 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`、`||` 和 `??`；动态计算的选中网络需要人工改为可验证的静态定义。业务依赖扫描遵循静态 `paths.sources`（默认 `contracts`），且只读取项目内目录。
+支持字面 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)`、
-  `readProjectNetworkSnapshots(root, aliases, env?)`、`loadDeliveryTarget(root, network, environment?)`、
+  `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)` 及请求类型。
@@ -75,7 +125,7 @@ upgrades-core `1.44.2`、contracts `5.4.0`；业务 Solidity 源码引用 contra
 - `gate-evm-tools/delivery-policy`：不加载 OZ 的共享 manifest 策略。
 
 `readProjectNetworkSnapshots` 提供给本地 provider 装配使用，包含解析后的 URL，
-不要把它写入交付文件或日志。`validateDeliveryRpc` 首先校验请求语法，之后才调用
+保留完整运行时环境读取语义；`readPublicProjectNetworkSnapshots` 用于不访问 `.env` 的公开预检，不能替代实际执行的运行时观察。两者都不要写入交付文件或日志。`validateDeliveryRpc` 首先校验请求语法，之后才调用
 注入的 `loadProvider(snapshot)`；provider 的 `request({ method: "eth_chainId", params: [] })`
 必须返回与项目快照一致的真实 chain ID。RPC 失败或链 ID 不符直接拒绝，没有备用网络。
 
@@ -87,7 +137,7 @@ upgrades-core `1.44.2`、contracts `5.4.0`；业务 Solidity 源码引用 contra
   "environment": "dev",
   "purpose": "dev-execution",
   "mode": "simulate",
-  "network": "sepolia",
+  "network": "sepoliaDev",
   "sourceRef": {
     "path": "handoff/task-1/handoff.md",
     "taskId": "task-1",
@@ -134,7 +184,7 @@ qualification verify 不需要伪造 fork 或 releaseRef，不接受 execute/exp
 旧 workflow 配置入口仅接受 local/development/production，拒绝 dev/prod；新协议通过独立 loader 只接受 dev/prod。
 共享 manifest/preparation 策略支持两套环境名称，但不会将新环境转换为旧 workflow 请求。
 
-真实本地验收：`npm run test:delivery:core`。测试需要相邻的 `EvmHardhatCli` checkout 已构建。该测试生成全新 core、安装本地 tarball、
+真实本地验收：`npm run test:delivery:evm`。测试需要相邻的 `EvmHardhatCli` checkout 已构建。该测试生成全新 full、安装本地 tarball、
 编译临时 UUPS 合约并验证 canonical prepare，确认重复 setup 稳定及删除 YAML 后普通命令正常；
 它不发布 npm 包，也不连接真实链。
 
@@ -144,3 +194,5 @@ 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

@@ -18,13 +18,11 @@ const bound = await validateDeliverySourceRpc(options, selectedNetworkSnapshot,
 
 `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 |
+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.
 
@@ -32,7 +30,7 @@ Traversal, symlinks, hardlinks, nonregular files, missing/invalid handoffs, inco
 
 ## 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.
+`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:
 
@@ -65,3 +63,5 @@ After reviewing the rebuilt artifact, explicitly update `runtime/delivery/codec-
 `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.

package/docs/openzeppelin-acceptance.md

@@ -0,0 +1,86 @@
+# 无补丁 OpenZeppelin 交付验收（2026-10-28）
+
+本文保留当时的 UUPS 验收范围；后续新增的普通 EVM OZ 5 Transparent/ProxyAdmin 能力与验收见 [2026-11-02 任务记录](plans/2026-11-02-transparent-proxy-delivery.md)。
+
+本轮配套版本：`gate-evm-tools@1.1.0`、`gate-evm-hardhat-foundry@2.2.0`。
+实现范围为普通 EVM CREATE2、UUPS 首次部署与后续升级；Transparent/ProxyAdmin
+未纳入本轮。两仓库位于 `feat/oz-toolkit-consolidation` 工作树，未发布 npm、推送、
+合并或替换 App 内包。产物、提交与哈希以产物目录的 `pair-manifest.json` 为准。
+
+## 实现核对
+
+| 能力 | 实现及验收 |
+| --- | --- |
+| 官方 OZ 原样使用 | full 删除 685 行补丁、patch-package 与安装钩子；与官方 3.9.1 的五个源码/构建/类型文件摘要逐一比较，执行前后不变 |
+| 准备与组合 | `deployment-evm` 复用现有准备引擎；CJS、ESM、包名 TypeScript 导入通过；无 signer 选择或广播 export |
+| CREATE2 | 真实构造参数绑定 initCodeHash/地址；预期地址不一致拒绝；实际 runtime 不匹配拒绝复用 |
+| UUPS | 原子部署/首次升级/初始化、兼容升级、普通及 namespace 布局拒绝；manifest 与当前实现校验保留 |
+| 原子业务调用 | 显式顺序、非零 value 精确求和、allowFailure=false；设置、owner 转移与回滚均在本地链验证 |
+| 正式执行入口 | full 的已安装 workflow engine 产生三笔真实回执并检查业务状态、同步 manifest；core 通过真实 tarball setup 进入 ready |
+| 安装与升级 | npm ignore-scripts 保留；npm/yarn/pnpm 无补丁后处理；失败返回依赖未就绪；新版 full upgrade 保护冲突、路径、自定义 hooks，旧 OZ 补丁项目拒绝自动迁移 |
+| dev 验收 | 已安装 public development API 实际执行 UUPS + 配置、2 条业务断言、真实 CheckCode；文件中断后恢复，无重复签名 |
+| prod 交付 | 真实 public release/production API 完成冻结、calldata 导出、2 笔本地交易及 2 条业务断言；发布中断、广播返回丢失、验收文件中断均恢复，合计仍只有 2 次签名和广播 |
+
+## 已通过的检查
+
+- GateTool 相关准备、manifest、setup、journal、development 等分组：156 项通过。
+- 额外执行/冻结边界分组：106 项通过；最新 API/准备/manifest 分组 22 项通过，包名类型导入 2 项通过。
+- 真实 core setup 与 EVM target manifest 集成：2 项通过，包含同 fork 升级、namespace、安全拒绝与 dev/prod 隔离。
+- zkSync 准备相关既有分组：8 项通过；只涉及适配器回归及 full 插件加载，不宣称完成 zkSync 链上部署。
+- 生成器 core/network/安装/升级相关分组：114 项通过；最新受影响安装/升级/模板分组 19 项通过；大型 full 文件中本轮相关断言 7 项通过。
+- 成对 tarball：带示例、无示例 full 均独立生成并安装本地工具包，通过编译、Hardhat 测试、create2-hashes CLI、真实 workflow engine 与 CREATE2/UUPS 验收。
+- Foundry：带示例运行测试；无示例项目运行 build（没有业务测试可执行）。GitHub 下载超时后显式使用 forge-std v1.16.2 本地归档，归档摘要记录在验收 JSON。
+- 实际本地 EOA operator → external → operator、两目标 aggregate 与 dev lifecycle 均通过。
+
+prod public API 验收最终通过（204 秒）；保留了实际冻结候选并从 checkpoint 收尾，未重填业务参数。
+测试结果有重叠，不相加为总用例数。日志和独立项目路径见 `pair-manifest.json` 与 `paired-acceptance.json`。
+
+## 复现
+
+在两个源码工作树分别运行 `npm run build`、`npm pack --pack-destination <产物目录>`。
+然后在生成器仓库运行：
+
+```sh
+GATE_TOOL_TARBALL=/absolute/gate-evm-tools-1.1.0.tgz \
+GATE_GENERATOR_TARBALL=/absolute/gate-evm-hardhat-foundry-2.2.0.tgz \
+GATE_ACCEPTANCE_OUTPUT=/absolute/evidence \
+GATE_FORGE_STD_TARBALL=/absolute/forge-std-v1.16.2.tar.gz \
+node --test test/packaged-unpatched-full.test.mjs
+```
+
+包验收使用 npm offline，需要完整的依赖缓存。网络可用时可以先正常预热依赖；
+缓存只是安装输入，验收实际从独立项目 node_modules 解析工具包与官方 OZ。
+不提供 Foundry 归档时使用原有 `npm run install:foundry`。
+生成器源码仓库自身仍保留基线 GateTool 开发依赖；源码夹具测试前需显式使用本轮
+已构建的本地包，成对验收通过环境变量直接选择实际 tarball，不依赖该开发依赖。
+
+core 冻结交付验收按顺序运行：
+
+```sh
+GATE_AGGREGATE_CASES=main GATE_KEEP_AGGREGATE_FIXTURE=1 \
+node --test test/integration/delivery-aggregate.test.mjs
+# 使用上一步日志中的实际项目绝对路径
+GATE_DEVELOPMENT_FIXTURE=/absolute/project GATE_KEEP_DEVELOPMENT_NODE=1 \
+GATE_DEVELOPMENT_EVIDENCE=/absolute/evidence \
+node --test test/integration/delivery-development.test.mjs
+GATE_UNPATCHED_RELEASE_FIXTURE=/absolute/project GATE_RELEASE_EVIDENCE=/absolute/evidence \
+node --test test/integration/openzeppelin-release.test.mjs
+```
+
+prod 夹具只使用本地 31337 链和公开测试账号。release checkpoint 已生成时，
+可以设置 `GATE_UNPATCHED_RELEASE_RESUME=1` 继续该冻结候选的执行验收；不重新填业务参数。
+验收进程可能耗时数分钟，完成后关闭该测试节点。
+aggregate 夹具显式锁定现有 compiler pins 已批准的 axios 1.20.0；
+本轮未扩展 compiler pins、未放行未批准的新传递依赖。
+实际验收的 core package/lock 副本随产物保存，部署项目仍需维护自己的审核锁文件。
+
+## 已知限制
+
+生成器 `full-template.test.mjs` 的一次整体运行未通过（248 项中 111 通过、137 失败）。
+多数失败来自旧源码复制/假 HRE 夹具遗漏 delivery policy、operationNames、transactionPlanner
+等依赖；基线 runtime 已包含这些依赖，本轮没有修改相应模块。已修正本轮受影响的模板、
+版本、补丁断言并单独通过，未将该历史整套测试报告为通过，也未为通过而跳过/删除其测试。
+独立本地包与真实 HRE 验收用于验证本次实际交付。
+
+不包含 App 内 LLM/Keychain/完整 UI、公开生产链广播、Safe 本轮新增验收、旧项目自动迁移，
+也不宣称 Transparent 或 Solana/Sui 获得支持。

package/docs/openzeppelin-baseline.json

@@ -0,0 +1,27 @@
+{
+  "package": "@openzeppelin/hardhat-upgrades",
+  "version": "3.9.1",
+  "tarballSha256": "b56f30fb689bd01a0cc7f1eb1de7fed2781cf86945e910391c770b17931178e6",
+  "files": {
+    "src/deploy-proxy.ts": {
+      "sha256": "fcb35a3c52786825b72b0aabb56a385b9d79b522ea702b8789c54c9a60565ede",
+      "installedMatchesOfficial": true
+    },
+    "dist/deploy-proxy.js": {
+      "sha256": "629a7e8e6474b1b850d8a459331a96e994796ef72bc871c5c9553f937ac7af4f",
+      "installedMatchesOfficial": true
+    },
+    "dist/deploy-proxy.d.ts": {
+      "sha256": "5f34a9300873d6cb5182282154f6268da338ef7c390b5cac0a58985e808e0899",
+      "installedMatchesOfficial": true
+    },
+    "src/utils/options.ts": {
+      "sha256": "d974a3a29c616919ca709e3855a0fea5200ab45d1b7985f0e52027b6af90830b",
+      "installedMatchesOfficial": true
+    },
+    "dist/utils/options.d.ts": {
+      "sha256": "ad023980c98a326645b90ed28453dc025dea406e4964d482ab3c78f8146962b2",
+      "installedMatchesOfficial": true
+    }
+  }
+}

package/docs/openzeppelin-integration.md

@@ -0,0 +1,115 @@
+# OpenZeppelin without project patches
+
+GateTool prepares ordinary EVM CREATE2 deployment, UUPS placeholder deployment and
+UUPS upgrades, and ordinary EVM OZ 5 Transparent/ProxyAdmin deployment and
+upgrades using official OpenZeppelin packages. Old `deployProxy({ create2Factory, postDeployCalls,
+transferOwnership })` extensions are rejected, not monkey-patched or translated.
+The baseline in `openzeppelin-baseline.json` records official npm 3.9.1 file hashes.
+
+| Capability | Preparation / execution owner | Required evidence |
+| --- | --- | --- |
+| CREATE2 constructor arguments | `workflow.prepareWorkflow`, `core/preparation/evm` | artifact, encoded constructor, initCodeHash, predicted address/policy |
+| UUPS first deployment | same API, `workflow/steps/deploy` | official implementation safety, implementation + proxy + first upgrade/init in one controlled Multicall |
+| Transparent first deployment | same API, `workflow/steps/deploy` | official safety; CREATE2 constructor binds implementation, explicit admin owner and initialization; internal ProxyAdmin identity/runtime/owner |
+| Transparent upgrade | same API, `workflow/steps/upgrade` | registered transparent layout; ProxyAdmin `upgradeAndCall`; separate business/admin authority |
+| UUPS upgrade | same API, `workflow/steps/upgrade` | official implementation/storage/namespace safety, explicit target manifest/current implementation |
+| Post-deploy calls / ownership | explicit workflow call steps / controlled Multicall | ordered target/value/calldata, owner assertions and locked envelope |
+| Existing code | preparation runtime check + execution CheckCode/manifest/registry | compiled identity, ERC1967 implementation, target layout and registration |
+| Registration | `prepareEvmManifestCandidate` + transactional merge | actual receipts; no invented deployment hashes |
+
+## Read-only script API
+
+Use `gate-evm-tools/deployment-evm` (CJS, ESM and TypeScript). This is a thin facade
+of the established `gate-evm-tools/workflow` preparation engine and the shared
+Multicall composer; it does not read a private key, select a signer or broadcast.
+
+```ts
+import { prepareWorkflow, prepareControlledMulticallTransaction }
+  from 'gate-evm-tools/deployment-evm';
+
+const common = {
+  version: 1, scheme: 'evm', network: hre.network.name, target: 'dev',
+  contract: 'Vault', constructorArgs: [], factory,
+};
+const plain = await prepareWorkflow(hre, {
+  ...common, kind: 'create2-deploy', contract: 'Token', constructorArgs: [supply],
+  salt, addressPolicy: { expectedAddress },
+});
+const initial = await prepareWorkflow(hre, {
+  ...common, kind: 'uups-placeholder-deploy', proxyKind: 'uups',
+  implementationSalt, proxySalt, placeholderImplementation,
+  call: { method: 'initialize', args: [businessOwner] },
+});
+const upgrade = await prepareWorkflow(hre, {
+  ...common, kind: 'uups-upgrade', proxyKind: 'uups', proxy,
+  contract: 'VaultV2', implementationSalt: nextImplementationSalt,
+  call: { method: 'initializeV2', args: [limit] },
+});
+const envelope = prepareControlledMulticallTransaction(controlledMulticall, [
+  ...initial.transactions.map(tx => ({ target: tx.to, value: tx.value, data: tx.data })),
+  { target: proxy, value: '0', data: vault.encodeFunctionData('setLimit', [limit]) },
+  { target: proxy, value: '0', data: vault.encodeFunctionData('transferOwnership', [finalOwner]) },
+]);
+// envelope: target, value, data, operation:0, method, calls. Never automatically sent.
+```
+
+All example addresses, salts and business values must come from the project plan.
+For the post-call example initialize `businessOwner` to the controlled Multicall
+only when that is the intended temporary authority; `msg.sender` of inner calls is
+the Multicall, not the outer EOA. Set the business configuration before transferring
+ownership. Never default a business owner to the first Hardhat signer.
+Nonzero inner values select `aggregate3Value`; the outer value is their exact sum.
+Every call has `allowFailure:false`. A failure reverts the complete batch. If an
+atomic operation is required, do not send the individual prepared transactions.
+The existing execution engine also checks facility identity and authorization.
+
+This low-level envelope alone is not a production approval. In new full projects use `gate-tool delivery setup` and
+the delivery inputs. Represent business calls and final owner/config assertions
+in that plan so simulation, locked hash, export, execution and recovery consume
+the same calls. No new unbound `postDeployCalls` plan field is introduced.
+
+Developers execute dev, then finish and freeze prod inputs using the completed
+code and dev evidence. Administrators consume that frozen prod release, selecting
+only execution identity: authorized execution or calldata export. They do not
+re-enter business parameters. Network configuration, business inputs, manifests
+(`.openzeppelin.dev` / `.openzeppelin`) and `contractInfo.json` belong to the
+project. Preparation does not update them; validated execution receipts and
+transactional registration do. New full has a `gateflow-evm-full@1` marker and shares delivery with core. Old `template: full` projects are not adopted by setup.
+
+Local package acceptance and supported-runtime limits are recorded in
+[the acceptance report](openzeppelin-acceptance.md).
+
+## Transparent proxy inputs
+
+For ordinary EVM with the locked OZ Contracts 5, preparation accepts:
+
+```ts
+const transparent = await prepareWorkflow(hre, {
+  ...common, kind: 'transparent-deploy', proxyKind: 'transparent',
+  implementationSalt, proxySalt, proxyAdminOwner,
+  call: { method: 'initialize', args: [businessOwner] },
+});
+const upgrade = await prepareWorkflow(hre, {
+  ...common, kind: 'transparent-upgrade', proxyKind: 'transparent',
+  proxy, proxyAdmin: transparent.proxyAdmin.address, proxyAdminOwner,
+  contract: 'VaultV2', implementationSalt: nextImplementationSalt,
+  call: { method: 'initializeV2', args: [limit] },
+});
+```
+
+Workflow deploy uses `upgradeableStrategy: 'transparent-proxy'` with
+`proxy: {kind:'transparent',adminOwner,initializer:'initialize'}` and business
+initializer `args`. Workflow upgrade uses an explicit transparent proxy object
+with `address` or `name` and `adminOwner`. Do not set `firstUpgrade` or an UUPS
+placeholder. An explicit `initializer:false` is only appropriate when the
+confirmed contract design needs no initialization or provides atomic completion.
+
+The official proxy creates its own ProxyAdmin at CREATE nonce 1. Preparation
+binds this address and expected owner. Verification checks both the ERC1967
+admin slot and immutable admin, proxy/admin runtime and admin interface version.
+The business owner and ProxyAdmin owner are separate frozen business inputs;
+upgrades target ProxyAdmin, with executor authority read from ProxyAdmin.
+CheckCode checks implementation, `<alias>_Proxy` and `<alias>_ProxyAdmin`.
+Target sync requires `proxyKind:'transparent'`, `proxyAdminAddress` and
+`proxyAdminOwner` (CLI: `--proxy-kind`, `--proxy-admin-address`,
+`--proxy-admin-owner`). This path does not support zkSync or legacy OZ proxies.