aontu 0.52.1 → 0.54.0

package/src/ctx.ts

@@ -21,6 +21,11 @@ type AontuContextConfig = {
   cc?: number
   err?: any[] // Omit<NilVal[], "push">
   explain?: any[] | boolean | null
+
+  // The provenance recorder (G7 phase 3), or absent for an
+  // uninstrumented run. Shared by reference down every descend, as the
+  // error list is, so one run has one record.
+  prov?: any
   fs?: any
   path?: string[]
   root?: Val
@@ -41,6 +46,26 @@ class AontuContext {
   path: string[]  // Path to current Val.
   vc: number  // Val counter to create unique val ids.
   cc: number = -1
+
+  // THE STAGING RULE (G8 phase 0,
+  // docs/capability-review/g8-generation.md). A value whose answer
+  // depends on WHERE IT IS -- `key()` today, the generation
+  // combinators next -- must not answer while anything is still
+  // moving it: resolved early it reports the position it was WRITTEN
+  // at rather than the one it ends up at. Such a value RESIDUATES
+  // while this is false, and fires exactly once on the pass where it
+  // is true.
+  //
+  // The pass loop (ts/src/unify.ts) sets it on the first pass whose
+  // input tree is IDENTICAL to the previous pass's: everything that
+  // was going to move has moved, and what is left is the staged
+  // values themselves, which is precisely the moment they may answer.
+  // It replaces a `ctx.cc < 3` pass count in KeyFuncVal -- a magic
+  // number, right for the documents it was tuned on and silently
+  // wrong for anything that took a fourth pass to place a value. The
+  // comment it replaces said as much: "this delay makes keys in
+  // spreads and refs work, but it is a hack - find a better way".
+  settle: boolean = false
   vars: Record<string, Val> = {}
   src?: string
   fs?: FST
@@ -50,6 +75,25 @@ class AontuContext {
 
   collect: boolean
 
+  // THE COMPLETENESS PROBE (the review's finding C). vet detects
+  // residue by GENERATING the anchored meet and keeping the
+  // incomplete-class failures. Generation honours the OUTPUT marks --
+  // `type()` and `hide()` say "do not emit this" -- so a `--at` anchor
+  // sitting under a mark generated nothing at all, reported nothing,
+  // and vetted VALID for data missing a required field, while the same
+  // anchor without the mark answered incomplete (use-cases/BUGS.md
+  // §14). A mark is a decision about OUTPUT; it is not a statement
+  // about what the data must satisfy, and `--at` names the truth to
+  // validate against explicitly. Under this flag the generation walk
+  // descends through marked values; nothing else changes, and no
+  // output is produced from a probe run -- only its findings are read.
+  probe: boolean = false
+
+  // The provenance recorder (G7 phase 3), or undefined for an
+  // uninstrumented run. Inherited by every descended and cloned
+  // context through the prototype chain, so one run has one record.
+  prov?: any
+
   // errlist: Omit<NilVal[], "push">  // Nil error log of current unify.
   err: any[]
   explain: any[] | null
@@ -71,7 +115,7 @@ class AontuContext {
   _pathTrie: Map<number, Map<string, { idx: number, path: string[] }>>
   _pathidxNext: { n: number }
 
-  // Current `unite` recursion depth, checked against MAXDEPTH
+  // Current `unite` recursion depth, checked against the depth budget
   // (ts/src/unify.ts). Held in a shared mutable box, like _pathidxNext,
   // because clone() uses Object.create: the box is inherited by
   // reference, so a nested clone's increments are visible to the frame
@@ -79,6 +123,40 @@ class AontuContext {
   // directly on its Ctx pointer (go/unify.go, maxUniteDepth).
   _depth: { n: number }
 
+  // The relation declarations this evaluation accumulates (RELATIONS
+  // P2): predicate -> what its graph atoms said. One Map per
+  // evaluation, created here and inherited by reference through
+  // clone()'s prototype chain, exactly as _depth's box is -- a clone
+  // made before the first registration must still share the registry.
+  _reldecls: Map<string, { acyclic?: boolean, inverses: Set<string> }>
+
+  // The tree a recursive residual's target resolves against when the
+  // meet's own root does not contain it (RECURSION.0.md). Normally
+  // undefined: a residual expands by walking ctx.root, and the root
+  // holds the definition. An ANCHORED vet run meets a subtree LIFTED
+  // out of the settled schema, so `$.spec.Step` names nothing in the
+  // meet's root -- the residual held its peer forever and the data
+  // under it vetted VALID unchecked. Vet sets this to the settled
+  // schema root for anchored runs; RecurseVal.body falls back to it
+  // only when the root walk finds nothing. Inherited by clone()
+  // through the prototype chain.
+  _fixroot: any
+
+  // The evaluation budgets (G5 trust profile, docs/trust.md): integer
+  // counts of engine events, never wall-clock. Always present, defaults
+  // from the shared spec-visible constants (test/spec/budget.tsv), so
+  // the hot-path reads in unify.ts are plain property loads. Inherited
+  // by clone() through the prototype chain. `revisits` is NOT profile
+  // surface (the Go port has no revisit counter to configure — see
+  // TrustBudget in type.ts); it is carried here so unify.ts reads one
+  // budget object, at its fixed spec constant.
+  budget: { passes: number, revisits: number, depth: number }
+
+  // The include manifest sink (G5, docs/trust.md): every include the
+  // resolver reads is recorded here as { path, capability }, and
+  // Aontu.parse() sorts and dedups it onto the result's `deps`.
+  manifest: { path: string, capability: string }[]
+
   // Trial mode: set by DisjunctVal.unify while each member is tried
   // against the peer. When true, makeNilErr returns the shared
   // TRIAL_NIL sentinel instead of allocating a fresh NilVal, and
@@ -102,6 +180,7 @@ class AontuContext {
     this.src = cfg.src
 
     this.collect = cfg.collect ?? null != cfg.err
+    this.prov = cfg.prov
 
     this.err = cfg.err ?? []
     this.explain = Array.isArray(cfg.explain) ? cfg.explain : null
@@ -125,10 +204,23 @@ class AontuContext {
     this._pathTrie = new Map()
     this._pathidxNext = { n: 1 }  // 0 reserved for the root path
     this._depth = { n: 0 }
+    this._reldecls = new Map()
     this._pathidx = 0
 
+    this.manifest = []
+
     this.opts = DEFAULT_OPTS()
     this.addopts(cfg.opts)
+
+    // Budget defaults are the shared spec-visible constants
+    // (test/spec/budget.tsv pins the boundaries in both ports); the
+    // trust profile may lower or raise them, deterministically.
+    const budget = (this.opts as any).trust?.budget ?? {}
+    this.budget = {
+      passes: budget.passes ?? 9,
+      revisits: 999,
+      depth: budget.depth ?? 1000,
+    }
   }
 
 

package/src/diff.ts

@@ -0,0 +1,198 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// PATH-ADDRESSED DIFF (G7 phase 6,
+// docs/capability-review/g7-machine-access.md): what changed, at which
+// paths, between two documents — the dyff-style answer, which
+// deterministic canon makes possible without phantom noise. Two
+// documents that mean the same thing canon the same way, so a diff of
+// canons reports semantic change and not reformatting.
+//
+// The text compared is the HASH FORM (G6's `hcanon`), not the plain
+// canon, for the reason G6 gives: canon drops closedness and the
+// type/hide marks, so a canon diff calls `close({a:1})` and `{a:1}`
+// identical. A false "changed" costs a needless read; a false
+// "unchanged" is a change nobody reviewed, which is the one direction
+// that must not happen.
+//
+// WHETHER a change is BREAKING is a different question, and it belongs
+// to G3: `subsume` and `breaking` answer it with the lattice's own
+// rules. This verb answers "what moved", which is what a reviewer
+// reads first and what an agent needs before it can ask the other
+// question at all.
+
+import { Aontu } from './aontu'
+import type { TrustOptions } from './type'
+import { anchorAt } from './vet'
+import type { VetFinding } from './vet'
+import { cmpCodePoint } from './keyorder'
+import { hcanon } from './hcanon'
+import { evalFailure } from './query'
+
+
+export type DiffKind = 'added' | 'removed' | 'changed'
+
+export type DiffChange = {
+  kind: DiffKind
+  // The canon on each side, absent where there is no value.
+  left?: string
+  path: string
+  right?: string
+}
+
+export type DiffReport = {
+  changes: DiffChange[]
+  findings: VetFinding[]
+  ok: boolean
+  // True when nothing moved: the two documents mean the same thing.
+  same: boolean
+}
+
+export type DiffOptions = {
+  leftPath?: string
+  rightPath?: string
+  // Compare at this path of both documents, rather than at the root.
+  at?: string
+
+  // The trust profile this run evaluates under (G5, docs/trust.md).
+  // The source arrives from a caller, so the caller must be able to
+  // say what it may reach: without this the include chain is the
+  // default one, and `@"../../etc/passwd.aon"` reads whatever the
+  // process can. (`@"x.js"` no longer executes -- ADR-012 refuses the
+  // extension -- but reading is enough.) A server passes
+  // `{include:'none'}`.
+  trust?: TrustOptions
+}
+
+
+function pathText(parts: string[]): string {
+  return '$' + (0 < parts.length ? '.' + parts.join('.') : '')
+}
+
+
+// Both sides of one node — never both absent: keys come from the
+// union of the two bags, and list indices run to the longer side, so
+// every walk has at least one value. Bags of the SAME kind recurse,
+// which is what makes the report path-addressed rather than one line
+// saying the whole document changed; everything else compares text.
+function walk(
+  left: any, right: any, parts: string[], out: DiffChange[]): void {
+  if (null == left) {
+    out.push({ kind: 'added', path: pathText(parts), right: hcanon(right) })
+    return
+  }
+  if (null == right) {
+    out.push({ kind: 'removed', left: hcanon(left), path: pathText(parts) })
+    return
+  }
+
+  const bothMaps = true === left.isMap && true === right.isMap
+  const bothLists = true === left.isList && true === right.isList
+  if (bothMaps || bothLists) {
+    // The bag's OWN attributes, at pseudo-keys under it: a recursing
+    // bag never compares its own text, so what the children do not
+    // carry has to be compared here. The spread is part of what a bag
+    // MEANS; so are closedness and the marks, which is exactly why the
+    // hash form spells them (G6).
+    const lc = null == left.spread.cj ? undefined : hcanon(left.spread.cj)
+    const rc = null == right.spread.cj ? undefined : hcanon(right.spread.cj)
+    if (lc !== rc) {
+      out.push({
+        kind: null == lc ? 'added' : null == rc ? 'removed' : 'changed',
+        ...(null == lc ? {} : { left: lc }),
+        path: pathText(parts.concat('&')),
+        ...(null == rc ? {} : { right: rc }),
+      })
+    }
+    flag(left.closed, right.closed, parts, 'closed', out)
+    flag(left.mark?.type, right.mark?.type, parts, 'type', out)
+    flag(left.mark?.hide, right.mark?.hide, parts, 'hide', out)
+
+    const keys = bothMaps
+      ? [...new Set([
+        ...Object.keys(left.peg), ...Object.keys(right.peg),
+      ])].sort(cmpCodePoint)
+      : [...new Set([
+        ...Object.keys(left.peg), ...Object.keys(right.peg),
+      ])].sort((a, b) => Number(a) - Number(b))
+    for (const k of keys) {
+      walk(left.peg[k], right.peg[k], parts.concat(k), out)
+    }
+    return
+  }
+
+  const lh = hcanon(left)
+  const rh = hcanon(right)
+  if (lh !== rh) {
+    out.push({ kind: 'changed', left: lh, path: pathText(parts), right: rh })
+  }
+}
+
+
+// One boolean attribute of a bag, as a pseudo-key: `$.a.&closed` says
+// the map at `$.a` was closed (or opened) without saying anything
+// about its keys.
+function flag(
+  left: any, right: any, parts: string[], name: string,
+  out: DiffChange[]): void {
+  const l = true === left
+  const r = true === right
+  if (l !== r) {
+    out.push({
+      kind: 'changed',
+      left: String(l),
+      path: pathText(parts.concat('&' + name)),
+      right: String(r),
+    })
+  }
+}
+
+
+function evalSide(
+  aontu: Aontu, src: string, path: string | undefined, at: string | undefined,
+): { node?: any, finding?: VetFinding } {
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == path ? undefined : { path }
+  const root: any = aontu.unify(src, parseOpts, ctx)
+  if (0 < ctx.err.length) {
+    // The query surface's own fold: a document that does not stand up
+    // has no meaning to compare, and the engine's diagnosis is the
+    // report.
+    return { finding: evalFailure(ctx) }
+  }
+  const node: any = null == at ? root : anchorAt(root, at)
+  if (null == node) {
+    return {
+      finding: {
+        code: 'no_path',
+        class: 'reference',
+        severity: 'error',
+        path: at as string,
+        message: `The path ${at} names nothing in this document.`,
+        sites: [],
+      },
+    }
+  }
+  return { node }
+}
+
+
+// Diff two documents. Each is evaluated on its own — a document that
+// does not stand up has no meaning to compare, and the report says so
+// rather than diffing a wreck.
+export function diff(
+  leftSrc: string, rightSrc: string, opts?: DiffOptions): DiffReport {
+  const options = opts ?? {}
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+
+  const l = evalSide(aontu, leftSrc, options.leftPath, options.at)
+  const r = evalSide(aontu, rightSrc, options.rightPath, options.at)
+  const findings = [l.finding, r.finding].filter(Boolean) as VetFinding[]
+  if (0 < findings.length) {
+    return { changes: [], findings, ok: false, same: false }
+  }
+
+  const changes: DiffChange[] = []
+  walk(l.node, r.node, [], changes)
+  return { changes, findings: [], ok: true, same: 0 === changes.length }
+}

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'
@@ -15,6 +17,39 @@ import { hints } from './hints'
 const { errmsg, strinject } = util
 
 
+// COLOUR IS A DECISION ABOUT THE DESTINATION, not about the message.
+// Every error frame hardcoded the ANSI escapes, so a piped report and
+// a `--jsonl` answer carried terminal control codes into whatever read
+// them -- a log file, a CI annotation, an agent's parser (the review's
+// finding F).
+//
+// NO_COLOR (no-color.org: set, to anything, means no colour) turns them
+// off everywhere, library callers included. The CLI additionally turns
+// them off when its stderr is not a terminal, through setColor: a
+// library cannot see the destination, and a caller who has one is the
+// only one who can say.
+let COLOR: boolean | undefined
+
+function setColor(on: boolean | undefined): void {
+  COLOR = on
+}
+
+function colorActive(): boolean {
+  if (null != COLOR) {
+    return COLOR
+  }
+  // `globalThis` always exists; `process` need not (this library runs
+  // in a browser too), so the optional chain starts at the part that
+  // can actually be missing -- and stays a CHAIN rather than becoming
+  // an `if`, because the browser arm is unreachable from any test this
+  // suite can run and ADR-002 does not accept an arm nothing takes.
+  // Set-but-EMPTY is the documented exception and does not disable
+  // colour (no-color.org).
+  const no = (globalThis as any).process?.env?.NO_COLOR
+  return null == no || '' === no
+}
+
+
 function getHint(why: any, details?: Record<string, any>): string | undefined {
   if (hints[why]) {
     let txt = hints[why]
@@ -61,8 +96,8 @@ function descErr<NILS extends NilVal | NilVal[]>(
       let v1: any = err.primary
       let v2: any = err.secondary
 
-      let v1src = resolveSrc(v1, errctx, 'primary')
-      let v2src = resolveSrc(v2, errctx, 'secondary')
+      let v1src = resolveSrc(v1, errctx)
+      let v2src = resolveSrc(v2, errctx)
 
       // STRICT `!==` against the empty string. The loose `!=` here dropped
       // the list index 0, because `'' != 0` is FALSE in JavaScript ('' and
@@ -83,7 +118,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
       err.msg = [
         errmsg({
-          color: { active: true },
+          color: { active: colorActive() },
           name: 'aontu',
           code: err.why,
           txts: {
@@ -99,7 +134,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
         (null != v1 && errmsg({
           // TODO: color should come from jsonic config
-          color: { active: true, line: '\x1b[34m' },
+          color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v1.canon +
               (null == v2 ? '' : ' with value: ' + v2.canon), // + ' #' + err.id,
@@ -115,7 +150,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
         (null != v2 && errmsg({
           // TODO: color should come from jsonic config
-          color: { active: true, line: '\x1b[34m' },
+          color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v2.canon +
               ' with value: ' + v1.canon, // + ' #' + err.id,
@@ -147,13 +182,18 @@ 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
 }
 
 
-function resolveSrc(v: Val, errctx: ErrContext | undefined, position: string) {
+function resolveSrc(v: Val, errctx: ErrContext | undefined) {
   let src: string | undefined = undefined
   const url = v?.site.url
 
@@ -210,7 +250,7 @@ class AontuError extends Error {
   }
 
   errs: () => NilVal[]
-} /* node:coverage ignore next 9 */
+} /* node:coverage ignore next 11 */
 
 
 export {
@@ -218,4 +258,6 @@ export {
   makeNilErr,
   descErr,
   AontuError,
+  setColor,
+  colorActive,
 }

package/src/graph.ts

@@ -0,0 +1,185 @@
+/* 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'
+
+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[]
+}
+
+
+const formatPath = (path: string[]): string =>
+  0 === path.length ? '$' : '$.' + path.join('.')
+
+
+// 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 }
+      }
+    }
+  }
+  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: 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[] = []
+
+  // 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[], ancestors: Set<any>, hidden: boolean,
+    undecided: boolean
+  ): void => {
+    if (null == node || true !== node.isVal || ancestors.has(node)) {
+      return
+    }
+
+    hidden = hidden || true === node.mark?.hide
+
+    const link = node.link
+    if (null != link) {
+      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], ancestors, hidden, undecided)
+      }
+      ancestors.delete(node)
+    }
+  }
+
+  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) {
+    return { edges, disjunct: [...new Set(disjunct)].sort(cmpCodePoint) }
+  }
+  return { edges }
+}