@hyperscale0/hsx 2.4.0 → 3.0.0

package/std/SEMANTICS.md

@@ -1,44 +0,0 @@
-# Standard library money flows semantics
-
-This document records the runtime semantics and settlement mechanics of standard library modules under `std.money_flows`. The compiler and its unit specifications under `test/` remain the authoritative implementation reference.
-
-## Direct checkout and card
-
-- `instant_transfer` stores the amount, currency, payer, and payee. Action `create` opens the payment record without moving funds. Action `pay_piece_1` and subsequent piece actions execute the money movements, transitioning to state `paid`. A payer fee executes as an `on_top` move. A payee fee carves out of the base amount. Exact, basis-point, and tiered rules generate fee fields and `feeRules`. The finest common refinement of all fee cuts produces piece fields and one partition. Floor rounding sends minor-unit remainder to the designated non-fee recipient. A derived amount adds a floor percentage field, `derivedAmounts`, a platform party account, and its own transfer piece.
-- `captured_payment` stores authorization total, reserve and reversal dates, and party accounts. The instrument moves through `created`, `authorized`, optional `partially_captured`, `settled`, `voided`, `expired`, `corrected`, or `reversed`. Action `authorize` reserves custody on the payer balance. Actions `capture` and `capture_more` consume the authorized balance using partial posts. Action `settle` posts the captured amount. Actions `void` and `expire` release the reserve. Actions for payee correction and external reversal use their declared condition ports and deadline windows. Derived fees use the same floor, partition, bearer, and position rules as direct payment. Four unused signature knobs (`capture_mode`, `correction_mode`, `negative_position`, `timeout`) are pruned.
-
-## Custody and escrow
-
-- `held_payment` reserves every refined piece in a dedicated escrow account before release. It posts release pieces, voids cancellation pieces, and keeps payer service fees outside the held principal. Release and cancellation fee sides share the finest common partition, so each stored piece has one release recipient and one cancel recipient. States track funding, release, cancellation, and abandonment steps. Abandonment refunds every still-held piece. A deadline release and a caller decision release carry the named date or port clause. Retention forms reserve one held piece with a release deadline and cancellation back to the contractor. Whole-amount mode funds principal and on-top fees in one action, then releases or cancels the principal whole. Quoted cancellation uses `cancel_charge_bps` and `cancel_offer_life` to freeze penalty quotes before confirm and retain actions.
-- `cancellable_booking` holds booking funds in escrow away from guest and host until the booking ends or cancels. Cancellation quotes a penalty against the time remaining before `starts_at`, frozen for `offer_life`. Lifecycle moves through `created`, `held`, `cancellation_quoted`, `canceled`, `settled`, and `completed`. Penalty retention moves penalty funds to host and remainder to guest; completion releases full amount to host.
-- `security_deposit` reserves the full deposit amount in escrow. A claim port posts either the whole hold or an externally decided amount bounded by the hold. The explicit remainder returns to the payer. A return port voids the whole hold. The deadline form adds machine expiry and unfunded cancellation.
-- `premium_forward` holds premium pieces in escrow, then forwards net pieces after a carrier bind decision. It can abandon unbound custody. Policy reference, renewal due, endorsement evidence, and lapse actions activate when declared. Fee partition and floor remainder rules match `held_payment`.
-
-## Subscriptions, usage, and schedules
-
-- `scheduled` executes calendar-anchored payment series between one payer and one payee across three operational modes:
-  1. Finite installment plan: Stores total, first due date, and one money field per installment. The caller supplies each piece; a partition checks their sum, not equality. States and actions unroll in order with cumulative duration offsets.
-  2. Open recurring subscription: Charges a recurring amount on interval `every` until an `until` port fires, opening one period liability at a time.
-  3. Debt obligation: Emits a parent obligation plus one child payment instrument per installment. The parent stores principal, delinquency dates, party accounts, and aggregate invariants. Child instruments bind parent fields, repay against installment caps, and support full refunds. Finite obligation count generalization applies without grace periods.
-- `metered` stores one money field for each declared meter in its rate card and a period end date. Each usage charge executes an immediate transfer directly from payer to payee without escrow custody. Closing the period transitions state to `closed` at `close_by` and makes further charges unreachable.
-
-## Lending and credit
-
-- `advance` provides upfront capital disbursed to a recipient and repaid through two distinct modes:
-  1. Carved advance: References an active escrow hold and recourse instrument through `against`. It disburses once and settles from the referenced release without minting new value. In this mode, the `fee` parameter is ignored.
-  2. Scheduled advance: Stores advance amount, fee amount, repayable total, first due date, and one repayment field per installment. A supplied `fee` derives feeAmount as a floor percentage of principal. The caller supplies principal, repayable total and repayment pieces, which partitions reconcile. `repayment_source` can differ from the capital recipient. `profit_to` splits each collection between principal returned to the funder and profit paid to its recipient. `dated: true` requires one stored signed due date per repayment. Equality, chronological ordering, partial servicing and arrears are not implied by those partitions.
-- `credit_facility` stores lender, borrower, draw destination, credit limit, currency, and expiry date. The facility transitions across `active`, `frozen`, and `closed`. Each draw creates a child instrument with draw amount, facility reference, and obligation reference. Draw admission checks facility active state and aggregate child exposure against the limit. Closure requires all child draws to reach status `resolved`. Unused signature knobs (`availability_policy`, `expiry_policy`, `close_policy`) are pruned.
-- `conditional_disbursement` emits a submitted parent instrument with cap, currency, source account, destination account, and decision port. Denial terminates the parent before child approvals. Child approval instruments store externally bounded amounts. Child actions capture port input, move through `created`, `approved`, and `paid`, and verify aggregate child exposure against the parent cap. Unused signature knobs (`reopen_policy`, `recovery_policy`) are pruned.
-
-## Multi-party distributions and pooling
-
-- `pooled_split` stores pool total, due date, and one share amount and account per recipient. Positive shares total exactly 10,000 basis points. Floor division assigns each share, and the designated remainder recipient absorbs minor-unit residues. Funding and distribution actions execute in roster order.
-- `weighted_distribution` emits a parent distribution instrument and child entitlement instruments. The parent stores source account, total amount, record date, and maximum recipient count. Child rows store recipient, weight, source, currency, and parent reference. A largest-remainder distribution algorithm pays children once. Aggregate clauses cap and total child records against the pool.
-- `threshold_pool` emits a pool parent instrument and child commitment instruments. The parent stores target amount, close date, maximum contributors, beneficiary, and currency. It transitions through `open`, `active`, `failed`, or `settled` based on aggregate commitment gates. Each commitment can cancel before collection, collect into the pool, or refund after campaign failure.
-- `rotating_pool` emits a parent pool instrument plus one contribution child instrument per member. The parent unrolls active and ready states for every cycle and checks that each member row exists exactly once. Member child instruments unroll due, funded, defaulted, guaranteed, paid, and completed states for every cycle. A funded or guaranteed contribution pays the fixed beneficiary for that cycle. Final closure requires the escrow balance to drain to zero.
-
-## Bilateral exchange, clearing, and reconciliation
-
-- `swap` stores amounts, accounts, fees, currency, and optional clawback dates for both sides. Funding is atomic across both sides. Release, settlement, cancellation, dispute, abandonment, and clawback preserve the two-sided conservation group. Side fees retain their declared bearer and position. Unwind refunds each side and applies declared penalty tiers without altering principal partitions.
-- `settlement_batch` emits a batch instrument alongside capture, credit-adjustment, and debit-adjustment child records. The batch stores close time, settlement and payout accounts, beneficiary reference, and currency. Closure freezes intake. Calculation applies signed arithmetic across capture, fee, and reversal entries. Actions instruct, acknowledge, and reconcile through the declared payout port.
-- `reconciled_payout` instructs an external payout with a tolerance window, waits for a matching bank debit statement line, and tracks unmatched amounts at settlement date as break rows. Lifecycle transitions through `created`, `instructed`, and `settled`.

package/std/money_flows/advance.hsx

@@ -1,235 +0,0 @@
-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.
-// - `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
-// }
-// ```
-export instrument advance<C>(
-  funder: party,
-  to: party,
-  amount: money<C>,
-  fee: optional<percent>,
-  count: optional<integer>,
-  every: optional<text>,
-  first_due: optional<date>,
-  against: optional<ref>,
-  repayment_source: optional<party>,
-  profit_to: optional<party>,
-  dated: optional<boolean>,
-) {
-  let(amount_path): concat("fields.", amount);
-  let(currency_path): "fields.currency";
-  let(funder_field): camel(concat(funder, "_account_id"));
-  let(to_field): camel(concat(to, "_account_id"));
-
-  agent_description: "Reach for advance when the {funder} pays the {to} up front and is repaid afterwards, either out of a carved hold release or over scheduled repayments. Pick deposit for a refundable reservation and instant transfer when nobody repays the payer.";
-  title: sentence(instrument);
-  id_prefix: prefix(instrument);
-  parties {
-    payer: funder;
-    beneficiary: to;
-    when(repayment_source) { repayment: repayment_source; }
-    when(profit_to) { profit: profit_to; }
-  }
-
-  when(against) {
-    let(hold_name): owner(against);
-    summary: "Advance to the {to} repaid by carving the {hold_name} release";
-    description: "Advance: the {funder} disburses {amount} to the {to} and is repaid out of the {hold_name} release, which pays the {funder} in the {to}'s place";
-    fields {
-      amount {
-        type: money<C>;
-        description: "The advanced amount in {C} minor units, disbursed to the {to} up front";
-      }
-      carve_hold_id {
-        type: ref<hold_name>;
-        description: "The {hold_name} bound to this advance";
-        pattern: concat("^", prefix(hold_name), "_(sandbox|live)_[a-z0-9]{8,64}$");
-      }
-      carve_recourse_1_id {
-        type: ref<recourse>;
-        description: "The recourse bound to this advance";
-        pattern: "^reco_(sandbox|live)_[a-z0-9]{8,64}$";
-      }
-    }
-    required: [to_field, funder_field, amount, carveHoldId, carveRecourse1Id, currency];
-    lifecycle {
-      states created advanced repaid;
-      initial created;
-      on disburse: created -> advanced;
-      on settle: advanced -> repaid;
-    }
-    action create {
-      agent_description: "Open the advance row before any money moves. The caller supplies the {amount}, both party accounts, and the ids of the {hold_name} and the recourse that back repayment. Nothing is disbursed here.";
-      summary: concat("Create a ", words(instrument));
-      steps: [];
-      moves: [];
-    }
-    action disburse {
-      agent_description: "Pay the {amount} from the {funder} to the {to}. The advance must be created, the bound {hold_name} funded, and the recourse active, both matching this amount and currency. The transfer posts straight out and does not unwind.";
-      summary: "Disburse the {amount} to the {to}";
-      requires refs: [{
-        field: carveHoldId;
-        match: {
-          [currency_path]: currency_path;
-          [amount_path]: amount_path;
-        };
-        statuses: [funded];
-      }, {
-        field: carveRecourse1Id;
-        match: {
-          [currency_path]: currency_path;
-          [amount_path]: amount_path;
-        };
-        statuses: [active];
-      }];
-      moves: [{ amount: amount; from: payer; to: beneficiary; key: transfer; operation: create; }];
-      steps: [];
-    }
-    action settle {
-      agent_description: "Close the advance once the {hold_name} has released to the {funder} in the {to}'s place. The advance must already be disbursed. No money moves here, the release did the repaying.";
-      summary: concat("Close the advance once the ", hold_name, " has released to the ", funder);
-      steps: [];
-      moves: [];
-    }
-  }
-
-  when_not(against) {
-    let(repayment_role): if_eq(repayment_source, false, "beneficiary", "repayment");
-    when(fee) { computes derived: { field: feeAmount; source_field: amount; rule: { kind: percentage_of; bps: basis_points(fee); }; rounding: floor; }; }
-    let(repayment_fields): names("repayment", count, "Amount");
-    let(first_target): if_eq(count, 1, "repaid", "repaying_1");
-    let(states_key): "states";
-    let(first_due_field): camel(first_due);
-    summary: concat("Advance to ", to, " repaid over ", count, " anchors");
-    description: concat("Advance: the ", funder, " disburses ", amount, " to the ", to, ", repaid over ", count, " scheduled repayments plus the funder's discount");
-    fields {
-      amount {
-        type: money<C>;
-        description: "The advanced amount in {C} minor units, disbursed to the {to} up front";
-      }
-      fee_amount {
-        type: money<C>;
-        when(fee) { optional: true; allow_zero: true; }
-        description: concat(fee, " of ", amount, ", the funder's discount repaid on top of the advance");
-      }
-      repayable_amount {
-        type: money<C>;
-        description: concat(amount, " + feeAmount: the total the repayment fields below partition exactly");
-      }
-      [first_due_field] {
-        type: date;
-        description: concat("Due date of the first repayment; repayment k falls ", every, " after its predecessor");
-      }
-      for i in count {
-        repayment[i]Amount { type: money<C>; description: "Stored total for repayment {i}"; }
-        when(profit_to) {
-          repayment[i]Principal { type: money<C>; description: "Principal returned to the funder by repayment {i}"; }
-          repayment[i]Profit { type: money<C>; description: "Profit paid to the named recipient by repayment {i}"; }
-        }
-        when(dated) { repayment[i]DueAt { type: date; description: "Signed calendar due date for repayment {i}"; } }
-      }
-    }
-    lifecycle {
-      states created advanced;
-      [states_key]: [first_target];
-      initial created;
-      on disburse: created -> advanced;
-      on collect_repayment_1: advanced -> [first_target];
-      for repayment in sub(count, 1) {
-        let(index): add(repayment, 1);
-        let(previous): concat("repaying_", repayment);
-        let(target): if_eq(index, count, "repaid", concat("repaying_", index));
-        [states_key]: [target];
-        on collect_repayment_[index]: [previous] -> [target];
-      }
-    }
-    partitions: [{
-      piece_fields: repayment_fields;
-      total_field: repayableAmount;
-    }, {
-      piece_fields: [amount, feeAmount];
-      total_field: repayableAmount;
-    }];
-    when(profit_to) {
-      partitions: { total_field: amount; piece_fields: names("repayment", count, "Principal"); };
-      partitions: { total_field: feeAmount; piece_fields: names("repayment", count, "Profit"); };
-      for i in count {
-        partitions: { total_field: concat("repayment", i, "Amount"); piece_fields: [concat("repayment", i, "Principal"), concat("repayment", i, "Profit")]; };
-      }
-    }
-    action create {
-      agent_description: "Open the advance row before any money moves. The caller supplies the {amount}, the repayable total, and repayment dates. A declared fee derives the fee amount from principal. The repayment fields must partition the repayable total exactly. Nothing is disbursed here.";
-      summary: concat("Create a ", words(instrument));
-      steps: [];
-      moves: [];
-    }
-    action disburse {
-      agent_description: "Pay the {amount} from the {funder} to the {to} and start the repayment schedule. The advance must be created. The transfer posts straight out and does not unwind. Each repayment is collected on its own stored date anchor.";
-      summary: "Disburse the {amount} to the {to}";
-      moves: [{ amount: amount; from: payer; to: beneficiary; key: transfer; operation: create; }];
-      steps: [];
-    }
-    for i in count {
-      let(repayment_field): concat("repayment", i, "Amount");
-      action collect_repayment_[i] {
-        agent_description: "Collect repayment {i} once on its stored due anchor, returning principal to the funder and any separately routed profit to its recipient.";
-        summary: "Collect repayment {i} of {count}";
-        when(dated) { due: { field: concat("repayment", i, "DueAt"); }; }
-        when_not(dated) { due: { field: first_due_field; offset: scale_duration(every, sub(i, 1)); }; }
-        when_not(profit_to) { moves: [{ amount: repayment_field; from: repayment_role; to: payer; key: transfer; }]; }
-        when(profit_to) {
-          moves: [
-            { amount: concat("repayment", i, "Principal"); from: repayment_role; to: payer; key: principal; },
-            { amount: concat("repayment", i, "Profit"); from: repayment_role; to: profit; key: profit; }
-          ];
-        }
-        steps: [];
-      }
-    }
-  }
-}