@hyperscale0/hsx 1.0.128 → 1.0.132

package/src/compile.ts

@@ -457,6 +457,9 @@ export function compile(
       UdlSubjectRequirement,
       { source: string; span: Span; message: string }
     >();
+    // Instruments that lost a std action to an empty all() parent. Their
+    // lifecycles drop the states only that action reached.
+    const trimmed = new Set<string>();
     const used = new Set<string>();
     for (const use of program.decls.filter((d) => d.kind === "use")) {
       if (used.has(use.name))
@@ -551,6 +554,15 @@ export function compile(
     const assignments = new Map<string, AssignmentDecl>();
     const attachmentSubjects = new Map<string, string>();
     const names = new Set<string>();
+    // A record's create turns public only through a program-level expose,
+    // which applies after lowering, so creation input needs the list first.
+    const exposedCreates = new Set(
+      program.decls.flatMap((decl) =>
+        decl.kind === "expose" && decl.target.endsWith(".create")
+          ? [decl.target.split(".").slice(0, -1).join("_")]
+          : [],
+      ),
+    );
     for (const decl of program.decls) {
       if (decl.kind === "expose" || decl.kind === "hide" || decl.kind === "use")
         continue;
@@ -1039,6 +1051,29 @@ export function compile(
         (!!attachmentInfo &&
           subjectPartyRoles.includes(name as SubjectPartyRole));
       const resolvedParties = new Set<string>();
+      // A party of a sibling attachment this one references, such as the
+      // borrower of `self.plan`, binds here the way it binds there.
+      const reachedParty = (
+        name: string,
+      ): AttachmentPartyBinding | undefined => {
+        if (!attachmentInfo) return;
+        const targets = fields.flatMap((field) =>
+          field.type === "ref" && field.targetKind === "instrument"
+            ? [field.target].flat()
+            : [],
+        );
+        const bindings = attachmentInfo.attachments.flatMap((attachment) =>
+          targets.some(
+            (target) =>
+              target === attachment.instrument ||
+              target.startsWith(`${attachment.instrument}_`),
+          ) && attachment.parties[name]
+            ? [attachment.parties[name]]
+            : [],
+        );
+        const distinct = new Set(bindings.map((item) => JSON.stringify(item)));
+        return distinct.size === 1 ? bindings[0] : undefined;
+      };
       const resolve = (
         expr: Expr,
         seen = new Set<string>(),
@@ -1098,6 +1133,18 @@ export function compile(
               attachmentSubjects.has(name)
                 ? name.slice(attachmentInfo.subjectKindId.length + 1)
                 : `${name} (program)`;
+            const elsewhere = [...assignments.values()]
+              .filter(
+                (assignment) =>
+                  assignment.target === type &&
+                  attachmentSubjects.has(assignment.name) &&
+                  attachmentSubjects.get(assignment.name) !==
+                    attachmentInfo.subjectKindId,
+              )
+              .map((assignment) => {
+                const subject = attachmentSubjects.get(assignment.name)!;
+                return `\`${subject}.${assignment.name.slice(subject.length + 1)}\``;
+              });
             const target = templates.get(type);
             const required =
               target?.parameters
@@ -1116,7 +1163,7 @@ export function compile(
               }`,
               matches.length
                 ? `Bind \`${parameter}\` explicitly to one of: ${matches.map(local).join(", ")}.`
-                : `Declare a ${parameter} attachment and bind \`${parameter}: allowance\`. Choose ${required.map((name) => (name.startsWith("per_") ? `its ${name.slice(4).replaceAll("_", " ")} limit` : `\`${name}\``)).join(", ") || "its required bindings"} explicitly.`,
+                : `Attach \`${type}\` to \`${attachmentInfo.subjectKindId}\` and bind \`${parameter}\` to that attachment's name. Choose ${required.map((name) => (name.startsWith("per_") ? `its ${name.slice(4).replaceAll("_", " ")} limit` : `\`${name}\``)).join(", ") || "its required bindings"} explicitly.${elsewhere.length ? ` ${elsewhere.join(", ")} ${elsewhere.length === 1 ? "is" : "are"} on another object, which this binding cannot reach.` : ""}`,
             );
           }
           if (expr.name !== "all" && matches.length !== 1)
@@ -1555,6 +1602,28 @@ export function compile(
             value: `${id}_${key}`,
             span: origin,
           });
+      // A subject role only has money here when this attachment binds it.
+      const moneyPath = (expr: Expr): string => {
+        const lowered = path(expr);
+        const role = lowered.slice("party.".length) as SubjectPartyRole;
+        if (
+          attachmentInfo &&
+          lowered.startsWith("party.") &&
+          subjectPartyRoles.includes(role) &&
+          !Object.values(attachmentInfo.parties).some(
+            (binding) => "role" in binding && binding.role === role,
+          )
+        )
+          failWithCode(
+            expr,
+            "subject_party_unbound",
+            `\`${role}\` has no money account in \`${decl.name}\``,
+            role === "operator"
+              ? "Use `programOperator` for the company's own account."
+              : `Add a party parameter to \`${decl.name}\` and bind it to \`${role}\` where you attach it.`,
+          );
+        return lowered;
+      };
       const fields: UdlField[] = [];
       const calculations: UdlCalculation[] = [];
       let currentAction: UdlAction | undefined;
@@ -2472,9 +2541,18 @@ export function compile(
                     `unknown economic purpose ${purposeName}`,
                     "choose a declared economic purpose",
                   );
-                const sourcePartyName = sourceParty
+                let sourcePartyName = sourceParty
                   ? String(data(sourceParty))
                   : undefined;
+                const reached =
+                  sourcePartyName && !isParty(sourcePartyName)
+                    ? reachedParty(sourcePartyName)
+                    : undefined;
+                if (reached) {
+                  attachmentInfo!.parties[sourcePartyName!] = reached;
+                  sourcePartyName =
+                    "role" in reached ? reached.role : reached.party;
+                }
                 if (sourcePartyName && !isParty(sourcePartyName))
                   fail(
                     sourceParty!,
@@ -2608,7 +2686,7 @@ export function compile(
                       operation: "internal_transfer.create",
                       ...(economics ? { economics } : {}),
                       amount: piece,
-                      from: path(from),
+                      from: moneyPath(from),
                       to: `party.${recipient.value}`,
                     });
                   }
@@ -2636,8 +2714,8 @@ export function compile(
                     ? { capture: String(data(parts.get("capture")!)) }
                     : {}),
                   amount: val(amount!),
-                  from: path(from!),
-                  to: path(to!),
+                  from: moneyPath(from!),
+                  to: moneyPath(to!),
                 };
                 const fee = parts.get("fee");
                 if (!fee)
@@ -2766,6 +2844,15 @@ export function compile(
                       } as Omit<UdlCalculation, "target">)
                     : undefined;
                   const charges = vat ? [charge, vat] : [charge];
+                  // A payer's limit reads this: a buyer pays the charges on
+                  // top, a seller pays them out of the amount.
+                  derived("debit", "Payer debit", {
+                    op: "sum",
+                    values:
+                      paidBy === "buyer"
+                        ? [transfer.amount, ...charges]
+                        : [transfer.amount],
+                  } as Omit<UdlCalculation, "target">);
                   const net =
                     paidBy === "seller"
                       ? derived("net", "Amount after fee", {
@@ -2842,7 +2929,7 @@ export function compile(
         }
         if (actionFeeCalculations.length)
           a.calculate = [...(a.calculate ?? []), ...actionFeeCalculations];
-        if (attachmentInfo && !attachmentInfo.child) {
+        if (attachmentInfo) {
           if (attachmentInfo.exposed.has(name)) {
             if (automatic(a.actor))
               fail(
@@ -2909,6 +2996,34 @@ export function compile(
             message: `${id}.${name}.subject.${requirement.field.name}`,
           });
         }
+        // A parent list may name a list parameter such as `[parent, on]`.
+        if (
+          typeof a.actor === "object" &&
+          "parent" in a.actor &&
+          Array.isArray(a.actor.parent)
+        )
+          a.actor.parent = a.actor.parent.flat();
+        // A parent actor over an empty all() names no instrument that could
+        // invoke the action. A std action then does not exist in this program;
+        // in user code the all() is a mistake.
+        if (
+          typeof a.actor === "object" &&
+          "parent" in a.actor &&
+          Array.isArray(a.actor.parent) &&
+          !a.actor.parent.length
+        ) {
+          if ((declarationSources.get(decl) ?? "program") === "program") {
+            const parent = entries(asBlock(slots.get("actor"))).get("parent");
+            fail(
+              parent ?? row,
+              `${parent?.kind === "call" ? `${parent.name}(${text(parent.args[0]!)})` : `the parent actor of ${name}`} matches no instrument`,
+              "name an instrument this program declares or attaches",
+            );
+          }
+          delete lifecycle.transitions[name];
+          trimmed.add(id);
+          continue;
+        }
         inst.actions[name] = a;
         inst.actionOrder.push(name);
       }
@@ -3196,8 +3311,7 @@ export function compile(
           .slice(firstAttachedInstrument)
           .filter(
             (instrument) =>
-              instrument.id === instId ||
-              instrument.actions.create?.publicAction,
+              instrument.id === instId || exposedCreates.has(instrument.id),
           )) {
           if (!createdInst.actions.create) continue;
           const owned = new Set(
@@ -3210,9 +3324,15 @@ export function compile(
           }
           const create = createdInst.actions.create;
           for (const field of createdInst.fields) {
+            // The engine resolves a lone candidate itself; with several (a
+            // plan's slices) the caller names one, as late_charge does.
+            if (field.type === "ref" && field.targetKind === "instrument") {
+              if (!create.input.some((input) => input.name === field.name))
+                create.input.push({ ...field, optional: true });
+              continue;
+            }
             if (
               field.type === "account" ||
-              (field.type === "ref" && field.targetKind === "instrument") ||
               (field.type === "list" &&
                 field.item === "ref" &&
                 field.targetKind === "instrument") ||
@@ -3222,8 +3342,7 @@ export function compile(
               create.input.some((input) => input.name === field.name)
             )
               continue;
-            create.subject ??= { requirements: [], adapters: [] };
-            const existing = create.subject.requirements.find(
+            const existing = create.subject?.requirements.find(
               (item) => item.field.name === field.name,
             );
             if (existing) {
@@ -3236,11 +3355,16 @@ export function compile(
                 );
               continue;
             }
+            // A creation value belongs to this agreement. Only a rename shares
+            // it as object metadata; a matching authored field name does not,
+            // so two agreements never read each other's amount.
             const objectField = renames.get(field.name);
-            const requirement = {
-              field,
-              ...(objectField ? { objectField } : {}),
-            };
+            if (!objectField) {
+              create.input.push({ ...field });
+              continue;
+            }
+            const requirement = { field, objectField };
+            create.subject ??= { requirements: [], adapters: [] };
             create.subject.requirements.push(requirement);
             requirementOrigins.set(requirement, {
               source: declarationSources.get(template) ?? "program",
@@ -3259,6 +3383,20 @@ export function compile(
             );
           if (!found) {
             const renameEntry = renameEntries.get(oldName) ?? entry;
+            const record = document.instruments
+              .slice(firstAttachedInstrument)
+              .find(
+                (instrument) =>
+                  instrument.id.startsWith(`${instId}_`) &&
+                  instrument.fields.some((field) => field.name === oldName),
+              );
+            if (record)
+              failWithCode(
+                renameEntry,
+                "subject_field_unknown",
+                `rename source '${oldName}' belongs to the ${record.id.slice(instId.length + 1)} record of ${targetTemplate}; rename binds only fields of ${targetTemplate} itself`,
+                `remove this rename; supply ${oldName} as input when the record is created, or set it as a tunable where the header offers one`,
+              );
             const declared = attachedInst
               ? Object.values(attachedInst.actions).flatMap(
                   (action) =>
@@ -3746,7 +3884,7 @@ export function compile(
     // 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: UdlSelection) => {
+    const declaredMembers = (selection: UdlSelection) => {
       const members = [selection.instrument].flat();
       const header = selection.family
         ? templates.get(
@@ -3764,13 +3902,64 @@ export function compile(
         resolveField(document, byId.get(id)!, `self.${selection.reference}`),
       );
     };
-    // A count over no matchable member is zero.
+    // A member whose reference points at another attachment of the anchor's
+    // own template (the plan funding another object's escrow) cannot match
+    // either, so each object only selects what can reference it.
+    const kin = (a: string, b: string) => {
+      const left = byId.get(a);
+      const right = byId.get(b);
+      return (
+        !!left && !!right && declarations.get(left) === declarations.get(right)
+      );
+    };
+    const matchable = (
+      selection: UdlSelection,
+      inst: UdlInstrument,
+      action?: UdlAction,
+    ) =>
+      declaredMembers(selection).filter((id) => {
+        const member = byId.get(id);
+        if (!member) return true;
+        const anchor = resolveField(
+          document,
+          inst,
+          selection.anchor,
+          action?.input,
+          action,
+        );
+        const reference = resolveField(
+          document,
+          member,
+          `self.${selection.reference}`,
+        );
+        if (anchor?.type !== "ref" || reference?.type !== "ref") return true;
+        const targets = [anchor.target].flat();
+        const candidates = [reference.target].flat();
+        return !candidates.every(
+          (candidate) =>
+            !targets.includes(candidate) &&
+            targets.some((target) => kin(target, candidate)),
+        );
+      });
+    // A count over no matchable member is zero, in a requirement or a calculation.
     for (const inst of document.instruments)
-      for (const action of Object.values(inst.actions))
+      for (const action of Object.values(inst.actions)) {
+        if (action.calculate)
+          action.calculate = action.calculate.map((calculation) =>
+            calculation.op === "aggregate" &&
+            calculation.measure === "count" &&
+            !matchable(calculation.selection, inst, action).length
+              ? {
+                  target: calculation.target,
+                  op: "sum",
+                  values: [{ literal: 0 }],
+                }
+              : calculation,
+          );
         action.requires = action.requires.map((requirement) =>
           requirement.kind === "aggregate" &&
           requirement.measure === "count" &&
-          !matchable(requirement.selection).length
+          !matchable(requirement.selection, inst, action).length
             ? {
                 kind: "compare",
                 left: { literal: 0 },
@@ -3779,14 +3968,21 @@ export function compile(
               }
             : requirement,
         );
+      }
     const checkSelection = (
       selection: UdlSelection,
       at: Located,
       scope: Scope,
     ) => {
+      walk(
+        selection.overlaps,
+        "overlaps",
+        site(selection, "overlaps", at),
+        scope,
+      );
       walk(selection.anchor, "anchor", site(selection, "anchor", at), scope);
       walk(selection.where, "where", site(selection, "where", at), scope);
-      const members = matchable(selection);
+      const members = matchable(selection, scope.inst, scope.action);
       if (
         members.length &&
         members.length < [selection.instrument].flat().length
@@ -3807,6 +4003,9 @@ export function compile(
         selection.order?.forEach((key, index) =>
           member(key, site(selection.order!, index, at)),
         );
+        if (selection.overlaps)
+          for (const key of ["start", "end"] as const)
+            member(selection.overlaps[key], site(selection.overlaps, key, at));
         if (selection.window)
           member(selection.window.field, site(selection.window, "field", at));
       }
@@ -3942,7 +4141,7 @@ export function compile(
         )
       )
         continue;
-      let specialized = false;
+      let specialized = trimmed.has(inst.id);
       for (const [key, action] of Object.entries(inst.actions)) {
         const constant = (value: import("@hyperscale0/udl").UdlValue) => {
           if ("literal" in value) return value.literal;
@@ -4060,6 +4259,28 @@ export function compile(
           "give each exposed action a distinct public name",
         );
     }
+    // A public action on a fresh attachment creates it first with no input
+    // (in the engine executor), so creation that needs input must be public.
+    for (const kind of document.objects)
+      for (const attachment of kind.attachments) {
+        if (attachment.parent) continue;
+        const instrument = byId.get(attachment.instrument)!;
+        const create = instrument.actions.create;
+        const needed = create?.input.filter((field) => !field.optional) ?? [];
+        const entry = Object.values(instrument.actions).find(
+          (action) => action.publicAction,
+        );
+        if (!needed.length || create!.publicAction || !entry) continue;
+        fail(
+          objects
+            .get(kind.id)!
+            .body.entries.find((row) =>
+              new RegExp(`^attach\\s+${attachment.name}\\s*=`).test(row.key),
+            ) ?? objects.get(kind.id)!,
+          `${attachment.name} starts from ${entry.publicAction}, but its create needs ${needed.map((field) => field.name).join(", ")} and is not exposed`,
+          `expose create on ${attachment.name} so the caller supplies ${needed.length === 1 ? "it" : "them"}, or rename { ${needed[0]!.name}: ${needed[0]!.name} } to read object metadata`,
+        );
+      }
     for (const kind of document.objects) {
       for (const name of kind.entryActions ?? []) {
         const eligible = kind.attachments.some((attachment) => {
@@ -4112,13 +4333,15 @@ export function compile(
                       ),
                   ),
               );
+            const reaching = stranded.actions.at(-1);
+            const drain = `move ${stranded.accounts.map((account) => `\`self.${account}.balance\``).join(" and ")} out in ${reaching ? `\`${reaching}\`` : "the action that reaches it"}, or add an action from \`${stranded.state}\` that does`;
             return diagnostic(
               {
                 code: i.code,
                 message: `\`${attachment?.name ?? instrument.id}\` can reach \`${stranded.state}\` with money in ${stranded.accounts.map((account) => `\`${account}\``).join(", ")}, but no action leaves that state and disposes of the balance.`,
                 fix: binding
-                  ? `Restore \`${binding.parameter}: ${stranded.state}\`, or author a complete refund path for every reachable funded state.`
-                  : "Author a complete refund path for every reachable funded state.",
+                  ? `Restore \`${binding.parameter}: ${stranded.state}\`, or ${drain}.`
+                  : `${drain[0]!.toUpperCase()}${drain.slice(1)}.`,
                 span: binding?.span ?? origin?.span ?? program.span,
                 related: stranded.accounts.map((account) => ({
                   source: "program",

package/src/examples-bundle.ts

@@ -1,19 +1,19 @@
 // Generated by open/hsx/scripts/bundle-examples.ts. Do not edit by hand.
 import type { HsxExample } from "./examples.ts";
 export const examples: HsxExample[] = [
-  {"id":"cards","title":"Team expense cards","summary":"A company issues expense cards to employees and reserves each supplier payment before capture.","headers":["cards"],"source":"// A company issues expense cards to employees and reserves each supplier payment before capture.\nprogram team_expense_cards \"Team expense cards\"\nuse cards\nparty supplier: business\n\nobject employee \"Employee card\" {\n  fields { employeeName: text, department: text }\n  columns: [employeeName, department]\n  attach holder = cards.cardholder {\n    expose create as create_holder\n    holder: owner\n    expose activate as activate_employee\n    expose suspend as suspend_employee\n  }\n  attach card = cards.card {\n    expose create as create_card\n    holder: holder, spend_limit: 5000 SAR\n    expose activate as activate_card\n    expose freeze as freeze_card\n    expose unfreeze as unfreeze_card\n  }\n  attach payment = cards.authorization {\n    expose create as create_payment\n    card: card, merchant: supplier\n    expose approve as approve_payment\n    expose capture as capture_payment\n    expose reverse as reverse_payment\n  }\n  attach receipt = cards.transaction {\n    expose create as create_receipt\n    authorization: payment\n    expose refund as refund_payment\n  }\n}\n"},
-  {"id":"collections","title":"Small business collections","summary":"A business lender refers overdue instalments to an agency with limits on collection contacts.","headers":["collections","financing"],"source":"// A business lender refers overdue instalments to an agency with limits on collection contacts.\nprogram business_collections \"Small business collections\"\nuse collections\nuse financing\nparty agency: business\n\nobject facility \"Business loan\" {\n  fields { businessName: text, purpose: text, price: money }\n  columns: [businessName, purpose, price]\n  attach allowance = financing.limits { expose create as create_allowance, expose approve as approve_borrower, borrower: owner, per_borrower: 100000 SAR }\n  attach budget = financing.portfolio_limit { expose create as create_budget, expose approve as approve_budget, limit: 2000000 SAR }\n  attach loan = financing.installments {\n    expose create as create_loan\n    borrower: owner, capital: operator\n    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_loan\n    expose disburse as release_loan\n    expose payoff as repay_early\n  }\n  attach recovery = collections.case {\n    expose create as create_recovery\n    on: loan, agency: agency\n    expose assign as assign_case\n    expose recover as recover_payment\n    expose recall as recall_case\n  }\n  attach contact = collections.contact {\n    expose create as create_contact\n    case: recovery, agency: agency\n  }\n}\n\nexpose facility.loan.payment.create as create_payment\nexpose facility.loan.payment.pay as pay_instalment\nexpose facility.loan.payment.refund as refund_payment\nexpose facility.loan.payoff_quote.create as request_payoff_quote\n"},
+  {"id":"cards","title":"Team expense cards","summary":"A company issues expense cards to employees and reserves each supplier payment before capture.","headers":["cards"],"source":"// A company issues expense cards to employees and reserves each supplier payment before capture.\nprogram team_expense_cards \"Team expense cards\"\nuse cards\n// supplier is a business this program declares, so plan needs {\"partyBindings\":{\"supplier\":\"<partyId>\"}}.\n// That partyId is an organization customer's: create the Product from this source without the payment\n// and receipt attachments, add the customer with customer.create, activate its access, open its\n// customer_balance account, then compose this source with the binding.\nparty supplier: business\n\nobject employee \"Employee card\" {\n  fields { employeeName: text, department: text }\n  columns: [employeeName, department]\n  attach holder = cards.cardholder {\n    expose create as create_holder\n    holder: owner\n    expose activate as activate_employee\n    expose suspend as suspend_employee\n  }\n  attach card = cards.card {\n    expose create as create_card\n    holder: holder, person: owner, spend_limit: 5000 SAR\n    expose activate as activate_card\n    expose freeze as freeze_card\n    expose unfreeze as unfreeze_card\n    expose issuer_freeze as block_card\n    expose issuer_unfreeze as unblock_card\n  }\n  attach payment = cards.authorization {\n    expose create as create_payment\n    card: card, merchant: supplier\n    expose approve as approve_payment\n    expose capture as capture_payment\n    expose reverse as reverse_payment\n  }\n  attach receipt = cards.transaction {\n    expose create as create_receipt\n    authorization: payment\n    expose refund as refund_payment\n  }\n}\n"},
+  {"id":"collections","title":"Small business collections","summary":"A business lender refers overdue instalments to an agency with limits on collection contacts.","headers":["collections","financing"],"source":"// A business lender refers overdue instalments to an agency with limits on collection contacts.\nprogram business_collections \"Small business collections\"\nuse collections\nuse financing\n// agency is a business this program declares, so plan needs {\"partyBindings\":{\"agency\":\"<partyId>\"}}.\n// That partyId is an organization customer's: create the Product from this source without the recovery\n// and contact attachments, add the customer with customer.create, activate its access, open its\n// customer_balance account, then compose this source with the binding.\nparty agency: business\n\nobject facility \"Business loan\" {\n  fields { businessName: text, purpose: text, price: money }\n  columns: [businessName, purpose, price]\n  attach allowance = financing.limits { expose create as create_allowance, expose approve as approve_borrower, borrower: owner, per_borrower: 100000 SAR }\n  attach budget = financing.portfolio_limit { expose create as create_budget, expose approve as approve_budget, limit: 2000000 SAR }\n  attach loan = financing.installments {\n    expose create as create_loan\n    borrower: owner, capital: operator\n    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_loan\n    expose disburse as release_loan\n    expose payoff as repay_early\n  }\n  attach recovery = collections.case {\n    expose create as create_recovery\n    on: loan, agency: agency\n    expose assign as assign_case\n    expose recover as recover_payment\n    expose recall as recall_case\n  }\n  attach contact = collections.contact {\n    expose create as create_contact\n    case: recovery, agency: agency\n  }\n}\n\nexpose facility.loan.payment.create as create_payment\nexpose facility.loan.payment.pay as pay_instalment\nexpose facility.loan.payment.refund as refund_payment\nexpose facility.loan.payoff_quote.create as request_payoff_quote\n"},
   {"id":"escrow","title":"Used device sales","summary":"Buyers fund a used device purchase, then accept delivery or raise a dispute before release.","headers":["escrow"],"source":"// Buyers fund a used device purchase, then accept delivery or raise a dispute before release.\nprogram used_device_sales \"Used device sales\"\nuse escrow\n\nobject device \"Device\" {\n  fields {\n    model: text\n    condition: text\n    serialNumber: text\n    price: money\n  }\n  columns: [model, condition, price]\n  attach sale = escrow.hold {\n    expose create as create_sale\n    payer: actor, payee: owner\n    expose fund as pay_for_device\n    expose deliver as confirm_delivery\n    expose accept as accept_device\n    expose dispute as report_problem\n    expose verify_return as verify_return\n    expose refund as refund_buyer\n    expose cancel as cancel_sale\n  }\n}\n"},
   {"id":"financing","title":"Tuition instalments","summary":"A tuition lender funds a student's fees over three interest-free instalments with borrowing limits.","headers":["financing"],"source":"// A tuition lender funds a student's fees over three interest-free instalments with borrowing limits.\nprogram tuition_instalments \"Tuition instalments\"\nuse financing\n\nobject enrolment \"Enrolment\" {\n  fields { student: text, course: text, price: money }\n  columns: [student, course, price]\n  attach allowance = financing.limits {\n    expose create as create_allowance\n    borrower: owner, per_borrower: 12000 SAR\n    expose approve as approve_student\n  }\n  attach budget = financing.portfolio_limit {\n    expose create as create_budget\n    limit: 500000 SAR\n    expose approve as approve_budget\n  }\n  attach tuition = financing.installments {\n    expose create as create_tuition\n    borrower: owner, capital: operator\n    months: 3, pricing: flat_total, profit_rate: 0%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_tuition_plan\n    expose disburse as fund_tuition\n    expose payoff as repay_early\n  }\n}\n\nexpose enrolment.tuition.payment.create as create_payment\nexpose enrolment.tuition.payment.pay as pay_instalment\nexpose enrolment.tuition.payment.refund as refund_payment\nexpose enrolment.tuition.payoff_quote.create as request_payoff_quote\n"},
-  {"id":"insurance","title":"Device insurance","summary":"A device retailer collects the purchase price and attaches cover with a claim review process.","headers":["insurance","money"],"source":"// A device retailer collects the purchase price and attaches cover with a claim review process.\nprogram device_insurance \"Device insurance\"\nuse insurance\nuse money\n\nobject device \"Insured device\" {\n  fields { model: text, serialNumber: text, purchaseDate: date }\n  columns: [model, serialNumber, purchaseDate]\n  attach purchase = money.transfer {\n    expose create as create_purchase\n    payer: owner, payee: operator\n    economics pay { purpose: earning, sourceParty: owner }\n    expose pay as pay_for_device\n  }\n  // conformance_boundary is the sandbox insurer adapter; swap in the insurer's registered adapter to go live.\n  // Premiums net of commission go to its account. claim_limit is the sum insured, set per cover at creation.\n  attach protection = insurance.cover {\n    expose create as create_protection\n    holder: owner, adapter: \"conformance_boundary\", commission: 10%, covers: purchase\n    expose activate as activate_cover\n    expose cancel as cancel_cover\n  }\n  attach claim = insurance.claim {\n    expose create as create_claim\n    cover: protection, inspector: operator\n    expose approve as approve_claim\n    expose deny as deny_claim\n    expose pay as pay_claim\n  }\n}\n"},
+  {"id":"insurance","title":"Device insurance","summary":"A device retailer collects the purchase price and attaches cover with a claim review process.","headers":["insurance","money"],"source":"// A device retailer collects the purchase price and attaches cover with a claim review process.\nprogram device_insurance \"Device insurance\"\nuse insurance\nuse money\n\nobject device \"Insured device\" {\n  fields { model: text, serialNumber: text, purchaseDate: date }\n  columns: [model, serialNumber, purchaseDate]\n  attach purchase = money.transfer {\n    expose create as create_purchase\n    payer: owner, payee: operator\n    economics pay { purpose: earning, sourceParty: owner }\n    expose pay as pay_for_device\n  }\n  // conformance_boundary is the sandbox insurer adapter; swap in the insurer's registered adapter to go live.\n  // Premiums net of commission go to its account. The default broker is the retailer, which keeps the commission.\n  // claim_limit is the sum insured, set per cover at creation.\n  attach protection = insurance.cover {\n    expose create as create_protection\n    holder: owner, adapter: \"conformance_boundary\", commission: 10%, covers: purchase\n    expose activate as activate_cover\n    expose cancel as cancel_cover\n  }\n  attach claim = insurance.claim {\n    expose create as create_claim\n    cover: protection, inspector: operator\n    expose approve as approve_claim\n    expose deny as deny_claim\n    expose pay as pay_claim\n  }\n}\n"},
   {"id":"lending","title":"Community business lending","summary":"A lending composition with limit approvals, wallet commitments and cash distribution transitions.","headers":["lending","financing","wallet"],"source":"// A lending composition with limit approvals, wallet commitments and cash distribution transitions.\nprogram community_business_lending \"Community business lending\"\nuse lending\nuse financing\nuse wallet\n\nobject business \"Business funding\" {\n  fields { businessName: text, purpose: text, price: money }\n  columns: [businessName, purpose, price]\n  attach allowance = financing.limits {\n    expose create as create_allowance\n    borrower: owner, per_borrower: 100000 SAR\n    expose approve as approve_borrower\n  }\n  attach budget = financing.portfolio_limit {\n    expose create as create_budget\n    limit: 2000000 SAR\n    expose approve as approve_budget\n  }\n  attach loan = financing.installments {\n    expose create as create_loan\n    borrower: owner, capital: operator\n    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_loan\n    expose disburse as release_loan\n    expose payoff as repay_early\n  }\n  attach investor_balance = wallet.balance {\n    expose create as create_investor_balance\n    holder: actor\n    expose activate as open_wallet\n    expose topup as add_funds\n  }\n  attach funding = lending.round {\n    borrower: owner, plan: loan\n    expose create as open_funding\n    expose close as close_funding\n  }\n  attach investment = lending.commitment {\n    round: funding, wallet: investor_balance, investor: actor\n    expose create as invest\n    expose withdraw as withdraw_investment\n  }\n  attach returns = lending.distribution {\n    expose create as create_returns\n    round: funding, receipt: loan.settlement\n    expose prepare_cash as prepare_returns\n    expose distribute_cash as distribute_returns\n  }\n}\n\nexpose business.loan.payment.create as create_payment\nexpose business.loan.payment.pay as pay_instalment\nexpose business.loan.payment.refund as refund_payment\nexpose business.loan.payoff_quote.create as request_payoff_quote\nexpose business.returns.share.create as create_return_share\n"},
   {"id":"library","title":"Financed car sales","summary":"A minimal financed car sale connects escrow to a three-instalment plan and lending limits.","headers":["escrow","financing"],"source":"// A minimal financed car sale connects escrow to a three-instalment plan and lending limits.\nprogram cars \"Financed car sales\"\nuse escrow\nuse financing\nobject car \"Cars\" {\n fields { make: text, model: text, year: integer }\n attach sale = escrow.hold { expose create as create_sale, payer: actor, payee: owner, expose fund as sell }\n attach limits = financing.limits { expose create as create_limits, borrower: actor, per_borrower: 60000 SAR }\n attach ceiling = financing.portfolio_limit { expose create as create_ceiling, limit: 1500000 SAR }\n attach plan = financing.installments {\n  borrower: actor, capital: operator, share: 25%\n  months: 3, pricing: flat_total, profit_rate: 2.5%, funds: sale, limits: limits, portfolio: ceiling\n  expose create as finance\n }\n}\n"},
-  {"id":"marketplace","title":"Freelance marketplace","summary":"Freelancers publish offers and clients place orders with funds held until work is accepted.","headers":["marketplace","escrow"],"source":"// Freelancers publish offers and clients place orders with funds held until work is accepted.\nprogram freelance_marketplace \"Freelance marketplace\"\nuse marketplace\nuse escrow\n\nobject project \"Project\" {\n  fields { brief: text, deliverable: text, price: money }\n  columns: [brief, deliverable, price]\n  attach offer = marketplace.listing {\n    expose create as create_offer\n    seller: owner\n    expose publish as publish_offer\n    expose withdraw as withdraw_offer\n  }\n  attach order = marketplace.order {\n    expose create as create_order\n    listing: offer, buyer: actor\n    expose commit as place_order\n    expose fulfill as finish_order\n  }\n  attach payment = escrow.hold {\n    expose create as create_payment\n    payer: actor, payee: owner\n    expose fund as fund_project\n    expose deliver as submit_work\n    expose accept as accept_work\n    expose dispute as dispute_work\n    expose verify_return as verify_return\n    expose refund as refund_client\n    expose cancel as cancel_payment\n  }\n}\n"},
+  {"id":"marketplace","title":"Freelance marketplace","summary":"Freelancers publish offers and clients place orders with funds held until work is accepted.","headers":["marketplace","escrow"],"source":"// Freelancers publish offers and clients place orders with funds held until work is accepted.\nprogram freelance_marketplace \"Freelance marketplace\"\nuse marketplace\nuse escrow\n\nobject project \"Project\" {\n  fields { brief: text, deliverable: text, price: money }\n  columns: [brief, deliverable, price]\n  attach offer = marketplace.listing {\n    rename { price: price }\n    expose create as create_offer\n    seller: owner\n    expose publish as publish_offer\n    expose withdraw as withdraw_offer\n  }\n  attach order = marketplace.order {\n    rename { price: price }\n    expose create as create_order\n    listing: offer, buyer: actor, fulfiller: owner\n    expose commit as place_order\n    expose fulfill as finish_order\n  }\n  attach payment = escrow.hold {\n    expose create as create_payment\n    payer: actor, payee: owner\n    expose fund as fund_project\n    expose deliver as submit_work\n    expose accept as accept_work\n    expose dispute as dispute_work\n    expose verify_return as verify_return\n    expose refund as refund_client\n    expose cancel as cancel_payment\n  }\n}\n"},
   {"id":"money","title":"Tutoring studio","summary":"A tutoring studio collects a fixed fee for each lesson and can cancel unpaid bookings.","headers":["money"],"source":"// A tutoring studio collects a fixed fee for each lesson and can cancel unpaid bookings.\nprogram tutoring_studio \"Tutoring studio\"\nuse money\n\nobject lesson \"Lesson\" {\n  fields {\n    student: text\n    tutor: text\n    startsAt: date\n  }\n  columns: [student, tutor, startsAt]\n  attach payment = money.transfer {\n    expose create as create_payment\n    payer: actor, payee: operator, amount: 150 SAR\n    economics pay { purpose: earning, sourceParty: actor }\n    expose pay as pay_for_lesson\n    expose cancel as cancel_payment\n  }\n}\n"},
-  {"id":"rental-deposit","title":"Equipment rental","summary":"A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee. On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR.","headers":[],"source":"// A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee.\n// On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR.\nprogram equipment_rental \"Equipment rental\"\nparty renter: business\n\n// The renter is one declared business, so this instrument takes no parameters.\ninstrument deposit {\n  summary: \"Hold a rental deposit, then return it less any fixed late fee.\"\n  fields {\n    renter: account of renter\n    held: account of self\n    amount: money = 1000 SAR\n    lateFee: money = 50 SAR\n    dueAt: date\n    refund: money?\n  }\n  lifecycle { states: [pending, funded, returned, cancelled], initial: pending }\n  action create {\n    actor: { party: renter }\n    requires self.dueAt > self.now\n  }\n  action fund {\n    from: pending, to: funded, actor: { party: renter }\n    deadline: { at: self.dueAt }\n    moves self.amount from self.renter to self.held\n  }\n  action return_on_time {\n    from: funded, to: returned, actor: { party: programOperator }\n    deadline: { at: self.dueAt }\n    subject { returnReference: text }\n    moves self.held.balance from self.held to self.renter\n  }\n  action return_late {\n    from: funded, to: returned, actor: { party: programOperator }\n    due: { at: self.dueAt }\n    subject { returnReference: text }\n    calculate: [{ target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.lateFee }] }]\n    moves self.lateFee from self.held to programOperator\n    moves self.refund from self.held to self.renter\n  }\n  action cancel { from: pending, to: cancelled, actor: { party: renter } }\n}\n\nobject rental \"Equipment rental\" {\n  fields { equipment: text }\n  columns: [equipment, dueAt]\n  attach security = deposit {\n    expose create as agree_rental\n    expose fund as pay_deposit\n    expose return_on_time as return_equipment\n    expose return_late as return_equipment_late\n    expose cancel as cancel_rental\n  }\n}\n\nhide deposit.create\nhide deposit.fund\nhide deposit.return_on_time\nhide deposit.return_late\nhide deposit.cancel\n"},
+  {"id":"rental-deposit","title":"Equipment rental","summary":"A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee. On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR.","headers":[],"source":"// A business rents equipment with a 1000 SAR deposit and a single 50 SAR late fee.\n// On-time return refunds 1000 SAR; late return pays the operator 50 SAR and refunds 950 SAR.\nprogram equipment_rental \"Equipment rental\"\nparty renter: business\n\n// The renter is one declared business, so this instrument takes no parameters.\ninstrument deposit {\n  summary: \"Hold a rental deposit, then return it less any fixed late fee.\"\n  fields {\n    renter: account of renter\n    held: account of self\n    amount: money = 1000 SAR\n    lateFee: money = 50 SAR\n    dueAt: date\n    refund: money?\n  }\n  lifecycle { states: [pending, funded, returned, cancelled], initial: pending }\n  action create {\n    actor: { party: renter }\n    requires self.dueAt > self.now\n  }\n  action fund {\n    from: pending, to: funded, actor: { party: renter }\n    deadline: { at: self.dueAt }\n    moves self.amount from self.renter to self.held\n  }\n  action return_on_time {\n    from: funded, to: returned, actor: { party: programOperator }\n    deadline: { at: self.dueAt }\n    subject { returnReference: text }\n    moves self.held.balance from self.held to self.renter\n  }\n  action return_late {\n    from: funded, to: returned, actor: { party: programOperator }\n    due: { at: self.dueAt }\n    subject { returnReference: text }\n    calculate: [{ target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.lateFee }] }]\n    moves self.lateFee from self.held to programOperator\n    moves self.refund from self.held to self.renter\n  }\n  action cancel { from: pending, to: cancelled, actor: { party: renter } }\n}\n\nobject rental \"Equipment rental\" {\n  fields { equipment: text }\n  columns: [equipment, dueAt]\n  attach security = deposit {\n    // dueAt is a column, so it stays shared object metadata.\n    rename { dueAt: dueAt }\n    expose create as agree_rental\n    expose fund as pay_deposit\n    expose return_on_time as return_equipment\n    expose return_late as return_equipment_late\n    expose cancel as cancel_rental\n  }\n}\n\nhide deposit.create\nhide deposit.fund\nhide deposit.return_on_time\nhide deposit.return_late\nhide deposit.cancel\n"},
   {"id":"repair-approval","title":"Repair approvals","summary":"A repair shop records inspection and approval evidence before it can complete a job.","headers":[],"source":"// A repair shop records inspection and approval evidence before it can complete a job.\nprogram repair_shop \"Repair approvals\"\n\ninstrument assessment {\n  summary: \"Inspect the repair, collect approval, then record completion.\"\n  fields { inspectedAt: date?, approvedAt: date? }\n  lifecycle { states: [submitted, inspected, approved, completed, rejected], initial: submitted }\n  action create {}\n  action inspect {\n    from: submitted, to: inspected, actor: { party: programOperator }\n    subject { inspectionNotes: text }\n    set: { inspectedAt: { field: self.now } }\n  }\n  action approve {\n    from: inspected, to: approved, actor: { party: programOperator }\n    subject { approvalReference: text }\n    set: { approvedAt: { field: self.now } }\n  }\n  action reject {\n    from: inspected, to: rejected, actor: { party: programOperator }\n  }\n  action complete {\n    from: approved, to: completed, actor: { party: programOperator }\n    subject { completionNotes: text }\n  }\n}\n\nobject repair \"Repair\" {\n  fields { item: text, problem: text }\n  columns: [item, problem]\n  attach review = assessment {\n    expose create as create_review\n    expose inspect as inspect_repair\n    expose approve as approve_repair\n    expose reject as reject_repair\n    expose complete as complete_repair\n  }\n}\n\nhide assessment.create\nhide assessment.inspect\nhide assessment.approve\nhide assessment.reject\nhide assessment.complete\n"},
   {"id":"reporting","title":"Equipment loan reports","summary":"An equipment lender keeps an ageing report over its financed purchases and recorded repayments.","headers":["reporting","financing"],"source":"// An equipment lender keeps an ageing report over its financed purchases and recorded repayments.\nprogram equipment_loan_reports \"Equipment loan reports\"\nuse reporting\nuse financing\n\nobject purchase \"Equipment loan\" {\n  fields { businessName: text, equipment: text, price: money }\n  columns: [businessName, equipment, price]\n  attach allowance = financing.limits {\n    expose create as create_allowance\n    borrower: owner, per_borrower: 200000 SAR\n    expose approve as approve_business\n  }\n  attach budget = financing.portfolio_limit {\n    expose create as create_budget\n    limit: 5000000 SAR\n    expose approve as approve_budget\n  }\n  attach loan = financing.installments {\n    expose create as create_loan\n    borrower: owner, capital: operator\n    months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_purchase_loan\n    expose disburse as fund_purchase\n  }\n  attach reports = reporting.portfolio { expose create as create_reports, on: loan }\n}\n"},
   {"id":"savings","title":"Savings circle","summary":"Six members contribute to a shared pot and receive it in their agreed calendar order.","headers":["savings"],"source":"// Six members contribute to a shared pot and receive it in their agreed calendar order.\nprogram neighbourhood_savings \"Savings circle\"\nuse savings\n\nobject group \"Savings group\" {\n  fields { groupName: text, purpose: text }\n  columns: [groupName, purpose]\n  attach circle = savings.circle {\n    expose create as create_circle\n    contribution: 500 SAR, members: 6, starts: 2027-01-01\n    expose disband as disband_circle\n    expose close as close_circle\n  }\n  attach membership = savings.membership {\n    expose create as create_membership\n    circle: circle, member: actor\n    expose activate as confirm_membership\n    expose withdraw as leave_circle\n  }\n  // Contributions and each member's payout follow the declared calendar.\n}\n"},
   {"id":"serviced","title":"Car financing","summary":"A car finance company services loans with late charges, payment reminders and early repayment.","headers":["escrow","financing","collections"],"source":"// A car finance company services loans with late charges, payment reminders and early repayment.\nprogram car_financing \"Car financing\"\nuse escrow\nuse financing\nuse collections\nobject car \"Car\" {\n fields { make: text, model: text, year: integer, vin: text, price: money }\n columns: [make, model, year, vin, price]\n attach sale = escrow.hold { expose create as create_sale, payer: actor, payee: operator, expose fund as purchase }\n attach limits = financing.limits { expose create as create_limits, borrower: actor, per_borrower: 250000 SAR }\n attach ceiling = financing.portfolio_limit { expose create as create_ceiling, limit: 10000000 SAR }\n attach plan = financing.installments {\n  borrower: actor, capital: operator\n  months: 36, pricing: flat_total, profit_rate: 8.5%, down_payment: 10%\n  apply: fines_profit_principal, payoff_rebate: 100%, write_off_after: 90d\n  funds: sale, limits: limits, portfolio: ceiling\n  expose create as finance, expose sign as sign_contract, expose payoff as payoff\n }\n attach late = financing.late_charge {\n   expose create as create_late\n  on: plan, grace: 3d, fine: 50 SAR, cap: 25 SAR\n  fines_to: operator, costs_to: operator, borrower: actor\n }\n attach reminders = collections.reminder { expose create as create_reminders, on: plan, operator: operator, before_days: 3, overdue_days: 1 }\n}\n"},
-  {"id":"wallet","title":"Workshop credits","summary":"Members prepay for workshop visits and the studio reserves each spend before charging it.","headers":["wallet"],"source":"// Members prepay for workshop visits and the studio reserves each spend before charging it.\nprogram workshop_credits \"Workshop credits\"\nuse wallet\n\nobject membership \"Membership\" {\n  fields { memberName: text, membershipNumber: text }\n  columns: [memberName, membershipNumber]\n  attach balance = wallet.balance {\n    expose create as create_balance\n    holder: owner\n    expose activate as open_balance\n    expose topup as add_credit\n    expose withdraw as withdraw_credit\n    expose close as close_balance\n  }\n  attach visit = wallet.spend {\n    expose create as create_visit\n    wallet: balance, payee: operator\n    economics pay { purpose: earning, sourceParty: owner }\n    expose reserve as reserve_visit\n    expose pay as charge_visit\n    expose cancel as cancel_visit\n  }\n}\n"},
+  {"id":"wallet","title":"Workshop credits","summary":"Members prepay for workshop visits and the studio reserves each spend before charging it.","headers":["wallet"],"source":"// Members prepay for workshop visits and the studio reserves each spend before charging it.\nprogram workshop_credits \"Workshop credits\"\nuse wallet\n\nobject membership \"Membership\" {\n  fields { memberName: text, membershipNumber: text }\n  columns: [memberName, membershipNumber]\n  attach balance = wallet.balance {\n    expose create as create_balance\n    holder: owner\n    expose activate as open_balance\n    expose topup as add_credit\n    expose withdraw as withdraw_credit\n    expose close as close_balance\n  }\n  attach visit = wallet.spend {\n    expose create as create_visit\n    wallet: balance, payee: operator, holder: owner\n    economics pay { purpose: earning, sourceParty: owner }\n    expose reserve as reserve_visit\n    expose pay as charge_visit\n    expose cancel as cancel_visit\n  }\n}\n"},
 ];

package/src/parse.ts

@@ -471,13 +471,16 @@ class Parser {
       this.fail("expression nesting exceeds 32", "reduce nested values");
     const start = this.peek().span.start;
     let value = this.atom();
-    if (this.eat("cap"))
+    // `cap:` starts the next entry, so a field may still be named cap.
+    if (this.at("cap") && this.tokens[this.index + 1]?.text !== ":") {
+      this.take();
       value = {
         kind: "capped",
         rate: value,
         cap: this.atom(),
         span: this.span(start),
       };
+    }
     if (this.eat("="))
       value = {
         kind: "default",