@hyperscale0/hsx 2.1.1 → 2.2.1

package/docs/llms.txt

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # HSX documentation
 
-> Repository guide and generated compiler reference for HSX 2.1.1.
+> Repository guide and generated compiler reference for HSX 2.2.1.
 
 ## Guide
 
@@ -20,7 +20,7 @@
 ## Reference
 
 [Grammar](reference/grammar.md): Lexer, clause, and module vocabulary.
-[Types](reference/types.md): HSX type kinds.
+[Types](reference/types.md): HSX type kinds and account role pins.
 [Diagnostics](reference/diagnostics.md): Stable HSX diagnostic codes and fixes.
 [CLI](reference/cli.md): Generated command usage.
 [UDL output](reference/udl-output.md): Compile artifacts and canonical output.
@@ -35,7 +35,6 @@
 [pooled_split](reference/std/pooled_split.md): Standard-library module.
 [premium_forward](reference/std/premium_forward.md): Standard-library module.
 [reconciled_payout](reference/std/reconciled_payout.md): Standard-library module.
-[recurring_collection](reference/std/recurring_collection.md): Standard-library module.
 [rotating_pool](reference/std/rotating_pool.md): Standard-library module.
 [scheduled](reference/std/scheduled.md): Standard-library module.
 [security_deposit](reference/std/security_deposit.md): Standard-library module.

package/docs/reference/cli.md

@@ -1,14 +1,14 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # CLI
 
 ```text
-hsx 2.1.1, the HSX compiler
+hsx 2.2.1, the HSX compiler
 
 Usage:
-  hsx check <file.hsx> [--strict]
-  hsx build <file.hsx> [--out <file.json>] [--strict]
-  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  hsx 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
@@ -24,6 +24,7 @@ Commands:
   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.

package/docs/reference/diagnostics.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # Diagnostics
 
@@ -39,7 +39,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 program second "Second"
 ```
@@ -70,7 +70,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
 ```
@@ -122,7 +122,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 subject vehicle { title: "Vehicle"; }
 ```
@@ -340,7 +340,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 const fee: money<SAR> = USD 1.00
 ```
@@ -361,7 +361,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 const fee: money<SAR> = SAR 1.001
 ```
@@ -481,7 +481,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 
@@ -517,7 +517,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 
@@ -537,7 +537,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 

package/docs/reference/grammar.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # Grammar vocabulary
 
@@ -14,7 +14,7 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 
 ## Typed clause spellings
 
-`action library`, `agent description`, `calls`, `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`, `journeys`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
+`funding`, `receipt distribution`, `requires allocation`, `allocation`, `contributions`, `allocate`, `contribution stage`, `date order`, `unique`, `transitions refs`, `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
 
@@ -29,7 +29,6 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 - `pooled_split`
 - `premium_forward`
 - `reconciled_payout`
-- `recurring_collection`
 - `rotating_pool`
 - `scheduled`
 - `security_deposit`

package/docs/reference/std/advance.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # advance
 
@@ -10,14 +10,91 @@ Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
 
 ## Parameters
 
-- `funder: party`
-- `to: party`
-- `amount: money<C>`
-- `fee: optional<percent>`
-- `count: optional<integer>`
-- `every: optional<text>`
-- `first_due: optional<date>`
-- `against: optional<ref>`
+| 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
 
@@ -25,11 +102,11 @@ None.
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                  |
-| --------------------- | ------------------------------------------------ |
-| `create`              | `agent description`, `moves`, `steps`, `summary` |
-| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
-| `settle`              | `agent description`, `moves`, `steps`, `summary` |
-| `create`              | `agent description`, `moves`, `steps`, `summary` |
-| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
-| `collect_repayment_1` | `due`, `moves`, `steps`, `summary`               |
+| 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` |

package/docs/reference/std/cancellable_booking.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # cancellable_booking
 
@@ -10,14 +10,124 @@ Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/can
 
 ## Parameters
 
-- `guest: party`
-- `host: party`
-- `amount: money<C>`
-- `starts_at: date`
-- `late_penalty_bps: integer`
-- `late_within: text`
-- `early_penalty_bps: integer`
-- `offer_life: text`
+| 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. |
+
+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.
+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`
+- `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
 
@@ -25,11 +135,22 @@ 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`                          |
+| 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`, `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` |

package/docs/reference/std/captured_payment.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # captured_payment
 
@@ -10,17 +10,89 @@ Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captur
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `reserve_until: date`
-- `correction: condition`
-- `external_reversal: condition`
-- `capture_mode: text`
-- `correction_mode: text`
-- `negative_position: text`
-- `timeout: text`
-- `derived_amount: optional<block>`
+| 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
 
@@ -29,15 +101,15 @@ Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captur
 
 ## 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`                |
+| 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` |