@hyperscale0/udl 3.2.0 → 4.1.0

package/src/diagnostics.ts

@@ -1,4 +1,14 @@
 export type UdlIssueCode =
+  | "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"
   | "UDL1001"
   | "UDL1002"
   | "UDL1003"
@@ -19,9 +29,25 @@ export interface UdlIssue {
   category: string;
 }
 const fixes: Record<UdlIssueCode, string> = {
+  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.",
+
   UDL1001: "Encode the source as UTF-8.",
   UDL1002: "Repair JSON syntax.",
-  UDL1003: "Use the UDL 3 typed grammar.",
+  UDL1003: "Use the UDL 4 typed grammar.",
   UDL1004: "Reduce the declared structure or expansion.",
   UDL2001: "Give each declaration a distinct name.",
   UDL2002: "Repair the named type or declaration.",

package/src/evolution.ts

@@ -28,6 +28,14 @@ export function diffValidatedUdlEvolution(
   for (const [name, party] of Object.entries(live.parties))
     if (stable(party) !== stable(next.parties[name]))
       refuse(`$.parties.${name}`, "a live party cannot change or disappear");
+  for (const object of live.objects) {
+    const updated = next.objects.find((o) => o.id === object.id);
+    if (!updated || stable(object) !== stable(updated))
+      refuse(
+        `$.objects.${object.id}`,
+        "a live object kind cannot change or disappear; recreate development estates",
+      );
+  }
   for (const instrument of live.instruments) {
     const updated = next.instruments.find((i) => i.id === instrument.id);
     if (!updated || stable(instrument) !== stable(updated))

package/src/index.ts

@@ -3,8 +3,10 @@ export { parseUdl, canonicalizeUdl } from "./parser.js";
 export { serializeUdl, canonicalDigest } from "./canonical.js";
 export {
   validateUdl,
+  RESERVED_OBJECT_NAMES,
   assertValidUdl,
   resolveField,
+  resolveSubjectRequirement,
   UdlError,
   type UdlValidationResult,
 } from "./validation.js";
@@ -28,3 +30,4 @@ export {
   validateReportDefinition,
   reportExpressionTypes,
 } from "./reporting-validation.js";
+export * from "./object-contract.js";

package/src/instrument-references.ts

@@ -52,6 +52,29 @@ export function mapUdlInstrumentReferences(
       );
     } else if (object(value)) {
       const properties = object(schema.properties) ? schema.properties : {};
+      const discriminator = object(properties.type)
+        ? properties.type.const
+        : undefined;
+      if (
+        (discriminator === "ref" || discriminator === "list") &&
+        value.type === discriminator &&
+        value.targetKind === "instrument"
+      ) {
+        if (typeof value.target === "string")
+          locations.set(JSON.stringify([...path, "target"]), {
+            parent: value,
+            key: "target",
+            kind: "instrument",
+          });
+        else if (Array.isArray(value.target))
+          value.target.forEach((_, index) =>
+            locations.set(JSON.stringify([...path, "target", index]), {
+              parent: value.target as unknown[],
+              key: index,
+              kind: "instrument",
+            }),
+          );
+      }
       for (const [name, entry] of Object.entries(value))
         visit(
           properties[name] ?? schema.additionalProperties,
@@ -81,12 +104,13 @@ export function referencedUdlInstrumentIds(
   const found = new Set<string>();
   mapUdlInstrumentReferences(
     {
-      udl: 3,
+      udl: 4,
       version: 1,
       product: "references",
       title: "References",
       currency: "SAR",
       parties: {},
+      objects: [],
       instruments: [instrument],
     },
     (id) => {

package/src/object-contract.ts

@@ -0,0 +1,464 @@
+import * as z from "zod";
+import {
+  udlExternalIdSchema,
+  udlObjectIdSchema,
+  type UdlDocument,
+  type UdlField,
+  type UdlObjectField,
+  type UdlObjectKind,
+} from "./schema.js";
+
+export const requestAttributionSchema = z.union([
+  z.strictObject({
+    kind: z.literal("human"),
+    principalId: z.string().min(1),
+    humanId: z.string().min(1),
+    source: z.enum(["staff_session", "customer_session"]),
+  }),
+  z.strictObject({
+    kind: z.literal("machine"),
+    principalId: z.string().min(1),
+    source: z.enum(["api_key", "system"]),
+  }),
+  z.strictObject({
+    kind: z.literal("machine"),
+    principalId: z.string().min(1),
+    humanId: z.string().min(1),
+    source: z.literal("api_key_delegate"),
+  }),
+]);
+export type RequestAttribution = z.infer<typeof requestAttributionSchema>;
+
+export type JsonSchemaDocument = z.core.JSONSchema.BaseSchema;
+
+export interface ObjectKindDiscovery {
+  creation: true;
+  kind: string;
+  title: string;
+  fields: readonly UdlObjectField[];
+  authoredFields: readonly string[];
+  columns: readonly string[];
+  createSchema: JsonSchemaDocument;
+  actions: readonly ObjectActionDiscovery[];
+}
+export type ObjectActionTarget =
+  | { kind: "attachment"; attachment: string }
+  | { kind: "instance"; attachment: string; instanceId: string };
+export interface ObjectActionContext {
+  productBuildId: string;
+  digest: string;
+  target: ObjectActionTarget;
+}
+export interface ObjectActionDiscovery extends ObjectActionContext {
+  name: string;
+  title: string;
+  instrument: string;
+  action: string;
+  requirements: readonly UdlObjectField[];
+  creationRequirements?: readonly UdlObjectField[];
+  creationOnlyNames?: readonly string[];
+  inputSchema: JsonSchemaDocument;
+  fieldsSchema: JsonSchemaDocument;
+  availability:
+    | { status: "available" }
+    | { status: "unavailable"; code: string; message: string };
+}
+export type EvidenceState =
+  | "missing"
+  | "pending"
+  | "satisfied"
+  | "refused"
+  | "stale";
+
+export interface ObjectEvidenceSummary {
+  requirementId: string;
+  subjectId: string;
+  protectedInputDigest: string;
+  adapter: string;
+  declarationDigest: string;
+  productBuildId: string;
+  state: EvidenceState;
+  reference?: string;
+  observedAt?: string;
+  reasonCode?: string;
+}
+
+export interface ObjectActionState extends ObjectActionDiscovery {
+  requiredNow: readonly string[];
+  evidence?: readonly ObjectEvidenceSummary[];
+}
+/** GET /v1/products/{productId}/objects. Core supplies the frozen Build identity. */
+export type RetainedObjectKind = Pick<
+  ObjectKindDiscovery,
+  "kind" | "title" | "fields" | "authoredFields" | "columns"
+> & {
+  productBuildId: string;
+  digest: string;
+  creation: false;
+};
+export interface ObjectDiscovery {
+  retainedKinds: readonly RetainedObjectKind[];
+  productBuildId: string;
+  digest: string;
+  kinds: readonly ObjectKindDiscovery[];
+}
+export interface ObjectActionsResponse {
+  objectId: string;
+  revision: number;
+  actions: readonly ObjectActionState[];
+  evidence: readonly ObjectEvidenceSummary[];
+}
+export interface ObjectInstance {
+  objectId: string;
+  kind: string;
+  revision: number;
+  externalId?: string;
+  fields: Record<string, unknown>;
+  productBuildId: string;
+}
+export interface ObjectListResponse {
+  items: ObjectInstance[];
+  nextCursor?: string;
+}
+export interface ObjectActionResponse {
+  object: ObjectInstance;
+  outcome: { instrument: string; instanceId: string; state: string } | null;
+  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({
+    externalId: udlExternalIdSchema.optional(),
+    fields: z
+      .strictObject(
+        Object.fromEntries(
+          kind.fields.map((field) => [
+            field.name,
+            udlFieldValueSchema(field).optional(),
+          ]),
+        ),
+      )
+      .optional(),
+  });
+}
+
+/** Canonical UDL supplies meaning; core adds authority, lifecycle and readiness. */
+export function projectObjectDiscovery(
+  document: UdlDocument,
+  build: Pick<ObjectDiscovery, "productBuildId" | "digest">,
+): ObjectDiscovery {
+  return {
+    ...build,
+    retainedKinds: [],
+    kinds: document.objects.map((kind) => ({
+      creation: true,
+      kind: kind.id,
+      title: kind.title,
+      fields: kind.fields,
+      authoredFields: kind.authoredFields,
+      columns: kind.columns,
+      createSchema: z.toJSONSchema(objectCreateSchema(kind), { io: "input" }),
+      actions: document.instruments
+        .filter((instrument) => instrument.subject === kind.id)
+        .flatMap((instrument) => {
+          const createHidden =
+            !!instrument.actions.create &&
+            !instrument.actions.create.publicAction;
+          const attachmentRefListFields = instrument.fields.filter(
+            (field) =>
+              field.type === "list" &&
+              field.item === "ref" &&
+              field.targetKind !== "object",
+          );
+          return instrument.actionOrder.flatMap((name) => {
+            const action = instrument.actions[name]!;
+            if (!action.publicAction) return [];
+            const transition = instrument.lifecycle.transitions[name];
+            const canStartFromInitial = Boolean(
+              transition?.from.includes(instrument.lifecycle.initial),
+            );
+            const isCreationAction =
+              name === "create" || (createHidden && canStartFromInitial);
+
+            const rawCreateReqs: {
+              field: UdlField;
+              objectField?: string | undefined;
+            }[] = isCreationAction
+              ? [
+                  ...(instrument.actions.create?.subject?.requirements ?? []),
+                  ...attachmentRefListFields.map((field) => ({ field })),
+                ]
+              : [];
+            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];
+            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 unbound = [
+              ...(action.subject?.adapters ?? []),
+              ...(isCreationAction
+                ? (instrument.actions.create?.subject?.adapters ?? [])
+                : []),
+            ].find((adapter) => adapter.snapshot === null);
+            const seenCreation = new Set<string>();
+            const creationRequirements: UdlObjectField[] = [];
+            for (const requirement of rawCreateReqs) {
+              const name = requirement.objectField ?? requirement.field.name;
+              if (!seenCreation.has(name)) {
+                seenCreation.add(name);
+                creationRequirements.push({
+                  ...requirement.field,
+                  name,
+                } as UdlObjectField);
+              }
+            }
+            const creationOnlyNames = creationRequirements
+              .map((field) => field.name)
+              .filter((name) => !actionReqNames.has(name));
+            return [
+              {
+                ...build,
+                target: {
+                  kind: "attachment" as const,
+                  attachment: kind.attachments.find(
+                    (attachment) => attachment.instrument === instrument.id,
+                  )!.name,
+                },
+                name: action.publicAction,
+                title: action.summary,
+                instrument: instrument.id,
+                action: name,
+                requirements: mergedReqs.map(
+                  (requirement) =>
+                    ({
+                      ...requirement.field,
+                      name: requirement.objectField ?? requirement.field.name,
+                    }) as UdlObjectField,
+                ),
+                ...(creationRequirements.length > 0
+                  ? { creationRequirements }
+                  : {}),
+                ...(creationRequirements.length > 0
+                  ? { creationOnlyNames }
+                  : {}),
+                fieldsSchema: z.toJSONSchema(
+                  z.strictObject(
+                    Object.fromEntries(
+                      mergedReqs.map((requirement) => [
+                        requirement.objectField ?? requirement.field.name,
+                        udlFieldValueSchema(requirement.field).optional(),
+                      ]),
+                    ),
+                  ),
+                  { io: "input" },
+                ),
+                inputSchema: z.toJSONSchema(
+                  z.strictObject(
+                    Object.fromEntries(
+                      action.input.map((field) => [
+                        field.name,
+                        field.optional
+                          ? udlFieldValueSchema(field).optional()
+                          : udlFieldValueSchema(field),
+                      ]),
+                    ),
+                  ),
+                  { io: "input" },
+                ),
+                availability: unbound
+                  ? {
+                      status: "unavailable" as const,
+                      code: "subject_adapter_unbound",
+                      message: `Adapter declaration ${unbound.binding} is unavailable`,
+                    }
+                  : { status: "available" as const },
+              },
+            ];
+          });
+        }),
+    })),
+  };
+}
+
+/** Object-specific values determine missing fields; global discovery cannot. */
+export function objectActionState(
+  action: ObjectActionDiscovery,
+  fields: Readonly<Record<string, unknown>>,
+  options?: { attached?: boolean } | boolean,
+): ObjectActionState {
+  const attached =
+    typeof options === "boolean" ? options : (options?.attached ?? false);
+  const creationFilter = new Set(action.creationOnlyNames ?? []);
+  return {
+    ...action,
+    requiredNow: action.requirements
+      .filter((field) => {
+        const value = fields[field.name];
+        const optional =
+          field.optional || (attached && creationFilter.has(field.name));
+        return (
+          !(optional && value === undefined) &&
+          !udlFieldValueSchema(field).safeParse(value).success
+        );
+      })
+      .map((field) => field.name),
+  };
+}
+export interface SubjectRequirementIssue {
+  code:
+    | "subject_requirement_missing"
+    | "subject_field_unknown"
+    | "subject_adapter_unbound";
+  action: string;
+  field?: string;
+  origin: string;
+  message: string;
+}
+
+/** Check merged metadata before dispatch. Runtime guards add their active child requirements. */
+export function validateObjectActionSubject(
+  action: ObjectActionDiscovery,
+  storedFields: Readonly<Record<string, unknown>>,
+  submittedFields: Readonly<Record<string, unknown>>,
+  options?: { attached?: boolean } | boolean,
+): readonly SubjectRequirementIssue[] {
+  const origin = `${action.instrument}.${action.action}.subject`;
+  const issues: SubjectRequirementIssue[] = [];
+  if (
+    action.availability.status === "unavailable" &&
+    action.availability.code === "subject_adapter_unbound"
+  ) {
+    issues.push({
+      code: "subject_adapter_unbound",
+      action: action.name,
+      origin,
+      message: action.availability.message,
+    });
+  }
+  const admitted = new Set(action.requirements.map((field) => field.name));
+  for (const field of Object.keys(submittedFields)) {
+    if (!admitted.has(field))
+      issues.push({
+        code: "subject_field_unknown",
+        action: action.name,
+        field,
+        origin,
+        message: `${field} is not admitted by ${action.name}`,
+      });
+  }
+  for (const field of objectActionState(
+    action,
+    {
+      ...storedFields,
+      ...submittedFields,
+    },
+    options,
+  ).requiredNow) {
+    issues.push({
+      code: "subject_requirement_missing",
+      action: action.name,
+      field,
+      origin: `${origin}.${field}`,
+      message: `${action.name} requires a valid ${field}`,
+    });
+  }
+  return issues;
+}

package/src/reporting.ts

@@ -171,7 +171,6 @@ export const reportDefinitionSchema = z.strictObject({
     request: z.array(name).min(1).max(64),
     read: z.array(name).min(1).max(64),
     release: z.array(name).max(64),
-    independentApproval: z.literal(true),
     retention: z.strictObject({ policy: name, years: integer.min(1).max(100) }),
   }),
 });