@hyperscale0/hsx 1.0.130 → 1.0.134

package/std/cards.hsx

@@ -2,7 +2,10 @@ header cards
 
 // Activate holder and card before creating and approving an authorization.
 // Only the Product operator activates, suspends or resumes a cardholder; the
-// holder freezes, unfreezes and cancels their own card.
+// 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
@@ -26,18 +29,22 @@ instrument cardholder(holder: party) {
   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 }
+  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

@@ -15,14 +15,23 @@ header escrow
 // 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.
-// After a paid plan's refund window, the plan's return_hold runs it from funded
-// or return_verified to return the whole balance to the payer.
-// Only an installments plan can run confirm and unwind_financed; without
-// financing neither action exists, so no hold reaches funded without fundedAt. The plan's confirm leaves fundedAt unset, so
-// refund_undelivered never comes due on a financed hold and no schedule offers it.
+// 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;
@@ -38,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 }
@@ -54,6 +63,7 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   action confirm {
     from: pending, to: funded, actor: { parent: all(financing.installments) }
     requires self.held.balance == self.price
+    calculate: [{ target: deliverBy, op: shift, date: { field: self.now }, milliseconds: { literal: deliver_within }, direction: after }]
   }
   action deliver {
     from: funded, to: delivered, actor: { party: payee }
@@ -77,6 +87,22 @@ 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: [quoted, signed, active, paid, written_off], limit: 1 } == 0