@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/docs/reference/cli.md

@@ -0,0 +1,22 @@
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0. Edit the source, not cli.md. -->
+
+# Command reference
+
+The installed `udl` binary exposes the following commands and exit codes.
+
+```text
+udl - the Universal Domain Language toolchain
+
+usage:
+  udl validate <file>          parse <file> and report every issue found
+  udl fmt <file> [--write]     print the canonical form, or rewrite the file
+  udl canon <file> [--digest]  print canonical bytes, or their SHA-256 digest
+  udl diff <live> <next>       check <next> against the append-only law
+  udl explain UDL####          explain one stable diagnostic code
+  udl help                     print this
+
+exit codes:
+  0  the document is admissible, or the change is additive
+  1  the document was refused, or the change breaks the append-only law
+  2  the command line was wrong, or a file could not be read
+```

package/docs/reference/diagnostics.md

@@ -0,0 +1,32 @@
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0. Edit the source, not diagnostics.md. -->
+
+# Diagnostic reference
+
+Codes are stable. Titles and messages may become clearer without changing the code. Apply the listed fix, then validate the whole document again.
+
+| Code      | Family    | Category          | Title                                                   | Fix                                                                                                    |
+| --------- | --------- | ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `UDL1001` | admission | invalid_utf8      | Invalid UTF-8                                           | Encode the document as valid UTF-8.                                                                    |
+| `UDL1002` | admission | invalid_json      | Invalid JSON                                            | Repair the JSON syntax before validation.                                                              |
+| `UDL1003` | admission | invalid_shape     | Invalid document shape                                  | Match the published UDL JSON Schema.                                                                   |
+| `UDL1004` | admission | resource_limit    | Resource limit exceeded                                 | Reduce the source size, nesting, values, strings, references, or financial paths named by the message. |
+| `UDL2001` | document  | invalid_semantics | Duplicate declaration                                   | Give each declaration a unique name.                                                                   |
+| `UDL2002` | document  | invalid_semantics | Document law violation                                  | Repair the declaration, subject contract, or derived effects named by the message.                     |
+| `UDL2005` | document  | invalid_semantics | Derived effects mismatch                                | Regenerate the action effects from its clauses.                                                        |
+| `UDL3001` | lifecycle | invalid_semantics | Lifecycle is not closed                                 | Declare every state and action transition, and make every state reachable.                             |
+| `UDL4001` | finance   | invalid_semantics | Money graph violation                                   | Balance every funded amount and close every hold on each lifecycle path.                               |
+| `UDL5001` | gates     | invalid_semantics | Reference gate violation                                | Point the gate at a declared instrument, action, state, field, and reference.                          |
+| `UDL5002` | gates     | invalid_semantics | Check requirement violation                             | Use a declared check with compatible evidence and recurrence.                                          |
+| `UDL5003` | gates     | invalid_semantics | Exposure gate violation                                 | Use declared account and money fields for the exposure gate.                                           |
+| `UDL5004` | gates     | invalid_semantics | Aggregate law violation                                 | Point the aggregate at compatible parent and child fields.                                             |
+| `UDL5005` | gates     | invalid_semantics | Settlement or payout violation                          | Use a declared settlement account and a compatible payout statement line.                              |
+| `UDL5006` | gates     | invalid_semantics | Quote and commit violation                              | Declare one complete quote freeze set and one matching commit action.                                  |
+| `UDL5007` | gates     | invalid_semantics | Reconcile exception child violation                     | Name a declared child whose reference points back to this instrument.                                  |
+| `UDL5008` | gates     | invalid_semantics | Action clause violation                                 | Repair the clause fields and keep incompatible clauses separate.                                       |
+| `UDL5009` | gates     | invalid_semantics | Reconcile exception amount field is missing or optional | Name the exception child's required money field in amountField.                                        |
+| `UDL5010` | gates     | invalid_semantics | Reconcile exception amount field has the wrong type     | Point amountField at a money field declared by the exception child.                                    |
+| `UDL5011` | gates     | invalid_semantics | Reconcile exception reason field is missing or optional | Name the exception child's required text field in reasonField.                                         |
+| `UDL5012` | gates     | invalid_semantics | Reconcile exception reason field has the wrong type     | Point reasonField at a required plain text field declared by the exception child.                      |
+| `UDL6001` | schema    | invalid_semantics | Unsupported JSON Schema                                 | Use only the sealed UDL JSON Schema subset.                                                            |
+| `UDL7001` | evolution | invalid_evolution | Stored contract changed                                 | Keep stored identities and contracts unchanged, and add only allowed optional declarations.            |
+| `UDL7002` | evolution | invalid_evolution | Version was not increased                               | Increase the product version for every semantic change.                                                |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0",
   "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
   "keywords": [
     "udl",
@@ -47,7 +47,9 @@
     "SECURITY.md",
     "TRADEMARKS.md",
     "conformance",
+    "docs",
     "dist",
+    "skills",
     "spec",
     "src"
   ],
@@ -59,7 +61,9 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "check": "bun run spec:check && bun test && tsc -p tsconfig.json && bun run build && bun scripts/check-bin.ts",
+    "check": "bun run spec:check && bun run docs:check && bun test && tsc -p tsconfig.json && bun run build && bun scripts/check-bin.ts",
+    "docs:build": "bun scripts/docs/build.ts --write",
+    "docs:check": "bun scripts/docs/build.ts --check",
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "spec": "bun scripts/emit-spec.ts --write",

package/skills/udl/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: udl
+description: Read, validate, explain, or write Universal Domain Language documents directly. Use for canonical UDL JSON and format-level diagnostics. SDK and MCP consumers should use their generated contracts instead.
+---
+
+# UDL
+
+Use UDL when the task concerns the canonical product document, format conformance, or a validator implementation. Use HSX when authoring a product from reusable modules.
+
+## Read first
+
+1. Read `docs/guide/01-a-document.md` for the document frame.
+2. Read `docs/guide/03-laws.md` before changing lifecycle, money, gates, or references.
+3. Look up exact fields in `spec/udl.schema.json` and clauses in `docs/reference/clauses.md`.
+
+## Edit loop
+
+1. Change the smallest complete clause.
+2. Run `udl validate <file>`.
+3. Look up each `UDL####` code with `udl explain UDL####` or `docs/reference/diagnostics.md`.
+4. Apply the listed fix. Validate the whole document again.
+5. Run `udl canon <file> --digest` before pinning bytes or an identity.
+
+Never hand-author `effects`. Derive them from action clauses. Never represent money as a JSON number. Use an integer minor-unit string and its declared currency. Never add a money move without checking every terminal lifecycle path for a matching drain or unwind.
+
+For a stored definition, validate both documents before `udl diff <live> <next>`. Treat any `UDL7xxx` result as a refused change. A data migration does not make an incompatible document edit additive.
+
+Validator work must run the complete `conformance/` contract and follow `docs/reference/canonical.md` byte for byte.

package/spec/README.md

@@ -1,10 +1,15 @@
 # The UDL specification
 
 A UDL document describes one product in business terms: its subjects, its
-nouns, each noun's lifecycle, the verbs that move instances through it, and how
+instruments, each instrument's lifecycle, the actions that move instances through it, and how
 money moves while they do. Everything generated from a document (SDKs, docs,
 tool surfaces, the running engine) is downstream of what is written here.
 
+UDL is the platform's header files and driver framework. Its grammar is the
+complete instrument vocabulary and the ABI between authored programs and the
+engine. An instrument definition can round-trip through UDL without dropping a
+clause.
+
 ## The schema is the authority
 
 `udl.schema.json` in this directory is JSON Schema 2020-12, generated from the
@@ -17,7 +22,7 @@ no grammar tables and no field lists. Where anything below disagrees with
 `udl.schema.json`, the schema wins.
 
 The schema is generated from the _input_ view of the grammar, so it describes a
-document as an author writes it, before any default is filled in. A verb may
+document as an author writes it, before any default is filled in. A action may
 omit `moves`; a parser hands it back as `[]`.
 
 ## The ten laws
@@ -28,12 +33,13 @@ refuses.
 1. **One-sentence law.** Every concept in UDL is explainable in one sentence to
    someone who has never seen it. A concept that needs a paragraph is
    machinery, and machinery does not belong in the language.
-2. **Purity law.** No bank or provider legacy enters UDL: no statement formats,
-   no file drops, no polling, no batch windows, no cutoff times, no scheme
-   names, no reconciliation vocabulary, no ISO or SWIFT message types. A
-   document describes a product, never the plumbing under it.
-3. **Event law.** Every state change emits an event. Names derive from the noun
-   and the verb's past tense (`escrow_order.released`); the optional
+2. **Purity law.** No bank or provider legacy enters UDL: no provider statement
+   schemas, file drops, polling, batch windows, cutoff times, scheme names,
+   currency reconciliation rules, or ISO or SWIFT message types. A `reconcile`
+   clause names settlement evidence against a declared provider-side row. It
+   does not model the provider file, transport, or matching machinery.
+3. **Event law.** Every state change emits an event. Names derive from the instrument
+   and the action's past tense (`escrow_order.released`); the optional
    `eventName` overrides only where the honest past tense is irregular.
 4. **One-spine law.** Internal ledger money moves through four instructions and no others:
    `internal_transfer.create`, `.reserve`, `.post`, `.void`. Three account
@@ -42,23 +48,40 @@ refuses.
    a stored amount and beneficiary reference to the execution core. It is not
    a kernel instruction and cannot disguise an internal ledger move.
 5. **Uniform object law.** Every instance carries an opaque prefixed id (from
-   the noun's `idPrefix`), a `status` drawn from its declared lifecycle, a
+   the instrument's `idPrefix`), a `status` drawn from its declared lifecycle, a
    creation timestamp, and a caller-owned metadata bag. Amounts are
    string-encoded integer minor units paired with a currency code, never JSON
    numbers.
-6. **Requirements-as-data law.** Anything a caller must satisfy before a verb
+6. **Requirements-as-data law.** Anything a caller must satisfy before a action
    unlocks is declared data: `due`, `deadline`, `requiresRefs`,
-   `requiresAggregate`, `requiresDrainedAccount`, `requiresSettlement`. A
-   settlement gate reads a payout reference captured by an earlier payout
-   intent and records the durable matched evidence reference. No caller may
-   assert that match.
+   `requiresChecks`, `requiresExposure`, `requiresAggregate`, `remainder`,
+   `requiresDrainedAccount`, `commit`, `reconcile`. A reconcile declares one
+   expectation: the amount, the currency, `credit` or `debit`, the ref naming
+   the provider-side row, exactly one evidence source, a match law of `exact`,
+   `tolerance` bounded by a named dial, or `window`, and a window given as a
+   fixed duration or a stored deadline field. It ends matched or as a capped
+   exception child, never as a silent wait; the child is declared and validated
+   at admission rather than materialized, so past the window the transition
+   refuses naming it. Settlement evidence for a payout is one reconcile against
+   a debit statement line under any match law, reading the reference an earlier
+   payout intent captured. No caller may assert that match. An action that carries `quote` prices a base into a charge
+   and a net, names the fields the price depends on, and declares when the offer
+   dies, as a fixed duration or a stored deadline field. Exactly one other
+   action names it back through `commit`, and that action is the only one that
+   may move the net. A `commit` gate reads the offer the quoting action priced
+   and refuses once its deadline has passed or any frozen field has changed. It
+   spends what the quote wrote instead of pricing again, so the number a caller
+   is shown is the number they pay.
 7. **Append-only evolution law.** Once a definition has live instances, adding
-   states, transitions, optional fields, and verbs is legal; removing,
+   states, transitions, optional fields, and actions is legal; removing,
    renaming, tightening, or changing a money step is not.
    `diffValidatedUdlEvolution` decides, on two documents the validator has
-   already admitted; `udl diff` parses both files and then calls it.
-8. **Naming law.** Nouns are `snake_case`, singular, plain business English.
-   Verbs are single words in imperative present. Operations are `noun.verb`.
+   already admitted; `udl diff` parses both files and then calls it. Evolution
+   snapshots retain navigation, update examples, and parked-state reasons for
+   complete inspection. The diff treats their prose as editable presentation
+   and protects the parked state keys that carry lifecycle meaning.
+8. **Naming law.** Instruments are `snake_case`, singular, plain business English.
+   Actions are single words in imperative present. Operations are `instrument.action`.
    Fields are `camelCase`. The patterns live in the schema.
 9. **Time law.** Delays the world imposes (settlement windows, activation
    periods, renewal cycles, retries) surface as honest statuses and timestamps
@@ -68,6 +91,19 @@ refuses.
     every gate names a state that exists, and every funded balance is drained
     on every terminal path.
 
+## Admission budgets and derived effects
+
+The 10,000-node limit bounds authored program complexity. The compiler derives
+`effects` rows from action clauses, so the node counter excludes every action
+`effects` subtree. Admission still checks those subtrees for shape, exact
+agreement with the clauses including row order, nesting depth, string limits,
+JSON-only values, and cycles.
+
+The canonical 33-instrument catalog measured 10,270 nodes with derived effects
+and 9,321 authored nodes without the effect subtrees on 2026-09-02. The fixed
+10,000-node limit therefore leaves 679 authored nodes of headroom. The full
+effectful document validates as one document.
+
 ## What the schema cannot say
 
 JSON Schema pins shape. It does not pin meaning, and four classes of law live
@@ -91,38 +127,21 @@ suite is what makes two implementations agree.
 
 ## Issue codes
 
-A refusal reports one or more issues, each with a stable code and a JSON path.
-The codes are the cross-implementation contract; the messages are not.
-
-| Code                | Meaning                                                                                   |
-| ------------------- | ----------------------------------------------------------------------------------------- |
-| `invalid_utf8`      | The bytes are not valid UTF-8.                                                            |
-| `invalid_json`      | The bytes are UTF-8 but not JSON.                                                         |
-| `invalid_shape`     | The JSON does not match `udl.schema.json`, or fails a check the schema cannot express.    |
-| `invalid_semantics` | The shape is right and a whole-document law is broken.                                    |
-| `resource_limit`    | The document exceeds an admission budget (size, depth, node count, pattern search space). |
+A refusal reports one or more issues, each with a stable `UDL####` code, a
+category, a fix, and a JSON path. Codes and paths form the conformance
+contract. Messages may become clearer. The generated
+[diagnostic reference](../docs/reference/diagnostics.md) lists every code.
 
 Paths are `$`-rooted with dotted keys and bracketed array indices:
-`$.nouns[0].lifecycle.states[2]`.
+`$.instruments[0].lifecycle.states[2]`.
 
 ## Canonical form
 
-Every document has exactly one canonical byte sequence, produced by
-`serializeUdl`:
-
-- UTF-8, JSON, no byte-order mark.
-- Object keys sorted ascending by UTF-16 code unit. Sorting is recursive.
-- Two spaces of indentation per level of nesting.
-- One space after each `:`. Members separated by `,` then a newline.
-- An empty object is `{}` and an empty array is `[]`, both on one line.
-- Exactly one line feed at the end of the file, and no other trailing
-  whitespace.
-- Non-ASCII characters are written literally, not escaped.
-
-Two consequences worth stating outright. Serialization validates first, so an
-invalid document has no canonical form. And the round trip is byte-stable:
-canonicalizing canonical bytes returns them unchanged, which is what lets a
-document be diffed, signed, and stored as its own identity.
+Every admitted document has one canonical byte sequence. The normative
+[canonical bytes law](../docs/reference/canonical.md) defines key and array
+order, number and string encoding, empty containers, the trailing line feed,
+and the SHA-256 digest. Serialization validates first, so an invalid document
+has no canonical form.
 
 ## Two version numbers
 
@@ -133,9 +152,21 @@ that exists.
 **Package version** is the semver of `@hyperscale0/udl`, declared in
 `package.json`.
 
-They move independently, under one rule: **format 1 is unstable until the
-package reaches 1.0.0.** Until then an alpha release may change what format 1
-accepts, and the changes are listed in `../CHANGELOG.md`. Once the package
-ships 1.0.0, format 1 is frozen and an incompatible format change bumps the
-literal to `2`, with both formats readable for as long as the deprecation
-window says.
+They move independently, under one rule: **format 1 freezes when the package
+reaches 1.0.0.** The release candidate may still change what format 1 accepts,
+and every change appears in `../CHANGELOG.md`.
+
+After 1.0.0, an incompatible grammar change uses a new format literal. Readers
+keep an explicit decoder and validator for each supported old literal. A
+stored format 1 document remains readable under the format 1 rules. It does
+not acquire new required fields from the current package. Passing an old
+document to an evolution comparison can raise the matching `UDL7xxx` removal,
+tightening, lifecycle, or executable-change code, but a package upgrade alone
+does not rewrite its bytes. A product migration must validate and store its new
+document as a separate version before switching instances to it.
+
+The evolution codes are explicit. `UDL7001` protects stored identities,
+subjects, instruments, fields, lifecycles, actions, money clauses, gates, and
+policy. `UDL7002` requires a version increase for a semantic change.
+Evolution comparison admits the previous document first. A stored document
+that fails admission is `invalid_previous`, not an evolution issue.