@hyperscale0/udl 2.6.1 → 3.0.0

package/docs/llms-full.txt

@@ -1,2008 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.1. Edit the source, not llms-full.txt. -->
-
-# UDL complete reference
-
-<!-- source: README.md -->
-
-# UDL documentation
-
-UDL is the versioned JSON contract between a product definition and an engine that executes it. Start with the document guide, then read the guides in order. Validator authors should also read the canonical bytes law and run the conformance corpus.
-
-1. [A document](guide/01-a-document.md)
-2. [Money steps](guide/02-money-steps.md)
-3. [The ten laws](guide/03-laws.md)
-4. [Fees and remainder](guide/04-fees-and-remainder.md)
-5. [Checks, updates, and dials](guide/05-checks-updates-dials.md)
-6. [Effects](guide/06-effects.md)
-7. [Evolution](guide/07-evolution.md)
-8. [Implementing UDL](guide/08-implementing.md)
-9. [Schedules, allocation and referenced state](guide/09-schedules-and-allocation.md)
-
-[Piece plans and private action composition](piece-plans.md) is a worked
-instrument fragment for `piecePlan`, `pieceStage`, `calls` and `actionLibrary`.
-
-The [clause reference](reference/clauses.md) and [diagnostic reference](reference/diagnostics.md) come from the package tables. The [command reference](reference/cli.md) comes from the CLI usage text. Run `bun run docs:build` in a source checkout. Package builds and prepack generate these ignored files automatically and validate local links.
-
-<!-- source: guide/01-a-document.md -->
-
-# A document
-
-A UDL document names one product and contains its subjects and instruments. Each instrument declares stored fields, required fields, a lifecycle, and the actions that create or change an instance.
-
-This is the smallest admitted document. `create` starts at `open`. `close` follows the matching lifecycle transition and ends at `closed`.
-
-```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
-}
-```
-
-The JSON Schema checks the written shape. `validateUdl` then checks names, references, lifecycle reachability, and the money graph. A document has no canonical form until both checks pass.
-
-<!-- source: guide/02-money-steps.md -->
-
-# Money steps
-
-UDL seals internal ledger work to seven kernel operations. Four instructions create, reserve, post, or void an internal transfer. Three account instructions provision an escrow account, freeze an account, or unfreeze it.
-
-A step names an operation and binds its inputs from action input, constants, or instance fields and refs. `capture` writes selected operation output into durable refs. A later step can read those refs.
-
-```jsonc
-{
-  "operation": "internal_transfer.reserve",
-  "bind": {
-    "sourceAccountId": { "from": "instance", "path": "fields.payerAccountId" },
-    "destinationAccountId": {
-      "from": "instance",
-      "path": "refs.escrowAccountId",
-    },
-    "amount": { "from": "instance", "path": "fields.amount" },
-    "currency": { "from": "const", "value": "SAR" },
-  },
-  "capture": { "transferId": "reservationId" },
-}
-```
-
-`payout` is an execution intent, not an eighth kernel operation. It reads stored money and beneficiary data, then captures a durable payout reference. A later system action can reconcile that payout against settlement evidence.
-
-<!-- source: guide/03-laws.md -->
-
-# The ten laws
-
-The schema defines shape. These laws define meaning.
-
-1. Every UDL concept fits in one sentence.
-2. Provider formats and operating machinery stay below UDL. `reconcile` names settlement evidence against a declared provider-side row. It does not model the provider file or transport.
-3. Every state change emits an event.
-4. Internal ledger money uses the seven sealed operations.
-5. Every instance has the same identity, status, timestamp, and metadata frame. Money uses integer minor-unit strings plus a currency.
-6. Requirements such as due time, checks, references, quote commitment, and reconciliation are data.
-7. A stored definition evolves by additive change only.
-8. Instruments, actions, operations, and fields follow their declared naming patterns.
-9. Real delays appear as statuses and timestamps.
-10. Every state, reference, gate, and funded path closes inside the document.
-
-A reconcile exception names the child fields that receive the unmatched amount and its reason. `exception.amountField` must be a required money field on the child. `exception.reasonField` must be a required plain text field. A plain text field has `type: "string"` and no `pattern`, `format`, or `enum`. Admission rejects a missing or optional field, the wrong type, or a child that does not belong to the declaring instrument.
-
-The [diagnostic reference](reference/diagnostics.md) lists every stable refusal code. The [specification](../spec/README.md) carries the normative prose for each law.
-
-<!-- source: guide/04-fees-and-remainder.md -->
-
-# Fees and remainder
-
-Fee rules derive named amounts from a stored base amount. Partitions state how cancellation or reversal divides held money. A remainder clause computes one amount after named deductions and captures it under `amountRef`.
-
-```jsonc
-{
-  "remainder": {
-    "amountRef": "sellerNet",
-    "from": "fields.amount",
-    "subtract": ["refs.platformFee"],
-  },
-}
-```
-
-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
-
-`requiresChecks` asks for current evidence from a declared provider family. The row names the check kind, acceptable statuses, subject field, and optional maximum age. Callers cannot replace the evidence with a boolean.
-
-`update` declares which stored fields an update operation may change. Action-level `updates` assign admitted values. Required creation fields, derived amounts, immutable bindings, and quote-frozen fields remain protected.
-
-Dials are named policy values with bounds. Clauses refer to a dial by id instead of copying a threshold into several actions. The document therefore exposes one reviewable setting for limits such as reconciliation tolerance.
-
-<!-- source: guide/06-effects.md -->
-
-# Effects
-
-Effects are derived ABI rows. Authors declare clauses such as moves, decisions, schedules, reads, and notifications. The compiler derives the `effects` object from those clauses in vocabulary order.
-
-Each row records its source and a stable signature. Movement signatures include their cost class. Schedule signatures identify a deadline or due trigger. Read signatures identify the gate family. Notification rows retain channel and role.
-
-The validator derives the rows again and compares the complete object, including row order. A missing, extra, changed, or reordered row is a refusal. Derived effect subtrees do not count toward the authored node budget, but they still pass JSON, depth, and string limits.
-
-Cost tooling reads the same movement and hold signatures. Runtime hints may read the effect rows, but they cannot change the clauses that produced them.
-
-`quote` derives `holds.quote` and `schedules.expiry`. `reconcile` derives one `reads.reconcile` row per expectation. `commit` has no separate effect row. The committing action consumes the held quote through its `moves.*` row, so another consumption row would count the same work twice.
-
-<!-- source: guide/07-evolution.md -->
-
-# Evolution
-
-`diffValidatedUdlEvolution(live, next)` compares two admitted documents. The CLI exposes the same check as `udl diff live.udl next.udl`.
-
-Once instances exist, a new version may add optional fields, states, transitions, and actions. It may not remove or rename stored structure, tighten an admitted schema, change a money step, or reuse an existing version number for different executable meaning. The diff returns `UDL7xxx` issues with JSON paths.
-
-A migration is work outside the format. It reads stored instances under their original document, writes data required by a new document, and changes the pinned definition only after that work succeeds. Editing the document does not migrate data.
-
-Keep old canonical documents with stored instances. A format bump changes the literal `udl` value. A reader must keep explicit decoders for supported older formats rather than silently treating old bytes as the newest grammar.
-
-Evolution does not invent defaults for executable clause fields. In particular, it does not guess `reconcile.exception.amountField` or `reasonField` for an older snapshot. A candidate must name both fields and pass the current validator before the diff can judge it.
-
-<!-- source: guide/08-implementing.md -->
-
-# Implementing UDL
-
-A second implementation needs three independent checks.
-
-1. Validate JSON shape against `spec/udl.schema.json`.
-2. Enforce the whole-document laws and report the matching stable diagnostic code and JSON path.
-3. Serialize admitted documents under the canonical bytes law.
-
-Run every conformance level. Valid cases must admit and match their canonical bytes and SHA-256 digest. Invalid cases must report every listed code and path. Evolution pairs must produce the listed `UDL7xxx` issues. An implementation may report more issues, but it may not omit a listed issue.
-
-Do not key behavior on diagnostic messages. Titles, details, and fixes can become clearer. Codes cannot change once published.
-
-Keep parsing, validation, canonicalization, and evolution comparison separate. That split prevents a diff from judging a candidate that the validator would refuse on its own.
-
-<!-- source: guide/09-schedules-and-allocation.md -->
-
-# Schedules, allocation and referenced state
-
-These clauses describe product laws. An engine must implement their admission semantics before accepting a document that uses them. The pure planners exported by this package calculate from trusted snapshots. They do not authenticate a caller, acquire locks, post money or claim an operation identity.
-
-## Fields and dates
-
-`derivedAmounts` retains its ordered list of computations. `percentage_of.bps` accepts a literal rate or `{field}`. The field must be required, immutable and bounded to integer basis points between 1 and 9999. `minimum` reads `sourceField` and `capField` in one currency. Both operands must be immutable money available at creation, supplied as required fields, derived earlier or bound from a reference. Bind a referenced cap into a local field through `requiresRefs.bind`. Floor rounding still applies. A derived operand must appear before its consumer.
-
-For a SAR 200 premium, 1000 bps produces SAR 20 and 500 bps produces SAR 10. Costs of SAR 12, 25 and 40 with a stored SAR 25 cap produce SAR 12, 25 and 25.
-
-`due.offset`, `deadline.offset` and an aggregate's `dueBefore.offset` accept a literal duration or `{field}`. A stored duration must enumerate positive fixed ISO durations. It cannot contain months or a runtime expression. The enclosing record supplies the field: a due-clock aggregate reads each candidate child's date and duration. The engine compares date plus offset to one authoritative admission time, including when the scheduler has not updated the child's status.
-
-`dateOrder` compares two immutable date fields on one instrument with `<` or `<=`. Distinct `requiresRefs` gates may constrain the same reference. Engines apply all gates as a conjunction, including both interval bounds. Repeating an identical gate remains invalid.
-
-## Aggregates and exact schedules
-
-`requiresAggregate.anchorField` selects the owner's parent reference. Candidate rows have their own `refField` pointing to that same parent. This lets a claim inspect premium slices of its cover without pretending those slices reference the claim. The engine locks the shared parent and the relevant row set. A `dueBefore` predicate applies before the aggregate check. A zero `count_exactly` over unpaid due slices refuses cover immediately at the clock boundary.
-
-`count_at_least.targetField` is an integer count. `ordered` checks strictly ascending dates in contiguous integer position order starting at 1. `schedule` additionally requires exact membership in the parent's immutable signed date list. No missing, extra or duplicate position is admitted. Every signed date must be strictly later than its predecessor. The engine reads the complete child set and checks statuses without discarding extra rows.
-
-For every declared schedule amount, each child receives integer division of the parent total by the signed date count. The first position receives the remainder. SAR 48,000 principal and SAR 2,400 profit over six dates therefore produce six SAR 8,000 principal and SAR 400 profit slices. Adding one minor unit to principal adds it to the first slice only. The date list is bounded to 366 entries.
-
-## Held partitions and contributions
-
-A `partitions` declaration is an exact equality, not a spending allowance. Admission verifies numeric equality and immutability. The finance proof can replace one complete funded partition with another partition of the same total on the same held account. Partial funding and already spent pieces do not establish the total. The proof permits one substitution per funded batch, with no active holds or unrelated balance. Draining the account resets that limit.
-
-`contributions` declares a required immutable list, its positive amount and origin-account keys, and a total money field. The list contains at most 256 entries. `contributionStage` funds every entry into one held account atomically or refunds every entry from that account to its original origin. Origins cannot equal the held account. The sum must equal the declared total. The engine derives operation identity from the instrument, stage and entry index and records the same entries for recovery.
-
-The SAR 60,000 witness receives SAR 12,000 and SAR 48,000. Its outgoing partition is SAR 59,310 seller net, SAR 600 fee and SAR 90 tax. A refund returns SAR 12,000 and SAR 48,000 to the respective origins. Evidence attachment remains a separate action; do not update financial inputs during a cash action.
-
-## Shared allocation and refunds
-
-An obligation's `allocation` declares its slice instrument, reference and eligible statuses, due date, position, earning-rule field and bucket sources. Principal and profit come from the slice. Cost and fine may come from separately assessed child records of that slice. Bucket array order is payment priority. Engines always walk slices by due date ascending, then declared position. There is no company-supplied sorting option. Multiple assessments of the same bucket use ascending stable assessment identity.
-
-A children bucket can select a concrete `instrumentId` or declare `template` and `parameters`. A template selector matches every instrument whose `templateBinding.id` equals that template and whose bound parameters include the requested scalar values. HSX retains string, integer and boolean arguments in `templateBinding.parameters` when it instantiates a template. Every matching alias must supply the declared slice reference, statuses, amount and destination fields. An uninstantiated selector contributes no assessments to a catalogue. The composed document validates the matching product instances.
-
-For `payoff` and `write_off`, omitting `allocate.refField` selects the executing instance. That instance must declare `allocation`. This does not introduce a caller-supplied self reference. Refund may also omit the reference and name its own earlier allocating action. Payment requires an explicit reference.
-
-An action's `allocate` references this declaration. Payment and payoff resolve amount, source account and payment identity from required immutable fields. Self payoff and assessment payment may instead use required action input keys. An operand must resolve to exactly one source. Self payoff may omit amountField so the planner computes the amount; a supplied amount must equal that figure. Assessment payment may omit amountField so the planner collects the assessment's whole remaining balance; a supplied amount above that balance refuses. The engine claims the identity under the obligation, reads remaining balances from prior allocation records and posts only positive allocations. It commits postings, consumption records, receipt and lifecycle state together. Recovery replays the recorded result. Direct collection and agency recovery must use the same declaration and assessment identities. A new channel or alias must not restore debt already consumed.
-
-A SAR 4,000 payment against an SAR 8,400 slice consumes principal only. A later SAR 4,400 consumes the remaining SAR 4,000 principal and SAR 400 profit. Cost and fine follow when the authored priority puts them after principal and profit. An overpayment refuses rather than disappearing into an unspecified balance.
-
-`allocate.mode: refund` names the original allocating action on self or through a typed instrument reference. An assessment record may omit `action` and reference its allocation owner instead: the engine reverses every consumption recorded against that assessment across the receipts that consumed it, its own collection, a repayment, a recovery or a payoff, each amount back to that receipt's payer, once. An optional immutable assessment identity selects one assessment's recorded allocation. The engine reverses those recorded postings to the original payer once. It does not accept new destinations or amounts and does not reopen consumed assessment debt. The refund identity is the original receipt plus assessment identity. A second refund refuses across aliases and lifecycle states.
-
-## Earning and noncash cancellation
-
-The immutable earning-rule field chooses one of two language-defined rules:
-
-- `per_slice_on_due`: profit earns when its slice becomes due or is paid, whichever comes first.
-- `on_disbursement`: all profit earns when the obligation advances.
-
-The engine proves the advance and supplies trusted paid/consumed facts to the planner. `payoff` collects outstanding principal, earned profit and assessed charges. It cancels unearned future profit without a cash refund. After one SAR 8,400 slice is paid, the six-slice example has SAR 40,000 principal and SAR 2,000 future profit remaining. Under `per_slice_on_due`, payoff collects SAR 40,000 and cancels SAR 2,000. Under `on_disbursement`, payoff collects SAR 42,000.
-
-`write_off` posts no money. Cancellation rows distinguish principal loss and earned charges from unearned-profit cancellation. No daily accrual rule exists: UDL does not yet define an authoritative day-count convention.
-
-`remainder.subtractPaths` is a bounded list of immutable money operands subtracted alongside existing collected sums from `totalPath`. Negative results refuse; zero follows `onZero`. It is not unrestricted arithmetic over money.
-
-## Referenced state and admission authority
-
-`transitionsRefs` invokes named noncash lifecycle actions on referenced instruments in the same transaction. The engine applies every target gate, authority check and lifecycle precondition. Cycles, repeated target actions and cash-bearing or input-dependent target actions refuse. A child can lapse its cover; a refund can cancel a referenced funding record and prevent future actions through that record's lifecycle gates. This does not replace durable approval consumption tied to a downstream operation.
-
-`cascade` executes a named lifecycle action on linked instances of another instrument inside the same transaction before evaluating the parent action's own admission gates. Target instances are identified either through caller input IDs via `inputField` or by matching a parent reference on target rows via `refField` filtered by lifecycle statuses. The cascading action cannot be create and cannot declare a decision. The target action must exist in lifecycle, cannot be create or engine-owned, cannot declare a decision, and cannot declare a cascade of its own. Because the cascade runs before the parent's admission gates, child status transitions take effect in time for parent aggregate requirements.
-
-`requiresRefs.unique` accepts `{namespace, byFields}`. The uniqueness key contains the Product, namespace, referenced instance identity and immutable key values. It excludes instrument aliases and current status. A waived or refunded fine still occupies its key; cost uses a different kind value. The engine enforces this key under a shared constraint or lock.
-
-Decision authentication, attestation verification and request hashing are admission concerns. The decision record must carry the requested instrument kind, instance, action, canonical input digest, deciding role and actor, expiry, verdict and evidence references. The engine computes the digest from the admitted request, authenticates the authority, checks expiry and revocation under locks, and binds consumption to the durable operation identity. Submitted actor and operation fields are not proof.
-
-## Effects and classification budget
-
-Canonical JSON preserves every clause and array order. Allocation and referenced transitions add explicit effects. Hosts must price `decides.allocation`, `moves.allocation` and `decides.referenced_transition` before compiling products that use them. Write-off has no movement effect. Contribution transfers use the existing internal-transfer effect signature.
-
-Reference classification reads the sealed ID pattern text; it never executes an authored regular expression or compiles a JSON Schema validator per candidate prefix. HSX supplies the published prefix when a typed reference omits its pattern. The 131,072 distinct-pair budget is a safety limit, not a catalogue-size target. The memo counts a schema/prefix pair once and fails closed after the limit.
-
-## Attested requests
-
-An action may declare one `requiresRefs` gate with `attests`. The gate must
-require a status and match `instrumentInstanceId` to a field on the referenced
-record. It cannot be optional. The block declares `action`, `digest`, `role`,
-`expiresAt` and `consume`. HSX accepts `expires_at` and emits `expiresAt`.
-Action and role paths name text fields, digest names a lowercase SHA-256 field
-with pattern `^[a-f0-9]{64}$`, and expiry names a date field.
-
-Admission compares the stored action to the admitted lifecycle action name.
-It computes the stored digest's expected value as
-`bindResolvedRequestHash(operationExecutionIdentity({ name, environment, body }))`
-for the downstream operation as admitted. The role must belong to the
-authenticated deciding principal. A caller-supplied actor or role is not proof.
-Admission refuses at or after expiry.
-
-Stored terms are absent from the request body. An attested action therefore
-puts its material terms in required input and declares `requiresInput`, a map
-from input key to stored `fields.*` path. Admission checks equality before
-updates or money movement. Changing a premium from 240000 to 180000 minor
-units changes the request digest and fails the stored-term equality law.
-
-The `consume` action must be reachable from every admitted status and declare
-`engineOwned: true`. It cannot be public, accept input or update caller fields.
-`captureEngine: { consumedByOperationId: "operationId" }` declares a ref written
-from the admitting operation identity. These keys cannot be fields, input,
-caller captures or move captures. The marker controls invocation authority;
-the capture map names engine facts and their destination keys.
-
-Consumption reuses referenced-transition effects and cycle checks. An ordinary
-`transitionsRefs` entry cannot invoke an engine-owned action. The engine must
-lock the decision and execute its transition inside the admitting transaction,
-so a refusal rolls back consumption and one approval cannot authorize two
-operations. This ABI declares those obligations; validation is not runtime
-proof of their enforcement.
-
-## Subject uniqueness
-
-An action's `unique: { namespace, byFields }` claims one key at creation without a reference gate. Keys contain one to eight distinct required immutable string, account or integer fields. Every use of a namespace must carry the same ordered field names and types. Reference-keyed and subject-keyed claims cannot share a namespace. The engine must claim the key tenant-wide, across instrument aliases, and never release it on closure. Raising a limit updates the existing record. The effect is `decides.subject_unique`, priced at zero without a price-version change.
-
-## Allocation exposure
-
-`requiresExposure.measure: { allocation: "principal" }` selects a bucket on the child instrument. Its gross operand is the parent money field named by an exact `requiresAggregate.check.kind: "schedule"` mapping to that bucket's slice amount field. The relation must use the allocation's slice instrument and reference. A bucket sourced from other children has no such mapping and cannot be measured by this clause.
-
-For qualifying children, the engine sums `amountField` and subtracts consumed amounts of the selected bucket over those same children. Payment, payoff and write-off share that consumption record. Refunds must be reflected by that record. The admitted instance contributes its full `amountField`. Omitting `measure` preserves the existing gross sum.
-
-## Recorded decider
-
-`attests.instrument` is a required text-field path on the referenced decision. Admission compares that stored value with the admitted instrument's id. Required `attests.party` names a declared party on the referenced decision. Admission compares the recorded deciding account with that party's bound account.
-
-A decision action declares `port.capture` as the name of an optional account field on its own instrument. The engine writes the admitted actor account there after checking `allowedParties`. Callers cannot populate it through `captureInput`, action input, step captures or updates. It cannot be required at creation. This records the tenant backend's assertion of the actor account; it does not independently authenticate that account.
-
-## Slice consumption and assessment collection
-
-`requiresAllocation: { refField, slice: "self", buckets, check }` reads the referenced obligation's shared consumption for the executing slice. `settled` requires every listed bucket to equal its gross amount. `outstanding` requires at least one bucket below gross. The reference is required and immutable, and the owner must allocate over this slice instrument or its template alias.
-
-Payment on an assessment may declare `assessment: "self"`. Admission matches the executing record to exactly one children bucket, then restricts payment to that record's remaining balance. An amount above that balance refuses. Refund without `action` reverses the assessment's consumption across every receipt that consumed it, once, and never reopens its consumed debt.
-
-An anchor exposure cap may be updatable only when its anchor update clause names the cap field and the exposure declares `measure`. Other exposure caps remain immutable.
-
-<!-- source: reference/canonical.md -->
-
-# Canonical bytes
-
-An admitted UDL document has one canonical byte sequence.
-
-- Encode JSON as UTF-8 without a byte-order mark.
-- Sort every object's keys by ascending UTF-16 code unit. Compare code units, not locale order or Unicode collation order.
-- Preserve array order exactly as authored. Never sort an array.
-- Indent nested values with two ASCII spaces. Write one ASCII space after each colon.
-- Write empty objects as `{}` and empty arrays as `[]`.
-- Serialize JSON numbers with JavaScript `JSON.stringify` semantics. An admitted integer uses base-10 digits with an optional leading minus and no leading zeros. Negative zero serializes as `0`. UDL money is not a JSON number. It is a base-10 integer minor-unit string paired with a currency code.
-- Apply ECMAScript well-formed `JSON.stringify` string escaping. Escape U+0000 through U+001F. Escape every lone surrogate as `\uXXXX`. Write every other code point literally, including U+007F and U+2028.
-- End the document with exactly one line feed byte, `0A`. Write no other trailing whitespace.
-
-`serializeUdl(document)` validates and writes these bytes. `canonicalizeUdl(input)` parses, validates, and writes them. Canonicalizing canonical bytes returns the same bytes.
-
-`canonicalDigest(document)` computes SHA-256 over the canonical UTF-8 bytes and returns a promise for the lowercase hexadecimal digest. `udl canon file.udl --digest` prints that digest. It does not hash the source bytes before canonicalization.
-
-<!-- source: reference/clauses.md -->
-
-# Clause reference
-
-This page lists every entry in `udlClauseVocabulary`. The examples are copied from admitted documents under `conformance/valid`.
-
-## funding
-
-- Scope: action
-- UDL target: `funding`
-- Cardinality: one
-- Linear outputs: none
-- Effects: moves.transfer.internal per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "capture": "snapshot",
-  "collectAction": "collect",
-  "destinationAccountField": "fundingAccount",
-  "obligationField": "obligationId",
-  "principalField": "principal",
-  "sourceAccountPath": "refs.escrow",
-  "terms": {
-    "currency": "currency",
-    "principal": "principal"
-  },
-  "ticketAccountField": "wallet",
-  "ticketAmountField": "amount",
-  "ticketInstrumentId": "ticket",
-  "ticketInvestorField": "investor",
-  "ticketRefField": "roundId",
-  "ticketStatus": "open"
-}
-```
-
-## receipt distribution
-
-- Scope: action
-- UDL target: `receiptDistribution`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.allocation per clause; moves.allocation per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "capture": "receipt",
-  "feeAccountField": "fee",
-  "feeBps": 100,
-  "mode": "cash",
-  "receiptField": "receiptId",
-  "receiptPath": "refs.allocationReceipt",
-  "residualAccountField": "residual",
-  "roundField": "roundId",
-  "snapshotRef": "snapshot",
-  "taxAccountField": "tax",
-  "vatBps": 1500
-}
-```
-
-## requires allocation
-
-- Scope: action
-- UDL target: `requiresAllocation`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.allocation per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "buckets": [
-    "principal",
-    "profit"
-  ],
-  "check": "settled",
-  "refField": "coverId",
-  "slice": "self"
-}
-```
-
-## allocation
-
-- Scope: instrument
-- UDL target: `allocation`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "buckets": [
-    {
-      "key": "principal",
-      "source": {
-        "amountField": "principal",
-        "destinationField": "receiver",
-        "from": "slice"
-      }
-    },
-    {
-      "key": "profit",
-      "source": {
-        "amountField": "profit",
-        "destinationField": "receiver",
-        "from": "slice"
-      }
-    },
-    {
-      "key": "cost",
-      "source": {
-        "amountField": "amount",
-        "destinationField": "receiver",
-        "from": "children",
-        "parameters": {
-          "cost": true
-        },
-        "refField": "sliceId",
-        "statuses": [
-          "open"
-        ],
-        "template": "assessment"
-      }
-    }
-  ],
-  "dueField": "dueAt",
-  "earningRuleField": "earningRule",
-  "positionField": "position",
-  "sliceInstrumentId": "slice",
-  "sliceRefField": "coverId",
-  "sliceStatuses": [
-    "open"
-  ]
-}
-```
-
-## contributions
-
-- Scope: instrument
-- UDL target: `contributions`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "accountKey": "origin",
-  "amountKey": "amount",
-  "field": "contributions",
-  "totalField": "price"
-}
-```
-
-## allocate
-
-- Scope: action
-- UDL target: `allocate`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.allocation per clause; moves.allocation per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "capture": "payoffReceipt",
-  "mode": "payoff",
-  "paymentIdentityField": "paymentIdentity",
-  "sourceAccountField": "payerAccount"
-}
-```
-
-## contribution stage
-
-- Scope: action
-- UDL target: `contributionStage`
-- Cardinality: one
-- Linear outputs: none
-- Effects: moves.transfer.internal per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "accountPath": "refs.hold",
-  "stage": "fund"
-}
-```
-
-## date order
-
-- Scope: instrument
-- UDL target: `dateOrder`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-[
-  {
-    "afterField": "end",
-    "beforeField": "start",
-    "operator": "<"
-  }
-]
-```
-
-## unique
-
-- Scope: action
-- UDL target: `unique`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.subject_unique per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "byFields": [
-    "borrower",
-    "currency"
-  ],
-  "namespace": "borrower_limit"
-}
-```
-
-## transitions refs
-
-- Scope: action
-- UDL target: `transitionsRefs`
-- Cardinality: many
-- Linear outputs: none
-- Effects: decides.referenced_transition per element
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-[
-  {
-    "action": "close",
-    "field": "coverId"
-  }
-]
-```
-
-## cascade
-
-- Scope: action
-- UDL target: `cascade`
-- Cardinality: many
-- Linear outputs: none
-- Effects: decides.cascade_transition per element
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-A cascade target action that declares a `port` is allowed only when the parent action declares a `port`: the engine forwards the port actor.
-
-```json
-[
-  {
-    "action": "close",
-    "inputField": "sliceIds",
-    "instrumentId": "slice"
-  }
-]
-```
-
-## action library
-
-- Scope: instrument
-- UDL target: `actionLibrary`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `piece-plan-calls.udl`
-
-```json
-{
-  "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"
-      }
-    }
-  }
-}
-```
-
-## agent description
-
-- Scope: action
-- UDL target: `agentDescription`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `agent-description.udl`
-
-```json
-"Close a note that has already been filed. Takes the note id and nothing else, and moves no money."
-```
-
-## calls
-
-- Scope: action
-- UDL target: `calls`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `piece-plan-calls.udl`
-
-```json
-[
-  {
-    "action": "transfers.execute_fund",
-    "bind": {
-      "inst": "$instance",
-      "p": "$piece"
-    },
-    "id": "call_fund"
-  }
-]
-```
-
-## requires input
-
-- Scope: action
-- UDL target: `requiresInput`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-{
-  "amount": "fields.amount"
-}
-```
-
-## engine owned
-
-- Scope: action
-- UDL target: `engineOwned`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-true
-```
-
-## capture engine
-
-- Scope: action
-- UDL target: `captureEngine`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-{
-  "consumedByOperationId": "operationId"
-}
-```
-
-## capture input
-
-- Scope: action
-- UDL target: `captureInput`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-{
-  "snapshotEvidenceReference": "evidenceReference"
-}
-```
-
-## commit
-
-- Scope: action
-- UDL target: `commit`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `commerce-escrow.udl`
-
-A commit has no separate effect row. The committing action consumes the quote through its `moves.*` row.
-
-```json
-"quote"
-```
-
-## quote
-
-- Scope: action
-- UDL target: `quote`
-- Cardinality: one
-- Linear outputs: `netRef`
-- Effects: holds.quote per clause; schedules.expiry per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `commerce-escrow.udl`
-
-```json
-{
-  "baseField": "amount",
-  "chargeRef": "unwindPenalty",
-  "charges": [
-    {
-      "bps": 0
-    }
-  ],
-  "expires": {
-    "offset": "PT15M"
-  },
-  "fixes": [
-    "amount",
-    "buyerAccountId"
-  ],
-  "netDestinationField": "buyerAccountId",
-  "netRef": "unwindRefund"
-}
-```
-
-## decided amount
-
-- Scope: action
-- UDL target: `decidedAmount`
-- Cardinality: one
-- Linear outputs: `field`
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-{
-  "boundField": "depositAmount",
-  "field": "damageAmount",
-  "remainderAction": "return_deposit"
-}
-```
-
-## deadline
-
-- Scope: action
-- UDL target: `deadline`
-- Cardinality: one
-- Linear outputs: none
-- Effects: schedules.deadline per clause
-- Law: Time law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-{
-  "field": "clawbackAt"
-}
-```
-
-## decision
-
-- Scope: action
-- UDL target: `decision`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.value from capability per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `cards.udl`
-
-```json
-{
-  "capability": "banking_or_card_issuing",
-  "deadlineMs": 1500,
-  "onTimeout": "decline"
-}
-```
-
-## computes distribute
-
-- Scope: action
-- UDL target: `distribute`
-- Cardinality: one
-- Linear outputs: `amountRef`
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-{
-  "amountRef": "payoutShare",
-  "onZero": "skip_steps",
-  "pool": {
-    "from": "parent",
-    "path": "fields.distributableAmount"
-  },
-  "refField": "repaymentDistributionId",
-  "statuses": [
-    "recorded",
-    "paid"
-  ],
-  "weightField": "committedWeight"
-}
-```
-
-## description
-
-- Scope: action
-- UDL target: `description`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `cards.udl`
-
-```json
-"Approves the customer to hold and use cards."
-```
-
-## due
-
-- Scope: action
-- UDL target: `due`
-- Cardinality: one
-- Linear outputs: none
-- Effects: schedules.due per clause
-- Law: Time law and closure law
-- Conformance source: `cards.udl`
-
-```json
-{
-  "field": "expiresAt"
-}
-```
-
-## earnable
-
-- Scope: action
-- UDL target: `earnable`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `cards.udl`
-
-```json
-true
-```
-
-## event name
-
-- Scope: action
-- UDL target: `eventName`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Event law and naming law
-- Conformance source: `cards.udl`
-
-```json
-"card.issued"
-```
-
-## examples
-
-- Scope: action
-- UDL target: `examples`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `cards.udl`
-
-```json
-[
-  {
-    "input": {
-      "cardholderId": "chd_sandbox_customer0001",
-      "tenantId": "ten_sandbox_cards000001"
-    },
-    "name": "activate_approved_cardholder"
-  }
-]
-```
-
-## input
-
-- Scope: action
-- UDL target: `input`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-{
-  "additionalProperties": false,
-  "properties": {
-    "amount": {
-      "pattern": "^[1-9][0-9]{0,17}$",
-      "type": "string",
-      "x-hyperscale-currency": "SAR"
-    }
-  },
-  "required": [
-    "amount"
-  ],
-  "type": "object"
-}
-```
-
-## moves
-
-- Scope: action
-- UDL target: `moves`
-- Cardinality: many
-- Linear outputs: none
-- Effects: moves.movement class per element; holds.reserve per element
-- Law: One-spine law and closure law
-- Conformance source: `agent-description.udl`
-
-```json
-[]
-```
-
-## payout
-
-- Scope: action
-- UDL target: `payout`
-- Cardinality: one
-- Linear outputs: none
-- Effects: moves.payout.external per clause
-- Law: One-spine law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-{
-  "amount": "refs.netPayable",
-  "beneficiaryField": "payoutBeneficiaryId",
-  "beneficiaryPartyField": "payoutDestinationAccountId",
-  "capture": "payoutId",
-  "currencyField": "currency",
-  "sourceAccountField": "clubAccountId",
-  "speed": "standard"
-}
-```
-
-## piece plan
-
-- Scope: instrument
-- UDL target: `piecePlan`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `piece-plan-calls.udl`
-
-```json
-{
-  "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"
-  ]
-}
-```
-
-## piece stage
-
-- Scope: action
-- UDL target: `pieceStage`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `piece-plan-calls.udl`
-
-```json
-{
-  "plan": "split_plan",
-  "stage": "fund"
-}
-```
-
-## port
-
-- Scope: action
-- UDL target: `port`
-- Cardinality: one
-- Linear outputs: none
-- Effects: decides.tenant_port per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-{
-  "allowedParties": [
-    "decider"
-  ],
-  "capture": "decidedBy"
-}
-```
-
-## principal
-
-- Scope: action
-- UDL target: `principal`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `complete-contract.udl`
-
-```json
-"user_session"
-```
-
-## public action
-
-- Scope: action
-- UDL target: `publicAction`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Event law and naming law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-"abandonLenderCommitment"
-```
-
-## reconcile
-
-- Scope: action
-- UDL target: `reconcile`
-- Cardinality: many
-- Linear outputs: none
-- Effects: reads.reconcile per element
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-`exception.amountField` must name a required money field on the exception child. `exception.reasonField` must name a required text field on that child. UDL evolution supplies no default for either name.
-
-```json
-[
-  {
-    "amount": "refs.netPayable",
-    "capture": "settlementEvidenceId",
-    "counterpartyRef": "payoutId",
-    "currencyField": "currency",
-    "direction": "debit",
-    "evidence": "statement_line",
-    "exception": {
-      "amountField": "amount",
-      "childInstrumentId": "seller_payout_debit_adjustment",
-      "maxOpen": 1,
-      "reasonField": "adjustmentReference",
-      "refField": "sellerPayoutId"
-    },
-    "match": {
-      "law": "exact"
-    },
-    "within": {
-      "offset": "P30D"
-    }
-  }
-]
-```
-
-## computes remainder
-
-- Scope: action
-- UDL target: `remainder`
-- Cardinality: one
-- Linear outputs: `amountRef`
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `complete-contract.udl`
-
-```json
-{
-  "amountRef": "remainingAmount",
-  "onZero": "refuse",
-  "totalPath": "fields.amount"
-}
-```
-
-## requires aggregate
-
-- Scope: action
-- UDL target: `requiresAggregate`
-- Cardinality: many
-- Linear outputs: none
-- Effects: reads.requires_aggregate per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-[
-  {
-    "check": {
-      "amountField": "amount",
-      "kind": "sum_exactly",
-      "targetField": "installment1Amount"
-    },
-    "instrumentId": "borrower_loan_installment_1_payment",
-    "over": "children",
-    "refField": "borrowerLoanId",
-    "statuses": [
-      "paid"
-    ]
-  }
-]
-```
-
-## requires checks
-
-- Scope: action
-- UDL target: `requiresChecks`
-- Cardinality: many
-- Linear outputs: none
-- Effects: reads.requires_checks per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `complete-contract.udl`
-
-```json
-[
-  {
-    "checkKind": "identity_verification",
-    "family": "national_identity",
-    "maxAge": "P30D",
-    "statuses": [
-      "completed"
-    ],
-    "subjectField": "subjectId"
-  }
-]
-```
-
-## requires drained
-
-- Scope: action
-- UDL target: `requiresDrainedAccount`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `commerce-escrow.udl`
-
-```json
-{
-  "path": "refs.escrowAccountId"
-}
-```
-
-## requires exposure
-
-- Scope: action
-- UDL target: `requiresExposure`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-[
-  {
-    "amountField": "amount",
-    "anchorField": "borrowerLoanId",
-    "capField": "installment1Amount",
-    "capOnAnchor": true,
-    "childInstrumentId": "borrower_loan_installment_1_payment",
-    "statuses": [
-      "paid"
-    ]
-  }
-]
-```
-
-## requires refs
-
-- Scope: action
-- UDL target: `requiresRefs`
-- Cardinality: many
-- Linear outputs: none
-- Effects: reads.requires_refs per clause
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-[
-  {
-    "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"
-    ]
-  }
-]
-```
-
-## sandbox failure point
-
-- Scope: action
-- UDL target: `sandboxFailurePoint`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `commerce-escrow.udl`
-
-```json
-"funding"
-```
-
-## sets at
-
-- Scope: action
-- UDL target: `setsAt`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Time law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-{
-  "field": "installment1DelinquentAfter",
-  "marker": true,
-  "offset": "PT1S"
-}
-```
-
-## computes signed_sum
-
-- Scope: action
-- UDL target: `signedSum`
-- Cardinality: one
-- Linear outputs: `amountRef`
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-{
-  "amountRef": "netPayable",
-  "onNegative": "refuse",
-  "onZero": "refuse",
-  "sources": [
-    {
-      "amountField": "amount",
-      "instrumentId": "seller_payout_capture_entry",
-      "refField": "sellerPayoutId",
-      "sign": "add",
-      "statuses": [
-        "accrued"
-      ],
-      "subtotalRef": "grossCaptureAmount"
-    },
-    {
-      "amountField": "amount",
-      "instrumentId": "seller_payout_credit_adjustment",
-      "refField": "sellerPayoutId",
-      "sign": "add",
-      "statuses": [
-        "applied"
-      ],
-      "subtotalRef": "creditAdjustmentAmount"
-    },
-    {
-      "amountField": "amount",
-      "instrumentId": "seller_payout_debit_adjustment",
-      "refField": "sellerPayoutId",
-      "sign": "subtract",
-      "statuses": [
-        "applied"
-      ],
-      "subtotalRef": "debitAdjustmentAmount"
-    }
-  ]
-}
-```
-
-## steps
-
-- Scope: action
-- UDL target: `steps`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: One-spine law and closure law
-- Conformance source: `agent-description.udl`
-
-```json
-[]
-```
-
-## summary
-
-- Scope: action
-- UDL target: `summary`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `agent-description.udl`
-
-```json
-"Close the note."
-```
-
-## updates
-
-- Scope: action
-- UDL target: `updates`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `commerce-escrow.udl`
-
-```json
-[
-  "escrowOrderId"
-]
-```
-
-## notify
-
-- Scope: action
-- UDL target: `effects.notifies`
-- Cardinality: many
-- Linear outputs: none
-- Effects: notifies.value from channel per element
-- Law: Requirements-as-data law and closure law
-- Conformance source: `effect-signatures.udl`
-
-```json
-[
-  {
-    "channel": "email",
-    "role": "beneficiary",
-    "signature": "notifies.email",
-    "source": "effects.notifies[0]"
-  }
-]
-```
-
-## agent description
-
-- Scope: instrument
-- UDL target: `agentDescription`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `agent-description.udl`
-
-```json
-"Close a note that has already been filed. Takes the note id and nothing else, and moves no money."
-```
-
-## aggregate invariants
-
-- Scope: instrument
-- UDL target: `aggregateInvariants`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-[
-  {
-    "childField": "amount",
-    "childInstrumentId": "borrower_loan_installment_1_payment",
-    "childRefField": "borrowerLoanId",
-    "childStatuses": [
-      "paid"
-    ],
-    "parentField": "installment1Amount"
-  },
-  {
-    "childField": "amount",
-    "childInstrumentId": "borrower_loan_installment_2_payment",
-    "childRefField": "borrowerLoanId",
-    "childStatuses": [
-      "paid"
-    ],
-    "parentField": "installment2Amount"
-  }
-]
-```
-
-## caller parked states
-
-- Scope: instrument
-- UDL target: `callerParkedStates`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Time law and closure law
-- Conformance source: `cards.udl`
-
-```json
-{
-  "active": "a cardholder in good standing stays active until the issuer or holder acts",
-  "pending": "activation follows the issuer's verification outcome",
-  "suspended": "reinstatement or closure is an issuer decision"
-}
-```
-
-## description
-
-- Scope: instrument
-- UDL target: `description`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `cards.udl`
-
-```json
-"Approves the customer to hold and use cards."
-```
-
-## dials
-
-- Scope: instrument
-- UDL target: `dials`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `cards.udl`
-
-```json
-[
-  {
-    "field": "expiresAt",
-    "key": "authorization_window",
-    "kind": "window",
-    "maxOffset": "P30D",
-    "summary": "Grace beyond the authorization expiry timestamp before an uncaptured hold expires.",
-    "title": "Authorization window"
-  },
-  {
-    "action": "approve",
-    "key": "policy_decision_deadline_ms",
-    "kind": "decision_deadline_ms",
-    "maxMs": 5000,
-    "minMs": 500,
-    "summary": "How long approve waits for the card policy's just-in-time decision before the timeout default declines.",
-    "title": "Policy decision deadline"
-  }
-]
-```
-
-## distinct parties
-
-- Scope: instrument
-- UDL target: `distinctParties`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-true
-```
-
-## computes derived
-
-- Scope: instrument
-- UDL target: `derivedAmounts`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: One-spine law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-[
-  {
-    "field": "platformFee",
-    "rounding": "floor",
-    "rule": {
-      "bps": 200,
-      "kind": "percentage_of"
-    },
-    "sourceField": "principalAmount"
-  }
-]
-```
-
-## computes fees
-
-- Scope: instrument
-- UDL target: `feeRules`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: One-spine law and closure law
-- Conformance source: `compiled-watch-club.udl`
-
-```json
-[
-  {
-    "amountField": "checkoutFee",
-    "baseField": "purchasePrice",
-    "bearerField": "memberAccountId",
-    "position": "on_top",
-    "rule": {
-      "currencyField": "currency",
-      "field": "checkoutFee",
-      "kind": "exact"
-    }
-  },
-  {
-    "amountField": "carvedFeeAmount",
-    "baseField": "purchasePrice",
-    "bearerField": "sellerAccountId",
-    "position": "carved",
-    "rule": {
-      "kind": "tiered",
-      "tiers": [
-        {
-          "fromInclusive": "0",
-          "rule": {
-            "bps": 100,
-            "kind": "bps"
-          },
-          "toExclusive": "10000"
-        },
-        {
-          "fromInclusive": "10000",
-          "rule": {
-            "currencyField": "currency",
-            "field": "highValueFee",
-            "kind": "exact"
-          }
-        }
-      ]
-    }
-  }
-]
-```
-
-## id prefix
-
-- Scope: instrument
-- UDL target: `idPrefix`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `agent-description.udl`
-
-```json
-"note"
-```
-
-## nav
-
-- Scope: instrument
-- UDL target: `nav`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `cards.udl`
-
-```json
-[
-  "Blueprints",
-  "Cardholders"
-]
-```
-
-## partitions
-
-- Scope: instrument
-- UDL target: `partitions`
-- Cardinality: many
-- Linear outputs: none
-- Effects: none
-- Law: One-spine law and closure law
-- Conformance source: `compiled-crowdfunding.udl`
-
-```json
-[
-  {
-    "pieceFields": [
-      "installment1Amount",
-      "installment2Amount"
-    ],
-    "totalField": "principalAmount"
-  }
-]
-```
-
-## subject
-
-- Scope: instrument
-- UDL target: `subject`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Closure law
-- Conformance source: `commerce-escrow.udl`
-
-```json
-{
-  "kinds": [
-    "vehicle",
-    "merchandise"
-  ]
-}
-```
-
-## summary
-
-- Scope: instrument
-- UDL target: `summary`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `agent-description.udl`
-
-```json
-"Close the note."
-```
-
-## surface visibility
-
-- Scope: instrument
-- UDL target: `surfaceVisibility`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `complete-contract.udl`
-
-```json
-"public"
-```
-
-## template binding
-
-- Scope: instrument
-- UDL target: `templateBinding`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `vocabulary.udl`
-
-```json
-{
-  "id": "assessment",
-  "parameters": {
-    "cost": true
-  }
-}
-```
-
-## template id
-
-- Scope: instrument
-- UDL target: `templateId`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `cards.udl`
-
-```json
-"wallet_cards"
-```
-
-## title
-
-- Scope: instrument
-- UDL target: `title`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: One-sentence law, uniform object law, and naming law
-- Conformance source: `agent-description.udl`
-
-```json
-"Note"
-```
-
-## update
-
-- Scope: instrument
-- UDL target: `update`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Closure law
-- Conformance source: `cards.udl`
-
-```json
-{
-  "examples": [
-    {
-      "input": {
-        "cardholderId": "chd_sandbox_customer0001",
-        "displayName": "Noura Al Saud",
-        "email": "noura@example.test",
-        "tenantId": "ten_sandbox_cards000001"
-      },
-      "name": "update_cardholder_contact"
-    }
-  ],
-  "fields": [
-    "displayName",
-    "email",
-    "phoneNumber"
-  ],
-  "states": [
-    "pending",
-    "active",
-    "suspended"
-  ]
-}
-```
-
-## request authority
-
-- Scope: action
-- UDL target: `requestAuthority`
-- Cardinality: one
-- Linear outputs: none
-- Effects: none
-- Law: Requirements-as-data law and closure law
-- Conformance source: `attested.udl`
-
-```json
-{
-  "actionField": "actionName",
-  "digestField": "digest",
-  "expiresField": "expiry",
-  "inputField": "requestInput",
-  "instanceField": "requestId",
-  "instrumentField": "requestInstrument",
-  "party": "decider",
-  "roleField": "role"
-}
-```
-
-<!-- source: reference/diagnostics.md -->
-
-# Diagnostic reference
-
-Codes are stable. Titles and messages may become clearer without changing the code. Apply the listed fix, then validate the whole document again.
-
-| Code      | Family    | Category          | Title                                                   | Fix                                                                                                                |
-| --------- | --------- | ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `UDL1001` | admission | invalid_utf8      | Invalid UTF-8                                           | Encode the document as valid UTF-8.                                                                                |
-| `UDL1002` | admission | invalid_json      | Invalid JSON                                            | Repair the JSON syntax before validation.                                                                          |
-| `UDL1003` | admission | invalid_shape     | Invalid document shape                                  | Match the published UDL JSON Schema.                                                                               |
-| `UDL1004` | admission | resource_limit    | Resource limit exceeded                                 | Reduce the source size, nesting, values, strings, references, or financial paths named by the message.             |
-| `UDL2001` | document  | invalid_semantics | Duplicate declaration                                   | Give each declaration a unique name.                                                                               |
-| `UDL2002` | document  | invalid_semantics | Document law violation                                  | Repair the declaration, subject contract, or derived effects named by the message.                                 |
-| `UDL2005` | document  | invalid_semantics | Derived effects mismatch                                | Regenerate the action effects from its clauses.                                                                    |
-| `UDL2010` | document  | invalid_semantics | Action graph violation                                  | Order all actions and calls without cycles or collisions, within depth and count limits.                           |
-| `UDL2011` | document  | invalid_semantics | Action binding violation                                | Bind parameters to declared instance, piece, or caller variables without forward references or duplicate captures. |
-| `UDL2012` | document  | invalid_semantics | Action authority violation                              | Match principal, approval, and recovery policies and keep field paths within tenant boundary.                      |
-| `UDL2013` | document  | invalid_semantics | Action effect or evidence violation                     | Provide valid effect kind, matching effect signature, and non-empty evidence for every leaf.                       |
-| `UDL3001` | lifecycle | invalid_semantics | Lifecycle is not closed                                 | Declare every state and action transition, and make every state reachable.                                         |
-| `UDL4001` | finance   | invalid_semantics | Money graph violation                                   | Balance every funded amount and close every hold on each lifecycle path.                                           |
-| `UDL4002` | finance   | invalid_semantics | Piece partition violation                               | Match piece plan total, amounts, and payees to required immutable fields and declared partition.                   |
-| `UDL5001` | gates     | invalid_semantics | Reference gate violation                                | Point the gate at a declared instrument, action, state, field, and reference.                                      |
-| `UDL5002` | gates     | invalid_semantics | Check requirement violation                             | Use a declared check with compatible evidence and recurrence.                                                      |
-| `UDL5003` | gates     | invalid_semantics | Exposure gate violation                                 | Use declared account and money fields for the exposure gate.                                                       |
-| `UDL5004` | gates     | invalid_semantics | Aggregate law violation                                 | Point the aggregate at compatible parent and child fields.                                                         |
-| `UDL5005` | gates     | invalid_semantics | Settlement or payout violation                          | Use a declared settlement account and a compatible payout statement line.                                          |
-| `UDL5006` | gates     | invalid_semantics | Quote and commit violation                              | Declare one complete quote freeze set and one matching commit action.                                              |
-| `UDL5007` | gates     | invalid_semantics | Reconcile exception child violation                     | Name a declared child whose reference points back to this instrument.                                              |
-| `UDL5008` | gates     | invalid_semantics | Action clause violation                                 | Repair the clause fields and keep incompatible clauses separate.                                                   |
-| `UDL5009` | gates     | invalid_semantics | Reconcile exception amount field is missing or optional | Name the exception child's required money field in amountField.                                                    |
-| `UDL5010` | gates     | invalid_semantics | Reconcile exception amount field has the wrong type     | Point amountField at a money field declared by the exception child.                                                |
-| `UDL5011` | gates     | invalid_semantics | Reconcile exception reason field is missing or optional | Name the exception child's required text field in reasonField.                                                     |
-| `UDL5012` | gates     | invalid_semantics | Reconcile exception reason field has the wrong type     | Point reasonField at a required plain text field declared by the exception child.                                  |
-| `UDL5013` | gates     | invalid_semantics | Piece stage violation                                   | Reference a declared piece plan and stage in the containing instrument.                                            |
-| `UDL6001` | schema    | invalid_semantics | Unsupported JSON Schema                                 | Use only the sealed UDL JSON Schema subset.                                                                        |
-| `UDL7001` | evolution | invalid_evolution | Stored contract changed                                 | Keep stored identities and contracts unchanged, and add only allowed optional declarations.                        |
-| `UDL7002` | evolution | invalid_evolution | Version was not increased                               | Increase the product version for every semantic change.                                                            |
-
-<!-- source: reference/cli.md -->
-
-# Command reference
-
-In the full repository checkout, run `bun open/udl/src/cli.ts validate <file.udl.json>` from the repository root. The entrypoint is `open/udl/src/cli.ts`; in a standalone package checkout it is `src/cli.ts`. Use this local validator for local HSX output.
-
-The installed `udl` binary exposes the following commands and exit codes.
-
-```text
-udl - the Universal Domain Language toolchain
-
-usage:
-  udl validate <file>          parse <file> and report every issue found
-  udl fmt <file> [--write]     print the canonical form, or rewrite the file
-  udl canon <file> [--digest]  print canonical bytes, or their SHA-256 digest
-  udl diff <live> <next>       check <next> against the append-only law
-  udl explain UDL####          explain one stable diagnostic code
-  udl help                     print this
-
-exit codes:
-  0  the document is admissible, or the change is additive
-  1  the document was refused, or the change breaks the append-only law
-  2  the command line was wrong, or a file could not be read
-```