aontu 0.53.0 → 0.55.0

package/src/cli.ts

@@ -40,6 +40,11 @@ import type { TrimReport, TrimVerdict } from './trim'
 import type { RelationReport, RelationVerdict } from './relation'
 import { reachCheck } from './reach'
 import type { ReachReport, ReachVerdict } from './reach'
+import { view, viewSet, viewDefaultProfile } from './view'
+import type {
+  ViewEdges, ViewFigure, ViewKind, ViewLoss, ViewOptions, ViewProfile,
+  ViewReport, ViewSetReport, ViewStyle, ViewVerdict,
+} from './view'
 import type { QueryView } from './query'
 import type { WhyRecord } from './provenance'
 import { agentsMdSplice } from './agentsmd'
@@ -55,6 +60,8 @@ const HELP = `Usage: aontu [options] [file]
        aontu trim --check [options] <file>
        aontu relations [options] <file>
        aontu reaches <from> <to> [--relation <name>] [options] <file>
+       aontu view <kind> [options] <file>...
+       aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
@@ -175,6 +182,72 @@ Why options:
 Why exit codes mirror get's: 0 explained, 1 the path names nothing,
 2 usage, 4 the document does not stand up on its own.
 
+View kinds: tree, matrix, graph, layer, sets, layers, ladder, poset
+(the poset takes several files). The figure goes to stdout, the loss
+report to stderr. With --views it draws every figure a document
+declares as data, from one evaluation: each declaration names its own
+kind and out file, nothing is written unless every figure rendered,
+and --check gates the committed set.
+
+View options:
+  --as <profile>    text | mermaid | dot | er | svg, per kind: doc,
+                    tree, matrix, sets and layers draw text (default)
+                    or svg; graph draws mermaid (default), dot or er;
+                    layer draws text (default), mermaid or svg; ladder
+                    and poset draw mermaid (default) or dot
+  --at <path>       Restrict the figure to nodes under this path; the
+                    subtree doc draws; the path the ladder draws;
+                    where the poset compares
+  --views <path>    Draw every figure the document declares at this
+                    path, one evaluation, all or nothing; each
+                    declaration names its own kind and out file
+  -o, --out <file>  Write the figure here instead of stdout
+  --check           Exit 1 if --out differs from what would be drawn;
+                    nothing is written
+  --strict          Exit 1 when the loss report holds anything beyond
+                    edges_deduped, inverse_suppressed and crossings
+  --depth <n>       doc: how many levels of key to draw (default 3)
+  --max-rows <n>    Refuse a figure above this many rows (default 60)
+  --style <s>       auto (default), none, ansi or css. A figure's
+                    marks carry their meaning -- a direct cell, a
+                    closure cell, an upward edge -- and each profile
+                    has one way to show it: SGR escapes for text, CSS
+                    classes for svg. auto picks that mechanism where
+                    the destination can carry it: escapes only on a
+                    terminal (NO_COLOR is honoured), and an svg keeps
+                    the stylesheet that makes it standalone. none
+                    drops both; on svg the classes stay and only the
+                    stylesheet goes, for a host page that has already
+                    bound --av-ink and its kin. Escapes are never
+                    written to a file
+  --format <f>      text (default) or json, the whole report
+  --relation <n>    tree, matrix, layer: draw over this relation only;
+                    graph: keep this predicate (repeatable)
+  --root <path>     tree: draw only the subtree under this node;
+                    repeatable
+  --order <o>       matrix: canon (default) or partition
+  --closure         matrix: mark transitively reachable cells +
+  --group-by <k>    graph: one subgraph per distinct value of field k;
+                    layer: one band per value (required)
+  --layers <a,b>    layer: the bands in this order, top first; without
+                    it the order is derived from the relation
+  --edges <e>       layer: which of the relation's edges to draw over
+                    the bands -- upward (the violations, the default
+                    for text and svg), all (mermaid's default) or none
+  --label <k>       graph: label each node with field k
+  --sets <path>     sets: the map whose keys are the sets
+  --member <k>      sets: the field holding each set's members
+  --universe <p>    sets: the full element domain, so the empty
+                    column exists
+  --min-degree <n>  sets: drop intersections below this degree
+  --min-size <n>    layers: drop intersections below this many paths
+  --max-cols <n>    sets, layers: elide columns beyond this many
+  --profile <p>     poset: values | defaults (default) | gen
+
+View exit codes: 0 rendered, 1 --check mismatch or lossy under
+--strict, 2 usage or --max-rows exceeded, 4 the document does not stand
+up on its own, or a relation, root or path that names nothing.
+
 Set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -1711,6 +1784,69 @@ const REACHES_EXIT: Record<ReachVerdict, number> = {
   error: 4,
 }
 
+const VIEW_HELP =
+  'aontu view <kind> [options] <file>... (try --help)'
+
+const VIEW_KINDS: ViewKind[] =
+  ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets', 'layers', 'ladder',
+    'poset']
+
+const VIEW_PROFILES: ViewProfile[] = ['text', 'mermaid', 'dot', 'er', 'svg']
+
+const VIEW_EDGES: ViewEdges[] = ['upward', 'all', 'none']
+
+// The styles the CLI accepts (VIEWS.0.md, "7. Styling"). `auto` is
+// here and NOT in ViewStyle: resolving it means knowing whether stdout
+// is a terminal, which is the CLI's to know and the library's never --
+// the same division err.ts already draws for the error frames.
+const VIEW_STYLES = ['auto', 'none', 'ansi', 'css']
+
+// `--style auto` resolved, which only the CLI can do. The mechanism is
+// the PROFILE's and the library knows it -- an SVG carries its
+// stylesheet unless told not to, which is what makes a figure stand
+// alone. What the library cannot know is whether the DESTINATION is a
+// terminal, so that is the only thing decided here: escapes on the
+// text profile when stdout is a terminal and NO_COLOR is unset, the
+// same two conditions the error frames use. `undefined` leaves the
+// profile's own default in place.
+function viewStyleOf(
+  asked: string | undefined, as: ViewProfile | undefined
+): ViewStyle | undefined {
+  if (undefined !== asked && 'auto' !== asked) {
+    return asked as ViewStyle
+  }
+  // STDOUT'S OWN TERMINAL-NESS, and NO_COLOR read here rather than
+  // through colorActive(). The figure goes to STDOUT and the error
+  // frames go to STDERR, and they are not the same destination: main()
+  // has already called setColor for stderr, so asking colorActive()
+  // would answer the wrong question twice --- no escapes for
+  // `aontu view tree m.aon 2>/dev/null` at a terminal, and escapes
+  // into the pipe for `aontu view tree m.aon | less`. The NO_COLOR
+  // rule is the one no-color.org states and err.ts implements:
+  // set, to anything but empty, means no colour.
+  const no = process.env.NO_COLOR
+  return 'text' === as && true === process.stdout.isTTY
+    && (null == no || '' === no) ? 'ansi' : undefined
+}
+
+// The figure was drawn (0, `lossy` included: the loss report says
+// what it could not draw, and --strict is the gate on that), or the
+// document could not be drawn (4). An EMPTY figure is a drawing, not
+// a failure: a model with no links has nothing to draw, honestly.
+const VIEW_EXIT: Record<ViewVerdict, number> = {
+  rendered: 0,
+  lossy: 0,
+  error: 4,
+}
+
+// The refusals that are USAGE, not the document's fault: exit 2, as
+// every other verb's usage errors do.
+const VIEW_USAGE_CODES = [
+  'view_kind_unknown', 'view_profile_unknown', 'view_rows_exceeded',
+  'view_at_required', 'view_sets_required', 'view_group_required',
+  'view_document_shape', 'view_style_profile', 'view_style_unknown',
+]
+
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)'
 
 // The module tooling (G6 phase 3, ts/src/mod-tool.ts). All LOCAL:
@@ -1773,7 +1909,8 @@ function runMod(argv: string[]): number {
   if ('get' === sub || 'publish' === sub) {
     process.stderr.write(
       'aontu: mod ' + sub + ' needs a registry client, which this build ' +
-      'does not ship (docs/capability-review/g6-distribution.md)\n')
+      'does not ship; vendor the module by hand and run ' +
+      "'aontu mod tidy'\n")
     return 2
   }
 
@@ -2026,7 +2163,7 @@ function runReaches(argv: string[]): number {
 
   if (3 !== rest.length) {
     process.stderr.write(
-      `aontu: reaches needs two entities and one file\n${REACHES_HELP}\n`)
+      `aontu: reaches needs two node paths and one file\n${REACHES_HELP}\n`)
     return 2
   }
 
@@ -2074,6 +2211,412 @@ function renderReachesJson(report: ReachReport): string {
   }, 2)
 }
 
+// ---------------------------------------------------------------------
+// The tree view (docs/design/VIEWS.0.md, ts/src/view.ts): the drawn
+// edge set, as text a golden diff can check.
+
+function runView(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const rest: string[] = []
+  let format: SubsumeFormat = 'text'
+  let out: string | undefined = undefined
+  let check = false
+  let strict = false
+  const relations: string[] = []
+  const roots: string[] = []
+  const opts: ViewOptions = {}
+  // The style ASKED FOR, which may be `auto` -- a word ViewStyle does
+  // not have, because resolving it is the CLI's job.
+  let style: string | undefined = undefined
+
+  // A flag that takes a value, read into `opts` by name.
+  const valued: Record<string, keyof ViewOptions> = {
+    '--as': 'as', '--at': 'at', '--order': 'order', '--group-by': 'groupBy',
+    '--label': 'label', '--sets': 'sets', '--member': 'member',
+    '--universe': 'universe', '--profile': 'profile', '--views': 'views',
+    '--edges': 'edges',
+  }
+  const counted: Record<string, keyof ViewOptions> = {
+    '--max-rows': 'maxRows', '--max-cols': 'maxCols',
+    '--min-degree': 'minDegree', '--min-size': 'minSize',
+    '--depth': 'depth',
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--format' === arg) {
+      const f = argv[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return 2
+      }
+      format = f
+    }
+    else if ('--relation' === arg) {
+      const relation = argv[++i]
+      if (null == relation || '' === relation) {
+        process.stderr.write('aontu: --relation needs a name\n')
+        return 2
+      }
+      relations.push(relation)
+    }
+    else if ('--root' === arg) {
+      const root = argv[++i]
+      if (null == root) {
+        process.stderr.write('aontu: --root needs a node path\n')
+        return 2
+      }
+      roots.push(root)
+    }
+    else if ('-o' === arg || '--out' === arg) {
+      out = argv[++i]
+      if (null == out) {
+        process.stderr.write('aontu: --out needs a file\n')
+        return 2
+      }
+    }
+    else if ('--style' === arg) {
+      style = argv[++i]
+      if (null == style || !VIEW_STYLES.includes(style)) {
+        process.stderr.write(
+          `aontu: --style needs one of ${VIEW_STYLES.join(', ')}\n`)
+        return 2
+      }
+    }
+    else if ('--check' === arg) {
+      check = true
+    }
+    else if ('--strict' === arg) {
+      strict = true
+    }
+    else if ('--closure' === arg) {
+      opts.closure = true
+    }
+    else if ('--layers' === arg) {
+      const v = argv[++i]
+      if (null == v || '' === v) {
+        process.stderr.write('aontu: --layers needs a comma-separated list\n')
+        return 2
+      }
+      opts.layers = v.split(',')
+    }
+    else if (undefined !== valued[arg]) {
+      const v = argv[++i]
+      if (null == v || '' === v) {
+        process.stderr.write(`aontu: ${arg} needs a value\n`)
+        return 2
+      }
+      (opts as any)[valued[arg]] = v
+    }
+    else if (undefined !== counted[arg]) {
+      const v = argv[++i]
+      if (null == v || !/^[0-9]+$/.test(v)) {
+        process.stderr.write(`aontu: ${arg} needs a count\n`)
+        return 2
+      }
+      (opts as any)[counted[arg]] = parseInt(v, 10)
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown view option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      rest.push(arg)
+    }
+  }
+
+  // ESCAPES NEVER GO INTO A FILE. A pinned golden holding terminal
+  // control codes is not a golden anybody can read, and a byte
+  // comparison against one would fail on the reader's terminal
+  // settings. `auto` resolves to `none` there on its own; asking for
+  // `ansi` explicitly is a usage error rather than a silent downgrade,
+  // so a script that wanted colour is told where it went.
+  if ('ansi' === style && (undefined !== out || undefined !== opts.views)) {
+    process.stderr.write(
+      'aontu: --style ansi writes to a terminal, not to a file\n')
+    return 2
+  }
+
+  // THE VIEW DOCUMENT draws every figure a document declares, so it
+  // names no kind: the declarations do, one each.
+  if (undefined !== opts.views) {
+    // A declaration names its own profile, so the style is left to
+    // each figure's own default; `--style none` still reaches every
+    // one of them, which is how a host page that binds the CSS
+    // variables asks for eight figures without eight stylesheets.
+    opts.style = viewStyleOf(style, undefined)
+    return runViewSet(rest, opts, trust, { format, check, strict, out })
+  }
+
+  if (2 > rest.length) {
+    process.stderr.write(
+      `aontu: view needs a kind and a file\n${VIEW_HELP}\n`)
+    return 2
+  }
+  const kind = rest[0] as ViewKind
+  if (!VIEW_KINDS.includes(kind)) {
+    process.stderr.write(
+      `aontu: unknown view kind ${kind} (the kinds are: ${VIEW_KINDS.join(', ')})\n`)
+    return 2
+  }
+  if (undefined !== opts.as && !VIEW_PROFILES.includes(opts.as)) {
+    process.stderr.write(
+      `aontu: --as needs one of ${VIEW_PROFILES.join(', ')}\n`)
+    return 2
+  }
+  if (undefined !== opts.order && 'canon' !== opts.order && 'partition' !== opts.order) {
+    process.stderr.write('aontu: --order needs canon or partition\n')
+    return 2
+  }
+  if (undefined !== opts.edges && !VIEW_EDGES.includes(opts.edges)) {
+    process.stderr.write(
+      `aontu: --edges needs one of ${VIEW_EDGES.join(', ')}\n`)
+    return 2
+  }
+  if (undefined !== opts.profile && !['values', 'defaults', 'gen'].includes(opts.profile)) {
+    process.stderr.write('aontu: --profile needs values, defaults or gen\n')
+    return 2
+  }
+  if ('poset' !== kind && 2 !== rest.length) {
+    process.stderr.write(`aontu: view ${kind} takes one file\n`)
+    return 2
+  }
+  if ('graph' === kind) {
+    opts.relations = relations
+  }
+  else if (1 < relations.length) {
+    process.stderr.write(`aontu: view ${kind} takes one --relation\n`)
+    return 2
+  }
+  else {
+    opts.relation = relations[0]
+  }
+  if (check && undefined === out) {
+    process.stderr.write('aontu: --check needs --out\n')
+    return 2
+  }
+
+  const files = rest.slice(1)
+  const srcs: string[] = []
+  for (const file of files) {
+    try {
+      srcs.push(readFileSync(file, 'utf8'))
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+  }
+
+  const report = view(srcs[0], {
+    ...opts,
+    style: viewStyleOf(style, opts.as ?? viewDefaultProfile(kind)),
+    kind,
+    path: files[0],
+    roots,
+    trust: verbTrust(trust, entryRootOf(files[0])),
+    docs: files.slice(1).map((path, i) => ({ src: srcs[i + 1], path })),
+  })
+
+  if ('json' === format) {
+    process.stdout.write(renderViewJson(report) + '\n')
+  }
+  else if ('error' === report.verdict) {
+    process.stderr.write(
+      (report.errors as VetFinding[]).map(renderFinding).join('\n') + '\n')
+  }
+  else {
+    // THE FIGURE AND NOTHING ELSE on stdout (or in the file): stdout is
+    // what a golden diff reads, and a verdict line would be part of
+    // every drawing. The loss report goes to stderr, so a figure
+    // written to a file still tells the reader what it could not draw.
+    const text = report.text + '\n'
+    if (undefined === out) {
+      process.stdout.write(text)
+    }
+    else if (check) {
+      let have: string | undefined = undefined
+      try {
+        have = readFileSync(out, 'utf8')
+      }
+      catch (_err: any) {
+        // Absent is a mismatch.
+      }
+      if (have !== text) {
+        process.stderr.write(`aontu: ${out} differs from the ${kind} figure\n`)
+        return 1
+      }
+    }
+    else {
+      writeFileSync(out, text, 'utf8')
+    }
+    if (0 < report.loss.length) {
+      process.stderr.write(renderViewLoss(report.loss) + '\n')
+    }
+  }
+
+  if ('error' === report.verdict) {
+    const code = (report.errors as VetFinding[])[0]?.code
+    return VIEW_USAGE_CODES.includes(code) ? 2 : VIEW_EXIT.error
+  }
+  return strict && 'lossy' === report.verdict ? 1 : VIEW_EXIT[report.verdict]
+}
+
+// `aontu view --views <path> <file>`: every figure the document
+// declares, from one evaluation, all or nothing.
+//
+// A declared `out` is resolved against the DOCUMENT's own directory,
+// not the caller's: a view document is committed beside the figures it
+// gates, and a gate that only passes from one working directory is not
+// a gate.
+function runViewSet(
+  rest: string[], opts: ViewOptions, trust: TrustArg,
+  how: { format: SubsumeFormat, check: boolean, strict: boolean, out?: string }
+): number {
+  if (1 !== rest.length) {
+    process.stderr.write('aontu: view --views takes one file\n')
+    return 2
+  }
+  if (undefined !== how.out) {
+    process.stderr.write(
+      'aontu: --out is per figure in a view document; each declares its own\n')
+    return 2
+  }
+  const file = rest[0]
+  let src: string
+  try {
+    src = readFileSync(file, 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  const report = viewSet(src, {
+    ...opts, path: file, trust: verbTrust(trust, entryRootOf(file)),
+  })
+
+  if ('json' === how.format) {
+    process.stdout.write(renderViewSetJson(report) + '\n')
+  }
+  else if (undefined !== report.errors) {
+    process.stderr.write(report.errors.map(renderFinding).join('\n') + '\n')
+  }
+  else {
+    for (const fig of report.views) {
+      if (undefined !== fig.errors) {
+        process.stderr.write(`${fig.name} (${fig.kind}):\n` +
+          fig.errors.map(renderFinding).join('\n') + '\n')
+      }
+      else if (0 < fig.loss.length) {
+        process.stderr.write(renderViewLoss(fig.loss)
+          .split('\n').map((l) => `${fig.name}  ${l}`).join('\n') + '\n')
+      }
+    }
+  }
+  if ('error' === report.verdict) {
+    return setExit(report)
+  }
+
+  // EVERY FIGURE RENDERED, so the whole set is written -- or, under
+  // --check, the whole set is compared and every difference named.
+  const dir = dirname(resolve(file))
+  let differ = 0
+  for (const fig of report.views) {
+    const path = resolve(dir, fig.out)
+    const text = fig.text + '\n'
+    if (how.check) {
+      let have: string | undefined = undefined
+      try {
+        have = readFileSync(path, 'utf8')
+      }
+      catch (_err: any) {
+        // Absent is a mismatch.
+      }
+      if (have !== text) {
+        differ++
+        process.stderr.write(
+          `aontu: ${fig.out} differs from the ${fig.name} figure\n`)
+      }
+    }
+    else {
+      try {
+        writeFileSync(path, text, 'utf8')
+      }
+      catch (err: any) {
+        process.stderr.write(`aontu: cannot write ${err.path}: ${err.message}\n`)
+        return 2
+      }
+      if ('json' !== how.format) {
+        process.stderr.write(`wrote ${fig.out}  ${fig.name} (${fig.kind})\n`)
+      }
+    }
+  }
+  if (0 < differ) {
+    return 1
+  }
+  return how.strict && 'lossy' === report.verdict ? 1 : VIEW_EXIT[report.verdict]
+}
+
+
+// A set's exit code is the worst of its figures': a usage refusal
+// anywhere is usage, and any other refusal is the document's fault.
+function setExit(report: ViewSetReport): number {
+  const codes = [
+    ...(report.errors ?? []),
+    ...report.views.flatMap((v) => v.errors ?? []),
+  ].map((e) => e.code)
+  return codes.some((c) => VIEW_USAGE_CODES.includes(c))
+    ? 2 : VIEW_EXIT.error
+}
+
+
+function renderViewSetJson(report: ViewSetReport): string {
+  return exactJSON({
+    aontu: { version: version(), verb: 'view' },
+    verdict: report.verdict,
+    views: report.views.map((v: ViewFigure) => ({
+      name: v.name,
+      kind: v.kind,
+      out: v.out,
+      verdict: v.verdict,
+      ...(null == v.text ? {} : { text: v.text }),
+      loss: v.loss,
+      ...(null == v.errors ? {} : { errors: v.errors }),
+    })),
+    ...(null == report.errors ? {} : { errors: report.errors }),
+  }, 2)
+}
+
+
+// One line per code: the code, the count, and the detail if any.
+function renderViewLoss(loss: ViewLoss[]): string {
+  return loss.map((l) =>
+    `${l.code}  ${l.count}` +
+    (undefined === l.detail ? '' : '  ' + l.detail.join(' '))).join('\n')
+}
+
+function renderViewJson(report: ViewReport): string {
+  return exactJSON({
+    aontu: { version: version(), verb: 'view' },
+    kind: report.kind,
+    verdict: report.verdict,
+    ...(null == report.text ? {} : { text: report.text }),
+    loss: report.loss,
+    ...(null == report.errors ? {} : { errors: report.errors }),
+  }, 2)
+}
+
 function renderRelationsText(report: RelationReport): string {
   const head = `verdict: ${report.verdict}`
   // WHY, when the document could not be evaluated at all: rendered as
@@ -2088,11 +2631,8 @@ function renderRelationsText(report: RelationReport): string {
   const lines = report.findings.map((f) =>
     'relation_cycle' === f.code
       ? `${f.at}  ${f.relation}: cycle ${f.detail.join(' -> ')}`
-      : 'relation_target_unmet' === f.code
-        ? `${f.at}  ${f.relation}: ${f.detail[1]} is not what ` +
-        `${f.relation} targets (${f.detail[2]})`
-        : `${f.at}  ${f.relation}: ${f.detail[1]} does not list ` +
-        `${f.detail[0]} under ${f.detail[2]}`)
+      : `${f.at}  ${f.relation}: ${f.detail[1]} does not list ` +
+      `${f.detail[0]} under ${f.detail[2]}`)
   return [head, ''].concat(lines).join('\n')
 }
 
@@ -2906,6 +3446,10 @@ function main(argv: string[]): void {
     return finish(runReaches(argv.slice(3)))
   }
 
+  if ('view' === argv[2]) {
+    return finish(runView(argv.slice(3)))
+  }
+
   if ('trim' === argv[2]) {
     return finish(runTrim(argv.slice(3)))
   }
@@ -2989,7 +3533,7 @@ function main(argv: string[]): void {
   else {
     runStdin(mode, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 15 */
+} /* node:coverage ignore next 16 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -2999,6 +3543,7 @@ function main(argv: string[]): void {
 export {
   evalSource, main, runVet, runSubsume, runBreaking, runTrim, runRelations,
   runReaches,
+  runView,
   runJsonSchema,
   runMod,
   runHash, runGet,

package/src/ctx.ts

@@ -123,6 +123,25 @@ 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
@@ -185,6 +204,7 @@ 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 = []

package/src/diff.ts

@@ -56,8 +56,10 @@ export type DiffOptions = {
   // 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 `@"x.js"` is arbitrary code execution in the
-  // evaluating process. A server passes `{include:'none'}`.
+  // 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
 }