@hyperscale0/udl 2.2.0 → 2.3.0

package/docs/README.md

@@ -11,4 +11,7 @@ UDL is the versioned JSON contract between a product definition and an engine th
 7. [Evolution](guide/07-evolution.md)
 8. [Implementing UDL](guide/08-implementing.md)
 
+[Piece plans and private action composition](piece-plans.md) is a worked
+instrument fragment for `piecePlan`, `pieceStage`, `calls` and `actionLibrary`.
+
 The [clause reference](reference/clauses.md) and [diagnostic reference](reference/diagnostics.md) come from the package tables. The [command reference](reference/cli.md) comes from the CLI usage text. Do not edit those generated files by hand.

package/docs/llms-full.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.2.0. Edit the source, not llms-full.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.3.0. Edit the source, not llms-full.txt. -->
 
 # UDL complete reference
 
@@ -17,6 +17,9 @@ UDL is the versioned JSON contract between a product definition and an engine th
 7. [Evolution](guide/07-evolution.md)
 8. [Implementing UDL](guide/08-implementing.md)
 
+[Piece plans and private action composition](piece-plans.md) is a worked
+instrument fragment for `piecePlan`, `pieceStage`, `calls` and `actionLibrary`.
+
 The [clause reference](reference/clauses.md) and [diagnostic reference](reference/diagnostics.md) come from the package tables. The [command reference](reference/cli.md) comes from the CLI usage text. Do not edit those generated files by hand.
 
 <!-- source: guide/01-a-document.md -->

package/docs/llms.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.2.0. Edit the source, not llms.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.3.0. Edit the source, not llms.txt. -->
 
 # UDL documentation
 

package/docs/piece-plans.md

@@ -0,0 +1,148 @@
+# Piece plans and private action composition
+
+UDL preserves the authored graph and the order needed to interpret it.
+`piecePlan` declares a finite partition, `pieceStage` names a stage, `calls`
+binds private actions, and `actionLibrary` supplies their definitions. HSX
+spells these clauses `piece_plan`, `piece_stage`, `calls` and `action_library`.
+The shapes live in [`schema.ts`](../src/schema.ts); resolution and finance
+validation live in [`validation.ts`](../src/validation.ts). The
+[clause reference](reference/clauses.md) describes the complete vocabulary.
+
+## Worked sale example
+
+The following decoded instrument fragment uses the sale settlement's price
+partition and refund action. Add it to an instrument with its required
+immutable fields, matching partition, lifecycle and captured escrow account.
+It omits the surrounding document and other actions. It is formatted for
+reading; canonical serialization sorts object keys and retains array order.
+
+```json
+{
+  "piecePlan": {
+    "id": "price",
+    "total": "price",
+    "pieces": [
+      {
+        "id": "seller",
+        "amount": "piece1Amount",
+        "release_to": "sellerAccountId",
+        "refund_to": "buyerAccountId"
+      },
+      {
+        "id": "platform_fee",
+        "amount": "piece2Amount",
+        "release_to": "platformAccountId",
+        "refund_to": "buyerAccountId"
+      },
+      {
+        "id": "seller_cancel_fee",
+        "amount": "piece3Amount",
+        "release_to": "platformAccountId",
+        "refund_to": "sellerAccountId"
+      }
+    ],
+    "fund_order": ["seller", "platform_fee", "seller_cancel_fee"],
+    "release_order": ["platform_fee", "seller_cancel_fee"],
+    "refund_order": ["platform_fee", "seller_cancel_fee"],
+    "unfund_order": ["seller_cancel_fee", "platform_fee", "seller"]
+  },
+  "actionLibrary": {
+    "settlement_piece": {
+      "actionOrder": ["move"],
+      "actions": {
+        "move": {
+          "parameters": {
+            "piece": { "kind": "piece" },
+            "source": { "kind": "account" },
+            "destination": { "kind": "account" }
+          },
+          "principal": "api_key",
+          "approval": "inherit",
+          "recovery": "local",
+          "order": ["transfer"],
+          "calls": [],
+          "leaves": [
+            {
+              "id": "transfer",
+              "operation": "internal_transfer.create",
+              "bind": {
+                "amount": "$piece.amount",
+                "currency": "$piece.currency",
+                "sourceAccountId": "$source",
+                "destinationAccountId": "$destination"
+              },
+              "effects": [
+                { "kind": "moves", "signature": "moves.transfer.internal" }
+              ],
+              "evidence": "transferId"
+            }
+          ]
+        }
+      }
+    }
+  },
+  "actions": {
+    "refund_piece": {
+      "pieceStage": { "plan": "price", "stage": "refund" },
+      "calls": [
+        {
+          "id": "move_piece",
+          "action": "settlement_piece.move",
+          "bind": {
+            "piece": "$piece",
+            "source": "$instance.refs.escrowAccountId",
+            "destination": "$piece.refund_to"
+          }
+        }
+      ],
+      "steps": [],
+      "summary": "Refund a piece of a sale settlement"
+    }
+  }
+}
+```
+
+The containing instrument's `actionOrder` includes `refund_piece` at its
+authored position. Both library `actionOrder` and private action `order` must
+be exact permutations of their members. The stage derives a required
+`pieceId` enum, here `platform_fee` or `seller_cancel_fee`. The selector does
+not add another transfer; the private leaf moves its amount once.
+
+For the sale's example amounts, `piece1Amount` is `245000`, `piece2Amount` is
+`3750`, and `piece3Amount` is `1250`, all SAR minor units. They partition
+`price` of `250000`. Cancellation's separate decision action returns the seller
+piece to the buyer. The refund stage then returns `3750` to the buyer and pays
+`1250` to the seller. Unfund follows its reverse order and returns every funded
+piece to the buyer instead. The service fee stays outside the price partition.
+
+`resolveUdlActionPlans` returns plans and issues. A plan identifies its action
+and optional piece ID, with resolved effects and leaves. Each leaf retains
+`originPath`, step, effects and evidence. Resolution expands static calls; it
+does not replace the source graph in canonical UDL. A private library entry is
+not a public action. [`refactor-clauses.spec.ts`](../test/refactor-clauses.spec.ts)
+checks piece constraints, graph order, cycles, bindings, authority and evidence.
+
+## Conservation and diagnostics
+
+UDL 2.3.0 checks funded amounts over piece progress. A partially funded path
+must return only the pieces actually funded; selecting one piece is not proof
+that a whole stage completed. For a piece plan, `expandPieceProgress` bounds the reachable lifecycle/progress
+states at 256. Instruments without a piece plan use the separate action-plan
+combination bound. These bounds belong to the proof, not to a runtime retry
+loop. [`udl.spec.ts`](../test/udl.spec.ts) includes the stranded-funded-piece
+refusal; [`validation.ts`](../src/validation.ts) owns the progress expansion.
+
+[`diagnostics.ts`](../src/diagnostics.ts) defines the refusal codes:
+
+| Code      | Refusal                | Repair                                                                                   |
+| --------- | ---------------------- | ---------------------------------------------------------------------------------------- |
+| `UDL4001` | Money graph violation  | Balance each funded amount and close every hold on each lifecycle path                   |
+| `UDL5013` | Piece stage violation  | Select a declared plan/stage, valid ordered piece IDs and a call-based stage action      |
+| `UDL2010` | Action graph violation | Resolve targets and remove cycles, collisions or invalid order within depth/count limits |
+
+A partition mismatch or incompatible immutable field is `UDL4002`. A typed
+binding failure is `UDL2011`; an authority boundary is `UDL2012`; incomplete
+effects or evidence are `UDL2013`. These failures are not permission to skip
+the independent conservation oracle. Keep actions that need another principal,
+independent approval or external recovery as separate calls at the public
+boundary, not flattened private work.

package/docs/reference/clauses.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.2.0. Edit the source, not clauses.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.3.0. Edit the source, not clauses.md. -->
 
 # Clause reference
 

package/docs/reference/cli.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.2.0. Edit the source, not cli.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.3.0. Edit the source, not cli.md. -->
 
 # Command reference
 

package/docs/reference/diagnostics.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.2.0. Edit the source, not diagnostics.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.3.0. Edit the source, not diagnostics.md. -->
 
 # Diagnostic reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
   "keywords": [
     "udl",
@@ -84,5 +84,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "982ff68eee44e481944fe0bc50c6eee6fee17059"
+  "gitHead": "ed8866f5e5201aad938ad0219da06e430a513467"
 }

package/src/effects.ts

@@ -66,6 +66,26 @@ function boundPath(move: Movement, endpoint: string): string | undefined {
  * External collection, deposit, and payout operations carry their role in the
  * operation family because their remote endpoint is not a UDL account binding.
  */
+/**
+ * The typed kind of an instance ref a call binding may name. Refs exist only
+ * through step and move captures on the same instrument; a capture of a leaf's
+ * `accountId` output is an account, every other capture is opaque text.
+ */
+function capturedRefKind(
+  instrument: UdlInstrument,
+  refName: string,
+): "account" | "text" | undefined {
+  for (const action of Object.values(instrument.actions)) {
+    for (const step of [...action.steps, ...action.moves]) {
+      const output = step.capture?.[refName];
+      if (output !== undefined) {
+        return output === "accountId" ? "account" : "text";
+      }
+    }
+  }
+  return undefined;
+}
+
 export function movementClass(move: Movement): UdlMovementClass {
   if (move.operation.startsWith("internal_transfer.")) {
     const source = boundPath(move, "sourceAccountId");
@@ -231,6 +251,35 @@ function encodeOriginPathKey(originPath: readonly string[]): string {
   return `k_${parts.join("_")}`;
 }
 
+function sameEffectSignatures(
+  left: readonly { readonly kind: UdlEffectKind; readonly signature: string }[],
+  right: readonly {
+    readonly kind: UdlEffectKind;
+    readonly signature: string;
+  }[],
+): boolean {
+  const count = (
+    effects: readonly {
+      readonly kind: UdlEffectKind;
+      readonly signature: string;
+    }[],
+  ) => {
+    const counts = new Map<string, number>();
+    for (const eff of effects) {
+      const key = `${eff.kind}:${eff.signature}`;
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+  };
+  const leftCounts = count(left);
+  const rightCounts = count(right);
+  if (leftCounts.size !== rightCounts.size) return false;
+  for (const [key, n] of leftCounts) {
+    if (rightCounts.get(key) !== n) return false;
+  }
+  return true;
+}
+
 function expectedLeafEffects(
   step: UdlStep | UdlMove,
 ): readonly { readonly kind: UdlEffectKind; readonly signature: string }[] {
@@ -925,6 +974,35 @@ export function resolveUdlActionPlans(
             path: parts[1],
           };
         }
+        if (parts[1] === "refs") {
+          if (parts.length !== 3) {
+            issues.push(
+              issue(
+                "UDL2011",
+                leafPath,
+                `invalid trailing member access on instance ref: ${rawBind}`,
+              ),
+            );
+            return undefined;
+          }
+          const refName = parts[2]!;
+          const captured = capturedRefKind(instrument, refName);
+          if (!captured) {
+            issues.push(
+              issue(
+                "UDL2011",
+                leafPath,
+                `referenced ref ${refName} is not captured by any step or move on instrument`,
+              ),
+            );
+            return undefined;
+          }
+          return {
+            binding: { from: "instance", path: `refs.${refName}` },
+            kind: captured,
+            path: `refs.${refName}`,
+          };
+        }
         issues.push(
           issue(
             "UDL2011",
@@ -1275,27 +1353,17 @@ export function resolveUdlActionPlans(
           consumedSources.add(holdKey);
         }
 
+        // A library leaf is written once and expanded under several callers,
+        // so its declaration names the operation's generic class (the class
+        // with no bindings). Each expansion then carries the class its
+        // resolved bindings select, exactly as an inline move would: a buyer
+        // funding escrow is a pay-in, the same leaf paying out is internal.
         const expectedEffects = expectedLeafEffects(step);
-        const actualCounts = new Map<string, number>();
-        for (const eff of leaf.effects) {
-          const key = `${eff.kind}:${eff.signature}`;
-          actualCounts.set(key, (actualCounts.get(key) ?? 0) + 1);
-        }
-        const expectedCounts = new Map<string, number>();
-        for (const eff of expectedEffects) {
-          const key = `${eff.kind}:${eff.signature}`;
-          expectedCounts.set(key, (expectedCounts.get(key) ?? 0) + 1);
-        }
-        let effectsMatch = actualCounts.size === expectedCounts.size;
-        if (effectsMatch) {
-          for (const [k, count] of actualCounts.entries()) {
-            if (expectedCounts.get(k) !== count) {
-              effectsMatch = false;
-              break;
-            }
-          }
-        }
-        if (!effectsMatch) {
+        const genericEffects = expectedLeafEffects({ ...step, bind: {} });
+        if (
+          !sameEffectSignatures(leaf.effects, expectedEffects) &&
+          !sameEffectSignatures(leaf.effects, genericEffects)
+        ) {
           issues.push(
             issue(
               "UDL2013",
@@ -1306,7 +1374,7 @@ export function resolveUdlActionPlans(
         }
 
         expandedLeaves.push({
-          effects: leaf.effects,
+          effects: expectedEffects,
           evidence: leaf.evidence,
           originPath,
           step,

package/src/index.ts

@@ -109,6 +109,7 @@ export {
   reconcileExceptionChildProblems,
   openReferenceShapeBudget,
   UdlError,
+  instrumentFinanceIssues,
   validateUdl,
   validateUdlJsonSchema,
   validateUdlSchemaValue,