@hyperscale0/hsx 2.4.1 → 3.0.0

package/docs/reference/grammar.md

@@ -1,38 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# Grammar vocabulary
-
-The parser is hand-written. This page records the exported lexer vocabulary, the UDL clause vocabulary it binds, and the current standard-library module names.
-
-## Keywords
-
-`action`, `as`, `asset`, `commit`, `const`, `expect`, `expose`, `expires`, `export`, `from`, `import`, `instrument`, `module`, `party`, `port`, `program`, `quote`, `rate`, `reconcile`, `settlement`, `subject`, `type`, `use`
-
-## Punctuation
-
-`{`, `}`, `(`, `)`, `[`, `]`, `:`, `,`, `;`, `=`, `|`, `.`, `<`, `>`, `?` and `->`
-
-## Typed clause spellings
-
-`funding`, `receipt distribution`, `requires allocation`, `allocation`, `contributions`, `allocate`, `contribution stage`, `date order`, `unique`, `transitions refs`, `cascade`, `action library`, `agent description`, `calls`, `requires input`, `engine owned`, `capture engine`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `piece plan`, `piece stage`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template binding`, `template id`, `title`, `update`, `request authority`
-
-## Standard-library modules
-
-- `advance`
-- `cancellable_booking`
-- `captured_payment`
-- `conditional_disbursement`
-- `credit_facility`
-- `held_payment`
-- `instant_transfer`
-- `metered`
-- `pooled_split`
-- `premium_forward`
-- `reconciled_payout`
-- `rotating_pool`
-- `scheduled`
-- `security_deposit`
-- `settlement_batch`
-- `swap`
-- `threshold_pool`
-- `weighted_distribution`

package/docs/reference/std/advance.md

@@ -1,112 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# advance
-
-Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
-
-## Export
-
-`advance<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `funder` | `party` | Yes | The party providing the upfront capital. |
-| `to` | `party` | Yes | The party receiving the advance and responsible for repayment. |
-| `amount` | `money<C>` | Yes | Total advanced principal in minor units of currency `C`. |
-| `fee` | `optional<percent>` | No | Optional markup percentage fee charged on the advance (basis points precision). |
-| `count` | `optional<integer>` | No | Optional number of scheduled installment repayments. |
-| `every` | `optional<text>` | No | Optional recurrence duration between installments (e.g. `"P30D"`). |
-| `first_due` | `optional<date>` | No | Optional date for the first installment repayment. |
-| `against` | `optional<ref>` | No | Optional reference to a hold instrument whose release will be carved to repay the advance. |
-| `repayment_source` | `optional<party>` | No | Optional party repaying when distinct from the capital recipient. |
-| `profit_to` | `optional<party>` | No | Optional recipient of profit, separated from principal repayments. |
-| `dated` | `optional<boolean>` | No | Require an explicit signed date for each repayment instead of duration offsets. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-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.
-- `repayment_source`: Optional party repaying when distinct from the capital recipient.
-- `profit_to`: Optional recipient of profit, separated from principal repayments.
-- `dated`: Require an explicit signed date for each repayment instead of duration offsets.
-- `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
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `id prefix`
-- `moves`
-- `partitions`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `disburse` | `agent description`, `moves`, `steps`, `summary` |
-| `settle` | `agent description`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `disburse` | `agent description`, `moves`, `steps`, `summary` |
-| `collect_repayment_[i]` | `agent description`, `due`, `moves`, `steps`, `summary` |

package/docs/reference/std/cancellable_booking.md

@@ -1,159 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# cancellable_booking
-
-Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/cancellable_booking.hsx)
-
-## Export
-
-`cancellable_booking<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `guest` | `optional<party>` | No | The booking customer paying the fee and receiving refunds. |
-| `host` | `optional<party>` | No | The service provider receiving the payout or retained cancellation penalty. |
-| `amount` | `optional<money<C>>` | No | Total booking price in minor units of currency `C`. |
-| `starts_at` | `optional<date>` | No | Stored ISO 8601 date when the booking begins. |
-| `late_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling within the late window. |
-| `late_within` | `optional<text>` | No | ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days). |
-| `early_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling before the late window. |
-| `offer_life` | `optional<text>` | No | ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`). |
-| `cancel_bands` | `optional<list<block>>` | No | Supply cancel_bands to select deposit/balance custody instead of quoted cancellation. |
-| `price_value` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `supplier_cost` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `departure` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `balance_before` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `confirmation_window` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
-| `unpaid_band` | `optional<integer>` | No | The unpaid_band index selects a retained deposit policy. |
-| `acceptance` | `optional<block>` | No | acceptance optionally supplies an aggregate gate. |
-| `deposit_bps` | `optional<integer>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
-| `tax_bps` | `optional<integer>` | No | tax_bps applies to margin after the supplier share. |
-| `authority_type` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
-| `supplier_role` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
-| `collects` | `optional<json>` | No | collects optionally cascades named actions to linked instruments on deposit. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-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"
-}
-```
-
-### Finite cancellation bands
-
-Supply cancel_bands to select deposit/balance custody instead of quoted cancellation.
-Each band has name, refund (full, balance or none), starts_at after the first band,
-and supplier_bps when money is retained. The unpaid_band index selects a retained
-deposit policy. Omit it to return the deposit; a full-refund band also returns it. price_value and supplier_cost fix the price; deposit_bps derives
-the deposit. balance_before and confirmation_window are positive fixed durations
-relative to departure. tax_bps applies to margin after the supplier share.
-authority_type and supplier_role bind release to a consumed confirmation decision.
-collects optionally cascades named actions to linked instruments on deposit.
-acceptance optionally supplies an aggregate gate. All actions are private until
-expose selects them. Ordered band starts and deadlines prevent a late sweep from
-extending an earlier band's cancellation rights. Full timeout refund returns price.
-Seven derivations suffice for three bands; larger finite policies use up to the
-UDL bound of 64 derived amounts. shift_date(date, duration, "before") subtracts a
-fixed duration; omitting the direction adds it. Invalid dates or durations refuse.
-
-## Declared clauses
-
-- `agent description`
-- `caller parked states`
-- `cascade`
-- `commit`
-- `deadline`
-- `description`
-- `distinct parties`
-- `due`
-- `id prefix`
-- `input`
-- `moves`
-- `partitions`
-- `port`
-- `quote`
-- `requires drained`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-- `unique`
-- `updates`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `take` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `complete` | `due`, `moves`, `steps`, `summary` |
-| `cancel` | `agent description`, `moves`, `quote`, `steps`, `summary` |
-| `confirm` | `agent description`, `commit`, `moves`, `steps`, `summary` |
-| `retain` | `agent description`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `deadline`, `steps`, `unique` |
-| `deposit` | `agent description`, `cascade`, `deadline`, `moves`, `port`, `steps` |
-| `expire` | `agent description`, `due`, `requires drained`, `steps` |
-| `[balance_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
-| `[open_action]` | `agent description`, `due`, `steps` |
-| `[cancel_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
-| `cancel_unpaid` | `agent description`, `due`, `moves`, `steps` |
-| `await_confirmation` | `agent description`, `due`, `steps` |
-| `confirm` | `agent description`, `deadline`, `input`, `steps`, `updates` |
-| `release` | `agent description`, `moves`, `steps` |
-| `refund_unconfirmed` | `agent description`, `due`, `moves`, `steps` |

package/docs/reference/std/captured_payment.md

@@ -1,115 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# captured_payment
-
-Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captured_payment.hsx)
-
-## Export
-
-`captured_payment<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `payer` | `party` | Yes | Party whose account balance is reserved during authorization. |
-| `payee` | `party` | Yes | Beneficiary party capturing authorized funds. |
-| `amount` | `money<C>` | Yes | Maximum authorized reservation in minor units of currency `C`. |
-| `reserve_until` | `date` | Yes | Expiration date for the authorization hold. |
-| `correction` | `condition` | Yes | Condition port allowing post-settlement amount corrections. |
-| `external_reversal` | `condition` | Yes | Condition port allowing external processor chargebacks/reversals. |
-| `derived_amount` | `optional<block>` | No | Optional block declaring percentage fee calculation. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-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.
-- `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
-}
-port correct_capture { allowed: [payee] }
-port reverse_capture {
-  allowed: [payee]
-  shape: { externalReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `deadline`
-- `description`
-- `due`
-- `input`
-- `moves`
-- `port`
-- `sandbox failure point`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `correction`
-- `external_reversal`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `authorize` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `capture` | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `capture_more` | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary` |
-| `settle` | `agent description`, `deadline`, `moves`, `steps`, `summary` |
-| `void` | `agent description`, `moves`, `steps`, `summary` |
-| `expire` | `due`, `moves`, `steps`, `summary` |
-| `settle_on_expiry` | `due`, `moves`, `steps`, `summary` |
-| `[correction_name]` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
-| `[reversal_name]` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary` |

package/docs/reference/std/conditional_disbursement.md

@@ -1,101 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# conditional_disbursement
-
-Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flows/conditional_disbursement.hsx)
-
-## Export
-
-`conditional_disbursement<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `source` | `party` | Yes | The funding party providing the money. |
-| `destination` | `party` | Yes | The beneficiary party receiving approved disbursements. |
-| `cap` | `money<C>` | Yes | Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`. |
-| `amount` | `money<C>` | Yes | Binding name for child approval amount values. |
-| `decision` | `condition` | Yes | Port conditioning approval, requiring evidence reference. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-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.
-
-### 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
-}
-port approve_claim {
-  allowed: [source]
-  shape: { evidenceReference: text }
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `capture input`
-- `description`
-- `id prefix`
-- `input`
-- `moves`
-- `port`
-- `steps`
-- `summary`
-- `title`
-- `unique`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-- `decision`
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `deny` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
-| `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `pay` | `agent description`, `moves`, `steps`, `summary` |

package/docs/reference/std/credit_facility.md

@@ -1,108 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# credit_facility
-
-Source: [`std/money_flows/credit_facility.hsx`](../../../std/money_flows/credit_facility.hsx)
-
-## Export
-
-`credit_facility<C>`
-
-## Parameters
-
-| Parameter | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `lender` | `party` | Yes | The financing institution or party providing the credit capacity. |
-| `borrower` | `party` | Yes | The borrowing party authorized to draw against the facility limit. |
-| `draw_destination` | `party` | Yes | Account or party receiving disbursed draw proceeds. |
-| `limit` | `money<C>` | Yes | Total revolving borrowing limit in minor units of currency `C`. |
-| `expires_at` | `date` | Yes | Expiration date after which new draws cannot be opened. |
-| `obligation` | `ref` | Yes | Reference to a scheduled obligation instrument handling draw repayments. |
-
-Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
-
-## Module guidance
-
-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.
-
-### 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
-}
-```
-
-## Declared clauses
-
-- `agent description`
-- `description`
-- `due`
-- `id prefix`
-- `moves`
-- `steps`
-- `summary`
-- `title`
-
-This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
-
-## Decision ports
-
-None.
-
-## Actions and clauses
-
-| Action | Clauses lowered |
-| --- | --- |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `freeze` | `due`, `moves`, `steps`, `summary` |
-| `close` | `agent description`, `moves`, `steps`, `summary` |
-| `create` | `agent description`, `moves`, `steps`, `summary` |
-| `resolve` | `agent description`, `moves`, `steps`, `summary` |