@hyperscale0/hsx 2.1.1 → 2.2.0
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.
- package/CHANGELOG.md +28 -7
- package/dist/src/cli.d.ts +1 -1
- package/dist/src/cli.d.ts.map +1 -1
- package/dist/src/cli.js +39 -5
- package/dist/src/cli.js.map +1 -1
- package/dist/src/compile.d.ts +0 -1
- package/dist/src/compile.d.ts.map +1 -1
- package/dist/src/compile.js +15 -1
- package/dist/src/compile.js.map +1 -1
- package/dist/src/cost.d.ts +3 -3
- package/dist/src/cost.d.ts.map +1 -1
- package/dist/src/cost.js +22 -12
- package/dist/src/cost.js.map +1 -1
- package/dist/src/parse.d.ts.map +1 -1
- package/dist/src/parse.js +10 -14
- package/dist/src/parse.js.map +1 -1
- package/dist/src/std-bundle.d.ts.map +1 -1
- package/dist/src/std-bundle.js +20 -84
- package/dist/src/std-bundle.js.map +1 -1
- package/dist/src/typecheck.d.ts.map +1 -1
- package/dist/src/typecheck.js +171 -39
- package/dist/src/typecheck.js.map +1 -1
- package/dist/src/version.d.ts +1 -1
- package/dist/src/version.js +1 -1
- package/docs/README.md +4 -2
- package/docs/guide/01-first-program.md +1 -1
- package/docs/guide/06-schedules.md +5 -1
- package/docs/guide/08-writing-a-module.md +48 -0
- package/docs/llms-full.txt +1928 -421
- package/docs/llms.txt +2 -3
- package/docs/reference/cli.md +6 -5
- package/docs/reference/diagnostics.md +9 -9
- package/docs/reference/grammar.md +2 -3
- package/docs/reference/std/advance.md +94 -17
- package/docs/reference/std/cancellable_booking.md +138 -17
- package/docs/reference/std/captured_payment.md +96 -24
- package/docs/reference/std/conditional_disbursement.md +82 -14
- package/docs/reference/std/credit_facility.md +89 -16
- package/docs/reference/std/held_payment.md +155 -55
- package/docs/reference/std/instant_transfer.md +79 -12
- package/docs/reference/std/metered.md +71 -9
- package/docs/reference/std/pooled_split.md +76 -7
- package/docs/reference/std/premium_forward.md +100 -20
- package/docs/reference/std/reconciled_payout.md +84 -14
- package/docs/reference/std/rotating_pool.md +112 -24
- package/docs/reference/std/scheduled.md +117 -32
- package/docs/reference/std/security_deposit.md +119 -27
- package/docs/reference/std/settlement_batch.md +105 -24
- package/docs/reference/std/swap.md +113 -26
- package/docs/reference/std/threshold_pool.md +120 -29
- package/docs/reference/std/weighted_distribution.md +117 -21
- package/docs/reference/types.md +15 -15
- package/docs/reference/udl-output.md +6 -6
- package/examples/01-first-program/README.md +1 -1
- package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/README.md +1 -1
- package/examples/{02-imports-and-archetypes → 02-imports-and-modules}/photo-booth.hsx +1 -1
- package/examples/04-complete-product/README.md +1 -1
- package/examples/05-authored-instrument/README.md +5 -0
- package/examples/05-authored-instrument/payment.hsx +37 -0
- package/examples/05-watch-club/watch-club.hsx +0 -1
- package/examples/README.md +1 -2
- package/examples/advance/advance.udl +29 -6
- package/examples/cancellable_booking/cancellable_booking.udl +19 -0
- package/examples/captured_payment/captured_payment.hsx +0 -4
- package/examples/captured_payment/captured_payment.udl +6 -0
- package/examples/conditional_disbursement/conditional_disbursement.hsx +0 -2
- package/examples/conditional_disbursement/conditional_disbursement.udl +4 -0
- package/examples/cost-table.json +136 -8
- package/examples/credit_facility/credit_facility.hsx +0 -3
- package/examples/credit_facility/credit_facility.udl +17 -1
- package/examples/held_payment/held_payment.udl +16 -0
- package/examples/instant_transfer/instant_transfer.udl +6 -0
- package/examples/metered/metered.udl +5 -1
- package/examples/pooled_split/pooled_split.udl +4 -0
- package/examples/premium_forward/premium_forward.udl +4 -0
- package/examples/reconciled_payout/reconciled_payout.udl +7 -0
- package/examples/rotating_pool/rotating_pool.udl +8 -0
- package/examples/scheduled/scheduled.udl +18 -3
- package/examples/security_deposit/security_deposit.udl +13 -0
- package/examples/settlement_batch/settlement_batch.udl +4 -0
- package/examples/swap/swap.udl +10 -0
- package/examples/threshold_pool/threshold_pool.udl +11 -0
- package/examples/weighted_distribution/weighted_distribution.udl +9 -0
- package/package.json +10 -10
- package/skills/hsx/SKILL.md +2 -36
- package/src/cli.ts +41 -5
- package/src/compile.ts +14 -6
- package/src/cost.ts +13 -16
- package/src/parse.ts +15 -10
- package/src/std-bundle.ts +21 -88
- package/src/typecheck.ts +207 -34
- package/src/version.ts +1 -1
- package/std/SEMANTICS.md +33 -128
- package/std/money_flows/advance.hsx +39 -26
- package/std/money_flows/cancellable_booking.hsx +275 -8
- package/std/money_flows/captured_payment.hsx +1 -9
- package/std/money_flows/conditional_disbursement.hsx +0 -6
- package/std/money_flows/credit_facility.hsx +0 -9
- package/std/money_flows/held_payment.hsx +39 -1
- package/std/money_flows/index.hsx +2 -1
- package/std/money_flows/metered.hsx +1 -5
- package/std/money_flows/scheduled.hsx +29 -119
- package/std/money_flows/threshold_pool.hsx +40 -5
- package/std/money_flows/weighted_distribution.hsx +47 -5
- package/docs/reference/std/recurring_collection.md +0 -25
- package/examples/recurring_collection/README.md +0 -3
- package/examples/recurring_collection/recurring_collection.hsx +0 -21
- package/examples/recurring_collection/recurring_collection.udl +0 -1135
- package/std/money_flows/recurring_collection.hsx +0 -72
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. 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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
25
|
-
|
|
|
26
|
-
| `create`
|
|
27
|
-
| `
|
|
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
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. 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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
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
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. 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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
30
|
-
|
|
|
31
|
-
| `create`
|
|
32
|
-
| `fund_piece_1`
|
|
33
|
-
| `fund_piece_2`
|
|
34
|
-
| `bind`
|
|
35
|
-
| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`
|
|
36
|
-
| `unfund_piece_1`
|
|
37
|
-
| `abandon`
|
|
38
|
-
| `endorsement`
|
|
39
|
-
| `lapse`
|
|
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
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. 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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
|
28
|
-
|
|
|
29
|
-
| `create`
|
|
97
|
+
| Action | Clauses lowered |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `create` | `agent description`, `moves`, `steps`, `summary` |
|
|
30
100
|
| `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
|
|
31
|
-
| `settle`
|
|
32
|
-
| `create`
|
|
33
|
-
| `carry`
|
|
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
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.2.0. 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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
33
|
-
|
|
|
34
|
-
| `create`
|
|
35
|
-
| `cancel`
|
|
36
|
-
| `activate` | `agent description`, `moves`, `steps`, `summary`
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `create`
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
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` |
|