aontu 0.53.0 → 0.55.0

package/src/lsp.ts

@@ -270,6 +270,7 @@ function initializeResult() {
       textDocumentSync: 1,
       hoverProvider: true,
       completionProvider: {},
+      signatureHelpProvider: { triggerCharacters: ['(', ','] },
     },
     serverInfo: {
       name: 'aontu-lsp',
@@ -279,6 +280,59 @@ function initializeResult() {
 }
 
 
+// signatureHelp: the declared signature of the ENCLOSING call, served
+// from the registry (docs/design/SIGNATURES.0.md). The enclosing call
+// is found lexically -- scan back from the cursor for the nearest
+// unclosed '(' and read the word before it; commas at that depth
+// count the active parameter, capped at the last slot so a rest tail
+// stays active for every excess argument. Strings are skipped so a
+// paren or comma inside one does not miscount, and the scan stops at
+// the line start, a call being one line in practice.
+function computeSignatureHelp(text: string, pos: any): any {
+  // Position to offset, under the full-sync model: lines are exactly
+  // the text's newlines.
+  const lines = text.split('\n')
+  const line = Math.max(0, Math.min(Number(pos.line) || 0, lines.length - 1))
+  let offset = 0
+  for (let li = 0; li < line; li++) {
+    offset += lines[li].length + 1
+  }
+  offset += Math.max(0, Math.min(Number(pos.character) || 0, lines[line].length))
+  let depth = 0
+  let commas = 0
+  let open = -1
+  for (let i = offset - 1; 0 <= i; i--) {
+    const c = text[i]
+    if ('"' === c || "'" === c) {
+      for (i--; 0 <= i && text[i] !== c; i--) { }
+      continue
+    }
+    if (')' === c) { depth++ }
+    else if ('(' === c) {
+      if (0 === depth) { open = i; break }
+      depth--
+    }
+    else if (',' === c && 0 === depth) { commas++ }
+    else if ('\n' === c && 0 === depth) { break }
+  }
+  if (0 > open) { return null }
+  let start = open
+  while (0 < start && /[a-zA-Z0-9_]/.test(text[start - 1])) { start-- }
+  const name = text.slice(start, open)
+  const sig = funcSig[name]
+  if (undefined === sig) { return null }
+  const last = sig.args.length - 1
+  return {
+    signatures: [{
+      label: renderSig(sig),
+      parameters: sig.args.map((a) => ({ label: renderSigArg(a) })),
+    }],
+    activeSignature: 0,
+    activeParameter: Math.min(commas, 0 <= last ? last : 0),
+  }
+}
+
+
 function publishDiagnosticsMsg(uri: string, diagnostics: Diagnostic[]): OutMessage {
   return {
     jsonrpc: '2.0',
@@ -457,23 +511,26 @@ type CompletionItem = {
   detail?: string
 }
 
+import { funcSig, renderSig, renderSigArg } from './sig'
+
 // LSP CompletionItemKind subset.
 const COMPLETION_FUNCTION = 3
 const COMPLETION_KEYWORD = 14
 
-// The twenty-eight built-in functions. Kept in sync with the engine by
+// The built-in functions. Kept in sync with the engine by
 // `lsp.test.ts`, which asserts each is recognised and no others are.
 // The Go port derives its list from the engine's own name set
 // (`BuiltinFuncNames`, go/func.go), which is why a name added there
 // and forgotten here diverges silently — as `id` and `refer` did
 // between G4 phases 1/2 and G8 phase 1.
 const BUILTIN_FUNCS = [
-  'above', 'add', 'below', 'close', 'copy', 'deprecate', 'div', 'each',
+  'above', 'acyclic', 'add', 'below', 'close', 'copy', 'deprecate', 'div',
+  'each',
   'filter', 'greatest',
-  'hide', 'id', 'key', 'least', 'length', 'lower',
-  'match', 'max', 'min', 'mod', 'move', 'mul', 'must', 'neq', 'open',
+  'hide', 'inverse', 'join', 'key', 'least', 'length', 'list', 'lower',
+  'map', 'match', 'max', 'min', 'mod', 'move', 'mul', 'must', 'neq', 'open',
   'pack', 'path', 'pick',
-  'pref', 're', 'refer', 'rem', 'sub', 'sum', 'super', 'type', 'unique',
+  'pref', 're', 'refer', 'rel', 'rem', 'sub', 'sum', 'super', 'type', 'unique',
   'upper',
 ]
 
@@ -493,7 +550,10 @@ const LITERAL_KEYWORDS = ['_', 'true', 'false', 'null', 'top']
 function computeCompletions(): CompletionItem[] {
   const out: CompletionItem[] = []
   for (const f of BUILTIN_FUNCS) {
-    out.push({ label: f, kind: COMPLETION_FUNCTION, detail: 'Aontu built-in function' })
+    // The detail is the rendered SIGNATURE (docs/design/SIGNATURES.0.md)
+    // -- the same renderer the hints and the docs table use, so the
+    // completion list cannot drift from the declaration.
+    out.push({ label: f, kind: COMPLETION_FUNCTION, detail: renderSig(funcSig[f]) })
   }
   for (const k of KIND_KEYWORDS) {
     out.push({ label: k, kind: COMPLETION_KEYWORD, detail: 'scalar kind' })
@@ -695,6 +755,15 @@ class LspHandler {
       case 'textDocument/completion':
         return [{ jsonrpc: '2.0', id: msg.id, result: computeCompletions() }]
 
+      case 'textDocument/signatureHelp': {
+        const uri = msg.params?.textDocument?.uri
+        const pos = msg.params?.position
+        const text = null != uri ? this.docs.get(uri) : undefined
+        const help = (null != text && null != pos)
+          ? computeSignatureHelp(text, pos) : null
+        return [{ jsonrpc: '2.0', id: msg.id, result: help }]
+      }
+
       default:
         // Unknown request (has an id): reply method-not-found. Unknown
         // notification: ignore.

package/src/mcp.ts

@@ -48,6 +48,7 @@ import { trimCheck } from './trim'
 import { jsonSchema } from './jsonschema'
 import { relationCheck } from './relation'
 import { reachCheck } from './reach'
+import { view } from './view'
 import { patch } from './patch'
 
 
@@ -114,7 +115,9 @@ export type ToolDef = {
 // applied by each tool for itself. That is deliberate: four of the six
 // original tools once called the library with no profile at all, so a
 // served `@"x.js"` was require()d in the server process, while the
-// module header claimed confinement. A tool that must remember to
+// module header claimed confinement. (That particular include is
+// refused outright now -- ADR-012 -- but a served document could still
+// read every file the server can.) A tool that must remember to
 // confine itself is a tool that eventually forgets, and the forgetting
 // is silent. With the profile arriving as an argument, a tool cannot
 // run unconfined without visibly discarding it.
@@ -408,7 +411,7 @@ const TOOLS: ToolDef[] = [
     name: 'relations',
     description:
       'Check the declared relations of a finished model: acyclicity ' +
-      'and inverse consistency over the entity edge set. Returns ' +
+      'and inverse consistency over the link edge set. Returns ' +
       'verdict (pass | fail | error) and relation findings.',
     properties: {
       source: { type: 'string', description: 'The document' },
@@ -428,16 +431,16 @@ const TOOLS: ToolDef[] = [
   {
     name: 'reaches',
     description:
-      'Ask whether one entity reaches another over the entity graph, ' +
+      'Ask whether one node reaches another over the link graph, ' +
       'at any remove — the closure question `relations` cannot ask one ' +
       'edge at a time (blast radius, containment). Returns verdict ' +
       '(reaches | unreachable | error) and, when it reaches, a shortest ' +
-      'path. Transitive, not reflexive: an entity reaches itself only ' +
+      'path. Transitive, not reflexive: a node reaches itself only ' +
       'through a cycle.',
     properties: {
       source: { type: 'string', description: 'The document' },
-      from: { type: 'string', description: 'The entity to start at' },
-      to: { type: 'string', description: 'The entity to look for' },
+      from: { type: 'string', description: 'The node path to start at' },
+      to: { type: 'string', description: 'The node path to look for' },
       relation: {
         type: 'string',
         description: 'Follow only edges under this relation (optional)',
@@ -452,6 +455,161 @@ const TOOLS: ToolDef[] = [
         relation: null == a.relation ? undefined : str(a.relation),
       }),
   },
+  {
+    name: 'view',
+    description:
+      'Draw a figure of the document as deterministic text. Kinds: ' +
+      'tree (the dependency tree of a relation), matrix (the ' +
+      'dependency matrix, canon or partition order, --closure), graph ' +
+      '(node-link, as mermaid, dot or er), layer (the architecture ' +
+      'layers as stacked bands, groupBy naming the layer field), sets ' +
+      '(the set-intersection ' +
+      'panel over a set family), layers (which document contributed ' +
+      'which path), ladder (the meet ladder at a path). Returns ' +
+      'verdict (rendered | lossy | error), kind, the text, and the ' +
+      'loss report. The poset kind compares several files and is CLI ' +
+      'only.',
+    properties: {
+      source: { type: 'string', description: 'The document' },
+      kind: {
+        type: 'string',
+        description:
+          'The figure to draw: tree (the default), matrix, graph, layer, ' +
+          'sets, layers or ladder',
+      },
+      as: {
+        type: 'string',
+        description:
+          'The target grammar: text, mermaid, dot, er or svg, per kind ' +
+          '(optional; the kind\'s default otherwise)',
+      },
+      at: {
+        type: 'string',
+        description:
+          'Restrict the figure to nodes under this path; the path the ' +
+          'ladder draws (optional)',
+      },
+      relation: {
+        type: 'string',
+        description:
+          'Draw the tree or matrix over this relation only; keep this ' +
+          'predicate in the graph (optional)',
+      },
+      root: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'Draw only the subtrees under these node paths (optional)',
+      },
+      order: {
+        type: 'string',
+        description: 'matrix: canon (the default) or partition (optional)',
+      },
+      closure: {
+        type: 'boolean',
+        description: 'matrix: mark transitively reachable cells (optional)',
+      },
+      groupBy: {
+        type: 'string',
+        description:
+          'graph: one subgraph per value of this field (optional); ' +
+          'layer: one band per value (required)',
+      },
+      label: {
+        type: 'string',
+        description: 'graph: label each node with this field (optional)',
+      },
+      edges: {
+        type: 'string',
+        description:
+          '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 (optional)',
+      },
+      layers: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'layer: the bands in this order, top first (optional)',
+      },
+      sets: {
+        type: 'string',
+        description: 'sets: the map whose keys are the sets',
+      },
+      member: {
+        type: 'string',
+        description: 'sets: the field holding each set\'s members',
+      },
+      universe: {
+        type: 'string',
+        description: 'sets: the full element domain (optional)',
+      },
+      depth: {
+        type: 'integer',
+        description: 'doc: how many levels of key to draw (default 3)',
+      },
+      maxRows: {
+        type: 'integer',
+        description: 'Refuse a figure above this many rows (default 60)',
+      },
+      style: {
+        type: 'string',
+        description:
+          'How the figure carries the meaning of its marks: none, ansi ' +
+          '(SGR escapes, text only) or css (classes and the embedded ' +
+          'stylesheet, svg only). Absent means the profile\'s own ' +
+          'default -- svg keeps its stylesheet, everything else has no ' +
+          'mechanism. There is no auto here: resolving it needs a ' +
+          'terminal, which a server does not have (optional)',
+      },
+    },
+    required: ['source'],
+    docs: ['source'],
+    check: (a) => {
+      const kinds = ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets',
+        'layers', 'ladder']
+      if (null != a.kind && !kinds.includes(a.kind)) {
+        return `kind must be one of ${kinds.join(', ')}, not ${JSON.stringify(a.kind)}`
+      }
+      const profiles = ['text', 'mermaid', 'dot', 'er', 'svg']
+      if (null != a.as && !profiles.includes(a.as)) {
+        return `as must be one of ${profiles.join(', ')}, not ${JSON.stringify(a.as)}`
+      }
+      const edges = ['upward', 'all', 'none']
+      if (null != a.edges && !edges.includes(a.edges)) {
+        return `edges must be one of ${edges.join(', ')}, not ${JSON.stringify(a.edges)}`
+      }
+      const styles = ['none', 'ansi', 'css']
+      if (null != a.style && !styles.includes(a.style)) {
+        return `style must be one of ${styles.join(', ')}, not ${JSON.stringify(a.style)}`
+      }
+      return undefined
+    },
+    refuse: (a, finding) =>
+      ({ verdict: 'error', kind: a.kind ?? 'tree', loss: [], errors: [finding] }),
+    run: (a, trust, paths) =>
+      view(str(a.source), {
+        kind: null == a.kind ? 'tree' : a.kind,
+        as: null == a.as ? undefined : a.as,
+        at: null == a.at ? undefined : str(a.at),
+        path: paths.source,
+        trust,
+        relation: null == a.relation ? undefined : str(a.relation),
+        relations: null == a.relation ? undefined : [str(a.relation)],
+        roots: Array.isArray(a.root) ? a.root.map(str) : undefined,
+        order: null == a.order ? undefined : a.order,
+        closure: true === a.closure,
+        groupBy: null == a.groupBy ? undefined : str(a.groupBy),
+        label: null == a.label ? undefined : str(a.label),
+        layers: Array.isArray(a.layers) ? a.layers.map(str) : undefined,
+        edges: null == a.edges ? undefined : a.edges,
+        sets: null == a.sets ? undefined : str(a.sets),
+        member: null == a.member ? undefined : str(a.member),
+        universe: null == a.universe ? undefined : str(a.universe),
+        depth: 'number' === typeof a.depth ? a.depth : undefined,
+        maxRows: 'number' === typeof a.maxRows ? a.maxRows : undefined,
+        style: null == a.style ? undefined : a.style,
+      }),
+  },
   {
     name: 'hash',
     description:

package/src/mod-tool.ts

@@ -24,7 +24,9 @@ import {
 } from 'node:fs'
 import { join as pathJoin, dirname as pathDirname } from 'node:path'
 
-import { parseModuleRef, moduleDir, lockJson } from './mod'
+import {
+  parseModuleRef, validateModulePath, moduleDir, lockJson,
+} from './mod'
 import { subsume } from './subsume'
 import type { ModuleRef } from './mod'
 
@@ -162,6 +164,30 @@ export function versionCompare(a: string, b: string): number {
 }
 
 
+// A dependency or lockfile key as a module ref this tooling may ACT
+// on, or undefined.
+//
+// Two ways to be unusable, one answer. A key that is not module-shaped
+// names nothing the resolver can find; a key that is shaped but whose
+// path cannot legally be a directory (`..` in it, a reserved device
+// name) must not be turned into one, which is the whole of the
+// traversal fix on this side. Both land in the caller's `missing`
+// bucket, because from the report's point of view they are the same
+// fact: the lockfile names something that cannot be resolved here.
+//
+// A STALE LOCKFILE IS THE REASON THIS EXISTS AT ALL. `resolveModule`
+// gates the evaluator, but `tidy`, `verify` and `vendor` read a
+// lockfile straight off disk -- one that may have been committed
+// before the gate existed -- so the gate has to be here too.
+function usableRef(mod: string): ModuleRef | undefined {
+  const ref = parseModuleRef(mod)
+  if (undefined === ref || undefined !== validateModulePath(ref.path)) {
+    return undefined
+  }
+  return ref
+}
+
+
 // The directory a module is in, in the local stores: the project's
 // vendor tree first, then the cache under the hash the lockfile pins.
 function storeDir(
@@ -245,11 +271,11 @@ export function modTidy(root: string, options: ModToolOptions): ModTidyReport {
       }
       selected[mod] = want
 
-      const ref = parseModuleRef(mod)
+      const ref = usableRef(mod)
       if (undefined === ref) {
-        // A dependency key that is not a module path names nothing this
-        // resolver can find, which is the same answer as a module that
-        // is not there.
+        // A dependency key this tooling cannot act on names nothing
+        // this resolver can find, which is the same answer as a module
+        // that is not there (see usableRef).
         missing.push(mod)
         continue
       }
@@ -278,7 +304,7 @@ export function modTidy(root: string, options: ModToolOptions): ModTidyReport {
     if (missing.includes(mod)) {
       continue
     }
-    const ref = parseModuleRef(mod) as ModuleRef
+    const ref = usableRef(mod) as ModuleRef
     const dir = storeDir(root, ref, previous[mod]?.canon ?? '', options) as string
     const main = pathJoin(dir, mainOf(dir, options))
     // RECOMPUTED, never carried over: the pin is what the module in
@@ -374,7 +400,7 @@ export function modVerify(root: string, options: ModToolOptions):
     .filter((mod) => null == locked[mod]).sort()
 
   for (const mod of Object.keys(locked).sort()) {
-    const ref = parseModuleRef(mod)
+    const ref = usableRef(mod)
     if (undefined === ref) {
       missing.push(mod)
       continue
@@ -422,8 +448,10 @@ export function modVendor(root: string, options: ModToolOptions):
   const vendored: string[] = []
   const missing: string[] = []
 
+  const vendorRoot = pathJoin(root, 'aon_vendor')
+
   for (const mod of Object.keys(locked).sort()) {
-    const ref = parseModuleRef(mod)
+    const ref = usableRef(mod)
     if (undefined === ref) {
       missing.push(mod)
       continue
@@ -435,7 +463,18 @@ export function modVendor(root: string, options: ModToolOptions):
       continue
     }
 
-    const to = moduleDir(pathJoin(root, 'aon_vendor'), ref)
+    // WHY THERE IS NO CONTAINMENT CHECK ON `to`, at the one write site
+    // that copied a tree outside the project: `usableRef` above is the
+    // gate, and after it a store path CANNOT escape. Every element is
+    // non-empty and neither begins nor ends with `.`, so none is `.`
+    // or `..`; MODULE_RE's element class admits no `/`, no `\` and no
+    // leading slash, so no element can re-root the join. A second
+    // lexical check here would be unreachable code, which ADR-002 asks
+    // to be deleted rather than excluded -- so the invariant is pinned
+    // by a test that drives the escape through this verb instead.
+    // ANY NEW CALLER of moduleDir must go through usableRef too;
+    // `mod get` is the next one.
+    const to = moduleDir(vendorRoot, ref)
     if (from !== to) {
       copyTree(from, to)
     }

package/src/mod.ts

@@ -73,9 +73,94 @@ export function parseModuleRef(spec: string): ModuleRef | undefined {
 }
 
 
+// SHAPE IS NOT VALIDITY, and the gap between them was a hole. MODULE_RE
+// answers "does this string route to the module resolver" -- a
+// ROUTING predicate, and it must stay one, because anything it rejects
+// falls through to the file leg and a stricter pattern would silently
+// re-route documents that work today. But its element class
+// `[A-Za-z0-9._-]` admits `..`, and `moduleDir` joins elements with
+// pathJoin, which CLEANS `..` rather than refusing it:
+//
+//   moduleDir('/store/aon_vendor', 'corp.example/../../etc/passwd@1')
+//     -> /store/etc/passwd@1
+//
+// `mod vendor` then copied a tree THERE, outside the project entirely,
+// and reported `verdict: ok`. So validity is a separate question asked
+// separately, after the shape matched, and asked at every site that
+// turns a module path into a directory.
+//
+// The rules are Go's (golang.org/x/mod/module.CheckPath), for the
+// reason Go has them: a module path becomes a real directory on every
+// platform the toolchain runs on, so it must be a legal one everywhere.
+export const MODULE_MAX_PATH = 512
+export const MODULE_MAX_ELEMS = 32
+
+
+// Windows refuses these as file names whatever the extension, so a
+// module path containing one cannot be materialised there at all. The
+// check is on the element up to its first dot, which is where Windows
+// stops looking too.
+const RESERVED_ELEMS = new Set([
+  'con', 'prn', 'aux', 'nul',
+  'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
+  'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
+])
+
+
+// Why a module path may not be used as a directory, or undefined when
+// it may. The reason is user-facing: it goes in the refusal, because a
+// path refused without saying which rule it broke is a puzzle.
+export function validateModulePath(path: string): string | undefined {
+  if (MODULE_MAX_PATH < path.length) {
+    return 'longer than ' + MODULE_MAX_PATH + ' characters'
+  }
+
+  const elems = path.split('/')
+  if (MODULE_MAX_ELEMS < elems.length) {
+    return 'more than ' + MODULE_MAX_ELEMS + ' elements'
+  }
+
+  for (const elem of elems) {
+    if ('' === elem) {
+      return 'an element is empty'
+    }
+    // This one rule kills `.` and `..` -- the traversal -- along with
+    // `.hidden` and `trailing.`, exactly as Go's does. Stating it as
+    // the rule rather than as "no `..`" is deliberate: a check that
+    // named the two dangerous spellings would miss the next one.
+    if (elem.startsWith('.') || elem.endsWith('.')) {
+      return 'an element begins or ends with "."'
+    }
+    if (RESERVED_ELEMS.has(elem.split('.')[0].toLowerCase())) {
+      return 'an element is a reserved device name'
+    }
+  }
+
+  return undefined
+}
+
+
+// An element as it is spelled ON DISK. Uppercase is escaped to
+// `!`+lowercase, Go's rule (go.dev/ref/mod, module proxy protocol) and
+// for Go's reason: `github.com/Alice/Widgets` and
+// `github.com/alice/widgets` are two module identities and, on macOS
+// and Windows, ONE directory -- so without this the second module
+// fetched silently clobbers the first, and an unpinned import resolves
+// to whichever won.
+//
+// The WRITTEN path stays the identity; only the directory is escaped.
+function escapeElem(elem: string): string {
+  return elem.replace(/[A-Z]/g, (c) => '!' + c.toLowerCase())
+}
+
+
 // The directory a module's files live in, under a store root.
+//
+// Callers must have validated the path (validateModulePath); this
+// function cannot refuse, because it answers a location rather than a
+// question, and every caller has a refusal shape of its own.
 export function moduleDir(store: string, ref: ModuleRef): string {
-  return pathJoin(store, ...ref.path.split('/')) + '@' + ref.major
+  return pathJoin(store, ...ref.path.split('/').map(escapeElem)) + '@' + ref.major
 }
 
 
@@ -248,6 +333,19 @@ export type ModuleFound = {
 }
 
 
+// EVERY code `resolveModule` can refuse with. The list lives HERE,
+// beside the refusals themselves, because the parse layer has to
+// recognise them to turn the throw into a parse-stage nil
+// (ts/src/lang.ts) -- and when that list was written out longhand
+// there, adding a fourth code left it unhandled and the refusal
+// surfaced as `unexpected error` instead of the message it carries.
+// The Go port has no such list (recordModErr takes any code), which is
+// why only this side could drift.
+export const MODULE_REFUSAL_CODES: ReadonlySet<string> = new Set([
+  'module_path', 'module_missing', 'module_integrity', 'module_depth',
+])
+
+
 // A refusal that carries its code to the parse layer, exactly as a
 // denied include does (makeModelResolver's `deny`): the resolver
 // THROWS, so a bare-member module import cannot vanish in the merge and
@@ -266,6 +364,17 @@ export function resolveModule(
   fs: ModuleFs,
   options: ModuleOptions,
 ): ModuleFound {
+  // THE PATH IS CHECKED BEFORE ANYTHING IS BUILT FROM IT. This is
+  // first because it is a question about the REQUEST, not about the
+  // state of the machine: a path that cannot legally be a directory is
+  // refused identically whether or not the module is present, and
+  // whether or not the depth bound is near.
+  const badpath = validateModulePath(ref.path)
+  if (undefined !== badpath) {
+    refuse('module_path',
+      'module path: ' + ref.path + '@' + ref.major + ' (' + badpath + ')')
+  }
+
   if (MODULE_MAX_DEPTH <= (options.depth ?? 0)) {
     refuse('module_depth',
       'module depth: ' + ref.path + '@' + ref.major +

package/src/patch.ts

@@ -333,34 +333,36 @@ function editableLiteral(
     }
   }
 
-  const one = literals[0]
+  return verifiedSite(overlaySrc, path, literals[0])
+}
 
-  // THE SPAN MUST CHECK OUT, and this is one condition rather than two.
-  //
-  // A first draft tested "no extent" separately from "the text
-  // disagrees", which read as two guards and was really one question
-  // asked twice — with the second half unreachable, since denying
-  // includes means the site comes from evaluating THIS TEXT with
-  // nothing loaded, so its coordinates describe this text by
-  // construction. Merged, the question is reachable through the case
-  // that has no extent at all (`x: hello |> upper` synthesises a call
-  // the parser never sited), so the check is exercised rather than
-  // argued for — and `spanHolds` is exported and tested against sites
-  // the engine would never produce, which is the only way to reach the
-  // half that remains theoretical.
-  //
-  // It is load-bearing either way: a contribution with no `src` would
-  // otherwise splice ZERO characters, INSERTING the new value into the
-  // middle of a line instead of replacing anything.
+
+// THE SPAN MUST CHECK OUT before anything splices. The refusal arm is
+// unreachable through `patch` since ADR-018: the pipe (`x: hello |>
+// upper`) was the one spelling that synthesised a contribution the
+// parser never sited, and denying includes means every WRITTEN
+// contribution's coordinates describe this text by construction. The
+// verification is kept rather than deleted — splicing without it would
+// corrupt the file (a contribution with no `src` would splice ZERO
+// characters, INSERTING the new value into the middle of a line) — and
+// this last step is its own exported seam so the refusal can be tested
+// directly, against conjuncts the engine would never produce, on the
+// same footing as `spanHolds` itself.
+export function verifiedSite(
+  overlaySrc: string,
+  path: string,
+  one: WhyConjunct,
+): { site: PatchReplacement | undefined, finding: VetFinding | undefined } {
   if (!spanHolds(overlaySrc, one.site, one.src)) {
-    return {
-      site: undefined,
-      finding: notEditable('patch_span_mismatch', path,
-        'the overlay does not hold ' + JSON.stringify(one.src) + ' at ' +
-        one.site.row + ':' + one.site.col + ' (len ' + one.site.len +
-        '), so the span cannot be verified before writing',
-        [one]),
-    }
+    const finding = notEditable('patch_span_mismatch', path,
+      'the overlay does not hold ' + JSON.stringify(one.src) + ' at ' +
+      one.site.row + ':' + one.site.col + ' (len ' + one.site.len +
+      '), so the span cannot be verified before writing',
+      [one])
+    // The one internal-class refusal: a recorded span failing to check
+    // out is the engine's fault, never the document's.
+    finding.class = 'internal'
+    return { site: undefined, finding }
   }
 
   // DOES THE SPAN MEAN THE WHOLE CONTRIBUTION?
@@ -479,7 +481,9 @@ function notEditable(
 ): VetFinding {
   return {
     code,
-    class: 'patch_span_mismatch' === code ? 'internal' : 'reference',
+    // Always `reference`; the one internal-class refusal
+    // (patch_span_mismatch) overrides at its call site.
+    class: 'reference',
     severity: 'warning',
     path,
     // No separate `note`: the renderer prints both, and a note that