@hyperscale0/hsx 2.0.1 → 2.0.3

package/src/version.ts

@@ -1,5 +1,5 @@
 /** Package version reported by the command line. */
-export const HSX_VERSION = "2.0.1";
+export const HSX_VERSION = "2.0.3";
 
 /** Canonical UDL contract version emitted by this compiler. */
 export const HSX_TARGET_UDL_VERSION = 1;

package/std/money_flows/advance.hsx

@@ -1,5 +1,50 @@
 module std.money_flows.advance
 
+// Upfront capital disbursement repaid by carving future held payment releases or over scheduled installments.
+//
+// ### Purpose
+// `advance` provides working capital, merchant cash advances, or contractor pre-funding from a funder to a recipient.
+// Repayment occurs either automatically by intercepting (carving) releases from a linked escrow hold (`against`),
+// or over calendar-anchored installment repayments (`count`, `every`, `first_due`).
+//
+// ### Selection guidance
+// - vs `credit_facility`: `advance` disburses a single upfront lump-sum principal that is repaid over time.
+//   `credit_facility` establishes a reusable revolving credit line with multiple draws up to a limit,
+//   where repayments restore available borrowing capacity.
+// - vs `conditional_disbursement`: `advance` expects repayment of the advanced principal plus optional fees.
+//   `conditional_disbursement` disburses non-repayable grants, claims, or milestone payments against external evidence.
+// - vs `held_payment`: `held_payment` holds customer funds in escrow until delivery. An `advance` can carve repayments
+//   directly out of a `held_payment`'s release using `against`.
+//
+// ### Parameters
+// - `funder`: The party providing the upfront capital.
+// - `to`: The party receiving the advance and responsible for repayment.
+// - `amount`: Total advanced principal in minor units of currency `C`.
+// - `fee`: Optional markup percentage fee charged on the advance (basis points precision).
+// - `count`: Optional number of scheduled installment repayments.
+// - `every`: Optional recurrence duration between installments (e.g. `"P30D"`).
+// - `first_due`: Optional date for the first installment repayment.
+// - `against`: Optional reference to a hold instrument whose release will be carved to repay the advance.
+//
+// ### Decision ports
+// None. Repayment is driven by linked hold releases or scheduled calendar dates.
+//
+// ### Example
+// ```hsx
+// program advance_example "Advance example"
+// import { advance } from "std/money_flows"
+// party funder: business
+// party recipient: business
+// settlement advance_payment = advance {
+//   funder: funder
+//   to: recipient
+//   amount: principal: money(SAR)
+//   fee: 2.5%
+//   count: 2
+//   every: P30D
+//   first_due: firstDueAt
+// }
+// ```
 export instrument advance<C>(
   funder: party,
   to: party,

package/std/money_flows/cancellable_booking.hsx

@@ -1,5 +1,50 @@
 module std.money_flows.cancellable_booking
 
+// Time-anchored reservation holding booking funds in escrow with dynamically quoted cancellation penalties.
+//
+// ### Purpose
+// `cancellable_booking` holds booking fees in escrow from a guest for a host until a scheduled start date.
+// It fits hospitality, travel reservations, studio rentals, event tickets, and appointments where guests
+// can cancel prior to start, but cancellation penalties depend on how close to the start date cancellation occurs.
+//
+// ### Selection guidance
+// - vs `held_payment`: Both hold money in escrow and both quote a cancellation before it is spent.
+//   `cancellable_booking` prices the penalty against the time left before `starts_at`, so the charge moves
+//   as the start approaches; `held_payment` has no start date and quotes one flat charge.
+//   Choose `cancellable_booking` whenever cancellation fees are time-sensitive.
+// - vs `security_deposit`: `security_deposit` holds funds to cover damages claimed by the holder.
+//   `cancellable_booking` holds the service fee itself and releases to the host upon `starts_at` or refunds net of penalty.
+//
+// ### Parameters
+// - `guest`: The booking customer paying the fee and receiving refunds.
+// - `host`: The service provider receiving the payout or retained cancellation penalty.
+// - `amount`: Total booking price in minor units of currency `C`.
+// - `starts_at`: Stored ISO 8601 date when the booking begins.
+// - `late_penalty_bps`: Penalty in basis points applied when cancelling within the late window.
+// - `late_within`: ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days).
+// - `early_penalty_bps`: Penalty in basis points applied when cancelling before the late window.
+// - `offer_life`: ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`).
+//
+// ### Decision ports
+// None. Action transitions are driven by guest API calls (`take`, `cancel`, `confirm`) and scheduled completion (`complete` due at `starts_at`).
+//
+// ### Example
+// ```hsx
+// program studio_booking "Studio booking"
+// import { cancellable_booking } from "std/money_flows"
+// party guest: person
+// party studio: business
+// settlement studio_session = cancellable_booking {
+//   guest: guest
+//   host: studio
+//   amount: sessionPrice: money(SAR)
+//   starts_at: startsAt
+//   late_penalty_bps: 5000
+//   late_within: "P2D"
+//   early_penalty_bps: 1000
+//   offer_life: "PT30M"
+// }
+// ```
 export instrument cancellable_booking<C>(
   guest: party,
   host: party,

package/std/money_flows/captured_payment.hsx

@@ -1,5 +1,60 @@
 module std.money_flows.captured_payment
 
+// Two-phase authorization and capture payment flow for card and merchant processing.
+//
+// ### Purpose
+// `captured_payment` reserves funds against a payer's account and allows the payee to capture the authorized
+// balance in one or multiple slices before a reservation expiry date (`reserve_until`). It fits ecommerce checkouts,
+// card processing, hotel authorizations, and pay-at-pump fuel payments where final amounts vary or settle later.
+//
+// ### Selection guidance
+// - vs `instant_transfer`: `instant_transfer` immediately transfers money from payer to payee in a single irreversible
+//   step without reservation or settlement delays. `captured_payment` separates authorization from capture, allowing
+//   incremental captures, voids, amount corrections via the `correction` port, and external network reversals via `external_reversal`.
+// - vs `held_payment`: `held_payment` holds the full amount in third-party escrow pending release. `captured_payment`
+//   reserves funds directly on payer balance and settles incrementally directly to payee.
+//
+// ### Parameters
+// - `payer`: Party whose account balance is reserved during authorization.
+// - `payee`: Beneficiary party capturing authorized funds.
+// - `amount`: Maximum authorized reservation in minor units of currency `C`.
+// - `reserve_until`: Expiration date for the authorization hold.
+// - `correction`: Condition port allowing post-settlement amount corrections.
+// - `external_reversal`: Condition port allowing external processor chargebacks/reversals.
+// - `capture_mode`: Text specifying capture behavior (`"slice"` or `"full"`).
+// - `correction_mode`: Text specifying correction behavior.
+// - `negative_position`: Text policy when correction creates an overdraft.
+// - `timeout`: Timeout duration string for pending authorizations.
+// - `derived_amount`: Optional block declaring percentage fee calculation.
+//
+// ### Decision ports
+// - `correction`: Condition allowing payee or processor to submit an amount correction after settlement.
+// - `external_reversal`: Condition allowing bank or card network to execute an external reversal.
+//
+// ### Example
+// ```hsx
+// program captured_payment_example "Captured payment example"
+// import { captured_payment } from "std/money_flows"
+// party payer: person
+// party payee: business
+// settlement card_payment = captured_payment {
+//   payer: payer
+//   payee: payee
+//   amount: authorizedAmount: money(SAR)
+//   reserve_until: reserveUntil
+//   correction: port correct_capture
+//   external_reversal: port reverse_capture within P14D
+//   capture_mode: partial_then_full
+//   correction_mode: full_only
+//   negative_position: reject
+//   timeout: reject
+// }
+// port correct_capture { allowed: [payee] }
+// port reverse_capture {
+//   allowed: [payee]
+//   shape: { externalReference: text }
+// }
+// ```
 export instrument captured_payment<C>(payer: party, payee: party, amount: money<C>, reserve_until: date, correction: condition, external_reversal: condition, capture_mode: text, correction_mode: text, negative_position: text, timeout: text, derived_amount: optional<block>) {
   let(correction_name): correction;
   let(reversal_name): external_reversal;

package/std/money_flows/conditional_disbursement.hsx

@@ -1,5 +1,51 @@
 module std.money_flows.conditional_disbursement
 
+// Capped disbursement from a source party to a destination party gated on stored external decision evidence.
+//
+// ### Purpose
+// `conditional_disbursement` manages evidence-contingent payouts subject to a cumulative cap.
+// It fits insurance claim settlements, grant tranches, subsidy distributions, and escrow milestones
+// where each approved payment requires explicit external evidence and the total paid must not exceed `cap`.
+//
+// ### Selection guidance
+// - vs `advance`: `conditional_disbursement` disburses non-repayable funds against external evidence
+//   up to a declared cap. `advance` pays money up front with the expectation of repayment through carved
+//   hold releases or scheduled installments.
+// - vs `instant_transfer`: `instant_transfer` moves money immediately with no evidence gate or cap.
+//   `conditional_disbursement` requires an external decision port and evidence reference before any child amount moves.
+//
+// ### Parameters
+// - `source`: The funding party providing the money.
+// - `destination`: The beneficiary party receiving approved disbursements.
+// - `cap`: Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`.
+// - `amount`: Binding name for child approval amount values.
+// - `decision`: Port conditioning approval, requiring evidence reference.
+// - `reopen_policy`: Policy for reopening closed disbursements (`refuse`).
+// - `recovery_policy`: Policy for recovering overpayments (`separate_transfer`).
+//
+// ### Decision ports
+// - `decision`: External port providing decision evidence required to approve child disbursement amounts.
+//
+// ### Example
+// ```hsx
+// program conditional_disbursement_example "Conditional disbursement example"
+// import { conditional_disbursement } from "std/money_flows"
+// party source: business
+// party claimant: person
+// settlement claim_payment = conditional_disbursement {
+//   source: source
+//   destination: claimant
+//   cap: policyLimit: money(SAR)
+//   amount: approvedAmount: money(SAR)
+//   decision: port approve_claim
+//   reopen_policy: refuse
+//   recovery_policy: separate_transfer
+// }
+// port approve_claim {
+//   allowed: [source]
+//   shape: { evidenceReference: text }
+// }
+// ```
 export instrument conditional_disbursement<C>(
   source: party,
   destination: party,

package/std/money_flows/credit_facility.hsx

@@ -1,5 +1,62 @@
 module std.money_flows.credit_facility
 
+// Revolving credit line providing reusable borrowing capacity up to a limit backed by scheduled obligations.
+//
+// ### Purpose
+// `credit_facility` manages revolving commercial credit, inventory financing, and overdraft facilities.
+// A borrower can draw funds multiple times up to `limit` into `draw_destination`. Each draw creates a child
+// record linked to a scheduled `obligation`. Repayments restore available borrowing capacity until `expires_at`.
+//
+// ### Selection guidance
+// - vs `advance`: `credit_facility` provides revolving, reusable credit lines where multiple draws can occur
+//   and repayments restore capacity. `advance` is a single upfront lump-sum disbursement with a fixed repayment plan.
+// - vs `scheduled`: `scheduled` defines repayment installments or recurring transfers. `credit_facility` delegates
+//   draw repayments to a `scheduled` obligation while tracking total facility utilization and limit compliance.
+//
+// ### Parameters
+// - `lender`: The financing institution or party providing the credit capacity.
+// - `borrower`: The borrowing party authorized to draw against the facility limit.
+// - `draw_destination`: Account or party receiving disbursed draw proceeds.
+// - `limit`: Total revolving borrowing limit in minor units of currency `C`.
+// - `expires_at`: Expiration date after which new draws cannot be opened.
+// - `obligation`: Reference to a scheduled obligation instrument handling draw repayments.
+// - `availability_policy`: Facility capacity availability policy (`revolving`).
+// - `expiry_policy`: Policy on facility expiration (`freeze_draws`).
+// - `close_policy`: Policy on facility closure (`no_open_draws`).
+//
+// ### Decision ports
+// None on the facility itself. Mandates and decision ports are declared on the linked `obligation` instrument.
+//
+// ### Example
+// ```hsx
+// program credit_facility_example "Credit facility example"
+// import { credit_facility, scheduled } from "std/money_flows"
+// party lender: business
+// party borrower: business
+// party draw_destination: business
+// party repayment_source: business
+// settlement repayment = scheduled {
+//   mode: obligation
+//   payer: repayment_source
+//   payee: lender
+//   debtor: borrower
+//   amount: principal: money(SAR)
+//   count: 2
+//   every: P30D
+//   first_due: firstDueAt
+// }
+// settlement facility = credit_facility {
+//   lender: lender
+//   borrower: borrower
+//   draw_destination: draw_destination
+//   limit: facilityLimit: money(SAR)
+//   expires_at: expiresAt
+//   obligation: repayment.obligation
+//   availability_policy: revolving
+//   expiry_policy: freeze_draws
+//   close_policy: no_open_draws
+// }
+// ```
 export instrument credit_facility<C>(
   lender: party,
   borrower: party,

package/std/money_flows/held_payment.hsx

@@ -1,6 +1,66 @@
 module std.money_flows.held_payment
 
-export instrument held_payment<C>(payer: party, payee: party, amount: money<C>, release: condition, fees: optional<block>, on_cancel: optional<block>, derived_amount: optional<block>, release_to: optional<party>, whole_amount: optional<block>, release_action: optional<text>, whole_fee: optional<money<C>>, reference: optional<text>, upstream: optional<ref>, id_prefix_override: optional<text>) {
+// Escrow settlement holding funds from a payer before releasing to a payee upon a verified condition or deadline.
+//
+// ### Purpose
+// `held_payment` holds customer funds in a dedicated product escrow account away from both payer and payee.
+// It fits milestone-gated commerce, vehicle escrow, contractor holdbacks, and goods purchases where funds
+// must remain reserved until delivery confirmation or inspection.
+//
+// ### Selection guidance
+// - vs `cancellable_booking`: Both hold funds in custody and both can quote a cancellation before it is
+//   spent. `held_payment` quotes one flat charge declared by `cancel_charge_bps`, because it has no scheduled
+//   start to price against, and `on_cancel` remains the way to unwind it on static splits instead.
+//   Choose `cancellable_booking` when the charge must follow the time left before a scheduled start date.
+// - vs `security_deposit`: `held_payment` releases or cancels the principal according to predefined splits.
+//   Choose `security_deposit` when the holder must assess damages and claim an arbitrary partial amount
+//   via a `decided amount` clause while returning the unspent remainder to the payer.
+// - vs `swap`: `held_payment` is a one-way transfer from payer to payee. Choose `swap` for bilateral or
+//   multi-party atomic exchanges where all parties must fund their legs into escrow before simultaneous release.
+// - vs `premium_forward`: Choose `premium_forward` for insurance premium collection requiring carrier policy
+//   binding conditions, broker commission retention, policy endorsements, and lapse schedules.
+//
+// ### Parameters
+// - `payer`: The funding party providing the money.
+// - `payee`: The beneficiary party receiving the released funds.
+// - `amount`: Total amount in minor units of currency `C`.
+// - `release`: Condition required to release funds. Supports decision ports (`port <name>`), date deadlines
+//   (`at(<date>)`), or disjunctions (`port <name> | at(<date>)`).
+// - `fees`: Optional block declaring percentage or fixed fee cuts, e.g. `{ buyer: 1%, seller: 2% }`.
+// - `on_cancel`: Optional block defining refund splits if cancelled while funded, e.g. `(funded) { buyer: 90%, seller: 10% }`.
+// - `derived_amount`: Optional block declaring machine-derived fees calculated as a percentage of another field.
+// - `release_to`: Optional third-party destination for release.
+// - `whole_amount`: Optional block enabling single-action funding and release of principal plus on-top fee.
+// - `release_action`: Optional custom name for the release action.
+// - `whole_fee`: Optional money amount for the whole-amount fee.
+// - `reference`: Optional string reference stored on the instance.
+// - `upstream`: Optional reference to a parent instrument.
+// - `id_prefix_override`: Optional custom prefix for generated instrument IDs.
+// - `cancel_charge_bps`: Optional cancellation charge in basis points. Declaring it gives the settlement a
+//   quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both,
+//   `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee.
+// - `cancel_offer_life`: ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`.
+//
+// ### Decision ports
+// - `release`: Port deciding release authorization, answered by allowed parties declared in the port.
+//
+// ### Example
+// ```hsx
+// program held_payment_example "Held payment example"
+// import { held_payment } from "std/money_flows"
+// party buyer: person
+// party seller: business
+// settlement sale = held_payment {
+//   payer: buyer
+//   payee: seller
+//   amount: price: money(SAR)
+//   fees { buyer: 1% }
+//   on_cancel(funded) { buyer: 100% }
+//   release: port confirm_delivery | at(releaseDueAt)
+// }
+// port confirm_delivery { allowed: [buyer] }
+// ```
+export instrument held_payment<C>(payer: party, payee: party, amount: money<C>, release: condition, fees: optional<block>, on_cancel: optional<block>, derived_amount: optional<block>, release_to: optional<party>, whole_amount: optional<block>, release_action: optional<text>, whole_fee: optional<money<C>>, reference: optional<text>, upstream: optional<ref>, id_prefix_override: optional<text>, cancel_charge_bps: optional<integer>, cancel_offer_life: optional<text>) {
   let(release_name): release;
   let(release_actor_text): if_eq(len(release_allowed), 1, words(at(release_allowed, 1)), concat("a party allowed by ", release));
   let(payer_account_field): camel(concat(payer, "_account_id"));
@@ -19,6 +79,45 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       }
     }
   }
+  when(cancel_charge_bps) {
+    when(on_cancel) {
+      unsupported {
+        code: HSX1110;
+        message: "a quoted cancellation cannot combine with on_cancel splits";
+        fix: "drop on_cancel and let cancel_charge_bps price the cancellation";
+      }
+    }
+    when(payee_fee) {
+      unsupported {
+        code: HSX1110;
+        message: "a quoted cancellation cannot combine with a payee fee";
+        fix: "drop the payee fee, or unwind through on_cancel splits instead of a quote";
+      }
+    }
+    when(whole_amount) {
+      unsupported {
+        code: HSX1110;
+        message: "a quoted cancellation cannot combine with whole_amount";
+        fix: "drop whole_amount, which cancels the whole hold without quoting it";
+      }
+    }
+    when_not(cancel_offer_life) {
+      unsupported {
+        code: HSX1110;
+        message: "a quoted cancellation needs cancel_offer_life";
+        fix: "declare how long the quote stays open, for example PT30M";
+      }
+    }
+  }
+  when(cancel_offer_life) {
+    when_not(cancel_charge_bps) {
+      unsupported {
+        code: HSX1110;
+        message: "cancel_offer_life needs a nonzero cancel_charge_bps to quote";
+        fix: "declare the cancellation charge in basis points, or drop cancel_offer_life";
+      }
+    }
+  }
   let(payer_bps): basis_points(payer_fee);
   let(payee_bps): basis_points(payee_fee);
   let(net_bps): sub(10000, payee_fee);
@@ -103,6 +202,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       when_not(cancel_splits) {
         states created funded disputed released;
         when(on_cancel) { states cancelled; }
+        when(cancel_charge_bps) { states cancellation_quoted cancelled settled; }
         states abandoned;
       }
       when(cancel_splits) { states created funding_1 funded disputed releasing_1 released cancelling_1 cancelled abandoned; }
@@ -119,8 +219,17 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     when_not(payee_fee) {
       when_not(cancel_splits) {
         on fund_piece_1: created -> funded;
-        on [release_name]: funded -> released;
-        when(release_deadline) { on release_on_deadline: funded -> released; }
+        when_not(cancel_charge_bps) {
+          on [release_name]: funded -> released;
+          when(release_deadline) { on release_on_deadline: funded -> released; }
+        }
+        when(cancel_charge_bps) {
+          on [release_name]: funded | cancellation_quoted -> released;
+          when(release_deadline) { on release_on_deadline: funded | cancellation_quoted -> released; }
+          on quote_cancellation: funded -> cancellation_quoted;
+          on cancel: cancellation_quoted -> cancelled;
+          on retain_cancellation_charge: cancelled -> settled;
+        }
         when(on_cancel) { on cancel: funded -> cancelled; }
       }
       when(cancel_splits) {
@@ -411,6 +520,44 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
   }
+  when(cancel_charge_bps) {
+    action quote_cancellation {
+      agent_description: concat("Price the cancellation and hold that price open. No money moves. The charge the ", words(payee), " keeps and the refund the ", words(payer), " gets back are worked out here and frozen for ", cancel_offer_life, ", after which a fresh call prices it again. Call cancel to spend the quote.");
+      summary: "Price the cancellation and hold that price open";
+      when(release_deadline) { deadline { field: release_deadline; }; }
+      quote {
+        baseField: amount;
+        chargeRef: cancellationChargeAmount;
+        charges: [{ bps: cancel_charge_bps; }];
+        expires { offset: cancel_offer_life; }
+        fixes: [amount, payer_account_field];
+        netDestinationField: payer_account_field;
+        netRef: cancellationRefundAmount;
+      }
+      moves: [];
+      steps: [];
+    }
+    action cancel {
+      let(metadata_instrument): "metadata.instrumentId";
+      let(metadata_instance): "metadata.instrumentInstanceId";
+      let(metadata_phase): "metadata.phase";
+      agent_description: concat("Spend the frozen quote and return the net refund to the ", words(payer), ". This moves money and does not reverse. It needs an un-expired quote from quote_cancellation, and the charge that refund left behind goes to the ", words(payee), " through retain_cancellation_charge.");
+      summary: concat("Spend the quoted cancellation and return the net to the ", words(payer));
+      commit: quote_cancellation;
+      when(release_deadline) { deadline { field: release_deadline; }; }
+      moves: [{ key: refund; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationRefundAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payer_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: cancel; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.escrowAccountId; }; }; capture: { cancelTransferTransferId: transferId; }; }];
+      steps: [];
+    }
+    action retain_cancellation_charge {
+      let(metadata_instrument): "metadata.instrumentId";
+      let(metadata_instance): "metadata.instrumentInstanceId";
+      let(metadata_phase): "metadata.phase";
+      agent_description: concat("Pay the quoted cancellation charge out of escrow to the ", words(payee), ". This moves money and does not reverse. The settlement must already be cancelled, so the figure is the one the quote fixed and the escrow ends empty.");
+      summary: concat("Pay the quoted cancellation charge to the ", words(payee));
+      moves: [{ key: charge; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationChargeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payee_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: retain_cancellation_charge; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.escrowAccountId; }; }; capture: { retainCancellationChargeTransferId: transferId; }; }];
+      steps: [];
+    }
+  }
   when(payee_fee) {
     when_not(on_cancel) {
       action fund_piece_2 {

package/std/money_flows/instant_transfer.hsx

@@ -1,5 +1,47 @@
 module std.money_flows.instant_transfer
 
+// Direct, single-step push transfer from payer to payee with optional tiered or percentage fees.
+//
+// ### Purpose
+// `instant_transfer` debits a payer and credits a payee immediately in a single execution step.
+// It fits peer-to-peer transfers, direct disbursements, instant payouts, wallet reloads, and simple point-of-sale payments.
+//
+// ### Selection guidance
+// - vs `captured_payment`: `instant_transfer` moves money in one atomic step without prior authorization holds,
+//   incremental captures, voids, or post-settlement correction ports. Use `captured_payment` when authorization must precede capture.
+// - vs `conditional_disbursement`: `instant_transfer` executes immediately without external decision evidence
+//   or cumulative cap tracking. Use `conditional_disbursement` when payments require evidence submission or aggregate milestone caps.
+// - vs `held_payment`: `instant_transfer` never holds funds in an intermediary escrow account.
+//
+// ### Parameters
+// - `payer`: Funding party whose account is debited.
+// - `payee`: Recipient party whose account is credited.
+// - `amount`: Transfer amount in minor units of currency `C`.
+// - `fees`: Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee.
+// - `derived_amount`: Optional block declaring derived platform fees calculated from the transfer amount.
+//
+// ### Decision ports
+// None. Transfers execute immediately upon invocation.
+//
+// ### Example
+// ```hsx
+// program instant_transfer_example "Instant transfer example"
+// import { instant_transfer } from "std/money_flows"
+// party customer: person
+// party merchant: business
+// settlement transfer = instant_transfer {
+//   payer: customer
+//   payee: merchant
+//   amount: transferAmount: money(SAR)
+//   fees {
+//     customer: checkoutFee: money(SAR)
+//     merchant {
+//       tier { from: 0, to: 10000, fee: 1% }
+//       tier { from: 10000, fee: highValueFee: money(SAR) }
+//     }
+//   }
+// }
+// ```
 export instrument instant_transfer<C>(payer: party, payee: party, amount: money<C>, fees: optional<block>, derived_amount: optional<block>) {
   let(payer_fee): get(fees, payer);
   let(payee_fee): get(fees, payee);

package/std/money_flows/metered.hsx

@@ -1,5 +1,46 @@
 module std.money_flows.metered
 
+// Usage-based billing against a committed rate card over an open period until a stored close date.
+//
+// ### Purpose
+// `metered` bills customers for variable resource consumption such as API requests, compute hours,
+// storage gigabytes, or utility consumption. The rate card is fixed when the period opens, and individual
+// usage events are charged incrementally until the billing period closes on `close_by`.
+//
+// ### Selection guidance
+// - vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
+//   rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
+//   with predetermined amounts or installments.
+// - vs `recurring_collection`: `metered` calculates and executes real ledger transfers for each usage charge.
+//   `recurring_collection` is a lightweight status tracker for collection runs without balance transfers or rate cards.
+// - vs `instant_transfer`: `instant_transfer` executes a single immediate payment. `metered` manages a stateful
+//   open billing cycle accepting multiple usage charges under a fixed rate card.
+//
+// ### Parameters
+// - `payer`: The customer being billed for usage.
+// - `payee`: The service provider receiving usage revenue.
+// - `close_by`: Date when the metering period closes, preventing further usage charges.
+// - `rates`: Block mapping rate metric names to their per-unit money prices committed at period open.
+//
+// ### Decision ports
+// None. Charges are driven by caller billing actions and period closure.
+//
+// ### Example
+// ```hsx
+// program metered_example "Metered example"
+// import { metered } from "std/money_flows"
+// party customer: business
+// party provider: business
+// settlement usage = metered {
+//   payer: customer
+//   payee: provider
+//   close_by: periodEnd
+//   rates {
+//     api_call: callRate: money(SAR)
+//     storage_gib: storageRate: money(SAR)
+//   }
+// }
+// ```
 export instrument metered(
   payer: party,
   payee: party,

package/std/money_flows/pooled_split.hsx

@@ -1,5 +1,46 @@
 module std.money_flows.pooled_split
 
+// Fixed multi-recipient revenue or period pool funded share-by-share and released automatically on a due date.
+//
+// ### Purpose
+// `pooled_split` pools a period total from one payer and splits it across a fixed roster of recipients
+// according to predetermined percentage shares (with integer division remainder assigned to `remainder_to`).
+// Callers fund the pool share-by-share, and payouts disburse automatically to each recipient on `payout_due`.
+//
+// ### Selection guidance
+// - vs `weighted_distribution`: `pooled_split` hardcodes a fixed set of recipients and static percentage shares
+//   directly in the contract. `weighted_distribution` handles dynamic recipient counts where arbitrary weights
+//   are recorded as child records and frozen via a snapshot port before distribution.
+// - vs `settlement_batch`: `settlement_batch` aggregates multiple payments from many sources into one net payout.
+//   `pooled_split` takes one period total from one payer and partitions it out to multiple recipients.
+//
+// ### Parameters
+// - `payer`: The funding party providing the pooled amount.
+// - `amount`: Total pooled amount in minor units of currency `C`.
+// - `payout_due`: Stored payout date when the pool distributes to all recipients.
+// - `split`: Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders.
+//
+// ### Decision ports
+// None. Payout distribution triggers automatically from the stored `payout_due` date.
+//
+// ### Example
+// ```hsx
+// program pooled_split_example "Pooled split example"
+// import { pooled_split } from "std/money_flows"
+// party payer: business
+// party first_recipient: business
+// party second_recipient: business
+// settlement pool = pooled_split {
+//   payer: payer
+//   amount: poolAmount: money(SAR)
+//   payout_due: payoutDueAt
+//   split {
+//     first_recipient: 60%
+//     second_recipient: 40%
+//     remainder_to: first_recipient
+//   }
+// }
+// ```
 export instrument pooled_split<C>(payer: party, amount: money<C>, payout_due: date, split: block) {
   let(recipients): keys_except(split, "remainder_to");
   let(recipient_count): len(recipients);