@hyperscale0/hsx 1.0.0 → 2.0.0

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",

package/src/emit.ts

@@ -1,5 +1,4 @@
 import {
-  serializeUdl,
   validateUdl,
   type UdlDocument,
   type UdlIssueCode,
@@ -25,7 +24,6 @@ export type GeneralLowerResult =
   | {
       readonly ok: true;
       readonly value: {
-        readonly canonicalUdl: string;
         readonly document: UdlDocument;
         readonly originMap: readonly OriginMapEntry[];
       };
@@ -72,7 +70,9 @@ export function lowerGeneralProgram(program: TypedProgram): GeneralLowerResult {
       ok: false,
     };
   }
-  const validation = validateUdl(candidate);
+  const validation = validateUdl(candidate, {
+    requireDecisionPartyBindings: true,
+  });
   if (!validation.ok) {
     const origins = originMapFor(program);
     return {
@@ -94,7 +94,6 @@ export function lowerGeneralProgram(program: TypedProgram): GeneralLowerResult {
   return {
     ok: true,
     value: {
-      canonicalUdl: serializeUdl(document),
       document,
       originMap: originMapFor(program),
     },
@@ -129,21 +128,36 @@ function unresolvedCompilerMarkers(
   });
 }
 
-function originForUdlPath(
+export function originForUdlPath<T extends { readonly path: string }>(
   path: string,
-  origins: readonly OriginMapEntry[],
-): OriginMapEntry | undefined {
-  return (
-    [...origins]
-      .filter(
-        (entry) =>
-          path === entry.path ||
-          path.startsWith(`${entry.path}.`) ||
-          path.startsWith(`${entry.path}[`),
-      )
-      .sort((left, right) => right.path.length - left.path.length)[0] ??
-    origins.find((entry) => entry.path === "$")
-  );
+  origins: readonly T[],
+): T | undefined {
+  let longestMatch: T | undefined;
+  let longestLength = -1;
+  let rootFallback: T | undefined;
+
+  for (let i = 0; i < origins.length; i += 1) {
+    const entry = origins[i]!;
+    const entryPath = entry.path;
+    if (rootFallback === undefined && entryPath === "$") {
+      rootFallback = entry;
+    }
+    const entryLen = entryPath.length;
+    if (
+      path === entryPath ||
+      (path.length > entryLen &&
+        (path.charCodeAt(entryLen) === 46 ||
+          path.charCodeAt(entryLen) === 91) &&
+        path.startsWith(entryPath))
+    ) {
+      if (entryLen > longestLength) {
+        longestMatch = entry;
+        longestLength = entryLen;
+      }
+    }
+  }
+
+  return longestMatch ?? rootFallback;
 }
 
 export function requiredFields(instrument: TypedInstrument): string[] {

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   type HsxEffectKind,
   type UdlCostManifest,
   type UdlCostTable,
+  type UdlCostTables,
 } from "./cost.ts";
 export {
   hsxDiagnostics,
@@ -27,7 +28,7 @@ export {
   type ProgramEntryOverrideValue,
 } from "./entry-overrides.ts";
 export { type OriginMapEntry } from "./emit.ts";
-export { lowerGeneralProgram } from "./emit.ts";
+export { lowerGeneralProgram, originForUdlPath } from "./emit.ts";
 export { parseProgram } from "./parse.ts";
 export { checkGeneralProgram, type GeneralCheckOptions } from "./typecheck.ts";
 export {

package/src/modules.ts

@@ -327,7 +327,13 @@ function declarationReferences(decl: Decl): {
   if (decl.kind === "type") collectExprNames(decl.value, names, ports);
   if (decl.kind === "party" && decl.attrs)
     collectExprNames(decl.attrs, names, ports);
-  if (decl.kind === "port") collectExprNames(decl.body, names, ports);
+  if (decl.kind === "port") {
+    collectExprNames(decl.body, names, ports);
+    const allowed = decl.body.entries.find(
+      (entry) => entry.key.name === "allowed",
+    );
+    if (allowed) collectApplicationPartyNames(allowed.value, parties);
+  }
   if (decl.kind === "instrument_apply" || isApplicationScopeDecl(decl)) {
     names.delete(decl.name.name);
     parties.delete(decl.name.name);
@@ -431,13 +437,13 @@ function standardSources(
   specifier: string,
   names: readonly string[],
 ): ModuleSource[] {
-  if (specifier !== "std/settlements") return [];
+  if (specifier !== "std/money_flows") return [];
   return names.flatMap((name) => {
     const source = standardLibrary.source(specifier, name);
     return source !== undefined
       ? [
           {
-            name: `std.settlements.${name}`,
+            name: `std.money_flows.${name}`,
             source,
           },
         ]

package/src/parse.ts

@@ -367,7 +367,7 @@ class Parser {
     if (
       !this.expectPunct(
         "{",
-        'import lists its names in braces: import { held_payment } from "std/settlements"',
+        'import lists its names in braces: import { held_payment } from "std/money_flows"',
       )
     ) {
       return undefined;
@@ -385,7 +385,7 @@ class Parser {
     if (!this.at("keyword") || this.peek().text !== "from") {
       this.error(
         this.peek().span,
-        'import needs from: import { held_payment } from "std/settlements"',
+        'import needs from: import { held_payment } from "std/money_flows"',
       );
       return undefined;
     }
@@ -393,7 +393,7 @@ class Parser {
     if (!this.at("string")) {
       this.error(
         this.peek().span,
-        'the import source must be a quoted module name like "std/settlements"',
+        'the import source must be a quoted module name like "std/money_flows"',
       );
       return undefined;
     }