@hyperscale0/hsx 2.4.1 → 3.0.0

package/docs/llms.txt

@@ -1,44 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# HSX documentation
-
-> Repository guide and generated compiler reference for HSX 2.4.1.
-
-## Guide
-
-[Your first program](guide/01-first-program.md): Hand-written chapter with compiler-checked programs.
-[Money](guide/02-money.md): Hand-written chapter with compiler-checked programs.
-[Instruments](guide/03-instruments.md): Hand-written chapter with compiler-checked programs.
-[Lifecycles](guide/04-lifecycles.md): Hand-written chapter with compiler-checked programs.
-[Fees and splits](guide/05-fees-and-splits.md): Hand-written chapter with compiler-checked programs.
-[Schedules](guide/06-schedules.md): Hand-written chapter with compiler-checked programs.
-[Composition](guide/07-composition.md): Hand-written chapter with compiler-checked programs.
-[Writing a module](guide/08-writing-a-module.md): Hand-written chapter with compiler-checked programs.
-[Cost](guide/09-cost.md): Hand-written chapter with compiler-checked programs.
-[Diagnostics](guide/10-diagnostics.md): Hand-written chapter with compiler-checked programs.
-
-## Reference
-
-[Grammar](reference/grammar.md): Lexer, clause, and module vocabulary.
-[Types](reference/types.md): HSX type kinds and account role pins.
-[Diagnostics](reference/diagnostics.md): Stable HSX diagnostic codes and fixes.
-[CLI](reference/cli.md): Generated command usage.
-[UDL output](reference/udl-output.md): Compile artifacts and canonical output.
-[advance](reference/std/advance.md): Standard-library module.
-[cancellable_booking](reference/std/cancellable_booking.md): Standard-library module.
-[captured_payment](reference/std/captured_payment.md): Standard-library module.
-[conditional_disbursement](reference/std/conditional_disbursement.md): Standard-library module.
-[credit_facility](reference/std/credit_facility.md): Standard-library module.
-[held_payment](reference/std/held_payment.md): Standard-library module.
-[instant_transfer](reference/std/instant_transfer.md): Standard-library module.
-[metered](reference/std/metered.md): Standard-library module.
-[pooled_split](reference/std/pooled_split.md): Standard-library module.
-[premium_forward](reference/std/premium_forward.md): Standard-library module.
-[reconciled_payout](reference/std/reconciled_payout.md): Standard-library module.
-[rotating_pool](reference/std/rotating_pool.md): Standard-library module.
-[scheduled](reference/std/scheduled.md): Standard-library module.
-[security_deposit](reference/std/security_deposit.md): Standard-library module.
-[settlement_batch](reference/std/settlement_batch.md): Standard-library module.
-[swap](reference/std/swap.md): Standard-library module.
-[threshold_pool](reference/std/threshold_pool.md): Standard-library module.
-[weighted_distribution](reference/std/weighted_distribution.md): Standard-library module.

package/docs/piece-plans.md

@@ -1,120 +0,0 @@
-# Compose actions over a piece plan
-
-Use `piece_plan` to declare a finite partition and `piece_stage` to select a
-stage of that plan. Use `calls` and `action_library` to share the transfer
-body. These are ordinary clauses; they do not add another HSX grammar or a
-public operation for each private leaf.
-
-The clause shapes are defined by the selected UDL vocabulary. HSX checks them
-in [`typecheck.ts`](../src/typecheck.ts) and preserves them in
-[`emit.ts`](../src/emit.ts). The round-trip and private-module examples in
-[`general-language.spec.ts`](../test/general-language.spec.ts) exercise this
-path. The [UDL output reference](reference/udl-output.md) describes the emitted ABI.
-
-## Worked sale example
-
-This excerpt uses the sale settlement's `price` plan and funding call. It
-belongs inside an instrument that declares the referenced immutable fields,
-its lifecycle, its partition and its escrow-account capture. It is not a
-standalone program. The three money fields partition `price` exactly. For
-example, SAR minor-unit amounts `245000`, `3750` and `1250` sum to `250000`.
-The separate service fee is outside that partition.
-
-```hsx
-piece_plan: {
-  id: "price";
-  total: "price";
-  pieces: [
-    { id: "seller"; amount: "piece1Amount";
-      release_to: "sellerAccountId"; refund_to: "buyerAccountId"; },
-    { id: "platform_fee"; amount: "piece2Amount";
-      release_to: "platformAccountId"; refund_to: "buyerAccountId"; },
-    { id: "seller_cancel_fee"; amount: "piece3Amount";
-      release_to: "platformAccountId"; refund_to: "sellerAccountId"; }
-  ];
-  fund_order: ["seller", "platform_fee", "seller_cancel_fee"];
-  release_order: ["platform_fee", "seller_cancel_fee"];
-  refund_order: ["platform_fee", "seller_cancel_fee"];
-  unfund_order: ["seller_cancel_fee", "platform_fee", "seller"];
-};
-action_library: {
-  settlement_piece: {
-    actionOrder: ["move"];
-    actions: {
-      move: {
-        parameters: {
-          piece: { kind: "piece"; };
-          source: { kind: "account"; };
-          destination: { kind: "account"; };
-        };
-        principal: "api_key";
-        approval: "inherit";
-        recovery: "local";
-        order: ["transfer"];
-        calls: [];
-        leaves: [{
-          id: "transfer";
-          operation: "internal_transfer.create";
-          bind: {
-            amount: "$piece.amount";
-            currency: "$piece.currency";
-            sourceAccountId: "$source";
-            destinationAccountId: "$destination";
-          };
-          effects: [{ kind: "moves"; signature: "moves.transfer.internal"; }];
-          evidence: "transferId";
-        }];
-      };
-    };
-  };
-};
-action fund_piece {
-  public: none;
-  piece_stage: { plan: "price"; stage: "fund"; };
-  calls: [{
-    id: "move_piece";
-    action: "settlement_piece.move";
-    bind: {
-      piece: "$piece";
-      source: "$fields.buyerAccountId";
-      destination: "$instance.refs.escrowAccountId";
-    };
-  }];
-  steps: [];
-  summary: "Fund a piece of a sale settlement";
-}
-```
-
-The compiler derives `pieceId` from `fund_order`; callers cannot override the
-piece amount or destination. The call binds the buyer and captured escrow
-account into the one transfer leaf. The stage itself adds no movement.
-`public: none` leaves program exposure explicit. Canonical UDL keeps the plan,
-library, calls and action order, while resolved plans carry the expanded leaves
-and their origin paths. An ordinary exported module value can supply the same
-library without publishing another instrument.
-
-For the cancellation path, the same private action binds its destination to
-`$piece.refund_to`. `platform_fee` returns to the buyer; `seller_cancel_fee`
-pays the seller. Unfund instead binds the buyer for every funded piece, in
-reverse order. Handover, cancellation and service-fee collection remain
-separate declared actions; a piece plan does not combine their decisions.
-
-## Refusals to understand
-
-UDL diagnostics retain their codes through HSX diagnostic provenance.
-[`diagnostics.ts`](../src/diagnostics.ts) owns the HSX mapping, and
-[`general-language.spec.ts`](../test/general-language.spec.ts) checks that fatal
-UDL codes survive it.
-
-| UDL code  | Meaning for this example                                                              | Repair                                                                    |
-| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `UDL4001` | The money graph loses or creates value on a lifecycle path, including partial funding | Balance the funded amount on every exit and drain held value              |
-| `UDL5013` | A stage names an invalid plan/order or lacks the required call form                   | Name `price`, use declared unique piece IDs and declare the stage's calls |
-| `UDL2010` | Private calls cycle, name an unresolved action, violate order or exceed bounds        | Keep the graph finite and its order lists exact                           |
-
-The partition itself has `UDL4002` diagnostics for incompatible immutable
-fields, amount partition or currency. A stage does not exempt its transfer
-from the independent money proof. Calls across different principals,
-independent approval or external recovery boundaries are refused; model those
-as separate actions. The [diagnostic reference](reference/diagnostics.md) lists the HSX refusal
-codes and their repairs.

package/docs/playground.md

@@ -1,55 +0,0 @@
-# Browser playground
-
-The HSX playground is a static browser application for authoring, editing,
-and inspecting HSX programs without a server. It runs the compiler directly
-in the browser client. The hosted playground is served at
-https://hyperscale0.ai/playground.
-
-## What it provides
-
-- Source editor with line numbers and debounced compilation (200 ms).
-- Verdict badge showing `valid`, `warning`, or `invalid`.
-- Diagnostics panel with stage, code, line and column coordinates, message,
-  and suggested fix. Clicking any diagnostic focuses the editor and highlights
-  the exact source span.
-- Tabbed output pane showing the lowered canonical UDL document as formatted
-  JSON and the UDL cost manifest.
-- Built-in example selector containing the full corpus of test programs and
-  standard-library settlements.
-- Pure client execution with no Node runtime dependencies.
-
-## Build the playground
-
-Generate the examples manifest, bundle the browser assets, and copy static
-files to `open/hsx/playground/dist/`:
-
-```bash
-bun run --cwd open/hsx playground:build
-```
-
-Verify that the generated static bundle contains no Node specifiers or URL
-resolution calls:
-
-```bash
-bun run --cwd open/hsx playground:check
-```
-
-## Serve locally
-
-The hosted playground is served at https://hyperscale0.ai/playground.
-To run the playground locally from `open/hsx/playground/dist/`, serve
-the output directory with any local static file server.
-
-Using Bun:
-
-```bash
-bunx serve open/hsx/playground/dist
-```
-
-Using Python:
-
-```bash
-python3 -m http.server -d open/hsx/playground/dist 8000
-```
-
-Open `http://localhost:8000` in a browser.

package/docs/reference/cli.md

@@ -1,36 +0,0 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.4.1. Do not edit. -->
-
-# CLI
-
-```text
-hsx 2.4.1, the HSX compiler
-
-Usage:
-  hsx check <file.hsx> [--catalog <catalog.udl>] [--strict]
-  hsx build <file.hsx> [--catalog <catalog.udl>] [--out <file.json>] [--strict]
-  hsx cost <file.hsx> [--catalog <catalog.udl>] [--json] [--out <file.json>] [--strict]
-  hsx explain <HSX####>
-  hsx format <file.hsx>
-  hsx lsp
-  hsx --version
-  hsx --help
-
-Commands:
-  check   Compile and report diagnostics. Prints nothing when the program is clean.
-  build   Compile and write canonical UDL as JSON.
-  cost    Compile and print the version-pinned cost manifest as a table or JSON.
-  explain Print one diagnostic title, fix, and source example.
-  format  Print the source in the one canonical HSX style.
-  lsp     Run the language server over stdin and stdout.
-
-Options:
-  --catalog <file>  Read the published instrument catalogue as canonical UDL JSON.
-  --json        Print the cost manifest as JSON instead of a table.
-  --out <file>  Write build or cost JSON to this path instead of stdout.
-  --strict      Treat warning-severity diagnostics as failures.
-
-Exit codes:
-  0  the program compiled (verdict valid, or warning without --strict)
-  1  the program was refused (verdict invalid, or warning with --strict)
-  2  the command line or the input file could not be used
-```