@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/hooks/evidence_independence.ts

@@ -43,6 +43,7 @@
  *
  * Exit codes: 0 allow · 2 block (stderr carries the reason).
  */
+import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -50,8 +51,9 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { atomic_write_json } from "./state_io.js";
 import { readHookStdin } from "./hook_stdin.js";
+import { isCodePath, isTestPath } from "../_lib/test_delta.js";
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
 // 0 allow / 1 block / 2 warn — NOT the 2-means-block shape a PreToolUse guard
 // reads naturally from Claude's own native contract. This constant was 2 when
@@ -59,7 +61,6 @@ const EXIT_ALLOW = 0;
 // and the gate emitted advisory context while the operation went through.
 // Pinned against the dispatcher's export by
 // tests/hooks/concern_block_exit_parity.test.ts.
-const EXIT_BLOCK = 1;
 
 export const STATE_FILE = path.join("agents", "state", "evidence-dispatch.json");
 
@@ -324,6 +325,79 @@ export function decide(
   };
 }
 
+/**
+ * The one-commit test-authorship flag —
+ * `road-to-adversarial-verification-and-long-runs` 2.4, third clause.
+ *
+ * A commit staging BOTH a test and code it could cover is the shape of L0 on the
+ * independence scale — the implementer wrote the evaluator — and it is the one
+ * case nobody sees, because the diff looks exactly like a well-tested change.
+ *
+ * **It reads the STAGED SET and the command, and nothing else.** It does NOT
+ * read a session id, an author or a timestamp, so it cannot distinguish an
+ * implementer who wrote both from one committing a test another session authored
+ * — an independent review of this function caught an earlier docstring here
+ * claiming a session boundary the code never reads, which is exactly the
+ * over-claim `evaluator-independence` exists over. The honest reading is: this
+ * is the shape L0 takes in a diff, surfaced so the level is stated rather than
+ * inferred.
+ *
+ * **WARN, never block.** L0 is explicitly permitted as a fallback, so refusing it
+ * would forbid a legal state; and a signal this coarse may surface, never refuse.
+ *
+ * Returns `null` when nothing is worth saying — i.e. this is not a commit.
+ */
+export function sameSessionTestFlag(command: string | null): string | null {
+  if (command === null || !/\bgit\b[^|;&]*\bcommit\b/.test(command)) return null;
+  return SAME_SESSION_TEXT;
+}
+
+const SAME_SESSION_TEXT =
+  "This commit stages both a test and code it could cover — the shape L0 takes " +
+  "in a diff, where the implementer authored the evaluator. This check reads the " +
+  "staged set only: it cannot tell who wrote the test, so it is a prompt to STATE " +
+  "the level, not a finding that you are at L0. L0 is a permitted FALLBACK, not " +
+  "the default: where a second session, a second model or a second provider was " +
+  "available, the test should have come from one of them. Say which in the commit " +
+  "or the PR body — a diff looks identical either way. See evaluator-independence " +
+  "§ Tests are evaluators.";
+
+/** Both a test path and a production path in one changed set. */
+export function touchesTestAndCode(paths: readonly string[]): boolean {
+  return paths.some(isTestPath) && paths.some(isCodePath);
+}
+
+/** The shell command this envelope is about, across the key names hosts use. */
+function _commandOf(envelope: JsonObject): string | null {
+  const payload = _isObject(envelope["payload"]) ? envelope["payload"] : envelope;
+  const input = _isObject(payload["tool_input"]) ? payload["tool_input"] : payload;
+  for (const key of ["command", "cmd", "shell_command"]) {
+    const v = input[key];
+    if (typeof v === "string" && v !== "") return v;
+  }
+  return null;
+}
+
+/**
+ * Staged paths, or `null` when git cannot answer.
+ *
+ * `null` is not "nothing staged" — it is "no reading", and the caller must not
+ * turn an unreadable index into a silent clean bill. A hook that cannot measure
+ * says nothing rather than implying a measurement.
+ */
+function _stagedPaths(consumer_root: string): string[] | null {
+  const r = spawnSync("git", ["diff", "--cached", "--name-only"], {
+    cwd: consumer_root,
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return null;
+  const out = r.stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+  return out.length === 0 ? null : out;
+}
+
 export function run(stdin_text: string, options: { consumer_root: string }): number {
   let envelope: JsonObject = {};
   if (stdin_text.trim()) {
@@ -355,6 +429,27 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   }
 
   const [tool, prompt] = extractDispatch(envelope);
+
+  // 2.4 — the one-commit test-authorship flag, checked BEFORE the dispatch
+  // branch and returning early. A commit envelope carries no evaluation prompt,
+  // so `decide` would classify it as not-an-evaluation and allow it silently;
+  // running both would mean the commit path fell through to a counter that is
+  // about evaluation dispatches and would be wrong to advance here.
+  //
+  // CHEAP TEST FIRST, and that ordering is the finding rather than a style
+  // preference: `_stagedPaths` spawns `git diff --cached`, and this concern is
+  // bound on `pre_tool_use`, so reading the index before the regex made every
+  // Read, Edit, Grep and Task dispatch in every session pay a subprocess. The
+  // regex answers "is this even a commit" for free.
+  const flag = sameSessionTestFlag(_commandOf(envelope));
+  if (flag !== null) {
+    const staged = _stagedPaths(options.consumer_root);
+    if (staged !== null && touchesTestAndCode(staged)) {
+      process.stdout.write(`${JSON.stringify({ decision: "warn", reason: flag })}\n`);
+      return EXIT_ALLOW;
+    }
+  }
+
   const decision = decide(tool, prompt, state.evaluations.length);
 
   if (decision.evaluations > state.evaluations.length) {

package/src/scripts/hooks/exit_codes.ts

@@ -0,0 +1,128 @@
+/**
+ * The hook exit-code table — one frozen definition, imported everywhere.
+ *
+ * road-to-a-kernel-that-guards-its-plumbing 4.1.
+ *
+ * WHAT WAS WRONG. Thirty-three files under `src/scripts/hooks/` each declared
+ * their own `const EXIT_ALLOW = 0` / `EXIT_BLOCK = 1` / `EXIT_WARN = 2`, two of
+ * them under a third name (`EXIT_OK`). Thirty-three copies of a contract is
+ * thirty-three places it can be changed in one and not the others, and the
+ * change that matters here is not a typo: exit 1 and exit 2 mean the OPPOSITE
+ * things on Claude Code from what they mean in this tree's internal language
+ * (`host_semantics.ts` exists entirely to lower one onto the other). A number
+ * that means "advisory" here and "hard deny" there is not a constant anyone
+ * should be re-deriving per file.
+ *
+ * WHAT THE TABLE ADDS BEYOND THE NUMBERS. `owner` and `authorizedBy` — who
+ * decides that a concern emits this code, and what authorises the dispatcher to
+ * act on it. A bare `1` in a concern says nothing about whether that concern was
+ * ever allowed to refuse; the manifest's `severity` is what authorises it, and
+ * the dispatcher enforces that ceiling (`_is_advisory`). Recording it beside the
+ * number is what makes the table a contract rather than an enum.
+ *
+ * WHAT IS NOT IN SCOPE. The `*-dispatcher.sh` trampolines carry inline
+ * `process.exit(0)` in a `node -e` one-liner that reads a workspace root off
+ * stdin. They are shell, they cannot import, and their exit code is the
+ * one-liner's, never a verdict. `lint_exit_codes` scans `.ts` only.
+ */
+
+/** Allow — the concern has no objection. The overwhelmingly common verdict. */
+export const EXIT_ALLOW = 0;
+
+/** Block — the concern refuses. Only a `severity: blocking` concern may. */
+export const EXIT_BLOCK = 1;
+
+/** Warn — advisory. The dispatcher exits 0 and surfaces the reason. */
+export const EXIT_WARN = 2;
+
+/**
+ * Error — the concern crashed or could not decide.
+ *
+ * `3` is the floor, not the only value: the dispatcher treats every rc ≥ 3 the
+ * same way, and what that way IS depends on the concern's declared severity.
+ */
+export const EXIT_ERROR = 3;
+
+/**
+ * Usage error on the process's OWN argv — not a verdict, and not a row.
+ *
+ * `dispatch_hook` and `replay_hook` are also CLIs: run with `--platform`
+ * missing they exit before any concern is consulted. The number is 2 by the
+ * POSIX convention for a usage error, which COLLIDES with `EXIT_WARN` by
+ * coincidence and not by meaning — nothing advisory has happened, and no
+ * concern has spoken.
+ *
+ * Named rather than left as a bare `2`, and kept OUT of `EXIT_CODES`, because
+ * both readings are wrong: importing `EXIT_WARN` here would assert a verdict
+ * that was never reached, and adding a fifth row would put a non-verdict in a
+ * table whose whole subject is what a concern may say. `lint_exit_codes`
+ * refuses the bare literal, so the next writer has to pick one of the two
+ * deliberately.
+ */
+export const EXIT_USAGE = 2;
+
+export interface ExitCodeRow {
+    /** The numeric code, or its floor for the open-ended error band. */
+    readonly code: number;
+    readonly name: 'allow' | 'block' | 'warn' | 'error';
+    readonly meaning: string;
+    /** Who decides a concern emits this code. */
+    readonly owner: string;
+    /** What authorises the dispatcher to act on it. */
+    readonly authorizedBy: string;
+}
+
+/**
+ * The frozen table. Ordered by code; the last row is a band, not a value.
+ *
+ * `as const` plus `Object.freeze` rather than a plain array: this is the kind of
+ * structure a later convenience ("just push a row for the new verdict") turns
+ * into a fourth dialect, and the whole point of the file is that there is one.
+ */
+export const EXIT_CODES: readonly ExitCodeRow[] = Object.freeze([
+    Object.freeze({
+        code: EXIT_ALLOW,
+        name: 'allow',
+        meaning: 'no objection; the dispatcher passes the call through',
+        owner: 'every concern — the default verdict',
+        authorizedBy: 'nothing; allowing needs no authority',
+    }),
+    Object.freeze({
+        code: EXIT_BLOCK,
+        name: 'block',
+        meaning: 'refuse the call; the dispatcher lowers this onto the host deny channel',
+        owner: 'a concern declared `severity: blocking` in hook_manifest.yaml',
+        authorizedBy:
+            'the manifest entry plus its row in the BLOCKING_ALLOWLIST of ' +
+            'tests/hooks/concern_severity.test.ts — an advisory concern emitting this is ' +
+            'downgraded to warn by dispatch_hook._is_advisory',
+    }),
+    Object.freeze({
+        code: EXIT_WARN,
+        name: 'warn',
+        meaning: 'advisory; the dispatcher exits 0 and surfaces the reason',
+        owner: 'any concern',
+        authorizedBy:
+            'nothing; warning is the ceiling for an advisory concern and is always available ' +
+            'to a blocking one',
+    }),
+    Object.freeze({
+        code: EXIT_ERROR,
+        name: 'error',
+        meaning:
+            'the concern crashed, timed out, or could not decide — any rc >= 3. The dispatcher ' +
+            'resolves it by the concern`s declared severity, never by the number itself',
+        owner: 'no concern emits this on purpose; the runtime does',
+        authorizedBy:
+            'hook_manifest.yaml `fail_closed` and `severity` together — see ' +
+            'docs/contracts/hook-architecture-v1.md § Exit-code semantics',
+    }),
+] as const);
+
+/** The row a raw exit code resolves to, or `null` for a negative code. */
+export function rowFor(code: number): ExitCodeRow | null {
+    if (code >= EXIT_ERROR) {
+        return EXIT_CODES[3] ?? null;
+    }
+    return EXIT_CODES.find((r) => r.code === code) ?? null;
+}

package/src/scripts/hooks/host_lowering.json

@@ -0,0 +1 @@
+{"fingerprint":"08575a71d81fd8a5ef9e4b400f4a38cb66c26e1dd701d98f3cdc0bdc9e4758b4:22235","table":{"schema_version":1,"hosts":{"claude":{"surfaces":{"any":{"entry_shape":"claude-settings-hooks","json_shape":"hook-specific-output","fail_policy":"propagate","timeout_unit":"seconds","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://code.claude.com/docs/en/hooks.md","docs_digest":"9dd68316c1111c118e3ddb82861ac6271a8cd164cee0d371b26165efff35fe88","probe_at":"2026-09-06","host_version":"2.1.263","expires":"2027-09-06"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"Stop","block_exit":2,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"UserPromptSubmit","block_exit":2,"answered_at":"2026-09-29"},"pre_tool_use":{"native":"PreToolUse","block_exit":2,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"},"pre_compact":{"native":"PreCompact","block_exit":null,"answered_at":"2026-09-29"},"subagent_start":{"native":"SubagentStart","block_exit":null,"answered_at":"2026-09-29"},"subagent_stop":{"native":"SubagentStop","block_exit":null,"answered_at":"2026-09-29"}}}}},"augment":{"surfaces":{"any":{"entry_shape":"augment-settings-hooks","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.augmentcode.com/cli/hooks.md","docs_digest":"e500823be8303717020c1823f670e06d100108f6e3ac4b8d12a46d91fd1898fa","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"Stop","block_exit":null,"answered_at":"2026-09-29"},"pre_tool_use":{"native":"PreToolUse","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"cursor":{"surfaces":{"any":{"entry_shape":"cursor-hooks-json","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://cursor.com/docs/hooks.md","docs_digest":"7294a2d63b19d79a5283c948afe174cba8b06a7585563d34a2c41b90f5df0d39","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"sessionStart","block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"sessionEnd","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"stop","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"beforeSubmitPrompt","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"postToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"cline":{"surfaces":{"any":{"entry_shape":"cline-per-event-script","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.cline.bot/customization/hooks.md","docs_digest":"ef87561721f4cb80fe6d682b6866d638a4952dd416d36cd5ab398426ce64084b","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":["TaskStart","TaskResume"],"block_exit":null,"answered_at":"2026-09-29"},"session_end":{"native":"TaskComplete","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"TaskCancel","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"UserPromptSubmit","block_exit":null,"answered_at":"2026-09-29"},"post_tool_use":{"native":"PostToolUse","block_exit":null,"answered_at":"2026-09-29"}}}}},"windsurf":{"surfaces":{"any":{"entry_shape":"windsurf-hooks-json","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.devin.ai/desktop/cascade/hooks.md","docs_digest":"460ffe7aa91998804920f6722c0153b9948eadd5edafa19582298475a19835a2","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"post_setup_worktree","block_exit":null,"answered_at":"2026-09-29"},"user_prompt_submit":{"native":"pre_user_prompt","block_exit":null,"answered_at":"2026-09-29"},"stop":{"native":"post_cascade_response","block_exit":null,"answered_at":"2026-09-29"}}}}},"gemini":{"surfaces":{"any":{"entry_shape":"gemini-settings-hooks","json_shape":"none","fail_policy":"propagate","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://geminicli.com/docs/hooks/reference.md","docs_digest":"06d37f2f66812ee78bb46c37a112203376f0bae4d3b8b44ac79d0bda4b86a118","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{"session_start":{"native":"SessionStart","block_exit":null,"answered_at":"2026-09-29","matcher":""},"session_end":{"native":"SessionEnd","block_exit":null,"answered_at":"2026-09-29","matcher":""},"stop":{"native":"AfterAgent","block_exit":null,"answered_at":"2026-09-29","matcher":""},"user_prompt_submit":{"native":"BeforeAgent","block_exit":null,"answered_at":"2026-09-29","matcher":""},"post_tool_use":{"native":"AfterTool","block_exit":null,"answered_at":"2026-09-29","matcher":".*"}}}}},"cowork":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":null,"docs_digest":null,"probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{}}}},"copilot":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://docs.github.com/en/copilot/concepts/agents/hooks.md","docs_digest":"bfd40aa93ad62133efc17a50f189034f01594dc89a5d31a13a0c541d691acede","probe_at":null,"host_version":null,"expires":"2027-09-29"},"slots":{}}}},"codex":{"surfaces":{"any":{"entry_shape":"none","json_shape":"none","fail_policy":"discard","timeout_unit":"unknown","timeout_default":null,"verified":{"docs_at":"2026-09-29","docs_url":"https://developers.openai.com/codex/hooks.md","docs_digest":"724881d81f1a9fdb35ea42d4851a11b1f6606bbc6e9d2d05c1e8c466fc25c630","probe_at":"2026-10-01","host_version":"0.148.0","expires":"2027-09-29"},"slots":{}}}}}}}

package/src/scripts/hooks/host_lowering.ts

@@ -21,6 +21,8 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { tableFingerprint } from './table_fingerprint.js';
+
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
 const _REPO_ROOT = path.resolve(
@@ -30,10 +32,59 @@ const _REPO_ROOT = path.resolve(
 
 export const HOST_LOWERING_PATH = path.join(_REPO_ROOT, 'src', 'scripts', 'hooks', 'host_lowering.yaml');
 
+/**
+ * Compiled sibling of the table above — the same data with comments stripped.
+ *
+ * WHY IT EXISTS, measured rather than assumed. The dispatcher consults this
+ * table on EVERY dispatch (`emitFor` needs `blockExitFor`), and since
+ * `hook_manifest.json` landed it is the ONLY remaining YAML reader on that
+ * path — so it pays both its own parse and the cold load of the `yaml` module
+ * nothing else pulls in any more. Measured on one developer machine: the
+ * 16.8 kB source parses in 3.1-7.0 ms and the `yaml` module costs a further
+ * 8.1 ms to load, against `JSON.parse` of the 5.9 kB compiled form at 0.03 ms.
+ *
+ * Exactly the shape `compile_hook_manifest` already established for the
+ * manifest, including the content fingerprint — see `table_fingerprint` for
+ * why freshness is decided by content and never by mtime.
+ */
+export const HOST_LOWERING_JSON_PATH = path.join(_REPO_ROOT, 'src', 'scripts', 'hooks', 'host_lowering.json');
+
 /** Provenance of a row. Every field may be null; `expires` may not. */
 export interface VerifiedBlock {
     docs_at: string | null;
     docs_url: string | null;
+    /**
+     * sha256 of the `docs_url` body as last ESTABLISHED for this row.
+     *
+     * "Established" means recorded by a human-run fill, not merely seen. The
+     * watcher re-hashes the page on every run and writes the new value only
+     * when the field was empty; on a DRIFT it deliberately leaves the recorded
+     * digest alone, so the field keeps pointing at the body someone actually
+     * read while `expires` carries the alarm.
+     *
+     * Three earlier wordings were wrong and all three are named rather than
+     * quietly replaced, because each was corrected by evidence the next one
+     * then contradicted. "As fetched on `docs_at`" was refuted by the very
+     * first fill (digests taken 2026-10-01 against rows whose `docs_at` is
+     * 2026-09-29). "As fetched by the LAST digest run" was refuted by the
+     * writer (after a drift the last run computed a different hash than the
+     * field holds). "`docs_at` + `docs_digest` are ONE pair" was refuted by
+     * the same committed data as the first — stating it was a relapse, caught
+     * in review.
+     *
+     * The two fields are simply INDEPENDENT. `docs_at` dates a human reading
+     * the page for the row's ANSWERS; `docs_digest` names the body the watcher
+     * compares against. Nothing guarantees they were the same fetch, and no
+     * wording that implies they were can survive this table's own rows.
+     *
+     * Null where there is nothing to hash — a row whose `docs_url` is null —
+     * and null is also the pre-fill state `check_host_docs_digest --fetch
+     * --write` resolves. It is deliberately NOT part of the expiry test: a
+     * digest is evidence about the page, `expires` is this package's review-by
+     * date, and collapsing the two would make a vendor's CSS rebuild look like
+     * a lapsed citation.
+     */
+    docs_digest: string | null;
     probe_at: string | null;
     host_version: string | null;
     expires: string;
@@ -44,6 +95,21 @@ export interface SlotRow {
     native: string[];
     /** Exit code the host honours as a refusal here, or null if unestablished. */
     block_exit: number | null;
+    /**
+     * The date this pair was last answered, or null when it never was.
+     *
+     * `block_exit: null` alone cannot distinguish "looked, found none" from
+     * "nobody looked", and the whole point of this table is that a zero is a
+     * fact with a date on it. `lint_hook_manifest` requires the date; the
+     * parser keeps it nullable so a malformed table still parses into
+     * something the linter can report on rather than throwing first.
+     */
+    answered_at: string | null;
+    /**
+     * Citation for this pair, when it differs from the row's
+     * `verified.docs_url`. Absent means the row's URL is the citation.
+     */
+    docs_url: string | null;
     /** Entry-shape-specific extra (gemini's per-binding matcher). */
     matcher?: string;
 }
@@ -72,7 +138,18 @@ function _asString(v: unknown): string | null {
 }
 
 function _parse(text: string): HostLowering {
-    const raw = parseYaml(text) as Record<string, unknown> | null;
+    return _structure(parseYaml(text) as Record<string, unknown> | null);
+}
+
+/**
+ * Build the table from an ALREADY-PARSED document.
+ *
+ * Split out of `_parse` so the compiled-JSON fast path below reaches exactly
+ * the same validation on exactly the same shape — the YAML step is the only
+ * thing it skips. A second structuring function would be a second thing to
+ * drift; there is one, and both paths call it.
+ */
+function _structure(raw: Record<string, unknown> | null): HostLowering {
     const hostsRaw = raw?.['hosts'];
     if (typeof hostsRaw !== 'object' || hostsRaw === null) {
         throw new Error('host_lowering.yaml: missing `hosts:` map');
@@ -96,6 +173,7 @@ function _parse(text: string): HostLowering {
                 verified = {
                     docs_at: _asString(verifiedRaw['docs_at']),
                     docs_url: _asString(verifiedRaw['docs_url']),
+                    docs_digest: _asString(verifiedRaw['docs_digest']),
                     probe_at: _asString(verifiedRaw['probe_at']),
                     host_version: _asString(verifiedRaw['host_version']),
                     expires,
@@ -110,6 +188,8 @@ function _parse(text: string): HostLowering {
                 const row: SlotRow = {
                     native,
                     block_exit: typeof be === 'number' ? be : null,
+                    answered_at: _asString(rv['answered_at']),
+                    docs_url: _asString(rv['docs_url']),
                 };
                 if (typeof rv['matcher'] === 'string') row.matcher = rv['matcher'];
                 slots.set(slot, row);
@@ -131,12 +211,57 @@ function _parse(text: string): HostLowering {
 
 let _cache: HostLowering | null = null;
 
-/** Parse the table once per process. Throws on a missing or malformed file. */
+/**
+ * Parse the table once per process. Throws on a missing or malformed file.
+ *
+ * Tries the compiled sibling first and falls through to the YAML source on
+ * anything unexpected — missing, unreadable, malformed, or a fingerprint that
+ * does not match the live source. A stale or absent compiled file is therefore
+ * SLOW and never WRONG, which is the property that lets the optimisation ship
+ * without a second correctness argument.
+ */
 export function loadHostLowering(): HostLowering {
-    if (_cache === null) _cache = _parse(fs.readFileSync(HOST_LOWERING_PATH, 'utf-8'));
+    if (_cache !== null) return _cache;
+    // Reading the YAML unconditionally costs ~0.03 ms — it is the PARSE that is
+    // expensive — so the fast path still skips the whole 11-15 ms.
+    const text = fs.readFileSync(HOST_LOWERING_PATH, 'utf-8');
+    let compiled: string | null;
+    try {
+        compiled = fs.readFileSync(HOST_LOWERING_JSON_PATH, 'utf-8');
+    } catch {
+        compiled = null;
+    }
+    _cache = resolveTable(text, compiled);
     return _cache;
 }
 
+/**
+ * Pick the path and build the table — the whole decision, with no I/O.
+ *
+ * Split from `loadHostLowering` so the FALLBACK semantics are testable. They
+ * are the half that carries the risk: the fast path is easy to verify and a
+ * mis-shaped fallback would be a wrong table rather than a slow one. A test
+ * that could only reach the happy path would be watching the safe half.
+ */
+export function resolveTable(yamlText: string, compiledText: string | null): HostLowering {
+    if (compiledText !== null) {
+        try {
+            const raw = JSON.parse(compiledText) as Record<string, unknown>;
+            const table = raw['table'];
+            if (
+                raw['fingerprint'] === tableFingerprint(yamlText) &&
+                typeof table === 'object' &&
+                table !== null
+            ) {
+                return _structure(table as Record<string, unknown>);
+            }
+        } catch {
+            // Malformed JSON → the source below. Never fail on the optimisation.
+        }
+    }
+    return _parse(yamlText);
+}
+
 /** Test seam — drop the memoized table so a fixture can be loaded instead. */
 export function _resetHostLoweringCache(table?: HostLowering): void {
     _cache = table ?? null;