aontu 0.53.0 → 0.55.0

package/src/err.ts

@@ -1,6 +1,8 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
+import { sep } from 'node:path'
+
 import { util } from '@tabnas/jsonic'
 
 import { Val, ErrContext } from './type'
@@ -180,7 +182,12 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
 function resolveFile(url: string | undefined) {
   const cwd = process.cwd()
-  let out = url?.replace(cwd + '/', '') ?? '<no-file>'
+  // The PLATFORM'S separator, not '/': a hardcoded slash never matched
+  // a Windows cwd, so every Windows report named the absolute path
+  // where the POSIX report (and the Go CLI, which prints the entry as
+  // typed) named `clash.aon` -- caught by the docs transcript for
+  // reading a conflict error, which pins the relative spelling.
+  let out = url?.replace(cwd + sep, '') ?? '<no-file>'
   out = out === cwd || '' === out ? '<no-file>' : out
   return out
 }

package/src/graph.ts

@@ -1,52 +1,59 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE DERIVED STRUCTURES (G4 phase 3,
+// THE DERIVED STRUCTURE (G4 phase 3,
 // docs/capability-review/g4-identity-relations.md): an evaluated
-// document has, besides its value, a GRAPH — an entity index (id → the
-// tree paths that hold it) and an edge set (the checked links, each
-// from one entity to one address).
+// document has, besides its value, a GRAPH — the set of checked links,
+// each from one tree position to another.
 //
-// G4's deliverable is that these exist and are DETERMINISTIC. What is
-// built on them — impact analysis ("what reaches svc/auth?"),
-// reachability, context-window-sized entity 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.
+// 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'
 
 import { cmpCodePoint } from './keyorder'
 
 
-export type EntityEntry = {
-  // The id, as `id(name)` spelled it.
-  id: string
-  // Every tree path that holds this entity, in code-point order. More
-  // than one is the normal case: the merge puts the entity's value at
-  // every position that declared it.
-  paths: string[]
-}
-
 export type Edge = {
-  // The entity the link is INSIDE — the nearest identified ancestor,
-  // or '' for a link outside every entity. This is the
-  // entity/component distinction: a node without an id is a component
-  // of its nearest identified ancestor.
+  // 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 nearest map key on the way down from the entity,
-  // so a link inside a list (`dependsOn: [&: refer(), svc/auth]`) is an
-  // edge under `dependsOn` rather than under `0`.
+  // 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 = {
-  entities: EntityEntry[]
   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[]
 }
 
 
@@ -54,82 +61,125 @@ const formatPath = (path: string[]): string =>
   0 === path.length ? '$' : '$.' + path.join('.')
 
 
-// The nearest map key on the path below an entity: list indices are
-// positions within a relation, not relations of their own. Digits-only
-// segments are the indices, which is exactly how the rest of the engine
-// spells them.
-const relationKey = (tail: string[]): string => {
-  for (let i = tail.length - 1; 0 <= i; i--) {
-    if (!/^[0-9]+$/.test(tail[i])) {
-      return tail[i]
+// Digits-only segments are list indices, which is exactly how the rest
+// of the engine spells them.
+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 } => {
+  if (undefined !== relkey) {
+    for (let i = at.length - 1; 0 <= i; i--) {
+      if (at[i] === relkey) {
+        return { from: formatPath(at.slice(0, i)), key: relkey }
+      }
     }
   }
-  return ''
+  let i = at.length - 1
+  for (; 0 <= i && isIndex(at[i]); i--) { }
+  return 0 > i
+    ? { from: formatPath([]), key: relkey ?? '' }
+    : { from: formatPath(at.slice(0, i)), key: relkey ?? at[i] }
 }
 
 
-// The graph of an evaluated tree. Walks POSITIONS, not values: two
-// positions of one entity share a value object after the merge, so a
-// walk guarded by object identity would find the entity once and miss
-// every other place it is declared. The guard is therefore the
-// ancestor chain — which is what a cycle actually is.
+// 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 byId = new Map<string, string[]>()
   const edges: Edge[] = []
+  const disjunct: string[] = []
 
+  // ONE WALK, with `undecided` saying which side of ADR-007 it is on:
+  // below an unresolved disjunction every link is a position the
+  // document has not decided, and nothing there is an edge.
   const visit = (
-    node: any, path: string[], entity: string, tail: string[],
-    ancestors: Set<any>
+    node: any, path: string[], ancestors: Set<any>, hidden: boolean,
+    undecided: boolean
   ): void => {
     if (null == node || true !== node.isVal || ancestors.has(node)) {
       return
     }
 
-    let inside = entity
-    let below = tail
-    const name = node.entity
-    if (null != name) {
-      let paths = byId.get(name)
-      if (undefined === paths) {
-        paths = []
-        byId.set(name, paths)
-      }
-      paths.push(formatPath(path))
-      // A nested entity is not a component of the one above it: the
-      // key path restarts at the identified node.
-      inside = name
-      below = []
-    }
+    hidden = hidden || true === node.mark?.hide
 
     const link = node.link
     if (null != link) {
-      edges.push({
-        from: inside,
-        key: relationKey(below),
-        to: link,
-        at: formatPath(path),
-      })
+      if (undecided) {
+        disjunct.push(formatPath(path))
+      }
+      else {
+        const { from, key } = cut(path, node.relkey as string | undefined)
+        const edge: Edge = { from, key, to: link, at: formatPath(path) }
+        if (hidden) {
+          edge.hidden = true
+        }
+        edges.push(edge)
+      }
+    }
+
+    // A graph atom is TRANSPARENT here (RELATIONS P2): it carries the
+    // field's value at the field's own position, and the graph is about
+    // the value.
+    if (true === node.isGraphAtom && undefined !== node.held) {
+      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) {
+        visit(term, path, ancestors, hidden, undecided)
+      }
+      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) {
+        visit(arm, path, ancestors, hidden, true)
+      }
+      ancestors.delete(node)
     }
 
     if ((true === node.isMap || true === node.isList) && null != node.peg) {
       ancestors.add(node)
       for (const k of Object.keys(node.peg)) {
-        visit(node.peg[k], [...path, k], inside, [...below, k], ancestors)
+        visit(node.peg[k], [...path, k], ancestors, hidden, undecided)
       }
       ancestors.delete(node)
     }
   }
 
-  visit(root, [], '', [], new Set())
-
-  // DETERMINISTIC by construction, not by luck: ids in code-point
-  // order, each id's paths in code-point order, edges by the position
-  // they are written at (which is unique — one link, one place).
-  const entities: EntityEntry[] = [...byId.keys()]
-    .sort(cmpCodePoint)
-    .map((id) => ({ id, paths: (byId.get(id) as string[]).sort(cmpCodePoint) }))
+  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))
 
-  return { entities, edges }
+  if (0 < disjunct.length) {
+    return { edges, disjunct: [...new Set(disjunct)].sort(cmpCodePoint) }
+  }
+  return { edges }
 }

package/src/hcanon.ts

@@ -67,7 +67,15 @@ function render(v: any, inh: HMarks): string {
 
   let s: string
   if (true === v.isMap) {
-    const keys = Object.keys(v.peg).sort(cmpCodePoint)
+    // 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)
     s = '{' +
       (v.spread.cj ? '&:' + render(v.spread.cj, inner) +
         (0 < keys.length ? ',' : '') : '') +
@@ -102,16 +110,6 @@ function render(v: any, inh: HMarks): string {
     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 + ')'
   }

package/src/hints.ts

@@ -67,6 +67,17 @@ const hints: Record<string, string> = {
 
   unify_cycle: 'Circular reference detected during unification.',
 
+  pref_implicit_bag:
+    'A preference marks a VALUE, and a bare key is not one. Without\n' +
+    'braces the `*` took the whole implicit map as its operand, so the\n' +
+    'document became a preferred map rather than a map with a preferred\n' +
+    'entry. Brace the bag, or move the `*` onto the value it marks.' +
+    '\n \nExamples:\n' +
+    '  *a: 1        -> nil       # No braces: the `*` takes the whole map;\n' +
+    '  a: *1        -> *1        # ... the `*` belongs on the value;\n' +
+    '  *{a: 1}      -> *{"a":1}  # ... or brace the bag to prefer it whole;\n' +
+    '  *{x:1}|*{y:2} -> *{"x":1}|*{"y":2}  # which is what disjunction needs.',
+
   constraint:
     'This value does not satisfy the constraint. A constraint is the\n' +
     'meet of bound atoms (min, max, above, below) and exclusions (neq)\n' +
@@ -153,20 +164,51 @@ const hints: Record<string, string> = {
   merge_conflict: 'A version-control conflict marker was found in the source. The\nfile still holds an unresolved merge: resolve it and remove the\n`<<<<<<<`, `=======` and `>>>>>>>` lines before unifying.\n \nExamples:\n  <<<<<<< HEAD  -> nil  # A conflict marker, not a `<` operation;\n  =======       -> nil  # ... nor a chain of `=` characters;\n  >>>>>>> other -> nil  # ... nor a `>` operation.',
 
   include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"in-root.aon"    -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
+  include_extension: 'An @\"...\" include named a file the engine does not read. THE\nEXTENSION DECIDES which of two things a file is: `.aon` and\n`.aontu` are Aontu source, with the whole language in them, and\n`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,\n`.yaml`, `.yml` and `.ini` are configuration DATA, read by that\nformat\'s own parser. Anything else -- and a name with no extension\n-- is refused rather than guessed at: a guess produces a document\nthat looks right and is not.\n \nExamples:\n  a:@\"model.aon\"    -> {..}  # Aontu source;\n  a:@\"server.toml\"  -> {..}  # ... config data, read as TOML;\n  a:@\"notes.txt\"    -> nil   # ... but text is not a document;\n  a:@\"data\"         -> nil   # ... and neither is an unnamed kind.',
 
   func_arity: 'This function was called with the wrong number of arguments:\n{func} takes {want}, but was given {got}.\n \nExamples:\n  upper(\"a\")     -> \"A\"  # One argument, which is what upper takes;\n  upper(\"a\",\"b\") -> nil  # ... so two is a mistake in the source;\n  key()          -> \"\"   # key takes none, or one level count;\n  neq(1,2,3)     -> neq  # ... and neq takes one or more exclusions.',
+  func_arg: 'This argument does not fit the function\'s signature:\n \n  {sig}\n  argument {argn} (`{arg}`) was `{got}`.\n \nThe signature is the declared call surface (one line per builtin,\ntest/spec/signature.tsv); an argument slot admits a concrete value\nof its declared kind, `number` admitting every numeric leaf and\n`string` admitting a path.\n \nExamples:\n  upper("a")     -> "A"    # A string fits upper(s: string|number);\n  upper(1)       -> 1      # ... and so does a number;\n  upper(true)    -> nil    # ... but a boolean fits neither word;\n  add([1],2)     -> nil    # ... and a list is no operand.',
 
   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.',
+  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.',
+  relation_cycle: 'This relation declared acyclic(), and its edges form a cycle. The\nverdict lands at generation, where every edge is known; the error\npoints at an edge on the cycle and names the nodes it runs\nthrough, closing back on the first.\n \nExamples:\n  dependsOn: rel() & acyclic()\n  a: {dependsOn: ["$.b"]}\n  b: {dependsOn: ["$.a"]}   -> nil   # $.a -> $.b -> $.a;\n  b: {dependsOn: []}        -> {..}  # ... one edge fewer passes.',
+  relation_inverse_missing: 'This relation declared inverse(name), and an edge has no mirroring\nedge under that name: A relates to B, and B does not name A back.\nThe declaration asks for the mirror to be WRITTEN, and never writes\nit for the author -- generation is refused until the document says\nboth directions.\n \nExamples:\n  a: {dependsOn: rel() & inverse(dependedOnBy) & [b]}\n  b: {dependedOnBy: rel() & [a]}  -> {..}  # Mirrored;\n  b: {dependedOnBy: rel() & []}   -> nil   # ... and this is not.',
+  inverse_name: 'The argument to inverse() is not a relation name. The mirroring\npredicate is a D-1 name -- a letter or `_`, then letters, digits,\n`_` or `-` -- spelled bare or quoted.\n \nExamples:\n  inverse(dependedOnBy)  -> inverse  # A name;\n  inverse("dep-on")     -> inverse  # ... quoted when hyphenated;\n  inverse(1)             -> nil      # ... a number is not a name.',
+  rel_address: 'A rel() field holds tree addresses: one path value, a list of path\nvalues, or a map whose leaves are path values. A bare string is never\nan address — `path("...")` is the one conversion — and this value can\nnever be one.\n \nExamples:\n  dependsOn: rel() & [path($.ledger)]  -> {..}  # A list of addresses;\n  hostedOn: rel() & path($.bastion)    -> {..}  # ... or one;\n  dependsOn: rel() & ["$.ledger"]      -> nil   # ... a string is not a path;\n  dependsOn: rel() & [7]               -> nil   # ... and neither is 7.',
+  refer_address: 'A refer() was given something that is not a tree address. An address\nis a PATH VALUE — `path($.a.b)` from the document root, `path(.b)`\nfrom the link\'s own sibling scope — and only a path value can be one:\na bare string never is, and `path("...")` is the one conversion.\n \nExamples:\n  refer() & path($.services.auth)  -> ...   # From the root;\n  refer() & path(.auth)            -> ...   # ... or beside the link;\n  refer() & "$.services.auth"      -> nil   # ... a string is not a path;\n  refer() & 1                      -> nil   # ... and neither is a number.',
+
+  path_address: 'This is not a tree address, so it cannot be a path value. An address\nis `$.a.b` from the document root, or `.b` from the sibling scope with\none more leading dot per parent step -- the grammar path() captures.\nString text with no anchor converts as RELATIVE, and a string\nconverts ONLY through the call\'s own argument.\n \nExamples:\n  d: path("$.services.auth") -> path($.services.auth) # A converted string;\n  d: path("auth")           -> path(.auth)  # ... anchorless text is relative;\n  d: path("a..b")           -> nil   # ... but this spells nothing;\n  d: path("$")              -> nil   # ... and the root is not addressable.',
+
+  rel_unresolved: 'The address names no node in this evaluation. Every position in the\ndocument is addressable; nothing outside it is.\n \nExamples:\n  p: {}\n  q: rel() & "$.p"       -> {..}  # $.p is a node;\n  q: rel() & "$.nosuch"  -> nil   # ... $.nosuch is not.',
+  refer_unresolved: 'A refer() address names no node in this evaluation. Within one\nevaluation the document-set is fixed, so a link to nothing is an error\nrather than something to resolve later: check the spelling, or add the\nnode it was meant to reach. A relative address that climbs off the top\nof the tree lands here too.\n \nExamples:\n  a:{p:1} b:refer()&"$.a"    -> "$.a"    # $.a is a node;\n  a:{p:1} b:refer()&"$.a.p"  -> "$.a.p"  # ... and so is a node inside it;\n  b:refer()&"$.nope"         -> nil      # ... but nothing is here.',
+  view_relation_unknown: 'The relation named to the view has no edges in this document, so\nthe figure would be empty -- and an empty figure and a misspelled name are\nthe same file on disk. Check the spelling against the relations the\nnote lists, or drop the relation to draw every relation at once.',
+
+  view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
+
+  view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
+  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.',
+
+  view_rows_exceeded: 'The figure has more rows than --max-rows allows. This is a REFUSAL,\nnot a truncation: a view that quietly omits things is the failure the\nverb exists to avoid. Narrow the figure with --at or --relation, or\nraise the limit.',
+
+  view_line_break: 'A label the figure would draw holds a line terminator (U+000A, U+000D,\nU+2028 or U+2029), and a figure line cannot carry one. Label the node\nwith another field, or drop --label / --group-by.',
+
+  view_relation_ambiguous: 'The document has edges under several relations and the matrix (or the\nlayer diagram) draws exactly one. Name it with --relation; the note\nlists the relations with edges.',
 
-  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.',
+  view_sets_shape: 'The set panel reads generated values: --sets must name a map whose\nvalues each hold the --member field as a list of strings, and\n--universe a map or a list of strings. The path in the finding is the\nvalue that has another shape.',
+
+  view_sets_required: 'The set panel needs both --sets (the map whose keys are the sets) and\n--member (the field holding each set\'s members).',
+
+  view_at_required: 'The meet ladder draws the contributions at ONE path, and none was\nnamed. Pass --at with the path, as `aontu why` takes it.',
+
+  view_group_required: 'The layer diagram puts each node in the band its --group-by field\nnames, and no field was named. Pass --group-by with the field that\nholds each node\'s layer.',
+  view_document_shape: 'A view document declares each figure as a map of view options --\nthe flag names without the dashes -- and every declaration must name\nits `kind` and the `out` file it draws into. This one names an option\nthat is not one, gives a value of the wrong shape, or leaves out what\nevery declaration needs. `aontu view --help` lists the options.',
 
   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.',
 
@@ -180,8 +222,8 @@ const hints: Record<string, string> = {
 
   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_path: 'A module import is domain-shaped and carries a major, but its\npath cannot be a directory on every platform the toolchain runs on --\nso it is refused before anything is built from it. An element may not\nbe empty, may not begin or end with `.` (which is what forbids `..`),\nand may not be a reserved device name. These are Go\'s module-path\nrules, for Go\'s reason: a module path becomes a real directory.\n \nExamples:\n  @"corp.example/s@1"        -> {..} # An ordinary path is fine;\n  @"corp.example/../s@1"     -> nil  # ... `..` would escape the store;\n  @"corp.example/nul@1"      -> nil  # ... and Windows has no such file.',
   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.',
@@ -248,6 +290,22 @@ 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.',
 
+  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' +
+    'string on the left RESIDUATES on a map, a list or a null rather\n' +
+    'than refusing — so folding blindly would report the failure at\n' +
+    'generation, naming the whole call instead of the member. It is\n' +
+    'refused here, where the member can still be named. A member that\n' +
+    'is merely UNRESOLVED is a different thing: the call stays\n' +
+    'residual and generation reports it as ordinary incompleteness.' +
+    '\n \nExamples:\n' +
+    '  join([1,2], "-")        -> "1-2"  # Numbers render as digits;\n' +
+    '  join([true], ",")       -> "true" # ... so do booleans;\n' +
+    '  join([{a:1}], ",")      -> nil    # A map is not text;\n' +
+    '  join([null], ",")       -> nil    # ... and neither is null;\n' +
+    '  join(pick($.r, n), ",") -> "a,b"  # Project first.',
+
   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' +
@@ -363,8 +421,14 @@ const hints: Record<string, string> = {
   'required_listelem': 'Required list element is missing. A non-optional list element has no value.',
 
   // Junction errors (disjunction/conjection)
-  '|:empty': 'Empty disjunction. The disjunction has no valid alternatives.',
-  '|:empty-dist': 'Empty disjunction distribution. All alternatives in the disjunction are invalid.',
+  '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.',
 
   'max_depth': 'Input nesting is too deep to process safely.',
 
@@ -406,6 +470,7 @@ const codeClasses: Record<string, string> = {
   parse_bad_src: 'parse',
   merge_conflict: 'parse',
   include_denied: 'parse',
+  include_extension: 'parse',
 
   // G3 -- the subsumption query's report vocabulary (class compat):
   // the compat_* codes are its findings, the sub_* codes its undecided
@@ -431,24 +496,37 @@ const codeClasses: Record<string, string> = {
   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
+  // 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',
+  rel_unresolved: 'reference',
+
+  // The tree view (docs/design/VIEWS.0.md): a relation that draws
+  // nothing is refused rather than drawn empty. Class `reference`: a
+  // name that does not resolve.
+  view_relation_unknown: 'reference',
+  view_kind_unknown: 'reference',
+  view_profile_unknown: 'reference',
+  view_style_profile: 'reference',
+  view_style_unknown: 'reference',
+  view_rows_exceeded: 'budget',
+  view_line_break: 'parse',
+  view_relation_ambiguous: 'reference',
+  view_sets_shape: 'reference',
+  view_sets_required: 'reference',
+  view_at_required: 'reference',
+  view_group_required: 'reference',
+  view_document_shape: 'reference',
+
+
+  // First-class paths (docs/design/PATHS.0.md): text that is not a
+  // tree address, met by path()'s capture or promotion. The same
+  // 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
@@ -471,15 +549,11 @@ const codeClasses: Record<string, string> = {
   // 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_path: 'parse',
   module_missing: 'parse',
   module_integrity: 'parse',
   module_depth: 'budget',
@@ -490,11 +564,17 @@ const codeClasses: Record<string, string> = {
   // and a lattice citizen may not be falsified by more information.
   relation_cycle: 'conflict',
   relation_inverse_missing: 'conflict',
-  relation_target_unmet: 'conflict',
+  inverse_name: 'parse',
+  list_length: 'conflict',
+  recursion_unexpanded: 'incomplete',
+  recursion_budget: 'budget',
   func_arity: 'parse',
   elided_value: 'parse',
   unify_no_src: 'parse',
   incomplete_expression: 'parse',
+  pref_implicit_bag: 'parse',
+  alias_not_toplevel: 'parse',
+  alias_in_path: 'parse',
   not_number: 'parse',
   negative: 'parse',
   decimal_syntax: 'parse',
@@ -516,13 +596,15 @@ const codeClasses: Record<string, string> = {
   literal_nil: 'conflict',
   nil_gen: 'conflict',
   unite: 'conflict',
-  '|:empty': 'conflict',
-  '|:empty-dist': 'conflict',
+  'empty': 'conflict',
+  'empty-dist': 'conflict',
+  pref_rank_clash: 'conflict',
   exact_float_mix: 'conflict',
   inexact_integer_sum: 'conflict',
   pick_key: 'conflict',
   aggregate_data: 'conflict',
   aggregate_empty: 'conflict',
+  join_member: 'conflict',
   divide_by_zero: 'conflict',
   inexact_divide: 'conflict',
   float_overflow: 'conflict',
@@ -530,6 +612,7 @@ const codeClasses: Record<string, string> = {
   lossy_integer_literal: 'conflict',
   arg: 'conflict',
   'invalid-arg': 'conflict',
+  func_arg: 'conflict',
   no_first_arg: 'conflict',
   key_level: 'conflict',
   func: 'conflict',

package/src/jsonschema.ts

@@ -109,6 +109,10 @@ const KIND_TYPE: Record<string, string> = {
   Float: 'number',
   BigDecimal: 'number',
   Number: 'number',
+  // A path value is its address string at the JSON boundary
+  // (docs/design/PATHS.0.md), so the projection says `string` -- the
+  // same lossy-projection rule the exact numeric leaves follow.
+  Path: 'string',
 }
 
 
@@ -238,7 +242,44 @@ function fromConstraint(ctx: Ctx, path: string[], c: any): any {
 // (the marker drops LINES, not branches). Go's twin keeps its `nil ==
 // v` arm because a missing map key there yields a typed nil rather
 // than an absent property.
+// DEPRECATION IS AN ANNOTATION, and 2020-12 has one: `deprecated`.
+// The export used to drop the whole record in SILENCE -- no keyword,
+// and no loss line even under --strict -- which is the one thing the
+// verb's own contract says it never does (use-cases/BUGS.md §56).
+//
+// The boolean crosses faithfully. The record's STRINGS (msg, use,
+// since) have no home in 2020-12, so they are reported as a loss
+// rather than invented into `description`: this exporter emits no
+// `description` anywhere, and quietly making it mean "deprecation
+// note" would be a mapping a consumer cannot undo.
 function fromVal(ctx: Ctx, path: string[], v: any): any {
+  const out = fromValInner(ctx, path, v)
+
+  const dep = v?.deprecation
+  if (null != dep && null != out && 'object' === typeof out) {
+    const said = DEPRECATION_TEXT.filter((k) => null != dep[k])
+    if (0 < said.length) {
+      lose(ctx, path, 'deprecate',
+        'JSON Schema 2020-12 has the `deprecated` flag and no field for ' +
+        'what it SAYS, so ' + said.join('/') + ' cannot cross; the ' +
+        'schema marks the property deprecated and a consumer must read ' +
+        'the model for the reason')
+    }
+    return { ...out, deprecated: true }
+  }
+
+  return out
+}
+
+
+// The record's text keys -- the ones with nothing to carry them.
+// `DEPRECATION_KEYS` in DeprecateFuncVal.ts is the authority on what a
+// record may hold; this is that list, and a key added there without a
+// JSON Schema home belongs here too.
+const DEPRECATION_TEXT = ['msg', 'use', 'since']
+
+
+function fromValInner(ctx: Ctx, path: string[], v: any): any {
   // A preference is its inner value plus a DEFAULT. JSON Schema's
   // `default` is annotation rather than constraint -- it does not
   // validate -- which is exactly what a preference is when something