@hyperscale0/hsx 2.4.1 → 3.0.0

package/std/money_flows/premium_forward.hsx

@@ -1,307 +0,0 @@
-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,
-  amount: money<C>,
-  bind: condition,
-  commission: percent,
-  policy_ref: optional<text>,
-  renewal_due: optional<date>,
-  endorsement: optional<condition>,
-) {
-  let(instrument_words): words(instrument);
-  let(bind_name): concat(bind);
-  let(payer_field): camel(concat(payer, "_account_id"));
-  let(carrier_field): camel(concat(carrier, "_account_id"));
-  let(amount_field): concat(amount);
-  let(net_bps): sub(10000, commission);
-  let(fee_bps): add(commission, 0);
-  let(net_percent): percent_text(net_bps);
-  let(fee_percent): percent_text(fee_bps);
-  let(owner_id_key): "owner.id";
-  let(owner_type_key): "owner.type";
-  let(metadata_instrument_key): "metadata.instrumentId";
-  let(metadata_instance_key): "metadata.instrumentInstanceId";
-  let(metadata_phase_key): "metadata.phase";
-  let(bind_capture_key): camel(concat(bind, "_transfer_transfer_id"));
-  let(fee_port_key): "x-hyperscale-fee-collection-port";
-  let(reference_filter_key): "x-hyperscale-reference-filter";
-
-  title: sentence(instrument);
-  agent_description: "Reach for {instrument_words} when the {payer} pays an insurance premium ahead of cover and the {carrier} must not be paid until the policy binds. The {amount_field} sits in this settlement's own escrow until {bind_name} fires. Binding then forwards {net_percent} to the {carrier} and {fee_percent} to the platform.";
-  summary: "Premium held for the {carrier} until the policy binds";
-  description: "Premium forward: the {payer} funds the {amount_field} into this settlement's own escrow; binding through {bind_name} forwards it to the {carrier} exactly once, minus the platform commission";
-  partitions: { total_field: amount_field; piece_fields: [piece1Amount, piece2Amount]; };
-
-  fields {
-    platform_account_id: {
-      type: account;
-      description: "The product fee collection account";
-      [fee_port_key]: true;
-      [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
-    }
-    amount: {
-      type: money<C>;
-      description: "The gross held amount in {C} minor units; the piece fields below partition it exactly";
-    }
-    piece1_amount: {
-      type: money<C>;
-      description: "{net_percent} of {amount_field} (carries the integer-division remainder): released to the {carrier}. Computed as floor({amount_field} * {net_bps} / 10000) in {C} minor units";
-    }
-    piece2_amount: {
-      type: money<C>;
-      description: "{fee_percent} of {amount_field}: released to the platform. Computed as floor({amount_field} * {fee_bps} / 10000) in {C} minor units";
-    }
-    when(policy_ref) {
-      policy_ref: {
-        type: text;
-        description: "Immutable external policy reference recorded with this forward";
-        max_length: 180;
-        min_length: 1;
-      }
-    }
-    when(renewal_due) {
-      renewal_due: {
-        type: date;
-        description: "Stored renewal due condition for the forwarded policy";
-      }
-    }
-  }
-
-  parties { payer: payer; beneficiary: carrier; }
-
-  lifecycle {
-    states created funding_1 funded releasing_1 released abandoned;
-    when(endorsement) { states endorsed lapsed; }
-    initial created;
-    on fund_piece_1: created -> funding_1;
-    on fund_piece_2: funding_1 -> funded;
-    on [bind]: funded -> releasing_1;
-    on forward_piece_2: releasing_1 -> released;
-    on unfund_piece_1: funding_1 -> abandoned;
-    on abandon: created -> abandoned;
-    when(endorsement) {
-      on [endorsement]: released -> endorsed;
-      on lapse: released|endorsed -> lapsed;
-    }
-  }
-
-  action create {
-    agent_description: "Open the {instrument_words} and provision the escrow account that holds the funds. This is the first call on the settlement, and funding refuses until it lands. It moves no money.";
-    summary: "Create a {instrument_words} settlement";
-    steps: [{
-      operation: "account.escrow.provision";
-      bind: {
-        currency: { from: instance; path: fields.currency; };
-        [owner_id_key]: { from: instance; path: productId; };
-        [owner_type_key]: { from: const; value: product; };
-        product_id: { from: instance; path: productId; };
-        role: { from: const; value: product_escrow; };
-      };
-      capture: { escrow_account_id: accountId; };
-    }];
-  }
-
-  action fund_piece_1 {
-    agent_description: "Move the {carrier}'s share of the premium from the {payer} into escrow. The settlement must exist and be unfunded. It debits the {payer} for real, and piece 2 still has to fund before the policy can bind.";
-    summary: "Fund piece 1 of the held amount into escrow";
-    moves: [{
-      key: transfer; operation: "internal_transfer.create";
-      bind: {
-        amount: { from: instance; path: fields.piece1Amount; };
-        currency: { from: instance; path: fields.currency; };
-        destination_account_id: { from: instance; path: refs.escrowAccountId; };
-        source_account_id: { from: instance; path: concat("fields.", payer_field); };
-        [metadata_instrument_key]: { from: const; value: instrument; };
-        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
-        [metadata_phase_key]: { from: const; value: fund_piece_1; };
-        product_id: { from: instance; path: productId; };
-      };
-      capture: { fund_piece_1_transfer_transfer_id: transferId; };
-    }];
-    sandbox_failure_point: funding;
-    steps: [];
-  }
-
-  action fund_piece_2 {
-    agent_description: "Move the platform commission piece from the {payer} into escrow, which completes funding. Piece 1 must be in escrow first. It debits the {payer} for real, and the premium is then held whole.";
-    summary: "Fund piece 2 of the held amount into escrow";
-    moves: [{
-      key: transfer; operation: "internal_transfer.create";
-      bind: {
-        amount: { from: instance; path: fields.piece2Amount; };
-        currency: { from: instance; path: fields.currency; };
-        destination_account_id: { from: instance; path: refs.escrowAccountId; };
-        source_account_id: { from: instance; path: concat("fields.", payer_field); };
-        [metadata_instrument_key]: { from: const; value: instrument; };
-        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
-        [metadata_phase_key]: { from: const; value: fund_piece_2; };
-        product_id: { from: instance; path: productId; };
-      };
-      capture: { fund_piece_2_transfer_transfer_id: transferId; };
-    }];
-    sandbox_failure_point: funding;
-    steps: [];
-  }
-
-  action [bind] {
-    agent_description: "Bind the policy through {bind_name} and forward the {carrier}'s share out of escrow. The premium must be fully funded first, and the call carries the decision reference the product asks for. Money leaves escrow here and does not come back.";
-    summary: "Confirm through {bind_name} and start the forward payout";
-    input: {
-      additional_properties: false;
-      properties: {
-        for item in keys(bind_fields) {
-          [item]: get(bind_fields, item);
-        }
-      };
-      required: keys(bind_fields);
-      type: object;
-    };
-    port: { allowed_parties: bind_allowed; };
-    moves: [{
-      key: transfer; operation: "internal_transfer.create";
-      bind: {
-        amount: { from: instance; path: fields.piece1Amount; };
-        currency: { from: instance; path: fields.currency; };
-        destination_account_id: { from: instance; path: concat("fields.", carrier_field); };
-        source_account_id: { from: instance; path: refs.escrowAccountId; };
-        [metadata_instrument_key]: { from: const; value: instrument; };
-        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
-        [metadata_phase_key]: { from: const; value: bind; };
-        product_id: { from: instance; path: productId; };
-      };
-      capture: { [bind_capture_key]: transferId; };
-    }];
-    sandbox_failure_point: "release";
-    steps: [];
-  }
-
-  action forward_piece_2 {
-    agent_description: "Pay the platform commission out of escrow to the fee collection account, which closes the forward. {bind_name} must have run first. Money leaves escrow here and does not come back.";
-    summary: "Forward piece 2 of the held amount";
-    moves: [{
-      key: transfer; operation: "internal_transfer.create";
-      bind: {
-        amount: { from: instance; path: fields.piece2Amount; };
-        currency: { from: instance; path: fields.currency; };
-        destination_account_id: { from: instance; path: fields.platformAccountId; };
-        source_account_id: { from: instance; path: refs.escrowAccountId; };
-        [metadata_instrument_key]: { from: const; value: instrument; };
-        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
-        [metadata_phase_key]: { from: const; value: forward_piece_2; };
-        product_id: { from: instance; path: productId; };
-      };
-      capture: { forward_piece_2_transfer_transfer_id: transferId; };
-    }];
-    steps: [];
-  }
-
-  action unfund_piece_1 {
-    agent_description: "Return the {carrier}'s share from escrow to the {payer} and abandon the forward. It runs only while funding stopped after piece 1, before the policy binds. The settlement ends abandoned.";
-    summary: "Return piece 1 to the {payer} on abandonment";
-    moves: [{
-      key: transfer; operation: "internal_transfer.create";
-      bind: {
-        amount: { from: instance; path: fields.piece1Amount; };
-        currency: { from: instance; path: fields.currency; };
-        destination_account_id: { from: instance; path: concat("fields.", payer_field); };
-        source_account_id: { from: instance; path: refs.escrowAccountId; };
-        [metadata_instrument_key]: { from: const; value: instrument; };
-        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
-        [metadata_phase_key]: { from: const; value: unfund_piece_1; };
-        product_id: { from: instance; path: productId; };
-      };
-      capture: { unfund_piece_1_transfer_transfer_id: transferId; };
-    }];
-    steps: [];
-  }
-
-  action abandon {
-    agent_description: "Close a {instrument_words} that was never funded. The escrow account must be empty, so this refuses once any piece is in it. It moves no money and the settlement ends here.";
-    summary: "Abandon the settlement before any money is held";
-    requires drained: { path: refs.escrowAccountId; };
-    steps: [];
-  }
-
-  when(endorsement) {
-    action [endorsement] {
-      agent_description: "Record one endorsement against a policy that already forwarded, from evidence the caller supplies. The forward must be released first, and only the {carrier} may call it. It moves no money and it does not change the premium.";
-      summary: "Record one non-money endorsement from external evidence";
-      when(endorsement_fields) {
-        input: {
-          additional_properties: false;
-          properties: {
-            for item in keys(endorsement_fields) {
-              [item]: get(endorsement_fields, item);
-            }
-          };
-          required: keys(endorsement_fields);
-          type: object;
-        };
-        capture_input: {
-          for item in keys(endorsement_fields) { [item]: item; }
-        };
-      }
-      port { allowed_parties: endorsement_allowed; };
-      steps: [];
-    }
-    action lapse {
-      summary: "Mark the forwarded policy lapsed at its stored renewal due condition";
-      due: { field: renewal_due; };
-      requires drained: { path: refs.escrowAccountId; };
-      steps: [];
-    }
-  }
-}

package/std/money_flows/reconciled_payout.hsx

@@ -1,119 +0,0 @@
-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,
-  amount: money<C>,
-  beneficiary_ref: text,
-  settle_by: date,
-  matched_within: integer,
-  matched_ceiling: integer,
-) {
-  let(payer_account_field): camel(concat(payer, "_account_id"));
-  let(beneficiary_account_field): camel(concat(beneficiary, "_account_id"));
-  let(reference_filter_key): "x-hyperscale-reference-filter";
-  fields {
-    amount { type: money<C>; description: concat("Amount instructed to the ", words(beneficiary), " in minor units"); }
-    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-    settle_by { type: date; description: "Instant the expectation stops waiting and the unmatched amount becomes a break"; }
-    beneficiary_ref { type: text; description: "Beneficiary ID for the payout instruction"; pattern: "^ben_(sandbox|live)_[a-z0-9]{8,64}$"; }
-    [beneficiary_account_field] { type: account<C>; description: concat("The ", words(beneficiary), " account"); [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-    [payer_account_field] { type: account<C>; description: concat("The ", words(payer), " account the payout leaves"); [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-  }
-  lifecycle {
-    states created instructed settled;
-    initial created;
-    on instruct: created -> instructed;
-    on settle: instructed -> settled;
-  }
-  parties { beneficiary: beneficiary_account_field; payer: payer_account_field; }
-  required: [amount, beneficiary_account_field, beneficiary_ref, currency, payer_account_field, settle_by];
-  title: sentence(instrument);
-  agent_description: concat("Reach for reconciled payout when a payment to the ", words(beneficiary), " is not finished until the bank confirms the debit. The instruction goes out, the expectation waits for a matching statement line, and anything still unmatched at the settle date becomes a break row instead of disappearing. Pick instant transfer when no bank confirmation is involved.");
-  id_prefix: prefix(instrument);
-  summary: concat("Payout from ", words(payer), " to ", words(beneficiary), " that is not done until the bank agrees");
-  description: "A payout the instrument owns end to end: one instruction, one expectation about the debit it will produce, and one break when the debit never matches";
-  dials: [{ key: settlement_tolerance; kind: reconcile_tolerance; maxMinorUnits: matched_ceiling; summary: "Largest difference between the instructed amount and the settled debit that still counts as matched."; title: "Settlement tolerance"; }];
-  action create { summary: concat("Create a ", words(instrument)); agent_description: concat("Open the payout row with the ", words(payer), " and ", words(beneficiary), " accounts, the amount, the beneficiary reference, and the settle date. No money moves and no instruction goes out yet. Call instruct next."); moves: []; steps: []; }
-  action instruct {
-    agent_description: concat("Send the payout instruction and start the expectation clock. This commits the amount to the ", words(beneficiary), " and the payout is not reversible from here. The bank debit is matched later by settle, which runs on its own at the settle date.");
-    summary: concat("Instruct the payout to the ", words(beneficiary));
-    payout { amount: concat("fields.", amount); beneficiaryField: beneficiary_ref; beneficiaryPartyField: beneficiary_account_field; capture: payoutId; currencyField: currency; sourceAccountField: payer_account_field; speed: standard; }
-    moves: []; steps: [];
-  }
-  action settle {
-    summary: "Match the bank's debit against what the instruction promised";
-    due { field: settle_by; }
-    reconcile {
-      amount: concat("fields.", amount); capture: settlementEvidenceId; counterpartyRef: payoutId;
-      currencyField: currency; direction: debit; evidence: statement_line;
-      exception { amountField: unmatchedAmount; childInstrumentId: concat(instrument, "_break"); maxOpen: 1; reasonField: breakReason; refField: concat(camel(instrument), "Id"); }
-      match { law: tolerance; dial: settlement_tolerance; minorUnits: matched_within; }
-      within { field: settle_by; }
-    }
-    moves: []; steps: [];
-  }
-  instruments {
-    instrument {
-      let(parent_name): instrument;
-      id: concat(parent_name, "_break");
-      id_prefix: concat(prefix(parent_name), "bk");
-      fields {
-        unmatchedAmount { type: money<C>; description: "Difference between the instructed amount and the evidence, in minor units"; }
-        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-        breakReason { type: text; description: "Why the expectation went unmatched"; minLength: 1; maxLength: 180; }
-        [parent_name]Id { type: ref<parent_name>; description: "Payout whose expectation broke"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
-      }
-      lifecycle { states created carried; initial created; on carry: created -> carried; }
-      required: [breakReason, currency, unmatchedAmount, concat(camel(parent_name), "Id")];
-      title: concat(sentence(parent_name), " Break");
-      agent_description: concat("Reach for this child row when a ", words(parent_name), " expectation reached its window with no matching bank debit. The break carries the unmatched amount and the reason so the difference is owned by someone rather than silently dropped.");
-      summary: "Unmatched settlement expectation carried as its own row";
-      description: "One break raised when a payout expectation reached its window with no matching debit; it is carried, never silently dropped";
-      action create { summary: "Raise a break against an instructed payout"; agent_description: "Raise a break against an instructed payout, recording the unmatched amount and why the expectation went unmatched. No money moves. The payout must still be instructed, and only one open break exists per payout."; requires refs { field: concat(camel(parent_name), "Id"); statuses: [instructed]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-      action carry { summary: "Carry the break to whoever owns it"; agent_description: "Hand the break to whoever owns resolving it. No money moves. The payout must still be instructed. This is the only exit from a raised break, so a break is never closed by dropping it."; requires refs { field: concat(camel(parent_name), "Id"); statuses: [instructed]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-    }
-  }
-}