@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/docs/llms-full.txt

@@ -0,0 +1,1739 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+
+# HSX full documentation
+
+# Your first program
+
+An HSX file declares one program, the parties that take part, and the instruments that define its money rules. A settlement applies a standard-library instrument. The compiler checks the application and emits canonical UDL with an origin map and a cost manifest.
+
+This program sends a tip from a listener to a host:
+
+```hsx
+program tip_jar "Tip jar"
+import { instant_transfer } from "std/settlements"
+party listener: person
+party host: business
+settlement tip = instant_transfer {
+  payer: listener
+  payee: host
+  amount: tipAmount: money(SAR)
+  fees { listener: 1% }
+}
+```
+
+`tipAmount` is an input field measured in SAR minor units. The settlement becomes an instrument named `tip` in the UDL document.
+
+A port declares a decision that an external caller may supply. The port names the parties allowed to answer and may define a typed input shape. Use a port only when the selected instrument accepts a condition parameter.
+
+After package installation, run `npx hsx check product.hsx` while editing and `npx hsx build product.hsx --out product.udl.json` when the program passes. In a repository checkout, run `bun install` once, then use `bun run bin/hsx.ts check product.hsx` and `bun run bin/hsx.ts build product.hsx --out product.udl.json`.
+
+# Money
+
+HSX indexes money by currency. `money<SAR>` is the field type inside a general instrument. `amount: total: money(SAR)` binds a settlement parameter to a new SAR money field. Values use integer minor units, so `1250` means SAR 12.50.
+
+Money of different currencies never unifies. Percent literals use basis-point precision: `2%` is 200 basis points and `2.5%` is 250 basis points. The compiler floors percentage-derived minor units and assigns any declared remainder according to the selected instrument.
+
+Money is linear. A computed amount must be consumed exactly once. This invalid general-form program uses `rest` twice, so the compiler reports `HSX1201`:
+
+```hsx expect=HSX1201
+program duplicated_money "Duplicated money"
+party buyer: person
+instrument invoice {
+  fields { amount: money<SAR>; }
+  lifecycle { states created paid; initial created; on pay: created -> paid; }
+  parties { payer: buyer; }
+  action create { steps: []; }
+  action pay {
+    computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }
+    moves: [{ amount: rest; }, { amount: rest; }]
+    steps: []
+  }
+}
+```
+
+Do not use free arithmetic to repair a linearity refusal. Choose a standard-library split, fee, or derived-amount form that states where every minor unit goes.
+
+# Instruments
+
+Start with the standard library. Import a settlement module by export name from `std/settlements`, then apply it under a local settlement name. The local name becomes the emitted instrument id.
+
+```hsx
+program equipment_hire "Equipment hire"
+import { scheduled } from "std/settlements"
+party renter: person
+party owner: business
+settlement installments = scheduled {
+  payer: renter
+  payee: owner
+  amount: hirePrice: money(SAR)
+  count: 2
+  every: P30D
+  first_due: firstPaymentAt
+}
+```
+
+Required parameters state the instrument's core contract. Optional parameters add bounded behavior such as a deadline, cancellation allocation, fee, or policy. Omit an optional block when the product does not need it. Do not pass an empty block as a substitute unless the module documents that form.
+
+The generated standard-library reference lists every module, parameter, action, port, and emitted clause. Read that page before choosing a module. Prefer one module that already states the required lifecycle over a custom instrument with copied mechanics.
+
+# Lifecycles
+
+A lifecycle lists every state, names one initial state, and declares action transitions. Every reachable nonterminal state must have a bounded exit or be explicitly parked for a caller action. Actions hold the money moves and other typed clauses that occur on a transition.
+
+```hsx
+program approvals "Approvals"
+instrument approval {
+  title: "Approval"
+  summary: "A bounded approval decision"
+  fields {}
+  lifecycle {
+    states pending approved rejected;
+    initial pending;
+    on approve: pending -> approved;
+    on reject: pending -> rejected;
+  }
+  action create { steps: []; moves: []; }
+  action approve { steps: []; moves: []; }
+  action reject { steps: []; moves: []; }
+}
+```
+
+Standard-library instruments bind ports to caller decisions. A deadline appears as stored date data and a `due` clause on the action that may run at that date. An unwind states how a failed or cancelled path drains held value. The compiler refuses a reachable exit that strands money.
+
+Keep lifecycle changes additive after composition. Add a new action or state when old instances can still obey the previous contract. Do not rename a state or tighten an active transition in place.
+
+# Fees and splits
+
+Standard-library payment modules accept bounded fee forms. A payer fee sits on top of the principal. A payee fee is carved from the payout. A fee may be an exact percentage, an immutable money field, or a finite tier table when the module accepts it.
+
+```hsx
+program lesson_market "Lesson market"
+import { instant_transfer, pooled_split } from "std/settlements"
+party student: person
+party tutor: business
+party assistant: business
+party school: business
+settlement lesson = instant_transfer {
+  payer: student
+  payee: tutor
+  amount: lessonFee: money(SAR)
+  fees { student: 1%, tutor: 8% }
+}
+settlement payout = pooled_split {
+  payer: school
+  amount: weeklyPool: money(SAR)
+  payout_due: payoutAt
+  split { tutor: 60%, assistant: 40%, remainder_to: tutor }
+}
+```
+
+Every percentage partition must total 100 percent. `pooled_split` distributes a pool among named recipients and sends integer-division residue to `remainder_to`. `security_deposit` can bind a decided claim amount and return the unused remainder. `weighted_distribution` records bounded entitlement rows before it snapshots a distribution.
+
+`cancellable_booking` uses `quote` and `commit` when a fee must be shown before it can move money. Its `cancel` action prices a penalty from the time left before `starts_at`, freezes the price and the fields named by `fixes`, and gives the offer a bounded life. Its `confirm` action commits that exact quote. Expiry or a changed frozen field refuses the commit instead of repricing it silently.
+
+```hsx
+program studio_booking "Studio booking"
+import { cancellable_booking } from "std/settlements"
+party guest: person
+party studio: business
+settlement session = cancellable_booking {
+  guest: guest
+  host: studio
+  amount: sessionPrice: money(SAR)
+  starts_at: startsAt
+  late_penalty_bps: 5000
+  late_within: P2D
+  early_penalty_bps: 1000
+  offer_life: PT30M
+}
+```
+
+# Schedules
+
+HSX schedules are finite. A literal `count`, an interval, and a first due date let the compiler expand installments at compile time. The monthly obligation form can instead use a caller-controlled end condition, but it must name the drain action that ends future liability.
+
+```hsx
+program installments "Installments"
+import { scheduled } from "std/settlements"
+party buyer: person
+party seller: business
+settlement plan = scheduled {
+  payer: buyer
+  payee: seller
+  amount: totalAmount: money(SAR)
+  count: 3
+  every: P30D
+  first_due: firstDueAt
+}
+```
+
+`scheduled` handles finite installments and obligation schedules. `recurring_collection` records collection periods without inventing money movement. `rotating_pool` expands a fixed roster and cycle count. `settlement_batch` closes on a stored date before calculation, approval, instruction, acknowledgement, and reconciliation actions.
+
+General modules may use a comprehension over a compile-time integer or finite list. Runtime-dependent bounds are refused. An expansion may contain at most 256 generated rows.
+
+# Composition
+
+One program can apply several instruments. Each instrument keeps its own lifecycle and fields. References connect them through typed ids instead of shared mutable state.
+
+```hsx
+program studio_sales "Studio sales"
+import { instant_transfer, scheduled } from "std/settlements"
+party buyer: person
+party studio: business
+settlement purchase = instant_transfer {
+  payer: buyer
+  payee: studio
+  amount: purchasePrice: money(SAR)
+  fees { buyer: 1% }
+}
+settlement installments = scheduled {
+  payer: buyer
+  payee: studio
+  amount: servicePrice: money(SAR)
+  count: 2
+  every: P30D
+  first_due: firstPaymentAt
+}
+```
+
+A general instrument declares a `ref<target>` field when an instance must point to another instrument. Cross-instrument clauses bind against the target's declared fields, actions, and lifecycle states after the full module graph resolves. A missing target or incompatible field reports a typed diagnostic before UDL emission.
+
+Keep each money route in one instrument. Connect instruments with evidence and references. Do not move an amount through an untyped text field.
+
+`reconciled_payout` composes a payout instruction with one explicit expectation about the bank debit that follows. Its `reconcile` clause binds the expected amount, currency, direction, payout reference, evidence source, match law, and deadline. A match settles the payout. A missed or mismatched expectation creates the declared break child, so the composition retains the exception as contract data.
+
+```hsx
+program supplier_payment "Supplier payment"
+import { reconciled_payout } from "std/settlements"
+party treasury: business
+party supplier: business
+settlement payout = reconciled_payout {
+  payer: treasury
+  beneficiary: supplier
+  amount: netPayable: money(SAR)
+  beneficiary_ref: supplierBeneficiaryId
+  settle_by: settleBy
+  matched_within: 100
+  matched_ceiling: 500
+}
+```
+
+# Writing a module
+
+A module is ordinary HSX source. It declares a dotted module name and exports templates, types, constants, subjects, or applications. The compiler does not branch on a standard-library module name.
+
+```hsx
+program approval_example "Approval example"
+instrument approval() {
+  title: "Approval"
+  summary: "A reusable approval lifecycle"
+  fields {}
+  lifecycle {
+    states pending approved;
+    initial pending;
+    on approve: pending -> approved;
+  }
+  action create { steps: []; moves: []; }
+  action approve { steps: []; moves: []; }
+}
+instrument review = approval()
+```
+
+A parameter list makes an instrument a template, including an empty list. A concrete instrument without a parameter list emits directly when its file compiles. Export only the declarations that callers need.
+
+Imported exports carry the local declarations they reference. Identical declarations unify. Conflicting declarations report `HSX1009`. Keep module parameters typed, keep loops finite, and use UDL clause vocabulary for instrument and action mechanics.
+
+Publish a module only after compiling it directly and through an importing program. Compare the canonical UDL bytes from both paths when the exported application should be identical.
+
+# Cost
+
+Compilation emits a deterministic cost manifest beside the UDL document. The manifest pins the cost-table version and effective digest. It records fixed structural cost, action effect rows, payer, settlement policy, meters, per-event prices, and any basis-point volume price.
+
+```hsx
+program direct_sale "Direct sale"
+import { instant_transfer } from "std/settlements"
+party buyer: person
+party seller: business
+settlement sale = instant_transfer {
+  payer: buyer
+  payee: seller
+  amount: saleAmount: money(SAR)
+  fees { buyer: 1% }
+}
+```
+
+Read an action line as `instrument.action`, followed by the effect signature and its count. The payer tells whether the product or end customer bears the row. `perEventMinor` prices one occurrence in the cost table's billing currency. A row with `bps` also names a volume meter.
+
+The monthly estimate is an expression over declared meter variables. Billing supplies observed readings to that frozen expression. Recomposition emits a new manifest for the next commercial snapshot. It does not rewrite a prior manifest.
+
+An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. Use the single rate card shipped at `examples/cost-table.json`; do not create a second table for documentation.
+
+Do not confuse an action `quote` with the commercial cost manifest. `cancellable_booking.cancel` quotes a customer-visible cancellation penalty and `confirm` commits it. The compiler counts an instrument that carries a quote as unwind work because an expired or abandoned offer still needs bounded cleanup. The cost manifest prices that runtime work from the shipped rate card. It does not replace, spend, or alter the quoted financial amount.
+
+# Diagnostics
+
+An HSX diagnostic carries a stable code, severity, stage, source line and column, message, and fix. Match automation on the code. Treat the message as explanation rather than a stable interface.
+
+The stages locate the refusal:
+
+- `parse` means the source did not form valid declarations or expressions.
+- `bind` means an import, name, port, or reference did not resolve.
+- `typecheck` and `check` mean the program formed but violated a type or language law.
+- `lower` means the typed program could not emit valid UDL.
+
+Use one loop: compile, find the first error code in the diagnostics reference, apply its stated fix, and compile again. Do not suppress the diagnostic or alter generated UDL by hand.
+
+```hsx
+program repaired_transfer "Repaired transfer"
+import { instant_transfer } from "std/settlements"
+party sender: person
+party recipient: business
+settlement transfer = instant_transfer {
+  payer: sender
+  payee: recipient
+  amount: transferAmount: money(SAR)
+  fees { sender: 1% }
+}
+```
+
+Exit code `0` means the command accepted the program. Exit code `1` means compilation refused it. Exit code `2` means the invocation or file operation failed. `hsx explain HSX1201` prints the catalog entry for one code.
+
+# CLI
+
+```text
+hsx 1.0.0, the HSX compiler
+
+Usage:
+  hsx check <file.hsx> [--strict]
+  hsx build <file.hsx> [--out <file.json>] [--strict]
+  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  hsx explain <HSX####>
+  hsx format <file.hsx>
+  hsx lsp
+  hsx --version
+  hsx --help
+
+Commands:
+  check   Compile and report diagnostics. Prints nothing when the program is clean.
+  build   Compile and write canonical UDL as JSON.
+  cost    Compile and print the version-pinned cost manifest as a table or JSON.
+  explain Print one diagnostic title, fix, and source example.
+  format  Print the source in the one canonical HSX style.
+  lsp     Run the language server over stdin and stdout.
+
+Options:
+  --json        Print the cost manifest as JSON instead of a table.
+  --out <file>  Write build or cost JSON to this path instead of stdout.
+  --strict      Treat warning-severity diagnostics as failures.
+
+Exit codes:
+  0  the program compiled (verdict valid, or warning without --strict)
+  1  the program was refused (verdict invalid, or warning with --strict)
+  2  the command line or the input file could not be used
+```
+
+# Diagnostics
+
+Use `hsx explain HSX####` for the same catalog entry.
+
+## HSX1000: Missing file declaration
+
+Stage: `typecheck`
+
+Fix: Add one program header or module declaration.
+
+No source-only witness exists. The compiler host or lowering input must supply the invalid value.
+
+## HSX1001: Unbound name
+
+Stage: `bind`
+
+Fix: Declare or import the name before using it.
+
+```hsx expect=HSX1001
+program catalog_probe "Catalog probe"
+instrument probe = missing()
+```
+
+## HSX1002: Duplicate program declaration
+
+Stage: `typecheck`
+
+Fix: Keep exactly one program declaration.
+
+```hsx expect=HSX1002
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+program second "Second"
+```
+
+## HSX1003: Invalid declaration name
+
+Stage: `typecheck`
+
+Fix: Use lowercase snake_case for program and instrument names.
+
+```hsx expect=HSX1003
+program NotSnake "Catalog probe"
+```
+
+## HSX1004: Duplicate declaration
+
+Stage: `typecheck`
+
+Fix: Keep one declaration or give each declaration a distinct name.
+
+```hsx expect=HSX1004
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+```
+
+## HSX1005: Invalid field name
+
+Stage: `typecheck`
+
+Fix: Rename the field in lower camelCase.
+
+No source-only witness exists. The parser normalizes every accepted field spelling before typechecking.
+
+## HSX1006: Invalid module import
+
+Stage: `bind`
+
+Fix: Resolve one module that exports each imported name exactly once.
+
+No source-only witness exists. This refusal requires a compiler-host module resolver result.
+
+## HSX1007: Invalid cross-instrument reference
+
+Stage: `typecheck`
+
+Fix: Name an existing target instrument in the ref type.
+
+```hsx expect=HSX1007
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields { parentId { type: ref; description: "Parent"; } }
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+```
+
+## HSX1008: Invalid subject or decision port
+
+Stage: `typecheck`
+
+Fix: Complete the declaration and bind every referenced decision port.
+
+```hsx expect=HSX1008
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+subject vehicle { title: "Vehicle"; }
+```
+
+## HSX1009: Imported declaration collision
+
+Stage: `bind`
+
+Fix: Rename the importer-owned declaration or the module-local declaration.
+
+No source-only witness exists. This refusal requires declarations returned by a compiler-host module resolver.
+
+## HSX1010: Wrong type-argument count
+
+Stage: `typecheck`
+
+Fix: Supply exactly the type arguments declared by the instrument function.
+
+```hsx expect=HSX1010
+program catalog_probe "Catalog probe"
+export instrument template<C>() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template<SAR, USD>()
+```
+
+## HSX1011: Missing required argument
+
+Stage: `typecheck`
+
+Fix: Pass every required instrument-function argument.
+
+```hsx expect=HSX1011
+program catalog_probe "Catalog probe"
+export instrument template(value: text) { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template()
+```
+
+## HSX1012: Unknown named argument
+
+Stage: `typecheck`
+
+Fix: Remove the argument or use a parameter declared by the instrument function.
+
+```hsx expect=HSX1012
+program catalog_probe "Catalog probe"
+export instrument template() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template(typo: true)
+```
+
+## HSX1013: Duplicate named argument
+
+Stage: `typecheck`
+
+Fix: Pass each named argument once.
+
+```hsx expect=HSX1013
+program catalog_probe "Catalog probe"
+export instrument template(value: text) { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template(value: "one", value: "two")
+```
+
+## HSX1014: JSON supplied as HSX
+
+Stage: `parse`
+
+Fix: Replace the JSON object with HSX declarations.
+
+```hsx expect=HSX1014
+{ "hsx": 1 }
+```
+
+## HSX1015: Invalid composed program identity
+
+Stage: `typecheck`
+
+Fix: Give the composed program a bounded product id and title.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1016: Empty published composition
+
+Stage: `typecheck`
+
+Fix: Select at least one published instrument with use.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1017: Duplicate published instrument
+
+Stage: `typecheck`
+
+Fix: Keep one use declaration for each published instrument.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1018: Unavailable published instrument
+
+Stage: `typecheck`
+
+Fix: Use an instrument id from the supplied published catalog.
+
+```hsx expect=HSX1018
+program catalog_probe "Catalog probe"
+use missing
+```
+
+## HSX1020: Invalid public action name
+
+Stage: `typecheck`
+
+Fix: Expose each action once under a distinct lower camelCase name.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1021: Invalid exposed action
+
+Stage: `typecheck`
+
+Fix: Expose an action on an explicitly used published instrument.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1022: Authored instrument in a composition
+
+Stage: `typecheck`
+
+Fix: Publish the instrument separately, then select it with use.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1023: Invalid required-field list
+
+Stage: `typecheck`
+
+Fix: List declared, non-optional field names once each.
+
+```hsx expect=HSX1023
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  required: missing;
+}
+```
+
+## HSX1101: Currency mismatch
+
+Stage: `typecheck`
+
+Fix: Use the declared currency because money values never coerce.
+
+```hsx expect=HSX1101
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+const fee: money<SAR> = USD 1.00
+```
+
+## HSX1102: Money precision exceeds minor units
+
+Stage: `typecheck`
+
+Fix: Round the literal to the currency's minor-unit precision.
+
+```hsx expect=HSX1102
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+const fee: money<SAR> = SAR 1.001
+```
+
+## HSX1103: Invalid numeric value
+
+Stage: `typecheck`
+
+Fix: Use an integer, percent, bps, or valid fixed-money binding.
+
+```hsx expect=HSX1103
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  summary: 1.5;
+}
+```
+
+## HSX1104: Value has the wrong type
+
+Stage: `typecheck`
+
+Fix: Pass the type declared by the parameter or UDL slot.
+
+```hsx expect=HSX1104
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  summary: money(SAR, 2500);
+}
+```
+
+## HSX1110: Unsupported parameter combination
+
+Stage: `typecheck`
+
+Fix: Choose a supported compile-time parameter combination.
+
+```hsx expect=HSX1110
+program catalog_probe "Catalog probe"
+export instrument template() {
+  unsupported { message: "Not supported"; fix: "Choose another form"; }
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+instrument probe = template()
+```
+
+## HSX1201: Linear money consumed more than once
+
+Stage: `typecheck`
+
+Fix: Leave exactly one sink for each produced money value.
+
+```hsx expect=HSX1201
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  fields { amount: money<SAR>; }
+action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; moves: [{ amount: rest; }, { amount: rest; }]; }
+}
+```
+
+## HSX1202: Linear money is unconsumed
+
+Stage: `typecheck`
+
+Fix: Route each produced money value to one explicit sink.
+
+```hsx expect=HSX1202
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  fields { amount: money<SAR>; }
+action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; }
+}
+```
+
+## HSX1301: Missing cost-table price
+
+Stage: `typecheck`
+
+Fix: Supply a versioned cost table with a row for every emitted effect.
+
+```hsx expect=HSX1301
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+```
+
+## HSX1302: Invalid cost-table row
+
+Stage: `typecheck`
+
+Fix: Use non-negative integer prices and a supported settlement timing.
+
+No source-only witness exists. This refusal requires a malformed compiler-host cost table.
+
+## HSX1303: Invalid cost-table currency
+
+Stage: `typecheck`
+
+Fix: Use the supported uppercase cost-table currency.
+
+No source-only witness exists. This refusal requires an invalid compiler-host cost-table currency.
+
+## HSX1401: Unbounded action
+
+Stage: `typecheck`
+
+Fix: Replace runtime iteration with a bounded compile-time comprehension.
+
+```hsx expect=HSX1401
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  action run { while { condition: true; }; }
+}
+```
+
+## HSX1402: Missing lifecycle
+
+Stage: `typecheck`
+
+Fix: Declare lifecycle states and an initial state.
+
+```hsx expect=HSX1402
+program catalog_probe "Catalog probe"
+instrument probe { fields {}; action create { steps: []; }; }
+```
+
+## HSX1403: Runtime comprehension bound
+
+Stage: `typecheck`
+
+Fix: Use an integer literal or literal finite list as the bound.
+
+```hsx expect=HSX1403
+program catalog_probe "Catalog probe"
+export instrument template(count: integer) {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  for item in count { action run_[item] { steps: []; } }
+}
+instrument probe = template(count: runtimeCount: integer)
+```
+
+## HSX1404: Comprehension expansion limit
+
+Stage: `typecheck`
+
+Fix: Reduce the fixed expansion to the compiler limit.
+
+```hsx expect=HSX1404
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  for item in 257 { action run_[item] { steps: []; } }
+}
+```
+
+## HSX1405: Invalid compile-time selection
+
+Stage: `typecheck`
+
+Fix: Give compile-time conditions and unsupported branches fixed blocks.
+
+```hsx expect=HSX1405
+program catalog_probe "Catalog probe"
+export instrument template() { unsupported: true; fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template()
+```
+
+## HSX1406: Invalid companion instrument
+
+Stage: `typecheck`
+
+Fix: Construct each companion with a compile-time id.
+
+```hsx expect=HSX1406
+program catalog_probe "Catalog probe"
+export instrument template() {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  instruments { invalid: true; }
+}
+instrument probe = template()
+```
+
+## HSX1501: Unknown UDL clause
+
+Stage: `typecheck`
+
+Fix: Use a clause exported by the targeted UDL vocabulary.
+
+```hsx expect=HSX1501
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  unknown_clause: true;
+}
+```
+
+## HSX1502: Program emits no instruments
+
+Stage: `typecheck`
+
+Fix: Declare or instantiate at least one instrument.
+
+```hsx expect=HSX1502
+program catalog_probe "Catalog probe"
+```
+
+## HSX1503: Missing fields block
+
+Stage: `typecheck`
+
+Fix: Add a fields block, even when it is empty.
+
+```hsx expect=HSX1503
+program catalog_probe "Catalog probe"
+instrument probe { lifecycle { states created; initial created; }; action create { steps: []; }; }
+```
+
+## HSX1504: Missing create action
+
+Stage: `typecheck`
+
+Fix: Add an action create block.
+
+```hsx expect=HSX1504
+program catalog_probe "Catalog probe"
+instrument probe { fields {}; lifecycle { states created; initial created; }; }
+```
+
+## HSX1505: Repeated single-valued clause
+
+Stage: `typecheck`
+
+Fix: Keep one occurrence of the clause.
+
+```hsx expect=HSX1505
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  title: "First"; title: "Second";
+}
+```
+
+## HSX1506: Conflicting public action settings
+
+Stage: `typecheck`
+
+Fix: Keep either public: none or a public action name.
+
+```hsx expect=HSX1506
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  action finish { public: none; public_action: finishProbe; steps: []; }
+}
+```
+
+## HSX1507: Invalid application metadata
+
+Stage: `typecheck`
+
+Fix: Keep contract mechanics in the parameterized instrument.
+
+```hsx expect=HSX1507
+program catalog_probe "Catalog probe"
+export instrument template() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template() { fields: {}; }
+```
+
+## HSX1601: Invalid UDL shape
+
+Stage: `lower`
+
+Fix: Correct the named clause so it matches the targeted UDL definition.
+
+No source-only witness exists. Typed source cannot bypass the checker to emit an invalid UDL shape.
+
+## HSX1602: Invalid UDL semantics
+
+Stage: `lower`
+
+Fix: Correct the named clause so it satisfies the targeted UDL law.
+
+No source-only witness exists. Typed source cannot bypass the checker to emit invalid UDL semantics.
+
+## HSX1603: Unresolved compiler marker
+
+Stage: `lower`
+
+Fix: Correct compile-time block keys or parameter bindings.
+
+```hsx expect=HSX1603
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  title: "__hsx_none__";
+}
+```
+
+# Grammar vocabulary
+
+The parser is hand-written. This page records the exported lexer vocabulary, the UDL clause vocabulary it binds, and the current standard-library module names.
+
+## Keywords
+
+`action`, `as`, `asset`, `commit`, `const`, `expect`, `expose`, `expires`, `export`, `from`, `import`, `instrument`, `module`, `party`, `port`, `program`, `quote`, `rate`, `reconcile`, `settlement`, `subject`, `type`, `use`
+
+## Punctuation
+
+`{`, `}`, `(`, `)`, `[`, `]`, `:`, `,`, `;`, `=`, `|`, `.`, `<`, `>`, `?` and `->`
+
+## Typed clause spellings
+
+`agent description`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
+
+## Standard-library modules
+
+- `advance`
+- `cancellable_booking`
+- `captured_payment`
+- `conditional_disbursement`
+- `credit_facility`
+- `held_payment`
+- `instant_transfer`
+- `metered`
+- `pooled_split`
+- `premium_forward`
+- `reconciled_payout`
+- `recurring_collection`
+- `rotating_pool`
+- `scheduled`
+- `security_deposit`
+- `settlement_batch`
+- `swap`
+- `threshold_pool`
+- `weighted_distribution`
+
+# advance
+
+Source: [`std/settlements/advance.hsx`](../../../std/settlements/advance.hsx)
+
+## Export
+
+`advance<C>`
+
+## Parameters
+
+- `funder: party`
+- `to: party`
+- `amount: money<C>`
+- `fee: optional<percent>`
+- `count: optional<integer>`
+- `every: optional<text>`
+- `first_due: optional<date>`
+- `against: optional<ref>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action                | Clauses lowered                                  |
+| --------------------- | ------------------------------------------------ |
+| `create`              | `agent description`, `moves`, `steps`, `summary` |
+| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
+| `settle`              | `agent description`, `moves`, `steps`, `summary` |
+| `create`              | `agent description`, `moves`, `steps`, `summary` |
+| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
+| `collect_repayment_1` | `due`, `moves`, `steps`, `summary`               |
+
+# cancellable_booking
+
+Source: [`std/settlements/cancellable_booking.hsx`](../../../std/settlements/cancellable_booking.hsx)
+
+## Export
+
+`cancellable_booking<C>`
+
+## Parameters
+
+- `guest: party`
+- `host: party`
+- `amount: money<C>`
+- `starts_at: date`
+- `late_penalty_bps: integer`
+- `late_within: text`
+- `early_penalty_bps: integer`
+- `offer_life: text`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                            |
+| ---------- | ---------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`           |
+| `take`     | `agent description`, `moves`, `steps`, `summary`           |
+| `complete` | `due`, `moves`, `steps`, `summary`                         |
+| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`  |
+| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary` |
+| `retain`   | `agent description`, `moves`, `steps`, `summary`           |
+
+# captured_payment
+
+Source: [`std/settlements/captured_payment.hsx`](../../../std/settlements/captured_payment.hsx)
+
+## Export
+
+`captured_payment<C>`
+
+## Parameters
+
+- `payer: party`
+- `payee: party`
+- `amount: money<C>`
+- `reserve_until: date`
+- `correction: condition`
+- `external_reversal: condition`
+- `capture_mode: text`
+- `correction_mode: text`
+- `negative_position: text`
+- `timeout: text`
+- `derived_amount: optional<block>`
+
+## Decision ports
+
+- `correction`
+- `external_reversal`
+
+## Actions and clauses
+
+| Action             | Clauses lowered                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------- |
+| `create`           | `agent description`, `moves`, `steps`, `summary`                                             |
+| `authorize`        | `agent description`, `moves`, `steps`, `summary`                                             |
+| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
+| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
+| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                 |
+| `void`             | `agent description`, `moves`, `steps`, `summary`                                             |
+| `expire`           | `due`, `moves`, `steps`, `summary`                                                           |
+| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                           |
+| `correction_name`  | `agent description`, `moves`, `port`, `steps`, `summary`                                     |
+| `reversal_name`    | `agent description`, `deadline`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+
+# conditional_disbursement
+
+Source: [`std/settlements/conditional_disbursement.hsx`](../../../std/settlements/conditional_disbursement.hsx)
+
+## Export
+
+`conditional_disbursement<C>`
+
+## Parameters
+
+- `source: party`
+- `destination: party`
+- `cap: money<C>`
+- `amount: money<C>`
+- `decision: condition`
+- `reopen_policy: text`
+- `recovery_policy: text`
+
+## Decision ports
+
+- `decision`
+
+## Actions and clauses
+
+| Action    | Clauses lowered                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------- |
+| `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `deny`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `pay`     | `agent description`, `moves`, `steps`, `summary`                                                  |
+
+# credit_facility
+
+Source: [`std/settlements/credit_facility.hsx`](../../../std/settlements/credit_facility.hsx)
+
+## Export
+
+`credit_facility<C>`
+
+## Parameters
+
+- `lender: party`
+- `borrower: party`
+- `draw_destination: party`
+- `limit: money<C>`
+- `expires_at: date`
+- `obligation: ref`
+- `availability_policy: text`
+- `expiry_policy: text`
+- `close_policy: text`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action    | Clauses lowered                                  |
+| --------- | ------------------------------------------------ |
+| `create`  | `agent description`, `moves`, `steps`, `summary` |
+| `freeze`  | `due`, `moves`, `steps`, `summary`               |
+| `close`   | `agent description`, `moves`, `steps`, `summary` |
+| `create`  | `agent description`, `moves`, `steps`, `summary` |
+| `resolve` | `agent description`, `moves`, `steps`, `summary` |
+
+# held_payment
+
+Source: [`std/settlements/held_payment.hsx`](../../../std/settlements/held_payment.hsx)
+
+## Export
+
+`held_payment<C>`
+
+## Parameters
+
+- `payer: party`
+- `payee: party`
+- `amount: money<C>`
+- `release: condition`
+- `fees: optional<block>`
+- `on_cancel: optional<block>`
+- `derived_amount: optional<block>`
+- `release_to: optional<party>`
+- `whole_amount: optional<block>`
+- `release_action: optional<text>`
+- `whole_fee: optional<money<C>>`
+- `reference: optional<text>`
+- `upstream: optional<ref>`
+- `id_prefix_override: optional<text>`
+
+## Decision ports
+
+- `release`
+
+## Actions and clauses
+
+| Action                | Clauses lowered                                                                               |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
+| `fund_piece_3`        | `agent description`, `moves`, `steps`, `summary`                                              |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                                              |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
+| `release_piece_3`     | `agent description`, `moves`, `steps`, `summary`                                              |
+| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `refund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `unfund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `unfund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `create`              | `agent description`, `moves`, `steps`, `summary`                                              |
+| `fund_piece_1`        | `agent description`, `moves`, `steps`, `summary`                                              |
+| `release_name`        | `agent description`, `deadline`, `description`, `input`, `moves`, `port`, `steps`, `summary`  |
+| `release_on_deadline` | `due`, `moves`, `steps`, `summary`                                                            |
+| `cancel`              | `agent description`, `deadline`, `moves`, `steps`, `summary`                                  |
+| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
+| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
+| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                              |
+| `create`              | `agent description`, `moves`, `steps`, `summary`                                              |
+| `fund`                | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                     |
+| `release_action`      | `agent description`, `deadline`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `release_on_deadline` | `due`, `event name`, `moves`, `steps`, `summary`                                              |
+| `cancel`              | `agent description`, `deadline`, `event name`, `moves`, `steps`, `summary`                    |
+| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                              |
+
+# instant_transfer
+
+Source: [`std/settlements/instant_transfer.hsx`](../../../std/settlements/instant_transfer.hsx)
+
+## Export
+
+`instant_transfer<C>`
+
+## Parameters
+
+- `payer: party`
+- `payee: party`
+- `amount: money<C>`
+- `fees: optional<block>`
+- `derived_amount: optional<block>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action                | Clauses lowered                                  |
+| --------------------- | ------------------------------------------------ |
+| `create`              | `agent description`, `moves`, `steps`, `summary` |
+| `pay_piece_1`         | `agent description`, `moves`, `steps`, `summary` |
+| `pay_piece_2`         | `agent description`, `moves`, `steps`, `summary` |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |
+
+# metered
+
+Source: [`std/settlements/metered.hsx`](../../../std/settlements/metered.hsx)
+
+## Export
+
+`metered`
+
+## Parameters
+
+- `payer: party`
+- `payee: party`
+- `close_by: date`
+- `rates: unknown`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action         | Clauses lowered                         |
+| -------------- | --------------------------------------- |
+| `create`       | `agent description`, `steps`, `summary` |
+| `close_period` | `due`, `steps`, `summary`               |
+
+# pooled_split
+
+Source: [`std/settlements/pooled_split.hsx`](../../../std/settlements/pooled_split.hsx)
+
+## Export
+
+`pooled_split<C>`
+
+## Parameters
+
+- `payer: party`
+- `amount: money<C>`
+- `payout_due: date`
+- `split: block`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action   | Clauses lowered                                  |
+| -------- | ------------------------------------------------ |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+
+# premium_forward
+
+Source: [`std/settlements/premium_forward.hsx`](../../../std/settlements/premium_forward.hsx)
+
+## Export
+
+`premium_forward<C>`
+
+## Parameters
+
+- `payer: party`
+- `carrier: party`
+- `amount: money<C>`
+- `bind: condition`
+- `commission: percent`
+- `policy_ref: optional<text>`
+- `renewal_due: optional<date>`
+- `endorsement: optional<condition>`
+
+## Decision ports
+
+- `bind`
+- `endorsement`
+
+## Actions and clauses
+
+| Action            | Clauses lowered                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `create`          | `agent description`, `steps`, `summary`                                                  |
+| `fund_piece_1`    | `agent description`, `moves`, `steps`, `summary`                                         |
+| `fund_piece_2`    | `agent description`, `moves`, `steps`, `summary`                                         |
+| `bind`            | `agent description`, `description`, `input`, `moves`, `port`, `steps`, `summary`         |
+| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`                                         |
+| `unfund_piece_1`  | `agent description`, `moves`, `steps`, `summary`                                         |
+| `abandon`         | `agent description`, `steps`, `summary`                                                  |
+| `endorsement`     | `agent description`, `capture input`, `description`, `input`, `port`, `steps`, `summary` |
+| `lapse`           | `due`, `steps`, `summary`                                                                |
+
+# reconciled_payout
+
+Source: [`std/settlements/reconciled_payout.hsx`](../../../std/settlements/reconciled_payout.hsx)
+
+## Export
+
+`reconciled_payout<C>`
+
+## Parameters
+
+- `payer: party`
+- `beneficiary: party`
+- `amount: money<C>`
+- `beneficiary_ref: text`
+- `settle_by: date`
+- `matched_within: integer`
+- `matched_ceiling: integer`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                            |
+| ---------- | ---------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`           |
+| `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
+| `settle`   | `due`, `moves`, `reconcile`, `steps`, `summary`            |
+| `create`   | `agent description`, `moves`, `steps`, `summary`           |
+| `carry`    | `agent description`, `moves`, `steps`, `summary`           |
+
+# recurring_collection
+
+Source: [`std/settlements/recurring_collection.hsx`](../../../std/settlements/recurring_collection.hsx)
+
+## Export
+
+`recurring_collection`
+
+## Parameters
+
+- `marker: optional<text>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action    | Clauses lowered                         |
+| --------- | --------------------------------------- |
+| `create`  | `agent description`, `steps`, `summary` |
+| `collect` | `agent description`, `steps`, `summary` |
+| `end`     | `agent description`, `steps`, `summary` |
+
+# rotating_pool
+
+Source: [`std/settlements/rotating_pool.hsx`](../../../std/settlements/rotating_pool.hsx)
+
+## Export
+
+`rotating_pool<C>`
+
+## Parameters
+
+- `members: optional<list<party>>`
+- `contribution: money<C>`
+- `count: integer`
+- `every: optional<text>`
+- `first_due: date`
+- `payout_order: optional<list<party>>`
+- `default_policy: optional<text>`
+- `guarantee_policy: optional<text>`
+- `guarantor: optional<party>`
+- `exit_policy: optional<text>`
+- `memo: optional<text>`
+- `membership: optional<block>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                   |
+| ---------- | ------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
+| `activate` | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `close`    | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `examples`, `moves`, `steps` |
+| `activate` | `due`, `examples`, `moves`, `steps`               |
+| `disband`  | `agent description`, `examples`, `moves`, `steps` |
+| `close`    | `agent description`, `examples`, `moves`, `steps` |
+
+# scheduled
+
+Source: [`std/settlements/scheduled.hsx`](../../../std/settlements/scheduled.hsx)
+
+## Export
+
+`scheduled<C>`
+
+## Parameters
+
+- `payer: party`
+- `payee: party`
+- `amount: money<C>`
+- `count: optional<integer>`
+- `every: text`
+- `first_due: date`
+- `mode: optional<text>`
+- `debtor: optional<party>`
+- `advance_to: optional<party>`
+- `until: optional<condition>`
+- `month_end: optional<text>`
+- `period_liability: optional<text>`
+- `termination_drain: optional<text>`
+- `mandate: optional<condition>`
+- `derived_amount: optional<unknown>`
+
+## Decision ports
+
+- `until`
+- `mandate`
+
+## Actions and clauses
+
+| Action              | Clauses lowered                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| `create`            | `agent description`, `steps`, `summary`                                                           |
+| `create`            | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `approve`           | `agent description`, `steps`, `summary`                                                           |
+| `advance`           | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `delinquent_action` | `due`, `sets at`, `steps`, `summary`                                                              |
+| `complete`          | `due`, `steps`, `summary`                                                                         |
+| `write_off`         | `agent description`, `steps`, `summary`                                                           |
+| `create`            | `agent description`, `steps`, `summary`                                                           |
+| `repay`             | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `refund`            | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `create`            | `agent description`, `steps`, `summary`                                                           |
+| `open_period`       | `due`, `steps`, `summary`                                                                         |
+| `collect_period`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `until`             | `agent description`, `capture input`, `description`, `input`, `port`, `steps`, `summary`          |
+
+# security_deposit
+
+Source: [`std/settlements/security_deposit.hsx`](../../../std/settlements/security_deposit.hsx)
+
+## Export
+
+`security_deposit<C>`
+
+## Parameters
+
+- `payer: party`
+- `holder: party`
+- `amount: money<C>`
+- `claim: optional<condition>`
+- `return: optional<condition>`
+- `claim_amount: optional<block>`
+- `deadline: optional<date>`
+- `claim_to: optional<party>`
+- `return_to: optional<party>`
+- `memo: optional<text>`
+- `claim_input: optional<block>`
+- `claim_capture: optional<block>`
+- `fund_failure_point: optional<text>`
+- `id_prefix_override: optional<text>`
+
+## Decision ports
+
+- `claim`
+- `return`
+
+## Actions and clauses
+
+| Action          | Clauses lowered                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `create`        | `agent description`, `moves`, `steps`, `summary`                                                                 |
+| `place_deposit` | `agent description`, `moves`, `steps`, `summary`                                                                 |
+| `claim_name`    | `agent description`, `description`, `input`, `moves`, `port`, `steps`, `summary`                                 |
+| `return_name`   | `agent description`, `moves`, `steps`, `summary`                                                                 |
+| `create`        | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                     |
+| `fund`          | `agent description`, `deadline`, `moves`, `sandbox failure point`, `steps`, `summary`                            |
+| `claim`         | `agent description`, `capture input`, `deadline`, `decided amount`, `input`, `moves`, `port`, `steps`, `summary` |
+| `return`        | `agent description`, `deadline`, `moves`, `port`, `steps`, `summary`                                             |
+| `expire`        | `due`, `moves`, `steps`, `summary`                                                                               |
+| `cancel`        | `agent description`, `moves`, `steps`, `summary`                                                                 |
+
+# settlement_batch
+
+Source: [`std/settlements/settlement_batch.hsx`](../../../std/settlements/settlement_batch.hsx)
+
+## Export
+
+`settlement_batch<C>`
+
+## Parameters
+
+- `settlement_account: party`
+- `source_capture_refs: text`
+- `fee_entries: text`
+- `external_reversal_offsets: text`
+- `close_trigger: date`
+- `payout_destination: party`
+- `negative_position: text`
+- `payout_acknowledgement: condition`
+- `payout_beneficiary_ref: text`
+
+## Decision ports
+
+- `payout_acknowledgement`
+
+## Actions and clauses
+
+| Action                   | Clauses lowered                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `close`                  | `due`, `moves`, `steps`, `summary`                                                                |
+| `calculate`              | `agent description`, `computes signed_sum`, `moves`, `steps`, `summary`                           |
+| `approve`                | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `instruct`               | `agent description`, `moves`, `payout`, `steps`, `summary`                                        |
+| `payout_acknowledgement` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `reconcile`              | `due`, `moves`, `reconcile`, `steps`, `summary`                                                   |
+| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `accrue`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `adjust`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `correct`                | `agent description`, `moves`, `steps`, `summary`                                                  |
+
+# swap
+
+Source: [`std/settlements/swap.hsx`](../../../std/settlements/swap.hsx)
+
+## Export
+
+`swap<C>`
+
+## Parameters
+
+- `between: list<party>`
+- `amounts: block`
+- `fees: block`
+- `release: condition`
+- `dispute: condition`
+- `side_names: optional<block>`
+- `lifecycle_state_order: optional<list<text>>`
+- `action_bindings: optional<block>`
+- `parked_states: optional<block>`
+- `fixed_prefix: optional<text>`
+
+## Decision ports
+
+- `release`
+- `dispute`
+
+## Actions and clauses
+
+| Action    | Clauses lowered                                                                                                             |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `abandon` | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
+| `cancel`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
+| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
+| `dispute` | `agent description`, `deadline`, `moves`, `port`, `public action`, `steps`, `summary`                                       |
+| `fund`    | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
+| `post`    | `due`, `moves`, `steps`, `summary`                                                                                          |
+| `release` | `agent description`, `moves`, `port`, `public action`, `sets at`, `steps`, `summary`                                        |
+| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
+| `fund`    | `agent description`, `event name`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                    |
+| `release` | `agent description`, `event name`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary` |
+| `post`    | `due`, `event name`, `moves`, `steps`, `summary`                                                                            |
+| `dispute` | `agent description`, `deadline`, `event name`, `moves`, `port`, `public action`, `steps`, `summary`                         |
+| `cancel`  | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                             |
+| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                             |
+
+# threshold_pool
+
+Source: [`std/settlements/threshold_pool.hsx`](../../../std/settlements/threshold_pool.hsx)
+
+## Export
+
+`threshold_pool<C>`
+
+## Parameters
+
+- `contributor: optional<party>`
+- `beneficiary: optional<party>`
+- `target: money<C>`
+- `commitment: money<C>`
+- `max_contributors: optional<integer>`
+- `close_by: date`
+- `close_policy: optional<text>`
+- `overfund_policy: optional<text>`
+- `cancel_policy: optional<text>`
+- `fail_policy: optional<text>`
+- `beneficiary_account: optional<account<C>>`
+- `memo: optional<text>`
+- `contribution_instrument: optional<block>`
+- `wording: optional<block>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                   |
+| ---------- | ------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `activate` | `due`, `moves`, `steps`, `summary`                |
+| `fail`     | `due`, `moves`, `steps`, `summary`                |
+| `close`    | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
+| `collect`  | `agent description`, `moves`, `steps`, `summary`  |
+| `refund`   | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `examples`, `moves`, `steps` |
+| `activate` | `due`, `examples`, `moves`, `steps`               |
+| `fail`     | `due`, `examples`, `moves`, `steps`               |
+| `close`    | `agent description`, `examples`, `moves`, `steps` |
+
+# weighted_distribution
+
+Source: [`std/settlements/weighted_distribution.hsx`](../../../std/settlements/weighted_distribution.hsx)
+
+## Export
+
+`weighted_distribution<C>`
+
+## Parameters
+
+- `source: party`
+- `recipient: party`
+- `amount: money<C>`
+- `record_at: date`
+- `weight: optional<money<C>>`
+- `max_recipients: optional<integer>`
+- `snapshot: optional<condition>`
+- `rounding_policy: optional<text>`
+- `withholding_policy: optional<text>`
+- `correction_policy: optional<text>`
+- `flat: optional<block>`
+- `id_prefix_override: optional<text>`
+
+## Decision ports
+
+- `snapshot`
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `snapshot` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `payout`   | `agent description`, `computes distribute`, `moves`, `steps`, `summary`                           |
+| `create`   | `agent description`, `moves`, `requires refs`, `steps`, `summary`                                 |
+| `payout`   | `computes distribute`, `due`, `moves`, `steps`, `summary`                                         |
+
+# Types
+
+HSX checks types before it emits UDL. Money and account values carry a currency parameter, and no implicit currency conversion exists.
+
+| Kind        | Meaning                                                              |
+| ----------- | -------------------------------------------------------------------- |
+| `account`   | A currency-indexed ledger account reference.                         |
+| `boolean`   | A compile-time or stored true or false value.                        |
+| `bps`       | An integer basis-point value.                                        |
+| `condition` | A declared decision port.                                            |
+| `date`      | A stored date-time string checked by UDL.                            |
+| `integer`   | A bounded whole number.                                              |
+| `money`     | A currency-indexed minor-unit amount.                                |
+| `party`     | A declared program party.                                            |
+| `percent`   | An exact percentage with basis-point precision.                      |
+| `ref`       | A typed reference to another instrument.                             |
+| `text`      | A finite string value.                                               |
+| `unknown`   | An internal checker result that source must resolve before lowering. |
+
+# UDL output
+
+An accepted compile returns three artifacts.
+
+| Artifact       | Contents                                                                            |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `document`     | The canonical UDL object. Serialize it with `serializeUdl` from `@hyperscale0/udl`. |
+| `originMap`    | Canonical UDL paths mapped to authored HSX spans.                                   |
+| `costManifest` | The deterministic manifest pinned to the supplied rate card.                        |
+
+Canonical UDL sorts object keys, preserves array order, uses two-space JSON indentation, and ends with one line feed.