@hyperscale0/udl 1.0.265 → 1.0.284

package/spec/README.md

@@ -24,22 +24,21 @@ A Build freezes this contract and its bindings for the executor.
 Business instructions are actions composed from typed requirements and effects.
 The four `internal_transfer` instructions are their money effects. The contract
 expresses valid conditions; execution can still refuse for the current state,
-authority, evidence or balance. Parsing and validation execute nothing.
+authority, evidence or balance. Validation executes nothing.
 
 ## JSON admission and canonical bytes
 
-The parser refuses duplicate JSON member names, including escaped spellings of
-one name. Decoded documents must contain finite JSON data. Accessors, cycles,
-sparse arrays, symbol keys, hidden properties and `__proto__` members refuse
-before schema parsing. Shared values count once per occurrence toward the budget.
-Admission permits at most 100,000 visited values, 32 nesting levels, 240 code units
-per key and 1 MiB of UTF-8 key and string data. Source text has a separate 1 MiB
-byte limit. These bounds live in `src/limits.ts`.
+`validateUdl` takes a decoded JSON value. The host reads and decodes document
+text and owns its byte limit and duplicate member policy. Numbers must be safe
+integers. Accessors, cycles, sparse arrays, symbol keys, hidden properties,
+non-plain prototypes and `__proto__` members refuse before schema parsing. Shared
+values count once per occurrence toward the budget. Admission permits at most
+100,000 visited values, 32 nesting levels, 240 code units per key and 1 MiB of
+UTF-8 key and string data. These bounds live in `src/limits.ts`.
 
 Canonical JSON sorts object keys recursively, preserves array order and ends
 with a newline. Schema defaults are part of the admitted document. Equivalent
-key insertion orders and explicit defaults have the same digest. Object field
-compatibility and evolution comparisons use the same key ordering.
+key insertion orders and explicit defaults have the same digest.
 
 ## Objects and subjects
 
@@ -66,12 +65,10 @@ Attachment parties resolve from authenticated authority, never from party accoun
 IDs supplied in a caller body.
 
 `object-contract.ts` projects `ObjectDiscovery` for
-`GET /v1/products/{productId}/objects`. It exports the discovery, instance, list
-and action response types. Discovery preserves Build identity, authored field
-names, the full optional create schema and each exposed action's requirements.
-Object instances carry `objectId`, `kind`, `revision`, optional `externalId`,
-`fields` and `productBuildId`. Action responses carry the object and either a
-financial instrument outcome or null.
+`GET /v1/products/{productId}/objects` and exports the discovery and action
+state types. Discovery preserves Build identity, authored field names, the full
+optional create schema and each exposed action's requirements. The host defines
+the object instance, list and action response types.
 
 An object may declare `entryActions`, a list of exposed attachment creation
 names. The host admits an active enrolled customer only to an entry action whose
@@ -82,8 +79,7 @@ participation never changes the owner.
 An instrument may declare `scope: "product"`. Object creation can resolve a
 reference to that instrument on another record in the same Product when every
 retained party account matches the current bindings. Otherwise references stay
-on the current record. Create and approve shared limits once per Product or
-borrower; referencing them does not create a new limit.
+on the current record.
 
 ## Object operations
 
@@ -144,7 +140,8 @@ These are ordinary paired moves in HSX, not executor loan rules.
 A value is `{literal: value}` or `{field: path}`. Paths start with `self`, `input`, `subject`
 or `party`. Reference fields allow typed traversal. Account paths expose locked,
 read-only `.balance` and `.reserved` money values. `self.id`, `self.status`,
-`self.createdAt` and `self.now` are sealed executor values. Callers cannot set
+`self.createdAt`, `self.now` and `self.productRevision` are sealed executor
+values. Callers cannot set
 constants, calculated fields, account bindings or capture fields. Create supplies
 declared typed references; later actions cannot replace them. A ref declares `targetKind: "object" | "instrument"` and one target id or
 a list of 1 to 16 distinct target ids in that namespace. Its stored value is an
@@ -161,9 +158,10 @@ Calculations form a finite dependency graph. `sum`, `subtract` and `minimum`
 operate on money or integer fields, with operands of the same type as the target.
 `rate`, `multiply`, `divide` and `shift` retain their typed operands. A shift's
 `milliseconds` operand is a duration field or a non-negative safe integer literal.
-Zero leaves the date unchanged; duration fields still require positive values. Rate and
-division round down. Weighted shares also round down; residual minor units go
-to the declared residual account. Cash and loss use this one rounding rule.
+Zero leaves the date unchanged; duration fields still require positive values. Rate,
+ratio and division round down. UDL has no residual account. A program that
+splits an amount computes its last share with `subtract`, so that share carries
+the remainder. Cash and loss use this one rounding rule.
 There is no largest-remainder allocation. Subtraction refuses a negative result. Integer results must
 be safe integers. No calculation evaluates source text.
 
@@ -232,7 +230,10 @@ balances. An invariant holds before and after every affected transaction.
 
 `hours` converts a date path to its literal IANA timezone and accepts `[start,end)`.
 A start greater than end wraps midnight; equal endpoints admit no time.
-`evidence` declares subject, family, check, result and maxAge. The subject is an
+`evidence` declares subject, family, check, result and maxAge. Optional `instruction`
+is a path to a captured boundary instruction (HSX: `instruction self.receipt`).
+Only instruction-bound requirements consume settlement evidence once; ordinary
+identity evidence remains reusable. The subject is an
 account or text id. The executor selects the newest matching subject binding,
 checks its retained Build, protected input digest and adapter declaration, then
 requires the declared result and age. A newer matching refusal or pending result

package/spec/udl.schema.json

@@ -1282,36 +1282,6 @@
               "items": {
                 "$ref": "#/$defs/__schema40"
               }
-            },
-            "lockTimeoutMs": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 2000,
-              "$ref": "#/$defs/__schema29"
-            },
-            "captureTimeoutMs": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 10000,
-              "$ref": "#/$defs/__schema29"
-            },
-            "maxRows": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 100000,
-              "$ref": "#/$defs/__schema29"
-            },
-            "maxJoinRows": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 1000000,
-              "$ref": "#/$defs/__schema29"
-            },
-            "maxBytes": {
-              "type": "integer",
-              "minimum": 1024,
-              "maximum": 16777216,
-              "$ref": "#/$defs/__schema29"
             }
           },
           "required": [
@@ -1319,12 +1289,7 @@
             "required",
             "rowReconcile",
             "reconcile",
-            "unavailableFacts",
-            "lockTimeoutMs",
-            "captureTimeoutMs",
-            "maxRows",
-            "maxJoinRows",
-            "maxBytes"
+            "unavailableFacts"
           ],
           "additionalProperties": false
         },

package/src/diagnostics.ts

@@ -25,12 +25,13 @@ export interface UdlIssue {
   message: string;
   fix: string;
   category: string;
-  stranded?: {
-    state: string;
-    accounts: string[];
-    actions: string[];
-    paths: Record<string, string[]>;
-  };
+  stranded?: Stranded;
+}
+export interface Stranded {
+  state: string;
+  accounts: string[];
+  actions: string[];
+  paths: Record<string, string[]>;
 }
 const fixes: Record<UdlIssueCode, string> = {
   economic_party_unbound:

package/src/field-value.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 import { udlObjectIdSchema, type UdlField } from "./schema.js";
+import { amount, integer, isMinorUnits, text } from "./primitives.js";
 
-const amount = z.string().regex(/^(0|[1-9][0-9]{0,17})$/);
-const text = z.string().min(1).max(2048);
 // HSX dates are instants; say so when a caller sends a calendar date.
 const dateTime = z.iso.datetime({
   offset: true,
@@ -18,7 +17,7 @@ export function udlFieldValueSchema(field: UdlField): z.ZodType {
       schema = amount
         .refine(
           (value) =>
-            /^(0|[1-9][0-9]{0,17})$/.test(value) &&
+            isMinorUnits(value) &&
             (field.minimum === undefined ||
               BigInt(value) >= BigInt(field.minimum)) &&
             (field.maximum === undefined ||
@@ -44,7 +43,7 @@ export function udlFieldValueSchema(field: UdlField): z.ZodType {
       schema = dateTime;
       break;
     case "duration":
-      schema = z.number().int().safe().positive();
+      schema = integer.positive();
       break;
     case "text": {
       let value = z
@@ -56,7 +55,7 @@ export function udlFieldValueSchema(field: UdlField): z.ZodType {
       break;
     }
     case "integer": {
-      let value = z.number().int().safe();
+      let value = integer;
       if (field.minimum !== undefined) value = value.min(field.minimum);
       if (field.maximum !== undefined) value = value.max(field.maximum);
       schema = value;
@@ -78,7 +77,7 @@ export function udlFieldValueSchema(field: UdlField): z.ZodType {
           : field.item === "date"
             ? dateTime
             : field.item === "integer"
-              ? z.number().int().safe()
+              ? integer
               : field.item === "ref" && field.targetKind === "object"
                 ? udlObjectIdSchema
                 : text;

package/src/finance.ts

@@ -4,16 +4,13 @@ import type {
   UdlInstrument,
   UdlValue,
 } from "./schema.js";
+import { targetIds } from "./primitives.js";
+import type { Stranded } from "./diagnostics.js";
 
 export interface FinanceIssue {
   path: string;
   message: string;
-  stranded?: {
-    state: string;
-    accounts: string[];
-    actions: string[];
-    paths: Record<string, string[]>;
-  };
+  stranded?: Stranded;
 }
 type Sum = Map<string, bigint>;
 type Balance = Sum | null;
@@ -59,6 +56,12 @@ export function analyzeInstrumentFinance(
       .filter((f) => f.type === "account" && f.owner === "self")
       .map((f) => `self.${f.name}`),
   );
+  /** The owned account a `.balance` read names; this pass tracks no other account. */
+  const ownedAccount = (field: string): string | undefined => {
+    if (!field.endsWith(".balance")) return undefined;
+    const account = field.slice(0, -".balance".length);
+    return owned.has(account) ? account : undefined;
+  };
   const shared = new Set<string>();
   for (const owner of document?.instruments ?? []) {
     if (owner.id === instrument.id) continue;
@@ -76,10 +79,7 @@ export function analyzeInstrumentFinance(
                   (field) => field.name === key,
                 );
                 if (reference?.type !== "ref") return [];
-                const ids =
-                  typeof reference.target === "string"
-                    ? [reference.target]
-                    : reference.target;
+                const ids = targetIds(reference.target);
                 return (
                   document?.instruments.filter((candidate) =>
                     ids.includes(candidate.id),
@@ -219,19 +219,21 @@ export function analyzeInstrumentFinance(
       ...downstream((field) => declared.has(field)),
     ]);
     let reading = 0;
+    // The pass keeps no reserved total per account, so a reserved read is external even on an owned account.
     const external = (field: string) =>
-      /\.(balance|reserved)$/.test(field) && !owned.has(field.slice(0, -8));
+      field.endsWith(".reserved") ||
+      (field.endsWith(".balance") && ownedAccount(field) === undefined);
     const resolve = (sum: Sum): Balance => {
       let result: Balance = new Map();
       for (const [key, coefficient] of sum) {
-        const account = key.slice(0, -8);
+        const account = ownedAccount(key);
         const scoped =
           balanceBound.has(key) ||
           fresh.has(key) ||
           live.has(key) ||
           external(key);
         const term: Balance =
-          key.endsWith(".balance") && owned.has(account)
+          account !== undefined
             ? (start.get(account) ?? null)
             : new Map([[scoped ? `${scope}:${key}` : key, 1n]]);
         result = add(result, term, coefficient);
@@ -245,11 +247,8 @@ export function analyzeInstrumentFinance(
     const amount = (value: UdlValue, seen = new Set<string>()): Balance => {
       if ("field" in value) {
         if (calculated.has(value.field)) return calculated.get(value.field)!;
-        if (
-          value.field.endsWith(".balance") &&
-          owned.has(value.field.slice(0, -8))
-        )
-          return state.balances.get(value.field.slice(0, -8)) ?? null;
+        const account = ownedAccount(value.field);
+        if (account !== undefined) return state.balances.get(account) ?? null;
         // Another account's balance moves between reads, so each read is its own symbol.
         if (external(value.field))
           return new Map([[`${scope}:${reading++}:${value.field}`, 1n]]);
@@ -277,10 +276,9 @@ export function analyzeInstrumentFinance(
           [requirement.left, requirement.right],
           [requirement.right, requirement.left],
         ] as const) {
-          if ("field" in left && left.field.endsWith(".balance")) {
-            const account = left.field.slice(0, -8);
-            if (owned.has(account)) state.balances.set(account, amount(right));
-          }
+          const account =
+            "field" in left ? ownedAccount(left.field) : undefined;
+          if (account !== undefined) state.balances.set(account, amount(right));
         }
       }
     for (const key of local.keys()) calculated.set(key, amount({ field: key }));

package/src/limits.ts

@@ -2,6 +2,5 @@ export const UDL_LIMITS = Object.freeze({
   maxDepth: 32,
   maxKeyLength: 240,
   maxNodes: 100_000,
-  maxSourceBytes: 1_024 * 1_024,
   maxTotalStringLength: 1_024 * 1_024,
 });

package/src/object-contract.ts

@@ -461,10 +461,9 @@ function requirementPossible(
 export function objectActionState(
   action: ObjectActionDiscovery,
   fields: Readonly<Record<string, unknown>>,
-  options?: ObjectActionStateOptions | boolean,
+  options: ObjectActionStateOptions = {},
 ): ObjectActionState {
-  const attached =
-    typeof options === "boolean" ? options : (options?.attached ?? false);
+  const attached = options.attached ?? false;
   const creationFilter = new Set(action.creationOnlyNames ?? []);
   return {
     ...action,
@@ -477,12 +476,7 @@ export function objectActionState(
             : undefined;
         if (
           conditions &&
-          !requirementPossible(
-            conditions,
-            action,
-            fields,
-            typeof options === "object" ? options : {},
-          )
+          !requirementPossible(conditions, action, fields, options)
         )
           return false;
         const value = fields[field.name];
@@ -512,7 +506,7 @@ export function validateObjectActionSubject(
   action: ObjectActionDiscovery,
   storedFields: Readonly<Record<string, unknown>>,
   submittedFields: Readonly<Record<string, unknown>>,
-  options?: ObjectActionStateOptions | boolean,
+  options: ObjectActionStateOptions = {},
 ): readonly SubjectRequirementIssue[] {
   const origin = `${action.instrument}.${action.action}.subject`;
   const issues: SubjectRequirementIssue[] = [];

package/src/object-semantics.ts

@@ -6,6 +6,7 @@ import {
   type UdlAction,
 } from "./schema.js";
 import { resolveField } from "./validation.js";
+import { own, targetIds } from "./primitives.js";
 import type {
   DocumentSemantics,
   SemanticAccount,
@@ -40,8 +41,6 @@ const labelled = <T extends UdlField>(field: T): T => ({
   ...field,
   label: field.label ?? presentationLabel(field.name),
 });
-const targets = (target: string | string[]) =>
-  typeof target === "string" ? [target] : target;
 
 function owner(
   document: UdlDocument,
@@ -52,11 +51,12 @@ function owner(
     return { kind: "adapter", adapter: value.adapter };
   if (value === "self")
     return { kind: "instrument", instrument: instrument.id };
-  const binding = document.objects
-    .flatMap((object) => object.attachments)
-    .find((attachment) => attachment.instrument === instrument.id)?.parties[
-    value
-  ];
+  const binding = own(
+    document.objects
+      .flatMap((object) => object.attachments)
+      .find((attachment) => attachment.instrument === instrument.id)?.parties,
+    value,
+  );
   if (binding)
     return "role" in binding
       ? { kind: "role", role: binding.role }
@@ -82,7 +82,7 @@ function scopes(
     field.targetKind === "instrument"
   )
     return document.instruments
-      .filter((candidate) => targets(field.target).includes(candidate.id))
+      .filter((candidate) => targetIds(field.target).includes(candidate.id))
       .flatMap((candidate) =>
         scopes(document, candidate, `self.${rest.join(".")}`),
       );
@@ -200,7 +200,7 @@ function relationships(
             via: "field" as const,
             name: field.name,
             targetKind: field.targetKind,
-            targets: targets(field.target),
+            targets: targetIds(field.target),
             cardinality: { min: field.optional ? 0 : 1, max: 1 },
           },
         ];
@@ -252,7 +252,7 @@ function relationships(
       (action) =>
         typeof action.actor === "object" &&
         "parent" in action.actor &&
-        targets(action.actor.parent).includes(instrument.id),
+        targetIds(action.actor.parent).includes(instrument.id),
     );
     if (
       parentActor &&
@@ -260,7 +260,7 @@ function relationships(
         (field) =>
           field.type === "ref" &&
           field.targetKind === "instrument" &&
-          targets(field.target).includes(instrument.id),
+          targetIds(field.target).includes(instrument.id),
       )
     )
       references.push({
@@ -292,7 +292,7 @@ function projectAction(
         ? { kind: actor }
         : "party" in actor
           ? owner(document, instrument, actor.party)
-          : { kind: "parent", instruments: targets(actor.parent) },
+          : { kind: "parent", instruments: targetIds(actor.parent) },
     ],
     from: transition?.from ?? [],
     to:
@@ -360,7 +360,8 @@ export function projectDocumentSemantics(
         initial: instrument.lifecycle.initial,
         states: instrument.lifecycle.states.map((name) => ({
           name,
-          label: instrument.lifecycle.labels?.[name] ?? presentationLabel(name),
+          label:
+            own(instrument.lifecycle.labels, name) ?? presentationLabel(name),
           terminal: isTerminalState(instrument, name),
         })),
         cancellationActions: [],

package/src/object-structures.ts

@@ -3,6 +3,7 @@ import type {
   SemanticAction,
   SemanticInstrument,
 } from "./object-semantics-schema.js";
+import { targetIds } from "./primitives.js";
 
 const hasMoney = (instrument: SemanticInstrument) =>
   instrument.actions.some((action) => action.moneyEffects.length > 0);
@@ -149,10 +150,7 @@ export function projectStructures(
   );
   const funding = contributions.some((selection) => {
     if (selection.anchor !== "self.id") return false;
-    const ids =
-      typeof selection.instrument === "string"
-        ? [selection.instrument]
-        : selection.instrument;
+    const ids = targetIds(selection.instrument);
     const children = instruments.filter(
       (candidate) =>
         ids.includes(candidate.id) &&

package/src/primitives.ts

@@ -0,0 +1,29 @@
+import * as z from "zod";
+
+const minorUnits = /^(0|[1-9][0-9]{0,17})$/;
+
+export const name = z
+  .string()
+  .regex(/^[a-z][a-zA-Z0-9_]*$/)
+  .max(80);
+export const text = z.string().min(1).max(2048);
+export const amount = z.string().regex(minorUnits);
+export const integer = z.number().int().safe();
+export const path = z
+  .string()
+  .regex(/^[a-z][a-zA-Z0-9_]*(?:\.[a-z][a-zA-Z0-9_]*)*$/)
+  .max(240);
+
+/** True for a money amount in minor units. Guard every BigInt() of an unchecked amount with it. */
+export const isMinorUnits = (value: string): boolean => minorUnits.test(value);
+
+/** Reads only the record's own keys, so names like `constructor` never reach the prototype. */
+export function own<T>(
+  record: Record<string, T> | undefined,
+  key: string,
+): T | undefined {
+  return record && Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+export const targetIds = (target: string | string[]): string[] =>
+  typeof target === "string" ? [target] : target;

package/src/reporting-validation.ts

@@ -4,6 +4,7 @@ import type {
   ReportExpression,
   ReportType,
 } from "./reporting.js";
+import { isMinorUnits } from "./primitives.js";
 
 type Types = Map<string, ReportType>;
 const sealedFields = new Map([
@@ -49,7 +50,7 @@ export function reportExpressionTypes(
         const value = expression.value;
         requireRule(
           result.kind === "money"
-            ? typeof value === "string" && /^(0|[1-9][0-9]{0,17})$/.test(value)
+            ? typeof value === "string" && isMinorUnits(value)
             : result.kind === "integer"
               ? typeof value === "number" && Number.isSafeInteger(value)
               : result.kind === "boolean"

package/src/reporting.ts

@@ -144,11 +144,6 @@ export const reportDefinitionSchema = z.strictObject({
     rowReconcile: z.array(z.strictObject({ left: name, right: name })).max(16),
     reconcile: z.array(z.strictObject({ left: name, right: name })).max(16),
     unavailableFacts: z.array(z.string().min(1).max(240)).max(32),
-    lockTimeoutMs: integer.min(1).max(2000),
-    captureTimeoutMs: integer.min(1).max(10000),
-    maxRows: integer.min(1).max(100000),
-    maxJoinRows: integer.min(1).max(1000000),
-    maxBytes: integer.min(1024).max(16777216),
   }),
   output: z.strictObject({
     profile: z.literal("internal.v1"),

package/src/schema.ts

@@ -5,7 +5,7 @@ import { writeJson } from "./json.js";
 
 export const UDL_FORMAT_VERSION = 1 as const;
 /** Counts the root and every nested invocation, including selected and ranged children. */
-export const MAX_ACTION_EXPANSION = 4096;
+export const MAX_ACTION_EXPANSION = 8192;
 const name = z
   .string()
   .regex(/^[a-z][a-zA-Z0-9_]*$/)
@@ -454,6 +454,7 @@ export const udlActionSchema = z.strictObject({
   summary: text,
   title: text.optional(),
   publicAction: name.optional(),
+  // Retained Builds keep this key; execution uses MAX_ACTION_EXPANSION.
   expansionLimit: z.literal(8192).optional(),
   reminder: z
     .strictObject({