gate-evm-tools 1.0.28 → 1.0.31

package/docs/delivery-custom-input-closure.md

@@ -0,0 +1,51 @@
+# Custom planning input closure (policy `gate-custom-cjs@1`)
+
+This layer captures the actual selected custom modules, their supported static runtime graph, configuration reads, business file reads, and installed npm packages. `CustomEvidence.closure` records each evaluation's contribution; `DeliveryPlan.customInputClosure` binds the session's union into `planHash`. Native-only plans carry `null` and never initialize this loader. Ordered `resolve` observations, including changing workflow state, remain separate from immutable file inputs.
+
+This is supported-code validation and controlled evaluation. It is not sound analysis of arbitrary JavaScript, a hostile-code sandbox, a same-UID filesystem boundary, a complete toolchain/artifact/public-configuration freeze, or `release_ready`. Compiler/artifact/OZ-layout/public-configuration and aggregate freeze belong to Task 5c.1c; durable execution and lifecycle/release qualification remain later tasks.
+
+## Sources and evaluation
+
+The actual selected step's `script` is a project-relative root. The TypeScript 5.9.3 AST follows imports, side-effect imports, re-exports, literal `import = require`, and direct literal `require`, including statically visible calls in branches that never execute. Explicit type-only edges are excluded. Caller-declared files are permissions for business ports, not graph-completeness declarations.
+
+Project `.ts`, `.cts`, `.js`, `.cjs`, and imported `.json` are supported. Extensionless relative imports must have exactly one regular target among the literal name, the supported extensions, and `index` with those extensions. Explicit extensions select exactly that file. Missing or ambiguous candidates fail; there is no `.js` to `.ts` substitution, directory `package.json` main adapter, or TypeScript type-resolution authority. Module source format follows captured nearest `package.json` metadata; native `.mjs`, `.d.ts` runtime targets, `.js`/`.ts` under `type: module`, and TypeScript runtime files inside packages are unsupported.
+
+Captured bytes are transpiled with fixed CommonJS, isolated-module, JSON interop, no helper-package injection, LF and no source-map options. The exact effective options, TypeScript version and emitted-JavaScript hashes are evidence. Source/data bytes and emitted JavaScript remain in the collector's private memory for controlled evaluation. Host `require` is never used to evaluate project or dependency code. Each session owns a VM context, frozen importer-to-target edges and a private CJS module cache. Cycles publish partial exports before evaluating the dependency, matching CJS semantics. Failed initializers are removed from the module cache while successfully loaded dependencies remain cached; an importer that catches the error can retry initialization from the same captured bytes. A graph-collection failure or an initializer error escaping the root loader makes the session terminal and cannot be sealed as a successful closure.
+
+The supported subset rejects nonliteral/aliased loaders, runtime `import()`, `require.resolve/cache/extensions`, `module` access other than `module.exports`, `createRequire`, generated code, reflective constructor/prototype access, nonliteral computed property access, and ambient APIs. Thus ordinary deterministic helpers using direct fields, destructuring, literal indexing and array methods work; arbitrary dynamic indexing requires a future reviewed adapter. Filesystem, subprocess, network, environment, argv/cwd, clocks, randomness, native addons and HRE/signer/RPC access are unavailable. Broad `ethers` or Hardhat imports can fail because their reachable code uses those capabilities. No ambient capability is granted to make such imports pass.
+
+Only this collector's known VM Object/Array prototypes and ordinary host own-data prototypes are normalized. Normalization checks descriptors, symbols, dense arrays and cycles; it never uses getter execution, `toJSON`, or JSON stringify coercion to accept a foreign object. Returned business data and planning results are immutable.
+
+## Business data and configuration
+
+`readJson` and `readBytes` require declared file names confined to the task/business root, itself inside the project. Their exact project paths and byte digests bind into both observations and closure files. No directory or glob port exists. Imports and ports both reject traversal/escape, symlink components, hardlinks and nonregular leaves. The project-files boundary checks the lexical path before following it; a business-root symlink cannot disappear through `realpath` normalization.
+
+Session construction, target rebinding and owned-session checks validate the business directory before normalization, even when no file port is used. Lexical `.`/`..` components, outside roots and existing symlink/non-directory components reject. The supplied project-root spelling and its canonical realpath are accepted aliases (including macOS temporary-directory aliases); an unused task directory may be absent.
+
+The shared path policy denies credentials (`.env*`, `.npmrc`, keys, wallets, certificates), generated reports/status/results/releases/handoffs/manifests, deployment state and private deployment configuration, `.gate-template.json`, raw lockfiles, and project generated/cache directories. Package code may live in its own `dist` tree, but importing sensitive files is still forbidden. Public configuration/provenance will use a separate projection, not raw business reads.
+
+The root `tsconfig.json` is read with TypeScript JSONC parsing and compiler-option conversion through confined captured reads. Local `extends` and explicit package JSON subpaths (for example `@tsconfig/node16/tsconfig.json`) join the closure; package extends require the same lock/payload identity as runtime packages. Single-string extends is supported; external extends, extends arrays, package-directory config discovery, aliases/baseUrl/rootDirs/moduleSuffixes, custom conditions, transformers/plugins/decorators/JSX and ts-node compiler/transpiler hooks are unsupported. Runtime target, `esModuleInterop` and class-field semantics are honored; other accepted type-check/build settings cannot override the fixed transpile-only loader options. An absent config has explicit deterministic ES2022/CommonJS defaults and its absence is rechecked. Nearest package metadata and absence of closer metadata are also rechecked.
+
+Every config file inside a package is attributed by its physical project-relative location, including `./node_modules/pkg/tsconfig.json`, package-local relative parents and relative paths into another package. Spelling a package config as a relative path does not omit its lock or complete installed payload identity.
+
+## npm package identity
+
+Every bare specifier resolves from its actual importer using the running Node version's default CJS resolver, in a fresh Node child with an empty environment and `--preserve-symlinks`. Node's exports/conditions are authoritative. Evidence records the exact Node version and resolver policy/flag, including the version's default conditions such as `module-sync` and `node-addons`; it does not pretend that only `require`/`node`/`default` exist. Fresh children avoid stale host path/package-json caches at sealing.
+
+Package-internal relative edges also use Node CJS extension/index/main resolution; the project-only ambiguity policy does not replace Node package semantics. The selected runtime file must be inside a regular local npm package. Nested duplicate and hoisted/peer dependencies have their own physical project-relative `lockLocation`; ancestor/global packages, NODE_PATH, custom conditions, absolute/file/http specifiers, `#imports`, workspace/directory links, PnP, and native/ESM-only loaders are unsupported. Local npm lock v2/v3 entries must match installed package name/version, have a supported integrity value and registry or `file:...tgz` source, and not be linked/extraneous.
+
+Each used package binds package metadata digest, `type/main/exports/imports`, lock location, name/version/integrity, safe source identity, and the complete current unpacked payload: sorted portable regular-file paths and byte hashes. Nested `node_modules` are independent identities, never merged into the parent payload. There is no blanket omission of dotfiles, documentation, tests or unused payload files. Symlinks, hardlinked/nonregular payload files and native addons fail.
+
+Tarball SRI identifies the locked tarball; it does **not** prove installed bytes. The installed payload digest is an independent identity. Local tarball source evidence uses its SRI-derived content identity, never its host path. Registry source URLs are represented only by opaque hashes. No resolved URL, credential-bearing lock metadata, `.npmrc`, full lockfile, or absolute path is exported.
+
+The only host preload adapter is exactly `-r ts-node/register` (or `--require`), locally installed ts-node 10.9.2 and Hardhat 2.26.3 with matching local lock versions, the actual loaded local register entry and its byte digest, and captured package metadata identities. Companion preloads, loader/condition switches, NODE_OPTIONS/NODE_PATH and TS_NODE selectors fail. The adapter's host HRE bootstrap is trusted; custom code still uses the private loader. Full adapter/toolchain payload identity belongs to 5c.1c.
+
+## Sealing and replay
+
+`CustomPlanningSession.sealClosure()` rehashes all captured inputs, re-resolves every edge, checks previously absent config/metadata paths, and re-enumerates every package payload. Newly closer dependencies, newly ambiguous relative candidates and added/removed unused package files therefore invalidate the session even when previously selected file bytes stayed unchanged. These are ordinary before/after drift checks, not an atomic filesystem snapshot against a hostile writer.
+
+A session accumulates roots from actual evaluations. `forTarget()` creates target-specific ports sharing that same private immutable-input collector; later roots and data cannot be excluded by passing a caller list. The collection checks the complete union after identity revalidation and again after the asynchronous fork audit. Replay recollects/evaluates current files and compares the canonical plan; changed unexecuted helpers change the plan identity. Evidence is portable across checkout roots, uses sorted canonical framed JSON, and excludes absolute paths and mtimes. There is no detached/offline source-execution replay API in this unit.
+
+Injected sessions must be collector-owned and bound to the collection's project/business root. The launcher calls private captured operations, so replacing a genuine object's public `evaluate` or `sealClosure` methods cannot forge evidence. A self-consistent fake session or fake evidence cannot qualify collection. Pure parsers validate persisted structure/hash relationships; they do not attest to filesystem collection by themselves.
+
+Closure parsing requires actual string fields and one edge per `(importer, specifier, kind)` key; identical and conflicting duplicates both reject. Roots and runtime importers must be modules, and runtime targets must be modules or imported JSON. Config edges and the compiler config reference must identify config JSON; a config also imported at runtime retains the `json` file kind and remains a valid config endpoint.

package/docs/delivery-development.md

@@ -0,0 +1,32 @@
+# Tool-side development delivery
+
+`gate-evm-tools/delivery-development` exports `createDevelopmentDelivery`. It connects an actual development `collectDeliveryAggregate` result to the existing EOA execution store, read-only business verification, recoverable project materialization, and actual CheckCode. This is the tool-side development entry; GateFlow host authorization, production orchestration, Safe execution, and release publication are separate work.
+
+```ts
+const aggregate = await collectDeliveryAggregate(source); // selection: 'development'
+// Persist source + aggregate before sending. Resume with those original bytes.
+const delivery = await createDevelopmentDelivery({
+  root: projectRoot, source, aggregate, target: 'localDev', hre,
+  execution: { context, store, signer, approval },
+});
+const result = await delivery.continue({ unsigned });
+// Each call may sign/send one original operator transaction. Host supplies the
+// complete type 0/1/2 envelope (nonce, gas and all fee fields); no defaults.
+const progress = await delivery.continue();
+```
+
+Use the actual project HRE loaded for the named target. Its provider is used for both execution and verification; fork HREs and fabricated HRE replacements are refused. The context is the existing EOA execution context, with immutable plan/execution/operator/chain/target identity and explicit host policy/finality. The host-injected approval capability remains mandatory for signing. Configured target confirmations are a minimum. The lifecycle does not reevaluate business modules or parameter producers to send transactions.
+
+The method first reconciles the original durable transaction prefix. Unfinished external execution returns `waiting-external-execution`; callers can supply an explicit `hashReferences` map. Contract executors remain unsupported by the EOA observer. Missing receipts/finality remain pending. Reverted/blocked execution cannot produce acceptance.
+
+After finality, all frozen manifest/native or emitted custom `check` calls run through the shared verify engine using `staticCall`. An empty assertion collection is not business acceptance. Assertion IDs, order, methods, ABI, addresses, typed arguments, definitions and expected values are checked against the sealed collection. Current eligible source, input files, installed runtime, effective HRE, artifacts and provider chain are rechecked.
+
+Successful assertions permit materialization of `contractInfo.json`, `deploymentInfo.json`, an explicit per-execution `deployment.json`, and the official selected-target OpenZeppelin manifest for UUPS. The native adapter checks actual deployed bytecode, ERC-1967 implementation, official validation data and layout. Registry merges preserve unrelated entries and reject same-instance/base conflicts.
+
+`.gate-delivery/materialization/<executionId>.json` contains the exact old/new bytes and hashes for the multi-file intent. A SQLite transaction holds the process mutex; files and intent are atomically renamed and fsynced. The `prepared` journal is durable before the first project-file replacement. Recovery accepts only recognized old/new bytes, finishes remaining file writes, and marks `committed`. A process crash releases the mutex automatically. Conflicting edits or invalid journals fail closed. Do not delete these journals to retry a deployment.
+
+CheckCode runs `npm run compile -- --network <target>` and the installed local `gate-tool check --scheme evm --network <target> --config <effective> --output <raw>`. Each new attempt gets a unique private directory. Actual artifacts are checked before and after both compilations. The current raw report must have exactly the expected selected-network keys, matching scheme/contract/address, `matches: true` and `error: null`. UUPS requires both the business implementation entry and `<Alias>_Proxy`.
+
+An `accepted` result includes finalized transaction observations, complete business assertions, materialization identity, official manifest evidence, and CheckCode raw/registry/metadata/effective/artifact hashes. It is persisted at `.gate-delivery/development/<executionId>.acceptance.json`. Repeated `continue()` revalidates saved evidence and original finality without signing, sending, or rerunning completed CheckCode. Raw tampering is an error, not a new successful check.
+
+The targeted crash test covers process death after a file rename. It is not an experimental power-loss guarantee. Filesystem durability depends on the platform honoring `fsync` and atomic rename semantics. The entry is for the installed new-core project/runtime; it performs no unrelated legacy migration.

package/docs/delivery-eoa.md

@@ -0,0 +1,46 @@
+# Delivery EOA execution kernel
+
+`gate-evm-tools/delivery-eoa` consumes the existing immutable `DeliveryPlan` and shared private `ExecutionStore`. It requires the delivery toolchain's ethers 6 and Node `^22.13.0 || ^24.0.0`. It is an injected execution kernel for a trusted host, not the production host, Safe support, development acceptance, or release readiness. `delivery-export` remains independent and does not import this entry.
+
+The host supplies the RPC transport, immutable execution context (plan, release, operator, target, chain and policy identities, explicit finality policy), a **sign-only** signer, and an approval capability. These implementations must come from controlled host code. Agent-generated code and user JSON such as `authorized: true` must never be accepted as implementations or permission. The old combined custody sign/send API is unsuitable here.
+
+```ts
+const execution = createDeliveryEoaExecution({
+  plan,
+  context: {
+    executionId: plan.executionId, planHash: plan.planHash,
+    chainId: plan.chainId, target: plan.target, operator: plan.operator,
+    releaseHash: hostReleaseHash, policyHash: hostPolicyHash,
+    finality: { kind: 'confirmations', depth: '12' },
+    // Or { kind: 'rpc_finalized' }; unsupported RPC never falls back.
+  },
+  store, // openExecutionStore({ trustedRoot: hostSharedPrivateRoot })
+  provider: { request: (method, params) => hostRpc.send(method, [...params]) },
+  signer: hostSignOnlySigner,
+  approval: hostApprovalCapability,
+});
+await execution.execute(completeUnsignedEnvelope);
+await execution.reconcile({ [externalTransactionId]: [explicitTransactionHash] });
+const artifact = await execution.export();
+```
+
+`execute` handles one active contiguous operator transaction. Supply every `UnsignedEnvelope` field, including decimal-string nonce, gas, fees, exact value/data, explicit transaction type and access list; inapplicable fees are explicitly `null`. Types 0, 1 and 2 and EOA `operation: 0` are supported. Chain, signer and full envelope are verified against the plan. The signer must match the approved operator, and the executor must have empty code. No business script reruns, route changes, implicit export, or gas/nonce defaults occur.
+
+The store freezes and reserves the envelope before the approval capability receives its complete immutable snapshot: context, exact plan transaction, frozen envelope and deterministic signing request ID. This snapshot is reproducible from the immutable context (bound by the durable context hash), durable plan and frozen envelope. The request ID commits to all those fields and cannot change after intent. `withApproval(snapshot, controlledWork)` must validate the whole snapshot and **await** `controlledWork()` while its authority remains active. Throw to deny. The kernel fences continuation if the approval scope ends during awaited signing. The store's lifetime claim remains held through all controlled work.
+
+`sign(requestId, unsigned)` must only sign and durably retain its result under that ID. It must never broadcast. The kernel records signing intent first, decodes the actual signed RLP, recovers the signer, compares every frozen field using exact quantities, and durably commits the original bytes/hash before recording submission intent and calling `eth_sendRawTransaction`. A wrong returned hash is an error and never changes the original identity.
+
+Recovery is deliberately finite:
+
+- `signing`: only `signer.recover(requestId)` may retrieve the original result. This is a read-only lookup, never fresh signing. Missing recovery returns `signing-result-unavailable`.
+- `signed`: after renewed exact approval/validation, submit the durable original bytes once.
+- `submission-uncertain` or `included-unfinalized`: query only the original hash; missing transaction/receipt remains pending. Never resign or resend, even if submission intent was recorded just before a process died without sending.
+- External work: provide explicit hash sets by transaction ID to `reconcile`. It never scans blocks. More than one matching included hash is ambiguous and requires a single reference.
+
+`observeEoaTransaction` is a read-only producer for controlled hosts. It verifies RPC chain, full transaction/receipt identity, exact value/data, canonical block height/hash/index inclusion, executor code at that block, and the configured finality. Operator records additionally match the complete frozen envelope and original signature. Missing transactions, receipts or canonical blocks never prove success. Reverts never advance the prefix. Unknown permissions, unavailable signers, unsupported executors/operations, RPC failures and verification mismatches produce explicit errors; they do not authorize another route.
+
+Only finalized success advances the contiguous prefix. A transaction hash cannot complete two entries, even if their calls are identical. Unfinalized observations can be reread after reorg/reblock. Every later execution, advancement and trusted-progress export rechecks already-finalized observations; loss of canonical finalized evidence permanently blocks this execution in the store. A transport exception stops the current call without inventing a finality loss. There is no automatic unblock, resubmission, block scanner, persistent scan checkpoint, or Safe adapter.
+
+The store's business schema advances from version 1 to version 2 by adding only nullable `executions.blocked_reason`. The verified version 1 schema, existing records, original byte identities and nonce reservations are retained inside the same transactional migration. The authority database/protocol is unchanged. `blockExecution` is a structural store operation for trusted verifiers, not independent chain proof.
+
+The focused test `test/delivery-eoa.test.mjs` covers actual ethers signatures, precision, controlled approval/send ordering, hash verification, finality loss and the three new signing/submission process crash boundaries. `test/integration/delivery-eoa.test.mjs` runs one disposable local EOA operator → external-hash → operator scenario with transfers and no contract compilation. These checks do not imply real-chain acceptance or production-host authorization.

package/docs/delivery-evm-manifest.md

@@ -0,0 +1,20 @@
+# EVM explicit target manifest seam
+
+`syncWithHre(options, hre, root)` routes EVM requests with `target` to the explicit project registry. The root must match the HRE project, the network and target must match the active HRE network, and the configured chain ID must match the provider. `config.yaml` selects `.openzeppelin.dev` or the configured production directory. A provider's Hardhat/Anvil metadata does not redirect this path to an OS temporary manifest. No-target EVM sync retains its legacy implementation.
+
+Sync compiles and validates the candidate with official OpenZeppelin `getDeployData` and `assertUpgradeSafe`, reads the real ERC-1967 implementation, checks proxy/implementation code, and matches the artifact runtime using compiler immutable references. Reads use the active HRE provider. The implementation key is `version.linkedWithoutMetadata`, including encoded constructor arguments. Layout evidence is the full canonical SHA-256, including namespaces and nested metadata.
+
+The existing manifest transaction confines paths, rejects simultaneous canonical/fallback files, and restores original filenames and bytes after ordinary failures. Sync preserves unrelated implementations, admin and proxy kinds; a conflicting proxy kind or same-version layout is refused. A second implementation address for the same version is added to `allAddresses`, preserving the original primary address and deployment hash. A supplied transaction hash fills a missing deployment hash only when its successful receipt proves creation of that implementation. Upgrade receipts are never used for that field. `skipTxHash` skips receipt lookup; immutable workflow evidence binds the actual upgrade receipt separately.
+
+Canonical EVM UUPS preparation reads the registered UUPS proxy and current implementation layout from the explicit target registry before calling `assertStorageUpgradeSafe`. It uses official implementation validation and the full namespace-aware layout. It refuses missing baselines. The low-level adapter's documented validation/evidence dependency is a test seam; `prepareWorkflow` always uses the official default and has no request field to bypass storage checks.
+
+Run the packed integration fixture from EvmGateTools:
+
+```sh
+npm run build
+node --test test/integration/evm-target-manifest.test.mjs
+```
+
+The fixture generates a core project through the sibling generator, installs actual packed dependencies offline, and starts an ordinary loopback Hardhat node. It deploys V1/proxy directly for this seam test, syncs dev and prod in separate processes on chain 31337, checks official version/layout/namespace evidence, repeats sync with a same-version deployment, and prepares compatible V2. Ordinary and namespaced incompatible storage and unsafe implementation validation are rejected. Preparation preserves manifests, file inventory and block height; the OpenZeppelin temporary manifest remains untouched. Focused unit tests cover rollback, fallback migration, conflicts, path refusal and receipt semantics.
+
+This acceptance does not establish the full CREATE2/multicall lifecycle, execution engine, journal-provided baselines, release readiness, or crash-durable registry promotion. Those are separate delivery tasks.

package/docs/delivery-execution-store.md

@@ -0,0 +1,33 @@
+# Delivery export and durable execution records
+
+`gate-evm-tools/delivery-export` exports the existing immutable `DeliveryPlan` without running business code, preparation, execution, HRE, a signer or a provider. `renderDeliveryExport(plan)` is synchronous and has no filesystem or chain effects. JSON and Markdown contain the same complete canonical model, including all transactions, references and total-order dependencies, plus a separate current contiguous route/executor segment. Success means artifact delivery, not deployment or release readiness.
+
+Completed progress requires `validateDeliveryProgress({plan, completed, finalized})`, where `completed` contains observation references and `finalized.readFinalized` is a trusted host-owned canonical/finality query. Its live opaque result can be passed to `renderDeliveryExport`. Serialization or copying loses provenance. `exportDelivery` is a convenience wrapper that resolves provenance before rendering. Structural plan/receipt parsing grants no host authorization. No release binding is invented here.
+
+`gate-evm-tools/delivery-execution-store` lazily loads `node:sqlite` when `openExecutionStore` is called and requires Node `^22.13.0 || ^24.0.0`. Global package engines are unchanged. The trusted host and CLI must select the **same private local store root across projects and environments**. No project-local default or network filesystem support is provided. The root must be a canonical absolute path without symlink components, owned by the user with mode 0700. A missing final directory can be created only beneath a private parent. Fixed 0600 database files cannot be replaced, linked or aliased.
+
+The store keeps a private `authority.sqlite` BEGIN IMMEDIATE lock across the complete awaited claim callback. One session runs globally, including across different nonces. A timeout reports busy; it never grants takeover. Short business commits use a distinct `execution.sqlite`, DELETE journaling, synchronous EXTRA, macOS fullfsync and strict directory synchronization. A UUID and initializing/ready bootstrap marker distinguish interrupted initialization from a missing/truncated established database. SQLite owns hot-journal recovery; this implementation never deletes journals or replaces the authority inode.
+
+Typical host flow:
+
+```ts
+const store = await openExecutionStore({ trustedRoot: hostSharedStoreRoot });
+const previous = await store.readExecution(plan.executionId);
+await store.withExecutionClaim({
+  plan, contextHash: immutableHostContextHash,
+  expectedRevision: previous?.revision ?? null,
+}, async (claim, snapshot) => {
+  snapshot = store.freezeAndReserve(claim, snapshot.revision, transactionId, unsigned);
+  // Later signing/broadcast adapters must be awaited inside this scope.
+});
+```
+
+`contextHash` identifies immutable execution context, independently of transaction approval. Each transaction freezes its own full unsigned envelope and digest without resealing the business plan. The same execution can wait for external finalized progress and freeze a later transaction. Reservations are permanent and unique by exact canonical chain/signer/nonce across all aliases, environments and executions in this store. Chain, nonce, value, gas, fees, heights, revisions and epochs use decimal strings/BigInt; bounded transaction indexes and types remain numbers.
+
+Every mutation requires the original live claim, current revision/epoch and active transaction. Callback settlement/failure revokes the claim and closes its original connections. `markSigning` persists intent once; reopened signing uncertainty is **not permission to sign again**. `commitSigned` stores exactly one canonical byte record. It does not decode the signature, recover the signer or certify that the bytes match the unsigned envelope. `recordSubmissionIntent` persists uncertainty; it does not send or authorize resend. Signing, cryptographic checks, broadcasting and EOA/Safe reconciliation belong to subsequent units.
+
+`recordObservation` accepts an observation reference and a trusted host-owned `readObservation` port, not caller JSON. The port must establish transaction identity, canonical inclusion, execution outcome and configured finality. Only finalized success advances the contiguous prefix; inclusion and revert never permit skipping. Port implementations and signing approvals must not be supplied by agent-generated code. Store snapshots are data, not proof of chain finality or send capabilities.
+
+A SQL commit/directory-sync error may leave the original record committed. The live claim is fenced and no durable result is returned; recovery reacquires the lock and rereads original identities, nonce reservations and signed bytes. Do not infer an absent receipt or an uncertain response permits another signature. Tests cover actual process crashes, kernel locking and response loss; they are not power-loss experiments. Durability relies on the documented local-filesystem locking/sync contract.
+
+EOA signing and trusted hash reconciliation are provided separately by [`delivery-eoa`](delivery-eoa.md). Business schema version 2 adds a durable execution-level finality block while retaining version 1 records and reservations; the authority protocol is unchanged. `blockedReason` prevents further mutations after a trusted verifier detects lost finalized progress.

package/docs/delivery-inputs.md

@@ -0,0 +1,46 @@
+# Owned delivery business inputs
+
+`gate-evm-tools/delivery-inputs` reads an actual core-project handoff and its business files. It provides an immutable business-input snapshot and owned parameter receipts. It does **not** qualify an aggregate plan, grant an execution action, or create a release. Full effective config/HRE correspondence, runtime package identity and the multi-target staging owner are separate gates.
+
+```ts
+import { openDeliveryInputs, consumeDeliveryInputParameters } from 'gate-evm-tools/delivery-inputs';
+
+const inputs = openDeliveryInputs({
+  workspaceRoot: '/workspace',
+  projectRoot: 'contracts/vault',
+  request, // The strict delivery request identifying the actual handoff invocation.
+  selection: 'development',
+});
+const parameters = inputs.values('localDev'); // Immutable planning inputs.
+const receipt = inputs.parameters('localDev');
+const evidence = inputs.seal(); // Terminal rereads only; no producer invocation.
+const sameParameters = consumeDeliveryInputParameters(receipt);
+```
+
+The handoff invocation supplies `deploymentId`, `developmentNetwork` and `releaseTargetNetworks`. The reader derives `scripts/tasks/<deploymentId>/`, the ordered manifest steps, upstream canonical definitions and the selected target set. It accepts no caller steps, hashes, source roots, target objects, parameter overrides or pre-parsed documents. Canonical definitions exclude progress and unrelated tasks. Final rereading checks the current invocation's eligibility and the same business definitions. Dependencies may refer to another deployment package in the same project.
+
+`selection: 'development'` requires complete values and provenance for the development target only. `release` requires every declared production target; `all` requires development and every production target. Selection controls data coverage. It does not authorize any additional invocation, environment or target action.
+
+The new file contract is:
+
+| File below the task directory | Shape |
+| --- | --- |
+| `task.yaml` | `{version: 1, id, developmentNetwork, releaseTargetNetworks}`; must match the actual handoff deployment scope |
+| `manifest.yaml` | `{id, description?, steps}`; steps retain their source order |
+| `parameters.schema.json` | Strict draft-07 schema with the existing leaf policies |
+| `parameters.yaml` | `{params: {<target>: <complete values>}}` |
+| `parameters.provenance.json` | `{version: 1, producers, targets}` |
+
+Each producer definition is `{version, module}`. Its module is a confined project-relative path below this task, for example `scripts/tasks/vault/producers/salt.ts`. Each target provenance entry is `{manual, computed}`, using the existing path maps and exact observation shapes. Copy policies read from the same actual `parameters.yaml` document; there is no implicit global merge or `run.targets` override. A manual observation's `source` is only a source label, never proof of human approval.
+
+Before any producer runs, every source step passes the existing strict native parser or the pure custom-step structural parser. Runtime ABI/reference validation still belongs to the engine. Documents reject duplicate members, aliases, anchors, merge keys, non-string mapping keys, unsafe numeric values and non-JSON data. Files must be confined regular single-link files; symlinks and traversal are rejected. This tightens the new delivery input boundary; the previous YAML parser already rejected duplicate mapping keys.
+
+Producers export only synchronous `produce(inputs)`. Inputs are frozen strict JSON. The existing `CustomModuleClosure` owns loading, static dependencies, package resolution and returned-data normalization. There are no provider, state, environment or file-read ports. The actual output must match both the delivered computed observation and the parameter value. Each selected target resolves its envelope once with an isolated producer session. Evidence binds the actual input files, schema, target, producer ID/version/module, complete module closure, inputs/output and resolved envelope identity.
+
+`inputs.values()` and `inputs.parameters()` are available while the owner is open. A receipt becomes consumable only after `seal()` succeeds. Sealing rereads input files, handoff eligibility and producer closures without rerunning producers. A failed seal permanently revokes every receipt. Sealing twice and reading through a terminal handle are rejected. `close()` explicitly revokes receipts, including after a successful seal. A copied or self-consistent JSON receipt has no authority. These receipts are process-local; durable production transport is not implemented by this API.
+
+`snapshot.targets` contains only validated, frozen version-1 public targets: `id`, `network`, declared `chainId`, `environment`, `finality`, `openzeppelin`, and optional `admin`, `create2`, `uups`, `multicall`. CREATE2 supports `scheme`, `factory`, optional `leadingZeroBytes` and optional `caller`. Zero confirmations and zero leading bytes are retained; omitted fields remain absent. Invalid nulls and arbitrary extras are rejected. Business extensions belong in schema-checked parameters. `admin` and `create2.caller` are business addresses, not executor claims. Both native `$target` references and custom target declarations use the same scalar field boundary.
+
+Admin retains the shared engine's semantics: absence, a string that trims to empty, and a case-insensitive `deployer` select the execution signer; valid address strings (including zero) select that address. The public definition retains its original spelling/whitespace and absence so these inputs remain distinct. Invalid types, nulls and invalid checksums are rejected before engine use. Facility address rules remain separate.
+
+The public chain ID comes from the current project-owned Hardhat network declaration, with no network catalog. Config and business file evidence contains confined paths and digests, not RPC/account/header capabilities. This input module does not yet attest post-extender effective Hardhat settings. `businessInputHash` is deliberately named separately from the future aggregate `inputsHash`.

package/docs/delivery-parameters.md

@@ -0,0 +1,65 @@
+# Delivery parameter and native-operation validation
+
+This is the delivery-only development/consumption boundary. It does not replace legacy `resolveExecutionParameters(...overrides)`, qualify a release, or supply production parameters. Delivery requires the pinned ethers 6.15.0 runtime; this API makes no ethers 5 compatibility claim.
+
+## Development and consumption
+
+`gate-evm-tools/delivery-parameters` exports `resolveDeliveryParameters` and `consumeDeliveryParameters`. Development supplies the complete target `values`, including manual values and computed outputs. Resolution validates rather than filling defaults, choosing a wallet identity, or silently copying missing target values. The returned version-1 envelope and every nested value are immutable.
+
+The production consumer takes only the existing envelope and its independently supplied trusted `identity`. It revalidates schema, observations, provenance and the envelope hash, returns frozen values, and never invokes a producer. There are no overrides or fill-in arguments. The expected identity must come from the caller's trusted development evidence; hashing an arbitrary incoming envelope and trusting that same hash does not authenticate it.
+
+```ts
+const resolved = resolveDeliveryParameters({
+  target: 'prod',
+  schema: {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object', additionalProperties: false, required: ['enabled'],
+    properties: { enabled: { type: 'boolean', 'x-policy': { kind: 'manual' } } },
+  },
+  values: { enabled: false },
+  manual: { '/enabled': { source: 'review-42', value: false } },
+});
+const values = consumeDeliveryParameters(resolved, trustedDevelopmentIdentity);
+```
+
+Source/manual/computed observations and schema are included in the identity. These are business inputs, not a place for RPC URLs, account material, or secrets. Source files/modules/packages and the compiler, storage-layout and runtime aggregate identities are closed in later work. The producer registry and expected-identity input are versioned trusted seams, not independent production authority.
+
+## Schema and JSON policy
+
+Ajv 8.17.1 is a direct exact runtime dependency, with strict mode and all errors enabled. Coercion, defaults and removal of unknown properties are disabled. The only accepted dialect is the exact explicit URI `http://json-schema.org/draft-07/schema#`.
+
+Supported schema keywords are `$schema` (root only), `title`, `description`, `type`, `properties`, `required`, `additionalProperties`, `items`, `minItems`, `maxItems`, `uniqueItems`, `minProperties`, `maxProperties`, `enum`, `const`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`, `minLength`, `maxLength`, `pattern`, and `x-policy`. Each node requires one explicit type. Objects require a properties map and `additionalProperties:false`; arrays require a single item schema. Formats, defaults, `$ref`, composition/conditional schemas, tuple-schema item lists, pattern properties, and every other dialect/keyword are rejected. No hand-validator fallback exists.
+
+All JSON numbers, including schema numeric constraints, are safe integers. Fractional numbers, NaN, infinities, unsafe integers, bigint, undefined, cycles, sparse arrays, extra array properties, symbols, non-enumerable fields, getters and unsupported prototypes are rejected without invoking getters or `toJSON`. Use canonical decimal strings for large ABI integers. Plain objects and null-prototype objects are accepted; arrays require the ordinary array prototype.
+
+The general own-data copier preserves own `__proto__`, `constructor`, and `prototype` keys deterministically using property definitions. Parameter schema property names explicitly reject these three names because Ajv's generated treatment of `__proto__` is unsuitable for this policy. They are never silently ignored or used to mutate prototypes.
+
+## Per-leaf provenance
+
+`x-policy` has one exact shape:
+
+- `{kind:'copy', target:'dev', path:'/source/path'}`
+- `{kind:'manual'}`
+- `{kind:'computed', producer:'salt', version:'1'}`
+
+Policies inherit down objects and array items until a child overrides them. A copy policy's JSON pointer anchors at the node declaring it; descendant paths append relative segments, including concrete array indexes. Children explicitly marked manual/computed must provide their own observations even when their parent is copied. Empty containers count as leaves. Ambiguous schema composition is unsupported.
+
+Every actual leaf binds target, JSON pointer, policy and value hash. Copy observations additionally bind source target, source pointer, source leaf content and entire source-target identity, and compare the actual source value. Manual observations are keyed by target JSON pointer and have `{source, value}`; the source identifier must be nonempty and the value must match. Computed observations have `{producer, version, inputs, output}` and bind input/output identities. Development invokes the trusted registry's matching versioned producer over frozen inputs and compares its actual output. Unused manual/computed observations fail. Production verifies existing observations and identities without recomputation.
+
+## Business references and ABI validation
+
+Business references use `$param.path`, `$target.path`, `$state.path`, or an exact `{$ref:'param.path'}` / `target.path` / `state.path` object. Dot-separated segments contain only ASCII letters, digits, `_`, or `-`; numeric segments index arrays. Unknown namespaces, extra `$ref` fields, missing/undefined values, accessors and reference cycles fail. Referenced values are resolved recursively. Each resolution reads at most one state snapshot, safely traverses own enumerable data descriptors, and strictly validates the selected subtree. Unrelated optional runtime metadata may be undefined; a referenced undefined, accessor, non-plain or cyclic value still fails. Observation identities hash the selected source subtree and its resolved value. Schema `$ref` has no relationship to this syntax and is unsupported.
+
+Public target references are scalar leaves only: `id`, `environment`, `chainId`, `admin`, `create2.scheme`, `create2.factory`, `uups.placeholderImplementation`, and `multicall.controlledMulticall`. The resolver never traverses or hashes the other target fields. Each resolved reference records its namespace/path and actual source/resolved content identities. `runDeliverySteps` returns immutable reference observations; `collectDeliveryPlan` exposes them by source step in `runtimeEvidence.references`. They remain internal evidence, not a release seal.
+
+One ethers-parsed recursive ABI validator handles constructor/init/upgrade/call/view/check arguments and check expectations. Booleans must be booleans; integers accept safe integer numbers or canonical decimal strings and use exact BigInt ranges. Addresses must be valid EVM addresses; bytes are even hex with exact fixed sizes. Arrays enforce fixed lengths. Tuples accept positional arrays or exact named own-data objects with unique nonempty ABI names. Missing/extra arguments and fields fail. Runtime bigint and ethers Result values cross an explicit normalization function; arbitrary objects are never converted with `String`/`toString`.
+
+## Execution and preparation guarantees
+
+Delivery always installs its own validation adapter, replacing any caller-provided no-op shared port. Collection preflights the complete known native source list before sending. Each custom module's complete emitted list is independently preflighted before its first operation. Future custom modules are not executed speculatively. Static preflight resolves immutable params/target references and defers state-reference values without reading state. Methods, the outer argument count, known sibling values and known array/tuple shapes are still checked. An individual argument or nested tuple/array may come from future state; the entire outer argument list must have known shape. Final resolved arguments, check expectations and values validate again before encoding/invoking/sending.
+
+Artifact ABI comes from the explicit runtime artifact reader, never an address resolver. The optional neutral core hook checks a detached actual artifact after compilation, before constructor or initializer encoding. Fresh, expected-replay and disk preparation paths all rederive semantics before evidence is journaled or transactions are planned/sent. Reuse never reruns fresh preparation, compilation, or deployment-status selection.
+
+Supplied CREATE2 fields validate independently of constructor availability, including effective redeploy-policy fields. Factory, salt, expected address and leading-zero types/ranges cannot hide behind a deferred constructor. Resolved fields validate again before shared extraction; invalid supplied values never become absent or fall back to defaults. Forward values accept nonnegative safe integers or canonical decimal strings within uint256; safe integer numbers normalize explicitly to decimal strings, including zero. Only prediction-dependent comparisons wait for the constructor/factory/salt to resolve. Upgrade preflight requires both target factory and controlled multicall fields; deferred references remain allowed and their resolved addresses validate again before preparation.
+
+CREATE2 derives constructor input and init-code hash from actual artifact ABI/bytecode, actual factory and salt. Every role's address, salt, constructor input and init-code hash is compared; false expected addresses or leading-zero policies fail. UUPS implementation uses `implementationSalt`; the actual ERC1967Proxy artifact uses `[placeholderImplementation,'0x']` and `proxySalt`. Full factory calldata/value and upgrade proxy/implementation/initializer data are compared, including reused/zero-transaction plans. Original `required`/`reused` status decisions remain part of existing preparation/replay evidence; this check establishes current artifact/request/calldata consistency, not independent chain-state or release authority. Legacy shared execution without the optional port retains its loading isolation and behavior.

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,65 @@
+# Developer production delivery
+
+`gate-evm-tools/delivery-release` completes the developer side of the new EVM core 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 `deploy-test` task in the same canonical handoff.
+
+## 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.
+
+## 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, adaptations, and recovery instructions in the canonical manifest and parameters. `docs/prod-execution-plan.md` explains these canonical inputs, references `manifest.yaml` and `parameters.yaml`, and includes a `recovery` section. It is not another executable business plan.
+
+Development and enabled audit dependencies must appear in each qualification's upstream closure. Each current prerequisite must be completed/successful with `adoptedRev === rev`. `deploy` references its actual acceptance file; `check-code` references the actual raw CheckCode file. 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 every declared report's actual bytes. Audit tasks require `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 now uses the canonical Plan commands to create **all** `release-prepare → release-execute → release-verify` tasks for **each** selected target in the same handoff. Each has exact `environment: prod`, target, current revision, scope, and `prepared.releaseRef`. `release-prepare` depends on its target's qualification task; the next two stages depend on the preceding stage. Allowed actions are respectively `['simulate']`, `['execute','export-calldata','reconcile']`, and `['verify']`. Qualification tasks have `['simulate','verify']` and no releaseRef. The deployment agent implements and qualifies; mainAgent plans and dispatches. Admin 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, duplicate, split or missing stages 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.