@hyperscale0/hsx 1.0.0-rc.1 → 2.0.0

package/dist/src/version.d.ts

@@ -1,5 +1,5 @@
 /** Package version reported by the command line. */
-export declare const HSX_VERSION = "1.0.0-rc.1";
+export declare const HSX_VERSION = "2.0.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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,IAAI,CAAC"}

package/dist/src/version.js

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

package/dist/src/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC"}

package/docs/README.md

@@ -18,6 +18,18 @@ 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.
 
+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.
+
+## Examples and tooling
+
+- [Standard library examples](../examples/README.md)
+- [Browser playground](./playground.md)
+- [VS Code extension](../editors/vscode/README.md)
+
+## Agent references
+
 Agents can start with [llms.txt](./llms.txt) or load the
 [HSX skill](../skills/hsx/SKILL.md). [llms-full.txt](./llms-full.txt) combines
 the guide and generated reference in reading order.

package/docs/assets/hsx.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="360" viewBox="0 0 1200 360" role="img" aria-labelledby="title desc">
+  <title id="title">HSX</title>
+  <desc id="desc">Write a financial product. Compile its contract.</desc>
+  <rect width="1200" height="360" fill="#050505"/>
+  <path d="M48 48H1152M48 304H1152M944 48V304" fill="none" stroke="#303030"/>
+  <rect x="48" y="76" width="10" height="10" fill="#2f7dff"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+    <text x="72" y="86" fill="#a3a3a3" font-size="14" letter-spacing="2">HYPERSCALE / DOCUMENTATION</text>
+    <text x="44" y="194" fill="#ffffff" font-size="76" letter-spacing="-4">HSX</text>
+    <text x="48" y="243" fill="#a3a3a3" font-size="20">Write a financial product. Compile its contract.</text>
+    <text x="48" y="334" fill="#a3a3a3" font-size="12" letter-spacing="2">LANGUAGE / STANDARD LIBRARY / COMPILER</text>
+    <text x="991" y="279" fill="#a3a3a3" font-size="12">SOURCE → CONTRACT</text>
+  </g>
+  <g fill="none" stroke="#2f7dff" stroke-width="2">
+    <path d="M990 110H1058V178H1126V246H1058V178H990Z"/>
+    <path d="M1058 110H1126V178H1058"/>
+  </g>
+</svg>

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

@@ -1,12 +1,12 @@
 # Your first program
 
-An HSX file declares one program, the parties that take part, and the instruments that define its money rules. A settlement applies a standard-library instrument. The compiler checks the application and emits canonical UDL with a Business Frame, an origin map, and a cost manifest.
+An HSX file declares one program, the parties that take part, and the instruments that define its money rules. A settlement applies a standard-library instrument. The compiler checks the application and emits canonical UDL with an origin map and a cost manifest.
 
 This program sends a tip from a listener to a host:
 
 ```hsx
 program tip_jar "Tip jar"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party listener: person
 party host: business
 settlement tip = instant_transfer {

package/docs/guide/02-money.md

@@ -1,6 +1,6 @@
 # Money
 
-HSX indexes money by currency. `money<SAR>` is the field type inside a general instrument. `amount: total: money(SAR)` binds a settlement parameter to a new SAR money field. Values use integer minor units, so `1250` means SAR 12.50.
+HSX indexes money by currency. `money<SAR>` is the field type inside a general instrument. `amount: total: money(SAR)` binds a settlement parameter to a new SAR money field. Values use integer minor units, so `1250` means SAR 12.50. The emitted UDL field keeps the currency as `x-hyperscale-currency`, which is how the platform learns a program's ledger currency.
 
 Money of different currencies never unifies. Percent literals use basis-point precision: `2%` is 200 basis points and `2.5%` is 250 basis points. The compiler floors percentage-derived minor units and assigns any declared remainder according to the selected instrument.
 

package/docs/guide/03-instruments.md

@@ -1,10 +1,10 @@
 # Instruments
 
-Start with the standard library. Import a settlement module by export name from `std/settlements`, then apply it under a local settlement name. The local name becomes the emitted instrument id.
+Start with the money flows library (open/hsx/std). Import a money flow by export name from `std/money_flows`, then apply it under a local settlement name. The local name becomes the emitted instrument id.
 
 ```hsx
 program equipment_hire "Equipment hire"
-import { scheduled } from "std/settlements"
+import { scheduled } from "std/money_flows"
 party renter: person
 party owner: business
 settlement installments = scheduled {
@@ -19,4 +19,45 @@ settlement installments = scheduled {
 
 Required parameters state the instrument's core contract. Optional parameters add bounded behavior such as a deadline, cancellation allocation, fee, or policy. Omit an optional block when the product does not need it. Do not pass an empty block as a substitute unless the module documents that form.
 
-The generated standard-library reference lists every module, parameter, action, port, and emitted clause. Read that page before choosing a module. Prefer one module that already states the required lifecycle over a custom instrument with copied mechanics.
+The generated money flows reference lists every module, parameter, action, port, and emitted clause. Read that page before choosing a module. Prefer one module that already states the required lifecycle over a custom instrument with copied mechanics.
+
+## Account fields
+
+When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
+
+```hsx
+fields {
+  customerAccountId: account<SAR>;
+  amount: money<SAR>;
+}
+```
+
+## Port declarations and action clauses
+
+HSX supports two distinct port syntaxes depending on scope:
+
+1. **Top-level port declarations** declare a named port at program scope using `allowed: [...]`.
+2. **Action-level port clauses** define caller permissions directly inside an instrument action using `allowed_parties: [...]`.
+
+Top-level port declaration:
+
+```hsx
+port confirm_delivery {
+  allowed: [buyer];
+}
+```
+
+Action-level port clause:
+
+```hsx
+action release {
+  agent_description: "Release escrowed funds to the payee."
+  steps: [];
+  moves: [];
+  port {
+    allowed_parties: [payer];
+  }
+}
+```
+
+Writing `allowed:` inside an action-level `port` clause triggers diagnostic `HSX1508`. Use `allowed_parties: [...]` inside action clauses, and reserve `allowed: [...]` for top-level port declarations.

package/docs/guide/04-lifecycles.md

@@ -5,6 +5,7 @@ A lifecycle lists every state, names one initial state, and declares action tran
 ```hsx
 program approvals "Approvals"
 instrument approval {
+  agent_description: "Manage a bounded approval decision across pending, approved, and rejected states."
   title: "Approval"
   summary: "A bounded approval decision"
   fields {}
@@ -14,12 +15,26 @@ instrument approval {
     on approve: pending -> approved;
     on reject: pending -> rejected;
   }
-  action create { steps: []; moves: []; }
-  action approve { steps: []; moves: []; }
-  action reject { steps: []; moves: []; }
+  action create {
+    agent_description: "Create an approval record in pending state."
+    steps: [];
+    moves: [];
+  }
+  action approve {
+    agent_description: "Approve the pending decision."
+    steps: [];
+    moves: [];
+  }
+  action reject {
+    agent_description: "Reject the pending decision."
+    steps: [];
+    moves: [];
+  }
 }
 ```
 
+Every callable custom instrument action becomes an agent tool and requires an `agent_description` string. Instruments that declare callable actions also require an `agent_description` string. Actions that declare a `due` clause are exempt system actions that run on a schedule instead of an agent call. The compiler emits `HSX1509` when an author omits `agent_description` on an instrument or callable action.
+
 Standard-library instruments bind ports to caller decisions. A deadline appears as stored date data and a `due` clause on the action that may run at that date. An unwind states how a failed or cancelled path drains held value. The compiler refuses a reachable exit that strands money.
 
 Keep lifecycle changes additive after composition. Add a new action or state when old instances can still obey the previous contract. Do not rename a state or tighten an active transition in place.

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

@@ -4,7 +4,7 @@ Standard-library payment modules accept bounded fee forms. A payer fee sits on t
 
 ```hsx
 program lesson_market "Lesson market"
-import { instant_transfer, pooled_split } from "std/settlements"
+import { instant_transfer, pooled_split } from "std/money_flows"
 party student: person
 party tutor: business
 party assistant: business
@@ -29,7 +29,7 @@ Every percentage partition must total 100 percent. `pooled_split` distributes a
 
 ```hsx
 program studio_booking "Studio booking"
-import { cancellable_booking } from "std/settlements"
+import { cancellable_booking } from "std/money_flows"
 party guest: person
 party studio: business
 settlement session = cancellable_booking {

package/docs/guide/06-schedules.md

@@ -4,7 +4,7 @@ HSX schedules are finite. A literal `count`, an interval, and a first due date l
 
 ```hsx
 program installments "Installments"
-import { scheduled } from "std/settlements"
+import { scheduled } from "std/money_flows"
 party buyer: person
 party seller: business
 settlement plan = scheduled {

package/docs/guide/07-composition.md

@@ -4,7 +4,7 @@ One program can apply several instruments. Each instrument keeps its own lifecyc
 
 ```hsx
 program studio_sales "Studio sales"
-import { instant_transfer, scheduled } from "std/settlements"
+import { instant_transfer, scheduled } from "std/money_flows"
 party buyer: person
 party studio: business
 settlement purchase = instant_transfer {
@@ -31,7 +31,7 @@ Keep each money route in one instrument. Connect instruments with evidence and r
 
 ```hsx
 program supplier_payment "Supplier payment"
-import { reconciled_payout } from "std/settlements"
+import { reconciled_payout } from "std/money_flows"
 party treasury: business
 party supplier: business
 settlement payout = reconciled_payout {
@@ -44,3 +44,9 @@ settlement payout = reconciled_payout {
   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

@@ -5,6 +5,7 @@ A module is ordinary HSX source. It declares a dotted module name and exports te
 ```hsx
 program approval_example "Approval example"
 instrument approval() {
+  agent_description: "Reusable approval lifecycle template."
   title: "Approval"
   summary: "A reusable approval lifecycle"
   fields {}
@@ -13,12 +14,22 @@ instrument approval() {
     initial pending;
     on approve: pending -> approved;
   }
-  action create { steps: []; moves: []; }
-  action approve { steps: []; moves: []; }
+  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.

package/docs/guide/09-cost.md

@@ -4,7 +4,7 @@ Compilation emits a deterministic cost manifest beside the UDL document. The man
 
 ```hsx
 program direct_sale "Direct sale"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party buyer: person
 party seller: business
 settlement sale = instant_transfer {
@@ -17,8 +17,8 @@ settlement sale = instant_transfer {
 
 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.
+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`. Use the single rate card shipped at `examples/cost-table.json`; do not create a second table for documentation.
+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. 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

@@ -13,7 +13,7 @@ Use one loop: compile, find the first error code in the diagnostics reference, a
 
 ```hsx
 program repaired_transfer "Repaired transfer"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party sender: person
 party recipient: business
 settlement transfer = instant_transfer {