@hyperscale0/udl 4.2.1 → 4.3.0

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"),