@hyperscale0/hsx 5.4.2 → 5.6.0

package/src/version.ts

@@ -1 +1 @@
-export const HSX_VERSION = "5.4.2";
+export const HSX_VERSION = "5.6.0";

package/std/collections.hsx

@@ -1,5 +1,8 @@
 header collections
 
+// Economics: Company capital pays agencies as participant payouts; outside capital passes through.
+// A company agency earns outside capital fees; its own capital fee is internal.
+
 // 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.
@@ -28,7 +31,7 @@ instrument case(on: ref<financing.installments>[], agency: party, capital: party
   }
   action assign { from: opened, to: assigned, actor: { party: capital } }
   action recover { expansionLimit: 8192, from: assigned, to: recovered, actor: { party: agency }, requires self.payment.plan == self.plan, invoke: [{ reference: self.payment, action: pay, input: {} }, { reference: self.id, action: pay_fee, input: {} }] }
-  action pay_fee { allowZero: true, from: recovered, to: recovered, actor: { parent: current() }, moves self.agencyFee from self.plan.capital to agency }
+  action pay_fee { allowZero: true, from: recovered, to: recovered, actor: { parent: current() }, moves self.agencyFee from self.plan.capital to agency economics { recipient: agency, company: { recipient: capital, company: { purpose: internal, sourceParty: capital }, participant: { purpose: earning, sourceParty: capital } }, participant: { recipient: capital, company: { purpose: participant_payout, sourceParty: capital }, participant: { purpose: pass_through, sourceParty: capital } } } }
   action recall { from: [opened, assigned], to: recalled, actor: { party: capital } }
   action return_uncollected { from: assigned, to: returned_uncollected, actor: { party: agency } }
 }

package/std/escrow.hsx

@@ -1,5 +1,8 @@
 header escrow
 
+// Economics: Funding and unspent returns are principal. Acceptance realizes earnings for
+// the company or a payout to a bound outside seller; tax is pass-through.
+
 // 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.
@@ -31,7 +34,7 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   action fund {
     from: pending, to: funded, actor: { party: payer }
     subject { price: money }
-    moves self.price from payer to self.held
+    moves self.price from payer to self.held economics { purpose: principal, sourceParty: payer }
   }
   action confirm {
     from: pending, to: funded
@@ -45,7 +48,7 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
     from: delivered, to: released, actor: { party: payer }
     input { acceptanceReference: text }
     deadline: { at: self.deliveredAt, offset: accept_within }
-    moves self.price from self.held to payee fee fee
+    moves self.price from self.held to payee fee fee economics { payee: { recipient: payee, company: { purpose: earning, sourceParty: payer }, participant: { purpose: participant_payout, sourceParty: programOperator } }, fee: { purpose: earning, sourceParty: payer }, tax: { purpose: pass_through, sourceParty: programOperator } }
   }
   action expire_acceptance {
     from: delivered, to: disputed, actor: clock
@@ -61,10 +64,10 @@ instrument hold(payer: party = party(person), payee: party = programOperator, ac
   }
   action refund {
     from: dispute.refund_after, to: refunded, actor: { party: payee }
-    moves self.price from self.held to payer
+    moves self.price 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
+    moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }
   }
 }

package/std/financing.hsx

@@ -1,5 +1,10 @@
 header financing
 
+// Economics: Principal advances and repayments are excluded from earnings. Claims, waivers,
+// write-offs and allocations are internal. Paid profit and company charges are
+// earnings; receipt refunds reverse captured cash. Outside recovery recipients
+// receive payouts from held company cash, or pass-through direct customer cash.
+
 // 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.
@@ -68,7 +73,7 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
     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
+      moves self.downPaymentRemaining from self.borrower to self.funds.held economics { purpose: principal, sourceParty: borrower }
     }
   }
   action disburse { allowZero: true,
@@ -79,7 +84,7 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
       requires self.funds in [pending]
       invoke: [{ reference: self.id, action: fund_down_payment, input: {} }]
     }
-    when disburse_to is borrower { moves self.principal from self.capital to self.borrower }
+    when disburse_to is borrower { moves self.principal from self.capital to self.borrower economics { purpose: principal, sourceParty: capital } }
     invoke: [{ selection: { instrument: slice, reference: "plan", anchor: self.id, states: [draft], limit: 366, order: [position] }, action: activate, input: {} }]
     when disburse_to is funds { invoke: [{ reference: self.funds, action: confirm, input: {} }] }
   }
@@ -87,8 +92,8 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
     from: active, to: active, actor: { parent: current() }
     when disburse_to is funds {
       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.funds.payer to self.funds.held
-      moves self.principal from self.capital to self.funds.held
+      moves self.downPaymentRemaining from self.funds.payer to self.funds.held economics { purpose: principal, sourceParty: borrower }
+      moves self.principal from self.capital to self.funds.held economics { purpose: principal, sourceParty: capital }
     }
   }
   action complete {
@@ -233,11 +238,11 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
         input { plan: ref<parent>, identity: text, principal: money, profit: money, loss: money, kind: enum(cash, loss) }
         requires unique "settlement_identity" on [self.plan, self.identity]
         calculate: [{ target: "share", op: "rate", base: { field: self.profit }, bps: { literal: share }, rounding: "floor" }, { target: retainedProfit, op: "subtract", base: { field: self.profit }, subtract: [{ field: self.share }] }]
-        moves self.share from self.profitIncome to self.allocatedPayable
+        moves self.share from self.profitIncome to self.allocatedPayable economics { purpose: internal, sourceParty: capital }
       }
       action refund { allowZero: true,
         from: recorded, to: refunded, actor: { parent: payment }
-        moves self.share from self.allocatedPayable to self.profitIncome
+        moves self.share from self.allocatedPayable to self.profitIncome economics { purpose: internal, sourceParty: capital }
       }
     }
     slice: {
@@ -303,9 +308,9 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
       }
       action activate { allowZero: true,
         from: draft, to: pending, actor: { parent: parent }
-        moves self.principal from self.debt to self.principalReceivable
-        moves self.profit from self.debt to self.profitReceivable
-        when profit_earned is at_disbursement { moves self.profit from self.profitReceivable to self.profitEarned }
+        moves self.principal from self.debt to self.principalReceivable economics { purpose: internal, sourceParty: borrower }
+        moves self.profit from self.debt to self.profitReceivable economics { purpose: internal, sourceParty: borrower }
+        when profit_earned is at_disbursement { moves self.profit from self.profitReceivable to self.profitEarned economics { purpose: internal, sourceParty: programOperator } }
         when profit_earned is by_schedule { invoke: [{ instrument: recognition, action: create, input: { slice: { field: self.id } } }] }
       }
       action mature {
@@ -370,15 +375,15 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
         from: [pending, due], to: paid, actor: { parent: parent }, input { identity: text }
         set: { payoffIdentity: { field: input.identity } }
         calculate: [{ target: payoffRebate, op: rate, base: { field: self.profitReceivable.balance }, bps: { literal: payoff_rebate }, rounding: floor }, { target: payoffProfitTotal, op: sum, values: [{ field: self.profitReceivable.balance }, { field: self.profitEarned.balance }] }, { target: payoffProfit, op: subtract, base: { field: self.payoffProfitTotal }, subtract: [{ field: self.payoffRebate }] }]
-        moves self.principalReceivable.balance from self.plan.borrower to self.plan.capital
-        moves self.payoffProfit from self.plan.borrower to self.plan.profitIncome
-        moves self.principalReceivable.balance from self.principalReceivable to self.debt
-        moves self.profitReceivable.balance from self.profitReceivable to self.debt
-        moves self.profitEarned.balance from self.profitEarned to self.debt
+        moves self.principalReceivable.balance from self.plan.borrower to self.plan.capital economics { purpose: principal, sourceParty: borrower }
+        moves self.payoffProfit from self.plan.borrower to self.plan.profitIncome economics { recipient: capital, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: pass_through, sourceParty: borrower } }
+        moves self.principalReceivable.balance from self.principalReceivable to self.debt economics { purpose: internal, sourceParty: programOperator }
+        moves self.profitReceivable.balance from self.profitReceivable to self.debt economics { purpose: internal, sourceParty: programOperator }
+        moves self.profitEarned.balance from self.profitEarned to self.debt economics { purpose: internal, sourceParty: programOperator }
       }
       action write_off { allowZero: true,
         from: [pending, due], to: written_off, actor: { parent: parent }
-        moves self.principalReceivable.balance from self.principalReceivable to self.loss; moves self.profitReceivable.balance from self.profitReceivable to self.debt; moves self.profitEarned.balance from self.profitEarned to self.loss
+        moves self.principalReceivable.balance from self.principalReceivable to self.loss economics { purpose: internal, sourceParty: programOperator }; moves self.profitReceivable.balance from self.profitReceivable to self.debt economics { purpose: internal, sourceParty: programOperator }; moves self.profitEarned.balance from self.profitEarned to self.loss economics { purpose: internal, sourceParty: programOperator }
       }
     }
     recognition: {
@@ -386,7 +391,7 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
       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 }, 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 }
+      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 economics { purpose: internal, sourceParty: programOperator } }
     }
     payment: {
       revisioned: true
@@ -408,7 +413,7 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
         when apply is principal_profit { calculate: [{ target: outstandingTotal, op: sum, values: [{ field: self.outstandingPrincipal }, { field: self.outstandingProfit }] }] }
         when apply is pro_rata { calculate: [{ target: outstandingTotal, op: sum, values: [{ field: self.outstandingPrincipal }, { field: self.outstandingProfit }] }] }
         requires self.plan in [active]; requires self.amount <= self.outstandingTotal
-        moves self.amount from self.plan.borrower to self.held
+        moves self.amount from self.plan.borrower to self.held economics { purpose: principal, sourceParty: borrower }
         when apply is principal_profit {
           invoke: [{ selection: { instrument: slice, reference: "plan", anchor: self.plan, states: [pending, due], limit: 366, order: [position] }, action: collect, guard: { kind: compare, left: { field: self.held.balance }, operator: ">", right: { literal: "0" } }, input: { payment: { field: self.id } } }]
         }
@@ -445,32 +450,32 @@ instrument installments(months: integer(1, 366), charge_limit: integer(1, 3) = 3
         actor: { parent: slice }
         input { slice: ref<slice>, payment: ref<payment>, limit: money }
         requires unique "principal_receipt" on [self.slice, self.payment]
-        moves self.amount from self.payment.held to self.slice.plan.capital; moves self.amount from self.slice.principalReceivable to self.slice.debt
+        moves self.amount from self.payment.held to self.slice.plan.capital economics { purpose: principal, sourceParty: programOperator }; moves self.amount from self.slice.principalReceivable to self.slice.debt economics { purpose: internal, sourceParty: programOperator }
       }
       action refund { allowZero: true,
         from: paid, to: refunded, actor: { parent: payment }
-        moves self.amount from self.slice.plan.capital to self.slice.plan.borrower; moves self.amount from self.slice.debt to self.slice.principalReceivable
+        moves self.amount from self.slice.plan.capital to self.slice.plan.borrower economics { purpose: principal, sourceParty: capital }; moves self.amount from self.slice.debt to self.slice.principalReceivable economics { purpose: internal, sourceParty: borrower }
       }
     }
     profit_piece: {
-      fields { slice: ref<slice>, payment: ref<payment>, limit: money, amount: money? }
+      fields { cashReceipt: text?, slice: ref<slice>, payment: ref<payment>, limit: money, amount: money? }
       lifecycle { states: [paid, refunded], initial: paid }
       action create { allowZero: true,
         calculate: [{ target: amount, op: minimum, values: [{ field: self.payment.held.balance }, { field: self.limit }] }]
         actor: { parent: slice }
         input { slice: ref<slice>, payment: ref<payment>, limit: money }
         requires unique "profit_receipt" on [self.slice, self.payment]
-        moves self.amount from self.payment.held to self.slice.plan.profitIncome
-        when profit_earned is on_payment { moves self.amount from self.slice.profitReceivable to self.slice.debt }
-        when profit_earned is by_schedule { moves self.amount from self.slice.profitEarned to self.slice.debt }
-        when profit_earned is at_disbursement { moves self.amount from self.slice.profitEarned to self.slice.debt }
+        moves self.amount from self.payment.held to self.slice.plan.profitIncome capture "cashReceipt" economics { recipient: capital, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: participant_payout, sourceParty: programOperator } }
+        when profit_earned is on_payment { moves self.amount from self.slice.profitReceivable to self.slice.debt economics { purpose: internal, sourceParty: programOperator } }
+        when profit_earned is by_schedule { moves self.amount from self.slice.profitEarned to self.slice.debt economics { purpose: internal, sourceParty: programOperator } }
+        when profit_earned is at_disbursement { moves self.amount from self.slice.profitEarned to self.slice.debt economics { purpose: internal, sourceParty: programOperator } }
       }
       action refund { allowZero: true,
         from: paid, to: refunded, actor: { parent: payment }
-        moves self.amount from self.slice.plan.profitIncome to self.slice.plan.borrower
-        when profit_earned is on_payment { moves self.amount from self.slice.debt to self.slice.profitReceivable }
-        when profit_earned is by_schedule { moves self.amount from self.slice.debt to self.slice.profitEarned }
-        when profit_earned is at_disbursement { moves self.amount from self.slice.debt to self.slice.profitEarned }
+        moves self.amount from self.slice.plan.profitIncome to self.slice.plan.borrower economics { recipient: capital, company: { purpose: earning, sourceParty: capital, reversalOf: self.cashReceipt }, participant: unclassified }
+        when profit_earned is on_payment { moves self.amount from self.slice.debt to self.slice.profitReceivable economics { purpose: internal, sourceParty: borrower } }
+        when profit_earned is by_schedule { moves self.amount from self.slice.debt to self.slice.profitEarned economics { purpose: internal, sourceParty: borrower } }
+        when profit_earned is at_disbursement { moves self.amount from self.slice.debt to self.slice.profitEarned economics { purpose: internal, sourceParty: borrower } }
       }
     }
   }
@@ -496,7 +501,7 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
   action assess { allowZero: true,
     from: proposed, to: assessed, actor: clock, due: { at: self.overdueAt }
     requires self.slice.principalReceivable.balance > "0"
-    moves self.fine from self.debt to self.receivable
+    moves self.fine from self.debt to self.receivable economics { purpose: internal, sourceParty: borrower }
   }
   action collect {
     from: [assessed, collected], to: assessed, actor: { parent: child(on, slice) }, input { payment: ref<on.payment> }
@@ -507,8 +512,8 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
   action payoff { allowZero: true,
     from: [assessed, collected], to: collected, actor: { parent: on }
     requires self.plan in [paid]
-    moves self.receivable.balance from self.plan.borrower to fines_to
-    moves self.receivable.balance from self.receivable to self.debt
+    moves self.receivable.balance from self.plan.borrower to fines_to economics { recipient: fines_to, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: pass_through, sourceParty: borrower } }
+    moves self.receivable.balance from self.receivable to self.debt economics { purpose: internal, sourceParty: programOperator }
   }
   action finish { from: assessed, to: collected, actor: { parent: current() }, requires self.receivable.balance == "0" }
   action cancel { from: proposed, to: waived }
@@ -517,7 +522,7 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
     requires input.amendment.plan == self.plan; requires input.amendment in [applied]
     invoke: [{ instrument: waiver, action: create, input: { assessment: { field: self.id }, amendment: { field: input.amendment } } }]
   }
-  action waive { allowZero: true, from: [assessed, collected], to: waived, actor: { parent: waiver_request }, input { reason: text, evidence: text }, moves self.receivable.balance from self.receivable to self.debt }
+  action waive { allowZero: true, from: [assessed, collected], to: waived, actor: { parent: waiver_request }, input { reason: text, evidence: text }, moves self.receivable.balance from self.receivable to self.debt economics { purpose: internal, sourceParty: programOperator } }
   action refund {
     from: [assessed, collected], to: assessed, actor: { party: fines_to }, input { payment: ref<on.payment> }
     requires input.payment in [paid, refunded]
@@ -542,14 +547,14 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
         actor: { parent: parent }, input { assessment: ref<parent>, amendment: ref<on.amendment> }
         calculate: [{ target: amount, op: rate, base: { field: self.assessment.receivable.balance }, bps: { field: self.amendment.waiverPercent }, rounding: floor }]
         requires unique "amendment_waiver" on [self.assessment, self.amendment]
-        moves self.amount from self.assessment.receivable to self.assessment.debt
+        moves self.amount from self.assessment.receivable to self.assessment.debt economics { purpose: internal, sourceParty: programOperator }
       }
     }
     receipt: {
-      fields { assessment: ref<parent>, payment: ref<on.payment>, amount: money? }
+      fields { cashReceipt: text?, assessment: ref<parent>, payment: ref<on.payment>, amount: money? }
       lifecycle { states: [paid, refunded], initial: paid }
-      action create { allowZero: true, calculate: [{ target: amount, op: minimum, values: [{ field: self.payment.held.balance }, { field: self.assessment.receivable.balance }] }], actor: { parent: parent }, input { assessment: ref<parent>, payment: ref<on.payment> }, requires input.payment.plan == self.assessment.plan; requires unique "fine_receipt" on [self.assessment, self.payment]; moves self.amount from self.payment.held to fines_to; moves self.amount from self.assessment.receivable to self.assessment.debt }
-      action refund { allowZero: true, from: paid, to: refunded, actor: { parent: parent }, moves self.amount from fines_to to self.payment.plan.borrower; moves self.amount from self.assessment.debt to self.assessment.receivable }
+      action create { allowZero: true, calculate: [{ target: amount, op: minimum, values: [{ field: self.payment.held.balance }, { field: self.assessment.receivable.balance }] }], actor: { parent: parent }, input { assessment: ref<parent>, payment: ref<on.payment> }, requires input.payment.plan == self.assessment.plan; requires unique "fine_receipt" on [self.assessment, self.payment]; moves self.amount from self.payment.held to fines_to capture "cashReceipt" economics { recipient: fines_to, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: participant_payout, sourceParty: programOperator } }; moves self.amount from self.assessment.receivable to self.assessment.debt economics { purpose: internal, sourceParty: programOperator } }
+      action refund { allowZero: true, from: paid, to: refunded, actor: { parent: parent }, moves self.amount from fines_to to self.payment.plan.borrower economics { recipient: fines_to, company: { purpose: earning, sourceParty: fines_to, reversalOf: self.cashReceipt }, participant: unclassified }; moves self.amount from self.assessment.debt to self.assessment.receivable economics { purpose: internal, sourceParty: borrower } }
     }
 
     cost: {
@@ -563,7 +568,7 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
       action assess { allowZero: true,
         from: proposed, to: assessed, actor: clock, due: { at: self.assessment.overdueAt }
         requires self.assessment.slice.principalReceivable.balance > "0"
-        moves self.amount from self.debt to self.receivable
+        moves self.amount from self.debt to self.receivable economics { purpose: internal, sourceParty: borrower }
       }
       action collect {
         from: [assessed, collected], to: assessed, actor: { parent: child(on, slice) }, input { payment: ref<on.payment> }
@@ -574,8 +579,8 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
       action payoff { allowZero: true,
         from: [assessed, collected], to: collected, actor: { parent: on }
         requires self.plan in [paid]
-        moves self.receivable.balance from self.plan.borrower to costs_to
-        moves self.receivable.balance from self.receivable to self.debt
+        moves self.receivable.balance from self.plan.borrower to costs_to economics { recipient: costs_to, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: pass_through, sourceParty: borrower } }
+        moves self.receivable.balance from self.receivable to self.debt economics { purpose: internal, sourceParty: programOperator }
       }
       action finish { from: assessed, to: collected, actor: { parent: current() }, requires self.receivable.balance == "0" }
       action cancel { from: proposed, to: waived }
@@ -584,7 +589,7 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
         requires input.amendment.plan == self.plan; requires input.amendment in [applied]
         invoke: [{ instrument: waiver, action: create, input: { assessment: { field: self.id }, amendment: { field: input.amendment } } }]
       }
-      action waive { allowZero: true, from: [assessed, collected], to: waived, actor: { parent: waiver_request }, input { reason: text, evidence: text }, moves self.receivable.balance from self.receivable to self.debt }
+      action waive { allowZero: true, from: [assessed, collected], to: waived, actor: { parent: waiver_request }, input { reason: text, evidence: text }, moves self.receivable.balance from self.receivable to self.debt economics { purpose: internal, sourceParty: programOperator } }
       action refund {
         from: [assessed, collected], to: assessed, actor: { party: costs_to }, input { payment: ref<on.payment> }
         requires input.payment in [paid, refunded]
@@ -609,14 +614,14 @@ instrument late_charge(on: ref<financing.installments>[], grace: duration = 3d,
             actor: { parent: parent }, input { assessment: ref<parent>, amendment: ref<on.amendment> }
             calculate: [{ target: amount, op: rate, base: { field: self.assessment.receivable.balance }, bps: { field: self.amendment.waiverPercent }, rounding: floor }]
             requires unique "amendment_waiver" on [self.assessment, self.amendment]
-            moves self.amount from self.assessment.receivable to self.assessment.debt
+            moves self.amount from self.assessment.receivable to self.assessment.debt economics { purpose: internal, sourceParty: programOperator }
           }
         }
         receipt: {
-          fields { assessment: ref<parent>, payment: ref<on.payment>, amount: money? }
+          fields { cashReceipt: text?, assessment: ref<parent>, payment: ref<on.payment>, amount: money? }
           lifecycle { states: [paid, refunded], initial: paid }
-          action create { allowZero: true, calculate: [{ target: amount, op: minimum, values: [{ field: self.payment.held.balance }, { field: self.assessment.receivable.balance }] }], actor: { parent: parent }, input { assessment: ref<parent>, payment: ref<on.payment> }, requires input.payment.plan == self.assessment.plan; requires unique "cost_receipt" on [self.assessment, self.payment]; moves self.amount from self.payment.held to costs_to; moves self.amount from self.assessment.receivable to self.assessment.debt }
-          action refund { allowZero: true, from: paid, to: refunded, actor: { parent: parent }, moves self.amount from costs_to to self.payment.plan.borrower; moves self.amount from self.assessment.debt to self.assessment.receivable }
+          action create { allowZero: true, calculate: [{ target: amount, op: minimum, values: [{ field: self.payment.held.balance }, { field: self.assessment.receivable.balance }] }], actor: { parent: parent }, input { assessment: ref<parent>, payment: ref<on.payment> }, requires input.payment.plan == self.assessment.plan; requires unique "cost_receipt" on [self.assessment, self.payment]; moves self.amount from self.payment.held to costs_to capture "cashReceipt" economics { recipient: costs_to, company: { purpose: earning, sourceParty: borrower }, participant: { purpose: participant_payout, sourceParty: programOperator } }; moves self.amount from self.assessment.receivable to self.assessment.debt economics { purpose: internal, sourceParty: programOperator } }
+          action refund { allowZero: true, from: paid, to: refunded, actor: { parent: parent }, moves self.amount from costs_to to self.payment.plan.borrower economics { recipient: costs_to, company: { purpose: earning, sourceParty: costs_to, reversalOf: self.cashReceipt }, participant: unclassified }; moves self.amount from self.assessment.debt to self.assessment.receivable economics { purpose: internal, sourceParty: borrower } }
         }
       }
     }

package/std/insurance.hsx

@@ -1,5 +1,9 @@
 header insurance
 
+// Economics: Company commission is earning; refunds reverse its captured transfer.
+// Outside broker commissions are pass-through. Adapter-owned premium and claim
+// accounts lack an authored source party, so their moves remain unclassified.
+
 // 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
@@ -39,7 +43,7 @@ instrument cover(holder: party, adapter: text, commission: percent = 0%, broker:
       fields {
         cover: ref<parent>, covers: ref<covers>, premium: money = premium, startsAt: date, endsAt: date
         commission: money = rate(self.premium, commission)
-        insurerPremium: money = subtract(self.premium, self.commission)
+        insurerPremium: money = subtract(self.premium, self.commission), commissionReceipt: text?
       }
       lifecycle { states: [pending, paid, active, expired, refunded], initial: pending }
       action create {
@@ -53,7 +57,7 @@ instrument cover(holder: party, adapter: text, commission: percent = 0%, broker:
         from: pending, to: paid, actor: { party: holder }
         requires self.cover in [active]
         moves self.insurerPremium from holder to self.cover.insurer
-        moves self.commission from holder to broker
+        moves self.commission from holder to broker capture "commissionReceipt" economics { recipient: broker, company: { purpose: earning, sourceParty: holder }, participant: { purpose: pass_through, sourceParty: holder } }
       }
       action start { from: paid, to: active, actor: clock, due: { at: self.startsAt } }
       action expire { from: active, to: expired, actor: clock, due: { at: self.endsAt } }
@@ -62,7 +66,7 @@ instrument cover(holder: party, adapter: text, commission: percent = 0%, broker:
         requires self.premium > "0"
         from: paid, to: refunded, actor: { parent: parent }, deadline: { at: self.startsAt }
         moves self.insurerPremium from self.cover.insurer to holder
-        moves self.commission from broker to holder
+        moves self.commission from broker to holder economics { recipient: broker, company: { purpose: earning, sourceParty: broker, reversalOf: self.commissionReceipt }, participant: { purpose: pass_through, sourceParty: broker } }
       }
     }
   }

package/std/lending.hsx

@@ -1,5 +1,9 @@
 header lending
 
+// Economics: Funding and commitment returns are principal. Distribution tax is
+// pass-through; own-account fee and claim allocations are internal. Mixed
+// principal/profit distributions and unbound source owners remain unclassified.
+
 // 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
@@ -31,7 +35,7 @@ instrument round(borrower: party, plan: ref<financing.installments> = object(fin
     from: open, to: funded, actor: { party: operator }
     requires sum "amount" of { instrument: commitments, reference: "round", anchor: self.id, states: [committed], limit: 366 } == self.price
     requires self.held.balance == self.price
-    moves self.price from self.held to self.plan.capital
+    moves self.price from self.held to self.plan.capital economics { purpose: principal, sourceParty: programOperator }
     invoke: [{ selection: { instrument: commitments, reference: "round", anchor: self.id, states: [committed], limit: 366 }, action: fund, input: {} }]
   }
   action fail {
@@ -54,18 +58,18 @@ instrument commitment(round: ref<lending.round>, wallet: ref<wallet.balance>, in
     requires self.wallet.holder == self.investor
     requires self.amount >= self.round.minimumTicket
     deadline: { at: self.round.closesAt }
-    moves self.amount from self.wallet.held to self.round.held
+    moves self.amount from self.wallet.held to self.round.held economics { purpose: principal, sourceParty: programOperator }
   }
   action fund { from: committed, to: funded, actor: { parent: round } }
   action withdraw {
     from: committed, to: withdrawn, actor: { party: investor }
     requires self.round in [open]
     deadline: { at: self.round.closesAt }
-    moves self.amount from self.round.held to self.wallet.held
+    moves self.amount from self.round.held to self.wallet.held economics { purpose: principal, sourceParty: programOperator }
   }
   action refund {
     from: committed, to: refunded, actor: { parent: round }
-    moves self.amount from self.round.held to self.wallet.held
+    moves self.amount from self.round.held to self.wallet.held economics { purpose: principal, sourceParty: programOperator }
   }
 }
 
@@ -98,7 +102,7 @@ instrument distribution(round: ref<lending.round>, receipt: ref, commitments: re
   action distribute_cash { allowZero: true,
     from: cash_ready, to: distributed, actor: { party: operator }
     requires sum "weight" of { instrument: share, reference: "distribution", anchor: self.id, states: [pending], limit: 366 } == self.round.price
-    moves self.principal from self.source.capital to self.held; moves self.profit from self.source.profitIncome to self.held; moves self.charge from self.held to programOperator; moves self.vat from self.held to programTax
+    moves self.principal from self.source.capital to self.held; moves self.profit from self.source.profitIncome to self.held; moves self.charge from self.held to programOperator economics { purpose: internal, sourceParty: programOperator }; moves self.vat from self.held to programTax economics { purpose: pass_through, sourceParty: programOperator }
     invoke: [{ selection: { instrument: share, reference: "distribution", anchor: self.id, states: [pending], limit: 366 }, action: cash, input: {} }, { reference: self.id, action: residual_cash, input: {} }]
   }
   action residual_cash { allowZero: true,
@@ -113,7 +117,7 @@ instrument distribution(round: ref<lending.round>, receipt: ref, commitments: re
   }
   action residual_loss { allowZero: true,
     from: distributed, to: distributed, actor: { parent: current() }
-    moves self.losses.balance from self.losses to self.residualLoss
+    moves self.losses.balance from self.losses to self.residualLoss economics { purpose: internal, sourceParty: programOperator }
   }
   records {
     share: {
@@ -128,7 +132,7 @@ instrument distribution(round: ref<lending.round>, receipt: ref, commitments: re
         from: pending, to: paid, actor: { parent: parent }
         moves self.gross from self.distribution.held to self.commitment.wallet.held
       }
-      action loss { allowZero: true, from: pending, to: paid, actor: { parent: parent }, moves self.gross from self.distribution.losses to self.commitment.loss }
+      action loss { allowZero: true, from: pending, to: paid, actor: { parent: parent }, moves self.gross from self.distribution.losses to self.commitment.loss economics { purpose: internal, sourceParty: programOperator } }
     }
   }
 }

package/std/marketplace.hsx

@@ -1,5 +1,8 @@
 header marketplace
 
+// Economics: Deposit funding, escrow credit and returns are principal. Retention is
+// earning for the company or a payout to a bound outside recipient.
+
 // 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,
@@ -77,7 +80,7 @@ instrument reservation(listing: ref<marketplace.listing>, funds: ref<escrow.hold
     calculate: [{ target: expiresAt, op: shift, date: { field: self.now }, milliseconds: { literal: expires_after }, direction: after }]
     requires self.listing in [active]; requires self.price == self.listing.price
     requires count of { instrument: all(marketplace.order), reference: "listing", anchor: self.listing, states: [placed, fulfilled], limit: 366 } == 0
-    moves self.deposit from self.buyer to self.held
+    moves self.deposit from self.buyer to self.held economics { purpose: principal, sourceParty: buyer }
   }
   action convert_financed {
     from: active, to: active, actor: { party: buyer }, deadline: { at: self.expiresAt }
@@ -96,31 +99,31 @@ instrument reservation(listing: ref<marketplace.listing>, funds: ref<escrow.hold
     requires input.contribution <= self.price
     calculate: [{ target: credit, op: minimum, values: [{ field: self.held.balance }, { field: input.contribution }] }, { target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.credit }] }]
     set: { dispositionAt: { field: self.now } }
-    moves self.credit from self.held to input.funds.held
-    moves self.refund from self.held to self.buyer
+    moves self.credit from self.held to input.funds.held economics { purpose: principal, sourceParty: programOperator }
+    moves self.refund from self.held to self.buyer economics { purpose: principal, sourceParty: programOperator }
   }
   action cancel { allowZero: true,
     from: active, to: cancelled, actor: { party: buyer }, input { reason: text }
     calculate: [{ target: refund, op: rate, base: { field: self.held.balance }, bps: { literal: cancellation_refund }, rounding: floor }, { target: retained, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.refund }] }]
     set: { reason: { field: input.reason }, dispositionAt: { field: self.now } }
-    moves self.refund from self.held to self.buyer; moves self.retained from self.held to retained_to
+    moves self.refund from self.held to self.buyer economics { purpose: principal, sourceParty: programOperator }; moves self.retained from self.held to retained_to economics { recipient: retained_to, company: { purpose: earning, sourceParty: buyer }, participant: { purpose: participant_payout, sourceParty: programOperator } }
   }
   action seller_cancel {
     from: active, to: cancelled, actor: { party: seller }, input { reason: text }
     set: { reason: { field: input.reason }, dispositionAt: { field: self.now } }
-    moves self.held.balance from self.held to self.buyer
+    moves self.held.balance from self.held to self.buyer economics { purpose: principal, sourceParty: programOperator }
   }
   action operator_cancel {
     from: active, to: cancelled, actor: { party: operator }, input { reason: text }
     set: { reason: { field: input.reason }, dispositionAt: { field: self.now } }
-    moves self.held.balance from self.held to self.buyer
+    moves self.held.balance from self.held to self.buyer economics { purpose: principal, sourceParty: programOperator }
   }
   action withdraw { from: proposed, to: cancelled, actor: { party: buyer } }
   action expire { allowZero: true,
     from: active, to: expired, actor: clock, due: { at: self.expiresAt }
     calculate: [{ target: refund, op: rate, base: { field: self.held.balance }, bps: { literal: expiry_refund }, rounding: floor }, { target: retained, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.refund }] }]
     set: { dispositionAt: { field: self.now } }
-    moves self.refund from self.held to self.buyer; moves self.retained from self.held to retained_to
+    moves self.refund from self.held to self.buyer economics { purpose: principal, sourceParty: programOperator }; moves self.retained from self.held to retained_to economics { recipient: retained_to, company: { purpose: earning, sourceParty: buyer }, participant: { purpose: participant_payout, sourceParty: programOperator } }
   }
   action expire_proposal { from: proposed, to: expired, actor: clock, due: { at: self.proposalExpiresAt } }
 }

package/std/money.hsx

@@ -1,5 +1,9 @@
 header money
 
+// Economics: Held funding and returns are principal. Release to the company realizes
+// earnings; release to another participant is a payout. Generic transfers, splits,
+// schedules, swaps, boundary payouts and metered fees retain no assumed purpose.
+
 // 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.
@@ -36,7 +40,7 @@ instrument hold(payer: party, payee: party, amount: money = runtime) {
   action create { }
   action fund {
     from: pending, to: funded, actor: { party: payer }
-    moves self.amount from payer to self.held
+    moves self.amount from payer to self.held economics { purpose: principal, sourceParty: payer }
   }
   action confirm {
     from: pending, to: funded
@@ -44,11 +48,11 @@ instrument hold(payer: party, payee: party, amount: money = runtime) {
   }
   action release {
     from: funded, to: released, actor: { party: payer }
-    moves self.amount from self.held to payee
+    moves self.amount from self.held to payee economics { recipient: payee, company: { purpose: earning, sourceParty: payer }, participant: { purpose: participant_payout, sourceParty: programOperator } }
   }
   action refund {
     from: funded, to: refunded, actor: { party: payee }
-    moves self.amount from self.held to payer
+    moves self.amount from self.held to payer economics { purpose: principal, sourceParty: programOperator }
   }
   action cancel { from: pending, to: cancelled }
 }
@@ -103,7 +107,7 @@ instrument pool(payer: party, payee: party, target: money, closes: date) {
   action pay {
     from: open, to: paid, actor: { party: payee }
     requires self.held.balance == self.target
-    moves self.target from self.held to payee
+    moves self.target from self.held to payee economics { recipient: payee, company: { purpose: earning, sourceParty: payer }, participant: { purpose: participant_payout, sourceParty: programOperator } }
   }
   action fail {
     from: open, to: failed, actor: clock, due: { at: self.closesAt }
@@ -116,8 +120,8 @@ instrument pool(payer: party, payee: party, target: money, closes: date) {
       lifecycle { states: [pending, paid, refunded], initial: pending }
       invariants count of { instrument: current(), reference: "pool", anchor: self.pool, states: [paid], limit: 366 } <= 366
       action create { requires self.pool in [open] }
-      action pay { from: pending, to: paid, actor: { party: payer }, deadline: { at: self.pool.closesAt }, requires self.pool in [open], calculate: [{ target: remaining, op: subtract, base: { field: self.pool.target }, subtract: [{ field: self.pool.held.balance }] }], requires self.amount <= self.remaining, moves self.amount from self.payer to self.pool.held }
-      action refund { from: paid, to: refunded, actor: { parent: parent }, moves self.amount from self.pool.held to self.payer }
+      action pay { from: pending, to: paid, actor: { party: payer }, deadline: { at: self.pool.closesAt }, requires self.pool in [open], calculate: [{ target: remaining, op: subtract, base: { field: self.pool.target }, subtract: [{ field: self.pool.held.balance }] }], requires self.amount <= self.remaining, moves self.amount from self.payer to self.pool.held economics { purpose: principal, sourceParty: payer } }
+      action refund { from: paid, to: refunded, actor: { parent: parent }, moves self.amount from self.pool.held to self.payer economics { purpose: principal, sourceParty: programOperator } }
     }
   }
 }

package/std/savings.hsx

@@ -1,5 +1,7 @@
 header savings
 
+// Economics: Contributions and returned pots are principal, not company earnings.
+
 // 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.
@@ -52,7 +54,7 @@ instrument membership(circle: ref<savings.circle>, member: party) {
     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: [received], limit: 60 } == self.preceding
-    moves self.total from self.circle.held to self.member
+    moves self.total from self.circle.held to self.member economics { purpose: principal, sourceParty: programOperator }
   }
   action withdraw { from: joined, to: withdrawn, requires self.circle in [disbanded] }
   records {
@@ -60,7 +62,7 @@ instrument membership(circle: ref<savings.circle>, member: party) {
       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.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 }
+      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 economics { purpose: principal, sourceParty: member } }
     }
   }
 }