aontu 0.61.0 → 0.62.0

package/src/format.ts

@@ -1190,15 +1190,59 @@ function mergeDeep(p: Node): Node {
   return { ...p, value: 'pair' === v.t ? body[0] : { ...v, body }, orig: [p] }
 }
 
+// Whether a value is a RECORD: a braced map of several entries, every
+// one of them a VALUE rather than another map. A field, an error, a
+// rule row -- something whose keys are what it IS, as against a level
+// of the tree, whose keys are a way through to something else.
+//
+// A CHAIN IS NOT ONE, whatever it holds: a one-entry map is D1's, and
+// D1 writes it as a chain at every width. Nor is a map holding a
+// spread, which says something about the map's MEMBERS and which D1's
+// exception already gives a spelling of its own inside a repeat.
+function record(v: Node, entries: Node[]): boolean {
+  if ('map' !== v.t) {
+    return false
+  }
+  let pairs = 0
+  for (const e of entries) {
+    if ('spread' === e.t) {
+      return false
+    }
+    if ('pair' !== e.t) {
+      continue
+    }
+    if (undefined !== plainEntries(e.value!)) {
+      return false
+    }
+    pairs++
+  }
+  return 1 < pairs
+}
+
 // The lines of a map repeated under a prefix (§3.4, rule 2): every
 // entry written with the prefix in front of it as one line, or --
-// where an entry's value is a map that does not fit -- repeated further
+// where an entry's value is a map that does not fit -- descended into
 // under the longer prefix. Comments and blank lines are kept where
 // they stood. Undefined where an entry cannot be one line: a list that
 // does not fit, a value that spans lines, a comment closing the map
 // (which a repeat could not keep in the map) -- and where the map holds
 // two spreads, which repeated would be two maps, and a different meet.
-type Line = { t: 'text' | 'comment' | 'blank', text?: string }
+//
+// A DESCENT ENDS AT A RECORD (§3.4, D2's amendment). The prefix reaches
+// through maps that hold maps, because those keys are a path and a line
+// carrying the whole path says where it is. It stops at a map that
+// holds only values: there the keys are the thing's own fields, the
+// prefix in front of each of them is the same prefix again, and the
+// map is written as a braced BLOCK under the prefix instead --
+// `entity: planet: field: id: {` and its seven facts indented once.
+// The statement's own map is not an entry of anything and is
+// unaffected, so a flat `service: host: …` is still one repeat.
+type Line = {
+  t: 'text' | 'comment' | 'blank' | 'block'
+  text?: string
+  node?: Node
+  trail?: string
+}
 
 function repeatLines(entries: Node[], prefix: string, indent: number): Line[] | undefined {
   if (0 === entries.length || 'comment' === entries[entries.length - 1].t ||
@@ -1240,8 +1284,27 @@ function repeatLines(entries: Node[], prefix: string, indent: number): Line[] |
     if (undefined === lines) {
       return undefined
     }
+    // THE DESCENT COULD GO ON, AND WHAT IT REACHES IS A RECORD: it
+    // stops, and the record is a block under the prefix instead. The
+    // deeper repeat is asked for first and thrown away deliberately --
+    // the block REPLACES a descent that would have worked, and never
+    // rescues one that would not, so a map this rule cannot reach two
+    // ways round is laid out exactly as it was before the amendment.
+    if (record(e.value!, sub)) {
+      out.push({ t: 'block', text: head, node: e.value!, trail })
+      continue
+    }
     if ('' !== trail) {
-      lines[lines.length - 1].text += trail
+      // Onto the last line written for this entry -- and after the
+      // CLOSER where that line is a block, which is where the trailing
+      // comment of the entry the block came from also stands.
+      const last = lines[lines.length - 1]
+      if ('block' === last.t) {
+        last.trail = (last.trail ?? '') + trail
+      }
+      else {
+        last.text += trail
+      }
     }
     out.push(...lines)
   }
@@ -1297,6 +1360,15 @@ function emitStatement(w: Writer, p: Node, indent: number, stmt: Stmt, prefix: s
         pending = false
         count++
         w.text(line.text!)
+        if ('block' === line.t) {
+          // The record the descent stopped at: its entries are
+          // statements in turn, and the whole statement this repeat
+          // belongs to is what carries the check, so they are covered.
+          emitBlock(w, '{', '}', line.node!, indent, { meet: stmt.meet, covered: true })
+          if (undefined !== line.trail) {
+            w.text(line.trail)
+          }
+        }
       }
       rewritten = true
     }

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\"above\" / %s\"acyclic\" / %s\"add\" / %s\"below\" / %s\"close\"\n          / %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\"list\" / %s\"lower\" / %s\"map\" / %s\"match\"\n          / %s\"max\" / %s\"min\" / %s\"mod\" / %s\"move\"\n          / %s\"mul\" / %s\"must\"\n          / %s\"neq\"\n          / %s\"open\" / %s\"pack\" / %s\"path\" / %s\"pick\" / %s\"pref\"\n          / %s\"refer\" / %s\"rel\" / %s\"rem\" / %s\"rep\" / %s\"re\" / %s\"split\"\n          / %s\"super\"\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

@@ -203,6 +203,17 @@ 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.',
+
+  // THIS PORT NEVER RAISES decimal_syntax -- Go's construct.go does,
+  // and go/hints.go's header records that the CODE is Go-only. The
+  // TEXT is here anyway, verbatim, because since G11 phase 3 this
+  // table is a LOOKUP surface as well as a message source: the code is
+  // in the shared registry (test/spec/errcodes.tsv), so
+  // `aontu explain decimal_syntax` must answer the same in both ports
+  // or the agent that met the error under one binary learns nothing
+  // from the other. An entry for a code this port cannot raise is
+  // never read on an error path, only on that lookup.
+  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 +236,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 +260,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.',
@@ -626,7 +640,7 @@ const codeClasses: Record<string, string> = {
   // 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.
+  // `form_data` is `each_data`'s retired twin (ADR-027).
   replace_overlap: 'parse',
   replace_unused: 'parse',
   replace_value: 'conflict',

package/src/lang.ts

@@ -142,8 +142,10 @@ import { DeprecateFuncVal } from './val/DeprecateFuncVal'
 import { ReferFuncVal, RelFuncVal } from './val/ReferFuncVal'
 import { AcyclicFuncVal, InverseFuncVal } from './val/GraphAtomVal'
 import { PackFuncVal } from './val/PackFuncVal'
+import { CMP_FUNCS } from './val/CmpFuncVal'
+import { NomFuncVal } from './val/NomFuncVal'
+import { TranslateFuncVal } from './val/TranslateFuncVal'
 import { EachFuncVal } from './val/EachFuncVal'
-import { FormFuncVal } from './val/FormFuncVal'
 import { FilterFuncVal } from './val/FilterFuncVal'
 import { MatchFuncVal } from './val/MatchFuncVal'
 import { EmitFuncVal } from './val/EmitFuncVal'
@@ -915,21 +917,24 @@ help isolate the syntax error.`,
     acyclic: AcyclicFuncVal,
     inverse: InverseFuncVal,
 
-    // G8 phase 1: the generation combinators. `pack` makes one keyed
-    // child per child of its data, `each` one list element; both clone
-    // their template per destination exactly as a spread does, and both
-    // wait for the model to settle before they fire (the staging rule,
-    // G8 phase 0).
+    // G8 phase 1: generation to KEYED CHILDREN. `pack` makes one keyed
+    // child per child of its data, cloning its template per
+    // destination exactly as a spread does, and waits for the model to
+    // settle before it fires (the staging rule, G8 phase 0).
     pack: PackFuncVal,
-    each: EachFuncVal,
 
-    // RENDER P6: the order-preserving map. `form` makes one list
-    // element per child of its data, being the template with `_`
-    // bound to the source child -- a construction, where `each` is a
-    // bound (G9 §4). It exists because `pick(pack(...))` re-sorts to
-    // code-point order, and a struct's fields or a file's imports
-    // are the model's order or they are wrong.
-    form: FormFuncVal,
+    // RENDER P6: the order-preserving map, and generation to a LIST.
+    // `each` makes one list element per child of its data, being the
+    // template with `_` bound to the source child. It exists because
+    // `pick(pack(...))` re-sorts to code-point order, and a struct's
+    // fields or a file's imports are the model's order or they are
+    // wrong.
+    //
+    // Mentioning the hole makes it a BOUND instead: `each(d, _ & t)`
+    // meets each child with `t`, and `each(d, _)` is a bag's members
+    // as a list. That is what the retired meet-only `each` spelled
+    // (ADR-026), and why this one could take the name (ADR-027).
+    each: EachFuncVal,
 
     // G8 phase 2: selection. `filter` keeps the children of a bag that
     // unify with a condition; `match` picks the first arm whose
@@ -962,7 +967,8 @@ help isolate the syntax error.`,
 
     // Projection, which is what lets the aggregates reach a bag of
     // RECORDS: `sum(pick($.lines, amountCents))`. Not a clever `each`
-    // template -- `each` MEETS each child, and a meet cannot select.
+    // template -- `each(d, _ & t)` MEETS each child, and a meet cannot
+    // select.
     pick: PickFuncVal,
 
     // G9 phase 2: the fold to a STRING. `sum` folds with `add`; this
@@ -989,6 +995,39 @@ help isolate the syntax error.`,
     usc: UscFuncVal,
     rep: RepFuncVal,
     split: SplitFuncVal,
+
+    // THE COMPONENT PRIMITIVES -- SPIKE (ts/src/val/CmpFuncVal.ts,
+    // docs/design/JOSTRACA.0.md). jostraca's component set, spelled
+    // as functions -- LOWER CASE, like every other builtin in this
+    // language, while the node each one builds names the jostraca
+    // component it drives (`file(...)` is aontu, `"File"` is
+    // jostraca's). A document then says what FILES it produces
+    // instead of filling in the `aontu:code` vocabulary as data.
+    // Eight of jostraca's ten: `copy` and `list` are already builtins
+    // here with unrelated meanings, so those two have no lower-case
+    // spelling to take (see ts/src/val/CmpFuncVal.ts).
+    //
+    // TypeScript only, and so deliberately NOT in
+    // test/spec/signature.tsv, BUILTIN_FUNCS (ts/src/lsp.ts) or the
+    // grammar/ files -- each is asserted in cross-port parity and a
+    // TS-only entry turns the Go suite red. Arity and argument shape
+    // are refused in CmpFuncVal.resolve for the same reason.
+    ...CMP_FUNCS,
+
+    // NAME TRANSFORMATION -- SPIKE (ts/src/val/NamerFuncVal.ts).
+    // Generated code is mostly names, and no two targets spell them
+    // the same way. Splits a name into words whatever format it is
+    // written in, then renders it in the target's. TypeScript only,
+    // and out of the parity-pinned registries for the reason the
+    // component primitives are.
+    nom: NomFuncVal,
+
+    // PER-CHARACTER SUBSTITUTION AND DELETION -- SPIKE
+    // (ts/src/val/TranslateFuncVal.ts), after `tr`. Reads the source
+    // once and consults a table, which is what `rep` cannot do: a
+    // per-character map spelled as N `rep` calls composes wrongly,
+    // since each pass sees the previous one's output.
+    translate: TranslateFuncVal,
   }
 
 
@@ -2250,13 +2289,13 @@ function makeModelResolver(options: any) {
   // remain available under every capability but 'none' — they are
   // host-provided, not document-requested, so confining them would
   // confine the host against itself.
-  // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts) rides the
-  // memory leg: served from the engine itself, so it needs neither the
-  // filesystem nor package resolution and is available under every
-  // capability but `none` — which denies every include outright, that
-  // being what `none` means. Host entries and the capability's own set
-  // WIN over it: a caller that supplies its own `std/system` gets the
-  // one it supplied.
+  // A LANGUAGE-SUPPLIED MODEL DOES NOT RIDE THIS LEG (ADR-028). Every
+  // bundled schema is named under `aontu:` and answered by the scheme
+  // leg above, which returns before the memory resolver is built, so
+  // neither a host entry nor a capability's own file set can stand in
+  // front of one: `aontu:system` is the engine's, always. That is what
+  // the prefix buys, and it is why the bare-name leg that once let a
+  // caller shadow `std/system` is gone.
   let memResolver = makeMemResolver(memCapability
     ? { ...(capability as any).mem }
     : { ...(options.resolver?.mem || {}) })
@@ -2426,10 +2465,14 @@ function makeModelResolver(options: any) {
     // else -- the memory, module, file and package legs are never
     // asked, so nothing on disk can shadow one and a typo is refused
     // here, naming the set, rather than searched for. Available under
-    // every capability but `none`, checked just above, like the std
-    // names below. A path that is not a string (`a: @1`) is not a name
-    // at all: it falls through to the legs below and is not found there,
-    // as it always was.
+    // every capability but `none`, checked just above. A path that is
+    // not a string (`a: @1`) is not a name at all: it falls through to
+    // the legs below and is not found there, as it always was.
+    //
+    // This is the ONLY leg that serves a bundled model (ADR-028). The
+    // vocabularies once had bare names (`std/system`) and a second leg
+    // below to match them; the prefix is now the whole spelling, so one
+    // leg answers for every language-supplied schema.
     if ('string' === typeof path && path.startsWith(AONTU_SCHEME)) {
       const model = STD_SOURCES[path]
       if (null == model) {
@@ -2439,19 +2482,6 @@ function makeModelResolver(options: any) {
       return { found: true, path, full: path, kind: 'aon', src: model, search: [] }
     }
 
-    // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts): served from
-    // the engine itself, so it needs neither the filesystem nor package
-    // resolution and is available under every capability but `none` —
-    // checked just above, that being what `none` means. Matched against
-    // the name the author WROTE, before the memory leg, so the kind is
-    // stated rather than guessed from an extension the bare name does
-    // not have.
-    const std = STD_SOURCES[path]
-    if (null != std) {
-      record(ctx, path, 'std')
-      return { found: true, path, full: path, kind: 'aon', src: std, search: [] }
-    }
-
     let search: any = []
     let res = memResolver(path, popts, rule, ctx, jsonic)
     res.path = path
@@ -2581,10 +2611,27 @@ for (const name in funcSig) {
   }
 }
 
+// THE COMPONENT PRIMITIVES, listed by hand (the spike, see funcMap
+// above and ts/src/val/CmpFuncVal.ts). They carry no signature
+// declaration, so the derivation above cannot see them -- and
+// `file("main.ts", [...])` without an entry arrives as ONE raw array
+// term, which the call then reads as its spec. The leaves are here
+// too, so that a written second argument is COUNTED and refused as
+// the arity mistake it is rather than arriving as a one-element list
+// that is merely the wrong shape.
+for (const name of Object.keys(CMP_FUNCS)) {
+  POSITIONAL_ARG_FUNCS[name] = true
+}
+POSITIONAL_ARG_FUNCS['nom'] = true
+POSITIONAL_ARG_FUNCS['translate'] = true
+
 
-// [min, max]; a max of -1 is unbounded. Every name in funcMap has an
+// [min, max]; a max of -1 is unbounded. Every DECLARED name has an
 // entry, and the arity is a property of the language rather than of
-// either port -- go/func.go derives the same table. A required slot
+// either port -- go/func.go derives the same table. The spike's
+// component primitives are the one exception: they carry no
+// declaration, so they have no entry here and refuse a bad count in
+// their own resolve (ts/src/val/CmpFuncVal.ts). A required slot
 // counts toward the minimum; a rest slot makes the maximum unbounded
 // and counts its group size (one, for a plain rest type) toward the
 // minimum, which is what gives `match` its floor of three and `neq`
@@ -2646,7 +2693,16 @@ function arityText(lo: number, hi: number): string {
     return 'one or more arguments'
   }
   if (lo !== hi) {
-    return 0 === lo ? 'no arguments or one' : 'one argument or two'
+    if (0 === lo) {
+      return 'no arguments or one'
+    }
+    // The case range gave `upper` and `lower` a span rather than a
+    // pair, and a two-arm phrasing cannot say it: [1,3] read as "one
+    // argument or two", which is a wrong count rather than an
+    // imprecise one. Each arm here is a shape the table actually
+    // carries, and each is pinned by a row -- a phrasing for a count no
+    // entry has would be untested prose pretending to be tested.
+    return 3 === hi ? 'one to three arguments' : 'one argument or two'
   }
   // The {0,0} arm returned with the container kinds and acyclic()
   // (ADR-015): `map(1)` must not claim map takes exactly one.

package/src/lower.ts

@@ -103,19 +103,19 @@ export function splitWords(name: string): string[] {
   return words
 }
 
-function lowerASCII(s: string): string {
+export function lowerASCII(s: string): string {
   return Array.from(s).map((c) =>
     isUpper(c) ? String.fromCharCode(c.charCodeAt(0) + 32) : c).join('')
 }
 
-function upperASCII(s: string): string {
+export function upperASCII(s: string): string {
   return Array.from(s).map((c) =>
     isLower(c) ? String.fromCharCode(c.charCodeAt(0) - 32) : c).join('')
 }
 
 // A word capitalised: the acronym set wins, so `id` is `ID` under a
 // profile that lists it and `Id` under one that does not.
-function capitalise(word: string, acronyms: string[]): string {
+export function capitalise(word: string, acronyms: string[]): string {
   const low = lowerASCII(word)
   for (const a of acronyms) {
     if (lowerASCII(a) === low) {

package/src/lsp.ts

@@ -528,7 +528,7 @@ const COMPLETION_KEYWORD = 14
 const BUILTIN_FUNCS = [
   'above', 'acyclic', 'add', 'below', 'close', 'copy', 'deprecate', 'div',
   'each', 'emit', 'esc',
-  'filter', 'form', 'greatest',
+  'filter', 'greatest',
   'hide', 'inverse', 'join', 'key', 'least', 'length', 'list', 'lower',
   'map', 'match', 'max', 'min', 'mod', 'move', 'mul', 'must', 'neq', 'open',
   'pack', 'path', 'pick',

package/src/relation.ts

@@ -61,6 +61,12 @@ export type RelationReport = {
   // arrive with an empty list -- something is wrong, and nothing about
   // what. Present ONLY on an `error` verdict.
   errors?: VetFinding[]
+
+  // How many relation declarations the document makes (G11 phase 4).
+  // ZERO is the answer that matters: `pass` over no declarations means
+  // nothing was checked, and without this the two are one word.
+  // Absent unless the run asked for it (`RelationOptions.count`).
+  declared?: number
 }
 
 export type RelationOptions = {
@@ -76,6 +82,14 @@ export type RelationOptions = {
   // Rides beside `trust` because it is the other half of what an
   // include may read.
   textExt?: string[]
+
+  // Count the relation declarations the document makes (G11 phase 4),
+  // so a caller can tell a graph that CHECKED CLEAN from one there was
+  // nothing to check. `pass` is the same word for both, which is the
+  // whole reason this exists. Absent from the report unless asked for,
+  // so no existing caller's report changes shape -- `vet --coverage`
+  // sets the precedent.
+  count?: boolean
 }
 
 
@@ -271,8 +285,13 @@ export function relationCheck(
   }
 
   const decls: Map<string, RelDecl> = (ctx as any)._reldecls
+  // The count rides every report from here down: the engine knows it
+  // at exactly this point, and a caller asking "was there anything to
+  // check?" should not have to evaluate the document a second time to
+  // find out.
+  const counted = true === options.count ? { declared: decls.size } : {}
   if (0 === decls.size) {
-    return { verdict: 'pass', findings: [] }
+    return { verdict: 'pass', findings: [], ...counted }
   }
 
   // NOR IS A DOCUMENT THAT CANNOT BE GENERATED. Unification can
@@ -299,5 +318,6 @@ export function relationCheck(
   return {
     verdict: 0 === findings.length ? 'pass' : 'fail',
     findings,
+    ...counted,
   }
 }