@hyperscale0/hsx 5.2.0 → 5.4.0

package/src/tunables.ts

@@ -1,3 +1,4 @@
+import { fail } from "./diagnostics.ts";
 import type { Expr } from "./ast.ts";
 
 /** Bounds use UDL units: minor units, basis points and milliseconds. */
@@ -24,7 +25,11 @@ export function tunableBounds(
       numbers.some((value) => !Number.isSafeInteger(value)) ||
       numbers[0]! > numbers[1]!
     )
-      throw new Error("integer tunable needs a minimum and maximum");
+      fail(
+        type,
+        "integer tunable needs ordered safe integer bounds",
+        "write integer(1, 12)",
+      );
     return { minimum: numbers[0]!, maximum: numbers[1]! };
   }
   return { minimum: 0, maximum: Number.MAX_SAFE_INTEGER };

package/src/version.ts

@@ -1,2 +1 @@
-export const HSX_VERSION = "5.2.0";
-export const HSX_TARGET_UDL_VERSION = 4;
+export const HSX_VERSION = "5.4.0";

package/std/cards.hsx

@@ -1,5 +1,17 @@
 header cards
 
+// Activate holder and card before creating and approving an authorization.
+// Expose authorization.create, approve and capture; expose decline and reverse
+// separately if callers need those paths. Issuer declines only from pending;
+// merchant captures or reverses an approved reservation. Expiry voids approved
+// reservations or abandons pending ones; it does not delay a captured refund.
+// Create one transaction for the captured authorization and expose its refund.
+// Refund is available immediately from posted, even before authorization.expiresAt,
+// and moves the whole captured amount from merchant to holder under programOperator.
+// No partial capture, repeated capture or partial transaction refund is provided.
+// Disputes need a posted transaction, issuer review and win before their deadline;
+// win invokes the same refund. The alias never changes the declared action actor.
+
 instrument cardholder(holder: party) {
   summary: "An account holder whose card access can be activated, suspended or closed."
   fields { holder: account of holder }

package/std/collections.hsx

@@ -1,5 +1,16 @@
 header collections
 
+// Expose case.create, assign and recover as separate steps. Creation needs overdue
+// outstanding principal and a matching slice/plan. Assignment belongs to capital;
+// recovery belongs to agency and pays the linked payment before the agency fee.
+// Payment must belong to the same plan. Recovered means that payment was processed,
+// not that the entire debt was repaid. Fee debits plan.capital, not the borrower.
+// Expose recall for capital and return_uncollected for agency when needed.
+// Contacts need an assigned case, matching agency, local hours and rolling count.
+// Contact outcomes are separate records. Reminder dispatch is operator-owned;
+// before_due/overdue are clock-owned and require active debt. Scheduled admission
+// does not prove delivery or retry. No collector can infer authority from an alias.
+
 instrument case(on: ref<financing.installments>[], agency: party, capital: party = programOperator, overdue: duration = 3d, fee: percent = 20%) {
   revisioned: true
   summary: "Refer an overdue installment without creating another debt."

package/std/escrow.hsx

@@ -1,5 +1,16 @@
 header escrow
 
+// Expose create, fund, deliver and accept for the purchase path. Create captures
+// subject.price; acceptance pays payee less the configured fee, not payer.
+// Expose dispute, verify_return and refund separately for the return path.
+// Payer disputes delivered goods; payee verifies return evidence from disputed;
+// payee refunds the entire held price from return_verified by default.
+// Acceptance expiry enters disputed, never released. Neither verify_return nor
+// refund becomes public merely because dispute is exposed. Clock actions remain
+// internal. Expose cancel for a pending hold, including a checkout-funded hold;
+// it returns its credited balance to payer before cancelling. Confirm requires
+// the whole captured price in held. This flow has no partial release or refund.
+
 instrument hold(payer: party = party(person), payee: party = programOperator, accept_within: duration = 48h, fee: fee = { seller: 0%, tax: 0% }, dispute: policy = { refund_after: return_verified }) {
   revisioned: true
   summary: "Hold the subject price through delivery, acceptance and verified return."
@@ -16,7 +27,7 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   action fund {
     from: pending, to: funded, actor: { party: payer }
     subject { price: money }
-    moves subject.price from payer to self.held
+    moves self.price from payer to self.held
   }
   action confirm {
     from: pending, to: funded
@@ -48,5 +59,8 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
     from: dispute.refund_after, to: refunded, actor: { party: payee }
     moves self.price from self.held to payer
   }
-  action cancel { from: pending, to: cancelled }
+  action cancel { allowZero: true,
+    from: pending, to: cancelled, actor: { party: payer }
+    moves self.held.balance from self.held to payer
+  }
 }

package/std/financing.hsx

@@ -1,5 +1,27 @@
 header financing
 
+// Expose create and sign on installments, then collect_down_payment as checkout
+// for disburse_to: funds. Checkout requires a signed plan and pending escrow;
+// it tops up only the missing down payment, without advancing lender principal.
+// Disburse still collects any missing down payment, activates slices, and confirms
+// the fully funded hold. Existing escrow credit counts once toward the down payment.
+// Borrower-directed disbursement excludes collect_down_payment. A down_payment
+// there reduces principal but does not collect cash. Price is subject metadata,
+// not the borrower limit. The escrow payer and price must match the plan.
+// Expose escrow cancel to return checkout cash if financing is abandoned; plan
+// void alone cancels the agreement and does not refund its separate escrow.
+// Approve borrower and portfolio limits before disbursement. Create builds the
+// dated slice records; payments need a separate payment record and pay action.
+// Expose parent payoff separately and create a current, unexpired payoff_quote.
+// Expose late_charge.create as propose_assessment before the clock can assess;
+// provide matching plan, slice and borrower. Fine is fixed money, not a percentage.
+// Collection uses the minimum of payment cash and outstanding fine; a partial
+// payment does not settle the remaining fine. Recovery cost needs its own record.
+// Profit share credits capital's allocatedProfitPayable, not an outside agency.
+// Credit lines need adapter binding at activation; draws are ledger advances,
+// not evidence of outside funding. Caller-authorized limit approvals and advances
+// need the Product's operation authority. No clock declaration proves retries.
+
 instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3, profit: percent, disburse_to: enum(funds, borrower) = funds, profit_earned: enum(on_payment, by_schedule, at_disbursement) = on_payment, apply: enum(fines_profit_principal, principal_profit, pro_rata) = fines_profit_principal, payoff_rebate: percent = 100%, write_off_after: duration = 90d, max_extension: duration = 90d, max_amendments: integer(0, 366) = 2, waiver_limit: percent = 100%, amendment_expiry: duration = 7d, payoff_quote_expiry: duration = 1h, allow_overdue: enum(allowed, blocked) = allowed, assessed_fines: enum(carry, require_waiver) = carry, down_payment: percent = 0%, funds: ref<escrow.hold>?, borrower: party = party(person), capital: party = programOperator, share: percent = 0%, limits: ref<financing.limits> = object(financing.limits), portfolio: ref<financing.portfolio_limit> = object(financing.portfolio_limit)) {
   dependencies {
     funds {
@@ -29,13 +51,22 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
   action create {
     subject { price: money }
     requires self.borrowerLimit.borrower == self.borrower
-    when disburse_to is funds { requires self.borrower == self.funds.payer }
+    when disburse_to is funds { requires self.borrower == self.funds.payer; requires self.price == self.funds.price }
     invoke: [{ range: { count: { literal: months }, maximum: months, bind: position }, instrument: slice, action: create, input: { plan: { field: self.id }, borrowerLimit: { field: self.borrowerLimit }, portfolioLimit: { field: self.portfolioLimit }, position: { field: position } } }]
   }
   action sign {
     from: quoted, to: signed, actor: { party: borrower }, input { signedOffer: text, affordabilityReference: text }
     requires count of { instrument: slice, reference: "plan", anchor: self.id, states: [draft], limit: 366 } == self.months
   }
+  action collect_down_payment { allowZero: true,
+    from: signed, to: signed, actor: { party: borrower }
+    when disburse_to is borrower { requires true == false }
+    when disburse_to is funds {
+      requires self.funds in [pending]
+      calculate: [{ target: downPaymentCredit, op: minimum, values: [{ field: self.funds.held.balance }, { field: self.downPayment }] }, { target: downPaymentRemaining, op: subtract, base: { field: self.downPayment }, subtract: [{ field: self.downPaymentCredit }] }]
+      moves self.downPaymentRemaining from self.borrower to self.funds.held
+    }
+  }
   action disburse { allowZero: true,
     from: signed, to: active, actor: { party: capital }
     requires self.borrowerLimit in [approved]
@@ -350,7 +381,7 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
       fields { slice: ref<slice>, dueAt: date = after(self.slice.dueAt, 0) }
       lifecycle { states: [pending, recognised], initial: pending }
       action create { actor: { parent: slice }, input { slice: ref<slice> }, requires unique "profit_recognition" on [self.slice] }
-      action reschedule { from: pending, to: pending, actor: { parent: slice } }
+      action reschedule { from: pending, to: pending, actor: { parent: slice }, calculate: [{ target: dueAt, op: shift, date: { field: self.slice.dueAt }, milliseconds: { literal: 0 }, direction: after }] }
       action mature { allowZero: true, from: pending, to: recognised, actor: clock, due: { at: self.dueAt }, moves self.slice.profitReceivable.balance from self.slice.profitReceivable to self.slice.profitEarned }
     }
     payment: {
@@ -451,12 +482,12 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
   }
   revisioned: true
   familyRevision: 1
-  summary: "Separate approved fine and evidenced recovery claims on an overdue installment."
+  summary: "Separate fine and evidenced recovery claims on an overdue installment."
   fields {
     plan: ref<on>, slice: ref<on.slice>, borrower: account of borrower, fine: money = fine, overdueAt: date?
     receivable: account(self, claim), debt: account(borrower, claim, contra, "debt")
   }
-  lifecycle { states: [proposed, assessed, collected, waived, refunded], initial: proposed }
+  lifecycle { states: [proposed, assessed, collected, waived], initial: proposed }
   action create { calculate: [{ target: overdueAt, op: shift, date: { field: self.slice.dueAt }, milliseconds: { literal: grace }, direction: after }], requires unique "late_assessment" on [self.slice, self.overdueAt]; requires self.borrower == self.slice.plan.borrower; requires self.plan == self.slice.plan }
   action assess { allowZero: true,
     from: proposed, to: assessed, actor: clock, due: { at: self.overdueAt }
@@ -523,7 +554,7 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
         plan: ref<on>, assessment: ref<parent>, overdueAt: date?, evidence: text, evidencedCost: money, amount: money = minimum(self.evidencedCost, cap)
         receivable: account(self, claim), debt: account(borrower, claim, contra, "debt")
       }
-      lifecycle { states: [proposed, assessed, collected, waived, refunded], initial: proposed }
+      lifecycle { states: [proposed, assessed, collected, waived], initial: proposed }
       action create { calculate: [{ target: overdueAt, op: shift, date: { field: self.assessment.overdueAt }, milliseconds: { literal: 0 }, direction: after }], requires unique "recovery_assessment" on [self.assessment]; requires self.plan == self.assessment.plan }
       action assess { allowZero: true,
         from: proposed, to: assessed, actor: clock, due: { at: self.assessment.overdueAt }

package/std/insurance.hsx

@@ -1,6 +1,21 @@
 header insurance
 
-instrument cover(holder: party, adapter: text, commission: percent = 0%, covers: ref, premium: money = runtime) {
+// Expose cover.create, activate and cancel separately. Activation binds adapter;
+// each slice needs a separately created unique period and an active cover to collect.
+// Collection debits holder for insurerPremium to the insurer and commission to
+// broker as two moves. Broker defaults to programOperator; bind a declared business
+// for a distinct agency. The two amounts sum to premium. Zero portions are allowed.
+// Cover.cancel invokes refund only on paid slices, before each startsAt. It returns
+// insurerPremium from insurer and commission from broker to holder. Active or
+// expired periods are excluded; insufficient recipient funds refuse the reversal.
+// Slice refund is parent-owned, not a public alias. Expose cover.cancel instead.
+// Claims require active cover. Expose claim.create, approve, deny and pay as needed.
+// Inspector approves OR denies from submitted. After approval only pay or clock
+// expiry can consume the reservation; deny is never available after approval.
+// Inspector is a bound party, not necessarily staff. These are ledger transfers;
+// outside settlement needs the boundary protocol, not a claim of provider success.
+
+instrument cover(holder: party, adapter: text, commission: percent = 0%, broker: party = programOperator, covers: ref, premium: money = runtime) {
   summary: "Recurring cover bound to an outside insurer across an ADL boundary."
   fields { covers: ref<covers>, holder: account of holder, insurer: account(adapter(adapter), cash, "premium"), expiresAt: date }
   lifecycle { states: [pending, active, cancelled, expired], initial: pending }
@@ -33,8 +48,8 @@ instrument cover(holder: party, adapter: text, commission: percent = 0%, covers:
         requires self.premium > "0"
         from: pending, to: paid, actor: { party: holder }
         requires self.cover in [active]
-        moves self.premium from holder to programOperator
-        moves self.insurerPremium from programOperator to self.cover.insurer
+        moves self.insurerPremium from holder to self.cover.insurer
+        moves self.commission from holder to broker
       }
       action start { from: paid, to: active, actor: clock, due: { at: self.startsAt } }
       action expire { from: active, to: expired, actor: clock, due: { at: self.endsAt } }
@@ -42,8 +57,8 @@ instrument cover(holder: party, adapter: text, commission: percent = 0%, covers:
         allowZero: true
         requires self.premium > "0"
         from: paid, to: refunded, actor: { parent: parent }, deadline: { at: self.startsAt }
-        moves self.insurerPremium from self.cover.insurer to programOperator
-        moves self.premium from programOperator to holder
+        moves self.insurerPremium from self.cover.insurer to holder
+        moves self.commission from broker to holder
       }
     }
   }

package/std/lending.hsx

@@ -1,5 +1,19 @@
 header lending
 
+// Round target is plan.principal from runtime subject.price, not its credit limit.
+// Expose round.create and close plus commitment.create and withdraw. A commitment
+// debits the bound investor's original active wallet before closesAt. Investor cap
+// aggregates by investor across wallets. Failure refunds those original wallets.
+// Closing needs the exact target; it funds plan.capital and does not disburse the
+// loan. Expose plan.disburse separately after signing and limit approval.
+// Distribution.create needs a recorded, unconsumed settlement matching the plan.
+// Prepare cash or loss first, then create shares against funded commitments of
+// that round. Distribution needs pending share weights equal to the round target.
+// Cash fee is a percentage of retained profit, VAT a percentage of that fee.
+// Principal plus retained profit less fee and VAT goes to weighted wallets;
+// floored residual goes to residual_to. Loss mode moves claim balances, not cash.
+// Child share execution is parent-owned. No report or clock proves outside payout.
+
 instrument round(borrower: party, plan: ref<financing.installments> = object(financing.installments), operator: party = programOperator, minimum_ticket: money = 100 SAR, investor_cap: percent = 20%, commitments: ref<lending.commitment> = object(lending.commitment)) {
   summary: "A threshold funding round; failed rounds return each original wallet contribution."
   fields {

package/std/marketplace.hsx

@@ -1,5 +1,19 @@
 header marketplace
 
+// Listing, order and reservation are separate agreements. Expose their create
+// and decision actions individually. Order fulfillment does not move escrow cash.
+// Pair an order with escrow.hold and expose its fund, deliver, accept, dispute,
+// verify_return and refund aliases. Refund needs disputed -> return_verified,
+// with payee evidence, then returns the full price to payer; accept pays payee.
+// A reservation holds its own deposit. Activate requires an active listing and
+// no placed order. Convert must wire the declared converters to invoke credit;
+// naming a converter alone does not add that invocation. Credit consumes the
+// deposit once, credits at most the contribution, and returns excess to buyer.
+// Expose cancel, seller_cancel or operator_cancel for the intended actors.
+// Buyer cancel and expiry use configured refund percentages; seller/operator
+// cancellation return the whole reservation balance. Converted money is in escrow,
+// so subsequent return verification and refund use the escrow aliases.
+
 instrument listing(seller: party) {
   revisioned: true
   summary: "A seller's offer and its asking price."

package/std/money.hsx

@@ -1,5 +1,18 @@
 header money
 
+// Expose each attachment's create and caller actions explicitly. A transfer or
+// split pays once; a hold exposes fund, release and refund separately. Release
+// pays payee and refund returns payer. A hold has no dispute or damage decision.
+// A schedule needs count unique occurrence records before activation; each due
+// occurrence pays only while the schedule is active. A due time promises no retry.
+// A pool accepts whole contributions only up to its remaining target and at most
+// 366 paid records. Expose pay to release the exact target. Clock failure refunds
+// original contributors; excess acceptance and partial contribution are absent.
+// A swap reserves both legs before exchange or voids reservations on expiry.
+// Payout instruct reserves across the selected adapter; confirm/reject require
+// matching terminal instruction evidence. An acknowledgement cannot settle it.
+// Metered bill charges a unique usage identity at the fixed unit price.
+
 instrument transfer(payer: party, payee: party, amount: money = runtime) {
   summary: "One transfer between the bound parties."
   fields { amount: money = amount }

package/std/reporting.hsx

@@ -1,5 +1,15 @@
 header reporting
 
+// Attach portfolio to one or more financing plans. Its only lifecycle action is
+// create; reports use the declared report request/read roles, not a money action.
+// Aging selects active facilities and includes earned profit when deciding arrears.
+// The default-rate report measures period-end stock, not new default incidence.
+// Paid facilities are excluded and write-offs counted separately. Amounts are SAR
+// minor units; declared scale and rounding govern ratios. Missing identity joins
+// or unreconciled schedule counts refuse. Origination cohorts and bureau output
+// explicitly refuse until their unavailable governed facts exist. No bureau
+// submission, provider layout, external transport or restructuring proof is supplied.
+
 instrument portfolio(on: ref<financing.installments>[], default_days: integer(1, 3650) = 90, retention_years: integer(1, 100) = 10, aging_first_days: integer(1, 3650) = 30, aging_second_days: integer(1, 3650) = 60, aging_third_days: integer(1, 3650) = 90, ratio_scale: integer(1, 1000000) = 10000, ratio_rounding: enum(floor, halfUp) = floor, lock_wait_ms: integer(1, 2000) = 2000, capture_ms: integer(1, 10000) = 10000, max_rows: integer(1, 100000) = 10000, max_join_rows: integer(1, 1000000) = 100000, max_bytes: integer(1024, 16777216) = 8388608) {
   summary: "Declared financing reports evaluated over frozen Product facts."
   fields {}

package/std/savings.hsx

@@ -1,8 +1,25 @@
 header savings
 
+// Expose circle.create and membership.create; create one pending contribution
+// record per member per circle date before membership.activate. Circle activation
+// is clock-owned and needs exactly members joined memberships at or after startsAt.
+// Membership.activate needs the active circle and its full pending schedule.
+// Membership.received means the member received the pot. Contribution.paid means
+// one contribution was collected. Neither record's state proves the other's state.
+// A member can have received the pot with future unpaid contributions, or paid
+// a contribution while their membership still waits for its payout seat.
+// Receive counts preceding received memberships, never paid contributions.
+// Eight members at 300 SAR require 2400 SAR per payout; seven payments supply 2100,
+// so a full payout lacks 300 unless other cash exists. There is no reduced payout.
+// Contribution.pay has a due time and no deadline or prior-payment requirement.
+// Late and out-of-order collection is admitted while membership is active or
+// received and circle is active. Clock admission does not promise scheduler retry.
+// Circle.close needs every membership received and an empty held account.
+// Circle creation collects circleDates, one date per member for contributions and payouts.
+
 instrument circle(contribution: money, members: integer(1, 60), starts: date, memberships: ref<savings.membership> = object(savings.membership)) {
   summary: "A fixed group contributes on its explicit calendar and takes the pot in order."
-  fields { contribution: money = contribution, members: integer = members, startsAt: date = starts, dates: list(date, members), pot: money = multiply(self.contribution, self.members), held: account of self }
+  fields { contribution: money = contribution, members: integer = members, startsAt: date = starts, circleDates: list(date, members), pot: money = multiply(self.contribution, self.members), held: account of self }
   lifecycle { states: [forming, active, closed, disbanded], initial: forming }
   action create { }
   action activate {
@@ -11,35 +28,35 @@ instrument circle(contribution: money, members: integer(1, 60), starts: date, me
   }
   action close {
     from: active, to: closed
-    requires count of { instrument: memberships, reference: "circle", anchor: self.id, states: [paid], limit: 60 } == self.members
+    requires count of { instrument: memberships, reference: "circle", anchor: self.id, states: [received], limit: 60 } == self.members
     requires self.held.balance == "0"
   }
   action disband { from: forming, to: disbanded }
 }
 
 instrument membership(circle: ref<savings.circle>, member: party) {
-  summary: "A member contributes on the circle calendar and receives the pot in the assigned position."
-  fields { circle: ref<circle>, member: account of member, position: integer(1, 60), preceding: integer = subtract(self.position, 1), receivesAt: date = at(self.circle.dates, self.position), contribution: money = self.circle.contribution, total: money = self.circle.pot }
-  lifecycle { states: [joined, active, paid, withdrawn], initial: joined }
-  action create { requires self.position <= self.circle.members; requires self.circle in [forming]; requires unique "circle_seat" on [self.circle, self.position]; requires unique "circle_member" on [self.circle, self.member] }
+  summary: "A member contributes on the circle calendar and receives the pot in the assigned seat."
+  fields { circle: ref<circle>, member: account of member, seat: integer(1, 60), preceding: integer = subtract(self.seat, 1), receivesAt: date = at(self.circle.circleDates, self.seat), contribution: money = self.circle.contribution, total: money = self.circle.pot }
+  lifecycle { states: [joined, active, received, withdrawn], initial: joined }
+  action create { requires self.seat <= self.circle.members; requires self.circle in [forming]; requires unique "circle_seat" on [self.circle, self.seat]; requires unique "circle_member" on [self.circle, self.member] }
   action activate {
     from: joined, to: active
     requires self.circle in [active]
     requires count of { instrument: contribution, reference: "membership", anchor: self.id, states: [pending], limit: 60 } == self.circle.members
   }
   action receive {
-    from: active, to: paid, actor: clock, due: { at: self.receivesAt }
+    from: active, to: received, actor: clock, due: { at: self.receivesAt }
     requires self.circle in [active]
-    requires count of { instrument: all(savings.membership), reference: "circle", anchor: self.circle, states: [paid], limit: 60 } == self.preceding
+    requires count of { instrument: all(savings.membership), reference: "circle", anchor: self.circle, states: [received], limit: 60 } == self.preceding
     moves self.total from self.circle.held to self.member
   }
   action withdraw { from: joined, to: withdrawn, requires self.circle in [disbanded] }
   records {
     contribution: {
-      fields { membership: ref<parent>, position: integer(1, 60), dueAt: date = at(self.membership.circle.dates, self.position), amount: money = self.membership.contribution }
+      fields { membership: ref<parent>, period: integer(1, 60), dueAt: date = at(self.membership.circle.circleDates, self.period), amount: money = self.membership.contribution }
       lifecycle { states: [pending, paid], initial: pending }
-      action create { requires self.position <= self.membership.circle.members; requires self.membership in [joined]; requires unique "seat_period" on [self.membership, self.position] }
-      action pay { from: pending, to: paid, actor: clock, due: { at: self.dueAt }, requires self.membership in [active, paid]; requires self.membership.circle in [active], moves self.amount from self.membership.member to self.membership.circle.held }
+      action create { requires self.period <= self.membership.circle.members; requires self.membership in [joined]; requires unique "seat_period" on [self.membership, self.period] }
+      action pay { from: pending, to: paid, actor: clock, due: { at: self.dueAt }, requires self.membership in [active, received]; requires self.membership.circle in [active], moves self.amount from self.membership.member to self.membership.circle.held }
     }
   }
 }

package/std/travel.hsx

@@ -1,5 +1,23 @@
 header travel
 
+// Publish a package before booking.create. Expose deposit, balance and confirm
+// separately. Deposit needs pending premium slices whose cover is active, and
+// collects those premiums in addition to booking cash. Balance is due by balanceAt.
+// Expose cancel_early, cancel_middle and cancel_late for the desired booking paths.
+// Early returns all held booking cash, whether deposit-only or fully paid. Middle
+// returns held minus the original deposit; a deposit-only booking gets zero.
+// Supplier penalty is based on supplierCost; tax applies to retained margin,
+// and the bound operator receives the remainder. Late returns no buyer cash.
+// Middle opens at earlyAt and ends at lateAt, which is middleAt plus 1ms; late
+// starts there. Default_balance can already cancel a deposit_paid booking at
+// balanceAt, after which no booking cancellation is reachable. Clock order matters.
+// Booking refunds exclude insurance premiums, broker commission and all balances
+// outside booking.held. Expose cover.cancel independently to refund eligible paid
+// premium periods before startsAt; slice.refund is parent-owned. Active/expired
+// premium periods remain excluded. Confirmation timeout returns the full booking
+// price from paid only. A penalty above held cash or retained deposit refuses;
+// this header does not subsidize a shortfall or reduce the configured penalty.
+
 instrument package(price: money, supplier_cost: money, departure: date) {
   constraints { supplier_cost: at_most(price) }
   summary: "Immutable package price, supplier cost and departure."
@@ -48,7 +66,7 @@ instrument booking(package: ref<travel.package>, buyer: party, supplier: party,
     due: { at: self.package.departure }, deadline: { at: self.confirmBy }
     moves self.supplierCost from self.held to supplier
     moves self.tax from self.held to programTax
-    moves self.operatorNet from self.held to programOperator
+    moves self.operatorNet from self.held to operator
   }
   action timeout {
     from: paid, to: refunded, actor: clock, due: { at: self.confirmBy }
@@ -69,7 +87,7 @@ instrument booking(package: ref<travel.package>, buyer: party, supplier: party,
     moves self.refund from self.held to buyer
     moves self.middlePenalty from self.held to supplier
     moves self.retainedTax from self.held to programTax
-    moves self.retainedNet from self.held to programOperator
+    moves self.retainedNet from self.held to operator
   }
   action cancel_late { allowZero: true, requires self.price > "0";
     from: [deposit_paid, paid], to: cancelled, actor: { party: buyer }, due: { at: self.lateAt }
@@ -80,7 +98,7 @@ instrument booking(package: ref<travel.package>, buyer: party, supplier: party,
     ]
     moves self.latePenalty from self.held to supplier
     moves self.retainedTax from self.held to programTax
-    moves self.retainedNet from self.held to programOperator
+    moves self.retainedNet from self.held to operator
   }
   action default_balance { allowZero: true, requires self.price > "0";
     from: deposit_paid, to: cancelled, actor: clock, due: { at: self.balanceAt }
@@ -91,6 +109,6 @@ instrument booking(package: ref<travel.package>, buyer: party, supplier: party,
     ]
     moves self.latePenalty from self.held to supplier
     moves self.retainedTax from self.held to programTax
-    moves self.retainedNet from self.held to programOperator
+    moves self.retainedNet from self.held to operator
   }
 }

package/std/wallet.hsx

@@ -1,5 +1,14 @@
 header wallet
 
+// Expose balance.create, activate, topup and withdraw as needed. Holder moves
+// cash only while active. Freeze blocks new topups, withdrawals and spend reserves;
+// close requires no held cash. Freeze/unfreeze use caller operation authority.
+// A separate spend record checks its amount against spendLimit at creation.
+// Expose reserve, pay and cancel for the bound payee. Reserve requires an active
+// wallet before expiresAt; pay posts the whole reservation, cancel/expiry void it.
+// Existing reservations may still post after the wallet freezes. There is no
+// daily aggregate limit, partial spend or card-network settlement in this header.
+
 instrument balance(holder: party, spend_limit: money = 100000 SAR) {
   summary: "A holder's reusable balance with an immutable per-spend ceiling."
   fields { holder: account of holder, held: account of self, spendLimit: money = spend_limit }