gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/materialization.ts

@@ -0,0 +1,53 @@
+/** Recoverable file-only commit. SQLite supplies an OS-released cross-process mutex;
+ * the fsynced intent survives that mutex's rollback after a process crash. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+import {DatabaseSync} from 'node:sqlite';
+import {canonicalJson,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import {portablePath,safeId} from './protocol';
+export interface DevelopmentFile {path:string;before:string|null;after:string}
+export interface DevelopmentFileCommit {root:string;executionId:string;identity:string;files:DevelopmentFile[]}
+export const byteHash=(bytes:string|Buffer)=>createHash('sha256').update(bytes).digest('hex');
+export function developmentPath(root:string,relative:string):string {
+ portablePath(relative,'materialization path');let current=fs.realpathSync(root);
+ for(const part of relative.split('/')){current=path.join(current,part);if(fs.existsSync(current)){const s=fs.lstatSync(current);if(s.isSymbolicLink()||(!s.isDirectory()&&!s.isFile())||s.isFile()&&s.nlink!==1)throw Error('Unsafe materialization path');}}
+ return current;
+}
+export function fileBytes(root:string,relative:string):string|null {const file=developmentPath(root,relative);return fs.existsSync(file)?fs.readFileSync(file,'utf8'):null;}
+function syncDir(directory:string){const fd=fs.openSync(directory,'r');try{fs.fsyncSync(fd);}finally{fs.closeSync(fd);}}
+function mkdir(directory:string){if(fs.existsSync(directory))return;mkdir(path.dirname(directory));fs.mkdirSync(directory,{mode:0o700});syncDir(path.dirname(directory));}
+export function atomicDevelopmentWrite(root:string,relative:string,bytes:string):void {
+ const file=developmentPath(root,relative);mkdir(path.dirname(file));const temp=`${file}.${randomUUID()}.tmp`;
+ const fd=fs.openSync(temp,'wx',0o600);try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}
+ fs.renameSync(temp,file);syncDir(path.dirname(file));
+}
+export function readDevelopmentJournal(root:string,executionId:string):any|undefined {
+ const bytes=fileBytes(root,`.gate-delivery/materialization/${safeId(executionId,'executionId')}.json`);if(bytes===null)return;
+ const j=JSON.parse(bytes);exactObject(j,['version','executionId','identity','files','state','intentHash'],'materialization journal');
+ if(j.version!==1||j.executionId!==executionId||!['prepared','committed'].includes(j.state)||!Array.isArray(j.files)||!j.files.length)throw Error('Invalid materialization journal');
+ for(const f of j.files){exactObject(f,['path','before','after','beforeHash','afterHash'],'journal file');portablePath(f.path,'journal path');if((f.before!==null&&typeof f.before!=='string')||typeof f.after!=='string'||f.beforeHash!==(f.before===null?null:byteHash(f.before))||f.afterHash!==byteHash(f.after))throw Error('Invalid materialization journal bytes');}
+ if(new Set(j.files.map((f:any)=>f.path)).size!==j.files.length||j.intentHash!==semanticHash({version:j.version,executionId:j.executionId,identity:j.identity,files:j.files}))throw Error('Invalid materialization journal identity');return j;
+}
+export async function withDevelopmentFileLock<T>(root:string,work:()=>Promise<T>):Promise<T> {
+ const file=developmentPath(root,'.gate-delivery/materialization.sqlite');mkdir(path.dirname(file));const db=new DatabaseSync(file);
+ try{db.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE');return await work();}finally{try{db.exec('ROLLBACK');}finally{db.close();}}
+}
+/** Caller holds no file lock. onFileCommitted is a progress notification, never acceptance authority. */
+export async function commitDevelopmentFiles(input:DevelopmentFileCommit,onFileCommitted?:(path:string)=>void):Promise<any> {
+ return withDevelopmentFileLock(input.root,()=>commitDevelopmentFilesLocked(input,onFileCommitted));
+}
+export async function commitDevelopmentFilesLocked(input:DevelopmentFileCommit,onFileCommitted?:(path:string)=>void):Promise<any> {
+ safeId(input.executionId,'executionId');if(!/^[a-f0-9]{64}$/.test(input.identity)||!input.files.length)throw Error('Invalid materialization identity/files');
+ const files=input.files.map(f=>{exactObject(f,['path','before','after'],'materialization file');developmentPath(input.root,f.path);if((f.before!==null&&typeof f.before!=='string')||typeof f.after!=='string')throw Error('Invalid file bytes');return {...f,beforeHash:f.before===null?null:byteHash(f.before),afterHash:byteHash(f.after)};});
+ if(new Set(files.map(f=>f.path)).size!==files.length)throw Error('Duplicate materialization path');
+ const body={version:1,executionId:input.executionId,identity:input.identity,files},intentHash=semanticHash(body);
+ let journal=readDevelopmentJournal(input.root,input.executionId);
+ if(journal&&journal.intentHash!==intentHash)throw Error('Materialization identity/candidate conflict');
+ const journalPath=`.gate-delivery/materialization/${input.executionId}.json`;
+ // Validate the entire set before changing even the first file.
+ for(const f of files){const bytes=fileBytes(input.root,f.path);if(bytes!==f.before&&bytes!==f.after)throw Error(`Materialization byte conflict: ${f.path}`);if(journal?.state==='committed'&&bytes!==f.after)throw Error(`Committed materialization conflict: ${f.path}`);}
+ if(!journal){journal={...body,state:'prepared',intentHash};atomicDevelopmentWrite(input.root,journalPath,canonicalJson(journal)+'\n');}
+ for(const f of files){const current=fileBytes(input.root,f.path);if(current===f.after)continue;if(current!==f.before)throw Error(`Materialization byte conflict: ${f.path}`);atomicDevelopmentWrite(input.root,f.path,f.after);onFileCommitted?.(f.path);}
+ journal={...journal,state:'committed'};atomicDevelopmentWrite(input.root,journalPath,canonicalJson(journal)+'\n');return journal;
+}

package/runtime/delivery/observations.ts

@@ -0,0 +1,60 @@
+/** Structural observation validation grants neither chain finality nor send authority. */
+import { canonicalJson, deepFreeze, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import { strictData } from './data';
+import type { DeliveryPlan } from './plan';
+export type ObservationState = 'included-unfinalized' | 'finalized-success' | 'finalized-reverted';
+export interface TransactionObservation {
+    observationId: string;
+    executionId: string;
+    planHash: string;
+    chainId: string;
+    target: string;
+    transaction: DeliveryPlan['transactions'][number];
+    transactionHash: string;
+    state: ObservationState;
+    blockNumber: string;
+    blockHash: string;
+    safe?: {
+        envelopeId: string;
+        innerCallIndex: number;
+        transactionIndex: string;
+    };
+}
+/** Trusted producer must verify exact transaction/chain inclusion, execution outcome,
+ * canonicality and configured finality. A user JSON object or receipt hash is not this capability.
+ * Hosts must supply this port from controlled code, never agent-supplied implementations. */
+export interface TrustedObservationPort {
+    readObservation(observationId: string): Promise<TransactionObservation | undefined>;
+}
+export interface TrustedFinalizedProgressPort {
+    readFinalized(observationId: string): Promise<TransactionObservation | undefined>;
+}
+export function uint256(raw: unknown, label: string): string {
+    if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw) || BigInt(raw) >= 2n ** 256n)
+        throw new Error(`Invalid canonical uint256 ${label}`);
+    return raw;
+}
+export function hash32(raw: unknown, label: string): string {
+    if (typeof raw !== 'string' || !/^0x[0-9a-f]{64}$/.test(raw))
+        throw new Error(`Invalid ${label}`);
+    return raw;
+}
+export function parseObservation(raw: unknown, plan: DeliveryPlan, index: number): TransactionObservation {
+    const data = strictData(raw);
+    const v = exactObject(data, ['observationId', 'executionId', 'planHash', 'chainId', 'target', 'transaction', 'transactionHash', 'state', 'blockNumber', 'blockHash', ...(Object.hasOwn(data as object, 'safe') ? ['safe'] : [])], 'transaction observation');
+    if (v.safe !== undefined) {
+        const m = exactObject(v.safe, ['envelopeId', 'innerCallIndex', 'transactionIndex'], 'Safe observation mapping');
+        if (typeof m.envelopeId !== 'string' || !/^[0-9a-f]{64}$/.test(m.envelopeId) || !Number.isSafeInteger(m.innerCallIndex) || Number(m.innerCallIndex) < 0)
+            throw Error('Invalid Safe observation mapping');
+        uint256(m.transactionIndex, 'Safe transactionIndex');
+    }
+    nonempty(v.observationId, 'observationId');
+    hash32(v.transactionHash, 'transactionHash');
+    hash32(v.blockHash, 'blockHash');
+    uint256(v.blockNumber, 'blockNumber');
+    if (!['included-unfinalized', 'finalized-success', 'finalized-reverted'].includes(String(v.state)))
+        throw new Error('Invalid observation state');
+    if (v.executionId !== plan.executionId || v.planHash !== plan.planHash || v.chainId !== plan.chainId || v.target !== plan.target || !plan.transactions[index] || canonicalJson(v.transaction) !== canonicalJson(plan.transactions[index]))
+        throw new Error('Observation plan identity/order mismatch');
+    return deepFreeze(v as unknown as TransactionObservation);
+}

package/runtime/delivery/parameters.ts

@@ -0,0 +1,349 @@
+import Ajv from "ajv";
+import {
+  deepFreeze,
+  semanticHash,
+  canonicalJson,
+} from "../workflow/lib/canonicalData";
+import { strictData, ownPath, pointerPart, pointerParts } from "./data";
+export { strictData } from "./data";
+
+type Schema = Record<string, any>;
+type Policy =
+  | { kind: "copy"; target: string; path: string }
+  | { kind: "manual" }
+  | { kind: "computed"; producer: string; version: string };
+export interface ManualObservation {
+  source: string;
+  value: unknown;
+}
+export interface ComputedObservation {
+  producer: string;
+  version: string;
+  inputs: unknown;
+  output: unknown;
+}
+export interface ParameterInputs {
+  schema: Schema;
+  target: string;
+  values: unknown;
+  sources?: Record<string, unknown>;
+  manual?: Record<string, ManualObservation>;
+  computed?: Record<string, ComputedObservation>;
+}
+export interface TrustedParameterProducer {
+  version: string;
+  produce(inputs: unknown): unknown;
+}
+export interface LeafProvenance {
+  target: string;
+  path: string;
+  policy: Policy["kind"];
+  valueIdentity: string;
+  observation: Record<string, unknown>;
+}
+export interface ResolvedDeliveryParameters extends Required<ParameterInputs> {
+  version: 1;
+  provenance: LeafProvenance[];
+  identity: string;
+}
+const DIALECT = "http://json-schema.org/draft-07/schema#";
+const KEYWORDS = new Set([
+  "$schema",
+  "title",
+  "description",
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+  "enum",
+  "const",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "x-policy",
+]);
+const ajv = new Ajv({
+  strict: true,
+  allErrors: true,
+  coerceTypes: false,
+  useDefaults: false,
+  removeAdditional: false,
+  ownProperties: true,
+});
+ajv.addKeyword({ keyword: "x-policy", valid: true });
+function checkedSchema(raw: Schema): Schema {
+  const schema = strictData(raw);
+  if (schema.$schema !== DIALECT)
+    throw new Error("Delivery schema requires explicit draft-07 dialect");
+  const visit = (s: Schema, root = false): void => {
+    if (!s || typeof s !== "object" || Array.isArray(s))
+      throw new Error("Delivery schema nodes must be objects");
+    for (const key of Object.keys(s))
+      if (!KEYWORDS.has(key))
+        throw new Error(`Unsupported delivery schema keyword ${key}`);
+    if (!root && s.$schema !== undefined)
+      throw new Error("Nested schema dialect unsupported");
+    if (
+      ![
+        "object",
+        "array",
+        "string",
+        "boolean",
+        "integer",
+        "number",
+        "null",
+      ].includes(s.type)
+    )
+      throw new Error("Each delivery schema node requires one explicit type");
+    if (s.type === "object") {
+      if (
+        s.additionalProperties !== false ||
+        !s.properties ||
+        typeof s.properties !== "object" ||
+        Array.isArray(s.properties)
+      )
+        throw new Error(
+          "Object schemas require properties and additionalProperties:false",
+        );
+      if (
+        Object.keys(s.properties).some((key) =>
+          ["__proto__", "constructor", "prototype"].includes(key),
+        )
+      )
+        throw new Error(
+          "Delivery schemas explicitly disallow prototype-like property names",
+        );
+      Object.values(s.properties).forEach((child) => visit(child as Schema));
+    } else if (
+      s.properties !== undefined ||
+      s.additionalProperties !== undefined
+    )
+      throw new Error("Object keywords require object type");
+    if (s.type === "array") visit(s.items);
+    else if (s.items !== undefined)
+      throw new Error("items requires array type");
+    if (s["x-policy"] !== undefined) {
+      const p = s["x-policy"];
+      if (!p || typeof p !== "object" || Array.isArray(p))
+        throw new Error("Invalid parameter policy");
+      const keys =
+        p.kind === "copy"
+          ? ["kind", "target", "path"]
+          : p.kind === "computed"
+            ? ["kind", "producer", "version"]
+            : p.kind === "manual"
+              ? ["kind"]
+              : [];
+      if (
+        !keys.length ||
+        Object.keys(p).sort().join() !== keys.sort().join() ||
+        keys.some((k) => typeof p[k] !== "string" || (k !== "path" && !p[k]))
+      )
+        throw new Error("Invalid parameter policy fields");
+      if (p.kind === "copy") pointerParts(p.path);
+    }
+  };
+  visit(schema, true);
+  // Ajv's code generator rejects some prototype-like property names; refuse these schema
+  // names explicitly rather than silently omitting validation. strictData itself preserves them.
+  ajv.compile(schema);
+  return schema;
+}
+function attest(
+  input: Required<ParameterInputs>,
+  producers?: Record<string, TrustedParameterProducer>,
+): LeafProvenance[] {
+  const schema = checkedSchema(input.schema),
+    validate = ajv.compile(schema);
+  if (!validate(input.values))
+    throw new Error(
+      `Delivery parameter schema: ${ajv.errorsText(validate.errors)}`,
+    );
+  if (!input.target || typeof input.target !== "string")
+    throw new Error("Parameter target required");
+  const provenance: LeafProvenance[] = [];
+  const usedManual = new Set<string>(),
+    usedComputed = new Set<string>();
+  const visit = (
+    s: Schema,
+    value: unknown,
+    path: string,
+    inherited?: { policy: Policy; root: string },
+  ) => {
+    const selected = s["x-policy"]
+      ? { policy: s["x-policy"] as Policy, root: path }
+      : inherited;
+    const entries =
+      value && typeof value === "object"
+        ? Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        : [];
+    if (entries.length) {
+      for (const [key, v] of entries)
+        visit(
+          s.type === "array" ? s.items : s.properties[key],
+          v,
+          `${path}/${pointerPart(key)}`,
+          selected,
+        );
+      return;
+    }
+    if (!selected) throw new Error(`Missing parameter policy at ${path}`);
+    const p = selected.policy;
+    let observation: Record<string, unknown>;
+    if (p.kind === "copy") {
+      const sourcePath = p.path + path.slice(selected.root.length);
+      const source = ownPath(
+        input.sources,
+        [p.target, ...pointerParts(sourcePath)],
+        `Copy source ${p.target}${sourcePath}`,
+      );
+      if (canonicalJson(source) !== canonicalJson(value))
+        throw new Error(`Copy value mismatch at ${path}`);
+      observation = {
+        target: p.target,
+        path: sourcePath,
+        contentIdentity: semanticHash(source),
+        sourceIdentity: semanticHash(ownPath(input.sources, [p.target])),
+      };
+    } else if (p.kind === "manual") {
+      const o = ownPath(input.manual, [path]) as ManualObservation;
+      usedManual.add(path);
+      if (
+        !o ||
+        Object.keys(o).sort().join() !== "source,value" ||
+        typeof o.source !== "string" ||
+        !o.source ||
+        canonicalJson(o.value) !== canonicalJson(value)
+      )
+        throw new Error(`Manual observation mismatch at ${path}`);
+      observation = {
+        source: o.source,
+        contentIdentity: semanticHash(o.value),
+      };
+    } else {
+      const o = ownPath(input.computed, [path]) as ComputedObservation;
+      usedComputed.add(path);
+      if (
+        !o ||
+        Object.keys(o).sort().join() !== "inputs,output,producer,version" ||
+        o.producer !== p.producer ||
+        o.version !== p.version ||
+        canonicalJson(o.output) !== canonicalJson(value)
+      )
+        throw new Error(`Computed observation mismatch at ${path}`);
+      if (producers) {
+        const producer = ownPath(producers, [
+          p.producer,
+        ]) as TrustedParameterProducer;
+        if (
+          producer.version !== p.version ||
+          canonicalJson(
+            strictData(producer.produce(deepFreeze(strictData(o.inputs)))),
+          ) !== canonicalJson(value)
+        )
+          throw new Error(`Computed producer mismatch at ${path}`);
+      }
+      observation = {
+        producer: p.producer,
+        version: p.version,
+        inputIdentity: semanticHash(o.inputs),
+        outputIdentity: semanticHash(o.output),
+      };
+    }
+    provenance.push({
+      target: input.target,
+      path,
+      policy: p.kind,
+      valueIdentity: semanticHash(value),
+      observation,
+    });
+  };
+  visit(schema, input.values, "");
+  for (const [observations, used] of [
+    [input.manual, usedManual],
+    [input.computed, usedComputed],
+  ] as const)
+    if (Object.keys(observations).some((k) => !used.has(k)))
+      throw new Error("Unused parameter observation");
+  return provenance.sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+  );
+}
+/** Development only. Producers are a versioned trusted seam, not independent production authority. */
+export function resolveDeliveryParameters(
+  raw: ParameterInputs & {
+    producers?: Record<string, TrustedParameterProducer>;
+  },
+): ResolvedDeliveryParameters {
+  const allowed = [
+    "schema",
+    "target",
+    "values",
+    "sources",
+    "manual",
+    "computed",
+    "producers",
+  ];
+  if (
+    !raw ||
+    typeof raw !== "object" ||
+    Array.isArray(raw) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) ||
+    Object.getOwnPropertySymbols(raw).length
+  )
+    throw new Error("Parameter inputs require own data fields");
+  const detached: Record<string, unknown> = {};
+  for (const key of Object.getOwnPropertyNames(raw)) {
+    if (!allowed.includes(key))
+      throw new Error(
+        "Unsupported parameter input field (overrides are not accepted)",
+      );
+    detached[key] = ownPath(raw, [key], "parameter input");
+  }
+  raw = detached as unknown as typeof raw;
+  const input = strictData({
+    schema: raw.schema,
+    target: raw.target,
+    values: raw.values,
+    sources: raw.sources ?? {},
+    manual: raw.manual ?? {},
+    computed: raw.computed ?? {},
+  });
+  const provenance = attest(input, raw.producers ?? {});
+  const body = { version: 1 as const, ...input, provenance };
+  return deepFreeze({ ...body, identity: semanticHash(body) });
+}
+/** Consume a previously trusted identity; no fill-in, override, or producer invocation. */
+export function consumeDeliveryParameters(
+  raw: ResolvedDeliveryParameters,
+  expectedIdentity: string,
+): unknown {
+  if (arguments.length !== 2)
+    throw new Error(
+      "Production parameter consumption accepts no override arguments",
+    );
+  const result = strictData(raw);
+  if (
+    Object.keys(result).sort().join() !==
+      "computed,identity,manual,provenance,schema,sources,target,values,version" ||
+    result.version !== 1
+  )
+    throw new Error("Invalid resolved parameter envelope");
+  const { identity, ...body } = result;
+  if (identity !== expectedIdentity || identity !== semanticHash(body))
+    throw new Error("Resolved parameter identity mismatch");
+  if (canonicalJson(attest(result)) !== canonicalJson(result.provenance))
+    throw new Error("Resolved parameter provenance mismatch");
+  return deepFreeze(result.values);
+}

package/runtime/delivery/pending.ts

@@ -0,0 +1,98 @@
+/** Typed evidence consumer. Durable finalized observation production/query is supplied by the launcher (Task6a). */
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { canonicalData, canonicalJson, deepFreeze, digest, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import { assertPendingUupsCurrentState, assertPendingUupsPreparation, planDeployment, sameAddress, type PendingUupsBindingInput, type PendingUupsResolution, type PendingUupsResolverPort } from '../workflow/lib/pendingUupsBinding';
+import { parseDeliveryPlan, type DeliveryPlan } from './plan';
+import { parseDerivedBindings, type DerivedBindings } from './bindings';
+import { parsePreparationJournal, type PreparationEntry } from './journal';
+import { validateNetworkAlias } from './policy';
+export interface PendingEvidenceIdentity {
+  executionId: string; target: string; inputsHash: string; artifactHash: string; planHash: string;
+  selectedStepIds: string[];
+  infrastructure: { scheme: 'evm'; factory: string; multicall: string; placeholderImplementation: string };
+  derivedValues: DerivedBindings;
+}
+export interface ObservationReference { observationId: string; transactionId: string; transactionHash: string }
+export interface PendingUupsEvidence {
+  identity: PendingEvidenceIdentity;
+  candidate: { deploymentId: string; executionId: string; target: string; instanceId: string; contractInfoKey: string; address: string };
+  plan: DeliveryPlan; preparations: PreparationEntry[]; observations: ObservationReference[];
+}
+export interface FinalizedTransactionObservation {
+  observationId: string; executionId: string; target: string; planHash: string;
+  transaction: ReleaseExecutionTransaction; transactionHash: string;
+  receipt: { transactionHash: string; status: 1; blockNumber: string; blockHash: string };
+}
+export interface FinalizedObservationPort {
+  /** Trusted query capability must establish canonical inclusion and configured finality before returning.
+   * This consumer cannot establish finality from caller JSON or a `finalized: true` flag. */
+  readFinalized(observationId: string): Promise<FinalizedTransactionObservation | undefined>;
+}
+function hash32(raw: unknown, label: string): string {
+  if (typeof raw !== 'string' || !/^0x[\da-f]{64}$/.test(raw)) throw new Error(`Invalid ${label}`); return raw;
+}
+function parseIdentity(raw: unknown): PendingEvidenceIdentity {
+  const v = exactObject(raw, ['executionId', 'target', 'inputsHash', 'artifactHash', 'planHash', 'selectedStepIds', 'infrastructure', 'derivedValues'], 'pending evidence identity');
+  nonempty(v.executionId, 'executionId'); validateNetworkAlias(v.target, 'target', false);
+  digest(v.inputsHash, 'inputsHash'); digest(v.artifactHash, 'artifactHash'); digest(v.planHash, 'planHash');
+  if (!Array.isArray(v.selectedStepIds) || !v.selectedStepIds.length || v.selectedStepIds.some(id => typeof id !== 'string' || !id) || new Set(v.selectedStepIds).size !== v.selectedStepIds.length) throw new Error('Invalid selectedStepIds');
+  const infra = exactObject(v.infrastructure, ['scheme', 'factory', 'multicall', 'placeholderImplementation'], 'pending infrastructure');
+  if (infra.scheme !== 'evm') throw new Error('Pending delivery evidence requires EVM');
+  for (const key of ['factory', 'multicall', 'placeholderImplementation']) if (typeof infra[key] !== 'string' || !/^0x[\da-f]{40}$/.test(infra[key] as string)) throw new Error('Invalid pending infrastructure address');
+  const derived = parseDerivedBindings(v.derivedValues);
+  if (derived.executionId !== v.executionId) throw new Error('Pending derived execution identity mismatch');
+  return deepFreeze(v as unknown as PendingEvidenceIdentity);
+}
+export async function validatePendingUupsEvidence(options: {
+  input: PendingUupsBindingInput; identity: PendingEvidenceIdentity; evidence: unknown; finalized: FinalizedObservationPort;
+}): Promise<PendingUupsResolution> {
+  if (!options.finalized || typeof options.finalized.readFinalized !== 'function') throw new Error('Pending reuse requires a trusted finalized observation resolver');
+  const identity = parseIdentity(options.identity), input = options.input;
+  const v = exactObject(options.evidence, ['identity', 'candidate', 'plan', 'preparations', 'observations'], 'pending UUPS evidence');
+  if (canonicalJson(parseIdentity(v.identity)) !== canonicalJson(identity)) throw new Error('Pending evidence identity mismatch');
+  const plan = parseDeliveryPlan(v.plan);
+  if (plan.executionId !== identity.executionId || plan.target !== identity.target || plan.inputsHash !== identity.inputsHash || plan.planHash !== identity.planHash || canonicalJson(plan.derivedBindings) !== canonicalJson(identity.derivedValues)) throw new Error('Pending plan identity mismatch');
+  if (input.network !== identity.target || !identity.selectedStepIds.includes(input.stepId) || input.scheme !== identity.infrastructure.scheme || !sameAddress(input.factory, identity.infrastructure.factory) || !sameAddress(input.multicall, identity.infrastructure.multicall) || !sameAddress(input.placeholderImplementationAddress, identity.infrastructure.placeholderImplementation)) throw new Error('Pending selection/infrastructure identity mismatch');
+  const candidate = exactObject(v.candidate, ['deploymentId', 'executionId', 'target', 'instanceId', 'contractInfoKey', 'address'], 'pending candidate');
+  if (candidate.deploymentId !== input.taskId || candidate.deploymentId !== plan.deploymentId || candidate.executionId !== identity.executionId || candidate.target !== input.network || candidate.instanceId !== input.instanceId || candidate.contractInfoKey !== input.contractInfoKey) throw new Error('Pending candidate identity mismatch');
+  const preparations = parsePreparationJournal(v.preparations, plan.transactions, plan.derivedBindings, { target: plan.target, chainId: plan.chainId, expectedStepIds: plan.deploymentBindings.map(b => b.stepId) });
+  for (const entry of preparations) {
+    const binding = plan.deploymentBindings.find(b => b.stepId === entry.stepId)!;
+    if (binding.preparationHash !== entry.preparationHash || canonicalJson(binding.transactionIds) !== canonicalJson(entry.mappings.map(m => m.transactionId)) || canonicalJson(binding.derivedKeys) !== canonicalJson(entry.derivedKeys)) throw new Error('Pending plan preparation binding mismatch');
+  }
+  const matching = preparations.filter(p => p.stepId === input.stepId);
+  if (matching.length !== 1) throw new Error('Pending evidence requires exactly one matching preparation');
+  const entry = matching[0], { request, plan: gatePlan } = entry.prepared;
+  assertPendingUupsPreparation(input, entry.change, request, gatePlan);
+  const proxy = planDeployment(gatePlan, 'proxy'), implementation = planDeployment(gatePlan, 'implementation');
+  if (!sameAddress(candidate.address, proxy.address)) throw new Error('Pending candidate address mismatch');
+  if (!Array.isArray(v.observations) || v.observations.length !== plan.transactions.length || !v.observations.length) throw new Error('Pending receipt completeness mismatch');
+  const seen = new Set<string>(), observationIds: string[] = [];
+  for (const [index, raw] of v.observations.entries()) {
+    const ref = exactObject(raw, ['observationId', 'transactionId', 'transactionHash'], 'observation reference');
+    const observationId = nonempty(ref.observationId, 'observationId'), tx = plan.transactions[index];
+    if (seen.has(observationId) || ref.transactionId !== tx.transactionId) throw new Error('Duplicate or unordered pending receipt mapping');
+    seen.add(observationId); observationIds.push(observationId); hash32(ref.transactionHash, 'reference transaction hash');
+    const observed = await options.finalized.readFinalized(observationId);
+    if (!observed) throw new Error('Finalized observation is unavailable');
+    const o = exactObject(observed, ['observationId', 'executionId', 'target', 'planHash', 'transaction', 'transactionHash', 'receipt'], 'finalized observation');
+    const receipt = exactObject(o.receipt, ['transactionHash', 'status', 'blockNumber', 'blockHash'], 'finalized receipt');
+    if (o.observationId !== observationId || o.executionId !== identity.executionId || o.target !== identity.target || o.planHash !== identity.planHash || o.transactionHash !== ref.transactionHash || canonicalJson(o.transaction) !== canonicalJson(tx) || receipt.transactionHash !== o.transactionHash || receipt.status !== 1) throw new Error('Finalized receipt/transaction/plan identity mismatch');
+    hash32(o.transactionHash, 'observed transaction hash'); hash32(receipt.blockHash, 'receipt block hash');
+    if (typeof receipt.blockNumber !== 'string' || !/^(0|[1-9][0-9]*)$/.test(receipt.blockNumber)) throw new Error('Invalid finalized block number');
+  }
+  await assertPendingUupsCurrentState(input, proxy.address, implementation.address);
+  return deepFreeze({ implementationAddress: implementation.address, implementationSalt: implementation.salt, proxyAddress: proxy.address, artifactDigest: gatePlan.artifact.digest,
+    binding: { executionId: identity.executionId, target: identity.target, planHash: identity.planHash, artifactDigest: gatePlan.artifact.digest, observationIds } });
+}
+export function pendingUupsResolver(input: {
+  identity: PendingEvidenceIdentity;
+  resolveEvidence(query: PendingUupsBindingInput): Promise<unknown | undefined>;
+  finalized: FinalizedObservationPort;
+}): PendingUupsResolverPort {
+  const identity = parseIdentity(canonicalData(input.identity));
+  return { resolve: async query => {
+    const evidence = await input.resolveEvidence(query);
+    return evidence === undefined ? undefined : validatePendingUupsEvidence({ input: query, identity, evidence, finalized: input.finalized });
+  } };
+}