# aontu

> aontu is a language for the ontology of a software system: the entities it contains, the types they must have, and the relations that must hold between them. The definition is machine-checkable, so a change proposed by a coding agent is admitted or refused with the offending line named.

Every documentation page, concatenated. Documented against `aontu` 0.72.0.
Source: https://github.com/aontu-lang/aontu. Index: https://aontu.dev/llms.txt

Each page below is rendered from the engine repository, where its examples
are executed by the test suite on every build.

The executed use cases are deliberately NOT here. They are long-form
records (verbatim CLI transcripts and findings), and folding them in
would half again the size of this corpus with material a reader wants one
at a time. They are indexed in https://aontu.dev/llms.txt, and each has its own
markdown twin.

---

# aontu documentation

_What aontu is, how its documentation is organised, and a 30-second taste of unification._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/index.md · Page: https://aontu.dev/docs

aontu is a JSON structure **unifier**: a small language (a
purpose-specific dialect inspired by [CUE](https://cuelang.org/)) and an
engine that merges partial structures into one consistent result, or
reports exactly where they conflict. The same source can describe data,
the schema that constrains it, and the defaults that fill it in: all in
one notation, all combined by a single operation: *unification*.

This repository ships **two implementations kept in parity**:

- **TypeScript** in [`ts/`](https://github.com/aontu-lang/aontu/blob/main/ts/): the canonical implementation,
  published to npm as [`aontu`](https://npmjs.com/package/aontu).
- **Go** in [`go/`](https://github.com/aontu-lang/aontu/blob/main/go/): a port
  (`github.com/aontu-lang/aontu/go`) that mirrors the core semantics.

Both are checked against one language-agnostic test suite in
[`test/spec/`](https://github.com/aontu-lang/aontu/blob/main/test/spec/), and every example in these pages is
executed by that machinery too: the outputs come from the engine, not
from the author's memory.

## How this documentation is organised

The documentation is split by **what you are trying to do** when you
open it. Reach for the part that matches your need:

| If you want to…                                               | Read |
|---------------------------------------------------------------|------|
| **Learn** aontu from zero by building something, step by step | [Tutorials](/docs/tutorial) |
| **Accomplish a specific task** you already have in mind       | [How-to guides](https://github.com/aontu-lang/aontu/blob/main/docs/how-to/) |
| **Look up** exact syntax, semantics, options, or API surface  | [Language reference](/docs/reference-language) · [API reference](/docs/reference-api), with three supplements below |
| **Understand unification itself**: meet, top, bottom, the lattice | [Unification](/docs/unification) |
| **Understand** how and why the engine works the way it does   | [Explanation](/docs/explanation) |
| **See whole systems defined**, each with its checks runnable  | [Use cases](/docs/use-cases) |

There are four tutorials, each building one thing and showing the
output of every step: a config that is schema, defaults, and data at
once; the graph layer of identity, relations, and reachability; sharing
a model as a versioned package; and computing source files from a
model. The [index](/docs/tutorial) says what each one assumes.

The how-to guides are one page per task, grouped six ways: run, embed
and integrate; templates, defaults and composition; schemas and
constraints; query, explain and change; validate and evolve; modules
and multi-file.

Three capabilities have doorways of their own:

- **Declare and check relations.** Entities carry identity, the edges
  between them are declared in the model, and the engine checks both.
  The recipe is [check relations](/how-to/check-relations); the live
  version is [`use-cases/12-relations`](/use-cases/12-relations);
  the normative rules are under
  [Declared relations](/docs/reference-language#declared-relations).
- **Write a recursive schema.** A schema can name itself, so trees and
  nested structures validate to any depth. The recipe is
  [define a recursive schema](/how-to/define-a-recursive-schema);
  the live version is
  [`use-cases/13-recursive-schema`](/use-cases/13-recursive-schema);
  the semantics are under
  [Recursive references](/docs/reference-language#recursive-references-fixpoints).
- **Generate code from a model.** The field names, types and
  optionality a Go struct or a TypeScript interface needs are already
  in the model, and the unifier computes the file: a rule set over the
  records, `match` for the type mapping, a backtick string to carry the
  target text, and a component tree of files and lines that a generator
  runtime writes to disk and holds against its golden. The recipe is
  [generate code from a model](/how-to/generate-code); the live
  version, with three targets in one document and a check that both
  ports build identical trees, is
  [`use-cases/15-code-generation`](/use-cases/15-code-generation). The
  rules for the tree itself are the
  [Generation reference](/docs/reference-generation).

Six reference sections sit beside the two above. Each is a surface
that cuts across the language reference rather than a part of it, which
is what the language reference, organised by topic, cannot show at
once:

- [Generation reference](/docs/reference-generation). The component tree:
  every component node, the props it carries, the children it admits,
  and what `aontu render` and `aontu trace` do with a tree.
- [Functions reference](/docs/reference-functions). The call surface of
  every built-in: arity, argument modes, accepted kinds and result
  words, as one table and as slices through it.
- [Error reference](/docs/reference-errors). Every registered error code,
  by class, with what raises it and what a report carries.
- [Packages reference](/docs/reference-packages). The files the package
  system keeps, every field `pkg.aon` declares, the name rules, the
  caps, what an archive may hold, and every refusal code.
- [Grammar reference](/docs/reference-grammar). The published grammar rule
  by rule, the spellings the parser accepts beyond it, and what holds
  the four grammar files to the engine.
- [Agent and editor reference](/docs/reference-agents). Every door a
  machine comes in by, the one answer shape they share, what none of
  them does, and the posture each takes towards includes.

Tooling:

- [The `aontu` command](/docs/reference-api#command-line-interface). One
  binary, nineteen verbs, both implementations. Each verb has its own
  reference section:
  - validate: [`vet`](/docs/reference-api#aontu-vet), wrapped for CI as a
    [GitHub Action](https://github.com/aontu-lang/aontu/blob/main/vet-action/README.md)
  - evolve a schema: [`subsume`](/docs/reference-api#aontu-subsume),
    [`breaking`](/docs/reference-api#aontu-breaking)
  - ask and change: [`get`](/docs/reference-api#aontu-model-get),
    [`why`](/docs/reference-api#aontu-model-why),
    [`set`](/docs/reference-api#aontu-model-set),
    [`trim`](/docs/reference-api#aontu-trim)
  - identity and relations:
    [`relations`](/docs/reference-api#aontu-relations),
    [`reaches`](/docs/reference-api#aontu-reaches),
    [`view`](/docs/reference-api#aontu-view)
  - export and pin: [`jsonschema`](/docs/reference-api#aontu-jsonschema),
    [`hash`](/docs/reference-api#aontu-hash)
  - generate: [`template`](/docs/reference-api#aontu-template),
    [`trace`](/docs/reference-api#aontu-trace) (the guide:
    [Generate code from a model](/how-to/generate-code))
  - depend and publish: [`sync`](/docs/reference-api#aontu-sync),
    [`add`, `get`, `remove`](/docs/reference-api#aontu-add-aontu-get-aontu-remove),
    [`why`](/docs/reference-api#aontu-why),
    [`publish`](/docs/reference-api#aontu-publish),
    [`pkg`](/docs/reference-api#aontu-pkg)
  - hand over: [`agentsmd`](/docs/reference-api#aontu-agentsmd)
  - keep in the agreed form: [`fmt`](/docs/reference-api#aontu-fmt) (the form: [The formatted form](/docs/reference-language#the-formatted-form); the guide: [Format a document](/how-to/format-a-document))

  With no file at all, `aontu` starts a REPL.
- [Language Server (LSP)](/docs/lsp). The `aontu-lsp` diagnostics server
  (TypeScript and Go), how to wire it into an editor, and the reusable
  LSP library API.
- [The MCP server](/docs/reference-api#the-mcp-server). `aontu mcp`, a
  Model Context Protocol server over stdio, answering with the
  identical reports the CLI prints.

For agents:

- [The aontu skill](https://github.com/aontu-lang/aontu/blob/main/docs/skill/SKILL.md). An agent-facing teaching pack:
  the [grammar card](https://github.com/aontu-lang/aontu/blob/main/docs/skill/grammar-card.md), a
  [worked example ladder](https://github.com/aontu-lang/aontu/blob/main/docs/skill/examples.md) whose documents the test
  suite executes, and the [error-code index](https://github.com/aontu-lang/aontu/blob/main/docs/skill/error-codes.md).
-  [The published
  grammar](/docs/reference-language#the-published-grammar): [`grammar/aontu.abnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.abnf)
  to read, with railroad diagrams; [`aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf)
  and [`aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark) for constrained decoding.

Contract:

- [The trust contract](/docs/trust). Hermeticity, termination,
  determinism, and sandboxing: what a host may rely on when evaluating
  an aontu document, and where each guarantee is conditional.

For contributors:

- [The style guide](https://github.com/aontu-lang/aontu/blob/main/docs/STYLE-GUIDE.md). How these pages are written:
  Diátaxis placement, the voice, the banned-phrase list, and the
  snippet directives under which every example runs.

### Why the split?

The four kinds of document answer four different questions and are kept
separate on purpose. A tutorial holds your hand and is allowed to omit
detail; a how-to assumes you know the basics and just need the recipe; a
reference is exhaustive and dry so you can trust it as the source of
truth; an explanation is discursive and is the only place that argues
about trade-offs. Mixing them (a reference that teaches, a tutorial
that digresses into design rationale) serves none of those needs well,
so each lives in its own file.

The rule applies to the toolkit as much as to the language, which is
why a verb can appear in all four kinds without any of them repeating
another: met once, in passing, while a tutorial builds something; given
as a recipe for one goal in a how-to guide; specified exhaustively
(every flag, every exit code) in the API reference; and argued for,
never merely listed, in the explanation. The use cases stand alongside
as whole worked systems, each holding a `check.sh` that CI runs.

## A 30-second taste

```aontu
# A schema, a default, and data — unified into one result.
port: *8080|integer
host: string
host: "localhost"
```

Unifying the three lines above yields:

```json
{ "host": "localhost", "port": 8080 }
```

The `port` is constrained to be an `integer`, defaults to `8080`, and,
because nothing overrode the default, `8080` is what comes out. `host`
is constrained to a `string` and pinned to `"localhost"`. Conflicting
facts (a second `port: "high"`, say, or a `port: 1.5`) are refused
with a precise error rather than silently resolved: the preferred
branch keeps the kind it names, which is
[argued in the explanation](/docs/explanation#a-preference-is-gated-by-kind-not-by-family).

Try it without writing a file: both implementations ship an `aontu`
command that evaluates a file, reads stdin, or starts a REPL:

<!-- test: run -->
```sh
$ echo 'port: *8080 | integer' | aontu
{
  "port": 8080
}
```

Start with [build a config that checks itself](/docs/tutorial-config),
the first of four [tutorials](/docs/tutorial).

---

# Tutorials

_The four tutorials, what each one builds, and which to read first._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/tutorial.md · Page: https://aontu.dev/docs/tutorial

Four tutorials, each building one thing from an empty directory and
showing the engine's output at every step. Read them in this order if
you are new; take one on its own if its subject is what you need.

- [Build a config that checks itself](/docs/tutorial-config). A service
  config that is schema, defaults, and data in one document, validated
  against a second file with `aontu vet` and explained line by line
  with `aontu model why`. Assumes no aontu at all.
- [Model the system, not the tree](/docs/tutorial-graph). The same config
  as a graph: two views of one service brought into contact, declared
  relations that refuse a cycle, and a schema as deep as its data.
  Assumes the first tutorial.
- [Share a model as a package](/docs/tutorial-package). A schema
  published as a signed package into a directory, acquired by a second
  project, and pinned so that a change to what it means is refused.
  Assumes the first tutorial.
- [From a model to a file tree](/docs/tutorial-generate). A TypeScript
  client computed from a model of its routes, as a tree of folders,
  files, and lines, written to disk with `aontu render` and held
  against the model by its check. Assumes the first tutorial.

Every transcript on these pages is run by `ts/test/docs.test.ts`, so
the output beside a command is what the engine printed.

A tutorial is the wrong shape once you can name what you want. Go to
the [how-to guides](https://github.com/aontu-lang/aontu/blob/main/docs/how-to/) for a task, the
[language reference](/docs/reference-language) or the
[API reference](/docs/reference-api) for a fact,
[unification](/docs/unification) for the operation itself, and the
[explanation](/docs/explanation) for why the engine works as it does.

---

# Tutorial: build a config that checks itself

_Learn aontu from zero by building a config that checks itself, step by step._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/tutorial-config.md · Page: https://aontu.dev/docs/tutorial-config

A service config needs values, constraints, and defaults. In aontu,
you can write all three in one document and combine them through
[unification](/docs/unification).

Build a config, validate data against it, and find which statement set
a value. Each step shows source and output checked by the test suite.
For the reasoning behind the operation, read the
[explanation](/docs/explanation).

## 1. Set up

If aontu is already installed, skip to [§2](#2-objects-are-just-keys-and-values).

### TypeScript

Install and build inside the repo's `ts/` directory:

<!-- test: skip environment setup; npm and node are outside the transcript vocabulary -->
```sh
cd ts
npm install
npm run build      # compiles src + test into dist/ and dist-test/
```

A scratch `play.js` next to `ts/` is enough to call the library:

<!-- test: skip TypeScript API sample; the API is pinned by ts/test/aontu.test.ts -->
```js
const { Aontu } = require('aontu')   // when installed from npm
// from inside this repo: require('./ts/dist/aontu')

const aontu = new Aontu()
console.log(aontu.generate('hello: world'))
// { hello: 'world' }
```

`generate` takes aontu source text and returns a plain JavaScript
value. That is the whole API surface you need today.

### Go

The Go port lives in `go/`:

<!-- test: skip environment setup; go is outside the transcript vocabulary -->
```sh
cd go
go test ./...      # confirms the toolchain works
```

A scratch `main.go`:

<!-- test: skip Go API sample; the API is pinned by go/aontu_test.go -->
```go
package main

import (
	"fmt"
	aontu "github.com/aontu-lang/aontu/go"
)

func main() {
	out, err := aontu.New().Generate("hello: world")
	fmt.Println(out, err)        // map[hello:world] <nil>
}
```

The two implementations accept the same source and produce the same
shape; the parity is pinned by one test suite both implementations
run. The rest of this page shows source and result: run
them in whichever language you keep at hand.

### The `aontu` command

Both implementations also ship an `aontu` command, and this page
writes its CLI moments as transcripts of it. From a clone the command
is `node ts/bin/aontu.js` (or `go run ./cmd/aontu` from inside `go/`);
installed from npm (`npm i -g aontu`) it is plain `aontu`, which is
how the transcripts spell it. Pipe a snippet in:

<!-- test: run -->
```sh
$ echo 'a:1 b:$.a' | aontu
{
  "a": 1,
  "b": 1
}
```

`b` followed a reference to `a` before printing: even a piped
one-liner is fully evaluated. Run `aontu` with no file and you get a
REPL; the [API reference](/docs/reference-api#command-line-interface)
covers both.

Two verbs help before the language does. `aontu init <dir>` writes a
model, an instance of it, and a `check.sh` that asks the four
questions, which is a faster start than an empty file; `aontu explain
<code>` prints the long form of a refusal, so a code in a message
becomes a paragraph with examples.

## 2. Objects are just keys and values

aontu source reads as relaxed JSON (it is parsed by
[`@tabnas/jsonic`](https://github.com/tabnas/jsonic), so quotes,
commas and braces are mostly optional). Plain data is legal on its
own:

```aontu
name: Mercury
order: 1
rocky: true
```

→

```json
{ "name": "Mercury", "order": 1, "rocky": true }
```

No quotes on `Mercury`, no braces, no commas; the output is ordinary
JSON all the same.

Nesting repeats keys with a colon: `a:b:c:1` means
`a: { b: { c: 1 } }`:

<!-- fmt: keep two statements meeting is the lesson -->
```aontu
server: host: localhost
server: port: 8080
```

→

```json
{ "server": { "host": "localhost", "port": 8080 } }
```

The two `server:` lines did not collide. They merged, and that merge
is your first unification.

## 3. Unification: combining facts

Stating two things about the same place combines them. The explicit
operator is `&`; between map keys it happens on its own:

<!-- fmt: keep two statements meeting is the lesson -->
```aontu
server: { host: localhost }
server: { port: 8080 }
```

→

```json
{ "server": { "host": "localhost", "port": 8080 } }
```

Where the statements agree, or one is more specific, unification keeps
the combination. Where they disagree, we want an error, and we get
one:

```aontu
port: 8080
port: 9090
```

→ fails with:

```
[aontu/scalar_value]: Cannot unify values at path $.port

Cannot unify value: 9090 with value: 8080
```

(Trimmed; the real message also quotes both source lines, with a
caret under each.) Combining information can only narrow toward a
single answer or fail loudly. aontu never picks one fact over the
other silently.

## 4. Types as values

A bare type name is a value too: it means "any value of this kind".
Unify it with a concrete value and the value wins, provided it fits:

```aontu
port: integer
port: 8080
```

→

```json
{ "port": 8080 }
```

And when it does not fit:

```aontu
port: integer
port: "high"
```

→ fails with:

```
[aontu/no_scalar_unify]: Cannot unify values at path $.port

Cannot unify value: "high" with value: integer
```

The built-in kinds are `string`, `boolean`, `top` (the catch-all that
admits anything), and the numeric family: `number` covers every
numeric value, over its four leaves `integer`, `float`, `biginteger`
and `bigdecimal`. Say `number` when you mean "some number", and name a
leaf when you mean that leaf: `port: integer` will not accept
`8080.5`. Your config now carries the first piece of its own schema.

## 5. Exact numbers with `0d`

An ordinary aontu number, like an ordinary JSON number, is a binary
floating-point value. For a port or a timeout that is fine. For money
and for large identifiers it is not, because binary cannot represent
every decimal:

```aontu
total: 0.1 + 0.2
```

→

```json
{ "total": 0.30000000000000004 }
```

Prefix the literals with `0d` and the arithmetic is exact, stored as
decimal digits and computed without rounding:

<!-- test: run -->
```sh
$ echo 'total: 0d0.1 + 0d0.2' | aontu
{
  "total": 0.3
}
```

The prefix is source syntax only; the digits generate as an ordinary
JSON number. Whole digits give a `biginteger` (`0d5`); a decimal
point or an exponent gives a `bigdecimal` (`0d19.99`, `0d1e3`).
Neither has a practical size limit.

The same care shows up as a refusal. A literal that cannot be stored
without silently becoming a different number is not stored:

<!-- test: run -->
```sh
$ echo 'id: 9007199254740993' | aontu
[aontu/lossy_integer_literal]: Cannot resolve value at path $.id

This integer literal, 9007199254740993, is not exactly representable in
binary64, so storing it would silently round it to a DIFFERENT
number. aontu refuses rather than corrupts: write it as a `0d`
literal to get the exact integer.
...
$ echo $?
1
```

That value is 2^53+1, just past where doubles start skipping whole
numbers. Take the hint:

<!-- test: run -->
```sh
$ echo 'id: 0d9007199254740993' | aontu
{
  "id": 9007199254740993
}
```

The exact ID survives to the output. One thing to remember when you
write the schema: an exact value is a `biginteger` or a `bigdecimal`,
never an `integer`, so constrain it with the exact leaf (or with
`number`, which admits any numeric leaf).

## 6. Defaults with `*`

Mark a value as a **default** with `*`. A default is used only when
nothing more specific is supplied:

```aontu
port: *8080|integer
```

→

```json
{ "port": 8080 }
```

The `|` is **disjunction**, a choice between alternatives (`8080` or
any `integer`), and the `*` says which branch to take when nothing
forces the choice. Unify a concrete value on top and it wins:

```aontu
port: *8080|integer
port: 9090
```

→

```json
{ "port": 9090 }
```

Now try a float:

```aontu
port: *8080|integer
port: 1.5
```

→ fails with:

```
[aontu/empty]: Cannot unify values at path $.port

Empty disjunction. The disjunction has no valid alternatives.
```

An override must be admitted by one of the branches you wrote, and
`1.5` is a `float`, which `integer` does not admit: why the gate is
this strict is argued in the
[explanation](/docs/explanation#a-preference-is-gated-by-kind-not-by-family).
When any number should be able to win, say so in the branch:

```aontu
port: *8080|number
port: 1.5
```

→

```json
{ "port": 1.5 }
```

`*value | kind` is the shape to remember: the kind you write is the
kind you get. The full rule, including enums with defaults, is in the
[language reference](/docs/reference-language#preference--default-).

## 7. References

Pull a value from elsewhere in the document with a path; `$.` starts
at the root:

```aontu
defaults: timeout: 30
service: timeout: $.defaults.timeout
```

→

```json
{ "defaults": { "timeout": 30 }, "service": { "timeout": 30 } }
```

Change the default once and every reader of the path follows. A
leading `.` is relative to the current object, and `key()` names the
key a value is stored under: a compact way to give records their own
name:

```aontu
users: { alice:id:key() bob:id:key() }
```

→

```json
{ "users": { "alice": { "id": "alice" }, "bob": { "id": "bob" } } }
```

Each record read its own key. The [graph tutorial](/docs/tutorial-graph)
picks this thread up again, where names become identities.

## 8. Templates with `&:` (spread)

A `&:` entry inside a map is a **template** unified into every sibling
key. Declare a shape once and it applies everywhere:

```aontu
servers: { &: { region: *"us-east"|string active: *true|boolean } }
servers: web: region: "eu-west"
servers: db: {}
```

→

```json
{
  "servers": {
    "db":  { "active": true, "region": "us-east" },
    "web": { "active": true, "region": "eu-west" }
  }
}
```

`web` overrode the default region; `db` supplied nothing and took both
defaults; the template itself does not appear in the output. Spreads
work in lists too (`[&: {...}]`), and §11 leans on that form.

## 9. Functions

aontu has a fixed set of built-in functions, and no user-defined ones.
A few of the everyday ones:

```aontu
web: region: "eu-west"
name: upper(mercury) # -> "MERCURY"
slug: lower(Mercury) # -> "mercury"
label: a + b + c # -> "abc"
copy: copy($.web) # deep copy of another node
```

→

```json
{
  "copy":  { "region": "eu-west" },
  "label": "abc",
  "name":  "MERCURY",
  "slug":  "mercury",
  "web":   { "region": "eu-west" }
}
```

`+` concatenates strings and adds numbers; `upper` and `lower` double
as ceiling and floor on numbers, and they keep exact numbers exact
(`upper(0d1.1)` prints `2.0`, a `bigdecimal` ceiling). The rest are
tabulated with tested examples in the
[language reference](/docs/reference-language#functions): bounds,
pattern, and length constraints; generators that build children; and
`join`, which folds a bag into a line of text. You need none of them
today.

## 10. Sealing a shape with `close`

A map is **open** by default: unifying in extra keys is allowed, which
is what lets separate files contribute separate keys. A schema usually
wants the opposite. `close()` seals a shape:

```aontu
point: close({ x:number y:number })
point: { x:1 y:2 }
```

→

```json
{ "point": { "x": 1, "y": 2 } }
```

Add a key the shape does not declare and the document refuses:

```aontu
point: close({ x:number y:number })
point: { x:1 y:2 z:3 }
```

→ fails with:

```
[aontu/closed]: Cannot resolve value at path $.point.z

Cannot add to closed structure.
```

`open()` reverses it. How open a schema should be is a genuine design
dial; [closed values](/docs/reference-language#closed-values-close--open)
has the mechanics, and the
[explanation](/docs/explanation#closed-world-validation-is-a-dial) the
trade-off.

## 11. Putting it together

Time to spend all of it. Here is a single document that is schema,
defaults and data at once: save it as `config.aon`:

<!-- test: scenario service-config -->
<!-- test: file config.aon -->
```aontu
# --- schema + defaults (could live in its own file) ---
service: close({
  name: string
  host: *localhost|string
  port: *8080|integer
  rate: *0d0.01|bigdecimal
  tags: [&: string]
})

# --- environment data merged on top ---
service: { name:api port:9090 rate:0d0.025 tags: [public http] }
```

Run it:

<!-- test: run -->
```sh
$ aontu config.aon
{
  "service": {
    "host": "localhost",
    "name": "api",
    "port": 9090,
    "rate": 0.025,
    "tags": [
      "public",
      "http"
    ]
  }
}
```

Every default is `*value | kind`, the §6 shape, so `port: 9090.5` is
refused rather than accepted. And `tags` says `[&: string]` where
`[string]` might look like enough: a list literal is positional, so
`[string]` constrains element 0 and waves `tags: [public, 7]` through;
the [explanation](/docs/explanation#a-list-literal-is-positional) argues
why it works that way.

With those two spellings in place the schema constrains every field.
Defaults filled `host`, the data supplied the rest, `rate` stayed exact
from `0d0.025` to the printed `0.025`, and `close` kept stray keys
out: one answer, assembled by unification, which would have failed loudly
had anything conflicted.

## 12. Asking the document questions

You have written something that says quite a lot. From here on, stop
reading it and start asking it. `get` prints one slice of the answer:

<!-- test: run -->
```sh
$ aontu model get '$.service.tags' config.aon
[
  "public",
  "http"
]
```

The path is the same `$.`-rooted path §7 used for references: quote
it so the shell leaves the `$` alone.

`why` is the verb to reach for when a value surprises you. It names
every statement that contributed to a path, in source order:

<!-- test: run -->
```sh
$ aontu model why '$.service.port' config.aon
$.service.port = 9090
  1. *8080|integer  config.aon:5:9
  2. 9090  config.aon:11:26
```

Two contributions, and you wrote both: the default with its type, and
the data that beat it, each with the line and column it came from. The
first line is the *whole* written value: a contribution is a
statement, so the `8080` and the `integer` arrive together, as the
single value they were written as. Now ask about `host`, which nothing
overrode:

<!-- test: run -->
```sh
$ aontu model why '$.service.host' config.aon
$.service.host = *"localhost"|string
  1. *"localhost"|string  config.aon:4:9
```

One contribution, still wearing its `*`: the default answered only
because nothing outranked it. `get` has `--keys`, `--types` and
`--canon` views as well, and the rest of the verb surface is
tabulated in the
[API reference](/docs/reference-api#command-line-interface);
[query a path](/how-to/query-a-path) and
[explain a value](/how-to/explain-a-value) put these two to work.

## 13. Validating data with `aontu vet`

Configuration rarely stays in one file: the schema is yours, the data
arrives from somewhere else. Split `config.aon` at its comment. The
schema half becomes `service.aon`:

<!-- test: file service.aon -->
```aontu
service: close({
  name: string
  host: *localhost|string
  port: *8080|integer
  rate: *0d0.01|bigdecimal
  tags: [&: string]
})
```

and the data half becomes `prod.aon`:

<!-- test: file prod.aon -->
```aontu
service: { name:api port:9090 rate:0d0.025 tags: [public http] }
```

`vet` asks whether a data document holds against a schema document:

<!-- test: run -->
```sh
$ aontu vet service.aon prod.aon
verdict: valid
```

Now a second environment arrives, `staging.aon`, written by someone
else:

<!-- test: file staging.aon -->
```aontu
service: { name:search port:8100 tags: [internal 3] }
```

Vet it:

<!-- test: run -->
```sh
$ aontu vet service.aon staging.aon
verdict: invalid

$.service.tags.1: no_scalar_unify [conflict]
  [aontu/no_scalar_unify]: Cannot unify values at path $.service.tags.1
  data: staging.aon:1:50 (3)
  schema: service.aon:6:13 (string)
$ echo $?
1
```

Read the finding from the top. The path `$.service.tags.1` is exactly
where the trouble is: element 1 of the list, the `3`. Then **two
sites**, because a conflict is always between two statements and neither
one owns the blame: `data` is what arrived (`3`, line 4, column 20 of
`staging.aon`) and `schema` is what it had to [meet](/docs/unification)
(`string`, line 6, column 16 of `service.aon`). Every finding is sited
on both sides, so you never guess which file to open. And the exit code,
`1`, is the verdict class: a CI job needs nothing else.

The `3` was meant to be a tier name. Write `staging.aon` again, saying
so:

<!-- test: file staging.aon -->
```aontu
service: { name:search port:8100 tags: [internal tier3] }
```

<!-- test: run -->
```sh
$ aontu vet service.aon staging.aon
verdict: valid
```

Notice `staging.aon` never mentions `host` or `rate` and passes
anyway: the schema's defaults stand in. To see what the service
actually gets, unify the two files: a document that loads both is all
it takes. Write `stack.aon`:

<!-- test: file stack.aon -->
```aontu
@"./service.aon"
@"./staging.aon"
```

<!-- test: run -->
```sh
$ aontu stack.aon
{
  "service": {
    "host": "localhost",
    "name": "search",
    "port": 8100,
    "rate": 0.01,
    "tags": [
      "internal",
      "tier3"
    ]
  }
}
```

`@"file"` loads a source file and unifies it in place, which is all
"multi-file" means here;
[split a model across files](/how-to/split-a-model-across-files)
grows the idea into versioned, vendored dependencies.

`vet` has a third verdict, and it is the one that stops the loop
calling an unfinished document valid. Delete the `name` line from `staging.aon`:

<!-- test: file staging.aon -->
```aontu
service: { port:8100 tags: [internal tier3] }
```

<!-- test: run -->
```sh
$ aontu vet service.aon staging.aon
verdict: incomplete

$.service.name: mapval_required [incomplete]
  [aontu/mapval_required]: Cannot resolve value at path $.service.name
  schema: service.aon:2:9 (string)
$ echo $?
3
```

Nothing contradicts anything; the document is simply not finished yet.
aontu has kept "wrong" and "unfinished" apart all through this page,
and `vet` keeps them apart in its exit codes too: one code per
verdict class, which is what makes it usable as a gate. The codes, the
JSON and SARIF report forms and `--watch` are specified under
[`aontu vet`](/docs/reference-api#aontu-vet), and
[validate in CI](/how-to/validate-in-ci) is the recipe.

That is the loop the whole verb surface exists for: **emit** a
document, **vet** it against the truth it has to satisfy, and when it
fails, let the two sites and `aontu model why` say where to **repair** it.
You have now run it once by hand, which matters, because repair is the
step you will eventually hand to a command: `aontu model set` rewrites
overlay files under exactly these rules, and
[change a pinned value](/how-to/change-a-pinned-value) shows what it
will and will not touch.

## Where to go next

Your config is a tree. Real systems are graphs: services that depend
on each other, ownership that must not cycle, schemas that contain
themselves. The [graph tutorial](/docs/tutorial-graph) is the second half
of this one: identity, relations, reachability and recursion, on the
engine you just used. When the document is ready to leave your
repository, [share a model as a package](/docs/tutorial-package) pins it
for whoever imports it, and [from a model to a file
tree](/docs/tutorial-generate) computes source files from it. The
[tutorials index](/docs/tutorial) lists all four.

For a task you already have, go straight to its guide:

-  **Run, embed and integrate**: [call from
  TypeScript](/how-to/call-from-typescript), [call from
  Go](/how-to/call-from-go), [read a conflict
  error](/how-to/read-a-conflict-error)
-  **Templates, defaults and composition**: [provide
  defaults](/how-to/provide-defaults), [apply a template to many
  keys](/how-to/apply-a-template-to-many-keys)
-  **Schemas and constraints**: [constrain list
  elements](/how-to/constrain-list-elements), [make a field
  optional](/how-to/make-a-field-optional)
-  **Query, explain and change**: [query a path](/how-to/query-a-path),
  [explain a value](/how-to/explain-a-value)
-  **Validate and evolve**: [validate in CI](/how-to/validate-in-ci),
  [gate schema changes](/how-to/gate-schema-changes)
-  **Modules and multi-file**: [split a model across
  files](/how-to/split-a-model-across-files)

Every rule and edge case is in the
[language reference](/docs/reference-language); the command and both APIs
are in the [API reference](/docs/reference-api); the reasons are in the
[explanation](/docs/explanation).

---

# Tutorial: model the system, not the tree

_Model a system with identities, declared relations, and recursive schemas._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/tutorial-graph.md · Page: https://aontu.dev/docs/tutorial-graph

At 04:11 the ledger database went down, and at 04:12 the payments
service went with it: a dependency that was real in production and
recorded nowhere. Every config file involved was valid all night.

The [first tutorial](/docs/tutorial-config) left you with a config that is
schema, defaults and data in one document, describing each service
completely, and each service alone. Nothing in it can say "these
two files describe the same service", or "this feeds that, never in
a loop", or "a chain of these, as long as it needs to be". This
tutorial adds that layer: bringing two views into contact,
declared relations (`rel` and the graph atoms), and recursive
schemas. Each is a
statement the engine checks: "payments depends on ledger" becomes
something that can refuse.

Run snippets as before (from a clone, `node ts/bin/aontu.js`
stands in for `aontu`). Every output here is the engine's own.

## 1. Two views of one service

The catalog team records what `payments` *is*; the platform team records
what actually *runs*. Unification is path-aligned, so a claim at
`$.catalog.payments` never [meets](/docs/unification) a claim at
`$.deploy.eu1.payments`: a forked tier stays confident in both files,
and one of them is wrong.

Bringing the two into contact is a reference. Here are the two
views, trimmed from
[use-case 01](/use-cases/01-service-catalog) and inlined into
one document:

```aontu
catalog: payments: { owner:"team-payments" tier:1 }

deploy: eu1: payments: $.catalog.payments & {
  image: "acme/payments:2.14.1"
  replicas: 6
}
```

→

```json
{"catalog": {"payments": {"owner": "team-payments", "tier": 1}},
 "deploy": {"eu1": {"payments": {"image": "acme/payments:2.14.1",
   "owner": "team-payments", "replicas": 6, "tier": 1}}}}
```

The deploy view now holds the whole service, and the two claims
about `tier` have met. A disagreement between them is a located
error rather than a silent fork:

<!-- test: run -->
```sh
$ echo 'catalog: pay: {tier:1} deploy: pay: $.catalog.pay & {tier:2}' | aontu
[aontu/scalar_value]: Cannot unify values at path $.deploy.pay.tier
...
$ echo $?
1
```

A reference is **directional**: `deploy` is narrowed by the catalog,
and the catalog is not changed by the deploy. That direction is
deliberate. The alternative (a global name both files declare, with
every node carrying it merged into every other) reads well until you
mount the same model twice, at which point the two instances are one
entity and the second one's overrides are contradictions. The
[reference](/docs/reference-language#linking-the-tree-is-the-namespace)
has the argument; the practical consequence is that a model file is
reusable, which §2 relies on.

## 2. Relations: an edge you can trust

Now the connections. We model an ETL pipeline of three jobs
(extract feeds transform, transform feeds load), trimmed from
[use-case 12](/use-cases/12-relations), where the four-job
original lives under test.

<!-- test: scenario pipeline -->

The vocabulary sits in `spec.aon` (`hide()` marks it schema:
present for unification, absent from output):

<!-- test: file spec.aon -->
```aontu
spec: hide({
  Job: { kind:job feeds?:rel($.spec.JobShape) }

  JobShape: kind: job
})
```

`rel(t)` turns the field's strings into **tree addresses**: each
must name a node in this evaluation, and the type `t` flows into
every target, so an edge landing on something that is not a job
refuses at the edge. The `?` makes the key
[optional](/docs/reference-language#optional-keys-): a job with
nothing downstream writes nothing. (`JobShape` is a thin stand-in:
a self-typed `rel($.spec.Job)` inside `Job` is still in design.)

The topology sits in `pipeline.aon`: plain lists of addresses, one
of which carries a typo:

<!-- test: file pipeline.aon -->
```aontu
pipeline: jobs: { &: $.spec.Job }

pipeline: jobs: extract: feeds: [path($.pipeline.jobs.tranform)]
pipeline: jobs: transform: feeds: [path($.pipeline.jobs.load)]
pipeline: jobs: load: {}
```

A two-line root, `model.aon`, joins them:

<!-- test: file model.aon -->
```aontu
@"./spec.aon"
@"./pipeline.aon"
```

<!-- test: run -->
```sh
$ aontu model.aon
[aontu/rel_unresolved]: Cannot refer value at path $.pipeline.jobs.extract.feeds.0
...
$ echo $?
1
```

Without `rel()`, that address is a perfectly good string and this
pipeline silently loses everything downstream of extract. With it,
the typo is a located refusal, and existence is decided inside the
evaluation: an address resolves, or the document refuses. Correct
the line in `pipeline.aon`:

<!-- test: file pipeline.aon -->
```aontu
pipeline: jobs: { &: $.spec.Job }

pipeline: jobs: extract: feeds: [path($.pipeline.jobs.transform)]
pipeline: jobs: transform: feeds: [path($.pipeline.jobs.load)]
pipeline: jobs: load: {}
```

<!-- test: run -->
```sh
$ aontu model.aon
...
        "feeds": [
          "$.pipeline.jobs.transform"
        ],
...
```

### A constraint held on every address: `re()`

Acme's convention says a job may only feed another **job**: not a
raw dump, which lives elsewhere in the tree. The addresses say where
each target is, so the convention is a rule about the address. Write
it into the declaration, in `spec.aon`:

<!-- test: file spec.aon -->
```aontu
spec: hide({
  Job: {
    kind: job
    feeds?: rel($.spec.JobShape) & re("^\\$\\.pipeline\\.jobs\\.")
  }

  JobShape: kind: job
})
```

A constraint beside `rel()` constrains the **address string**, and
it is held onto every element of the list. To watch it work, write
a change request: a file that includes the model and layers a
delta on at the path it applies to. Propose a new edge, `raw.aon`:

<!-- test: file raw.aon -->
```aontu
@"./model.aon"

pipeline: {
  dumps: raw: kind: job
  jobs: extract: feeds: [
    path($.pipeline.jobs.transform)
    path($.pipeline.dumps.raw)
  ]
}
```

<!-- test: run -->
```sh
$ aontu raw.aon
[aontu/constraint]: Cannot unify values at path $.pipeline.jobs.extract.feeds.1
...
 Cannot unify value: re("^\\$\\.pipeline\\.jobs\\.") with value: path($.pipeline.dumps.raw)
...
$ echo $?
1
```

`$.pipeline.dumps.raw` resolves, and it is even shaped like a job, but it
is not *under* `jobs`, the held `re()` refuses the address, and the edge
never exists. Conventions like this usually live in a wiki. This one is
schema.

### The graph atoms: `acyclic()` and `inverse()`

Two facts about the pipeline concern the whole edge set: no job may
feed itself at any remove, and every fed job should name its
feeders back. Declare both at the field, and give `fedBy` the same
checked treatment, in `spec.aon`:

<!-- test: file spec.aon -->
```aontu
spec: hide({
  Job: {
    kind: job
    feeds?: rel($.spec.JobShape) & acyclic() & inverse(fedBy)
    fedBy?: rel($.spec.JobShape)
  }

  JobShape: kind: job
})
```

The `feeds?:` line is now the entire relation: checked addresses,
endpoint type, naming rule, acyclicity, inverse. During unification
the atoms only *register* the declaration: one more edge can flip
either property, so the verdict waits for generation, where every
edge is known ([the rule](/docs/reference-language#declared-relations)).
And `inverse(fedBy)` checks the mirror rather than writing it for
you, so the data states both directions, in `pipeline.aon`:

<!-- test: file pipeline.aon -->
```aontu
pipeline: jobs: { &: $.spec.Job }

pipeline: jobs: extract: feeds: [path($.pipeline.jobs.transform)]
pipeline: jobs: transform: {
  fedBy: [path($.pipeline.jobs.extract)]
  feeds: [path($.pipeline.jobs.load)]
}
pipeline: jobs: load: fedBy: [path($.pipeline.jobs.transform)]
```

<!-- test: run -->
```sh
$ aontu model.aon
{
  "pipeline": {
    "jobs": {
      "extract": {
        "feeds": [
          "$.pipeline.jobs.transform"
        ],
        "kind": "job"
      },
...
      "transform": {
        "fedBy": [
          "$.pipeline.jobs.extract"
        ],
        "feeds": [
          "$.pipeline.jobs.load"
        ],
        "kind": "job"
      }
    }
  }
}
$ aontu relations model.aon
verdict: pass
```

The links generate as the plain strings the author wrote; the
machinery stays in the hidden vocabulary, and the data keeps its
JSON shape. The second command, the `relations` verb, reports the
same verdict without generating anything.

### Refusing a cycle

A change request makes load feed extract, and its author is careful: the
inverse entry is dutifully written too. Save it as `cycle.aon`:

<!-- test: file cycle.aon -->
```aontu
@"./model.aon"

pipeline: jobs: load: feeds: [path($.pipeline.jobs.extract)]
pipeline: jobs: extract: fedBy: [path($.pipeline.jobs.load)]
```

<!-- test: run -->
```sh
$ aontu cycle.aon
[aontu/relation_cycle]: Cannot relate value at path $.pipeline.jobs.extract.feeds
...
$ echo $?
1
$ aontu relations cycle.aon
verdict: fail

$.pipeline.jobs.extract.feeds.0  feeds: cycle $.pipeline.jobs.extract -> $.pipeline.jobs.transform -> $.pipeline.jobs.load -> $.pipeline.jobs.extract
$ echo $?
1
```

The care did not help, which is the point: acyclicity is a property
of the whole graph, and no local diligence satisfies it. Generation
refuses at an edge on the loop; the verb names the loop itself,
closing back on the first node.

### Refusing a missing inverse

A new job taps the transform output, and nobody records the feeder
on its `fedBy`. The `change` list restates `job_load` because lists
unify positionally (the first tutorial's §11 rule). Save it as
`metrics.aon`:

<!-- test: file metrics.aon -->
```aontu
@"./model.aon"

pipeline: jobs: {
  metrics: fedBy: []
  transform: feeds: [path($.pipeline.jobs.load) path($.pipeline.jobs.metrics)]
}
```

<!-- test: run -->
```sh
$ aontu relations metrics.aon
verdict: fail

$.pipeline.jobs.transform.feeds.1  feeds: $.pipeline.jobs.metrics does not list $.pipeline.jobs.transform under fedBy
$ echo $?
1
```

The exact missing entry is named, at the position that states the
edge.
Add `$.pipeline.jobs.transform` to the new job's `fedBy` and the
model passes.

### Reachability

If extract dies, does load stop? That question needs the closure of
the edge set, and it has its own verb:

<!-- test: run -->
```sh
$ aontu reaches $.pipeline.jobs.extract $.pipeline.jobs.load --relation feeds model.aon
verdict: reaches

$.pipeline.jobs.extract -> $.pipeline.jobs.transform -> $.pipeline.jobs.load
$ aontu reaches $.pipeline.jobs.load $.pipeline.jobs.extract --relation feeds model.aon
verdict: unreachable

$.pipeline.jobs.load does not reach $.pipeline.jobs.extract
$ echo $?
1
```

The answer is the path, because the path is what an operator acts
on; a "no" carries none and exits `1`, so a policy like "nothing in
the public tier may reach the ledger" can be a CI gate. One
caution: this model writes both directions, so leaving off
`--relation` lets load "reach" extract by walking `fedBy` upstream. A directional question names its relation.

The [check-relations](/how-to/check-relations) and
[query-reachability](/how-to/query-reachability) guides turn
these verbs into CI recipes; the
[API reference](/docs/reference-api#aontu-relations) lists every flag
and exit code.

## 3. A schema as deep as the data

An approval chain is a step that may be followed by another step,
and the depth belongs to each policy: a schema that hard-codes
three levels is wrong the day someone needs four. Here is the whole
vocabulary, trimmed from
[use-case 13](/use-cases/13-recursive-schema), as `schema.aon`:

<!-- test: scenario approvals -->
<!-- test: file schema.aon -->
```aontu
spec: hide({
  Step: {
    approver: string & re("^[a-z]+@acme[.]example$")
    decision: *pending|pending|approved|rejected
    then?: $.spec.Step
  }
})
```

Look at the last field. `$.spec.Step`, written *inside* `Step`, is
a reference to the value being defined, and it simply means the
fixpoint: a `Step` whose tail is a `Step`, by this very definition,
all the way down. No marker, no depth parameter, no unrolled
copies. Write a three-level chain against it, as `chain.aon`:

<!-- test: file chain.aon -->
```aontu
@"./schema.aon"

payments: $.spec.Step & {
  approver: "lead@acme.example"
  decision: approved
  then: {
    approver: "cfo@acme.example"
    decision: approved
    then: approver: "audit@acme.example"
  }
}
```

<!-- test: run -->
```sh
$ aontu chain.aon
{
  "payments": {
    "approver": "lead@acme.example",
    "decision": "approved",
    "then": {
      "approver": "cfo@acme.example",
      "decision": "approved",
      "then": {
        "approver": "audit@acme.example",
        "decision": "pending"
      }
    }
  }
}
```

The leaf never states a `decision`, and the ranked default supplied
`"pending"` three levels down, from a schema one reference deep.
Mechanically, the self-reference leaves a *residual* (a value still
waiting for information) at each `then`, and the residual expands
one level per meet with concrete data: the checks descend exactly
as far as the chain does, and stop. Data is finite, so evaluation
terminates.

### The guard is the `?`

The engine never analyses a schema for well-foundedness; the data
decides, and what ends the expansion is the `?` on `then?:`, where
the data stops, the optional key drops. Spell the tail required and
no finite chain can satisfy it. Try it, as `strict.aon`:

<!-- test: file strict.aon -->
```aontu
strict: hide({ Step: { approver:string then:$.strict.Step } })

doc: $.strict.Step & {
  approver: "lead@acme.example"
  then: approver: "cfo@acme.example"
}
```

<!-- test: run -->
```sh
$ aontu strict.aon
[aontu/recursion_unexpanded]: Cannot recurse value at path $.doc.then.then
...
$ echo $?
1
```

The schema itself is accepted (it is a perfectly good fixpoint),
but every step demands a next step, so generation refuses at
`$.doc.then.then`, the exact position where this document ran out.
A required tail is a schema for documents that cannot exist.

### Vetting a chain you did not write

The chains that matter arrive from outside (an approval tool, an
agent) as plain JSON. Here is one with no aontu syntax in it at
all, `review.json`:

<!-- test: file review.json -->
```json
{
  "approver": "lead@acme.example",
  "decision": "approved",
  "then": {
    "approver": "cfo@acme.example",
    "decision": "pending"
  }
}
```

`vet --at` anchors the check at the recursive definition:

<!-- test: run -->
```sh
$ aontu vet --at '$.spec.Step' schema.aon review.json
verdict: valid
```

Now a chain that smuggles in an outside approver one level down, as
`outside.json`:

<!-- test: file outside.json -->
```json
{
  "approver": "lead@acme.example",
  "decision": "approved",
  "then": {
    "approver": "EXTERNAL@other.example",
    "decision": "maybe"
  }
}
```

<!-- test: run -->
```sh
$ aontu vet --at '$.spec.Step' schema.aon outside.json
verdict: invalid

$.spec.Step.then.approver: constraint [conflict]
  [aontu/constraint]: Cannot unify values at path $.spec.Step.then.approver
  expected: re("^[a-z]+@acme[.]example$")
  actual:   "EXTERNAL@other.example"
  data: outside.json:5:17 ("EXTERNAL@other.example")
  schema: schema.aon:3:24 (re("^[a-z]+@acme[.]example$"))
...
$ echo $?
1
```

The finding is one level down, sited on both sides (the data's line
in `outside.json`, the schema's line in `schema.aon`), and the
invented `decision` is refused right beside it. The depth cost
nothing to write, and there is no blind spot at level fifty either!

The [define-a-recursive-schema](/how-to/define-a-recursive-schema)
guide adds what a vocabulary needs next: canonical form, and the
hash that pins a recursive schema as one string.

## Where to go next

You can now hand the engine plain-looking files and get back
refusals for a forked fact, a dangling name, a dependency loop, an
unmirrored edge, and a malformed chain at any depth: a decent set
of questions to have asked about payments and ledger before 04:11.

- The live models this page trimmed:
  [use-case 12, relations](/use-cases/12-relations) and
  [use-case 13, recursive schema](/use-cases/13-recursive-schema),
  each with a `check.sh` driving every refusal shown here and more.
- Gating a repo on the checks:
  [check relations](/how-to/check-relations),
  [query reachability](/how-to/query-reachability),
  [define a recursive schema](/how-to/define-a-recursive-schema).
- The rules in full:
  [linking](/docs/reference-language#linking-the-tree-is-the-namespace),
  [checked links](/docs/reference-language#checked-links-refert),
  [declared relations](/docs/reference-language#declared-relations),
  [recursive references](/docs/reference-language#recursive-references-fixpoints).
- Why a checked link refuses where `owl:sameAs` silently merged, and why
  the graph checks are verbs: the [explanation](/docs/explanation).
- The other tutorials: [share a model as a
  package](/docs/tutorial-package) gives this model a version and a hash
  for another project to import, [from a model to a file
  tree](/docs/tutorial-generate) computes source files from it, and the
  [tutorials index](/docs/tutorial) lists all four.

---

# Tutorial: share a model as a package

_Publish a schema as a package, acquire it from another project, and watch the pin refuse a change to what it means._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/tutorial-package.md · Page: https://aontu.dev/docs/tutorial-package

A schema two projects need gets copied into both, and from that moment
there are two schemas. This tutorial takes one model out of its
repository and gives it a version, a signature and a hash, so the
second project imports it instead of copying it, and a later change to
what it means is refused rather than absorbed.

Everything here runs on one machine, with no network: the package
repository is a directory. The one step that needs a listening process
is described in [§9](#9-where-the-network-comes-in) and left to its
guide.

Commands are written as `aontu`; from a clone, `node ts/bin/aontu.js`
stands in. Every result on this page is the engine's own.

## 1. The model two projects need

Money has two fields and one rule that should exist in exactly one
place. Save this as `rates/rates.aon`:

<!-- test: scenario share-a-package -->
<!-- test: file rates/rates.aon -->
```aontu
currency: string & re("^[A-Z]{3}$")
amount: bigdecimal
```

`re` bounds a string by a pattern, and `bigdecimal` is the exact
decimal leaf from
[§5 of the first tutorial](/docs/tutorial-config#5-exact-numbers-with-0d):
a price is not a `float`. A document of your own can be checked against
it. Save one as `price.aon`:

<!-- test: file price.aon -->
```aontu
currency: "eur"
amount: 0d19.99
```

and [vet](/docs/reference-api#aontu-vet) it:

<!-- test: run -->
```sh
$ aontu vet rates/rates.aon price.aon
verdict: invalid

$.currency: constraint [conflict]
  [aontu/constraint]: Cannot unify values at path $.currency
  expected: re("^[A-Z]{3}$")
  actual:   "eur"
  data: price.aon:1:11 ("eur")
  schema: rates/rates.aon:1:20 (re("^[A-Z]{3}$"))
$ echo $?
1
```

That is the value of the rule and the reason to share it: a lowercase
currency code is caught in one line, in whichever project asks. Fix the
data, in `price.aon`:

<!-- test: file price.aon -->
```aontu
currency: "EUR"
amount: 0d19.99
```

<!-- test: run -->
```sh
$ aontu vet rates/rates.aon price.aon
verdict: valid
```

## 2. Make it a package

A **module** is what an import names. A **package** is what you
publish: a versioned archive of one or more modules. Both words are
about to appear, and they are not synonyms.

A package declares itself in a `pkg.aon` beside its sources. Write
`rates/pkg.aon`:

<!-- test: file rates/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/rates" version:"1.0.0" main:"rates.aon" }
publish: public
```

Four facts, and no more: the `path` importers will write, the `version`
this release carries, the `main` file an import of the bare path
resolves to, and `publish: public`, which is the package saying it may
leave the machine. The path's first segment carries a dot, which is
what separates a module import from a file path.

## 3. Publish it into a directory

A publish is signed, so there is a key first. `aontu pkg keygen` mints
one and prints the public half, which is the id a consumer names:

<!-- test: run -->
```sh
$ aontu pkg keygen key.pem
...
```

Keep `key.pem` where a build job can read it and nobody else can. Now
publish, into a directory called `repo`. Without `--yes` every check
runs and nothing is sent:

<!-- test: run -->
```sh
$ aontu publish --key key.pem --to repo rates
verdict: dry-run
corp.example/schemas/rates 1.0.0 public
archive: sha256:171e30a516146c364a20ddb7291cf9c9856fecb6b6223f5f29e8cdfb63096dcf (2 files, 353 bytes)
module: corp.example/schemas/rates rates.aon aon1-vO_nsrLAdRBPpq8Vi8G_FgDDMWmoVGRjm6eZThS0QHA
file: pkg.aon sha256:0f2e3cb9456aede3ec8e9fa99e5a1dd2c4bb5376b7ca23871e2f6aa9516773c0 92
file: rates.aon sha256:fed42fa726c3df4155c84dd35e690383b8a1a07d7f05a0544168a7f487c524d2 55
...
dry run: nothing sent (add --yes)
```

Two of those lines are the ones to keep your eye on. `archive` is the
digest of the bytes; `module` is the **canon-hash**, `aon1-…`, which is
what the module MEANS after evaluation. They answer different
questions, and both are about to be pinned. Send it:

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo rates
verdict: sent
...
sent
```

`repo` now holds the layout a consumer reads:

```
repo/
  pkg/corp.example/schemas/rates/
    @latest
    @v/
      list
      1.0.0.zip        the archive
      1.0.0.manifest   what it holds, file by file, and what it means
      1.0.0.sig        the proof, over the manifest
  advisory/corp.example/schemas/rates.aon
```

Nothing in that directory was evaluated by the repository, and a
consumer trusts none of it for more than availability: every pin is
recomputed on the way in.

## 4. Take it on, in another project

The consumer is a second project, beside the first. Its `checkout/pkg.aon`
names itself and what it depends on:

<!-- test: file checkout/pkg.aon -->
```aontu
pkg: { path:"corp.example/checkout" main:"main.aon" }
dep: "corp.example/schemas/rates": v: "1.0.0"
```

The `v` is a **minimum**, not a pin: the lockfile pins, and §5 writes
it. The entry document imports the module and adds its own facts.
Write `checkout/main.aon`:

<!-- test: file checkout/main.aon -->
```aontu
price: @"corp.example/schemas/rates"
price: { currency:"EUR" amount:0d19.99 }
```

Those two lines are what the exercise is for: the schema arrives by
import and the data meets it in the [ordinary way](/docs/unification).
Nothing has been received yet, though, and `aontu pkg tidy`, the
resolve step that fetches nothing, says so:

<!-- test: run -->
```sh
$ aontu pkg tidy checkout
verdict: missing
corp.example/schemas/rates: not fetched (run: aontu sync)
$ echo $?
1
```

No lockfile was written: a partial lock would claim a closure that was
never resolved. The hint names the arrangement in
[§9](#9-where-the-network-comes-in), where a repository answers; here
§5 puts the copy in place by hand instead.

## 5. Vendor the tree, and lock what it means

The consumer's copy of a package lives in its own project, under
`aontu_meta/vendor/<package path>/`, one directory per path segment.
Put the package's source tree there. Its
`checkout/aontu_meta/vendor/corp.example/schemas/rates/pkg.aon`:

<!-- test: file checkout/aontu_meta/vendor/corp.example/schemas/rates/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/rates" version:"1.0.0" main:"rates.aon" }
publish: public
```

and its
`checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon`:

<!-- test: file checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon -->
```aontu
currency: string & re("^[A-Z]{3}$")
amount: bigdecimal
```

That is a copy and nothing more: `cp -r` of the published tree. §9 is
where a repository does the copying for you. Either way, `sync` is what
turns a copy into a dependency:

<!-- test: run -->
```sh
$ aontu sync checkout
verdict: ok
corp.example/schemas/rates 1.0.0 aon1-vO_nsrLAdRBPpq8Vi8G_FgDDMWmoVGRjm6eZThS0QHA
```

That hash is the one the publish printed. `sync` resolved the closure,
evaluated the module on its own, and wrote one canonical line to
`checkout/aontu_meta/pkg-lock.aon`:

```
# pkg-lock.aon (generated by `aontu sync`; do not edit)
{"lock":{"corp.example/schemas/rates":{"archive":"sha256:171e30a516146c364a20ddb7291cf9c9856fecb6b6223f5f29e8cdfb63096dcf","canon":"aon1-vO_nsrLAdRBPpq8Vi8G_FgDDMWmoVGRjm6eZThS0QHA","v":"1.0.0"}}}
```

One line, JSON-parseable, and diffable like code. Commit it together
with `aontu_meta/vendor/`: that pair is the build, on a machine with no
network.

## 6. Evaluate with nothing but the project

<!-- test: run -->
```sh
$ aontu checkout/main.aon
{
  "price": {
    "amount": 19.99,
    "currency": "EUR"
  }
}
```

The import resolved from the vendor tree, the pattern held, and
`0d19.99` reached the output exactly. Ask why the package is in the
closure and the answer is a path of requirements:

<!-- test: run -->
```sh
$ aontu why corp.example/schemas/rates checkout
verdict: ok
corp.example/checkout -> corp.example/schemas/rates
```

One hop, because the project asked for it directly. A package pulled in
by a dependency of a dependency prints the chain that reaches it.

## 7. The pin earns its keep

Here is the part a copied file cannot do. Someone relaxes the vendored
schema, perhaps to get a build through. Rewrite
`checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon`:

<!-- test: file checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon -->
```aontu
currency: string
amount: bigdecimal
```

The data still satisfies it, so nothing about the document is wrong.
Evaluate anyway:

<!-- test: run -->
```sh
$ aontu checkout/main.aon
module integrity: corp.example/schemas/rates expected aon1-vO_nsrLAdRBPpq8Vi8G_FgDDMWmoVGRjm6eZThS0QHA got aon1-wixJdyL2g90c1HaWaoBKBpHA6da7Hn-MEikz6LW-BVI
$ echo $?
1
```

Both hashes are named: the meaning that was reviewed, and the meaning
the store holds now. `aontu pkg verify` asks the same question of the
bytes first, and never reaches the meaning here because the archive
digest already disagrees:

<!-- test: run -->
```sh
$ aontu pkg verify checkout
verdict: mismatch
corp.example/schemas/rates: pinned archive sha256:171e30a516146c364a20ddb7291cf9c9856fecb6b6223f5f29e8cdfb63096dcf but the store holds sha256:62be1cd19a5db54c374a3b0539ec0973ae66bbb0b5d2411f28fbba3eb7a1e716
$ echo $?
1
```

That is the command for a build job: it recomputes every pin, writes
nothing, and exits `1` on any disagreement. Put
`checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon`
back:

<!-- test: file checkout/aontu_meta/vendor/corp.example/schemas/rates/rates.aon -->
```aontu
currency: string & re("^[A-Z]{3}$")
amount: bigdecimal
```

<!-- test: run -->
```sh
$ aontu pkg verify checkout
verdict: ok
corp.example/schemas/rates: verified
```

Be precise about what the canon-hash protects. It is taken over what
the module MEANS, so comments, whitespace, and a rewrite that canons
to the same value all keep it, deliberately. The bytes are the
`archive` pin's job, and it is the stricter of the two: a comment
added to a vendored file keeps the meaning and still fails
`aontu pkg verify`, which is why a vendored tree is re-vendored rather
than edited.

## 8. The next version is gated on this one

Back in the package. Currencies differ in how many decimal places they
carry, so `rates.aon` gains a field. Rewrite `rates/rates.aon`:

<!-- test: file rates/rates.aon -->
```aontu
currency: string & re("^[A-Z]{3}$")
amount: bigdecimal
precision?: integer
```

The `?` makes the key optional, so a document that never mentions it
still holds. Bump the version in `rates/pkg.aon`:

<!-- test: file rates/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/rates" version:"1.0.1" main:"rates.aon" }
publish: public
```

and publish. `publish` fetches the highest version the repository
already holds and compares the two:

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo rates
verdict: sent
corp.example/schemas/rates 1.0.1 public
...
against: corp.example/schemas/rates 1.0.0
...
sent
```

`against` names what it was gated on. Now make the same field
required, which is the edit that feels like a tidy-up and is not.
Rewrite `rates/rates.aon`:

<!-- test: file rates/rates.aon -->
```aontu
currency: string & re("^[A-Z]{3}$")
amount: bigdecimal
precision: integer
```

with `rates/pkg.aon` at a new minor version:

<!-- test: file rates/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/rates" version:"1.1.0" main:"rates.aon" }
publish: public
```

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo rates
verdict: breaking
corp.example/schemas/rates 1.1.0 public
...
$.precision: the general value requires this key; the specific value makes it optional, so instances without it are admitted
...
$ echo $?
1
```

Refused, at the key it refuses on, and nothing was written. The two
names in that message are the sides of the question: the candidate is
the general value, the version already published is the specific one,
and a release ships only when the candidate admits every instance its
predecessor did. Every 1.0.1 consumer with no `precision` would stop
evaluating, and no version number lifts the gate: a break ships as a
new package path, and [modules](/docs/reference-language#modules) has the
`moved` declaration that retires the old one.

Meanwhile `checkout` is untouched at 1.0.0, because its lockfile says
so. `aontu get corp.example/schemas/rates@1.0.1` is how it moves, when
it chooses to, and it needs a repository to reach: the arrangement in
[§9](#9-where-the-network-comes-in), or a fresh vendored copy and
`aontu sync`.

## 9. Where the network comes in

Every command above ran against a directory, which is why this page
needs none. A colleague cannot read your directory, though, so the
arrangement between two machines serves it instead: `aontu pkg serve
repo` serves the same bytes over HTTP on a loopback address and runs
until interrupted, which is the one thing a transcript cannot show. A
consumer then names the base and the signer it accepts, in its own
`pkg.aon`:

<!-- test: skip the consumer of a served repository; §5 runs the vendored form -->
```aontu
pkg: { path:"corp.example/checkout" main:"main.aon" }
dep: "corp.example/schemas/rates": v: "1.0.0"

repo: base: ["http://127.0.0.1:8017"]
repo: trust: "corp.example/*": { signer:"ed25519:…" inclusion:none }
```

and `aontu sync` fetches the archive, the manifest and the proof,
checks the proof, then the bytes, then the meaning, and refuses at the
first that does not hold. What it writes is the lockfile and the
vendor tree from §5, with one pin more: `manifest`, the digest of what
the publisher signed. The rest of the page is unchanged, which is the
reason it was worth learning in this order.

Evaluation never reaches the network in either arrangement. An `@"…"`
import resolves from the vendor tree and a local cache, and from
nowhere else.

## Where to go next

Your model is now a thing with a version, and the two questions that
follow are what to pin it against and who may move it:

- The recipes, each one task: [publish a
  package](/how-to/publish-a-package) with a served repository and a
  trust stanza, [vendor a dependency
  closure](/how-to/vendor-a-dependency-closure) for the frozen CI
  form, [vendor a module by hand](/how-to/vendor-by-hand) for a
  package that was never published, and [gate schema
  changes](/how-to/gate-schema-changes) for the compatibility query
  §8 ran, asked of two documents rather than two versions.
- The rules in full: [`aontu sync`](/docs/reference-api#aontu-sync),
  [`aontu publish`](/docs/reference-api#aontu-publish),
  [`aontu pkg`](/docs/reference-api#aontu-pkg), and
  [modules](/docs/reference-language#modules) for how an import resolves.
- The live version, cold start through tamper, trust confinement and
  the publish gate, with a `check.sh` that drives all of it:
  [use-cases/11-shared-modules](/use-cases/11-shared-modules).
- The other tutorials: [from a model to a file
  tree](/docs/tutorial-generate) computes source files from the model you
  just shared, and the [tutorials index](/docs/tutorial) lists all four.

---

# Tutorial: from a model to a file tree

_Compute a TypeScript client from a model of its routes, then write the file tree with aontu render._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/tutorial-generate.md · Page: https://aontu.dev/docs/tutorial-generate

A client library for an HTTP API says the same thing three times: once
in a route table, once in a function per route, once in the types. Two
of those are derivable from the first, and a model that already holds
the route table already holds the file.

This tutorial computes a small TypeScript client from a model of its
routes. The result is a **component tree**: an ordinary aontu value
whose nodes are a project, a folder, files, and lines. The tree is
checkable on its own, and [§6](#6-write-the-files) writes it to disk
with `aontu render`.

Commands are written as `aontu`; from a clone, `node ts/bin/aontu.js`
stands in. Every result on this page is the engine's own.

## 1. The model

Two routes are enough to show the shape. Save this as `api.aon`:

<!-- test: scenario generate-client -->
<!-- test: file api.aon -->
```aontu
routes: [
  { name:"list" verb:GET path:"/orders" }
  { name:"create" verb:POST path:"/orders" }
]
```

<!-- test: run -->
```sh
$ aontu api.aon
{
  "routes": [
    {
      "name": "list",
      "path": "/orders",
      "verb": "GET"
    },
    {
      "name": "create",
      "path": "/orders",
      "verb": "POST"
    }
  ]
}
```

Plain data, and deliberately so. A model worth generating from is one
the rest of the project can also validate, query and diff, which is
what the [first tutorial](/docs/tutorial-config) built.

## 2. A file is a value

`file(name, children)` names a file and holds its lines. Write
`client.aon`, which loads the model and describes one file:

<!-- test: file client.aon -->
```aontu
@"./api.aon"

out: file("client.ts", ["export const timeout = 5000"])
```

`@"./api.aon"` loads a source file and unifies it in place, so
`$.routes` is in scope here. The file itself is at `$.out`, and the
verb that reads a value is `get`:

<!-- test: run -->
```sh
$ aontu model get '$.out' client.aon
{
  "children": [
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "export const timeout = 5000"
      }
    }
  ],
  "cmp": "File",
  "props": {
    "name": "client.ts"
  }
}
```

Three keys make up every node of the tree. `cmp` is what kind of node
it is, `props` carries what that kind needs, and `children` holds what
sits inside it. The bare string became a `Line`, which is the node
that writes its own newline, so nothing in the source spells one.

## 3. One line per record

A generator is a **rule set**. `emit(selection, table)` visits every
node of a selection, takes the first template whose `match` the node
unifies with, and instantiates that template's `body` against the node,
where `.name` is that node's `name`. A list is visited in its own
order, which is why the route table is a list: a map is visited in
code-point order of its keys, whatever order it was written in. Rewrite
`client.aon`:

<!-- test: file client.aon -->
```aontu
@"./api.aon"

%route = emit(_, {
  match: verb: GET
  body: [`export const ` + .name + ` = () => get("` + .path + `")`]
})

out: file("client.ts", emit($.routes, %route))
```

Two things about the spelling. A backtick string may hold a literal
newline and a `"` without escaping it, which is what makes it the way
to carry another language's text. And `%route` is a named table,
declared once and called by name, so a document can hold several
generators without nesting them.

Run it:

<!-- test: run -->
```sh
$ aontu model get '$.out' client.aon
...
[aontu/emit_none]: Cannot resolve value at path $.out.0
...
$ echo $?
4
```

The refusal is the lesson. `create` is a `POST`, the only template
matches `GET`, and a generator that silently dropped the route would
have produced a client missing a function. `message` is the headline;
the node it could not place and the matches it tried are in the
finding's `hint`, which `--format json` carries and running the
document prints in full:

<!-- test: run -->
```sh
$ aontu client.aon
...
node unifies with; the node {"name":"create","path":"/orders","verb":"POST"} unified with none of {"verb":"GET"}.
...
$ echo $?
1
```

## 4. A second template, and the dispatch

Give `POST` a template of its own. A table may be a list of them, tried
in the order written. Rewrite `client.aon`:

<!-- test: file client.aon -->
```aontu
@"./api.aon"

%route = emit(_, [
  {
    match: verb: GET
    body: [`export const ` + .name + ` = () => get("` + .path + `")`]
  }
  {
    match: verb: POST
    body: [`export const ` + .name + ` = (b) => post("` + .path + `", b)`]
  }
])

out: file("client.ts", emit($.routes, %route))
```

<!-- test: run -->
```sh
$ aontu model get '$.out' client.aon
{
  "children": [
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "export const list = () => get(\"/orders\")"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "export const create = (b) => post(\"/orders\", b)"
      }
    }
  ],
  "cmp": "File",
  "props": {
    "name": "client.ts"
  }
}
```

Two lines, in the model's order, each taking the body its `verb`
selected. The one to ask about later is which rule wrote which line,
and `aontu trace` answers it, one row per piece:

<!-- test: run -->
```sh
$ aontu trace client.aon
client.ts	$.children.0	$.routes.0	$.%route#0
client.ts	$.children.1	$.routes.1	$.%route#1
```

The file it reached, the node in the tree, the model record that
matched, and the rule: `%route#0` is the `GET` template and `#1` the
`POST` one. A line nobody generated has no row, which is worth
remembering when a report looks short.

## 5. A folder, and a project

A client is more than one file, and files live in directories.
`folder(name, children)` is a directory, `project(dir, children)` is
the root and names the output directory, and both hold children the
same way a file holds lines. Rewrite `client.aon` a last time:

<!-- test: file client.aon -->
```aontu
@"./api.aon"

%route = emit(_, [
  {
    match: verb: GET
    body: [`export const ` + .name + ` = () => get("` + .path + `")`]
  }
  {
    match: verb: POST
    body: [`export const ` + .name + ` = (b) => post("` + .path + `", b)`]
  }
])

out: project("build", [
  folder("src", [
    file("client.ts", [
      `import { get, post } from "./http"`
      emit($.routes, %route)
    ])
    file("index.ts", each(pick($.routes, name), `export { ` + _ + ` } from "./client"`))
  ])
])
```

Two new shapes in there. The `import` line is a plain string beside an
`emit` call, and the call **splices**: its pieces join the list rather
than nesting inside it, so a body can mix written lines with generated
ones. And `index.ts` uses a different generator: `pick` projects one
field out of every record, and `each` makes one element per member, so
the re-exports come out in the model's order. `pack` would key them by
data and sort the keys, which is right for a map and wrong for a file.

<!-- test: run -->
```sh
$ aontu model get '$.out' client.aon
{
  "children": [
    {
      "children": [
        {
          "children": [
            {
              "children": [],
              "cmp": "Line",
              "props": {
                "src": "import { get, post } from \"./http\""
              }
            },
            {
              "children": [],
              "cmp": "Line",
              "props": {
                "src": "export const list = () => get(\"/orders\")"
              }
            },
            {
              "children": [],
              "cmp": "Line",
              "props": {
                "src": "export const create = (b) => post(\"/orders\", b)"
              }
            }
          ],
          "cmp": "File",
          "props": {
            "name": "client.ts"
          }
        },
        {
          "children": [
            {
              "children": [],
              "cmp": "Line",
              "props": {
                "src": "export { list } from \"./client\""
              }
            },
            {
              "children": [],
              "cmp": "Line",
              "props": {
                "src": "export { create } from \"./client\""
              }
            }
          ],
          "cmp": "File",
          "props": {
            "name": "index.ts"
          }
        }
      ],
      "cmp": "Folder",
      "props": {
        "name": "src"
      }
    }
  ],
  "cmp": "Project",
  "props": {
    "folder": "build"
  }
}
```

A `Project` whose `folder` is `build`, holding a `Folder` named `src`,
holding two `File` nodes, each holding its lines. Nothing in that tree
is a template waiting to be filled or a string waiting to be split: it
says which files exist, in which directories, with which lines, in
which order.

And because it is an ordinary value, `get` reads any node of it. Read
one leaf:

<!-- test: run -->
```sh
$ aontu model get '$.out.children.0.children.1.props.name' client.aon
"index.ts"
```

`aontu vet` can check the tree against a schema, and the rule behind
one generated line is what
[§4](#4-a-second-template-and-the-dispatch)'s `aontu trace` names.

## 6. Write the files

`aontu render` writes the tree. It hands it to a **generator runtime**,
[jostraca](https://github.com/jostraca/jostraca), which both
implementations depend on; each node's `cmp` is the component name that
runtime looks up, which is what those keys in the JSON above are for.
The path argument is the root the tree is written under, and the
`Project`'s own `folder` names the directory inside it:

<!-- test: run -->
```sh
$ aontu render --at '$.out' client.aon .
```

It prints nothing, and `build/src/client.ts` and `build/src/index.ts`
are on disk. `--check` writes nothing and compares instead:

<!-- test: run -->
```sh
$ aontu render --check --at '$.out' client.aon .
$ echo $?
0
```

Hand-edit `build/src/client.ts`:

<!-- test: file build/src/client.ts -->
```ts
export const oops = 1
```

and the check names the file and refuses:

<!-- test: run -->
```sh
$ aontu render --check --at '$.out' client.aon .
content: build/src/client.ts
$ echo $?
1
```

That is the form for CI: commit the generated files beside the model,
and an edit to one of them is a red build rather than a quiet
divergence from the model that produced it. The tree is still a value
either way, which is why [§5](#5-a-folder-and-a-project) could read a
leaf of it with `aontu model get` before anything was written.

The rest is a pipe, and it is a recipe rather than a lesson:
[generate code from a model](/how-to/generate-code) has the command
that hands `aontu model get` output to a runtime, the `--folder` form
that compares instead of writing (a generated file edited by hand is
then a red build), and the way to write the generator in the target's
own syntax so that `gofmt` and an editor can read it.

## Where to go next

You have a model that computes its own source files, and the questions
that follow are what else the model should hold:

- The recipes: [generate code from a
  model](/how-to/generate-code) end to end with goldens,
  [seal generated children deeply](/how-to/seal-generated-children)
  when a generated shape must stay closed, and [keep schema out of the
  output](/how-to/keep-schema-out-of-output) for the helper fields a
  generator needs and a file does not.
- The rules in full:
  [transforming with `emit`](/docs/reference-language#transforming-emit)
  for dispatch order, splicing and recursion,
  [`each`](/docs/reference-language#each-the-order-preserving-map) and its
  `_ & …` idiom, and
  [generation](/docs/reference-language#generation) for the ten component
  functions and what each node means for the output.
  [`aontu trace`](/docs/reference-api#aontu-trace) is specified with the
  other verbs.
- The live version: three targets in one document, committed goldens,
  and a check that both implementations answer byte-identical files, in
  [use-cases/15-code-generation](/use-cases/15-code-generation).
- The other tutorials: [share a model as a
  package](/docs/tutorial-package) gives the model a version and a hash so
  another project can import it, and the
  [tutorials index](/docs/tutorial) lists all four.

---

# Language reference

_The core language, exhaustively: syntax, semantics, the unification lattice, and every operator._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-language.md · Page: https://aontu.dev/docs/reference-language

Complete, exhaustive description of the aontu language: lexical
structure, every value form and operator, evaluation order, the
canonical form, and generation rules. Behaviour stated here is verified
by the shared [`test/spec/*.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/) suite and holds in both
the TypeScript and Go implementations unless a difference is called out.

For the public programming interface see the
[API reference](/docs/reference-api). For the reasoning behind the model see
the [Explanation](/docs/explanation).

## Contents

- [Lexical structure](#lexical-structure)
- [The value lattice](#the-value-lattice)
- [Scalars](#scalars)
- [Scalar kinds (types)](#scalar-kinds-types)
- [Maps](#maps)
- [Lists](#lists)
- [Container kinds: `map()` and `list()`](#container-kinds-map-and-list)
- [Conjunction `&`](#conjunction-)
- [Disjunction `|`](#disjunction-)
- [Preference / default `*`](#preference--default-)
- [Optional keys `?`](#optional-keys-)
- [Spreads `&:`](#spreads-)
- [Generating children: `pack` and `each`](#generating-children-pack-and-each)
  - [Making elements: `each`](#each-the-order-preserving-map)
  - [The `_ & …` idiom](#the-_---idiom-construction-and-bound)
- [Selecting: `filter` and `match`](#selecting-filter-and-match)
- [The placeholder `_`](#the-placeholder-_)
- [Transforming: `emit`](#transforming-emit)
- [References and paths](#references-and-paths)
  - [Recursive references (fixpoints)](#recursive-references-fixpoints)
- [Variables `$name`](#variables-name)
- [Aliases `%`](#aliases-)
- [The `+` operator and grouping](#the--operator-and-grouping)
- [Functions](#functions)
- [Arithmetic: `add` `sub` `mul` `div` `mod` `rem`](#arithmetic-add-sub-mul-div-mod-rem)
- [Projecting fields: `pick`](#projecting-fields-pick)
- [Optional input: `maybe`](#optional-input-maybe)
- [Ordering: `sort`](#ordering-sort)
- [Aggregating: `sum` `least` `greatest`](#aggregating-sum-least-greatest)
- [Folding to a string: `join`](#folding-to-a-string-join)
- [Text: `esc` `usc` `rep` `split`](#text-esc-usc-rep-split)
- [Linking: the tree is the namespace](#linking-the-tree-is-the-namespace)
- [First-class paths: `path(p?)`](#first-class-paths-pathp)
- [Checked links: `refer(t?)`](#checked-links-refert)
  - [Declared relations](#declared-relations)
- [Marks: `type` and `hide`](#marks-type-and-hide)
- [Closed values: `close` / `open`](#closed-values-close--open)
- [Source loading `@"…"`](#source-loading-)
  - [Text: `.txt` and `--text-ext`](#text-txt-and---text-ext)
- [Operator precedence](#operator-precedence)
- [Canonical form](#canonical-form)
- [The formatted form](#the-formatted-form)
- [The published grammar](#the-published-grammar)
- [Generation](#generation)
- [Subsumption](#subsumption)
- [Errors](#errors)
- [Grammars: `abnf()` and `parse()`](#grammars-abnf-and-parse)
  - [A grammar reads better in backticks](#a-grammar-reads-better-in-backticks)
  - [A grammar can say what it builds](#a-grammar-can-say-what-it-builds)
  - [Shaping an unannotated tree](#shaping-an-unannotated-tree)
- [The constraint algebra](#the-constraint-algebra)
  - [Named constraint aliases](#named-constraint-aliases)

---

## Lexical structure

aontu source is parsed by
[`@tabnas/jsonic`](https://github.com/tabnas/jsonic) with aontu-specific
plugins, so the surface syntax is "relaxed JSON".

- **Whitespace** separates tokens; newlines and commas are
  interchangeable separators. `a:1 b:2`, `a:1, b:2`, and `a:1\nb:2` are
  equivalent.
- **Comments** begin with `#` and run to end of line. A file of only
  comments unifies to `{}`.
- **Bare strings** need no quotes (`name: Mercury`), and may hold
  letters, digits, `-` and `_`, and nothing else. So `owner:
  team-payments`, `on: 2026-09-05` and `id: user_42` are bare strings.
  Every other punctuation character is either syntax, where the
  grammar gives it a meaning, or an error where it does not: `x=y`,
  `6/2`, `50%` and `>10` are refused with `[aontu/bare_punct]`, which
  names the character, rather than read as strings. Quote with `"…"`,
  `'…'` or `` `…` `` to include spaces or any other character
  (`name: "hi there"`, `ratio: "6/2"`). All three are the same kind of
  value; only what they may contain differs.
- **Keys** follow the same rule: bare when they hold only letters,
  digits, `-` and `_` (`host`, `a-b`), quoted otherwise.
- **Backtick strings may span lines.** `"…"` and `'…'` refuse a
  literal newline; `` `…` `` accepts one, so a backtick string carries
  several lines of text as one scalar. This is what lets a document hold a
  block of another language: a shell script, a template, a fragment
  of generated source. Escapes are processed in all three forms, so
  `\t` is a tab and `` \` `` is a literal backtick. A **literal**
  control character in the source is refused
  (`[aontu/unprintable]`), including a literal tab: write `\t`.
- **Numbers** come in two families. A plain JSON number (`1`, `1.5`,
  `1e3`) is stored as an IEEE-754 double and takes `integer` or
  `float` kind; a `0d`-prefixed literal (`0d5`, `0d0.1`) is stored
  *exactly*, with no binary rounding anywhere, and takes `biginteger`
  or `bigdecimal` kind. Which of the four a literal takes is decided
  by its source text, never by its magnitude; the rule is stated in
  full under [Scalar kinds](#scalar-kinds-types).
- **Exact literals** are written `0d` (or `0D`) followed by digits.
  Digits alone give a biginteger (`0d123`); adding a `.` or an
  exponent gives a bigdecimal (`0d0.1`, `0d1e3`). The grammar is
  `0[dD] digits [ "." digits ] [ (e|E) [+-] digits ]`. The sign goes
  *before* the prefix (`-0d5`, never `0d-5`) and a marker with no
  digit after it is not a literal at all: `0d` is the bare string
  `"0d"`, and `0d.5` reads as member access on that string.
- **Other numeric forms.** Hexadecimal (`0x1f`), octal (`0o17`) and
  binary (`0b1010`) literals use lower-case prefixes, and belong to
  the plain family, not the exact one. (Only the exact marker also
  accepts its letter in upper case: `0D12` is a literal, `0X1F` is the
  bare string `"0X1F"`.) `_` may separate digits (`1_000_000`,
  `0d1_000`), but only singly and only *between* digits: a run that
  breaks the rule is not a number at all, so `1__0` is the string
  `"1__0"`, not `10`.
- **A number that cannot be stored exactly is refused.** An integer
  literal the double format would silently round is a located error
  naming the `0d` escape, not an approximation: see
  [Exact or refused](#exact-or-refused-lossy-literals).
- **Booleans** are `true` / `false`; **null** is `null`.

A backtick string is how a document holds a block of another
language. Here `greet.aon` carries a shell script as one value:

<!-- test: scenario backtick-multiline -->
<!-- test: file greet.aon -->
```aon
greet: `#!/bin/sh
echo "hi"
`
tab: `x\ty`
```

<!-- test: run -->
```sh
$ aontu -c greet.aon
{"greet":"#!/bin/sh\necho \"hi\"\n","tab":"x\ty"}
$ echo $?
0
```

The relaxed forms combine in one document:

```aon
a: 1
b: 2
c: Mercury
d: "hi there"
```

```json
{"a":1,"b":2,"c":"Mercury","d":"hi there"}
```

## The value lattice

Every aontu value is a point in a lattice ordered from most general to
most specific:

<figure class="diagram"><div class="diagram-frame">
<svg xmlns="http://www.w3.org/2000/svg" class="av" viewBox="0 0 576 222" width="576" height="222" role="img" aria-label="Value lattice at $: 0 value(s) placed">
<style>.av{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:13px}.av-t{fill:var(--av-ink,#1f2328)}.av-m{fill:var(--av-muted,#6e7781)}.av-box{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule,#8c959f);stroke-width:1}.av-cell{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-direct{fill:var(--av-ink,#1f2328);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-closure{fill:var(--av-closure,#9ec5fe);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-unmirrored{fill:var(--av-warn,#e3b341);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-line{stroke:var(--av-rule,#8c959f);stroke-width:1;fill:none}.av-up{stroke:var(--av-alert,#d1242f);stroke-width:1.5;fill:none;stroke-dasharray:4 3}.av-dot{fill:var(--av-ink,#1f2328)}.av-hole{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-bar{fill:var(--av-bar,#57606a)}</style>
<path d="M288 34V51H40V68" class="av-line"/>
<path d="M40 94V111H40V128" class="av-line"/>
<path d="M288 34V51H248V68" class="av-line"/>
<path d="M248 94V111H120V128" class="av-line"/>
<path d="M248 94V111H192V128" class="av-line"/>
<path d="M248 94V111H272V128" class="av-line"/>
<path d="M248 94V111H376V128" class="av-line"/>
<path d="M288 34V51H472V68" class="av-line"/>
<path d="M288 34V51H536V68" class="av-line"/>
<path d="M40 154V171H288V188" class="av-line"/>
<path d="M120 154V171H288V188" class="av-line"/>
<path d="M192 154V171H288V188" class="av-line"/>
<path d="M272 154V171H288V188" class="av-line"/>
<path d="M376 154V171H288V188" class="av-line"/>
<path d="M472 94V171H288V188" class="av-line"/>
<path d="M536 94V171H288V188" class="av-line"/>
<rect x="268" y="8" width="40" height="26" class="av-cell"/>
<text x="288" y="26" text-anchor="middle"><tspan class="av-t">top</tspan><tspan class="av-m"></tspan></text>
<rect x="8" y="68" width="64" height="26" class="av-cell"/>
<text x="40" y="86" text-anchor="middle"><tspan class="av-t">string</tspan><tspan class="av-m"></tspan></text>
<rect x="216" y="68" width="64" height="26" class="av-cell"/>
<text x="248" y="86" text-anchor="middle"><tspan class="av-t">number</tspan><tspan class="av-m"></tspan></text>
<rect x="436" y="68" width="72" height="26" class="av-cell"/>
<text x="472" y="86" text-anchor="middle"><tspan class="av-t">boolean</tspan><tspan class="av-m"></tspan></text>
<rect x="512" y="68" width="48" height="26" class="av-cell"/>
<text x="536" y="86" text-anchor="middle"><tspan class="av-t">null</tspan><tspan class="av-m"></tspan></text>
<rect x="8" y="128" width="64" height="26" class="av-cell"/>
<text x="40" y="146" text-anchor="middle"><tspan class="av-t">path()</tspan><tspan class="av-m"></tspan></text>
<rect x="84" y="128" width="72" height="26" class="av-cell"/>
<text x="120" y="146" text-anchor="middle"><tspan class="av-t">integer</tspan><tspan class="av-m"></tspan></text>
<rect x="164" y="128" width="56" height="26" class="av-cell"/>
<text x="192" y="146" text-anchor="middle"><tspan class="av-t">float</tspan><tspan class="av-m"></tspan></text>
<rect x="224" y="128" width="96" height="26" class="av-cell"/>
<text x="272" y="146" text-anchor="middle"><tspan class="av-t">biginteger</tspan><tspan class="av-m"></tspan></text>
<rect x="328" y="128" width="96" height="26" class="av-cell"/>
<text x="376" y="146" text-anchor="middle"><tspan class="av-t">bigdecimal</tspan><tspan class="av-m"></tspan></text>
<rect x="268" y="188" width="40" height="26" class="av-cell"/>
<text x="288" y="206" text-anchor="middle"><tspan class="av-t">nil</tspan><tspan class="av-m"></tspan></text>
</svg>
</div><figcaption>The value lattice: top at the join; string, number, boolean and null under it; path() under string; integer, float, biginteger and bigdecimal under number; nil at the meet, below every kind.</figcaption></figure>

The engine draws this figure itself: it is
[`aontu view lattice`](/docs/reference-api#aontu-view) over a document
with no values in it. Run the same verb over your own document and
each node carries a count of the values that landed there.

- **`top`** is the unit: unifying anything with `top` yields the other
  value. It is what an unconstrained field is.
- **`nil`** (bottom) is the result of a failed unification. It carries an
  error message and cannot be generated.
- **Unification** of two values is their *greatest lower bound*: the
  most general value at least as specific as both. If none exists, the
  result is `nil`.

This ordering is why unification is order-independent and idempotent:
`a & b` equals `b & a`, and `a & a` equals `a`.

## Scalars

| Form        | Example source | Generates |
|-------------|----------------|-----------|
| integer     | `a:1`          | `1`       |
| negative    | `a:-5`         | `-5`      |
| float       | `a:1.5`        | `1.5`     |
| biginteger  | `a:0d5`        | `5`       |
| bigdecimal  | `a:0d0.1`      | `0.1`     |
| bare string | `a:hello`      | `"hello"` |
| quoted str  | `a:"hi there"` | `"hi there"` |
| boolean     | `a:true`       | `true`    |
| null        | `a:null`       | `null`    |

Two scalars unify only if they are of the same kind *and* equal
(`1 & 1` → `1`, `foo & foo` → `"foo"`); otherwise the result is a
conflict (`1 & 2` → error, and so is `1 & 1.0`).

## Scalar kinds (types)

A bare kind name is a *type*: the set of all scalars of that kind.

| Kind         | Matches                                        |
|--------------|------------------------------------------------|
| `string`     | any string                                     |
| `number`     | any numeric value: the supertype over the four leaves below |
| `integer`    | any value of *integer kind* (below)            |
| `float`      | any value of *float kind* (below)              |
| `biginteger` | any value of *biginteger kind* (below)         |
| `bigdecimal` | any value of *bigdecimal kind* (below)         |
| `boolean`    | `true` or `false`                              |
| `top`        | any value at all                               |

The path kind is spelled `path()` rather than a bare word, and sits
under `string`: see [First-class paths](#first-class-paths-pathp).
The container kinds are `map()` and `list()`: see
[Container kinds](#container-kinds-map-and-list).

### The four numeric leaves

Every numeric value carries a **kind**, fixed when the value is built,
and it is the kind (not the magnitude) that decides what the value
unifies with. There are four numeric kinds, and `number` is not one of
them: `number` names the whole family and nothing else, so no value
ever has `number` kind.

```
number                   (a pure supertype — no value has this kind)
├── integer      a double, whole, in the int64 window   1     1e3
├── float        any other double                       1.5   1e21
├── biginteger   exact, whole, unbounded                0d5   0d1_000
└── bigdecimal   exact, with a point or an exponent     0d0.1 0d1e3
```

The two upper leaves hold IEEE-754 doubles (every value a plain JSON
number can hold exactly) and the source rule below decides which of
them a literal joins. The two lower leaves are reached only by writing
`0d`, and hold their digits *exactly*: no binary rounding, and no
precision limit but the [exactness budget](#the-exactness-budget).

The four leaves are **disjoint**. No value belongs to two of them, and
values of different leaves never unify however equal they look: `1 &
1.0`, `5 & 0d5` and `0d5 & 0d5.0` are all conflicts. A cross-leaf result
would have to pick a kind, and either choice would make `&` asymmetric
in kind.

**Leaf by source.** Which leaf a literal lands in is decided by how it
is written, never by how large it is. A literal *without* the `0d`
prefix has **integer** kind if, and only if, all three of these hold:

1. its source text contains no `.`;
2. its value is integral (no fractional part);
3. its value lies within the int64 range, that is
   `-9223372036854775808 ≤ n < 9223372036854775808`.

Anything else has **float** kind. The upper bound is *exclusive*
because these values are doubles and 2^63−1 cannot be represented in
one: it rounds up to 2^63, and so falls outside the range.

A literal *with* the `0d` prefix has **bigdecimal** kind if its source
contains a `.` or an exponent, and **biginteger** kind otherwise.

```
1                      → integer     (no '.', integral, in range)
1e3                    → integer     (1000 — an exponent is not a '.')
9007199254740992       → integer
1.0                    → float       (rule 1: the source has a '.')
1.5                    → float       (rules 1 and 2)
1e21                   → float       (rule 3: beyond int64)
100000000000000000000  → float       (rule 3)
0d5                    → biginteger  (0d, digits only)
0d1_000                → biginteger
0d0.1                  → bigdecimal  (0d with a '.')
0d1e3                  → bigdecimal  (0d with an exponent)
```

The two families nearly mirror each other, with one asymmetry: a `.`
splits the leaf in both, but an exponent splits it only in the `0d`
family: `1e3` is an integer, `0d1e3` a bigdecimal.

**Canon rendering.** Canon renders a number so that reparsing it
yields the same kind again, which takes three markers:

- an integer-kind value renders plainly: `1000`;
- a float-kind value always carries a fraction or an exponent, so
  a `.0` suffix is appended when the shortest rendering has neither:
  `1.0`, `100000000000000000000.0`;
- an exact value carries the `0d` marker, with any sign in front of
  it: `0d5`, `-0d5`, `0d0.1`.

Because `0d` names the *family* and not the leaf, one more marker is
needed to tell the two exact leaves apart, and it is the same `.0`
device: **an integral bigdecimal always renders with one decimal
place.** So `0d1e3` canons as `0d1000.0` while the biginteger `0d1000`
canons as `0d1000`. Without that, `canon(0d1e3)` would reparse as a
biginteger: a different lattice point, since the leaves are disjoint.

Exact values render in plain form at every magnitude, never in
scientific notation, and **one value has exactly one rendering**:
scale is presentation, not identity, so `0d0.10`, `0d0.1` and `0d1e-1`
all parse to the same value and all canon as `0d0.1`.

Edge cases:

- The same rules apply wherever a numeric value is built (a parsed
  literal, a `$var` binding, a raw value handed to the API) so a given
  number never has two different kinds depending on where it came from.
  Where there is no source text, condition 1 is vacuous and conditions
  2 and 3 decide.
- A literal that overflows the double range entirely (`1e999`) is not a
  number at all; it is an error. One that *underflows* to exactly zero
  (`1e-400`) is integer-kind `0`.
- Negative zero never survives, in any leaf: `-0.0` normalises to
  `0.0`, `-0d0` to `0d0`, and `-0d0.0` to `0d0.0`, in canon and in
  generated output alike.
- aontu has no negative literals: `-` is a prefix operator applied to a
  positive literal. The int64 *minimum* therefore cannot be written as
  an integer-kind literal: `-9223372036854775808` negates the
  float-kind literal `9223372036854775808` and stays float kind. Write
  it `-0d9223372036854775808` to hold it exactly, as a biginteger.

### Exact or refused: lossy literals

An integer literal is stored only if the double format holds it
*exactly*. One that would be silently rounded is a located error
instead, and the message names the fix: write it with `0d`.

The input that triggers this rule is ordinary JSON: for example, a
64-bit record ID in a dump from an API. `id: 9007199254740993` is
2^53+1, the first whole number a double cannot hold. Storing it anyway
would yield 9007199254740992, a different ID, with nothing said about
it. aontu refuses:

<!-- test: scenario lossy-literal -->
<!-- test: run -->
```sh
$ echo 'id: 9007199254740993' | aontu
[aontu/lossy_integer_literal]: Cannot resolve value at path $.id

This integer literal, 9007199254740993, is not exactly representable in
binary64, so storing it would silently round it to a DIFFERENT
number. aontu refuses rather than corrupts: write it as a `0d`
literal to get the exact integer.
...
$ echo $?
1
```

(That is the TypeScript wording; Go phrases the same refusal
differently. Both name the `0d` escape.)

Take the escape and the document works again, exactly: in generated
output and in canonical form:

<!-- test: run -->
```sh
$ echo 'id: 0d9007199254740993' | aontu
{
  "id": 9007199254740993
}
$ echo 'id: 0d9007199254740993' | aontu -c
{"id":0d9007199254740993}
```

One consequence to plan for: the rescued value has **biginteger**
kind, not `integer`, so a schema constraining it must say `biginteger`
(or the family, `number`). `id: integer` would now conflict.

```
id:0d9007199254740993 & biginteger   → {"id":0d9007199254740993}
id:0d9007199254740993 & number       → {"id":0d9007199254740993}
id:0d9007199254740993 & integer      → error
```

**The rule is exactness, not magnitude.** A shorter literal can be
refused while a much longer one is fine, because what matters is
whether the exact value happens to be a double:

```
9007199254740992       → integer  (2^53, exactly representable)
9007199254740993       → error    (2^53+1 is not)
100000000000000000000  → float    (10^20 — far larger, still exact)
0x7fffffffffffffff     → error    (2^63−1 rounds up to 2^63)
0x8000000000000000     → float    (2^63 itself is a power of two)
```

The refusal covers every integer-literal form, decimal and
base-prefixed alike, and it happens at parse time, so a lossy literal
never reaches unification.

### The exactness budget

The exact leaves have no precision limit in the ordinary sense (a
biginteger is as wide as its digits) but a bigdecimal is bounded, so
that a short source cannot demand unbounded work. The bound is one a
document can rely on:

> A bigdecimal may carry **at most 4096 coefficient digits** and an
> **absolute scale of at most 4096**.

The *coefficient* is the significant digits with the point removed;
the *scale* is where the point sits among them, which for a literal is
its fraction digits minus its exponent. So `0d1.5e-4095` has
coefficient 2 and scale 4096, and is the last value of its shape that
fits.

Both halves are checked independently, on literals (against the source
as written, before normalisation) and on every computed result.
Exceeding either is a located error: *"This exact decimal exceeds the
exactness budget"*. aontu has no rounding mode and no precision
context, so a value beyond the budget is refused rather than
approximated.

```
0d1e-4096            → 0d0.000…0001   (scale 4096 — inside)
0d1e-4097            → error          (scale 4097 — outside)
0d1e4097             → error          (the bound is two-sided)
0d1e1000000000       → error          (refused before rendering it)
0d1e-4000 + 0d1e4000 → error          (the exact sum needs 8001 digits)
```

`biginteger` has no scale and no coefficient bound: a whole number of
ten thousand digits is an ordinary value.

### Unification rules

- **kind & matching scalar → the scalar.** `number & 2` → `2`;
  `string & hello` → `"hello"`; `1 & integer` → `1`;
  `0d1.5 & bigdecimal` → `0d1.5`.
- **kind & non-matching scalar → conflict.** `1 & string` → error;
  `1.0 & integer` → error (`1.0` is float kind whatever its value),
  and so are `1e21 & integer`, `0d5 & integer` and `1 & biginteger`.
- **kind & kind:** equal kinds unify to themselves; `number & <leaf>` →
  that leaf (`number & integer` → `integer`, `number & bigdecimal` →
  `bigdecimal`); two distinct leaves conflict, as do unrelated kinds.
- **scalar & scalar:** two concrete numbers are the same only when kind
  *and* value match. So `1 & 1.0` is a conflict, and `1|1.0` is a real
  two-branch disjunction: `(1|1.0) & 1.0` selects the float. Value
  comparison for the exact leaves is over the number, not its
  spelling: `0d1.5 & 0d1.50` is `0d1.5`.

No operator or function narrows a kind: see
[`+`](#the--operator-and-grouping) and
[`upper()`/`lower()`](#functions). The int64 window, the `.0` canon
suffix and the `0d` marker are stated in
[the four numeric leaves](#the-four-numeric-leaves) and
[Canonical form](#canonical-form).

## Maps

A map is an unordered set of key/value pairs. Braces are optional at the
top level.

- **Literal:** `a:{b:1,c:2}` → `{"a":{"b":1,"c":2}}`.
-  **Implicit nesting:** a chain of colons builds nested maps: `a:b:c:1`
  → `{"a":{"b":{"c":1}}}`.
- **Duplicate-key merge:** stating a key twice unifies the two values.
  `a:{b:1}, a:{c:2}` → `{"a":{"b":1,"c":2}}`.

The merge recurses through nesting:

<!-- fmt: keep the statements the merge law reads as one map -->
```aon
a: b: c: 1
a: b: d: 2
a: e: 3
```

```json
{"a":{"b":{"c":1,"d":2},"e":3}}
```

Maps are **open** by default (extra keys may be unified in) until sealed
with [`close`](#closed-values-close--open).

## Lists

A list is an ordered sequence.

- **Literal:** `a:[1,2,3]` → `{"a":[1,2,3]}`. Elements may be
  whitespace-separated: `[1 2 3]`.
- **Mixed / nested / of maps:** `[1,two,true]`, `[[1,2],[3,4]]`,
  `[{x:1},{y:2}]` all work.
- **A pair is a single-key map element:** `[a:1, b:2]` is
  `[{a:1}, {b:2}]`: the braces are optional for a one-key map in list
  position, and the two spellings are the same document. An optional
  pair carries its `?` into the element (`[a?:1]` is `[{a?:1}]`), a
  numeric key is a key of the element map and never an index into the
  list (`[0:1]` is `[{"0":1}]`), and a chain nests (`[a:b:1]` is
  `[{a:{b:1}}]`).
- Lists unify element-by-element by position (and support `&:` spreads,
  below).

The pair form reads naturally for ordered records:

```aon
routes: [get:"/health" post:"/orders"]
```

```json
{ "routes": [ { "get": "/health" }, { "post": "/orders" } ] }
```

## Container kinds: `map()` and `list()`

`{}` and `[]` are the container *units*: each admits any value of its
shape, and generates empty when nothing else arrives. `map()` and
`list()` are the container *kinds*: each admits exactly the same
values and defaults to nothing, as `string` does. The kind is the
spelling of "a map must be supplied here": an unmet unit silently
manufactures its empty value, an unmet kind refuses to generate.

```aon
required: map() & { a:1 }
```

```json
{ "required": {"a": 1} }
```

The contrast, unmet:

<!-- test: scenario container-kinds -->
<!-- test: run -->
```sh
$ echo 'y: {}' | aontu -c
{"y":{}}
$ echo 'y: map()' | aontu
[aontu/mapval_no_gen]: Cannot resolve value at path $.y
...
$ echo $?
1
```

A kind mismatch refuses with the unit's own codes (`[aontu/map]`,
`[aontu/list]`): `map() & [1]` is the same fact `{} & [1]` reports.
Neither function takes arguments: element constraints belong to the
spreads (`{&: V}`, `[&: V]`). The kinds settle inside `type()` bodies,
[meet](/docs/unification) the unit literals (`map() & {}` is `{}`: an
explicitly supplied empty map satisfies the kind), and subsume their
containers (`map()` subsumes `{a:1}`). Pinned by
[`test/spec/containerkind.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/containerkind.tsv).

## Conjunction `&`

`a & b` is the explicit unification of `a` and `b`: the same operation
that merges duplicate map keys.

```aon
a: 1 & integer
b: { x:1 } & { y:2 }
c: { x:p:1 } & { x:q:2 }
```

```json
{"a":1,"b":{"x":1,"y":2},"c":{"x":{"p":1,"q":2}}}
```

Two kinds meet to the narrower kind and stay a kind: `number & integer`
canons as `integer` and does not generate on its own.

Conjunction is commutative, associative, and idempotent. It **distributes
over disjunction**: `x & (a|b)` tries `x` against each alternative.

## Disjunction `|`

`a | b` is a choice of alternatives. It is kept open until something
selects a branch.

```
a:1|2                → canon {"a":1|2}
a:string|number      → canon {"a":string|number}
a:1|2|3              → canon {"a":1|2|3}
```

Unifying a concrete value selects the matching branch (others become nil
and drop out):

```aon
a: 2
a: 1|2
b: 2
b: string|number
```

```json
{"a":2,"b":2}
```

`&` binds tighter than `|`, so `c & b | a` parses as `(c & b) | a`.

**An unresolved disjunction has no value**. More than one alternative
still admitted means the truth is not yet settled, so generation refuses
with `disjunct_no_gen`, class `incomplete`: the same class a bare
`string` residue answers:

```
a:1|2                → [aontu/disjunct_no_gen] at $.a
a:{x:1}|{y:2}        → [aontu/disjunct_no_gen] at $.a
```

Two things resolve it: a value that selects an alternative, or a
preference saying which one holds when nothing else does (below).
Alternatives that are the *same value* collapse first, so `1|1` and
`{a:1}|{a:1}` each generate that one value: sameness is structural
for maps and lists (container kind, closedness, marks, optional keys,
then the children).

An optional key whose value is an unresolved disjunction is dropped
rather than reported, as every other unresolved optional is.

## Preference / default `*`

`*x` marks `x` as **preferred** (a default). In a disjunction the
preferred branch is chosen unless unification forces another.

```aon
a: *1|number
b: *5
c: *green|string
d: *1|number
d: 2
```

```json
{"a":1,"b":5,"c":"green","d":2}
```

The preference survives in canonical form (`a` above canons as
`{"a":*1|number}`) because a default is constraint information, not a
resolved value.

Defaults propagate through nesting and spreads. `pref(x)` is the
function form of `*x` (canon `*x`). Preferences can be ranked (a `*` of
a `*` outranks a single `*`); the lowest rank wins when two preferred
values meet. A ranked preference meets its peers exactly as rank 1
does: the **rank-uniform meet**: `a:**1.5 & float` is `1.5` just as
`a:*1.5 & float` is, and `**2|integer` met by a bare `integer` keeps its
default.

Overriding a default is judged in two steps, and they are the two arms
of the disjunction `*x` stands for: `*x & peer` is `(x & peer) |
(super(x) & peer)`.

**The preferred value answers first.** A peer it still admits leaves
the preference standing, narrowed to what survived: `a:*1.5 & float`
and `a:*1.5 & number` are both `1.5`, `a:*8080 & min(1024)` is still
`*8080`, and `a:*integer & 7` is `*7`.

**Otherwise its type answers, and that is the override.** `a:*8080 &
9090` is `9090`: `8080` cannot admit it, `integer` can. When neither
arm admits the peer, nothing is left of the disjunction and the
refusal is `empty`: `a:*2 & 3.0`, `a:*2.2 & 3` and `a:*1.5 & integer`
are all errors, because the numeric leaves are disjoint.

The type is `super(x)`, so the rule reaches every kind of
default: `super(integer)` is `number`, so `a:*integer & 7` narrows and
`a:*integer & "s"` refuses.

**Two defaults of the same rank must agree.** `a:*1` beside `a:*7` is
`pref_rank_clash`, in that spelling and in `a:*1|*7`: the disagreement
is between the DEFAULTS, and the fix is to rank one of them (`**`).
Compatible defaults fold: `a:*1` beside `a:*integer` is `*1`.

**A preference conjoined with a disjunction names an alternative**:
`(A|B) & *A` is `*A|B`, the same value the direct spelling denotes, so
the two ways of writing an enum-with-default agree.

```aon
a: ("1.0"|"1.1") & *"1.0"
```

```json
{"a":"1.0"}
```

The canon is `{"a":*"1.0"|"1.1"}`. A preference that names no
alternative is dropped (it has nothing to prefer) so
`("1.0"|"1.1") & *"2.0"` canons as `"1.0"|"1.1"`. The default-validity
lint below is what reports that shape.

**A preference inside a disjunction is gated by admission**: an override
must be admitted by the disjunction itself: by at least one
alternative, or by the preferred value. A preferred branch contributes
exactly its own value to the admitted set, so `*'auto' | 'literal' |
'data'` is a true **enum with a default**: unset generates `"auto"`,
`'literal'` and `'data'` override, and anything else is the empty
disjunction (`[aontu/empty]`). A wider alternative admits a wider
override (`*8080 | integer` accepts any integer), and a constraint
alternative is consulted rather than bypassed (`*8080 | (integer &
min(1024) & max(65535))` refuses `80` and accepts `2048`; `*8080 |
(integer & neq(80))` refuses `80`). A deliberately open default states
its openness: `*x | top` admits every override. The gate covers scalar
preferred values: the same boundary as the kind gate above.

```aon
a: *8080|integer
a: 9090
b: *8080|number
b: 1.5
c: *8080|string
c: 8080
```

```json
{"a":9090,"b":1.5,"c":8080}
```

An alternative admits `a`'s override (same leaf); the `number` branch
admits `b`'s float; the preferred value admits itself at `c`. An
override nothing admits is the empty disjunction:

<!-- test: scenario enum-gate -->
<!-- test: run -->
```sh
$ echo 'k: *auto | literal | data  k: autoo' | aontu
[aontu/empty]: Cannot unify values at path $.k
...
$ echo $?
1
```

The refusals follow the same rule at every width: `*8080 | integer`
met by `1.5` is `[aontu/empty]` (the other numeric leaf), and
`*8080 | (integer & neq(80))` met by `80` is refused because the
exclusion is consulted, not bypassed.

A document that wants an open override says so by writing the open
branch explicitly, `*x | top`.

**A structural default is gated too**, by the same rule as every
other: the peer must pass `super(x)`, and `super({x:1})` is
`{x:integer}`. A map default therefore MERGES with a map that adds a
key (the preferred value itself admits it) and refuses a value of
another kind outright:

```aon
a: *{ x:1 }
a: y: 2
b: *{ x:1 }
b: x: 2
```

```json
{"a":{"x":1,"y":2},"b":{"x":2}}
```

`a` keeps its `x` default and gains `y`; `b`'s `x` is overridden,
because `{x:1}` cannot admit `{x:2}` but its type can. A peer of
another kind (`a: "s"`) refuses, as the scalar case always did.

A document that wants a structural default any peer may replace says so
by writing the open branch explicitly, `*{x:1} | top`.

Writing `a:{x:*1}` rather than `a:*{x:1}` is still the clearer
spelling when you mean "a map whose `x` defaults to 1", and it is what
`pref({x:1})` produces. Pinned by the `pref-struct-*` rows in
[`test/spec/pref.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/pref.tsv).

## Optional keys `?`

A key suffixed with `?` is optional. If it never receives a concrete
value, it is **dropped from the generated output** instead of erroring.

<!-- fmt: keep a schema and its data as separate statements -->
```aon
x?: number
y: Y
a: {y?:number, z:2}
a: {}
b: {y?:number, z:2}
b: {y:11}
c: {y?:number, z:*3}
c: {y:11}
```

```json
{"a":{"z":2},"b":{"y":11,"z":2},"c":{"y":11,"z":3},"y":"Y"}
```

The unresolved `x?` is dropped, `b`'s filled `y` is kept, and `c`'s
default still applies beside the filled key.

Optionality survives references: a referenced map drops its unresolved
optional keys too.

## Spreads `&:`

A `&:` entry is a **template** unified into every other entry of its map
or list. The template itself is not emitted:

```aon
c: { &: { x:2 } y:k:3 z:k:4 }
```

```json
{"c":{"y":{"k":3,"x":2},"z":{"k":4,"x":2}}}
```

A template may be a kind (`&: string`), a constraint map
(`&: {x:number}`), a referenced value (`&: $.tmpl`), or carry a
per-child overridable default (`&: x: *1|number`). A template that
names each child uses `key()`:

```aon
a: b: { &: { name:key() } c: {} d: {} }
```

```json
{"a":{"b":{"c":{"name":"c"},"d":{"name":"d"}}}}
```

Other forms:

- **Implicit / cross-statement:** `a:b:{} a:&:{x:1}` →
  `{"a":{"b":{"x":1}}}`.
- **Top-level:** `a:{} &:{x:1}` → `{"a":{"x":1}}` (applied to every root
  key).
- **Lists:** the spread applies to every element, and canon keeps the
  spread entry (`[&:{"x":1},{"y":1,"x":1},…]`):

```aon
l: [&: { x:1 } y:1 y:2]
```

```json
{"l":[{"y":1,"x":1},{"y":2,"x":1}]}
```

**Several templates apply independently, per child.** When one bag
accumulates more than one `&:` template (consecutive spreads, spreads
from different statements, templates arriving by reference through a
conjunction or an id-merge) every child meets the combined constraint
of all of them, and only that: children never meet each other's data
through the templates, whatever mix of literal values, kinds,
references, defaults or `key()` the templates carry. A key one
template requires is required at every child; a default one template
carries defaults (and stays overridable) per child.

<!-- fmt: keep two spreads written as separate statements -->
```aon
w: &: {p: integer}
w: &: {r: integer}
w: x: {p:1, r:5}
w: y: {p:2, r:6}
```

```json
{"w":{"x":{"p":1,"r":5},"y":{"p":2,"r":6}}}
```

## Generating children: `pack` and `each`

A spread constrains children that already exist. `pack` and `each`
**make** them, from data that is already in the model, so the list of
names and the children built from it cannot drift apart:

```aon
names: [web auth billing]

deploy: close(pack($.names, {
  image: "acme/" + key() + ":1.4.2"
  replicas: *2|integer
  port: *8080|integer
}))

deploy: billing: replicas: 4 # an override composes as usual
```

```json
{"names": ["web", "auth", "billing"],
 "deploy": {
   "web":     {"image": "acme/web:1.4.2",     "replicas": 2, "port": 8080},
   "auth":    {"image": "acme/auth:1.4.2",    "replicas": 2, "port": 8080},
   "billing": {"image": "acme/billing:1.4.2", "replicas": 4, "port": 8080}}}
```

`pack(data, tmpl)` makes one **keyed child** per child of `data`. The
keys are **data, never position**: for a list, the strings themselves
(a non-string element is an error, `pack_key`); for a map, its keys.
Each generated child is `tmpl` cloned at that destination, so `key()`
and relative references inside the template answer for the child
rather than for the call. Duplicate keys are not an error: the
colliding children unify, exactly as duplicate source keys merge.

**Instantiation is per destination, to the leaves**. The clone a
destination receives is a *full instance*: nothing in it (not a call's
arguments, not a preference's inner value, not an operator's operands) is
shared with the template or with any sibling destination, and every path
inside it is the destination's. So `close({name: key()})`, `**key(1) |
string` and `.a + 1` inside a template all answer per child, in
expressions and call arguments as much as in bare positions; the first
child's resolution can never answer for the others. The same rule
instantiates a `filter` condition per trial and a spread constraint
(`&:`) per application.

`each(data, tmpl)` makes one **list element** per child of `data`. It
is documented in full [below](#each-the-order-preserving-map); what
matters here is that the same `_` that binds the source child also
lets it be kept, so `each(d, _ & t)` is every member of `d` met with
`t`, and `each(d, _)` is a map's children as a list. The order is
fixed: source order for a list, sorted-key order for a map.

```aon
ports: { http:80 https:443 }
open: each($.ports, _ & integer)
names: each({ b:2 a:1 }, _)
```

```json
{"ports":{"http":80,"https":443},"open":[80,443],"names":[1,2]}
```

Once fired, generated children are **ordinary children**: a
destination `&:` spread applies to them, `close()` seals the generated
shape, references reach into them, and a template may itself contain a
generator.

Both **wait for the model to settle** before they fire, and fire exactly
once. A generator's data can still be merged into by a sibling
statement, an include or a spread after it first looks complete, and
children generated from a half-merged bag would be missing. The data
argument's **snapshot waits for the source too**: a reference like
`pack($.ports, …)` copies its target only once the target has finished
resolving in the tree, so a source augmented by a spread (even one
injecting relative references (`ports: &: {port:
.containerPort}`)) reaches the generator with those references already
answered at the source. Until it fires, a generator canons as its own
call (`pack($.n,…)` with the data reference still standing) which reparses
to the same value.

Neither can recurse. Both iterate a finite bag that already exists, so
the number of children either can produce is fixed by the data:
evaluation still terminates by construction.

### `each`, the order-preserving map

`each(data, tmpl)` makes one **list element** per child of `data`,
being `tmpl` instantiated at that position with `_` bound to the
source child. Written plainly it **replaces** rather than meets: the
element is the template and nothing else, which is what makes it a
construction. Mentioning the hole keeps the child; that is the
[`_ & …` idiom](#the-_---idiom-construction-and-bound) below.

```aon
names: [web auth billing]
files: each($.names, { path:_ + ".ts" })
consts: each($.names, upper(_))
tag: join(each(split("index-build", "-"), upper(_)), "_")
```

```json
{"names": ["web", "auth", "billing"],
 "files": [{"path": "web.ts"}, {"path": "auth.ts"}, {"path": "billing.ts"}],
 "consts": ["WEB", "AUTH", "BILLING"],
 "tag": "INDEX_BUILD"}
```

The order is the data's (source order for a list, sorted-key order for
a map) through the one rule every bag reader uses, and a hidden
child or an unfilled optional is skipped as generation would skip it.
That order is why the list generator is a built-in at all:
`pick(pack(d, {f: t}), f)` maps too, but through a map, so it re-sorts
to code-point order, and the fields of a struct, the imports of a file
or an index in the model's order would come out alphabetised. With
`split` and `join` it closes the name-derivation chain, as `tag`
shows. Like `pack`, it waits for the model to settle and fires once; a
`_` inside its template is its own to bind, never an enclosing
generator's.

### The `_ & …` idiom: construction and bound

`_` inside a generator's template binds the **source child**. Whether
that child survives into the element is decided by one thing: whether
the template mentions the hole.

```aon
ports: [containerPort:80 containerPort:443]
plain: each($.ports, { protocol:TCP })
bound: each($.ports, _ & { protocol:TCP })
```

```json
{"ports": [{"containerPort": 80}, {"containerPort": 443}],
 "plain": [{"protocol": "TCP"}, {"protocol": "TCP"}],
 "bound": [{"containerPort": 80, "protocol": "TCP"},
           {"containerPort": 443, "protocol": "TCP"}]}
```

`plain` **replaces**: the element is the template, and the port
numbers are gone. `bound` **meets**: `_ & {protocol:TCP}` is the child
unified with the template, so each entry keeps its `containerPort` and
gains a `protocol`. One generator, two jobs, and the `_` says which.

Three shapes cover most uses:

| written | the element is | use it for |
|---|---|---|
| `each(d, t)` | `t`, instantiated | building new records from data |
| `each(d, _ & t)` | the child, met with `t` | constraining or extending members |
| `each(d, _)` | the child itself | a map's values as a list |

**`each(d, _ & t)` is a bound**, so everything a meet does applies: a
kind checks the members, a constraint atom bounds them, and a
preference supplies a default the member may override.

```aon
ports: [8080 443]
checked: each($.ports, _ & integer)

m: { b:2 a:1 }
vals: each($.m, _)
```

```json
{"ports": [8080, 443], "checked": [8080, 443],
 "m": {"a": 1, "b": 2}, "vals": [1, 2]}
```

**`each(d, _)` is the map-to-list conversion**: the template is the
hole and nothing else, so every member arrives unchanged, in
sorted-key order for a map and source order for a list.

The same `_` binds in a `pack` template, a `filter` condition and an
`emit` body, and it always names the value that construct is working
on. Two rules govern it:

- **The hole belongs to the nearest enclosing generator.** In
  `pack($.m, {inner: each(_, _)})` the first `_` is the *pack's*
  source child, because a generator's data argument is not a binding
  position, and the second is the `each`'s own.
- **A spread has no hole.** `&: {n: _}` leaves `_` unfilled; inside a
  spread, name the child's fields with a relative reference (`.k`) and
  its key with `key()`.

A meet cannot select, so `_` does not reach into the child: asking for
one of its fields with `each($.lines, _ & _.amount)` asks for
something that is both the whole record and one of its fields. Use
[`pick`](#projecting-fields-pick) to project a field.

## Selecting: `filter` and `match`

`filter(data, cond)` keeps the children of `data` that **already
satisfy** `cond` (keys preserved for a map, order for a list) and
drops the rest silently:

```aon
services: { web: { debug:true port:80 } auth:port:81 }
debugged: filter($.services, { debug:true })
sidecars: pack($.debugged, { image:"acme/debug:1.0" })
```

```json
{"services": {"web": {"debug": true, "port": 80}, "auth": {"port": 81}},
 "debugged": {"web": {"debug": true, "port": 80}},
 "sidecars": {"web": {"image": "acme/debug:1.0"}}}
```

"Already satisfies" means the meet **changes nothing**: `cond` adds no
information the child did not have. Mere unifiability would not do: a map
is open, so `{port:81}` unifies with `{debug:true}` by *gaining* the
key, and a filter that kept everything that could be made to match would
keep everything. The condition is an ordinary value, so the constraint
atoms compose with it: `filter($.deploy, {replicas:min(3)})`.

`match(v, p1, r1, …, d?)` is a **bounded conditional**. The first
pattern in argument order that `v` **already satisfies** selects its
result, which is the answer; a trailing argument (the one that makes the
argument count even) is the default:

```aon
tier: large
size: match($.tier, small, { cpu:1 }, large, { cpu:8 }, { cpu:2 })
```

```json
{"tier":"large","size":{"cpu":8}}
```

A pattern is held to the same "already satisfies" rule as `filter`'s
condition above, so kinds and atoms work as patterns (`match(x,
integer, …, string, …)`, `match(n, min(0), …)`) while a pattern naming
a key the value lacks does not match by gaining it. There are no
guards, no comparisons beyond the atoms, and no
fallthrough. **No match and no default is an error** naming the
patterns that were tried, not an empty answer: a default is how a
document says the rest was meant to be allowed. An unselected result
is never evaluated, so a broken arm nobody takes is not an error the
document has to carry.

**A defaulted scrutinee matches as the value it generates**. A settled
scrutinee that carries an effective default (a preference, or a
disjunction holding one) is tested as the innermost preferred value,
not as the still-open preference. So with `side_effect: *readonly |
write | destructive`, the derivation `match(.side_effect, destructive,
true, false)` answers `false` when `side_effect` is unset (the effective
value is `"readonly"`), and `true` only when it is genuinely
`destructive`. Before this rule a pattern could *select* an arm by
overriding the default, deriving a value that contradicted the one
generated beside it. A pref-free open disjunction still matches by plain
unifiability.

Both wait for the model to settle before they answer, for the reason
`pack` and `each` do: a bag that is still being merged into is the
wrong bag to take a subset of, and a scrutinee that is still being
narrowed can match an earlier arm than the one it will end up matching.

**A `match` does not fire on an unfilled hole.** `match(_, …)` outside
a generator's template never answers: the peer that would fill the hole
is not also checked against the arm the fill selects (see
[The placeholder `_`](#the-placeholder-_)), so a `match` written as a
schema would accept every document it was asked about. The call stands
unresolved instead, and a `vet` run says so. Inside a generator's
template the hole is the source child, the scrutinee is a value by the
time the match runs, and the form works as documented above.

## The placeholder `_`

A bare `_` is a **hole**: a call holding one waits, and whatever the
call is unified with fills it.

<!-- fmt: keep a template and a key written as separate statements -->
```aon
greeting: upper(_) & hello
x: {&: {m: _ + 2}}
x: a: m: 1
```

```json
{"greeting":"HELLO","x":{"a":{"m":3}}}
```

The peer goes **into** the call and is not also a constraint on the
way out: `upper(_) & hello` is `"HELLO"`, not `"HELLO" & "hello"`.
Two holes meeting is an error: neither has a value to fill the other.
`match` is the one call a peer does not fill, because the arm it would
select is not then checked against that peer: see
[Selecting](#selecting-filter-and-match).

Inside a generator's template, `_` is the **source child** the
generated one is being made from:

```aon
ports: { http:80 https:443 }
open: pack($.ports, { port:_ name:key() })
```

```json
{"ports": {"http": 80, "https": 443},
 "open":  {"http":  {"name": "http",  "port": 80},
           "https": {"name": "https", "port": 443}}}
```

A hole belongs to its **nearest enclosing generator**: an outer
generator's fill pass never reaches into a nested generator's template
(or a `filter`'s condition), so in `pack($.envs, {services:
pack($.fleet, {v: _})})` the inner `_` is the fleet entry, not the env.
A hole in a generator's *data* argument is not a binding position, so it
is still the outer generator's to fill: `pack($.m, {inner: each(_, _)})`
iterates the outer source child. A generator whose data is a hole is
filled by its **peer**, exactly as any other call is (`["a"] &
pack(_, {x:1})` packs the list) which is what lets a rule table be named
(see [Transforming](#transforming-emit)). And wrapping a generator in a call
(`close(pack(d, _ & t))`) does not expose the template's hole to the
wrapper's peers: an overlay statement merges with the generated
children, never with the template.

For a `pack` over a list of names, `_` and `key()` are the same
thing: the name is the key. Over a map they differ: `key()` is the key,
`_` is the value. In a `filter` condition, `_` is the child being
tested.

A hole is not a function parameter: it cannot be named, passed, or
partially applied, and there is no way to write one that is not
already inside a call. Unfilled at generation it is an error, exactly
as `top` is.

A bare `_` is a hole, pinned by `test/spec/place.tsv`. Quoted `"_"`
is that string, any longer bare word containing it (`_b`) is ordinary
text, and `_` as a **key** is a key.

## Transforming: `emit`

`emit(select, table)` applies a **rule table** to a selection of nodes.
For every node, in order, the first template whose `match` the node
already satisfies is taken, and its `body` is instantiated against that
node. The answer is one flat list of pieces:

```aon
services: [{ kind:sqs pin:"srv:a" } { kind:http path:"/a" }]

lines: emit($.services, [
  { match:kind:sqs body: ["listen(" + .pin + ")"] }
  { match:kind:http body: ["serve(" + .path + ")"] }
])
```

```json
{"services": [{"kind": "sqs", "pin": "srv:a"}, {"kind": "http", "path": "/a"}],
 "lines": ["listen(srv:a)", "serve(/a)"]}
```

A **table is a list of templates**, tried in order, and each template
is a map naming both a `match` and a `body`. A table of one may be
written as the template map itself. Both keys are required: a template
with no pattern would claim every node by accident, and one with no
body would claim a node and emit nothing.

**The body is a list, and the result is flat.** A body element that is
itself a list splices into the answer rather than nesting, which is
what lets one dispatch compose into another.

**Two things inside a body name the matched node**: `_` is the node,
and a *relative* reference is a field of it: `.pin` is that node's
`pin`. An absolute reference (`$.x`) is untouched and still reads the
document root. A relative reference the node cannot answer is an error
(`emit_ref`) reported against the node, not a miss somewhere else:
inside a body, only a chain of plain names is a field, so a parent step
has no answer at a node that is an origin rather than a position.

**An empty selection emits nothing**, and that is the whole conditional
mechanism: there is no `when` directive because there is nothing for one
to do. A dispatch over a `filter` that selects nothing contributes
nothing:

```aon
services: [{ name:web logs: [] }]

lines: emit($.services, {
  match: name: string
  body: [
    "start " + .name
    emit(filter(.logs, { level:debug }), {
      match: level: debug
      body: ["debug on"]
    })
  ]
})
```

```json
{"services": [{"name": "web", "logs": []}], "lines": ["start web"]}
```

**No match is an error** (`emit_none`), naming the patterns that were
tried, rather than an empty answer or a copy of the node. A template
whose `match` is `any`, written last, is how a document says the rest
of the selection was meant to be allowed.

### A named table

A table written as an ordinary field is evaluated where it sits, so the
relative references in its bodies resolve there and miss. The position
that holds a table unevaluated is the one position the language never
drives: a call's template argument. Write the table as an `emit` whose
**selection is a hole**, and it is a rule set waiting for its nodes:

```aon
%wire = emit(_, { match:pin:string body: ["client(" + .pin + ")"] })

listen: [pin:"srv:a"]
client: [pin:"srv:b"]

a: emit($.listen, %wire)
b: $.client & %wire
```

```json
{"listen": [{"pin": "srv:a"}], "client": [{"pin": "srv:b"}],
 "a": ["client(srv:a)"], "b": ["client(srv:b)"]}
```

Passing the nodes by call and by meet are the same dispatch. A named
table is also how one rule set serves two outputs: naming a value is
something the language already does, so no keyword is needed for it.

### Recursion, and what bounds it

A named table may name **itself**, which is how a rule set walks a
nested structure into nested output:

```aon
tree: [{ name:a kids: [{ name:b kids: [] }] }]

%walk = emit(_, {
  match: name: string
  body: ["<" + .name + ">" emit(.kids, %walk) "</" + .name + ">"]
})

out: emit($.tree, %walk)
```

```json
{"tree": [{"name": "a", "kids": [{"name": "b", "kids": []}]}],
 "out": ["<a>", "<b>", "</b>", "</a>"]}
```

`emit` is the one form here that recurses, and what bounds it is the
**selection**: each dispatch descends into a finite bag that already
exists in the model, and a selection that empties emits nothing. A rule
set that walks into itself without descending is refused as a spent
depth budget, like any other runaway descent.

Like the other combinators, `emit` waits for the model to settle before
it fires: a selection that is still being merged into is the wrong set
of nodes to dispatch over. Until it fires it canons as its own call.

### Replacing text in a body: `replace` and `esc`

A body line is target text, and a value reaches it through a
**`replace`** map rather than a hole: each key is an exact string the
body already holds as ordinary text, and its value is evaluated
against the matched node. Every value is **escaped** by the template's
`esc` convention: the C/JSON escape when the key is absent; `sq` for a
single-quoted literal; `sql`, `shell`, `xml`, `uri` or `regex` by
name; and `none` for a value that is not going into a literal at all:

```aon
services: [{ name:"o'brien" pin:"srv:a" }]

lines: emit($.services, {
  match: name: string
  esc: sq
  replace: { NAME:.name PIN:.pin }
  body: ["seneca.client({type:'sqs',pin:'PIN'})" "await getSeneca('NAME')"]
})
```

```json
{"services": [{"name": "o'brien", "pin": "srv:a"}],
 "lines": ["seneca.client({type:'sqs',pin:'srv:a'})", "await getSeneca('o\\'brien')"]}
```

There is no delimiter to collide with the target's own syntax, so a
deployment template's `${self:provider.stage}` and a backtick string
survive untouched. Three rules bound the substitution: a line is
scanned once, left to right, taking the longest key at each position;
a substituted value is never scanned again, so no value can introduce
a key; and a template's replacements touch its own literal lines
only: a piece spliced in from a nested dispatch carries that template's
replacements and is finished. A number or a boolean value spells
itself, as it does after `+`; a map, a list or a null is refused
(`replace_value`).

Two checks run on the template before any node is visited: a key
inside another key is ambiguous whatever the order
(`replace_overlap`), and a key the body's literal lines do not hold
means the template has drifted from its map (`replace_unused`).

## References and paths

A reference resolves to the value at another location, then unifies in
place.

| Syntax    | Meaning                                              | Example |
|-----------|------------------------------------------------------|---------|
| `$.a.b`   | absolute path from the document root                 | `a:1 b:$.a` → `b:1` |
| `.a.b`    | path relative to the current map                     | `z:x:{a:62} z:y:.x.a` → `y:62` |
| `$.a.1`   | list index: a segment is numeric **only** as a plain decimal integer | `a:[10,20,30] b:$.a.1` → `b:20` |

**Numeric segments are plain decimal integers, and nothing else is.**
`$.a.1` indexes a list and reaches the key `1`. Every other numeric
spelling (hex, `0d`, `_` separators, an exponent) addresses the key
spelled **exactly that way**, because that is what the spelling already
produces on the key side: `a:{0x0:1}` generates `{"0x0":1}`, not
`{"0":1}`, so `$.a.0x0` finds it and `$.a.0` does not.

In a path the dot is always the **separator**, never a decimal point.
That is why `$.a.1.0` is the two segments `1` and `0` (how a nested list
index is written (`a:[[1,2],[3,4]] b:$.a.1.0` → `b:3`)) rather than a
key spelled `1.0`.

References compose with unification and each other: cross-references,
chains, and a referenced map met with extra keys:

```aon
a: { x:1 y:$.b.x }
b: { x:2 y:$.a.x }
c: v: $.d.v
d: v: 99
q: a: x: 1
w: b: $.q.a & { y:2 z:3 }
```

```json
{"a": {"x": 1, "y": 2},
 "b": {"x": 2, "y": 1},
 "c": {"v": 99},
 "d": {"v": 99},
 "q": {"a": {"x": 1}},
 "w": {"b": {"x": 1, "y": 2, "z": 3}}}
```

An unresolvable path is an error: `a:$.nope` →
`Cannot resolve value: $.nope`.

### Recursive references (fixpoints)

A reference to a value **inside that value** is the fixpoint, not an
error. `$.schema.Step` written inside `Step` means "a `Step`, by this
very definition", and the schema applies at every depth of the data:

```aon
schema: hide({ Step: { label:string then?:$.schema.Step } })
doc: $.schema.Step & { label:"start" then:label:"finish" }
```

```json
{"doc": {"label": "start", "then": {"label": "finish"}}}
```

The recursive position expands **one level per meet with concrete
data**, so the checks descend exactly as far as the data does and no
further. Data is finite, so evaluation terminates; the depth budget
is the backstop (`recursion_budget`).

**Guardedness is emergent: the data decides, never a static
analysis.** Under an optional key (`then?:`) the chain ends where
the data ends. A ranked default works the same way:

```aon
schema: hide({ Node: { v:integer next: *null|$.schema.Node } })
doc: $.schema.Node & { v:1 next:v:2 }
```

```json
{"doc": {"v": 1, "next": {"v": 2, "next": null}}}
```

A **required** recursive position that never meets data refuses at
generation, at the exact place no finite document can fill:

```
schema: hide({Step: {label: string, then: $.schema.Step}})
doc: $.schema.Step & {label: "start"}
→ [aontu/recursion_unexpanded]: Cannot recurse value at path $.doc.then
```

In [canonical form](#canonical-form) and the `aon1-` hash the
recursion stays **symbolic**: the instance unrolls to its data and
then says `$.schema.Step`; the definition stays one reference deep.
A recursive schema's canon is finite, reparses to itself, and its
hash pins the mu-form: one string for an infinitely deep type:

```
{"doc":{"label":"start","then"?:{"label":"finish","then"?:$.schema.Step}},
 "schema":{"Step":{"label":string,"then"?:$.schema.Step}}}
```

Mutual recursion (`A` referencing `B` referencing `A`) works the same
way, and so does a recursive [alias](#aliases-), which is enough to
write the JSON value space in one line:

```aon
%json = null|boolean|number|string|[&: %json]|{ &: %json }
x: %json & { a: [1 "two" b:true] }
```

```json
{"x": {"a": [1, "two", {"b": true}]}}
```

[Subsumption](#subsumption) over an unexpanded recursive position
answers `undecided` rather than guessing. The degenerate
self-reference with no structure at all (`a: $.a`) is a residual that
can never expand: its canon is exactly `{"a":$.a}` and generation
refuses with `recursion_unexpanded`. A cycle THROUGH other values
(`a:$.b b:$.a`) is still `path_cycle`: two references chasing each
other name no definition at all.

For the recipe form see
[Define a recursive schema](/how-to/define-a-recursive-schema); the
live version, with its checks, is
[use-cases/13-recursive-schema](/use-cases/13-recursive-schema).

## Variables `$name`

`$name` (a bare name with no leading dot) is never resolved from the
document. The calling program supplies it (see
[API reference](/docs/reference-api#variables)). The shared test set binds
`foo=11`, `bar="hello"`, `flag=true`, `obj={x:1}`:

```
a:$foo               → {"a":11}
a:$bar               → {"a":"hello"}
a:$obj               → {"a":{"x":1}}
a:$foo & number      → {"a":11}            (variables unify like values)
```

An unknown variable is a `Cannot resolve` error.

## Aliases `%`

An **alias** is a name for a value, written with a leading `%`.
`%name = value` at the top level of a file declares one; `%name` in
value position uses it. The `=` is the declaration operator, and it is
an operator nowhere else: `foo = 1` without the sigil is not a
declaration, and neither it nor `a: x=y` is a value: a `=` outside a
declaration is punctuation outside its syntax, refused with
`[aontu/bare_punct]` (see [Lexical structure](#lexical-structure)).
Unlike a
[reference](#references-and-paths), which spells a path into the tree,
an alias names the value directly and belongs to no path:

```aon
%port = integer & min(1) & max(65535)

listen: %port
listen: 8080
admin: %port
admin: 443
```

```json
{ "listen": 8080, "admin": 443 }
```

**The declaration is not part of the document.** It does not generate,
it is not a key `close()` counts, and it does not appear in canon, so the file above and the file with
`integer & min(1) & max(65535)` written out at both keys are the same
document and produce the same [`aon1-` hash](#canonical-form). That is
the whole of what an alias is: a name for a value, and nothing else.

**An alias key declares a value and creates a field.** `%name: value` is
shorthand for `name: %name = value`. The field keeps the value at its
written position, and the alias belongs to the file. This form works
at the root, inside nested maps, and in list elements. Alias declarations
require a map-root document; a root list with declarations is refused
with `alias_not_toplevel`. Wrap that list in a field. Quoting the key,
`"%name": value`, creates an ordinary key with the sigil in its name.

```aon
schema: type({ %row:name:string })
item: %row & { name:example }
```

```json
{ "item": { "name": "example" } }
```

**Inside a spread template.** `{&: {a: %D}}` does not resolve the
reference when it is written (a template applies to children that have
not arrived) so the reference stands in the evaluated document. Canon
spells it as the value it names, at any depth: `%u = integer` with
`t: {&: %u}` canons as `{"t":{&:integer}}`, and the file produces the
same [`aon1-` hash](#canonical-form) as the file with `integer`
written in the template. A template that reads its own position, such
as `%row = {name: key()}`, canons as the template (`{"name":key()}`),
not as what `key()` answered at the declaration. One reference keeps
its name: a recursive alias's reference to itself inside its own
template (`%json = null | boolean | number | string | [&: %json] |
{&: %json}`), which no finite text can write out. Such a document
generates and hashes, and its canon is the same in both
implementations, but the canon does not reparse on its own.

**An alias is not a path segment.** `$.%foo` is refused, at any depth:
the alias namespace and the path namespace are disjoint, and an alias
is reached by writing `%foo` and only that.

**A declaration sits at the root of the document.** A nested
`x: { %a = 1 }` is refused: `%a` resolves from the root, so a nested
declaration would be erased from the output (it *is* a declaration) and
still unreachable by any reference (it is *not* at the root): a name
that exists nowhere.

Where the declaration *lands* is what decides this, not where it was
written, which is what makes the two include shapes differ:

- `a: @"./f.aon"` is **refused** if `f.aon` declares an alias. The
  declaration is at the root of its own file but not of the document,
  and left writable a `%b` in the *including* file is what `f.aon`'s own
  `%b` would reach.
- `@"./f.aon"` spliced at the root is **accepted**. There is one root map,
  so there is no second scope for a name to leak out of, and the
  declaration is a declaration of that one document.

**A declaration may also prefix a value**, and written that way it is
accepted wherever it sits. `%name = ` in front of any value, to the
right of a colon or as a list element, declares the name for the
document and leaves the value alone:

```aon
x: %a = 1
y: %a
```

```json
{ "x": 1, "y": 1 }
```

This is what a key declaration cannot do, and the reason both forms
exist. A key leaves a field behind: `%a: 1` names the value and emits
`a` beside it. A prefix leaves the document as it was, so a shape can
be named exactly where it is used without a key appearing to say so.
The value stays where it was written and at its own path, so `x` above
is still `1`, and nothing else is added. Either form binds the name for
the file rather than for the place it sits, so either resolves from
anywhere, and two declarations of one name unify whichever form each
was written in and wherever each sat.


**A name belongs to the file that declares it.** An include carries a
file's *values* across the boundary and never its names, in either
direction: an included file cannot see a name the including file
declared, the including file cannot see a name the included file
declared, and two files that declare one name hold two names that never
meet. A reference resolves where it
was written rather than where it lands, so a spread template written in
one file still names its own file's declaration when it is instantiated
against another file's data.

A name crosses where both files say so, and nowhere else: the declaring
file publishes it with [`export`](#publishing-a-name-export), and the
using file asks for it by name with [the
destructure](#taking-a-name-the-destructure).

**The `%` is part of the name.** A quoted `"%a"` is an ordinary key or
string, and a `%` anywhere but on an alias name is refused like any
other stray punctuation (`b: 50%` is `[aontu/bare_punct]`; write
`"50%"`):

```aon
a: "%foo"
b: "50%"
```

```json
{ "a": "%foo", "b": "50%" }
```

An alias resolves exactly the way a path reference does, which is where
its properties come from rather than from rules of its own:

- **Order is irrelevant**: a use may precede its declaration.
- **An alias may name another alias**, and a cycle is refused. So is a
  cycle that runs through the document (`%a = $.x` with `x: %a`), because
  there is one reference graph, not two.
- **Two declarations of one name unify**, exactly as two statements for
  one key do: `%n = 1` with `%n = integer` is `1`, and `%n = 1` with
  `%n = 2` is a conflict.
- **A use of an undeclared name is refused**, naming the name.

**Expansion is bounded by size.** A name built from other aliases
expands to the product of what they hold, so a file that fits on a
screen can describe a document that does not fit in memory: twenty
declarations of the shape
`%a20 = [%a19, %a19]` reach a million nodes. The expanded size is
counted before evaluation and refused over `trust.budget.alias` with the
code `alias_budget`. Expansion always terminates, whatever the budget,
because an alias takes no parameters, a cycle is refused, and a file
declares finitely many names: the bound is about size alone, so raising
it is the repair where the document is meant and the machine can hold
the result.

Aliases are not passed to generated children: a spread template sees the
*expansion*, so children are constrained by the value and acquire no
name.

```aon
%row = { kind:string id:integer }

table: { &: %row a: { kind:user id:1 } b: { kind:user id:2 } }
```

```json
{ "table": { "a": { "kind": "user", "id": 1 },
             "b": { "kind": "user", "id": 2 } } }
```

### What a finding says about a name

A value that arrives through a name has two places: where the source
writes it, and where the document asks for it. A finding names both. The
frames give the value, what it met, and the reference that carried it:

<!-- test: skip an abridged finding; its two frames are pinned by alias.tsv's alias-finding-names-the-use and alias-finding-marks-the-use -->
```sh
$ aontu conflict.aon
[aontu/scalar_value]: Cannot unify values at path $.a
...
 Cannot unify value: 1 with value: 2
  --> conflict.aon:1:6
  1 | %p = 1
           ^ value was: 1

 Value arrived through %p
  --> conflict.aon:2:4
  2 | a: %p
         ^ used %p here
```

A value that arrives by an ordinary path reference has no name to blame,
so a finding adds no such frame.

### The shorthand: `{ %a %b }`

In value position a set of names stands for the map that binds each one
under its own name: `{ %a %b }` is `{ a: %a, b: %b }`, key without the
sigil and value with it.

<!-- test: scenario alias-shorthand -->
```aon
%kind = "user"
%limit = 10

defaults: { %kind %limit }
```

```json
{"defaults":{"kind":"user","limit":10}}
```

The sigil is what makes the sugar unambiguous, so `{ a, b }` stays the
parse error it has always been, and a set may still separate its names
with commas. Canon expands the shorthand, so a document written short and the
same document written long are one `aon1-` digest, which is what makes
this sugar rather than a second way to say something else.

A rename needs no shorthand, because `a: %b` already spells it.

### Publishing a name: `export`

`export({ %a, %b })` declares which of a file's names another file may
take. It is a declaration and not a value, so a file generates the same
document with it as without it:

```aon
%port = integer & min(1) & max(65535)

export({ %port })

listen: %port
listen: 8080
```

```json
{ "listen": 8080 }
```

It takes a set of alias names and nothing else. Every other argument is
refused with `export_arg`: `export({ port })` names a key, which already
crosses the boundary as a value; `export(%port)` names an alias but not
a set; and `export({%})` is the wildcard, which belongs on the taking
side. A name a file declares and does not export stays that file's own.

### Taking a name: the destructure

`{ %a } = @"./f.aon"` places `f.aon`'s values exactly as `@"./f.aon"`
places them, and also binds `%a` in the taking file's scope. There is no
`import` verb: the include already crosses the boundary for values, and
the pattern on its left crosses it for names. Write the publishing file
as `types.aon`:

<!-- test: scenario alias-destructure -->
<!-- test: file types.aon -->
```aon
%uint8 = integer & min(0) & max(255)

export({ %uint8 })

defaults: retries: 3
```

and take its name from `main.aon`:

<!-- test: file main.aon -->
```aon
{ %uint8 } = @"./types.aon"

level: %uint8
level: 200
```

<!-- test: run -->
```sh
$ aontu -c main.aon
{"defaults":{"retries":3},"level":200}
```

The file's values arrive whether or not a name is asked for, which is
what makes the pattern additive rather than a filter.

`{%}` takes every name the other file exports, and only those: the
publishing file chose the set. Asking for a name that file does not
export is refused with `import_not_exported`, which names the name; the
destructure asked, so the refusal stands whether or not anything goes on
to use the name. A name that arrives this way meets a local declaration
of the same name rather than replacing it, exactly as two declarations
in one file meet.

**A file publishes what it declares.** A name that merely arrived in a
file through an include belongs to the file that wrote it, so
re-exporting it is refused: publishing someone else's private name is
not a file's to do.

**Rename what you take with `%local: %remote`.** Both sides carry the
sigil, because both are names; the left is what this file calls it and
the right is what the other file publishes. Two files publishing one
name is the case it answers, and nothing else does.

**A destructure may also sit under a key.** The values land where the
head stands and the names it binds are the document's, so a file can be
mounted at a path and still be taken from. Both forms read the same
`types.aon`:

<!-- test: scenario alias-destructure-more -->
<!-- test: file types.aon -->
```aon
%uint8 = integer & min(0) & max(255)

export({ %uint8 })

defaults: retries: 3
```

`rename.aon` takes `%uint8` under a name of its own:

<!-- test: file rename.aon -->
```aon
{ %port: %uint8 } = @"./types.aon"

listen: %port
listen: 200
```

<!-- test: run -->
```sh
$ aontu -c rename.aon
{"defaults":{"retries":3},"listen":200}
```

and `mount.aon` puts the same file's values under `svc`:

<!-- test: file mount.aon -->
```aon
svc: { %uint8 } = @"./types.aon"

level: %uint8
level: 200
```

<!-- test: run -->
```sh
$ aontu -c mount.aon
{"level":200,"svc":{"defaults":{"retries":3}}}
```

The other file's own declarations come up to the document root with its
values. Without that a file that uses the name it publishes could not be
mounted at all, since an alias resolves from the root and its
declaration would have landed under the key.

**A wrapped root still publishes.** `open(...)` and `copy(...)` hold the
document as their one argument, so such a file publishes what its map
declares. One limit: the wrapper's argument may not use the name the file
publishes, because the declaration rises to the taking document's root,
out of the argument's reach. That include fails with `conjunct`.

`export` does not rename: a file publishes what it has, and the taking
file renames what it takes, so `export({ %a: %b })` is refused with
`export_arg`.

## The `+` operator and grouping

`+` adds numbers and concatenates strings; it chains left-to-right.
Parentheses group sub-expressions and a leading unary `+` is allowed.

```aon
a: 1 + 2
b: 1 + 2 + 3
c: 1.5 + 2
d: p + q
e: p + q + r
f: (1 + 2)
g: ( + 3 + 4)
h: i: j: 10 + 5
```

```json
{"a":3,"b":6,"c":3.5,"d":"pq","e":"pqr","f":3,"g":7,"h":{"i":{"j":15}}}
```

**Result kind: the exact ladder.** `+` never introduces a kind
narrower than its operands, and it never demotes. The three exact
leaves form a ladder,

```
integer  <  biginteger  <  bigdecimal
```

and a sum of exact operands takes the **widest** leaf present and is
computed exactly. `float` is not on that ladder: it keeps its classic
contagion with `integer` alone.

```
x:1+2                 → integer 3      canon {"x":3}
x:1+2.0               → float 3        canon {"x":3.0}
x:1.5+1.5             → float 3        canon {"x":3.0}
x:1+0d2               → biginteger 3   canon {"x":0d3}
x:0d2+0d3             → biginteger 5   canon {"x":0d5}
x:1+0d0.5             → bigdecimal 1.5 canon {"x":0d1.5}
x:0d2+0d0.5           → bigdecimal 2.5 canon {"x":0d2.5}
x:(1+2) & integer     → {"x":3}
x:(1.5+1.5) & integer → error          (the sum is float kind)
x:(1+0d2) & integer   → error          (the sum is a biginteger)
```

The widest operand anywhere in a chain decides, whichever end it
arrives at: `x:1+2+0d3` → `0d6`. A `*`-preferred operand contributes
its preferred value's kind. Results never demote, so a biginteger sum
that would fit an `integer` stays a biginteger, and an integral
bigdecimal sum stays a bigdecimal: `x:(0d0.5+0d0.5)&0d1.0` is
`0d1.0`, while `& 0d1` is a conflict.

**Exact arithmetic is exact.** Adding bigdecimals aligns the scales
and adds; nothing is rounded and no precision context is consulted, so
the answers are the ones decimal arithmetic gives on paper:

```
x:0d0.1+0d0.2          → {"x":0d0.3}    (binary64: 0.30000000000000004)
x:0d0.1+0d0.2+0d0.3    → {"x":0d0.6}    (binary64: 0.6000000000000001)
x:0d1.23+0d4.567       → {"x":0d5.797}
```

The same sums, run through the CLI:

<!-- test: scenario exact-sums -->
<!-- test: run -->
```sh
$ echo 'x: 0d0.1 + 0d0.2' | aontu
{
  "x": 0.3
}
$ echo 'x: 0d0.1 + 0d0.2 + 0d0.3' | aontu
{
  "x": 0.6
}
```

A sum too wide to hold is refused, never approximated: see
[the exactness budget](#the-exactness-budget).

**Float and exact never mix.** An exact value never silently becomes a
binary float, in either operand order. There is no promotion for this
pair; it is a hard error.

```
x:1.0+0d2   → error   (a float and a biginteger cannot mix)
x:0d0.5+1.0 → error   (the same refusal, operands the other way round)
```

Parentheses only decide *where* the refusal happens: `x:(1+0d2)+1.0`
and `x:(1+2.0)+0d3` both fail.

**Integer sums are exact too.** `integer + integer` is computed
exactly, and the answer must then satisfy the same storage contract
its operands did: integral, inside the int64 window, *and* exactly
representable as a double. A sum that fails any of the three is a
located error naming the `0d` escape, rather than a rounded value:

```
x:4503599627370496+4503599627370496 → {"x":9007199254740992}   (2^53)
x:9007199254740992+2                → {"x":9007199254740994}
x:9007199254740992+1                → error: … not exactly representable
x:9007199254740992+0d1              → {"x":0d9007199254740993}  (the escape)
x:4611686018427387904+4611686018427387904 → error (2^63, past int64)
```

**String concatenation renders digits, not kinds.** A `+` with a
string operand concatenates, and the numeric side contributes its
plain digits with **no `0d` marker**: the marker is canon decoration,
and it never leaks into a string.

```aon
a: q + 0d5
b: q + 0d0.1
c: 0d5 + q
d: q + 0d1e3
e: q + 0d1000
```

```json
{"a":"q5","b":"q0.1","c":"5q","d":"q1000.0","e":"q1000"}
```

The digits are the value's own rendering minus the marker, so the
integral bigdecimal at `d` keeps its one decimal place while the
biginteger at `e` does not. The plain family is unchanged and still
coerces with JavaScript rules, which drop a trailing `.0`:
`x:a+1.0` → `"a1"`, not `"a1.0"`.

**Two lists concatenate.** A `+` whose operands are both lists answers
one list: the left's elements, then the right's, each cloned into its
new index. An empty operand contributes nothing. This is how a
document assembles a list from a written head and a computed tail:

```aon
a: [1] + [2]
b: [] + [2]
c: ["x"] + each(["y"], _)
```

```json
{"a":[1,2],"b":[2],"c":["x","y"]}
```

A list with a scalar is not a sum and is refused, in either order.

**A sum of an absence is absent.** `maybe()` travels through `+` the
way it travels through a call, on either side and whatever the other
operand is, so an optional tail needs no guard:

<!-- test: run -->
```sh
$ echo 'a: 1  b: [1] + maybe($.gone)  c: "x" + maybe($.gone)' | aontu
{
  "a": 1
}
```

See [Optional input: `maybe`](#optional-input-maybe).

Unary `-` negates a numeric operand exactly. It binds tighter than
`+`, `&` and `|` (`-1 & integer` is `(-1) & integer`) and, like `+`,
never narrows the kind and never yields `-0`.

## Functions

aontu provides a fixed set of built-in functions. There are no
user-defined functions. This alphabetical index lists every built-in;
the links lead to its detailed behaviour and examples.

The argument modes describe how a call uses its arguments: `template`
is instantiated for a selected value, `trial` supplies a condition,
`projector` names a field or index, `capture` preserves a path's spelling,
and `text` supplies literal text. An unmarked argument supplies a value.

For collection operations, compare [pack and each](#generating-children-pack-and-each),
[the `_ & …` idiom](#the-_---idiom-construction-and-bound), [filter and
match](#selecting-filter-and-match), [pick](#projecting-fields-pick),
and [emit](#transforming-emit).
`pack` and `each` construct collections; `filter` selects members;
`pick` projects a field; `emit` applies a rule table and flattens its output.

### `abnf(g: string) : string`

Compile an RFC 5234 ABNF grammar and answer its source, so a parser is an ordinary string. A grammar that does not compile is refused here, once, rather than at every site that parses with it. See [grammars](#grammars-abnf-and-parse).

Example: `G: abnf("v = 1*DIGIT")`

### `above(n: number|string) : constraint`

Constrain a numeric or string value to be strictly greater than a bound. See [bounds](#the-constraint-algebra).

Example: `integer & above(0)`

### `acyclic() : constraint`

Require the edges of a declared relation to contain no cycle. See [declared relations](#declared-relations).

Example: `rel() & acyclic()`

### `add(a: number, b: number) : number`

Add two numbers under the [number-tower rules](#arithmetic-add-sub-mul-div-mod-rem).

Example: `add(2, 3)` → `5`

### `below(n: number|string) : constraint`

Constrain a numeric or string value to be strictly less than a bound. See [bounds](#the-constraint-algebra).

Example: `integer & below(10)`

### `close(m: any) : any`

Seal a map/list against extra keys.

Example: see [closed values](#closed-values-close--open)

### `content(spec: string|map) : map`

A text node of the [component tree](#generation): a span of target
text, added with no newline of its own, which is the whole difference
from `line`. A bare string fills `src`, and an empty span is a value
rather than a mistake.

Example: `content("export const N = 1\n")`

### `copy(v: any) : any`

Deep copy of a value or referenced node; clears `type`/`hide` marks.

Example: `copy({a:1,b:2})`→`{a:1,b:2}`; `copy($.x)`

### `copyfiles(spec: string|map) : map`

A copy node of the [component tree](#generation): files copied
verbatim from `from` into the output. Named `copyfiles` because `copy`
already copies a VALUE.

Example: `copyfiles("assets")`

### `deprecate(v: any, r?: map) : any`

Mark `x` deprecated; unifies exactly as `x`, and the record `m` (`{msg?, use?, since?}`, all strings; `use` is a path spelled as a string) rides the result through meets, reference clones and spread applications. Canon renders the call back; generation is unchanged. The point-of-use surfaces: a vet `deprecated` warning, the LSP Deprecated tag, and `aontu breaking --allow-deprecated-removal`.

Example: `port: deprecate(*8080|integer, {msg:"renamed", use:"$.listen", since:"2.0.0"})`

### `div(a: number, b: number) : number`

Divide two numbers; integer division truncates towards zero. See [arithmetic and refusals](#arithmetic-add-sub-mul-div-mod-rem).

Example: `div(7, 2)` → `3`

### `each(d: map|list, template t: any) : list`

Construct one list element per source child by instantiating a template with `_` bound to that child. See [form](#each-the-order-preserving-map).

Example: `each([a, b], upper(_))` → `["A", "B"]`

### `emit(s: map|list, template t: map|list) : list`

One flat list of pieces from a selection and a rule table: for each node, the first template whose `match` it already satisfies, its `body` instantiated at that node. See [Transforming](#transforming-emit).

Example: `lines: emit($.services, {match:{pin:string}, body:[.pin]})`

### `esc(s: string, variant?: string) : string`

Escape a string using a named convention; the default is JSON-style double-quoted text. See [escaping](#escs-variant-and-uscs-variant).

Example: `esc("<a>", xml)`

### `file(spec: string|map, children?: list) : map`

A file node of the [component tree](#generation), named by `name` and
holding content, lines, fragments, injections, and copies: one file of
the output. Wherever `line` is admitted a bare string stands for it,
which is what a template body line becomes.

Example: `file("index.ts", ["export {}\n"])`

### `filter(d: map|list, trial c: any) : map|list`

The children of `d` that ALREADY satisfy `c`: the meet with `c` changes nothing. Keys kept for a map, order for a list; the rest are dropped, not refused. See [Selecting](#selecting-filter-and-match).

Example: `debugged: filter($.services, {debug:true})`

### `folder(spec: string|map, children?: list) : map`

A folder node of the [component tree](#generation), named by `name`
and holding folders, files, and copies: one directory of the output.

Example: `folder("src", [file("index.ts")])`

### `fragment(spec: string|map, children?: list) : map`

A fragment node of the [component tree](#generation): a file read from
`from`, reaching the output with its `<[SLOT]>` markers filled by the
slots beneath it.

Example: `fragment("head.ts", [slot("body")])`

### `greatest(d: map|list) : number`

Return the greatest numeric member, preserving its kind. An empty collection is refused. See [aggregates](#aggregating-sum-least-greatest).

Example: `greatest([2, 7, 4])` → `7`

### `hide(v: any) : any`

Mark `x` as hidden.

Example: `hide(world) & string`→`"world"`

### `inject(spec: string|map, children?: list) : map`

An injection node of the [component tree](#generation): a body written
between markers in an output file that already exists.

Example: `inject("routes", [line("app.use(r)")])`

### `inverse(projector k: string) : constraint`

Require every edge of a declared relation to have a corresponding edge under the named inverse. See [declared relations](#declared-relations).

Example: `rel() & inverse(usedBy)`

### `join(d: map|list, sep?: string) : string`

Join collection members as text, with an optional separator. See [join](#folding-to-a-string-join).

Example: `join([a, b], ", ")` → `"a, b"`

### `key(up?: integer|biginteger) : string`

The ancestor key `n` levels up (`0` = own key, default `1` = parent). `n` must be an **integer** (`integer` or `biginteger`); anything else is an error. A level beyond the top of the path yields `""`.

Example: at `a:b:c`: `key()`→`"b"`, `key(0)`→`"c"`, `key(2)`→`"a"`, `key(2.0)`→error

### `least(d: map|list) : number`

Return the least numeric member, preserving its kind. An empty collection is refused. See [aggregates](#aggregating-sum-least-greatest).

Example: `least([2, 7, 4])` → `2`

### `length(n: number|constraint) : constraint`

Constrain a string length or collection size. See [length semantics](#length-semantics).

Example: `list() & length(min(1))`

### `line(spec: string|map) : map`

A text node of the [component tree](#generation): a span of target
text with a newline added, which is the whole difference from
`content`. An empty span is a blank line.

Example: `line("import fs from 'fs'")`; `line("")` is a blank line

### `list() : list`

The list **kind**: admits any list, defaults to nothing.

Example: `y: list() & [1]`→`[1]`

### `listitems(spec: map, children?: list) : map`

A repetition node of the [component tree](#generation), over the list
at `item`: its children are written once for each member. The bag is
required and must be a list: a missing one would render nothing,
silently.

Example: `listitems({item: $.rows}, [line("x")])`

### `lower(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string`

Lowercase a string, or a run of it; **floor** of a number, keeping the argument's kind. The range is `upper`'s; see [`upper`](#uppers-stringnumber-start-integerbiginteger-len-integerbiginteger--string).

Example: `lower(ABC)`→`"abc"`, `lower("FOO",1,-1)`→`"Foo"`, `lower("FOOBAR",-3,-1)`→`"fooBAR"`, `lower(1.9)`→ float `1`

### `map() : map`

The map **kind**: admits any map, defaults to nothing. See [Container kinds](#container-kinds-map-and-list).

Example: `y: map() & {a:1}`→`{a:1}`; `y: map()`→ error

### `match(s: any, ...pr: (trial any, any), dflt?: any) : any`

The result of the first pattern `v` already satisfies; a trailing argument is the default. No match and no default is an error naming the patterns tried.

Example: `size: match($.tier, small, {cpu:1}, {cpu:2})`

### `max(n: number|string) : constraint`

Constrain a numeric or string value to be at most the bound. See [bounds](#the-constraint-algebra).

Example: `integer & max(10)`

### `maybe(v: any) : any`

The value when it resolves, and **absence** when the only thing wrong is that it is not there. See [Optional input](#optional-input-maybe).

Example: `maybe($.gone)` generates nothing; `maybe($.here)` is `$.here`

### `min(n: number|string) : constraint`

Constrain a numeric or string value to be at least the bound. See [bounds](#the-constraint-algebra).

Example: `integer & min(0)`

### `mod(a: number, b: number) : number`

Compute a modulo whose nonzero result follows the divisor's sign. See [arithmetic](#arithmetic-add-sub-mul-div-mod-rem).

Example: `mod(-7, 3)` → `2`

### `move(v: any) : any`

Resolve reference `p`, dropping unresolved optional keys.

Example: `m:{x?:number,y:Y} n:move($.m)`→`n:{y:"Y"}`

### `mul(a: number, b: number) : number`

Multiply two numbers under the [number-tower rules](#arithmetic-add-sub-mul-div-mod-rem).

Example: `mul(2, 3)` → `6`

### `must(trial c: any, text msg: string) : constraint`

Apply an evaluation-time condition with an author-supplied failure message. See [must](#band-b-must).

Example: `must(min(1), "must be positive")`

### `neq(...vals: number|string) : constraint`

Exclude the listed numeric or string values. See [constraint atoms](#the-constraint-algebra).

Example: `string & neq("reserved")`

### `nom(name: string, style?: string|list, acronyms?: list) : string|map`

One name in one spelling, or every spelling as a map when no style
is named: `camel`, `dot`, `kebab`, `pascal`, `path`, `snake`,
`text`, `title` and `upper`. An acronym list keeps `id` as `ID`.

Example: `nom("planet_body", pascal)` → `"PlanetBody"`

### `open(m: any) : any`

Reverse a `close`.

Example: `open(close({x:1})) & {y:2}`→`{x:1,y:2}`

### `pack(d: map|list, template t: any) : map`

One keyed child per child of `d`, each of them `t` cloned at that destination. Keys are the strings of a list, or the keys of a map. See [Generating children](#generating-children-pack-and-each).

Example: `deploy: pack($.names, {replicas:*2|integer})`

### `parse(g: string, v?: string) : map|list|constraint`

Parse a string under a grammar and answer what the grammar says it builds: the syntax tree, or the map or list a **value annotation** asks for. With no value, the grammar as a **constraint** on whatever meets it, answering that value unchanged. A failure to parse is a failure to unify. See [grammars](#grammars-abnf-and-parse).

Example: `parse($.G, "12")` → `{rule:"v" src:"12" kids:[...]}`; `*"" | parse($.G)`

### `path(capture p?: path) : path`

**capture** `p` as a path value: the spelling, never the resolution; with no argument, the path **kind**. See [First-class paths](#first-class-paths-pathp).

Example: `dep: path(.auth)` generates `".auth"`; `host: path()`

### `pick(d: map|list, projector k: string|integer) : any`

Project one field or index from every collection member into a list. See [pick](#projecting-fields-pick).

Example: `pick([{n:a}, {n:b}], n)` → `["a", "b"]`

### `pref(v: any) : any`

Mark `x` as preferred (same as `*x`).

Example: `pref(1)` canon `*1`; `pref(2),x:3`→`3`

### `project(spec?: string|map, children?: list) : map`

The root node of the [component tree](#generation); its `folder` is
the output directory and is the one prop that is not required.

Example: `project("./build", [folder("src")])`

### `re(text p: string) : constraint`

Constrain a string to match a portable regular expression. See [patterns](#re-and-the-portable-pattern-subset).

Example: `string & re("^[a-z]+$")`

### `refer(template t?: any) : constraint`

Constrain a field to a **path value whose address resolves**; `t`, if given, is unified into the target. The field keeps the address. See [Checked links](#checked-links-refert).

Example: `dependsOn: [&: refer($.aontu.System.Service), path($.services.auth)]`

### `rel(template t?: any) : constraint`

Declare a field as a relation and optionally constrain its targets. See [declared relations](#declared-relations).

Example: `dependsOn: rel() & [path($.auth)]`

### `rem(a: number, b: number) : number`

Compute the remainder of truncating division. See [arithmetic](#arithmetic-add-sub-mul-div-mod-rem).

Example: `rem(-7, 3)` → `-1`

### `rep(s: string, text p: string, text sub: string) : string`

Replace every pattern match in a string. See [replacement syntax](#reps-pattern-sub).

Example: `rep("a1b2", "[0-9]", "_")`

### `slot(spec: string|map, children?: list) : map`

A slot node of the [component tree](#generation), beneath a fragment:
the body that fills the marker of that name.

Example: `slot("body", [line("return 1")])`

### `sort(d: map|list, projector k?: string|integer, dir?: string) : list`

Order a collection's members into a list, by a projected field or by the members themselves. See [Ordering](#ordering-sort).

Example: `sort([3, 1, 2])` → `[1, 2, 3]`

### `split(s: string, sep: string|constraint) : list`

Split a string using a literal separator or a pattern constraint. See [split](#splits-sep).

Example: `split("a,b", ",")` → `["a", "b"]`

### `sub(a: number, b: number) : number`

Subtract the second number from the first. See [arithmetic](#arithmetic-add-sub-mul-div-mod-rem).

Example: `sub(7, 2)` → `5`

### `sum(d: map|list) : number`

Add the numeric members of a collection; an empty collection sums to zero. See [aggregates](#aggregating-sum-least-greatest).

Example: `sum([2, 3])` → `5`

### `super(t: any) : any`

The immediate parent type of `x`, structurally: a scalar's kind, a kind's parent, a container of its children's parents.

Example: `super(1)` → `integer`, `super(integer)` → `number`, `super({a:1})` → `{a:integer}`

### `translate(s: string, from: string, to?: string) : string`

Map the characters of `s` from one set to another. A range expands
(`a-z`), a short `to` pads with its last character, and an omitted
`to` deletes every character named in `from`.

Example: `translate("a-b-c", "-", "_")` → `"a_b_c"`

### `type(t: any) : any`

Mark `x` as a type/schema value.

Example: `type(1) & number`→`1`

### `unique(projector k?: string) : constraint`

Require distinct members, optionally comparing a named field. See [unique semantics](#unique-semantics).

Example: `list() & unique(id)`

### `upper(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string`

Uppercase a string, or a run of it; **ceiling** of a number, keeping the argument's kind.

`start` is a boundary. Zero or positive, the run begins there and reaches forward; negative, it counts from the end and the run stops there, the character it lands on being the first one left alone. `len` is how many characters; `-1`, which is also the default, is the whole source. Both ends clamp, so a run past either end does as much as exists. Indices are code points. A range on a number is refused.

Example: `upper(abc)`→`"ABC"`, `upper("foo",0,1)`→`"Foo"`, `upper("foo",1)`→`"fOO"`, `upper("foo",-1,2)`→`"FOo"`, `upper(1.1)`→ float `2`

### `usc(s: string, variant?: string) : string`

Decode text escaped with the named convention, refusing malformed input. See [escaping](#escs-variant-and-uscs-variant).

Example: `usc(esc("<a>", xml), xml)` → `"<a>"`


### Parent types

`super(x)` answers the immediate parent type of its **argument**. For
a concrete scalar that is the scalar's kind, and for a kind it is the
kind's own parent: `number` sits above the four numeric leaves, so
the numeric ladder has a real middle rung. For structured arguments,
`super` descends: a map lifts to the map of its values' parents (key
optionality, closedness and any `&:` spread carried over, the spread
template lifted), a list lifts element by element, a preference lifts
to its value's parent, a disjunction lifts arm by arm, and a
constraint lifts to the kind it constrains: its absorbed leaf kind
when it has one, otherwise the domain its atoms compare in.

<!-- test: scenario super-parent-type -->
<!-- test: run -->
```sh
$ echo 'a: super(1)  b: super(1.5)  c: super(integer)  d: super(number)' | aontu -c
{"a":integer,"b":float,"c":number,"d":top}
$ echo 'e: super({port: 8080, name?: web})  f: super([1, on])' | aontu -c
{"e":{"name"?:string,"port":integer},"f":[integer,string]}
$ echo 'g: super(*8080)  h: super(1|2)  i: super(min(3))  j: super(integer & min(3))' | aontu -c
{"g":integer,"h":integer,"i":number,"j":integer}
$ echo $?
0
```

The result is a type, so it constrains: lifting an example produces
a schema the example itself satisfies:

<!-- test: scenario super-as-schema -->
<!-- test: run -->
```sh
$ echo 'x: super({a:1}) & {a: 7}' | aontu
{
  "x": {
    "a": 7
  }
}
$ echo 'x: super({a:1}) & {a: 7.5}' | aontu
[aontu/no_scalar_unify]: Cannot unify values at path $.x.a
...
$ echo $?
1
```

The answer is `top` only where `top` is the immediate parent: the
root kinds (`number`, `string`, `boolean`), `top` itself, a
disjunction with an arm that lifts to `top`, and a constraint that
admits several container kinds (`length(n)` constrains strings, lists
and maps alike). Two edges are pinned in `test/spec/super.tsv`: a
recursion residual met by `super` stays a symbolic call (the finite
spelling of a lift that is itself recursive) which generation
refuses like any unresolved call, and `super(null)` answers the null
kind, which canon prints as `null`, the same spelling as the value.

### Rounding numbers

`upper()` and `lower()` round a number without narrowing it: the result
carries the *argument's* kind, so `upper(2)` is an integer `2` (and
unifies with `integer`) while `upper(1.1)` is a float `2` (and does
not). On the exact leaves they are exact ceiling and floor: no
binary arithmetic is involved, and the kind still survives:

```
x:upper(0d1.1)   → {"x":0d2.0}     x:upper(-0d1.5)  → {"x":-0d1.0}
x:lower(0d1.9)   → {"x":0d1.0}     x:lower(-0d1.5)  → {"x":-0d2.0}
x:upper(0d5)     → {"x":0d5}       (a biginteger is already integral)
x:upper(0d1.1) & bigdecimal → {"x":0d2.0}
x:upper(0d1.1) & biginteger → error   (rounding does not change the leaf)
```

A bigdecimal result is still a bigdecimal, so it keeps the one decimal
place its leaf always renders, even when the value is whole.

### Composing calls

Functions compose with operators, references, list elements, and the
preference mark:

```aon
a: upper(abc) + def
b: lower(1.1) + 2
c: foo
d: upper($.c)
e: [lower(A) lower(B)]
f: *upper(foo)
```

```json
{"a":"ABCdef","b":3,"c":"foo","d":"FOO","e":["a","b"],"f":"FOO"}
```

## Arithmetic: `add` `sub` `mul` `div` `mod` `rem`

Maths beyond `+` is spelled with **functions**. The tokens `-` `*` `/`
`%` stay reserved for the language's own use, so there is no infix
arithmetic to learn beyond `+` and unary `-`:

```aon
replicas: mul($.base.replicas, 2)
spare: sub($.quota.cpu, $.used.cpu)
shards: div($.total, $.per_shard)
```

Each takes exactly **two operands**, and both must be numbers. That is
what distinguishes `add` from `+`: the operator is polymorphic and will
happily concatenate, so a Kubernetes quantity written `"500m" + "500m"`
is the string `"500m500m"` and nothing complains. `add("500m","500m")`
is an error, because a function named for a numeric operation has no
business inventing a string.

```aon
a: add(1, 2)
b: sub(10, 3)
c: mul(6, 7)
```

```json
{"a":3,"b":7,"c":42}
```

A non-number operand is an `invalid-arg` error whatever its shape:
`add("a","b")`, `add(true,1)` and `sub(integer,1)` are all refused.

**Kind follows the operands** (R5, and the same
[exact ladder](#the-four-numeric-leaves) `+` uses): integer with
integer is an integer, anything with a float is a float, and a mixed
exact operation promotes to the widest leaf and never demotes.

```
x:mul(2,3)         → {"x":6}      integer
x:mul(2,1.5)       → {"x":3.0}    float — never narrowed to integer 3
x:add(1,0d2)       → {"x":0d3}    biginteger, the wider operand
x:mul(2,0d1.5)     → {"x":0d3.0}  bigdecimal
x:add(1.0,0d2)     → error, exact_float_mix — as with `+`
```

**Integer division truncates toward zero**, and `rem` and `mod` differ
only in whose sign the answer follows: `rem`'s the dividend's, `mod`'s
the divisor's. That is the whole reason both exist:

```aon
a: div(7, 2)
b: div(-7, 2)
c: rem(-7, 2)
d: mod(-7, 2)
e: rem(7, -2)
f: mod(7, -2)
```

```json
{"a":3,"b":-3,"c":-1,"d":1,"e":1,"f":-1}
```

`b` is `-3`, not `-4`: truncation, not flooring.

Three things are refused rather than answered, each because the answer
would be a value aontu cannot carry:

- **A zero divisor**, in every leaf including floats. A JSON superset
  has no notation for an infinity, so there is nothing `div(7,0)` could
  return (`divide_by_zero`).
- **A non-finite float result**: `mul(1.0e200,1.0e200)` overflows
  binary64 (`float_overflow`). The same check governs `+`.
- **`div`, `mod` or `rem` over a bigdecimal.** One third has no finite
  decimal form, so exact decimal division either rounds (the one thing
  that leaf exists to prevent) or refuses (`inexact_divide`). Scale to
  integers first, which is how money should be carried anyway (minor
  units as an integer), or use floats if an approximation is acceptable.
  Note `0d10` is a *biginteger*, not a decimal, so `div(0d10,0d4)` is
  `0d2`; it is `0d10.0` that is refused.

An exact result that will not store is refused too, exactly as a sum is
(`inexact_integer_sum`): `mul(4503599627370496,4503599627370496)` is an
error rather than a rounded answer, and `0d` operands compute it
exactly.

## Projecting fields: `pick`

`pick(data, key)` returns a list containing the named field from each
member of a map or list. Use it to turn records into the values that
an aggregate or a string join needs:

```aon
lines: [amountCents:1200 amountCents:450]
amounts: pick($.lines, amountCents)
total: sum($.amounts)
```

```json
{"amounts":[1200,450],"lines":[{"amountCents":1200},{"amountCents":450}],"total":1650}
```

`amountCents` is a field name supplied to the projector argument.
The bare word and the quoted string `"amountCents"` name the same key.
The result preserves each selected value's kind and structure; picking
a map-valued field returns that map as one element, without flattening it.

### Order and list indexes

A list is visited in source order. A map is visited in sorted-key order,
and its keys do not appear in the resulting list. For members that are
lists, supply a zero-based integer index:

```aon
records: { z:name:last a:name:first }
names: pick($.records, name)
first: pick([[9 8] [7 6]], 0)
empty: pick([], name)
```

```json
{"empty":[],"first":[9,7],"names":["first","last"],"records":{"a":{"name":"first"},"z":{"name":"last"}}}
```

The empty collection returns an empty list. As with `each`, hidden or
type-marked collection members and unfilled optional members are skipped.
This selection happens before `pick` reads the requested field.

### Missing fields and invalid arguments

Every selected member must contain the requested field or index.
A missing key, an out-of-range index, or a scalar member is `pick_key`.
The call refuses the projection instead of returning a shorter list:

<!-- test: scenario pick-missing-field -->
<!-- test: run -->
```sh
$ echo 'x: pick([{a:1}, {b:2}], a)' | aontu
[aontu/pick_key]: Cannot pick value at path $.x
...
$ echo $?
1
```

A non-collection input is `aggregate_data`. The key must be a string
name or an `integer` index; a float such as `0.0`, a kind, or a list is
`invalid-arg`. A missing argument is `func_arity`.

A projector names one key, not a dotted path expression. Project twice
to select through two levels:

```aon
records: [address:city:Dublin address:city:Cork]
cities: pick(pick($.records, address), city)
```

```json
{"cities":["Dublin","Cork"],"records":[{"address":{"city":"Dublin"}},{"address":{"city":"Cork"}}]}
```

### Choose projection or construction

Use `pick(records, name)` to extract a field. Use
[`each`](#each-the-order-preserving-map) when each output element needs
an expression or a new structure. The bound spelling `each(records, _ &
t)` unifies each source member with a template; it preserves that
member's information rather than extracting one field from it.

Compose the resulting list with [sum](#aggregating-sum-least-greatest)
for a total or [join](#folding-to-a-string-join) for a line of text.

## Optional input: `maybe`

A path that names nothing is `no_path`, and that is right: a typo
should be loud. It leaves a document that reads **optional** input with
nothing to say, though, because the miss refuses the whole call.
`maybe(v)` is the value when it resolves, and **absence** when the only
thing wrong is that it is not there.

**Absence generates nothing**, at a required key as readily as at an
optional one, and from a list without leaving a hole. That is the whole
difference from `top`, which is not generable and refuses with
`mapval_no_gen`.

<!-- test: run -->
```sh
$ echo 'a: 1  b: maybe($.gone)  c: [1, maybe($.gone), 2]' | aontu
{
  "a": 1,
  "c": [
    1,
    2
  ]
}
```

**A call on an absent argument is no call.** Absence travels through
every built-in, in any argument position, and through
[`+`](#the--operator-and-grouping), so a transform written against
optional input needs no guard around it.

<!-- test: run -->
```sh
$ echo 'a: 1  b: each(maybe($.tags), {t:_})  c: join(maybe($.tags), "-")' | aontu -c
{"a":1,"b":maybe(),"c":maybe()}
```

**Absence is the unit of `&`**, on either side, so meeting it with a
constraint leaves the constraint:

<!-- test: run -->
```sh
$ echo 'a: 1 & maybe($.gone)  b: maybe($.gone) & 2' | aontu -c
{"a":1,"b":2}
```

**Only a missing referent is forgiven.** A conflict inside the argument
is the document's own bug and is reported where it happened, not
swallowed:

<!-- test: scenario maybe-keeps-conflict -->
<!-- test: run -->
```sh
$ echo 'b: maybe(1 & 2)' | aontu
[aontu/scalar_value]: Cannot unify values at path $.b
...
$ echo $?
1
```

**It waits for the model.** A reference that has not resolved yet is
not a reference to nothing, so `maybe` fires only once the document has
settled, the way [`each`](#each-the-order-preserving-map) and
[`pack`](#generating-children-pack-and-each) do. A forward reference
therefore answers the value:

<!-- test: run -->
```sh
$ echo 'b: maybe($.x)  x: 1' | aontu -c
{"b":1,"x":1}
```

**It cannot make a containing map vanish.** Absence travels through a
call and out of a list element, not out of a map that still has other
keys: `{k:"frag", n: emit(maybe($.tags), t)}` drops `n` and keeps a
`{k:"frag"}` behind. Write the whole element as the optional thing, not
one of its fields.

**A constrained list refuses it.** Absence leaves a plain list without
a hole, but a list carrying a spread meets every element against the
spread's template, and absence is not a member that template admits:

<!-- test: scenario maybe-under-a-spread -->
<!-- test: run -->
```sh
$ echo 'x: ["a", maybe($.gone)]' | aontu -c
{"x":["a",maybe()]}
$ echo 'x: [&: string]  x: ["a", maybe($.gone)]' | aontu
[aontu/listval_no_gen]: Cannot resolve value at path $.x.1
...
$ echo $?
1
```

So an optional member of a list a schema constrains is written as an
optional KEY of the map that holds it, or the spread is dropped from
the list.

## Ordering: `sort`

Generation supplies two orders, and neither is the one a report or a
rendered file wants: a map generates in **sorted-key** order and a list
in **source** order. `sort(data)` is the third.

**It answers a list, from either container.** A map has no order of its
own to be put in, which is the reason `Semver` is a list as well.

<!-- test: run -->
```sh
$ echo 'a: sort([3, 1, 2])  b: sort({x:"c", y:"a"})' | aontu -c
{"a":[1,2,3],"b":["a","c"]}
```

**The second argument projects**, exactly as `pick`'s does: a key name
for a map member, an index for a list member.

<!-- test: run -->
```sh
$ echo 'a: sort([{n:"b"}, {n:"a"}], n)' | aontu -c
{"a":[{"n":"a"},{"n":"b"}]}
```

**The third is `asc` or `desc`**, and omitting it is `asc`. The
projector comes first, so a keyless descending sort writes the empty
projector, which means the member itself.

<!-- test: run -->
```sh
$ echo 'a: sort([{n:1}, {n:3}], n, desc)  b: sort([1, 3, 2], "", desc)' | aontu -c
{"a":[{"n":3},{"n":1}],"b":[3,2,1]}
```

**Equal keys keep source order**, in both directions. The source
position breaks every tie, which makes the order a total one, so the
two implementations answer the same list whatever their own sort does
with equals.

<!-- test: run -->
```sh
$ echo 'a: sort([{k:1,v:"a"}, {k:1,v:"b"}, {k:0,v:"c"}], k, desc)' | aontu -c
{"a":[{"k":1,"v":"a"},{"k":1,"v":"b"},{"k":0,"v":"c"}]}
```

**There are two orders and no third.** Numbers compare through the
exact comparator, never through binary64, so a bigdecimal and an
integer in one bag order by their values. Text compares by code point.
A bag that mixes the two, or that holds a boolean, a null or a
container, has no order to be put in and is refused (`sort_domain`). A
member with no key to order by is `sort_key`, for the reason
[`pick`](#projecting-fields-pick) refuses one: a shorter list is a
different answer. A direction naming no direction is `sort_dir`.

<!-- test: run -->
```sh
$ echo 'a: sort([0d9007199254740993, 9007199254740992])' | aontu -c
{"a":[9007199254740992,0d9007199254740993]}
```

**A sort sees the members generation emits**, the rule every bag reader
follows: a `hide()`- or `type()`-marked child is not one, and neither
is an optional key that generates nothing.

Composed with [`pick`](#projecting-fields-pick) it turns a bag of
records into an ordered line of source, and with
[`join`](#folding-to-a-string-join) into the text of one:

<!-- test: run -->
```sh
$ echo 'cols: [{n:"id"}, {n:"age"}]  sql: join(pick(sort($.cols, n), n), ", ")' | aontu -c
{"cols":[{"n":"id"},{"n":"age"}],"sql":"age, id"}
```

## Aggregating: `sum` `least` `greatest`

`length()` counts a bag; these three fold one. Each takes a **single
bag** (a list or a map) and walks the children the model already
holds:

```aon
lines: [1200 450 3000]
total: sum($.lines)
lowest: least($.lines)
peak: greatest($.lines)

hourly: { p50:12 p95:40 p99:91 }
spike: greatest($.hourly)
```

```json
{"lines": [1200, 450, 3000],
 "total": 4650, "lowest": 450, "peak": 3000,
 "hourly": {"p50": 12, "p95": 40, "p99": 91},
 "spike": 91}
```

A map is folded in **sorted-key order** and a list in source order,
which is `each`'s rule; for these three it changes nothing, since every
operation is commutative, but it is stated so that it cannot drift.

They are named `least` and `greatest` rather than `min` and `max`
because those two are already the constraint atoms for a lower and an
upper *bound*: `min(3)` means "at least 3", which is a statement about
a value, while `least($.xs)` picks an element out of a set. Two
different things do not share a spelling.

**`sum` folds with `add`**, so the whole [number tower](#arithmetic-add-sub-mul-div-mod-rem)
comes with it: a bag of integers sums to an integer, one float among
them makes the total a float, `0d` members keep it exact, and a total
that will not store is refused rather than rounded.

```
x:sum([1,2,3])         → {"x":6}       integer
x:sum([1,2.5])         → {"x":3.5}     float, by contagion
x:sum([0d1.5,0d2.5])   → {"x":0d4.0}   exact
x:sum([])              → {"x":0}
```

**`sum([])` is `0`, and `least([])` is an error.** Addition has an
identity, so the empty sum has an answer; comparison has none, and
answering with a zero or an infinity would be inventing a value the
data does not contain (`aggregate_empty`).

`least` and `greatest` return **one of the elements**, so the answer
keeps that element's own kind, and they compare with the tower's exact
comparator rather than through binary64: `0d9007199254740993` and
`9007199254740992` share a float image but are correctly ordered here.

A value that is not a bag is `aggregate_data`; a member that is not a
number is `invalid-arg`, reported against the aggregate the author
wrote rather than against the `add` inside it.

There is no `fold` combinator and will not be one: a fold takes a
function, and this language has no user functions to give it. These
three are total because the bag is finite, the operation is fixed, and
each child is visited once: the same argument that makes `each` safe.

## Folding to a string: `join`

`join(coll, sep?)` folds a bag into one string: every member rendered
as text, with `sep` between them. It is the counterpart of `sum`: one
takes a bag to a number, the other to a string.

<!-- test: scenario join-fold -->
<!-- test: run -->
```sh
$ echo 'ports: [8080, 443]  addr: join($.ports, "-")' | aontu -c
{"addr":"8080-443","ports":[8080,443]}
```

**The separator defaults to the empty string**, so `join(coll)` is
concatenation. That is why there is no `concat` and no `lines`: with a
separator argument, one function covers both.

<!-- test: run -->
```sh
$ echo 'a: join([x, y, z])  b: join([x, y, z], ", ")' | aontu -c
{"a":"xyz","b":"x, y, z"}
```

**A fold sees the members generation emits.** `join`, and with it
`each`, `emit`, `filter`, `pack`, `pick` and the aggregates, read a
bag's *members*: a `hide()`- or `type()`-marked child is not one, and
an optional key whose value generates nothing is not one, so a value
the document withholds from its output never reaches a string or a
total the document computes. Canon still shows the whole document; the
fold does not.

<!-- test: run -->
```sh
$ echo 'm: {a: "keep", b: hide("SECRET")}  s: join($.m, "-")' | aontu -c
{"m":{"a":"keep","b":"SECRET"},"s":"keep"}
```

A reference still lifts a hidden bag: `each($.schema.entities, _)`
under `schema: hide({…})` sees every entity, because there the mark
belongs to the schema, not to any one entity.

**`join` folds with `+`**, exactly as `sum` folds with `add`. The
number-to-text rule is therefore `+`'s own and not a second one: no
`0d` marker, no `.0` float suffix, and the exact digits of a big
integer.

<!-- test: run -->
```sh
$ echo 'a: join([1, 2.0, 0d0.5, true], "|")' | aontu -c
{"a":"1|2|0.5|true"}
```

**`join([])` is `""`**, concatenation's identity: the parallel of
`sum([]) == 0`, and the opposite of `least([])`, which refuses because
comparison has no identity to answer with.

A map folds in **sorted-key order** and a list in source order, which
is `each`'s rule and `pick`'s. For a generated file this matters: list
order is *source* order, so a list is what a transform should build
its lines in.

<!-- test: run -->
```sh
$ echo 'm: {b: B, a: A}  x: join($.m, ",")' | aontu -c
{"m":{"a":"A","b":"B"},"x":"A,B"}
```

Composed with `pick`, it is the step that turns a bag of records into
a line of source:

<!-- test: run -->
```sh
$ echo 'cols: [{n: id}, {n: email}]  sql: join(pick($.cols, n), ", ")' | aontu -c
{"cols":[{"n":"id"},{"n":"email"}],"sql":"id, email"}
```

**A member that is settled but not text is an error** (`join_member`),
raised at the member rather than at generation. `+` with a string on
the left *residuates* on a map or a null rather than refusing, so
folding blindly would report the failure late and name the whole call
instead of the member that caused it.

<!-- test: run -->
```sh
$ echo 'a: join([{x: 1}], ",")' | aontu
[aontu/join_member]: Cannot join value at path $.a
...
$ echo $?
1
```

**A member that is merely unresolved is not an error at all.** The call
stays residual and generation reports ordinary incompleteness, so
`join` can be written in a schema over data that has not arrived:

<!-- test: run -->
```sh
$ echo 'names: [string]  line: join($.names, ",")' | aontu -c
{"line":join([string],","),"names":[string]}
```

The separator must be a **string**. A number would render perfectly
well through `+` and is still refused: the separator is not a member of
the fold but the parameter naming the text between members, and
`join(x, 5)` is far likelier a mistake than an intent (`invalid-arg`).

A value that is not a bag is `aggregate_data`, as it is for the
aggregates.

## Text: `esc` `usc` `rep` `split`

Four ordinary string functions. They return values and compose with
`+`, and they know nothing about generation, but they are what a
generator needs, because a generator interpolates values into literals
and derives names from data.

### `esc(s, variant?)` and `usc(s, variant?)`

`esc` makes a string safe to place inside a literal; `usc` reads it
back out. **A variant names a convention, not a language**: several
languages share one convention, and one language has several: a C-family
literal escapes differently in each quote, and SQL spells a literal one
way and an identifier another.

| variant | convention |
|---------|------------|
| *(none)* | C / JSON, double-quoted: TypeScript, JavaScript, Java, C, C++, C#, Go, Rust, Swift, Kotlin, Scala and JSON itself |
| `sq` | single-quoted C-family |
| `sql` | standard SQL, which doubles the quote |
| `shell` | POSIX single-quote |
| `xml` | the five entities; covers HTML |
| `uri` | percent-encoding, RFC 3986 |
| `regex` | the metacharacters the pattern subset admits |

```aon
plain: esc("plain text")
inner: esc("it\'s", sq)
table: esc("o\'brien", sql)
markup: esc("<a>&", xml)
address: esc("a b/c", uri)
pattern: esc("a.b", regex)
```

```json
{"plain": "plain text", "inner": "it\\'s", "table": "o''brien",
 "markup": "&lt;a&gt;&amp;", "address": "a%20b%2Fc", "pattern": "a\\.b"}
```

**Escaping a value that was already safe changes nothing**, which is
what makes it cheap enough to do by default. An unknown variant is
refused at the call (`esc_variant`) rather than passed through, so a new
convention arrives by name rather than by a silent change in what an
existing one does.

**`usc` is the left inverse, and it is partial.** `usc(esc(s))` is `s`
for every `s` and every convention. The other direction does not hold:
several spellings escape to one value, so `esc(usc(t))` is `t` only for
canonically escaped `t`. Text with no original (a truncated code-point
escape, an escape the convention does not define, a lone quote where the
convention doubles it) is refused (`usc_malformed`) rather than answered
with a different string.

### `rep(s, pattern, sub)`

Every match of `pattern` in `s` replaced by `sub`. The pattern is the
**same portable subset [`re`](#re-and-the-portable-pattern-subset)
takes**, so a document has one regexp language rather than two. The
substitution is `$1` to `$9` for the numbered groups, `$&` for the whole
match and `$$` for a literal `$`.

```aon
day: rep("2026-09-04", "([0-9]+)-([0-9]+)-([0-9]+)", "$3/$2/$1")
words: rep("aim:ingest,process:episode", "[,:]", " ")
```

```json
{"day": "04/09/2026", "words": "aim ingest process episode"}
```

**It replaces every match**: a replace-the-first default silently does
the wrong thing in a generator that normalises separators, and anchoring
the pattern is how a document asks for one. A `$` naming nothing, or a group the pattern
has not got, is refused (`rep_sub`) rather than expanded to the empty
string: a file written with a hole in it and no complaint is the failure
that refusal exists to close.

### `split(s, sep)`

The fields of `s`. **A plain string separator is a literal and an
`re(…)` argument is a pattern**: the asymmetry with `rep` is deliberate,
since splitting is usually on a literal, and it removes the trap where
`split(v, ".")` silently cuts between every character.

```aon
fields: split("a,,b", ",")
chars: split("abc", "")
runs: split("a1b22c", re("[0-9]+"))
whole: split("abc", ",")
```

```json
{"fields": ["a", "", "b"], "chars": ["a", "b", "c"],
 "runs": ["a", "b", "c"], "whole": ["abc"]}
```

Empty fields are **preserved**, so `join` is the inverse:
`join(split(s, sep), sep)` is `s`. An empty separator yields the code
points, and a separator that does not occur yields the whole string as
one field.

## Linking: the tree is the namespace

A document is a tree, and its only names are tree paths. That is
deliberate, and it is the whole of the addressing story: there is no
second namespace, no registry of declared names, and nothing a document
can say that makes two positions one node.

Two consequences follow, and both are what the design is for.

**A model can be instantiated more than once.** Mount the same file at
two paths and you get two independent nodes, each with its own values.
Write the model as `model.aon`:

<!-- test: scenario reuse -->
<!-- test: file model.aon -->
```aon
auth: { port:80 region: *"eu"|string }
billing: dep: refer() & path(..auth)
```

and mount it twice from `main.aon`:

<!-- test: file main.aon -->
```aon
tenantA: m: @"./model.aon"
tenantB: { m:@"./model.aon" m:auth:region:"us" }
```

Each instance resolves its own internal link inside itself, and the
per-tenant override is an ordinary narrowing rather than a
contradiction. A global name on `auth` would have made the two
instances one entity and the second override an error, which is why
there are no global names.

**Bringing two descriptions into contact is something you write.**
Unification is path-aligned, so a catalog file and a deploy file that
describe the same real-world thing at different paths do not meet on
their own. Point one at the other and they do:

```aon
catalog: payments: { owner:"team-pay" tier:1 }
deploy: eu1: payments: $.catalog.payments & { replicas:3 tier:2 }
```

The two `tier` values now meet, and disagree, so the run fails at the
site that says so. A reference is directional (`deploy` is narrowed,
`catalog` is not) and that directionality is what keeps two unrelated
models from silently merging because they happened to choose the same
word.

## First-class paths: `path(p?)`

`path(p)` **captures** the path expression `p` as a value: the
spelling, never the resolution. A plain reference resolves; a capture
is the address itself, as data.

```aon
a: b: 1
emb: $.a.b # a reference: the value at the path
cap: path($.a.b) # a capture: the path itself
```

```json
{ "a": {"b": 1}, "cap": "$.a.b", "emb": 1 }
```

This is the one non-strict argument position in the language: every
other call reads its argument's value, `path(p)` reads its spelling. The
captured spelling is the address grammar `refer` reads (`$.a.b` from the
document root, `.b` from the sibling scope, one more leading dot per
parent step) and a bare dotted argument is relative (`path(q.r)` captures
`.q.r`).

A bare string is **never** a path: the call's own argument is the one
conversion the language has. A string *literal* argument is address text
(`path("$.a")` is the capture `path($.a)`), and text with no anchor is
**relative**: `path("auth")` is `path(.auth)`, the address the raw
spelling captures. A *computed* argument (an expression, a reference to
a string) evaluates first, and the result converts by the same grammar,
which is what makes an address buildable:

```aon
names: { web: {} db: {} }
accounts: pack($.names, { for:refer() & path("$.names." + key()) })
```

```json
{ "accounts": { "db": {"for": "$.names.db"}, "web": {"for": "$.names.web"} },
  "names": { "db": {}, "web": {} } }
```

Text that spells no address even once anchored (an empty string, an
empty segment (`"a..b"`), a broken `$` spelling) refuses at the call
(`path_address`); a number or a container argument is refused as
`invalid-arg`.

`path()` with no argument is the path **kind**: the set of all path
values. It sits under `string` in the kind lattice, so `string` admits a
path value and the string constraints apply to spellings, but the kind
does **not** promote: `path() & "$.a"` refuses (`no_scalar_unify`)
exactly as `integer & "x"` does, because outside the `path(...)` call a
string never becomes a path.

Everything else about a path value is what scalars already do, made
precise by three rules:

1. **Meets are syntactic, by the prefix rule.** Two path values meet
   when one spells a *prefix* of the other (the same anchor, the
   shorter path's segments starting the longer path) and the result is the
   **longer**: a path can always be told more precisely.
   `path($.a) & path($.a.b)` is `path($.a.b)`; incomparable
   spellings (`path($.a) & path($.b)`, or different anchors) refuse
   (`scalar_value`); and a path value refuses a plain string
   *literal* (`path($.a) & "$.a"` is `scalar_kind`) exactly as the
   number tower's leaves refuse each other. Subsumption follows the
   meet: a prefix subsumes its extensions.
2. **A path value is data.** `path($.nope)` generates `"$.nope"`:
   existence is `refer`'s contract, not the value's, so a document may
   address things outside this evaluation. `path(p) & refer()` is the
   checked link: see [Checked links](#checked-links-refert).
3. **Generation and canon.** A path value generates as its address
   string; its canonical form is the call (`path($.a.b)`), which
   reparses to the same value: the call form is the literal syntax
   for this kind.

The kind settles inside `type()` bodies, which a `refer` cannot
(see [Checked links](#checked-links-refert)), so a vocabulary can
declare a path-valued field for the data to meet:

```aon
Service: type({ host:path() })
db: $.Service & { host:path($.hosts.h1) }
hosts: h1: {}
```

```json
{ "db": {"host": "$.hosts.h1"}, "hosts": {"h1": {}} }
```

Pinned by [`test/spec/path.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/path.tsv).

## Checked links: `refer(t?)`

A reference (`$.a.b`) resolves by *cloning* its target into place, so
`dependsOn: [$.services.auth]` generates a full copy of the auth node
where the author meant a name. A bare string generates the name and
checks nothing. `refer` is the third option: the field keeps the
address string, and the language checks it.

```aon
services: auth: { kind:service port:8080 }
services: billing: dependsOn: [&: refer({ kind:service }) path($.services.auth)]
```

```json
{"services": {
   "auth":    {"kind": "service", "port": 8080},
   "billing": {"dependsOn": ["$.services.auth"]}}}
```

The list spread applies `refer` to every element, so `dependsOn`
generates a list of **addresses**, checked.

`refer(t)` says three things about the string it constrains:

1. It must be a **tree address**.
2. The address must **resolve** in this evaluation.
3. If `t` is given, `t` is unified **into** the target.

### Addresses

An address is a path, in the two spellings a reference already uses:

```
$.services.auth   from the document root
.auth             beside the link itself
..auth            one level up from there
```

`$.a.b` is absolute. A leading `.` reads the link's own sibling scope,
and every further dot is one step up: the same reduction a relative
reference performs. `$` alone is not an address: the whole document has
no enclosing position, so nothing could be written back into it.

Relative addressing is what makes a model reusable. A link written
`..auth` means a different node from each position the model is mounted
at, so the same file instantiated twice gives two self-contained
instances.

Only a [path value](#first-class-paths-pathp) can be an address: a bare
string never is (`refer() & "$.a"` refuses (`refer_address`)) and
`path("...")` is the one conversion. A second path peer refines the
address by the prefix rule (`refer() & path($.a) & path($.a.b)` links to
`$.a.b`), and a relative address that climbs off the top of the tree is
refused outright: no later pass can grow a tree upwards.

### Existence is decided, not deferred

A `refer` **residuates**: a target may be introduced by a later
conjunct, include or spread, so the constraint retries each pass
exactly as a forward reference does. But within one evaluation the
document-set is fixed, so existence *is* decidable: an address that
still names nothing at the last pass is a located error
(`refer_unresolved`), not something to check later.

### Constraints flow through links

`refer(t)` does not merely *test* the target against `t`; it unifies
`t` into it, at the position the address names:

```aon
a: p: 1
b: refer({ r:3 }) & path($.a)
```

```json
{"a": {"p":1, "r":3}, "b": "$.a"}
```

Referring to something as a `Service` makes it one, and if it cannot
be, the conflict is an ordinary located error. Check-only semantics
would be non-monotone (true, then false as the target grows), and the
lattice guarantee is that more information never falsifies what has
already been observed.

Constraints written *alongside* a refer constrain the **link**, not the
target: `refer() & string & re("auth$") & path($.services.auth)` checks the
address itself. They are held until the address arrives, and then meet
it.

### The argument is a template, not an address

`refer(t)` takes the value the **target** must satisfy. The address
comes from the `path()` beside it, never from the argument, so
`refer(key())` does not mean "link to the node this key names". It means
"the target must unify with whatever `key()` answers here", and `key()`
answers with a *string*, so the link is constrained to a target that is
that string. At the root of a document `key()` is `""`, which leaves
`refer("")`: a link with no address, which cannot generate.

```
link: refer(key())     → [aontu/mapval_no_gen] at $.link
                         value was: refer("")
```

**A key does not survive a reference.** `key()` is path-dependent (it
answers for the destination it lands at) and a reference is a new
destination, so referring to a field whose value came from `key()`
re-fires it at the referring site rather than carrying the target's
key across. There is no built-in that takes a `path()` value and
yields its last segment.

Generate the link and the name together instead, from the one place
the key is already in hand. Inside a `pack` template `key()` is the
child's own key, so it can build the address and stand as a value at
the same time:

```aon
services: { auth:port:8080 billing:port:9090 }
names: [auth billing]
links: pack($.names, { to:refer() & path("$.services." + key()) name:key() })
```

```json
{"services": {"auth": {"port": 8080}, "billing": {"port": 9090}},
 "names": ["auth", "billing"],
 "links": {"auth":    {"to": "$.services.auth",    "name": "auth"},
           "billing": {"to": "$.services.billing", "name": "billing"}}}
```

`to` is checked (a name with no service refuses) and `name` is the
same key as an ordinary string.

### The bundled vocabularies

**Five vocabularies ship with the engine**, served from it rather than
from disk, and **every one of them is named under `aontu:`**. That is
the whole rule: a language-supplied schema has one spelling, and the
scheme is what stops a file on disk from standing in front of it.

| name | what it is |
|---|---|
| `aontu:system` | ports, components and services: [below](#the-aontusystem-vocabulary) |
| `aontu:view` | the schema for one declaration of a [view document](/docs/reference-api#aontu-view), `$.aontu.View.Figure`, which types every option the verb reads so a typo is refused at evaluation |
| `aontu:profile` | a language declared as data, which `template` and `fmt` read through `--profile` |
| `aontu:lang/text` | the text profile |
| `aontu:lang/markdown` | the markdown profile |

The last three are described [after the system vocabulary](#the-aontu-models).

### The `aontu:` models

A name that begins `aontu:` is a **language-supplied model**, and it
resolves from the engine's own table and nowhere else: the memory,
module, file and package legs are never asked, so no file can shadow
one, and a name the engine does not serve is refused naming the set
rather than looked for on disk.

**Everything an `aontu:` model defines lands under the single root key
`aontu`**, so including one never takes a name a document wants:

| include | defines |
|---|---|
| `@"aontu:system"` | `$.aontu.System.Port`, `.Component`, `.Service`, `.Semver` |
| `@"aontu:view"` | `$.aontu.View.Figure` |
| `@"aontu:profile"` | `$.aontu.Profile`, `$.aontu.Lang` |

One key is reserved instead of six, it is named for the language
rather than for a domain, and `$.aontu` anywhere tells a reader at once
that the subtree is not the document's own.

**A path part that names a type is CamelCase.** That is why every
bundled key above is capitalised, and why the members under them
(`Port`, `Service`, `Figure`) always were: the case of a segment says
what kind of thing it names. It is a **convention and only a
convention**: the engine does not check it, `aontu vet` says nothing
about a lowercase `type()`, and a document is free to ignore it. The
bundled models follow it so there is one worked example to copy.

The SCHEME name is unaffected and stays lowercase: `@"aontu:system"`
loads the model, `$.aontu.System` is where its content lands, and a
source name is not a path. Write this as `models.aon`:

<!-- test: scenario aontu-models -->
<!-- test: file models.aon -->
```aon
@"aontu:profile"

aontu: Lang: { lang:"ocaml" template: { marker:"(*-" close:"*)" ext: [ml] } }
```

<!-- test: run -->
```sh
$ aontu models.aon
{
  "aontu": {
    "Lang": {
      "indent": {
        "unit": " ",
        "width": 2
      },
      "lang": "ocaml",
      "template": {
        "close": "*)",
        "ext": [
          "ml"
        ],
        "marker": "(*-"
      }
    }
  }
}
```

A name the engine does not serve is refused, and the refusal names
the set. Write this as `nope.aon`:

<!-- test: file nope.aon -->
```aon
@"aontu:nope"
```

<!-- test: run -->
```sh
$ aontu nope.aon
source not found: aontu:nope (the language-supplied models are aontu:lang/markdown, aontu:lang/text, aontu:profile, aontu:system, aontu:view)
$ echo $?
1
```

**`aontu:profile`** is the schema of a language profile: a language
declared as data, which `aontu template` and `aontu fmt` read through
`--profile`. It carries the language's `lang`, an `indent`, optionally
the comment forms, and the `template` block below. A profile is data
and only data. Its root is not `type()`-marked, because a profile is
read through generation; `$.aontu.Profile` names the schema with
`type()`, so naming it neither generates it nor asks a document to fill
it, and `$.aontu.Lang` is where one lands.

**A profile is where a language is configured.** Its `template` block
names the marker a generator written in that language carries and the
extensions that marker belongs to, so `aontu template` and `aontu fmt`
read one file rather than repeating a `--marker` flag. A marker carries
its own closer after a space where the opener does not imply one, which
is what reaches a block comment the engine has never seen:

<!-- test: skip the file it configures is the reader's own language -->
```aon
aontu: Lang: template: { marker:"(*-" close:"*)" ext: ["ml" "mli"] }
```

**`aontu:lang/text`** and **`aontu:lang/markdown`** are the two bundled
profiles. `text` is `lang: "text"` and an indent of two spaces, and
nothing else; `markdown` is that plus what markdown has of its own, the
HTML comment form and the template marker its files write,
`<!--- … -->`. A language the bundled pair does not cover writes its own
profile and passes it with `--profile`.

Every bundled model is **experimental** until the vocabulary can be
versioned by canon-hash.

### The `aontu:system` vocabulary

Ports, components and relations need no syntax: they are schemas, and
one set of them ships with the engine. Write this as `system.aon`:

<!-- test: scenario std-system -->
<!-- test: file system.aon -->
```aon
@"aontu:system"

services: {
  auth: $.aontu.System.Service & {
    ports: http: protocol: http
    dependedOnBy: rel() & [path($.services.billing)]
  }
  billing: $.aontu.System.Service & {
    dependsOn: rel($.aontu.System.Service) & inverse(dependedOnBy) & acyclic() & [
      path($.services.auth)
    ]
  }
}
```

<!-- test: run -->
```sh
$ aontu system.aon
{
  "aontu": {
    "System": {}
  },
  "services": {
    "auth": {
      "dependedOnBy": [
        "$.services.billing"
      ],
      "kind": "service",
...
```

| Schema | Says |
|--------|------|
| `$.aontu.System.Port` | one end of a connection: `direction` (default `in`) and an optional `protocol` |
| `$.aontu.System.Component` | a node with `ports`, each of which is a `Port` |
| `$.aontu.System.Service` | a Component whose `kind` is `service` |
| `$.aontu.System.Semver` | a version as an ordered tuple, `[major minor patch pre-release build]`, with the tail defaulted: `[1]` is `[1 0 0 "" ""]` |

**`Semver` is a list, not a string and not a map.** A version is
compared rather than read, and comparison runs component by component
from the left, an order a list has and the other two do not: `"1.10.0"`
sorts below `"1.9.0"` as text, and a map has no order of its own to
compare along.

**The tail is defaulted**, so a version may be written as short as it
is meant: `[1]` is `[1 0 0 "" ""]`, and `[1 2]` is `[1 2 0 "" ""]`. The
arity is five, so a sixth element is refused (`[aontu/constraint]`).
Write this as `version.aon`:

<!-- test: scenario aontu-system-semver -->
<!-- test: file version.aon -->
```aon
@"aontu:system"
v: $.aontu.System.Semver & [1]
pre: $.aontu.System.Semver & [1 2 3 "alpha.1"]
```

<!-- test: run -->
```sh
$ aontu version.aon
{
  "aontu": {
    "System": {}
  },
  "pre": [
    1,
    2,
    3,
    "alpha.1",
    ""
  ],
  "v": [
    1,
    0,
    0,
    "",
    ""
  ]
}
```

The two string parts differ in three ways:

- **Both are checked by grammar, not by pattern.**
  [semver.org 2.0.0](https://semver.org) spells each as dot-separated
  identifiers, which as a pattern is a quantified group holding a
  quantifier, the one shape `re()` refuses outright
  (`constraint_pattern`, for backtracking exponentially; see
  [The constraint algebra](#the-constraint-algebra)). The vocabulary
  carries an ABNF grammar for each instead and applies it with
  `parse()`, so `"beta_1"`, `"alpha..1"` and `"01"` are all refused
  (`[aontu/empty]`) where an alphabet pattern admitted the last two.
  The two grammars are members of the model in their own right,
  `semverPreRelease` and `semverBuild`, hidden so a schema's grammar
  does not generate into the document it checks, and lower-case because
  the case of a bundled key says whether it names a type. See
  [grammars](#grammars-abnf-and-parse).
- **The two grammars differ where the spec does.** A wholly numeric
  pre-release identifier may not carry a leading zero, because
  pre-releases are compared numerically; a build identifier may,
  because build metadata is never compared. So `[1 0 0 "01"]` is
  refused, `[1 0 0 "0alpha"]` stands, and so does
  `[1 0 0 "" "001"]`.
- **Build metadata comes last.** The spec says it MUST be ignored when
  determining precedence, and last is the one position where a
  comparison that walks the tuple from the left can stop before it
  without leaving a hole.

Leading zeroes need no rule in the numeric parts: they are integers, and
`01` is not a distinct integer literal, so the spec's "MUST NOT contain
leading zeroes" is impossible to write there rather than merely
forbidden.

`@"aontu:system"` is **bundled with the engine** (no filesystem, no
package resolution) so it resolves under every include capability
except `'none'`, which denies every include by definition. It is
**experimental** until the vocabulary can be versioned by canon-hash.

Two of its behaviours are the language rather than the vocabulary:

- **A preferred member is one enum member, with the default role.**
  `direction: *in | out | inout` is a true enum-with-default under the
  admission gate: unset generates `in`, `out` and `inout`
  override, and any other value is refused (`[aontu/empty]`). A
  vocabulary that wants an open field says so with a `| top` (or
  `| string`) branch.
- **`Service` is written out rather than as `$.aontu.System.Component & {kind:
  service}`.** A reference from one member of an included file to
  another does not survive the include, so each schema states itself;
  `$.aontu.System.Component & $.aontu.System.Service` still meets exactly as you would
  expect.

Everything here is ordinary unification, so an author who wants a
different vocabulary writes one the same way, and nothing in the
language knows these names.

### Declared relations

A relation is declared AT ITS FIELD: `rel(t)` says the field's strings
are tree addresses and flows `t` into every target, and the two
GRAPH ATOMS declare the properties that hold over the whole edge set:

```aon
a: dependsOn: rel() & inverse(usedBy) & acyclic() & [path($.b)]
b: usedBy: rel() & [path($.a)]
```

```json
{"a": {"dependsOn": ["$.b"]}, "b": {"usedBy": ["$.a"]}}
```

- **`acyclic()`**: the edges under this relation must have no cycle.
  The error names the nodes the cycle runs through, closing back on
  the first.
- **`inverse(<name>)`**: for each `a --dependsOn--> b`, `b` must carry
  `a` under `<name>`, as an edge of that relation. The error names the
  exact missing entry. Writing the inverse **for** you is generation,
  not validation, and is not done here.
- The `target` half of the old declaration is `rel(t)` itself: the
  type flows into each far end at the site, so a conflict or a hole is
  an ordinary located evaluation error.

The atoms are **lattice-inert, deliberately.** Both properties are
global and non-monotone: an acyclic graph becomes cyclic when one more
edge unifies in, and an inverse that is present becomes absent when the
far side is narrowed. The lattice guarantee is that more information
never falsifies what has already been observed, so a constraint that
could be true and then false is not one the lattice may hold. During
unification the atoms only REGISTER the declaration (the predicate is
the key they sit on) and ride the field's value; the verdict lands at
GENERATION (where no more information can arrive) as a located
`relation_cycle` or `relation_inverse_missing` at the offending edge,
exactly as an unmet sizing atom refuses. `aontu relations <file>`
reports the same findings without generating, and the library exposes
`relationCheck(src)`. The closure question (does `a` reach `b` at any
remove?) is a separate verb, [`aontu reaches`](/docs/reference-api#aontu-reaches).

There is no reserved `relations:` key: a document that writes one has
written ordinary data. The tree is user space at every level.

For the working recipes see
[Check relations](/how-to/check-relations) and
[Query reachability](/how-to/query-reachability); the live version,
with its checks, is [use-cases/12-relations](/use-cases/12-relations).

## Marks: `type` and `hide`

Marks are boolean flags carried on a value (set by `type()` / `hide()`,
or propagated by conjunction):

- A **type**-marked value is schema/metadata.
- A **hide**-marked value is intentionally excluded from output.

In both cases, **a map field whose value is type- or hide-marked is
omitted when the enclosing map is generated**, while still participating
in unification. A bare marked value at the top level still generates
(`type(1) & number`→`1`). `copy()` clears both marks, making the result
emittable again:

```aon
x: type({})
x: y: 1
a: copy($.x)
```

```json
{"a":{"y":1}}
```

**A mark belongs to the field its wrapper was written at**. A reference
to a `type()`/`hide()`-marked value copies the value with the marks
cleared, and that holds however the wrapper resolves: a reference that
lands on a still-unresolved `type()`/`hide()` call waits for it to
resolve at its *own* field rather than copying the call, so the marks
can never be re-stamped at the referring site. In particular `m:
hide(pack(...))` hides the field `m` exactly as `hide({literal map})`
does (the generated children stay usable downstream (`out: pack($.m,
{got:_})` emits their values)) and a `type()`-marked alias referenced
inside another `type()` body constrains the referring field without
suppressing its emission.

## Closed values: `close` / `open`

A **closed** map or list refuses any key/element not already present.
Narrowing an existing key is fine, and `open` lifts the seal:

```aon
a: close({ x:1 }) & { x:number }
b: open(close({ x:1 })) & { y:2 }
c: close(42)
```

```json
{"a":{"x":1},"b":{"x":1,"y":2},"c":42}
```

`close` on a scalar is a no-op (`c` above), and `close($.x)` closes a
referenced node. Adding a key or extending a list is refused:

```
close({x:1}) & {y:2}      → error: closed
close([1,2]) & [3,4,5]    → error: closed
```

## Source loading `@"…"`

`@"path"` loads and parses another source file, then unifies the result
in place, so external files merge like any other value.

Source files use the `.aon` extension (preferred) or `.aontu`. When the
path has no extension, those two are tried in turn, so `@"foo"` resolves
`foo.aon` then `foo.aontu`.

**The extension decides what the file is**, and it says which of three
things:

| extension | what it is |
|---|---|
| `.aon`, `.aontu` | **aontu source**: the language, with everything in it |
| `.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`, `.yaml`, `.yml`, `.ini` | **configuration data**, read by that format's own parser |
| `.txt`, and whatever `--text-ext` names | **text**: the file's bytes, as one string |
| anything else | refused, by name |

Every one of those formats maps onto JSON, which is why one word covers
them: a `.toml` file is a map of scalars, lists and maps, and so is the
`.aon` file that unifies with it. What a data format does not get is
the language: a `&` in a YAML file is a YAML anchor, not a spread key,
because the YAML parser reads it, not this one.

Write `vocab.jsonld`:

<!-- test: scenario include-extension -->
<!-- test: file vocab.jsonld -->
```json
{"name": "aontu", "tags": ["config", "types"]}
```

and load it from `main.aon`:

<!-- test: file main.aon -->
```aon
schema: @"./vocab.jsonld"
```

<!-- test: run -->
```sh
$ aontu main.aon
{
  "schema": {
    "name": "aontu",
    "tags": [
      "config",
      "types"
    ]
  }
}
```

### Text: `.txt` and `--text-ext`

A `.txt` file is read as **one string**. Nothing parses it, so nothing
in it can mean anything, which is what makes it the safe third
category. Write `notes.txt`:

<!-- test: file notes.txt -->
```
Deploy freezes over the holiday period.
```

and load it as a value in `main.aon`:

<!-- test: file main.aon -->
```aon
notes: @"./notes.txt"
```

<!-- test: run -->
```sh
$ aontu -c main.aon
{"notes":"Deploy freezes over the holiday period.\n"}
```

The result is an ordinary string, so the language's string operations
reach it and a schema can constrain it: `notes: string & length(1)`
holds, and `upper(@"./notes.txt")` uppercases the file.

**Other extensions need an allowance.** `--text-ext md,sql` reads those
as text too, for a project that keeps its prose in `.md` or its queries
in `.sql`. Every verb but `help`, `explain`, `init`, `lsp` and `mcp`
takes it, and the dots are optional
(`--text-ext .md`). Two limits: an extension the table already names
keeps its meaning, so `--text-ext toml` does not re-read TOML as a
string; and `.js` stays refused however the flag is spelled.

A config file in any of those formats reads the same way. Write
`server.toml`:

<!-- test: file server.toml -->
```toml
port = 8080
hosts = ["a", "b"]
```

and hold it to a schema in `main.aon`:

<!-- test: file main.aon -->
```aon
port: integer
hosts: [string]

@"./server.toml"
```

<!-- test: run -->
```sh
$ aontu main.aon
{
  "hosts": [
    "a",
    "b"
  ],
  "port": 8080
}
```

**A format's own semantics are the ones that apply.** INI has no types,
so `port=8080` read from a `.ini` is the string `"8080"`, and a schema
wanting a number has to say so. A malformed config file refuses the
whole document rather than becoming an empty value under the key that
included it.

Every other extension (and a name with no extension at all) is
refused by name rather than guessed at. Put rows in `rows.csv`:

<!-- test: file rows.csv -->
```
port,host
8080,local
```

and ask for it in `main.aon`:

<!-- test: file main.aon -->
```aon
rows: @"./rows.csv"
```

<!-- test: run -->
```sh
$ aontu main.aon
include not readable: ./rows.csv (extension: .csv)
$ echo $?
1
```

A guess would be worse than the refusal, and it was: read as text, a
vocabulary became a string that a schema then validated nothing
against; read as aontu, prose became a parse error at a line nobody
wrote. Both exited 0. Reading a file as text is a category the table
now *names* (that is what `.txt` is) and the difference is that it is
stated rather than a fallback for whatever the table failed to
recognise.

```
@"./foo.aon"                       → {"f":11}            (top level)
a:@"./foo.aon"                     → {"a":{"f":11}}      (nested)
car:@"./car.aon" car:{wheels:4}    → merges loaded + local
@"foo"                           → {"f":11}            (implicit .aon/.aontu)
```

To see the merge, write `foo.aon`:

<!-- test: scenario include -->
<!-- test: file foo.aon -->
```aon
f: 11
```

a second file, `car.aon`:

<!-- test: file car.aon -->
```aon
doors: 2
```

and an entry file, `main.aon`, loading both:

<!-- test: file main.aon -->
```aon
@"./foo.aon"
car: @"./car.aon"
car: wheels: 4
```

<!-- test: run -->
```sh
$ aontu main.aon
{
  "car": {
    "doors": 2,
    "wheels": 4
  },
  "f": 11
}
```

A **relative** path resolves against a configurable base directory: the
`aontu` CLI sets it to the entry file's directory, and the Go API exposes
it via `NewWithBase` (the TypeScript API via the `path` option). A
relative load *inside* a loaded file resolves against **that file's own
directory**, so a chain of files (a → b → c) each resolves relative to
itself. Absolute paths ignore the base. Resolution tries, in order, an
in-memory resolver,
the filesystem, then package resolution (see
[API reference](/docs/reference-api#aontuoptions)). A conflict between a loaded
value and a local one is a normal unification
error.

### Modules

An import whose path is **domain-shaped** is a module import rather than
a file path. A local file says so with a `./`, `../` or `/` prefix:

```
service: @"corp.example/schemas/service"
frozen:  @"corp.example/schemas/service#aon1-4vJemVYtWFR2mQeN…"
legacy:  @"alias:legacy"
local:   @"./fragment.aon"
```

**Every reference says what it is.** The first segment of a package
path contains a dot and the path carries no version: compatibility is
computed at publish, so the major left the name. `alias:<name>` names
an alias the project's package file declares, and resolves by lookup,
never by shape. A bare reference whose last segment carries an
extension the include table knows is refused with `module_local` and
the message `local files need a ./ prefix`, because `config.json`
routes here now and was a file before.

**Shape routes; validity refuses.** A path that routes here becomes a
directory on every platform the toolchain runs on, so it is checked
before anything is built from it: no element may be empty, begin or
end with `.`, or be a reserved device name (`nul`, `con`, `com1`…), and
the path is bounded in length and element count.

```
module path: corp.example/../schemas (an element begins or ends with ".")
```

**Uppercase is escaped on disk.** `corp.example/Widgets` and
`corp.example/widgets` are two identities and, on a case-insensitive
filesystem, one directory, so an uppercase letter is written
`!`+lowercase in every store. The written path stays the identity.

**Evaluation never touches the network.** A module resolves from local
stores only: `aontu_meta/vendor/` in the project that declares
`pkg.aon`, and in every project enclosing it, then the user cache under
`aontu/pkg`, which is consulted only when the expected canon-hash is
known, because that hash is its key. A module in neither store names
the step that fixes it:

```
module not fetched: corp.example/schemas/service (run: aontu sync)
```

**A package that moved refuses.** A package's own file may declare
`moved: <new path>`; an import of the old path is refused with
`module_moved`, naming the destination, and nothing follows it. A name
that came to mean something else without saying so would be the failure
the naming convention exists to prevent.

**The package file and the lockfile are ordinary aontu.** `pkg.aon`
declares the package's own path, entry and version, what it depends on,
and whether it may be published:

```aon
pkg: { path:"corp.example/schemas/service" version:"1.4.2" main:"service.aon" }
dep: "corp.example/schemas/common": v: "1.0.0"
publish: public
```

`aontu_meta/pkg-lock.aon` is machine-written in **canonical form**: one
line, sorted keys, diffable, and (its leaves being scalars) valid JSON.
Each entry carries three pins with distinct roles: `archive` certifies
*these are the bytes*, `manifest` certifies *this is what the publisher
signed*, and `canon` certifies *this is the meaning that was reviewed*:

<!-- fmt: keep a lock file, shown as the tool writes it -->
```aon
{"lock":{"corp.example/schemas/service":{"archive":"sha256:9127…","canon":"aon1-4vJe…","manifest":"sha256:f72c…","v":"1.4.2"}}}
```

Only the canon pin can be checked by evaluation alone, and it is the
one an import checks: by unifying the module **standalone** and
comparing its [canon-hash](#canonical-form):

```
module integrity: corp.example/schemas/service expected aon1-4vJe… got aon1-9kQz…
```

The pin survives comments, whitespace, formatting and refactoring; it
breaks on any semantic change in the module's transitive closure. An
inline `#aon1-…` fragment is the same check without a lockfile: the
degenerate mode for single-file and agent-sandbox use. The other two
pins belong to the tooling: `aontu sync` and `aontu pkg verify` check the
bytes before the meaning.

Under a **root** trust capability (`docs/trust.md`) the user cache is
not consulted at all: a confined evaluation sees the project's own
`aontu_meta/vendor/` and nothing else, which is what confinement means.

**A vendored package is a project inside a project.** It carries its
own `pkg.aon`, and its imports resolve from its own directory and then
from every project enclosing it, which is where `sync` put its
dependencies. The vendor tree is flat: a dependency of a dependency sits
beside its dependant, never inside it.

**The lockfile is maintained by tooling, not by hand.** `aontu sync`
walks the closure and resolves it by **minimum version selection**:
every package is taken at the highest of the minima anyone asked for,
and never higher, so the answer is reproducible and adding one
dependency cannot move another. It fetches what no store holds,
verifying the proof, the bytes and the meaning in that order, writes
the lockfile, materialises the vendor tree and verifies every pin. The
verbs, their flags and the repository they read from are in the
[API reference](/docs/reference-api#aontu-sync).

## Operator precedence

From tightest to loosest binding (higher binding power binds first):

| Operator            | Form        | Notes |
|---------------------|-------------|-------|
| `$` (variable/abs)  | prefix      | tightest |
| `.` (path)          | prefix/infix |       |
| `*` (preference)    | prefix      |       |
| `-` / `+` (unary)   | prefix      | `-1 & integer` ≡ `(-1) & integer` |
| `+` (add/concat)    | infix       |       |
| `&` (conjunction)   | infix       | binds tighter than `\|` |
| `\|` (disjunction)  | infix       | loosest |

So `c & b | a` ≡ `(c & b) | a` and `*1 | number` ≡ `(*1) | number`.
Parentheses override precedence and also serve as function-call syntax.

## Canonical form

`unify(src).canon` (TS) / `Unify(src).Canon()` (Go) renders a unified
value as **reparseable source text**. Unlike generation it preserves
constraints, defaults, and open disjunctions. Rules:

- Maps render as `{"k":v,…}` with **quoted keys**, no spaces:
  `{"a":{"b":1,"c":2}}`. Lists as `[v,…]`.
- Strings are quoted (`"hello"`); numbers, booleans and `null` render
  literally; `top` renders as `top`.
- **Numbers render so that canon reparses to the same kind.** An
  integer-kind value renders plainly (`1000`). A float-kind value
  always carries a fraction or an exponent, so a `.0` suffix is
  appended when the shortest rendering has neither:

  ```
  1.0    → 1.0        1e21     → 1e+21        (already exponential)
  0.0    → 0.0        0.000001 → 0.000001     (already fractional)
  1e20   → 100000000000000000000.0
  ```

  This applies to **canon only**. String concatenation is unaffected:
  `a+1.0` is still `"a1"`.
- **Exact values carry the `0d` marker**, with any sign in front of
  it, in plain form at every magnitude: never scientific. An integral
  bigdecimal keeps one decimal place, which is what distinguishes it
  from the biginteger of the same value:

  ```
  0d5    → 0d5          0d1000  → 0d1000       (biginteger)
  -0d5   → -0d5         0d1e3   → 0d1000.0     (bigdecimal)
  0d0.10 → 0d0.1        0d1e-1  → 0d0.1        (one value, one rendering)
  ```

  Here too the marker is canon decoration only: `q+0d5` is `"q5"`.
- Negative zero never appears: it normalises to `0` (integer), `0.0`
  (float), `0d0` (biginteger) or `0d0.0` (bigdecimal), in canon and in
  generated output alike.
- Kinds render lowercase: `number`, `integer`, `float`, `biginteger`,
  `bigdecimal`, `string`, `boolean`.
- Conjunction: `a&b` (for example `number&"A"`). Disjunction: `a|b`
  (for example `1|2`, `string|number`). Preference: `*x` (for example `*1|number`).
- Spreads keep the `&:` entry: `{&:{"x":2},"y":{…}}`.

## The formatted form

`aontu fmt` writes a document in one agreed form, in the tradition of
`gofmt`, so that layout is never argued about and a diff shows only
what changed. The form is a spelling of the document and not a change
to it: what the formatter writes evaluates to the same value, has the
same canon-hash, and is a fixed point of the formatter. The verb is in
the [API reference](/docs/reference-api#aontu-fmt); how to run it on a
file or gate a repository is a
[how-to](/how-to/format-a-document). This section is the form.

**Lines.** Two spaces per level of indentation, never a tab. Line
endings are `LF`, no line ends in whitespace, and the file ends in one
newline. A packing budget of 80 columns decides between two legal
spellings of a value, one line or several, and nothing else: the
formatter never breaks a line. A string 200 columns wide stays 200
columns wide, and an expression the author wrote on one line stays on
it however wide it is.

**Pairs.** A pair is `key: value`, no space before the colon and one
after, and the key, the colon and the value are never on different
lines. At statement level every pair has its own line, so `a: 1 b: 2`
on one line becomes two. Inside an inline container the colon is
tight, `{ a:1 b:2 }`, and the space between pairs is what separates
them. An optional key keeps its marker tight, `port?: integer`; a
spread is `&: value`; an alias declaration is `%Name = value`.

**Braces are for shape, not for nesting.** A pair whose value is a map
holding exactly one entry is written as a chain: `a: {b: 1}` is
`a: b: 1`, recursively, and the root map has no braces at all. A
one-key map in list position is a pair element, `[a:1 b:2]` for
`[{a:1}, {b:2}]`. A map whose only entry is a spread keeps its braces,
`a: { &: integer }`, because the braces are what say "a map shape": a
spread alone reads as a constraint on `a` rather than on its members.
A map that is an operand or an argument keeps its braces too,
`a: { b:1 } & T`, `s: close({ a:1 })`: those are expressions, and
inside them the rules apply again to each entry.

**Repeat the prefix.** A pair in statement position whose value is a
plain map is laid out in this order: on one line, `key: { a:v b:v }`,
when that fits the budget and the map holds no comment and no value
that spans lines; else as one statement per entry, each carrying the
key again, when every entry is a one-liner that way:

```aon
server: host: "0.0.0.0"
server: port: 8080
server: tls: { enabled:true cert:"/etc/tls/edge/cert.pem" }
```

and otherwise as a braced block, `key: {` on the pair's line, each
entry a statement one level in, and `}` alone on its line. The repeat
is legal because a key written twice is a meet, and the meet of two
maps with disjoint keys is their union: the three statements above and
`server: { host: "0.0.0.0", port: 8080, tls: { ... } }` are one document,
with one canon-hash. It applies recursively, so a nested map that fits
stays on its line and one that does not is descended into under the
longer prefix, `a: b: c: 1` / `a: b: d: 2`; there is no cap on how many
statements a map becomes.

**The descent stops at a record.** A record is a map of several
entries, every one of them a value rather than another map: a field, an
error, a row. The prefix reaches through a map that holds maps, because
those keys are a path and a line carrying all of them says where it is;
where the descent reaches a record instead, that map is written as a
braced block under the prefix rather than dissolved into it, because
its keys are what the thing IS and repeating the prefix in front of
each of them says nothing:

```aon
entity: planet: table: "planets"
entity: planet: field: id: {
  name: "id"
  json: "id"
  kind: "string"
  required: true
  pk: true
  write: true
  fk: false
}
```

A one-entry map is a chain at every width and is not a record; nor is
a map holding a spread. The block replaces a descent and never rescues
one: where the deeper repeat could not have been written anyway (a list
too wide under the longer prefix, a value spanning lines) the statement
is a braced block by the rule above, exactly as it was before this. And
the statement's own map is not reached by a descent, so a flat
`server: host:` / `server: port:` is written as the repeat it has
always been, and so is a record a chain leads to and nothing else does.

Merging goes the other way too: adjacent
statements naming one key are one map to the formatter, which then
lays that map out by the same procedure, so `s: a: 1` / `s: b: 2` is
written `s: { a:1 b:2 }`. Only adjacent statements merge; a `server:`
line, something else, then another `server:` line stays as it is,
because the formatter never reorders. A statement's trailing comment
travels onto the entry it stood beside; comments and blank lines
between merged statements stay between the entries.

The rule touches nothing but a plain map in statement position. A map
wrapped in a call is an expression, and splitting it changes the
document: `s: close({a: 1})` / `s: close({b: 2})` does not evaluate
where `s: close({a: 1, b: 2})` does. The same holds for an operand of
`&` or `|`, a list element, a map with a comment on its opening line or
as its last entry, and a map holding two spreads, which the engine
keeps as a conjunction. Every repeat and every merge is checked with
the engine before it is written, the two spellings evaluated in
isolation and compared, and a rewrite the engine evaluates differently
is not made: the statement keeps its braces.

**Containers.** A map whose one-line spelling fits is written on one
line, padded inside the braces and with the colons tight; a list is
not padded: `limits: { rps:100 burst:200 }`, `ports: [80 443 8080]`,
`routes: [get:"/health" post:"/orders"]`. A container goes to several
lines when it does not fit, when it holds a comment, or when an
element is itself several lines. A list then puts each element on its
own line one level in, with the closing bracket alone on a line; a map
in statement position repeats or blocks as above; a map in expression
position is a braced block, `{` at the end of the line that opens it
and `}` alone, which is the ordinary spelling of a constrained map:

```aon
CatalogEntry: $.aontu.System.Service & {
  owner: %Owner
  tier: 1|2|3
  dependsOn?: rel($.aontu.System.Service) & %CatalogAddr & acyclic() & inverse(dependedOnBy)
}
```

That third line is 83 columns where it sits, and stays so.

Empty containers are `{}` and `[]`, always inline.

**Separators.** No commas between pairs or between elements: a newline
or a space separates, and commas on input are dropped, trailing ones
included. Inside a call's argument list the author's separators are
kept, a comma or a space, with one space after a comma, because the
parser reads a run of arguments such as `must((v) => 0 <= v, "…")`
exactly as it reads `match(.t, "string", "x")`.

**Comments.** Every `#` comment is kept, its text untouched. A comment
on its own line attaches to the statement that follows it and is
indented to that statement's level; a blank line between the two
stays. A trailing comment stays on its line, one space after the last
token, and trailing comments are not aligned into a column. A comment
inside a container puts the container on several lines, which is the
only way the comment keeps its place; a comment on the line that opens
a block stays there, `server: { # what the edge sees`.

**Blank lines.** A blank line is a paragraph break the author chose,
and the formatter keeps it: any run of blank lines becomes one. None at
the start or end of a block, none at the start of the file, and one at
the end, which is the final newline.

**Keys and strings.** A key is bare when it can be: a quoted key whose
text is a legal bare key, `[A-Za-z_][A-Za-z0-9_]*`, is written bare, so
`"host": 1` becomes `host: 1`. Quoting that means something is never
touched: `"a?": 1` is a key named `a?`, where `a?: 1` is an optional
`a`. A single-quoted string becomes double-quoted, `'plain'` to
`"plain"`, unless it holds a double quote; a backtick string is
verbatim, newlines and indentation included; a string's content is
never changed; and a bare string stays bare, a quoted one quoted.

**Numbers.** A number's source text is copied exactly. `1`, `1.0`,
`0d1` and `0d1.0` are four kinds, and `1_000`, `0x1f` and `1e3` are
spellings the author chose.

**Operators and calls.** Binary operators are spaced, `a & b`, `a | b`,
`a + b`; a preference is tight, `*8080 | 9090`; a call is
`name(arg, arg)` with no space before the parenthesis and none inside
it, and an empty argument list is `name()`. References and paths are
copied as written. Parentheses are the author's: the formatter neither
adds nor removes a grouping parenthesis. A line break the author put
inside an expression is kept, at its operator, which then leads its
continuation line one level in:

```aon
out: `a` + .b
  + match(.t, "string", `TEXT`)
```

A call that does not fit on its line hugs its last argument to the
parentheses when that argument is a container, an unbroken expression
that ends in one, or a call whose own last argument hugs, which is the
schema idiom `type(close({` … `}))`; otherwise the arguments go one per
line, one level in, with the closing parenthesis alone. Arguments that
hold no container stay on one line however wide it is: a scalar is no
narrower on a line of its own.

**The root, and what never changes.** The root map has no braces.
Includes and alias declarations are statements like any other, kept
where the author put them and in that order. The formatter never
reorders a key, an element, an include or a declaration; never renames
a key; never introduces an alias; never resolves an include or reads a
file it was not given; never changes a number, a string's content or a
parenthesis; and never breaks a line.

## The published grammar

Canon is the shape a grammar can be written for (every key quoted,
one spelling per construct) and
[`grammar/aontu.abnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.abnf) is that grammar, in
RFC 5234 notation with RFC 7405's case-sensitive `%s"…"` literals.
The same rules are published for two machine consumers as
[`aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf) and
[`aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark); this is the form to read.

It is the **emission surface**: what a document should be allowed to
write, a superset of JSON plus the operators, constraints and marks
canon emits. It is **conservative by construction** (it may accept
less than the parser does, never more) and it makes two deliberate
exclusions. `@"…"` includes are absent, because a generated document
should describe values rather than reach for files. So are unquoted
keys and the other spellings the parser tolerates, because canon does
not emit them.

The grammar is executed, not merely published: `ts/test/grammar.test.ts`
reads the file, interprets it, and requires it to accept **every
canonical-form output in the shared spec suite** (several hundred of
them) and to refuse the excluded forms. A rule the engine has
outgrown fails the suite.

### How a value composes

Whitespace is permitted between every element and is not drawn; the
`ws` rule in the grammar text carries it. Each track is one rule, and a
box in one is a link to its own track.

<figure class="diagram"><div class="diagram-frame">
<svg xmlns="http://www.w3.org/2000/svg" class="railroad" width="938" height="2518" viewBox="0 0 938 2518"><style>svg.railroad{background:var(--rr-bg,#fff);font-family:monospace;font-size:13px}.rr-line{stroke:var(--rr-rule,#334);stroke-width:2;fill:none}.rr-cap{fill:var(--rr-rule,#334)}.rr-term{fill:var(--rr-term,#e8f0ff);stroke:var(--rr-rule,#334);stroke-width:2}.rr-nonterm{fill:var(--rr-nonterm,#fff7e8);stroke:var(--rr-rule,#334);stroke-width:2}.rr-label{fill:var(--rr-ink,#111);text-anchor:middle;dominant-baseline:middle}.rr-comment{fill:var(--rr-muted,#666);font-style:italic;text-anchor:middle;dominant-baseline:middle}.rr-title{fill:var(--rr-title,#113);font-weight:bold;font-size:15px}.rr-legend{fill:var(--rr-legend,#333);font-size:12px}.rr-legend-tok{fill:var(--rr-title,#113);font-weight:bold}a:hover .rr-nonterm{fill:var(--rr-nonterm-hover,#ffe6b3);cursor:pointer}</style><g><g id="root"><text class="rr-title" x="16" y="31">root</text><circle class="rr-cap" cx="46" cy="42" r="3"/><path class="rr-line" d="M46 42V56"/><a href="#value"><rect class="rr-nonterm" x="16" y="56" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="46" y="69">value</text></a><path class="rr-line" d="M46 82V96"/><circle class="rr-cap" cx="46" cy="96" r="3"/></g><g id="value"><text class="rr-title" x="16" y="145">value</text><circle class="rr-cap" cx="58" cy="156" r="3"/><path class="rr-line" d="M58 156V170"/><a href="#disjunct"><rect class="rr-nonterm" x="16" y="170" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="58" y="183">disjunct</text></a><path class="rr-line" d="M58 196V210"/><circle class="rr-cap" cx="58" cy="210" r="3"/></g><g id="disjunct"><text class="rr-title" x="16" y="259">disjunct</text><circle class="rr-cap" cx="98" cy="270" r="3"/><path class="rr-line" d="M98 270V284"/><a href="#conjunct"><rect class="rr-nonterm" x="56" y="284" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="98" y="297">conjunct</text></a><path class="rr-line" d="M98 310V328"/><path class="rr-line" d="M98 328V346"/><path class="rr-line" d="M58 346H138"/><path class="rr-line" d="M58 488H138"/><path class="rr-line" d="M98 488V506"/><path class="rr-line" d="M58 346V364"/><path class="rr-line" d="M58 364V382"/><rect class="rr-term" x="43" y="382" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="58" y="395">|</text><path class="rr-line" d="M58 408V426"/><a href="#conjunct"><rect class="rr-nonterm" x="16" y="426" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="58" y="439">conjunct</text></a><path class="rr-line" d="M58 452V470"/><path class="rr-line" d="M58 461H110"/><path class="rr-line" d="M58 373H110"/><path class="rr-line" d="M110 373V461"/><path class="rr-line" d="M58 470V488"/><path class="rr-line" d="M138 346V364"/><path class="rr-line" d="M138 364V376"/><path class="rr-line" d="M138 376V488"/><path class="rr-line" d="M98 506V520"/><circle class="rr-cap" cx="98" cy="520" r="3"/></g><g id="conjunct"><text class="rr-title" x="16" y="569">conjunct</text><circle class="rr-cap" cx="98" cy="580" r="3"/><path class="rr-line" d="M98 580V594"/><a href="#prefixed"><rect class="rr-nonterm" x="56" y="594" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="98" y="607">prefixed</text></a><path class="rr-line" d="M98 620V638"/><path class="rr-line" d="M98 638V656"/><path class="rr-line" d="M58 656H138"/><path class="rr-line" d="M58 798H138"/><path class="rr-line" d="M98 798V816"/><path class="rr-line" d="M58 656V674"/><path class="rr-line" d="M58 674V692"/><rect class="rr-term" x="43" y="692" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="58" y="705">&amp;</text><path class="rr-line" d="M58 718V736"/><a href="#prefixed"><rect class="rr-nonterm" x="16" y="736" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="58" y="749">prefixed</text></a><path class="rr-line" d="M58 762V780"/><path class="rr-line" d="M58 771H110"/><path class="rr-line" d="M58 683H110"/><path class="rr-line" d="M110 683V771"/><path class="rr-line" d="M58 780V798"/><path class="rr-line" d="M138 656V674"/><path class="rr-line" d="M138 674V686"/><path class="rr-line" d="M138 686V798"/><path class="rr-line" d="M98 816V830"/><circle class="rr-cap" cx="98" cy="830" r="3"/></g><g id="prefixed"><text class="rr-title" x="16" y="879">prefixed</text><circle class="rr-cap" cx="103" cy="890" r="3"/><path class="rr-line" d="M103 890V904"/><path class="rr-line" d="M103 904V922"/><path class="rr-line" d="M58 922H148"/><path class="rr-line" d="M58 1028H148"/><path class="rr-line" d="M103 1028V1046"/><path class="rr-line" d="M58 922V940"/><rect class="rr-term" x="43" y="940" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="58" y="953">*</text><path class="rr-line" d="M58 966V984"/><a href="#prefixed"><rect class="rr-nonterm" x="16" y="984" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="58" y="997">prefixed</text></a><path class="rr-line" d="M58 1010V1028"/><path class="rr-line" d="M148 922V940"/><a href="#sum"><rect class="rr-nonterm" x="126" y="940" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="148" y="953">sum</text></a><path class="rr-line" d="M148 966V1028"/><path class="rr-line" d="M103 1046V1060"/><circle class="rr-cap" cx="103" cy="1060" r="3"/></g><g id="sum"><text class="rr-title" x="16" y="1109">sum</text><circle class="rr-cap" cx="74" cy="1120" r="3"/><path class="rr-line" d="M74 1120V1134"/><a href="#atom"><rect class="rr-nonterm" x="48" y="1134" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="74" y="1147">atom</text></a><path class="rr-line" d="M74 1160V1178"/><path class="rr-line" d="M74 1178V1196"/><path class="rr-line" d="M42 1196H106"/><path class="rr-line" d="M42 1338H106"/><path class="rr-line" d="M74 1338V1356"/><path class="rr-line" d="M42 1196V1214"/><path class="rr-line" d="M42 1214V1232"/><rect class="rr-term" x="27" y="1232" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="42" y="1245">+</text><path class="rr-line" d="M42 1258V1276"/><a href="#atom"><rect class="rr-nonterm" x="16" y="1276" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="42" y="1289">atom</text></a><path class="rr-line" d="M42 1302V1320"/><path class="rr-line" d="M42 1311H78"/><path class="rr-line" d="M42 1223H78"/><path class="rr-line" d="M78 1223V1311"/><path class="rr-line" d="M42 1320V1338"/><path class="rr-line" d="M106 1196V1214"/><path class="rr-line" d="M106 1214V1226"/><path class="rr-line" d="M106 1226V1338"/><path class="rr-line" d="M74 1356V1370"/><circle class="rr-cap" cx="74" cy="1370" r="3"/></g><g id="atom"><text class="rr-title" x="16" y="1419">atom</text><circle class="rr-cap" cx="319" cy="1430" r="3"/><path class="rr-line" d="M319 1430V1444"/><path class="rr-line" d="M319 1444V1462"/><path class="rr-line" d="M38 1462H600"/><path class="rr-line" d="M38 1612H600"/><path class="rr-line" d="M319 1612V1630"/><path class="rr-line" d="M38 1462V1480"/><a href="#map"><rect class="rr-nonterm" x="16" y="1480" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="38" y="1493">map</text></a><path class="rr-line" d="M38 1506V1612"/><path class="rr-line" d="M112 1462V1480"/><a href="#list"><rect class="rr-nonterm" x="86" y="1480" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="112" y="1493">list</text></a><path class="rr-line" d="M112 1506V1612"/><path class="rr-line" d="M190 1462V1480"/><a href="#func"><rect class="rr-nonterm" x="164" y="1480" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="190" y="1493">func</text></a><path class="rr-line" d="M190 1506V1612"/><path class="rr-line" d="M264 1462V1480"/><a href="#ref"><rect class="rr-nonterm" x="242" y="1480" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="264" y="1493">ref</text></a><path class="rr-line" d="M264 1506V1612"/><path class="rr-line" d="M338 1462V1480"/><rect class="rr-nonterm" x="312" y="1480" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="338" y="1493">kind</text><path class="rr-line" d="M338 1506V1612"/><path class="rr-line" d="M420 1462V1480"/><a href="#place"><rect class="rr-nonterm" x="390" y="1480" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="420" y="1493">place</text></a><path class="rr-line" d="M420 1506V1612"/><path class="rr-line" d="M510 1462V1480"/><rect class="rr-nonterm" x="476" y="1480" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="510" y="1493">scalar</text><path class="rr-line" d="M510 1506V1612"/><path class="rr-line" d="M600 1462V1480"/><rect class="rr-term" x="585" y="1480" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="600" y="1493">(</text><path class="rr-line" d="M600 1506V1524"/><a href="#value"><rect class="rr-nonterm" x="570" y="1524" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="600" y="1537">value</text></a><path class="rr-line" d="M600 1550V1568"/><rect class="rr-term" x="585" y="1568" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="600" y="1581">)</text><path class="rr-line" d="M600 1594V1612"/><path class="rr-line" d="M319 1630V1644"/><circle class="rr-cap" cx="319" cy="1644" r="3"/></g><g id="map"><text class="rr-title" x="16" y="1693">map</text><circle class="rr-cap" cx="110" cy="1704" r="3"/><path class="rr-line" d="M110 1704V1718"/><rect class="rr-term" x="95" y="1718" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="110" y="1731">{</text><path class="rr-line" d="M110 1744V1762"/><path class="rr-line" d="M110 1762V1780"/><path class="rr-line" d="M80 1780H140"/><path class="rr-line" d="M80 2038H140"/><path class="rr-line" d="M110 2038V2056"/><path class="rr-line" d="M80 1780V1798"/><a href="#entry"><rect class="rr-nonterm" x="50" y="1798" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="80" y="1811">entry</text></a><path class="rr-line" d="M80 1824V1842"/><path class="rr-line" d="M80 1842V1860"/><path class="rr-line" d="M46 1860H114"/><path class="rr-line" d="M46 2002H114"/><path class="rr-line" d="M80 2002V2020"/><path class="rr-line" d="M46 1860V1878"/><path class="rr-line" d="M46 1878V1896"/><rect class="rr-term" x="31" y="1896" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="46" y="1909">,</text><path class="rr-line" d="M46 1922V1940"/><a href="#entry"><rect class="rr-nonterm" x="16" y="1940" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="46" y="1953">entry</text></a><path class="rr-line" d="M46 1966V1984"/><path class="rr-line" d="M46 1975H86"/><path class="rr-line" d="M46 1887H86"/><path class="rr-line" d="M86 1887V1975"/><path class="rr-line" d="M46 1984V2002"/><path class="rr-line" d="M114 1860V1878"/><path class="rr-line" d="M114 1878V1890"/><path class="rr-line" d="M114 1890V2002"/><path class="rr-line" d="M80 2020V2038"/><path class="rr-line" d="M140 1780V1798"/><path class="rr-line" d="M140 1798V1810"/><path class="rr-line" d="M140 1810V2038"/><path class="rr-line" d="M110 2056V2074"/><rect class="rr-term" x="95" y="2074" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="110" y="2087">}</text><path class="rr-line" d="M110 2100V2114"/><circle class="rr-cap" cx="110" cy="2114" r="3"/></g><g id="entry"><text class="rr-title" x="16" y="2163">entry</text><circle class="rr-cap" cx="93" cy="2174" r="3"/><path class="rr-line" d="M93 2174V2188"/><path class="rr-line" d="M93 2188V2206"/><path class="rr-line" d="M50 2206H136"/><path class="rr-line" d="M50 2268H136"/><path class="rr-line" d="M93 2268V2286"/><path class="rr-line" d="M50 2206V2224"/><a href="#spread"><rect class="rr-nonterm" x="16" y="2224" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="50" y="2237">spread</text></a><path class="rr-line" d="M50 2250V2268"/><path class="rr-line" d="M136 2206V2224"/><a href="#pair"><rect class="rr-nonterm" x="110" y="2224" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="136" y="2237">pair</text></a><path class="rr-line" d="M136 2250V2268"/><path class="rr-line" d="M93 2286V2300"/><circle class="rr-cap" cx="93" cy="2300" r="3"/></g><g id="spread"><text class="rr-title" x="16" y="2349">spread</text><circle class="rr-cap" cx="46" cy="2360" r="3"/><path class="rr-line" d="M46 2360V2374"/><rect class="rr-term" x="31" y="2374" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="46" y="2387">&amp;</text><path class="rr-line" d="M46 2400V2418"/><rect class="rr-term" x="31" y="2418" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="46" y="2431">:</text><path class="rr-line" d="M46 2444V2462"/><a href="#value"><rect class="rr-nonterm" x="16" y="2462" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="46" y="2475">value</text></a><path class="rr-line" d="M46 2488V2502"/><circle class="rr-cap" cx="46" cy="2502" r="3"/></g><g id="pair"><text class="rr-title" x="678" y="31">pair</text><circle class="rr-cap" cx="712" cy="42" r="3"/><path class="rr-line" d="M712 42V56"/><rect class="rr-nonterm" x="678" y="56" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="712" y="69">string</text><path class="rr-line" d="M712 82V100"/><path class="rr-line" d="M712 100V118"/><path class="rr-line" d="M695.5 118H728.5"/><path class="rr-line" d="M695.5 180H728.5"/><path class="rr-line" d="M712 180V198"/><path class="rr-line" d="M695.5 118V136"/><rect class="rr-term" x="680.5" y="136" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="695.5" y="149">?</text><path class="rr-line" d="M695.5 162V180"/><path class="rr-line" d="M728.5 118V136"/><path class="rr-line" d="M728.5 136V148"/><path class="rr-line" d="M728.5 148V180"/><path class="rr-line" d="M712 198V216"/><rect class="rr-term" x="697" y="216" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="712" y="229">:</text><path class="rr-line" d="M712 242V260"/><a href="#value"><rect class="rr-nonterm" x="682" y="260" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="712" y="273">value</text></a><path class="rr-line" d="M712 286V300"/><circle class="rr-cap" cx="712" cy="300" r="3"/></g><g id="list"><text class="rr-title" x="678" y="349">list</text><circle class="rr-cap" cx="786" cy="360" r="3"/><path class="rr-line" d="M786 360V374"/><rect class="rr-term" x="771" y="374" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="786" y="387">[</text><path class="rr-line" d="M786 400V418"/><path class="rr-line" d="M786 418V436"/><path class="rr-line" d="M754 436H818"/><path class="rr-line" d="M754 694H818"/><path class="rr-line" d="M786 694V712"/><path class="rr-line" d="M754 436V454"/><a href="#element"><rect class="rr-nonterm" x="716" y="454" width="76" height="26" rx="4" ry="4"/><text class="rr-label" x="754" y="467">element</text></a><path class="rr-line" d="M754 480V498"/><path class="rr-line" d="M754 498V516"/><path class="rr-line" d="M716 516H792"/><path class="rr-line" d="M716 658H792"/><path class="rr-line" d="M754 658V676"/><path class="rr-line" d="M716 516V534"/><path class="rr-line" d="M716 534V552"/><rect class="rr-term" x="701" y="552" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="716" y="565">,</text><path class="rr-line" d="M716 578V596"/><a href="#element"><rect class="rr-nonterm" x="678" y="596" width="76" height="26" rx="4" ry="4"/><text class="rr-label" x="716" y="609">element</text></a><path class="rr-line" d="M716 622V640"/><path class="rr-line" d="M716 631H764"/><path class="rr-line" d="M716 543H764"/><path class="rr-line" d="M764 543V631"/><path class="rr-line" d="M716 640V658"/><path class="rr-line" d="M792 516V534"/><path class="rr-line" d="M792 534V546"/><path class="rr-line" d="M792 546V658"/><path class="rr-line" d="M754 676V694"/><path class="rr-line" d="M818 436V454"/><path class="rr-line" d="M818 454V466"/><path class="rr-line" d="M818 466V694"/><path class="rr-line" d="M786 712V730"/><rect class="rr-term" x="771" y="730" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="786" y="743">]</text><path class="rr-line" d="M786 756V770"/><circle class="rr-cap" cx="786" cy="770" r="3"/></g><g id="element"><text class="rr-title" x="678" y="819">element</text><circle class="rr-cap" cx="757" cy="830" r="3"/><path class="rr-line" d="M757 830V844"/><path class="rr-line" d="M757 844V862"/><path class="rr-line" d="M712 862H802"/><path class="rr-line" d="M712 924H802"/><path class="rr-line" d="M757 924V942"/><path class="rr-line" d="M712 862V880"/><a href="#spread"><rect class="rr-nonterm" x="678" y="880" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="712" y="893">spread</text></a><path class="rr-line" d="M712 906V924"/><path class="rr-line" d="M802 862V880"/><a href="#value"><rect class="rr-nonterm" x="772" y="880" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="802" y="893">value</text></a><path class="rr-line" d="M802 906V924"/><path class="rr-line" d="M757 942V956"/><circle class="rr-cap" cx="757" cy="956" r="3"/></g><g id="func"><text class="rr-title" x="678" y="1005">func</text><circle class="rr-cap" cx="772" cy="1016" r="3"/><path class="rr-line" d="M772 1016V1030"/><a href="#name"><rect class="rr-nonterm" x="746" y="1030" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="772" y="1043">name</text></a><path class="rr-line" d="M772 1056V1074"/><rect class="rr-term" x="757" y="1074" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="772" y="1087">(</text><path class="rr-line" d="M772 1100V1118"/><path class="rr-line" d="M772 1118V1136"/><path class="rr-line" d="M742 1136H802"/><path class="rr-line" d="M742 1394H802"/><path class="rr-line" d="M772 1394V1412"/><path class="rr-line" d="M742 1136V1154"/><a href="#value"><rect class="rr-nonterm" x="712" y="1154" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="742" y="1167">value</text></a><path class="rr-line" d="M742 1180V1198"/><path class="rr-line" d="M742 1198V1216"/><path class="rr-line" d="M708 1216H776"/><path class="rr-line" d="M708 1358H776"/><path class="rr-line" d="M742 1358V1376"/><path class="rr-line" d="M708 1216V1234"/><path class="rr-line" d="M708 1234V1252"/><rect class="rr-term" x="693" y="1252" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="708" y="1265">,</text><path class="rr-line" d="M708 1278V1296"/><a href="#value"><rect class="rr-nonterm" x="678" y="1296" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="708" y="1309">value</text></a><path class="rr-line" d="M708 1322V1340"/><path class="rr-line" d="M708 1331H748"/><path class="rr-line" d="M708 1243H748"/><path class="rr-line" d="M748 1243V1331"/><path class="rr-line" d="M708 1340V1358"/><path class="rr-line" d="M776 1216V1234"/><path class="rr-line" d="M776 1234V1246"/><path class="rr-line" d="M776 1246V1358"/><path class="rr-line" d="M742 1376V1394"/><path class="rr-line" d="M802 1136V1154"/><path class="rr-line" d="M802 1154V1166"/><path class="rr-line" d="M802 1166V1394"/><path class="rr-line" d="M772 1412V1430"/><rect class="rr-term" x="757" y="1430" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="772" y="1443">)</text><path class="rr-line" d="M772 1456V1470"/><circle class="rr-cap" cx="772" cy="1470" r="3"/></g><g id="name"><text class="rr-title" x="678" y="1519">name</text><circle class="rr-cap" cx="800" cy="1530" r="3"/><path class="rr-line" d="M800 1530V1544"/><path class="rr-line" d="M800 1544V1570"/><text class="rr-comment" x="800" y="1557">one of the builtin functions</text><path class="rr-line" d="M800 1570V1584"/><circle class="rr-cap" cx="800" cy="1584" r="3"/></g><g id="ref"><text class="rr-title" x="678" y="1633">ref</text><circle class="rr-cap" cx="777" cy="1644" r="3"/><path class="rr-line" d="M777 1644V1658"/><path class="rr-line" d="M777 1658V1676"/><path class="rr-line" d="M716 1676H838"/><path class="rr-line" d="M716 1862H838"/><path class="rr-line" d="M777 1862V1880"/><path class="rr-line" d="M716 1676V1694"/><rect class="rr-term" x="701" y="1694" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="716" y="1707">$</text><path class="rr-line" d="M716 1720V1738"/><path class="rr-line" d="M716 1738V1756"/><rect class="rr-term" x="701" y="1756" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="716" y="1769">.</text><path class="rr-line" d="M716 1782V1800"/><a href="#segment"><rect class="rr-nonterm" x="678" y="1800" width="76" height="26" rx="4" ry="4"/><text class="rr-label" x="716" y="1813">segment</text></a><path class="rr-line" d="M716 1826V1844"/><path class="rr-line" d="M716 1835H764"/><path class="rr-line" d="M716 1747H764"/><path class="rr-line" d="M764 1747V1835"/><path class="rr-line" d="M716 1844V1862"/><path class="rr-line" d="M838 1676V1694"/><path class="rr-line" d="M838 1694V1712"/><rect class="rr-term" x="823" y="1712" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="838" y="1725">.</text><path class="rr-line" d="M838 1738V1756"/><a href="#segment"><rect class="rr-nonterm" x="800" y="1756" width="76" height="26" rx="4" ry="4"/><text class="rr-label" x="838" y="1769">segment</text></a><path class="rr-line" d="M838 1782V1800"/><path class="rr-line" d="M838 1791H886"/><path class="rr-line" d="M838 1703H886"/><path class="rr-line" d="M886 1703V1791"/><path class="rr-line" d="M838 1800V1862"/><path class="rr-line" d="M777 1880V1894"/><circle class="rr-cap" cx="777" cy="1894" r="3"/></g><g id="segment"><text class="rr-title" x="678" y="1943">segment</text><circle class="rr-cap" cx="786.5" cy="1954" r="3"/><path class="rr-line" d="M786.5 1954V1968"/><path class="rr-line" d="M786.5 1968V1986"/><path class="rr-line" d="M786.5 1986V2004"/><path class="rr-line" d="M708 2004H865"/><path class="rr-line" d="M708 2066H865"/><path class="rr-line" d="M786.5 2066V2084"/><path class="rr-line" d="M708 2004V2022"/><rect class="rr-nonterm" x="678" y="2022" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="708" y="2035">ALPHA</text><path class="rr-line" d="M708 2048V2066"/><path class="rr-line" d="M794 2004V2022"/><rect class="rr-nonterm" x="764" y="2022" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="794" y="2035">DIGIT</text><path class="rr-line" d="M794 2048V2066"/><path class="rr-line" d="M865 2004V2022"/><rect class="rr-term" x="850" y="2022" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="865" y="2035">_</text><path class="rr-line" d="M865 2048V2066"/><path class="rr-line" d="M786.5 2084V2102"/><path class="rr-line" d="M786.5 2093H890"/><path class="rr-line" d="M786.5 1977H890"/><path class="rr-line" d="M890 1977V2093"/><path class="rr-line" d="M786.5 2102V2116"/><circle class="rr-cap" cx="786.5" cy="2116" r="3"/></g><g id="place"><text class="rr-title" x="678" y="2165">place</text><circle class="rr-cap" cx="693" cy="2176" r="3"/><path class="rr-line" d="M693 2176V2190"/><rect class="rr-term" x="678" y="2190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="693" y="2203">_</text><path class="rr-line" d="M693 2216V2230"/><circle class="rr-cap" cx="693" cy="2230" r="3"/></g></g></svg>
</div><figcaption>Railroad diagram of the aontu grammar's structural rules: a value is a disjunction of conjunctions of prefixed sums, and an atom is a map, list, function call, reference, kind, placeholder, scalar or parenthesised value.</figcaption></figure>

### How one is spelled

The scalar forms, the character rules behind a string, the four numeric
spellings, and whitespace itself.

<figure class="diagram"><div class="diagram-frame">
<svg xmlns="http://www.w3.org/2000/svg" class="railroad" width="1210" height="2194" viewBox="0 0 1210 2194"><style>svg.railroad{background:var(--rr-bg,#fff);font-family:monospace;font-size:13px}.rr-line{stroke:var(--rr-rule,#334);stroke-width:2;fill:none}.rr-cap{fill:var(--rr-rule,#334)}.rr-term{fill:var(--rr-term,#e8f0ff);stroke:var(--rr-rule,#334);stroke-width:2}.rr-nonterm{fill:var(--rr-nonterm,#fff7e8);stroke:var(--rr-rule,#334);stroke-width:2}.rr-label{fill:var(--rr-ink,#111);text-anchor:middle;dominant-baseline:middle}.rr-comment{fill:var(--rr-muted,#666);font-style:italic;text-anchor:middle;dominant-baseline:middle}.rr-title{fill:var(--rr-title,#113);font-weight:bold;font-size:15px}.rr-legend{fill:var(--rr-legend,#333);font-size:12px}.rr-legend-tok{fill:var(--rr-title,#113);font-weight:bold}a:hover .rr-nonterm{fill:var(--rr-nonterm-hover,#ffe6b3);cursor:pointer}</style><g><g id="kind"><text class="rr-title" x="16" y="31">kind</text><circle class="rr-cap" cx="452" cy="42" r="3"/><path class="rr-line" d="M452 42V56"/><path class="rr-line" d="M452 56V74"/><path class="rr-line" d="M66 74H838"/><path class="rr-line" d="M66 136H838"/><path class="rr-line" d="M452 136V154"/><path class="rr-line" d="M66 74V92"/><rect class="rr-term" x="16" y="92" width="100" height="26" rx="13" ry="13"/><text class="rr-label" x="66" y="105">biginteger</text><path class="rr-line" d="M66 118V136"/><path class="rr-line" d="M192 74V92"/><rect class="rr-term" x="142" y="92" width="100" height="26" rx="13" ry="13"/><text class="rr-label" x="192" y="105">bigdecimal</text><path class="rr-line" d="M192 118V136"/><path class="rr-line" d="M306 74V92"/><rect class="rr-term" x="268" y="92" width="76" height="26" rx="13" ry="13"/><text class="rr-label" x="306" y="105">boolean</text><path class="rr-line" d="M306 118V136"/><path class="rr-line" d="M400 74V92"/><rect class="rr-term" x="370" y="92" width="60" height="26" rx="13" ry="13"/><text class="rr-label" x="400" y="105">float</text><path class="rr-line" d="M400 118V136"/><path class="rr-line" d="M494 74V92"/><rect class="rr-term" x="456" y="92" width="76" height="26" rx="13" ry="13"/><text class="rr-label" x="494" y="105">integer</text><path class="rr-line" d="M494 118V136"/><path class="rr-line" d="M592 74V92"/><rect class="rr-term" x="558" y="92" width="68" height="26" rx="13" ry="13"/><text class="rr-label" x="592" y="105">number</text><path class="rr-line" d="M592 118V136"/><path class="rr-line" d="M686 74V92"/><rect class="rr-term" x="652" y="92" width="68" height="26" rx="13" ry="13"/><text class="rr-label" x="686" y="105">string</text><path class="rr-line" d="M686 118V136"/><path class="rr-line" d="M768 74V92"/><rect class="rr-term" x="746" y="92" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="768" y="105">top</text><path class="rr-line" d="M768 118V136"/><path class="rr-line" d="M838 74V92"/><rect class="rr-term" x="816" y="92" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="838" y="105">nil</text><path class="rr-line" d="M838 118V136"/><path class="rr-line" d="M452 154V168"/><circle class="rr-cap" cx="452" cy="168" r="3"/></g><g id="scalar"><text class="rr-title" x="16" y="217">scalar</text><circle class="rr-cap" cx="265" cy="228" r="3"/><path class="rr-line" d="M265 228V242"/><path class="rr-line" d="M265 242V260"/><path class="rr-line" d="M50 260H480"/><path class="rr-line" d="M50 322H480"/><path class="rr-line" d="M265 322V340"/><path class="rr-line" d="M50 260V278"/><a href="#string"><rect class="rr-nonterm" x="16" y="278" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="50" y="291">string</text></a><path class="rr-line" d="M50 304V322"/><path class="rr-line" d="M140 260V278"/><a href="#exact"><rect class="rr-nonterm" x="110" y="278" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="140" y="291">exact</text></a><path class="rr-line" d="M140 304V322"/><path class="rr-line" d="M230 260V278"/><a href="#number"><rect class="rr-nonterm" x="196" y="278" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="230" y="291">number</text></a><path class="rr-line" d="M230 304V322"/><path class="rr-line" d="M316 260V278"/><rect class="rr-term" x="290" y="278" width="52" height="26" rx="13" ry="13"/><text class="rr-label" x="316" y="291">true</text><path class="rr-line" d="M316 304V322"/><path class="rr-line" d="M398 260V278"/><rect class="rr-term" x="368" y="278" width="60" height="26" rx="13" ry="13"/><text class="rr-label" x="398" y="291">false</text><path class="rr-line" d="M398 304V322"/><path class="rr-line" d="M480 260V278"/><rect class="rr-term" x="454" y="278" width="52" height="26" rx="13" ry="13"/><text class="rr-label" x="480" y="291">null</text><path class="rr-line" d="M480 304V322"/><path class="rr-line" d="M265 340V354"/><circle class="rr-cap" cx="265" cy="354" r="3"/></g><g id="string"><text class="rr-title" x="16" y="403">string</text><circle class="rr-cap" cx="74" cy="414" r="3"/><path class="rr-line" d="M74 414V428"/><a href="#DQUOTE"><rect class="rr-nonterm" x="40" y="428" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="74" y="441">DQUOTE</text></a><path class="rr-line" d="M74 454V472"/><path class="rr-line" d="M74 472V490"/><path class="rr-line" d="M42 490H106"/><path class="rr-line" d="M42 588H106"/><path class="rr-line" d="M74 588V606"/><path class="rr-line" d="M42 490V508"/><path class="rr-line" d="M42 508V526"/><a href="#char"><rect class="rr-nonterm" x="16" y="526" width="52" height="26" rx="4" ry="4"/><text class="rr-label" x="42" y="539">char</text></a><path class="rr-line" d="M42 552V570"/><path class="rr-line" d="M42 561H78"/><path class="rr-line" d="M42 517H78"/><path class="rr-line" d="M78 517V561"/><path class="rr-line" d="M42 570V588"/><path class="rr-line" d="M106 490V508"/><path class="rr-line" d="M106 508V520"/><path class="rr-line" d="M106 520V588"/><path class="rr-line" d="M74 606V624"/><a href="#DQUOTE"><rect class="rr-nonterm" x="40" y="624" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="74" y="637">DQUOTE</text></a><path class="rr-line" d="M74 650V664"/><circle class="rr-cap" cx="74" cy="664" r="3"/></g><g id="char"><text class="rr-title" x="16" y="713">char</text><circle class="rr-cap" cx="115" cy="724" r="3"/><path class="rr-line" d="M115 724V738"/><path class="rr-line" d="M115 738V756"/><path class="rr-line" d="M62 756H168"/><path class="rr-line" d="M62 862H168"/><path class="rr-line" d="M115 862V880"/><path class="rr-line" d="M62 756V774"/><a href="#unescaped"><rect class="rr-nonterm" x="16" y="774" width="92" height="26" rx="4" ry="4"/><text class="rr-label" x="62" y="787">unescaped</text></a><path class="rr-line" d="M62 800V862"/><path class="rr-line" d="M168 756V774"/><rect class="rr-term" x="153" y="774" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="168" y="787">\</text><path class="rr-line" d="M168 800V818"/><a href="#escape"><rect class="rr-nonterm" x="134" y="818" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="168" y="831">escape</text></a><path class="rr-line" d="M168 844V862"/><path class="rr-line" d="M115 880V894"/><circle class="rr-cap" cx="115" cy="894" r="3"/></g><g id="unescaped"><text class="rr-title" x="16" y="943">unescaped</text><circle class="rr-cap" cx="134" cy="954" r="3"/><path class="rr-line" d="M134 954V968"/><path class="rr-line" d="M134 968V986"/><path class="rr-line" d="M46 986H222"/><path class="rr-line" d="M46 1048H222"/><path class="rr-line" d="M134 1048V1066"/><path class="rr-line" d="M46 986V1004"/><rect class="rr-term" x="16" y="1004" width="60" height="26" rx="13" ry="13"/><text class="rr-label" x="46" y="1017">%x0-!</text><path class="rr-line" d="M46 1030V1048"/><path class="rr-line" d="M124 986V1004"/><rect class="rr-term" x="102" y="1004" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="124" y="1017">#-[</text><path class="rr-line" d="M124 1030V1048"/><path class="rr-line" d="M222 986V1004"/><rect class="rr-term" x="172" y="1004" width="100" height="26" rx="13" ry="13"/><text class="rr-label" x="222" y="1017">]-%x10FFFF</text><path class="rr-line" d="M222 1030V1048"/><path class="rr-line" d="M134 1066V1080"/><circle class="rr-cap" cx="134" cy="1080" r="3"/></g><g id="escape"><text class="rr-title" x="16" y="1129">escape</text><circle class="rr-cap" cx="287" cy="1140" r="3"/><path class="rr-line" d="M287 1140V1154"/><path class="rr-line" d="M287 1154V1172"/><path class="rr-line" d="M50 1172H524"/><path class="rr-line" d="M50 1410H524"/><path class="rr-line" d="M287 1410V1428"/><path class="rr-line" d="M50 1172V1190"/><a href="#DQUOTE"><rect class="rr-nonterm" x="16" y="1190" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="50" y="1203">DQUOTE</text></a><path class="rr-line" d="M50 1216V1410"/><path class="rr-line" d="M125 1172V1190"/><rect class="rr-term" x="110" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="125" y="1203">\</text><path class="rr-line" d="M125 1216V1410"/><path class="rr-line" d="M181 1172V1190"/><rect class="rr-term" x="166" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="181" y="1203">/</text><path class="rr-line" d="M181 1216V1410"/><path class="rr-line" d="M237 1172V1190"/><rect class="rr-term" x="222" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="237" y="1203">b</text><path class="rr-line" d="M237 1216V1410"/><path class="rr-line" d="M293 1172V1190"/><rect class="rr-term" x="278" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="293" y="1203">f</text><path class="rr-line" d="M293 1216V1410"/><path class="rr-line" d="M349 1172V1190"/><rect class="rr-term" x="334" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="349" y="1203">n</text><path class="rr-line" d="M349 1216V1410"/><path class="rr-line" d="M405 1172V1190"/><rect class="rr-term" x="390" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="405" y="1203">r</text><path class="rr-line" d="M405 1216V1410"/><path class="rr-line" d="M461 1172V1190"/><rect class="rr-term" x="446" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="461" y="1203">t</text><path class="rr-line" d="M461 1216V1410"/><path class="rr-line" d="M524 1172V1190"/><rect class="rr-term" x="509" y="1190" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="524" y="1203">u</text><path class="rr-line" d="M524 1216V1234"/><a href="#hex"><rect class="rr-nonterm" x="502" y="1234" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="524" y="1247">hex</text></a><path class="rr-line" d="M524 1260V1278"/><a href="#hex"><rect class="rr-nonterm" x="502" y="1278" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="524" y="1291">hex</text></a><path class="rr-line" d="M524 1304V1322"/><a href="#hex"><rect class="rr-nonterm" x="502" y="1322" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="524" y="1335">hex</text></a><path class="rr-line" d="M524 1348V1366"/><a href="#hex"><rect class="rr-nonterm" x="502" y="1366" width="44" height="26" rx="4" ry="4"/><text class="rr-label" x="524" y="1379">hex</text></a><path class="rr-line" d="M524 1392V1410"/><path class="rr-line" d="M287 1428V1442"/><circle class="rr-cap" cx="287" cy="1442" r="3"/></g><g id="hex"><text class="rr-title" x="16" y="1491">hex</text><circle class="rr-cap" cx="120" cy="1502" r="3"/><path class="rr-line" d="M120 1502V1516"/><path class="rr-line" d="M120 1516V1534"/><path class="rr-line" d="M46 1534H194"/><path class="rr-line" d="M46 1596H194"/><path class="rr-line" d="M120 1596V1614"/><path class="rr-line" d="M46 1534V1552"/><a href="#DIGIT"><rect class="rr-nonterm" x="16" y="1552" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="46" y="1565">DIGIT</text></a><path class="rr-line" d="M46 1578V1596"/><path class="rr-line" d="M124 1534V1552"/><rect class="rr-term" x="102" y="1552" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="124" y="1565">A-F</text><path class="rr-line" d="M124 1578V1596"/><path class="rr-line" d="M194 1534V1552"/><rect class="rr-term" x="172" y="1552" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="194" y="1565">a-f</text><path class="rr-line" d="M194 1578V1596"/><path class="rr-line" d="M120 1614V1628"/><circle class="rr-cap" cx="120" cy="1628" r="3"/></g><g id="exact"><text class="rr-title" x="16" y="1677">exact</text><circle class="rr-cap" cx="88" cy="1688" r="3"/><path class="rr-line" d="M88 1688V1702"/><path class="rr-line" d="M88 1702V1720"/><path class="rr-line" d="M71.5 1720H104.5"/><path class="rr-line" d="M71.5 1782H104.5"/><path class="rr-line" d="M88 1782V1800"/><path class="rr-line" d="M71.5 1720V1738"/><rect class="rr-term" x="56.5" y="1738" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="71.5" y="1751">-</text><path class="rr-line" d="M71.5 1764V1782"/><path class="rr-line" d="M104.5 1720V1738"/><path class="rr-line" d="M104.5 1738V1750"/><path class="rr-line" d="M104.5 1750V1782"/><path class="rr-line" d="M88 1800V1818"/><rect class="rr-term" x="70" y="1818" width="36" height="26" rx="13" ry="13"/><text class="rr-label" x="88" y="1831">0d</text><path class="rr-line" d="M88 1844V1862"/><a href="#digits"><rect class="rr-nonterm" x="54" y="1862" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="88" y="1875">digits</text></a><path class="rr-line" d="M88 1888V1906"/><path class="rr-line" d="M88 1906V1924"/><path class="rr-line" d="M62 1924H114"/><path class="rr-line" d="M62 2030H114"/><path class="rr-line" d="M88 2030V2048"/><path class="rr-line" d="M62 1924V1942"/><rect class="rr-term" x="47" y="1942" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="62" y="1955">.</text><path class="rr-line" d="M62 1968V1986"/><a href="#digits"><rect class="rr-nonterm" x="28" y="1986" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="62" y="1999">digits</text></a><path class="rr-line" d="M62 2012V2030"/><path class="rr-line" d="M114 1924V1942"/><path class="rr-line" d="M114 1942V1954"/><path class="rr-line" d="M114 1954V2030"/><path class="rr-line" d="M88 2048V2066"/><path class="rr-line" d="M88 2066V2084"/><path class="rr-line" d="M58 2084H118"/><path class="rr-line" d="M58 2146H118"/><path class="rr-line" d="M88 2146V2164"/><path class="rr-line" d="M58 2084V2102"/><a href="#exponent"><rect class="rr-nonterm" x="16" y="2102" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="58" y="2115">exponent</text></a><path class="rr-line" d="M58 2128V2146"/><path class="rr-line" d="M118 2084V2102"/><path class="rr-line" d="M118 2102V2114"/><path class="rr-line" d="M118 2114V2146"/><path class="rr-line" d="M88 2164V2178"/><circle class="rr-cap" cx="88" cy="2178" r="3"/></g><g id="number"><text class="rr-title" x="908" y="31">number</text><circle class="rr-cap" cx="980" cy="42" r="3"/><path class="rr-line" d="M980 42V56"/><path class="rr-line" d="M980 56V74"/><path class="rr-line" d="M963.5 74H996.5"/><path class="rr-line" d="M963.5 136H996.5"/><path class="rr-line" d="M980 136V154"/><path class="rr-line" d="M963.5 74V92"/><rect class="rr-term" x="948.5" y="92" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="963.5" y="105">-</text><path class="rr-line" d="M963.5 118V136"/><path class="rr-line" d="M996.5 74V92"/><path class="rr-line" d="M996.5 92V104"/><path class="rr-line" d="M996.5 104V136"/><path class="rr-line" d="M980 154V172"/><a href="#digits"><rect class="rr-nonterm" x="946" y="172" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="980" y="185">digits</text></a><path class="rr-line" d="M980 198V216"/><path class="rr-line" d="M980 216V234"/><path class="rr-line" d="M954 234H1006"/><path class="rr-line" d="M954 340H1006"/><path class="rr-line" d="M980 340V358"/><path class="rr-line" d="M954 234V252"/><rect class="rr-term" x="939" y="252" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="954" y="265">.</text><path class="rr-line" d="M954 278V296"/><a href="#digits"><rect class="rr-nonterm" x="920" y="296" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="954" y="309">digits</text></a><path class="rr-line" d="M954 322V340"/><path class="rr-line" d="M1006 234V252"/><path class="rr-line" d="M1006 252V264"/><path class="rr-line" d="M1006 264V340"/><path class="rr-line" d="M980 358V376"/><path class="rr-line" d="M980 376V394"/><path class="rr-line" d="M950 394H1010"/><path class="rr-line" d="M950 456H1010"/><path class="rr-line" d="M980 456V474"/><path class="rr-line" d="M950 394V412"/><a href="#exponent"><rect class="rr-nonterm" x="908" y="412" width="84" height="26" rx="4" ry="4"/><text class="rr-label" x="950" y="425">exponent</text></a><path class="rr-line" d="M950 438V456"/><path class="rr-line" d="M1010 394V412"/><path class="rr-line" d="M1010 412V424"/><path class="rr-line" d="M1010 424V456"/><path class="rr-line" d="M980 474V488"/><circle class="rr-cap" cx="980" cy="488" r="3"/></g><g id="exponent"><text class="rr-title" x="908" y="537">exponent</text><circle class="rr-cap" cx="981.5" cy="548" r="3"/><path class="rr-line" d="M981.5 548V562"/><path class="rr-line" d="M981.5 562V580"/><path class="rr-line" d="M953.5 580H1009.5"/><path class="rr-line" d="M953.5 642H1009.5"/><path class="rr-line" d="M981.5 642V660"/><path class="rr-line" d="M953.5 580V598"/><rect class="rr-term" x="938.5" y="598" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="953.5" y="611">e</text><path class="rr-line" d="M953.5 624V642"/><path class="rr-line" d="M1009.5 580V598"/><rect class="rr-term" x="994.5" y="598" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="1009.5" y="611">E</text><path class="rr-line" d="M1009.5 624V642"/><path class="rr-line" d="M981.5 660V678"/><path class="rr-line" d="M981.5 678V696"/><path class="rr-line" d="M951 696H1012"/><path class="rr-line" d="M951 830H1012"/><path class="rr-line" d="M981.5 830V848"/><path class="rr-line" d="M951 696V714"/><path class="rr-line" d="M951 714V732"/><path class="rr-line" d="M923 732H979"/><path class="rr-line" d="M923 794H979"/><path class="rr-line" d="M951 794V812"/><path class="rr-line" d="M923 732V750"/><rect class="rr-term" x="908" y="750" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="923" y="763">-</text><path class="rr-line" d="M923 776V794"/><path class="rr-line" d="M979 732V750"/><rect class="rr-term" x="964" y="750" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="979" y="763">+</text><path class="rr-line" d="M979 776V794"/><path class="rr-line" d="M951 812V830"/><path class="rr-line" d="M1012 696V714"/><path class="rr-line" d="M1012 714V726"/><path class="rr-line" d="M1012 726V830"/><path class="rr-line" d="M981.5 848V866"/><a href="#digits"><rect class="rr-nonterm" x="947.5" y="866" width="68" height="26" rx="4" ry="4"/><text class="rr-label" x="981.5" y="879">digits</text></a><path class="rr-line" d="M981.5 892V906"/><circle class="rr-cap" cx="981.5" cy="906" r="3"/></g><g id="digits"><text class="rr-title" x="908" y="955">digits</text><circle class="rr-cap" cx="938" cy="966" r="3"/><path class="rr-line" d="M938 966V980"/><path class="rr-line" d="M938 980V998"/><a href="#DIGIT"><rect class="rr-nonterm" x="908" y="998" width="60" height="26" rx="4" ry="4"/><text class="rr-label" x="938" y="1011">DIGIT</text></a><path class="rr-line" d="M938 1024V1042"/><path class="rr-line" d="M938 1033H978"/><path class="rr-line" d="M938 989H978"/><path class="rr-line" d="M978 989V1033"/><path class="rr-line" d="M938 1042V1056"/><circle class="rr-cap" cx="938" cy="1056" r="3"/></g><g id="ws"><text class="rr-title" x="908" y="1105">ws</text><circle class="rr-cap" cx="1105.25" cy="1116" r="3"/><path class="rr-line" d="M1105.25 1116V1130"/><path class="rr-line" d="M1105.25 1130V1148"/><path class="rr-line" d="M1024.5 1148H1186"/><path class="rr-line" d="M1024.5 1318H1186"/><path class="rr-line" d="M1105.25 1318V1336"/><path class="rr-line" d="M1024.5 1148V1166"/><path class="rr-line" d="M1024.5 1166V1184"/><path class="rr-line" d="M1024.5 1184V1202"/><path class="rr-line" d="M923 1202H1126"/><path class="rr-line" d="M923 1264H1126"/><path class="rr-line" d="M1024.5 1264V1282"/><path class="rr-line" d="M923 1202V1220"/><rect class="rr-term" x="908" y="1220" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="923" y="1233"> </text><path class="rr-line" d="M923 1246V1264"/><path class="rr-line" d="M986 1202V1220"/><rect class="rr-term" x="964" y="1220" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="986" y="1233">%x9</text><path class="rr-line" d="M986 1246V1264"/><path class="rr-line" d="M1056 1202V1220"/><rect class="rr-term" x="1034" y="1220" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="1056" y="1233">%xA</text><path class="rr-line" d="M1056 1246V1264"/><path class="rr-line" d="M1126 1202V1220"/><rect class="rr-term" x="1104" y="1220" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="1126" y="1233">%xD</text><path class="rr-line" d="M1126 1246V1264"/><path class="rr-line" d="M1024.5 1282V1300"/><path class="rr-line" d="M1024.5 1291H1158"/><path class="rr-line" d="M1024.5 1175H1158"/><path class="rr-line" d="M1158 1175V1291"/><path class="rr-line" d="M1024.5 1300V1318"/><path class="rr-line" d="M1186 1148V1166"/><path class="rr-line" d="M1186 1166V1178"/><path class="rr-line" d="M1186 1178V1318"/><path class="rr-line" d="M1105.25 1336V1350"/><circle class="rr-cap" cx="1105.25" cy="1350" r="3"/></g><g id="ALPHA"><text class="rr-title" x="908" y="1399">ALPHA</text><circle class="rr-cap" cx="965" cy="1410" r="3"/><path class="rr-line" d="M965 1410V1424"/><path class="rr-line" d="M965 1424V1442"/><path class="rr-line" d="M930 1442H1000"/><path class="rr-line" d="M930 1504H1000"/><path class="rr-line" d="M965 1504V1522"/><path class="rr-line" d="M930 1442V1460"/><rect class="rr-term" x="908" y="1460" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="930" y="1473">A-Z</text><path class="rr-line" d="M930 1486V1504"/><path class="rr-line" d="M1000 1442V1460"/><rect class="rr-term" x="978" y="1460" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="1000" y="1473">a-z</text><path class="rr-line" d="M1000 1486V1504"/><path class="rr-line" d="M965 1522V1536"/><circle class="rr-cap" cx="965" cy="1536" r="3"/></g><g id="DIGIT"><text class="rr-title" x="908" y="1585">DIGIT</text><circle class="rr-cap" cx="930" cy="1596" r="3"/><path class="rr-line" d="M930 1596V1610"/><rect class="rr-term" x="908" y="1610" width="44" height="26" rx="13" ry="13"/><text class="rr-label" x="930" y="1623">0-9</text><path class="rr-line" d="M930 1636V1650"/><circle class="rr-cap" cx="930" cy="1650" r="3"/></g><g id="DQUOTE"><text class="rr-title" x="908" y="1699">DQUOTE</text><circle class="rr-cap" cx="923" cy="1710" r="3"/><path class="rr-line" d="M923 1710V1724"/><rect class="rr-term" x="908" y="1724" width="30" height="26" rx="13" ry="13"/><text class="rr-label" x="923" y="1737">&quot;</text><path class="rr-line" d="M923 1750V1764"/><circle class="rr-cap" cx="923" cy="1764" r="3"/></g></g></svg>
</div><figcaption>Railroad diagram of the aontu grammar's lexical rules: the kind names, the scalar forms, a string as a quoted run of escaped or unescaped characters, the exact 0d literal, the plain number with its optional fraction and exponent, and whitespace.</figcaption></figure>

The function-name rule is drawn as one node rather than as a fan of
alternatives; the names are in the grammar text and in
[Functions](#functions), with what each one means.

## Generation

This section is about producing a **value** from a model. Producing
target-language **source** from one is a different thing with the same
name: see [Generate code from a model](/how-to/generate-code).

The ten component functions (`project`, `folder`, `file`, `content`,
`line`, `fragment`, `slot`, `inject`, `copyfiles`, and `listitems`)
answer a **component tree**, which generates as any other value does.
Each node's `cmp` key is the component name a generator runtime looks
up: `Project`, `CopyFiles`, `ListItems`, and the rest.
[jostraca](https://github.com/jostraca/jostraca) is one such runtime,
and reads the tree directly.

`generate` / `Generate` produces a native value (JSON-compatible) and
requires the model to be **fully concrete**:

- Disjunctions must be resolved to a single branch; a `*`-preferred
  branch is generated as that value.
- Unresolved **optional** keys are dropped.
- **type/hide**-marked map fields are omitted.
- An unresolved **type**, an unresolved **conjunction**, a **nil**, or
  `top` cannot be generated and raises an error.

**Exact values generate exactly.** The `0d` marker is source syntax
and does not survive into output; the digits do, all of them. A JSON
number is arbitrary-precision text, so nothing is lost on the way out:

```
x:0d9007199254740993   → {"x": 9007199254740993}
x:0d0.1+0d0.2          → {"x": 0.3}
a:0d1000 b:0d1e3       → {"a": 1000, "b": 1000.0}
```

The last line, run through the CLI's exact emitter:

<!-- test: scenario exact-gen -->
<!-- test: run -->
```sh
$ echo 'a: 0d1000 b: 0d1e3' | aontu
{
  "a": 1000,
  "b": 1000.0
}
```

That is the leaf distinction reaching the output: a
biginteger emits `1000`, and the integral bigdecimal beside it emits
`1000.0`, because that trailing place is part of a bigdecimal's own
digits. The plain family behaves the other way: an integral float
loses its point, so `b:2.0` generates `2`.

The native values follow: `bigint` and `Decimal` in TypeScript,
`*big.Int` and `*aontu.Decimal` in Go, each carrying the exact value.
TypeScript's `JSON.stringify` cannot serialise a `bigint`, so the
library exports its own exact emitter (`exactJSON`): the one the
`aontu` command uses.

Object key order is not significant in generated output, and within
the plain family neither is numeric kind. Between the exact leaves it
*is* significant, as the `1000` / `1000.0` pair shows, which is why the
shared suite pins those cases byte for byte rather than structurally.

## Subsumption

`A ⊒ B` ("A subsumes B") holds when **every instance the specific
value B admits, the general value A admits too**. It is the lattice's
own order, asked as a first-class query: `subsume(general, specific)`
in both engines, running after evaluation on finished trees, never
mutating them. The
verdict is three-valued plus `error`: `subsumes`, `does_not_subsume`
(with the failing path and both sides' canons as the witness),
`undecided` (always with a `sub_*` reason code, never silently), and
`error` for a source that does not stand up on its own. Findings reuse
the validation verb's report object with class `compat`; every code is
registered in `test/spec/errcodes.tsv`, and the whole behaviour is
pinned by `test/spec/subsume.tsv` in both engines.

**Soundness before completeness.** Where a rule cannot decide, the
answer folds toward `does_not_subsume` or `undecided`, never toward
"compatible": a gate that wrongly reports "breaking" costs a second
look, one that wrongly reports "compatible" ships the break.

### Profiles

| Profile | Compares |
|---------|----------|
| `values` | admitted value sets only |
| `defaults` (the default) | value sets, plus every effective default the specific side declares must survive into the general side unchanged |
| `gen` | `defaults`, plus the `type`/`hide` marks on corresponding nodes (they change the output shape) |

An **effective default** is a preference's own value, or, in a
disjunction holding several preferences, the value of the
lowest-ranked one (generation picks the lowest rank: `a:**1|*2`
generates `2`). Equal-rank preferences that disagree make the
effective default indeterminate (`sub_default_indeterminate`,
undecided). Adding a default where none existed is compatible;
changing or removing one is `compat_default_changed`: previously
generable documents materialise differently or become incomplete.

### Rules, by value former

| A (general) | B (specific) | A ⊒ B |
|-------------|--------------|-------|
| `top` | anything | yes |
| preference `*x` |: | compares as what it admits (its superior type); its default value is the profiles' business, not the value set's |
| unresolved residue (reference, variable, unreduced conjunct or function) on either side |: | `undecided` (`sub_unresolved`): there is no admitted set to compare |
| anything | disjunction | every specific alternative must be admitted by A; a concrete failing alternative is a witness (`compat_narrowed`), a non-concrete one is `undecided` (`sub_disjunct_distribution`) |
| disjunction | non-disjunction | some general alternative must admit B member-wise; failure with concrete B is a witness, otherwise `undecided` (`sub_disjunct_distribution`): member-wise failure is not proof, the distribution case |
| scalar kind | scalar kind or scalar | the general kind admits the specific kind (`number ⊒ integer`) or the scalar's kind; distinct leaves are disjoint |
| scalar kind | constraint residual | the kind covers the residual's domain: `number` admits any numeric residual, a numeric leaf kind admits a residual pinned to that leaf, `string` admits any pattern residual |
| constraint residual | constraint residual | per the constraint algebra's own [subsumption table](#subsumption-1); a `must` on the general side is `undecided` (`sub_evaluate_only`) |
| constraint residual | scalar | membership, with `must` again `undecided`; `unique()` and `length` demands admit no scalar |
| concrete scalar | concrete scalar | identity: a concrete value subsumes only itself (kind included) |
| map | map | see below; anything else is `compat_narrowed` |
| list | list | element-wise by position, with the same required/optional shape as maps |

There is no nil rule: an error-free evaluated document carries no nil
(failing disjunct members are discarded and every other nil collects
an error), and a source that does not stand alone answers `error`
before the walk begins.

### Maps, lists, closedness, optionality, spreads

- Every **required** key of the general side must be present and
  required in the specific side, and subsume; a missing or
  optional-ised key is `compat_required_added` (instances without it
  are admitted by the specific side but refused by the general).
- An **optional** key (`k?:`) of the general side compares only when
  the specific side has it; the specific side making a general
  optional key required merely narrows, which is compatible.
- A **closed** general bag (`close(…)`) requires the specific side to
  be closed and inside its declared key set; an open specific side, or
  a surplus key, is `compat_narrowed`.
- A **spread** template (`&:`) on the general side governs the
  specific side's surplus keys and its template (a missing specific
  template compares as `top`, so a general-only template does not
  subsume an open specific bag). A specific-only template narrows the
  specific side and refuses nothing. A **path-dependent** template
  (one whose meaning depends on where it lands: `key()`, a
  reference) cannot be compared structurally:
  `sub_path_dependent_spread`, undecided.
- Under the `gen` profile, `type`/`hide` marks must agree on
  corresponding nodes (`compat_marks_changed`).

The `at` option anchors both documents at one path before comparing
(the validation verb's `--at`); a path missing from either side is an
`error` verdict.

### Default validity

The relation also powers an advisory lint: the validation verb reports a
`pref_not_instance` finding (severity `warning`, class `compat`) when a
disjunction's effective default is not an instance of any **remaining**
alternative. Under the admission gate this is no longer a soundness
hole (the preferred branch contributes its own value to the admitted set,
so `level: *wran | info | warn | debug` is a well-defined enum `{wran,
info, warn, debug}` defaulting to `wran`) but that spelling is also
exactly the shape of a *typo'd* default (`*warn` was probably meant),
which nothing at meet time can distinguish. The warning flags the
boundary: a default drawn from the written alternatives (`*8080 |
integer`) is silent; a default that widens them is what the warning reports.
Repeating the branch (`*warn | warn | error`) states "the default is a
first-class member", silences the lint, and enforces the same admitted
set.

## Errors

Failures surface as messages (thrown as `AontuError` in TS, returned as
`error` in Go):

| Situation              | Message (contains) |
|------------------------|--------------------|
| scalar conflict        | `Cannot unify value: 2 with value: 1` |
| kind conflict          | `Cannot unify value: string with value: 1` |
| cross-leaf conflict    | `different kinds cannot unify` (`1 & 1.0`, `5 & 0d5`) |
| nested conflict        | reports the clashing leaf values |
| unresolved reference   | `Cannot resolve value: $.nope` |
| unknown variable       | `Cannot resolve …` |
| extra key on closed    | `closed` |
| lossy integer literal  | `not exactly representable`, plus the `0d` hint |
| inexact integer sum    | `exactly representable`, plus `0d<digits>` |
| float mixed with exact | `cannot mix` (naming both leaves) |
| over the exact budget  | `exceeds the exactness budget`, `at most 4096` |
| conflict marker left in | `conflict marker was found` (code `merge_conflict`) |
| wrong argument count   | `takes exactly one argument, but was given 2` (code `func_arity`) |
| key or element with no value | `written with no value after the colon` (code `elided_value`) |

**Every built-in has a fixed arity, checked at parse.** Nearly all take
exactly one argument; the two exceptions are `key`, which takes none or
one (how many levels up the path to read: none means the parent), and
`neq`, which takes one or more exclusions. A wrong count is a mistake in
the source and is refused before anything is evaluated.

**An elided value is refused.** A key, element or spread written with
nothing after its colon (`a:`, `a?:`, `[,]`, `[1,,2]`, `x:$obj&:`) is a
mistake in the source
rather than a null: writing it as a null made the mistake
indistinguishable from a deliberate `a:null`. The error names the key or
index, not the container, except for a spread, which has no key of its
own and so refuses the map it belongs to.

Three things that look similar are not elisions and keep working: an
explicit `a:null`, a colon chain (`a: b:1`, whose value is the nested
pair), and a trailing comma (`[1,]`, `{a:1,}`).

A comma group and a written list are different counts:
`upper("a","b")` is two arguments and is refused, while
`upper(["a","b"])` is one: a list, which `upper` then refuses for its
kind rather than its count.

A **version-control conflict marker** is refused before the parse, with
a code of its own, `merge_conflict`. A marker line would otherwise fall
to the bare-string rule (`<` and `=` are punctuation outside any
syntax) and be refused as a stray character, which says nothing about
the merge that left it there. The match is git's exact shape: seven
`<`, `=` or `>` at the start of a line, followed by the end of the line
or a space before the branch label. A document may still write those
characters anywhere else in a quoted string (`a:"<<<<<<<"`); a bare
`a:<<<<<<` is refused, but as `bare_punct`, never as a conflict.

In conflict messages the operand later in the source is named first
("…value: `<later>` with value: `<earlier>`") so the two sites are
distinguishable.

## Grammars: `abnf()` and `parse()`

`re()` is deliberately small: the portable pattern subset both engines
agree on. Real formats are published as **grammars** rather than as
regexes, and transcribing one into that subset is at best lossy. `abnf()`
takes the grammar as written.

**`abnf(g)` compiles an RFC 5234 grammar and answers its source**, so a
parser is an ordinary string that canons, hashes and unifies like any
other. The compile is what the call is for: a grammar that does not
compile is refused where it is DECLARED, once, rather than at every site
that parses with it. Write this as `grammar.aon`:

<!-- test: scenario abnf-parse -->
<!-- test: file grammar.aon -->
```aon
G: abnf("v = n \".\" n\nn = 1*d\nd = %x30-39\n")
a: parse($.G, "1.2")
```

<!-- test: run -->
```sh
$ aontu grammar.aon
{
  "G": "v = n \".\" n\nn = 1*d\nd = %x30-39\n",
  "a": {
    "kids": [
      {
        "kids": [],
        "rule": "d",
        "src": "1"
      },
      {
        "kids": [
          {
            "kids": [],
            "rule": "d",
            "src": "2"
          }
        ],
        "rule": "n",
        "src": "2"
      }
    ],
    "rule": "v",
    "src": "1.2"
  }
}
```

**`parse(g, v)` answers the syntax tree** as ordinary maps and lists:
`rule` names the production that matched, `src` the text it matched, and
`kids` its children. `kids` is always present and always a list, so a
schema written against the tree need not ask whether a leaf has the key.

**A failure to parse is a failure to unify.** The call answers a refusal
(`parse_failed`), so a field is refused rather than set to a value
meaning "no". That is what lets a grammar act as a check:

```aon
G: abnf("v = 1*d\nd = %x30-39\n")
ok: parse($.G, "12") # the tree
no: parse($.G, "x") # [aontu/parse_failed]
```

**`parse(g)` with no value is the grammar as a constraint**, which is
what a schema position wants: there is no value there yet to hand the
call. It is value-preserving, like every other atom in
[the constraint algebra](#the-constraint-algebra): it admits a string
the grammar accepts and answers that string, so it stays idempotent and
order-independent under a meet, and a default can sit beside it. Write
this as `check.aon`:

<!-- test: scenario abnf-constraint -->
<!-- test: file check.aon -->
```aon
G: abnf("v = 1*d\nd = %x30-39\n")
tag: *""|parse($.G)
ver: (*""|parse($.G)) & "12"
```

<!-- test: run -->
```sh
$ aontu check.aon
{
  "G": "v = 1*d\nd = %x30-39\n",
  "tag": "",
  "ver": "12"
}
```

`tag` takes its default because nothing met it; `ver` was written with
`"12"`, the grammar accepts it, and the field keeps the string it was
given. Written with `"xy"` instead, both branches fail and the
disjunction is empty (`[aontu/empty]`). The tree is what the
two-argument form is for: a constraint that also rewrote its value would
have to carry the grammar that produced it for a second meet to mean
anything, and nothing needs that yet. `aontu:system`'s `Semver` is the
worked use: see [The `aontu:system` vocabulary](#the-aontusystem-vocabulary).

Four things govern a grammar:

- **Whitespace is not skipped.** The grammars run here describe strings
  with no spaces in them, so `1 . 2` does not parse as `1.2`.
- **The empty string parses under no grammar.** The host engine answers
  an empty tree for empty input, which would make `parse(g, "")` succeed
  everywhere; it is refused instead.
- **The parse is bounded** at 100 000 steps. A grammar needing more is
  refused rather than run, for the reason `re()` refuses a pattern that
  backtracks exponentially.
- **`src` is the text the rule matched**, assembled from what the
  grammar consumed rather than sliced out of the input.
- **A character class must not contain a literal used elsewhere.**
  Write `digit = "0" / positive-digit`, never `digit = %x30-39`, when
  `"0"` also appears on its own. Where a class overlaps a literal the
  class wins, and the literal's alternative silently becomes
  unreachable, so a grammar that looks right refuses input it names.

The overlap rule is worth a moment, because a grammar that breaks it
looks correct and fails on ordinary input. The no-leading-zero rule of a
semantic version needs `"0"` as an alternative of its own:

<!-- test: skip an ABNF fragment, not an aontu document; the overlap rule it shows is pinned by the grammars in `aontu:system` and their rows in test/spec/aontu-system.tsv -->
```abnf
numeric-identifier = "0" / positive-digit *digit
positive-digit     = %x31-39
digit              = "0" / positive-digit
```

`digit` is spelled `"0" / positive-digit` rather than `%x30-39` so that
a `0` is always the same token wherever it appears. Spell it as the
class and `numeric-identifier`'s `"0"` branch is never reached, so
`1.0.0` stops parsing while `1.2.3` still does.

### A grammar reads better in backticks

A backtick string spans lines, so a grammar can be written as a grammar
rather than as a run of escapes. Write this as `media.aon`:

<!-- test: scenario abnf-backtick -->
<!-- test: file media.aon -->
```aon
G: abnf(
  `
media = "@" type "/" sub
type = 1*ALPHA
sub = 1*ALPHA
ALPHA = %x61-7A
`
)

ok: "@text/plain" & parse($.G)
```

<!-- test: run -->
```sh
$ aontu media.aon
{
  "G": "\nmedia = \"@\" type \"/\" sub\ntype = 1*ALPHA\nsub = 1*ALPHA\nALPHA = %x61-7A\n",
  "ok": "@text/plain"
}
```

The leading newline is part of the string and costs nothing: a grammar
is a list of rules, and ABNF ignores a blank line. The bundled
[`aontu:system`](#the-aontusystem-vocabulary) model still spells its two
grammars with `\n` escapes, because its text is held in a raw string
literal in each port and a raw string cannot contain a backtick.

### A grammar can say what it builds

The tree is the default, not the only answer. A **value annotation**, a
trailing comment on a production, says what that rule should build
instead. Write this as `build.aon`:

<!-- test: scenario abnf-build -->
<!-- test: file build.aon -->
```aon
G: hide(
  abnf(
    `
ver = maj "." min "." pat   ; @object maj min pat
maj = 1*DIGIT
min = 1*DIGIT
pat = 1*DIGIT
DIGIT = %x30-39
`
  )
)

v: parse($.G, "1.2.30")
```

<!-- test: run -->
```sh
$ aontu build.aon
{
  "v": {
    "maj": "1",
    "min": "2",
    "pat": "30"
  }
}
```

Nothing in `1.2.30` spells `maj`. The keys come from the comment, and
`; @object` names one member per part of the rule that produces a value:
a rule reference, a group or a repetition. A literal produces nothing
and is never named, which is why `"."` is not a member and three
references take three names.

**`; @array` names nothing** and takes every part that produces a value
as an element, in order. Shapes compose, because a part whose own rule
is annotated is assigned whole. Write this as `list.aon`:

<!-- test: scenario abnf-list -->
<!-- test: file list.aon -->
```aon
G: hide(
  abnf(
    `
list = "[" entry *( "," entry ) "]"   ; @array
entry = key "=" val   ; @object key val
key = 1*ALPHA
val = 1*DIGIT
ALPHA = %x61-7A
DIGIT = %x30-39
`
  )
)

entries: parse($.G, "[width=10,height=20]")
```

<!-- test: run -->
```sh
$ aontu list.aon
{
  "entries": [
    {
      "key": "width",
      "val": "10"
    },
    {
      "key": "height",
      "val": "20"
    }
  ]
}
```

A repetition contributes one element per item, so a list comes out a
list rather than the run's matched text.

Five things to know before writing one:

- **It is about the output, never the language.** A comment is the one
  place in RFC 5234 that carries no meaning of its own, so delete every
  annotation and the same inputs parse. You get the tree back.
- **Every leaf is still text.** The annotation chooses the container,
  and there is no scalar form, so `"30"` is a string and stays one.
- **The leading fold is answered, not removed.** Naming a member keeps
  it, so the `"v"` the next section needs is unnecessary here. Where the
  fold would erase a member's own built value the compile is REFUSED,
  with a diagnostic naming the rule and what to write instead.
- **A rule that builds a value contributes no text** to whatever
  contains it. Mixing the two is supported; just do not read `src` on a
  node that contains an annotated rule.
- **The refusals are deliberate.** More than one alternative, a member
  count that does not match the parts, a duplicate member name, and a
  leading member whose own rule builds a value are all refused where the
  grammar is declared rather than built into a differently shaped value.

**Either builder nests inside the other.** An `@array` is a member of
an `@object`, an element of another `@array`, or an object's only
member, and answers the same value in both engines.

### Shaping an unannotated tree

The answer is the RAW tree, so a document that wants natural structure
builds it with the language's own verbs. Three do the work:
[`pick`](#projecting-fields-pick) projects one field of every child,
[`filter`](#selecting-filter-and-match) selects children by rule, and
[`join`](#folding-to-a-string-join) folds a one-element selection back
to a scalar. `hide()` keeps the grammar and the tree out of the
generated document. Write this as `shape.aon`:

<!-- test: scenario abnf-shape -->
<!-- test: file shape.aon -->
```aon
G: hide(
  abnf(
    `
ver = "v" maj "." min "." pat
maj = 1*DIGIT
min = 1*DIGIT
pat = 1*DIGIT
DIGIT = %x30-39
`
  )
)

t: hide(parse($.G, "v1.2.30"))

parts: pick($.t.kids, src)
names: pick($.t.kids, rule)
minor: join(pick(filter($.t.kids, { rule:"min" }), src))
whole: $.t.src
```

<!-- test: run -->
```sh
$ aontu shape.aon
{
  "minor": "2",
  "names": [
    "maj",
    "min",
    "pat"
  ],
  "parts": [
    "1",
    "2",
    "30"
  ],
  "whole": "v1.2.30"
}
```

**A leading field loses its name**, and that is the one shape rule a
grammar author has to know. The compiler folds a production's first
element into the parent's node, so `ver = maj "." min "." pat` answers a
first child named `DIGIT` where the version above answers `maj`. The fix
is the `"v"` above: give the production a leading terminal and every
field keeps its name. Both engines do this identically, so it is a
property of the grammar compiler rather than a difference between the
ports.

Both limits belong to the tree, and the annotation above answers the
first: name the members and the leading field keeps its name with no
terminal in front of it. The second it does not answer. Every leaf is
the **text** the rule matched, so `"30"` is a string under either
spelling, and nothing turns it into `30`.

## The constraint algebra

> All nine atoms (the bounds `min`/`max`/`above`/`below`, the
> exclusion `neq`, the pattern `re`, the sizing atoms `length` and
> `unique`, and the evaluate-only `must`) are implemented in both
> engines over the four-leaf number tower, pinned by the
> [`test/spec/constraint-*.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/) suites. Violations
> raise the registered `constraint` code, and a pattern outside the
> portable subset raises `constraint_pattern`. Known limit: a
> preference meeting a constraint in a CONJUNCT (`min(1024) & *8080`)
> does not resolve to the default: use the disjunct form
> (`*8080 | (integer & min(1024))`). Under the admission gate
> the disjunct form also ENFORCES on override: an
> out-of-bound peer is refused rather than silently bypassing the
> constraint branch, so the recommended spelling both defaults and
> validates.

### Vocabulary

Nine builtins join the function registry. Eight are **Band A**: full
lattice citizens with defined meet, emptiness, subsumption, and
canonical form. One is **Band B**: evaluate-only, and reported
as such. There is no new grammar: atoms are ordinary functions.

| Atom | Band | Meaning |
|------|------|---------|
| `min(n: number\|string) : constraint` | A | value ≥ x (numeric, or string with lexical order) |
| `max(n: number\|string) : constraint` | A | value ≤ x |
| `above(n: number\|string) : constraint` | A | value > x |
| `below(n: number\|string) : constraint` | A | value < x |
| `neq(...vals: number\|string) : constraint` | A | value is none of the listed scalars (leaf-aware) |
| `re(text p: string) : constraint` | A | string matches pattern p (unanchored, portable subset) |
| `length(n: number\|constraint) : constraint` | A | length/count satisfies integer constraint c |
| `unique(projector k?: string) : constraint` | A | members pairwise distinct (list elements, map values) |
| `must(trial c: any, text msg: string) : constraint` | B | evaluate-only check with an author message |

### Bounds and the number tower

Three rulings, each forced by the tower's disjoint leaves
(`integer`, `float`, `biginteger`, `bigdecimal` under the pure
supertype `number`):

1. **Order is a property of the number line, not the leaf.** A
   numeric bound constrains the value's mathematical position and is
   satisfied by ANY numeric leaf at an admissible position:
   `min(0) & 0d5` is `0d5`, `above(1) & 1.5` is `1.5`. Comparison is
   exact across leaves: every binary64 is exactly a rational, so a
   `float` compares with an exact decimal without rounding, in both
   implementations. A numeric bound implies the kind `number` (the
   supertype); it never narrows the peer's leaf.
2. **Endpoints keep their written leaf.** Canon round-trips kind
   (rule R4), so `min(1)`, `min(1.0)` and `min(0d1)` are distinct
   canonical texts denoting the same bound point. When two endpoints
   at the SAME point meet (`min(1) & min(1.0)`), the survivor is the
   one whose leaf sits lowest in the tower order
   `integer < float < biginteger < bigdecimal`: a deterministic
   choice both implementations make identically.
3. **`neq` excludes by scalar identity (leaf and value**) because
   that is what scalar identity means in the lattice (`1 & 1.0` is a
   conflict; `1|1.0` keeps both alternatives). `neq(1)` excludes the
   integer `1` and admits the float `1.0`. To exclude a point on the
   whole number line, list its leaves: `neq(1, 1.0)` (the exact
   leaves are opt-in, so `0d`-free documents need only these two).

String bounds (`min("a")`) use lexical code-point order and imply
`string`. Mixing domains in one meet (`min(0) & min("a")`) is empty
and yields nil.

### The meet

`atom & atom` (same domain) is symbolic: decided at
schema-composition time, before any data arrives:

| Meet | Result |
|------|--------|
| interval & interval | intersection: `min(0) & min(5)` → `min(5)`; `min(2) & max(10) & max(7)` → `min(2)&max(7)` |
| `neq` & `neq` | exclusion-set union, arguments sorted |
| `re` & `re` | regex-set accumulation (patterns sorted; never simplified) |
| `length(c1)` & `length(c2)` | `length(c1 & c2)`: the count atom reuses the numeric algebra recursively |
| bound & kind | domain narrowing: `integer & min(0)` keeps both (interval gains the integral-domain flag); `number & min(0)` keeps `min(0)` (already implied); `string & min(0)` → nil |
| bound & concrete scalar | membership by exact comparison → the scalar, or a two-site nil |
| bound & `must` | both kept; `must` stays opaque |

Meets are commutative and idempotent by construction (normalisation,
not term order, defines the result) so the lattice guarantee is
preserved.

### Emptiness

Decided **eagerly at unification time** where it is exact, and never
guessed where it is not:

- Empty interval: `min(5) & max(3)` → nil, both sites reported.
- Integral gap: an integral-domain interval containing no integral
  value: `integer & above(1) & below(2)` → nil. (Applies when the
  domain is narrowed by `integer` or `biginteger`.)
- Point deletion **requires a narrowed leaf**: `min(3) & max(3)`
  admits the point 3 in any numeric leaf, so `neq(3)` (which excludes
  only the integer `3`) does NOT empty it, but
  `integer & min(3) & max(3) & neq(3)` → nil. This is the tower
  re-derivation of the pre-tower example, and the spec rows pin both
  directions.
- `length(c)` is empty iff `c & integer & min(0)` is.
- Regex emptiness is deliberately approximate: distinct `re` atoms
  accumulate and are never declared empty: sound (no false
  conflicts), incomplete (some contradictions surface only against
  data).

### Subsumption

*The `subsume` query implements this table in both engines (its
per-former rules are in [Subsumption](#subsumption) above). One
mapping to note: the
query answers the `must` row's "never" as `undecided` with reason
`sub_evaluate_only`: the admitted set is opaque, which is
undecided rather than refused.*

`A ⊒ B` ("A subsumes B", B is an instance of A) holds when **every
value B admits, A admits too**. It is the lattice's own order, and for
this algebra it is decided per atom family rather than by search. Three
properties make it useful: it is reflexive (`A ⊒ A`), transitive, and
`A ⊒ B` exactly when `A & B` is `B`, so an implementation has a free
cross-check against the meet table.

**Soundness before completeness.** Where a rule below cannot decide, the
answer is **not subsumed**, never a guess. That direction is the safe
one for the `subsume` query built on it: a compatibility check that wrongly
reports "breaking" costs a reviewer a second look, while one that
wrongly reports "compatible" ships the break. Two rules are approximate
in this sense and are marked; the rest are exact.

| A (general) | B (specific) | A ⊒ B when |
|-------------|--------------|------------|
| no kind     | any          | always: an unnarrowed residual admits every leaf its domain has |
| `number`    | any numeric leaf, or a numeric residual | always: the supertype admits every leaf |
| leaf `k`    | leaf `k'`    | `k == k'`; distinct leaves are disjoint, so neither subsumes the other |
| interval    | interval     | A's interval contains B's: A's lower endpoint is at or below B's, A's upper at or above, and where endpoints coincide A's may not be the open one |
| interval    | concrete scalar | the scalar is admitted by A (the membership rule of the meet) |
| no bound on a side | any    | an absent endpoint is ±∞ and contains everything |
| `neq(S)`    | `neq(T)`     | `S ⊆ T`: excluding *fewer* values is more general. `neq(1) ⊒ neq(1,2)` |
| `neq(S)`    | concrete scalar | the scalar is in neither S nor excluded by A's other atoms |
| `re(P)`     | `re(Q)`      | **approximate**: `P ⊆ Q` as a *set of pattern strings*. Adding a pattern narrows, so `re("a") ⊒ re("a")&re("b")` |
| `length(c)`    | `length(d)`     | `c ⊒ d`, recursively: the count atom reuses this same table over the integer domain |
| absent `length`/`unique` | present | always: an unsized residual admits every size |
| `unique(k)` | `unique()`   | always (reflexive); nothing else subsumes or is subsumed by it |
| `must(f)`   | anything     | **never**: a Band B predicate is opaque, so A's admitted set is unknown |
| anything    | `must(…)`    | decided by A's other atoms alone; an extra `must` on B can only narrow B |
| anything    | nil (empty)  | always: the empty set is an instance of everything |

A whole residual subsumes another when **every** row above holds for the
corresponding atom families, and the domains agree (a numeric residual
never subsumes a string one, or a container one).

**Why the two approximations are where they are.** `re` compares
patterns as *text* because deciding that `^a` admits everything `^ab`
admits is regex containment, which this algebra deliberately does not
do: the same ruling that stops two `re` atoms being declared empty at
composition time. `must` is opaque by construction: that is what Band B
*means*. In both cases the answer is "not subsumed", so the error is
always toward reporting a difference that is not there.

**Normalisation makes the spelling irrelevant.** Subsumption is decided
over the *normalised* residual, so two spellings of one constraint
subsume each other in both directions. `min(0)&max(10)` and `max(10)&min(0)`
normalise identically, and the canonical atom order below is what makes
that true by construction rather than by a special case.

### Endpoint tightening: lazy endpoints, eager emptiness

The pre-tower draft left open whether `integer & above(0.5)` should
rewrite to `integer&min(1)`. **Decided: no endpoint rewriting.**
Under the tower, a synthesised endpoint must be given a leaf the
author never wrote (`1`? `0d1`?), and that invented spelling leaks
into canonical text and, later, canon hashes. Emptiness needs no
synthesis, so the algebra keeps *eager emptiness* (the
composition-time contradiction detection that is the point of Band A)
with *lazy endpoints* (canon stays what was written, normalised only
by the meet rules above).

### Canonical form

A residual constraint renders as its normalised atoms joined by `&`
in a fixed order (**kind, lower bound (`min`/`above`), upper bound
(`max`/`below`), `neq` (arguments sorted), `re` (patterns sorted),
`length`, `unique`, `must`**) no spaces, reparseable, endpoint leaves
preserved:

```aon
a: integer & max(10) & min(0) & min(2)
# canon: {"a":integer&min(2)&max(10)}
```

`parse(canon(v)) == v` holds for every atom and every normalisation
rule: the reparse produces a conjunct of atoms that normalises back
to the identical residual. Spec rows pin a round-trip and an
order-independence case (`min(0)&max(10)` vs `max(10)&min(0)` →
identical canon) for each rule.

Two renderings follow from that round trip rather than from taste:

-  **`length`'s argument renders unabridged**, implied parts and all:
  `length(3)` canonicalises to `length(integer&min(3)&max(3))`, because
  that *is* the residual the count must satisfy (`length(c)` always
  meets `integer & min(0)`; see [`length`
  semantics](#length-semantics)). Abbreviating it would mean a second
  set of rules for when the implied parts may be dropped, and canon is a
  normal form ([`aontu hash`](/docs/reference-api#aontu-hash) digests it) not
  a pretty-printer.
- **A bare domain is spelled out when nothing implies it.** An order
  atom's argument names its own domain, so `min(2)` need not say
  `number`. A sizing residual carries no order, so `string & length(3)`
  renders as `string&length(...)`: drop the `string` and the reparse would
  admit lists and maps of three members too.

### `re` and the portable pattern subset

`re(p)` admits a string matching `p`. Matching is **unanchored** in
both implementations, so `re("el")` admits `"hello"`; anchor with `^`
and `$` to constrain the whole string. The string kind is implied, so
`string & re("x")` canonicalises to `re("x")`: the same rule that
makes `number & min(0)` canonicalise to `min(0)`.

A pattern must mean the same thing in both implementations **and cost
about the same to evaluate**, and the two host regex engines guarantee
neither: TypeScript compiles with JavaScript's backtracking `RegExp`, Go
with RE2: a different language, in a different complexity class, over a
different alphabet.

aontu therefore **defines** the pattern language and rewrites your
pattern into a form neither engine can read two ways. Only the rewritten
form reaches a host engine.

**What `re` accepts**

| | |
|---|---|
| literals | `a`, and `\` before any of `. \ + * ? ( ) [ ] { } \| ^ $ /` to mean it literally; `\xHH` |
| classes | `[abc]`, `[^abc]`, `[a-z]`; `\-` inside a class for a literal hyphen |
| abbreviations | `\d \D \w \W \s \S` and `.` |
| repetition | `*` `+` `?` `{n}` `{n,}` `{n,m}` with every count **1000 or less**, and the lazy forms `*?` `+?` `??` |
| grouping | `(…)`, `(?:…)`, alternation `a|b` |
| anchors | `^` `$` `\A` `\z` `\b` `\B` |
| control | `\t \n \r \f \v` |

**aontu defines the abbreviations**, and inherits neither host's:

| written | means | 
|---|---|
| `\d` / `\D` | `[0-9]` / `[^0-9]` |
| `\w` / `\W` | `[0-9A-Za-z_]` / `[^0-9A-Za-z_]` |
| `\s` / `\S` | `[ \t\n\r\f\v]` / `[^ \t\n\r\f\v]` |
| `.` | `[^\n]` |
| `\A` / `\z` | `^` / `$` |

These are the small ASCII sets deliberately. **`\s` is those six
characters only**: it does *not* match U+00A0 or the other Unicode
spaces, though JavaScript's `\s` does, because a non-breaking space in
a config value is a mistake worth catching rather than a space worth
accepting in silence. Matching counts **code points**, not UTF-16 code
units, in both implementations.

**What `re` refuses**, and why rewriting cannot help:

| Construct | Why |
|-----------|-----|
| backreferences `\1`–`\9`, `\k<name>` | RE2 has no equivalent, and a pattern using one is not a regular expression at all |
| lookaround `(?=)` `(?!)` `(?<=)` `(?<!)` | same: not in RE2 |
| any `(?…)` but `(?:` | named groups are spelled `(?P<n>` in RE2 and `(?<n>` in JavaScript; inline flags change the meaning of everything after them |
| `\p{…}`, `\x{…}`, `\u`, `\Z` | spelled differently, or read as a literal by one engine |
| POSIX classes `[[:alpha:]]` | RE2 only |
| empty classes `[]`, `[^]` | a never-matching class in JavaScript, a parse error in RE2 |
| a repeat count above **1000** (`a{1001}`, `a{2,1001}`) | RE2 refuses to compile it and JavaScript accepts it, so the same schema was valid in one implementation and not the other. The bound is **aontu's**, checked in the normaliser before either engine sees the pattern, which is why the refusal is the same in both |
| a quantifier applied to `^`, `$`, `\b` or `\B` | there is nothing to repeat: JavaScript under the `u` flag calls it a syntax error, RE2 quantifies the assertion and matches |
| a `{` that opens no counted quantifier (`x{y}`), or a `}` that closes none | JavaScript reads each as a lone quantifier bracket and refuses; RE2 reads both as literals |
| a quantifier on a group containing a quantifier or an alternation | **cost, not meaning**: see below |

The last one is different in kind. `(a+)+$` against twenty-nine `a`s and
a `!` takes **45 seconds** in JavaScript and 0.065s under RE2, growing
exponentially; a regex match is counted by no evaluator budget ([the
trust contract](/docs/trust), clause 2), so without this rule an untrusted
schema could stall the TypeScript evaluator indefinitely. Rewriting
cannot fix a complexity difference, so this one is refused rather than
normalised. `(?:a|b)+` is caught by it too, though it is safe: deciding
that two alternation branches cannot both match is real work. Write
`[ab]+`. Unquantified groups, top-level alternation, `(?:ab)+`, `(a)(b)`
and `(a)+` all pass, and a quantifier inside a character class is a
literal character (`[a+]+` is fine).

The refusal message names the offending construct *and* restates this
whole table, so an author never has to find this page to recover.

Patterns **accumulate** and are never simplified: `re("x") & re("a")`
keeps both (sorted by pattern text in canon), and a value must match
every one. Two `re` atoms are never declared empty at composition time,
because deciding that one pattern excludes another is regex
containment, which this algebra deliberately does not do. A contradiction
between patterns therefore surfaces against data, not against the
schema.

Canon renders the pattern **as written**, never the rewritten form:
canon round-trips source, and the semantic hash
([`aontu hash`](/docs/reference-api#aontu-hash)) is taken over canon.

### `length` semantics

`length` applies to strings, lists, and maps, with the domain fixed by
the peer:

- **strings**: length in **Unicode code points**: not UTF-16 code
  units (TS's native count) and not bytes (Go's): `length(1) & "𝄞"`
  holds, in both implementations. Astral-plane rows are part of the
  spec suite, not an implementation accident.
- **lists**: element count. **maps**: entry count.

Its argument is any integer-domain constraint: `length(3)` means exactly
3; `length(min(2) & max(5))` means between 2 and 5. Every argument meets
`integer & min(0)` (a count is a non-negative whole number) which is
what makes `length(max(-1))` and `length(1.5)` empty on their own, and what
canon renders.

Like every other atom's argument, it **residuates** until it settles:
`length($.n)` waits for `$.n`, then checks the count. Only
a *settled* argument of the wrong shape (a string, a boolean, a
contradictory kind) is refused.

A sizing residual has **no domain of its own** (a count says nothing
about what is counted) so meeting a kind *sets* one rather than merely
agreeing with it. `string & length(3)` is a three-character string, and
`number & length(3)` is empty, because a number has neither a length nor
members. `min(2) & unique()` and `re("^a") & unique()` are empty for the
same reason.

**`length` counts what generates.** An optional key that never resolves
is dropped at generation, so it does not count. The constraint is a
claim about the data, and the data is what comes out:

```aon
a: string & length(3)
a: abc
b: length(1) & { x:1 y?:number }
```

```json
{"a":"abc","b":{"x":1}}
```

`b` holds because the generated value is `{"x":1}`: one member.

**When the count is decided.** An optional key **survives unification
carrying its unresolved value** (`{x:1, y?:number}` canonicalises as
`{"x":1,"y"?:number}`) and is dropped only in generation
(`BagVal.gen`). It is tempting to conclude that the count is therefore
unknowable until generation, and that `length` must wait for a drop. It
must not: nothing in the fixpoint performs that drop, so an atom waiting
for it waits forever.

The count is knowable earlier, because *whether a member will generate*
is decided before generation runs. A member is skipped by generation
when it carries a `type` or `hide` mark, or when it is an optional key
whose value cannot generate. So:

- **Every optional child settled**: this includes `{x:1, y?:number}`,
  where the map converges immediately and `y` holds an
  unresolved kind. The count is known, and `length` decides at composition
  time like every other atom, `length(1) & {x:1, y?:number}` included.
- **Some optional child still converging**: `{x:1, y?:$.z}` before `z`
  resolves, where the child's fate genuinely is not yet decided. `length`
  **residuates**: it stays in place and is retried, exactly as an
  arithmetic operator with a non-concrete operand does.

So `length` is eager in the ordinary case and defers only where the answer
is not yet determined, which is the same discipline every other
deferring value in the language follows. What is never deferred is the
atom's own arithmetic: `length(min(5) & max(3))` is empty at composition
time whatever map it meets, because the inner interval is empty on its
own.

### Sizing atoms fold last

There is one more rule the sizing atoms need, and it is not shared with
the order atoms: **`length` and `unique` are the last terms of a conjunct
to fold.**

An order atom may decide the moment it meets a scalar, because meeting
further scalars can only narrow: `min(2) & 1 & 2` is a conflict however
it is grouped. A sizing atom cannot, because meeting further containers
*grows* the member set:

```aon
a: length(2)
a: { x:1 y:2 }
```

```json
{"a":{"x":1,"y":2}}
```

Layering fragments like this is the point of the language, and an atom
that folded early would count `{x:1}` alone and refuse it. So the two
kinds of atom take different slots in the conjunct sort order (`cjo`):
the order atoms fold before containers, the sizing atoms after every
value that could contribute a member. The size is then read once, from
the merged container.

Written order does not matter (`a: {x:1} a: {y:2} a: length(2)` is the
same value) which is the property the sort order exists to guarantee.

**`must` folds last for the same reason**, and the slot is named for
what the three atoms share rather than for sizing alone: `length`,
`unique` and `must` all need the *whole* value. An evaluate-only check
run against the first fragment would refuse `a: must(length(2),m)` /
`a: {x:1}` / `a: {y:2}` on a count of one, exactly as an early-folding
`length` would.

**And "last" reaches past the document.** Sorting the atom to the end of
its conjunct is only half the rule, because a container can settle in
one document and still gain members from another: the data half of a
[`vet`](/docs/reference-api#aontu-vet) meet, an
[`@` include](#source-loading-), a later [`pack`](#generating-children-pack-and-each).
An atom that decided when its own conjunct settled decided too early
there, and `vet` then reported `valid` for data the evaluator refuses.

So a sizing verdict is taken only when **more members cannot change
it**: members accumulate under unification, they are never removed:

| reading | permanent? | what happens |
|---|---|---|
| an upper bound **violated** | yes: more members only add | refuse now |
| an upper bound **satisfied** | no | the atom stays on the value |
| a lower bound **satisfied** | yes | that reading is spent |
| a lower bound **violated** | no | the atom stays on the value |
| a **duplicate** found | yes | refuse now |
| distinctness **so far** | no | the atom stays on the value |

Anything provisional **residuates**, exactly as an atom over a container
that has not settled does, and is decided at **generation**, which is
where nothing more can arrive. So `length(min(1)) & {&: {r: integer}}`
no longer refuses the schema it was written for, and
`length(max(2)) & {&: {r: integer}}` no longer passes three records.
A residuated atom is visible in [canon](#canonical-form), which is the
correct rendering: the value really does still carry the constraint.

### `unique` semantics

`unique()` holds when the members of a container are **pairwise
distinct**, compared by **canonical form**: two members are the same
member exactly when their canons are equal.

Canon is the right yardstick because it is already this language's
normal form for "the same value": `ConstraintVal.same` compares canons,
and `DisjunctVal` deduplicates members that way. It is deterministic,
byte-identical across the two implementations (every `canon` spec row
pins that), and it is defined for *every* value, which scalar identity
is not.

For scalar members it reduces exactly to scalar identity (leaf *and*
value) because canon round-trips kind: `1` and `1.0` canon differently,
so `[1, 1.0]` is distinct under the number tower, exactly as `1 & 1.0`
is a conflict. For **container** members it gives structural equality
without a separate rule: `[{x:1},{x:1}]` is not unique, because both
elements canon as `{"x":1}`, and `[{x:1},{x:2}]` is.

It applies to two shapes:

- **lists**: the elements are pairwise distinct.
- **maps**: the entry *values* are pairwise distinct. (Keys are
  distinct by construction, so there is nothing to check there.)

Any other peer (a string, a number, a boolean, `null`) is a domain
conflict: no scalar has members. The members it does compare are the
members that *generate*, the same set `length` counts, so a `hide`n entry
and a dropped optional are not members here either.

**`unique(k)` is uniqueness by projection.** "No two services share a
port" compares one field of each member rather than the whole member,
and the atom's single argument is that projector: the arity was
reserved for it, and is now spent:

```aon
services: unique(port) & {
  api: { port:8080 name:"api" }
  auth: { port:8443 name:"auth" }
}
```

```json
{"services": {
   "api":  {"port": 8080, "name": "api"},
   "auth": {"port": 8443, "name": "auth"}}}
```

A member with no such key **fails** rather than being skipped:
distinctness that cannot be shown is distinctness the collection does
not have, and skipping would let one keyless record hide a duplicate.
A member that is not a map fails for the same reason: it has no key
to project.

`unique(a) & unique(b)` demands **both**; the keys accumulate rather
than the later one replacing the earlier, since each names a different
axis of distinctness and dropping either would silently weaken the
constraint. Canon renders them sorted after the bare atom
(`unique()&unique("a")&unique("b")`), so two documents saying the same
thing render the same string. In subsumption, a general `unique(k)`
needs the same key on the specific side (distinctness on `port` says
nothing about distinctness on `name`) while a specific that adds a
key still subsumes, because more distinctness is narrower.

### Cross-field bounds and residuation

An atom whose argument contains an unresolved reference, or whose
peer is not yet concrete, **residuates**: no error, stays in place,
re-evaluated on later fixpoint passes. Atoms only ever suspend or
intersect (never force evaluation) so evaluation order cannot
change results.

```aon
scaling: floor: 2
scaling: ceiling: 10
scaling: target: integer & min($.scaling.floor) & max($.scaling.ceiling)

# target normalises to integer&min(2)&max(10) once floor/ceiling resolve
```

A residual that survives to generation is an error, exactly like an
unresolved kind today; exhaustion of the pass budget while residuals
are still refining is `budget_passes` ([the trust
contract](/docs/trust), clause 2).

### Band B: `must`

`must(c, msg)` wraps any aontu value as an evaluate-only check: it
residuates until its peer is concrete, then requires the peer to
unify with `c`; on failure the author's message is attached to the
nil (`NilVal.details`). `must` never participates in emptiness or
subsumption, and any report including one states that the check was
evaluate-only: the channel for domain rules beyond the
algebra.

### Errors

A constraint violation is an ordinary two-site nil in the existing
message family (`Cannot unify value: 99999 with value: max(65535)`),
with machine-readable `details`: the failing atom, the normalised
admissible interval/sets, and any `must` message. Codes ride the
[error-code registry](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv); rendering into
reports belongs to [`aontu vet`](/docs/reference-api#aontu-vet).

### Named constraint aliases

The algebra has no `int8`, `uint16` or `port` keyword, and does not
need one. A constraint is an ordinary value, so a name for one is an
ordinary field, and a `type()`-marked block gives you a library of
them that unifies like everything else and emits nothing.

This section names constraints by their **path** (`$.type.port`). For
the name-only spelling, `%port`, see [Aliases `%`](#aliases-); the two
are the same idea reached two ways, and a `%` alias may hold a
constraint just as a `type()` field can:

```aon
type: type({})

type: {
  uint8: integer & min(0) & max(255)
  int8: integer & min(-128) & max(127)
  port: integer & min(1) & max(65535)
}

listen: $.type.port
listen: 8080
```

```json
{ "listen": 8080 }
```

Three properties make this work, and all three are rules stated
elsewhere in this document rather than anything special to constraints:

- **The block is schema, so it does not generate.** `type()` marks its
  value as metadata, and a map field whose value is type-marked is
  omitted from the enclosing map ([Marks](#marks-type-and-hide)). The
  aliases are present for unification and absent from output.
- **A reference copies with the marks cleared.** `$.type.port` lands on
  a type-marked value and yields an unmarked one, so `listen` emits
  normally.
- **The alias is a constraint, not a value**, so it meets the concrete
  value at the referring field exactly as if it had been written there.

The key name is not reserved: `type` above is a field called `type`
that happens to be `type()`-marked. `defs`, `schema` or anything else
reads the same to the engine.

An out-of-range value is refused at the field that holds it. Write
this as `uint8.aon`:

<!-- test: scenario alias-range -->
<!-- test: file uint8.aon -->
```aon
type: type({})
type: uint8: integer & min(0) & max(255)
a: $.type.uint8
a: 300
```

<!-- test: run -->
```sh
$ aontu uint8.aon
[aontu/constraint]: Cannot unify values at path $.a
...
$ echo $?
1
```

`300` does not satisfy `max(255)`.

**Name the kind as well as the bounds.** `min(0) & max(255)` alone is a
bound on *numbers*, so `1.5` satisfies it; a sized integer is
`integer & min(0) & max(255)`. This is the one mistake the idiom
invites, and the reason the aliases above all lead with `integer`:

```aon
loose: type({})
loose: byteish: min(0) & max(255)
a: $.loose.byteish
a: 1.5
```

```json
{ "a": 1.5 }
```

Because an alias is a value, the aliases compose: one can be
written in terms of another, and a reference to an alias may be met
with further constraints at the point of use.

```aon
type: type({})
type: { n:integer & min(0) u8:$.type.n & max(255) }

small: $.type.u8 & max(15)
small: 12
```

```json
{ "small": 12 }
```

`u8` is written in terms of `n`, and `small` narrows `u8` again where
it is used. Nothing here is special to constraints: it is the meet,
applied to values that happen to be constraints.

A value that violates the composition is refused against the whole
residual, not against whichever atom noticed first:

```
Cannot unify value: 20 with value: integer&min(0)&max(15)
```

`max(255)` is absent because `max(15)` subsumes it, and `integer` and
`min(0)` are present because `20` still has to satisfy them. That
normalised form is what `vet --format json` reports as `expected`, and
what the value's [canon](#canonical-form) states.

---

# Generation reference

_The component tree: every component node, its props and the children it admits, and what aontu render and aontu trace do with it._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-generation.md · Page: https://aontu.dev/docs/reference-generation

A component tree is the value a generator answers: nested nodes that
name every output file, every folder above it, and every span of text
inside it.

This page is normative for the tree's shape, for each component's props
and admitted children, and for what each verb writes when handed one.
The constructs that *compute* a tree are specified in the language
reference and not here: [Generating children: `pack` and
`each`](/docs/reference-language#generating-children-pack-and-each),
[Selecting: `filter` and `match`](/docs/reference-language#selecting-filter-and-match),
[The placeholder `_`](/docs/reference-language#the-placeholder-_),
[Transforming: `emit`](/docs/reference-language#transforming-emit), and
[Generation](/docs/reference-language#generation) for what `generate`
requires of a model. Each component function's one-entry summary is in
that page's [Functions](/docs/reference-language#functions) index, and the
arity and argument modes of every name are in [The call
surface](/docs/reference-functions#the-call-surface).

The option lists and synopses for the verbs belong to the API
reference, under [`aontu render`](/docs/reference-api#aontu-render) and
[`aontu trace`](/docs/reference-api#aontu-trace), and the error codes
named below to [The codes](/docs/reference-errors#the-codes). Behaviour
stated here is pinned by [`test/spec/cmp.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/cmp.tsv) and
[`test/spec/trace.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/trace.tsv), which both
implementations run.

## Contents

- [The component tree](#the-component-tree)
- [The components](#the-components)
- [What `aontu render` writes](#what-aontu-render-writes)
- [What `aontu trace` reports](#what-aontu-trace-reports)
- [Order and determinism](#order-and-determinism)
- [Related](#related)

---

## The component tree

Every component function answers a map of exactly three keys: `cmp`,
the string a generator runtime looks the component up by; `props`, a map
holding that component's declared props; and `children`, a list of
further nodes. A node built by a component function is
[closed](/docs/reference-language#closed-values-close--open), so a fourth
key is a `closed` refusal rather than an ignored field:

```aon
out: file("a.txt", ["x" ["y" "z"]])
```

```json
{
  "out": {
    "children": [
      { "children": [], "cmp": "Line", "props": { "src": "x" } },
      { "children": [], "cmp": "Line", "props": { "src": "y" } },
      { "children": [], "cmp": "Line", "props": { "src": "z" } }
    ],
    "cmp": "File",
    "props": { "name": "a.txt" }
  }
}
```

**A bare string child is a `line`**, terminator included, which is what
a template body line desugars to; an explicit `content()` is still a
span with no terminator (`cmp-bare-string-child`,
`cmp-bare-string-spliced`). The conversion happens only where `line` is
an admitted child, so `file`, `fragment`, `slot`, `inject`, and
`listitems` take a bare string and `folder` and `project` refuse one
(`cmp-bare-string-needs-line`, `cmp-bare-string-not-in-project`). The
children argument is flattened in place, recursively
(`cmp-children-splice`), under the rule [Transforming:
`emit`](/docs/reference-language#transforming-emit) states for a body.

A node is an ordinary map addressed by path, printing its keys in the
[order every value prints in](#order-and-determinism). Write a
`tree.aon`:

<!-- test: scenario generation-tree -->
<!-- test: file tree.aon -->
```aon
out: project(".", [folder("src", [file("main.js", ["const x = 1"])])])
```

and address a node inside it by path:

<!-- test: run -->
```sh
$ aontu model get '$.out.children.0.cmp' tree.aon
"Folder"
$ aontu model get '$.out.children.0.children.0.children.0' tree.aon
{
  "children": [],
  "cmp": "Line",
  "props": {
    "src": "const x = 1"
  }
}
```

[Generate code from a model](/how-to/generate-code) reads a whole
tree with the same verb.

**The prop schema is enforced by the component function, not by the
tree.** A hand-written map carrying a `cmp` key that names a component
is admitted as a child, and its props are never checked against the
schema below: an undeclared prop reaches the runtime, where eight of
the ten components drop it in silence. A prop a component does not
declare is refused at the call.

## The components

Ten functions build nodes. A leaf handed a children list is a
`func_arity` error ([Class `parse`](/docs/reference-errors#class-parse))
rather than a bad argument (`cmp-leaf-takes-no-children`). The
shorthand column names the prop a bare string spec sets.

| signature | node | shorthand | children | props |
|---|---|---|---|---|
| `project(spec?: string\|map, children?: list) : map` | `Project` | `folder`, optional | `project`, `folder`, `file`, `copyfiles` | `name`, `folder` |
| `folder(spec: string\|map, children?: list) : map` | `Folder` | `name` | `folder`, `file`, `copyfiles` | `name` |
| `file(spec: string\|map, children?: list) : map` | `File` | `name` | `content`, `line`, `fragment`, `inject`, `listitems`, `copyfiles` | `name`, `exclude`, `mode` |
| `content(spec: string\|map) : map` | `Content` | `src`, a span | none | `arg`, `src`, `name`, `indent`, `extra`, `replace`, `raw` |
| `line(spec: string\|map) : map` | `Line` | `src`, a span | none | `arg`, `src`, `name`, `indent`, `extra`, `replace`, `raw` |
| `fragment(spec: string\|map, children?: list) : map` | `Fragment` | `from` | `slot`, `content`, `line`, `listitems` | `from`, `indent`, `replace`, `eject` |
| `slot(spec: string\|map, children?: list) : map` | `Slot` | `name` | `content`, `line`, `fragment`, `listitems` | `name` |
| `inject(spec: string\|map, children?: list) : map` | `Inject` | `name` | `content`, `line`, `listitems` | `name`, `markers`, `exclude` |
| `copyfiles(spec: string\|map) : map` | `CopyFiles` | `from` | none | `from`, `to`, `replace`, `exclude` |
| `listitems(spec: map, children?: list) : map` | `ListItems` | none | `content`, `line`, `fragment` | `item`, `line`, `indent` |

Every bad call answers the same error code, `invalid-arg` ([Class
`conflict`](/docs/reference-errors#class-conflict)). The message's attempt
word is the offending name rather than a fixed verb, and it is one of
five:

- the prop that is not declared;
- the text prop's own name, where that prop is required and missing, or
  is present and is not a non-empty string, so `project({folder: 1})`
  and `project({folder: ""})` both answer `Cannot folder`;
- `item`, where a `listitems` bag is absent or is not a list, so
  `listitems({})` and `listitems({item: "a"})` both answer
  `Cannot item`;
- `children`, for a child the component does not admit;
- `spec`, where the argument is not a form the component's spec takes,
  which covers the string `listitems("a")`.

Where more than one prop is wrong, the one named is the **first
written**, not the first in sorted order, and both ports walk the
written key list to keep that promise (`cmp-props-names-first-written`).

A child the component does not admit:

<!-- test: scenario generation-refusal -->
<!-- test: run -->
```sh
$ echo 'out: folder("src", [line("x")])' | aontu
[aontu/invalid-arg]: Cannot children values at path $.out
...
$ echo $?
1
```

What each component adds to the table:

- **`project`**: the one component whose text prop is optional, so
  `project()` answers a node with empty props. A `folder` written as
  anything but a non-empty string is refused by that name
  (`cmp-project-folder-kind`, `cmp-project-folder-not-empty`).
- **`folder`**: `name` is required and non-empty
  (`cmp-folder-needs-a-name`, `cmp-folder-name-not-empty`).
- **`file`**: `name` is required and may hold `/`, and the folders on
  the way are made. `exclude: true` leaves the file alone when it is
  already there, and is the only form each runtime honours: a path or a
  list of paths is matched against the COMPONENT path rather than the
  output path, and the Go runtime skips nothing for either. `mode` is
  the permission bits
  as a number: `mode: 493` and `mode: 0o755` are the same value, both
  spellings being [numeric
  literals](/docs/reference-language#lexical-structure), and
  `test/spec/cmp.tsv` writes `mode: 420` for `0o644`.
- **`content`**: the text prop may be the empty string, so `content("")`
  is a node where `folder("")` is a refusal. The text is taken from
  `arg`, then `src`, then a string child, and a node holding none of the
  three writes nothing. `indent` is a count of spaces or a literal
  prefix.
- **`line`**: the same seven props as `content`, from the same alias.
  The name is also a `listitems` prop, which is a different thing
  spelled the same way.
- **`fragment`**: `from` resolves against the output folder. `eject`
  names a start and end marker pair, and only the region between them is
  read. The source file must exist. `fragment` and `copyfiles` are the
  two components whose props the runtime validates against a closed set,
  so an undeclared prop on a hand-written `Fragment` or `CopyFiles` node
  is refused by name at render time rather than dropped, and `eject` is
  refused unless it is a list of two markers: `eject: true` builds a
  node (`cmp-props-fragment-all`) and does not render.
- **`slot`**: `name` is required and non-empty, and fills the
  `<[SLOT:name]>` marker of the enclosing `fragment`. The unnamed
  `<[SLOT]>` marker takes that fragment's non-`slot` children instead,
  so a bare string, `content`, `line`, or `listitems` written directly
  under a `fragment` lands there; a `fragment` carrying such children
  whose source has no unnamed marker is a refusal at exit 2.
- **`inject`**: the default marker pair is `#--START--#` followed by a
  newline, and a newline followed by `#--END--#`. A `markers` pair with
  exactly one empty member is refused at render, and both empty reads as
  unset. `inject` rewrites a file that already exists and never creates
  one, so a missing target is a refusal at exit 2.
- **`copyfiles`**: `from` resolves against the process working directory.
  `replace` substitutes in copied text, and a binary file is copied
  through unchanged. This `replace`, here and in the span set, is a
  substitution the runtime applies, and not [`emit`'s `replace`
  key](/docs/reference-language#replacing-text-in-a-body-replace-and-esc).
- **`listitems`**: the one component with no text prop, so it takes no
  bare string spec (`cmp-listitems-takes-no-string`), and the one with a
  bag: `item` must be present and must be a list, whatever else it holds
  (`cmp-listitems-needs-item`, `cmp-listitems-item-is-a-list`). `line`
  here is a prop and not the component of that name.

## What `aontu render` writes

Per node, on disk:

| node | effect |
|---|---|
| `Project` | Joins `folder` under the run's output folder. `name` writes nothing. |
| `Folder` | One or more path segments below the enclosing folder, so `folder("a/b")` is two of them. |
| `File` | One output file at `name` below the enclosing folder, with `mode` and `exclude` applied. |
| `Content` | A span of text, with no terminator. |
| `Line` | The same span, with a newline after it. |
| `Fragment` | The file at `from`, resolved against the output folder, with its markers filled by the slots beneath. |
| `Slot` | One marker of the enclosing `Fragment`. |
| `Inject` | The region between a marker pair, in a file that already exists. |
| `CopyFiles` | A copy of `from`, resolved against the process working directory, at `to` below the enclosing folder. |
| `ListItems` | Its children once per element of `item`, then a blank line unless `line: false`. |

Where a root lands is stated under [`aontu
render`](/docs/reference-api#aontu-render). One segment of the path is the
tree's own: a `Project`'s `folder` is joined under `<path>` as a further
segment, so `project("pkg", [file("a.txt")])` against `build2` writes
`build2/pkg/a.txt`, and the project's `name` adds nothing to the path.

**Text reaches the file verbatim.** `render` sets `raw` on every
`Content` and `Line` node, so the substitution the runtime would
otherwise apply to a span does not run, and a `$$…$$` sequence in a shell
script, a doc comment, or a regex is written as it stands. Two props in
the span set follow from that: `extra` and `replace` are inert unless
the node writes `raw: false` itself. `indent` is placement rather than
substitution and applies either way.

**The write is not atomic.** The runtime writes as it walks, so a
refusal part way through leaves the files written before it on disk. Two
generators in one set claiming a single output path are refused that
way, at exit 2, with the first file already written.

`--check` writes nothing, and its flag entry is under [`aontu
render`](/docs/reference-api#aontu-render). What it holds is the tree's own
surface: the files the generator emits and not the directory, so a file
that stops being generated is not reported. It answers the question
`render` answers, so it reports no difference for a file `render`
leaves alone: a `file` carrying `exclude: true` is reported neither for
its bytes nor for its mode. The one difference it still reports for
such a file is `missing`, because `exclude` is consulted only when the
target is already there, and `render` writes an absent one. A reported
path is the one the generator names, relative to `<path>`, rather than
the path the command was given.

Write a `gen.aon` answering a project of one file:

<!-- test: scenario generation-render -->
<!-- test: file gen.aon -->
```aon
out: project(".", [folder("src", [file("main.js", ["const x = 1" ""])])])
```

and a `build/src/main.js` holding different bytes:

<!-- test: file build/src/main.js -->
```text
const x = 2
```

<!-- test: run -->
```sh
$ aontu render --check gen.aon build
content: src/main.js
$ echo $?
1
```

The same edit under `exclude: true` is not a difference, because
`render` does not make it. Write a generator that excludes its one
file, as `gen.aon`:

<!-- test: scenario generation-render-exclude -->
<!-- test: file gen.aon -->
```aon
out: project(".", [file({ name:"keep.txt" exclude:true }, ["generated"])])
```

and a hand-written `build/keep.txt`:

<!-- test: file build/keep.txt -->
```text
hand written
```

`render` leaves those bytes where they are, and the check then
reports nothing:

<!-- test: run -->
```sh
$ aontu render gen.aon build
$ aontu render --check gen.aon build
$ echo $?
0
```

Exit codes for the verb are listed under [`aontu
render`](/docs/reference-api#aontu-render), and the five values the engine
uses under [Exit codes](/docs/reference-errors#exit-codes). Two of them are
decided by the tree rather than by the command:

| refusal | exit |
|---|---|
| the tree root is a `File` with no `name` | 4 |
| the tree is refused before any write: an absolute or climbing `Project` folder, or a `props` that is not a map | 4 |

A climbing `Project` folder is refused while the tree is still data, at
exit 4; a climbing `File` or `Folder` name is refused by the write, at
exit 2. The nameless-`File` guard reads the tree root alone, so a
hand-written nameless `File` nested inside a `Project` renders and
writes a file called `undefined`.

## What `aontu trace` reports

`trace` reports one row per piece an
[`emit`](/docs/reference-language#transforming-emit) rule stamped,
attributed to the file it reached. The text form is four tab-separated
columns, in this order:

1. `file`, the `name` prop of the innermost enclosing `File` node.
2. `at`, the address of the stamped piece in the document.
3. `node`, the address of the model node the dispatch matched, and the
   empty string where the selection was written inline at the call and
   so has no address (`test/spec/trace.tsv`).
4. `rule`, the rule table's address, `#`, and the template's index,
   addressed as [`aontu trace`](/docs/reference-api#aontu-trace) states.

`--format json` answers one object under a `trace` key, whose entries
carry the same four fields keyed `at`, `file`, `node`, and `rule`. Both
ports print the four in those two orders.

Write a `gen.aon` whose fields come from a rule set:

<!-- test: scenario generation-trace -->
<!-- test: file gen.aon -->
```aon
fields: [n:"id" n:"name"]

%field = emit(_, { match:n:string body: [line("  " + .n + ": string")] })

out: file("t.ts", ["type T = {" emit($.fields, %field) "}"])
```

Ask what wrote each line:

<!-- test: run -->
```sh
$ aontu trace gen.aon
t.ts	$.children.1	$.fields.0	$.%field#0
t.ts	$.children.2	$.fields.1	$.%field#0
$ aontu trace --format json gen.aon
{"trace":[{"at":"$.children.1","file":"t.ts","node":"$.fields.0","rule":"$.%field#0"},{"at":"$.children.2","file":"t.ts","node":"$.fields.1","rule":"$.%field#0"}]}
```

Four rules decide what has no row:

- A piece no rule stamped, which covers every hand-written child
  (`trace-no-rule-no-entry`).
- A piece under no `File` node at all, and a piece under a `File`-shaped
  map whose `props` is not a map, which names no file.
- The descendants of a stamped piece. Only the top level of a spliced
  result is stamped, so a rule whose body is
  `[file(.n + ".txt", [line(.n)])]` puts a row on the `File` node and
  none on the `Line` inside it.
- Anything outside the anchor, which is `$.out` unless `--at` names
  another path.

The `file` column is the innermost enclosing `File`, by longest matching
address prefix rather than by first match, and a `File` node that a rule
stamped itself gets a row naming itself.

`trace` reads a `<file>` whose name does not end in `.aon` as a
generator in the target's own syntax, desugared by its marker. That
includes a `.aontu` file, which [`aontu render`](/docs/reference-api#aontu-render)
and [`aontu fmt`](/docs/reference-api#aontu-fmt) both read as plain aontu;
traced, it has no `$.out` and answers `no_path` ([Class
`reference`](/docs/reference-errors#class-reference)) at exit 4. Exit codes
are `0` for a report, empty or not, `2` for usage or I/O, and `4` where
the document does not stand up or `--at` names nothing.

## Order and determinism

`children` is a list and keeps document order. Each spliced child is
checked against the same parent's admitted children
(`cmp-splice-refuses-inside`).

A node's own three keys print in code-point order, `children`, `cmp`,
then `props`, and a props map prints its keys sorted the same way,
whatever order they were written in: `cmp-map-spec` writes
`file({name: "a.ts", mode: 420})` and pins the printed props as `mode`
then `name`. List elements print in index order.

`emit` visits its selection in the [order every bag
reader uses](/docs/reference-language#generating-children-pack-and-each).

`pack` answers a map, and no component accepts a map as `children`, so a
`pack` result reaches a `file` as `Cannot children`. `each` and `emit`
answer lists and feed `children` directly. [Generate code from a
model](/how-to/generate-code) makes the practical point about which to
reach for.

Where rules nest, the innermost owns its pieces. A nested `emit`
flattens its result into the parent's piece list in place, and the
stamp is applied only where a piece carries none, so an outer rule never
overwrites an inner rule's attribution. The stamps themselves are opt
in: they are built only for a run that asks for them, which `trace`
does and ordinary evaluation does not, so no stamp appears in the tree
`generate` or `model get` answers.

Both implementations promise the same tree and the same report, under
[Behavioural parity](/docs/reference-api#behavioural-parity), and the Go
component table mirrors the TypeScript one entry for entry. What
`render` writes is one step further out: the two ports call two separate
builds of the generator runtime, and it is the goldens in
[`use-cases/15-code-generation/`](/use-cases/15-code-generation), held
by `render --check`, that hold the bytes to each other.

## Related

- [Language reference, Generation](/docs/reference-language#generation).
  What `generate` requires of a model, and the per-function index entry
  for each of the ten components.
- [The call surface](/docs/reference-functions#the-call-surface). The
  arity, argument modes, and result word of every declared name.
- [The codes](/docs/reference-errors#the-codes). `invalid-arg`,
  `func_arity`, and `no_path` by class, with the exit code each run ends
  on.
- [`aontu render`](/docs/reference-api#aontu-render). The flags, the
  synopsis, where a root lands, and the groups `--format json` sorts
  written files into.
- [Generate code from a model](/how-to/generate-code). The worked
  recipe: a rule set over the records, a tree of files and lines, and
  the bytes held against goldens.
- [Trust and determinism](/docs/trust#clause-4-sandboxing). Why nothing in
  the engine writes a file, and which tree-shape refusals stand before
  `render` hands the tree on.

---

# Functions reference

_The call surface of all 64 built-ins: arity, argument modes, accepted kinds and result words, as one table and as slices through it._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-functions.md · Page: https://aontu.dev/docs/reference-functions

aontu has 64 built-in functions and no user-defined ones. The name set
is closed: `test/spec/signature.tsv` declares one line per built-in, both
implementations carry a copy of that file inlined at build time, and a
name the engine does not hold is refused while the document is parsed.

This page is normative for the call surface. It states how many
arguments each name takes, which mode each argument slot is read in,
which kinds a slot admits, the result word the declaration gives, and
what a call is refused for. It tabulates that surface, then slices it
by argument mode, by result word, by rest slot, and by optional slot.
It says nothing
about what any function means.

What each function means, with an example, is the language reference's
[Functions](/docs/reference-language#functions) index: one entry per
built-in, keyed by its whole signature. Nothing here repeats it. Each
refusal code named below, with its class and the version it was
registered at, is the [errors reference](/docs/reference-errors#the-codes),
which is normative for the registry and for the shape of a report.

## Contents

- [How a call is checked](#how-a-call-is-checked)
- [Argument modes](#argument-modes)
- [The call surface](#the-call-surface)
- [Slices](#slices)
- [Related](#related)

---

## How a call is checked

The arity is decided at parse, the kinds at evaluation, and the two
answer different codes.

The permitted count comes from the declaration: a required slot raises
the minimum, an optional slot raises the maximum only, and a rest slot
leaves the maximum open while counting its group's length toward the
minimum. The value builder compares that interval against the number of
comma-separated terms the author wrote and, on a miss, puts a nil
carrying `func_arity` where the call was. Its class is `parse`. No
argument has been evaluated at that point, so the same broken reference
is invisible while the count is wrong and reported once the count is
right:

<!-- test: run -->
```sh
$ echo 'a: add($.nope)' | aontu
[aontu/func_arity]: Cannot resolve value at path $.a
...
add takes exactly two arguments, but was given 1.
...
$ echo $?
1
$ echo 'a: add(1, $.nope)' | aontu
[aontu/no_path]: Cannot resolve value at path $.a
...
$ echo $?
1
```

The wording in that message is rendered from the interval and collapses
cases, so it is not itself the interval: `rep` takes three arguments and
prints `rep takes exactly one argument`, `project` takes none to two and
prints `project takes no arguments or one`, and `match`'s floor of three
is invisible in `match takes one or more arguments`. The bound is the
arity column of [the call surface](#the-call-surface). The count is of
written terms, so a list literal counts as one: `add([1 2])` misses
`add`'s interval of two, while `neq([1 2])` meets `neq`'s minimum of one
([Errors](/docs/reference-language#errors)).

Kinds are checked at evaluation, after every argument has settled and
before the function resolves. The signature gate walks the declared
slots, stops at a rest slot, and reads only a slot whose mode is `value`
and whose declared type words are all scalar kinds: `string`, `number`,
`integer`, `float`, `biginteger`, `bigdecimal`, `boolean`, and `path`. A
slot declared `any`, `map`, `list`, or `constraint` is skipped, and so
is an argument that is absent, nil, or unsettled. What the gate admits
is a concrete scalar whose leaf kind is or sits below one of the
declared words, so `number` admits every numeric leaf and `string`
admits a path, while a scalar kind written in place of a value is
refused. A miss is `func_arg`, class `conflict`, and the message prints
the whole declaration and names the slot by number and by name:

<!-- test: run -->
```sh
$ echo 'a: upper(true)' | aontu
[aontu/func_arg]: Cannot unify values at path $.a
...
  argument 1 (`s`) was `true`.
...
$ echo $?
1
```

The declared words are read as kinds, so a numeric leaf fits `number`
and a path fits `string`:

```aon
n: add(1.5, 2)
s: upper(path($.n))
```

```json
{
  "n": 3.5,
  "s": "$.N"
}
```

`upper` declares `s: string|number`, and the path was admitted as a
string.

Eighteen names have a gated slot. The declaration alone would gate 23:
`key` is exempt by name and answers `key_level` for a bad argument, and
`min`, `max`, `above`, and `below` are constraint atoms that never reach
the gate, so a bad argument to one of those is `invalid-arg`. One
further boundary sits inside `parse`, whose one-argument form is the
constraint form and [meets](/docs/unification) its peer instead of
resolving: so `parse(1)` is `mapval_no_gen` and `parse(1, "x")` is
`func_arg`.

Absence is decided before the signature gate: the first absent argument
drops the whole call, and `maybe` is the only built-in that forgives it
([Optional input: `maybe`](/docs/reference-language#optional-input-maybe)).

The order a call is refused in, first to last:

1. `func_arity`, from the written count, at parse.
2. Whatever refuses while the value-mode arguments are driven. A broken
   reference is `no_path`.
3. Absence, which drops the call.
4. `func_arg`, from the signature gate.
5. The function's own reading of its slots, which is `invalid-arg` or a
   code of that verb's own.

There is no declaration form for a function anywhere in the grammar:
the `name` rule enumerates the built-in names and the `func` rule admits
no other
([The published grammar](/docs/reference-language#the-published-grammar)).
A name the engine does not hold answers `unknown_function`, class
`reference`, also at parse, and a call cannot be applied to a further
argument list:

<!-- test: run -->
```sh
$ echo 'a: nonesuch(1)' | aontu
[aontu/unknown_function]: Cannot resolve value at path $.a
...
$ echo $?
1
$ echo 'a: add(1)("x")' | aontu
[aontu/unknown_function]: Cannot resolve value at path $.a
...
$ echo $?
1
```

A name in a value position is an ordinary string, because only `name(`
builds a call
([Lexical structure](/docs/reference-language#lexical-structure)):

```aon
a: upper
```

```json
{
  "a": "upper"
}
```

An alias ([Aliases `%`](/docs/reference-language#aliases-)) may hold a
call, which is how a named constraint and a named `emit` table are
written ([Named constraint
aliases](/docs/reference-language#named-constraint-aliases)), and it still
cannot be a function name: `%Up = upper` followed by `%Up("x")` is
`unknown_function`.

```aon
%U = upper("x")
n: %U
```

```json
{
  "n": "X"
}
```

There is no partial application: an under-supplied call is `func_arity`
at parse ([Limitations and
trade-offs](/docs/explanation#limitations-and-trade-offs)). A parse-time
nil is reported where the value is reached rather than where it was
built, so a miss inside a losing disjunct branch is silent:

```aon
a: *1|add(1)
```

```json
{
  "a": 1
}
```

## Argument modes

A declaration marks each slot with the mode it is read in and leaves
`value` unmarked. The mode decides what the evaluator does with the slot
before the function resolves, and which refusal a bad argument gets: the
signature gate reads value-mode slots only, so in every other mode the
refusal comes from the function's own reading of the settled argument.
What each mode word means is the language reference's
[Functions](/docs/reference-language#functions) index intro. The grammar of
the declaration line is the header of `test/spec/signature.tsv`.

An unmarked slot is driven: it is unified against
[top](/docs/unification) before the call resolves, and the call resolves
only once every value slot has settled. At least one value slot appears
in 54 of the 64 names, and 46 of those carry no other mode. Three names
have no slots at all (`acyclic`, `list`, and `map`), so 49 of the 64 use
no mode but `value`, and 15 carry at least one slot in another mode.

The five other modes, the slots that carry them, what the evaluator does
with the slot, and where the semantics are specified:

- `template`, five slots: `each`'s, `emit`'s, and `pack`'s second
  argument, and `refer`'s and `rel`'s only argument. `pack`, `each`, and
  `emit` instantiate the template per destination rather than driving
  it; `refer` and `rel` drive it at the call site.
  [Generating children: `pack` and
  `each`](/docs/reference-language#generating-children-pack-and-each),
  [Transforming: `emit`](/docs/reference-language#transforming-emit),
  [The placeholder `_`](/docs/reference-language#the-placeholder-_),
  [Checked links: `refer(t?)`](/docs/reference-language#checked-links-refert),
  and [The argument is a template, not an
  address](/docs/reference-language#the-argument-is-a-template-not-an-address).
- `projector`, four slots: `pick`'s and `sort`'s second argument, and
  `inverse`'s and `unique`'s only argument. `pick` and `sort` never
  drive the slot (`test/spec/agg.tsv:115-122`,
  `test/spec/sort.tsv:70-72`); `inverse` and `unique` do, and then
  require the settled value to be a name
  (`test/spec/relation.tsv:112-113,170-174`,
  `test/spec/constraint-length.tsv:79-90`).
  [Projecting fields: `pick`](/docs/reference-language#projecting-fields-pick),
  [Ordering: `sort`](/docs/reference-language#ordering-sort),
  [`unique` semantics](/docs/reference-language#unique-semantics), and
  [Declared relations](/docs/reference-language#declared-relations).
- `trial`, three slots: `must`'s check, `filter`'s condition, and the
  odd members of `match`'s rest group. The argument is unified against a
  candidate in a sandbox with an error sink of its own, and the sandbox
  is discarded afterwards, so a failed trial is a false answer rather
  than an error in the document.
  [Selecting: `filter` and
  `match`](/docs/reference-language#selecting-filter-and-match),
  [Band B: `must`](/docs/reference-language#band-b-must), and
  [Sizing atoms fold last](/docs/reference-language#sizing-atoms-fold-last).
- `text`, four slots in three names: `re`'s pattern, `must`'s message,
  and `rep`'s pattern and substitution. The slot settles to a string
  like any other, and the settled string is then read as text in another
  notation rather than compared as a value.
  [`re` and the portable pattern
  subset](/docs/reference-language#re-and-the-portable-pattern-subset) and
  [`rep(s, pattern, sub)`](/docs/reference-language#reps-pattern-sub).
- `capture`, one slot, `path`'s. The slot is read for its spelling and
  its value is never asked for, which is the one argument position the
  evaluator does not drive.
  [First-class paths: `path(p?)`](/docs/reference-language#first-class-paths-pathp).

Five non-value slots answer a code of their own rather than
`invalid-arg`:

| name | slot | mode | code |
|---|---|---|---|
| `inverse` | `k` | `projector` | `inverse_name` |
| `path` | `p` | `capture` | `path_address` |
| `re` | `p` | `text` | `constraint_pattern` |
| `rep` | `p` | `text` | `rep_pattern` |
| `rep` | `sub` | `text` | `rep_sub` |

Every other non-value slot answers `invalid-arg`, `path`'s included
where the argument is neither address text nor a reference. One call
carries a code from each side of the gate: `test/spec/str.tsv:132-134`
pins `rep(1, "a", "b")` as `func_arg` from slot 1, which is value mode,
and `rep("a", 1, "b")` and `rep("a", "a", 1)` as `invalid-arg` from
slots 2 and 3, which are text mode.

## The call surface

One row per declared name, in alphabetical order. The signature cell is
the declaration line from `test/spec/signature.tsv`, with the type
alternation's `|` escaped for the cell. The arity is the interval the
engine derives from that line, written as a count, a range, or a floor
with `n` for a rest slot. The modes are those the name's slots use, and
`none` where the name has no slots. The result is the declaration's
result word.

The table is generated from the engine's registry and gated against it:
`ts/test/docs.test.ts` re-renders every signature printed on a
documentation page and fails on a difference of one space.

| signature | arity | modes | result |
|---|---|---|---|
| `abnf(g: string) : string` | `1` | `value` | `string` |
| `above(n: number\|string) : constraint` | `1` | `value` | `constraint` |
| `acyclic() : constraint` | `0` | none | `constraint` |
| `add(a: number, b: number) : number` | `2` | `value` | `number` |
| `below(n: number\|string) : constraint` | `1` | `value` | `constraint` |
| `close(m: any) : any` | `1` | `value` | `any` |
| `content(spec: string\|map) : map` | `1` | `value` | `map` |
| `copy(v: any) : any` | `1` | `value` | `any` |
| `copyfiles(spec: string\|map) : map` | `1` | `value` | `map` |
| `deprecate(v: any, r?: map) : any` | `1..2` | `value` | `any` |
| `div(a: number, b: number) : number` | `2` | `value` | `number` |
| `each(d: map\|list, template t: any) : list` | `2` | `value`, `template` | `list` |
| `emit(s: map\|list, template t: map\|list) : list` | `2` | `value`, `template` | `list` |
| `esc(s: string, variant?: string) : string` | `1..2` | `value` | `string` |
| `file(spec: string\|map, children?: list) : map` | `1..2` | `value` | `map` |
| `filter(d: map\|list, trial c: any) : map\|list` | `2` | `value`, `trial` | `map\|list` |
| `folder(spec: string\|map, children?: list) : map` | `1..2` | `value` | `map` |
| `fragment(spec: string\|map, children?: list) : map` | `1..2` | `value` | `map` |
| `greatest(d: map\|list) : number` | `1` | `value` | `number` |
| `hide(v: any) : any` | `1` | `value` | `any` |
| `inject(spec: string\|map, children?: list) : map` | `1..2` | `value` | `map` |
| `inverse(projector k: string) : constraint` | `1` | `projector` | `constraint` |
| `join(d: map\|list, sep?: string) : string` | `1..2` | `value` | `string` |
| `key(up?: integer\|biginteger) : string` | `0..1` | `value` | `string` |
| `least(d: map\|list) : number` | `1` | `value` | `number` |
| `length(n: number\|constraint) : constraint` | `1` | `value` | `constraint` |
| `line(spec: string\|map) : map` | `1` | `value` | `map` |
| `list() : list` | `0` | none | `list` |
| `listitems(spec: map, children?: list) : map` | `1..2` | `value` | `map` |
| `lower(s: string\|number, start?: integer\|biginteger, len?: integer\|biginteger) : string` | `1..3` | `value` | `string` |
| `map() : map` | `0` | none | `map` |
| `match(s: any, ...pr: (trial any, any), dflt?: any) : any` | `3..n` | `value`, `trial` | `any` |
| `max(n: number\|string) : constraint` | `1` | `value` | `constraint` |
| `maybe(v: any) : any` | `1` | `value` | `any` |
| `min(n: number\|string) : constraint` | `1` | `value` | `constraint` |
| `mod(a: number, b: number) : number` | `2` | `value` | `number` |
| `move(v: any) : any` | `1` | `value` | `any` |
| `mul(a: number, b: number) : number` | `2` | `value` | `number` |
| `must(trial c: any, text msg: string) : constraint` | `2` | `trial`, `text` | `constraint` |
| `neq(...vals: number\|string) : constraint` | `1..n` | `value` | `constraint` |
| `nom(name: string, style?: string\|list, acronyms?: list) : string\|map` | `1..3` | `value` | `string\|map` |
| `open(m: any) : any` | `1` | `value` | `any` |
| `pack(d: map\|list, template t: any) : map` | `2` | `value`, `template` | `map` |
| `parse(g: string, v?: string) : map\|list\|constraint` | `1..2` | `value` | `map\|list\|constraint` |
| `path(capture p?: path) : path` | `0..1` | `capture` | `path` |
| `pick(d: map\|list, projector k: string\|integer) : any` | `2` | `value`, `projector` | `any` |
| `pref(v: any) : any` | `1` | `value` | `any` |
| `project(spec?: string\|map, children?: list) : map` | `0..2` | `value` | `map` |
| `re(text p: string) : constraint` | `1` | `text` | `constraint` |
| `refer(template t?: any) : constraint` | `0..1` | `template` | `constraint` |
| `rel(template t?: any) : constraint` | `0..1` | `template` | `constraint` |
| `rem(a: number, b: number) : number` | `2` | `value` | `number` |
| `rep(s: string, text p: string, text sub: string) : string` | `3` | `value`, `text` | `string` |
| `slot(spec: string\|map, children?: list) : map` | `1..2` | `value` | `map` |
| `sort(d: map\|list, projector k?: string\|integer, dir?: string) : list` | `1..3` | `value`, `projector` | `list` |
| `split(s: string, sep: string\|constraint) : list` | `2` | `value` | `list` |
| `sub(a: number, b: number) : number` | `2` | `value` | `number` |
| `sum(d: map\|list) : number` | `1` | `value` | `number` |
| `super(t: any) : any` | `1` | `value` | `any` |
| `translate(s: string, from: string, to?: string) : string` | `2..3` | `value` | `string` |
| `type(t: any) : any` | `1` | `value` | `any` |
| `unique(projector k?: string) : constraint` | `0..1` | `projector` | `constraint` |
| `upper(s: string\|number, start?: integer\|biginteger, len?: integer\|biginteger) : string` | `1..3` | `value` | `string` |
| `usc(s: string, variant?: string) : string` | `1..2` | `value` | `string` |

A result word of `constraint` marks a residual whose meet depends on the
peer it lands beside. `any` is the result word where the declaration
cannot name the result: ten wrappers that answer whatever they were
given, plus `pick`, which answers a projection out of every child, and
`match`, which answers one of its pattern results.

## Slices

The same 64 names, cut by result word, by rest slot, and by optional
slot. Every count below is over the whole surface. The mode slice is
[Argument modes](#argument-modes).

The ten result words, and the names under each:

| result | count | names |
|---|---|---|
| `any` | 12 | `close`, `copy`, `deprecate`, `hide`, `match`, `maybe`, `move`, `open`, `pick`, `pref`, `super`, `type` |
| `constraint` | 13 | `above`, `acyclic`, `below`, `inverse`, `length`, `max`, `min`, `must`, `neq`, `re`, `refer`, `rel`, `unique` |
| `list` | 5 | `each`, `emit`, `list`, `sort`, `split` |
| `map` | 12 | `content`, `copyfiles`, `file`, `folder`, `fragment`, `inject`, `line`, `listitems`, `map`, `pack`, `project`, `slot` |
| `map\|list` | 1 | `filter` |
| `map\|list\|constraint` | 1 | `parse` |
| `number` | 9 | `add`, `div`, `greatest`, `least`, `mod`, `mul`, `rem`, `sub`, `sum` |
| `path` | 1 | `path` |
| `string` | 9 | `abnf`, `esc`, `join`, `key`, `lower`, `rep`, `translate`, `upper`, `usc` |
| `string\|map` | 1 | `nom` |

The algebra of the thirteen that answer `constraint`, including which
pairs have a meet and what each one is refused for, is
[The constraint algebra](/docs/reference-language#the-constraint-algebra).
Ten of the twelve that answer `map` are the component functions, written
as a tree that a generator walks: the tree's shape and each component's
props are the [generation reference](/docs/reference-generation), and what
the tree is turned into is
[Generation](/docs/reference-language#generation). The other two are
`map()`, which is the map kind, and `pack`. Three of the nine that
answer `string` are the text verbs, `esc`, `usc`, and `rep`, together
with `split`, which answers `list`:
[Text: `esc` `usc` `rep`
`split`](/docs/reference-language#text-esc-usc-rep-split). The one name
that answers `path` is `path` itself:
[First-class paths: `path(p?)`](/docs/reference-language#first-class-paths-pathp).

Two names take a rest slot, spelled `...` in the declaration. `neq`
takes one or more single values and has a floor of one. `match` takes a
repeating pair whose first member is the pattern and whose second is the
answer, and the pair's length counts toward the floor, which is why the
floor is three: a scrutinee, a pattern, and an answer. `match` is
specified at [Selecting: `filter` and
`match`](/docs/reference-language#selecting-filter-and-match), `neq` at
[The constraint algebra](/docs/reference-language#the-constraint-algebra).

Twenty-three names have at least one optional slot. `must` is the one
name that carries two non-value modes, its check `trial` and its message
`text`. `match` is the one name whose rest group pairs a `trial` member
with a `value` one.

## Related

- [Language reference: Functions](/docs/reference-language#functions). One
  entry per built-in, keyed by its signature: what the function means,
  and an example.
- [Composing calls](/docs/reference-language#composing-calls). Where a call
  may be written, and what it may stand in for.
- [Errors reference](/docs/reference-errors#the-codes). Every registered
  code, its class, the version it was registered at, and the shape of
  the report a refusal is carried in.
- [Generation reference](/docs/reference-generation). The component tree
  the ten component functions build, and what each verb writes when
  handed one.
- [Unification](/docs/unification). Meet, top, bottom, and residual, which
  the modes and result words above are stated in terms of.
- [API reference](/docs/reference-api). Calling the engine, and reading the
  refusals it answers with, from TypeScript or Go.

---

# Errors reference

_Every registered error code, by class, with what raises it, how a report is shaped, and which exit code a verb answers with._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-errors.md · Page: https://aontu.dev/docs/reference-errors

Every refusal the engine can make carries a **code**, and every code
carries a **class**. The code names the condition that was refused; the
class says what kind of thing went wrong, and so which repair applies.

This page is normative for the registry: every registered code, its
class, and the version it was first registered at. It is not normative
for the report a code arrives in, nor for the failures themselves.
[`aontu vet`](/docs/reference-api#aontu-vet) specifies the report: the
fields a finding carries, what a site names, and the `--format json`
object each verb answers. The language reference specifies each
construct where that construct belongs, and states what refuses it
there: see [Errors](/docs/reference-language#errors) for the message
families, [Exact or refused: lossy
literals](/docs/reference-language#exact-or-refused-lossy-literals) and
[The exactness budget](/docs/reference-language#the-exactness-budget) for
the numeric rules, and [Errors](/docs/reference-language#errors-1) under
[The constraint algebra](/docs/reference-language#the-constraint-algebra)
for a constraint violation.

[`aontu explain`](/docs/reference-api#aontu-explain) answers one code from
the same table a finding carries, and `aontu help codes` prints the
agent-facing card of the classes, which is shorter than the table below
and carries no counts.

## Contents

- [Classes](#classes)
- [Dynamic-prefix families](#dynamic-prefix-families)
- [The registry in a finding](#the-registry-in-a-finding)
- [Exit codes](#exit-codes)
- [The codes](#the-codes)
  - [Class `parse`](#class-parse)
  - [Class `conflict`](#class-conflict)
  - [Class `incomplete`](#class-incomplete)
  - [Class `reference`](#class-reference)
  - [Class `compat`](#class-compat)
  - [Class `budget`](#class-budget)
  - [Class `internal`](#class-internal)
- [Related](#related)

---

## Classes

There are seven classes, and the registry holds **172** codes across
them.

| class | codes | what went wrong |
|---|---|---|
| `parse` | 53 | the text is not a document |
| `conflict` | 55 | two values cannot both hold |
| `incomplete` | 11 | nothing contradicts, but the value is not concrete |
| `reference` | 27 | a name or path resolves to nothing |
| `compat` | 13 | a change breaks an earlier version |
| `budget` | 7 | evaluation hit a deterministic limit |
| `internal` | 6 | the engine reached a state it should not reach |

A class states which repair applies rather than where in the engine the
failure arose. [`aontu explain`](/docs/reference-api#aontu-explain) answers
one code with its class and the engine's own text for it.

Two `conflict` codes are reported after unification rather than by it:
`relation_cycle` and `relation_inverse_missing`, whose shape and timing
are under [`aontu relations`](/docs/reference-api#aontu-relations).

## Dynamic-prefix families

Five registry rows are prefixes rather than whole codes: `func:`,
`op:`, `op[`, `ref[`, and `var[`. The engine appends a name or a value,
so a reported code may be `func:upper` or `ref[$.x]`. The bare `func`,
`op`, `ref`, and `var` are separate rows with their own classes, and
are not the same codes as the families.

Class lookup takes the exact registry entry first, then the registered
prefix the code extends, and then `internal`, because an unregistered
code is an engine defect rather than a user error. Hint lookup has no
such fallback. It is exact, so a finding whose code extends a family
carries no hint text although the prefix row has some, and
[`aontu explain`](/docs/reference-api#aontu-explain) is the only place a
prefix's text is answered. `func:upper` is not a registry row, and
resolves through `func:`:

<!-- test: run -->
```sh
$ aontu explain func:upper
code:  func:upper
class: conflict

Function error:
```

Both the class and the text are the prefix's. A finding carrying that
code would take the class and carry no `hint` key.

## The registry in a finding

Three of a finding's fields are read from the registry, and each
carries a qualification the registry alone does not show.

**Class.** A finding's `class` is the registered class, on every
surface that reports one. A finding that mints its own code takes the
class that code is registered with; a finding that repeats a code the
engine raised takes the class from the same row, never one of its own.
`message` is the code's one-line headline throughout; the wording of
that line is each implementation's own, since the shared suite holds
codes and classes rather than prose.

**Hint text.** All 172 codes have hint text. `aontu explain --list`
prints them one per line, with each code's class beside it; a code
carrying no text would be marked `(no text)`, and none is. A finding
carries that text under `hint` when it repeats a code the engine
raised and the run asked for `--format json`:
[`vet`](/docs/reference-api#aontu-vet),
[`allow`](/docs/reference-api#aontu-allow),
[`model get`](/docs/reference-api#aontu-model-get),
[`model why`](/docs/reference-api#aontu-model-why),
[`view`](/docs/reference-api#aontu-view),
the library's `diff`
([TypeScript](/docs/reference-api#typescript-api), and no CLI verb of its
own), and the [MCP tools](/docs/reference-api#the-mcp-server). A finding
the report mints for itself carries its own message and no `hint`, and
so does the bare command that evaluates a document. No text format
prints hint text at all:
[`aontu explain`](/docs/reference-api#aontu-explain) is the verb that
answers one code's.

**Severity.** The field's domain is `error`, `warning`, and `info`, and
nothing in either implementation reports `info`. Five codes are always
reported at `warning`: `deprecated`, `pref_not_instance`,
`patch_not_editable`, `patch_ambiguous`, and `patch_span_mismatch`.
Under [`aontu breaking`](/docs/reference-api#aontu-breaking) with
`--allow-deprecated-removal`, any error finding at a path the prior
version marked with
[`deprecate`](/docs/reference-language#deprecatev-any-r-map--any) is
reported at `warning` instead, so a `compat` code otherwise reported at
`error` arrives at `warning` there.

Class `incomplete` is the only class a verdict rule reads. Under `vet`
a schema that does not stand up on its own is verdict `error` whatever
the finding's class; otherwise any error outside class `incomplete`
makes the verdict `invalid`, errors only of class `incomplete` make it
`incomplete` unless `--partial` was passed, and a `warning` never moves
it.

## Exit codes

A code's class does not determine the exit code. `scalar_value`, class
`conflict`, exits 1 where the contradiction is between schema and data,
and 4 where it is inside the schema. Which values a verb answers, and
what each one means for that verb, is in the API reference beside that
verb's option list. [`aontu vet`](/docs/reference-api#aontu-vet),
[`aontu subsume`](/docs/reference-api#aontu-subsume),
[`aontu breaking`](/docs/reference-api#aontu-breaking),
[`aontu view`](/docs/reference-api#aontu-view),
[`aontu model set`](/docs/reference-api#aontu-model-set), and
[`aontu fmt`](/docs/reference-api#aontu-fmt) each state their own table.

`aontu view` is the one verb whose refusals split across two exits.
Nine `view_*` codes are usage rather than the document's fault and exit
2: `view_kind_unknown`, `view_profile_unknown`, `view_rows_exceeded`,
`view_at_required`, `view_sets_required`, `view_group_required`,
`view_document_shape`, `view_style_profile`, and `view_style_unknown`.
A view kind that names no kind at all is caught while the arguments are
being read, so it exits 2 with no report at all.

## The codes

The registry is [`test/spec/errcodes.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv),
which both implementations run as part of the shared suite; the parity
it holds them to is stated under
[`aontu explain`](/docs/reference-api#aontu-explain).

The tables below are that file, one section per class, alphabetical
within each. A `since` column is the version line at which the code was
first registered, and `0.51.0` is the registry's own inception version,
so every code older than the registry carries it. Codes are
append-only: a registered code is never renamed or reused, so a row
stays registered after the condition it named stops arising. The
parenthetical link on a row is the section that specifies the refusal;
twenty rows have no such section and carry no link.

### Class `parse`

| code | since | raised when |
|---|---|---|
| `abnf_grammar` | 0.63.0 | The grammar could not be compiled; `abnf()` takes RFC 5234 ABNF, with `=` and `/` rather than `::=`. ([Grammars: `abnf()` and `parse()`](/docs/reference-language#grammars-abnf-and-parse)) |
| `alias_colon` | 0.58.0 | Reserved for the former rejection of alias keys; `%name: value` now creates a field and declares its alias. ([Aliases `%`](/docs/reference-language#aliases-)) |
| `alias_in_path` | 0.53.0 | An alias name used as a segment of a path. ([Aliases `%`](/docs/reference-language#aliases-)) |
| `alias_not_toplevel` | 0.53.0 | An alias declaration has no map root, or a key declaration sits below it. ([Aliases `%`](/docs/reference-language#aliases-)) |
| `bare_punct` | 0.58.0 | A bare string holding a character outside letters, digits, `-`, and `_`. ([Errors](/docs/reference-language#errors)) |
| `decimal_syntax` | 0.51.0 | A `0d` literal that is not a valid exact number. ([The four numeric leaves](/docs/reference-language#the-four-numeric-leaves)) |
| `each_data` | 0.53.0 | The first argument to `each()` is not a bag, so it has no children to make elements from. ([Generating children: `pack` and `each`](/docs/reference-language#generating-children-pack-and-each)) |
| `elided_value` | 0.53.0 | A key, element, or spread with no value. ([Errors](/docs/reference-language#errors)) |
| `emit_body` | 0.57.0 | A template body in an `emit()` table is not a list. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `emit_data` | 0.57.0 | The first argument to `emit()` is not a bag, so the selection has no children to visit. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `emit_table` | 0.57.0 | The second argument to `emit()` is not a rule table. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `emit_template` | 0.57.0 | A template in an `emit()` table is not a rule naming both `match` and `body`. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `esc_variant` | 0.57.0 | `esc()`, `usc()`, or a template's `esc:` key was given a variant naming no convention. ([`esc(s, variant?)` and `usc(s, variant?)`](/docs/reference-language#escs-variant-and-uscs-variant)) |
| `export_arg` | 0.69.0 | `export()` was given something other than a set of alias names. ([Publishing a name: `export`](/docs/reference-language#publishing-a-name-export)) |
| `filter_data` | 0.53.0 | The first argument to `filter()` is not a bag. ([Selecting: `filter` and `match`](/docs/reference-language#selecting-filter-and-match)) |
| `form_data` | 0.58.0 | The first argument to the list generator `form` is not a bag; `form` was renamed `each`, which answers `each_data`. |
| `func_arity` | 0.53.0 | A call whose argument count is not the built-in's arity. ([Errors](/docs/reference-language#errors)) |
| `include_denied` | 0.53.0 | An `@"..."` include refused by the active trust profile. ([Clause 1: hermeticity](/docs/trust#clause-1-hermeticity)) |
| `include_extension` | 0.54.0 | An `@"..."` include naming a file whose extension the include table does not know. ([Source loading `@"…"`](/docs/reference-language#source-loading-)) |
| `incomplete_expression` | 0.51.0 | An expression missing a term, grouping parentheses with nothing inside included. ([The `+` operator and grouping](/docs/reference-language#the--operator-and-grouping)) |
| `inverse_name` | 0.53.0 | The argument to `inverse()` is not a relation name. ([Declared relations](/docs/reference-language#declared-relations)) |
| `merge_conflict` | 0.53.0 | A version-control conflict marker left in the source. ([Errors](/docs/reference-language#errors)) |
| `module_integrity` | 0.53.0 | A module resolved locally does not carry the meaning its canon-hash pin recorded. ([Modules](/docs/reference-language#modules)) |
| `module_local` | 0.65.0 | A bare module reference whose last segment carries an extension the include table knows. ([Modules](/docs/reference-language#modules)) |
| `module_missing` | 0.53.0 | A module import naming a package that is not in the project's local stores. ([Modules](/docs/reference-language#modules)) |
| `module_moved` | 0.65.0 | A later version of the imported package declares a new path. ([Modules](/docs/reference-language#modules)) |
| `module_path` | 0.54.0 | A domain-shaped module import whose path cannot be a directory on every platform the toolchain runs on. ([Modules](/docs/reference-language#modules)) |
| `negative` | 0.51.0 | Unary minus applied to a non-numeric operand. ([The four numeric leaves](/docs/reference-language#the-four-numeric-leaves)) |
| `not_number` | 0.51.0 | A numeric literal that reads as a non-finite value. ([The four numeric leaves](/docs/reference-language#the-four-numeric-leaves)) |
| `pack_data` | 0.53.0 | The first argument to `pack()` is not a bag. ([Generating children: `pack` and `each`](/docs/reference-language#generating-children-pack-and-each)) |
| `pack_key` | 0.53.0 | A list packed by `pack()` holds an element that is not a string. ([Generating children: `pack` and `each`](/docs/reference-language#generating-children-pack-and-each)) |
| `parse` | 0.51.0 | The outer wrapper for a source that could not be turned into a document; the inner error carries the code that explains it. |
| `parse_arg` | 0.63.0 | `parse()` was given something other than a grammar string and a text string. ([Grammars: `abnf()` and `parse()`](/docs/reference-language#grammars-abnf-and-parse)) |
| `parse_bad_src` | 0.51.0 | The source handed in for parsing is not a non-empty string. |
| `parse_unknown` | 0.51.0 | A parsed node of a kind the value builder has no case for. |
| `patch_assignment` | 0.53.0 | A `set` argument that is not `<path>=<value>`. ([`aontu model set`](/docs/reference-api#aontu-model-set)) |
| `path_address` | 0.54.0 | `path()` was given text that is not a tree address. ([First-class paths: `path(p?)`](/docs/reference-language#first-class-paths-pathp)) |
| `pref_implicit_bag` | 0.53.0 | A preference mark written on a bare key rather than on a value. ([Preference / default `*`](/docs/reference-language#preference--default-)) |
| `refer_address` | 0.53.0 | `refer()` was given something that is not a path value. ([Addresses](/docs/reference-language#addresses)) |
| `rel_address` | 0.53.0 | A `rel()` field holds something other than path values. ([Declared relations](/docs/reference-language#declared-relations)) |
| `render_path` | 0.58.0 | A unit path that is not relative, below the output directory, and distinct from every other unit's. ([What `aontu render` writes](/docs/reference-generation#what-aontu-render-writes)) |
| `render_profile` | 0.58.0 | A declaration needing a lowering, under a profile whose language has none. ([What `aontu render` writes](/docs/reference-generation#what-aontu-render-writes)) |
| `rep_pattern` | 0.57.0 | The pattern given to `rep()` is outside the portable subset `re()` takes. ([`rep(s, pattern, sub)`](/docs/reference-language#reps-pattern-sub)) |
| `rep_sub` | 0.57.0 | The substitution given to `rep()` names a group the pattern does not have. ([`rep(s, pattern, sub)`](/docs/reference-language#reps-pattern-sub)) |
| `replace_overlap` | 0.58.0 | Two keys of a template's `replace` map overlap, one inside the other. ([Replacing text in a body: `replace` and `esc`](/docs/reference-language#replacing-text-in-a-body-replace-and-esc)) |
| `replace_unused` | 0.58.0 | A key of a template's `replace` map appears in none of the body's literal lines. ([Replacing text in a body: `replace` and `esc`](/docs/reference-language#replacing-text-in-a-body-replace-and-esc)) |
| `reserved_key` | 0.69.0 | A source key beginning with the engine's reserved `\u0000aontu_` prefix, where the parser keeps a document's marks. ([Errors](/docs/reference-language#errors)) |
| `sort_dir` | 0.63.0 | A sort direction other than `asc` or `desc`. ([Ordering: `sort`](/docs/reference-language#ordering-sort)) |
| `split_sep` | 0.57.0 | The separator given to `split()` is neither a string nor a pattern. ([Text: `esc` `usc` `rep` `split`](/docs/reference-language#text-esc-usc-rep-split)) |
| `syntax` | 0.51.0 | The parser refused the source text; the message is the parser's own, with the operator-character hint appended. ([Lexical structure](/docs/reference-language#lexical-structure)) |
| `unify_no_src` | 0.51.0 | No source was handed in for unification. |
| `usc_malformed` | 0.57.0 | `usc()` was given text the named convention could not have produced. ([`esc(s, variant?)` and `usc(s, variant?)`](/docs/reference-language#escs-variant-and-uscs-variant)) |
| `view_line_break` | 0.54.0 | A label the figure would draw holds a line terminator. ([`aontu view`](/docs/reference-api#aontu-view)) |

### Class `conflict`

| code | since | raised when |
|---|---|---|
| `aggregate_data` | 0.53.0 | An aggregate was given something other than a bag to fold. ([Aggregating: `sum` `least` `greatest`](/docs/reference-language#aggregating-sum-least-greatest)) |
| `aggregate_empty` | 0.53.0 | `least` or `greatest` given an empty bag. ([Aggregating: `sum` `least` `greatest`](/docs/reference-language#aggregating-sum-least-greatest)) |
| `arg` | 0.51.0 | A required argument is missing. |
| `close` | 0.51.0 | The structure could not be closed. ([Closed values: `close` / `open`](/docs/reference-language#closed-values-close--open)) |
| `closed` | 0.51.0 | A key or element added to a closed map or list. ([Errors](/docs/reference-language#errors)) |
| `constraint` | 0.52.0 | The value does not satisfy the normalised residual the constraint reduced to. ([The constraint algebra](/docs/reference-language#the-constraint-algebra)) |
| `constraint_pattern` | 0.53.0 | An `re()` pattern outside the supported subset. ([The constraint algebra](/docs/reference-language#the-constraint-algebra)) |
| `decimal_budget` | 0.51.0 | An exact decimal past 4096 coefficient digits or an absolute scale of 4096. ([The exactness budget](/docs/reference-language#the-exactness-budget)) |
| `divide_by_zero` | 0.53.0 | `div`, `mod`, or `rem` given a zero divisor. ([Arithmetic: `add` `sub` `mul` `div` `mod` `rem`](/docs/reference-language#arithmetic-add-sub-mul-div-mod-rem)) |
| `emit_none` | 0.57.0 | No template matched a node, and the table has no catch-all. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `emit_ref` | 0.57.0 | A template body names a field the node it matched does not carry. ([Transforming: `emit`](/docs/reference-language#transforming-emit)) |
| `empty` | 0.54.0 | A disjunction with no admitted alternative. ([Preference / default `*`](/docs/reference-language#preference--default-)) |
| `empty-dist` | 0.54.0 | Every alternative of a distributed disjunction is refused. ([Disjunction `|`](/docs/reference-language#disjunction-)) |
| `exact_float_mix` | 0.51.0 | An exact number combined with a binary float. ([The four numeric leaves](/docs/reference-language#the-four-numeric-leaves)) |
| `float_overflow` | 0.53.0 | A result that is not a finite binary64 number. ([Arithmetic: `add` `sub` `mul` `div` `mod` `rem`](/docs/reference-language#arithmetic-add-sub-mul-div-mod-rem)) |
| `func` | 0.51.0 | A function operation failed; the named function carries the detail. ([How a call is checked](/docs/reference-functions#how-a-call-is-checked)) |
| `func:` | 0.51.0 | Dynamic-prefix family: a named function's own failure, the name appended (`func:upper`). |
| `func_arg` | 0.55.0 | An argument does not fit the function's signature. ([How a call is checked](/docs/reference-functions#how-a-call-is-checked)) |
| `inexact_divide` | 0.53.0 | An exact decimal operand given to `div`, `mod`, or `rem`; exact decimal division is not closed, so it is refused rather than rounded, while a `0d` biginteger divides. ([Arithmetic: `add` `sub` `mul` `div` `mod` `rem`](/docs/reference-language#arithmetic-add-sub-mul-div-mod-rem)) |
| `inexact_integer_sum` | 0.51.0 | An `integer` result outside the integral, int64, exactly representable range. ([Arithmetic: `add` `sub` `mul` `div` `mod` `rem`](/docs/reference-language#arithmetic-add-sub-mul-div-mod-rem)) |
| `invalid-arg` | 0.51.0 | An argument does not match the expected type or format. |
| `join_member` | 0.54.0 | A member of the bag `join()` folds is not text and never will be. ([Folding to a string: `join`](/docs/reference-language#folding-to-a-string-join)) |
| `key_level` | 0.51.0 | The argument to `key()` is not a level. ([How a call is checked](/docs/reference-functions#how-a-call-is-checked)) |
| `list` | 0.51.0 | A list was expected and the value is of another kind. ([Container kinds: `map()` and `list()`](/docs/reference-language#container-kinds-map-and-list)) |
| `list_length` | 0.53.0 | A literal list alternative admits only a list of its own length; a spread makes it take any length. ([Lists](/docs/reference-language#lists)) |
| `literal_nil` | 0.51.0 | A literal nil met another value. ([The value lattice](/docs/reference-language#the-value-lattice)) |
| `lossy_integer_literal` | 0.51.0 | An integer literal not exactly representable in binary64; the hint names the `0d` spelling. ([Exact or refused: lossy literals](/docs/reference-language#exact-or-refused-lossy-literals)) |
| `make` | 0.51.0 | A value could not be constructed. |
| `map` | 0.51.0 | A map was expected and the value is of another kind. ([Container kinds: `map()` and `list()`](/docs/reference-language#container-kinds-map-and-list)) |
| `match_none` | 0.53.0 | No pattern matched, and `match` has no default. ([Selecting: `filter` and `match`](/docs/reference-language#selecting-filter-and-match)) |
| `must` | 0.53.0 | The value fails an evaluate-only check written with `must()`; the author's message rides on the finding. ([Band B: `must`](/docs/reference-language#band-b-must)) |
| `nil_gen` | 0.51.0 | A nil survived unification, and nil is not a literal value to generate. ([Generation](/docs/reference-language#generation)) |
| `no_first_arg` | 0.51.0 | The function's first argument is missing. |
| `no_scalar_unify` | 0.51.0 | Two scalar values of incompatible types. ([Unification rules](/docs/reference-language#unification-rules)) |
| `not-scalar-type` | 0.51.0 | A scalar type was expected and the value is not one. ([Unification rules](/docs/reference-language#unification-rules)) |
| `op` | 0.51.0 | An operator operation failed; the named operator carries the detail. |
| `op:` | 0.51.0 | Dynamic-prefix family: a named operator's own failure, the name appended (`op:add`). |
| `op[` | 0.51.0 | Dynamic-prefix family: an operator failure carrying the offending value (`op[1]`). |
| `operate` | 0.51.0 | The operation could not be performed over the values given. |
| `parse_failed` | 0.63.0 | The text does not parse under the grammar given, so the field is refused. ([Grammars: `abnf()` and `parse()`](/docs/reference-language#grammars-abnf-and-parse)) |
| `pick_key` | 0.53.0 | A child of the bag has no key for `pick` to project. ([Missing fields and invalid arguments](/docs/reference-language#missing-fields-and-invalid-arguments)) |
| `place_pair` | 0.53.0 | Two placeholders met, and neither has a value to fill the other. ([The placeholder `_`](/docs/reference-language#the-placeholder-_)) |
| `pref_rank_clash` | 0.54.0 | Two defaults of the same rank disagree. ([Preference / default `*`](/docs/reference-language#preference--default-)) |
| `relation_cycle` | 0.53.0 | A relation declared `acyclic()`, and its edges form a cycle. ([Declared relations](/docs/reference-language#declared-relations)) |
| `relation_inverse_missing` | 0.53.0 | A relation declared `inverse(name)`, and an edge has no mirroring edge. ([Declared relations](/docs/reference-language#declared-relations)) |
| `render_lang` | 0.58.0 | A text escape carrying verbatim syntax of a language other than the unit's. ([What `aontu render` writes](/docs/reference-generation#what-aontu-render-writes)) |
| `render_strict` | 0.58.0 | An opaque escape, which the renderer cannot check, under strict rendering. ([What `aontu render` writes](/docs/reference-generation#what-aontu-render-writes)) |
| `replace_value` | 0.58.0 | A replacement value is not text by the time the dispatch fires. ([Replacing text in a body: `replace` and `esc`](/docs/reference-language#replacing-text-in-a-body-replace-and-esc)) |
| `resolve` | 0.51.0 | The value could not be resolved. |
| `scalar-type` | 0.51.0 | Two scalar kinds where neither contains the other. ([Unification rules](/docs/reference-language#unification-rules)) |
| `scalar_kind` | 0.51.0 | Two literal scalars of different kinds. ([Unification rules](/docs/reference-language#unification-rules)) |
| `scalar_value` | 0.51.0 | Two literal scalars of the same kind that are not equal. ([Unification rules](/docs/reference-language#unification-rules)) |
| `sort_domain` | 0.63.0 | A bag with no order to be put in. ([Ordering: `sort`](/docs/reference-language#ordering-sort)) |
| `sort_key` | 0.63.0 | A child of the bag has no key to order by. ([Ordering: `sort`](/docs/reference-language#ordering-sort)) |
| `unite` | 0.51.0 | Two values could not be united. |

### Class `incomplete`

| code | since | raised when |
|---|---|---|
| `conjunct` | 0.51.0 | A conjunction has a term that could not be resolved. ([Conjunction `&`](/docs/reference-language#conjunction-)) |
| `disjunct_no_gen` | 0.53.0 | More than one alternative is still admitted, so there is no single value to generate. ([Disjunction `|`](/docs/reference-language#disjunction-)) |
| `listval_no_gen` | 0.51.0 | A list element survived unification as something other than a literal value. ([Generation](/docs/reference-language#generation)) |
| `listval_required` | 0.51.0 | A required list element has no value. ([Optional keys `?`](/docs/reference-language#optional-keys-)) |
| `listval_spread_required` | 0.51.0 | A key a spread requires has no value, in a list. ([Spreads `&:`](/docs/reference-language#spreads-)) |
| `mapval_no_gen` | 0.51.0 | A map value survived unification as something other than a literal value. ([Optional input: `maybe`](/docs/reference-language#optional-input-maybe)) |
| `mapval_required` | 0.51.0 | A required map value has no value. ([Optional keys `?`](/docs/reference-language#optional-keys-)) |
| `mapval_spread_required` | 0.51.0 | A key a spread requires has no value, in a map. ([Spreads `&:`](/docs/reference-language#spreads-)) |
| `no_gen` | 0.51.0 | A value survived unification as something other than a literal value. ([Generation](/docs/reference-language#generation)) |
| `recursion_unexpanded` | 0.53.0 | A schema refers to itself, and no data reached the position to expand it against. ([Recursive references (fixpoints)](/docs/reference-language#recursive-references-fixpoints)) |
| `required_listelem` | 0.51.0 | A non-optional list element has no value. ([Optional keys `?`](/docs/reference-language#optional-keys-)) |

### Class `reference`

| code | since | raised when |
|---|---|---|
| `import_not_exported` | 0.69.0 | A destructure asked for a name the other file does not publish. ([Taking a name: the destructure](/docs/reference-language#taking-a-name-the-destructure)) |
| `invalid_var_kind` | 0.51.0 | A variable's kind is not the kind the use expects. ([Variables `$name`](/docs/reference-language#variables-name)) |
| `multisource_not_found` | 0.51.0 | An `aontu:` name that is not one of the language-supplied models; the message names the set. ([The `aontu:` models](/docs/reference-language#the-aontu-models)) |
| `no_path` | 0.51.0 | A path reference resolves to nothing. ([Optional input: `maybe`](/docs/reference-language#optional-input-maybe)) |
| `patch_ambiguous` | 0.53.0 | Two or more statements pin the path, so an in-place edit has no single place to write. ([`aontu model set`](/docs/reference-api#aontu-model-set)) |
| `patch_not_editable` | 0.53.0 | An in-place edit found no single literal to rewrite, so the assignment was appended. ([`aontu model set`](/docs/reference-api#aontu-model-set)) |
| `path_cycle` | 0.51.0 | A path reference closes a cycle. ([Recursive references (fixpoints)](/docs/reference-language#recursive-references-fixpoints)) |
| `ref` | 0.51.0 | A reference could not be resolved to a value. ([References and paths](/docs/reference-language#references-and-paths)) |
| `ref[` | 0.51.0 | Dynamic-prefix family: a reference failure carrying the address (`ref[$.x]`). ([References and paths](/docs/reference-language#references-and-paths)) |
| `refer_unresolved` | 0.53.0 | A `refer()` address names no node in this evaluation. ([Existence is decided, not deferred](/docs/reference-language#existence-is-decided-not-deferred)) |
| `rel_unresolved` | 0.53.0 | A `rel()` address names no node in this evaluation. ([Declared relations](/docs/reference-language#declared-relations)) |
| `render_unit` | 0.58.0 | The unit asked for is not in the instance. ([What `aontu render` writes](/docs/reference-generation#what-aontu-render-writes)) |
| `unknown_function` | 0.51.0 | A function name that resolves to no built-in. ([How a call is checked](/docs/reference-functions#how-a-call-is-checked)) |
| `unknown_var` | 0.51.0 | A variable that has not been defined. ([Variables `$name`](/docs/reference-language#variables-name)) |
| `var` | 0.51.0 | An unresolved variable reached generation. ([Variables `$name`](/docs/reference-language#variables-name)) |
| `var[` | 0.51.0 | Dynamic-prefix family: a variable failure carrying the name (`var[$x]`). ([Variables `$name`](/docs/reference-language#variables-name)) |
| `view_at_required` | 0.54.0 | The meet ladder draws the contributions at one path, and none was named. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_document_shape` | 0.54.0 | A figure in a view document does not name both its `kind` and its `out` file. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_group_required` | 0.54.0 | The layer diagram bands nodes by a field, and none was named. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_kind_unknown` | 0.54.0 | The figure kind is not one the verb draws; the note lists the kinds. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_profile_unknown` | 0.54.0 | The figure kind does not render into the profile asked for. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_relation_ambiguous` | 0.54.0 | The document has edges under several relations, and the figure draws one. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_relation_unknown` | 0.54.0 | The relation named to the view has no edges in this document. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_sets_required` | 0.54.0 | The set panel needs both the sets map and the member field, and one was missing. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_sets_shape` | 0.54.0 | The sets map or the universe does not have the shape the set panel reads. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_style_profile` | 0.55.0 | The style asked for is not the one that profile carries. ([`aontu view`](/docs/reference-api#aontu-view)) |
| `view_style_unknown` | 0.55.0 | A style other than `none`, `ansi`, `css`, or the command line's `auto`. ([`aontu view`](/docs/reference-api#aontu-view)) |

### Class `compat`

| code | since | raised when |
|---|---|---|
| `compat_default_changed` | 0.53.0 | The effective default changed, so a document generable before materialises differently or becomes incomplete. ([Profiles](/docs/reference-language#profiles)) |
| `compat_marks_changed` | 0.53.0 | The marks on the two values differ. ([Maps, lists, closedness, optionality, spreads](/docs/reference-language#maps-lists-closedness-optionality-spreads)) |
| `compat_narrowed` | 0.53.0 | The specific value admits something the general does not; the message names which comparison failed. ([Rules, by value former](/docs/reference-language#rules-by-value-former)) |
| `compat_outcome_changed` | 0.65.0 | A position both versions resolve with nothing supplied, to different values. ([`aontu publish`](/docs/reference-api#aontu-publish)) |
| `compat_required_added` | 0.53.0 | The general value requires a key the specific omits or makes optional. ([Maps, lists, closedness, optionality, spreads](/docs/reference-language#maps-lists-closedness-optionality-spreads)) |
| `compat_undetermined` | 0.65.0 | A position the prior version resolved with nothing supplied, and nothing resolves now. ([`aontu publish`](/docs/reference-api#aontu-publish)) |
| `deprecated` | 0.53.0 | A use of a value carrying a `deprecate` mark. ([`deprecate(v: any, r?: map) : any`](/docs/reference-language#deprecatev-any-r-map--any)) |
| `pref_not_instance` | 0.53.0 | A disjunction's effective default is not an instance of any remaining alternative. ([Default validity](/docs/reference-language#default-validity)) |
| `sub_default_indeterminate` | 0.53.0 | Equal-rank preferences disagree, so the effective default is not a single value. ([Profiles](/docs/reference-language#profiles)) |
| `sub_disjunct_distribution` | 0.53.0 | A specific alternative is not admitted member-wise, and no concrete counterexample settles the distribution case. ([Rules, by value former](/docs/reference-language#rules-by-value-former)) |
| `sub_evaluate_only` | 0.53.0 | An evaluate-only check makes the admitted set opaque. ([Rules, by value former](/docs/reference-language#rules-by-value-former)) |
| `sub_path_dependent_spread` | 0.53.0 | A path-dependent spread template cannot be compared structurally. ([Maps, lists, closedness, optionality, spreads](/docs/reference-language#maps-lists-closedness-optionality-spreads)) |
| `sub_unresolved` | 0.53.0 | Unresolved residue, or no subsumption rule covers the pair of value formers. ([Rules, by value former](/docs/reference-language#rules-by-value-former)) |

### Class `budget`

| code | since | raised when |
|---|---|---|
| `alias_budget` | 0.69.0 | Alias expansion counted past the size budget before evaluation; expansion terminates whatever the budget, so this is about size. ([Aliases `%`](/docs/reference-language#aliases-)) |
| `budget_passes` | 0.52.0 | The fixpoint pass budget was spent before the model converged; the hint names what was still refining. ([Cross-field bounds and residuation](/docs/reference-language#cross-field-bounds-and-residuation)) |
| `max_depth` | 0.51.0 | Input nested deeper than the engine processes. ([Clause 2: termination](/docs/trust#clause-2-termination)) |
| `module_depth` | 0.53.0 | Module verification nested past its depth, usually a vendor tree leading back to itself. ([Modules](/docs/reference-language#modules)) |
| `recursion_budget` | 0.53.0 | A recursive schema expanded past the depth budget without meeting concrete data. ([Recursive references (fixpoints)](/docs/reference-language#recursive-references-fixpoints)) |
| `unify_cycle` | 0.51.0 | A circular reference reached during unification. ([Clause 2: termination](/docs/trust#clause-2-termination)) |
| `view_rows_exceeded` | 0.54.0 | The figure has more rows than the row cap allows; the figure is refused rather than trimmed. ([`aontu view`](/docs/reference-api#aontu-view)) |

### Class `internal`

| code | since | raised when |
|---|---|---|
| `format_check` | 0.56.0 | The formatted text is not the same document, so nothing was written. ([`aontu fmt`](/docs/reference-api#aontu-fmt)) |
| `internal` | 0.51.0 | An unexpected state during unification. |
| `unify_failed` | 0.67.0 | A document does not evaluate, and the failure carries no code of its own. |
| `patch_span_mismatch` | 0.53.0 | The overlay text does not hold the recorded source at the recorded span, so the span cannot be verified before writing. ([`aontu model set`](/docs/reference-api#aontu-model-set)) |
| `unify_no_res` | 0.51.0 | Unification produced no result. |
| `unknown_op` | 0.51.0 | An operator expression the evaluator has no rule for. |

## Related

- [`aontu vet`](/docs/reference-api#aontu-vet) for the report these
  findings arrive in, the fields they carry, and its own exit table.
- [`aontu explain`](/docs/reference-api#aontu-explain) for the verb that
  answers one code, and for what `--list` prints.
- [Errors](/docs/reference-language#errors) in the language reference for
  the message families and the rules that refuse a document.
- [Read a conflict error](/how-to/read-a-conflict-error) for reading
  a two-site conflict message operand by operand.
- [Collect errors instead of throwing](/how-to/collect-errors) for
  gathering every finding in one pass from the embedded API.
- [`test/spec/errcodes.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv) for the
  registry itself, which both implementations run.

---

# Packages reference

_The package system's artefacts: the files it keeps, every field pkg.aon declares, the name rules, the caps, the archive allowlist, and every refusal code._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-packages.md · Page: https://aontu.dev/docs/reference-packages

A **module** is a document another document imports. A **package** is a
module that was published: a tree of aontu source with a path, a
version, a signed manifest, and an archive whose bytes one digest
names. The language reference states how an import routes to one; this
page states what the package system keeps on disk while it does so.

This page is normative for the artefacts: the files the package system
reads and writes, every field `pkg.aon` declares, the name and version
rules, the caps every consumer applies, what an archive may hold, and
every code a package operation refuses with. It states no verb's
options and no verb's exit codes.

The verbs are the API reference: [`aontu
sync`](/docs/reference-api#aontu-sync) for the one that makes a project
correct, [`aontu add`, `aontu get`, `aontu
remove`](/docs/reference-api#aontu-add-aontu-get-aontu-remove) for
changing what a project depends on, [`aontu
publish`](/docs/reference-api#aontu-publish) for sending one out, and
[`aontu pkg`](/docs/reference-api#aontu-pkg) for the remaining steps.
[Modules](/docs/reference-language#modules) in the language reference
states how a reference routes, and
[`tutorial-package.md`](/docs/tutorial-package) walks the whole path once
with a real package.

## Contents

- [The files](#the-files)
- [What pkg.aon declares](#what-pkgaon-declares)
- [Names and versions](#names-and-versions)
- [Where a module resolves from](#where-a-module-resolves-from)
- [The caps](#the-caps)
- [What an archive may hold](#what-an-archive-may-hold)
- [Refusals](#refusals)
- [Related](#related)

---

## The files

Everything the package system keeps in a project is a file in it, and
every one of those is ordinary text: nothing is hidden in a database,
and nothing outside this table is consulted. The two stores outside a
project are not text alone. The user cache and a repository directory
hold the archives themselves, which are zips, beside the manifest and
proof that travel with them.

| path | written by | read by | commit it |
|---|---|---|---|
| `pkg.aon` | the author, and `add`, `get`, `remove` by the smallest text change | every package verb, and module resolution | yes |
| `aontu_meta/pkg-lock.aon` | `sync`, `pkg tidy`, `pkg refreeze` | `sync --frozen`, `pkg verify`, `pkg tree`, `why`, and resolution for a pinned import | yes |
| `aontu_meta/vendor/<package-path>/` | `sync`, `pkg vendor` | resolution, first of the stores | yes |
| `aontu_meta/vendor/<package-path>/aontu_meta/` | `sync`, holding the manifest and proof as served | `pkg verify` | yes |
| the user cache | `sync`, `add`, `get` | resolution, when the expected canon-hash is known | it is outside the project |
| a repository directory | `publish --to <dir>` | `pkg serve`, and any consumer whose `repo.base` names it | it is not part of a project |
| the signing key | `pkg keygen`, once | `publish --key` | never |

A project that has been synced evaluates from its own directory with no
cache and no network, because the vendor tree is a real copy rather
than a link. The lockfile and the vendor tree are written together and
belong in one commit: a lockfile without the tree it pins names bytes
the project does not have.

## What pkg.aon declares

`pkg.aon` is an ordinary aontu document, evaluated as any other. The
tools read the fields below and nothing else, so a field of the
author's own is carried rather than refused.

| field | value | default | read by |
|---|---|---|---|
| `pkg.path` | this package's path | none | resolution, `publish`, `why` |
| `pkg.version` | this package's own version | none | `publish`, `pkg manifest` |
| `pkg.main` | the entry document, a path inside the tree | `main.aon` | resolution, `publish` |
| `dep."<path>".v` | the minimum version of a dependency | none | `sync`, and every verb that resolves |
| `dep."alias:<name>".pkg` | the package an alias names | none | resolution of an `alias:` import |
| `dep."alias:<name>".v` | the minimum version taken under that alias | none | `sync` |
| `publish` | `public`, to allow publication at all | `private` | `publish` |
| `moved` | the package path that replaces this one | absent | resolution, `publish` |
| `retract` | versions withdrawn, as a list of strings | empty | `publish --to`, which derives the advisory |
| `repo.base` | repositories to read from, in order | none | every verb that fetches |
| `repo.write` | the write path a publish sends to | none | `publish` |
| `repo.private` | patterns never sent to a public base | none | every verb that fetches |
| `repo.private_base` | repositories for a name on the private list | none | every verb that fetches |
| `repo.trust."<pattern>".signer` | `forge`, or `ed25519:` and a public key | the entry for `*`, which names the forge signer | acquisition |
| `repo.trust."<pattern>".inclusion` | `none`, to accept a key proof that carries no log inclusion | inclusion is required | acquisition |

A consuming project declares what it depends on, and where those
packages are read from:

```aon
pkg: { path:"corp.example/checkout" main:"main.aon" }

dep: "corp.example/schemas/service": v: "1.4.2"
dep: "alias:legacy": { pkg:"corp.example/schemas/service" v:"1.2.0" }

repo: base: ["https://pkg.aontu.dev"]
repo: private: ["corp.example/*"]
repo: private_base: ["https://pkg.corp.example"]
repo: trust: "corp.example/*": { signer:"ed25519:q520" inclusion:none }
```

A package that is published declares its own version and says so out
loud, and the last version of a path that has been superseded points at
its replacement:

```aon
pkg: { path:"corp.example/schemas/service" version:"1.4.2" main:"service.aon" }
publish: public
retract: ["1.4.1"]
moved: "corp.example/schemas/service2"
```

Both fields are shown together above for the field's sake. A package
declares `moved` when its path is finished, and a path that is finished
gains no further versions.

## Names and versions

A **package path** is a domain-shaped path: the first element contains a
dot, and no element is a major version, because compatibility is
computed when a package is published rather than declared in its name.
A path that routes to a package becomes a directory on every platform
the toolchain runs on, so the shape is bounded before anything is built
from it.

- At most **512** characters, and at most **32** elements.
- No element is empty, and none begins or ends with `.`.
- The part of an element before its first `.` is not a reserved device
  name. The set, matched without regard to case: `con`, `prn`, `aux`,
  `nul`, `com1` to `com9`, and `lpt1` to `lpt9`.
- An uppercase letter is written as `!` and its lowercase form in every
  store, so two paths differing only in case stay two identities on a
  filesystem that would fold them into one.

A **version** is three parts separated by `.`, each either `0` or a
digit string with no leading zero. That is what a publish mints and
what a manifest carries. The comparator reads a part a version omits as
`0`, so `1.2` and `1.2.0` are one version to it, and a lockfile
rewritten from either says the same thing.

An **alias key** is `alias:` followed by the name the imports use. A
**local** import carries `./`, `../` or `/`; a bare relative path whose
last segment has an extension the include table knows is refused with
`module_local` rather than read as a package.

## Where a module resolves from

Resolution reads local stores only, in this order, and stops at the
first that holds the module:

1. `aontu_meta/vendor/` of the project whose directory holds `pkg.aon`.
2. `aontu_meta/vendor/` of each project enclosing that one, outward, so
   a vendored module resolves its own dependencies from the tree that
   vendored it.
3. The user cache, which is keyed by canon-hash and so is consulted
   only where the expected hash is already known.

The cache directory is the first of these that applies:

| condition | directory |
|---|---|
| `XDG_CACHE_HOME` is set | `$XDG_CACHE_HOME/aontu/pkg` |
| `HOME` is set | `$HOME/.cache/aontu/pkg` |
| Windows, and `LOCALAPPDATA` is set | `%LOCALAPPDATA%\aontu\pkg` |
| none of those | there is no cache, and the vendor tree is the only store |

## The caps

Every cap is a fixed number, the same in both implementations, and each
is refused by name so a report says which one was reached.

| cap | value | refused as |
|---|---|---|
| a module path, in characters | 512 | `module_path` |
| elements in a module path | 32 | `module_path` |
| dependency nesting, in levels | 16 | `module_depth` |
| packages in one closure | 1024 | `closure_too_large` |
| an archive, compressed | 16777216 bytes | `archive_too_large` |
| an archive, extracted | 67108864 bytes | `archive_bomb` |
| files in an archive | 4096 | `archive_too_many_files` |
| one file in an archive | 8388608 bytes | `archive_bomb` |

The four archive caps are applied twice. A consumer applies them while
acquiring, before a byte of the archive is parsed. A publish applies
the same four before anything is minted, so a package that every
consumer would refuse never leaves the machine; there the reasons are
reported as what stopped the mint rather than as a refusal code.

## What an archive may hold

The archive of a package holds source and the text that travels with
it. The list is enumerated and refused by default, so a new extension
is admitted by a change to the engine and never by a package.

| group | admitted |
|---|---|
| aontu source | `aon`, `aontu` |
| data the include table reads | `json`, `jsonld`, `jsonc`, `json5`, `jsonic`, `jsc`, `toml`, `yaml`, `yml`, `ini` |
| text | `md`, `txt` |
| by name, with no extension | `LICENSE`, `NOTICE` |

No path element may begin with `.`, and nothing under `aontu_meta/` is
sent: a lockfile and a vendor tree are the consuming project's, and a
package that carried them would ship one project's resolution to
another. Anything else in the tree is refused with
`archive_entry_forbidden`, which names the file.

## Refusals

A package operation refuses with a **code**, a message, and the package
it was about. There are thirty codes.

Six of them are also engine codes, raised while a document is
evaluated, and those six are in the registry with a class and a
registered-at version: see [the
codes](/docs/reference-errors#the-codes) for `module_path`,
`module_local`, `module_missing`, `module_moved`, `module_integrity`
and `module_depth`. The other twenty-four name a refusal by a verb.
They are not findings, carry no class, and arrive under `refusal` in a
verb's `--format json` report.

The step each code is raised at: **resolution** reads the local stores
while a document is evaluated; **configuration** reads `repo` and the
signing key; **acquisition** reads a repository, in the order version
list, manifest, proof, archive; **publication** mints and sends.

| code | raised at | what it means |
|---|---|---|
| `archive_bomb` | acquisition | a file, or the running total, is over the size cap once extracted |
| `archive_digest_mismatch` | acquisition | the archive's digest is not the one the manifest declares |
| `archive_entry_forbidden` | acquisition | the archive carries a file the allowlist does not admit |
| `archive_not_canonical` | acquisition | the zip is not in the canonical form one tree has one digest under |
| `archive_path_invalid` | acquisition | a path in the archive breaks the element rules |
| `archive_too_large` | acquisition | the archive is over the compressed cap |
| `archive_too_many_files` | acquisition | the archive is over the file-count cap |
| `base_not_https` | configuration | a repository base is neither `https` nor `http` on a loopback host |
| `closure_too_large` | acquisition | the closure is over the package cap |
| `config_invalid` | configuration | a `repo.trust` entry is not a pattern, or names no signer |
| `fetch_failed` | acquisition | no repository answered, or answered with a status, for a list, manifest or archive |
| `file_manifest_mismatch` | acquisition | the archive holds a file the manifest does not list, or lacks one it does |
| `inclusion_missing` | acquisition | the trust entry requires log inclusion, which a key proof does not carry |
| `key_invalid` | configuration | the key file is not a PEM private key, or is not Ed25519 |
| `list_rollback` | acquisition | a version seen before is absent from the list now served |
| `manifest_invalid` | acquisition | the manifest is malformed, names another package or version, or declares a dependency without the package it names |
| `module_depth` | resolution, acquisition | dependency nesting is past the level cap |
| `module_integrity` | resolution, acquisition | the module's meaning is not the canon-hash that was pinned |
| `module_local` | resolution | a local file was written without a `./` prefix |
| `module_missing` | resolution | no store holds the module, or an alias is not declared |
| `module_moved` | resolution, acquisition | the package declares `moved`, and nothing follows a move |
| `module_path` | resolution | the path breaks a name rule or a length cap |
| `not_public` | publication | the package does not declare `publish: public` |
| `path_moved` | publication | the path is frozen by a `moved` declaration |
| `private_name_public_path` | configuration | the name is on the private list and `repo.private_base` names no repository |
| `proof_missing` | acquisition | no proof is served for the version |
| `proof_signer_untrusted` | acquisition | the proof's signer is not the one the trust entry accepts for that name |
| `response_mismatch` | acquisition | a served document is malformed, or names something other than what was asked for |
| `tombstoned` | acquisition | the version was withdrawn by the repository |
| `version_exists` | publication | the version was published before, and a version is never reusable |

## Related

- [`aontu sync`](/docs/reference-api#aontu-sync) for the verb that makes a
  project correct, its report, and the order the checks run in.
- [`aontu publish`](/docs/reference-api#aontu-publish) for what a publish
  sends, the compatibility gate, and the proof.
- [`aontu pkg`](/docs/reference-api#aontu-pkg) for the individual
  operations, including `verify`, `vendor`, `tree` and `serve`.
- [Modules](/docs/reference-language#modules) in the language reference for
  how a reference routes to a package, a file or an alias.
- [The codes](/docs/reference-errors#the-codes) in the errors reference for
  the six codes that are also engine codes, with their classes.
- [Vendor a dependency
  closure](/how-to/vendor-a-dependency-closure) and [publish a
  package](/how-to/publish-a-package) for the two jobs in recipe form.

---

# Grammar reference

_The published grammar rule by rule, the spellings the parser accepts beyond it, and the checks that hold the four grammar files to the engine._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-grammar.md · Page: https://aontu.dev/docs/reference-grammar

One grammar, published four times. The rules below are the **emission
surface**: what a document should be allowed to write, which is a
superset of JSON plus the operators, constraints and marks the
canonical form emits. The grammar is conservative by construction, so
it accepts less than the parser does and never more.

This page is normative for the published grammar as a set of rules:
which rules there are, what each spells, which spellings the parser
accepts beyond them, and what holds the four files to the engine. It
does not draw the grammar: [The published
grammar](/docs/reference-language#the-published-grammar) in the language
reference carries the railroad diagrams and the status of the emission
surface, and each construct is specified where the language reference
defines it. A refusal while a document is read is class `parse`, and
the codes are the [errors reference](/docs/reference-errors#class-parse).

## Contents

- [The published files](#the-published-files)
- [The rules](#the-rules)
- [Two notation choices](#two-notation-choices)
- [Where order matters](#where-order-matters)
- [What the parser also accepts](#what-the-parser-also-accepts)
- [What the grammar excludes](#what-the-grammar-excludes)
- [Lexical sets](#lexical-sets)
- [What holds the files to the engine](#what-holds-the-files-to-the-engine)
- [Related](#related)

---

## The published files

| file | notation | for | held to |
|---|---|---|---|
| [`grammar/aontu.abnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.abnf) | RFC 5234, with RFC 7405 case-sensitive literals | a reader, and the railroad diagrams the language reference draws | interpreted and run against every canonical output of the shared spec suite; every rule reachable; the name set checked against the engine |
| [`grammar/aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf) | GBNF | a constrained decoder | interpreted and run against the same corpus; the name set checked against the engine |
| [`grammar/aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark) | Lark | a parser generator | rule names checked against the other two; the name set checked against the engine |
| [`grammar/aontu.tmLanguage.json`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.tmLanguage.json) | TextMate | editor highlighting | the name set checked against the engine, and the copy the editor extensions ship checked against this one |

The first three are one grammar in three notations. Twenty-nine rules
are named in all three, rule for rule and name for name. The ABNF
carries four more, which the other two spell inline rather than name:
`unescaped`, and RFC 5234's core rules `ALPHA`, `DIGIT` and `DQUOTE`,
written out so that file stands alone. The fourth file is a highlighter
rather than a parser, and shares only the built-in name set.

## The rules

Thirty-three rules, in the order the file defines them. Every one is
reachable from `root`, and a rule that stops being reachable fails the
suite rather than sitting in the file.

| rule | what it spells |
|---|---|
| `root` | a whole document: whitespace, one value, whitespace |
| `value` | a value, which is a disjunction |
| `disjunct` | alternatives, separated by the vertical bar |
| `conjunct` | values that must all hold, separated by `&` |
| `prefixed` | a `*` preference, or a sum |
| `sum` | atoms joined by `+` |
| `atom` | a map, a list, a call, a reference, a kind, the placeholder, a scalar, or a parenthesised value |
| `map` | a brace-delimited bag of entries |
| `entry` | a spread template, or a pair |
| `spread` | `&`, `:` and the template every key of the bag must satisfy |
| `pair` | a key, an optional `?`, `:`, and a value |
| `list` | a bracket-delimited sequence of elements |
| `element` | a spread template, or a value |
| `func` | a built-in name applied to arguments |
| `name` | the closed set of built-in names |
| `ref` | a path reference, absolute from `$` or relative from `.` |
| `segment` | one path segment: letters, digits and `_` |
| `place` | the placeholder, `_`, bare |
| `kind` | a kind name |
| `scalar` | a string, an exact number, a number, `true`, `false` or `null` |
| `string` | a double-quoted run of characters |
| `char` | one character: unescaped, or `\` and an escape |
| `unescaped` | every code point but the quote and the backslash |
| `escape` | what may follow a backslash, including `u` and four hex digits |
| `hex` | one hexadecimal digit |
| `exact` | an exact literal: `0d`, digits, an optional fraction and exponent |
| `number` | digits, an optional fraction and exponent |
| `exponent` | `e` or `E`, an optional sign, and digits |
| `digits` | one or more digits |
| `ws` | the whitespace characters |
| `ALPHA` | a letter |
| `DIGIT` | a digit |
| `DQUOTE` | the double-quote character |

`root` is the start rule. Whitespace is permitted between every
element and is carried by `ws` rather than drawn.

## Two notation choices

**Every literal is case-sensitive**, spelled `%s"..."`. A plain
`"..."` is case-insensitive in RFC 5234, and this language is not:
`TRUE` is a bare word and `true` is a boolean. The reader refuses a
bare quoted literal rather than guess which was meant, so a rule
cannot acquire a case-insensitive literal by accident.

**Alternation is ordered.** RFC 5234's `/` is formally unordered, and
both consumers of the file take the first branch that matches. Where
one spelling is a prefix of another the longer comes first, which is
what makes the ordered reading and the unordered one accept the same
language.

## Where order matters

Ordered alternation has a consequence wherever one branch matches a
prefix of what another would match: the longer branch has to come
first. Every such place in the file, and what a swap would do:

| earlier | later | what a swap would do |
|---|---|---|
| `exact` | `number` | `0d5` begins with a digit, so `number` would match `0` and leave `d5` unread |
| `copyfiles` | `copy` | a call to `copyfiles` would be read as `copy` |
| `listitems` | `list` | a call to `listitems` would be read as `list` |
| `refer` | `re` | a call to `refer` would be read as `re` |
| `rel` | `re` | a call to `rel` would be read as `re` |
| `rem` | `re` | a call to `rem` would be read as `re` |
| `rep` | `re` | a call to `rep` would be read as `re` |

The first row is an ordering between two rules, in `scalar`. The rest
are built-in names inside the `name` rule, and are every prefix pair
that rule holds.

## What the parser also accepts

The grammar describes what a document should write. The parser accepts
these spellings too, and each means what the canonical form in the
third column says. A model generating aontu should write the canonical
spelling; a human reading a document may meet either.

| spelling | written | means |
|---|---|---|
| an unquoted key | `a: 1` | `{"a":1}` |
| a document with no outer braces | `a: 1 b: 2` | `{"a":1,"b":2}` |
| a bare word as a string | `a: hello` | `{"a":"hello"}` |
| a single-quoted string | `a: 'x'` | `{"a":"x"}` |
| a trailing comma | `a: {b: 1,}` | `{"a":{"b":1}}` |
| a path-flattened pair | `a: b: 1` | `{"a":{"b":1}}` |
| a comment to end of line | `a: 1 # note` | `{"a":1}` |
| an unquoted key the canonical form quotes | `a-b: 1` | `{"a-b":1}` |

A newline separates entries as a comma does, and a backtick-quoted
string reads as a double-quoted one. Two entries naming the same key
meet rather than replace, which is the language's own rule and not a
spelling: see [the unification rules](/docs/reference-language#unification-rules).

## What the grammar excludes

Two forms are deliberately absent, and the suite requires the grammar
to refuse them rather than merely omit them:

- **`@"..."` includes.** A generated document should describe values
  rather than reach for files, so nothing a constrained decoder emits
  can read the filesystem.
- **The tolerated spellings above.** The canonical form quotes every
  key and writes one spelling per construct, and one spelling is what
  a grammar is for.

An excluded form is still valid aontu. The exclusion says what a
generator should write, not what the engine reads.

## Lexical sets

| set | members |
|---|---|
| whitespace | space, tab, carriage return, line feed |
| an escape after `\` | `"`, `\`, `/`, `b`, `f`, `n`, `r`, `t`, and `u` with four hex digits |
| unescaped | every code point except `"` and `\`, control characters included |
| a hex digit | `0` to `9`, `A` to `F`, `a` to `f` |
| a path segment | letters, digits and `_`, and never `-` |

Control characters are admitted because the canonical form writes them
escaped, and a grammar that refused them would refuse less than the
parser accepts in the one direction this file may not take.

A path segment has no `-` because a hyphen is not a bare-text
character: `a:6-2` is a parse error rather than the key `6-2`, so
admitting it in a segment would describe a language wider than the one
the engine reads.

## What holds the files to the engine

The grammar is executed rather than published and left alone. In both
implementations' test suites:

| check | what it proves |
|---|---|
| the reader parses the file | the notation is well formed, and no literal is case-insensitive |
| every canonical output of the shared spec suite is accepted | the grammar has not fallen behind the engine |
| every excluded form is refused | the exclusions are real, rather than an omission |
| the three parser grammars name the same rules, less the four the ABNF writes out | one grammar, three notations |
| every rule is reachable from `root` | no rule outlives the construct it spelled |
| all four files name exactly the engine's built-ins | a function added or retired cannot leave a grammar behind |
| the editor extensions' copy is the published file | an editor highlights what the engine reads |

## Related

- [The published grammar](/docs/reference-language#the-published-grammar)
  in the language reference for the railroad diagrams and the status of
  the emission surface.
- [The formatted
  form](/docs/reference-language#the-formatted-form) for what `aontu fmt`
  writes, which is the spelling a page shows.
- [Class `parse`](/docs/reference-errors#class-parse) in the errors
  reference for every code a refusal while reading carries.
- [Grammars: `abnf()` and
  `parse()`](/docs/reference-language#grammars-abnf-and-parse) for using a
  grammar of your own inside a document, which is a different thing
  from this one.
- [The published grammar](/docs/reference-api#the-published-grammar) in
  the API reference for the files as an artefact of the distribution.

---

# Agent and editor reference

_Every door a machine reads a model through, the one answer shape they share, what none of them does, and the include posture each takes._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-agents.md · Page: https://aontu.dev/docs/reference-agents

An editor and an agent read a model through the same doors, and there
are more of them than the command line. This page is normative for
that surface taken as a whole: which doors there are, what each
answers, what none of them does, what posture each takes towards
`@"..."` includes, and which implementation carries it.

Each door's own specification is elsewhere and is linked from the
table below. Nothing here repeats a tool list, an option or an exit
table: the [API reference](/docs/reference-api#command-line-interface)
specifies every verb, [the language server](/docs/lsp) specifies the
protocol and the library behind it, and the [errors
reference](/docs/reference-errors#exit-codes) specifies the exit codes and
the codes a report carries.

## Contents

- [The doors](#the-doors)
- [The machine answer](#the-machine-answer)
- [What none of them does](#what-none-of-them-does)
- [Includes, by door](#includes-by-door)
- [The teaching topics](#the-teaching-topics)
- [Which implementation has it](#which-implementation-has-it)
- [Related](#related)

---

## The doors

| door | reached by | answers | specified in |
|---|---|---|---|
| the verbs | `aontu <verb>`, with `--format json` where a report is wanted | one report a verb | [command-line interface](/docs/reference-api#command-line-interface) |
| the embedded API | a library call, in either implementation | the same reports, as values rather than text | [TypeScript API](/docs/reference-api#typescript-api), [Go API](/docs/reference-api#go-api) |
| the language server | `aontu lsp`, or the `aontu-lsp` binary, over stdio | diagnostics, hover and completion as an editor asks for them | [the language server](/docs/lsp) |
| the tool server | `aontu mcp`, or the `aontu-mcp` binary, over stdio | a tool for each report it serves, which is a subset of the verbs, under the same JSON contract | [the MCP server](/docs/reference-api#the-mcp-server) |
| the teaching pack | `aontu help <topic>` | the language, from inside the binary, with no network and no checkout | [`aontu help`](/docs/reference-api#aontu-help) |
| the code index | `aontu explain <code>`, or `--list` | what one refusal means, or every registered code with its class | [errors reference](/docs/reference-errors#the-codes) |
| the starting documents | `aontu init [dir]` | a model, an instance of it, and the checks to run | [`aontu init`](/docs/reference-api#aontu-init) |
| the prose entrypoint | `aontu agentsmd --write <file>` | the stanza naming a document's pin, root keys, shape and commands | [`aontu agentsmd`](/docs/reference-api#aontu-agentsmd) |
| the structured-output bridge | `aontu jsonschema` | a JSON Schema for the document, and the list of what it could not say | [`aontu jsonschema`](/docs/reference-api#aontu-jsonschema) |
| the published grammars | the files in [`grammar/`](https://github.com/aontu-lang/aontu/blob/main/grammar/) | the emission surface, for a constrained decoder or a highlighter | [grammar reference](/docs/reference-grammar) |
| the editor plugins | [`editors/`](https://github.com/aontu-lang/aontu/blob/main/editors/) for Visual Studio Code, Emacs and Vim | the language server, wired to an editor | [editor configuration](/docs/lsp#editor-configuration) |

A door is a way in, not a tier: the tool server answers with the
report the verb prints, and the verb prints what the library returned.
One question has one answer whichever door it arrives by, which is the
property that makes a transcript in a document and a tool call in an
agent the same evidence.

## The machine answer

`--format json` is a per-verb option rather than a global one: `fmt`,
`template` and `agentsmd` do not take it, and refuse it by name.

Where a verb does answer JSON it answers one object, and every one of
them opens with the same block:

| key | carries |
|---|---|
| `aontu` | `verb` and `version`: which verb answered, and the version that answered it |

`aontu trace --format json` is the one exception: it answers its record
alone, under `trace`.

**How an answer says whether it holds** is one of three shapes. The
shape belongs to the verb rather than to the run, so a document that
does not hold changes the values and never the keys:

| shape | the answer carries | the verbs |
|---|---|---|
| `ok` and the answer beside it | `ok`, with `out` or `record` | the bare entry point, `model get`, `model why` |
| a verdict word | `verdict`, with the verb's own fields | `vet`, `subsume`, `breaking`, `relations`, `reaches`, `trim`, `jsonschema`, `view`, `render --check`, `allow` |
| the payload alone | neither: the object is the answer | `hash`, `help`, `explain` |

**A refusal is an answer**, and the findings say what was refused. The
key they arrive under is the verb's too:

| findings under | the verbs |
|---|---|
| `findings` | the bare entry point, `model get`, `model why`, `vet`, `subsume`, `breaking`, `relations`, `allow` |
| `errors` | `reaches` |
| nothing: the verb reports none | `trim`, `jsonschema`, `view`, `render --check`, `hash`, `help`, `explain` |

A verb that reports no findings says what it could not do in a field of
its own instead: `view`'s `loss`, `jsonschema`'s `lossy` and
`render --check`'s `drift`.

A caller branches on `ok` or on `verdict` rather than parsing prose, and
the exit code carries the same answer: the [errors
reference](/docs/reference-errors#exit-codes) is normative for it. Each
verb's own section names the fields beside these.

The tool server keeps the same rule at the protocol level: a tool whose
document does not hold answers with its own report and `isError:
false`, because the report is the answer. `isError` is reserved for a
call that could not be made at all, such as an unknown tool, a
malformed argument, or a file argument the server does not serve.

## What none of them does

These hold across every door, and each is the property an integrator
needs before wiring one into something that runs unattended:

- **The language server never writes a file.** It answers, and the
  editor owns the buffer.
- **The tool server never writes a file.** `set` answers the new
  overlay text, and the caller owns the write.
- **`init` never overwrites.** If any member of the trio already
  stands in the directory it refuses before writing any of them, so a
  refused run leaves nothing half written.
- **`agentsmd --write` changes only what lies between its two
  markers.** Everything outside them is left exactly as it was, which
  is what makes it safe to re-run and safe to point at a file someone
  else writes prose in.
- **A `--check` run writes nothing.** It compares and exits.
- **Evaluation never reaches the network.** A module resolves from
  local stores only; the package verbs are the only ones that fetch,
  and they say so by name.

## Includes, by door

`@"..."` reads a file while a document is evaluated, so every door
that evaluates a document a caller supplied has a posture towards it.
The postures are the [trust contract](/docs/trust); this is which door
takes which by default.

| door | default | how it is set |
|---|---|---|
| the verbs | `system`: an include reads what the process can read | `--trust none`, `--trust root[:dir]`, or `--include-root <dir>`, on every verb that reads a document; `help`, `explain` and `init` read none and refuse them, and `lsp` takes no arguments at all |
| the embedded API | whatever the caller passes, and `system` where it passes nothing | the `trust` option of the call |
| the language server | confined below the workspace folder the client named, and `system` where the client named none | `initializationOptions.aontu.trust.include`: `system`, `none`, a root, or an in-memory map |
| the tool server | `none`: every include is denied | `--root <dir>`, which confines includes below the resolved root and serves the path arguments of every tool |

A server that evaluates source from a caller is exactly the place an
unconfined include is a mistake, which is why the tool server denies
them until a root says otherwise, and why a path argument is refused
until then too.

## The teaching topics

`aontu help` lists what the binary carries, and `aontu help <topic>`
prints one. Each is staged into both implementations at build time from
its source, and both suites hold the staged copy to that source byte
for byte, so the answer travels with the binary rather than with a
checkout.

| topic | what it carries |
|---|---|
| `tasks` | the job-to-verb index: which verb answers the question you have |
| `language` | the grammar card: everything the language spells, on one page |
| `examples` | the ladder, from plain JSON upward, one addition at a time |
| `codes` | what a refusal means, and what to do about it |
| `grammar` | the published ABNF, for a parser or a constrained decoder |

`aontu help` with no topic lists them, `aontu --help` documents the
verbs and their flags, and `--format json` answers either as an object.

## Which implementation has it

| door | TypeScript | Go |
|---|---|---|
| the verbs | yes | yes, less the tool server |
| the embedded API | yes | yes |
| the language server | yes | yes |
| the tool server | yes | no: `aontu mcp` says so and exits `2` |
| the teaching pack | yes | yes, from a committed copy of the staged pack |
| the code index | yes | yes |
| the starting documents | yes | yes |
| the prose entrypoint | yes | yes |
| the structured-output bridge | yes | yes |
| the published grammars | shared: the files are the distribution's, not a port's | shared |
| the editor plugins | either binary serves them | either binary serves them |

The tool server is the one door with no Go half. Its role there is the
embedded API, which carries the same calls.

## Related

- [The language server](/docs/lsp) for the protocol surface, the library
  API in both implementations, and how diagnostics are computed.
- [The MCP server](/docs/reference-api#the-mcp-server) for the tools, what
  each answers, and the confinement the `--root` posture adds.
- [The trust contract](/docs/trust) for what an include may read, and what
  a profile confines.
- [Exit codes](/docs/reference-errors#exit-codes) in the errors reference
  for the verdict every verb carries out of a run.
- [Grammar reference](/docs/reference-grammar) for the published grammars
  and what holds them to the engine.
- [Give an agent an
  entrypoint](/how-to/give-an-agent-an-entrypoint) and [wire your
  editor](/how-to/wire-your-editor) for the two jobs in recipe form.

---

# API reference

_The API and the command line: every verb, every flag, every exit code, and the MCP server._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/reference-api.md · Page: https://aontu.dev/docs/reference-api

The programming interfaces of both implementations, plus the
command-line tool. For the language itself see the
[Language reference](/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:

<!-- test: run -->
```sh
$ aontu --help
Usage: aontu [options] [file]
       aontu vet [options] <schema> <data> [more-data...]
       aontu subsume [options] <general> <specific>
       aontu breaking --against <file|git#rev> [options] <file>
       aontu trim --check [options] <file>
       aontu relations [options] <file>
       aontu reaches <from> <to> [--relation <name>] [options] <file>
       aontu view <kind> [options] <file>...
       aontu view --views <path> [--check] [options] <file>
       aontu jsonschema [--at <path>] [--strict] [options] <file>
       aontu template [--resugar] [--check] [--marker <token>]
                      [--profile <file>] <file>
       aontu trace [--at <path>] [--format json] [--marker <token>]
                   [--profile <file>] <file>
       aontu render [--check] [--at <path>] [--format json]
                    [--marker <token>] [--profile <file>]
                    <file|folder> <path>
       aontu hash [options] <file>
       aontu sync [--frozen] [options] [dir]
       aontu add <pkg>[@<version>] [options] [dir]
       aontu get <pkg>[@<version>] [options] [dir]
       aontu remove <pkg> [options] [dir]
       aontu why <pkg> [options] [dir]
       aontu publish [--yes] [--to <dir>] [options] [dir]
       aontu pkg tidy|verify|vendor|manifest|refreeze|tree|outdated|serve
                 [options] [dir]
       aontu pkg keygen <file>
       aontu model get <path> [options] <file>
       aontu model why <path> [options] <file>
       aontu model set <path>=<value>... --entry <file> --overlay <file>
       aontu allow --role <role> [--at <path>] <roles-file> <path>...
       aontu agentsmd [--write <AGENTS.md>] [--depth <n>] <file>
       aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>]
                 [--profile <file>] <file>...
       aontu help [topic] [--format text|json]
       aontu explain <code> | --list [--format text|json]
       aontu init [dir]
       aontu lsp
       aontu mcp [--root <dir>]

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 <t>` (the include capability: `system`, `none`, or
`root[:dir]`; see [`AontuOptions`](#aontuoptions) for what each
admits), its shorthand `--include-root <dir>`, and
`--text-ext <ext>[,<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 <dir>`
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.aon 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.aon`, `/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.

```
aontu vet [options] <schema> <data> [more-data...]

  --at <path>       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 <n>  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 <p> Measure coverage under this path of the data only
  --format <f>      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:

```
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 [`&:`](/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.aon`:

<!-- test: scenario vet-site -->
<!-- test: file schema.aon -->
```aontu
port: 8080
```

and vet a `data.aon` that spells a different port in hex:

<!-- test: file data.aon -->
```aontu
port: 0x1F
```

<!-- test: run -->
```sh
$ aontu vet --format json schema.aon data.aon
{
  "aontu": {
    "verb": "vet",
...
      "sites": [
        {
          "col": 7,
          "file": "data.aon",
          "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.aon` and reached through `@"./lib/types.aon"` is reported at
`lib/types.aon` 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.aon` names `types.aon`, `vet a/b/contract.aon` names
`a/b/types.aon`, 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 <file>`.

**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.aon`:

<!-- test: scenario vet -->
<!-- test: file service.aon -->
```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:

<!-- test: file deploy.json -->
```json
{"service": {"name": "checkout", "prot": 8080,
  "replicas": "3"}}
```

<!-- test: run -->
```sh
$ aontu vet service.aon 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.aon: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):

<!-- test: skip abridged finding excerpt; hint prose is deliberately outside cross-port parity and tracks the engine's wording -->
```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](/docs/reference-language#recursive-references-fixpoints) needs
nothing extra from `vet`: the definition expands one level per
[meet](/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](/use-cases/13-recursive-schema).
Write it as `chain.aon`:

<!-- test: scenario vet-recursive -->
<!-- test: file chain.aon -->
```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:

<!-- test: file request.json -->
```json
{"approver": "lead@acme.example", "decision": "approved",
 "then": {"approver": "cfo@acme.example"}}
```

<!-- test: run -->
```sh
$ aontu vet --at $.spec.Step chain.aon request.json
verdict: valid
```

A chain whose third level breaks the `approver` pattern, as
`request-deep.json` does, is refused **at that depth**:

<!-- test: file request-deep.json -->
```json
{"approver": "lead@acme.example", "decision": "approved",
 "then": {"approver": "cfo@acme.example",
          "then": {"approver": "EXTERNAL@other.example"}}}
```

<!-- test: run -->
```sh
$ aontu vet --at $.spec.Step chain.aon 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.aon: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](/how-to/define-a-recursive-schema).

### `aontu subsume`

The subsumption query as a command
([docs/reference-language.md, "Subsumption"](/docs/reference-language#subsumption)):
does the general document admit every instance the specific one admits?

```
aontu subsume [--profile values|defaults|gen] [--at <path>]
              [--format text|json] <general.aon> <specific.aon>
```

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](/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.aon`:

<!-- test: scenario subsume-recursive -->
<!-- test: file general.aon -->
```aontu
spec: hide({ Step: { label:string then?:$.spec.Step } })
doc: $.spec.Step
```

and a `specific.aon` whose step recurses into a DIFFERENT definition:

<!-- test: file specific.aon -->
```aontu
spec: hide({ Step: { label:"start" then?:$.spec.Other } Other:label:string })
doc: $.spec.Step
```

<!-- test: run -->
```sh
$ aontu subsume general.aon specific.aon
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.aon:1:41 ($.spec.Step)
  specific: specific.aon: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.aon:2:6 ($.spec.Step)
  specific: specific.aon: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.

```
aontu breaking --against <file|git#rev> [--at <path>]
               [--mode backward|forward|full]
               [--allow-undecided] [--format text|json] <file.aon>
```

-  `--against` takes a file path or `git#<rev>`, and is repeatable. A
  `git#<rev>` spelling is the old version of the **whole tree**, not of
  the entry file alone: the revision's includable sources (`.aon`,
  `.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 <path>` 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.

```
aontu trim --check [--format text|json] <file.aon>
```

- 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.aon`
  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](/docs/reference-language#declared-relations)
checks (acyclicity and inverse consistency) over one finished model.

```
aontu relations [--format text|json] <file.aon>
```

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](/use-cases/12-relations).
Write the vocabulary as `spec.aon`:

<!-- test: scenario relations -->
<!-- test: file spec.aon -->
```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.aon`, passes:

<!-- test: file system.aon -->
```aontu
@"./spec.aon"

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)]
```

<!-- test: run -->
```sh
$ aontu relations system.aon
verdict: pass
```

A `bad-system.aon` whose two services depend on each other, with
neither inverse written out, fails on every count at once:

<!-- test: file bad-system.aon -->
```aontu
@"./spec.aon"

services: { &: $.spec.Service }
services: auth: dependsOn: [path($.services.billing)]
services: billing: dependsOn: [path($.services.auth)]
```

<!-- test: run -->
```sh
$ aontu relations bad-system.aon
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](/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](/docs/reference-language#declared-relations) states
  the rule; the [explanation](/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.

```
aontu reaches <from> <to> [--relation <name>] [--format text|json] <file>
```

[`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.aon` model above:

<!-- test: run -->
```sh
$ aontu reaches $.services.web $.services.ledger system.aon
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 <name>` 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.aon` the `usedBy` inverses run the other way, so the ledger
reaches the web service in general but not along `dependsOn`:

<!-- test: run -->
```sh
$ aontu reaches $.services.ledger $.services.web system.aon
verdict: reaches

$.services.ledger -> $.services.billing -> $.services.web
$ aontu reaches $.services.ledger $.services.web --relation dependsOn system.aon
verdict: unreachable

$.services.ledger does not reach $.services.web
$ echo $?
1
```

And an endpoint that names no node refuses rather than answering:

<!-- test: run -->
```sh
$ aontu reaches $.services.web $.services.ledgr system.aon
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.

```
aontu view <kind> [--as <profile>] [--at <path>] [--out <file> [--check]]
           [--strict] [--max-rows <n>] [--depth <n>] [--style <s>]
           [--format text|json] [options] <file>...
```

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.aon` model above over its `dependsOn` relation, first
as the tree, then as the matrix in partition order:

<!-- test: run -->
```sh
$ aontu view tree --relation dependsOn system.aon
web
└── billing
    └── ledger
```

<!-- test: run -->
```sh
$ aontu view matrix --relation dependsOn --order partition --closure system.aon
          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:

<!-- test: run -->
```sh
$ aontu view graph --relation dependsOn system.aon
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](/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.aon`:

<!-- test: file ports.aon -->
```aontu
host: "0.0.0.0"
port: 8080
tls: true
timeout: 1.5
retries: integer
backoff: integer & min(1)
```

<!-- test: run -->
```sh
$ aontu view lattice ports.aon
                                           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:

```
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 <s>`** 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 <file>` 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 <n>`** (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 <n>` 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 <path>`** 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 <path>` (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
  <field>` puts each node in a subgraph named by that field's value
  (ids `g0`, `g1` and so on, in label order); `--label <field>` 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 <field>` (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 <path>` names a map whose keys are the sets,
  `--member <key>` the field holding each set's members (a list of
  strings), `--universe <path>` 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 <n>` drops the low ones and `--max-cols <n>` 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 <n>` 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 `.aon`.
- 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 <path>` 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.aon` beside the
`system.aon` above:

<!-- test: file views.aon -->
```aon
@"./system.aon"

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"
}
```

<!-- test: run -->
```sh
$ aontu view --views '$.views' views.aon
$ aontu view --views '$.views' --check views.aon
$ 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.aon`:

<!-- test: file views-typed.aon -->
```aon
@"aontu:view"
@"./system.aon"

views: { &: $.aontu.View.Figure } & {
  arch: {
    kind: matrix
    relation: dependsOn
    order: partition
    closure: true
    out: "arch.dsm.txt"
  }
}
```

<!-- test: run -->
```sh
$ aontu view --views '$.views' --check views-typed.aon
$ 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](/use-cases/01-service-catalog) the graph and
the matrix, [04-schema-evolution](/use-cases/04-schema-evolution)
the poset, [08-feature-flags](/use-cases/08-feature-flags) the
ladder, [12-relations](/use-cases/12-relations) the graph and the
ER diagram, and [16-module-deps](/use-cases/16-module-deps) the
tree, the matrix and the layers; 16 also declares all seven of its
figures in a `views.aon` 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.

```
aontu jsonschema [--at <path>] [--strict] [--format text|json] <file>
```

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.aon > schema.json` writes a usable schema and still
tells the reader what it left behind. Write a `contract.aon`:

<!-- test: scenario jsonschema -->
<!-- test: file contract.aon -->
```aontu
spec: name: string & re("^[a-z][a-z0-9-]{2,39}$")
spec: tier: *internal|standard|critical
```

<!-- test: run -->
```sh
$ aontu jsonschema --at spec contract.aon
{
  "$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 <path>` 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: <template>`,
which is what a spread means. A written list is a **tuple**, so
`prefixItems` plus `items: false`.

**And `close()` is `additionalProperties: false`**: the one thing the
two languages say identically, and the reason the export is worth
having at all: the closedness an agent's output must respect crosses
without loss.

**What does not cross is REPORTED, never dropped in silence.** A
converter that silently lost a constraint would hand its caller a schema
that admits *more* than the model does, which is the failure this
language exists to refuse. So each loss carries its path, the aontu
construct's own name, and one sentence saying what the schema says
instead:

```
lossy: $.spec.total must: an evaluate-only check is opaque by
  construction … so it is DROPPED and the schema admits values `vet`
  refuses
```

The losses, and why each is one:

| Construct | Why JSON Schema cannot say it |
|---|---|
| `must(c, m)` | Band B is opaque by construction: it carries the author's own message and the algebra never reasons about it |
| `unique(k)` | there is no uniqueness-by-property keyword; `uniqueItems` compares whole items |
| `biginteger`, `bigdecimal`, and exact literals | JSON has one number type and it is binary64, so the exactness these leaves exist for has no receiver |
| `hide(x)` | a hidden entry is not generated, so it is not part of the value a consumer produces |
| `&:` on a closed map | the template constrains keys that cannot exist |
| a `length` with no domain | no keyword counts a string *or* a container, so it is exported as `minItems`/`maxItems` |
| residue: an unresolved reference, a waiting call | not a property constraint at all; guessing one would be inventing a promise |

The exact-leaf loss is the one with a way around it. Money carried as a
**decimal string** with a conversion mark exports without loss (the
pattern and the mark both cross) and stays exact on the aontu side:
see [Carry exact money over JSON](/how-to/carry-exact-money-over-json).

**A recursive position is residue, and exports as residue.** JSON
Schema can spell recursion (`$defs` plus `$ref`), but this exporter
does not mint it: a
[recursive reference](/docs/reference-language#recursive-references-fixpoints)
that has met no data is unresolved, so it crosses as the empty schema
`{}` (a position that admits *anything*) and is reported under
`lossy` as `unresolved`, like any other residue. Two consequences
follow. Anchor the export at a definition kept **un-hidden**, because
a `hide()` mark propagates and a hidden entry is omitted from the
export entirely; and treat the exported schema as wider than the
model at the recursive position: [`vet`](#aontu-vet) the produced
value against the model, which does check every depth. `--strict`
turns the loss into exit 1. Write a recursive `steps.aon`:

<!-- test: file steps.aon -->
```aontu
Step: { approver:string & re("^[a-z]+@acme[.]example$") then?:$.Step }
```

<!-- test: run -->
```sh
$ aontu jsonschema --strict --at Step steps.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "approver": {
      "pattern": "^[a-z]+@acme[.]example$",
      "type": "string"
    },
    "then": {}
  },
  "required": [
    "approver"
  ],
  "type": "object"
}
lossy: $.Step.then unresolved: this is not a value yet, so there is nothing to constrain a consumer to; the schema admits anything here
$ echo $?
1
```

Everything above `then` crosses intact; the tail is the gap it reports.
Without `--strict` the same export exits 0.

- The library form is `jsonSchema(src, options?)` in TypeScript and
  `Aontu.JSONSchema(src, at)` in Go, returning the identical
  `{verdict, schema, lossy}` record (plus `errors` on a failed run).

### `aontu model get`

Select one node of an evaluated document by path and render it: the
task-sized slice, instead of the whole file as one JSON blob.

```
aontu model get <path> [-c|--canon] [--keys] [--types] [--depth <n>]
          [--format text|json] <file.aon>
```

- **Evaluation is global.** Unification has no partial mode: the whole
  document is evaluated and then one node is selected. What `get` buys
  is the size of the *answer*, not the cost of producing it.
- The path is what a reference means by `$.a.b`: map keys and
  canonical-decimal list indices, and nothing else, so `$.a.01` names
  nothing here exactly as it names nothing there. A key that *contains*
  a dot is likewise unreachable, as it is to a reference.
- Default output is the fragment's generated JSON; `--canon` is its
  canonical form, and for the root path that is byte-identical to
  `aontu --canon`.
- Exit codes: `0` rendered, `1` the path names nothing (the finding
  carries a nearest-key suggestion), `2` usage, `4` the document does
  not stand up on its own, including a node that is not concrete, for
  which there is no JSON to print.

Write an `app.aon` whose spread template supplies defaults:

<!-- test: scenario query -->
<!-- test: file app.aon -->
```aontu
services: { &: { replicas: *1|integer port: *8080|integer } }
services: auth: replicas: 3
services: billing: {}
```

<!-- test: run -->
```sh
$ aontu model get $.services.auth app.aon
{
  "port": 8080,
  "replicas": 3
}
$ aontu model get --keys $.services app.aon
auth
billing
$ aontu model get $.services.auht app.aon
$.services.auht: no_path [reference]
  The path $.services.auht names nothing in this document.
  note: did you mean auth?
$ echo $?
1
```

The mistyped path is exit 1 with a suggestion, not an empty render: a
missing key and an empty value are different answers.

**The projections are lattice abstractions.** Each view is a valid
aontu document that *subsumes the truth*: generalisation, never
distortion:

| flag | view |
|------|------|
| `--types` | every concrete leaf lifted to its own kind: `{"replicas":3}` becomes `{"replicas":integer}` |
| `--depth n` | structure to depth n; every elided subtree renders as `top`: "no further information at this tier" |
| `--keys` | the node's own key names (or list indices), one per line |

On `app.aon` the shape view erases the concrete leaves:

<!-- test: run -->
```sh
$ aontu model get --types $.services.auth app.aon
{"port":*integer|integer,"replicas":integer}
```

That claim is checked rather than asserted: every projection row of
`test/spec/query.tsv` runs [`subsume`](#aontu-subsume)`(view, truth)` in
both implementations and requires `subsumes`. It runs under the
**values** profile, deliberately: a shape view *erases defaults*
(`*8080|integer` becomes `*integer|integer`, as above), which the
`defaults` profile would rightly call a compatibility break. The claim
projections make is about the values admitted, not about which one is
generated.

Kinds are lifted through the lattice's own `superior()`, so the view
follows the type system rather than a table of the renderer's opinions;
a value that is *already* an abstraction (a kind marker, a constraint,
an unresolved reference) is left alone rather than generalised twice.
Projections are not canonical form and are never fed to
[`aontu hash`](#aontu-hash): the flags are distinct from `--canon` to
keep that unambiguous.

### `aontu model why`

Provenance: what *contributed* to the value at a path, in order, with
the site each contribution was written at. The positive twin of
[`vet`](#aontu-vet)'s report: errors explain what failed to unify,
`why` explains what did.

```
aontu model why <path> [--format text|json] <file.aon>
```

Ask it about the `app.aon` above:

<!-- test: run -->
```sh
$ aontu model why $.services.auth.replicas app.aon
$.services.auth.replicas = 3
  1. *1|integer  app.aon:1:28  (spread)
  2. 3  app.aon:2:27
```

- A **contribution** is a value the author *wrote* that met something
  at this path. Values the engine mints on the way (a kind lifted
  from a leaf while a disjunction trials its members, a fold's
  intermediate) are not contributions, and neither are the members
  *inside* one written value, which meet at the same path as that
  value resolves. A **conjunct** is the exception in the other
  direction: `a & b`, or the merge of two duplicate keys, is the
  statement that several separately written values must all hold, so
  it expands into one contribution each.
- **Roles**: `literal`, `spread` (a template applied to this key),
  `ref` (the reference itself, whose canon names its target) and
  `pref`. A preference *inside* a spread template reports as `spread`,
  which is the thing the author needs to be told.
- Contributions are listed in **source order** (file, then row, then
  column) not in the order the fixpoint happened to meet them, which
  is an engine detail.
- **Provenance travels with a clone.** A value that reached this path
  by being copied from somewhere else (a spread template applied per
  key, a `pack()` generator's child, a `$ref`, a `refer(t)` flow) is
  reported as the value the author wrote, at the line
  they wrote it on. That is the whole audit question: *which file set
  this?* A clone of a written value is that written value somewhere
  else, so it is named; a value the engine mints on the way is not.
- **The value that stands at a path is a contribution when nothing met
  there.** A generator places a value without meeting anything, and a
  path with no meets still has a source.
- A value the author never wrote and no template supplied has **no
  contributions**, and says so. That is a fact about the document, not
  a failure.
- `--format json` emits the record: `{path, value, conjuncts:
  [{canon, role, site}]}`, with sites in the same shape the vet report
  uses. Exit codes mirror `get`'s: `0` explained, `1` the path names
  nothing, `2` usage, `4` the document does not stand up.
-  **Cost**: the recorder rides the context and is off by
  default: uninstrumented evaluation pays one property load per meet. An
  instrumented run pays site materialisation, one map entry per path
  met, and the spread walk that marks a template's application.

### `aontu model set`

Change a document by **appending to an overlay**: or, with
`--in-place`, by rewriting the literal inside that same overlay.
`--overlay` is required either way, and the entry document is never
written.

```
aontu model set <path>=<value>... --entry <file> --overlay <file>
         [--in-place] [--dry-run] [--format text|json]
```

Write an `entry.aon` that constrains `owner` and pins `replicas`:

<!-- test: scenario set -->
<!-- test: file entry.aon -->
```aontu
services: auth: { owner:string replicas:3 }
```

<!-- test: run -->
```sh
$ aontu model set '$.services.auth.owner="identity-2"' --entry entry.aon --overlay changes.aon
verdict: valid
wrote: changes.aon
```

A pinned value refuses the append and the overlay is left unchanged:

<!-- test: run -->
```sh
$ aontu model set '$.services.auth.replicas=5' --entry entry.aon --overlay changes.aon
verdict: invalid

$.services.auth.replicas: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.services.auth.replicas
  data: changes.aon:2:33 (5)
  schema: entry.aon:1:41 (3)
$ echo $?
1
```

A literal the overlay itself pinned is `--in-place`'s case: the span
is rewritten where it was written, and the report says so as source
text:

<!-- test: run -->
```sh
$ aontu model set '$.services.auth.owner="identity-3"' --entry entry.aon --overlay changes.aon --in-place
verdict: valid
replaced: changes.aon:1:30 "identity-2" -> "identity-3"
wrote: changes.aon
```

- The assignment becomes a **path-flattened conjunct**: `$.a.b=1`
  is appended as `"a": "b": 1`, keys quoted so a segment may be a
  word the grammar spells otherwise, a number, or hold a space. The
  text is split at the *first* `=`; everything after it is aontu
  source, so a value may contain one.
- This needs no rewriter, and damages nothing: an overlay entry is
  just another conjunct, and unification is order-independent, so
  appending to a second file is the same value as writing into the
  first. The shared suite asserts that equivalence for every row
  rather than claiming it.
- **Appending cannot change a pinned value.** The lattice refuses `5`
  against `3`, the verdict is `invalid`, and the finding names the
  pinning site, which [`aontu model why`](#aontu-model-why) then explains.
  `--in-place` closes that loop.
- **A path reached through a reference is refused** (`patch_not_editable`).
  `n: $.base` against `base: 7` is pinned by `base`'s line, not by
  `n`'s: splicing there would rewrite the referent for every reader of
  it and leave the named path where it was. The assignment is appended
  instead, exactly as it would be without the flag.
- **`--in-place` rewrites the literal where the author wrote it.** The
  span at `(row, col, len)` is replaced and nothing else is touched, so
  comments and layout survive, including a comment on the edited line.
  Nothing is re-serialised, which is why no CST is needed: a targeted
  splice never reads the bytes it does not replace.
- **The span is verified before a byte is written.** A site carries
  `src`, the source text it claims to cover, and the text at the span
  must equal it. That is what makes `port: 0x1F` safe to rewrite even
  though its value is `31`: the span is four code units and says so.
-  **An overlay that loads another document is refused outright.** A
  literal reached through `@"..."` cannot be told apart from the
  overlay's own by position (an include holding `a: 42` at 1:4 and an
  overlay holding `x: 42` at 1:4 give the same site and the same text) so
  the evaluation that decides what to edit denies loads, and what
  resolves is what the overlay says by itself.
-  **It rewrites only a single editable literal, and appends
  otherwise.** The contribution must be one `literal`-role conjunct in
  *this* overlay whose `src`, parsed alone, means the contribution's own
  canon, which refuses a compound, because a site names a compound's
  *opening token* (`min` for `min(1)`, `1` for `1+2`, `{` for a map). It
  must also be concrete: `a: integer` is a constraint, not a pin, and
  appending narrows it without discarding what it says. Anything else
  appends exactly as plain `set` would, plus one **warning** naming the
  case: `patch_not_editable`, `patch_ambiguous` or `patch_span_mismatch`.
  Warnings never move a verdict, so `--in-place` cannot turn a run that
  would have held into one that does not.
- A default (`a: *1`) is left alone with no warning: appending already
  overrides a default correctly.
- **The text form says `would replace:` when nothing was written**, and
  `replaced:` only when the file changed: a run can have one replaceable
  assignment and another that refuses it as a whole. A run that HOLDS
  writes its status to stdout whether or not it carries warnings; the
  warnings go to stderr beside it.
- The report gains `replaced`, one entry per rewrite, carrying the path,
  the site, and `from`/`to` as **source text**: replacing `0x1F` with
  `31` is a different edit from replacing it with `0x1F`, and only the
  spelling says which.
- **The overlay is written only when the change holds.** An `invalid`
  or `error` verdict leaves the file exactly as it was: a change the
  author still has to think about should not sit in their
  configuration while they do. `--dry-run` writes nothing either way
  and prints what would have been written.
- A missing overlay file is the empty overlay, and is created.
- Exit codes are [`vet`](#aontu-vet)'s verdict classes: `0` valid,
  `1` invalid, `2` usage, `3` incomplete, `4` the entry does not stand
  up on its own.

### `aontu allow`

Ask a role model whether a role may modify every one of the given
subtrees, and answer before the change is made: the gate an agent runs
in front of [`set`](#aontu-model-set), from a document that is itself aontu.

```
aontu allow --role <role> [--at <path>] [--format text|json]
            <roles-file> <path>...
```

- **The role model is an aontu document**: one entry per role, each
  carrying `allow` (the subtrees it may modify) and optionally `deny`
  (the ones it may not), as path strings. The map lives at `$.roles`
  unless `--at` names another path, and a role is whatever identifier
  its author writes.
- **A path is allowed when an `allow` entry is at or above it.** Being
  allowed `$.services` allows `$.services.auth` and
  `$.services.auth.replicas`; it does not allow `$`, because a change
  at the root reaches every sibling too.
- **A path is refused when a `deny` entry is at, above or below it,
  whatever the order.** Denied `$.services.*.tier` refuses
  `$.services.auth.tier`, and refuses `$.services.auth` and
  `$.services` as well, because a change at either could rewrite the
  tier. Deny wins over allow however the entries were written.
- `*` in a path matches any one key. It is the only pattern character;
  every other segment is a map key or a list index compared for
  equality, as a reference compares them.
- A role with no `allow` list allows nothing, and so does a role the
  model does not declare: the verdict is `refused`, and a `no_path`
  finding at the role's path names the nearest declared role when one
  is close.
- Every asked path is answered, and the verdict is `allowed` only when
  every one of them is. Each answer names the entry that decided it as
  a path into the role model, so [`aontu model why`](#aontu-model-why) locates the
  rule and the line that wrote it.
- Every path starts with `$`, and may be spelled as `set`'s
  assignment, `<path>=<value>`, so a skill can hand the gate the very
  arguments the write will get. The value must be one value: `set`
  appends it as source after the flattened path, so a value carrying
  a second pair (`3 secrets: key: "x"`) would write a sibling of the
  overlay root, a subtree the gate was never asked about. Such an
  argument, an empty one, or a second filename in a path's place is
  a usage error, exit 2.
- `--format json` emits `{aontu, findings, paths, role, verdict}`. Each
  entry of `paths` carries `path`, `allowed` and `reason` (`allow`,
  `deny`, `uncovered` or `no_role`), plus `by` and `pattern` when an
  entry decided it.
- Exit codes: `0` allowed (every path), `1` refused (at least one
  path, or a role the model does not declare), `2` usage, `4` the role
  model does not stand up on its own, in which case the engine's own
  finding follows the verdict after a blank line.

The shape of a role is aontu too. The model meets it at evaluation,
as data meets a schema under [`vet`](#aontu-vet): a spread template
over the roles map, `roles: { &: { allow: [&: Entry] deny?: [&:
Entry] } }` where `Entry` is `string & re("^[$]") & re("[^.]$")`, so
a malformed role (`allow: "$.a"`, `deny: [1]`, an entry that is empty
or does not start at `$` or ends in a dot, a roles map that is a
number) is refused with the engine's own code and site, exit 4. A
role model that `close()`s its role vocabulary must declare `deny?`
in it, or the template's optional key is refused as `[aontu/closed]`
and no role can be asked about. The lists are read from the written
tree rather than the generated document, so a `hide()`d `deny` still
denies; each entry must be one concrete string, and a kind (`string`)
in an entry's place is refused as `no_gen`.

Three limits follow from what the gate compares:

- A key that contains a dot is unreachable, as it is for
  [`get`](#aontu-model-get): an asked path and an entry are both split at
  every dot, quotes included, so neither side can name such a key. A
  role is one key, looked up as written and never split, and the
  command refuses a dotted role name, because the entry paths it
  reports could not then be followed by `why`.
- The gate answers about the path, and says nothing about where the
  value is written. A path reached through a reference is `set`'s
  business: the append lands at the named path, and `--in-place` is
  refused there.
- The verb is TypeScript-only for now: the Go CLI does not have it.

Write a `roles.aon` that declares three roles:

<!-- test: scenario allow -->
<!-- test: file roles.aon -->
```aontu
roles: admin: allow: ["$"]
roles: dev: {
  allow: ["$.services" "$.deploy.*.replicas"]
  deny: ["$.services.*.tier"]
}
roles: qa: allow: ["$.tests"]
```

`dev` may change any service, and the replica count of any region:

<!-- test: run -->
```sh
$ aontu allow --role dev roles.aon $.services.auth.replicas $.deploy.eu1.replicas
verdict: allowed
role: dev
$.services.auth.replicas: allowed by $.roles.dev.allow.0 ($.services)
$.deploy.eu1.replicas: allowed by $.roles.dev.allow.1 ($.deploy.*.replicas)
```

A service's tier is denied, and so is the service above it, because a
change there could rewrite the tier:

<!-- test: run -->
```sh
$ aontu allow --role dev roles.aon $.services.auth
verdict: refused
role: dev
$.services.auth: refused by $.roles.dev.deny.0 ($.services.*.tier)
$ echo $?
1
```

A role the model does not declare may change nothing, and the finding
says which path was looked for:

<!-- test: run -->
```sh
$ aontu allow --role ops roles.aon $.services.auth
verdict: refused
role: ops
$.services.auth: refused (role ops is not declared)

$.roles.ops: no_path [reference]
  The role ops is not declared at $.roles in this document.
$ echo $?
1
```

The deciding entry is a path into the role model, and `why` names the
line that wrote it:

<!-- test: run -->
```sh
$ aontu model why $.roles.dev.deny.0 roles.aon
$.roles.dev.deny.0 = "$.services.*.tier"
  1. "$.services.*.tier"  roles.aon:4:10
```

### `aontu agentsmd`

Generate the AGENTS.md stanza for a definition: the prose entrypoint,
derived from the formal source so it cannot drift from it.

```
aontu agentsmd [--write <AGENTS.md>] [--depth <n>] <file.aon>
```

The stanza names the document, its [canon-hash](#aontu-hash) pin, its
root keys and its shape, spells the `get` / `why` / `vet` / `set`
commands with a path that actually exists in it, and points at
[`aontu help language`](#aontu-help) for the language the document is
written in. `--write` splices it into a file between
`<!-- aontu:begin -->` and `<!-- aontu:end -->`, appending the markers
when they are absent: everything outside them is left exactly as it
was, so the verb is safe to re-run and safe to point at a file someone
else writes prose in.

`--depth <n>` is how deep the **shape** line projects, default `2`.
Two levels name the root keys and say `top` under them, which says
what the document is about rather than what is in it; `--depth 4` on
an entity map reaches the fields. The default is unchanged because the
stanza is spliced into a file people read.

Exit codes: `0` generated, `2` usage, `4` the document does not stand
up on its own.

### `aontu fmt`

The source formatter, in the tradition of `gofmt`: one agreed form for
aontu source, so that layout is never argued about and a diff shows
only what changed.

```
aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>]
          [--profile <file>] <file>...
aontu fmt < in.aon > out.aon
```

| option | does |
|---|---|
| (none) | print the formatted text; one file, or standard input |
| `-w`, `--write` | rewrite each file in place, when its form would change |
| `-l`, `--list` | print the name of each file whose form would change |
| `--check` | like `--list`, and exit 1 when any would: the CI gate |
| `-d`, `--diff` | print a unified diff for each file whose form would change |
| `--lint` | report the style findings, key case and repeated shapes, on standard error, and print nothing else |
| `--strict` | `--lint`, and exit 1 when there is a finding |
| `--marker <t>` | the file is a generator, and this is its marker (default `//-`, and `#-` `---` `/*-` `<!---` by extension) |
| `--profile <f>` | a profile file, whose `template.ext` names the extensions it marks and `template.marker` the marker |

- **The form.** Two-space indentation. `key: value`, the colon tight
  to the key. No commas between entries (a call's argument list keeps
  them). Braces only where the language needs them: a one-pair map is a
  chain, `a: b: c: 1`, and a one-key map in a list is a pair element,
  `[a:1 b:2]`. A container on one line when it fits 80 columns, padded
  inside braces and with the colons tight, `{ a:1 b:2 }`, and as a
  block when it does not. Keys bare where they can be; a single-quoted
  string double-quoted unless it holds a double quote; numbers as
  written. Every comment and every blank line between groups stays.
  The formatter never breaks a line, and keeps the author's line breaks
  inside an expression, at their operators.
- **The prefix is repeated.** A map that does not fit on one line is
  written as one statement per entry, each carrying its key again:
  `server: host: "0.0.0.0"` / `server: port: 8080`. A key written
  twice is a meet, so the two spellings are one document. The prefix
  reaches through nested maps and stops at a RECORD (a map of several
  entries, all of them values) which is written as a braced block
  under the prefix instead, `field: id: {` and its facts one level in.
  Adjacent statements naming one key are the same map to the
  formatter, and are written as one line when that fits. Only a plain
  map in statement position: a map that is an argument, an operand or
  a list element keeps its braces, because splitting it would change
  the document.
- **It reads the file it is given and no other.** An `@"..."` include
  is a token like any other, so `--trust` has nothing to confine in
  it. The verb does take the flag, and it governs the `--profile`
  document, which is evaluated: `--trust none` beside a profile that
  includes a file refuses with `include_denied`.
- **A new tree at the top level stands apart.** One blank line above a
  top-level statement that takes more than one line to write, and one
  below it, above its own comments so that a note travels with what it
  describes. What counts as a tree is measured rather than guessed: the
  statement did not fit on one line. `a: 1` beside `b: 2` is left where
  it is, and the rule is the root's alone; below it a blank line is the
  author's.
- **A generator is formatted as the document it carries.** A file whose
  extension is not `.aon` is a generator written in the target's own
  syntax ([`aontu template`](#aontu-template)), as it is for `trace`:
  it is desugared, formatted and resugared, so what comes back is a
  generator. The marker stands at the left margin with the aontu
  indented **after** it, so the tree the marker lines carry has a shape
  on the page, and every line of output is held on a line of its own,
  which the packing budget would otherwise fold three strings into.
  `--marker` names the marker for a language the table does not know.
  A file with no marker line in it is another language's, a `.json`,
  `.yaml` or `.toml` include, and is refused by name, exit 2.
- **It checks its own work.** Before a byte is returned the formatted
  text is parsed again and compared with the input, tree to tree; a
  disagreement is refused as the formatter's own defect
  (`format_check`), and nothing is written. Each repeated or merged
  statement is also evaluated both ways in isolation, and a rewrite the
  engine evaluates differently is not made: that statement keeps its
  braces.
- **It points at style, and touches nothing.** `--lint` reports on
  standard error, one line per finding as `file:line:col: rule:
  message`, and changes neither the document nor the exit code.
  `style/key-case` is a bare key holding an underscore or beginning
  with two capitals, `credit_cents`, `HTTP_PORT`, with the spelling
  that would follow the form, `creditCents`, `httpPort`; a quoted key
  that must stay quoted is a deliberate spelling. `style/repeat` is a
  map or list whose shape is written two or more times in the file
  and is 40 columns or wider, reported once, at its first site, with
  the other sites, because a value written twice can drift and an
  alias names it once. A chain and the braces it stands for are one
  shape, the order of a map's entries is not part of it, and a repeat
  inside a repeat is the outer one's. `--strict` is `--lint` with
  exit 1 when there is a finding.
- With no file it reads standard input; with several files it needs
  `--write`, `--list`, `--check`, `--diff` or `--lint`, rather than
  print them as one stream.
- Exit codes: `0` formatted or clean, `1` a `--check` file would
  change or a `--strict` finding, `2` usage, `4` a document does not
  parse.

A configuration written as it came from JSON, `config.aon`:

<!-- test: scenario fmt -->
<!-- test: file config.aon -->
<!-- fmt: keep the input the transcript formats -->
```aontu
{
  "server": { "host": "0.0.0.0", "port": 8080, "tls": { "enabled": true, "cert": "/etc/tls/cert.pem" } },
  "features": ["auth", "metrics"],
  "limits": { "rps": 100, "burst": 200 }
}
```

<!-- test: run -->
```sh
$ aontu fmt config.aon
server: host: "0.0.0.0"
server: port: 8080
server: tls: { enabled:true cert:"/etc/tls/cert.pem" }

features: ["auth" "metrics"]
limits: { rps:100 burst:200 }
```

The formatted text is the same document: `aontu hash` of the two
agrees, and formatting the formatted text changes nothing.

### `aontu template`

Read a generator written in the **target's own syntax**, and print the
aontu it means.

<!-- test: skip the synopsis is not a transcript -->
```sh
aontu template [--resugar] [--check] [--marker <token>]
               [--profile <file>] <file>
```

**One rule: a marked line is aontu source, and every other line is a
line of output.** The marker is the target's comment token plus a
dash (`//-`, `#-`, `---`, or a block form such as `/*- … */` and
markdown's `<!--- … -->` where the language has no line comment) so the
file stays valid in its own language, an editor highlights it, and the
target's compiler parses it.

**A language the table does not know says so once.** `--marker` names
the marker for one call; a profile names it for every call, because a
profile is a language declared as data and `aontu template` and
`aontu fmt` read the same file. A marker carries its own closer after a
space when the opener does not imply one:

<!-- test: skip the file it reads is the reader's own language -->
```aon
@"aontu:profile"

aontu: Lang: lang: "ocaml"
aontu: Lang: indent: { unit:" " width:2 }
aontu: Lang: template: { marker:"(*-" close:"*)" ext: ["ml" "mli"] }
```

<!-- test: skip the synopsis is not a transcript -->
```sh
aontu template --profile ocaml.aon unit.ml
```
Write a `greet.ts`:

<!-- test: scenario template -->
<!-- test: file greet.ts -->
```typescript
//- who: { world: {}, moon: {} }
//- svc: $.who & pack($.who, { name: key() })
//- out: emit($.svc, {
//- match: { name: string }
//- body: [file("greet-" + .name + ".ts", emit([_], {
//- match: { name: string }, replace: { NAME: .name }, body: [
export function greet() {
  console.log(`hello, NAME`)
}
//- ]}))]
//- })
```

The three unmarked lines are the output. They are ordinary TypeScript,
indented where they belong, and **a value reaches them through
`replace` rather than through a hole**: `NAME` is a string the body
already holds, and there is no delimiter to collide with the target's
own syntax: the backtick template literal above survives untouched. The
inner dispatch is what makes `replace` reach those lines: a rule
substitutes into the body it wrote, so the lines of a file and the map
that names the file are two rules, not one.

**The verb prints the canonical form**, which is what the marker lines
mean once the output lines are quoted:

<!-- test: run -->
```sh
$ aontu template greet.ts
who: { world: {}, moon: {} }
svc: $.who & pack($.who, { name: key() })
out: emit($.svc, {
match: { name: string }
body: [file("greet-" + .name + ".ts", emit([_], {
match: { name: string }, replace: { NAME: .name }, body: [
`export function greet() {`
"  console.log(`hello, NAME`)"
`}`
]}))]
})
```

Each output line is one string, and **the quote is chosen per line**: a
backtick, which carries `"` and `'` without escaping, unless the line
holds a backtick itself, in which case the double quote is used and `"`
is escaped. A backslash is escaped in either.

**Every verb that reads a generator reads the template directly**, so
the canonical form is something to look at rather than something to
keep. [`aontu trace`](#aontu-trace) answers over the file the author
edits:

<!-- test: run -->
```sh
$ aontu trace greet.ts
greet-moon.ts	$.0	$.who.moon	#0
greet-moon.ts	$.0.children.0	$.who.moon	#0
greet-moon.ts	$.0.children.1	$.who.moon	#0
greet-moon.ts	$.0.children.2	$.who.moon	#0
greet-world.ts	$.1	$.who.world	#0
greet-world.ts	$.1.children.0	$.who.world	#0
greet-world.ts	$.1.children.1	$.who.world	#0
greet-world.ts	$.1.children.2	$.who.world	#0
```

**`--resugar` is the other direction**, and `--check` is the round trip
between them: it holds the file to the spelling the two transforms
answer, and names the first line that is not it. What that catches is a
marker line the transform would not have written: one without its space,
or one indented to match the code around it, since the marker stands at
the left margin with the aontu indented after it. **A template's
whitespace is output**, so its bytes are the artifact: a body line's
trailing space shows up as a changed byte in the generated tree, which
is what a drift check against the committed files catches.

[`aontu fmt`](#aontu-fmt) writes that spelling, and formats the aontu
the marker lines carry while it is there.

<!-- test: run -->
```sh
$ aontu template --check greet.ts
```

The round trip is a **fixpoint**, not a table of escapes: a canonical
line becomes an output line only when desugaring the rebuilt line
answers the canonical line back. A line that could not survive (one
beginning with the marker itself) fails that test and stays aontu, which
is how a generator emits its own marker with no new syntax.

Exit codes: `0` written, `1` a `--check` file that is not what the
round trip answers, `2` usage or I/O.

### `aontu trace`

Ask **what wrote this line**. Every piece a rule stamped under the
component tree, with the file it reached, the model node the dispatch
matched, and the rule set that wrote it.

<!-- test: skip the synopsis is not a transcript -->
```sh
aontu trace [--at <path>] [--format json] [--marker <token>]
            [--profile <file>] <file>
```

A generator answers a tree of files, and a reader looking at one line
of the output has no way back to the rule that produced it. This is
that way back. The anchor is `$.out` unless `--at` names another.

<!-- test: skip the document it reads is the reader's own generator -->
```sh
$ aontu trace gen.aon
handlers/chat.ts	$.0.children.0	$.services.chat	$.%handler#0
```

Four columns: the **file**, the **address** of the piece in the
document, the **model node** the dispatch matched, and the **rule**.
`--format json` answers the same entries as one object.

**A rule read through a name is addressed by it.** `$.%handler#0` is
the first template of the `%handler` rule set. A table written inline
at the call has no address of its own and is `#0`, `#1` and so on, so
the two cases are told apart by whether an address precedes the hash.

**A piece that reached no file is not traced.** The tree is what the
entries attribute to, so a rule whose output never landed in a file has
nothing to name.


### `aontu render`

Write the files a generator answers.

<!-- test: skip the synopsis is not a transcript -->
```sh
aontu render [--check] [--at <path>] [--format json] [--marker <token>]
             [--profile <file>] <file|folder> <path>
```

A generator answers a **component tree** (`file`, `folder`, `line` and
the rest) as an ordinary value at `$.out`. `render` hands that tree to
[jostraca](https://github.com/jostraca/jostraca), the generator runtime
both implementations depend on, and jostraca writes the files. aontu
decides which files exist and what each line of them is; the runtime
decides how the bytes reach a disk. Write a `gen.aon`:

<!-- test: scenario render -->
<!-- test: file gen.aon -->
```aontu
foo: "BAR"

out: file("zed.txt", ["foo = " + $.foo])
```

**A tree that is one file is written to `<path>` itself**, under that
name, unless `<path>` is a directory that already exists:

<!-- test: run -->
```sh
$ aontu render gen.aon zed.txt
```

Nothing is printed when the write succeeds, unless a file was skipped
(below). `--format json` reports the files written, in the seven groups
the runtime sorts them into, and an eighth aontu reads from the run's
own record:

<!-- test: run -->
```sh
$ aontu render --format json gen.aon zed.txt
{
  "aontu": {
...
  "files": {
...
    "unchanged": [
      "zed.txt"
    ],
    "written": []
  },
  "verdict": "ok"
}
```

**A file the runtime declines to touch is named as skipped.** A copy on
disk carrying the `JOSTRACA_PROTECT` marker is left as it is, so a hand
edit survives the next run. Those seven groups say what was done to a
file, and nothing was done to this one, so aontu reads the run's own
record under `.jostraca/` and reports `skipped: <path>` in text,
or the `skipped` group in JSON. `--check` still counts it as `content`
drift: the bytes differ from what the generator answers, whoever chose
that.

**Any other tree is written below `<path>`**: a `project`, a `folder`,
or a list of files, with the paths the tree spells. A one-file tree
that should land in a directory names the file: `aontu render gen.aon
build/zed.txt`.

**A folder is a set of generators.** Every regular file directly in it
is one (a name beginning with a dot is not), taken in name order: a
`.aon` as it is, any other file by its marker, as below. Their trees are written below
`<path>` as one run, so one `--check` holds the whole set, and two
generators claiming one path are refused by the runtime. A file with no
marker line in it is refused by name rather than skipped. Write a
`gen/a.aon`:

<!-- test: file gen/a.aon -->
```aontu
out: file("a.txt", ["a"])
```

and a `gen/b.rb`, a generator in the target's own syntax:

<!-- test: file gen/b.rb -->
```ruby
#- out: folder("lib", [file("b.rb", [
puts "b"
#- ])])
```

<!-- test: run -->
```sh
$ aontu render gen out
$ aontu render --check gen out
```

`out/a.txt` and `out/lib/b.rb` are on disk, `a.txt` under its own name:
in a set the one-file rule above does not apply.

**`--check` is the CI form.** Nothing is written; `<path>` is compared
with what the generator writes, one `kind: file` line per difference
(`content`, `missing`, or `mode` where the tree declared one), and the
exit code is 1 on drift:

<!-- test: run -->
```sh
$ aontu render --check gen.aon zed.txt
```

Edit the file by hand, as `zed.txt`:

<!-- test: file zed.txt -->
```text
foo = edited
```

<!-- test: run -->
```sh
$ aontu render --check gen.aon zed.txt
content: zed.txt
$ echo $?
1
```

**A template entry is read directly.** As [`aontu trace`](#aontu-trace)
does, `render` reads a `<file>` whose extension is not `.aon` as a
generator in the target's own syntax (see
[`aontu template`](#aontu-template)), desugared by the marker its
extension names, `--marker`, or a profile's. `--at` names another
anchor than `$.out`.

Beside the files it writes, jostraca keeps a record of its own in a
`.jostraca/` folder under the output directory (for a one-file render,
the directory that holds the file), with a `.gitignore` in it. That
folder, and what the runtime does with a file that already exists, is
jostraca's contract; [Trust and determinism](/docs/trust#clause-4-sandboxing)
records what stays aontu's.

Exit codes: `0` written or clean, `1` `--check` drift, `2` usage or
I/O (a path that cannot be made, a `fragment` whose source is not
there), `4` the document does not stand up, or `--at` names nothing.


### `aontu hash`

The canon-hash: one string that pins what a document *means*, so a
lockfile, a registry or an agent can say "this module, this meaning"
and have the claim survive reformatting.

```
aontu hash [--form] [--format text|json] <file.aon>
```

- The hash is
  `"aon1-" + base64url(SHA-256(UTF-8(hcanon(unify(file)))))`, where
  `hcanon` is the **hash form**: see below. `aon1-` is a scheme id, so
  a future semantically stronger normal form is an upgrade rather than
  a breakage.
- The document is evaluated **standalone**: its own `@"file"` closure
  resolved and unified at its own root, before any consumer context.
  That is what makes the pin transitive: an edit two includes deep
  changes the unified root, hence the hash.
- **The pin survives** comments, whitespace, formatting, key
  reordering, and splitting one file into several includes: any
  refactor that leaves the unified value identical. **It breaks on**
  any semantic change in the transitive closure: a default flipped, a
  field added, a map closed, a constraint tightened.
- `--form` prints the hashed TEXT instead of the digest, which is what
  to diff when a pin moves. `--format json` prints both under
  `hash` and `form`.
- Exit codes: `0` hashed, `2` usage, `4` the document does not
  evaluate on its own: a broken document has no meaning to pin, and a
  hash of the wreck would agree with every other wreck.

To see the pin hold still, write `svc.aon`:

<!-- test: scenario hash -->
<!-- test: file svc.aon -->
```aontu
service: { name:"checkout" port: *8080|integer }
```

and `svc-reformat.aon`, the same meaning re-ordered under a comment:

<!-- test: file svc-reformat.aon -->
<!-- fmt: keep the reordered spelling the hash survives -->
```aontu
# the same meaning, reordered and commented
service: port: *8080 | integer
service: name: "checkout"
```

<!-- test: run -->
```sh
$ aontu hash svc.aon
aon1-nSY9noXFhWc_dtcRrErhCS9bZVtNfTJb0vVoCE9W1CM
$ aontu hash svc-reformat.aon
aon1-nSY9noXFhWc_dtcRrErhCS9bZVtNfTJb0vVoCE9W1CM
$ aontu hash --form svc.aon
{"service":{"name":"checkout","port":*8080|integer}}
```

Two spellings, one meaning, one pin, and `--form` prints the exact
text the digest is taken over.

**The hash form (`hcanon`)**

Exactly the unify-level [canon](#val-typescript) with the two
additions that close its semantic gaps:

| | canon | hash form |
|---|---|---|
| a closed map or list | `{"a":1}` | `close({"a":1})` |
| a `type`- or `hide`-marked value | `1` | `type(1)`, `hide(1)` |

Both reuse existing parseable syntax, so the hash form is itself valid
aontu source and round-trips: `hcanon(unify(parse(hcanon(v)))) ==
hcanon(v)` is asserted for every row of `test/spec/hcanon.tsv`, in both
implementations. Marks propagate to every descendant at unification, so
a wrapper is emitted only where a mark *starts*. User-facing `canon` is
unchanged.

This is a *canonical-text* hash, not a hash of semantic equivalence
classes: canon is deterministic syntax, not a unique normal form, so
`number|integer` and `number` denote the same value set and hash
differently. The failure direction is the safe one: a false "changed"
forces a needless re-review, while a false "unchanged" is impossible
provided the hash form is semantically complete, which is exactly why
the `close`/mark additions are part of the definition rather than an
optimisation.

### `aontu sync`

Make the project correct: resolve its declared dependencies by minimum
version selection, fetch what no local store holds, write the lockfile,
materialise the vendor tree, and verify every pin. It is idempotent, and
it is the one package verb a reader needs to know.

```
aontu sync [--frozen] [--base <url>]... [--format text|json] [dir]
```

`dir` is the project root, the directory holding `pkg.aon`, and defaults
to the working directory.

**What a project declares.** `pkg.aon` names the package and what it
depends on. A dependency is a minimum version; an `alias:<name>` entry
holds a second version of one package under a name the imports use:

```aon
pkg: { path:"corp.example/checkout" main:"main.aon" }

dep: "corp.example/schemas/service": v: "1.4.2"
dep: "alias:legacy": { pkg:"corp.example/schemas/service" v:"1.2.0" }
```

**Resolution is minimum version selection.** Every package is taken at
the highest of the minima anyone in the closure asked for, and never
higher, so a resolve is reproducible and adding one dependency cannot
move another. The closure is walked from the project's own file through
each dependency's `pkg.aon`, fetching a package the stores lack as it is
reached.

**What a fetch checks, in order.** The repository is trusted for
availability and for nothing else. For each package the client reads the
version list, then the manifest, then the proof, then the archive, and
refuses at the first check that does not hold:

1. the manifest is well formed and names the package and version asked
   for;
2. the proof signs the manifest's digest, by a signer the project's
   trust configuration accepts for that name;
3. the archive's digest is the one the manifest declares, before a byte
   of it is parsed;
4. every file in the archive has the digest and size the manifest lists,
   no file is missing and none is extra, every path obeys the element
   rules (at most 32 elements, none a name a platform reserves such as
   `con` or `nul`), and nothing outside the allowlist is present;
5. the module, evaluated standalone with its own dependencies at the
   minima it declares, means what the manifest's canon-hash pins.

A refusal names its code and the package, and nothing is written:

```
verdict: refused
fetched: corp.example/schemas/common 1.0.0
refused: archive_digest_mismatch: the archive for corp.example/schemas/service 1.4.2 is sha256:45e3…, not sha256:9127…
```

**The lockfile pins three things.** `aontu_meta/pkg-lock.aon` is one
canonical line, and each entry carries the version, the canon-hash of
the module's meaning, the digest of its canonical archive and, for a
package acquired from a repository, the digest of its signed manifest:

<!-- fmt: keep a lock file, shown as the tool writes it -->
```aon
# pkg-lock.aon (generated by `aontu sync`; do not edit)
{"lock":{"corp.example/schemas/service":{"archive":"sha256:9127…","canon":"aon1-zFHn…","manifest":"sha256:f72c…","v":"1.4.2"}}}
```

**The vendor tree is the build.** `aontu_meta/vendor/<package-path>/`
holds every package of the closure as a real copy, one directory per
`/`-element, uppercase escaped as `!x`, with the served manifest and
proof kept beside it under the package's own `aontu_meta/`. A synced
project evaluates with no cache and no network. Commit the lockfile
and the vendor tree together.

**`--frozen` is the CI mode.** It resolves, fetches what a locked
version needs, and refuses to change the lockfile: a dependency the
lock does not name, a version that would move, a pin that would be
recomputed, all exit 1 and name themselves as `lockfile would change`.

**Where packages come from.** `repo` in `pkg.aon` is the project's trust
configuration, and it travels with the project:

```aon
repo: base: ["https://pkg.aontu.dev"]
repo: private: ["corp.example/*"]
repo: private_base: ["https://pkg.corp.example"]
repo: trust: "corp.example/*": { signer:"ed25519:q520…" inclusion:none }
```

`base` lists the repositories to read from, in order; `--base <url>`
on the command line replaces the list. A base is `https`, or `http` on a
loopback host, which is how a local `aontu pkg serve` is reached. A name
matching `private` is never sent to a public base: it is read from
`private_base`, or refused when none is configured. `trust` maps a
pattern (a package path, a path followed by `/*`, or `*`) to the signer
accepted for it: a named Ed25519 key, or `forge` for a signing identity
proved through Sigstore. The default entry, `*`, names the forge signer
and requires log inclusion. This build verifies key proofs; a name whose
entry names the forge is refused rather than accepted unverified.

**Cooldown.** A version is selectable by `get` and `outdated` only once
the repository has held it for 72 hours, timed from the repository's
own first-seen time, and a version that a later version retracted is
never selected. A version named explicitly, in `pkg.aon` or on the
command line, is taken as it is; a private name skips the cooldown.

**Exit codes.** `0` the project is correct; `1` a refusal, a frozen
lockfile that would change, a missing package or a pin that does not
hold; `2` usage; `4` a module in the store that does not evaluate on its
own.

`--format json` prints the report: `verdict`, `fetched`, `lock`,
`vendored`, `missing`, `unevaluable`, `forbidden`, `mismatched`,
`unlocked`, `changes`, `events` and, on a refusal, `refusal` with its
`code`, `message` and `pkg`.

### `aontu add`, `aontu get`, `aontu remove`

Change what the project depends on, then sync.

```
aontu add <pkg> [dir]
aontu get <pkg>[@<version>] [dir]
aontu remove <pkg> [dir]
```

- **`add`** takes on a dependency the project does not have. It refuses
  one already declared and names `get`.
- **`get`** adds a dependency or raises its minimum: the superset of
  `add`. Without a version it takes the newest selectable version.
- **`remove`** drops a dependency and the vendor tree it held.

Each edits `pkg.aon` by the smallest text change that keeps the file the
author's: a line appended, a version literal rewritten where it stands,
a one-line entry removed. An entry the verb cannot edit that way is left
to the author, and the verb says so. Each then runs a full `sync`, and a
change the sync cannot carry is taken back, so neither leaves the
project half-changed:

```
$ aontu get corp.example/schemas/service@1.4.3
verdict: ok
change: raised corp.example/schemas/service 1.4.2 -> 1.4.3
fetched: corp.example/schemas/service 1.4.3
corp.example/schemas/service 1.4.3 aon1-JstX…
```

Exit codes are `sync`'s, plus `2` for a spelling the verb cannot act on.

### `aontu why`

Why is this package in the closure? Every chain of dependencies from
the project to it, read from the lockfile and the package files in the
store. No network.

```
aontu why <pkg> [--format text|json] [dir]
```

```
$ aontu why corp.example/schemas/common
verdict: ok
corp.example/checkout -> corp.example/schemas/service -> corp.example/schemas/common
```

Exit `0` when a chain exists, `1` when the package is not in the
closure.

### `aontu publish`

Publish this package. A dry run without `--yes`.

```
aontu publish [--yes] [--key <file>] [--token <file>] [--to <dir>]
              [--write <url>] [--against <dir>] [--format text|json] [dir]
```

A package declares its path, its version and its entry in `pkg.aon`,
and whether it may leave the machine:

```aon
pkg: { path:"corp.example/schemas/service" version:"1.4.2" main:"service.aon" }
publish: public
```

`publish` defaults to `private`, and a private package is refused by a
public write path; a project-level `publish: public` is what allows it
out.

**What a publish sends** is the manifest, its proof, and the canonical
archive of the source tree. The archive holds exactly what the allowlist
admits: aontu source, the data formats the include table reads, `.md`
and `.txt`, `LICENSE` and `NOTICE`, and nothing under `aontu_meta/`. It
is a zip whose entries are sorted, stored uncompressed and undated, so
one tree has one digest in both implementations. It is held to the caps
every consumer applies at acquisition (16 MiB compressed, 64 MiB of
files, 4096 files, 8 MiB a file) before it is minted, so nothing
leaves the machine that every consumer would refuse; the package path
and version in `pkg.aon` must be a package path and a version, and the
entry must be a path inside the tree.

**The gate runs first.** The highest version the repository already
holds is fetched, checked as any acquisition is, and the candidate is
compared against it. Compatibility has three components, and all
three must hold: **acceptance**, every document the old version
admitted the new one admits, which is the subsumption query's
[`subsume`](#aontu-subsume) with its findings; **determination**, every
position the old version resolved to a value with nothing supplied the
new one still resolves (`compat_undetermined`, as when `port: 8080`
loosens to `port: integer` and a consumer who supplied nothing had a
value and now has an error); and **agreement**, where both resolve a
position they resolve it to the same value (`compat_outcome_changed`).
A change that fails any of them is refused, and there is no major
version to bump past the gate; a breaking change ships as a new
package path, and the old path's last version declares
`moved: <new path>`. `--against <dir>` names a prior tree to gate
against instead.

```
$ aontu publish --key key.pem
verdict: dry-run
corp.example/schemas/service 1.4.3 public
archive: sha256:b4b8… (2 files, 1006 bytes)
module: corp.example/schemas/service service.aon aon1-JstX…
file: pkg.aon sha256:bc26… 133
file: service.aon sha256:0188… 663
digest: sha256:acb6…
signer: ed25519:q520…
against: corp.example/schemas/service 1.4.2
write: https://publish.aontu.dev/v1/publish
dry run: nothing sent (add --yes)
```

**The proof.** `--key <file>` names a PKCS#8 PEM Ed25519 private key;
any other kind of key, or a file that is not a PEM private key, is
refused `key_invalid` before anything is signed. The proof signs the
manifest's digest under it, and the signer's id,
`ed25519:` followed by the public key, is what a consumer names in its
`trust` entry. `--token <file>` carries the forge's OIDC token to the
write path, which decides admission from it; the token's claims are
copied into the manifest as its `publisher` block.

**`--to <dir>`** writes the read-path layout straight into a directory
instead of sending anything: the archive, manifest and proof under
`pkg/<path>/@v/`, the version list and `@latest`, and the advisory
derived from `retract` declarations. That directory is a repository,
which `aontu pkg serve` serves and a consumer reads over a loopback
base. `--write <url>` names another write path.

**Exit codes.** `0` sent or dry run; `1` refused, or breaking; `2`
usage; `3` the gate is undecided; `4` the package cannot be minted.

### `aontu pkg`

The remaining package operations, each the right verb when you want
exactly that step and no other.

```
aontu pkg tidy     [--format text|json] [dir]
aontu pkg verify   [--format text|json] [dir]
aontu pkg vendor   [--format text|json] [dir]
aontu pkg manifest [--against <dir>] [--format text|json] [dir]
aontu pkg refreeze [--format text|json] [dir]
aontu pkg tree     [--format text|json] [dir]
aontu pkg outdated [--base <url>]... [--format text|json] [dir]
aontu pkg serve    [--listen <addr>] [--upstream <url>]... [dir]
aontu pkg keygen   <file>
```

**`tidy`** resolves the closure against the local stores and rewrites
the lockfile, fetching nothing. A package the stores do not hold is
reported and **the lockfile is not written at all**: a partial lock
claims a closure that was never resolved. A package that is present but
does not evaluate on its own is refused the same way (`verdict: error`,
exit 4), because a pin computed from a module with no meaning is the
same string for every broken module.

**`verify`** asks whether every locked package still is, and still
means, what the lockfile pins, and **changes nothing**. It is the CI
gate. Bytes are checked before meaning: the archive digest and each
file against the kept manifest first, then the one evaluation and the
canon-hash. A pinned manifest the tree no longer keeps is a mismatch,
not a pass.

```
$ aontu pkg verify
verdict: mismatch
corp.example/schemas/service: pinned archive sha256:9127… but the store holds sha256:45e3…
```

Verdicts: `ok`; `mismatch`, a store no longer is or means what is
pinned; `unlocked`, the lockfile does not name a dependency the project
declares; `missing`, a locked package is in no store. Exit `0`, and `1`
for each of the three refusals: nothing to check is not a pass.

**`vendor`** copies every locked package from the stores into
`aontu_meta/vendor/`, as whole source trees, replacing whatever stood at
each destination. The cache is keyed by canon-hash, and a consumer's pin
is computed against its own closure, so `vendor` looks under that pin
and under the canon the repository's manifest for the locked version
pins.

**`manifest`** prints the manifest a publish would send, and gates it
with `--against <dir>` exactly as `publish` does: acceptance,
determination and agreement.

**`refreeze`** recomputes every canon pin and nothing else, which is
what a canonical-form change in the engine needs.

**`tree`** draws the locked closure as a graph, each node's edges read
from its own package file in the store.

**`outdated`** asks the repository, for every locked package, what the
newest selectable version is and what a resolution taking it would move
with it: minimum version selection walked through the repository's
manifests to the closure, so a dependency's own raises are listed too.
A pinned version that a later one retracted is named too; the lock keeps
working.

```
$ aontu pkg outdated
verdict: outdated
corp.example/schemas/common 1.0.0 -> 1.1.0
corp.example/schemas/service 1.0.0 -> 1.1.0
  corp.example/schemas/common 1.0.0 -> 1.1.0
corp.example/schemas/service 1.0.0: retracted by 1.1.0
```

**`keygen`** writes a new Ed25519 signing key to a file, as PKCS#8 PEM
and once only, and prints the signer id, `ed25519:` followed by the
public key, which is what a consumer names in a `trust` entry and what
`publish --key` signs under.

**`serve`** serves a repository directory over HTTP: what `publish --to`
wrote, byte for byte. With `--upstream <url>` it is a caching proxy in
front of another repository, fetching an object on a miss and keeping
it, and it says when it served a copy no upstream would refresh. The
default address is `127.0.0.1:8017`. A proxy relaxes nothing: every
consumer verifies what it serves as it verifies anything else.

**The user cache** is `$XDG_CACHE_HOME/aontu/pkg` where that is set,
otherwise `~/.cache/aontu/pkg` (`%LOCALAPPDATA%\aontu\pkg` on
Windows), and holds three trees: `download/<package>/@v/` keyed by
package and version, `store/<canon-hash>/<package>/` keyed by canon-hash
and package path, and `seen/<package>/`, the client's own first-seen
records, from which a repository that drops a version this client saw
is detected. Under a root trust capability the cache is not consulted at
all: a confined run reads the vendor tree only, and the verbs that
write the cache refuse to run.

**`aontu_meta/` is where a project's generated state lives**: the
lockfile, the vendored closure, and whatever later tooling writes.
`pkg.aon` and the documents stay at the root, since they are authored;
nothing under `aontu_meta/` is. The verbs name an older layout, a
`mod.aon` or a root `mod-lock.aon`, once when they find it, and read
nothing from it.

- `--format json` prints every report as an object with the usual
  `aontu: {version, verb}` envelope and a `verdict`.

**REPL commands**

| Command | Effect |
|---------|--------|
| `:help` | show help |
| `:load <file>` | evaluate a document and hold it for the commands below |
| `:get [path]` | what the held document says at a path |
| `:keys [path]` | the keys at a path of the held document |
| `:why <path>` | every contribution to the value at a path |
| `:canon` | switch to canonical-form output |
| `:json` | switch to JSON output |
| `:quit`, `:exit` | leave (or press Ctrl-D) |

`:load` holds the document's **source**, not its evaluated tree (parsed
trees are single-use) so every later question re-evaluates from the text.
`:get` and `:keys` are the [query](#aontu-model-get) surface and `:why` is the
[provenance](#aontu-model-why) surface, answering about the held document.

**`--jsonl` makes the session machine-drivable**: no banner, no
prompt, and every command answers as one JSON line
(`{"ok":true,"out":"…"}`), so a harness can drive the REPL the way it
drives the CLI. Human-readable output stays the default.

```
$ aontu
aontu v0.56.0 REPL — :help for commands, :quit to exit
aontu> port: *8080 | integer
{
  "port": 8080
}
aontu> :canon
canon output
aontu> a:1|2|3
{"a":1|2|3}
aontu> :quit
```

### `aontu help`

Print the embedded teaching pack: the **language**, where `--help`
documents the **tool**.

```
aontu help [topic] [--format text|json]
```

With no topic it lists them. The corpus travels inside the binary, so
it answers with no network, no checkout and no documentation site,
which is the condition it exists for.

| topic | is |
|---|---|
| `tasks` | which verb does the job you have, indexed by the word you arrived with |
| `language` | the grammar card: everything the language spells, on one page |
| `examples` | the ladder, from plain JSON upward |
| `codes` | what a refusal means, and what to do about it |
| `grammar` | the published [ABNF](#the-published-grammar) |

The corpus is **generated** from [`docs/skill/`](https://github.com/aontu-lang/aontu/blob/main/docs/skill/) and
`grammar/aontu.abnf` by `ts/scripts/helpdoc.cjs` (`make helpdoc`, which
`make build-ts` runs), into `ts/src/helpdoc.ts` and
`go/cmd/aontu/helpdoc/`. Both suites assert the embedded copy is
byte-identical with its source, so the pack cannot drift from the
published files: a Go binary needs a copy inside its own package
directory, because `//go:embed` cannot read above one, and a generated
copy that nothing compares is a second source of truth.

`--format json` answers `{aontu, topics}` for the index and
`{aontu, source, summary, text, topic}` for a topic.

Exit codes: `0` printed, `2` an unknown topic (the topics are listed)
or a bad option.

### `aontu explain`

Explain one error code, from the same table the engine attaches to a
finding.

```
aontu explain <code> [--format text|json]
aontu explain --list [--format text|json]
```

Every code in [the registry](#behavioural-parity) resolves, so a code
read out of a report always answers:

```
$ aontu explain mapval_no_gen
code:  mapval_no_gen
class: incomplete

This value was present after unification, and cannot be generated
because it is not a literal value.
```

The list is the **registry**, not the hint table. The registry is in
cross-port parity (`test/spec/errcodes.tsv`, asserted set-equal with
the engine's class map in both ports), and listing from the hint table
would make the verb answer about something other than what either port
can report. Every registered code carries explanation text, and a gate
in both suites holds it so. A registered code carrying none would be
marked `(no text)` in the listing and say so when asked, rather than
printing an empty block.

The code may be written bare or with the `aontu/` prefix a report
prints in its brackets: `aontu explain constraint` and `aontu explain
aontu/constraint` answer identically, under the registered spelling.

A dynamic code is registered through the prefix it extends, and carries
that prefix's text: `func:upper` answers with the `func:` explanation,
because the suffix names the operator and the explanation is the
prefix's.

An unknown code exits 2 and names the nearest registered match.

Exit codes: `0` explained, `2` an unknown code or a bad option.

### `aontu init`

Write a working model, an instance of it, and a check script into a
directory.

```
aontu init [dir]
```

The reason this verb exists is that writing a **first** document is the
most expensive thing to get wrong. A model that reaches for `"*"`,
where the language spells the template
[`&:`](/docs/reference-language#spreads-), constrains nothing, and
[`vet`](#aontu-vet) over it reports `valid`. A known-good document
makes the next step an edit rather than an invention.

| file | is |
|---|---|
| `model.aon` | the truth: an entity map, constrained with `&:` |
| `data.aon` | an instance of it that holds |
| `check.sh` | the four checks to run after every edit, `vet --strict-coverage` first |

```
$ aontu init
model.aon
data.aon
check.sh

A model, an instance of it, and the four questions to ask.
Run the checks:  sh check.sh
Learn the language:  aontu help language
```

With no directory it writes into the working one, and it creates the
directory if it is not there. `check.sh` is written executable and
takes the binary from `$AONTU`, so a checkout with no installed `aontu`
runs it with `AONTU=./aontu sh check.sh`.

It **never overwrites**. If any member of the trio already stands in
the directory, it refuses before writing any of them, so a refused run
never leaves the directory half written.

The trio is **generated** into both ports from `docs/skill/init/` by
the generator that stages the teaching pack (`make helpdoc`), on the
[`aontu help`](#aontu-help) precedent. Both suites assert the staged
bytes are identical with their sources, and that the emitted documents
pass their own `check.sh`.

Exit codes: `0` written, `2` a standing file, a directory it cannot
write, more than one directory, or a bad option.

### `aontu lsp`

```
aontu lsp
```

The language server, over standard input and output: LSP, which is
JSON-RPC with Content-Length framing, until the client says exit. Both
builds serve it, byte-for-byte alike from a client's point of view;
editors launch it with no arguments beyond the verb, and `--help` is
the only option. The standalone `aontu-lsp` binary runs the same
server. What it reports, and the library beneath it, are on
[the LSP page](/docs/lsp); wiring a client is in
[wire your editor](/how-to/wire-your-editor).

### The MCP server

```
aontu mcp [--root <dir>]
```

A Model Context Protocol server over stdio (newline-delimited
JSON-RPC 2.0), the `mcp` verb of the npm build's CLI; the standalone
`aontu-mcp` binary of the package runs the same server. It follows the
language server's three-layer split ([docs/lsp.md](/docs/lsp)): the
tools and the protocol are a transport-free library
(`ts/src/mcp.ts`), the verb is stdio and nothing else.

| Tool | Answers |
|------|---------|
| `vet` | the [vet](#aontu-vet) report for a schema and a data document |
| `get` | the [query](#aontu-model-get) surface: a path, and a view of it |
| `why` | the [provenance](#aontu-model-why) record for a path |
| `diff` | what changed at which paths between two documents |
| `canon` | a document's canonical form |
| `summary` | the pin, the root keys and the top-tier shape: the first tier of progressive disclosure, expanded by calling `get` |
| `subsume` | the [subsume](#aontu-subsume) report: does the general document admit every instance the specific one admits? |
| `breaking` | the [breaking](#aontu-breaking) verdict (`compatible` \| `breaking` \| `undecided` \| `error`) plus the mode checked: the `mode` argument, else the document's own `$.aontu_policy.compat`, else `backward` |
| `set` | the [set](#aontu-model-set) report **plus the new overlay text**: assignments arrive as `{path, value}` pairs (with optional `inPlace`), and the server never writes files: the caller owns the write |
| `relations` | the [relations](#aontu-relations) report: acyclicity and inverse consistency over the entity edge set |
| `hash` | the [canon-hash](#aontu-hash) pin `{hash}` (plus the hash-form text when `form: true`) |
| `trim` | the [`trim --check`](#aontu-trim) report: redundant entries as paths |
| `reaches` | the [reachability check](#aontu-reaches): the verdict and, when it reaches, a shortest path: the closure question `relations` cannot ask one edge at a time |
| `view` | a [figure](#aontu-view) of the document as text: the tree, matrix, graph (mermaid, dot, er), layer, sets, layers, ladder, doc or lattice kind, with the loss report; the poset takes several files and is CLI only |
| `jsonschema` | the [JSON Schema export](#aontu-jsonschema): the schema, and the `lossy` list naming what it could not say: the bridge to a structured-output API, and to an MCP tool's own `inputSchema` |

Every tool returns **the same JSON contract the CLI prints**, so a
report read from one is the report read from the other. A tool that
*refuses* (an invalid document, a path that names nothing, a document
the served trust profile cannot read) answers with its own report and
`isError: false`, because the report is the answer; `isError` is
reserved for a call that could not be made at all (an unknown tool, a
malformed argument, a file argument the server cannot serve).

Served evaluation is **confined** ([the trust contract](/docs/trust)): the
source arrives from a caller, and `@"..."` is exactly what a server
must not run unconfined. By default every include is denied
(`{ include: 'none' }`). Started with **`--root <dir>`**, the server
takes the CLI's `--trust root:<dir>` posture instead: includes resolve
confined below the (realpath'd) root, and every tool's document
arguments gain `<name>Path` alternatives (`schemaPath`, `srcPath`,
`sourcePath`, `generalPath`, …) naming files below that root, checked
by the same realpath-then-prefix rule the include resolver applies, so
a symlink escape is an escape. Without `--root`, path arguments are
refused with `isError: true`; the `initialize` handshake's
`instructions` field says which mode the server is in, and
`tools/list` advertises the `<name>Path` properties only when they are
served. The package-resolver leg is enabled by neither posture.

The Go port ships no MCP server: its `aontu mcp` says so and exits 2.
Its role is embedding the same library calls, and `Get`, `Why`, `Diff`
and `AgentsMd` are in the Go API for that.

### The published grammar

Three files, one grammar. [`grammar/aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf)
and [`grammar/aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark) publish the
**emission surface** for constrained decoding;
[`grammar/aontu.abnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.abnf) says the same thing in
RFC 5234 notation, for a reader rather than a decoder, and is the one
the [language reference draws its railroad
diagrams](/docs/reference-language#the-published-grammar) from.

All three are conservative by construction (they accept less than the
parser does, never more) and all three deliberately exclude `@"..."`
includes, because generated documents should describe values rather
than reach for files.

The grammar is not a document that drifts: `ts/test/grammar.test.ts`
reads `aontu.gbnf` and `aontu.abnf`, interprets both, and requires each
to accept **every canonical-form output in the shared spec suite**. The
function-name list in all three, and in the TextMate grammar the
editors ship, is checked against the engine's own registry in both
directions.

### The skill

[`docs/skill/`](https://github.com/aontu-lang/aontu/blob/main/docs/skill/) holds the agent-facing sources: a trigger
stub, a task-to-verb index, a one-page grammar card, a JSON-first
example ladder, and the error-code index for repair loops. Every
example document in the ladder is evaluated by
`ts/test/skill.test.ts`, so a skill that teaches something the engine
no longer does fails the build.

They reach a caller by three routes, and the third is the one that
works when nothing was configured. The npm tarball stages them as
`skill/` (`ts/scripts/prepack.js`, which rewrites the links that
would otherwise escape the package). A harness can mount the directory
as a skill. And [`aontu help`](#aontu-help) serves them **from inside
the binary**, which is what an agent holding the command and no
network has.

### LSP hover provenance

The language server can append a value's **contributions** to its
hover (what met at that path, in source order, with each site) the
same record [`aontu model why`](#aontu-model-why) prints. It is off unless an
editor asks for it:

<!-- test: skip editor initialization sample; the hover surface is pinned by ts/test/lsp.test.ts -->
```json
{ "initializationOptions": { "aontu": { "provenance": true } } }
```

Hover already re-unifies the document per request, so an editor that
asks for this pays a second, instrumented evaluation knowingly, and
one that does not pays nothing. Diagnostics are unchanged either way.

**Getting the command**

- **TypeScript:** the npm package declares a `bin` named `aontu`
  (`bin/aontu.js`), so `npm install -g aontu` (or `npx aontu`) provides
  it. From a clone: `make install-ts`, an `npm link` of the checkout,
  or `node ts/bin/aontu.js …` without installing.
- **Go:** `go install github.com/aontu-lang/aontu/go/cmd/aontu@latest`, or
  from a clone: `make install-go`, a `go install` of `aontu` and
  `aontu-lsp`, or `go run ./cmd/aontu …` inside `go/`.

`make install` at the root of a clone does both. Both commands accept
the same options and produce the same results.

---

## Evaluation consumes the tree

A parsed `Val` tree is **single-use**, in both implementations.
`unify`/`generate` refine the tree in place (children are written
back, junction and reference nodes advance their own state), which is
safe only because a tree is unified once and never shared. Do not
cache, reuse, or unify the same parsed `Val` (or any node reachable
from it) in two different evaluations: the second run starts from
mutated state and the result is nondeterministic. Parse again (or
clone first) for every independent evaluation. The string entry points
(`generate(src)`, `unify(src)`) parse per call and are always safe.

This is a named rule of the [trust contract](/docs/trust)'s determinism
clause, not a performance note: violating it produces wrong answers,
not slow ones.

## TypeScript API

Package `aontu` (canonical). Entry point `dist/aontu.js`, types
`dist/aontu.d.ts`. Requires Node ≥ 22.

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
import { Aontu } from 'aontu'          // named
import Aontu from 'aontu'              // default (same class)
```

### class `Aontu`

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
new Aontu(opts?: AontuOptions)
```

Constructs an instance and its parser (`Lang`). One instance can process
many sources.

| Method | Signature | Returns | Notes |
|--------|-----------|---------|-------|
| `parse`    | `parse(src: string, opts?, ctx?)` | `Val \| undefined` | Parses to an unresolved AST. Does not unify. |
| `unify`    | `unify(src: string \| Val, opts?, ctx?)` | `Val` | Parses (if given a string) and runs the fixpoint to a fully unified `Val`. |
| `generate` | `generate(src: string, opts?, ctx?)` | `any` | Parse → unify → emit a native JS value. **Throws `AontuError`** on conflict or an unresolved result. Serialise the result with [`exactJSON`](#exact-numbers-and-exactjson), not `JSON.stringify`. |
| `ctx`      | `ctx(cfg?: AontuContextConfig)` | `AontuContext` | Creates a context (for variables, error collection, a custom `fs`, etc.). |

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
const aontu = new Aontu()
aontu.parse('a:number')                  // Val (AST)
aontu.unify('a:1 a:number').canon        // '{"a":1}'
aontu.generate('a:1 b:$.a')              // { a: 1, b: 1 }
aontu.generate('a:1 a:2')                // throws AontuError: Cannot unify value: 2 with value: 1
```

`unify` accepts a previously parsed `Val`, so a caller that wants the
AST first need not re-parse: `const p = aontu.parse(src);
aontu.unify(p)`. But note that the parsed tree is **single-use** (see
[Evaluation consumes the tree](#evaluation-consumes-the-tree)) so each
parse feeds at most one unify/generate.

### `AontuOptions`

Passed to the constructor, to any method's `opts` argument, or merged
into a context.

| Option     | Type        | Purpose |
|------------|-------------|---------|
| `src`      | `string`    | Source text (usually passed positionally instead). |
| `path`     | `string`    | Path of the entry file (for `@"…"` relative resolution and error sites). |
| `base`     | `string`    | Base path for the resolver. |
| `resolver` | `Resolver`  | Custom source resolver for `@"…"` loading. |
| `fs`       | `typeof fs` | Filesystem implementation: for example a `memfs` volume for tests. |
| `collect`  | `boolean`   | Collect errors onto `result.err` instead of throwing. |
| `err`      | `any[]`     | Pre-existing array to accumulate errors into (implies `collect`). |
| `explain`  | `any[]`     | Capture a structured trace of the unification. |
| `debug` / `trace` | `boolean` | Enable parser debug / parse tracing. |
| `deps`     | `object`    | Dependency record populated by `@"…"` loads. |
| `log`      | `number`    | Parser log verbosity. |

`@"…"` resolution tries an **in-memory** resolver, then the
**filesystem**, then **package** resolution, in that order. The chain
is unconfined by default (a relative include follows any path the
process can read) so **treat opening an untrusted source as running
it**. Confinement is the **`trust` option** ([the trust
contract](/docs/trust)), in both implementations:

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
const aontu = new Aontu({
  trust: {
    // include capability, one of:
    //   'none'              — @"…" always denied
    //   { mem: {...} }      — a virtual file set only
    //   { root: '/models' } — real files, realpath-confined below root;
    //                         no package resolution
    //   'system'            — the full chain (today's default)
    include: { root: '/models' },
    budget: { passes: 9, depth: 1000 },  // integer engine-event counts
  },
})
```

Go mirrors it as `Aontu.Trust` (`TrustOptions`: `IncludeNone`,
`IncludeMem`, `IncludeRoot`, `Budget`). A denied resolution is the
parse-stage `include_denied` error, pinned by
`test/spec/include-trust.tsv` in both runners. Confinement is
realpath-then-prefix-check on the resolved file, so a symlink inside the
root pointing outside it is denied. An **empty** `root` denies every
include rather than resolving to the process directory; Go's flat
`IncludeRoot` has no spelling for it, its zero value being an absent
root. Note `fs` is *not* a sandbox: it
supplies source text for parsing and error context, and the file and
package legs read through their own channels; the trust profile is the
confinement surface.

**The include manifest.** After a parse, the resolved include closure is
observable as sorted, deduplicated `{ path, capability }`
entries (`result.deps` in TypeScript, `Aontu.IncludeDeps` in
Go) hermeticity's "file set" as data (capability is `mem`, `file` or
`pkg`). Content hashing and pinning belong to [`aontu
hash`](#aontu-hash) and the package tooling, [`aontu pkg`](#aontu-pkg).

**The bundled vocabularies.** `@"aontu:system"` ([the system
vocabulary](/docs/reference-language#the-aontusystem-vocabulary)) and
`@"aontu:view"` (the schema for a [view document's](#aontu-view)
declarations) are served from the engine rather than from disk, so they
need neither the filesystem nor package resolution and resolve under
every include capability except `'none'`. They appear in the manifest
with capability `std`. A host that wants a different vocabulary supplies its own source
under its own name; the bundled one is engine-owned.

**Relation checks.** `relationCheck(src)` in TypeScript and
`Aontu.RelationCheck(src)` in Go run the
[declared-relation](/docs/reference-language#declared-relations) checks
over the derived edge set, returning the `{verdict, findings}` record
that [`aontu relations`](#aontu-relations) prints: that section has
the verdicts, the finding fields, and the exit codes.

**The derived graph.** After a unification, an evaluated document's link
structure is observable too: `result.graph` in TypeScript (also available
as the pure function `graphOf(val)`) and `Aontu.Graph` in Go. It is the
edge set:

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
{
  edges: [ { from: '$.services.billing', key: 'dependsOn',
             to: '$.services.auth',
             at: '$.services.billing.dependsOn.0' }, … ],
}
```

There is no entity index, because there is no second namespace to index:
a node's address is its path. One entry per checked
[link](/docs/reference-language#checked-links-refert):

- **`from`** is the node the link starts at: the link's own position
  with the relation key and any list indices stripped, so a link inside
  a list is an edge from the node that holds the list. `$` when the
  link sits at the top of the document.
- **`key`** is the relation. A `rel()`-minted link carries its
  predicate declared; a bare `refer()` has it inferred as the first
  real key above the link.
-  **`to`** is the **resolved** address, always absolute. A relative
  address means a different node from each position it is written at, so
  an edge set whose far ends were spellings could not be traversed: the
  link's own *value* is still what the author wrote.
- **`at`** is where the link is written.

It is **deterministic**: edges are sorted by construction, and both
runners re-derive the graph on a fresh engine and require the same
bytes (`test/spec/graph.tsv`). Impact analysis, reachability and node
slices are traversals over it; their
exposure as verbs and projections is the machine-access layer's.

### `AontuContext`

A context threads variables, error state, and resolver configuration
through a run. Create one with `aontu.ctx()`.

- `ctx.vars: Record<string, Val>`: values for `$name` variables.
- `ctx.err: any[]`: collected errors (when `collect`).
- `ctx.find(path: string[]): Val | undefined`: look a value up by path.

Pass the context as the third argument:
`aontu.generate(src, undefined, ctx)`.

### `Val` (TypeScript)

The unified value. Useful members:

| Member | Description |
|--------|-------------|
| `canon: string` | Reparseable canonical form (see [language reference](/docs/reference-language#canonical-form)). |
| `gen(ctx): any` | Emit the native value (used by `generate`). |
| `err: any[]`    | Errors attached to this value (`NilVal`s). |
| `isVal: boolean` and `isMap`/`isList`/`isScalar`/`isNil`/… | Type discriminators. |
| `path: string[]` | Path from the root. |

`Val` is an abstract base; concrete subclasses (`MapVal`, `ListVal`,
`IntegerVal`, `NumberVal`, `BigIntegerVal`, `BigDecimalVal`,
`StringVal`, `BooleanVal`, `NullVal`, `ScalarKindVal`, `ConjunctVal`,
`DisjunctVal`, `PrefVal`, `RefVal`, `VarVal`, the `*FuncVal`s, …) are
exported from their modules under `dist/val/`.

The four numeric subclasses are the four numeric leaves:
`IntegerVal` is `integer`, `NumberVal` is `float` (the class name is
historical: `number` is the pure supertype, not a leaf), and
`BigIntegerVal` / `BigDecimalVal` are the exact leaves
`biginteger` / `bigdecimal`.

### Exact numbers and `exactJSON`

`generate()` returns **native** values, and a document that opts into
the `0d` exact literals returns two of them that `JSON.stringify` cannot
write:

| aontu kind   | Source     | `generate()` returns |
|--------------|------------|----------------------|
| `integer`    | `x:5`      | `number`, or `bigint` past `Number.MAX_SAFE_INTEGER` (see below) |
| `float`      | `x:1.5`    | `number`             |
| `biginteger` | `x:0d5`    | `bigint`             |
| `bigdecimal` | `x:0d0.1`  | `Decimal`            |

**Why an `integer` can be a `bigint`.** The `integer` leaf is an int64
window, and JavaScript stores it in a double. Below
`Number.MAX_SAFE_INTEGER` that is faithful: the integers are contiguous
there, so the `number` renders its own exact digits. Above it they are
not (`JSON.stringify(2**60)` is `1152921504606847000`, a *different*
integer that merely rounds to the same double) so `generate()` returns
a `bigint`, which `exactJSON` writes exactly. A `float` stays a `number`
at any magnitude, because a double's shortest form already names it
exactly (`1e21` serialises as `1e+21`, in this port and in Go).

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
typeof gen('x:9007199254740991').x     // 'number'  (2^53-1)
typeof gen('x:9007199254740992').x     // 'bigint'  (2^53)
typeof gen('x:1e21').x                 // 'number'  (float kind)
exactJSON(gen('x:1152921504606846976'))  // '{"x":1152921504606846976}'
```

An integer-kind `bigint` is still not a `biginteger`: the leaves stay
disjoint and only canon tells them apart (`1152921504606846976` versus
`0d1152921504606846976`). Go needs none of this: its `integer` leaf is
an `int64`, exact across the whole window, so `Generate` returns an
`int64` at every magnitude. The serialised JSON is identical in both
ports.

A `0d`-free document generates exactly what it always did: the exact
leaves are reached only by writing `0d` (see the
[language reference](/docs/reference-language#the-four-numeric-leaves)).
Both leaves survive nesting: `generate('x:{y:0d7} z:[0d1,0d0.5]')` puts
a `bigint` at `x.y` and a `Decimal` at `z[1]`. Note that an *integral*
bigdecimal is still a `Decimal` and never a `bigint`: `0d1e3` is a
bigdecimal by source form, and the leaves are disjoint.

`JSON.stringify` **throws** on a `bigint` (`TypeError: Do not know how
to serialize a BigInt`), and a `replacer` cannot rescue it: a replacer
may only return another *value*, and anything it returns that is not
already a JSON primitive gets quoted, so the exact digits could come
back only as a JSON *string*, which is a different document. JSON itself
was never the obstacle: a JSON number is arbitrary-precision decimal
text, and `{"x":9007199254740993}` is a legal document. Only
JavaScript's serialiser stands in the way, so the package ships its own.

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
exactJSON(value: any, indent?: number | string): string
```

Serialises a `generate()` result as JSON text, preserving exact numbers.
**Use it instead of `JSON.stringify` on generated output.**

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
import { Aontu, exactJSON } from 'aontu'

const out = new Aontu().generate('x:0d9007199254740993')
typeof out.x        // 'bigint'
exactJSON(out)      // '{"x":9007199254740993}'
exactJSON(out, 2)   // '{\n  "x": 9007199254740993\n}'
JSON.stringify(out) // TypeError: Do not know how to serialize a BigInt
```

- **`indent`** has `JSON.stringify`'s `space` semantics: a number of
  spaces (clamped to `0`–`10`) or a literal string (truncated to 10
  characters). Omitted or `0` gives **compact** output: no spaces, no
  newlines.
- A `bigint` writes its digits. A `Decimal` writes its plain digit form
  (`1000.0`, `0.1`, `-1.5`): no `0d` marker, since that belongs to
  canon and is not JSON, but an integral bigdecimal keeps its `.0` so
  the JSON still shows a decimal.
- Object keys are emitted in **lexicographic order** (by UTF-16 code
  unit), matching Go's `encoding/json`, which sorts map keys. This is
  done at emit time and not by `generate()`, because a JavaScript object
  *cannot* hold the required order: ECMAScript lists canonical
  array-index keys first, ascending numerically, so an object can never
  present `"10"` before `"9"`. It applies to any object passed in, not
  only `generate()` output, since this is a general emitter, and it is
  the one place the result deliberately differs from `JSON.stringify`.
- Ordinary values are otherwise written exactly as `JSON.stringify`
  writes them: the same string escaping, `null` for `NaN` and
  `Infinity`, and `undefined`/function/symbol dropped from an object but
  written as `null` inside an array. An object with a `toJSON` method is
  asked for its replacement (`Decimal` is handled as a number before
  that check).
-  U+2028 and U+2029 are escaped, which `JSON.stringify` does not
  do: that is the one place JavaScript and Go disagree by default, and
  escaping is both legal JSON and safe to embed in JavaScript source.
- It always returns a string: a top-level `undefined` becomes `null`.
- It throws `AontuError` if the value contains a reference cycle. A
  *shared* subtree (which unification produces routinely) is fine;
  only a true cycle is refused, as in `JSON.stringify`.

The output is byte-identical to the Go port's `encoding/json` with
`SetEscapeHTML(false)` for the same document; that equivalence is
pinned by the test suite both implementations run. The `aontu`
CLI calls this same export with `indent` of `2`, so there is exactly one
implementation for the pretty and compact forms to stay in step with.

`Decimal` is exported from `aontu` alongside it: the type a bigdecimal
generates as. It is an immutable exact base-10 value (`unscaled: bigint`
plus `scale: number`) in normal form, so numerically equal decimals have
equal fields:

| Member | Description |
|--------|-------------|
| `new Decimal(unscaled: bigint, scale: number)` | Construct and normalise. |
| `Decimal.fromString(src: string)` | Parse `[+-]?digits[.digits][e[+-]digits]`, with or without a `0d` marker. |
| `toString(): string` | Plain digit form: what `exactJSON` writes. |
| `canon(): string` | Canonical form, with the `0d` marker. |
| `equals` / `compare` / `add` / `negate` / `ceil` / `floor` / `isZero` | Exact operations: no rounding anywhere. |

`Decimal.fromString` refuses input beyond the exactness budget (at most
4096 coefficient digits and an absolute scale of at most 4096: see the
[language reference](/docs/reference-language#the-exactness-budget)), the
same refusal a literal gets.

### Variables

`$name` references are filled from `ctx.vars`. Build value objects with
the exported `Val` constructors:

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
import { Aontu } from 'aontu'
import { IntegerVal } from 'aontu/dist/val/IntegerVal'
import { StringVal }  from 'aontu/dist/val/StringVal'
import { MapVal }     from 'aontu/dist/val/MapVal'

const aontu = new Aontu()
const ctx = aontu.ctx()
ctx.vars.foo = new IntegerVal({ peg: 11 })
ctx.vars.bar = new StringVal({ peg: 'hello' })
ctx.vars.obj = new MapVal({ peg: { x: new IntegerVal({ peg: 1 }) } })

aontu.generate('a:$foo b:$bar c:$obj', undefined, ctx)
// { a: 11, b: 'hello', c: { x: 1 } }
```

**Exact-input constructors.** The two exact leaves take a `bigint`, a
`Decimal`, or the digits as **text**: never a JS `number`, which
binary64 has already rounded before this library could inspect it, so an
exact value above 2^53 could not arrive that way intact:

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
import { Decimal }       from 'aontu'
import { BigIntegerVal } from 'aontu/dist/val/BigIntegerVal'
import { BigDecimalVal } from 'aontu/dist/val/BigDecimalVal'

new BigIntegerVal({ peg: 5n })                     // 0d5
new BigIntegerVal({ peg: '9007199254740993' })     // 0d9007199254740993
new BigIntegerVal({ peg: 5 })                      // throws: not-biginteger

new BigDecimalVal({ peg: new Decimal(15n, 1) })    // 0d1.5
new BigDecimalVal({ peg: '0.10' })                 // 0d0.1  (normalised)
new BigDecimalVal({ peg: 1.5 })                    // throws: not-bigdecimal
```

Both reject malformed text (`'5.5'` is not a biginteger).
`BigDecimalVal` additionally refuses input over the exactness budget,
exactly as a `0d` literal does; a biginteger has no bound and is as wide
as its digits. Because the constructor picks the leaf where a literal's
source text would, `new BigDecimalVal({ peg: '5' })` is a *bigdecimal*
and canons `0d5.0`.

### Exports

From `aontu`:

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
Aontu          // class (also default export)
AontuOptions   // type
AontuContext   // class
AontuError     // error class (thrown by generate)
Val            // base value type
Lang           // the parser
VERSION        // the package version string
runparse, util // parsing helpers
formatExplain  // pretty-print an `explain` trace
exactJSON      // exact JSON emitter — use instead of JSON.stringify
Decimal        // the type a bigdecimal generates as
vet            // the validation verb (see `aontu vet` above)
sarifReport    // a vet report as SARIF 2.1.0
subsume        // the subsumption query (docs/reference-language.md,
               // "Subsumption"): subsume(general, specific, {profile?, at?})
               // -> {verdict, findings}; Go: aontu.Subsume
trimCheck      // the redundancy reporter (see `aontu trim` above):
               // trimCheck(src, {path?}) -> {verdict, redundant};
               // Go: aontu.New().TrimCheck(src)
hcanon         // the HASH FORM of an evaluated Val (see `aontu hash`
               // above): canon plus the close()/type()/hide()
               // wrappers; Go: aontu.Hcanon
canonHash      // the canon-hash pin over that form,
               // "aon1-"+base64url(SHA-256(...)); Go: aontu.CanonHash
get            // the query surface (see `aontu model get` above):
               // get(src, path, {view?, depth?, path?, trust?}) ->
               // {ok, out, findings}; Go: aontu.New().Get(src, path, opts)
why            // provenance (see `aontu model why` above):
               // why(src, path, {path?, trust?}) -> {ok, record, findings},
               // record = {path, value, conjuncts}; Go: (*Aontu).Why
patch          // the overlay patch (see `aontu model set` above):
               // patch(entry, overlay, ["$.a.b=1"], opts?) ->
               // {overlay, appended, verdict, findings}; Go: aontu.Patch
diff           // what changed at which paths between two documents:
               // diff(left, right, {at?, trust?}) -> {changes, same, findings};
               // Go: aontu.Diff
agentsMd       // the generated AGENTS.md stanza (see `aontu agentsmd`
               // above): agentsMd(src, {name?}) -> {stanza, ok};
               // Go: (*Aontu).AgentsMd
format         // the source formatter (see `aontu fmt` above):
               // format(src, {path?, lint?}) -> {verdict, text,
               // changed, findings} or {verdict, errors}; Go:
               // aontu.New().Format(src), and FormatWith(src,
               // FormatOptions{Lint: true}) for the findings
unifiedDiff    // unifiedDiff(name, before, after): the diff `aontu fmt
               // --diff` prints; Go: aontu.UnifiedDiff
loadProfile    // a profile document -> {profile} or {errors}:
               // evaluated under the caller's include options, vetted
               // against aontu:profile as a settled value and met with
               // it, so the defaults are filled; what --profile <file>
               // hands to `template`, `fmt` and `trace`
desugarTemplate // a generator in the target's own syntax -> the
               // canonical aontu it means (see `aontu template`):
               // desugarTemplate(src, marker?) -> string;
               // Go: aontu.DesugarTemplate
resugarTemplate // the other direction, a fixpoint against the first:
               // resugarTemplate(src, marker?) -> string;
               // Go: aontu.ResugarTemplate
markerFor      // the marker a file's extension names, `//-` by
               // default: markerFor(path) -> string;
               // Go: aontu.MarkerFor
```

#### Evaluating a document you did not write

`vet`, `get`, `why` and `diff` each take a **`trust`** option, the same
profile [`AontuOptions.trust`](#aontuoptions) takes, and it means the
same thing: what the document being evaluated may reach.

These four verbs exist to be pointed at source from somewhere else (a
candidate an agent emitted, a live system dump, the other side of a
diff) and without a profile they resolve `@"…"` through the default
chain, which reaches anything on the filesystem the process can read.
**Opening an untrusted source is reading your disk**, so pass a profile
whenever the source is not yours. Reading, never running: an include's
extension decides what the file is (`.aon` and `.aontu` as aontu source,
`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,
`.yaml`, `.yml` and `.ini` as configuration data, and `.txt` as text
(the bytes, as one string)) and every other extension is refused.
`textExt` widens the text set; it cannot re-read a named format, and
cannot reach `.js`.

<!-- test: skip TypeScript API sample; the API surface is pinned by ts/test/ -->
```ts
vet(schemaSrc, candidateSrc, { trust: { include: 'none' } })
```

The [MCP server](#the-mcp-server) supplies its profile (`{ include:
'none' }`, or `{ include: { root } }` when started with `--root <dir>`) to every tool from a single place, rather than each tool applying
it for itself: a tool that must remember to confine itself is one that
eventually forgets, and the forgetting is silent. The engines that take
no `trust` option (`subsume`, `trimCheck`, `relationCheck`, `patch`) are
confined there by a pre-parse under the same profile: includes resolve
at parse, so a document whose confined parse is clean gives the engine
nothing it could reach further with.

---

## Go API

Module `github.com/aontu-lang/aontu/go`, package `aontu`.

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
import aontu "github.com/aontu-lang/aontu/go"
```

### type `Aontu`

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
func New() *Aontu                 // relative @"file" loads resolve from the cwd
func NewWithBase(base string) *Aontu  // …resolve from base (a directory)
```

Use `NewWithBase` when a source's relative `@"file"` loads should resolve
from somewhere other than the process working directory: typically the
directory of an entry file:

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
abs, _ := filepath.Abs(file)
a := aontu.NewWithBase(filepath.Dir(abs))
```

Absolute `@"file"` paths are unaffected by the base. (The `aontu` CLI
does exactly this for a file argument.)

| Method | Signature | Notes |
|--------|-----------|-------|
| `Parse`        | `Parse(src string) (Val, error)` | AST, not unified. |
| `Unify`        | `Unify(src string) (Val, error)` | Parse + fixpoint unify. |
| `UnifyVars`    | `UnifyVars(src string, vars map[string]Val) (Val, error)` | `Unify` with `$name` variables. |
| `Generate`     | `Generate(src string) (any, error)` | Parse → unify → native Go value. |
| `GenerateVars` | `GenerateVars(src string, vars map[string]Val) (any, error)` | `Generate` with variables. |
| `Trace`        | `Trace(src string, opts *TraceOptions) TraceReport` | What wrote each line of a component tree (see [`aontu trace`](#aontu-trace)): `Trace` is one `TraceEntry` per stamped piece (`At`, `File`, `Node` and `Rule`), or `Errors`. `aontu.TraceTree(root Val) []TraceEntry` is the walk alone, over a value already unified. |
| `LoadProfile`  | `LoadProfile(src string) (map[string]any, []VetFinding)` | A profile document, evaluated under this instance's include options, vetted against `aontu:profile` as a settled value and met with it so the defaults are filled: the profile `--profile <file>` hands to `template`, `fmt` and `trace`, or the findings that refused it. |
| `Format`       | `Format(src string) FormatReport` | The source formatter (see [`aontu fmt`](#aontu-fmt)): the agreed form, or the findings that say why there is none. `FormatWith(src string, opts FormatOptions) FormatReport` is the same with the options: `Lint` fills the report's `Findings`, the style findings of `--lint`. `aontu.UnifiedDiff(name, before, after string) string` is the diff `--diff` prints. |

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
a := aontu.New()
v, err := a.Unify("a:1 a:number")   // v.Canon() == `{"a":1}`
out, err := a.Generate("a:1 b:$.a") // out == map[string]any{"a":1,"b":1}
```

All methods return an `error` (never panic for ordinary conflicts);
`Generate` returns `(nil, err)` on any unresolved or conflicting value.
Generated output uses Go's natural types (`map[string]any`, `[]any`,
`int64`/`float64`, `string`, `bool`, `nil`), plus `*big.Int` and
`*Decimal` for the exact leaves: see
[Exact numbers in Go](#exact-numbers-in-go).

### `Val` (Go)

The lattice element interface:

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
type Val interface {
    Canon() string              // canonical source-like form
    Gen(ctx *Ctx) (any, error)  // native value (error if not generable)
    Unify(peer Val, ctx *Ctx) Val
    Dc() int                    // done-counter; DONE (-1) == fully resolved
    Nil() bool                  // true for a unification failure (bottom)
    // …plus unexported lattice-ordering methods
}
```

Concrete exported types: `TopVal`, `NilVal`, `ScalarVal`,
`ScalarKindVal`, `MapVal`, `ListVal`, `ConjunctVal`, `DisjunctVal`,
`PrefVal`, `RefVal`, `VarVal`, `FuncVal`, `PlusOpVal`. Every scalar
leaf (including the two exact ones) is a `ScalarVal`; it holds its kind
internally, so from outside the package a leaf is told apart by the
concrete type `Gen` returns, or by `Canon`.

### Exact numbers in Go

`Generate` returns Go's natural types, and the two exact leaves come out
as the two types that can hold them exactly:

| aontu kind   | Source     | `Generate` returns |
|--------------|------------|--------------------|
| `integer`    | `x:5`      | `int64`            |
| `float`      | `x:1.5`    | `float64`          |
| `biginteger` | `x:0d5`    | `*big.Int`         |
| `bigdecimal` | `x:0d0.1`  | `*Decimal`         |

A `0d`-free document generates exactly what it always did. An
*integral* bigdecimal is still a `*Decimal` and never a `*big.Int`:
`0d1e3` is a bigdecimal by source form, and the leaves are disjoint.

Both types implement `json.Marshaler` and emit **exact digits as a raw
JSON number**, so `encoding/json` needs no help:

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
out, _ := aontu.New().Generate("a:0d9007199254740993 b:0d1e3 c:0d0.1")
b, _ := json.Marshal(out)
// {"a":9007199254740993,"b":1000.0,"c":0.1}
```

The pointer is part of the contract. A non-pointer `big.Int` inside an
`any` has no `MarshalJSON` in its method set, so `encoding/json` falls
back to the struct encoder and writes `{}`: an exact number silently
replaced by an empty object, which is the class of failure the exact
leaves exist to eliminate.

A generated `*big.Int` is a **copy**, so a caller may mutate it without
disturbing the value it came from.

`Decimal` is an exact base-10 value (coefficient plus scale), immutable
and always in normal form. Its exported surface is what a consumer of
generated output needs:

| Method | Description |
|--------|-------------|
| `String() string`             | Plain digit form (`1000.0`, `0.1`, `-1.5`). |
| `MarshalJSON() ([]byte, error)` | The same digits, as a raw JSON number. |
| `Canon() string`              | Canonical form, with the `0d` marker. |

`json.Marshal` output matches the TypeScript port's
[`exactJSON`](#exact-numbers-and-exactjson) byte for byte once HTML
escaping is off (`json.Encoder` + `SetEscapeHTML(false)`); that
equivalence is pinned by the test suite both implementations run.

### `Ctx` and errors

- `Ctx` carries the root, variables, and collected errors through a run;
  you normally let `Unify`/`Generate` create it.
- `AontuError{ Msg string }` implements `error` and is returned (wrapped)
  for conflicts; its message matches the TypeScript phrasing
  (for example `Cannot unify value: 2 with value: 1`).

### Variables in Go

`UnifyVars`/`GenerateVars` accept a `map[string]Val`. Build the values
with the exported constructors:

| Constructor | Returns |
|-------------|---------|
| `NewString(s string) Val`        | string scalar |
| `NewInteger(i int64) Val`        | `integer` scalar: **refuses** an `int64` binary64 cannot carry exactly (see below) |
| `NewNumber(f float64) Val`       | `float` scalar (the name is kept for API compatibility; the kind it builds is `KindFloat`) |
| `NewBigInteger(n *big.Int) Val`  | `biginteger` scalar: the exact unbounded integer leaf |
| `NewBigDecimal(s string) (Val, error)` | `bigdecimal` scalar: the exact base-10 leaf |
| `NewBoolean(b bool) Val`         | boolean scalar |
| `NewNull() Val`                  | null scalar |
| `NewScalarKind(k Kind) Val`      | type constraint (`KindString`, `KindBoolean`, `KindNull`, and the numeric lattice `KindNumber` with its leaves `KindInteger`, `KindFloat`, `KindBigInteger`, `KindBigDecimal`) |
| `NewMap(map[string]Val) Val`     | map (keys inserted in sorted order) |
| `NewList([]Val) Val`             | list |

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
vars := map[string]aontu.Val{
    "port": aontu.NewInteger(8080),
    "host": aontu.NewString("localhost"),
    "obj":  aontu.NewMap(map[string]aontu.Val{"x": aontu.NewInteger(1)}),
}
out, err := aontu.New().GenerateVars(
    "server: { host: $host, port: $port }", vars)
// out == map[string]any{"server": map[string]any{"host":"localhost","port":8080}}
```

Pass `nil` vars when a model uses no `$name` variables. An undefined
`$name` is a `Cannot resolve` error.

**`NewInteger` obeys the same storage contract as a literal.** An
`int64` that binary64 cannot carry exactly is refused rather than
stored, exactly as the equivalent literal is refused: otherwise the API
would be a hole straight through that rule, since Go's `integer` leaf is
an `int64` and the canonical TypeScript port's is a double. The refusal
is a **nil value**, not a panic and not a second return: aontu errors
are values, so it flows through unification and surfaces at `Generate`
with the same "not exactly representable" message and the same `0d`
escape a lossy literal gets.

The rule is **exactness, not magnitude**: every power of two in the
window is fine however large, `math.MinInt64` included.

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
aontu.NewInteger(1152921504606846976)   // 2^60 — fine
aontu.NewInteger(math.MinInt64)         // -2^63, a power of two — fine
aontu.NewInteger(9007199254740993)      // 2^53+1 — nil value
aontu.NewInteger(math.MaxInt64)         // 2^63-1, rounds up — nil value
aontu.NewBigInteger(big.NewInt(9007199254740993))  // the exact escape
```

**Exact-input constructors.** `NewBigInteger` **copies** its argument
and never mutates the copy, so a caller may keep using (and mutating)
the `*big.Int` it passed in; a `nil` argument is zero.
`NewBigDecimal` takes a **string**: an optional sign, an optional `0d`
marker, digits, an optional fraction and an optional exponent, and no
`_` separators (those are literal syntax, not part of a number's text).
A `float64` is deliberately not accepted: it has already rounded before
the library can inspect it.

<!-- test: skip Go API sample; the API surface is pinned by the go/ test suite -->
```go
n, _ := new(big.Int).SetString("123456789012345678901234567890", 10)
aontu.NewBigInteger(n)          // 0d123456789012345678901234567890
aontu.NewBigDecimal("0.10")     // 0d0.1   (normalised)
aontu.NewBigDecimal("0d1e3")    // 0d1000.0
aontu.NewBigDecimal("1_000")    // error: Not an exact decimal
```

`NewBigDecimal` returns an error for malformed text and for input over
the exactness budget (at most 4096 coefficient digits and an absolute
scale of at most 4096: see the
[language reference](/docs/reference-language#the-exactness-budget)), the
same refusal a literal gets. A biginteger has no bound and is as wide as
its digits. Because the constructor picks the leaf where a literal's
source text would, `NewBigDecimal("5")` is a *bigdecimal* and canons
`0d5.0`.

---

## Behavioural parity

Both implementations are validated against the same
[`test/spec/*.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/) cases and agree on: scalars and scalar
kinds (including the numeric tower's four leaves (`integer`, `float`,
`biginteger`, `bigdecimal`) under the pure supertype `number`, their
`0d` exact literals, and exact arithmetic) maps (nesting, merge,
spreads `&:`, optional keys, `close`/`open`), lists (incl. spreads),
conjunction `&`, disjunction `|`, preference `*`, references (`$.a.b`,
`.x.a`), `$name` variables, the `+` operator, all twelve
functions, `type`/`hide` marks, and `@"…"` source loading: plus
`parse` / `unify` / `generate` and the canonical form.

Generated **bytes** are in parity too: `exactJSON` in TypeScript and
`encoding/json` in Go produce the same JSON text for the same document,
which the shared suite's byte-exact `gens` rows pin. What byte equality
cannot see (a `bigint` where a `number` was due, since both serialise
as `5`) is pinned by per-port API tests instead.

**Validation reports** are in parity as well: `aontu vet` produces the
same report from both commands, text and JSON, with the same exit
code: pinned by the shared suite's [`vet.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/vet.tsv) rows
for everything but each finding's `message`, which is prose. One thing
still differs by construction: the wording of a "cannot read <file>"
failure, which is the host's. The `aontu.version` field agreed from
0.70.0, when the two version series merged into one.

The shared parser stack is identical: TypeScript uses `@tabnas/jsonic` +
`@tabnas/{expr,path,multisource,directive,debug}`; Go uses the ports
`github.com/tabnas/{jsonic,expr,path,multisource,directive}/go`. See
the [Explanation](/docs/explanation#two-implementations-one-behaviour) for
how parity is maintained.

---

# aontu Language Server (LSP)

_The aontu-lsp language server: diagnostics, hover and completion, how to wire it into an editor, and the reusable library API._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/lsp.md · Page: https://aontu.dev/docs/lsp

Both implementations ship a [Language Server
Protocol](https://microsoft.github.io/language-server-protocol/) server
that reports aontu unification problems as editor diagnostics while you
type. As required by the project's parity rule, the TypeScript and Go
servers are built the same way, advertise the same capabilities, and
produce identical diagnostic text for the same source.

This document is a **reference**: it is exhaustive about the architecture,
the library API in both languages, the supported protocol surface, and how
to run the server. Wiring it into an editor is a task, and lives in the
[wire your editor](/how-to/wire-your-editor) guide.

- [What it does](#what-it-does)
- [Architecture: library vs. server](#architecture-library-vs-server)
- [Running the server](#running-the-server)
- [Editor configuration](#editor-configuration)
- [Library API](#library-api)
  - [TypeScript](#typescript-library)
  - [Go](#go-library)
- [Protocol surface](#protocol-surface)
- [How diagnostics are computed](#how-diagnostics-are-computed)
- [Cross-implementation parity](#cross-implementation-parity)
- [Limitations and extension points](#limitations-and-extension-points)


## What it does

The server provides these features:

- **Diagnostics**: unification problems published as you edit.
- **Hover**: the resolved value and kind under the cursor, or the
  declaration of the alias name it is on.
- **Completion**: the built-in functions, scalar-kind keywords and
  literals, and the alias names the document binds.
- **Go to definition**: from an alias name to where the file binds it.
- **Signature help**: the parameters of the function being called.

**Diagnostics**: open or edit an aontu document and it
publishes a list of problems, each with a precise source range, severity,
an engine error code (`code`), and a human-readable message.

It reports *genuine errors* only:

| Source                  | Diagnostic?                                   |
|-------------------------|-----------------------------------------------|
| `a:1 a:2`               | yes: `scalar_value` conflict                 |
| `a:1 & string`          | yes: `no_scalar_unify`                        |
| `x:foo(1)`              | yes: `unknown_function`                       |
| `a:$.missing`           | yes: `no_path`                                |
| `b: refer() & path("$.nope")` | yes: `refer_unresolved` (a `rel()` member naming no entity: `rel_unresolved`) |
| `a:string`              | **no**: a non-concrete schema is valid        |
| `a:{b:string, c:1}`     | **no**: partial/constraint documents are valid |
| `port:*8080 \| integer` | **no**: defaults and disjunctions are valid    |
| `a: $.a`                | **no**: a recursive reference is a valid schema |

This distinction is deliberate: aontu documents are frequently schemas or
partial fragments, which are *not concrete* but are *not errors*. The
server flags only contradictions and unresolved/unknown constructs. See
[How diagnostics are computed](#how-diagnostics-are-computed).

Verdicts that land at generation stay out of the editor. A required
recursive position that no data expanded (`recursion_unexpanded`) and a
relation finding from `acyclic()` (`relation_cycle`) are generate-time
refusals, so `computeDiagnostics` publishes nothing for either.

One diagnostic is not an error: a value carrying `deprecate()` is
published with code `deprecated` at Hint severity (4), tagged with the
native Deprecated tag (2), so editors strike it through without
shouting.

**Hover** reads the *unified* tree, so hovering a value shows what it
resolves to: hovering `8080` in `port: 8080` shows `8080` with kind
*integer*; hovering `string` in a schema shows kind *type*. Hover targets
concrete values (scalars, kinds, references), not containers.

**Completion** offers a context-free list (clients filter by the typed
prefix): the built-in functions (the engine's full roster, 41 today, the
constraint atoms (`min`, `re`, `length`, …) and the entity and relation
atoms (`id`, `refer`, `rel`, `acyclic`, `inverse`) included) the
scalar-kind keywords (`string`, `number`, `integer`, `float`,
`biginteger`, `bigdecimal`, `boolean`) and the literals (`_`, `true`,
`false`, `null`, `top`).


## Architecture: library vs. server

Per the requirement to *expose the LSP logic as a library separate from
serving it*, each implementation is split into three layers. Only the
outermost layer touches stdin/stdout, so the analysis and the protocol
state machine are both unit-testable with no I/O.

```
┌─────────────────────────────────────────────────────────────┐
│ 3. Server (transport)        ts/src/lsp-server.ts             │
│    stdio Content-Length      go/lsp/serve.go                  │
│    JSON-RPC framing only                                      │
└───────────────┬─────────────────────────────────────────────┘
                │ decoded message objects
┌───────────────▼─────────────────────────────────────────────┐
│ 2. Handler (protocol)        LspHandler  (ts/src/lsp.ts)      │
│    document sync, dispatch,  lsp.Handler (go/lsp/handler.go)  │
│    initialize/shutdown/exit  — no I/O, returns reply objects  │
└───────────────┬─────────────────────────────────────────────┘
                │ document text
┌───────────────▼─────────────────────────────────────────────┐
│ 1. Analysis (pure)           computeDiagnostics (ts/src/lsp.ts)│
│    source text -> Diagnostic[]  lsp.Diagnostics (go/lsp/lsp.go)│
└─────────────────────────────────────────────────────────────┘
```

| Layer | TypeScript | Go |
|-------|------------|----|
| 1. Analysis | `computeDiagnostics(src)` in `ts/src/lsp.ts` | `lsp.Diagnostics(src)` in `go/lsp/lsp.go` (over `aontu.Check`) |
| 2. Handler | `LspHandler` in `ts/src/lsp.ts` | `lsp.Handler` in `go/lsp/handler.go` |
| 3. Server | `ts/src/lsp-server.ts` → `aontu lsp` (and the `aontu-lsp` bin) | `go/lsp/serve.go` → `aontu lsp` (and the `aontu-lsp` binary) |

You can consume any layer directly:

- embed **layer 1** to lint aontu source in your own tool;
- embed **layer 2** to run the server over a non-stdio transport (for example a
  socket or an in-process channel) by feeding it decoded JSON-RPC objects;
- run **layer 3** as a ready-made stdio server for an editor.

### Bring your own server

The library (layers 1–2) does **not** depend on the bundled stdio server,
so a third party can build a server on a different transport while reusing
all the analysis and protocol logic:

- **Go**: import `github.com/aontu-lang/aontu/go/lsp`. The package has no
  dependency on `cmd/aontu-lsp` (verifiable with
  `go list -deps ./lsp | grep cmd` → empty). Drive `lsp.NewHandler()` with
  decoded `lsp.Message` values and write back the returned `lsp.Out`s over
  whatever transport you like.
- **TypeScript**: import `aontu/dist/lsp` (or `ts/src/lsp.ts`). It does
  not import `lsp-server.ts`; the dependency is one-way (server →
  library). Drive `new LspHandler()` with message objects.

In both, `computeDiagnostics`/`Diagnostics`, `computeHover`/`Hover`, and
`computeCompletions`/`Completions` take the document's text and are
usable standalone, with no
JSON-RPC at all.


## Running the server

The server is the `lsp` verb of the CLI in both builds. It reads
LSP/JSON-RPC from **stdin** and writes to **stdout**; diagnostic
logging (if any) goes to **stderr**. Editors launch it with no
arguments beyond the verb:

<!-- test: skip a long-running stdio server; the transport is round-trip tested in ts/test/lsp.test.ts and go/lsp/serve_test.go, and the verb in both CLI suites -->
```sh
aontu lsp
```

The standalone binaries still ship and run the same server, for
configurations that name them: `aontu-lsp` from the npm package
(`node ts/bin/aontu-lsp.js` from a checkout), and `cmd/aontu-lsp` in
the Go module (`go run ./cmd/aontu-lsp` inside `go/`). The two builds
are byte-for-byte interchangeable from a client's point of view.


## Editor configuration

Ready-made plugins for **VS Code**, **Emacs** and **Vim/Neovim** live in
[`editors/`](https://github.com/aontu-lang/aontu/blob/main/editors/), and the manual wiring recipes for VS Code,
Neovim and any other LSP client have moved to the
[wire your editor](/how-to/wire-your-editor) guide. The facts a client
needs: command `aontu` with the argument `lsp`, transport stdio,
document selector the `aontu` language (`.aon` is the preferred extension, `.aontu` also
works, `.jsonic` is retired), and no configuration options.


## Library API

### TypeScript library

Import from the built package (`ts/dist/lsp`) or from source
(`ts/src/lsp.ts`).

<!-- test: skip TypeScript import sample; the exported surface is pinned by ts/test/lsp.test.ts -->
```ts
import {
  computeDiagnostics,
  LspHandler,
  type Diagnostic,
  type Message,
  type OutMessage,
  SEVERITY_ERROR,
} from 'aontu/dist/lsp' // or relative path in this repo
```

#### `computeDiagnostics(src, opts?) => Diagnostic[]`

Analyse one document of aontu source and return its diagnostics. A valid
document (including a non-concrete schema) returns `[]`.

- `src: string`: the document text.
- `opts?: { vars?: Record<string, Val> }`: optional `$name` variable
  bindings, the same map accepted by the engine's runner context.

`Diagnostic` is LSP-shaped:

<!-- test: skip type shapes quoted from ts/src/lsp.ts; pinned by ts/test/lsp.test.ts -->
```ts
type Position = { line: number; character: number }   // 0-based; UTF-16 chars
type Range    = { start: Position; end: Position }
type Diagnostic = {
  range: Range
  severity: number       // SEVERITY_ERROR (1); SEVERITY_HINT (4) for "deprecated"
  code?: string          // engine error code, e.g. "scalar_value"
  source: string         // always "aontu"
  message: string
  tags?: number[]        // LSP DiagnosticTag values; [2] marks "deprecated"
}
```

<!-- test: skip TypeScript API sample; results probed against ts/dist/lsp.js and pinned by ts/test/lsp.test.ts -->
```ts
computeDiagnostics('a:1\na:2')
// [{ range: { start: { line: 1, character: 2 }, end: { line: 1, character: 3 } },
//    severity: 1, code: 'scalar_value', source: 'aontu',
//    message: '[aontu/scalar_value]: Cannot unify values at path $.a\n...' }]

computeDiagnostics('a:string') // []  (valid schema)
```

#### `computeHover(src, position) => Hover | null`

Resolve the value at a 0-based `{ line, character }` position and describe
it, or `null` if the position is not over a concrete value.

<!-- test: skip TypeScript API sample; results probed against ts/dist/lsp.js and pinned by ts/test/lsp.test.ts -->
```ts
computeHover('port: 8080', { line: 0, character: 7 })
// { contents: { kind: 'markdown', value: '```aontu\n8080\n```\n\n*integer*' },
//   range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }
```

#### `computeCompletions(src) => CompletionItem[]`

Return the completion list: the built-in functions, scalar-kind
keywords and literals, which do not depend on `src`, and the alias
names `src` binds, which do. `CompletionItem` is
`{ label, kind?, detail? }`. The exported `BUILTIN_FUNCS` is the
function-name list.

#### `computeDefinition(src, position, uri) => Location | null`

Where the document binds the alias name at a 0-based position, or
`null` where the position is not on one, or names nothing the file
binds. `Location` is `{ uri, range }`.

#### `class LspHandler`

The transport-agnostic protocol state machine. Construct one per session
and feed it decoded JSON-RPC message objects.

<!-- test: skip TypeScript API sample; the handler is pinned by ts/test/lsp.test.ts -->
```ts
const handler = new LspHandler()
const replies: OutMessage[] = handler.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
```

- `handle(msg: Message): OutMessage[]`: process one message; returns the
  messages to send back (a response for a request, notifications such as
  `textDocument/publishDiagnostics` for document events, or `[]`).
- `get shouldExit(): boolean`: true once an `exit` notification arrives.
- `get exitCode(): number`: `0` if `shutdown` preceded `exit`, else `1`.
- `doc(uri: string): string | undefined`: current text of an open
  document (handy in tests).

#### `class FrameCodec` (server helper)

Exported from `ts/src/lsp-server.ts`. A byte-level Content-Length codec
that drives an `LspHandler`; injectable `write`/`onExit` make it testable
without real stdio. Most users want `aontu lsp` instead.

### Go library

Import `github.com/aontu-lang/aontu/go/lsp`.

<!-- test: skip Go import sample; the exported surface is pinned by go/lsp/lsp_test.go -->
```go
import "github.com/aontu-lang/aontu/go/lsp"
```

#### `func Diagnostics(src string) []Diagnostic`

Analyse one document and return its diagnostics (empty for valid
documents). `DiagnosticsVars(src, vars)` adds `$name` bindings.

<!-- test: skip struct shapes quoted from go/lsp/lsp.go; pinned by go/lsp/lsp_test.go -->
```go
type Position struct { Line int `json:"line"`; Character int `json:"character"` }
type Range    struct { Start Position `json:"start"`; End Position `json:"end"` }
type Diagnostic struct {
    Range    Range  `json:"range"`
    Severity int    `json:"severity"` // SeverityError (1); SeverityHint (4) for "deprecated"
    Code     string `json:"code,omitempty"`
    Source   string `json:"source"`   // "aontu"
    Message  string `json:"message"`
    Tags     []int  `json:"tags,omitempty"` // LSP DiagnosticTag values; [2] marks "deprecated"
}
```

<!-- test: skip Go API sample; behaviour is pinned by go/lsp/lsp_test.go and kept in parity with the probed TypeScript results -->
```go
d := lsp.Diagnostics("a:1\na:2")
// d[0].Code == "scalar_value", d[0].Range.Start == {Line:1, Character:2}
lsp.Diagnostics("a:string") // len 0 (valid schema)
```

#### `func Hover(src string, line, character int) *HoverResult`

Resolve the value at a 0-based position, or `nil`. `HoverResult` is
`{ Contents MarkupContent; Range *Range }`. Built on the core
`(*aontu.Aontu).Spans(src) []aontu.ValueSpan`, which lists positioned
non-container values.

#### `func Completions(src string) []CompletionItem`

The completion list: the built-in functions, scalar-kind keywords and
literals, which do not depend on `src`, and the alias names `src`
binds, which do. `CompletionItem` is
`{ Label string; Kind int; Detail string }`. The function names come from
the engine via `aontu.BuiltinFuncNames()`, and the alias names via
`aontu.AliasScope()`.

#### `func Definition(src string, line, character int, uri string) *Location`

Where the document binds the alias name at a 0-based position, or `nil`
where the position is not on one, or names nothing the file binds.
`Location` is `{ URI string; Range Range }`.

#### `type Handler`

The transport-agnostic protocol state machine (mirrors `LspHandler`).

- `NewHandler() *Handler`
- `(*Handler) Handle(m Message) []Out`: process one message, return
  messages to send.
- `(*Handler) ShouldExit() bool`, `(*Handler) ExitCode() int`,
  `(*Handler) Doc(uri string) (string, bool)`.

`Message`/`Out` are JSON-RPC envelopes; `Out` marshals to a well-formed
response (including an explicit `result: null` for `shutdown`).

#### Core support: `func (*aontu.Aontu) Check(src string) []aontu.Problem`

`lsp.Diagnostics` is built on `aontu.Check`, which lives in `package
aontu` because it needs the engine's internal error positions. `Check`
parses and unifies `src` and returns every problem (it does not stop at
the first, and does not treat non-concrete values as errors). Each
`Problem` carries a source **byte offset** (`Pos`, or `-1`), the byte
`Len` of the offending value's canon, the error code (`Why`), and the
`Message`. The `lsp` package converts byte offsets to LSP line/UTF-16
positions.


## Protocol surface

`textDocumentSync` is **Full** (the client sends the whole document on
each change). Advertised capabilities: `textDocumentSync: 1`,
`hoverProvider: true`, `definitionProvider: true`,
`completionProvider: {}`, `signatureHelpProvider` with the trigger
characters `(` and `,`.

| Method | Kind | Behaviour |
|--------|------|-----------|
| `initialize` | request | Replies with the advertised capabilities and `serverInfo: { name: "aontu-lsp", version }`. |
| `initialized` | notification | Ignored. |
| `textDocument/didOpen` | notification | Stores the document, publishes diagnostics. |
| `textDocument/didChange` | notification | Replaces the document with the last content change (Full sync), publishes diagnostics. |
| `textDocument/didClose` | notification | Drops the document, publishes an empty diagnostic list (clears markers). |
| `textDocument/hover` | request | Replies with a hover for the alias name at the position, else for the value there, else `null`. |
| `textDocument/completion` | request | Replies with the completion item list for the open document. |
| `textDocument/definition` | request | Replies with the `Location` where the document binds the alias name at the position, or `null`. |
| `textDocument/signatureHelp` | request | Replies with the signature of the call the position is inside, or `null`. |
| `textDocument/publishDiagnostics` | notification (server→client) | Carries `{ uri, diagnostics }`. |
| `shutdown` | request | Replies `result: null`, arms a clean exit. |
| `exit` | notification | Stops the server. Exit code `0` if `shutdown` came first, else `1`. |
| any other request | request | Replies with JSON-RPC error `-32601` (method not found). |
| any other notification | notification | Ignored. |

### Message flow

```
client → initialize                     server → result(capabilities)
client → initialized
client → didOpen(uri, text)             server → publishDiagnostics(uri, [...])
client → didChange(uri, newText)        server → publishDiagnostics(uri, [...])
client → didClose(uri)                  server → publishDiagnostics(uri, [])
client → shutdown                       server → result(null)
client → exit                           (process exits 0)
```


## How diagnostics are computed

The analysis layer turns source into diagnostics in three steps:

1. **Unify.** Parse and run the fixpoint unification over the whole
   document (in error-collecting mode; it never throws on conflicts).
2. **Walk for `NilVal`s.** Traverse the unified result tree and collect
   every `NilVal` node. The rule: in aontu a `NilVal` in the
   *result* is always a real error (a conflict, an unresolved reference,
   an unknown function, …). Valid-but-non-concrete values (scalar kinds
   like `string`, unresolved references, conjuncts) are **not** `NilVal`s,
   so schemas and partial documents produce no diagnostics. Nodes are
   de-duplicated by identity.
3. **Map to LSP.** Each `NilVal` carries a source position (1-based
   row/col in TS; a byte offset in Go) and the offending value's canon.
   These become a 0-based LSP range whose end extends across the canon
   length. The message is the engine's full error text (the
   `[aontu/<code>]` marker line, the hint, and the located source
   frames) identical in both languages.

A hard **syntax error** (which prevents producing a tree) is reported as a
single diagnostic with code `parse`, positioned where the parser failed if
that information is available, otherwise at the document start.

Positions use the LSP default encoding (**UTF-16 code units** per line):
JavaScript strings are already UTF-16, and the Go library counts UTF-16
units explicitly, so a multi-byte character before an error does not shift
the reported column.


## Cross-implementation parity

The two servers are kept in lock-step:

- **Same capabilities** and `serverInfo.name` (`aontu-lsp`).
- **Same diagnostics**: the analysis is driven by the same engine, the
  `NilVal`-walk is identical, and the message text is constructed the same
  way (`go/val.go` `NilVal.Message` and `ts/src/lsp.ts` `nilMessage`), so
  for any given source both servers emit the same `code`, `range`, and
  `message`.
- **Same protocol behaviour**, including `result: null` for `shutdown` and
  the `0`/`1` exit-code rule.

Both libraries are unit-tested (`ts/test/lsp.test.ts`,
`go/lsp/lsp_test.go`) and each server has a transport round-trip test
(`go/lsp/serve_test.go`, and the `FrameCodec` test in
`ts/test/lsp.test.ts`).


## Limitations and extension points

Current scope is diagnostics, hover, completion, go-to-definition on an
alias name, and signature help. The layered design
makes additions localised: most new features are implemented once in the
analysis layer (layer 1) and advertised in `initialize` (layer 2):

- **Hover** targets concrete values (scalars, kinds, references), not
  containers, and uses canon length to size the hit span on a single
  line; a value resolved from a reference is shown at its definition
  site. Hovering a multi-line container or the cursor exactly on a `{`
  brace may not resolve.
- **Completion** has no cursor-to-path awareness: it offers the
  built-ins and the names the document binds, but not sibling keys.
  Adding key completion needs a position→path mapping in the analysis
  layer.
- **The alias features read the document's text**, not its tree, so
  they answer while a document is half-written and would not parse. The
  cost is that they know only what the text says: a name arriving
  through a destructure resolves to the pattern that takes it, which is
  where the file binds the name, rather than to the declaration in the
  other file. Following it across the boundary would mean the server
  reading that file itself, outside the include capability that governs
  every other read.
- **Go-to-definition on a key or path**, cancellation, rename: not
  implemented; unknown requests get a `-32601` reply.
- **Incremental sync**: the server uses Full document sync for
  simplicity; range-based incremental edits could be added in the handler
  without touching the analysis layer.
- **Warnings/info severities**: engine problems are all published as
  `Error`; the one exception is `deprecated`, at Hint severity with the
  Deprecated tag.
- **Number-canon edge cases**: diagnostic ranges are sized by the
  offending value's canon length; see
  [Canonical form](/docs/reference-language#canonical-form) for the
  decimal subset that pins it.

---

# Use cases

_The executed, enterprise-shaped models: the evidence the documentation's examples are lifted from._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/use-cases.md · Page: https://aontu.dev/docs/use-cases

Documentation examples are small on purpose. Systems are not. The
eighteen models in [`use-cases/`](/use-cases) close that gap: each
one is an enterprise-shaped system built as real aontu documents (a
service catalog, a schema registry, an RBAC model) and each carries a
`check.sh` that drives the actual CLI and asserts every outcome, with
golden diffs for expected output and error-code greps for expected
refusals. When a page in these docs shows a shape, this is where that
shape lives, running. Run one case, or the whole suite:

<!-- test: skip runs the full case suite; use-cases/run-all.sh is its own gate, run before every landing -->
```sh
$ ./use-cases/03-api-contract/check.sh   # one case
$ ./use-cases/run-all.sh                 # all eighteen, one verdict line per case
```

The scripts need Node with `ts/node_modules` installed, plus `python3`
and `git` for a few cases. Each case's `README.md` is the worked
example in full, with verbatim CLI output; the sections below compress
it.

## 01. Service catalog

A Backstage-style catalog for eight services across three teams, where
the org chart and the runtime each hold facts about the same things.
`catalog.aon` says what each service *is* (owner, tier, dependencies);
`deploy.aon` says what each cluster *runs* (image, replicas, ports);
and the deployment view references the catalog, so one evaluation
merges them field by field and any contradiction between the views is a
located error instead of a silent fork. The case also drives `refer()`
existence checks, declared relations, and change requests written as
four-line overlay files. The same service, seen from both views:

```aon
# catalog.aon — the catalog view
services: payments: {
  tier: 1
  description: "Card payment orchestration and capture API."
  dependsOn: [
    "$.services.ledger"
    "$.services.risk"
    "$.services.auth"
    "$.services.notify"
  ]
  dependedOnBy: ["$.services.gateway"]
}

# deploy.aon — the deployment view
deploy: eu1: payments: $.services.payments & {
  image: "registry.acme.internal/payments:2.14.1"
  replicas: 6
  ports: http: { number:8080 protocol:http }
}
```

The reference joins them, and an overlay claiming `tier: 2` refuses
with `[aontu/scalar_value]`. The live model, refusals included:
[`use-cases/01-service-catalog/`](/use-cases/01-service-catalog).

## 02. Deploy config

Four services, three environments, four layers of authority: org
policy, team defaults, a service catalog, per-environment overlays.
This is Helm-values and Kustomize territory, and the layering
mechanism is the preference-rank ladder: the fewer stars, the stronger
the default. The org writes `***`, teams
`**`, environments `*`, a concrete pin beats them all, and two
disagreeing defaults at the same rank are a conflict. The whole
ladder, trimmed from the case's `probes/rank-ladder.aon`:

```aontu
org_team_env: ***info|string
org_team_env: **debug|string
org_team_env: *warn|string

pinned: ***info|string
pinned: **debug|string
pinned: error
```
```json
{
  "org_team_env": "warn",
  "pinned": "error"
}
```

Statement order never matters, and `aontu model why` prints each surviving
rung with the file and line that wrote it. The full six-file layering:
[`use-cases/02-deploy-config/`](/use-cases/02-deploy-config).

## 03. API contract

A REST contract for a project-management SaaS: entities, endpoints,
request bodies keyed by status code, one error envelope. It is the
document an agent codes against and is corrected by: the agent emits
a candidate body, `aontu vet` reports what fails and where, and the
case's `repair.py` repairs it mechanically from the `--format json`
findings. Exit codes are verdict classes (0 valid, 1 invalid, 3
incomplete, 4 schema-side error), so a caller can branch before
reading a byte. A wire message is a `close()`d shape, so a surplus or
typo'd key is a conflict, not a silently ignored extra:

```aon
CreateUserRequest: close({
  email: $.types.Email
  name: $.types.DisplayName
  role: $.types.Role
  # Invitations send an email unless explicitly suppressed.
  send_invite?: boolean
})
```

`vet --at '$.msg.CreateUserRequest'` anchors on it directly. The
contract, the candidates, and the repair loop:
[`use-cases/03-api-contract/`](/use-cases/03-api-contract).

## 04. Schema evolution

A shared customer-profile schema across three released versions, with
a queue of proposed changes. `aontu breaking --against` is the
governance gate a schema registry needs: additive changes pass, a
narrowed constraint or an added required key exits 1 with a witness
naming both files, and a `must()` on the new side answers *undecided*
(exit 3) rather than guessing. The centrepiece is the two-release
rename: deprecate in v2, remove in v3. The v2 mark, from
`profile-v2.aon`:

```aon
phone?: deprecate(string, {
  msg: "free-form phone is unvalidated; write E.164 to contact.phone"
  use: "$.profile.contact.phone"
  since: "2.0.0"
})
```

The mark rides the value: `vet` warns with the data site when an
instance still uses the field, and `--allow-deprecated-removal` admits
the v3 deletion while keeping the finding visible at severity
`warning`. All three versions and the proposal queue:
[`use-cases/04-schema-evolution/`](/use-cases/04-schema-evolution).

## 05. RBAC policy

An authorization model for a multi-tenant SaaS, written as data the
engine checks: a permission catalog, an exhaustive role registry,
tenant plans, and agent-emitted candidates vetted against all of it. Every grant is a `refer()`-checked address, so a
hallucinated permission is a located refusal, and the registry is
`close()`d, so an invented role dies at review. The security rule "no
role holds the wildcard unless flagged privileged" is structural: a
role is a disjunction of two closed shapes:

```aon
Role: type(
  close({
    desc: string
    rank: integer & min(0) & max(100)
    tenantOwner: boolean
    privileged: true
    grants: unique() & [&: refer() & string]
  })
  | close({
    desc: string
    rank: integer & min(0) & max(100)
    tenantOwner: false
    privileged: false
    grants: unique() & [&: refer() & string & neq("$.permissions.admin_all")]
  })
)
```

The unprivileged branch excludes the wildcard from every grant with one
`neq()`, so a proposal granting it to a collaborator role is refused. A
grant is a **tree address**, which is what makes `refer()` a checked
foreign key against the permission catalog rather than a string
comparison. The registry and its attack proposals:
[`use-cases/05-rbac-policy/`](/use-cases/05-rbac-policy).

## 06. Kubernetes golden path

A platform team's golden path: product teams edit a 40-line service
model, and evaluating `main.aon` renders three Deployments and three
Services, around 340 lines of manifests, none written by hand. An
override composes like plain data (pin `replicas: 6` at the generated
path and the sibling defaults survive), `close()` seals the service
set against drift, and `vet` runs the org guardrails over the rendered
JSON. `pack()` makes a manifest per service, and a second pack merges
one authored column into every generated child:

```aon
deploy: close(pack($.svc.names, {
  apiVersion: "apps/v1"
  kind: Deployment
  metadata: name: key(2) # depth-counted by hand
  # ... the rest of the Deployment skeleton ...
}))

deploy: pack($.svc.version, {
  spec: template: spec: containers: [
    image: $.platform.registry + "/" + key(6) + ":" + _
  ]
})
```

The version column becomes the image tag through `_`, and drift in
either direction refuses: an entry with no service hits the sealed
set, a service with no entry leaves `image: string` ungenerable. The
whole generator: [`use-cases/06-k8s-golden-path/`](/use-cases/06-k8s-golden-path).

## 07. Event contracts

An order service's events, held the way a Kafka schema registry holds
them: one shared CloudEvents-flavoured envelope, one closed payload
shape per event type, a discriminated union, and a compatibility gate
between contract versions. Producers vet before
publishing, consumers vet a whole stream sample with one command, and
CI refuses a revision that breaks subscribers. Each event type is the
envelope, narrowed by conjunction and sealed:

```aon
OrderPaid: close($.Envelope & {
  type: "order.paid"
  payload: close({
    order_id: re("^ord-[0-9a-f]{8}$")
    payment_ref: re("^psp-[a-z0-9-]{4,40}$")
    amount_cents: integer & min(1)
    method: "card"|"sepa"|"paypal"|"invoice"
  })
})
```

Pinning `type` to one string is what makes the union discriminated,
and `close()` keeps surplus keys off the wire. The contract versions
and the stream samples:
[`use-cases/07-event-contracts/`](/use-cases/07-event-contracts).

## 08. Feature flags

The write-path case: a flag catalog with environment and tenant
overrides, mutated by `aontu model set` into an overlay file the reviewed base
files never absorb. Ten sets of the same path collapse to a single
overlay line under `--in-place`, `why` attributes the served value to
the overlay with rank annotations, and a hostile overlay is confined by
`--trust`. The kill switch is a concrete pin in the catalog, so no
overlay of any rank can flip it: `set` vets before writing and refuses
with the pinning site named:

```
$ aontu model set '$.flags.payments_legacy_gateway.enabled=true' --entry base.aon --overlay overlay.aon
verdict: invalid

$.flags.payments_legacy_gateway.enabled: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.flags.payments_legacy_gateway.enabled
  data: overlay.aon:2:48 (true)
  schema: base.aon:53:14 (false)
```

Exit 1, and the overlay is untouched (the case asserts both). The full
write loop: [`use-cases/08-feature-flags/`](/use-cases/08-feature-flags).

## 09. Agent tools

An agent platform's tool registry: six tools with closed argument
schemas, rate limits, and side-effect classes, plus a runtime
guardrail that vets each `{tool, arguments}` call at `$.guard.<tool>`.
The four vet verdicts are a dispatcher's decision table (valid:
dispatch; invalid: refuse, feed the findings back; incomplete: ask for
the missing argument; error: unknown tool), and the case drives the
real `aontu mcp` server over JSON-RPC too. The wire
schema is generated from the registry, so the two can never drift:

<!-- test: skip a fragment of 09-agent-tools, whose `registry.aon` this page does not ship; the case's own check.sh runs it -->
```aon
@"./registry.aon"

guard: pack($.argschemas, close({ tool:key() arguments:_ }))
```

`close()` survives the `_` clone, so a hallucinated argument on any
tool is a located `[aontu/closed]`. The registry, the calls, and the
MCP session: [`use-cases/09-agent-tools/`](/use-cases/09-agent-tools).

## 10. Data model

An order-to-cash domain: customers with 64-bit upstream ledger ids,
orders, invoices, money. One document is at once the vet schema, the
referential-integrity checker, and the seed-data generator; money is
the stress test the `0d` exact-decimal literals exist for. The price
book pins its own sums, so an engine that computed them inexactly
could not produce output at all.

<!-- test: scenario exact-money -->

The smallest such theorem, lifted from the case's `seed.aon`: write
it as `reconcile.aon`:

<!-- test: file reconcile.aon -->
```aontu
reconcile: centsPath: (10 + 20) & 30 # integer cents: exact
reconcile: exactPath: (0d0.1 + 0d0.2) & 0d0.3 # exact decimals: also exact
```

Evaluate it:

<!-- test: run -->
```sh
$ aontu reconcile.aon
{
  "reconcile": {
    "centsPath": 30,
    "exactPath": 0.3
  }
}
```

Binary64 arithmetic answers `0.30000000000000004` here; the pinned
`& 0d0.3` holds because `0d` values are exact, and the case's
`money-wire.aon` shows how that exactness crosses JSON. The same
schema is a code source: the case's `xf-domain.aon` walks its record
types into a component tree, one exported interface per record, with
the TypeScript spelled by the transform itself; `xf-order.aon` writes
the same walk as TypeScript and as Go, where `nom` and an acronym list
the document carries spell `ledgerId` as `LedgerID`, and an optional
field is a pointer with `omitempty`. Both are held against their
goldens by the byte gate. The
domain, the transforms and the failed attempts, kept executable:
[`use-cases/10-data-model/`](/use-cases/10-data-model).

## 11. Shared modules

The distribution story: a platform team's deployment contract,
published into a repository with `aontu publish`, acquired by a
consumer with `aontu sync`, and held by a one-line lockfile whose
three pins cover the bytes, the signed manifest and the meaning. The
canon pin survives a byte-different, meaning-identical module refactor
(a byte-hash lockfile breaks on exactly this), and a flipped default in
the vendored tree fails evaluation with both hashes named. A single
file can freeze the hash in the import string, with no `pkg.aon` and no
lockfile: the agent-sandbox mode:

<!-- test: skip a fragment of 11-shared-modules, which resolves against that case's module store; the case's own check.sh runs it -->
```aon
svc: @"corp.example/schemas/service#aon1-zFHnyVa1fA--g8hTx8lUUhaKzzRUNI--2nDheIMsSFs"
svc: spec: { name:"audit-log" owner:"sec-ops@corp.example" }
```

A tampered store is refused, with both hashes named:

```
module integrity: corp.example/schemas/service expected aon1-zFHnyVa1fA--g8hTx8lUUhaKzzRUNI--2nDheIMsSFs got aon1-NHmNT6r-Lhy8di9BgGNRfgwNFT3r5PgCZxCYnJ4F0Ws
```

The `#aon1-` pin resolves, verifies, and refuses a mangled hash with
the same integrity error. The publish gate and the whole vendoring
flow: [`use-cases/11-shared-modules/`](/use-cases/11-shared-modules).

## 12. Relations

An ETL pipeline DAG: four jobs, one relation (`feeds`, with its
written-out inverse `fedBy`). The whole thing is declared once, at the
field, and data documents stay plain JSON-shaped string lists, with no
per-link boilerplate. A cycle or a missing
inverse refuses at generation with a located finding naming the loop
or the exact absent entry, and `aontu reaches --relation feeds`
answers the closure question directionally over the same edges. The
declaration, from the case's `spec.aon`:

```aon
feeds?: rel($.spec.JobShape) & acyclic() & inverse(fedBy)
fedBy?: rel($.spec.JobShape)
```

`rel(t)` makes the field's strings checked entity addresses and flows
the shape into every target, `re()` rides onto every address, and the
graph atoms are decided at generation, where every edge is known. The
DAG, its refusals, and the append proposal:
[`use-cases/12-relations/`](/use-cases/12-relations).

## 13. Recursive schema

An approval chain: a `Step` is an approver, a decision, and optionally
the step that follows it. Writing `then?: $.spec.Step` inside `Step`
means the fixpoint, with no marker and no unrolled copies: the schema
applies at every depth, expanding one level per [meet](/docs/unification)
with concrete data, so `vet` descends exactly as far as the data does.
Canon and the `aon1-` hash stay symbolic: one finite string pins an
infinitely deep type. The vocabulary, one reference deep, from
`schema.aon`:

```aon
Step: approver: string & re("^[a-z]+@acme[.]example$")
Step: decision: *pending|pending|approved|rejected
Step: then?: $.spec.Step
```

A *required* recursive tail refuses at generation with
`recursion_unexpanded` at the exact position no finite document can
fill; guardedness is emergent, because the data decides. The chain,
vetted as plain JSON: [`use-cases/13-recursive-schema/`](/use-cases/13-recursive-schema).

## 14. JSON Schema export

JSON Schema is the bridge out: an MCP tool's `inputSchema` must be
one, structured-output APIs constrain generation to one, OpenAPI
embeds one. `aontu jsonschema` exports the unified value as draft
2020-12 on stdout and names every loss on stderr; `--strict` turns a
lossy export into exit 1, and a dangling reference exports nothing
rather than a partial schema.

<!-- test: scenario jsonschema-export -->

Write a tool's argument schema as `registry.aon` (trimmed from the
case's registry):

<!-- test: file registry.aon -->
```aontu
argschemas: read_file: close({
  path: string & re("^[A-Za-z0-9._/\\-]+$") & re("^[a-z]") & length(max(512))
  max_bytes?: integer & min(1) & max(1048576)
})
```

Export it as the tool's `inputSchema`:

<!-- test: run -->
```sh
$ aontu jsonschema --at '$.argschemas.read_file' registry.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "max_bytes": {
      "maximum": 1048576,
      "minimum": 1,
      "type": "integer"
    },
    "path": {
      "allOf": [
        {
          "pattern": "^[A-Za-z0-9._/\\-]+$"
        },
        {
          "pattern": "^[a-z]"
        }
      ],
      "maxLength": 512,
      "minLength": 0,
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}
```

The two `re()` calls cross as an `allOf` of patterns, the closed map
becomes `additionalProperties: false`, and the optional key stays out
of `required`, with stderr empty, nothing was lost. The three moods
of the bridge (exact, lossy, refused):
[`use-cases/14-jsonschema-export/`](/use-cases/14-jsonschema-export).

## 15. Code generation

The model is the source of the code. One catalogue of record types
feeds a Go generator, a TypeScript generator and a SQL generator, each
reading a different slice of it, and one component tree holds the
three files. A generator is a rule set: `emit` walks the records in
source order and each node contributes *children* (a blank line, a
head, one line per field at depth 1, a tail) which splice flat into
the `file` that holds them, so the transform owns every indent and
every terminator. Names like
`Email` and `credit_cents` are written in the model rather than
derived, because what a type is called in a target is a fact about the
model, not a rule in a template.

<!-- test: scenario code-generation -->

Write the model and one generator as `types.aon`:

<!-- test: file types.aon -->
```aontu
records: [
  {
    name: "Customer"
    fields: [{ n:"id" t:"string" go:"ID" } { n:"email" t:"string" go:"Email" }]
  }
]

%field = emit(_, {
  match: n: string
  body: [
    line(
      "\t" + .go + " " + match(.t, "string", "string", "integer", "int64")
      + ` \`json:"` + .n + `"\``
    )
  ]
})

%record = emit(_, {
  match: name: string
  body: ["type " + .name + " struct {" emit(.fields, %field) "}"]
})

out: file("types.go", emit($.records, %record))
```

The generator answers a **component tree**: a `File` holding the `Line`
nodes the model produced, which `aontu render` writes to disk.

<!-- test: run -->
```sh
$ aontu model get $.out types.aon
{
  "children": [
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "type Customer struct {"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "\tID string `json:\"id\"`"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "\tEmail string `json:\"email\"`"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "}"
      }
    }
  ],
  "cmp": "File",
  "props": {
    "name": "types.go"
  }
}
```

A rule set rather than `pack`, because list order is source order and
map keys sort by code point; a nested `emit` splices its children, so
the file's lines arrive flat. A bare string child is a `Line`, which is
why the two rules above read as text. The three generators, their
goldens, and a check that both ports answer byte-identical files:
[`use-cases/15-code-generation/`](/use-cases/15-code-generation).

## 16. Module deps

A codebase's own module graph: twelve modules across four layers,
where the architecture rule is that nothing may depend on a layer
above it. The rule is a shape rather than a checking pass. `rel(t)`
flows its target shape into every module an edge names, so a core
module's `dependsOn` carries `layer: "core" | "util"` to the far end,
and a module that says `layer: "feature"` cannot meet it. Each layer
is one line of schema and one disjunction, from `spec.aon`:

```aon
Core: $.spec.Mod & { layer:"core" dependsOn?:rel($.spec.CoreDep) }
CoreDep: { kind:mod layer:"core"|"util" }
```

An upward edge then refuses at generation as an ordinary conflict naming
both sides, and a loop between two modules of the *same* layer (which the
layering allows) refuses under `acyclic()`. The case pins the refusal in
both declaration orders. The same edges are drawn two ways and pinned as
goldens: a dependency tree, drawn by [`aontu view
tree`](/docs/reference-api#aontu-view) with derived roots and every
repeated subtree elided the way `cargo tree` elides one, and a
dependency-structure matrix. The layered codebase, its refusals, and its
views: [`use-cases/16-module-deps/`](/use-cases/16-module-deps).

## 17. Lambda handlers

Twelve services on one message wire, each deployed as its own Lambda
handler: the same forty lines with three things that vary per
service. The generator is the handler file itself, as one rule set in
the canonical form a template file expands into: the body is the
file, line for line, and a value reaches a line through `replace`
rather than a hole:

```aon
%handler = emit(_, {
  match: name: string
  esc: sq
  replace: SERVICE: .name
  body: [
    "function complete(seneca: any) {"
    emit(.listen, {
      match: pin: string
      esc: sq
      replace: PIN: .pin
      body: ["  seneca.listen({type:'sqs',pin:'PIN'})"]
    })
    "}"
    "  let seneca = await getSeneca('SERVICE', complete)"
  ]
})
```

`SERVICE` and `PIN` are ordinary TypeScript in the body; the map says
which strings stand for a value, and `esc: sq` escapes each for the
single-quoted literal it lands in, so a service named `o'brien`
compiles. A service with no S3 events gets no gateway hook, because a
dispatch over an empty selection emits nothing, and the two lines of
two spaces in every handler survive because a line is verbatim. An
index names the services in the model's order through `each`, with a
constant spelled by `join(each(split(_, "-"), upper(_)), "_")`. All
thirteen files are held against their goldens by the byte gate in both
ports: [`use-cases/17-lambda-handlers/`](/use-cases/17-lambda-handlers).
The same generator is there twice: `gen.aon` is the canonical aontu
above, and `handler.ts` is that generator written as a Lambda handler,
with its aontu on marked lines. Both answer the same thirteen files.

## 18. Role permissions

Which role may change which subtree, asked before the change.
`roles.aon` is a `close()`d role vocabulary (`desc`, `allow`, `deny?`)
and a closed registry of four roles, `admin`, `dev`, `product` and
`qa`, over the service model in `model.aon`: services with an owner, a
tier, replicas and a description, a deploy layer with per-region
replicas, feature flags and a tests block. The vocabulary and the
`dev` role, from `roles.aon`:

```aon
Role: type(close({ desc:string allow: [&: string] deny?: [&: string] }))

roles: close({
  &: $.Role
  dev: {
    desc: "Runs the services: scaling and deployment, never ownership or tier"
    allow: ["$.services" "$.deploy.*.replicas"]
    deny: ["$.services.*.tier" "$.services.*.owner"]
  }
})
```

The agent skill asks `aontu allow` with the very assignment it is
about to hand `set`, and writes on exit 0 alone. A proposal at
`$.services.auth.replicas` lands in the overlay; one at
`$.services.auth.tier` is refused with the rule named, and so is one at
`$.services.auth`, because a change there could rewrite the tier:

```
$ aontu allow --role dev roles.aon '$.services.auth.tier="standard"'
verdict: refused
role: dev
$.services.auth.tier: refused by $.roles.dev.deny.0 ($.services.*.tier)
```

Exit 1, and `aontu model why '$.roles.dev.deny.0' roles.aon` names the line
that wrote the rule. A role-model edit that puts a string where the
`allow` list goes, or adds a key the closed vocabulary does not
declare, is exit 4 with the engine's own finding, so the rules are
held to the same shape as everything else. The roles, the proposals
and the skill:
[`use-cases/18-role-permissions/`](/use-cases/18-role-permissions).

Where a page in these docs and a use case disagree, the case wins (its
checks run; the page does not). File the docs bug.

---

# Unification

_The one operation, and the vocabulary for it: meet, top, bottom, the lattice, and the three laws that make order irrelevant._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/unification.md · Page: https://aontu.dev/docs/unification

aontu has one operation. Every construct in the language (a second
statement for the same key, an `&`, an included file, a spread applied
to a child, a schema checked against data) is that one operation
under a different spelling. It is called **unification**, and this page
is what it means.

The [language reference](/docs/reference-language) states the rules.
This page explains the idea they come from, and defines the vocabulary
the rest of the documentation uses: *meet*, *top*, *bottom*, *lattice*,
*residual*, *subsumption*.

## Values are ordered by how much they say

Start with an ordering rather than an operation. Of any two aontu
values, one may be **more specific** than the other: it admits fewer
possibilities.

`integer` admits every whole number. `8080` admits one. So `8080` is
more specific than `integer`, and `integer` is more general than
`8080`. Write that as `8080 ⊑ integer`.

The ordering is partial, not total: `8080` and `"auto"` are not
comparable in either direction, and neither is `min(1024)` against
`max(65535)`. Most pairs of values have no ordering between them at
all. That is the normal case, and it is what makes the next paragraph
do any work.

## The meet is the answer to "both"

Given two values, the **meet** is the most general value that is at
least as specific as both. Written `a & b`. It is the answer to a
question you ask constantly without noticing: *what is still true if
both of these hold?*

`integer & 8080` is `8080`: the only whole number that is also `8080`.
`integer & min(1024)` is neither of its operands: it is a third value,
`integer & min(1024)`, still waiting to be narrowed. A value in that
state is a **residual**: it holds real information and is not yet one
concrete answer.

<!-- test: scenario unification-meet -->
```aon
port: integer
port: min(1024)
port: 8080
```

```json
{ "port": 8080 }
```

Three statements about one key, met into one value. The engine never
chose between them and never overwrote one with another; it asked what
satisfies all three.

"Meet" is the standard name for this operation in order theory, and
aontu's error messages use it. When you read *"a constraint is the meet
of bound atoms"*, it is this: the one value that carries every
constraint at once.

## Top and bottom

An ordering like this needs two endpoints, and both are ordinary
values you can write.

**`top`** is the most general value: it admits everything. It is what an
unconstrained field is, and it is the identity of the meet: `top & x` is
`x`, for every `x`. A field that is still `top` at the end of a run says
nothing, so it cannot be generated.

**`nil`**, also called **bottom** and written `⊥` in order theory, is the most
specific: it admits nothing. It is what a failed unification produces.
`1 & 2` is `nil`, because no value is both. `nil` carries the error
that made it and cannot be generated either.

Every other value sits between them, under the kind it belongs to:

<figure class="diagram"><div class="diagram-frame">
<svg xmlns="http://www.w3.org/2000/svg" class="av" viewBox="0 0 576 222" width="576" height="222" role="img" aria-label="Value lattice at $: 0 value(s) placed">
<style>.av{font-family:ui-monospace,Menlo,Consolas,monospace;font-size:13px}.av-t{fill:var(--av-ink,#1f2328)}.av-m{fill:var(--av-muted,#6e7781)}.av-box{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule,#8c959f);stroke-width:1}.av-cell{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-direct{fill:var(--av-ink,#1f2328);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-closure{fill:var(--av-closure,#9ec5fe);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-unmirrored{fill:var(--av-warn,#e3b341);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-line{stroke:var(--av-rule,#8c959f);stroke-width:1;fill:none}.av-up{stroke:var(--av-alert,#d1242f);stroke-width:1.5;fill:none;stroke-dasharray:4 3}.av-dot{fill:var(--av-ink,#1f2328)}.av-hole{fill:var(--av-bg,#f6f8fa);stroke:var(--av-rule-faint,#d0d7de);stroke-width:1}.av-bar{fill:var(--av-bar,#57606a)}</style>
<path d="M288 34V51H40V68" class="av-line"/>
<path d="M40 94V111H40V128" class="av-line"/>
<path d="M288 34V51H248V68" class="av-line"/>
<path d="M248 94V111H120V128" class="av-line"/>
<path d="M248 94V111H192V128" class="av-line"/>
<path d="M248 94V111H272V128" class="av-line"/>
<path d="M248 94V111H376V128" class="av-line"/>
<path d="M288 34V51H472V68" class="av-line"/>
<path d="M288 34V51H536V68" class="av-line"/>
<path d="M40 154V171H288V188" class="av-line"/>
<path d="M120 154V171H288V188" class="av-line"/>
<path d="M192 154V171H288V188" class="av-line"/>
<path d="M272 154V171H288V188" class="av-line"/>
<path d="M376 154V171H288V188" class="av-line"/>
<path d="M472 94V171H288V188" class="av-line"/>
<path d="M536 94V171H288V188" class="av-line"/>
<rect x="268" y="8" width="40" height="26" class="av-cell"/>
<text x="288" y="26" text-anchor="middle"><tspan class="av-t">top</tspan><tspan class="av-m"></tspan></text>
<rect x="8" y="68" width="64" height="26" class="av-cell"/>
<text x="40" y="86" text-anchor="middle"><tspan class="av-t">string</tspan><tspan class="av-m"></tspan></text>
<rect x="216" y="68" width="64" height="26" class="av-cell"/>
<text x="248" y="86" text-anchor="middle"><tspan class="av-t">number</tspan><tspan class="av-m"></tspan></text>
<rect x="436" y="68" width="72" height="26" class="av-cell"/>
<text x="472" y="86" text-anchor="middle"><tspan class="av-t">boolean</tspan><tspan class="av-m"></tspan></text>
<rect x="512" y="68" width="48" height="26" class="av-cell"/>
<text x="536" y="86" text-anchor="middle"><tspan class="av-t">null</tspan><tspan class="av-m"></tspan></text>
<rect x="8" y="128" width="64" height="26" class="av-cell"/>
<text x="40" y="146" text-anchor="middle"><tspan class="av-t">path()</tspan><tspan class="av-m"></tspan></text>
<rect x="84" y="128" width="72" height="26" class="av-cell"/>
<text x="120" y="146" text-anchor="middle"><tspan class="av-t">integer</tspan><tspan class="av-m"></tspan></text>
<rect x="164" y="128" width="56" height="26" class="av-cell"/>
<text x="192" y="146" text-anchor="middle"><tspan class="av-t">float</tspan><tspan class="av-m"></tspan></text>
<rect x="224" y="128" width="96" height="26" class="av-cell"/>
<text x="272" y="146" text-anchor="middle"><tspan class="av-t">biginteger</tspan><tspan class="av-m"></tspan></text>
<rect x="328" y="128" width="96" height="26" class="av-cell"/>
<text x="376" y="146" text-anchor="middle"><tspan class="av-t">bigdecimal</tspan><tspan class="av-m"></tspan></text>
<rect x="268" y="188" width="40" height="26" class="av-cell"/>
<text x="288" y="206" text-anchor="middle"><tspan class="av-t">nil</tspan><tspan class="av-m"></tspan></text>
</svg>
</div><figcaption>The value lattice: top at the join; string, number, boolean and null under it; path() under string; integer, float, biginteger and bigdecimal under number; nil at the meet, below every kind.</figcaption></figure>

`"ada"` sits under `string`, `1` under `integer`, `0d0.1` under
`bigdecimal`, `true` under `boolean`: each one a point below the kind
that admits it, and every one of them above `nil`.

A structure with a top, a bottom, and a meet for every pair is a
**lattice**, which is where the term comes from. The
[value lattice](/docs/reference-language#the-value-lattice) section of
the language reference gives the rules, kind by kind.

## Three laws, and what they buy you

The meet obeys three laws. They are not decoration: everything aontu
claims about being safe to split, merge and re-order rests on them.

**Idempotent.** `a & a` is `a`. Saying a thing twice says it once.

```aon
region: string
region: string
region: "eu-west-1"
region: "eu-west-1"
```

```json
{ "region": "eu-west-1" }
```

**Commutative.** `a & b` is `b & a`. Neither operand wins by being
first.

**Associative.** `(a & b) & c` is `a & (b & c)`. Grouping does not
matter either.

Take the three together and a document has no evaluation order to
reason about. There is no "later key wins", no cascade, no
precedence table, no question of which file was loaded first. Write
the shape as `shape.aon`:

<!-- test: file shape.aon -->
```aon
port: integer
port: min(1024)
```

the pin in another, `pin.aon`:

<!-- test: file pin.aon -->
```aon
port: 8080
```

and load them in one order as `a.aon`:

<!-- test: file a.aon -->
```aon
@"./shape.aon"
@"./pin.aon"
```

and the other order as `b.aon`:

<!-- test: file b.aon -->
```aon
@"./pin.aon"
@"./shape.aon"
```

<!-- test: run -->
```sh
$ aontu a.aon
{
  "port": 8080
}
$ aontu b.aon
{
  "port": 8080
}
```

The same document, twice. This is the property that makes an overlay
file, a vendored module and a machine-generated fragment all safe to
combine: none of them can silently outrank another by arriving later.

It is also why a conflict is reported rather than resolved. If `a: 1`
and `a: 2` both hold, no order of evaluation makes one of them correct,
so the engine refuses instead of picking:

<!-- test: skip the framed multi-line error is shown in Read a conflict error -->
```
[aontu/scalar_value]: Cannot unify values at path $.a
```

A last-write-wins merge would have answered `2` here, and been wrong
about it in a way nothing could detect.

## Subsumption is the same order, asked as a question

Once values are ordered, you can ask about the order directly rather
than computing with it. **Subsumption** is that question: does `A`
admit everything `B` admits? Every instance the specific document
allows, does the general one allow too?

That is `B ⊑ A`, the same relation the meet is built from, and it has
an equivalent phrasing in terms of the meet: `A` subsumes `B` exactly
when `A & B` is `B`. Nothing new is needed to decide it.

The [`aontu subsume`](/docs/reference-api#aontu-subsume) verb answers it
for two documents, and [`aontu breaking`](/docs/reference-api#aontu-breaking)
runs it between a document and its own earlier version, which is what
makes "is this schema change breaking?" a question with a mechanical
answer.

## What aontu does not have

A lattice has a second operation, the **join**: the most *specific*
value at least as general as both, the answer to "either". aontu's
disjunction `a|b` looks like a join and is deliberately not one: it
keeps both alternatives as a value that is still undecided, rather than
collapsing them to a common supertype. `1|2` stays `1|2`; it does not
become `integer`.

The difference matters when generating: an unresolved disjunction has
no single value, so generation refuses rather than guessing. A real
join would have thrown away exactly the information that refusal
depends on.

## Where to go next

- [The value lattice](/docs/reference-language#the-value-lattice). The
  normative rules, kind by kind.
- [Conjunction `&`](/docs/reference-language#conjunction-). The operator,
  exhaustively.
- [Read a conflict error](/how-to/read-a-conflict-error). What the
  engine prints when a meet lands on `nil`, and how to find the two
  statements responsible.
- [Explanation](/docs/explanation). Why the engine is built the way it
  is, including where the ordering is deliberately incomplete.

---

# Explanation: how and why aontu works

_How and why the engine works the way it does: the only part of the documentation that argues about trade-offs._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/explanation.md · Page: https://aontu.dev/docs/explanation

aontu uses one operation to combine schemas, defaults, and data. This
page explains that choice and the implementation costs it introduces.
For exact rules, use the [language reference](/docs/reference-language);
for a task, choose a [how-to guide](https://github.com/aontu-lang/aontu/blob/main/docs/how-to/).

## The core idea: one operation, three jobs

A configuration can state what values are allowed, supply defaults,
and set concrete values for an environment. aontu follows
[CUE](https://cuelang.org/) in expressing all three as values ordered
in a [lattice](/docs/unification). **Unification** combines those values.

- A schema like `port: integer` is just a value (the set of all
  integers).
- A default like `port: *8080` is just a value (a preference annotation
  on `8080`).
- Data like `port: 9090` is just a value.

Combining any of them is the same act: take the **greatest lower bound**
of the two values: the most general value that is at least as specific
as both. When that bound exists you get a result that honours every input
at once; when it does not, you get a precise error. There is no
precedence to remember and no order dependence: `a & b` always equals
`b & a`, and re-applying a fact changes nothing (`a & a == a`).

This is why the same document can be schema, defaults, and data
simultaneously, and why merging two configurations can never silently
pick a winner: it either narrows to a consistent answer or fails loudly.

## The lattice

Values are ordered from general to specific:

```
top  ⊐  string ⊐ "ada"
     ⊐  number ⊐ integer ⊐ 1
     ⊐  boolean ⊐ true
                         ⊐ … ⊐  nil (⊥)
```

- **`top`** sits above everything and is the unit element: `x & top == x`.
  An unconstrained field *is* `top`.
- **`nil`** sits below everything; it is what you get when two values have
  no common lower bound. `nil` carries a message and poisons generation.
- Unification walks *down* the lattice. `number & integer` → `integer`
  (more specific); `integer & 1` → `1`; `1 & 2` → `nil` (no value is both).

Disjunction (`|`) builds a small lattice of alternatives; unifying a
concrete value against it keeps the branches that survive and discards
the rest. Preference (`*`) is a tie-breaker annotation that says "if the
choice is otherwise unforced, pick me".

## The pipeline

Both implementations share the same three-stage pipeline:

```
source text ──parse──▶ Val AST ──unify (fixpoint)──▶ unified Val ──generate──▶ native value
                                                              ├──canon──▶ source-like text
                                                              └──ask────▶ vet · get · why · subsume · hash
```

1. **Parse.** [`@tabnas/jsonic`](https://github.com/tabnas/jsonic) plus
   the `expr`, `path`, `multisource`, and `directive` plugins turn relaxed
   JSON-with-operators into a tree of `Val` nodes: `MapVal`,
   `ConjunctVal`, `RefVal`, `ScalarKindVal`, and so on. Operators like
   `&`, `|`, `*`, `.`, `+` are configured as parser expression operators
   with explicit binding powers, which is how precedence is defined (see
   [`ts/src/lang.ts`](https://github.com/aontu-lang/aontu/blob/main/ts/src/lang.ts)).

2. **Unify.** A fixpoint loop repeatedly unifies the tree with `top`
   until it stops changing or an error appears. Each `Val` subclass knows
   how to unify itself with a peer.

3. **Generate / canon.** A converged tree is either emitted as a native
   value (`gen`) or rendered as canonical source (`canon`).

The third arrow fans out instead of adding a fourth stage. `vet`, `get`,
`why`, `subsume` and `hash` all interrogate the *same* converged tree
that `generate` renders, which is why they agree with one another by
construction rather than by care, and why none of them can be a partial
evaluation. What they are *for* is argued below, in
[Why there is a verb surface](#why-there-is-a-verb-surface).

### Why unification runs to a fixpoint

References make a single pass insufficient. Consider:

```aon
a: v: $.b.v
b: v: $.c.v
c: v: 99
```

On the first pass `$.b.v` resolves to *another reference* (`$.c.v`),
which only resolves to `99` once `c` has settled. So unification runs in
rounds: each pass refreshes the root and re-resolves references against
the latest tree, and the loop ends when every node reports "done"
(`dc == DONE`) or an error is collected. The loop is bounded (a small
maximum pass count) so a pathological model terminates rather than
spinning.

### The dispatch ladder

The engine's dispatch is one binary function, `unite(a, b)` (see
[`ts/src/unify.ts`](https://github.com/aontu-lang/aontu/blob/main/ts/src/unify.ts) and
[`go/unify.go`](https://github.com/aontu-lang/aontu/blob/main/go/unify.go)), and it is a careful ladder of cases:

- degenerate/`top` cases first (unit element);
- `nil` short-circuits (bottom is absorbing);
- **complex** values that know how to "absorb" a peer (conjunction,
  disjunction, reference, preference, function) drive their own
  `unify`;
- otherwise the two concrete values are matched directly (equal scalars
  collapse; mismatches become `nil`).

Each `Val` type implements only the cases it understands and defers the
rest by unifying with `top`. This keeps the type-specific logic local:
`MapVal.unify` knows about keys and spreads, `DisjunctVal.unify` knows
about trying alternatives, `ScalarKindVal.unify` knows that `number`
subsumes `integer`, and none of them needs to know about the others.

### Distribution and trials

Conjunction distributes over disjunction: `x & (a | b)` tries `x` against
each alternative independently and keeps the survivors. The
implementation runs each alternative as a *trial* with its own throwaway
error bucket: if the trial collects an error, that branch is dropped.
The TypeScript version optimises this hot path with a shared "trial nil"
sentinel and save/restore of the error array instead of cloning a context
per alternative, because schemas with many disjunctions
(`GET | PUT | POST | …`) make this the busiest path in the engine.

## Recursive schemas and residuals

Unification needs a word for a value that is still waiting. A
**residual** is that word, and this page is its definition of record: a
residual is a value that has absorbed everything said about it so far
and still needs more information to be decided: a `min(1)` no number
has reached yet, a reference whose target a later include will declare,
an entity address whose entity has not yet appeared. Residuals are what
let the fixpoint loop stop without guessing: each pass either brings
that discharges one or leaves it standing, and the ones still standing
when the loop settles are the document's open questions, judged by
whatever consumes the tree next: `vet` reports them as its
`incomplete` verdict, generation refuses one left in a demanded
position, and canon prints each as it was written.

One residual deserves its own argument, because it looks like the thing
this engine most loudly refuses. A reference to a value from **inside
that value** (`$.schema.Step` written inside `Step`) means the fixpoint: a
`Step`, by this very definition. The engine's cycle detector always
recognised the shape; what changed is the response. Where the prefix
test used to refuse with `path_cycle`, it now answers a **recursive
residual**, a deferred reference carrying its target exactly as a
constraint atom carries its bound. When concrete data
[meets](/docs/unification) the residual, it expands the definition one
level (per destination, under the same clone discipline spreads use) and
the clone's own self-reference is again a residual. Each meet with data
consumes one level of data:

```aontu
schema: hide({ Step: { label:string then?:$.schema.Step } })
doc: $.schema.Step & { label:"a" then: { label:"b" then:label:"c" } }
```

```json
{"doc": {"label": "a", "then": {"label": "b", "then": {"label": "c"}}}}
```

The schema is one reference deep; the checks descend exactly as far as
the data does, and no further. Mutual recursion needs nothing extra:
once `$.B` expands inside `A`, the `$.A` in the clone is a
self-reference at its landed position and residuates by the same rule.

That expansion rule is also the termination argument, and it has to be,
because the [limitations below](#limitations-and-trade-offs) refuse
user-defined functions on termination grounds. The two rulings are
consistent because they license different recursions. A recursive
*function* is a fixpoint of the program, and whether its expansion ends
is undecidable: admitting one would demote "every aontu program
terminates" to "most do", and
[Termination is part of the offer](#termination-is-part-of-the-offer)
says what that demotion costs. A recursive *schema* is structural
descent on the data: an expansion happens only at a meet with concrete
structure and consumes one level of it, and data is finite, so the
expansions along any path are bounded by the data's depth. The one
shape that escapes the bound (two recursive definitions unified
directly, with no concrete layer between them to consume) is caught by
the depth budget, and exhausting it refuses with
`[aontu/recursion_budget]`, naming the recursion. The guarantee
survives as the smaller of the data's depth and the budget.

Guardedness is **emergent**: the engine never analyses a schema for
well-foundedness, because the data decides. Under an optional key
(`then?:`) an unexpanded residual drops with its key; under
`*null | $.Node` the preference generates; and a required recursive
field that no data reached refuses at generation, per instance, at the
exact position no finite document can fill:

```
schema: hide({Step: {label: string, then: $.schema.Step}})
doc: $.schema.Step & {label: "start"}
    → refused: [aontu/recursion_unexpanded] at $.doc.then
```

A static well-foundedness check was considered and declined: it would
need an analysis the lattice never needed, and the per-instance refusal
names the same fix at the place the author feels it.

In canon and the `aon1-` hash the recursion stays **symbolic**: the
residual prints as the reference the author wrote:

```
schema: hide({Step: {label: string, then?: $.schema.Step}})
    → canon: {"schema":{"Step":{"label":string,"then"?:$.schema.Step}}}
```

So the canonical form of a recursive schema is finite, reparses to
itself, and the hash pins the mu-form: one string names an infinitely
deep type, which is what makes the hash usable as a schema version pin.
This is a documented exception to the hash form's resolve-everything
rule, and a principled one: a recursive reference is the fixpoint
binder, and the binder *is* its own resolved form.

The rules are in the reference under
[Recursive references (fixpoints)](/docs/reference-language#recursive-references-fixpoints);
the recipe is
[Define a recursive schema](/how-to/define-a-recursive-schema); and
the live version, an approval chain checked at every depth, is
[use-cases/13-recursive-schema](/use-cases/13-recursive-schema).

## Immutability

A foundational rule, stated right on the base class: **`unify` must not
mutate its operands.** Unification returns a *new* value; the inputs are
left intact. This is what makes order-independence and the fixpoint loop
sound: a value can be unified many times, against many peers, across
many passes, and shared structurally between branches, without one
unification corrupting another. Cloning carries a value to a new path
(references resolve relative to where a value *is*), but the original is
never altered in place.

## Marks: separating schema from data

Two boolean **marks** ride along with every value: `type` and `hide`.
Both leave *what* a value unifies to alone and decide only whether it is
*emitted*. A `type`-marked field is schema and a `hide`-marked field is a
working value: both are omitted when their enclosing map is generated,
yet both still constrain unification. This is how a single document can
carry its own schema inline without that schema leaking into the output,
and why `copy()` (which clears the marks) is the way to turn a schema
node back into emittable data.

## Linking and relations

A document is a tree, and a tree gives every value exactly one name:
its path. The payments service is described by the catalog (owner,
tier) and by the deployment (image, replicas), in two files, under two
paths that never mention each other, and both descriptions are about
one thing. Unification is path-aligned, so on their own the two never
meet, and a contradiction between them survives in silence.

Bringing them into contact is a **reference**, which is to say it is
something an author writes at one of the two sites. The shape, trimmed
from the [service catalog use
case](/use-cases/01-service-catalog):

```aontu
catalog: pay: tier: 1
deploy: pay: $.catalog.pay & { replicas:3 }
```

```json
{"catalog": {"pay": {"tier": 1}},
 "deploy": {"pay": {"replicas": 3, "tier": 1}}}
```

The deploy view now holds the whole service, and a contradiction between
the views (the catalog pinning `tier: 1` where the deployment claims
`tier: 2`) is an ordinary located error. That failure mode is the
argument. The alternative is an identity link bolted on beside the data,
`owl:sameAs` style, and such a link cannot fail: asserting sameness
costs nothing to be wrong about, each store keeps its own copy, and
drift between the copies is found by whoever gets paged. Making the
claim *inside* the operation the engine already trusts means it is
re-checked on every contact, and the commonest enterprise lie (two
systems silently disagreeing about one thing) dies at evaluation instead
of in production.

The language once had a stronger form of this: `id(name)`, a global
second name, with every node carrying it unified into every other. It is
retired. A reference catches the same contradiction at the same site,
and the global name cost more than it bought: a model carrying one could
not be **instantiated twice**, because two mounts of one file were one
entity and the second one's overrides were contradictions. The tree is
the namespace, and a tree lets you have two of something.

Relations follow the same instinct: an edge is data on a **field**, and
the field declares what its data means. `rel(t)` on a field says the
field's strings are entity addresses; each must resolve in this
evaluation, and `t`, when given, is unified *into* every target.
(Check-only semantics would be non-monotone (true, then false as the
target grows) so referring to something as a `Service` makes it one,
and a target that cannot be one fails with an ordinary located error.)
The predicate, the relation's name, is the key the `rel()` sits on:
declared once, in the schema, never inferred. The first landed design
inferred it ("the nearest non-numeric key above the link") and the
heuristic answered wrongly for map-valued relations, which meant two of
an edge's three parts were guesses and only the object was written.
Declaration also buys the property `vet` needs: with the schema side
carrying the `rel()`, a data document is plain JSON-shaped, links and
all, with no aontu spelling in it.

The graph properties are where the lattice draws a line worth arguing.
`acyclic()` and `inverse(name)`, conjoined at the same field, declare
properties of the whole edge set, and both are global and non-monotone,
because one more edge is more information, and one more edge can turn
an acyclic graph cyclic. The lattice guarantee is that more information
never falsifies what has been observed, so a constraint that could
answer true and then false is one unification may not hold, and the
engine must not refuse early. The atoms are therefore **lattice-inert**
declarations: during unification they only register the predicate and
ride the field through meets, and the verdict lands at **generation**,
where the edge set is complete: the same settle point the sizing atoms
use:

```
a: { feeds: rel() & acyclic() & ["$.b"] }
b: { feeds: rel() & [path($.a)] }
    → refused: [aontu/relation_cycle] at $.a.feeds
```

A declaration that binds at generation also repairs an old
embarrassment: in the first design, plain generation happily emitted a
cyclic model and only the `relations` verb noticed, so `acyclic` was
advisory: a constraint the author wrote into the document that the
document did not enforce.

That first design kept its relation declarations under a `relations:`
key at the document root, a plain key that one verb's pass knew by
convention and nothing else in the engine knew at all. Retiring it
follows one rule: **the tree is user space.** A plain, spellable key never carries
engine-assigned meaning at any depth; reserved meaning rides only on
syntax an author visibly opts into, which `rel()` and the atoms are. The
retirement bought two concrete things. A document that writes
`relations:` today has written ordinary data. And because the
declarations now live in the lattice, they reach canon and the `aon1-`
hash, so a pin distinguishes two documents that disagree about their
relations: under the magic key the declaration's *meaning* lived
outside the hash's reach, in the verb.

The precise rules are the reference's
[Linking](/docs/reference-language#linking-the-tree-is-the-namespace) and
[Declared relations](/docs/reference-language#declared-relations)
sections; the live versions are
[use-cases/12-relations](/use-cases/12-relations) (an ETL pipeline
DAG, one relation with its inverse) and
[use-cases/01-service-catalog](/use-cases/01-service-catalog) (the
two-view catalog this section's example was trimmed from).

## Why there is a verb surface

A definition that can only be *evaluated* answers exactly one question:
what is the value? That is enough when a person reads the answer and a
program consumes it. It stops being enough when the thing on the other
end is writing the document as well as reading it, because then the
interesting questions are all the other ones. Does this data hold
against that definition, and *where* does it not? What does it say at
this one path? Why does it say that: who wrote the value that made it
so? Has its meaning changed since the pin you recorded? Can you change
it without breaking somebody downstream?

Every one of those is already answerable from the converged tree. The
source sites are on the nodes, the contributions met at known paths,
the canon is a deterministic rendering. Declining to expose them leaves
the questions standing, and pushes every consumer into re-deriving the
answers from generated JSON, badly and out of band. A definition that
can validate, be queried, explain itself and be diffed has become
ground truth that something else can act on, and the verbs are what
turn a document into that. The roster is in the
[API reference](/docs/reference-api#command-line-interface); what follows
is why it has the shape it has.

### The emit → validate → repair loop

One loop explains most of the surface. Something writes a document,
[`vet`](/docs/reference-api#aontu-vet) says what does not hold and where,
the author (human or otherwise) repairs it and goes round again.
Taking that loop seriously decides several things that would otherwise
be arbitrary.

**Exit codes are verdict classes** rather than a pass/fail bit, because
the three ways to fail call for three different next moves. A
contradiction (`invalid`) means repair what you emitted. An unsatisfied
truth (`incomplete`) means keep writing: nothing is wrong yet, the
document is merely unfinished. An unusable schema (`error`) means stop:
the fault lies outside the data, and another round of repair cannot
reach it. Collapsing those into "failed" discards exactly the bit the
repairing end needs in order to choose. For the same reason a finding
labels its two sites by provenance instead of by source order, and puts
the data's site first: that is the one you are meant to edit.

**[`why`](/docs/reference-api#aontu-model-why) is the positive twin of a failure
report.** An error explains what did not unify; `why` explains what
did, listing the values that met at a path with the site each was
written at, in source order. It exists because "the value is 3" is not
actionable and "a spread offered `*1|integer` here, and this line
pinned `3`" is. The same record is what the language server can append
to a hover and what the MCP tool of that name returns: one answer,
three ways in.

**[`get`](/docs/reference-api#aontu-model-get) buys the size of the answer
rather than the cost of it.** Unification has no partial mode (the
whole document converges or none of it does) so a query verb cannot be
an optimisation, and it would be dishonest to present it as one. It is
a way for a reader with a small question to receive a small answer,
which for a consumer paying by the token is no small thing. Its shape
views are held to a stronger claim than "a summary": each is itself a
valid document that *subsumes* the truth, so a projection may
generalise but may never mislead.

**[`set`](/docs/reference-api#aontu-model-set) appends by default**, and that
follows from the lattice rather than from a gap in the tooling. Because
unification is order-independent, a change written into a second file
is the same value as the same change written into the first, so an
overlay needs no format-preserving rewriter, and cannot damage the
document it is changing.

What appending cannot do is override a value that is already **pinned**:
the lattice refuses, because unification only narrows. That was a real
hole rather than a principled refusal, and an embarrassing one: the
commonest validation failure of all is "the data says the wrong thing",
and the verb built for repair could only fill holes.

`--in-place` closes it with a targeted splice: new text written over the
span where the author spelled the value, every other byte untouched. The
prerequisite the rewriter had long been deferred behind, a
comment-preserving CST, turned out to belong to a different
job: re-serialising a document needs one, and replacing one value
serialises nothing, which is why comments and layout survive without
ever being read. What the splice does need is to be right about the
bytes, and the rule that decides it generalises past this verb: instead
of enumerating which spans are safe to write over (a list is a thing to
be incomplete about), the candidate text is parsed on its own and
required to mean what the contribution meant, so the same unifier that
produced the value rules on whether the text is the whole of it, and the
answer cannot drift from the engine.

Rewriting stays **opt-in** for the reason appending was preferred in the
first place: appending is reversible in a way overwriting is not, so the
flag is asked for, never inferred. Where a span cannot be established (a
compound spelling, a path reached through a reference) the assignment
appends exactly as it would have without the flag, and says why; an
overlay that loads another document is refused outright, because a
position inside an include can collide with a position in the overlay,
and the span check would pass while lying about the place. Refusing to
edit is always safe; editing the wrong bytes never is. The
mechanics (span verification, the warning vocabulary, what counts as an
editable literal) are specified with [`aontu
set`](/docs/reference-api#aontu-model-set) in the API reference.

### What the hash pins

[`hash`](/docs/reference-api#aontu-hash) answers "has this changed?" over
what a document *means* rather than over the bytes it is stored in.
Reformat it, reorder its keys, split it into three files pulled back
together by `@"…"` includes, and the pin holds; flip one default and it
moves. That is only possible because canon renders the converged tree
rather than the source text.

The trade is real and taken deliberately. Canon is a deterministic
rendering and only that: two documents that denote the same set of
values can still hash differently, because no unique normal form is
computed: `number|integer` and `number` are the standing example. The
failure direction is the safe one: a spurious "changed" costs somebody a
second look, whereas a spurious "unchanged" would ship the break, and the
extra spellings the hash form carries over ordinary canon are there
precisely to keep that second failure out of reach. Trading cheap false
alarms for an assurance that cannot fail in the dangerous direction is a
good bargain, and it is the same bargain
[`subsume`](/docs/reference-api#aontu-subsume) and
[`breaking`](/docs/reference-api#aontu-breaking) make one level up, where
the question sharpens from "did the meaning change?" to "did it change
in a direction that hurts anyone downstream?" A check that answers
`undecided`, and fails the gate for saying so, is doing its job; one that
guesses "compatible" ships the break it was installed to catch.

### The same answers, through other transports

The MCP server, the language server, the published grammar, and the agent
skill are the argument above carried to callers that do not run a shell.
The MCP tools return the identical JSON contract the CLI prints, and a
tool that *refuses* (an invalid document, a path naming nothing) answers
with its own report rather than a protocol error, because the report is
the answer. The grammar published for constrained decoding accepts less
than the parser does and never more, and leaves out `@"…"` includes
entirely, on the view that a generated document should describe values
rather than reach for files. Served evaluation is confined for the same
reason rather than as a deployment option: a tool that has to remember
to restrict itself is one that will eventually forget, silently. And the
skill's example documents are executed by the test suite, on the same
principle that governs the rest of this repository: a teaching pack that
taught something the engine no longer did would fail the build rather
than mislead a reader silently.

## Closed-world validation is a dial

Schema languages usually take a global stance on unknown keys: JSON
Schema is open until you write `additionalProperties: false`, protobuf
is closed and you work around it. aontu cannot take a global stance,
because the same tree is schema and data at once and at different
stages of completion. A half-written definition has to be allowed to be
incomplete while the finished one beside it is allowed to be strict,
and no single default serves both.

So closedness is a property of a **node**. `close()` seals one map or
one list and `open()` lifts that seal, and the seal covers the node it
was written on rather than everything beneath it: a map nested inside a
closed map is still open, and so is a list. That is deliberate, and the
alternative (a mark that travels further than it was written) is
worse in a language where a subtree is routinely a template someone
else will extend. `aontu vet --closed` is the same dial at the command
line: it closes the anchor being validated, not the whole document, so
"no keys you did not declare *here*" is a question you can ask without
sealing everything else.

The cost is that closedness has to be written rather than assumed. An
author who never reaches for `close()` is never told about a typo in a
key, and the sealing has to be repeated at each tier that wants it.
That is the bill for letting one notation carry both a finished
definition and the half-written one beside it.

## Two implementations, one behaviour

TypeScript is canonical; Go is a port kept in lock-step. Parity rests
on a **shared, data-driven contract** rather than on reading code side
by side: the [`test/spec/*.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/) files. Each row is a
`name / mode / src / expect` tuple, and both
[`ts/test/spec.test.ts`](https://github.com/aontu-lang/aontu/blob/main/ts/test/spec.test.ts) and
[`go/spec_test.go`](https://github.com/aontu-lang/aontu/blob/main/go/spec_test.go) load the *same* files and assert
the *same* results: canonical form, generated JSON, or error substring.

Two things make this work in practice:

1. **The same parser stack.** Both sides use the `@tabnas` family
   (`jsonic` + `expr` + `path` + `multisource` + `directive`), TypeScript
   natively and Go via the matching Go ports. Surface syntax therefore
   parses identically, so the spec can exercise real syntax rather than a
   lowest common denominator.

2. **A single source of truth for behaviour.** A new behaviour is added
   to the canonical TypeScript implementation, captured as a spec row,
   then made to pass in Go. A row is only committed once *both* pass, so
   the spec always describes agreed, shared behaviour. Language-specific
   tests (the rich TypeScript `*.test.ts` suites, the Go-native sanity
   tests) live alongside the shared spec but never define cross-language
   behaviour on their own.

The Go port deliberately implements the *subset that the spec covers*
(which is, today, the full surface language) and mirrors the TypeScript
architecture closely (the same `Val` interface, the same `unite` ladder,
the same fixpoint loop) so that a change on one side has an obvious
counterpart on the other.

What the arrangement costs is worth naming, because it is paid on every
change. A language feature is written twice, and a row is only committed
once both engines produce it, so the cheapest possible change to
behaviour is still two ports and a spec row in one commit; features are
designed knowing that. What it buys is a claim no single implementation
can make. Two independently written engines agreeing byte for byte
across the whole shared suite is evidence about the *specification*
itself, of a kind one codebase's tests cannot supply, and the suite
becomes an unusually good detector of accidents, because an optimisation
that silently reorders a fold shows up as failing rows on whichever side
moved. That friction is the mechanism working.

## Where the meaning belongs to the engine

Parity is enforceable only while everything either port does is the engine's
to fix. `re()` broke that assumption. A pattern is handed to a *host*
subsystem (JavaScript's `RegExp` on one side, RE2 on the other) and
those hosts are different languages, in different complexity classes,
over different alphabets, with no shared specification between them.
`\A` is an anchor in one and a literal `A` in the other; `\s` is
Unicode whitespace in one and ASCII in the other; one matches UTF-16
code units where the other matches code points. None of it can be
fixed from this repository.

The first attempt was a blacklist (enumerate the constructs known to
differ, refuse those, pass the rest through) and it leaked three times
in a day. The instructive part is where a blacklist's correctness
lives: in the *author's knowledge* of two large external systems, a
claim that decays silently as those systems evolve and that no test can
falsify. Two of the three leaks were found by reading and one while
writing documentation. None by the suite.

So aontu inverts it: **where a host subsystem supplies semantics,
aontu defines the meaning and rewrites the input**, and the host is
given only constructs it cannot read two ways. `\d` is `[0-9]` because
the language says so, whether or not the hosts happen to agree. What that costs is paid at
the point of use: `\s` no longer means what a regex habit expects in
*either* language, and an author has one more small thing to learn. The
gain is that the guarantee stops depending on what the implementer
happens to know, and becomes checkable instead: a committed corpus pins
both normalisers, so a drift fails in whichever port drifted.

The rule is stated generally on purpose, because a date parser, a
collation order or a number formatter would each inherit it. It also
admits what it cannot close. Complexity is a property of the host's
matcher rather than of the pattern language (backtracking makes some
patterns exponential where an automaton is linear) so no rewriting
reaches it, and that axis is held by a syntactic restriction instead.
The principled end state is to own the matcher, at which point there is
no host subsystem left to normalise; that is recorded as a direction
rather than a plan.

## Performance shape

Unification is pointer-chasing over many small immutable nodes, run for
several passes, so most of the engineering effort goes into *not
allocating*: type discriminators, source positions, error arrays, path
indexing and per-pass descent are all arranged so that the common node
pays for none of them. The inventory of those optimisations lives as
comments beside the code that carries each one (start at
[`ts/src/unify.ts`](https://github.com/aontu-lang/aontu/blob/main/ts/src/unify.ts) and the `Val` classes under
[`ts/src/val/`](https://github.com/aontu-lang/aontu/blob/main/ts/src/val/)); none of them changes behaviour (the
shared spec guards that) and together they are why the engine stays
usable on realistically large models. The Go port keeps the same
overall structure but, lacking references-with-cycles in its hottest
paths, uses a simpler depth guard in place of the TypeScript seen-map.

## Two rules that surprise readers

Both of the rules below are specified, pinned by shared rows,
and (judging by how often they are written wrong) surprising. They belong
here rather than in a bug list, because in each case the rule is
defensible *and* the surprise is real, which is the shape of a trade-off
rather than of a defect.

### A preference is gated by kind, not by family

Overriding a default is judged by asking the two questions the long form
asks out loud. `*x` is sugar for `*x | super(x)`, so a peer meets it arm
by arm:

    *x & peer   ==   (x & peer)  |  (super(x) & peer)

The first arm decides. Does the preferred value *itself* still admit the
peer? Then the default stands, narrowed to what survived: `*1 &
integer`, `*8080 & min(1024)`, and (because maps merge) `*{p:1} & {q:2}`,
which keeps the `p` default and gains `q`. Only when that arm is empty
does the second answer, and that is the override: `*8080` meeting `9090`
yields `9090`, because `8080` cannot admit it but `integer` can. When
both arms are empty nothing is left of the disjunction the star stands
for, and the refusal says exactly that: `empty`. `*8080` meeting `3.5` is
empty, and so is `*2.2` meeting `3`.

There is one rule here, and it reaches everything a default can be:
a scalar, a kind (`super(integer)` is `number`, so `*integer` admits
`7` and refuses `"s"`), a constraint, a map, a list.

The surprise is that the two numeric leaves do not mix around a
preference, even though they share a supertype:

```
a: *2.2 & 3         → refused: [aontu/empty] at $.a
a: *1.5 & integer   → refused: [aontu/empty] at $.a
```

This is a choice, and the other one shipped for a while. A gate that
widens to the numeric *family* lets `*2.2 & 3` through, which reads as a
kindness: an author should not have to know which numeric leaf they
happened to write their default in. But that is one rule seen in one
direction, and the other direction is the idiom that looks most like "a
typed default":

```
port: *8080 | integer   with a later  port: 1.5
```

Under a family gate that generates `{"port":1.5}`. The preference widens
its branch to the base kind (`number`) so the `integer` the author
believes they wrote is not the constraint that survives, and every key
written the way [the agent skill](https://github.com/aontu-lang/aontu/blob/main/docs/skill/examples.md) teaches it is
silently a `number` key. No kind-based gate can keep the convenience and
refuse that; the leaf gate refuses both.

So the idiom now means what it looks like:

```
port: *8080 | integer
    alone                          → generates {"port":8080}
    with a later  port: 9090       → generates {"port":9090}
    with a later  port: 1.5        → refused: [aontu/empty] at $.port
```

and an author who *wants* the whole family writes it in the branch,
where a reader can see it:

```
port: *8080 | number    with a later  port: 1.5  → generates {"port":1.5}
```

`port: *8080 & integer` is still not the way to write a default,
tempting though it reads: a conjunction is not a choice, so the value is
pinned at `8080` and `9090` is refused along with `1.5`.

What the tightening costs is named rather than hidden: mixing the
numeric leaves around a preference is an error instead of a silent
widening. `*1.5 & integer` does not answer `integer` and discard a
default that could never apply; it says so, and names the line that
has to change. Only the numeric leaves are affected, because only
they sit under a common supertype: `*"us-east" | string` meeting a
later `42` was always an empty disjunction.

The rule is written down in [`test/spec/pref.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/pref.tsv)
and [`test/spec/number-tower.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/number-tower.tsv), and
the suite pins both of its directions: the `pref-kind-gate-*` rows pin
the cross-kind REFUSAL (`*1` against a map, a string, a boolean, a
list), `pref-override-within-kind-gens` pins the same-kind override that
is the same rule from the other side, and the tower's
`pref-idiom-refuses-other-leaf` / `pref-idiom-number-still-admits` pair
pins the numeric case. Both ports agree on it byte for byte.

### A list literal is positional

`tags: [string]` reads as "a list of strings" and is not one. A list
literal is **positional with an open tail**: it constrains element 0
and says nothing about anything after it.

```
tags: [string]     with a later  tags: [core, 7]  → generates {"tags":["core",7]}
tags: [&: string]  with a later  tags: [core, 7]  → refused: [aontu/no_scalar_unify] at $.tags.1
```

The homogeneous form is the spread, `[&: string]`, which applies its
template to every element: the same `&:` that templates a map. That
consistency is the defence: a list is a value like any other, so `[a,
b]` meeting `[c, d]` element-wise is the reading that keeps `&` meaning
one thing everywhere, and a bracket that silently meant "and all the
rest, too" would be the exception. Closing the enclosing map does not
close the tail either, because closedness is a mark on the node the
author closed; `close([string])` does close it, and refuses element 1
outright.

The surprise is nonetheless worth naming, because the two spellings
differ by three characters and fail in opposite directions: the
positional one accepts what it looks like it should refuse.

## Termination is part of the offer

The surface argued above is meant to be driven by something that is not
watching: a CI gate, a tool call, a repair loop several steps from
anyone's attention. For that caller, "usually finishes" is not a weaker
version of "finishes": it is a different product. A definition
language that can loop is one you have to supervise, and a definition
you have to supervise is a program you are running on faith.

That is the reason for the refusals listed below, rather than the other
way round: the guarantee is made of them, and implementation difficulty
had no vote. The trust contract ([trust.md](/docs/trust)) states the
guarantee formally and is candid about the clauses that are conditional
today.

## Limitations and trade-offs

- **No user-defined functions.** The function set is fixed: the
  built-ins declared in
  [`test/spec/signature.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/signature.tsv), the
  constraint atoms, the graph atoms and the generator combinators
  among them. This keeps the language total and analysable. The
  placeholder `_` is fixed syntax rather than a function, and custom
  functions were considered and refused: a recursive function is a
  fixpoint of the program, and its termination is undecidable.
  [Recursive schemas](#recursive-schemas-and-residuals)
  stand on the other side of that line: they recurse on finite data,
  never on the program, so the guarantee survives them.
-  **The fixpoint is bounded.** Extremely self-referential models hit
  the pass/cycle limits and surface a cycle error rather than
  diverging: correct, but it means some legal-looking models are rejected
  for practical termination reasons.

## Further reading

- The lattice and unification idea, in much greater depth, in the
  [CUE documentation](https://cuelang.org/docs/concept/the-logic-of-cue/).

---

# The aontu trust contract

_The trust contract: hermeticity, termination, determinism and sandboxing: what a host may rely on, and where each guarantee is conditional._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/trust.md · Page: https://aontu.dev/docs/trust

*Status: normative. This document states the guarantees an agent
harness (or any host) may rely on when evaluating an aontu document,
and where each guarantee is conditional. It is the written half of the
contract; the tested half lives in the shared spec suite
([test/spec/](https://github.com/aontu-lang/aontu/blob/main/test/spec/)), and anything stated here without a spec
pin says so plainly.*

For a document that agents evaluate unattended, safety guarantees are
not hardening applied afterwards: they are constitutive. The contract
is four clauses: **hermeticity**, **termination**, **determinism**, and
**sandboxing**.

## Clause 1: hermeticity

The output of an evaluation is a pure function of exactly four inputs:

1. the entry source text,
2. the resolved `@"…"` include closure,
3. the host-injected `$name` bindings, and
4. the evaluator: implementation (TypeScript or Go), version, and
   options.

Nothing else. The language has **no clock, no randomness, no
environment access, and no network**: the builtin functions are pure
value transformers, the `+` operator works over concrete scalars, and
external input enters only through includes and `$` bindings. No
construct that observes time or entropy will ever be added (see
[Refusals](#refusals) below); parameterise through `$` bindings
instead.

**Where this is conditional.** Input 2 (the include closure) is only
a well-defined *input* when the resolver is confined, and confinement
is the **trust profile**, an option in **both** implementations:
`trust: { include: 'none' | {mem} | {root} | 'system' }` on
`AontuOptions` in TypeScript, `Aontu.Trust` (`TrustOptions`) in Go.
Under `none`, `{mem}` or `{root}` the closure is explicit and
hermeticity is TOTAL: `none` denies every `@"…"`, `{mem}` resolves
only the declared virtual file set, and `{root}` reads real files
realpath-confined below the root (a symlink inside the root pointing
outside it is an escape and is denied; package resolution never runs).
A few names are served under every capability but `none`, because they
are BUNDLED with the engine: `@"aontu:system"` and `@"aontu:view"`, the
[system and view vocabularies](/docs/reference-language#the-bundled-vocabularies),
and every `@"aontu:…"` name: the
[language-supplied models](/docs/reference-language#the-aontu-models),
`aontu:profile`, `aontu:lang/text` and `aontu:lang/markdown`. An
`aontu:` name resolves from the
engine's own table and nowhere else: the memory, module, file and
package legs are never asked, so nothing on disk can shadow one, and a
name the engine does not serve is refused naming the set rather than
searched for. None of them touches the filesystem or package
resolution, so they widen nothing a hermetic evaluation cares about (a
source that never leaves the process is as reproducible as a builtin
function) and each appears in the manifest under capability `std`, so
the closure still says it was read. Under `none` they are denied with
everything else: `none` means no includes at all.

A denied resolution is the located, deterministic parse-stage
`include_denied` error, pinned by `test/spec/include-trust.tsv` in
both runners. The resolved closure itself is observable as the
**include manifest** (sorted, deduplicated `{path, capability}`
entries on the parse result (`val.deps` in TypeScript,
`Aontu.IncludeDeps` in Go)) which is this clause's "file set" as
data.

Under the DEFAULT `'system'` capability the chain (memory →
filesystem → package in TypeScript; filesystem in Go) reads anything
the process can, the closure is machine-dependent, and the code's
posture is the operative warning:

> **Treat opening an untrusted source as reading your disk.**

Reading, never running. An include's extension decides what the file is:
thirteen extensions are read at all (`.aon` and `.aontu` as aontu
source; `.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`,
`.toml`, `.yaml`, `.yml` and `.ini` as configuration data, each read by
its own parser; and `.txt` as text, which chooses no parser at all) and
everything else is refused by name, so no include is ever executed in
the evaluating process. `--text-ext` widens only the text set, and
cannot reach `.js`. The TypeScript package leg follows
the same rule: a package whose entry point is JavaScript does not
resolve.

`options.fs` still does not confine: it feeds source text for parsing
and error context, while the file and package legs read through their
own channels.

**The JSON-superset guarantee, stated precisely.** Every JSON document
*parses* as aontu. That is the whole claim. It does not say "behaves
identically to a JSON parser": the number tower refuses what JSON
silently corrupts, so `{"x":9007199254740993}` (a literal binary64
cannot carry exactly) is a loud `lossy_integer_literal` error in
aontu where `JSON.parse` would round it. Refusal-over-corruption is a
feature of the contract, not an exception to it.

## Clause 2: termination

Every evaluation halts within deterministic budgets counted in
**engine events, never wall-clock**:

| budget     | counts                                   | current state |
|------------|------------------------------------------|-----------------|
| `passes`   | fixpoint passes over the whole model     | 9 (`maxcc`, `ts/src/unify.ts`; `go/unify.go`) |
| `revisits` | same-pair re-unifications within a pass  | 999 (`MAXCYCLE`, `ts/src/unify.ts`) |
| `depth`    | structural recursion depth               | 1000 (`MAXDEPTH`, `ts/src/unify.ts`; `maxUniteDepth`, `go/unify.go`), plus Go's parse-depth guard (`max_depth`). Shared: both engines report `unify_cycle` past it, and `test/spec/budget.tsv` pins the boundary from both sides. |

(The shared 1000 sits above every real document and below both hosts'
stack limits, so the budget, not the host, decides the verdict.)

The contract pins *verdicts at default budgets* (every shared spec
row must produce the same verdict in both implementations) not
internal step counts, which remain implementation detail.

**Exhaustion is a semantic error, never silent truncation.** The
different answers ("your model is cyclic", "your model is
incomplete", "the budget ran out") are distinct codes with distinct
classes (the registry: [test/spec/errcodes.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv);
the taxonomy rows: [test/spec/budget.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/budget.tsv)):

| code            | class       | meaning                                | valid agent response |
|-----------------|-------------|----------------------------------------|----------------------|
| `path_cycle`    | `reference` | a **proven** structural cycle: a self/ancestor reference, or a chain of plain references revisiting a node (`a:$.b b:$.a`) | fix the model: no budget helps |
| `no_path`       | `reference` | a reference target that does not exist | supply what is missing |
| `budget_passes` | `budget`    | the pass budget was spent while the final pass was **still making progress**: the evaluator gave up mid-convergence | retry with a larger budget, or restructure |
| `unify_cycle`   | `budget`    | the revisit bound tripped: **suspected** non-convergence | inspect; may be a cycle or a very large model |
| `recursion_unexpanded` | `incomplete` | a required recursive-schema position that no data ever expanded: refused at generation, at the instance | supply the data, or guard the field (`next?:` drops, a `*null` preference generates) |
| `recursion_budget` | `budget` | a recursive schema expanded past the depth budget without meeting concrete data: two definitions feeding each other, or data deeper than the budget | restructure the definitions, or raise `trust.budget.depth` for genuinely deep data |

A *stable* residue (a stuck `1+true`, an unresolved kind) is none of
these: it is ordinary incompleteness, silent at unify time and a
generate-time error (`mapval_no_gen` family, class `incomplete`).
Only genuine cut-off earns `budget_passes`.

**Pattern matching is bounded by construction, not by a budget.** The
`re()` atom is the one place the evaluator runs a subsystem whose cost
no budget counts, and the two ports do not agree on complexity: Go uses
RE2, which is linear, while TypeScript uses JavaScript's backtracking
`RegExp`, which is not. A nested quantifier is enough to make the
difference unbounded: `(a+)+$` against twenty-nine characters takes 45
seconds in TypeScript and 0.065s in Go. The *semantic* half of that
mismatch is handled by normalising the pattern before either engine sees
it; complexity is the half normalisation cannot reach. Rather than add a
budget the host engine cannot be asked to respect, the [portable
subset](/docs/reference-language#re-and-the-portable-pattern-subset)
**refuses the shapes that cause it**: a quantifier may not be applied to
a group containing a quantifier or an alternation. That keeps this
clause true in the port that has the problem, at the cost of refusing
some patterns that would have been safe. Residual risk, stated plainly:
the rule is syntactic, so a pattern with a large but polynomial
backtracking cost is still admitted, and pattern matching remains
outside the event-counted budgets above.

Two notes on how the budgets behave, and one caveat:

- A chain of plain references resolves one link per pass from the tail
  in **both** engines, so the pass budget is part of the shared
  language surface: nine links fit, ten exhaust it as `budget_passes`,
  pinned by the shared `budget-chain-*` rows in
  [test/spec/budget.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/budget.tsv).
-  A cycle wearing a function call is the same cycle: `a:$.b
  b:upper($.a)` is `path_cycle` in both ports, which follow function
  arguments when detecting the cycle. The shape is pinned by the shared
  `path-cycle-func-routed`, `-msg` and `path-cycle-func-chain`
  rows: together with `path-cycle-func-no-cycle`, which pins that an
  ordinary function chain is still not a cycle.
- `unify_cycle` remains *suspicion*, not proof, which is why it is class
  `budget` and not `reference`: the revisit bound cannot distinguish a
  genuine cycle from a model too large to settle within it. A legal
  model with more than `MAXCYCLE` sibling conjunct terms at one path
  does not trip it; a 1200-sibling-term fixture driven through both
  engines pins that.

## Clause 3: determinism

Identical inputs (clause 1's four) produce **byte-identical canonical
output and byte-identical generated JSON**, across runs and across the
TypeScript and Go implementations. This is pinned, not promised:

- `canon` spec rows are strict string equality in both runners, and
  canon round-trips kind (a number-kind scalar always renders with a
  fraction or an exponent), so a canon row pins the value the engine
  *holds*, not only the JSON it emits.
- `gens` spec rows compare the serialised generate output **byte for
  byte** (compact, sorted keys, no HTML escaping, JS number
  formatting) using each port's real emitter.
- Error **codes** are stable and cross-implementation per the
  registry ([test/spec/errcodes.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv), `errc`
  rows); thrown-error message text is in cross-port parity (marker,
  headline, verbatim hints with injected details, and located
  ANSI source frames render identically, byte-guarded by the
  full-message twin tests), while spec rows continue to bind only
  their asserted substrings and codes.
- Expected values are **parity-probed**: obtained from both engines
  before a row is written, never copied from one.
-  Known disagreements live in exactly one place (the parity ledger) and
  its normal state is empty of open entries.

## Clause 4: sandboxing

What an evaluation may read is declared by the **host**, not by the
document: a `.aon` file cannot request more capability, includes take a
literal string (never a computed expression), and canonical form is
unaffected by any trust setting.

That declaration is the **trust profile** (clause 1), in both
implementations, at every surface:

- **Library**: `trust.include` on the evaluator options (TypeScript)
  / `Aontu.Trust` (Go). The default remains `'system'`.
- **LSP**: confined to the **workspace root** by default, from the
  `initialize` params (workspaceFolders, rootUri, rootPath, in that
  order). The capability governs the **whole** server: hover and
  hover-provenance as well as the diagnostics it publishes. An explicit
  `initializationOptions.aontu.trust.include` of
  `'system'`, `'none'`, `{root}` or `{mem}` widens or narrows it, and
  an unrecognised value confines to nothing rather than silently
  widening. A session with no workspace root and no explicit option
  stays unconfined, which single-file sessions rely on. A `file://`
  uri's path is everything after the literal `file://`, and the leading
  slash of a **drive-letter** path is uri syntax rather than path, so
  `file:///C:/Users/me/project` is the root `C:/Users/me/project`, not
  `/C:/Users/me/project`. Both ports read it that way. **A non-empty
  authority is not handled**: `file://server/share/x` yields
  `server/share/x`, a relative string, so a UNC root or a VS Code
  `wsl.localhost` remote root confines to nothing usable. Both ports
  behave the same way, and neither has a spelling for the UNC form
  (`\\server\share`).
- **CLI**: `--trust <system|none|root[:dir]>` and
  `--include-root <dir>`, accepted by the bare command **and by every
  verb that reads a document**, and by the REPL, whose `--jsonl`
  session honours the capability for `:load`, `:get`, `:why` and bare
  snippets alike. `help`, `explain` and `init` read no document and
  refuse the flags, as does `lsp`, which takes no arguments at all; the
  MCP server confines with `--root <dir>` instead. `sync`, `add`, `get`
  and `remove` take the flags and then refuse a `root` capability,
  which puts the package cache they write out of reach. A verb takes the flags anywhere in its argument tail; a
  bare `root` means the primary document's own directory, matching the
  bare command's entry root. The default is `'system'` **with a warning**:
  every resolution that escapes the entry file's directory, or goes
  through package resolution, prints a one-line stderr warning naming
  the flags. The warning is a deprecation notice: a later major
  version denies those resolutions by default, and `--trust system`
  keeps the unconfined chain.

**An empty root is not a root.** Both CLIs refuse `--include-root ""`
and `--trust root:`, and the MCP server refuses `--root ""`. The
TypeScript library denies every include under `{root: ''}`, which is
how both language servers already read an empty explicit root. None of
those roads resolves the empty string, because resolving it yields the
process directory, a root nothing named. Go's
`TrustOptions.IncludeRoot` has no spelling for the case at all: its
zero value is an absent root, and an absent root is `'system'`.

Denied resolution is a located, deterministic parse-stage error
(`include_denied`) like any other (never a silent skip) and is
raised, not injected as a value, so a bare-member include
(`@"./denied.aon"` at the top of a file) cannot vanish in the merge.

Budgets are part of the same profile: `trust.budget.passes` and
`trust.budget.depth` (TypeScript) / `TrustOptions.Budget` (Go), integer
counts of engine events defaulting to the spec constants of clause 2.
The per-pair revisit bound is NOT profile surface: the Go dispatcher
has no revisit counter to configure, and a knob one port cannot honour
would break the parity contract by construction.

**NOTHING IN THE ENGINE WRITES A FILE.** The trust profile governs what
an evaluation may *read*. A generator answers a **component tree** as
an ordinary value, and the one verb that writes, `aontu render`, hands
that tree to jostraca, the generator runtime, which writes it below the
path the command names; no library call and no MCP tool writes. What
the runtime may write, and where, is its own contract rather than this
one: it refuses a `folder` that is absolute or climbs with `..`, so a
tree cannot choose the output root. The engine's refusals still stand
on the tree it answers. A filename is checked at the call, and two
files resolving to one path are refused, so a malformed tree never
reaches anything downstream.

## Evaluation consumes the tree

A parsed `Val` tree is **single-use**: `unify`/`generate` refine it in
place, and reusing a consumed tree (or any node reachable from it) in
a second evaluation is a *correctness* bug that surfaces as
nondeterminism: the exact failure mode this contract exists to
exclude. Parse again (or clone first) for every independent
evaluation. This is a rule of the API contract (see
[the API reference](/docs/reference-api#evaluation-consumes-the-tree)).

## Refusals

Guarantees are as much about what will never be added:

- **No wall-clock or memory budgets**: a limit that varies with
  machine load makes identical inputs fail differently.
- **No `now()`, `random()`, or `env()`**: each would falsify
  clause 1 by construction.
- **No Turing-completeness, no SMT solvers**: termination stays
  structural plus fuel; every trust question is answered by counting,
  never by solving.
- **No executable hooks in evaluation**: no callbacks or shell-outs;
  the resolver is the language's only effect, which is why confining
  the resolver confines the language.

## Where each piece is pinned

| claim | pin |
|-------|-----|
| cycle/no-path taxonomy codes | [test/spec/budget.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/budget.tsv) (`errc` + substring rows, both engines) |
| `budget_passes` code, class and "evaluation budget" substring | shared rows: [test/spec/budget.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/budget.tsv) `budget-chain-*` (verdicts, code and message substring, both engines); `ts/test/unify.test.ts` and `go/hints_test.go` keep the per-port err-shape guards |
| code → class registry | [test/spec/errcodes.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv) + set-equality tests in both runners |
| canon byte-stability | every `canon` row (strict equality, both runners) |
| generated-JSON byte-stability | `gens` rows (both runners) |
| graph and relation-verdict byte-stability | [test/spec/graph.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/graph.tsv) (`graph` rows: both runners re-derive the entity index and edge set on a fresh engine and require the same bytes) + [test/spec/relation.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/relation.tsv) (`relation` verdict rows, both engines) |
| known open divergences | [test/spec/divergent.tsv](https://github.com/aontu-lang/aontu/blob/main/test/spec/divergent.tsv): each entry carries its tracking issue; read the file for the live list rather than a count copied here. Only the Unicode table vintage is permanent |
| resolver posture | SECURITY comment, `ts/src/lang.ts`; this document |
| single-use trees | reference-api.md rule; `Aontu.parse` / Go `Parse` doc comments |

---

# Run a file or start a REPL

_Evaluate a file, read from stdin, or question a document interactively with the `aontu` command._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/run-cli-and-repl.md · Page: https://aontu.dev/how-to/run-cli-and-repl

Both implementations ship the same `aontu` command, and it decides what
to do from what you hand it: a file argument evaluates, piped input
evaluates, and an empty interactive terminal becomes a REPL. Three
inputs, one command.

Write this as `config.aon`:

<!-- test: scenario cli -->
<!-- test: file config.aon -->
```aontu
a: 1
b: $.a
```

Now run it, three ways:

<!-- test: run -->
```sh
$ aontu config.aon
{
  "a": 1,
  "b": 1
}
$ echo 'a:1 b:$.a' | aontu
{
  "a": 1,
  "b": 1
}
$ aontu --canon config.aon
{"a":1,"b":1}
```

Pretty-printed JSON is the default; `--canon` prints the
[canonical form](/how-to/see-canonical-form) instead: the same document, as
the engine would write it back.

With no file and a terminal on stdin, `aontu` starts a REPL. Each line
is evaluated and printed, `:canon` and `:json` switch the output mode,
and `:quit` (or Ctrl-D) leaves:

<!-- test: skip interactive REPL session -->
```sh
$ aontu
aontu v0.56.0 REPL — :help for commands, :quit to exit
aontu> a:*1|number
{
  "a": 1
}
aontu> :quit
```

`:load <file>` holds a document so that `:get`, `:keys` and `:why` can
question it: the same [query](/how-to/query-a-path) and
[provenance](/how-to/explain-a-value) surfaces the CLI verbs offer, from
inside the session. A harness can hold a session too: `--jsonl` drops
the banner and the prompt and answers each command as one JSON line,
so a program drives the REPL the way it drives the CLI. This
transcript was run exactly that way:

<!-- test: run -->
```sh
$ echo 'a:*1|number' | aontu --jsonl
{"ok":true,"out":"{\n  \"a\": 1\n}"}
```

One caution: the REPL evaluates each line as a complete document: there
is no continuation prompt, and the permissive parser closes what you
left open, so a half-typed `a: {` evaluates to `{"a":{}}` rather than
waiting for more. Paste whole statements.

Get the command in whichever of these fits the machine. Every one
installs the same `aontu`, whose `lsp` verb is the editor's language
server (the Go builds bring the standalone `aontu-lsp` binary too).

- `npm install -g aontu` (or `npx aontu`) for the TypeScript build.
- `curl -fsSL https://aontu.dev/install.sh | sh` on Linux or macOS:
  the script fetches the release archive for the platform, checks it
  against the release's `SHA256SUMS`, and puts the binaries in
  `~/.local/bin`; `AONTU_INSTALL_DIR` and `AONTU_VERSION` change the
  place and the release.
- A package from the
  [releases page](https://github.com/aontu-lang/aontu/releases): a
  `.deb`, `.rpm` or `.apk`, a zip for Windows, or the archive itself.
- `docker run --rm -v "$PWD:/work" ghcr.io/aontu-lang/aontu …`, the
  image on GitHub's registry, for containers and CI.
- `uses: aontu-lang/aontu/setup-action@main` in a GitHub workflow.
- `nix run github:aontu-lang/aontu`, or the flake as an input, built
  from source.
- `go install github.com/aontu-lang/aontu/go/cmd/aontu@latest` with a
  Go toolchain.

From a clone, `make install` puts both builds on `PATH`, each by its
own toolchain: `make install-ts` links the checkout as the global npm
package, so `make build-ts` updates the command in place, and
`make install-go` runs `go install` for `aontu` and `aontu-lsp`. Both
builds provide `aontu`, so `PATH` order decides which one answers and
`aontu --version` says which did. Without installing:
`node ts/bin/aontu.js …`, or `go run ./cmd/aontu …` inside `go/`. Both
accept the same options and print the same bytes.

The full option, verb and REPL-command tables are in the
[CLI reference](/docs/reference-api#command-line-interface). To keep
the answers inside a program instead of a terminal,
[call aontu from TypeScript](/how-to/call-from-typescript) or
[from Go](/how-to/call-from-go).

---

# Call aontu from TypeScript

_Embed the engine in Node with the `Aontu` class: parse, unify and generate from your own code._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/call-from-typescript.md · Page: https://aontu.dev/how-to/call-from-typescript

The npm package `aontu` is not a wrapper around the CLI: the CLI is a
thin client over the class the package exports. Requires Node ≥ 22.
Three methods cover most embeddings:

<!-- test: skip TypeScript API sample; the API is pinned by ts/test/ -->
```ts
import { Aontu } from 'aontu'

const aontu = new Aontu()

aontu.generate('a: 1 b: $.a')   // { a: 1, b: 1 }   (a plain JS value)
aontu.unify('a: *1 | number')   // a Val; .canon is '{"a":*1|number}'
aontu.parse('a: number')        // a Val AST, not yet unified
```

`generate` throws an `AontuError` on a conflict, or when the result is
not fully concrete: a schema is a valid document but not a generable
one. When you want to see an unresolved or schema-bearing result
rather than a final value, take `unify(...).canon`
([see the canonical form](/how-to/see-canonical-form)); when you want every
problem instead of the first throw,
[collect errors](/how-to/collect-errors).

Two habits keep an embedding correct. Serialise generated output with
the package's `exactJSON`, never `JSON.stringify`: a document using
`0d` exact literals generates `bigint` and `Decimal` values that
`JSON.stringify` refuses to write
([exact numbers](/docs/reference-api#exact-numbers-and-exactjson)).
And treat a parsed `Val` tree as single-use: unification refines it
in place, so parse again for every independent evaluation
([evaluation consumes the
tree](/docs/reference-api#evaluation-consumes-the-tree)). The string
entry points parse per call and are always safe.

The full surface (options, contexts, the `Val` classes, and the
library forms of the CLI verbs: `vet`, `get`, `why`, `subsume`, …)
is the [TypeScript API reference](/docs/reference-api#typescript-api).
To parameterise a model from code, [inject host
values](/how-to/inject-host-values); for the Go port,
[call aontu from Go](/how-to/call-from-go).

---

# Call aontu from Go

_Embed the engine with the Go port: the same three calls, with errors returned instead of thrown._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/call-from-go.md · Page: https://aontu.dev/how-to/call-from-go

The Go port is a library first: module `github.com/aontu-lang/aontu/go`,
package `aontu`, kept in parity with the canonical TypeScript engine
for the subset it implements. The same three calls, in Go's idiom:

<!-- test: skip Go API sample; the API is pinned by the go/ test suite -->
```go
import aontu "github.com/aontu-lang/aontu/go"

a := aontu.New()

out, err := a.Generate("a: 1 b: $.a")   // out = map[string]any{"a":1, "b":1}
v,   err := a.Unify("a: *1 | number")   // v.Canon() == `{"a":*1|number}`
v,   err  = a.Parse("a: number")        // AST, not yet unified
```

Nothing throws or panics for an ordinary conflict: every method
returns an `error`, and `Generate` returns `(nil, err)` on any
unresolved or conflicting value, so check it. Generated output uses
Go's natural types (`map[string]any`, `[]any`, `int64`, `float64`,
`string`, `bool`, `nil`), plus `*big.Int` and `*Decimal` for the two
exact leaves, both of which marshal their exact digits as raw JSON
numbers ([exact numbers in
Go](/docs/reference-api#exact-numbers-in-go)).

When a source's relative `@"file"` loads should resolve from somewhere
other than the process working directory (typically the directory of
an entry file), construct with a base:

<!-- test: skip Go API sample; the API is pinned by the go/ test suite -->
```go
abs, _ := filepath.Abs(file)
a := aontu.NewWithBase(filepath.Dir(abs))
```

(The `aontu` CLI does exactly this for a file argument.) Absolute
paths are unaffected.

One difference from the TypeScript port to plan around: the Go port
ships no MCP binary: its role is embedding, so `Get`, `Why`, `Diff`
and `AgentsMd` are library calls instead
([give an agent an entrypoint](/how-to/give-an-agent-an-entrypoint)).
For every problem in one pass rather than the first error, use
`Check` ([collect errors](/how-to/collect-errors)).

The full surface is the [Go API
reference](/docs/reference-api#go-api); to parameterise a model from
code, [inject host values](/how-to/inject-host-values). The two ports
answer alike by construction, and one shared test suite is what pins
it.

---

# See the canonical form

_Print what a document means (defaults, disjunctions and all) instead of what it resolves to._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/see-canonical-form.md · Page: https://aontu.dev/how-to/see-canonical-form

Generation answers "what does this resolve to?", and in answering it
erases the thing a schema author cares about: what the document still
admits. The canonical form keeps that. Write `timeout.aon`:

<!-- test: scenario canon -->
<!-- test: file timeout.aon -->
```aontu
timeout: *30|integer
```

Now evaluate it both ways:

<!-- test: run -->
```sh
$ aontu timeout.aon
{
  "timeout": 30
}
$ aontu --canon timeout.aon
{"timeout":*30|integer}
```

Generation resolves the default; `--canon` keeps the whole
default-and-type so you can see what a caller may still override. Where
information has fully arrived, the two agree: a constraint
[met](/docs/unification) by a concrete value canons to just the value.
Write `pinned.aon`:

<!-- test: file pinned.aon -->
```aontu
a: 1
a: number
```

<!-- test: run -->
```sh
$ aontu --canon pinned.aon
{"a":1}
```

From code, the same view is the `canon` property of a unified value:

<!-- test: skip TypeScript API sample; the canon surface is pinned by ts/test/ -->
```ts
aontu.unify('a: *1 | number').canon   // '{"a":*1|number}'
aontu.unify('a: 1 a: number').canon   // '{"a":1}'
```

<!-- test: skip Go API sample; the canon surface is pinned by the go/ test suite -->
```go
v, _ := a.Unify("a: *1 | number")   // v.Canon() == `{"a":*1|number}`
```

A conflict throws before there is anything to read, so ask for the
wreckage with `collect: true` ([collect errors](/how-to/collect-errors));
the failed path reads `nil`:

<!-- test: skip TypeScript API sample; the canon surface is pinned by ts/test/ -->
```ts
aontu.unify('a: number a: string', { collect: true }).canon  // '{"a":nil}'
```

Canon is deterministic and reparseable, which is why it carries more
weight than a debugging view: it is the text the `aon1-` pin is
derived from, so "same canon" is this project's working definition of
"same meaning" ([pin a document hash](/how-to/pin-a-document-hash)).

The exhaustive rendering rules (key order, number forms, what
recursion renders as) are in the language reference under
[Canonical form](/docs/reference-language#canonical-form).

---

# Inject values from the host program

_Fill `$name` variables from the calling program to parameterise a model from code._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/inject-host-values.md · Page: https://aontu.dev/how-to/inject-host-values

A `$name` with no dot is not a path: it names a value the calling
program supplies. This is how a model takes parameters from code (a
port from the environment, a region from a flag) without a second
source file.

In TypeScript, set variables on a context and pass it as the third
argument:

<!-- test: skip TypeScript API sample; the API is pinned by ts/test/ -->
```ts
import { Aontu } from 'aontu'
import { IntegerVal } from 'aontu/dist/val/IntegerVal'

const aontu = new Aontu()
const ctx = aontu.ctx()
ctx.vars.port = new IntegerVal({ peg: 8080 })

aontu.generate('server: { port: $port }', undefined, ctx)
// { server: { port: 8080 } }
```

In Go, build a `map[string]Val` with the exported constructors
(`NewInteger`, `NewString`, `NewNumber`, `NewBoolean`, `NewNull`,
`NewScalarKind`, `NewMap`, `NewList`, and the exact-leaf pair
`NewBigInteger` / `NewBigDecimal`) and use the `Vars` variants:

<!-- test: skip Go API sample; the API is pinned by the go/ test suite -->
```go
vars := map[string]aontu.Val{"port": aontu.NewInteger(8080)}
out, err := aontu.New().GenerateVars("server: { port: $port }", vars)
// out == map[string]any{"server": map[string]any{"port": 8080}}
```

A `$name` nobody supplied is refused, under its own error code:

<!-- test: run -->
```sh
$ echo 'server: port: $port' | aontu
[aontu/unknown_var]: Cannot unify values at path $.server.port
...
$ echo $?
1
```

The similar-looking `[aontu/no_path]: Cannot resolve value at path …`
is the path case: a `$.reference` that names nothing in the document.
Two different mistakes, two different codes
([read a conflict error](/how-to/read-a-conflict-error) has the anatomy).

An injected variable is a value like any other, so it unifies rather
than overrides: `server: { port: $port }` beside
`server: { port: integer & max(65535) }` checks the injected value
against the constraint, and a bad injection fails with a located
conflict. That makes variables a safe seam: the document keeps its
say. The exact-leaf constructors take a `bigint`, a `Decimal`, or the
digits as text, never a host `number`, which binary64 has already
rounded before the library could look
([exact-input constructors](/docs/reference-api#variables)).

The constructor tables are in the API reference, for
[TypeScript](/docs/reference-api#variables) and
[Go](/docs/reference-api#variables-in-go); the language rule is
[Variables `$name`](/docs/reference-language#variables-name).

---

# Give an agent an entrypoint to a definition

_Generate a ground-truth stanza with `aontu agentsmd` and serve the verbs over MCP with `aontu mcp`._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/give-an-agent-an-entrypoint.md · Page: https://aontu.dev/how-to/give-an-agent-an-entrypoint

An agent working against a model needs two things: a stanza to read
before it starts, and a service to question while it works. aontu
ships both halves, and neither is written by hand.

The stanza first. `aontu agentsmd` derives it from the source, so it
cannot drift from what the document says. Write `system.aon`:

<!-- test: scenario agent-entrypoint -->
<!-- test: file system.aon -->
```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

<!-- test: run -->
```sh
$ aontu agentsmd system.aon
<!-- aontu:begin -->
## Ground truth: `system.aon`
...
- Pin: `aon1-kmZi3pPU2hnWQfwLnaFoC5iUtlrt6vbUzU7og-KxWJE`
...
- Top-level keys: `services`
- Shape: `{"services":{&:top,"auth":top,"billing":top}}`
...
<!-- aontu:end -->
$ aontu agentsmd --write AGENTS.md system.aon
wrote: AGENTS.md
```

The stanza names the pin (the [canon-hash](/how-to/pin-a-document-hash),
which survives reformatting and moves on any change of meaning), the
root keys, the shape, and the `get` / `why` / `vet` / `set` commands
spelled with a path that actually exists in the document. `--write`
splices it between the two markers, appending them when absent, and
touches nothing outside them, so re-run it in the same commit that
changes the definition.

The server second. `aontu mcp` is the `mcp` verb of the npm package's
command, speaking Model Context Protocol over stdio (the standalone
`aontu-mcp` binary runs the same server). Point a harness at it the
way you point it at any stdio MCP server:

<!-- test: skip MCP client configuration; the served contract is pinned by ts/test/mcp.test.ts -->
```json
{ "mcpServers": { "aontu": { "command": "aontu", "args": ["mcp"] } } }
```

It serves `vet`, `get`, `why`, `diff`, `canon`, `summary` and the
rest of the verb roster, each returning the same JSON contract the
matching CLI verb prints. A call that refuses (a bad path, a
document that does not hold) answers with its report and
`isError: false`, because the report is the answer.

It also evaluates confined: the source arrives from the caller, so
`@"..."` is denied rather than followed. Asking it to canonicalise
`a: @"./system.aon"` comes back as a finding, not a file read:

<!-- test: skip MCP tool response; the served contract is pinned by ts/test/mcp.test.ts -->
```json
{
  "ok": false,
  "canon": "",
  "findings": [
    {
      "code": "include_denied",
      "class": "reference",
      "severity": "error",
      "path": "$",
      "message": "include denied: ./system.aon (capability: none)",
      "sites": []
    }
  ]
}
```

(Started with `--root <dir>`, the server resolves includes confined
below that root instead, and accepts file-path arguments under it.)
The Go port ships no MCP binary: `Get`, `Why`, `Diff` and `AgentsMd`
are library calls for [embedding](/how-to/call-from-go).

Details of both halves: [`aontu
agentsmd`](/docs/reference-api#aontu-agentsmd) and [the MCP
server](/docs/reference-api#the-mcp-server). The live version is
[use-cases/09-agent-tools](/use-cases/09-agent-tools): a tool
registry whose agent-emitted calls are vetted by exit code, with the
real MCP server driven over stdio in the checks. The verbs an agent
should reach for first are [query a path](/how-to/query-a-path) and
[validate in CI](/how-to/validate-in-ci).

---

# Collect errors instead of throwing

_Gather every problem in one pass with `collect: true` (TypeScript) or `Check` (Go) instead of stopping at the first._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/collect-errors.md · Page: https://aontu.dev/how-to/collect-errors

`generate` throws on the first surfaced error, which suits a build
step and fails a linter: an editor wants every problem in one pass,
each with its location. Pass `collect: true` and read the result's
`err` array:

<!-- test: skip TypeScript API sample; the API is pinned by ts/test/ -->
```ts
const aontu = new Aontu()
const res = aontu.unify('a: 1 a: 2', { collect: true })

res.err            // one NilVal per failure — nothing thrown
res.err[0].why     // 'scalar_value', the error code
res.canon          // '{"a":nil}' — the failure sits where it happened
```

Each collected error is a `NilVal`: the value a failed unification
leaves behind, carrying its error code (`why`), its full message, and
the path it failed at. The rest of the document still unifies around
it, which is what makes the mode useful: one pass, every error,
each located. The [canonical form](/how-to/see-canonical-form) then shows
`nil` at each failed path, a map of the damage.

The Go port never throws for a conflict (`Unify` and `Generate`
return an `error`), but that error is still the first one. The
every-problem call is `Check`:

<!-- test: skip Go API sample; the API is pinned by the go/ test suite -->
```go
problems := aontu.New().Check("a:1\na:2")
// every problem: source position, error code, full message
```

Both language servers are this mode with a protocol around it: the
diagnostics your editor shows are a walk over the collected `NilVal`s
([how diagnostics are
computed](/docs/lsp#how-diagnostics-are-computed)). A valid but
non-concrete document (a schema, a partial fragment) collects
nothing: a value still waiting for information is a residual, not an
error.

The `collect` and `err` options are in
[`AontuOptions`](/docs/reference-api#aontuoptions). To make sense of
one collected conflict, [read a conflict
error](/how-to/read-a-conflict-error); to get the collecting behaviour in
your editor rather than your code, [wire your
editor](/how-to/wire-your-editor).

---

# Read a conflict error

_What a conflict message names, in what order, and how to tell a conflict from an unresolved path._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/read-a-conflict-error.md · Page: https://aontu.dev/how-to/read-a-conflict-error

A conflict message names both operands, and it pays to know which is
which. For two plain facts [meeting](/docs/unification) at a path, the
later-in-source one is named first:

```
Cannot unify value: 2 with value: 1
```

means two facts reached the same path (`1` earlier, `2` later) and
they cannot both hold. To see everything the engine prints around
that line, write `clash.aon`:

<!-- test: scenario conflict -->
<!-- test: file clash.aon -->
<!-- fmt: keep two writers, one statement each -->
```aontu
a: b: 1
a: b: 2
```

<!-- test: run -->
```sh
$ aontu clash.aon
[aontu/scalar_value]: Cannot unify values at path $.a.b
...
 Cannot unify value: 2 with value: 1
  --> clash.aon:2:7
...
 Cannot unify value: 1 with value: 2
  --> clash.aon:1:7
...
$ echo $?
1
```

Read it top to bottom. The `[aontu/scalar_value]` line carries the error
code and the path; a hint block restates the rule that was broken; then
each operand appears with an annotated source frame: file, line, column,
and the offending text with a caret under it. Note the path: a nested
conflict reports the leaf values that clashed, so `a:b:1` against
`a:b:2` is that same one-line message at `$.a.b`, not a complaint about
`a`.

Where the conflict is reached through a disjunction, a list spread or
a reference, both operands are still named but the ordering heuristic
no longer applies: the value "later in source" may have travelled.
Trust the two source frames, not the order.

An unresolved path is a different failure, with a different code:

```
[aontu/no_path]: Cannot resolve value at path $.x
```

Nothing contradicted anything; a `$.reference` names a key the
document does not have. (An undefined `$name` variable is
`[aontu/unknown_var]`, a third case: see [inject host
values](/how-to/inject-host-values).)

The error codes, spelled as they render, are catalogued in the
language reference under [Errors](/docs/reference-language#errors).
To see every contribution that met at a path (including the ones
that agreed), [explain a value](/how-to/explain-a-value); to gather every
failure in one pass instead of reading them one throw at a time,
[collect errors](/how-to/collect-errors).

---

# Wire your editor

_Connect `aontu lsp` to VS Code, Neovim, or any LSP client for diagnostics as you type._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/wire-your-editor.md · Page: https://aontu.dev/how-to/wire-your-editor

Both implementations serve the Language Server Protocol from the
command itself, `aontu lsp`: unification problems as diagnostics
while you type, with hover and completion beside them. Ready-made
plugins for VS Code, Emacs and Vim/Neovim live in
[`editors/`](https://github.com/aontu-lang/aontu/blob/main/editors/), each a thin client that launches the
server, with install steps in its README. The recipes below are for
wiring a client yourself.

The facts every client needs: the command is `aontu` with the one
argument `lsp`, the transport is stdio, and the document selector is
the `aontu` language (`.aon` is the preferred extension, `.aontu` also
works, `.jsonic` is retired). The server has no configuration options.
The standalone `aontu-lsp` binary that earlier configurations name
still ships and runs the same server.

Get the command any way the [CLI guide](/how-to/run-cli-and-repl) lists:
`npm install -g aontu`, a built binary, or `go install`. The two builds
are interchangeable from a client's point of view
([running the server](/docs/lsp#running-the-server)).

## VS Code

There is no published extension; the smallest path is a tiny custom
extension whose `activate` starts the server with
[`vscode-languageclient`](https://www.npmjs.com/package/vscode-languageclient):

<!-- test: skip VS Code extension wiring; the server contract is pinned by ts/test/lsp.test.ts -->
```ts
import { workspace, ExtensionContext } from 'vscode'
import { LanguageClient, TransportKind } from 'vscode-languageclient/node'

export function activate(_ctx: ExtensionContext) {
  const server = { command: 'aontu', args: ['lsp'], transport: TransportKind.stdio }
  const client = new LanguageClient(
    'aontu',
    'aontu',
    { run: server, debug: server },
    { documentSelector: [{ scheme: 'file', language: 'aontu' }] },
  )
  client.start()
}
```

From a checkout, use
`{ module: '/abs/path/to/aontu/ts/bin/aontu-lsp.js', transport: TransportKind.stdio }`
for the TypeScript server, or `command: '/abs/path/to/go/aontu'` with
the same `args` for a Go build.

## Neovim (built-in LSP)

<!-- test: skip Neovim configuration; the server contract is pinned by ts/test/lsp.test.ts and go/lsp/serve_test.go -->
```lua
vim.filetype.add({ extension = { aon = 'aontu', aontu = 'aontu' } })

vim.api.nvim_create_autocmd('FileType', {
  pattern = 'aontu',
  callback = function(args)
    vim.lsp.start({
      name = 'aontu',
      cmd = { 'aontu', 'lsp' },        -- or { 'node', '/abs/path/ts/bin/aontu-lsp.js' }
      root_dir = vim.fs.dirname(args.file),
    })
  end,
})
```

The filetype registration covers both extensions; the shipped
[vim plugin](https://github.com/aontu-lang/aontu/blob/main/editors/vim/) does the same and adds syntax
highlighting.

## Any LSP client

Configure a server whose command is `aontu` with the argument `lsp`
(or `node …/aontu-lsp.js`), transport stdio, document selector the
`aontu` language / `*.aon` glob. No initialization options are
required. One is available: hover provenance, which appends to each
hover the contributions record `aontu model why` prints: ask for it and
pay a second evaluation per hover, or leave it off and pay nothing
([LSP hover provenance](/docs/reference-api#lsp-hover-provenance)):

<!-- test: skip editor initialization sample; the hover surface is pinned by ts/test/lsp.test.ts -->
```json
{ "initializationOptions": { "aontu": { "provenance": true } } }
```

What you will and will not see: the server flags contradictions,
unresolved references and unknown constructs, and stays silent on
schemas and partial documents: non-concrete is valid, so your
half-written model does not light up red
([how diagnostics are
computed](/docs/lsp#how-diagnostics-are-computed)).

The full reference (architecture, both library APIs, the protocol
surface) is [the LSP page](/docs/lsp). The same contributions record
the hover option shows is yours at the command line with
[explain a value](/how-to/explain-a-value).

---

# Provide defaults that callers can override

_Write a default in a disjunction with the type an override must satisfy, and layer defaults by rank._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/provide-defaults.md · Page: https://aontu.dev/how-to/provide-defaults

A default that nothing can override is a constant, and a default
that anything can override is a bug with a delay on it. The
disjunction holds the ground between: write the default beside the
type an override must satisfy:

```aontu
timeout: *30|integer # 30 unless overridden
```

```json
{ "timeout": 30 }
```

The `*` marks the preferred branch, so with no other statement the
document generates `30`. A later `timeout: 60` (in the same file or
merged from another) takes its place:

```aontu
timeout: *30|integer
timeout: 60
```

```json
{ "timeout": 60 }
```

An override is admitted only if an alternative of the disjunction
accepts it or it equals the preferred value, so `timeout: 1.5` is
refused. Write both lines as `timeout.aon`:

<!-- test: scenario provide-defaults -->
<!-- test: file timeout.aon -->
```aontu
timeout: *30|integer
timeout: 1.5
```

<!-- test: run -->
```sh
$ aontu timeout.aon
[aontu/empty]: Cannot unify values at path $.timeout
...
 Cannot unify value: 1.5 with value: *30|integer
...
$ echo $?
1
```

The branch is doing the admitting, which means it is also the dial:
`*30 | number` is how you ask for a default that any number may
override:

```aontu
timeout: *30|number
timeout: 1.5
```

```json
{ "timeout": 1.5 }
```

A bound goes inside the branch the same way:

```aontu
replicas: *2|(integer & min(1) & max(24))
replicas: 12
```

```json
{ "replicas": 12 }
```

Unset, this field generates `2`; `12` is admitted; `40` must be
refused, because a fleet that silently accepts `replicas: 40` has no
policy at all. Check it with `replicas.aon`:

<!-- test: file replicas.aon -->
```aontu
replicas: *2|(integer & min(1) & max(24))
replicas: 40
```

<!-- test: run -->
```sh
$ aontu replicas.aon
[aontu/empty]: Cannot unify values at path $.replicas
...
 Cannot unify value: 40 with value: *2|integer&min(1)&max(24)
...
$ echo $?
1
```

A lone `*5` with no `|` is just a default `5` and needs none of
this, and the spelling `integer & (*30 | integer)` means the same as
`*30 | integer`.

## Layer defaults by rank

When several layers of authority each want to supply the default,
stars decide. The fewer the stars, the stronger the default (`*`
beats `**` beats `***`) and a concrete value beats them all, so an
organisation writes `***`, a team `**`, an environment `*`:

```aontu
logLevel: ***info # org
logLevel: **debug # team
logLevel: *warn # environment
```

```json
{ "logLevel": "warn" }
```

No priority table, no merge order: the three statements can arrive
from three files in any order and `warn` still wins. Two defaults of
the same rank that disagree refuse as `[aontu/pref_rank_clash]`, whose
hint names the fix, so two teams cannot both claim the same rung
silently.

Ranks also order the arms of one disjunction, and there the ladder
survives elimination: `*1 | **2` generates `1`, and generates `2` once
something rules `1` out. Adding a rung is therefore safe: it cannot
take the rungs above it with it.

The marker is specified in [Preference / default
`*`](/docs/reference-language#preference--default-). Two live
versions run this at scale: the [feature-flag
catalog](/use-cases/08-feature-flags) arbitrates org, then
environment, then tenant over the same rank ladder, and the
[deployment fleet](/use-cases/02-deploy-config) layers org,
team, and environment files the same way. Offering a default is also
how a referenced base lets its referrers differ (see [reference and
reshape](/how-to/reference-and-reshape)) and when the value is already
pinned concrete, overriding means [changing a pinned
value](/how-to/change-a-pinned-value) instead.

---

# Apply a template to many keys

_Use a `&:` spread entry to unify one template into every key of a map or every element of a list._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/apply-a-template-to-many-keys.md · Page: https://aontu.dev/how-to/apply-a-template-to-many-keys

Ten endpoints, one policy, and the policy written ten times: that is
how drift starts. Write it once as a `&:` spread entry: it is
unified into every other key of the map:

```aontu
endpoints: { &: { method: *GET|string auth: *true|boolean } }
endpoints: list: {}
endpoints: create: method: POST
```

```json
{ "endpoints": {
  "create": { "auth": true, "method": "POST" },
  "list":   { "auth": true, "method": "GET" }
} }
```

`create` keeps its own `method` and picks up the rest: the template
is a peer of each child, so children override its defaults the
ordinary way. (Keys come out sorted, whatever order they were
written in.) The same entry works in lists:

```aontu
a: [&: { x:1 } y:1 y:2]
```

```json
{ "a": [ { "x": 1, "y": 1 }, { "x": 1, "y": 2 } ] }
```

A top-level `&: {...}` applies to every key of the root map.

## Stamp a schema and a shared field

A template does not have to be defaults. The service-catalog pattern
stamps a `type()`-marked schema together with the one field every
child in a block shares:

```aontu
CatalogEntry: type({
  owner: string
  tier: integer & min(1) & max(3)
  description: string
})

payments: services: { &: $.CatalogEntry & { owner:"team-payments" } }
payments: services: payments: { tier:1 description:"Card capture API." }
payments: services: ledger: { tier:1 description:"Ledger of record." }
```

```json
{ "payments": { "services": {
  "ledger":   { "description": "Ledger of record.",
                "owner": "team-payments", "tier": 1 },
  "payments": { "description": "Card capture API.",
                "owner": "team-payments", "tier": 1 }
} } }
```

`CatalogEntry` itself never appears in the output (the mark keeps
it for unification only, per [keep schema out of the
output](/how-to/keep-schema-out-of-output)) and no service repeats its
`owner`. The stamped constraints are enforced per child. Change
`ledger` to `tier: 4` and run it as `catalog.aon`:

<!-- test: scenario stamp-catalog -->
<!-- test: file catalog.aon -->
```aontu
CatalogEntry: type({
  owner: string
  tier: integer & min(1) & max(3)
  description: string
})

payments: services: { &: $.CatalogEntry & { owner:"team-payments" } }
payments: services: payments: { tier:1 description:"Card capture API." }
payments: services: ledger: { tier:4 description:"Ledger of record." }
```

<!-- test: run -->
```sh
$ aontu catalog.aon
[aontu/constraint]: Cannot unify values at path $.payments.services.ledger.tier
...
 Cannot unify value: 4 with value: integer&min(1)&max(3)
...
$ echo $?
1
```

The refusal lands on the child that broke the rule, not on the
template: the reader of a CI log gets the offending service by
name.

One thing to watch: a spread constrains the children it
[meets](/docs/unification) and creates none of its own, so a map holding
only `&:` generates `{}`. Generating children from a table is `pack`'s
job, and sealing what it generates is the subject of [seal generated
children deeply](/how-to/seal-generated-children). For lists, the choice
between `[&: T]` and the positional `[T]` is decided in [constrain every
element of a list](/how-to/constrain-list-elements).

Spreads are specified in [Spreads
`&:`](/docs/reference-language#spreads-). The live versions: the
[service catalog](/use-cases/01-service-catalog) stamps a
schema and an owner across three domains exactly as above, and the
[Kubernetes golden path](/use-cases/06-k8s-golden-path)
combines spreads with generators to fan one service model out into
whole manifests.

---

# Seal generated children deeply

_Close both the set of `pack`-generated children and each child's shape, or seal from the side with a hidden guard._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/seal-generated-children.md · Page: https://aontu.dev/how-to/seal-generated-children

`close` seals exactly the node it wraps: it is deliberately
shallow. Around a
[`pack`](/docs/reference-language#generating-children-pack-and-each)
generator, that means `close(pack(...))` forbids adding *children*
to the generated map while each child's own keys stay open. A typo'd
override is then absorbed instead of refused:

```aontu
names: hide({ web: {} auth: {} })

deploy: close(pack($.names, { replicas: *1|integer tier: *standard|string }))

deploy: web: replicaz: 3
```

```json
{
  "deploy": {
    "auth": { "replicas": 1, "tier": "standard" },
    "web":  { "replicas": 1, "replicaz": 3, "tier": "standard" }
  }
}
```

Exit 0, and `web` ships with the default `replicas: 1`, the
misspelled `replicaz` riding along beside it, doing nothing. The
deep-seal spelling closes the template as well, so every generated
child is sealed too:

```aontu
names: hide({ web: {} auth: {} })

deploy: close(pack($.names, close({
  replicas: *1|integer
  tier: *standard|string
})))

deploy: web: replicas: 3
```

```json
{
  "deploy": {
    "auth": { "replicas": 1, "tier": "standard" },
    "web":  { "replicas": 3, "tier": "standard" }
  }
}
```

The legitimate override composes exactly as before: `web` gets its
`replicas: 3`, `auth` keeps the defaults. Now misspell it against
the same sealed shape: the same document with `deploy: web:
replicaz: 3`, as `deploy.aon`:

<!-- test: scenario deep-seal -->
<!-- test: file deploy.aon -->
```aontu
names: hide({ web: {} auth: {} })

deploy: close(pack($.names, close({
  replicas: *1|integer
  tier: *standard|string
})))

deploy: web: replicaz: 3
```

<!-- test: run -->
```sh
$ aontu deploy.aon
[aontu/closed]: Cannot resolve value at path $.deploy.web.replicaz
...
$ echo $?
1
```

The child refuses, naming the key. The rule generalises: `close`
never travels, so seal each level you mean to seal: the outer
`close(...)` pins the *set* of children, the inner `close({...})`
pins each child's *shape*.

## Seal the set without closing the tree

Sometimes the generated map itself has to stay open: other statements
merge into it, or overlays you do not control land on it. A hidden guard
seals from the side: [meet](/docs/unification) a clone of the tree with
a closed pack of the same table and an empty template:

```aontu
environments: hide({ dev: {} prod: {} })

deploy: pack($.environments, { replicas: *1|integer })

envguard: hide($.deploy & close(pack($.environments, {})))

deploy: prod: replicas: 3
```

```json
{ "deploy": { "dev": { "replicas": 1 }, "prod": { "replicas": 3 } } }
```

`envguard` evaluates on every run and emits nothing. An environment
that exists nowhere in the table now has nowhere to land: change
the last line of `guard.aon` to invent one:

<!-- test: scenario envguard -->
<!-- test: file guard.aon -->
```aontu
environments: hide({ dev: {} prod: {} })

deploy: pack($.environments, { replicas: *1|integer })

envguard: hide($.deploy & close(pack($.environments, {})))

deploy: prod2: replicas: 3
```

<!-- test: run -->
```sh
$ aontu guard.aon
[aontu/closed]: Cannot resolve value at path $.envguard
...
$ echo $?
1
```

The annotated site is the overlay line that invented `prod2`; the
reported path is the guard's own, which is the cost of guarding from
the side rather than in the tree.

For the shallow basics of `close` on a plain map, start at [forbid
unexpected keys](/how-to/forbid-unexpected-keys); the semantics are
specified in [Closed values: `close` /
`open`](/docs/reference-language#closed-values-close--open). Both
recipes run live: the [Kubernetes golden
path](/use-cases/06-k8s-golden-path) seals its service set
with `close(pack(...))` as its drift guard, and the [deployment
fleet](/use-cases/02-deploy-config) keeps the environment
guard as a worked example in `stack.aon`.

---

# Reference and reshape other parts of the document

_Pull other parts of the document in by reference, extend them, and relocate them with `move` and `copy`._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/reference-and-reshape.md · Page: https://aontu.dev/how-to/reference-and-reshape

A reference pulls another node in and **unifies** with it: it adds,
it never overrides. That one sentence decides most of what follows:

```aontu
base: { region:"us-east" tier:free }
prod: $.base & { replicas:3 }
```

```json
{ "base": { "region": "us-east", "tier": "free" },
  "prod": { "region": "us-east", "replicas": 3, "tier": "free" } }
```

`prod` extends the base and the base is untouched. (Note the quotes
on `"us-east"`: a bare word stops at the `-`.) Now try to *change* a
field instead of adding one: the same base with `prod: $.base &
{ tier: paid }`, as `tier.aon`:

<!-- test: scenario reference-conflict -->
<!-- test: file tier.aon -->
```aontu
base: { region:"us-east" tier:free }
prod: $.base & { tier:paid }
```

<!-- test: run -->
```sh
$ aontu tier.aon
[aontu/scalar_value]: Cannot unify values at path $.prod.tier
...
 Cannot unify value: "paid" with value: "free"
...
$ echo $?
1
```

A conflict, not an override. To let a referrer change a field, the
base has to offer it as a [default](/how-to/provide-defaults):

```aontu
base: { region:"us-east" tier: *free|string }
prod: $.base & { tier:paid }
```

```json
{ "base": { "region": "us-east", "tier": "free" },
  "prod": { "region": "us-east", "tier": "paid" } }
```

The addressing and reshaping vocabulary, in full:

- `$.a.b`: absolute path from the document root.
- `.a.b`: path relative to the current map.
- `key()`: the key the current value is stored under.
- `copy($.x)`: a deep copy, `type`/`hide` marks cleared.
- `move($.x)`: a reference that relocates: the source is dropped
  from the output, along with any unresolved optional keys.

The last one reshapes in the strict sense: the value leaves its old
address:

```aontu
m: { x?:number y:Y }
n: move($.m)
```

```json
{ "n": { "y": "Y" } }
```

`m` is gone from the output and the unresolved optional `x` went
with it; a plain `n: $.m` would have kept both `m` and `n`.

Path grammar and composition rules are specified in [References and
paths](/docs/reference-language#references-and-paths), and the
`copy`/`move`/`key` rows in
[Functions](/docs/reference-language#functions). For reference
conjunction at scale, the [feature-flag
catalog](/use-cases/08-feature-flags) is the live version: its
served views are built as `$.flags & $.envs.prod.flags &
$.tenants.megacorp.flags`, so every layer's write flows into the
view by reference alone.

---

# Keep schema and helper fields out of the output

_Mark schema and helper fields with `type()` or `hide()` so they constrain and compute without being generated._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/keep-schema-out-of-output.md · Page: https://aontu.dev/how-to/keep-schema-out-of-output

A schema written next to its data has one job left after
constraining it: staying out of the generated JSON. A field whose
value is marked with `type(...)` or `hide(...)` is omitted when the
enclosing map generates, and still participates in unification. Park
the schema at its own key and reference it where it should apply:

```aontu
_schema: type({ id:integer name:string })

users: { &: $._schema ada: { id:1 name:ada } bob: { id:2 name:bob } }
```

```json
{ "users": { "ada": { "id": 1, "name": "ada" },
             "bob": { "id": 2, "name": "bob" } } }
```

`_schema` never appears, and it still constrains. Give `bob` a
string id in `users.aon`:

<!-- test: scenario schema-mark -->
<!-- test: file users.aon -->
```aontu
_schema: type({ id:integer name:string })

users: { &: $._schema ada: { id:1 name:ada } bob: { id:"two" name:bob } }
```

<!-- test: run -->
```sh
$ aontu users.aon
[aontu/no_scalar_unify]: Cannot unify values at path $.users.bob.id
...
$ echo $?
1
```

A mark belongs to the field its wrapper was written at, and a
reference copies the value with the marks cleared, which is why
`$._schema` constrains the children without hiding them, and why
marking `_schema` does nothing to any other field. Mark the field
the data itself arrives at and you silence the whole thing:

```aontu
user: type({ id:integer })
user: id: 7
```

```json
{}
```

Unified, constrained, then omitted. `type()` on the data's own field
is almost never what you meant.

`hide(...)` is the same mechanism for values you compute with but do
not emit:

```aontu
secret: hide("s3cret")
token: $.secret
```

```json
{ "token": "s3cret" }
```

The reference emits because it copied the value and left the mark
behind; `copy(...)` is the explicit spelling of that copy when you
want it on the page.

## Hide an invariant, keep it armed

The same mark carries policy. A rule that must hold on every
evaluation, without appearing anywhere in the output, is a hidden
block: here, "exactly one role holds the tenant":

```aontu
roles: owner: { tenantOwner:true rank:100 }
roles: admin: { tenantOwner:false rank:80 }
roles: auditor: { tenantOwner:false rank:20 }

registry_invariant: hide({
  one_owner: length(1) & filter($.roles, { tenantOwner:true })
})
```

```json
{ "roles": { "admin":   { "rank": 80,  "tenantOwner": false },
             "auditor": { "rank": 20,  "tenantOwner": false },
             "owner":   { "rank": 100, "tenantOwner": true } } }
```

The filtered set must have length 1, and the check costs the output
nothing. Promote `admin` to `tenantOwner: true` in `rbac.aon` and
the hidden block fails loudly:

<!-- test: file rbac.aon -->
```aontu
roles: owner: { tenantOwner:true rank:100 }
roles: admin: { tenantOwner:true rank:80 }
roles: auditor: { tenantOwner:false rank:20 }

registry_invariant: hide({
  one_owner: length(1) & filter($.roles, { tenantOwner:true })
})
```

<!-- test: run -->
```sh
$ aontu rbac.aon
[aontu/constraint]: Cannot unify values at path $.registry_invariant.one_owner
...
$ echo $?
1
```

The refusal prints the offending set (both roles claiming the
tenant, by name), so the reviewer reads the violation itself rather
than a bare verdict.

Marks are specified in [Marks: `type` and
`hide`](/docs/reference-language#marks-type-and-hide). A
`type()`-marked block is also how you build a vocabulary of named
constraints: [name a reusable
constraint](/how-to/name-a-reusable-constraint). The invariant recipe
runs live in the [RBAC policy](/use-cases/05-rbac-policy) use
case.

---

# Constrain every element of a list

_Type every element of a list with a `&:` spread, and know why a bare `[string]` does not._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/constrain-list-elements.md · Page: https://aontu.dev/how-to/constrain-list-elements

A bare `[string]` is a positional constraint: it types element 0 and
says nothing about the rest. Most lists are collections, and most
authors learn the difference from data that should have failed:

```aontu
tags: [string]
tags: [core 7]
```

```json
{
  "tags": [
    "core",
    7
  ]
}
```

The `7` passed because position 1 was never constrained: the two
lists unified element by element, and the schema list simply ran out.

The collection form is a `&:` spread: a template unified into every
element. Write this as `tags.aon`:

<!-- test: scenario list-elements -->
<!-- test: file tags.aon -->
```aontu
tags: [&: string]
tags: [core 7]
```

Now run it:

<!-- test: run -->
```sh
$ aontu tags.aon
[aontu/no_scalar_unify]: Cannot unify values at path $.tags.1
...
$ echo $?
1
```

The path names the exact element, so a thousand-entry list fails at
`$.tags.999`, not "somewhere in tags".

Reach for the positional form when the positions genuinely differ (a
pair, a fixed header) and for `[&: T]` whenever the list is a
collection. `close` on the enclosing map seals that map's
keys and leaves the list tail open: the spread is what constrains
the elements. Constraints on the list itself (`length`, `unique`)
sit beside the spread with `&`; see [`length`
semantics](/docs/reference-language#length-semantics).

The constructs are specified in the language reference under
[Lists](/docs/reference-language#lists) and
[Spreads `&:`](/docs/reference-language#spreads-). To close the map
around the list too, see
[forbid unexpected keys](/how-to/forbid-unexpected-keys); a bare-kind
element template also crosses to JSON Schema as `items`: see
[export JSON Schema](/how-to/export-json-schema).

---

# Forbid unexpected keys

_Seal a map with `close` so a typo'd or invented key is refused instead of absorbed._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/forbid-unexpected-keys.md · Page: https://aontu.dev/how-to/forbid-unexpected-keys

Maps are open by default: a key the schema never mentioned unifies in
without comment. That openness is what makes composition work, and it
is exactly wrong for config. Seal the map with `close`:

```aontu
config: close({ host:string port:integer })
config: { host:h port:1 }
```

```json
{
  "config": {
    "host": "h",
    "port": 1
  }
}
```

Declared keys compose as before. Now add a key the schema does not
declare. Write this as `config.aon`:

<!-- test: scenario closed-map -->
<!-- test: file config.aon -->
```aontu
config: close({ host:string port:integer })
config: { host:h port:1 debug:true }
```

<!-- test: run -->
```sh
$ aontu config.aon
[aontu/closed]: Cannot resolve value at path $.config.debug
...
$ echo $?
1
```

The error names the key, which is the point: an absorbed `debug`
would have run in production doing nothing.

`open(x)` lifts a seal again, so a schema you import closed can be
extended deliberately:

```aontu
a: open(close({ x:1 })) & { y:2 }
```

```json
{
  "a": {
    "x": 1,
    "y": 2
  }
}
```

What to watch for: `close` seals exactly the node it wraps, and only
that node. Children generated inside it stay open unless you seal
them too: around a `pack` generator that difference decides whether
a misspelled override is refused or absorbed, and [seal generated
children deeply](/how-to/seal-generated-children) walks through it. A
list tail is also not closed by the enclosing map's seal; the
element template is: see
[constrain every element of a list](/how-to/constrain-list-elements).

The semantics are specified in [Closed values: `close` /
`open`](/docs/reference-language#closed-values-close--open).
Closedness is also the one thing aontu and JSON Schema say
identically (`additionalProperties: false`): see
[export JSON Schema](/how-to/export-json-schema).

---

# Make a field optional

_Suffix a key with `?` so a field that never receives a value is dropped instead of erroring._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/make-a-field-optional.md · Page: https://aontu.dev/how-to/make-a-field-optional

Some fields are genuinely sometimes-absent, and a schema that demands
them anyway teaches producers to send empty strings. Suffix the key
with `?` instead. An optional field that never receives a concrete
value is dropped from the output:

<!-- fmt: keep a schema and its data as separate statements -->
```aontu
record: { id: integer, note?: string }
record: { id: 1 }
```

```json
{
  "record": {
    "id": 1
  }
}
```

Dropped means absent: no `note`, not `note: null`. Supplying a value
keeps the field, checked against its constraint as usual:

<!-- fmt: keep a schema and its data as separate statements -->
```aontu
record: { id: integer, note?: string }
record: { id: 1, note: hi }
```

```json
{
  "record": {
    "id": 1,
    "note": "hi"
  }
}
```

An optional key with a [ranked
default](/docs/reference-language#preference--default-) is filled
rather than dropped, because the default is a concrete value arriving:

<!-- fmt: keep a schema and its data as separate statements -->
```aontu
record: { id: integer, retries?: *3 | integer }
record: { id: 1 }
```

```json
{
  "record": {
    "id": 1,
    "retries": 3
  }
}
```

Use `note?:` for "may not exist" and `retries?: *3 | integer` for
"always exists, sender may omit". The two read almost the same and
generate differently.

An optional key is still a declared key, so it coexists with
[`close`](/how-to/forbid-unexpected-keys): the sealed map admits the key
when it arrives and drops it when it does not:

```aontu
config: close({ id:integer note?:string })
config: id: 1
```

```json
{
  "config": {
    "id": 1
  }
}
```

The full rules, including how optionality survives references, are in
[Optional keys `?`](/docs/reference-language#optional-keys-). For
defaults on their own, see [provide defaults](/how-to/provide-defaults);
on a JSON Schema export an optional key is simply absent from
`required`: see [export JSON Schema](/how-to/export-json-schema).

---

# Name a reusable constraint

_Build a `uint8`/`port` vocabulary as a `type()`-marked block of ordinary fields._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/name-a-reusable-constraint.md · Page: https://aontu.dev/how-to/name-a-reusable-constraint

aontu has no `uint8`, `int8` or `port` keyword, and does not need
one: a constraint is a value, so a name for one is a field. A
`type()`-marked block gives you a library of them that unifies like
everything else and emits nothing:

```aontu
type: type({})

type: {
  uint8: integer & min(0) & max(255)
  int8: integer & min(-128) & max(127)
  port: integer & min(1) & max(65535)
}

listen: $.type.port
listen: 8080
```

```json
{ "listen": 8080 }
```

The block is absent from the output and present for unification, and
the key name is not reserved: `type` here is a field that happens to
be `type()`-marked, so `defs` or `schema` reads the same.

An out-of-range value is refused at the field that holds it. Write
the same document with `listen: 70000` as `types.aon`:

<!-- test: scenario named-constraints -->
<!-- test: file types.aon -->
```aontu
type: type({})

type: {
  uint8: integer & min(0) & max(255)
  int8: integer & min(-128) & max(127)
  port: integer & min(1) & max(65535)
}

listen: $.type.port
listen: 70000
```

<!-- test: run -->
```sh
$ aontu types.aon
[aontu/constraint]: Cannot unify values at path $.listen
...
 Cannot unify value: 70000 with value: integer&min(1)&max(65535)
...
$ echo $?
1
```

The refusal states the normalised residual the value had to satisfy,
not the alias's name: the constraint travelled, the label did not.

Lead with the kind. `min(0) & max(255)` alone bounds a *number*, so
`1.5` satisfies it:

```aontu
loose: type({})
loose: byteish: min(0) & max(255)
a: $.loose.byteish
a: 1.5
```

```json
{ "a": 1.5 }
```

A sized integer is `integer & min(0) & max(255)`, which is why every
alias above starts with `integer`.

Aliases are ordinary values, so they compose: one can be defined in
terms of another, and a use site can narrow one further
(`$.type.uint8 & max(15)`). For a file-local name that skips the
path entirely, `%port = integer & min(1) & max(65535)` declares an
[alias](/docs/reference-language#aliases-) used as bare `%port`.

The idiom is specified in [Named constraint
aliases](/docs/reference-language#named-constraint-aliases); the
`type()` mark's mechanics are the subject of [keep schema out of the
output](/how-to/keep-schema-out-of-output).

---

# Define a recursive schema

_Reference a definition inside itself to get a schema that applies at every depth of the data._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/define-a-recursive-schema.md · Page: https://aontu.dev/how-to/define-a-recursive-schema

An approval chain, a comment thread, a filesystem tree: the data is
self-similar, and the schema should be written once. Reference the
definition inside itself: that reference means the fixpoint, and the
schema applies at every depth of the data:

```aontu
spec: hide({
  Step: {
    approver: string & re("^[a-z]+@acme[.]example$")
    decision: *pending|pending|approved|rejected
    then?: $.spec.Step
  }
})

policy: $.spec.Step & {
  approver: "lead@acme.example"
  decision: approved
  then: { approver:"cfo@acme.example" then:approver:"audit@acme.example" }
}
```

```json
{
  "policy": {
    "approver": "lead@acme.example",
    "decision": "approved",
    "then": {
      "approver": "cfo@acme.example",
      "decision": "pending",
      "then": {
        "approver": "audit@acme.example",
        "decision": "pending"
      }
    }
  }
}
```

`$.spec.Step` written inside `Step` is the whole trick: no marker, no
unrolled copies, and every level of the chain [met](/docs/unification)
the `re()` and got the ranked `decision` default. The recursive position
expands one level per meet with concrete data, so validation descends
exactly as far as the data does: no maximum depth to configure, no
blind spot past it.

## Guard the recursion

The `?` on `then?:` is the guard: an optional recursive tail simply
drops where the data stops. A ranked default guards the same way,
ending the structure with an explicit value instead of an absence:

```aontu
schema: hide({ Node: { v:integer next: *null|$.schema.Node } })
doc: $.schema.Node & { v:1 next:v:2 }
```

```json
{
  "doc": {
    "v": 1,
    "next": {
      "v": 2,
      "next": null
    }
  }
}
```

The recursion also runs through list templates, which is how a
comment thread types its replies:

```aontu
spec: hide({
  Comment: { author:string text:string replies?: [&: $.spec.Comment] }
})

thread: $.spec.Comment & {
  author: "alix"
  text: "ship it"
  replies: [
    { author:"bo" text:"+1" }
    { author:"cy" text:"hold on" replies: [{ author:"alix" text:"?" }] }
  ]
}
```

```json
{
  "thread": {
    "author": "alix",
    "text": "ship it",
    "replies": [
      {"author": "bo", "text": "+1"},
      {"author": "cy", "text": "hold on",
       "replies": [{"author": "alix", "text": "?"}]}
    ]
  }
}
```

A wrong value three levels down is an ordinary located error
(`$.thread.replies.1.replies.0.author`), because each level of data
expanded the schema one more level to meet it.

## The unguarded tail refuses

Guardedness is emergent: the engine never analyses the schema for
well-foundedness, the data decides. Drop the `?` and the schema still
evaluates, but no finite document can satisfy it. Write this as
`chain.aon`:

<!-- test: scenario recursion-unguarded -->
<!-- test: file chain.aon -->
```aontu
spec: hide({ Step: { approver:string then:$.spec.Step } })

doc: $.spec.Step & {
  approver: "lead@acme.example"
  then: approver: "cfo@acme.example"
}
```

<!-- test: run -->
```sh
$ aontu chain.aon
[aontu/recursion_unexpanded]: Cannot recurse value at path $.doc.then.then
...
$ echo $?
1
```

The refusal lands at `$.doc.then.then` (the exact position the data
ran out), and the error's hint states the repair:

```
Guard the recursion -- an optional key (next?:) drops when nothing
arrives, and a preferred alternative (*null | $.Node) generates --
or supply the data.
```

## The canon stays finite

An infinitely deep type still has a one-line canonical form, because
recursion renders symbolically. Put the vocabulary alone in
`spec.aon`:

<!-- test: scenario recursion-canon -->
<!-- test: file spec.aon -->
```aontu
spec: hide({
  Step: {
    approver: string & re("^[a-z]+@acme[.]example$")
    decision: *pending|pending|approved|rejected
    then?: $.spec.Step
  }
})
```

<!-- test: run -->
```sh
$ aontu --canon spec.aon
{"spec":{"Step":{"approver":re("^[a-z]+@acme[.]example$"),"decision":*"pending"|"pending"|"approved"|"rejected","then"?:$.spec.Step}}}
$ aontu hash spec.aon
aon1-sgTj1hvqaL8vHdKZrlH7eaPbKeE9UW28b9WGBlVW9hw
```

The definition stays one reference deep (`"then"?:$.spec.Step`), so
the `aon1-` hash pins the mu-form of the schema, not any unrolling of
it. That single string is a version pin for the whole recursive
vocabulary: data instances unroll to their own depth without moving
it.

## Vet plain JSON at any depth

The same anchored vet that checks flat records checks recursive ones,
against data that carries no aontu syntax at all. With `spec.aon`
still in place, put a chain in `chain-good.json`:

<!-- test: file chain-good.json -->
```json
{
  "approver": "lead@acme.example",
  "decision": "approved",
  "then": {
    "approver": "cfo@acme.example",
    "decision": "pending"
  }
}
```

and a chain that goes wrong one level down in `chain-bad.json`:

<!-- test: file chain-bad.json -->
```json
{
  "approver": "lead@acme.example",
  "decision": "approved",
  "then": {
    "approver": "EXTERNAL@other.example",
    "decision": "maybe"
  }
}
```

Now vet both against the definition:

<!-- test: run -->
```sh
$ aontu vet --at '$.spec.Step' spec.aon chain-good.json
verdict: valid
$ aontu vet --at '$.spec.Step' spec.aon chain-bad.json
verdict: invalid

$.spec.Step.then.approver: constraint [conflict]
  [aontu/constraint]: Cannot unify values at path $.spec.Step.then.approver
  expected: re("^[a-z]+@acme[.]example$")
  actual:   "EXTERNAL@other.example"
  data: chain-bad.json:5:17 ("EXTERNAL@other.example")
  schema: spec.aon:3:24 (re("^[a-z]+@acme[.]example$"))
$.spec.Step.then.decision: empty [conflict]
  [aontu/empty]: Cannot unify values at path $.spec.Step.then.decision
  data: chain-bad.json:6:17 ("maybe")
  schema: spec.aon:4:15 (*"pending"|"pending"|"approved"|"rejected")
$ echo $?
1
```

Both findings are located in the schema's namespace at the depth the
data failed, with the data site beside them.

The live version of all of this is
[use-cases/13-recursive-schema](/use-cases/13-recursive-schema),
an approval-chain model whose `check.sh` asserts every moment shown
here. The semantics are specified in [Recursive
references
(fixpoints)](/docs/reference-language#recursive-references-fixpoints),
mutual recursion and recursive aliases included.

---

# Carry exact money over JSON

_Keep money exact inside aontu and cross JSON as a fixed-scale decimal string with a conversion mark._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/carry-exact-money-over-json.md · Page: https://aontu.dev/how-to/carry-exact-money-over-json

Inside an aontu document, money is a
[`bigdecimal`](/docs/reference-language#the-four-numeric-leaves):
`0d` literals are exact base-10 values and `+` on them is exact
arithmetic: no binary rounding, ever. Write this as `money.aon`:

<!-- test: scenario money-wire -->
<!-- test: file money.aon -->
```aontu
subtotal: 0d19.99
shipping: 0d4.01
total: $.subtotal + $.shipping
```

<!-- test: run -->
```sh
$ aontu money.aon
{
  "shipping": 4.01,
  "subtotal": 19.99,
  "total": 24.0
}
```

The problem is the wire. A `bigdecimal` schema cannot be satisfied by
a plain JSON number, by design: `JSON.parse` has already turned `0.1`
into a binary64 `float` before aontu ever sees it, and [the numeric
leaves are
disjoint](/docs/reference-language#the-four-numeric-leaves), so the
exactness the field demands is gone at the door. Put the schema in
`invoice.aon`:

<!-- test: file invoice.aon -->
```aontu
invoice: total: bigdecimal
```

and a parsed-and-reserialised number in `invoice.json`:

<!-- test: file invoice.json -->
```json
{"invoice": {"total": 0.1}}
```

<!-- test: run -->
```sh
$ aontu vet invoice.aon invoice.json
verdict: invalid

$.invoice.total: no_scalar_unify [conflict]
  [aontu/no_scalar_unify]: Cannot unify values at path $.invoice.total
  data: invoice.json:1:23 (0.1)
  schema: invoice.aon:1:17 (bigdecimal)
$ echo $?
1
```

This refusal is the feature: a schema that admitted `0.1` here would
be certifying a value the wire already corrupted. The convention that
works is string decimals at the boundary: the JSON field carries the
exact digits as text, and the schema pins its shape with
[`re`](/docs/reference-language#re-and-the-portable-pattern-subset).
Replace `invoice.aon` with the string form:

<!-- test: file invoice.aon -->
```aontu
invoice: total: string & re("^-?[0-9]+\\.[0-9][0-9]$")
```

A conforming wire value in `wire.json`:

<!-- test: file wire.json -->
```json
{"invoice": {"total": "19.99"}}
```

and a wrong-scale one in `bad.json`:

<!-- test: file bad.json -->
```json
{"invoice": {"total": "19.9"}}
```

<!-- test: run -->
```sh
$ aontu vet invoice.aon wire.json
verdict: valid
$ aontu vet invoice.aon bad.json
verdict: invalid

$.invoice.total: constraint [conflict]
  [aontu/constraint]: Cannot unify values at path $.invoice.total
  expected: re("^-?[0-9]+\\.[0-9][0-9]$")
  actual:   "19.9"
  data: bad.json:1:23 ("19.9")
  schema: invoice.aon:1:26 (re("^-?[0-9]+\\.[0-9][0-9]$"))
$ echo $?
1
```

## The convention, in full

A pattern alone leaves the reader guessing that the string is a
number at all. The convention has two parts, a canonical wire form
and a conversion mark that says what the text means. Write it as
`money-wire.aon`:

<!-- test: file money-wire.aon -->
```aontu
# A decimal carried as text, at a fixed scale. Canonical only: no
# leading zeros, no separators, no exponent, no bare -0.
Dec2: type(string & re("^-?(0|[1-9][0-9]*)[.][0-9]{2}$") & neq("-0.00"))

Money: type(close({
  amount: $.Dec2
  currency: string & re("^[A-Z]{3}$") & neq("XXX", "XTS")

  # The conversion mark: which leaf, at what scale. OPTIONAL, so a
  # producer is never asked to send it; CONSTANT, so a producer that
  # does send it cannot claim something else.
  dec?: "bigdecimal:2"
}))
```

Write the mark as a constant, not as a preference. `dec?:
*"bigdecimal:2"` looks equivalent and is not: a preference is a
*default*, so it yields to whatever the data says, and `{"dec":
"float"}` would vet clean.

The currency travels with the amount. A decimal string with no
currency beside it is a number rather than money, and every rounding
rule that matters belongs to the currency.

## Crossing the boundary

The conversion is textual: the wire string is the `0d` literal's
digits, so nothing is parsed as a float on the way in and nothing is
rounded. Put the corner cases in `convert.aon`:

<!-- test: file convert.aon -->
```aontu
amount: 0d3998.19
refund: -0d12.05
sameNumber: 0d10.50 & 0d10.5
scaleZeroRight: 0d10.0
```

<!-- test: run -->
```sh
$ aontu --canon convert.aon
{"amount":0d3998.19,"refund":-0d12.05,"sameNumber":0d10.5,"scaleZeroRight":0d10.0}
```

Three details decide whether an implementation of this is correct:

- **The sign goes outside the prefix.** `"-12.05"` becomes
  `-0d12.05`. `0d-12.05` is not a literal, so a converter that pastes
  the sign after the prefix fails to parse rather than computing the
  wrong number: the safe direction, but still the detail everyone
  gets wrong once.
- **Scale is not part of the value.** `0d10.50` and `0d10.5` are the
  same number and unify; canon prints the shorter one. A serialiser
  therefore cannot recover `"10.50"` from the value: it formats *to*
  the scale the schema declared, which is why the mark names a scale
  as well as a leaf.
- **At scale 0 the point still has to be written.** `0d10` is a
  `biginteger` and the leaves are disjoint, so a scale-0 wire decimal
  converts to `0d<digits>.0`: never `0d<digits>`, which would refuse
  the very schema it was converted for.

The producer formats its exact value into the string; the consumer,
after `vet` passes, parses the string with a *decimal* parser (never
`parseFloat`): in TypeScript the `Decimal` class the engine itself
uses, in Go `math/big`. Inside the trust boundary, keep the value a
`0d` exact literal and let aontu's arithmetic and the [lossy-literal
refusal](/docs/reference-language#exact-or-refused-lossy-literals)
protect it. Note the asymmetry: aontu's own generated JSON *writes*
an exact value's digits faithfully (the `24.0` above), but a standard
JSON reader hands them back as a float. Exactness survives writing,
not the round trip, which is exactly why the wire field is a string.

## The convention survives export

A bare `bigdecimal` field is a loss on a JSON Schema export: the
exactness has no receiver. The wire form is the way around it:
[export JSON Schema](/how-to/export-json-schema) covers the verb, and the
`Money` type crosses whole, mark included:

<!-- test: run -->
```sh
$ aontu jsonschema --at '$.Money' money-wire.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "amount": {
...
      "pattern": "^-?(0|[1-9][0-9]*)[.][0-9]{2}$",
      "type": "string"
    },
...
    "dec": {
      "const": "bigdecimal:2",
      "type": "string"
    }
  },
  "required": [
    "amount",
    "currency"
  ],
  "type": "object"
}
```

`type` and `pattern` do different jobs here and both are needed:
`type: "string"` is what refuses a bare JSON number (whose *text* the
pattern would happily accept), `pattern` is what refuses the wrong
scale. A consumer that never runs aontu still enforces the wire form,
and still learns the leaf and the scale from the exported `const`.

A worked end-to-end version (the schema, strictly JSON records that
pass, the three that must not, the exported schema checked against the
same records, and the conversion written as theorems) is
[use-cases/10-data-model](/use-cases/10-data-model)
(`money-wire.aon` and `money-convert.aon`), with `check.sh` asserting
every claim on this page.

---

# Export JSON Schema

_Export a model as JSON Schema 2020-12 with `aontu jsonschema`, and read the loss report it owes you._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/export-json-schema.md · Page: https://aontu.dev/how-to/export-json-schema

JSON Schema is what the rest of the world reads: an MCP tool's
`inputSchema` must be one, structured-output APIs constrain
generation to one, OpenAPI embeds one. `aontu jsonschema` exports the
unified value as draft 2020-12 to stdout, and names every loss on
stderr, because a converter that silently dropped a constraint would
hand you a schema that admits more than the model does.

## Export a whole document

A document whose root is one `close()` expression exports as one
schema object, sealed at the root. Write this as `event.aon`:

<!-- test: scenario jsonschema-export -->
<!-- test: file event.aon -->
```aontu
close({
  id: string & re("^evt_[0-9a-f]{12}$")
  kind: created|updated|deleted
  priority: *normal|low|high
  note?: string & length(min(1) & max(500))
})
```

<!-- test: run -->
```sh
$ aontu jsonschema event.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "id": {
      "pattern": "^evt_[0-9a-f]{12}$",
      "type": "string"
    },
    "kind": {
      "enum": [
        "created",
        "updated",
        "deleted"
      ]
    },
    "note": {
      "maxLength": 500,
      "minLength": 1,
      "type": "string"
    },
    "priority": {
      "default": "normal",
      "enum": [
        "normal",
        "low",
        "high"
      ]
    }
  },
  "required": [
    "id",
    "kind",
    "priority"
  ],
  "type": "object"
}
```

Everything here crossed exactly: `re()` as `pattern`, the scalar
disjunctions as `enum` with the `*` preference as `default`,
`length()` on a string as `minLength`/`maxLength`, the optional
`note` out of `required`, and the root `close()` as
`additionalProperties: false`: the one thing the two languages say
identically. This output is pasteable into an OpenAPI components
entry with nothing to strip.

## Export one definition with `--at`

`--at <path>` names the subtree to export, the same anchor
[`vet --at`](/docs/reference-api#aontu-vet) takes. This is the MCP
move: keep a registry of tools in one document and answer each tool's
`inputSchema` from its own anchor. Write a one-tool registry as
`tools.aon`:

<!-- test: file tools.aon -->
```aontu
argschemas: type(close({
  search_docs: close({
    query: string & length(min(1) & max(256))
    limit?: integer & min(1) & max(50)
    scope?: workspace|org|web
  })
}))
```

<!-- test: run -->
```sh
$ aontu jsonschema --at '$.argschemas.search_docs' tools.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "query": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "scope": {
      "enum": [
        "workspace",
        "org",
        "web"
      ]
    }
  },
  "required": [
    "query"
  ],
  "type": "object"
}
```

The export reads straight through the `type()` mark, and the
closedness the agent must respect crosses without loss: a
hallucinated argument is a refusal on the aontu side and
`additionalProperties: false` on the JSON Schema side. Stderr stayed
empty for this run because the registry is written in the crossing
subset: kinds, scalar enums, bounds, `re()`, string `length()`,
optional keys, `close()`. The full crossing table is in the
reference under
[`aontu jsonschema`](/docs/reference-api#aontu-jsonschema).

## Read the loss report

Constructs JSON Schema cannot say still export, as the nearest
admissible schema, and each one is named on stderr with its path and
construct. Collect the classes in `report.aon`:

<!-- test: file report.aon -->
```aontu
report: {
  total: number & must((v) => 0 <= v, "total must not be negative")
  amountEur: bigdecimal
  audit: hide("kept-off-the-wire")
  attempts: [&: integer] & length(max(3))
}
```

<!-- test: run -->
```sh
$ aontu jsonschema --at report report.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "amountEur": {
      "type": "number"
    },
    "attempts": {
      "items": {
        "type": "integer"
      },
      "maxItems": 3,
      "minItems": 0,
      "type": "array"
    },
    "total": {}
  },
  "required": [
    "amountEur",
    "attempts",
    "total"
  ],
  "type": "object"
}
```

That exit was 0: a lossy export is still an export, so redirecting
stdout writes a usable schema. The report went to stderr, and
`--strict` turns it into a failure for pipelines that must not ship
a schema admitting more than the model does:

<!-- test: run -->
```sh
$ aontu jsonschema --strict --at report report.aon
...
lossy: $.report.amountEur bigdecimal: JSON has one number type and it is binary64, so the EXACTNESS this leaf exists for cannot be carried; the schema says "number" and a consumer may round
lossy: $.report.attempts length: a count with no domain is exported as minItems/maxItems; JSON Schema has no keyword that counts a string OR a container
lossy: $.report.audit hide: a hidden entry is not generated, so it is omitted from the schema; a consumer is neither asked for it nor allowed to know about it
lossy: $.report.total nil: this is not a value yet, so there is nothing to constrain a consumer to; the schema admits anything here
$ echo $?
1
```

`--format json` carries the same report as data (`verdict: "lossy"`,
each loss as `{path, construct, reason}`, the schema embedded) for a
build step that wants to allowlist specific losses rather than fail
on any. The `bigdecimal` loss is the one with a way around it:
[carry exact money over JSON](/how-to/carry-exact-money-over-json) crosses
the export loss-free as a decimal string with a conversion mark.

## Four edges

The report above already pins two of them. First, `must()` holds the whole value residual, so `number &
must(...)` exports `{}` under the construct name `nil`: the check is
opaque by construction, and the `number` kind beside it is lost with
it (a concrete `5 & must(...)` exports `{}` all the same). Second,
`length()` on a list has no domain until data arrives, so `attempts`
exported real `minItems`/`maxItems` and was still reported: the
keywords are the sizing atom's best rendering, not its meaning.

Third, a spread template crosses as `additionalProperties` (or
`items`) only when it is a bare kind. A template carrying a
constraint call stays residual and exports `{}`, reported as
`unresolved`. Put both in `spreads.aon`:

<!-- test: file spreads.aon -->
```aontu
labels: { &: string }
annotations: { &: string & length(max(63)) }
```

<!-- test: run -->
```sh
$ aontu jsonschema --strict spreads.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "annotations": {
      "additionalProperties": {},
      "properties": {},
      "type": "object"
    },
    "labels": {
      "additionalProperties": {
        "type": "string"
      },
      "properties": {},
      "type": "object"
    }
  },
  "required": [
    "annotations",
    "labels"
  ],
  "type": "object"
}
lossy: $.annotations.& unresolved: this is not a value yet, so there is nothing to constrain a consumer to; the schema admits anything here
$ echo $?
1
```

`labels` admits string values; `annotations` admits anything, and
says so. The same split decides list templates: `[&: string]`
crosses as `items`, a constrained element template does not.

Fourth, `deprecate()` crosses as the annotation 2020-12 has for it,
`deprecated: true`, and what the deprecation SAYS does not, because
the draft has no field for it. That half is reported. Write
`legacy.aon`:

<!-- test: file legacy.aon -->
```aontu
region: deprecate(string & re("^[a-z]{2}-[a-z]+-[0-9]$"), {
  msg: "renamed"
  use: "$.zone"
  since: "2.0.0"
})
```

<!-- test: run -->
```sh
$ aontu jsonschema --strict legacy.aon
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "region": {
      "deprecated": true,
      "pattern": "^[a-z]{2}-[a-z]+-[0-9]$",
      "type": "string"
    }
  },
  "required": [
    "region"
  ],
  "type": "object"
}
lossy: $.region deprecate: JSON Schema 2020-12 has the `deprecated` flag and no field for what it SAYS, so msg/use/since cannot cross; the schema marks the property deprecated and a consumer must read the model for the reason
$ echo $?
1
```

A consumer of the exported schema learns that the property is
deprecated, which is the part that changes what a client does. It does
not learn the reason, the replacement or the version (`msg`, `use`
and `since` have nowhere to go in 2020-12), so `--strict` reports that
half and exits 1. Announce renames through a channel that carries the
text.

## The refusals

A lossy export exits 0; a run that cannot produce a truthful schema
at all exits 4, and stdout stays empty: never a partial schema. An
`--at` that names nothing is one such run:

<!-- test: run -->
```sh
$ aontu jsonschema --at '$.reprot' report.aon
$: no_path [reference]
  [aontu/no_path]: Cannot at value at path $
...
$ echo $?
4
```

So is a document that does not stand up on its own, such as a
dangling reference in `dangling.aon`:

<!-- test: file dangling.aon -->
```aontu
spec: owner: $.people.alice.email
people: {}
```

<!-- test: run -->
```sh
$ aontu jsonschema dangling.aon
$.spec.owner: no_path [reference]
  [aontu/no_path]: Cannot resolve value at path $.spec.owner
  data: dangling.aon:1:14 ($.people.alice.email)
$ echo $?
4
```

That is not a loss to report: the verb exports what a document
*means*, and this one does not mean anything.

The live version is
[use-cases/14-jsonschema-export](/use-cases/14-jsonschema-export):
a three-tool registry exported per-anchor with empty stderr, a wire
message exported whole, the money convention crossing intact, and
every loss class pinned by golden files, including the exports
re-checked under a stock JSON reader.

---

# Generate code from a model

_Generate target-language source from a model: a rule set over the records, a component tree of files and lines, and `aontu render` to write the bytes and hold them against their goldens._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/generate-code.md · Page: https://aontu.dev/how-to/generate-code

A model that holds the field names, the types, and the optionality
already holds everything a Go struct or a TypeScript interface needs.
This guide computes a Go file from one with a rule set (`emit`), as a
**component tree**: a `File` holding the `Line` nodes the model
produced. aontu answers the tree; a generator runtime writes it.

For the full worked version (three targets in one document, goldens,
and a check that both ports answer byte-identical files) see
[`use-cases/15-code-generation/`](/use-cases/15-code-generation).

## Hold the target text in a backtick string

`"…"` and `'…'` refuse a literal newline. `` `…` `` accepts one, so a
backtick string carries a block of another language as one value, and
escapes work in it: `\t` is a tab and `` \` `` a literal backtick.
Write this as `frag.aon`:

<!-- test: scenario generate-code -->
<!-- test: file frag.aon -->
```aontu
tag: `json:"id"`
row: `\tID string`
```

<!-- test: run -->
```sh
$ aontu -c frag.aon
{"row":"\tID string","tag":"json:\"id\""}
```

## Write the rules

A generator is a **rule set**: `emit(select, table)` visits every node
of a selection in source order, takes the first template whose `match`
the node unifies with, and instantiates its `body` against that node:
`.name` is that node's `name`. The body is a list of **children** of
the component the rule is filling. A bare string is a `Line`, `line(s)`
is the same thing written out, and a nested `emit` splices its children
into the list, so the result is flat.

`file(name, children)` names a file and holds its lines. Write this as
`types.aon`:

<!-- test: file types.aon -->
```aontu
records: [
  {
    name: "Customer"
    fields: [{ n:"id" t:"string" go:"ID" } { n:"email" t:"string" go:"Email" }]
  }
]

%field = emit(_, {
  match: n: string
  body: [
    line(
      "\t" + .go + " " + match(.t, "string", "string", "integer", "int64")
      + ` \`json:"` + .n + `"\``
    )
  ]
})

%record = emit(_, {
  match: name: string
  body: ["" "type " + .name + " struct {" emit(.fields, %field) "}"]
})

out: file("types.go", ["package acme" emit($.records, %record)])
```

Each piece of that shape is there for a reason:

- **A rule set walks the records in source order.** List order is what
  a file needs; `pack` would key by data and emit the records
  alphabetically: silently wrong output for a file.
- **Lines, not text.** A record contributes a blank line, a head, its
  fields and a tail; a field contributes one line. A `Line` writes its
  terminator, so nothing here spells a newline, and the indent is the
  target's own: a tab in the string, because aontu knows no languages
  and has no view about how Go indents.
- **The file is a value.** `$.out` is the tree, so `aontu model get` reads it,
  `aontu vet` checks it, and a second generator can meet it.
- **The source keys ride through.** `emit` binds the body to the node,
  so `.name` and `.fields` resolve inside the template without the node
  being copied anywhere.

## Read the tree

The tree is an ordinary value, so the verb that answers it is `get`:

<!-- test: run -->
```sh
$ aontu model get $.out types.aon
{
  "children": [
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "package acme"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": ""
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "type Customer struct {"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "\tID string `json:\"id\"`"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "\tEmail string `json:\"email\"`"
      }
    },
    {
      "children": [],
      "cmp": "Line",
      "props": {
        "src": "}"
      }
    }
  ],
  "cmp": "File",
  "props": {
    "name": "types.go"
  }
}
```

That is the file, as data. No host unwraps a string, decides an
ordering, or adds a separator: the transform said which lines exist and
in what order, and each one carries its own text.

## Write the files, and hold them

[`aontu render`](/docs/reference-api#aontu-render) hands the tree to
[jostraca](https://github.com/jostraca/jostraca), the generator runtime,
which writes it: `Project`, `Folder`, `File`, `Line` and the rest are
its components, and it is a dependency of both implementations. This
tree is one file, so the path names the file:

<!-- test: run -->
```sh
$ aontu render types.aon gen/types.go
```

`gen/types.go` is on disk. `--check` writes nothing and compares,
exiting 1 on drift and naming the files that differ:

<!-- test: run -->
```sh
$ aontu render --check types.aon gen/types.go
```

That is the CI form. Commit the generated files beside the model and
run the comparison in CI; a hand edit to a generated file is then a red
build rather than a silent divergence from the model. A project written
in several languages is a folder of generators, one file per language,
and `aontu render gen/ app` writes every generator directly in `gen/`
as one run, with one `--check` for the set.

Nothing in aontu walks the tree to disk. The value is checkable
without a runtime (`aontu model get` above), and the runtime writes
the bytes, so what a user gets is what the check held.

## Ask what wrote a line

A reader looking at one line of generated output has no way back to the
rule that produced it. [`aontu trace`](/docs/reference-api#aontu-trace)
answers that, one entry per stamped piece: the file it reached, the
model node the dispatch matched, and the rule set that wrote it.

<!-- test: run -->
```sh
$ aontu trace types.aon
types.go	$.children.1	$.records.0	$.%record#0
types.go	$.children.2	$.records.0	$.%record#0
types.go	$.children.3	$.records.0.fields.0	$.%field#0
types.go	$.children.4	$.records.0.fields.1	$.%field#0
types.go	$.children.5	$.records.0	$.%record#0
```

**What is missing from that list is as useful as what is in it.**
`$.children.0` is the package clause, which the document writes by hand
rather than a rule producing it, so no rule stamped it and it has no
entry. `--format json` is the same report for a tool.

## Write the generator in the target's own syntax

A body of quoted lines is a generator a compiler cannot read. The same
generator can be written as a file **in the language it generates**:
one rule, a marked line is aontu source and every other line is a line
of output. The marker is the target's comment token plus a dash, so the
file stays valid in its own language. Write the model as `model.aon`:

<!-- test: file model.aon -->
```aontu
records: [
  { name:"Customer" note:"one account holder" }
  { name:"Order" note:"one purchase" }
]
```

and the generator as `struct.go`:

<!-- test: file struct.go -->
```go
//- @"./model.aon"
//- out: emit($.records, {
//- match: { name: string }
//- body: [file(.name + ".go", emit([_], {
//- match: { name: string }
//- replace: { NAME: .name, NOTE: .note }
//- body: [
package acme

// NAME is NOTE. Generated: edit the model, not this file.
type NAME struct{}
//- ]}))]
//- })
```

Every verb that reads a generator reads it directly (the entry's
extension says it is a template), so there is nothing new to learn
about generation itself:

<!-- test: run -->
```sh
$ aontu trace struct.go
Customer.go	$.0	$.records.0	#0
Customer.go	$.0.children.0	$.records.0	#0
Customer.go	$.0.children.1	$.records.0	#0
Customer.go	$.0.children.2	$.records.0	#0
Customer.go	$.0.children.3	$.records.0	#0
Order.go	$.1	$.records.1	#0
Order.go	$.1.children.0	$.records.1	#0
Order.go	$.1.children.1	$.records.1	#0
Order.go	$.1.children.2	$.records.1	#0
Order.go	$.1.children.3	$.records.1	#0
```

The rule is `#0` with no name, because the table is written inline at
the call rather than bound to a `%name`.

A list of files is written below the path:

<!-- test: run -->
```sh
$ aontu render struct.go gen
```

Three things follow from writing it this way:

- **The output lines are the target's, at their own indentation.**
  `gofmt` formats them, an editor highlights them, and `go vet` reads
  the generator itself. What the target sees is a file with four
  comments in it. The MARKER lines are aontu's half, and `aontu fmt`
  formats them: the marker stands at the left margin with the aontu
  indented after it, so the tree the generator carries has a shape on
  the page without any of the target's lines moving.
- **A value still arrives through `replace`.** `NAME` is a string the
  body holds, matched exactly, so no delimiter can collide with the
  target's syntax. That needs an inner dispatch: `replace` reaches the
  lines a rule wrote, so the file's lines and the map naming the file
  are two rules rather than one.
- **The whitespace is the artifact.** A line of two spaces is two
  spaces of output, so the generator's bytes matter as much as the
  generated file's. `aontu template --check struct.go` holds the file
  to the spelling the round trip answers, and the byte gate against the
  committed output catches a body line whose whitespace changed: an
  editor set to trim on save, say.

`aontu template struct.go` prints the canonical form, the aontu the
marked lines mean, for reading rather than for keeping. `aontu fmt
struct.go` formats the generator ITSELF: it desugars, formats the
document the marker lines carry, and resugars, so what comes back is a
generator with every output line where it was. A file with no marker
line in it is another language's, and is refused by name.

## Put the target's names in the model

aontu knows no languages: there is no table of reserved words, no
acronym set and no case rule inside it, and a generator spells the
target's names itself. `nom(name, style, acronyms)` does the casing,
so `nom("ledger_id", pascal, ["ID"])` is `LedgerID`, and the acronym
list is the generator's, written where a reader can see it.

Better still, write the target's spelling as data, as `go: "ID"` does
above. What a type is called in a target is a fact about the model
rather than a rule in a template, which is the split every code
generator that survived contact with many languages arrives at.
Writing it down makes a name collision a unification conflict instead
of a broken identifier at emit time.

## Related

- [`aontu render`](/docs/reference-api#aontu-render). The verb that
  writes the tree, and its `--check`.
- [`aontu trace`](/docs/reference-api#aontu-trace). What wrote a line:
  the file, the model node and the rule.
- [Transforming: `emit`](/docs/reference-language#transforming-emit).
  Dispatch order, splicing, named tables and recursion.
- [`aontu template`](/docs/reference-api#aontu-template). The two
  transforms, the markers by extension, and the round trip.
- [Export JSON Schema](/how-to/export-json-schema). The other bridge out of
  the model.
- [Keep schema out of output](/how-to/keep-schema-out-of-output). `hide()`
  and marks, and what they do to generation.

---

# Query a path

_Print one node of the evaluated document by path, or a keys, types, or depth-limited view of it._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/query-a-path.md · Page: https://aontu.dev/how-to/query-a-path

An evaluated document is one JSON value, and most questions are about
one node of it. `aontu model get` selects that node by path (the same path
a reference means by `$.a.b`) and prints it alone. Write
`system.aon`:

<!-- test: scenario query-a-path -->
<!-- test: file system.aon -->
```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

Now ask for one service:

<!-- test: run -->
```sh
$ aontu model get $.services.auth system.aon
{
  "replicas": 3,
  "tier": "standard"
}
```

The `tier` came from the `&:` template, not from the `auth` line: you
are querying the evaluated document, not the source text. (Evaluation
is global (unification has no partial mode) so `get` buys you a
smaller answer, never a cheaper run.)

Three flags give a smaller answer rather than a smaller slice: the
keys alone, the shape with concrete leaves lifted to their kinds, and
the structure cut off at a depth:

<!-- test: run -->
```sh
$ aontu model get $.services --keys system.aon
auth
billing
$ aontu model get $.services.auth --types system.aon
{"replicas":integer,"tier":*string|string}
$ aontu model get $ --depth 1 --canon system.aon
{"services":top}
```

Each view is itself a valid aontu document that generalises the
truth: `top` means "no further information at this tier". `--depth` needs
`--canon` or `--types`, because JSON has no way to write `top`.

A path that names nothing exits `1` and guesses:

<!-- test: run -->
```sh
$ aontu model get $.services.authz system.aon
$.services.authz: no_path [reference]
  The path $.services.authz names nothing in this document.
  note: did you mean auth?
$ echo $?
1
```

A missing key and an empty value are different answers, so this is a
refusal with a suggestion, not an empty render. In a script, branch on
the exit code: `0` rendered, `1` no such path, `4` the document does
not stand up on its own (a residual node has no JSON to print).

The flags, exit codes, and the subsumption claim behind the
projections are specified under [`aontu
get`](/docs/reference-api#aontu-model-get). To see the whole document in
one reparseable line instead of a slice, [see the canonical
form](/how-to/see-canonical-form); to ask who put the value there rather
than what it is, [explain the value](/how-to/explain-a-value).

---

# Explain a value

_List every contribution that met at a path (which file, which line, which layer) with aontu model why._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/explain-a-value.md · Page: https://aontu.dev/how-to/explain-a-value

A layered document tells you what won and keeps quiet about who was in
the race. `aontu model why` lists every value the author *wrote* that
[met](/docs/unification) at a path, in source order, with the site each
was written at. The file below is the [deployment
fleet](/use-cases/02-deploy-config) use case trimmed to two layers
in one file: in the live version the layers are separate files, and the
sites carry each file's name. Write `stack.aon`:

<!-- test: scenario explain-a-value -->
<!-- test: file stack.aon -->
```aontu
# the org layer: a default for every service
services: { &: { logLevel: ***info|string replicas: ***1|integer } }

# the prod layer: stronger defaults and pins
services: auth: { logLevel: *warn|string replicas:3 }
services: billing: {}
```

Ask why `auth` runs three replicas:

<!-- test: run -->
```sh
$ aontu model why $.services.auth.replicas stack.aon
$.services.auth.replicas = 3
  1. ***1|integer  stack.aon:2:53  (spread)
  2. 3  stack.aon:5:51
```

The role in brackets marks a contribution that arrived indirectly:
`(spread)` is the `&:` template on line 3, applied to this key. The
concrete `3` carries no role: the author wrote it at the path it
stands at. Contributions are listed in source order (file, row,
column), not in the order the engine happened to meet them.

The same question at `logLevel` shows the rank ladder mid-argument:

<!-- test: run -->
```sh
$ aontu model why $.services.auth.logLevel stack.aon
$.services.auth.logLevel = *"warn"|***"info"|string
  1. ***"info"|string  stack.aon:2:28  (spread)
  2. *"warn"|string  stack.aon:5:29
```

The value at the path is the merged disjunction of both defaults;
generation then picks `warn`, because fewer stars is the stronger
rank (see [provide defaults](/how-to/provide-defaults)). `why` shows the
value *standing* at the path, which is exactly what you need when the
generated answer surprises you.

A path where only a template ever wrote still answers: the default
that stands there is a contribution, and its site is the line the
author wrote it on:

<!-- test: run -->
```sh
$ aontu model why $.services.billing.replicas stack.aon
$.services.billing.replicas = ***1|integer
  1. ***1|integer  stack.aon:2:53  (spread)
```

A path that names nothing is a refusal, exactly as it is for `get`:

<!-- test: run -->
```sh
$ aontu model why $.services.auth.memory stack.aon
$.services.auth.memory: no_path [reference]
  The path $.services.auth.memory names nothing in this document.
$ echo $?
1
```

For a program, `--format json` emits the record (`{path, value,
conjuncts: [{canon, role, site}]}`) with sites in the shape the vet
report uses. Provenance travels with a clone, so a value that reached
its path through a template, a `pack()` generator, or a `$ref` is
reported as the value the author wrote, where they wrote it.

The contribution rules and roles are specified under [`aontu
why`](/docs/reference-api#aontu-model-why); the live version asks the same
question across four layers of authority in
[use-cases/02-deploy-config](/use-cases/02-deploy-config).
`why` also names the line that will refuse your next edit, when it
does, [change the value with an
overlay](/how-to/change-a-value-with-an-overlay).

---

# Change a value with an overlay

_Append a change to an overlay file with aontu model set, so the original document keeps its bytes and a bad change is refused before it lands._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/change-a-value-with-an-overlay.md · Page: https://aontu.dev/how-to/change-a-value-with-an-overlay

Use `aontu model set` to append a change to an *overlay*, a second document
unified with the entry. The command checks the proposed change before
writing it and preserves the entry file. Write `system.aon`:

<!-- test: scenario change-overlay -->
<!-- test: file system.aon -->
```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

Now raise billing's replicas without opening the file:

<!-- test: run -->
```sh
$ aontu model set '$.services.billing.replicas=2' --entry system.aon --overlay overlay.aon
verdict: valid
wrote: overlay.aon
```

The command creates a missing overlay. The file contains one assignment
written as a chain of keys:

```aon
services: billing: replicas: 2
```

The entry and the overlay together are the changed document.
Unification is order-independent, so appending to a second file means
the same thing as writing into the first; to consume both, write an
`all.aon` that loads them:

<!-- test: file all.aon -->
```aontu
@"./system.aon"
@"./overlay.aon"
```

<!-- test: run -->
```sh
$ aontu all.aon
{
  "services": {
    "auth": {
      "replicas": 3,
      "tier": "standard"
    },
    "billing": {
      "replicas": 2,
      "tier": "premium"
    }
  }
}
```

Billing overrides its `*1` default; auth keeps its pin. Overriding a
default is the case `set` handles cleanly, because a default invites
a concrete peer. A pinned value does not:

<!-- test: run -->
```sh
$ aontu model set '$.services.auth.replicas=5' --entry system.aon --overlay overlay.aon
verdict: invalid

$.services.auth.replicas: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.services.auth.replicas
  data: overlay.aon:2:33 (5)
  schema: system.aon:2:27 (3)
$ echo $?
1
```

The overlay is written only when the change holds, so this refusal
leaves its contents unchanged. The finding names
the site doing the pinning (`system.aon:3:24`, which [`aontu
why`](/how-to/explain-a-value) will list as a contribution) and to
rewrite that literal rather than contradict it, [change the pinned
value](/how-to/change-a-pinned-value).

`--dry-run` writes nothing either way and prints what would have been
written; exit codes are [`aontu
vet`](/docs/reference-api#aontu-vet)'s verdict classes, so the verb
gates automation on its own. Keep the overlay *outside* the entry's
include graph: an entry that loads its own overlay counts every
change twice. The flag-by-flag contract is under [`aontu
set`](/docs/reference-api#aontu-model-set), and the live version is
[use-cases/08-feature-flags](/use-cases/08-feature-flags),
where an ops overlay is written by `set --in-place` and never by
hand, and repeated writes of one path leave one line.

---

# Gate an agent's changes by role

_Ask aontu allow whether a role may change a subtree before aontu model set writes it, with the answer read from a role model that is itself an aontu document._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/gate-changes-by-role.md · Page: https://aontu.dev/how-to/gate-changes-by-role

An agent that edits a model under a role (`dev`, `product`, an
on-call rotation) has to be told no before it writes, and the rules
that say no should live in a document the same tools read. Write
`roles.aon`:

<!-- test: scenario gate-by-role -->
<!-- test: file roles.aon -->
```aontu
roles: dev: {
  allow: ["$.services" "$.deploy.*.replicas"]
  deny: ["$.services.*.tier"]
}
roles: product: allow: ["$.features" "$.services.*.description"]
```

Each role names the subtrees it may change and, optionally, the ones
it may not; `*` stands for any one key. Now ask, with the very
assignment the agent is about to hand `set`:

<!-- test: run -->
```sh
$ aontu allow --role dev roles.aon '$.services.auth.tier="standard"'
verdict: refused
role: dev
$.services.auth.tier: refused by $.roles.dev.deny.0 ($.services.*.tier)
$ echo $?
1
```

The path is what is judged, and the value only has to be one value: a
second pair inside it would write a subtree the gate was not asked
about, so such a call is refused as usage. The answer names the rule
as a path into the role model, so `aontu model why '$.roles.dev.deny.0'
roles.aon` lists who wrote it and where. Ask again for a path the
role does cover:

<!-- test: run -->
```sh
$ aontu allow --role dev roles.aon '$.services.auth.replicas=4'
verdict: allowed
role: dev
$.services.auth.replicas: allowed by $.roles.dev.allow.0 ($.services)
```

Exit 0 is the cue to write. Given a `model.aon` whose replicas are a
default:

<!-- test: file model.aon -->
```aontu
services: {
  &: { tier: *standard|string replicas: *1|integer description?:string }
  auth: tier: premium
  billing: {}
}

features: dark_mode: false
```

the same assignment goes to [`aontu
set`](/how-to/change-a-value-with-an-overlay) unchanged:

<!-- test: run -->
```sh
$ aontu model set '$.services.auth.replicas=4' --entry model.aon --overlay overlay.aon
verdict: valid
wrote: overlay.aon
```

The gate and the write take one spelling, so a skill runs the first
and, on exit 0 alone, the second. Two answers are easy to misread. A
deny entry refuses the paths above it as well as the ones below: `dev`
may not change `$.services.auth` either, because a change there could
rewrite the tier, and asking about the parent is how an agent that
plans to replace a whole service finds that out. And a call that lost
its paths, or hands an empty one, is a usage error (exit 2), never
`allowed`, so a script that branches on exit 0 cannot be let through
by an empty question.

The rule in full, the `--at` and `--format json` flags, and the shape
every role must satisfy are under [`aontu
allow`](/docs/reference-api#aontu-allow). The live version is
[use-cases/18-role-permissions](/use-cases/18-role-permissions),
where a closed role vocabulary governs a service model, an agent skill
asks before every write, and the proposals that touch a denied subtree
are refused with the rule named.

---

# Change a pinned value

_Rewrite a pinned literal where the author wrote it with aontu model set --in-place, and know the cases where the verb appends instead._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/change-a-pinned-value.md · Page: https://aontu.dev/how-to/change-a-pinned-value

Appending cannot change a pinned value: the append makes two concrete
facts at one path, and the lattice refuses both. `--in-place` closes
the loop by rewriting the literal where the author wrote it. To see
both behaviours, write a `schema.aon` that constrains the fields:

<!-- test: scenario change-pinned -->
<!-- test: file schema.aon -->
```aontu
replicas: integer & min(1) & max(24)
port: integer
```

and a `deploy.aon` overlay that pins them, comments included:

<!-- test: file deploy.aon -->
```aontu
# the deployment
replicas: 42 # too many
port: 0x1F
```

Plain [`aontu model set`](/how-to/change-a-value-with-an-overlay) refuses,
because the overlay would then disagree with itself:

<!-- test: run -->
```sh
$ aontu model set '$.replicas=5' --entry schema.aon --overlay deploy.aon
verdict: invalid

$.replicas: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.replicas
  data: deploy.aon:4:13 (5)
  data: deploy.aon:2:11 (42)
$ echo $?
1
```

Both sites are labelled `data:`: the pin and the contradiction live
in the same file, which is exactly why appending cannot help. Add
`--in-place` and the literal is rewritten instead:

<!-- test: run -->
```sh
$ aontu model set '$.replicas=5' --entry schema.aon --overlay deploy.aon --in-place
verdict: valid
replaced: deploy.aon:2:11 42 -> 5
wrote: deploy.aon
$ echo $?
0
```

The file now reads:

```aon
# the deployment
replicas: 5 # too many
port: 0x1F
```

Comments and layout survive, including the one on the edited line,
because nothing is re-serialised: the span at `(row, col, len)` is
replaced and every other byte is left exactly as it was. The edit is
also verified before it is written: a site carries the source text
it claims to cover, and the text at the span must match it. That is
what makes a hex literal safe to rewrite even though its *value* is
`31`:

<!-- test: run -->
```sh
$ aontu model set '$.port=80' --entry schema.aon --overlay deploy.aon --in-place
verdict: valid
replaced: deploy.aon:3:7 0x1F -> 80
wrote: deploy.aon
```

The report speaks in source text (`0x1F -> 80`), because replacing a
spelling is a different edit from replacing a value.

Where it cannot rewrite, it appends as plain `set` would and says why
in a warning. A warning never moves a verdict, so `--in-place` is
never worse than `set` without it:

| the overlay says | why not | what happens |
|---|---|---|
| `a: min(1)`, `a: 1+2`, `a: {b:1}` | the site names the opening token of a compound, not the whole value | appended, `patch_not_editable` |
| `a: 1` twice | two statements pin it; there is no single place to edit | appended, `patch_ambiguous` |
| a `&:` template, a `$ref` | the value comes from elsewhere; edit it there | appended, `patch_not_editable` |
| `a: integer`, `a: above(0)` | a constraint, not a pin: appending narrows it without discarding it | appended, `patch_not_editable` |
| anything, when the overlay itself `@"includes"` another document | a loaded literal's position cannot be told from the overlay's own | appended, `patch_not_editable` |

A default (`a: *1`) is not in the table: appending already overrides
it correctly, so `--in-place` leaves it alone and says nothing.

The last row cuts both ways, and the reverse direction is easy to get
wrong. To change a value that lives in an *included* file, name that
file as the overlay, but give `--entry` something that constrains the
value without also pulling the file in. Write a `stack.aon` entry that
loads `deploy.aon`, the natural arrangement and the wrong one here:

<!-- test: file stack.aon -->
```aontu
@"./deploy.aon"
replicas: integer & min(1) & max(24)
port: integer
```

<!-- test: run -->
```sh
$ aontu model set '$.replicas=9' --entry stack.aon --overlay deploy.aon --in-place
verdict: invalid
would replace: deploy.aon:2:11 5 -> 9

$.replicas: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.replicas
  data: deploy.aon:2:11 (9)
  schema: deploy.aon:2:11 (5)
$ echo $?
1
```

The overlay's value [meets](/docs/unification) *itself* through the
entry's include, so the run is refused and nothing is written. `would
replace:` (rather than `replaced:`) tells you the edit itself was
possible and the conflict lay elsewhere: here, in the shape of the
invocation. Pass `schema.aon` as the entry, as the earlier runs do, and
the same command holds. ([Why the tool refuses the shape instead of
detecting the
collision](/docs/explanation#the-emit--validate--repair-loop).)

Pair `--in-place` with `--dry-run` to see the rewritten overlay
without writing it. The full editability rules are under [`aontu
set`](/docs/reference-api#aontu-model-set); after any refusal, [`aontu
why`](/how-to/explain-a-value) lists every line involved; and the live
version, an ops overlay repeatedly rewritten in place, is
[use-cases/08-feature-flags](/use-cases/08-feature-flags).

---

# Find dead entries

_Report map entries whose removal changes nothing, so layered files do not silt up with lines a template already implies._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/find-dead-entries.md · Page: https://aontu.dev/how-to/find-dead-entries

Layered files silt up: an entry written before the template existed
now repeats what the template already says, and deleting it by eye is
a bet. `aontu trim --check` settles the bet by evaluation: each map
entry is deleted in turn, the document re-evaluated, and the entries
that made no difference are reported as paths. Write `services.aon`:

<!-- test: scenario find-dead-entries -->
<!-- test: file services.aon -->
<!-- fmt: keep the template and the entry in one map, which is what trim reads -->
```aontu
services: {
  &: { tier: standard }
  auth:    { tier: standard, replicas: 3 }
  billing: { replicas: 1 }
}
```

Now check it:

<!-- test: run -->
```sh
$ aontu trim --check services.aon
verdict: redundant

$.services.auth.tier
$ echo $?
1
```

`auth.tier` restates the `&:` template, so the document means the
same thing without it. The test is evaluate-and-compare, not pattern
matching, which covers everything the fixpoint can see: spread
templates, references, duplicate-key merges. (A removal that makes
the document *error* is not redundant: the document does not stand
up without that entry.)

Delete the dead line yourself (trim only reports) and re-declare
`services.aon`:

<!-- test: file services.aon -->
```aontu
services: { &: { tier:standard } auth:replicas:3 billing:replicas:1 }
```

<!-- test: run -->
```sh
$ aontu trim --check services.aon
verdict: clean
$ echo $?
0
```

Exit `0` is `clean` and exit `1` is `redundant`, so the verb gates a
lint job as it stands; `--format json` gives the paths as a
`redundant` array. Two limits to know: list elements are never
candidates (removing one renumbers the rest, a different document
rather than a leaner one), and `--check` is required: a bare `aontu
trim` that silently did something other than trimming would be worse
than refusing.

The candidate rules and the `error` verdict's report shape are under
[`aontu trim`](/docs/reference-api#aontu-trim). Run it beside your
schema gate when you [validate in CI](/how-to/validate-in-ci); when a
reported path surprises you, [explain the value](/how-to/explain-a-value)
to see which template is doing the implying.

---

# Draw a model

_Draw a model as a dependency tree, matrix or architecture layers with aontu view, and gate the committed figures in CI._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/draw-a-model.md · Page: https://aontu.dev/how-to/draw-a-model

A model that says which service depends on which, or which module sits
in which layer, already holds the picture. `aontu view` draws it from
the evaluated document, so the figure is a fact about the model rather
than a diagram someone kept in step with it.

Here is a `system.aon` with three services and a dependency relation:

<!-- test: scenario draw -->
<!-- test: file system.aon -->
```aontu
spec: hide({
  Service: {
    tier: "edge"|"core"
    dependsOn?: rel($.spec.Service) & acyclic() & [&: refer($.spec.Service)]
  }
})

web: $.spec.Service & { tier:"edge" dependsOn: [path($.api)] }
api: $.spec.Service & { tier:"core" dependsOn: [path($.store)] }
store: $.spec.Service & { tier:"core" }
```

The tree is the default kind. It derives its roots (a root is a node
nothing depends on) and prints nothing else, so a redirect is a golden
file:

<!-- test: run -->
```sh
$ aontu view tree --relation dependsOn system.aon
web
└── api
    └── store
```

The same edges as a **dependency-structure matrix**, in partition
order, mark a cell where the row depends on the column. A perfect
lower triangle is the acyclicity proof in the picture's own shape, and
the footer counts the cells above the diagonal:

<!-- test: run -->
```sh
$ aontu view matrix --relation dependsOn --order partition system.aon
        1 2 3
store 1 \ . .
api   2 X \ .
web   3 . X \
# above-diagonal direct cells: 0
```

## Draw the architecture layers

Any field of a node can be the band it belongs to. `--group-by` names
it, and the band order is derived from the relation rather than
declared, so it follows the model:

<!-- test: run -->
```sh
$ aontu view layer --relation dependsOn --group-by tier system.aon
+------------------+
| edge  web        |
+------------------+
| core  api  store |
+------------------+
# dependsOn: 1 downward, 1 sideways, 0 upward
```

The footer is the layering rule, counted: `web -> api` crosses a band
and `api -> store` stays inside one. An **upward** edge (one that
points back up the bands) is the violation, and is named under the
figure. `--edges all` draws the whole relation over the bands
instead, which is what a reader tracing one service's dependencies
wants.

## Get an SVG for a web page

The kinds whose text form is a grid of character cells (`tree`,
`matrix`, `layer`, `sets` and `layers`) also render as a standalone
SVG that carries its own style block and takes its colours from CSS
variables, so a page can theme it:

<!-- test: run -->
```sh
$ aontu view tree --relation dependsOn --as svg --out tree.svg system.aon
$ echo $?
0
```

The node-link kinds (`graph`, `ladder`, `poset`) render as Mermaid or
DOT, which have renderers of their own.

## Gate the figures in CI

A committed figure that nobody re-draws is a stale picture. Write the
figures down as data, in a `views.aon` that includes the model:

<!-- test: file views.aon -->
```aontu
@"aontu:view"
@"./system.aon"

views: { &: $.aontu.View.Figure } & {
  tree: { kind:tree relation:dependsOn out:"tree.txt" }
  matrix: { kind:matrix relation:dependsOn order:partition out:"matrix.txt" }
  layers: { kind:layer relation:dependsOn groupBy:tier as:svg out:"layers.svg" }
}
```

`views` is your key, not one the engine knows, so `--views` says where
to look. Each declaration's keys are the view options (the flags
without the dashes) and `@"aontu:view"` is the schema for one, so a
misspelled option or a kind that is not a kind is refused when the
document is evaluated.

Draw them all from one evaluation, then gate them:

<!-- test: run -->
```sh
$ aontu view --views '$.views' views.aon
$ aontu view --views '$.views' --check views.aon
$ echo $?
0
```

`--check` writes nothing and exits `1` naming every figure that
differs. Each `out` is resolved against the view document's own
directory, so the gate passes from any working directory; the
directory it names must already exist, as it must for `--out`. Nothing
is written unless every figure rendered: N figures of one model are
only meaningful together.

## What the figure could not draw

Every run reports its losses on stderr, so a figure written to a file
still tells the reader what it left out: a `hide()`-marked edge, a
`--group-by` field a node does not have, a cycle that blocks the
partition order, columns elided by `--max-cols`. `--strict` turns any
of that into exit `1`, and `--max-rows` refuses a figure too big to
read rather than truncating it.

## Related

- [`aontu view`](/docs/reference-api#aontu-view). Every kind, every
  option, the loss codes and the exit codes.
- [Query a path](/how-to/query-a-path). Read one node instead of drawing
  the whole shape.
- [Explain a value](/how-to/explain-a-value). Why one value is what it is,
  which the `ladder` kind draws.

---

# Validate data in CI

_Run aontu vet in a pipeline so a document that does not hold fails the build, with the reason attached._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/validate-in-ci.md · Page: https://aontu.dev/how-to/validate-in-ci

A schema nobody runs is a comment. The `vet` verb turns yours into a
gate: it validates data files against a schema document, prints
located findings, and exits with the verdict class, which is
everything a pipeline needs to go red for a reason.

Write the schema as `schema.aon`:

<!-- test: scenario ci-vet -->
<!-- test: file schema.aon -->
```aontu
user: { id:integer name:string admin:boolean }
```

and the data your pipeline produced as `user.json`:

<!-- test: file user.json -->
```json
{"user": {"id": "seven", "name": "ada", "admin": true}}
```

Now vet it:

<!-- test: run -->
```sh
$ aontu vet schema.aon user.json
verdict: invalid

$.user.id: no_scalar_unify [conflict]
  [aontu/no_scalar_unify]: Cannot unify values at path $.user.id
  data: user.json:1:17 ("seven")
  schema: schema.aon:1:12 (integer)
$ echo $?
1
```

The finding names both sides, data site first, because the data is
the side to edit. (To refuse *extra* keys too, wrap the schema in
`close`: see [Forbid unexpected keys](/how-to/forbid-unexpected-keys).)

## The exit code is the verdict class

There is more than one kind of "no", and a gate that collapses them
throws information away. Drop `id` from the data instead of mistyping
it, as `user2.json` does:

<!-- test: file user2.json -->
```json
{"user": {"name": "ada", "admin": true}}
```

<!-- test: run -->
```sh
$ aontu vet schema.aon user2.json
verdict: incomplete

$.user.id: mapval_no_gen [incomplete]
  [aontu/mapval_no_gen]: Cannot resolve value at path $.user.id
  schema: schema.aon:1:12 (integer)
$ echo $?
3
```

Nothing contradicts here; the truth is simply not met yet, and the
exit code says so:

| Exit | Verdict | What the pipeline should do |
|------|---------|-----------------------------|
| 0 | `valid` | pass |
| 1 | `invalid` | fail: the data contradicts the schema; repair the data |
| 3 | `incomplete` | fail: no contradiction, but required truth is unmet |
| 4 | `error` | fail loudly: the *schema* side is unusable, never the data's fault |

(Exit 2 is usage: a bad flag or an unreadable file.) A blanket
"non-zero is red" still gates correctly, but keeping 1 and 3 apart
lets an emit → validate → repair loop route the failure: exit 1 means
repair what was emitted, exit 3 means finish it, exit 4 means stop
and page whoever owns the schema. The full classes are specified
under [`aontu vet`](/docs/reference-api#aontu-vet).

## Reports for machines

`--format json` emits the same findings as one object; `--format
sarif` emits SARIF 2.1.0, the form GitHub code scanning ingests:

<!-- test: run -->
```sh
$ aontu vet --format sarif schema.aon user.json
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "runs": [
    {
      "invocations": [
        {
          "executionSuccessful": true
        }
      ],
...
$ echo $?
1
```

The exit code still carries the verdict, so a job can upload the
report and stay red.

## Wire it in

In GitHub Actions, the repository ships an action wrapping the verb,
[`vet-action/`](https://github.com/aontu-lang/aontu/blob/main/vet-action/README.md), which fails the job by
verdict class and can hand the SARIF to code scanning:

<!-- test: skip CI configuration; not executable here -->
```yaml
steps:
  - uses: actions/checkout@v4
  - uses: aontu-lang/aontu/vet-action@main
    with:
      schema: schema.aon
      data: user.json
```

As a pre-commit hook, the verb is one line, and the verdict classes
mean a half-finished document blocks the commit too:

<!-- test: skip git hook configuration; not executable here -->
```sh
#!/bin/sh
# .git/hooks/pre-commit
exec aontu vet schema.aon user.json
```

While editing, `--watch` re-runs the whole vet whenever the schema or
a data file changes, streaming one report per run:

<!-- test: skip --watch runs until interrupted; not executable here -->
```sh
$ aontu vet --watch schema.aon user.json
```

Every run is a full re-parse and re-unify, so what you see on each
save is exactly what CI will say.

## Make the gate prove it checked something

A gate that passes because it examined **nothing** is worse than no
gate: it reports success. The usual cause is one construct, and it is
silent. A schema written with the wildcard other tools use is a key
**named** `*` in aontu, so it meets no data key and constrains
nothing. Here it is as `wild.aon`:

<!-- test: scenario vacuous-gate -->
<!-- test: file wild.aon -->
<!-- fmt: keep the braces are the point: this is the block shape a caller writes, and the agreed form collapses it to a chain -->
```aontu
entity: { "*": { table: string } }
```

`rows.aon` is the data it was meant to check:

<!-- test: file rows.aon -->
```aontu
entity: planet: table: 42
```

<!-- test: run -->
```sh
$ aontu vet --partial --strict-coverage wild.aon rows.aon
verdict: valid
...
coverage: VACUOUS — no data leaf was constrained by the schema; this run checked nothing
coverage: 0/1 data leaves checked, 3 schema declarations
  unchecked: $.entity.planet
  unused: $.entity.*
aontu: no data leaf was constrained by the schema: this run checked nothing
...
$ echo $?
1
```

`--strict-coverage` is the CI form: it measures what the run examined
and exits 1 when the answer is nothing. The verdict word stays
`valid`, because the unification really did hold; what failed is the
gate's claim to have checked anything. Written with the template
`&:` the same run checks the field and refuses the `42`.

Use `--coverage` alone while writing a schema, to see which
declarations no data meets and which data paths nothing constrains,
and `--coverage-at` to measure one subtree.

Vetting gates the data; the schema itself changes too, and that gate
is [`aontu breaking`](/how-to/gate-schema-changes). For decoding an
individual finding, see [Read a conflict
error](/how-to/read-a-conflict-error).

---

# Gate schema changes

_Gate schema edits with aontu breaking, so a change that would refuse previously valid documents fails the review._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/gate-schema-changes.md · Page: https://aontu.dev/how-to/gate-schema-changes

Consumers validated their documents against the schema you published.
Edit it, and every one of those documents is re-judged. `vet` answers
"does this data hold?"; `breaking` answers the question a schema edit
raises: do documents that were valid against the old version still
hold under the new one?

Point it at the earlier version. Here is a released `profile-v1.aon`:

<!-- test: scenario gate -->
<!-- test: file profile-v1.aon -->
```aontu
profile: close({
  id: string & re("^C[0-9]{7}$")
  email: string
  tier: "standard"|"premium"|"enterprise"
})
```

and a proposed `profile-v2.aon` that adds one optional key:

<!-- test: file profile-v2.aon -->
```aontu
profile: close({
  id: string & re("^C[0-9]{7}$")
  email: string
  tier: "standard"|"premium"|"enterprise"
  locale?: string
})
```

Now ask whether the proposal breaks anybody:

<!-- test: run -->
```sh
$ aontu breaking --against profile-v1.aon profile-v2.aon
verdict: compatible
```

Additive and optional, so every v1-valid document is still admitted.
A proposal that *requires* a new key is a different story: write it
as `require-owner.aon`:

<!-- test: file require-owner.aon -->
```aontu
profile: close({
  id: string & re("^C[0-9]{7}$")
  email: string
  tier: "standard"|"premium"|"enterprise"
  locale?: string
  owner: string
})
```

<!-- test: run -->
```sh
$ aontu breaking --against profile-v2.aon require-owner.aon
verdict: breaking

$.profile.owner: compat_required_added [compat]
  the general value requires this key; the specific value admits instances without it
  expected: string
  actual:   {"email":string,"id":re("^C[0-9]{7}$"),"locale"?:string,"tier":"standard"|"premium"|"enterprise"}
  general: require-owner.aon:6:10 (string)
  specific: profile-v2.aon:1:10 ({"email":string,"id":re("^C[0-9]{7}$"),"locale"?:string,"tier":"standard"|"premium"|"enterprise"})
$ echo $?
1
```

Every old document that omitted `owner` is now refused, and the
finding names the key and both versions' sites. Narrowing an existing
field breaks the same way (`compat_narrowed`): tightening `email` to
a pattern rejects any v1 document with a plain string there.

## The query underneath

`breaking` is [subsumption](/docs/reference-language#subsumption)
pointed at history: the new version must **subsume** the old: admit
every instance the old admitted. The query is a verb of its own when
you want to compare two arbitrary documents rather than versions:

<!-- test: run -->
```sh
$ aontu subsume profile-v2.aon profile-v1.aon
verdict: subsumes
```

The general document goes first, the specific second. The same query
is a library export in both ports (`subsume` / `aontu.Subsume`) for
programmatic gates.

## In CI

`--against` also takes `git#<rev>`, so the gate needs no copies of
old versions lying around: it materialises the revision's tree and
evaluates the old document from there, includes and all:

<!-- test: skip requires a git checkout; the live version is use-cases/04-schema-evolution/check.sh -->
```sh
$ aontu breaking --against git#HEAD profile.aon
```

One line then gates every pull request against the branch it merges
into:

<!-- test: skip CI configuration; not executable here -->
```yaml
- run: aontu breaking --against git#origin/main profile.aon
```

## What to watch for

Exit `1` means a previously valid document is now refused. Exit `3`
means the query could not decide (always with a `sub_*` reason
naming why), and it **fails the gate** unless you pass
`--allow-undecided`; a gate that shrugs is not a gate. Two more
flags earn their keep in practice: `--at <path>` anchors the
comparison at the contract, so a version string at the top level
stops self-breaking the gate on every release, and
`--allow-deprecated-removal` admits the removal of a field the old
version already marked `deprecate()`: the supported rename path.
All of it is specified under [`aontu
breaking`](/docs/reference-api#aontu-breaking).

The live version is
[use-cases/04-schema-evolution](/use-cases/04-schema-evolution):
three released versions of a customer profile, every verdict above
asserted by its `check.sh`, the `git#HEAD` gate included. When a
change lands, [pin the new meaning](/how-to/pin-a-document-hash) so
consumers can tell it moved.

---

# Check that components agree about their relations

_Declare a relation once at the field with rel(), acyclic() and inverse(), and have the whole model's edge set checked._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/check-relations.md · Page: https://aontu.dev/how-to/check-relations

A model can hold field by field and still be wrong as a graph: a
dependency loop nobody meant, an edge whose other end never wrote it
down. Those are facts about the *finished* model, so you declare them
once, at the field, and the verdict lands when every edge is known.

## Declare the relation at the field

The vocabulary below is a trimmed version of
[use-cases/12-relations](/use-cases/12-relations), an ETL
pipeline where jobs feed jobs. Write it as `spec.aon`:

<!-- test: scenario relations -->
<!-- test: file spec.aon -->
```aontu
spec: hide({
  Job: {
    kind: job
    feeds?: rel($.spec.JobShape) & acyclic() & inverse(fedBy)
    fedBy?: rel($.spec.JobShape)
  }
  JobShape: kind: job
})
```

One conjunction on `feeds` declares the whole contract. `rel(t)`
makes the field's strings checked entity addresses and flows the
endpoint type `t` into every target; `acyclic()` and `inverse(fedBy)`
are the graph atoms: declarations that unification carries along
inert, whose verdict lands at generation. Data documents then stay
plain lists of names. Write the topology as `pipeline.aon`:

<!-- test: file pipeline.aon -->
```aontu
@"./spec.aon"

jobs: { &: $.spec.Job }
jobs: extract: feeds: [path($.jobs.transform)]
jobs: transform: { fedBy: [path($.jobs.extract)] feeds: [path($.jobs.load)] }
jobs: load: fedBy: [path($.jobs.transform)]
```

Every list is plain: each entry is a
[tree address](/docs/reference-language#checked-links-refert), which
is what `rel()` checks. Both directions are written out by hand,
because `inverse()` only checks that the mirror exists; it never
writes the mirror for you. Run the checks:

<!-- test: run -->
```sh
$ aontu relations pipeline.aon
verdict: pass
```

Generating the document (`aontu pipeline.aon`) is unaffected by any
of this, and the lists come out as the same plain strings the author
wrote: `rel()` checks addresses, it never rewrites them.

## A cycle is a located refusal

Suppose a change makes `load` feed `extract`, closing the DAG into a
loop. Write the change as `cycle.aon`, patching both directions in:

<!-- test: file cycle.aon -->
```aontu
@"./pipeline.aon"
jobs: { load:feeds: [path($.jobs.extract)] extract:fedBy: [path($.jobs.load)] }
```

Every field still unifies (nothing contradicts locally), but the
edge set now violates `acyclic()`, so *generation* refuses, with a
located error at an edge on the loop:

<!-- test: run -->
```sh
$ aontu cycle.aon
[aontu/relation_cycle]: Cannot relate value at path $.jobs.extract.feeds
...
$ echo $?
1
```

The verb reports the same verdict without generating, and names the
nodes the cycle runs through, closing back on the first:

<!-- test: run -->
```sh
$ aontu relations cycle.aon
verdict: fail

$.jobs.extract.feeds.0  feeds: cycle $.jobs.extract -> $.jobs.transform -> $.jobs.load -> $.jobs.extract
$ echo $?
1
```

Each verdict line is one finding: the position of the offending edge,
the relation, and the detail. Findings are sorted by position, so the
report diffs cleanly between runs.

## A missing inverse names the missing entry

Add a `metrics` job that taps the transform output, and forget to
record the feeder on its `fedBy`. Write it as `metrics.aon`:

<!-- test: file metrics.aon -->
```aontu
@"./pipeline.aon"

jobs: metrics: fedBy: []
jobs: transform: feeds: [path($.jobs.load) path($.jobs.metrics)]
```

<!-- test: run -->
```sh
$ aontu relations metrics.aon
verdict: fail

$.jobs.transform.feeds.1  feeds: $.jobs.metrics does not list $.jobs.transform under fedBy
$ echo $?
1
```

The finding says exactly which entry to write. Generation refuses the
same model with a located `[aontu/relation_inverse_missing]` at that
edge.

## What to watch for

Acyclicity and inverse consistency are deliberately *not* lattice
constraints: both are global and non-monotone (one more edge can
make an acyclic graph cyclic), so unification could never hold them
open at all. The endpoint *type* is different: `rel(t)` flows `t`
into each far end at the site, so an edge landing on a wrong-shaped
entity is an ordinary located evaluation error, and the verb answers
`verdict: error` (exit 4) for a document that does not stand up at
all. Exit codes are otherwise `0` pass and `1` fail, with
`--format json` for a machine-readable report.

The atoms are specified in [Declared
relations](/docs/reference-language#declared-relations), the verb
under [`aontu relations`](/docs/reference-api#aontu-relations), and
the live version, with its checks, is
[use-cases/12-relations](/use-cases/12-relations). Once the
edges hold, ask what they connect: [Query reachability between
entities](/how-to/query-reachability).

---

# Query reachability between entities

_Ask whether one entity reaches another over the declared edges with aontu reaches, and get the path as the answer._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/query-reachability.md · Page: https://aontu.dev/how-to/query-reachability

"If the extract job stops, what downstream goes stale?" is a question
about the graph's closure, and no amount of staring at one edge at a
time answers it. `aontu reaches` asks it directly: does anything
`from` links to, at any remove, end up at `to`?

It runs over the same declared edges as [`aontu
relations`](/how-to/check-relations). The model below is a trimmed version
of [use-cases/12-relations](/use-cases/12-relations): jobs feed
jobs, both directions written out. The vocabulary goes in `spec.aon`:

<!-- test: scenario reach -->
<!-- test: file spec.aon -->
```aontu
spec: hide({
  Job: {
    kind: job
    feeds?: rel($.spec.JobShape) & acyclic() & inverse(fedBy)
    fedBy?: rel($.spec.JobShape)
  }
  JobShape: kind: job
})
```

and a four-job topology in `pipeline.aon`, where `transform` fans out
to two consumers:

<!-- test: file pipeline.aon -->
```aontu
@"./spec.aon"

jobs: { &: $.spec.Job }
jobs: extract: feeds: [path($.jobs.transform)]
jobs: transform: {
  fedBy: [path($.jobs.extract)]
  feeds: [path($.jobs.load) path($.jobs.audit)]
}
jobs: load: fedBy: [path($.jobs.transform)]
jobs: audit: fedBy: [path($.jobs.transform)]
```

Now ask whether the extract job's output ends up in the warehouse:

<!-- test: run -->
```sh
$ aontu reaches $.jobs.extract $.jobs.load --relation feeds pipeline.aon
verdict: reaches

$.jobs.extract -> $.jobs.transform -> $.jobs.load
$ echo $?
0
```

The path is the answer, not decoration: an operator asking what a
failure takes out acts on the chain, and a bare "yes" gives them
nothing to act on. It is a shortest path, and among shortest paths
the first in code-point order, so both engines print the same one.

## Direction matters

Along `feeds`, the DAG answers directionally: downstream yes,
upstream no:

<!-- test: run -->
```sh
$ aontu reaches $.jobs.load $.jobs.extract --relation feeds pipeline.aon
verdict: unreachable

$.jobs.load does not reach $.jobs.extract
$ echo $?
1
```

An unreachable pair is a failed check, and carries no path: there is
no evidence for a negative answer. Exit `1` (rather than `4`) says
the question was answered, and the answer was no, which is exactly
what a containment policy wants to assert in CI ("nothing in the
public tier may reach the ledger").

## With and without `--relation`

Omit `--relation` and every declared edge counts, `fedBy` included.
`load` and `audit` are siblings, so no chain of `feeds` connects
them, but the unrestricted graph does:

<!-- test: run -->
```sh
$ aontu reaches $.jobs.load $.jobs.audit pipeline.aon
verdict: reaches

$.jobs.load -> $.jobs.transform -> $.jobs.audit
$ aontu reaches $.jobs.load $.jobs.audit --relation feeds pipeline.aon
verdict: unreachable

$.jobs.load does not reach $.jobs.audit
$ echo $?
1
```

That is the difference between "are these connected at all" and "can
this reach that *this way*", and in a model that writes out its
inverses, the unrestricted graph connects nearly everything, so
`--relation` is what makes direction mean anything. The query is
transitive but never reflexive for free: `reaches $.jobs.extract
$.jobs.extract` is true only when a path of one or more edges returns
home, which reports a cycle rather than reporting nothing.

## An endpoint that names nothing refuses

An endpoint that names no node would make `unreachable` a lie about
the model, so the verb refuses instead, and lists what it does know:

<!-- test: run -->
```sh
$ aontu reaches $.jobs.extract $.jobs.laod pipeline.aon
verdict: error

$: refer_unresolved [reference]
  $.jobs.laod names no node in this document.
  note: nodes with links: $.jobs.audit, $.jobs.extract, $.jobs.load, $.jobs.transform
$ echo $?
4
```

A policy check that silently passed because its target was misspelled
is the failure mode this exit code exists to prevent. Treat exit `4`
as a broken check, and fix the spelling.

The verb is specified under [`aontu
reaches`](/docs/reference-api#aontu-reaches), including the library
forms (`reachCheck` / `Aontu.Reach`). The live version is
[use-cases/12-relations](/use-cases/12-relations), whose
`check.sh` asserts the directional answers above. To validate the
edge set itself before querying it, start with [Check that components
agree about their relations](/how-to/check-relations).

---

# Pin what a document means

_Pin a document's meaning to one string with aontu hash, and detect when the meaning moves._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/pin-a-document-hash.md · Page: https://aontu.dev/how-to/pin-a-document-hash

A file hash moves when a comment moves. `aontu hash` prints one
string that identifies a document's *meaning*, so a lockfile, a
registry entry or an agent can say "this definition, this version"
and check the claim later. Write a small model as `system.aon`:

<!-- test: scenario hash -->
<!-- test: file system.aon -->
```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

<!-- test: run -->
```sh
$ aontu hash system.aon
aon1-kmZi3pPU2hnWQfwLnaFoC5iUtlrt6vbUzU7og-KxWJE
```

The `aon1-` prefix is a scheme id; the rest is a digest of the
document's canonical meaning after evaluation. Reorder the keys, add
comments and split entries apart, as `system-reordered.aon` does:

<!-- test: file system-reordered.aon -->
```aontu
# same meaning: keys reordered, comments added, one entry split
services: billing: tier: premium
services: auth: replicas: 3
services: { &: { replicas: *1|integer tier: *standard|string } }
```

<!-- test: run -->
```sh
$ aontu hash system-reordered.aon
aon1-kmZi3pPU2hnWQfwLnaFoC5iUtlrt6vbUzU7og-KxWJE
```

Same pin. The document is evaluated standalone before hashing, so
even splitting it across files leaves the pin alone. Move the
template into its own `defaults.aon`:

<!-- test: file defaults.aon -->
```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
```

and load it from a two-line `system-split.aon`:

<!-- test: file system-split.aon -->
<!-- fmt: keep the split spelling the hash survives -->
```aontu
@"./defaults.aon"
services: auth: replicas: 3
services: billing: tier: premium
```

<!-- test: run -->
```sh
$ aontu hash system-split.aon
aon1-kmZi3pPU2hnWQfwLnaFoC5iUtlrt6vbUzU7og-KxWJE
```

The include is part of the evaluation, which also means the pin is
transitive: an edit two includes deep moves it.

## When the pin moves

Change what the document *means* and the string changes. Flip the
`replicas` default from 1 to 2, as `system-changed.aon` does:

<!-- test: file system-changed.aon -->
```aontu
services: { &: { replicas: *2|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

<!-- test: run -->
```sh
$ aontu hash system-changed.aon
aon1-2kHqTOm6-XLy1j322NI3Wje3AEAgdN5K6OEZdLpor84
```

A stored pin is therefore a one-string staleness check: re-run the
verb, compare, and only re-read the document when the strings differ.
When one has moved and you want to see *what* moved, `--form` prints
the exact text the digest is taken over, which is the thing to diff:

<!-- test: run -->
```sh
$ aontu hash --form system.aon
{"services":{&:{"replicas":*1|integer,"tier":*"standard"|string},"auth":{"replicas":3,"tier":*"standard"|string},"billing":{"replicas":*1|integer,"tier":"premium"}}}
```

The form carries marks the display canon omits (`close()`, `hide()`),
so two documents that render alike but close differently pin
differently. That is the point.

## A broken document has no pin

A document that does not evaluate has no meaning to identify, and a
hash of the wreck would agree with every other wreck. Give
`broken.aon` an outright contradiction:

<!-- test: file broken.aon -->
```aontu
port: 8080
port: 9090
```

<!-- test: run -->
```sh
$ aontu hash broken.aon
aontu: broken.aon does not evaluate on its own; nothing to hash
...
$ echo $?
4
```

Exit `4` with the engine's own refusal attached, so a pipeline that
pins on release fails on the release that broke.

The hash form and its guarantees are specified under [`aontu
hash`](/docs/reference-api#aontu-hash). A pin also holds still across
a recursive definition's unrollings ([Define a recursive
schema](/how-to/define-a-recursive-schema) shows one), and it pairs with
[the breaking gate](/how-to/gate-schema-changes): `hash` says whether the
meaning moved, `breaking` says whether the move breaks anyone.

---

# Format a document

_Put a document in the agreed form with `aontu fmt`, gate a repository on it in CI, read what the formatter will and will not change, and point `--lint` at the style it never touches._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/format-a-document.md · Page: https://aontu.dev/how-to/format-a-document

`aontu fmt` writes a document in one agreed form, in the tradition of
`gofmt`: two-space indentation, no commas between entries, braces only
where the language needs them, and a map that does not fit on one line
written as one statement per entry with its key repeated. What comes
back is the same document, with the same canon-hash, and formatting it
again changes nothing. The form itself is in the language reference,
[The formatted form](/docs/reference-language#the-formatted-form).

Write this as `catalog.aon`, in whatever shape it arrived:

<!-- test: scenario fmt -->
<!-- test: file catalog.aon -->
<!-- fmt: keep the input the transcript formats -->
```aontu
services: {
  web: { image: "registry.acme.internal/web:4.7.3", port: 8080 },
  auth: {
    image: "registry.acme.internal/auth:5.2.0",
    port: 8443
  }
}
```

## See the form

With a file and no option, the verb prints the formatted text and
touches nothing:

<!-- test: run -->
```sh
$ aontu fmt catalog.aon
services: web: { image:"registry.acme.internal/web:4.7.3" port:8080 }
services: auth: { image:"registry.acme.internal/auth:5.2.0" port:8443 }
```

The commas are gone, each service is one line with the colons tight
inside the braces, and `services:` is repeated rather than opened as a
block: a key written twice is a meet, so the two statements are the
one map the source wrote. `--diff` shows the change as a unified diff
instead, which is what to read before rewriting a file you did not
write.

## Rewrite the file

`--write` rewrites each file in place, and only when its form would
change; `--check` says whether it would, and is the gate:

<!-- test: run -->
```sh
$ aontu fmt --check catalog.aon
catalog.aon
$ echo $?
1
$ aontu fmt --write catalog.aon
$ aontu fmt --check catalog.aon
$ echo $?
0
```

`--check` prints the name of every file whose form would change and
exits 1 when there is one, so a pipeline step of `aontu fmt --check
*.aon` fails the build on a file that is not in the form, and names
it. `--list` prints the same names without the exit code. Several
files need one of `--write`, `--list`, `--check` or `--diff`: the verb
does not print two documents as one stream.

## Point at style

Two things the origin of the form suggests are not the formatter's to
do, because doing them changes the document: keys as lower-case words
or CamelCase rather than `snake_case`, and an alias for a value that
recurs. `--lint` reports them and touches nothing. Write `deploy.aon`:

<!-- test: file deploy.aon -->
```aontu
services: web: limits: { cpu:"500m" memory:"256Mi" restart:"always" }
services: auth: limits: { cpu:"500m" memory:"256Mi" restart:"always" }

max_replicas: 4
```

<!-- test: run -->
```sh
$ aontu fmt --strict deploy.aon
deploy.aon:1:16: style/repeat: this map is written 2 times (again at 2:17); an alias would name it once
deploy.aon:4:1: style/key-case: key max_replicas holds an underscore; maxReplicas would follow the form
$ echo $?
1
```

Each finding is one line on standard error, `file:line:col: rule:
message`. `style/repeat` points at the first of the sites and names
the others: the map after `limits:` is written twice, and a map that
is 40 columns or wider and written twice is one that can drift. An
alias names it once, and the document is the same document.
`style/key-case` says what the key would be under the form and no
more: `max_replicas` may be the name a generator or a column reads,
so whether to rename it is the author's call. With an alias, the two
`services:` statements are short enough to be one map in the form.
Write `services.aon` with both taken up:

<!-- test: file services.aon -->
```aontu
%Limits = { cpu:"500m" memory:"256Mi" restart:"always" }
services: { web:limits:%Limits auth:limits:%Limits }
maxReplicas: 4
```

<!-- test: run -->
```sh
$ aontu fmt --strict services.aon
$ echo $?
0
```

`--lint` alone prints the same lines and leaves the exit code alone;
`--strict` is the gate, and `aontu fmt --check --strict *.aon` is both
gates in one step.

## What the formatter refuses, and what it never does

A document that does not parse is not formatted: the verb prints the
syntax error as every other verb does and exits 4, and the file is left
as it was. A document with a conflict in it is formatted, because it
parses; the conflict is the evaluator's business.

The formatter never reorders a key, an element, an include or an alias
declaration; never renames a key; never changes a number, a string's
content or a parenthesis; never resolves an include, so it needs no
`--trust`; and never breaks a line. A line that is too wide stays as
wide as it is. Where it repeats a key or merges two statements it
checks the rewrite with the engine first, and keeps the spelling it
was given when the engine evaluates the two differently.

The verb's options and exit codes are in the
[API reference](/docs/reference-api#aontu-fmt).

---

# Split a model across files

_Load other source files with @"path" so a base model and its overrides unify into one document._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/split-a-model-across-files.md · Page: https://aontu.dev/how-to/split-a-model-across-files

One file holds a model well until two teams edit it, or until the
environment-specific lines outnumber the shared ones. `@"path"` loads
another source file and unifies it in place, so a split costs nothing:
the parts mean exactly what the whole meant. Write the shared shape
as `base.aon`:

<!-- test: scenario split-model -->
<!-- test: file base.aon -->
```aontu
server: { host:string port: *8080|integer debug: *false|boolean }
```

the production pins as `override.aon`:

<!-- test: file override.aon -->
```aontu
server: { host:"app.corp.example" port:8443 }
```

and an entry file `main.aon` that loads both:

<!-- test: file main.aon -->
```aontu
@"./base.aon"
@"./override.aon"
```

<!-- test: run -->
```sh
$ aontu main.aon
{
  "server": {
    "debug": false,
    "host": "app.corp.example",
    "port": 8443
  }
}
```

The override beats the `*8080` default, `debug` falls back to its
own, and `host: string` is satisfied rather than replaced.
Unification is order-independent, so swapping the two include lines
changes nothing: there is no cascade to reason about, only one merged
document.

An include is an ordinary value, so it can land under a key. Write
`car.aon`:

<!-- test: file car.aon -->
```aontu
color: silver
doors: 4
```

and mount it in `lot.aon`, constraints attached:

<!-- test: file lot.aon -->
```aontu
car: @"./car.aon"
car: { doors:number wheels:4 }
```

<!-- test: run -->
```sh
$ aontu lot.aon
{
  "car": {
    "color": "silver",
    "doors": 4,
    "wheels": 4
  }
}
```

The loaded file never learns it was mounted: its `doors: 4`
[meets](/docs/unification) the local `doors: number` the way any two
conjuncts meet, and a conflict between a loaded value and a local one is
a normal unification error (read one with [read a conflict
error](/how-to/read-a-conflict-error)).

Watch the paths. A relative include resolves against the including
file's own directory (the CLI starts the chain at the entry file's
directory), so a tree of split files moves as a unit. The embedding
APIs accept a base directory and an in-memory resolver for tests; see
[`AontuOptions`](/docs/reference-api#aontuoptions). And one shape of
path bypasses the filesystem entirely: a first segment carrying a dot
and no `./` prefix (`@"corp.example/schemas/service"`) is a module
import, resolved from the project's vendor tree under the lockfile's
pins. The path carries no version: compatibility is computed at
publish, so the major left the name. That story starts in
[vendor a dependency closure](/how-to/vendor-a-dependency-closure).

The full loading contract, extension defaulting included, is [source
loading](/docs/reference-language#source-loading-) in the language
reference. [Change a value with an
overlay](/how-to/change-a-value-with-an-overlay) uses this same split so
machine edits land in a file of their own, and
[use-cases/11-shared-modules](/use-cases/11-shared-modules) is
the live version of a model split all the way across repositories.

---

# Vendor a dependency closure for an offline build

_Lock a dependency closure with aontu sync and commit aontu_meta/vendor/ so a build resolves every import with no network at all._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/vendor-a-dependency-closure.md · Page: https://aontu.dev/how-to/vendor-a-dependency-closure

An `@"…"` import whose first segment carries a dot is a module import
rather than a file path, and modules resolve from local stores only:
evaluation never reaches the network. The stores are `aontu_meta/vendor/`
in your project and a user cache keyed by canon-hash. `aontu sync` is
the verb that fills both; a synced project evaluates with neither a
cache nor a network, which is what this guide is for.

Declare the dependency in the project's `pkg.aon`:

<!-- test: scenario vendor-closure -->
<!-- test: file pkg.aon -->
```aontu
pkg: { path:"corp.example/app" main:"main.aon" }
dep: "corp.example/schemas/service": v: "1.4.2"
```

and import it from the entry file, `main.aon`:

<!-- test: file main.aon -->
```aontu
svc: @"corp.example/schemas/service"
svc: name: "auth"
```

The package itself is an ordinary source tree with its own `pkg.aon`
and entry file. Here it already sits in the vendor tree, copied by hand
from the platform team's repository, which is its own guide:
[vendor a module by hand](/how-to/vendor-by-hand). Its
`aontu_meta/vendor/corp.example/schemas/service/pkg.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.4.2" main:"service.aon" }
```

and its entry,
`aontu_meta/vendor/corp.example/schemas/service/service.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/service.aon -->
```aontu
name: string
port: *8080|integer
```

`sync` resolves the closure, fetches nothing it already holds, writes
the lockfile and verifies every pin; evaluation then needs nothing
outside the project directory:

<!-- test: run -->
```sh
$ aontu sync
verdict: ok
corp.example/schemas/service 1.4.2 aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E

$ aontu main.aon
{
  "svc": {
    "name": "auth",
    "port": 8080
  }
}
```

The default filled and the schema held, all from the vendored tree.
The lockfile `sync` wrote is one canonical, diffable, JSON-parseable
line:

<!-- fmt: keep a lock file, shown as the tool writes it -->
```aon
# pkg-lock.aon (generated by `aontu sync`; do not edit)
{"lock":{"corp.example/schemas/service":{"archive":"sha256:f0e8…","canon":"aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E","v":"1.4.2"}}}
```

The `canon` pin is the module's meaning, recomputed and compared on
every later evaluation ([vendor by hand](/how-to/vendor-by-hand) shows what
that catches); `archive` is the digest of the tree's canonical archive,
which `aontu pkg verify` compares before it evaluates anything. A
package acquired from a repository carries a third pin, `manifest`, the
digest of what its publisher signed. Commit `aontu_meta/pkg-lock.aon`
and `aontu_meta/vendor/` together: that pair is the offline build, the
tree to bake into a container image, an air-gapped checkout, or an
agent sandbox.

## In CI, freeze

`sync` is idempotent, so running it in CI is safe; what CI must not do
is let it rewrite the lockfile without anyone noticing. `--frozen`
resolves and fetches what a locked version needs, and refuses when the
lockfile would change. Add a dependency to `pkg.aon` without syncing:

<!-- test: file pkg.aon -->
```aontu
pkg: { path:"corp.example/app" main:"main.aon" }

dep: "corp.example/schemas/service": v: "1.4.2"
dep: "corp.example/schemas/common": v: "1.0.0"
```

<!-- test: run -->
```sh
$ aontu sync --frozen
verdict: frozen
lockfile would change: corp.example/schemas/common: unlocked -> 1.0.0
$ echo $?
1
```

Nothing was fetched and nothing was written: the refusal came before
the first request. A pin that would move says `repinned`, and a
dependency that left the package file says `dropped`. Run `sync`
without the flag where the lockfile is meant to change, review its
diff like code, and let CI hold the result.

`aontu pkg verify` is the narrower gate: it checks every pin against
the stores and reaches for nothing, which is what to run beside the
tests when the project is already synced ([validate in CI](/how-to/validate-in-ci)
is the surrounding job). The verbs' full contract is
[`aontu sync`](/docs/reference-api#aontu-sync) and
[`aontu pkg`](/docs/reference-api#aontu-pkg); the module resolution
rules are in the [language reference](/docs/reference-language#modules).
Publishing the package a consumer syncs is
[publish a package](/how-to/publish-a-package), and the live version (cold
start through tamper, confinement, a local repository and the publish
gate) is [use-cases/11-shared-modules](/use-cases/11-shared-modules).

---

# Vendor a module by hand

_Bootstrap a module dependency with no repository to fetch from by copying its source tree into aontu_meta/vendor/ and letting aontu sync pin what it means._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/vendor-by-hand.md · Page: https://aontu.dev/how-to/vendor-by-hand

`aontu sync` fetches a package from a repository, and a package that
was never published to one cannot be fetched. The content-addressed
user cache cannot be searched until a lockfile pins a hash, either, so
the cold start for a package that lives only in a colleague's checkout
is hand-vendoring: put its source tree into `aontu_meta/vendor/`
yourself, then let `sync` pin it. `cp -r` is the distribution protocol.

Start on the consumer side. The project declares the dependency in
its `pkg.aon`:

<!-- test: scenario vendor-by-hand -->
<!-- test: file pkg.aon -->
```aontu
pkg: { path:"corp.example/app" main:"main.aon" }
dep: "corp.example/schemas/service": v: "1.0.0"
```

and the entry file `main.aon` imports it:

<!-- test: file main.aon -->
```aontu
svc: @"corp.example/schemas/service"
svc: name: "auth"
```

With nothing received yet, `aontu pkg tidy`, the resolve step that
fetches nothing, refuses and names the module:

<!-- test: run -->
```sh
$ aontu pkg tidy
verdict: missing
corp.example/schemas/service: not fetched (run: aontu sync)
$ echo $?
1
```

No lockfile is written; a partial lock would claim a closure that was
never resolved. So do the fetch's job by hand. The layout is
`aontu_meta/vendor/<package-path>/` under your project, beside its
`pkg.aon`: each `/`-segment of the package path becomes a directory,
and an uppercase letter is written `!` followed by its lowercase:

```
project/
  pkg.aon
  main.aon
  aontu_meta/
    vendor/
      corp.example/
        schemas/
          service/
            pkg.aon
            service.aon
```

The directory holds the package's own source tree. Its
`aontu_meta/vendor/corp.example/schemas/service/pkg.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.0.0" main:"service.aon" }
```

and its entry file,
`aontu_meta/vendor/corp.example/schemas/service/service.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/service.aon -->
```aontu
name: string
port: *8080|integer
```

Now `sync`, from the project root. It finds the hand-made tree at the
version the project asked for, evaluates the module standalone, locks
its canon-hash and the digest of its archive, and verifies both;
evaluation then resolves the import:

<!-- test: run -->
```sh
$ aontu sync
verdict: ok
corp.example/schemas/service 1.0.0 aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E

$ aontu main.aon
{
  "svc": {
    "name": "auth",
    "port": 8080
  }
}
```

The pin is what the hand-vendoring was for. Every later evaluation
re-derives the vendored module's canon-hash and compares it to the
locked one, so a change to the module's evaluated meaning is refused
rather than silently used. Flip the vendored default in
`aontu_meta/vendor/corp.example/schemas/service/service.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/service.aon -->
```aontu
name: string
port: *9090|integer
```

<!-- test: run -->
```sh
$ aontu main.aon
module integrity: corp.example/schemas/service expected aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E got aon1-Bd4OQlOyzyJcXZvYbVcV7NZbMJGGxQH6GtNctkC26VA
$ echo $?
1
```

Both hashes are named: the meaning that was reviewed and the meaning
the store now holds. Be precise about what that pin protects. It is a
semantic pin, taken over the canonical form of the module's entry
document and its include closure; comments, whitespace, refactored
spellings that canon to the same value, `pkg.aon` metadata, and files
the entry never includes all keep the hash, deliberately. The bytes are
the `archive` pin's job, and the tooling checks that one first.

<a id="in-ci-verifydo-not-tidy"></a>

## In CI, verify: do not tidy

`tidy` rewrites the lockfile from whatever the store currently holds,
so a job that tidies before evaluating makes the lock agree with a
tampered store and then passes. `aontu pkg verify` asks the question
without answering it by editing: against the still-tampered store, the
bytes are checked before the meaning, so it is the archive pin that
speaks:

<!-- test: run -->
```sh
$ aontu pkg verify
verdict: mismatch
corp.example/schemas/service: pinned archive sha256:db1c3797fbf11badbc4fb7c87c6a4c34fafe602735fb63dbdccc7de951f3d5e8 but the store holds sha256:d5e16bacd6172fd3f585fb8ec75d720c5653f277f301792bf0470edf19e2e6f2
$ echo $?
1
```

It recomputes every pin, compares against the committed lockfile,
writes nothing, and exits `1` on any disagreement. Run it beside your
tests ([validate in CI](/how-to/validate-in-ci) is the surrounding job), or
run `aontu sync --frozen`, which refuses the same way and fetches what
a locked version needs; run `sync` without the flag only when you
intend to move a pin, and review its diff like code. Nothing to check
is not a pass, either. Take a project that declares the dependency but
never committed a lockfile: only its `pkg.aon`:

<!-- test: scenario verify-unlocked -->
<!-- test: file pkg.aon -->
```aontu
pkg: { path:"corp.example/app" main:"main.aon" }
dep: "corp.example/schemas/service": v: "1.0.0"
```

<!-- test: run -->
```sh
$ aontu pkg verify
verdict: unlocked
corp.example/schemas/service: not in the lockfile (run: aontu sync)
$ echo $?
1
```

An uncovered project is refused rather than verified over an empty
set, and the line names the repair.

## A package with its own dependencies vendors flat

A vendored package carries its own `pkg.aon` and may declare its own
`dep`. Its imports resolve from its own directory and from every
enclosing project root, so its dependency goes in the same
`aontu_meta/vendor/` tree, beside it: never nested inside it:

```
project/
  pkg.aon
  aontu_meta/
    vendor/
      corp.example/
        schemas/
          service/         # imports common
            pkg.aon
            service.aon
          common/          # flat beside it, not nested inside it
            pkg.aon
            common.aon
```

Declaring only the top of the closure is enough, because `sync` walks
the rest. A consumer `pkg.aon`:

<!-- test: scenario vendor-transitive -->
<!-- test: file pkg.aon -->
```aontu
pkg: { path:"corp.example/app" main:"main.aon" }
dep: "corp.example/schemas/service": v: "1.0.0"
```

its entry `main.aon`:

<!-- test: file main.aon -->
```aontu
svc: @"corp.example/schemas/service"
svc: name: "auth"
```

a hand-vendored
`aontu_meta/vendor/corp.example/schemas/service/pkg.aon` that declares a
dependency of its own:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.0.0" main:"service.aon" }
dep: "corp.example/schemas/common": v: "1.0.0"
```

and its entry
`aontu_meta/vendor/corp.example/schemas/service/service.aon`, importing
it:

<!-- test: file aontu_meta/vendor/corp.example/schemas/service/service.aon -->
```aontu
@"corp.example/schemas/common"
name: string
port: *8080|integer
```

With `common` not yet vendored, `tidy` refuses the whole closure:

<!-- test: run -->
```sh
$ aontu pkg tidy
verdict: error
corp.example/schemas/service: does not evaluate on its own; nothing to pin
corp.example/schemas/common: not fetched (run: aontu sync)
$ echo $?
4
```

A module that does not evaluate on its own is refused rather than
pinned, because every module that fails to evaluate hashes to the
same string: a lockfile written from one would look like a pin and
mean nothing. (`aontu hash` refuses the same file with the same
wording.) Vendor the dependency flat beside its dependant:
`aontu_meta/vendor/corp.example/schemas/common/pkg.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/common/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/common" version:"1.0.0" main:"common.aon" }
```

with its entry, a shared naming vocabulary, as
`aontu_meta/vendor/corp.example/schemas/common/common.aon`:

<!-- test: file aontu_meta/vendor/corp.example/schemas/common/common.aon -->
```aontu
name: string & re("^[a-z][a-z0-9-]*$")
```

and the closure resolves, both packages pinned:

<!-- test: run -->
```sh
$ aontu sync
verdict: ok
corp.example/schemas/common 1.0.0 aon1-btDT9RfDGjP4uvd5osF3R3mRW5aIeDz49_JbJpVLDwU
corp.example/schemas/service 1.0.0 aon1-GublSGsGCwYBgyQBAZSk9imd7xfbeCYKY6qbud8okdc

$ aontu main.aon
{
  "svc": {
    "name": "auth",
    "port": 8080
  }
}
```

One caution to carry away: the first copy is trusted axiomatically.
There is no signed manifest to compare a hand-vendored tree against,
so review what you vendor as if it were your own code; every copy
after that is held to the first by the pins. A package that has been
published carries its publisher's proof instead: that is
[publish a package](/how-to/publish-a-package). The verbs' full contract is
[`aontu sync`](/docs/reference-api#aontu-sync) and
[`aontu pkg`](/docs/reference-api#aontu-pkg), and the live version of
all of this (tamper, refactor-stable hashes, trust confinement, the
publish gate) is
[use-cases/11-shared-modules](/use-cases/11-shared-modules).

---

# Publish a package

_Publish a package with aontu publish, gated on compatibility with the version before it, into a local repository that aontu pkg serve serves and aontu sync reads._

Source: https://github.com/aontu-lang/aontu/blob/main/docs/how-to/publish-a-package.md · Page: https://aontu.dev/how-to/publish-a-package

A package is a versioned, signed archive of a module. Publishing one
sends three objects to a repository: the manifest that describes the
archive file by file and pins what the module means, a proof that
signs the manifest, and the archive itself. A consumer's `sync` fetches
the three, checks the proof, the bytes and the meaning in that order,
and refuses at the first that does not hold. This guide publishes into
a directory, which is a repository a laptop can serve, and gates the
next version on the one before it.

The package declares its path, its version, its entry, and that it may
leave the machine. Its `service/pkg.aon`:

<!-- test: scenario publish -->
<!-- test: file service/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.4.2" main:"service.aon" }
publish: public
```

and its entry, `service/service.aon`:

<!-- test: file service/service.aon -->
```aontu
name: string
port: *8080|integer
```

A publish is signed. The key is an Ed25519 private key in PKCS#8 PEM,
and `aontu pkg keygen` mints one, once, printing the signer id that a
consumer will name:

<!-- test: run -->
```sh
$ aontu pkg keygen key.pem
...
```

The line is `signer: ed25519:…`, the public half of the key. Keep the
file where a CI job can read it and nobody else can; the id is not a
secret.

## A dry run, then the publish

Without `--yes`, `publish` runs every check and sends nothing. `--to`
names a directory to publish into instead of the write path:

<!-- test: run -->
```sh
$ aontu publish --key key.pem --to repo service
verdict: dry-run
corp.example/schemas/service 1.4.2 public
archive: sha256:8a26b9f1b78620c8d452e69e9681a31027df431c833896bc98545627e6df3016 (2 files, 339 bytes)
module: corp.example/schemas/service service.aon aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E
file: pkg.aon sha256:7cc6671240e0c5f327dad20a10361edb98c687430eeadc9fc3d9604e287a11f4 96
file: service.aon sha256:36851584bea3d7109995deae363852734aca001c9e494b8868d736c5c49e7275 33
...
dry run: nothing sent (add --yes)
```

Read it top to bottom: the package and version, the archive's digest
and what it holds, the module's canon-hash, then the manifest's digest,
the signer, and where it would go. Then send it:

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo service
verdict: sent
...
sent
```

The directory now holds the read-path layout: `pkg/<path>/@v/` with
the archive, manifest and proof, the version list and `@latest`, and
an advisory. It is a repository. Nothing in it was evaluated by the
repository, and nothing in it is trusted by a consumer for more than
availability: the consumer recomputes every pin.

## The gate

The version after this one must admit every document this one
admitted, and resolve every position this one resolved, to the same
value: a consumer whose build worked keeps the same build. `publish`
fetches the highest version the repository holds and compares. A
candidate `service-1.4.3/pkg.aon`:

<!-- test: file service-1.4.3/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.4.3" main:"service.aon" }
publish: public
```

whose `service-1.4.3/service.aon` adds an optional key:

<!-- test: file service-1.4.3/service.aon -->
```aontu
name: string
port: *8080|integer
owner?: string
```

is compatible, and the report names what it was gated against:

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo service-1.4.3
verdict: sent
...
against: corp.example/schemas/service 1.4.2
...
```

A candidate `service-1.5.0/pkg.aon`:

<!-- test: file service-1.5.0/pkg.aon -->
```aontu
pkg: { path:"corp.example/schemas/service" version:"1.5.0" main:"service.aon" }
publish: public
```

whose `service-1.5.0/service.aon` makes that key required:

<!-- test: file service-1.5.0/service.aon -->
```aontu
name: string
port: *8080|integer
owner: string
```

is refused, with the key it refuses on, and nothing is written:

<!-- test: run -->
```sh
$ aontu publish --yes --key key.pem --to repo service-1.5.0
verdict: breaking
...
$.owner: the general value requires this key; the specific value makes it optional, so instances without it are admitted
...
$ echo $?
1
```

Every 1.4.3 consumer without an `owner` would stop evaluating, so the
release is refused, and there is no major version to bump past the
gate: compatibility is decided, not asserted. A breaking change ships
as a new package path, and the last version of the old path declares
`moved: <new path>`, which refuses every import of the old name with
the destination.

## Serve it, and read from it

`aontu pkg serve` serves the directory over HTTP on a loopback address,
byte for byte, and runs until interrupted:

<!-- test: skip serve runs until interrupted, which a transcript cannot show -->
```sh
$ aontu pkg serve repo
serving /home/me/repo at http://127.0.0.1:8017
```

A consumer names the base and the signer it accepts in its own
`pkg.aon`, and syncs. A base is `https`, or `http` on a loopback host,
which is what makes the laptop's registry reachable:

<!-- test: skip the consumer reads from the served registry above -->
```aontu
pkg: { path:"corp.example/checkout" main:"main.aon" }
dep: "corp.example/schemas/service": v: "1.4.2"

repo: base: ["http://127.0.0.1:8017"]
repo: trust: "corp.example/*": { signer:"ed25519:…" inclusion:none }
```

<!-- test: skip the consumer reads from the served registry above -->
```sh
$ aontu sync
verdict: ok
fetched: corp.example/schemas/service 1.4.2
corp.example/schemas/service 1.4.2 aon1-oQs6Ng6XxP2FHQGTYescREGDrDPfLLW1Liq4OS8Gs2E
```

`aontu get corp.example/schemas/service@1.4.3` raises the dependency
and syncs; `aontu pkg outdated` asks what could move. A version is
selectable by name at once, and by `get` without a version only after
the repository has held it for three days, so a compromised publisher's
newest release does not reach every consumer the hour it lands.

Publishing to the public repository is the same command without
`--to`: `aontu publish --yes --key key.pem --token token` from a CI
job, where the token is the forge's OIDC token and the write path
decides admission from it. The verb's full contract is
[`aontu publish`](/docs/reference-api#aontu-publish); the consumer
side is [vendor a dependency closure](/how-to/vendor-a-dependency-closure).

The public repository is not serving yet. Its default bases have no
address, so until they do a project names its `repo.base`, and a
publisher writes with `--to <dir>` and serves with `aontu pkg serve`.

---