@hyperscale0/hsx 2.1.1 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/CHANGELOG.md +38 -7
  2. package/dist/src/cli.d.ts +1 -1
  3. package/dist/src/cli.d.ts.map +1 -1
  4. package/dist/src/cli.js +39 -5
  5. package/dist/src/cli.js.map +1 -1
  6. package/dist/src/compile.d.ts +0 -1
  7. package/dist/src/compile.d.ts.map +1 -1
  8. package/dist/src/compile.js +15 -1
  9. package/dist/src/compile.js.map +1 -1
  10. package/dist/src/cost.d.ts +3 -3
  11. package/dist/src/cost.d.ts.map +1 -1
  12. package/dist/src/cost.js +22 -12
  13. package/dist/src/cost.js.map +1 -1
  14. package/dist/src/parse.d.ts.map +1 -1
  15. package/dist/src/parse.js +10 -14
  16. package/dist/src/parse.js.map +1 -1
  17. package/dist/src/std-bundle.d.ts.map +1 -1
  18. package/dist/src/std-bundle.js +20 -84
  19. package/dist/src/std-bundle.js.map +1 -1
  20. package/dist/src/typecheck.d.ts.map +1 -1
  21. package/dist/src/typecheck.js +171 -39
  22. package/dist/src/typecheck.js.map +1 -1
  23. package/dist/src/version.d.ts +1 -1
  24. package/dist/src/version.js +1 -1
  25. package/docs/README.md +4 -2
  26. package/docs/guide/01-first-program.md +1 -1
  27. package/docs/guide/03-instruments.md +14 -1
  28. package/docs/guide/06-schedules.md +5 -1
  29. package/docs/guide/08-writing-a-module.md +48 -0
  30. package/docs/llms-full.txt +1966 -422
  31. package/docs/llms.txt +3 -4
  32. package/docs/reference/cli.md +6 -5
  33. package/docs/reference/diagnostics.md +9 -9
  34. package/docs/reference/grammar.md +2 -3
  35. package/docs/reference/std/advance.md +94 -17
  36. package/docs/reference/std/cancellable_booking.md +138 -17
  37. package/docs/reference/std/captured_payment.md +96 -24
  38. package/docs/reference/std/conditional_disbursement.md +82 -14
  39. package/docs/reference/std/credit_facility.md +89 -16
  40. package/docs/reference/std/held_payment.md +155 -55
  41. package/docs/reference/std/instant_transfer.md +79 -12
  42. package/docs/reference/std/metered.md +71 -9
  43. package/docs/reference/std/pooled_split.md +76 -7
  44. package/docs/reference/std/premium_forward.md +100 -20
  45. package/docs/reference/std/reconciled_payout.md +84 -14
  46. package/docs/reference/std/rotating_pool.md +112 -24
  47. package/docs/reference/std/scheduled.md +117 -32
  48. package/docs/reference/std/security_deposit.md +119 -27
  49. package/docs/reference/std/settlement_batch.md +105 -24
  50. package/docs/reference/std/swap.md +113 -26
  51. package/docs/reference/std/threshold_pool.md +120 -29
  52. package/docs/reference/std/weighted_distribution.md +117 -21
  53. package/docs/reference/types.md +39 -15
  54. package/docs/reference/udl-output.md +6 -6
  55. package/examples/01-first-program/README.md +1 -1
  56. package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/README.md +1 -1
  57. package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/photo-booth.hsx +1 -1
  58. package/examples/04-complete-product/README.md +1 -1
  59. package/examples/05-authored-instrument/README.md +5 -0
  60. package/examples/05-authored-instrument/payment.hsx +37 -0
  61. package/examples/05-watch-club/watch-club.hsx +0 -1
  62. package/examples/README.md +1 -2
  63. package/examples/advance/advance.udl +29 -6
  64. package/examples/cancellable_booking/cancellable_booking.udl +19 -0
  65. package/examples/captured_payment/captured_payment.hsx +0 -4
  66. package/examples/captured_payment/captured_payment.udl +6 -0
  67. package/examples/conditional_disbursement/conditional_disbursement.hsx +0 -2
  68. package/examples/conditional_disbursement/conditional_disbursement.udl +4 -0
  69. package/examples/cost-table.json +136 -8
  70. package/examples/credit_facility/credit_facility.hsx +0 -3
  71. package/examples/credit_facility/credit_facility.udl +17 -1
  72. package/examples/held_payment/held_payment.udl +16 -0
  73. package/examples/instant_transfer/instant_transfer.udl +6 -0
  74. package/examples/metered/metered.udl +5 -1
  75. package/examples/pooled_split/pooled_split.udl +4 -0
  76. package/examples/premium_forward/premium_forward.udl +4 -0
  77. package/examples/reconciled_payout/reconciled_payout.udl +7 -0
  78. package/examples/rotating_pool/rotating_pool.udl +8 -0
  79. package/examples/scheduled/scheduled.udl +18 -3
  80. package/examples/security_deposit/security_deposit.udl +13 -0
  81. package/examples/settlement_batch/settlement_batch.udl +4 -0
  82. package/examples/swap/swap.udl +10 -0
  83. package/examples/threshold_pool/threshold_pool.udl +11 -0
  84. package/examples/weighted_distribution/weighted_distribution.udl +9 -0
  85. package/package.json +10 -10
  86. package/skills/hsx/SKILL.md +2 -36
  87. package/src/cli.ts +41 -5
  88. package/src/compile.ts +14 -6
  89. package/src/cost.ts +13 -16
  90. package/src/parse.ts +15 -10
  91. package/src/std-bundle.ts +21 -88
  92. package/src/typecheck.ts +207 -34
  93. package/src/version.ts +1 -1
  94. package/std/SEMANTICS.md +33 -128
  95. package/std/money_flows/advance.hsx +39 -26
  96. package/std/money_flows/cancellable_booking.hsx +275 -8
  97. package/std/money_flows/captured_payment.hsx +1 -9
  98. package/std/money_flows/conditional_disbursement.hsx +0 -6
  99. package/std/money_flows/credit_facility.hsx +0 -9
  100. package/std/money_flows/held_payment.hsx +39 -1
  101. package/std/money_flows/index.hsx +2 -1
  102. package/std/money_flows/metered.hsx +1 -5
  103. package/std/money_flows/scheduled.hsx +29 -119
  104. package/std/money_flows/threshold_pool.hsx +40 -5
  105. package/std/money_flows/weighted_distribution.hsx +47 -5
  106. package/docs/reference/std/recurring_collection.md +0 -25
  107. package/examples/recurring_collection/README.md +0 -3
  108. package/examples/recurring_collection/recurring_collection.hsx +0 -21
  109. package/examples/recurring_collection/recurring_collection.udl +0 -1135
  110. package/std/money_flows/recurring_collection.hsx +0 -72
@@ -1,4 +1,4 @@
1
- <!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
1
+ <!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
2
2
 
3
3
  # metered
4
4
 
@@ -10,10 +10,71 @@ Source: [`std/money_flows/metered.hsx`](../../../std/money_flows/metered.hsx)
10
10
 
11
11
  ## Parameters
12
12
 
13
- - `payer: party`
14
- - `payee: party`
15
- - `close_by: date`
16
- - `rates: unknown`
13
+ | Parameter | Type | Required | Meaning |
14
+ | --- | --- | --- | --- |
15
+ | `payer` | `party` | Yes | The customer being billed for usage. |
16
+ | `payee` | `party` | Yes | The service provider receiving usage revenue. |
17
+ | `close_by` | `date` | Yes | Date when the metering period closes, preventing further usage charges. |
18
+ | `rates` | `unknown` | Yes | Block mapping rate metric names to their per-unit money prices committed at period open. |
19
+
20
+ Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
21
+
22
+ ## Module guidance
23
+
24
+ Usage-based billing against a committed rate card over an open period until a stored close date.
25
+
26
+ ### Purpose
27
+
28
+ `metered` bills customers for variable resource consumption such as API requests, compute hours,
29
+ storage gigabytes, or utility consumption. The rate card is fixed when the period opens, and individual
30
+ usage events are charged incrementally until the billing period closes on `close_by`.
31
+
32
+ ### Selection guidance
33
+
34
+ - vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
35
+ rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
36
+ with predetermined amounts or installments.
37
+
38
+ ### Parameters
39
+
40
+ - `payer`: The customer being billed for usage.
41
+ - `payee`: The service provider receiving usage revenue.
42
+ - `close_by`: Date when the metering period closes, preventing further usage charges.
43
+ - `rates`: Block mapping rate metric names to their per-unit money prices committed at period open.
44
+
45
+ ### Decision ports
46
+
47
+ None. Charges are driven by caller billing actions and period closure.
48
+
49
+ ### Example
50
+
51
+ ```hsx
52
+ program metered_example "Metered example"
53
+ import { metered } from "std/money_flows"
54
+ party customer: business
55
+ party provider: business
56
+ settlement usage = metered {
57
+ payer: customer
58
+ payee: provider
59
+ close_by: periodEnd
60
+ rates {
61
+ api_call: callRate: money(SAR)
62
+ storage_gib: storageRate: money(SAR)
63
+ }
64
+ }
65
+ ```
66
+
67
+ ## Declared clauses
68
+
69
+ - `agent description`
70
+ - `description`
71
+ - `due`
72
+ - `moves`
73
+ - `steps`
74
+ - `summary`
75
+ - `title`
76
+
77
+ 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.
17
78
 
18
79
  ## Decision ports
19
80
 
@@ -21,7 +82,8 @@ None.
21
82
 
22
83
  ## Actions and clauses
23
84
 
24
- | Action | Clauses lowered |
25
- | -------------- | --------------------------------------- |
26
- | `create` | `agent description`, `steps`, `summary` |
27
- | `close_period` | `due`, `steps`, `summary` |
85
+ | Action | Clauses lowered |
86
+ | --- | --- |
87
+ | `create` | `agent description`, `steps`, `summary` |
88
+ | `charge_[item]` | `agent description`, `moves`, `steps`, `summary` |
89
+ | `close_period` | `due`, `steps`, `summary` |
@@ -1,4 +1,4 @@
1
- <!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
1
+ <!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
2
2
 
3
3
  # pooled_split
4
4
 
@@ -10,10 +10,77 @@ Source: [`std/money_flows/pooled_split.hsx`](../../../std/money_flows/pooled_spl
10
10
 
11
11
  ## Parameters
12
12
 
13
- - `payer: party`
14
- - `amount: money<C>`
15
- - `payout_due: date`
16
- - `split: block`
13
+ | Parameter | Type | Required | Meaning |
14
+ | --- | --- | --- | --- |
15
+ | `payer` | `party` | Yes | The funding party providing the pooled amount. |
16
+ | `amount` | `money<C>` | Yes | Total pooled amount in minor units of currency `C`. |
17
+ | `payout_due` | `date` | Yes | Stored payout date when the pool distributes to all recipients. |
18
+ | `split` | `block` | Yes | Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders. |
19
+
20
+ Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
21
+
22
+ ## Module guidance
23
+
24
+ Fixed multi-recipient revenue or period pool funded share-by-share and released automatically on a due date.
25
+
26
+ ### Purpose
27
+
28
+ `pooled_split` pools a period total from one payer and splits it across a fixed roster of recipients
29
+ according to predetermined percentage shares (with integer division remainder assigned to `remainder_to`).
30
+ Callers fund the pool share-by-share, and payouts disburse automatically to each recipient on `payout_due`.
31
+
32
+ ### Selection guidance
33
+
34
+ - vs `weighted_distribution`: `pooled_split` hardcodes a fixed set of recipients and static percentage shares
35
+ directly in the contract. `weighted_distribution` handles dynamic recipient counts where arbitrary weights
36
+ are recorded as child records and frozen via a snapshot port before distribution.
37
+ - vs `settlement_batch`: `settlement_batch` aggregates multiple payments from many sources into one net payout.
38
+ `pooled_split` takes one period total from one payer and partitions it out to multiple recipients.
39
+
40
+ ### Parameters
41
+
42
+ - `payer`: The funding party providing the pooled amount.
43
+ - `amount`: Total pooled amount in minor units of currency `C`.
44
+ - `payout_due`: Stored payout date when the pool distributes to all recipients.
45
+ - `split`: Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders.
46
+
47
+ ### Decision ports
48
+
49
+ None. Payout distribution triggers automatically from the stored `payout_due` date.
50
+
51
+ ### Example
52
+
53
+ ```hsx
54
+ program pooled_split_example "Pooled split example"
55
+ import { pooled_split } from "std/money_flows"
56
+ party payer: business
57
+ party first_recipient: business
58
+ party second_recipient: business
59
+ settlement pool = pooled_split {
60
+ payer: payer
61
+ amount: poolAmount: money(SAR)
62
+ payout_due: payoutDueAt
63
+ split {
64
+ first_recipient: 60%
65
+ second_recipient: 40%
66
+ remainder_to: first_recipient
67
+ }
68
+ }
69
+ ```
70
+
71
+ ## Declared clauses
72
+
73
+ - `agent description`
74
+ - `description`
75
+ - `due`
76
+ - `id prefix`
77
+ - `moves`
78
+ - `partitions`
79
+ - `steps`
80
+ - `summary`
81
+ - `title`
82
+
83
+ 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.
17
84
 
18
85
  ## Decision ports
19
86
 
@@ -21,6 +88,8 @@ None.
21
88
 
22
89
  ## Actions and clauses
23
90
 
24
- | Action | Clauses lowered |
25
- | -------- | ------------------------------------------------ |
91
+ | Action | Clauses lowered |
92
+ | --- | --- |
26
93
  | `create` | `agent description`, `moves`, `steps`, `summary` |
94
+ | `fund_share_[index]` | `agent description`, `moves`, `steps`, `summary` |
95
+ | `distribute_share_[index]` | `due`, `moves`, `steps`, `summary` |
@@ -1,4 +1,4 @@
1
- <!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
1
+ <!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
2
2
 
3
3
  # premium_forward
4
4
 
@@ -10,14 +10,94 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
10
10
 
11
11
  ## Parameters
12
12
 
13
- - `payer: party`
14
- - `carrier: party`
15
- - `amount: money<C>`
16
- - `bind: condition`
17
- - `commission: percent`
18
- - `policy_ref: optional<text>`
19
- - `renewal_due: optional<date>`
20
- - `endorsement: optional<condition>`
13
+ | Parameter | Type | Required | Meaning |
14
+ | --- | --- | --- | --- |
15
+ | `payer` | `party` | Yes | The policyholder paying the insurance premium. |
16
+ | `carrier` | `party` | Yes | The insurance carrier underwriting the policy. |
17
+ | `amount` | `money<C>` | Yes | Total gross premium in minor units of currency `C`. |
18
+ | `bind` | `condition` | Yes | Condition port triggering policy binding and premium forwarding. |
19
+ | `commission` | `percent` | Yes | Platform commission percentage retained from the gross premium. |
20
+ | `policy_ref` | `optional<text>` | No | Optional policy identifier string. |
21
+ | `renewal_due` | `optional<date>` | No | Optional date anchor when the policy is due for renewal. |
22
+ | `endorsement` | `optional<condition>` | No | Optional condition port for recording policy endorsements. |
23
+
24
+ Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
25
+
26
+ ## Module guidance
27
+
28
+ Insurance premium escrow holding customer funds until policy binding, then partitioning net carrier premium and commission.
29
+
30
+ ### Purpose
31
+
32
+ `premium_forward` manages insurance premium collection, broker commission retention, and carrier remittance.
33
+ A policyholder funds the premium into dedicated escrow. The funds remain held until the policy binds via the `bind` port.
34
+ Upon binding, the gross premium is automatically partitioned: the platform fee/commission is retained, and the net
35
+ balance forwards to the carrier. It also supports policy endorsements and renewal schedules.
36
+
37
+ ### Selection guidance
38
+
39
+ - vs `held_payment`: `premium_forward` is tailored for insurance lifecycles, featuring automatic commission splits
40
+ upon binding and policy endorsement tracking. `held_payment` is general commercial escrow without insurance
41
+ underwriting binding semantics or gross-to-net fee partitioning.
42
+ - vs `conditional_disbursement`: `premium_forward` collects and forwards inbound policy premiums to carriers.
43
+ `conditional_disbursement` pays outbound claim settlements to claimants against stored evidence.
44
+
45
+ ### Parameters
46
+
47
+ - `payer`: The policyholder paying the insurance premium.
48
+ - `carrier`: The insurance carrier underwriting the policy.
49
+ - `amount`: Total gross premium in minor units of currency `C`.
50
+ - `bind`: Condition port triggering policy binding and premium forwarding.
51
+ - `commission`: Platform commission percentage retained from the gross premium.
52
+ - `policy_ref`: Optional policy identifier string.
53
+ - `renewal_due`: Optional date anchor when the policy is due for renewal.
54
+ - `endorsement`: Optional condition port for recording policy endorsements.
55
+
56
+ ### Decision ports
57
+
58
+ - `bind`: Port authorizing policy binding, triggering carrier payout and commission retention.
59
+ - `endorsement`: Port allowing carrier endorsement evidence to be recorded.
60
+
61
+ ### Example
62
+
63
+ ```hsx
64
+ program premium_forward_example "Premium forward example"
65
+ import { premium_forward } from "std/money_flows"
66
+ party policyholder: person
67
+ party carrier: business
68
+ settlement premium = premium_forward {
69
+ payer: policyholder
70
+ carrier: carrier
71
+ amount: premiumAmount: money(SAR)
72
+ commission: 2%
73
+ bind: port bind_policy
74
+ policy_ref: policyReference
75
+ renewal_due: renewalDueAt
76
+ endorsement: port record_endorsement
77
+ }
78
+ port bind_policy { allowed: [policyholder, carrier] }
79
+ port record_endorsement {
80
+ allowed: [carrier]
81
+ shape: { evidenceReference: text }
82
+ }
83
+ ```
84
+
85
+ ## Declared clauses
86
+
87
+ - `agent description`
88
+ - `capture input`
89
+ - `description`
90
+ - `due`
91
+ - `input`
92
+ - `moves`
93
+ - `partitions`
94
+ - `port`
95
+ - `sandbox failure point`
96
+ - `steps`
97
+ - `summary`
98
+ - `title`
99
+
100
+ 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.
21
101
 
22
102
  ## Decision ports
23
103
 
@@ -26,14 +106,14 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
26
106
 
27
107
  ## Actions and clauses
28
108
 
29
- | Action | Clauses lowered |
30
- | ----------------- | ------------------------------------------------------------------------------------------ |
31
- | `create` | `agent description`, `steps`, `summary` |
32
- | `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
33
- | `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
34
- | `bind` | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
35
- | `forward_piece_2` | `agent description`, `moves`, `steps`, `summary` |
36
- | `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
37
- | `abandon` | `agent description`, `steps`, `summary` |
38
- | `endorsement` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
39
- | `lapse` | `due`, `steps`, `summary` |
109
+ | Action | Clauses lowered |
110
+ | --- | --- |
111
+ | `create` | `agent description`, `steps`, `summary` |
112
+ | `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
113
+ | `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
114
+ | `[bind]` | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
115
+ | `forward_piece_2` | `agent description`, `moves`, `steps`, `summary` |
116
+ | `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
117
+ | `abandon` | `agent description`, `steps`, `summary` |
118
+ | `[endorsement]` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
119
+ | `lapse` | `due`, `steps`, `summary` |
@@ -1,4 +1,4 @@
1
- <!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
1
+ <!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
2
2
 
3
3
  # reconciled_payout
4
4
 
@@ -10,13 +10,83 @@ Source: [`std/money_flows/reconciled_payout.hsx`](../../../std/money_flows/recon
10
10
 
11
11
  ## Parameters
12
12
 
13
- - `payer: party`
14
- - `beneficiary: party`
15
- - `amount: money<C>`
16
- - `beneficiary_ref: text`
17
- - `settle_by: date`
18
- - `matched_within: integer`
19
- - `matched_ceiling: integer`
13
+ | Parameter | Type | Required | Meaning |
14
+ | --- | --- | --- | --- |
15
+ | `payer` | `party` | Yes | The funding party providing the payout. |
16
+ | `beneficiary` | `party` | Yes | The beneficiary party receiving the external payout. |
17
+ | `amount` | `money<C>` | Yes | Instructed payout amount in minor units of currency `C`. |
18
+ | `beneficiary_ref` | `text` | Yes | Registered external beneficiary ID for bank routing. |
19
+ | `settle_by` | `date` | Yes | Cut-off date when unmatched expectation amounts become formal break records. |
20
+ | `matched_within` | `integer` | Yes | Match tolerance window in basis points or minor units. |
21
+ | `matched_ceiling` | `integer` | Yes | Maximum acceptable tolerance ceiling between instructed amount and settled debit. |
22
+
23
+ Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
24
+
25
+ ## Module guidance
26
+
27
+ Outbound bank payout instruction with end-to-end reconciliation against external bank statement feeds.
28
+
29
+ ### Purpose
30
+
31
+ `reconciled_payout` manages high-assurance payouts to external suppliers, partners, or customers where payment
32
+ is not complete until confirmed by bank statement data. An instruction is dispatched to the beneficiary and an expectation
33
+ record is opened. Incoming statement debit lines match against the expectation within configurable tolerance thresholds
34
+ (`matched_within`, `matched_ceiling`). If the statement debit does not match before `settle_by`, a formal break row is raised.
35
+
36
+ ### Selection guidance
37
+
38
+ - vs `settlement_batch`: `reconciled_payout` executes and reconciles an individual bank payout instruction.
39
+ `settlement_batch` aggregates periodic captures, fees, and signed adjustments to calculate a net payable batch.
40
+ - vs `instant_transfer`: `instant_transfer` executes an immediate internal ledger transfer between platform accounts.
41
+ `reconciled_payout` dispatches funds across external banking rails with reconciliation tolerances and break tracking.
42
+
43
+ ### Parameters
44
+
45
+ - `payer`: The funding party providing the payout.
46
+ - `beneficiary`: The beneficiary party receiving the external payout.
47
+ - `amount`: Instructed payout amount in minor units of currency `C`.
48
+ - `beneficiary_ref`: Registered external beneficiary ID for bank routing.
49
+ - `settle_by`: Cut-off date when unmatched expectation amounts become formal break records.
50
+ - `matched_within`: Match tolerance window in basis points or minor units.
51
+ - `matched_ceiling`: Maximum acceptable tolerance ceiling between instructed amount and settled debit.
52
+
53
+ ### Decision ports
54
+
55
+ None. Payout dispatch and settlement matching follow the declared schedule, bank statement lines, and tolerance rules.
56
+
57
+ ### Example
58
+
59
+ ```hsx
60
+ program reconciled_payout_example "Reconciled payout example"
61
+ import { reconciled_payout } from "std/money_flows"
62
+ party treasury: business
63
+ party supplier: business
64
+ settlement supplier_payout = reconciled_payout {
65
+ payer: treasury
66
+ beneficiary: supplier
67
+ amount: netPayable: money(SAR)
68
+ beneficiary_ref: supplierBeneficiaryId
69
+ settle_by: settleBy
70
+ matched_within: 100
71
+ matched_ceiling: 500
72
+ }
73
+ ```
74
+
75
+ ## Declared clauses
76
+
77
+ - `agent description`
78
+ - `description`
79
+ - `dials`
80
+ - `due`
81
+ - `id prefix`
82
+ - `moves`
83
+ - `payout`
84
+ - `reconcile`
85
+ - `steps`
86
+ - `summary`
87
+ - `title`
88
+
89
+ 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.
20
90
 
21
91
  ## Decision ports
22
92
 
@@ -24,10 +94,10 @@ None.
24
94
 
25
95
  ## Actions and clauses
26
96
 
27
- | Action | Clauses lowered |
28
- | ---------- | ---------------------------------------------------------- |
29
- | `create` | `agent description`, `moves`, `steps`, `summary` |
97
+ | Action | Clauses lowered |
98
+ | --- | --- |
99
+ | `create` | `agent description`, `moves`, `steps`, `summary` |
30
100
  | `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
31
- | `settle` | `due`, `moves`, `reconcile`, `steps`, `summary` |
32
- | `create` | `agent description`, `moves`, `steps`, `summary` |
33
- | `carry` | `agent description`, `moves`, `steps`, `summary` |
101
+ | `settle` | `due`, `moves`, `reconcile`, `steps`, `summary` |
102
+ | `create` | `agent description`, `moves`, `steps`, `summary` |
103
+ | `carry` | `agent description`, `moves`, `steps`, `summary` |
@@ -1,4 +1,4 @@
1
- <!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
1
+ <!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
2
2
 
3
3
  # rotating_pool
4
4
 
@@ -10,18 +10,99 @@ Source: [`std/money_flows/rotating_pool.hsx`](../../../std/money_flows/rotating_
10
10
 
11
11
  ## Parameters
12
12
 
13
- - `members: optional<list<party>>`
14
- - `contribution: money<C>`
15
- - `count: integer`
16
- - `every: optional<text>`
17
- - `first_due: date`
18
- - `payout_order: optional<list<party>>`
19
- - `default_policy: optional<text>`
20
- - `guarantee_policy: optional<text>`
21
- - `guarantor: optional<party>`
22
- - `exit_policy: optional<text>`
23
- - `memo: optional<text>`
24
- - `membership: optional<block>`
13
+ | Parameter | Type | Required | Meaning |
14
+ | --- | --- | --- | --- |
15
+ | `members` | `optional<list<party>>` | No | List of parties belonging to the rotating group. |
16
+ | `contribution` | `money<C>` | Yes | Fixed contribution amount required from each member per cycle in minor units of currency `C`. |
17
+ | `count` | `integer` | Yes | Total number of cycles in the rotation (matching the member count). |
18
+ | `every` | `optional<text>` | No | Recurrence interval between contribution cycles (e.g. `"P30D"`). |
19
+ | `first_due` | `date` | Yes | Due date for the first cycle's contribution. |
20
+ | `payout_order` | `optional<list<party>>` | No | Ordered list of member parties defining the cycle payout sequence. |
21
+ | `default_policy` | `optional<text>` | No | Policy for handling missed contributions (`due_condition`). |
22
+ | `guarantee_policy` | `optional<text>` | No | Policy for backing defaulted contributions (`funded_only`). |
23
+ | `guarantor` | `optional<party>` | No | Optional guarantor party covering member defaults. |
24
+ | `exit_policy` | `optional<text>` | No | Policy governing member departures (`before_activation_only`). |
25
+ | `memo` | `optional<text>` | No | Optional memo text stored on the pool. |
26
+ | `membership` | `optional<block>` | No | Optional custom membership configuration block. |
27
+
28
+ Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
29
+
30
+ ## Module guidance
31
+
32
+ Rotating savings and credit association (ROSCA) pool where members contribute fixed amounts and take turns receiving the pot.
33
+
34
+ ### Purpose
35
+
36
+ `rotating_pool` coordinates peer savings circles, chit funds, tandas, and committee savings groups.
37
+ A fixed group of members contributes an identical contribution amount each cycle. In each cycle, one designated member
38
+ receives the entire pooled pot according to a predefined `payout_order` until all members have taken their turn.
39
+
40
+ ### Selection guidance
41
+
42
+ - vs `threshold_pool`: `rotating_pool` coordinates recurring multi-party peer savings with rotating payouts.
43
+ `threshold_pool` is all-or-nothing capital accumulation toward a single threshold for one beneficiary.
44
+ - vs `scheduled`: `scheduled` coordinates a single payer to a single payee. `rotating_pool` orchestrates
45
+ a closed circular group of members taking sequential turns.
46
+
47
+ ### Parameters
48
+
49
+ - `members`: List of parties belonging to the rotating group.
50
+ - `contribution`: Fixed contribution amount required from each member per cycle in minor units of currency `C`.
51
+ - `count`: Total number of cycles in the rotation (matching the member count).
52
+ - `every`: Recurrence interval between contribution cycles (e.g. `"P30D"`).
53
+ - `first_due`: Due date for the first cycle's contribution.
54
+ - `payout_order`: Ordered list of member parties defining the cycle payout sequence.
55
+ - `default_policy`: Policy for handling missed contributions (`due_condition`).
56
+ - `guarantee_policy`: Policy for backing defaulted contributions (`funded_only`).
57
+ - `guarantor`: Optional guarantor party covering member defaults.
58
+ - `exit_policy`: Policy governing member departures (`before_activation_only`).
59
+ - `memo`: Optional memo text stored on the pool.
60
+ - `membership`: Optional custom membership configuration block.
61
+
62
+ ### Decision ports
63
+
64
+ None. Cycle advancement and pot payouts follow the declared schedule and membership actions.
65
+
66
+ ### Example
67
+
68
+ ```hsx
69
+ program rotating_pool_example "Rotating pool example"
70
+ import { rotating_pool } from "std/money_flows"
71
+ party member_a: person
72
+ party member_b: person
73
+ party member_c: person
74
+ party guarantor: business
75
+ settlement pool = rotating_pool {
76
+ members: [member_a, member_b, member_c]
77
+ contribution: contributionAmount: money(SAR)
78
+ count: 3
79
+ every: P30D
80
+ first_due: firstContributionAt
81
+ payout_order: [member_b, member_c, member_a]
82
+ default_policy: due_condition
83
+ guarantee_policy: funded_only
84
+ guarantor: guarantor
85
+ exit_policy: before_activation_only
86
+ }
87
+ ```
88
+
89
+ ## Declared clauses
90
+
91
+ - `agent description`
92
+ - `aggregate invariants`
93
+ - `caller parked states`
94
+ - `description`
95
+ - `due`
96
+ - `examples`
97
+ - `id prefix`
98
+ - `moves`
99
+ - `sandbox failure point`
100
+ - `steps`
101
+ - `summary`
102
+ - `title`
103
+ - `unique`
104
+
105
+ 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.
25
106
 
26
107
  ## Decision ports
27
108
 
@@ -29,14 +110,21 @@ None.
29
110
 
30
111
  ## Actions and clauses
31
112
 
32
- | Action | Clauses lowered |
33
- | ---------- | ------------------------------------------------- |
34
- | `create` | `agent description`, `moves`, `steps`, `summary` |
35
- | `cancel` | `agent description`, `moves`, `steps`, `summary` |
36
- | `activate` | `agent description`, `moves`, `steps`, `summary` |
37
- | `create` | `agent description`, `moves`, `steps`, `summary` |
38
- | `close` | `agent description`, `moves`, `steps`, `summary` |
39
- | `create` | `agent description`, `examples`, `moves`, `steps` |
40
- | `activate` | `due`, `examples`, `moves`, `steps` |
41
- | `disband` | `agent description`, `examples`, `moves`, `steps` |
42
- | `close` | `agent description`, `examples`, `moves`, `steps` |
113
+ | Action | Clauses lowered |
114
+ | --- | --- |
115
+ | `create` | `agent description`, `moves`, `steps`, `summary` |
116
+ | `cancel` | `agent description`, `moves`, `steps`, `summary` |
117
+ | `activate` | `agent description`, `moves`, `steps`, `summary` |
118
+ | `ready_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
119
+ | `advance_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
120
+ | `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
121
+ | `contribute_cycle_[cycle]` | `due`, `moves`, `sandbox failure point`, `steps`, `summary` |
122
+ | `mark_default_cycle_[cycle]` | `due`, `moves`, `steps`, `summary` |
123
+ | `guarantee_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
124
+ | `pay_cycle_[cycle]` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
125
+ | `pay_guaranteed_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
126
+ | `close` | `agent description`, `moves`, `steps`, `summary` |
127
+ | `create` | `agent description`, `examples`, `moves`, `steps` |
128
+ | `activate` | `due`, `examples`, `moves`, `steps` |
129
+ | `disband` | `agent description`, `examples`, `moves`, `steps` |
130
+ | `close` | `agent description`, `examples`, `moves`, `steps` |