@hyperscale0/hsx 5.3.0 → 5.4.0

package/dist/src/std-bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"std-bundle.js","sourceRoot":"","sources":["../../src/std-bundle.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAiB;IACpF,CAAC,WAAW,EAAE,uhIAAuhI,CAAC;IACtiI,CAAC,iBAAiB,EAAE,ooKAAooK,CAAC;IACzpK,CAAC,YAAY,EAAE,o8DAAo8D,CAAC;IACp9D,CAAC,eAAe,EAAE,g5vDAAg5vD,CAAC;IACn6vD,CAAC,eAAe,EAAE,+0GAA+0G,CAAC;IACl2G,CAAC,aAAa,EAAE,mvPAAmvP,CAAC;IACpwP,CAAC,iBAAiB,EAAE,m0PAAm0P,CAAC;IACx1P,CAAC,WAAW,EAAE,y1RAAy1R,CAAC;IACx2R,CAAC,eAAe,EAAE,w77CAAw77C,CAAC;IAC387C,CAAC,aAAa,EAAE,wrGAAwrG,CAAC;IACzsG,CAAC,YAAY,EAAE,8kMAA8kM,CAAC;IAC9lM,CAAC,YAAY,EAAE,m6DAAm6D,CAAC;CACp7D,CAAC,CAAC"}
+{"version":3,"file":"std-bundle.js","sourceRoot":"","sources":["../../src/std-bundle.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAiB;IACpF,CAAC,WAAW,EAAE,k6JAAk6J,CAAC;IACj7J,CAAC,iBAAiB,EAAE,s8LAAs8L,CAAC;IAC39L,CAAC,YAAY,EAAE,00FAA00F,CAAC;IAC11F,CAAC,eAAe,EAAE,2z0DAA2z0D,CAAC;IAC900D,CAAC,eAAe,EAAE,0+IAA0+I,CAAC;IAC7/I,CAAC,aAAa,EAAE,oyRAAoyR,CAAC;IACrzR,CAAC,iBAAiB,EAAE,y1RAAy1R,CAAC;IAC92R,CAAC,WAAW,EAAE,0yTAA0yT,CAAC;IACzzT,CAAC,eAAe,EAAE,uq9CAAuq9C,CAAC;IAC1r9C,CAAC,aAAa,EAAE,o+IAAo+I,CAAC;IACr/I,CAAC,YAAY,EAAE,s6OAAs6O,CAAC;IACt7O,CAAC,YAAY,EAAE,qjFAAqjF,CAAC;CACtkF,CAAC,CAAC"}

package/dist/src/version.d.ts

@@ -1,3 +1,2 @@
-export declare const HSX_VERSION = "5.3.0";
-export declare const HSX_TARGET_UDL_VERSION = 4;
+export declare const HSX_VERSION = "5.4.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/src/version.js

@@ -1,3 +1,2 @@
-export const HSX_VERSION = "5.3.0";
-export const HSX_TARGET_UDL_VERSION = 4;
+export const HSX_VERSION = "5.4.0";
 //# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/docs/README.md

@@ -1,4 +1,4 @@
-# HSX 5.0.1
+# HSX
 
 A program declares business objects and financial instruments. Objects contain
 optional metadata. Attachments expose named actions against an object.
@@ -49,6 +49,9 @@ library's declared reference type. References can name a child, such as
 objects of type T. `on: [plan_3, plan_6]` creates one late-charge or collections
 policy. Its references can point into either plan; selections can span both.
 A plain `ref<T>` accepts one object only.
+Tunable constructors are `enum(choices)` and `integer(minimum, maximum)`.
+Other constructors, including `party(business)` and bounded `money(...)`, are
+rejected at the header declaration. Their arguments do not restrict bindings.
 Imports are `use header`; there are no file imports, macros or executable strings.
 
 Amounts use `750 SAR`; percentages use `2.5%`; durations use `48h`, `3d`, or `1w`.
@@ -78,8 +81,9 @@ same book and key within the Product. Providers remain outside parties.
 A missing binding refuses before money moves. Reference paths such as
 `self.cover.insurer` use the referenced agreement's account.
 
-Insurance collection credits the premium to the operator, then moves the premium
-net of commission to the insurer account. Refunds reverse those two portions.
+Insurance collection pays the premium net of commission to the insurer account
+and pays commission separately to the bound broker, which defaults to the operator.
+Refunds return those two portions directly from insurer and broker to holder.
 Claims reserve from the cover's insurer account. These moves record ledger money;
 external confirmation still needs the boundary protocol.
 `account(buyer, claim, contra, "debt")` declares the borrower's claim contra account.
@@ -271,7 +275,7 @@ adapters are bound, participants have funds, or the flow can finish.
 | `lending.distribution`                     | Cash distribution needs an eligible recorded settlement, `prepare_cash`, one share record per funded commitment, then `distribute_cash`. Attaching it moves nothing.                                                                                                                                                         |
 | `insurance.cover.slice`                    | `collect` credits premium net of commission to the insurer account. The tenant retains commission. `refund` returns both portions; claims reserve insurer funds. External settlement uses the boundary protocol.                                                                                                             |
 | `travel.booking`                           | From `deposit_paid` or `paid`, early cancellation returns the full held balance, middle returns held balance minus deposit, and late has no buyer refund transfer. State, time and balance requirements still apply. A deposit-only early cancellation refunds the deposit; a deposit-only middle cancellation refunds zero. |
-| `financing.installments`, `savings.circle` | Supply explicit date lists when creating agreements. A term count does not generate a monthly calendar. Savings supports at most 60 distinct member positions.                                                                                                                                                               |
+| `financing.installments`, `savings.circle` | Supply explicit date lists when creating agreements. A term count does not generate a monthly calendar. Savings supports at most 60 distinct member seats.                                                                                                                                                                   |
 | `escrow.hold`                              | `fund` takes the whole price. Financing into pending escrow collects the remaining down payment and adds capital principal at disbursement; `fund` is not a down-payment checkout.                                                                                                                                           |
 | `escrow.hold`                              | Acceptance timeout enters `disputed` without paying the seller. Delivery and return verification belong to `payee`; rebinding it also changes who receives accepted funds.                                                                                                                                                   |
 | `financing.late_charge`                    | `fine` is a fixed money amount, not a percentage of overdue principal.                                                                                                                                                                                                                                                       |
@@ -282,3 +286,44 @@ commitment creation, and cash prepare/distribute actions. Its repayment and shar
 child actions still lack a public execution path. It is a composition example,
 not a complete public repayment flow. Callers still need dates, agreement inputs,
 funded wallets, eligible settlements and the distribution's share records.
+
+## Checkout and reversals
+
+For financed checkout, expose `installments.collect_down_payment` after `create`
+and `sign`. It credits the linked pending escrow with the missing down payment.
+It does not disburse principal or activate the plan. The later `disburse` action
+uses that credit before collecting any remainder. Borrower-directed financing
+has no checkout collection action. The plan and escrow must agree on payer and
+price.
+
+Expose escrow `cancel` to return money credited before full funding. Plan `void`
+cancels the signed financing agreement but does not cancel its escrow. After
+funding and delivery, the default return path needs three separate aliases for
+`dispute`, `verify_return` and `refund`. The payee supplies return evidence and
+returns the full price to the payer. `accept` pays the payee instead.
+Marketplace order fulfillment alone does not execute any of these money actions.
+
+Expose `late_charge.create` to create an assessment with matching plan, slice
+and borrower. Only that existing assessment can reach clock-owned `assess` after
+grace. A payment can collect part of a fine without settling the rest. A recovery
+cost assessment is a separate record.
+
+## Separate payments and states
+
+Bind `insurance.cover.broker` to the agency that receives commission. Collection
+pays the insurer's net premium and the broker's commission as two moves. Refunds
+reverse those same portions. The default broker is the program operator.
+`claim.deny` accepts only `submitted`; after approval, `pay` or expiry consumes
+the reservation.
+
+A booking cancellation refunds only its own held cash. Expose `cover.cancel`
+separately for eligible premium refunds before the paid period starts. Active
+and expired premium periods are excluded. A card transaction needs a captured
+authorization and its own record before refund, but no authorization-expiry wait.
+
+A savings membership becomes `received` after its pot payout. Its contribution
+records become `paid` independently. Future contributions can remain pending
+after the member receives the pot; paying a contribution does not advance their
+payout seat. Late contributions remain eligible while the membership is
+`active` or `received` and the circle is `active`. These guards do not promise
+scheduler retries or permit a payout larger than the available cash.

package/docs/headers.md

@@ -29,7 +29,7 @@ Bind party parameters to owner, actor, operator or declared parties. Configure d
 | lending.round | `borrower: party`, `plan: ref<financing.installments> = object(financing.installments)`, `operator: party = programOperator`, `minimum_ticket: money = 100 SAR`, `investor_cap: percent = 20%`, `commitments: ref<lending.commitment> = object(lending.commitment)` |
 | lending.commitment | `round: ref<lending.round>`, `wallet: ref<wallet.balance>`, `investor: party = party(person)` |
 | lending.distribution | `round: ref<lending.round>`, `receipt: ref`, `commitments: ref<lending.commitment> = object(lending.commitment)`, `mode: enum(cash, loss) = cash`, `residual_to: party = programOperator`, `operator: party = programOperator`, `fee: percent = 1%`, `tax: percent = 15%` |
-| insurance.cover | `holder: party`, `adapter: text`, `commission: percent = 0%`, `covers: ref`, `premium: money = runtime` |
+| insurance.cover | `holder: party`, `adapter: text`, `commission: percent = 0%`, `broker: party = programOperator`, `covers: ref`, `premium: money = runtime` |
 | insurance.claim | `cover: ref<insurance.cover>`, `inspector: party` |
 | collections.case | `on: ref<financing.installments>[]`, `agency: party`, `capital: party = programOperator`, `overdue: duration = 3d`, `fee: percent = 20%` |
 | collections.contact | `case: ref<collections.case>[]`, `agency: party`, `max_contacts: integer = 10`, `window: duration = 30d`, `contact_from: integer(0, 23) = 8`, `contact_until: integer(1, 23) = 20`, `timezone: text = "Asia/Riyadh"`; contact_from less_than contact_until |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "5.3.0",
+  "version": "5.4.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.8",
-    "@hyperscale0/udl": "4.4.1",
+    "@hyperscale0/udl": "4.5.0",
     "fast-sha256": "1.3.0"
   },
   "devDependencies": {
@@ -98,5 +98,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "c4c05d21a84c60a5dd5fcd94412f0997a091b05c"
+  "gitHead": "4141f2296d9427b30d04933c735be4af1ba88dec"
 }

package/src/cli.ts

@@ -5,6 +5,8 @@ import { HSX_VERSION } from "./version.ts";
 import { compile } from "./compile.ts";
 import { format } from "./format.ts";
 import { serializeUdl } from "@hyperscale0/udl";
+const usage =
+  "hsx build|format|cost <file> [--out path]\nhsx check <file>\nhsx headers --json";
 const standardLibrary = {
   source: (header: string) => {
     for (const base of ["../std/", "../../std/"]) {
@@ -20,8 +22,6 @@ export interface Io {
   err(line: string): void;
   readFile(path: string): Promise<string>;
   writeFile(path: string, text: string): Promise<void>;
-  stdin?: NodeJS.ReadableStream;
-  stdout?: NodeJS.WritableStream;
 }
 export async function runCli(argv: readonly string[], io: Io): Promise<number> {
   const [command, file, ...options] = argv;
@@ -34,7 +34,7 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     return 0;
   }
   if (["--help", "help", "-h"].includes(command ?? "")) {
-    io.out("hsx build|check|format|cost <file> [--out path]");
+    io.out(usage);
     return 0;
   }
   if (command === "--version") {
@@ -46,14 +46,20 @@ export async function runCli(argv: readonly string[], io: Io): Promise<number> {
     !file ||
     !["build", "check", "format", "cost"].includes(command)
   ) {
-    io.err("usage: hsx build|check|format|cost <file> [--out path]");
+    io.err(`usage:\n${usage}`);
     return 2;
   }
   let output: string | undefined;
   for (let i = 0; i < options.length; i++) {
-    if (options[i] === "--out" && options[i + 1] && output === undefined)
+    if (
+      command !== "check" &&
+      options[i] === "--out" &&
+      options[i + 1] &&
+      !options[i + 1]!.startsWith("--") &&
+      output === undefined
+    )
       output = options[++i];
-    else if (!["--json", "--strict"].includes(options[i]!)) {
+    else {
       io.err(`unknown option ${options[i]}`);
       return 2;
     }

package/src/compile.ts

@@ -1099,11 +1099,16 @@ export function compile(
             (binding.kind === "name" && binding.value === expr.value))
         )
           return expr;
-        // A resolved party parameter takes precedence over a same-named attachment.
+        // A resolved party parameter or an own parameter bound to a value takes
+        // precedence over a same-named sibling attachment; `limits: limits`
+        // binds by identity and still names the sibling.
         if (attachmentInfo && !resolvedParties.has(expr.value)) {
           const [local, ...tail] = expr.value.split(".");
+          const own = environment.get(local!);
+          const ownValue =
+            own !== undefined && !(own.kind === "name" && own.value === local);
           const target = `${attachmentInfo.subjectKindId}_${local}`;
-          if (attachmentSubjects.has(target))
+          if (!ownValue && attachmentSubjects.has(target))
             return { ...expr, value: [target, ...tail].join("_") };
         }
         if (expr.value.startsWith("party.")) {
@@ -2629,7 +2634,7 @@ export function compile(
           }
         }
         if (automatic(a.actor)) delete a.publicAction;
-        const checkSubjectPaths = (obj: unknown, span: Span, key = "") => {
+        const checkSubjectPaths = (obj: unknown, key = "") => {
           if (typeof obj === "string") {
             if (
               [
@@ -2649,7 +2654,7 @@ export function compile(
               );
               if (!req) {
                 failWithCode(
-                  { span },
+                  row,
                   "subject_field_unknown",
                   `subject.${subField} names no declared subject requirement in action ${name}`,
                   `declare ${subField} in subject { ... }`,
@@ -2657,15 +2662,15 @@ export function compile(
               }
             }
           } else if (Array.isArray(obj)) {
-            for (const item of obj) checkSubjectPaths(item, span, key);
+            for (const item of obj) checkSubjectPaths(item, key);
           } else if (obj !== null && typeof obj === "object") {
             for (const [key, val] of Object.entries(obj))
-              checkSubjectPaths(val, span, key);
+              checkSubjectPaths(val, key);
           }
         };
-        checkSubjectPaths(a.requires, row.span);
-        checkSubjectPaths(a.set, row.span);
-        checkSubjectPaths(a.invoke, row.span);
+        checkSubjectPaths(a.requires);
+        checkSubjectPaths(a.set);
+        checkSubjectPaths(a.invoke);
         currentAction = undefined;
         currentActionName = undefined;
         for (const requirement of a.subject?.requirements ?? []) {
@@ -3394,6 +3399,24 @@ export function compile(
           );
         else action!.publicAction = decl.name!;
       }
+    for (const decl of program.decls) {
+      if (decl.kind !== "expose") continue;
+      const parts = decl.target.split(".");
+      parts.pop();
+      const instrument = document.instruments.find(
+        (item) => item.id === parts.join("_"),
+      )!;
+      if (
+        Object.values(instrument.actions).filter(
+          (action) => action.publicAction === decl.name,
+        ).length > 1
+      )
+        fail(
+          decl,
+          `public action ${decl.name} is used more than once on ${parts.join(".")}`,
+          "give each exposed action a distinct public name",
+        );
+    }
     const usedParties = new Set<string>();
     const collectParties = (value: unknown): void => {
       if (typeof value === "string") {

package/src/header-source.ts

@@ -38,6 +38,16 @@ export function parseHeader(source: string, name: string) {
           "declare each parameter once",
         );
       parameters.add(parameter.key);
+      const type =
+        parameter.value.kind === "default"
+          ? parameter.value.type
+          : parameter.value;
+      if (type.kind === "call" && !["enum", "integer"].includes(type.name))
+        fail(
+          type,
+          `unsupported tunable constructor ${type.name}`,
+          "Only enum(choices) and integer(minimum, maximum) are supported tunable constructors. This constructor's restrictions cannot be enforced.",
+        );
     }
   }
   return program;