@hyperscale0/hsx 2.4.1 → 3.0.1

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,cAAc,EAAE,26SAA26S,CAAC;IAC77S,CAAC,yBAAyB,EAAE,ytWAAytW,CAAC;IACtvW,CAAC,qCAAqC,EAAE,0jgCAA0jgC,CAAC;IACnmgC,CAAC,kCAAkC,EAAE,4pdAA4pd,CAAC;IAClsd,CAAC,0CAA0C,EAAE,shSAAshS,CAAC;IACpkS,CAAC,iCAAiC,EAAE,s8QAAs8Q,CAAC;IAC3+Q,CAAC,8BAA8B,EAAE,g73EAAg73E,CAAC;IACl93E,CAAC,uBAAuB,EAAE,8JAA8J,CAAC;IACzL,CAAC,kCAAkC,EAAE,k7fAAk7f,CAAC;IACx9f,CAAC,yBAAyB,EAAE,siIAAsiI,CAAC;IACnkI,CAAC,8BAA8B,EAAE,slOAAslO,CAAC;IACxnO,CAAC,iCAAiC,EAAE,wucAAwuc,CAAC;IAC7wc,CAAC,mCAAmC,EAAE,4hSAA4hS,CAAC;IACnkS,CAAC,+BAA+B,EAAE,ohwBAAohwB,CAAC;IACvjwB,CAAC,2BAA2B,EAAE,gu2BAAgu2B,CAAC;IAC/v2B,CAAC,kCAAkC,EAAE,+0eAA+0e,CAAC;IACr3e,CAAC,kCAAkC,EAAE,s2dAAs2d,CAAC;IAC54d,CAAC,sBAAsB,EAAE,kxuCAAkxuC,CAAC;IAC5yuC,CAAC,gCAAgC,EAAE,ktpBAAktpB,CAAC;IACtvpB,CAAC,uCAAuC,EAAE,mtgBAAmtgB,CAAC;CAC/vgB,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,eAAe,EAAE,u8BAAu8B,CAAC;IAC19B,CAAC,WAAW,EAAE,i5GAAi5G,CAAC;IACh6G,CAAC,iBAAiB,EAAE,suEAAsuE,CAAC;IAC3vE,CAAC,YAAY,EAAE,66DAA66D,CAAC;IAC77D,CAAC,eAAe,EAAE,82gCAA82gC,CAAC;IACj4gC,CAAC,eAAe,EAAE,ojGAAojG,CAAC;IACvkG,CAAC,aAAa,EAAE,ohPAAohP,CAAC;IACriP,CAAC,iBAAiB,EAAE,ujCAAujC,CAAC;IAC5kC,CAAC,WAAW,EAAE,2tWAA2tW,CAAC;IAC1uW,CAAC,aAAa,EAAE,qmGAAqmG,CAAC;IACtnG,CAAC,YAAY,EAAE,0zLAA0zL,CAAC;IAC10L,CAAC,YAAY,EAAE,w1DAAw1D,CAAC;CACz2D,CAAC,CAAC"}

package/dist/src/std-library.d.ts

@@ -1,5 +1,5 @@
 export interface StandardLibrary {
-    readonly source: (specifier: string, name: string) => string | undefined;
+    source(header: string): string | undefined;
 }
 export declare const bundledStandardLibrary: StandardLibrary;
 //# sourceMappingURL=std-library.d.ts.map

package/dist/src/std-library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"std-library.d.ts","sourceRoot":"","sources":["../../src/std-library.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1E;AAED,eAAO,MAAM,sBAAsB,EAAE,eAKpC,CAAC"}
+{"version":3,"file":"std-library.d.ts","sourceRoot":"","sources":["../../src/std-library.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5C;AACD,eAAO,MAAM,sBAAsB,EAAE,eAEpC,CAAC"}

package/dist/src/std-library.js

@@ -1,9 +1,5 @@
 import { BUNDLED_STD_FILES } from "./std-bundle.js";
 export const bundledStandardLibrary = {
-    source(specifier, name) {
-        if (specifier !== "std/money_flows")
-            return undefined;
-        return BUNDLED_STD_FILES.get(`money_flows/${name}.hsx`);
-    },
+    source: (header) => BUNDLED_STD_FILES.get(`${header}.hsx`),
 };
 //# sourceMappingURL=std-library.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"std-library.js","sourceRoot":"","sources":["../../src/std-library.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAMpD,MAAM,CAAC,MAAM,sBAAsB,GAAoB;IACrD,MAAM,CAAC,SAAiB,EAAE,IAAY;QACpC,IAAI,SAAS,KAAK,iBAAiB;YAAE,OAAO,SAAS,CAAC;QACtD,OAAO,iBAAiB,CAAC,GAAG,CAAC,eAAe,IAAI,MAAM,CAAC,CAAC;IAC1D,CAAC;CACF,CAAC"}
+{"version":3,"file":"std-library.js","sourceRoot":"","sources":["../../src/std-library.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAIpD,MAAM,CAAC,MAAM,sBAAsB,GAAoB;IACrD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,MAAM,MAAM,CAAC;CAC3D,CAAC"}

package/dist/src/tunables.d.ts

@@ -0,0 +1,7 @@
+import type { Expr } from "./ast.ts";
+/** Bounds use UDL units: minor units, basis points and milliseconds. */
+export declare function tunableBounds(type: Expr): {
+    minimum: number | string;
+    maximum: number | string;
+} | undefined;
+//# sourceMappingURL=tunables.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tunables.d.ts","sourceRoot":"","sources":["../../src/tunables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,GACT;IAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,CAyBpE"}

package/dist/src/tunables.js

@@ -0,0 +1,26 @@
+/** Bounds use UDL units: minor units, basis points and milliseconds. */
+export function tunableBounds(type) {
+    const name = type.kind === "call" || type.kind === "type"
+        ? type.name
+        : type.kind === "name"
+            ? type.value
+            : "";
+    if (name === "money")
+        return { minimum: "0", maximum: "999999999999999999" };
+    if (name === "percent")
+        return { minimum: 0, maximum: 10000 };
+    if (name === "duration")
+        return { minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
+    if (name !== "integer")
+        return;
+    if (type.kind === "call") {
+        const numbers = type.args.map((arg) => arg.kind === "number" ? Number(arg.value) : NaN);
+        if (numbers.length !== 2 ||
+            numbers.some((value) => !Number.isSafeInteger(value)) ||
+            numbers[0] > numbers[1])
+            throw new Error("integer tunable needs a minimum and maximum");
+        return { minimum: numbers[0], maximum: numbers[1] };
+    }
+    return { minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+}
+//# sourceMappingURL=tunables.js.map

package/dist/src/tunables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunables.js","sourceRoot":"","sources":["../../src/tunables.ts"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAC3B,IAAU;IAEV,MAAM,IAAI,GACR,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;QAC1C,CAAC,CAAC,IAAI,CAAC,IAAI;QACX,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM;YACpB,CAAC,CAAC,IAAI,CAAC,KAAK;YACZ,CAAC,CAAC,EAAE,CAAC;IACX,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAC7E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9D,IAAI,IAAI,KAAK,UAAU;QACrB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC;IAC1D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACpC,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAChD,CAAC;QACF,IACE,OAAO,CAAC,MAAM,KAAK,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YACrD,OAAO,CAAC,CAAC,CAAE,GAAG,OAAO,CAAC,CAAC,CAAE;YAEzB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC;AAC1D,CAAC"}

package/dist/src/version.d.ts

@@ -1,5 +1,3 @@
-/** Package version reported by the command line. */
-export declare const HSX_VERSION = "2.4.1";
-/** Canonical UDL contract version emitted by this compiler. */
-export declare const HSX_TARGET_UDL_VERSION = 1;
+export declare const HSX_VERSION = "3.0.1";
+export declare const HSX_TARGET_UDL_VERSION = 3;
 //# 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,oDAAoD;AACpD,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"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"}

package/dist/src/version.js

@@ -1,5 +1,3 @@
-/** Package version reported by the command line. */
-export const HSX_VERSION = "2.4.1";
-/** Canonical UDL contract version emitted by this compiler. */
-export const HSX_TARGET_UDL_VERSION = 1;
+export const HSX_VERSION = "3.0.1";
+export const HSX_TARGET_UDL_VERSION = 3;
 //# 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,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,+DAA+D;AAC/D,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;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC"}

package/docs/README.md

@@ -1,41 +1,179 @@
-# HSX documentation
-
-Read the guide in order. Every HSX program in it runs through the compiler in
-the package test suite.
-
-1. [Your first program](./guide/01-first-program.md)
-2. [Money](./guide/02-money.md)
-3. [Instruments](./guide/03-instruments.md)
-4. [Lifecycles](./guide/04-lifecycles.md)
-5. [Fees and splits](./guide/05-fees-and-splits.md)
-6. [Schedules](./guide/06-schedules.md)
-7. [Composition](./guide/07-composition.md)
-8. [Writing a module](./guide/08-writing-a-module.md)
-9. [Cost](./guide/09-cost.md)
-10. [Diagnostics](./guide/10-diagnostics.md)
-
-The generated [reference](./reference/) follows the compiler, UDL vocabulary,
-and standard-library files. Run `bun run generate` in a source checkout to
-build references, the embedded standard library and playground examples. Package
-builds and prepack do this automatically. These outputs are ignored by git;
-`bun run docs:build` compiles guide examples and validates documentation links.
-
-The [browser playground](./playground.md) provides a static editing surface with
-live compilation, diagnostics inspection, and example programs. The hosted
-playground is served at https://hyperscale0.ai/playground.
-
-[Compose actions over a piece plan](./piece-plans.md) is a worked excerpt, not
-a standalone program: it shows the `piece_plan`, `piece_stage`, `calls` and
-`action_library` clauses inside an instrument.
-
-## Examples and tooling
-
-- [Standard library examples](../examples/README.md)
-- [Browser playground](./playground.md)
-- [VS Code extension](../editors/vscode/README.md)
-
-## Agent references
-
-Agents can start with [llms.txt](./llms.txt) or load the
-[HSX skill](../skills/hsx/SKILL.md). [llms-full.txt](./llms-full.txt) combines
-the guide and generated reference in reading order.
+# HSX 3
+
+A program declares parties and objects from headers. Currency defaults to SAR.
+A party binds its account and optional role at admission. A program never carries
+account ids, reference filters, credentials or bank beneficiary ids.
+
+```hsx
+program shop "Shop"
+use marketplace
+use escrow
+party buyer: person
+party seller: business
+listing = marketplace.listing { seller: seller }
+order = marketplace.order { listing: listing, buyer: buyer }
+sale = escrow.hold {
+  payer: buyer, payee: seller, for: order, accept_within: 48h
+  fee { seller: 1% cap 750 SAR, tax: 15% }
+  dispute { refund_after: return_verified }
+}
+```
+
+The header defines the available policies. The company chooses percentages, amounts, durations,
+parties and typed references. `funds: sale` links the stored records through the
+library's declared reference type. References can name a child, such as
+`receipt: plan.settlement`. A header tunable declared `ref<T>[]` accepts one object or a list of up to 16
+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.
+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`.
+Dates use `2026-11-28` or a timestamp with an explicit offset. Money has at most two
+decimal places and percentages at most two. The compiler uses integer minor units
+and basis points. Fee and tax calculations round down. Split percentages sum to
+100%; the last declared recipient receives the rounding remainder. Finite
+schedules use positions 1 through n and put the division remainder in position 1.
+Tax binds `programTax`. Fees default to `programOperator`. Fine, recovery and
+residual destinations are party tunables. Unused `programFines` and `programCosts`
+bindings are omitted.
+
+Every action is public with a generated camelCase name: `createSale`,
+`acceptSale`. `expose sale.accept as acceptDelivery` renames it;
+`hide sale.refund` removes it from the public API. Visibility grants no authority.
+Parent and clock actions still require their executor principal. Exposure paths
+can name children: `hide plan.payment.refund`.
+
+Accounts use cash or claim books. A move stays in one book. `account of buyer`
+aliases the default cash account; `account of self` provisions an owned account.
+`account(lender, cash, "capital")` binds a named account.
+`account(buyer, claim, contra, "debt")` declares the borrower's claim contra account.
+`account(seller, cash, external, "bank")` binds the executor-managed bank destination.
+Outstanding debt is an account balance. The library pairs cash repayment with
+claim reduction and represents receipts as immutable child records. Cash and loss
+shares round down; the declared residual account receives leftover minor units.
+
+The four transfer instructions are create, reserve, post and void under
+`internal_transfer`. A captured transfer exposes reserved, posted, settled,
+reversed or voided status. Voided means a released reservation. Settled means
+provider confirmation, not an internal account balance change.
+
+For a new record type, declare `instrument name { fields { ... } lifecycle { ... }
+action create { ... } }`. Fields are `money`, `account of buyer`, `ref<order>`,
+`date`, `duration`, `text`, `integer`, `percent`, `boolean`, `enum(a, b)` or
+`list(date, 12)`. `?` makes a field optional; `= value` fixes a constant or a typed
+calculation. Actions declare `input { reason: text }`. Headers and expert records
+write ordered requirements and moves as expressions:
+
+```hsx
+requires self.payer == self.order.buyer
+requires self.order in [placed]
+requires approval by underwriter
+moves self.price from payer to self.held
+moves self.price from self.held to payee fee fee
+```
+
+Comparisons accept `==`, `!=`, `<`, `<=`, `>` and `>=`. A path beginning with
+`self`, `input` or `party` is a field operand; a quoted string, amount or number is
+a literal. `requires unique "order" on [self.order]` fixes an identity namespace.
+`requires count of { instrument: child, reference: "parent", anchor: self.id,
+states: [pending], limit: 12 } == 12` checks a typed selection; `sum "amount" of`
+uses the same selection syntax. `invariants` accepts these requirement expressions.
+`requires hours self.now between 8 and 20 timezone "Asia/Riyadh"` checks local hours.
+`requires evidence self.payer family registry check ownership result verified
+maxAge 1d` requires a recent completed provider check.
+
+`moves reserve amount from payer to payee capture receipt` reserves a transfer;
+`moves post self.receipt` posts it and `moves void self.receipt` releases it.
+`moves amount from payer shares shares` expands a declared split. Optional `fee`,
+`capture` and `key` modifiers follow a move in that order. Repeated clauses keep
+their declaration order. The JSON-like clause form remains accepted and lowers
+to the same [UDL clauses](../../udl/spec/README.md).
+They cannot add kernel instructions. `at(list, position)` reads a dated list;
+`aggregate(selection, "amount")` sums selected money; `ratio(amount, weight, total)`
+floors a weighted share. `records` declares child types. `invoke` can create a child
+with typed input in the same transaction.
+
+An `approval` tunable binds a party and emits a decision record for each gated
+action, including child actions. `approval: underwriter` needs no separate object.
+Generated records are named `<object>_<action>_decision`; child names retain their
+object prefix. `requires approval by approver for approve is declined` reuses the
+approve decision for a declined branch. Decisions keep the target action's typed
+material input and expiry. `approvals.decision` remains available to attach an
+explicit decision to an action without a library approval tunable. A decision
+alone does not add a requirement to that action. Approval declarations with
+`input: "material"` infer immutable material fields from the target action's input.
+The compiler removes branches excluded by fixed enum tunables. An invalid program reports its source line
+and a correction. No artifact is returned with diagnostics.
+
+## Financing policies
+
+`financing.installments` keeps principal and fixed flat profit as claims from
+activation. The company chooses where funding goes and when profit becomes earned.
+All choices use accounts, calculations and moves in the same two books.
+
+| Tunable                            | Default                  | Selected behavior                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disburse_to`                      | `funds`                  | `funds` pays down payment and principal into the hold and confirms it. `borrower` credits principal to the borrower's balance.                                                                                                                                                                                                                                      |
+| `profit_earned`                    | `on_payment`             | `on_payment` collects unearned profit on payment. `by_schedule` moves unearned claims to earned claims at each slice's date. `at_disbursement` makes that move at activation. Cash arrives only on payment.                                                                                                                                                         |
+| `apply`                            | `fines_profit_principal` | Collect assessed fines by overdue date, then evidenced costs, then each slice in position order, profit before principal. `principal_profit` collects each slice in position order, principal before profit. `pro_rata` uses the slice's fixed principal:profit ratio, caps each side by its collectible balance, and assigns the remainder without stranding cash. |
+| `payoff_rebate`                    | `100%`                   | Reverse this share of unearned profit to borrower debt. Collect the remainder and all earned profit with outstanding principal.                                                                                                                                                                                                                                     |
+| `late_charge.fines_to`             | `programOperator`        | Receive fine cash and fund its refunds.                                                                                                                                                                                                                                                                                                                             |
+| `late_charge.costs_to`             | `programOperator`        | Receive evidenced recovery cash and fund its refunds.                                                                                                                                                                                                                                                                                                               |
+| `collections.case.fee`             | `20%`                    | After payment succeeds, transfer this share of the payment amount from plan capital to the agency.                                                                                                                                                                                                                                                                  |
+| `lending.distribution.residual_to` | `programOperator`        | Receive the cash remainder and own the claim loss remainder after weighted distribution.                                                                                                                                                                                                                                                                            |
+
+Each slice owns separate unearned and earned claim accounts. Scheduled recognition
+uses a dated child record so a partial payment cannot disable the maturity clock.
+A normal payment collects only earned profit for the schedule and disbursement
+choices; payoff can also collect non-rebated unearned profit. Partial fines and
+costs stay assessed until their receivable reaches zero. Immutable receipts let
+a refund restore only what that payment collected. The plan's payment receipt
+records actual principal and profit after all ordered collections finish.
+Write-off moves principal and earned profit claims to loss and reverses unearned
+profit to debt. There is no provision policy or write-off tunable.
+
+## Header branches and bounds
+
+A header may select action clauses at compile time:
+
+```hsx
+when disburse_to is borrower {
+  moves self.principal from self.capital to self.borrower
+}
+```
+
+`when <enum tunable> is <value>` accepts requirements, calculations, moves and
+invocations, including nested branches. The compiler emits only the selected
+clauses and preserves their order within each UDL phase. Lifecycle and actor
+clauses stay outside branches. Calculations and requirements run before moves;
+invocations run after moves. A collections fee therefore uses an internal action
+invoked after payment. Clock and parent actions have no public API name.
+
+`integer(1, 366)` declares an inclusive tunable bound. The compiler-owned manifest
+publishes enum values, numeric minima and maxima, and cross-tunable constraints.
+Bounds use minor units for money, basis points for percentages and milliseconds
+for durations. Money spans 0 through 999999999999999999 minor units; percentages
+span 0 through 10000 basis points. Durations start at 1 millisecond. Integers
+default to 0 through 9007199254740991 unless their declaration narrows the range. For example, `constraints { contact_from: less_than(contact_until) }`
+requires a valid hours interval. `at_most` and `greater_than` are also supported.
+A refusal names the tunable. Empty `all(type)` selections lower to zero aggregates
+or no invocations, so a plan does not require a late-charge object.
+
+The permutation spec builds a dependency-closed program per object. It takes each
+enum value and the minimum, default or example value, and a large numeric value.
+It uses the full product through 512 cases and pair coverage above that. Invalid
+bound combinations must refuse with a named diagnostic. Valid cases must produce
+valid UDL and retain public names on every caller action. This proves compilation,
+not executed balances or bank settlement.
+
+Build with `hsx build company.hsx --out company.udl.json`; check with
+`hsx check company.hsx`; print instruction counts with `hsx cost company.hsx`.
+Print the compiler-owned object manifest with `hsx headers --json`.
+The compiler API is `compile(source)`. A valid result contains `artifacts.document`,
+`costManifest` and source origins. Instruction counts are not bank tariffs or a
+promise of provider execution cost.
+
+The [header inventory](headers.md) is generated from the declarations. The
+[executable inventory](../examples/library.hsx) exercises every public object.
+The [playground](../playground/index.html) compiles locally in the browser.

package/docs/headers.md

@@ -0,0 +1,44 @@
+# Header inventory
+
+Each company selects library policies through typed tunables.
+`ref<T>[]` accepts one reference or up to 16 references as one policy. `approval` accepts a party and generates the required decision records.
+
+| Object                 | Tunables                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| money.transfer         | `payer: party`, `payee: party`, `amount: money = runtime`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| money.hold             | `payer: party`, `payee: party`, `amount: money = runtime`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| money.split            | `payer: party`, `amount: money = runtime`, `shares: split = { programOperator: 100% }`                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| money.schedule         | `payer: party`, `payee: party`, `amount: money = runtime`, `count: integer(1, 366) = 12`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| money.pool             | `payer: party`, `payee: party`, `target: money`, `closes: date`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| money.swap             | `first: party`, `second: party`, `first_amount: money`, `second_amount: money`, `expires: date`                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| money.deposit          | `payer: party`, `payee: party`, `amount: money`, `expires: date`, `approval: approval`                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| money.payout           | `payer: party`, `payee: party`, `amount: money = runtime`, `reconcile_within: duration = 3d`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| money.metered          | `payer: party`, `payee: party`, `unit_price: money`, `units: integer = 1`, `fee: fee = { seller: 0% }`                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| money.batch            | `payer: party`, `payee: party`, `closes: date`, `approval: approval`, `reconcile_within: duration = 3d`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| marketplace.listing    | `seller: party`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| marketplace.order      | `listing: ref<marketplace.listing>`, `buyer: party`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| escrow.hold            | `payer: party`, `payee: party`, `for: ref<marketplace.order>`, `accept_within: duration = 48h`, `fee: fee = { seller: 0%, tax: 0% }`, `dispute: policy = { refund_after: return_verified }`                                                                                                                                                                                                                                                                                                                                                      |
+| wallet.balance         | `holder: party`, `spend_limit: money = 100000 SAR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| wallet.spend           | `wallet: ref<wallet.balance>`, `payee: party`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| financing.installments | `months: integer(1, 366)`, `profit: percent`, `disburse_to: enum(funds, borrower) = funds`, `profit_earned: enum(on_payment, by_schedule, at_disbursement) = on_payment`, `apply: enum(fines_profit_principal, principal_profit, pro_rata) = fines_profit_principal`, `payoff_rebate: percent = 100%`, `down_payment: percent = 0%`, `funds: ref`, `approval: approval`, `borrower: party = party(person)`, `capital: party = programOperator`, `profit_to: party = programOperator`, `limits: ref<financing.limits> = object(financing.limits)` |
+| financing.late_charge  | `on: ref<financing.installments>[]`, `grace: duration = 3d`, `fine: money = 50 SAR`, `cap: money = 25 SAR`, `fines_to: party = programOperator`, `costs_to: party = programOperator`, `approval: approval = programOperator`, `borrower: party = party(person)`                                                                                                                                                                                                                                                                                  |
+| financing.limits       | `per_borrower: money`, `portfolio: money`, `borrower: party = party(person)`, `active_plans: integer = 1`                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| financing.credit_line  | `borrower: party`, `lender: party`, `limit: money`, `expires: date`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| financing.advance      | `line: ref<financing.credit_line>`, `amount: money = runtime`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| lending.round          | `borrower: party`, `capital: party`, `plan: ref<financing.installments> = object(financing.installments)`, `months: integer(1, 366) = 3`, `profit: percent = 3%`, `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`, `fee: percent = 1%`, `tax: percent = 15%`                                                                                                                                                                                                                                                                                                             |
+| insurance.cover        | `holder: party`, `insurer: party`, `commission: percent = 0%`, `covers: ref`, `premium: money = runtime`                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| insurance.claim        | `cover: ref<insurance.cover>`, `approved_by: approval`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| approvals.decision     | `for: ref`, `approved_by: party`, `action: text = "approve"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| collections.case       | `on: ref<financing.installments>[]`, `agency: approval`, `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                                                                                                                                                                                                                                                                                       |
+| travel.package         | `price: money`, `supplier_cost: money`, `departure: date`; supplier_cost at_most price                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| travel.booking         | `package: ref<travel.package>`, `buyer: party`, `supplier: approval`, `cover: ref<insurance.cover>`, `deposit: percent = 30%`, `balance_before: duration = 14d`, `confirm_within: duration = 24h`, `tax: percent = 15%`, `early_before: duration = 30d`, `middle_before: duration = 15d`, `middle_penalty: percent = 10%`, `late_penalty: percent = 30%`; early_before greater_than middle_before                                                                                                                                                |
+| cards.cardholder       | `holder: party`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| cards.card             | `holder: ref<cards.cardholder>`, `spend_limit: money`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| cards.authorization    | `card: ref<cards.card>`, `merchant: party`, `approval: approval`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| cards.transaction      | `authorization: ref<cards.authorization>`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| cards.dispute          | `transaction: ref<cards.transaction>`, `approved_by: approval`, `within: duration = 90d`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| savings.circle         | `contribution: money`, `members: integer(1, 366)`, `starts: date`, `memberships: ref<savings.membership> = object(savings.membership)`                                                                                                                                                                                                                                                                                                                                                                                                           |
+| savings.membership     | `circle: ref<savings.circle>`, `member: party`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |