aontu 0.61.0 → 0.63.0

package/src/graph.ts

@@ -1,22 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE DERIVED STRUCTURE (G4 phase 3,
-// docs/capability-review/g4-identity-relations.md): an evaluated
-// document has, besides its value, a GRAPH — the set of checked links,
-// each from one tree position to another.
-//
-// The graph is PATH-NATIVE (ADR-014). There is no second namespace to
-// index: a node's address is its path, so the entity index the first
-// design carried is exactly the set of paths already in the edges, and
-// the node a link starts at is derived from where the link sits rather
-// than declared by a mark.
-//
-// G4's deliverable is that this exists and is DETERMINISTIC. What is
-// built on it — impact analysis ("what reaches $.services.auth?"),
-// reachability, context-window-sized slices — is a traversal, and its
-// exposure as verbs and projections belongs to G7. Relation properties
-// (acyclicity, inverse consistency) are G4 phase 5's, and consume
-// exactly this edge set.
 
 import type { Val } from './type'
 
@@ -24,35 +7,17 @@ import { cmpCodePoint } from './keyorder'
 
 
 export type Edge = {
-  // The node the link starts at, as a `$.dotted.path`: the link's own
-  // position with the relation key and any list indices stripped. `$`
-  // when the link sits at the top of the document.
   from: string
-  // The RELATION: the key the link hangs under, so a link inside a
-  // list (`dependsOn: [refer() & "$.a"]`) is an edge under `dependsOn`
-  // rather than under `0`. A rel()-minted link carries its predicate
-  // declared rather than inferred.
   key: string
-  // The address, as the link spells it.
   to: string
   // Where the link is, as a `$.dotted.path`, so a report can point at
   // it.
   at: string
-  // Set when the link sits inside a `hide()`-marked subtree. The link
-  // is still checked and still an edge, but a figure that draws it
-  // DISCLOSES what the document hides, so the view extractors skip it
-  // and report it as `hidden_contribution`.
   hidden?: true
 }
 
 export type Graph = {
   edges: Edge[]
-  // The positions of links written under an UNRESOLVED DISJUNCTION.
-  // ADR-007: an unresolved disjunction is not a value, so a link
-  // beneath one of its arms is not a fact and is not an edge -- but it
-  // is not nothing either, and a figure that silently dropped it would
-  // be the failure the views exist to avoid. Absent when there are
-  // none, so a graph of a decided document is the shape it always was.
   disjunct?: string[]
 }
 
@@ -66,14 +31,6 @@ const formatPath = (path: string[]): string =>
 const isIndex = (seg: string): boolean => /^[0-9]+$/.test(seg)
 
 
-// The node a link starts at and the relation it hangs under, derived
-// from the link's own position.
-//
-// A DECLARED predicate (rel()-minted) is authoritative: the link is cut
-// at the key the rel() sat on, wherever that is on the way down, which
-// is what makes a MAP-valued relation report the relation rather than
-// the inner label. Without one the relation is INFERRED: strip the list
-// indices, and the first real key above the link is it.
 const cut = (
   at: string[], relkey: string | undefined
 ): { from: string, key: string } => {
@@ -92,11 +49,6 @@ const cut = (
 }
 
 
-// The graph of an evaluated tree. Walks POSITIONS, not values: a
-// reference or a spread can put one value object at several positions,
-// and a walk guarded by object identity would find the first and miss
-// every other place it is reached. The guard is therefore the ancestor
-// chain — which is what a cycle actually is.
 export function graphOf(root: Val): Graph {
   const edges: Edge[] = []
   const disjunct: string[] = []
@@ -136,11 +88,6 @@ export function graphOf(root: Val): Graph {
       visit(node.held, path, ancestors, hidden, undecided)
     }
 
-    // An unresolved conjunction (a link waiting on a peer that never
-    // came, a constraint still open) holds its terms at the SAME
-    // position; every link among them is written there, and is an
-    // edge. This is what a match-selected branch or a deferred refer()
-    // looks like after evaluation.
     if (true === node.isConjunct && Array.isArray(node.peg)) {
       ancestors.add(node)
       for (const term of node.peg) {
@@ -149,10 +96,6 @@ export function graphOf(root: Val): Graph {
       ancestors.delete(node)
     }
 
-    // AN UNRESOLVED DISJUNCTION IS NOT A VALUE (ADR-007), so a link
-    // under one of its arms is not an edge. Its POSITION is collected
-    // instead, so a figure can report what the document leaves
-    // undecided rather than drawing it or dropping it in silence.
     if (true === node.isDisjunct && Array.isArray(node.peg)) {
       ancestors.add(node)
       for (const arm of node.peg) {
@@ -172,10 +115,6 @@ export function graphOf(root: Val): Graph {
 
   visit(root, [], new Set(), false, false)
 
-  // DETERMINISTIC by construction, not by luck: edges by the position
-  // they are written at, which is unique — one link, one place. That
-  // holds through a conjunction too: its terms share the position, and
-  // two links there would have had to unify into one.
   edges.sort((a, b) => cmpCodePoint(a.at, b.at))
 
   if (0 < disjunct.length) {

package/src/hcanon.ts

@@ -1,44 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// The HASH FORM (G6 phase 0, docs/capability-review/g6-distribution.md):
-// exactly the unify-level canon with the additions that close its
-// semantic gaps, so that two documents with the same hash form have the
-// same meaning:
-//
-//   - a CLOSED map or list renders wrapped: close({...}), close([...])
-//     (canon drops closedness);
-//   - the type/hide MARKS render as their builtin wrappers: type(x),
-//     hide(x) (canon drops marks).
-//
-// Both additions reuse existing parseable syntax, so the hash form
-// remains valid Aontu source and round-trips:
-// hcanon(unify(parse(hcanon(v)))) == hcanon(v) is a spec-suite property
-// (test/spec/hcanon.tsv). User-facing canon is UNCHANGED — hcanon is a
-// separate rendering.
-//
-// An ALIAS REFERENCE left standing in a spread template renders its
-// EXPANSION through this same walk rather than through the reference's
-// own canon, so a close() or a mark on the aliased value survives into
-// the hash. Without that the wrappers above are absent exactly where
-// the alias filter has already erased the declaration that carried
-// them (BUGS.md §60).
-//
-// The marks PROPAGATE to every descendant at unification (walkMark), so
-// a wrapper is emitted only where a mark STARTS: the walk carries the
-// inherited marks down and a child whose mark the parent already
-// carries renders bare. Without that, hide({a:1}) would render every
-// leaf re-wrapped — still correct, never minimal, and not what the
-// source said.
-//
-// canonHash (G6 phase 1) is the pin built on it:
-//   "aon1-" + base64url( SHA-256( UTF-8( hcanon(v) ) ) )
-// (unpadded base64url, RFC 4648 section 5). The "aon1-" scheme id
-// exists so a future semantically-stronger normal form is an upgrade,
-// not a breakage. This is a CANONICAL-TEXT hash, not a semantic
-// equivalence class: the failure direction is the safe one — a false
-// "changed" forces a needless re-review; a false "unchanged" would need
-// two hash forms with the same bytes and different meanings, which is
-// exactly the gap the close/mark wrappers exist to shut.
 
 import { createHash } from 'node:crypto'
 
@@ -53,15 +14,6 @@ type HMarks = {
 }
 
 
-// One node's rendering, carrying the marks the ANCESTORS already
-// wrapped. Bags and junctions recurse structurally (their canon getters
-// render children through plain canon, which would drop a nested
-// close), and so does an expanded alias reference, for the reason its
-// own arm gives. Everything else — scalars, kinds, funcs, constraints,
-// and a reference with nothing to expand — delegates to its own canon,
-// whose text is already in cross-port parity. The non-Val arm mirrors
-// MapVal.canon's raw-peg fallback and is unreachable through an
-// evaluated tree (direct-tested, ADR-002).
 function render(v: any, inh: HMarks): string {
   if (true !== v?.isVal) {
     return String(v)
@@ -76,12 +28,6 @@ function render(v: any, inh: HMarks): string {
 
   let s: string
   if (true === v.isMap) {
-    // Alias declarations are dropped here for the same reason
-    // MapVal.canon drops them, and this is the surface where it counts:
-    // `aon1-` pins MEANING, so a document written with aliases and the
-    // same document written longhand must hash to one string. Two
-    // renderers, one rule -- hcanon is not canon and does not inherit
-    // the filter (docs/design/ALIASES.0.md §4).
     const keys = Object.keys(v.peg)
       .filter((k) => !v.aliasKeys.includes(k))
       .sort(cmpCodePoint)
@@ -115,22 +61,6 @@ function render(v: any, inh: HMarks): string {
   else if (true === v.isConjunct || true === v.isDisjunct) {
     s = junctionText(v, true === v.isConjunct ? '&' : '|', inner)
   }
-  // AN EXPANDED ALIAS REFERENCE IS RENDERED, NOT DELEGATED (BUGS.md
-  // §60). A reference standing after unification is one inside a
-  // spread template, and `RefVal.canon` answers with the EXPANSION's
-  // plain canon -- which drops exactly what this renderer exists to
-  // keep. The declaration carrying `close()` or a mark is erased by
-  // the alias filter above, so a `close()` lost here is lost from the
-  // hash entirely: `%A = close({n:string})` and `%A = {n:string}`,
-  // used as `box: [&: %A]`, hashed to ONE STRING while refusing and
-  // admitting `{n:"x",z:1}` respectively -- a change of meaning the
-  // pin reported as no change, in the unsafe direction. Recursing
-  // through `inner` is what makes the alias form and its longhand
-  // twin agree again, which is ALIASES.0.md §4's own requirement.
-  //
-  // A reference with NO expansion still spells its name: a plain
-  // `$.A` names a key the hash form still carries in full, and the
-  // knot of a recursive alias inside its own template never gets one.
   else if (true === v.isRef && undefined !== v.expansion) {
     s = render(v.expansion, inner)
   }
@@ -160,14 +90,6 @@ function render(v: any, inh: HMarks): string {
 }
 
 
-// The JunctionVal.canon parenthesisation rule, kept: a member that is
-// itself a junction with more than one term keeps its parens so the
-// text reparses with the same structure (`(1|2)&3`, not the
-// differently-parsing `1|2&3`). Post-unification junctions are
-// flattened by norm, so no SOURCE reaches the wrapping arm -- it is
-// pinned by direct tests over constructed Vals in both ports, because
-// a hash form that could render ambiguously would be a pin that
-// silently agrees with a document it should not.
 function junctionText(v: any, sym: string, inner: HMarks): string {
   return v.peg.map((m: any) =>
     true === m?.isJunction && 1 < m.peg.length
@@ -185,10 +107,6 @@ export function hcanon(v: Val): string {
 }
 
 
-// The canon-hash pin. Scoped to the module evaluated STANDALONE: its
-// own include closure resolved and unified at its own root, before any
-// consumer context — which is what makes the pin transitive (an edit
-// two includes deep changes the unified root, hence the hash).
 export function canonHash(v: Val): string {
   return 'aon1-' +
     createHash('sha256').update(hcanon(v), 'utf8').digest('base64url')

package/src/helpdoc.ts

@@ -0,0 +1,77 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// GENERATED by ts/scripts/helpdoc.cjs (`make helpdoc`) from
+// docs/skill/*.md and grammar/aontu.abnf — DO NOT EDIT. The skill
+// sources are the source; ts/test/helpdoc.test.ts asserts this copy
+// is identical with them.
+
+type HelpTopic = {
+  topic: string
+  summary: string
+  source: string
+  text: string
+}
+
+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## Check code against a model\n\n```\naontu render --check src/ --profile go.aon model.aon\n```\n\n`render` writes code from the model; `--check` writes nothing and\nlists what on disk differs from what the model implies. That is the\ngate: the model is the truth, the code is the claim, and drift is a\nfinding. `--coverage` reports the other direction — model paths no\noutput consumed, and rendered declarations no rule produced.\n\n## Ask what a model says, and why\n\n```\naontu get  $.entity.planet.table model.aon\naontu why  $.entity.planet.table model.aon\naontu get  $.entity --keys       model.aon\naontu 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 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",
+    "summary": "the grammar card — everything the language spells, on one page",
+    "source": "docs/skill/grammar-card.md",
+    "text": "# aontu grammar card\n\nEverything the language spells, on one page. The published machine\ngrammars are [`grammar/aontu.abnf`](../../grammar/aontu.abnf) — the\nnotation a person reads, with railroad diagrams — and\n[`aontu.gbnf`](../../grammar/aontu.gbnf), `aontu.lark` and\n`aontu.tmLanguage.json` for constrained decoding, parsing and\nhighlighting; this is their human twin.\n\n## Values\n\n| Write | Means |\n|-------|-------|\n| `{\"a\":1}`, `a: 1` | a map; keys may be bare or quoted |\n| `[1,2]` | a list |\n| `\"s\"`, `1`, `1.5`, `true`, `null` | scalars, as JSON |\n| `0d9007199254740993` | an EXACT number, at any magnitude |\n| `string integer number float boolean null` | kinds: any value of that kind |\n| `top` | anything at all; `nil` is the failure |\n\n## Combining\n\n| Write | Means |\n|-------|-------|\n| `a & b` | both must hold — the meet |\n| `a \\| b` | either may hold — the join |\n| `*1 \\| integer` | either, with `1` the DEFAULT a generation picks |\n| | the branch keeps its kind: a later `1.5` is refused, not admitted |\n| `x: 1` twice | the two meet; `1 & 2` is an error, `1 & integer` is `1` |\n| `$.a.b` | the value at that path of this document |\n| `1 + 2` | arithmetic on concrete numbers |\n\n## Maps that say more\n\n| Write | Means |\n|-------|-------|\n| `{&: {k: integer}}` | a TEMPLATE every key must satisfy |\n| `close({a:1})` | no key beyond those named |\n| `{a?: 1}` | optional: dropped if unresolved |\n| `hide(x)` | evaluated, then dropped from the output |\n| `type(x)` | a definition, not a value: it generates nothing |\n| `deprecate(x, {msg:\"…\"})` | still works, and says so |\n| `refer(t) & path($.a.b)` | a checked LINK: the tree address must resolve, and `t` flows into it |\n\n## Constraints\n\n`min(n) max(n) above(n) below(n)` bound a number;\n`length(n)` and `unique()` bound a list or string;\n`re(\"^…$\")` matches a string; `neq(v)` refuses one value;\n`must(cond, \"why\")` is the escape hatch.\n\nBounds compose: `integer & min(1) & max(10)` is a range, and two\nranges meet to their overlap.\n\n## Files\n\n`@\"other.aon\"` includes another document — it unifies in, it does not\nconcatenate. (A constrained decoder is not given this: generated\ndocuments describe values, they do not load files.)\n"
+  },
+  {
+    "topic": "examples",
+    "summary": "the ladder — plain JSON, then one addition at a time",
+    "source": "docs/skill/examples.md",
+    "text": "# aontu by example\n\nThe ladder: start with the JSON you already know, add one thing at a\ntime. Every rung is a valid document.\n\n## 1. It is JSON\n\n```\n{\"service\": {\"name\": \"auth\", \"port\": 8080}}\n```\n\nBare keys and no commas also parse, so this is the same document:\n\n```\nservice: {\n  name: \"auth\"\n  port: 8080\n}\n```\n\n## 2. Say what a value MAY be\n\n```\nservice: {\n  name: string\n  port: integer\n}\n```\n\nNothing generates yet — this is a truth, not a value. `aontu vet\nservice.aon deploy.aon` says whether a deployment satisfies it.\n\n## 3. Say what it SHOULD be\n\n```\nservice: {\n  name: string\n  port: *8080 | integer      # 8080 unless told otherwise\n  replicas: *1 | integer\n}\n```\n\nNow it generates: `{\"service\":{\"name\":…,\"port\":8080,\"replicas\":1}}` —\nexcept `name`, which nothing has supplied. Defaults are picked at\ngeneration; they do not stop a caller from choosing something else.\n\n`*8080 | integer` means what it reads as: a caller's `9090` overrides\nit, and a caller's `1.5` is refused, because the branch admits only the\nkind it names. Write `*8080 | number` if any numeric value should be\nallowed to win.\n\n## 4. Say it once, for every key\n\n```\nservices: {\n  &: { port: integer, replicas: *1 | integer }\n  auth: { port: 8080 }\n  db:   { port: 5432, replicas: 3 }\n}\n```\n\nThe `&:` template meets EVERY key. `aontu why $.services.db.replicas`\nreports both contributions — the template's `*1|integer` and the\nliteral `3` — with the line each was written on.\n\n## 5. Bound it\n\n```\nservices: {\n  &: {\n    port: integer & min(1) & max(65535)\n    name: string & re(\"^[a-z][a-z0-9-]*$\")\n  }\n}\n```\n\nA port of `0` is now an error with a path, not a runtime surprise.\n\n## 6. Layer it\n\n```\n# base.aon\nservice: { image: string, replicas: *1 | integer }\n\n# prod.aon\n@\"base.aon\"\nservice: { image: \"auth:v2.3\", replicas: 5 }\n```\n\nUnification is order-independent: `base & prod` is `prod & base`. To\nchange a value without editing the file, append to an overlay:\n\n```\naontu set '$.service.replicas=7' --entry prod.aon --overlay local.aon\n```\n\nIf the value is PINNED rather than open, that command refuses and\nnames the pinning site — which is the honest answer, and where\n`aontu why` takes you next.\n"
+  },
+  {
+    "topic": "codes",
+    "summary": "what a refusal means, and what to do about it",
+    "source": "docs/skill/error-codes.md",
+    "text": "# What a refusal means\n\nEvery aontu error carries a **code**, and every code has a **class**.\nThe class says what kind of thing went wrong, which is what decides\nyour next move. The full registry — every code, its class, and the\nversion it appeared in — is\n[`test/spec/errcodes.tsv`](../../test/spec/errcodes.tsv), which the\ntest suite holds to the engine in both implementations.\n\n| Class | Meaning | What to do |\n|-------|---------|------------|\n| `parse` | the text is not a document | fix the syntax at the site the frame points at |\n| `conflict` | two values cannot both hold | one of them is wrong: `aontu why <path>` names both and where they were written |\n| `incomplete` | nothing contradicts, but the value is not concrete | supply what is missing, or accept it with `--partial` |\n| `reference` | a path names nothing | check the spelling; `aontu get $ --keys` lists what is there |\n| `compat` | a change breaks an earlier version | that is `aontu subsume` / `aontu breaking` talking: widen the change or version it |\n| `budget` | evaluation hit a deterministic limit | usually a cycle; simplify, or raise the budget deliberately |\n| `internal` | the engine surprised itself | a bug worth reporting |\n\n## The repair loop\n\n```\naontu vet schema.aon mine.aon --format json\n```\n\nThe exit code branches for you: `0` valid, `1` invalid (fix the\ndata), `3` incomplete (supply more), `4` the schema itself is\nunusable (fix the truth, not the data). Every finding carries\n`path`, `code`, and the sites on both sides — the data site first,\nbecause that is the one to edit. A site names **the file whose text\nit excerpts**, so its row and column are safe to edit at even when\nthe document loads others.\n\nRead `hint` before guessing. `message` is the one-line headline;\n`hint` is the engine's own explanation of the failure class with the\noffending values filled in, and for several codes it names the fix\noutright — `lossy_integer_literal` tells you to write the literal as\n`0d…`. It is absent for codes that have no hint text.\n\nFor a conflict, `aontu why <path> mine.aon` lists every contribution\nto that path with its role and source line, which turns \"these\ndisagree\" into \"these two lines disagree\".\n\nThen fix it:\n\n```\naontu set '$.replicas=5' --entry schema.aon --overlay mine.aon --in-place\n```\n\n`--in-place` rewrites the pinned literal **where it was written**, so\ncomments and layout survive. Without it, `set` APPENDS — which is the\nright thing when the document left a hole, and cannot work when it\npinned the wrong value, because unification only narrows.\n\nThe edit is verified before a byte is written: a site carries the\nsource text it covers, and the text at the span must match it. Where\nthat cannot be established — the value comes from a `&:` template or a\n`$ref`, two statements pin the path, the site names the opening token\nof a compound like `min(1)`, or the overlay `@\"includes\"` another\ndocument — the assignment is appended as usual and a **warning** says\nwhich case it hit. A warning never changes the verdict, so asking for\n`--in-place` cannot make a run fail that would have succeeded.\n"
+  },
+  {
+    "topic": "grammar",
+    "summary": "the published ABNF, for a parser or a constrained decoder",
+    "source": "grammar/aontu.abnf",
+    "text": "; Aontu --- published grammar (ABNF, RFC 5234 + RFC 7405).\n;\n; The same language as grammar/aontu.gbnf, rule for rule and name for\n; name, in the notation an RFC reader expects. The GBNF form is for a\n; constrained decoder; THIS form is for a person, and for the railroad\n; diagram in the language reference, which is generated from this file\n; (ts/scripts/figures.cjs).\n;\n; It covers the DOCUMENTED EMISSION SURFACE: what a model should be\n; allowed to write, which is a superset of JSON plus the operators,\n; constraints and marks the language's own canonical form emits. It is\n; CONSERVATIVE BY CONSTRUCTION --- it may accept less than the parser\n; does, never more. The same two deliberate exclusions the GBNF has:\n;\n;   - `@\"...\"` includes. A generated document should describe values,\n;     not reach for files.\n;   - Unquoted keys and the other spellings the parser tolerates.\n;     Canon quotes every key, and one spelling is what a grammar is\n;     for.\n;\n; TWO NOTATION CHOICES worth stating, because both are load-bearing.\n;\n; EVERY LITERAL IS CASE-SENSITIVE, spelled `%s\"...\"` (RFC 7405). A\n; plain `\"...\"` is case-INSENSITIVE in RFC 5234, and Aontu is not:\n; `TRUE` is a bare word and `true` is a boolean. The reader in\n; ts/scripts/abnf.cjs refuses a bare quoted string rather than guess\n; which was meant.\n;\n; ALTERNATION IS ORDERED. RFC 5234's `/` is formally unordered, and\n; the consumers of this file (a PEG-style matcher here, a railroad\n; renderer) take the first branch that matches. Where one spelling is\n; a prefix of another the longer comes first --- `exact` before\n; `number`, `refer` before `rem` before `re`, `biginteger` before\n; `boolean` --- so the ordered reading and the unordered one accept\n; the same language. ts/test/grammar.test.ts holds this file to the\n; whole canon corpus of test/spec/*.tsv, which is what proves it.\n\nroot      = ws value ws\n\n; No pipe. `|>` was parse-time sugar; it was removed, `x |> f(a)`\n; being written `f(x, a)`.\nvalue     = disjunct\n\ndisjunct  = conjunct *( ws %s\"|\" ws conjunct )\n\nconjunct  = prefixed *( ws %s\"&\" ws prefixed )\n\n; A preference marks the alternative a generation picks.\nprefixed  = %s\"*\" ws prefixed / sum\n\nsum       = atom *( ws %s\"+\" ws atom )\n\natom      = map\n          / list\n          / func\n          / ref\n          / kind\n          / place\n          / scalar\n          / %s\"(\" ws value ws %s\")\"\n\nmap       = %s\"{\" ws [ entry *( ws %s\",\" ws entry ) ws ] %s\"}\"\n\nentry     = spread / pair\n\n; The template every key of the bag must also satisfy.\nspread    = %s\"&\" ws %s\":\" ws value\n\npair      = string ws [ %s\"?\" ] ws %s\":\" ws value\n\n; A list ELEMENT is a value, not a pair --- only the template is keyed.\nlist      = %s\"[\" ws [ element *( ws %s\",\" ws element ) ws ] %s\"]\"\n\nelement   = spread / value\n\n; The builtins, applied. The name set is closed on purpose: an unknown\n; function is a parse-time error in the engine, so a grammar that\n; allowed any name would over-approximate.\nfunc      = name %s\"(\" ws [ value *( ws %s\",\" ws value ) ws ] %s\")\"\n\n; ORDER MATTERS where one name is a prefix of another: `refer` is\n; listed before `re`, and `rem` before `re` as well.\nname      = %s\"abnf\" / %s\"above\" / %s\"acyclic\" / %s\"add\" / %s\"below\" / %s\"close\"\n          / %s\"copyfiles\" / %s\"copy\" / %s\"deprecate\" / %s\"div\"\n          / %s\"each\" / %s\"emit\" / %s\"esc\" / %s\"filter\" / %s\"greatest\"\n          / %s\"hide\"\n          / %s\"inverse\" / %s\"join\" / %s\"key\" / %s\"least\"\n          / %s\"length\" / %s\"listitems\" / %s\"list\" / %s\"lower\" / %s\"map\" / %s\"match\"\n          / %s\"maybe\" / %s\"max\" / %s\"min\" / %s\"mod\" / %s\"move\"\n          / %s\"mul\" / %s\"must\"\n          / %s\"neq\"\n          / %s\"open\" / %s\"pack\" / %s\"parse\" / %s\"path\" / %s\"pick\" / %s\"pref\"\n          / %s\"refer\" / %s\"rel\" / %s\"rem\" / %s\"rep\" / %s\"re\" / %s\"sort\" / %s\"split\"\n          / %s\"super\"\n          / %s\"content\" / %s\"file\" / %s\"folder\" / %s\"fragment\" / %s\"inject\"\n          / %s\"line\" / %s\"nom\" / %s\"project\" / %s\"slot\" / %s\"translate\"\n          / %s\"sub\" / %s\"sum\"\n          / %s\"type\"\n          / %s\"unique\" / %s\"upper\" / %s\"usc\"\n\n; A path reference, absolute from the document root. At least one\n; segment: a bare `$` is an incomplete expression, not a reference.\n; A RELATIVE reference has no `$`: `.n` names a sibling, resolved\n; against the enclosing map rather than the document root. Canon emits\n; one wherever a spread template survives unresolved, so a grammar\n; without it cannot parse this engine's own output. No conflict with\n; `number`: a numeric literal always starts with a digit or `-`.\nref       = %s\"$\" 1*( %s\".\" segment ) / 1*( %s\".\" segment )\n\n; No `-`: it is not a bare-text character (test/spec/op-chars.tsv pins\n; `a:6-2` as a parse error), so admitting it would over-approximate.\nsegment   = 1*( ALPHA / DIGIT / %s\"_\" )\n\n; The placeholder: a hole a call is filled through. BARE only --- `\"_\"`\n; is an ordinary string, and a longer bare word containing it is\n; ordinary text.\nplace     = %s\"_\"\n\n; `biginteger` before `bigdecimal` is not required (they differ at the\n; fourth character), but `biginteger` before `boolean` is: see the\n; ordered-alternation note above.\nkind      = %s\"biginteger\" / %s\"bigdecimal\" / %s\"boolean\" / %s\"float\"\n          / %s\"integer\" / %s\"number\" / %s\"string\" / %s\"top\" / %s\"nil\"\n\n; `exact` before `number`, or `0d5` would match `number` as the single\n; digit `0` and leave `d5` unconsumed.\nscalar    = string / exact / number / %s\"true\" / %s\"false\" / %s\"null\"\n\nstring    = DQUOTE *char DQUOTE\n\nchar      = unescaped / %x5C escape\n\n; Every code point but the quote and the backslash, which is what the\n; GBNF's `[^\"\\\\]` says. Control characters included: canon writes them\n; escaped, and a grammar that refused them would refuse less than the\n; parser accepts in the one direction this file may not.\nunescaped = %x00-21 / %x23-5B / %x5D-10FFFF\n\nescape    = DQUOTE / %x5C / %s\"/\" / %s\"b\" / %s\"f\" / %s\"n\" / %s\"r\"\n          / %s\"t\" / %s\"u\" hex hex hex hex\n\nhex       = DIGIT / %x41-46 / %x61-66\n\n; The exact leaves: arbitrary precision, spelled with the 0d marker.\nexact     = [ %s\"-\" ] %s\"0d\" digits [ %s\".\" digits ] [ exponent ]\n\nnumber    = [ %s\"-\" ] digits [ %s\".\" digits ] [ exponent ]\n\nexponent  = ( %s\"e\" / %s\"E\" ) [ %s\"-\" / %s\"+\" ] digits\n\ndigits    = 1*DIGIT\n\nws        = *( %x20 / %x09 / %x0A / %x0D )\n\n; RFC 5234's core rules, written out so this file stands alone.\nALPHA     = %x41-5A / %x61-7A\nDIGIT     = %x30-39\nDQUOTE    = %x22\n"
+  }
+]
+
+type InitFile = {
+  file: string
+  mode: number
+  name: string
+  text: string
+}
+
+const INITDOC: InitFile[] = [
+  {
+    "file": "docs/skill/init/model.aon",
+    "name": "model.aon",
+    "mode": 420,
+    "text": "# model.aon --- the truth. `aontu vet model.aon data.aon` asks whether\n# a document satisfies it.\n#\n# `&:` is the construct to learn first: it meets EVERY key of the map\n# it sits in, so one statement constrains every entity. A quoted \"*\" is\n# not a wildcard -- it is a key named `*`, it meets nothing, and a\n# schema written that way reports `valid` over data that violates it.\n# `aontu vet --strict-coverage` refuses to pass such a check.\nentity: {\n  &: {\n    table: string & re(\"^[a-z][a-z0-9_]*$\")\n    fields: {\n      &: {\n        type: \"string\" | \"integer\" | \"boolean\"\n        required: *false | boolean\n      }\n    }\n  }\n}\n"
+  },
+  {
+    "file": "docs/skill/init/data.aon",
+    "name": "data.aon",
+    "mode": 420,
+    "text": "# data.aon --- an instance of the truth in model.aon. Edit it and run\n# check.sh: every change is checked against the model, and a change the\n# model refuses is named with the line it is on.\nentity: {\n  planet: {\n    table: \"planets\"\n    fields: {\n      name: { type: \"string\", required: true }\n      diameter: { type: \"integer\" }\n    }\n  }\n}\n"
+  },
+  {
+    "file": "docs/skill/init/check.sh",
+    "name": "check.sh",
+    "mode": 493,
+    "text": "#!/usr/bin/env sh\n# check.sh --- the four questions to ask of a model. Run it after\n# every edit to model.aon or data.aon.\n#\n# `aontu help tasks` maps a job to a verb; `aontu explain <code>` says\n# what a refusal means; `aontu help language` is the whole grammar on\n# one page. None of them needs a network.\nset -eu\n\nAONTU=\"${AONTU:-aontu}\"\ncd \"$(dirname \"$0\")\"\n\n# 1. Does the data satisfy the truth -- and did the check examine\n#    anything? --strict-coverage exits 1 on a check that constrained no\n#    value, which is the failure a passing gate hides.\n$AONTU vet --strict-coverage model.aon data.aon\n\n# 2. What does it say at a path?\n$AONTU get '$.entity.planet.table' data.aon\n\n# 3. Why does it say that? Every contribution, with the line it is on.\n$AONTU why '$.entity.planet.table' data.aon\n\n# 4. A pin for the truth: it survives reformatting and moves on any\n#    change of meaning.\n$AONTU hash model.aon\n\necho \"ok --- model.aon and data.aon agree\"\n"
+  }
+]
+
+export type { HelpTopic, InitFile }
+export { HELPDOC, INITDOC }

package/src/hints.ts

@@ -1,11 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/**
- * Error code hints for Aontu unification errors.
- *
- * Each key is an error code that can be passed to makeNilErr.
- * Each value is a human-readable explanation of what the error means.
- */
 
 const hints: Record<string, string> = {
 
@@ -40,7 +34,6 @@ const hints: Record<string, string> = {
     'when nothing else does.',
 
 
-  // TODO: extend errors to have details so we can name the key
   mapval_required: 'This map value is required.',
 
   mapval_no_gen:
@@ -108,6 +101,31 @@ const hints: Record<string, string> = {
     '                                                   #     with "tier";\n' +
     '  min(0) & must(integer,"whole") & 3    -> 3      # Bands compose.',
 
+  abnf_grammar:
+    'This ABNF grammar could not be compiled:\n' +
+    '{reason}\n' +
+    ' \n' +
+    'abnf() takes RFC 5234 ABNF -- `=` and `/`, not `::=`. The\n' +
+    'compiler reports the first thing it could not read; a rule\n' +
+    'referenced but never defined is the usual cause, after a\n' +
+    'quantifier written the EBNF way.',
+
+  parse_arg:
+    'parse(grammar, text) takes two strings: a grammar, normally the\n' +
+    'answer of an abnf() call, and the text to parse.\n' +
+    ' \n' +
+    'Examples:\n' +
+    '  G: abnf("v = 1*DIGIT")\n' +
+    '  a: parse($.G, "12")     # the AST\n' +
+    '  b: parse($.G, 12)       # parse_arg: the text is not a string',
+
+  parse_failed:
+    'The text does not parse under this grammar:\n' +
+    '{reason}\n' +
+    ' \n' +
+    'A failure to parse is a failure to unify, so the field is\n' +
+    'refused rather than set to a value meaning "no".',
+
   constraint_pattern:
     'This re() pattern is outside the supported subset. It uses\n' +
     '{reason}.\n' +
@@ -176,8 +194,6 @@ const hints: Record<string, string> = {
   bare_punct: 'A bare string holds letters, digits, `-` and `_`, and nothing else.\nThis one holds `{char}`, in `{text}`. Every other punctuation\ncharacter is either syntax or an error, never silently part of a\nstring: a value that needs one is written quoted, and a `>` or `<`\nthat was meant as a bound is written as min(x), max(x), above(x) or\nbelow(x).\n \nExamples:\n  a: team-payments  -> "team-payments"  # `-` and `_` are text;\n  a: 2026-09-05     -> "2026-09-05"     # ... digits included;\n  a: x=y            -> nil              # `=` is not;\n  a: "x=y"          -> "x=y"            # ... so quote it;\n  a: >10            -> nil              # Not an operator: write above(10).',
 
 
-
-
   recursion_unexpanded: 'A schema refers to itself here, and no data reached this position\nto expand it against. Guard the recursion -- an optional key\n(next?:) drops when nothing arrives, and a preferred alternative\n(*null | $.Node) generates -- or supply the data.\n \nExamples:\n  Node: {v: integer, next?: $.Node}\n  t: $.Node & {v: 1}            -> {..}  # next? drops;\n  Node: {v: integer, next: $.Node}\n  t: $.Node & {v: 1}            -> nil   # ... required refuses.',
   recursion_budget: 'A recursive schema expanded past the evaluation depth budget\nwithout meeting concrete data. Expansion is driven by the data --\nfinite data always terminates -- so a chain this deep means two\ndefinitions feeding each other, or data deeper than the budget\n(docs/trust.md raises it deliberately).',
   list_length: 'A literal list alternative in a disjunction admits only a list of\nits own length -- a spread (&:) makes it variadic. Outside a\ndisjunction two statements of one list still merge elementwise.\n \nExamples:\n  x: [] | [&: integer]\n  x: [1, 2]      -> [1,2]  # The variadic arm;\n  x: []          -> []     # ... or exactly empty;\n  y: [a] | [b]\n  y: [a, extra]  -> nil    # ... a literal arm is its length.',
@@ -203,6 +219,8 @@ const hints: Record<string, string> = {
   view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
 
   format_check: 'The formatted text is not the same document, so nothing was written.\nThis is a formatter defect: please report it, with the source.',
+
+  decimal_syntax: 'This 0d literal is not a valid exact number.',
   view_style_profile: 'Each profile has ONE way to carry the meaning of a figure\'s marks:\nSGR escapes for text, CSS classes for svg. Asking for the other one is\na usage error rather than a silent no-op. `none` works everywhere.',
   view_style_unknown: 'The styles are none, ansi and css, plus `auto` at the command line,\nwhich the command resolves before the library runs: whether the\ndestination is a terminal is not something a library can see.',
 
@@ -225,7 +243,7 @@ const hints: Record<string, string> = {
 
   pack_key: 'A list packed by pack() holds something that is not a string. The\nelements of a packed list ARE the generated keys, and only a string\nis a key — an element keyed by its position would churn every\ngenerated child the moment the list was reordered.\n \nExamples:\n  pack([a,b], {x:1})   -> {..}  # Names;\n  pack(["a b"], {x:1}) -> {..}  # ... a quoted name is still a name;\n  pack([1,2], {x:1})   -> nil   # ... but a number is not one.',
 
-  each_data: 'The first argument to each() is not a bag. `each` makes one list\nelement per child of its DATA, so the data has to have children: a\nlist, or a map whose values become the elements in sorted-key order.\n \nExamples:\n  each([1,2])       -> [..]  # A list, in source order;\n  each({b:2,a:1})   -> [..]  # ... a map, in sorted-key order;\n  each(1)           -> nil   # ... but a scalar has no children.',
+  each_data: 'The first argument to each() is not a bag. `each` makes one list\nelement per child of its DATA, so the data has to have children: a\nlist, or a map whose values are taken in sorted-key order.\n \nExamples:\n  each([a,b], upper(_))  -> [..]  # A list, in source order;\n  each({b:2,a:1}, _)     -> [..]  # ... a map, in sorted-key order;\n  each(1, _)             -> nil   # ... but a scalar has no children.',
 
   filter_data: 'The first argument to filter() is not a bag. `filter` keeps the\nchildren of its DATA that already satisfy a condition, so the data\nhas to have children: a list, or a map.\n \nExamples:\n  filter([1,x], integer)      -> [..]  # A list;\n  filter({a:1,b:x}, integer)  -> {..}  # ... or a map, keys kept;\n  filter(1, integer)          -> nil   # ... but a scalar has none.',
 
@@ -249,6 +267,9 @@ const hints: Record<string, string> = {
 
   replace_value: 'A replacement value is not text: the `replace` key {key} came to\n{value} at the node. A value reaches the body as a string -- a number\nor a boolean spells itself, as it does after `+` -- and it has to\nhave settled by the time the dispatch fires, so a map, a list, a\nnull or a value still unresolved is refused rather than written into\na file as something else.\n \nExamples:\n  replace: {PIN: .pin}    # A string field;\n  replace: {PORT: .port}  # ... or a number, as digits;\n  replace: {ALL: _}       # ... but the node itself is a map.',
 
+  // RETIRED with the name `form` (ADR-027): the function is `each` now
+  // and answers `each_data`. Registered still, errcodes.tsv being
+  // append-only, so a code a released engine raised keeps its meaning.
   form_data: 'The first argument to form() is not a bag. `form` makes one list\nelement per child of its DATA, so the data has to have children: a\nlist, or a map whose values are taken in sorted-key order.\n \nExamples:\n  form([a,b], upper(_))  -> [..]  # A list, in source order;\n  form({b:2,a:1}, _)     -> [..]  # ... a map, in sorted-key order;\n  form(1, _)             -> nil   # ... but a scalar has no children.',
 
   esc_variant: 'esc(), usc() or a template\'s `esc:` key were given a variant that\nnames no convention.\nA variant names a CONVENTION rather than a language, because several\nlanguages share one and one language has several. The names are `sq`,\n`sql`, `shell`, `xml`, `uri` and `regex`; written with no variant at\nall it is the C escape, JSON canonical, which covers the double-quoted\nliteral of every C-family language.\n \nExamples:\n  esc(text)          -> ...   # C / JSON, the default;\n  esc(text, sq)      -> ...   # ... single-quoted C-family;\n  esc(text, pascal)  -> nil   # ... but that is not a convention.',
@@ -331,6 +352,41 @@ const hints: Record<string, string> = {
     '  pick([{a:1},{b:2}], a)   -> nil    # ... the second does not;\n' +
     '  pick([[9],[8]], 0)       -> [9,8]  # A list child takes an index.',
 
+  sort_key:
+    'A child of this bag has no key `{key}` to order by. Ordering\n' +
+    'refuses rather than skipping, for the reason `pick` does: a\n' +
+    'shorter list orders a DIFFERENT set of records than the one the\n' +
+    'author named. Give every child the key, or filter the bag first.\n' +
+    ' \n' +
+    'Examples:\n' +
+    '  sort([{a:2},{a:1}], a)   -> [{a:1},{a:2}]  # Every child has it;\n' +
+    '  sort([{a:1},{b:2}], a)   -> nil            # ... the second does not;\n' +
+    '  sort([[9],[8]], 0)       -> [[8],[9]]      # A list child takes an index.',
+
+  sort_domain:
+    'This bag cannot be ordered: `{member}`. There are two orders and no\n' +
+    'third -- text by code point, numbers by the exact comparator -- so a\n' +
+    'bag that mixes them, or holds a boolean, a null or a container, has\n' +
+    'no order to be put in. Project a field that is all one kind, or\n' +
+    'filter the bag first.\n' +
+    ' \n' +
+    'Examples:\n' +
+    '  sort([3,1,2])            -> [1,2,3]      # All numbers;\n' +
+    '  sort([b,a])              -> ["a","b"]    # ... or all text;\n' +
+    '  sort([1,a])              -> nil          # ... never both.',
+
+  sort_dir:
+    'A sort direction names no direction: `{dir}`. The third argument is\n' +
+    '`asc` or `desc`, and omitting it is `asc`. The second argument is\n' +
+    'the field to order by, so a keyless descending sort writes the\n' +
+    'empty projector: the member itself.\n' +
+    ' \n' +
+    'Examples:\n' +
+    '  sort($.rows, n)          # Ascending by field `n`;\n' +
+    '  sort($.rows, n, desc)    # ... descending;\n' +
+    '  sort($.tags)             # The members themselves, ascending;\n' +
+    '  sort($.tags, "", desc)   # ... descending.',
+
   join_member:
     'A member of this bag is not text and never will be: `{member}`.\n' +
     '`join` folds with `+` seeded with the empty string, and `+` with a\n' +
@@ -465,8 +521,6 @@ const hints: Record<string, string> = {
   'empty': 'Empty disjunction. The disjunction has no valid alternatives.',
   'empty-dist': 'Empty disjunction distribution. All alternatives in the disjunction are invalid.',
 
-  // ADR-011 R2: two DEFAULTS of equal rank that cannot agree. The
-  // fix is a rank, so the hint names it.
   'pref_rank_clash': 'Two defaults of the same rank disagree.' +
     ' Rank one of them (`**x`) to say which is the weaker layer,' +
     ' or give them the same value.',
@@ -494,15 +548,6 @@ const hints: Record<string, string> = {
 }
 
 
-// codeClasses assigns every error code a CLASS: conflict | incomplete |
-// reference | parse | budget | internal. The contract lives in
-// test/spec/errcodes.tsv (mode `errcode`): the spec suite executes one
-// row per code against this table and asserts SET EQUALITY between the
-// file and these keys, in both implementations (go/hints.go mirrors
-// this map exactly). Codes are append-only and never renamed; a class
-// change is a breaking change. Class rulings (why decimal_budget and
-// lossy_integer_literal are conflict, not budget; why unknown_function
-// is reference) are documented in the tsv header.
 const codeClasses: Record<string, string> = {
   // parse -- the source text is malformed or unusable
   parse: 'parse',
@@ -537,10 +582,6 @@ const codeClasses: Record<string, string> = {
   patch_ambiguous: 'reference',
   patch_span_mismatch: 'internal',
 
-  // G4 phase 2 -- the checked link: a string that is not a tree
-  // address (class `parse`, the text is wrong), and an address that
-  // names nothing in this evaluation (class `reference`, the same
-  // class as `no_path`, because it is the same kind of miss).
   refer_address: 'parse',
   rel_address: 'parse',
   refer_unresolved: 'reference',
@@ -581,10 +622,6 @@ const codeClasses: Record<string, string> = {
   // class as refer_address, because it is the same mistake.
   path_address: 'parse',
 
-  // G8 phase 1 -- the generation combinators. All three are class
-  // `parse`: what is wrong is the CALL as written (data that is not a
-  // bag, a list element that is not a name), not any pair of values a
-  // meet brought together.
   pack_data: 'parse',
   pack_key: 'parse',
   each_data: 'parse',
@@ -597,24 +634,12 @@ const codeClasses: Record<string, string> = {
   filter_data: 'parse',
   match_none: 'conflict',
 
-  // G9 phase 6 -- the string builtins. All five are class `parse`:
-  // what is wrong is the CALL as written -- a variant that names no
-  // convention, a pattern outside the subset, a substitution naming a
-  // group that does not exist, a separator that is neither string nor
-  // pattern. `usc_malformed` is the odd one and still `parse`: the
-  // TEXT the call was given has no inverse, which is a fact about the
-  // argument rather than about any meet.
   esc_variant: 'parse',
   usc_malformed: 'parse',
   rep_pattern: 'parse',
   rep_sub: 'parse',
   split_sep: 'parse',
 
-  // G9 phase 6 -- apply-templates. The four shape codes are class
-  // `parse`: what is wrong is the CALL as written -- a selection with
-  // no children, a table that is not one, a rule missing a half.
-  // `emit_none` is class `conflict` for `match_none`'s reason: the
-  // node and every pattern written for it disagreed.
   emit_data: 'parse',
   emit_table: 'parse',
   emit_template: 'parse',
@@ -622,19 +647,11 @@ const codeClasses: Record<string, string> = {
   emit_none: 'conflict',
   emit_ref: 'conflict',
 
-  // RENDER P6 -- `replace` on a template, and `form`. The two
-  // template checks are class `parse`: what is wrong is the TEMPLATE
-  // as written, before any node. `replace_value` is class `conflict`:
-  // the node's value and the body that wanted text disagreed.
-  // `form_data` is `each_data`'s twin.
   replace_overlap: 'parse',
   replace_unused: 'parse',
   replace_value: 'conflict',
   form_data: 'parse',
 
-  // G8 phase 3 -- the placeholder. Class `conflict`: two values met
-  // and neither could answer for the other, which is what every
-  // conflict is.
   place_pair: 'conflict',
 
   // G6 phase 2 -- modules. Both are class `parse`: a module import is
@@ -675,6 +692,9 @@ const codeClasses: Record<string, string> = {
   constraint: 'conflict',
   must: 'conflict',
   constraint_pattern: 'conflict',
+  abnf_grammar: 'parse',
+  parse_arg: 'parse',
+  parse_failed: 'conflict',
   scalar_value: 'conflict',
   scalar_kind: 'conflict',
   no_scalar_unify: 'conflict',
@@ -692,6 +712,9 @@ const codeClasses: Record<string, string> = {
   exact_float_mix: 'conflict',
   inexact_integer_sum: 'conflict',
   pick_key: 'conflict',
+  sort_key: 'conflict',
+  sort_domain: 'conflict',
+  sort_dir: 'parse',
   aggregate_data: 'conflict',
   aggregate_empty: 'conflict',
   join_member: 'conflict',