spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-eval/dist/freshness.js

@@ -0,0 +1,799 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { batchRevisionOids, gitTry, headSha, gitObjectInterpretation, currentGitBuildAbortSignal, gitAbortError, ancestorsOf, inAncestors, commitReachable, pathEvents, primeAncestorClosures, unionTopology, eventsSince } from '@spexcode/spec-core';
+import { anchorHitExists, extOf, extractorFor, extractors, resolveSelectors } from '@spexcode/spec-core';
+import { scenarioCodeAxis, scenarioHash } from './scenarios.js';
+import { scenarioChangeCommits, scenarioBlocksAt, primeScenarioBlocks } from './scenariofresh.js';
+const rootScopes = new Map();
+// Roots come and go (a closed worktree never asks again), so cap how many stay warm — the same bounded-slot
+// guard the index caches use, and the only bound needed once per-root cardinality is the corpus, not history.
+const ROOT_SLOTS = Math.max(4, Number(process.env.SPEXCODE_FRESHNESS_ROOT_SLOTS || 64));
+function scopeFor(rootKey, head, currentOid) {
+    const current = rootScopes.get(rootKey);
+    if (current?.head === head && (current.currentOid === currentOid || currentOid === null || current.currentOid === null)) {
+        if (currentOid !== null)
+            current.currentOid = currentOid;
+        rootScopes.delete(rootKey);
+        rootScopes.set(rootKey, current);
+        return current;
+    }
+    const scope = { head, currentOid, anchors: new Map(), topology: null, topologyRoster: new Set(), topologyFlight: null, blockDemands: new Set(), anchorVerdicts: new Map() };
+    rootScopes.set(rootKey, scope);
+    while (rootScopes.size > ROOT_SLOTS) {
+        const oldest = rootScopes.keys().next().value;
+        if (oldest === undefined || oldest === rootKey)
+            break;
+        rootScopes.delete(oldest);
+    }
+    return scope;
+}
+// a read only ever sees the root's CURRENT head — a probe pinned to a superseded head can't testify
+function currentScope(rootKey, head) {
+    const scope = rootScopes.get(rootKey);
+    return scope?.head === head ? scope : undefined;
+}
+// the cardinality invariant, made observable: how many anchor entries are resident at a root's CURRENT head
+// (every root when none is named). It must track the corpus's anchors, never how many times the board has
+// been rebuilt — one retained generation, not one per rebuild.
+export function freshnessCacheSize(root) {
+    if (root !== undefined)
+        return rootScopes.get(resolve(root))?.anchors.size ?? 0;
+    let total = 0;
+    for (const scope of rootScopes.values())
+        total += scope.anchors.size;
+    return total;
+}
+// The same invariant for the OTHER probe in this scope. It needs its own counter rather than a bigger number
+// from the one above: the two hold different things (content anchor entries vs selector-anchor verdicts), and
+// a counter that cannot see a case is exactly how "one retained generation, not one per rebuild" came to be
+// declared, observable, and still violated ([[selector-anchor-scope]]).
+export function anchorVerdictCacheSize(root) {
+    if (root !== undefined)
+        return rootScopes.get(resolve(root))?.anchorVerdicts.size ?? 0;
+    let total = 0;
+    for (const scope of rootScopes.values())
+        total += scope.anchorVerdicts.size;
+    return total;
+}
+function touchAnchor(scope, sha, imageOid) {
+    const hit = scope.anchors.get(sha);
+    if (hit && imageOid === undefined)
+        return hit;
+    if (hit && hit.imageOid == null && imageOid !== undefined) {
+        hit.imageOid = imageOid;
+        hit.gone = imageOid === null;
+        return hit;
+    }
+    if (hit && hit.imageOid === imageOid)
+        return hit;
+    const entry = { imageOid, verdicts: new Map(), gone: imageOid === null, pending: new Set(), flight: null };
+    scope.anchors.set(sha, entry);
+    return entry;
+}
+const heavyDiffScopes = new Map();
+// One tree comparison at a time is enough for a production repo's pack/index memory. The graph-wide git
+// permits still bound every child; this narrower domain scheduler keeps these immutable-tree
+// comparisons serial per (repo, HEAD), without teaching the git transport what a content fallback is.
+function acquireHeavyDiff(scopeKey, signal) {
+    if (signal?.aborted)
+        return Promise.reject(gitAbortError());
+    let scope = heavyDiffScopes.get(scopeKey);
+    if (!scope) {
+        scope = { active: false, waiting: [] };
+        heavyDiffScopes.set(scopeKey, scope);
+    }
+    const releaseFor = () => {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            scope.active = false;
+            while (scope.waiting.length) {
+                const waiter = scope.waiting.shift();
+                waiter.signal?.removeEventListener('abort', waiter.onAbort);
+                if (waiter.signal?.aborted) {
+                    waiter.reject(gitAbortError());
+                    continue;
+                }
+                scope.active = true;
+                waiter.resolve(releaseFor());
+                return;
+            }
+            if (heavyDiffScopes.get(scopeKey) === scope)
+                heavyDiffScopes.delete(scopeKey);
+        };
+    };
+    if (!scope.active) {
+        scope.active = true;
+        return Promise.resolve(releaseFor());
+    }
+    return new Promise((resolvePermit, reject) => {
+        const waiter = {
+            signal,
+            resolve: resolvePermit,
+            reject,
+            onAbort: () => {
+                const index = scope.waiting.indexOf(waiter);
+                if (index < 0)
+                    return;
+                scope.waiting.splice(index, 1);
+                signal?.removeEventListener('abort', waiter.onAbort);
+                reject(gitAbortError());
+                if (!scope.active && scope.waiting.length === 0 && heavyDiffScopes.get(scopeKey) === scope)
+                    heavyDiffScopes.delete(scopeKey);
+            },
+        };
+        scope.waiting.push(waiter);
+        signal?.addEventListener('abort', waiter.onAbort, { once: true });
+    });
+}
+// @@@ one bounded batch per planned population, only the paths actually asked about - the tree comparison is pathspec-scoped
+// (`:(literal)` so a path holding a glob char, a space or a leading colon is matched verbatim, `-z` so the
+// answer needs no unquoting), and the answer retained is one boolean per REQUESTED path. Concurrent primes
+// on the same anchor therefore union their paths BEFORE the child starts: a caller records what it needs in
+// `pending`, then either starts the batch that drains pending or joins the running one and re-checks after —
+// so a path requested mid-flight rides the NEXT batch instead of racing this one, and a settled path is
+// never asked again. Every bounded chunk stays serial through the same scope permit.
+const CONTENT_BATCH_RECORD_LIMIT = 8_192;
+const CONTENT_BATCH_ARGV_BYTE_LIMIT = 16 * 1_024;
+const CONTENT_BATCH_MARKER = '\x1espex-content:';
+function contentBatchArgs(root, paths) {
+    return [
+        '-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--stdin', '--always', '-r', '--name-status', '-z',
+        '--no-renames', '--no-color', '--no-ext-diff', '--no-textconv', `--format=${CONTENT_BATCH_MARKER}%H`,
+        '--', ...paths.map((path) => `:(literal)${path}`),
+    ];
+}
+function argvBytes(args) {
+    return args.reduce((total, arg) => total + Buffer.byteLength(arg) + 1, 0);
+}
+function contentBatchChunks(root, rows) {
+    const chunks = [];
+    let byRow = new Map();
+    let paths = new Set();
+    const flush = () => {
+        if (byRow.size)
+            chunks.push([...byRow.values()]);
+        byRow = new Map();
+        paths = new Set();
+    };
+    for (const row of rows) {
+        for (const path of row.requested) {
+            for (;;) {
+                const nextPaths = paths.has(path) ? paths : new Set(paths).add(path);
+                const nextRows = byRow.size + (byRow.has(row) ? 0 : 1);
+                const withinRecords = nextRows * nextPaths.size <= CONTENT_BATCH_RECORD_LIMIT;
+                const withinArgv = argvBytes(contentBatchArgs(root, [...nextPaths])) <= CONTENT_BATCH_ARGV_BYTE_LIMIT;
+                if (withinRecords && withinArgv)
+                    break;
+                if (!byRow.size)
+                    throw new Error(`git content diff path exceeds the ${CONTENT_BATCH_ARGV_BYTE_LIMIT}-byte argv bound: ${path}`);
+                flush();
+            }
+            let slice = byRow.get(row);
+            if (!slice) {
+                slice = { ...row, requested: [] };
+                byRow.set(row, slice);
+            }
+            slice.requested.push(path);
+            paths.add(path);
+        }
+    }
+    flush();
+    return chunks;
+}
+function parseContentBatch(out, rows) {
+    let rowIndex = -1;
+    let status = null;
+    const changed = rows.map(() => new Set());
+    for (const raw of out.split('\0')) {
+        if (!raw)
+            continue;
+        const token = raw.startsWith('\n') ? raw.slice(1) : raw;
+        if (status !== null) {
+            if (rowIndex < 0 || rowIndex >= rows.length)
+                throw new Error('git content diff batch emitted a path before its pair marker');
+            changed[rowIndex].add(token);
+            status = null;
+            continue;
+        }
+        if (token.startsWith(CONTENT_BATCH_MARKER)) {
+            rowIndex++;
+            if (rowIndex >= rows.length)
+                throw new Error('git content diff batch emitted too many pair markers');
+            continue;
+        }
+        if (!/^[A-Z](?:\d+)?$/.test(token))
+            throw new Error(`git content diff batch emitted malformed status '${token}'`);
+        status = token;
+    }
+    if (status !== null)
+        throw new Error(`git content diff batch ended after status '${status}'`);
+    if (rowIndex + 1 !== rows.length)
+        throw new Error(`git content diff batch emitted ${rowIndex + 1} pair markers for ${rows.length} pairs`);
+    return changed;
+}
+async function resolvedContentImages(root, raws, replacements) {
+    const targets = raws.map((raw) => {
+        let target = raw;
+        const seen = new Set();
+        while (replacements.has(target)) {
+            if (seen.has(target))
+                throw new Error(`refs/replace cycle while resolving content image '${raw}'`);
+            seen.add(target);
+            target = replacements.get(target);
+        }
+        return target;
+    });
+    // One no-replace child proves both the names callers supplied and the exact final replacement targets.
+    // A target cannot make a nonexistent raw id look available, and a missing replacement target is loud.
+    const queries = [...new Set([...raws, ...targets])];
+    const answers = await batchRevisionOids(root, queries, { replaceObjects: false });
+    const checked = new Map(queries.map((query, index) => [query, answers[index]]));
+    return raws.map((raw, index) => {
+        if (!checked.get(raw))
+            return null;
+        const target = checked.get(targets[index]);
+        if (!target)
+            throw new Error(`replacement target '${targets[index]}' for content image '${raw}' is unreadable`);
+        return target;
+    });
+}
+async function runContentBatch(root, currentOid, rows) {
+    const settled = [];
+    for (const chunk of contentBatchChunks(root, rows)) {
+        const paths = [...new Set(chunk.flatMap((row) => row.requested))].sort();
+        const result = await gitTry(contentBatchArgs(root, paths), {
+            input: chunk.map((row) => `${row.oid} ${currentOid}`).join('\n') + '\n',
+            // batchRevisionOids already froze replacements/grafts into exact object ids. Do not reinterpret those
+            // ids if refs/replace moves between the resolution child and this content child.
+            extraEnv: { GIT_NO_REPLACE_OBJECTS: '1' },
+        });
+        if (!result.ok)
+            throw new Error(`git content diff batch failed (${result.failure ?? 'unknown'}): ${result.stderr.trim() || 'unknown git error'}`);
+        parseContentBatch(result.stdout, chunk).forEach((changed, index) => settled.push({ row: chunk[index], changed }));
+    }
+    // Publish only after every chunk succeeds. A late transport failure leaves the entire planned population
+    // retryable instead of turning its early chunks into an accidental partial freshness answer.
+    for (const { row, changed } of settled)
+        for (const path of row.requested)
+            row.entry.verdicts.set(path, changed.has(path));
+}
+function startPluralContentBatch(root, rootKey, scope, rows) {
+    const run = async () => {
+        const release = await acquireHeavyDiff(`${rootKey}\x1f${scope.head}`, currentGitBuildAbortSignal());
+        const batch = rows.map((row) => ({ ...row, oid: row.entry.imageOid, requested: [...row.entry.pending] }))
+            .filter((row) => row.requested.length);
+        for (const row of batch)
+            row.entry.pending.clear();
+        try {
+            await runContentBatch(root, scope.currentOid, batch);
+        }
+        finally {
+            release();
+        }
+    };
+    let flight;
+    flight = run().finally(() => {
+        for (const row of rows)
+            if (row.entry.flight === flight)
+                row.entry.flight = null;
+    });
+    for (const row of rows)
+        row.entry.flight = flight;
+    return flight;
+}
+// @@@ the drift COUNT is a reachability question, so ONE walk answers the whole roster - counting it as
+// `rev-list --count <anchor>..<HEAD> -- <path>` names an OFF-HISTORY range, so Git can never cut the walk
+// short: every (anchor, path) pair traverses the entire history, and the pairs multiply. Measured cold on a
+// 437-anchor deployment scope: 1748 of the read's 1750 git children were those counts. What HEAD's index
+// genuinely lacks is only the ANCHORS' own ancestry, and one `rev-list --parents` walk over the whole roster
+// carries it; the count is then the same in-memory rule `eventsSince` applies on the in-history side. The
+// walk is a SEPARATE structure from the shared drift index on purpose: grafting off-history tips into that
+// index would make `ancestorsOf` stop answering undefined for them and silently switch the freshness
+// DECISION from this content probe to ancestry. A rejected walk caches nothing and every joiner sees the
+// same failure, matching the anchor batch above.
+async function primeAnchorTopology(root, scope, oids) {
+    for (;;) {
+        const missing = oids.filter((oid) => !scope.topologyRoster.has(oid));
+        if (!missing.length)
+            return;
+        // an anchor that arrives mid-walk rides the NEXT one instead of racing this one, exactly as a
+        // mid-flight path rides the next content batch.
+        if (scope.topologyFlight) {
+            await scope.topologyFlight;
+            continue;
+        }
+        const roster = [...new Set([...scope.topologyRoster, ...missing])];
+        const run = async () => {
+            const reach = await unionTopology(root, roster);
+            // one child-before-parent pass for the whole roster; the bytes are identical to asking one by one.
+            primeAncestorClosures(reach, roster);
+            scope.topology = reach;
+            scope.topologyRoster = new Set(roster);
+        };
+        let flight;
+        flight = run().finally(() => { if (scope.topologyFlight === flight)
+            scope.topologyFlight = null; });
+        scope.topologyFlight = flight;
+        await flight;
+    }
+}
+export function contentProbeFor(root) {
+    const rootKey = resolve(root);
+    let head;
+    let activeImageKey;
+    const headOf = () => (head ??= headSha(root));
+    const imageOf = () => {
+        const rawHead = headOf();
+        const interpretation = gitObjectInterpretation(root);
+        return { rawHead, key: `${rawHead}\x1f${interpretation.identity}`, interpretation };
+    };
+    const primeMany = async (demands) => {
+        if (!demands.length)
+            return;
+        const planned = new Map();
+        for (const demand of demands) {
+            const row = planned.get(demand.anchorSha) ?? { paths: new Set(), codePaths: new Set(), evalPaths: new Set() };
+            for (const path of demand.paths) {
+                if (path) {
+                    row.paths.add(path);
+                    row.codePaths.add(path);
+                }
+            }
+            if (demand.evalPath) {
+                row.paths.add(demand.evalPath);
+                row.evalPaths.add(demand.evalPath);
+            }
+            planned.set(demand.anchorSha, row);
+        }
+        let scope;
+        for (;;) {
+            const image = imageOf();
+            activeImageKey = image.key;
+            const current = scopeFor(rootKey, image.key, null);
+            for (const [sha, row] of planned) {
+                const entry = touchAnchor(current, sha, undefined);
+                for (const path of row.paths)
+                    if (!entry.verdicts.has(path))
+                        entry.pending.add(path);
+            }
+            const needsResolution = current.currentOid === null || [...planned].some(([sha]) => {
+                const entry = current.anchors.get(sha);
+                return entry.imageOid === undefined || entry.gone;
+            });
+            if (!needsResolution) {
+                scope = current;
+                break;
+            }
+            // Resolve HEAD and every anchor in ONE child, then require the interpretation inputs to remain stable.
+            // The returned object ids become the only images downstream commands may execute against.
+            const shas = [...planned.keys()];
+            const resolved = await resolvedContentImages(root, [image.rawHead, ...shas], image.interpretation.replacements);
+            if (imageOf().key !== image.key)
+                continue;
+            const currentOid = resolved[0];
+            if (!currentOid)
+                throw new Error(`git content diff current image '${image.rawHead}' is unreadable`);
+            scope = scopeFor(rootKey, image.key, currentOid);
+            shas.forEach((sha, index) => touchAnchor(scope, sha, resolved[index + 1]));
+            break;
+        }
+        const grouped = new Map();
+        for (const [sha, row] of planned) {
+            const entry = scope.anchors.get(sha);
+            if (!entry)
+                throw new Error(`git content diff did not resolve planned anchor '${sha}'`);
+            grouped.set(sha, { entry, ...row });
+        }
+        for (;;) {
+            const waiting = new Set();
+            const ready = [];
+            for (const [sha, row] of grouped) {
+                if (row.entry.gone)
+                    continue;
+                const missing = [...row.paths].filter((path) => !row.entry.verdicts.has(path));
+                if (!missing.length)
+                    continue;
+                for (const path of missing)
+                    row.entry.pending.add(path);
+                if (row.entry.flight)
+                    waiting.add(row.entry.flight);
+                else
+                    ready.push({ sha, entry: row.entry });
+            }
+            if (waiting.size) {
+                await Promise.all(waiting);
+                continue;
+            }
+            if (!ready.length)
+                break;
+            await startPluralContentBatch(root, rootKey, scope, ready);
+        }
+        // only anchors whose governed content actually differs need their past: those are the readings that
+        // will render a drift count, and a byte-identical population walks nothing at all.
+        const drifted = [...grouped.values()]
+            .filter((row) => !row.entry.gone && [...row.codePaths].some((path) => row.entry.verdicts.get(path) === true))
+            .map((row) => row.entry.imageOid);
+        if (drifted.length)
+            await primeAnchorTopology(root, scope, drifted);
+        for (const [sha, row] of grouped) {
+            if (row.entry.gone)
+                continue;
+            for (const evalPath of row.evalPaths)
+                if (row.entry.verdicts.get(evalPath) === true) {
+                    scope.blockDemands.add(`${row.entry.imageOid}\x1f${evalPath}`);
+                    scope.blockDemands.add(`${scope.currentOid}\x1f${evalPath}`);
+                }
+        }
+    };
+    return {
+        async prime(sha, paths, evalPath) {
+            await primeMany([{ anchorSha: sha, paths, evalPath }]);
+        },
+        primeMany,
+        async primeBlocks() {
+            const image = imageOf();
+            activeImageKey = image.key;
+            const scope = currentScope(rootKey, image.key);
+            if (!scope?.blockDemands.size)
+                return;
+            const demands = [...scope.blockDemands].map((k) => {
+                const cut = k.indexOf('\x1f');
+                return { rev: k.slice(0, cut), path: k.slice(cut + 1) };
+            });
+            scope.blockDemands.clear();
+            await primeScenarioBlocks(root, demands);
+        },
+        changed(sha, path) {
+            // The async prime owns all I/O. An unprimed path is 'can't testify', never a fresh sync diff: a miss
+            // stays conservative and no abort/transient failure can turn into an unbounded synchronous fallback.
+            const entry = activeImageKey ? currentScope(rootKey, activeImageKey)?.anchors.get(sha) : undefined;
+            if (!entry || entry.gone)
+                return null;
+            return entry.verdicts.get(path) ?? null;
+        },
+        canTestify(sha) {
+            // a settled verdict — of either polarity — is the proof the anchor's tree was readable
+            const entry = activeImageKey ? currentScope(rootKey, activeImageKey)?.anchors.get(sha) : undefined;
+            return !!entry && !entry.gone && entry.verdicts.size > 0;
+        },
+        scenarioDiffers(sha, evalPath, scenario) {
+            const scope = activeImageKey ? currentScope(rootKey, activeImageKey) : undefined;
+            const entry = scope?.anchors.get(sha);
+            const a = entry?.imageOid ? scenarioBlocksAt(root, entry.imageOid, evalPath) : null;
+            if (!a)
+                return true; // eval.md unreadable at the anchor (renamed/absent) → can't prove → stale
+            return a.get(scenario) !== scenarioBlocksAt(root, scope.currentOid, evalPath)?.get(scenario);
+        },
+        inAnchorPast(sha, commit) {
+            const scope = activeImageKey ? currentScope(rootKey, activeImageKey) : undefined;
+            const oid = scope?.anchors.get(sha)?.imageOid;
+            if (!scope?.topology || !oid)
+                return false;
+            const bits = ancestorsOf(scope.topology, oid);
+            return !!bits && inAncestors(scope.topology, bits, commit);
+        },
+    };
+}
+// 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
+// hand the first one's answer to all the others — silently, and in the fresh direction.
+const anchorKey = (sinceSha, path, selectors) => `${sinceSha}\x1f${path}\x1f${[...selectors].sort().join('\x1e')}`;
+// @@@ 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();
+// The memo key doubles as the IMAGE's name — the extractor that answered plus the exact bytes it read — so a
+// caller retaining a verdict derived from these units names it by the same identity that decides the parse
+// ([[selector-anchor-scope]]). Returning the key rather than re-deriving it elsewhere is what keeps the two
+// from drifting apart.
+function currentTreeImage(root, x, path) {
+    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 { key, units: hit.units };
+    }
+    let entry;
+    try {
+        entry = { units: x.extract(source, path) };
+    }
+    catch (err) {
+        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 { key, units: entry.units };
+}
+function entryImage(root, regs, path, selector) {
+    const x = extractorFor(regs, extOf(path));
+    if (!x)
+        return { problem: `\`code\` selector \`${path}#${selector}\` — no designated extractor for that language; drop the #anchor or add a language row` };
+    const ready = x.ready();
+    if (ready !== true)
+        return { problem: `\`code\` anchors on ${path} are unverified: ${ready}` };
+    try {
+        return currentTreeImage(root, x, path);
+    }
+    catch (err) {
+        return { problem: `\`code\` anchors on ${path} are unverified: ${err?.message ?? String(err)}` };
+    }
+}
+// every selector of one entry resolves to exactly one unit in the CURRENT tree, or the entry cannot testify.
+// This gate is what stops a DEAD selector from reading fresh: the hit engine answers "no commit touched a
+// unit of that name", which for a name that exists nowhere is a vacuous no — true of spec drift, where the
+// dead anchor is a separate blocking error, and dangerously false here, where the same silence would retire
+// a reading's whole code axis. `problem` names the repair for lint; null means the entry is verifiable.
+function selectorProblem(units, path, selectors) {
+    // 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, selectors)) {
+        if ('dead' in r)
+            return `\`code\` selector \`${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 \`${path}#${r.selector}\` is ambiguous — ${r.ambiguous} units share that name; pin a unique one`;
+    }
+    return null;
+}
+function entryUnverifiable(root, regs, entry) {
+    const image = entryImage(root, regs, entry.path, entry.selectors[0]);
+    return 'problem' in image ? image.problem : selectorProblem(image.units, entry.path, entry.selectors);
+}
+// @@@ 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 = () => new Promise((resolve) => { setImmediate(resolve); });
+// A verdict's window is `sinceSha..HEAD`, and that window LENGTHENS as HEAD advances — the same
+// (sinceSha, path, selectors) that answers false at one head can legitimately answer true at the next. So
+// these are per-head immutable, never content-addressed-forever, and they belong in the root's current-head
+// scope above rather than in a memo of their own ([[selector-anchor-scope]]).
+// The working tree, however, does NOT stand still at one head: a session re-images the files a selector
+// resolves against, and each image is its own key. Bound that with the same drop-wholesale idiom the
+// current-tree parse memo uses instead of inventing a second eviction policy.
+const ANCHOR_VERDICT_MAX = Math.max(1024, Number(process.env.SPEXCODE_ANCHOR_VERDICT_SLOTS || 8192));
+export function anchorProbeFor(root, idx) {
+    const rootKey = resolve(root);
+    const regs = extractors(root);
+    const verdicts = new Map();
+    // The scope is the one the content probe already owns, entered only when the index's own tip IS the
+    // current head. An index built at another tip cannot borrow this head's answers, and — the reason this is
+    // a guard rather than a rotation — a head that moved mid-read must not make THIS probe displace the
+    // content probe's just-settled scope. Either the two probes agree on the head and share one scope, or this
+    // one keeps nothing and recomputes.
+    const scopeOf = () => {
+        if (!idx.tip)
+            return null;
+        const rawHead = headSha(root);
+        if (idx.tip !== rawHead)
+            return null;
+        return scopeFor(rootKey, `${rawHead}\x1f${gitObjectInterpretation(root).identity}`, null);
+    };
+    // which extractor BUILD answered is part of a verdict's identity too — a host TypeScript resolving to a
+    // different module or version must not inherit the previous one's units.
+    const registry = regs.map((x) => x.memoKey('\0registry')).join('\x1e');
+    return {
+        async prime(demands) {
+            const scope = scopeOf();
+            const keys = [];
+            const scoped = [];
+            const queries = [];
+            const queued = new Set();
+            // one coherent read of each source per sweep: every entry on a path resolves against the same bytes,
+            // and the read that names the verdict is the read the verdict was derived from.
+            const images = new Map();
+            const imageOf = (path, selector) => {
+                let hit = images.get(path);
+                if (hit === undefined) {
+                    hit = entryImage(root, regs, path, selector);
+                    images.set(path, hit);
+                }
+                return hit;
+            };
+            const remember = (name, hit) => {
+                if (scope && name !== null) {
+                    if (scope.anchorVerdicts.size >= ANCHOR_VERDICT_MAX)
+                        scope.anchorVerdicts.clear();
+                    scope.anchorVerdicts.set(name, hit);
+                }
+            };
+            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) || queued.has(key))
+                        continue;
+                    const image = imageOf(e.path, e.selectors[0]);
+                    const name = 'problem' in image ? null : `${registry}\x1f${image.key}\x1f${key}`;
+                    const remembered = scope && name !== null ? scope.anchorVerdicts.get(name) : undefined;
+                    if (remembered !== undefined) {
+                        verdicts.set(key, remembered);
+                        continue;
+                    }
+                    // a miss runs the FULL derivation below, unchanged — it is what a verdict MEANS, not a fallback
+                    if ('problem' in image || selectorProblem(image.units, e.path, e.selectors))
+                        continue; // no verdict → conservative stale (lint says why)
+                    const win = eventsSince(idx, sinceSha, e.path);
+                    if (win === null)
+                        continue;
+                    if (!win.length) {
+                        verdicts.set(key, false);
+                        remember(name, false);
+                        continue;
+                    }
+                    queued.add(key);
+                    keys.push(key);
+                    scoped.push(name);
+                    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); remember(scoped[index], hit); });
+        },
+        hit(sinceSha, path, selectors) {
+            return verdicts.get(anchorKey(sinceSha, path, selectors)) ?? null;
+        },
+    };
+}
+// the LOUD half: a selector is a claim that a named unit EXISTS, held to the same standard as a ghost path.
+// Dead, ambiguous, unparseable, or no designated extractor — each names itself and its repair, and until
+// repaired the probe issues no verdict, so the reading stays stale. Over-warn, never a silent pass.
+export function anchorProblems(root, entries) {
+    const regs = extractors(root);
+    const out = [];
+    for (const e of entries) {
+        if (!e.selectors.length)
+            continue;
+        const problem = entryUnverifiable(root, regs, e);
+        if (problem)
+            out.push(problem);
+    }
+    return out;
+}
+// the teeth (T1): a scenario is remark-stale unless EVERY remark is resolved AND this reading post-dates
+// every resolution. So an UNRESOLVED remark ages it; a RESOLVED remark keeps it stale until a reading taken
+// strictly after the resolve (reading.ts > resolvedAt) exists — you can't out-run a remark by re-measuring
+// before the resolve, nor clear it by passive receipt. A resolved bit with no timestamp stays conservatively
+// stale (defensive: resolveRemark always stamps one).
+export function remarkStale(reading, remarks) {
+    return remarks.some((r) => !r.resolved || !(r.resolvedAt && reading.ts > r.resolvedAt));
+}
+// true iff some commit touched `path` that is NOT an ancestor of `sinceSha` — i.e. it lies in
+// `sinceSha..HEAD` by true DAG reachability, never a log-position/date compare (which under-reports on
+// branchy history). An off-history `sinceSha` falls back to the content probe when one is fed (see
+// 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, sinceSha, path, probe) {
+    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;
+}
+// the code axis's DISPLAY detail: which governed files drifted since a reading, and by HOW MANY commits — so
+// a stale eval can say "EvalsFeed.jsx +3" instead of a bare "code moved". Same DAG reachability as
+// changedSince (a commit touching the file that is NOT an ancestor of the reading's sha lies in sinceSha..HEAD);
+// an off-history sinceSha reports through the same content fallback (only files whose content differs, counted
+// against the anchor's own ancestry); 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, sinceSha, codeAxis, probe) {
+    // 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(undefined, codeAxis).paths;
+    const out = [];
+    for (const f of codeFiles) {
+        const since = eventsSince(idx, sinceSha, f);
+        const events = pathEvents(idx, f);
+        const differs = since ? undefined : probe?.changed(sinceSha, f);
+        const behind = since ? new Set(since.map((event) => event.commit)).size
+            // off-history and the content differs: the SAME rule as the in-history branch above — the path's events
+            // this anchor has not already seen — read against the anchor's own ancestry instead of HEAD's. Floored
+            // at one: the trees demonstrably differ, so 'drifted by 0 commits' would be a lie whatever the walk
+            // could and could not project.
+            : differs === true ? Math.max(1, new Set(events.filter((event) => !probe.inAnchorPast(sinceSha, event.commit)).map((event) => event.commit)).size)
+                : differs === false ? 0
+                    : new Set(events.map((event) => event.commit)).size;
+        if (behind > 0)
+            out.push({ file: f, behind });
+    }
+    return out;
+}
+// @@@scenario axis decides by stored contract hash - a reading filed since #61 carries `scenarioHash`, the
+// content hash of the semantic text it was measured against (scenarios.ts scenarioHash — normalized
+// description+expected). For such a reading the scenario axis is a PURE TEXT COMPARE: recorded hash vs the
+// CURRENT declaration's hash — no git walk, no chain, no ancestry. That is what makes it converge under
+// fleet-parallel filing+merging: a sibling scenario's edit, a sidecar-only commit, a merge's textual shift,
+// a whitespace re-wrap — none of them move THIS scenario's hash, so none can re-stale its reading; only the
+// contract actually changing (or the scenario disappearing from eval.md — `current` undefined) does. A
+// LEGACY reading without the hash is decided by the git-derived per-scenario rule below, unchanged — the
+// one-shot degradation: exactly ONE track decides each reading (hash if present, else git), never both
+// OR-ed together.
+function scenarioStaleByHash(reading, current) {
+    if (reading.scenarioHash === undefined)
+        return undefined; // legacy → the git rule decides
+    return current ? scenarioHash(current) !== reading.scenarioHash : true;
+}
+// LEGACY scenario freshness (readings filed before the stored contract hash) — PER-SCENARIO and SEMANTIC,
+// not per-file: a reading stales only when ITS OWN scenario's semantic block (description+expected —
+// [[scenariofresh]]'s blockContent projection) moved in scenarioSha..HEAD — never when a sibling in the
+// same eval.md did, and never on a metadata-only edit (tags/test/code/related). Reads like the code axis's
+// changedSince — the per-scenario change-commits ([[scenariofresh]], rename-followed so a bare git-mv
+// reparent isn't a change) tested for ancestry — and an off-history codeSha takes the same content fallback
+// at the same granularity and the same projection. Known limit (#61, why the hash replaced it for new
+// readings): the change-commit chain is built off a LINEARIZED log walk, so parallel branches editing one
+// eval.md cross-attribute each other's edits and can false-stale a sibling's reading across a merge.
+function scenarioMoved(scIdx, didx, sinceSha, evalPath, scenario, probe) {
+    const anc = ancestorsOf(didx, sinceSha);
+    if (anc)
+        return scenarioChangeCommits(scIdx, evalPath, scenario).some((h) => !inAncestors(didx, anc, h));
+    const differs = probe?.changed(sinceSha, evalPath);
+    if (differs == null)
+        return true;
+    if (!differs)
+        return false; // whole file byte-identical → this block too
+    return probe.scenarioDiffers(sinceSha, evalPath, scenario);
+}
+// one declared entry's contribution to the code axis. The FILE question runs first and is unchanged; only an
+// ANCHORED entry whose file really moved asks the narrower spatial one, so an anchor can subtract from the
+// file verdict but never add to it. No verdict (unprimed, off-history, unverifiable selector) → conservative.
+function entryMoved(idx, sinceSha, entry, probe, anchors) {
+    if (!changedSince(idx, sinceSha, entry.path, probe))
+        return false;
+    if (!entry.selectors.length)
+        return true;
+    return anchors?.hit(sinceSha, entry.path, entry.selectors) ?? true;
+}
+export function staleAxes(reading, codeAxis, evalPath, didx, scIdx, remarks = [], probe, current, // the scenario's CURRENT declaration (undefined = gone from eval.md) — the hash compare's other side
+anchors) {
+    const axes = [];
+    const byHash = scenarioStaleByHash(reading, current);
+    if (probe && !commitReachable(didx, reading.codeSha) && !probe.canTestify(reading.codeSha)) {
+        // the anchor commit object is GONE — neither git axis can testify; say that, not "content changed".
+        // The stored contract hash needs no anchor, so it still decides the scenario axis when present.
+        axes.push('anchor');
+        if (byHash)
+            axes.push('scenario');
+    }
+    else {
+        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');
+    return axes;
+}
+export function isStale(reading, codeAxis, evalPath, didx, scIdx, remarks = [], probe, current, anchors) {
+    return staleAxes(reading, codeAxis, evalPath, didx, scIdx, remarks, probe, current, anchors).length > 0;
+}