@hyperscale0/udl 3.1.0 → 4.0.0

package/dist/validation.js

@@ -1,6 +1,37 @@
-import { udlDocumentSchema, } from "./schema.js";
+import { udlDocumentSchema, subjectPartyRoles, sameObjectField, MAX_ACTION_EXPANSION, } from "./schema.js";
 import { issue } from "./diagnostics.js";
+import { validateReportDefinition } from "./reporting-validation.js";
 import { analyzeInstrumentFinance } from "./finance.js";
+export const RESERVED_OBJECT_NAMES = [
+    "objectId",
+    "externalId",
+    "revision",
+    "kind",
+    "tenantId",
+    "productId",
+];
+const reservedObjectNamesSet = new Set(RESERVED_OBJECT_NAMES);
+function hasParty(document, instrument, name) {
+    if (document.parties[name])
+        return true;
+    if (!instrument?.subject)
+        return false;
+    return (document.objects
+        .find((kind) => kind.id === instrument.subject)
+        ?.attachments.some((attachment) => (attachment.instrument === instrument.id ||
+        instrument.id.startsWith(`${attachment.instrument}_`)) &&
+        Object.values(attachment.parties).some((binding) => "role" in binding ? binding.role === name : binding.party === name)) ?? false);
+}
+function moneyParty(document, instrument, name) {
+    return (hasParty(document, instrument, name) &&
+        (document.parties[name]?.kind === "business" ||
+            (!document.parties[name] && !!instrument?.subject) ||
+            (!instrument?.subject && document.parties[name]?.kind === "person")));
+}
+function approvalParty(document, name) {
+    const party = document.parties[name];
+    return party?.kind === "staff" && !!party.role;
+}
 export class UdlError extends Error {
     issues;
     constructor(issues) {
@@ -49,17 +80,26 @@ function commonField(fields) {
             field.optional !== first.optional))
         return;
     if (first.type === "ref") {
+        if (fields.some((field) => field?.type !== "ref" ||
+            field.targetKind !== first.targetKind ||
+            JSON.stringify(field.targetFamily) !==
+                JSON.stringify(first.targetFamily)))
+            return;
         const targets = [
             ...new Set(fields.flatMap((field) => field?.type === "ref" ? targetIds(field.target) : [])),
         ];
-        return { ...first, target: targets.length === 1 ? targets[0] : targets };
+        return {
+            ...first,
+            targetKind: first.targetKind,
+            target: targets.length === 1 ? targets[0] : targets,
+            ...(first.targetFamily ? { targetFamily: first.targetFamily } : {}),
+        };
     }
     if (first.type === "account" &&
         fields.some((field) => field?.type !== "account" ||
             field.book !== first.book ||
             field.owner !== first.owner ||
             field.key !== first.key ||
-            field.external !== first.external ||
             field.contra !== first.contra))
         return;
     if (first.type === "enum" &&
@@ -70,23 +110,69 @@ function commonField(fields) {
     if (first.type === "list" &&
         fields.some((field) => field?.type !== "list" ||
             field.item !== first.item ||
+            field.targetKind !== first.targetKind ||
             field.target !== first.target))
         return;
     return first;
 }
-export function resolveField(document, instrument, path, input = []) {
-    return resolvePath(document, instrument, path, input, new Map());
+export function resolveField(document, instrument, path, input = [], action) {
+    return resolvePath(document, instrument, path, input, new Map(), action);
+}
+/** A subject expression names a requirement; objectField names its stored metadata. */
+export function resolveSubjectRequirement(instrument, name, action) {
+    const requirements = action
+        ? "requirements" in action
+            ? action.requirements
+            : action.subject?.requirements
+        : Object.values(instrument.actions).flatMap((item) => item.subject?.requirements ?? []);
+    return requirements?.find((requirement) => requirement.field.name === name);
+}
+function resolveReferencePath(document, field, suffix, cache) {
+    return commonField(targetIds(field.target).map((id) => {
+        const key = `${field.targetKind}:${id}:${suffix}`;
+        if (!cache.has(key)) {
+            const object = field.targetKind === "object" &&
+                document.objects.find((item) => item.id === id);
+            const instrument = field.targetKind === "instrument" &&
+                document.instruments.find((item) => item.id === id);
+            cache.set(key, object
+                ? resolveObjectPath(document, object, suffix, cache)
+                : instrument
+                    ? resolvePath(document, instrument, `self.${suffix}`, [], cache)
+                    : undefined);
+        }
+        return cache.get(key);
+    }));
+}
+function resolveObjectPath(document, object, path, cache) {
+    const parts = path.split(".");
+    const key = parts.shift();
+    if (!key)
+        return;
+    const field = object.fields.find((f) => f.name === key);
+    if (!field)
+        return;
+    if (parts.length === 0)
+        return field;
+    if (field.type !== "ref")
+        return;
+    return resolveReferencePath(document, field, parts.join("."), cache);
 }
-function resolvePath(document, instrument, path, input, cache) {
+function resolvePath(document, instrument, path, input, cache, action) {
     const parts = path.split(".");
     const root = parts.shift();
     const key = parts.shift();
     if (!key)
         return root === "self"
-            ? { name: "id", type: "ref", target: instrument.id }
+            ? {
+                name: "id",
+                type: "ref",
+                targetKind: "instrument",
+                target: instrument.id,
+            }
             : undefined;
     if (root === "party") {
-        if (!document.parties[key])
+        if (!moneyParty(document, instrument, key))
             return;
         if (parts.length === 0)
             return { name: key, type: "account", owner: key, book: "cash" };
@@ -94,14 +180,47 @@ function resolvePath(document, instrument, path, input, cache) {
             return { name: parts[0], type: "money" };
         return;
     }
+    if (root === "self" && key === "subject" && instrument.subject) {
+        if (parts.length === 0)
+            return {
+                name: "subject",
+                type: "ref",
+                targetKind: "object",
+                target: instrument.subject,
+            };
+        const target = document.objects.find((o) => o.id === instrument.subject);
+        if (!target)
+            return;
+        const suffix = parts.join(".");
+        const cacheKey = `obj:${instrument.subject}:${suffix}`;
+        if (!cache.has(cacheKey))
+            cache.set(cacheKey, resolveObjectPath(document, target, suffix, cache));
+        return cache.get(cacheKey);
+    }
     if (root === "self" && parts.length === 0) {
         if (key === "id")
-            return { name: key, type: "ref", target: instrument.id };
+            return {
+                name: key,
+                type: "ref",
+                targetKind: "instrument",
+                target: instrument.id,
+            };
         if (key === "now" || key === "createdAt")
             return { name: key, type: "date" };
+        if (key === "productRevision")
+            return { name: key, type: "text" };
         if (key === "status")
             return { name: key, type: "enum", values: instrument.lifecycle.states };
     }
+    if (root === "subject") {
+        const requirement = resolveSubjectRequirement(instrument, key, action);
+        if (!requirement || !instrument.subject)
+            return;
+        const object = document.objects.find((item) => item.id === instrument.subject);
+        if (!object)
+            return;
+        return resolveObjectPath(document, object, [requirement.objectField ?? requirement.field.name, ...parts].join("."), cache);
+    }
     const scope = instrument;
     let field = (root === "self" ? instrument.fields : root === "input" ? input : []).find((f) => f.name === key);
     for (const [index, part] of parts.entries()) {
@@ -120,16 +239,7 @@ function resolvePath(document, instrument, path, input, cache) {
             };
         if (field?.type !== "ref")
             return;
-        return commonField(targetIds(field.target).map((id) => {
-            const target = document.instruments.find((instrument) => instrument.id === id);
-            if (!target)
-                return;
-            const suffix = "self." + parts.slice(index).join(".");
-            const key = `${id}:${suffix}`;
-            if (!cache.has(key))
-                cache.set(key, resolvePath(document, target, suffix, [], cache));
-            return cache.get(key);
-        }));
+        return resolveReferencePath(document, field, parts.slice(index).join("."), cache);
     }
     return field;
 }
@@ -161,21 +271,185 @@ export function validateUdl(value) {
             seen.add(v);
         }
     };
+    if (document.objects.length === 0 && document.instruments.length === 0)
+        add("$", "document requires at least one object or instrument", "UDL2002");
+    duplicate(document.objects.map((o) => o.id), "$.objects");
     duplicate(document.instruments.map((i) => i.id), "$.instruments");
+    for (const name of subjectPartyRoles)
+        if (document.parties[name])
+            add(`$.parties.${name}`, `${name} is a reserved subject role`, "party_name_reserved");
+    const byObjectId = new Map(document.objects.map((o) => [o.id, o]));
     const byId = new Map(document.instruments.map((i) => [i.id, i]));
+    const checkFields = (fields, where, isObject = false, instrument) => {
+        duplicate(fields.map((f) => f.name), where);
+        for (const f of fields) {
+            if (isObject) {
+                if (reservedObjectNamesSet.has(f.name))
+                    add(where, `${f.name} is a reserved object name`);
+            }
+            else {
+                if (f.type === "account" && f.contra && f.book !== "claim")
+                    add(where, "contra accounts require the claim book");
+                if (["id", "status", "createdAt", "now", "productRevision"].includes(f.name))
+                    add(where, `${f.name} is a sealed instance field`);
+                if (f.type === "account" &&
+                    f.owner !== "self" &&
+                    !moneyParty(document, instrument, f.owner))
+                    add(where, `${f.name} needs an eligible money party as owner`, hasParty(document, instrument, f.owner)
+                        ? "party_kind_mismatch"
+                        : "subject_party_unbound");
+            }
+            if (f.type === "text") {
+                if ((f.minLength ?? 1) > (f.maxLength ?? 2048))
+                    add(where, "text minimum exceeds maximum");
+                if (f.pattern) {
+                    try {
+                        new RegExp(f.pattern);
+                    }
+                    catch {
+                        add(where, "invalid text character class");
+                    }
+                }
+            }
+            if (f.type === "ref") {
+                duplicate(targetIds(f.target), where);
+                for (const id of targetIds(f.target)) {
+                    const exists = f.targetKind === "object" ? byObjectId.has(id) : byId.has(id);
+                    if (!exists)
+                        add(where, `unknown reference target ${id}`, "UDL5001");
+                }
+                if (f.targetFamily) {
+                    if (f.targetKind !== "instrument") {
+                        add(where, "targetFamily requires an instrument reference target", "UDL5001");
+                    }
+                    else {
+                        for (const id of targetIds(f.target)) {
+                            const targetInst = byId.get(id);
+                            if (targetInst &&
+                                (!targetInst.family ||
+                                    targetInst.family.module !== f.targetFamily.module ||
+                                    targetInst.family.exportPath !== f.targetFamily.exportPath ||
+                                    targetInst.family.revision !== f.targetFamily.revision)) {
+                                add(where, `targetFamily does not match target instrument ${id} family`, "UDL5001");
+                            }
+                        }
+                    }
+                }
+            }
+            if (f.type === "enum") {
+                duplicate(f.values, where);
+                if (f.value !== undefined && !f.values.includes(f.value))
+                    add(where, `${f.name} constant is outside its enum`);
+            }
+            if (f.type === "list") {
+                const validRefList = f.item === "ref" &&
+                    f.targetKind &&
+                    (f.targetKind === "object"
+                        ? byObjectId.has(f.target ?? "")
+                        : byId.has(f.target ?? ""));
+                const nonRefTarget = f.item !== "ref" &&
+                    (f.targetKind !== undefined || f.target !== undefined);
+                if (!validRefList && (f.item === "ref" || nonRefTarget))
+                    add(where, `${f.name} needs a target exactly when its items are references`);
+                if (f.targetFamily) {
+                    if (f.item !== "ref" || f.targetKind !== "instrument") {
+                        add(where, "targetFamily requires an instrument reference target", "UDL5001");
+                    }
+                    else if (f.target) {
+                        const targetInst = byId.get(f.target);
+                        if (targetInst &&
+                            (!targetInst.family ||
+                                targetInst.family.module !== f.targetFamily.module ||
+                                targetInst.family.exportPath !== f.targetFamily.exportPath ||
+                                targetInst.family.revision !== f.targetFamily.revision)) {
+                            add(where, `targetFamily does not match target instrument ${f.target} family`, "UDL5001");
+                        }
+                    }
+                }
+            }
+            if ((f.type === "integer" || f.type === "money") &&
+                f.minimum !== undefined &&
+                f.maximum !== undefined &&
+                BigInt(f.minimum) > BigInt(f.maximum))
+                add(where, `${f.name} minimum exceeds maximum`);
+            if ((f.type === "integer" || f.type === "money") &&
+                f.value !== undefined &&
+                ((f.minimum !== undefined && BigInt(f.value) < BigInt(f.minimum)) ||
+                    (f.maximum !== undefined && BigInt(f.value) > BigInt(f.maximum))))
+                add(where, `${f.name} constant violates its bounds`);
+        }
+    };
+    for (const [index, obj] of document.objects.entries()) {
+        const base = `$.objects[${index}]`;
+        if (reservedObjectNamesSet.has(obj.id))
+            add(base, `${obj.id} is a reserved object name`);
+        duplicate(obj.attachments.map((attachment) => attachment.name), `${base}.attachments`);
+        duplicate(obj.attachments.map((attachment) => attachment.instrument), `${base}.attachments`);
+        for (const [attachmentIndex, attachment] of obj.attachments.entries()) {
+            for (const [parameter, binding] of Object.entries(attachment.parties))
+                if ("party" in binding && !document.parties[binding.party])
+                    add(`${base}.attachments[${attachmentIndex}].parties.${parameter}`, `unknown declared party ${binding.party}`, "subject_party_unbound");
+            if (byId.get(attachment.instrument)?.subject !== obj.id)
+                add(`${base}.attachments`, `${attachment.instrument} must attach to ${obj.id}`);
+        }
+        duplicate(obj.authoredFields, `${base}.authoredFields`);
+        duplicate(obj.columns, `${base}.columns`);
+        checkFields(obj.fields, `${base}.fields`, true);
+        for (let i = 0; i < obj.authoredFields.length; i++) {
+            const af = obj.authoredFields[i];
+            if (reservedObjectNamesSet.has(af))
+                add(`${base}.authoredFields`, `${af} is a reserved object name`);
+            if (!obj.fields.some((f) => f.name === af))
+                add(`${base}.authoredFields`, `authored field ${af} is not in declared fields`, "subject_field_unknown");
+            if (obj.fields[i]?.name !== af)
+                add(base, `authored field ${af} must precede attached requirements in fields`);
+        }
+        for (const col of obj.columns) {
+            if (reservedObjectNamesSet.has(col))
+                add(`${base}.columns`, `${col} is a reserved object name`);
+            if (!obj.fields.some((f) => f.name === col))
+                add(`${base}.columns`, `column ${col} is not a declared field`, "subject_field_unknown");
+        }
+        const pubActions = document.instruments
+            .filter((i) => i.subject === obj.id)
+            .flatMap((i) => Object.values(i.actions).flatMap((a) => a.publicAction ? [a.publicAction] : []));
+        duplicate(pubActions, `$.objects.${obj.id}.publicActions`);
+    }
+    const reportIds = new Set();
+    for (const [index, instrument] of document.instruments.entries()) {
+        for (const report of instrument.reports ?? []) {
+            const path = `$.instruments[${index}].reports`;
+            if (reportIds.has(report.identity.id))
+                add(path, `duplicate report ${report.identity.id}`);
+            reportIds.add(report.identity.id);
+            try {
+                validateReportDefinition(report, document);
+            }
+            catch (error) {
+                add(path, error instanceof Error ? error.message : "Invalid report definition");
+            }
+        }
+    }
     const calls = new Map();
     for (const [index, inst] of document.instruments.entries()) {
         const base = `$.instruments[${index}]`;
-        const field = (p, input = []) => resolveField(document, inst, p, input);
-        const expect = (p, type, where, input = []) => {
-            const found = field(p, input);
+        if (inst.subject && !byObjectId.has(inst.subject))
+            add(base, `unknown subject object ${inst.subject}`);
+        const field = (p, input = [], action) => resolveField(document, inst, p, input, action);
+        const expect = (p, type, where, input = [], action) => {
+            const party = p.startsWith("party.") ? p.split(".")[1] : undefined;
+            if (party && !moneyParty(document, inst, party))
+                add(where, `${party} cannot supply a money account`, hasParty(document, inst, party)
+                    ? "party_kind_mismatch"
+                    : "subject_party_unbound");
+            const found = field(p, input, action);
             if (found?.type !== type)
                 add(where, `${p} must name a ${type} field`, "UDL5001");
             return found;
         };
-        const checkValue = (v, type, where, input = []) => {
+        const checkValue = (v, type, where, input = [], action) => {
             if ("field" in v) {
-                expect(v.field, type, where, input);
+                expect(v.field, type, where, input, action);
                 return;
             }
             const valid = type === "money"
@@ -191,48 +465,7 @@ export function validateUdl(value) {
             if (!valid)
                 add(where, `literal must have type ${type}`);
         };
-        const checkFields = (fields, where) => {
-            duplicate(fields.map((f) => f.name), where);
-            for (const f of fields) {
-                if (f.type === "account" &&
-                    ((f.contra && f.book !== "claim") ||
-                        (f.external && (f.book !== "cash" || f.owner === "self"))))
-                    add(where, "contra accounts require the claim book; external accounts require a cash party owner");
-                if (["id", "status", "createdAt", "now"].includes(f.name))
-                    add(where, `${f.name} is a sealed instance field`);
-                if (f.type === "ref") {
-                    duplicate(targetIds(f.target), where);
-                    for (const id of targetIds(f.target))
-                        if (!byId.has(id))
-                            add(where, `unknown reference target ${id}`, "UDL5001");
-                }
-                if (f.type === "account" &&
-                    f.owner !== "self" &&
-                    !document.parties[f.owner])
-                    add(where, `${f.name} needs self or a declared party as owner`);
-                if (f.type === "enum") {
-                    duplicate(f.values, where);
-                    if (f.value !== undefined && !f.values.includes(f.value))
-                        add(where, `${f.name} constant is outside its enum`);
-                }
-                if (f.type === "list" &&
-                    (f.item === "ref"
-                        ? !f.target || !byId.has(f.target)
-                        : f.target !== undefined))
-                    add(where, `${f.name} needs a target exactly when its items are references`);
-                if ((f.type === "integer" || f.type === "money") &&
-                    f.minimum !== undefined &&
-                    f.maximum !== undefined &&
-                    BigInt(f.minimum) > BigInt(f.maximum))
-                    add(where, `${f.name} minimum exceeds maximum`);
-                if ((f.type === "integer" || f.type === "money") &&
-                    f.value !== undefined &&
-                    ((f.minimum !== undefined && BigInt(f.value) < BigInt(f.minimum)) ||
-                        (f.maximum !== undefined && BigInt(f.value) > BigInt(f.maximum))))
-                    add(where, `${f.name} constant violates its bounds`);
-            }
-        };
-        checkFields(inst.fields, `${base}.fields`);
+        checkFields(inst.fields, `${base}.fields`, false, inst);
         const captures = new Set(Object.values(inst.actions).flatMap((a) => [
             ...a.moves.flatMap((m) => "capture" in m && m.capture ? [m.capture] : []),
         ]));
@@ -255,9 +488,18 @@ export function validateUdl(value) {
             const compatible = (a, b) => a &&
                 b &&
                 a.type === b.type &&
-                (a.type !== "ref" || (b.type === "ref" && overlap(a.target, b.target)));
+                (a.type !== "ref" ||
+                    (b.type === "ref" &&
+                        a.targetKind === b.targetKind &&
+                        overlap(a.target, b.target)));
             const anchor = field(selection.anchor, input);
             for (const target of targets) {
+                if (selection.family &&
+                    (!target.family ||
+                        target.family.module !== selection.family.module ||
+                        target.family.exportPath !== selection.family.exportPath ||
+                        target.family.revision !== selection.family.revision))
+                    add(where, `selection family does not match target instrument ${target.id} family`, "UDL5001");
                 if (selection.window &&
                     target.fields.find((f) => f.name === selection.window.field)
                         ?.type !== "date")
@@ -295,14 +537,14 @@ export function validateUdl(value) {
                 }),
             };
         };
-        const checkCalculations = (calculations, where, input = []) => {
+        const checkCalculations = (calculations, where, input = [], act) => {
             duplicate(calculations.map((c) => c.target), where);
             const dependencies = new Map();
             for (const c of calculations) {
                 const arithmetic = ["sum", "subtract", "minimum", "divide"].includes(c.op);
                 const resultType = c.op === "at"
                     ? (() => {
-                        const list = field(c.list, input);
+                        const list = field(c.list, input, act);
                         return list?.type === "list" ? list.item : "text";
                     })()
                     : (c.op === "aggregate" && c.measure === "count") ||
@@ -317,11 +559,11 @@ export function validateUdl(value) {
                 const operands = [];
                 const money = (v) => {
                     operands.push(v);
-                    checkValue(v, arithmetic ? resultType : "money", where, input);
+                    checkValue(v, arithmetic ? resultType : "money", where, input, act);
                 };
                 if (c.op === "at") {
-                    expect(c.list, "list", where, input);
-                    checkValue(c.position, "integer", where, input);
+                    expect(c.list, "list", where, input, act);
+                    checkValue(c.position, "integer", where, input, act);
                     if ("literal" in c.position && Number(c.position.literal) < 1)
                         add(where, "list positions start at one");
                     operands.push({ field: c.list }, c.position);
@@ -337,15 +579,15 @@ export function validateUdl(value) {
                 if (c.op === "ratio") {
                     money(c.amount);
                     const type = "field" in c.numerator
-                        ? field(c.numerator.field, input)?.type
+                        ? field(c.numerator.field, input, act)?.type
                         : typeof c.numerator.literal === "number"
                             ? "integer"
                             : "money";
                     if (type !== "integer" && type !== "money" && type !== "percent")
                         add(where, "ratio weights must share a numeric type");
                     else {
-                        checkValue(c.numerator, type, where, input);
-                        checkValue(c.denominator, type, where, input);
+                        checkValue(c.numerator, type, where, input, act);
+                        checkValue(c.denominator, type, where, input, act);
                     }
                     if ("literal" in c.denominator &&
                         BigInt(c.denominator.literal.toString()) <= 0n)
@@ -360,13 +602,13 @@ export function validateUdl(value) {
                 }
                 if (c.op === "rate") {
                     money(c.base);
-                    checkValue(c.bps, "percent", where, input);
+                    checkValue(c.bps, "percent", where, input, act);
                     operands.push(c.bps);
                 }
                 if (c.op === "multiply" || c.op === "divide") {
                     money(c.amount);
                     const count = c.op === "multiply" ? c.units : c.divisor;
-                    checkValue(count, "integer", where, input);
+                    checkValue(count, "integer", where, input, act);
                     operands.push(count);
                     if ("literal" in count &&
                         (c.op === "divide"
@@ -375,8 +617,8 @@ export function validateUdl(value) {
                         add(where, "money multiplier must be nonnegative and divisor must be positive");
                 }
                 if (c.op === "shift") {
-                    checkValue(c.date, "date", where, input);
-                    checkValue(c.milliseconds, "duration", where, input);
+                    checkValue(c.date, "date", where, input, act);
+                    checkValue(c.milliseconds, "duration", where, input, act);
                     operands.push(c.date, c.milliseconds);
                 }
                 dependencies.set(c.target, operands.flatMap((v) => "field" in v && v.field.startsWith("self.")
@@ -403,6 +645,8 @@ export function validateUdl(value) {
         };
         checkCalculations(inst.calculate, `${base}.calculate`);
         const states = new Set(inst.lifecycle.states);
+        if (states.has("preserve"))
+            add(base, "preserve is a reserved transition destination", "UDL3001");
         duplicate(inst.lifecycle.states, `${base}.lifecycle.states`);
         if (!states.has(inst.lifecycle.initial) || !inst.actions.create)
             add(base, "declare create and a declared initial state", "UDL3001");
@@ -414,22 +658,24 @@ export function validateUdl(value) {
         for (const [action, edge] of Object.entries(inst.lifecycle.transitions)) {
             if (!inst.actions[action] ||
                 action === "create" ||
-                !states.has(edge.to) ||
+                (edge.to !== "preserve" && !states.has(edge.to)) ||
                 edge.from.some((s) => !states.has(s)))
                 add(base, `invalid transition ${action}`, "UDL3001");
         }
         for (let pass = 0; pass < states.size; pass++)
             for (const edge of Object.values(inst.lifecycle.transitions))
-                if (edge.from.some((s) => reachable.has(s)))
+                if (edge.to !== "preserve" && edge.from.some((s) => reachable.has(s)))
                     reachable.add(edge.to);
         for (const state of states)
             if (!reachable.has(state))
                 add(base, `unreachable state ${state}`, "UDL3001");
-        const checkRequirements = (requirements, where, input = []) => {
+        const checkRequirements = (requirements, where, input = [], act) => {
             for (const req of requirements ?? []) {
                 if (req.kind === "compare") {
-                    const left = "field" in req.left ? field(req.left.field, input) : undefined;
-                    const right = "field" in req.right ? field(req.right.field, input) : undefined;
+                    const left = "field" in req.left ? field(req.left.field, input, act) : undefined;
+                    const right = "field" in req.right
+                        ? field(req.right.field, input, act)
+                        : undefined;
                     if (("field" in req.left && !left) ||
                         ("field" in req.right && !right))
                         add(where, "comparison refers to an undeclared field");
@@ -438,48 +684,62 @@ export function validateUdl(value) {
                         (left.type !== right.type ||
                             (left.type === "ref" &&
                                 right.type === "ref" &&
-                                !overlap(left.target, right.target))))
+                                (left.targetKind !== right.targetKind ||
+                                    !overlap(left.target, right.target)))))
                         add(where, "comparison operands have different types");
                     if (left && "literal" in req.right) {
-                        checkValue(req.right, left.type, where, input);
+                        checkValue(req.right, left.type, where, input, act);
                         if (left.type === "enum" &&
                             !left.values.includes(String(req.right.literal)))
                             add(where, "comparison names an undeclared enum value");
                     }
                     if (right && "literal" in req.left) {
-                        checkValue(req.left, right.type, where, input);
+                        checkValue(req.left, right.type, where, input, act);
                         if (right.type === "enum" &&
                             !right.values.includes(String(req.left.literal)))
                             add(where, "comparison names an undeclared enum value");
                     }
                 }
                 else if (req.kind === "state") {
-                    const target = expect(req.reference, "ref", where, input);
+                    const target = expect(req.reference, "ref", where, input, act);
                     if (target?.type === "ref" &&
+                        target.targetKind === "instrument" &&
                         req.states.some((s) => targetIds(target.target).some((id) => !byId.get(id)?.lifecycle.states.includes(s))))
                         add(where, "reference gate names an undeclared state");
                 }
                 else if (req.kind === "unique") {
                     for (const p of req.fields)
-                        if (!field(p, input))
+                        if (!field(p, input, act))
                             add(where, `unknown identity field ${p}`);
                 }
                 else if (req.kind === "approval") {
-                    const target = expect(req.target, "ref", where, input);
-                    if (!document.parties[req.party])
-                        add(where, `unknown approving party ${req.party}`);
+                    const request = expect(req.protectedRequest, "ref", where, input, act);
+                    if (request?.type === "ref" && request.targetKind !== "instrument")
+                        add(where, "protectedRequest must reference an instrument", "UDL5001");
+                    const target = expect(req.target, "ref", where, input, act);
+                    if (!approvalParty(document, req.party))
+                        add(where, `approval requires staff with a role: ${req.party}`, hasParty(document, inst, req.party)
+                            ? "party_kind_mismatch"
+                            : "subject_party_unbound");
                     if (req.action &&
                         target?.type === "ref" &&
+                        target.targetKind === "instrument" &&
                         targetIds(target.target).some((id) => !byId.get(id)?.actions[req.action]))
                         add(where, `unknown approved action ${req.action}`);
                 }
                 else if (req.kind === "evidence") {
-                    const subject = field(req.subject, input);
-                    if (!subject || !["account", "text"].includes(subject.type))
+                    if (req.instruction) {
+                        expect(req.instruction, "text", where, input, act);
+                        if (!["confirmed", "rejected"].includes(req.result))
+                            add(where, "instruction evidence requires a terminal outcome");
+                    }
+                    const subject = field(req.subject, input, act);
+                    if (!subject ||
+                        !["account", "text", ...(req.instruction ? ["ref"] : [])].includes(subject.type))
                         add(where, "evidence subject must be an account or text subject id");
                 }
                 else if (req.kind === "hours") {
-                    expect(req.at, "date", where, input);
+                    expect(req.at, "date", where, input, act);
                     try {
                         new Intl.DateTimeFormat("en", { timeZone: req.timezone });
                     }
@@ -498,7 +758,7 @@ export function validateUdl(value) {
                                 resolveField(document, selected, `self.${measure.sum}`)
                                     ?.type) !== "money")
                             add(where, "aggregate sum requires a money field");
-                        checkValue(req.value, req.measure === "count" ? "integer" : "money", where, input);
+                        checkValue(req.value, req.measure === "count" ? "integer" : "money", where, input, act);
                     }
                 }
             }
@@ -508,7 +768,56 @@ export function validateUdl(value) {
             const where = `${base}.actions.${actionName}`;
             if (actionName !== "create" && !inst.lifecycle.transitions[actionName])
                 add(where, "action needs a lifecycle transition", "UDL3001");
-            checkFields(action.input, `${where}.input`);
+            if (action.subject) {
+                const subBase = `${where}.subject`;
+                checkFields(action.subject.requirements.map((r) => ({
+                    ...r.field,
+                    name: r.objectField ?? r.field.name,
+                })), `${subBase}.requirements`, true);
+                for (const req of action.subject.requirements) {
+                    if (req.field.optional)
+                        add(`${subBase}.requirements`, `subject requirement ${req.field.name} cannot be optional`, "UDL2002");
+                    const name = req.objectField ?? req.field.name;
+                    if (reservedObjectNamesSet.has(name))
+                        add(subBase, `${name} is a reserved object name`);
+                    if (inst.subject) {
+                        const field = byObjectId
+                            .get(inst.subject)
+                            ?.fields.find((field) => field.name === name);
+                        if (!field || !sameObjectField(field, req.field))
+                            add(subBase, `object field ${name} must match requirement ${req.field.name}`, field ? "subject_field_conflict" : "subject_field_unknown");
+                    }
+                }
+                duplicate(action.subject.adapters.map((a) => a.binding), `${subBase}.adapters`);
+                for (const adapter of action.subject.adapters) {
+                    if (adapter.snapshot) {
+                        checkFields(adapter.snapshot.requirements, `${subBase}.adapters.${adapter.binding}.requirements`, true);
+                        for (const reqField of adapter.snapshot.requirements) {
+                            const objectName = adapter.renames?.[reqField.name] ?? reqField.name;
+                            const requirement = action.subject.requirements.find((item) => (item.objectField ?? item.field.name) === objectName &&
+                                sameObjectField(item.field, reqField));
+                            if (!requirement)
+                                add(subBase, `adapter ${adapter.binding} requirement ${reqField.name} is absent from the action`);
+                            if (reqField.optional)
+                                add(`${subBase}.adapters.${adapter.binding}`, `adapter requirement ${reqField.name} cannot be optional`, "UDL2002");
+                        }
+                    }
+                }
+            }
+            checkFields(action.input, `${where}.input`, false, inst);
+            if (action.reminder) {
+                expect(action.reminder.installment, "ref", where, action.input, action);
+                expect(action.reminder.recipient, "account", where, action.input, action);
+                expect(action.reminder.dueAt, "date", where, action.input, action);
+                if (action.reminder.startHour >= action.reminder.endHour)
+                    add(where, "reminder sending window is empty");
+                try {
+                    new Intl.DateTimeFormat("en", { timeZone: action.reminder.timezone });
+                }
+                catch {
+                    add(where, "reminder requires an IANA timezone");
+                }
+            }
             for (const input of action.input) {
                 if (input.type === "account")
                     add(where, "account bindings cannot be caller inputs");
@@ -524,26 +833,41 @@ export function validateUdl(value) {
                 if (captures.has(input.name))
                     add(where, `${input.name} is an executor-owned receipt and cannot be an input`);
             }
-            checkCalculations(action.calculate ?? [], `${where}.calculate`, action.input);
-            checkRequirements(action.requires, `${where}.requires`, action.input);
+            checkCalculations(action.calculate ?? [], `${where}.calculate`, action.input, action);
+            checkRequirements(action.requires, `${where}.requires`, action.input, action);
             if (typeof action.actor === "object" &&
                 "party" in action.actor &&
-                !document.parties[action.actor.party])
+                !hasParty(document, inst, action.actor.party))
                 add(where, "actor names an undeclared party");
             if (typeof action.actor === "object" &&
                 "parent" in action.actor &&
-                !byId.has(action.actor.parent))
+                targetIds(action.actor.parent).some((id) => !byId.has(id)))
                 add(where, "actor names an undeclared parent");
             if (action.actor === "clock" && !action.due)
                 add(where, "clock action needs a due instant");
             for (const clock of [action.due, action.deadline])
-                if (clock)
-                    expect(clock.at, "date", where, action.input);
+                if (clock) {
+                    expect(clock.at, "date", where, action.input, action);
+                    if (clock.localDay) {
+                        try {
+                            new Intl.DateTimeFormat("en", {
+                                timeZone: clock.localDay.timezone,
+                            }).format(0);
+                        }
+                        catch {
+                            add(where, "clock timezone must be an IANA timezone");
+                        }
+                    }
+                }
             for (const move of action.moves) {
+                if (move.operation === "internal_transfer.reserve" &&
+                    move.boundary &&
+                    !action.subject?.adapters.some((binding) => binding.binding === move.boundary.adapter && binding.snapshot))
+                    add(where, "boundary reservation requires a retained adapter binding");
                 if ("amount" in move) {
-                    checkValue(move.amount, "money", where, action.input);
-                    const from = expect(move.from, "account", where, action.input);
-                    const to = expect(move.to, "account", where, action.input);
+                    checkValue(move.amount, "money", where, action.input, action);
+                    const from = expect(move.from, "account", where, action.input, action);
+                    const to = expect(move.to, "account", where, action.input, action);
                     if (from?.type === "account" &&
                         to?.type === "account" &&
                         from.book !== to.book)
@@ -558,7 +882,7 @@ export function validateUdl(value) {
                         add(where, "a transfer needs distinct accounts", "UDL4001");
                 }
                 else
-                    expect(move.transfer, "text", where, action.input);
+                    expect(move.transfer, "text", where, action.input, action);
             }
             duplicate(action.moves.flatMap((m) => "capture" in m && m.capture ? [m.capture] : []), `${where}.captures`);
             duplicate(action.moves.map((m) => m.key), `${where}.moves`);
@@ -572,9 +896,9 @@ export function validateUdl(value) {
                     inst.calculate.some((c) => c.target === key))
                     add(where, `cannot write immutable field ${key}`);
                 else
-                    checkValue(v, target.type, where, action.input);
+                    checkValue(v, target.type, where, action.input, action);
             }
-            const checkArguments = (targetId, actionName, values) => {
+            const checkArguments = (targetId, actionName, values, binding) => {
                 const target = targetId
                     ? byId.get(targetId)?.actions[actionName]
                     : undefined;
@@ -591,37 +915,64 @@ export function validateUdl(value) {
                         add(where, `unknown target input ${name}`);
                         continue;
                     }
-                    checkValue(value, declared.type, where, action.input);
+                    if (binding && "field" in value && value.field === binding) {
+                        if (declared.type !== "integer")
+                            add(where, "range binding requires an integer target input");
+                        continue;
+                    }
+                    checkValue(value, declared.type, where, action.input, action);
                     if (declared.type === "ref" && "field" in value) {
-                        const supplied = field(value.field, action.input);
+                        const supplied = field(value.field, action.input, action);
                         if (supplied?.type !== "ref" ||
+                            supplied.targetKind !== declared.targetKind ||
                             !targetIds(supplied.target).every((id) => targetIds(declared.target).includes(id)))
                             add(where, `target input ${name} has the wrong reference type`);
                     }
                 }
             };
             if (action.approval) {
-                const reference = expect(action.approval.target, "ref", where, action.input);
+                const request = expect(action.approval.protectedRequest, "ref", where, action.input, action);
+                if (request?.type === "ref" && request.targetKind !== "instrument")
+                    add(where, "protectedRequest must reference an instrument", "UDL5001");
+                const reference = expect(action.approval.target, "ref", where, action.input, action);
                 if (reference?.type === "ref" &&
+                    reference.targetKind === "instrument" &&
                     targetIds(reference.target).some((id) => !byId.get(id)?.actions[action.approval.action]))
                     add(where, "approval target action does not exist");
-                if (reference?.type === "ref")
+                if (reference?.type === "ref" && reference.targetKind === "instrument")
                     for (const id of targetIds(reference.target))
                         checkArguments(id, action.approval.action, action.approval.input);
-                expect(action.approval.expires, "date", where, action.input);
-                if (!document.parties[action.approval.party])
-                    add(where, "approval needs a declared party");
+                expect(action.approval.expires, "date", where, action.input, action);
+                if (!approvalParty(document, action.approval.party))
+                    add(where, "approval requires staff with a role", hasParty(document, inst, action.approval.party)
+                        ? "party_kind_mismatch"
+                        : "subject_party_unbound");
             }
             const targets = [];
             for (const call of action.invoke ?? []) {
+                if (call.guard)
+                    checkRequirements([call.guard], where, action.input, action);
+                const range = "instrument" in call ? call.range : undefined;
+                if (range) {
+                    checkValue(range.count, "integer", where, action.input, action);
+                    if (["self", "input", "party", "subject"].includes(range.bind))
+                        add(where, "range binding cannot shadow a reserved scope");
+                    if ("literal" in range.count &&
+                        (typeof range.count.literal !== "number" ||
+                            range.count.literal < 1 ||
+                            range.count.literal > range.maximum))
+                        add(where, "range count must be between one and its maximum");
+                }
                 if ("selection" in call)
                     checkSelection(call.selection, where, action.input);
-                const target = "reference" in call ? field(call.reference, action.input) : undefined;
+                const target = "reference" in call
+                    ? field(call.reference, action.input, action)
+                    : undefined;
                 const selected = "instrument" in call
                     ? call.instrument
                     : "selection" in call
                         ? call.selection.instrument
-                        : target?.type === "ref"
+                        : target?.type === "ref" && target.targetKind === "instrument"
                             ? target.target
                             : undefined;
                 const ids = Array.isArray(selected)
@@ -632,15 +983,32 @@ export function validateUdl(value) {
                 if (!ids.length)
                     add(where, "invocation needs a declared target");
                 for (const targetId of ids) {
-                    checkArguments(targetId, call.action, call.input);
+                    checkArguments(targetId, call.action, call.input, range?.bind);
                     if (call.action === "create" && !("instrument" in call))
                         add(where, "invocation references an existing instance and cannot create it again");
-                    if (!byId.get(targetId)?.actions[call.action])
+                    const targetInst = byId.get(targetId);
+                    if (!targetInst?.actions[call.action])
                         add(where, "invocation target must name a declared action");
+                    else if (!call.guard) {
+                        const targetAction = targetInst.actions[call.action];
+                        if (inst.subject &&
+                            targetInst.subject &&
+                            inst.subject === targetInst.subject) {
+                            const callerRequirements = action.subject?.requirements ?? [];
+                            for (const targetReq of targetAction.subject?.requirements ??
+                                []) {
+                                const targetObjFieldName = targetReq.objectField ?? targetReq.field.name;
+                                const satisfied = callerRequirements.some((cr) => (cr.objectField ?? cr.field.name) === targetObjFieldName);
+                                if (!satisfied) {
+                                    add(`${where}.invoke`, `mandatory invocation of ${targetId}.${call.action} requires subject field ${targetReq.field.name}`, "UDL2002");
+                                }
+                            }
+                        }
+                    }
                 }
                 targets.push({
                     targets: ids.map((id) => `${id}.${call.action}`),
-                    count: "selection" in call ? call.selection.limit : 1,
+                    count: "selection" in call ? call.selection.limit : (range?.maximum ?? 1),
                 });
             }
             calls.set(`${inst.id}.${actionName}`, targets);
@@ -653,7 +1021,7 @@ export function validateUdl(value) {
     const visit = (key) => {
         if (active.has(key)) {
             add("$.instruments", `invocation cycle at ${key}`, "UDL2010");
-            return 4097;
+            return MAX_ACTION_EXPANSION + 1;
         }
         const known = depths.get(key);
         if (known !== undefined)
@@ -663,8 +1031,11 @@ export function validateUdl(value) {
             (calls.get(key) ?? []).reduce((n, edge) => n + edge.count * Math.max(0, ...edge.targets.map(visit)), 0);
         active.delete(key);
         depths.set(key, size);
-        if (size > 4096)
-            add("$.instruments", `invocation ${key} exceeds 4096 actions`, "UDL2010");
+        const [id, action] = key.split(".");
+        const limit = document.instruments.find((item) => item.id === id)?.actions[action]
+            ?.expansionLimit ?? MAX_ACTION_EXPANSION;
+        if (size > limit)
+            add("$.instruments", `invocation ${key} exceeds ${limit} actions`, "UDL2010");
         return size;
     };
     for (const key of calls.keys())