aontu 0.65.0 → 0.66.0

package/grammar/aontu.gbnf

@@ -1,9 +1,9 @@
 # Aontu — published grammar (GBNF), for constrained decoding.
 #
-# G7 phase 6, docs/capability-review/g7-machine-access.md. This
-# grammar covers the DOCUMENTED EMISSION SURFACE: what a model should
-# be allowed to write, which is a superset of JSON plus the operators,
-# constraints and marks the language's own canonical form emits.
+# This grammar covers the DOCUMENTED EMISSION SURFACE: what a model
+# should be allowed to write, which is a superset of JSON plus the
+# operators, constraints and marks the language's own canonical form
+# emits.
 #
 # It is CONSERVATIVE BY CONSTRUCTION: it may accept less than the
 # parser does, never more. Two deliberate exclusions:
@@ -21,19 +21,9 @@
 
 root ::= ws value ws
 
-# No pipe. `|>` was parse-time sugar (G8 phase 4); ADR-018 removed it,
-# `x |> f(a)` being written `f(x, a)`.
-#
-# That ADR says "the operator from both grammars", and both kept it
-# anyway — the engine, the suite, the error code and the docs were
-# done, these two files were not. Nothing caught it, and nothing here
-# could have: the parity discipline above runs one way, requiring every
-# canon output to PARSE, so a rule canon never emits is unreachable and
-# a test that only reads this file cannot tell a dead rule from a live
-# one. What it cost was the direction that matters to this file's
-# consumer — a decoder constrained by the old text could emit `|>` and
-# have the engine refuse it with `aontu/unexpected`. Fixed before the
-# next release, so no published grammar ever disagreed with its engine.
+# No pipe. `|>` is not in the language; `x |> f(a)` is written
+# `f(x, a)`. A decoder constrained by this file cannot emit a spelling
+# the engine refuses with `aontu/unexpected`.
 value ::= disjunct
 
 disjunct ::= conjunct ( ws "|" ws conjunct )*
@@ -108,7 +98,7 @@ ref ::= "$" ( "." segment )+ | ( "." segment )+
 # `a:6-2` as a parse error), so admitting it over-approximated.
 segment ::= ( [a-zA-Z0-9_] )+
 
-# The placeholder: a hole a call is filled through (G8 phase 3). BARE
+# The placeholder: a hole a call is filled through. BARE
 # only -- `"_"` is an ordinary string, and a longer bare word
 # containing it is ordinary text.
 place ::= "_"

package/grammar/aontu.lark

@@ -1,9 +1,8 @@
 // Aontu — published grammar (lark), for constrained decoding.
 //
-// G7 phase 6, docs/capability-review/g7-machine-access.md. The same
-// rules as grammar/aontu.gbnf, for the other consumer: keep the two in
-// step, and note that ts/test/grammar.test.ts checks that every rule
-// named there is named here.
+// The same rules as grammar/aontu.gbnf, for the other consumer: keep
+// the two in step, and note that ts/test/grammar.test.ts checks that
+// every rule named there is named here.
 //
 // The gbnf file is the one the parity test INTERPRETS against the
 // shared suite's canonical output; this file is its transcription, so
@@ -15,16 +14,9 @@
 
 root: value
 
-// No pipe. `|>` was parse-time sugar (G8 phase 4); ADR-018 removed it,
-// `x |> f(a)` being written `f(x, a)`.
-//
-// That ADR says "the operator from both grammars", and both kept it
-// anyway — the engine, the suite, the error code and the docs were
-// done, these two files were not. Nothing caught it: a rule nothing
-// derives never matches, so every canon still parsed and every test
-// stayed green while the grammars offered a spelling the parser
-// refuses with `aontu/unexpected`. Fixed before the next release, so
-// no published grammar ever disagreed with its engine.
+// No pipe. `|>` is not in the language; `x |> f(a)` is written
+// `f(x, a)`. The engine refuses the old spelling with
+// `aontu/unexpected`, and all three published grammars agree with it.
 value: disjunct
 
 disjunct: conjunct ("|" conjunct)*

package/grammar/aontu.tmLanguage.json

@@ -14,16 +14,14 @@
     "rejects AS THOUGH it were valid, which is why the builtin list below is",
     "the engine's own set and not a hand-picked sample of it.",
     "",
-    "THE BUILTIN LIST IS A COPY, AND A COPY DRIFTS. aontu.lark carried",
-    "`same` — never a builtin — and was missing `acyclic`, `inverse` and",
-    "`rel` for two releases, with every test green. So the same guard the",
+    "THE BUILTIN LIST IS A COPY, AND A COPY DRIFTS, so the same guard the",
     "other two grammars have covers this file: ts/test/grammar.test.ts,",
     "`the-textmate-grammar-names-exactly-the-engine-builtins`, asserts this",
     "list against BUILTIN_FUNCS in BOTH directions. Add a builtin to the",
     "engine without adding it here and that test fails.",
     "",
-    "No `|>`: ADR-018 removed the pipe from the language, and all three",
-    "published grammars now agree about that."
+    "No `|>`: the pipe is not in the language, and all three published",
+    "grammars agree about that."
   ],
   "name": "aontu",
   "displayName": "Aontu",
@@ -130,7 +128,7 @@
           "match": "\\b(true|false|null)\\b"
         },
         {
-          "comment": "`_` is a literal of the language as of G8 phase 3, not text.",
+          "comment": "`_` is a literal of the language, not text.",
           "name": "constant.language.placeholder.aontu",
           "match": "(?<![A-Za-z0-9_])_(?![A-Za-z0-9_])"
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aontu",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "main": "dist/aontu.js",
   "type": "commonjs",
   "types": "dist/aontu.d.ts",
@@ -78,7 +78,8 @@
     "@tabnas/parser": "0.9.7",
     "@tabnas/path": "0.3.2",
     "@tabnas/toml": "0.5.7",
-    "@tabnas/yaml": "0.5.7"
+    "@tabnas/yaml": "0.5.7",
+    "jostraca": "0.38.0"
   },
   "devDependencies": {
     "@tabnas/railroad": "0.3.6",

package/skill/tasks.md

@@ -82,16 +82,21 @@ aontu trim --check model.aon     # entries whose removal changes nothing
 ## Generate code from a model, and hold it
 
 ```
-aontu model get out gen.aon      # the component tree: files, and the lines in them
-aontu trace gen.aon        # what rule wrote each line
+aontu render gen.aon build          # write the files below build/
+aontu render --check gen.aon build  # write nothing; exit 1 when build/ has drifted
+aontu render gen/ build             # every generator directly in gen/, as one run
+aontu model get out gen.aon         # the component tree: files, and the lines in them
+aontu trace gen.aon                 # what rule wrote each line
 ```
 
 A generator answers a **component tree** -- `file(name, [lines])` and
-its neighbours -- which a generator runtime writes to disk. Hand the
-tree to one and compare with what is committed: the model is the truth,
-the code is the claim, and drift is a finding. `aontu trace` answers
-the other direction: for a line of the output, the model node and the
-rule behind it.
+its neighbours -- which `aontu render` hands to jostraca, the generator
+runtime, to write. A tree that is one file is written to the path
+itself, and a folder of generators is one run. `--check` compares with
+what is committed: the model is the
+truth, the code is the claim, and drift is a finding. `aontu trace`
+answers the other direction: for a line of the output, the model node
+and the rule behind it.
 
 ## Ask what a model says, and why
 

package/src/aontu.ts

@@ -35,7 +35,7 @@ import { format, unifiedDiff } from './format'
 export type { LintFinding, FormatReport, FormatOptions } from './format'
 
 
-const VERSION = '0.65.0'
+const VERSION = '0.66.0'
 
 
 function genQuiet(val: any, aontu: Aontu): any {

package/src/cli.ts

@@ -5,8 +5,10 @@
 import { evalFailure } from './query'
 // __importStar downlevel helper, whose branches no supported Node takes.
 import {
-  existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync,
+  existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync,
+  writeFileSync,
 } from 'node:fs'
+import type { Dirent } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { createInterface } from 'node:readline'
@@ -97,6 +99,9 @@ const HELP = `Usage: aontu [options] [file]
                       [--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]
@@ -411,6 +416,31 @@ every other line is a line of output.
 
 Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
 
+Render options:
+  --check         Compare what the generator writes with what <path>
+                  holds, write nothing, and exit 1 on drift
+  --at <path>     Where the component tree lives in the document
+                  (default $.out)
+  --format json   Print the files written, or the drift, as JSON
+  --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 render verb writes the component tree a generator answers. The
+tree is handed to jostraca, the generator runtime, which writes the
+files: a tree that is one file is written to <path> itself, unless
+<path> is a directory, and any other tree is written below <path>.
+With --check nothing is written and <path> is compared with what the
+generator writes, one "kind: file" line per difference.
+A folder as the generator is a set: every regular file directly in
+it, dotfiles aside, in name order, and their trees are written below
+<path> as one run, so a path two of them claim is refused. A file with
+no marker line in it is refused by name.
+
+Render exit codes: 0 written or clean, 1 --check drift, 2 usage or
+I/O, 4 the document does not stand up, or --at names nothing.
+
 Model set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -2880,6 +2910,211 @@ function runTrace(argv: string[]): number {
 }
 
 
+// ---------------------------------------------------------------------
+// The writer (ADR-040). A generator answers a component tree; this verb
+// hands it to jostraca, which writes the files below a path or holds
+// them to it.
+
+const RENDER_HELP =
+  'aontu render [--check] [--at <path>] [--format json] ' +
+  '[--marker <token>] [--profile <file>] <file|folder> <path> (try --help)'
+
+
+// Loaded at the call, so every other verb starts without it.
+function generatorRuntime(): any {
+  return require('jostraca')
+}
+
+
+function isDirectory(path: string): boolean {
+  return true === statSync(path, { throwIfNoEntry: false })?.isDirectory()
+}
+
+
+async function runRender(argv: string[]): Promise<number> {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const rest: string[] = []
+  const profileFiles: string[] = []
+  let format: SubsumeFormat = 'text'
+  let at: string | undefined = undefined
+  let marker: string | undefined = undefined
+  let check = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--check' === arg) {
+      check = true
+    }
+    else if ('--format' === arg) {
+      const f = argv[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return 2
+      }
+      format = f
+    }
+    else if ('--at' === arg) {
+      at = argv[++i]
+      if (null == at || '' === at) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker || '' === marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if ('--profile' === arg) {
+      const pf = argv[++i]
+      if (null == pf || '' === pf) {
+        process.stderr.write('aontu: --profile needs a file\n')
+        return 2
+      }
+      profileFiles.push(pf)
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown render option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      rest.push(arg)
+    }
+  }
+
+  if (2 !== rest.length) {
+    process.stderr.write(`aontu: render needs a file and a path\n${RENDER_HELP}\n`)
+    return 2
+  }
+  const [file, dest] = rest
+
+  const declared = loadProfiles(profileFiles, trust)
+  if ('number' === typeof declared) {
+    return declared
+  }
+
+  // A FOLDER IS A SET OF GENERATORS: every regular file directly in it,
+  // dotfiles aside, in code-point order, written as one tree.
+  let entries: Dirent[] | undefined
+  try {
+    entries = readdirSync(file, { withFileTypes: true })
+  }
+  catch (err: any) {
+    entries = undefined
+  }
+  const set = undefined !== entries
+  const files = undefined === entries ? [file] :
+    entries.filter((e) => e.isFile() && !e.name.startsWith('.'))
+      .map((e) => e.name).sort(cmpCodePoint).map((n) => join(file, n))
+  if (0 === files.length) {
+    process.stderr.write(`aontu: ${file} holds no generator\n`)
+    return 2
+  }
+
+  const trees: any[] = []
+  for (const f of files) {
+    let src: string
+    try {
+      src = readFileSync(f, 'utf8')
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+    if (!/[.](aon|aontu)$/.test(f)) {
+      const mark = marker ?? markerFromProfiles(declared, f) ?? markerFor(f)
+      if (!templateOutputs(src, mark).some((out) => !out)) {
+        process.stderr.write(`aontu: ${f} carries no ${mark} marker line, ` +
+          'so there is no aontu in it to render\n')
+        return 2
+      }
+      src = desugarTemplate(src, mark)
+    }
+    const report = get(src, at ?? '$.out', {
+      view: 'json', path: f, ...verbOpts(trust, entryRootOf(f)),
+    })
+    if (!report.ok) {
+      process.stderr.write(report.findings.map(renderFinding).join('\n') + '\n')
+      return 4
+    }
+    const tree = JSON.parse(report.out)
+    // A `File` without a name is refused: the runtime ports disagree
+    // about it.
+    if ('File' === tree?.cmp && 'string' !== typeof tree.props?.name) {
+      process.stderr.write(`aontu: ${f}: the file at ${at ?? '$.out'} has no name\n`)
+      return 4
+    }
+    trees.push(tree)
+  }
+
+  // ONE FILE GOES TO THE PATH ITSELF, unless the path is a directory; a
+  // set is written below the path whatever its trees are.
+  let folder = dest
+  const tree: any = set ? trees.flatMap((t) => Array.isArray(t) ? t : [t]) : trees[0]
+  if (!set && 'File' === tree?.cmp && !isDirectory(dest)) {
+    tree.props.name = basename(dest)
+    folder = dirname(dest)
+  }
+
+  const { cmpTree, Jostraca } = generatorRuntime()
+  let root: any
+  try {
+    root = cmpTree(tree, { raw: true })
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: ${file}: ${err.message}\n`)
+    return 4
+  }
+  const runtime = Jostraca()
+
+  try {
+    if (check) {
+      const res = await runtime.check({ folder }, root)
+      const drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      if ('json' === format) {
+        process.stdout.write(exactJSON({
+          aontu: { version: version(), verb: 'render' },
+          verdict: 0 === drift.length ? 'ok' : 'drift',
+          checked: res.checked,
+          drift,
+        }, 2) + '\n')
+      }
+      else {
+        for (const d of drift) {
+          process.stdout.write(`${d.kind}: ${d.path}\n`)
+        }
+      }
+      return 0 === drift.length ? 0 : 1
+    }
+
+    const res = await runtime.generate({ folder }, root)
+    if ('json' === format) {
+      process.stdout.write(exactJSON({
+        aontu: { version: version(), verb: 'render' },
+        verdict: 'ok',
+        files: res.files,
+      }, 2) + '\n')
+    }
+    return 0
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: ${err.message}\n`)
+    return 2
+  }
+}
+
+
 function runReaches(argv: string[]): number {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -4880,8 +5115,8 @@ function runInit(argv: string[]): number {
 const KNOWN_VERBS = [
   'add', 'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
   'help', 'init', 'jsonschema', 'lsp', 'mcp', 'model', 'pkg', 'publish',
-  'reaches', 'relations', 'remove', 'subsume', 'sync', 'template', 'trace',
-  'trim', 'vet', 'view', 'why',
+  'reaches', 'relations', 'remove', 'render', 'subsume', 'sync', 'template',
+  'trace', 'trim', 'vet', 'view', 'why',
 ]
 
 
@@ -5029,6 +5264,10 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runTrace(argv.slice(3)))
   }
 
+  if ('render' === argv[2]) {
+    return void runRender(argv.slice(3)).then(finish)
+  }
+
   if ('reaches' === argv[2]) {
     return finish(runReaches(argv.slice(3)))
   }
@@ -5146,6 +5385,7 @@ export {
   runJsonSchema,
   runTemplate,
   runTrace,
+  runRender,
   runPkg, runModel, runPackageVerb, pkgToolOptions, serveUntilInterrupted,
   runHash, runGet, runHelp, runExplain, runInit, nearestVerb,
   looksLikeVerb,

package/src/helpdoc.ts

@@ -17,7 +17,7 @@ const HELPDOC: HelpTopic[] = [
     "topic": "tasks",
     "summary": "what do you want to do? — the verb for a job",
     "source": "docs/skill/tasks.md",
-    "text": "# What do you want to do?\n\nThe verb for a job, found by the word you arrived with. aontu's own\nvocabulary is on the right; yours is probably on the left.\n\n## Start from a document that works\n\nNothing written yet? Do not invent the first document, edit one:\n\n```\naontu init            # into the working directory\naontu init model/     # or into a named one\nsh check.sh           # the four questions, on what was just written\n```\n\n`init` writes `model.aon` (an entity map constrained with `&:`),\n`data.aon` (an instance of it that holds) and `check.sh` (the four\nchecks to run after every edit). It never overwrites: if any\nof the three already stands there, it refuses and writes none of them.\n\n## Describe a domain\n\nAn **ontology**, a **schema**, a **data model**, a **contract** — in\naontu these are all one thing: a document. Write the entities as a\n**map keyed by name**, and say what every entry must satisfy with the\n`&:` template:\n\n```\nentity: {\n  &: {\n    table:  string\n    fields: { &: { type: string, required: *false | boolean } }\n  }\n  planet: { table: \"planets\", fields: { name: { type: \"string\" } } }\n  moon:   { table: \"moons\",   fields: { name: { type: \"string\" } } }\n}\n```\n\n`&:` is the construct to reach for first, and the one most easily\nmissed. It meets **every** key of the map it sits in. A quoted `\"*\"`\nis not a wildcard — it is a key named `*`, and a schema written that\nway constrains nothing while still reporting `valid`.\n\nPrefer a named map to a list unless the order is a fact (a migration\nsequence, a rule table tried in order). A key is an address, a name\nother parts can refer to, and a diff that shows one insertion instead\nof every following element renumbered.\n\n## Check data against a model\n\n```\naontu vet model.aon data.aon\n```\n\nExit `0` valid, `1` a contradiction, `3` incomplete (nothing\ncontradicts, but the model is not yet satisfied), `4` the model does\nnot stand up on its own. `--format json` for the machine-readable\nreport, `--closed` to refuse keys the model does not declare,\n`--max-errors <n>` to cap the list.\n\n**Make the check prove it checked something.** A check that examined\nnothing answers exactly like one that passed:\n\n```\naontu vet --coverage model.aon data.aon         # what did it examine?\naontu vet --strict-coverage model.aon data.aon  # exit 1 if nothing\n```\n\n`--coverage` reports how many data leaves a declaration constrained,\nthe data paths none did, and the declarations no data met.\n`--strict-coverage` exits 1 when the answer is nothing. The usual\ncause is the `\"*\"` mistake above: reach for `&:`.\n\n## Check the model is coherent with itself\n\n```\naontu relations model.aon        # declared entity edges: targets resolve, no cycles\naontu reaches planet moon model.aon   # does one entity reach another, at any remove?\naontu trim --check model.aon     # entries whose removal changes nothing\n```\n\n## Generate code from a model, and hold it\n\n```\naontu model get out gen.aon      # the component tree: files, and the lines in them\naontu trace gen.aon        # what rule wrote each line\n```\n\nA generator answers a **component tree** -- `file(name, [lines])` and\nits neighbours -- which a generator runtime writes to disk. Hand the\ntree to one and compare with what is committed: the model is the truth,\nthe code is the claim, and drift is a finding. `aontu trace` answers\nthe other direction: for a line of the output, the model node and the\nrule behind it.\n\n## Ask what a model says, and why\n\n```\naontu model get  $.entity.planet.table model.aon\naontu model why  $.entity.planet.table model.aon\naontu model get  $.entity --keys       model.aon\naontu model get  $.entity --types      model.aon\n```\n\n`why` names **every** contribution to a value, with the file and line\neach was written on. It is the first thing to run when a value is not\nwhat you expected, and the second thing to run when `vet` refuses.\n\n## Change a value without editing the file\n\n```\naontu model set '$.entity.planet.table=planet_v2' --entry model.aon --overlay local.aon\n```\n\nThe change is checked before it is written; a change that contradicts\na pinned value is refused, and the file is left alone.\n\n## Gate a change to the model itself\n\n```\naontu subsume old.aon new.aon              # does the general admit every specific?\naontu breaking --against git#HEAD~1 model.aon\naontu hash model.aon                       # a pin that survives reformatting\n```\n\n## Hand a model to another agent\n\n```\naontu agentsmd --write AGENTS.md model.aon\n```\n\nSplices a derived stanza — the pin, the root keys, the shape, and the\ncommands spelled with paths that exist — between two markers, and\nleaves the rest of the file alone. Re-run it in the commit that\nchanges the model.\n\n## When something refuses\n\nRead the code in the brackets, then look it up:\n\n```\naontu explain no_scalar_unify\n```\n\nEvery finding carries a `code`, a `class`, a `path` and the **two\nsites** that disagree — the value and the constraint it failed, each\nwith its file and line. The class says what kind of answer it is:\n`conflict` (two things cannot both hold), `incomplete` (nothing is\nwrong yet, something is missing), `parse`, `reference`, `budget`.\n\nFull index: [`error-codes.md`](error-codes.md). The language on one\npage: [`grammar-card.md`](grammar-card.md). The worked ladder from\nplain JSON upward: [`examples.md`](examples.md).\n"
+    "text": "# What do you want to do?\n\nThe verb for a job, found by the word you arrived with. aontu's own\nvocabulary is on the right; yours is probably on the left.\n\n## Start from a document that works\n\nNothing written yet? Do not invent the first document, edit one:\n\n```\naontu init            # into the working directory\naontu init model/     # or into a named one\nsh check.sh           # the four questions, on what was just written\n```\n\n`init` writes `model.aon` (an entity map constrained with `&:`),\n`data.aon` (an instance of it that holds) and `check.sh` (the four\nchecks to run after every edit). It never overwrites: if any\nof the three already stands there, it refuses and writes none of them.\n\n## Describe a domain\n\nAn **ontology**, a **schema**, a **data model**, a **contract** — in\naontu these are all one thing: a document. Write the entities as a\n**map keyed by name**, and say what every entry must satisfy with the\n`&:` template:\n\n```\nentity: {\n  &: {\n    table:  string\n    fields: { &: { type: string, required: *false | boolean } }\n  }\n  planet: { table: \"planets\", fields: { name: { type: \"string\" } } }\n  moon:   { table: \"moons\",   fields: { name: { type: \"string\" } } }\n}\n```\n\n`&:` is the construct to reach for first, and the one most easily\nmissed. It meets **every** key of the map it sits in. A quoted `\"*\"`\nis not a wildcard — it is a key named `*`, and a schema written that\nway constrains nothing while still reporting `valid`.\n\nPrefer a named map to a list unless the order is a fact (a migration\nsequence, a rule table tried in order). A key is an address, a name\nother parts can refer to, and a diff that shows one insertion instead\nof every following element renumbered.\n\n## Check data against a model\n\n```\naontu vet model.aon data.aon\n```\n\nExit `0` valid, `1` a contradiction, `3` incomplete (nothing\ncontradicts, but the model is not yet satisfied), `4` the model does\nnot stand up on its own. `--format json` for the machine-readable\nreport, `--closed` to refuse keys the model does not declare,\n`--max-errors <n>` to cap the list.\n\n**Make the check prove it checked something.** A check that examined\nnothing answers exactly like one that passed:\n\n```\naontu vet --coverage model.aon data.aon         # what did it examine?\naontu vet --strict-coverage model.aon data.aon  # exit 1 if nothing\n```\n\n`--coverage` reports how many data leaves a declaration constrained,\nthe data paths none did, and the declarations no data met.\n`--strict-coverage` exits 1 when the answer is nothing. The usual\ncause is the `\"*\"` mistake above: reach for `&:`.\n\n## Check the model is coherent with itself\n\n```\naontu relations model.aon        # declared entity edges: targets resolve, no cycles\naontu reaches planet moon model.aon   # does one entity reach another, at any remove?\naontu trim --check model.aon     # entries whose removal changes nothing\n```\n\n## Generate code from a model, and hold it\n\n```\naontu render gen.aon build          # write the files below build/\naontu render --check gen.aon build  # write nothing; exit 1 when build/ has drifted\naontu render gen/ build             # every generator directly in gen/, as one run\naontu model get out gen.aon         # the component tree: files, and the lines in them\naontu trace gen.aon                 # what rule wrote each line\n```\n\nA generator answers a **component tree** -- `file(name, [lines])` and\nits neighbours -- which `aontu render` hands to jostraca, the generator\nruntime, to write. A tree that is one file is written to the path\nitself, and a folder of generators is one run. `--check` compares with\nwhat is committed: the model is the\ntruth, the code is the claim, and drift is a finding. `aontu trace`\nanswers the other direction: for a line of the output, the model node\nand the rule behind it.\n\n## Ask what a model says, and why\n\n```\naontu model get  $.entity.planet.table model.aon\naontu model why  $.entity.planet.table model.aon\naontu model get  $.entity --keys       model.aon\naontu model get  $.entity --types      model.aon\n```\n\n`why` names **every** contribution to a value, with the file and line\neach was written on. It is the first thing to run when a value is not\nwhat you expected, and the second thing to run when `vet` refuses.\n\n## Change a value without editing the file\n\n```\naontu model set '$.entity.planet.table=planet_v2' --entry model.aon --overlay local.aon\n```\n\nThe change is checked before it is written; a change that contradicts\na pinned value is refused, and the file is left alone.\n\n## Gate a change to the model itself\n\n```\naontu subsume old.aon new.aon              # does the general admit every specific?\naontu breaking --against git#HEAD~1 model.aon\naontu hash model.aon                       # a pin that survives reformatting\n```\n\n## Hand a model to another agent\n\n```\naontu agentsmd --write AGENTS.md model.aon\n```\n\nSplices a derived stanza — the pin, the root keys, the shape, and the\ncommands spelled with paths that exist — between two markers, and\nleaves the rest of the file alone. Re-run it in the commit that\nchanges the model.\n\n## When something refuses\n\nRead the code in the brackets, then look it up:\n\n```\naontu explain no_scalar_unify\n```\n\nEvery finding carries a `code`, a `class`, a `path` and the **two\nsites** that disagree — the value and the constraint it failed, each\nwith its file and line. The class says what kind of answer it is:\n`conflict` (two things cannot both hold), `incomplete` (nothing is\nwrong yet, something is missing), `parse`, `reference`, `budget`.\n\nFull index: [`error-codes.md`](error-codes.md). The language on one\npage: [`grammar-card.md`](grammar-card.md). The worked ladder from\nplain JSON upward: [`examples.md`](examples.md).\n"
   },
   {
     "topic": "language",