spexcode 0.5.8 → 0.5.9

package/spec-eval/src/freshness.ts

@@ -1,9 +1,10 @@
 import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { join, resolve } from 'node:path'
-import { gitA, gitTry, headSha, currentGitBuildAbortSignal, gitAbortError, ancestorsOf, inAncestors, commitReachable, pathEvents, type DriftIndex, type DriftPathEvent } from '../../spec-cli/src/git.js'
-import { anchorHitCommits, extOf, extractorFor, extractors, resolveAnchor, type Extractor, type RelationEntry } from '../../spec-cli/src/anchors.js'
+import { gitA, gitTry, headSha, currentGitBuildAbortSignal, gitAbortError, ancestorsOf, inAncestors, commitReachable, pathEvents, type DriftIndex, type DriftPathEvent, eventsSince } from '../../spec-cli/src/git.js'
+import { anchorHitExists, extOf, extractorFor, extractors, resolveAnchor, resolveSelectors, type AnchorHitQuery, type Extractor, type RelationEntry, type Unit } from '../../spec-cli/src/anchors.js'
 import type { Reading } from './sidecar.js'
-import { scenarioCodeAxis, scenarioHash, type Scenario } from './scenarios.js'
+import { scenarioCodeAxis, scenarioHash, type Scenario, type ScenarioCodeAxisSource } from './scenarios.js'
 import { scenarioChangeCommits, scenarioBlocksAt, primeScenarioBlocksAt, type ScenarioIndex } from './scenariofresh.js'
 
 // the CODE axis is touch-based (DriftIndex), so a code-file rename is out of scope — the same blind spot lint's code-drift has
@@ -259,8 +260,12 @@ export type AnchorProbe = {
   // did any commit in sinceSha..HEAD touch one of THESE anchored units?
   // null = cannot testify (unprimed, off-history, no usable extractor) — callers stay conservatively stale.
   hit(sinceSha: string, path: string, selectors: readonly string[]): boolean | null
-  prime?(sinceSha: string, entries: readonly RelationEntry[]): Promise<void>
+  // The demand set is PLURAL because the engine underneath is: every window's Git images and ordinary hunks
+  // are immutable, so one call owns them once for the whole read. A caller that primes one reading at a time
+  // re-forks that batch per reading, which on this corpus was ~2.5k children for ~800 verdicts.
+  prime?(demands: readonly AnchorDemand[]): Promise<void>
 }
+export type AnchorDemand = { sinceSha: string; entries: readonly RelationEntry[] }
 
 // a verdict answers ONE selector set, so the set is part of its identity: several scenarios anchoring
 // DIFFERENT units of one shared file is the whole point of narrowing, and keying only by (sha, path) would
@@ -268,13 +273,29 @@ export type AnchorProbe = {
 const anchorKey = (sinceSha: string, path: string, selectors: readonly string[]) =>
   `${sinceSha}\x1f${path}\x1f${[...selectors].sort().join('\x1e')}`
 
-// the eval code window: commits touching `path` in sinceSha..HEAD by the same true ancestry `changedSince`
-// uses, from the same index source — so the anchor check can only narrow the very set the file question just
-// answered `true` for. null = ancestry cannot testify (off-history anchor) → the caller stays conservative.
-function evalWindowCommits(idx: DriftIndex, sinceSha: string, path: string): DriftPathEvent[] | null {
-  const anc = ancestorsOf(idx, sinceSha)
-  if (!anc) return null
-  return pathEvents(idx, path).filter((event) => !inAncestors(idx, anc, event.commit))
+// @@@ one parse per CONTENT, not per selector entry - a node's `code:` entries are asked one at a time, and
+// the same working-tree file backs many of them, so the unmemoized read parsed 46 distinct files 922 times
+// per build (40.4 MB through the TypeScript parser) and did it again on every rebuild. `extract` is a pure
+// function of (text, path, extractor), so its result is reusable exactly as far as the CONTENT is unchanged.
+// The key is a content digest and never mtime/size: this gate decides whether a reading may testify, so a
+// stale unit list would let a dead selector read as alive — the precise failure the comment below warns
+// about. Digesting is ~10x cheaper than parsing, so the read stays and only the parse is saved. Bounded like
+// the historical-revision memo it mirrors ([[code-anchor]]), and it caches the extractor's REJECTION too, so
+// an unparseable file does not re-parse once per entry.
+const CURRENT_TREE_MEMO_MAX = 4096
+const currentTreeUnitMemo = new Map<string, { units: Unit[] } | { failed: string }>()
+function currentTreeUnits(root: string, x: Extractor, path: string): Unit[] {
+  const source = readFileSync(join(root, path), 'utf8')
+  const key = `${x.memoKey(path)}\0${createHash('sha1').update(source).digest('hex')}`
+  const hit = currentTreeUnitMemo.get(key)
+  if (hit) { if ('failed' in hit) throw new Error(hit.failed); return hit.units }
+  let entry: { units: Unit[] } | { failed: string }
+  try { entry = { units: x.extract(source, path) } }
+  catch (err: any) { entry = { failed: err?.message ?? String(err) } }
+  if (currentTreeUnitMemo.size >= CURRENT_TREE_MEMO_MAX) currentTreeUnitMemo.clear()
+  currentTreeUnitMemo.set(key, entry)
+  if ('failed' in entry) throw new Error(entry.failed)
+  return entry.units
 }
 
 // every selector of one entry resolves to exactly one unit in the CURRENT tree, or the entry cannot testify.
@@ -288,32 +309,55 @@ function entryUnverifiable(root: string, regs: Extractor[], entry: RelationEntry
   const ready = x.ready()
   if (ready !== true) return `\`code\` anchors on ${entry.path} are unverified: ${ready}`
   let units
-  try { units = x.extract(readFileSync(join(root, entry.path), 'utf8'), entry.path) }
+  try { units = currentTreeUnits(root, x, entry.path) }
   catch (err: any) { return `\`code\` anchors on ${entry.path} are unverified: ${err?.message ?? String(err)}` }
-  for (const sym of entry.selectors) {
-    const r = resolveAnchor(units, sym)
-    if ('dead' in r) return `\`code\` selector \`${entry.path}#${sym}\` names no unit in that file — follow the rename or drop the selector (evals stay stale until then)`
-    if ('ambiguous' in r) return `\`code\` selector \`${entry.path}#${sym}\` is ambiguous — ${r.ambiguous} units share that name; pin a unique one`
+  // the SAME classifier the gate uses ([[code-anchor]]'s resolveSelectors) — only the wording is ours, so a
+  // selector can never be verifiable to one reader and dead to the other.
+  for (const r of resolveSelectors(units, entry.selectors)) {
+    if ('dead' in r) return `\`code\` selector \`${entry.path}#${r.selector}\` names no unit in that file — follow the rename or drop the selector (evals stay stale until then)`
+    if ('ambiguous' in r) return `\`code\` selector \`${entry.path}#${r.selector}\` is ambiguous — ${r.ambiguous} units share that name; pin a unique one`
   }
   return null
 }
 
+// @@@ the verify sweep must reach the MACROTASK queue - resolving every reading's `code:` selectors against
+// the working tree is a doubly-nested SYNCHRONOUS sweep (4,384 demands on this corpus), and nothing in it
+// awaits, so it ran as one uninterruptible stretch: measured, it held the loop for 1,104ms, which is the
+// `/health` p99 this gate is judged by. The bound defended here is a LIVENESS signal, not a latency taste —
+// a probe that cannot answer is indistinguishable from a dead backend, and the CLI allows it 600ms while the
+// supervisor allows 1,000ms before it keeps the old child. `setImmediate` is what actually returns to the
+// loop's I/O phase (awaiting a synchronous-bodied async fn only drains microtasks). A time budget rather
+// than every-iteration keeps the common cheap iteration from paying a turn: the sweep's own longest single
+// step is one file parse, so the worst hold stays near budget + that step.
+const VERIFY_YIELD_BUDGET_MS = Number(process.env.SPEXCODE_VERIFY_YIELD_BUDGET_MS || 50)
+const yieldToEventLoop = (): Promise<void> => new Promise<void>((resolve) => { setImmediate(resolve) })
+
 export function anchorProbeFor(root: string, idx: DriftIndex): AnchorProbe {
   const regs = extractors(root)
   const verdicts = new Map<string, boolean>()
   return {
-    async prime(sinceSha, entries) {
-      for (const e of entries) {
+    async prime(demands) {
+      const keys: string[] = []
+      const queries: AnchorHitQuery[] = []
+      const queued = new Set<string>()
+      let sinceYield = Date.now()
+      for (const { sinceSha, entries } of demands) for (const e of entries) {
+        if (Date.now() - sinceYield >= VERIFY_YIELD_BUDGET_MS) { await yieldToEventLoop(); sinceYield = Date.now() }
         if (!e.selectors.length) continue
         const key = anchorKey(sinceSha, e.path, e.selectors)
-        if (verdicts.has(key)) continue
+        if (verdicts.has(key) || queued.has(key)) continue
         if (entryUnverifiable(root, regs, e)) continue  // no verdict → conservative stale (lint says why)
-        const win = evalWindowCommits(idx, sinceSha, e.path)
+        const win = eventsSince(idx, sinceSha, e.path)
         if (win === null) continue
         if (!win.length) { verdicts.set(key, false); continue }
-        const hits = await anchorHitCommits(root, win, [...e.selectors], regs)
-        verdicts.set(key, hits.length > 0)
+        queued.add(key)
+        keys.push(key)
+        queries.push({ win, symbols: [...e.selectors] })
       }
+
+      if (!queries.length) return
+      const results = await anchorHitExists(root, queries, regs)
+      results.forEach((hit, index) => verdicts.set(keys[index], hit))
     },
     hit(sinceSha, path, selectors) {
       return verdicts.get(anchorKey(sinceSha, path, selectors)) ?? null
@@ -355,8 +399,10 @@ export function remarkStale(reading: { ts: string }, remarks: RemarkSignal[]): b
 // ContentProbe above); without a probe — or when the anchor object is gone — freshness can't be proven
 // from HEAD's history, so it reads stale rather than silently pass.
 export function changedSince(idx: DriftIndex, sinceSha: string, path: string, probe?: ContentProbe): boolean {
-  const anc = ancestorsOf(idx, sinceSha)
-  if (anc) return pathEvents(idx, path).some((event) => !inAncestors(idx, anc, event.commit))
+  const events = eventsSince(idx, sinceSha, path)
+  // null = ancestry cannot testify for this anchor; only then does content get a say ([[root-lru]]'s sibling
+  // rule: one meaning of changed-since, each layer's own fallback on top).
+  if (events) return events.length > 0
   return probe?.changed(sinceSha, path) ?? true
 }
 
@@ -366,16 +412,16 @@ export function changedSince(idx: DriftIndex, sinceSha: string, path: string, pr
 // an off-history sinceSha reports through the same content fallback (only files whose content differs, counted
 // by rev-list); with no probe or a gone anchor it counts every touch (conservative, matching changedSince).
 // Reporting only — it never decides freshness (staleAxes does); it explains a decision already made.
-export function codeDrift(idx: DriftIndex, sinceSha: string, codeAxis: string[], probe?: ContentProbe): { file: string; behind: number }[] {
+export function codeDrift(idx: DriftIndex, sinceSha: string, codeAxis: ScenarioCodeAxisSource, probe?: ContentProbe): { file: string; behind: number }[] {
   // an entry may be anchored (`path#symbol`); drift is reported per BASE FILE — a raw selector string names
   // no real path, so counting commits against it would silently report nothing.
-  const codeFiles = scenarioCodeAxis(codeAxis).paths
-  const anc = ancestorsOf(idx, sinceSha)
+  const codeFiles = scenarioCodeAxis(undefined, codeAxis).paths
   const out: { file: string; behind: number }[] = []
   for (const f of codeFiles) {
+    const since = eventsSince(idx, sinceSha, f)
     const events = pathEvents(idx, f)
-    const differs = anc ? undefined : probe?.changed(sinceSha, f)
-    const behind = anc ? new Set(events.filter((event) => !inAncestors(idx, anc, event.commit)).map((event) => event.commit)).size
+    const differs = since ? undefined : probe?.changed(sinceSha, f)
+    const behind = since ? new Set(since.map((event) => event.commit)).size
       : differs === true ? probe!.behind(sinceSha, f)
       : differs === false ? 0
       : new Set(events.map((event) => event.commit)).size
@@ -428,7 +474,7 @@ function entryMoved(idx: DriftIndex, sinceSha: string, entry: RelationEntry, pro
 
 export function staleAxes(
   reading: Reading,
-  codeAxis: string[],
+  codeAxis: ScenarioCodeAxisSource,
   evalPath: string,
   didx: DriftIndex,
   scIdx: ScenarioIndex,
@@ -445,7 +491,7 @@ export function staleAxes(
     axes.push('anchor')
     if (byHash) axes.push('scenario')
   } else {
-    if (scenarioCodeAxis(codeAxis).entries.some((e) => entryMoved(didx, reading.codeSha, e, probe, anchors))) axes.push('code')
+    if (scenarioCodeAxis(undefined, codeAxis).entries.some((e) => entryMoved(didx, reading.codeSha, e, probe, anchors))) axes.push('code')
     if (byHash ?? scenarioMoved(scIdx, didx, reading.codeSha, evalPath, reading.scenario, probe)) axes.push('scenario')
   }
   if (remarkStale(reading, remarks)) axes.push('remark')
@@ -454,7 +500,7 @@ export function staleAxes(
 
 export function isStale(
   reading: Reading,
-  codeAxis: string[],
+  codeAxis: ScenarioCodeAxisSource,
   evalPath: string,
   didx: DriftIndex,
   scIdx: ScenarioIndex,

package/spec-eval/src/humanok.ts

@@ -4,36 +4,21 @@ import { commitTrunkData } from '../../spec-cli/src/localIssues.js'
 import { evalNodes, resolveEvalNode } from './scenarios.js'
 import { readReadings, readSidecar, appendHumanOk, humanOkFor, type HumanOk } from './sidecar.js'
 
-// @@@ human-ok - the human sign-off on an eval reading ([[human-ok]]). One write, both surfaces: the CLI
-// (`spex eval ok`) and the HTTP route (`POST /api/specs/:id/evals/ok`, identity server-derived 'human')
-// call THIS. The ok binds to ONE immutable reading — the scenario's latest effective reading at ok-time,
-// anchored by its (ts, codeSha) — and is MONOTONIC: no un-ok verb exists, because a newer reading is a
-// different object the ok never transfers to, and staleness is computed live; both bring the scenario back
-// on their own. Durability follows the checkout: on the trunk checkout the append is committed straight to
-// trunk (`--no-verify`, path-scoped, under the shared store lock — the [[local-issues]] discipline,
-// commitTrunkData); on a linked worktree the append stays in that tree and the session's own ritual commit
-// carries it, exactly like every other sidecar write.
 export type OkResult =
   | { ok: true; humanOk: HumanOk; already: boolean; landed: 'committed' | 'uncommitted' }
   | { ok: false; error: string }
 
 export function fileHumanOk(nodeId: string, scenario: string, by: string): OkResult {
   const root = repoRoot()
-  // the same loud resolution every eval verb applies ([[eval-core]]): exact canonical id, else a unique
-  // bare leaf; an ambiguous leaf returns the candidate list instead of blessing an arbitrary node.
   const res = resolveEvalNode(evalNodes(root), nodeId)
   if (!res.ok) return { ok: false, error: res.error }
   const node = res.node
   if (!node.scenarios.some((s) => s.name === scenario) &&
       !readSidecar(node.sidecarPath).readings.some((r) => r.scenario === scenario))
     return { ok: false, error: `'${node.id}' has no scenario '${scenario}'` }
-  // the ok's one possible target: the latest EFFECTIVE reading — an ok is a judgment on a measurement that
-  // exists and currently counts; an unmeasured (or fully-retracted) scenario has nothing to bless.
   const forScenario = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
   if (!forScenario.length) return { ok: false, error: `'${node.id}' scenario '${scenario}' has no effective eval — nothing to ok` }
   const latest = forScenario[forScenario.length - 1]
-  // a duplicate ok is idempotent success (the store already IS the requested state — the local-issue
-  // close's `already` semantics), never an error and never a second appended row.
   const existing = humanOkFor(readSidecar(node.sidecarPath).oks, scenario, latest.ts)
   if (existing) return { ok: true, humanOk: existing, already: true, landed: 'committed' }
   const row: HumanOk = { kind: 'human-ok', scenario, okTs: latest.ts, okSha: latest.codeSha, by, ts: new Date().toISOString() }

package/spec-eval/src/scenariofresh.ts

@@ -1,31 +1,12 @@
 import { spawn } from 'node:child_process'
 import { git, gitA, gitTry, headSha } from '../../spec-cli/src/git.js'
 import { parseScenarios } from './scenarios.js'
-
-// @@@ per-scenario content freshness — the SCENARIO axis, sub-file
-// An eval.md holds many scenarios, but a reading measures ONE. eval-core's contract says "a scenario is the
-// unit of measurement, so its freshness is its OWN — two scenarios stale independently." Git has no sub-file
-// history, so we build it: for each scenario NAME in an eval.md, the commits where THAT scenario's SEMANTIC
-// block content (description + expected — see blockContent) changed (added / removed / edited),
-// rename-followed. `scenarioMoved` then reads exactly like the code axis's `changedSince` — a pure ancestry
-// lookup over this per-scenario commit list — so editing one scenario never re-stales its siblings (the
-// file-granular bug this replaces), and retagging one never re-stales itself.
+import { rootSlots, touchRoot as touchRootLru } from '../../spec-cli/src/root-lru.js'
 
 const RS = '\x1e'
 
-// evalPath (head path) -> scenario name -> commit hashes that changed that scenario's block (newest-first)
 export type ScenarioIndex = Map<string, Map<string, string[]>>
 
-// the block content that stales a reading: the scenario's SEMANTIC fields only — description (what to
-// measure) + expected (what zero loss looks like), the contract a measurement is taken AGAINST. The name is
-// the join key (a renamed scenario is a remove+add, surfaced as a change-commit on each name), and the
-// metadata fields are OUT: tags route a scenario to a measuring hand, test/code/related point at files —
-// none of them changes what an already-taken reading proved, so a tags sweep or a coverage retune must not
-// re-stale every reading in the tree. Both freshness paths (the in-history change-commits and the
-// off-history scenarioDiffers probe) read THIS one projection — narrowing it here narrows both at once, and
-// because freshness is derived live from git, historical metadata-only commits stop registering as scenario
-// changes with no migration. parseScenarios already folds YAML block scalars, so a pure prose re-wrap
-// yields the same string and does NOT stale.
 function blockContent(src: string): Map<string, string> {
   const m = new Map<string, string>()
   for (const s of parseScenarios(src)) {
@@ -34,30 +15,14 @@ function blockContent(src: string): Map<string, string> {
   return m
 }
 
-const ZERO = '0'.repeat(40)   // the null OID a delete/add carries on its absent side
+const ZERO = '0'.repeat(40)
 const EMPTY: Map<string, string> = new Map()
 
-// content-addressed: a blob OID -> its canonical per-scenario block map. Git objects are IMMUTABLE, so this
-// memo never needs invalidation and is shared across every root — a per-worktree build reuses the blocks main
-// already parsed, which is what lets a worktree's freshness build stay cheap instead of re-reading everything.
 const blockByOid = new Map<string, Map<string, string>>()
 
-// ONE `git log --raw` walk over all eval.md → per head-path version chain [{hash, oid}], newest-first,
-// rename-followed via the `alias` idiom (git.ts buildIndex): the newest sighting of a path IS its head path;
-// an `R` row remaps the older `from` path onto that head. The raw row carries the new blob OID directly, so
-// no per-version path resolution and no `git show`. --full-history is REQUIRED: default pathspec
-// history-simplification prunes commits off HEAD's first-parent chain, but in this repo every spec edit lands
-// via a --no-ff merge of a node branch, so those pruned commits ARE the scenario edits — dropping them would
-// under-report staleness (a stale reading judged fresh). Merge commits emit no raw diff row, so they add no
-// version (exactly as the old `--follow` did).
 async function fileChains(root: string, wanted: Set<string>): Promise<Map<string, { hash: string; oid: string }[]>> {
   const chains = new Map<string, { hash: string; oid: string }[]>()
   const alias = new Map<string, string>()
-  // DUAL pathspec — the live name AND the archived one ([[eval-core]]): this walk reads IMMUTABLE history,
-  // and pre-rename commits touched files literally named yatsu.md, so an archive answers only to its
-  // archive name. A single '*eval.md' pathspec truncates every chain at the yatsu.md→eval.md rename commit,
-  // making the rename read as each scenario's birth — a change-commit newer than every pre-rename reading's
-  // codeSha — and false-stales whole adopter corpora (the scenariofresh.test.ts regression pins this).
   const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log',
     '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*eval.md', '*yatsu.md']) // dead-words-ok: archived pathspec — immutable pre-rename history is read under its archived name
   for (const rec of out.split(RS)) {
@@ -72,22 +37,18 @@ async function fileChains(root: string, wanted: Set<string>): Promise<Map<string
       const meta = line.slice(1, tab).split(' ')
       const oid = meta[3], rename = meta[4][0] === 'R' || meta[4][0] === 'C'
       const paths = line.slice(tab + 1).split('\t')
-      const to = rename ? paths[1] : paths[0]   // the path on the newer side of this commit
+      const to = rename ? paths[1] : paths[0]
       let head = alias.get(to)
       if (head === undefined) { head = to; alias.set(to, to) }
       let arr = chains.get(head); if (!arr) { arr = []; chains.set(head, arr) }
       arr.push({ hash, oid })
-      if (rename && paths[0] !== to) { alias.set(paths[0], head); alias.delete(to) }   // older history calls it `from`
+      if (rename && paths[0] !== to) { alias.set(paths[0], head); alias.delete(to) }
     }
   }
-  for (const k of [...chains.keys()]) if (!wanted.has(k)) chains.delete(k)   // keep only the head paths asked for
+  for (const k of [...chains.keys()]) if (!wanted.has(k)) chains.delete(k)
   return chains
 }
 
-// per-scenario change-commits for one file's version chain: newest->oldest, attribute a commit to every
-// scenario whose canonical block differs from the next-older version (undefined either side = add/remove = a
-// change). A ZERO-oid (delete) version is dropped — it carries no readable content, matching the old
-// `git show ''` skip; a pure rename (R100, oid == the older version's oid) diffs to no change for free.
 function scenarioCommits(chain: { hash: string; oid: string }[]): Map<string, string[]> {
   const commits = new Map<string, string[]>()
   const push = (name: string, hash: string) => { const a = commits.get(name); if (a) a.push(hash); else commits.set(name, [hash]) }
@@ -142,8 +103,6 @@ function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>
   })
 }
 
-// TWO git subprocesses for the whole index (was F logs + V shows): one `--raw` log for the rename-followed
-// chains, one `cat-file --batch` for every distinct blob not already memoized. Then a pure in-memory diff.
 async function build(root: string, evalPaths: string[]): Promise<ScenarioIndex> {
   const chains = await fileChains(root, new Set(evalPaths))
   const need = new Set<string>()
@@ -153,35 +112,16 @@ async function build(root: string, evalPaths: string[]): Promise<ScenarioIndex>
     for (const [oid, src] of blobs) blockByOid.set(oid, blockContent(src))
   }
   const idx: ScenarioIndex = new Map()
-  for (const p of evalPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))   // every asked path gets an entry (empty if untracked)
+  for (const p of evalPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))
   return idx
 }
 
-// HEAD-keyed LRU, mirroring historyIndex/driftIndex in git.ts: same head ⇒ same per-scenario history,
-// whatever the caller. Holds the in-flight promise so concurrent board builds share one build.
-const SLOTS = 16
+const SLOTS = rootSlots(process.env.SPEXCODE_SCENARIO_CACHE_ROOTS, 16)
 const cache = new Map<string, Promise<ScenarioIndex>>()
 const roots = new Map<string, string>()
 
-// A checkout moving from HEAD A to HEAD B no longer needs A's full scenario chains. Keep an old index only
-// while another checkout still points at that immutable HEAD; otherwise a sequence of successful rebuilds
-// retains one whole history-shaped index per commit until the broad LRU fills.
 function touchRoot(root: string, head: string): void {
-  const previous = roots.get(root)
-  if (previous === head) {
-    roots.delete(root)
-    roots.set(root, head)
-    return
-  }
-  roots.set(root, head)
-  if (previous && ![...roots.values()].includes(previous)) cache.delete(previous)
-  while (roots.size > SLOTS) {
-    const oldest = roots.keys().next().value as string | undefined
-    if (oldest === undefined) break
-    const oldHead = roots.get(oldest)
-    roots.delete(oldest)
-    if (oldHead && ![...roots.values()].includes(oldHead)) cache.delete(oldHead)
-  }
+  touchRootLru(roots, cache, root, head, SLOTS)
 }
 
 export function scenarioIndex(root: string, evalPaths: string[]): Promise<ScenarioIndex> {
@@ -205,13 +145,6 @@ export function scenarioChangeCommits(idx: ScenarioIndex, evalPath: string, scen
   return idx.get(evalPath)?.get(scenario) ?? []
 }
 
-// (root, sha, path) -> the blob oid at that commit ('' = unresolvable: path absent there, or the commit
-// object gone). A FULL sha names an immutable tree, so entries never invalidate (freshness.ts's diffMemo
-// reasoning); the LRU only bounds memory, sized above the largest adopter reading corpus — one entry per
-// (reading, path) worst case — so a repeat board build never thrashes back into forking. This memo is what
-// keeps a fully off-history corpus (an adopter history rewrite) cheap on REPEAT builds: without it every
-// scenarioDiffers call re-forked `git rev-parse` for BOTH sides, per reading, per build (spexcode#39). A
-// symbolic rev (HEAD, a branch) moves, so it resolves live and is never cached.
 const FULL_SHA = /^[0-9a-f]{40}$/
 const oidMemo = new Map<string, string>()
 function oidAt(root: string, rev: string, path: string): string {
@@ -248,11 +181,6 @@ export async function primeScenarioBlocksAt(root: string, revs: string[], path:
   }
 }
 
-// canonical per-scenario SEMANTIC blocks of `rev:path` (the blockContent projection), for the off-history
-// content fallback ([[eval-core]]'s ContentProbe): resolve the blob oid first (memoized above for a full
-// sha) — oids are content-addressed, so an unchanged file usually hits blockByOid straight from the index
-// build — and parse only on a genuine miss. null = the path is unreadable at that rev (absent, renamed
-// since, or the rev itself is gone).
 export function scenarioBlocksAt(root: string, rev: string, path: string): Map<string, string> | null {
   const oid = oidAt(root, rev, path)
   if (!oid) return null

package/spec-eval/src/scenarios.ts

@@ -24,10 +24,6 @@ export type Scenario = {
   related?: string[]
 }
 
-// The scenario index is a declaration projection, not a reading view. Keep its three identity layers
-// explicit: scenarioHash is the measurement-contract hash, semanticIndexHash is the canonical declaration
-// index, and fullIndexHash adds only the measuring-hand test mapping. Git provenance is supplied by the CLI
-// outside both hashes, so a mode/type change cannot masquerade as a scenario-content change.
 export const SCENARIO_PROJECTION = 'spex.eval.scenario-index'
 export const SCENARIO_SCHEMA_VERSION = 1
 export type ScenarioSemanticRow = {
@@ -56,13 +52,11 @@ export type ScenarioProjection = {
 }
 
 export type EvalNode = {
-  id: string            // the node's CANONICAL spec id (leaf name, '_'-disambiguated on a leaf collision)
-  dir: string           // absolute node directory
-  evalPath: string     // repo-relative path to eval.md — the SCENARIO freshness axis
-  sidecarPath: string   // absolute path to evals.ndjson
+  id: string
+  dir: string
+  evalPath: string
+  sidecarPath: string
   scenarios: Scenario[]
-  // The exact declaration bytes used to build this node, present for real filesystem and fixed-tree walks.
-  // Synthetic EvalNode values in narrow unit tests may omit it.
   evalSource?: string
 }
 
@@ -81,8 +75,6 @@ type RawTestObject = {
 
 type RawFieldLocation = { startLine: number; endLine: number; indent: string }
 
-// a raw scenario item straight off the frontmatter walk: the known fields it set, plus any UNKNOWN keys it
-// carried — kept (not dropped) so the validator can name a typo'd field instead of silently swallowing it.
 type RawItem = {
   fields: Partial<Record<ScenarioKey, string>>
   testObject?: RawTestObject
@@ -95,7 +87,7 @@ type RawItem = {
 
 const leadingIndent = (line: string): string => line.match(/^[ \t]*/)?.[0] ?? ''
 
-// tiny indentation parser for eval.md's frontmatter `scenarios:` block (no YAML dep), shared by parseScenarios and validateScenarios so they can't disagree; reports hasFrontmatter/hasKey so the validator can tell "none declared" from "malformed"
+// Keep parsing and validation on the same structural walk.
 function walkScenarios(src: string): { hasFrontmatter: boolean; hasKey: boolean; items: RawItem[]; malformed: string[] } {
   const normalized = src.replace(/\r\n?/g, '\n')
   const m = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)
@@ -120,7 +112,6 @@ function walkScenarios(src: string): { hasFrontmatter: boolean; hasKey: boolean;
     const trimmed = line.trim()
     const dash = trimmed.startsWith('- ') || trimmed === '-'
     if (dash && (itemIndent < 0 || indent <= itemIndent)) {
-      // a new scenario item. start fresh; the `- ` may carry the first field inline.
       cur = {
         fields: {}, unknownKeys: [], duplicateKeys: [], malformed: [], locations: {},
         ...(trimmed.slice(1).trim() ? { fieldIndent: `${prefix}  ` } : {}),
@@ -146,11 +137,6 @@ function walkScenarios(src: string): { hasFrontmatter: boolean; hasKey: boolean;
   return { hasFrontmatter: true, hasKey: true, items, malformed }
 }
 
-// assign a `key: value` field to the current item. When the value is a block-scalar indicator (`|`
-// literal / `>` folded), consume the following more-indented lines as the value and return the index of
-// the LAST consumed line (the for-loop's ++ then moves past it); otherwise return `idx` unchanged. A key
-// outside the schema is recorded under unknownKeys (still consuming its block, so the body isn't misread as
-// new items) rather than dropped — validateScenarios needs to see it to reject the typo.
 function assignField(cur: RawItem, kv: string, lines: string[], idx: number, keyIndent: number, inline = false): number {
   const f = kv.match(/^([A-Za-z_][\w-]*):\s*(.*)$/)
   if (!f) {
@@ -200,7 +186,6 @@ function assignField(cur: RawItem, kv: string, lines: string[], idx: number, key
       return finish(idx)
     }
   }
-  // a list field (`code:`/`related:`) may be a YAML block sequence (`- item` lines); the scalar reader can't see those, so collect them here into the comma form parseCodeList expects
   if ((LIST_KEYS as readonly string[]).includes(key) && f[2].trim() === '') {
     const items: string[] = []
     let lastItem = idx
@@ -234,8 +219,7 @@ function assignField(cur: RawItem, kv: string, lines: string[], idx: number, key
       const tabInIndent = tabBeforeContent && spaces.length < requiredIndent
       if (tabInIndent) cur.malformed.push(`tab indentation is not valid in block scalar \`${key}\``)
       if (!l.trim() && !tabBeforeContent) { body.push(''); continue }
-      // YAML indentation is spaces-only. Once the line is deeper than its key, a leading TAB belongs to the
-      // scalar content and must survive parsing; before the block's required depth it is illegal indentation.
+      // A tab after the required indent is scalar content, not indentation.
       const ind = tabInIndent ? leadingIndent(l).length : spaces.length
       if (ind <= keyIndent) break   // dedented to a sibling field / next item → the block is done
       if (base < 0) base = ind
@@ -275,8 +259,7 @@ function assignTestField(obj: RawTestObject, entry: string): void {
   obj.fields[key as TestKey] = testValue(f[2], key === 'name')
 }
 
-// A flow mapping is accepted beside the more readable block form. Split only on commas outside quotes so
-// an opaque case name such as "allows admin, user" survives byte-for-byte after YAML quote removal.
+// Test names may contain commas inside quotes.
 function parseFlowTestObject(raw: string): RawTestObject {
   const obj = emptyTestObject()
   if (!raw.startsWith('{') || !raw.endsWith('}')) {
@@ -317,36 +300,23 @@ function normalizedTest(it: RawItem): ScenarioTestReference | undefined {
   return path ? { path } : undefined
 }
 
-// @@@scenario contract hash - the deterministic content hash of a scenario's SEMANTIC text, stamped on each
-// reading at filing time ([[eval-core]]'s scenario freshness axis). Hashes ONLY the measurement contract —
-// description (what to measure) + expected (what zero loss looks like) — never name/tags/test/code/related.
-// Normalization (spec'd, don't drift): each field independently collapses every whitespace run (space, tab,
-// CR, LF) to a single space and trims its ends, so a prose re-wrap, an indent shift, CRLF churn or trailing
-// whitespace never changes the hash; the two normalized fields join with a single '\n' (neither can contain
-// one after normalization, so the join is unambiguous) and sha256-hex the UTF-8 bytes. The hash is pure text
-// over the parsed declaration — no git, no file position — so it is identical wherever and however the same
-// contract text is read.
 const normSemantic = (s: string) => s.replace(/\s+/g, ' ').trim()
 export function scenarioHash(s: Pick<Scenario, 'description' | 'expected'>): string {
   return createHash('sha256').update(`${normSemantic(s.description)}\n${normSemantic(s.expected)}`, 'utf8').digest('hex')
 }
 
-// @@@scenario code axis - the ONE resolution of a scenario's code freshness axis, so a declaration can never
-// mean two things to two consumers. A scenario's own `code:` narrows the node's list; absent, it inherits it
-// whole ([[eval-core]]). Each entry may carry [[code-anchor]]'s `path#symbol` selectors, folded per base file
-// by the SAME structural parser spec relations use (several selectors on one file OR together; duplicates,
-// bare+scoped mixing and a selector on a glob come back as `problems` for lint to report).
-// `paths` is what every PATH consumer must read — changed-scan selection, session impact, drift display,
-// the ghost-path check — because a raw `path#symbol` string matches no real file and would silently drop the
-// scenario out of those sets instead of narrowing it. `entries` is what the freshness code axis narrows with.
 export type ScenarioCodeAxis = { entries: RelationEntry[]; paths: string[]; problems: string[] }
-export function scenarioCodeAxis(scenarioCode: readonly string[] | undefined, nodeCode: readonly string[] = []): ScenarioCodeAxis {
-  const { entries, problems } = parseRelation([...(scenarioCode?.length ? scenarioCode : nodeCode)], 'code')
+export type ScenarioCodeAxisSource = readonly string[] | readonly RelationEntry[]
+export function scenarioCodeAxis(scenarioCode: readonly string[] | undefined, nodeCode: ScenarioCodeAxisSource = []): ScenarioCodeAxis {
+  const parsed = scenarioCode?.length
+    ? parseRelation([...scenarioCode], 'code')
+    : nodeCode.length && typeof nodeCode[0] !== 'string'
+      ? { entries: (nodeCode as readonly RelationEntry[]).map((e) => ({ path: e.path, selectors: [...e.selectors] })), problems: [] }
+      : parseRelation([...(nodeCode as readonly string[])], 'code')
+  const { entries, problems } = parsed
   return { entries, paths: entries.map((e) => e.path), problems }
 }
 
-// a scenario's optional list field (`code:`/`related:`) is a comma-separated path list (a YAML flow list
-// `[a, b]` or bare `a, b`, or a single path) — the tiny parser stays scalar-only, so it is split here.
 function parseCodeList(raw: string): string[] {
   return raw.replace(/^\[|\]$/g, '').split(',').map((s) => unquote(s.trim())).filter(Boolean)
 }
@@ -368,7 +338,7 @@ export function parseScenarios(src: string): Scenario[] {
         ...(related.length ? { related } : {}),
       }
     })
-    .filter((s) => s.name)   // a scenario with no name is malformed — drop it (validateScenarios reports it)
+    .filter((s) => s.name)
 }
 
 const compareStable = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0
@@ -380,8 +350,6 @@ const hashProjection = (value: unknown): string =>
 
 const semanticOnly = (row: ScenarioProjectionRow): ScenarioSemanticRow => row.semantic
 
-// Build one canonical declaration index from the already-parsed scenarios. No eval sidecar is touched here;
-// callers can safely use this projection to compare fixed trees without importing the reading/freshness path.
 export function scenarioProjection(
   nodes: readonly Pick<EvalNode, 'id' | 'scenarios' | 'evalSource'>[],
   provenance: Partial<ScenarioProjectionProvenance> = {},
@@ -426,10 +394,6 @@ export function scenarioProjection(
   }
 }
 
-// `tagLibrary` is the closed vocabulary a scenario's `tags:` must draw from (config's `lint.scenarioTags`).
-// Every scenario needs ≥1 tag; each tag must be IN the library — an out-of-library tag is rejected LOUD with
-// the repair the user owns: pick an existing tag, or extend the library. An empty library (none configured)
-// disables only the membership check, never the ≥1-tag requirement.
 export function validateScenarios(src: string, tagLibrary: string[] = [], pathRoot?: string): string[] {
   const { hasFrontmatter, hasKey, items, malformed } = walkScenarios(src)
   if (!hasFrontmatter) return ['no frontmatter block — an eval.md must declare a `scenarios:` list']
@@ -528,9 +492,6 @@ function malformedDeclaration(errors: string[]): Error {
   return new Error(`malformed eval.md:\n${errors.map((error) => `  - ${error}`).join('\n')}`)
 }
 
-// Canonical write half of the declaration identity. The caller supplies authoritative bytes and one closed
-// semantic mutation; source locations come only from the same structural walk parseScenarios/validation use.
-// Untouched lines are never serialized, which is what makes insert -> delete a byte-exact inverse.
 export function writeScenarioMeasurementMetadata(source: string, request: unknown): string {
   const mutation = parseMetadataMutation(request)
   const beforeErrors = validateScenarios(source)
@@ -582,12 +543,6 @@ export function writeScenarioMeasurementMetadata(source: string, request: unknow
   return proposed
 }
 
-// walk `.spec` for every dir holding an eval.md; the node id is its CANONICAL spec id ([[id-url-safe]]) —
-// minted by the SAME rule as specs.ts's loader (mintIds: the leaf dir name, or on a leaf collision the
-// shortest globally-unique '_'-joined trailing suffix) over the SAME universe (every dir holding a spec.md,
-// not just the eval subset — a leaf that collides among spec nodes is disambiguated even when only one of
-// them measures). So the id eval verbs answer to is exactly the id board/scan/search already print — never a
-// second, diverging bare-leaf scheme. An eval.md beside no spec.md keeps its leaf name (no spec id to align with).
 function assembleNodes(root: string, specDirs: string[], hits: { dir: string; src: string }[]): EvalNode[] {
   const specBase = join(root, '.spec')
   const ids = mintIds(specDirs.map((d) => relative(specBase, d).split(/[/\\]/)))
@@ -620,8 +575,6 @@ export function evalNodes(root: string): EvalNode[] {
   return assembleNodes(root, specDirs, hits)
 }
 
-// Exact fixed-tree twin for the canonical JSON seam. It reads only eval.md/spec.md bytes from `tip`, then
-// reuses assembleNodes/parseScenarios; no working-tree declaration can be paired with that tree's provenance.
 export function evalNodesAt(root: string, tip: string): EvalNode[] {
   const files = treeTextFiles(root, tip, '.spec')
   const paths = [...files.keys()]
@@ -659,10 +612,6 @@ export async function evalNodesAsync(root: string): Promise<EvalNode[]> {
 
 export type EvalResolution<T> = { ok: true; node: T } | { ok: false; ambiguous: boolean; error: string }
 
-// resolve a user-supplied node ref against the measurable set: an EXACT canonical id always wins; a bare leaf
-// name stays the convenience it always was while it names exactly ONE measurable node; a leaf several nodes
-// share fails LOUD listing the candidate canonical ids — never an arbitrary first hit, so a reading can
-// only land on the node the caller actually named.
 export function resolveEvalNode<T extends Pick<EvalNode, 'id' | 'dir'>>(nodes: T[], ref: string): EvalResolution<T> {
   const exact = nodes.find((n) => n.id === ref)
   if (exact) return { ok: true, node: exact }