@hyperscale0/udl 2.2.0 → 2.4.0

package/src/validation.ts

@@ -1,3 +1,5 @@
+import { referencePatternPrefix } from "./reference.js";
+import { validateVocabulary } from "./vocabulary.js";
 import {
   Validator,
   type OutputUnit,
@@ -19,11 +21,14 @@ import {
   type UdlInstrument,
   type UdlStep,
   type UdlAction,
+  type UdlPieceStageStage,
 } from "./schema.js";
 import { fixedIsoDurationMs } from "./duration.js";
 import {
   analyzeInstrumentFinance,
   financeAdmissionProblem,
+  type FinanceIssue,
+  type FinanceOptions,
 } from "./finance.js";
 import { UDL_LIMITS } from "./limits.js";
 import {
@@ -65,6 +70,12 @@ export interface UdlValidationOptions {
   readonly requireDecisionPartyBindings?: boolean;
 }
 
+/**
+ * Validate a complete document. Clause references to instruments must resolve
+ * within this document, even when the reference field is optional. A catalogue
+ * slice must include its referenced instruments; an external catalogue cannot
+ * supply missing product laws. Reference fields use the sealed public ID grammar.
+ */
 export function validateUdl(
   value: unknown,
   options: UdlValidationOptions = {},
@@ -293,6 +304,26 @@ function semanticIssues(
   validateDocumentSchemas(document, add);
   if (issues.length > 0) return issues;
 
+  // Vocabulary laws must accumulate with the existing semantic diagnostics.
+  validateVocabulary(document.instruments, (path, message) =>
+    add(
+      path,
+      message,
+      path.some((part) =>
+        [
+          "attests",
+          "requiresInput",
+          "engineOwned",
+          "captureEngine",
+          "unique",
+          "port",
+        ].includes(String(part)),
+      )
+        ? "UDL5001"
+        : shapeIssueCode(path),
+    ),
+  );
+
   addDuplicateIssues(
     document.subjects.map((subject) => subject.kind),
     ["subjects"],
@@ -313,7 +344,6 @@ function semanticIssues(
   );
 
   validateCompositionDials(document, add);
-  validateInstrumentJourneys(document, add);
 
   const subjects = new Map(
     document.subjects.map((subject) => [subject.kind, subject] as const),
@@ -413,162 +443,6 @@ function semanticIssues(
   return issues;
 }
 
-const scopedIdPattern =
-  /^\^([a-z]{2,8})_\(sandbox\|live\)_\[a-z0-9\]\{8,64\}\$$/;
-
-function camel(value: string): string {
-  return value.replace(/_([a-z0-9])/g, (_match, character: string) =>
-    character.toUpperCase(),
-  );
-}
-
-function journeyReferenceFields(
-  instrument: UdlInstrument,
-  actionName: string,
-): ReadonlyMap<string, string> {
-  const action = instrument.actions[actionName];
-  if (!action) return new Map();
-  const fields = new Map<string, string>();
-  const addSchema = (name: string, schema: unknown) => {
-    const pattern = recordValue(schema).pattern;
-    if (typeof pattern !== "string") return;
-    const prefix = scopedIdPattern.exec(pattern)?.[1];
-    if (prefix) fields.set(name, prefix);
-  };
-  if (actionName === "create") {
-    const derivedFields = new Set(
-      (action.requiresRefs ?? []).flatMap((gate) =>
-        Object.keys(gate.bind ?? {}),
-      ),
-    );
-    for (const name of instrument.required) {
-      if (!derivedFields.has(name)) addSchema(name, instrument.fields[name]);
-    }
-  } else {
-    fields.set(`${camel(instrument.id)}Id`, instrument.idPrefix);
-  }
-  const input = recordValue(action.input);
-  const required = Array.isArray(input.required)
-    ? input.required.filter((name): name is string => typeof name === "string")
-    : [];
-  const properties = recordValue(input.properties);
-  for (const name of required) addSchema(name, properties[name]);
-  return fields;
-}
-
-/**
- * Validate the part of authored journeys that canonical UDL can prove alone.
- * A caller with the operation catalog validates root-operation examples and
- * cross-kind bindings. UDL owns local examples, lifecycle order, and local
- * reference completeness so raw UDL cannot bypass those laws.
- */
-function validateInstrumentJourneys(
-  document: UdlDocument,
-  add: AddIssue,
-): void {
-  const instruments = new Map(
-    document.instruments.map(
-      (instrument) => [instrument.id, instrument] as const,
-    ),
-  );
-  for (const [instrumentIndex, owner] of document.instruments.entries()) {
-    for (const [journeyIndex, journey] of (owner.journeys ?? []).entries()) {
-      const base = [
-        "instruments",
-        instrumentIndex,
-        "journeys",
-        journeyIndex,
-      ] as const;
-      const seen = new Set<string>();
-      const createdKindByStep = new Map<string, string>();
-      const stateByStep = new Map<string, string>();
-      for (const [stepIndex, step] of journey.steps.entries()) {
-        const stepBase = [...base, "steps", stepIndex] as const;
-        if (step.id) {
-          if (seen.has(step.id)) {
-            add(
-              [...stepBase, "id"],
-              `journey ${journey.id} declares step id ${step.id} more than once`,
-              "journey_duplicate_step_id",
-            );
-          }
-        }
-        const [instrumentId, actionName] = step.operation.split(".");
-        const instrument = instrumentId
-          ? instruments.get(instrumentId)
-          : undefined;
-        const action =
-          instrument && actionName ? instrument.actions[actionName] : undefined;
-        if (!instrument) {
-          if (step.id) seen.add(step.id);
-          continue;
-        }
-        if (!action || !actionName) {
-          add(
-            [...stepBase, "operation"],
-            `journey ${journey.id} names unknown operation ${step.operation}`,
-            "journey_unknown_operation",
-          );
-          continue;
-        }
-        if (
-          !action.examples?.some((example) => example.name === step.example)
-        ) {
-          add(
-            [...stepBase, "example"],
-            `journey ${journey.id} names unknown example ${step.example} on ${step.operation}`,
-            "journey_unknown_example",
-          );
-        }
-        for (const [field, prefix] of journeyReferenceFields(
-          instrument,
-          actionName,
-        )) {
-          const producer = step.bind[field];
-          if (!producer || !seen.has(producer)) {
-            add(
-              [...stepBase, "bind", field],
-              `journey ${journey.id} must bind ${step.operation}.${field} to an earlier step`,
-              "journey_unbound_reference",
-            );
-            continue;
-          }
-          const producedPrefix = createdKindByStep.get(producer);
-          if (producedPrefix && producedPrefix !== prefix) {
-            add(
-              [...stepBase, "bind", field],
-              `journey ${journey.id} binds ${step.operation}.${field} to ${producer}, which creates ${producedPrefix} instead of ${prefix}`,
-              "journey_unbound_reference",
-            );
-          }
-        }
-        if (actionName === "create") {
-          if (step.id) {
-            createdKindByStep.set(step.id, instrument.idPrefix);
-            stateByStep.set(step.id, instrument.lifecycle.initial);
-            seen.add(step.id);
-          }
-          continue;
-        }
-        const transition = instrument.lifecycle.transitions[actionName];
-        if (!transition) continue;
-        const ownProducer = step.bind[`${camel(instrument.id)}Id`];
-        const state = ownProducer ? stateByStep.get(ownProducer) : undefined;
-        if (state && !transition.from.includes(state)) {
-          add(
-            [...stepBase, "operation"],
-            `journey ${journey.id} runs ${step.operation} from ${state}; allowed states are ${transition.from.join(", ")}`,
-            "journey_invalid_transition",
-          );
-        } else if (ownProducer) {
-          stateByStep.set(ownProducer, transition.to);
-        }
-        if (step.id) seen.add(step.id);
-      }
-    }
-  }
-}
-
 function structuralBudgetIssue(value: unknown): UdlIssue | undefined {
   let discovered = 1;
   let nodes = 0;
@@ -1365,90 +1239,366 @@ function validateInstrument(
     }
   }
 
-  // Multi-variant finance oracle check across action plan combinations
+  for (const finIssue of instrumentFinanceIssues(instrument, {
+    plans: planResolution.plans,
+  })) {
+    add([...base, ...finIssue.path], finIssue.message, finIssue.code);
+  }
+  validateAggregates(instrument, base, instruments, references, add);
+}
+
+/**
+ * The finance oracle over an instrument's resolved action plans, with paths
+ * rooted at the instrument. A piece-plan instrument is unfolded over the
+ * runtime's piece progress; any other instrument runs once per action plan
+ * combination. Contract-side callers pass the UDL projection of a blueprint
+ * definition so both boundaries prove the same machine.
+ */
+export function instrumentFinanceIssues(
+  instrument: UdlInstrument,
+  options: FinanceOptions & {
+    readonly plans?: readonly ResolvedActionPlan[];
+  } = {},
+): readonly FinanceIssue[] {
+  const plans = options.plans ?? resolveUdlActionPlans(instrument).plans;
+  const financeOptions: FinanceOptions =
+    options.penaltyMayBeNonzero === undefined
+      ? {}
+      : { penaltyMayBeNonzero: options.penaltyMayBeNonzero };
+  const issues: FinanceIssue[] = [];
+  const seen = new Set<string>();
+  const add = (
+    path: readonly PropertyKey[],
+    message: string,
+    code: UdlIssueCode,
+  ): void => {
+    const key = `${code}:${path.join(".")}:${message}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    issues.push({ code, message, path });
+  };
+
+  const expansion = instrument.piecePlan
+    ? expandPieceProgress(instrument, plans)
+    : undefined;
+  if (expansion === "bound") {
+    add(
+      ["actions"],
+      `piece progress expansion exceeds reachable variant bound of ${UDL_LIMITS.maxActionExpansion}`,
+      "UDL2010",
+    );
+    return issues;
+  }
+  if (expansion) {
+    for (const finIssue of analyzeInstrumentFinance(
+      expansion.instrument,
+      financeOptions,
+    )) {
+      const message = expansion.displayNames.reduce(
+        (text, [expanded, display]) => text.replaceAll(expanded, display),
+        finIssue.message,
+      );
+      add(originFinancePath(expansion, finIssue.path), message, finIssue.code);
+    }
+    return issues;
+  }
+
   const actionsWithPlans = Object.keys(instrument.actions).filter((aName) =>
-    planResolution.plans.some((p) => p.action === aName),
+    plans.some((p) => p.action === aName),
   );
-
   let totalCombinations = 1;
   const actionPlanMap: Record<string, ResolvedActionPlan[]> = {};
   for (const aName of actionsWithPlans) {
-    const actionPlans = planResolution.plans.filter((p) => p.action === aName);
+    const actionPlans = plans.filter((p) => p.action === aName);
     actionPlanMap[aName] = actionPlans;
     totalCombinations *= actionPlans.length;
   }
-
   if (
     actionsWithPlans.length > 0 &&
     totalCombinations > UDL_LIMITS.maxActionExpansion
   ) {
     add(
-      [...base, "actions"],
+      ["actions"],
       `variant expansion exceeds combination bound of ${UDL_LIMITS.maxActionExpansion} (${totalCombinations} combinations)`,
       "UDL2010",
     );
-  } else {
-    const generateCombos = (
-      keys: string[],
-    ): Record<string, ResolvedActionPlan>[] => {
-      if (keys.length === 0) return [{}];
-      const [first, ...rest] = keys;
-      const restCombos = generateCombos(rest);
-      const result: Record<string, ResolvedActionPlan>[] = [];
-      for (const plan of actionPlanMap[first!]!) {
-        for (const combo of restCombos) {
-          result.push({ ...combo, [first!]: plan });
-        }
+    return issues;
+  }
+  const generateCombos = (
+    keys: string[],
+  ): Record<string, ResolvedActionPlan>[] => {
+    if (keys.length === 0) return [{}];
+    const [first, ...rest] = keys;
+    const restCombos = generateCombos(rest);
+    const result: Record<string, ResolvedActionPlan>[] = [];
+    for (const plan of actionPlanMap[first!]!) {
+      for (const combo of restCombos) {
+        result.push({ ...combo, [first!]: plan });
       }
-      return result;
-    };
+    }
+    return result;
+  };
+  const combinations =
+    actionsWithPlans.length > 0 ? generateCombos(actionsWithPlans) : [{}];
+  for (const combo of combinations) {
+    const expandedActions: Record<string, UdlAction> = {};
+    for (const [aName, aDef] of Object.entries(instrument.actions)) {
+      expandedActions[aName] = planExpandedAction(aDef, combo[aName]);
+    }
+    for (const finIssue of analyzeInstrumentFinance(
+      { ...instrument, actions: expandedActions },
+      financeOptions,
+    )) {
+      add(finIssue.path, finIssue.message, finIssue.code);
+    }
+  }
+  return issues;
+}
 
-    const combinations =
-      actionsWithPlans.length > 0 ? generateCombos(actionsWithPlans) : [{}];
-    const seenFinanceIssues = new Set<string>();
+/**
+ * Only an action that moves money through calls is replaced by its expanded
+ * leaves. Authored moves and steps always reach the oracle.
+ */
+function planExpandedAction(
+  definition: UdlAction,
+  plan: ResolvedActionPlan | undefined,
+): UdlAction {
+  if (!plan || (definition.calls?.length ?? 0) === 0) return definition;
+  const steps: UdlStep[] = [];
+  const moves: UdlMove[] = [];
+  for (const leaf of plan.leaves) {
+    if ("key" in leaf.step) {
+      moves.push(leaf.step as UdlMove);
+    } else {
+      steps.push(leaf.step as UdlStep);
+    }
+  }
+  return { ...definition, moves, steps };
+}
 
-    for (const combo of combinations) {
-      const expandedActions: Record<
-        string,
-        (typeof instrument.actions)[string]
-      > = {};
-      for (const [aName, aDef] of Object.entries(instrument.actions)) {
-        const plan = combo[aName];
-        // Only an action that moves money through calls is replaced by its
-        // expanded leaves. Authored moves and steps always reach the oracle.
-        if (plan && (aDef.calls?.length ?? 0) > 0) {
-          const steps: UdlStep[] = [];
-          const moves: UdlMove[] = [];
-          for (const leaf of plan.leaves) {
-            if ("key" in leaf.step) {
-              moves.push(leaf.step as UdlMove);
-            } else {
-              steps.push(leaf.step as UdlStep);
-            }
-          }
-          expandedActions[aName] = {
-            ...aDef,
-            moves,
-            steps,
-          };
-        } else {
-          expandedActions[aName] = aDef;
-        }
+interface PieceProgress {
+  readonly funded: readonly string[];
+  readonly consumed: readonly string[];
+}
+
+interface PieceProgressExpansion {
+  readonly instrument: UdlInstrument;
+  /** Expanded action name to display name, longest first. */
+  readonly displayNames: readonly (readonly [string, string])[];
+  readonly actionOrigins: ReadonlyMap<
+    string,
+    {
+      readonly action: string;
+      readonly leafOrigins?: readonly (readonly string[])[];
+    }
+  >;
+  readonly stateOrigins: ReadonlyMap<string, string>;
+  readonly originStates: readonly string[];
+}
+
+function progressKey(progress: PieceProgress): string {
+  return `${progress.funded.join(",")}|${progress.consumed.join(",")}`;
+}
+
+/** Mirrors eligiblePieces in the engine's piece-plan dispatcher. */
+function eligiblePieces(
+  plan: NonNullable<UdlInstrument["piecePlan"]>,
+  stage: UdlPieceStageStage,
+  progress: PieceProgress,
+): readonly string[] {
+  return plan[`${stage}_order`].filter((id) =>
+    stage === "fund"
+      ? !progress.funded.includes(id)
+      : progress.funded.includes(id) && !progress.consumed.includes(id),
+  );
+}
+
+/**
+ * Unfolds a piece-plan instrument over the runtime's piece progress so the
+ * ordinary lifecycle oracle sees exactly the states the dispatcher admits: a
+ * piece-stage action moves the next eligible piece of its stage order, the
+ * lifecycle state is retained until the stage's last piece moves, funding
+ * cannot resume once a piece has left escrow, and an action gated on a drained
+ * account is closed while a funded piece is still held. Every expanded state is
+ * one (lifecycle state, progress) pair; expanded action names carry the piece
+ * and the source state so each has exactly one transition. A quote-commit pair
+ * is not carried through the expansion.
+ */
+function expandPieceProgress(
+  instrument: UdlInstrument,
+  plans: readonly ResolvedActionPlan[],
+): PieceProgressExpansion | "bound" | undefined {
+  const plan = instrument.piecePlan;
+  if (!plan) return undefined;
+  const stateName = (state: string, progress: PieceProgress): string =>
+    `${state}#${progressKey(progress)}`;
+  const initialProgress: PieceProgress = { funded: [], consumed: [] };
+  const stateOrigins = new Map<string, string>();
+  const actionOrigins = new Map<
+    string,
+    { action: string; leafOrigins?: readonly (readonly string[])[] }
+  >();
+  const displayNames: [string, string][] = [];
+  const actions: Record<string, UdlAction> = {};
+  const transitions: Record<string, { from: string[]; to: string }> = {};
+  const pending: { state: string; progress: PieceProgress }[] = [
+    { state: instrument.lifecycle.initial, progress: initialProgress },
+  ];
+  stateOrigins.set(
+    stateName(instrument.lifecycle.initial, initialProgress),
+    instrument.lifecycle.initial,
+  );
+
+  const visit = (state: string, progress: PieceProgress): void => {
+    const name = stateName(state, progress);
+    if (stateOrigins.has(name)) return;
+    stateOrigins.set(name, state);
+    pending.push({ state, progress });
+  };
+
+  while (pending.length > 0) {
+    const { state, progress } = pending.shift()!;
+    if (stateOrigins.size > UDL_LIMITS.maxActionExpansion) return "bound";
+    const held = progress.funded.filter(
+      (id) => !progress.consumed.includes(id),
+    );
+    for (const [actionName, transition] of Object.entries(
+      instrument.lifecycle.transitions,
+    )) {
+      if (!transition.from.includes(state)) continue;
+      const definition = instrument.actions[actionName];
+      if (!definition) continue;
+      if (definition.requiresDrainedAccount && held.length > 0) continue;
+      const stage = definition.pieceStage;
+      if (!stage) {
+        const expanded = `${actionName}#${state}#${progressKey(progress)}`;
+        const variant = plans.find(
+          (candidate) => candidate.action === actionName,
+        );
+        actions[expanded] = planExpandedAction(definition, variant);
+        transitions[expanded] = {
+          from: [stateName(state, progress)],
+          to: stateName(transition.to, progress),
+        };
+        actionOrigins.set(expanded, {
+          action: actionName,
+          ...(variant && (definition.calls?.length ?? 0) > 0
+            ? { leafOrigins: variant.leaves.map((leaf) => leaf.originPath) }
+            : {}),
+        });
+        displayNames.push([expanded, actionName]);
+        visit(transition.to, progress);
+        continue;
       }
-      const financeInstrument = {
-        ...instrument,
-        actions: expandedActions,
+      if (stage.plan !== plan.id) continue;
+      if (stage.stage === "fund" && progress.consumed.length > 0) continue;
+      const eligible = eligiblePieces(plan, stage.stage, progress);
+      const pieceId = eligible[0];
+      if (pieceId === undefined) continue;
+      const variant = plans.find(
+        (candidate) =>
+          candidate.action === actionName && candidate.pieceId === pieceId,
+      );
+      if (!variant) continue;
+      const next: PieceProgress =
+        stage.stage === "fund"
+          ? {
+              funded: [...progress.funded, pieceId],
+              consumed: progress.consumed,
+            }
+          : {
+              funded: progress.funded,
+              consumed: [...progress.consumed, pieceId],
+            };
+      const stageComplete =
+        eligiblePieces(plan, stage.stage, next).length === 0;
+      const target = stageComplete ? transition.to : state;
+      const expanded = `${actionName}@${pieceId}#${state}#${progressKey(progress)}`;
+      actions[expanded] = planExpandedAction(definition, variant);
+      transitions[expanded] = {
+        from: [stateName(state, progress)],
+        to: stateName(target, next),
       };
-      for (const finIssue of analyzeInstrumentFinance(financeInstrument)) {
-        const issueKey = `${finIssue.code}:${finIssue.path.join(".")}:${finIssue.message}`;
-        if (!seenFinanceIssues.has(issueKey)) {
-          seenFinanceIssues.add(issueKey);
-          add([...base, ...finIssue.path], finIssue.message, finIssue.code);
-        }
-      }
+      actionOrigins.set(expanded, {
+        action: actionName,
+        leafOrigins: variant.leaves.map((leaf) => leaf.originPath),
+      });
+      displayNames.push([expanded, `${actionName}[${pieceId}]`]);
+      visit(target, next);
     }
   }
-  validateAggregates(instrument, base, instruments, references, add);
+
+  for (const [actionName, definition] of Object.entries(instrument.actions)) {
+    if (Object.hasOwn(instrument.lifecycle.transitions, actionName)) continue;
+    actions[actionName] = planExpandedAction(
+      definition,
+      plans.find((candidate) => candidate.action === actionName),
+    );
+    actionOrigins.set(actionName, { action: actionName });
+  }
+
+  return {
+    instrument: {
+      ...instrument,
+      actions,
+      lifecycle: {
+        initial: stateName(instrument.lifecycle.initial, initialProgress),
+        states: [...stateOrigins.keys()],
+        transitions,
+      },
+    },
+    displayNames: [
+      ...displayNames,
+      ...[...stateOrigins.entries()].map(
+        ([expanded, origin]): [string, string] => [expanded, origin],
+      ),
+    ].sort((left, right) => right[0].length - left[0].length),
+    actionOrigins,
+    stateOrigins,
+    originStates: instrument.lifecycle.states,
+  };
+}
+
+function originFinancePath(
+  expansion: PieceProgressExpansion,
+  path: readonly PropertyKey[],
+): readonly PropertyKey[] {
+  const [head, second, third, fourth, ...rest] = path;
+  if (
+    head === "lifecycle" &&
+    second === "states" &&
+    typeof third === "number"
+  ) {
+    const expandedState = expansion.instrument.lifecycle.states[third];
+    const origin =
+      expandedState === undefined
+        ? undefined
+        : expansion.stateOrigins.get(expandedState);
+    const index =
+      origin === undefined ? -1 : expansion.originStates.indexOf(origin);
+    return index >= 0
+      ? ["lifecycle", "states", index]
+      : ["lifecycle", "states"];
+  }
+  if (head === "actions" && typeof second === "string") {
+    const origin = expansion.actionOrigins.get(second);
+    if (!origin) return path;
+    if (
+      third === "moves" &&
+      typeof fourth === "number" &&
+      origin.leafOrigins?.[fourth]
+    ) {
+      return ["actions", ...origin.leafOrigins[fourth], ...rest];
+    }
+    return [
+      "actions",
+      origin.action,
+      ...(third === undefined ? [] : [third]),
+      ...(fourth === undefined ? [] : [fourth]),
+      ...rest,
+    ];
+  }
+  return path;
 }
 
 function validatePiecePlan(
@@ -2637,7 +2787,11 @@ function validateActionUpdates(
       add(fieldPath, `updated field ${field} is an aggregate cap`, "UDL5008");
     }
   });
-  if (definition.moves.length > 0) {
+  if (
+    definition.moves.length > 0 ||
+    definition.allocate ||
+    definition.contributionStage
+  ) {
     add(
       [...actionBase, "updates"],
       "an action cannot update fields while moving money",
@@ -2716,6 +2870,33 @@ function validateRemainder(
       "UDL4001",
     );
   }
+  addDuplicateIssues(
+    remainder.subtractPaths ?? [],
+    [...remainderBase, "subtractPaths"],
+    "remainder operand",
+    add,
+  );
+  for (const path of remainder.subtractPaths ?? []) {
+    const [root, key] = path.split(".");
+    const declared =
+      root === "fields" &&
+      key !== undefined &&
+      isMoneySchema(instrument.fields[key] ?? {}) &&
+      !instrument.update?.fields.includes(key) &&
+      !Object.values(instrument.actions).some((action) =>
+        action.updates?.includes(key),
+      );
+    if (
+      !declared ||
+      path === remainder.totalPath ||
+      path === `refs.${remainder.amountRef}`
+    )
+      add(
+        [...remainderBase, "subtractPaths"],
+        `remainder subtraction ${path} must name distinct immutable money`,
+        "UDL4001",
+      );
+  }
   const [totalRoot, totalKey] = remainder.totalPath.split(".");
   const totalDeclared =
     (totalRoot === "fields" &&
@@ -2910,10 +3091,24 @@ function validateActions(
     );
 
     if (definition.requiresRefs) {
+      const boundFields = new Map<string, string>();
+      for (const gate of definition.requiresRefs) {
+        for (const [field, path] of Object.entries(gate.bind ?? {})) {
+          const source = `${gate.field}:${path}`;
+          const previous = boundFields.get(field);
+          if (previous !== undefined && previous !== source)
+            add(
+              [...actionBase, "requiresRefs"],
+              `reference gates bind ${field} from conflicting sources`,
+              "UDL5001",
+            );
+          boundFields.set(field, source);
+        }
+      }
       addDuplicateIssues(
-        definition.requiresRefs.map((gate) => gate.field),
+        definition.requiresRefs.map((gate) => JSON.stringify(sortObject(gate))),
         [...actionBase, "requiresRefs"],
-        "gate field",
+        "gate",
         add,
       );
       definition.requiresRefs.forEach((gate, gateIndex) => {
@@ -3023,6 +3218,7 @@ function validateActions(
         ...Object.entries(instrument.actions).flatMap(
           ([candidateAction, candidate]) => [
             ...Object.keys(candidate.captureInput ?? {}),
+            ...Object.keys(candidate.captureEngine ?? {}),
             ...[...candidate.steps, ...candidate.moves].flatMap((step) =>
               Object.keys(step.capture ?? {}),
             ),
@@ -3223,7 +3419,7 @@ function validateActions(
         );
       }
       if (
-        definition.due.offset &&
+        typeof definition.due.offset === "string" &&
         fixedIsoDurationMs(definition.due.offset) === null
       ) {
         add(
@@ -3258,7 +3454,7 @@ function validateActions(
         );
       }
       if (
-        definition.deadline.offset &&
+        typeof definition.deadline.offset === "string" &&
         fixedIsoDurationMs(definition.deadline.offset) === null
       ) {
         add(
@@ -3858,9 +4054,10 @@ function validatePayoutsAndSettlement(
   }
 
   const reservedRefs = new Set([
-    ...Object.values(instrument.actions).flatMap((action) =>
-      Object.keys(action.captureInput ?? {}),
-    ),
+    ...Object.values(instrument.actions).flatMap((action) => [
+      ...Object.keys(action.captureInput ?? {}),
+      ...Object.keys(action.captureEngine ?? {}),
+    ]),
     ...Object.values(instrument.actions).flatMap((action) =>
       [...action.steps, ...action.moves].flatMap((step) =>
         Object.keys(step.capture ?? {}),
@@ -3887,6 +4084,9 @@ function validatePayoutsAndSettlement(
           ]
         : [],
     ),
+    ...Object.values(instrument.actions).flatMap((action) =>
+      action.allocate ? [action.allocate.capture] : [],
+    ),
     ...quoteRefKeys(instrument),
     ...(instrument.subject ? ["subject"] : []),
   ]);
@@ -4419,9 +4619,10 @@ function declaredRefKeys(instrument: UdlInstrument): ReadonlySet<string> {
     ...Object.values(instrument.actions).flatMap((action) =>
       (action.reconcile ?? []).map((reconcile) => reconcile.capture),
     ),
-    ...Object.values(instrument.actions).flatMap((action) =>
-      Object.keys(action.captureInput ?? {}),
-    ),
+    ...Object.values(instrument.actions).flatMap((action) => [
+      ...Object.keys(action.captureInput ?? {}),
+      ...Object.keys(action.captureEngine ?? {}),
+    ]),
     ...Object.values(instrument.actions).flatMap((action) =>
       [...action.steps, ...action.moves].flatMap((step) =>
         Object.keys(step.capture ?? {}),
@@ -4435,6 +4636,9 @@ function declaredRefKeys(instrument: UdlInstrument): ReadonlySet<string> {
           ]
         : [],
     ),
+    ...Object.values(instrument.actions).flatMap((action) =>
+      action.allocate ? [action.allocate.capture] : [],
+    ),
     ...quoteRefKeys(instrument),
     ...(instrument.subject ? ["subject"] : []),
   ]);
@@ -5275,34 +5479,28 @@ function reconcileExceptionProblemMessage(
  * are written once. The value is disposable: no document ever carries it, and
  * a host's real id grammar stays the host's business.
  */
-const probeIdFor = (prefix: string): string =>
-  `${prefix}_sandbox_0123456789abcdef`;
-
-/** A prefix no host mints, so a schema that accepts it accepts anything. */
-const UNCLAIMED_PREFIX = "zzzz";
-
+/** Classify the sealed ID pattern without compiling document-authored regexes. */
 export function openReferenceShapeBudget(): ReferenceShapeBudget {
   const answers = new WeakMap<object, Map<string, boolean>>();
   let probes = 0;
+  let exhausted = false;
   return {
     accepts(schema, prefix) {
       const seen = answers.get(schema);
       const cached = seen?.get(prefix);
       if (cached !== undefined) return cached;
-      if (probes >= UDL_LIMITS.maxSchemaProbes) return false;
+      if (probes >= UDL_LIMITS.maxSchemaProbes) {
+        exhausted = true;
+        return false;
+      }
       probes += 1;
-
-      const answer =
-        validateUdlSchemaValue(schema, probeIdFor(prefix)).errors.length ===
-          0 &&
-        validateUdlSchemaValue(schema, probeIdFor(UNCLAIMED_PREFIX)).errors
-          .length > 0;
+      const answer = referencePatternPrefix(schema) === prefix;
       if (seen) seen.set(prefix, answer);
       else answers.set(schema, new Map([[prefix, answer]]));
       return answer;
     },
     get exhausted() {
-      return probes >= UDL_LIMITS.maxSchemaProbes;
+      return exhausted;
     },
   };
 }
@@ -5447,3 +5645,14 @@ function jsonPath(path: readonly PropertyKey[]): string {
   }
   return result;
 }
+
+function sortObject(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortObject);
+  if (value !== null && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => [key, sortObject(item)]),
+    );
+  return value;
+}