aontu 0.67.0 → 0.69.0

package/src/cli.ts

@@ -5039,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 } {
@@ -5078,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)
@@ -5088,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)' : ''
 }
 
 
@@ -5138,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
@@ -5164,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
 }
 
@@ -5487,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
@@ -5504,6 +5525,7 @@ export {
   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/ctx.ts

@@ -93,7 +93,9 @@ class AontuContext {
 
   _fixroot: any
 
-  budget: { passes: number, revisits: number, depth: number }
+  budget: {
+    passes: number, revisits: number, depth: number, alias: number
+  }
 
   // The include manifest sink (G5, docs/trust.md): every include the
   // resolver reads is recorded here as { path, capability }, and
@@ -153,6 +155,7 @@ class AontuContext {
       passes: budget.passes ?? 9,
       revisits: 999,
       depth: budget.depth ?? 1000,
+      alias: budget.alias ?? 1000000,
     }
   }
 

package/src/err.ts

@@ -1,6 +1,7 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
+import { aliasPathSegment } from './aliasname'
 import { sep } from 'node:path'
 
 import { util } from '@tabnas/jsonic'
@@ -71,7 +72,10 @@ function descErr<NILS extends NilVal | NilVal[]>(
       let v1src = resolveSrc(v1, errctx)
       let v2src = resolveSrc(v2, errctx)
 
-      let path = ['$', ...err.path].filter((p: any) => null != p && '' !== p)
+      // A list index is a number here, and only a key can be an alias.
+      let path = ['$', ...err.path.map((p: any) =>
+        'string' === typeof p ? aliasPathSegment(p) : p)]
+        .filter((p: any) => null != p && '' !== p)
 
       // '$' is neither null nor '', so the filter always leaves it.
       let valpath = path.join('.')
@@ -125,6 +129,20 @@ function descErr<NILS extends NilVal | NilVal[]>(
           col: v2.site.col,
         })),
 
+        // A NAME IS WHERE THE VALUE ENTERED THIS PATH, which is not
+        // where it is written (ALIASES.0.md A-1).
+        ...[v1, v2].map((v: any) => null != v?.site?.via && errmsg({
+          color: { active: colorActive(), line: '\x1b[34m' },
+          txts: {
+            msg: 'Value arrived through ' + v.site.via.name,
+            site: ''
+          },
+          smsg: 'used ' + v.site.via.name + ' here',
+          file: resolveFile(v.site.via.url),
+          src: resolveSrc({ site: v.site.via } as any, errctx),
+          row: v.site.via.row,
+          col: v.site.via.col,
+        })),
 
       ]
         .filter((n: any) => null != n && false !== n)

package/src/format.ts

@@ -6,6 +6,7 @@ import { failureFinding } from './vet'
 import type { VetFinding } from './vet'
 import type { Resolver } from './type'
 import { desugarTemplate, resugarTemplate, templateOutputs } from './template'
+import { ALIAS_RE, EXPORT_DECL_NAME, isExportHoldKey } from './aliasname'
 
 
 const BUDGET = 80
@@ -303,6 +304,19 @@ class Reader {
       this.i += 2
       return { t: 'spread', value: this.value(), at }
     }
+    // `export({ %a })` is ONE declaration lexed as a pair.
+    if (isExportHoldKey(this.T[this.i].val) &&
+      EXPORT_DECL_NAME === this.T[this.i].src && this.atKey()) {
+      const text = EXPORT_DECL_NAME + '(' + this.T[this.i + 2].src + ')'
+      this.i += 3
+      return { t: 'atom', text, at }
+    }
+    if (this.atKey() && ALIAS_RE.test('' + this.T[this.i].src) &&
+      this.T[this.i].src === this.T[this.i + 2]?.src) {
+      const text = '' + this.T[this.i].src
+      this.i += 3
+      return { t: 'atom', text, at }
+    }
     if (this.atKey()) {
       const tok = this.T[this.i]
       const opt = '#QM' === this.name(1)

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

@@ -189,6 +189,8 @@ const hints: Record<string, string> = {
 
   elided_value: 'A key or element was written with no value after the colon. An\nelided value is a mistake in the source rather than a null: write\n`null` if that is what was meant, or supply the value.\n \nExamples:\n  a:null  -> null  # An explicit null, which is a value;\n  a:      -> nil   # ... but nothing at all is not;\n  a: b:1  -> {..}  # A colon chain is not an elision;\n  [1,]    -> [1]   # ... nor is a trailing comma.',
 
+  alias_budget: 'Alias expansion is bounded but not small: a name that names names\nexpands to the product of what they hold, so twenty shallow\ndeclarations reach a million nodes. The expanded size is counted\nbefore evaluation and refused over the budget ({budget} nodes), so\nthe document is turned away rather than run until memory is gone.\n \nExpansion terminates whatever the budget: an alias takes no\nparameters, a cycle is refused, and a file declares finitely many\nnames. The budget is about SIZE, not about termination.\n \nRaise it with trust.budget.alias where the document is trusted and\nthe machine can hold the result.',
+  reserved_key: 'The \\u0000aontu_ key prefix belongs to the engine. A document\'s key\norder, its spreads and its alias declarations are held under keys in\nthat namespace, so a source key written there would land on one of\nthem. It is refused where it stands rather than silently replacing\nwhat the parser put there. No ordinary key needs the prefix: it\nbegins with a NUL, which only an escape can spell.\n \nExamples:\n  "\\u0000aontu_order": 1  -> nil   # The namespace is the engine\'s;\n  "aontu_order": 1        -> {..}  # ... without the NUL it is a key;\n  "___merge": 1           -> {..}  # ... and so is this.',
   alias_colon: 'An alias is declared with `=`: write `%name = value`. Until 0.57.0\nthe declaration was spelled with a colon, `%name: value`, and that\nform is refused rather than read as an ordinary key -- a document\nwritten for the old spelling fails here, at the declaration, instead\nof gaining a key named `%name` and a use that resolves to nothing.\n \nExamples:\n  %u8 = integer & min(0)  -> {..}  # Declares %u8, which a: %u8 uses;\n  %u8: integer            -> nil   # The form before 0.58.0, refused;\n  "%u8": 1                -> {..}  # A quoted key is an ordinary key.',
 
   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).',
@@ -542,6 +544,228 @@ 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 written as a KEY sits at the root of the\n' +
+    'document. A nested `x: { %a = 1 }` is refused because `%a` resolves\n' +
+    'from the root: the declaration would be erased from the output,\n' +
+    'being a declaration, and still unreachable by any reference, not\n' +
+    'being at the root. Where the declaration LANDS decides this, not\n' +
+    'where it was written, so an include spliced at the root may declare\n' +
+    'one and an include taken as a value may not.\n' +
+    'To name a shape where it is used, write the declaration as a VALUE\n' +
+    'prefix instead: `x: %a = 1` is accepted at any depth, leaves the\n' +
+    'value alone, and declares `%a` for the document.',
+
+  'export_arg':
+    '`export` takes a SET OF ALIAS NAMES and nothing else: write\n' +
+    '`export({ %a, %b })`. A key already crosses a file boundary as a\n' +
+    'value, so a bare word names nothing `export` could publish, and a\n' +
+    'single name still stands in a set. The `{%}` wildcard is the\n' +
+    'importing side\'s: the publishing file chooses what it publishes.\n' +
+    ' \nExamples:\n' +
+    '  %u8 = integer\n' +
+    '  export({ %u8 })  -> published;\n' +
+    '  export({ u8 })   -> nil  # A key, not an alias;\n' +
+    '  export(%u8)      -> nil  # A set, even of one;\n' +
+    '  export({%})      -> nil  # The wildcard is the importer\'s.',
+
+  'import_not_exported':
+    'The file this name was asked of does not publish `{name}`. A name\n' +
+    'belongs to the file that declares it and crosses only where that\n' +
+    'file says so, which is what `export` is for: add the name to the\n' +
+    'other file\'s `export({ ... })`, or write the value in this one.\n' +
+    'The include still placed the file\'s values -- it is the NAME that\n' +
+    'did not cross.\n' +
+    ' \nExamples:\n' +
+    '  { %u8 } = @"types.aon"      -> bound, if types.aon exports %u8;\n' +
+    '  { %secret } = @"types.aon"  -> nil  # ... and refused if 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: ',
@@ -687,7 +911,11 @@ const codeClasses: Record<string, string> = {
   pref_implicit_bag: 'parse',
   alias_not_toplevel: 'parse',
   alias_in_path: 'parse',
+  alias_budget: 'budget',
+  reserved_key: 'parse',
   alias_colon: 'parse',
+  export_arg: 'parse',
+  import_not_exported: 'reference',
   bare_punct: 'parse',
   not_number: 'parse',
   negative: 'parse',