@hyperscale0/udl 1.0.0-alpha.1

package/LICENSING.md

@@ -0,0 +1,51 @@
+# Licensing
+
+The code in this repository is Copyright 2026 Hyperscale LLC and is licensed
+under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full text is in [`LICENSE`](./LICENSE).
+
+## What the AGPL asks of you
+
+Two obligations matter in practice.
+
+**If you distribute a copy in object form**, modified or not, you make its
+Corresponding Source available under the same license.
+
+**If you run a modified copy as a network service**, section 13 applies: the
+users interacting with it over the network get an offer of the source of the
+version you are running. Running UDL unmodified behind your own service does
+not trigger this. Changing the parser, the validator, or the canonical
+serializer and then serving that change does.
+
+Using `@hyperscale0/udl` as a library inside your own program is a combined
+work under the AGPL. If that does not fit how you ship, take the commercial
+license instead.
+
+## Commercial license
+
+Hyperscale LLC sells a commercial license to organisations that cannot accept
+the AGPL, for the usual reasons: a proprietary product that links the library,
+a hosted service you will not open, a procurement policy that refuses copyleft.
+It grants the same code under ordinary commercial terms with no source
+obligation.
+
+Ask through <https://hyperscale0.ai>.
+
+## The license covers code, not marks
+
+"Hyperscale" and "UDL" are trademarks of Hyperscale LLC. A copyright license
+says nothing about trademarks in either direction, so
+[`TRADEMARKS.md`](./TRADEMARKS.md) draws that boundary.
+
+## The format is not the implementation
+
+UDL the format is separate from this implementation of it. The JSON Schema in
+[`spec/`](./spec) and the conformance cases in [`conformance/`](./conformance)
+are data describing a format, and anyone may write their own parser, validator,
+or serializer against them, in any language, under any license, without
+touching this code.
+
+What you may then say about it is a trademark question, not a copyright one.
+[`TRADEMARKS.md`](./TRADEMARKS.md) has the rule: claim compatibility with a UDL
+version only when your implementation passes that version's published
+conformance cases unmodified.

package/README.md

@@ -0,0 +1,163 @@
+# UDL
+
+UDL is the Universal Domain Language: a JSON document format for describing
+a financial product in business terms. One `.udl` file declares the product's
+subjects, its nouns, each noun's lifecycle, the verbs that move instances
+through that lifecycle, and how money moves while they do. Everything else,
+SDKs, docs, tool surfaces, the running engine, is generated from it or checked
+against it.
+
+The language deliberately cannot say certain things. There is no statement
+format, no file drop, no polling loop, no cutoff time, no scheme name, no
+reconciliation vocabulary. Those are real and they are somebody's problem, but
+they are not the product, so they are absorbed below the language and never
+surface in a document. What is left is small enough to hold in your head.
+
+This package is the reference implementation: parser, semantic validator,
+canonical serializer, evolution diff, and the `udl` command. The format itself
+is specified in [`spec/`](./spec/README.md) and pinned by
+[`conformance/`](./conformance/README.md).
+
+## Install
+
+```bash
+npm install @hyperscale0/udl@alpha
+```
+
+There is no `latest` tag before 1.0.0, so a bare `npm install @hyperscale0/udl`
+fails loudly rather than installing something you did not choose.
+
+## Thirty seconds
+
+`note.udl`, the smallest document the format accepts:
+
+```json
+{
+  "nouns": [
+    {
+      "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",
+      "verbs": {
+        "close": { "moves": [], "steps": [], "summary": "Close the note." },
+        "create": { "moves": [], "steps": [], "summary": "File the note." }
+      }
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "Minimal",
+  "udl": 1,
+  "version": 1
+}
+```
+
+```ts
+import { readFile, writeFile } from "node:fs/promises";
+import {
+  diffUdlEvolution,
+  parseUdl,
+  serializeUdl,
+  validateUdl,
+} from "@hyperscale0/udl";
+
+const document = parseUdl(await readFile("note.udl"));
+
+// One document, one byte sequence. Sorted keys, two-space indent, final LF.
+await writeFile("note.udl", serializeUdl(document));
+
+// Issues carry a stable code and a JSON path, never just a sentence.
+const result = validateUdl(document);
+if (!result.ok) console.error(result.issues);
+
+// Is this change legal against the version that already has live instances?
+const live = parseUdl(await readFile("note.live.udl"));
+const violations = diffUdlEvolution(live, document);
+```
+
+`parseUdl` takes a string or a `Uint8Array`; bytes are decoded as strict UTF-8.
+`serializeUdl` validates before it writes, so an invalid document has no
+canonical form.
+
+## The command
+
+```bash
+udl validate product.udl        # parse and report every issue found
+udl fmt product.udl             # print the canonical form
+udl fmt product.udl --write     # rewrite the file in place
+udl diff live.udl product.udl   # is the change additive, or does it break?
+```
+
+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. That split matters in CI: a broken
+document and a broken invocation are different failures.
+
+## The two things worth knowing
+
+**Evolution is append-only.** Once a definition has live instances, you may add
+states, transitions, optional fields, and verbs. You may not remove, rename,
+tighten, or change a money step. `udl diff` is not advice; it is the same
+function the compiler runs before it will accept a new version.
+
+**Money moves through four instructions and no others.**
+`internal_transfer.create`, `.reserve`, `.post`, `.void`. Three account
+instructions complete the sealed set. A noun cannot invent a fifth money path,
+which is why a document can be checked for stranded value before anything runs.
+
+## The spec
+
+- [`spec/README.md`](./spec/README.md) is the specification: the ten laws, the
+  canonical form, the issue codes, and what the schema deliberately cannot say.
+- [`spec/udl.schema.json`](./spec/udl.schema.json) is JSON Schema 2020-12,
+  generated from the grammar. Where prose and schema disagree, the schema wins.
+- [`conformance/`](./conformance/README.md) is the semantic spec: `.udl` inputs
+  with expected verdicts, canonical bytes, and issue codes, runnable from any
+  language.
+
+## Versioning
+
+Two numbers move independently.
+
+**Format version** is the literal `"udl": 1` inside a document. Format 1 is the
+only format that exists.
+
+**Package version** is this package's semver, currently `1.0.0-alpha.1`,
+published only under the `alpha` dist-tag.
+
+Format 1 is unstable until the package reaches 1.0.0. Until then an alpha
+release may change what format 1 accepts, and every such change is listed in
+[`CHANGELOG.md`](./CHANGELOG.md). After 1.0.0, format 1 is frozen and an
+incompatible change bumps the literal to `2`.
+
+## Status
+
+Alpha. The format is in use, the API surface is settled enough to build on, and
+the version number is honest about the rest. Breaking changes go in the
+changelog, not in a footnote.
+
+## Contributing
+
+Issues only. Hyperscale makes the changes to the format and the package; you
+propose them in an issue carrying the use case and the conformance case it
+would add. [`CONTRIBUTING.md`](./CONTRIBUTING.md) has that model in full, plus
+the dev setup, the test commands, and how to regenerate the spec. Conduct:
+[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). Vulnerabilities:
+[`SECURITY.md`](./SECURITY.md).
+
+## License
+
+AGPL-3.0-only, with a commercial license available from Hyperscale LLC for
+organisations that cannot accept the AGPL. See [`LICENSE`](./LICENSE) for the
+text and [`LICENSING.md`](./LICENSING.md) for which one you want and how to ask
+for the commercial one. The marks are not covered by either; see
+[`TRADEMARKS.md`](./TRADEMARKS.md), which also carries the rule for claiming
+UDL compatibility.

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security
+
+## Reporting a vulnerability
+
+Report privately through GitHub, using this repository's
+[private vulnerability reporting form](https://github.com/hyperscale0/hyperscale-udl/security/advisories/new).
+That is the only intake. There is no security email address, and nothing
+security-sensitive belongs in an issue, a pull request, a discussion, or a
+commit message.
+
+A report we can act on names the affected version, describes the surface, and
+gives us something to run: a `.udl` file, an input, a snippet. If you can shape
+it as a conformance case, do that; it goes straight into the fix.
+
+## What counts
+
+This package parses untrusted documents, so the interesting failures are the
+ones a document can cause:
+
+- A document that gets past `validateUdl` but should not, especially one that
+  breaks a money-graph law.
+- A document that makes the parser or validator burn unbounded time or memory.
+  Admission budgets (source bytes, nesting depth, node count, string length,
+  regex search space) exist precisely to make this impossible; a way around one
+  is a vulnerability.
+- A document that makes `serializeUdl` produce bytes that reparse into a
+  different document.
+- An evolution diff that reports a breaking change as additive.
+
+Out of scope: the `udl` command reading a file you told it to read, and
+anything that requires already controlling the machine running it.
+
+## Supported versions
+
+Alpha releases are supported at the newest published `alpha` version only.
+Fixes land there; there is no backport branch before 1.0.0.
+
+## Disclosure
+
+We will confirm receipt, tell you what we found, and agree a disclosure date
+with you before publishing an advisory. If a fix is not straightforward we will
+say so rather than go quiet.

package/TRADEMARKS.md

@@ -0,0 +1,35 @@
+# Trademarks
+
+"Hyperscale" and "UDL" are trademarks of Hyperscale LLC.
+
+The AGPL covers the code in this repository and nothing else. It grants no
+rights to the marks, and it never mentions them: a copyright license says
+nothing about trademarks either way. This file draws that boundary so nobody
+has to guess where it sits.
+
+What that means in practice:
+
+- **Yes.** Say your project uses UDL, reads UDL, or is compatible with UDL.
+  Say it in your README, your docs, your talk, and your package description.
+  Fork this repository and keep the notices intact.
+- **Yes.** Publish a UDL implementation in another language, and name it in a
+  way that describes what it does: `udl-rs`, `udl-parser`, `python-udl`.
+- **No.** Name your project, company, or product in a way that suggests
+  Hyperscale LLC published it or endorses it. `@hyperscale0/*` on npm and the
+  `hyperscale0` GitHub organisation are ours.
+- **No.** Use the marks or our logo in a way that implies affiliation,
+  sponsorship, or certification we have not given.
+
+## Claiming compatibility
+
+An independent implementation may say it "implements UDL version X" or "passes
+the UDL conformance suite version X" only while it passes the published
+conformance cases for that version, unmodified. The cases in
+[`conformance/`](./conformance) are the whole test: no skipped case, no edited
+expectation, no local fork of the fixtures.
+
+That claim is a statement about your implementation, so keep the marks out of
+its name and off its logo, and do not present it as endorsement or
+certification by Hyperscale LLC. We certify nothing; the suite does.
+
+If you are unsure, open an issue and ask. Nobody has ever regretted asking.

package/conformance/README.md

@@ -0,0 +1,79 @@
+# The UDL conformance suite
+
+Every file here is data. Nothing in this directory imports the reference
+implementation, so a UDL implementation in any language can run the suite by
+reading files and comparing bytes.
+
+`../test/conformance.spec.ts` is the reference runner. Read it if a rule below
+is ambiguous.
+
+## Layout
+
+```
+conformance/
+  valid/    documents the format accepts, each with its canonical form
+  invalid/  documents the format refuses, each with the issues it must report
+```
+
+Every `<case>.udl` has a sibling `<case>.expected.json`. A file without its
+sibling is a case that silently stopped running, so the runner fails on
+orphans in either direction.
+
+## Expected files
+
+A valid case:
+
+```json
+{
+  "canonical": "minimal.udl",
+  "summary": "Compact, reverse-ordered bytes canonicalize to minimal.udl.",
+  "verdict": "valid"
+}
+```
+
+`canonical` names the file in `valid/` holding the canonical bytes for this
+input. A document that is already canonical names itself.
+
+An invalid case:
+
+```json
+{
+  "issues": [{ "code": "invalid_semantics", "path": "$.nouns[0].verbs" }],
+  "summary": "Every noun declares create: nothing else can bring an instance into being.",
+  "verdict": "invalid"
+}
+```
+
+`summary` is for humans reading a failure. Nothing asserts against it beyond
+requiring it to be present and non-blank.
+
+## The three levels
+
+An implementation claims conformance at the highest level it passes.
+
+**Level 1, verdict.** Read the file as bytes. Every `valid/` case is admitted
+and every `invalid/` case is refused. This is the whole contract for a
+validator.
+
+**Level 2, canonical bytes.** For each `valid/` case, serialize the parsed
+document and compare it byte for byte against the file named by `canonical`.
+Any implementation that writes UDL must pass this, or two tools will disagree
+about what the same document is.
+
+**Level 3, issues.** For each `invalid/` case, every listed `code` and `path`
+pair appears among the reported issues. Extra issues are allowed, because
+implementations legitimately differ on how many problems they report before
+giving up. Messages are never compared; they are prose and they are free to
+change.
+
+## Adding a case
+
+Write the `.udl` and its `.expected.json`, then run `bun test`. Keep new cases
+small and single-purpose: the point of `invalid/blank-title.udl` is that it
+differs from `valid/minimal.udl` in exactly one key. `valid/minimal.udl` is the
+smallest document both the grammar and the semantic laws accept, and it is the
+right base to mutate.
+
+The five domain documents in `valid/` are the real thing, projected from a
+shipped product catalog. They are large on purpose: they are what catches a
+regression the minimal case cannot see.

package/conformance/invalid/blank-title.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_shape",
+      "path": "$.title"
+    }
+  ],
+  "summary": "Whitespace is not a title. JSON Schema cannot express this check, so it lives here.",
+  "verdict": "invalid"
+}

package/conformance/invalid/blank-title.udl

@@ -0,0 +1,50 @@
+{
+  "nouns": [
+    {
+      "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",
+      "verbs": {
+        "close": {
+          "moves": [],
+          "steps": [],
+          "summary": "Close the note."
+        },
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        }
+      }
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "   ",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/depth-budget.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "resource_limit",
+      "path": "$.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested.nested"
+    }
+  ],
+  "summary": "Admission budgets are part of the format: nesting past 24 levels is refused before validation.",
+  "verdict": "invalid"
+}

package/conformance/invalid/depth-budget.udl

@@ -0,0 +1,49 @@
+{
+  "nested": {
+    "nested": {
+      "nested": {
+        "nested": {
+          "nested": {
+            "nested": {
+              "nested": {
+                "nested": {
+                  "nested": {
+                    "nested": {
+                      "nested": {
+                        "nested": {
+                          "nested": {
+                            "nested": {
+                              "nested": {
+                                "nested": {
+                                  "nested": {
+                                    "nested": {
+                                      "nested": {
+                                        "nested": {
+                                          "nested": {
+                                            "nested": {
+                                              "nested": {
+                                                "nested": {}
+                                              }
+                                            }
+                                          }
+                                        }
+                                      }
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/conformance/invalid/format-version.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_shape",
+      "path": "$.udl"
+    }
+  ],
+  "summary": "A document declares its format version literally; format 2 does not exist yet.",
+  "verdict": "invalid"
+}

package/conformance/invalid/format-version.udl

@@ -0,0 +1,50 @@
+{
+  "nouns": [
+    {
+      "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",
+      "verbs": {
+        "close": {
+          "moves": [],
+          "steps": [],
+          "summary": "Close the note."
+        },
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        }
+      }
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "Minimal",
+  "udl": 2,
+  "version": 1
+}

package/conformance/invalid/invalid-utf8.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_utf8",
+      "path": "$"
+    }
+  ],
+  "summary": "A UDL file is strict UTF-8; a lone continuation byte is refused before JSON parsing.",
+  "verdict": "invalid"
+}

package/conformance/invalid/invalid-utf8.udl

@@ -0,0 +1 @@
+{"udl": 1, "title": "�"}

package/conformance/invalid/malformed-json.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_json",
+      "path": "$"
+    }
+  ],
+  "summary": "Bytes that are not JSON at all report a parse failure, not a grammar failure.",
+  "verdict": "invalid"
+}

package/conformance/invalid/malformed-json.udl

@@ -0,0 +1 @@
+{"udl": 1,

package/conformance/invalid/missing-create-verb.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_semantics",
+      "path": "$.nouns[0].verbs"
+    }
+  ],
+  "summary": "Every noun declares create: nothing else can bring an instance into being.",
+  "verdict": "invalid"
+}

package/conformance/invalid/missing-create-verb.udl

@@ -0,0 +1,45 @@
+{
+  "nouns": [
+    {
+      "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",
+      "verbs": {
+        "close": {
+          "moves": [],
+          "steps": [],
+          "summary": "Close the note."
+        }
+      }
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "Minimal",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/not-an-object.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_shape",
+      "path": "$"
+    }
+  ],
+  "summary": "Valid JSON that is not a UDL document.",
+  "verdict": "invalid"
+}

package/conformance/invalid/not-an-object.udl

@@ -0,0 +1 @@
+"a string"

package/conformance/invalid/noun-id-not-snake-case.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "invalid_shape",
+      "path": "$.nouns[0].id"
+    }
+  ],
+  "summary": "Naming law: noun ids are snake_case, singular, plain business English.",
+  "verdict": "invalid"
+}