@hyperscale0/udl 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -8,6 +8,22 @@ Format version and package version are different numbers.
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-14
+
+Published in lockstep with HSX 2.1.0.
+
+### Added
+
+- An instrument may declare `piecePlan`: a total field partitioned into named pieces, each with an amount field and immutable release and refund payees, plus `fundOrder`, `releaseOrder`, `refundOrder` and `unfundOrder`. Fund covers every piece, unfund reverses fund, and the other orders may select subsets. Piece amount fields must be distinct and partition the total in one concrete currency; a singleton may bind the total itself.
+- An action may declare `pieceStage` (`plan` and `stage`) to move one piece of a plan. The compiler derives the required `pieceId` input from the selected order and adds no movement of its own; the money flows through the action's `calls`.
+- An action may declare `calls` to typed private actions from an `actionLibrary`, binding parameters from `$instance`, `$piece` or its own inputs and capturing results by name. Private actions never carry independent approval or recovery.
+- Diagnostics `UDL2010` (action graph: cycles, unresolved targets, expansion bound), `UDL2011` (call bindings: forward references, `$results.*`, types), `UDL2012` (call authority: principal, approval and recovery boundary), `UDL2013` (leaf effects and evidence), `UDL4002` (piece partition) and `UDL5013` (piece stage). Each has a conformance case under `conformance/invalid` and a clause reference entry.
+- `resolveUdlActionPlans` exposes the expanded action plans and their diagnostics.
+
+### Changed
+
+- The schema specification, clause reference and diagnostics reference are regenerated for the new clauses.
+
 ## [2.0.4] - 2026-09-11
 
 - Republished in lockstep with HSX 2.0.4. No format or API change.

package/README.md

@@ -1,7 +1,17 @@
-![UDL: The contract between a product and its engine.](docs/assets/udl.svg)
+<p align="left">
+<picture>
+  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/assets/brand/udl-stacked-white.svg">
+  <source media="(max-width: 600px)" srcset="docs/assets/brand/udl-stacked.svg">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/udl-horizontal-white.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/brand/udl-horizontal.svg">
+  <img src="docs/assets/brand/udl-horizontal.svg" alt="Hyperscale™ UDL" width="336">
+</picture>
+</p>
 
 # UDL
 
+Hyperscale™ UDL. The canonical contract between a financial product and its engine.
+
 UDL is the Universal Domain Language, the canonical JSON contract for a financial product. One `.udl` file declares subjects, instruments, lifecycles, actions, and money movement. An engine admits that document without reading the source language that produced it. UDL keeps provider machinery below the format: it has no file drops, polling loops, cutoff jobs, scheme messages, or provider statement schemas. The `reconcile` clause names settlement evidence against a declared provider-side row; it does not model provider transport or matching machinery.
 
 ## Install
@@ -96,3 +106,7 @@ The evolution diff API (`diffValidatedUdlEvolution`, `diffInstrumentEvolution`,
 UDL is licensed under AGPL-3.0-only, with a commercial license available from Hyperscale LLC. See [LICENSE](LICENSE), [LICENSING.md](LICENSING.md), and [TRADEMARKS.md](TRADEMARKS.md).
 
 Vulnerability reports go through private disclosure as described in [SECURITY.md](SECURITY.md).
+
+---
+
+Hyperscale™ is a trademark of Hyperscale LLC. Code licenses do not grant rights to the name or marks.

package/conformance/invalid/call-binds-results.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL2011",
+      "path": "$.instruments[0].actions.fund_piece.calls.call_fund.bind.p"
+    }
+  ],
+  "summary": "Call bindings are static; $results is not a binding scope.",
+  "verdict": "invalid"
+}

package/conformance/invalid/call-binds-results.udl

@@ -0,0 +1,314 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "fund_piece",
+        "payout_piece"
+      ],
+      "actions": {
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "Create watch instrument"
+        },
+        "fund_piece": {
+          "calls": [
+            {
+              "action": "transfers.execute_fund",
+              "bind": {
+                "inst": "$instance",
+                "p": "$results.previous_leaf"
+              },
+              "id": "call_fund"
+            }
+          ],
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "fund_piece.call_fund.leaf_fund"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "pieceId": {
+                "enum": [
+                  "p1",
+                  "p2"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "pieceId"
+            ],
+            "type": "object"
+          },
+          "moves": [],
+          "pieceStage": {
+            "plan": "split_plan",
+            "stage": "fund"
+          },
+          "steps": [],
+          "summary": "Fund one piece in stage"
+        },
+        "payout_piece": {
+          "calls": [
+            {
+              "action": "transfers.execute_release",
+              "bind": {
+                "inst": "$instance",
+                "p": "$piece"
+              },
+              "id": "call_rel"
+            }
+          ],
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "payout_piece.call_rel.leaf_rel"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "pieceId": {
+                "enum": [
+                  "p1",
+                  "p2"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "pieceId"
+            ],
+            "type": "object"
+          },
+          "moves": [],
+          "pieceStage": {
+            "plan": "split_plan",
+            "stage": "release"
+          },
+          "steps": [],
+          "summary": "Release piece"
+        }
+      },
+      "actionLibrary": {
+        "transfers": {
+          "actionOrder": [
+            "execute_fund",
+            "execute_release"
+          ],
+          "actions": {
+            "execute_fund": {
+              "approval": "inherit",
+              "calls": [],
+              "leaves": [
+                {
+                  "bind": {
+                    "amount": "$p.amount",
+                    "destinationAccountId": "$p.release_to",
+                    "sourceAccountId": "$inst.fields.buyerAccount"
+                  },
+                  "effects": [
+                    {
+                      "kind": "moves",
+                      "signature": "moves.transfer.internal"
+                    }
+                  ],
+                  "evidence": "bank transfer confirmation receipt",
+                  "id": "leaf_fund",
+                  "operation": "internal_transfer.create"
+                }
+              ],
+              "order": [
+                "leaf_fund"
+              ],
+              "parameters": {
+                "inst": {
+                  "kind": "instance"
+                },
+                "p": {
+                  "kind": "piece"
+                }
+              },
+              "principal": "api_key",
+              "recovery": "local"
+            },
+            "execute_release": {
+              "approval": "inherit",
+              "calls": [],
+              "leaves": [
+                {
+                  "bind": {
+                    "amount": "$p.amount",
+                    "destinationAccountId": "$p.release_to",
+                    "sourceAccountId": "$inst.fields.escrowAccount"
+                  },
+                  "effects": [
+                    {
+                      "kind": "moves",
+                      "signature": "moves.transfer.internal"
+                    }
+                  ],
+                  "evidence": "release to payee confirmation",
+                  "id": "leaf_rel",
+                  "operation": "internal_transfer.create"
+                }
+              ],
+              "order": [
+                "leaf_rel"
+              ],
+              "parameters": {
+                "inst": {
+                  "kind": "instance"
+                },
+                "p": {
+                  "kind": "piece"
+                }
+              },
+              "principal": "api_key",
+              "recovery": "local"
+            }
+          }
+        }
+      },
+      "fields": {
+        "buyerAccount": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "currency": {
+          "const": "USD",
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "escrowAccount": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p1Amount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        },
+        "p1Refund": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p1Release": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p2Amount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        },
+        "p2Refund": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p2Release": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "totalAmount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        }
+      },
+      "id": "escrow_watch",
+      "idPrefix": "ew",
+      "lifecycle": {
+        "initial": "draft",
+        "states": [
+          "draft",
+          "funded",
+          "released"
+        ],
+        "transitions": {
+          "fund_piece": {
+            "from": [
+              "draft"
+            ],
+            "to": "funded"
+          },
+          "payout_piece": {
+            "from": [
+              "funded"
+            ],
+            "to": "released"
+          }
+        }
+      },
+      "partitions": [
+        {
+          "pieceFields": [
+            "p1Amount",
+            "p2Amount"
+          ],
+          "totalField": "totalAmount"
+        }
+      ],
+      "piecePlan": {
+        "fund_order": [
+          "p1",
+          "p2"
+        ],
+        "id": "split_plan",
+        "pieces": [
+          {
+            "amount": "p1Amount",
+            "id": "p1",
+            "refund_to": "p1Refund",
+            "release_to": "p1Release"
+          },
+          {
+            "amount": "p2Amount",
+            "id": "p2",
+            "refund_to": "p2Refund",
+            "release_to": "p2Release"
+          }
+        ],
+        "refund_order": [
+          "p1"
+        ],
+        "release_order": [
+          "p1",
+          "p2"
+        ],
+        "total": "totalAmount",
+        "unfund_order": [
+          "p2",
+          "p1"
+        ]
+      },
+      "required": [
+        "totalAmount",
+        "p1Amount",
+        "p2Amount",
+        "p1Release",
+        "p1Refund",
+        "p2Release",
+        "p2Refund",
+        "buyerAccount",
+        "escrowAccount"
+      ],
+      "summary": "Escrow watch contract with piece plan",
+      "title": "Escrow Watch"
+    }
+  ],
+  "product": "escrow_watch",
+  "subjects": [],
+  "title": "Escrow Watch Document",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/call-unknown-action.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL2010",
+      "path": "$.instruments[0].actions.fund_piece.calls.call_fund.action"
+    }
+  ],
+  "summary": "A call names an action the library does not declare.",
+  "verdict": "invalid"
+}

package/conformance/invalid/call-unknown-action.udl

@@ -0,0 +1,314 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "fund_piece",
+        "payout_piece"
+      ],
+      "actions": {
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "Create watch instrument"
+        },
+        "fund_piece": {
+          "calls": [
+            {
+              "action": "transfers.unknown_action",
+              "bind": {
+                "inst": "$instance",
+                "p": "$piece"
+              },
+              "id": "call_fund"
+            }
+          ],
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "fund_piece.call_fund.leaf_fund"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "pieceId": {
+                "enum": [
+                  "p1",
+                  "p2"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "pieceId"
+            ],
+            "type": "object"
+          },
+          "moves": [],
+          "pieceStage": {
+            "plan": "split_plan",
+            "stage": "fund"
+          },
+          "steps": [],
+          "summary": "Fund one piece in stage"
+        },
+        "payout_piece": {
+          "calls": [
+            {
+              "action": "transfers.execute_release",
+              "bind": {
+                "inst": "$instance",
+                "p": "$piece"
+              },
+              "id": "call_rel"
+            }
+          ],
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "payout_piece.call_rel.leaf_rel"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "pieceId": {
+                "enum": [
+                  "p1",
+                  "p2"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "pieceId"
+            ],
+            "type": "object"
+          },
+          "moves": [],
+          "pieceStage": {
+            "plan": "split_plan",
+            "stage": "release"
+          },
+          "steps": [],
+          "summary": "Release piece"
+        }
+      },
+      "actionLibrary": {
+        "transfers": {
+          "actionOrder": [
+            "execute_fund",
+            "execute_release"
+          ],
+          "actions": {
+            "execute_fund": {
+              "approval": "inherit",
+              "calls": [],
+              "leaves": [
+                {
+                  "bind": {
+                    "amount": "$p.amount",
+                    "destinationAccountId": "$p.release_to",
+                    "sourceAccountId": "$inst.fields.buyerAccount"
+                  },
+                  "effects": [
+                    {
+                      "kind": "moves",
+                      "signature": "moves.transfer.internal"
+                    }
+                  ],
+                  "evidence": "bank transfer confirmation receipt",
+                  "id": "leaf_fund",
+                  "operation": "internal_transfer.create"
+                }
+              ],
+              "order": [
+                "leaf_fund"
+              ],
+              "parameters": {
+                "inst": {
+                  "kind": "instance"
+                },
+                "p": {
+                  "kind": "piece"
+                }
+              },
+              "principal": "api_key",
+              "recovery": "local"
+            },
+            "execute_release": {
+              "approval": "inherit",
+              "calls": [],
+              "leaves": [
+                {
+                  "bind": {
+                    "amount": "$p.amount",
+                    "destinationAccountId": "$p.release_to",
+                    "sourceAccountId": "$inst.fields.escrowAccount"
+                  },
+                  "effects": [
+                    {
+                      "kind": "moves",
+                      "signature": "moves.transfer.internal"
+                    }
+                  ],
+                  "evidence": "release to payee confirmation",
+                  "id": "leaf_rel",
+                  "operation": "internal_transfer.create"
+                }
+              ],
+              "order": [
+                "leaf_rel"
+              ],
+              "parameters": {
+                "inst": {
+                  "kind": "instance"
+                },
+                "p": {
+                  "kind": "piece"
+                }
+              },
+              "principal": "api_key",
+              "recovery": "local"
+            }
+          }
+        }
+      },
+      "fields": {
+        "buyerAccount": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "currency": {
+          "const": "USD",
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "escrowAccount": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p1Amount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        },
+        "p1Refund": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p1Release": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p2Amount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        },
+        "p2Refund": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "p2Release": {
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "totalAmount": {
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string",
+          "x-hyperscale-currency": "USD"
+        }
+      },
+      "id": "escrow_watch",
+      "idPrefix": "ew",
+      "lifecycle": {
+        "initial": "draft",
+        "states": [
+          "draft",
+          "funded",
+          "released"
+        ],
+        "transitions": {
+          "fund_piece": {
+            "from": [
+              "draft"
+            ],
+            "to": "funded"
+          },
+          "payout_piece": {
+            "from": [
+              "funded"
+            ],
+            "to": "released"
+          }
+        }
+      },
+      "partitions": [
+        {
+          "pieceFields": [
+            "p1Amount",
+            "p2Amount"
+          ],
+          "totalField": "totalAmount"
+        }
+      ],
+      "piecePlan": {
+        "fund_order": [
+          "p1",
+          "p2"
+        ],
+        "id": "split_plan",
+        "pieces": [
+          {
+            "amount": "p1Amount",
+            "id": "p1",
+            "refund_to": "p1Refund",
+            "release_to": "p1Release"
+          },
+          {
+            "amount": "p2Amount",
+            "id": "p2",
+            "refund_to": "p2Refund",
+            "release_to": "p2Release"
+          }
+        ],
+        "refund_order": [
+          "p1"
+        ],
+        "release_order": [
+          "p1",
+          "p2"
+        ],
+        "total": "totalAmount",
+        "unfund_order": [
+          "p2",
+          "p1"
+        ]
+      },
+      "required": [
+        "totalAmount",
+        "p1Amount",
+        "p2Amount",
+        "p1Release",
+        "p1Refund",
+        "p2Release",
+        "p2Refund",
+        "buyerAccount",
+        "escrowAccount"
+      ],
+      "summary": "Escrow watch contract with piece plan",
+      "title": "Escrow Watch"
+    }
+  ],
+  "product": "escrow_watch",
+  "subjects": [],
+  "title": "Escrow Watch Document",
+  "udl": 1,
+  "version": 1
+}