@hyperscale0/udl 1.0.0 → 1.0.123

package/src/canonical.ts

@@ -1,6 +1,5 @@
 import { assertValidUdl } from "./validation.js";
-
-const INDENT = "  ";
+import { writeJson } from "./json.js";
 
 export function serializeUdl(value: unknown): string {
   const document = assertValidUdl(value);
@@ -17,36 +16,3 @@ export async function canonicalDigest(value: unknown): Promise<string> {
     .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);
-    if (encoded === undefined) {
-      throw new TypeError("UDL canonical JSON received a non-JSON value");
-    }
-    return encoded;
-  }
-
-  const indent = INDENT.repeat(depth);
-  const childIndent = INDENT.repeat(depth + 1);
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
-    return `[\n${value
-      .map((item) => `${childIndent}${writeJson(item, depth + 1)}`)
-      .join(",\n")}\n${indent}]`;
-  }
-
-  const record = value as Record<string, unknown>;
-  const keys = Object.keys(record).sort(compareCodeUnits);
-  if (keys.length === 0) return "{}";
-  return `{\n${keys
-    .map(
-      (key) =>
-        `${childIndent}${JSON.stringify(key)}: ${writeJson(record[key], depth + 1)}`,
-    )
-    .join(",\n")}\n${indent}}`;
-}
-
-function compareCodeUnits(left: string, right: string): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}

package/src/diagnostics.ts

@@ -1,221 +1,88 @@
-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 type UdlIssueCode =
+  | "economic_party_unbound"
+  | "economic_move_invalid"
+  | "economic_reservation_conflict"
+  | "subject_field_conflict"
+  | "subject_field_unknown"
+  | "subject_requirement_missing"
+  | "subject_adapter_unbound"
+  | "subject_party_unbound"
+  | "party_name_reserved"
+  | "party_kind_mismatch"
+  | "staff_role_unknown"
+  | "product_party_unbound"
+  | "product_party_invalid"
+  | "UDL1003"
+  | "UDL1004"
+  | "UDL2001"
+  | "UDL2002"
+  | "UDL2010"
+  | "UDL3001"
+  | "UDL4001"
+  | "UDL5001";
 export interface UdlIssue {
-  readonly category: UdlIssueCategory;
-  readonly code: UdlIssueCode;
-  readonly fix: string;
-  readonly message: string;
-  readonly path: string;
+  code: UdlIssueCode;
+  path: string;
+  message: string;
+  fix: string;
+  category: string;
+  stranded?: {
+    state: string;
+    accounts: string[];
+    actions: string[];
+    paths: Record<string, string[]>;
+  };
 }
+const fixes: Record<UdlIssueCode, string> = {
+  economic_party_unbound:
+    "Bind sourceParty to a money party retained by this attachment.",
+  economic_move_invalid:
+    "Declare a cash purpose on a cash transfer or its posting; use internal for non-cash accounting.",
+  economic_reservation_conflict:
+    "Keep the reservation's economics on its posting.",
+  subject_field_conflict:
+    "Rename the field or use matching types and constraints.",
+  subject_field_unknown: "Name a declared subject requirement or object field.",
+  subject_requirement_missing: "Supply the required action field.",
+  subject_adapter_unbound: "Bind the required adapter declaration.",
+  subject_party_unbound:
+    "Bind the parameter to a subject role or declared party.",
+  party_name_reserved:
+    "Choose a party name other than owner, actor or operator.",
+  party_kind_mismatch: "Use a business or subject role for money.",
+  staff_role_unknown: "Use a registered staff permission role.",
+  product_party_unbound:
+    "Supply the consumed business in the Build party bindings.",
+  product_party_invalid:
+    "Bind a business participant in the same tenant and environment.",
 
+  UDL1003: "Use the UDL 1 typed grammar.",
+  UDL1004: "Reduce the declared structure or expansion.",
+  UDL2001: "Give each declaration a distinct name.",
+  UDL2002: "Repair the named type or declaration.",
+  UDL2010: "Remove the invocation cycle or reduce its expansion.",
+  UDL3001: "Declare reachable states and one transition per action.",
+  UDL4001:
+    "Fund owned accounts before spending and close them with zero balances.",
+  UDL5001: "Use a declared reference of the required type.",
+};
 export function issue(
   code: UdlIssueCode,
   path: string,
-  messageDetail?: string,
+  message: string,
 ): UdlIssue {
-  const diagnostic = diagnosticDefinitions[code];
   return {
-    category: diagnostic.category,
     code,
-    fix: diagnostic.fix,
-    message: messageDetail ?? diagnostic.title,
     path,
+    message,
+    fix: fixes[code],
+    category: category(code),
   };
 }
+function category(code: string): string {
+  return code === "UDL1003"
+    ? "invalid_shape"
+    : code === "UDL1004"
+      ? "resource_limit"
+      : "invalid_semantics";
+}

package/src/field-value.ts

@@ -0,0 +1,87 @@
+import * as z from "zod";
+import { udlObjectIdSchema, type UdlField } from "./schema.js";
+
+const amount = z.string().regex(/^(0|[1-9][0-9]{0,17})$/);
+const text = z.string().min(1).max(2048);
+
+/** Values, rather than declarations. The same validator feeds forms and admission. */
+export function udlFieldValueSchema(field: UdlField): z.ZodType {
+  let schema: z.ZodType;
+  switch (field.type) {
+    case "money":
+      schema = amount
+        .refine(
+          (value) =>
+            /^(0|[1-9][0-9]{0,17})$/.test(value) &&
+            (field.minimum === undefined ||
+              BigInt(value) >= BigInt(field.minimum)) &&
+            (field.maximum === undefined ||
+              BigInt(value) <= BigInt(field.maximum)),
+          "Money is outside its declared bounds",
+        )
+        .meta({
+          ...(field.minimum !== undefined
+            ? { "x-udl-minimum": field.minimum }
+            : {}),
+          ...(field.maximum !== undefined
+            ? { "x-udl-maximum": field.maximum }
+            : {}),
+        });
+      break;
+    case "account":
+      schema = text;
+      break;
+    case "ref":
+      schema = field.targetKind === "object" ? udlObjectIdSchema : text;
+      break;
+    case "date":
+      schema = z.iso.datetime({ offset: true });
+      break;
+    case "duration":
+      schema = z.number().int().safe().positive();
+      break;
+    case "text": {
+      let value = z
+        .string()
+        .min(field.minLength ?? 1)
+        .max(field.maxLength ?? 2048);
+      if (field.pattern) value = value.regex(new RegExp(field.pattern));
+      schema = value;
+      break;
+    }
+    case "integer": {
+      let value = z.number().int().safe();
+      if (field.minimum !== undefined) value = value.min(field.minimum);
+      if (field.maximum !== undefined) value = value.max(field.maximum);
+      schema = value;
+      break;
+    }
+    case "percent":
+      schema = z.number().int().min(0).max(10000);
+      break;
+    case "boolean":
+      schema = z.boolean();
+      break;
+    case "enum":
+      schema = z.enum(field.values);
+      break;
+    case "list": {
+      const item =
+        field.item === "money"
+          ? amount
+          : field.item === "date"
+            ? z.iso.datetime({ offset: true })
+            : field.item === "integer"
+              ? z.number().int().safe()
+              : field.item === "ref" && field.targetKind === "object"
+                ? udlObjectIdSchema
+                : text;
+      schema = z.array(item).max(field.maxItems);
+      break;
+    }
+  }
+  if ("value" in field && field.value !== undefined)
+    schema = z.literal(field.value);
+  if (field.description) schema = schema.describe(field.description);
+  return schema;
+}