@hyperscale0/hsx 5.3.0 → 5.4.1

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,uhIAAuhI,CAAC;IACtiI,CAAC,iBAAiB,EAAE,ooKAAooK,CAAC;IACzpK,CAAC,YAAY,EAAE,o8DAAo8D,CAAC;IACp9D,CAAC,eAAe,EAAE,g5vDAAg5vD,CAAC;IACn6vD,CAAC,eAAe,EAAE,+0GAA+0G,CAAC;IACl2G,CAAC,aAAa,EAAE,mvPAAmvP,CAAC;IACpwP,CAAC,iBAAiB,EAAE,m0PAAm0P,CAAC;IACx1P,CAAC,WAAW,EAAE,y1RAAy1R,CAAC;IACx2R,CAAC,eAAe,EAAE,w77CAAw77C,CAAC;IAC387C,CAAC,aAAa,EAAE,wrGAAwrG,CAAC;IACzsG,CAAC,YAAY,EAAE,8kMAA8kM,CAAC;IAC9lM,CAAC,YAAY,EAAE,m6DAAm6D,CAAC;CACp7D,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,WAAW,EAAE,2oKAA2oK,CAAC;IAC1pK,CAAC,iBAAiB,EAAE,+rMAA+rM,CAAC;IACptM,CAAC,YAAY,EAAE,6jGAA6jG,CAAC;IAC7kG,CAAC,eAAe,EAAE,0j1DAA0j1D,CAAC;IAC7k1D,CAAC,eAAe,EAAE,ouJAAouJ,CAAC;IACvvJ,CAAC,aAAa,EAAE,4hSAA4hS,CAAC;IAC7iS,CAAC,iBAAiB,EAAE,ilSAAilS,CAAC;IACtmS,CAAC,WAAW,EAAE,kjUAAkjU,CAAC;IACjkU,CAAC,eAAe,EAAE,649CAA649C,CAAC;IACh69C,CAAC,aAAa,EAAE,mtJAAmtJ,CAAC;IACpuJ,CAAC,YAAY,EAAE,ssPAAssP,CAAC;IACttP,CAAC,YAAY,EAAE,kxFAAkxF,CAAC;CACnyF,CAAC,CAAC"}

package/dist/src/version.d.ts

@@ -1,3 +1,2 @@
-export declare const HSX_VERSION = "5.3.0";
-export declare const HSX_TARGET_UDL_VERSION = 4;
+export declare const HSX_VERSION = "5.4.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/src/version.js

@@ -1,3 +1,2 @@
-export const HSX_VERSION = "5.3.0";
-export const HSX_TARGET_UDL_VERSION = 4;
+export const HSX_VERSION = "5.4.1";
 //# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/docs/README.md

@@ -1,18 +1,107 @@
-# HSX 5.0.1
+# HSX
 
-A program declares business objects and financial instruments. Objects contain
-optional metadata. Attachments expose named actions against an object.
+HSX composes a company's objects, agreements and actions into a typed program.
+A repair approval can change state without moving money. A rental can collect a
+deposit and refund it under declared rules. Headers supply reusable instruments;
+you can also write an instrument with its own fields, lifecycle and actions.
+The compiler emits UDL, the Universal Domain Language contract an executor reads.
+It does not run the business or move money. This release supports SAR only.
+
+## First program
+
+The package supplies the `hsx` executable. Save this as `lesson.hsx`:
 
 ```hsx
-program cars "Cars"
-use escrow
-object car "Cars" {
- fields { make: text, model: text, year: integer }
- columns: [make, model, year]
- attach sale = escrow.hold { payer: actor, payee: owner, expose fund as sell }
+program tutoring "Tutoring studio"
+use money
+object lesson "Lesson" {
+  fields { student: text }
+  columns: [student]
+  attach payment = money.transfer {
+    payer: owner, payee: operator, amount: 150 SAR
+    expose create as book_lesson
+    expose pay as pay_for_lesson
+    expose cancel as cancel_lesson
+  }
 }
 ```
 
+An object is the business record. An instrument holds an agreement's state and
+money rules. An attachment connects the instrument to an object kind. A tunable
+is a header parameter, such as `amount`, fixed by this program. An exposed action
+is a public name for an instrument action. Exposing it does not grant permission.
+
+```sh
+hsx check lesson.hsx
+hsx build lesson.hsx --out lesson.udl.json
+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
+`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
+agreement. Call `pay_for_lesson` on that agreement to move 150 SAR from its bound
+owner to the operator. Object creation alone creates no agreement. Object
+metadata such as `student` is optional until an action requires it. Account IDs
+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
+`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
+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                                               |
+
+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
+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.
+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.
+
+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
+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
+parties, object actions, funded accounts and a saved Product Build. A Build is the
+frozen contract and configuration used by its agreements. Existing agreements
+keep that Build when the program changes. The package includes no local money
+executor. Compilation cannot establish balances, permissions or provider readiness.
+
+## Objects, metadata and parties
+
 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.
@@ -42,6 +131,8 @@ Creation accepts `{}`. Every normalized field, including adapter requirements,
 is optional at creation. Only a named action requires its subject metadata.
 Use `attach` inside the object block to configure its financial instruments.
 
+## Headers and tunables
+
 The header defines the available policies. The company chooses percentages, amounts, durations,
 parties and typed references. `funds: sale` links the stored records through the
 library's declared reference type. References can name a child, such as
@@ -49,8 +140,16 @@ library's declared reference type. References can name a child, such as
 objects of type T. `on: [plan_3, plan_6]` creates one late-charge or collections
 policy. Its references can point into either plan; selections can span both.
 A plain `ref<T>` accepts one object only.
+Tunable constructors are `enum(choices)` and `integer(minimum, maximum)`.
+Other constructors, including `party(business)` and bounded `money(...)`, are
+rejected as tunable types. A default selector such as `payer: party = party(person)`
+is different: its type is plain `party`, and the call chooses a default binding.
+Use explicit `payer: owner` or `payer: actor` bindings when the participant comes
+from the object or session.
 Imports are `use header`; there are no file imports, macros or executable strings.
 
+## Values and money
+
 Amounts use `750 SAR`; percentages use `2.5%`; durations use `48h`, `3d`, or `1w`.
 Dates use `2026-11-28` or a timestamp with an explicit offset. Money has at most two
 decimal places and percentages at most two. The compiler uses integer minor units
@@ -78,10 +177,6 @@ same book and key within the Product. Providers remain outside parties.
 A missing binding refuses before money moves. Reference paths such as
 `self.cover.insurer` use the referenced agreement's account.
 
-Insurance collection credits the premium to the operator, then moves the premium
-net of commission to the insurer account. Refunds reverse those two portions.
-Claims reserve from the cover's insurer account. These moves record ledger money;
-external confirmation still needs the boundary protocol.
 `account(buyer, claim, contra, "debt")` declares the borrower's claim contra account.
 Provider confirmation belongs on a reserved move with `boundary adapter`,
 followed by instruction-bound evidence and a post or void. External account
@@ -111,6 +206,14 @@ The four transfer instructions are create, reserve, post and void under
 reversed or voided status. Voided means a released reservation. Settled means
 provider confirmation, not an internal account balance change.
 
+## Authored instruments and actions
+
+An action is the business instruction: its actor, state, requirements and effects
+define when it is valid. The executor still checks those conditions on each call.
+The four transfer instructions below that action are its money effects. There is
+no general-purpose `instruction` declaration; `instruction` in an evidence clause
+binds external evidence to a captured boundary instruction.
+
 For a new record type, declare `instrument name { fields { ... } lifecycle { ... }
 action create { ... } }`. Fields are `money`, `account of buyer`, `ref<order>`,
 `date`, `duration`, `text`, `integer`, `percent`, `boolean`, `enum(a, b)` or
@@ -142,7 +245,7 @@ maxAge 1d` requires a recent completed provider check.
 `capture`, `key` and `boundary` modifiers describe a move. `boundary` applies
 only to reservations. Fees settle with create moves, never reservations. Repeated clauses keep
 their declaration order. The JSON-like clause form remains accepted and lowers
-to the same [UDL clauses](../../udl/spec/README.md).
+to the same [UDL clauses](https://github.com/hyperscale0/hyperscale-udl/blob/main/spec/README.md).
 They cannot add kernel instructions. `at(list, position)` reads a dated list;
 `aggregate(selection, "amount")` sums selected money; `ratio(amount, weight, total)`
 floors a weighted share. `records` declares child types. `invoke` can create a child
@@ -237,25 +340,26 @@ unsupported percentage semantics and repair. They do not change the tunable type
 UDL refusals retain their UDL codes. A terminal-money refusal includes the owned
 account and the prover's action path in related diagnostic information.
 
-Build with `hsx build company.hsx --out company.udl.json`; check with
-`hsx check company.hsx`; print instruction counts with `hsx cost company.hsx`.
-Print the compiler-owned object manifest with `hsx headers --json`.
-The compiler API is `compile(source)`. A valid result contains `artifacts.document`,
-`costManifest` and source origins. Instruction counts are not bank tariffs or a
-promise of provider execution cost.
+## Instruction cost
 
-The [header inventory](headers.md) is generated from the declarations. The
-[object example](../examples/library.hsx) shows authenticated role bindings.
-The [playground](../playground/index.html) compiles locally in the browser.
+`hsx cost company.hsx` reports `transfers`, `accounts` and `invocations` per
+instrument action after lowering. Transfers count declared move instructions,
+including reserve, post and void. Accounts count self-owned accounts created by
+`create`, not every party account. Bounded invocations include child costs up to
+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.
 
-## Financing attachments
+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
+prices. The executor's tariff supplies commercial prices and actual usage.
 
-Financing retains its authored borrower and portfolio limits. Bind every party
-parameter to a subject role, declared business or staff party with a supported
-role, and link the existing escrow and limits attachments.
-No limit is inferred from object metadata.
+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.
 
-See the complete [financing object example](../examples/library.hsx).
+The [header inventory](headers.md) is generated from the declarations. The
+[object example](../examples/library.hsx) shows authenticated role bindings.
+The [playground](../playground/index.html) compiles locally in the browser.
 
 ## Standard-library behavior
 
@@ -271,14 +375,61 @@ adapters are bound, participants have funds, or the flow can finish.
 | `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.                                                                                                             |
 | `travel.booking`                           | From `deposit_paid` or `paid`, early cancellation returns the full held balance, middle returns held balance minus deposit, and late has no buyer refund transfer. State, time and balance requirements still apply. A deposit-only early cancellation refunds the deposit; a deposit-only middle cancellation refunds zero. |
-| `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 positions.                                                                                                                                                               |
+| `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.                                                                                                                                                                                                                                                       |
 
+The financing, collections and reporting samples compose loan agreements; they
+do not supply a complete public repayment path. Insurance and travel also need
+premium-slice records and actions. Savings needs dated contribution records.
+Create aliases in these samples cover the root attachments, not every child
+record. Read each header's creation and lifecycle requirements before execution.
+
 The [lending sample](../examples/lending.hsx) exposes limit approvals, funding and
 commitment creation, and cash prepare/distribute actions. Its repayment and share
 child actions still lack a public execution path. It is a composition example,
 not a complete public repayment flow. Callers still need dates, agreement inputs,
 funded wallets, eligible settlements and the distribution's share records.
+
+## Checkout and reversals
+
+For financed checkout, expose `installments.collect_down_payment` after `create`
+and `sign`. It credits the linked pending escrow with the missing down payment.
+It does not disburse principal or activate the plan. The later `disburse` action
+uses that credit before collecting any remainder. Borrower-directed financing
+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
+`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.
+
+Expose `late_charge.create` to create an assessment with matching plan, slice
+and borrower. Only that existing assessment can reach clock-owned `assess` after
+grace. A payment can collect part of a fine without settling the rest. A recovery
+cost assessment is a separate record.
+
+## Separate payments and states
+
+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.
+
+A booking cancellation refunds only its own held cash. Expose `cover.cancel`
+separately for eligible premium refunds before the paid period starts. Active
+and expired premium periods are excluded. A card transaction needs a captured
+authorization and its own record before refund, but no authorization-expiry wait.
+
+A savings membership becomes `received` after its pot payout. Its contribution
+records become `paid` independently. Future contributions can remain pending
+after the member receives the pot; paying a contribution does not advance their
+payout seat. Late contributions remain eligible while the membership is
+`active` or `received` and the circle is `active`. These guards do not promise
+scheduler retries or permit a payout larger than the available cash.

package/docs/examples.md

@@ -13,6 +13,7 @@ Each file is an authored program. Object creation enters no agreement; an attach
 | [Financed car sales](../examples/library.hsx) | escrow, financing | A minimal financed car sale connects escrow to a three-instalment plan and lending limits. |
 | [Freelance marketplace](../examples/marketplace.hsx) | marketplace, escrow | Freelancers publish offers and clients place orders with funds held until work is accepted. |
 | [Tutoring studio](../examples/money.hsx) | money | A tutoring studio collects a fixed fee for each lesson and can cancel unpaid bookings. |
+| [Equipment rental](../examples/rental-deposit.hsx) |  | A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee. On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR. |
 | [Repair approvals](../examples/repair-approval.hsx) |  | A repair shop records inspection and approval evidence before it can complete a job. |
 | [Equipment loan reports](../examples/reporting.hsx) | reporting, financing | An equipment lender keeps an ageing report over its financed purchases and recorded repayments. |
 | [Savings circle](../examples/savings.hsx) | savings | Six members contribute to a shared pot and receive it in their agreed calendar order. |

package/docs/headers.md

@@ -29,7 +29,7 @@ Bind party parameters to owner, actor, operator or declared parties. Configure d
 | lending.round | `borrower: party`, `plan: ref<financing.installments> = object(financing.installments)`, `operator: party = programOperator`, `minimum_ticket: money = 100 SAR`, `investor_cap: percent = 20%`, `commitments: ref<lending.commitment> = object(lending.commitment)` |
 | lending.commitment | `round: ref<lending.round>`, `wallet: ref<wallet.balance>`, `investor: party = party(person)` |
 | lending.distribution | `round: ref<lending.round>`, `receipt: ref`, `commitments: ref<lending.commitment> = object(lending.commitment)`, `mode: enum(cash, loss) = cash`, `residual_to: party = programOperator`, `operator: party = programOperator`, `fee: percent = 1%`, `tax: percent = 15%` |
-| insurance.cover | `holder: party`, `adapter: text`, `commission: percent = 0%`, `covers: ref`, `premium: money = runtime` |
+| insurance.cover | `holder: party`, `adapter: text`, `commission: percent = 0%`, `broker: party = programOperator`, `covers: ref`, `premium: money = runtime` |
 | insurance.claim | `cover: ref<insurance.cover>`, `inspector: party` |
 | collections.case | `on: ref<financing.installments>[]`, `agency: party`, `capital: party = programOperator`, `overdue: duration = 3d`, `fee: percent = 20%` |
 | collections.contact | `case: ref<collections.case>[]`, `agency: party`, `max_contacts: integer = 10`, `window: duration = 30d`, `contact_from: integer(0, 23) = 8`, `contact_until: integer(1, 23) = 20`, `timezone: text = "Asia/Riyadh"`; contact_from less_than contact_until |

package/examples/cards.hsx

@@ -7,23 +7,27 @@ object employee "Employee card" {
   fields { employeeName: text, department: text }
   columns: [employeeName, department]
   attach holder = cards.cardholder {
+    expose create as create_holder
     holder: owner
     expose activate as activate_employee
     expose suspend as suspend_employee
   }
   attach card = cards.card {
+    expose create as create_card
     holder: holder, spend_limit: 5000 SAR
     expose activate as activate_card
     expose freeze as freeze_card
     expose unfreeze as unfreeze_card
   }
   attach payment = cards.authorization {
+    expose create as create_payment
     card: card, merchant: supplier
     expose approve as approve_payment
     expose capture as capture_payment
     expose reverse as reverse_payment
   }
   attach receipt = cards.transaction {
+    expose create as create_receipt
     authorization: payment
     expose refund as refund_payment
   }

package/examples/collections.hsx

@@ -7,9 +7,10 @@ party agency: business
 object facility "Business loan" {
   fields { businessName: text, purpose: text, price: money }
   columns: [businessName, purpose, price]
-  attach allowance = financing.limits { borrower: owner, per_borrower: 100000 SAR }
-  attach budget = financing.portfolio_limit { limit: 2000000 SAR }
+  attach allowance = financing.limits { expose create as create_allowance, borrower: owner, per_borrower: 100000 SAR }
+  attach budget = financing.portfolio_limit { expose create as create_budget, limit: 2000000 SAR }
   attach loan = financing.installments {
+    expose create as create_loan
     borrower: owner, capital: operator
     months: 12, profit: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
@@ -17,12 +18,14 @@ object facility "Business loan" {
     expose disburse as release_loan
   }
   attach recovery = collections.case {
+    expose create as create_recovery
     on: loan, agency: agency
     expose assign as assign_case
     expose recover as recover_payment
     expose recall as recall_case
   }
   attach contact = collections.contact {
+    expose create as create_contact
     case: recovery, agency: agency
   }
 }

package/examples/escrow.hsx

@@ -11,6 +11,7 @@ object device "Device" {
   }
   columns: [model, condition, price]
   attach sale = escrow.hold {
+    expose create as create_sale
     payer: actor, payee: owner
     expose fund as pay_for_device
     expose deliver as confirm_delivery
@@ -18,5 +19,6 @@ object device "Device" {
     expose dispute as report_problem
     expose verify_return as verify_return
     expose refund as refund_buyer
+    expose cancel as cancel_sale
   }
 }

package/examples/financing.hsx

@@ -6,14 +6,17 @@ object enrolment "Enrolment" {
   fields { student: text, course: text, price: money }
   columns: [student, course, price]
   attach allowance = financing.limits {
+    expose create as create_allowance
     borrower: owner, per_borrower: 12000 SAR
     expose approve as approve_student
   }
   attach budget = financing.portfolio_limit {
+    expose create as create_budget
     limit: 500000 SAR
     expose approve as approve_budget
   }
   attach tuition = financing.installments {
+    expose create as create_tuition
     borrower: owner, capital: operator
     months: 3, profit: 0%, disburse_to: borrower
     limits: allowance, portfolio: budget

package/examples/insurance.hsx

@@ -8,16 +8,19 @@ object device "Insured device" {
   fields { model: text, serialNumber: text, purchaseDate: date }
   columns: [model, serialNumber, purchaseDate]
   attach purchase = money.transfer {
+    expose create as create_purchase
     payer: owner, payee: operator
     expose pay as pay_for_device
   }
   // Bind device_insurer to an ADL adapter before creating cover. Premiums net of commission go to its account.
   attach protection = insurance.cover {
+    expose create as create_protection
     holder: owner, adapter: "device_insurer", 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
     expose approve as approve_claim
     expose deny as deny_claim

package/examples/lending.hsx

@@ -9,14 +9,17 @@ object business "Business funding" {
   fields { businessName: text, purpose: text, price: money }
   columns: [businessName, purpose, price]
   attach allowance = financing.limits {
+    expose create as create_allowance
     borrower: owner, per_borrower: 100000 SAR
     expose approve as approve_borrower
   }
   attach budget = financing.portfolio_limit {
+    expose create as create_budget
     limit: 2000000 SAR
     expose approve as approve_budget
   }
   attach loan = financing.installments {
+    expose create as create_loan
     borrower: owner, capital: operator
     months: 12, profit: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
@@ -24,6 +27,7 @@ object business "Business funding" {
     expose disburse as release_loan
   }
   attach investor_balance = wallet.balance {
+    expose create as create_investor_balance
     holder: actor
     expose activate as open_wallet
     expose topup as add_funds
@@ -39,6 +43,7 @@ object business "Business funding" {
     expose withdraw as withdraw_investment
   }
   attach returns = lending.distribution {
+    expose create as create_returns
     round: funding, receipt: loan.settlement
     expose prepare_cash as prepare_returns
     expose distribute_cash as distribute_returns

package/examples/library.hsx

@@ -4,9 +4,9 @@ use escrow
 use financing
 object car "Cars" {
  fields { make: text, model: text, year: integer }
- attach sale = escrow.hold { payer: actor, payee: owner, expose fund as sell }
- attach limits = financing.limits { borrower: actor, per_borrower: 60000 SAR }
- attach ceiling = financing.portfolio_limit { limit: 1500000 SAR }
+ attach sale = escrow.hold { expose create as create_sale, payer: actor, payee: owner, expose fund as sell }
+ attach limits = financing.limits { expose create as create_limits, borrower: actor, per_borrower: 60000 SAR }
+ 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

package/examples/marketplace.hsx

@@ -7,20 +7,26 @@ object project "Project" {
   fields { brief: text, deliverable: text, price: money }
   columns: [brief, deliverable, price]
   attach offer = marketplace.listing {
+    expose create as create_offer
     seller: owner
     expose publish as publish_offer
     expose withdraw as withdraw_offer
   }
   attach order = marketplace.order {
+    expose create as create_order
     listing: offer, buyer: actor
     expose commit as place_order
     expose fulfill as finish_order
   }
   attach payment = escrow.hold {
+    expose create as create_payment
     payer: actor, payee: owner
     expose fund as fund_project
     expose deliver as submit_work
     expose accept as accept_work
     expose dispute as dispute_work
+    expose verify_return as verify_return
+    expose refund as refund_client
+    expose cancel as cancel_payment
   }
 }

package/examples/money.hsx

@@ -10,6 +10,7 @@ object lesson "Lesson" {
   }
   columns: [student, tutor, startsAt]
   attach payment = money.transfer {
+    expose create as create_payment
     payer: actor, payee: operator, amount: 150 SAR
     expose pay as pay_for_lesson
     expose cancel as cancel_payment

package/examples/rental-deposit.hsx

@@ -0,0 +1,60 @@
+// A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee.
+// On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR.
+program equipment_rental "Equipment rental"
+party renter: business
+
+// Program-local instruments have fixed terms and parties, not tunable parameters.
+instrument deposit {
+  summary: "Hold a rental deposit, then return it less any fixed late fee."
+  fields {
+    renter: account of renter
+    held: account of self
+    amount: money = 1000 SAR
+    lateFee: money = 50 SAR
+    dueAt: date
+    refund: money?
+  }
+  lifecycle { states: [pending, funded, returned, cancelled], initial: pending }
+  action create {
+    actor: { party: renter }
+    requires self.dueAt > self.now
+  }
+  action fund {
+    from: pending, to: funded, actor: { party: renter }
+    deadline: { at: self.dueAt }
+    moves self.amount from self.renter to self.held
+  }
+  action return_on_time {
+    from: funded, to: returned, actor: { party: programOperator }
+    deadline: { at: self.dueAt }
+    subject { returnReference: text }
+    moves self.held.balance from self.held to self.renter
+  }
+  action return_late {
+    from: funded, to: returned, actor: { party: programOperator }
+    due: { at: self.dueAt }
+    subject { returnReference: text }
+    calculate: [{ target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.lateFee }] }]
+    moves self.lateFee from self.held to programOperator
+    moves self.refund from self.held to self.renter
+  }
+  action cancel { from: pending, to: cancelled, actor: { party: renter } }
+}
+
+object rental "Equipment rental" {
+  fields { equipment: text }
+  columns: [equipment, dueAt]
+  attach security = deposit {
+    expose create as agree_rental
+    expose fund as pay_deposit
+    expose return_on_time as return_equipment
+    expose return_late as return_equipment_late
+    expose cancel as cancel_rental
+  }
+}
+
+hide deposit.create
+hide deposit.fund
+hide deposit.return_on_time
+hide deposit.return_late
+hide deposit.cancel

package/examples/repair-approval.hsx

@@ -29,6 +29,7 @@ object repair "Repair" {
   fields { item: text, problem: text }
   columns: [item, problem]
   attach review = assessment {
+    expose create as create_review
     expose inspect as inspect_repair
     expose approve as approve_repair
     expose reject as reject_repair

package/examples/reporting.hsx

@@ -7,19 +7,22 @@ object purchase "Equipment loan" {
   fields { businessName: text, equipment: text, price: money }
   columns: [businessName, equipment, price]
   attach allowance = financing.limits {
+    expose create as create_allowance
     borrower: owner, per_borrower: 200000 SAR
     expose approve as approve_business
   }
   attach budget = financing.portfolio_limit {
+    expose create as create_budget
     limit: 5000000 SAR
     expose approve as approve_budget
   }
   attach loan = financing.installments {
+    expose create as create_loan
     borrower: owner, capital: operator
     months: 12, profit: 6%, disburse_to: borrower
     limits: allowance, portfolio: budget
     expose sign as sign_purchase_loan
     expose disburse as fund_purchase
   }
-  attach reports = reporting.portfolio { on: loan }
+  attach reports = reporting.portfolio { expose create as create_reports, on: loan }
 }

package/examples/savings.hsx

@@ -6,11 +6,13 @@ object group "Savings group" {
   fields { groupName: text, purpose: text }
   columns: [groupName, purpose]
   attach circle = savings.circle {
+    expose create as create_circle
     contribution: 500 SAR, members: 6, starts: 2027-01-01
     expose disband as disband_circle
     expose close as close_circle
   }
   attach membership = savings.membership {
+    expose create as create_membership
     circle: circle, member: actor
     expose activate as confirm_membership
     expose withdraw as leave_circle