@hyperscale0/udl 1.0.0-rc.1 → 1.0.123

package/dist/parser.js

@@ -1,44 +0,0 @@
-import { serializeUdl } from "./canonical.js";
-import { issue } from "./diagnostics.js";
-import { UDL_LIMITS } from "./limits.js";
-import { assertValidUdl, UdlError } from "./validation.js";
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-export function parseUdl(source) {
-    const sourceBytes = typeof source === "string"
-        ? source.length > UDL_LIMITS.maxSourceBytes
-            ? source.length
-            : new TextEncoder().encode(source).byteLength
-        : source.byteLength;
-    if (sourceBytes > UDL_LIMITS.maxSourceBytes) {
-        throw new UdlError([
-            issue("UDL1004", "$", `UDL source exceeds ${UDL_LIMITS.maxSourceBytes} bytes`),
-        ]);
-    }
-    return parseUdlText(typeof source === "string" ? source : decodeUdlBytes(source));
-}
-function parseUdlText(source) {
-    let value;
-    try {
-        value = JSON.parse(source);
-    }
-    catch (error) {
-        throw new UdlError([
-            issue("UDL1002", "$", error instanceof Error ? error.message : "could not parse JSON"),
-        ]);
-    }
-    return assertValidUdl(value);
-}
-export function canonicalizeUdl(source) {
-    return serializeUdl(parseUdl(source));
-}
-function decodeUdlBytes(source) {
-    try {
-        return utf8Decoder.decode(source);
-    }
-    catch {
-        throw new UdlError([
-            issue("UDL1001", "$", "UDL bytes must be valid UTF-8"),
-        ]);
-    }
-}
-//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE9D,MAAM,UAAU,QAAQ,CAAC,MAA2B;IAClD,MAAM,WAAW,GACf,OAAO,MAAM,KAAK,QAAQ;QACxB,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,UAAU,CAAC,cAAc;YACzC,CAAC,CAAC,MAAM,CAAC,MAAM;YACf,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU;QAC/C,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,WAAW,GAAG,UAAU,CAAC,cAAc,EAAE,CAAC;QAC5C,MAAM,IAAI,QAAQ,CAAC;YACjB,KAAK,CACH,SAAS,EACT,GAAG,EACH,sBAAsB,UAAU,CAAC,cAAc,QAAQ,CACxD;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CACjB,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAY,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC;YACjB,KAAK,CACH,SAAS,EACT,GAAG,EACH,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAChE;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAA2B;IACzD,OAAO,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,cAAc,CAAC,MAAkB;IACxC,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAAC;YACjB,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,+BAA+B,CAAC;SACvD,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/docs/README.md

@@ -1,14 +0,0 @@
-# UDL documentation
-
-UDL is the versioned JSON contract between a product definition and an engine that executes it. Start with the document guide, then read the guides in order. Validator authors should also read the canonical bytes law and run the conformance corpus.
-
-1. [A document](guide/01-a-document.md)
-2. [Money steps](guide/02-money-steps.md)
-3. [The ten laws](guide/03-laws.md)
-4. [Fees and remainder](guide/04-fees-and-remainder.md)
-5. [Checks, updates, and dials](guide/05-checks-updates-dials.md)
-6. [Effects](guide/06-effects.md)
-7. [Evolution](guide/07-evolution.md)
-8. [Implementing UDL](guide/08-implementing.md)
-
-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/guide/01-a-document.md

@@ -1,37 +0,0 @@
-# A document
-
-A UDL document names one product and contains its subjects and instruments. Each instrument declares stored fields, required fields, a lifecycle, and the actions that create or change an instance.
-
-This is the smallest admitted document. `create` starts at `open`. `close` follows the matching lifecycle transition and ends at `closed`.
-
-```json
-{
-  "instruments": [
-    {
-      "actionOrder": ["close", "create"],
-      "fields": { "reference": { "type": "string" } },
-      "id": "note",
-      "idPrefix": "note",
-      "lifecycle": {
-        "initial": "open",
-        "states": ["open", "closed"],
-        "transitions": { "close": { "from": ["open"], "to": "closed" } }
-      },
-      "required": ["reference"],
-      "summary": "A note a tenant files and later closes.",
-      "title": "Note",
-      "actions": {
-        "close": { "moves": [], "steps": [], "summary": "Close the note." },
-        "create": { "moves": [], "steps": [], "summary": "File the note." }
-      }
-    }
-  ],
-  "product": "minimal",
-  "subjects": [],
-  "title": "Minimal",
-  "udl": 1,
-  "version": 1
-}
-```
-
-The JSON Schema checks the written shape. `validateUdl` then checks names, references, lifecycle reachability, and the money graph. A document has no canonical form until both checks pass.

package/docs/guide/02-money-steps.md

@@ -1,23 +0,0 @@
-# Money steps
-
-UDL seals internal ledger work to seven kernel operations. Four instructions create, reserve, post, or void an internal transfer. Three account instructions provision an escrow account, freeze an account, or unfreeze it.
-
-A step names an operation and binds its inputs from action input, constants, or instance fields and refs. `capture` writes selected operation output into durable refs. A later step can read those refs.
-
-```jsonc
-{
-  "operation": "internal_transfer.reserve",
-  "bind": {
-    "sourceAccountId": { "from": "instance", "path": "fields.payerAccountId" },
-    "destinationAccountId": {
-      "from": "instance",
-      "path": "refs.escrowAccountId",
-    },
-    "amount": { "from": "instance", "path": "fields.amount" },
-    "currency": { "from": "const", "value": "SAR" },
-  },
-  "capture": { "transferId": "reservationId" },
-}
-```
-
-`payout` is an execution intent, not an eighth kernel operation. It reads stored money and beneficiary data, then captures a durable payout reference. A later system action can reconcile that payout against settlement evidence.

package/docs/guide/03-laws.md

@@ -1,18 +0,0 @@
-# The ten laws
-
-The schema defines shape. These laws define meaning.
-
-1. Every UDL concept fits in one sentence.
-2. Provider formats and operating machinery stay below UDL. `reconcile` names settlement evidence against a declared provider-side row. It does not model the provider file or transport.
-3. Every state change emits an event.
-4. Internal ledger money uses the seven sealed operations.
-5. Every instance has the same identity, status, timestamp, and metadata frame. Money uses integer minor-unit strings plus a currency.
-6. Requirements such as due time, checks, references, quote commitment, and reconciliation are data.
-7. A stored definition evolves by additive change only.
-8. Instruments, actions, operations, and fields follow their declared naming patterns.
-9. Real delays appear as statuses and timestamps.
-10. Every state, reference, gate, and funded path closes inside the document.
-
-A reconcile exception names the child fields that receive the unmatched amount and its reason. `exception.amountField` must be a required money field on the child. `exception.reasonField` must be a required plain text field. A plain text field has `type: "string"` and no `pattern`, `format`, or `enum`. Admission rejects a missing or optional field, the wrong type, or a child that does not belong to the declaring instrument.
-
-The [diagnostic reference](../reference/diagnostics.md) lists every stable `UDL####` refusal code. The [specification](../../spec/README.md) carries the normative prose for each law.

package/docs/guide/04-fees-and-remainder.md

@@ -1,15 +0,0 @@
-# Fees and remainder
-
-Fee rules derive named amounts from a stored base amount. Partitions state how cancellation or reversal divides held money. A remainder clause computes one amount after named deductions and captures it under `amountRef`.
-
-```jsonc
-{
-  "remainder": {
-    "amountRef": "sellerNet",
-    "from": "fields.amount",
-    "subtract": ["refs.platformFee"],
-  },
-}
-```
-
-Computed money has one author. A remainder, signed sum, distribution, quote, or derived amount must not compete with another clause for the same field or ref. A money move consumes the computed value once. The validator rejects missing sources, duplicate outputs, and terminal paths that strand funded value.

package/docs/guide/05-checks-updates-dials.md

@@ -1,7 +0,0 @@
-# Checks, updates, and dials
-
-`requiresChecks` asks for current evidence from a declared provider family. The row names the check kind, acceptable statuses, subject field, and optional maximum age. Callers cannot replace the evidence with a boolean.
-
-`update` declares which stored fields an update operation may change. Action-level `updates` assign admitted values. Required creation fields, derived amounts, immutable bindings, and quote-frozen fields remain protected.
-
-Dials are named policy values with bounds. Clauses refer to a dial by id instead of copying a threshold into several actions. The document therefore exposes one reviewable setting for limits such as reconciliation tolerance.

package/docs/guide/06-effects.md

@@ -1,11 +0,0 @@
-# Effects
-
-Effects are derived ABI rows. Authors declare clauses such as moves, decisions, schedules, reads, and notifications. The compiler derives the `effects` object from those clauses in vocabulary order.
-
-Each row records its source and a stable signature. Movement signatures include their cost class. Schedule signatures identify a deadline or due trigger. Read signatures identify the gate family. Notification rows retain channel and role.
-
-The validator derives the rows again and compares the complete object, including row order. A missing, extra, changed, or reordered row is a refusal. Derived effect subtrees do not count toward the authored node budget, but they still pass JSON, depth, and string limits.
-
-Cost tooling reads the same movement and hold signatures. Runtime hints may read the effect rows, but they cannot change the clauses that produced them.
-
-`quote` derives `holds.quote` and `schedules.expiry`. `reconcile` derives one `reads.reconcile` row per expectation. `commit` has no separate effect row. The committing action consumes the held quote through its `moves.*` row, so another consumption row would count the same work twice.

package/docs/guide/07-evolution.md

@@ -1,11 +0,0 @@
-# Evolution
-
-`diffValidatedUdlEvolution(live, next)` compares two admitted documents. The CLI exposes the same check as `udl diff live.udl next.udl`.
-
-Once instances exist, a new version may add optional fields, states, transitions, and actions. It may not remove or rename stored structure, tighten an admitted schema, change a money step, or reuse an existing version number for different executable meaning. The diff returns `UDL7xxx` issues with JSON paths.
-
-A migration is work outside the format. It reads stored instances under their original document, writes data required by a new document, and changes the pinned definition only after that work succeeds. Editing the document does not migrate data.
-
-Keep old canonical documents with stored instances. A format bump changes the literal `udl` value. A reader must keep explicit decoders for supported older formats rather than silently treating old bytes as the newest grammar.
-
-Evolution does not invent defaults for executable clause fields. In particular, it does not guess `reconcile.exception.amountField` or `reasonField` for an older snapshot. A candidate must name both fields and pass the current validator before the diff can judge it.

package/docs/guide/08-implementing.md

@@ -1,13 +0,0 @@
-# Implementing UDL
-
-A second implementation needs three independent checks.
-
-1. Validate JSON shape against `spec/udl.schema.json`.
-2. Enforce the whole-document laws and report the matching `UDL####` code and JSON path.
-3. Serialize admitted documents under the canonical bytes law.
-
-Run every conformance level. Valid cases must admit and match their canonical bytes and SHA-256 digest. Invalid cases must report every listed code and path. Evolution pairs must produce the listed `UDL7xxx` issues. An implementation may report more issues, but it may not omit a listed issue.
-
-Do not key behavior on diagnostic messages. Titles, details, and fixes can become clearer. Codes cannot change once published.
-
-Keep parsing, validation, canonicalization, and evolution comparison separate. That split prevents a diff from judging a candidate that the validator would refuse on its own.