@hyperscale0/hsx 2.0.1 → 2.0.2

package/std/money_flows/premium_forward.hsx

@@ -1,5 +1,56 @@
 module std.money_flows.premium_forward
 
+// 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 }
+// }
+// ```
 export instrument premium_forward<C>(
   payer: party,
   carrier: party,

package/std/money_flows/reconciled_payout.hsx

@@ -1,5 +1,47 @@
 module std.money_flows.reconciled_payout
 
+// 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
+// }
+// ```
 export instrument reconciled_payout<C>(
   payer: party,
   beneficiary: party,

package/std/money_flows/recurring_collection.hsx

@@ -1,5 +1,50 @@
 module std.money_flows.recurring_collection
 
+// Bounded lifecycle state tracker for recurring collections without direct balance movement.
+//
+// ### Purpose
+// `recurring_collection` tracks the ongoing execution state of a series of recurring collections.
+// It carries no money amount and no account bindings; each `collect` call records that an installment
+// occurred, and `end` closes the series permanently. It is typically paired with an external billing
+// engine or a separate debt obligation instrument.
+//
+// ### Selection guidance
+// - vs `scheduled`: `recurring_collection` moves no money and has no ledger accounts or amount partitioning.
+//   It is a pure lifecycle tracker. Choose `scheduled` when the platform itself must calculate installment amounts,
+//   enforce calendar intervals, or debit customer accounts.
+// - vs `metered`: `metered` bills variable usage against a rate card with real balance movements.
+//   `recurring_collection` only records collection lifecycle steps.
+//
+// ### Parameters
+// - `marker`: Optional descriptive text marker stored on the recurring collection record.
+//
+// ### Decision ports
+// None. State transitions are controlled directly by API actions (`collect`, `end`).
+//
+// ### Example
+// ```hsx
+// program recurring_collection_example "Recurring collection example"
+// import { recurring_collection, scheduled } from "std/money_flows"
+// party debtor: person
+// party repayment_source: business
+// party recipient: business
+// settlement obligation = scheduled {
+//   mode: obligation
+//   payer: repayment_source
+//   payee: recipient
+//   debtor: debtor
+//   amount: principal: money(SAR)
+//   count: 2
+//   every: P30D
+//   first_due: firstDueAt
+//   mandate: port mandate_evidence
+// }
+// settlement collection = recurring_collection {}
+// port mandate_evidence {
+//   allowed: [repayment_source]
+//   shape: { evidenceReference: text }
+// }
+// ```
 export instrument recurring_collection(marker: optional<text>) {
   agent_description: concat("Reach for ", words(instrument), " to track a bounded run of scheduled collections, one call per recorded installment. It carries no amount and no account, and every action only advances its own state. A settlement that debits an account on a schedule is a different shape.");
   fields {}

package/std/money_flows/rotating_pool.hsx

@@ -1,5 +1,56 @@
 module std.money_flows.rotating_pool
 
+// 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
+// }
+// ```
 export instrument rotating_pool<C>(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>) {
   when_not(membership) {
   let(member_fields): suffix_each(members, "AccountId");

package/std/money_flows/scheduled.hsx

@@ -1,5 +1,58 @@
 module std.money_flows.scheduled
 
+// 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 `recurring_collection`: `scheduled` actively moves ledger balances and partitions amounts.
+//   `recurring_collection` is a lightweight status tracker for collection runs without balance transfers.
+// - 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
+// }
+// ```
 export instrument scheduled<C>(
   payer: party,
   payee: party,

package/std/money_flows/security_deposit.hsx

@@ -1,5 +1,63 @@
 module std.money_flows.security_deposit
 
+// 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] }
+// ```
 export instrument security_deposit<C>(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>) {
   let(claim_name): claim;
   let(return_name): return;

package/std/money_flows/settlement_batch.hsx

@@ -1,5 +1,56 @@
 module std.money_flows.settlement_batch
 
+// 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 }
+// }
+// ```
 export instrument settlement_batch<C>(
   settlement_account: party,
   source_capture_refs: text,

package/std/money_flows/swap.hsx

@@ -1,4 +1,57 @@
 module std.money_flows.swap;
+
+// Atomic two-sided trade between two parties where neither leg settles alone.
+//
+// ### Purpose
+// `swap` executes atomic delivery-versus-payment (DvP) or payment-versus-payment (PvP) exchanges between two named parties.
+// Both sides fund their declared principal amounts and platform fees into a shared escrow. The exchange settles atomically
+// upon triggering the `release` condition port, paying each party the other's funded amount. If a `dispute` occurs,
+// both legs unwind and refund simultaneously. Half-funded or half-released states cannot occur.
+//
+// ### Selection guidance
+// - vs `held_payment`: `swap` is a bilateral trade where both sides must deposit funds into escrow and receive each other's
+//   disbursements simultaneously. `held_payment` is unilateral escrow where a single payer funds a payment held for a payee.
+// - vs `instant_transfer`: `instant_transfer` executes an immediate one-way transfer. `swap` coordinates two reciprocal transfers
+//   held atomically in escrow until release confirmation.
+//
+// ### Parameters
+// - `between`: List containing exactly two trade participant parties (`[side_a, side_b]`).
+// - `amounts`: Block declaring the principal money amounts for each party.
+// - `fees`: Block declaring the platform fee money amounts for each party.
+// - `release`: Condition port required to execute the atomic swap release.
+// - `dispute`: Condition port triggering unwinding and refunding of both trade legs.
+// - `side_names`: Optional custom naming block for the two sides (`first`, `second`).
+// - `lifecycle_state_order`: Optional custom ordering for lifecycle states.
+// - `action_bindings`: Optional custom action names.
+// - `parked_states`: Optional configuration for parked states.
+// - `fixed_prefix`: Optional custom prefix for generated instrument IDs.
+//
+// ### Decision ports
+// - `release`: Port authorizing atomic settlement of both trade legs.
+// - `dispute`: Port triggering atomic cancellation and refund of both parties.
+//
+// ### Example
+// ```hsx
+// program swap_example "Swap example"
+// import { swap } from "std/money_flows"
+// party buyer: business
+// party seller: business
+// settlement exchange = swap {
+//   between: [buyer, seller]
+//   amounts {
+//     buyer: buyerAmount: money(SAR)
+//     seller: sellerAmount: money(SAR)
+//   }
+//   fees {
+//     buyer: buyerFee: money(SAR)
+//     seller: sellerFee: money(SAR)
+//   }
+//   release: port release_exchange
+//   dispute: port dispute_exchange within P7D
+// }
+// port release_exchange { allowed: [buyer, seller] }
+// port dispute_exchange { allowed: [buyer, seller] }
+// ```
 export instrument swap<C>(between: list<party>, amounts: block, fees: block, release: condition, dispute: condition, side_names: optional<block>, lifecycle_state_order: optional<list<text>>, action_bindings: optional<block>, parked_states: optional<block>, fixed_prefix: optional<text>) {
   let(side_a): at(between, 1);
   let(side_b): at(between, 2);

package/std/money_flows/threshold_pool.hsx

@@ -1,5 +1,56 @@
 module std.money_flows.threshold_pool
 
+// All-or-nothing capital accumulation pool collecting commitments toward a target amount before a close deadline.
+//
+// ### Purpose
+// `threshold_pool` powers all-or-nothing crowdfunding, capital calls, collective purchasing, and consortium rounds.
+// Multiple contributors pledge commitments toward a monetary `target`. Commitments sit in escrow until the pool
+// reaches the target before `close_by` (activating and settling funds to the beneficiary), or fails (triggering full refunds).
+//
+// ### Selection guidance
+// - vs `rotating_pool`: `threshold_pool` is all-or-nothing fundraising where many contributors fund a single beneficiary.
+//   `rotating_pool` is a peer savings circle where members contribute identically in each cycle and rotate who receives the pot.
+// - vs `weighted_distribution`: `threshold_pool` pools funds inward from many contributors to one beneficiary.
+//   `weighted_distribution` pays funds outward from one source pool to many weighted recipients.
+//
+// ### Parameters
+// - `contributor`: The archetype party representing individual contributors.
+// - `beneficiary`: The beneficiary party receiving the settled pool if the target is met.
+// - `target`: Total target funding threshold in minor units of currency `C`.
+// - `commitment`: Binding name for individual contributor commitment amounts.
+// - `max_contributors`: Optional maximum count of admitted contributors.
+// - `close_by`: Stored date deadline by which the target must be met.
+// - `close_policy`: Policy determining pool close behavior (`threshold`).
+// - `overfund_policy`: Policy on commitments exceeding the target (`reject`).
+// - `cancel_policy`: Contributor withdrawal policy before close (`before_close`).
+// - `fail_policy`: Refund policy if the pool fails to hit target (`whole_commitment_refund`).
+// - `beneficiary_account`: Optional direct account reference for the beneficiary.
+// - `memo`: Optional memo text stored on the pool.
+// - `contribution_instrument`: Optional custom contribution child instrument block.
+// - `wording`: Optional custom UI wording block.
+//
+// ### Decision ports
+// None. Lifecycle transitions (`activate`, `fail`, `close`) are driven by target threshold evaluation and the `close_by` date.
+//
+// ### Example
+// ```hsx
+// program capital_pool_example "Capital pool example"
+// import { threshold_pool } from "std/money_flows"
+// party contributor: person
+// party company: business
+// settlement round = threshold_pool {
+//   contributor: contributor
+//   beneficiary: company
+//   target: targetAmount: money(SAR)
+//   commitment: commitmentAmount: money(SAR)
+//   max_contributors: 100
+//   close_by: closeBy
+//   close_policy: threshold
+//   overfund_policy: reject
+//   cancel_policy: before_close
+//   fail_policy: whole_commitment_refund
+// }
+// ```
 export instrument threshold_pool<C>(
   contributor: optional<party>,
   beneficiary: optional<party>,

package/std/money_flows/weighted_distribution.hsx

@@ -1,5 +1,59 @@
 module std.money_flows.weighted_distribution
 
+// Frozen largest-remainder distribution splitting one pool across dynamic recipients by recorded weights.
+//
+// ### Purpose
+// `weighted_distribution` distributes dividend pools, creator royalties, liquidation proceeds, and investment returns.
+// Child entitlement rows are recorded for each recipient with their respective weight. Once all recipients are recorded,
+// an evidence-backed snapshot freezes the entitlement set. Each recipient is then paid their exact largest-remainder
+// share such that all payouts sum exactly to `amount` without rounding leaks.
+//
+// ### Selection guidance
+// - vs `pooled_split`: `weighted_distribution` handles dynamic recipient rosters recorded as child rows and frozen
+//   via snapshot. `pooled_split` hardcodes a fixed set of recipients and static percentages at definition time.
+// - vs `settlement_batch`: `weighted_distribution` splits one funding pool out to many recipients.
+//   `settlement_batch` aggregates many inbound charges and adjustments into a single net payout.
+//
+// ### Parameters
+// - `source`: The funding party providing the distribution pool.
+// - `recipient`: The archetype party representing entitled recipients.
+// - `amount`: Total distribution pool in minor units of currency `C`.
+// - `record_at`: Date when entitlement eligibility is established.
+// - `weight`: Binding name for individual recipient weight amounts.
+// - `max_recipients`: Exact number of entitlement rows required before snapshotting.
+// - `snapshot`: Port freezing the entitlement set against stored decision evidence.
+// - `rounding_policy`: Mathematical rounding policy (`largest_remainder`).
+// - `withholding_policy`: Tax or withholding policy (`refuse`).
+// - `correction_policy`: Error correction policy (`new_distribution`).
+// - `flat`: Optional flat distribution configuration block.
+// - `id_prefix_override`: Optional custom prefix for generated instrument IDs.
+//
+// ### Decision ports
+// - `snapshot`: Port freezing the entitlement set with an evidence reference, preventing further entries.
+//
+// ### Example
+// ```hsx
+// program weighted_distribution_example "Weighted distribution example"
+// import { weighted_distribution } from "std/money_flows"
+// party distribution_source: business
+// party recipient: business
+// settlement proceeds = weighted_distribution {
+//   source: distribution_source
+//   recipient: recipient
+//   amount: distributableAmount: money(SAR)
+//   weight: entitlementWeight: money(SAR)
+//   max_recipients: 12
+//   record_at: recordAt
+//   snapshot: port snapshot_entitlements
+//   rounding_policy: largest_remainder
+//   withholding_policy: refuse
+//   correction_policy: new_distribution
+// }
+// port snapshot_entitlements {
+//   allowed: [distribution_source]
+//   shape: { evidenceReference: text }
+// }
+// ```
 export instrument weighted_distribution<C>(
   source: party,
   recipient: party,