gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/identities.ts

@@ -0,0 +1,132 @@
+import {
+  canonicalData,
+  deepFreeze,
+  exactObject,
+  nonempty,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+export interface OperationBinding {
+  stepId: string;
+  sourceStepId: string;
+  operationId: string | null;
+  kind: string;
+}
+const kinds = new Set(["deploy", "upgrade", "call", "view", "check"]);
+const engineId = (source: string, operation: string | null) =>
+  `op-${semanticHash(["gate-delivery-operation", 1, source, operation])}`;
+export function parseOperationBindings(raw: unknown): OperationBinding[] {
+  if (!Array.isArray(raw))
+    throw new Error("operation bindings must be an array");
+  const seen = new Set<string>();
+  return deepFreeze(
+    raw.map((item) => {
+      const v = exactObject(
+        item,
+        ["stepId", "sourceStepId", "operationId", "kind"],
+        "operation binding",
+      );
+      nonempty(v.sourceStepId, "sourceStepId");
+      if (v.operationId !== null) nonempty(v.operationId, "operationId");
+      if (
+        !kinds.has(String(v.kind)) ||
+        v.stepId !==
+          engineId(v.sourceStepId as string, v.operationId as string | null) ||
+        seen.has(String(v.stepId))
+      )
+        throw new Error("Invalid or duplicate operation identity");
+      seen.add(String(v.stepId));
+      return v as unknown as OperationBinding;
+    }),
+  );
+}
+/** Delivery only: the neutral/legacy planner's locked IDs are unchanged. */
+export class DeliveryOperationIdentities {
+  private readonly bindings: OperationBinding[] = [];
+  register(
+    sourceStepId: string,
+    operationId: string | null,
+    kind: string,
+  ): string {
+    nonempty(sourceStepId, "source step");
+    if (operationId !== null) nonempty(operationId, "custom operation");
+    const stepId = engineId(sourceStepId, operationId);
+    if (!kinds.has(kind) || this.bindings.some((b) => b.stepId === stepId))
+      throw new Error("Duplicate operation identity or hash collision");
+    this.bindings.push({ stepId, sourceStepId, operationId, kind });
+    return stepId;
+  }
+  transactionStepId(stepId: string, role: "call", ordinal: number): string {
+    if (
+      !this.bindings.some((b) => b.stepId === stepId && b.kind === role) ||
+      !Number.isSafeInteger(ordinal) ||
+      ordinal < 0
+    )
+      throw new Error("Invalid delivery call identity");
+    return `${stepId}-call-${ordinal}`;
+  }
+  seal(): OperationBinding[] {
+    return parseOperationBindings(canonicalData(this.bindings));
+  }
+}
+
+export interface TransactionBinding {
+  transactionId: string;
+  stepId: string;
+  role: "call" | "deployment" | "implementation" | "upgrade";
+  callIndex: number | null;
+}
+/** Explicit reverse map: transaction -> operation/role -> source step/custom operation. */
+export function bindDeliveryTransactions(
+  transactions: readonly import("../workflow/lib/transactionPlanner").ReleaseExecutionTransaction[],
+  operations: readonly OperationBinding[],
+): TransactionBinding[] {
+  let previousOperation = -1;
+  const callOrdinals = new Map<string, number>();
+  const roles = new Set<string>();
+  return deepFreeze(
+    transactions.map((tx) => {
+      const index = operations.findIndex(
+        (b) =>
+          tx.stepId === b.stepId ||
+          (b.kind === "upgrade" &&
+            tx.stepId === `${b.stepId}-implementation`) ||
+          (b.kind === "call" && tx.stepId.startsWith(`${b.stepId}-call-`)),
+      );
+      if (index < previousOperation || index < 0)
+        throw new Error("Unbound or unordered delivery transaction identity");
+      previousOperation = index;
+      const operation = operations[index];
+      if (operation.kind === "view" || operation.kind === "check")
+        throw new Error("Read operation cannot bind transaction");
+      let role: TransactionBinding["role"],
+        callIndex: number | null = null;
+      if (operation.kind === "call") {
+        callIndex = callOrdinals.get(operation.stepId) ?? 0;
+        if (tx.stepId !== `${operation.stepId}-call-${callIndex}`)
+          throw new Error("Invalid delivery call ordinal");
+        callOrdinals.set(operation.stepId, callIndex + 1);
+        role = "call";
+      } else
+        role =
+          operation.kind === "deploy"
+            ? "deployment"
+            : tx.stepId === operation.stepId
+              ? "upgrade"
+              : "implementation";
+      const key = JSON.stringify([operation.stepId, role, callIndex]);
+      if (
+        roles.has(key) ||
+        (role === "implementation" &&
+          roles.has(JSON.stringify([operation.stepId, "upgrade", null])))
+      )
+        throw new Error("Duplicate or unordered transaction role");
+      roles.add(key);
+      return {
+        transactionId: tx.transactionId,
+        stepId: operation.stepId,
+        role,
+        callIndex,
+      };
+    }),
+  );
+}

package/runtime/delivery/input-files.ts

@@ -0,0 +1,46 @@
+/** Strict, confined business document reads. Errors never include document contents. */
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import YAML from 'yaml';
+import { strictData } from './data';
+import { confinedFile } from './project-files';
+
+export const inputDigest = (bytes: string | Buffer): string => createHash('sha256').update(bytes).digest('hex');
+export function readInputBytes(root: string, relative: string): Buffer {
+  const file = confinedFile(root, 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 business input file');
+    const bytes = fs.readFileSync(fd), after = fs.fstatSync(fd);
+    confinedFile(root, 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('Business input changed while reading');
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+export function parseInputDocument(bytes: Buffer | string, format: 'json' | 'yaml'): unknown {
+  try {
+    const text = typeof bytes === 'string' ? bytes : new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    // JSON.parse establishes JSON syntax; the YAML AST additionally preserves duplicate members.
+    if (format === 'json') JSON.parse(text);
+    const doc = YAML.parseDocument(text, { uniqueKeys: true, merge: false, prettyErrors: false });
+    if (doc.errors.length || doc.warnings.length) throw new Error();
+    YAML.visit(doc, {
+      Node(_key, node) {
+        if (YAML.isAlias(node) || ('anchor' in node && node.anchor) || node.tag) throw new Error();
+      },
+      Pair(_key, pair) {
+        if (!YAML.isScalar(pair.key) || typeof pair.key.value !== 'string' || pair.key.value === '<<') throw new Error();
+      },
+    });
+    return strictData(doc.toJS({ maxAliasCount: 0 }));
+  } catch { throw new Error('Invalid business document: duplicate members or unsafe non-JSON data'); }
+}
+/** The canonical codec remains the sole handoff interpreter; this only rejects ambiguous syntax. */
+export function assertUnambiguousHandoff(text: string): void {
+  const frontmatter = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (frontmatter) parseInputDocument(frontmatter[1], 'yaml');
+  for (const match of text.matchAll(/```gateflow-(?:task|progress)\r?\n([\s\S]*?)\r?\n```/g)) parseInputDocument(match[1], 'json');
+}

package/runtime/delivery/inputs.ts

@@ -0,0 +1,204 @@
+/** Owned business input binding only. This is not an aggregate plan or release/execution authority. */
+import { readOwnedDeliverySource, type DeliverySourceBinding } from './source';
+import { strictData, ownPath } from './data';
+import { readInputBytes, parseInputDocument, inputDigest } from './input-files';
+import { object, safeId, portablePath, type DeliveryRequest } from './protocol';
+import { parseDeliveryPublicTargets, type DeliveryPublicTarget } from './config';
+import { confinedFile } from './project-files';
+import { parseCustomStep, parseNativeOperation } from './custom';
+import { CustomModuleClosure, type CustomInputClosure } from './custom-closure';
+import { resolveDeliveryParameters, consumeDeliveryParameters, type ResolvedDeliveryParameters, type TrustedParameterProducer } from './parameters';
+import { validateDeploySaveAs, type WorkflowStep } from '../workflow/lib/parameters';
+import { canonicalJson, deepFreeze, semanticHash, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import type { DeepReadonly } from './source';
+import { parseDeploymentRequirementRef } from './task-identity';
+import { resolveParameterTargets } from './parameter-defaults';
+
+export interface DeliveryInputOptions {
+  workspaceRoot: string;
+  projectRoot: string;
+  request: DeliveryRequest;
+  /** Data scope only; does not authorize invocation against any additional target. */
+  selection: 'development' | 'release' | 'all';
+}
+export interface DeliveryInputSnapshot {
+  version: 1;
+  deploymentId: string;
+  businessRoot: string;
+  sourceDefinitionHash: string;
+  sourceDefinition: DeliverySourceBinding['sourceDefinition'];
+  steps: readonly WorkflowStep[];
+  targets: DeliveryPublicTarget[];
+  files: Array<{ path: string; digest: string }>;
+}
+export interface DeliveryParameterReceipt { readonly version: 1; readonly target: string; readonly identity: string }
+export interface DeliveryParameterEvidence {
+  target: string;
+  resolved: ResolvedDeliveryParameters;
+  producers: Array<{ id: string; version: string; module: string; moduleDigest: string }>;
+  closure: CustomInputClosure | null;
+  identity: string;
+}
+export interface DeliveryInputEvidence extends DeliveryInputSnapshot {
+  parameters: DeliveryParameterEvidence[];
+  /** Business-input identity only; never a final aggregate inputsHash. */
+  businessInputHash: string;
+}
+export interface DeliveryInputHandle {
+  readonly snapshot: DeepReadonly<DeliveryInputSnapshot>;
+  values(target: string): unknown;
+  parameters(target: string): DeliveryParameterReceipt;
+  /** Terminal reread only; no producer or custom execution. One shot, failure revokes all receipts. */
+  seal(): DeepReadonly<DeliveryInputEvidence>;
+  close(): void;
+}
+type State = { status: 'open' | 'sealed' | 'failed' | 'closed' };
+const receipts = new WeakMap<object, { owner: State; evidence: DeliveryParameterEvidence }>();
+/** Only a receipt issued by a successfully sealed owner can be consumed; JSON is never authority. */
+export function consumeDeliveryInputParameters(receipt: DeliveryParameterReceipt): unknown {
+  const owned = receipt && typeof receipt === 'object' ? receipts.get(receipt) : undefined;
+  if (!owned || owned.owner.status !== 'sealed') throw new Error('Parameter receipt requires a sealed owned session (closed or failed receipts are invalid)');
+  return consumeDeliveryParameters(owned.evidence.resolved, owned.evidence.resolved.identity);
+}
+function same(a: unknown, b: unknown, label: string): void {
+  if (canonicalJson(a) !== canonicalJson(b)) throw new Error(`${label} drift or mismatch`);
+}
+function parseSteps(raw: unknown): readonly WorkflowStep[] {
+  if (!Array.isArray(raw) || !raw.length) throw new Error('Manifest steps must be a nonempty ordered array');
+  const steps = raw.map(step => object(step, 'manifest step').kind === 'custom' ? parseCustomStep(step) : parseNativeOperation(step));
+  if (new Set(steps.map(step => step.id)).size !== steps.length) throw new Error('Duplicate manifest step IDs');
+  validateDeploySaveAs(steps);
+  return deepFreeze(steps);
+}
+/** Read all structure before invoking any producer. Actual modules reuse the existing bounded loader. */
+export function openDeliveryInputs(raw: DeliveryInputOptions): DeliveryInputHandle {
+  const input = strictData(raw);
+  exactObject(input, ['workspaceRoot', 'projectRoot', 'request', 'selection'], 'delivery input options');
+  if (!['development', 'release', 'all'].includes(input.selection)) throw new Error('Unsupported delivery input selection');
+  const sourceInput = { workspaceRoot: input.workspaceRoot, projectRoot: input.projectRoot, request: input.request };
+  const source = readOwnedDeliverySource(sourceInput);
+  const scope = object(source.invocation.task.scope?.deployment, 'deployment');
+  const deploymentId = safeId(scope.deploymentId, 'deploymentId'), businessRoot = `scripts/tasks/${deploymentId}`;
+  const files: DeliveryInputSnapshot['files'] = [];
+  const read = (name: string, format: 'json' | 'yaml') => {
+    const relative = `${businessRoot}/${name}`, bytes = readInputBytes(source.projectRoot, relative);
+    files.push({ path: relative, digest: inputDigest(bytes) });
+    return parseInputDocument(bytes, format);
+  };
+  const task = object(read('task.yaml', 'yaml'), 'task.yaml', ['version', 'id', 'developmentNetwork', 'releaseTargetNetworks', 'requirementRef', 'productionRequirementRef', 'referenceDeploymentId']);
+  if (task.version !== 1 || task.id !== deploymentId) throw new Error('Task version/deployment identity mismatch');
+  same(parseDeploymentRequirementRef(task.requirementRef), scope.requirementRef, 'Task requirementRef');
+  same(task.referenceDeploymentId ?? null, scope.referenceDeploymentId ?? null, 'Task referenceDeploymentId');
+  same(task.developmentNetwork, scope.developmentNetwork, 'Task developmentNetwork');
+  const release = task.releaseTargetNetworks as string[];
+  if (!Array.isArray(release) || new Set(release).size !== release.length) throw Error('Invalid task releaseTargetNetworks');
+  for (const network of release) if(typeof network !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(network) || ['__proto__','prototype','constructor'].includes(network)) throw Error('Invalid release target');
+  if (input.request.environment === 'dev') {
+    if (!(scope.releaseTargetNetworks as string[]).every(network => release.includes(network))) throw Error('Task removed a development-declared release target');
+  } else {
+    same(release, scope.releaseTargetNetworks, 'Task releaseTargetNetworks');
+    same(task.productionRequirementRef === undefined ? null : parseDeploymentRequirementRef(task.productionRequirementRef), scope.productionRequirementRef ?? null, 'Task productionRequirementRef');
+  }
+  const manifest = object(read('manifest.yaml', 'yaml'), 'manifest.yaml', ['id', 'description', 'steps']);
+  if (manifest.id !== deploymentId) throw new Error('Manifest deployment identity mismatch');
+  if (manifest.description !== undefined) nonempty(manifest.description, 'manifest description');
+  const steps = parseSteps(manifest.steps);
+  const schema = object(read('parameters.schema.json', 'json'), 'parameters schema');
+  const dev = scope.developmentNetwork as string;
+  const all = [dev, ...release];
+  const { params, observations, definitions } = resolveParameterTargets(
+    read('parameters.yaml', 'yaml'), read('parameters.provenance.json', 'json'), all);
+  for (const [id, raw] of Object.entries(definitions)) {
+    safeId(id, 'producer ID');
+    const definition = exactObject(raw, ['version', 'module'], 'producer');
+    nonempty(definition.version, 'producer version');
+    const module = portablePath(definition.module, 'producer module');
+    if (!module.startsWith(`${businessRoot}/`)) throw new Error('Producer module is outside deployment business root');
+  }
+  const selected = input.selection === 'development' ? [dev] : input.selection === 'release' ? release : all;
+  // Both the digest and every public projection use these exact buffers. Reopening
+  // for projection would permit an A→B→A edit to bind B's values to A's digest.
+  const configBytes = readInputBytes(source.projectRoot, 'config.yaml');
+  const projectConfigBytes = readInputBytes(source.projectRoot, 'hardhat.config.ts');
+  const targets = parseDeliveryPublicTargets(configBytes, projectConfigBytes,
+    selected.map(network => ({ network, environment: network === dev ? 'dev' : 'prod' })));
+  for (const target of targets) confinedFile(source.projectRoot, target.openzeppelin!.manifestDir, 'directory');
+  const configurationFiles = [{ path: 'config.yaml', digest: inputDigest(configBytes) },
+    { path: 'hardhat.config.ts', digest: inputDigest(projectConfigBytes) }];
+  for (const file of configurationFiles) {
+    files.push(file);
+  }
+  // Verify every selected envelope is present before the first producer runs.
+  for (const target of targets) {
+    ownPath(params, [target.id], 'selected target parameters');
+    ownPath(observations, [target.id], 'selected target provenance');
+  }
+  const snapshot = deepFreeze({ version: 1 as const, deploymentId, businessRoot, sourceDefinitionHash: source.sourceDefinitionHash,
+    sourceDefinition: source.sourceDefinition, steps, targets, files });
+  const state: State = { status: 'open' };
+  const resolved = new Map<string, { receipt: DeliveryParameterReceipt; evidence: DeliveryParameterEvidence; closure?: CustomModuleClosure }>();
+  const assertOpen = () => { if (state.status !== 'open') throw new Error('Business input session is closed'); };
+  try {
+    for (const target of targets) {
+      const observed = object(observations[target.id], 'target provenance');
+      const computed = object(observed.computed, 'computed observations');
+      object(observed.manual, 'manual observations');
+      let closure: CustomModuleClosure | undefined;
+      const producers: Record<string, TrustedParameterProducer> = Object.create(null);
+      const used: DeliveryParameterEvidence['producers'] = [];
+      for (const raw of Object.values(computed)) {
+        const observation = exactObject(raw, ['producer', 'version', 'inputs', 'output'], 'computed observation');
+        const id = safeId(observation.producer, 'producer ID');
+        if (Object.hasOwn(producers, id)) continue;
+        const definition = exactObject(ownPath(definitions, [id], 'producer definition'), ['version', 'module'], 'producer');
+        closure ??= new CustomModuleClosure(source.projectRoot);
+        const loaded = closure.load(definition.module as string);
+        if (!loaded.module || typeof loaded.module.produce !== 'function' || Object.keys(loaded.module).some(key => key !== 'produce')) throw new Error('Parameter module must only export synchronous produce(inputs)');
+        used.push({ id, version: definition.version as string, module: loaded.identity.path, moduleDigest: loaded.identity.digest });
+        const current = closure;
+        producers[id] = Object.freeze({ version: definition.version as string, produce: (inputs: unknown) => {
+          const result = current.normalize(loaded.module.produce(deepFreeze(strictData(inputs))));
+          current.assertUnchanged();
+          return result;
+        } });
+      }
+      const envelope = resolveDeliveryParameters({ schema, target: target.id, values: params[target.id], sources: params,
+        manual: observed.manual as ResolvedDeliveryParameters['manual'], computed: observed.computed as ResolvedDeliveryParameters['computed'], producers });
+      const body = { target: target.id, resolved: envelope, producers: used.sort((a,b) => a.id.localeCompare(b.id, 'en')), closure: closure?.seal() ?? null };
+      const evidence = deepFreeze({ ...body, identity: semanticHash({ version: 1, files, ...body }) });
+      const receipt = Object.freeze({ version: 1 as const, target: target.id, identity: evidence.identity });
+      receipts.set(receipt, { owner: state, evidence });
+      resolved.set(target.id, { receipt, evidence, closure });
+    }
+  } catch (error) { state.status = 'failed'; throw error; }
+  const get = (target: string) => {
+    assertOpen(); const result = resolved.get(target);
+    if (!result) throw new Error('Target is outside selected delivery inputs');
+    return result;
+  };
+  const handle: DeliveryInputHandle = {
+    snapshot,
+    values: target => get(target).evidence.resolved.values,
+    parameters: target => get(target).receipt,
+    close() { if (state.status !== 'failed') state.status = 'closed'; },
+    seal() {
+      assertOpen();
+      // Close evaluation/read ports before terminal verification. Failure is permanent.
+      state.status = 'failed';
+      for(const {closure} of resolved.values())closure?.closeReads();
+      const current = readOwnedDeliverySource(sourceInput);
+      same(current.sourceDefinitionHash, source.sourceDefinitionHash, 'Business source definition');
+      same(current.invocation.task.scope?.deployment, scope, 'Business invocation');
+      for (const file of files) if (inputDigest(readInputBytes(source.projectRoot, file.path)) !== file.digest) throw new Error('Business input file drift');
+      const parameters = [...resolved.values()].map(({ evidence, closure }) => {
+        same(closure?.seal() ?? null, evidence.closure, 'Parameter producer closure');
+        return evidence;
+      });
+      const body = { ...snapshot, parameters };
+      const evidence = deepFreeze({ ...body, businessInputHash: semanticHash(body) });
+      state.status = 'sealed';
+      return evidence;
+    },
+  };
+  return Object.freeze(handle);
+}

package/runtime/delivery/journal.ts

@@ -0,0 +1,205 @@
+import { contractInfoKey } from '../workflow/lib/deployments';
+import { expectedTransactionPurposes } from "../workflow/lib/gateTool";
+import { sameAddress } from "../workflow/lib/pendingUupsBinding";
+import { normalizePreparationPlan, normalizePreparationRequest, hashPreparationRequest } from 'gate-evm-tools/workflow';
+import type { GateToolAddressPolicy, GateToolPreparationRequestV1 } from 'gate-evm-tools/workflow';
+import type { DeploymentChange } from '../workflow/lib/deploymentRecords';
+import type { PreparedGateToolWorkflow } from '../workflow/lib/gateTool';
+import type { PreparationInput, PreparationMapping, PreparationSink } from '../workflow/lib/evidencePorts';
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { canonicalData, canonicalJson, deepFreeze, digest, exactObject, nonempty, semanticHash } from '../workflow/lib/canonicalData';
+import { assertCreate2AddressPolicy, prepareControlledMulticallTransaction } from '../workflow/lib/create2';
+import { portablePath } from './protocol';
+import type { DerivedBindings } from './bindings';
+import { matchesSameForkInitial, sameForkBaselineDigest } from './same-fork-baseline';
+export interface PreparationEntry extends PreparationInput { requestHash: string; gateToolPlanHash: string; mappings: PreparationMapping[]; preparationHash: string }
+export interface JournalIdentity { target: string; chainId: string; expectedStepIds: readonly string[] }
+const addressKeys = ['address', 'proxyAddress', 'proxyAdminAddress', 'proxyAdminOwner', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'factory', 'multicall', 'expectedAddress', 'predictedAddress', 'previousAddress'];
+const stringKeys = ['stepId', 'instanceId', 'actualContract', 'contractInfoKey', 'strategy', 'proxyKind', 'implementationSalt', 'salt', 'redeployReason'];
+// Prepared changes cannot carry runtime reuse observations, receipts, candidate lifecycle, sync or success markers.
+const changeKeys = [...addressKeys, ...stringKeys, 'kind', 'constructorArgs', 'leadingZeroBytes', 'gateTool'];
+function normalizeChange(raw: unknown): DeploymentChange {
+  const v = canonicalData(raw) as Record<string, unknown>;
+  if (!v || typeof v !== 'object' || Array.isArray(v) || Object.keys(v).some(k => !changeKeys.includes(k))) throw new Error('Unsupported prepared deployment change metadata');
+  for (const key of ['stepId', 'instanceId', 'actualContract', 'contractInfoKey']) nonempty(v[key], key);
+  if (v.kind !== 'deploy' && v.kind !== 'upgrade') throw new Error('Invalid prepared deployment kind');
+  for (const k of stringKeys) if (Object.hasOwn(v, k)) nonempty(v[k], k);
+  for (const k of addressKeys) if (Object.hasOwn(v, k) && (typeof v[k] !== 'string' || !/^0x[\da-fA-F]{40}$/.test(v[k] as string))) throw new Error(`Invalid prepared ${k}`);
+  for (const k of ['salt', 'implementationSalt']) if (Object.hasOwn(v, k) && !/^0x[\da-fA-F]{64}$/.test(v[k] as string)) throw new Error(`Invalid prepared ${k}`);
+  if (Object.hasOwn(v, 'constructorArgs') && !Array.isArray(v.constructorArgs)) throw new Error('Invalid constructorArgs');
+  if (Object.hasOwn(v, 'leadingZeroBytes') && (!Number.isInteger(v.leadingZeroBytes) || (v.leadingZeroBytes as number) < 0 || (v.leadingZeroBytes as number) > 20)) throw new Error('Invalid leadingZeroBytes');
+  exactObject(v.gateTool, ['outputPath', 'data'], 'GateTool evidence');
+  return v as unknown as DeploymentChange;
+}
+function normalizeInput(raw: unknown, identity: JournalIdentity): PreparationInput {
+  const v = exactObject(raw, ['stepId', 'change', 'prepared', 'derivedKeys'], 'preparation');
+  const stepId = nonempty(v.stepId, 'preparation stepId');
+  if (!identity.expectedStepIds.includes(stepId)) throw new Error('Unexpected preparation stepId');
+  const change = normalizeChange(v.change);
+  const p = exactObject(v.prepared, ['request', 'plan', 'requestPath', 'planPath'], 'prepared GateTool evidence');
+  const request = normalizePreparationRequest(p.request), plan = normalizePreparationPlan(p.plan);
+  const requestPath = portablePath(p.requestPath, 'request ref'), planPath = portablePath(p.planPath, 'plan ref');
+  if (!requestPath.endsWith(`/${stepId}-request.json`) || !planPath.endsWith(`/${stepId}-plan.json`)) throw new Error('Preparation step/ref mismatch');
+  if (request.scheme !== 'evm' || plan.scheme !== 'evm') throw new Error('Delivery preparation must use EVM');
+  if (plan.requestHash !== hashPreparationRequest(request) || plan.kind !== request.kind || plan.network !== request.network || plan.target !== request.target || plan.contract !== request.contract || plan.target !== identity.target || plan.chainId !== identity.chainId) throw new Error('Preparation request/plan identity mismatch');
+  if (change.stepId !== stepId || (change.kind === 'upgrade') !== (plan.kind === 'uups-upgrade' || plan.kind === 'transparent-upgrade') || change.actualContract !== plan.artifact.contractName || (plan.contract.includes(':') && plan.contract !== `${plan.artifact.sourceName}:${plan.artifact.contractName}`)) throw new Error('Preparation change/step/artifact identity mismatch');
+  if (canonicalJson(plan.transactions.map(t => t.purpose)) !== canonicalJson(expectedTransactionPurposes(plan))) throw new Error('Preparation transaction purposes/order mismatch');
+  if (!sameAddress(change.factory, request.factory) || change.contractInfoKey !== contractInfoKey(change.instanceId, change.actualContract)) throw new Error('Prepared factory/registry identity mismatch');
+  if (change.strategy !== ((plan.kind === 'uups-upgrade' || plan.kind === 'transparent-upgrade') ? 'gate-tool' : 'create2')) throw new Error('Invalid prepared strategy');
+  const role = (name: string) => { const matches = plan.deployments.filter(d => d.role === name); if (matches.length !== 1) throw new Error(`Missing/duplicate preparation ${name}`); return matches[0]; };
+  const optionalAddress = (key: keyof DeploymentChange, expected: string) => {
+    if (Object.hasOwn(change, key) && !sameAddress(change[key], expected)) throw new Error(`Prepared ${key} does not match its canonical address`);
+  };
+  const rejectFields = (...keys: (keyof DeploymentChange)[]) => {
+    for (const key of keys) if (Object.hasOwn(change, key)) throw new Error(`Prepared ${request.kind} cannot contain ${key}`);
+  };
+  const deploymentPolicy = (policy: GateToolAddressPolicy | undefined, deployedAddress: string) => {
+    assertCreate2AddressPolicy('Prepared deployment', deployedAddress, policy ?? {});
+    optionalAddress('expectedAddress', deployedAddress);
+    if (Object.hasOwn(change, 'leadingZeroBytes') && change.leadingZeroBytes !== policy?.leadingZeroBytes) throw new Error('Prepared leadingZeroBytes differs from request policy');
+  };
+  if (Object.hasOwn(change, 'constructorArgs') && canonicalJson(change.constructorArgs) !== canonicalJson(request.constructorArgs)) throw new Error('Prepared constructorArgs differ from canonical request');
+  if (request.kind === 'create2-deploy') {
+    const deployment = role('contract');
+    rejectFields('proxyAddress', 'implementationAddress', 'preparedImplementationAddress', 'placeholderImplementationAddress', 'implementationSalt', 'proxyAdminAddress', 'proxyAdminOwner');
+    if (change.proxyKind !== undefined || deployment.salt !== request.salt || change.salt !== request.salt || !sameAddress(change.predictedAddress, deployment.address)) throw new Error('Prepared CREATE2 request/deployment mismatch');
+    optionalAddress('address', deployment.address);
+    deploymentPolicy(request.addressPolicy, deployment.address);
+  } else {
+    const implementation = role('implementation');
+    if (change.proxyKind !== request.proxyKind || !sameAddress(change.implementationAddress, implementation.address) || implementation.salt !== request.implementationSalt) throw new Error('Prepared implementation mismatch');
+    optionalAddress('preparedImplementationAddress', implementation.address);
+    if(request.proxyKind==='transparent'){
+      if(!sameAddress(change.proxyAdminAddress,plan.proxyAdmin?.address)||!sameAddress(change.proxyAdminOwner,request.proxyAdminOwner)||!sameAddress(plan.proxyAdmin?.owner,request.proxyAdminOwner))throw Error('Prepared Transparent ProxyAdmin mismatch');
+    }else rejectFields('proxyAdminAddress','proxyAdminOwner');
+    if (request.kind === 'uups-placeholder-deploy' || request.kind === 'transparent-deploy') {
+      const proxy = role('proxy');
+      if (proxy.salt !== request.proxySalt || change.salt !== request.proxySalt || !sameAddress(change.predictedAddress, proxy.address) || (request.kind==='uups-placeholder-deploy'&&!sameAddress(change.placeholderImplementationAddress, request.placeholderImplementation))) throw new Error('Prepared proxy mismatch');
+      if(request.kind==='transparent-deploy')rejectFields('placeholderImplementationAddress');
+      optionalAddress('address', proxy.address);
+      optionalAddress('proxyAddress', proxy.address);
+      deploymentPolicy(request.proxyAddressPolicy, proxy.address);
+    } else {
+      // Deployment address-policy aliases describe a newly created contract/proxy,
+      // not the existing proxy or its separately named implementation upgrade.
+      rejectFields('salt', 'predictedAddress', 'expectedAddress', 'leadingZeroBytes', 'placeholderImplementationAddress', 'previousAddress', 'redeployReason');
+      if (!sameAddress(change.proxyAddress, request.proxy)) throw new Error('Prepared upgrade proxy mismatch');
+      optionalAddress('address', request.proxy);
+      assertCreate2AddressPolicy('Prepared implementation', implementation.address, request.implementationAddressPolicy ?? {});
+    }
+  }
+  if (change.gateTool?.outputPath !== planPath || canonicalJson(change.gateTool?.data) !== canonicalJson(plan)) throw new Error('Prepared embedded GateTool plan mismatch');
+  if (!Array.isArray(v.derivedKeys) || v.derivedKeys.some(k => typeof k !== 'string') || new Set(v.derivedKeys).size !== v.derivedKeys.length) throw new Error('Invalid derivedKeys');
+  const derivedKeys = v.derivedKeys as string[];
+  if (plan.kind !== 'create2-deploy' && (derivedKeys.length !== 1 || derivedKeys[0] !== `${stepId}.implementation` || change.implementationSalt !== (request as { implementationSalt: string }).implementationSalt)) throw new Error('Preparation derived binding mismatch');
+  if (plan.kind === 'create2-deploy' && derivedKeys.length) throw new Error('Unexpected derived bindings');
+  return deepFreeze({ stepId, change, prepared: { request, plan, requestPath, planPath }, derivedKeys });
+}
+function normalizeMapping(raw: unknown): PreparationMapping {
+  const m = exactObject(raw, ['transactionId', 'gateToolTransactionIds', 'kind'], 'preparation mapping');
+  nonempty(m.transactionId, 'mapping transactionId');
+  if (m.kind !== 'multicall' && m.kind !== 'direct') throw new Error('Invalid mapping kind');
+  if (!Array.isArray(m.gateToolTransactionIds) || !m.gateToolTransactionIds.length || m.gateToolTransactionIds.some(id => typeof id !== 'string') || new Set(m.gateToolTransactionIds).size !== m.gateToolTransactionIds.length) throw new Error('Invalid mapping GateTool IDs');
+  return m as unknown as PreparationMapping;
+}
+function entryBody(input: PreparationInput, mappings: PreparationMapping[]) {
+  return { ...input, requestHash: hashPreparationRequest(input.prepared.request), gateToolPlanHash: semanticHash(input.prepared.plan), mappings };
+}
+function validateMappings(entry: PreparationEntry, transactions: readonly ReleaseExecutionTransaction[], derived: DerivedBindings, used: Set<string>): void {
+  const innerIds = entry.mappings.flatMap(m => m.gateToolTransactionIds);
+  const expectedIds = entry.prepared.plan.transactions.map(t => t.id);
+  if (canonicalJson(innerIds) !== canonicalJson(expectedIds)) throw new Error('missing, extra, duplicate or out-of-order preparation mapping');
+  for (const key of entry.derivedKeys) if (!Object.hasOwn(derived.values, key) || derived.values[key] !== entry.change.implementationSalt) throw new Error('Preparation derived value mismatch');
+  let previousIndex = -1;
+  for (const m of entry.mappings) {
+    const tx = transactions.find(t => t.transactionId === m.transactionId);
+    if (!tx || used.has(m.transactionId) || (tx.stepId !== entry.stepId && tx.stepId !== `${entry.stepId}-implementation`) || tx.transactionIndex <= previousIndex) throw new Error('Invalid preparation transaction mapping');
+    used.add(m.transactionId); previousIndex = tx.transactionIndex;
+    const inner = m.gateToolTransactionIds.map(id => entry.prepared.plan.transactions.find(t => t.id === id)!);
+    if (m.kind === 'direct' && inner.length !== 1) throw new Error('Direct mapping must contain exactly one transaction');
+    if (m.kind === 'multicall' && !entry.change.multicall) throw new Error('Missing multicall address');
+    const envelope = m.kind === 'direct' ? { target: inner[0].to, value: inner[0].value, data: inner[0].data, operation: inner[0].operation }
+      : prepareControlledMulticallTransaction(entry.change.multicall!, inner.map(t => ({ target: t.to, value: t.value, data: t.data })));
+    if (tx.to.toLowerCase() !== envelope.target.toLowerCase() || tx.value !== envelope.value || tx.data !== envelope.data.toLowerCase() || tx.operation !== envelope.operation || tx.scheme !== undefined) throw new Error('Preparation transaction envelope mismatch');
+  }
+}
+export function parsePreparationJournal(raw: unknown, transactions: readonly ReleaseExecutionTransaction[], derived: DerivedBindings, identity: JournalIdentity): PreparationEntry[] {
+  if (!Array.isArray(raw)) throw new Error('Preparation journal must be an array');
+  const entries = raw.map(item => {
+    const v = exactObject(item, ['stepId', 'change', 'prepared', 'derivedKeys', 'requestHash', 'gateToolPlanHash', 'mappings', 'preparationHash'], 'preparation entry');
+    const input = normalizeInput({ stepId: v.stepId, change: v.change, prepared: v.prepared, derivedKeys: v.derivedKeys }, identity);
+    if (!Array.isArray(v.mappings)) throw new Error('Invalid mappings');
+    const body = entryBody(input, v.mappings.map(normalizeMapping));
+    if (digest(v.requestHash, 'requestHash') !== body.requestHash || digest(v.gateToolPlanHash, 'GateTool plan hash') !== body.gateToolPlanHash || digest(v.preparationHash, 'preparationHash') !== semanticHash(body)) throw new Error('Preparation content hash mismatch');
+    return { ...body, preparationHash: semanticHash(body) };
+  });
+  if (canonicalJson(entries.map(e => e.stepId)) !== canonicalJson(identity.expectedStepIds)) throw new Error('missing, extra or duplicate preparation steps');
+  for (const [index, entry] of entries.entries()) {
+    const {request,plan} = entry.prepared;
+    if ((request.kind === 'uups-upgrade' || request.kind === 'transparent-upgrade') && (plan.validation.kind === 'uups-upgrade' || plan.validation.kind === 'transparent-upgrade') && plan.validation.sameForkBaselineDigest !== undefined) {
+      const validation = plan.validation;
+      const prior = entries.slice(0,index).filter(e => matchesSameForkInitial(e.prepared,request.target,plan.chainId,request.proxy,validation.currentImplementation,request.proxyKind));
+      if (prior.length !== 1 || sameForkBaselineDigest(prior[0].prepared,validation.oldLayoutHash) !== validation.sameForkBaselineDigest) throw new Error('Same-fork upgrade requires its exact prior initial preparation');
+    }
+  }
+  const used = new Set<string>();
+  for (const entry of entries) validateMappings(entry, transactions, derived, used);
+  for (const tx of transactions) if (identity.expectedStepIds.some(id => tx.stepId === id || tx.stepId === `${id}-implementation`) && !used.has(tx.transactionId)) throw new Error('Unresolved expected preparation transaction');
+  return deepFreeze(canonicalData(entries) as PreparationEntry[]);
+}
+export class PreparationJournal implements PreparationSink {
+  private readonly identity: Omit<JournalIdentity, "expectedStepIds"> & { expectedStepIds: string[] };
+  private readonly inputs: PreparationInput[] = [];
+  private readonly mappings = new Map<string, PreparationMapping[]>();
+  private readonly prior: PreparationEntry[];
+  private sealed = false;
+  private readonly qualifiedSameFork?: (initial: PreparedGateToolWorkflow) => boolean;
+  constructor(input: JournalIdentity & { expected?: readonly PreparationEntry[]; qualifiedSameFork?: (initial: PreparedGateToolWorkflow) => boolean }) {
+    this.qualifiedSameFork = input.qualifiedSameFork;
+    this.identity = { target: input.target, chainId: input.chainId, expectedStepIds: [...input.expectedStepIds] };
+    if (new Set(input.expectedStepIds).size !== input.expectedStepIds.length) throw new Error('Duplicate preparation step');
+    // Full binding validation occurs against the sealed plan at the coordinator/parser boundary.
+    this.prior = deepFreeze(canonicalData(input.expected ?? []) as PreparationEntry[]);
+  }
+  declare(stepIds: readonly string[]): void {
+    if (this.sealed) throw new Error("Preparation journal sealed");
+    for (const id of stepIds) {
+      nonempty(id, "preparation step");
+      if (this.identity.expectedStepIds.includes(id)) throw new Error("Duplicate preparation step");
+      this.identity.expectedStepIds.push(id);
+    }
+  }
+  expected(stepId: string, request: GateToolPreparationRequestV1): PreparedGateToolWorkflow | undefined {
+    const entry = this.prior.find(e => e.stepId === stepId);
+    if (!entry) { if (this.prior.length) throw new Error('Missing expected preparation'); return undefined; }
+    const input = normalizeInput({ stepId: entry.stepId, change: entry.change, prepared: entry.prepared, derivedKeys: entry.derivedKeys }, this.identity);
+    exactObject(entry, ['stepId', 'change', 'prepared', 'derivedKeys', 'requestHash', 'gateToolPlanHash', 'mappings', 'preparationHash'], 'expected preparation');
+    if (entry.requestHash !== hashPreparationRequest(input.prepared.request) || entry.gateToolPlanHash !== semanticHash(input.prepared.plan) || semanticHash(entryBody(input, entry.mappings.map(normalizeMapping))) !== entry.preparationHash) throw new Error('Expected preparation hash mismatch');
+    if (canonicalJson(normalizePreparationRequest(request)) !== canonicalJson(input.prepared.request)) throw new Error('Expected preparation request mismatch');
+    return input.prepared;
+  }
+  prepare(raw: PreparationInput): void {
+    if (this.sealed) throw new Error('Preparation journal sealed');
+    const input = normalizeInput(raw, this.identity);
+    if (this.inputs.some(i => i.stepId === input.stepId)) throw new Error('Duplicate preparation');
+    this.inputs.push(input); this.mappings.set(input.stepId, []);
+  }
+  bind(stepId: string, raw: PreparationMapping): void {
+    if (this.sealed) throw new Error('Preparation journal sealed');
+    const mappings = this.mappings.get(stepId);
+    if (!mappings) throw new Error('Mapping has no prepared step');
+    mappings.push(normalizeMapping(raw));
+  }
+  assertUpgradeBaseline(proxy: string): boolean {
+    const matches = this.inputs.filter(i => matchesSameForkInitial(i.prepared,this.identity.target,this.identity.chainId,proxy));
+    if (!matches.length) return false;
+    if (matches.length !== 1 || !this.qualifiedSameFork?.(matches[0].prepared)) throw new Error('Same-fork proxy upgrade requires a complete validated immutable OZ layout baseline; unsupported without that evidence');
+    return true;
+  }
+  seal(transactions: readonly ReleaseExecutionTransaction[], derived: DerivedBindings): PreparationEntry[] {
+    const raw = this.inputs.map(input => { const body = entryBody(input, this.mappings.get(input.stepId)!); return { ...body, preparationHash: semanticHash(body) }; });
+    const entries = parsePreparationJournal(raw, transactions, derived, this.identity);
+    if (this.prior.length && canonicalJson(entries) !== canonicalJson(this.prior)) throw new Error('Preparation replay differs from sealed evidence');
+    this.sealed = true; return entries;
+  }
+}