@hyperscale0/hsx 1.0.337 → 1.0.339

package/dist/src/compile.js

@@ -5,7 +5,7 @@ import { validateUdl, resolveField, sameAccount, sameObjectField, subjectPartyRo
 import { bindingDependencies, parameterDiagnostics, BindingContractError, } from "./binding-contract.js";
 import { tunableBounds } from "./tunables.js";
 import { parseProgram } from "./parse.js";
-import { applyAttachmentEconomics, purposeWarnings, } from "./attachment-economics.js";
+import { applyAttachmentEconomics, purposeWarnings, samePartyMoves, unboundEconomicSources, } from "./attachment-economics.js";
 import { parseHeader } from "./header-source.js";
 import { lineColAt, } from "./ast.js";
 import { bundledStandardLibrary } from "./std-library.js";
@@ -200,6 +200,24 @@ function decimal(raw, scale, expr) {
     return (BigInt(whole) * 10n ** BigInt(scale) +
         BigInt(fraction.padEnd(scale, "0") || "0")).toString();
 }
+/**
+ * A calendar period as ISO-8601 text: `1 month`, `2 weeks`, `7d` or `P1M`.
+ * Days, weeks, months and years only, the units Stripe and Shopify bill in.
+ */
+function periodText(expr) {
+    if (!["duration", "text", "name"].includes(expr.kind))
+        return undefined;
+    const value = expr.value.trim();
+    const units = { d: "D", w: "W", m: "M", y: "Y" };
+    const words = /^([1-9]\d{0,3}) ?(day|week|month|year)s?$/.exec(value);
+    const short = /^([1-9]\d{0,3})(d|w)$/.exec(value);
+    const iso = /^P(?!$)(?:[1-9]\d{0,3}Y)?(?:[1-9]\d{0,3}M)?(?:[1-9]\d{0,3}W)?(?:[1-9]\d{0,3}D)?$/.exec(value);
+    if (words)
+        return `P${words[1]}${units[words[2][0]]}`;
+    if (short)
+        return `P${short[1]}${units[short[2]]}`;
+    return iso ? value : undefined;
+}
 function literal(expr, expectedType) {
     if (expr.kind === "text" && expectedType === "duration")
         return literal({ ...expr, kind: "duration" });
@@ -501,7 +519,9 @@ export function compile(source, options = {}) {
             }
             return { module: moduleName, exportPath, revision };
         };
-        const addInstrument = (decl, id, arguments_, origin, inherited = new Map(), inheritedEnums = new Map(), attachmentInfo, familyDeclaration, standardOrigin) => {
+        const addInstrument = (decl, id, arguments_, origin, inherited = new Map(), inheritedEnums = new Map(), attachmentInfo, familyDeclaration, standardOrigin, 
+        /** Declared tunables, true where the author bound them. */
+        inheritedTunables = new Map()) => {
             const resolveFamilyInstruments = (family, currentInstId, expr) => {
                 const found = new Set();
                 if (currentInstId && familyDeclaration) {
@@ -635,13 +655,16 @@ export function compile(source, options = {}) {
                 suppliedEntries.set(entry.key, entry);
             }
             const environment = new Map(inherited);
+            // `when every is set` asks whether the author bound a tunable; a
+            // default leaves it unset.
+            const tunables = new Map(inheritedTunables);
             const parameterErrors = [];
             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 typeName = type.kind === "type" || type.kind === "call" ? type.name : text(type);
                 const partyParameter = attachmentInfo && typeName === "party";
-                const optional = type.kind === "type" && type.optional;
+                const optional = (type.kind === "type" || type.kind === "call") && !!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 &&
@@ -650,6 +673,7 @@ export function compile(source, options = {}) {
                         document.parties[param.key])
                     ? { kind: "name", value: param.key, span: origin }
                     : undefined;
+                tunables.set(param.key, supplied.has(param.key) || !!byName);
                 const actual = supplied.get(param.key) ??
                     byName ??
                     (fallback && {
@@ -699,9 +723,10 @@ export function compile(source, options = {}) {
             }
             for (const dependency of dependencies) {
                 const selected = environment.get(dependency.when);
-                if (selected?.kind === "name" &&
-                    selected.value === dependency.is &&
-                    !environment.has(dependency.binding)) {
+                const holds = enums.has(dependency.when)
+                    ? selected?.kind === "name" && selected.value === dependency.is
+                    : tunables.get(dependency.when) === (dependency.is === "set");
+                if (holds && !environment.has(dependency.binding)) {
                     throw new CompileFailure({
                         code: "HSX1001",
                         message: dependency.message.replaceAll("{attachment}", attachmentInfo?.attachmentName ?? id),
@@ -812,7 +837,8 @@ export function compile(source, options = {}) {
                         const target = templates.get(type);
                         const required = target?.parameters
                             .filter((p) => p.value.kind !== "default" &&
-                            !(p.value.kind === "type" && p.value.optional))
+                            !((p.value.kind === "type" || p.value.kind === "call") &&
+                                p.value.optional))
                             .map((p) => p.key) ?? [];
                         fail({ span: origin }, `Attachment \`${attachmentInfo.attachmentName}\` needs a \`${parameter}\` binding. ${matches.length === 0
                             ? `No \`${type}\` attachment exists on \`${attachmentInfo.subjectKindId}\`.`
@@ -895,6 +921,10 @@ export function compile(source, options = {}) {
                         (v.kind === "text" || v.kind === "name") &&
                         /^P/.test(v.value))
                         v = { ...v, kind: "duration" };
+                    // A period lowers as ISO text, so `after` steps calendar months.
+                    const period = type === "period" ? periodText(v) : undefined;
+                    if (period)
+                        v = { kind: "text", value: period, span: v.span };
                     environment.set(param.key, v);
                     if (type === "enum" && t.kind === "call") {
                         if (v.kind !== "name" || !t.args.some((a) => text(a) === v.value))
@@ -982,6 +1012,10 @@ export function compile(source, options = {}) {
                                 span: v.span,
                             });
                     }
+                    else if (type === "period") {
+                        if (!period)
+                            fail(v, `${param.key} needs a calendar period`, `write ${param.key}: 1 month, 2 weeks, 1 year or 7 days`);
+                    }
                     else if (type === "fee" || type === "split" || type === "policy") {
                         if (v.kind !== "block")
                             fail(v, `${param.key} needs a block`, `write ${param.key} { ... }`);
@@ -1067,6 +1101,27 @@ export function compile(source, options = {}) {
                 throw new CompileFailure(parameterErrors[0]);
             }
             const body = entries(decl.body);
+            // A ceiling caps a tunable by the value of an enum tunable, such as the
+            // longest term per loan kind. An unset tunable takes the ceiling; a
+            // supplied one may lower it, never raise it.
+            for (const ceiling of asBlock(body.get("ceilings")).entries) {
+                const table = entries(asBlock(ceiling.value));
+                const by = table.get("by");
+                const selected = by && environment.get(text(by));
+                if (!by || selected?.kind !== "name")
+                    fail(ceiling, `ceiling ${ceiling.key} needs by: an enum tunable`, "write by: kind and one maximum per enum value");
+                const maximum = table.get(selected.value);
+                if (maximum?.kind !== "number")
+                    fail(ceiling, `ceiling ${ceiling.key} has no maximum for ${selected.value}`, `add ${selected.value}: number to the ceiling`);
+                if (!tunables.get(ceiling.key)) {
+                    environment.set(ceiling.key, { ...maximum, span: origin });
+                    continue;
+                }
+                const supplied = environment.get(ceiling.key);
+                if (supplied.kind !== "number" ||
+                    BigInt(supplied.value) > BigInt(maximum.value))
+                    fail(supplied, `${ceiling.key} for ${selected.value} is at most ${maximum.value}`, `choose ${ceiling.key} of ${maximum.value} or less, or omit it`);
+            }
             for (const constraint of asBlock(body.get("constraints")).entries) {
                 const rule = constraint.value;
                 if (rule.kind !== "call" ||
@@ -1076,6 +1131,9 @@ export function compile(source, options = {}) {
                 const left = environment.get(constraint.key), right = environment.get(text(rule.args[0]));
                 if (!left || !right)
                     fail(rule, "constraint needs two declared tunables", "name the compared tunables");
+                // A runtime value is checked when the agreement is created.
+                if ([left, right].some((expr) => expr.kind === "name" && expr.value === "runtime"))
+                    continue;
                 const numericKind = (expr) => expr.kind === "name" && /^P(?:\d|T)/.test(expr.value)
                     ? "duration"
                     : expr.kind;
@@ -1099,6 +1157,7 @@ export function compile(source, options = {}) {
                     "summary",
                     "invariants",
                     "constraints",
+                    "ceilings",
                     "dependencies",
                     "parameterDiagnostics",
                     "reports",
@@ -1289,9 +1348,52 @@ export function compile(source, options = {}) {
                         : value.value;
                 return literal(value);
             };
+            const branchMatches = (entry) => {
+                const [, tunable, relation, choice] = entry.key.split(" ");
+                // `when every is set` holds when the author bound the tunable, so an
+                // optional tunable and a defaulted one both read as unset.
+                if (relation === "is" &&
+                    (choice === "set" || choice === "unset") &&
+                    tunables.has(tunable) &&
+                    !enums.has(tunable))
+                    return tunables.get(tunable) === (choice === "set");
+                const binding = environment.get(tunable);
+                if (!binding)
+                    fail(entry, `unknown branch tunable ${tunable}`, "name an enum, reference or optional tunable declared by this header");
+                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");
+                    return entries(asBlock(entries(target).get("fields"))).has(choice);
+                }
+                if (!enums.get(tunable)?.includes(choice))
+                    fail(entry, `unknown enum branch ${choice}`, "use a declared enum value, or set or unset");
+                return text(binding) === choice;
+            };
+            // Fields and inputs take `when` branches too; a branch holds field rows.
+            const branchRows = (block) => block.entries.flatMap((row) => row.key.startsWith("when ")
+                ? branchMatches(row)
+                    ? branchRows(asBlock(row.value))
+                    : []
+                : [row]);
             const lowerFields = (block) => {
                 const result = [];
-                for (const row of block.entries) {
+                for (const row of branchRows(block)) {
                     const { type: t } = fieldType(row);
                     const constant = row.value.kind === "default" ? resolve(row.value.value) : undefined;
                     const f = lowerFieldShape(row, resolve);
@@ -1476,6 +1578,15 @@ export function compile(source, options = {}) {
                                     milliseconds: args[1],
                                     direction: constant.name,
                                 });
+                            // after(start, 1 month, 3) steps calendar periods from start.
+                            else if (constant.name === "after" && args.length === 3)
+                                calculations.push({
+                                    target,
+                                    op: "step",
+                                    date: args[0],
+                                    period: args[1],
+                                    times: args[2],
+                                });
                             else
                                 fail(constant, `unknown calculation ${constant.name}`, "use rate, sum, minimum, subtract, multiply, divide, before or after");
                             authored.set(calculations.at(-1), constant);
@@ -1563,37 +1674,7 @@ export function compile(source, options = {}) {
                     entries: block.entries.flatMap((entry) => {
                         if (!entry.key.startsWith("when "))
                             return [entry];
-                        const [, tunable, relation, choice] = entry.key.split(" ");
-                        const binding = environment.get(tunable);
-                        if (!binding)
-                            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 matches = branchMatches(entry);
                         const body = asBlock(entry.value);
                         for (const clause of body.entries)
                             if (!["requires", "moves", "invoke", "calculate"].includes(clause.key) &&
@@ -2446,7 +2527,7 @@ export function compile(source, options = {}) {
                             .filter(Boolean)
                             .join("."),
                     }
-                    : undefined);
+                    : undefined, tunables);
             }
         };
         const compileObject = (decl) => {
@@ -3388,10 +3469,21 @@ export function compile(source, options = {}) {
                     }, "lower");
                 }),
             };
+        const sameParty = samePartyMoves(document, attachedSelectors, attachEntries);
+        const unbound = unboundEconomicSources(document, attachedSelectors, attachEntries);
+        if (sameParty.errors.length || unbound.length)
+            return {
+                verdict: "invalid",
+                warnings: [],
+                diagnostics: [...sameParty.errors, ...unbound].map((d) => diagnostic(d, "check")),
+            };
         return {
             verdict: "valid",
             diagnostics: [],
-            warnings: purposeWarnings(document, attachedSelectors, attachEntries).map((d) => ({ ...diagnostic(d, "check"), severity: "warning" })),
+            warnings: [
+                ...sameParty.warnings,
+                ...purposeWarnings(document, attachedSelectors, attachEntries),
+            ].map((d) => ({ ...diagnostic(d, "check"), severity: "warning" })),
             artifacts: {
                 document: validated.value,
                 costManifest: buildUdlCostManifest(validated.value),