@hyperscale0/hsx 2.4.1 → 3.0.1

package/docs/guide/05-fees-and-splits.md

@@ -1,45 +0,0 @@
-# Fees and splits
-
-Standard-library payment modules accept bounded fee forms. A payer fee sits on top of the principal. A payee fee is carved from the payout. A fee may be an exact percentage, an immutable money field, or a finite tier table when the module accepts it.
-
-```hsx
-program lesson_market "Lesson market"
-import { instant_transfer, pooled_split } from "std/money_flows"
-party student: person
-party tutor: business
-party assistant: business
-party school: business
-settlement lesson = instant_transfer {
-  payer: student
-  payee: tutor
-  amount: lessonFee: money(SAR)
-  fees { student: 1%, tutor: 8% }
-}
-settlement payout = pooled_split {
-  payer: school
-  amount: weeklyPool: money(SAR)
-  payout_due: payoutAt
-  split { tutor: 60%, assistant: 40%, remainder_to: tutor }
-}
-```
-
-Every percentage partition must total 100 percent. `pooled_split` distributes a pool among named recipients and sends integer-division residue to `remainder_to`. `security_deposit` can bind a decided claim amount and return the unused remainder. `weighted_distribution` records bounded entitlement rows before it snapshots a distribution.
-
-`cancellable_booking` uses `quote` and `commit` when a fee must be shown before it can move money. Its `cancel` action prices a penalty from the time left before `starts_at`, freezes the price and the fields named by `fixes`, and gives the offer a bounded life. Its `confirm` action commits that exact quote. Expiry or a changed frozen field refuses the commit instead of repricing it silently.
-
-```hsx
-program studio_booking "Studio booking"
-import { cancellable_booking } from "std/money_flows"
-party guest: person
-party studio: business
-settlement session = cancellable_booking {
-  guest: guest
-  host: studio
-  amount: sessionPrice: money(SAR)
-  starts_at: startsAt
-  late_penalty_bps: 5000
-  late_within: P2D
-  early_penalty_bps: 1000
-  offer_life: PT30M
-}
-```

package/docs/guide/06-schedules.md

@@ -1,26 +0,0 @@
-# Schedules
-
-HSX schedules are finite. A literal `count`, an interval, and a first due date let the compiler expand installments at compile time. The monthly obligation form can instead use a caller-controlled end condition, but it must name the drain action that ends future liability.
-
-```hsx
-program installments "Installments"
-import { scheduled } from "std/money_flows"
-party buyer: person
-party seller: business
-settlement plan = scheduled {
-  payer: buyer
-  payee: seller
-  amount: totalAmount: money(SAR)
-  count: 3
-  every: P30D
-  first_due: firstDueAt
-}
-```
-
-`scheduled` handles finite installments and obligation schedules. `rotating_pool` expands a fixed roster and cycle count. `settlement_batch` closes on a stored date before calculation, approval, instruction, acknowledgement, and reconciliation actions.
-
-General modules may use a comprehension over a compile-time integer or finite list. Runtime-dependent bounds are refused. An expansion may contain at most 256 generated rows.
-
-Finite obligation counts expand the same lifecycle for each slice. A lifecycle source may be a finite list; `without(states, state)` removes one state before expansion. This preserves rejection of a repeated delinquency marker for its current slice.
-
-Use `advance` with `dated: true` when each repayment has a signed date. `repayment_source` separates the borrower from the capital recipient; `profit_to` sends computed profit to a separate account. The caller partitions the principal and profit across stored repayments. These partitions do not enforce equal slices or ordered dates.

package/docs/guide/07-composition.md

@@ -1,52 +0,0 @@
-# Composition
-
-One program can apply several instruments. Each instrument keeps its own lifecycle and fields. References connect them through typed ids instead of shared mutable state.
-
-```hsx
-program studio_sales "Studio sales"
-import { instant_transfer, scheduled } from "std/money_flows"
-party buyer: person
-party studio: business
-settlement purchase = instant_transfer {
-  payer: buyer
-  payee: studio
-  amount: purchasePrice: money(SAR)
-  fees { buyer: 1% }
-}
-settlement installments = scheduled {
-  payer: buyer
-  payee: studio
-  amount: servicePrice: money(SAR)
-  count: 2
-  every: P30D
-  first_due: firstPaymentAt
-}
-```
-
-A general instrument declares a `ref<target>` field when an instance must point to another instrument. Cross-instrument clauses bind against the target's declared fields, actions, and lifecycle states after the full module graph resolves. A missing target or incompatible field reports a typed diagnostic before UDL emission.
-
-Keep each money route in one instrument. Connect instruments with evidence and references. Do not move an amount through an untyped text field.
-
-`reconciled_payout` composes a payout instruction with one explicit expectation about the bank debit that follows. Its `reconcile` clause binds the expected amount, currency, direction, payout reference, evidence source, match law, and deadline. A match settles the payout. A missed or mismatched expectation creates the declared break child, so the composition retains the exception as contract data.
-
-```hsx
-program supplier_payment "Supplier payment"
-import { reconciled_payout } from "std/money_flows"
-party treasury: business
-party supplier: business
-settlement payout = reconciled_payout {
-  payer: treasury
-  beneficiary: supplier
-  amount: netPayable: money(SAR)
-  beneficiary_ref: supplierBeneficiaryId
-  settle_by: settleBy
-  matched_within: 100
-  matched_ceiling: 500
-}
-```
-
-## Recomposition and exposed actions
-
-When evolving an existing Product with new instruments or flows, the composer plans the candidate program against the active Product Build.
-
-Public action exposures preserve stable semantic identities across builds. Unchanged authored instruments and catalog instruments retain their exposures without false removal and re-addition churn. Only genuinely new, removed, or rebound action aliases appear in the exposure delta.

package/docs/guide/08-writing-a-module.md

@@ -1,85 +0,0 @@
-# Writing a module
-
-A module is ordinary HSX source. It declares a dotted module name and exports templates, types, constants, subjects, or applications. The compiler does not branch on a standard-library module name.
-
-```hsx
-program approval_example "Approval example"
-instrument approval() {
-  agent_description: "Reusable approval lifecycle template."
-  title: "Approval"
-  summary: "A reusable approval lifecycle"
-  fields {}
-  lifecycle {
-    states pending approved;
-    initial pending;
-    on approve: pending -> approved;
-  }
-  action create {
-    agent_description: "Create a pending approval record."
-    steps: [];
-    moves: [];
-  }
-  action approve {
-    agent_description: "Approve the pending decision."
-    steps: [];
-    moves: [];
-  }
-}
-instrument review = approval()
-```
-
-Custom instruments and callable actions require `agent_description: "..."`. An agent uses these descriptions as tool instructions when invoking actions on an instance. Actions that declare a `due` clause run without an agent call and remain exempt from this requirement. Omitting `agent_description` on callable actions or their containing instruments triggers `HSX1509`.
-
-A parameter list makes an instrument a template, including an empty list. A concrete instrument without a parameter list emits directly when its file compiles. Export only the declarations that callers need.
-
-Imported exports carry the local declarations they reference. Identical declarations unify. Conflicting declarations report `HSX1009`. Keep module parameters typed, keep loops finite, and use UDL clause vocabulary for instrument and action mechanics.
-
-Publish a module only after compiling it directly and through an importing program. Compare the canonical UDL bytes from both paths when the exported application should be identical.
-
-## An authored action that moves money
-
-Declare each cash movement in `moves` with a unique `key`, an `operation`, and `bind` operands. This complete program comes from [payment.hsx](../../examples/05-authored-instrument/payment.hsx). The docs builder requires the snippet to match that file and compiles it with the packaged cost table.
-
-```hsx source=examples/05-authored-instrument/payment.hsx
-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"
-    }];
-  }
-}
-```
-
-`from: "instance"` reads an immutable stored field. `from: "const"` supplies the literal currency. The four bindings supply the transfer's amount, currency, source account and destination account. `internal_transfer.create` names the transfer operation; `payment_transfer` identifies this move within the action. Account IDs come from account creation or discovery before creating the payment. They are never invented by the program.
-
-`create` opens a pending record without cash movement. `pay` moves the stored amount and transitions to `paid`; the lifecycle refuses a second payment under a new action request. The compiler emits these bindings into UDL. Execution still requires an engine that admits the operation and accounts.

package/docs/guide/09-cost.md

@@ -1,24 +0,0 @@
-# Cost
-
-Compilation emits a deterministic cost manifest beside the UDL document. The manifest pins the cost-table version and effective digest. It records fixed structural cost, action effect rows, payer, settlement policy, meters, per-event prices, and any basis-point volume price.
-
-```hsx
-program direct_sale "Direct sale"
-import { instant_transfer } from "std/money_flows"
-party buyer: person
-party seller: business
-settlement sale = instant_transfer {
-  payer: buyer
-  payee: seller
-  amount: saleAmount: money(SAR)
-  fees { buyer: 1% }
-}
-```
-
-Read an action line as `instrument.action`, followed by the effect signature and its count. The payer tells whether the product or end customer bears the row. `perEventMinor` prices one occurrence in the cost table's billing currency. A row with `bps` also names a volume meter.
-
-The monthly estimate is an expression over declared meter variables. Billing supplies observed readings to that frozen expression. Recomposition emits a new manifest for the next commercial snapshot. It does not rewrite a prior manifest. During recomposition planning, compose plan calculates the candidate program's proposed estimate and reconciles it against the current Build's frozen pricing quote. The existing Product retains its frozen quote until the recomposition is applied.
-
-An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. `examples/cost-table.json` ships one rate card per priced billing currency; the compiler picks the card whose currency the program's money fields move. Money in a currency no card prices reports `HSX1304`, and money in two currencies reports `HSX1305`: a program bills in one ledger currency. A move of a `money<SAR>` field moves SAR whatever the caller wrote in the instance currency field: the compiler pins the move's currency binding to the constant, and a binding it cannot pin reports `HSX1306`. Do not create another table for documentation.
-
-Do not confuse an action `quote` with the commercial cost manifest. `cancellable_booking.cancel` quotes a customer-visible cancellation penalty and `confirm` commits it. The compiler counts an instrument that carries a quote as unwind work because an expired or abandoned offer still needs bounded cleanup. The cost manifest prices that runtime work from the shipped rate card. It does not replace, spend, or alter the quoted financial amount.

package/docs/guide/10-diagnostics.md

@@ -1,27 +0,0 @@
-# Diagnostics
-
-An HSX diagnostic carries a stable code, severity, stage, source line and column, message, and fix. Match automation on the code. Treat the message as explanation rather than a stable interface.
-
-The stages locate the refusal:
-
-- `parse` means the source did not form valid declarations or expressions.
-- `bind` means an import, name, port, or reference did not resolve.
-- `typecheck` and `check` mean the program formed but violated a type or language law.
-- `lower` means the typed program could not emit valid UDL.
-
-Use one loop: compile, find the first error code in the diagnostics reference, apply its stated fix, and compile again. Do not suppress the diagnostic or alter generated UDL by hand.
-
-```hsx
-program repaired_transfer "Repaired transfer"
-import { instant_transfer } from "std/money_flows"
-party sender: person
-party recipient: business
-settlement transfer = instant_transfer {
-  payer: sender
-  payee: recipient
-  amount: transferAmount: money(SAR)
-  fees { sender: 1% }
-}
-```
-
-Exit code `0` means the command accepted the program. Exit code `1` means compilation refused it. Exit code `2` means the invocation or file operation failed. `hsx explain HSX1201` prints the catalog entry for one code.