@hyperscale0/hsx 2.1.0 → 2.2.0

package/docs/reference/std/swap.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. Do not edit. -->
 
 # swap
 
@@ -10,16 +10,103 @@ Source: [`std/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
 
 ## Parameters
 
-- `between: list<party>`
-- `amounts: block`
-- `fees: block`
-- `release: condition`
-- `dispute: condition`
-- `side_names: optional<block>`
-- `lifecycle_state_order: optional<list<text>>`
-- `action_bindings: optional<block>`
-- `parked_states: optional<block>`
-- `fixed_prefix: optional<text>`
+| 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
 
@@ -28,19 +115,19 @@ Source: [`std/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
 
 ## 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`                                                                              |
+| 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`                                               |
+| `cancel` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary` |
+| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary` |

package/docs/reference/std/threshold_pool.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. Do not edit. -->
 
 # threshold_pool
 
@@ -10,20 +10,111 @@ Source: [`std/money_flows/threshold_pool.hsx`](../../../std/money_flows/threshol
 
 ## Parameters
 
-- `contributor: optional<party>`
-- `beneficiary: optional<party>`
-- `target: money<C>`
-- `commitment: money<C>`
-- `max_contributors: optional<integer>`
-- `close_by: date`
-- `close_policy: optional<text>`
-- `overfund_policy: optional<text>`
-- `cancel_policy: optional<text>`
-- `fail_policy: optional<text>`
-- `beneficiary_account: optional<account<C>>`
-- `memo: optional<text>`
-- `contribution_instrument: optional<block>`
-- `wording: optional<block>`
+| 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
 
@@ -31,17 +122,17 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                   |
-| ---------- | ------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `activate` | `due`, `moves`, `steps`, `summary`                |
-| `fail`     | `due`, `moves`, `steps`, `summary`                |
-| `close`    | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
-| `collect`  | `agent description`, `moves`, `steps`, `summary`  |
-| `refund`   | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `examples`, `moves`, `steps` |
-| `activate` | `due`, `examples`, `moves`, `steps`               |
-| `fail`     | `due`, `examples`, `moves`, `steps`               |
-| `close`    | `agent description`, `examples`, `moves`, `steps` |
+| 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` |

package/docs/reference/std/weighted_distribution.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. Do not edit. -->
 
 # weighted_distribution
 
@@ -10,18 +10,113 @@ Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/w
 
 ## Parameters
 
-- `source: party`
-- `recipient: party`
-- `amount: money<C>`
-- `record_at: date`
-- `weight: optional<money<C>>`
-- `max_recipients: optional<integer>`
-- `snapshot: optional<condition>`
-- `rounding_policy: optional<text>`
-- `withholding_policy: optional<text>`
-- `correction_policy: optional<text>`
-- `flat: optional<block>`
-- `id_prefix_override: optional<text>`
+| 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
 
@@ -29,11 +124,12 @@ Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/w
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                                                                   |
-| ---------- | ------------------------------------------------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `snapshot` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `payout`   | `agent description`, `computes distribute`, `moves`, `steps`, `summary`                           |
-| `create`   | `agent description`, `moves`, `requires refs`, `steps`, `summary`                                 |
-| `payout`   | `computes distribute`, `due`, `moves`, `steps`, `summary`                                         |
+| 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` |

package/docs/reference/types.md

@@ -1,20 +1,20 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. Do not edit. -->
 
 # 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. |
+| 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. |

package/docs/reference/udl-output.md

@@ -1,13 +1,13 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. Do not edit. -->
 
 # 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.                        |
+| 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.

package/examples/01-first-program/README.md

@@ -27,7 +27,7 @@ payee, and both must be declared parties.
 `payee` name declared parties; `amount: tipAmount: money(SAR)` declares a
 field the instance stores, called `tipAmount`, holding an amount in SAR.
 
-That doubled colon reads oddly the first time. The archetype's parameter is
+That doubled colon reads oddly the first time. The module's parameter is
 `amount`; its value is a typed binding, `tipAmount: money(SAR)`, which names
 the field AND its type. You choose the field name because it shows up in the
 generated API, and `amount` is HSX's word, not your product's.

package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/README.md

@@ -1,4 +1,4 @@
-# 2 · Imports, settlement bricks, and the port
+# 2 · Imports, modules, and the port
 
 [`photo-booth.hsx`](./photo-booth.hsx) is a photo-booth rental company. The
 renter pays up front, but the money does not reach the company until the booth

package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/photo-booth.hsx

@@ -1,4 +1,4 @@
-// Imports, archetypes, and the decision port.
+// Imports, modules, and the decision port.
 //
 // A photo-booth rental company. The renter pays up front, but the money sits
 // in escrow until the booth is delivered. The company's own backend answers

package/examples/04-complete-product/README.md

@@ -59,7 +59,7 @@ share does. Nobody's fraction of a halala goes missing, and nobody's is
 invented.
 
 A pool needs at least two recipients, and the funder cannot be one of them. A
-pool that distributes to one person is a transfer, and there is an archetype
+pool that distributes to one person is a transfer, and there is an module
 for that.
 
 ## What it compiles to

package/examples/05-authored-instrument/README.md

@@ -0,0 +1,5 @@
+# Authored payment
+
+`payment.hsx` declares a payment with a bound internal transfer. The [module guide](../../docs/guide/08-writing-a-module.md#an-authored-action-that-moves-money) contains the same program. The docs builder compares the bytes and compiles it with the packaged cost table.
+
+From the full repository root, run `bun open/hsx/bin/hsx.ts check open/hsx/examples/05-authored-instrument/payment.hsx`.

package/examples/05-authored-instrument/payment.hsx

@@ -0,0 +1,37 @@
+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"
+    }];
+  }
+}

package/examples/05-watch-club/watch-club.hsx

@@ -7,7 +7,6 @@ program watch_club "Watch club"
 import {
   security_deposit,
   instant_transfer,
-  recurring_collection,
   scheduled,
   settlement_batch,
   swap

package/examples/README.md

@@ -8,7 +8,7 @@ document byte for byte.
 The numbered examples provide end-to-end walkthroughs:
 
 - [01 · Your first program](01-first-program/README.md)
-- [02 · Imports and modules](02-imports-and-archetypes/README.md)
+- [02 · Imports and modules](02-imports-and-modules/README.md)
 - [03 · Diagnostics](03-diagnostics/README.md)
 - [04 · Complete product](04-complete-product/README.md)
 - [05 · Watch club](05-watch-club/README.md)
@@ -28,7 +28,6 @@ Each money flow has a runnable example directory:
 - [pooled_split](pooled_split/README.md)
 - [premium_forward](premium_forward/README.md)
 - [reconciled_payout](reconciled_payout/README.md)
-- [recurring_collection](recurring_collection/README.md)
 - [rotating_pool](rotating_pool/README.md)
 - [scheduled](scheduled/README.md)
 - [security_deposit](security_deposit/README.md)