@hyperscale0/hsx 5.4.2 → 5.6.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,2oKAA2oK,CAAC;IAC1pK,CAAC,iBAAiB,EAAE,+rMAA+rM,CAAC;IACptM,CAAC,YAAY,EAAE,6jGAA6jG,CAAC;IAC7kG,CAAC,eAAe,EAAE,0j1DAA0j1D,CAAC;IAC7k1D,CAAC,eAAe,EAAE,ouJAAouJ,CAAC;IACvvJ,CAAC,aAAa,EAAE,4hSAA4hS,CAAC;IAC7iS,CAAC,iBAAiB,EAAE,ilSAAilS,CAAC;IACtmS,CAAC,WAAW,EAAE,kjUAAkjU,CAAC;IACjkU,CAAC,eAAe,EAAE,649CAA649C,CAAC;IACh69C,CAAC,aAAa,EAAE,mtJAAmtJ,CAAC;IACpuJ,CAAC,YAAY,EAAE,ssPAAssP,CAAC;IACttP,CAAC,YAAY,EAAE,kxFAAkxF,CAAC;CACnyF,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,2oKAA2oK,CAAC;IAC1pK,CAAC,iBAAiB,EAAE,2sNAA2sN,CAAC;IAChuN,CAAC,YAAY,EAAE,+qHAA+qH,CAAC;IAC/rH,CAAC,eAAe,EAAE,gq9DAAgq9D,CAAC;IACnr9D,CAAC,eAAe,EAAE,01KAA01K,CAAC;IAC72K,CAAC,aAAa,EAAE,qwTAAqwT,CAAC;IACtxT,CAAC,iBAAiB,EAAE,s+TAAs+T,CAAC;IAC3/T,CAAC,WAAW,EAAE,u1VAAu1V,CAAC;IACt2V,CAAC,eAAe,EAAE,649CAA649C,CAAC;IACh69C,CAAC,aAAa,EAAE,85JAA85J,CAAC;IAC/6J,CAAC,YAAY,EAAE,o7SAAo7S,CAAC;IACp8S,CAAC,YAAY,EAAE,2jGAA2jG,CAAC;CAC5kG,CAAC,CAAC"}

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const HSX_VERSION = "5.4.2";
+export declare const HSX_VERSION = "5.6.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const HSX_VERSION = "5.4.2";
+export const HSX_VERSION = "5.6.0";
 //# sourceMappingURL=version.js.map

package/docs/README.md

@@ -246,6 +246,13 @@ maxAge 1d` requires a recent completed provider check.
 only to reservations. Fees settle with create moves, never reservations. Repeated clauses keep
 their declaration order. The JSON-like clause form remains accepted and lowers
 to the same [UDL clauses](https://github.com/hyperscale0/hyperscale-udl/blob/main/spec/README.md).
+Use `economics { purpose: earning, sourceParty: merchant }` on a move to
+classify posted money. Other purposes are `principal`, `participant_payout`,
+`internal`, `prepaid_credit`, and `pass_through`. `reversalOf: self.originalTransfer` links a
+reversal. The source party must own the source account, except when an earning
+releases the retained payer’s money from an agreement-bound instrument account
+to a company account outside the agreement. A reservation passes its economics
+to its post. Fee shorthand accepts separate economics for each expanded leg.
 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
@@ -433,3 +440,36 @@ 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.
+
+## Posted economics in the money flows
+
+Held customer funding and its unspent return are `principal`. A release for the
+company's sale is `earning`. A payment from company cash to another participant
+is `participant_payout`. Claims, waivers, write-offs and own-account allocations
+are `internal`; prepaid balance topups and returns are `prepaid_credit`. Tax is
+`pass_through`, excluded from earnings and costs. Unpaid claims count as neither.
+Refunds of paid profit, company charges and commission capture the original
+transfer and use `reversalOf`, so refunds reduce the original purpose.
+
+Fee shorthand accepts separate move economics: `economics { payee: { purpose:
+earning, sourceParty: payer }, fee: { purpose: earning, sourceParty: payer },
+tax: { purpose: pass_through, sourceParty: payer } }`. These describe authored
+product fees. Automatic platform fees keep their commercial classification.
+
+Any economics block can select by a resolved party: `economics { recipient:
+recipient, company: { purpose: earning, sourceParty: payer }, participant:
+{ purpose: participant_payout, sourceParty: programOperator } }`. The compiler
+chooses `company` for `operator`, `programOperator`, or a declared party with the
+`program_operator` role; it chooses `participant` for other bound parties.
+Both branches must be supplied. A branch may be `unclassified` when no purpose
+is established. Outside financing-profit and recovery recipients refund directly
+to the customer, not the company that funded the payout; those refund branches
+remain unclassified because they cannot reverse that company payout. Std
+recovery charges use this rule to avoid counting company receipts as participant
+costs. Direct customer payments to
+outside recipients are pass-through; payments from held company cash are costs.
+
+Generic transfers and mixed principal/profit distributions remain unclassified
+when their structure does not establish a purpose. Adapter-owned premium and
+claim accounts and credit-line advances also lack an authored source party.
+Their reports remain incomplete rather than guessing a company earning or cost.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/hsx",
-  "version": "5.4.2",
+  "version": "5.6.0",
   "description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
   "keywords": [
     "hsx",
@@ -85,8 +85,8 @@
     "examples:bundle": "bun scripts/bundle-examples.ts"
   },
   "dependencies": {
-    "@hyperscale0/adl": "1.0.0-beta.8",
-    "@hyperscale0/udl": "4.6.0",
+    "@hyperscale0/adl": "1.0.0-beta.10",
+    "@hyperscale0/udl": "4.8.0",
     "fast-sha256": "1.3.0"
   },
   "devDependencies": {
@@ -98,5 +98,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "bb10d3ee33343ddd5a4328401f25177cd46be9f6"
+  "gitHead": "be567dd18eb45ea3e02adc1f33b8491aa05df135"
 }

package/src/compile.ts

@@ -56,6 +56,7 @@ export interface CompileDiagnostic extends Diagnostic {
 export interface CompileOriginMapEntry {
   path: string;
   span: Span & { line: number; column: number };
+  standardBlock?: { key: string; recordPath: string; headerDigest: string };
 }
 export interface AdapterBindingTarget {
   adapter: ProviderAdapter;
@@ -428,6 +429,10 @@ export function compile(
       );
     const templates = new Map<string, InstrumentDecl>();
     const declarationSources = new Map<InstrumentDecl, string>();
+    const standardOrigins = new Map<
+      InstrumentDecl,
+      NonNullable<CompileOriginMapEntry["standardBlock"]>
+    >();
     const requirementOrigins = new Map<
       UdlSubjectRequirement,
       { source: string; span: Span; message: string }
@@ -447,6 +452,13 @@ export function compile(
       if (!content)
         fail(use, `unknown header ${use.name}`, "choose a published header");
       sources.set(use.name, content);
+      const bundled = bundledStandardLibrary.source(use.name);
+      const headerDigest =
+        bundled === content
+          ? Array.from(sha256(new TextEncoder().encode(content)), (byte) =>
+              byte.toString(16).padStart(2, "0"),
+            ).join("")
+          : undefined;
       let header;
       try {
         header = parseHeader(content, use.name);
@@ -475,6 +487,14 @@ export function compile(
           );
         templates.set(prefix, parentDecl);
         declarationSources.set(parentDecl, use.name);
+        if (headerDigest) {
+          const [, root, ...record] = prefix.split(".");
+          standardOrigins.set(parentDecl, {
+            key: `${use.name}.${root}`,
+            recordPath: record.join("."),
+            headerDigest,
+          });
+        }
         const recs = entries(asBlock(entries(parentDecl.body).get("records")));
         for (const [recName, recBlock] of recs) {
           const recDecl: InstrumentDecl = {
@@ -663,6 +683,7 @@ export function compile(
         exportPath: string;
         revision?: number | undefined;
       },
+      standardOrigin?: NonNullable<CompileOriginMapEntry["standardBlock"]>,
     ) => {
       const resolveFamilyInstruments = (
         family: UdlFamily,
@@ -2323,6 +2344,125 @@ export function compile(
               const key = parts.has("key")
                 ? String(data(parts.get("key")!))
                 : `move${index + 1}`;
+              const lowerEconomics = (
+                economicsExpr: Expr | undefined,
+              ): UdlAction["moves"][number]["economics"] => {
+                if (economicsExpr) {
+                  const resolved = resolve(economicsExpr);
+                  if (
+                    resolved.kind === "name" &&
+                    resolved.value === "unclassified"
+                  )
+                    return undefined;
+                  const choices = entries(asBlock(resolve(economicsExpr)));
+                  if (choices.has("recipient")) {
+                    for (const term of choices.keys())
+                      if (
+                        !["recipient", "company", "participant"].includes(term)
+                      )
+                        fail(
+                          economicsExpr,
+                          `unknown economics choice ${term}`,
+                          "use recipient, company and participant",
+                        );
+                    const recipient = String(data(choices.get("recipient")!));
+                    if (
+                      !isParty(recipient) ||
+                      !choices.has("company") ||
+                      !choices.has("participant")
+                    )
+                      fail(
+                        economicsExpr,
+                        "economics choice needs a bound recipient and both branches",
+                        "declare recipient, company and participant",
+                      );
+                    const company =
+                      recipient === "operator" ||
+                      recipient === "programOperator" ||
+                      document.parties[recipient]?.role === "program_operator";
+                    return lowerEconomics(
+                      choices.get(company ? "company" : "participant"),
+                    );
+                  }
+                }
+                const economicsParts = economicsExpr
+                  ? entries(asBlock(resolve(economicsExpr)))
+                  : undefined;
+                if (economicsParts) {
+                  for (const term of economicsParts.keys())
+                    if (
+                      !["purpose", "sourceParty", "reversalOf"].includes(term)
+                    )
+                      fail(
+                        economicsExpr!,
+                        `unknown economics term ${term}`,
+                        "use purpose, sourceParty or reversalOf",
+                      );
+                }
+                const purpose = economicsParts?.get("purpose");
+                const sourceParty = economicsParts?.get("sourceParty");
+                if (economicsParts && (!purpose || !sourceParty))
+                  fail(
+                    economicsExpr!,
+                    "economics needs purpose and sourceParty",
+                    "declare both economics fields",
+                  );
+                const purposeName = purpose ? String(data(purpose)) : undefined;
+                if (
+                  purposeName &&
+                  ![
+                    "earning",
+                    "principal",
+                    "participant_payout",
+                    "internal",
+                    "prepaid_credit",
+                    "pass_through",
+                  ].includes(purposeName)
+                )
+                  fail(
+                    purpose!,
+                    `unknown economic purpose ${purposeName}`,
+                    "choose a declared economic purpose",
+                  );
+                const sourcePartyName = sourceParty
+                  ? String(data(sourceParty))
+                  : undefined;
+                if (sourcePartyName && !isParty(sourcePartyName))
+                  fail(
+                    sourceParty!,
+                    `unknown source party ${sourcePartyName}`,
+                    "bind an authored party",
+                  );
+                return economicsParts
+                  ? {
+                      purpose: purposeName as NonNullable<
+                        UdlAction["moves"][number]["economics"]
+                      >["purpose"],
+                      sourceParty: sourcePartyName!,
+                      ...(economicsParts.has("reversalOf")
+                        ? {
+                            reversalOf: path(economicsParts.get("reversalOf")!),
+                          }
+                        : {}),
+                    }
+                  : undefined;
+              };
+              const economicsExpr = parts.get("economics");
+              const feeEconomics =
+                parts.has("fee") && economicsExpr
+                  ? entries(asBlock(resolve(economicsExpr)))
+                  : undefined;
+              if (feeEconomics)
+                for (const term of feeEconomics.keys())
+                  if (!["payee", "fee", "tax"].includes(term))
+                    fail(
+                      economicsExpr!,
+                      `unknown fee economics leg ${term}`,
+                      "declare payee, fee or tax economics separately",
+                    );
+              const economics = lowerEconomics(
+                feeEconomics ? feeEconomics.get("payee") : economicsExpr,
+              );
               if (
                 op === "internal_transfer.create" ||
                 op === "internal_transfer.reserve"
@@ -2418,6 +2558,7 @@ export function compile(
                     a.moves.push({
                       key: `${key}_${index + 1}`,
                       operation: "internal_transfer.create",
+                      ...(economics ? { economics } : {}),
                       amount: piece,
                       from: path(from),
                       to: `party.${recipient.value}`,
@@ -2440,6 +2581,7 @@ export function compile(
                 const transfer = {
                   key,
                   operation: op,
+                  ...(economics ? { economics } : {}),
                   ...(parts.has("capture")
                     ? { capture: String(data(parts.get("capture")!)) }
                     : {}),
@@ -2585,6 +2727,9 @@ export function compile(
                   });
                   a.moves.push({
                     key: key + "Fee",
+                    ...(feeEconomics?.has("fee")
+                      ? { economics: lowerEconomics(feeEconomics.get("fee")) }
+                      : {}),
                     operation: "internal_transfer.create",
                     amount: charge,
                     from: transfer.from,
@@ -2593,6 +2738,9 @@ export function compile(
                   if (vat)
                     a.moves.push({
                       key: key + "Tax",
+                      ...(feeEconomics?.has("tax")
+                        ? { economics: lowerEconomics(feeEconomics.get("tax")) }
+                        : {}),
                       operation: "internal_transfer.create",
                       amount: vat,
                       from: transfer.from,
@@ -2606,6 +2754,7 @@ export function compile(
                 a.moves.push({
                   key,
                   operation: op,
+                  ...(economics ? { economics } : {}),
                   transfer: path(parts.get("transfer")!),
                   ...(parts.has("capture")
                     ? { capture: String(data(parts.get("capture")!)) }
@@ -2719,6 +2868,7 @@ export function compile(
       origins.push({
         path: `$.instruments[${document.instruments.length}]`,
         span: { ...origin, ...lineColAt(source, origin.start) },
+        ...(standardOrigin ? { standardBlock: standardOrigin } : {}),
       });
       if (familyDeclaration && familyDeclaration.revision !== undefined) {
         inst.family = {
@@ -2776,6 +2926,14 @@ export function compile(
           enums,
           childAttachment,
           childFamily,
+          standardOrigin
+            ? {
+                ...standardOrigin,
+                recordPath: [standardOrigin.recordPath, key]
+                  .filter(Boolean)
+                  .join("."),
+              }
+            : undefined,
         );
       }
     };
@@ -2907,6 +3065,7 @@ export function compile(
               attachments,
             },
             templateFamily ? { ...templateFamily } : undefined,
+            standardOrigins.get(template),
           );
         } catch (error) {
           if (!(error instanceof CompileFailure)) throw error;
@@ -3052,6 +3211,7 @@ export function compile(
           new Map(),
           undefined,
           templateFamily ? { ...templateFamily } : undefined,
+          standardOrigins.get(template),
         );
       }
       if (decl.kind === "object") {

package/src/parse.ts

@@ -450,6 +450,7 @@ class Parser {
     }
     for (const key of ["fee", "capture", "key"])
       if (this.eat(key)) values[key] = this.atom();
+    if (this.eat("economics")) values.economics = this.block();
     if (this.eat("boundary"))
       values.boundary = this.record({ adapter: this.atom() });
     return this.record(values);