@hyperscale0/udl 2.0.2 → 2.0.3

package/docs/guide/04-fees-and-remainder.md

@@ -13,3 +13,24 @@ Fee rules derive named amounts from a stored base amount. Partitions state how c
 ```
 
 Computed money has one author. A remainder, signed sum, distribution, quote, or derived amount must not compete with another clause for the same field or ref. A money move consumes the computed value once. The validator rejects missing sources, duplicate outputs, and terminal paths that strand funded value.
+
+## Retained charges
+
+A quote may declare `chargeRetainedBy` with a role (`payer`, `beneficiary`, or `subjectHolder`). The named role keeps the quoted charge instead of moving it through an escrow payout action. The role must be declared under `parties`, its account field must be required and frozen by `fixes`, and the committing refund transfer must source funds directly from that account.
+
+```jsonc
+{
+  "quote": {
+    "baseField": "premiumAmount",
+    "chargeRef": "unwindPenalty",
+    "chargeRetainedBy": "beneficiary",
+    "charges": [{ "bps": 1000 }],
+    "expires": { "offset": "PT15M" },
+    "fixes": ["insurerAccountId", "policyholderAccountId", "premiumAmount"],
+    "netDestinationField": "policyholderAccountId",
+    "netRef": "policyRefund",
+  },
+}
+```
+
+The retained remainder stays in the source account and cannot be spent by subsequent instrument actions. Actions cannot consume the charge reference, and no self-transfer is permitted.

package/docs/llms-full.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.2. Edit the source, not llms-full.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.3. Edit the source, not llms-full.txt. -->
 
 # UDL complete reference
 
@@ -124,6 +124,27 @@ Fee rules derive named amounts from a stored base amount. Partitions state how c
 
 Computed money has one author. A remainder, signed sum, distribution, quote, or derived amount must not compete with another clause for the same field or ref. A money move consumes the computed value once. The validator rejects missing sources, duplicate outputs, and terminal paths that strand funded value.
 
+## Retained charges
+
+A quote may declare `chargeRetainedBy` with a role (`payer`, `beneficiary`, or `subjectHolder`). The named role keeps the quoted charge instead of moving it through an escrow payout action. The role must be declared under `parties`, its account field must be required and frozen by `fixes`, and the committing refund transfer must source funds directly from that account.
+
+```jsonc
+{
+  "quote": {
+    "baseField": "premiumAmount",
+    "chargeRef": "unwindPenalty",
+    "chargeRetainedBy": "beneficiary",
+    "charges": [{ "bps": 1000 }],
+    "expires": { "offset": "PT15M" },
+    "fixes": ["insurerAccountId", "policyholderAccountId", "premiumAmount"],
+    "netDestinationField": "policyholderAccountId",
+    "netRef": "policyRefund",
+  },
+}
+```
+
+The retained remainder stays in the source account and cannot be spent by subsequent instrument actions. Actions cannot consume the charge reference, and no self-transfer is permitted.
+
 <!-- source: guide/05-checks-updates-dials.md -->
 
 # Checks, updates, and dials

package/docs/llms.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.2. Edit the source, not llms.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.3. Edit the source, not llms.txt. -->
 
 # UDL documentation
 

package/docs/reference/clauses.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.2. Edit the source, not clauses.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.3. Edit the source, not clauses.md. -->
 
 # Clause reference
 

package/docs/reference/cli.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.2. Edit the source, not cli.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.3. Edit the source, not cli.md. -->
 
 # Command reference
 

package/docs/reference/diagnostics.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.2. Edit the source, not diagnostics.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.0.3. Edit the source, not diagnostics.md. -->
 
 # Diagnostic reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
   "keywords": [
     "udl",
@@ -84,5 +84,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "70ddac0ae5599ca61c7951b027befbeb6eea9f96"
+  "gitHead": "d9200bc6856f30811e8aa2888c44fdd045424120"
 }

package/spec/udl.schema.json

@@ -1302,6 +1302,10 @@
                       "type": "string",
                       "pattern": "^[a-z][A-Za-z0-9]*$"
                     },
+                    "chargeRetainedBy": {
+                      "type": "string",
+                      "enum": ["payer", "beneficiary", "subjectHolder"]
+                    },
                     "charges": {
                       "minItems": 1,
                       "type": "array",

package/src/finance.ts

@@ -47,6 +47,11 @@ interface FinancialInstrument {
           | {
               readonly baseField: string;
               readonly chargeRef: string;
+              readonly chargeRetainedBy?:
+                | "payer"
+                | "beneficiary"
+                | "subjectHolder"
+                | undefined;
               readonly charges: readonly { readonly bps: number }[];
               readonly netRef: string;
             }
@@ -65,6 +70,11 @@ interface FinancialInstrument {
 interface QuoteFacts {
   readonly baseField: string;
   readonly chargeRef: string;
+  readonly chargeRetainedBy?:
+    | "payer"
+    | "beneficiary"
+    | "subjectHolder"
+    | undefined;
   readonly chargeCanBeNonzero: boolean;
   readonly commit: string;
   readonly netRef: string;
@@ -172,7 +182,15 @@ export function analyzeInstrumentFinance(
     trackedAccounts.add(source);
   }
   const refundSourceAccounts = new Set(refundSources.values());
-  if (trackedAccounts.size === 0) return [];
+  for (const quote of quotes) {
+    validateChargePayout(
+      instrument,
+      quote,
+      refundSources.get(quote.commit),
+      add,
+    );
+  }
+  if (trackedAccounts.size === 0) return issues;
   if (trackedAccounts.size > UDL_LIMITS.financeAccounts) {
     add(
       ["actions"],
@@ -183,14 +201,6 @@ export function analyzeInstrumentFinance(
   }
 
   const reservations = reservationsByKey(instrument);
-  for (const quote of quotes) {
-    validateChargePayout(
-      instrument,
-      quote,
-      refundSources.get(quote.commit),
-      add,
-    );
-  }
 
   let pathVariants = 0;
   let work = 0;
@@ -720,6 +730,7 @@ function quoteFacts(
         declaresChargePayout ||
         quote.charges.some((tier) => tier.bps > 0),
       chargeRef: quote.chargeRef,
+      chargeRetainedBy: quote.chargeRetainedBy,
       commit,
       netRef: quote.netRef,
       quoting,
@@ -750,6 +761,62 @@ function validateChargePayout(
         ),
       ),
   );
+
+  if (quote.chargeRetainedBy !== undefined) {
+    const role = quote.chargeRetainedBy;
+    const partyField = Object.hasOwn(instrument.parties ?? {}, role)
+      ? instrument.parties?.[
+          role as keyof NonNullable<FinancialInstrument["parties"]>
+        ]
+      : undefined;
+    if (!partyField) {
+      add(
+        ["actions", quote.quoting, "quote", "chargeRetainedBy"],
+        `quoting action ${quote.quoting} retains charge by undeclared party role ${role}`,
+      );
+    } else {
+      const expectedSource = `field:${partyField}`;
+      if (refundSource === undefined) {
+        add(
+          ["actions", quote.commit, "moves"],
+          `commit action ${quote.commit} refund source cannot be resolved to charge-retaining party field ${partyField}`,
+        );
+      } else if (refundSource !== expectedSource) {
+        if (refundSource.startsWith("ref:")) {
+          add(
+            ["actions", quote.commit, "moves"],
+            `commit action ${quote.commit} refund source cannot be a product escrow ref for a retained quote`,
+          );
+        } else {
+          add(
+            ["actions", quote.commit, "moves"],
+            `commit action ${quote.commit} refund source ${refundSource} does not match charge-retaining party field ${partyField}`,
+          );
+        }
+      }
+    }
+    if (uses.length > 0) {
+      add(
+        ["actions"],
+        `${chargePath} is retained by ${role} and cannot be consumed by an action`,
+      );
+      for (const use of uses) {
+        add(
+          [
+            "actions",
+            use.actionName,
+            "moves",
+            use.stepIndex,
+            "bind",
+            use.target,
+          ],
+          `${chargePath} is retained by ${role} and cannot be consumed by an action`,
+        );
+      }
+    }
+    return;
+  }
+
   if (quote.chargeCanBeNonzero && uses.length !== 1) {
     add(
       ["actions"],

package/src/schema.ts

@@ -237,6 +237,13 @@ const udlQuoteChargeSchema = z.strictObject({
   withinOffset: nonEmptyTextSchema.optional(),
 });
 
+export const udlQuoteRetainedRoleSchema = z.enum([
+  "payer",
+  "beneficiary",
+  "subjectHolder",
+]);
+export type UdlQuoteRetainedRole = z.infer<typeof udlQuoteRetainedRoleSchema>;
+
 // A priced, expiring offer. The quoting action splits `baseField` into a charge
 // and a net at its own clock, freezes the fields the price was read from, and
 // stamps an expiry. Only the paired `commit` action may spend the offer, and
@@ -246,6 +253,8 @@ const udlQuoteShape = {
   anchorField: udlFieldNameSchema.optional(),
   baseField: udlFieldNameSchema,
   chargeRef: udlFieldNameSchema,
+  /** Party role that keeps the quoted charge instead of moving it through an escrow payout action. */
+  chargeRetainedBy: udlQuoteRetainedRoleSchema.optional(),
   charges: z.array(udlQuoteChargeSchema).min(1),
   /** Fixed ISO-8601 duration from the quoting action, or a stored deadline. */
   expires: z.union([

package/src/validation.ts

@@ -4262,6 +4262,69 @@ function validateQuoteCommit(
         "UDL5006",
       );
     }
+    if (quote.chargeRetainedBy !== undefined) {
+      const retainedRole = quote.chargeRetainedBy;
+      // Own keys only: a role named after a prototype member is undeclared.
+      const partyField = Object.hasOwn(instrument.parties ?? {}, retainedRole)
+        ? instrument.parties?.[retainedRole]
+        : undefined;
+      if (!partyField) {
+        add(
+          [...quoteBase, "chargeRetainedBy"],
+          `quoting action ${actionName} retains charge by undeclared party role ${retainedRole}`,
+          "UDL5006",
+        );
+      } else {
+        const partySchema = instrument.fields[partyField];
+        if (!partySchema || !references.accepts(partySchema, "acct")) {
+          add(
+            [...quoteBase, "chargeRetainedBy"],
+            `charge-retaining party field ${partyField} must be an account field`,
+            "UDL5006",
+          );
+        }
+        if (!instrument.required.includes(partyField)) {
+          add(
+            [...quoteBase, "chargeRetainedBy"],
+            `charge-retaining party field ${partyField} must be required`,
+            "UDL5006",
+          );
+        }
+        if (!quote.fixes.includes(partyField)) {
+          add(
+            [...quoteBase, "chargeRetainedBy"],
+            `quoting action ${actionName} must freeze its charge-retaining party field ${partyField}`,
+            "UDL5006",
+          );
+        }
+      }
+      const chargePath = `refs.${quote.chargeRef}`;
+      for (const [consumerName, candidateAction] of Object.entries(
+        instrument.actions,
+      )) {
+        for (const [moveIndex, move] of (
+          candidateAction.moves ?? []
+        ).entries()) {
+          for (const [target, binding] of Object.entries(move.bind)) {
+            if (binding.from === "instance" && binding.path === chargePath) {
+              add(
+                [
+                  ...base,
+                  "actions",
+                  consumerName,
+                  "moves",
+                  moveIndex,
+                  "bind",
+                  target,
+                ],
+                `charge ${chargePath} is retained by ${retainedRole} and cannot be consumed by an action`,
+                "UDL5006",
+              );
+            }
+          }
+        }
+      }
+    }
   }
 
   const seededBy = new Map<string, string>();
@@ -4342,6 +4405,37 @@ function validateQuoteCommit(
         "UDL5006",
       );
     }
+    if (quote.chargeRetainedBy !== undefined) {
+      const partyField = instrument.parties?.[quote.chargeRetainedBy];
+      let sourceField: string | undefined;
+      if (sourceBinding?.from === "instance") {
+        if (sourceBinding.path.startsWith("fields.")) {
+          sourceField = sourceBinding.path.slice("fields.".length);
+        } else if (sourceBinding.path.startsWith("party.")) {
+          const role = sourceBinding.path.slice("party.".length);
+          sourceField = instrument.parties?.[role];
+        }
+      }
+      if (
+        sourceBinding?.from !== "instance" ||
+        !sourceField ||
+        sourceField !== partyField
+      ) {
+        add(
+          [
+            ...base,
+            "actions",
+            actionName,
+            "moves",
+            0,
+            "bind",
+            "sourceAccountId",
+          ],
+          `commit action ${actionName} refund source must come from charge-retaining party field ${partyField ?? quote.chargeRetainedBy}`,
+          "UDL5006",
+        );
+      }
+    }
   }
 }