@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/docs/reference/std/threshold_pool.md

@@ -0,0 +1,47 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+
+# threshold_pool
+
+Source: [`std/settlements/threshold_pool.hsx`](../../../std/settlements/threshold_pool.hsx)
+
+## Export
+
+`threshold_pool<C>`
+
+## Parameters
+
+- `contributor: optional<party>`
+- `beneficiary: optional<party>`
+- `target: money<C>`
+- `commitment: money<C>`
+- `max_contributors: optional<integer>`
+- `close_by: date`
+- `close_policy: optional<text>`
+- `overfund_policy: optional<text>`
+- `cancel_policy: optional<text>`
+- `fail_policy: optional<text>`
+- `beneficiary_account: optional<account<C>>`
+- `memo: optional<text>`
+- `contribution_instrument: optional<block>`
+- `wording: optional<block>`
+
+## Decision ports
+
+None.
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                   |
+| ---------- | ------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `activate` | `due`, `moves`, `steps`, `summary`                |
+| `fail`     | `due`, `moves`, `steps`, `summary`                |
+| `close`    | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `moves`, `steps`, `summary`  |
+| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
+| `collect`  | `agent description`, `moves`, `steps`, `summary`  |
+| `refund`   | `agent description`, `moves`, `steps`, `summary`  |
+| `create`   | `agent description`, `examples`, `moves`, `steps` |
+| `activate` | `due`, `examples`, `moves`, `steps`               |
+| `fail`     | `due`, `examples`, `moves`, `steps`               |
+| `close`    | `agent description`, `examples`, `moves`, `steps` |

package/docs/reference/std/weighted_distribution.md

@@ -0,0 +1,39 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+
+# weighted_distribution
+
+Source: [`std/settlements/weighted_distribution.hsx`](../../../std/settlements/weighted_distribution.hsx)
+
+## Export
+
+`weighted_distribution<C>`
+
+## Parameters
+
+- `source: party`
+- `recipient: party`
+- `amount: money<C>`
+- `record_at: date`
+- `weight: optional<money<C>>`
+- `max_recipients: optional<integer>`
+- `snapshot: optional<condition>`
+- `rounding_policy: optional<text>`
+- `withholding_policy: optional<text>`
+- `correction_policy: optional<text>`
+- `flat: optional<block>`
+- `id_prefix_override: optional<text>`
+
+## Decision ports
+
+- `snapshot`
+
+## Actions and clauses
+
+| Action     | Clauses lowered                                                                                   |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `snapshot` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `payout`   | `agent description`, `computes distribute`, `moves`, `steps`, `summary`                           |
+| `create`   | `agent description`, `moves`, `requires refs`, `steps`, `summary`                                 |
+| `payout`   | `computes distribute`, `due`, `moves`, `steps`, `summary`                                         |

package/docs/reference/types.md

@@ -0,0 +1,20 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+
+# Types
+
+HSX checks types before it emits UDL. Money and account values carry a currency parameter, and no implicit currency conversion exists.
+
+| Kind        | Meaning                                                              |
+| ----------- | -------------------------------------------------------------------- |
+| `account`   | A currency-indexed ledger account reference.                         |
+| `boolean`   | A compile-time or stored true or false value.                        |
+| `bps`       | An integer basis-point value.                                        |
+| `condition` | A declared decision port.                                            |
+| `date`      | A stored date-time string checked by UDL.                            |
+| `integer`   | A bounded whole number.                                              |
+| `money`     | A currency-indexed minor-unit amount.                                |
+| `party`     | A declared program party.                                            |
+| `percent`   | An exact percentage with basis-point precision.                      |
+| `ref`       | A typed reference to another instrument.                             |
+| `text`      | A finite string value.                                               |
+| `unknown`   | An internal checker result that source must resolve before lowering. |

package/docs/reference/udl-output.md

@@ -0,0 +1,13 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+
+# UDL output
+
+An accepted compile returns three artifacts.
+
+| Artifact       | Contents                                                                            |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `document`     | The canonical UDL object. Serialize it with `serializeUdl` from `@hyperscale0/udl`. |
+| `originMap`    | Canonical UDL paths mapped to authored HSX spans.                                   |
+| `costManifest` | The deterministic manifest pinned to the supplied rate card.                        |
+
+Canonical UDL sorts object keys, preserves array order, uses two-space JSON indentation, and ends with one line feed.

package/docs/sessions/2026-09-02-two-instruments.hsx

@@ -0,0 +1,21 @@
+program juniper_forge_contract "Juniper Forge contract"
+import { instant_transfer, scheduled } from "std/settlements"
+
+party samira_nassar: person
+party juniper_forge_interiors: business
+
+settlement concept_fee = instant_transfer {
+  payer: samira_nassar
+  payee: juniper_forge_interiors
+  amount: conceptFee: money(SAR)
+  fees { samira_nassar: 1% }
+}
+
+settlement build_installments = scheduled {
+  payer: samira_nassar
+  payee: juniper_forge_interiors
+  amount: buildPrice: money(SAR)
+  count: 3
+  every: P30D
+  first_due: firstBuildPaymentAt
+}

package/docs/sessions/2026-09-02-two-instruments.md

@@ -0,0 +1,41 @@
+# Two-instrument reading session, 2026-09-02
+
+The reader worked only inside the HSX public export. It read the README, skill,
+guide, grammar, types, and generated standard-library pages.
+
+## First run
+
+Attempts: 3. Result: environment refusal before language checking.
+
+```text
+$ hsx check reading-test.hsx
+zsh: command not found: hsx
+exit 127
+
+$ npm exec --offline --package=. -- hsx check reading-test.hsx
+sh: hsx: command not found
+exit 127
+
+$ bun run src/cli.ts check reading-test.hsx
+SyntaxError: Export named 'udlEffectKinds' not found in the cached UDL beta package
+exit 1
+```
+
+The public docs did not distinguish the installed command from the source
+checkout command. The provisional pre-publication clone also resolved an old
+UDL package. The README and first-program guide now name the exact checkout
+command. The rerun used the local UDL rc.1 package already proved by the
+exporter.
+
+## Rerun after the docs repair
+
+Attempts: 1. Result: accepted with no diagnostics.
+
+```text
+$ bun run bin/hsx.ts check reading-test.hsx
+[no diagnostics]
+exit 0
+```
+
+The accepted program is in
+[`2026-09-02-two-instruments.hsx`](./2026-09-02-two-instruments.hsx).

package/examples/01-first-program/README.md

@@ -0,0 +1,45 @@
+# 1 · Your first program
+
+[`tip-jar.hsx`](./tip-jar.hsx) is the smallest HSX program that moves money.
+A listener tips a podcast host and the money goes straight through.
+
+```bash
+hsx check tip-jar.hsx     # prints nothing, exits 0
+hsx build tip-jar.hsx     # the compiled IR
+```
+
+## The four things in the file
+
+**`program tip_jar "Tip jar"`** names the company. Exactly one per file. The
+name is `snake_case` and becomes the IR document's `product`; the title is
+optional and is what people read.
+
+**`import { instant_transfer } from "std/settlements"`** brings in one settlement brick.
+`"settlement"` is the only module there is, and it holds seventeen settlement
+bricks. A brick you have not imported cannot be instantiated, so the imports
+at the top tell you what shape of company this is before you read a line of it.
+
+**`party listener: person`** declares who is involved. A party is a `person`
+or a `business`. Both are needed here: `instant_transfer` names a payer and a
+payee, and both must be declared parties.
+
+**`settlement tip = instant_transfer { … }`** is the money. `payer` and
+`payee` name declared parties; `amount: tipAmount: money(SAR)` declares a
+field the instance stores, called `tipAmount`, holding an amount in SAR.
+
+That doubled colon reads oddly the first time. The archetype's parameter is
+`amount`; its value is a typed binding, `tipAmount: money(SAR)`, which names
+the field AND its type. You choose the field name because it shows up in the
+generated API, and `amount` is HSX's word, not your product's.
+
+## What it compiles to
+
+One instrument with one action that moves money, and one money event, `tip_pay_1`.
+Notice what is NOT there: no escrow flag, because nothing is held. Compare
+that with example 2, where the money waits for someone to decide.
+
+## Try breaking it
+
+Change `payee: host` to `payee: hosts` and run `hsx check` again. The
+compiler tells you there is no party named `hosts`, and points at the column
+where you wrote it. That is example 3's whole subject.

package/examples/01-first-program/tip-jar.hsx

@@ -0,0 +1,17 @@
+// The smallest HSX program that moves money.
+//
+// A listener tips a podcast host. Nothing is held, nobody has to decide
+// anything, and the money goes straight through.
+
+program tip_jar "Tip jar"
+
+import { instant_transfer } from "std/settlements"
+
+party listener: person
+party host:     business
+
+settlement tip = instant_transfer {
+  payer:  listener
+  payee:  host
+  amount: tipAmount: money(SAR)
+}

package/examples/02-imports-and-archetypes/README.md

@@ -0,0 +1,96 @@
+# 2 · Imports, settlement bricks, and the port
+
+[`photo-booth.hsx`](./photo-booth.hsx) is a photo-booth rental company. The
+renter pays up front, but the money does not reach the company until the booth
+is delivered.
+
+```bash
+hsx check photo-booth.hsx
+hsx build photo-booth.hsx --out ir.json
+```
+
+## Holding money changes everything
+
+`instant_transfer` in example 1 had no custody: money left the payer and
+arrived at the payee in one step. `held_payment` puts the money in the
+settlement's own escrow and holds it there until something says to let go.
+That "something" is the interesting part.
+
+```hsx
+release: port confirm_delivery
+```
+
+A **port** is the typed seam where the tenant's own backend decides. HSX does
+not model delivery, and the platform has no way to know whether a booth showed
+up. So the language does not pretend: it declares who may answer the question
+and what the answer looks like, and the answer comes from outside.
+
+```hsx
+port confirm_delivery {
+  allowed: [company]
+  shape {
+    boothId:     id(booth)
+    deliveredOn: date
+  }
+}
+```
+
+`allowed` is required and must name declared parties. `shape` is optional; its
+field types are `text`, `date`, `id(<asset>)`, and `money(<CUR>)`.
+
+## Assets are the things, not the money
+
+```hsx
+asset booth: good { title_transfer: off_platform }
+```
+
+`title_transfer: off_platform` records that ownership of the booth changes
+hands outside the platform. Money stays on-platform; this flag describes the
+object.
+
+## Fees have a side, and the side matters
+
+```hsx
+fees { renter: 1%, company: 3% }
+```
+
+Those two percentages behave completely differently, and the difference is
+fixed by the compiler, not by you:
+
+- The **payer-side** fee (`renter: 1%`) is charged **on top** at funding and
+  moves renter → platform directly. It never enters escrow, so no exit
+  refunds it.
+- The **payee-side** fee (`company: 3%`) is **carved out** of the amount at
+  release. The renter pays the booking fee, and the company receives 97% of it.
+
+## Cancellation splits to the basis point
+
+```hsx
+on_cancel(funded) { renter: 90%, company: 10% }
+```
+
+The shares must total exactly 100%. Not 99.99%, not 100.01%. A 0% share is
+refused outright: drop the party from the block instead of promising them
+nothing.
+
+## Where the piece fields come from
+
+Look at the compiled instrument's `fields` and you will find `piece1Amount`,
+`piece2Amount`, `piece3Amount` next to `bookingFee`, plus a `partitions`
+clause proving they sum to it exactly.
+
+Release pays out 97/3 (company, platform). Cancellation pays out 90/10
+(renter, company). The compiler cuts the amount at every boundary either exit
+cares about, which lands on 90 / 7 / 3, and then every exit is a whole number
+of pieces:
+
+| Piece                | Release  | Cancel  |
+| -------------------- | -------- | ------- |
+| `piece1Amount` (90%) | company  | renter  |
+| `piece2Amount` (7%)  | company  | company |
+| `piece3Amount` (3%)  | platform | company |
+
+Each piece is `floor(bookingFee × bps / 10000)` in minor units, and the
+division remainder goes to `piece1Amount`. Nothing rounds; nothing is lost.
+This is what "the runtime does the plumbing" actually means, and it is why the
+source is 20 lines instead of a lifecycle table.

package/examples/02-imports-and-archetypes/photo-booth.hsx

@@ -0,0 +1,37 @@
+// Imports, archetypes, and the decision port.
+//
+// A photo-booth rental company. The renter pays up front, but the money sits
+// in escrow until the booth is delivered. The company's own backend answers
+// "was it delivered?" through the `confirm_delivery` port; nothing on the
+// platform guesses. If the booking falls through after funding, the renter
+// gets almost everything back and the company keeps a small penalty.
+
+program photo_booth "Photo booth rentals"
+
+import { held_payment } from "std/settlements"
+
+party renter:  person
+party company: business
+
+asset booth: good { title_transfer: off_platform }
+
+settlement booking = held_payment {
+  payer:   renter
+  payee:   company
+  amount:  bookingFee: money(SAR)
+
+  // The platform takes 3% out of the company's payout, and charges the
+  // renter 1% on top of the booking fee at funding.
+  fees { renter: 1%, company: 3% }
+
+  release: port confirm_delivery
+  on_cancel(funded) { renter: 90%, company: 10% }
+}
+
+port confirm_delivery {
+  allowed: [company]
+  shape {
+    boothId:     id(booth)
+    deliveredOn: date
+  }
+}

package/examples/03-diagnostics/README.md

@@ -0,0 +1,68 @@
+# 3 · Reading diagnostics
+
+[`corner-shop.hsx`](./corner-shop.hsx) is wrong on purpose. Three mistakes,
+one per idea. [`corner-shop-fixed.hsx`](./corner-shop-fixed.hsx) is the same
+program repaired.
+
+```bash
+hsx check corner-shop.hsx        # exits 1
+hsx check corner-shop-fixed.hsx  # exits 0, prints nothing
+```
+
+## What comes back
+
+```
+corner-shop.hsx:15:12: error [check] settlement basket payee must name a declared party; there is no party named grocer
+corner-shop.hsx:17:17: error [check] settlement basket decides release through port confirm_pickup, but no port with that name is declared
+corner-shop.hsx:18:21: error [check] the on_cancel split must account for exactly 100%; these shares total 60%
+```
+
+Every diagnostic carries a 1-indexed line and column, a severity, the stage
+that raised it, and one sentence. Coordinates always point at the source you
+wrote, never at a path inside the compiled IR.
+
+## The three mistakes
+
+**Line 15, a name that was never declared.** `payee: grocer` names a party
+that does not exist. Parties, assets, settlements, and ports share one flat
+namespace, and everything in it must be declared. The fix is one line:
+`party grocer: business`.
+
+**Line 17, a decision with nothing behind it.** `release: port confirm_pickup`
+says the release is decided by a port called `confirm_pickup`, and no such
+port is declared. HSX will not invent a decider: someone real has to answer,
+and the file has to say who. The fix declares the port and names who may
+answer it.
+
+**Line 18, money that does not add up.** `on_cancel(funded) { shopper: 60% }`
+leaves 40% of the held amount unaccounted for. There is no default recipient
+and no implicit remainder. The message does the arithmetic for you and says
+what the shares actually total.
+
+## All three at once, and why
+
+The compiler reports every error it can rather than stopping at the first, so
+one run tells you everything you have to fix.
+
+But it will not report errors from two different stages in the same run.
+Compiling is three stages, parse then check then lower, and a stage only runs
+the one before it produced something to work with. All three errors here are
+`[check]`. Introduce a syntax error, say by deleting a closing brace, and you
+get one `[parse]` diagnostic and nothing else: a file that does not parse has
+no meaning to check, so anything else the compiler said about it would be
+guesswork.
+
+## Errors, warnings, verdicts
+
+There are three verdicts:
+
+| Verdict   | Artifacts |                                            |
+| --------- | --------- | ------------------------------------------ |
+| `valid`   | present   | Nothing to say.                            |
+| `warning` | present   | It compiled, and the lint voice has notes. |
+| `invalid` | absent    | It cannot be compiled.                     |
+
+Warnings are lint, not soft errors: a party nobody involves, an import nothing
+instantiates, a 0% fee, a port nothing releases through. They never block, and
+the artifacts of a `warning` compile are complete and usable. If you want them
+to block in CI, `hsx check --strict` exits 1 on a warning.

package/examples/03-diagnostics/corner-shop-fixed.hsx

@@ -0,0 +1,22 @@
+// The same program with all three mistakes repaired: the grocer is declared,
+// the port the release decides through exists, and the cancellation split
+// accounts for the whole held amount.
+
+program corner_shop "Corner shop"
+
+import { held_payment } from "std/settlements"
+
+party shopper: person
+party grocer:  business
+
+settlement basket = held_payment {
+  payer:   shopper
+  payee:   grocer
+  amount:  basketTotal: money(SAR)
+  release: port confirm_pickup
+  on_cancel(funded) { shopper: 60%, grocer: 40% }
+}
+
+port confirm_pickup {
+  allowed: [grocer]
+}

package/examples/03-diagnostics/corner-shop.hsx

@@ -0,0 +1,19 @@
+// This program is wrong on purpose. Three separate mistakes, one per idea:
+// a name that was never declared, a decision with no port behind it, and a
+// cancellation split that does not add up.
+//
+// Run `hsx check corner-shop.hsx` and read what comes back.
+
+program corner_shop "Corner shop"
+
+import { held_payment } from "std/settlements"
+
+party shopper: person
+
+settlement basket = held_payment {
+  payer:   shopper
+  payee:   grocer
+  amount:  basketTotal: money(SAR)
+  release: port confirm_pickup
+  on_cancel(funded) { shopper: 60% }
+}

package/examples/04-complete-product/README.md

@@ -0,0 +1,84 @@
+# 4 · A complete product
+
+[`study-hall.hsx`](./study-hall.hsx) is a tutoring marketplace: three
+settlements, three different jobs, one program.
+
+```bash
+hsx check study-hall.hsx
+hsx build study-hall.hsx --out ir.json
+```
+
+| Settlement     | Brick              | What it does                                                                                           |
+| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `lesson`       | `held_payment`     | Holds the student's payment until the tutor confirms the lesson, or until the stored end date arrives. |
+| `kit_deposit`  | `security_deposit` | Reserves the equipment deposit on the student's own account. Claimed on damage, returned intact.       |
+| `tutor_payout` | `pooled_split`     | Splits the weekly pool 55/45 between the two tutors, remainder to the lead.                            |
+
+## A deposit is not a payment
+
+```hsx
+settlement kit_deposit = security_deposit {
+  payer:  student
+  holder: tutor
+  amount: kitDeposit: money(SAR)
+  claim:  port assess_kit
+  return: port release_kit
+}
+```
+
+The money never leaves the student's account. A deposit is a **reservation**:
+placed as a hold, then either posted to the holder (`claim`) or voided back to
+the payer (`return`). That is why one settlement needs two ports and why they
+must be different ones. Two exits, two decisions, and the hold pairing law
+accounts for the full amount on both.
+
+## Nobody answering is an answer
+
+```hsx
+release: port confirm_lesson | at(lessonEndsAt)
+```
+
+`| at(<date field>)` gives the release a stored date to fall back on. If
+nobody answers the port, the date releases the money to the tutor.
+
+This is the one place HSX lets a deadline decide money, and it is deliberately
+not symmetric: inaction resolves in the direction the parties already agreed
+on, rather than stranding the payment in escrow forever. Only `held_payment`'s
+`release` accepts it. Every other port must be answered.
+
+## The remainder has an owner
+
+```hsx
+split { lead_tutor: 55%, tutor: 45%, remainder_to: lead_tutor }
+```
+
+Percentages of an integer amount of minor units almost never divide evenly.
+Every piece is floored, and the leftover minor units go somewhere explicit:
+`remainder_to` names which recipient carries them, and without it the first
+share does. Nobody's fraction of a halala goes missing, and nobody's is
+invented.
+
+A pool needs at least two recipients, and the funder cannot be one of them. A
+pool that distributes to one person is a transfer, and there is an archetype
+for that.
+
+## What it compiles to
+
+Three instruments, `lesson`, `kit_deposit`, and `tutor_payout`, plus nine money events:
+
+```
+lesson_fund
+lesson_release_tutor
+lesson_release_platform
+lesson_abandon
+kit_deposit_hold_1
+tutor_payout_pool_1
+tutor_payout_pool_2
+tutor_payout_payout_1
+tutor_payout_payout_2
+```
+
+One program carries at most **20** money events (`MONEY_EVENT_BUDGET`). This
+one uses nine. Every installment anchor, fee leg, cancellation leg, and
+abandonment refund counts one, so the budget is the real ceiling on how much
+company fits in a single file. Past it, split the product.

package/examples/04-complete-product/study-hall.hsx

@@ -0,0 +1,67 @@
+// A complete small product: a tutoring marketplace.
+//
+// Three settlements, three different jobs:
+//
+//   lesson       a student's payment is held until the tutor confirms the
+//                lesson happened; the platform's 8% comes out of the payout
+//   kit_deposit  the tutor's equipment deposit is a reservation on the
+//                student's own account, claimed on damage or returned intact
+//   tutor_payout the marketplace's weekly pool, split between the two tutors
+//                who ran the sessions, with the remainder going to the lead
+//
+// Everything a caller can decide goes through a port, and every port names
+// exactly who may answer it.
+
+program study_hall "Study hall"
+
+import { held_payment, security_deposit, pooled_split } from "std/settlements"
+
+party student:     person
+party tutor:       business
+party lead_tutor:  business
+party school:      business
+
+asset lesson_kit: good { title_transfer: on_platform }
+
+settlement lesson = held_payment {
+  payer:   student
+  payee:   tutor
+  amount:  lessonFee: money(SAR)
+  fees { tutor: 8% }
+  release: port confirm_lesson | at(lessonEndsAt)
+}
+
+settlement kit_deposit = security_deposit {
+  payer:  student
+  holder: tutor
+  amount: kitDeposit: money(SAR)
+  claim:  port assess_kit
+  return: port release_kit
+}
+
+settlement tutor_payout = pooled_split {
+  payer:      school
+  amount:     weeklyPool: money(SAR)
+  payout_due: payoutDate
+  split { lead_tutor: 55%, tutor: 45%, remainder_to: lead_tutor }
+}
+
+// The tutor confirms the lesson happened. If nobody answers, `at(lessonEndsAt)`
+// releases the money to the tutor on the stored date: inaction resolves in the
+// direction the parties already agreed on, instead of stranding the payment.
+port confirm_lesson {
+  allowed: [tutor]
+  shape {
+    kitId:       id(lesson_kit)
+    lessonNotes: text
+  }
+}
+
+port assess_kit {
+  allowed: [tutor]
+  shape { damageReport: text }
+}
+
+port release_kit {
+  allowed: [tutor]
+}

package/examples/05-watch-club/README.md

@@ -0,0 +1,9 @@
+# Watch club
+
+This reference program joins the algebra needed for one club product. It keeps
+each watch attached to explicit sale, deposit, and trade rules. Membership due
+dates open periods, while callers still author every money action. Seller
+payouts close through stored provider evidence.
+
+The acceptance proof lives in
+`toolchain/system-tests/test/watch-club.acceptance.spec.ts`.