@hyperscale0/udl 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -8,6 +8,44 @@ Format version and package version are different numbers.
 
 ## [Unreleased]
 
+- `attests.forAction` lets a declined decision close the same assessed request through its declared refusal action.
+
+- Add reference age gates with fixed durations and allocation gates over a named slice.
+- Refuse fee plus VAT ratios above distributable profit and impossible constant partitions.
+- Derive published instrument dependencies and tenant scoping from the same schema annotations.
+
+### Added
+
+- Request authority binds a server-computed decision digest to a frozen target action and its material input.
+- Instrument reference annotations drive tenant scoping through the document schema, including allocation and funding references.
+
+## [2.4.0] - 2026-09-15
+
+### Added
+
+- Allocation vocabulary: `allocation`, `requiresAllocation`, self allocation, shared consumption and children buckets; `templateBinding` preserves template identity. Unique constraints accept account fields, and exposure can measure allocation-backed remaining balances.
+- Signed schedules, stored rates, equal partitions, contributions, referenced transitions and attested decisions with subject and party binding.
+- Custody clauses: `shift_date`, `requiresExposure.groupField` and `minimumField`, `funding` snapshots and `receiptDistribution` for repeated receipt-backed cash and noncash loss allocation.
+- Assessment refunds across receipts and collection against remaining balances.
+
+### Changed
+
+- Regenerate the schema specification and public clause reference for this vocabulary. Document checkout validation and the matching HSX 2.2.0 release.
+- Remove the retired journeys clause and Blueprint cost dimension.
+- Clarify that catalogue slices must include clause-referenced instruments, including optional references, and use the sealed public ID grammar.
+
+## [2.3.0] - 2026-09-14
+
+### Added
+
+- `instrumentFinanceIssues(instrument, options?)` exposes the funded-amount conservation proof for one instrument. An instrument with a `piecePlan` is unfolded over piece progress (which pieces are funded, which are consumed) the same way the runtime admits pieces: the next piece in the stage's order, fund refused once any piece has left escrow, the lifecycle state retained until the stage's last eligible piece, and `requiresDrainedAccount` actions closed while held pieces remain. `validateUdl` runs the same proof, so a plan whose refund or unfund order skips a funded piece is refused with `UDL4001` on the authored action and state names.
+- A call binding may name `$instance.refs.<name>` when a step or move on the same instrument captures that ref; a captured `accountId` binds as an account, any other capture as text.
+
+### Changed
+
+- The piece-progress unfolding is bounded by the action expansion limit (256 reachable variants); exceeding it reports `UDL2010`.
+- Sandbox failure points and finance proofs judge a call-based action by its resolved plan leaves, not by authored moves it does not have.
+
 ## [2.2.0] - 2026-09-14
 
 ### Changed

package/README.md

@@ -56,7 +56,11 @@ Save this document as `note.udl`:
 }
 ```
 
-Check the document with the CLI:
+In the full repository checkout, the UDL CLI entrypoint is `open/udl/src/cli.ts`. Validate local compiler output with `bun open/udl/src/cli.ts validate note.udl` from the repository root so the compiler and validator use the same source revision. In a standalone UDL package checkout, use `bun src/cli.ts validate note.udl`.
+
+For npm installations, pair HSX 2.2.0 with UDL 2.4.0. HSX 2.1.1 as published pairs with UDL 2.3.0; a checkout with later clauses such as `templateBinding` needs the local validator even if its package version has not yet changed. These are package versions; the UDL document format remains version 1.
+
+Check the document with the installed CLI:
 
 ```bash
 npx @hyperscale0/udl validate note.udl

package/conformance/invalid/invalid-journeys.expected.json

@@ -1,26 +1,10 @@
 {
-  "summary": "Authored journeys reject unknown operations, unknown examples, missing bindings, invalid transitions, and duplicate step ids.",
+  "summary": "The retired journeys clause is refused rather than ignored.",
   "verdict": "invalid",
   "issues": [
     {
-      "code": "journey_unknown_operation",
-      "path": "$.instruments[0].journeys[0].steps[0].operation"
-    },
-    {
-      "code": "journey_unknown_example",
-      "path": "$.instruments[0].journeys[1].steps[0].example"
-    },
-    {
-      "code": "journey_unbound_reference",
-      "path": "$.instruments[0].journeys[2].steps[1].bind.noteId"
-    },
-    {
-      "code": "journey_invalid_transition",
-      "path": "$.instruments[0].journeys[3].steps[2].operation"
-    },
-    {
-      "code": "journey_duplicate_step_id",
-      "path": "$.instruments[0].journeys[4].steps[1].id"
+      "code": "UDL1003",
+      "path": "$.instruments[0]"
     }
   ]
 }

package/conformance/invalid/invalid-journeys.udl

@@ -1,79 +1,77 @@
 {
   "instruments": [
     {
-      "actionOrder": ["create", "close"],
+      "actionOrder": [
+        "close",
+        "create"
+      ],
       "actions": {
-        "create": {
-          "examples": [{ "input": { "reference": "example" }, "name": "default" }],
+        "close": {
           "moves": [],
           "steps": [],
-          "summary": "File the note."
+          "summary": "Close the note."
         },
-        "close": {
-          "examples": [{ "input": {}, "name": "default" }],
+        "create": {
+          "examples": [
+            {
+              "input": {
+                "reference": "example"
+              },
+              "name": "default"
+            }
+          ],
           "moves": [],
           "steps": [],
-          "summary": "Close the note."
+          "summary": "File the note."
+        }
+      },
+      "fields": {
+        "reference": {
+          "type": "string"
         }
       },
-      "fields": { "reference": { "type": "string" } },
       "id": "note",
       "idPrefix": "note",
       "journeys": [
         {
-          "id": "unknown_operation",
-          "label": "Unknown operation",
-          "steps": [{ "bind": {}, "example": "default", "operation": "note.missing" }],
-          "summary": "Refuse an unknown operation."
-        },
-        {
-          "id": "unknown_example",
-          "label": "Unknown example",
-          "steps": [{ "bind": {}, "example": "missing", "operation": "note.create" }],
-          "summary": "Refuse an unknown example."
-        },
-        {
-          "id": "unbound_reference",
-          "label": "Unbound reference",
-          "steps": [
-            { "bind": {}, "example": "default", "id": "note", "operation": "note.create" },
-            { "bind": {}, "example": "default", "operation": "note.close" }
-          ],
-          "summary": "Refuse an unbound reference."
-        },
-        {
-          "id": "invalid_transition",
-          "label": "Invalid transition",
+          "id": "file_note",
+          "label": "File a note",
           "steps": [
-            { "bind": {}, "example": "default", "id": "note", "operation": "note.create" },
-            { "bind": { "noteId": "note" }, "example": "default", "operation": "note.close" },
-            { "bind": { "noteId": "note" }, "example": "default", "operation": "note.close" }
+            {
+              "bind": {},
+              "example": "default",
+              "id": "note",
+              "operation": "note.create"
+            }
           ],
-          "summary": "Refuse an invalid transition."
-        },
-        {
-          "id": "duplicate_step_id",
-          "label": "Duplicate step id",
-          "steps": [
-            { "bind": {}, "example": "default", "id": "duplicate", "operation": "note.create" },
-            { "bind": {}, "example": "default", "id": "duplicate", "operation": "note.create" }
-          ],
-          "summary": "Refuse a duplicate step id."
+          "summary": "File a note."
         }
       ],
       "lifecycle": {
         "initial": "open",
-        "states": ["open", "closed"],
-        "transitions": { "close": { "from": ["open"], "to": "closed" } }
+        "states": [
+          "open",
+          "closed"
+        ],
+        "transitions": {
+          "close": {
+            "from": [
+              "open"
+            ],
+            "to": "closed"
+          }
+        }
       },
-      "required": ["reference"],
+      "required": [
+        "reference"
+      ],
       "summary": "A note a tenant files and later closes.",
       "title": "Note"
     }
   ],
-  "product": "invalid_journeys",
+  "product": "minimal",
   "subjects": [],
-  "title": "Invalid journeys",
+  "title": "Minimal",
   "udl": 1,
   "version": 1
 }

package/conformance/valid/attested.expected.json

@@ -0,0 +1,6 @@
+{
+  "canonical": "attested.udl",
+  "digest": "aa584ac3a220b85cff4c2f36ae56324427b5905ac549a89f7be4a403c3ce006d",
+  "summary": "Server-bound request authority and one approved decision with engine-owned consumption",
+  "verdict": "valid"
+}

package/conformance/valid/attested.udl

@@ -0,0 +1,251 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "approve",
+        "consume"
+      ],
+      "actions": {
+        "approve": {
+          "agentDescription": "Record the bound deciding account.",
+          "effects": {
+            "decides": [
+              {
+                "signature": "decides.tenant_port",
+                "source": "port"
+              }
+            ]
+          },
+          "moves": [],
+          "port": {
+            "allowedParties": [
+              "decider"
+            ],
+            "capture": "decidedBy"
+          },
+          "steps": [],
+          "summary": "Approve instrument"
+        },
+        "consume": {
+          "agentDescription": "Consume this approval within the admitted operation.",
+          "captureEngine": {
+            "consumedByOperationId": "operationId"
+          },
+          "engineOwned": true,
+          "moves": [],
+          "steps": [],
+          "summary": "Consume instrument"
+        },
+        "create": {
+          "agentDescription": "Store the immutable request terms.",
+          "moves": [],
+          "requestAuthority": {
+            "actionField": "actionName",
+            "digestField": "digest",
+            "expiresField": "expiry",
+            "inputField": "requestInput",
+            "instanceField": "requestId",
+            "instrumentField": "requestInstrument",
+            "party": "decider",
+            "roleField": "role"
+          },
+          "steps": [],
+          "summary": "Create instrument"
+        }
+      },
+      "agentDescription": "Record approval for one exact request.",
+      "fields": {
+        "actionName": {
+          "type": "string"
+        },
+        "decidedBy": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "deciderAccount": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "digest": {
+          "pattern": "^[a-f0-9]{64}$",
+          "type": "string"
+        },
+        "expiry": {
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "requestId": {
+          "type": "string"
+        },
+        "requestInput": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "requestInstrument": {
+          "type": "string"
+        },
+        "role": {
+          "type": "string"
+        }
+      },
+      "id": "approval",
+      "idPrefix": "apr",
+      "lifecycle": {
+        "initial": "requested",
+        "states": [
+          "requested",
+          "approved",
+          "consumed"
+        ],
+        "transitions": {
+          "approve": {
+            "from": [
+              "requested"
+            ],
+            "to": "approved"
+          },
+          "consume": {
+            "from": [
+              "approved"
+            ],
+            "to": "consumed"
+          }
+        }
+      },
+      "parties": {
+        "decider": "deciderAccount"
+      },
+      "required": [
+        "deciderAccount",
+        "requestId",
+        "requestInstrument",
+        "actionName",
+        "digest",
+        "role",
+        "expiry"
+      ],
+      "summary": "Approval instrument",
+      "title": "Approval"
+    },
+    {
+      "actionOrder": [
+        "create",
+        "accept"
+      ],
+      "actions": {
+        "accept": {
+          "agentDescription": "Accept the exact approved amount once.",
+          "effects": {
+            "decides": [
+              {
+                "signature": "decides.referenced_transition",
+                "source": "transitionsRefs[0]"
+              }
+            ],
+            "reads": [
+              {
+                "signature": "reads.requires_refs",
+                "source": "requiresRefs"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "amount": {
+                "pattern": "^[1-9][0-9]{0,17}$",
+                "type": "string",
+                "x-hyperscale-currency": "SAR"
+              }
+            },
+            "required": [
+              "amount"
+            ],
+            "type": "object"
+          },
+          "moves": [],
+          "requiresInput": {
+            "amount": "fields.amount"
+          },
+          "requiresRefs": [
+            {
+              "attests": {
+                "action": "fields.actionName",
+                "consume": "consume",
+                "digest": "fields.digest",
+                "expiresAt": "fields.expiry",
+                "instrument": "fields.requestInstrument",
+                "party": "decider",
+                "role": "fields.role"
+              },
+              "field": "approvalId",
+              "match": {
+                "instrumentInstanceId": "fields.requestId"
+              },
+              "statuses": [
+                "approved"
+              ]
+            }
+          ],
+          "steps": [],
+          "summary": "Accept instrument"
+        },
+        "create": {
+          "agentDescription": "Store the immutable request terms.",
+          "moves": [],
+          "steps": [],
+          "summary": "Create instrument"
+        }
+      },
+      "agentDescription": "Admit only the independently approved request.",
+      "fields": {
+        "amount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
+        },
+        "approvalId": {
+          "pattern": "^apr_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        }
+      },
+      "id": "request",
+      "idPrefix": "req",
+      "lifecycle": {
+        "initial": "open",
+        "states": [
+          "open",
+          "done"
+        ],
+        "transitions": {
+          "accept": {
+            "from": [
+              "open"
+            ],
+            "to": "done"
+          }
+        }
+      },
+      "required": [
+        "approvalId",
+        "amount",
+        "currency"
+      ],
+      "summary": "Request instrument",
+      "title": "Request"
+    }
+  ],
+  "product": "attested",
+  "subjects": [],
+  "title": "Attested action",
+  "udl": 1,
+  "version": 1
+}

package/conformance/valid/hand-edited.expected.json

@@ -1,6 +1,6 @@
 {
   "canonical": "minimal.udl",
-  "digest": "d7a742548bf559eaa3101e09e0c404190957e34854b220ca010d145d4fd9cae6",
+  "digest": "7933986489470a2e95e316c854077b6f970b1228679ea86d71d8c4c276e89624",
   "summary": "Compact, reverse-ordered bytes canonicalize to minimal.udl.",
   "verdict": "valid"
 }

package/conformance/valid/hand-edited.udl

@@ -1 +1 @@
-{"version":1,"udl":1,"title":"Minimal","subjects":[],"product":"minimal","instruments":[{"fields":{"reference":{"type":"string"}},"id":"note","idPrefix":"note","journeys":[{"id":"file_note","label":"File a note","steps":[{"bind":{},"example":"default","id":"note","operation":"note.create"}],"summary":"File a note."}],"lifecycle":{"initial":"open","states":["open","closed"],"transitions":{"close":{"from":["open"],"to":"closed"}}},"required":["reference"],"summary":"A note a tenant files and later closes.","title":"Note","actionOrder":["close","create"],"actions":{"close":{"moves":[],"steps":[],"summary":"Close the note."},"create":{"examples":[{"input":{"reference":"example"},"name":"default"}],"moves":[],"steps":[],"summary":"File the note."}}}]}
+{"version":1,"udl":1,"title":"Minimal","subjects":[],"product":"minimal","instruments":[{"fields":{"reference":{"type":"string"}},"id":"note","idPrefix":"note","lifecycle":{"initial":"open","states":["open","closed"],"transitions":{"close":{"from":["open"],"to":"closed"}}},"required":["reference"],"summary":"A note a tenant files and later closes.","title":"Note","actionOrder":["close","create"],"actions":{"close":{"moves":[],"steps":[],"summary":"Close the note."},"create":{"examples":[{"input":{"reference":"example"},"name":"default"}],"moves":[],"steps":[],"summary":"File the note."}}}]}

package/conformance/valid/minimal.expected.json

@@ -1,6 +1,6 @@
 {
   "canonical": "minimal.udl",
-  "digest": "d7a742548bf559eaa3101e09e0c404190957e34854b220ca010d145d4fd9cae6",
+  "digest": "7933986489470a2e95e316c854077b6f970b1228679ea86d71d8c4c276e89624",
   "summary": "The smallest document the grammar and the semantic laws both accept.",
   "verdict": "valid"
 }

package/conformance/valid/minimal.udl

@@ -32,21 +32,6 @@
       },
       "id": "note",
       "idPrefix": "note",
-      "journeys": [
-        {
-          "id": "file_note",
-          "label": "File a note",
-          "steps": [
-            {
-              "bind": {},
-              "example": "default",
-              "id": "note",
-              "operation": "note.create"
-            }
-          ],
-          "summary": "File a note."
-        }
-      ],
       "lifecycle": {
         "initial": "open",
         "states": [

package/conformance/valid/vocabulary.expected.json

@@ -0,0 +1,6 @@
+{
+  "canonical": "vocabulary.udl",
+  "digest": "c4d53928531382cf5e24bcb52c5350889531a8d978252b34f5416f87146bae1a",
+  "summary": "Schedules, allocation, grouped ticket admission, funding snapshots and receipt distributions",
+  "verdict": "valid"
+}