@hyperscale0/udl 2.6.1 → 3.0.1

package/docs/llms.txt

@@ -1,14 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.1. Edit the source, not llms.txt. -->
-
-# UDL documentation
-
-- [Start here](README.md)
-- [Write a document](guide/01-a-document.md)
-- [Understand the laws](guide/03-laws.md)
-- [Evolve a stored document](guide/07-evolution.md)
-- [Implement UDL](guide/08-implementing.md)
-- [Clause reference](reference/clauses.md)
-- [Diagnostic reference](reference/diagnostics.md)
-- [Canonical bytes](reference/canonical.md)
-- [Command reference](reference/cli.md)
-- [Conformance contract](../conformance/README.md)

package/docs/piece-plans.md

@@ -1,148 +0,0 @@
-# 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/canonical.md

@@ -1,16 +0,0 @@
-# Canonical bytes
-
-An admitted UDL document has one canonical byte sequence.
-
-- Encode JSON as UTF-8 without a byte-order mark.
-- Sort every object's keys by ascending UTF-16 code unit. Compare code units, not locale order or Unicode collation order.
-- Preserve array order exactly as authored. Never sort an array.
-- Indent nested values with two ASCII spaces. Write one ASCII space after each colon.
-- Write empty objects as `{}` and empty arrays as `[]`.
-- Serialize JSON numbers with JavaScript `JSON.stringify` semantics. An admitted integer uses base-10 digits with an optional leading minus and no leading zeros. Negative zero serializes as `0`. UDL money is not a JSON number. It is a base-10 integer minor-unit string paired with a currency code.
-- Apply ECMAScript well-formed `JSON.stringify` string escaping. Escape U+0000 through U+001F. Escape every lone surrogate as `\uXXXX`. Write every other code point literally, including U+007F and U+2028.
-- End the document with exactly one line feed byte, `0A`. Write no other trailing whitespace.
-
-`serializeUdl(document)` validates and writes these bytes. `canonicalizeUdl(input)` parses, validates, and writes them. Canonicalizing canonical bytes returns the same bytes.
-
-`canonicalDigest(document)` computes SHA-256 over the canonical UTF-8 bytes and returns a promise for the lowercase hexadecimal digest. `udl canon file.udl --digest` prints that digest. It does not hash the source bytes before canonicalization.