@hyperscale0/udl 2.6.1 → 3.0.0

package/CHANGELOG.md

@@ -1,331 +1,3 @@
-# Changelog
+# UDL 3.0.0
 
-All notable changes to this package are documented here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package
-follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-Format version and package version are different numbers.
-
-## [2.6.1] - 2026-09-17
-
-Pairs with HSX 2.4.1.
-
-### Changed
-
-- README pairs the package with HSX 2.4.1. No format or validator change.
-
-## [2.6.0] - 2026-09-17
-
-### Added
-
-- `cascade`: executes a named lifecycle action on linked instances of another instrument inside the same transaction before evaluating the parent action's gates. A cascade target action may declare a port when the parent action declares a port.
-- Validate cascade `inputField` against reserved protocol fields (`tenantId`, `productId`, `actorAccountId`) and the instrument instance key.
-- Snapshot cascade declarations in `EvolutionActionSnapshot` and report changed or removed cascade configurations as breaking changes.
-
-## [2.5.0] - 2026-09-17
-
-### Changed
-
-- The `hyperscale-date-time` format admits any RFC 3339 offset, not only `Z`. Hosts normalise the value to its UTC instant on admission.
-
-## [2.4.0] - 2026-09-15
-
-### Added
-
-- `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.
-- 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.
-
-- 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
-
-- `resolveUdlActionPlans` returns a plan for every action. Ordinary actions (no `calls`, no `pieceStage`) now resolve to flat leaves in executor order: each `steps` entry, the `payout` intent as a `payout.create` step, then each `moves` entry. Every leaf carries an `originPath` into the authored action and the clause-vocabulary effects derived for that source. Compilers no longer need a separate path for actions that never expanded.
-- `ResolvedActionPlanLeaf.step` admits the synthetic `payout.create` step alongside authored steps and moves.
-
-## [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.
-
-## [2.0.3] - 2026-09-10
-
-Published in lockstep with HSX 2.0.3.
-
-### Added
-
-- A quote may declare `chargeRetainedBy` (`payer`, `beneficiary`, or `subjectHolder`). The named role keeps the quoted charge in the source account instead of moving it through a payout action. `UDL5006` refuses a retained charge whose refund source is not that role's account, a charge reference any action consumes, and a self-transfer. The finance walk keeps proving the refund source account when the charge is retained.
-
-## [2.0.2] - 2026-09-10
-
-- Republished in lockstep with HSX 2.0.2. The README no longer points at a GitHub Actions publish path, and the workflows are removed. No format or API change.
-
-## [2.0.1] - 2026-09-10
-
-Published in lockstep with HSX 2.0.1. No functional change.
-
-## [2.0.0] - 2026-09-10
-
-Published in lockstep with HSX 2.0.0.
-
-### Added
-
-- Money field schemas may carry `x-hyperscale-currency`; `UDL6001` refuses any value that is not a three-letter uppercase code on a string schema.
-- `dateComparison` reference laws compare a local date field against a referenced instrument's date field with a matched-field guard.
-- Aggregate invariants sum integer supply fields, not only money fields, so share allocations cannot exceed an offering's supply.
-- `validateUdl` takes options, and the document schema gains `journey` and composition dial definitions.
-- Evolution comparison reports a changed `sandboxFailurePoint`.
-
-### Changed
-
-- Finance laws know the declared parties: distinct declared parties never alias, and terminal stranding applies only to `ref:` accounts.
-- Field descriptions are prose and no longer part of the frozen schema; the migration plan says recompose is refused when a frozen field changes.
-
-## [1.0.0] - 2026-09-04
-
-This release is byte-identical to 1.0.0-rc.1.
-
-## [1.0.0-rc.1] - 2026-09-02
-
-### Added
-
-- Stable `UDL####` diagnostics include a category, fix, message, and JSON path.
-- Evolution comparison returns coded issues instead of strings.
-- `canonicalDigest` returns a promise for SHA-256 over canonical UTF-8 bytes.
-- `udl canon` prints canonical bytes or their digest, and `udl explain` prints
-  the catalog entry for one code.
-- The conformance runner has evolution pairs and pins canonical digests, issue
-  codes, and paths.
-- Eight guides, generated clause, diagnostic, and command references,
-  `llms.txt`, `llms-full.txt`, and an agent skill now ship with the package.
-
-- `reconcile` declares one expectation about money an action cannot see yet:
-  the amount path, currency field, direction, the ref naming the provider-side
-  row, exactly one evidence source, a match law, and a window. The match law is
-  `exact`, `tolerance` bounded by a `reconcile_tolerance` dial, or `window`. An
-  expectation that never matches by the end of its window is carried by the
-  named exception child, capped by `maxOpen`. The child is declared and
-  validated at admission, not materialized: the transition refuses with
-  `state_conflict` naming it and the due sweep re-arms the expectation.
-  `UdlReconcile` exposes the clause type.
-- An action may declare a `quote` offer and exactly one other action may spend
-  it through `commit`. Both the base money field and the net destination are
-  mandatory members of `fixes`, and `fixes` and `updates` may not overlap.
-
-### Removed
-
-- `requiresSettlement` and `UdlRequiresSettlement` are gone. A payout-owning
-  instrument now declares exactly one action carrying `reconcile` against a
-  debit statement line, under any match law. There is no wrapper and no alias.
-
-### Changed
-
-- The npm package includes `docs/` and `skills/`.
-- Derived effect rows for `quote`, `commit`, and `reconcile` change the canonical
-  bytes of stored documents that carry `effects` for those clauses.
-- Format 1 now carries every instrument contract clause. Instrument metadata
-  includes archetype template, navigation, visibility, dials, caller-parked
-  states, and extensible subjects. Actions include check gates, remainder
-  arithmetic, field updates, principal policy, and sandbox failure points.
-- Remainder clauses declare their computed money refs, so computed money has
-  one authored source.
-- Evolution snapshots protect lifted clauses that affect composition,
-  admission, or execution. Navigation, examples, and parked-state reason text
-  remain editable presentation.
-
-## [1.0.0-beta.1] - 2026-08-29
-
-- This is the first beta and has no package behavior changes from
-  1.0.0-alpha.5.
-
-## [1.0.0-alpha.5] - 2026-08-29
-
-### Added
-
-- Actions may declare a camelCase `publicAction` as their author-approved public
-  name while the action key remains the lifecycle and execution identity. System
-  due actions must omit it. `udlPublicActionSchema` is exported for consumers
-  that admit the same name outside a complete document.
-- `captureInput` maps declared action input fields into durable receipt refs.
-  Declare only input properties from that action and allocate each captured key
-  in the instrument's shared ref namespace.
-- `signedSum` computes stored add and subtract subtotals over typed child money,
-  then captures one net amount for exactly one payout or instrument transfer. Authors
-  must declare the child reference, money field, currency, admitted statuses,
-  and explicit negative and zero policies.
-- `requiresExposure` gates a child amount against a stored cap, with an optional
-  anchor-specific cap, and `setsAt.marker` records occurrence timestamps that
-  cannot drive a due condition or deadline. Use these clauses for bounded
-  installment writes and per-anchor occurrence markers.
-- `distribute` allocates one parent money field or remainder-computed money ref
-  across typed children selected by status and stored weight. The validator
-  resolves the parent, weight, statuses, and pool before admitting the document.
-- Instruments may declare up to four `derivedAmounts`. Each rule computes a declared
-  money field as 1 through 9,999 basis points of another declared money field
-  with floor rounding. Callers supply neither the result nor a fixed or tiered
-  rule, and a rule may not derive a field from itself.
-- Actions may declare one `payout` intent that reads stored money, currency,
-  source-account, and beneficiary values and captures the payout reference.
-  This does not add an operation to the seven-instruction kernel.
-- A system-only `requiresSettlement` transition may read a captured payout
-  reference and capture the durable evidence record that matched it. The
-  validator rejects caller input, decision ports, public actions, due and
-  deadline triggers, kernel steps, and money moves on that transition.
-- `validateUdlJsonSchema` validates one schema against UDL's sealed JSON Schema
-  subset without applying it to a value. `UdlPayout` and
-  `UdlRequiresSettlement` expose the new clause types to TypeScript consumers.
-
-### Changed
-
-- Evolution snapshots freeze public actions, captured receipt input,
-  distribution rules, exposure gates, signed sums, computed money clauses, and
-  derived-amount arithmetic once a instrument has live instances. Older snapshots
-  remain readable when those keys are absent.
-- Evolution snapshots freeze both payout intents and settlement evidence gates.
-- Receipt refs written by the new clauses share the instrument ref namespace with
-  kernel captures, input captures, signed sums, subject refs, and unwind refs.
-
-## [1.0.0-alpha.4] - 2026-08-26
-
-### Removed
-
-- `diffUdlEvolution`. It validated both arguments and then handed off to
-  `diffValidatedUdlEvolution`, and nothing called it: `udl diff` and the
-  engine's composer both take the validated door. Two doors onto one comparison
-  meant every caller first had to work out which one it was standing in.
-  Validate with `validateUdl` or `assertValidUdl`, then call
-  `diffValidatedUdlEvolution`, whose `UdlDocument` parameters keep the compiler
-  on the right side of that rule.
-
-## [1.0.0-alpha.3] - 2026-08-25
-
-### Changed
-
-- `diffUdlEvolution` validates both arguments, so a document `validateUdl`
-  refuses now throws a `UdlError` carrying that document's issues where
-  alpha.2 returned evolution violations. Measured on
-  `conformance/valid/protection.udl` with the product renamed to
-  `protection_v2` and the live `claim` instrument dropped: alpha.2 returned three
-  violations, naming the rename, the removed live instrument, and the version that
-  did not move; this release throws `invalid_semantics` at
-  `$.instruments[0].aggregateInvariants[0].childInstrumentId`, because another instrument's
-  aggregate still references `claim`.
-
-  Read the throw as a refusal to judge, not as a verdict of no violations.
-  A `catch` that treats it as a schema problem and carries on has skipped the
-  append-only check entirely, and the candidate above is exactly the kind that
-  then sails through: dropping a live instrument is the headline violation the law
-  exists to catch. Fix the document, or use `diffValidatedUdlEvolution`.
-
-  The parameters are `unknown` because the function now accepts input nobody
-  has parsed. A caller who wants the compiler checking the call should hold
-  two validated documents and use `diffValidatedUdlEvolution`, which keeps the
-  `UdlDocument` parameter types.
-
-### Fixed
-
-- The evolution exports no longer route around the validator. `diffUdlEvolution`
-  took typed `UdlDocument` arguments and called neither `validateUdl` nor
-  `assertValidUdl` before reaching the diff's comparison key, so a caller
-  handing it an object it had never parsed got a `RangeError` off the call
-  stack where `validateUdl` returns a `resource_limit` issue for the same
-  object. It takes `unknown` now and validates both arguments.
-- The comparison key behind every diff carries the same depth budget the
-  validator applies to a document (`UDL_LIMITS.maxDepth`, 24 levels; the
-  deepest conformance document reaches 12). This is what protects
-  `diffInstrumentEvolution`, which takes snapshots no validator has seen, and it
-  closes the case where `snapshotUdlInstrument` returns a cyclic snapshot that only
-  detonates when something later stringifies it.
-
-### Added
-
-- `diffValidatedUdlEvolution`, the same comparison for a caller holding two
-  documents `validateUdl` has already admitted. It keeps the `UdlDocument`
-  parameter types, and it is the door for judging a candidate that is not yet
-  valid on its own. It also skips a validation the caller has already paid
-  for: on the commerce-escrow fixture `validateUdl` costs 0.57 ms against the
-  diff's 0.38 ms, so `udl diff`, which parses both files first, takes this
-  door rather than validating four documents to compare two.
-
-## [1.0.0-alpha.2] - 2026-08-23
-
-### Fixed
-
-- `bin` points at the built JavaScript; alpha.1's registry metadata pointed at
-  TypeScript source. npm builds the packument from package.json as it sits on
-  disk after `postpack`, so the pack-time rewrite never reached `bin`, and
-  every install linked `.bin/udl` to `src/cli.ts`, which Node refuses to
-  execute.
-
-### Changed
-
-- Licensed AGPL-3.0-only with a commercial license from Hyperscale LLC;
-  copyright holder Hyperscale LLC; repository renamed to
-  `hyperscale0/hyperscale-udl`.
-
-## [1.0.0-alpha.1] - 2026-08-22
-
-First public release. Format version 1.
-
-### Added
-
-- `spec/udl.schema.json`, JSON Schema 2020-12 generated from the grammar, plus
-  `spec/README.md` carrying the ten laws, the canonical form, and the issue
-  codes.
-- `conformance/`, the format's semantic spec as data: 7 valid documents with
-  their canonical bytes and 11 refused documents with the issue codes and JSON
-  paths they must report, runnable from any language.
-- The `udl` command: `udl validate`, `udl fmt [--write]`, and `udl diff`.
-- `bun run spec:check`, which fails when the committed schema drifts from the
-  grammar it was generated from.
-
-[Unreleased]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-rc.1...v1.0.0
-[1.0.0-rc.1]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-beta.1...v1.0.0-rc.1
-[1.0.0-beta.1]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.5...v1.0.0-beta.1
-[1.0.0-alpha.5]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.4...v1.0.0-alpha.5
-[1.0.0-alpha.4]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.3...v1.0.0-alpha.4
-[1.0.0-alpha.3]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.2...v1.0.0-alpha.3
-[1.0.0-alpha.2]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.1...v1.0.0-alpha.2
-[1.0.0-alpha.1]: https://github.com/hyperscale0/hyperscale-udl/releases/tag/v1.0.0-alpha.1
+Version 3 replaces the previous grammar. Recreate development estates. There is no migration reader.

package/LICENSING.md

@@ -40,8 +40,7 @@ says nothing about trademarks in either direction, so
 ## The format is not the implementation
 
 UDL the format is separate from this implementation of it. The JSON Schema in
-[`spec/`](./spec) and the conformance cases in [`conformance/`](./conformance)
-are data describing a format, and anyone may write their own parser, validator,
+[`spec/`](./spec) is data describing a format, and anyone may write their own parser, validator,
 or serializer against them, in any language, under any license, without
 touching this code.
 

package/README.md

@@ -1,116 +1,5 @@
-<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 3
 
-# UDL
+Read the [language reference](docs/README.md).
 
-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
-
-```bash
-npm install @hyperscale0/udl
-```
-
-This package contains the parser, semantic validator, canonical serializer, append-only evolution diff, JSON Schema, and conformance corpus.
-
-## First document
-
-Save this document as `note.udl`:
-
-```json
-{
-  "instruments": [
-    {
-      "actionOrder": ["close", "create"],
-      "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",
-      "actions": {
-        "close": { "moves": [], "steps": [], "summary": "Close the note." },
-        "create": { "moves": [], "steps": [], "summary": "File the note." }
-      }
-    }
-  ],
-  "product": "minimal",
-  "subjects": [],
-  "title": "Minimal",
-  "udl": 1,
-  "version": 1
-}
-```
-
-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.4.1 with UDL 2.6.1. 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
-npx @hyperscale0/udl fmt note.udl --write
-npx @hyperscale0/udl canon note.udl --digest
-```
-
-Exit code `0` means success. Exit code `1` means the validator refused the document. Exit code `2` means the invocation or file read failed.
-
-In TypeScript, parse, validate, and compare documents directly:
-
-```ts
-import { readFile, writeFile } from "node:fs/promises";
-import {
-  canonicalDigest,
-  diffValidatedUdlEvolution,
-  parseUdl,
-  serializeUdl,
-  validateUdl,
-} from "@hyperscale0/udl";
-
-const document = parseUdl(await readFile("note.udl"));
-await writeFile("note.udl", serializeUdl(document));
-console.log(await canonicalDigest(document));
-
-const result = validateUdl(document);
-if (!result.ok) console.error(result.issues);
-
-const previous = parseUdl(await readFile("note.previous.udl"));
-const violations = diffValidatedUdlEvolution(previous, document);
-```
-
-The evolution diff API (`diffValidatedUdlEvolution`, `diffInstrumentEvolution`, and `npx @hyperscale0/udl diff`) verifies that changes between two product versions are append-only. Adding optional fields, states, transitions, and actions is permitted; removing, renaming, or tightening existing structures returns `UDL7xxx` violation issues.
-
-## Documentation
-
-- [Guide and reading order](docs/README.md)
-- [Format specification](spec/README.md)
-- [Canonical bytes law](docs/reference/canonical.md)
-- [Stable diagnostics](docs/reference/diagnostics.md)
-- [Conformance suite](conformance/README.md)
-- [Agent skill](skills/udl/SKILL.md)
-- [Contributing](CONTRIBUTING.md)
-
-## License and security
-
-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.
+Run `bun run check` to build and check this package.

package/TRADEMARKS.md

@@ -25,8 +25,8 @@ What that means in practice:
 An independent implementation may say it "implements UDL version X" or "passes
 the UDL conformance suite version X" only while it passes the published
 conformance cases for that version, unmodified. The cases in
-[`conformance/`](./conformance) are the whole test: no skipped case, no edited
-expectation, no local fork of the fixtures.
+[`test/language.spec.ts`](./test/language.spec.ts) are the whole test: no skipped case, no edited
+expectation, no local change to the document mutations.
 
 That claim is a statement about your implementation, so keep the marks out of
 its name and off its logo, and do not present it as endorsement or