@hyperscale0/hsx 1.0.124 → 1.0.128

package/dist/src/std-bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"std-bundle.js","sourceRoot":"","sources":["../../src/std-bundle.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAiB;IACpF,CAAC,WAAW,EAAE,2oKAA2oK,CAAC;IAC1pK,CAAC,iBAAiB,EAAE,2sNAA2sN,CAAC;IAChuN,CAAC,YAAY,EAAE,+qHAA+qH,CAAC;IAC/rH,CAAC,eAAe,EAAE,6m+DAA6m+D,CAAC;IACho+D,CAAC,eAAe,EAAE,01KAA01K,CAAC;IAC72K,CAAC,aAAa,EAAE,qwTAAqwT,CAAC;IACtxT,CAAC,iBAAiB,EAAE,woTAAwoT,CAAC;IAC7pT,CAAC,WAAW,EAAE,u1VAAu1V,CAAC;IACt2V,CAAC,eAAe,EAAE,+q2BAA+q2B,CAAC;IACls2B,CAAC,aAAa,EAAE,85JAA85J,CAAC;IAC/6J,CAAC,YAAY,EAAE,2jGAA2jG,CAAC;CAC5kG,CAAC,CAAC"}
+{"version":3,"file":"std-bundle.js","sourceRoot":"","sources":["../../src/std-bundle.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAiB;IACpF,CAAC,aAAa,EAAE,soLAAsoL,CAAC;IACvpL,CAAC,WAAW,EAAE,2oKAA2oK,CAAC;IAC1pK,CAAC,iBAAiB,EAAE,2sNAA2sN,CAAC;IAChuN,CAAC,YAAY,EAAE,i9JAAi9J,CAAC;IACj+J,CAAC,eAAe,EAAE,uzpEAAuzpE,CAAC;IAC10pE,CAAC,eAAe,EAAE,uxLAAuxL,CAAC;IAC1yL,CAAC,aAAa,EAAE,qwTAAqwT,CAAC;IACtxT,CAAC,iBAAiB,EAAE,mpTAAmpT,CAAC;IACxqT,CAAC,WAAW,EAAE,+1VAA+1V,CAAC;IAC92V,CAAC,eAAe,EAAE,+q2BAA+q2B,CAAC;IACls2B,CAAC,aAAa,EAAE,85JAA85J,CAAC;IAC/6J,CAAC,YAAY,EAAE,kyHAAkyH,CAAC;CACnzH,CAAC,CAAC"}

package/docs/README.md

@@ -82,11 +82,16 @@ the executor's current time when the action runs, not a caller-supplied return d
 A late `due` permits the operator action; it does not schedule that action.
 
 This sample binds a declared business named `renter` in Product configuration.
-It uses fixed parties because this compiler rejects parameterized instruments
-inside a program. Changing the renter binding is a Build configuration decision,
-not a different party ID on each request. Use header party parameters bound to
-`owner` or `actor` for per-object participants. Reusable custom headers require a
-host-supplied `StandardLibrary`; `use` cannot load a local file through this CLI.
+The renter is one business for the whole Build, so the instrument takes no
+parameters. Changing the renter binding is a Build configuration decision, not a
+different party ID on each request. For per-object participants, give a program
+instrument parameters as a header would, such as `instrument purse(holder: party)`,
+and bind `holder: owner` or `holder: actor` in each `attach` block. A
+parameterized program instrument exists only through its attachments. A `fee` on
+a move of an action input, such as `moves input.amount from holder to self.held
+fee { seller: 1% }`, is calculated when that action runs. Reusable custom headers
+require a host-supplied `StandardLibrary`; `use` cannot load a local file through
+this CLI.
 
 Inspect `objects` in the compiled UDL for the attachment and public names, then
 its instrument for fields, transitions, actors, requirements and ordered moves.
@@ -104,11 +109,15 @@ executor. Compilation cannot establish balances, permissions or provider readine
 
 Every attached party parameter binds to `owner`, `actor`, `operator`, a declared
 business, or a declared staff party with a supported role. Configure declared
-business participants per Build. Declared person parties cannot bind attachments.
+business participants per Build. The host binds a declared business to an
+organization customer that holds one open balance account in the Product, so the
+Product exists before the binding and a recomposition adds it. Declared person
+parties cannot bind attachments.
 `owner` is the object's resolved customer or business, `actor` is the authenticated
 caller, and `operator` is the program operator. A parameter with one of these
-names binds by name. Other party parameters use a same-named eligible declaration,
-a header default, or an explicit binding. Explicit bindings take precedence.
+names binds by name. Other required party parameters use a same-named eligible
+declaration, a header default, or an explicit binding. An optional party parameter
+stays unset unless the attachment binds it. Explicit bindings take precedence.
 Unbound parameters report `subject_party_unbound`. These bindings are frozen in
 UDL `objects[].attachments[].parties`; no caller supplies party IDs at creation.
 
@@ -156,6 +165,8 @@ decimal places and percentages at most two. The compiler uses integer minor unit
 and basis points. Fee and tax calculations round down. Split percentages sum to
 100%; the last declared recipient receives the rounding remainder. Finite
 schedules use positions 1 through n and put the division remainder in position 1.
+Amortizing financing is the exception: it rounds half up and puts the remainder in
+the last instalment, as a standard amortization table does.
 Tax binds `programTax`. Fees default to `programOperator`. Fine, recovery and
 residual destinations are party tunables.
 
@@ -261,20 +272,30 @@ and a correction. No artifact is returned with diagnostics.
 
 ## Financing policies
 
-`financing.installments` keeps principal and fixed flat profit as claims from
-activation. The company chooses where funding goes and when profit becomes earned.
-All choices use accounts, calculations and moves in the same two books.
-
-| Tunable                            | Default                  | Selected behavior                                                                                                                                                                                                                                                                                                                                                                |
-| ---------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `disburse_to`                      | `funds`                  | `funds` pays down payment and principal into the hold and confirms it. `borrower` credits principal to the borrower's balance.                                                                                                                                                                                                                                                   |
-| `profit_earned`                    | `on_payment`             | `on_payment` collects unearned profit on payment. `by_schedule` moves unearned claims to earned claims at each slice's date. `at_disbursement` makes that move at activation. Cash arrives only on payment.                                                                                                                                                                      |
-| `apply`                            | `fines_profit_principal` | Visit each slice in position order; within that slice collect assessed fines by overdue date, evidenced costs, profit, then principal. `principal_profit` collects each slice in position order, principal before profit. `pro_rata` uses the slice's fixed principal:profit ratio, caps each side by its collectible balance, and assigns the remainder without stranding cash. |
-| `payoff_rebate`                    | `100%`                   | Reverse this share of unearned profit to borrower debt. Collect the remainder and all earned profit with outstanding principal.                                                                                                                                                                                                                                                  |
-| `late_charge.fines_to`             | `programOperator`        | Receive fine cash and fund its refunds.                                                                                                                                                                                                                                                                                                                                          |
-| `late_charge.costs_to`             | `programOperator`        | Receive evidenced recovery cash and fund its refunds.                                                                                                                                                                                                                                                                                                                            |
-| `collections.case.fee`             | `20%`                    | After payment succeeds, transfer this share of the payment amount from plan capital to the agency.                                                                                                                                                                                                                                                                               |
-| `lending.distribution.residual_to` | `programOperator`        | Receive the cash remainder and own the claim loss remainder after weighted distribution.                                                                                                                                                                                                                                                                                         |
+`financing.installments` keeps principal and fixed profit as claims from
+activation. The company chooses how profit is priced, where funding goes and when
+profit becomes earned. All choices use accounts, calculations and moves in the same
+two books.
+
+`pricing` has no default, so every plan states it. `amortizing` reads
+`profit_rate` as an annual rate on the declining balance: equal monthly
+instalments from standard annuity maths, interest and instalment rounded half up,
+the last instalment absorbing the rounding. 12,000 SAR at 18% over 12 months is
+11 instalments of 1,100.16 SAR and a last one of 1,100.19 SAR, 13,201.95 SAR in
+total. `flat_total` reads `profit_rate` as one charge on principal for the whole
+term, rounded down and split evenly with the remainder in position 1: murabaha and
+fixed-fee pay-later. The same 12,000 SAR at 18% `flat_total` costs 14,160 SAR.
+
+| Tunable                            | Default                  | Selected behavior                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disburse_to`                      | `funds`                  | `funds` pays down payment and principal into the hold and confirms it. `borrower` credits principal to the borrower's balance. `seller` pays principal to the `seller` party at activation; after capital refunds every paid payment, capital's `unwind` debits it back from the seller and cancels open slices.                                                                                                                   |
+| `profit_earned`                    | `on_payment`             | `on_payment` collects unearned profit on payment. `by_schedule` moves unearned claims to earned claims at each slice's date. `at_disbursement` makes that move at activation. Cash arrives only on payment.                                                                                                                                                                                                                        |
+| `apply`                            | `fines_profit_principal` | Visit each slice in position order; within that slice collect assessed fines by overdue date, evidenced costs, profit, then principal. `principal_profit` collects each slice in position order, principal before profit. `pro_rata` uses the slice's fixed principal:profit ratio (its own principal and profit under `amortizing`), caps each side by its collectible balance, and assigns the remainder without stranding cash. |
+| `payoff_rebate`                    | `100%`                   | Reverse this share of unearned profit to borrower debt. Collect the remainder and all earned profit with outstanding principal.                                                                                                                                                                                                                                                                                                    |
+| `late_charge.fines_to`             | `programOperator`        | Receive fine cash and fund its refunds.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `late_charge.costs_to`             | `programOperator`        | Receive evidenced recovery cash and fund its refunds.                                                                                                                                                                                                                                                                                                                                                                              |
+| `collections.case.fee`             | `20%`                    | After payment succeeds, transfer this share of the payment amount from plan capital to the agency.                                                                                                                                                                                                                                                                                                                                 |
+| `lending.distribution.residual_to` | `programOperator`        | Receive the cash remainder and own the claim loss remainder after weighted distribution.                                                                                                                                                                                                                                                                                                                                           |
 
 Each slice owns separate unearned and earned claim accounts. Scheduled recognition
 uses a dated child record so a partial payment cannot disable the maturity clock.
@@ -362,9 +383,9 @@ The compiler API is `compile(source)`. On success, `result.verdict` is `valid`
 and `result.artifacts` contains `document`, `costManifest` and `originMap`.
 On refusal, inspect `result.diagnostics`; no artifact is returned.
 
-`hsx headers` prints the instrument inventory from the declarations. The
+`hsx headers --json` prints the instrument inventory from the declarations. The
 [object example](../examples/library.hsx) shows authenticated role bindings.
-The [playground](../playground/index.html) compiles locally in the browser.
+The [playground](https://hyperscale0.ai/playground/) compiles locally in the browser.
 
 ## Standard-library behavior
 
@@ -372,18 +393,21 @@ Read the instrument's states, time gates and moves before promising a money
 outcome. A compiler pass does not prove that required actions are exposed,
 adapters are bound, participants have funds, or the flow can finish.
 
-| Instrument                                 | Behavior                                                                                                                                                                                                         |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `financing.installments`                   | `share` allocates collected profit to a cash payable owned by `capital`. It does not itself pay operator income.                                                                                                 |
-| `financing.limits`                         | `per_borrower` caps outstanding principal. Both borrower and portfolio limits must be approved before disbursement; attaching them does not approve them.                                                        |
-| `lending.round`                            | The target is the linked plan's principal. Closing requires commitments and held funds to equal that amount.                                                                                                     |
-| `lending.distribution`                     | Cash distribution needs an eligible recorded settlement, `prepare_cash`, one share record per funded commitment, then `distribute_cash`. Attaching it moves nothing.                                             |
-| `insurance.cover.slice`                    | `collect` credits premium net of commission to the insurer account. The tenant retains commission. `refund` returns both portions; claims reserve insurer funds. External settlement uses the boundary protocol. |
-| `financing.installments`, `savings.circle` | Supply explicit date lists when creating agreements. A term count does not generate a monthly calendar. Savings supports at most 60 distinct member seats.                                                       |
-| `escrow.hold`                              | `fund` takes the whole price. Financing into pending escrow collects the remaining down payment and adds capital principal at disbursement; `fund` is not a down-payment checkout.                               |
-| `escrow.hold`                              | Acceptance timeout enters `disputed` without paying the seller. Delivery and return verification belong to `payee`; rebinding it also changes who receives accepted funds.                                       |
-| `financing.late_charge`                    | `fine` is a fixed money amount, not a percentage of overdue principal.                                                                                                                                           |
-| `cards.card`                               | `spend_limit` is a per-authorization ceiling, not a monthly aggregate.                                                                                                                                           |
+| Instrument                                 | Behavior                                                                                                                                                                                                                                                               |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `financing.installments`                   | `share` allocates collected profit to a cash payable owned by `capital`. It does not itself pay operator income.                                                                                                                                                       |
+| `financing.limits`                         | `per_borrower` caps outstanding principal. Both borrower and portfolio limits must be approved before disbursement; attaching them does not approve them.                                                                                                              |
+| `lending.round`                            | The target is the linked plan's principal. Closing requires commitments and held funds to equal that amount.                                                                                                                                                           |
+| `lending.distribution`                     | Cash distribution needs an eligible recorded settlement, `prepare_cash`, one share record per funded commitment, then `distribute_cash`. Attaching it moves nothing.                                                                                                   |
+| `insurance.cover.slice`                    | `collect` credits premium net of commission to the insurer account. The tenant retains commission. `refund` returns both portions; claims reserve insurer funds. External settlement uses the boundary protocol.                                                       |
+| `financing.installments`, `savings.circle` | Supply explicit date lists when creating agreements. A term count does not generate a monthly calendar. Savings supports at most 60 distinct member seats.                                                                                                             |
+| `escrow.hold`                              | `fund` takes the whole price. Financing into pending escrow collects the remaining down payment and adds capital principal at disbursement; `fund` is not a down-payment checkout.                                                                                     |
+| `escrow.hold`                              | Acceptance timeout enters `disputed` without paying the seller. Delivery and return verification belong to `payee`; rebinding it also changes who receives accepted funds.                                                                                             |
+| `escrow.hold`                              | `deliver_within` (default `14d`) starts at funding. After it passes without delivery, an exposed `refund_undelivered` lets the payer take the whole held price back. Nothing runs it automatically.                                                                    |
+| `wallet.balance`                           | `topup_fee` (default `0%`) takes a floored percentage of each top-up for the Company. At `1%`, a 100.00 top-up credits 99.00 and earns 1.00.                                                                                                                           |
+| `booking.reservation`                      | The balance is payable only from `deposit_paid`, so a cancelled booking never takes it. `middle_forfeit` and `late_forfeit` default to `0%`, so every cancellation returns all held money until the author sets them. The clock completes a paid booking at departure. |
+| `financing.late_charge`                    | `fine` is a fixed money amount, not a percentage of overdue principal.                                                                                                                                                                                                 |
+| `cards.card`                               | `spend_limit` is a per-authorization ceiling, not a monthly aggregate.                                                                                                                                                                                                 |
 
 A seller-owned marketplace object can declare `entryActions: [create_order]`
 when `create_order` exposes an attachment's create action with its buyer bound
@@ -441,8 +465,9 @@ has no checkout collection action. The plan and escrow must agree on payer and
 price.
 
 Expose escrow `cancel` to return money credited before full funding. Plan `void`
-cancels the signed financing agreement but does not cancel its escrow. After
-funding and delivery, the default return path needs three separate aliases for
+cancels the signed financing agreement but does not cancel its escrow. Between
+funding and delivery, the payee's `refund` returns the full price. After
+delivery, the default return path needs three separate aliases for
 `dispute`, `verify_return` and `refund`. The payee supplies return evidence and
 returns the full price to the payer. `accept` pays the payee instead.
 Marketplace order fulfillment alone does not execute any of these money actions.
@@ -458,7 +483,10 @@ Bind `insurance.cover.broker` to the agency that receives commission. Collection
 pays the insurer's net premium and the broker's commission as two moves. Refunds
 reverse those same portions. The default broker is the program operator.
 `claim.deny` accepts only `submitted`; after approval, `pay` or expiry consumes
-the reservation.
+the reservation. `claim_limit` is the sum insured, supplied per cover at creation:
+approved and paid claims on one cover never total more. `adapter` names a
+registered boundary adapter, `conformance_boundary` in sandbox. `covers` is
+optional; the attached object is already the insured thing.
 
 A booking cancellation refunds only its own held cash. Expose `cover.cancel`
 separately for eligible premium refunds before the paid period starts. Active
@@ -497,8 +525,9 @@ instruments stay generic. New Builds carry the purpose; existing agreements
 and postings keep their retained Build and classification.
 
 Held customer funding and its unspent return are `principal`. A release for the
-company's sale is `earning`. A payment from company cash to another participant
-is `participant_payout`. Claims, waivers, write-offs and own-account allocations
+company's sale is `earning`; its release to another participant is
+`pass_through`, because the company never owned it. A payment from company cash
+to another participant is `participant_payout`. Claims, waivers, write-offs and own-account allocations
 are `internal`; prepaid balance topups and returns are `prepaid_credit`. Tax is
 `pass_through`, excluded from earnings and costs. Unpaid claims count as neither.
 Refunds of paid profit, company charges and commission capture the original
@@ -511,16 +540,14 @@ product fees. Automatic platform fees keep their commercial classification.
 
 A move's economics block can select by a resolved party: `economics { recipient:
 recipient, company: { purpose: earning, sourceParty: payer }, participant:
-{ purpose: participant_payout, sourceParty: programOperator } }`. The compiler
+{ purpose: pass_through, sourceParty: programOperator } }`. The compiler
 chooses `company` for `operator`, `programOperator`, or a declared party with the
 `program_operator` role; it chooses `participant` for other bound parties.
 Both branches must be supplied. A branch may be `unclassified` when no purpose
 is established. Outside financing-profit and recovery recipients refund directly
-to the customer, not the company that funded the payout; those refund branches
-remain unclassified because they cannot reverse that company payout. Std
-recovery charges use this rule to avoid counting company receipts as participant
-costs. Direct customer payments to
-outside recipients are pass-through; payments from held company cash are costs.
+to the customer; those refund branches remain unclassified. Customer cash paid to
+outside recipients is pass-through, whether paid direct or released from a hold
+the customer funded as principal. Only company-owned cash paid out is a cost.
 
 Generic transfers and mixed principal/profit distributions remain unclassified
 when their structure does not establish a purpose. Adapter-owned premium and

package/examples/collections.hsx

@@ -12,7 +12,7 @@ object facility "Business loan" {
   attach loan = financing.installments {
     expose create as create_loan
     borrower: owner, capital: operator
-    months: 12, profit: 6%, disburse_to: borrower
+    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
     expose sign as sign_loan
     expose disburse as release_loan

package/examples/financing.hsx

@@ -18,7 +18,7 @@ object enrolment "Enrolment" {
   attach tuition = financing.installments {
     expose create as create_tuition
     borrower: owner, capital: operator
-    months: 3, profit: 0%, disburse_to: borrower
+    months: 3, pricing: flat_total, profit_rate: 0%, disburse_to: borrower
     limits: allowance, portfolio: budget
     expose sign as sign_tuition_plan
     expose disburse as fund_tuition

package/examples/insurance.hsx

@@ -2,7 +2,6 @@
 program device_insurance "Device insurance"
 use insurance
 use money
-party inspector: staff role claims
 
 object device "Insured device" {
   fields { model: text, serialNumber: text, purchaseDate: date }
@@ -13,16 +12,17 @@ object device "Insured device" {
     economics pay { purpose: earning, sourceParty: owner }
     expose pay as pay_for_device
   }
-  // Bind device_insurer to an ADL adapter before creating cover. Premiums net of commission go to its account.
+  // conformance_boundary is the sandbox insurer adapter; swap in the insurer's registered adapter to go live.
+  // Premiums net of commission go to its account. claim_limit is the sum insured, set per cover at creation.
   attach protection = insurance.cover {
     expose create as create_protection
-    holder: owner, adapter: "device_insurer", commission: 10%, covers: purchase
+    holder: owner, adapter: "conformance_boundary", commission: 10%, covers: purchase
     expose activate as activate_cover
     expose cancel as cancel_cover
   }
   attach claim = insurance.claim {
     expose create as create_claim
-    cover: protection, inspector: inspector
+    cover: protection, inspector: operator
     expose approve as approve_claim
     expose deny as deny_claim
     expose pay as pay_claim

package/examples/lending.hsx

@@ -20,7 +20,7 @@ object business "Business funding" {
   attach loan = financing.installments {
     expose create as create_loan
     borrower: owner, capital: operator
-    months: 12, profit: 6%, disburse_to: borrower
+    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
     expose sign as sign_loan
     expose disburse as release_loan

package/examples/library.hsx

@@ -9,7 +9,7 @@ object car "Cars" {
  attach ceiling = financing.portfolio_limit { expose create as create_ceiling, limit: 1500000 SAR }
  attach plan = financing.installments {
   borrower: actor, capital: operator, share: 25%
-  months: 3, profit: 2.5%, funds: sale, limits: limits, portfolio: ceiling
+  months: 3, pricing: flat_total, profit_rate: 2.5%, funds: sale, limits: limits, portfolio: ceiling
   expose create as finance
  }
 }

package/examples/rental-deposit.hsx

@@ -3,7 +3,7 @@
 program equipment_rental "Equipment rental"
 party renter: business
 
-// Program-local instruments have fixed terms and parties, not tunable parameters.
+// The renter is one declared business, so this instrument takes no parameters.
 instrument deposit {
   summary: "Hold a rental deposit, then return it less any fixed late fee."
   fields {

package/examples/reporting.hsx

@@ -19,7 +19,7 @@ object purchase "Equipment loan" {
   attach loan = financing.installments {
     expose create as create_loan
     borrower: owner, capital: operator
-    months: 12, profit: 6%, disburse_to: borrower
+    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
     expose sign as sign_purchase_loan
     expose disburse as fund_purchase

package/examples/serviced.hsx

@@ -11,7 +11,7 @@ object car "Car" {
  attach ceiling = financing.portfolio_limit { expose create as create_ceiling, limit: 10000000 SAR }
  attach plan = financing.installments {
   borrower: actor, capital: operator
-  months: 36, profit: 8.5%, down_payment: 10%
+  months: 36, pricing: flat_total, profit_rate: 8.5%, down_payment: 10%
   apply: fines_profit_principal, payoff_rebate: 100%, write_off_after: 90d
   funds: sale, limits: limits, portfolio: ceiling
   expose create as finance, expose sign as sign_contract, expose payoff as payoff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "1.0.124",
+  "version": "1.0.128",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -84,8 +84,8 @@
     "examples:bundle": "bun scripts/bundle-examples.ts"
   },
   "dependencies": {
-    "@hyperscale0/adl": "1.0.124",
-    "@hyperscale0/udl": "1.0.124",
+    "@hyperscale0/adl": "1.0.128",
+    "@hyperscale0/udl": "1.0.128",
     "fast-sha256": "1.3.0"
   },
   "devDependencies": {
@@ -97,5 +97,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "8275c2a026b6cc8a628ab11198ce0eefb8568982"
+  "gitHead": "d22a6727cbbb9fc59ffc1625b2d162711dccbe98"
 }

package/src/compile.ts

@@ -534,14 +534,6 @@ export function compile(
     }
     for (const decl of program.decls)
       if (decl.kind === "instrument") templates.set(decl.name, decl);
-    for (const decl of program.decls) {
-      if (decl.kind === "instrument" && decl.parameters.length)
-        fail(
-          decl,
-          "This compiler cannot instantiate a parameterized instrument declared inside a program.",
-          "For this version, specialize the instrument with fixed bindings and remove its parameters. Custom reusable headers require a host-supplied library.",
-        );
-    }
     const document: UdlDocument = {
       udl: UDL_FORMAT_VERSION,
       version: 1,
@@ -906,8 +898,12 @@ export function compile(
         const typeName =
           type.kind === "type" || type.kind === "call" ? type.name : text(type);
         const partyParameter = attachmentInfo && typeName === "party";
+        const optional = type.kind === "type" && type.optional;
+        // An optional party stays unset unless the attachment binds it, so a
+        // program party that shares its name does not switch it on.
         const byName: Expr | undefined =
           partyParameter &&
+          !optional &&
           (subjectPartyRoles.includes(param.key as SubjectPartyRole) ||
             document.parties[param.key])
             ? { kind: "name", value: param.key, span: origin }
@@ -920,7 +916,7 @@ export function compile(
             source: declarationSources.get(decl) ?? "program",
           });
         if (!actual) {
-          if (type.kind === "type" && type.optional) continue;
+          if (optional) continue;
           parameterErrors.push({
             span: origin,
             code: partyParameter ? "subject_party_unbound" : "HSX1001",
@@ -989,7 +985,12 @@ export function compile(
           .filter((entry) => entry.key.startsWith("action "))
           .flatMap(
             (entry) =>
-              asBlock(entries(asBlock(entry.value)).get("subject")).entries,
+              // Read subject rows directly: entries() refuses repeated when branches.
+              asBlock(
+                asBlock(entry.value).entries.find(
+                  (row) => row.key === "subject",
+                )?.value,
+              ).entries,
           );
         const moneyFields = [
           ...new Set(
@@ -2286,12 +2287,12 @@ export function compile(
             };
           }
         }
-        const fromBinding = slots.get("from");
-        if (
-          fromBinding?.kind === "name" &&
-          fromBinding.value.includes(".") &&
-          slots.has("moves")
-        ) {
+        const from = slots.get("from");
+        // A policy member may sit in a state list such as `[funded, dispute.refund_after]`.
+        const fromBinding = (from?.kind === "list" ? from.items : [from]).find(
+          (item) => item?.kind === "name" && item.value.includes("."),
+        );
+        if (fromBinding?.kind === "name" && slots.has("moves")) {
           const [parameter, member] = fromBinding.value.split(".");
           const suppliedPolicy = supplied.get(parameter!);
           if (suppliedPolicy?.kind === "block") {
@@ -2332,6 +2333,7 @@ export function compile(
           ...(actionSubject ? { subject: actionSubject } : {}),
         };
         authored.set(a, row.value);
+        const actionFeeCalculations: UdlCalculation[] = [];
         for (const binding of boundaryBindings)
           if (
             !a.subject?.adapters.find((entry) => entry.binding === binding)
@@ -2692,8 +2694,14 @@ export function compile(
                       "write a percentage such as 1%",
                     );
                   const prefix = `${name}_${key}`;
+                  // Instrument calculations run at create, before any action
+                  // input exists, so a fee on an input amount runs with its action.
+                  const perAction =
+                    "field" in transfer.amount &&
+                    transfer.amount.field.startsWith("input.");
                   const derived = (
                     suffix: string,
+                    label: string,
                     calculation: Omit<UdlCalculation, "target">,
                   ): UdlValue => {
                     const target = prefix + "_" + suffix;
@@ -2703,19 +2711,32 @@ export function compile(
                         `generated fee field ${target} conflicts with a field`,
                         "rename the authored field or move key",
                       );
-                    fields.push({ name: target, type: "money" });
-                    calculations.push({
+                    fields.push({
+                      name: target,
+                      type: "money",
+                      label,
+                      ...(perAction ? { optional: true } : {}),
+                    });
+                    (perAction ? actionFeeCalculations : calculations).push({
                       ...calculation,
                       target,
                     } as UdlCalculation);
                     return { field: `self.${target}` };
                   };
-                  const gross = derived("feeGross", {
-                    op: "rate",
-                    base: transfer.amount,
-                    bps: { literal: literal(rate) },
-                    rounding: "floor",
-                  } as Omit<UdlCalculation, "target">);
+                  // Labels come from the source keys: seller or buyer, cap, tax.
+                  const feeLabel = `${paidBy === "seller" ? "Seller" : "Buyer"} fee`;
+                  const gross = derived(
+                    "feeGross",
+                    quoted.kind === "capped"
+                      ? `${feeLabel} before cap`
+                      : feeLabel,
+                    {
+                      op: "rate",
+                      base: transfer.amount,
+                      bps: { literal: literal(rate) },
+                      rounding: "floor",
+                    } as Omit<UdlCalculation, "target">,
+                  );
                   let charge = gross;
                   if (quoted.kind === "capped") {
                     if (quoted.cap.kind !== "money")
@@ -2724,7 +2745,7 @@ export function compile(
                         "fee cap needs money",
                         "write an amount such as 750 SAR",
                       );
-                    charge = derived("fee", {
+                    charge = derived("fee", feeLabel, {
                       op: "minimum",
                       values: [gross, { literal: literal(quoted.cap) }],
                     } as Omit<UdlCalculation, "target">);
@@ -2737,7 +2758,7 @@ export function compile(
                       "write tax: 15%",
                     );
                   const vat = tax
-                    ? derived("tax", {
+                    ? derived("tax", "Fee tax", {
                         op: "rate",
                         base: charge,
                         bps: { literal: literal(tax) },
@@ -2747,7 +2768,7 @@ export function compile(
                   const charges = vat ? [charge, vat] : [charge];
                   const net =
                     paidBy === "seller"
-                      ? derived("net", {
+                      ? derived("net", "Amount after fee", {
                           op: "subtract",
                           base: transfer.amount,
                           subtract: charges,
@@ -2819,6 +2840,8 @@ export function compile(
             }
           } else (a as unknown as Record<string, unknown>)[key] = data(expr);
         }
+        if (actionFeeCalculations.length)
+          a.calculate = [...(a.calculate ?? []), ...actionFeeCalculations];
         if (attachmentInfo && !attachmentInfo.child) {
           if (attachmentInfo.exposed.has(name)) {
             if (automatic(a.actor))
@@ -3298,7 +3321,9 @@ export function compile(
       });
     };
     for (const decl of program.decls) {
-      if (decl.kind === "instrument") {
+      // A parameterized program instrument is a template, like a header
+      // instrument: each attachment instantiates it with its own bindings.
+      if (decl.kind === "instrument" && !decl.parameters.length) {
         addInstrument(decl, decl.name, emptyBlock, decl.span);
       }
       if (decl.kind === "assignment") {
@@ -3638,7 +3663,9 @@ export function compile(
         fail(
           at,
           `\`${name}\` is not a declared party.${didYouMean(name, names)}`,
-          `Declare it with \`party ${name}: business\`, or name a declared party (${names.join(", ")}).`,
+          subjectPartyRoles.includes(name as SubjectPartyRole)
+            ? `Declare a party parameter such as \`holder: party\` on the instrument, use it here, and bind \`holder: ${name}\` where you attach it.`
+            : `Declare it with \`party ${name}: business\`, or name a declared party (${names.join(", ")}).`,
         );
     };
     const checkInput = (
@@ -3716,6 +3743,42 @@ export function compile(
       inst,
       label: declarations.get(inst)!.name,
     });
+    // A family member drops an optional reference field its binding left
+    // unset (a borrower-funded plan has no `funds`), so it cannot match and
+    // leaves the selection. The header must still declare the field.
+    const matchable = (selection: UdlSelection) => {
+      const members = [selection.instrument].flat();
+      const header = selection.family
+        ? templates.get(
+            `${selection.family.module}.${selection.family.exportPath}`,
+          )
+        : undefined;
+      if (
+        !header ||
+        !entries(asBlock(entries(header.body).get("fields"))).has(
+          selection.reference,
+        )
+      )
+        return members;
+      return members.filter((id) =>
+        resolveField(document, byId.get(id)!, `self.${selection.reference}`),
+      );
+    };
+    // A count over no matchable member is zero.
+    for (const inst of document.instruments)
+      for (const action of Object.values(inst.actions))
+        action.requires = action.requires.map((requirement) =>
+          requirement.kind === "aggregate" &&
+          requirement.measure === "count" &&
+          !matchable(requirement.selection).length
+            ? {
+                kind: "compare",
+                left: { literal: 0 },
+                operator: requirement.operator,
+                right: requirement.value,
+              }
+            : requirement,
+        );
     const checkSelection = (
       selection: UdlSelection,
       at: Located,
@@ -3723,6 +3786,12 @@ export function compile(
     ) => {
       walk(selection.anchor, "anchor", site(selection, "anchor", at), scope);
       walk(selection.where, "where", site(selection, "where", at), scope);
+      const members = matchable(selection);
+      if (
+        members.length &&
+        members.length < [selection.instrument].flat().length
+      )
+        selection.instrument = members;
       for (const id of [selection.instrument].flat()) {
         checkTarget(id, site(selection, "instrument", at));
         const target = scopeOf(byId.get(id)!);