@hyperscale0/hsx 2.4.0 → 3.0.0

package/docs/llms-full.txt

@@ -1,3684 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.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/money_flows"
-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 @hyperscale0/hsx check product.hsx` while editing and `npx @hyperscale0/hsx build product.hsx --out product.udl.json` when the program passes. In the full repository checkout, run `bun install` once from the repository root, then use `bun open/hsx/bin/hsx.ts check product.hsx` and `bun open/hsx/bin/hsx.ts build product.hsx --out product.udl.json`. In the standalone HSX package checkout, the entrypoint is `bin/hsx.ts`.
-
-# 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. The emitted UDL field keeps the currency as `x-hyperscale-currency`, which is how the platform learns a program's ledger currency.
-
-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 money flows library (open/hsx/std). Import a money flow by export name from `std/money_flows`, 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/money_flows"
-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 money flows 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.
-
-## Account fields
-
-When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
-
-```hsx
-fields {
-  customerAccountId {
-    type: account<SAR>;
-    "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
-  }
-  amount: money<SAR>;
-}
-```
-
-The account type pins the currency and identifier shape. The reference filter
-pins the allowed ledger roles. Product admission requires every account field
-to declare a non-empty role list. Choose roles that match the accounts the
-program will use; `customer_balance` is the role in this example.
-
-Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
-with `column: role` and `values: [...]`. There is no shorter role annotation.
-A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
-the host's account-role admission law.
-
-## Money fields
-
-A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
-
-```hsx
-fields {
-  amount: money<SAR>;
-  discount { type: money<SAR>; optional: true; allow_zero: true; }
-}
-```
-
-`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
-
-## Date fields
-
-A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
-
-## Port declarations and action clauses
-
-HSX supports two distinct port syntaxes depending on scope:
-
-1. **Top-level port declarations** declare a named port at program scope using `allowed: [...]`.
-2. **Action-level port clauses** define caller permissions directly inside an instrument action using `allowed_parties: [...]`.
-
-Top-level port declaration:
-
-```hsx
-port confirm_delivery {
-  allowed: [buyer];
-}
-```
-
-Action-level port clause:
-
-```hsx
-action release {
-  agent_description: "Release escrowed funds to the payee."
-  steps: [];
-  moves: [];
-  port {
-    allowed_parties: [payer];
-  }
-}
-```
-
-Writing `allowed:` inside an action-level `port` clause triggers diagnostic `HSX1508`. Use `allowed_parties: [...]` inside action clauses, and reserve `allowed: [...]` for top-level port declarations.
-
-# 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 {
-  agent_description: "Manage a bounded approval decision across pending, approved, and rejected states."
-  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 {
-    agent_description: "Create an approval record in pending state."
-    steps: [];
-    moves: [];
-  }
-  action approve {
-    agent_description: "Approve the pending decision."
-    steps: [];
-    moves: [];
-  }
-  action reject {
-    agent_description: "Reject the pending decision."
-    steps: [];
-    moves: [];
-  }
-}
-```
-
-Every callable custom instrument action becomes an agent tool and requires an `agent_description` string. Instruments that declare callable actions also require an `agent_description` string. Actions that declare a `due` clause are exempt system actions that run on a schedule instead of an agent call. The compiler emits `HSX1509` when an author omits `agent_description` on an instrument or callable action.
-
-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/money_flows"
-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/money_flows"
-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/money_flows"
-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. `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.
-
-Finite obligation counts expand the same lifecycle for each slice. A lifecycle source may be a finite list; `without(states, state)` removes one state before expansion. This preserves rejection of a repeated delinquency marker for its current slice.
-
-Use `advance` with `dated: true` when each repayment has a signed date. `repayment_source` separates the borrower from the capital recipient; `profit_to` sends computed profit to a separate account. The caller partitions the principal and profit across stored repayments. These partitions do not enforce equal slices or ordered dates.
-
-# 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/money_flows"
-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/money_flows"
-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
-}
-```
-
-## Recomposition and exposed actions
-
-When evolving an existing Product with new instruments or flows, the composer plans the candidate program against the active Product Build.
-
-Public action exposures preserve stable semantic identities across builds. Unchanged authored instruments and catalog instruments retain their exposures without false removal and re-addition churn. Only genuinely new, removed, or rebound action aliases appear in the exposure delta.
-
-# 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() {
-  agent_description: "Reusable approval lifecycle template."
-  title: "Approval"
-  summary: "A reusable approval lifecycle"
-  fields {}
-  lifecycle {
-    states pending approved;
-    initial pending;
-    on approve: pending -> approved;
-  }
-  action create {
-    agent_description: "Create a pending approval record."
-    steps: [];
-    moves: [];
-  }
-  action approve {
-    agent_description: "Approve the pending decision."
-    steps: [];
-    moves: [];
-  }
-}
-instrument review = approval()
-```
-
-Custom instruments and callable actions require `agent_description: "..."`. An agent uses these descriptions as tool instructions when invoking actions on an instance. Actions that declare a `due` clause run without an agent call and remain exempt from this requirement. Omitting `agent_description` on callable actions or their containing instruments triggers `HSX1509`.
-
-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.
-
-## An authored action that moves money
-
-Declare each cash movement in `moves` with a unique `key`, an `operation`, and `bind` operands. This complete program comes from [payment.hsx](../../examples/05-authored-instrument/payment.hsx). The docs builder requires the snippet to match that file and compiles it with the packaged cost table.
-
-```hsx source=examples/05-authored-instrument/payment.hsx
-program authored_payment "Authored payment"
-
-instrument payment {
-  agent_description: "Collect a stored payment once from its payer."
-  title: "Payment"
-  summary: "A payment with fixed payer and payee accounts"
-  fields {
-    payerAccountId: account<SAR>;
-    payeeAccountId: account<SAR>;
-    amount: money<SAR>;
-  }
-  parties { payer: payerAccountId; beneficiary: payeeAccountId; }
-  lifecycle {
-    states pending paid;
-    initial pending;
-    on pay: pending -> paid;
-  }
-  action create {
-    agent_description: "Open a pending payment without moving money."
-    steps: [];
-    moves: [];
-  }
-  action pay {
-    agent_description: "Move the stored amount from payer to payee."
-    steps: [];
-    moves: [{
-      bind: {
-        amount: { from: "instance", path: "fields.amount" }
-        currency: { from: "const", value: "SAR" }
-        sourceAccountId: { from: "instance", path: "fields.payerAccountId" }
-        destinationAccountId: { from: "instance", path: "fields.payeeAccountId" }
-      }
-      key: "payment_transfer"
-      operation: "internal_transfer.create"
-    }];
-  }
-}
-```
-
-`from: "instance"` reads an immutable stored field. `from: "const"` supplies the literal currency. The four bindings supply the transfer's amount, currency, source account and destination account. `internal_transfer.create` names the transfer operation; `payment_transfer` identifies this move within the action. Account IDs come from account creation or discovery before creating the payment. They are never invented by the program.
-
-`create` opens a pending record without cash movement. `pay` moves the stored amount and transitions to `paid`; the lifecycle refuses a second payment under a new action request. The compiler emits these bindings into UDL. Execution still requires an engine that admits the operation and accounts.
-
-# 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/money_flows"
-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. During recomposition planning, compose plan calculates the candidate program's proposed estimate and reconciles it against the current Build's frozen pricing quote. The existing Product retains its frozen quote until the recomposition is applied.
-
-An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. `examples/cost-table.json` ships one rate card per priced billing currency; the compiler picks the card whose currency the program's money fields move. Money in a currency no card prices reports `HSX1304`, and money in two currencies reports `HSX1305`: a program bills in one ledger currency. A move of a `money<SAR>` field moves SAR whatever the caller wrote in the instance currency field: the compiler pins the move's currency binding to the constant, and a binding it cannot pin reports `HSX1306`. Do not create another 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/money_flows"
-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 2.4.0, the HSX compiler
-
-Usage:
-  hsx check <file.hsx> [--catalog <catalog.udl>] [--strict]
-  hsx build <file.hsx> [--catalog <catalog.udl>] [--out <file.json>] [--strict]
-  hsx cost <file.hsx> [--catalog <catalog.udl>] [--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:
-  --catalog <file>  Read the published instrument catalogue as canonical UDL JSON.
-  --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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 collides with published catalog
-
-Stage: `typecheck`
-
-Fix: Rename the authored instrument to avoid colliding with published catalog instruments.
-
-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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  required: missing;
-}
-```
-
-## HSX1024: Decision party has no matching account binding
-
-Stage: `typecheck`
-
-Fix: Bind the allowed party to an account field and use that binding in the decision action.
-
-```hsx expect=HSX1024
-program decision_binding "Decision binding"
-party buyer: person
-party seller: business
-port approve { allowed: [buyer] }
-instrument gated(decision: condition) {
-  fields {}
-  parties { payer: seller }
-  lifecycle { states created done; initial created; on approve: created -> done; }
-  action create { steps: []; }
-  action [decision] { steps: []; port { allowed_parties: [payer]; } }
-}
-instrument gate = gated(decision: port approve)
-```
-
-## HSX1025: Unknown decision port shape type
-
-Stage: `typecheck`
-
-Fix: Declare the shape field as text, money(CUR), date, integer, boolean, account(CUR), ref<instrument_id>, id(instrument_id), bps, or percent.
-
-```hsx expect=HSX1025
-program catalog_probe "Catalog probe"
-import { security_deposit } from "std/money_flows"
-party buyer: person
-party seller: business
-settlement hold = security_deposit {
-  payer: buyer
-  holder: seller
-  amount: depositAmount: money(SAR)
-  claim: port report_damage
-  claim_amount: { field: damageAmount, bound: depositAmount, remainder: return }
-  return: port pass_inspection
-}
-port report_damage { allowed: [seller] shape { damageAmount: money(SAR) } }
-port pass_inspection { allowed: [seller] shape { invalidField: mystery_type } }
-```
-
-## HSX1026: Decision port input type mismatch with instrument capture field
-
-Stage: `typecheck`
-
-Fix: Declare the decision port input field with the type expected by the instrument capture field.
-
-No source-only witness exists. This refusal requires a compiler-host published catalog.
-
-## 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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  summary: money(SAR, 2500);
-}
-```
-
-## HSX1105: allow_zero needs a money field
-
-Stage: `typecheck`
-
-Fix: Put allow_zero: true on a money field, or remove it; amounts are strictly positive unless a money field opts in.
-
-```hsx expect=HSX1105
-program catalog_probe "Catalog probe"
-instrument probe {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields { memo { type: text; allow_zero: true; } }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  
-}
-```
-
-## 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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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.
-
-## HSX1304: Unpriced ledger currency
-
-Stage: `typecheck`
-
-Fix: Move money in a currency the shipped cost tables price.
-
-```hsx expect=HSX1304
-program catalog_probe "Catalog probe"
-instrument probe {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields { amount: money<JPY>; }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  
-}
-```
-
-## HSX1305: More than one ledger currency
-
-Stage: `typecheck`
-
-Fix: Move all money in one currency; a program bills in one ledger currency.
-
-```hsx expect=HSX1305
-program catalog_probe "Catalog probe"
-instrument probe {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields { amount: money<SAR>; fee: money<USD>; }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  
-}
-```
-
-## HSX1306: Fixed-currency amount moved in another currency
-
-Stage: `typecheck`
-
-Fix: Bind the currency of a money<CUR> move or account step as the constant CUR; the compiler pins a binding that reads the instrument's currency field.
-
-```hsx expect=HSX1306
-program catalog_probe "Catalog probe"
-instrument probe {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields { amount: money<SAR>; payeeAccountId: account<SAR>; payerAccountId: account<SAR>; }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  action pay { agent_description: "Pay the amount."; moves: [{ "bind": { "amount": { "from": "instance"; "path": "fields.amount"; }; "currency": { "from": "const"; "value": "USD"; }; "destinationAccountId": { "from": "instance"; "path": "fields.payeeAccountId"; }; "sourceAccountId": { "from": "instance"; "path": "fields.payerAccountId"; }; }; "key": "transfer"; "operation": "internal_transfer.create"; }]; steps: []; }
-}
-```
-
-## 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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    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: {}; }
-```
-
-## HSX1508: Invalid action-level port syntax
-
-Stage: `typecheck`
-
-Fix: Use allowed_parties: [...] inside an action-level port clause; allowed: is for top-level port declarations.
-
-```hsx expect=HSX1508
-program catalog_probe "Catalog probe"
-party approver: person
-instrument probe {
-  fields {}
-  lifecycle { states created; initial created; }
-  action create {
-    steps: [];
-    port { allowed: [approver]; }
-  }
-}
-```
-
-## HSX1509: Callable action without an agent description
-
-Stage: `typecheck`
-
-Fix: Add agent_description: "..." to the instrument and to every action a caller can reach; composer.check refuses the program without them.
-
-```hsx expect=HSX1509
-program catalog_probe "Catalog probe"
-instrument probe {
-  fields {}
-  lifecycle { states created; initial created; }
-  action create { steps: []; }
-}
-```
-
-## 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 {
-  agent_description: "Probe instrument for catalog diagnostics.";
-  fields {  }
-  lifecycle { states created; initial created; }
-  action create {
-    agent_description: "Create a probe instance.";
-    steps: [];
-  }
-  title: "__hsx_none__";
-}
-```
-
-## HSX1610: Invalid piece partition
-
-Stage: `typecheck`
-
-Fix: Bind immutable money and account fields to one declared partition.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-## HSX1611: Invalid piece stage
-
-Stage: `typecheck`
-
-Fix: Use a declared piece stage and let the compiler derive pieceId.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-## HSX1612: Invalid action graph
-
-Stage: `typecheck`
-
-Fix: Declare an acyclic action graph within the expansion bound.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-## HSX1613: Invalid static call binding
-
-Stage: `typecheck`
-
-Fix: Bind declared typed targets with unique captures and money consumption.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-## HSX1614: Incompatible action boundary
-
-Stage: `typecheck`
-
-Fix: Keep the parent principal, approval and recovery boundary.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-## HSX1615: Invalid leaf evidence or effects
-
-Stage: `typecheck`
-
-Fix: Declare evidence and the exact effects of each expanded leaf.
-
-No source-only witness exists. The shared UDL action-plan validator supplies the code and source path.
-
-# 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
-
-`funding`, `receipt distribution`, `requires allocation`, `allocation`, `contributions`, `allocate`, `contribution stage`, `date order`, `unique`, `transitions refs`, `cascade`, `action library`, `agent description`, `calls`, `requires input`, `engine owned`, `capture engine`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `piece plan`, `piece stage`, `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 binding`, `template id`, `title`, `update`, `request authority`
-
-## Standard-library modules
-
-- `advance`
-- `cancellable_booking`
-- `captured_payment`
-- `conditional_disbursement`
-- `credit_facility`
-- `held_payment`
-- `instant_transfer`
-- `metered`
-- `pooled_split`
-- `premium_forward`
-- `reconciled_payout`
-- `rotating_pool`
-- `scheduled`
-- `security_deposit`
-- `settlement_batch`
-- `swap`
-- `threshold_pool`
-- `weighted_distribution`
-
-# advance
-
-Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
-
-## Export
-
-`advance<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `funder` | `party` | Yes | The party providing the upfront capital. |
-| `to` | `party` | Yes | The party receiving the advance and responsible for repayment. |
-| `amount` | `money<C>` | Yes | Total advanced principal in minor units of currency `C`. |
-| `fee` | `optional<percent>` | No | Optional markup percentage fee charged on the advance (basis points precision). |
-| `count` | `optional<integer>` | No | Optional number of scheduled installment repayments. |
-| `every` | `optional<text>` | No | Optional recurrence duration between installments (e.g. `"P30D"`). |
-| `first_due` | `optional<date>` | No | Optional date for the first installment repayment. |
-| `against` | `optional<ref>` | No | Optional reference to a hold instrument whose release will be carved to repay the advance. |
-| `repayment_source` | `optional<party>` | No | Optional party repaying when distinct from the capital recipient. |
-| `profit_to` | `optional<party>` | No | Optional recipient of profit, separated from principal repayments. |
-| `dated` | `optional<boolean>` | No | Require an explicit signed date for each repayment instead of duration offsets. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Upfront capital disbursement repaid by carving future held payment releases or over scheduled installments.
-
-### Purpose
-
-`advance` provides working capital, merchant cash advances, or contractor pre-funding from a funder to a recipient.
-Repayment occurs either automatically by intercepting (carving) releases from a linked escrow hold (`against`),
-or over calendar-anchored installment repayments (`count`, `every`, `first_due`).
-
-### Selection guidance
-
-- vs `credit_facility`: `advance` disburses a single upfront lump-sum principal that is repaid over time.
-  `credit_facility` establishes a reusable revolving credit line with multiple draws up to a limit,
-  where repayments restore available borrowing capacity.
-- vs `conditional_disbursement`: `advance` expects repayment of the advanced principal plus optional fees.
-  `conditional_disbursement` disburses non-repayable grants, claims, or milestone payments against external evidence.
-- vs `held_payment`: `held_payment` holds customer funds in escrow until delivery. An `advance` can carve repayments
-  directly out of a `held_payment`'s release using `against`.
-
-### Parameters
-
-- `funder`: The party providing the upfront capital.
-- `to`: The party receiving the advance and responsible for repayment.
-- `amount`: Total advanced principal in minor units of currency `C`.
-- `fee`: Optional markup percentage fee charged on the advance (basis points precision).
-- `count`: Optional number of scheduled installment repayments.
-- `every`: Optional recurrence duration between installments (e.g. `"P30D"`).
-- `first_due`: Optional date for the first installment repayment.
-- `repayment_source`: Optional party repaying when distinct from the capital recipient.
-- `profit_to`: Optional recipient of profit, separated from principal repayments.
-- `dated`: Require an explicit signed date for each repayment instead of duration offsets.
-- `against`: Optional reference to a hold instrument whose release will be carved to repay the advance.
-
-### Decision ports
-
-None. Repayment is driven by linked hold releases or scheduled calendar dates.
-
-### Example
-
-```hsx
-program advance_example "Advance example"
-import { advance } from "std/money_flows"
-party funder: business
-party recipient: business
-settlement advance_payment = advance {
-  funder: funder
-  to: recipient
-  amount: principal: money(SAR)
-  fee: 2.5%
-  count: 2
-  every: P30D
-  first_due: firstDueAt
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `id prefix`
-- `moves`
-- `partitions`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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_[i]` | `agent description`, `due`, `moves`, `steps`, `summary` |
-
-# cancellable_booking
-
-Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/cancellable_booking.hsx)
-
-## Export
-
-`cancellable_booking<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `guest` | `optional<party>` | No | The booking customer paying the fee and receiving refunds. |
-| `host` | `optional<party>` | No | The service provider receiving the payout or retained cancellation penalty. |
-| `amount` | `optional<money<C>>` | No | Total booking price in minor units of currency `C`. |
-| `starts_at` | `optional<date>` | No | Stored ISO 8601 date when the booking begins. |
-| `late_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling within the late window. |
-| `late_within` | `optional<text>` | No | ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days). |
-| `early_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling before the late window. |
-| `offer_life` | `optional<text>` | No | ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`). |
-| `cancel_bands` | `optional<list<block>>` | No | Supply cancel_bands to select deposit/balance custody instead of quoted cancellation. |
-| `price_value` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `supplier_cost` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `departure` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `balance_before` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `confirmation_window` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `unpaid_band` | `optional<integer>` | No | The unpaid_band index selects a retained deposit policy. |
-| `acceptance` | `optional<block>` | No | acceptance optionally supplies an aggregate gate. |
-| `deposit_bps` | `optional<integer>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `tax_bps` | `optional<integer>` | No | tax_bps applies to margin after the supplier share. |
-| `authority_type` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
-| `supplier_role` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
-| `collects` | `optional<json>` | No | collects optionally cascades named actions to linked instruments on deposit. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Time-anchored reservation holding booking funds in escrow with dynamically quoted cancellation penalties.
-
-### Purpose
-
-`cancellable_booking` holds booking fees in escrow from a guest for a host until a scheduled start date.
-It fits hospitality, travel reservations, studio rentals, event tickets, and appointments where guests
-can cancel prior to start, but cancellation penalties depend on how close to the start date cancellation occurs.
-
-### Selection guidance
-
-- vs `held_payment`: Both hold money in escrow and both quote a cancellation before it is spent.
-  `cancellable_booking` prices the penalty against the time left before `starts_at`, so the charge moves
-  as the start approaches; `held_payment` has no start date and quotes one flat charge.
-  Choose `cancellable_booking` whenever cancellation fees are time-sensitive.
-- vs `security_deposit`: `security_deposit` holds funds to cover damages claimed by the holder.
-  `cancellable_booking` holds the service fee itself and releases to the host upon `starts_at` or refunds net of penalty.
-
-### Parameters
-
-- `guest`: The booking customer paying the fee and receiving refunds.
-- `host`: The service provider receiving the payout or retained cancellation penalty.
-- `amount`: Total booking price in minor units of currency `C`.
-- `starts_at`: Stored ISO 8601 date when the booking begins.
-- `late_penalty_bps`: Penalty in basis points applied when cancelling within the late window.
-- `late_within`: ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days).
-- `early_penalty_bps`: Penalty in basis points applied when cancelling before the late window.
-- `offer_life`: ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`).
-
-### Decision ports
-
-None. Action transitions are driven by guest API calls (`take`, `cancel`, `confirm`) and scheduled completion (`complete` due at `starts_at`).
-
-### Example
-
-```hsx
-program studio_booking "Studio booking"
-import { cancellable_booking } from "std/money_flows"
-party guest: person
-party studio: business
-settlement studio_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"
-}
-```
-
-### Finite cancellation bands
-
-Supply cancel_bands to select deposit/balance custody instead of quoted cancellation.
-Each band has name, refund (full, balance or none), starts_at after the first band,
-and supplier_bps when money is retained. The unpaid_band index selects a retained
-deposit policy. Omit it to return the deposit; a full-refund band also returns it. price_value and supplier_cost fix the price; deposit_bps derives
-the deposit. balance_before and confirmation_window are positive fixed durations
-relative to departure. tax_bps applies to margin after the supplier share.
-authority_type and supplier_role bind release to a consumed confirmation decision.
-collects optionally cascades named actions to linked instruments on deposit.
-acceptance optionally supplies an aggregate gate. All actions are private until
-expose selects them. Ordered band starts and deadlines prevent a late sweep from
-extending an earlier band's cancellation rights. Full timeout refund returns price.
-Seven derivations suffice for three bands; larger finite policies use up to the
-UDL bound of 64 derived amounts. shift_date(date, duration, "before") subtracts a
-fixed duration; omitting the direction adds it. Invalid dates or durations refuse.
-
-## Declared clauses
-
-- `agent description`
-- `caller parked states`
-- `cascade`
-- `commit`
-- `deadline`
-- `description`
-- `distinct parties`
-- `due`
-- `id prefix`
-- `input`
-- `moves`
-- `partitions`
-- `port`
-- `quote`
-- `requires drained`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-- `unique`
-- `updates`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `take` | `agent description`, `moves`, `sandbox failure point`, `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` |
-| `create` | `agent description`, `deadline`, `steps`, `unique` |
-| `deposit` | `agent description`, `cascade`, `deadline`, `moves`, `port`, `steps` |
-| `expire` | `agent description`, `due`, `requires drained`, `steps` |
-| `[balance_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
-| `[open_action]` | `agent description`, `due`, `steps` |
-| `[cancel_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
-| `cancel_unpaid` | `agent description`, `due`, `moves`, `steps` |
-| `await_confirmation` | `agent description`, `due`, `steps` |
-| `confirm` | `agent description`, `deadline`, `input`, `steps`, `updates` |
-| `release` | `agent description`, `moves`, `steps` |
-| `refund_unconfirmed` | `agent description`, `due`, `moves`, `steps` |
-
-# captured_payment
-
-Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captured_payment.hsx)
-
-## Export
-
-`captured_payment<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | Party whose account balance is reserved during authorization. |
-| `payee` | `party` | Yes | Beneficiary party capturing authorized funds. |
-| `amount` | `money<C>` | Yes | Maximum authorized reservation in minor units of currency `C`. |
-| `reserve_until` | `date` | Yes | Expiration date for the authorization hold. |
-| `correction` | `condition` | Yes | Condition port allowing post-settlement amount corrections. |
-| `external_reversal` | `condition` | Yes | Condition port allowing external processor chargebacks/reversals. |
-| `derived_amount` | `optional<block>` | No | Optional block declaring percentage fee calculation. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Two-phase authorization and capture payment flow for card and merchant processing.
-
-### Purpose
-
-`captured_payment` reserves funds against a payer's account and allows the payee to capture the authorized
-balance in one or multiple slices before a reservation expiry date (`reserve_until`). It fits ecommerce checkouts,
-card processing, hotel authorizations, and pay-at-pump fuel payments where final amounts vary or settle later.
-
-### Selection guidance
-
-- vs `instant_transfer`: `instant_transfer` immediately transfers money from payer to payee in a single irreversible
-  step without reservation or settlement delays. `captured_payment` separates authorization from capture, allowing
-  incremental captures, voids, amount corrections via the `correction` port, and external network reversals via `external_reversal`.
-- vs `held_payment`: `held_payment` holds the full amount in third-party escrow pending release. `captured_payment`
-  reserves funds directly on payer balance and settles incrementally directly to payee.
-
-### Parameters
-
-- `payer`: Party whose account balance is reserved during authorization.
-- `payee`: Beneficiary party capturing authorized funds.
-- `amount`: Maximum authorized reservation in minor units of currency `C`.
-- `reserve_until`: Expiration date for the authorization hold.
-- `correction`: Condition port allowing post-settlement amount corrections.
-- `external_reversal`: Condition port allowing external processor chargebacks/reversals.
-- `derived_amount`: Optional block declaring percentage fee calculation.
-
-### Decision ports
-
-- `correction`: Condition allowing payee or processor to submit an amount correction after settlement.
-- `external_reversal`: Condition allowing bank or card network to execute an external reversal.
-
-### Example
-
-```hsx
-program captured_payment_example "Captured payment example"
-import { captured_payment } from "std/money_flows"
-party payer: person
-party payee: business
-settlement card_payment = captured_payment {
-  payer: payer
-  payee: payee
-  amount: authorizedAmount: money(SAR)
-  reserve_until: reserveUntil
-  correction: port correct_capture
-  external_reversal: port reverse_capture within P14D
-}
-port correct_capture { allowed: [payee] }
-port reverse_capture {
-  allowed: [payee]
-  shape: { externalReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `deadline`
-- `description`
-- `due`
-- `input`
-- `moves`
-- `port`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `correction`
-- `external_reversal`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `authorize` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `capture` | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `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`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
-| `[reversal_name]` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary` |
-
-# conditional_disbursement
-
-Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flows/conditional_disbursement.hsx)
-
-## Export
-
-`conditional_disbursement<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `source` | `party` | Yes | The funding party providing the money. |
-| `destination` | `party` | Yes | The beneficiary party receiving approved disbursements. |
-| `cap` | `money<C>` | Yes | Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`. |
-| `amount` | `money<C>` | Yes | Binding name for child approval amount values. |
-| `decision` | `condition` | Yes | Port conditioning approval, requiring evidence reference. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Capped disbursement from a source party to a destination party gated on stored external decision evidence.
-
-### Purpose
-
-`conditional_disbursement` manages evidence-contingent payouts subject to a cumulative cap.
-It fits insurance claim settlements, grant tranches, subsidy distributions, and escrow milestones
-where each approved payment requires explicit external evidence and the total paid must not exceed `cap`.
-
-### Selection guidance
-
-- vs `advance`: `conditional_disbursement` disburses non-repayable funds against external evidence
-  up to a declared cap. `advance` pays money up front with the expectation of repayment through carved
-  hold releases or scheduled installments.
-- vs `instant_transfer`: `instant_transfer` moves money immediately with no evidence gate or cap.
-  `conditional_disbursement` requires an external decision port and evidence reference before any child amount moves.
-
-### Parameters
-
-- `source`: The funding party providing the money.
-- `destination`: The beneficiary party receiving approved disbursements.
-- `cap`: Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`.
-- `amount`: Binding name for child approval amount values.
-- `decision`: Port conditioning approval, requiring evidence reference.
-
-### Decision ports
-
-- `decision`: External port providing decision evidence required to approve child disbursement amounts.
-
-### Example
-
-```hsx
-program conditional_disbursement_example "Conditional disbursement example"
-import { conditional_disbursement } from "std/money_flows"
-party source: business
-party claimant: person
-settlement claim_payment = conditional_disbursement {
-  source: source
-  destination: claimant
-  cap: policyLimit: money(SAR)
-  amount: approvedAmount: money(SAR)
-  decision: port approve_claim
-}
-port approve_claim {
-  allowed: [source]
-  shape: { evidenceReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `description`
-- `id prefix`
-- `input`
-- `moves`
-- `port`
-- `steps`
-- `summary`
-- `title`
-- `unique`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `decision`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `deny` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
-| `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `pay` | `agent description`, `moves`, `steps`, `summary` |
-
-# credit_facility
-
-Source: [`std/money_flows/credit_facility.hsx`](../../../std/money_flows/credit_facility.hsx)
-
-## Export
-
-`credit_facility<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `lender` | `party` | Yes | The financing institution or party providing the credit capacity. |
-| `borrower` | `party` | Yes | The borrowing party authorized to draw against the facility limit. |
-| `draw_destination` | `party` | Yes | Account or party receiving disbursed draw proceeds. |
-| `limit` | `money<C>` | Yes | Total revolving borrowing limit in minor units of currency `C`. |
-| `expires_at` | `date` | Yes | Expiration date after which new draws cannot be opened. |
-| `obligation` | `ref` | Yes | Reference to a scheduled obligation instrument handling draw repayments. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Revolving credit line providing reusable borrowing capacity up to a limit backed by scheduled obligations.
-
-### Purpose
-
-`credit_facility` manages revolving commercial credit, inventory financing, and overdraft facilities.
-A borrower can draw funds multiple times up to `limit` into `draw_destination`. Each draw creates a child
-record linked to a scheduled `obligation`. Repayments restore available borrowing capacity until `expires_at`.
-
-### Selection guidance
-
-- vs `advance`: `credit_facility` provides revolving, reusable credit lines where multiple draws can occur
-  and repayments restore capacity. `advance` is a single upfront lump-sum disbursement with a fixed repayment plan.
-- vs `scheduled`: `scheduled` defines repayment installments or recurring transfers. `credit_facility` delegates
-  draw repayments to a `scheduled` obligation while tracking total facility utilization and limit compliance.
-
-### Parameters
-
-- `lender`: The financing institution or party providing the credit capacity.
-- `borrower`: The borrowing party authorized to draw against the facility limit.
-- `draw_destination`: Account or party receiving disbursed draw proceeds.
-- `limit`: Total revolving borrowing limit in minor units of currency `C`.
-- `expires_at`: Expiration date after which new draws cannot be opened.
-- `obligation`: Reference to a scheduled obligation instrument handling draw repayments.
-
-### Decision ports
-
-None on the facility itself. Mandates and decision ports are declared on the linked `obligation` instrument.
-
-### Example
-
-```hsx
-program credit_facility_example "Credit facility example"
-import { credit_facility, scheduled } from "std/money_flows"
-party lender: business
-party borrower: business
-party draw_destination: business
-party repayment_source: business
-settlement repayment = scheduled {
-  mode: obligation
-  payer: repayment_source
-  payee: lender
-  debtor: borrower
-  amount: principal: money(SAR)
-  count: 2
-  every: P30D
-  first_due: firstDueAt
-}
-settlement facility = credit_facility {
-  lender: lender
-  borrower: borrower
-  draw_destination: draw_destination
-  limit: facilityLimit: money(SAR)
-  expires_at: expiresAt
-  obligation: repayment.obligation
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `id prefix`
-- `moves`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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/money_flows/held_payment.hsx`](../../../std/money_flows/held_payment.hsx)
-
-## Export
-
-`held_payment<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The funding party providing the money. |
-| `payee` | `party` | Yes | The beneficiary party receiving the released funds. |
-| `amount` | `money<C>` | Yes | Total amount in minor units of currency `C`. |
-| `release` | `condition` | Yes | Condition required to release funds. Supports decision ports (`port <name>`), date deadlines (`at(<date>)`), or disjunctions (`port <name> &#124; at(<date>)`). |
-| `fees` | `optional<block>` | No | Optional block declaring percentage or fixed fee cuts, e.g. `{ buyer: 1%, seller: 2% }`. |
-| `on_cancel` | `optional<block>` | No | Optional block defining refund splits if cancelled while funded, e.g. `(funded) { buyer: 90%, seller: 10% }`. |
-| `derived_amount` | `optional<block>` | No | Optional block declaring machine-derived fees calculated as a percentage of another field. |
-| `release_to` | `optional<party>` | No | Optional third-party destination for release. |
-| `whole_amount` | `optional<block>` | No | Optional block enabling single-action funding and release of principal plus on-top fee. |
-| `release_action` | `optional<text>` | No | Optional custom name for the release action. |
-| `whole_fee` | `optional<money<C>>` | No | Optional money amount for the whole-amount fee. |
-| `reference` | `optional<text>` | No | Optional string reference stored on the instance. |
-| `upstream` | `optional<ref>` | No | Optional reference to a parent instrument. |
-| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
-| `cancel_charge_bps` | `optional<integer>` | No | Optional cancellation charge in basis points. Declaring it gives the settlement a quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both, `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee. A zero charge keeps the flow with a zero fee. |
-| `cancel_offer_life` | `optional<text>` | No | ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`. |
-| `private_actions` | `optional<boolean>` | No | Suppress automatic aliases. Publish chosen actions with `expose`. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Escrow settlement holding funds from a payer before releasing to a payee upon a verified condition or deadline.
-
-### Purpose
-
-`held_payment` holds customer funds in a dedicated product escrow account away from both payer and payee.
-It fits milestone-gated commerce, vehicle escrow, contractor holdbacks, and goods purchases where funds
-must remain reserved until delivery confirmation or inspection.
-
-### Selection guidance
-
-- vs `cancellable_booking`: Both hold funds in custody and both can quote a cancellation before it is
-  spent. `held_payment` quotes one flat charge declared by `cancel_charge_bps`, because it has no scheduled
-  start to price against, and `on_cancel` remains the way to unwind it on static splits instead.
-  Choose `cancellable_booking` when the charge must follow the time left before a scheduled start date.
-- vs `security_deposit`: `held_payment` releases or cancels the principal according to predefined splits.
-  Choose `security_deposit` when the holder must assess damages and claim an arbitrary partial amount
-  via a `decided amount` clause while returning the unspent remainder to the payer.
-- vs `swap`: `held_payment` is a one-way transfer from payer to payee. Choose `swap` for bilateral or
-  multi-party atomic exchanges where all parties must fund their legs into escrow before simultaneous release.
-- vs `premium_forward`: Choose `premium_forward` for insurance premium collection requiring carrier policy
-  binding conditions, broker commission retention, policy endorsements, and lapse schedules.
-
-### Parameters
-
-- `payer`: The funding party providing the money.
-- `payee`: The beneficiary party receiving the released funds.
-- `amount`: Total amount in minor units of currency `C`.
-- `release`: Condition required to release funds. Supports decision ports (`port <name>`), date deadlines
-  (`at(<date>)`), or disjunctions (`port <name> | at(<date>)`).
-- `fees`: Optional block declaring percentage or fixed fee cuts, e.g. `{ buyer: 1%, seller: 2% }`.
-- `on_cancel`: Optional block defining refund splits if cancelled while funded, e.g. `(funded) { buyer: 90%, seller: 10% }`.
-- `derived_amount`: Optional block declaring machine-derived fees calculated as a percentage of another field.
-- `release_to`: Optional third-party destination for release.
-- `whole_amount`: Optional block enabling single-action funding and release of principal plus on-top fee.
-- `release_action`: Optional custom name for the release action.
-- `whole_fee`: Optional money amount for the whole-amount fee.
-- `reference`: Optional string reference stored on the instance.
-- `upstream`: Optional reference to a parent instrument.
-- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
-- `cancel_charge_bps`: Optional cancellation charge in basis points. Declaring it gives the settlement a
-  quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both,
-  `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee.
-  A zero charge keeps the flow with a zero fee.
-- `cancel_offer_life`: ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`.
-
-- `private_actions`: Suppress automatic aliases. Publish chosen actions with `expose`.
-
-### Decision ports
-
-- `release`: Port deciding release authorization, answered by allowed parties declared in the port.
-
-### Example
-
-```hsx
-program held_payment_example "Held payment example"
-import { held_payment } from "std/money_flows"
-party buyer: person
-party seller: business
-settlement sale = held_payment {
-  payer: buyer
-  payee: seller
-  amount: price: money(SAR)
-  fees { buyer: 1% }
-  on_cancel(funded) { buyer: 100% }
-  release: port confirm_delivery | at(releaseDueAt)
-}
-port confirm_delivery { allowed: [buyer] }
-```
-
-## Declared clauses
-
-- `agent description`
-- `caller parked states`
-- `commit`
-- `deadline`
-- `description`
-- `distinct parties`
-- `due`
-- `event name`
-- `id prefix`
-- `input`
-- `moves`
-- `partitions`
-- `port`
-- `quote`
-- `requires drained`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `release`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `fund_piece_3` | `agent description`, `moves`, `sandbox failure point`, `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`, `sandbox failure point`, `steps`, `summary` |
-| `[release_name]` | `agent description`, `deadline`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `release_on_deadline` | `due`, `moves`, `steps`, `summary` |
-| `cancel` | `agent description`, `deadline`, `moves`, `steps`, `summary` |
-| `quote_cancellation` | `agent description`, `deadline`, `moves`, `quote`, `steps`, `summary` |
-| `cancel` | `agent description`, `commit`, `deadline`, `moves`, `steps`, `summary` |
-| `retain_cancellation_charge` | `agent description`, `moves`, `steps`, `summary` |
-| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `release_piece_2` | `agent description`, `moves`, `steps`, `summary` |
-| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
-| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `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` |
-| `dispute` | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary` |
-| `resume` | `agent description`, `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`, `requires drained`, `steps`, `summary` |
-| `dispute` | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary` |
-| `resume` | `agent description`, `description`, `moves`, `steps`, `summary` |
-
-# instant_transfer
-
-Source: [`std/money_flows/instant_transfer.hsx`](../../../std/money_flows/instant_transfer.hsx)
-
-## Export
-
-`instant_transfer<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | Funding party whose account is debited. |
-| `payee` | `party` | Yes | Recipient party whose account is credited. |
-| `amount` | `money<C>` | Yes | Transfer amount in minor units of currency `C`. |
-| `fees` | `optional<block>` | No | Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee. |
-| `derived_amount` | `optional<block>` | No | Optional block declaring derived platform fees calculated from the transfer amount. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Direct, single-step push transfer from payer to payee with optional tiered or percentage fees.
-
-### Purpose
-
-`instant_transfer` debits a payer and credits a payee immediately in a single execution step.
-It fits peer-to-peer transfers, direct disbursements, instant payouts, wallet reloads, and simple point-of-sale payments.
-
-### Selection guidance
-
-- vs `captured_payment`: `instant_transfer` moves money in one atomic step without prior authorization holds,
-  incremental captures, voids, or post-settlement correction ports. Use `captured_payment` when authorization must precede capture.
-- vs `conditional_disbursement`: `instant_transfer` executes immediately without external decision evidence
-  or cumulative cap tracking. Use `conditional_disbursement` when payments require evidence submission or aggregate milestone caps.
-- vs `held_payment`: `instant_transfer` never holds funds in an intermediary escrow account.
-
-### Parameters
-
-- `payer`: Funding party whose account is debited.
-- `payee`: Recipient party whose account is credited.
-- `amount`: Transfer amount in minor units of currency `C`.
-- `fees`: Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee.
-- `derived_amount`: Optional block declaring derived platform fees calculated from the transfer amount.
-
-### Decision ports
-
-None. Transfers execute immediately upon invocation.
-
-### Example
-
-```hsx
-program instant_transfer_example "Instant transfer example"
-import { instant_transfer } from "std/money_flows"
-party customer: person
-party merchant: business
-settlement transfer = instant_transfer {
-  payer: customer
-  payee: merchant
-  amount: transferAmount: money(SAR)
-  fees {
-    customer: checkoutFee: money(SAR)
-    merchant {
-      tier { from: 0, to: 10000, fee: 1% }
-      tier { from: 10000, fee: highValueFee: money(SAR) }
-    }
-  }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `moves`
-- `partitions`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `pay_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `pay_piece_2` | `agent description`, `moves`, `steps`, `summary` |
-| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |
-
-# metered
-
-Source: [`std/money_flows/metered.hsx`](../../../std/money_flows/metered.hsx)
-
-## Export
-
-`metered`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The customer being billed for usage. |
-| `payee` | `party` | Yes | The service provider receiving usage revenue. |
-| `close_by` | `date` | Yes | Date when the metering period closes, preventing further usage charges. |
-| `rates` | `unknown` | Yes | Block mapping rate metric names to their per-unit money prices committed at period open. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Usage-based billing against a committed rate card over an open period until a stored close date.
-
-### Purpose
-
-`metered` bills customers for variable resource consumption such as API requests, compute hours,
-storage gigabytes, or utility consumption. The rate card is fixed when the period opens, and individual
-usage events are charged incrementally until the billing period closes on `close_by`.
-
-### Selection guidance
-
-- vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
-  rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
-  with predetermined amounts or installments.
-
-### Parameters
-
-- `payer`: The customer being billed for usage.
-- `payee`: The service provider receiving usage revenue.
-- `close_by`: Date when the metering period closes, preventing further usage charges.
-- `rates`: Block mapping rate metric names to their per-unit money prices committed at period open.
-
-### Decision ports
-
-None. Charges are driven by caller billing actions and period closure.
-
-### Example
-
-```hsx
-program metered_example "Metered example"
-import { metered } from "std/money_flows"
-party customer: business
-party provider: business
-settlement usage = metered {
-  payer: customer
-  payee: provider
-  close_by: periodEnd
-  rates {
-    api_call: callRate: money(SAR)
-    storage_gib: storageRate: money(SAR)
-  }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `moves`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `steps`, `summary` |
-| `charge_[item]` | `agent description`, `moves`, `steps`, `summary` |
-| `close_period` | `due`, `steps`, `summary` |
-
-# pooled_split
-
-Source: [`std/money_flows/pooled_split.hsx`](../../../std/money_flows/pooled_split.hsx)
-
-## Export
-
-`pooled_split<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The funding party providing the pooled amount. |
-| `amount` | `money<C>` | Yes | Total pooled amount in minor units of currency `C`. |
-| `payout_due` | `date` | Yes | Stored payout date when the pool distributes to all recipients. |
-| `split` | `block` | Yes | Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Fixed multi-recipient revenue or period pool funded share-by-share and released automatically on a due date.
-
-### Purpose
-
-`pooled_split` pools a period total from one payer and splits it across a fixed roster of recipients
-according to predetermined percentage shares (with integer division remainder assigned to `remainder_to`).
-Callers fund the pool share-by-share, and payouts disburse automatically to each recipient on `payout_due`.
-
-### Selection guidance
-
-- vs `weighted_distribution`: `pooled_split` hardcodes a fixed set of recipients and static percentage shares
-  directly in the contract. `weighted_distribution` handles dynamic recipient counts where arbitrary weights
-  are recorded as child records and frozen via a snapshot port before distribution.
-- vs `settlement_batch`: `settlement_batch` aggregates multiple payments from many sources into one net payout.
-  `pooled_split` takes one period total from one payer and partitions it out to multiple recipients.
-
-### Parameters
-
-- `payer`: The funding party providing the pooled amount.
-- `amount`: Total pooled amount in minor units of currency `C`.
-- `payout_due`: Stored payout date when the pool distributes to all recipients.
-- `split`: Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders.
-
-### Decision ports
-
-None. Payout distribution triggers automatically from the stored `payout_due` date.
-
-### Example
-
-```hsx
-program pooled_split_example "Pooled split example"
-import { pooled_split } from "std/money_flows"
-party payer: business
-party first_recipient: business
-party second_recipient: business
-settlement pool = pooled_split {
-  payer: payer
-  amount: poolAmount: money(SAR)
-  payout_due: payoutDueAt
-  split {
-    first_recipient: 60%
-    second_recipient: 40%
-    remainder_to: first_recipient
-  }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `id prefix`
-- `moves`
-- `partitions`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `fund_share_[index]` | `agent description`, `moves`, `steps`, `summary` |
-| `distribute_share_[index]` | `due`, `moves`, `steps`, `summary` |
-
-# premium_forward
-
-Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium_forward.hsx)
-
-## Export
-
-`premium_forward<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The policyholder paying the insurance premium. |
-| `carrier` | `party` | Yes | The insurance carrier underwriting the policy. |
-| `amount` | `money<C>` | Yes | Total gross premium in minor units of currency `C`. |
-| `bind` | `condition` | Yes | Condition port triggering policy binding and premium forwarding. |
-| `commission` | `percent` | Yes | Platform commission percentage retained from the gross premium. |
-| `policy_ref` | `optional<text>` | No | Optional policy identifier string. |
-| `renewal_due` | `optional<date>` | No | Optional date anchor when the policy is due for renewal. |
-| `endorsement` | `optional<condition>` | No | Optional condition port for recording policy endorsements. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Insurance premium escrow holding customer funds until policy binding, then partitioning net carrier premium and commission.
-
-### Purpose
-
-`premium_forward` manages insurance premium collection, broker commission retention, and carrier remittance.
-A policyholder funds the premium into dedicated escrow. The funds remain held until the policy binds via the `bind` port.
-Upon binding, the gross premium is automatically partitioned: the platform fee/commission is retained, and the net
-balance forwards to the carrier. It also supports policy endorsements and renewal schedules.
-
-### Selection guidance
-
-- vs `held_payment`: `premium_forward` is tailored for insurance lifecycles, featuring automatic commission splits
-  upon binding and policy endorsement tracking. `held_payment` is general commercial escrow without insurance
-  underwriting binding semantics or gross-to-net fee partitioning.
-- vs `conditional_disbursement`: `premium_forward` collects and forwards inbound policy premiums to carriers.
-  `conditional_disbursement` pays outbound claim settlements to claimants against stored evidence.
-
-### Parameters
-
-- `payer`: The policyholder paying the insurance premium.
-- `carrier`: The insurance carrier underwriting the policy.
-- `amount`: Total gross premium in minor units of currency `C`.
-- `bind`: Condition port triggering policy binding and premium forwarding.
-- `commission`: Platform commission percentage retained from the gross premium.
-- `policy_ref`: Optional policy identifier string.
-- `renewal_due`: Optional date anchor when the policy is due for renewal.
-- `endorsement`: Optional condition port for recording policy endorsements.
-
-### Decision ports
-
-- `bind`: Port authorizing policy binding, triggering carrier payout and commission retention.
-- `endorsement`: Port allowing carrier endorsement evidence to be recorded.
-
-### Example
-
-```hsx
-program premium_forward_example "Premium forward example"
-import { premium_forward } from "std/money_flows"
-party policyholder: person
-party carrier: business
-settlement premium = premium_forward {
-  payer: policyholder
-  carrier: carrier
-  amount: premiumAmount: money(SAR)
-  commission: 2%
-  bind: port bind_policy
-  policy_ref: policyReference
-  renewal_due: renewalDueAt
-  endorsement: port record_endorsement
-}
-port bind_policy { allowed: [policyholder, carrier] }
-port record_endorsement {
-  allowed: [carrier]
-  shape: { evidenceReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `description`
-- `due`
-- `input`
-- `moves`
-- `partitions`
-- `port`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `bind`
-- `endorsement`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `steps`, `summary` |
-| `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `[bind]` | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `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`, `input`, `port`, `steps`, `summary` |
-| `lapse` | `due`, `steps`, `summary` |
-
-# reconciled_payout
-
-Source: [`std/money_flows/reconciled_payout.hsx`](../../../std/money_flows/reconciled_payout.hsx)
-
-## Export
-
-`reconciled_payout<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The funding party providing the payout. |
-| `beneficiary` | `party` | Yes | The beneficiary party receiving the external payout. |
-| `amount` | `money<C>` | Yes | Instructed payout amount in minor units of currency `C`. |
-| `beneficiary_ref` | `text` | Yes | Registered external beneficiary ID for bank routing. |
-| `settle_by` | `date` | Yes | Cut-off date when unmatched expectation amounts become formal break records. |
-| `matched_within` | `integer` | Yes | Match tolerance window in basis points or minor units. |
-| `matched_ceiling` | `integer` | Yes | Maximum acceptable tolerance ceiling between instructed amount and settled debit. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Outbound bank payout instruction with end-to-end reconciliation against external bank statement feeds.
-
-### Purpose
-
-`reconciled_payout` manages high-assurance payouts to external suppliers, partners, or customers where payment
-is not complete until confirmed by bank statement data. An instruction is dispatched to the beneficiary and an expectation
-record is opened. Incoming statement debit lines match against the expectation within configurable tolerance thresholds
-(`matched_within`, `matched_ceiling`). If the statement debit does not match before `settle_by`, a formal break row is raised.
-
-### Selection guidance
-
-- vs `settlement_batch`: `reconciled_payout` executes and reconciles an individual bank payout instruction.
-  `settlement_batch` aggregates periodic captures, fees, and signed adjustments to calculate a net payable batch.
-- vs `instant_transfer`: `instant_transfer` executes an immediate internal ledger transfer between platform accounts.
-  `reconciled_payout` dispatches funds across external banking rails with reconciliation tolerances and break tracking.
-
-### Parameters
-
-- `payer`: The funding party providing the payout.
-- `beneficiary`: The beneficiary party receiving the external payout.
-- `amount`: Instructed payout amount in minor units of currency `C`.
-- `beneficiary_ref`: Registered external beneficiary ID for bank routing.
-- `settle_by`: Cut-off date when unmatched expectation amounts become formal break records.
-- `matched_within`: Match tolerance window in basis points or minor units.
-- `matched_ceiling`: Maximum acceptable tolerance ceiling between instructed amount and settled debit.
-
-### Decision ports
-
-None. Payout dispatch and settlement matching follow the declared schedule, bank statement lines, and tolerance rules.
-
-### Example
-
-```hsx
-program reconciled_payout_example "Reconciled payout example"
-import { reconciled_payout } from "std/money_flows"
-party treasury: business
-party supplier: business
-settlement supplier_payout = reconciled_payout {
-  payer: treasury
-  beneficiary: supplier
-  amount: netPayable: money(SAR)
-  beneficiary_ref: supplierBeneficiaryId
-  settle_by: settleBy
-  matched_within: 100
-  matched_ceiling: 500
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `dials`
-- `due`
-- `id prefix`
-- `moves`
-- `payout`
-- `reconcile`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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` |
-
-# rotating_pool
-
-Source: [`std/money_flows/rotating_pool.hsx`](../../../std/money_flows/rotating_pool.hsx)
-
-## Export
-
-`rotating_pool<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `members` | `optional<list<party>>` | No | List of parties belonging to the rotating group. |
-| `contribution` | `money<C>` | Yes | Fixed contribution amount required from each member per cycle in minor units of currency `C`. |
-| `count` | `integer` | Yes | Total number of cycles in the rotation (matching the member count). |
-| `every` | `optional<text>` | No | Recurrence interval between contribution cycles (e.g. `"P30D"`). |
-| `first_due` | `date` | Yes | Due date for the first cycle's contribution. |
-| `payout_order` | `optional<list<party>>` | No | Ordered list of member parties defining the cycle payout sequence. |
-| `default_policy` | `optional<text>` | No | Policy for handling missed contributions (`due_condition`). |
-| `guarantee_policy` | `optional<text>` | No | Policy for backing defaulted contributions (`funded_only`). |
-| `guarantor` | `optional<party>` | No | Optional guarantor party covering member defaults. |
-| `exit_policy` | `optional<text>` | No | Policy governing member departures (`before_activation_only`). |
-| `memo` | `optional<text>` | No | Optional memo text stored on the pool. |
-| `membership` | `optional<block>` | No | Optional custom membership configuration block. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Rotating savings and credit association (ROSCA) pool where members contribute fixed amounts and take turns receiving the pot.
-
-### Purpose
-
-`rotating_pool` coordinates peer savings circles, chit funds, tandas, and committee savings groups.
-A fixed group of members contributes an identical contribution amount each cycle. In each cycle, one designated member
-receives the entire pooled pot according to a predefined `payout_order` until all members have taken their turn.
-
-### Selection guidance
-
-- vs `threshold_pool`: `rotating_pool` coordinates recurring multi-party peer savings with rotating payouts.
-  `threshold_pool` is all-or-nothing capital accumulation toward a single threshold for one beneficiary.
-- vs `scheduled`: `scheduled` coordinates a single payer to a single payee. `rotating_pool` orchestrates
-  a closed circular group of members taking sequential turns.
-
-### Parameters
-
-- `members`: List of parties belonging to the rotating group.
-- `contribution`: Fixed contribution amount required from each member per cycle in minor units of currency `C`.
-- `count`: Total number of cycles in the rotation (matching the member count).
-- `every`: Recurrence interval between contribution cycles (e.g. `"P30D"`).
-- `first_due`: Due date for the first cycle's contribution.
-- `payout_order`: Ordered list of member parties defining the cycle payout sequence.
-- `default_policy`: Policy for handling missed contributions (`due_condition`).
-- `guarantee_policy`: Policy for backing defaulted contributions (`funded_only`).
-- `guarantor`: Optional guarantor party covering member defaults.
-- `exit_policy`: Policy governing member departures (`before_activation_only`).
-- `memo`: Optional memo text stored on the pool.
-- `membership`: Optional custom membership configuration block.
-
-### Decision ports
-
-None. Cycle advancement and pot payouts follow the declared schedule and membership actions.
-
-### Example
-
-```hsx
-program rotating_pool_example "Rotating pool example"
-import { rotating_pool } from "std/money_flows"
-party member_a: person
-party member_b: person
-party member_c: person
-party guarantor: business
-settlement pool = rotating_pool {
-  members: [member_a, member_b, member_c]
-  contribution: contributionAmount: money(SAR)
-  count: 3
-  every: P30D
-  first_due: firstContributionAt
-  payout_order: [member_b, member_c, member_a]
-  default_policy: due_condition
-  guarantee_policy: funded_only
-  guarantor: guarantor
-  exit_policy: before_activation_only
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `aggregate invariants`
-- `caller parked states`
-- `description`
-- `due`
-- `examples`
-- `id prefix`
-- `moves`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-- `unique`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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` |
-| `ready_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
-| `advance_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
-| `contribute_cycle_[cycle]` | `due`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `mark_default_cycle_[cycle]` | `due`, `moves`, `steps`, `summary` |
-| `guarantee_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
-| `pay_cycle_[cycle]` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `pay_guaranteed_cycle_[cycle]` | `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/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx)
-
-## Export
-
-`scheduled<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The paying party (or repayment source). |
-| `payee` | `party` | Yes | The beneficiary party receiving installment funds. |
-| `amount` | `money<C>` | Yes | Total amount to partition into installments or recurring charge amount in minor units of currency `C`. |
-| `count` | `optional<integer>` | No | Optional number of installments for installment or obligation modes. |
-| `every` | `text` | Yes | Recurrence cadence duration string (e.g. `"P30D"`, `"P1M"`). |
-| `first_due` | `date` | Yes | Stored date anchor for the first installment or charge. |
-| `mode` | `optional<text>` | No | Optional mode selector (`obligation`). Omit for standard installment plans. |
-| `debtor` | `optional<party>` | No | Optional debtor party when distinct from the payment source in obligation mode. |
-| `advance_to` | `optional<party>` | No | Optional third-party receiving upfront advance disbursements in obligation mode. |
-| `until` | `optional<condition>` | No | Optional condition port triggering cancellation of recurring subscription runs. |
-| `month_end` | `optional<text>` | No | Optional handling policy for calendar month-end adjustments. |
-| `period_liability` | `optional<text>` | No | Optional liability policy for billing periods. |
-| `termination_drain` | `optional<text>` | No | Optional policy for draining balances on early termination. |
-| `mandate` | `optional<condition>` | No | Optional condition port supplying formal debit mandate evidence. |
-| `derived_amount` | `optional<unknown>` | No | Optional calculated markup or fee rules. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Calendar-anchored payments supporting fixed installment plans, recurring subscriptions, or debt obligations.
-
-### Purpose
-
-`scheduled` automates time-anchored payment series between one payer and one payee.
-It supports three modes:
-
-1. Installment plan: Partitions a fixed total amount into `count` installments, each collected on its own stored date.
-2. Open recurring subscription: Charges a recurring amount on an interval `every` until an `until` port fires.
-3. Debt obligation: Manages legally binding multi-installment debt with delinquency tracking, mandate evidence, and child payment records.
-
-### Selection guidance
-
-- vs `metered`: `scheduled` executes calendar-based recurring charges or fixed installment plans.
-  `metered` bills variable usage per event based on a committed rate card.
-- vs `rotating_pool`: `scheduled` coordinates one payer to one payee on a calendar.
-  `rotating_pool` coordinates a multi-party peer circle where members rotate turns receiving the entire pot.
-
-### Parameters
-
-- `payer`: The paying party (or repayment source).
-- `payee`: The beneficiary party receiving installment funds.
-- `amount`: Total amount to partition into installments or recurring charge amount in minor units of currency `C`.
-- `count`: Optional number of installments for installment or obligation modes.
-- `every`: Recurrence cadence duration string (e.g. `"P30D"`, `"P1M"`).
-- `first_due`: Stored date anchor for the first installment or charge.
-- `mode`: Optional mode selector (`obligation`). Omit for standard installment plans.
-- `debtor`: Optional debtor party when distinct from the payment source in obligation mode.
-- `advance_to`: Optional third-party receiving upfront advance disbursements in obligation mode.
-- `until`: Optional condition port triggering cancellation of recurring subscription runs.
-- `month_end`: Optional handling policy for calendar month-end adjustments.
-- `period_liability`: Optional liability policy for billing periods.
-- `termination_drain`: Optional policy for draining balances on early termination.
-- `mandate`: Optional condition port supplying formal debit mandate evidence.
-- `derived_amount`: Optional calculated markup or fee rules.
-
-### Decision ports
-
-- `until`: Port terminating recurring subscriptions.
-- `mandate`: Port supplying mandate verification evidence for direct debit obligations.
-
-### Example
-
-```hsx
-program scheduled_example "Scheduled example"
-import { scheduled } from "std/money_flows"
-party payer: business
-party payee: business
-settlement installments = scheduled {
-  payer: payer
-  payee: payee
-  amount: totalAmount: money(SAR)
-  count: 3
-  every: P30D
-  first_due: firstDueAt
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `aggregate invariants`
-- `capture input`
-- `description`
-- `due`
-- `input`
-- `moves`
-- `partitions`
-- `port`
-- `sandbox failure point`
-- `sets at`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `until`
-- `mandate`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `steps`, `summary` |
-| `pay_installment_[i]` | `due`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `approve` | `agent description`, `steps`, `summary` |
-| `advance` | `agent description`, `moves`, `steps`, `summary` |
-| `collect_installment_[i]` | `due`, `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`, `sandbox failure point`, `steps`, `summary` |
-| `[until]` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
-
-# security_deposit
-
-Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/security_deposit.hsx)
-
-## Export
-
-`security_deposit<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | The customer providing the deposit collateral. |
-| `holder` | `party` | Yes | The merchant or owner holding the deposit rights. |
-| `amount` | `money<C>` | Yes | Total reserved deposit amount in minor units of currency `C`. |
-| `claim` | `optional<condition>` | No | Optional condition port triggering a damage claim. |
-| `return` | `optional<condition>` | No | Optional condition port triggering full return of the deposit. |
-| `claim_amount` | `optional<block>` | No | Optional block defining partial claim logic (`field`, `bound`, `remainder`). |
-| `deadline` | `optional<date>` | No | Optional stored date anchor for automatic deposit release or expiry. |
-| `claim_to` | `optional<party>` | No | Optional alternate destination for claimed funds. |
-| `return_to` | `optional<party>` | No | Optional alternate destination for returned funds. |
-| `memo` | `optional<text>` | No | Optional memo text stored on the deposit record. |
-| `claim_input` | `optional<block>` | No | Optional custom input schema for the claim action. |
-| `claim_capture` | `optional<block>` | No | Optional capture mappings for claim evidence. |
-| `fund_failure_point` | `optional<text>` | No | Optional configuration for deposit funding failure. |
-| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Collateral deposit reserved against a payer's account in favor of a holder, returned in full or claimed against damages.
-
-### Purpose
-
-`security_deposit` reserves collateral funds for vehicle rentals, property leasing, equipment hire, and security bonds.
-Funds remain held until the rental or lease concludes. The holder can either return the deposit in full
-or assess damages, claim a decided partial amount, and return the exact unspent remainder.
-
-### Selection guidance
-
-- vs `held_payment`: `security_deposit` holds collateral where the standard outcome is returning 100% of the funds
-  to the payer, and claims are partial damage assessments. `held_payment` holds payment consideration where the
-  standard outcome is releasing 100% of the funds to the payee upon delivery.
-- vs `cancellable_booking`: `cancellable_booking` holds booking fees and applies time-based cancellation penalties.
-  `security_deposit` holds damage collateral and supports arbitrary damage claims with remainder refund.
-
-### Parameters
-
-- `payer`: The customer providing the deposit collateral.
-- `holder`: The merchant or owner holding the deposit rights.
-- `amount`: Total reserved deposit amount in minor units of currency `C`.
-- `claim`: Optional condition port triggering a damage claim.
-- `return`: Optional condition port triggering full return of the deposit.
-- `claim_amount`: Optional block defining partial claim logic (`field`, `bound`, `remainder`).
-- `deadline`: Optional stored date anchor for automatic deposit release or expiry.
-- `claim_to`: Optional alternate destination for claimed funds.
-- `return_to`: Optional alternate destination for returned funds.
-- `memo`: Optional memo text stored on the deposit record.
-- `claim_input`: Optional custom input schema for the claim action.
-- `claim_capture`: Optional capture mappings for claim evidence.
-- `fund_failure_point`: Optional configuration for deposit funding failure.
-- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
-
-### Decision ports
-
-- `claim`: Port permitting the holder to submit a damage claim.
-- `return`: Port permitting the holder to return the deposit to the payer.
-
-### Example
-
-```hsx
-program deposit_example "Deposit example"
-import { security_deposit } from "std/money_flows"
-party renter: person
-party owner: business
-settlement security_deposit = security_deposit {
-  payer: renter
-  holder: owner
-  amount: depositAmount: money(SAR)
-  claim: port assess_damage
-  claim_amount: decided {
-    field: damageAmount
-    bound: depositAmount
-    remainder: return
-  }
-  return: port return_deposit
-}
-port assess_damage {
-  allowed: [owner]
-  shape: { damageAmount: money(SAR), evidence: text }
-}
-port return_deposit { allowed: [owner] }
-```
-
-## Declared clauses
-
-- `agent description`
-- `caller parked states`
-- `capture input`
-- `deadline`
-- `decided amount`
-- `description`
-- `dials`
-- `distinct parties`
-- `due`
-- `id prefix`
-- `input`
-- `moves`
-- `port`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `claim`
-- `return`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `place_deposit` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `[claim_name]` | `agent description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `[return_name]` | `agent description`, `capture input`, `input`, `moves`, `port`, `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`, `sandbox failure point`, `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/money_flows/settlement_batch.hsx`](../../../std/money_flows/settlement_batch.hsx)
-
-## Export
-
-`settlement_batch<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `settlement_account` | `party` | Yes | The source clearing account holding captured funds and paying the batch. |
-| `source_capture_refs` | `text` | Yes | Binding name for gross capture references included in the batch. |
-| `fee_entries` | `text` | Yes | Binding name for fee deductions applied to the batch. |
-| `external_reversal_offsets` | `text` | Yes | Binding name for reversal adjustments applied to the batch. |
-| `close_trigger` | `date` | Yes | Date when the batch closes and ceases accepting new transaction entries. |
-| `payout_destination` | `party` | Yes | The merchant or partner account receiving the net payout. |
-| `negative_position` | `text` | Yes | Policy when calculated net payable is zero or negative (`reject`). |
-| `payout_acknowledgement` | `condition` | Yes | Condition port confirming bank receipt of the payout. |
-| `payout_beneficiary_ref` | `text` | Yes | Beneficiary identifier for external bank dispatch. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Periodic aggregation of capture lineage, fee entries, and adjustments into a single net calculated payout.
-
-### Purpose
-
-`settlement_batch` settles merchant balances, marketplace vendor earnings, and partner clearing accounts.
-Individual payment captures, platform fees, and reversal adjustments accumulate into an open batch over a period.
-On `close_trigger`, the batch freezes. The platform calculates the signed net payable from gross captures plus credit
-adjustments minus debit adjustments. If positive, an outbound bank payout is instructed and acknowledged.
-
-### Selection guidance
-
-- vs `reconciled_payout`: `settlement_batch` aggregates multiple transactions and adjustments over a billing cycle
-  to compute a single net payable. `reconciled_payout` manages bank instruction dispatch and statement line reconciliation
-  for an individual payout amount.
-- vs `weighted_distribution`: `settlement_batch` consolidates many inbound transactions into one net outbound payout.
-  `weighted_distribution` splits one funding pool into many recipient payouts.
-
-### Parameters
-
-- `settlement_account`: The source clearing account holding captured funds and paying the batch.
-- `source_capture_refs`: Binding name for gross capture references included in the batch.
-- `fee_entries`: Binding name for fee deductions applied to the batch.
-- `external_reversal_offsets`: Binding name for reversal adjustments applied to the batch.
-- `close_trigger`: Date when the batch closes and ceases accepting new transaction entries.
-- `payout_destination`: The merchant or partner account receiving the net payout.
-- `negative_position`: Policy when calculated net payable is zero or negative (`reject`).
-- `payout_acknowledgement`: Condition port confirming bank receipt of the payout.
-- `payout_beneficiary_ref`: Beneficiary identifier for external bank dispatch.
-
-### Decision ports
-
-- `payout_acknowledgement`: Port recording external bank or partner receipt confirmation.
-
-### Example
-
-```hsx
-program settlement_batch_example "Settlement batch example"
-import { settlement_batch } from "std/money_flows"
-party settlement_account: business
-party payout_destination: business
-settlement batch = settlement_batch {
-  settlement_account: settlement_account
-  source_capture_refs: captureReference
-  fee_entries: feeReference
-  external_reversal_offsets: reversalReference
-  close_trigger: closeAt
-  payout_destination: payout_destination
-  negative_position: reject
-  payout_acknowledgement: port acknowledge_payout
-  payout_beneficiary_ref: payoutBeneficiaryId
-}
-port acknowledge_payout {
-  allowed: [payout_destination]
-  shape: { acknowledgementReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `description`
-- `due`
-- `id prefix`
-- `input`
-- `moves`
-- `payout`
-- `port`
-- `reconcile`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `payout_acknowledgement`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `close` | `due`, `moves`, `steps`, `summary` |
-| `calculate` | `agent description`, `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/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
-
-## Export
-
-`swap<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `between` | `list<party>` | Yes | List containing exactly two trade participant parties (`[side_a, side_b]`). |
-| `amounts` | `block` | Yes | Block declaring the principal money amounts for each party. |
-| `fees` | `block` | Yes | Block declaring the platform fee money amounts for each party. |
-| `release` | `condition` | Yes | Condition port required to execute the atomic swap release. |
-| `dispute` | `condition` | Yes | Condition port triggering unwinding and refunding of both trade legs. |
-| `side_names` | `optional<block>` | No | Optional custom naming block for the two sides (`first`, `second`). |
-| `lifecycle_state_order` | `optional<list<text>>` | No | Optional custom ordering for lifecycle states. |
-| `action_bindings` | `optional<block>` | No | Optional custom action names. |
-| `parked_states` | `optional<block>` | No | Optional configuration for parked states. |
-| `fixed_prefix` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Atomic two-sided trade between two parties where neither leg settles alone.
-
-### Purpose
-
-`swap` executes atomic delivery-versus-payment (DvP) or payment-versus-payment (PvP) exchanges between two named parties.
-Both sides fund their declared principal amounts and platform fees into a shared escrow. The exchange settles atomically
-upon triggering the `release` condition port, paying each party the other's funded amount. If a `dispute` occurs,
-both legs unwind and refund simultaneously. Half-funded or half-released states cannot occur.
-
-### Selection guidance
-
-- vs `held_payment`: `swap` is a bilateral trade where both sides must deposit funds into escrow and receive each other's
-  disbursements simultaneously. `held_payment` is unilateral escrow where a single payer funds a payment held for a payee.
-- vs `instant_transfer`: `instant_transfer` executes an immediate one-way transfer. `swap` coordinates two reciprocal transfers
-  held atomically in escrow until release confirmation.
-
-### Parameters
-
-- `between`: List containing exactly two trade participant parties (`[side_a, side_b]`).
-- `amounts`: Block declaring the principal money amounts for each party.
-- `fees`: Block declaring the platform fee money amounts for each party.
-- `release`: Condition port required to execute the atomic swap release.
-- `dispute`: Condition port triggering unwinding and refunding of both trade legs.
-- `side_names`: Optional custom naming block for the two sides (`first`, `second`).
-- `lifecycle_state_order`: Optional custom ordering for lifecycle states.
-- `action_bindings`: Optional custom action names.
-- `parked_states`: Optional configuration for parked states.
-- `fixed_prefix`: Optional custom prefix for generated instrument IDs.
-
-### Decision ports
-
-- `release`: Port authorizing atomic settlement of both trade legs.
-- `dispute`: Port triggering atomic cancellation and refund of both parties.
-
-### Example
-
-```hsx
-program swap_example "Swap example"
-import { swap } from "std/money_flows"
-party buyer: business
-party seller: business
-settlement exchange = swap {
-  between: [buyer, seller]
-  amounts {
-    buyer: buyerAmount: money(SAR)
-    seller: sellerAmount: money(SAR)
-  }
-  fees {
-    buyer: buyerFee: money(SAR)
-    seller: sellerFee: money(SAR)
-  }
-  release: port release_exchange
-  dispute: port dispute_exchange within P7D
-}
-port release_exchange { allowed: [buyer, seller] }
-port dispute_exchange { allowed: [buyer, seller] }
-```
-
-## Declared clauses
-
-- `agent description`
-- `caller parked states`
-- `capture input`
-- `deadline`
-- `description`
-- `distinct parties`
-- `due`
-- `event name`
-- `id prefix`
-- `input`
-- `moves`
-- `port`
-- `public action`
-- `sandbox failure point`
-- `sets at`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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`, `capture input`, `deadline`, `input`, `moves`, `port`, `public action`, `steps`, `summary` |
-| `fund` | `agent description`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary` |
-| `post` | `due`, `moves`, `steps`, `summary` |
-| `release` | `agent description`, `moves`, `port`, `public action`, `sandbox failure point`, `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`, `capture input`, `deadline`, `event name`, `input`, `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/money_flows/threshold_pool.hsx`](../../../std/money_flows/threshold_pool.hsx)
-
-## Export
-
-`threshold_pool<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `contributor` | `optional<party>` | No | The party representing individual contributors. |
-| `beneficiary` | `optional<party>` | No | The beneficiary party receiving the settled pool if the target is met. |
-| `target` | `money<C>` | Yes | Total target funding threshold in minor units of currency `C`. |
-| `commitment` | `money<C>` | Yes | Binding name for individual contributor commitment amounts. |
-| `max_contributors` | `optional<integer>` | No | Optional maximum count of admitted contributors. |
-| `close_by` | `date` | Yes | Stored date deadline by which the target must be met. |
-| `close_policy` | `optional<text>` | No | Policy determining pool close behavior (`threshold`). |
-| `overfund_policy` | `optional<text>` | No | Policy on commitments exceeding the target (`reject`). |
-| `cancel_policy` | `optional<text>` | No | Contributor withdrawal policy before close (`before_close`). |
-| `fail_policy` | `optional<text>` | No | Refund policy if the pool fails to hit target (`whole_commitment_refund`). |
-| `beneficiary_account` | `optional<account<C>>` | No | Optional direct account reference for the beneficiary. |
-| `memo` | `optional<text>` | No | Optional memo text stored on the pool. |
-| `contribution_instrument` | `optional<block>` | No | Optional custom contribution child instrument block. |
-| `wording` | `optional<block>` | No | Optional custom UI wording block. |
-| `funding_join` | `optional<block>` | No | funding_join configures the flat contribution-instrument mode for a priced obligation. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-All-or-nothing capital accumulation pool collecting commitments toward a target amount before a close deadline.
-
-### Purpose
-
-`threshold_pool` powers all-or-nothing crowdfunding, capital calls, collective purchasing, and consortium rounds.
-Multiple contributors pledge commitments toward a monetary `target`. Commitments sit in escrow until the pool
-reaches the target before `close_by` (activating and settling funds to the beneficiary), or fails (triggering full refunds).
-
-### Selection guidance
-
-- vs `rotating_pool`: `threshold_pool` is all-or-nothing fundraising where many contributors fund a single beneficiary.
-  `rotating_pool` is a peer savings circle where members contribute identically in each cycle and rotate who receives the pot.
-- vs `weighted_distribution`: `threshold_pool` pools funds inward from many contributors to one beneficiary.
-  `weighted_distribution` pays funds outward from one source pool to many weighted recipients.
-
-### Parameters
-
-- `contributor`: The party representing individual contributors.
-- `beneficiary`: The beneficiary party receiving the settled pool if the target is met.
-- `target`: Total target funding threshold in minor units of currency `C`.
-- `commitment`: Binding name for individual contributor commitment amounts.
-- `max_contributors`: Optional maximum count of admitted contributors.
-- `close_by`: Stored date deadline by which the target must be met.
-- `close_policy`: Policy determining pool close behavior (`threshold`).
-- `overfund_policy`: Policy on commitments exceeding the target (`reject`).
-- `cancel_policy`: Contributor withdrawal policy before close (`before_close`).
-- `fail_policy`: Refund policy if the pool fails to hit target (`whole_commitment_refund`).
-- `beneficiary_account`: Optional direct account reference for the beneficiary.
-- `memo`: Optional memo text stored on the pool.
-- `contribution_instrument`: Optional custom contribution child instrument block.
-- `wording`: Optional custom UI wording block.
-
-### Decision ports
-
-None. Lifecycle transitions (`activate`, `fail`, `close`) are driven by target threshold evaluation and the `close_by` date.
-
-### Example
-
-```hsx
-program capital_pool_example "Capital pool example"
-import { threshold_pool } from "std/money_flows"
-party contributor: person
-party company: business
-settlement round = threshold_pool {
-  contributor: contributor
-  beneficiary: company
-  target: targetAmount: money(SAR)
-  commitment: commitmentAmount: money(SAR)
-  max_contributors: 100
-  close_by: closeBy
-  close_policy: threshold
-  overfund_policy: reject
-  cancel_policy: before_close
-  fail_policy: whole_commitment_refund
-}
-```
-
-### Funding join
-
-funding_join configures the flat contribution-instrument mode for a priced
-obligation. Opening freezes minimum ticket, investor cap, profit and schedule
-terms. Closing binds the obligation, freezes committed ticket identities and
-moves the principal once into its funding account. A ticket's engine-owned
-collection action has no independent payment or clock trigger.
-
-## Declared clauses
-
-- `agent description`
-- `aggregate invariants`
-- `caller parked states`
-- `description`
-- `due`
-- `examples`
-- `funding`
-- `id prefix`
-- `input`
-- `moves`
-- `steps`
-- `summary`
-- `title`
-- `updates`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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`, `funding`, `input`, `moves`, `steps`, `updates` |
-
-# weighted_distribution
-
-Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/weighted_distribution.hsx)
-
-## Export
-
-`weighted_distribution<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `source` | `optional<party>` | No | The funding party providing the distribution pool. |
-| `recipient` | `optional<party>` | No | The party representing entitled recipients. |
-| `amount` | `optional<money<C>>` | No | Total distribution pool in minor units of currency `C`. |
-| `record_at` | `optional<date>` | No | Date when entitlement eligibility is established. |
-| `weight` | `optional<money<C>>` | No | Binding name for individual recipient weight amounts. |
-| `max_recipients` | `optional<integer>` | No | Exact number of entitlement rows required before snapshotting. |
-| `snapshot` | `optional<condition>` | No | Port freezing the entitlement set against stored decision evidence. |
-| `rounding_policy` | `optional<text>` | No | Mathematical rounding policy (`largest_remainder`). |
-| `withholding_policy` | `optional<text>` | No | Tax or withholding policy (`refuse`). |
-| `correction_policy` | `optional<text>` | No | Error correction policy (`new_distribution`). |
-| `flat` | `optional<block>` | No | Optional flat distribution configuration block. |
-| `receipts` | `optional<block>` | No | receipts selects repeated distributions from immutable allocation receipts. |
-| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-Frozen largest-remainder distribution splitting one pool across dynamic recipients by recorded weights.
-
-### Purpose
-
-`weighted_distribution` distributes dividend pools, creator royalties, liquidation proceeds, and investment returns.
-Child entitlement rows are recorded for each recipient with their respective weight. Once all recipients are recorded,
-an evidence-backed snapshot freezes the entitlement set. Each recipient is then paid their exact largest-remainder
-share such that all payouts sum exactly to `amount` without rounding leaks.
-
-### Selection guidance
-
-- vs `pooled_split`: `weighted_distribution` handles dynamic recipient rosters recorded as child rows and frozen
-  via snapshot. `pooled_split` hardcodes a fixed set of recipients and static percentages at definition time.
-- vs `settlement_batch`: `weighted_distribution` splits one funding pool out to many recipients.
-  `settlement_batch` aggregates many inbound charges and adjustments into a single net payout.
-
-### Parameters
-
-- `source`: The funding party providing the distribution pool.
-- `recipient`: The party representing entitled recipients.
-- `amount`: Total distribution pool in minor units of currency `C`.
-- `record_at`: Date when entitlement eligibility is established.
-- `weight`: Binding name for individual recipient weight amounts.
-- `max_recipients`: Exact number of entitlement rows required before snapshotting.
-- `snapshot`: Port freezing the entitlement set against stored decision evidence.
-- `rounding_policy`: Mathematical rounding policy (`largest_remainder`).
-- `withholding_policy`: Tax or withholding policy (`refuse`).
-- `correction_policy`: Error correction policy (`new_distribution`).
-- `flat`: Optional flat distribution configuration block.
-- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
-
-### Decision ports
-
-- `snapshot`: Port freezing the entitlement set with an evidence reference, preventing further entries.
-
-### Example
-
-```hsx
-program weighted_distribution_example "Weighted distribution example"
-import { weighted_distribution } from "std/money_flows"
-party distribution_source: business
-party recipient: business
-settlement proceeds = weighted_distribution {
-  source: distribution_source
-  recipient: recipient
-  amount: distributableAmount: money(SAR)
-  weight: entitlementWeight: money(SAR)
-  max_recipients: 12
-  record_at: recordAt
-  snapshot: port snapshot_entitlements
-  rounding_policy: largest_remainder
-  withholding_policy: refuse
-  correction_policy: new_distribution
-}
-port snapshot_entitlements {
-  allowed: [distribution_source]
-  shape: { evidenceReference: text }
-}
-```
-
-### Receipt-backed distributions
-
-receipts selects repeated distributions from immutable allocation receipts.
-It names round, receipt, path, mode (cash or loss), fee_bps and vat_bps.
-The funding snapshot owns ticket weights and original wallet destinations.
-Cash floors each ratio after fee and fee VAT; a named account receives residual.
-Loss assigns principal by largest remainder without cash, fee or VAT.
-Each receipt is consumed once; a new receipt may fund a new distribution record.
-This mode does not use caller-entered weights or a once-only settled principal pool.
-
-## Declared clauses
-
-- `agent description`
-- `aggregate invariants`
-- `capture input`
-- `description`
-- `due`
-- `id prefix`
-- `input`
-- `moves`
-- `port`
-- `requires refs`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## 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`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `requires refs`, `steps`, `summary` |
-| `payout` | `due`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `steps` |
-
-# 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. |
-
-## Account fields
-
-When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
-
-```hsx
-fields {
-  customerAccountId {
-    type: account<SAR>;
-    "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
-  }
-  amount: money<SAR>;
-}
-```
-
-The account type pins the currency and identifier shape. The reference filter
-pins the allowed ledger roles. Product admission requires every account field
-to declare a non-empty role list. Choose roles that match the accounts the
-program will use; `customer_balance` is the role in this example.
-
-Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
-with `column: role` and `values: [...]`. There is no shorter role annotation.
-A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
-the host's account-role admission law.
-
-## Money fields
-
-A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
-
-```hsx
-fields {
-  amount: money<SAR>;
-  discount { type: money<SAR>; optional: true; allow_zero: true; }
-}
-```
-
-`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
-
-## Date fields
-
-A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
-
-# 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.