@spexcode/spec-core 0.6.2 → 0.6.4

package/src/anchors.ts

@@ -1,728 +0,0 @@
-import { join } from 'node:path'
-import { createRequire } from 'node:module'
-import { git, gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, readImmutableHunkFacts, persistImmutableHunkFacts, withEventLedgerBuild, type DiffLineRange, type DriftIndex, type DriftPathEvent, type ImmutableHunkRanges } from './git.js'
-
-const RS = '\x1e'
-
-// ---- the anchor vocabulary ([[code-anchor]]) ----
-// A spec's `code:` entry may pin ONE named unit: `path#symbol` (`#Class.method` for a class method).
-// Everything below the entry parse splits into two layers:
-//   - the LANGUAGE SEAM: pure extractors (content, filename) -> Unit[] — no git, no cache, no fs.
-//     Each extension maps to exactly ONE designated extractor; there is NO cross-tier fallback.
-//   - the LANGUAGE-AGNOSTIC ENGINE: file-revision memo (keyed by the complete immutable parse input), anchor resolution
-//     (dead/ambiguous), diff-hunk ∩ unit-range intersection over the drift window. It never knows
-//     which language it is measuring.
-
-export type Unit = { name: string; kind: string; start: number; end: number; typeOnly?: boolean }
-
-export type Extractor = {
-  id: string
-  claims(ext: string): boolean
-  // true = usable here. A string is WHY it cannot run — lint turns that into a visible error and
-  // skips the affected anchors as unverified while continuing the other checks (never a crash or fake pass).
-  ready(): true | string
-  // PURE function of its arguments (importable by an external benchmark/scorer as-is). Throws when the
-  // content cannot be parsed — the caller maps that to a conservative verdict, never a silent skip.
-  extract(content: string, filename: string): Unit[]
-  // Every input that can affect extract() must be represented here before its result enters the memo.
-  memoKey: (filename: string) => string
-}
-
-export type CodeEntry = { path: string; anchor: string | null }
-export function parseCodeEntry(raw: string): CodeEntry {
-  const i = raw.indexOf('#')
-  if (i < 0) return { path: raw.trim(), anchor: null }
-  return { path: raw.slice(0, i).trim(), anchor: raw.slice(i + 1).trim() || null }
-}
-
-// ---- relation parsing: ONE structured path+selector grammar for code: AND related: ----
-// A relation's raw rows group per base path: a row is bare (`path`, whole-file — today's semantics,
-// unchanged) or scoped (`path#symbol`), and any number of scoped rows on the SAME base file fold into
-// one entry whose selectors are OR'd (a commit hitting any counts once; no selector-count cap — the
-// benchmark roster's 1–3 was an annotation rubric, never product syntax). STRUCTURAL verdicts live
-// here, pure and loud: an exact duplicate row, mixing bare with selectors on one base path, and a
-// selector on a glob are all `problems` the caller turns into integrity errors. Filesystem/git
-// verdicts (existence, directories, dead/ambiguous units, extractor readiness) stay the caller's —
-// this parser never touches fs.
-export type RelationEntry = { path: string; selectors: string[] }
-export type RelationParse = { entries: RelationEntry[]; problems: string[] }
-export function relationClaimsPath(claim: string, file: string): boolean {
-  if (claim === file) return true
-  if (file.startsWith(claim.replace(/\/+$/, '') + '/')) return true
-  if (!claim.includes('*')) return false
-  const pattern = claim.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
-  return new RegExp(`^${pattern}$`).test(file)
-}
-export function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse {
-  const order: string[] = []
-  const byPath = new Map<string, { bare: boolean; selectors: string[] }>()
-  const problems: string[] = []
-  for (const raw of raws) {
-    const { path, anchor } = parseCodeEntry(raw)
-    let e = byPath.get(path)
-    if (!e) { e = { bare: false, selectors: [] }; byPath.set(path, e); order.push(path) }
-    if (anchor === null) {
-      if (e.bare) problems.push(`${relation}: lists '${path}' twice — drop the duplicate entry`)
-      e.bare = true
-    } else if (e.selectors.includes(anchor)) {
-      problems.push(`${relation}: lists selector '${path}#${anchor}' twice — drop the duplicate`)
-    } else e.selectors.push(anchor)
-  }
-  for (const path of order) {
-    const e = byPath.get(path)!
-    if (e.bare && e.selectors.length)
-      problems.push(`${relation}: mixes bare '${path}' with '${path}#…' selectors — one base path is either whole-file or selector-scoped, never both; drop one form`)
-    if (e.selectors.length && path.includes('*'))
-      problems.push(`${relation}: '${path}#${e.selectors[0]}' puts a selector on a glob — a selector scopes ONE real file`)
-  }
-  return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p)!.selectors })), problems }
-}
-
-// ---- extractor: ts-ast (the designated extractor for the JS family) ----
-// Parse-only via the HOST project's own typescript, so the parse matches what the project itself compiles
-// with. If it cannot resolve, ready() returns a loud unverified verdict and lint skips these anchors
-// without crashing (no bundled compiler, regex fallback, or fake pass for JS).
-const JS_EXTS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts'])
-const TS_AST_MEMO_SCHEMA = 'ts-ast-memo-v1'
-
-export function tsAstExtractor(root: string): Extractor {
-  let ts: any | null | undefined // undefined = unprobed; null = unresolvable
-  let tsModulePath = ''
-  let readiness: true | string | undefined
-  const probe = () => {
-    if (ts !== undefined) return
-    try {
-      const require = createRequire(join(root, 'package.json'))
-      tsModulePath = require.resolve('typescript')
-      ts = require('typescript')
-    } catch { ts = null }
-  }
-  return {
-    id: 'ts-ast',
-    claims: (ext) => JS_EXTS.has(ext),
-    ready() {
-      if (readiness !== undefined) return readiness
-      probe()
-      if (!ts) return (readiness = `typescript is not resolvable from the governed repository (${root}) — JS-family anchors were skipped and remain unverified; run 'npm i -D typescript@5', or remove the #anchor`)
-      // resolvability is not usability: typescript@7 (the Go rewrite) may resolve yet not expose the JS
-      // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse. Once a candidate
-      // resolves, incompatibility is loud rather than silently changing parser versions.
-      try {
-        const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS)
-        if (!sf?.statements?.length || sf.parseDiagnostics?.length) throw new Error('probe parse failed')
-        readiness = true
-      } catch {
-        readiness = `host typescript (v${ts?.version ?? 'unknown'}) resolves but its createSourceFile API is unusable (a TS7/Go build?) — pin 'npm i -D typescript@5', or remove the #anchor`
-      }
-      return readiness
-    },
-    extract(content, filename) {
-      probe()
-      if (!ts) throw new Error('ts-ast extractor is not ready (typescript unresolvable)')
-      const kind = /\.(tsx)$/.test(filename) ? ts.ScriptKind.TSX
-        : /\.(jsx)$/.test(filename) ? ts.ScriptKind.JSX
-        : /\.(ts|mts|cts)$/.test(filename) ? ts.ScriptKind.TS
-        : ts.ScriptKind.JS
-      const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, false, kind)
-      // parse-only gate: a file that does not parse yields GARBAGE units (a shell script's `x=$(...)`
-      // parses as a const) — throw so the caller renders an honest "cannot parse" verdict instead.
-      if (sf.parseDiagnostics?.length) throw new Error(`${filename} does not parse as ${ts.ScriptKind[kind]} (${sf.parseDiagnostics.length} syntax error(s))`)
-      const line = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1
-      const units: Unit[] = []
-      const push = (name: string, ukind: string, node: any, typeOnly = false) =>
-        units.push({ name, kind: ukind, start: line(node.getStart(sf)), end: line(node.end), ...(typeOnly ? { typeOnly } : {}) })
-      for (const st of sf.statements) {
-        if (ts.isFunctionDeclaration(st)) push(st.name ? st.name.text : '(default)', 'function', st)
-        else if (ts.isClassDeclaration(st)) {
-          const cname = st.name ? st.name.text : '(default)'
-          push(cname, 'class', st)
-          for (const m of st.members) {
-            if ((ts.isMethodDeclaration(m) || ts.isConstructorDeclaration(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) && m.body) {
-              const mname = ts.isConstructorDeclaration(m) ? 'constructor' : (m.name && ts.isIdentifier(m.name) ? m.name.text : '(computed)')
-              push(`${cname}.${mname}`, 'method', m)
-            }
-          }
-        } else if (ts.isVariableStatement(st)) {
-          for (const d of st.declarationList.declarations) {
-            if (!ts.isIdentifier(d.name)) continue // destructuring — not anchorable by one name
-            const fn = d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))
-            // range = the whole statement (multi-declarator lines co-move; each name shares the range)
-            units.push({ name: d.name.text, kind: fn ? 'const-fn' : 'const-data', start: line(st.getStart(sf)), end: line(st.end) })
-          }
-        } else if (ts.isEnumDeclaration(st)) push(st.name.text, 'enum', st)
-        else if (ts.isInterfaceDeclaration(st)) push(st.name.text, 'interface', st, true)
-        else if (ts.isTypeAliasDeclaration(st)) push(st.name.text, 'type', st, true)
-      }
-      return units
-    },
-    memoKey(filename) {
-      probe()
-      const host = ts ? `${tsModulePath}\0${ts.version ?? 'unknown'}` : `unresolved\0${root}`
-      return `${TS_AST_MEMO_SCHEMA}\0${host}\0target:Latest\0parents:false\0${filename}`
-    },
-  }
-}
-
-// ---- extractor: heuristic(langSpec) — a generic regex engine fed LANGUAGE DATA, not language branches ----
-// The designated extractor for languages described by a LangSpec row; adding a language = adding a data
-// row + a registry entry (never a new engine). The JS family is deliberately NOT routed here (its
-// designated extractor is ts-ast above); JS_LANG_R5B below exists as the validated reference row for the
-// engine's shape and for the external benchmark to score.
-export type LangSpec = {
-  id: string
-  extensions: string[]
-  // column-0 declaration patterns; capture group 1 = the unit name (or the declarator list when declList)
-  decls: {
-    re: RegExp
-    kind: string
-    typeOnly?: boolean
-    classOpener?: boolean
-    declList?: boolean
-    scopeOpener?: boolean
-    memberOf?: { parentKind: string; kind: string }
-  }[]
-  // class-member pattern, active while inside a classOpener's balanced-bracket body (name -> Class.name)
-  member?: { re: RegExp; blacklist?: RegExp }
-  // indentation-significant languages use declaration nesting for qualified names and ranges. The
-  // declaration regexes remain language data; this only selects a generic boundary strategy.
-  indentScopes?: { decorator?: RegExp }
-  // a column-0 line matching this ENDS the previous unit (comment-aware so trailing comment blocks
-  // attach to the NEXT unit, not the previous one)
-  boundary: RegExp
-}
-
-const balance = (s: string) => { let n = 0; for (const ch of s) { if ('([{'.includes(ch)) n++; else if (')]}'.includes(ch)) n-- } return n }
-// split a declarator-list head on top-level commas: `COLS = 220, ROWS = 50` -> [COLS, ROWS]
-function declNames(head: string): string[] {
-  let d = 0, seg = ''
-  const segs: string[] = []
-  for (const ch of head) {
-    if ('([{<'.includes(ch)) d++
-    else if (')]}>'.includes(ch)) d--
-    if (ch === ',' && d === 0) { segs.push(seg); seg = '' } else seg += ch
-  }
-  segs.push(seg)
-  return segs.map((s) => s.match(/^\s*([A-Za-z_$][\w$]*)\s*(?::|=|$)/)?.[1]).filter((x): x is string => !!x)
-}
-
-const indentation = (line: string): number => {
-  let n = 0
-  for (const ch of line) {
-    if (ch === ' ') n++
-    else if (ch === '\t') n += 8 - (n % 8)
-    else break
-  }
-  return n
-}
-
-function extractIndentScoped(content: string, spec: LangSpec): Unit[] {
-  const lines = content.split('\n')
-  type ScopedUnit = Unit & { declaration: number; indent: number }
-  const units: ScopedUnit[] = []
-  const scopes: { indent: number; name: string; kind: string }[] = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (!line.trim() || /^\s*#/.test(line)) continue
-    const indent = indentation(line)
-    while (scopes.length && scopes[scopes.length - 1].indent >= indent) scopes.pop()
-    for (const d of spec.decls) {
-      const m = line.match(d.re)
-      if (!m) continue
-      const local = m[1]
-      const name = [...scopes.map((s) => s.name), local].join('.')
-      const parent = scopes[scopes.length - 1]
-      const kind = d.memberOf && parent?.kind === d.memberOf.parentKind ? d.memberOf.kind : d.kind
-      let start = i + 1
-      if (spec.indentScopes?.decorator) {
-        for (let j = i - 1; j >= 0; j--) {
-          if (indentation(lines[j]) !== indent || !spec.indentScopes.decorator.test(lines[j])) break
-          start = j + 1
-        }
-      }
-      units.push({ name, kind, start, end: i + 1, declaration: i, indent, ...(d.typeOnly ? { typeOnly: true } : {}) })
-      if (d.scopeOpener) scopes.push({ indent, name: local, kind: d.kind })
-      break
-    }
-  }
-
-  for (const unit of units) {
-    let boundary: number | null = null
-    for (let i = unit.declaration + 1; i < lines.length; i++) {
-      const line = lines[i]
-      if (!line.trim()) continue
-      const indent = indentation(line)
-      if (/^\s*#/.test(line)) {
-        if (indent <= unit.indent && boundary === null) boundary = i
-        continue
-      }
-      if (indent <= unit.indent) { boundary ??= i; break }
-      boundary = null
-    }
-    unit.end = Math.max(unit.start, (boundary ?? lines.length) )
-  }
-  return units.map(({ declaration: _declaration, indent: _indent, ...unit }) => unit)
-}
-
-export function heuristicExtractor(spec: LangSpec): Extractor {
-  return {
-    id: spec.id,
-    claims: (ext) => spec.extensions.includes(ext),
-    ready: () => true,
-    extract(content) {
-      if (spec.indentScopes) return extractIndentScoped(content, spec)
-      const lines = content.split('\n')
-      const units: Unit[] = []
-      let cls: string | null = null, depth = 0
-      for (let i = 0; i < lines.length; i++) {
-        const l = lines[i]
-        if (cls) {
-          const m = spec.member && l.match(spec.member.re)
-          if (m && !spec.member!.blacklist?.test(m[1])) units.push({ name: `${cls}.${m[1]}`, kind: 'method', start: i + 1, end: i + 1 })
-          depth += balance(l)
-          if (depth <= 0) cls = null
-          continue
-        }
-        for (const d of spec.decls) {
-          const m = l.match(d.re)
-          if (!m) continue
-          for (const name of d.declList ? declNames(m[1]) : [m[1]])
-            units.push({ name, kind: d.kind, start: i + 1, end: i + 1, ...(d.typeOnly ? { typeOnly: true } : {}) })
-          if (d.classOpener) { cls = m[1]; depth = balance(l) }
-          break
-        }
-      }
-      // R5b ranges: a unit ends before the next column-0 boundary line; a method is also capped by the
-      // next unit's start (methods sit inside their class's indentation, below boundary's radar).
-      const bset: number[] = []
-      for (let i = 0; i < lines.length; i++) if (spec.boundary.test(lines[i])) bset.push(i + 1)
-      const starts = units.map((u) => u.start).sort((a, b) => a - b)
-      for (const u of units) {
-        const nb = bset.find((b) => b > u.start)
-        let end = nb ?? lines.length + 1
-        if (u.kind === 'method') { const ns = starts.find((x) => x > u.start); if (ns && ns < end) end = ns }
-        u.end = Math.max(u.start, end - 1)
-      }
-      return units
-    },
-    memoKey(filename) {
-      const regex = (r: RegExp | undefined) => r ? `${r.source}/${r.flags}` : null
-      return JSON.stringify({
-        schema: 'heuristic-memo-v1', filename, id: spec.id, extensions: spec.extensions,
-        decls: spec.decls.map((d) => ({
-          re: regex(d.re), kind: d.kind, typeOnly: !!d.typeOnly, classOpener: !!d.classOpener,
-          declList: !!d.declList, scopeOpener: !!d.scopeOpener, memberOf: d.memberOf ?? null,
-        })),
-        member: spec.member ? { re: regex(spec.member.re), blacklist: regex(spec.member.blacklist) } : null,
-        indentScopes: spec.indentScopes ? { decorator: regex(spec.indentScopes.decorator) } : null,
-        boundary: regex(spec.boundary),
-      })
-    },
-  }
-}
-
-// The validated JS-family reference row (R5b: name precision 99.7% / recall 100% / range 98.9% on the
-// 41-file oracle) — NOT registered for JS (ts-ast is designated); kept as the engine's reference shape
-// and the benchmark's scoring subject.
-export const JS_LANG_R5B: LangSpec = {
-  id: 'heuristic-js',
-  extensions: [...JS_EXTS],
-  decls: [
-    { re: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/, kind: 'function' },
-    { re: /^(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/, kind: 'class', classOpener: true },
-    { re: /^(?:export\s+)?(?:declare\s+)?enum\s+([A-Za-z_$][\w$]*)/, kind: 'enum' },
-    { re: /^(?:export\s+)?(?:declare\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: 'interface', typeOnly: true },
-    { re: /^(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][\w$]*)/, kind: 'type', typeOnly: true },
-    { re: /^(?:export\s+)?(?:const|let|var)\s+(.+)$/, kind: 'const', declList: true },
-  ],
-  member: {
-    re: /^\s+(?:(?:public|private|protected|static|readonly|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(/,
-    blacklist: /^(if|for|while|switch|return|catch|new|await|typeof|throw|else|do)$/,
-  },
-  boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
-}
-
-// Python is a LangSpec DATA row over the same generic engine: declaration names come from patterns;
-// significant indentation supplies lexical qualification and ranges. It is intentionally structural,
-// not a Python runtime or full grammar (the user-facing boundary is documented by [[code-anchor]]).
-const PY_ID = String.raw`[\p{ID_Start}_][\p{ID_Continue}_]*`
-export const PYTHON_LANG: LangSpec = {
-  id: 'heuristic-python',
-  extensions: ['py', 'pyi'],
-  decls: [
-    {
-      re: new RegExp(`^\\s*(?:async\\s+)?def\\s+(${PY_ID})\\s*\\(`, 'u'),
-      kind: 'function',
-      scopeOpener: true,
-      memberOf: { parentKind: 'class', kind: 'method' },
-    },
-    { re: new RegExp(`^\\s*class\\s+(${PY_ID})(?:\\s*\\(|\\s*:)`, 'u'), kind: 'class', scopeOpener: true },
-  ],
-  indentScopes: { decorator: /^\s*@/ },
-  boundary: /^\S/,
-}
-
-// ---- registry: extension -> its ONE designated extractor ----
-// The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
-// heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
-// config — whatever the implementation needs rides inside its own factory, never in the registry.
-export function extractors(root: string): Extractor[] {
-  return [tsAstExtractor(root), ...[PYTHON_LANG].map(heuristicExtractor)]
-}
-// first claiming extractor IS the designation (the registry order defines it); null = no anchor support
-// for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
-export function extractorFor(regs: Extractor[], ext: string): Extractor | null {
-  return regs.find((x) => x.claims(ext)) ?? null
-}
-export const extOf = (path: string): string => {
-  const base = path.slice(path.lastIndexOf('/') + 1)
-  const dot = base.lastIndexOf('.')
-  return dot > 0 ? base.slice(dot + 1) : ''
-}
-
-// ---- anchor resolution (language-agnostic) ----
-export type AnchorResolution = { ok: Unit } | { dead: true } | { ambiguous: number }
-// @@@ ONE classification for "does this selector resolve here" - the gate (reading the candidate TIP) and the
-// freshness probe (reading the WORKING TREE) both have to answer it, and each used to branch on
-// dead/ambiguous itself. Two copies of a verdict rule drift, and these two already had: the gate warns on a
-// type-only unit, the probe never noticed one. The TEXT each reads stays its own business — a gate must judge
-// the tree it is gating, never a dirty worktree — but the VERDICT is decided once, here, so a new outcome
-// cannot reach one caller and silently miss the other.
-export type SelectorVerdict = { selector: string } & ({ ok: Unit } | { dead: true } | { ambiguous: number })
-export function resolveSelectors(units: Unit[], selectors: readonly string[]): SelectorVerdict[] {
-  return selectors.map((selector) => {
-    const r = resolveAnchor(units, selector)
-    if ('dead' in r) return { selector, dead: true as const }
-    if ('ambiguous' in r) return { selector, ambiguous: r.ambiguous }
-    return { selector, ok: r.ok }
-  })
-}
-
-export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
-  const hits = units.filter((u) => u.name === symbol)
-  if (!hits.length) return { dead: true }
-  if (hits.length > 1) return { ambiguous: hits.length }
-  return { ok: hits[0] }
-}
-
-// The one selector/range intersection used by historical commits and a pinned worktree overlay.
-export function selectorsHitRanges(units: readonly Unit[], symbols: readonly string[], ranges: readonly [number, number][]): string[] {
-  return symbols.filter((symbol) => {
-    const matching = units.filter((unit) => unit.name === symbol)
-    return matching.length > 0 && ranges.some(([start, end]) => matching.some((unit) => start <= unit.end && unit.start <= end))
-  })
-}
-
-// Ordinary zero-context ranges. The side chooses the immutable image whose units the caller resolved.
-export function diffHunkRanges(patch: string, side: 'old' | 'new' = 'new'): [number, number][] {
-  const ranges: [number, number][] = []
-  for (const match of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
-    const offset = side === 'old' ? 1 : 3
-    const start = +match[offset]
-    const count = match[offset + 1] === undefined ? 1 : +match[offset + 1]
-    if (count > 0) ranges.push([start, start + count - 1])
-  }
-  return ranges
-}
-
-// ---- the historical hit engine (language-agnostic; batch short-lived git, no resident process) ----
-
-// units of a file AS OF a commit, memoized by the complete immutable parse identity. File content identified
-// by an object id is immutable, but the extractor also consumes filename and host/config identity; distinct
-// file revisions in a window are few.
-// 'absent' = no file at that commit; 'unparseable' = the extractor rejected that revision's content.
-type FileRevisionUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
-const fileRevisionUnitMemo = new Map<string, FileRevisionUnits>()
-const MEMO_MAX = 4096
-const fileRevisionMemoKey = (objectFormat: string, oid: string, x: Extractor, path: string) => `${objectFormat}\0${oid}\0${x.memoKey(path)}`
-async function unitsAtFileRevision(commit: string, path: string, x: Extractor, objectFormat: string, oid: string | null, text?: string): Promise<FileRevisionUnits> {
-  if (!oid) return { absent: true }
-  const key = fileRevisionMemoKey(objectFormat, oid, x, path)
-  const hit = fileRevisionUnitMemo.get(key)
-  if (hit) return hit
-  if (text === undefined) throw new Error(`git cat-file --batch omitted object ${oid} for ${commit}:${path}`)
-  let result: FileRevisionUnits
-  try { result = { units: x.extract(text, path) } } catch (e: any) { result = { unparseable: e?.message ?? String(e) } }
-  if (fileRevisionUnitMemo.size >= MEMO_MAX) fileRevisionUnitMemo.clear()
-  fileRevisionUnitMemo.set(key, result)
-  return result
-}
-
-// Changed line ranges on both sides of one commit's diff. Ordinary commits have one parent image. Merges
-// retain one before-image per parent and only all-parent authored rows; an owned line never widens to an
-// adjacent inherited line merely because Git placed both in one `@@@` hunk.
-type HunkRanges = { after: DiffLineRange[]; before: DiffLineRange[][] }
-// @@@ RANGE_SEMANTICS - hunk ranges must not depend on ambient Git state, because a range that moves with
-// config or attributes is neither a sound anchor verdict nor a reusable fact. Outside the commit, three
-// classes decide them: presentation (`.gitattributes` `-diff` prints `Binary files … differ` with no `@@` at
-// all — measured: one hunk bare, ZERO under `src/x.py -diff`, so an attribute edit silently disabled an
-// anchored contract's drift; a textconv or external driver replaces the text compared), the ALGORITHM and
-// its heuristics (`diff.algorithm`, `diff.indentHeuristic` — both repo config), and hunk COALESCING
-// (`diff.interHunkContext`). All are pinned here, on the two readers this node owns.
-//
-// The algorithm's VALUE is a product choice, not a formality, because the algorithms genuinely disagree:
-// on `c a c a` -> `c c a a a`, myers authors new lines 4-5 and deletes old line 2, while histogram authors
-// new lines 2-3 and deletes old line 3 — so a unit on line 3 is a HIT under histogram and a MISS under
-// myers, on one commit. histogram is pinned because it aligns the change with the unit that actually moved,
-// which for a BLOCKING gate is the conservative direction; myers (Git's default) would silently miss that
-// drift. So this pin is not merely determinism: it settles which reading a verdict means.
-// `--no-color` is not cosmetic here: under an ambient `color.ui=always` Git prefixes every `@@` with an
-// ANSI escape, so a `/^@@/` parse finds NO hunks and every anchored path reads as "nothing changed" — a
-// silent zero-drift verdict for the whole corpus, and one that would then be memoized. `-M -l0` pins rename
-// detection with no candidate limit, matching the identity stream this engine's events come from, so a large
-// rename set cannot quietly change which pairs are compared.
-const RANGE_SEMANTICS = [
-  '--text', '--no-textconv', '--no-ext-diff', '--no-color',
-  '--diff-algorithm=histogram', '--no-indent-heuristic', '--inter-hunk-context=0',
-  '-M', '-l0',
-] as const
-const hunkMemo = new Map<string, HunkRanges>()
-// @@@ the reusable fact is a diff of ORDERED IMAGES, not of a commit id - a commit id is not immutable
-// interpretation: `refs/replace` can swap the object, and a graft or an unshallow can change its parents, so
-// one (commit,path) can name two different diffs inside one process. The inputs that actually decide the
-// hunks are the result image and each parent image, in order, each identified by its resolved blob oid and
-// historical path. Keying on those makes the key move exactly when an input does, and the oids are already
-// resolved by this read's one `cat-file --batch-check`, so completeness costs no extra child and no new state.
-const ABSENT_IMAGE = '-'
-const HUNK_FACT_SCHEMA = 'anchor-range-histogram-v1'
-const hunkMemoKey = (images: string[]) => `${HUNK_FACT_SCHEMA}\0${images.join('\0')}`
-function rememberHunks(key: string, ranges: HunkRanges): HunkRanges {
-  if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
-  hunkMemo.set(key, ranges)
-  return ranges
-}
-async function hunksAt(root: string, event: DriftPathEvent, key: string): Promise<HunkRanges> {
-  const paths = [...new Set([event.historicalPath, ...event.parents.map((parent) => parent.historicalPath)])]
-  const hit = hunkMemo.get(key)
-  if (hit) return hit
-  const merge = event.parents.length > 1
-  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'show', '--cc', '--combined-all-paths', '--unified=0', ...RANGE_SEMANTICS, '--format=', event.commit,
-    ...(merge ? [] : ['--', ...paths])],
-    `cannot derive anchor hunks for ${event.commit}:${event.historicalPath}`)
-  let ranges: HunkRanges = { after: [], before: [[]] }
-  if (/^@@@/m.test(out)) {
-    const owned = combinedDiffOwnedChanges(out).get(event.historicalPath)
-    if (!owned) throw new Error(`combined diff for ${event.commit} did not expose owned ranges for '${event.historicalPath}'`)
-    ranges = owned
-  } else {
-    for (const m of out.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
-      const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2]
-      const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4]
-      if (oldCount > 0) ranges.before[0].push([oldStart, oldStart + oldCount - 1])
-      if (newCount > 0) ranges.after.push([newStart, newStart + newCount - 1])
-    }
-  }
-  return rememberHunks(key, ranges)
-}
-
-// Ordinary commits whose two images keep one path share a single query. Renames and merges retain distinct
-// image paths, so they stay on hunksAt's exact event-shaped query. Commits ride argv here, so a build-wide
-// batch is split to stay clear of the kernel's exec argument limit; the records are order-independent.
-//
-// @@@ the demand set is the MISSES - a hunk is reusable by the identity of the IMAGES it diffed, never by the
-// commit id (see hunkMemoKey): under that identity, plus this seam's pinned interpretation, the fact cannot be
-// reinterpreted inside one process, so the batch may ask git only for what it has not read. Asking for the
-// whole window again is what made a repeated read cost the CORPUS instead of the movement: a re-lint after one
-// trunk commit or one dirty edit re-forked one `log --patch` per anchored path (22 here) to re-derive
-// byte-identical answers.
-const HUNK_COMMIT_CHUNK = 400
-async function hunksAtMany(root: string, path: string, entries: Map<string, string>): Promise<Map<string, HunkRanges>> {
-  const result = new Map<string, HunkRanges>()
-  const ordinary: string[] = []
-  for (const [commit, key] of entries) {
-    const hit = hunkMemo.get(key)
-    if (hit) result.set(commit, hit)
-    else ordinary.push(commit)
-  }
-  if (!ordinary.length) return result
-  for (let cursor = 0; cursor < ordinary.length; cursor += HUNK_COMMIT_CHUNK)
-    await hunkRecordsInto(root, ordinary.slice(cursor, cursor + HUNK_COMMIT_CHUNK), path, entries, result)
-  return result
-}
-async function hunkRecordsInto(root: string, ordinary: string[], path: string, keys: Map<string, string>, result: Map<string, HunkRanges>): Promise<void> {
-  const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'log', '--no-walk', '--no-merges', '--patch', '--unified=0', ...RANGE_SEMANTICS,
-    `--format=${RS}%H`, ...ordinary, '--', path], `cannot derive anchor hunks for ${path}`)
-  for (const rec of out.split(RS)) {
-    const normalized = rec.replace(/^\n/, '')
-    if (!normalized) continue
-    const newline = normalized.indexOf('\n')
-    const hash = (newline < 0 ? normalized : normalized.slice(0, newline)).trim()
-    if (!isGitObjectId(root, hash)) throw new Error(`anchor hunk query returned malformed object id '${hash || 'empty'}'`)
-    const patch = newline < 0 ? '' : normalized.slice(newline + 1)
-    const ranges: HunkRanges = { after: [], before: [[]] }
-    for (const m of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
-      const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2]
-      const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4]
-      if (oldCount > 0) ranges.before[0].push([oldStart, oldStart + oldCount - 1])
-      if (newCount > 0) ranges.after.push([newStart, newStart + newCount - 1])
-    }
-    const key = keys.get(hash)
-    result.set(hash, key === undefined ? ranges : rememberHunks(key, ranges))
-  }
-}
-
-// the drift window of an anchored file: every commit to `path` not reachable from the spec's version
-// and not covered by a valid Spec-OK ack — the SAME set driftFor counts, exposed as commits so the
-// anchor engine can probe each one. Ordinary file commits and merge-authored dense-combined paths are
-// indexed separately so clean merge transport is never charged twice.
-export function windowEvents(idx: DriftIndex, sinceHash: string, path: string, nodeId?: string): DriftPathEvent[] {
-  if (!sinceHash) return []
-  return driftPathWindow(idx, sinceHash, path, nodeId) ?? []
-}
-
-// Which window commits touched an anchored unit. Added lines intersect the result-image unit; deleted lines
-// intersect the parent-image unit. A merge owns a deletion only when every parent-side range belongs to the
-// selector. This is why events retain their immutable post/preimage paths instead of resolving every blob
-// through the current filename. Several selectors are OR'd and one commit still produces one hit row.
-// An historical image the designated extractor cannot parse is a conservative hit (`unparseable`).
-export type AnchorHit = { commit: string; selectors: string[]; unparseable?: string }
-export type AnchorHitQuery = { win: DriftPathEvent[]; symbols: string[] }
-type AnchorRevision = { commit: string; path: string }
-const anchorRevisionKey = ({ commit, path }: AnchorRevision) => `${commit}\0${path}`
-
-// One lint can judge several selectors with overlapping windows. Their Git images and ordinary hunks are
-// reusable under the identity of those images, so the batch owns them once and each query keeps its own
-// selector verdict.
-async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[], stopAtFirstHit: boolean): Promise<AnchorHit[][]> {
-  if (!queries.length) return []
-  return withEventLedgerBuild(root, () => runAnchorQueriesInLedger(root, queries, regs, stopAtFirstHit))
-}
-
-async function runAnchorQueriesInLedger(root: string, queries: AnchorHitQuery[], regs: Extractor[], stopAtFirstHit: boolean): Promise<AnchorHit[][]> {
-  const objectFormat = gitObjectFormat(root)
-  const revisions = new Map<string, AnchorRevision>()
-  const ordinaryEvents: { path: string; commit: string; event: DriftPathEvent }[] = []
-  for (const { win } of queries) for (const event of win) {
-    const refs = [{ commit: event.commit, path: event.historicalPath }, ...event.parents.map(({ commit, historicalPath }) => ({ commit, path: historicalPath }))]
-    for (const ref of refs) revisions.set(anchorRevisionKey(ref), ref)
-    if (event.parents.length > 1 || event.parents.some((parent) => parent.historicalPath !== event.historicalPath)) continue
-    ordinaryEvents.push({ path: event.historicalPath, commit: event.commit, event })
-  }
-  const refs = [...revisions.values()]
-  const oids = await batchRevisionOids(root, refs.map(({ commit, path }) => `${commit}:${path}`))
-  // Every image this read will diff is now resolved, so the reusable hunk fact can be named by the identity
-  // that actually decides it: the result image and each parent image, in order, oid + historical path.
-  const oidByRef = new Map<string, string | null>()
-  for (let index = 0; index < refs.length; index++) oidByRef.set(anchorRevisionKey(refs[index]), oids[index])
-  const imageOf = (commit: string, path: string) => `${oidByRef.get(anchorRevisionKey({ commit, path })) ?? ABSENT_IMAGE}:${path}`
-  const imageIdentity = (event: DriftPathEvent) => hunkMemoKey([
-    imageOf(event.commit, event.historicalPath),
-    ...event.parents.map(({ commit, historicalPath }) => imageOf(commit, historicalPath)),
-  ])
-  const hunkKeys = new Set<string>()
-  const ordinaryByPath = new Map<string, Map<string, string>>()
-  for (const { path, commit, event } of ordinaryEvents) {
-    const entries = ordinaryByPath.get(path) ?? new Map<string, string>()
-    const key = imageIdentity(event)
-    hunkKeys.add(key)
-    entries.set(commit, key)
-    ordinaryByPath.set(path, entries)
-  }
-  for (const { win } of queries) for (const event of win) hunkKeys.add(imageIdentity(event))
-  const durableHunks = readImmutableHunkFacts(root, hunkKeys)
-  for (const [key, ranges] of durableHunks) rememberHunks(key, ranges)
-  const newHunks = new Map<string, ImmutableHunkRanges>()
-  const ordinaryHunks = new Map<string, Map<string, HunkRanges>>()
-  for (const [path, entries] of ordinaryByPath) {
-    const rangesByCommit = await hunksAtMany(root, path, entries)
-    ordinaryHunks.set(path, rangesByCommit)
-    for (const [commit, key] of entries) {
-      const ranges = rangesByCommit.get(commit)
-      if (ranges && !durableHunks.has(key)) newHunks.set(key, ranges)
-    }
-  }
-  // The image's own memo answers before any bytes move, so the read asks git only for the revisions this
-  // process has not parsed yet — the retention half of the same rule the hunk demand set follows.
-  const units = new Map<string, FileRevisionUnits>()
-  const primeUnits = async (keys: Set<string>): Promise<void> => {
-    const pending: { key: string; ref: AnchorRevision; oid: string; x: Extractor }[] = []
-    const wanted = new Set<string>()
-    for (const key of keys) {
-      if (units.has(key)) continue
-      const ref = revisions.get(key)!, oid = oidByRef.get(key) ?? null
-      const x = extractorFor(regs, extOf(ref.path))
-      const ready = x?.ready()
-      if (!x || ready !== true) {
-        units.set(key, { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) })
-        continue
-      }
-      if (!oid) { units.set(key, { absent: true }); continue }
-      const hit = fileRevisionUnitMemo.get(fileRevisionMemoKey(objectFormat, oid, x, ref.path))
-      if (hit) { units.set(key, hit); continue }
-      pending.push({ key, ref, oid, x }); wanted.add(oid)
-    }
-    if (!pending.length) return
-    const blobs = await batchBlobTexts(root, [...wanted])
-    for (const { key, ref, oid, x } of pending)
-      units.set(key, await unitsAtFileRevision(ref.commit, ref.path, x, objectFormat, oid, blobs.get(oid)))
-  }
-  const intersects = (ranges: DiffLineRange[], candidates: Unit[]) =>
-    ranges.some(([start, end]) => candidates.some((unit) => start <= unit.end && unit.start <= end))
-  // @@@ the scan advances in DOUBLING corpus-wide rounds - an existence read may stop at its window's first
-  // hit, but which event that is cannot be known before the images are parsed, so the demand set has to be
-  // discovered rather than declared. Each round still asks the WHOLE unsettled corpus at once (never one
-  // reading at a time, which is what would re-fork the batch per unit), and doubling bounds the rounds by hit
-  // DEPTH, not by how many readings are asked. An enumeration read takes its whole remaining window in one
-  // slice, so it keeps the single-round shape it has always had.
-  const runs = queries.map(() => ({ hits: new Map<string, { selectors: Set<string>; unparseable?: string }>(), cursor: 0, settled: false }))
-  for (let chunk = 1; ; chunk *= 2) {
-    const slices: { run: typeof runs[number]; symbols: string[]; events: DriftPathEvent[] }[] = []
-    for (let index = 0; index < queries.length; index++) {
-      const run = runs[index], { win, symbols } = queries[index]
-      if (run.settled || run.cursor >= win.length) continue
-      slices.push({ run, symbols, events: win.slice(run.cursor, run.cursor + (stopAtFirstHit ? chunk : win.length - run.cursor)) })
-    }
-    if (!slices.length) break
-    const keys = new Set<string>()
-    for (const { events } of slices) for (const event of events) {
-      keys.add(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))
-      for (const parent of event.parents) keys.add(anchorRevisionKey({ commit: parent.commit, path: parent.historicalPath }))
-    }
-    await primeUnits(keys)
-    for (const { run, symbols, events } of slices) {
-      for (const event of events) {
-        run.cursor++
-        const after = units.get(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))!
-        const before = event.parents.map(({ commit, historicalPath }) => units.get(anchorRevisionKey({ commit, path: historicalPath }))!)
-        const key = imageIdentity(event)
-        const ranges = ordinaryHunks.get(event.historicalPath)?.get(event.commit)
-          ?? await hunksAt(root, event, key)
-        if (!durableHunks.has(key)) newHunks.set(key, ranges)
-        if (event.parents.length && ranges.before.length !== before.length)
-          throw new Error(`anchor diff for ${event.commit}:${event.historicalPath} has ${ranges.before.length} parent ranges for ${before.length} parents`)
-        const hit = run.hits.get(event.commit) ?? { selectors: new Set<string>() }
-        const broken = [after, ...before].find((image) => 'unparseable' in image)
-        if (broken && 'unparseable' in broken) {
-          for (const symbol of symbols) hit.selectors.add(symbol)
-          hit.unparseable = broken.unparseable
-        } else {
-          for (const symbol of symbols) {
-            const afterUnits = 'units' in after ? after.units.filter((unit) => unit.name === symbol) : []
-            const authoredAfter = intersects(ranges.after, afterUnits)
-            const authoredBefore = before.length > 0 && before.every((image, parent) =>
-              'units' in image && intersects(ranges.before[parent], image.units.filter((unit) => unit.name === symbol)))
-            if (authoredAfter || authoredBefore) hit.selectors.add(symbol)
-          }
-        }
-        if (hit.selectors.size) run.hits.set(event.commit, hit)
-        if (stopAtFirstHit && run.hits.size) { run.settled = true; break }
-      }
-    }
-  }
-  await persistImmutableHunkFacts(root, newHunks)
-  return runs.map((run) => [...run.hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) })))
-}
-
-// The two consumers ask DIFFERENT questions of this engine, so they enter through different doors rather
-// than through one call with a mode flag. Enumeration must scan every window event because its answer IS the
-// per-commit, per-selector list; existence is discharged by the first hit, and scanning past it computes rows
-// nobody reads.
-export async function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]> {
-  return runAnchorQueries(root, queries, regs, false)
-}
-export async function anchorHitExists(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<boolean[]> {
-  return (await runAnchorQueries(root, queries, regs, true)).map((hits) => hits.length > 0)
-}
-export async function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]> {
-  return (await anchorHitQueries(root, [{ win, symbols }], regs))[0]
-}