@hyperscale0/hsx 3.2.0 → 4.0.0

package/dist/src/compile.js

@@ -1,5 +1,6 @@
+import { hash as sha256 } from "fast-sha256";
 import { buildUdlCostManifest } from "./cost.js";
-import { validateUdl, } from "@hyperscale0/udl";
+import { validateUdl, resolveField, sameObjectField, subjectPartyRoles, RESERVED_OBJECT_NAMES, udlObjectFieldSchema, } from "@hyperscale0/udl";
 import { tunableBounds } from "./tunables.js";
 import { parseProgram } from "./parse.js";
 import { lineColAt, } from "./ast.js";
@@ -12,7 +13,125 @@ class CompileFailure extends Error {
     }
 }
 function fail(expr, message, fix) {
-    throw new CompileFailure({ code: "HSX1001", message, fix, span: expr.span });
+    return failWithCode(expr, "HSX1001", message, fix);
+}
+function failWithCode(expr, code, message, fix) {
+    throw new CompileFailure({
+        code,
+        message,
+        fix,
+        span: expr.span,
+        ...(expr.source ? { source: expr.source } : {}),
+    });
+}
+function lowerFieldShape(row, resolveExpr = (e) => e) {
+    let rawValue = row.value.kind === "default" ? row.value.type : row.value;
+    let isSensitive = false;
+    if (rawValue.kind === "call" && rawValue.name === "sensitive") {
+        isSensitive = true;
+        rawValue = rawValue.args[0];
+    }
+    const t = rawValue;
+    if (t.kind === "block") {
+        const b = entries(t);
+        if (b.has("family") || b.has("target") || b.has("instrument")) {
+            const tgt = b.get("instrument") ?? b.get("target");
+            let target;
+            if (tgt) {
+                const resolved = resolveExpr(tgt);
+                if (resolved.kind === "list") {
+                    const items = resolved.items.map((i) => text(resolveExpr(i)));
+                    target = items.length === 1 ? items[0] : items;
+                }
+                else {
+                    target = text(resolved);
+                }
+            }
+            return {
+                name: row.key,
+                type: "ref",
+                targetKind: "instrument",
+                ...(target !== undefined ? { target } : {}),
+                ...(isSensitive ? { sensitive: true } : {}),
+            };
+        }
+    }
+    const type = t.kind === "type" || t.kind === "call" ? t.name : text(t);
+    const f = {
+        name: row.key,
+        type,
+        ...(t.kind === "type" && t.optional ? { optional: true } : {}),
+        ...(isSensitive ? { sensitive: true } : {}),
+    };
+    if (type === "enum" && t.kind === "call") {
+        f.values = t.args.map(text);
+    }
+    if (type === "text" && t.kind === "call") {
+        if (t.args.length < 2 || t.args.length > 3) {
+            fail(t, "bounded text needs length bounds and an optional pattern", "write text(1, 80)");
+        }
+        f.minLength = literal(resolveExpr(t.args[0]));
+        f.maxLength = literal(resolveExpr(t.args[1]));
+        if (t.args[2])
+            f.pattern = literal(resolveExpr(t.args[2]));
+    }
+    if (["integer", "money"].includes(type) && t.kind === "call") {
+        if (t.args.length !== 2) {
+            fail(t, "bounded fields need a minimum and maximum", "write integer(1, 12) or money(0 SAR, 100 SAR)");
+        }
+        f.minimum = literal(resolveExpr(t.args[0]));
+        f.maximum = literal(resolveExpr(t.args[1]));
+    }
+    if (type === "list" && t.kind === "call") {
+        const item = t.args[0];
+        f.item = item.kind === "type" ? item.name : text(item);
+        if (item.kind === "type" && item.name === "ref") {
+            f.target = item.target;
+            f.targetKind = "object";
+        }
+        f.maxItems = t.args[1] ? literal(resolveExpr(t.args[1])) : 366;
+    }
+    if (type === "list" && t.kind === "type") {
+        f.item = t.target;
+        f.maxItems = 366;
+    }
+    if (type === "ref") {
+        const target = t.kind === "type" ? t.target : f.target;
+        if (!target && t.kind !== "block") {
+            fail(row, "reference needs a target", "write ref<object>");
+        }
+        f.targetKind = f.targetKind ?? "object";
+        if (target)
+            f.target = target;
+    }
+    return f;
+}
+function lowerObjectField(row, resolveExpr = (e) => e) {
+    const f = lowerFieldShape(row, resolveExpr);
+    const constant = row.value.kind === "default" ? resolveExpr(row.value.value) : undefined;
+    if (constant && !(constant.kind === "name" && constant.value === "runtime")) {
+        f.value =
+            f.type === "enum" && constant.kind === "name"
+                ? constant.value
+                : literal(constant);
+    }
+    const result = udlObjectFieldSchema.safeParse(f);
+    if (!result.success)
+        fail(row, result.error.message, "use a UDL object field type and its constraints");
+    return result.data;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => (item === undefined ? "null" : canonicalJson(item))).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record)
+        .filter((k) => record[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(record[k])}`).join(",")}}`;
 }
 const emptyBlock = {
     kind: "block",
@@ -28,7 +147,14 @@ function entries(block) {
     for (const row of block.entries) {
         const previous = map.get(row.key);
         if (previous) {
-            if (!["requires", "moves", "invariants", "invoke", "calculate"].includes(row.key))
+            if (![
+                "requires",
+                "moves",
+                "invariants",
+                "invoke",
+                "calculate",
+                "expose",
+            ].includes(row.key))
                 fail(row, `duplicate ${row.key}`, "keep one value for this name");
             const items = (expr) => expr.kind === "list" ? expr.items : [expr];
             map.set(row.key, {
@@ -126,9 +252,10 @@ function literal(expr) {
 }
 export function compile(source, options = {}) {
     const parsed = parseProgram(source);
+    const sources = new Map([["program", source]]);
     const diagnostic = (d, stage) => ({
         ...d,
-        ...lineColAt(source, d.span.start),
+        ...lineColAt(sources.get(d.source ?? "program") ?? source, d.span.start),
         severity: "error",
         stage,
     });
@@ -144,6 +271,9 @@ export function compile(source, options = {}) {
         if (program.currency !== "SAR")
             fail(program, "this release supports SAR", "write currency SAR or omit currency");
         const templates = new Map();
+        const declarationSources = new Map();
+        const declarationExportPaths = new Map();
+        const requirementOrigins = new Map();
         const used = new Set();
         for (const use of program.decls.filter((d) => d.kind === "use")) {
             if (used.has(use.name))
@@ -152,17 +282,38 @@ export function compile(source, options = {}) {
             const content = (options.standardLibrary ?? bundledStandardLibrary).source(use.name);
             if (!content)
                 fail(use, `unknown header ${use.name}`, "choose a published header");
+            sources.set(use.name, content);
             const header = parseProgram(content);
             if (header.diagnostics.length ||
                 !header.program.header ||
                 header.program.name !== use.name)
                 fail(use, `header ${use.name} is malformed`, "repair the header source before compiling");
+            const registerTemplates = (parentDecl, prefix, exportPath) => {
+                templates.set(prefix, parentDecl);
+                declarationSources.set(parentDecl, use.name);
+                declarationExportPaths.set(parentDecl, exportPath);
+                const recs = entries(asBlock(entries(parentDecl.body).get("records")));
+                for (const [recName, recBlock] of recs) {
+                    const recDecl = {
+                        kind: "instrument",
+                        name: recName,
+                        parameters: [],
+                        body: asBlock(recBlock),
+                        span: parentDecl.span,
+                    };
+                    registerTemplates(recDecl, `${prefix}.${recName}`, `${exportPath}.${recName}`);
+                }
+            };
             for (const decl of header.program.decls)
-                if (decl.kind === "instrument")
-                    templates.set(`${use.name}.${decl.name}`, decl);
+                if (decl.kind === "instrument") {
+                    registerTemplates(decl, `${use.name}.${decl.name}`, decl.name);
+                }
         }
+        for (const decl of program.decls)
+            if (decl.kind === "instrument")
+                templates.set(decl.name, decl);
         const document = {
-            udl: 3,
+            udl: 4,
             version: 1,
             product: program.name,
             title: program.title,
@@ -173,9 +324,12 @@ export function compile(source, options = {}) {
                 programFines: { kind: "business", role: "fine_payable" },
                 programCosts: { kind: "business", role: "cost_recovery" },
             },
+            objects: [],
             instruments: [],
         };
         const objects = new Map();
+        const assignments = new Map();
+        const attachmentSubjects = new Map();
         const names = new Set();
         for (const decl of program.decls) {
             if (decl.kind === "expose" || decl.kind === "hide" || decl.kind === "use")
@@ -183,9 +337,28 @@ export function compile(source, options = {}) {
             if (names.has(decl.name))
                 fail(decl, `duplicate declaration ${decl.name}`, "give this declaration a distinct name");
             names.add(decl.name);
-            if (decl.kind === "object")
+            if (decl.kind === "object") {
                 objects.set(decl.name, decl);
+                for (const entry of decl.body.entries) {
+                    const match = /^attach\s+(\w+)\s*=\s*(.+)$/.exec(entry.key);
+                    if (!match)
+                        continue;
+                    const name = `${decl.name}_${match[1]}`;
+                    assignments.set(name, {
+                        kind: "assignment",
+                        name,
+                        target: match[2],
+                        body: asBlock(entry.value),
+                        span: entry.span,
+                    });
+                    attachmentSubjects.set(name, decl.name);
+                }
+            }
+            if (decl.kind === "assignment")
+                assignments.set(decl.name, decl);
             if (decl.kind === "party") {
+                if (subjectPartyRoles.includes(decl.name))
+                    failWithCode(decl, "party_name_reserved", `${decl.name} is a reserved subject role`, "choose a party name other than owner, actor or operator");
                 if (!["person", "business", "staff"].includes(decl.partyKind))
                     fail(decl, `unknown party kind ${decl.partyKind}`, "choose person, business, or staff");
                 document.parties[decl.name] = {
@@ -197,7 +370,170 @@ export function compile(source, options = {}) {
         const origins = [];
         const materialApprovals = new Set();
         const implicitDecisions = new Map();
-        const addInstrument = (decl, id, arguments_, origin, inherited = new Map(), inheritedApprovers = new Set(), inheritedEnums = new Map()) => {
+        const resolveFamily = (rawPath, expr, required = true) => {
+            const parts = rawPath.split(".");
+            if (parts.length < 2) {
+                if (!required)
+                    return undefined;
+                failWithCode(expr, "HSX1001", `invalid family ${rawPath}`, "use module.instrument or module.instrument.record");
+            }
+            const moduleName = parts[0];
+            const exportPath = parts.slice(1).join(".");
+            const targetTemplate = templates.get(rawPath);
+            if (!targetTemplate) {
+                if (!required)
+                    return undefined;
+                failWithCode(expr, "HSX1001", `unknown family declaration ${rawPath}`, "choose a declared standard instrument");
+            }
+            const topTemplate = templates.get(`${moduleName}.${parts[1]}`);
+            if (!topTemplate) {
+                if (!required)
+                    return undefined;
+                failWithCode(expr, "HSX1001", `unknown family declaration ${moduleName}.${parts[1]}`, "choose a declared standard instrument");
+            }
+            const topBody = entries(topTemplate.body);
+            let revision;
+            if (topBody.has("familyRevision")) {
+                const val = literal(topBody.get("familyRevision"));
+                if (typeof val === "number")
+                    revision = val;
+            }
+            let currentBody = topTemplate.body;
+            for (const recName of parts.slice(2)) {
+                const recs = entries(asBlock(entries(currentBody).get("records")));
+                const child = recs.get(recName);
+                if (child) {
+                    currentBody = asBlock(child);
+                    const cBody = entries(currentBody);
+                    if (cBody.has("familyRevision")) {
+                        const val = literal(cBody.get("familyRevision"));
+                        if (typeof val === "number")
+                            revision = val;
+                    }
+                }
+            }
+            if (revision === undefined) {
+                if (!required)
+                    return undefined;
+                failWithCode(expr, "HSX1001", `declaration ${rawPath} has no familyRevision declared`, "declare familyRevision on the standard instrument");
+            }
+            return { module: moduleName, exportPath, revision };
+        };
+        const addInstrument = (decl, id, arguments_, origin, inherited = new Map(), inheritedApprovers = new Set(), inheritedEnums = new Map(), attachmentInfo, familyDeclaration) => {
+            const resolveFamilyInstruments = (family, currentInstId, expr) => {
+                const found = new Set();
+                if (currentInstId && familyDeclaration) {
+                    if (family.module === familyDeclaration.module &&
+                        family.exportPath.startsWith(`${familyDeclaration.exportPath}.`)) {
+                        const sub = family.exportPath
+                            .slice(familyDeclaration.exportPath.length + 1)
+                            .replaceAll(".", "_");
+                        found.add(`${currentInstId}_${sub}`);
+                    }
+                }
+                const topDeclName = family.exportPath.split(".")[0];
+                const subRecordPath = family.exportPath.includes(".")
+                    ? family.exportPath.slice(topDeclName.length + 1).replaceAll(".", "_")
+                    : undefined;
+                for (const asgn of assignments.values()) {
+                    if (asgn.target === `${family.module}.${topDeclName}`) {
+                        if (subRecordPath) {
+                            found.add(`${asgn.name}_${subRecordPath}`);
+                        }
+                        else {
+                            found.add(asgn.name);
+                        }
+                    }
+                }
+                for (const inst of document.instruments) {
+                    if (inst.family &&
+                        inst.family.module === family.module &&
+                        inst.family.exportPath === family.exportPath &&
+                        inst.family.revision === family.revision) {
+                        found.add(inst.id);
+                    }
+                }
+                const result = [...found];
+                if (result.length === 0 && expr) {
+                    failWithCode(expr, "HSX1001", `no instruments found for family ${family.module}.${family.exportPath}`, "declare an attachment matching this family");
+                }
+                return result;
+            };
+            const resolveChildExportPath = (parentDecl, suffix) => {
+                const recs = entries(asBlock(entries(parentDecl.body).get("records")));
+                for (const [recName] of recs) {
+                    if (suffix === recName)
+                        return recName;
+                }
+                for (const [recName, recBlock] of recs) {
+                    if (suffix.startsWith(`${recName}_`)) {
+                        const rest = resolveChildExportPath({
+                            kind: "instrument",
+                            name: recName,
+                            parameters: [],
+                            body: asBlock(recBlock),
+                            span: parentDecl.span,
+                        }, suffix.slice(recName.length + 1));
+                        if (rest)
+                            return `${recName}.${rest}`;
+                    }
+                }
+                return undefined;
+            };
+            const getInstrumentFamily = (targetId) => {
+                const existing = document.instruments.find((i) => i.id === targetId);
+                if (existing?.family)
+                    return existing.family;
+                if (targetId.startsWith(`${id}_`) && familyDeclaration) {
+                    const sub = resolveChildExportPath(decl, targetId.slice(id.length + 1));
+                    if (sub) {
+                        const fullExport = `${familyDeclaration.exportPath}.${sub}`;
+                        try {
+                            return resolveFamily(`${familyDeclaration.module}.${fullExport}`, { span: origin }, false);
+                        }
+                        catch { }
+                    }
+                }
+                for (const [asgnName, asgn] of assignments) {
+                    if (targetId === asgnName || targetId.startsWith(`${asgnName}_`)) {
+                        const tmpl = templates.get(asgn.target);
+                        if (!tmpl)
+                            continue;
+                        const mod = declarationSources.get(tmpl);
+                        if (!mod || mod === "program")
+                            continue;
+                        if (targetId === asgnName) {
+                            try {
+                                return resolveFamily(asgn.target, asgn, false);
+                            }
+                            catch { }
+                        }
+                        else {
+                            const sub = resolveChildExportPath(tmpl, targetId.slice(asgnName.length + 1));
+                            if (sub) {
+                                const fullTarget = `${asgn.target}.${sub}`;
+                                try {
+                                    return resolveFamily(fullTarget, asgn, false);
+                                }
+                                catch { }
+                            }
+                        }
+                    }
+                }
+                return undefined;
+            };
+            const checkTargetFamily = (targetIds, expectedFamily, expr) => {
+                const ids = Array.isArray(targetIds) ? targetIds : [targetIds];
+                for (const tid of ids) {
+                    const fam = getInstrumentFamily(tid);
+                    if (!fam ||
+                        fam.module !== expectedFamily.module ||
+                        fam.exportPath !== expectedFamily.exportPath ||
+                        fam.revision !== expectedFamily.revision) {
+                        failWithCode(expr, "HSX1001", `target instrument ${tid} family does not match expected family ${expectedFamily.module}.${expectedFamily.exportPath} (revision ${expectedFamily.revision})`, "ensure target instrument matches the declared family");
+                    }
+                }
+            };
             const enums = new Map(inheritedEnums);
             for (const parameter of decl.parameters) {
                 const type = parameter.value.kind === "default"
@@ -207,23 +543,44 @@ export function compile(source, options = {}) {
                     enums.set(parameter.key, type.args.map(text));
             }
             const approvers = new Set(inheritedApprovers);
-            const supplied = entries(arguments_);
+            const supplied = new Map();
+            for (const entry of arguments_.entries) {
+                if (supplied.has(entry.key))
+                    fail(entry, `duplicate tunable ${entry.key}`, "supply each parameter once");
+                supplied.set(entry.key, entry.value);
+            }
             const environment = new Map(inherited);
             for (const param of decl.parameters) {
                 const type = param.value.kind === "default" ? param.value.type : param.value;
                 const fallback = param.value.kind === "default" ? param.value.value : undefined;
-                const actual = supplied.get(param.key) ?? fallback;
+                const typeName = type.kind === "type" || type.kind === "call" ? type.name : text(type);
+                const partyParameter = attachmentInfo && (typeName === "party" || typeName === "approval");
+                const byName = partyParameter &&
+                    (subjectPartyRoles.includes(param.key) ||
+                        document.parties[param.key])
+                    ? { kind: "name", value: param.key, span: origin }
+                    : undefined;
+                const actual = supplied.get(param.key) ??
+                    byName ??
+                    (fallback && {
+                        ...fallback,
+                        source: declarationSources.get(decl) ?? "program",
+                    });
                 if (!actual) {
                     if (type.kind === "type" && type.optional)
                         continue;
-                    fail({ span: origin }, `${id} needs ${param.key}`, `add ${param.key}: value inside ${id}`);
+                    failWithCode({ span: origin }, partyParameter ? "subject_party_unbound" : "HSX1001", `${id} needs ${param.key}`, `add ${param.key}: value inside ${id}`);
                 }
                 environment.set(param.key, actual);
             }
             for (const key of supplied.keys())
                 if (!decl.parameters.some((p) => p.key === key))
                     fail(supplied.get(key), `unknown tunable ${key}`, `choose ${decl.parameters.map((p) => p.key).join(", ")}`);
-            const resolve = (expr, seen = new Set()) => {
+            const isParty = (name) => !!document.parties[name] ||
+                (!!attachmentInfo &&
+                    subjectPartyRoles.includes(name));
+            const resolvedParties = new Set();
+            const resolve = (expr, seen = new Set(), partyBinding = false) => {
                 if (expr.kind === "call" &&
                     ["object", "all", "party"].includes(expr.name)) {
                     if (expr.args.length !== 1)
@@ -231,15 +588,19 @@ export function compile(source, options = {}) {
                     const type = text(expr.args[0]);
                     const matches = expr.name === "party"
                         ? Object.entries(document.parties)
-                            .filter(([, party]) => party.kind === type)
+                            .filter(([name, party]) => party.kind === type && (!partyBinding || names.has(name)))
                             .map(([name]) => name)
-                        : [...objects.values()]
-                            .filter((object) => object.object === type ||
-                            type.startsWith(`${object.object}.`))
-                            .map((object) => object.name +
-                            type.slice(object.object.length).replaceAll(".", "_"));
+                        : [...assignments.values()]
+                            .filter((assignment) => expr.name === "all" ||
+                            !attachmentSubjects.has(assignment.name) ||
+                            attachmentSubjects.get(assignment.name) ===
+                                attachmentInfo?.subjectKindId)
+                            .filter((assignment) => assignment.target === type ||
+                            type.startsWith(`${assignment.target}.`))
+                            .map((assignment) => assignment.name +
+                            type.slice(assignment.target.length).replaceAll(".", "_"));
                     if (expr.name !== "all" && matches.length !== 1)
-                        fail({ span: origin }, `${id} needs ${expr.name === "all" ? "at least one" : "exactly one"} ${type}`, "declare the required object or supply this tunable explicitly");
+                        failWithCode(expr, partyBinding ? "subject_party_unbound" : "HSX1001", `${id} needs ${expr.name === "all" ? "at least one" : "exactly one"} ${type}`, "declare the required object or supply this tunable explicitly");
                     const items = matches.map((value) => ({
                         kind: "name",
                         value,
@@ -251,27 +612,45 @@ export function compile(source, options = {}) {
                 }
                 if (expr.kind !== "name")
                     return expr;
+                const binding = environment.get(expr.value);
+                if (attachmentInfo &&
+                    subjectPartyRoles.includes(expr.value) &&
+                    (!binding ||
+                        (binding.kind === "name" && binding.value === expr.value)))
+                    return expr;
+                if (attachmentInfo) {
+                    const [local, ...tail] = expr.value.split(".");
+                    const target = `${attachmentInfo.subjectKindId}_${local}`;
+                    if (attachmentSubjects.has(target))
+                        return { ...expr, value: [target, ...tail].join("_") };
+                }
                 if (expr.value.startsWith("party.")) {
-                    const binding = environment.get(expr.value.slice(6));
-                    if (binding?.kind === "name" && document.parties[binding.value])
-                        return { ...expr, value: `party.${binding.value}` };
+                    const [, party, ...members] = expr.value.split(".");
+                    const binding = environment.get(party);
+                    if (binding?.kind === "name" && isParty(binding.value))
+                        return {
+                            ...expr,
+                            value: ["party", binding.value, ...members].join("."),
+                        };
                 }
                 const [root, ...tail] = expr.value.split(".");
                 const bound = environment.get(root);
                 if (!bound || (bound.kind === "name" && bound.value === root))
                     return expr;
                 if (seen.has(root))
-                    return fail(expr, `cyclic tunable ${root}`, "replace the cycle with a literal or declared reference");
-                let resolved = supplied.has(root) || inherited.has(root) || enums.has(root)
+                    return failWithCode(expr, partyBinding ? "subject_party_unbound" : "HSX1001", `cyclic tunable ${root}`, "replace the cycle with a literal or declared reference");
+                let resolved = resolvedParties.has(root) ||
+                    (!partyBinding &&
+                        (supplied.has(root) || inherited.has(root) || enums.has(root)))
                     ? bound
-                    : resolve(bound, new Set([...seen, root]));
+                    : resolve(bound, new Set([...seen, root]), partyBinding);
                 for (const key of tail) {
                     if (resolved.kind !== "block")
                         return expr;
                     const child = entries(resolved).get(key);
                     if (!child)
                         return fail(expr, `missing tunable ${expr.value}`, `declare ${key} in ${root}`);
-                    resolved = resolve(child, new Set([...seen, root]));
+                    resolved = resolve(child, new Set([...seen, root]), partyBinding);
                 }
                 return resolved;
             };
@@ -281,7 +660,9 @@ export function compile(source, options = {}) {
                     continue;
                 const t = param.value.kind === "default" ? param.value.type : param.value;
                 const type = t.kind === "type" || t.kind === "call" ? t.name : text(t);
-                const v = supplied.has(param.key) || type === "enum" ? actual : resolve(actual);
+                const v = (supplied.has(param.key) && !attachmentInfo) || type === "enum"
+                    ? actual
+                    : resolve(actual, new Set(), !!attachmentInfo && (type === "party" || type === "approval"));
                 environment.set(param.key, v);
                 if (type === "enum" && t.kind === "call") {
                     if (v.kind !== "name" || !t.args.some((a) => text(a) === v.value))
@@ -292,8 +673,21 @@ export function compile(source, options = {}) {
                         fail(v, `${param.key} needs a list`, "write [value, value]");
                 }
                 else if (type === "party" || type === "approval") {
-                    if (v.kind !== "name" || !document.parties[v.value])
-                        fail(v, `${param.key} needs a declared party`, "declare a party and use its name here");
+                    if (v.kind !== "name" || !isParty(v.value))
+                        failWithCode(actual, attachmentInfo ? "subject_party_unbound" : "HSX1001", `${param.key} needs a declared party`, "declare a party and use its name here");
+                    const party = document.parties[v.value];
+                    if ((type === "approval" && (party?.kind !== "staff" || !party.role)) ||
+                        (type === "party" &&
+                            (party?.kind === "staff" ||
+                                (attachmentInfo && party?.kind === "person"))))
+                        failWithCode(actual, "party_kind_mismatch", `${param.key} cannot bind ${v.value}`, type === "approval"
+                            ? "use a declared staff party with a role"
+                            : "use a subject role or declared business");
+                    resolvedParties.add(param.key);
+                    if (attachmentInfo)
+                        attachmentInfo.parties[param.key] = subjectPartyRoles.includes(v.value)
+                            ? { role: v.value }
+                            : { party: v.value };
                     if (type === "approval")
                         approvers.add(text(v));
                 }
@@ -309,11 +703,14 @@ export function compile(source, options = {}) {
                             fail(value, "reference needs an object name", "name a declared object");
                         const [root, ...tail] = value.value.split(".");
                         const obj = objects.get(root);
+                        const assignment = assignments.get(root);
+                        const targetType = obj ? obj.name : assignment?.target;
                         if ((!obj &&
+                            !assignment &&
                             !document.instruments.some((inst) => inst.id === value.value)) ||
                             (t.kind === "type" &&
                                 t.target &&
-                                [obj?.object, ...tail].join(".") !== t.target))
+                                [targetType, ...tail].join(".") !== t.target))
                             fail(value, `${param.key} has the wrong object type`, `use an object of type ${t.kind === "type" ? t.target : "ref"}`);
                         if (seen.has(value.value))
                             fail(value, "duplicate reference", "list each object once");
@@ -373,15 +770,30 @@ export function compile(source, options = {}) {
             }
             for (const key of body.keys())
                 if (![
+                    "familyRevision",
                     "fields",
                     "lifecycle",
                     "records",
                     "summary",
                     "invariants",
                     "constraints",
+                    "reports",
+                    "revisioned",
                 ].includes(key) &&
                     !key.startsWith("action "))
                     fail(decl, `unknown instrument clause ${key}`, "use fields, lifecycle, actions, invariants, or records");
+            if (body.has("familyRevision")) {
+                const revExpr = body.get("familyRevision");
+                const revVal = literal(revExpr);
+                if (typeof revVal !== "number" ||
+                    !Number.isInteger(revVal) ||
+                    revVal <= 0) {
+                    fail(revExpr, "familyRevision must be a positive integer", "use a positive integer revision");
+                }
+                if (familyDeclaration) {
+                    familyDeclaration.revision = revVal;
+                }
+            }
             const records = entries(asBlock(body.get("records")));
             if (!inherited.size)
                 environment.set("parent", { kind: "name", value: id, span: origin });
@@ -394,12 +806,54 @@ export function compile(source, options = {}) {
                     });
             const fields = [];
             const calculations = [];
+            let currentAction;
+            let currentActionName;
             const path = (expr) => {
                 const value = resolve(expr);
                 const name = text(value);
-                if (document.parties[name])
+                if (isParty(name))
                     return `party.${name}`;
-                return /^(self|input|party)\./.test(name) ? name : `self.${name}`;
+                if (name.startsWith("subject.")) {
+                    const subField = name.split(".")[1];
+                    if (currentAction) {
+                        const req = currentAction.subject?.requirements.find((r) => r.field.name === subField);
+                        if (!req) {
+                            failWithCode(expr, "subject_field_unknown", `subject.${subField} names no declared subject requirement in action ${currentActionName}`, `declare ${subField} in subject { ... }`);
+                        }
+                    }
+                    else {
+                        const declaredInAction = decl.body.entries.some((e) => {
+                            if (!e.key.startsWith("action "))
+                                return false;
+                            const subBlock = entries(asBlock(e.value)).get("subject");
+                            if (!subBlock)
+                                return false;
+                            return asBlock(subBlock).entries.some((se) => {
+                                if (se.key === subField)
+                                    return true;
+                                if (se.key === "adapter") {
+                                    const names = se.value.kind === "list"
+                                        ? se.value.items.map(text)
+                                        : [text(se.value)];
+                                    return names.some((n) => {
+                                        const reg = options.adapterRegistry?.[n];
+                                        if (!reg)
+                                            return false;
+                                        const op = reg.adapter.operationMap[reg.operation];
+                                        return op?.subjectRequirements?.some((sr) => sr.name === subField);
+                                    });
+                                }
+                                return false;
+                            });
+                        });
+                        if (!declaredInAction) {
+                            failWithCode(expr, "subject_field_unknown", `subject.${subField} names no declared subject requirement in instrument ${id}`, `declare ${subField} in an action subject { ... }`);
+                        }
+                    }
+                }
+                return /^(self|input|party|subject)\./.test(name)
+                    ? name
+                    : `self.${name}`;
             };
             const val = (expr) => {
                 const v = resolve(expr);
@@ -414,7 +868,44 @@ export function compile(source, options = {}) {
                     return id;
                 const value = resolve(expr);
                 if (value.kind === "block") {
-                    const result = Object.fromEntries([...entries(value)].map(([key, value]) => [key, data(value)]));
+                    const rawEntries = entries(value);
+                    if ((rawEntries.has("family") && !rawEntries.has("kind")) ||
+                        ((rawEntries.has("states") ||
+                            rawEntries.has("reference") ||
+                            rawEntries.has("anchor")) &&
+                            rawEntries.has("instrument"))) {
+                        let famTuple;
+                        if (rawEntries.has("family")) {
+                            const famExpr = rawEntries.get("family");
+                            const famStr = famExpr.kind === "name" ? famExpr.value : text(famExpr);
+                            famTuple = resolveFamily(famStr, famExpr);
+                        }
+                        let instrumentVal;
+                        if (rawEntries.has("instrument")) {
+                            instrumentVal = data(rawEntries.get("instrument"));
+                            if (famTuple) {
+                                checkTargetFamily(instrumentVal, famTuple, rawEntries.get("instrument"));
+                            }
+                        }
+                        else if (famTuple) {
+                            const matched = resolveFamilyInstruments(famTuple, id, rawEntries.get("family"));
+                            instrumentVal = matched.length === 1 ? matched[0] : matched;
+                        }
+                        const result = {};
+                        if (famTuple) {
+                            result.family = famTuple;
+                        }
+                        if (instrumentVal !== undefined) {
+                            result.instrument = instrumentVal;
+                        }
+                        for (const [k, v] of rawEntries) {
+                            if (k === "family" || k === "instrument")
+                                continue;
+                            result[k] = data(v);
+                        }
+                        return result;
+                    }
+                    const result = Object.fromEntries([...rawEntries].map(([key, value]) => [key, data(value)]));
                     const selection = result.selection;
                     if (Array.isArray(selection?.instrument) &&
                         selection.instrument.length === 0) {
@@ -457,48 +948,77 @@ export function compile(source, options = {}) {
                 for (const row of block.entries) {
                     const t = row.value.kind === "default" ? row.value.type : row.value;
                     const constant = row.value.kind === "default" ? resolve(row.value.value) : undefined;
-                    const type = t.kind === "type" || t.kind === "call" ? t.name : text(t);
-                    const f = {
-                        name: row.key,
-                        type,
-                        ...(t.kind === "type" && t.optional ? { optional: true } : {}),
-                    };
-                    if (type === "enum" && t.kind === "call")
-                        f.values = t.args.map(text);
-                    if (["integer", "money"].includes(type) && t.kind === "call") {
-                        if (t.args.length !== 2)
-                            fail(t, "bounded fields need a minimum and maximum", "write integer(1, 12) or money(0 SAR, 100 SAR)");
-                        f.minimum = literal(resolve(t.args[0]));
-                        f.maximum = literal(resolve(t.args[1]));
-                    }
+                    const f = lowerFieldShape(row, resolve);
+                    const type = f.type;
                     if (type === "list" && t.kind === "call") {
-                        f.item = text(t.args[0]);
-                        f.maxItems = t.args[1] ? literal(resolve(t.args[1])) : 366;
-                    }
-                    if (type === "list" && t.kind === "type") {
-                        f.item = t.target;
-                        f.maxItems = 366;
+                        const item = t.args[0];
+                        if (item.kind === "type" && item.name === "ref" && item.target) {
+                            f.target = text(resolve({ kind: "name", value: item.target, span: item.span })).replaceAll(".", "_");
+                            f.targetKind = objects.has(String(f.target))
+                                ? "object"
+                                : "instrument";
+                        }
                     }
                     if (type === "ref") {
-                        const target = t.kind === "type" ? t.target : undefined;
-                        if (!target)
-                            fail(row, "reference needs a target", "write ref<object>");
-                        const [root, ...tail] = target.split(".");
-                        const resolved = environment.get(root);
-                        const resolvedTargets = resolved?.kind === "list"
-                            ? resolved.items
-                            : resolved
-                                ? [resolved]
-                                : [];
-                        const targets = resolvedTargets.map((value) => [text(resolve(value)).replaceAll(".", "_"), ...tail].join("_"));
-                        f.target =
-                            target === "self"
-                                ? id
-                                : targets.length === 1
-                                    ? targets[0]
-                                    : targets.length
-                                        ? targets
-                                        : target;
+                        if (t.kind === "block") {
+                            const b = entries(t);
+                            const famNode = b.get("targetFamily") ?? b.get("family");
+                            let targetFamTuple;
+                            if (famNode) {
+                                const famStr = famNode.kind === "name" ? famNode.value : text(famNode);
+                                targetFamTuple = resolveFamily(famStr, famNode);
+                                f.targetFamily = targetFamTuple;
+                            }
+                            if (b.has("target") || b.has("instrument")) {
+                                const tgtExpr = (b.get("target") ?? b.get("instrument"));
+                                const resolvedTgt = resolve(tgtExpr);
+                                let tgtVal;
+                                if (resolvedTgt.kind === "list") {
+                                    const items = resolvedTgt.items.map((it) => text(resolve(it)).replaceAll(".", "_"));
+                                    tgtVal = items.length === 1 ? items[0] : items;
+                                }
+                                else {
+                                    tgtVal = text(resolvedTgt).replaceAll(".", "_");
+                                }
+                                f.target = tgtVal;
+                                if (targetFamTuple) {
+                                    checkTargetFamily(tgtVal, targetFamTuple, tgtExpr);
+                                }
+                            }
+                            else if (targetFamTuple) {
+                                const matched = resolveFamilyInstruments(targetFamTuple, id, famNode);
+                                f.target = matched.length === 1 ? matched[0] : matched;
+                            }
+                            f.targetKind =
+                                typeof f.target === "string" && objects.has(f.target)
+                                    ? "object"
+                                    : "instrument";
+                        }
+                        else {
+                            const target = t.kind === "type" ? t.target : undefined;
+                            if (!target)
+                                fail(row, "reference needs a target", "write ref<object>");
+                            const [root, ...tail] = target.split(".");
+                            const resolved = environment.get(root);
+                            const resolvedTargets = resolved?.kind === "list"
+                                ? resolved.items
+                                : resolved
+                                    ? [resolved]
+                                    : [];
+                            const targets = resolvedTargets.map((value) => [text(resolve(value)).replaceAll(".", "_"), ...tail].join("_"));
+                            f.target =
+                                target === "self"
+                                    ? id
+                                    : targets.length === 1
+                                        ? targets[0]
+                                        : targets.length
+                                            ? targets
+                                            : target;
+                            f.targetKind =
+                                typeof f.target === "string" && objects.has(f.target)
+                                    ? "object"
+                                    : "instrument";
+                        }
                     }
                     else if (type === "account") {
                         if (t.kind === "call") {
@@ -508,8 +1028,10 @@ export function compile(source, options = {}) {
                             f.book = t.args[1] ? text(t.args[1]) : "cash";
                             if (t.args[2]) {
                                 const mode = text(t.args[2]);
-                                if (["contra", "external"].includes(mode))
-                                    f[mode] = true;
+                                if (mode === "external")
+                                    fail(t, "external account mode was removed", "use a reservation and instruction-bound evidence");
+                                if (mode === "contra")
+                                    f.contra = true;
                                 else
                                     f.key = mode;
                             }
@@ -620,6 +1142,7 @@ export function compile(source, options = {}) {
             lifecycle.transitions = {};
             const inst = {
                 id,
+                ...(attachmentInfo ? { subject: attachmentInfo.subjectKindId } : {}),
                 title: title(id),
                 summary: body.has("summary")
                     ? String(data(body.get("summary")))
@@ -637,21 +1160,213 @@ export function compile(source, options = {}) {
                     entries: block.entries.flatMap((entry) => {
                         if (!entry.key.startsWith("when "))
                             return [entry];
-                        const [, tunable, , choice] = entry.key.split(" ");
+                        const [, tunable, relation, choice] = entry.key.split(" ");
                         const binding = environment.get(tunable);
                         if (!binding)
-                            fail(entry, `unknown branch tunable ${tunable}`, "name an enum tunable declared by this header");
-                        if (!enums.get(tunable)?.includes(choice))
-                            fail(entry, `unknown enum branch ${choice}`, "use a declared enum value");
+                            fail(entry, `unknown branch tunable ${tunable}`, "name an enum or reference tunable declared by this header");
+                        let matches;
+                        if (relation === "has") {
+                            // Inspect declarations, not lowering order: a bound object may
+                            // appear after the instrument that asks about its fields.
+                            const bound = resolve(binding);
+                            const [root, ...children] = text(bound).split(".");
+                            const assignment = assignments.get(root);
+                            let target = assignment
+                                ? templates.get(assignment.target)?.body
+                                : program.decls
+                                    .filter((decl) => decl.kind === "instrument")
+                                    .find((decl) => decl.name === root)?.body;
+                            for (const child of children) {
+                                const record = target
+                                    ? entries(asBlock(entries(target).get("records"))).get(child)
+                                    : undefined;
+                                target = record ? asBlock(record) : undefined;
+                            }
+                            if (!target)
+                                fail(entry, "field branch needs a declared object", "bind a reference to a declared object");
+                            matches = entries(asBlock(entries(target).get("fields"))).has(choice);
+                        }
+                        else {
+                            if (!enums.get(tunable)?.includes(choice))
+                                fail(entry, `unknown enum branch ${choice}`, "use a declared enum value");
+                            matches = text(binding) === choice;
+                        }
                         const body = asBlock(entry.value);
                         for (const clause of body.entries)
                             if (!["requires", "moves", "invoke", "calculate"].includes(clause.key) &&
                                 !clause.key.startsWith("when "))
                                 fail(clause, "when permits requirements, calculations, moves and invocations", "keep lifecycle and actor clauses outside the branch");
-                        return text(binding) === choice ? selected(body).entries : [];
+                        return matches ? selected(body).entries : [];
                     }),
                 });
                 const slots = entries(selected(asBlock(row.value)));
+                let actionSubject;
+                let subjectExpr = slots.get("subject");
+                const boundaryBindings = new Set();
+                const authoredMoves = slots.get("moves");
+                for (const move of authoredMoves?.kind === "list"
+                    ? authoredMoves.items
+                    : authoredMoves
+                        ? [authoredMoves]
+                        : []) {
+                    const parts = entries(asBlock(move));
+                    const boundary = parts.get("boundary");
+                    if (!boundary)
+                        continue;
+                    if ((parts.has("operation")
+                        ? String(data(parts.get("operation")))
+                        : "internal_transfer.create") !== "internal_transfer.reserve" ||
+                        parts.has("shares") ||
+                        parts.has("fee"))
+                        fail(move, "boundary dispatch requires a reservation", "reserve the exact amount before dispatch");
+                    const adapterExpr = entries(asBlock(boundary)).get("adapter");
+                    if (!adapterExpr)
+                        fail(boundary, "boundary needs an adapter", "name a bound ADL adapter");
+                    const binding = text(resolve(adapterExpr));
+                    const target = options.adapterRegistry &&
+                        Object.hasOwn(options.adapterRegistry, binding)
+                        ? options.adapterRegistry[binding]
+                        : undefined;
+                    if (!target ||
+                        !Object.hasOwn(target.adapter.operationMap, target.operation))
+                        fail(boundary, `unknown boundary adapter ${binding}`, "bind the named ADL adapter before compilation");
+                    boundaryBindings.add(binding);
+                }
+                if (boundaryBindings.size) {
+                    const block = asBlock(subjectExpr);
+                    const declared = new Set(block.entries
+                        .filter((entry) => entry.key === "adapter")
+                        .flatMap((entry) => entry.value.kind === "list"
+                        ? entry.value.items.map(text)
+                        : [text(entry.value)]));
+                    subjectExpr = {
+                        ...block,
+                        entries: [
+                            ...block.entries,
+                            ...[...boundaryBindings]
+                                .filter((binding) => !declared.has(binding))
+                                .map((binding) => ({
+                                key: "adapter",
+                                value: {
+                                    kind: "name",
+                                    value: binding,
+                                    span: row.span,
+                                },
+                                span: row.span,
+                            })),
+                        ],
+                    };
+                }
+                if (subjectExpr) {
+                    const subjectBlock = asBlock(subjectExpr);
+                    const directRequirements = [];
+                    const adapterList = [];
+                    for (const entry of subjectBlock.entries) {
+                        if (entry.key === "adapter") {
+                            const bindingNames = entry.value.kind === "list"
+                                ? entry.value.items.map(text)
+                                : [text(entry.value)];
+                            for (const bindingName of bindingNames) {
+                                const target = options.adapterRegistry?.[bindingName];
+                                if (target) {
+                                    const { adapter, operation } = target;
+                                    const opBinding = adapter.operationMap[operation];
+                                    if (opBinding &&
+                                        opBinding.subjectRequirements !== undefined) {
+                                        const validatedRequirements = [];
+                                        for (const req of opBinding.subjectRequirements) {
+                                            const result = udlObjectFieldSchema.safeParse(req);
+                                            if (!result.success || result.data.optional) {
+                                                fail(entry, `adapter requirement ${req.name} is invalid or optional: ${result.success ? "requirements cannot be optional" : result.error.message}`, "ensure adapter subject requirements conform to UDL schema");
+                                            }
+                                            validatedRequirements.push(result.data);
+                                        }
+                                        const declaration = {
+                                            provider: adapter.provider,
+                                            capability: adapter.capability,
+                                            operation,
+                                            requirements: validatedRequirements,
+                                        };
+                                        const digest = sha256(new TextEncoder().encode(canonicalJson(declaration)));
+                                        const snapshot = {
+                                            ...declaration,
+                                            declarationDigest: Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join(""),
+                                        };
+                                        const adapterRenames = {};
+                                        if (attachmentInfo?.renames) {
+                                            for (const req of snapshot.requirements) {
+                                                if (attachmentInfo.renames.has(req.name)) {
+                                                    adapterRenames[req.name] = attachmentInfo.renames.get(req.name);
+                                                }
+                                            }
+                                        }
+                                        adapterList.push({
+                                            binding: bindingName,
+                                            snapshot,
+                                            ...(Object.keys(adapterRenames).length > 0
+                                                ? { renames: adapterRenames }
+                                                : {}),
+                                        });
+                                        for (const reqField of snapshot.requirements) {
+                                            const objectField = attachmentInfo?.renames.get(reqField.name);
+                                            const targetName = objectField ?? reqField.name;
+                                            const existing = directRequirements.find((r) => (r.objectField ?? r.field.name) === targetName);
+                                            if (existing) {
+                                                if (!sameObjectField(existing.field, reqField)) {
+                                                    failWithCode(entry, "subject_field_conflict", `conflicting requirement ${reqField.name} in action ${name}`, "rename or unify the requirement");
+                                                }
+                                            }
+                                            else {
+                                                directRequirements.push({
+                                                    field: { ...reqField },
+                                                    ...(objectField ? { objectField } : {}),
+                                                });
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        adapterList.push({
+                                            binding: bindingName,
+                                            snapshot: null,
+                                        });
+                                    }
+                                }
+                                else {
+                                    adapterList.push({
+                                        binding: bindingName,
+                                        snapshot: null,
+                                    });
+                                }
+                            }
+                        }
+                        else {
+                            const fieldDef = lowerObjectField(entry, resolve);
+                            if (fieldDef.optional) {
+                                fail(entry, `subject requirement ${entry.key} cannot be optional`, "remove ? from requirement");
+                            }
+                            const objectField = attachmentInfo?.renames.get(entry.key);
+                            const targetName = objectField ?? entry.key;
+                            const existing = directRequirements.find((r) => (r.objectField ?? r.field.name) === targetName);
+                            if (existing) {
+                                if (!sameObjectField(existing.field, fieldDef)) {
+                                    failWithCode(entry, "subject_field_conflict", `conflicting requirement ${entry.key} in action ${name}`, "rename or unify the requirement");
+                                }
+                            }
+                            else {
+                                directRequirements.push({
+                                    field: fieldDef,
+                                    ...(objectField ? { objectField } : {}),
+                                });
+                            }
+                        }
+                    }
+                    if (directRequirements.length > 0 || adapterList.length > 0) {
+                        actionSubject = {
+                            requirements: directRequirements,
+                            adapters: adapterList,
+                        };
+                    }
+                }
                 const a = {
                     summary: slots.has("summary")
                         ? String(data(slots.get("summary")))
@@ -662,7 +1377,14 @@ export function compile(source, options = {}) {
                     input: lowerFields(asBlock(slots.get("input"))),
                     requires: [],
                     moves: [],
+                    ...(actionSubject ? { subject: actionSubject } : {}),
                 };
+                for (const binding of boundaryBindings)
+                    if (!a.subject?.adapters.find((entry) => entry.binding === binding)
+                        ?.snapshot)
+                        fail(row, `boundary adapter ${binding} has no declared requirements`, "declare the adapter subject requirements, including an explicit empty list");
+                currentAction = a;
+                currentActionName = name;
                 if (name !== "create") {
                     const from = slots.get("from");
                     const to = slots.get("to");
@@ -674,7 +1396,7 @@ export function compile(source, options = {}) {
                     };
                 }
                 for (const [key, expr] of slots) {
-                    if (["from", "to", "input", "summary"].includes(key))
+                    if (["from", "to", "input", "summary", "subject"].includes(key))
                         continue;
                     if (key === "moves") {
                         const moves = expr.kind === "list" ? expr.items : [expr];
@@ -695,6 +1417,17 @@ export function compile(source, options = {}) {
                             if (op === "internal_transfer.create" ||
                                 op === "internal_transfer.reserve") {
                                 const amount = parts.get("amount"), from = parts.get("from"), to = parts.get("to");
+                                if (amount) {
+                                    const resolvedAmount = resolve(amount);
+                                    if (resolvedAmount.kind === "name" &&
+                                        resolvedAmount.value.startsWith("subject.")) {
+                                        const subField = resolvedAmount.value.split(".")[1];
+                                        const req = a.subject?.requirements.find((r) => r.field.name === subField);
+                                        if (req && req.field.type !== "money") {
+                                            fail(amount, `move amount subject.${subField} must have type money`, "use a money field");
+                                        }
+                                    }
+                                }
                                 if (parts.has("shares")) {
                                     if (!amount ||
                                         !from ||
@@ -715,7 +1448,7 @@ export function compile(source, options = {}) {
                                             span: rate.span,
                                         });
                                         if (recipient.kind !== "name" ||
-                                            !document.parties[recipient.value] ||
+                                            !isParty(recipient.value) ||
                                             rate.kind !== "percent")
                                             fail(rate, "split needs party percentages", "write party_name: 70%");
                                         total += Number(literal(rate));
@@ -770,6 +1503,13 @@ export function compile(source, options = {}) {
                                             ...transfer,
                                             operation: op,
                                             capture: String(data(parts.get("capture"))),
+                                            ...(parts.has("boundary")
+                                                ? {
+                                                    boundary: {
+                                                        adapter: text(resolve(entries(asBlock(parts.get("boundary"))).get("adapter"))),
+                                                    },
+                                                }
+                                                : {}),
                                         }
                                         : { ...transfer, operation: op });
                                 else {
@@ -888,8 +1628,40 @@ export function compile(source, options = {}) {
                     else
                         a[key] = data(expr);
                 }
+                if (attachmentInfo) {
+                    if (attachmentInfo.exposed.has(name)) {
+                        a.publicAction = attachmentInfo.exposed.get(name);
+                    }
+                    else {
+                        delete a.publicAction;
+                    }
+                }
                 if (automatic(a.actor))
                     delete a.publicAction;
+                const checkSubjectPaths = (obj, span) => {
+                    if (typeof obj === "string") {
+                        if (obj.startsWith("subject.")) {
+                            const subField = obj.split(".")[1];
+                            const req = a.subject?.requirements.find((r) => r.field.name === subField);
+                            if (!req) {
+                                failWithCode({ span }, "subject_field_unknown", `subject.${subField} names no declared subject requirement in action ${name}`, `declare ${subField} in subject { ... }`);
+                            }
+                        }
+                    }
+                    else if (Array.isArray(obj)) {
+                        for (const item of obj)
+                            checkSubjectPaths(item, span);
+                    }
+                    else if (obj !== null && typeof obj === "object") {
+                        for (const val of Object.values(obj))
+                            checkSubjectPaths(val, span);
+                    }
+                };
+                checkSubjectPaths(a.requires, row.span);
+                checkSubjectPaths(a.set, row.span);
+                checkSubjectPaths(a.invoke, row.span);
+                currentAction = undefined;
+                currentActionName = undefined;
                 for (const requirement of a.requires ?? []) {
                     if (requirement.kind !== "approval" ||
                         !approvers.has(requirement.party))
@@ -897,25 +1669,45 @@ export function compile(source, options = {}) {
                     const action = requirement.action ?? name;
                     const key = `${id}_${action}_decision`;
                     const previous = implicitDecisions.get(key);
-                    if (previous && previous.party !== requirement.party)
-                        fail({ span: origin }, `action ${action} has multiple approval parties`, "use a separate decision action for each party");
+                    if (previous &&
+                        (previous.party !== requirement.party ||
+                            previous.protectedRequest !==
+                                (requirement.protectedRequest ?? "self")))
+                        fail({ span: origin }, `action ${action} has conflicting approval parties or protected requests`, "use a separate decision action for each party");
                     implicitDecisions.set(key, {
                         target: id,
                         action,
                         party: requirement.party,
+                        protectedRequest: requirement.protectedRequest ?? "self",
                         origin,
                     });
                 }
+                for (const requirement of a.subject?.requirements ?? []) {
+                    const entry = asBlock(subjectExpr).entries.find((entry) => entry.key === requirement.field.name) ??
+                        asBlock(subjectExpr).entries.find((entry) => entry.key === "adapter");
+                    requirementOrigins.set(requirement, {
+                        source: declarationSources.get(decl) ?? "program",
+                        span: entry?.span ?? row.span,
+                        message: `${id}.${name}.subject.${requirement.field.name}`,
+                    });
+                }
                 inst.actions[name] = a;
                 inst.actionOrder.push(name);
             }
-            for (const key of ["invariants"])
+            for (const key of ["invariants", "reports", "revisioned"])
                 if (body.has(key))
                     inst[key] = data(body.get(key));
             origins.push({
                 path: `$.instruments[${document.instruments.length}]`,
                 span: { ...origin, ...lineColAt(source, origin.start) },
             });
+            if (familyDeclaration && familyDeclaration.revision !== undefined) {
+                inst.family = {
+                    module: familyDeclaration.module,
+                    exportPath: familyDeclaration.exportPath,
+                    revision: familyDeclaration.revision,
+                };
+            }
             document.instruments.push(inst);
             for (const [key, definition] of records) {
                 const child = {
@@ -925,11 +1717,169 @@ export function compile(source, options = {}) {
                     body: asBlock(definition),
                     span: origin,
                 };
+                declarationSources.set(child, declarationSources.get(decl) ?? "program");
+                const childFamily = familyDeclaration
+                    ? {
+                        module: familyDeclaration.module,
+                        exportPath: `${familyDeclaration.exportPath}.${key}`,
+                        ...(familyDeclaration.revision !== undefined
+                            ? { revision: familyDeclaration.revision }
+                            : {}),
+                    }
+                    : undefined;
                 addInstrument(child, `${id}_${key}`, emptyBlock, origin, new Map([
                     ...environment,
                     ["parent", { kind: "name", value: id, span: origin }],
-                ]), approvers, enums);
+                ]), approvers, enums, attachmentInfo
+                    ? { ...attachmentInfo, exposed: new Map() }
+                    : undefined, childFamily);
+            }
+        };
+        const compileObject = (decl) => {
+            const body = entries(decl.body);
+            for (const key of body.keys()) {
+                if (key !== "fields" &&
+                    key !== "columns" &&
+                    !key.startsWith("attach ")) {
+                    fail(decl, `unknown object clause ${key}`, "use fields, columns, or attach");
+                }
+            }
+            // 1. Lower authored fields
+            const authoredFields = [];
+            const authoredNames = [];
+            const fieldsBlock = asBlock(body.get("fields"));
+            for (const row of fieldsBlock.entries) {
+                if (RESERVED_OBJECT_NAMES.some((name) => name === row.key)) {
+                    fail(row, `${row.key} is a reserved object name`, "rename this field");
+                }
+                const fieldDef = lowerObjectField(row);
+                authoredFields.push(fieldDef);
+                authoredNames.push(row.key);
             }
+            // 2. Process attachments
+            const attachments = [];
+            for (const entry of decl.body.entries) {
+                if (!entry.key.startsWith("attach "))
+                    continue;
+                const match = /^attach\s+([A-Za-z0-9_]+)\s*=\s*(.+)$/.exec(entry.key);
+                if (!match) {
+                    fail(entry, "invalid attach syntax", "write attach name = template { ... }");
+                }
+                const attachmentName = match[1];
+                const targetTemplate = match[2];
+                const template = templates.get(targetTemplate);
+                if (!template) {
+                    fail(entry, `unknown instrument ${targetTemplate}`, `add use ${targetTemplate.split(".")[0]} and choose a declared instrument`);
+                }
+                const instId = `${decl.name}_${attachmentName}`;
+                const attachmentBlock = asBlock(entry.value);
+                const renames = new Map();
+                const renameEntries = new Map();
+                const exposed = new Map();
+                const tunableEntries = [];
+                for (const row of attachmentBlock.entries) {
+                    if (row.key === "rename") {
+                        for (const r of asBlock(row.value).entries) {
+                            renames.set(r.key, text(r.value));
+                            renameEntries.set(r.key, r);
+                        }
+                    }
+                    else if (row.key === "expose") {
+                        if (row.value.kind === "call") {
+                            const actionName = row.value.name;
+                            const publicName = text(row.value.args[0]);
+                            exposed.set(actionName, publicName);
+                        }
+                    }
+                    else {
+                        tunableEntries.push(row);
+                    }
+                }
+                const parties = {};
+                attachments.push({ name: attachmentName, instrument: instId, parties });
+                const tunableBlock = {
+                    kind: "block",
+                    entries: tunableEntries,
+                    span: entry.value.span,
+                };
+                const templateFamily = resolveFamily(targetTemplate, entry, false);
+                addInstrument(template, instId, tunableBlock, entry.span, new Map(), new Set(), new Map(), {
+                    subjectKindId: decl.name,
+                    attachmentName,
+                    renames,
+                    exposed,
+                    parties,
+                }, templateFamily ? { ...templateFamily } : undefined);
+                const attachedInst = document.instruments.find((i) => i.id === instId);
+                if (attachedInst?.actions.create) {
+                    const owned = new Set(attachedInst.calculate.map((node) => node.target));
+                    for (const action of Object.values(attachedInst.actions)) {
+                        for (const node of action.calculate ?? [])
+                            owned.add(node.target);
+                        for (const move of action.moves)
+                            if ("capture" in move && move.capture)
+                                owned.add(move.capture);
+                    }
+                    const create = attachedInst.actions.create;
+                    for (const field of attachedInst.fields) {
+                        if (field.type === "account" ||
+                            (field.type === "ref" && field.targetKind === "instrument") ||
+                            (field.type === "list" &&
+                                field.item === "ref" &&
+                                field.targetKind === "instrument") ||
+                            field.optional ||
+                            "value" in field ||
+                            owned.has(field.name))
+                            continue;
+                        create.subject ??= { requirements: [], adapters: [] };
+                        const existing = create.subject.requirements.find((item) => item.field.name === field.name);
+                        if (existing) {
+                            if (canonicalJson(existing.field) !== canonicalJson(field))
+                                failWithCode(entry, "subject_field_conflict", `${instId}.create.subject.${field.name} conflicts with its instrument field`, "use the instrument field's type and constraints");
+                            continue;
+                        }
+                        const objectField = renames.get(field.name);
+                        const requirement = {
+                            field,
+                            ...(objectField ? { objectField } : {}),
+                        };
+                        create.subject.requirements.push(requirement);
+                        requirementOrigins.set(requirement, {
+                            source: declarationSources.get(template) ?? "program",
+                            span: entry.span,
+                            message: `${instId}.create.fields.${field.name}`,
+                        });
+                    }
+                }
+                for (const [oldName] of renames) {
+                    const found = attachedInst &&
+                        Object.values(attachedInst.actions).some((action) => action.subject?.requirements.some((requirement) => requirement.field.name === oldName));
+                    if (!found) {
+                        const renameEntry = renameEntries.get(oldName) ?? entry;
+                        failWithCode(renameEntry, "subject_field_unknown", `rename source '${oldName}' is not a declared subject requirement of ${targetTemplate}`, "rename a declared subject requirement");
+                    }
+                }
+            }
+            // 4. Validate columns
+            const columnsExpr = body.get("columns");
+            let columns = [];
+            if (columnsExpr) {
+                if (columnsExpr.kind !== "list") {
+                    fail(columnsExpr, "columns needs a list of field names", "write columns: [name, ...]");
+                }
+                columns = columnsExpr.items.map(text);
+                if (columns.length > 8) {
+                    fail(columnsExpr, "at most 8 columns allowed", "choose up to 8 columns");
+                }
+            }
+            document.objects.push({
+                id: decl.name,
+                title: decl.title,
+                authoredFields: authoredNames,
+                attachments,
+                fields: authoredFields,
+                columns,
+            });
         };
         for (const decl of program.decls) {
             if (decl.kind === "instrument") {
@@ -937,11 +1887,123 @@ export function compile(source, options = {}) {
                     fail(decl, "program records cannot declare tunables", "put reusable instruments in a header");
                 addInstrument(decl, decl.name, emptyBlock, decl.span);
             }
-            if (decl.kind === "object") {
-                const template = templates.get(decl.object);
+            if (decl.kind === "assignment") {
+                const template = templates.get(decl.target);
                 if (!template)
-                    fail(decl, `unknown object ${decl.object}`, `add use ${decl.object.split(".")[0]} and choose a declared object`);
-                addInstrument(template, decl.name, decl.body, decl.span);
+                    fail(decl, `unknown instrument ${decl.target}`, `add use ${decl.target.split(".")[0]} and choose a declared instrument`);
+                const templateFamily = resolveFamily(decl.target, decl, false);
+                addInstrument(template, decl.name, decl.body, decl.span, new Map(), new Set(), new Map(), undefined, templateFamily ? { ...templateFamily } : undefined);
+            }
+            if (decl.kind === "object") {
+                compileObject(decl);
+            }
+        }
+        // Propagate mandatory invoked action requirements
+        let changedInvocations = true;
+        let invocationIterations = 0;
+        while (changedInvocations && invocationIterations < 32) {
+            changedInvocations = false;
+            invocationIterations++;
+            for (const inst of document.instruments) {
+                for (const action of Object.values(inst.actions)) {
+                    for (const call of action.invoke ?? []) {
+                        if (call.guard)
+                            continue;
+                        let targetIds = [];
+                        if ("instrument" in call) {
+                            targetIds = [call.instrument];
+                        }
+                        else if ("selection" in call) {
+                            targetIds = Array.isArray(call.selection.instrument)
+                                ? call.selection.instrument
+                                : [call.selection.instrument];
+                        }
+                        else if ("reference" in call) {
+                            const refField = resolveField(document, inst, call.reference, action.input, action);
+                            if (refField?.type === "ref" &&
+                                refField.targetKind === "instrument") {
+                                targetIds = Array.isArray(refField.target)
+                                    ? refField.target
+                                    : [refField.target];
+                            }
+                        }
+                        for (const targetId of targetIds) {
+                            const targetInst = document.instruments.find((i) => i.id === targetId);
+                            if (!targetInst)
+                                continue;
+                            if (inst.subject &&
+                                targetInst.subject &&
+                                inst.subject === targetInst.subject) {
+                                const targetAction = targetInst.actions[call.action];
+                                if (!targetAction?.subject)
+                                    continue;
+                                if (!action.subject) {
+                                    action.subject = { requirements: [], adapters: [] };
+                                }
+                                for (const adapter of targetAction.subject.adapters) {
+                                    if (!action.subject.adapters.some((existing) => existing.binding === adapter.binding)) {
+                                        action.subject.adapters.push(adapter);
+                                        changedInvocations = true;
+                                    }
+                                }
+                                for (const targetReq of targetAction.subject.requirements) {
+                                    const targetObjFieldName = targetReq.objectField ?? targetReq.field.name;
+                                    const existing = action.subject.requirements.find((cr) => (cr.objectField ?? cr.field.name) === targetObjFieldName);
+                                    if (!existing) {
+                                        const inherited = {
+                                            field: { ...targetReq.field, name: targetObjFieldName },
+                                        };
+                                        action.subject.requirements.push(inherited);
+                                        requirementOrigins.set(inherited, requirementOrigins.get(targetReq));
+                                        changedInvocations = true;
+                                    }
+                                    else if (!sameObjectField(existing.field, targetReq.field)) {
+                                        const first = requirementOrigins.get(existing);
+                                        const second = requirementOrigins.get(targetReq);
+                                        throw new CompileFailure({
+                                            code: "subject_field_conflict",
+                                            message: `${first.message} conflicts with ${second.message}: incompatible requirement '${targetObjFieldName}'`,
+                                            fix: "ensure compatible requirement definitions across invoked actions",
+                                            span: first.span,
+                                            source: first.source,
+                                            related: [first, second],
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        for (const kind of document.objects) {
+            const origins = new Map(kind.fields.map((field) => [
+                field.name,
+                `authored field ${kind.id}.${field.name}`,
+            ]));
+            for (const instrument of document.instruments.filter((item) => item.subject === kind.id)) {
+                for (const name of instrument.actionOrder) {
+                    for (const requirement of instrument.actions[name].subject
+                        ?.requirements ?? []) {
+                        const field = {
+                            ...requirement.field,
+                            name: requirement.objectField ?? requirement.field.name,
+                        };
+                        const previous = kind.fields.find((item) => item.name === field.name);
+                        const origin = `${instrument.id}.${name}.subject.${requirement.field.name}`;
+                        if (previous && !sameObjectField(previous, field)) {
+                            failWithCode(objects.get(kind.id), "subject_field_conflict", `${origin} conflicts with ${origins.get(field.name)}: incompatible types or constraints`, "rename fields with different meanings");
+                        }
+                        if (!previous) {
+                            kind.fields.push(field);
+                            origins.set(field.name, origin);
+                        }
+                    }
+                }
+            }
+            for (const column of kind.columns) {
+                if (!kind.fields.some((field) => field.name === column))
+                    failWithCode(objects.get(kind.id), "subject_field_unknown", `column ${column} is unknown on ${kind.id}`, "name an authored field or attached requirement");
             }
         }
         const eliminatedStates = new Map();
@@ -974,7 +2036,8 @@ export function compile(source, options = {}) {
             for (let n = 0; n < inst.lifecycle.states.length; n++)
                 for (const edge of Object.values(inst.lifecycle.transitions))
                     if (edge.from.some((state) => reachable.has(state)))
-                        reachable.add(edge.to);
+                        if (edge.to !== "preserve")
+                            reachable.add(edge.to);
             for (const [key, edge] of Object.entries(inst.lifecycle.transitions)) {
                 edge.from = edge.from.filter((state) => reachable.has(state));
                 if (!edge.from.length) {
@@ -1013,13 +2076,36 @@ export function compile(source, options = {}) {
                     continue;
                 const existing = document.instruments.some((inst) => Object.values(inst.actions).some((action) => action.approval?.action === decision.action &&
                     action.approval.party === decision.party &&
-                    inst.fields.some((field) => field.type === "ref" &&
-                        field.target === decision.target &&
-                        `self.${field.name}` === action.approval?.target)));
+                    inst.fields.some((field) => {
+                        if (field.type !== "ref" ||
+                            field.target !== decision.target ||
+                            `self.${field.name}` !== action.approval?.target)
+                            return false;
+                        const [root, name, ...tail] = decision.protectedRequest.split(".");
+                        const input = name && action.approval.input[name];
+                        const request = root === "self"
+                            ? [action.approval.target, name, ...tail]
+                                .filter(Boolean)
+                                .join(".")
+                            : root === "input" && name
+                                ? input && "field" in input
+                                    ? [input.field, ...tail].join(".")
+                                    : materialApprovals.has(action)
+                                        ? [`self.material_${name}`, ...tail].join(".")
+                                        : undefined
+                                : undefined;
+                        return (request !== undefined &&
+                            action.approval.protectedRequest === request);
+                    })));
                 if (existing)
                     continue;
                 if (document.instruments.some((inst) => inst.id === id))
                     fail({ span: decision.origin }, `implicit decision name ${id} is already used`, "rename the conflicting object");
+                const protectedRequest = decision.protectedRequest === "self"
+                    ? "self.target"
+                    : decision.protectedRequest.startsWith("self.")
+                        ? `self.target.${decision.protectedRequest.slice(5)}`
+                        : fail({ span: decision.origin }, "implicit approval needs a stored protected request", "declare an explicit decision for an input-based protected request");
                 addInstrument(template, id, {
                     kind: "block",
                     span: decision.origin,
@@ -1027,16 +2113,27 @@ export function compile(source, options = {}) {
                         for: decision.target,
                         approved_by: decision.party,
                         action: decision.action,
+                        protected_request: protectedRequest,
                     }).map(([key, value]) => ({
                         key,
                         value: {
-                            kind: key === "action" ? "text" : "name",
+                            kind: key === "action" || key === "protected_request"
+                                ? "text"
+                                : "name",
                             value,
                             span: decision.origin,
                         },
                         span: decision.origin,
                     })),
-                }, decision.origin);
+                }, decision.origin, new Map(), new Set(), new Map(), document.instruments.find((instrument) => instrument.id === decision.target)?.subject
+                    ? {
+                        subjectKindId: document.instruments.find((instrument) => instrument.id === decision.target).subject,
+                        attachmentName: id,
+                        parties: {},
+                        renames: new Map(),
+                        exposed: new Map(),
+                    }
+                    : undefined);
             }
         }
         // Material approval fields are inferred from the selected action's typed input.
@@ -1099,7 +2196,7 @@ export function compile(source, options = {}) {
                         .reverse()
                         .find((o) => i.path.startsWith(o.path));
                     return diagnostic({
-                        code: "HSX1601",
+                        code: i.code.startsWith("UDL") ? "HSX1601" : i.code,
                         message: `${i.path}: ${i.message}`,
                         fix: i.fix,
                         span: origin?.span ?? program.span,