@hyperscale0/hsx 5.6.0 → 5.7.0

package/examples/collections.hsx

@@ -7,8 +7,8 @@ party agency: business
 object facility "Business loan" {
   fields { businessName: text, purpose: text, price: money }
   columns: [businessName, purpose, price]
-  attach allowance = financing.limits { expose create as create_allowance, borrower: owner, per_borrower: 100000 SAR }
-  attach budget = financing.portfolio_limit { expose create as create_budget, limit: 2000000 SAR }
+  attach allowance = financing.limits { expose create as create_allowance, expose approve as approve_borrower, borrower: owner, per_borrower: 100000 SAR }
+  attach budget = financing.portfolio_limit { expose create as create_budget, expose approve as approve_budget, limit: 2000000 SAR }
   attach loan = financing.installments {
     expose create as create_loan
     borrower: owner, capital: operator
@@ -16,6 +16,7 @@ object facility "Business loan" {
     limits: allowance, portfolio: budget
     expose sign as sign_loan
     expose disburse as release_loan
+    expose payoff as repay_early
   }
   attach recovery = collections.case {
     expose create as create_recovery
@@ -29,3 +30,8 @@ object facility "Business loan" {
     case: recovery, agency: agency
   }
 }
+
+expose facility.loan.payment.create as create_payment
+expose facility.loan.payment.pay as pay_instalment
+expose facility.loan.payment.refund as refund_payment
+expose facility.loan.payoff_quote.create as request_payoff_quote

package/examples/financing.hsx

@@ -25,3 +25,8 @@ object enrolment "Enrolment" {
     expose payoff as repay_early
   }
 }
+
+expose enrolment.tuition.payment.create as create_payment
+expose enrolment.tuition.payment.pay as pay_instalment
+expose enrolment.tuition.payment.refund as refund_payment
+expose enrolment.tuition.payoff_quote.create as request_payoff_quote

package/examples/lending.hsx

@@ -1,5 +1,4 @@
 // A lending composition with limit approvals, wallet commitments and cash distribution transitions.
-// Repayment and distribution-share child actions still need an execution path; this is not a complete public repayment flow.
 program community_business_lending "Community business lending"
 use lending
 use financing
@@ -25,6 +24,7 @@ object business "Business funding" {
     limits: allowance, portfolio: budget
     expose sign as sign_loan
     expose disburse as release_loan
+    expose payoff as repay_early
   }
   attach investor_balance = wallet.balance {
     expose create as create_investor_balance
@@ -49,3 +49,9 @@ object business "Business funding" {
     expose distribute_cash as distribute_returns
   }
 }
+
+expose business.loan.payment.create as create_payment
+expose business.loan.payment.pay as pay_instalment
+expose business.loan.payment.refund as refund_payment
+expose business.loan.payoff_quote.create as request_payoff_quote
+expose business.returns.share.create as create_return_share

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -86,7 +86,7 @@
   },
   "dependencies": {
     "@hyperscale0/adl": "1.0.0-beta.10",
-    "@hyperscale0/udl": "4.8.0",
+    "@hyperscale0/udl": "4.9.0",
     "fast-sha256": "1.3.0"
   },
   "devDependencies": {
@@ -98,5 +98,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "be567dd18eb45ea3e02adc1f33b8491aa05df135"
+  "gitHead": "e1e36df7b7182c7e22264414c622076a044e974a"
 }

package/src/compile.ts

@@ -1488,6 +1488,7 @@ export function compile(
             "parameterDiagnostics",
             "reports",
             "revisioned",
+            "scope",
           ].includes(key) &&
           !key.startsWith("action ")
         )
@@ -2278,7 +2279,7 @@ export function compile(
         const a: UdlAction = {
           summary: slots.has("summary")
             ? String(data(slots.get("summary")!))
-            : `${title(name)} ${id}`,
+            : title(name),
           publicAction: camel(`${name}_${id}`),
           event: `${id}.${name}`,
           actor: "caller",
@@ -2839,11 +2840,43 @@ export function compile(
         inst.actions[name] = a;
         inst.actionOrder.push(name);
       }
-      for (const key of ["invariants", "reports", "revisioned"] as const)
+      for (const key of [
+        "invariants",
+        "reports",
+        "revisioned",
+        "scope",
+      ] as const)
         if (body.has(key))
           (inst as unknown as Record<string, unknown>)[key] = data(
             body.get(key)!,
           );
+      let usesTax = false;
+      for (const action of Object.values(inst.actions)) {
+        for (const move of action.moves) {
+          if (!("from" in move)) continue;
+          for (const endpoint of ["from", "to"] as const) {
+            if (move[endpoint] === "party.programTax") {
+              move[endpoint] = "self.programTaxPayable";
+              usesTax = true;
+            }
+          }
+        }
+      }
+      if (usesTax) {
+        if (inst.fields.some((field) => field.name === "programTaxPayable"))
+          fail(
+            decl,
+            "programTaxPayable is reserved for the tax account",
+            "rename the authored field",
+          );
+        inst.fields.push({
+          name: "programTaxPayable",
+          type: "account",
+          owner: "programOperator",
+          book: "cash",
+          key: "programTax",
+        });
+      }
       const shape = udlInstrumentSchema.safeParse(inst);
       if (!shape.success) {
         const issue = shape.error.issues[0]!;
@@ -2943,12 +2976,13 @@ export function compile(
         if (
           key !== "fields" &&
           key !== "columns" &&
+          key !== "entryActions" &&
           !key.startsWith("attach ")
         ) {
           fail(
             decl,
             `unknown object clause ${key}`,
-            "use fields, columns, or attach",
+            "use fields, columns, entryActions, or attach",
           );
         }
       }
@@ -3180,9 +3214,21 @@ export function compile(
         }
       }
 
+      const entryExpr = body.get("entryActions");
+      let entryActions: string[] | undefined;
+      if (entryExpr) {
+        if (entryExpr.kind !== "list" || !entryExpr.items.length)
+          fail(
+            entryExpr,
+            "entryActions needs a nonempty list",
+            "name exposed create actions bound to actor",
+          );
+        entryActions = entryExpr.items.map(text);
+      }
       document.objects.push({
         id: decl.name,
         title: decl.title,
+        ...(entryActions ? { entryActions } : {}),
         authoredFields: authoredNames,
         attachments,
         fields: authoredFields,
@@ -3225,6 +3271,31 @@ export function compile(
           .sort((a, b) => a.span.start - b.span.start)
           .map((d) => diagnostic(d, "check")),
       };
+    // Resolve selectors after every attachment and child has its family.
+    const retainSelectionFamilies = (value: unknown): void => {
+      if (!value || typeof value !== "object") return;
+      const record = value as Record<string, unknown>;
+      const selection = record.selection as
+        | { instrument: string | string[]; family?: UdlFamily }
+        | undefined;
+      if (selection && !selection.family) {
+        const families = [selection.instrument]
+          .flat()
+          .map(
+            (id) => document.instruments.find((item) => item.id === id)?.family,
+          );
+        const family = families[0];
+        if (
+          family &&
+          families.every(
+            (item) => canonicalJson(item) === canonicalJson(family),
+          )
+        )
+          selection.family = family;
+      }
+      for (const child of Object.values(record)) retainSelectionFamilies(child);
+    };
+    retainSelectionFamilies(document);
     // Propagate invoked requirements with the conditions on each invocation path.
     let changedInvocations = true;
     let invocationIterations = 0;
@@ -3577,6 +3648,27 @@ export function compile(
           "give each exposed action a distinct public name",
         );
     }
+    for (const kind of document.objects) {
+      for (const name of kind.entryActions ?? []) {
+        const eligible = kind.attachments.some((attachment) => {
+          const create = document.instruments.find(
+            (instrument) => instrument.id === attachment.instrument,
+          )?.actions.create;
+          return (
+            create?.publicAction === name &&
+            typeof create.actor === "object" &&
+            "party" in create.actor &&
+            create.actor.party === "actor"
+          );
+        });
+        if (!eligible)
+          fail(
+            objects.get(kind.id)!,
+            `entry action ${name} must create an attachment as actor`,
+            "expose its create action and bind its acting party to actor",
+          );
+      }
+    }
     const usedParties = new Set<string>();
     const collectParties = (value: unknown): void => {
       if (typeof value === "string") {

package/src/examples-bundle.ts

@@ -2,11 +2,11 @@
 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, borrower: owner, per_borrower: 100000 SAR }\n  attach budget = financing.portfolio_limit { expose create as create_budget, limit: 2000000 SAR }\n  attach loan = financing.installments {\n    expose create as create_loan\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    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"},
+  {"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, profit: 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, 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":"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, 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\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\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    expose create as create_purchase\n    payer: owner, payee: operator\n    expose pay as pay_for_device\n  }\n  // Bind device_insurer to an ADL adapter before creating cover. Premiums net of commission go to its account.\n  attach protection = insurance.cover {\n    expose create as create_protection\n    holder: owner, adapter: \"device_insurer\", 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: 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":"A lending composition with limit approvals, wallet commitments and cash distribution transitions. Repayment and distribution-share child actions still need an execution path; this is not a complete public repayment flow.","headers":["lending","financing","wallet"],"source":"// A lending composition with limit approvals, wallet commitments and cash distribution transitions.\n// Repayment and distribution-share child actions still need an execution path; this is not a complete public repayment flow.\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, 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    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"},
+  {"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, profit: 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, 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    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":"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    expose pay as pay_for_lesson\n    expose cancel as cancel_payment\n  }\n}\n"},