@hyperscale0/hsx 4.1.1 → 4.3.0

package/examples/marketplace.hsx

@@ -0,0 +1,26 @@
+// Freelancers publish offers and clients place orders with funds held until work is accepted.
+program freelance_marketplace "Freelance marketplace"
+use marketplace
+use escrow
+
+object project "Project" {
+  fields { brief: text, deliverable: text, price: money }
+  columns: [brief, deliverable, price]
+  attach offer = marketplace.listing {
+    seller: owner
+    expose publish as publish_offer
+    expose withdraw as withdraw_offer
+  }
+  attach order = marketplace.order {
+    listing: offer, buyer: actor
+    expose commit as place_order
+    expose fulfill as finish_order
+  }
+  attach payment = escrow.hold {
+    payer: actor, payee: owner
+    expose fund as fund_project
+    expose deliver as submit_work
+    expose accept as accept_work
+    expose dispute as dispute_work
+  }
+}

package/examples/money.hsx

@@ -0,0 +1,17 @@
+// A tutoring studio collects a fixed fee for each lesson and can cancel unpaid bookings.
+program tutoring_studio "Tutoring studio"
+use money
+
+object lesson "Lesson" {
+  fields {
+    student: text
+    tutor: text
+    startsAt: date
+  }
+  columns: [student, tutor, startsAt]
+  attach payment = money.transfer {
+    payer: actor, payee: operator, amount: 150 SAR
+    expose pay as pay_for_lesson
+    expose cancel as cancel_payment
+  }
+}

package/examples/reporting.hsx

@@ -0,0 +1,25 @@
+// An equipment lender keeps an ageing report over its financed purchases and recorded repayments.
+program equipment_loan_reports "Equipment loan reports"
+use reporting
+use financing
+
+object purchase "Equipment loan" {
+  fields { businessName: text, equipment: text, price: money }
+  columns: [businessName, equipment, price]
+  attach allowance = financing.limits {
+    borrower: owner, per_borrower: 200000 SAR
+    expose approve as approve_business
+  }
+  attach budget = financing.portfolio_limit {
+    limit: 5000000 SAR
+    expose approve as approve_budget
+  }
+  attach loan = financing.installments {
+    borrower: owner, capital: operator
+    months: 12, profit: 6%, disburse_to: borrower
+    limits: allowance, portfolio: budget
+    expose sign as sign_purchase_loan
+    expose disburse as fund_purchase
+  }
+  attach reports = reporting.portfolio { on: loan }
+}

package/examples/savings.hsx

@@ -0,0 +1,19 @@
+// Six members contribute to a shared pot and receive it in their agreed calendar order.
+program neighbourhood_savings "Savings circle"
+use savings
+
+object group "Savings group" {
+  fields { groupName: text, purpose: text }
+  columns: [groupName, purpose]
+  attach circle = savings.circle {
+    contribution: 500 SAR, members: 6, starts: 2027-01-01
+    expose disband as disband_circle
+    expose close as close_circle
+  }
+  attach membership = savings.membership {
+    circle: circle, member: actor
+    expose activate as confirm_membership
+    expose withdraw as leave_circle
+  }
+  // Contributions and each member's payout follow the declared calendar.
+}

package/examples/serviced.hsx

@@ -1,3 +1,4 @@
+// A car finance company services loans with late charges, payment reminders and early repayment.
 program car_financing "Car financing"
 use escrow
 use financing

package/examples/travel.hsx

@@ -0,0 +1,26 @@
+// A travel agency takes deposits for an insured holiday and pays its supplier after confirmation.
+program travel_agency "Travel agency"
+use travel
+use insurance
+party hotel: business
+
+object holiday "Holiday booking" {
+  fields { destination: text, leadTraveller: text }
+  columns: [destination, leadTraveller]
+  attach trip = travel.package {
+    price: 5000 SAR, supplier_cost: 3500 SAR, departure: 2027-07-01
+    expose publish as publish_trip
+  }
+  // Bind travel_insurer to an ADL adapter before activating cover.
+  attach protection = insurance.cover {
+    holder: actor, adapter: "travel_insurer", covers: reservation
+    expose activate as activate_cover
+  }
+  attach reservation = travel.booking {
+    package: trip, buyer: actor, supplier: hotel, cover: protection
+    expose deposit as pay_deposit
+    expose balance as pay_balance
+    expose confirm as confirm_completion
+    expose cancel_early as cancel_booking
+  }
+}

package/examples/wallet.hsx

@@ -0,0 +1,21 @@
+// Members prepay for workshop visits and the studio reserves each spend before charging it.
+program workshop_credits "Workshop credits"
+use wallet
+
+object membership "Membership" {
+  fields { memberName: text, membershipNumber: text }
+  columns: [memberName, membershipNumber]
+  attach balance = wallet.balance {
+    holder: owner
+    expose activate as open_balance
+    expose topup as add_credit
+    expose withdraw as withdraw_credit
+    expose close as close_balance
+  }
+  attach visit = wallet.spend {
+    wallet: balance, payee: operator
+    expose reserve as reserve_visit
+    expose pay as charge_visit
+    expose cancel as cancel_visit
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -40,6 +40,14 @@
       "types": "./dist/src/cost.d.ts",
       "default": "./dist/src/cost.js"
     },
+    "./examples": {
+      "types": "./dist/src/examples.d.ts",
+      "default": "./dist/src/examples.js"
+    },
+    "./language": {
+      "types": "./dist/src/language.d.ts",
+      "default": "./dist/src/language.js"
+    },
     "./package.json": "./package.json",
     "./std/*": "./std/*"
   },
@@ -71,9 +79,10 @@
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "std:bundle": "bun scripts/bundle-std.ts",
-    "generate": "bun run std:bundle && bun run docs:build",
-    "prepare": "bun run std:bundle",
-    "check": "bun run typecheck && tsc -p playground/tsconfig.json && bun test test"
+    "generate": "bun run std:bundle && bun run examples:bundle && bun run docs:build",
+    "prepare": "bun run std:bundle && bun run examples:bundle",
+    "check": "bun run typecheck && tsc -p playground/tsconfig.json && bun test test",
+    "examples:bundle": "bun scripts/bundle-examples.ts"
   },
   "dependencies": {
     "@hyperscale0/adl": "1.0.0-beta.8",
@@ -89,5 +98,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "42fc8744b74e9b251196ee5743897b3aff3ca9e3"
+  "gitHead": "c02b50cd28968db4b64bededd947e74f62fe5a4b"
 }

package/src/compile.ts

@@ -848,7 +848,9 @@ export function compile(
             { span: origin },
             partyParameter ? "subject_party_unbound" : "HSX1001",
             `${id} needs ${param.key}`,
-            `add ${param.key}: value inside ${id}`,
+            partyParameter
+              ? `bind ${param.key} to ${[...subjectPartyRoles, ...Object.keys(document.parties)].join(", ")} or declare a party`
+              : `add ${param.key}: value inside ${id}`,
           );
         }
         environment.set(param.key, actual);
@@ -932,7 +934,8 @@ export function compile(
             (binding.kind === "name" && binding.value === expr.value))
         )
           return expr;
-        if (attachmentInfo) {
+        // A resolved party parameter takes precedence over a same-named attachment.
+        if (attachmentInfo && !resolvedParties.has(expr.value)) {
           const [local, ...tail] = expr.value.split(".");
           const target = `${attachmentInfo.subjectKindId}_${local}`;
           if (attachmentSubjects.has(target))
@@ -1004,7 +1007,9 @@ export function compile(
               actual,
               attachmentInfo ? "subject_party_unbound" : "HSX1001",
               `${param.key} needs a declared party`,
-              "declare a party and use its name here",
+              attachmentInfo
+                ? `bind ${param.key} to ${[...subjectPartyRoles, ...Object.keys(document.parties)].join(", ")} or declare a party`
+                : "declare a party and use its name here",
             );
           const party = document.parties[v.value];
           if (
@@ -2561,11 +2566,21 @@ export function compile(
             );
           if (!found) {
             const renameEntry = renameEntries.get(oldName) ?? entry;
+            const declared = attachedInst
+              ? Object.values(attachedInst.actions).flatMap(
+                  (action) =>
+                    action.subject?.requirements.map(
+                      (requirement) => requirement.field.name,
+                    ) ?? [],
+                )
+              : [];
             failWithCode(
               renameEntry,
               "subject_field_unknown",
               `rename source '${oldName}' is not a declared subject requirement of ${targetTemplate}`,
-              "rename a declared subject requirement",
+              declared.length
+                ? `rename one of: ${[...new Set(declared)].join(", ")}`
+                : "rename a declared subject requirement",
             );
           }
         }

package/src/examples-bundle.ts

@@ -0,0 +1,18 @@
+// 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    holder: owner\n    expose activate as activate_employee\n    expose suspend as suspend_employee\n  }\n  attach card = cards.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    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    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 { borrower: owner, per_borrower: 100000 SAR }\n  attach budget = financing.portfolio_limit { limit: 2000000 SAR }\n  attach loan = financing.installments {\n    borrower: owner, capital: operator\n    months: 12, profit: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_loan\n    expose disburse as release_loan\n  }\n  attach recovery = collections.case {\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    case: recovery, agency: agency\n  }\n}\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    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  }\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    borrower: owner, per_borrower: 12000 SAR\n    expose approve as approve_student\n  }\n  attach budget = financing.portfolio_limit {\n    limit: 500000 SAR\n    expose approve as approve_budget\n  }\n  attach tuition = financing.installments {\n    borrower: owner, capital: operator\n    months: 3, profit: 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"},
+  {"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\nparty inspector: staff role claims\n\nobject device \"Insured device\" {\n  fields { model: text, serialNumber: text, purchaseDate: date }\n  columns: [model, serialNumber, purchaseDate]\n  attach purchase = money.transfer {\n    payer: owner, payee: operator\n    expose pay as pay_for_device\n  }\n  // Bind device_insurer to an ADL adapter before activating cover.\n  attach protection = insurance.cover {\n    holder: owner, adapter: \"device_insurer\", covers: purchase\n    expose activate as activate_cover\n    expose cancel as cancel_cover\n  }\n  attach claim = insurance.claim {\n    cover: protection, inspector: inspector\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":"Investors fund a small business loan from their wallets and share its recorded repayments.","headers":["lending","financing","wallet"],"source":"// Investors fund a small business loan from their wallets and share its recorded repayments.\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 { borrower: owner, per_borrower: 100000 SAR }\n  attach budget = financing.portfolio_limit { limit: 2000000 SAR }\n  attach loan = financing.installments {\n    borrower: owner, capital: operator\n    months: 12, profit: 6%, disburse_to: borrower\n    limits: allowance, portfolio: budget\n    expose sign as sign_loan\n    expose disburse as release_loan\n  }\n  attach investor_balance = wallet.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 close as close_funding\n  }\n  attach investment = lending.commitment {\n    round: funding, wallet: investor_balance, investor: actor\n    expose withdraw as withdraw_investment\n  }\n  attach returns = lending.distribution {\n    round: funding, receipt: loan.settlement\n  }\n}\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 { payer: actor, payee: owner, expose fund as sell }\n attach limits = financing.limits { borrower: actor, per_borrower: 60000 SAR }\n attach ceiling = financing.portfolio_limit { limit: 1500000 SAR }\n attach plan = financing.installments {\n  borrower: actor, capital: operator, share: 25%\n  months: 3, profit: 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    seller: owner\n    expose publish as publish_offer\n    expose withdraw as withdraw_offer\n  }\n  attach order = marketplace.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    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  }\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    payer: actor, payee: operator, amount: 150 SAR\n    expose pay as pay_for_lesson\n    expose cancel as cancel_payment\n  }\n}\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    borrower: owner, per_borrower: 200000 SAR\n    expose approve as approve_business\n  }\n  attach budget = financing.portfolio_limit {\n    limit: 5000000 SAR\n    expose approve as approve_budget\n  }\n  attach loan = financing.installments {\n    borrower: owner, capital: operator\n    months: 12, profit: 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 { 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    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    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 { payer: actor, payee: operator, expose fund as purchase }\n attach limits = financing.limits { borrower: actor, per_borrower: 250000 SAR }\n attach ceiling = financing.portfolio_limit { limit: 10000000 SAR }\n attach plan = financing.installments {\n  borrower: actor, capital: operator\n  months: 36, profit: 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  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 { on: plan, operator: operator, before_days: 3, overdue_days: 1 }\n}\n"},
+  {"id":"travel","title":"Travel agency","summary":"A travel agency takes deposits for an insured holiday and pays its supplier after confirmation.","headers":["travel","insurance"],"source":"// A travel agency takes deposits for an insured holiday and pays its supplier after confirmation.\nprogram travel_agency \"Travel agency\"\nuse travel\nuse insurance\nparty hotel: business\n\nobject holiday \"Holiday booking\" {\n  fields { destination: text, leadTraveller: text }\n  columns: [destination, leadTraveller]\n  attach trip = travel.package {\n    price: 5000 SAR, supplier_cost: 3500 SAR, departure: 2027-07-01\n    expose publish as publish_trip\n  }\n  // Bind travel_insurer to an ADL adapter before activating cover.\n  attach protection = insurance.cover {\n    holder: actor, adapter: \"travel_insurer\", covers: reservation\n    expose activate as activate_cover\n  }\n  attach reservation = travel.booking {\n    package: trip, buyer: actor, supplier: hotel, cover: protection\n    expose deposit as pay_deposit\n    expose balance as pay_balance\n    expose confirm as confirm_completion\n    expose cancel_early as cancel_booking\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    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    wallet: balance, payee: operator\n    expose reserve as reserve_visit\n    expose pay as charge_visit\n    expose cancel as cancel_visit\n  }\n}\n"},
+];

package/src/examples.ts

@@ -0,0 +1,9 @@
+/** Authored programs shipped with the compiler, generated from examples/*.hsx. */
+export interface HsxExample {
+  id: string;
+  title: string;
+  summary: string;
+  headers: string[];
+  source: string;
+}
+export { examples } from "./examples-bundle.ts";

package/src/headers.ts

@@ -21,10 +21,11 @@ export const HEADER_NAMES = [
 /** The compiler frontend owns header metadata used by docs and catalogue consumers. */
 export function headerManifest(
   library: StandardLibrary = bundledStandardLibrary,
+  names: readonly string[] = HEADER_NAMES,
 ) {
   return {
     version: 4,
-    headers: HEADER_NAMES.map((name) => {
+    headers: names.map((name) => {
       const source = library.source(name);
       if (!source) throw new Error(`Missing standard header ${name}`);
       const parsed = parseProgram(source);
@@ -102,6 +103,23 @@ export function headerManifest(
             return {
               name: decl.name,
               qualifiedName: `${name}.${decl.name}`,
+              signature: source
+                .slice(decl.span.start, decl.body.span.start)
+                .replace(/^instrument\s+/, "")
+                .trim(),
+              states: (() => {
+                const lifecycle = decl.body.entries.find(
+                  (entry) => entry.key === "lifecycle",
+                )?.value;
+                const states =
+                  lifecycle?.kind === "block"
+                    ? lifecycle.entries.find((entry) => entry.key === "states")
+                        ?.value
+                    : undefined;
+                return states?.kind === "list"
+                  ? states.items.map(spelling)
+                  : [];
+              })(),
               summary:
                 summary?.kind === "text"
                   ? summary.value
@@ -145,6 +163,24 @@ export function headerManifest(
               parties: tunables
                 .filter((t) => t.type === "party")
                 .map((t) => t.name),
+              // Fields the attached object must carry (or rename to) before
+              // the instrument's actions can read them.
+              subject: (() => {
+                const fields = new Map<string, string>();
+                for (const entry of decl.body.entries) {
+                  if (!entry.key.startsWith("action ")) continue;
+                  if (entry.value.kind !== "block") continue;
+                  const subject = entry.value.entries.find(
+                    (slot) => slot.key === "subject",
+                  )?.value;
+                  if (subject?.kind !== "block") continue;
+                  for (const field of subject.entries) {
+                    const type = spelling(field.value);
+                    if (type !== "adapter") fields.set(field.key, type);
+                  }
+                }
+                return [...fields].map(([name, type]) => ({ name, type }));
+              })(),
               actions: actions(decl.body),
             };
           }),

package/src/keywords.ts

@@ -0,0 +1,126 @@
+import type { KEYWORDS } from "./lex.ts";
+
+/** Business explanations shared by every HSX editor. */
+export const KEYWORD_HELP = {
+  program: [
+    "Names the financial product and gives it a title.",
+    "Product contract",
+  ],
+  header: ["Names a reusable library of instruments."],
+  use: ["Makes a header's instruments available to this program."],
+  party: [
+    "Declares a person or business that can own accounts or act in an agreement.",
+    "Parties",
+  ],
+  role: ["Names the responsibility a declared party has in this product."],
+  currency: ["Sets the currency used by the program's money amounts."],
+  instrument: [
+    "Defines an agreement's fields, states and permitted actions.",
+    "Instruments",
+  ],
+  fields: ["Declares the values an object or agreement retains.", "Fields"],
+  lifecycle: [
+    "Lists the agreement's possible states and its starting state.",
+    "Lifecycle",
+  ],
+  action: [
+    "Defines an operation that can change an agreement or move money.",
+    "Actions",
+  ],
+  expose: [
+    "Makes an attached action available under a public name.",
+    "Object action bindings",
+  ],
+  hide: ["Removes an action from the program's public actions."],
+  as: ["Gives an exposed action its public name."],
+  cap: ["Limits a percentage charge to a maximum money amount.", "Capped rate"],
+  of: [
+    "Names the owner of an account, or the records included in a count or sum.",
+  ],
+  when: ["Includes rules only when a parameter selects the stated option."],
+  constraints: [
+    "Requires parameter values to agree with each other before the program can be used.",
+  ],
+  requires: [
+    "Rejects an action unless the stated condition holds.",
+    "Requirements",
+  ],
+  invariants: [
+    "States conditions that the agreement must preserve.",
+    "Invariants",
+  ],
+  moves: [
+    "Declares a transfer, reservation, posting or release of money.",
+    "Moves",
+  ],
+  from: [
+    "Names the account money leaves, or the state an action can start from.",
+  ],
+  to: ["Names the account money reaches, or the state an action enters."],
+  in: [
+    "Requires a referenced agreement to be in one of the listed states.",
+    "State requirement",
+  ],
+  by: ["Names who performs the stated operation."],
+  for: ["Identifies the subject of the stated rule."],
+  is: ["Selects rules for one named parameter choice."],
+  unique: [
+    "Rejects a repeated combination of values in the named namespace.",
+    "Unique requirement",
+  ],
+  on: ["Lists the fields whose combined values must be unique."],
+  count: [
+    "Limits how many selected records may exist.",
+    "Aggregate requirement",
+  ],
+  sum: [
+    "Limits the total value of a field across selected records.",
+    "Aggregate requirement",
+  ],
+  hours: [
+    "Allows an action only within the stated local hours.",
+    "Hours requirement",
+  ],
+  between: ["Introduces the opening time of an allowed time window."],
+  and: ["Introduces the closing time of an allowed time window."],
+  timezone: ["Chooses the timezone used to evaluate allowed hours."],
+  evidence: [
+    "Requires evidence about the subject with the stated check and result.",
+    "Evidence requirement",
+  ],
+  reserve: [
+    "Holds money for later posting or release.",
+    "internal_transfer.reserve",
+  ],
+  post: ["Completes a previously reserved transfer.", "internal_transfer.post"],
+  void: [
+    "Releases a previously reserved transfer without paying its recipient.",
+    "internal_transfer.void",
+  ],
+  capture: ["Stores the transfer reference for a later posting or release."],
+  fee: ["Applies the stated charges to a money movement.", "Move fees"],
+  shares: [
+    "Divides a money movement among the listed recipients.",
+    "Move shares",
+  ],
+  object: [
+    "Declares a business object with fields and attached agreements.",
+    "Subjects",
+  ],
+  attach: [
+    "Adds an instrument to an object and binds its parameters.",
+    "Subject attachments",
+  ],
+  subject: [
+    "Declares object fields that an action requires before it can run.",
+    "Subject requirements",
+  ],
+  rename: [
+    "Changes the names of fields exposed by an attachment.",
+    "Attachment field mappings",
+  ],
+  columns: [
+    "Selects the fields shown when listing objects.",
+    "Presentation columns",
+  ],
+} satisfies Record<(typeof KEYWORDS)[number], readonly [string, string?]>;