@hyperscale0/udl 1.0.0-alpha.3 → 1.0.0-alpha.5

package/spec/udl.schema.json

@@ -109,6 +109,14 @@
               ]
             }
           },
+          "computedMoneyRefs": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z][A-Za-z0-9]*$"
+            }
+          },
           "description": {
             "type": "string"
           },
@@ -116,6 +124,46 @@
             "type": "boolean",
             "const": true
           },
+          "derivedAmounts": {
+            "minItems": 1,
+            "maxItems": 4,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "field": {
+                  "type": "string",
+                  "pattern": "^[a-z][A-Za-z0-9]*$"
+                },
+                "rounding": {
+                  "type": "string",
+                  "const": "floor"
+                },
+                "rule": {
+                  "type": "object",
+                  "properties": {
+                    "bps": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 9999
+                    },
+                    "kind": {
+                      "type": "string",
+                      "const": "percentage_of"
+                    }
+                  },
+                  "required": ["bps", "kind"],
+                  "additionalProperties": false
+                },
+                "sourceField": {
+                  "type": "string",
+                  "pattern": "^[a-z][A-Za-z0-9]*$"
+                }
+              },
+              "required": ["field", "rounding", "rule", "sourceField"],
+              "additionalProperties": false
+            }
+          },
           "fields": {
             "type": "object",
             "propertyNames": {
@@ -338,6 +386,17 @@
             "additionalProperties": {
               "type": "object",
               "properties": {
+                "captureInput": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^[a-z][A-Za-z0-9]*$"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^[a-z][A-Za-z0-9]*$"
+                  }
+                },
                 "deadline": {
                   "type": "object",
                   "properties": {
@@ -372,6 +431,59 @@
                   "required": ["capability", "deadlineMs", "onTimeout"],
                   "additionalProperties": false
                 },
+                "distribute": {
+                  "type": "object",
+                  "properties": {
+                    "amountRef": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "onZero": {
+                      "type": "string",
+                      "enum": ["refuse", "skip_steps"]
+                    },
+                    "pool": {
+                      "type": "object",
+                      "properties": {
+                        "from": {
+                          "type": "string",
+                          "const": "parent"
+                        },
+                        "path": {
+                          "type": "string",
+                          "pattern": "^[a-z][A-Za-z0-9]*(?:\\.[a-z][A-Za-z0-9]*)*$"
+                        }
+                      },
+                      "required": ["from", "path"],
+                      "additionalProperties": false
+                    },
+                    "refField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "statuses": {
+                      "minItems": 1,
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                      }
+                    },
+                    "weightField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    }
+                  },
+                  "required": [
+                    "amountRef",
+                    "onZero",
+                    "pool",
+                    "refField",
+                    "statuses",
+                    "weightField"
+                  ],
+                  "additionalProperties": false
+                },
                 "description": {
                   "type": "string"
                 },
@@ -580,6 +692,49 @@
                     "additionalProperties": false
                   }
                 },
+                "payout": {
+                  "type": "object",
+                  "properties": {
+                    "amount": {
+                      "type": "string",
+                      "pattern": "^(?:fields|refs)\\.[a-z][A-Za-z0-9]*$"
+                    },
+                    "beneficiaryField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "beneficiaryPartyField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "capture": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "currencyField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "sourceAccountField": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "speed": {
+                      "type": "string",
+                      "const": "standard"
+                    }
+                  },
+                  "required": [
+                    "amount",
+                    "beneficiaryField",
+                    "beneficiaryPartyField",
+                    "capture",
+                    "currencyField",
+                    "sourceAccountField",
+                    "speed"
+                  ],
+                  "additionalProperties": false
+                },
                 "port": {
                   "type": "object",
                   "properties": {
@@ -595,6 +750,11 @@
                   "required": ["allowedParties"],
                   "additionalProperties": false
                 },
+                "publicIntent": {
+                  "description": "Author-approved public intent name; the containing verb key remains the lifecycle and execution identity",
+                  "type": "string",
+                  "pattern": "^[a-z][A-Za-z0-9]*$"
+                },
                 "requiresAggregate": {
                   "minItems": 1,
                   "type": "array",
@@ -758,6 +918,51 @@
                   "required": ["path"],
                   "additionalProperties": false
                 },
+                "requiresExposure": {
+                  "minItems": 1,
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "amountField": {
+                        "type": "string",
+                        "pattern": "^[a-z][A-Za-z0-9]*$"
+                      },
+                      "anchorField": {
+                        "type": "string",
+                        "pattern": "^[a-z][A-Za-z0-9]*$"
+                      },
+                      "capField": {
+                        "type": "string",
+                        "pattern": "^[a-z][A-Za-z0-9]*$"
+                      },
+                      "capOnAnchor": {
+                        "type": "boolean",
+                        "const": true
+                      },
+                      "childNounId": {
+                        "type": "string",
+                        "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                      },
+                      "statuses": {
+                        "minItems": 1,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                        }
+                      }
+                    },
+                    "required": [
+                      "amountField",
+                      "anchorField",
+                      "capField",
+                      "childNounId",
+                      "statuses"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
                 "requiresRefs": {
                   "minItems": 1,
                   "type": "array",
@@ -811,6 +1016,21 @@
                     "additionalProperties": false
                   }
                 },
+                "requiresSettlement": {
+                  "type": "object",
+                  "properties": {
+                    "capture": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "payoutRef": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    }
+                  },
+                  "required": ["capture", "payoutRef"],
+                  "additionalProperties": false
+                },
                 "setsAt": {
                   "type": "object",
                   "properties": {
@@ -818,6 +1038,10 @@
                       "type": "string",
                       "pattern": "^[a-z][A-Za-z0-9]*$"
                     },
+                    "marker": {
+                      "type": "boolean",
+                      "const": true
+                    },
                     "offset": {
                       "type": "string"
                     }
@@ -825,6 +1049,71 @@
                   "required": ["field", "offset"],
                   "additionalProperties": false
                 },
+                "signedSum": {
+                  "type": "object",
+                  "properties": {
+                    "amountRef": {
+                      "type": "string",
+                      "pattern": "^[a-z][A-Za-z0-9]*$"
+                    },
+                    "onNegative": {
+                      "type": "string",
+                      "const": "refuse"
+                    },
+                    "onZero": {
+                      "type": "string",
+                      "enum": ["refuse", "skip_steps"]
+                    },
+                    "sources": {
+                      "minItems": 1,
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "amountField": {
+                            "type": "string",
+                            "pattern": "^[a-z][A-Za-z0-9]*$"
+                          },
+                          "nounId": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                          },
+                          "refField": {
+                            "type": "string",
+                            "pattern": "^[a-z][A-Za-z0-9]*$"
+                          },
+                          "sign": {
+                            "type": "string",
+                            "enum": ["add", "subtract"]
+                          },
+                          "statuses": {
+                            "minItems": 1,
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                            }
+                          },
+                          "subtotalRef": {
+                            "type": "string",
+                            "pattern": "^[a-z][A-Za-z0-9]*$"
+                          }
+                        },
+                        "required": [
+                          "amountField",
+                          "nounId",
+                          "refField",
+                          "sign",
+                          "statuses",
+                          "subtotalRef"
+                        ],
+                        "additionalProperties": false
+                      }
+                    }
+                  },
+                  "required": ["amountRef", "onNegative", "onZero", "sources"],
+                  "additionalProperties": false
+                },
                 "steps": {
                   "type": "array",
                   "items": {

package/src/evolution.ts

@@ -1,6 +1,6 @@
 import { UDL_LIMITS } from "./limits.js";
 import type { UdlAggregate, UdlDocument, UdlNoun, UdlVerb } from "./schema.js";
-import { assertValidUdl, UdlError } from "./validation.js";
+import { UdlError } from "./validation.js";
 
 export interface EvolutionFieldSnapshot {
   readonly required: boolean;
@@ -18,8 +18,12 @@ export interface EvolutionMoveSnapshot extends EvolutionStepSnapshot {
 }
 
 export interface EvolutionVerbSnapshot {
+  /** Missing on snapshots written before receipt-input capture existed. */
+  readonly captureInput?: unknown;
   readonly deadline: unknown;
   readonly decision: unknown;
+  /** Missing on snapshots written before weighted distribution existed. */
+  readonly distribute?: unknown;
   readonly due: unknown;
   readonly earnable: boolean;
   readonly eventName: string | null;
@@ -30,11 +34,21 @@ export interface EvolutionVerbSnapshot {
    * friends change what callers may send, so they are frozen once live.
    */
   readonly inputConstraints: unknown;
+  /** Missing on snapshots written before payout intents existed. */
+  readonly payout?: unknown;
   readonly port: unknown;
+  /** Missing on snapshots written before public intent metadata existed. */
+  readonly publicIntent?: string | null;
   readonly requiresAggregate: unknown;
   readonly requiresDrainedAccount: unknown;
+  /** Missing on snapshots written before exposure gates entered open UDL. */
+  readonly requiresExposure?: unknown;
   readonly requiresRefs: unknown;
+  /** Missing on snapshots written before settlement evidence gates existed. */
+  readonly requiresSettlement?: unknown;
   readonly setsAt: unknown;
+  /** Missing on snapshots written before signed child sums existed. */
+  readonly signedSum?: unknown;
   readonly moves: readonly EvolutionMoveSnapshot[];
   readonly steps: readonly EvolutionStepSnapshot[];
 }
@@ -47,6 +61,9 @@ export interface EvolutionTransitionSnapshot {
 /** The complete serializable algebra protected by append-only evolution. */
 export interface NounEvolutionSnapshot {
   readonly aggregateInvariants: readonly string[];
+  /** Missing on snapshots written before typed computed refs entered UDL. */
+  readonly computedMoneyRefs?: readonly string[];
+  readonly derivedAmounts: readonly string[];
   readonly distinctParties?: true;
   readonly fields: Readonly<Record<string, EvolutionFieldSnapshot>>;
   readonly id: string;
@@ -70,6 +87,11 @@ export function snapshotUdlNoun(noun: UdlNoun): NounEvolutionSnapshot {
     aggregateInvariants: (noun.aggregateInvariants ?? []).map(
       aggregateInvariantKey,
     ),
+    computedMoneyRefs: [...(noun.computedMoneyRefs ?? [])].sort(),
+    derivedAmounts: (noun.derivedAmounts ?? []).map(
+      (amount) =>
+        `${amount.field}=floor(${amount.sourceField}*${amount.rule.bps}/10000)`,
+    ),
     ...(noun.distinctParties ? { distinctParties: true as const } : {}),
     fields: Object.fromEntries(
       Object.entries(noun.fields).map(([field, schema]) => [
@@ -108,27 +130,10 @@ export function snapshotUdlNoun(noun: UdlNoun): NounEvolutionSnapshot {
 /**
  * Compare two product definitions under the append-only evolution law.
  *
- * Both arguments are validated first. The typed signature this used to carry
- * invited a caller to hand over an object it had never parsed, and the diff
- * walks straight into `stableStringify`: a document with a cycle in it threw
- * a RangeError out of here while `validateUdl` returned a clean
- * `resource_limit` issue for the same object.
- */
-export function diffUdlEvolution(
-  previous: unknown,
-  next: unknown,
-): readonly string[] {
-  return diffValidatedUdlEvolution(
-    assertValidUdl(previous),
-    assertValidUdl(next),
-  );
-}
-
-/**
- * The same comparison for a caller holding two documents `validateUdl` has
- * already admitted. Validation costs roughly twice what the diff costs, so a
- * caller that has paid once should not pay again: `udl diff` parses both
- * files and then takes this door.
+ * Both documents must already have passed `validateUdl`. The diff walks
+ * straight into `stableStringify`, so an unvalidated document with a cycle in
+ * it throws a RangeError out of here where the validator would have returned a
+ * clean `resource_limit` issue: parse first, then diff.
  */
 export function diffValidatedUdlEvolution(
   previous: UdlDocument,
@@ -252,6 +257,22 @@ export function diffNounEvolution(
   violations.push(...diffVerbs(previous.verbs, next.verbs));
   violations.push(...diffParties(previous.parties, next.parties));
   violations.push(...diffAggregates(previous, next));
+  if (
+    stableStringify(previous.computedMoneyRefs ?? []) !==
+    stableStringify(next.computedMoneyRefs ?? [])
+  ) {
+    violations.push(
+      "computed money refs changed; runtime-derived money surfaces are frozen once live",
+    );
+  }
+  if (
+    stableStringify(previous.derivedAmounts ?? []) !==
+    stableStringify(next.derivedAmounts ?? [])
+  ) {
+    violations.push(
+      "derived amount rules changed; derived money arithmetic is frozen once live",
+    );
+  }
   violations.push(
     ...removedSetEntries(
       previous.partitions,
@@ -288,8 +309,10 @@ export function diffNounEvolution(
 
 function snapshotUdlVerb(definition: UdlVerb): EvolutionVerbSnapshot {
   return {
+    captureInput: definition.captureInput ?? null,
     deadline: definition.deadline ?? null,
     decision: definition.decision ?? null,
+    distribute: definition.distribute ?? null,
     due: definition.due ?? null,
     earnable: definition.earnable ?? false,
     eventName: definition.eventName ?? null,
@@ -297,8 +320,11 @@ function snapshotUdlVerb(definition: UdlVerb): EvolutionVerbSnapshot {
     inputConstraints: definition.input
       ? snapshotJsonSchemaConstraints(definition.input)
       : null,
+    payout: definition.payout ?? null,
     port: definition.port ?? null,
+    publicIntent: definition.publicIntent ?? null,
     setsAt: definition.setsAt ?? null,
+    signedSum: definition.signedSum ?? null,
     moves: definition.moves.map((move) => ({
       bind: move.bind,
       capture: move.capture ?? {},
@@ -307,7 +333,9 @@ function snapshotUdlVerb(definition: UdlVerb): EvolutionVerbSnapshot {
     })),
     requiresAggregate: definition.requiresAggregate ?? [],
     requiresDrainedAccount: definition.requiresDrainedAccount ?? null,
+    requiresExposure: definition.requiresExposure ?? [],
     requiresRefs: definition.requiresRefs ?? [],
+    requiresSettlement: definition.requiresSettlement ?? null,
     steps: definition.steps.map((step) => ({
       bind: step.bind,
       capture: step.capture ?? {},
@@ -448,6 +476,26 @@ function diffVerbs(
     ) {
       violations.push(`verb ${verb} changed its drained-account gate`);
     }
+    if (
+      descriptor.requiresExposure !== undefined &&
+      stableStringify(descriptor.requiresExposure) !==
+        stableStringify(current.requiresExposure)
+    ) {
+      violations.push(`verb ${verb} changed its exposure admission gates`);
+    }
+    if (
+      descriptor.requiresSettlement !== undefined &&
+      stableStringify(descriptor.requiresSettlement) !==
+        stableStringify(current.requiresSettlement)
+    ) {
+      violations.push(`verb ${verb} changed its settlement evidence gate`);
+    }
+    if (
+      stableStringify(descriptor.payout ?? null) !==
+      stableStringify(current.payout ?? null)
+    ) {
+      violations.push(`verb ${verb} changed its payout intent`);
+    }
     if (descriptor.earnable !== current.earnable) {
       violations.push(`verb ${verb} changed its earnable flag`);
     }
@@ -467,14 +515,48 @@ function diffVerbs(
     ) {
       violations.push(`verb ${verb} changed its provider decision`);
     }
+    if (
+      stableStringify(descriptor.distribute) !==
+      stableStringify(current.distribute)
+    ) {
+      violations.push(
+        `verb ${verb} changed its distribution rule; money distribution is frozen once live`,
+      );
+    }
+    if (
+      descriptor.captureInput !== undefined &&
+      stableStringify(descriptor.captureInput) !==
+        stableStringify(current.captureInput)
+    ) {
+      violations.push(`verb ${verb} changed its captured receipt input`);
+    }
     if (stableStringify(descriptor.port) !== stableStringify(current.port)) {
       violations.push(`verb ${verb} changed its decision port`);
     }
+    if (
+      descriptor.publicIntent != null &&
+      descriptor.publicIntent !== current.publicIntent
+    ) {
+      violations.push(`verb ${verb} changed its public intent`);
+    }
     if (
       stableStringify(descriptor.setsAt) !== stableStringify(current.setsAt)
     ) {
       violations.push(`verb ${verb} changed its computed timestamp`);
     }
+    if (
+      descriptor.signedSum !== undefined &&
+      stableStringify(descriptor.signedSum) !==
+        stableStringify(current.signedSum)
+    ) {
+      violations.push(`verb ${verb} changed its signed child sum`);
+    }
+  }
+  for (const [verb, descriptor] of Object.entries(next)) {
+    if (previous[verb] || descriptor.payout == null) continue;
+    violations.push(
+      `verb ${verb} added a payout intent; external money movement is frozen once live`,
+    );
   }
   return violations;
 }

package/src/index.ts

@@ -8,7 +8,6 @@ export {
 } from "./finance.js";
 export {
   diffNounEvolution,
-  diffUdlEvolution,
   diffValidatedUdlEvolution,
   snapshotUdlNoun,
 } from "./evolution.js";
@@ -24,6 +23,7 @@ export {
   UDL_FORMAT_VERSION,
   udlDocumentSchema,
   udlKernelOperationSchema,
+  udlPublicIntentSchema,
 } from "./schema.js";
 export type {
   UdlAggregate,
@@ -40,6 +40,8 @@ export type {
   UdlLifecycleTransition,
   UdlNoun,
   UdlNounSubject,
+  UdlPayout,
+  UdlRequiresSettlement,
   UdlStep,
   UdlSubject,
   UdlUnwind,
@@ -50,6 +52,7 @@ export {
   openReferenceShapeBudget,
   UdlError,
   validateUdl,
+  validateUdlJsonSchema,
   validateUdlSchemaValue,
 } from "./validation.js";
 export type {