@hyperscale0/hsx 1.0.258 → 1.0.284

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,aAAa,EAAE,soLAAsoL,CAAC;IACvpL,CAAC,WAAW,EAAE,6wMAA6wM,CAAC;IAC5xM,CAAC,iBAAiB,EAAE,2sNAA2sN,CAAC;IAChuN,CAAC,YAAY,EAAE,yjQAAyjQ,CAAC;IACzkQ,CAAC,eAAe,EAAE,6nrFAA6nrF,CAAC;IAChprF,CAAC,eAAe,EAAE,41LAA41L,CAAC;IAC/2L,CAAC,aAAa,EAAE,03UAA03U,CAAC;IAC34U,CAAC,iBAAiB,EAAE,syTAAsyT,CAAC;IAC3zT,CAAC,WAAW,EAAE,8zYAA8zY,CAAC;IAC70Y,CAAC,eAAe,EAAE,ir2BAAir2B,CAAC;IACps2B,CAAC,aAAa,EAAE,4hKAA4hK,CAAC;IAC7iK,CAAC,YAAY,EAAE,2zIAA2zI,CAAC;CAC50I,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,m7LAAm7L,CAAC;IACp8L,CAAC,WAAW,EAAE,6wMAA6wM,CAAC;IAC5xM,CAAC,iBAAiB,EAAE,qrNAAqrN,CAAC;IAC1sN,CAAC,YAAY,EAAE,mkOAAmkO,CAAC;IACnlO,CAAC,eAAe,EAAE,kinFAAkinF,CAAC;IACrjnF,CAAC,eAAe,EAAE,41LAA41L,CAAC;IAC/2L,CAAC,aAAa,EAAE,03UAA03U,CAAC;IAC34U,CAAC,iBAAiB,EAAE,syTAAsyT,CAAC;IAC3zT,CAAC,WAAW,EAAE,ogYAAogY,CAAC;IACnhY,CAAC,cAAc,EAAE,svJAAsvJ,CAAC;IACxwJ,CAAC,eAAe,EAAE,4o1BAA4o1B,CAAC;IAC/p1B,CAAC,aAAa,EAAE,4hKAA4hK,CAAC;IAC7iK,CAAC,YAAY,EAAE,2zIAA2zI,CAAC;CAC50I,CAAC,CAAC"}

package/docs/README.md

@@ -42,10 +42,10 @@ hsx cost lesson.hsx
 `check` exits zero without output on success. `build` writes canonical UDL;
 without `--out` it prints to stdout. `cost` prints instruction counts, described
 below. `format` prints formatted source or writes it with `--out`. `headers --json`
-prints the header manifest. These commands have no `--strict` or `--catalog` option.
-Exit 1 means invalid source; exit 2 means a command or file error. Diagnostics name
-the source, line, column, code, problem and suggested fix. UDL validation keeps
-its UDL diagnostic codes; binding errors can have names such as
+prints the header manifest. Exit 1 means invalid source; exit 2 means a command
+or file error. Diagnostics name the source, line, column, code, problem and
+suggested fix. UDL validation keeps its UDL diagnostic codes; binding errors can
+have names such as
 `subject_party_unbound`. Read the message and fix, not just the code.
 
 At runtime, create a lesson object first, then call `book_lesson` to create its
@@ -57,38 +57,37 @@ and party IDs are not metadata supplied by the caller.
 ## A rental deposit in one hour
 
 Open [rental-deposit.hsx](../examples/rental-deposit.hsx). It is a complete source
-file for a business renting equipment from the program operator. Copy it to
+file for a customer renting equipment from the program operator. Copy it to
 `rental.hsx` and run the same check, build and cost commands against that file.
 No header import is needed because it declares its own instrument.
 
-The terms are a 1,000 SAR deposit and a one-time 50 SAR late fee. The supplied
-`dueAt` timestamp is the cutoff: a return before it gets the whole deposit back;
-a return at or after it gets 950 SAR back. The operator receives the other 50 SAR.
-The late fee is not a daily charge and is not `financing.late_charge`, which
+The terms are a 1,000 SAR deposit and one late charge of 50 SAR plus 15% VAT,
+which is 7.50 SAR. The record's `startsAt` and `dueAt` timestamps reach the
+agreement through `rename`, so `agree_rental` reads them from the object. A
+return before `dueAt` gets the whole deposit back; a return at or after it gets
+942.50 SAR back. The operator receives 50 SAR and `programTax` receives 7.50 SAR.
+The late charge is not a daily charge and is not `financing.late_charge`, which
 requires a financing plan and an overdue installment.
 
-| Step                         | Public action           | Actor and required values                                                             | Money effect                                       |
-| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| Create the object            | Host object creation    | Optional `equipment` metadata                                                         | None                                               |
-| Agree terms                  | `agree_rental`          | Bound renter; `dueAt`, for example `2027-01-10T12:00:00+03:00`, must be in the future | Creates the agreement's held account               |
-| Fund before the cutoff       | `pay_deposit`           | Bound renter with 1,000 SAR available                                                 | Renter pays 1,000 SAR into held                    |
-| Record an on-time return     | `return_equipment`      | Operator; `returnReference` metadata                                                  | Held pays 1,000 SAR to renter                      |
-| Or record a late return      | `return_equipment_late` | Operator; `returnReference` metadata                                                  | Held pays 50 SAR to operator and 950 SAR to renter |
-| Cancel an unfunded agreement | `cancel_rental`         | Bound renter, while pending                                                           | None                                               |
+| Step                         | Public action           | Actor and required values                                                                                 | Money effect                                                           |
+| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Create the object            | Host object creation    | Optional `equipment`, `serialNumber`, `renterName`, `startsAt` and `dueAt` metadata                       | None                                                                   |
+| Agree terms                  | `agree_rental`          | Bound renter; `startsAt` and `dueAt`, for example `2027-01-10T12:00:00+03:00`, both future, `dueAt` later | Creates the agreement's held account                                   |
+| Fund before pickup           | `pay_deposit`           | Bound renter with 1,000 SAR available, before `startsAt`                                                  | Renter pays 1,000 SAR into held                                        |
+| Record an on-time return     | `return_equipment`      | Operator, before `dueAt`; `returnReference` metadata                                                      | Held pays 1,000 SAR to renter                                          |
+| Or record a late return      | `return_equipment_late` | Operator, at or after `dueAt`; `returnReference` metadata                                                 | Held pays 50 SAR to operator, 7.50 SAR to tax and 942.50 SAR to renter |
+| Cancel before pickup         | `cancel_before_pickup`  | Bound renter on a funded agreement, before `startsAt`                                                     | Held pays 1,000 SAR back to renter                                     |
+| Cancel an unfunded agreement | `cancel_unpaid_rental`  | Bound renter, while pending                                                                               | None                                                                   |
 
 Choose one return action. Both finish the agreement, so the fee and refund cannot
-repeat. The late action calculates the refund from the held balance before either
+repeat. The late action calculates the refund from the held balance before any
 move runs. Both paths empty the held account. `returnReference` records the
 operator's return evidence; it does not verify the physical return. Time means
 the executor's current time when the action runs, not a caller-supplied return date.
 A late `due` permits the operator action; it does not schedule that action.
 
-This sample binds a declared business named `renter` in Product configuration.
-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
+The renter is a party parameter bound to the rental object's `owner`. Each rental
+can belong to a different customer without a fixed business binding. 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
@@ -97,8 +96,7 @@ 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.
-The `hide deposit.*` lines remove public names from the unattached declaration;
-the attachment exposes its own copy. `money.hold` and `escrow.hold` both refund
+`money.hold` and `escrow.hold` both refund
 whole amounts, so neither implements this partial-refund policy by itself.
 
 A local compile gives you a contract. Executing it needs a host with authenticated
@@ -189,7 +187,7 @@ and basis points. Fee and tax calculations round down. Split percentages sum to
 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
+Tax binds `programTax`. Fees go to `programOperator`. Fine, recovery and
 residual destinations are party tunables.
 
 Attached actions are private unless the attachment exposes them with
@@ -284,8 +282,9 @@ maxAge 1d` requires a recent completed provider check.
 only to reservations. Fees settle with create moves, never reservations. A fee move
 also derives `<action>_<move>_debit`, the payer's whole debit: amount plus fee and
 tax when the buyer pays, the amount alone when the seller pays. Repeated clauses keep
-their declaration order. The JSON-like clause form remains accepted and lowers
-to the same [UDL clauses](https://github.com/hyperscale0/hyperscale-udl/blob/main/spec/README.md).
+their declaration order. A clause list after a colon, such as `calculate: [{ ... }]`
+or `invoke: [{ ... }]`, writes [UDL clauses](https://github.com/hyperscale0/hyperscale-udl/blob/main/spec/README.md)
+directly; the std headers use it for calculations, `set` and invocations.
 Use `economics { purpose: earning, sourceParty: merchant }` on a move to
 classify posted money. Other purposes are `principal`, `participant_payout`,
 `internal`, `prepaid_credit`, and `pass_through`. `reversalOf: self.originalTransfer` links a
@@ -369,7 +368,8 @@ the selection limit, so a count is an upper bound rather than observed usage.
 Zero-valued moves can cost fewer actual transfers than their static count.
 
 The rental attachment's create declares one owned account, fund declares one
-transfer, on-time return one, and late return two. These are counts, not SAR
+transfer, on-time return one, and late return three: the charge, its VAT and
+the refund. These are counts, not SAR
 prices. The executor's tariff supplies commercial prices and actual usage.
 
 The compiler API is `compile(source)`. On success, `result.verdict` is `valid`
@@ -395,7 +395,16 @@ customer: `financing.limits` and `financing.installments` (borrower),
 (member). Several customers can each start one on the same record. A plan,
 commitment or other reference resolves the sibling that binds the same
 accounts to the parties both share, so each customer's plan finds its own
-escrow and each investor's commitment finds their own wallet.
+checkout and each investor's commitment finds their own wallet.
+
+A financed purchase connects `financing.installments` to `escrow.hold` through
+`purchase.checkout`. Bind the plan's `funds` to checkout, checkout's `funds` to
+the hold, and checkout's `plans` to the plan. Give the hold the funding policy
+`{ controllers: [checkout], reference: "funds", blocking_states: [active] }`.
+If a marketplace reservation contributes a deposit, its `converters` also names
+checkout. Create the hold, then checkout, then the plan. The coordinator collects
+the missing down payment and returns outstanding lender capital before a buyer
+refund. See [library.hsx](../examples/library.hsx) for the complete wiring.
 
 `financing.limits` and `financing.portfolio_limit` declare `scope: product`.
 Create and approve the portfolio limit once per Product and the borrower limit

package/examples/library.hsx

@@ -3,6 +3,7 @@
 program cars "Riyadh used van finance"
 use escrow
 use financing
+use purchase
 party dealer: business
 
 // Bind dealer to the vehicle seller. Set price to its gross 34,500 SAR invoice;
@@ -13,6 +14,7 @@ object car "Financed van purchase" {
   columns: [make, model, year, vin, price]
   attach sale = escrow.hold {
     payer: actor, payee: dealer
+    funding: { controllers: [checkout], reference: "funds", blocking_states: [active] }
     fee: { seller: 2%, tax: 15% }
     deliver_within: 7d, accept_within: 3d
     expose create as agree_van_purchase
@@ -42,10 +44,14 @@ object car "Financed van purchase" {
   // At 34,500 SAR, 2.5% flat profit is 862.50 SAR for the whole term.
   // Financing fee: 0%, tax: 0% on principal; no separate financing service fee.
   // Supply three future monthly dates and a unique settlementIdentity.
+  attach checkout = purchase.checkout {
+    plans: plan, funds: sale, borrower: actor, capital: operator
+    expose create as prepare_financed_purchase
+  }
   attach plan = financing.installments {
     borrower: actor, capital: operator, share: 0%
     months: 3, pricing: flat_total, profit_rate: 2.5%
-    funds: sale, limits: limits, portfolio: ceiling
+    funds: checkout, limits: limits, portfolio: ceiling
     returned_goods: refund_all, refund_within: 30d, write_off_after: 90d
     expose create as finance
     expose sign as sign_finance_agreement

package/examples/rental-deposit.hsx

@@ -1,11 +1,10 @@
-// Dammam equipment hire holds a 1,000 SAR deposit for a business renter.
+// Equipment rental holds a 1,000 SAR deposit for the customer who owns each rental.
 // Return the deposit in full, or deduct a single 50 SAR late charge plus 7.50 SAR VAT.
-program equipment_rental "Dammam equipment hire"
-party renter: business
+program equipment_rental "Equipment rental deposits"
 
-// Bind renter to the business hiring the equipment. The deposit has fee 0%
+// Bind renter to the customer who owns this rental. The deposit has fee 0%
 // and tax 0% because it stays refundable principal. The late service has 15% VAT.
-instrument deposit {
+instrument deposit(renter: party) {
   summary: "Hold security until return, with one disclosed late charge."
   fields {
     renter: account of renter
@@ -56,6 +55,7 @@ object rental "Equipment deposit" {
   fields { equipment: text, serialNumber: text, renterName: text }
   columns: [equipment, serialNumber, renterName, startsAt, dueAt]
   attach security = deposit {
+    renter: owner
     rename { startsAt: startsAt, dueAt: dueAt }
     expose create as agree_rental
     expose fund as pay_deposit
@@ -65,10 +65,3 @@ object rental "Equipment deposit" {
     expose cancel as cancel_unpaid_rental
   }
 }
-
-hide deposit.create
-hide deposit.fund
-hide deposit.return_on_time
-hide deposit.return_late
-hide deposit.refund_before_pickup
-hide deposit.cancel

package/examples/serviced.hsx

@@ -3,6 +3,7 @@
 program car_financing "Dammam delivery van finance"
 use escrow
 use financing
+use purchase
 use collections
 party dealer: business
 
@@ -13,6 +14,7 @@ object car "Delivery van finance" {
   columns: [make, model, year, vin, price]
   attach sale = escrow.hold {
     payer: actor, payee: dealer
+    funding: { controllers: [checkout], reference: "funds", blocking_states: [active] }
     fee: { seller: 1%, tax: 15% }, deliver_within: 14d, accept_within: 3d
     expose create as agree_van_purchase
     expose fund as pay_cash_instead
@@ -40,13 +42,17 @@ object car "Delivery van finance" {
   // Down payment is 6,900 SAR. Capital is 62,100 SAR; total flat profit is
   // 5,278.50 SAR. Financing service fee: 0%, tax: 0% on principal repayments.
   // Supply 36 future monthly dates. Approve limits before collecting and funding.
+  attach checkout = purchase.checkout {
+    plans: plan, funds: sale, borrower: actor, capital: operator
+    expose create as prepare_financed_purchase
+  }
   attach plan = financing.installments {
     borrower: actor, capital: operator, share: 0%
     months: 36, pricing: flat_total, profit_rate: 8.5%, down_payment: 10%
     apply: fines_profit_principal, payoff_rebate: 100%, write_off_after: 90d
     refund_within: 30d, payoff_quote_expiry: 1h, returned_goods: refund_all
     max_extension: 60d, max_amendments: 2, amendment_expiry: 7d
-    funds: sale, limits: limits, portfolio: ceiling
+    funds: checkout, limits: limits, portfolio: ceiling
     expose create as finance
     expose sign as sign_contract
     expose collect_down_payment as pay_down_payment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "1.0.258",
+  "version": "1.0.284",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -40,6 +40,10 @@
       "types": "./dist/src/cost.d.ts",
       "default": "./dist/src/cost.js"
     },
+    "./bases": {
+      "types": "./dist/src/bases.d.ts",
+      "default": "./dist/src/bases.js"
+    },
     "./examples": {
       "types": "./dist/src/examples.d.ts",
       "default": "./dist/src/examples.js"
@@ -61,6 +65,7 @@
     "bin",
     "dist",
     "docs",
+    "bases",
     "examples",
     "std",
     "src"
@@ -78,14 +83,15 @@
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "std:bundle": "bun scripts/bundle-std.ts",
-    "generate": "bun run std:bundle && bun run examples:bundle",
-    "prepare": "bun run std:bundle && bun run examples:bundle",
+    "generate": "bun run std:bundle && bun run examples:bundle && bun run bases:bundle",
+    "prepare": "bun run std:bundle && bun run examples:bundle && bun run bases:bundle",
     "check": "bun run typecheck && tsc -p playground/tsconfig.json && bun test test",
-    "examples:bundle": "bun scripts/bundle-examples.ts"
+    "examples:bundle": "bun scripts/bundle-examples.ts",
+    "bases:bundle": "bun scripts/bundle-bases.ts"
   },
   "dependencies": {
-    "@hyperscale0/adl": "1.0.258",
-    "@hyperscale0/udl": "1.0.258",
+    "@hyperscale0/adl": "1.0.284",
+    "@hyperscale0/udl": "1.0.284",
     "fast-sha256": "1.3.0"
   },
   "devDependencies": {
@@ -97,5 +103,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "20d3d1eddd70d7629f5ae6a5b14e0e89c4ce536a"
+  "gitHead": "f4101f194e0e7c24997b0625ab1d48bec1255508"
 }

package/src/bases-bundle.ts

@@ -0,0 +1,15 @@
+// Generated by open/hsx/scripts/bundle-bases.ts. Do not edit by hand.
+import type { HsxBase } from "./bases.ts";
+export const bases: HsxBase[] = [
+  {"id":"cards","title":"Control card spending","summary":"Reserve a card payment within its spending limit before capture.","headers":["cards"],"source":"// Reserve a card payment within its spending limit before capture.\nprogram cards_base \"Control card spending\"\nuse cards\nparty seller: business\n\nobject card \"Card\" {\n  attach holder = cards.cardholder {\n    holder: owner\n    expose create as create_holder\n    expose activate as activate_holder\n    expose suspend as suspend_holder\n    expose resume as resume_holder\n    expose close as close_holder\n  }\n  attach card = cards.card {\n    holder: holder, person: owner, issuer: operator, spend_limit: runtime\n    expose create as create_card\n    expose activate as activate_card\n    expose freeze as freeze_card\n    expose unfreeze as unfreeze_card\n    expose issuer_freeze as issuer_freeze_card\n    expose issuer_unfreeze as issuer_unfreeze_card\n    expose cancel as cancel_card\n  }\n  attach payment = cards.authorization {\n    card: card, merchant: seller, issuer: operator\n    expose create as create\n    expose approve as approve\n    expose decline as decline\n    expose capture as capture\n    expose reverse as reverse\n  }\n  attach receipt = cards.transaction {\n    authorization: payment\n    expose create as record_payment\n    expose refund as refund\n  }\n}\n"},
+  {"id":"collections","title":"Follow up overdue payments","summary":"Refer overdue instalments for collection and limit contact attempts.","headers":["collections","financing"],"source":"// Refer overdue instalments for collection and limit contact attempts.\nprogram collections_base \"Follow up overdue payments\"\nuse collections\nuse financing\nparty collector: business\n\nobject plan \"Plan\" {\n  fields { price: money }\n  attach allowance = financing.limits {\n    borrower: owner, per_borrower: runtime\n    expose create as request_limit\n    expose approve as approve_limit\n  }\n  attach budget = financing.portfolio_limit {\n    limit: runtime\n    expose create as create_budget\n    expose approve as approve_budget\n  }\n  // Architect sets the placeholder profit rate during tailoring.\n  attach plan = financing.installments {\n    borrower: owner, capital: operator\n    months: 2, pricing: flat_total, profit_rate: 0%\n    disburse_to: borrower, limits: allowance, portfolio: budget\n    expose create as quote\n    expose sign as sign\n    expose disburse as fund\n    expose cancel as cancel_quote\n    expose void as cancel_plan\n    expose payoff as repay_early\n    expose complete as complete\n  }\n  attach recovery = collections.case {\n    on: plan, agency: collector, capital: operator\n    expose create as refer\n    expose assign as assign\n    expose recover as recover\n    expose recall as recall\n    expose return_uncollected as return_uncollected\n  }\n  attach contact = collections.contact {\n    case: recovery, agency: collector\n    expose create as record_contact\n  }\n}\n\nexpose plan.plan.payment.create as record_payment\nexpose plan.plan.payment.pay as pay_instalment\nexpose plan.plan.payment.refund as refund_payment\nexpose plan.plan.payoff_quote.create as quote_payoff\n\nexpose plan.contact.outcome.create as record_contact_outcome\n"},
+  {"id":"escrow","title":"Hold payment until delivery","summary":"Hold a buyer’s payment until delivery is accepted.","headers":["escrow"],"source":"// Hold a buyer’s payment until delivery is accepted.\nprogram escrow_base \"Hold payment until delivery\"\nuse escrow\nparty seller: business\n\nobject order \"Order\" {\n  fields { price: money }\n  attach payment = escrow.hold {\n    payer: owner, payee: seller\n    expose create as create\n    expose fund as fund\n    expose deliver as deliver\n    expose accept as accept\n    expose dispute as dispute\n    expose verify_return as verify_return\n    expose refund as refund\n    expose refund_undelivered as refund_undelivered\n    expose settle_release as settle_release\n    expose settle_return as settle_return\n    expose settle_refund as settle_refund\n    expose cancel as cancel\n  }\n}\n"},
+  {"id":"financing","title":"Split a purchase into instalments","summary":"Fund a purchase and collect its scheduled repayments.","headers":["financing"],"source":"// Fund a purchase and collect its scheduled repayments.\nprogram financing_base \"Split a purchase into instalments\"\nuse financing\nparty seller: business\n\nobject purchase \"Purchase\" {\n  fields { price: money }\n  attach allowance = financing.limits {\n    borrower: owner, per_borrower: runtime\n    expose create as request_limit\n    expose approve as approve_limit\n  }\n  attach budget = financing.portfolio_limit {\n    limit: runtime\n    expose create as create_budget\n    expose approve as approve_budget\n  }\n  // Architect sets the placeholder profit rate during tailoring.\n  attach plan = financing.installments {\n    borrower: owner, capital: operator\n    months: 2, pricing: flat_total, profit_rate: 0%\n    disburse_to: seller, seller: seller, limits: allowance, portfolio: budget\n    expose create as quote\n    expose sign as sign\n    expose disburse as fund\n    expose cancel as cancel_quote\n    expose void as cancel_plan\n    expose payoff as repay_early\n    expose complete as complete\n  }\n}\n\nexpose purchase.plan.payment.create as record_payment\nexpose purchase.plan.payment.pay as pay_instalment\nexpose purchase.plan.payment.refund as refund_payment\nexpose purchase.plan.payoff_quote.create as quote_payoff\n"},
+  {"id":"insurance","title":"Protect a purchase","summary":"Collect cover premiums and reserve approved claims for payment.","headers":["insurance"],"source":"// Collect cover premiums and reserve approved claims for payment.\nprogram insurance_base \"Protect a purchase\"\nuse insurance\n\nobject purchase \"Purchase\" {\n  attach cover = insurance.cover {\n    holder: owner, adapter: \"conformance_boundary\"\n    expose create as create_cover\n    expose activate as activate_cover\n    expose cancel as cancel_cover\n  }\n  attach claim = insurance.claim {\n    cover: cover, inspector: operator\n    expose create as create_claim\n    expose approve as approve_claim\n    expose deny as deny_claim\n    expose pay as pay_claim\n  }\n}\n\nexpose purchase.cover.slice.create as create_period\nexpose purchase.cover.slice.collect as collect_premium\n"},
+  {"id":"lending","title":"Pool funds for lending","summary":"Pool member commitments to fund a loan and distribute repayments or losses.","headers":["lending","financing","wallet"],"source":"// Pool member commitments to fund a loan and distribute repayments or losses.\nprogram lending_base \"Pool funds for lending\"\nuse lending\nuse financing\nuse wallet\n\nobject plan \"Plan\" {\n  fields { price: money }\n  attach allowance = financing.limits {\n    borrower: owner, per_borrower: runtime\n    expose create as request_limit\n    expose approve as approve_limit\n  }\n  attach budget = financing.portfolio_limit {\n    limit: runtime\n    expose create as create_budget\n    expose approve as approve_budget\n  }\n  // Architect sets the placeholder profit rate during tailoring.\n  attach plan = financing.installments {\n    borrower: owner, capital: operator\n    months: 2, pricing: flat_total, profit_rate: 0%\n    disburse_to: borrower, limits: allowance, portfolio: budget\n    expose create as quote\n    expose sign as sign\n    expose disburse as fund\n    expose cancel as cancel_quote\n    expose void as cancel_plan\n    expose payoff as repay_early\n    expose complete as complete\n  }\n  attach balance = wallet.balance {\n    holder: actor\n    expose create as create_balance\n    expose activate as activate_balance\n    expose topup as add_funds\n    expose withdraw as withdraw_funds\n    expose close as close_balance\n  }\n  attach round = lending.round {\n    borrower: owner, plan: plan\n    expose create as open_round\n    expose close as close_round\n  }\n  attach commitment = lending.commitment {\n    round: round, wallet: balance, investor: actor\n    expose create as commit\n    expose withdraw as withdraw_commitment\n  }\n  attach returns = lending.distribution {\n    round: round, receipt: plan.settlement\n    expose create as record_settlement\n    expose prepare_cash as prepare_returns\n    expose distribute_cash as distribute_returns\n  }\n  attach losses = lending.distribution {\n    round: round, receipt: plan.settlement, mode: loss\n    expose create as record_loss\n    expose prepare_loss as prepare_losses\n    expose distribute_loss as distribute_losses\n  }\n}\n\nexpose plan.plan.payment.create as record_payment\nexpose plan.plan.payment.pay as pay_instalment\nexpose plan.plan.payment.refund as refund_payment\nexpose plan.plan.payoff_quote.create as quote_payoff\n\nexpose plan.returns.share.create as create_return_share\nexpose plan.losses.share.create as create_loss_share\nexpose plan.plan.write_off_request.create as request_write_off\nexpose plan.plan.write_off_request.apply as apply_write_off\nexpose plan.plan.write_off_request.cancel as cancel_write_off\n"},
+  {"id":"marketplace","title":"Connect buyers and sellers","summary":"Turn a seller’s offer into an order with payment held until acceptance.","headers":["marketplace","escrow"],"source":"// Turn a seller’s offer into an order with payment held until acceptance.\nprogram marketplace_base \"Connect buyers and sellers\"\nuse marketplace\nuse escrow\nparty seller: business\n\nobject order \"Order\" {\n  fields { price: money }\n  attach offer = marketplace.listing {\n    seller: seller\n    expose create as create_offer\n    expose publish as publish_offer\n    expose withdraw as withdraw_offer\n    expose sell as sell_offer\n  }\n  attach order = marketplace.order {\n    listing: offer, buyer: owner, fulfiller: seller\n    expose create as create_order\n    expose commit as commit_order\n    expose fulfill as fulfill_order\n    expose cancel as cancel_order\n  }\n  attach payment = escrow.hold {\n    payer: owner, payee: seller\n    expose create as create\n    expose fund as fund\n    expose deliver as deliver\n    expose accept as accept\n    expose dispute as dispute\n    expose verify_return as verify_return\n    expose refund as refund\n    expose refund_undelivered as refund_undelivered\n    expose settle_release as settle_release\n    expose settle_return as settle_return\n    expose settle_refund as settle_refund\n    expose cancel as cancel\n  }\n}\n"},
+  {"id":"money","title":"Collect a payment","summary":"Collect a payment from a customer.","headers":["money"],"source":"// Collect a payment from a customer.\nprogram money_base \"Collect a payment\"\nuse money\n\nobject purchase \"Purchase\" {\n  attach payment = money.transfer {\n    payer: owner, payee: operator\n    expose create as create\n    expose pay as pay\n    expose cancel as cancel\n  }\n}\n"},
+  {"id":"reporting","title":"Track repayments","summary":"Report outstanding balances and overdue repayments on financed purchases.","headers":["reporting","financing"],"source":"// Report outstanding balances and overdue repayments on financed purchases.\nprogram reporting_base \"Track repayments\"\nuse reporting\nuse financing\n\nobject purchase \"Purchase\" {\n  fields { price: money }\n  attach allowance = financing.limits {\n    borrower: owner, per_borrower: runtime\n    expose create as request_limit\n    expose approve as approve_limit\n  }\n  attach budget = financing.portfolio_limit {\n    limit: runtime\n    expose create as create_budget\n    expose approve as approve_budget\n  }\n  // Architect sets the placeholder profit rate during tailoring.\n  attach plan = financing.installments {\n    borrower: owner, capital: operator\n    months: 2, pricing: flat_total, profit_rate: 0%\n    disburse_to: borrower, limits: allowance, portfolio: budget\n    expose create as quote\n    expose sign as sign\n    expose disburse as fund\n    expose cancel as cancel_quote\n    expose void as cancel_plan\n    expose payoff as repay_early\n    expose complete as complete\n  }\n  attach reports = reporting.portfolio {\n    on: plan\n    expose create as create_reports\n  }\n}\n\nexpose purchase.plan.payment.create as record_payment\nexpose purchase.plan.payment.pay as pay_instalment\nexpose purchase.plan.payment.refund as refund_payment\nexpose purchase.plan.payoff_quote.create as quote_payoff\n"},
+  {"id":"savings","title":"Save as a group","summary":"Collect contributions into a shared pot and pay each member in turn.","headers":["savings"],"source":"// Collect contributions into a shared pot and pay each member in turn.\nprogram savings_base \"Save as a group\"\nuse savings\n\nobject pot \"Pot\" {\n  attach circle = savings.circle {\n    contribution: runtime, members: 2, starts: runtime\n    expose create as create_circle\n    expose disband as disband_circle\n    expose close as close_circle\n  }\n  attach membership = savings.membership {\n    circle: circle, member: actor\n    expose create as join\n    expose activate as activate_membership\n    expose withdraw as withdraw\n  }\n}\n\nexpose pot.membership.contribution.create as schedule_contribution\n"},
+  {"id":"wallet","title":"Offer prepaid credit","summary":"Let a customer add funds and reserve each spend before payment.","headers":["wallet"],"source":"// Let a customer add funds and reserve each spend before payment.\nprogram wallet_base \"Offer prepaid credit\"\nuse wallet\n\nobject balance \"Balance\" {\n  attach balance = wallet.balance {\n    holder: owner\n    expose create as create_balance\n    expose activate as activate_balance\n    expose topup as add_funds\n    expose withdraw as withdraw_funds\n    expose freeze as freeze_balance\n    expose unfreeze as unfreeze_balance\n    expose close as close_balance\n  }\n  attach spend = wallet.spend {\n    wallet: balance, payee: operator, holder: owner\n    expose create as create\n    expose reserve as reserve\n    expose pay as pay\n    expose cancel as cancel\n  }\n}\n"},
+];

package/src/bases.ts

@@ -0,0 +1,9 @@
+/** Neutral programs generated from bases/*.hsx. */
+export interface HsxBase {
+  id: string;
+  title: string;
+  summary: string;
+  headers: string[];
+  source: string;
+}
+export { bases } from "./bases-bundle.ts";

package/src/compile.ts

@@ -241,6 +241,24 @@ const automatic = (actor: UdlAction["actor"]) =>
   (actor !== null && typeof actor === "object" && "parent" in actor);
 const title = (name: string) =>
   name[0]!.toUpperCase() + name.slice(1).replaceAll("_", " ");
+/** Parties an instrument names itself: account owners, actors, move endpoints. */
+function namedParties(instrument: UdlInstrument): string[] {
+  const names = instrument.fields.flatMap((field) =>
+    field.type === "account" && typeof field.owner === "string"
+      ? [field.owner]
+      : [],
+  );
+  for (const action of Object.values(instrument.actions)) {
+    if (typeof action.actor === "object" && "party" in action.actor)
+      names.push(action.actor.party);
+    for (const move of action.moves) {
+      if (move.economics) names.push(move.economics.sourceParty);
+      for (const endpoint of "from" in move ? [move.from, move.to] : [])
+        if (endpoint.startsWith("party.")) names.push(endpoint.slice(6));
+    }
+  }
+  return names;
+}
 function entries(block: BlockExpr): Map<string, Expr> {
   const map = new Map<string, Expr>();
   for (const row of block.entries) {
@@ -283,6 +301,12 @@ function text(expr: Expr): string {
   );
 }
 function decimal(raw: string, scale: number, expr: Expr): string {
+  if (raw.startsWith("-"))
+    fail(
+      expr,
+      "literal cannot be negative",
+      "write a positive value; a move's from and to set its direction",
+    );
   const [whole = "", fraction = ""] = raw.split(".");
   if (!/^\d+$/.test(whole) || fraction.length > scale)
     fail(
@@ -389,6 +413,12 @@ function literal(expr: Expr, expectedType?: string): string | number | boolean {
   if (expr.kind === "text") return expr.value;
   if (expr.kind === "name" && ["true", "false"].includes(expr.value))
     return expr.value === "true";
+  if (expr.kind === "name" && expr.value === "runtime")
+    fail(
+      expr,
+      "this value is fixed when the program compiles, so it cannot be runtime",
+      "write a literal value",
+    );
   return fail(expr, "expected a literal", "write a typed constant");
 }
 
@@ -1453,7 +1483,7 @@ export function compile(
               )
                 fail(
                   v,
-                  `${param.key} is outside ${bounds.minimum}..${bounds.maximum}`,
+                  `value is outside ${bounds.minimum}..${bounds.maximum}`,
                   "choose a value inside the tunable's bounds",
                 );
             } catch (error) {
@@ -1524,7 +1554,7 @@ export function compile(
             "name the compared tunables",
           );
         const numericKind = (expr: Expr) =>
-          expr.kind === "name" && /^P/.test(expr.value)
+          expr.kind === "name" && /^P(?:\d|T)/.test(expr.value)
             ? "duration"
             : expr.kind;
         if (
@@ -1627,6 +1657,7 @@ export function compile(
         return lowered;
       };
       const fields: UdlField[] = [];
+      const boundaryReceipts = new Map<string, string>();
       const calculations: UdlCalculation[] = [];
       let currentAction: UdlAction | undefined;
       let currentActionName: string | undefined;
@@ -2070,6 +2101,38 @@ export function compile(
         actions: Object.create(null) as UdlInstrument["actions"],
         actionOrder: [],
       };
+      const actionTargets = new Set<string>();
+      const collectTargets = (block: BlockExpr): void => {
+        for (const entry of block.entries)
+          if (entry.key.startsWith("when "))
+            collectTargets(asBlock(entry.value));
+          else if (entry.key === "calculate")
+            for (const item of entry.value.kind === "list"
+              ? entry.value.items
+              : [entry.value]) {
+              const target =
+                item.kind === "block" ? entries(item).get("target") : undefined;
+              if (target) actionTargets.add(String(data(target)));
+            }
+      };
+      for (const row of decl.body.entries)
+        if (row.key.startsWith("action ")) collectTargets(asBlock(row.value));
+      // Instrument calculations run before every action, create included, so
+      // a fee or split calculates there only on an amount held from create.
+      const heldFromCreate = (amount: UdlValue): boolean => {
+        if (!("field" in amount)) return true;
+        const [root, name, ...rest] = amount.field.split(".");
+        const field = fields.find((item) => item.name === name);
+        return (
+          root === "self" &&
+          !rest.length &&
+          !!field &&
+          !actionTargets.has(name!) &&
+          (!field.optional ||
+            "value" in field ||
+            calculations.some((node) => node.target === name))
+        );
+      };
       for (const row of decl.body.entries.filter((e) =>
         e.key.startsWith("action "),
       )) {
@@ -2407,7 +2470,7 @@ export function compile(
           ...(actionSubject ? { subject: actionSubject } : {}),
         };
         authored.set(a, row.value);
-        const actionFeeCalculations: UdlCalculation[] = [];
+        const moveCalculations: UdlCalculation[] = [];
         for (const binding of boundaryBindings)
           if (
             !a.subject?.adapters.find((entry) => entry.binding === binding)
@@ -2447,12 +2510,28 @@ export function compile(
               const op = parts.has("operation")
                 ? String(data(parts.get("operation")!))
                 : "internal_transfer.create";
-              if (op === "internal_transfer.reserve" && !parts.has("capture"))
-                fail(
-                  move,
-                  "reserve needs a receipt field",
-                  "add capture: receipt_name",
-                );
+              if (op === "internal_transfer.reserve" && !parts.has("capture")) {
+                if (!parts.has("boundary"))
+                  fail(
+                    move,
+                    "reserve needs a receipt field",
+                    "add capture: receipt_name",
+                  );
+                const capture = `${name}Receipt`;
+                if (fields.some((field) => field.name === capture))
+                  fail(
+                    move,
+                    "boundary receipt name is already used",
+                    "name each reservation with an explicit capture",
+                  );
+                fields.push({ name: capture, type: "text", optional: true });
+                boundaryReceipts.set(name, capture);
+                parts.set("capture", {
+                  kind: "text",
+                  value: capture,
+                  span: move.span,
+                });
+              }
               if (
                 (op === "internal_transfer.post" ||
                   op === "internal_transfer.void") &&
@@ -2643,6 +2722,7 @@ export function compile(
                     );
                   let total = 0;
                   const pieces: UdlValue[] = [];
+                  const perAction = !heldFromCreate(val(amount));
                   for (const [index, [party, rate]] of shares.entries()) {
                     const recipient = resolve({
                       kind: "name",
@@ -2694,8 +2774,12 @@ export function compile(
                         "split field name conflicts",
                         "rename the move key",
                       );
-                    fields.push({ name: target, type: "money" });
-                    calculations.push(
+                    fields.push({
+                      name: target,
+                      type: "money",
+                      ...(perAction ? { optional: true } : {}),
+                    });
+                    (perAction ? moveCalculations : calculations).push(
                       index === shares.length - 1 && pieces.length
                         ? {
                             target,
@@ -2797,6 +2881,22 @@ export function compile(
                       "write seller: 1% or buyer: 1%",
                     );
                   const quoted = terms.get(paidBy)!;
+                  // An account the agreement owns holds only what was moved
+                  // into it, so a charge on top has nothing to come from.
+                  if (
+                    paidBy === "buyer" &&
+                    fields.some(
+                      (field) =>
+                        `self.${field.name}` === transfer.from &&
+                        field.type === "account" &&
+                        field.owner === "self",
+                    )
+                  )
+                    fail(
+                      quoted,
+                      `a buyer fee cannot come from \`${transfer.from.slice("self.".length)}\`, which holds only the moved amount`,
+                      "use a seller fee, which comes out of the held amount",
+                    );
                   const rate = quoted.kind === "capped" ? quoted.rate : quoted;
                   if (rate.kind !== "percent")
                     fail(
@@ -2805,11 +2905,7 @@ 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 perAction = !heldFromCreate(transfer.amount);
                   const derived = (
                     suffix: string,
                     label: string,
@@ -2828,7 +2924,7 @@ export function compile(
                       label,
                       ...(perAction ? { optional: true } : {}),
                     });
-                    (perAction ? actionFeeCalculations : calculations).push({
+                    (perAction ? moveCalculations : calculations).push({
                       ...calculation,
                       target,
                     } as UdlCalculation);
@@ -2960,8 +3056,8 @@ export function compile(
             }
           } else (a as unknown as Record<string, unknown>)[key] = data(expr);
         }
-        if (actionFeeCalculations.length)
-          a.calculate = [...(a.calculate ?? []), ...actionFeeCalculations];
+        if (moveCalculations.length)
+          a.calculate = [...(a.calculate ?? []), ...moveCalculations];
         if (attachmentInfo) {
           if (attachmentInfo.exposed.has(name)) {
             if (automatic(a.actor))
@@ -3060,6 +3156,14 @@ export function compile(
         inst.actions[name] = a;
         inst.actionOrder.push(name);
       }
+      for (const action of Object.values(inst.actions))
+        for (const move of action.moves)
+          if ("transfer" in move) {
+            const receipt = boundaryReceipts.get(
+              move.transfer.replace(/^self\./, ""),
+            );
+            if (receipt) move.transfer = `self.${receipt}`;
+          }
       if (attachmentInfo && !attachmentInfo.child)
         applyAttachmentEconomics(
           document,
@@ -3339,6 +3443,21 @@ export function compile(
           bindingDiagnostics.push(error.diagnostic);
           continue;
         }
+        // A business the instrument names itself binds like a parameter, so
+        // Build asks for it and the engine resolves its account and principal.
+        // programOperator and programTax are the company's own accounts.
+        for (const party of document.instruments
+          .slice(firstAttachedInstrument)
+          .flatMap(namedParties))
+          if (
+            document.parties[party]?.kind === "business" &&
+            party !== "programOperator" &&
+            party !== "programTax" &&
+            !Object.values(parties).some(
+              (binding) => "party" in binding && binding.party === party,
+            )
+          )
+            parties[party] ??= { party };
         const attachedInst = document.instruments.find((i) => i.id === instId);
         for (const createdInst of document.instruments
           .slice(firstAttachedInstrument)