@hyperscale0/udl 1.0.0 → 1.0.123

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "1.0.0",
-  "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
+  "version": "1.0.123",
+  "description": "The Universal Domain Language: format spec and validator.",
   "keywords": [
     "udl",
     "schema",
@@ -19,37 +19,30 @@
     "type": "git",
     "url": "git+https://github.com/hyperscale0/hyperscale-udl.git"
   },
-  "license": "AGPL-3.0-only",
+  "license": "SEE LICENSE IN LICENSE.md",
   "author": "Hyperscale LLC",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "udl": "./dist/cli.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./spec/*": "./spec/*",
-    "./conformance/*": "./conformance/*",
     "./package.json": "./package.json"
   },
   "files": [
+    "LICENSE.md",
+    "NOTICE.md",
     "AUTHORS",
     "CHANGELOG.md",
-    "LICENSE",
-    "LICENSING.md",
     "README.md",
     "SECURITY.md",
-    "TRADEMARKS.md",
-    "conformance",
     "docs",
     "dist",
-    "skills",
     "spec",
     "src"
   ],
@@ -61,27 +54,25 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "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",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun test test",
     "postpack": "bun scripts/pack-exports.ts restore",
     "prepack": "bun run build && bun scripts/pack-exports.ts apply",
     "spec": "bun scripts/emit-spec.ts --write",
     "spec:check": "bun scripts/emit-spec.ts --check",
-    "test": "bun test",
-    "typecheck": "tsc -p tsconfig.json"
+    "check": "bun run spec:check && bun run typecheck && bun test test"
   },
   "dependencies": {
-    "@cfworker/json-schema": "4.1.1",
-    "zod": "4.4.3"
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@types/bun": "1.4.0",
-    "typescript": "6.0.3"
+    "bun-types": "1.4.2",
+    "typescript": "7.0.2"
   },
   "contributors": [
     "Meshael AlBakaawi",
     "Amir Ayub",
     "Sara AlBakaawi"
-  ]
+  ],
+  "gitHead": "3af04bb95dfbacee4caae46f0eaf2b88296a18a7"
 }

package/spec/README.md

@@ -1,172 +1,300 @@
-# The UDL specification
-
-A UDL document describes one product in business terms: its subjects, its
-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
-Zod grammar in `src/schema.ts` by `scripts/emit-spec.ts`. It is checked in so
-that an implementation in any language can read it, and `bun run spec:check`
-fails the build when the committed bytes stop matching the generator.
-
-Prose copies of a machine-checked format drift. This document therefore carries
-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 action may
-omit `moves`; a parser hands it back as `[]`.
-
-## The ten laws
-
-These are judgment, not shape. They explain why the schema refuses what it
-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 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
-   instructions (`account.escrow.provision`, `account.freeze`,
-   `account.unfreeze`) complete the sealed kernel set. A `payout` intent hands
-   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 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 action
-   unlocks is declared data: `due`, `deadline`, `requiresRefs`,
-   `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 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. 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
-   on objects, never as processes the caller has to operate.
-10. **Closure law.** A document is self-contained. Every lifecycle state is
-    reachable from `create`, every reference resolves inside the document,
-    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
-outside it:
-
-- **Blankness.** The schema says `"type": "string"` where the grammar says a
-  string whose trimmed length is non-zero. A title of `"   "` passes the schema
-  and is refused by the parser.
-- **Closure and reference resolution.** Reachability, gate targets, party
-  bindings, aggregate links, and authored-example validation are whole-document
-  properties.
-- **Money-graph admission.** Whether a debit can be reached before its funding,
-  and whether any terminal path strands value, is decided by walking the
-  lifecycle.
-- **Evolution.** The legality of a change is a property of two documents, not
-  one.
-
-All four are pinned as data in `../conformance/`. An implementation that reads
-only `udl.schema.json` will admit documents this one refuses; the conformance
-suite is what makes two implementations agree.
-
-## Issue codes
-
-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:
-`$.instruments[0].lifecycle.states[2]`.
-
-## Canonical form
-
-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
-
-**Format version** is what a document declares, as the literal `"udl": 1`. A
-document that declares any other value is refused. Format 1 is the only format
-that exists.
-
-**Package version** is the semver of `@hyperscale0/udl`, declared in
-`package.json`.
-
-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.
+# UDL 1
+
+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`.
+
+## 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
+one name. Decoded documents must contain finite JSON data. Accessors, cycles,
+sparse arrays, symbol keys, hidden properties and `__proto__` members refuse
+before schema parsing. Shared values count once per occurrence toward the budget.
+Admission permits at most 100,000 visited values, 32 nesting levels, 240 code units
+per key and 1 MiB of UTF-8 key and string data. Source text has a separate 1 MiB
+byte limit. These bounds live in `src/limits.ts`.
+
+Canonical JSON sorts object keys recursively, preserves array order and ends
+with a newline. Schema defaults are part of the admitted document. Equivalent
+key insertion orders and explicit defaults have the same digest. Object field
+compatibility and evolution comparisons use the same key ordering.
+
+## Objects and subjects
+
+An object kind declares identity, title, authored field names, normalized fields
+and display columns. Each attachment freezes its instrument identity and party
+parameter bindings to `owner`, `actor`, `operator`, or a declared Product party. Core resolves role bindings from the object row, session and Product, and
+declared parties from the Product party binding. `authoredFields` records only names declared in the HSX
+object block. `fields` is their union with attached action requirements. Matching
+names must have matching types and constraints. Account fields belong to
+instruments, never objects.
+
+An instrument may name its object kind with `subject`. An action's `subject`
+contains its requirements and any frozen adapter binding. Each requirement keeps
+its source field and optional `objectField` rename. Adapter snapshots contain
+provider, capability, operation, declaration digest and requirements. A null snapshot
+marks an unbound adapter. It permits discovery but blocks that action. No provider
+requirement is inferred from an operation name.
+
+Object creation accepts `{}`. Its optional `fields` property accepts every
+normalized field as optional. Requirements become mandatory only when the
+attached action runs. Object creation performs no financial action. Instrument
+creation remains internal; an attached create action may expose a public name.
+Attachment parties resolve from authenticated authority, never from party account
+IDs supplied in a caller body.
+
+`object-contract.ts` projects `ObjectDiscovery` for
+`GET /v1/products/{productId}/objects`. It exports the discovery, instance, list
+and action response types. Discovery preserves Build identity, authored field
+names, the full optional create schema and each exposed action's requirements.
+Object instances carry `objectId`, `kind`, `revision`, optional `externalId`,
+`fields` and `productBuildId`. Action responses carry the object and either a
+financial instrument outcome or null.
+
+An object may declare `entryActions`, a list of exposed attachment creation
+names. The host admits an active enrolled customer only to an entry action whose
+actor is the session's `actor` role. Other records remain closed. Retained
+participants can read their record and use the actions granted to their roles;
+participation never changes the owner.
+
+An instrument may declare `scope: "product"`. Object creation can resolve a
+reference to that instrument on another record in the same Product when every
+retained party account matches the current bindings. Otherwise references stay
+on the current record. Create and approve shared limits once per Product or
+borrower; referencing them does not create a new limit.
+
+## Object operations
+
+The host owns transport routes for object discovery, creation, listing,
+retrieval, action availability, execution and agreement evidence.
+`src/object-contract.ts` defines the language package's object projections.
+
+Execution binds `productBuildId`, `digest`, `target` and `expectedRevision`.
+The target identifies an attachment or an existing instance on that attachment.
+The optional `fields` collect subject metadata; optional `input` carries the action's typed input.
+Missing requirements refuse execution. Callers reuse an idempotency key only for
+retries of the same request. Staff Create for may name `ownerPrincipalId` through
+its authorized path; ordinary ownership comes from the session.
+
+## Accounts and money
+
+A document declares SAR once. Money is a nonnegative minor-unit decimal string
+of at most 18 digits. Percentages are basis points, durations are positive integer
+milliseconds, and dates are timestamps with explicit offsets.
+
+An account field binds a party, the instrument itself, or an adapter. Party owners
+are names; `owner: "self"` provisions an account per instance. An adapter owner
+is `{ "adapter": "insurer" }`, where `insurer` names an adapter declared in one
+of the instrument's action subjects. The agreement retains that declaration's
+provider identity. Missing or conflicting bindings refuse with
+`subject_adapter_unbound`; changing an existing account binding refuses with
+`account_binding_changed`. A null declaration can describe a draft but cannot
+create an adapter-owned account.
+
+Account creation and binding are executor work. Callers never supply account IDs.
+Accounts declare `book: "cash" | "claim"`, defaulting to cash. Moves never cross books.
+Only claim accounts may declare `contra: true` and permit a negative balance.
+Party and adapter accounts share owner, book and key within a Product; the key
+defaults to `balance`. Adapter aliases for the same provider share that account. Transfers between
+known aliases of one account refuse, including self fields with the same key.
+The executor scopes provider accounts to the tenant and Product, with the Product
+participant as ledger custodian. Providers are not parties. An account owned by
+self defaults its key to the field name. Named capital, premium, income, debt and
+loss balances use explicit keys. `party.buyer` is the buyer's default cash account.
+
+A plain move to an adapter account credits its ledger balance. It does not prove
+an external payout. Provider confirmation still uses a boundary reservation and
+instruction-bound evidence. Account ownership adds no settlement operation.
+
+Disbursement moves cash from lender to borrower and claims from borrower debt to
+principal and profit receivables. Repayment moves borrower cash to lender cash and
+the same claim amounts from receivables back to borrower debt. Unearned profit is
+cancelled by the claim move alone. Write-off moves the principal claim to the
+lender's loss account, with no cash movement. The library declares when profit
+is earned: on payment, by schedule or at disbursement.
+These are ordinary paired moves in HSX, not executor loan rules.
+
+A value is `{literal: value}` or `{field: path}`. Paths start with `self`, `input`, `subject`
+or `party`. Reference fields allow typed traversal. Account paths expose locked,
+read-only `.balance` and `.reserved` money values. `self.id`, `self.status`,
+`self.createdAt` and `self.now` are sealed executor values. Callers cannot set
+constants, calculated fields, account bindings or capture fields. Create supplies
+declared typed references; later actions cannot replace them. A ref declares `targetKind: "object" | "instrument"` and one target id or
+a list of 1 to 16 distinct target ids in that namespace. Its stored value is an
+identity from one listed target. Path traversal exposes only fields
+with compatible types on every target. Nested refs combine their target sets;
+accounts must agree on owner, key, book and contra flags, and enums must
+have the same values. A comparison or selection anchor must share a possible
+reference target. An invoked input must accept every possible supplied target.
+The executor checks the actual instance type at admission.
+
+## Calculation and movement
+
+Calculations form a finite dependency graph. `sum`, `subtract` and `minimum`
+operate on money or integer fields, with operands of the same type as the target.
+`rate`, `multiply`, `divide` and `shift` retain their typed operands. A shift's
+`milliseconds` operand is a duration field or a non-negative safe integer literal.
+Zero leaves the date unchanged; duration fields still require positive values. Rate and
+division round down. Weighted shares also round down; residual minor units go
+to the declared residual account. Cash and loss use this one rounding rule.
+There is no largest-remainder allocation. Subtraction refuses a negative result. Integer results must
+be safe integers. No calculation evaluates source text.
+
+The only move instructions are `internal_transfer.create`,
+`internal_transfer.reserve`, `internal_transfer.post` and `internal_transfer.void`.
+Create and reserve declare an amount, from account and to account. Reserve captures
+its executor-produced transfer identity into a declared self text field. Post and
+void consume that identity. Callers cannot create or replace captured identities.
+Adapter-owned endpoints use the same move vocabulary.
+
+Each move may declare `economics: { purpose, sourceParty, reversalOf? }`.
+HSX attachment economics lower into this same move block on the attachment's
+instrument. There is no separate override at runtime. The attachment's party
+bindings include its economic source. Validation refuses an unbound money
+party, a cash purpose on non-cash accounts, a void with authored economics,
+and posting economics that conflict with the reservation. Non-cash accounting
+can retain the `internal` purpose.
+Purpose is `earning`, `principal`, `participant_payout`, `internal`,
+`prepaid_credit`, or `pass_through`. Pass-through money is excluded from earnings
+and costs. `sourceParty` names an authored party whose retained
+participant must own the debit account. For an earning realized from company-held
+customer money, it identifies the retained payer instead. The debit must be an
+instrument account bound to the same agreement or a retained referenced agreement
+in the same Build with the same payer; the company credit must be outside the
+agreement. Evidence also retains the actual debit account participant.
+`reversalOf` is a transfer reference path. A reversal preserves purpose, Product, Build and agreement, debits the
+original recipient account and credits the original source participant. The
+combined refunds cannot exceed the original posted amount. A post inherits its
+reservation's economics; it cannot change them.
+The terminal ledger evidence keeps these fields with the agreement, Build,
+account participants, and move key. A move without economics has no inferred
+classification.
+
+A loan, refund, payoff, write-off or distribution is library behavior built from
+accounts, calculations and ordered moves. None has a privileged executor clause.
+Outstanding principal is an account balance. A schedule consists of explicit
+dated child records, with positions 1 through n in declaration order. The library
+uses ordinary comparisons and aggregates to constrain those records. There is no
+recurrence process, allocation bucket, partition expander or schedule requirement
+in the UDL kernel.
+
+## Admission and lifecycle
+
+Actions declare typed input lists, requirements, an actor and an event. Lifecycle
+edges name their source and destination states. Requirements and effects execute
+atomically under the same account and reference locks. `set` copies typed values
+to mutable fields. Action calculations read the locked snapshot and populate the
+action draft before requirements. Ordered moves and invocations follow admission;
+a zero create move refuses unless the action declares `allowZero: true`.
+With that permission it records no transfer or capture. A reserve amount must
+always be positive.
+Invariants check the completed transaction. A due instant
+is inclusive; a deadline is exclusive. Clock delays never extend deadlines.
+
+Requirements are compare, state, unique, aggregate, evidence and hours.
+A typed selection names one instrument or a bounded union, a reference field,
+anchor, accepted states and row limit. Exceeding the limit refuses rather than
+truncates. Optional equality filters apply to every selected type. An optional
+window selects date values between `self.now - milliseconds` and `self.now`.
+Aggregate sums use typed paths on the selected records, including account
+balances. An invariant holds before and after every affected transaction.
+
+`hours` converts a date path to its literal IANA timezone and accepts `[start,end)`.
+A start greater than end wraps midnight; equal endpoints admit no time.
+`evidence` declares subject, family, check, result and maxAge. The subject is an
+account or text id. The executor selects the newest matching subject binding,
+checks its retained Build, protected input digest and adapter declaration, then
+requires the declared result and age. A newer matching refusal or pending result
+prevents reuse of an older success.
+
+`invoke` supplies typed inputs to a linked action or bounded selection. Its graph
+is acyclic and bounded. Public names grant no authority; clock and parent actors
+remain executor-owned. A public action on a subject instrument requires an
+attachment on that object kind. State requirements refer to instrument instances;
+objects have no instrument lifecycle. List extraction preserves the reference
+namespace and target. Selection anchors and filters participate in calculation
+cycle detection. Literal assignments must satisfy the destination field's constraints.
+
+A captured transfer exposes its executor-owned `.status`. A boundary payout
+reserves before dispatch. Only matching terminal confirmation can post or void
+the reservation. An acknowledgement, transport failure or missing response
+keeps the reservation. A refund is a separately funded move. Account balances
+alone do not prove an external effect. The language adds no automatic
+provider-failure reversal or deadline settlement policy.
+
+## Ten laws
+
+1. Each concept has one concrete meaning.
+2. Provider transport and credentials stay outside the contract.
+3. Every state change emits its declared event.
+4. Four transfer instructions are the only money movement vocabulary.
+5. Instances have an opaque identity and money uses integer minor units.
+6. Typed requirements and effects execute atomically.
+7. Live additions preserve existing meaning; development estates may recreate.
+8. Business names identify object kinds, attached instruments and public actions.
+9. Waiting uses lifecycle states and clocks. Before admission, the executor
+   catches up actor: clock actions with due instants on the locked instance,
+   references and selected rows, in chronological order. Catch-up commits its
+   own transaction and events before the caller request is evaluated. A refused
+   caller request rolls back only its own drafts. Caller deadlines are refusal
+   boundaries; they never execute the caller action. Separate clock actions
+   carry expiry consequences. Requirements and selections observe the resulting
+   clock state.
+10. References close, states are reachable, captures are linear, and terminal
+    instances have no remaining owned-account balances or reservations.
+
+## Clause inventory
+
+The generated [JSON schema](../spec/udl.schema.json) owns the complete field
+inventory, defaults and constraints. `src/schema.ts` is its source.
+
+`calculate.aggregate` reads a typed selection and yields its count or a money sum. `calculate.ratio` computes floor(amount * numerator / denominator) with arbitrary-precision intermediates and refuses a zero denominator. Numerator and denominator share a numeric type. Selection order is a list of typed ascending paths, followed by identity as the final tie-break. `invoke {instrument, action: "create", input}` creates a child record in the same transaction; its inputs resolve in the caller, and the ordinary create actor and requirements still apply.
+
+`calculate.at` reads a typed list at a one-based position and refuses an out-of-range index. Its result has the list item type. Integer divide accepts integer operands and rounds down. Every move may capture its transfer identity into a declared self text field; reserve requires a capture. Captures and their status paths are executor-owned.
+
+## Reporting definitions
+
+An instrument may declare `reports`, a bounded array of strict ReportDefinition
+values. Each definition contains identity/version, scope, datasets, time,
+selection, calculation, validation, output and authority. The JSON schema defines
+all fields. Expressions form an ordered graph with backward references, typed
+money in integer minor units, explicit ratios and date operations. Source fields
+must exist in every bound instrument. A scalar field cannot acquire a suffix;
+account balances use the declared `<account>.balance` path. Company instrument reports require
+cross-Build bindings and are not admitted in this version.
+
+Joins declare one-or-many cardinality, missing-record policy and aggregates;
+implicit row multiplication is forbidden. Compilation checks currencies, column
+and expression types, output columns and sort keys. Execution must check complete
+source populations, required facts, unique row and sort identities, reconciliation
+and declared limits before publishing any result. Empty-population behavior and
+unavailable facts are definition data. Request, read and release roles are
+separate. Independent activation and retained deterministic replay belong to the
+host; language acceptance alone does not authorize an artifact or external release.
+
+Reporting source selections and foreign join keys must be computable from
+PostgreSQL facts; ledger balances and ratios belong after capture. Aggregate
+names are unique across stages. `average` requires an explicit `rounding` policy
+(`floor` or `halfUp`) to retain integer and money minor-unit types. Numeric and
+min/max aggregates skip nulls, return null for all-null inputs, and emit per-row
+`_skippedNulls_<name>` counters in JSON and CSV. Required facts still refuse nulls.