gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/manifest.ts

@@ -0,0 +1,54 @@
+import { parseDeliveryRequest, type DeliveryRequest } from './protocol';
+import { loadDeliveryTarget } from './config';
+import { projectDefaultNetwork } from './project';
+import { validateNetworkAlias } from './policy';
+import path from 'node:path';
+
+/** Validate every explicit selector, then bind the network Hardhat is expected to select. */
+export function resolveDeliveryRuntimeNetwork(input: {
+  root: string; request: DeliveryRequest; env?: NodeJS.ProcessEnv; argv?: string[];
+}): string {
+  const env = input.env ?? process.env;
+  const argv = input.argv ?? process.argv;
+  const argumentsFor = (name: string): string[] => {
+    const values: string[] = [];
+    for (let index = 0; index < argv.length; index++) {
+      const argument = argv[index];
+      if (argument !== name && !argument.startsWith(`${name}=`)) continue;
+      const value = argument === name ? argv[++index] : argument.slice(name.length + 1);
+      if (!value || value.startsWith('-')) throw new Error(`${name} requires a value`);
+      values.push(value);
+    }
+    return values;
+  };
+  for (const [name, values, file] of [
+    ['config', [env.HARDHAT_CONFIG, ...argumentsFor('--config')], 'hardhat.config.ts'],
+    ['tsconfig', [env.HARDHAT_TSCONFIG, ...argumentsFor('--tsconfig')], 'tsconfig.json'],
+  ] as const) {
+    for (const value of values) {
+      if (value === undefined) continue;
+      if (!value || path.resolve(input.root, value) !== path.resolve(input.root, file)) throw new Error(`Hardhat ${name} conflict with delivery project`);
+    }
+  }
+  const networks = [env.HARDHAT_NETWORK, ...argumentsFor('--network')].filter((value): value is string => value !== undefined);
+  for (const value of networks) validateNetworkAlias(value, 'Hardhat network');
+  if (new Set(networks).size > 1) throw new Error('Hardhat network selector conflict with delivery context');
+  const runner = networks[0] ?? projectDefaultNetwork(input.root);
+  if (runner !== input.request.network && !(runner === 'hardhat' && input.request.mode === 'simulate')) throw new Error('Hardhat network conflict with delivery context');
+  return runner;
+}
+
+/** Must run before importing any OZ module. A context is routing data, never execution authority. */
+export function configureDeliveryEnvironment(input: { root: string; env?: NodeJS.ProcessEnv; argv?: string[] }): string | undefined {
+  const env = input.env ?? process.env;
+  if (env.GATE_DELIVERY_CONTEXT === undefined) return undefined;
+  const request = parseDeliveryRequest(JSON.parse(env.GATE_DELIVERY_CONTEXT));
+  resolveDeliveryRuntimeNetwork({ ...input, request, env });
+  const target = loadDeliveryTarget(input.root, request.network, request.environment);
+  const dir = target.openzeppelin.manifestDir;
+  if (env.MANIFEST_DEFAULT_DIR && env.MANIFEST_DEFAULT_DIR !== dir) throw new Error('MANIFEST_DEFAULT_DIR conflict with delivery context');
+  if (env.GATE_WORKFLOW_TARGET && env.GATE_WORKFLOW_TARGET !== request.network) throw new Error('GATE_WORKFLOW_TARGET conflict with delivery context');
+  env.MANIFEST_DEFAULT_DIR = dir;
+  env.GATE_WORKFLOW_TARGET = request.network;
+  return dir;
+}

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/parameter-defaults.ts

@@ -0,0 +1,75 @@
+/** Expand task-owned defaults before schema/provenance validation. Never a production override port. */
+import { ownPath, pointerPart } from './data';
+import { object } from './protocol';
+import { canonicalJson, exactObject } from '../workflow/lib/canonicalData';
+
+type Observations = { manual: Record<string, unknown>; computed: Record<string, unknown> };
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+function observations(raw: unknown): Observations {
+  const value = exactObject(raw, ['manual', 'computed'], 'target provenance');
+  return { manual: object(value.manual, 'manual observations'), computed: object(value.computed, 'computed observations') };
+}
+function leaves(value: unknown, path = '', result = new Map<string, unknown>()): Map<string, unknown> {
+  const entries = value !== null && typeof value === 'object' ? Object.entries(value) : [];
+  if (!entries.length) result.set(path, value);
+  else for (const [key, child] of entries) leaves(child, `${path}/${pointerPart(key)}`, result);
+  return result;
+}
+function merge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries([...new Set([...Object.keys(base), ...Object.keys(override)])].map(key => [key,
+    !Object.hasOwn(override, key) ? base[key]
+      : Object.hasOwn(base, key) && record(base[key]) && record(override[key]) ? merge(base[key], override[key])
+        : override[key],
+  ]));
+}
+/** Only leaves actually inherited from defaults may inherit default observations. Arrays replace as a unit. */
+function inheritedLeaves(base: unknown, override: unknown, path = '', result = new Set<string>()): Set<string> {
+  if (!record(base) || !record(override)) return result;
+  for (const [key, value] of Object.entries(base)) {
+    const child = `${path}/${pointerPart(key)}`;
+    if (!Object.hasOwn(override, key)) for (const pointer of leaves(value, child).keys()) result.add(pointer);
+    else if (record(value) && record(override[key])) inheritedLeaves(value, override[key], child, result);
+  }
+  // The empty root/container is itself a schema leaf.
+  if (!Object.keys(base).length && !Object.keys(override).length) result.add(path);
+  return result;
+}
+
+export function resolveParameterTargets(rawValues: unknown, rawProvenance: unknown, networks: readonly string[]): {
+  params: Record<string, unknown>; observations: Record<string, Observations>; definitions: Record<string, unknown>;
+} {
+  const values = object(rawValues, 'parameters.yaml', ['defaults', 'params']);
+  const params = object(ownPath(values, ['params'], 'target parameters'), 'target parameters');
+  const provenance = object(rawProvenance, 'parameters provenance', ['version', 'producers', 'defaults', 'targets']);
+  if (provenance.version !== 1) throw new Error('Unsupported provenance version');
+  const definitions = object(provenance.producers, 'producers'), targets = object(provenance.targets, 'provenance targets');
+  for (const name of [...Object.keys(params), ...Object.keys(targets)])
+    if (!networks.includes(name)) throw new Error('Unknown parameter target');
+  const observed = Object.fromEntries(Object.entries(targets).map(([name, value]) => [name, observations(value)]));
+  if (!Object.hasOwn(values, 'defaults')) {
+    if (Object.hasOwn(provenance, 'defaults')) throw new Error('Default provenance requires parameter defaults');
+    return { params, observations: observed, definitions };
+  }
+  const defaults = object(values.defaults, 'parameter defaults');
+  const shared = Object.hasOwn(provenance, 'defaults') ? observations(provenance.defaults) : { manual: {}, computed: {} };
+  const defaultLeaves = leaves(defaults);
+  for (const kind of ['manual', 'computed'] as const) for (const [path, raw] of Object.entries(shared[kind])) {
+    if (!defaultLeaves.has(path)) throw new Error(`Unused default parameter observation at ${path}`);
+    const observation = exactObject(raw, kind === 'manual' ? ['source', 'value'] : ['producer', 'version', 'inputs', 'output'], 'default observation');
+    if (canonicalJson(observation[kind === 'manual' ? 'value' : 'output']) !== canonicalJson(defaultLeaves.get(path)))
+      throw new Error(`Default observation mismatch at ${path}`);
+  }
+  const effective = Object.fromEntries(networks.map(name => {
+    const override = Object.hasOwn(params, name) ? object(params[name], 'network parameter overrides') : {};
+    return [name, merge(defaults, override)];
+  }));
+  const effectiveObservations = Object.fromEntries(networks.map(name => {
+    const override = Object.hasOwn(params, name) ? params[name] : {};
+    const inherited = inheritedLeaves(defaults, override), local = Object.hasOwn(observed, name) ? observed[name] : { manual: {}, computed: {} };
+    return [name, Object.fromEntries((['manual', 'computed'] as const).map(kind => [kind, {
+      ...Object.fromEntries(Object.entries(shared[kind]).filter(([path]) => inherited.has(path))), ...local[kind],
+    }])) as Observations];
+  }));
+  return { params: effective, observations: effectiveObservations, definitions };
+}

package/runtime/delivery/parameters.ts

@@ -0,0 +1,367 @@
+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) });
+}
+/** Read-only migration check, never a producer receipt or production authority. */
+export function validateHistoricalParameterExtension(previous: ResolvedDeliveryParameters, current: ParameterInputs): ResolvedDeliveryParameters {
+  consumeDeliveryParameters(previous, previous.identity);
+  const input = strictData({schema: current.schema, target: current.target, values: current.values,
+    sources: current.sources ?? {}, manual: current.manual ?? {}, computed: current.computed ?? {}});
+  if (input.target !== previous.target) throw Error('Historical parameter target changed');
+  // A historical consumer cannot rerun or grant authority to a newly introduced producer.
+  for (const [pointer, observation] of Object.entries(input.computed)) {
+    if (canonicalJson(observation) !== canonicalJson(previous.computed[pointer] ?? null)) throw Error('Historical computed parameter changed; new development acceptance required');
+  }
+  const provenance = attest(input);
+  for (const leaf of previous.provenance) {
+    const next = provenance.find(candidate => candidate.path === leaf.path);
+    if (!next || canonicalJson(next) !== canonicalJson(leaf)) throw Error(`Historical parameter value/provenance changed: ${leaf.path}`);
+  }
+  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);
+}