@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/docs/llms-full.txt

@@ -0,0 +1,1241 @@
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0. 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)
+
+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. Do not edit those generated files by hand.
+
+<!-- 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 `UDL####` 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.
+
+<!-- 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 `UDL####` 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: 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`.
+
+## 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."
+```
+
+## 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: `cards.udl`
+
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "maxLength": 180,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": ["reason"],
+  "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"
+}
+```
+
+## 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: `compiled-crowdfunding.udl`
+
+```json
+{
+  "allowedParties": ["beneficiary"]
+}
+```
+
+## 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: `cards.udl`
+
+```json
+[
+  {
+    "field": "cardholderId",
+    "statuses": ["active"]
+  }
+]
+```
+
+## 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 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"]
+}
+```
+
+<!-- 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.                                                        |
+| `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.                               |
+| `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.                      |
+| `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
+
+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
+```