gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/source.ts

@@ -0,0 +1,130 @@
+/** Actual-file source binding only. This API grants no host approval or execution authority. */
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { deliveryProjectMarker, projectRoot, confinedFile } from './project-files';
+import { object, parseDeliveryRequest, validateDeliveryRpc, type DeliveryRequest, type ChainIdProvider, type ProjectNetworkSnapshot } from './protocol';
+import { loadPlanCodec } from './codec';
+import type { Plan, PlanTask, DefinitionSelection, DefinitionSnapshot, DeepReadonly } from '../vendor/plan-codec/index.cjs';
+export type { DefinitionSelection, DefinitionSnapshot, DeepReadonly } from '../vendor/plan-codec/index.cjs';
+
+export interface DeliverySourceOptions {
+  workspaceRoot: string;
+  /** Workspace-relative path or '.'. */
+  projectRoot: string;
+  request: unknown;
+  /** Explicit upstream roots, independent of the invocation sourceRef task. */
+  sourceRoots: string[];
+}
+export interface DeliverySourceBinding {
+  request: DeliveryRequest;
+  workspaceRoot: string;
+  projectRoot: string;
+  observation: { path: string; sha256: string };
+  invocation: { lane: string; task: PlanTask };
+  sourceDefinition: DefinitionSnapshot;
+  sourceDefinitionBytes: string;
+  sourceDefinitionHash: string;
+  prodTaskGraph?: DefinitionSnapshot;
+  prodTaskGraphBytes?: string;
+  prodTaskGraphHash?: string;
+}
+const sha256 = (bytes: string | Buffer): string => createHash('sha256').update(bytes).digest('hex');
+function freeze<T>(value: T): DeepReadonly<T> {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value as DeepReadonly<T>;
+}
+export function parseCanonicalPlan(text: string): Plan { return loadPlanCodec().parsePlan(text); }
+export function projectCanonicalDefinitions(text: string, selection: DefinitionSelection): ReturnType<ReturnType<typeof loadPlanCodec>['projectDefinitions']> {
+  return loadPlanCodec().projectDefinitions(text, selection);
+}
+export function deploymentPurpose(task: Pick<PlanTask, 'step' | 'scope'>) {
+  return loadPlanCodec().deploymentPurpose(task);
+}
+function sameRelease(actual: unknown, expected: DeliveryRequest['releaseRef']): boolean {
+  if (expected === undefined) return actual === undefined;
+  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return false;
+  const ref = actual as Record<string, unknown>;
+  return Object.keys(ref).length === 3 && ref.path === expected.path && ref.releaseId === expected.releaseId && ref.inputsHash === expected.inputsHash;
+}
+function actualSource(workspace: string, relative: string): Buffer {
+  const file = confinedFile(workspace, relative);
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const before = fs.fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1) throw new Error('Unsafe handoff file type');
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd);
+    // Fail if the observed file was replaced or changed during reading.
+    confinedFile(workspace, relative);
+    const current = fs.lstatSync(file);
+    if (before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('Handoff changed while reading');
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+/** Read one confined handoff snapshot and bind the current invocation to it before any RPC work. */
+export function readDeliverySource(input: DeliverySourceOptions): DeepReadonly<DeliverySourceBinding> {
+  object(input, 'source options', ['workspaceRoot', 'projectRoot', 'request', 'sourceRoots']);
+  return readSource(input);
+}
+/** Owned business selection derives upstream roots from the same actual invocation bytes. */
+export function readOwnedDeliverySource(input: Omit<DeliverySourceOptions, 'sourceRoots'>): DeepReadonly<DeliverySourceBinding> {
+  object(input, 'owned source options', ['workspaceRoot', 'projectRoot', 'request']);
+  return readSource(input);
+}
+function readSource(input: Omit<DeliverySourceOptions, 'sourceRoots'> & { sourceRoots?: string[] }): DeepReadonly<DeliverySourceBinding> {
+  const request = parseDeliveryRequest(input.request);
+  const workspace = projectRoot(input.workspaceRoot, '.');
+  const root = projectRoot(workspace, input.projectRoot);
+  deliveryProjectMarker(root);
+  const bytes = actualSource(workspace, request.sourceRef.path);
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  if (input.sourceRoots === undefined) (require('./input-files') as typeof import('./input-files')).assertUnambiguousHandoff(text);
+  const codec = loadPlanCodec();
+  const plan = codec.parsePlan(text);
+  if (plan.taskId !== request.sourceRef.taskId) throw new Error('sourceRef.taskId does not match actual handoff');
+  const entries = Object.entries(plan.tasks).flatMap(([lane, tasks]) => tasks.map(task => ({ lane, task })));
+  const invocation = entries.find(({ task }) => task.planKey === request.sourceRef.planKey);
+  if (!invocation || invocation.task.rev !== request.sourceRef.rev) throw new Error('sourceRef planKey/rev does not match actual handoff');
+  if (plan.lanes[invocation.lane].state !== 'enabled' || invocation.task.status === 'cancelled') throw new Error('Invocation task is disabled or cancelled');
+  const requirementIssue = codec.deploymentRequirementIssue(plan, invocation.task);
+  if (requirementIssue) throw new Error(requirementIssue);
+  const deployment = object(invocation.task.scope?.deployment, 'invocation scope.deployment');
+  if (deployment.projectRoot !== input.projectRoot) throw new Error('Invocation projectRoot mismatch');
+  if (deployment.chainFamily !== 'evm' || deployment.framework !== 'hardhat2') throw new Error('Invocation requires an EVM Hardhat2 deployment');
+  if (deploymentPurpose(invocation.task) !== request.purpose) throw new Error('Invocation purpose mismatch');
+  if (deployment.environment !== request.environment || deployment.targetNetwork !== request.network) throw new Error('Invocation environment/targetNetwork mismatch');
+  if (!Array.isArray(deployment.allowedActions) || !deployment.allowedActions.includes(request.mode)) throw new Error('Invocation mode is not in allowedActions');
+  if (!sameRelease(deployment.releaseRef, request.releaseRef)) throw new Error('Invocation releaseRef mismatch');
+  const sourceRoots = input.sourceRoots ?? (request.purpose === 'prod-execution'
+    ? entries.filter(({ task }) => deploymentPurpose(task) === 'prod-qualification'
+      && (task.scope?.deployment as Record<string, unknown> | undefined)?.projectRoot === input.projectRoot
+      && (task.scope?.deployment as Record<string, unknown> | undefined)?.deploymentId === deployment.deploymentId).map(({ task }) => task.planKey)
+    : [invocation.task.planKey]);
+  if (!sourceRoots.length) throw new Error('Owned source requires an upstream qualification definition');
+  const source = codec.projectDefinitions(text, { roots: sourceRoots, mode: 'upstream' });
+  for (const task of source.snapshot.tasks) {
+    const selectedDeployment = task.scope?.deployment as Readonly<Record<string, unknown>> | undefined;
+    if (selectedDeployment && selectedDeployment.projectRoot !== input.projectRoot) throw new Error(`Selected upstream deployment projectRoot mismatch: ${task.planKey}`);
+  }
+  let production: ReturnType<typeof codec.projectDefinitions> | undefined;
+  if (request.purpose === 'prod-execution') {
+    const roots = entries.filter(({ task }) => deploymentPurpose(task) === 'prod-execution'
+      && task.scope?.deployment && (task.scope.deployment as Record<string, unknown>).projectRoot === input.projectRoot
+      && sameRelease((task.scope.deployment as Record<string, unknown>).releaseRef, request.releaseRef)).map(({ task }) => task.planKey);
+    production = codec.projectDefinitions(text, { roots, mode: 'full' });
+  }
+  // All values came from detached request parsing and actual handoff text; freeze before exposing.
+  return freeze({ request, workspaceRoot: workspace, projectRoot: root, observation: { path: request.sourceRef.path, sha256: sha256(bytes) },
+    invocation, sourceDefinition: source.snapshot, sourceDefinitionBytes: source.bytes, sourceDefinitionHash: sha256(source.bytes),
+    ...(production ? { prodTaskGraph: production.snapshot, prodTaskGraphBytes: production.bytes, prodTaskGraphHash: sha256(production.bytes) } : {}),
+  }) as DeepReadonly<DeliverySourceBinding>;
+}
+/** Read/validate actual source before a provider can be loaded; still not host authorization. */
+export async function validateDeliverySourceRpc(input: DeliverySourceOptions, snapshot: ProjectNetworkSnapshot,
+  loadProvider: (snapshot: ProjectNetworkSnapshot) => Promise<ChainIdProvider>,
+): Promise<DeepReadonly<DeliverySourceBinding & { chainId: number }>> {
+  const binding = readDeliverySource(input);
+  const { chainId } = await validateDeliveryRpc(binding.request, snapshot, loadProvider);
+  return freeze({ ...binding, chainId }) as DeepReadonly<DeliverySourceBinding & { chainId: number }>;
+}

package/runtime/delivery/target-fields.ts

@@ -0,0 +1,7 @@
+/** Complete scalar public target boundary shared by native references and custom ports. */
+export const PUBLIC_TARGET_FIELDS = new Set([
+  'version', 'id', 'network', 'environment', 'chainId', 'admin',
+  'finality.confirmations', 'openzeppelin.manifestDir',
+  'create2.scheme', 'create2.factory', 'create2.leadingZeroBytes', 'create2.caller',
+  'uups.placeholderImplementation', 'multicall.controlledMulticall',
+]);

package/runtime/delivery/task-identity.ts

@@ -0,0 +1,85 @@
+/** Allocate a round only after its concrete requirement revision is confirmed. */
+import fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { parseCanonicalPlan, projectCanonicalDefinitions, deploymentPurpose } from './source';
+import { projectRoot, deliveryProjectMarker, confinedFile, stat } from './project-files';
+import { readInputBytes, assertUnambiguousHandoff } from './input-files';
+import { withDevelopmentFileLock, atomicDevelopmentWrite, fileBytes } from './materialization';
+import { exactObject, semanticHash, canonicalJson } from '../workflow/lib/canonicalData';
+import { safeId, portablePath, object } from './protocol';
+
+export interface DeploymentRequirementRef { planKey: string; rev: number }
+export function parseDeploymentRequirementRef(raw: unknown): DeploymentRequirementRef {
+  const ref = exactObject(raw, ['planKey', 'rev'], 'requirementRef');
+  safeId(ref.planKey, 'requirementRef.planKey');
+  if (!Number.isSafeInteger(ref.rev) || (ref.rev as number) < 1) throw Error('Invalid requirement revision');
+  return { planKey: ref.planKey as string, rev: ref.rev as number };
+}
+export interface CreateDeliveryTaskOptions {
+  workspaceRoot: string; projectRoot: string; handoff: string; taskId: string;
+  requirementRef: DeploymentRequirementRef; businessSlug: string; referenceDeploymentId?: string;
+}
+/** A reservation creates metadata only. The deployment Agent supplies executable content afterwards. */
+export async function createDeliveryTask(input: CreateDeliveryTaskOptions) {
+  object(input, 'create deployment task', ['workspaceRoot', 'projectRoot', 'handoff', 'taskId', 'requirementRef', 'businessSlug', 'referenceDeploymentId']);
+  const root = projectRoot(input.workspaceRoot, input.projectRoot), workspace = projectRoot(input.workspaceRoot, '.');
+  deliveryProjectMarker(root);
+  portablePath(input.handoff, 'handoff'); safeId(input.taskId, 'taskId');
+  const ref = parseDeploymentRequirementRef(input.requirementRef);
+  if (typeof input.businessSlug !== 'string' || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(input.businessSlug)) throw Error('businessSlug must be a short lowercase business name');
+  if (input.referenceDeploymentId !== undefined) safeId(input.referenceDeploymentId, 'referenceDeploymentId');
+  return withDevelopmentFileLock(root, async () => {
+    const text = readInputBytes(workspace, input.handoff).toString(); assertUnambiguousHandoff(text);
+    const plan = parseCanonicalPlan(text);
+    if (plan.taskId !== input.taskId) throw Error('Requirement taskId mismatch');
+    const requirement = Object.values(plan.tasks).flat().find(t => t.planKey === ref.planKey);
+    if (!requirement || requirement.rev !== ref.rev || requirement.requirementConfirmation?.rev !== ref.rev
+      || requirement.status === 'cancelled' || deploymentPurpose(requirement) !== 'analysis'
+      || (requirement.scope?.deployment as any)?.projectRoot !== input.projectRoot) throw Error('Deployment requirement is unconfirmed or stale');
+    const d = requirement.scope!.deployment as any;
+    if (!d.requiredOperations?.length || !d.developmentNetwork || !Array.isArray(d.releaseTargetNetworks)) throw Error('Confirmed requirement scope is incomplete');
+    const identity = semanticHash({ taskId: input.taskId, projectRoot: input.projectRoot, requirementRef: ref });
+    const requirementHash = semanticHash(projectCanonicalDefinitions(text, { roots: [ref.planKey], mode: 'upstream' }).snapshot);
+    const registry = `.gate-delivery/deployment-requests/${identity}.json`;
+    const requestIdentity = { taskId: input.taskId, requirementRef: ref, requirementHash,
+      referenceDeploymentId: input.referenceDeploymentId ?? null };
+    let record: any;
+    const existing = fileBytes(root, registry);
+    if (existing !== null) {
+      record = JSON.parse(existing);
+      if (canonicalJson(record.requestIdentity) !== canonicalJson(requestIdentity)) throw Error('Confirmed requirement identity conflict');
+      safeId(record.deploymentId, 'reserved deploymentId');
+    } else {
+      const known = new Set(Object.values(plan.tasks).flat().map(t => (t.scope?.deployment as any)?.deploymentId).filter(Boolean));
+      const history = fileBytes(workspace, input.handoff.includes('/') ? `${input.handoff.slice(0, input.handoff.lastIndexOf('/'))}/handoff-ledger.jsonl` : 'handoff-ledger.jsonl');
+      if (history) for (const line of history.split('\n').filter(Boolean)) {
+        const item = JSON.parse(line);
+        for (const entry of item.tasks ?? []) { const id = entry.task?.scope?.deployment?.deploymentId; if (id) known.add(id); }
+      }
+      const date = new Date().toISOString().slice(0, 10).replaceAll('-', '');
+      let deploymentId: string;
+      do { deploymentId = `${input.businessSlug}-${date}-${randomBytes(4).toString('hex')}`; }
+      while (known.has(deploymentId) || stat(confinedFile(root, `scripts/tasks/${deploymentId}`, 'directory')));
+      record = { version: 1, deploymentId, releaseId: `${deploymentId}-release`, requestIdentity, state: 'reserved' };
+      // Publish reservation before creating the package, so a retry uses the same ID.
+      atomicDevelopmentWrite(root, registry, canonicalJson(record) + '\n');
+    }
+    const businessRoot = `scripts/tasks/${record.deploymentId}`;
+    const directory = confinedFile(root, businessRoot, 'directory');
+    const marker = `${businessRoot}/.request.json`;
+    const markerBytes = canonicalJson({ identity }) + '\n';
+    const previousMarker = fileBytes(root, marker);
+    if (stat(directory) && previousMarker !== markerBytes && fs.readdirSync(directory).length) throw Error('Reserved deployment directory is occupied; refusing to overwrite');
+    if (previousMarker !== null && previousMarker !== markerBytes) throw Error('Deployment reservation ownership mismatch');
+    if (previousMarker === null) atomicDevelopmentWrite(root, marker, markerBytes);
+    const metadata = { version: 1, id: record.deploymentId, requirementRef: ref,
+      developmentNetwork: d.developmentNetwork, releaseTargetNetworks: d.releaseTargetNetworks,
+      ...(input.referenceDeploymentId ? { referenceDeploymentId: input.referenceDeploymentId } : {}) };
+    const taskPath = `${businessRoot}/task.yaml`, bytes = canonicalJson(metadata) + '\n';
+    const previous = fileBytes(root, taskPath);
+    if (previous !== null && previous !== bytes) throw Error('Reserved task metadata changed; refusing to overwrite');
+    if (previous === null) atomicDevelopmentWrite(root, taskPath, bytes);
+    if (record.state !== 'complete') atomicDevelopmentWrite(root, registry, canonicalJson({ ...record, state: 'complete' }) + '\n');
+    return { status: 'created' as const, deploymentId: record.deploymentId as string, releaseId: record.releaseId as string, businessRoot, specPath: taskPath, requirementRef: ref };
+  });
+}

package/runtime/delivery/toolchain.ts

@@ -0,0 +1,48 @@
+import { compilerDependencyPins } from './compiler-dependency-pins';
+
+/** Reviewed compiler adapter dependency selections; payload checks remain authoritative.
+ * Range-scoped entries preserve distinct dependency majors. Setup never overrides a conflicting project choice. */
+export const REVIEWED_DELIVERY_OVERRIDES: Record<string, string> = {
+  "axios": "1.20.0",
+  "@aws-sdk/client-lambda": "3.1152.0",
+  "@aws-sdk/core": "3.978.3",
+  "@aws-sdk/credential-provider-env": "3.972.74",
+  "@aws-sdk/credential-provider-http": "3.972.76",
+  "@aws-sdk/credential-provider-ini": "3.973.19",
+  "@aws-sdk/credential-provider-login": "3.972.81",
+  "@aws-sdk/credential-provider-node": "3.972.86",
+  "@aws-sdk/credential-provider-process": "3.972.74",
+  "@aws-sdk/credential-provider-sso": "3.973.18",
+  "@aws-sdk/credential-provider-web-identity": "3.972.80",
+  "@aws-sdk/nested-clients": "3.997.48",
+  "@aws-sdk/signature-v4-multi-region": "3.996.48",
+  "@aws-sdk/token-providers": "3.1150.0",
+  "@aws-sdk/types": "3.974.6",
+  "@smithy/types": "4.19.0",
+  "@smithy/signature-v4": "5.7.4",
+  "@smithy/fetch-http-handler": "5.8.0",
+  "@smithy/credential-provider-imds": "4.5.2",
+  "@smithy/core": "3.36.0",
+  "@smithy/node-http-handler": "4.12.1",
+  "bowser": "2.14.1",
+  "follow-redirects": "1.16.1",
+  "undici@>=5 <6": "5.29.0",
+  "undici@>=6 <7": "6.29.0",
+  "tslib@>=1 <2": "1.14.1",
+  "tslib@>=2 <3": "2.7.0",
+  "semver@>=5 <6": "5.7.2",
+  "semver@>=6 <7": "6.3.1",
+  "semver@>=7 <8": "7.8.5",
+  "ansi-regex@>=6 <7": "6.4.0"
+};
+
+// OZ's compiler adapter follows floating AWS/Smithy ranges. Freeze that reviewed
+// family closure so a fresh npm resolution cannot select unqualified payloads.
+// Other project dependencies keep their original constraints and payload checks.
+for (const key of Object.keys(compilerDependencyPins)) {
+  if (!key.startsWith('@aws-sdk/') && !key.startsWith('@smithy/')) continue;
+  const at = key.lastIndexOf('@'), name = key.slice(0, at), version = key.slice(at + 1);
+  const existing = REVIEWED_DELIVERY_OVERRIDES[name];
+  if (existing && existing !== version) throw new Error('Ambiguous reviewed compiler dependency: ' + name);
+  REVIEWED_DELIVERY_OVERRIDES[name] = version;
+}

package/runtime/delivery/validation.ts

@@ -0,0 +1,252 @@
+import { validateCreate2Fields } from "./create2";
+import { canonicalCreate2Hashes } from "../workflow/lib/create2Hashes";
+import { ParamType, getCreate2Address } from "ethers";
+import type { WorkflowContext } from "../workflow/lib/context";
+import type { WorkflowStep } from "../workflow/lib/parameters";
+import type { WorkflowValidationPort } from "../workflow/lib/validation";
+import { strictData } from "./data";
+import {
+  resolveBusinessValue,
+  containsDeferred,
+  type ReferenceObservation,
+} from "./references";
+import {
+  validateAbiArguments,
+  validateAbiValue,
+  validateTransactionValue,
+  validateAbiResult,
+  compareAbiResults,
+  stringifyRuntimeValue,
+} from "./abi";
+import {
+  deliveryArtifact,
+  deliveryPreparationData,
+  validatePreparationSemantics,
+  ERC1967_PROXY,
+} from "./preparation";
+import { parseNativeOperation } from "./custom";
+import { deepFreeze } from "../workflow/lib/canonicalData";
+import { ownedDeliveryCompiler, compilerPreparationHooks, validateCompilerPreparationPlan, verifyCompilerSameForkUpgrade } from './compiler';
+
+export interface DeliveryValidation extends WorkflowValidationPort {
+  preflight(steps: readonly WorkflowStep[]): Promise<void>;
+  observations(): readonly ReferenceObservation[];
+}
+export function createDeliveryValidation(
+  context: WorkflowContext,
+): DeliveryValidation {
+  if (context.target.create2?.scheme && context.target.create2.scheme !== "evm")
+    throw new Error("Delivery validation requires EVM");
+  const observations: ReferenceObservation[] = [];
+  const compiler = ownedDeliveryCompiler(context.runtime.hre);
+  const params = deepFreeze(strictData(context.targetParams));
+  const resolve = (value: unknown, deferState = false): unknown => {
+    const result = resolveBusinessValue(
+      value,
+      { params, target: context.target, state: () => context.state.snapshot() },
+      { deferState },
+    );
+    observations.push(...result.observations);
+    return result.value;
+  };
+  // Artifact reader is an explicit runtime capability, never an address/contract resolver.
+  const read = async (name: string) => {
+    if (!context.runtime.hre.artifacts?.readArtifact)
+      throw new Error(
+        "Delivery validation requires explicit runtime artifact reader",
+      );
+    return deliveryArtifact(
+      await context.runtime.hre.artifacts.readArtifact(name),
+    );
+  };
+  const argumentsFor = async (
+    name: string,
+    method: string | null,
+    args: unknown,
+    deferState = false,
+  ) =>
+    validateAbiArguments(
+      (await read(name)).abi,
+      method,
+      resolve(args, deferState),
+      { allowDeferred: deferState },
+    );
+  const call = async (
+    name: string,
+    method: string,
+    args: unknown,
+    value?: unknown,
+  ) => {
+    validateAbiArguments((await read(name)).abi, method, args);
+    if (value !== undefined) validateTransactionValue(value);
+  };
+  const preflight = async (steps: readonly WorkflowStep[]) => {
+    const data = strictData(steps);
+    for (const step of data) {
+      // Internal operation IDs can exceed the source parser's 200-character limit.
+      parseNativeOperation({ ...step, id: "validation" });
+      resolve(step, true); // Parse every reference without reading future state.
+      if (step.address !== undefined)
+        validateAbiValue(
+          ParamType.from("address"),
+          resolve(step.address, true),
+          "operation address",
+          true,
+        );
+      if (["call", "view", "check"].includes(step.kind)) {
+        for (const c of step.calls as Array<Record<string, unknown>>) {
+          await argumentsFor(
+            String(step.abi ?? step.contract),
+            c.method as string,
+            c.args === undefined ? [] : c.args,
+            true,
+          );
+          if (step.kind === "check")
+            validateAbiResult(
+              (await read(String(step.abi ?? step.contract))).abi,
+              c.method as string,
+              resolve(c.expect, true),
+              true,
+            );
+          if (c.value !== undefined)
+            validateTransactionValue(resolve(c.value, true), true);
+        }
+      } else {
+        const first = step.firstUpgrade as Record<string, unknown> | undefined;
+        const proxy = step.proxy as Record<string, unknown> | undefined;
+        const name = first?.contract ?? step.contract;
+        const args = first
+          ? (first.constructorArgs ?? [])
+          : step.kind === "deploy"
+            ? (proxy ? (proxy.constructorArgs ?? []) : (step.args ?? []))
+            : (step.constructorArgs ??
+              (typeof proxy === "object"
+                ? proxy?.constructorArgs
+                : undefined) ??
+              []);
+        await argumentsFor(name as string, null, args, true);
+        if (step.kind === "deploy" && proxy?.kind === "transparent" && proxy.initializer !== false) {
+          await argumentsFor(name as string, String(proxy.initializer), step.args ?? [], true);
+        }
+        const init = (first?.call ?? step.call) as
+          | Record<string, unknown>
+          | undefined;
+        if (init)
+          await argumentsFor(
+            name as string,
+            (init.method ?? init.fn) as string,
+            init.args ?? [],
+            true,
+          );
+        if (first)
+          await argumentsFor(
+            ERC1967_PROXY,
+            null,
+            [context.target.uups?.placeholderImplementation, "0x"],
+            true,
+          );
+        const fields = (value: unknown, kind: Parameters<typeof validateCreate2Fields>[1]) =>
+          validateCreate2Fields(resolve(value === undefined ? {} : value, true), kind, true);
+        const targetCreate2 = fields(context.target.create2, "target");
+        fields(context.target.uups, "uups");
+        const targetMulticall = fields(context.target.multicall, "multicall");
+        if (
+          step.kind === "upgrade" &&
+          (targetCreate2.factory === undefined || targetMulticall.controlledMulticall === undefined)
+        )
+          throw new Error(`Upgrade step ${step.id} requires target create2 factory and controlledMulticall`);
+        const declaredCreate2 = step.create2 === undefined
+          ? undefined
+          : fields(step.create2, "step");
+        const policy =
+          context.existingDeploymentPolicies?.[String(step.saveAs)];
+        const create2 =
+          declaredCreate2 && policy?.mode === "redeploy"
+            ? validateCreate2Fields(
+                {
+                  ...declaredCreate2,
+                  salt: policy.salt,
+                  expectedAddress: policy.expectedAddress,
+                },
+                "step",
+                true,
+              )
+            : declaredCreate2;
+        // Transparent proxy prediction depends on the prepared implementation salt/address.
+        // Its actual constructor and policies are independently checked by preparation semantics.
+        if (step.kind === "deploy" && create2 && proxy?.kind !== "transparent") {
+          const a = await read(first ? ERC1967_PROXY : (name as string));
+          const constructor = resolve(
+            first
+              ? [context.target.uups?.placeholderImplementation, "0x"]
+              : args,
+            true,
+          );
+          const factory = create2.factory ?? targetCreate2.factory,
+            salt = create2.salt;
+          if (factory === undefined)
+            throw new Error("CREATE2 requires a factory address");
+          if (!containsDeferred([constructor, factory, salt])) {
+            const hashes = canonicalCreate2Hashes({
+              scheme: "evm",
+              artifact: a,
+              args: constructor as unknown[],
+            });
+            if (hashes.scheme !== "evm")
+              throw new Error("Invalid CREATE2 scheme");
+            const predicted = getCreate2Address(
+              factory as string,
+              salt as string,
+              hashes.initCodeHash,
+            ).toLowerCase();
+            if (create2.expectedAddress !== undefined) {
+              const expected = create2.expectedAddress;
+              if (
+                !containsDeferred(expected) &&
+                (typeof expected !== "string" ||
+                  predicted !== expected.toLowerCase())
+              )
+                throw new Error(
+                  "Actual CREATE2 predicted address differs from expectedAddress",
+                );
+            }
+            const zeroes =
+              create2.leadingZeroBytes ??
+              targetCreate2.leadingZeroBytes;
+            if (
+              zeroes !== undefined &&
+              !containsDeferred(zeroes) &&
+              !predicted.slice(2).startsWith("00".repeat(Number(zeroes)))
+            )
+              throw new Error("Actual CREATE2 violates leadingZeroBytes");
+          }
+        }
+      }
+    }
+  };
+  return {
+    resolve,
+    create2Fields: validateCreate2Fields,
+    call,
+    address: (value) =>
+      validateAbiValue(ParamType.from("address"), value, "operation address"),
+    callInterface: validateAbiArguments,
+    check: validateAbiResult,
+    compare: compareAbiResults,
+    stringify: stringifyRuntimeValue,
+    preparation: {
+      data: deliveryPreparationData,
+      artifact: (name, raw) => deepFreeze(deliveryArtifact(compiler ? compiler.artifact(name, raw) : raw)),
+      arguments: (artifact, method, args) =>
+        validateAbiArguments(artifact.abi, method, args),
+      ...compilerPreparationHooks(context.runtime.hre),
+    },
+    preparationPlan: async (request, plan) => {
+      await validatePreparationSemantics(request, plan, read);
+      await validateCompilerPreparationPlan(context.runtime.hre,request,plan);
+    },
+    sameForkUpgrade: proxy => verifyCompilerSameForkUpgrade(context.runtime.hre,context.targetId,proxy,context.simulation.snapshot?.blockNumber),
+    preflight,
+    observations: () => deepFreeze(strictData(observations)),
+  };
+}

package/runtime/delivery/verification.ts

@@ -0,0 +1,47 @@
+import { canonicalData, canonicalJson, deepFreeze, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import { parseTypedValue } from '../workflow/lib/typedValue';
+import type { VerificationObservation, VerificationSink } from '../workflow/lib/evidencePorts';
+export interface ExpectedAssertion { stepId: string; callIndex: number; assertionId: string }
+export function parseVerificationObservation(raw: unknown): VerificationObservation {
+  const v = exactObject(raw, ['stepId', 'callIndex', 'assertionId', 'contract', 'abiName', 'abi', 'address', 'method', 'args', 'definition', 'actual', 'expected'], 'verification observation');
+  for (const key of ['stepId', 'assertionId', 'contract', 'abiName', 'method']) nonempty(v[key], key);
+  if (!Number.isSafeInteger(v.callIndex) || (v.callIndex as number) < 0 || v.assertionId !== `${v.stepId}:${v.callIndex}`) throw new Error('Invalid assertion identity');
+  if (typeof v.address !== 'string' || !/^0x[\da-fA-F]{40}$/.test(v.address)) throw new Error('Invalid verification address');
+  if (!Array.isArray(v.abi) || v.abi.length === 0 || v.abi.some(item => typeof item !== 'string' || !item)) throw new Error('Invalid verification ABI');
+  const definition = exactObject(v.definition, ['method', 'args', 'expect'], 'check definition');
+  nonempty(definition.method, 'definition method');
+  if (definition.method !== v.method) throw new Error('Check definition method mismatch');
+  parseTypedValue(definition.args); parseTypedValue(definition.expect);
+  parseTypedValue(v.args); parseTypedValue(v.actual); parseTypedValue(v.expected);
+  return deepFreeze(canonicalData(v) as unknown as VerificationObservation);
+}
+export class VerificationJournal implements VerificationSink {
+  private readonly expected: ExpectedAssertion[];
+  private readonly observations: VerificationObservation[] = [];
+  private sealed = false;
+  constructor(expected: readonly ExpectedAssertion[]) {
+    this.expected = [];
+    this.declare(expected);
+  }
+  declare(expected: readonly ExpectedAssertion[]): void {
+    if (this.sealed) throw new Error("verification journal sealed");
+    this.expected.push(...deepFreeze(canonicalData(expected) as ExpectedAssertion[]));
+    if (new Set(this.expected.map(e => e.assertionId)).size !== this.expected.length) throw new Error('Duplicate expected assertion');
+    for (const e of this.expected) {
+      exactObject(e, ['stepId', 'callIndex', 'assertionId'], 'expected assertion');
+      if (!Number.isSafeInteger(e.callIndex) || e.callIndex < 0 || e.assertionId !== `${e.stepId}:${e.callIndex}`) throw new Error('Invalid expected assertion');
+    }
+  }
+  record(raw: VerificationObservation): void {
+    if (this.sealed) throw new Error('verification journal sealed');
+    const observation = parseVerificationObservation(raw), expected = this.expected[this.observations.length];
+    if (!expected || canonicalJson(expected) !== canonicalJson({ stepId: observation.stepId, callIndex: observation.callIndex, assertionId: observation.assertionId })) throw new Error('Unexpected verification step/call mapping');
+    this.observations.push(observation);
+  }
+  seal(): VerificationObservation[] {
+    if (this.expected.length !== this.observations.length) throw new Error('missing expected verification observations');
+    this.sealed = true;
+    // Empty is valid collection, never business acceptance or qualification authority.
+    return deepFreeze([...this.observations]);
+  }
+}

package/runtime/migrate.ts

@@ -12,6 +12,7 @@ const commands: Record<string, string> = {
   create2Hashes: 'create2-hashes', releaseFinalize: 'release-finalize',
   importState: 'import-state', reconcileExternal: 'reconcile-external',
   commitContractInfo: 'commit-contract-info',
+  planRead: 'plan-read', planWrite: 'plan-write', planAdd: 'plan-add', planStatus: 'plan-status',
 };
 
 /** Plan first; preserve custom files/state. Only known sources/shims are removable. */

package/runtime/miner/binary.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Create2MinerBinaryOptions } from "./types";
+
+// These trusted pins are compiled into the runtime. A mutable manifest alone is not a trust anchor.
+const bundled: Record<string, { sha256: string; bytes: number }> = {
+  "darwin-arm64": { sha256: "9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954", bytes: 1297616 },
+  "darwin-x64": { sha256: "a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82", bytes: 1306112 },
+};
+function executable(file: string): void {
+  try {
+    if (!statSync(file).isFile()) throw new Error("not a regular file");
+    accessSync(file, constants.X_OK);
+    if (process.platform !== "win32" && (statSync(file).mode & 0o111) === 0) throw new Error("missing executable permission");
+  } catch (cause) {
+    throw new Error(`CREATE2 miner is not an executable file: ${file}`, { cause });
+  }
+}
+export function resolveCreate2MinerBinary(options: Create2MinerBinaryOptions = {}): string {
+  const override = options.binaryPath !== undefined ? options.binaryPath : process.env.GATE_TOOL_CREATE2_MINER_BIN;
+  if (override !== undefined) {
+    if (typeof override !== "string" || override.trim().length === 0) throw new Error("CREATE2 miner binaryPath override must be a non-empty path");
+    const file = resolve(override);
+    executable(file);
+    return file;
+  }
+  const host = `${process.platform}-${process.arch}`;
+  const pin = bundled[host];
+  if (!pin) throw new Error(`No bundled CREATE2 miner for ${host}. Build a compatible smartflow_miner and set GATE_TOOL_CREATE2_MINER_BIN or binaryPath to its executable path.`);
+  const directory = resolve(__dirname, "../../resources/create2");
+  const file = resolve(directory, host, "smartflow_miner");
+  executable(file);
+  const bytes = readFileSync(file);
+  if (bytes.length !== pin.bytes || createHash("sha256").update(bytes).digest("hex") !== pin.sha256) throw new Error(`Bundled CREATE2 miner SHA-256 mismatch: ${file}; reinstall the package or supply a trusted binaryPath`);
+  let entry: { sha256?: unknown; bytes?: unknown } | undefined;
+  try { entry = JSON.parse(readFileSync(resolve(directory, "manifest.json"), "utf8")).binaries?.[host]; }
+  catch (cause) { throw new Error("Bundled CREATE2 miner manifest is invalid", { cause }); }
+  if (!entry || entry.sha256 !== pin.sha256 || entry.bytes !== pin.bytes) throw new Error(`Bundled CREATE2 miner manifest mismatch for ${host}`);
+  return file;
+}