@hyperscale0/hsx 2.4.0 → 3.0.0

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

@@ -1,84 +0,0 @@
-# 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 module
-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

@@ -1,67 +0,0 @@
-// 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/money_flows"
-
-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-authored-instrument/README.md

@@ -1,5 +0,0 @@
-# Authored payment
-
-`payment.hsx` declares a payment with a bound internal transfer. The [module guide](../../docs/guide/08-writing-a-module.md#an-authored-action-that-moves-money) contains the same program. The docs builder compares the bytes and compiles it with the packaged cost table.
-
-From the full repository root, run `bun open/hsx/bin/hsx.ts check open/hsx/examples/05-authored-instrument/payment.hsx`.

package/examples/05-authored-instrument/payment.hsx

@@ -1,37 +0,0 @@
-program authored_payment "Authored payment"
-
-instrument payment {
-  agent_description: "Collect a stored payment once from its payer."
-  title: "Payment"
-  summary: "A payment with fixed payer and payee accounts"
-  fields {
-    payerAccountId: account<SAR>;
-    payeeAccountId: account<SAR>;
-    amount: money<SAR>;
-  }
-  parties { payer: payerAccountId; beneficiary: payeeAccountId; }
-  lifecycle {
-    states pending paid;
-    initial pending;
-    on pay: pending -> paid;
-  }
-  action create {
-    agent_description: "Open a pending payment without moving money."
-    steps: [];
-    moves: [];
-  }
-  action pay {
-    agent_description: "Move the stored amount from payer to payee."
-    steps: [];
-    moves: [{
-      bind: {
-        amount: { from: "instance", path: "fields.amount" }
-        currency: { from: "const", value: "SAR" }
-        sourceAccountId: { from: "instance", path: "fields.payerAccountId" }
-        destinationAccountId: { from: "instance", path: "fields.payeeAccountId" }
-      }
-      key: "payment_transfer"
-      operation: "internal_transfer.create"
-    }];
-  }
-}

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

@@ -1,6 +0,0 @@
-# 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.

package/examples/05-watch-club/watch-club.hsx

@@ -1,123 +0,0 @@
-// A watch club whose money rules remain explicit from member checkout through
-// seller payout. Each item owns its sale, deposit, and trade lifecycle. The
-// club membership schedule opens periods but never moves money on a timeout.
-
-program watch_club "Watch club"
-
-import {
-  security_deposit,
-  instant_transfer,
-  scheduled,
-  settlement_batch,
-  swap
-} from "std/money_flows"
-
-party member: person
-party seller: business
-party club: business
-party payout_destination: business
-
-asset watch: good { title_transfer: on_platform }
-
-settlement purchase = instant_transfer {
-  payer: member
-  payee: seller
-  amount: purchasePrice: money(SAR)
-  fees {
-    member: checkoutFee: money(SAR)
-    seller {
-      tier {
-        from: 0
-        to: 10000
-        fee: 1%
-      }
-      tier {
-        from: 10000
-        fee: highValueFee: money(SAR)
-      }
-    }
-  }
-}
-
-settlement inspection_deposit = security_deposit {
-  payer: member
-  holder: seller
-  amount: depositAmount: money(SAR)
-  claim: port assess_watch
-  claim_amount: decided {
-    field: damageAmount
-    bound: depositAmount
-    remainder: return
-  }
-  return: port return_deposit
-}
-
-settlement membership = scheduled {
-  mode: obligation
-  payer: member
-  payee: club
-  debtor: member
-  amount: monthlyFee: money(SAR)
-  every: P1M
-  first_due: firstPeriodAt
-  until: port cancel_membership
-  month_end: clamp_to_last_day
-  period_liability: one_open
-  termination_drain: cancel_membership
-  mandate: port collect_membership
-}
-
-settlement member_trade = swap {
-  between: [member, seller]
-  amounts {
-    member: memberPays: money(SAR)
-    seller: sellerPays: money(SAR)
-  }
-  fees {
-    member: memberTradeFee: money(SAR)
-    seller: sellerTradeFee: money(SAR)
-  }
-  release: port confirm_trade
-  dispute: port resolve_trade within P14D
-}
-
-settlement seller_payout = settlement_batch {
-  settlement_account: club
-  source_capture_refs: captureReference
-  fee_entries: feeReference
-  external_reversal_offsets: externalReversalReference
-  close_trigger: closeAt
-  payout_destination: payout_destination
-  negative_position: reject
-  payout_acknowledgement: port acknowledge_payout
-  payout_beneficiary_ref: payoutBeneficiaryId
-}
-
-port assess_watch {
-  allowed: [seller]
-  shape {
-    damageAmount: money(SAR)
-    evidence: text
-  }
-}
-
-port return_deposit { allowed: [seller] }
-
-port collect_membership {
-  allowed: [member]
-  shape { evidenceReference: text }
-}
-
-port cancel_membership {
-  allowed: [member]
-  shape { reason: text }
-}
-
-port confirm_trade { allowed: [member, seller] }
-
-port resolve_trade { allowed: [member, seller] }
-
-port acknowledge_payout {
-  allowed: [payout_destination]
-  shape { acknowledgementReference: text }
-}

package/examples/README.md

@@ -1,48 +0,0 @@
-# Examples
-
-Each money flow has its own directory with an HSX program, a
-short lesson, and pinned canonical UDL bytes. The test suite reads the module
-list from `std/money_flows`, compiles every program, and compares each emitted
-document byte for byte.
-
-The numbered examples provide end-to-end walkthroughs:
-
-- [01 · Your first program](01-first-program/README.md)
-- [02 · Imports and modules](02-imports-and-modules/README.md)
-- [03 · Diagnostics](03-diagnostics/README.md)
-- [04 · Complete product](04-complete-product/README.md)
-- [05 · Watch club](05-watch-club/README.md)
-
-## Money flows
-
-Each money flow has a runnable example directory:
-
-- [advance](advance/README.md)
-- [cancellable_booking](cancellable_booking/README.md)
-- [captured_payment](captured_payment/README.md)
-- [conditional_disbursement](conditional_disbursement/README.md)
-- [credit_facility](credit_facility/README.md)
-- [held_payment](held_payment/README.md)
-- [instant_transfer](instant_transfer/README.md)
-- [metered](metered/README.md)
-- [pooled_split](pooled_split/README.md)
-- [premium_forward](premium_forward/README.md)
-- [reconciled_payout](reconciled_payout/README.md)
-- [rotating_pool](rotating_pool/README.md)
-- [scheduled](scheduled/README.md)
-- [security_deposit](security_deposit/README.md)
-- [settlement_batch](settlement_batch/README.md)
-- [swap](swap/README.md)
-- [threshold_pool](threshold_pool/README.md)
-- [weighted_distribution](weighted_distribution/README.md)
-
-## Running an example
-
-Run an example with the installed CLI:
-
-```sh
-hsx check examples/instant_transfer/instant_transfer.hsx
-hsx build examples/instant_transfer/instant_transfer.hsx --out program.udl
-```
-
-Every company and person in these files is invented.

package/examples/advance/README.md

@@ -1,3 +0,0 @@
-# advance
-
-This example applies the `advance` standard-library module. Its sibling UDL file pins the canonical compiler output byte for byte. The company and parties are invented.

package/examples/advance/advance.hsx

@@ -1,13 +0,0 @@
-program advance_example "Advance example"
-import { advance } from "std/money_flows"
-party funder: business
-party recipient: business
-settlement advance_payment = advance {
-  funder: funder
-  to: recipient
-  amount: principal: money(SAR)
-  fee: 2.5%
-  count: 2
-  every: P30D
-  first_due: firstDueAt
-}