@hyperscale0/hsx 1.0.124 → 1.0.128

package/README.md

@@ -21,8 +21,8 @@ Start with the [first program and rental guide](docs/README.md). Save the
 It holds 1,000 SAR, charges a one-time 50 SAR late fee, and returns the remainder.
 The guide explains the fixed business binding and the host needed to execute it.
 
-`npx hsx headers` prints every std instrument and its tunables from the bundled
-headers. The [samples](examples/) include both complete action paths and
+`npx hsx headers --json` prints every std instrument and its tunables from the
+bundled headers as JSON. The [samples](examples/) include both complete action paths and
 compositions that still need child-record actions or adapter bindings. A compile
 pass does not prove that a flow is publicly executable or funded.
 

package/dist/src/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAgBL,KAAK,WAAW,EAQjB,MAAM,kBAAkB,CAAC;AAU1B,OAAO,EAIL,KAAK,UAAU,EAKf,KAAK,IAAI,EACV,MAAM,UAAU,CAAC;AAClB,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;CACpC;AACD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,aAAa,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AACD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CAClE;AACD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,WAAW,CAAC;QACtB,YAAY,EAAE,eAAe,CAAC;QAC9B,SAAS,EAAE,qBAAqB,EAAE,CAAC;KACpC,CAAC;CACH;AAqTD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAgnHf"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAgBL,KAAK,WAAW,EAQjB,MAAM,kBAAkB,CAAC;AAU1B,OAAO,EAIL,KAAK,UAAU,EAKf,KAAK,IAAI,EACV,MAAM,UAAU,CAAC;AAClB,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;CACpC;AACD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,aAAa,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AACD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CAClE;AACD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,WAAW,CAAC;QACtB,YAAY,EAAE,eAAe,CAAC;QAC9B,SAAS,EAAE,qBAAqB,EAAE,CAAC;KACpC,CAAC;CACH;AAqTD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAqrHf"}

package/dist/src/compile.js

@@ -349,10 +349,6 @@ export function compile(source, options = {}) {
         for (const decl of program.decls)
             if (decl.kind === "instrument")
                 templates.set(decl.name, decl);
-        for (const decl of program.decls) {
-            if (decl.kind === "instrument" && decl.parameters.length)
-                fail(decl, "This compiler cannot instantiate a parameterized instrument declared inside a program.", "For this version, specialize the instrument with fixed bindings and remove its parameters. Custom reusable headers require a host-supplied library.");
-        }
         const document = {
             udl: UDL_FORMAT_VERSION,
             version: 1,
@@ -600,7 +596,11 @@ export function compile(source, options = {}) {
                 const fallback = param.value.kind === "default" ? param.value.value : undefined;
                 const typeName = type.kind === "type" || type.kind === "call" ? type.name : text(type);
                 const partyParameter = attachmentInfo && typeName === "party";
+                const optional = type.kind === "type" && type.optional;
+                // An optional party stays unset unless the attachment binds it, so a
+                // program party that shares its name does not switch it on.
                 const byName = partyParameter &&
+                    !optional &&
                     (subjectPartyRoles.includes(param.key) ||
                         document.parties[param.key])
                     ? { kind: "name", value: param.key, span: origin }
@@ -612,7 +612,7 @@ export function compile(source, options = {}) {
                         source: declarationSources.get(decl) ?? "program",
                     });
                 if (!actual) {
-                    if (type.kind === "type" && type.optional)
+                    if (optional)
                         continue;
                     parameterErrors.push({
                         span: origin,
@@ -678,7 +678,9 @@ export function compile(source, options = {}) {
                 const suppliedValue = supplied.get(key);
                 const requirements = decl.body.entries
                     .filter((entry) => entry.key.startsWith("action "))
-                    .flatMap((entry) => asBlock(entries(asBlock(entry.value)).get("subject")).entries);
+                    .flatMap((entry) => 
+                // Read subject rows directly: entries() refuses repeated when branches.
+                asBlock(asBlock(entry.value).entries.find((row) => row.key === "subject")?.value).entries);
                 const moneyFields = [
                     ...new Set(requirements
                         .filter((entry) => {
@@ -1653,10 +1655,10 @@ export function compile(source, options = {}) {
                         };
                     }
                 }
-                const fromBinding = slots.get("from");
-                if (fromBinding?.kind === "name" &&
-                    fromBinding.value.includes(".") &&
-                    slots.has("moves")) {
+                const from = slots.get("from");
+                // A policy member may sit in a state list such as `[funded, dispute.refund_after]`.
+                const fromBinding = (from?.kind === "list" ? from.items : [from]).find((item) => item?.kind === "name" && item.value.includes("."));
+                if (fromBinding?.kind === "name" && slots.has("moves")) {
                     const [parameter, member] = fromBinding.value.split(".");
                     const suppliedPolicy = supplied.get(parameter);
                     if (suppliedPolicy?.kind === "block") {
@@ -1693,6 +1695,7 @@ export function compile(source, options = {}) {
                     ...(actionSubject ? { subject: actionSubject } : {}),
                 };
                 authored.set(a, row.value);
+                const actionFeeCalculations = [];
                 for (const binding of boundaryBindings)
                     if (!a.subject?.adapters.find((entry) => entry.binding === binding)
                         ?.snapshot)
@@ -1920,18 +1923,31 @@ export function compile(source, options = {}) {
                                     if (rate.kind !== "percent")
                                         fail(rate, "fee rate needs a percentage", "write a percentage such as 1%");
                                     const prefix = `${name}_${key}`;
-                                    const derived = (suffix, calculation) => {
+                                    // Instrument calculations run at create, before any action
+                                    // input exists, so a fee on an input amount runs with its action.
+                                    const perAction = "field" in transfer.amount &&
+                                        transfer.amount.field.startsWith("input.");
+                                    const derived = (suffix, label, calculation) => {
                                         const target = prefix + "_" + suffix;
                                         if (fields.some((f) => f.name === target))
                                             fail(move, `generated fee field ${target} conflicts with a field`, "rename the authored field or move key");
-                                        fields.push({ name: target, type: "money" });
-                                        calculations.push({
+                                        fields.push({
+                                            name: target,
+                                            type: "money",
+                                            label,
+                                            ...(perAction ? { optional: true } : {}),
+                                        });
+                                        (perAction ? actionFeeCalculations : calculations).push({
                                             ...calculation,
                                             target,
                                         });
                                         return { field: `self.${target}` };
                                     };
-                                    const gross = derived("feeGross", {
+                                    // Labels come from the source keys: seller or buyer, cap, tax.
+                                    const feeLabel = `${paidBy === "seller" ? "Seller" : "Buyer"} fee`;
+                                    const gross = derived("feeGross", quoted.kind === "capped"
+                                        ? `${feeLabel} before cap`
+                                        : feeLabel, {
                                         op: "rate",
                                         base: transfer.amount,
                                         bps: { literal: literal(rate) },
@@ -1941,7 +1957,7 @@ export function compile(source, options = {}) {
                                     if (quoted.kind === "capped") {
                                         if (quoted.cap.kind !== "money")
                                             fail(quoted.cap, "fee cap needs money", "write an amount such as 750 SAR");
-                                        charge = derived("fee", {
+                                        charge = derived("fee", feeLabel, {
                                             op: "minimum",
                                             values: [gross, { literal: literal(quoted.cap) }],
                                         });
@@ -1950,7 +1966,7 @@ export function compile(source, options = {}) {
                                     if (tax && tax.kind !== "percent")
                                         fail(tax, "tax needs a percentage of the fee", "write tax: 15%");
                                     const vat = tax
-                                        ? derived("tax", {
+                                        ? derived("tax", "Fee tax", {
                                             op: "rate",
                                             base: charge,
                                             bps: { literal: literal(tax) },
@@ -1959,7 +1975,7 @@ export function compile(source, options = {}) {
                                         : undefined;
                                     const charges = vat ? [charge, vat] : [charge];
                                     const net = paidBy === "seller"
-                                        ? derived("net", {
+                                        ? derived("net", "Amount after fee", {
                                             op: "subtract",
                                             base: transfer.amount,
                                             subtract: charges,
@@ -2022,6 +2038,8 @@ export function compile(source, options = {}) {
                     else
                         a[key] = data(expr);
                 }
+                if (actionFeeCalculations.length)
+                    a.calculate = [...(a.calculate ?? []), ...actionFeeCalculations];
                 if (attachmentInfo && !attachmentInfo.child) {
                     if (attachmentInfo.exposed.has(name)) {
                         if (automatic(a.actor))
@@ -2373,7 +2391,9 @@ export function compile(source, options = {}) {
             });
         };
         for (const decl of program.decls) {
-            if (decl.kind === "instrument") {
+            // A parameterized program instrument is a template, like a header
+            // instrument: each attachment instantiates it with its own bindings.
+            if (decl.kind === "instrument" && !decl.parameters.length) {
                 addInstrument(decl, decl.name, emptyBlock, decl.span);
             }
             if (decl.kind === "assignment") {
@@ -2628,7 +2648,9 @@ export function compile(source, options = {}) {
         const checkParty = (name, at, inst) => {
             const names = parties(inst);
             if (!names.includes(name))
-                fail(at, `\`${name}\` is not a declared party.${didYouMean(name, names)}`, `Declare it with \`party ${name}: business\`, or name a declared party (${names.join(", ")}).`);
+                fail(at, `\`${name}\` is not a declared party.${didYouMean(name, names)}`, subjectPartyRoles.includes(name)
+                    ? `Declare a party parameter such as \`holder: party\` on the instrument, use it here, and bind \`holder: ${name}\` where you attach it.`
+                    : `Declare it with \`party ${name}: business\`, or name a declared party (${names.join(", ")}).`);
         };
         const checkInput = (name, at, label, input) => {
             const names = input.map((field) => field.name);
@@ -2681,9 +2703,39 @@ export function compile(source, options = {}) {
             inst,
             label: declarations.get(inst).name,
         });
+        // A family member drops an optional reference field its binding left
+        // unset (a borrower-funded plan has no `funds`), so it cannot match and
+        // leaves the selection. The header must still declare the field.
+        const matchable = (selection) => {
+            const members = [selection.instrument].flat();
+            const header = selection.family
+                ? templates.get(`${selection.family.module}.${selection.family.exportPath}`)
+                : undefined;
+            if (!header ||
+                !entries(asBlock(entries(header.body).get("fields"))).has(selection.reference))
+                return members;
+            return members.filter((id) => resolveField(document, byId.get(id), `self.${selection.reference}`));
+        };
+        // A count over no matchable member is zero.
+        for (const inst of document.instruments)
+            for (const action of Object.values(inst.actions))
+                action.requires = action.requires.map((requirement) => requirement.kind === "aggregate" &&
+                    requirement.measure === "count" &&
+                    !matchable(requirement.selection).length
+                    ? {
+                        kind: "compare",
+                        left: { literal: 0 },
+                        operator: requirement.operator,
+                        right: requirement.value,
+                    }
+                    : requirement);
         const checkSelection = (selection, at, scope) => {
             walk(selection.anchor, "anchor", site(selection, "anchor", at), scope);
             walk(selection.where, "where", site(selection, "where", at), scope);
+            const members = matchable(selection);
+            if (members.length &&
+                members.length < [selection.instrument].flat().length)
+                selection.instrument = members;
             for (const id of [selection.instrument].flat()) {
                 checkTarget(id, site(selection, "instrument", at));
                 const target = scopeOf(byId.get(id));