@hyperscale0/hsx 2.4.1 → 3.0.0

package/std/money_flows/cancellable_booking.hsx

@@ -1,402 +0,0 @@
-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"
-// }
-// ```
-// ### 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.
-//
-export instrument cancellable_booking<C>(
-  guest: optional<party>,
-  host: optional<party>,
-  amount: optional<money<C>>,
-  starts_at: optional<date>,
-  late_penalty_bps: optional<integer>,
-  late_within: optional<text>,
-  early_penalty_bps: optional<integer>,
-  offer_life: optional<text>,
-  cancel_bands: optional<list<block>>,
-  price_value: optional<text>, supplier_cost: optional<text>, departure: optional<text>,
-  balance_before: optional<text>, confirmation_window: optional<text>, unpaid_band: optional<integer>,
-  acceptance: optional<block>, deposit_bps: optional<integer>, tax_bps: optional<integer>,
-  authority_type: optional<text>, supplier_role: optional<text>,
-  collects: optional<json>,
-) {
-  when_not(cancel_bands) {
-  let(guest_account_field): camel(concat(guest, "_account_id"));
-  let(host_account_field): camel(concat(host, "_account_id"));
-  let(reference_filter_key): "x-hyperscale-reference-filter";
-  let(owner_id_key): "owner.id";
-  let(owner_type_key): "owner.type";
-  fields {
-    amount { type: money<C>; description: concat("Booking price in minor units, held away from both the ", words(guest), " and the ", words(host), " until the booking ends"); }
-    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-    starts_at { type: date; description: "When the booking starts; the cancellation penalty is priced against the time left before it"; }
-    [guest_account_field] { type: account<C>; description: concat("The ", words(guest), " account the booking is taken from and the refund returns to"); [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-    [host_account_field] { type: account<C>; description: concat("The ", words(host), " account the booking and any penalty end up in"); [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-  }
-  lifecycle {
-    states created held cancellation_quoted canceled settled completed;
-    initial created;
-    on take: created -> held;
-    on complete: held | cancellation_quoted -> completed;
-    on cancel: held -> cancellation_quoted;
-    on confirm: cancellation_quoted -> canceled;
-    on retain: canceled -> settled;
-  }
-  parties { beneficiary: host_account_field; payer: guest_account_field; }
-  required: [amount, currency, guest_account_field, host_account_field, starts_at];
-  title: sentence(instrument);
-  agent_description: concat("Reach for cancellable booking when the ", words(guest), " pays up front and can back out at a price they see before they agree to it. The money sits in a holding account, the penalty is priced against the time left before the start, and the quote is frozen until it expires. Pick held payment when there is no cancellation price to quote.");
-  id_prefix: prefix(instrument);
-  summary: concat("Booking the ", words(guest), " can cancel at a price they see before they agree to it");
-  description: "A booking whose cancellation is quoted rather than argued: the penalty is priced against the time left before the start, frozen with the terms it was read from, and paid only if the guest confirms while the offer is still alive";
-  action create {
-    agent_description: concat("Open the booking and provision the holding account the price sits in. No money moves. The price, the currency, the start moment, and both party accounts are fixed here. Call take next to collect from the ", words(guest), ".");
-    summary: concat("Open a ", words(instrument), " and its holding account");
-    moves: [];
-    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; }; productId: { from: instance; path: productId; }; role: { from: const; value: product_escrow; }; }; capture: { bookingHoldingAccountId: accountId; }; }];
-  }
-  action take {
-    agent_description: concat("Move the whole booking price out of the ", words(guest), " account into the holding account. This moves money. Only a created booking takes. Neither party can spend the money until the booking completes or a cancellation is confirmed.");
-    summary: concat("Take the booking price from the ", words(guest), " into the holding account");
-    moves: [{ key: booking; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", guest_account_field); }; }; capture: { bookingTransferId: transferId; }; }];
-    sandbox_failure_point: funding;
-    steps: [];
-  }
-  action complete {
-    summary: concat("Release the whole booking to the ", words(host), " once the stay has started, even with a cancellation quote parked un-acted");
-    due { field: starts_at; }
-    moves: [{ key: release; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", host_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { releaseTransferId: transferId; }; }];
-    steps: [];
-  }
-  action cancel {
-    agent_description: "Price the cancellation and freeze that price. No money moves. The penalty is computed from the time left before the start, and the quote expires on its own, after which a new cancel prices it again. Call confirm to spend the quote.";
-    summary: "Price the cancellation and hold that price open";
-    quote {
-      anchorField: starts_at;
-      baseField: amount;
-      chargeRef: cancellationPenaltyAmount;
-      charges: [{ bps: late_penalty_bps; withinOffset: late_within; }, { bps: early_penalty_bps; }];
-      expires { offset: offer_life; }
-      fixes: [amount, guest_account_field];
-      netDestinationField: guest_account_field;
-      netRef: cancellationRefundAmount;
-    }
-    moves: []; steps: [];
-  }
-  action confirm {
-    agent_description: concat("Spend the frozen quote and return the net refund to the ", words(guest), ". This moves money and does not reverse. It requires an un-expired quote from cancel, and the penalty the refund left behind is paid to the ", words(host), " by retain.");
-    summary: concat("Spend the quoted cancellation and return the net to the ", words(guest));
-    commit: cancel;
-    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.", guest_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { cancellationTransferId: transferId; }; }];
-    steps: [];
-  }
-  action retain {
-    agent_description: concat("Pay the quoted cancellation penalty out of the holding account to the ", words(host), ". This moves money and does not reverse. The booking must already be canceled, so the penalty figure is the one the quote fixed.");
-    summary: concat("Pay the quoted penalty that the refund left behind to the ", words(host));
-    moves: [{ key: penalty; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationPenaltyAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", host_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { penaltyTransferId: transferId; }; }];
-    steps: [];
-  }
-  }
-  when(cancel_bands) {
-    let(band_count): len(cancel_bands);
-    for band in cancel_bands {
-      let(refund): get(band, "refund");
-      let(not_full): if_eq(refund, "full", false, true);
-      let(not_balance): if_eq(refund, "balance", false, true);
-      let(not_none): if_eq(refund, "none", false, true);
-      when(not_full) { when(not_balance) { when(not_none) {
-        unsupported { code: HSX1407; message: "Unknown cancellation refund policy"; fix: "Choose full, balance or none"; }
-      } } }
-    }
-    let(deposit_states): names("deposit_", len(cancel_bands), "");
-    let(full_states): names("full_", len(cancel_bands), "");
-    fields {
-      bookingKey { type: text; min_length: 1; }
-      signedTermsReference { type: text; min_length: 1; }
-      currency { type: text; const: C; }
-      customerAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      supplierAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      operatorAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      taxAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      authorityId { type: ref<authority_type>; optional: true; }
-      supplierRole { type: text; const: supplier_role; }
-      travellerCount { type: integer; minimum: 1; maximum: 20; }
-      departureAt { type: date; const: departure; }
-      balanceDueAt { type: date; const: shift_date(departure, balance_before, "before"); }
-      confirmationDeadline { type: date; const: shift_date(departure, confirmation_window); }
-      price { type: money<C>; const: price_value; }
-      supplierCost { type: money<C>; const: supplier_cost; }
-      depositAmount { type: money<C>; optional: true; allow_zero: true; }
-      balanceAmount: money<C>;
-      margin: money<C>;
-      operatorNet: money<C>;
-      marginVat { type: money<C>; optional: true; allow_zero: true; }
-      for i in len(cancel_bands) {
-        let(band): at(cancel_bands, i);
-      let(refund_mode): get(band, "refund");
-      let(full_refund): if_eq(refund_mode, "full", true, false);
-      let(balance_refund): if_eq(refund_mode, "balance", true, false);
-      let(retains): if_eq(refund_mode, "full", false, true);
-        let(later): if_eq(i, 1, false, true);
-        when(later) { band[i]Start { type: date; const: get(band, "starts_at"); } }
-
-        when(retains) {
-          band[i]Supplier { type: money<C>; optional: true; allow_zero: true; }
-          let(portions): if_eq(refund_mode, "balance", ["deposit"], ["deposit", "full"]);
-          for paid in portions {
-          let(is_full): if_eq(paid, "full", true, false);
-            let(portion): if_eq(refund_mode, "balance", "deposit", paid);
-            let(margin_field): concat("band", i, title(portion), "Margin");
-            let(net_field): concat("band", i, title(portion), "Net");
-            let(vat_field): concat("band", i, title(portion), "Vat");
-            [margin_field]: money<C>;
-            [net_field]: money<C>;
-            [vat_field] { type: money<C>; optional: true; allow_zero: true; }
-          }
-        }
-      }
-    }
-    parties { payer: customerAccountId; beneficiary: supplierAccountId; fee: operatorAccountId; tax: taxAccountId; }
-    distinct_parties: true;
-    computes derived: { field: depositAmount; source_field: price; rule: { kind: percentage_of; bps: deposit_bps; }; rounding: floor; };
-    computes derived: { field: marginVat; source_field: margin; rule: { kind: percentage_of; bps: tax_bps; }; rounding: floor; };
-    for i in len(cancel_bands) {
-      let(band): at(cancel_bands, i);
-      let(refund_mode): get(band, "refund");
-      let(balance_refund): if_eq(refund_mode, "balance", true, false);
-      when(balance_refund) {
-        partitions: { total_field: price; piece_fields: [balanceAmount, concat("band", i, "Supplier"), concat("band", i, "DepositNet"), concat("band", i, "DepositVat")]; };
-      }
-    }
-    partitions: { total_field: price; piece_fields: [supplierCost, operatorNet, marginVat]; };
-    partitions: { total_field: price; piece_fields: [depositAmount, balanceAmount]; };
-    partitions: { total_field: price; piece_fields: [supplierCost, margin]; };
-    partitions: { total_field: margin; piece_fields: [operatorNet, marginVat]; };
-    date order: { before_field: balanceDueAt; after_field: departureAt; operator: "<"; };
-    date order: { before_field: departureAt; after_field: confirmationDeadline; operator: "<"; };
-    for i in len(cancel_bands) {
-      let(band): at(cancel_bands, i);
-      let(refund_mode): get(band, "refund");
-      let(full_refund): if_eq(refund_mode, "full", true, false);
-      let(balance_refund): if_eq(refund_mode, "balance", true, false);
-      let(retains): if_eq(refund_mode, "full", false, true);
-      let(later): if_eq(i, 1, false, true);
-      let(band_start): concat("band", i, "Start");
-      when(later) {
-        date order: { before_field: band_start; after_field: departureAt; operator: "<"; };
-        let(after_second): if_eq(i, 2, false, true);
-        when(after_second) { date order: { before_field: concat("band", sub(i, 1), "Start"); after_field: band_start; operator: "<"; }; }
-      }
-
-      when(retains) {
-        let(supplier_field): concat("band", i, "Supplier");
-        computes derived: { field: supplier_field; source_field: supplierCost; rule: { kind: percentage_of; bps: get(band, "supplier_bps"); }; rounding: floor; };
-        let(portions): if_eq(refund_mode, "balance", ["deposit"], ["deposit", "full"]);
-        for paid in portions {
-          let(is_full): if_eq(paid, "full", true, false);
-          let(portion): if_eq(refund_mode, "balance", "deposit", paid);
-            let(margin_field): concat("band", i, title(portion), "Margin");
-          let(net_field): concat("band", i, title(portion), "Net");
-          let(vat_field): concat("band", i, title(portion), "Vat");
-          let(retained): if_eq(paid, "deposit", "depositAmount", if_eq(refund_mode, "balance", "depositAmount", "price"));
-          computes derived: { field: vat_field; source_field: margin_field; rule: { kind: percentage_of; bps: tax_bps; }; rounding: floor; };
-          partitions: { total_field: retained; piece_fields: [supplier_field, net_field, vat_field]; };
-          partitions: { total_field: retained; piece_fields: [supplier_field, margin_field]; };
-          partitions: { total_field: margin_field; piece_fields: [net_field, vat_field]; };
-        }
-      }
-    }
-    agent_description: "Hold deposit and balance in one booking account. Apply a finite dated cancellation policy and release the supplier, operator and tax partition only after the named authority confirms. Refund the entire price when confirmation times out.";
-    lifecycle {
-      states created awaiting_confirmation confirmed released refunded canceled expired;
-      let(states_key): "states";
-      [states_key]: concat_lists(deposit_states, full_states);
-      initial created;
-      on deposit: created -> deposit_1;
-      on expire: created -> expired;
-      for i in len(cancel_bands) {
-        let(band): at(cancel_bands, i);
-      let(refund_mode): get(band, "refund");
-      let(full_refund): if_eq(refund_mode, "full", true, false);
-      let(balance_refund): if_eq(refund_mode, "balance", true, false);
-      let(retains): if_eq(refund_mode, "full", false, true);
-        let(band_name): get(band, "name");
-        let(deposit_state): concat("deposit_", i);
-        let(full_state): concat("full_", i);
-        let(balance_action): concat("balance_", band_name);
-        let(cancel_deposit): concat("cancel_deposit_", band_name);
-        let(cancel_full): concat("cancel_full_", band_name);
-        on [balance_action]: deposit_state -> full_state;
-        on [cancel_deposit]: deposit_state -> canceled;
-        on [cancel_full]: full_state -> canceled;
-        let(later): if_eq(i, 1, false, true);
-        when(later) {
-          let(previous_deposit): names("deposit_", sub(i, 1), "");
-          let(previous_full): names("full_", sub(i, 1), "");
-          let(open_deposit): concat("open_deposit_", band_name);
-          let(open_full): concat("open_full_", band_name);
-          on [open_deposit]: previous_deposit -> deposit_state;
-          on [open_full]: previous_full -> full_state;
-        }
-      }
-      on cancel_unpaid: deposit_states -> canceled;
-      on await_confirmation: full_states -> awaiting_confirmation;
-      on confirm: awaiting_confirmation -> confirmed;
-      on release: confirmed -> released;
-      on refund_unconfirmed: full_states | awaiting_confirmation -> refunded;
-    }
-    caller_parked_states: { confirmed: "Release pays the confirmed supplier and frozen partition."; };
-    action create {
-      public: none;
-      agent_description: "Freeze the booking terms and provision its holding account.";
-      unique: { namespace: instrument; by_fields: [bookingKey]; };
-      deadline: { field: balanceDueAt; };
-      steps: { operation: "account.escrow.provision"; bind: { currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; "owner.id": { from: instance; path: productId; }; "owner.type": { from: const; value: product; }; role: { from: const; value: product_escrow; }; }; capture: { heldAccountId: accountId; }; };
-    }
-    action deposit {
-      public: none;
-      agent_description: "Collect the derived deposit after the acceptance requirements pass.";
-      when(collects) { cascade: collects; }
-      when(acceptance) { requires aggregate: acceptance; }
-      deadline: { field: balanceDueAt; }; port: { allowedParties: [payer]; };
-      moves: { key: deposit; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "depositAmount"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "fields.customerAccountId"; }; destinationAccountId: { from: instance; path: "refs.heldAccountId"; }; }; };
-      steps: [];
-    }
-    action expire { public: none; agent_description: "Close an unfunded booking."; due: { field: balanceDueAt; }; requires_drained: { path: refs.heldAccountId; }; steps: []; }
-    for i in len(cancel_bands) {
-      let(band): at(cancel_bands, i);
-      let(refund_mode): get(band, "refund");
-      let(full_refund): if_eq(refund_mode, "full", true, false);
-      let(balance_refund): if_eq(refund_mode, "balance", true, false);
-      let(retains): if_eq(refund_mode, "full", false, true);
-      let(band_name): get(band, "name");
-      let(balance_action): concat("balance_", band_name);
-      let(next_index): add(i, 1);
-      let(next_field): concat("band", next_index, "Start");
-      let(band_end): if_eq(i, band_count, "departureAt", next_field);
-      let(later): if_eq(i, 1, false, true);
-      action [balance_action] {
-        public: none; agent_description: "Collect the remaining balance once before its deadline.";
-        deadline: { field: balanceDueAt; }; port: { allowedParties: [payer]; };
-        moves: { key: balance; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "balanceAmount"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "fields.customerAccountId"; }; destinationAccountId: { from: instance; path: "refs.heldAccountId"; }; }; };
-        steps: [];
-      }
-      for paid in ["deposit", "full"] {
-          let(is_full): if_eq(paid, "full", true, false);
-        when(later) {
-          let(open_action): concat("open_", paid, "_", band_name);
-          action [open_action] { public: none; agent_description: "Open the next dated cancellation band."; due: { field: concat("band", i, "Start"); }; steps: []; }
-        }
-        let(portion): if_eq(refund_mode, "balance", "deposit", paid);
-        let(cancel_action): concat("cancel_", paid, "_", band_name);
-        action [cancel_action] {
-          public: none; agent_description: "Settle this paid amount under the active cancellation band.";
-          deadline: { field: band_end; }; port: { allowedParties: [payer]; };
-          when(full_refund) { moves: { key: refund; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", if_eq(paid, "deposit", "depositAmount", "price")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.customerAccountId"; }; }; }; }
-          when(retains) {
-            when(is_full) { when(balance_refund) { moves: { key: refund; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "balanceAmount"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.customerAccountId"; }; }; }; } }
-            moves: { key: supplier; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", i, "Supplier")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.supplierAccountId"; }; }; };
-            moves: { key: operator; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", i, title(portion), "Net")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.operatorAccountId"; }; }; };
-            moves: { key: vat; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", i, title(portion), "Vat")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.taxAccountId"; }; }; };
-          }
-          steps: [];
-        }
-      }
-    }
-    action cancel_unpaid {
-      public: none; agent_description: "Settle the deposit under the declared unpaid-balance band and end the remaining obligation.";
-      due: { field: balanceDueAt; };
-      when_not(unpaid_band) { moves: { key: refund; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: "fields.depositAmount"; }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.customerAccountId"; }; }; }; }
-      when(unpaid_band) {
-        let(unpaid_policy): at(cancel_bands, unpaid_band);
-        let(unpaid_full_refund): if_eq(get(unpaid_policy, "refund"), "full", true, false);
-        when(unpaid_full_refund) { moves: { key: refund; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: "fields.depositAmount"; }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.customerAccountId"; }; }; }; }
-        when_not(unpaid_full_refund) {
-      moves: { key: supplier; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", unpaid_band, "Supplier")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.supplierAccountId"; }; }; };
-      moves: { key: operator; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", unpaid_band, "DepositNet")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.operatorAccountId"; }; }; };
-      moves: { key: vat; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", concat("band", unpaid_band, "DepositVat")); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.taxAccountId"; }; }; };
-        }
-      }
-      steps: [];
-    }
-    action await_confirmation { public: none; agent_description: "Open confirmation at the booked departure."; due: { field: departureAt; }; steps: []; }
-    action confirm {
-      public: none; agent_description: "Consume the named supplier's approved decision for this booking before timeout.";
-      deadline: { field: confirmationDeadline; };
-      input: { type: object; additionalProperties: false; properties: { authorityId: { type: string; pattern: concat("^", prefix(authority_type), "_(sandbox|live)_[a-z0-9]{8,64}$"); }; }; required: [authorityId]; };
-      updates: [authorityId];
-      requires refs: { field: authorityId; statuses: [approved]; match: { instrumentInstanceId: fields.requestInstanceId; "fields.supplierAccountId": fields.decidingActorAccountId; "fields.supplierRole": fields.decidingRole; }; attests: { instrument: fields.requestInstrumentId; party: decider; action: fields.requestAction; digest: fields.inputDigest; role: fields.decidingRole; expires_at: fields.expiresAt; consume: consume; }; };
-      steps: [];
-    }
-    action release {
-      public: none; agent_description: "Pay supplier cost, operator net and VAT after confirmation.";
-      moves: { key: supplier; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "supplierCost"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.supplierAccountId"; }; }; };
-      moves: { key: operator; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "operatorNet"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.operatorAccountId"; }; }; };
-      moves: { key: vat; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "marginVat"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.taxAccountId"; }; }; };
-      steps: [];
-    }
-    action refund_unconfirmed {
-      public: none; agent_description: "Return the entire booking price when supplier confirmation times out.";
-      due: { field: confirmationDeadline; };
-      moves: { key: refund; operation: "internal_transfer.create"; bind: { amount: { from: instance; path: concat("fields.", "price"); }; currency: { from: instance; path: fields.currency; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.heldAccountId"; }; destinationAccountId: { from: instance; path: "fields.customerAccountId"; }; }; };
-      steps: [];
-    }
-  }
-}

package/std/money_flows/captured_payment.hsx

@@ -1,220 +0,0 @@
-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.
-// - `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 }
-// }
-// ```
-export instrument captured_payment<C>(payer: party, payee: party, amount: money<C>, reserve_until: date, correction: condition, external_reversal: condition, derived_amount: optional<block>) {
-  let(correction_name): correction;
-  let(reversal_name): external_reversal;
-  let(reversal_window): external_reversal_within;
-  let(instrument_words): words(instrument);
-  when(derived_amount) {
-    let(derived_field): get(derived_amount, "field");
-    let(derived_source): get(derived_amount, "source");
-    let(derived_rule): get(derived_amount, "rule");
-    let(derived_bearer): get(derived_amount, "bearer");
-  }
-  agent_description: "Reach for captured payment when the {payee} reserves against the {payer} first and then takes the money in slices before {reserve_until}. Pick instant transfer when the whole amount moves at once, and deposit when the reservation is claimed or returned whole.";
-  summary: "Capture reservation from {payer} to {payee}";
-  title: sentence(instrument);
-  description: "Payer reservation captured by the payee in slices within a fixed window";
-  fields {
-    when(derived_amount) {
-      let(fee_collection_key): "x-hyperscale-fee-collection-port";
-      let(reference_filter_key): "x-hyperscale-reference-filter";
-      platformAccountId {
-        type: account<C>;
-        description: "The product fee collection account";
-        [fee_collection_key]: true;
-        [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
-      }
-    }
-    amount { type: money<C>; description: "Maximum captured amount in {C} minor units"; }
-    reserve_until { type: date; description: "Reservation expiry that releases any uncaptured remainder"; }
-    reversalUntil { type: date; description: "Machine-owned external reversal cutoff anchored when settlement completes"; optional: true; }
-    when(derived_amount) {
-      [derived_field] { type: money<C>; description: "Machine-computed {derived_rule} of {derived_source}; callers never supply it"; pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
-    }
-  }
-  lifecycle {
-    states created authorized partially_captured settled voided expired corrected reversed;
-    initial created;
-    on authorize: created -> authorized;
-    on capture: authorized -> partially_captured;
-    on capture_more: partially_captured -> partially_captured;
-    on settle: authorized | partially_captured -> settled;
-    on void: authorized -> voided;
-    on expire: authorized -> expired;
-    on settle_on_expiry: partially_captured -> settled;
-    on [correction_name]: settled -> corrected;
-    on [reversal_name]: settled -> reversed;
-  }
-  parties {
-    payer: payer;
-    beneficiary: payee;
-  }
-  when(derived_amount) {
-    computes derived: { field: derived_field; source_field: derived_source; rounding: floor; rule: { kind: percentage_of; bps: derived_rule; }; };
-  }
-  action create {
-    let(metadata_instrument): "metadata.instrumentId";
-    let(metadata_instance): "metadata.instrumentInstanceId";
-    let(metadata_phase): "metadata.phase";
-    agent_description: "Open the payment row before anything is reserved. The caller supplies the {amount}, the currency, and both party accounts. This reserves nothing, call authorize next.";
-    summary: "Create a {instrument_words}";
-    when(derived_amount) {
-      moves: [{ key: "derived_amount"; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", derived_field); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: create; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", camel(derived_bearer), "AccountId"); }; }; capture: { createDerivedAmountTransferId: transferId; }; }];
-    }
-    steps: [];
-  }
-  action authorize {
-    agent_description: "Reserve the {amount} against the {payer} in the {payee}'s favor until {reserve_until}. The payment must be created. The money is held, not paid: capture and settle post it, void and expiry release it.";
-    summary: "Reserve the {amount} until {reserve_until}";
-    moves: [{ key: reservation; amount: amount; from: payer; to: beneficiary; operation: reserve; }];
-    sandbox_failure_point: funding;
-    steps: [];
-  }
-  action capture {
-    agent_description: "Post the first capture slice out of the live reservation. The payment must be authorized and the caller passes captureAmount in minor units. The slice settles for good and void can no longer release the reservation. Call before {reserve_until}.";
-    summary: "Post one strict partial capture slice";
-    deadline { field: reserve_until; };
-    input { type: object; additional_properties: false; properties: { captureAmount: { description: "Positive partial capture amount in minor units"; pattern: "^[1-9][0-9]{0,17}$"; type: string; }; }; required: [captureAmount]; }
-    moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: captureAmount; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
-    sandbox_failure_point: "release";
-    steps: [];
-  }
-  action capture_more {
-    agent_description: "Post another capture slice out of a partly captured reservation. Call this only after capture took the first slice. Each slice settles for good, and the uncaptured remainder still releases at {reserve_until}.";
-    summary: "Post another strict partial capture slice";
-    deadline { field: reserve_until; };
-    input { type: object; additional_properties: false; properties: { captureAmount: { description: "Positive partial capture amount in minor units"; pattern: "^[1-9][0-9]{0,17}$"; type: string; }; }; required: [captureAmount]; }
-    moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: captureAmount; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
-    steps: [];
-  }
-  action settle {
-    agent_description: "Post the whole reserved remainder and finish the payment. The payment must be authorized or partly captured. The money settles and the external reversal window opens on reversalUntil.";
-    summary: "Post the full reserved remainder and settle";
-    deadline { field: reserve_until; };
-    sets(at) { field: reversalUntil; offset: reversal_window; };
-    moves: [{ key: post; operation: internal_transfer.post; bind: { transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
-    steps: [];
-  }
-  action void {
-    agent_description: "Release the reservation whole and cancel the payment. Only an authorized reservation with nothing captured can void. Once any slice is captured, settle it or let it expire instead.";
-    summary: "Release an entirely uncaptured reservation";
-    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Reservation voided before any capture"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
-    steps: [];
-  }
-  action expire {
-    summary: "Release an uncaptured reservation at expiry";
-    due { field: reserve_until; };
-    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Uncaptured reservation expired"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
-    steps: [];
-  }
-  action settle_on_expiry {
-    summary: "Release the uncaptured remainder and settle captured slices";
-    due { field: reserve_until; };
-    sets(at) { field: reversalUntil; offset: reversal_window; };
-    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Uncaptured remainder released at expiry"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
-    steps: [];
-  }
-  action [correction_name] {
-    let(metadata_clawback): "metadata.clawbackOfTransferId";
-    let(metadata_instrument): "metadata.instrumentId";
-    let(metadata_instance): "metadata.instrumentInstanceId";
-    let(metadata_phase): "metadata.phase";
-    let(correction_capture): camel(concat(correction_name, "_transfer_transfer_id"));
-    agent_description: "Return the whole captured amount to the {payer} after the payment settled. Only a settled payment corrects, and only the party the product authorized may call it. The money moves back and there is no undo.";
-    summary: "Return the full captured amount on payee correction";
-    when(correction_fields) {
-      input {
-        type: object;
-        additional_properties: false;
-        properties {
-          for input_name in keys(correction_fields) {
-            [input_name]: get(correction_fields, input_name);
-          }
-        }
-        required: keys(correction_fields);
-      }
-      capture_input: {
-        for item in keys(correction_fields) { [item]: item; }
-      };
-    }
-    port { allowed_parties: correction_allowed; };
-    moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.capturedAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payer, "AccountId"); }; [metadata_clawback]: { from: instance; path: refs.authorizeReservationTransferId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: correction_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payee, "AccountId"); }; }; capture: { [correction_capture]: transferId; }; }];
-    steps: [];
-  }
-  action [reversal_name] {
-    let(metadata_clawback): "metadata.clawbackOfTransferId";
-    let(metadata_instrument): "metadata.instrumentId";
-    let(metadata_instance): "metadata.instrumentInstanceId";
-    let(metadata_phase): "metadata.phase";
-    let(reversal_capture): camel(concat(reversal_name, "_transfer_transfer_id"));
-    agent_description: "Return the whole captured amount to the {payer} on an external reversal. The payment must be settled and the call must land before reversalUntil. The caller passes externalReference, which stays in the receipt. There is no undo.";
-    summary: "Return the full captured amount on an external reversal";
-    deadline { field: reversalUntil; };
-    when(external_reversal_fields) {
-      capture_input: {
-        for item in keys(external_reversal_fields) { [item]: item; }
-      };
-      input {
-        type: object;
-        additional_properties: false;
-        properties {
-          for input_name in keys(external_reversal_fields) {
-            [input_name]: get(external_reversal_fields, input_name);
-          }
-        }
-        required: keys(external_reversal_fields);
-      }
-    }
-    port { allowed_parties: external_reversal_allowed; };
-    moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.capturedAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payer, "AccountId"); }; [metadata_clawback]: { from: instance; path: refs.authorizeReservationTransferId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: reversal_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payee, "AccountId"); }; }; capture: { [reversal_capture]: transferId; }; }];
-    steps: [];
-  }
-}