@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/src/canonical.ts

@@ -7,6 +7,17 @@ export function serializeUdl(value: unknown): string {
   return `${writeJson(document, 0)}\n`;
 }
 
+/** SHA-256 over the canonical UTF-8 bytes, encoded as lowercase hexadecimal. */
+export async function canonicalDigest(value: unknown): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(serializeUdl(value)),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 function writeJson(value: unknown, depth: number): string {
   if (value === null || typeof value !== "object") {
     const encoded = JSON.stringify(value);

package/src/check-profiles.ts

@@ -0,0 +1,80 @@
+/**
+ * Evidence profiles that an instrument action may require before it runs.
+ * The public grammar and the runtime both read this table. A pair absent here
+ * cannot gate an action.
+ */
+export interface UdlCheckEvidenceProfile {
+  readonly family: string;
+  readonly checkKind: string;
+  readonly kindField?: string;
+  readonly statusField: string;
+  readonly statuses: readonly string[];
+}
+
+export const udlCheckEvidenceProfiles = [
+  {
+    family: "national_identity",
+    checkKind: "identity_verification",
+    kindField: "checkKind",
+    statusField: "verificationStatus",
+    statuses: [
+      "requested",
+      "waiting",
+      "completed",
+      "rejected",
+      "expired",
+      "error",
+    ],
+  },
+  {
+    family: "national_identity",
+    checkKind: "contact_ownership_verification",
+    kindField: "checkKind",
+    statusField: "matchResult",
+    statuses: ["match", "no_match"],
+  },
+  {
+    family: "credit_bureau",
+    checkKind: "consumer_inquiry",
+    kindField: "inquiryType",
+    statusField: "bureauStatus",
+    statuses: ["returned", "acknowledged", "correction_required"],
+  },
+  {
+    family: "credit_bureau",
+    checkKind: "commercial_inquiry",
+    kindField: "inquiryType",
+    statusField: "bureauStatus",
+    statuses: ["returned", "acknowledged", "correction_required"],
+  },
+  {
+    family: "credit_bureau",
+    checkKind: "facility_report",
+    kindField: "inquiryType",
+    statusField: "bureauStatus",
+    statuses: ["returned", "acknowledged", "correction_required"],
+  },
+  {
+    family: "sanctions_screening",
+    checkKind: "screen",
+    kindField: "checkKind",
+    statusField: "screeningStatus",
+    statuses: ["clear", "hit", "manual_review"],
+  },
+  {
+    family: "enforcement_instrument",
+    checkKind: "note_request",
+    statusField: "requestStatus",
+    statuses: ["debtor_approved", "debtor_rejected", "auto_cancelled"],
+  },
+] as const satisfies readonly UdlCheckEvidenceProfile[];
+
+/** Returns the tenant-gateable evidence profile for one family and check. */
+export function udlCheckEvidenceProfile(
+  family: string,
+  checkKind: string,
+): UdlCheckEvidenceProfile | undefined {
+  return udlCheckEvidenceProfiles.find(
+    (profile) => profile.family === family && profile.checkKind === checkKind,
+  );
+}

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * The `udl` command. Three verbs over the same library the compiler uses:
+ * The `udl` command. Actions over the same library the compiler uses:
  * `validate` answers whether a document is admissible, `fmt` writes the
  * canonical bytes, and `diff` answers whether a change is legal against a
  * document that already has live instances.
@@ -9,10 +9,12 @@ import { readFile, writeFile } from "node:fs/promises";
 
 import {
   canonicalizeUdl,
+  canonicalDigest,
   diffValidatedUdlEvolution,
   parseUdl,
   UdlError,
   type UdlDocument,
+  udlDiagnostic,
 } from "./index.js";
 
 const USAGE = `udl - the Universal Domain Language toolchain
@@ -20,7 +22,9 @@ const USAGE = `udl - the Universal Domain Language toolchain
 usage:
   udl validate <file>          parse <file> and report every issue found
   udl fmt <file> [--write]     print the canonical form, or rewrite the file
+  udl canon <file> [--digest]  print canonical bytes, or their SHA-256 digest
   udl diff <live> <next>       check <next> against the append-only law
+  udl explain UDL####          explain one stable diagnostic code
   udl help                     print this
 
 exit codes:
@@ -40,8 +44,12 @@ async function main(argv: readonly string[]): Promise<number> {
       return validateCommand(rest);
     case "fmt":
       return formatCommand(rest);
+    case "canon":
+      return canonCommand(rest);
     case "diff":
       return diffCommand(rest);
+    case "explain":
+      return explainCommand(rest);
     case undefined:
       return usageError("udl: no command given");
     default:
@@ -49,6 +57,41 @@ async function main(argv: readonly string[]): Promise<number> {
   }
 }
 
+async function canonCommand(args: readonly string[]): Promise<number> {
+  const digest = args.includes("--digest");
+  const [file, ...extra] = args.filter((argument) => argument !== "--digest");
+  if (file === undefined || extra.length > 0) {
+    return usageError("usage: udl canon <file> [--digest]");
+  }
+  const bytes = await readDocument(file);
+  if (bytes === null) return 2;
+  let document: UdlDocument;
+  try {
+    document = parseUdl(bytes);
+  } catch (error) {
+    return reportIssues(file, error);
+  }
+  if (digest) console.log(await canonicalDigest(document));
+  else process.stdout.write(canonicalizeUdl(bytes));
+  return 0;
+}
+
+function explainCommand(args: readonly string[]): number {
+  const [code, ...extra] = args;
+  if (code === undefined || extra.length > 0) {
+    return usageError("usage: udl explain UDL####");
+  }
+  const diagnostic = udlDiagnostic(code);
+  if (!diagnostic) {
+    return usageError(`udl: unknown diagnostic code ${code}`);
+  }
+  console.log(`${code} ${diagnostic.title}`);
+  console.log(`category: ${diagnostic.category}`);
+  console.log(`family: ${diagnostic.family}`);
+  console.log(`fix: ${diagnostic.fix}`);
+  return 0;
+}
+
 async function validateCommand(args: readonly string[]): Promise<number> {
   const [file, ...extra] = args;
   if (file === undefined || extra.length > 0) {
@@ -108,8 +151,11 @@ async function diffCommand(args: readonly string[]): Promise<number> {
     console.log(`${nextPath}: additive`);
     return 0;
   }
-  for (const violation of violations)
-    console.error(`${nextPath}: ${violation}`);
+  for (const violation of violations) {
+    console.error(
+      `${nextPath}: ${violation.code} ${violation.path}: ${violation.message}`,
+    );
+  }
   return 1;
 }
 

package/src/diagnostics.ts

@@ -0,0 +1,221 @@
+export type UdlIssueCategory =
+  | "invalid_evolution"
+  | "invalid_json"
+  | "invalid_semantics"
+  | "invalid_shape"
+  | "invalid_utf8"
+  | "resource_limit";
+
+export type UdlDiagnosticFamily =
+  | "admission"
+  | "document"
+  | "evolution"
+  | "finance"
+  | "gates"
+  | "lifecycle"
+  | "schema";
+
+const diagnosticDefinitions = {
+  UDL1001: {
+    category: "invalid_utf8",
+    family: "admission",
+    title: "Invalid UTF-8",
+    fix: "Encode the document as valid UTF-8.",
+  },
+  UDL1002: {
+    category: "invalid_json",
+    family: "admission",
+    title: "Invalid JSON",
+    fix: "Repair the JSON syntax before validation.",
+  },
+  UDL1003: {
+    category: "invalid_shape",
+    family: "admission",
+    title: "Invalid document shape",
+    fix: "Match the published UDL JSON Schema.",
+  },
+  UDL1004: {
+    category: "resource_limit",
+    family: "admission",
+    title: "Resource limit exceeded",
+    fix: "Reduce the source size, nesting, values, strings, references, or financial paths named by the message.",
+  },
+
+  UDL2001: {
+    category: "invalid_semantics",
+    family: "document",
+    title: "Duplicate declaration",
+    fix: "Give each declaration a unique name.",
+  },
+  UDL2002: {
+    category: "invalid_semantics",
+    family: "document",
+    title: "Document law violation",
+    fix: "Repair the declaration, subject contract, or derived effects named by the message.",
+  },
+  UDL2005: {
+    category: "invalid_semantics",
+    family: "document",
+    title: "Derived effects mismatch",
+    fix: "Regenerate the action effects from its clauses.",
+  },
+
+  UDL3001: {
+    category: "invalid_semantics",
+    family: "lifecycle",
+    title: "Lifecycle is not closed",
+    fix: "Declare every state and action transition, and make every state reachable.",
+  },
+
+  UDL4001: {
+    category: "invalid_semantics",
+    family: "finance",
+    title: "Money graph violation",
+    fix: "Balance every funded amount and close every hold on each lifecycle path.",
+  },
+
+  UDL5001: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reference gate violation",
+    fix: "Point the gate at a declared instrument, action, state, field, and reference.",
+  },
+  UDL5002: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Check requirement violation",
+    fix: "Use a declared check with compatible evidence and recurrence.",
+  },
+  UDL5003: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Exposure gate violation",
+    fix: "Use declared account and money fields for the exposure gate.",
+  },
+  UDL5004: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Aggregate law violation",
+    fix: "Point the aggregate at compatible parent and child fields.",
+  },
+  UDL5005: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Settlement or payout violation",
+    fix: "Use a declared settlement account and a compatible payout statement line.",
+  },
+  UDL5006: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Quote and commit violation",
+    fix: "Declare one complete quote freeze set and one matching commit action.",
+  },
+  UDL5007: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reconcile exception child violation",
+    fix: "Name a declared child whose reference points back to this instrument.",
+  },
+  UDL5008: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Action clause violation",
+    fix: "Repair the clause fields and keep incompatible clauses separate.",
+  },
+  UDL5009: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reconcile exception amount field is missing or optional",
+    fix: "Name the exception child's required money field in amountField.",
+  },
+  UDL5010: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reconcile exception amount field has the wrong type",
+    fix: "Point amountField at a money field declared by the exception child.",
+  },
+  UDL5011: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reconcile exception reason field is missing or optional",
+    fix: "Name the exception child's required text field in reasonField.",
+  },
+  UDL5012: {
+    category: "invalid_semantics",
+    family: "gates",
+    title: "Reconcile exception reason field has the wrong type",
+    fix: "Point reasonField at a required plain text field declared by the exception child.",
+  },
+
+  UDL6001: {
+    category: "invalid_semantics",
+    family: "schema",
+    title: "Unsupported JSON Schema",
+    fix: "Use only the sealed UDL JSON Schema subset.",
+  },
+
+  UDL7001: {
+    category: "invalid_evolution",
+    family: "evolution",
+    title: "Stored contract changed",
+    fix: "Keep stored identities and contracts unchanged, and add only allowed optional declarations.",
+  },
+  UDL7002: {
+    category: "invalid_evolution",
+    family: "evolution",
+    title: "Version was not increased",
+    fix: "Increase the product version for every semantic change.",
+  },
+} as const satisfies Record<
+  string,
+  {
+    readonly category: UdlIssueCategory;
+    readonly family: UdlDiagnosticFamily;
+    readonly fix: string;
+    readonly title: string;
+  }
+>;
+
+export type UdlIssueCode = keyof typeof diagnosticDefinitions;
+
+export interface UdlDiagnostic {
+  readonly category: UdlIssueCategory;
+  readonly code: UdlIssueCode;
+  readonly family: UdlDiagnosticFamily;
+  readonly fix: string;
+  readonly title: string;
+}
+
+export const udlDiagnostics: readonly UdlDiagnostic[] = Object.entries(
+  diagnosticDefinitions,
+).map(([code, diagnostic]) => ({
+  code: code as UdlIssueCode,
+  ...diagnostic,
+}));
+
+export function udlDiagnostic(code: string): UdlDiagnostic | undefined {
+  return udlDiagnostics.find((diagnostic) => diagnostic.code === code);
+}
+
+export interface UdlIssue {
+  readonly category: UdlIssueCategory;
+  readonly code: UdlIssueCode;
+  readonly fix: string;
+  readonly message: string;
+  readonly path: string;
+}
+
+export function issue(
+  code: UdlIssueCode,
+  path: string,
+  messageDetail?: string,
+): UdlIssue {
+  const diagnostic = diagnosticDefinitions[code];
+  return {
+    category: diagnostic.category,
+    code,
+    fix: diagnostic.fix,
+    message: messageDetail ?? diagnostic.title,
+    path,
+  };
+}

package/src/effects.ts

@@ -0,0 +1,163 @@
+export const udlEffectKinds = [
+  "decides",
+  "holds",
+  "moves",
+  "notifies",
+  "reads",
+  "schedules",
+] as const;
+
+export type UdlEffectKind = (typeof udlEffectKinds)[number];
+
+type EffectDescriptor = {
+  readonly kind: UdlEffectKind;
+  readonly per: "clause" | "element";
+  readonly signature:
+    | { readonly fixed: string }
+    | { readonly fromField: string }
+    | { readonly movementClass: true };
+};
+
+type ActionClauseDescriptor = {
+  readonly effects?: readonly EffectDescriptor[];
+  readonly scope: "action" | "instrument";
+  readonly target: string;
+};
+
+type EffectRow = {
+  readonly channel?: string;
+  readonly role?: string;
+  readonly signature: string;
+  readonly source: string;
+};
+
+export type DerivedUdlEffects = Partial<
+  Readonly<Record<UdlEffectKind, readonly EffectRow[]>>
+>;
+
+export type UdlMovementClass =
+  | "collection.pay_in"
+  | "deposit.attributed"
+  | "payout.external"
+  | "transfer.internal";
+
+interface Movement {
+  readonly bind?: Readonly<Record<string, unknown>>;
+  readonly operation: string;
+}
+
+function boundPath(move: Movement, endpoint: string): string | undefined {
+  const binding = move.bind?.[endpoint];
+  if (binding === null || typeof binding !== "object") return undefined;
+  const path = (binding as { readonly path?: unknown }).path;
+  return typeof path === "string" ? path : undefined;
+}
+
+/**
+ * Maps a UDL money operation to the meter and pricing class that owns it.
+ * Internal-transfer endpoint bindings are product accounts by construction.
+ * External collection, deposit, and payout operations carry their role in the
+ * operation family because their remote endpoint is not a UDL account binding.
+ */
+export function movementClass(move: Movement): UdlMovementClass {
+  if (move.operation.startsWith("internal_transfer.")) {
+    const source = boundPath(move, "sourceAccountId");
+    const destination = boundPath(move, "destinationAccountId");
+    if (
+      source?.startsWith("fields.") &&
+      destination === "refs.escrowAccountId"
+    ) {
+      return "collection.pay_in";
+    }
+    return "transfer.internal";
+  }
+  if (move.operation.startsWith("collection.pay_in.")) {
+    return "collection.pay_in";
+  }
+  if (move.operation.startsWith("deposit.")) {
+    return "deposit.attributed";
+  }
+  if (move.operation.startsWith("payout.")) {
+    return "payout.external";
+  }
+  throw new Error(`cannot classify UDL movement operation ${move.operation}`);
+}
+
+/** Derive the ABI effect rows declared by the action-clause vocabulary. */
+export function deriveUdlActionEffects(
+  action: Readonly<Record<string, unknown>>,
+  vocabulary: readonly ActionClauseDescriptor[],
+): DerivedUdlEffects {
+  const effects: Partial<Record<UdlEffectKind, EffectRow[]>> = {};
+  for (const clause of vocabulary) {
+    if (clause.scope !== "action" || !clause.effects) continue;
+    const value = actionClauseValue(action, clause.target);
+    if (value === undefined) continue;
+    for (const descriptor of clause.effects) {
+      const values =
+        descriptor.per === "element" && Array.isArray(value) ? value : [value];
+      for (const [index, candidate] of values.entries()) {
+        const object = recordValue(candidate);
+        if (
+          descriptor.kind === "holds" &&
+          "fixed" in descriptor.signature &&
+          descriptor.signature.fixed === "reserve" &&
+          object?.operation !== "internal_transfer.reserve"
+        ) {
+          continue;
+        }
+        const suffix = effectSignatureSuffix(descriptor, object);
+        if (!suffix) continue;
+        (effects[descriptor.kind] ??= []).push({
+          signature: `${descriptor.kind}.${suffix}`,
+          source:
+            descriptor.per === "element"
+              ? `${clause.target}[${index}]`
+              : clause.target,
+          ...(descriptor.kind === "notifies" &&
+          typeof object?.channel === "string" &&
+          typeof object.role === "string"
+            ? { channel: object.channel, role: object.role }
+            : {}),
+        });
+      }
+    }
+  }
+  return effects;
+}
+
+function actionClauseValue(
+  action: Readonly<Record<string, unknown>>,
+  target: string,
+): unknown {
+  const [head, tail] = target.split(".");
+  if (!head) return undefined;
+  const value = action[head];
+  if (!tail) return value;
+  return recordValue(value)?.[tail];
+}
+
+function effectSignatureSuffix(
+  descriptor: EffectDescriptor,
+  value: Readonly<Record<string, unknown>> | undefined,
+): string | undefined {
+  if ("fixed" in descriptor.signature) return descriptor.signature.fixed;
+  if ("fromField" in descriptor.signature) {
+    const field = value?.[descriptor.signature.fromField];
+    return typeof field === "string" ? field : undefined;
+  }
+  if (!value || !("movementClass" in descriptor.signature)) return undefined;
+  const operation = value.operation;
+  const bind = recordValue(value.bind);
+  return typeof operation === "string"
+    ? movementClass({ ...(bind ? { bind } : {}), operation })
+    : undefined;
+}
+
+function recordValue(
+  value: unknown,
+): Readonly<Record<string, unknown>> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined;
+}