aontu 0.62.0 → 0.63.0

package/src/graph.ts

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

package/src/hcanon.ts

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

package/src/helpdoc.ts

@@ -41,7 +41,7 @@ const HELPDOC: HelpTopic[] = [
     "topic": "grammar",
     "summary": "the published ABNF, for a parser or a constrained decoder",
     "source": "grammar/aontu.abnf",
-    "text": "; Aontu --- published grammar (ABNF, RFC 5234 + RFC 7405).\n;\n; The same language as grammar/aontu.gbnf, rule for rule and name for\n; name, in the notation an RFC reader expects. The GBNF form is for a\n; constrained decoder; THIS form is for a person, and for the railroad\n; diagram in the language reference, which is generated from this file\n; (ts/scripts/figures.cjs).\n;\n; It covers the DOCUMENTED EMISSION SURFACE: what a model should be\n; allowed to write, which is a superset of JSON plus the operators,\n; constraints and marks the language's own canonical form emits. It is\n; CONSERVATIVE BY CONSTRUCTION --- it may accept less than the parser\n; does, never more. The same two deliberate exclusions the GBNF has:\n;\n;   - `@\"...\"` includes. A generated document should describe values,\n;     not reach for files.\n;   - Unquoted keys and the other spellings the parser tolerates.\n;     Canon quotes every key, and one spelling is what a grammar is\n;     for.\n;\n; TWO NOTATION CHOICES worth stating, because both are load-bearing.\n;\n; EVERY LITERAL IS CASE-SENSITIVE, spelled `%s\"...\"` (RFC 7405). A\n; plain `\"...\"` is case-INSENSITIVE in RFC 5234, and Aontu is not:\n; `TRUE` is a bare word and `true` is a boolean. The reader in\n; ts/scripts/abnf.cjs refuses a bare quoted string rather than guess\n; which was meant.\n;\n; ALTERNATION IS ORDERED. RFC 5234's `/` is formally unordered, and\n; the consumers of this file (a PEG-style matcher here, a railroad\n; renderer) take the first branch that matches. Where one spelling is\n; a prefix of another the longer comes first --- `exact` before\n; `number`, `refer` before `rem` before `re`, `biginteger` before\n; `boolean` --- so the ordered reading and the unordered one accept\n; the same language. ts/test/grammar.test.ts holds this file to the\n; whole canon corpus of test/spec/*.tsv, which is what proves it.\n\nroot      = ws value ws\n\n; No pipe. `|>` was parse-time sugar; it was removed, `x |> f(a)`\n; being written `f(x, a)`.\nvalue     = disjunct\n\ndisjunct  = conjunct *( ws %s\"|\" ws conjunct )\n\nconjunct  = prefixed *( ws %s\"&\" ws prefixed )\n\n; A preference marks the alternative a generation picks.\nprefixed  = %s\"*\" ws prefixed / sum\n\nsum       = atom *( ws %s\"+\" ws atom )\n\natom      = map\n          / list\n          / func\n          / ref\n          / kind\n          / place\n          / scalar\n          / %s\"(\" ws value ws %s\")\"\n\nmap       = %s\"{\" ws [ entry *( ws %s\",\" ws entry ) ws ] %s\"}\"\n\nentry     = spread / pair\n\n; The template every key of the bag must also satisfy.\nspread    = %s\"&\" ws %s\":\" ws value\n\npair      = string ws [ %s\"?\" ] ws %s\":\" ws value\n\n; A list ELEMENT is a value, not a pair --- only the template is keyed.\nlist      = %s\"[\" ws [ element *( ws %s\",\" ws element ) ws ] %s\"]\"\n\nelement   = spread / value\n\n; The builtins, applied. The name set is closed on purpose: an unknown\n; function is a parse-time error in the engine, so a grammar that\n; allowed any name would over-approximate.\nfunc      = name %s\"(\" ws [ value *( ws %s\",\" ws value ) ws ] %s\")\"\n\n; ORDER MATTERS where one name is a prefix of another: `refer` is\n; listed before `re`, and `rem` before `re` as well.\nname      = %s\"above\" / %s\"acyclic\" / %s\"add\" / %s\"below\" / %s\"close\"\n          / %s\"copy\" / %s\"deprecate\" / %s\"div\"\n          / %s\"each\" / %s\"emit\" / %s\"esc\" / %s\"filter\" / %s\"greatest\"\n          / %s\"hide\"\n          / %s\"inverse\" / %s\"join\" / %s\"key\" / %s\"least\"\n          / %s\"length\" / %s\"list\" / %s\"lower\" / %s\"map\" / %s\"match\"\n          / %s\"max\" / %s\"min\" / %s\"mod\" / %s\"move\"\n          / %s\"mul\" / %s\"must\"\n          / %s\"neq\"\n          / %s\"open\" / %s\"pack\" / %s\"path\" / %s\"pick\" / %s\"pref\"\n          / %s\"refer\" / %s\"rel\" / %s\"rem\" / %s\"rep\" / %s\"re\" / %s\"split\"\n          / %s\"super\"\n          / %s\"sub\" / %s\"sum\"\n          / %s\"type\"\n          / %s\"unique\" / %s\"upper\" / %s\"usc\"\n\n; A path reference, absolute from the document root. At least one\n; segment: a bare `$` is an incomplete expression, not a reference.\n; A RELATIVE reference has no `$`: `.n` names a sibling, resolved\n; against the enclosing map rather than the document root. Canon emits\n; one wherever a spread template survives unresolved, so a grammar\n; without it cannot parse this engine's own output. No conflict with\n; `number`: a numeric literal always starts with a digit or `-`.\nref       = %s\"$\" 1*( %s\".\" segment ) / 1*( %s\".\" segment )\n\n; No `-`: it is not a bare-text character (test/spec/op-chars.tsv pins\n; `a:6-2` as a parse error), so admitting it would over-approximate.\nsegment   = 1*( ALPHA / DIGIT / %s\"_\" )\n\n; The placeholder: a hole a call is filled through. BARE only --- `\"_\"`\n; is an ordinary string, and a longer bare word containing it is\n; ordinary text.\nplace     = %s\"_\"\n\n; `biginteger` before `bigdecimal` is not required (they differ at the\n; fourth character), but `biginteger` before `boolean` is: see the\n; ordered-alternation note above.\nkind      = %s\"biginteger\" / %s\"bigdecimal\" / %s\"boolean\" / %s\"float\"\n          / %s\"integer\" / %s\"number\" / %s\"string\" / %s\"top\" / %s\"nil\"\n\n; `exact` before `number`, or `0d5` would match `number` as the single\n; digit `0` and leave `d5` unconsumed.\nscalar    = string / exact / number / %s\"true\" / %s\"false\" / %s\"null\"\n\nstring    = DQUOTE *char DQUOTE\n\nchar      = unescaped / %x5C escape\n\n; Every code point but the quote and the backslash, which is what the\n; GBNF's `[^\"\\\\]` says. Control characters included: canon writes them\n; escaped, and a grammar that refused them would refuse less than the\n; parser accepts in the one direction this file may not.\nunescaped = %x00-21 / %x23-5B / %x5D-10FFFF\n\nescape    = DQUOTE / %x5C / %s\"/\" / %s\"b\" / %s\"f\" / %s\"n\" / %s\"r\"\n          / %s\"t\" / %s\"u\" hex hex hex hex\n\nhex       = DIGIT / %x41-46 / %x61-66\n\n; The exact leaves: arbitrary precision, spelled with the 0d marker.\nexact     = [ %s\"-\" ] %s\"0d\" digits [ %s\".\" digits ] [ exponent ]\n\nnumber    = [ %s\"-\" ] digits [ %s\".\" digits ] [ exponent ]\n\nexponent  = ( %s\"e\" / %s\"E\" ) [ %s\"-\" / %s\"+\" ] digits\n\ndigits    = 1*DIGIT\n\nws        = *( %x20 / %x09 / %x0A / %x0D )\n\n; RFC 5234's core rules, written out so this file stands alone.\nALPHA     = %x41-5A / %x61-7A\nDIGIT     = %x30-39\nDQUOTE    = %x22\n"
+    "text": "; Aontu --- published grammar (ABNF, RFC 5234 + RFC 7405).\n;\n; The same language as grammar/aontu.gbnf, rule for rule and name for\n; name, in the notation an RFC reader expects. The GBNF form is for a\n; constrained decoder; THIS form is for a person, and for the railroad\n; diagram in the language reference, which is generated from this file\n; (ts/scripts/figures.cjs).\n;\n; It covers the DOCUMENTED EMISSION SURFACE: what a model should be\n; allowed to write, which is a superset of JSON plus the operators,\n; constraints and marks the language's own canonical form emits. It is\n; CONSERVATIVE BY CONSTRUCTION --- it may accept less than the parser\n; does, never more. The same two deliberate exclusions the GBNF has:\n;\n;   - `@\"...\"` includes. A generated document should describe values,\n;     not reach for files.\n;   - Unquoted keys and the other spellings the parser tolerates.\n;     Canon quotes every key, and one spelling is what a grammar is\n;     for.\n;\n; TWO NOTATION CHOICES worth stating, because both are load-bearing.\n;\n; EVERY LITERAL IS CASE-SENSITIVE, spelled `%s\"...\"` (RFC 7405). A\n; plain `\"...\"` is case-INSENSITIVE in RFC 5234, and Aontu is not:\n; `TRUE` is a bare word and `true` is a boolean. The reader in\n; ts/scripts/abnf.cjs refuses a bare quoted string rather than guess\n; which was meant.\n;\n; ALTERNATION IS ORDERED. RFC 5234's `/` is formally unordered, and\n; the consumers of this file (a PEG-style matcher here, a railroad\n; renderer) take the first branch that matches. Where one spelling is\n; a prefix of another the longer comes first --- `exact` before\n; `number`, `refer` before `rem` before `re`, `biginteger` before\n; `boolean` --- so the ordered reading and the unordered one accept\n; the same language. ts/test/grammar.test.ts holds this file to the\n; whole canon corpus of test/spec/*.tsv, which is what proves it.\n\nroot      = ws value ws\n\n; No pipe. `|>` was parse-time sugar; it was removed, `x |> f(a)`\n; being written `f(x, a)`.\nvalue     = disjunct\n\ndisjunct  = conjunct *( ws %s\"|\" ws conjunct )\n\nconjunct  = prefixed *( ws %s\"&\" ws prefixed )\n\n; A preference marks the alternative a generation picks.\nprefixed  = %s\"*\" ws prefixed / sum\n\nsum       = atom *( ws %s\"+\" ws atom )\n\natom      = map\n          / list\n          / func\n          / ref\n          / kind\n          / place\n          / scalar\n          / %s\"(\" ws value ws %s\")\"\n\nmap       = %s\"{\" ws [ entry *( ws %s\",\" ws entry ) ws ] %s\"}\"\n\nentry     = spread / pair\n\n; The template every key of the bag must also satisfy.\nspread    = %s\"&\" ws %s\":\" ws value\n\npair      = string ws [ %s\"?\" ] ws %s\":\" ws value\n\n; A list ELEMENT is a value, not a pair --- only the template is keyed.\nlist      = %s\"[\" ws [ element *( ws %s\",\" ws element ) ws ] %s\"]\"\n\nelement   = spread / value\n\n; The builtins, applied. The name set is closed on purpose: an unknown\n; function is a parse-time error in the engine, so a grammar that\n; allowed any name would over-approximate.\nfunc      = name %s\"(\" ws [ value *( ws %s\",\" ws value ) ws ] %s\")\"\n\n; ORDER MATTERS where one name is a prefix of another: `refer` is\n; listed before `re`, and `rem` before `re` as well.\nname      = %s\"abnf\" / %s\"above\" / %s\"acyclic\" / %s\"add\" / %s\"below\" / %s\"close\"\n          / %s\"copyfiles\" / %s\"copy\" / %s\"deprecate\" / %s\"div\"\n          / %s\"each\" / %s\"emit\" / %s\"esc\" / %s\"filter\" / %s\"greatest\"\n          / %s\"hide\"\n          / %s\"inverse\" / %s\"join\" / %s\"key\" / %s\"least\"\n          / %s\"length\" / %s\"listitems\" / %s\"list\" / %s\"lower\" / %s\"map\" / %s\"match\"\n          / %s\"maybe\" / %s\"max\" / %s\"min\" / %s\"mod\" / %s\"move\"\n          / %s\"mul\" / %s\"must\"\n          / %s\"neq\"\n          / %s\"open\" / %s\"pack\" / %s\"parse\" / %s\"path\" / %s\"pick\" / %s\"pref\"\n          / %s\"refer\" / %s\"rel\" / %s\"rem\" / %s\"rep\" / %s\"re\" / %s\"sort\" / %s\"split\"\n          / %s\"super\"\n          / %s\"content\" / %s\"file\" / %s\"folder\" / %s\"fragment\" / %s\"inject\"\n          / %s\"line\" / %s\"nom\" / %s\"project\" / %s\"slot\" / %s\"translate\"\n          / %s\"sub\" / %s\"sum\"\n          / %s\"type\"\n          / %s\"unique\" / %s\"upper\" / %s\"usc\"\n\n; A path reference, absolute from the document root. At least one\n; segment: a bare `$` is an incomplete expression, not a reference.\n; A RELATIVE reference has no `$`: `.n` names a sibling, resolved\n; against the enclosing map rather than the document root. Canon emits\n; one wherever a spread template survives unresolved, so a grammar\n; without it cannot parse this engine's own output. No conflict with\n; `number`: a numeric literal always starts with a digit or `-`.\nref       = %s\"$\" 1*( %s\".\" segment ) / 1*( %s\".\" segment )\n\n; No `-`: it is not a bare-text character (test/spec/op-chars.tsv pins\n; `a:6-2` as a parse error), so admitting it would over-approximate.\nsegment   = 1*( ALPHA / DIGIT / %s\"_\" )\n\n; The placeholder: a hole a call is filled through. BARE only --- `\"_\"`\n; is an ordinary string, and a longer bare word containing it is\n; ordinary text.\nplace     = %s\"_\"\n\n; `biginteger` before `bigdecimal` is not required (they differ at the\n; fourth character), but `biginteger` before `boolean` is: see the\n; ordered-alternation note above.\nkind      = %s\"biginteger\" / %s\"bigdecimal\" / %s\"boolean\" / %s\"float\"\n          / %s\"integer\" / %s\"number\" / %s\"string\" / %s\"top\" / %s\"nil\"\n\n; `exact` before `number`, or `0d5` would match `number` as the single\n; digit `0` and leave `d5` unconsumed.\nscalar    = string / exact / number / %s\"true\" / %s\"false\" / %s\"null\"\n\nstring    = DQUOTE *char DQUOTE\n\nchar      = unescaped / %x5C escape\n\n; Every code point but the quote and the backslash, which is what the\n; GBNF's `[^\"\\\\]` says. Control characters included: canon writes them\n; escaped, and a grammar that refused them would refuse less than the\n; parser accepts in the one direction this file may not.\nunescaped = %x00-21 / %x23-5B / %x5D-10FFFF\n\nescape    = DQUOTE / %x5C / %s\"/\" / %s\"b\" / %s\"f\" / %s\"n\" / %s\"r\"\n          / %s\"t\" / %s\"u\" hex hex hex hex\n\nhex       = DIGIT / %x41-46 / %x61-66\n\n; The exact leaves: arbitrary precision, spelled with the 0d marker.\nexact     = [ %s\"-\" ] %s\"0d\" digits [ %s\".\" digits ] [ exponent ]\n\nnumber    = [ %s\"-\" ] digits [ %s\".\" digits ] [ exponent ]\n\nexponent  = ( %s\"e\" / %s\"E\" ) [ %s\"-\" / %s\"+\" ] digits\n\ndigits    = 1*DIGIT\n\nws        = *( %x20 / %x09 / %x0A / %x0D )\n\n; RFC 5234's core rules, written out so this file stands alone.\nALPHA     = %x41-5A / %x61-7A\nDIGIT     = %x30-39\nDQUOTE    = %x22\n"
   }
 ]
 

package/src/hints.ts

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