@hyperscale0/udl 1.0.0 → 2.0.0

package/src/evolution.ts

@@ -157,7 +157,7 @@ export function snapshotUdlInstrument(
     fields: Object.fromEntries(
       Object.entries(instrument.fields).map(([field, schema]) => [
         field,
-        { required: required.has(field), schema },
+        { required: required.has(field), schema: withoutProse(schema) },
       ]),
     ),
     id: instrument.id,
@@ -575,11 +575,34 @@ function snapshotJsonSchemaFields(
   return Object.fromEntries(
     Object.entries(properties).map(([field, fieldSchema]) => [
       field,
-      { required: required.has(field), schema: fieldSchema },
+      { required: required.has(field), schema: withoutProse(fieldSchema) },
     ]),
   );
 }
 
+/**
+ * Descriptions are prose for readers, not shape: a wording fix in a std
+ * template must land on a live flow as an extension, never as a refusal.
+ */
+function withoutProse(value: unknown, depth = 1): unknown {
+  if (depth > UDL_LIMITS.maxDepth) throw nestingExceeded();
+  if (Array.isArray(value)) {
+    return value.map((item) => withoutProse(item, depth + 1));
+  }
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => key !== "description")
+      .map(([key, entry]) => [key, withoutProse(entry, depth + 1)]),
+  );
+}
+
+function nestingExceeded(): UdlError {
+  return new UdlError([
+    issue("UDL1004", "$", `UDL nesting exceeds ${UDL_LIMITS.maxDepth} levels`),
+  ]);
+}
+
 function snapshotJsonSchemaConstraints(
   schema: Readonly<Record<string, unknown>>,
 ): Readonly<Record<string, unknown>> {
@@ -753,9 +776,12 @@ function diffActions(
     ) {
       violations.push(`action ${action} changed its check prerequisites`);
     }
+    // A failure point only adds a sandbox refusal for one documented amount, so
+    // declaring one on an action that had none is additive; changing or
+    // removing a declared one rewrites what a sandbox integration relies on.
     if (
-      (descriptor.sandboxFailurePoint ?? null) !==
-      (current.sandboxFailurePoint ?? null)
+      descriptor.sandboxFailurePoint &&
+      descriptor.sandboxFailurePoint !== (current.sandboxFailurePoint ?? null)
     ) {
       violations.push(`action ${action} changed its sandbox failure point`);
     }
@@ -937,15 +963,7 @@ function recordValue(value: unknown): Readonly<Record<string, unknown>> {
  * and lands here rather than exhausting the call stack.
  */
 function stableStringify(value: unknown, depth = 1): string {
-  if (depth > UDL_LIMITS.maxDepth) {
-    throw new UdlError([
-      issue(
-        "UDL1004",
-        "$",
-        `UDL nesting exceeds ${UDL_LIMITS.maxDepth} levels`,
-      ),
-    ]);
-  }
+  if (depth > UDL_LIMITS.maxDepth) throw nestingExceeded();
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value) ?? "null";
   }

package/src/finance.ts

@@ -207,6 +207,7 @@ export function analyzeInstrumentFinance(
       return issues;
     }
     const initial = applyEffects(
+      instrument,
       account,
       "create",
       { balance: EMPTY, holds: {} },
@@ -243,6 +244,7 @@ export function analyzeInstrumentFinance(
             return issues;
           }
           const targetState = applyEffects(
+            instrument,
             account,
             action,
             sourceState,
@@ -274,19 +276,21 @@ export function analyzeInstrumentFinance(
         (transition) => transition.from,
       ),
     );
-    for (const [state, variants] of states) {
-      if (nonterminalStates.has(state)) continue;
-      for (const variant of variants.values()) {
-        if (
-          variant.balance.kind === "empty" &&
-          Object.keys(variant.holds).length === 0
-        ) {
-          continue;
+    if (account.startsWith("ref:")) {
+      for (const [state, variants] of states) {
+        if (nonterminalStates.has(state)) continue;
+        for (const variant of variants.values()) {
+          if (
+            variant.balance.kind === "empty" &&
+            Object.keys(variant.holds).length === 0
+          ) {
+            continue;
+          }
+          add(
+            ["lifecycle", "states", instrument.lifecycle.states.indexOf(state)],
+            `terminal state ${state} can strand value in ${formatAccount(account)}`,
+          );
         }
-        add(
-          ["lifecycle", "states", instrument.lifecycle.states.indexOf(state)],
-          `terminal state ${state} can strand value in ${formatAccount(account)}`,
-        );
       }
     }
   }
@@ -434,7 +438,7 @@ function effectsByAction(
             instrument,
             step.bind.sourceAccountId,
           );
-          if (source && accountsMayAlias(source, account)) {
+          if (source && accountsMayAlias(instrument, source, account)) {
             const committed = quoteByCommit.get(actionName);
             const amountPath =
               step.bind.amount?.from === "instance"
@@ -474,7 +478,7 @@ function effectsByAction(
             instrument,
             step.bind.sourceAccountId,
           );
-          if (source && accountsMayAlias(source, account)) {
+          if (source && accountsMayAlias(instrument, source, account)) {
             effects.push({
               amount: amountIdentity(step.bind.amount),
               kind: "outgoing_reserve",
@@ -504,7 +508,10 @@ function effectsByAction(
           const reserved = reservations.get(reservation);
           if (
             !reserved ||
-            (!(reserved.source && accountsMayAlias(reserved.source, account)) &&
+            (!(
+              reserved.source &&
+              accountsMayAlias(instrument, reserved.source, account)
+            ) &&
               reserved.destination !== account)
           ) {
             return [];
@@ -526,6 +533,7 @@ function effectsByAction(
 }
 
 function applyEffects(
+  instrument: FinancialInstrument,
   account: string,
   action: string,
   input: AccountState,
@@ -582,7 +590,7 @@ function applyEffects(
       const reservation = reservations.get(key);
       if (
         reservation?.source &&
-        accountsMayAlias(reservation.source, account)
+        accountsMayAlias(instrument, reservation.source, account)
       ) {
         const held = holds[key];
         delete holds[key];
@@ -784,7 +792,7 @@ function validateChargePayout(
     source !== undefined &&
     source === refundSource &&
     destination !== undefined &&
-    !accountsMayAlias(source, destination);
+    !accountsMayAlias(instrument, source, destination);
   if (!valid) {
     add(
       ["actions", use.actionName, "moves", use.stepIndex, "bind", use.target],
@@ -812,9 +820,34 @@ function canonicalAccount(
   return undefined;
 }
 
-function accountsMayAlias(left: string, right: string): boolean {
-  if (left.startsWith("field:") && right.startsWith("field:")) return true;
-  return left === right;
+function accountsMayAlias(
+  instrument: FinancialInstrument,
+  left: string,
+  right: string,
+): boolean {
+  if (left === right) return true;
+  if (left.startsWith("field:") && right.startsWith("field:")) {
+    const leftField = left.slice("field:".length);
+    const rightField = right.slice("field:".length);
+    if (leftField === rightField) return true;
+    if (instrument.parties) {
+      const leftParty = Object.entries(instrument.parties).find(
+        ([, field]) => field === leftField,
+      )?.[0];
+      const rightParty = Object.entries(instrument.parties).find(
+        ([, field]) => field === rightField,
+      )?.[0];
+      if (
+        leftParty !== undefined &&
+        rightParty !== undefined &&
+        leftParty !== rightParty
+      ) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
 }
 
 function amountIdentity(binding: UdlBinding | undefined): string {

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   udlClauseVocabulary,
   udlDocumentSchema,
   udlInstrumentActionIdSchema,
+  udlJourneySchema,
   udlKernelOperationSchema,
   udlProviderFamilyIdSchema,
   udlPublicActionSchema,
@@ -64,12 +65,16 @@ export type {
   UdlDue,
   UdlEffects,
   UdlExample,
+  UdlDateComparison,
+  UdlDateComparisonOperator,
   UdlGate,
   UdlKernelOperation,
   UdlLifecycle,
   UdlLifecycleTransition,
   UdlInstrument,
   UdlInstrumentSubject,
+  UdlJourney,
+  UdlJourneyStep,
   UdlPayout,
   UdlQuote,
   UdlProviderFamilyId,
@@ -95,5 +100,6 @@ export {
 } from "./validation.js";
 export type {
   ReferenceShapeBudget,
+  UdlValidationOptions,
   UdlValidationResult,
 } from "./validation.js";

package/src/limits.ts

@@ -9,7 +9,8 @@ export const UDL_LIMITS = Object.freeze({
   financeWork: 4_096,
   maxDepth: 24,
   maxKeyLength: 128,
-  maxNodes: 10_000,
+  // The 33-instrument catalog includes its executable authored journeys.
+  maxNodes: 20_000,
   maxPatternLength: 320,
   /**
    * Upper bound on the match attempts a document-authored `pattern` can force
@@ -26,8 +27,10 @@ export const UDL_LIMITS = Object.freeze({
    * of the instruments x gate-fields product that asks for them.
    */
   maxSchemaProbes: 2_048,
-  // The complete 2026-09-01 platform catalog serializes to 402,126 bytes.
-  maxSourceBytes: 512 * 1_024,
+  // The complete catalog now carries executable authored journeys beside the
+  // instrument mechanics, so its bounded source and string budgets include
+  // that contract-owned corpus.
+  maxSourceBytes: 1_024 * 1_024,
   maxStringLength: 2_048,
-  maxTotalStringLength: 256 * 1_024,
+  maxTotalStringLength: 512 * 1_024,
 });

package/src/schema.ts

@@ -33,6 +33,14 @@ export const udlInstrumentActionIdSchema = z
     "must name an instrument action as instrument_id.action_key",
   );
 
+const udlJourneyOperationNameSchema = z
+  .string()
+  .max(160)
+  .regex(
+    /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/,
+    "must name a dotted operation",
+  );
+
 const nonEmptyTextSchema = z
   .string()
   .refine((value) => value.trim().length > 0, "must not be blank");
@@ -93,6 +101,20 @@ const udlExampleSchema = z.strictObject({
   output: z.json().optional(),
 });
 
+const udlJourneyStepSchema = z.strictObject({
+  bind: z.record(fieldPathSchema, udlSnakeCaseSchema),
+  example: udlSnakeCaseSchema,
+  id: udlSnakeCaseSchema.optional(),
+  operation: udlJourneyOperationNameSchema,
+});
+
+export const udlJourneySchema = z.strictObject({
+  id: udlSnakeCaseSchema,
+  label: nonEmptyTextSchema,
+  steps: z.array(udlJourneyStepSchema).min(1),
+  summary: nonEmptyTextSchema,
+});
+
 const udlLifecycleTransitionSchema = z.strictObject({
   from: z.array(udlSnakeCaseSchema).min(1),
   to: udlSnakeCaseSchema,
@@ -110,9 +132,18 @@ const udlUpdatePolicySchema = z.strictObject({
   states: z.array(udlSnakeCaseSchema).min(1),
 });
 
+const udlDateComparisonOperatorSchema = z.enum([">=", ">", "<=", "<", "=="]);
+
+const udlDateComparisonSchema = z.strictObject({
+  localPath: fieldPathSchema,
+  operator: udlDateComparisonOperatorSchema,
+  referencedPath: fieldPathSchema,
+});
+
 const udlGateSchema = z.strictObject({
   /** Local field key <- referenced instance path; create actions only. */
   bind: z.record(udlFieldNameSchema, fieldPathSchema).optional(),
+  dateComparison: udlDateComparisonSchema.optional(),
   field: udlFieldNameSchema,
   /** Local instance path === referenced instance path at admission. */
   match: z.record(fieldPathSchema, fieldPathSchema).optional(),
@@ -329,10 +360,10 @@ const udlExposureRequirementSchema = z.strictObject({
 // The tenant-backend decision port: the action's caller asserts the acting
 // party, checked at admission against the instrument's party bindings for the
 // allowed roles.
+const udlPartyRoleSchema = z.string().regex(/^[a-z][A-Za-z0-9_]*$/);
+
 const udlPortSchema = z.strictObject({
-  allowedParties: z
-    .array(z.enum(["payer", "beneficiary", "subjectHolder"]))
-    .min(1),
+  allowedParties: z.array(udlPartyRoleSchema).min(1),
 });
 
 const udlPayoutSchema = z.strictObject({
@@ -686,14 +717,9 @@ const udlInstrumentShape = {
     .string()
     .regex(idPrefixPattern, "must contain 2 to 8 lowercase letters"),
   lifecycle: udlLifecycleSchema,
+  journeys: z.array(udlJourneySchema).min(1).optional(),
   nav: z.array(nonEmptyTextSchema).min(1).optional(),
-  parties: z
-    .strictObject({
-      beneficiary: udlFieldNameSchema.optional(),
-      payer: udlFieldNameSchema.optional(),
-      subjectHolder: udlFieldNameSchema.optional(),
-    })
-    .optional(),
+  parties: z.record(udlPartyRoleSchema, udlFieldNameSchema).optional(),
   partitions: z.array(udlPartitionSchema).min(1).optional(),
   required: z.array(udlFieldNameSchema),
   subject: udlInstrumentSubjectSchema.optional(),
@@ -1099,6 +1125,12 @@ export const udlClauseVocabulary = [
     spelling: "id prefix",
     target: "idPrefix",
   },
+  {
+    cardinality: "many",
+    scope: "instrument",
+    spelling: "journeys",
+    target: "journeys",
+  },
   {
     cardinality: "many",
     scope: "instrument",
@@ -1330,6 +1362,10 @@ export type UdlDocument = z.infer<typeof udlDocumentSchema>;
 export type UdlDue = z.infer<typeof udlDueSchema>;
 export type UdlEffects = z.infer<typeof udlEffectsSchema>;
 export type UdlExample = z.infer<typeof udlExampleSchema>;
+export type UdlDateComparison = z.infer<typeof udlDateComparisonSchema>;
+export type UdlDateComparisonOperator = z.infer<
+  typeof udlDateComparisonOperatorSchema
+>;
 export type UdlGate = z.infer<typeof udlGateSchema>;
 export type UdlKernelOperation = z.infer<typeof udlKernelOperationSchema>;
 export type UdlLifecycle = z.infer<typeof udlLifecycleSchema>;
@@ -1338,6 +1374,8 @@ export type UdlLifecycleTransition = z.infer<
 >;
 export type UdlInstrument = z.infer<typeof udlInstrumentSchema>;
 export type UdlInstrumentSubject = z.infer<typeof udlInstrumentSubjectSchema>;
+export type UdlJourney = z.infer<typeof udlJourneySchema>;
+export type UdlJourneyStep = z.infer<typeof udlJourneyStepSchema>;
 export type UdlMove = z.infer<typeof udlMoveSchema>;
 export type UdlPayout = z.infer<typeof udlPayoutSchema>;
 export type UdlQuote = z.infer<typeof udlQuoteSchema>;