aontu 0.52.0 → 0.53.0

package/src/vet.ts

@@ -0,0 +1,992 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// The validation verb: check a data document against a schema document
+// and return a MACHINE-READABLE report (G2 phase 2,
+// docs/capability-review/g2-validation-verb.md).
+//
+// This module is the engine only. The CLI verb, the JSON/SARIF
+// renderers and `--watch` are phase 3 and 5; the Go port is phase 4.
+// Keeping the engine transport-free is the split lsp.ts already uses,
+// and for the same reason: it is the part that has to be unit-testable
+// and embeddable.
+//
+// Two properties of the engine shape everything here, and both were
+// probed rather than assumed:
+//
+//   - A CONTRADICTION surfaces as a NilVal in the unified tree, so
+//     conflict findings come from a tree walk (the `walkNils` pattern
+//     lsp.ts already uses, generalised).
+//   - INCOMPLETENESS does not. `{name:"auth"}` against
+//     `{name:string, port:integer}` unifies cleanly and leaves
+//     `port:integer` standing — no nil, no error. It surfaces only when
+//     something tries to GENERATE, which is why vet runs a generate
+//     check in an isolated collect context and reads the
+//     `incomplete`-class errors out of it. The two verdicts the report
+//     distinguishes therefore come from two different mechanisms.
+
+import type { TrustOptions, Val } from './type'
+
+import { Aontu } from './aontu'
+import {
+  dirname, isAbsolute, join as pathJoin, relative as pathRelative,
+  resolve as pathResolve,
+} from 'node:path'
+
+import { descErr, getHint } from './err'
+import { ConjunctVal } from './val/ConjunctVal'
+import { walkVals, collectNils } from './walk'
+import { sizingResidue } from './val/BagVal'
+import { collectDeprecations, walkBagVals, deprecationMessage } from './utility'
+import { subsumeNode, effectiveDefault } from './subsume'
+// The `--at` refusal is the SAME refusal `get` and `why` give for a
+// path that names nothing, down to the "did you mean" -- so it is that
+// one, not a second spelling of it. A cycle in the module graph
+// (query imports anchorAt from here), and a benign one: both sides
+// use the other only from inside a function body, never at load time.
+import { noPathFinding } from './query'
+
+
+export type VetVerdict = 'valid' | 'invalid' | 'incomplete' | 'error'
+
+export type VetRole = 'data' | 'schema'
+
+export type VetSite = {
+  file: string
+  row: number
+  col: number
+  // The extent in UTF-16 code units, or -1 when unknown — the same
+  // "unknown" row and col already use.
+  //
+  // THIS IS WHAT MAKES A FINDING REPAIRABLE. `value` is the CANON, not
+  // the source text: `port: 0x1F` reports canon `31` at column 7, so a
+  // consumer replacing `(col, value.length)` writes `port: 5x1F` and
+  // corrupts the document. With `len` the span is `(col, 4)` and the
+  // replacement is exact.
+  //
+  // NEVER GUESSED. Where the span is unknown this is -1 and a consumer
+  // must not edit — unlike the LSP, which falls back to canon because a
+  // wonky highlight is cosmetic while a wrong edit is a lost file.
+  // See ts/src/site.ts for what the extent covers.
+  len: number
+  role: VetRole
+  // The SOURCE TEXT the span covers, or '' when unknown.
+  //
+  // This is what makes the span SELF-VERIFYING, and it is not the same
+  // as `value`. For a scalar the two differ by normalisation — `0x1F`
+  // has src `0x1F` and value (canon) `31`. For a COMPOUND the span
+  // names the opening token only, exactly as row and col always have:
+  // a constraint `min(1)` reports src `min`, and a reference `$.b`
+  // reports src `$`.
+  //
+  // So a consumer must read the document at (row, col, len), compare it
+  // to `src`, and REFUSE when they differ — and, seeing `min` where it
+  // expected `min(1)`, refuse rather than replace the name and orphan
+  // the arguments. Without this field that mistake is undetectable.
+  src?: string
+  value?: string
+}
+
+export type VetFinding = {
+  code: string
+  class: string
+  severity: 'error' | 'warning' | 'info'
+  path: string
+  message: string
+
+  // THE REPAIR, not just the diagnosis. `message` is one line by
+  // design -- it is the headline, and the frames under it are for a
+  // human at a terminal -- but for several codes the part that says
+  // what to DO about the failure lived only in those frames, so a
+  // machine reader (an agent, a CI annotation, an editor) got the
+  // complaint and none of the cure. `0d` is the clearest case: the
+  // engine refuses a lossy integer literal and the hint names the
+  // exact-decimal escape that fixes it. Populated from the shared
+  // hints table (ts/src/hints.ts, mirrored by go/hints.go) whenever
+  // the code has one; absent when it does not (the report-layer
+  // compat_* codes, notably, carry no hint text).
+  //
+  // Excluded from spec goldens for the same reason `message` is: it is
+  // prose, it is long, and the two ports hold it to the byte through
+  // the message tests instead of through every vet row.
+  hint?: string
+
+  sites: VetSite[]
+  expected?: string
+  actual?: string
+  note?: string
+}
+
+export type VetReport = {
+  verdict: VetVerdict
+  truncated: boolean
+  findings: VetFinding[]
+}
+
+export type VetOptions = {
+  at?: string          // validate against this path of the schema
+  closed?: boolean     // close() the anchor for this run
+  partial?: boolean    // residue is not a failure
+  maxErrors?: number   // cap the finding list (default 20)
+  schemaUrl?: string   // provenance label for schema sites
+  dataUrl?: string     // provenance label for data sites
+
+  // Where each document CAME FROM, used to resolve its relative
+  // `@"file"` loads -- the file path, as `Aontu({path})` takes it, not
+  // the directory. Vet takes two documents from its caller rather than
+  // from the filesystem, so it cannot know this: without it a modular
+  // schema resolved its includes against the process working
+  // directory, which fails outside that directory and, worse, silently
+  // reads a same-named file that happens to sit there. The two
+  // documents get their OWN bases, because they need not live in the
+  // same place.
+  schemaPath?: string
+  dataPath?: string
+
+  // The trust profile this run evaluates under (G5, docs/trust.md).
+  // Vet's whole job is to evaluate a document its caller did not
+  // write, so the caller must be able to say what that document is
+  // allowed to reach: without this the include chain is the default
+  // one, and `@"x.js"` in hostile data is arbitrary code execution in
+  // the validating process. A server passes `{include:'none'}`.
+  trust?: TrustOptions
+}
+
+
+// The default cap, exported because the CLI applies it to the WHOLE
+// report across several data files and must not carry a second copy of
+// the number (ts/src/cli.ts).
+export const VET_MAX_ERRORS = 20
+
+const DEFAULT_SCHEMA_URL = 'schema'
+const DEFAULT_DATA_URL = 'data'
+
+
+// Every site in a freshly parsed tree carries the same url, and for a
+// bare parse that url is the empty string: `site.url` is only populated
+// by the multisource loader (ts/src/lang.ts). Vet takes two documents
+// from its CALLER, not from the filesystem, so it stamps provenance
+// itself — which is what lets the report assign site ROLES by
+// provenance rather than by NilVal's source-order heuristic, exactly as
+// the design requires.
+// EVERY SITE NAMES THE FILE WHOSE TEXT IT EXCERPTS (the review's
+// finding F, use-cases/BUGS.md §25). The parser already names the file
+// each value was read from -- a value loaded through `@"lib/types.aon"`
+// carries that path, with that file's row and column -- and this walk
+// used to OVERWRITE every url with the entry document's name. The
+// coordinates stayed the included file's, so a finding cited
+// `entry.aon:3:7` for text that lives three files away, at a line the
+// entry may not even have. A repair agent that follows the site edits
+// the wrong file.
+//
+// Only the values that carry no name of their own are stamped: those
+// are the ones the engine minted rather than read, and the entry is
+// the honest name for them. The urls actually seen are collected, so
+// the report can still tell WHICH DOCUMENT a site belongs to without
+// pretending they all came from one file -- see roleOf.
+function stampUrl(v: any, url: string, seen?: Set<string>): Set<string> {
+  const urls = seen ?? new Set<string>()
+  urls.add(url)
+  walkVals(v, (n: any) => {
+    // UNDEFINED counts as unstamped, not just empty: the parser leaves
+    // the url undefined on one of its two paths (ts/src/lang.ts), and
+    // treating that as a name would put `undefined` in the url set --
+    // where the OTHER document's unstamped values would then match it,
+    // and every site would read `data`.
+    if (null == n.site.url || '' === n.site.url) {
+      n.site.url = url
+    }
+    urls.add(n.site.url)
+    return true
+  }, new Set())
+  return urls
+}
+
+
+// The provenance a report projects its sites through: which urls
+// belong to the DATA document, and how the caller reached each of the
+// two documents (which is what says how to NAME a third file either of
+// them included).
+type Prov = {
+  // The urls the data walk reached. Roles are decided by membership,
+  // on the RAW url -- never by a name comparison.
+  data: Set<string>
+  schemaUrl?: string
+  schemaPath?: string
+  dataUrl?: string
+  dataPath?: string
+}
+
+
+// A FILE THE READER CAN OPEN. The parser resolves an include to an
+// absolute path, which is the right identity (two files loading the
+// same library by different relative spellings must be one file) and
+// the wrong NAME: a report whose entry reads `contract.aon` and whose
+// included site reads `/home/someone/checkout/types.aon` is a report
+// that cannot be uploaded as SARIF, diffed between machines, or read
+// beside the command that produced it.
+//
+// So an included file is named as the ENTRY'S OWN NAME reaches it:
+// relative to the entry's directory, then re-anchored on however the
+// caller spelled the entry. `vet contract.aon` names `types.aon`;
+// `vet a/b/contract.aon` names `a/b/types.aon`; an absolute entry
+// keeps absolute includes. A caller who passed no path at all has no
+// base to relativise against and gets the url unchanged.
+export function displayFile(
+  url: string, label: string, path?: string): string {
+  if (url === label || null == path || '' === url || !isAbsolute(url)) {
+    return url
+  }
+  const rel = pathRelative(dirname(pathResolve(path)), url)
+  const dir = dirname(label)
+  return '.' === dir ? rel : pathJoin(dir, rel)
+}
+
+
+// The name for one site, taken from the document the site BELONGS to
+// -- which is the role, already decided by url-set membership. Doing
+// it here rather than from a map built at stamping time is not a
+// shortcut: a nil's operands are off the tree by the time the report
+// is built, so a value first seen during the MEET (the commonest
+// schema site there is) would be missing from any such map.
+function displayOf(file: string, role: VetRole, prov: Prov): string {
+  return 'data' === role
+    ? displayFile(file, prov.dataUrl ?? file, prov.dataPath)
+    : displayFile(file, prov.schemaUrl ?? file, prov.schemaPath)
+}
+
+
+// The ROLE of a site: which of the two documents it belongs to. Not a
+// name comparison -- a data document may itself include another file,
+// and that file's values are still data. Membership of the url set the
+// stamping walk collected is the question, and the answer is `schema`
+// for anything the data walk never reached (an engine-minted value
+// stamped with the schema entry, say).
+function roleOf(file: string, prov: Prov): VetRole {
+  return prov.data.has(file) ? 'data' : 'schema'
+}
+
+
+// `$.a.b`, and `$` for the root. Deliberately NOT delimiter-escaped: a
+// map key may contain any character, including every separator a
+// compact summary might pick, so the path is carried as a JSON string
+// and never parsed back out of a larger token.
+function pathText(path?: string[]): string {
+  return '$' + (null != path && 0 < path.length ? '.' + path.join('.') : '')
+}
+
+
+// `secondary` is the only operand that can be absent — a `closed` or an
+// incomplete finding has one side, a two-site conflict has both — so
+// this is the one nullable input, and every Val that does arrive
+// carries a site and a canon.
+function siteOf(v: any, prov: Prov): VetSite | undefined {
+  if (null == v) {
+    return undefined
+  }
+  // The report's `file` is whatever the site carries, and by the time a
+  // site reaches a report that is always a stamped name: vet walks both
+  // documents before they meet, and the walk reaches the off-peg values
+  // a finding can name (ts/src/walk.ts). A consumer therefore reads
+  // `file` without a presence check, and the Go port -- whose field is
+  // a plain string -- writes the same key.
+  //
+  // NOT coalesced. The parser leaves the url undefined on one of its
+  // two paths (ts/src/lang.ts), and a `?? ''` here would be dead code
+  // that hides it: if a value ever reaches a report unstamped, the two
+  // ports should disagree loudly rather than quietly agree on an empty
+  // name that neither of them meant.
+  const file = v.site.url
+  // NAMED for the reader, ROLED by the raw url: the two questions are
+  // different, and only the first is about how the file is spelled
+  // (see displayFile).
+  const role = roleOf(file, prov)
+  return {
+    file: displayOf(file, role, prov),
+    row: v.site.row,
+    col: v.site.col,
+    len: v.site.len,
+    role,
+    src: v.site.src,
+    value: v.canon,
+  }
+}
+
+
+// The data site first — it is the thing to fix — then the schema site.
+// The underlying NilVal fields are untouched: this is a report-layer
+// projection, so the existing error.tsv assertions do not move.
+function sitesOf(nil: any, prov: Prov): VetSite[] {
+  // `?? nil`: a failure raised about a CONSTRUCT rather than about a
+  // failed meet -- a lossy integer literal, say -- carries no operands
+  // at all, and reporting it about ITSELF is what ctx.adderr already
+  // does for the same reason. Without the fallback the report built a
+  // site out of `undefined` and threw while partitioning it, which is
+  // the one thing vet promises not to do: a bad value in the data is
+  // DATA, and the caller gets a report.
+  const sites: VetSite[] = [siteOf(nil.primary ?? nil, prov) as VetSite]
+
+  const secondary = siteOf(nil.secondary, prov)
+  if (null != secondary) {
+    sites.push(secondary)
+  }
+
+  // Partitioned rather than sorted: which of the two NilVal operands is
+  // `primary` follows source order within one document, which says
+  // nothing useful when one side is a schema and the other is data.
+  return [
+    ...sites.filter((s) => 'data' === s.role),
+    ...sites.filter((s) => 'schema' === s.role),
+  ]
+}
+
+
+// The message text is MATERIALISED on demand, exactly as handleErrors
+// materialises one before a caller sees it: makeNilErr defers it
+// because most NilVals are transient and never rendered, and only the
+// throwing path asks for it. Without this a finding could carry an
+// empty `message` -- which is what the incomplete half of every report
+// did, and what any nil built during the PARSE of a document did.
+function materialise(nil: any, ctx: any): void {
+  if (null == nil.msg || '' === nil.msg) {
+    descErr(nil, ctx)
+  }
+}
+
+
+// The terminal colour escapes the parser puts in its message text. A
+// RegExp built from a string, not a literal: the escape is a control
+// character, and spelling it `\u001b` keeps the source readable.
+const ANSI_RE = new RegExp('\u001b\\[[0-9;]*m', 'g')
+
+function stripAnsi(s: string): string {
+  return s.replace(ANSI_RE, '')
+}
+
+
+function findingOf(nil: any, prov: Prov): VetFinding {
+  const details = nil.details ?? {}
+  const finding: VetFinding = {
+    code: nil.why,
+    class: nil.class,
+    severity: 'error',
+    path: pathText(nil.path),
+    // The HEADLINE only, WITHOUT ANSI: the frames below it are for a
+    // human reading a terminal, and the first line is the part the two
+    // ports hold to byte parity. Materialised before this runs, so it
+    // is always there (see materialise above). The escapes matter for
+    // one family only -- a parse failure's text comes from the parser,
+    // which colours its marker -- and a machine-readable report is no
+    // place for terminal control codes.
+    message: stripAnsi(nil.msg.split('\n')[0]),
+    sites: sitesOf(nil, prov),
+  }
+
+  // The hint, whole, with its detail placeholders filled in exactly as
+  // the terminal frame fills them. Trailing whitespace is dropped
+  // because it is spacing for the frame that used to follow it, not
+  // part of the text; the deliberate blank lines INSIDE a hint are
+  // `\n \n` and survive.
+  const hint = getHint(nil.why, nil.details)
+  if (null != hint && '' !== hint) {
+    finding.hint = stripAnsi(hint).replace(/\s+$/, '')
+  }
+
+  // `expected`/`actual` are the admissible-alternatives contract, and
+  // the constraint algebra already produces them: G1's atoms attach the
+  // normalised residual and the offending value, and `must` attaches
+  // the author's message. Read them where they are rather than
+  // re-deriving them here.
+  if ('string' === typeof details.expected) {
+    finding.expected = details.expected
+  }
+  if ('string' === typeof details.actual) {
+    finding.actual = details.actual
+  }
+  if ('string' === typeof details.message) {
+    finding.note = details.message
+  }
+
+  return finding
+}
+
+
+// Findings are sorted BY VET, not by the walk. The underlying walk
+// iterates raw object keys and the two hosts disagree about their order
+// — `10:… 9:…` yields ["9","10"] in JavaScript, which hoists
+// integer-like keys, against Go's insertion order (ts/src/keyorder.ts
+// exists for exactly this) — so an unsorted report could never be in
+// cross-port parity.
+//
+// The order is by data site (file, row, column), then code, then path.
+// It is carried in ONE key string rather than a cascade of comparisons:
+// the row and column are zero-padded so lexicographic order is numeric
+// order, and NUL joins the fields because no field can contain one.
+// A cascade would need a test per tie-breaker to stay honest; a key
+// needs none, and cannot disagree with itself.
+const ORDER_PAD = 9
+
+
+function pad(n: number): string {
+  return String(n).padStart(ORDER_PAD, '0')
+}
+
+
+// The walk index is the LAST field, which makes every key unique and
+// the sort below total: two findings can otherwise share everything the
+// key carries — same data site, same code, same path — and a comparator
+// that has to answer "equal" is one more thing to get right in two
+// languages. With the index appended, ties simply keep walk order, in
+// both ports, by construction rather than by the sort's promises.
+function orderKey(f: VetFinding, index: number): string {
+  const site = f.sites[0]
+  return [
+    site.file,
+    pad(site.row),
+    pad(site.col),
+    f.code,
+    f.path,
+    pad(index),
+  ].join('\u0000')
+}
+
+
+// A DOCUMENT THAT DOES NOT STAND UP, in the finding shape (the
+// review's finding F). `trim` and `relations` answered an unusable
+// document with `verdict: error` and an EMPTY list: the caller learned
+// that something was wrong and nothing about what, which is the one
+// thing a repair loop cannot work with. Both verbs take ONE document,
+// so there is no role to decide -- the document is the thing being
+// checked and the thing to edit, which is what `data` means here.
+//
+// The engine's own first error IS the finding: these verbs add nothing
+// to a diagnosis the evaluator already made, and the FIRST is enough
+// because everything after it is a consequence.
+//
+// The Go twin is failureFinding in go/vet.go.
+export function failureFinding(
+  ctx: any, url?: string, failed?: any): VetFinding {
+  // ctx.err IS SOMETIMES EMPTY, and the comment that used to stand here
+  // said otherwise (use-cases/BUGS.md §43). `&: id(root)` fails with a
+  // NIL ROOT and NO COLLECTED ERROR -- the id-spread refusal is the
+  // root itself -- and every verb that reports "this document does not
+  // stand up" then read `ctx.err[0]` as undefined and died: a TypeError
+  // out of `relations`, `reaches` and `jsonschema` in TypeScript, a
+  // panic in Go. The one shape where finding F's own invariant, that a
+  // document which does not stand up SAYS SO in the finding shape, was
+  // answered with a stack trace.
+  //
+  // `failed` is the caller's own root -- every caller has it, and its
+  // condition is `0 < ctx.err.length || root.isNil`, so when the first
+  // half is false the second holds and the root IS the reason.
+  const nil: any = ctx.err[0] ?? failed
+  materialise(nil, ctx)
+
+  // STAMPED, as vet stamps both documents before they meet: siteOf does
+  // not coalesce a missing name (deliberately -- see there), so a site
+  // that reached the report unstamped would carry `file: undefined`.
+  // The three Vals a finding can name are the nil and its two operands,
+  // and the url set collects whatever name each already had, so a value
+  // read from an included file keeps that file's name and still counts
+  // as part of the one document being checked.
+  const at = url ?? ''
+  const urls = new Set([at])
+  for (const v of [nil, nil.primary, nil.secondary]) {
+    if (null == v || null == v.site) {
+      continue
+    }
+    if (null == v.site.url || '' === v.site.url) {
+      v.site.url = at
+    }
+    urls.add(v.site.url)
+  }
+
+  return findingOf(nil, { data: urls })
+}
+
+
+// Walk the evaluated schema to the anchor path. `$` and `$.a.b` are
+// both accepted, as is the bare `a.b` a shell is likely to hand over
+// unquoted.
+export function anchorAt(root: any, at: string): Val | undefined {
+  const trimmed = at.startsWith('$') ? at.slice(1) : at
+  const parts = trimmed.split('.').filter((p) => '' !== p)
+
+  let node: any = root
+  for (const part of parts) {
+    // A SIZING RESIDUE IS ITS CONTAINER, plus a note about what the
+    // container must still satisfy (use-cases/BUGS.md §16). The path
+    // steps through it: `$.a.ports.0.port` names the same node whether
+    // or not `ports` still carries a `unique()`, and an anchor that
+    // stopped here would report `no_path` for a key the document
+    // plainly has.
+    node = throughResidue(node)
+
+    // TYPE-DIRECTED, not a property lookup on whatever `peg` happens to
+    // be. An anchor is a STRUCTURAL path into the schema — the same
+    // thing a reference means by `$.a.b` — so it walks map keys and
+    // list indices, and stops at anything else.
+    //
+    // Indexing the peg generically walked much further than that: into
+    // a junction's branches (`a:1|2` with `--at $.a.0` validated
+    // against ONE branch), into a constraint's atom arguments (so
+    // `min(2)` with `--at $.a.0` reported the bound's own argument as
+    // the truth), into a pref's wrapped value through the literal key
+    // `peg`, and into an array's `length` — that last one handing back
+    // a JavaScript NUMBER as the anchor, after which every document
+    // whatsoever came back valid. The Go port has always been
+    // type-directed here; this is the canonical side moving to it.
+    if (true === node?.isMap) {
+      const peg = node.peg
+      if (null == peg || !Object.prototype.hasOwnProperty.call(peg, part)) {
+        return undefined
+      }
+      node = peg[part]
+    }
+    else if (true === node?.isList) {
+      // CANONICAL DECIMAL, the spelling a reference uses for a list
+      // index (`0`, or a non-zero digit run) -- so `$.a.01` names
+      // nothing here exactly as it names nothing there.
+      const peg = node.peg
+      const index = Number(part)
+      if (!/^(0|[1-9][0-9]*)$/.test(part) ||
+        !Array.isArray(peg) || peg.length <= index) {
+        return undefined
+      }
+      node = peg[index]
+    }
+    else {
+      return undefined
+    }
+  }
+
+  // THE ANCHOR KEEPS ITS ATOM. Stepping THROUGH a residue is right --
+  // `$.x.a` names a key of the container whatever the container still
+  // has to satisfy -- but ARRIVING at one and handing back the bare
+  // container drops a constraint the author wrote, so `--at $.x` vetted
+  // clean against a `length` the evaluator enforces. The residue is the
+  // honest schema for the node: the meet drives it, and generation
+  // settles it, exactly as it does without an anchor.
+  return node
+}
+
+
+// The container inside a settled sizing residue, or the value itself.
+function throughResidue(v: any): any {
+  return sizingResidue(v)?.bag ?? v
+}
+
+
+// Validate `dataSrc` against `schemaSrc`.
+//
+// Never throws for findings: a contradiction in the data is DATA, and
+// the caller gets a report. It throws only when the caller's own inputs
+// are unusable — which is why an unusable schema is a verdict (`error`)
+// rather than an exception too: "the schema is broken" is a fact the
+// agent loop needs to branch on, not an exceptional condition.
+export function vet(
+  schemaSrc: string, dataSrc: string, opts?: VetOptions): VetReport {
+  const options = opts ?? {}
+  const schemaUrl = options.schemaUrl ?? DEFAULT_SCHEMA_URL
+  const dataUrl = options.dataUrl ?? DEFAULT_DATA_URL
+  const maxErrors = options.maxErrors ?? VET_MAX_ERRORS
+
+  // ONE instance, two bases: the path rides on each CALL rather than on
+  // the constructor, because the schema and the data may live in
+  // different directories (Lang.parse takes `opts.path` per parse).
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const schemaOpts = null == options.schemaPath ?
+    undefined : { path: options.schemaPath }
+  const dataOpts = null == options.dataPath ?
+    undefined : { path: options.dataPath }
+
+  // 1. The schema alone. If it does not stand up on its own, the data
+  //    is never blamed for it.
+  const schemaCtx = aontu.ctx({ collect: true })
+  const schemaVal: any = aontu.unify(schemaSrc, schemaOpts, schemaCtx)
+  if (0 < schemaCtx.err.length || true === schemaVal?.isNil) {
+    // A broken schema REPORTS, exactly as broken data does. It used to
+    // answer `findings: []` with exit 4 and nothing else, in both
+    // ports: the engine had collected the fault and vet threw it away,
+    // so an agent -- or a person -- was told the schema was broken and
+    // not what or where. The verdict stays `error` (the fault is in
+    // the truth, not in the data, and that distinction is the whole
+    // point of the class), but the finding travels with it.
+    //
+    // The FIRST error only, and the data path's reasoning applies
+    // unchanged: later errors in a document that does not stand up are
+    // consequences of the first rather than separate things to fix.
+    //
+    // ONE OF THE TWO IS ALWAYS THERE, and both are nils: the branch
+    // condition admits a collected error or a nil root, and every
+    // value on `schemaCtx.err` is a NilVal. There is no third case, so
+    // there is no guard here -- a guard that cannot fire is dead code,
+    // and dead code is what ADR-002 exists to keep out. (One stood
+    // here and the TypeScript line report called it covered; the Go
+    // gate, which measures blocks, refused the twin.)
+    const failure: any =
+      0 < schemaCtx.err.length ? schemaCtx.err[0] : schemaVal
+    // The normal path stamps both documents before they meet
+    // (stampUrl(anchor...) below), and this early return never reaches
+    // it, so it stamps what it is about to report: the unified root,
+    // and the failure itself -- a COLLECTED error is minted during
+    // unification and hangs off no tree, so nothing else would name
+    // it. The walk reaches a failure's operands (ts/src/walk.ts),
+    // which is what makes the sites say which file.
+    stampUrl(schemaVal, schemaUrl)
+    stampUrl(failure, schemaUrl)
+    materialise(failure, schemaCtx)
+    return {
+      verdict: 'error',
+      truncated: false,
+      // A schema that does not stand up: nothing here is data, so the
+      // data-url set is empty and every site reads `schema`.
+      findings: [findingOf(failure, { data: new Set<string>() })],
+    }
+  }
+
+  // 2. The anchor: the whole schema, or the value at `--at`.
+  let anchor: any = schemaVal
+  if (null != options.at) {
+    anchor = anchorAt(schemaVal, options.at)
+    if (null == anchor) {
+      // AND IT SAYS WHICH SEGMENT. `--at` naming nothing is an error
+      // verdict for the same reason a broken schema is -- the run
+      // could not be set up from the truth's side -- and it reports
+      // for the same reason too: a caller handed exit 4 and an empty
+      // list has nothing to act on.
+      return {
+        verdict: 'error',
+        truncated: false,
+        findings: [noPathFinding(schemaVal, options.at)],
+      }
+    }
+  }
+
+  // 3. Both documents get their provenance stamped BEFORE they meet, so
+  //    every site in the result knows which document it came from.
+  const dataCtx = aontu.ctx({ collect: true })
+  const dataVal: any = aontu.parse(dataSrc, dataOpts, dataCtx)
+  if (0 < dataCtx.err.length || null == dataVal) {
+    // A DATA DOCUMENT THAT WILL NOT PARSE IS THE DATA'S FAULT, and the
+    // report says so: verdict `invalid`, with a finding carrying the
+    // parser's own code and a site in the data. `error` is left to mean
+    // what the exit table says it means -- the run could not be set up
+    // from the SCHEMA side.
+    //
+    // The engine already answered it this way one character earlier: a
+    // refused CONSTRUCT (`a: 9007199254740993`) reaches the tree as an
+    // ordinary nil and is reported as an invalid data finding. A stray
+    // `]` took the throwing path instead and came back as a broken
+    // SCHEMA -- the same fault, classified two opposite ways by which
+    // branch the parser happened to take.
+    //
+    // The FIRST error only: the parser stops at the first syntax error,
+    // so a second entry would be a consequence of the first rather than
+    // a separate thing to fix.
+    const failure = dataCtx.err[0]
+    if (null == failure) {
+      return { verdict: 'error', truncated: false, findings: [] }
+    }
+    failure.site.url = dataUrl
+    materialise(failure, dataCtx)
+    return {
+      verdict: 'invalid',
+      truncated: false,
+      findings: [findingOf(failure, { data: new Set([dataUrl]) })],
+    }
+  }
+  stampUrl(anchor, schemaUrl)
+  const dataUrls = stampUrl(dataVal, dataUrl)
+  // The projection every site in this report goes through: roles by
+  // url-set membership, names by how the caller reached each document.
+  const prov: Prov = {
+    data: dataUrls,
+    schemaUrl, schemaPath: options.schemaPath,
+    dataUrl, dataPath: options.dataPath,
+  }
+
+  // Default-validity lint (G3 phase 5, re-examined under ADR-004): for
+  // every disjunction in the SCHEMA carrying a preference, warn when
+  // the effective default is not an instance of any REMAINING
+  // alternative (code `pref_not_instance`, class compat, severity
+  // warning).
+  //
+  // What the finding MEANS changed with the admission gate (ADR-004).
+  // Before the gate it flagged a soundness hole: the preference held
+  // the disjunction open, so `a:*5|string` both generated a value the
+  // alternatives refuse AND admitted any same-kind override. The gate
+  // closed that hole — a preferred branch now contributes exactly its
+  // own value to the admitted set, so a default can no longer be
+  // "invalid against its own disjunct" and the enum-with-default idiom
+  // (`*'auto'|'literal'|'data'`) is sound as written. The lint is KEPT,
+  // as an advisory: a default admitted only because it is the default
+  // is also the exact shape of a typo'd default
+  // (`level:*wran|info|warn|debug` — the intended `*warn` would be
+  // silent), and nothing at meet time can catch that. The
+  // repeated-branch spelling (`*warn|warn|...`) states "the default is
+  // a first-class member", silences the lint, and — unlike before the
+  // gate — enforces exactly the same admitted set. The message names
+  // the REMAINING alternatives because that is what was scanned: the
+  // preferred branch itself always admits its own default, so the old
+  // wording ("any alternative of *5|string") read as false on its face
+  // (use-cases/BUGS.md §4).
+  const lintFindings: VetFinding[] = []
+  walkBagVals(anchor, (v: any, path: string[]): void => {
+    if (true === v.isDisjunct && Array.isArray(v.peg)) {
+      const d = effectiveDefault(v)
+      if (null != d && 'indeterminate' !== d) {
+        const rest = v.peg.filter((m: any) => true !== m?.isPref)
+        const state: any = {
+          profile: 'values', findings: [],
+          generalUrl: schemaUrl, specificUrl: schemaUrl,
+        }
+        const admitted = rest.some(
+          (m: any) => 'yes' === subsumeNode(state, path, m, d))
+        if (!admitted && 0 < rest.length) {
+          lintFindings.push({
+            code: 'pref_not_instance',
+            class: 'compat',
+            severity: 'warning',
+            path: pathText(path),
+            message: 'the default ' + d.canon +
+              ' is not an instance of any remaining alternative of ' +
+              v.canon,
+            sites: [{
+              file: schemaUrl,
+              row: d.site?.row ?? -1,
+              col: d.site?.col ?? -1,
+              len: d.site?.len ?? -1,
+              role: 'schema',
+              src: d.site?.src ?? '',
+              value: d.canon,
+            }],
+          })
+        }
+      }
+    }
+  })
+
+  // `--closed` sets the flag `close()` itself sets, rather than wrapping
+  // the anchor in a CloseFuncVal: the anchor is an already-evaluated
+  // tree, and a func value would have to resolve again to have any
+  // effect. A scalar anchor has no keys to close, so the flag is only
+  // meaningful on a bag.
+  if (true === options.closed && (true === anchor.isMap || true === anchor.isList)) {
+    anchor.closed = true
+  }
+
+  // THE MEET IS FROM A FRESH PARSE, NOT THE SETTLED SCHEMA (the
+  // review's finding C, use-cases/BUGS.md §15).
+  //
+  // Step 1 evaluated the schema ALONE, to decide whether it stands up
+  // before any data is blamed for it. That answer is a diagnosis, and
+  // it was also being used as the left side of the meet -- so every
+  // reference in the schema had already RESOLVED against the schema's
+  // own values and been replaced by them. `a:integer b:$.a` settled to
+  // `a:integer b:integer`, and data `{a:3,b:4}` then vetted VALID,
+  // while the same four lines as one document refuse with
+  // scalar_value. A reference is a statement about the FINAL model, and
+  // vet is asking about a model the data is part of.
+  //
+  // Parsing again is what makes `vet(S,D)` and `eval(S ∪ D)` the same
+  // question: the meet runs the fixpoint once, over both documents, so
+  // references, spreads and generators all see the data. Parsed trees
+  // are single-use, hence a second parse rather than a reuse of step
+  // 1's. The lint above still reads the SETTLED tree, where
+  // disjunctions are ranked and normalised.
+  //
+  // ONLY WHEN THERE IS NO `--at`. An anchor is a SUBTREE lifted out of
+  // the schema, and an absolute reference inside it (`$.OrderPlaced`,
+  // the discriminated-union idiom) names a sibling of the document
+  // root -- which the lifted subtree no longer has. The settled tree is
+  // where those references have already been resolved and substituted,
+  // so an anchored run keeps meeting that, exactly as it always has.
+  // Making the rule explicit rather than leaving it to whether
+  // anchorAt happens to find the path in an unresolved tree: the two
+  // ports answered that differently, which is an ADR-001 divergence
+  // waiting to happen.
+  const ctx = aontu.ctx({ collect: true })
+  let meetAnchor: any = anchor
+  if (null == options.at) {
+    const meetCtx = aontu.ctx({ collect: true })
+    const freshSchema: any = aontu.parse(schemaSrc, schemaOpts, meetCtx)
+    if (0 === meetCtx.err.length && null != freshSchema) {
+      meetAnchor = freshSchema
+      if (true === options.closed &&
+        (true === meetAnchor.isMap || true === meetAnchor.isList)) {
+        meetAnchor.closed = true
+      }
+      stampUrl(meetAnchor, schemaUrl)
+    }
+  }
+  const pair = new ConjunctVal({ peg: [meetAnchor, dataVal] }, ctx)
+  const unified: any = aontu.unify(pair, undefined, ctx)
+
+  // 4. Contradictions: every NilVal standing in the result, PLUS the
+  //    ones that never made it into the tree.
+  //
+  // The second half is not belt-and-braces. When a parent collapses to
+  // a nil the whole subtree goes with it, so `service: close({...})`
+  // meeting a typo AND a kind conflict leaves ONE nil in the tree and
+  // reports the other only on the context — the vet verb's own
+  // motivating example, reporting half of what it found. The language
+  // server already walks both for this reason; vet dedups by identity
+  // the same way, and skips the transient disjunct-trial sentinel,
+  // which is bookkeeping rather than a finding.
+  const seen = new Set<any>()
+  const nils: any[] = collectNils(unified, seen)
+  for (const err of ctx.err) {
+    if (true === err?.isNil && '|:trial-nil' !== err.why && !seen.has(err)) {
+      seen.add(err)
+      nils.push(err)
+    }
+  }
+
+  const findings: VetFinding[] = nils.map((n) => {
+    materialise(n, ctx)
+    return findingOf(n, prov)
+  })
+
+  // 5. Incompleteness: what is left standing that cannot generate. The
+  //    generate check runs in its own collect context so nothing it
+  //    raises reaches the caller's error list, and so a schema that is
+  //    merely unsatisfied does not look like one that is contradicted.
+  // No try/catch: in collect mode `gen` records its reasons on the
+  // context instead of throwing, which is the whole point of the mode.
+  const genCtx: any = aontu.ctx({ collect: true })
+  genCtx.root = unified
+  // Under `--at` the probe descends through the OUTPUT marks: the
+  // caller named this node as the truth to validate against, so a
+  // `type()` or `hide()` on it (or propagated into it) is not a reason
+  // to check nothing. See AontuContext.probe.
+  genCtx.probe = null != options.at
+  unified.gen(genCtx)
+  for (const err of genCtx.err) {
+    // A CONFLICT RAISED AT GENERATION COUNTS TOO (the review's finding
+    // C, use-cases/BUGS.md §16). The filter used to keep the
+    // `incomplete` class alone, on the reading that step 4 had already
+    // found every contradiction -- true while every conflict was
+    // decided during the meet, and untrue since a sizing atom or a
+    // container `must` may hold a PROVISIONAL reading until generation,
+    // which is where no more members can arrive. Dropping those left
+    // `vet` answering `valid` for data the evaluator refuses, which is
+    // the one disagreement the vet-equals-eval harness exists to catch
+    // -- and did.
+    //
+    // Deduped against step 4 by the same cause key the loop below uses,
+    // so a contradiction seen twice is still reported once.
+    if ('incomplete' === err.class || 'conflict' === err.class) {
+      materialise(err, genCtx)
+      findings.push(findingOf(err, prov))
+    }
+  }
+
+  // 5b. Deprecation warnings (G3 phase 4): a value that carries the
+  //     deprecate() record after the meet was USED — the data met a
+  //     deprecated schema value, or the schema's own default will
+  //     generate one. Severity `warning` (the slot G2 reserved for
+  //     exactly this mark), and warnings never touch the verdict below.
+  findings.push(...lintFindings)
+  for (const { val, path } of collectDeprecations(unified)) {
+    const v: any = val
+    // The same file/role projection sitesOf makes: the url as stamped
+    // (empty when the value belongs to neither document), the role by
+    // comparing it to the data document's.
+    const file = v.site.url
+    findings.push({
+      code: 'deprecated',
+      class: 'compat',
+      severity: 'warning',
+      path: pathText(path),
+      message: deprecationMessage(v.deprecation),
+      sites: [{
+        file: displayOf(file, roleOf(file, prov), prov),
+        row: v.site.row ?? -1,
+        col: v.site.col ?? -1,
+        len: v.site.len ?? -1,
+        role: roleOf(file, prov),
+        src: v.site.src ?? '',
+        value: v.canon,
+      }],
+    })
+  }
+
+  const keyed = findings.map((f, i) => ({ key: orderKey(f, i), finding: f }))
+  keyed.sort((a, b) => a.key < b.key ? -1 : 1)
+  let ordered = keyed.map((k) => k.finding)
+
+  // ONE CAUSE, ONE FINDING. A reference resolves by CLONING its target,
+  // so a target that later fails can fail once per referrer — same
+  // code, same two source sites, a different path each time. Multi-pass
+  // collection (G2 phase 6) made this reachable: the pass loop now
+  // continues past the erroring pass, so the clones' own folds run too.
+  // The dedup key is the CODE plus the SITES (file, row, col, value,
+  // role): two findings that name the same meet of the same two source
+  // positions are one contradiction observed from two paths. The key is
+  // NOT (code, path) — the design's sketch — because the paths are
+  // exactly what differ. Sorted order makes the kept finding the first
+  // by data site then path, deterministically in both ports.
+  //
+  // THE KEPT PATH IS THE DEEPEST one (use-cases/BUGS.md §41). A meet
+  // that fails inside a REFERENCED map is recorded twice: once at the
+  // key that actually conflicts, and once at the enclosing map, which
+  // collapsed as a consequence and carries the child's two sites. Both
+  // are the same cause; only the deeper one names the field an author
+  // or an agent has to edit, and `$.q` for a conflict in `$.q.a` sent a
+  // repair loop to rewrite the whole record -- twice over, identically,
+  // when two of its fields conflicted. Depth first, then the sort order
+  // above, so the choice stays deterministic in both ports.
+  const causeKey = (f: VetFinding): string =>
+    f.code + '\u0000' + f.sites.map((s) =>
+      [s.file, s.row, s.col, s.role, s.value].join('\u0000')).join('\u0000')
+  const depth = (f: VetFinding): number => f.path.split('.').length
+  const deepest = new Map<string, VetFinding>()
+  for (const f of ordered) {
+    const cause = causeKey(f)
+    const held = deepest.get(cause)
+    if (null == held || depth(held) < depth(f)) {
+      deepest.set(cause, f)
+    }
+  }
+  const causes = new Set<string>()
+  ordered = ordered.filter((f) => {
+    const cause = causeKey(f)
+    if (causes.has(cause) || deepest.get(cause) !== f) {
+      return false
+    }
+    causes.add(cause)
+    return true
+  })
+
+  const truncated = maxErrors < ordered.length
+  const kept = truncated ? ordered.slice(0, maxErrors) : ordered
+
+  // 6. The verdict derives from finding CLASSES, never from codes, so a
+  //    new code can never change exit behaviour.
+  //
+  // BY CLASS, NOT BY STAGE. The split used to be positional -- whatever
+  // step 4 found counted as contradiction and whatever step 5 added
+  // counted as incompleteness -- which stopped being true when a sizing
+  // atom or a container `must` began holding a provisional reading
+  // until generation (the review's finding C, use-cases/BUGS.md §16). A
+  // CONTRADICTION found at generation is still a contradiction: reading
+  // it as mere incompleteness answered `incomplete` where the evaluator
+  // refuses, and `vet` and `eval` have to agree.
+  //
+  // So: an error-severity finding that is not INCOMPLETENESS makes the
+  // document invalid, wherever it was found -- a contradiction, a parse
+  // refusal, an unresolvable reference alike. Warnings (the `compat`
+  // class: lint and deprecation) never touch the verdict.
+  let verdict: VetVerdict = 'valid'
+  const errors = ordered.filter((f) => 'error' === f.severity)
+  const unmet = errors.filter((f) => 'incomplete' === f.class).length
+  if (unmet < errors.length) {
+    verdict = 'invalid'
+  }
+  else if (0 < unmet && true !== options.partial) {
+    verdict = 'incomplete'
+  }
+
+  return { verdict, truncated, findings: kept }
+}