@hyperscale0/hsx 2.1.0 → 2.2.0

package/dist/src/version.d.ts

@@ -1,5 +1,5 @@
 /** Package version reported by the command line. */
-export declare const HSX_VERSION = "2.1.0";
+export declare const HSX_VERSION = "2.2.0";
 /** Canonical UDL contract version emitted by this compiler. */
 export declare const HSX_TARGET_UDL_VERSION = 1;
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.js

@@ -1,5 +1,5 @@
 /** Package version reported by the command line. */
-export const HSX_VERSION = "2.1.0";
+export const HSX_VERSION = "2.2.0";
 /** Canonical UDL contract version emitted by this compiler. */
 export const HSX_TARGET_UDL_VERSION = 1;
 //# sourceMappingURL=version.js.map

package/docs/README.md

@@ -15,13 +15,19 @@ the package test suite.
 10. [Diagnostics](./guide/10-diagnostics.md)
 
 The generated [reference](./reference/) follows the compiler, UDL vocabulary,
-and standard-library files. Run `bun run docs:build` after changing one of
-those sources. `bun run docs:check` compares every generated byte.
+and standard-library files. Run `bun run generate` in a source checkout to
+build references, the embedded standard library and playground examples. Package
+builds and prepack do this automatically. These outputs are ignored by git;
+`bun run docs:build` compiles guide examples and validates documentation links.
 
 The [browser playground](./playground.md) provides a static editing surface with
 live compilation, diagnostics inspection, and example programs. The hosted
 playground is served at https://hyperscale0.ai/playground.
 
+[Compose actions over a piece plan](./piece-plans.md) is a worked excerpt, not
+a standalone program: it shows the `piece_plan`, `piece_stage`, `calls` and
+`action_library` clauses inside an instrument.
+
 ## Examples and tooling
 
 - [Standard library examples](../examples/README.md)

package/docs/guide/01-first-program.md

@@ -21,4 +21,4 @@ settlement tip = instant_transfer {
 
 A port declares a decision that an external caller may supply. The port names the parties allowed to answer and may define a typed input shape. Use a port only when the selected instrument accepts a condition parameter.
 
-After package installation, run `npx @hyperscale0/hsx check product.hsx` while editing and `npx @hyperscale0/hsx build product.hsx --out product.udl.json` when the program passes. In a repository checkout, run `bun install` once, then use `bun run bin/hsx.ts check product.hsx` and `bun run bin/hsx.ts build product.hsx --out product.udl.json`.
+After package installation, run `npx @hyperscale0/hsx check product.hsx` while editing and `npx @hyperscale0/hsx build product.hsx --out product.udl.json` when the program passes. In the full repository checkout, run `bun install` once from the repository root, then use `bun open/hsx/bin/hsx.ts check product.hsx` and `bun open/hsx/bin/hsx.ts build product.hsx --out product.udl.json`. In the standalone HSX package checkout, the entrypoint is `bin/hsx.ts`.

package/docs/guide/06-schedules.md

@@ -17,6 +17,10 @@ settlement plan = scheduled {
 }
 ```
 
-`scheduled` handles finite installments and obligation schedules. `recurring_collection` records collection periods without inventing money movement. `rotating_pool` expands a fixed roster and cycle count. `settlement_batch` closes on a stored date before calculation, approval, instruction, acknowledgement, and reconciliation actions.
+`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/08-writing-a-module.md

@@ -35,3 +35,51 @@ A parameter list makes an instrument a template, including an empty list. A conc
 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.