aontu 0.52.0 → 0.53.0

package/src/hcanon.ts

@@ -0,0 +1,169 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// The HASH FORM (G6 phase 0, docs/capability-review/g6-distribution.md):
+// exactly the unify-level canon with the additions that close its
+// semantic gaps, so that two documents with the same hash form have the
+// same meaning:
+//
+//   - a CLOSED map or list renders wrapped: close({...}), close([...])
+//     (canon drops closedness);
+//   - the type/hide MARKS render as their builtin wrappers: type(x),
+//     hide(x) (canon drops marks).
+//
+// Both additions reuse existing parseable syntax, so the hash form
+// remains valid Aontu source and round-trips:
+// hcanon(unify(parse(hcanon(v)))) == hcanon(v) is a spec-suite property
+// (test/spec/hcanon.tsv). User-facing canon is UNCHANGED — hcanon is a
+// separate rendering.
+//
+// The marks PROPAGATE to every descendant at unification (walkMark), so
+// a wrapper is emitted only where a mark STARTS: the walk carries the
+// inherited marks down and a child whose mark the parent already
+// carries renders bare. Without that, hide({a:1}) would render every
+// leaf re-wrapped — still correct, never minimal, and not what the
+// source said.
+//
+// canonHash (G6 phase 1) is the pin built on it:
+//   "aon1-" + base64url( SHA-256( UTF-8( hcanon(v) ) ) )
+// (unpadded base64url, RFC 4648 section 5). The "aon1-" scheme id
+// exists so a future semantically-stronger normal form is an upgrade,
+// not a breakage. This is a CANONICAL-TEXT hash, not a semantic
+// equivalence class: the failure direction is the safe one — a false
+// "changed" forces a needless re-review; a false "unchanged" would need
+// two hash forms with the same bytes and different meanings, which is
+// exactly the gap the close/mark wrappers exist to shut.
+
+import { createHash } from 'node:crypto'
+
+import type { Val } from './val/Val'
+
+import { cmpCodePoint } from './keyorder'
+
+
+type HMarks = {
+  type: boolean
+  hide: boolean
+}
+
+
+// One node's rendering, carrying the marks the ANCESTORS already
+// wrapped. Bags and junctions recurse structurally (their canon getters
+// render children through plain canon, which would drop a nested
+// close); everything else — scalars, kinds, funcs, refs, constraints —
+// delegates to its own canon, whose text is already in cross-port
+// parity. The non-Val arm mirrors MapVal.canon's raw-peg fallback and
+// is unreachable through an evaluated tree (direct-tested, ADR-002).
+function render(v: any, inh: HMarks): string {
+  if (true !== v?.isVal) {
+    return String(v)
+  }
+
+  const mtype = true === v.mark?.type
+  const mhide = true === v.mark?.hide
+  const inner: HMarks = {
+    type: inh.type || mtype,
+    hide: inh.hide || mhide,
+  }
+
+  let s: string
+  if (true === v.isMap) {
+    const keys = Object.keys(v.peg).sort(cmpCodePoint)
+    s = '{' +
+      (v.spread.cj ? '&:' + render(v.spread.cj, inner) +
+        (0 < keys.length ? ',' : '') : '') +
+      keys.map((k) =>
+        JSON.stringify(k) +
+        (v.optionalKeys.includes(k) ? '?' : '') +
+        ':' +
+        render(v.peg[k], inner)).join(',') +
+      '}'
+    if (true === v.closed) {
+      s = 'close(' + s + ')'
+    }
+  }
+  else if (true === v.isList) {
+    const keys = Object.keys(v.peg)
+    s = '[' +
+      (v.spread.cj ? '&:' + render(v.spread.cj, inner) +
+        (0 < keys.length ? ',' : '') : '') +
+      keys.map((k) => render(v.peg[k], inner)).join(',') +
+      ']'
+    if (true === v.closed) {
+      s = 'close(' + s + ')'
+    }
+  }
+  else if (true === v.isPref) {
+    s = '*' + render(v.peg, inner)
+  }
+  else if (true === v.isConjunct || true === v.isDisjunct) {
+    s = junctionText(v, true === v.isConjunct ? '&' : '|', inner)
+  }
+  else {
+    s = v.canon
+  }
+
+  // The IDENTITY is innermost, exactly as canon writes it (G4 phase
+  // 1). It is IN the hash — a node declared `id(svc/auth)` and the
+  // same node declared `id(svc/billing)` describe different systems,
+  // and a pin that could not tell them apart would be a pin on the
+  // shape rather than on the meaning.
+  const e = v.entity
+  if (null != e) {
+    s = 'id(' + JSON.stringify(e) + ')&' + s
+  }
+
+  if (mtype && !inh.type) {
+    s = 'type(' + s + ')'
+  }
+  if (mhide && !inh.hide) {
+    s = 'hide(' + s + ')'
+  }
+
+  // The deprecation record rides outermost, as canonRiders
+  // renders it (the wrappers are all reparseable calls, so order only
+  // has to be FIXED, and this matches the canon the G3 rows pinned).
+  const d = v.deprecation
+  if (null != d) {
+    const dkeys = Object.keys(d).sort()
+    const rec = dkeys.map((k) =>
+      JSON.stringify(k) + ':' + JSON.stringify(d[k])).join(',')
+    s = 'deprecate(' + s + ('' === rec ? '' : ',{' + rec + '}') + ')'
+  }
+
+  return s
+}
+
+
+// The JunctionVal.canon parenthesisation rule, kept: a member that is
+// itself a junction with more than one term keeps its parens so the
+// text reparses with the same structure (`(1|2)&3`, not the
+// differently-parsing `1|2&3`). Post-unification junctions are
+// flattened by norm, so no SOURCE reaches the wrapping arm -- it is
+// pinned by direct tests over constructed Vals in both ports, because
+// a hash form that could render ambiguously would be a pin that
+// silently agrees with a document it should not.
+function junctionText(v: any, sym: string, inner: HMarks): string {
+  return v.peg.map((m: any) =>
+    true === m?.isJunction && 1 < m.peg.length
+      ? '(' + render(m, inner) + ')'
+      : render(m, inner))
+    .join(sym)
+}
+
+
+// The hash form of an EVALUATED Val (unify first; parse-level canon
+// parenthesisation differs between the ports and is excluded by
+// construction — AGENTS.md).
+export function hcanon(v: Val): string {
+  return render(v, { type: false, hide: false })
+}
+
+
+// The canon-hash pin. Scoped to the module evaluated STANDALONE: its
+// own include closure resolved and unified at its own root, before any
+// consumer context — which is what makes the pin transitive (an edit
+// two includes deep changes the unified root, hence the hash).
+export function canonHash(v: Val): string {
+  return 'aon1-' +
+    createHash('sha256').update(hcanon(v), 'utf8').digest('base64url')
+}

package/src/hints.ts

@@ -33,6 +33,12 @@ const hints: Record<string, string> = {
     'This value was present after unification, and cannot be generated\n' +
     'because it is not a literal value.',
 
+  disjunct_no_gen:
+    'More than one alternative of this disjunction is still admitted, so\n' +
+    'there is no single value to generate. Supply a value that selects\n' +
+    'one alternative, or write a preference (*) to say which one holds\n' +
+    'when nothing else does.',
+
 
   // TODO: extend errors to have details so we can name the key
   mapval_required: 'This map value is required.',
@@ -72,7 +78,58 @@ const hints: Record<string, string> = {
     '  max(65535) & 99999            -> nil  # Above the bound;\n' +
     '  min(5) & max(3)               -> nil  # Empty at composition time;\n' +
     '  integer & above(1) & below(2) -> nil  # No integer in the gap;\n' +
-    '  neq(1) & 1.0                  -> 1.0  # neq excludes leaf AND value.',
+    '  neq(1) & 1.0                  -> 1.0  # neq excludes leaf AND value.\n' +
+    '  re("^a") & "abc"              -> "abc" # Patterns are unanchored.',
+
+  must:
+    'This value fails an evaluate-only check written with must().\n' +
+    'The author\'s message is: {message}' +
+    '\n \n' +
+    'must(c, msg) is Band B of the constraint algebra: the value must\n' +
+    'unify with c, but the check itself is OPAQUE to the algebra -- it\n' +
+    'never participates in emptiness or subsumption, and it never\n' +
+    'contributes to the value. It is the honest channel for a domain\n' +
+    'rule the algebra cannot reason about, which is why it carries a\n' +
+    'message of its own.' +
+    '\n \nExamples:\n' +
+    '  must("gold"|"silver","tier") & "gold" -> "gold"  # Admitted;\n' +
+    '  must("gold"|"silver","tier") & "lead" -> nil    # ... reported\n' +
+    '                                                   #     with "tier";\n' +
+    '  min(0) & must(integer,"whole") & 3    -> 3      # Bands compose.',
+
+  constraint_pattern:
+    'This re() pattern is outside the supported subset. It uses\n' +
+    '{reason}.\n' +
+    ' \n' +
+    're() accepts classical regular expressions over Unicode code\n' +
+    'points, with one meaning in both implementations:\n' +
+    ' \n' +
+    '  literals     a  \\.  \\*  \\xHH        (escape . \\ + * ? ( ) [ ] { } | ^ $ /)\n' +
+    '  classes      [abc]  [^abc]  [a-z]\n' +
+    '  abbreviations \\d \\D \\w \\W \\s \\S  and  .\n' +
+    '  repetition   *  +  ?  {n}  {n,}  {n,m}   (lazy: *? +? ??)\n' +
+    '  grouping     (...)  (?:...)      alternation  a|b\n' +
+    '  anchors      ^  $  \\A  \\z  \\b  \\B\n' +
+    ' \n' +
+    'Aontu DEFINES the abbreviations rather than inheriting either\n' +
+    'host regex engine, so they mean the same in both ports:\n' +
+    '  \\d [0-9]   \\w [0-9A-Za-z_]   \\s [ \\t\\n\\r\\f\\v]   . [^\\n]\n' +
+    'Note \\s is these six ASCII characters only -- not U+00A0.\n' +
+    ' \n' +
+    'NOT accepted, because no rewriting can make the two engines\n' +
+    'agree:\n' +
+    '  backreferences (\\1, \\k<n>) and lookaround ((?=) (?!) (?<=))\n' +
+    '  named groups, inline flags, and any (?...) but (?:\n' +
+    '  POSIX classes [[:alpha:]], \\p{...}, \\x{...}, \\u\n' +
+    '  a quantifier on a group containing a quantifier or an\n' +
+    '    alternation -- (a+)+ backtracks exponentially in one port,\n' +
+    '    so write [ab]+ rather than (?:a|b)+' +
+    '\n \nExamples:\n' +
+    '  re("^[a-z][a-z0-9-]*$")  # Fine;\n' +
+    '  re("^\\d{3}-\\d{4}$")      # Fine;\n' +
+    '  re("(?:ab)+")            # Fine (non-capturing group);\n' +
+    '  re("(?=x)y")             # Refused (lookahead);\n' +
+    '  re("(a+)+")              # Refused (nested quantifier).',
 
   budget_passes:
     'The evaluation budget of {limit} fixpoint passes was spent before\n' +
@@ -93,6 +150,44 @@ const hints: Record<string, string> = {
   // Parsing errors
   'parse_bad_src': 'Invalid source provided for parsing. The source must be a non-empty 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.',
+
+  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.',
+
+  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.',
+
+  id_name: 'The argument to id() is not an entity name. A name is one or\nmore letters, digits, `_`, `-` or `/`, and NO dots: a dot separates\nan entity name from a path inside that entity, so a dotted name\nwould be ambiguous. A `-` must be quoted, because it is not a\nbare-text character.\n \nExamples:\n  id(svc/auth)   -> id   # Letters, digits and `/` may be bare;\n  id("team-pay") -> id   # ... a `-` name must be quoted;\n  id(svc.auth)   -> nil  # ... a dot is a path separator, not a name;\n  id(1)          -> nil  # ... and a number is not a name at all.',
+
+  id_conflict: 'One value was declared to be two different entities. An id() says\nwhat a value IS, so two names on one node is a contradiction, not a\nmerge — the same kind of failure as unifying 1 with 2. Give the node\none name, or give the two names to two nodes.\n \nExamples:\n  id(a) & id(a) & {}  -> {..}  # One entity, said twice;\n  id(a) & {x:1}       -> {..}  # ... an entity with content;\n  id(a) & id(b) & {}  -> nil   # ... but a node cannot be both.',
+
+  id_spread: 'A spread template stamps one id() onto every child. `&: id(x) & …`\nsays that EVERY child of the bag is the entity `x`, and identity\nmerging would then unify all of them into one. Use a\npath-dependent name — `id(key())` — to give each child its own,\nor move the id() to the one child that has it.\n \nExamples:\n  {&: id(key()), a:{}, b:{}}  -> {..}  # A name per child;\n  {a: id(x) & {}}             -> {..}  # ... or one named child;\n  {&: id(x), a:{}, b:{}}      -> nil   # ... but not one name for all.',
+
+  refer_address: 'A refer() was given something that is not an entity address. An\naddress is an entity name, optionally followed by a dot-separated path\ninside that entity — and only a STRING can be one.\n \nExamples:\n  refer() & "svc/auth"        -> "svc/auth"  # An entity;\n  refer() & "svc/auth.port"   -> ...         # ... and a node inside it;\n  refer() & "svc/auth."       -> nil         # ... but not a trailing dot;\n  refer() & 1                 -> nil         # ... and not a number.',
+
+  refer_unresolved: 'A refer() address names no entity in this evaluation. Within one\nevaluation the document-set is fixed, so a link to nothing is an\nerror rather than something to resolve later: check the spelling, or\nadd the id() that was meant to declare it.\n \nExamples:\n  a:id(svc/x)&{} b:refer()&"svc/x"     -> "svc/x"  # Declared, so it resolves;\n  a:id(svc/x)&{p:1} b:refer()&"svc/x.p" -> "svc/x.p"  # ... and so does a node inside it;\n  b:refer()&"svc/nope"                -> nil      # ... but nothing declares this.',
+
+  pack_data: 'The first argument to pack() is not a bag. `pack` makes one child\nper child of its DATA, so the data has to have children: a list of\nnames, or a map whose keys are the names.\n \nExamples:\n  pack([a,b], {x:1})     -> {..}  # A list of names;\n  pack({a:1,b:2}, {x:1}) -> {..}  # ... or a map, keyed by its keys;\n  pack(1, {x:1})         -> nil   # ... but a scalar has no children.',
+
+  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.',
+
+  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.',
+
+  match_none: 'No pattern matched, and there is no default. `match` tries each\npattern in the order written and takes the first the value unifies\nwith; the value {value} unified with none of {tried}. Add a trailing\ndefault — the argument after the last pair — if the rest was meant\nto be allowed.\n \nExamples:\n  match(1, integer, ok)             -> "ok"   # The first pattern matches;\n  match(x, integer, ok, other)      -> "other"  # ... or the default does;\n  match(x, integer, ok)             -> nil    # ... but nothing here does.',
+
+  place_pair: 'Two placeholders met, and neither has a value to fill the other.\n`_` is a HOLE: it is filled by whatever the call is unified with, so\na call holding one needs a peer that does not. Give one side a\nvalue.\n \nExamples:\n  upper(_) & hello        -> "HELLO"  # The peer fills the hole;\n  _ + 2 & 1               -> 3        # ... whatever the call is;\n  upper(_) & lower(_)     -> nil      # ... but two holes fill nothing.',
+
+  pipe_target: 'The right-hand side of a `|>` is not a function. A pipe puts the\nvalue on its left in as the FIRST argument of the call on its\nright, so the right side has to be one: a call, or the bare name of\na built-in.\n \nExamples:\n  hello |> upper        -> "HELLO"  # A bare name is the call;\n  $.names |> pack({})   -> {..}     # ... or a call with more arguments;\n  1 |> 2                -> nil      # ... but a value is not a function.',
+
+  module_missing: 'A module import names a module that is not in this project. A\nmodule is resolved from LOCAL stores only -- `aon_vendor/` beside the\nproject\'s mod.aon, then the user cache -- because evaluation never\ntouches the network. Fetching is a separate step, and the message\nnames it.\n \nExamples:\n  @"corp.example/s@1"        -> nil  # Not fetched: run aontu mod get;\n  @"./local.aon"             -> {..} # ... a local path is not a module;\n  @"corp.example/s@1#aon1-…" -> {..} # ... and a pin does not fetch it either.',
+
+  module_integrity: 'A module resolved locally does not have the MEANING it was pinned\nto. The pin is a canon-hash -- the hash of the module unified\nstandalone -- so it survives comments, formatting and refactoring and\nbreaks on any semantic change in the module\'s transitive closure.\nVerification is always local: the registry\'s annotation is advisory.\n \nExamples:\n  @"corp.example/s@1"        -> {..} # No pin, no check;\n  @"corp.example/s@1#aon1-x" -> nil  # ... a pin that disagrees refuses;\n  aontu hash <file>                  # ... and this is what it should be.',
+
+  module_depth: 'Module verification nested too deep. A pinned module is checked by\nEVALUATING it, and that evaluation resolves the module\'s own imports\n-- so a vendor tree that leads back to itself would recurse until the\nhost ran out of stack. The bound makes that a stated refusal rather\nthan a crash whose verdict depends on the machine.\n \nExamples:\n  @"corp.example/s@1"   -> {..}  # Ordinary nesting is far below it;\n  aontu mod vendor              # ... rebuild a vendor tree that loops;\n  aontu hash <file>             # ... and check what it hashes to.',
+
   // Unification errors
   'unify_no_src': 'No source provided for unification. Cannot unify without source values.',
   'unify_no_res': 'Unification produced no result. The values could not be unified.',
@@ -142,12 +237,85 @@ const hints: Record<string, string> = {
     '  1.0 + 0d2   -> nil    # float with biginteger;\n' +
     '  0d0.5 + 1.0 -> nil    # ... and the same the other way round.',
 
+  pick_key:
+    'A child of this bag has no key `{key}` to pick. Projection\n' +
+    'refuses rather than skipping: a shorter list would make the\n' +
+    'aggregate over it total a DIFFERENT set of records than the one\n' +
+    'the author named, which is the failure an aggregate exists to\n' +
+    'prevent. Give every child the key, or filter the bag first.' +
+    '\n \nExamples:\n' +
+    '  pick([{a:1},{a:2}], a)   -> [1,2]  # Every child has it;\n' +
+    '  pick([{a:1},{b:2}], a)   -> nil    # ... the second does not;\n' +
+    '  pick([[9],[8]], 0)       -> [9,8]  # A list child takes an index.',
+
+  aggregate_data:
+    'This aggregate needs a BAG to fold: a list or a map. `sum`,\n' +
+    '`least` and `greatest` walk the children of the value they are\n' +
+    'given, so a scalar, a kind or an unresolved reference is not\n' +
+    'something they can total.' +
+    '\n \nExamples:\n' +
+    '  sum([1,2,3])       -> 6    # A list;\n' +
+    '  sum({a:1,b:2})     -> 3    # ... or a map, by sorted key;\n' +
+    '  sum(3)             -> nil  # A scalar is not a bag;\n' +
+    '  x:[1,2] sum($.x)   -> 3    # A reference to one is fine.',
+
+  aggregate_empty:
+    'There is no least or greatest element of an EMPTY bag. Addition\n' +
+    'has an identity, so `sum([])` is 0; comparison has none, and\n' +
+    'answering with a zero or an infinity would be inventing a value\n' +
+    'the data does not contain. Guard the bag, or give it a floor with\n' +
+    'a written element.' +
+    '\n \nExamples:\n' +
+    '  sum([])            -> 0    # Zero IS the empty sum;\n' +
+    '  least([])          -> nil  # ... but nothing is the least of none;\n' +
+    '  least([0])         -> 0    # A written floor answers.',
+
+  divide_by_zero:
+    'Division by zero. `div`, `mod` and `rem` refuse a zero divisor in\n' +
+    'every numeric leaf, including binary floats: Aontu is a JSON\n' +
+    'superset with no notation for an infinity, so there is no value\n' +
+    'the operation could answer with. A definition that divides by zero\n' +
+    'is wrong, and this says so where it is written rather than\n' +
+    'somewhere downstream.' +
+    '\n \nExamples:\n' +
+    '  div(7, 0)     -> nil  # No answer exists;\n' +
+    '  mod(7, 0)     -> nil  # ... nor for the modulus;\n' +
+    '  div(7.0, 0.0) -> nil  # ... and a float would say Infinity.',
+
+  inexact_divide:
+    'Exact decimal division is not closed: one third has no finite\n' +
+    'decimal form, so `div`, `mod` and `rem` refuse a `0d` operand\n' +
+    'rather than round one. Two ways out. Scale to integers and divide\n' +
+    'those -- which is the convention money should be carried in\n' +
+    'anyway, minor units as an integer -- or use binary floats if an\n' +
+    'approximation is acceptable here.' +
+    '\n \nExamples:\n' +
+    '  div(0d10.0, 0d4.0) -> nil    # Refused, though this one terminates;\n' +
+    '  div(0d10, 0d4)     -> 0d2    # A biginteger is not a decimal;\n' +
+    '  div(1000, 4)       -> 250    # Integer cents, exact;\n' +
+    '  div(10.0, 4.0)     -> 2.5    # ... or binary64, approximate;\n' +
+    '  mul(0d10.0, 0d4.0) -> 0d40.0 # Multiplication IS exact and stays.',
+
+  float_overflow:
+    'This result is not a finite binary64 number, so it is not a value\n' +
+    'Aontu can carry. There is no notation for an infinity or a NaN in\n' +
+    'a JSON superset, and no JSON a generator could emit for one, so\n' +
+    'the operation is refused where it is written rather than escaping\n' +
+    'as an internal error or an unserialisable value.\n' +
+    'Use the exact leaves (`0d`) if the magnitude is real rather than\n' +
+    'an accident.' +
+    '\n \nExamples:\n' +
+    '  1.0e308 + 1.0e308 -> nil  # Overflows binary64;\n' +
+    '  mul(1.0e200, 1.0e200) -> nil  # ... and so does this;\n' +
+    '  0d1e308 + 0d1e308 -> 0d2e308  # Exact, and well inside budget.',
+
   inexact_integer_sum:
     'The `integer` leaf holds a value only when it is integral, within\n' +
-    'the int64 range, and exactly representable in binary64. This sum\n' +
-    'is not: {sum}.\n' +
-    'Aontu adds integers exactly and refuses to store a rounded answer\n' +
-    '-- write `0d<digits>` for an exact integer beyond that window.' +
+    'the int64 range, and exactly representable in binary64. This\n' +
+    'result is not: {sum}.\n' +
+    'Aontu computes integers exactly and refuses to store a rounded\n' +
+    'answer -- write `0d<digits>` for an exact integer beyond that\n' +
+    'window.' +
     '\n \nExamples:\n' +
     '  4503599627370496 + 4503599627370496 -> 9007199254740992  # Exact;\n' +
     '  4503599627370496 + 4503599627370497 -> nil    # 2^53+1 is not;\n' +
@@ -236,6 +404,95 @@ const codeClasses: Record<string, string> = {
   syntax: 'parse',
   parse_unknown: 'parse',
   parse_bad_src: 'parse',
+  merge_conflict: 'parse',
+  include_denied: 'parse',
+
+  // G3 -- the subsumption query's report vocabulary (class compat):
+  // the compat_* codes are its findings, the sub_* codes its undecided
+  // reasons. Report-layer codes: no NilVal ever carries one, so they
+  // have no hint text.
+  compat_narrowed: 'compat',
+  compat_required_added: 'compat',
+  compat_default_changed: 'compat',
+  compat_marks_changed: 'compat',
+  sub_unresolved: 'compat',
+  sub_disjunct_distribution: 'compat',
+  sub_path_dependent_spread: 'compat',
+  sub_evaluate_only: 'compat',
+  sub_default_indeterminate: 'compat',
+  deprecated: 'compat',
+  pref_not_instance: 'compat',
+
+  // G7 phase 5 -- the overlay patch verb: an assignment that is not
+  // <path>=<value>. Class `parse`, because what is malformed IS
+  // source text; report-layer, so no NilVal carries it.
+  patch_assignment: 'parse',
+  patch_not_editable: 'reference',
+  patch_ambiguous: 'reference',
+  patch_span_mismatch: 'internal',
+
+  // G4 phase 1 -- the identity mark: a name that is not one, and two
+  // different names on one node. `id_name` is a parse-class refusal
+  // of the argument; `id_conflict` is a conflict like any other
+  // failed meet, because that is exactly what it is.
+  id_name: 'parse',
+  id_conflict: 'conflict',
+
+  // Clearing rule 3: a constant `id()` inside an `&:` template. Class
+  // `parse`, because what is wrong is the TEXT of the template rather
+  // than any pair of values it brought together.
+  id_spread: 'parse',
+
+  // G4 phase 2 -- the checked link: a string that is not an entity
+  // address (class `parse`, the text is wrong), and an address that
+  // names nothing in this evaluation (class `reference`, the same
+  // class as `no_path`, because it is the same kind of miss).
+  refer_address: 'parse',
+  refer_unresolved: 'reference',
+
+  // G8 phase 1 -- the generation combinators. All three are class
+  // `parse`: what is wrong is the CALL as written (data that is not a
+  // bag, a list element that is not a name), not any pair of values a
+  // meet brought together.
+  pack_data: 'parse',
+  pack_key: 'parse',
+  each_data: 'parse',
+
+  // G8 phase 2 -- selection. `filter_data` is class `parse` for the
+  // same reason `pack_data` is: the CALL names something with no
+  // children. `match_none` is class `conflict` -- the value and every
+  // pattern written for it disagreed, which is an ordinary failed
+  // meet, reported once for the whole form.
+  filter_data: 'parse',
+  match_none: 'conflict',
+
+  // G8 phase 3 -- the placeholder. Class `conflict`: two values met
+  // and neither could answer for the other, which is what every
+  // conflict is.
+  place_pair: 'conflict',
+
+  // G8 phase 4 -- the pipe. Class `parse`: a pipe is sugar resolved
+  // while reading the source, so a pipe into something that is not a
+  // call is wrong in the TEXT and no later pass can repair it.
+  pipe_target: 'parse',
+
+  // G6 phase 2 -- modules. Both are class `parse`: a module import is
+  // resolved while the source is READ, and neither a module that is
+  // absent nor one whose meaning disagrees with its pin can be
+  // repaired by any later pass.
+  module_missing: 'parse',
+  module_integrity: 'parse',
+  module_depth: 'budget',
+
+  // G4 phase 5 -- the relation graph checks. Class `conflict`: the
+  // model contradicts a property it declared for itself. Report-layer,
+  // so no NilVal carries either -- both are global and non-monotone,
+  // and a lattice citizen may not be falsified by more information.
+  relation_cycle: 'conflict',
+  relation_inverse_missing: 'conflict',
+  relation_target_unmet: 'conflict',
+  func_arity: 'parse',
+  elided_value: 'parse',
   unify_no_src: 'parse',
   incomplete_expression: 'parse',
   not_number: 'parse',
@@ -246,6 +503,8 @@ const codeClasses: Record<string, string> = {
   // (constraint covers the whole algebra family: membership failure,
   // empty meets at composition time, and domain/kind mixing.)
   constraint: 'conflict',
+  must: 'conflict',
+  constraint_pattern: 'conflict',
   scalar_value: 'conflict',
   scalar_kind: 'conflict',
   no_scalar_unify: 'conflict',
@@ -261,6 +520,12 @@ const codeClasses: Record<string, string> = {
   '|:empty-dist': 'conflict',
   exact_float_mix: 'conflict',
   inexact_integer_sum: 'conflict',
+  pick_key: 'conflict',
+  aggregate_data: 'conflict',
+  aggregate_empty: 'conflict',
+  divide_by_zero: 'conflict',
+  inexact_divide: 'conflict',
+  float_overflow: 'conflict',
   decimal_budget: 'conflict',
   lossy_integer_literal: 'conflict',
   arg: 'conflict',
@@ -279,6 +544,7 @@ const codeClasses: Record<string, string> = {
 
   // incomplete -- residue: the truth requires more than was supplied
   no_gen: 'incomplete',
+  disjunct_no_gen: 'incomplete',
   conjunct: 'incomplete',
   mapval_no_gen: 'incomplete',
   mapval_required: 'incomplete',