--- title: "API reference" description: "The API and the command line: every verb, every flag, every exit code, and the MCP server." source: "https://aontu.dev/docs/reference-api/" --- # API reference Rendered from [`docs/reference-api.md`](https://github.com/aontu-lang/aontu/blob/main/docs/reference-api.md) in the engine repository, where a correction belongs, and where the test suite executes every example on this page. The programming interfaces of both implementations, plus the command-line tool. For the language itself see the [Language reference](https://aontu.dev/docs/reference-language). ## Contents - [Command-line interface](#command-line-interface) - [Evaluation consumes the tree](#evaluation-consumes-the-tree) - [TypeScript API](#typescript-api) - [`Aontu`](#class-aontu) - [`AontuOptions`](#aontuoptions) - [`AontuContext`](#aontucontext) - [`Val`](#val-typescript) - [Exact numbers and `exactJSON`](#exact-numbers-and-exactjson) - [Variables](#variables) - [Exports](#exports) - [Go API](#go-api) - [`Aontu`](#type-aontu) - [`Val`](#val-go) - [Exact numbers in Go](#exact-numbers-in-go) - [`Ctx` and errors](#ctx-and-errors) - [Variables in Go](#variables-in-go) - [Behavioural parity](#behavioural-parity) --- ## Command-line interface Both implementations ship the same `aontu` command. It evaluates a source file (or stdin) and prints the result, or starts a REPL when run interactively with no file. The synopsis, from the command itself: ```sh $ aontu --help Usage: aontu [options] [file] aontu vet [options] [more-data...] aontu subsume [options] aontu breaking --against [options] aontu trim --check [options] aontu relations [options] aontu reaches [--relation ] [options] aontu view [options] ... aontu view --views [--check] [options] aontu jsonschema [--at ] [--strict] [options] aontu template [--resugar] [--check] [--marker ] [--profile ] aontu trace [--at ] [--format json] [--marker ] [--profile ] aontu render [--check] [--at ] [--format json] [--marker ] [--profile ] aontu hash [options] aontu sync [--frozen] [options] [dir] aontu add [@] [options] [dir] aontu get [@] [options] [dir] aontu remove [options] [dir] aontu why [options] [dir] aontu publish [--yes] [--to ] [options] [dir] aontu pkg tidy|verify|vendor|manifest|refreeze|tree|outdated|serve [options] [dir] aontu pkg keygen aontu model get [options] aontu model why [options] aontu model set =... --entry --overlay aontu allow --role [--at ] ... aontu agentsmd [--write ] [--depth ] aontu fmt [-w|-l|--check|-d|--lint] [--marker ] [--profile ] ... aontu help [topic] [--format text|json] aontu explain | --list [--format text|json] aontu init [dir] aontu lsp aontu mcp [--root ] Evaluate an aontu source file and print the result as JSON. With no file on an interactive terminal, start a REPL. With no file and piped input, read the source from stdin. ... ``` The elided remainder lists every option; the per-verb sections below carry the same lists. Three options apply to every verb that reads a document: `--trust ` (the include capability: `system`, `none`, or `root[:dir]`; see [`AontuOptions`](#aontuoptions) for what each admits), its shorthand `--include-root `, and `--text-ext [,]` (extensions an include additionally reads as text; repeatable, and a leading dot is optional). The last rides WITH the capability rather than beside it: both answer what an include may read. Five verbs take none of the three: [`help`](#aontu-help), [`explain`](#aontu-explain) and [`init`](#aontu-init), which read no document; [`lsp`](#aontu-lsp), which takes no arguments at all; and [the MCP server](#the-mcp-server), which confines with `--root ` instead. [`fmt`](#aontu-fmt) takes all three, and they govern the document it evaluates, which is the one `--profile` names rather than the one it formats. `sync`, `add`, `get` and `remove` take them and then refuse a `root` capability, because a confined run cannot reach the package cache they write. **Behaviour** - **File:** `aontu config.aontu` reads, unifies and prints the file. Relative `@"file"` loads inside it resolve against the file’s own directory, so it works from any working directory. - **Exactly one file.** The bare form is `aontu [options] [file]`, singular, and a second filename is a usage error (exit 2) rather than a silent discard. This is what makes a MISTYPED VERB fail loudly: `vet2` matches no subcommand, so it falls through as a file name, and `aontu vet2 schema.aontu good.json` is a usage error rather than a plausible pass: in the one place a tool loop reads the exit code to decide whether the data is good. A file genuinely named like a verb is still reachable as `./vet`. - **One mistyped verb is diagnosed too.** A single argument that cannot be read and is shaped like a bare word (no separator, no extension) is reported as a verb rather than as a missing file, with the nearest verb named: `aontu vett` answers ``aontu: `vett` is not a file, and not a verb this port knows`` and suggests `aontu vet`, at exit 2. A path-shaped argument (`./help`, `help.aontu`, `/tmp/help`) keeps the file diagnosis and its exit 1, which is the same escape hatch the subcommand dispatch uses. - **Stdin:** `echo 'a:1 b:$.a' | aontu` reads source from the pipe. - **REPL:** `aontu` with no file on a terminal starts an interactive loop; each line is evaluated and printed. - Output is pretty-printed JSON by default, or canonical form with `--canon`. - **Exact numbers keep their digits.** A document using the `0d` exact literals prints them in full, at any magnitude: `x:0d9007199254740993` prints `9007199254740993`, not a rounded `…992`. The TypeScript CLI gets this from the library’s [`exactJSON`](#exact-numbers-and-exactjson) export, the Go CLI from a `json.Encoder` over the [marshalling types](#exact-numbers-in-go), with HTML escaping **off** in both, so `<`, `>` and `&` stay literal and the two CLIs print the same bytes. - Results go to **stdout**; errors go to **stderr** with a non-zero exit status (`1` for an evaluation error, `2` for a bad option). - **`--format json` makes the answer an object**, so the default entry point reports like every other verb rather than like a stream of prose: `{aontu, findings, ok, out}` on **stdout**, whether the document evaluated or not. `out` is the text the default form prints (the generated JSON, or the canonical form under `--canon`), empty when it did not evaluate; `findings` then carries one finding with the `code` to hand to [`aontu explain`](#aontu-explain), its `class` from the registry, and the headline as `message`. The finding names no site and carries no hint: the frames under the headline are drawn for a person, and hint prose is deliberately outside cross-port parity. Exit codes are unchanged. ### `aontu vet` Validate data documents against a schema document. This is the emit → validate → repair loop’s entry point: an agent writes a document, `vet` says what does not hold and where, and the exit code says which kind of “no” it was. ```plaintext aontu vet [options] [more-data...] --at Validate against this path of the schema ($.a.b) --closed Refuse keys the anchor does not declare --partial Residue is reported but does not fail the run --max-errors Cap the finding list (default 20) --coverage Report what the check examined --strict-coverage --coverage, and exit 1 when the run was vacuous --coverage-at

Measure coverage under this path of the data only --format text (default), json or sarif --watch Re-run whenever a watched file changes ``` **Exit codes are verdict classes**, not a pass/fail bit, because the three ways to fail call for three different responses: | Exit | Verdict | Meaning | | --- | --- | --- | | 0 | `valid` | the data unifies and is concrete (or `--partial`) | | 1 | `invalid` | the data does not hold: a contradiction it can never satisfy, or a document that would not parse | | 1 | `valid` | a VACUOUS run under `--strict-coverage`: the unification held and measured nothing, so the verdict stands and only the status says so (below) | | 2 | : | usage: a bad option, or a file that cannot be read | | 3 | `incomplete` | no contradiction, but the truth is not yet satisfied | | 4 | `error` | the run could not be set up from the schema side: an unusable schema, or an `--at` that names nothing: never the data’s fault | Each data file is vetted separately, and the worst verdict wins: two data files are two candidates for the same truth, not one merged candidate. `--max-errors` caps the whole report, not each file, and says so with `truncated`. **A data file that will not parse is the data’s fault**, and is reported as one `parse`\-class finding with a site in that file: not as a broken schema. The distinction matters to the loop the verb exists for: exit 1 says “repair what you emitted”, exit 4 says “the truth you were given is unusable, stop”. #### What the check examined A check that examined **nothing** and a check that **passed** answer the same. That is not a bug in the unifier, which answered correctly about the document it was given, but it is a hole in a gate: the caller reads exit 0 and reports success. The usual cause is one construct. A schema written with the wildcard other tools use is not a wildcard here: ```plaintext entity: { "*": { table: string } } ``` `"*"` is a key **named** `*`. It declares an entity called `*`, meets no data key, and constrains nothing, so data with `table: 42` vets `valid`. The template is [`&:`](https://aontu.dev/docs/reference-language), which meets every key of the map it sits in. `--coverage` adds a `coverage` object to the report, and the report is the answer: | field | is | | --- | --- | | `checked` | data **leaves** a schema declaration constrained | | `leaves` | data leaves in all, under `--coverage-at` when given | | `declared` | declarations the schema makes under the anchor: a map key, a list index, or a template, at every depth | | `unchecked` | the shallowest data paths no declaration constrained | | `unused` | the shallowest declarations no data path met | | `vacuous` | no data leaf was constrained, over a document that has leaves | **Leaves, not paths.** A leaf is where a value lives, and matching a container constrains no value: a schema saying only “there is a key called `entity`” has checked nothing, and `checked` is the number that says so. A document with no leaves is not vacuous either, because there was nothing to examine. The lists name the **shallowest** paths: a subtree nothing constrained is named once rather than once per leaf. The text form prints the first ten of each and counts the rest; the JSON form carries every one. `--strict-coverage` makes a vacuous run **exit 1**. The verdict word is unchanged (the unification really did hold), so nothing that passes today starts failing, and the reason goes to stderr while stdout stays a report contract. It is the flag a CI gate and an agent loop both want, and it implies `--coverage`, because a gate cannot fire on what was never measured. Across several data files the schema side is counted once and the data side adds up: a declaration one file exercised is not unused, and `vacuous` means no file constrained anything. The accounting is **structural**: what the schema declares about the data, rather than a reading of the meet. A meet-based reading would count a value the data supplied to itself as covered, which is the opposite of the question. It costs one extra evaluation of the data document, and only when asked for. **A parse failure is located.** Its single site carries the parser’s own row and column, 1-based: the same position the human renderer draws its caret under. A document whose second line is `b: ]` reports `row: 2, col: 4`, in both ports. **A site has an extent, so a finding can be repaired.** Beside `row` and `col` a site carries `len` (the span in UTF-16 code units, the units `col` is already counted in) and `src`, the source text that span covers. Both are `-1` and `""` when unknown, and a consumer must not edit a site that says so. The extent is not optional detail, because **`value` is the canon and not the source text**. Vetting `port: 0x1F` reports `value: "31"` at column 7, so replacing `(col, value.length)` writes `port: 90001F`. With the span the edit is `(col, len)` (`(7, 4)`) and lands exactly on `0x1F`. `src` is what makes the span **verifiable**: read the document at `(row, col, len)`, compare it to `src`, and refuse if they differ. That check matters most where the span is correct but partial. A site names the token it points at, exactly as `row` and `col` always have, so a scalar reports its whole literal while a compound reports its opening token: `min(1)` reports `src: "min"`, a map reports `src: "{"`. Seeing `min` where it expected `min(1)`, a consumer refuses rather than replacing the name and orphaning the arguments. To see the site shape, pin `port` in a one-line `schema.aontu`: ```aontu port: 8080 ``` and vet a `data.aontu` that spells a different port in hex: ```aontu port: 0x1F ``` ```sh $ aontu vet --format json schema.aontu data.aontu { "aontu": { "verb": "vet", ... "sites": [ { "col": 7, "file": "data.aontu", "len": 4, "role": "data", "row": 1, "src": "0x1F", "value": "31" }, ... $ echo $? 1 ``` `value` says `31`, `src` says `0x1F`, and `len` says the span is four code units: the three facts an editing consumer needs, together. `aontu model why` carries the same pair: each conjunct in the record has the `len` on its site and the contribution’s own `src` beside its `canon`. **A site names the file whose text it excerpts**, which for a modular document is not the entry file. A constraint written in `lib/types.aontu` and reached through `@"./lib/types.aontu"` is reported at `lib/types.aontu` with that file’s row and column: never at the entry with the included file’s coordinates, which is a real filename against a line it may not have. The name is the one the CALLER’S OWN spelling reaches: `vet contract.aontu` names `types.aontu`, `vet a/b/contract.aontu` names `a/b/types.aontu`, and an absolute entry keeps absolute includes. So a site can be opened from wherever the command was run, and a report stays repo-relative, which is what a SARIF upload needs. Identity is still the resolved path underneath: two documents loading one library by different relative spellings are one file, not two. **Every verdict carries its finding, `error` included.** A schema that does not stand up (a contradiction inside it, a document that will not parse, a merge marker) reports what failed and where, while the verdict stays `error`: whose fault it is and what the fault is are two separate answers, and the report gives both. Every site is in the schema (role `schema`), and a contradiction names both of its operands, exactly as one in the data would. A report that said only `error` was the one a repair loop could do nothing with. **`--at` takes a structural path**: map keys and list indices, the same thing a reference means by `$.a.b`, with an index spelled as a plain decimal integer. A path that names nothing is verdict `error`, carrying the same `no_path` finding `get` and `why` give, including the “did you mean” note when a near key exists. **Relative `@"file"` loads inside either document** resolve from that document’s own directory, exactly as they do for `aontu `. **A finding names both sides.** Sites are labelled by provenance (`data` first, because that is the one to edit) rather than by the source-order heuristic a single-document error uses. Write a closed schema as `service.aontu`: ```aontu service: close({ name:string port: *8080|integer replicas:integer }) ``` and a `deploy.json` with one mistyped key and one string where an integer belongs: ```json {"service": {"name": "checkout", "prot": 8080, "replicas": "3"}} ``` ```sh $ aontu vet service.aontu deploy.json verdict: invalid $.service.prot: closed [conflict] [aontu/closed]: Cannot resolve value at path $.service.prot data: deploy.json:1:42 (8080) $.service.replicas: no_scalar_unify [conflict] [aontu/no_scalar_unify]: Cannot unify values at path $.service.replicas data: deploy.json:2:15 ("3") schema: service.aontu:1:59 (integer) $ echo $? 1 ``` The `closed` finding has no schema site (there is no line that refuses `prot`, only a `close()` that never declared it) and the `no_scalar_unify` finding names both. `--format json` emits the same report as an object, with an `aontu` stanza naming the producer, so a report read from a pipe says which version and verb made it. Where the constraint algebra knows what would have unified, the finding carries it as `expected`/`actual`, and a `must()` check’s author message rides along as `note`. **A finding carries the repair beside the diagnosis.** `message` is the headline and stays one line (that is what makes it comparable and greppable) so a finding also carries `hint`: the engine’s own explanation of the failure class, with the offending values filled in. It is the text a human sees under the error frame, and for several codes it is the only place the FIX is written down. A lossy integer literal is the clearest case (abridged): ```json { "code": "lossy_integer_literal", "message": "[aontu/lossy_integer_literal]: Cannot resolve value at path $.port", "hint": "This integer literal, 9007199254740993, is not exactly representable in\nbinary64 ... write it as a `0d`\nliteral to get the exact integer." } ``` The field is absent, not empty, for a code that has no hint text. Hint prose, like `message`, is deliberately outside cross-port parity. **Colour is a decision about the destination.** Error frames are coloured for a terminal and plain everywhere else: `NO_COLOR` (set, to anything) turns colour off for every caller of the library, the command additionally turns it off when its own stderr is not a terminal, and `--jsonl` turns it off unconditionally: a JSONL answer is machine-read by definition. A piped report therefore never carries terminal control codes into a log, a CI annotation or a parser. `--format sarif` emits the report as SARIF 2.1.0, the interchange form CI systems ingest (GitHub code scanning upload, PR annotation): a minimal profile: one run, one result per finding, the data site as the primary location, the schema site under `relatedLocations`, and the whole native finding embedded in `properties`, so a SARIF consumer still holds the native contract. Severities map to SARIF levels (`info` → `note`). The renderer is library API in both ports (`sarifReport(report, version)` from `aontu`; `aontu.SarifReport` in Go), and its bytes are held to cross-port parity by the golden in [`test/spec/files/vet-sarif/`](https://github.com/aontu-lang/aontu/blob/main/test/spec/files/vet-sarif/README.md). A ready-made GitHub Action wrapping the verb ships in this repository: [`vet-action/`](https://github.com/aontu-lang/aontu/blob/main/vet-action/README.md). `--watch` re-runs the whole vet whenever a watched file (the schema or any data file) changes, streaming one report per run: non-incremental by design: parsed trees are single-use, so every run is a full re-parse and re-unify, bounded by the fixpoint’s pass budget. A file that is briefly unreadable mid-save reports and keeps watching. #### Vetting a recursive schema A [recursive schema](https://aontu.dev/docs/reference-language#recursive-references-fixpoints) needs nothing extra from `vet`: the definition expands one level per [meet](https://aontu.dev/docs/unification) with concrete data, so the checks descend exactly as far as the data does, and a finding at depth is located there. The vocabulary below is a trimmed version of [use-cases/13-recursive-schema](https://aontu.dev/use-cases/13-recursive-schema). Write it as `chain.aontu`: ```aontu spec: hide({ Step: { approver: string & re("^[a-z]+@acme[.]example$") decision: *pending|pending|approved|rejected then?: $.spec.Step } }) ``` `--at` anchors the run at the definition (`hide()` keeps `spec` out of generated output but not out of the path) so a data document is a candidate `Step`, not a candidate whole file. A two-level chain in `request.json` holds: ```json {"approver": "lead@acme.example", "decision": "approved", "then": {"approver": "cfo@acme.example"}} ``` ```sh $ aontu vet --at $.spec.Step chain.aontu request.json verdict: valid ``` A chain whose third level breaks the `approver` pattern, as `request-deep.json` does, is refused **at that depth**: ```json {"approver": "lead@acme.example", "decision": "approved", "then": {"approver": "cfo@acme.example", "then": {"approver": "EXTERNAL@other.example"}}} ``` ```sh $ aontu vet --at $.spec.Step chain.aontu request-deep.json verdict: invalid $.spec.Step.then.then.approver: constraint [conflict] [aontu/constraint]: Cannot unify values at path $.spec.Step.then.then.approver expected: re("^[a-z]+@acme[.]example$") actual: "EXTERNAL@other.example" data: request-deep.json:3:32 ("EXTERNAL@other.example") schema: chain.aontu:3:24 (re("^[a-z]+@acme[.]example$")) $ echo $? 1 ``` The finding’s path is the unrolled position (`$.spec.Step.then.then.approver`), while its schema site is the one `re()` the author wrote: the definition is written once and applies at every depth, and the report says both. For the recipe form see [Define a recursive schema](https://aontu.dev/how-to/define-a-recursive-schema). ### `aontu subsume` The subsumption query as a command ([docs/reference-language.md, “Subsumption”](https://aontu.dev/docs/reference-language#subsumption)): does the general document admit every instance the specific one admits? ```plaintext aontu subsume [--profile values|defaults|gen] [--at ] [--format text|json] ``` The exit code is the verdict class: `0` subsumes, `1` does not subsume (the findings carry the witness: path, codes, both sites), `3` undecided (always with a `sub_*` reason), `4` a document that does not stand up on its own, `2` usage. The report reuses vet’s finding object and renderers, class `compat`. **An unexpanded recursive position is `undecided`, never guessed.** A [recursive reference](https://aontu.dev/docs/reference-language#recursive-references-fixpoints) expands only against concrete data, and subsumption compares two documents with no data on either side, so at the recursive position there is no rule to apply, and the query says so rather than answering from hope. Write a `general.aontu`: ```aontu spec: hide({ Step: { label:string then?:$.spec.Step } }) doc: $.spec.Step ``` and a `specific.aontu` whose step recurses into a DIFFERENT definition: ```aontu spec: hide({ Step: { label:"start" then?:$.spec.Other } Other:label:string }) doc: $.spec.Step ``` ```sh $ aontu subsume general.aontu specific.aontu verdict: undecided $.spec.Step.then: sub_unresolved [compat] no subsumption rule covers this pair of value formers expected: $.spec.Step actual: {"label":string} general: general.aontu:1:41 ($.spec.Step) specific: specific.aontu:1:63 ({"label":string}) $.doc: sub_unresolved [compat] no subsumption rule covers this pair of value formers expected: $.spec.Step actual: {"label":"start","then"?:{"label":string}} general: general.aontu:2:6 ($.spec.Step) specific: specific.aontu:1:20 ({"label":"start","then"?:{"label":string}}) $ echo $? 3 ``` **The same recursion on both sides is decided**, and decided by identity: a document that recurses, declares a relation or shares a template by reference admits itself, because two values with the same **hash form** are the same value. The rule runs only where the answer would otherwise be `undecided`, so it narrows nothing else, and without it a contract could not be gated against its own earlier version at all. This is the verdict [`breaking`](#aontu-breaking) fails on by default: a gate that cannot decide a recursive contract reports `undecided` and stops, and `--allow-undecided` is the deliberate downgrade. ### `aontu breaking` The evolution gate built on the same query: compare a document against its own earlier versions. ```plaintext aontu breaking --against [--at ] [--mode backward|forward|full] [--allow-undecided] [--format text|json] ``` - `--against` takes a file path or `git#`, and is repeatable. A `git#` spelling is the old version of the **whole tree**, not of the entry file alone: the revision’s includable sources (`.aontu`, `.aontu`, `.jsonic`, `.json`) are materialised into a temporary directory by shelling out to git (no embedded git) and the old document is evaluated from there, so a change inside an `@"…"`\-included file is part of the comparison. The temporary tree is removed when the run ends. Sources outside the revision (package includes under `node_modules`, the bundled `aontu:system`) resolve as they always do; their versions travel with the lockfile rather than with this comparison. A file the revision does not carry is a usage failure naming it, not a comparison against nothing. - `--at ` compares that path of **both** versions, the same anchor [`subsume`](#aontu-subsume) takes, and findings are reported from it. A module’s top level carries the things that are _supposed_ to change between releases (the version string, the `aontu_policy` block) so the whole-document comparison answers about those rather than about the contract, and a release that bumps only its version self-breaks the gate. Anchoring at the contract is the fix; splitting the file was the workaround. - Modes: **backward** (the default) checks the new document subsumes the old: documents valid under v1 stay valid; **forward** checks the old subsumes the new; **full** checks both. - The document can declare its own promise: `aontu_policy: hide({compat: *backward | forward | full | none})`: `breaking` reads `$.aontu_policy.compat` from the new document, and `--mode` overrides it. `none` declares no promise: nothing is checked. - Exit codes mirror `subsume`’s: `0` compatible, `1` breaking, `3` undecided, `4` error, `2` usage. Undecided **fails** the gate by default (a gate that shrugs is not a gate) downgradable with `--allow-undecided`. - `--allow-deprecated-removal` downgrades a finding about a value the old version already `deprecate()`d to a warning (still reported, no longer failing): deprecate-then-remove is the supported rename path. ### `aontu trim` Report redundant map entries (entries whose removal leaves the evaluated result unchanged, the spread-implied case included) as paths. ```plaintext aontu trim --check [--format text|json] ``` - The test is **evaluate-and-compare**: for each candidate entry the source is re-parsed, the entry deleted from the parsed tree, and the canon compared to the baseline. This covers everything the fixpoint can see (spread templates, references, duplicate-key merges), and a removal that _errors_ is not redundant: the document does not stand up without that entry. - Candidates are map entries at every depth; **list elements are not candidates** (removing one shifts every later index: a different document, not the same one minus a redundancy). A child of a redundant parent is skipped: removing the parent already covers it. - `--check` is **required**: trim only reports, and `aontu trim f.aontu` doing something other than trimming silently would be worse than saying so. It is not blocked on the machinery [`set --in-place`](#aontu-model-set) now has (a splice needs no format-preserving editor) but deleting an entry is a different edit from replacing one: a statement’s span does not say which surrounding blank line or trailing comment went with it, and guessing wrong silently rewrites the file’s shape. - Exit codes: `0` clean, `1` redundant entries found, `4` the document itself does not evaluate, `2` usage. - **A verdict of `error` says why.** A document that does not evaluate has no redundancy to report, but it does have a reason: the report carries `errors`, the engine’s own first failure in the same finding shape [`vet`](#aontu-vet) reports in: code, class, path, sites with file, row, column and extent, and the repair `hint`. The field is present only on that verdict, and the text renderer prints the finding under the verdict line. ### `aontu relations` Run the [declared-relation](https://aontu.dev/docs/reference-language#declared-relations) checks (acyclicity and inverse consistency) over one finished model. ```plaintext aontu relations [--format text|json] ``` The vocabulary is declared once, at the field; the model lists plain names. The files below are a trimmed version of [use-cases/12-relations](https://aontu.dev/use-cases/12-relations). Write the vocabulary as `spec.aontu`: ```aontu spec: hide({ Service: { kind: service dependsOn?: rel($.spec.ServiceShape) & acyclic() & inverse(usedBy) usedBy?: rel($.spec.ServiceShape) } ServiceShape: kind: service }) ``` A model whose edges hold, `system.aontu`, passes: ```aontu @"./spec.aontu" services: { &: $.spec.Service } services: web: dependsOn: [path($.services.billing)] services: billing: { dependsOn: [path($.services.ledger)] usedBy: [path($.services.web)] } services: ledger: usedBy: [path($.services.billing)] ``` ```sh $ aontu relations system.aontu verdict: pass ``` A `bad-system.aontu` whose two services depend on each other, with neither inverse written out, fails on every count at once: ```aontu @"./spec.aontu" services: { &: $.spec.Service } services: auth: dependsOn: [path($.services.billing)] services: billing: dependsOn: [path($.services.auth)] ``` ```sh $ aontu relations bad-system.aontu verdict: fail $.services.auth.dependsOn.0 dependsOn: cycle $.services.auth -> $.services.billing -> $.services.auth $.services.auth.dependsOn.0 dependsOn: $.services.billing does not list $.services.auth under usedBy $.services.billing.dependsOn.0 dependsOn: $.services.auth does not list $.services.billing under usedBy $ echo $? 1 ``` - Relations are declared **at the field**, by [`rel(t)` and the graph atoms](https://aontu.dev/docs/reference-language#declared-relations): `acyclic()` and `inverse(name)` register the declaration during unification, and the verb reports the verdict over the finished model’s edge set. There is no reserved `relations:` key: a document that writes one has written ordinary data. - **These are not lattice constraints, deliberately.** Both properties are global and non-monotone (one more edge makes an acyclic graph cyclic) so they are facts about a finished model rather than something unification may hold. Generation enforces the same verdict (a located `relation_cycle` / `relation_inverse_missing` at the offending edge); the verb reports it without generating. The [language reference](https://aontu.dev/docs/reference-language#declared-relations) states the rule; the [explanation](https://aontu.dev/docs/explanation#why-there-is-a-verb-surface) argues it. - A finding carries `at` (the position of the offending edge), `code` (`relation_cycle` or `relation_inverse_missing`), `relation`, and `detail`: for a cycle, the node paths it runs through in order; for a missing inverse, `[from, to, inverseName]`. Findings are **sorted by `at`**, so the report diffs cleanly. - **The endpoint type is `rel(t)`’s flow**: declared once on the field, it flows into each far end at the site, so a conflict or a hole is an ordinary located evaluation error rather than a report row, and a document with a wrong-typed far end answers `verdict: error` here, because it does not stand up at all. (The old `target:` declaration and its `relation_target_unmet` finding are retired with the `relations:` key.) - `--format json` wraps the same findings with the `aontu` producer block (`verb`, `version`) that every machine-readable report carries. - Exit codes: `0` `pass`, `1` `fail`, `4` `error` (the document does not evaluate), `2` usage. Note these are the verb’s own three verdicts, not [`vet`](#aontu-vet)’s five classes: there is no schema on the other side of this question, so `incomplete` has nothing to mean. - **A verdict of `error` says why.** A document that does not stand up has no graph, so it has no relation findings, but the report carries `errors`, the engine’s own first failure in the same finding shape [`vet`](#aontu-vet) reports in. `findings` stays the graph’s own vocabulary; the two lists answer two different questions, and the `errors` field is present only on the `error` verdict. - The library form is `relationCheck(src)` in TypeScript and `Aontu.RelationCheck(src)` in Go, returning the identical `{verdict, findings}` record (plus `errors` on a failed run); the derived graph the checks run over is `result.graph` / `Aontu.Graph`, described under [the TypeScript API](#class-aontu). ### `aontu reaches` Ask whether one node **reaches** another over the link graph, at any remove. Endpoints are `$.dotted` node paths. ```plaintext aontu reaches [--relation ] [--format text|json] ``` [`relations`](#aontu-relations) asks about the edge set as a whole. This asks the question that needs the **closure**: does anything `from` links to, at any remove, end up at `to`? That is the shape of every blast-radius question an operator asks (“if the billing database goes, what falls over?”) and every containment question a policy asks (“nothing in the public tier may reach the ledger”), and neither can be put one edge at a time. Ask it of the `system.aontu` model above: ```sh $ aontu reaches $.services.web $.services.ledger system.aontu verdict: reaches $.services.web -> $.services.billing -> $.services.ledger $ echo $? 0 ``` - **The path is the answer**, not decoration: “yes” is worth little to an operator asking what a failure would take out, and the chain is what they act on. It is a **shortest** path, and among shortest ones the first in code-point order, so it is the same path in both ports. A `no` carries none: there is no evidence for a negative answer. - **Transitive, not reflexive-transitive.** `reaches a a` is true only when a path of one or more edges returns to `a`, which says the graph has a cycle through `a` rather than saying nothing. - `--relation ` follows only edges under that relation: the difference between “can this reach that at all” and “can it reach it _this way_”. - A link into part of a node (`$.services.auth.ports.http`) reaches **that node**, not the one above it: reachability is between tree positions, and there is no declared boundary to widen it to. Same rule [`relations`](#aontu-relations) uses, and it has to be, or the two verbs would disagree about what an edge connects. - Exit codes: `0` `reaches`, `1` `unreachable`, `4` `error`, `2` usage. An unreachable pair is a **failed check**, not an error: the question was answered, and the answer was no. - **An endpoint that names no node is a refusal**, reported as `refer_unresolved` with the linked nodes listed: answering `no` would report a typo as a fact about the model. An endpoint that exists but has no edges is a perfectly good question with the answer `unreachable`. - Like acyclicity, this is a verb and **not a lattice constraint**: reachability is global and non-monotone, so a citizen asserting _non_\-reachability could be true and then false as one more edge arrives. - The library form is `reachCheck(src, from, to, options?)` in TypeScript and `Aontu.Reach(src, from, to, options)` in Go, returning the identical `{verdict, path?}` record (plus `errors` on a failed run). In `system.aontu` the `usedBy` inverses run the other way, so the ledger reaches the web service in general but not along `dependsOn`: ```sh $ aontu reaches $.services.ledger $.services.web system.aontu verdict: reaches $.services.ledger -> $.services.billing -> $.services.web $ aontu reaches $.services.ledger $.services.web --relation dependsOn system.aontu verdict: unreachable $.services.ledger does not reach $.services.web $ echo $? 1 ``` And an endpoint that names no node refuses rather than answering: ```sh $ aontu reaches $.services.web $.services.ledgr system.aontu verdict: error $: refer_unresolved [reference] $.services.ledgr names no node in this document. note: nodes with links: $.services.billing, $.services.ledger, $.services.web $ echo $? 4 ``` ### `aontu view` Draw a **figure** of a finished model, as deterministic text a golden diff can check: no coordinate is computed, nodes and edges are sorted by code point, and both ports emit the same bytes. ```plaintext aontu view [--as ] [--at ] [--out [--check]] [--strict] [--max-rows ] [--depth ] [--style ] [--format text|json] [options] ... ``` Ten kinds. Eight read a report the engine already produces; `doc` and `lattice` read the document itself, which is the one thing no report holds: | kind | draws | reads | profiles | | --- | --- | --- | --- | | `doc` | the document’s own key tree, to a depth | the anchor walk, as `get --keys --types` reads it | `text`, `svg` | | `lattice` | the language’s value lattice, with a count at every node the document reaches | the anchor walk, and each value’s own kind | `text`, `svg` | | `tree` | the dependency tree of a relation: roots derived, repeats elided, cycles marked | the edge set | `text`, `svg` | | `matrix` | the dependency-structure matrix over one relation, in `canon` or `partition` order, with `--closure` | the edge set and the relation declarations | `text`, `svg` | | `graph` | the node-link drawing, grouped and labelled by fields of the nodes | the edge set, the declarations, the node values | `mermaid`, `dot`, `er` | | `layer` | the architecture layers: one band per value of `--group-by`, upward edges named | the edge set and the node values | `text`, `mermaid`, `svg` | | `sets` | the set-intersection panel over a family of sets (UpSet) | the generated value | `text`, `svg` | | `layers` | which document contributed which path | the provenance record | `text`, `svg` | | `ladder` | the meet ladder at one path: every contribution as a rung, in rank order | the [`why`](#aontu-model-why) record | `mermaid`, `dot` | | `poset` | the subsumption order over several documents | [`subsume`](#aontu-subsume), pairwise | `mermaid`, `dot` | The first profile listed is the kind’s default; asking for another is a refusal (`view_profile_unknown`), because there is no text form of a node-link drawing and no Mermaid form of a matrix. `--as svg` draws the cell-based kinds (every kind whose text form is a grid of character cells) as a standalone SVG with the same geometry: 8 units per character and 20 per line, every coordinate a whole number, so no font is measured and both ports emit the same bytes. The figure carries its own style block (dropped by `--style none`, below); a host page sets the colours through CSS variables (`--av-ink`, `--av-muted`, `--av-bg`, `--av-rule`, `--av-rule-faint`, `--av-closure`, `--av-warn`, `--av-alert`, `--av-bar`), and the defaults stand where it sets none. The matrix fills a direct cell, tints a closure cell, marks an unmirrored edge, and rules the diagonal; the layers draw each upward edge as a dashed arrow; the panel draws its bars and dots. The node-link kinds stay Mermaid and DOT, whose renderers lay them out. Draw the `system.aontu` model above over its `dependsOn` relation, first as the tree, then as the matrix in partition order: ```sh $ aontu view tree --relation dependsOn system.aontu web └── billing └── ledger ``` ```sh $ aontu view matrix --relation dependsOn --order partition --closure system.aontu 1 2 3 ledger 1 \ . . billing 2 X \ . web 3 + X \ # above-diagonal direct cells: 0 ``` A cell at (row, column) is set when the row depends on the column: `X` a direct edge, `!` a direct edge whose declared inverse is not written back, `+` reachable only transitively, `.` absent, `\` the diagonal. In partition order an acyclic relation is a lower triangle, and the footer’s count of cells above the diagonal is the acyclicity proof in the picture’s own shape; a cycle survives every ordering as an above-diagonal cell, and is reported as `cycle_block`. The same edges as a node-link drawing, in Mermaid: ```sh $ aontu view graph --relation dependsOn system.aontu flowchart LR n_billing["billing"] n_ledger["ledger"] n_web["web"] n_billing -->|"dependsOn"| n_ledger n_web -->|"dependsOn"| n_billing ``` The `lattice` kind draws the LANGUAGE rather than the model. The shape is always the same ([the value lattice](https://aontu.dev/docs/reference-language#the-value-lattice), whatever the document holds) and what the document adds is a count at each node its own values landed on. Write `ports.aontu`: ```aontu host: "0.0.0.0" port: 8080 tls: true timeout: 1.5 retries: integer backoff: integer & min(1) ``` ```sh $ aontu view lattice ports.aontu top │ ┌────────────────────────────────┬────┴───────────────────────────┬─────────┐ string (1) number boolean (1) null │ │ │ │ ├─────────────┬────────────┬─────┴─────┬────────────┐ │ │ path() integer (2) float (1) biginteger bigdecimal │ │ │ │ │ │ │ │ │ └─────────────┴────────────┴──────────┬┴────────────┴─────────────┴─────────┘ nil ``` A concrete scalar sits at its kind (`8080` counts at `integer`) and a kind written as a schema sits _at_ that node, which is why `retries: integer` is the second of the two. `backoff` is at neither: `integer & min(1)` is a region of the lattice rather than a point, so the figure declines to draw it anywhere and names it instead: ```plaintext lattice_unplaced 1 $.backoff ``` An unresolved disjunction is unplaced for the same reason: `*8080 | 9090` is two places at once, and a node that claimed either would be claiming something the document does not say. - **The loss report.** Every run prints, on stderr, what the figure could not draw or drew differently from the model, one line per code with a count: `hidden_contribution` (an edge inside a `hide()` subtree, not drawn, because a committed figure discloses what it draws), `edges_in_disjunct` (a link under an unresolved disjunction, which is not a fact, so the figure reports it rather than picking an arm), `unresolved_field` (a node without a value for `--group-by` or `--label`), `lattice_unplaced` (a value at no single point of the lattice, named rather than drawn), `cycle_block`, `cols_elided`, and for the poset `order_undecided`, `order_maybe_equal` and `order_intransitive`. Any of these makes the verdict `lossy`, which `--strict` turns into exit `1`. Three codes are informational and leave the verdict `rendered`: `edges_deduped` (a model declaring each entity at two positions writes each edge twice), `inverse_suppressed` (a declared mirror, implied by the edge drawn) and `crossings` (a property of the emitted order). - **`--style `** says how a figure carries the MEANING of its marks. Every mark has a reason the extractor established (a direct cell, a closure cell, an unmirrored edge, an upward edge, a repeated subtree) and each profile has one way to show it: SGR escapes for `text`, CSS classes for `svg`. `auto`, the default, picks that mechanism where the destination can carry it: escapes only when **stdout** is a terminal and `NO_COLOR` is unset (stdout, because that is where the figure goes: the error frames’ own colour decision is about stderr), and an SVG keeps the stylesheet that makes it standalone. `none` drops both: on `svg` the classes stay (they are structure, not style) and only the embedded stylesheet goes, which is what a host page wants once it has bound `--av-ink` and its kin and is embedding several figures. `ansi` and `css` name a mechanism outright, and asking for one on a profile that cannot carry it is a usage error (`view_style_profile`) rather than a silent no-op. Escapes are never written to a file: `--out` with `--style ansi` is refused, and `auto` resolves to no escapes there. Neither mechanism states a colour, and a figure still cannot name one: SGR 31 means the colour the reader’s terminal calls red, and a CSS class states nothing at all. A hex triple in a figure stays refused, and so does `style` in a view document: a declaration says which projection, never how it looks. - **`--out ` and `--check`.** The figure is written to the file instead of stdout; with `--check` nothing is written and the exit is `1` when the file differs from what would be drawn, which is the CI gate for a committed figure. - **`--max-rows `** (default 60) is a refusal, exit `2`, not a truncation; the message names the narrowing options. - `doc`: the shape of the model, before any of its values mean anything. Every other kind here needs the document to HAVE something (links, contributions, peers) and draws nothing from one that does not; this draws what is in the document and how it is arranged, which is what a reader meeting a model wants first. `--at` names the subtree (default `$`) and `--depth ` how many levels of key below it (default 3). Map keys are in code-point order and list indices in order, exactly as `get --keys` lists them. A leaf carries its canon, cut at 32 characters: the kind of thing it is, not its value. A container the depth bound stops at carries the number of keys not drawn, and they are counted into the loss report as `depth_elided`: a tree that stopped without saying so would be the one thing a structural drawing must not be. - **`--at `** restricts the edge-derived kinds to nodes under the path, names the subtree `doc` draws, the provenance panel to paths under it, and names the path the ladder draws (required) and where the poset compares. - `tree`: `--relation` draws one relation; without it every relation is drawn, each branch naming its own. `--root ` (repeatable) draws one subtree; a root that is not a node of the drawn graph is refused (`refer_unresolved`). Roots are derived as the nodes nothing depends on; a shared subtree is expanded once and marked `(*)` after; a closing edge is `(cycle)`; labels are the shortest path suffix unique in the drawing. - `matrix`: `--relation` is required unless exactly one relation has edges (`view_relation_ambiguous` otherwise); `--order canon` (label order, the default) or `partition`; `--closure` marks the transitively reachable cells. Ten or more rows stack the index digits in the header. - `graph`: `--relation` (repeatable) keeps only those predicates; a declared inverse’s mirror is suppressed and counted. `--group-by ` puts each node in a subgraph named by that field’s value (ids `g0`, `g1` and so on, in label order); `--label ` labels the node with it, a number or boolean as its canon. Node ids encode the label injectively: `n_` + the name when it is an ASCII identifier, else `nq_` + the name with every other code point as `_` and its hex (`cust-1` is `nq_cust_2d1`, so a name such as `end` or `graph` can never collide with a keyword). Text is escaped per code point: Mermaid as numeric entities (`#34;` for `"`, `#124;` for `|`), DOT as `\"` and `\\`. A label holding a line terminator is refused (`view_line_break`). `--as er` draws Mermaid’s `erDiagram`, every relationship many-to-many because the model states no cardinality. - `layer`: `--group-by ` (required, `view_group_required`) names each node’s layer; bands are stacked in the partition order of the layer-level graph, reversed, so the layer nothing depends on is on top. `--layers a,b,c` fixes the order (top first) for a model whose upward edge makes the layer graph cyclic. The footer counts the relation’s downward, sideways and upward edges, and names each edge `--edges` shows. `--edges upward|all|none` chooses which of them the figure draws over the bands: `upward` is the violations, and the default for the fixed grids (`text`, `svg`), because the bands already say which way the rest go; `all` draws the relation itself, which is what a reader tracing one module’s dependencies wants, and is `mermaid`’s default since it lays edges out itself; `none` leaves the bands alone. In SVG an upward edge is dashed and alert-coloured, a downward one runs from the bottom of its box to the top of the one it names, and a sideways one dips below the boxes of its band. - `sets`: `--sets ` names a map whose keys are the sets, `--member ` the field holding each set’s members (a list of strings), `--universe ` a map or list of every element, so the covered-by-nothing column exists. A member written as an address (`path($.perms.read)`) meets a universe map’s key on that address and is shown by its shortest unique suffix. Columns are the exact membership signatures, by degree, then cardinality, then name; `--min-degree ` drops the low ones and `--max-cols ` elides the rest (`cols_elided`). Both need the document to generate. - `layers`: the same panel over the provenance record, sets being the documents and elements the paths each document wrote into. Files are shown relative to the entry document; `--min-size ` drops the small intersections. - `ladder`: the `why` record at `--at`, one rung per contribution, sorted by rank descending (weakest first, so the winner is the last rung before the value), then by site. - `poset`: several files; each pair is compared with `subsume` at `--at` under `--profile values|defaults|gen` (default `defaults`). Documents that subsume each other are one node, labelled `a = b`; an edge is a cover of the transitive closure, upward toward the more general document; an undecided pair with no proven order is a dashed edge labelled with the `sub_*` reason. Labels are the filenames without `.aontu`. - Exit codes: `0` rendered or lossy, `1` a `--check` mismatch or lossy under `--strict`, `2` usage (an unknown kind or profile, a missing required option, `--max-rows` exceeded), `4` error (a document that does not stand up, a relation, root or path that names nothing). A document with nothing to draw renders an empty figure and exits `0`. In text form the figure is all that stdout carries, so a redirect is a golden file; `--format json` wraps the whole report as `{kind, verdict, text, loss}` under the usual `aontu` envelope, and a refusal carries `errors` in place of `text`. - The library form is `view(src, options)` in TypeScript (`viewTree` remains for the tree) and `Aontu.View(src, options)` in Go, returning the identical `{verdict, kind, text?, loss, errors?}` record; the poset’s further documents ride `options.docs` as `{src, path?, name?}`. **The view document.** A projection that runs in CI belongs in a file. `--views ` names a map, in an ordinary document that includes the model, whose values declare figures: one evaluation, N figures, one exit code. The keys of a declaration are the view options (the flags without the dashes) and every declaration names its `kind` and the `out` file it draws into. `views` is the author’s key; nothing in the engine knows the name, which is why the path is given. Write a `views.aontu` beside the `system.aontu` above: ```aontu @"./system.aontu" views: arch: { kind: matrix relation: dependsOn order: partition closure: true out: "arch.dsm.txt" } views: map: { kind: graph relation: dependsOn groupBy: owner as: mermaid out: "arch.mmd" } ``` ```sh $ aontu view --views '$.views' views.aontu $ aontu view --views '$.views' --check views.aontu $ echo $? 0 ``` Each `out` is resolved against the **view document’s own directory**, so the gate passes from any working directory. Nothing is written unless every figure rendered: N figures of one model are only meaningful together, so a set whose third figure refuses leaves the first two off disk, and its exit code is the worst of the figures’. `--check` compares the whole set and names every difference; `--strict` turns any figure’s loss into exit `1`. A declaration that names an option that is not one, gives a value of the wrong shape, or leaves out `kind` or `out` is `view_document_shape`, reported for every faulty declaration at once and before anything is drawn. The `poset` is refused there: it compares several documents and a view document declares figures of the one it includes. The library form is `viewSet(src, options)` in TypeScript and `Aontu.ViewSet(src, options)` in Go, returning `{verdict, views, errors?}` where each view is `{name, kind, out, verdict, text?, loss, errors?}`: the caller writes the files. `@"aontu:view"` is the bundled schema for a declaration, so the same mistakes are refused when the document is EVALUATED rather than when the verb reads it. Write a `views-typed.aontu`: ```aontu @"aontu:view" @"./system.aontu" views: { &: $.aontu.View.Figure } & { arch: { kind: matrix relation: dependsOn order: partition closure: true out: "arch.dsm.txt" } } ``` ```sh $ aontu view --views '$.views' --check views-typed.aontu $ echo $? 0 ``` `$.aontu.View.Figure` types every option, and a kind that is not a kind, an order that is not an order or a count below zero is an ordinary unification failure naming `aontu:view` as the other operand. It is optional: a view document that does not include it is read exactly the same way, and refused by `view_document_shape` instead. The source is served from the engine, as `aontu:system` is, so it needs no filesystem and resolves under every include capability but `'none'`. The use cases pin one figure of each kind as a golden: [01-service-catalog](https://aontu.dev/use-cases/01-service-catalog) the graph and the matrix, [04-schema-evolution](https://aontu.dev/use-cases/04-schema-evolution) the poset, [08-feature-flags](https://aontu.dev/use-cases/08-feature-flags) the ladder, [12-relations](https://aontu.dev/use-cases/12-relations) the graph and the ER diagram, and [16-module-deps](https://aontu.dev/use-cases/16-module-deps) the tree, the matrix and the layers; 16 also declares all seven of its figures in a `views.aontu` that its `check.sh` gates in one run. ### `aontu jsonschema` Export a document as a **JSON Schema** (draft 2020-12), and say what could not be carried. ```plaintext aontu jsonschema [--at ] [--strict] [--format text|json] ``` This is the interop bridge. Every major LLM provider’s structured-output API constrains generation to JSON Schema and to nothing else, so the shape an enterprise actually deploys is: export the model, let the provider generate under it, then [`vet`](#aontu-vet) the result against the model itself: the schema narrows what is _produced_, the model decides what is _true_. An MCP tool’s `inputSchema`, which the protocol requires to be JSON Schema, is the same export. **The schema goes to stdout and the losses to stderr**, so `aontu jsonschema x.aontu > schema.json` writes a usable schema and still tells the reader what it left behind. Write a `contract.aontu`: ```aontu spec: name: string & re("^[a-z][a-z0-9-]{2,39}$") spec: tier: *internal|standard|critical ``` ```sh $ aontu jsonschema --at spec contract.aontu { "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "name": { "pattern": "^[a-z][a-z0-9-]{2,39}$", "type": "string" }, "tier": { "default": "internal", "enum": [ "internal", "standard", "critical" ] } }, "required": [ "name", "tier" ], "type": "object" } ``` - It exports the **unified** value, not the parse: what a document MEANS is what a consumer should be constrained to. - `--at ` names the subtree to export: the same anchor [`vet --at`](#aontu-vet) takes, so `--at spec` means the same thing in both. - `--format json` prints the whole report (`schema`, `lossy`, `verdict`) under the usual `aontu: {version, verb}` envelope. - Exit codes: `0` exported, `1` lossy **under `--strict`**, `2` usage, `4` the document does not stand up on its own. Without `--strict` a lossy export is still an export and exits 0. **What crosses exactly.** Kinds become `type`; a concrete scalar becomes `const`; a disjunction of scalars becomes `enum`, and its preference becomes `default`; bounds become `minimum`/`maximum`, with the open endpoints as 2020-12’s `exclusiveMinimum`/`exclusiveMaximum`; `re` becomes `pattern` (aontu’s portable subset is a subset of ECMA-262, which is what JSON Schema reads, so no translation happens); `neq` becomes `not: {enum: …}`; `length` becomes `minLength`/`maxLength` on a string and `minItems`/`maxItems` otherwise; `unique()` becomes `uniqueItems`; an optional key is simply absent from `required`. A spread is `additionalProperties: