@hyperscale0/udl 4.5.1 → 4.6.1

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;
+}

package/src/index.ts

@@ -30,4 +30,5 @@ export {
   validateReportDefinition,
   reportExpressionTypes,
 } from "./reporting-validation.js";
+export { udlFieldValueSchema } from "./field-value.js";
 export * from "./object-contract.js";

package/src/object-contract.ts

@@ -1,9 +1,18 @@
 import * as z from "zod";
+import { udlFieldValueSchema } from "./field-value.js";
+import {
+  projectDocumentSemantics,
+  presentationLabel,
+} from "./object-semantics.js";
+import type { DocumentSemantics } from "./object-semantics-schema.js";
+export * from "./object-semantics-schema.js";
+export {
+  projectDocumentSemantics,
+  presentationLabel,
+} from "./object-semantics.js";
 import {
   udlExternalIdSchema,
-  udlObjectIdSchema,
   type UdlDocument,
-  type UdlField,
   type UdlObjectField,
   type UdlObjectKind,
   type UdlSubjectRequirement,
@@ -43,9 +52,30 @@ export interface ObjectKindDiscovery {
   fields: readonly UdlObjectField[];
   authoredFields: readonly string[];
   columns: readonly string[];
+  filters: readonly {
+    field: string;
+    type: "text" | "enum" | "date" | "boolean" | "integer";
+  }[];
   createSchema: JsonSchemaDocument;
   actions: readonly ObjectActionDiscovery[];
 }
+export function objectKindFilters(
+  kind: UdlObjectKind,
+): ObjectKindDiscovery["filters"] {
+  return kind.columns.flatMap((column) => {
+    const field = kind.fields.find((item) => item.name === column);
+    return field &&
+      !field.sensitive &&
+      ["text", "enum", "date", "boolean", "integer"].includes(field.type)
+      ? [
+          {
+            field: column,
+            type: field.type as ObjectKindDiscovery["filters"][number]["type"],
+          },
+        ]
+      : [];
+  });
+}
 export type ObjectActionTarget =
   | { kind: "attachment"; attachment: string }
   | { kind: "instance"; attachment: string; instanceId: string };
@@ -69,10 +99,41 @@ export interface ObjectActionDiscovery extends ObjectActionContext {
   creationOnlyNames?: readonly string[];
   inputSchema: JsonSchemaDocument;
   fieldsSchema: JsonSchemaDocument;
-  availability:
-    | { status: "available" }
-    | { status: "unavailable"; code: string; message: string };
+  availability: ObjectActionAvailability;
 }
+export type ObjectActionBlockerCode =
+  | "permission_required"
+  | "state_changed"
+  | "not_due"
+  | "deadline_passed"
+  | "clock_pending"
+  | "condition_not_met"
+  | "already_used"
+  | "evidence_required"
+  | "account_unavailable"
+  | "insufficient_money"
+  | "setup_required"
+  | "invalid_input"
+  | "operation_pending";
+export type ObjectActionAvailability =
+  | { status: "available" }
+  | {
+      status: "requires_input";
+      subjectFields: readonly string[];
+      actionInputs: readonly string[];
+      parties: readonly string[];
+      reason: string;
+    }
+  | {
+      status: "unavailable";
+      blockers: readonly {
+        code: ObjectActionBlockerCode;
+        reason: string;
+        recheckAt?: string;
+      }[];
+    }
+  | { status: "unknown"; reason: string };
+
 export type EvidenceState =
   | "missing"
   | "pending"
@@ -100,13 +161,14 @@ export interface ObjectActionState extends ObjectActionDiscovery {
 /** GET /v1/products/{productId}/objects. Core supplies the frozen Build identity. */
 export type RetainedObjectKind = Pick<
   ObjectKindDiscovery,
-  "kind" | "title" | "fields" | "authoredFields" | "columns"
+  "kind" | "title" | "fields" | "authoredFields" | "columns" | "filters"
 > & {
   productBuildId: string;
   digest: string;
   creation: false;
 };
 export interface ObjectDiscovery {
+  semantics: DocumentSemantics;
   navigation: readonly { kind: string; title: string; creation: boolean }[];
   retainedKinds: readonly RetainedObjectKind[];
   productBuildId: string;
@@ -131,6 +193,8 @@ export interface ObjectInstance {
 export interface ObjectListResponse {
   items: ObjectInstance[];
   nextCursor?: string;
+  total: number;
+  facets: Record<string, Record<string, number>>;
 }
 export interface ObjectActionResponse {
   object: ObjectInstance;
@@ -138,90 +202,6 @@ export interface ObjectActionResponse {
   evidence: readonly ObjectEvidenceSummary[];
 }
 
-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;
-}
 /** Creation accepts the full metadata union, with every value optional. */
 export function objectCreateSchema(kind: UdlObjectKind): z.ZodObject {
   return z.strictObject({
@@ -239,20 +219,22 @@ export function objectCreateSchema(kind: UdlObjectKind): z.ZodObject {
   });
 }
 
-/** Canonical UDL supplies meaning; core adds authority, lifecycle and readiness. */
+/** Canonical UDL supplies meaning; core adds authority, instance state and readiness. */
 export function projectObjectDiscovery(
   document: UdlDocument,
   build: Pick<ObjectDiscovery, "productBuildId" | "digest">,
 ): ObjectDiscovery {
+  const semantics = projectDocumentSemantics(document);
   return {
     ...build,
+    semantics,
     navigation: document.objects.map((kind) => ({
       kind: kind.id,
       title: kind.title,
       creation: true,
     })),
     retainedKinds: [],
-    kinds: document.objects.map((kind) => ({
+    kinds: semantics.objects.map((kind) => ({
       ...build,
       creation: true,
       kind: kind.id,
@@ -260,6 +242,7 @@ export function projectObjectDiscovery(
       fields: kind.fields,
       authoredFields: kind.authoredFields,
       columns: kind.columns,
+      filters: objectKindFilters(kind),
       createSchema: z.toJSONSchema(objectCreateSchema(kind), { io: "input" }),
       actions: document.instruments
         .filter((instrument) => instrument.subject === kind.id)
@@ -344,9 +327,7 @@ export function projectObjectDiscovery(
                   )!.name,
                 },
                 name: action.publicAction,
-                title: action.publicAction
-                  .replace(/_/g, " ")
-                  .replace(/^./, (letter) => letter.toUpperCase()),
+                title: action.title ?? presentationLabel(action.publicAction),
                 summary: action.summary,
                 instrument: instrument.id,
                 action: name,
@@ -393,8 +374,13 @@ export function projectObjectDiscovery(
                 availability: unbound
                   ? {
                       status: "unavailable" as const,
-                      code: "subject_adapter_unbound",
-                      message: `Adapter declaration ${unbound.binding} is unavailable`,
+                      blockers: [
+                        {
+                          code: "setup_required" as const,
+                          reason:
+                            "A required external check has not been set up.",
+                        },
+                      ],
                     }
                   : { status: "available" as const },
               },
@@ -559,13 +545,15 @@ export function validateObjectActionSubject(
   const issues: SubjectRequirementIssue[] = [];
   if (
     action.availability.status === "unavailable" &&
-    action.availability.code === "subject_adapter_unbound"
+    action.availability.blockers.some(
+      (blocker) => blocker.code === "setup_required",
+    )
   ) {
     issues.push({
       code: "subject_adapter_unbound",
       action: action.name,
       origin,
-      message: action.availability.message,
+      message: "A required external check has not been set up.",
     });
   }
   const admitted = new Set(action.requirements.map((field) => field.name));

package/src/object-semantics-schema.ts

@@ -0,0 +1,148 @@
+import * as z from "zod";
+import {
+  udlActionSchema,
+  udlCalculationSchema,
+  udlFieldSchema,
+  udlInstrumentSchema,
+  udlObjectKindSchema,
+  udlObjectAttachmentSchema,
+  udlPartySchema,
+  udlRequirementSchema,
+  udlValueSchema,
+  udlKernelOperationSchema,
+  subjectPartyRoles,
+} from "./schema.js";
+
+const text = z.string();
+export const cardinalitySchema = z.strictObject({
+  min: z.number().int().nonnegative(),
+  // null means the declarations supply no upper bound.
+  max: z.number().int().nonnegative().nullable(),
+});
+export const semanticOwnerSchema = z.union([
+  z.strictObject({ kind: z.literal("instrument"), instrument: text }),
+  z.strictObject({ kind: z.literal("role"), role: z.enum(subjectPartyRoles) }),
+  z.strictObject({ kind: z.literal("party"), party: text }),
+  z.strictObject({ kind: z.literal("adapter"), adapter: text }),
+]);
+export const semanticAccountSchema = z.strictObject({
+  path: text,
+  scope: text,
+  instrument: text,
+  field: text,
+  owner: semanticOwnerSchema,
+  book: z.enum(["cash", "claim"]),
+  key: text.optional(),
+  contra: z.boolean(),
+});
+export const semanticRoleSchema = z.union([
+  semanticOwnerSchema,
+  z.strictObject({ kind: z.enum(["caller", "clock"]) }),
+  z.strictObject({ kind: z.literal("parent"), instruments: z.array(text) }),
+]);
+export const semanticRelationshipSchema = z.strictObject({
+  kind: z.enum(["reference", "child"]),
+  via: z.enum(["field", "attachment", "invocation", "parent_actor"]),
+  name: text,
+  targetKind: z.enum(["instrument", "object"]),
+  targets: z.array(text),
+  cardinality: cardinalitySchema,
+});
+export const semanticMoneyEffectSchema = z.strictObject({
+  key: text,
+  operation: udlKernelOperationSchema,
+  amount: udlValueSchema.nullable(),
+  from: z.array(semanticAccountSchema),
+  to: z.array(semanticAccountSchema),
+  // Expressions describe declared effects, never a receipt or evaluated quote.
+  disposition: z.enum(["held", "paid", "released", "claim", "unresolved"]),
+  transfer: text.nullable(),
+  reservations: z.array(
+    z.strictObject({ instrument: text, action: text, key: text }),
+  ),
+});
+export const semanticActionSchema = z.strictObject({
+  name: text,
+  alias: text.nullable(),
+  title: text,
+  actor: udlActionSchema.shape.actor,
+  roles: z.array(semanticRoleSchema),
+  from: z.array(text),
+  to: text.nullable(),
+  references: z.array(udlFieldSchema).optional(),
+  invokedBy: z
+    .array(
+      z.strictObject({
+        instrument: text,
+        action: text,
+        alias: text.nullable(),
+        invocation: udlActionSchema.shape.invoke.unwrap().element,
+      }),
+    )
+    .optional(),
+  inputs: udlActionSchema.shape.input,
+  subject: udlActionSchema.shape.subject,
+  prerequisites: udlActionSchema.shape.requires,
+  due: udlActionSchema.shape.due.unwrap().nullable(),
+  deadline: udlActionSchema.shape.deadline.unwrap().nullable(),
+  calculations: z.array(udlCalculationSchema),
+  assignments: udlActionSchema.shape.set.unwrap(),
+  moves: udlActionSchema.shape.moves,
+  moneyEffects: z.array(semanticMoneyEffectSchema),
+  invokes: udlActionSchema.shape.invoke.unwrap(),
+});
+export const semanticStructureSchema = z.enum([
+  "stage_and_decisions",
+  "payment_review",
+  "held_funds",
+  "reserved_payment",
+  "payment_calendar",
+  "funding_progress",
+  "cancellation_review",
+  "external_checks",
+  "report_view",
+]);
+export const semanticInstrumentSchema = z.strictObject({
+  id: text,
+  title: text,
+  subject: text.optional(),
+  fields: z.array(udlFieldSchema),
+  accounts: z.array(semanticAccountSchema),
+  relationships: z.array(semanticRelationshipSchema),
+  calculations: z.array(udlCalculationSchema),
+  invariants: z.array(udlRequirementSchema),
+  initialState: text,
+  lifecycle: z.strictObject({
+    initial: text,
+    states: z.array(
+      z.strictObject({ name: text, label: text, terminal: z.boolean() }),
+    ),
+    cancellationActions: z.array(text),
+  }),
+  actions: z.array(semanticActionSchema),
+  reports: udlInstrumentSchema.shape.reports.unwrap(),
+  structures: z.array(semanticStructureSchema),
+});
+export const documentSemanticsSchema = z.strictObject({
+  currency: text,
+  parties: z.record(text, udlPartySchema),
+  objects: z.array(
+    z.strictObject({
+      ...udlObjectKindSchema.shape,
+      attachments: z.array(
+        z.strictObject({
+          ...udlObjectAttachmentSchema.shape,
+          cardinality: cardinalitySchema,
+        }),
+      ),
+    }),
+  ),
+  instruments: z.array(semanticInstrumentSchema),
+});
+export type DocumentSemantics = z.infer<typeof documentSemanticsSchema>;
+export type SemanticInstrument = z.infer<typeof semanticInstrumentSchema>;
+export type SemanticAction = z.infer<typeof semanticActionSchema>;
+export type SemanticAccount = z.infer<typeof semanticAccountSchema>;
+export type SemanticOwner = z.infer<typeof semanticOwnerSchema>;
+export type SemanticRelationship = z.infer<typeof semanticRelationshipSchema>;
+export type SemanticMoneyEffect = z.infer<typeof semanticMoneyEffectSchema>;