@hyperscale0/hsx 1.0.0 → 2.0.1

package/dist/src/typecheck.js

@@ -5,6 +5,7 @@ const CAMEL_CASE = /^[a-z][A-Za-z0-9]*$/;
 const CURRENCY = /^[A-Z]{3}$/;
 const MONEY_PATTERN = "^[1-9][0-9]{0,17}$";
 const OPTIONAL_MONEY_PATTERN = "^(0|[1-9][0-9]{0,17})$";
+const ACCOUNT_PATTERN = "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
 const MAX_COMPREHENSION_EXPANSIONS = 256;
 const NONE_SENTINEL = "__hsx_none__";
 const actionClauseBySpelling = new Map(udlClauseVocabulary
@@ -43,6 +44,26 @@ export function checkGeneralProgram(program, options = {}) {
     const ports = new Map(program.decls
         .filter((decl) => decl.kind === "port")
         .map((decl) => [decl.name.name, decl]));
+    const checkedPorts = new Set();
+    const checkPortDeclarations = (declared, knownParties) => {
+        for (const port of declared.values()) {
+            if (checkedPorts.has(port))
+                continue;
+            checkedPorts.add(port);
+            const allowed = entry(port.body, "allowed")?.value;
+            for (const item of allowed?.kind === "list"
+                ? allowed.items
+                : allowed
+                    ? [allowed]
+                    : []) {
+                const party = nameText(item);
+                if (knownParties.has(party))
+                    continue;
+                report("HSX1024", item.span, `decision port ${port.name.name} allows undeclared party ${party}; declare the party before using it`, `declare party ${party} with its party kind before using it in this port`);
+            }
+        }
+    };
+    checkPortDeclarations(ports, parties);
     const assetSubjects = program.decls
         .filter((decl) => decl.kind === "asset")
         .map((decl) => ({
@@ -89,16 +110,17 @@ export function checkGeneralProgram(program, options = {}) {
         });
     }
     const compositionDeclarations = program.decls.filter((declaration) => declaration.kind === "use" || declaration.kind === "expose");
-    const authoredInstrumentDeclarations = program.decls.filter((declaration) => declaration.kind === "instrument" ||
-        declaration.kind === "instrument_apply");
-    if (options.publishedCatalog &&
-        (compositionDeclarations.length > 0 ||
-            authoredInstrumentDeclarations.length === 0)) {
-        return checkPublishedProgram(program, options.publishedCatalog, header, subjects, diagnostics, report);
-    }
-    for (const declaration of compositionDeclarations) {
-        report("HSX1018", declaration.span, "this compiler host did not supply a published instrument catalog", "pass the canonical UDL catalog as the publishedCatalog compile option");
+    if (!options.publishedCatalog) {
+        for (const declaration of compositionDeclarations) {
+            report("HSX1018", declaration.span, "this compiler host did not supply a published instrument catalog", "pass the canonical UDL catalog as the publishedCatalog compile option");
+        }
     }
+    const catalogById = options.publishedCatalog
+        ? new Map(options.publishedCatalog.instruments.map((instrument) => [
+            instrument.id,
+            instrument,
+        ]))
+        : undefined;
     const aliases = new Map(program.decls
         .filter((decl) => decl.kind === "type")
         .map((decl) => [decl.name.name, decl.value]));
@@ -115,6 +137,8 @@ export function checkGeneralProgram(program, options = {}) {
             templates.set(decl.name.name, decl);
     }
     const concrete = [];
+    const reachedPorts = new Set();
+    const droppedPorts = new Set();
     const scopedDeclarations = (declarationScope) => {
         const scopedAliases = new Map(aliases);
         const scopedConstants = resolveConstants([
@@ -135,6 +159,7 @@ export function checkGeneralProgram(program, options = {}) {
                 scopedTemplates.set(local.name.name, local);
             }
         }
+        checkPortDeclarations(scopedPorts, scopedParties);
         checkConstants(declarationScope, scopedAliases, diagnostics);
         return {
             aliases: scopedAliases,
@@ -149,13 +174,25 @@ export function checkGeneralProgram(program, options = {}) {
             !decl.hasParameterList &&
             decl.typeParameters.length === 0) {
             const scoped = scopedDeclarations(decl.declarationScope ?? []);
-            concrete.push({
+            const values = new Map(scoped.constants);
+            const dependencies = new Map();
+            const shapes = new Map();
+            for (const [name, port] of scoped.ports) {
+                const reference = {
+                    kind: "port_ref",
+                    name: port.name,
+                    span: port.span,
+                };
+                values.set(name, reference);
+                bindPortCompileValues(values, name, reference, scoped.ports, diagnostics, scoped.aliases, shapes, dependencies);
+            }
+            const selected = selectCompileTimeRows(decl.body, values, diagnostics, dependencies);
+            const body = expandComprehensions(selected, diagnostics, values, dependencies);
+            concrete.push(...bindActionPorts(constructedInstruments(decl.name, body, diagnostics), scoped.ports, reachedPorts).map((candidate) => ({
+                ...candidate,
                 aliases: scoped.aliases,
-                body: substituteExpr(decl.body, scoped.constants),
-                generatedPrefix: false,
-                name: decl.name,
                 parties: scoped.parties,
-            });
+            })));
         }
         if (decl.kind !== "instrument_apply")
             continue;
@@ -174,18 +211,31 @@ export function checkGeneralProgram(program, options = {}) {
             report("HSX1001", application.callee.span, `instrument function ${callee} is not bound by this module graph`, `import ${callee} from its module or declare it before instantiation`);
             continue;
         }
-        const body = instantiate(template, application, diagnostics, decl.name, scoped.ports, scoped.parties, scoped.aliases, scoped.constants);
+        const boundPorts = new Map();
+        const body = instantiate(template, application, diagnostics, decl.name, scoped.ports, scoped.parties, scoped.aliases, scoped.constants, boundPorts);
         if (body) {
+            const applicationPorts = new Set();
             const merged = decl.metadata
                 ? mergeApplicationMetadata(body, decl.metadata, diagnostics)
                 : body;
-            concrete.push(...constructedInstruments(decl.name, merged, diagnostics).map((candidate) => ({
+            concrete.push(...bindActionPorts(constructedInstruments(decl.name, merged, diagnostics), boundPorts, applicationPorts).map((candidate) => ({
                 ...candidate,
                 aliases: scoped.aliases,
                 parties: scoped.parties,
             })));
+            for (const port of boundPorts.values()) {
+                if (applicationPorts.has(port))
+                    reachedPorts.add(port);
+                else
+                    droppedPorts.add(port);
+            }
         }
     }
+    for (const port of checkedPorts) {
+        if (reachedPorts.has(port) && !droppedPorts.has(port))
+            continue;
+        report("HSX1024", port.name.span, `wired decision port ${port.name.name} reaches no action`, `carry ${port.name.name}'s condition into the action it authorizes`);
+    }
     const allocated = allocateGeneratedPrefixes(concrete);
     const instruments = [];
     const ids = new Set();
@@ -195,11 +245,18 @@ export function checkGeneralProgram(program, options = {}) {
             continue;
         }
         ids.add(candidate.name.name);
+        if (catalogById?.has(candidate.name.name)) {
+            report("HSX1022", candidate.name.span, `authored instrument ${candidate.name.name} collides with published catalog instrument`, "rename the authored instrument to avoid colliding with the published catalog");
+            continue;
+        }
         const expandedBody = expandComprehensions(candidate.body, diagnostics);
-        const checked = checkInstrument(candidate.name, expandedBody, candidate.parties, candidate.aliases, diagnostics);
+        const checked = checkInstrument(candidate.name, expandedBody, candidate.parties, candidate.ports, candidate.aliases, diagnostics);
         if (checked)
             instruments.push(checked);
     }
+    if (options.publishedCatalog) {
+        return checkPublishedProgram(program, options.publishedCatalog, header, subjects, instruments, diagnostics, report);
+    }
     crossInstrumentReferenceDiagnostics(instruments, diagnostics);
     if (header &&
         instruments.length === 0 &&
@@ -220,25 +277,22 @@ export function checkGeneralProgram(program, options = {}) {
     };
     return { diagnostics, program: typed };
 }
-function checkPublishedProgram(program, catalog, header, authoredSubjects, diagnostics, report) {
-    if (!header) {
-        return { diagnostics };
-    }
-    if (!header.title || header.title.value.length === 0) {
-        report("HSX1015", header.span, `composed program ${header.name.name} needs a product title`, 'write the title after the product id, like `program product_name "Product title"`');
-    }
-    if (header.name.name.length > 60) {
-        report("HSX1015", header.name.span, "a composed program product id is at most 60 characters", "shorten the product id without changing its snake_case spelling");
-    }
-    if ((header.title?.value.length ?? 0) > 80) {
-        report("HSX1015", header.title?.span ?? header.span, "a composed program title is at most 80 characters", "shorten the product title to 80 characters or fewer");
-    }
-    const authoredInstruments = program.decls.filter((decl) => decl.kind === "instrument" || decl.kind === "instrument_apply");
-    for (const declaration of authoredInstruments) {
-        report("HSX1022", declaration.span, "a composed program cannot author an instrument", "publish the instrument in the catalog, then select it with use");
+function checkPublishedProgram(program, catalog, header, authoredSubjects, authoredInstruments, diagnostics, report) {
+    const compositionDeclarations = program.decls.filter((decl) => decl.kind === "use" || decl.kind === "expose");
+    if (header &&
+        (compositionDeclarations.length > 0 || authoredInstruments.length === 0)) {
+        if (!header.title || header.title.value.length === 0) {
+            report("HSX1015", header.span, `composed program ${header.name.name} needs a product title`, 'write the title after the product id, like `program product_name "Product title"`');
+        }
+        if (header.name.name.length > 60) {
+            report("HSX1015", header.name.span, "a composed program product id is at most 60 characters", "shorten the product id without changing its snake_case spelling");
+        }
+        if ((header.title?.value.length ?? 0) > 80) {
+            report("HSX1015", header.title?.span ?? header.span, "a composed program title is at most 80 characters", "shorten the product title to 80 characters or fewer");
+        }
     }
     const uses = program.decls.filter((decl) => decl.kind === "use");
-    if (uses.length === 0) {
+    if (header && uses.length === 0 && authoredInstruments.length === 0) {
         report("HSX1016", header.span, `composed program ${header.name.name} uses no published instruments`, "add at least one `use published_instrument` declaration");
     }
     const catalogById = new Map(catalog.instruments.map((instrument) => [instrument.id, instrument]));
@@ -261,6 +315,7 @@ function checkPublishedProgram(program, catalog, header, authoredSubjects, diagn
     const selected = publishedInstrumentClosure(uses, catalogById);
     const selectedById = new Map(selected.map((entry) => [entry.instrument.id, entry]));
     const exposures = program.decls.filter((decl) => decl.kind === "expose");
+    const authoredById = new Map(authoredInstruments.map((instrument) => [instrument.id, instrument]));
     const publicNames = new Map();
     const exposedTargets = new Map();
     for (const exposure of exposures) {
@@ -268,8 +323,11 @@ function checkPublishedProgram(program, catalog, header, authoredSubjects, diagn
         const explicitlyUsed = useById.has(exposure.instrument.name);
         const instrument = selectedById.get(exposure.instrument.name)?.instrument;
         const action = instrument?.actions[exposure.action.name];
-        if (!explicitlyUsed || !instrument || !action) {
-            report("HSX1021", exposure.span, `${target} is not an action on an explicitly used published instrument`, "add the matching use declaration and choose one of that instrument's actions");
+        const authoredInstrument = authoredById.get(exposure.instrument.name);
+        const authoredAction = authoredInstrument?.actions.find((candidate) => candidate.name === exposure.action.name);
+        if ((!explicitlyUsed || !instrument || !action) &&
+            (!authoredInstrument || !authoredAction)) {
+            report("HSX1021", exposure.span, `${target} is not an action on an explicitly used published instrument or authored instrument`, "add the matching use declaration and choose one of that instrument's actions");
             continue;
         }
         if (!CAMEL_CASE.test(exposure.publicName.name)) {
@@ -287,10 +345,44 @@ function checkPublishedProgram(program, catalog, header, authoredSubjects, diagn
         publicNames.set(exposure.publicName.name, exposure);
         exposedTargets.set(target, exposure);
     }
+    const updatedAuthoredInstruments = authoredInstruments.map((authoredInstrument) => {
+        const instrumentExposures = exposures.filter((exposure) => exposure.instrument.name === authoredInstrument.id);
+        if (instrumentExposures.length === 0)
+            return authoredInstrument;
+        const exposureByAction = new Map(instrumentExposures.map((exposure) => [exposure.action.name, exposure]));
+        return {
+            ...authoredInstrument,
+            actions: authoredInstrument.actions.map((action) => {
+                const exposure = exposureByAction.get(action.name);
+                if (!exposure)
+                    return action;
+                return {
+                    ...action,
+                    origin: exposure.span,
+                    slots: {
+                        ...action.slots,
+                        publicAction: exposure.publicName.name,
+                    },
+                };
+            }),
+        };
+    });
+    const publishedInstruments = selected.map(({ instrument, origin }) => {
+        const projected = projectedPublishedInstrument(instrument, exposures);
+        return typedPublishedInstrument(projected, origin, exposures.filter((exposure) => exposure.instrument.name === instrument.id), catalog.instruments);
+    });
+    const instruments = [...publishedInstruments, ...updatedAuthoredInstruments];
+    crossInstrumentReferenceDiagnostics(instruments, diagnostics);
+    if (header &&
+        instruments.length === 0 &&
+        !diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+        report("HSX1502", header.span, `program ${header.name.name} emits no instruments`, "declare or instantiate at least one instrument");
+    }
     const referencedSubjectKinds = new Set(selected.flatMap(({ instrument }) => instrument.subject?.kinds ?? []));
+    const defaultSpan = uses[0]?.span ?? header?.span ?? program.span;
     const catalogSubjects = catalog.subjects
         .filter((subject) => referencedSubjectKinds.has(subject.kind))
-        .map((subject) => typedPublishedSubject(subject, uses[0]?.span ?? header.span));
+        .map((subject) => typedPublishedSubject(subject, defaultSpan));
     const catalogSubjectKinds = new Set(catalogSubjects.map((subject) => subject.kind));
     for (const subject of authoredSubjects) {
         if (!catalogSubjectKinds.has(subject.kind))
@@ -300,19 +392,18 @@ function checkPublishedProgram(program, catalog, header, authoredSubjects, diagn
     if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
         return { diagnostics };
     }
+    const module = program.decls.find((decl) => decl.kind === "module");
+    const name = header?.name.name ?? module?.name.parts.at(-1)?.name ?? "module";
     const typed = {
-        instruments: selected.map(({ instrument, origin }) => {
-            const projected = projectedPublishedInstrument(instrument, exposures);
-            return typedPublishedInstrument(projected, origin, exposures.filter((exposure) => exposure.instrument.name === instrument.id));
-        }),
+        instruments,
         kind: "typed_program",
-        name: header.name.name,
+        name,
         origin: program.span,
         subjects: [
             ...catalogSubjects,
             ...authoredSubjects.filter((subject) => !catalogSubjectKinds.has(subject.kind)),
         ],
-        title: header.title?.value ?? sentenceCase(header.name.name),
+        title: header?.title?.value ?? sentenceCase(name),
     };
     return { diagnostics, program: typed };
 }
@@ -390,7 +481,7 @@ function publishedInstrumentDependencies(instrument, idByPrefix) {
     found.delete(instrument.id);
     return [...found];
 }
-function typedPublishedInstrument(source, origin, exposures) {
+function typedPublishedInstrument(source, origin, exposures, catalog) {
     const exposureByAction = new Map(exposures.map((exposure) => [exposure.action.name, exposure]));
     const { actionOrder, actions, fields, id: _id, ...slots } = structuredClone(source);
     const requiredFields = new Set(source.required);
@@ -412,7 +503,7 @@ function typedPublishedInstrument(source, origin, exposures) {
             origin,
             required: requiredFields.has(name),
             schema,
-            type: { kind: "unknown" },
+            type: publishedFieldType(schema, catalog),
         })),
         id: source.id,
         origin,
@@ -422,6 +513,25 @@ function typedPublishedInstrument(source, origin, exposures) {
         },
     };
 }
+/** Recover the semantic types retained by UDL before checking mixed relations. */
+function publishedFieldType(schema, catalog) {
+    if (schema.type === "integer")
+        return { kind: "integer" };
+    if (schema.type === "boolean")
+        return { kind: "boolean" };
+    if (schema.type !== "string")
+        return { kind: "unknown" };
+    if (schema.pattern === MONEY_PATTERN ||
+        schema.pattern === OPTIONAL_MONEY_PATTERN) {
+        const currency = schema["x-hyperscale-currency"];
+        return typeof currency === "string"
+            ? { currency, kind: "money" }
+            : { kind: "money" };
+    }
+    const target = catalog.find((instrument) => schema.pattern ===
+        `^${instrument.idPrefix}_(sandbox|live)_[a-z0-9]{8,64}$`);
+    return target ? { kind: "ref", target: target.id } : { kind: "text" };
+}
 function typedPublishedSubject(subject, origin) {
     return {
         declaredValue: subject.declaredValue,
@@ -441,6 +551,7 @@ const applicationMetadataKeys = new Set([
     "action",
     "agent_description",
     "description",
+    "journeys",
     "nav",
     "navigation",
     "summary",
@@ -452,6 +563,7 @@ const applicationMetadataKeys = new Set([
 const applicationActionMetadataKeys = new Set([
     "agent_description",
     "description",
+    "examples",
     "public",
     "public_action",
     "summary",
@@ -532,6 +644,71 @@ function mergeApplicationMetadata(body, metadata, diagnostics) {
     }
     return { ...body, entries };
 }
+function bindActionPorts(candidates, bindings, reached) {
+    const declarations = new Map([...bindings.values()].map((port) => [port.name.name, port]));
+    return candidates.map((candidate) => {
+        const ports = new Map();
+        const entries = candidate.body.entries.map((row) => {
+            if (row.key.name !== "action" || row.value.kind !== "block")
+                return row;
+            const action = row.qualifiers[0]?.name;
+            if (!action)
+                return row;
+            const declared = (row.conditionPorts ?? []).flatMap((name) => {
+                const port = declarations.get(name);
+                if (!port)
+                    return [];
+                reached.add(port);
+                return [port];
+            });
+            if (!declared.length)
+                return row;
+            ports.set(action, declared);
+            if (entry(row.value, "port"))
+                return row;
+            const source = declared[0];
+            const allowed = entry(source.body, "allowed")?.value;
+            const span = source.span;
+            return {
+                ...row,
+                value: {
+                    ...row.value,
+                    entries: [
+                        ...row.value.entries,
+                        {
+                            key: { kind: "ident", name: "port", span },
+                            qualifiers: [],
+                            span,
+                            value: {
+                                kind: "block",
+                                span,
+                                entries: [
+                                    {
+                                        key: {
+                                            kind: "ident",
+                                            name: "allowed_parties",
+                                            span,
+                                        },
+                                        qualifiers: [],
+                                        span,
+                                        value: allowed?.kind === "list"
+                                            ? allowed
+                                            : {
+                                                kind: "list",
+                                                span,
+                                                items: allowed ? [allowed] : [],
+                                            },
+                                    },
+                                ],
+                            },
+                        },
+                    ],
+                },
+            };
+        });
+        return { ...candidate, body: { ...candidate.body, entries }, ports };
+    });
+}
 function constructedInstruments(rootName, body, diagnostics) {
     const expanded = expandComprehensions(body, diagnostics);
     const construction = entry(expanded, "instruments");
@@ -700,7 +877,9 @@ function validateMoneyLiteral(decl, diagnostics) {
         span: decl.value.span,
     });
 }
-function instantiate(template, application, diagnostics, instrumentName, ports, parties, aliases, constants) {
+function instantiate(template, application, diagnostics, instrumentName, ports, parties, aliases, constants, boundPorts) {
+    const loweredPortShapes = new Map();
+    const portDependencies = new Map();
     const partyKeyedParameters = partyKeyedBlockParameters(template, aliases);
     const named = new Map();
     const positional = [];
@@ -768,9 +947,11 @@ function instantiate(template, application, diagnostics, instrumentName, ports,
     });
     for (const [name, value] of named)
         values.set(name, value);
+    const resolvedArgs = [];
     let position = 0;
     for (const parameter of template.parameters) {
         const value = named.get(parameter.name.name) ?? positional[position++];
+        resolvedArgs.push({ parameter, value });
         if (!value) {
             if (optionalInner(parameter.type)) {
                 values.set(parameter.name.name, booleanExpr(false, parameter.span));
@@ -845,11 +1026,17 @@ function instantiate(template, application, diagnostics, instrumentName, ports,
         else {
             values.set(parameter.name.name, value);
         }
-        if (value.kind === "port_ref") {
-            bindPortCompileValues(values, parameter.name.name, value, ports, diagnostics);
+    }
+    for (const { parameter, value } of resolvedArgs) {
+        if (value?.kind === "port_ref") {
+            const port = ports.get(value.name.name);
+            if (port)
+                boundPorts.set(parameter.name.name, port);
+            bindPortCompileValues(values, parameter.name.name, value, ports, diagnostics, aliases, loweredPortShapes, portDependencies);
         }
     }
-    const selected = selectCompileTimeRows(template.body, values, diagnostics);
+    checkClaimAmountPortField(resolvedArgs, ports, aliases, diagnostics);
+    const selected = selectCompileTimeRows(template.body, values, diagnostics, portDependencies);
     const dependencyDiagnosticStart = diagnostics.length;
     for (const [name, parameter] of missingOptional) {
         if (!referencesIdentifier(selected, name, values))
@@ -867,7 +1054,7 @@ function instantiate(template, application, diagnostics, instrumentName, ports,
     }
     if (diagnostics.length > dependencyDiagnosticStart)
         return undefined;
-    const body = substituteExpr(selected, values);
+    const body = expandComprehensions(selected, diagnostics, values, portDependencies);
     return {
         ...body,
         entries: body.entries.map((row) => {
@@ -1039,7 +1226,231 @@ function partyKeyedBlockParameters(template, aliases) {
         nonPartyKeys.get(parameter) ?? new Set(),
     ]));
 }
-function bindPortCompileValues(values, binding, value, ports, diagnostics) {
+function shapeTypeText(expr) {
+    if (expr.kind === "ident")
+        return expr.name;
+    if (expr.kind === "block")
+        return "block";
+    if (expr.kind === "list")
+        return "list";
+    if (expr.kind === "number")
+        return expr.raw;
+    if (expr.kind === "string")
+        return `"${expr.value}"`;
+    if (expr.kind === "boolean")
+        return String(expr.value);
+    if (expr.kind === "call") {
+        const args = expr.args.map(shapeTypeText).join(", ");
+        return `${expr.callee.name}(${args})`;
+    }
+    if (expr.kind === "type_apply") {
+        const args = expr.args.map(shapeTypeText).join(", ");
+        return `${expr.callee.name}<${args}>`;
+    }
+    return nameText(expr);
+}
+function lowerPortShapeField(port, row, aliases, diagnostics) {
+    const type = typeOf(row.value, aliases);
+    if (![
+        "text",
+        "money",
+        "date",
+        "integer",
+        "boolean",
+        "account",
+        "ref",
+        "bps",
+        "percent",
+    ].includes(type.kind) ||
+        ((type.kind === "money" || type.kind === "account") &&
+            (!type.currency || !CURRENCY.test(type.currency)))) {
+        diagnostics.push({
+            code: "HSX1025",
+            fix: `declare ${row.key.name} as text, money(CUR), date, integer, boolean, account(CUR), ref<instrument_id>, id(instrument_id), bps, or percent`,
+            message: `decision port ${port.name.name} shape field ${row.key.name} has unknown type ${shapeTypeText(row.value)}`,
+            severity: "error",
+            span: row.value.span,
+        });
+        return undefined;
+    }
+    const extras = {};
+    if (type.kind === "text") {
+        extras.description =
+            "Required decision reference retained in the operation receipt";
+        extras.max_length = 180;
+        extras.min_length = 1;
+    }
+    else if (type.kind === "money") {
+        extras.description = `Decided amount in ${type.currency} minor units`;
+    }
+    else if (type.kind === "ref") {
+        extras.max_length = 180;
+        extras.min_length = 1;
+        if (type.target)
+            extras.pattern = `^${prefixFor(type.target)}_(sandbox|live)_[a-z0-9]{8,64}$`;
+    }
+    else if (type.kind === "account") {
+        extras.pattern = ACCOUNT_PATTERN;
+    }
+    const scalarEntries = (values) => Object.entries(values).map(([name, value]) => ({
+        key: { kind: "ident", name, span: row.span },
+        qualifiers: [],
+        span: row.span,
+        value: typeof value === "number"
+            ? { kind: "number", raw: String(value), span: row.span }
+            : { kind: "string", value: String(value), span: row.span },
+    }));
+    // Port inputs require every key, but a caller-decided amount may be zero.
+    const field = lowerField({
+        ...row,
+        value: {
+            kind: "block",
+            span: row.span,
+            entries: [
+                {
+                    key: { kind: "ident", name: "type", span: row.span },
+                    qualifiers: [],
+                    span: row.span,
+                    value: row.value,
+                },
+                {
+                    key: { kind: "ident", name: "optional", span: row.span },
+                    qualifiers: [],
+                    span: row.span,
+                    value: { kind: "boolean", value: true, span: row.span },
+                },
+                ...scalarEntries(extras),
+            ],
+        },
+    }, aliases, diagnostics);
+    const schema = type.kind === "text"
+        ? {
+            type: field.schema.type,
+            description: field.schema.description,
+            ...field.schema,
+        }
+        : field.schema;
+    return {
+        key: row.key,
+        qualifiers: [],
+        span: row.span,
+        value: {
+            kind: "block",
+            span: row.span,
+            entries: scalarEntries(schema),
+        },
+    };
+}
+function lowerPortShape(port, rawShape, aliases, diagnostics) {
+    if (rawShape.kind !== "block") {
+        diagnostics.push({
+            code: "HSX1025",
+            fix: "declare shape as a block of fields, like shape { note: text; }",
+            message: `decision port ${port.name.name} shape must be a block`,
+            severity: "error",
+            span: rawShape.span,
+        });
+        return { entries: [], kind: "block", span: rawShape.span };
+    }
+    const entries = [];
+    const names = new Set();
+    for (const row of rawShape.entries) {
+        if (names.has(row.key.name)) {
+            diagnostics.push({
+                code: "HSX1004",
+                fix: `keep one ${row.key.name} field in decision port ${port.name.name}`,
+                message: `decision port ${port.name.name} shape field ${row.key.name} is declared twice`,
+                severity: "error",
+                span: row.key.span,
+            });
+            continue;
+        }
+        names.add(row.key.name);
+        const lowered = lowerPortShapeField(port, row, aliases, diagnostics);
+        if (lowered)
+            entries.push(lowered);
+    }
+    return {
+        entries,
+        kind: "block",
+        span: rawShape.span,
+    };
+}
+function checkClaimAmountPortField(resolvedArgs, ports, aliases, diagnostics) {
+    for (const { value } of resolvedArgs) {
+        if (value?.kind !== "block")
+            continue;
+        const fieldEntry = entry(value, "field");
+        const boundEntry = entry(value, "bound");
+        if (!fieldEntry || !boundEntry)
+            continue;
+        const claimFieldName = fieldEntry.value.kind === "ident"
+            ? fieldEntry.value.name
+            : fieldEntry.value.kind === "string"
+                ? fieldEntry.value.value
+                : undefined;
+        const boundFieldName = boundEntry.value.kind === "ident"
+            ? boundEntry.value.name
+            : boundEntry.value.kind === "string"
+                ? boundEntry.value.value
+                : undefined;
+        if (!claimFieldName || !boundFieldName)
+            continue;
+        const boundArg = resolvedArgs.find((arg) => (arg.value?.kind === "binding" &&
+            arg.value.name.name === boundFieldName) ||
+            arg.parameter.name.name === boundFieldName);
+        const boundTypeExpr = boundArg?.value?.kind === "binding"
+            ? boundArg.value.type
+            : boundArg?.value;
+        if (!boundTypeExpr)
+            continue;
+        const boundType = typeOf(boundTypeExpr, aliases);
+        if (boundType.kind !== "money")
+            continue;
+        const portArg = resolvedArgs.find((arg) => arg.parameter.name.name === "claim");
+        if (portArg?.value?.kind !== "port_ref")
+            continue;
+        const portDecl = ports.get(portArg.value.name.name);
+        if (!portDecl)
+            continue;
+        const shapeExpr = entry(portDecl.body, "shape")?.value;
+        if (shapeExpr?.kind !== "block")
+            continue;
+        const shapeField = entry(shapeExpr, claimFieldName);
+        if (!shapeField) {
+            diagnostics.push({
+                code: "HSX1011",
+                fix: `add ${claimFieldName}: money(${boundType.currency ?? "CUR"}) to the shape of decision port ${portDecl.name.name}`,
+                message: `decision port ${portDecl.name.name} shape lacks claim field ${claimFieldName}`,
+                severity: "error",
+                span: portArg.value.span,
+            });
+            continue;
+        }
+        const actualType = typeOf(shapeField.value, aliases);
+        if (actualType.kind !== "money") {
+            diagnostics.push({
+                code: "HSX1104",
+                fix: `pass money<${boundType.currency ?? "CUR"}> to ${shapeField.key.name}`,
+                message: `${shapeField.key.name} needs money<${boundType.currency ?? "CUR"}> but receives ${argumentWords(shapeField.value, aliases)}`,
+                severity: "error",
+                span: shapeField.value.span,
+            });
+        }
+        else if (actualType.currency &&
+            boundType.currency &&
+            actualType.currency !== boundType.currency) {
+            diagnostics.push({
+                code: "HSX1101",
+                fix: `pass money<${boundType.currency}> to ${shapeField.key.name}`,
+                message: `${shapeField.key.name} needs money<${boundType.currency}> but receives money<${actualType.currency}>`,
+                severity: "error",
+                span: shapeField.value.span,
+            });
+        }
+    }
+}
+function bindPortCompileValues(values, binding, value, ports, diagnostics, aliases = new Map(), loweredPortShapes = new Map(), dependencies = new Map()) {
     const port = ports.get(value.name.name);
     if (!port) {
         diagnostics.push({
@@ -1051,14 +1462,36 @@ function bindPortCompileValues(values, binding, value, ports, diagnostics) {
         });
         return;
     }
-    const allowed = port ? entry(port.body, "allowed")?.value : undefined;
-    const shape = entry(port.body, "shape")?.value ?? {
-        entries: [],
-        kind: "block",
-        span: port.body.span,
-    };
-    if (allowed)
-        values.set(`${binding}_allowed`, allowed);
+    for (const key of [binding, `${binding}_allowed`, `${binding}_fields`]) {
+        dependencies.set(key, [port.name.name]);
+    }
+    const allowed = entry(port.body, "allowed")?.value;
+    let shape = loweredPortShapes.get(value.name.name);
+    if (!shape) {
+        const rawShape = entry(port.body, "shape")?.value ?? {
+            entries: [],
+            kind: "block",
+            span: port.body.span,
+        };
+        const shapeDiagnostics = [];
+        shape = lowerPortShape(port, rawShape, aliases, shapeDiagnostics);
+        for (const diagnostic of shapeDiagnostics) {
+            if (!diagnostics.some((prior) => prior.code === diagnostic.code &&
+                prior.span === diagnostic.span &&
+                prior.message === diagnostic.message))
+                diagnostics.push(diagnostic);
+        }
+        loweredPortShapes.set(value.name.name, shape);
+    }
+    const normalizedAllowed = allowed?.kind === "ident"
+        ? {
+            items: [allowed],
+            kind: "list",
+            span: allowed.span,
+        }
+        : allowed;
+    if (normalizedAllowed)
+        values.set(`${binding}_allowed`, normalizedAllowed);
     values.set(`${binding}_fields`, shape);
     if (value.within)
         values.set(`${binding}_within`, value.within);
@@ -1264,14 +1697,54 @@ function argumentWords(expression, aliases) {
 function booleanExpr(value, span) {
     return { kind: "boolean", span, value };
 }
-function selectCompileTimeRows(block, values, diagnostics) {
+function selectedControls(value) {
+    if (value.kind !== "block")
+        return [];
+    return value.entries.flatMap((row) => [
+        ...(row.conditionPorts ?? []),
+        ...selectedControls(row.value),
+    ]);
+}
+// Retain dependencies before compile-time evaluation erases identifiers.
+function expressionPorts(value, dependencies) {
+    if (!value || typeof value !== "object")
+        return [];
+    if (Array.isArray(value))
+        return [
+            ...new Set(value.flatMap((item) => expressionPorts(item, dependencies))),
+        ];
+    const node = value;
+    const found = new Set(node.conditionPorts ?? []);
+    if (node.kind === "ident" && typeof node.name === "string") {
+        for (const port of dependencies.get(node.name.replace(/^\[|\]$/g, "")) ??
+            [])
+            found.add(port);
+    }
+    if (node.kind === "string" && typeof node.value === "string") {
+        for (const match of node.value.matchAll(/\{([A-Za-z][A-Za-z0-9_]*)\}/g)) {
+            for (const port of dependencies.get(match[1]) ?? [])
+                found.add(port);
+        }
+    }
+    for (const [key, child] of Object.entries(node)) {
+        if (key === "span" || key === "conditionPorts")
+            continue;
+        for (const port of expressionPorts(child, dependencies))
+            found.add(port);
+    }
+    return [...found];
+}
+function selectCompileTimeRows(block, values, diagnostics, dependencies = new Map(), controls = []) {
     const entries = [];
     const locals = new Map(values);
+    const localDependencies = new Map(dependencies);
     for (const row of block.entries) {
         if (row.key.name === "let") {
             const binding = row.qualifiers[0];
-            if (binding)
+            if (binding) {
+                localDependencies.set(binding.name, expressionPorts(row.value, localDependencies));
                 locals.set(binding.name, substituteExpr(row.value, locals));
+            }
             entries.push(row);
             continue;
         }
@@ -1305,12 +1778,34 @@ function selectCompileTimeRows(block, values, diagnostics) {
         if (row.key.name !== "when" &&
             row.key.name !== "when_not" &&
             row.key.name !== "when_eq") {
-            entries.push({
-                ...row,
-                value: row.value.kind === "block" && !row.iteration
-                    ? selectCompileTimeRows(row.value, locals, diagnostics)
-                    : row.value,
-            });
+            const value = row.value.kind === "block" && !row.iteration
+                ? selectCompileTimeRows(row.value, locals, diagnostics, localDependencies, controls)
+                : row.value;
+            const conditionPorts = row.key.name === "action"
+                ? [
+                    ...new Set([
+                        ...(value.kind === "block" && entry(value, "due")
+                            ? []
+                            : controls),
+                        ...row.qualifiers
+                            .filter((qualifier) => qualifier.name.startsWith("["))
+                            .flatMap((qualifier) => expressionPorts(qualifier, localDependencies)),
+                        ...expressionPorts(value.kind === "block"
+                            ? entry(value, "port")?.value
+                            : undefined, localDependencies),
+                        ...expressionPorts(value.kind === "block"
+                            ? entry(value, "input")?.value
+                            : undefined, localDependencies),
+                        ...expressionPorts(value.kind === "block"
+                            ? entry(value, "capture_input", "captureInput")?.value
+                            : undefined, localDependencies),
+                        ...(value.kind === "block" && entry(value, "due")
+                            ? []
+                            : selectedControls(value)),
+                    ]),
+                ]
+                : controls;
+            entries.push({ ...row, conditionPorts, value });
             continue;
         }
         const subject = row.qualifiers[0];
@@ -1336,7 +1831,12 @@ function selectCompileTimeRows(block, values, diagnostics) {
             continue;
         }
         if (include) {
-            entries.push(...selectCompileTimeRows(row.value, locals, diagnostics).entries);
+            entries.push(...selectCompileTimeRows(row.value, locals, diagnostics, localDependencies, [
+                ...new Set([
+                    ...controls,
+                    ...(subject ? expressionPorts(subject, localDependencies) : []),
+                ]),
+            ]).entries);
         }
     }
     return { ...block, entries };
@@ -1589,11 +2089,12 @@ function nameText(value) {
         return `${value.owner.name}.${value.member.name}`;
     return "invalid_compile_time_name";
 }
-function expandComprehensions(block, diagnostics) {
+function expandComprehensions(block, diagnostics, values = new Map(), dependencies = new Map()) {
     const budget = { used: 0 };
-    const expand = (current, inherited = new Map()) => {
+    const expand = (current, inherited = new Map(), inheritedDependencies = dependencies) => {
         const entries = [];
         const locals = new Map(inherited);
+        const localDependencies = new Map(inheritedDependencies);
         for (const row of current.entries) {
             if (row.key.name === "let") {
                 const binding = row.qualifiers[0];
@@ -1607,6 +2108,7 @@ function expandComprehensions(block, diagnostics) {
                     });
                     continue;
                 }
+                localDependencies.set(binding.name, expressionPorts(row.value, localDependencies));
                 locals.set(binding.name, substituteExpr(row.value, locals));
                 continue;
             }
@@ -1622,7 +2124,7 @@ function expandComprehensions(block, diagnostics) {
                 if (row.key.name === "when_not")
                     include = !include;
                 if (include && row.value.kind === "block") {
-                    entries.push(...expand(row.value, locals).entries);
+                    entries.push(...expand(row.value, locals, localDependencies).entries);
                 }
                 continue;
             }
@@ -1641,8 +2143,8 @@ function expandComprehensions(block, diagnostics) {
                 };
                 entries.push({
                     ...substituted,
-                    value: substituted.value.kind === "block"
-                        ? expand(substituted.value, locals)
+                    value: row.value.kind === "block"
+                        ? expand(row.value, locals, localDependencies)
                         : substituted.value,
                 });
                 continue;
@@ -1677,14 +2179,13 @@ function expandComprehensions(block, diagnostics) {
                     ...locals,
                     [row.iteration.binding.name, value],
                 ]);
-                const body = substituteExpr(row.value, substitutions);
-                if (body.kind === "block")
-                    entries.push(...expand(body, substitutions).entries);
+                const body = selectCompileTimeRows(row.value, substitutions, diagnostics, localDependencies, row.conditionPorts);
+                entries.push(...expand(body, substitutions, localDependencies).entries);
             }
         }
         return { ...current, entries };
     };
-    return expand(block);
+    return expand(block, values);
 }
 function finiteIterationValues(bound) {
     if (bound.kind === "call") {
@@ -1704,7 +2205,7 @@ function finiteIterationValues(bound) {
         span: bound.span,
     }));
 }
-function checkInstrument(name, body, parties, aliases, diagnostics) {
+function checkInstrument(name, body, parties, ports, aliases, diagnostics) {
     if (!SNAKE_CASE.test(name.name)) {
         diagnostics.push({
             code: "HSX1003",
@@ -1752,8 +2253,57 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
     }
     const slots = {};
     const partiesEntry = entry(body, "parties");
-    if (partiesEntry?.value.kind === "block") {
-        const roleObject = blockToObject(partiesEntry.value, new Map(), diagnostics);
+    const roleObject = blockToObject(partiesEntry?.value.kind === "block" ? partiesEntry.value : undefined, new Map(), diagnostics);
+    const partyAccounts = new Map([...parties].map((party) => [party, `${camel(party)}AccountId`]));
+    for (const [role, binding] of Object.entries(roleObject)) {
+        if (!isJsonObject(binding))
+            continue;
+        if (typeof binding.party !== "string" ||
+            !parties.has(binding.party) ||
+            typeof binding.account !== "string" ||
+            !endpointFields.has(binding.account)) {
+            diagnostics.push({
+                code: "HSX1024",
+                fix: "bind a declared party to a declared account field",
+                message: `party role ${role} has an invalid party/account binding`,
+                severity: "error",
+                span: partiesEntry?.span ?? name.span,
+            });
+            continue;
+        }
+        partyAccounts.set(binding.party, binding.account);
+        roleObject[role] = binding.account;
+    }
+    const decisionRoles = new Map();
+    const inferredDecisionFields = new Set();
+    // Decision authority needs an identity binding, even when no money moves
+    // through that party. Reuse the same account binding as economic roles.
+    for (const action of body.entries) {
+        if (action.key.name !== "action" || action.value.kind !== "block")
+            continue;
+        const port = entry(action.value, "port")?.value;
+        if (port?.kind !== "block")
+            continue;
+        const allowed = entry(port, "allowed_parties", "allowedParties")?.value;
+        if (allowed?.kind !== "list")
+            continue;
+        for (const item of allowed.items) {
+            const party = nameText(item);
+            if (!parties.has(party))
+                continue;
+            const accountField = partyAccounts.get(party);
+            const existing = Object.entries(roleObject).find(([, value]) => value === party || value === accountField);
+            let role = existing?.[0] ?? party;
+            for (let suffix = 2; !existing && Object.hasOwn(roleObject, role); suffix++)
+                role = `${party}_${suffix}`;
+            if (!existing) {
+                roleObject[role] = party;
+                inferredDecisionFields.add(accountField);
+            }
+            decisionRoles.set(party, role);
+        }
+    }
+    if (Object.keys(roleObject).length > 0) {
         for (const [role, value] of Object.entries(roleObject)) {
             if (typeof value !== "string")
                 continue;
@@ -1770,11 +2320,11 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
                 if (!fieldNames.has(field)) {
                     fields.push({
                         name: field,
-                        origin: partiesEntry.span,
+                        origin: partiesEntry?.span ?? name.span,
                         required: true,
                         schema: {
                             description: `The ${value.replaceAll("_", " ")} account`,
-                            pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+                            pattern: ACCOUNT_PATTERN,
                             type: "string",
                             "x-hyperscale-reference-filter": {
                                 column: "role",
@@ -1792,8 +2342,11 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
                 fix: "bind the role to a declared party or field",
                 message: `party role refers to ${String(value)}, which is not declared`,
                 severity: "error",
-                span: partiesEntry.value.entries.find((entry) => entry.key.name === role)
-                    ?.value.span ?? partiesEntry.span,
+                span: (partiesEntry?.value.kind === "block"
+                    ? partiesEntry.value.entries
+                    : []).find((entry) => entry.key.name === role)?.value.span ??
+                    partiesEntry?.span ??
+                    name.span,
             });
         }
         slots.parties = roleObject;
@@ -1831,7 +2384,7 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
                         origin: actionEntry.span,
                         required: true,
                         schema: {
-                            pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+                            pattern: ACCOUNT_PATTERN,
                             type: "string",
                         },
                         type: { kind: "account" },
@@ -1841,14 +2394,98 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
             }
         }
     }
-    const actions = actionEntries.flatMap((candidate) => {
+    const actions = actionEntries
+        .flatMap((candidate) => {
         const actionName = candidate.qualifiers[0];
         if (!actionName || candidate.value.kind !== "block")
             return [];
         return [
             checkAction(actionName, candidate.value, fields, name.name, endpointFields, holdDestinations, diagnostics),
         ];
-    });
+    })
+        .map((action) => {
+        const port = action.slots.port;
+        if (port === undefined ||
+            !isJsonObject(port) ||
+            !Array.isArray(port.allowedParties))
+            return action;
+        return {
+            ...action,
+            slots: {
+                ...action.slots,
+                port: {
+                    ...port,
+                    allowedParties: port.allowedParties.map((party) => typeof party === "string"
+                        ? (decisionRoles.get(party) ?? party)
+                        : party),
+                },
+            },
+        };
+    })
+        .map((action) => pinFixedCurrencyBindings(action, fields, diagnostics));
+    for (const action of actions) {
+        for (const declared of ports.get(action.name) ?? []) {
+            const allowed = entry(declared.body, "allowed")?.value;
+            const allowedItems = allowed?.kind === "list" ? allowed.items : allowed ? [allowed] : [];
+            if (allowedItems.length === 0) {
+                diagnostics.push({
+                    code: "HSX1024",
+                    fix: `declare a nonempty allowed list of declared parties on port ${declared.name.name}`,
+                    message: `wired decision port ${declared.name.name} reaches action ${action.name} without declared allowed parties`,
+                    severity: "error",
+                    span: declared.name.span,
+                });
+                continue;
+            }
+            const port = action.slots.port;
+            if (port === undefined ||
+                !isJsonObject(port) ||
+                !Array.isArray(port.allowedParties)) {
+                diagnostics.push({
+                    code: "HSX1024",
+                    fix: `emit the allowed parties of ${declared.name.name} in action ${action.name}'s port`,
+                    message: `wired decision port ${declared.name.name} reaches action ${action.name} without a decision port`,
+                    severity: "error",
+                    span: action.origin,
+                });
+                continue;
+            }
+            const allowedFields = new Set();
+            for (const item of allowedItems) {
+                const party = nameText(item);
+                const role = decisionRoles.get(party) ??
+                    Object.keys(roleObject).find((role) => roleObject[role] ===
+                        (partyAccounts.get(party) ?? `${camel(party)}AccountId`));
+                const field = role === undefined ? undefined : roleObject[role];
+                if (typeof field === "string") {
+                    allowedFields.add(field);
+                    continue;
+                }
+                if (!parties.has(party))
+                    continue;
+                diagnostics.push({
+                    code: "HSX1024",
+                    fix: `bind ${party} to an account field and use that binding in action ${action.name}'s port`,
+                    message: `decision port ${action.name} allows party ${party}, but settlement ${name.name} does not bind that party to the decision action`,
+                    severity: "error",
+                    span: item.span,
+                });
+            }
+            if (port.allowedParties.length === 0 ||
+                allowedFields.size !==
+                    new Set(port.allowedParties.map((role) => String(roleObject[String(role)]))).size ||
+                port.allowedParties.some((role) => typeof role !== "string" ||
+                    !allowedFields.has(String(roleObject[role])))) {
+                diagnostics.push({
+                    code: "HSX1024",
+                    fix: `use only the account bindings allowed by ${declared.name.name}`,
+                    message: `action ${action.name} does not preserve the allowed parties of decision port ${declared.name.name}`,
+                    severity: "error",
+                    span: action.origin,
+                });
+            }
+        }
+    }
     if (!actionNames.has("create")) {
         diagnostics.push({
             code: "HSX1504",
@@ -1911,8 +2548,43 @@ function checkInstrument(name, body, parties, aliases, diagnostics) {
     slots.summary ??= `${titleize(name.name)} instrument`;
     slots.title ??= titleize(name.name);
     linearityDiagnostics(actionEntries, diagnostics);
+    agentDescriptionDiagnostics(name, slots, actions, diagnostics);
+    if (Array.isArray(slots.required)) {
+        slots.required = [
+            ...new Set([...slots.required, ...inferredDecisionFields]),
+        ];
+    }
     return { actions, fields, id: name.name, origin: name.span, slots };
 }
+// Mirrors the catalog law agent_description_required: every action a caller
+// can reach becomes an agent tool whose description is authored, never
+// synthesized from the human-facing summary. System actions with a due clause
+// are exempt because no caller can reach them.
+function agentDescriptionDiagnostics(name, slots, actions, diagnostics) {
+    const callable = actions.filter((action) => action.slots.due === undefined);
+    if (callable.length === 0)
+        return;
+    if (slots.agentDescription === undefined) {
+        diagnostics.push({
+            code: "HSX1509",
+            fix: 'add agent_description: "..." telling an agent when to reach for this instrument',
+            message: `instrument ${name.name} exposes callable actions without an agent_description`,
+            severity: "error",
+            span: name.span,
+        });
+    }
+    for (const action of callable) {
+        if (action.slots.agentDescription !== undefined)
+            continue;
+        diagnostics.push({
+            code: "HSX1509",
+            fix: 'add agent_description: "..." telling an agent when to call this action',
+            message: `action ${action.name} of ${name.name} is callable without an agent_description`,
+            severity: "error",
+            span: action.origin,
+        });
+    }
+}
 function checkRequiredFields(value, fields, span, diagnostics) {
     const report = (message, fix) => {
         diagnostics.push({
@@ -1980,62 +2652,76 @@ function checkFields(block, aliases, diagnostics) {
             continue;
         }
         names.add(name);
-        let typeExpr = row.value;
-        let description;
-        let required = true;
-        let extra = {};
-        if (row.value.kind === "block") {
-            const typeRow = entry(row.value, "type");
-            if (typeRow)
-                typeExpr = typeRow.value;
-            const desc = entry(row.value, "description") ?? entry(row.value, "desc");
-            if (desc?.value.kind === "string")
-                description = desc.value.value;
-            const optional = entry(row.value, "optional");
-            if (optional?.value.kind === "boolean")
-                required = !optional.value.value;
-            extra = blockToObject({
-                ...row.value,
-                entries: row.value.entries.filter((item) => !["type", "description", "desc", "optional"].includes(item.key.name)),
-            }, new Map(), diagnostics);
-        }
-        const type = typeOf(typeExpr, aliases);
-        const fixedMoneyIssue = invalidFixedMoneyBinding(typeExpr);
-        if (fixedMoneyIssue) {
-            diagnostics.push({
-                code: "HSX1103",
-                fix: `write ${name} as money(SAR, 2500) with a positive safe integer in minor units`,
-                message: `field ${name} ${fixedMoneyIssue}`,
-                severity: "error",
-                span: typeExpr.span,
-            });
-        }
-        if ((typeExpr.kind === "ident" && typeExpr.name === "ref") ||
-            (type.kind === "ref" && !type.target)) {
-            diagnostics.push({
-                code: "HSX1007",
-                fix: "declare the target instrument as ref<instrument_id>",
-                message: `field ${name} declares ref without an instrument target`,
-                severity: "error",
-                span: typeExpr.span,
-            });
-        }
-        const structuralType = Object.hasOwn(extra, "items")
-            ? "array"
-            : Object.hasOwn(extra, "properties") ||
-                Object.hasOwn(extra, "additionalProperties")
-                ? "object"
-                : undefined;
-        const schema = {
-            ...schemaFor(type, required),
-            ...extra,
-            ...(structuralType ? { type: structuralType } : {}),
-            ...(description ? { description } : {}),
-        };
-        result.push({ name, origin: row.span, required, schema, type });
+        result.push(lowerField(row, aliases, diagnostics));
     }
     return result;
 }
+function lowerField(row, aliases, diagnostics) {
+    const name = camel(row.key.name);
+    let typeExpr = row.value;
+    let description;
+    let required = true;
+    let extra = {};
+    if (row.value.kind === "block") {
+        const typeRow = entry(row.value, "type");
+        if (typeRow)
+            typeExpr = typeRow.value;
+        const desc = entry(row.value, "description") ?? entry(row.value, "desc");
+        if (desc?.value.kind === "string")
+            description = desc.value.value;
+        const optional = entry(row.value, "optional");
+        if (optional?.value.kind === "boolean")
+            required = !optional.value.value;
+        extra = blockToObject({
+            ...row.value,
+            entries: row.value.entries.filter((item) => !["type", "description", "desc", "optional"].includes(item.key.name)),
+        }, new Map(), diagnostics);
+    }
+    const type = typeOf(typeExpr, aliases);
+    // Diagnostics point at the field's own type expression, not at an alias
+    // declaration that may live in an imported module.
+    const declaredSpan = typeExpr.span;
+    const seen = new Set();
+    while (typeExpr.kind === "ident" &&
+        aliases.has(typeExpr.name) &&
+        !seen.has(typeExpr.name)) {
+        seen.add(typeExpr.name);
+        typeExpr = aliases.get(typeExpr.name);
+    }
+    const fixedMoneyIssue = invalidFixedMoneyBinding(typeExpr);
+    if (fixedMoneyIssue) {
+        diagnostics.push({
+            code: "HSX1103",
+            fix: `write ${name} as money(SAR, 2500) with a positive safe integer in minor units`,
+            message: `field ${name} ${fixedMoneyIssue}`,
+            severity: "error",
+            span: declaredSpan,
+        });
+    }
+    if ((typeExpr.kind === "ident" && typeExpr.name === "ref") ||
+        (type.kind === "ref" && !type.target)) {
+        diagnostics.push({
+            code: "HSX1007",
+            fix: "declare the target instrument as ref<instrument_id>",
+            message: `field ${name} declares ref without an instrument target`,
+            severity: "error",
+            span: declaredSpan,
+        });
+    }
+    const structuralType = Object.hasOwn(extra, "items")
+        ? "array"
+        : Object.hasOwn(extra, "properties") ||
+            Object.hasOwn(extra, "additionalProperties")
+            ? "object"
+            : undefined;
+    const schema = {
+        ...schemaFor(type, required),
+        ...extra,
+        ...(structuralType ? { type: structuralType } : {}),
+        ...(description ? { description } : {}),
+    };
+    return { name, origin: row.span, required, schema, type };
+}
 function checkLifecycle(instrument, block, actions, diagnostics) {
     const statesRows = block.entries.filter((row) => row.key.name === "states");
     const initialRow = entry(block, "initial");
@@ -2139,6 +2825,18 @@ function checkAction(name, body, fields, instrumentId, endpointFields, holdDesti
             continue;
         }
         if (definition?.scope === "action") {
+            if (definition.target === "port" && row.value.kind === "block") {
+                const allowedEntry = entry(row.value, "allowed");
+                if (allowedEntry) {
+                    diagnostics.push({
+                        code: "HSX1508",
+                        fix: "Use allowed_parties: [...] inside an action-level port clause; allowed: is for top-level port declarations.",
+                        message: "action-level port clause uses allowed: instead of allowed_parties:",
+                        severity: "error",
+                        span: allowedEntry.key.span,
+                    });
+                }
+            }
             const rawValue = exprToJsonForUdlSlot(row.value, definition.target, diagnostics);
             const moveOffset = Array.isArray(slots.moves) ? slots.moves.length : 0;
             const value = definition.target === "moves"
@@ -2302,6 +3000,93 @@ function friendlyMoveRows(body) {
 function isJsonObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+/**
+ * A money<SAR> field moves SAR, whatever the caller wrote in the instance
+ * currency field. Every move of a fixed-currency amount, and every account
+ * step of an instrument whose money is fixed, binds that currency as a
+ * constant: a binding that reads one of the instrument's own text fields is
+ * pinned here, and one the compiler cannot pin (an input, a ref, or a
+ * constant naming another currency) is refused as HSX1306.
+ */
+function pinFixedCurrencyBindings(action, fields, diagnostics) {
+    const fieldByName = new Map(fields.map((field) => [field.name, field]));
+    const fixedCurrencyOf = (field) => field?.type.kind === "money" &&
+        field.type.currency &&
+        CURRENCY.test(field.type.currency)
+        ? field.type.currency
+        : undefined;
+    const fixed = new Set(fields.flatMap((field) => fixedCurrencyOf(field) ?? []));
+    // Two fixed currencies is HSX1305's refusal; one decides here, none skips.
+    const ledger = fixed.size === 1 ? [...fixed][0] : undefined;
+    if (!ledger)
+        return action;
+    const instanceField = (binding) => binding !== undefined &&
+        isJsonObject(binding) &&
+        binding.from === "instance" &&
+        typeof binding.path === "string" &&
+        binding.path.startsWith("fields.")
+        ? fieldByName.get(binding.path.slice("fields.".length))
+        : undefined;
+    const pin = (entry, currency, subject) => {
+        if (!isJsonObject(entry))
+            return entry;
+        const bind = entry.bind;
+        if (bind === undefined || !isJsonObject(bind))
+            return entry;
+        const binding = bind.currency;
+        if (binding === undefined)
+            return entry;
+        const bound = isJsonObject(binding) && binding.from === "const"
+            ? String(binding.value)
+            : undefined;
+        if (bound === currency)
+            return entry;
+        if (bound === undefined && instanceField(binding)?.type.kind === "text") {
+            return {
+                ...entry,
+                bind: { ...bind, currency: { from: "const", value: currency } },
+            };
+        }
+        diagnostics.push({
+            code: "HSX1306",
+            fix: `bind currency as { from: const; value: ${currency}; }`,
+            message: `action ${action.name} binds the currency of ${subject} to ${bound ?? "a caller-supplied value"}; a money<${currency}> amount moves in ${currency}`,
+            severity: "error",
+            span: action.origin,
+        });
+        return entry;
+    };
+    const moves = action.slots.moves ?? [];
+    const steps = action.slots.steps ?? [];
+    return {
+        ...action,
+        slots: {
+            ...action.slots,
+            moves: Array.isArray(moves)
+                ? moves.map((move) => {
+                    if (!isJsonObject(move))
+                        return move;
+                    // A post settles a reservation; the ledger refuses a post whose
+                    // currency differs from the reserve, which is pinned here.
+                    if (move.operation === "internal_transfer.post")
+                        return move;
+                    const bind = move.bind;
+                    const amount = bind !== undefined && isJsonObject(bind)
+                        ? instanceField(bind.amount)
+                        : undefined;
+                    return pin(move, fixedCurrencyOf(amount) ?? ledger, amount ? `fields.${amount.name}` : "the moved amount");
+                })
+                : moves,
+            steps: Array.isArray(steps)
+                ? steps.map((step) => isJsonObject(step) &&
+                    typeof step.operation === "string" &&
+                    step.operation.startsWith("account.")
+                    ? pin(step, ledger, `the ${step.operation} account`)
+                    : step)
+                : steps,
+        },
+    };
+}
 function bindFieldReferences(slots, fields, action, diagnostics) {
     const externalFieldSlot = (path) => {
         const key = path.at(-1);
@@ -2385,9 +3170,18 @@ function crossInstrumentReferenceDiagnostics(instruments, diagnostics) {
                     report(owner, owner.origin, `${childId}.${childRefField} is not ref<${owner.id}>`, `declare ${childId}.${childRefField} as ref<${owner.id}> or correct childRefField`);
                 }
             }
+            const parentField = invariant.parentField;
+            const parent = typeof parentField === "string"
+                ? fieldIn(owner, parentField)
+                : undefined;
             const childField = invariant.childField;
+            const childFieldDef = typeof childField === "string" ? fieldIn(child, childField) : undefined;
+            const isIntegerSum = invariant.count !== true &&
+                parent?.type.kind === "integer" &&
+                childFieldDef?.type.kind === "integer";
             if (typeof childField === "string" &&
-                fieldIn(child, childField)?.type.kind !== "money") {
+                !isIntegerSum &&
+                childFieldDef?.type.kind !== "money") {
                 report(owner, owner.origin, `${childId}.${childField} is not declared money`, `declare ${childId}.${childField} as money<C> or correct childField`);
             }
             const childStates = statesOf(child);
@@ -2398,16 +3192,12 @@ function crossInstrumentReferenceDiagnostics(instruments, diagnostics) {
                     report(owner, owner.origin, `${childId} has no lifecycle state ${status}`, `add ${status} to ${childId} or correct childStatuses`);
                 }
             }
-            const parentField = invariant.parentField;
-            const parent = typeof parentField === "string"
-                ? fieldIn(owner, parentField)
-                : undefined;
             if (typeof parentField === "string" &&
                 (!parent ||
-                    (invariant.count === true
+                    (invariant.count === true || isIntegerSum
                         ? parent.type.kind !== "integer"
                         : parent.type.kind !== "money"))) {
-                const expected = invariant.count === true ? "integer" : "money<C>";
+                const expected = invariant.count === true || isIntegerSum ? "integer" : "money<C>";
                 report(owner, owner.origin, `${owner.id}.${parentField} is not declared ${expected}`, `declare ${owner.id}.${parentField} as ${expected} or correct parentField`);
             }
         }
@@ -2885,16 +3675,15 @@ function typeOf(expr, aliases = new Map(), seen = new Set()) {
 function schemaFor(type, required) {
     switch (type.kind) {
         case "money":
-            return type.fixedAmount
-                ? {
-                    const: type.fixedAmount,
-                    pattern: MONEY_PATTERN,
-                    type: "string",
-                }
-                : {
-                    pattern: required ? MONEY_PATTERN : OPTIONAL_MONEY_PATTERN,
-                    type: "string",
-                };
+            return {
+                ...(type.fixedAmount
+                    ? { const: type.fixedAmount, pattern: MONEY_PATTERN }
+                    : { pattern: required ? MONEY_PATTERN : OPTIONAL_MONEY_PATTERN }),
+                type: "string",
+                ...(type.currency && CURRENCY.test(type.currency)
+                    ? { "x-hyperscale-currency": type.currency }
+                    : {}),
+            };
         case "bps":
         case "percent":
             return { maximum: 10_000, minimum: 0, type: "integer" };
@@ -2906,6 +3695,8 @@ function schemaFor(type, required) {
             return { format: "hyperscale-date-time", type: "string" };
         case "ref":
             return { type: "string" };
+        case "account":
+            return { pattern: ACCOUNT_PATTERN, type: "string" };
         default:
             return { type: "string" };
     }