@hyperscale0/hsx 1.0.128 → 1.0.132

package/std/booking.hsx

@@ -21,7 +21,7 @@ header booking
 // cancellation and completion move the held balance. Run hsx cost for the
 // composed counts.
 
-instrument reservation(customer: party = party(person), operator: party = programOperator, early_until: duration = 30d, late_from: duration = 15d, balance_due: duration = 14d, middle_forfeit: percent = 0%, late_forfeit: percent = 0%) {
+instrument reservation(customer: party = party(person), operator: party = programOperator, early_until: duration = 30d, late_from: duration = 15d, balance_due: duration = 15d, middle_forfeit: percent = 0%, late_forfeit: percent = 0%) {
   revisioned: true
   summary: "Take a deposit and a balance for a dated booking, with cancellation windows before departure."
   fields {

package/std/cards.hsx

@@ -1,6 +1,11 @@
 header cards
 
 // Activate holder and card before creating and approving an authorization.
+// Only the Product operator activates, suspends or resumes a cardholder; the
+// cardholder or the Product operator closes it. The card's person, bound to the
+// cardholder's holder, freezes, unfreezes and cancels their own card. The issuer
+// freezes it with issuer_freeze into blocked, which only issuer_unfreeze lifts,
+// and cancels it with issuer_cancel.
 // 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
@@ -21,21 +26,25 @@ instrument cardholder(holder: party) {
   fields { holder: account of holder }
   lifecycle { states: [pending, active, suspended, closed], initial: pending }
   action create {}
-  action activate { from: pending, to: active }
-  action suspend { from: active, to: suspended }
-  action resume { from: suspended, to: active }
-  action close { from: [active, suspended], to: closed }
+  action activate { from: pending, to: active, actor: { party: programOperator } }
+  action suspend { from: active, to: suspended, actor: { party: programOperator } }
+  action resume { from: suspended, to: active, actor: { party: programOperator } }
+  action close { from: [active, suspended], to: closed, actor: { party: holder } }
+  action operator_close { from: [active, suspended], to: closed, actor: { party: programOperator } }
 }
 
-instrument card(holder: ref<cards.cardholder>, spend_limit: money) {
+instrument card(holder: ref<cards.cardholder>, spend_limit: money, issuer: party = programOperator, person: party = party(person)) {
   summary: "A card with a per-spend ceiling that can be activated, frozen or cancelled."
-  fields { holder: ref<holder>, spendLimit: money = spend_limit }
-  lifecycle { states: [issued, active, frozen, cancelled], initial: issued }
-  action create { requires self.holder in [active] }
+  fields { holder: ref<holder>, person: account of person, spendLimit: money = spend_limit }
+  lifecycle { states: [issued, active, frozen, blocked, cancelled], initial: issued }
+  action create { requires self.holder in [active]; requires self.holder.holder == self.person }
   action activate { from: issued, to: active, requires self.holder in [active] }
-  action freeze { from: active, to: frozen }
-  action unfreeze { from: frozen, to: active, requires self.holder in [active] }
-  action cancel { from: [issued, active, frozen], to: cancelled }
+  action freeze { from: active, to: frozen, actor: { party: person } }
+  action unfreeze { from: frozen, to: active, actor: { party: person }, requires self.holder in [active] }
+  action issuer_freeze { from: [active, frozen], to: blocked, actor: { party: issuer } }
+  action issuer_unfreeze { from: [frozen, blocked], to: active, actor: { party: issuer }, requires self.holder in [active] }
+  action cancel { from: [issued, active, frozen, blocked], to: cancelled, actor: { party: person } }
+  action issuer_cancel { from: [issued, active, frozen, blocked], to: cancelled, actor: { party: issuer } }
 }
 
 instrument authorization(card: ref<cards.card>, merchant: party, issuer: party = programOperator) {

package/std/escrow.hsx

@@ -9,13 +9,29 @@ header escrow
 // Expose dispute, verify_return and refund separately for the return path.
 // Payer disputes delivered goods; payee verifies return evidence from disputed.
 // Payee refunds the whole held balance before delivery, or from return_verified
-// by default after a dispute. While a signed, active or paid financing plan funds
-// the hold, both refunds refuse: the plan's unwind returns the lender's principal
-// first, then refund returns the rest. Unwind needs return_verified, so a
-// financed hold cannot be refunded before delivery.
+// by default after a dispute. While a financing plan funds the hold in any state
+// but cancelled, both refunds refuse, so a written-off plan never hands lender
+// principal to the payer. Only unwind returns the principal to capital and
+// cancels the plan; after that, refund returns the rest. Before delivery the
+// Product operator runs the plan's unwind_undelivered instead, which invokes
+// unwind_financed here to return the rest to the payer and close the hold.
+// For a paid plan, the plan's unwind_paid runs unwind_financed from funded after
+// deliverBy, and return_hold or unwind_paid runs it from return_verified,
+// depending on the plan's returned_goods.
+// Only an installments plan can run confirm and unwind_financed. In a program
+// without financing neither action exists, so every hold reaches funded through
+// fund, which sets fundedAt. The plan's confirm leaves fundedAt unset, so
+// refund_undelivered never comes due on a financed hold and no schedule offers
+// it. Confirm sets deliverBy, deliver_within after confirmation, and the plan's
+// unwind_paid waits for it so the payee keeps the whole delivery window.
 // Expose refund_undelivered to let the payer take the whole held price back once
 // deliver_within has passed since funding without delivery. It is a payer action
 // that becomes available at that time; nothing runs it automatically.
+// The Product operator settles any disputed hold: settle_release pays the payee
+// as acceptance would, and settle_return moves it to return_verified. Without a
+// live plan, settle_return also runs settle_refund to return the whole balance
+// to the payer. A financed return continues on the plan's returned-goods path,
+// and once that plan is cancelled the operator's settle_refund returns the rest.
 // 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;
@@ -31,7 +47,7 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   summary: "Hold the subject price through delivery, acceptance and verified return."
   fields {
     payer: account of payer, payee: account of payee
-    held: account of self, fundedAt: date?, deliveredAt: date?
+    held: account of self, fundedAt: date?, deliverBy: date?, deliveredAt: date?, openPlans: integer?
     price: money = subject.price
   }
   lifecycle { states: [pending, funded, delivered, disputed, return_verified, released, refunded, cancelled], initial: pending }
@@ -41,14 +57,13 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   }
   action fund {
     from: pending, to: funded, actor: { party: payer }
-    subject { price: money }
     set: { fundedAt: { field: self.now } }
     moves self.price from payer to self.held economics { purpose: principal, sourceParty: payer }
   }
   action confirm {
-    from: pending, to: funded
+    from: pending, to: funded, actor: { parent: all(financing.installments) }
     requires self.held.balance == self.price
-    set: { fundedAt: { field: self.now } }
+    calculate: [{ target: deliverBy, op: shift, date: { field: self.now }, milliseconds: { literal: deliver_within }, direction: after }]
   }
   action deliver {
     from: funded, to: delivered, actor: { party: payee }
@@ -72,17 +87,37 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
     from: disputed, to: return_verified, actor: { party: payee }
     input { returnEvidence: text }
   }
+  action settle_release { allowZero: true, requires self.price > "0";
+    from: disputed, to: released, actor: { party: programOperator }
+    input { ruling: text }
+    moves self.price from self.held to payee fee fee economics { payee: { recipient: payee, company: { purpose: earning, sourceParty: payer }, participant: { purpose: pass_through, sourceParty: programOperator } }, fee: { purpose: earning, sourceParty: payer }, tax: { purpose: pass_through, sourceParty: programOperator } }
+  }
+  action settle_return {
+    from: disputed, to: return_verified, actor: { party: programOperator }
+    input { ruling: text }
+    calculate: [{ target: openPlans, op: aggregate, selection: { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [quoted, signed, active, paid, written_off], limit: 1 }, measure: count }]
+    invoke: [{ reference: self.id, action: settle_refund, guard: { kind: compare, left: { field: self.openPlans }, operator: "==", right: { literal: 0 } }, input: {} }]
+  }
+  action settle_refund { allowZero: true,
+    from: return_verified, to: refunded, actor: { party: programOperator }
+    requires count of { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [quoted, signed, active, paid, written_off], limit: 1 } == 0
+    moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }
+  }
   action refund {
     from: [funded, dispute.refund_after], to: refunded, actor: { party: payee }
-    requires count of { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [signed, active, paid], limit: 1 } == 0
+    requires count of { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [quoted, signed, active, paid, written_off], limit: 1 } == 0
     moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }
   }
   action refund_undelivered {
     from: funded, to: refunded, actor: { party: payer }
     due: { at: self.fundedAt, offset: deliver_within }
-    requires count of { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [signed, active, paid], limit: 1 } == 0
+    requires count of { instrument: all(financing.installments), reference: "funds", anchor: self.id, states: [quoted, signed, active, paid, written_off], limit: 1 } == 0
     moves self.price from self.held to payer economics { purpose: principal, sourceParty: programOperator }
   }
+  action unwind_financed { allowZero: true,
+    from: [funded, return_verified], to: refunded, actor: { parent: all(financing.installments) }
+    moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }
+  }
   action cancel { allowZero: true,
     from: pending, to: cancelled, actor: { party: payer }
     moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }