@hyperscale0/udl 3.1.0 → 3.2.0

package/src/schema.ts

@@ -1,6 +1,9 @@
 import * as z from "zod";
+import { reportDefinitionSchema } from "./reporting.js";
 
 export const UDL_FORMAT_VERSION = 3 as const;
+/** Counts the root and every nested invocation, including selected and ranged children. */
+export const MAX_ACTION_EXPANSION = 4096;
 const name = z
   .string()
   .regex(/^[a-z][a-zA-Z0-9_]*$/)
@@ -62,7 +65,13 @@ export const udlFieldSchema = z.discriminatedUnion("type", [
     ...fieldBase,
     type: z.literal("text"),
     value: text.optional(),
+    minLength: integer.positive().max(2048).optional(),
     maxLength: integer.positive().max(2048).optional(),
+    // One anchored ASCII character class and a fixed repetition. No executable patterns.
+    pattern: z
+      .string()
+      .regex(/^\^\[[A-Za-z0-9-]+\]\{[1-9][0-9]{0,3}\}\$$/)
+      .optional(),
   }),
   z.strictObject({
     ...fieldBase,
@@ -183,6 +192,13 @@ export const udlCalculationSchema = z.discriminatedUnion("op", [
   }),
 ]);
 
+const comparisonRequirement = z.strictObject({
+  kind: z.literal("compare"),
+  left: value,
+  operator: z.enum(["==", "!=", "<", "<=", ">", ">="]),
+  right: value,
+});
+
 export const udlRequirementSchema = z.discriminatedUnion("kind", [
   z.strictObject({
     kind: z.literal("hours"),
@@ -191,12 +207,7 @@ export const udlRequirementSchema = z.discriminatedUnion("kind", [
     end: integer.min(0).max(23),
     timezone: text,
   }),
-  z.strictObject({
-    kind: z.literal("compare"),
-    left: value,
-    operator: z.enum(["==", "!=", "<", "<=", ">", ">="]),
-    right: value,
-  }),
+  comparisonRequirement,
   z.strictObject({
     kind: z.literal("state"),
     reference: path,
@@ -267,16 +278,46 @@ export const udlMoveSchema = z.discriminatedUnion("operation", [
     transfer: path,
   }),
 ]);
-const clock = z.strictObject({ at: path, offset: integer.optional() });
+const clock = z.strictObject({
+  at: path,
+  offset: integer.optional(),
+  localDay: z
+    .strictObject({
+      days: integer.min(0).max(366),
+      direction: z.enum(["before", "after"]),
+      hour: integer.min(0).max(23),
+      timezone: text,
+    })
+    .optional(),
+});
 export const udlActionSchema = z.strictObject({
   summary: text,
   publicAction: name.optional(),
+  expansionLimit: z.literal(8192).optional(),
+  humanApproval: z.literal("distinct_member").optional(),
+  reminder: z
+    .strictObject({
+      installment: path,
+      recipient: path,
+      dueAt: path,
+      channel: z.literal("email"),
+      template: z.literal("payment_reminder"),
+      beforeDays: integer.min(0).max(366),
+      overdueDays: integer.min(1).max(366),
+      maxPerDay: integer.min(1).max(10),
+      startHour: integer.min(0).max(23),
+      endHour: integer.min(1).max(24),
+      timezone: text,
+    })
+    .optional(),
   event: text,
   actor: z.union([
     z.literal("caller"),
     z.literal("clock"),
     z.strictObject({ party: name }),
-    z.strictObject({ parent: instrumentId }),
+    z.strictObject({
+      parent: z.union([instrumentId, z.array(instrumentId).min(1).max(16)]),
+    }),
   ]),
   input: z.array(udlFieldSchema).max(128),
   requires: z.array(udlRequirementSchema).max(128),
@@ -292,16 +333,26 @@ export const udlActionSchema = z.strictObject({
           instrument: instrumentId,
           action: z.literal("create"),
           input: z.record(name, value),
+          guard: comparisonRequirement.optional(),
+          range: z
+            .strictObject({
+              count: value,
+              maximum: integer.min(1).max(366),
+              bind: name,
+            })
+            .optional(),
         }),
         z.strictObject({
           reference: path,
           action: name,
           input: z.record(name, value),
+          guard: comparisonRequirement.optional(),
         }),
         z.strictObject({
           selection,
           action: name,
           input: z.record(name, value),
+          guard: comparisonRequirement.optional(),
         }),
       ]),
     )
@@ -327,6 +378,8 @@ export const udlLifecycleSchema = z.strictObject({
   ),
 });
 export const udlInstrumentSchema = z.strictObject({
+  reports: z.array(reportDefinitionSchema).max(16).optional(),
+  revisioned: z.literal(true).optional(),
   id: instrumentId,
   title: text,
   summary: text,

package/src/validation.ts

@@ -1,5 +1,6 @@
 import {
   udlDocumentSchema,
+  MAX_ACTION_EXPANSION,
   type UdlDocument,
   type UdlField,
   type UdlInstrument,
@@ -8,6 +9,7 @@ import {
   type UdlSelection,
 } from "./schema.js";
 import { issue, type UdlIssue } from "./diagnostics.js";
+import { validateReportDefinition } from "./reporting-validation.js";
 import { analyzeInstrumentFinance } from "./finance.js";
 
 export type UdlValidationResult =
@@ -149,6 +151,7 @@ function resolvePath(
     if (key === "id") return { name: key, type: "ref", target: instrument.id };
     if (key === "now" || key === "createdAt")
       return { name: key, type: "date" };
+    if (key === "productRevision") return { name: key, type: "text" };
     if (key === "status")
       return { name: key, type: "enum", values: instrument.lifecycle.states };
   }
@@ -239,6 +242,23 @@ export function validateUdl(value: unknown): UdlValidationResult {
     document.instruments.map((i) => i.id),
     "$.instruments",
   );
+  const reportIds = new Set<string>();
+  for (const [index, instrument] of document.instruments.entries()) {
+    for (const report of instrument.reports ?? []) {
+      const path = `$.instruments[${index}].reports`;
+      if (reportIds.has(report.identity.id))
+        add(path, `duplicate report ${report.identity.id}`);
+      reportIds.add(report.identity.id);
+      try {
+        validateReportDefinition(report, document);
+      } catch (error) {
+        add(
+          path,
+          error instanceof Error ? error.message : "Invalid report definition",
+        );
+      }
+    }
+  }
   const byId = new Map(document.instruments.map((i) => [i.id, i]));
   const calls = new Map<string, { targets: string[]; count: number }[]>();
   for (const [index, inst] of document.instruments.entries()) {
@@ -294,8 +314,23 @@ export function validateUdl(value: unknown): UdlValidationResult {
             where,
             "contra accounts require the claim book; external accounts require a cash party owner",
           );
-        if (["id", "status", "createdAt", "now"].includes(f.name))
+        if (
+          ["id", "status", "createdAt", "now", "productRevision"].includes(
+            f.name,
+          )
+        )
           add(where, `${f.name} is a sealed instance field`);
+        if (f.type === "text") {
+          if ((f.minLength ?? 1) > (f.maxLength ?? 2048))
+            add(where, "text minimum exceeds maximum");
+          if (f.pattern) {
+            try {
+              new RegExp(f.pattern);
+            } catch {
+              add(where, "invalid text character class");
+            }
+          }
+        }
         if (f.type === "ref") {
           duplicate(targetIds(f.target), where);
           for (const id of targetIds(f.target))
@@ -561,6 +596,8 @@ export function validateUdl(value: unknown): UdlValidationResult {
     };
     checkCalculations(inst.calculate, `${base}.calculate`);
     const states = new Set(inst.lifecycle.states);
+    if (states.has("preserve"))
+      add(base, "preserve is a reserved transition destination", "UDL3001");
     duplicate(inst.lifecycle.states, `${base}.lifecycle.states`);
     if (!states.has(inst.lifecycle.initial) || !inst.actions.create)
       add(base, "declare create and a declared initial state", "UDL3001");
@@ -575,14 +612,15 @@ export function validateUdl(value: unknown): UdlValidationResult {
       if (
         !inst.actions[action] ||
         action === "create" ||
-        !states.has(edge.to) ||
+        (edge.to !== "preserve" && !states.has(edge.to)) ||
         edge.from.some((s) => !states.has(s))
       )
         add(base, `invalid transition ${action}`, "UDL3001");
     }
     for (let pass = 0; pass < states.size; pass++)
       for (const edge of Object.values(inst.lifecycle.transitions))
-        if (edge.from.some((s) => reachable.has(s))) reachable.add(edge.to);
+        if (edge.to !== "preserve" && edge.from.some((s) => reachable.has(s)))
+          reachable.add(edge.to);
     for (const state of states)
       if (!reachable.has(state))
         add(base, `unreachable state ${state}`, "UDL3001");
@@ -696,6 +734,18 @@ export function validateUdl(value: unknown): UdlValidationResult {
       if (actionName !== "create" && !inst.lifecycle.transitions[actionName])
         add(where, "action needs a lifecycle transition", "UDL3001");
       checkFields(action.input, `${where}.input`);
+      if (action.reminder) {
+        expect(action.reminder.installment, "ref", where, action.input);
+        expect(action.reminder.recipient, "account", where, action.input);
+        expect(action.reminder.dueAt, "date", where, action.input);
+        if (action.reminder.startHour >= action.reminder.endHour)
+          add(where, "reminder sending window is empty");
+        try {
+          new Intl.DateTimeFormat("en", { timeZone: action.reminder.timezone });
+        } catch {
+          add(where, "reminder requires an IANA timezone");
+        }
+      }
       for (const input of action.input) {
         if (input.type === "account")
           add(where, "account bindings cannot be caller inputs");
@@ -734,13 +784,24 @@ export function validateUdl(value: unknown): UdlValidationResult {
       if (
         typeof action.actor === "object" &&
         "parent" in action.actor &&
-        !byId.has(action.actor.parent)
+        targetIds(action.actor.parent).some((id) => !byId.has(id))
       )
         add(where, "actor names an undeclared parent");
       if (action.actor === "clock" && !action.due)
         add(where, "clock action needs a due instant");
       for (const clock of [action.due, action.deadline])
-        if (clock) expect(clock.at, "date", where, action.input);
+        if (clock) {
+          expect(clock.at, "date", where, action.input);
+          if (clock.localDay) {
+            try {
+              new Intl.DateTimeFormat("en", {
+                timeZone: clock.localDay.timezone,
+              }).format(0);
+            } catch {
+              add(where, "clock timezone must be an IANA timezone");
+            }
+          }
+        }
       for (const move of action.moves) {
         if ("amount" in move) {
           checkValue(move.amount, "money", where, action.input);
@@ -790,6 +851,7 @@ export function validateUdl(value: unknown): UdlValidationResult {
         targetId: string | undefined,
         actionName: string,
         values: Record<string, UdlValue>,
+        binding?: string,
       ) => {
         const target = targetId
           ? byId.get(targetId)?.actions[actionName]
@@ -808,6 +870,11 @@ export function validateUdl(value: unknown): UdlValidationResult {
             add(where, `unknown target input ${name}`);
             continue;
           }
+          if (binding && "field" in value && value.field === binding) {
+            if (declared.type !== "integer")
+              add(where, "range binding requires an integer target input");
+            continue;
+          }
           checkValue(value, declared.type, where, action.input);
           if (declared.type === "ref" && "field" in value) {
             const supplied = field(value.field, action.input);
@@ -844,6 +911,20 @@ export function validateUdl(value: unknown): UdlValidationResult {
       }
       const targets: { targets: string[]; count: number }[] = [];
       for (const call of action.invoke ?? []) {
+        if (call.guard) checkRequirements([call.guard], where, action.input);
+        const range = "instrument" in call ? call.range : undefined;
+        if (range) {
+          checkValue(range.count, "integer", where, action.input);
+          if (["self", "input", "party"].includes(range.bind))
+            add(where, "range binding cannot shadow a reserved scope");
+          if (
+            "literal" in range.count &&
+            (typeof range.count.literal !== "number" ||
+              range.count.literal < 1 ||
+              range.count.literal > range.maximum)
+          )
+            add(where, "range count must be between one and its maximum");
+        }
         if ("selection" in call)
           checkSelection(call.selection, where, action.input);
         const target =
@@ -863,7 +944,7 @@ export function validateUdl(value: unknown): UdlValidationResult {
             : [];
         if (!ids.length) add(where, "invocation needs a declared target");
         for (const targetId of ids) {
-          checkArguments(targetId, call.action, call.input);
+          checkArguments(targetId, call.action, call.input, range?.bind);
           if (call.action === "create" && !("instrument" in call))
             add(
               where,
@@ -874,7 +955,8 @@ export function validateUdl(value: unknown): UdlValidationResult {
         }
         targets.push({
           targets: ids.map((id) => `${id}.${call.action}`),
-          count: "selection" in call ? call.selection.limit : 1,
+          count:
+            "selection" in call ? call.selection.limit : (range?.maximum ?? 1),
         });
       }
       calls.set(`${inst.id}.${actionName}`, targets);
@@ -891,7 +973,7 @@ export function validateUdl(value: unknown): UdlValidationResult {
   const visit = (key: string): number => {
     if (active.has(key)) {
       add("$.instruments", `invocation cycle at ${key}`, "UDL2010");
-      return 4097;
+      return MAX_ACTION_EXPANSION + 1;
     }
     const known = depths.get(key);
     if (known !== undefined) return known;
@@ -904,8 +986,16 @@ export function validateUdl(value: unknown): UdlValidationResult {
       );
     active.delete(key);
     depths.set(key, size);
-    if (size > 4096)
-      add("$.instruments", `invocation ${key} exceeds 4096 actions`, "UDL2010");
+    const [id, action] = key.split(".");
+    const limit =
+      document.instruments.find((item) => item.id === id)?.actions[action!]
+        ?.expansionLimit ?? MAX_ACTION_EXPANSION;
+    if (size > limit)
+      add(
+        "$.instruments",
+        `invocation ${key} exceeds ${limit} actions`,
+        "UDL2010",
+      );
     return size;
   };
   for (const key of calls.keys()) visit(key);