@hyperscale0/hsx 2.1.0 → 2.2.0

package/examples/security_deposit/security_deposit.udl

@@ -296,6 +296,19 @@
         "currency"
       ],
       "summary": "Refundable deposit from renter held for owner",
+      "templateBinding": {
+        "id": "security_deposit",
+        "parameters": {
+          "claimCapture": false,
+          "claimInput": false,
+          "claimTo": false,
+          "deadline": false,
+          "fundFailurePoint": false,
+          "idPrefixOverride": false,
+          "memo": false,
+          "returnTo": false
+        }
+      },
       "title": "Security deposit"
     }
   ],

package/examples/settlement_batch/settlement_batch.udl

@@ -302,6 +302,10 @@
         "payoutBeneficiaryId"
       ],
       "summary": "Payout batch from settlement account to payout destination",
+      "templateBinding": {
+        "id": "settlement_batch",
+        "parameters": {}
+      },
       "title": "Batch"
     },
     {

package/examples/swap/swap.udl

@@ -871,6 +871,16 @@
         "currency"
       ],
       "summary": "Two-party atomic trade between buyer and seller",
+      "templateBinding": {
+        "id": "swap",
+        "parameters": {
+          "actionBindings": false,
+          "fixedPrefix": false,
+          "lifecycleStateOrder": false,
+          "parkedStates": false,
+          "sideNames": false
+        }
+      },
       "title": "Exchange"
     }
   ],

package/examples/threshold_pool/threshold_pool.udl

@@ -219,6 +219,17 @@
         "maxContributors"
       ],
       "summary": "Threshold contribution pool for company",
+      "templateBinding": {
+        "id": "threshold_pool",
+        "parameters": {
+          "beneficiaryAccount": false,
+          "contributionInstrument": false,
+          "fundingJoin": false,
+          "maxContributors": 100,
+          "memo": false,
+          "wording": false
+        }
+      },
       "title": "Round"
     },
     {

package/examples/weighted_distribution/weighted_distribution.udl

@@ -130,6 +130,15 @@
         "maxRecipients"
       ],
       "summary": "Frozen largest-remainder distribution",
+      "templateBinding": {
+        "id": "weighted_distribution",
+        "parameters": {
+          "flat": false,
+          "idPrefixOverride": false,
+          "maxRecipients": 12,
+          "receipts": false
+        }
+      },
       "title": "Proceeds"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -70,22 +70,22 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "check": "bun test && bun run docs:check && bun run std:check && bun run playground:check && tsc -p tsconfig.json && bun run build && bun scripts/check-bin.ts",
-    "docs:build": "bun scripts/docs/build.ts",
-    "docs:check": "bun scripts/docs/check.ts",
+    "build": "bun run generate && tsc -p tsconfig.build.json",
+    "check": "bun run generate && bun test && bun run playground:check && tsc -p tsconfig.json && bun run build && bun scripts/check-bin.ts",
+    "docs:build": "bun scripts/docs/build.ts && bun scripts/docs/check.ts",
     "examples:build": "bun scripts/examples/build.ts",
     "playground:build": "bun scripts/build-playground.ts",
     "playground:check": "bun scripts/build-playground.ts --check",
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "std:bundle": "bun scripts/bundle-std.ts",
-    "std:check": "bun scripts/bundle-std.ts --check",
-    "test": "bun test",
-    "typecheck": "tsc -p tsconfig.json"
+    "test": "bun run generate && bun test",
+    "typecheck": "bun run generate && tsc -p tsconfig.json",
+    "prepare": "bun run std:bundle",
+    "generate": "bun run std:bundle && bun run docs:build && bun run playground:build"
   },
   "dependencies": {
-    "@hyperscale0/udl": "2.1.0"
+    "@hyperscale0/udl": "2.4.0"
   },
   "devDependencies": {
     "bun-types": "1.4.2",
@@ -96,5 +96,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "a62e6700e728f3ab56aa9de12ff83e669540511b"
+  "gitHead": "b2d3d1954db0038f654894b1be983ad2bae7c2d0"
 }

package/skills/hsx/SKILL.md

@@ -23,7 +23,6 @@ Choose the module whose lifecycle and money path already match the product. Do n
 - `cancellable_booking` quotes a cancellation penalty before commitment.
 - `captured_payment` reserves, captures, settles, voids, or corrects a payment.
 - `scheduled` expands finite installments or a bounded obligation.
-- `recurring_collection` records collection periods.
 - `advance` disburses now against finite repayment or a referenced release.
 - `credit_facility` controls draws against a referenced obligation.
 - `conditional_disbursement` releases a capped amount on stored evidence.
@@ -107,10 +106,6 @@ settlement card_payment = captured_payment {
   reserve_until: reserveUntil
   correction: port correct_capture
   external_reversal: port reverse_capture within P14D
-  capture_mode: partial_then_full
-  correction_mode: full_only
-  negative_position: reject
-  timeout: reject
 }
 port correct_capture { allowed: [payee] }
 port reverse_capture {
@@ -132,8 +127,6 @@ settlement claim_payment = conditional_disbursement {
   cap: policyLimit: money(SAR)
   amount: approvedAmount: money(SAR)
   decision: port approve_claim
-  reopen_policy: refuse
-  recovery_policy: separate_transfer
 }
 port approve_claim {
   allowed: [source]
@@ -167,9 +160,6 @@ settlement facility = credit_facility {
   limit: facilityLimit: money(SAR)
   expires_at: expiresAt
   obligation: repayment.obligation
-  availability_policy: revolving
-  expiry_policy: freeze_draws
-  close_policy: no_open_draws
 }
 ```
 
@@ -339,32 +329,6 @@ settlement supplier_payout = reconciled_payout {
 }
 ```
 
-<!-- hsx-brick: recurring_collection -->
-
-```hsx
-program recurring_collection_example "Recurring collection example"
-import { recurring_collection, scheduled } from "std/money_flows"
-party debtor: person
-party repayment_source: business
-party recipient: business
-settlement obligation = scheduled {
-  mode: obligation
-  payer: repayment_source
-  payee: recipient
-  debtor: debtor
-  amount: principal: money(SAR)
-  count: 2
-  every: P30D
-  first_due: firstDueAt
-  mandate: port mandate_evidence
-}
-settlement collection = recurring_collection {}
-port mandate_evidence {
-  allowed: [repayment_source]
-  shape: { evidenceReference: text }
-}
-```
-
 <!-- hsx-brick: rotating_pool -->
 
 ```hsx
@@ -481,3 +445,5 @@ port snapshot_entitlements {
 ## Output boundary
 
 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.
+
+Programs that `use` published instruments need the selected catalogue when checked outside the engine: `hsx check --strict --catalog catalog.udl company.hsx`. Obtain that canonical UDL from the catalogue publisher. The CLI does not fetch or choose a revision.

package/src/cli.ts

@@ -10,6 +10,7 @@
  * asserting on a subprocess's scrollback.
  */
 
+import { parseUdl, type UdlDocument } from "@hyperscale0/udl";
 import { fileURLToPath } from "node:url";
 import { compile, type CompileResult } from "./compile.ts";
 import type { UdlCostManifest, UdlCostTables } from "./cost.ts";
@@ -39,9 +40,9 @@ const USAGE = 2;
 export const USAGE_TEXT = `hsx ${HSX_VERSION}, the HSX compiler
 
 Usage:
-  hsx check <file.hsx> [--strict]
-  hsx build <file.hsx> [--out <file.json>] [--strict]
-  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  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
@@ -57,6 +58,7 @@ Commands:
   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.
@@ -134,7 +136,21 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     io.err(`hsx: cannot read the packaged cost table: ${messageOf(cause)}`);
     return USAGE;
   }
-  const result = compile(source, { costTable });
+  let publishedCatalog: UdlDocument | undefined;
+  if (parsed.catalog !== undefined) {
+    try {
+      publishedCatalog = parseUdl(await io.readFile(parsed.catalog));
+    } catch (cause) {
+      io.err(
+        `hsx: cannot read catalogue ${parsed.catalog}: ${messageOf(cause)}`,
+      );
+      return USAGE;
+    }
+  }
+  const result = compile(source, {
+    costTable,
+    ...(publishedCatalog === undefined ? {} : { publishedCatalog }),
+  });
   for (const line of diagnosticLines(parsed.file, result)) io.err(line);
 
   const refused =
@@ -174,6 +190,7 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
 }
 
 interface Options {
+  readonly catalog?: string;
   readonly file: string;
   readonly json: boolean;
   readonly out?: string;
@@ -185,6 +202,7 @@ function parseOptions(
   command: "build" | "check" | "cost" | "format",
 ): Options | { readonly error: string } {
   let file: string | undefined;
+  let catalog: string | undefined;
   let json = false;
   let out: string | undefined;
   let strict = false;
@@ -203,6 +221,18 @@ function parseOptions(
       json = true;
       continue;
     }
+    if (argument === "--catalog") {
+      if (command === "format")
+        return { error: "--catalog belongs to check, build or cost" };
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--"))
+        return { error: "--catalog needs a file path" };
+      if (catalog !== undefined)
+        return { error: "--catalog may be supplied only once" };
+      catalog = value;
+      index += 1;
+      continue;
+    }
     if (argument === "--out") {
       if (command !== "build" && command !== "cost") {
         return { error: "--out belongs to hsx build or hsx cost" };
@@ -225,7 +255,13 @@ function parseOptions(
   }
 
   if (file === undefined) return { error: `hsx ${command} needs a file` };
-  return { file, json, ...(out === undefined ? {} : { out }), strict };
+  return {
+    file,
+    json,
+    ...(catalog === undefined ? {} : { catalog }),
+    ...(out === undefined ? {} : { out }),
+    strict,
+  };
 }
 
 function explainDiagnostic(args: readonly string[], io: Io): number {

package/src/compile.ts

@@ -66,7 +66,6 @@ interface CompileArtifacts {
 }
 
 export interface CompileOptions extends HsxCompilerHost {
-  readonly composesCatalogBlueprint?: boolean;
   /** One table, or one per billing currency; the program's money fields pick. */
   readonly costTable?: UdlCostTables;
 }
@@ -136,6 +135,19 @@ export function compile(
     });
   };
 
+  const optionKeys = new Set([
+    "costTable",
+    "moduleName",
+    "publishedCatalog",
+    "resolveModule",
+    "standardLibrary",
+  ]);
+  for (const key of Object.keys(options)) {
+    if (optionKeys.has(key)) continue;
+    at("bind", "error", `unknown compile option ${key}`, { start: 0, end: 0 });
+  }
+  if (diagnostics.length > 0) return { diagnostics, verdict: "invalid" };
+
   const parsed = parseProgram(source);
   for (const diagnostic of parsed.diagnostics) {
     at(
@@ -185,11 +197,7 @@ export function compile(
     );
   }
   if (!checked.program) return { diagnostics, verdict: "invalid" };
-  const cost = buildCostManifest(
-    checked.program,
-    options.costTable,
-    options.composesCatalogBlueprint ?? false,
-  );
+  const cost = buildCostManifest(checked.program, options.costTable);
   if (!cost.ok) {
     for (const diagnostic of cost.diagnostics) {
       at(

package/src/cost.ts

@@ -90,7 +90,6 @@ export type CostManifestResult =
 export function buildCostManifest(
   program: TypedProgram,
   tables: UdlCostTables | undefined,
-  composesCatalogBlueprint: boolean,
 ): CostManifestResult {
   const priced = tables === undefined ? [] : [tables].flat();
   if (priced.length === 0) {
@@ -164,7 +163,7 @@ export function buildCostManifest(
     }
   }
   const fixed = fixedCost(
-    typedStructuralCounts(program, composesCatalogBlueprint),
+    typedStructuralCounts(program),
     table,
     program.origin,
     diagnostics,
@@ -222,11 +221,10 @@ function ledgerCostTable(
 export function computeUdlFixedCost(
   document: UdlDocument,
   table: UdlCostTable,
-  composesCatalogBlueprint: boolean,
 ): UdlCostManifest["fixed"] {
   const diagnostics: GeneralDiagnostic[] = [];
   const fixed = fixedCost(
-    udlStructuralCounts(document, composesCatalogBlueprint),
+    udlStructuralCounts(document),
     table,
     { start: 0, end: 0 },
     diagnostics,
@@ -238,7 +236,6 @@ export function computeUdlFixedCost(
 export function buildUdlCostManifest(
   document: UdlDocument,
   table: UdlCostTable,
-  composesCatalogBlueprint: boolean,
 ): UdlCostManifest {
   if (!CURRENCY.test(table.currency)) {
     throw new Error(
@@ -286,11 +283,7 @@ export function buildUdlCostManifest(
       );
     }
   }
-  return manifest(
-    table,
-    computeUdlFixedCost(document, table, composesCatalogBlueprint),
-    actions,
-  );
+  return manifest(table, computeUdlFixedCost(document, table), actions);
 }
 
 export function evaluateUdlCostManifest(
@@ -473,6 +466,16 @@ function fixedCost(
 ): UdlCostManifest["fixed"] {
   const components: UdlCostManifest["fixed"]["components"][number][] = [];
   let complexityScore = 0;
+  for (const weight of Object.keys(table.fixed.weights)) {
+    if (Object.hasOwn(counts, weight)) continue;
+    diagnostics.push({
+      code: "HSX1302",
+      fix: `remove the unknown ${weight} weight from cost table ${table.version}`,
+      message: `cost table ${table.version} has an unknown ${weight} complexity weight`,
+      severity: "error",
+      span,
+    });
+  }
   for (const [weight, count] of Object.entries(counts)) {
     if (count === 0) continue;
     const value = table.fixed.weights[weight];
@@ -518,7 +521,6 @@ function fixedCost(
 
 function typedStructuralCounts(
   program: TypedProgram,
-  blueprint: boolean,
 ): Readonly<Record<string, number>> {
   const subjectKinds = new Set<string>();
   const decisions = new Set<string>();
@@ -562,13 +564,11 @@ function typedStructuralCounts(
     aggregate,
     gate,
     timer,
-    blueprint,
   );
 }
 
 function udlStructuralCounts(
   document: UdlDocument,
-  blueprint: boolean,
 ): Readonly<Record<string, number>> {
   const subjectKinds = new Set<string>();
   const decisions = new Set<string>();
@@ -611,7 +611,6 @@ function udlStructuralCounts(
     aggregate,
     gate,
     timer,
-    blueprint,
   );
 }
 
@@ -625,7 +624,6 @@ function countRecord(
   aggregateInvariant: number,
   gate: number,
   timer: number,
-  blueprint: boolean,
 ): Readonly<Record<string, number>> {
   return {
     instrument,
@@ -637,7 +635,6 @@ function countRecord(
     aggregate_invariant: aggregateInvariant,
     gate,
     timer,
-    blueprint: blueprint ? 1 : 0,
   };
 }
 

package/src/parse.ts

@@ -1,3 +1,11 @@
+import { udlClauseVocabulary } from "@hyperscale0/udl";
+
+const compoundClauseHeads = new Set(
+  udlClauseVocabulary
+    .filter((clause) => clause.spelling.includes(" "))
+    .map((clause) => clause.spelling.split(" ")[0]),
+);
+
 /**
  * The HSX parser. Recursive descent over the lexer's token stream, total:
  * it always returns a best-effort `Program` plus diagnostics, recovering at
@@ -495,15 +503,15 @@ class Parser {
     if (
       !this.expectPunct(
         "=",
-        `settlement ${name.name} instantiates an archetype: settlement ${name.name} = held_payment { ... }`,
+        `settlement ${name.name} instantiates a module: settlement ${name.name} = held_payment { ... }`,
       )
     ) {
       return undefined;
     }
-    const archetype = this.expectIdent(
-      `expected an archetype name for settlement ${name.name}`,
+    const moduleName = this.expectIdent(
+      `expected a module name for settlement ${name.name}`,
     );
-    if (!archetype) return undefined;
+    if (!moduleName) return undefined;
     if (!this.atPunct("{")) {
       this.error(
         this.peek().span,
@@ -521,9 +529,9 @@ class Parser {
           span: row.value.span,
           type: row.value,
         })),
-        callee: { kind: "path", parts: [archetype], span: archetype.span },
+        callee: { kind: "path", parts: [moduleName], span: moduleName.span },
         kind: "apply",
-        span: { start: archetype.span.start, end: body.span.end },
+        span: { start: moduleName.span.start, end: body.span.end },
         typeArgs: [],
       },
       exported: false,
@@ -807,10 +815,7 @@ class Parser {
       }
     }
 
-    if (
-      (key.name === "requires" || key.name === "computes") &&
-      this.isName(this.peek())
-    ) {
+    if (compoundClauseHeads.has(key.name) && this.isName(this.peek())) {
       while (this.isName(this.peek())) qualifiers.push(this.parseIdent());
     }