@hyperscale0/udl 4.2.0 → 4.3.0

package/spec/udl.schema.json

@@ -149,6 +149,9 @@
         "name": {
           "$ref": "#/$defs/__schema1"
         },
+        "parent": {
+          "$ref": "#/$defs/__schema1"
+        },
         "instrument": {
           "$ref": "#/$defs/__schema6"
         },
@@ -911,7 +914,7 @@
                     "maxItems": 16,
                     "type": "array",
                     "items": {
-                      "$ref": "#/$defs/__schema47"
+                      "$ref": "#/$defs/__schema50"
                     }
                   }
                 },
@@ -932,14 +935,14 @@
                 "maxItems": 128,
                 "type": "array",
                 "items": {
-                  "$ref": "#/$defs/__schema48"
+                  "$ref": "#/$defs/__schema51"
                 }
               },
               "due": {
-                "$ref": "#/$defs/__schema50"
+                "$ref": "#/$defs/__schema52"
               },
               "deadline": {
-                "$ref": "#/$defs/__schema50"
+                "$ref": "#/$defs/__schema52"
               },
               "set": {
                 "type": "object",
@@ -961,14 +964,14 @@
                 "maxItems": 256,
                 "type": "array",
                 "items": {
-                  "$ref": "#/$defs/__schema51"
+                  "$ref": "#/$defs/__schema53"
                 }
               },
               "invoke": {
                 "maxItems": 16,
                 "type": "array",
                 "items": {
-                  "$ref": "#/$defs/__schema52"
+                  "$ref": "#/$defs/__schema54"
                 }
               }
             },
@@ -995,14 +998,14 @@
           "maxItems": 128,
           "type": "array",
           "items": {
-            "$ref": "#/$defs/__schema48"
+            "$ref": "#/$defs/__schema51"
           }
         },
         "examples": {
           "maxItems": 16,
           "type": "array",
           "items": {
-            "$ref": "#/$defs/__schema53"
+            "$ref": "#/$defs/__schema55"
           }
         }
       },
@@ -2403,6 +2406,14 @@
         },
         "objectField": {
           "$ref": "#/$defs/__schema1"
+        },
+        "when": {
+          "minItems": 1,
+          "maxItems": 128,
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/__schema47"
+          }
         }
       },
       "required": [
@@ -2411,6 +2422,74 @@
       "additionalProperties": false
     },
     "__schema47": {
+      "minItems": 1,
+      "maxItems": 32,
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/__schema48"
+      }
+    },
+    "__schema48": {
+      "type": "object",
+      "properties": {
+        "instrument": {
+          "$ref": "#/$defs/__schema6"
+        },
+        "action": {
+          "$ref": "#/$defs/__schema1"
+        },
+        "guard": {
+          "$ref": "#/$defs/__schema49"
+        },
+        "valueType": {
+          "type": "string",
+          "enum": [
+            "money",
+            "date"
+          ]
+        }
+      },
+      "required": [
+        "instrument",
+        "action",
+        "guard"
+      ],
+      "additionalProperties": false
+    },
+    "__schema49": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "compare"
+        },
+        "left": {
+          "$ref": "#/$defs/__schema43"
+        },
+        "operator": {
+          "type": "string",
+          "enum": [
+            "==",
+            "!=",
+            "<",
+            "<=",
+            ">",
+            ">="
+          ]
+        },
+        "right": {
+          "$ref": "#/$defs/__schema43"
+        }
+      },
+      "required": [
+        "kind",
+        "left",
+        "operator",
+        "right"
+      ],
+      "additionalProperties": false
+    },
+    "__schema50": {
       "type": "object",
       "properties": {
         "binding": {
@@ -2472,7 +2551,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema48": {
+    "__schema51": {
       "oneOf": [
         {
           "type": "object",
@@ -2656,40 +2735,7 @@
         }
       ]
     },
-    "__schema49": {
-      "type": "object",
-      "properties": {
-        "kind": {
-          "type": "string",
-          "const": "compare"
-        },
-        "left": {
-          "$ref": "#/$defs/__schema43"
-        },
-        "operator": {
-          "type": "string",
-          "enum": [
-            "==",
-            "!=",
-            "<",
-            "<=",
-            ">",
-            ">="
-          ]
-        },
-        "right": {
-          "$ref": "#/$defs/__schema43"
-        }
-      },
-      "required": [
-        "kind",
-        "left",
-        "operator",
-        "right"
-      ],
-      "additionalProperties": false
-    },
-    "__schema50": {
+    "__schema52": {
       "type": "object",
       "properties": {
         "at": {
@@ -2738,7 +2784,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema51": {
+    "__schema53": {
       "oneOf": [
         {
           "type": "object",
@@ -2867,7 +2913,7 @@
         }
       ]
     },
-    "__schema52": {
+    "__schema54": {
       "anyOf": [
         {
           "type": "object",
@@ -2982,14 +3028,14 @@
         }
       ]
     },
-    "__schema53": {
+    "__schema55": {
       "type": "object",
       "properties": {
         "name": {
           "$ref": "#/$defs/__schema2"
         },
         "input": {
-          "$ref": "#/$defs/__schema54"
+          "$ref": "#/$defs/__schema56"
         }
       },
       "required": [
@@ -2998,7 +3044,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema54": {
+    "__schema56": {
       "anyOf": [
         {
           "type": "string"
@@ -3015,7 +3061,7 @@
         {
           "type": "array",
           "items": {
-            "$ref": "#/$defs/__schema54"
+            "$ref": "#/$defs/__schema56"
           }
         },
         {
@@ -3024,7 +3070,7 @@
             "type": "string"
           },
           "additionalProperties": {
-            "$ref": "#/$defs/__schema54"
+            "$ref": "#/$defs/__schema56"
           }
         }
       ]

package/src/object-contract.ts

@@ -6,6 +6,9 @@ import {
   type UdlField,
   type UdlObjectField,
   type UdlObjectKind,
+  type UdlSubjectRequirement,
+  type UdlValue,
+  type UdlInstrument,
 } from "./schema.js";
 
 export const requestAttributionSchema = z.union([
@@ -58,6 +61,10 @@ export interface ObjectActionDiscovery extends ObjectActionContext {
   instrument: string;
   action: string;
   requirements: readonly UdlObjectField[];
+  requirementConditions?: Record<
+    string,
+    NonNullable<UdlSubjectRequirement["when"]>
+  >;
   creationRequirements?: readonly UdlObjectField[];
   creationOnlyNames?: readonly string[];
   inputSchema: JsonSchemaDocument;
@@ -275,33 +282,36 @@ export function projectObjectDiscovery(
             const isCreationAction =
               name === "create" || (createHidden && canStartFromInitial);
 
-            const rawCreateReqs: {
-              field: UdlField;
-              objectField?: string | undefined;
-            }[] = isCreationAction
+            const rawCreateReqs: UdlSubjectRequirement[] = isCreationAction
               ? [
                   ...(instrument.actions.create?.subject?.requirements ?? []),
-                  ...attachmentRefListFields.map((field) => ({ field })),
+                  ...attachmentRefListFields.map((field) => ({
+                    field: field as UdlObjectField,
+                  })),
                 ]
               : [];
             const actionReqs = action.subject?.requirements ?? [];
             const actionReqNames = new Set(
               actionReqs.map((r) => r.objectField ?? r.field.name),
             );
-            const mergedReqs: {
-              field: UdlField;
-              objectField?: string | undefined;
-            }[] = [...actionReqs];
+            const mergedReqs: UdlSubjectRequirement[] = actionReqs.map(
+              (requirement) => ({ ...requirement }),
+            );
             for (const req of rawCreateReqs) {
               const reqName = req.objectField ?? req.field.name;
-              if (
-                !mergedReqs.some(
-                  (r) => (r.objectField ?? r.field.name) === reqName,
-                )
-              ) {
-                mergedReqs.push(req);
-              }
+              const existing = mergedReqs.find(
+                (r) => (r.objectField ?? r.field.name) === reqName,
+              );
+              if (!existing) mergedReqs.push({ ...req });
+              else if (!req.when) delete existing.when;
+              else if (existing.when)
+                existing.when = [...existing.when, ...req.when];
             }
+            const requirementConditions = Object.fromEntries(
+              mergedReqs.flatMap((req) =>
+                req.when ? [[req.objectField ?? req.field.name, req.when]] : [],
+              ),
+            );
             const unbound = [
               ...(action.subject?.adapters ?? []),
               ...(isCreationAction
@@ -346,6 +356,9 @@ export function projectObjectDiscovery(
                       name: requirement.objectField ?? requirement.field.name,
                     }) as UdlObjectField,
                 ),
+                ...(Object.keys(requirementConditions).length
+                  ? { requirementConditions }
+                  : {}),
                 ...(creationRequirements.length > 0
                   ? { creationRequirements }
                   : {}),
@@ -391,11 +404,104 @@ export function projectObjectDiscovery(
   };
 }
 
+/** Values overwritten before invocation cannot decide a guard during discovery. */
+export function objectActionSelf(
+  instrument: UdlInstrument,
+  actionName: string,
+  fields: Readonly<Record<string, unknown>> = {},
+): Record<string, unknown> {
+  const action = instrument.actions[actionName]!;
+  const known = {
+    ...Object.fromEntries(
+      instrument.fields.flatMap((field) =>
+        "value" in field ? [[field.name, field.value]] : [],
+      ),
+    ),
+    ...fields,
+  };
+  for (const calculation of [
+    ...instrument.calculate,
+    ...(action.calculate ?? []),
+  ])
+    delete known[calculation.target];
+  for (const name of Object.keys(action.set ?? {})) delete known[name];
+  return known;
+}
+
+export interface ObjectActionStateOptions {
+  attached?: boolean;
+  self?: Readonly<Record<string, unknown>>;
+  input?: Readonly<Record<string, unknown>>;
+}
+
+/** Unknown invocation state remains possible; a known false guard suppresses a prompt. */
+function requirementPossible(
+  paths: NonNullable<UdlSubjectRequirement["when"]>,
+  action: ObjectActionDiscovery,
+  fields: Readonly<Record<string, unknown>>,
+  options: ObjectActionStateOptions,
+): boolean {
+  return paths.some((path) =>
+    path.every((condition) => {
+      const read = (value: UdlValue): unknown => {
+        if ("literal" in value) return value.literal;
+        const [root, name, ...tail] = value.field.split(".");
+        if (!name || tail.length) return undefined;
+        if (root === "subject") return fields[name];
+        if (
+          condition.instrument !== action.instrument ||
+          condition.action !== action.action
+        )
+          return undefined;
+        if (root === "self") return options.self?.[name];
+        if (root === "input") return options.input?.[name];
+        return undefined;
+      };
+      let left = read(condition.guard.left);
+      let right = read(condition.guard.right);
+      if (left === undefined || right === undefined) return true;
+      try {
+        if (condition.valueType === "money") {
+          left = BigInt(String(left));
+          right = BigInt(String(right));
+        } else if (condition.valueType === "date") {
+          left = Date.parse(String(left));
+          right = Date.parse(String(right));
+          if (!Number.isFinite(left) || !Number.isFinite(right)) return true;
+        }
+      } catch {
+        return true;
+      }
+      if (
+        typeof left !== typeof right ||
+        !["string", "number", "boolean", "bigint"].includes(typeof left)
+      )
+        return true;
+      const a = left as string | number | bigint;
+      const b = right as string | number | bigint;
+      switch (condition.guard.operator) {
+        case "==":
+          return left === right;
+        case "!=":
+          return left !== right;
+        case "<":
+          return a < b;
+        case "<=":
+          return a <= b;
+        case ">":
+          return a > b;
+        case ">=":
+          return a >= b;
+      }
+    }),
+  );
+}
+
 /** Object-specific values determine missing fields; global discovery cannot. */
 export function objectActionState(
   action: ObjectActionDiscovery,
   fields: Readonly<Record<string, unknown>>,
-  options?: { attached?: boolean } | boolean,
+  options?: ObjectActionStateOptions | boolean,
 ): ObjectActionState {
   const attached =
     typeof options === "boolean" ? options : (options?.attached ?? false);
@@ -404,6 +510,17 @@ export function objectActionState(
     ...action,
     requiredNow: action.requirements
       .filter((field) => {
+        const conditions = action.requirementConditions?.[field.name];
+        if (
+          conditions &&
+          !requirementPossible(
+            conditions,
+            action,
+            fields,
+            typeof options === "object" ? options : {},
+          )
+        )
+          return false;
         const value = fields[field.name];
         const optional =
           field.optional || (attached && creationFilter.has(field.name));
@@ -431,7 +548,7 @@ export function validateObjectActionSubject(
   action: ObjectActionDiscovery,
   storedFields: Readonly<Record<string, unknown>>,
   submittedFields: Readonly<Record<string, unknown>>,
-  options?: { attached?: boolean } | boolean,
+  options?: ObjectActionStateOptions | boolean,
 ): readonly SubjectRequirementIssue[] {
   const origin = `${action.instrument}.${action.action}.subject`;
   const issues: SubjectRequirementIssue[] = [];

package/src/schema.ts

@@ -154,10 +154,43 @@ export const udlObjectFieldSchema = z.discriminatedUnion("type", [
   boundedListField,
 ]);
 
+/** Values are constants or resolved typed paths, never executable strings. */
+export const udlValueSchema = z.union([
+  z.strictObject({ literal: scalar }),
+  z.strictObject({ field: path }),
+]);
+const value = udlValueSchema;
+
+const comparisonRequirement = z.strictObject({
+  kind: z.literal("compare"),
+  left: value,
+  operator: z.enum(["==", "!=", "<", "<=", ">", ">="]),
+  right: value,
+});
+
+// Alternatives are OR; each invocation path is a conjunction of scoped guards.
+export const udlSubjectConditionsSchema = z
+  .array(
+    z
+      .array(
+        z.strictObject({
+          instrument: instrumentId,
+          action: name,
+          guard: comparisonRequirement,
+          valueType: z.enum(["money", "date"]).optional(),
+        }),
+      )
+      .min(1)
+      .max(32),
+  )
+  .min(1)
+  .max(128);
+
 export const udlSubjectRequirementSchema = z.strictObject({
   field: udlObjectFieldSchema,
   // Present only for an authored rename.
   objectField: name.optional(),
+  when: udlSubjectConditionsSchema.optional(),
 });
 
 export const adapterSubjectSnapshotSchema = z.strictObject({
@@ -192,6 +225,7 @@ export type AttachmentPartyBinding = z.infer<
 >;
 export const udlObjectAttachmentSchema = z.strictObject({
   name,
+  parent: name.optional(),
   instrument: instrumentId,
   parties: z.record(name, attachmentPartyBindingSchema),
 });
@@ -207,12 +241,6 @@ export const udlObjectKindSchema = z.strictObject({
   columns: z.array(name).max(8),
 });
 
-/** Values are constants or resolved typed paths, never executable strings. */
-export const udlValueSchema = z.union([
-  z.strictObject({ literal: scalar }),
-  z.strictObject({ field: path }),
-]);
-const value = udlValueSchema;
 const values = z.array(value).min(1).max(256);
 
 const selection = z.strictObject({
@@ -295,13 +323,6 @@ 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"),

package/src/validation.ts

@@ -315,7 +315,12 @@ function resolvePath(
   }
   if (root === "subject") {
     const requirement = resolveSubjectRequirement(instrument, key, action);
-    if (!requirement || !instrument.subject) return;
+    if (!requirement) return;
+    // Evidence collected at the action need not exist on the object; the
+    // declared requirement is the contract for a bare `subject.<name>`.
+    if (parts.length === 0 && !requirement.objectField)
+      return requirement.field;
+    if (!instrument.subject) return;
     const object = document.objects.find(
       (item) => item.id === instrument.subject,
     );