aontu 0.66.0 → 0.68.0

package/src/cli.ts

@@ -166,22 +166,30 @@ query between a document and its own earlier versions.
 
 Options:
   -c, --canon     Print the canonical form instead of generated JSON
-  --format <f>    text (default) or json. The json form wraps the
-                  answer as {aontu, findings, ok, out}, so a failure
-                  here reads like every other verb's
+                  (the bare command's, as --jsonl is; model get has
+                  its own)
+  --format <f>    text (default) or json, on every verb that answers a
+                  report. The json form is one object opening with an
+                  aontu block; the bare command's carries findings, ok
+                  and out
   -h, --help      Show this help and exit (the verbs and their flags);
                   aontu help is the LANGUAGE, and lists its own topics
   --jsonl         REPL: answer every command as one JSON line
   -v, --version   Print the version and exit
-  --trust <t>     Include capability: system (default), none, or
-                  root[:dir] to confine @"..." below a directory.
-                  Every verb takes it too, and a bare root means the
-                  document's own directory
+  --trust <t>     Include capability: system, none, or root[:dir] to
+                  confine @"..." below a directory. A bare root means
+                  the entry root: the document's own directory, or the
+                  project's for the package verbs. Every verb takes it
+                  but help, explain, init and lsp, which read no
+                  document, and mcp, which is the npm build's server
+                  and confines with --root. Unset, a run behaves as
+                  system, and the bare command warns once for an
+                  include that leaves the entry root
   --include-root <dir>  Shorthand for --trust root:<dir>
-  --text-ext <e>  Read these extensions as text too, comma-separated
-                  and without dots (md,sql). .txt needs no flag; a
+  --text-ext <e>  Read these extensions as text too, comma-separated,
+                  with or without dots (md,sql). .txt needs no flag; a
                   named format keeps its meaning, and .js stays
-                  refused. Every verb takes it
+                  refused. The verbs that take --trust take it too
 
 Package verbs (a module is imported; a package is published):
   sync      Make the project correct: resolve by minimum version
@@ -708,7 +716,7 @@ function takeTrust(argv: string[], io: Io = PROCESS_IO):
     }
     else if ('--include-root' === arg) {
       const dir = argv[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         io.err('aontu: --include-root needs a directory\n')
         return undefined
       }
@@ -2704,20 +2712,42 @@ function pkgNetText(verb: string, report: any): string {
 const MODEL_HELP = 'aontu model get|why|set ... (try --help)'
 
 // One document, interrogated or edited (ADR-039 part 5).
+// Where the subcommand is, past any global flag that precedes it.
+// `takeTrust` strips those anywhere in a tail, so the subcommand has
+// to be found past a flag AND past its value: in `--text-ext get` the
+// `get` is the extension list, not the subcommand.
+const MODEL_SUBS = ['get', 'why', 'set']
+const GLOBAL_VALUED = ['--trust', '--include-root', '--text-ext']
+
+
+function modelSubAt(argv: string[]): number {
+  for (let i = 0; i < argv.length; i++) {
+    if (GLOBAL_VALUED.includes(argv[i])) {
+      i++
+      continue
+    }
+    return MODEL_SUBS.includes(argv[i]) ? i : -1
+  }
+  return -1
+}
+
+
 function runModel(argv: string[]): number {
   const sub = argv[0]
   if ('-h' === sub || '--help' === sub) {
     process.stdout.write(HELP)
     return 0
   }
-  if ('get' === sub) {
-    return runGet(argv.slice(1))
-  }
-  if ('why' === sub) {
-    return runWhy(argv.slice(1))
-  }
-  if ('set' === sub) {
-    return runSet(argv.slice(1))
+  const at = modelSubAt(argv)
+  if (0 <= at) {
+    const tail = argv.slice(0, at).concat(argv.slice(at + 1))
+    if ('get' === argv[at]) {
+      return runGet(tail)
+    }
+    if ('why' === argv[at]) {
+      return runWhy(tail)
+    }
+    return runSet(tail)
   }
   process.stderr.write(`aontu: model needs get, why or set\n${MODEL_HELP}\n`)
   return 2
@@ -2931,6 +2961,70 @@ function isDirectory(path: string): boolean {
 }
 
 
+// A `File` the write path skips, RENAMED rather than removed: dropping
+// the node would take its children's claims with it and hide drift the
+// write path does make. The skip is the File's own save alone, so what
+// separates the runs is its output path, composed by the runtime rather
+// than here.
+const EXCLUDED_NAME = '.aontu-check-excluded-'
+
+
+// `exclude` as the runtime reads it: `true`, or a string or list member
+// equal to the node's COMPONENT path, the chain of `name` props above
+// it, which a Project's `folder` is not part of. The Go runtime honours
+// the boolean alone, so the ports' `--check` answers differ for the
+// path forms (test/spec/divergent.tsv).
+function excludedFile(exclude: any, at: string[]): boolean {
+  if (true === exclude) {
+    return true
+  }
+  const path = at.join('/')
+  if ('string' === typeof exclude) {
+    return exclude === path
+  }
+  return Array.isArray(exclude) && exclude.includes(path)
+}
+
+
+function renameExcluded(node: any, at: string[], cut: number[]): any {
+  if (Array.isArray(node)) {
+    return node.map((child) => renameExcluded(child, at, cut))
+  }
+  // A hand-written tree carries nodes with no `props` and nodes with
+  // no `children`, and neither needs an arm of its own.
+  const props: any = node.props ?? {}
+  const below = 'string' === typeof props.name ? at.concat(props.name) : at
+  if ('File' === node.cmp && excludedFile(props.exclude, below)) {
+    cut.push(1)
+    return { ...node, props: { ...props, name: EXCLUDED_NAME + cut.length } }
+  }
+  if (!Array.isArray(node.children)) {
+    return node
+  }
+  return { ...node, children: renameExcluded(node.children, below, cut) }
+}
+
+
+// A file the runtime declined to touch, its copy on disk carrying the
+// protect marker, is in none of the lists it answers with: they hold
+// what was DONE to a file, and nothing was. The run's own record names
+// it. `since` drops what earlier runs left.
+function renderSkipped(folder: string, since: number): string[] {
+  const at = join(folder, '.jostraca', 'jostraca.meta.log')
+  let meta: any
+  try {
+    meta = JSON.parse(readFileSync(at, 'utf8'))
+  }
+  catch (err: any) {
+    return []
+  }
+  return Object.entries(meta?.files ?? {})
+    .filter(([_, f]: [string, any]) => 'skip' === f?.action && since <= f?.when)
+    .map(([path]) => path)
+    .sort(cmpCodePoint)
+}
+
+
 async function runRender(argv: string[]): Promise<number> {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -3081,7 +3175,22 @@ async function runRender(argv: string[]): Promise<number> {
   try {
     if (check) {
       const res = await runtime.check({ folder }, root)
-      const drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      let drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      // `--check` answers "would `render` change anything", so a file
+      // the write path leaves alone is not held to the generator's
+      // bytes. The skip is gated on the target BEING there -- `render`
+      // writes an absent one -- so drift at a path with nothing at it
+      // survives, which is the `missing` a deleted file reports.
+      const cut: number[] = []
+      const renamed = renameExcluded(tree, [], cut)
+      if (0 < cut.length) {
+        const kept = new Set<string>((await Jostraca().check(
+          { folder }, cmpTree(renamed, { raw: true }))).checked)
+        const skipped = new Set<string>(
+          res.checked.filter((p: string) => !kept.has(p)))
+        drift = drift.filter((d: any) => !skipped.has(d.path) ||
+          !existsSync(join(folder, d.path)))
+      }
       if ('json' === format) {
         process.stdout.write(exactJSON({
           aontu: { version: version(), verb: 'render' },
@@ -3098,14 +3207,21 @@ async function runRender(argv: string[]): Promise<number> {
       return 0 === drift.length ? 0 : 1
     }
 
+    const since = Date.now()
     const res = await runtime.generate({ folder }, root)
+    const skipped = renderSkipped(folder, since)
     if ('json' === format) {
       process.stdout.write(exactJSON({
         aontu: { version: version(), verb: 'render' },
         verdict: 'ok',
-        files: res.files,
+        files: { ...res.files, skipped },
       }, 2) + '\n')
     }
+    else {
+      for (const path of skipped) {
+        process.stdout.write(`skipped: ${path}\n`)
+      }
+    }
     return 0
   }
   catch (err: any) {
@@ -3932,7 +4048,7 @@ function runHash(argv: string[]): number {
   if (0 < ctx.err.length || true === v?.isNil) {
     process.stderr.write(
       `aontu: ${files[0]} does not evaluate on its own; nothing to hash\n` +
-      renderFinding(evalFailure(ctx)) + '\n')
+      renderFinding(evalFailure(ctx, v)) + '\n')
     return 4
   }
 
@@ -4923,6 +5039,17 @@ function runHelp(argv: string[]): number {
 // and carries that prefix's hint.
 const EXPLAIN_PREFIXES = ['func:', 'op:', 'op[', 'var[', 'ref[']
 
+// A report prints the namespaced spelling in its brackets, which is the
+// span a reader copies. The answer names the registered one.
+const EXPLAIN_NAMESPACE = 'aontu/'
+
+
+function canonExplainCode(code: string): string {
+  return code.startsWith(EXPLAIN_NAMESPACE)
+    ? code.slice(EXPLAIN_NAMESPACE.length)
+    : code
+}
+
 
 function explainCode(
   code: string): { cls: string, hint: string, registered: boolean } {
@@ -4962,9 +5089,10 @@ function explainListText(format: SubsumeFormat): string {
       codes: codes.map((code) => ({
         code,
         class: codeClass(code),
-        // Whether this port carries explanation text for the code. The
-        // registry is in parity; the hint tables are not, so a consumer
-        // that wants only explained codes can filter rather than guess.
+        // Whether this port carries explanation text for the code. A
+        // gate holds every registered code explained, so this reads
+        // true throughout; it stays because the registry is
+        // append-only and a consumer should filter rather than guess.
         explained: '' !== explainCode(code).hint,
       })),
     }, 2)
@@ -4972,7 +5100,21 @@ function explainListText(format: SubsumeFormat): string {
   const width = codes.reduce((w, c) => Math.max(w, c.length), 0)
   return codes.map((c) =>
     c.padEnd(width) + '  ' + codeClass(c) +
-    ('' === explainCode(c).hint ? '  (no text)' : '')).join('\n')
+    noTextMark(explainCode(c).hint)).join('\n')
+}
+
+
+// The registry is append-only, so a code can be registered before its
+// text is written; saying so beats printing an empty block.
+function explainBody(hint: string): string {
+  return '' === hint
+    ? '(no explanation text is registered for this code)'
+    : hint
+}
+
+
+function noTextMark(hint: string): string {
+  return '' === hint ? '  (no text)' : ''
 }
 
 
@@ -5022,7 +5164,7 @@ function runExplain(argv: string[]): number {
     return 2
   }
 
-  const code = codes[0]
+  const code = canonExplainCode(codes[0])
   const { cls, hint, registered } = explainCode(code)
   if (!registered) {
     // AN UNKNOWN CODE IS A USAGE ERROR AND NAMES NEAR MATCHES. A
@@ -5048,13 +5190,8 @@ function runExplain(argv: string[]): number {
     }, 2) + '\n')
     return 0
   }
-  // A REGISTERED CODE WITH NO HINT SAYS SO rather than printing an
-  // empty block, which would read as an explanation that happened to
-  // be blank.
-  const body = '' === hint
-    ? '(no explanation text is registered for this code)'
-    : hint
-  process.stdout.write(`code:  ${code}\nclass: ${cls}\n\n${body}\n`)
+  process.stdout.write(
+    `code:  ${code}\nclass: ${cls}\n\n${explainBody(hint)}\n`)
   return 0
 }
 
@@ -5322,7 +5459,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     }
     else if ('--include-root' === arg) {
       const dir = args[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         process.stderr.write('aontu: --include-root needs a directory\n')
         return finish(2)
       }
@@ -5371,7 +5508,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
   else {
     runStdin(mode, format, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 21 */
+} /* node:coverage ignore next 22 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -5385,9 +5522,10 @@ export {
   runJsonSchema,
   runTemplate,
   runTrace,
-  runRender,
+  runRender, renderSkipped,
   runPkg, runModel, runPackageVerb, pkgToolOptions, serveUntilInterrupted,
   runHash, runGet, runHelp, runExplain, runInit, nearestVerb,
+  explainBody, noTextMark, canonExplainCode,
   looksLikeVerb,
   KNOWN_VERBS,
   runWhy, renderWhyText, runSet, runAllow, runAgentsMd, runFmt,

package/src/helpdoc.ts

@@ -35,7 +35,7 @@ const HELPDOC: HelpTopic[] = [
     "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 model 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 model 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 model 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 model 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"
+    "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 model 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 model 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## Looking a code up\n\n```\naontu explain constraint    # what one code means, and its class\naontu explain --list        # every registered code, with its class\n```\n\nA report prints two bracketed spans, and only one of them is a code:\n\n```\n$.note.n1.id: constraint [conflict]\n  [aontu/constraint]: Cannot unify values at path $.note.n1.id\n```\n\n`[conflict]` is the **class**. `[aontu/constraint]` is the **code**,\ncarrying the `aontu/` prefix. `explain` takes either spelling —\n`constraint` or `aontu/constraint` — and answers under the registered\none. The headline carries the bare code as well, and so does the `code`\nfield of a `--format json` report.\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…`. Every code in the registry has hint text, which is what\n`aontu explain` prints. A finding carries it inline for an exact\nregistry code; a **dynamic** code (`func:upper`, `op[+]`) is registered\nthrough its prefix, and only `explain` falls back to the prefix's text,\nso such a finding carries no `hint`.\n\nFor a conflict, `aontu model 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 model 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",

package/src/hints.ts

@@ -181,7 +181,7 @@ const hints: Record<string, string> = {
 
   merge_conflict: 'A version-control conflict marker was found in the source. The\nfile still holds an unresolved merge: resolve it and remove the\n`<<<<<<<`, `=======` and `>>>>>>>` lines before unifying.\n \nExamples:\n  <<<<<<< HEAD  -> nil  # A conflict marker, not a `<` operation;\n  =======       -> nil  # ... nor a chain of `=` characters;\n  >>>>>>> other -> nil  # ... nor a `>` operation.',
 
-  include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"./in-root.aon"    -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
+  include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"./in-root.aon"  -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
   include_extension: 'An @\"...\" include named a file the engine does not read. THE\nEXTENSION DECIDES which of two things a file is: `.aon` and\n`.aontu` are aontu source, with the whole language in them, and\n`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,\n`.yaml`, `.yml` and `.ini` are configuration DATA, read by that\nformat\'s own parser. Anything else -- and a name with no extension\n-- is refused rather than guessed at: a guess produces a document\nthat looks right and is not.\n \nExamples:\n  a:@\"model.aon\"    -> {..}  # aontu source;\n  a:@\"server.toml\"  -> {..}  # ... config data, read as TOML;\n  a:@\"notes.txt\"    -> nil   # ... but text is not a document;\n  a:@\"data\"         -> nil   # ... and neither is an unnamed kind.',
 
   func_arity: 'This function was called with the wrong number of arguments:\n{func} takes {want}, but was given {got}.\n \nExamples:\n  upper(\"a\")     -> \"A\"  # One argument, which is what upper takes;\n  upper(\"a\",\"b\") -> nil  # ... so two is a mistake in the source;\n  key()          -> \"\"   # key takes none, or one level count;\n  neq(1,2,3)     -> neq  # ... and neq takes one or more exclusions.',
@@ -542,6 +542,201 @@ const hints: Record<string, string> = {
   // Close operation
   'close': 'Failed to close structure. The structure could not be closed.',
 
+  // Parse: the source text is malformed or unusable
+  'parse': 'The document could not be turned into a value. This wraps the\n' +
+    'failure that stopped it -- a syntax error, or a source the include\n' +
+    'machinery refused -- and that inner code and its frame say which,\n' +
+    'so a report names the inner code rather than this one.\n' +
+    ' \nNote that `parse` is also the name of a CLASS, and the class is\n' +
+    'what a refusal shows in the second bracket: `syntax [parse]` is\n' +
+    'the code `syntax` in the class `parse`.',
+
+  'syntax': 'The text is not valid Aontu syntax. The frame points at the\n' +
+    'character the parser stopped on; the fault is usually just before\n' +
+    'it, and commenting out the suspect lines with # isolates which.',
+
+  'parse_unknown':
+    'A parsed value arrived in a kind the language has no value for.\n' +
+    'Aontu builds from maps, lists, strings, numbers, booleans and nil,\n' +
+    'so a value outside that set is a defect in whatever produced it\n' +
+    'rather than something a document can write.',
+
+  'negative': 'Only a number can be negated. A `-` in front of a\n' +
+    'non-numeric value is an error rather than a missing value.\n' +
+    ' \nA `-` is a PREFIX here and never an operator between two values,\n' +
+    'so subtraction is sub(a, b).' +
+    '\n \nExamples:\n' +
+    '  a: -1       -> -1     # A number negates;\n' +
+    '  a: -x       -> nil    # ... a bare word does not;\n' +
+    '  a: k-x      -> "k-x"  # ... and this is one word, not a minus;\n' +
+    '  a: sub(5,3) -> 2      # Subtraction is a function.',
+
+  'not_number': 'This numeric literal is not a finite number. A literal\n' +
+    'past the range a double can hold (1e999) overflows to infinity\n' +
+    'while lexing, which is an error value and not a number. Write it\n' +
+    'within range, or as a decimal literal with the 0d escape.',
+
+  'incomplete_expression':
+    'The expression has no terms. An operator or a pair of parentheses\n' +
+    'was written with nothing for it to work on -- `a:()` is the bare\n' +
+    'case. Supply the operand, or delete the construct.',
+
+  'alias_in_path':
+    'An alias is not a path segment. The alias namespace and the path\n' +
+    'namespace are disjoint, so `$.%foo` is refused at any depth: an\n' +
+    'alias is reached by writing `%foo` and only that.' +
+    '\n \nExamples:\n' +
+    '  %port = min(1)   -> declared;\n' +
+    '  listen: %port    -> the alias, reached by its own name;\n' +
+    '  listen: $.%port  -> nil  # Not a path segment.',
+
+  'alias_not_toplevel':
+    'An alias declaration sits at the root of the document. A nested\n' +
+    '`x: { %a = 1 }` is refused because `%a` resolves from the root: the\n' +
+    'declaration would be erased from the output, being a declaration,\n' +
+    'and still unreachable by any reference, not being at the root.\n' +
+    'Where the declaration LANDS decides this, not where it was written,\n' +
+    'so an include spliced at the root may declare one and an include\n' +
+    'taken as a value may not.',
+
+  'patch_assignment':
+    'This is not a <path>=<value> assignment. The path is what stands\n' +
+    'before the first `=` and the value is what follows it, so an\n' +
+    'argument carrying only one of them cannot be applied.',
+
+  // Reference: a name or path resolves to nothing editable
+  'multisource_not_found':
+    'The source named here was not found. For a file include, check the\n' +
+    'path as written, which is resolved against the document that writes\n' +
+    'it; for an `aontu:` name the message lists the models the language\n' +
+    'supplies, and a name outside that set is never looked for on disk.',
+
+  'patch_ambiguous':
+    'More than one statement pins this path, so there is no single\n' +
+    'literal to rewrite in place. The sites on the finding are all of\n' +
+    'them: edit the one that should change, or narrow the overlay so\n' +
+    'that only one pins the path.',
+
+  'patch_not_editable':
+    'There is no literal at this path to rewrite in place. The value is\n' +
+    'reached through a reference, arrives only once the overlay loads\n' +
+    'another document, or is produced rather than written -- the finding\n' +
+    'names which, and the sites say where it does come from. Edit there,\n' +
+    'or let set append instead of asking for --in-place.',
+
+  'var': 'This variable has no value, and an unresolved variable cannot\n' +
+    'be generated. A `$name` variable is supplied by the CALLER, never\n' +
+    'by the document: bind it through `ctx.vars` in TypeScript or pass\n' +
+    'it to `UnifyVars` in Go. If the value was meant to come from the\n' +
+    'document, a path reference ($.a.b) or an alias (%name) is what\n' +
+    'reads one.',
+
+  // Internal: the engine surprised itself
+  'patch_span_mismatch':
+    'The overlay does not hold the text the site says is there, so the\n' +
+    'span cannot be verified and the edit is refused rather than\n' +
+    'written: splicing without verifying the span corrupts the file.\n' +
+    'The span is checked against the very text it was derived from, so\n' +
+    'a document changing underneath cannot produce this. It is an\n' +
+    'engine provenance defect -- the one refusal classed internal for\n' +
+    'that reason -- and worth reporting.',
+
+  'unify_failed':
+    'The document does not evaluate, and the failure carried no more\n' +
+    'specific code. This stands in where a nil reaches the report\n' +
+    'without one, so the other findings in the same run are what say\n' +
+    'what actually went wrong.',
+
+  'unknown_op':
+    'The parser produced an operator form the value builder does not\n' +
+    'recognise. Reaching this is an engine defect rather than a fault\n' +
+    'in the document.',
+
+  // Compat: the subsumption and outcome vocabulary
+  'compat_narrowed':
+    'The general value does not admit the specific one: the specific\n' +
+    'side allows something the general side refuses -- a wider kind, a\n' +
+    'wider residual, or a value the general residual excludes. A\n' +
+    'document the specific side accepts can therefore fail against the\n' +
+    'general one. Which document is on which side is the comparison\'s:\n' +
+    'subsume takes them in the order given, and breaking decides by its\n' +
+    'mode.',
+
+  'compat_required_added':
+    'The general value requires this key and the specific value does\n' +
+    'not, either because the key is absent there or because it is\n' +
+    'optional there. Instances without the key are admitted where the\n' +
+    'general side refuses them.',
+
+  'compat_default_changed':
+    'The general and specific values have different effective defaults,\n' +
+    'so a document resolving to one of them against one side resolves\n' +
+    'to the other -- or stops resolving -- against the other, with\n' +
+    'nothing in the document itself changing. Which document is on\n' +
+    'which side is the comparison\'s own.',
+
+  'compat_marks_changed':
+    'The marks on this value differ between the general and specific\n' +
+    'sides: one carries type() or hide() where the other does not. A\n' +
+    'mark changes what the value contributes to a generated document,\n' +
+    'so the two are not the same declaration even where what they admit\n' +
+    'agrees. Reported under the gen profile, which is the one that\n' +
+    'compares them.',
+
+  'compat_outcome_changed':
+    'This path resolved to one value before and resolves to a different\n' +
+    'one now. Nothing refuses, so the change is silent: a consumer\n' +
+    'reading this path gets a new answer with no error to say so.',
+
+  'compat_undetermined':
+    'This path resolved to a value before and nothing resolves it now.\n' +
+    'The declaration became incomplete rather than wrong, so a consumer\n' +
+    'that read a value here reads nothing.',
+
+  'deprecated':
+    'This value is marked deprecated. The record carries the author\'s\n' +
+    'message, and where they supplied them, what to use instead and the\n' +
+    'version it was deprecated in. Nothing refuses: a deprecation is a\n' +
+    'warning and never changes a verdict.',
+
+  'pref_not_instance':
+    'The preferred value is not repeated among the remaining\n' +
+    'alternatives of its disjunction. Nothing is refused and the\n' +
+    'preference still holds -- the default stays admitted, and\n' +
+    'generation selects it -- so this is ADVISORY. It catches the typo\n' +
+    'where a default was meant to name one of the alternatives beside\n' +
+    'it and names something else instead.',
+
+  'sub_unresolved':
+    'An unresolved value has no admitted set to compare. Either a\n' +
+    'residue is still standing here, or the two sides are value formers\n' +
+    'no comparison rule covers, so the answer is undecided rather than\n' +
+    'yes or no.',
+
+  'sub_evaluate_only':
+    'An evaluate-only check makes the admitted set opaque. must() is\n' +
+    'checked by running it and never by reasoning about what it admits,\n' +
+    'so a value carrying one cannot be compared and the answer is\n' +
+    'undecided rather than yes or no.',
+
+  'sub_disjunct_distribution':
+    'An alternative is not admitted member by member, and no concrete\n' +
+    'value settles it either way. Comparing a disjunction member-wise\n' +
+    'is sound when it answers yes; a no needs a counterexample, and\n' +
+    'there is none here, so the answer is undecided.',
+
+  'sub_default_indeterminate':
+    'The effective default is not a single value, because preferences\n' +
+    'of equal rank disagree. Nothing can be decided about the default\n' +
+    'until one of them is ranked (`**x`) or they are made to agree, so\n' +
+    'the answer is undecided rather than yes or no.',
+
+  'sub_path_dependent_spread':
+    'A spread template that depends on where it lands cannot be\n' +
+    'compared structurally. What it produces is known only once it is\n' +
+    'applied to a path, so the general and specific sides cannot be\n' +
+    'held against each other and the answer is undecided.',
+
   // Dynamic patterns (these serve as prefixes)
   'func:': 'Function error: ',
   'op:': 'Operator error: ',
@@ -780,6 +975,7 @@ const codeClasses: Record<string, string> = {
 
   // internal -- the engine reached a state it should not reach
   internal: 'internal',
+  unify_failed: 'internal',
   unify_no_res: 'internal',
   unknown_op: 'internal',
 }