@hyperscale0/hsx 2.1.0 → 2.2.0

package/docs/reference/std/instant_transfer.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. -->
 
 # instant_transfer
 
@@ -10,11 +10,78 @@ Source: [`std/money_flows/instant_transfer.hsx`](../../../std/money_flows/instan
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `fees: optional<block>`
-- `derived_amount: optional<block>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | Funding party whose account is debited. |
+| `payee` | `party` | Yes | Recipient party whose account is credited. |
+| `amount` | `money<C>` | Yes | Transfer amount in minor units of currency `C`. |
+| `fees` | `optional<block>` | No | Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee. |
+| `derived_amount` | `optional<block>` | No | Optional block declaring derived platform fees calculated from the transfer amount. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Direct, single-step push transfer from payer to payee with optional tiered or percentage fees.
+
+### Purpose
+
+`instant_transfer` debits a payer and credits a payee immediately in a single execution step.
+It fits peer-to-peer transfers, direct disbursements, instant payouts, wallet reloads, and simple point-of-sale payments.
+
+### Selection guidance
+
+- vs `captured_payment`: `instant_transfer` moves money in one atomic step without prior authorization holds,
+  incremental captures, voids, or post-settlement correction ports. Use `captured_payment` when authorization must precede capture.
+- vs `conditional_disbursement`: `instant_transfer` executes immediately without external decision evidence
+  or cumulative cap tracking. Use `conditional_disbursement` when payments require evidence submission or aggregate milestone caps.
+- vs `held_payment`: `instant_transfer` never holds funds in an intermediary escrow account.
+
+### Parameters
+
+- `payer`: Funding party whose account is debited.
+- `payee`: Recipient party whose account is credited.
+- `amount`: Transfer amount in minor units of currency `C`.
+- `fees`: Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee.
+- `derived_amount`: Optional block declaring derived platform fees calculated from the transfer amount.
+
+### Decision ports
+
+None. Transfers execute immediately upon invocation.
+
+### Example
+
+```hsx
+program instant_transfer_example "Instant transfer example"
+import { instant_transfer } from "std/money_flows"
+party customer: person
+party merchant: business
+settlement transfer = instant_transfer {
+  payer: customer
+  payee: merchant
+  amount: transferAmount: money(SAR)
+  fees {
+    customer: checkoutFee: money(SAR)
+    merchant {
+      tier { from: 0, to: 10000, fee: 1% }
+      tier { from: 10000, fee: highValueFee: money(SAR) }
+    }
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `moves`
+- `partitions`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -22,9 +89,9 @@ None.
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                                           |
-| --------------------- | ------------------------------------------------------------------------- |
-| `create`              | `agent description`, `moves`, `steps`, `summary`                          |
-| `pay_piece_1`         | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `pay_piece_2`         | `agent description`, `moves`, `steps`, `summary`                          |
-| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                          |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `pay_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `pay_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |

package/docs/reference/std/metered.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. -->
 
 # metered
 
@@ -10,10 +10,71 @@ Source: [`std/money_flows/metered.hsx`](../../../std/money_flows/metered.hsx)
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `close_by: date`
-- `rates: unknown`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The customer being billed for usage. |
+| `payee` | `party` | Yes | The service provider receiving usage revenue. |
+| `close_by` | `date` | Yes | Date when the metering period closes, preventing further usage charges. |
+| `rates` | `unknown` | Yes | Block mapping rate metric names to their per-unit money prices committed at period open. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Usage-based billing against a committed rate card over an open period until a stored close date.
+
+### Purpose
+
+`metered` bills customers for variable resource consumption such as API requests, compute hours,
+storage gigabytes, or utility consumption. The rate card is fixed when the period opens, and individual
+usage events are charged incrementally until the billing period closes on `close_by`.
+
+### Selection guidance
+
+- vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
+  rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
+  with predetermined amounts or installments.
+
+### Parameters
+
+- `payer`: The customer being billed for usage.
+- `payee`: The service provider receiving usage revenue.
+- `close_by`: Date when the metering period closes, preventing further usage charges.
+- `rates`: Block mapping rate metric names to their per-unit money prices committed at period open.
+
+### Decision ports
+
+None. Charges are driven by caller billing actions and period closure.
+
+### Example
+
+```hsx
+program metered_example "Metered example"
+import { metered } from "std/money_flows"
+party customer: business
+party provider: business
+settlement usage = metered {
+  payer: customer
+  payee: provider
+  close_by: periodEnd
+  rates {
+    api_call: callRate: money(SAR)
+    storage_gib: storageRate: money(SAR)
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `moves`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -21,7 +82,8 @@ None.
 
 ## Actions and clauses
 
-| Action         | Clauses lowered                         |
-| -------------- | --------------------------------------- |
-| `create`       | `agent description`, `steps`, `summary` |
-| `close_period` | `due`, `steps`, `summary`               |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `steps`, `summary` |
+| `charge_[item]` | `agent description`, `moves`, `steps`, `summary` |
+| `close_period` | `due`, `steps`, `summary` |

package/docs/reference/std/pooled_split.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. -->
 
 # pooled_split
 
@@ -10,10 +10,77 @@ Source: [`std/money_flows/pooled_split.hsx`](../../../std/money_flows/pooled_spl
 
 ## Parameters
 
-- `payer: party`
-- `amount: money<C>`
-- `payout_due: date`
-- `split: block`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The funding party providing the pooled amount. |
+| `amount` | `money<C>` | Yes | Total pooled amount in minor units of currency `C`. |
+| `payout_due` | `date` | Yes | Stored payout date when the pool distributes to all recipients. |
+| `split` | `block` | Yes | Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Fixed multi-recipient revenue or period pool funded share-by-share and released automatically on a due date.
+
+### Purpose
+
+`pooled_split` pools a period total from one payer and splits it across a fixed roster of recipients
+according to predetermined percentage shares (with integer division remainder assigned to `remainder_to`).
+Callers fund the pool share-by-share, and payouts disburse automatically to each recipient on `payout_due`.
+
+### Selection guidance
+
+- vs `weighted_distribution`: `pooled_split` hardcodes a fixed set of recipients and static percentage shares
+  directly in the contract. `weighted_distribution` handles dynamic recipient counts where arbitrary weights
+  are recorded as child records and frozen via a snapshot port before distribution.
+- vs `settlement_batch`: `settlement_batch` aggregates multiple payments from many sources into one net payout.
+  `pooled_split` takes one period total from one payer and partitions it out to multiple recipients.
+
+### Parameters
+
+- `payer`: The funding party providing the pooled amount.
+- `amount`: Total pooled amount in minor units of currency `C`.
+- `payout_due`: Stored payout date when the pool distributes to all recipients.
+- `split`: Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders.
+
+### Decision ports
+
+None. Payout distribution triggers automatically from the stored `payout_due` date.
+
+### Example
+
+```hsx
+program pooled_split_example "Pooled split example"
+import { pooled_split } from "std/money_flows"
+party payer: business
+party first_recipient: business
+party second_recipient: business
+settlement pool = pooled_split {
+  payer: payer
+  amount: poolAmount: money(SAR)
+  payout_due: payoutDueAt
+  split {
+    first_recipient: 60%
+    second_recipient: 40%
+    remainder_to: first_recipient
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `id prefix`
+- `moves`
+- `partitions`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -21,6 +88,8 @@ None.
 
 ## Actions and clauses
 
-| Action   | Clauses lowered                                  |
-| -------- | ------------------------------------------------ |
+| Action | Clauses lowered |
+| --- | --- |
 | `create` | `agent description`, `moves`, `steps`, `summary` |
+| `fund_share_[index]` | `agent description`, `moves`, `steps`, `summary` |
+| `distribute_share_[index]` | `due`, `moves`, `steps`, `summary` |

package/docs/reference/std/premium_forward.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. -->
 
 # premium_forward
 
@@ -10,14 +10,94 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
 
 ## Parameters
 
-- `payer: party`
-- `carrier: party`
-- `amount: money<C>`
-- `bind: condition`
-- `commission: percent`
-- `policy_ref: optional<text>`
-- `renewal_due: optional<date>`
-- `endorsement: optional<condition>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The policyholder paying the insurance premium. |
+| `carrier` | `party` | Yes | The insurance carrier underwriting the policy. |
+| `amount` | `money<C>` | Yes | Total gross premium in minor units of currency `C`. |
+| `bind` | `condition` | Yes | Condition port triggering policy binding and premium forwarding. |
+| `commission` | `percent` | Yes | Platform commission percentage retained from the gross premium. |
+| `policy_ref` | `optional<text>` | No | Optional policy identifier string. |
+| `renewal_due` | `optional<date>` | No | Optional date anchor when the policy is due for renewal. |
+| `endorsement` | `optional<condition>` | No | Optional condition port for recording policy endorsements. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Insurance premium escrow holding customer funds until policy binding, then partitioning net carrier premium and commission.
+
+### Purpose
+
+`premium_forward` manages insurance premium collection, broker commission retention, and carrier remittance.
+A policyholder funds the premium into dedicated escrow. The funds remain held until the policy binds via the `bind` port.
+Upon binding, the gross premium is automatically partitioned: the platform fee/commission is retained, and the net
+balance forwards to the carrier. It also supports policy endorsements and renewal schedules.
+
+### Selection guidance
+
+- vs `held_payment`: `premium_forward` is tailored for insurance lifecycles, featuring automatic commission splits
+  upon binding and policy endorsement tracking. `held_payment` is general commercial escrow without insurance
+  underwriting binding semantics or gross-to-net fee partitioning.
+- vs `conditional_disbursement`: `premium_forward` collects and forwards inbound policy premiums to carriers.
+  `conditional_disbursement` pays outbound claim settlements to claimants against stored evidence.
+
+### Parameters
+
+- `payer`: The policyholder paying the insurance premium.
+- `carrier`: The insurance carrier underwriting the policy.
+- `amount`: Total gross premium in minor units of currency `C`.
+- `bind`: Condition port triggering policy binding and premium forwarding.
+- `commission`: Platform commission percentage retained from the gross premium.
+- `policy_ref`: Optional policy identifier string.
+- `renewal_due`: Optional date anchor when the policy is due for renewal.
+- `endorsement`: Optional condition port for recording policy endorsements.
+
+### Decision ports
+
+- `bind`: Port authorizing policy binding, triggering carrier payout and commission retention.
+- `endorsement`: Port allowing carrier endorsement evidence to be recorded.
+
+### Example
+
+```hsx
+program premium_forward_example "Premium forward example"
+import { premium_forward } from "std/money_flows"
+party policyholder: person
+party carrier: business
+settlement premium = premium_forward {
+  payer: policyholder
+  carrier: carrier
+  amount: premiumAmount: money(SAR)
+  commission: 2%
+  bind: port bind_policy
+  policy_ref: policyReference
+  renewal_due: renewalDueAt
+  endorsement: port record_endorsement
+}
+port bind_policy { allowed: [policyholder, carrier] }
+port record_endorsement {
+  allowed: [carrier]
+  shape: { evidenceReference: text }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `capture input`
+- `description`
+- `due`
+- `input`
+- `moves`
+- `partitions`
+- `port`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -26,14 +106,14 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
 
 ## Actions and clauses
 
-| Action            | Clauses lowered                                                                            |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `create`          | `agent description`, `steps`, `summary`                                                    |
-| `fund_piece_1`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
-| `fund_piece_2`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
-| `bind`            | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`                                           |
-| `unfund_piece_1`  | `agent description`, `moves`, `steps`, `summary`                                           |
-| `abandon`         | `agent description`, `steps`, `summary`                                                    |
-| `endorsement`     | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                  |
-| `lapse`           | `due`, `steps`, `summary`                                                                  |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `steps`, `summary` |
+| `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `[bind]` | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
+| `abandon` | `agent description`, `steps`, `summary` |
+| `[endorsement]` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
+| `lapse` | `due`, `steps`, `summary` |

package/docs/reference/std/reconciled_payout.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. -->
 
 # reconciled_payout
 
@@ -10,13 +10,83 @@ Source: [`std/money_flows/reconciled_payout.hsx`](../../../std/money_flows/recon
 
 ## Parameters
 
-- `payer: party`
-- `beneficiary: party`
-- `amount: money<C>`
-- `beneficiary_ref: text`
-- `settle_by: date`
-- `matched_within: integer`
-- `matched_ceiling: integer`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The funding party providing the payout. |
+| `beneficiary` | `party` | Yes | The beneficiary party receiving the external payout. |
+| `amount` | `money<C>` | Yes | Instructed payout amount in minor units of currency `C`. |
+| `beneficiary_ref` | `text` | Yes | Registered external beneficiary ID for bank routing. |
+| `settle_by` | `date` | Yes | Cut-off date when unmatched expectation amounts become formal break records. |
+| `matched_within` | `integer` | Yes | Match tolerance window in basis points or minor units. |
+| `matched_ceiling` | `integer` | Yes | Maximum acceptable tolerance ceiling between instructed amount and settled debit. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Outbound bank payout instruction with end-to-end reconciliation against external bank statement feeds.
+
+### Purpose
+
+`reconciled_payout` manages high-assurance payouts to external suppliers, partners, or customers where payment
+is not complete until confirmed by bank statement data. An instruction is dispatched to the beneficiary and an expectation
+record is opened. Incoming statement debit lines match against the expectation within configurable tolerance thresholds
+(`matched_within`, `matched_ceiling`). If the statement debit does not match before `settle_by`, a formal break row is raised.
+
+### Selection guidance
+
+- vs `settlement_batch`: `reconciled_payout` executes and reconciles an individual bank payout instruction.
+  `settlement_batch` aggregates periodic captures, fees, and signed adjustments to calculate a net payable batch.
+- vs `instant_transfer`: `instant_transfer` executes an immediate internal ledger transfer between platform accounts.
+  `reconciled_payout` dispatches funds across external banking rails with reconciliation tolerances and break tracking.
+
+### Parameters
+
+- `payer`: The funding party providing the payout.
+- `beneficiary`: The beneficiary party receiving the external payout.
+- `amount`: Instructed payout amount in minor units of currency `C`.
+- `beneficiary_ref`: Registered external beneficiary ID for bank routing.
+- `settle_by`: Cut-off date when unmatched expectation amounts become formal break records.
+- `matched_within`: Match tolerance window in basis points or minor units.
+- `matched_ceiling`: Maximum acceptable tolerance ceiling between instructed amount and settled debit.
+
+### Decision ports
+
+None. Payout dispatch and settlement matching follow the declared schedule, bank statement lines, and tolerance rules.
+
+### Example
+
+```hsx
+program reconciled_payout_example "Reconciled payout example"
+import { reconciled_payout } from "std/money_flows"
+party treasury: business
+party supplier: business
+settlement supplier_payout = reconciled_payout {
+  payer: treasury
+  beneficiary: supplier
+  amount: netPayable: money(SAR)
+  beneficiary_ref: supplierBeneficiaryId
+  settle_by: settleBy
+  matched_within: 100
+  matched_ceiling: 500
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `dials`
+- `due`
+- `id prefix`
+- `moves`
+- `payout`
+- `reconcile`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -24,10 +94,10 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                            |
-| ---------- | ---------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
 | `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
-| `settle`   | `due`, `moves`, `reconcile`, `steps`, `summary`            |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
-| `carry`    | `agent description`, `moves`, `steps`, `summary`           |
+| `settle` | `due`, `moves`, `reconcile`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `carry` | `agent description`, `moves`, `steps`, `summary` |