@hyperscale0/udl 4.5.0 → 4.5.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# UDL 4.5.1
+
+Documentation only. The specification README explains how to read the
+contract before the rules, and the generated `docs/README.md` and
+`llms-full.txt` follow it. No validator behaviour changed.
+
 # UDL 4.5.0
 
 Admission walks own data properties only, refuses properties JSON

package/README.md

@@ -1,5 +1,27 @@
 # UDL 4
 
-Read the [language reference](docs/README.md).
+UDL, the Universal Domain Language, describes a company's objects, agreements,
+actions and money rules. HSX compiles to this typed contract. An executor reads
+UDL and enforces its actors, lifecycle transitions, requirements and effects.
+The UDL package parses, validates and serializes contracts; it executes no actions.
+This version supports SAR only.
 
-Run `bun run build` to build this package and `bun run check` to check it.
+Read the [specification](spec/README.md) for the contract and its runtime obligations.
+The [JSON schema](spec/udl.schema.json) defines every field and default.
+
+Install `@hyperscale0/udl` to use the `udl` executable with Node.js 22 or later.
+Given `rental.udl.json` from `hsx build rental.hsx --out rental.udl.json`:
+
+```sh
+npx udl validate rental.udl.json
+npx udl canon rental.udl.json --digest
+```
+
+Validation checks the contract, not an account balance or a deployed executor.
+The digest identifies canonical bytes. `udl explain UDL####` explains a diagnostic
+code printed by validation; replace `UDL####` with the reported code.
+
+From the public source checkout, run `bun install`, then `bun run build`.
+`bun run check` checks schema freshness, types and package tests. Edit prose in
+`spec/README.md`; `bun run docs:build` copies it to `docs/README.md` and
+`llms-full.txt` and writes the `llms.txt` index. Those copies are generated.

package/docs/README.md

@@ -1,9 +1,29 @@
 # UDL 4
 
-UDL is the typed contract between an HSX program and its executor. The grammar
+UDL is the Universal Domain Language, the typed contract between an HSX program
+and its executor. The grammar
 lives in `src/schema.ts`. Generate `udl.schema.json` with
 `bun scripts/emit-spec.ts --write`. There is no migration reader for earlier UDL.
 
+## Reading a compiled program
+
+Start with `product`, `title` and `currency`. `objects` describes business records
+and their attachments. Follow an attachment's instrument identity into
+`instruments` for its retained fields, lifecycle and actions. `actionOrder`
+preserves authored action order even though canonical JSON sorts object keys.
+An action's `publicAction` supplies its exposed name; its actor and requirements
+still control who may execute it and when.
+
+Object metadata describes the subject. Instrument fields retain the agreement's
+terms, account bindings and receipts. Party names identify authenticated or
+configured participants. None of these makes a caller-supplied account ID valid.
+A Build freezes this contract and its bindings for the executor.
+
+Business instructions are actions composed from typed requirements and effects.
+The four `internal_transfer` instructions are their money effects. The contract
+expresses valid conditions; execution can still refuse for the current state,
+authority, evidence or balance. Parsing and validation execute nothing.
+
 ## JSON admission and canonical bytes
 
 The parser refuses duplicate JSON member names, including escaped spellings of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
   "keywords": [
     "udl",
@@ -78,5 +78,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "4141f2296d9427b30d04933c735be4af1ba88dec"
+  "gitHead": "7940250e962dc6469ea6b29c4034a92cb2338b28"
 }

package/spec/README.md

@@ -1,9 +1,29 @@
 # UDL 4
 
-UDL is the typed contract between an HSX program and its executor. The grammar
+UDL is the Universal Domain Language, the typed contract between an HSX program
+and its executor. The grammar
 lives in `src/schema.ts`. Generate `udl.schema.json` with
 `bun scripts/emit-spec.ts --write`. There is no migration reader for earlier UDL.
 
+## Reading a compiled program
+
+Start with `product`, `title` and `currency`. `objects` describes business records
+and their attachments. Follow an attachment's instrument identity into
+`instruments` for its retained fields, lifecycle and actions. `actionOrder`
+preserves authored action order even though canonical JSON sorts object keys.
+An action's `publicAction` supplies its exposed name; its actor and requirements
+still control who may execute it and when.
+
+Object metadata describes the subject. Instrument fields retain the agreement's
+terms, account bindings and receipts. Party names identify authenticated or
+configured participants. None of these makes a caller-supplied account ID valid.
+A Build freezes this contract and its bindings for the executor.
+
+Business instructions are actions composed from typed requirements and effects.
+The four `internal_transfer` instructions are their money effects. The contract
+expresses valid conditions; execution can still refuse for the current state,
+authority, evidence or balance. Parsing and validation execute nothing.
+
 ## JSON admission and canonical bytes
 
 The parser refuses duplicate JSON member names, including escaped spellings of