@hyperscale0/hsx 1.0.0-rc.1 → 2.0.0

package/src/compile.ts

@@ -1,7 +1,7 @@
 /**
  * The HSX compiler driver: source text in, three-verdict result out.
  *
- * - `valid`: the program lowers cleanly; the IR document and frame are ready
+ * - `valid`: the program lowers cleanly; the IR document is ready
  *   for the independent checker.
  * - `warning`: the program lowers, and the compiler's lint voice has notes
  *   the author should read (the artifacts are still present and usable).
@@ -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. */
@@ -55,8 +57,6 @@ export interface CompileDiagnostic {
 interface CompileArtifacts {
   /** The canonical UDL document. */
   readonly document: Json;
-  /** The congruent Business Frame. */
-  readonly frame: Json;
   /** Canonical UDL paths bound to their narrowest authored source terms. */
   readonly originMap: readonly CompileOriginMapEntry[];
   /** Deterministic compile-time cost, pinned to one versioned table. */
@@ -65,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 {
@@ -115,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 },
@@ -215,7 +224,6 @@ export function compile(
     artifacts: {
       document: lowered.value.document,
       costManifest: cost.manifest,
-      frame: lowered.value.frame,
       originMap: lowered.value.originMap.map(compileOrigin),
     },
     diagnostics,

package/src/cost.ts

@@ -3,10 +3,17 @@ import {
   type UdlDocument,
   type UdlEffectKind,
 } from "@hyperscale0/udl";
-import type { GeneralDiagnostic, JsonValue, TypedProgram } from "./ir.ts";
+import type {
+  GeneralDiagnostic,
+  JsonValue,
+  TypedField,
+  TypedProgram,
+} from "./ir.ts";
 
 export type HsxEffectKind = UdlEffectKind;
 
+const CURRENCY = /^[A-Z]{3}$/;
+
 export interface UdlCostTable {
   readonly version: string;
   /** Digest of the effective prices and fixed anchors after overrides. */
@@ -72,16 +79,20 @@ export interface UdlCostManifest {
   };
 }
 
+/** One cost table, or one per billing currency the host prices. */
+export type UdlCostTables = UdlCostTable | readonly UdlCostTable[];
+
 export type CostManifestResult =
   | { readonly diagnostics: readonly GeneralDiagnostic[]; readonly ok: false }
   | { readonly manifest: UdlCostManifest; readonly ok: true };
 
 export function buildCostManifest(
   program: TypedProgram,
-  table: UdlCostTable | undefined,
+  tables: UdlCostTables | undefined,
   composesCatalogBlueprint: boolean,
 ): CostManifestResult {
-  if (!table) {
+  const priced = tables === undefined ? [] : [tables].flat();
+  if (priced.length === 0) {
     return {
       diagnostics: [
         {
@@ -97,13 +108,16 @@ export function buildCostManifest(
     };
   }
 
-  if (!/^[A-Z]{3}$/.test(table.currency)) {
+  const malformed = priced.find(
+    (candidate) => !CURRENCY.test(candidate.currency),
+  );
+  if (malformed) {
     return {
       diagnostics: [
         {
           code: "HSX1303",
           fix: "name one three-letter uppercase billing currency on the cost table",
-          message: `cost table ${table.version} has invalid billing currency ${table.currency}`,
+          message: `cost table ${malformed.version} has invalid billing currency ${malformed.currency}`,
           severity: "error",
           span: program.origin,
         },
@@ -113,65 +127,39 @@ export function buildCostManifest(
   }
 
   const diagnostics: GeneralDiagnostic[] = [];
-  const rowsBySignature = new Map<string, UdlCostTable["rows"]>();
-  for (const row of table.rows) {
-    rowsBySignature.set(row.signature, [
-      ...(rowsBySignature.get(row.signature) ?? []),
-      row,
-    ]);
-  }
+  const table = ledgerCostTable(program, priced, diagnostics);
+  if (!table) return { diagnostics, ok: false };
+  const rowsBySignature = indexCostRows(table);
   const actions: UdlCostManifest["actions"][number][] = [];
   for (const instrument of program.instruments) {
     for (const action of instrument.actions) {
-      const components: UdlCostManifest["actions"][number]["components"][number][] =
-        [];
-      let productPerEvent = 0n;
-      let endCustomerPerEvent = 0n;
-      for (const [signature, count] of effectCounts(action.effects)) {
-        const rows = rowsBySignature.get(signature) ?? [];
-        if (rows.length === 0) {
-          diagnostics.push({
-            code: "HSX1301",
-            fix: `add ${signature} to cost table ${table.version}`,
-            message: `${instrument.id}.${action.name} has unpriced effect signature ${signature}`,
-            severity: "error",
-            span: action.origin,
-          });
-          continue;
-        }
-        for (const row of rows) {
-          if (!validPrice(row)) {
-            diagnostics.push({
-              code: "HSX1302",
-              fix: `store ${signature} prices as nonnegative integers and name a volume meter for bps`,
-              message: `cost table ${table.version} has an invalid ${signature} price`,
-              severity: "error",
-              span: action.origin,
-            });
-            continue;
-          }
-          const eventTotal = BigInt(row.perEventMinor) * BigInt(count);
-          if (row.payer === "product") productPerEvent += eventTotal;
-          else endCustomerPerEvent += eventTotal;
-          components.push({
-            bps: row.bps,
-            count,
-            meter: row.meter,
-            payer: row.payer,
-            perEventMinor: row.perEventMinor,
-            settlement: row.settlement,
-            signature,
-            ...(row.volumeMeter ? { volumeMeter: row.volumeMeter } : {}),
-          });
-        }
-      }
-      actions.push({
-        action: action.name,
-        components,
-        endCustomerPerEventMinor: endCustomerPerEvent.toString(),
-        instrument: instrument.id,
-        perEventMinor: productPerEvent.toString(),
-      });
+      actions.push(
+        priceAction(
+          instrument.id,
+          action.name,
+          effectCounts(action.effects),
+          rowsBySignature,
+          (issue) => {
+            if (issue.kind === "missing_price") {
+              diagnostics.push({
+                code: "HSX1301",
+                fix: `add ${issue.signature} to cost table ${table.version}`,
+                message: `${instrument.id}.${action.name} has unpriced effect signature ${issue.signature}`,
+                severity: "error",
+                span: action.origin,
+              });
+            } else {
+              diagnostics.push({
+                code: "HSX1302",
+                fix: `store ${issue.signature} prices as nonnegative integers and name a volume meter for bps`,
+                message: `cost table ${table.version} has an invalid ${issue.signature} price`,
+                severity: "error",
+                span: action.origin,
+              });
+            }
+          },
+        ),
+      );
     }
   }
   const fixed = fixedCost(
@@ -184,6 +172,52 @@ export function buildCostManifest(
   return { manifest: manifest(table, fixed, actions), ok: true };
 }
 
+/**
+ * The table priced in the program's ledger currency: the one currency its
+ * money fields move. A program without money fields prices in the host's
+ * first table.
+ */
+function ledgerCostTable(
+  program: TypedProgram,
+  tables: readonly UdlCostTable[],
+  diagnostics: GeneralDiagnostic[],
+): UdlCostTable | undefined {
+  const currencies = new Map<string, TypedField["origin"]>();
+  for (const instrument of program.instruments) {
+    for (const field of instrument.fields) {
+      // An unbound currency parameter (money<C>) is decided per instance,
+      // not by the program, so it names no ledger currency.
+      const currency = field.type.currency;
+      if (field.type.kind !== "money" || !currency || !CURRENCY.test(currency))
+        continue;
+      if (!currencies.has(currency)) currencies.set(currency, field.origin);
+    }
+  }
+  const [first, second] = [...currencies];
+  if (second) {
+    diagnostics.push({
+      code: "HSX1305",
+      fix: `move all money in ${first![0]}; a program bills in one ledger currency`,
+      message: `program moves money in ${[...currencies.keys()].join(" and ")}; a program bills in one ledger currency`,
+      severity: "error",
+      span: second[1],
+    });
+    return undefined;
+  }
+  const ledger = first?.[0] ?? tables[0]!.currency;
+  const table = tables.find((candidate) => candidate.currency === ledger);
+  if (table) return table;
+  const priced = tables.map((candidate) => candidate.currency).join(", ");
+  diagnostics.push({
+    code: "HSX1304",
+    fix: `move money in a priced currency: ${priced}`,
+    message: `program moves money in ${ledger}, which no cost table prices (priced: ${priced})`,
+    severity: "error",
+    span: first?.[1] ?? program.origin,
+  });
+  return undefined;
+}
+
 export function computeUdlFixedCost(
   document: UdlDocument,
   table: UdlCostTable,
@@ -205,25 +239,15 @@ export function buildUdlCostManifest(
   table: UdlCostTable,
   composesCatalogBlueprint: boolean,
 ): UdlCostManifest {
-  if (!/^[A-Z]{3}$/.test(table.currency)) {
+  if (!CURRENCY.test(table.currency)) {
     throw new Error(
       `cost table ${table.version} has invalid billing currency ${table.currency}`,
     );
   }
-  const rowsBySignature = new Map<string, UdlCostTable["rows"]>();
-  for (const row of table.rows) {
-    rowsBySignature.set(row.signature, [
-      ...(rowsBySignature.get(row.signature) ?? []),
-      row,
-    ]);
-  }
+  const rowsBySignature = indexCostRows(table);
   const actions: UdlCostManifest["actions"][number][] = [];
   for (const instrument of document.instruments) {
     for (const [actionName, action] of Object.entries(instrument.actions)) {
-      const components: UdlCostManifest["actions"][number]["components"][number][] =
-        [];
-      let productPerEvent = 0n;
-      let endCustomerPerEvent = 0n;
       const effects = (action.effects ?? {}) as Readonly<
         Partial<
           Record<
@@ -232,39 +256,24 @@ export function buildUdlCostManifest(
           >
         >
       >;
-      for (const [signature, count] of effectCounts(effects)) {
-        const rows = rowsBySignature.get(signature) ?? [];
-        if (rows.length === 0)
-          throw new Error(
-            `${instrument.id}.${actionName} has unpriced effect signature ${signature}`,
-          );
-        for (const row of rows) {
-          if (!validPrice(row))
+      actions.push(
+        priceAction(
+          instrument.id,
+          actionName,
+          effectCounts(effects),
+          rowsBySignature,
+          (issue) => {
+            if (issue.kind === "missing_price") {
+              throw new Error(
+                `${instrument.id}.${actionName} has unpriced effect signature ${issue.signature}`,
+              );
+            }
             throw new Error(
-              `cost table ${table.version} has an invalid ${signature} price`,
+              `cost table ${table.version} has an invalid ${issue.signature} price`,
             );
-          const eventTotal = BigInt(row.perEventMinor) * BigInt(count);
-          if (row.payer === "product") productPerEvent += eventTotal;
-          else endCustomerPerEvent += eventTotal;
-          components.push({
-            bps: row.bps,
-            count,
-            meter: row.meter,
-            payer: row.payer,
-            perEventMinor: row.perEventMinor,
-            settlement: row.settlement,
-            signature,
-            ...(row.volumeMeter ? { volumeMeter: row.volumeMeter } : {}),
-          });
-        }
-      }
-      actions.push({
-        action: actionName,
-        components,
-        endCustomerPerEventMinor: endCustomerPerEvent.toString(),
-        instrument: instrument.id,
-        perEventMinor: productPerEvent.toString(),
-      });
+          },
+        ),
+      );
     }
   }
   return manifest(
@@ -295,6 +304,69 @@ export function evaluateUdlCostManifest(
   return total.toString();
 }
 
+interface ActionPricingIssue {
+  readonly kind: "invalid_price" | "missing_price";
+  readonly signature: string;
+}
+
+function indexCostRows(
+  table: UdlCostTable,
+): ReadonlyMap<string, readonly UdlCostTable["rows"][number][]> {
+  const rowsBySignature = new Map<string, UdlCostTable["rows"][number][]>();
+  for (const row of table.rows) {
+    const existing = rowsBySignature.get(row.signature);
+    if (existing) existing.push(row);
+    else rowsBySignature.set(row.signature, [row]);
+  }
+  return rowsBySignature;
+}
+
+function priceAction(
+  instrument: string,
+  action: string,
+  counts: Iterable<readonly [string, number]>,
+  rowsBySignature: ReadonlyMap<string, readonly UdlCostTable["rows"][number][]>,
+  onIssue: (issue: ActionPricingIssue) => void,
+): UdlCostManifest["actions"][number] {
+  const components: UdlCostManifest["actions"][number]["components"][number][] =
+    [];
+  let productPerEvent = 0n;
+  let endCustomerPerEvent = 0n;
+  for (const [signature, count] of counts) {
+    const rows = rowsBySignature.get(signature);
+    if (!rows || rows.length === 0) {
+      onIssue({ kind: "missing_price", signature });
+      continue;
+    }
+    for (const row of rows) {
+      if (!validPrice(row)) {
+        onIssue({ kind: "invalid_price", signature });
+        continue;
+      }
+      const eventTotal = BigInt(row.perEventMinor) * BigInt(count);
+      if (row.payer === "product") productPerEvent += eventTotal;
+      else endCustomerPerEvent += eventTotal;
+      components.push({
+        bps: row.bps,
+        count,
+        meter: row.meter,
+        payer: row.payer,
+        perEventMinor: row.perEventMinor,
+        settlement: row.settlement,
+        signature,
+        ...(row.volumeMeter ? { volumeMeter: row.volumeMeter } : {}),
+      });
+    }
+  }
+  return {
+    action,
+    components,
+    endCustomerPerEventMinor: endCustomerPerEvent.toString(),
+    instrument,
+    perEventMinor: productPerEvent.toString(),
+  };
+}
+
 function manifest(
   table: UdlCostTable,
   fixed: UdlCostManifest["fixed"],

package/src/diagnostics.ts

@@ -9,11 +9,16 @@ export interface HsxDiagnosticCatalogEntry {
 
 const instrument = (
   body: string,
+  fields = "",
 ): string => `program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { ${fields} }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   ${body}
 }`;
 
@@ -201,8 +206,8 @@ instrument probe = template(value: "one", value: "two")`,
   {
     code: "HSX1022",
     stage: "typecheck",
-    title: "Authored instrument in a composition",
-    fix: "Publish the instrument separately, then select it with use.",
+    title: "Authored instrument collides with published catalog",
+    fix: "Rename the authored instrument to avoid colliding with published catalog instruments.",
     // This diagnostic requires a compiler-host published catalog.
     example: null,
     reason: "This refusal requires a compiler-host published catalog.",
@@ -214,6 +219,44 @@ instrument probe = template(value: "one", value: "two")`,
     fix: "List declared, non-optional field names once each.",
     example: instrument("required: missing;"),
   },
+  {
+    code: "HSX1024",
+    stage: "typecheck",
+    title: "Decision party has no matching account binding",
+    fix: "Bind the allowed party to an account field and use that binding in the decision action.",
+    example: `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)`,
+  },
+  {
+    code: "HSX1025",
+    stage: "typecheck",
+    title: "Unknown decision port shape type",
+    fix: "Declare the shape field as text, money(CUR), date, integer, boolean, account(CUR), ref<instrument_id>, id(instrument_id), bps, or percent.",
+    example: `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 } }`,
+  },
   {
     code: "HSX1101",
     stage: "typecheck",
@@ -298,6 +341,20 @@ action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total
     reason:
       "This refusal requires an invalid compiler-host cost-table currency.",
   },
+  {
+    code: "HSX1304",
+    stage: "typecheck",
+    title: "Unpriced ledger currency",
+    fix: "Move money in a currency the shipped cost tables price.",
+    example: instrument("", "amount: money<JPY>;"),
+  },
+  {
+    code: "HSX1305",
+    stage: "typecheck",
+    title: "More than one ledger currency",
+    fix: "Move all money in one currency; a program bills in one ledger currency.",
+    example: instrument("", "amount: money<SAR>; fee: money<USD>;"),
+  },
   {
     code: "HSX1401",
     stage: "typecheck",
@@ -411,6 +468,34 @@ instrument probe = template()`,
     example: `program catalog_probe "Catalog probe"
 export instrument template() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
 instrument probe = template() { fields: {}; }`,
+  },
+  {
+    code: "HSX1508",
+    stage: "typecheck",
+    title: "Invalid action-level port syntax",
+    fix: "Use allowed_parties: [...] inside an action-level port clause; allowed: is for top-level port declarations.",
+    example: `program catalog_probe "Catalog probe"
+party approver: person
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create {
+    steps: [];
+    port { allowed: [approver]; }
+  }
+}`,
+  },
+  {
+    code: "HSX1509",
+    stage: "typecheck",
+    title: "Callable action without an agent description",
+    fix: 'Add agent_description: "..." to the instrument and to every action a caller can reach; composer.check refuses the program without them.',
+    example: `program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}`,
   },
   {
     code: "HSX1601",