@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/_lib/standing_bound_ratchet.ts

@@ -0,0 +1,220 @@
+/**
+ * The standing-payload bounds are shrink-only, checked against the base ref.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `src/config/preamble-payload-budget.json` says of its grace ceiling: *"It may
+ * never move UP."* `grace_ceiling_history` in the same file records it moving up
+ * twice — 138,212 → 138,273 on 2026-09-02 and 138,273 → 138,490 on 2026-09-08 —
+ * each with a careful prose justification. ADR-264 resolved that contradiction
+ * against the practice: the sentence stands, the two raises are violations caused
+ * by contradictory wording, and standing-rule growth needs a compensating
+ * reduction elsewhere.
+ *
+ * That decision then had no enforcement. A sentence in a JSON string is not a
+ * gate, and the file's own history is the evidence: nothing objected either time.
+ * This module is the enforcement — and it is the ONLY thing
+ * `road-to-a-standing-budget-with-headroom` step 1.3 ships, because the 128-token
+ * Iron Law reserve that step designed was refused by an AI council 2/2 on
+ * 2026-09-08. See ADR-265.
+ *
+ * WHAT IT CANNOT DO, STATED PLAINLY
+ * ---------------------------------
+ * The change under review can edit this file. Both council seats named that as
+ * the defect fatal to the reserve — "the checker, its imports, token census,
+ * workflow, and status context are all part of the trusted computing base", so a
+ * protected record read by an unprotected verifier grants nothing. It is fatal to
+ * a mechanism that GRANTS budget and it is not fatal to one that only REFUSES,
+ * which is the whole reason the reserve stayed unshipped and this ratchet did
+ * not: disabling this check requires visibly editing it, and every gate in this
+ * repository already rests on that same review. A ratchet whose only failure mode
+ * is "someone deleted the ratchet" is strictly better than the sentence it
+ * replaces, which had no failure mode because it did nothing.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Repo-relative path of the budget config the bound lives in. */
+export const BUDGET_CONFIG_PATH = 'src/config/preamble-payload-budget.json';
+
+/** Injection seam: run git, capture output, never throw on a non-zero exit. */
+export type GitRunner = (args: readonly string[], cwd: string) => {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+
+export const realGit: GitRunner = (args, cwd) => {
+    const r = spawnSync('git', [...args], { cwd, encoding: 'utf-8' });
+    return { ok: r.status === 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+
+export interface BoundsRatchetVerdict {
+    ok: boolean;
+    violations: string[];
+    /** The bound read at the base ref, or `null` when it could not be read. */
+    baseGraceCeiling: number | null;
+    /** The ref compared against, or `null` when none resolved. */
+    baseRef: string | null;
+    /** Why the comparison was skipped, when it was. Printed, never silent. */
+    note: string | null;
+    /**
+     * `false` means the bound could not be READ, not that it rose.
+     *
+     * Two refusals reach a caller with `ok: false` and they need opposite
+     * actions: a risen ceiling is fixed by lowering the addition, an
+     * unverifiable one by repairing the checkout. A completion review caught
+     * both being rendered as "ROSE", which would send an operator to shrink a
+     * rule over what was a fetch problem. Absent means verified — the only
+     * `ok: false` that predates this field is a genuine rise.
+     */
+    verified: boolean;
+}
+
+function showAtRef(git: GitRunner, repoRoot: string, ref: string, relPath: string): string | null {
+    const r = git(['show', `${ref}:${relPath}`], repoRoot);
+    return r.ok ? r.stdout : null;
+}
+
+/**
+ * A condition that stops the comparison: skip when advisory, refuse when not.
+ *
+ * One helper for all four causes rather than four inline branches, so the
+ * posture cannot drift between them — the failure this closes was four
+ * independent `ok: true` returns that all had to be found before any of them
+ * could be trusted.
+ */
+function unverified(
+    reason: string,
+    requireBase: boolean,
+    baseGraceCeiling: number | null,
+    baseRef: string | null,
+): BoundsRatchetVerdict {
+    if (requireBase) {
+        return {
+            ok: false,
+            verified: false,
+            baseGraceCeiling,
+            baseRef,
+            note: `${reason}, so the shrink-only bound was NOT verified in this run`,
+            violations: [
+                `the shrink-only bound could not be verified: ${reason}. This run is `
+                    + 'ENFORCING, so an unverifiable bound refuses rather than skips — an '
+                    + 'unreadable base would otherwise grant budget on an infrastructure '
+                    + 'failure. This is NOT a ceiling rise: fix the checkout (a full fetch '
+                    + 'of the base ref) rather than lowering the addition.',
+            ],
+        };
+    }
+    return {
+        ok: true,
+        verified: false,
+        violations: [],
+        baseGraceCeiling,
+        baseRef,
+        note: `${reason}, so the shrink-only bound was NOT verified in this run`,
+    };
+}
+
+/**
+ * Compare the grace ceiling in this tree against the one at the base ref.
+ *
+ * TWO POSTURES, AND WHICH ONE APPLIES IS THE CALLER'S TO DECLARE.
+ *
+ * Advisory (the default, and what every caller got before `requireBase`): a
+ * base ref or base config that cannot be read SKIPS, reported in both the human
+ * and JSON output so it cannot pass for a check. That default is not laziness
+ * and the original reasoning still holds — a shallow clone, a first commit and
+ * a detached build all legitimately have no base, and a gate that reds on them
+ * gets switched off, which is how a repository loses the enforcement it just
+ * built.
+ *
+ * Enforcing (`requireBase: true`): the same conditions REFUSE. An AI council
+ * (2/2, 2026-09-10) made this blocking for the move to a base-measured ceiling,
+ * and the reason is that the asymmetry above inverts once the base ref stops
+ * being a cross-check and becomes the ceiling itself. Today an unreadable base
+ * costs a comparison; there it would grant an unbounded budget on an
+ * infrastructure failure — the exact fail-open the reserve decision refused.
+ * anthropic's wording was "replaced or mode-gated"; this is the mode gate, so
+ * that no existing caller silently changes behaviour.
+ *
+ * The flag is the caller's rather than derived from `GITHUB_ACTIONS` here: this
+ * module cannot tell an enforcing CI run from a diagnostic one on the same
+ * runner, and a gate that guesses its own strictness from an environment
+ * variable is one `env` change away from being advisory everywhere.
+ */
+export function assertBoundsDidNotRise(opts: {
+    repoRoot: string;
+    baseRef: string | null;
+    git?: GitRunner;
+    /**
+     * Refuse instead of skipping when the base cannot be read.
+     *
+     * Absent is advisory, which keeps every pre-existing caller on the
+     * behaviour it was written against. The CI path sets it.
+     */
+    requireBase?: boolean;
+    /**
+     * The ceiling this run actually compares the payload against.
+     *
+     * The CI step passes `--ceiling <grace_ceiling>`, so the effective bound can
+     * be raised either by editing the config or by passing a bigger number. Both
+     * arrive here as one value, which closes the second path without a second
+     * check.
+     */
+    headGraceCeiling: number;
+}): BoundsRatchetVerdict {
+    const git = opts.git ?? realGit;
+    const requireBase = opts.requireBase === true;
+    if (opts.baseRef === null || opts.baseRef.trim() === '') {
+        return unverified('no base ref resolved', requireBase, null, null);
+    }
+    const cfg = showAtRef(git, opts.repoRoot, opts.baseRef, BUDGET_CONFIG_PATH);
+    if (cfg === null) {
+        return unverified(
+            `${BUDGET_CONFIG_PATH} could not be read at ${opts.baseRef}`,
+            requireBase,
+            null,
+            opts.baseRef,
+        );
+    }
+    let baseGrace: number | null = null;
+    try {
+        const parsed = JSON.parse(cfg) as Record<string, unknown>;
+        const delivery = (parsed['ci_delivery'] ?? {}) as Record<string, unknown>;
+        const n = Number(delivery['grace_ceiling']);
+        baseGrace = Number.isFinite(n) ? n : null;
+    } catch {
+        return unverified(
+            `${BUDGET_CONFIG_PATH} at ${opts.baseRef} is not parseable`,
+            requireBase,
+            null,
+            opts.baseRef,
+        );
+    }
+    if (baseGrace === null) {
+        return unverified(
+            `there is no ci_delivery.grace_ceiling at ${opts.baseRef} to ratchet against`,
+            requireBase,
+            null,
+            opts.baseRef,
+        );
+    }
+    if (opts.headGraceCeiling > baseGrace) {
+        return {
+            ok: false,
+            verified: true,
+            baseGraceCeiling: baseGrace,
+            baseRef: opts.baseRef,
+            note: null,
+            violations: [
+                `the standing-payload grace ceiling rose from ${String(baseGrace)} to ` +
+                    `${String(opts.headGraceCeiling)} against ${opts.baseRef}. ` +
+                    `${BUDGET_CONFIG_PATH} says it may not move upward and ADR-264 decided that ` +
+                    'the sentence stands: standing-rule growth needs a compensating reduction ' +
+                    'elsewhere, not a bigger ceiling. Lower the addition, migrate the prose out of ' +
+                    'the standing rule, or reduce another standing asset by the same amount.',
+            ],
+        };
+    }
+    return { ok: true, verified: true, violations: [], baseGraceCeiling: baseGrace, baseRef: opts.baseRef, note: null };
+}

package/src/scripts/_lib/tolerance_shadow.ts

@@ -0,0 +1,177 @@
+/**
+ * Shadow records for the value-reconciliation tolerance — the window whose
+ * distribution a threshold may later be read off.
+ *
+ * NO NEW CONCERN. `check_estate_count` reports zero growth allowance on hook
+ * concerns, and the roadmap step says so in as many words: extend the existing
+ * shadow gate. These records therefore ride `source_first_gate_hook.ts`'s
+ * `SHADOW_LOG` — the same JSONL file, the same gitignored local-only path — and
+ * are told apart by their own `record` discriminator. Nothing new is registered,
+ * nothing new fires, and the concern count is unmoved.
+ *
+ * NO SELF-REPORTED VERDICT, which is the property the step's verify clause
+ * names and the one most easily lost. A record says what the distance WAS and
+ * what each candidate threshold WOULD have done with it. It never says whether
+ * that was right. A field like `was_correct` would be the mechanism grading its
+ * own homework, and a distribution of self-assessments measures the assessor —
+ * the same reason `source_first_gate_hook` records `would_warn` per candidate
+ * instead of one `warn`.
+ *
+ * COUNTERFACTUAL, NOT CHOSEN. `CANDIDATE_COLOR_THRESHOLDS` and
+ * `CANDIDATE_LENGTH_THRESHOLDS` are evaluation points, not defaults: every
+ * record carries the outcome at each, so the window yields a curve rather than
+ * a yes/no. That is the council's own instruction — evaluate several candidate
+ * thresholds counterfactually, never select one as behaviour — and it is why a
+ * spread exists at all. `SHIPPED_TOLERANCE` stays `null` on both axes
+ * throughout the window.
+ *
+ * PRIVACY BY CONSTRUCTION. The record type carries a kind, a metric, numbers,
+ * a token NAME, and booleans. It has no field able to hold a file path, a
+ * prompt, a selector, or any document content — the same stance
+ * `source_first_gate_hook.ts` states for its own record. A token name is a
+ * project's own vocabulary and is the one string here; it is what makes a
+ * distribution readable per token rather than only in aggregate.
+ */
+import { appendShadowLine } from '../hooks/source_first_gate_hook.js';
+
+import type {
+    COLOR_DISTANCE_METRIC,
+    LENGTH_DISTANCE_METRIC,
+    ValueKind,
+    ValueRow,
+} from './design_tolerance.js';
+
+/**
+ * Colour ΔEOK evaluation points. Spread deliberately across two orders of
+ * magnitude: the window has to show where the curve bends, and a spread
+ * clustered around a guess would only confirm the guess.
+ */
+export const CANDIDATE_COLOR_THRESHOLDS: readonly number[] = [0.001, 0.005, 0.01, 0.02, 0.05];
+
+/**
+ * Length evaluation points, in CSS pixels. `1` is here because it is the one
+ * externally observed candidate in the evidence set (Primer's spacing plugin),
+ * and it is one point on a curve rather than a preferred value.
+ */
+export const CANDIDATE_LENGTH_THRESHOLDS: readonly number[] = [0.5, 1, 2, 4];
+
+/** Discriminator on the shared shadow log. */
+export const TOLERANCE_SHADOW_RECORD = 'tolerance_shadow' as const;
+
+export interface CounterfactualOutcome {
+    threshold: number;
+    /** Would this value have been reconciled onto the token at that threshold? */
+    would_reconcile: boolean;
+}
+
+export interface ToleranceShadowRecord {
+    record: typeof TOLERANCE_SHADOW_RECORD;
+    kind: ValueKind;
+    metric: typeof COLOR_DISTANCE_METRIC | typeof LENGTH_DISTANCE_METRIC;
+    /** Distance to the nearest project token, in `metric`. */
+    distance: number;
+    /** The token's own name. No value, no path, no content. */
+    nearest_token: string;
+    /** What the mechanism actually did — `false` throughout the shadow window. */
+    acted: boolean;
+    counterfactual: CounterfactualOutcome[];
+}
+
+export function candidatesFor(kind: ValueKind): readonly number[] {
+    return kind === 'color' ? CANDIDATE_COLOR_THRESHOLDS : CANDIDATE_LENGTH_THRESHOLDS;
+}
+
+/**
+ * Build a record from a reconciled value row, or `null` when the row carries
+ * nothing to measure.
+ *
+ * A row with no candidate token is deliberately NOT recorded as a distance of
+ * zero or of infinity: it is the absence of a measurement, and a window that
+ * silently folded those in would report a distribution over a population that
+ * includes non-observations.
+ */
+export function toleranceShadowRecord(
+    kind: ValueKind,
+    row: ValueRow,
+): ToleranceShadowRecord | null {
+    if (row.nearest === null || row.distance === null || row.metric === null) return null;
+    const distance = row.distance;
+    return {
+        record: TOLERANCE_SHADOW_RECORD,
+        kind,
+        metric: row.metric,
+        distance,
+        nearest_token: row.nearest.name,
+        acted: row.outcome === 'reconciled',
+        counterfactual: candidatesFor(kind).map((threshold) => ({
+            threshold,
+            would_reconcile: distance <= threshold,
+        })),
+    };
+}
+
+/**
+ * Append the records for one reconciliation pass to the shared shadow log.
+ *
+ * THE WINDOW IS ONLY OPEN IF SOMETHING WRITES TO IT. A blind review of the
+ * branch that shipped this module found the header above claiming records ride
+ * `SHADOW_LOG` while the module had no writer and no caller — so
+ * `FLIP_CRITERION`'s reverse trigger ("fewer than 20 records in 8 weeks")
+ * was satisfied by construction, which is a criterion that measures nothing.
+ * The writer is `appendShadowLine`, reused rather than reimplemented: it is
+ * already replay-aware and already fail-open, and a second writer to one log is
+ * two chances to disagree about the format.
+ *
+ * Returns the number of records written — rows with nothing to measure are
+ * skipped, so this is not `rows.length`.
+ */
+export function recordToleranceShadow(
+    root: string,
+    rows: ReadonlyArray<{ kind: ValueKind; row: ValueRow }>,
+): number {
+    let written = 0;
+    for (const { kind, row } of rows) {
+        const record = toleranceShadowRecord(kind, row);
+        if (record === null) continue;
+        appendShadowLine(root, record as unknown as Record<string, unknown>);
+        written += 1;
+    }
+    return written;
+}
+
+/**
+ * Pre-registered flip criterion, written BEFORE the window opens — which is the
+ * third clause of the step's verify and the one a later reader cannot
+ * reconstruct. Prose rather than code on purpose: nothing evaluates it
+ * automatically, and a function that returned `true` here would be the
+ * mechanism authorising its own promotion.
+ */
+export const FLIP_CRITERION = `
+Shadow -> a shipped tolerance, when ALL of:
+
+  a. >= 200 tolerance_shadow records, or >= 4 weeks of window, whichever comes
+     first, with at least 50 records on EACH axis. Colour and length are
+     separate distributions and a threshold read off a pooled one is read off
+     the wrong population.
+  b. The chosen candidate's counterfactual FALSE-RECONCILIATION share -- rows a
+     human reviewer marks as "should have been preserved" that the candidate
+     would have reconciled -- is at or below 1 %, estimated per axis. The
+     reviewer labels are collected OUTSIDE this record type on purpose: a
+     record that carried its own correctness label would be the self-report
+     this module refuses.
+  c. The MISSED-reconciliation share is reported alongside it and is not
+     optimised away. A threshold of zero trivially satisfies (b) and is useless;
+     both error directions are stated or the criterion is not met.
+  d. The distribution is not obviously bimodal. A bimodal curve means the
+     tolerance model itself is wrong -- two populations are being measured as
+     one -- and the response is to re-cut the model, never to pick a threshold
+     between the modes.
+
+Reverse trigger: fewer than 20 records in 8 weeks -> evaluate removing the
+mechanism. A reconciliation nobody exercises is prose with a config key.
+
+Never lifted by this criterion: enabling the mechanism BY DEFAULT is a
+consumer-facing default flip and stays owner-reserved, recorded in
+agents/roadmaps/stubs/road-to-frontend-power-default-flip.md. Meeting a to d
+authorises a shipped tolerance VALUE, not a shipped default.
+`.trim();

package/src/scripts/_lib/vendored_grammar_upstream.ts

@@ -0,0 +1,280 @@
+/**
+ * The vendored grammars' one anchor outside the manifest.
+ *
+ * WHAT THIS ANSWERS.
+ *
+ * `packed_binary_predicate.ts` verifies eleven conditions over
+ * `src/config/packed-binary-manifest.json`, and every one of them is
+ * manifest-internal: the manifest states a sha256 and the bytes are hashed
+ * against it, so a single commit that edits both passes all eleven. The
+ * `release/14.22.0` self-review finding `d1696732ac28` names exactly that gap.
+ * This module closes it by comparing the vendored bytes against a source the
+ * repository does not author: the `tree-sitter-wasms` release pinned in
+ * `package-lock.json` and installed by `npm ci`.
+ *
+ * WHAT IT MAY CLAIM, AND WHAT IT MAY NOT.
+ *
+ * It MAY claim: the vendored bytes equal the bytes of the locked upstream
+ * package, independent of the binary manifest's own self-description.
+ *
+ * It MUST NOT claim to be independent of all repository state, and it MUST NOT
+ * claim to verify the grammars cryptographically against the registry
+ * independent of local build state. It does neither. The chain is
+ * registry tarball -> `npm ci` checks its sha512 against the lock's
+ * `integrity` -> extracted bytes -> vendored bytes, and only the last link is
+ * checked here. An attacker who edits `node_modules` after install defeats
+ * this, and a lock entry that points at a hostile package defeats it earlier
+ * still — that link is review's job, not a check's, because the lock is
+ * human-readable text and the manifest is machine-only JSON.
+ *
+ * Both scoping sentences are the AI council's wording (2026-09-09, 2 seats,
+ * unanimous on this question), kept verbatim so a later reader can tell the
+ * boundary from an oversight.
+ *
+ * WHY IT REFUSES RATHER THAN SKIPS.
+ *
+ * An upstream comparison is trivially written so that it passes when the
+ * upstream is absent, which is a green that verifies nothing — the exact shape
+ * of the eleven conditions it is here to supplement. So an absent package, a
+ * version that is not the locked one, an absent counterpart file, an empty
+ * claim set, and two admitted entries sharing a filename are all refusals,
+ * never passes.
+ *
+ * The last of those is the subtlest, and it was added on an R2 review finding
+ * rather than foreseen: the upstream keeps its grammars in one flat directory,
+ * so the counterpart is addressed by basename. Two manifest rows with the same
+ * filename in different directories would anchor to the same upstream file —
+ * one admitted binary silently unanchored while the verdict reported full
+ * coverage, which is the false green this module exists to remove. The vendored
+ * side resolves the entry's OWN repo-relative path, never a basename under a
+ * fixed directory, for the same reason.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { loadManifest, VERIFIABLE_KIND, type PackedBinaryManifest } from './packed_binary_predicate.js';
+
+/**
+ * The upstream this repository copies from. Hardcoded rather than derived: the
+ * vendored set exists precisely because the package is NOT a runtime
+ * dependency, so there is no dependency edge to read it off, and
+ * `src/vendor/grammars/README.md` names the same string as the refresh source.
+ */
+export const UPSTREAM_PACKAGE = 'tree-sitter-wasms';
+
+/** Where the upstream keeps its compiled grammars inside its own package. */
+const UPSTREAM_GRAMMAR_SUBDIR = 'out';
+
+/** A refusal — the anchor could not be established, so no verdict is honest. */
+export class UpstreamAnchorRefusal extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'UpstreamAnchorRefusal';
+    }
+}
+
+/** One vendored file compared against its upstream counterpart. */
+export interface GrammarComparison {
+    readonly vendoredPath: string;
+    readonly upstreamPath: string;
+    readonly vendoredSha256: string;
+    readonly upstreamSha256: string;
+    readonly equal: boolean;
+}
+
+export interface UpstreamAnchorVerdict {
+    readonly lockedVersion: string;
+    readonly lockedIntegrity: string;
+    readonly installedVersion: string;
+    readonly comparisons: readonly GrammarComparison[];
+    /** Human-readable divergence lines. Empty iff every comparison is equal. */
+    readonly divergences: readonly string[];
+}
+
+export interface UpstreamAnchorOptions {
+    readonly repoRoot: string;
+    /** Defaults to `<repoRoot>/node_modules/<UPSTREAM_PACKAGE>`. Fixture seam. */
+    readonly upstreamPackageDir?: string;
+    /**
+     * Root the manifest's repo-relative `path` values resolve against.
+     * Defaults to `repoRoot`. Fixture seam — NOT a grammar directory: resolving
+     * by directory would discard the entry's own path, and two rows sharing a
+     * basename in different directories would then anchor to the same file.
+     */
+    readonly vendoredRoot?: string;
+    /** Defaults to the manifest at `<repoRoot>/src/config/…`. Fixture seam. */
+    readonly manifest?: PackedBinaryManifest;
+}
+
+export interface LockPin {
+    readonly version: string;
+    readonly integrity: string;
+}
+
+/**
+ * The locked pin for the upstream, read from `package-lock.json`.
+ *
+ * `integrity` is not used to verify anything here — it is carried into the
+ * verdict so the caller can print the anchor it is trusting, and its absence
+ * is a refusal because a lock row without one pins a version and not bytes.
+ */
+export function readLockPin(repoRoot: string): LockPin {
+    const lockPath = path.join(repoRoot, 'package-lock.json');
+    if (!fs.existsSync(lockPath)) {
+        throw new UpstreamAnchorRefusal(`no package-lock.json at ${lockPath} — there is no locked upstream to anchor to`);
+    }
+    const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as {
+        packages?: Record<string, { version?: string; integrity?: string }>;
+    };
+    const key = `node_modules/${UPSTREAM_PACKAGE}`;
+    const row = lock.packages?.[key];
+    if (row === undefined) {
+        throw new UpstreamAnchorRefusal(`package-lock.json carries no \`${key}\` row — the vendored grammars have no locked source`);
+    }
+    if (typeof row.version !== 'string' || row.version.length === 0) {
+        throw new UpstreamAnchorRefusal(`\`${key}\` in package-lock.json carries no version`);
+    }
+    if (typeof row.integrity !== 'string' || row.integrity.length === 0) {
+        throw new UpstreamAnchorRefusal(
+            `\`${key}\` in package-lock.json carries no \`integrity\` — the row pins a version but not bytes, so \`npm ci\` verifies nothing for it`,
+        );
+    }
+    return { version: row.version, integrity: row.integrity };
+}
+
+/**
+ * The manifest, read through the predicate's own reader.
+ *
+ * A second reader would drift: a shape condition added there — a
+ * `schema_version` check, a kind allowlist — would leave this module accepting
+ * a manifest the predicate rejects, and this module's whole value is that it
+ * covers what the manifest admits. So `loadManifest` is the reader and this
+ * wrapper only re-types its failures as refusals, because an unreadable
+ * manifest means the anchor was not established rather than that it failed.
+ * R2 finding 2, 2026-09-09 — the duplicate reader this replaces was one
+ * identifier away from the import already at the top of this file.
+ */
+function readManifest(repoRoot: string): PackedBinaryManifest {
+    try {
+        return loadManifest(repoRoot);
+    } catch (err) {
+        throw new UpstreamAnchorRefusal(
+            `the packed-binary manifest could not be read, so nothing was compared: ${err instanceof Error ? err.message : String(err)}`,
+        );
+    }
+}
+
+function sha256(file: string): string {
+    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+/**
+ * Compare every vendored grammar the manifest admits against the locked
+ * upstream's copy of the same filename.
+ *
+ * Throws `UpstreamAnchorRefusal` when the anchor cannot be established at all;
+ * returns a verdict whose `divergences` is non-empty when it can be established
+ * and the bytes differ. The two are deliberately different outcomes: a refusal
+ * says "this was not checked", a divergence says "this was checked and is
+ * wrong", and collapsing them is how a check becomes a permanent green.
+ */
+export function verifyVendoredGrammarsAgainstUpstream(options: UpstreamAnchorOptions): UpstreamAnchorVerdict {
+    const { repoRoot } = options;
+    const upstreamDir = options.upstreamPackageDir ?? path.join(repoRoot, 'node_modules', UPSTREAM_PACKAGE);
+    const vendoredRoot = options.vendoredRoot ?? repoRoot;
+    const manifest = options.manifest ?? readManifest(repoRoot);
+
+    const pin = readLockPin(repoRoot);
+
+    const claims = manifest.entries.filter((e) => e.kind === VERIFIABLE_KIND);
+    if (claims.length === 0) {
+        throw new UpstreamAnchorRefusal(
+            `the manifest admits no \`${VERIFIABLE_KIND}\` entry — nothing was compared, and reporting that as a pass would be a green over an empty corpus`,
+        );
+    }
+
+    // The upstream keeps its grammars in one flat directory, so the counterpart
+    // is addressed by basename. Two admitted entries sharing a basename would
+    // therefore point at the same upstream file, which is an ambiguous anchor
+    // rather than a comparison — refuse instead of picking one.
+    const byBase = new Map<string, string[]>();
+    for (const e of claims) {
+        const base = path.basename(e.path);
+        byBase.set(base, [...(byBase.get(base) ?? []), e.path]);
+    }
+    const ambiguous = [...byBase.entries()].filter(([, paths]) => paths.length > 1);
+    if (ambiguous.length > 0) {
+        throw new UpstreamAnchorRefusal(
+            `two or more admitted entries share a filename, so they would anchor to the same upstream file: ${ambiguous
+                .map(([base, paths]) => `${base} <- ${paths.join(', ')}`)
+                .join('; ')}`,
+        );
+    }
+
+    const upstreamPkgJson = path.join(upstreamDir, 'package.json');
+    if (!fs.existsSync(upstreamPkgJson)) {
+        throw new UpstreamAnchorRefusal(
+            `${UPSTREAM_PACKAGE} is not installed at ${upstreamDir} — run \`npm ci\`. The vendored bytes were NOT verified; an absent upstream is a refusal, never a pass`,
+        );
+    }
+    const installed = JSON.parse(fs.readFileSync(upstreamPkgJson, 'utf-8')) as { version?: string };
+    if (installed.version !== pin.version) {
+        throw new UpstreamAnchorRefusal(
+            `installed ${UPSTREAM_PACKAGE} is ${String(installed.version)} but package-lock.json pins ${pin.version} — comparing against an unlocked tree would anchor to nothing`,
+        );
+    }
+
+    const comparisons: GrammarComparison[] = [];
+    const divergences: string[] = [];
+
+    for (const entry of claims) {
+        const vendoredPath = path.join(vendoredRoot, entry.path);
+        const upstreamPath = path.join(upstreamDir, UPSTREAM_GRAMMAR_SUBDIR, path.basename(entry.path));
+        if (!fs.existsSync(vendoredPath)) {
+            throw new UpstreamAnchorRefusal(`the manifest admits ${entry.path} but ${vendoredPath} does not exist`);
+        }
+        if (!fs.existsSync(upstreamPath)) {
+            throw new UpstreamAnchorRefusal(
+                `${entry.path} has no counterpart at ${upstreamPath} — the locked upstream does not carry this grammar, so this file has no anchor`,
+            );
+        }
+        const vendoredSha256 = sha256(vendoredPath);
+        const upstreamSha256 = sha256(upstreamPath);
+        const equal = vendoredSha256 === upstreamSha256;
+        comparisons.push({ vendoredPath, upstreamPath, vendoredSha256, upstreamSha256, equal });
+        if (!equal) {
+            divergences.push(
+                `${entry.path}: vendored sha256 ${vendoredSha256} != upstream ${upstreamSha256} (${UPSTREAM_PACKAGE}@${pin.version})`,
+            );
+        }
+    }
+
+    return buildVerdict({ pin, installedVersion: installed.version, comparisons, divergences });
+}
+
+/**
+ * Assemble the verdict from the two version sources, kept separate.
+ *
+ * Extracted so the sourcing is testable at all. On any tree the check accepts,
+ * `pin.version` and the installed version are equal — the strict guard above
+ * refuses otherwise — so a test driving the whole function can never tell which
+ * of the two the `installedVersion` field came from, and the round-1 regression
+ * test for exactly that defect passed with the defect restored. R2 finding 1,
+ * 2026-09-09. Here the two can be given different values, which is the only
+ * place the distinction is observable.
+ */
+export function buildVerdict(args: {
+    readonly pin: LockPin;
+    readonly installedVersion: string;
+    readonly comparisons: readonly GrammarComparison[];
+    readonly divergences: readonly string[];
+}): UpstreamAnchorVerdict {
+    return {
+        lockedVersion: args.pin.version,
+        lockedIntegrity: args.pin.integrity,
+        installedVersion: args.installedVersion,
+        comparisons: args.comparisons,
+        divergences: args.divergences,
+    };
+}