@hyperscale0/hsx 2.1.0 → 2.2.0

package/docs/reference/std/rotating_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. -->
 
 # rotating_pool
 
@@ -10,18 +10,99 @@ Source: [`std/money_flows/rotating_pool.hsx`](../../../std/money_flows/rotating_
 
 ## Parameters
 
-- `members: optional<list<party>>`
-- `contribution: money<C>`
-- `count: integer`
-- `every: optional<text>`
-- `first_due: date`
-- `payout_order: optional<list<party>>`
-- `default_policy: optional<text>`
-- `guarantee_policy: optional<text>`
-- `guarantor: optional<party>`
-- `exit_policy: optional<text>`
-- `memo: optional<text>`
-- `membership: optional<block>`
+| 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
 
@@ -29,14 +110,21 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                   |
-| ---------- | ------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
-| `activate` | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `close`    | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `examples`, `moves`, `steps` |
-| `activate` | `due`, `examples`, `moves`, `steps`               |
-| `disband`  | `agent description`, `examples`, `moves`, `steps` |
-| `close`    | `agent description`, `examples`, `moves`, `steps` |
+| 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` |

package/docs/reference/std/scheduled.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. -->
 
 # scheduled
 
@@ -10,21 +10,104 @@ Source: [`std/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `count: optional<integer>`
-- `every: text`
-- `first_due: date`
-- `mode: optional<text>`
-- `debtor: optional<party>`
-- `advance_to: optional<party>`
-- `until: optional<condition>`
-- `month_end: optional<text>`
-- `period_liability: optional<text>`
-- `termination_drain: optional<text>`
-- `mandate: optional<condition>`
-- `derived_amount: optional<unknown>`
+| 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
 
@@ -33,19 +116,21 @@ Source: [`std/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx
 
 ## Actions and clauses
 
-| Action              | Clauses lowered                                                                                                            |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `create`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `approve`           | `agent description`, `steps`, `summary`                                                                                    |
-| `advance`           | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `delinquent_action` | `due`, `sets at`, `steps`, `summary`                                                                                       |
-| `complete`          | `due`, `steps`, `summary`                                                                                                  |
-| `write_off`         | `agent description`, `steps`, `summary`                                                                                    |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `repay`             | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary`                          |
-| `refund`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `open_period`       | `due`, `steps`, `summary`                                                                                                  |
-| `collect_period`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `until`             | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                                                  |
+| 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` |

package/docs/reference/std/security_deposit.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. -->
 
 # security_deposit
 
@@ -10,20 +10,112 @@ Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/securi
 
 ## Parameters
 
-- `payer: party`
-- `holder: party`
-- `amount: money<C>`
-- `claim: optional<condition>`
-- `return: optional<condition>`
-- `claim_amount: optional<block>`
-- `deadline: optional<date>`
-- `claim_to: optional<party>`
-- `return_to: optional<party>`
-- `memo: optional<text>`
-- `claim_input: optional<block>`
-- `claim_capture: optional<block>`
-- `fund_failure_point: optional<text>`
-- `id_prefix_override: optional<text>`
+| 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
 
@@ -32,15 +124,15 @@ Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/securi
 
 ## 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`                                                                                          |
+| 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` |

package/docs/reference/std/settlement_batch.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. -->
 
 # settlement_batch
 
@@ -10,15 +10,96 @@ Source: [`std/money_flows/settlement_batch.hsx`](../../../std/money_flows/settle
 
 ## Parameters
 
-- `settlement_account: party`
-- `source_capture_refs: text`
-- `fee_entries: text`
-- `external_reversal_offsets: text`
-- `close_trigger: date`
-- `payout_destination: party`
-- `negative_position: text`
-- `payout_acknowledgement: condition`
-- `payout_beneficiary_ref: text`
+| 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
 
@@ -26,17 +107,17 @@ Source: [`std/money_flows/settlement_batch.hsx`](../../../std/money_flows/settle
 
 ## Actions and clauses
 
-| Action                   | Clauses lowered                                                                                   |
-| ------------------------ | ------------------------------------------------------------------------------------------------- |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `close`                  | `due`, `moves`, `steps`, `summary`                                                                |
-| `calculate`              | `agent description`, `computes signed_sum`, `moves`, `steps`, `summary`                           |
-| `approve`                | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `instruct`               | `agent description`, `moves`, `payout`, `steps`, `summary`                                        |
-| `payout_acknowledgement` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `reconcile`              | `due`, `moves`, `reconcile`, `steps`, `summary`                                                   |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `accrue`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `adjust`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `correct`                | `agent description`, `moves`, `steps`, `summary`                                                  |
+| 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` |