@hyperscale0/udl 4.2.1 → 4.4.0

package/spec/README.md

@@ -8,8 +8,8 @@ lives in `src/schema.ts`. Generate `udl.schema.json` with
 
 An object kind declares identity, title, authored field names, normalized fields
 and display columns. Each attachment freezes its instrument identity and party
-parameter bindings to `owner`, `actor`, or `operator`. Core resolves these roles
-from the object row, authenticated session and product respectively. `authoredFields` records only names declared in the HSX
+parameter bindings to `owner`, `actor`, `operator`, or a declared Product party. Core resolves role bindings from the object row, session and Product, and
+declared parties from the Product party binding. `authoredFields` records only names declared in the HSX
 object block. `fields` is their union with attached action requirements. Matching
 names must have matching types and constraints. Account fields belong to
 instruments, never objects.
@@ -24,7 +24,7 @@ requirement is inferred from an operation name.
 Object creation accepts `{}`. Its optional `fields` property accepts every
 normalized field as optional. Requirements become mandatory only when the
 attached action runs. Object creation performs no financial action. Instrument
-creation remains an internal agreement operation and has no public action.
+creation remains internal; an attached create action may expose a public name.
 Attachment parties resolve from authenticated authority, never from party account
 IDs supplied in a caller body.
 
@@ -38,19 +38,12 @@ financial instrument outcome or null.
 
 ## Object operations
 
-The Product API uses six routes below `/v1/products/{productId}/objects`.
+The [Product runtime guide](../../../docs/public/runtime.md) owns the six routes
+for discovery, object creation, listing, retrieval, availability and execution.
 
-| Method | Suffix                                | Result                                         |
-| ------ | ------------------------------------- | ---------------------------------------------- |
-| GET    | root                                  | Object discovery for the Build                 |
-| POST   | `/{kind}`                             | New object with optional metadata              |
-| GET    | `/{kind}`                             | Cursor-paginated objects of a kind             |
-| GET    | `/{kind}/{objectId}`                  | Object metadata, revision and Build ID         |
-| GET    | `/{kind}/{objectId}/actions`          | Availability and missing `requiredNow` fields  |
-| POST   | `/{kind}/{objectId}/actions/{action}` | Updated object and optional instrument outcome |
-
-Execution binds `productBuildId` and `expectedRevision`. The optional `fields`
-collect subject metadata; optional `input` carries the action's typed input.
+Execution binds `productBuildId`, `digest`, `target` and `expectedRevision`.
+The target identifies an attachment or an existing instance on that attachment.
+The optional `fields` collect subject metadata; optional `input` carries the action's typed input.
 Missing requirements refuse execution. Callers reuse an idempotency key only for
 retries of the same request. Staff Create for may name `ownerPrincipalId` through
 its authorized path; ordinary ownership comes from the session.
@@ -61,19 +54,28 @@ A document declares SAR once. Money is a nonnegative minor-unit decimal string
 of at most 18 digits. Percentages are basis points, durations are positive integer
 milliseconds, and dates are timestamps with explicit offsets.
 
-An account field either binds a party or declares an account owned by the
-instrument. `owner: "self"` replaces the separate custody concept. Wallet, pool,
-receivable and entitlement are uses of accounts, not different field types.
-An external account is marked `external: true`. Its bank binding belongs to the
-executor; programs and callers never supply bank beneficiary ids. Account
-creation and binding are executor work, not caller-controlled instructions.
+An account field binds a party, the instrument itself, or an adapter. Party owners
+are names; `owner: "self"` provisions an account per instance. An adapter owner
+is `{ "adapter": "insurer" }`, where `insurer` names an adapter declared in one
+of the instrument's action subjects. The agreement retains that declaration's
+provider identity. Missing or conflicting bindings refuse with
+`subject_adapter_unbound`; changing an existing account binding refuses with
+`account_binding_changed`. A null declaration can describe a draft but cannot
+create an adapter-owned account.
+
+Account creation and binding are executor work. Callers never supply account IDs.
 Accounts declare `book: "cash" | "claim"`, defaulting to cash. Moves never cross books.
 Only claim accounts may declare `contra: true` and permit a negative balance.
-An external account must bind a party and use the cash book. A party-bound field
-is keyed by owner, book and key across the product. Its optional key defaults
-to `balance`, so payer and borrower can alias the same party account. An account
-owned by self defaults its key to the field name and is provisioned per instance.
-Named capital, profit income, debt and loss accounts declare explicit keys. `party.buyer` is the buyer's default cash account.
+Party and adapter accounts share owner, book and key within a Product; the key
+defaults to `balance`. Adapter aliases for the same provider share that account.
+The executor scopes provider accounts to the tenant and Product, with the Product
+participant as ledger custodian. Providers are not parties. An account owned by
+self defaults its key to the field name. Named capital, premium, income, debt and
+loss balances use explicit keys. `party.buyer` is the buyer's default cash account.
+
+A plain move to an adapter account credits its ledger balance. It does not prove
+an external payout. Provider confirmation still uses a boundary reservation and
+instruction-bound evidence. Account ownership adds no settlement operation.
 
 Disbursement moves cash from lender to borrower and claims from borrower debt to
 principal and profit receivables. Repayment moves borrower cash to lender cash and
@@ -91,7 +93,7 @@ declared typed references; later actions cannot replace them. A ref declares `ta
 a list of 1 to 16 distinct target ids in that namespace. Its stored value is an
 identity from one listed target. Path traversal exposes only fields
 with compatible types on every target. Nested refs combine their target sets;
-accounts must agree on owner, key, book, contra and external flags, and enums must
+accounts must agree on owner, key, book and contra flags, and enums must
 have the same values. A comparison or selection anchor must share a possible
 reference target. An invoked input must accept every possible supplied target.
 The executor checks the actual instance type at admission.
@@ -111,7 +113,7 @@ The only move instructions are `internal_transfer.create`,
 Create and reserve declare an amount, from account and to account. Reserve captures
 its executor-produced transfer identity into a declared self text field. Post and
 void consume that identity. Callers cannot create or replace captured identities.
-An external destination uses the same move vocabulary.
+Adapter-owned endpoints use the same move vocabulary.
 
 A loan, refund, payoff, write-off or distribution is library behavior built from
 accounts, calculations and ordered moves. None has a privileged executor clause.

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"
           }
         }
       },
@@ -1919,7 +1922,23 @@
               "const": "account"
             },
             "owner": {
-              "$ref": "#/$defs/__schema1"
+              "anyOf": [
+                {
+                  "$ref": "#/$defs/__schema1"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "adapter": {
+                      "$ref": "#/$defs/__schema1"
+                    }
+                  },
+                  "required": [
+                    "adapter"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
             },
             "key": {
               "$ref": "#/$defs/__schema1"
@@ -2403,6 +2422,14 @@
         },
         "objectField": {
           "$ref": "#/$defs/__schema1"
+        },
+        "when": {
+          "minItems": 1,
+          "maxItems": 128,
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/__schema47"
+          }
         }
       },
       "required": [
@@ -2411,6 +2438,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 +2567,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema48": {
+    "__schema51": {
       "oneOf": [
         {
           "type": "object",
@@ -2656,40 +2751,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 +2800,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema51": {
+    "__schema53": {
       "oneOf": [
         {
           "type": "object",
@@ -2867,7 +2929,7 @@
         }
       ]
     },
-    "__schema52": {
+    "__schema54": {
       "anyOf": [
         {
           "type": "object",
@@ -2982,14 +3044,14 @@
         }
       ]
     },
-    "__schema53": {
+    "__schema55": {
       "type": "object",
       "properties": {
         "name": {
           "$ref": "#/$defs/__schema2"
         },
         "input": {
-          "$ref": "#/$defs/__schema54"
+          "$ref": "#/$defs/__schema56"
         }
       },
       "required": [
@@ -2998,7 +3060,7 @@
       ],
       "additionalProperties": false
     },
-    "__schema54": {
+    "__schema56": {
       "anyOf": [
         {
           "type": "string"
@@ -3015,7 +3077,7 @@
         {
           "type": "array",
           "items": {
-            "$ref": "#/$defs/__schema54"
+            "$ref": "#/$defs/__schema56"
           }
         },
         {
@@ -3024,7 +3086,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[] = [];