@hyperscale0/hsx 1.0.0 → 2.0.0

package/docs/llms.txt

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # HSX documentation
 
-> Repository guide and generated compiler reference for HSX 1.0.0.
+> Repository guide and generated compiler reference for HSX 2.0.0.
 
 ## Guide
 

package/docs/playground.md

@@ -2,7 +2,8 @@
 
 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.
+in the browser client. The hosted playground is served at
+https://hyperscale0.ai/playground.
 
 ## What it provides
 
@@ -35,8 +36,8 @@ bun run --cwd open/hsx playground:check
 
 ## Serve locally
 
-The deliverable is the static directory under `open/hsx/playground/dist/`.
-Hosting infrastructure is owner-owed. To run the playground locally, serve
+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:

package/docs/reference/cli.md

@@ -1,9 +1,9 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # CLI
 
 ```text
-hsx 1.0.0, the HSX compiler
+hsx 2.0.0, the HSX compiler
 
 Usage:
   hsx check <file.hsx> [--strict]

package/docs/reference/diagnostics.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # Diagnostics
 
@@ -32,9 +32,13 @@ Fix: Keep exactly one program declaration.
 ```hsx expect=HSX1002
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 program second "Second"
@@ -59,9 +63,13 @@ Fix: Keep one declaration or give each declaration a distinct name.
 ```hsx expect=HSX1004
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
@@ -107,9 +115,13 @@ Fix: Complete the declaration and bind every referenced decision port.
 ```hsx expect=HSX1008
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 subject vehicle { title: "Vehicle"; }
@@ -232,11 +244,11 @@ Fix: Expose an action on an explicitly used published instrument.
 
 No source-only witness exists. This refusal requires a compiler-host published catalog.
 
-## HSX1022: Authored instrument in a composition
+## HSX1022: Authored instrument collides with published catalog
 
 Stage: `typecheck`
 
-Fix: Publish the instrument separately, then select it with use.
+Fix: Rename the authored instrument to avoid colliding with published catalog instruments.
 
 No source-only witness exists. This refusal requires a compiler-host published catalog.
 
@@ -249,13 +261,61 @@ Fix: List declared, non-optional field names once each.
 ```hsx expect=HSX1023
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   required: missing;
 }
 ```
 
+## HSX1024: Decision party has no matching account binding
+
+Stage: `typecheck`
+
+Fix: Bind the allowed party to an account field and use that binding in the decision action.
+
+```hsx expect=HSX1024
+program decision_binding "Decision binding"
+party buyer: person
+party seller: business
+port approve { allowed: [buyer] }
+instrument gated(decision: condition) {
+  fields {}
+  parties { payer: seller }
+  lifecycle { states created done; initial created; on approve: created -> done; }
+  action create { steps: []; }
+  action [decision] { steps: []; port { allowed_parties: [payer]; } }
+}
+instrument gate = gated(decision: port approve)
+```
+
+## HSX1025: Unknown decision port shape type
+
+Stage: `typecheck`
+
+Fix: Declare the shape field as text, money(CUR), date, integer, boolean, account(CUR), ref<instrument_id>, id(instrument_id), bps, or percent.
+
+```hsx expect=HSX1025
+program catalog_probe "Catalog probe"
+import { security_deposit } from "std/money_flows"
+party buyer: person
+party seller: business
+settlement hold = security_deposit {
+  payer: buyer
+  holder: seller
+  amount: depositAmount: money(SAR)
+  claim: port report_damage
+  claim_amount: { field: damageAmount, bound: depositAmount, remainder: return }
+  return: port pass_inspection
+}
+port report_damage { allowed: [seller] shape { damageAmount: money(SAR) } }
+port pass_inspection { allowed: [seller] shape { invalidField: mystery_type } }
+```
+
 ## HSX1101: Currency mismatch
 
 Stage: `typecheck`
@@ -265,9 +325,13 @@ Fix: Use the declared currency because money values never coerce.
 ```hsx expect=HSX1101
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 const fee: money<SAR> = USD 1.00
@@ -282,9 +346,13 @@ Fix: Round the literal to the currency's minor-unit precision.
 ```hsx expect=HSX1102
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 const fee: money<SAR> = SAR 1.001
@@ -299,9 +367,13 @@ Fix: Use an integer, percent, bps, or valid fixed-money binding.
 ```hsx expect=HSX1103
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   summary: 1.5;
 }
 ```
@@ -315,9 +387,13 @@ Fix: Pass the type declared by the parameter or UDL slot.
 ```hsx expect=HSX1104
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   summary: money(SAR, 2500);
 }
 ```
@@ -348,9 +424,13 @@ Fix: Leave exactly one sink for each produced money value.
 ```hsx expect=HSX1201
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   fields { amount: money<SAR>; }
 action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; moves: [{ amount: rest; }, { amount: rest; }]; }
 }
@@ -365,9 +445,13 @@ Fix: Route each produced money value to one explicit sink.
 ```hsx expect=HSX1202
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   fields { amount: money<SAR>; }
 action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; }
 }
@@ -382,9 +466,13 @@ Fix: Supply a versioned cost table with a row for every emitted effect.
 ```hsx expect=HSX1301
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 ```
@@ -405,6 +493,46 @@ Fix: Use the supported uppercase cost-table currency.
 
 No source-only witness exists. This refusal requires an invalid compiler-host cost-table currency.
 
+## HSX1304: Unpriced ledger currency
+
+Stage: `typecheck`
+
+Fix: Move money in a currency the shipped cost tables price.
+
+```hsx expect=HSX1304
+program catalog_probe "Catalog probe"
+instrument probe {
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { amount: money<JPY>; }
+  lifecycle { states created; initial created; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
+
+}
+```
+
+## HSX1305: More than one ledger currency
+
+Stage: `typecheck`
+
+Fix: Move all money in one currency; a program bills in one ledger currency.
+
+```hsx expect=HSX1305
+program catalog_probe "Catalog probe"
+instrument probe {
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { amount: money<SAR>; fee: money<USD>; }
+  lifecycle { states created; initial created; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
+
+}
+```
+
 ## HSX1401: Unbounded action
 
 Stage: `typecheck`
@@ -414,9 +542,13 @@ Fix: Replace runtime iteration with a bounded compile-time comprehension.
 ```hsx expect=HSX1401
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   action run { while { condition: true; }; }
 }
 ```
@@ -458,9 +590,13 @@ Fix: Reduce the fixed expansion to the compiler limit.
 ```hsx expect=HSX1404
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   for item in 257 { action run_[item] { steps: []; } }
 }
 ```
@@ -503,9 +639,13 @@ Fix: Use a clause exported by the targeted UDL vocabulary.
 ```hsx expect=HSX1501
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   unknown_clause: true;
 }
 ```
@@ -551,9 +691,13 @@ Fix: Keep one occurrence of the clause.
 ```hsx expect=HSX1505
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   title: "First"; title: "Second";
 }
 ```
@@ -567,9 +711,13 @@ Fix: Keep either public: none or a public action name.
 ```hsx expect=HSX1506
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   action finish { public: none; public_action: finishProbe; steps: []; }
 }
 ```
@@ -586,6 +734,40 @@ export instrument template() { fields {}; lifecycle { states created; initial cr
 instrument probe = template() { fields: {}; }
 ```
 
+## HSX1508: Invalid action-level port syntax
+
+Stage: `typecheck`
+
+Fix: Use allowed_parties: [...] inside an action-level port clause; allowed: is for top-level port declarations.
+
+```hsx expect=HSX1508
+program catalog_probe "Catalog probe"
+party approver: person
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create {
+    steps: [];
+    port { allowed: [approver]; }
+  }
+}
+```
+
+## HSX1509: Callable action without an agent description
+
+Stage: `typecheck`
+
+Fix: Add agent_description: "..." to the instrument and to every action a caller can reach; composer.check refuses the program without them.
+
+```hsx expect=HSX1509
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+```
+
 ## HSX1601: Invalid UDL shape
 
 Stage: `lower`
@@ -611,9 +793,13 @@ Fix: Correct compile-time block keys or parameter bindings.
 ```hsx expect=HSX1603
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   title: "__hsx_none__";
 }
 ```

package/docs/reference/grammar.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # Grammar vocabulary
 
@@ -14,7 +14,7 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 
 ## Typed clause spellings
 
-`agent description`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
+`agent description`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `journeys`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
 
 ## Standard-library modules
 

package/docs/reference/std/advance.md

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # advance
 
-Source: [`std/settlements/advance.hsx`](../../../std/settlements/advance.hsx)
+Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
 
 ## Export
 

package/docs/reference/std/cancellable_booking.md

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # cancellable_booking
 
-Source: [`std/settlements/cancellable_booking.hsx`](../../../std/settlements/cancellable_booking.hsx)
+Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/cancellable_booking.hsx)
 
 ## Export
 
@@ -25,11 +25,11 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                            |
-| ---------- | ---------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
-| `take`     | `agent description`, `moves`, `steps`, `summary`           |
-| `complete` | `due`, `moves`, `steps`, `summary`                         |
-| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`  |
-| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary` |
-| `retain`   | `agent description`, `moves`, `steps`, `summary`           |
+| Action     | Clauses lowered                                                           |
+| ---------- | ------------------------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                          |
+| `take`     | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `complete` | `due`, `moves`, `steps`, `summary`                                        |
+| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`                 |
+| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary`                |
+| `retain`   | `agent description`, `moves`, `steps`, `summary`                          |

package/docs/reference/std/captured_payment.md

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # captured_payment
 
-Source: [`std/settlements/captured_payment.hsx`](../../../std/settlements/captured_payment.hsx)
+Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captured_payment.hsx)
 
 ## Export
 
@@ -29,15 +29,15 @@ Source: [`std/settlements/captured_payment.hsx`](../../../std/settlements/captur
 
 ## Actions and clauses
 
-| Action             | Clauses lowered                                                                              |
-| ------------------ | -------------------------------------------------------------------------------------------- |
-| `create`           | `agent description`, `moves`, `steps`, `summary`                                             |
-| `authorize`        | `agent description`, `moves`, `steps`, `summary`                                             |
-| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
-| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
-| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                 |
-| `void`             | `agent description`, `moves`, `steps`, `summary`                                             |
-| `expire`           | `due`, `moves`, `steps`, `summary`                                                           |
-| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                           |
-| `correction_name`  | `agent description`, `moves`, `port`, `steps`, `summary`                                     |
-| `reversal_name`    | `agent description`, `deadline`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| Action             | Clauses lowered                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `create`           | `agent description`, `moves`, `steps`, `summary`                                                              |
+| `authorize`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                                     |
+| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`                          |
+| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                  |
+| `void`             | `agent description`, `moves`, `steps`, `summary`                                                              |
+| `expire`           | `due`, `moves`, `steps`, `summary`                                                                            |
+| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                                            |
+| `correction_name`  | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                            |
+| `reversal_name`    | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary`                |

package/docs/reference/std/conditional_disbursement.md

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # conditional_disbursement
 
-Source: [`std/settlements/conditional_disbursement.hsx`](../../../std/settlements/conditional_disbursement.hsx)
+Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flows/conditional_disbursement.hsx)
 
 ## Export
 
@@ -27,7 +27,7 @@ Source: [`std/settlements/conditional_disbursement.hsx`](../../../std/settlement
 | Action    | Clauses lowered                                                                                   |
 | --------- | ------------------------------------------------------------------------------------------------- |
 | `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `deny`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `deny`    | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                |
 | `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
 | `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
 | `pay`     | `agent description`, `moves`, `steps`, `summary`                                                  |

package/docs/reference/std/credit_facility.md

@@ -1,8 +1,8 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.0. Do not edit. -->
 
 # credit_facility
 
-Source: [`std/settlements/credit_facility.hsx`](../../../std/settlements/credit_facility.hsx)
+Source: [`std/money_flows/credit_facility.hsx`](../../../std/money_flows/credit_facility.hsx)
 
 ## Export