@hyperscale0/hsx 1.0.0 → 2.0.0

package/examples/security_deposit/security_deposit.hsx

@@ -1,5 +1,5 @@
 program deposit_example "Deposit example"
-import { security_deposit } from "std/settlements"
+import { security_deposit } from "std/money_flows"
 party renter: person
 party owner: business
 settlement security_deposit = security_deposit {

package/examples/security_deposit/security_deposit.udl

@@ -37,9 +37,10 @@
             "additionalProperties": false,
             "properties": {
               "damageAmount": {
-                "description": "Caller-decided amount in minor units",
+                "description": "Decided amount in SAR minor units",
                 "pattern": "^(0|[1-9][0-9]{0,17})$",
-                "type": "string"
+                "type": "string",
+                "x-hyperscale-currency": "SAR"
               },
               "evidence": {
                 "description": "Required decision reference retained in the operation receipt",
@@ -168,12 +169,19 @@
             }
           ],
           "publicAction": "placeDepositSecurityDeposit",
+          "sandboxFailurePoint": "funding",
           "steps": [],
           "summary": "Reserve the depositAmount against the renter's account"
         },
         "return_deposit": {
           "agentDescription": "Return the held deposit to the renter. The deposit must be in held and unclaimed. This releases the reservation whole and the owner receives nothing.",
           "effects": {
+            "decides": [
+              {
+                "signature": "decides.tenant_port",
+                "source": "port"
+              }
+            ],
             "moves": [
               {
                 "signature": "moves.transfer.internal",
@@ -197,6 +205,11 @@
               "operation": "internal_transfer.void"
             }
           ],
+          "port": {
+            "allowedParties": [
+              "beneficiary"
+            ]
+          },
           "publicAction": "returnDepositSecurityDeposit",
           "steps": [],
           "summary": "Return the deposit to the renter through return_deposit"
@@ -215,7 +228,8 @@
         "depositAmount": {
           "description": "The deposit amount in SAR minor units, reserved in full and fully accounted on claim or return",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "ownerAccountId": {
           "description": "The owner account",

package/examples/settlement_batch/settlement_batch.hsx

@@ -1,5 +1,5 @@
 program settlement_batch_example "Settlement batch example"
-import { settlement_batch } from "std/settlements"
+import { settlement_batch } from "std/money_flows"
 party settlement_account: business
 party payout_destination: business
 settlement batch = settlement_batch {

package/examples/swap/swap.hsx

@@ -1,5 +1,5 @@
 program swap_example "Swap example"
-import { swap } from "std/settlements"
+import { swap } from "std/money_flows"
 party buyer: business
 party seller: business
 settlement exchange = swap {

package/examples/swap/swap.udl

@@ -160,7 +160,7 @@
           "summary": "Create a exchange atomic trade"
         },
         "dispute": {
-          "agentDescription": "Claw back a released trade inside its dispute window. Both cross-payment reservations void and both principals return from escrow in one batch. The trade must be released and the clawback moment must not have passed. Either trading party may call it.",
+          "agentDescription": "Claw back a released trade inside its dispute window. Both cross-payment reservations void and both principals return from escrow in one batch. The trade must be released and the clawback moment must not have passed. The dispute port's declared parties may call it.",
           "deadline": {
             "field": "clawbackAt"
           },
@@ -515,6 +515,7 @@
             }
           ],
           "publicAction": "fundExchange",
+          "sandboxFailurePoint": "funding",
           "steps": [],
           "summary": "Fund both trade sides and collect on-top fees atomically"
         },
@@ -566,7 +567,7 @@
           "summary": "Post both trade reservations when the clawback window matures"
         },
         "release": {
-          "agentDescription": "Reserve each side's principal for the other side and start the dispute window. The trade must be funded. Money is reserved, not settled. It posts on its own when the window matures, and dispute unwinds it before then. Either trading party may call it.",
+          "agentDescription": "Reserve each side's principal for the other side and start the dispute window. The trade must be funded. Money is reserved, not settled. It posts on its own when the window matures, and dispute unwinds it before then. The release port's declared parties may call it.",
           "effects": {
             "decides": [
               {
@@ -694,6 +695,7 @@
             ]
           },
           "publicAction": "releaseExchange",
+          "sandboxFailurePoint": "release",
           "setsAt": {
             "field": "clawbackAt",
             "offset": "P7D"
@@ -744,12 +746,14 @@
         "buyerAmount": {
           "description": "Side A amount in SAR minor units, held against the whole trade",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "buyerFee": {
           "description": "Immutable exact buyer service fee in SAR minor units",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "clawbackAt": {
           "description": "Machine-owned end of the P7D whole-trade dispute window",
@@ -790,12 +794,14 @@
         "sellerAmount": {
           "description": "Side B amount in SAR minor units, held against the whole trade",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "sellerFee": {
           "description": "Immutable exact seller service fee in SAR minor units",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         }
       },
       "id": "exchange",

package/examples/threshold_pool/threshold_pool.hsx

@@ -1,5 +1,5 @@
 program capital_pool_example "Capital pool example"
-import { threshold_pool } from "std/settlements"
+import { threshold_pool } from "std/money_flows"
 party contributor: person
 party company: business
 settlement round = threshold_pool {

package/examples/threshold_pool/threshold_pool.udl

@@ -173,7 +173,8 @@
         "targetAmount": {
           "description": "Funding target in SAR minor units",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         }
       },
       "id": "round",
@@ -576,7 +577,8 @@
         "amount": {
           "description": "One whole commitment amount",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "companyAccountId": {
           "description": "The company account",

package/examples/weighted_distribution/weighted_distribution.hsx

@@ -1,5 +1,5 @@
 program weighted_distribution_example "Weighted distribution example"
-import { weighted_distribution } from "std/settlements"
+import { weighted_distribution } from "std/money_flows"
 party distribution_source: business
 party recipient: business
 settlement proceeds = weighted_distribution {

package/examples/weighted_distribution/weighted_distribution.udl

@@ -77,7 +77,8 @@
         "distributableAmount": {
           "description": "Distribution pool in SAR minor units",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "distributionSourceAccountId": {
           "description": "The distribution source account",
@@ -278,7 +279,8 @@
         "entitlementWeight": {
           "description": "Stored non-negative entitlement weight",
           "pattern": "^[1-9][0-9]{0,17}$",
-          "type": "string"
+          "type": "string",
+          "x-hyperscale-currency": "SAR"
         },
         "proceedsId": {
           "description": "The exact proceeds",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -85,15 +85,16 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@hyperscale0/udl": "1.0.0"
+    "@hyperscale0/udl": "2.0.0"
   },
   "devDependencies": {
-    "@types/bun": "1.4.0",
-    "typescript": "6.0.3"
+    "bun-types": "1.4.2",
+    "typescript": "7.0.2"
   },
   "contributors": [
     "Meshael AlBakaawi",
     "Amir Ayub",
     "Sara AlBakaawi"
-  ]
+  ],
+  "gitHead": "e557d602bb119778f75346179eef480b6e3deb8a"
 }

package/skills/hsx/SKILL.md

@@ -5,15 +5,15 @@ description: Write, review, and repair HSX programs that compile financial-produ
 
 # Write HSX
 
-Use this skill when a task creates or changes an `.hsx` program, chooses a standard-library settlement form, explains an HSX diagnostic, or reviews authored money rules. Do not use it to hand-edit canonical UDL or runtime state.
+Use this skill when a task creates or changes an `.hsx` program, chooses a money flow from the money flows library (open/hsx/std), explains an HSX diagnostic, or reviews authored money rules. Do not use it to hand-edit canonical UDL or runtime state.
 
 ## Program shape
 
-One file declares one `program`. Declare parties and assets before using them. Import standard-library instruments from `std/settlements`. Apply each selected instrument as a `settlement`, and declare every decision port it names. A program may also declare general instruments and subjects.
+One file declares one `program`. Declare parties and assets before using them. Import money flows from `std/money_flows`. Apply each selected instrument as a `settlement`, and declare every decision port it names. A program may also declare general instruments and subjects.
 
-Start with [the first-program guide](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/01-first-program.md). Read the generated [grammar](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/grammar.md), [types](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/types.md), and [standard-library pages](https://github.com/hyperscale0/hyperscale-hsx/tree/main/docs/reference/std) for the exact surface.
+Start with [the first-program guide](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/01-first-program.md). Read the generated [grammar](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/grammar.md), [types](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/types.md), and [money flows reference](https://github.com/hyperscale0/hyperscale-hsx/tree/main/docs/reference/std) for the exact surface.
 
-## Choose a standard instrument
+## Choose a money flow
 
 Choose the module whose lifecycle and money path already match the product. Do not copy its emitted mechanics into a custom instrument.
 
@@ -35,7 +35,7 @@ Choose the module whose lifecycle and money path already match the product. Do n
 - `settlement_batch` closes, calculates, approves, instructs, acknowledges, and reconciles a batch.
 - `swap` exchanges two independently typed sides.
 
-The standard library forms are demonstrated below. The marker before each program lets the repository test read the module list from disk and compile one matching example per module.
+The money flows are demonstrated below. The marker before each program lets the repository test read the module list from disk and compile one matching example per module.
 
 ## Diagnostic loop
 
@@ -54,13 +54,13 @@ Run `hsx check` after each coherent edit. Read the first error code, open the [d
 
 The [money](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/02-money.md), [fees and splits](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/05-fees-and-splits.md), [schedules](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/06-schedules.md), and [cost](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/09-cost.md) chapters explain these rules.
 
-## Standard-library witnesses
+## Money flow witnesses
 
 <!-- hsx-brick: advance -->
 
 ```hsx
 program advance_example "Advance example"
-import { advance } from "std/settlements"
+import { advance } from "std/money_flows"
 party funder: business
 party recipient: business
 settlement advance_payment = advance {
@@ -78,7 +78,7 @@ settlement advance_payment = advance {
 
 ```hsx
 program cancellable_booking_example "Cancellable booking example"
-import { cancellable_booking } from "std/settlements"
+import { cancellable_booking } from "std/money_flows"
 party guest: person
 party studio: business
 settlement studio_session = cancellable_booking {
@@ -97,7 +97,7 @@ settlement studio_session = cancellable_booking {
 
 ```hsx
 program captured_payment_example "Captured payment example"
-import { captured_payment } from "std/settlements"
+import { captured_payment } from "std/money_flows"
 party payer: person
 party payee: business
 settlement card_payment = captured_payment {
@@ -123,7 +123,7 @@ port reverse_capture {
 
 ```hsx
 program conditional_disbursement_example "Conditional disbursement example"
-import { conditional_disbursement } from "std/settlements"
+import { conditional_disbursement } from "std/money_flows"
 party source: business
 party claimant: person
 settlement claim_payment = conditional_disbursement {
@@ -145,7 +145,7 @@ port approve_claim {
 
 ```hsx
 program credit_facility_example "Credit facility example"
-import { credit_facility, scheduled } from "std/settlements"
+import { credit_facility, scheduled } from "std/money_flows"
 party lender: business
 party borrower: business
 party draw_destination: business
@@ -177,7 +177,7 @@ settlement facility = credit_facility {
 
 ```hsx
 program deposit_example "Deposit example"
-import { security_deposit } from "std/settlements"
+import { security_deposit } from "std/money_flows"
 party renter: person
 party owner: business
 settlement security_deposit = security_deposit {
@@ -203,7 +203,7 @@ port return_deposit { allowed: [owner] }
 
 ```hsx
 program capital_pool_example "Capital pool example"
-import { threshold_pool } from "std/settlements"
+import { threshold_pool } from "std/money_flows"
 party contributor: person
 party company: business
 settlement round = threshold_pool {
@@ -224,7 +224,7 @@ settlement round = threshold_pool {
 
 ```hsx
 program held_payment_example "Held payment example"
-import { held_payment } from "std/settlements"
+import { held_payment } from "std/money_flows"
 party buyer: person
 party seller: business
 settlement sale = held_payment {
@@ -242,7 +242,7 @@ port confirm_delivery { allowed: [buyer] }
 
 ```hsx
 program instant_transfer_example "Instant transfer example"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party customer: person
 party merchant: business
 settlement transfer = instant_transfer {
@@ -263,7 +263,7 @@ settlement transfer = instant_transfer {
 
 ```hsx
 program metered_example "Metered example"
-import { metered } from "std/settlements"
+import { metered } from "std/money_flows"
 party customer: business
 party provider: business
 settlement usage = metered {
@@ -281,7 +281,7 @@ settlement usage = metered {
 
 ```hsx
 program pooled_split_example "Pooled split example"
-import { pooled_split } from "std/settlements"
+import { pooled_split } from "std/money_flows"
 party payer: business
 party first_recipient: business
 party second_recipient: business
@@ -301,7 +301,7 @@ settlement pool = pooled_split {
 
 ```hsx
 program premium_forward_example "Premium forward example"
-import { premium_forward } from "std/settlements"
+import { premium_forward } from "std/money_flows"
 party policyholder: person
 party carrier: business
 settlement premium = premium_forward {
@@ -325,7 +325,7 @@ port record_endorsement {
 
 ```hsx
 program reconciled_payout_example "Reconciled payout example"
-import { reconciled_payout } from "std/settlements"
+import { reconciled_payout } from "std/money_flows"
 party treasury: business
 party supplier: business
 settlement supplier_payout = reconciled_payout {
@@ -343,7 +343,7 @@ settlement supplier_payout = reconciled_payout {
 
 ```hsx
 program recurring_collection_example "Recurring collection example"
-import { recurring_collection, scheduled } from "std/settlements"
+import { recurring_collection, scheduled } from "std/money_flows"
 party debtor: person
 party repayment_source: business
 party recipient: business
@@ -369,7 +369,7 @@ port mandate_evidence {
 
 ```hsx
 program rotating_pool_example "Rotating pool example"
-import { rotating_pool } from "std/settlements"
+import { rotating_pool } from "std/money_flows"
 party member_a: person
 party member_b: person
 party member_c: person
@@ -392,7 +392,7 @@ settlement pool = rotating_pool {
 
 ```hsx
 program scheduled_example "Scheduled example"
-import { scheduled } from "std/settlements"
+import { scheduled } from "std/money_flows"
 party payer: business
 party payee: business
 settlement installments = scheduled {
@@ -409,7 +409,7 @@ settlement installments = scheduled {
 
 ```hsx
 program settlement_batch_example "Settlement batch example"
-import { settlement_batch } from "std/settlements"
+import { settlement_batch } from "std/money_flows"
 party settlement_account: business
 party payout_destination: business
 settlement batch = settlement_batch {
@@ -433,7 +433,7 @@ port acknowledge_payout {
 
 ```hsx
 program swap_example "Swap example"
-import { swap } from "std/settlements"
+import { swap } from "std/money_flows"
 party buyer: business
 party seller: business
 settlement exchange = swap {
@@ -457,7 +457,7 @@ port dispute_exchange { allowed: [buyer, seller] }
 
 ```hsx
 program weighted_distribution_example "Weighted distribution example"
-import { weighted_distribution } from "std/settlements"
+import { weighted_distribution } from "std/money_flows"
 party distribution_source: business
 party recipient: business
 settlement proceeds = weighted_distribution {
@@ -480,4 +480,4 @@ port snapshot_entitlements {
 
 ## Output boundary
 
-Use `compile` or the CLI to obtain canonical UDL, the origin map, and the cost manifest. The engine reads UDL and never HSX. When a task needs direct UDL work, use the UDL skill instead.
+Use `compile` or the Hyperscale CLI to obtain canonical UDL, the origin map, and the cost manifest. The engine reads UDL and never HSX. When a task needs direct UDL work, use the UDL skill instead.

package/src/ast.ts

@@ -268,6 +268,8 @@ export type Expr =
  * and `on_cancel(funded) { ... }` (key + qualifiers + block value).
  */
 export interface Entry {
+  /** Port dependencies retained through compile-time selection and substitution. */
+  readonly conditionPorts?: readonly string[];
   /** `for item in bound { ... }`, expanded before binding or UDL lowering. */
   readonly iteration?: {
     readonly binding: IdentExpr;
@@ -305,7 +307,7 @@ export interface ExposeDecl {
   readonly span: Span;
 }
 
-/** `import { held_payment } from "std/settlements"`. */
+/** `import { held_payment } from "std/money_flows"`. */
 export interface ImportDecl {
   readonly from: StringExpr;
   readonly kind: "import";
@@ -347,7 +349,7 @@ export interface PortDecl {
   readonly span: Span;
 }
 
-/** `module std.settlements` gives a file its importable module name. */
+/** `module std.money_flows` gives a file its importable module name. */
 export interface ModuleDecl {
   readonly kind: "module";
   readonly name: PathExpr;

package/src/cli.ts

@@ -12,7 +12,7 @@
 
 import { fileURLToPath } from "node:url";
 import { compile, type CompileResult } from "./compile.ts";
-import type { UdlCostManifest, UdlCostTable } from "./cost.ts";
+import type { UdlCostManifest, UdlCostTables } from "./cost.ts";
 import { hsxDiagnostics } from "./diagnostics.ts";
 import { format } from "./format.ts";
 import { startLspServer } from "./lsp/server.ts";
@@ -124,7 +124,7 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     return OK;
   }
 
-  let costTable: UdlCostTable;
+  let costTable: UdlCostTables;
   try {
     costTable = await readDefaultCostTable(io);
   } catch (cause) {
@@ -300,7 +300,7 @@ async function writeOutput(
   return OK;
 }
 
-async function readDefaultCostTable(io: Io): Promise<UdlCostTable> {
+async function readDefaultCostTable(io: Io): Promise<UdlCostTables> {
   const candidates = [
     fileURLToPath(new URL("../examples/cost-table.json", import.meta.url)),
     fileURLToPath(new URL("../../examples/cost-table.json", import.meta.url)),
@@ -308,7 +308,7 @@ async function readDefaultCostTable(io: Io): Promise<UdlCostTable> {
   let lastError: unknown;
   for (const path of candidates) {
     try {
-      return JSON.parse(await io.readFile(path)) as UdlCostTable;
+      return JSON.parse(await io.readFile(path)) as UdlCostTables;
     } catch (cause) {
       lastError = cause;
     }

package/src/compile.ts

@@ -16,7 +16,7 @@ import { lineColIn, lineIndex } from "./ast.ts";
 import {
   buildCostManifest,
   type UdlCostManifest,
-  type UdlCostTable,
+  type UdlCostTables,
 } from "./cost.ts";
 import { lowerGeneralProgram, type OriginMapEntry } from "./emit.ts";
 import {
@@ -41,6 +41,8 @@ export interface CompileDiagnostic {
   readonly message: string;
   /** Source offsets in UTF-16 code units, matching parser and checker spans. */
   readonly span: { readonly end: number; readonly start: number };
+  /** UTF-8 byte span in root source, omitted when referring to an imported module. */
+  readonly byteSpan?: { readonly end: number; readonly start: number };
   readonly code?: string;
   readonly fix?: string;
   /** Canonical UDL path when lowering rejected an emitted clause. */
@@ -63,7 +65,8 @@ interface CompileArtifacts {
 
 export interface CompileOptions extends HsxCompilerHost {
   readonly composesCatalogBlueprint?: boolean;
-  readonly costTable?: UdlCostTable;
+  /** One table, or one per billing currency; the program's money fields pick. */
+  readonly costTable?: UdlCostTables;
 }
 
 export interface CompileOriginMapEntry {
@@ -113,7 +116,15 @@ export function compile(
     const position = origin ?? lineColIn(lines, span.start);
     diagnostics.push({
       column: position.column,
-      ...(origin ? { file: origin.moduleName } : {}),
+      ...(origin
+        ? { file: origin.moduleName }
+        : {
+            byteSpan: {
+              end:
+                byteOffsets[span.end] ?? byteOffsets[byteOffsets.length - 1]!,
+              start: byteOffsets[span.start] ?? 0,
+            },
+          }),
       line: position.line,
       message,
       span: { ...span },