@hyperscale0/hsx 1.0.265 → 1.0.284

package/CHANGELOG.md

@@ -1,14 +1,45 @@
 # Changelog
 
-## Unreleased
+## Since 1.0.123
 
-- Add eleven neutral archetype programs in `bases/` and the browser export
+Releases after 1.0.123 shipped without per-release entries. This entry
+summarises what changed in the language, the compiler and the bundled programs
+since then.
+
+Added:
+
+- Eleven neutral archetype programs in `bases/` and the browser export
   `@hyperscale0/hsx/bases`. Generation and preparation bundle their source and
   metadata. Package checks enforce compilation, coverage and neutral content.
+- The `booking` std header, with deposit, balance and cancellation windows.
+- `financing.installments` prices a plan as `amortizing` or `flat_total`, and
+  `refund_within` (default 30d) bounds refunds after a plan is paid.
+- `wallet.balance` takes a `topup_fee`; `escrow.hold` takes `deliver_within`.
+- Selections accept `overlaps: { start, end, from, until }` to match rows whose
+  date period meets a range.
+- Program instruments take party parameters, and a `fee` on a move of an action
+  input is calculated when that action runs.
+- Every agreement reference is an optional creation input on an exposed create.
+- Customers can start the std agreements whose first party can be a customer on
+  a record they do not own, through the object's `entryActions`.
+- `economics` can name a party reached through a reference.
+
+Changed:
 
-- Rewrite all 15 ready-made products as Saudi business examples with SAR prices,
-  explicit fees and VAT treatment, named business counterparties, useful list
-  columns, and supported payment, refund, dispute and overdue paths.
+- All 15 examples are Saudi businesses with SAR prices, explicit fees and VAT
+  treatment, named business counterparties, list columns, and payment, refund,
+  dispute and overdue paths.
+- A required instrument value with no fixed value becomes create `input` on the
+  agreement. Only an explicit `rename` shares it as record metadata.
+- Record actions stay private until the program exposes them.
+- Std actions name an accountable actor, and std money pulled from a customer
+  needs that customer's authority.
+- A split binds declared business and subject-role recipients itself, and a
+  share the payer keeps stays in the source account with no self-transfer.
+- Late charges and recovery costs are bounded across the whole plan, and an
+  insurance cover's claim limit is shared across every claim attachment.
+- Financing and escrow plans have exits for returned, undelivered and paid-off
+  goods, and a paid-off plan closes once its refund window passes.
 
 ## 1.0.123
 

package/README.md

@@ -20,7 +20,8 @@ npx hsx cost rental.hsx
 
 Start with the [first program and rental guide](docs/README.md). Save the
 [rental source](examples/rental-deposit.hsx) as `rental.hsx` for these commands.
-It holds 1,000 SAR, charges a one-time 50 SAR late fee, and returns the remainder.
+It holds 1,000 SAR, charges one 50 SAR late fee plus 7.50 SAR VAT, and returns
+the remainder.
 The guide explains the fixed business binding and the host needed to execute it.
 
 `npx hsx headers --json` prints every std instrument and its tunables from the

package/SECURITY.md

@@ -9,9 +9,8 @@ security-sensitive belongs in an issue, a pull request, a discussion, or a
 commit message.
 
 A report we can act on names the affected version and gives us something to
-run: the `.hsx` source, and what you expected the compiler to do with it. If
-you can shape it as a fixture under `test/fixtures/`, do that; it goes straight
-into the fix.
+run: the `.hsx` source, and what you expected the compiler to do with it. A
+failing spec is the most useful shape; it goes straight into the fix.
 
 ## What counts
 
@@ -23,22 +22,12 @@ executes, so the interesting failures are the ones a source file can cause:
   whose fees move money the source did not authorise. A `valid` verdict on an
   unsound program is the worst bug this package can have.
 - **A program that makes the lexer, parser, checker, or lowering burn
-  unbounded time or memory.** The schedule, split, and money-event limits bound
-  the output; `src/limits.ts` bounds the input, and a source over either of its
-  ceilings is refused with a diagnostic rather than read.
-
-  The stages behind that ceiling are linear, measured rather than assumed. The
-  lexer was timed on 21 adversarial inputs, one per branch of the scanner:
-  unterminated strings, unclosed comments, single-character invalid runs, one
-  quarter-megabyte invalid run, digit and percent soup, and interleaved open
-  delimiters. Across a 64x range of input size its cost per byte grew at most
-  1.44x, where a quadratic scanner would grow 64x. The worst admitted file
-  costs 9.8 ms to lex and 21.1 ms to compile. A payload that makes any stage
-  cost meaningfully more than that per byte is a finding worth reporting.
-
-- **A crash.** Parsing and checking are total by design: they return
-  diagnostics, they never throw. A source file that throws out of `compile()`
-  is a bug even when the program is nonsense.
+  unbounded time or memory.** The parser refuses source over 256 KiB with
+  `HSX1004`, and block or expression nesting deeper than 32. A way around
+  either, or a stage whose cost grows faster than its input, is a finding
+  worth reporting.
+- **A crash.** `compile()` reports invalid source as diagnostics. A source
+  file that makes it throw is a bug even when the program is nonsense.
 - **A diagnostic that reports the wrong source coordinates**, which sends an
   author to fix the wrong line.
 
@@ -47,8 +36,8 @@ anything that requires already controlling the machine running it.
 
 ## Supported versions
 
-Alpha releases are supported at the newest published `alpha` version only.
-Fixes land there; there is no backport branch before 1.0.0.
+Fixes land in the newest published `1.0.N` release. Older releases get no
+backports.
 
 ## Disclosure
 

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,EAiBL,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,CAq8Hf"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAiBL,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;AAmVD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,aAAa,CA8hIf"}

package/dist/src/compile.js

@@ -135,6 +135,24 @@ const camel = (name) => name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 const automatic = (actor) => actor === "clock" ||
     (actor !== null && typeof actor === "object" && "parent" in actor);
 const title = (name) => name[0].toUpperCase() + name.slice(1).replaceAll("_", " ");
+/** Parties an instrument names itself: account owners, actors, move endpoints. */
+function namedParties(instrument) {
+    const names = instrument.fields.flatMap((field) => field.type === "account" && typeof field.owner === "string"
+        ? [field.owner]
+        : []);
+    for (const action of Object.values(instrument.actions)) {
+        if (typeof action.actor === "object" && "party" in action.actor)
+            names.push(action.actor.party);
+        for (const move of action.moves) {
+            if (move.economics)
+                names.push(move.economics.sourceParty);
+            for (const endpoint of "from" in move ? [move.from, move.to] : [])
+                if (endpoint.startsWith("party."))
+                    names.push(endpoint.slice(6));
+        }
+    }
+    return names;
+}
 function entries(block) {
     const map = new Map();
     for (const row of block.entries) {
@@ -174,6 +192,8 @@ function text(expr) {
     return fail(expr, "expected a name or literal", "write a single name or literal");
 }
 function decimal(raw, scale, expr) {
+    if (raw.startsWith("-"))
+        fail(expr, "literal cannot be negative", "write a positive value; a move's from and to set its direction");
     const [whole = "", fraction = ""] = raw.split(".");
     if (!/^\d+$/.test(whole) || fraction.length > scale)
         fail(expr, `literal has more than ${scale} decimal places`, `write at most ${scale} decimal places`);
@@ -243,6 +263,8 @@ function literal(expr, expectedType) {
         return expr.value;
     if (expr.kind === "name" && ["true", "false"].includes(expr.value))
         return expr.value === "true";
+    if (expr.kind === "name" && expr.value === "runtime")
+        fail(expr, "this value is fixed when the program compiles, so it cannot be runtime", "write a literal value");
     return fail(expr, "expected a literal", "write a typed constant");
 }
 export function compile(source, options = {}) {
@@ -990,7 +1012,7 @@ export function compile(source, options = {}) {
                             if (bounds &&
                                 (BigInt(String(value)) < BigInt(bounds.minimum) ||
                                     BigInt(String(value)) > BigInt(bounds.maximum)))
-                                fail(v, `${param.key} is outside ${bounds.minimum}..${bounds.maximum}`, "choose a value inside the tunable's bounds");
+                                fail(v, `value is outside ${bounds.minimum}..${bounds.maximum}`, "choose a value inside the tunable's bounds");
                         }
                         catch (error) {
                             if (error instanceof CompileFailure)
@@ -1039,7 +1061,7 @@ 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");
-                const numericKind = (expr) => expr.kind === "name" && /^P/.test(expr.value)
+                const numericKind = (expr) => expr.kind === "name" && /^P(?:\d|T)/.test(expr.value)
                     ? "duration"
                     : expr.kind;
                 if (!["money", "number", "percent", "duration"].includes(numericKind(left)) ||
@@ -1106,6 +1128,7 @@ export function compile(source, options = {}) {
                 return lowered;
             };
             const fields = [];
+            const boundaryReceipts = new Map();
             const calculations = [];
             let currentAction;
             let currentActionName;
@@ -1486,6 +1509,38 @@ export function compile(source, options = {}) {
                 actions: Object.create(null),
                 actionOrder: [],
             };
+            const actionTargets = new Set();
+            const collectTargets = (block) => {
+                for (const entry of block.entries)
+                    if (entry.key.startsWith("when "))
+                        collectTargets(asBlock(entry.value));
+                    else if (entry.key === "calculate")
+                        for (const item of entry.value.kind === "list"
+                            ? entry.value.items
+                            : [entry.value]) {
+                            const target = item.kind === "block" ? entries(item).get("target") : undefined;
+                            if (target)
+                                actionTargets.add(String(data(target)));
+                        }
+            };
+            for (const row of decl.body.entries)
+                if (row.key.startsWith("action "))
+                    collectTargets(asBlock(row.value));
+            // Instrument calculations run before every action, create included, so
+            // a fee or split calculates there only on an amount held from create.
+            const heldFromCreate = (amount) => {
+                if (!("field" in amount))
+                    return true;
+                const [root, name, ...rest] = amount.field.split(".");
+                const field = fields.find((item) => item.name === name);
+                return (root === "self" &&
+                    !rest.length &&
+                    !!field &&
+                    !actionTargets.has(name) &&
+                    (!field.optional ||
+                        "value" in field ||
+                        calculations.some((node) => node.target === name)));
+            };
             for (const row of decl.body.entries.filter((e) => e.key.startsWith("action "))) {
                 const name = row.key.slice(7);
                 const selected = (block) => ({
@@ -1744,7 +1799,7 @@ export function compile(source, options = {}) {
                     ...(actionSubject ? { subject: actionSubject } : {}),
                 };
                 authored.set(a, row.value);
-                const actionFeeCalculations = [];
+                const moveCalculations = [];
                 for (const binding of boundaryBindings)
                     if (!a.subject?.adapters.find((entry) => entry.binding === binding)
                         ?.snapshot)
@@ -1775,8 +1830,20 @@ export function compile(source, options = {}) {
                             const op = parts.has("operation")
                                 ? String(data(parts.get("operation")))
                                 : "internal_transfer.create";
-                            if (op === "internal_transfer.reserve" && !parts.has("capture"))
-                                fail(move, "reserve needs a receipt field", "add capture: receipt_name");
+                            if (op === "internal_transfer.reserve" && !parts.has("capture")) {
+                                if (!parts.has("boundary"))
+                                    fail(move, "reserve needs a receipt field", "add capture: receipt_name");
+                                const capture = `${name}Receipt`;
+                                if (fields.some((field) => field.name === capture))
+                                    fail(move, "boundary receipt name is already used", "name each reservation with an explicit capture");
+                                fields.push({ name: capture, type: "text", optional: true });
+                                boundaryReceipts.set(name, capture);
+                                parts.set("capture", {
+                                    kind: "text",
+                                    value: capture,
+                                    span: move.span,
+                                });
+                            }
                             if ((op === "internal_transfer.post" ||
                                 op === "internal_transfer.void") &&
                                 !parts.has("transfer"))
@@ -1890,6 +1957,7 @@ export function compile(source, options = {}) {
                                         fail(move, "split needs 1 to 64 recipients", "name the receiving parties and percentages");
                                     let total = 0;
                                     const pieces = [];
+                                    const perAction = !heldFromCreate(val(amount));
                                     for (const [index, [party, rate]] of shares.entries()) {
                                         const recipient = resolve({
                                             kind: "name",
@@ -1920,8 +1988,12 @@ export function compile(source, options = {}) {
                                         const target = `${name}_${key}_share${index + 1}`;
                                         if (fields.some((f) => f.name === target))
                                             fail(move, "split field name conflicts", "rename the move key");
-                                        fields.push({ name: target, type: "money" });
-                                        calculations.push(index === shares.length - 1 && pieces.length
+                                        fields.push({
+                                            name: target,
+                                            type: "money",
+                                            ...(perAction ? { optional: true } : {}),
+                                        });
+                                        (perAction ? moveCalculations : calculations).push(index === shares.length - 1 && pieces.length
                                             ? {
                                                 target,
                                                 op: "subtract",
@@ -1993,14 +2065,18 @@ export function compile(source, options = {}) {
                                     if (terms.has("seller") === terms.has("buyer"))
                                         fail(fee, "fee needs exactly one paying party", "write seller: 1% or buyer: 1%");
                                     const quoted = terms.get(paidBy);
+                                    // An account the agreement owns holds only what was moved
+                                    // into it, so a charge on top has nothing to come from.
+                                    if (paidBy === "buyer" &&
+                                        fields.some((field) => `self.${field.name}` === transfer.from &&
+                                            field.type === "account" &&
+                                            field.owner === "self"))
+                                        fail(quoted, `a buyer fee cannot come from \`${transfer.from.slice("self.".length)}\`, which holds only the moved amount`, "use a seller fee, which comes out of the held amount");
                                     const rate = quoted.kind === "capped" ? quoted.rate : quoted;
                                     if (rate.kind !== "percent")
                                         fail(rate, "fee rate needs a percentage", "write a percentage such as 1%");
                                     const prefix = `${name}_${key}`;
-                                    // 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 perAction = !heldFromCreate(transfer.amount);
                                     const derived = (suffix, label, calculation) => {
                                         const target = prefix + "_" + suffix;
                                         if (fields.some((f) => f.name === target))
@@ -2011,7 +2087,7 @@ export function compile(source, options = {}) {
                                             label,
                                             ...(perAction ? { optional: true } : {}),
                                         });
-                                        (perAction ? actionFeeCalculations : calculations).push({
+                                        (perAction ? moveCalculations : calculations).push({
                                             ...calculation,
                                             target,
                                         });
@@ -2120,8 +2196,8 @@ export function compile(source, options = {}) {
                     else
                         a[key] = data(expr);
                 }
-                if (actionFeeCalculations.length)
-                    a.calculate = [...(a.calculate ?? []), ...actionFeeCalculations];
+                if (moveCalculations.length)
+                    a.calculate = [...(a.calculate ?? []), ...moveCalculations];
                 if (attachmentInfo) {
                     if (attachmentInfo.exposed.has(name)) {
                         if (automatic(a.actor))
@@ -2199,6 +2275,13 @@ export function compile(source, options = {}) {
                 inst.actions[name] = a;
                 inst.actionOrder.push(name);
             }
+            for (const action of Object.values(inst.actions))
+                for (const move of action.moves)
+                    if ("transfer" in move) {
+                        const receipt = boundaryReceipts.get(move.transfer.replace(/^self\./, ""));
+                        if (receipt)
+                            move.transfer = `self.${receipt}`;
+                    }
             if (attachmentInfo && !attachmentInfo.child)
                 applyAttachmentEconomics(document, inst, attachmentInfo.parties, attachmentInfo.economics, data);
             for (const key of [
@@ -2403,6 +2486,17 @@ export function compile(source, options = {}) {
                     bindingDiagnostics.push(error.diagnostic);
                     continue;
                 }
+                // A business the instrument names itself binds like a parameter, so
+                // Build asks for it and the engine resolves its account and principal.
+                // programOperator and programTax are the company's own accounts.
+                for (const party of document.instruments
+                    .slice(firstAttachedInstrument)
+                    .flatMap(namedParties))
+                    if (document.parties[party]?.kind === "business" &&
+                        party !== "programOperator" &&
+                        party !== "programTax" &&
+                        !Object.values(parties).some((binding) => "party" in binding && binding.party === party))
+                        parties[party] ??= { party };
                 const attachedInst = document.instruments.find((i) => i.id === instId);
                 for (const createdInst of document.instruments
                     .slice(firstAttachedInstrument)