@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/_lib/continuity_surface.ts

@@ -0,0 +1,296 @@
+/**
+ * Continuity-surface inventory — the behavioural half of the ratchet.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `road-to-one-continuity-record` measured its own success as five numbers —
+ * public continuity commands, session resume pickers, persistent continuity
+ * artefacts, continuity schemas, normal-path manual actions — and its council
+ * of 2026-09-07 named the defect in measuring them by name:
+ *
+ *   "Any persisted state written for later session/run recovery, verification,
+ *   or context restoration must be listed, whether or not it is labeled
+ *   continuity."
+ *
+ * A count keyed on the WORD `continuity` is gameable by renaming. So the
+ * artefact axis is DISCOVERED behaviourally — every distinct leaf under
+ * `agents/runtime/state/` that any source file names — and the inventory then
+ * has to dispose of each one as `counted` or `excluded` WITH A REASON. A leaf
+ * nothing disposes of is a hard failure, which is what makes a newly added
+ * persisted-state surface impossible to slip past the count silently.
+ *
+ * The exclusions are the load-bearing half, not the leftovers. `checkpoints/`
+ * is the worked example the council named: it is kept (D2 — run-integrity
+ * evidence is keyed by run id, consumed by `run:supervise`, and a disagreement
+ * there is an integrity alarm rather than a degraded resume), so it is excluded
+ * from the continuity axis, and that exclusion is PRINTED on every run rather
+ * than buried in a predicate.
+ *
+ * WHAT THIS MODULE IS NOT
+ * -----------------------
+ * It does not decide policy. It reads a committed inventory, checks that the
+ * inventory still describes the tree (every `locus` resolves; every discovered
+ * leaf is disposed of), and derives the five numbers from the dispositions.
+ * The ratchet that forbids growth lives in `check_continuity_surface.ts`, which
+ * runs these same functions over a materialised base tree.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Repo-relative POSIX path of the committed inventory. */
+export const INVENTORY_POSIX = 'src/config/continuity-surface.json';
+
+/** Source roots the behavioural discovery walks. */
+export const DISCOVERY_ROOTS: readonly string[] = [
+    'src/scripts',
+    'src/agent-src/scripts',
+    'src/cli',
+    'src/shared',
+    'src/server',
+    'src/install',
+];
+
+/**
+ * The five axes, in the order the parent roadmap's goal states them. The order
+ * is part of the contract: the goal reads `0 / 0 / 1 / 1 / 0` positionally, and
+ * a reader comparing a run against that line needs the same positions.
+ */
+export const AXES = [
+    'public_continuity_commands',
+    'session_resume_pickers',
+    'persistent_continuity_artefacts',
+    'continuity_schemas',
+    'normal_path_manual_actions',
+] as const;
+
+export type Axis = (typeof AXES)[number];
+
+/** The target the parent roadmap's goal states, by axis. */
+export const TARGETS: Readonly<Record<Axis, number>> = {
+    public_continuity_commands: 0,
+    session_resume_pickers: 0,
+    persistent_continuity_artefacts: 1,
+    continuity_schemas: 1,
+    normal_path_manual_actions: 0,
+};
+
+export interface InventoryRow {
+    /** Stable identifier. For a discovered artefact this is the state leaf. */
+    id: string;
+    /** Which axis this row belongs to. */
+    axis: Axis;
+    /** `counted` contributes to the axis number; `excluded` does not. */
+    disposition: 'counted' | 'excluded';
+    /**
+     * Repo-relative `file` or `file:line` the row is anchored to. It must
+     * resolve, which is what makes a retirement MEASURED: deleting the surface
+     * without deleting or re-disposing its row reddens.
+     */
+    locus: string;
+    /**
+     * Why. Mandatory on every row, not only on exclusions — a `counted` row
+     * whose reason nobody wrote is a number without a meaning.
+     */
+    reason: string;
+}
+
+export interface Inventory {
+    rows: readonly InventoryRow[];
+}
+
+/** A leaf the discovery found, with the first source position that names it. */
+export interface DiscoveredLeaf {
+    leaf: string;
+    locus: string;
+}
+
+const LEAF_RE =
+    /agents\/runtime\/state\/([A-Za-z0-9_.-]+)|['"]runtime['"],\s*['"]state['"],\s*['"]([A-Za-z0-9_.-]+)['"]/g;
+
+const SOURCE_EXT = /\.(ts|js|mjs|sh|bash)$/;
+
+function _walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            _walk(full, out);
+            continue;
+        }
+        if (!SOURCE_EXT.test(entry.name)) continue;
+        // Test files name state paths in fixtures; a fixture is not a surface.
+        if (entry.name.endsWith('.test.ts')) continue;
+        out.push(full);
+    }
+}
+
+/**
+ * Every distinct `agents/runtime/state/<leaf>` any source file names, with the
+ * first `file:line` that names it. Sorted, so two runs over the same tree
+ * produce byte-identical output and a diff of the count is a diff of the tree.
+ */
+export function discoverStateLeaves(root: string): DiscoveredLeaf[] {
+    const files: string[] = [];
+    for (const rel of DISCOVERY_ROOTS) {
+        _walk(path.join(root, rel), files);
+    }
+    files.sort();
+    const found = new Map<string, string>();
+    for (const file of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue;
+        }
+        const rel = path.relative(root, file).split(path.sep).join('/');
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? '';
+            LEAF_RE.lastIndex = 0;
+            let match: RegExpExecArray | null;
+            while ((match = LEAF_RE.exec(line)) !== null) {
+                const raw = match[1] ?? match[2] ?? '';
+                // A trailing dot is string concatenation in the source
+                // (`'...json' + '.tmp'`), never part of the leaf name.
+                const leaf = raw.replace(/\.+$/, '');
+                if (leaf === '' || leaf === '.') continue;
+                if (!found.has(leaf)) found.set(leaf, `${rel}:${String(i + 1)}`);
+            }
+        }
+    }
+    return [...found.keys()].sort().map((leaf) => ({ leaf, locus: found.get(leaf) ?? '' }));
+}
+
+export function readInventory(root: string): Inventory {
+    const file = path.join(root, INVENTORY_POSIX);
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as { rows?: unknown };
+    const rows = Array.isArray(parsed.rows) ? (parsed.rows as InventoryRow[]) : [];
+    return { rows };
+}
+
+/** Does a `file` or `file:line` locus still resolve in this tree? */
+export function locusResolves(root: string, locus: string): boolean {
+    const match = /^(.*?):(\d+)$/.exec(locus);
+    const rel = match ? (match[1] ?? '') : locus;
+    const target = path.join(root, rel);
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(target);
+    } catch {
+        return false;
+    }
+    if (!match) return true;
+    if (!stat.isFile()) return false;
+    // A line anchor must still BE a line. Content is deliberately not compared:
+    // a locus that pins prose would rot on every reflow and turn the inventory
+    // into a line-number chore, which is how anchor checks get deleted.
+    const line = Number(match[2]);
+    let text: string;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    } catch {
+        return false;
+    }
+    return line >= 1 && line <= text.split('\n').length;
+}
+
+export interface SurfaceCounts {
+    public_continuity_commands: number;
+    session_resume_pickers: number;
+    persistent_continuity_artefacts: number;
+    continuity_schemas: number;
+    normal_path_manual_actions: number;
+}
+
+export function countAxes(inv: Inventory): SurfaceCounts {
+    const counts = {
+        public_continuity_commands: 0,
+        session_resume_pickers: 0,
+        persistent_continuity_artefacts: 0,
+        continuity_schemas: 0,
+        normal_path_manual_actions: 0,
+    };
+    for (const row of inv.rows) {
+        if (row.disposition !== 'counted') continue;
+        if (!AXES.includes(row.axis)) continue;
+        counts[row.axis] += 1;
+    }
+    return counts;
+}
+
+export interface InventoryFinding {
+    kind: 'undisposed-leaf' | 'dead-locus' | 'bad-row' | 'duplicate-row';
+    detail: string;
+}
+
+/**
+ * Validate the inventory against the tree.
+ *
+ * Three failure classes, and each exists because a specific way of faking a
+ * lower number would otherwise work:
+ *
+ *   - `undisposed-leaf` — a persisted-state leaf the source names and the
+ *     inventory does not mention. This is the add-a-surface-quietly route.
+ *   - `dead-locus` — a row anchored to something that no longer exists. This
+ *     is the claim-a-retirement-that-did-not-happen route in reverse: it forces
+ *     the row to be deleted (a real subtraction) rather than left standing.
+ *   - `bad-row` / `duplicate-row` — shape defects that would make either of the
+ *     above unenforceable.
+ */
+export function validateInventory(
+    root: string,
+    inv: Inventory,
+    discovered: readonly DiscoveredLeaf[],
+): InventoryFinding[] {
+    const findings: InventoryFinding[] = [];
+    const seen = new Set<string>();
+    for (const row of inv.rows) {
+        const id = typeof row.id === 'string' ? row.id : '';
+        if (id === '') {
+            findings.push({ kind: 'bad-row', detail: 'a row carries no `id`' });
+            continue;
+        }
+        if (seen.has(id)) {
+            findings.push({ kind: 'duplicate-row', detail: `two rows share the id \`${id}\`` });
+        }
+        seen.add(id);
+        if (!AXES.includes(row.axis)) {
+            findings.push({ kind: 'bad-row', detail: `\`${id}\`: unknown axis \`${String(row.axis)}\`` });
+        }
+        if (row.disposition !== 'counted' && row.disposition !== 'excluded') {
+            findings.push({
+                kind: 'bad-row',
+                detail: `\`${id}\`: disposition must be \`counted\` or \`excluded\`, got \`${String(row.disposition)}\``,
+            });
+        }
+        if (typeof row.reason !== 'string' || row.reason.trim().length < 20) {
+            findings.push({
+                kind: 'bad-row',
+                detail: `\`${id}\`: every row needs a reason of substance — a number without a stated meaning is not an inventory`,
+            });
+        }
+        if (typeof row.locus !== 'string' || row.locus.trim() === '') {
+            findings.push({ kind: 'bad-row', detail: `\`${id}\`: no \`locus\`` });
+        } else if (!locusResolves(root, row.locus)) {
+            findings.push({
+                kind: 'dead-locus',
+                detail: `\`${id}\`: locus \`${row.locus}\` does not resolve — if the surface was retired, DELETE the row (that is the subtraction); if it moved, re-anchor it`,
+            });
+        }
+    }
+    for (const item of discovered) {
+        if (!seen.has(item.leaf)) {
+            findings.push({
+                kind: 'undisposed-leaf',
+                detail: `\`${item.leaf}\` (${item.locus}) is persisted state under agents/runtime/state/ that the inventory does not dispose of — add a row with \`disposition: counted\` (it is continuity state) or \`disposition: excluded\` with the reason it is not`,
+            });
+        }
+    }
+    return findings;
+}

package/src/scripts/_lib/corpus_manifest.ts

@@ -46,7 +46,19 @@ import {
 import { isExclusivelyPackageOnly } from '../../install/partitionEligibility.js';
 import { dedupableRules } from '../../install/ruleLayerPartition.js';
 
-export const CORPUS_MANIFEST_VERSION = 'corpus-manifest-v1';
+/**
+ * Bumped to v2 on 2026-09-07 with the `partition_active` -> `host_layer_verified`
+ * rename, after a neutral review named the alternative: `parseManifest` accepts
+ * any object carrying the declared version and validates three fields, and
+ * `diffManifests` compares with `String(e) !== String(a)`. So a v1 manifest
+ * (which has `partition_active` and no `host_layer_verified`) compared against
+ * another v1 yields `"undefined" === "undefined"` on the renamed field — NO
+ * difference reported, on a field neither side has. That is verbatim the failure
+ * `parseManifest`'s own error text says the version check exists to prevent:
+ * "comparing it partially would report equivalence from the fields that happened
+ * to survive". A rename inside a frozen version is exactly that.
+ */
+export const CORPUS_MANIFEST_VERSION = 'corpus-manifest-v2';
 
 /** The tool directory the experiment's corpus is enumerated from. */
 export const CORPUS_TOOL_DIR = '.claude/rules';
@@ -142,7 +154,7 @@ export interface ProjectionDecision {
      * `null` is the default and is the honest value for a capture that cannot
      * establish it. Every other field in this struct is a function of the
      * `(repoRoot, userHome)` pair the capture was given; this one is not.
-     * `partitionActive` resolves through `resolvePartitionVerdict`, which reads
+     * `hostLayerVerified` resolves through `resolveHostLayerVerdict`, which reads
      * the host layer at `os.homedir()` and the install lockfile at its own
      * fixed location — ignoring `userHome` entirely — and memoises the answer
      * for the life of the process. So a capture over a temporary tree that
@@ -150,7 +162,7 @@ export interface ProjectionDecision {
      * one process would reuse the first verdict. A caller for which those
      * globals ARE the run's own host supplies the predicate; nobody else does.
      */
-    readonly partition_active: boolean | null;
+    readonly host_layer_verified: boolean | null;
     readonly tool_id: string | null;
     /** The global layer directory, home-relative; `null` when this host has none. */
     readonly layer_dir: string | null;
@@ -365,7 +377,7 @@ export interface ProjectionDecisionOptions {
      * The host partition verdict, supplied by a caller for which the process
      * globals it reads are this run's own host. Omitted → `null`.
      */
-    readonly partitionActive?: ((repoRoot: string) => boolean) | undefined;
+    readonly hostLayerVerified?: ((repoRoot: string) => boolean) | undefined;
 }
 
 export function captureProjectionDecision(
@@ -401,7 +413,8 @@ export function captureProjectionDecision(
             sha256: layerPath === null ? null : sha256OfFile(path.join(layerPath, n)),
         }));
     return {
-        partition_active: opts.partitionActive === undefined ? null : opts.partitionActive(repoRoot),
+        host_layer_verified:
+            opts.hostLayerVerified === undefined ? null : opts.hostLayerVerified(repoRoot),
         tool_id: toolId,
         layer_dir: layerPath === null ? null : homeRelative(layerPath, userHome),
         carries: verdict.carries,
@@ -451,8 +464,8 @@ export interface CaptureOptions {
     readonly limit: number;
     readonly enumerationRule: string;
     readonly env?: Readonly<Record<string, string | undefined>> | undefined;
-    /** See {@link ProjectionDecisionOptions.partitionActive}. Omitted → `null`. */
-    readonly partitionActive?: ((repoRoot: string) => boolean) | undefined;
+    /** See {@link ProjectionDecisionOptions.hostLayerVerified}. Omitted → `null`. */
+    readonly hostLayerVerified?: ((repoRoot: string) => boolean) | undefined;
     /** See {@link UserScopeOptions.ruleNames}. Omitted → the projection-source superset. */
     readonly ruleNames?: readonly string[] | undefined;
 }
@@ -531,7 +544,7 @@ export function captureManifest(opts: CaptureOptions): CorpusManifest {
         user_scope_population:
             opts.ruleNames === undefined ? 'projection-source-superset' : 'caller-supplied',
         projection: captureProjectionDecision(repoRoot, userHome, {
-            partitionActive: opts.partitionActive,
+            hostLayerVerified: opts.hostLayerVerified,
         }),
         generator_config: generatorConfig,
         runtime: { node: process.version, platform: os.platform(), arch: os.arch() },
@@ -656,7 +669,11 @@ export function diffManifests(expected: CorpusManifest, actual: CorpusManifest):
     // The partition half, which is where the observed skips actually came from.
     // Diffed by digest rather than by name list because the inventory runs to
     // three figures and a diff nobody reads is a diff that does not exist.
-    push('projection.partition_active', expected.projection.partition_active, actual.projection.partition_active);
+    push(
+        'projection.host_layer_verified',
+        expected.projection.host_layer_verified,
+        actual.projection.host_layer_verified,
+    );
     push('projection.carries', expected.projection.carries, actual.projection.carries);
     push('projection.reason', expected.projection.reason, actual.projection.reason);
     push('projection.layer_digest', expected.projection.layer_digest, actual.projection.layer_digest);

package/src/scripts/_lib/hook_settings.ts

@@ -3,7 +3,7 @@
  * `.agent-settings.yml` without dragging a YAML parser into a hook.
  *
  * Every default-OFF hook needs the same two-level lookup, and the tree already
- * carries two hand-rolled copies of it (`code_graph_nudge_hook.enabled` and the
+ * carries two hand-rolled copies of it (`code_graph_context_hook (no flag)` and the
  * equivalent inside `design_slop_hook`). Adding a third copy for the route
  * nudge is what this file prevents; the two existing copies are pre-existing
  * duplication and are deliberately left alone — folding them in is a separate,

package/src/scripts/_lib/host_capability.ts

@@ -67,6 +67,23 @@ export interface HostCapabilityManifest {
      * stop-loss behaviour — loudly, never silently.
      */
     worker_respawn: boolean;
+    /**
+     * The host exposes its own structured-ask tool — a native question picker
+     * the agent can call instead of rendering a numbered-options block as prose.
+     *
+     * A STRICT BOOLEAN, and the per-host detail deliberately lives elsewhere.
+     * The source draft for road-to-asked-not-parked proposed a nested object
+     * carrying the tool name and the question/option ceilings; `asBool` below
+     * coerces every non-`true` value to `false`, so such an object would
+     * normalize silently to nothing. The shape lives in
+     * `_lib/structured_ask.ts` (`STRUCTURED_ASK_SHAPES`), which a caller reads
+     * explicitly; this field answers only whether there is anything to read.
+     *
+     * `false` is the safe default on purpose: an unknown host degrades to a
+     * text ask, and the agent never fires a tool call into a host that has no
+     * such tool.
+     */
+    structured_ask: boolean;
     /**
      * The host reads a PROJECT-scope MCP config file (`.mcp.json` or its
      * per-host equivalent) and starts the servers it names.
@@ -105,6 +122,7 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     separate_quota_pool: false,
     agent_teams: false,
     worker_respawn: false,
+    structured_ask: false,
     reads_project_mcp_config: false,
     // `true` because the safe answer here is "there is still a step", not
     // "there is nothing to do" — see the field's own note.
@@ -137,6 +155,7 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
         agent_teams: asBool(src.agent_teams),
         worker_respawn: asBool(src.worker_respawn),
+        structured_ask: asBool(src.structured_ask),
         reads_project_mcp_config: asBool(src.reads_project_mcp_config),
         // Inverted coercion, matching the inverted default: only an explicit
         // `false` clears the residual, so an absent or malformed value keeps
@@ -215,9 +234,26 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *
  * `agent_teams` — out of scope for a row by construction; see its own field
  *   doc comment and the protocol section.
+ *
+ * `structured_ask: false` — OBSERVED ABSENT, not never-looked, and the
+ *   difference is why it is written rather than omitted. claude (Claude Code
+ *   2.1.263, Opus 5 1M session, 2026-09-07). The host delivers the session's
+ *   tool surface at session start; that surface carried no structured-ask tool
+ *   under any name `_lib/structured_ask.ts` matches, and no per-host shape is
+ *   recorded for it in `STRUCTURED_ASK_SHAPES`. Artefact:
+ *   `agents/evidence/analysis/structured-ask-host-observation-2026-09.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artefact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ *   The observation is about the delivered surface of one session on one
+ *   version; it is not a claim that the vendor ships no such tool anywhere,
+ *   and a later session observing one writes the `true` row over it.
+ *
+ * NO ROW ANYWHERE SETS THE STRUCTURED-ASK FIELD TRUE, and the observation
+ * protocol above is the only path to the first one that does. A vendor's
+ * documentation is not that path — and the phrasing here avoids the literal
+ * key-value pair on purpose, because the roadmap step that ships this field
+ * verifies the absence with a grep for exactly that string.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
-    claude: { subagent_spawn: true, parallel_spawn: true },
+    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: false },
 };
 
 /**
@@ -323,6 +359,7 @@ const CAPABILITY_FIELDS: readonly CapabilityField[] = [
     'separate_quota_pool',
     'agent_teams',
     'worker_respawn',
+    'structured_ask',
     'reads_project_mcp_config',
     'mcp_needs_manual_activation',
 ];

package/src/scripts/_lib/injection_effect.ts

@@ -0,0 +1,151 @@
+/**
+ * Does a delivered rule body actually reach the model's context on this host?
+ *
+ * `road-to-delivery-on-hook-hosts` step 1.1, and the record owner ruling E3
+ * admits a host on.
+ *
+ * THE ONE THING THIS MODULE EXISTS TO REFUSE
+ * ------------------------------------------
+ * A host that BINDS `user_prompt_submit` looks, from every artefact in this
+ * tree, exactly like a host that DELIVERS. Cowork is the proof that they are
+ * different: it binds eight slots and its trampoline discards dispatcher output
+ * and `exit 0`s (`docs/enforcement-by-host.md:21`). Cursor and Cline bind the
+ * same slot the delivery concern needs, and whether their hook stdout reaches
+ * the model is unmeasured.
+ *
+ * So the binding is computable and the effect is not. This module keeps them
+ * apart by construction:
+ *
+ *   · `emits`             — computed. Is the concern bound on the slot at all?
+ *                           Read from the manifest. Cheap, always available,
+ *                           and NEVER promoted to an observation.
+ *   · `injection_effect`  — observed. Did a model visibly act on a delivered
+ *                           body? Read from a committed record and from nowhere
+ *                           else. There is no code path that derives it.
+ *
+ * An `observed-*` value is admissible only with the four-part citation the
+ * host-capability observation protocol requires (host · host version ·
+ * transcript or artefact reference · date) — see
+ * `_lib/host_capability.ts:183`. A record missing any part is rejected rather
+ * than downgraded, because a half-cited observation is the shape that gets
+ * quoted as a whole one.
+ *
+ * `unobserved` is a RESULT, not a gap. Most hosts cannot be observed from a
+ * Claude Code session at all, and the roadmap's K6 makes that an outcome: the
+ * host keeps its full rule bodies and loses nothing while it waits.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Where the committed observations live. One file, so there is one place to audit. */
+export const RECORD_REL = path.join('src', 'config', 'host-injection-effect.json');
+
+/**
+ * The three states, and the reason there is no fourth.
+ *
+ * `observed-false` is not "probably not" — it is a recorded observation that a
+ * delivered body did NOT reach the model, which is as citable as the positive.
+ * Anything not observed in either direction is `unobserved`.
+ */
+export const INJECTION_STATES = ['observed-true', 'observed-false', 'unobserved'] as const;
+export type InjectionState = (typeof INJECTION_STATES)[number];
+
+export interface InjectionObservation {
+    readonly state: InjectionState;
+    /** Host version the observation was taken on. Required for an `observed-*` state. */
+    readonly host_version: string | null;
+    /** Transcript or artefact reference. Required for an `observed-*` state. */
+    readonly transcript: string | null;
+    /** ISO date of the observation. Required for an `observed-*` state. */
+    readonly date: string | null;
+    /** Why it reads the way it does — required always, including for `unobserved`. */
+    readonly reason: string;
+}
+
+export type InjectionRecord = Readonly<Record<string, InjectionObservation>>;
+
+/** A malformed or under-cited row, in the words a maintainer needs to fix it. */
+export interface InjectionProblem {
+    readonly host: string;
+    readonly message: string;
+}
+
+/**
+ * Validate a record.
+ *
+ * The citation requirement is enforced HERE rather than at the reader, so every
+ * consumer gets the same answer: an `observed-*` row without all three citation
+ * fields is a problem, and `unobserved` needs only its reason.
+ */
+export function recordProblems(rec: InjectionRecord): InjectionProblem[] {
+    const out: InjectionProblem[] = [];
+    for (const [host, obs] of Object.entries(rec)) {
+        // A leading `_comment` is the convention every config JSON in this tree
+        // uses to carry its own contract, and it is not a host row. Skipping the
+        // underscore prefix rather than a literal `_comment` keeps a second
+        // annotation key from becoming a fake host with a fake verdict.
+        if (host.startsWith('_')) continue;
+        if (!(INJECTION_STATES as readonly string[]).includes(obs.state)) {
+            out.push({ host, message: `state ${JSON.stringify(obs.state)} is not one of ${INJECTION_STATES.join(' | ')}` });
+            continue;
+        }
+        if (typeof obs.reason !== 'string' || obs.reason.trim().length < 20) {
+            out.push({ host, message: 'reason is missing or shorter than 20 characters — an unexplained row reads as answered' });
+        }
+        if (obs.state === 'unobserved') continue;
+        for (const field of ['host_version', 'transcript', 'date'] as const) {
+            const v = obs[field];
+            if (typeof v !== 'string' || v.trim() === '') {
+                out.push({
+                    host,
+                    message:
+                        `state ${obs.state} without \`${field}\` — the observation protocol ` +
+                        '(host · host version · transcript · date) admits no partial citation',
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/** Load the committed record. A missing file is an empty record, never a throw. */
+export function loadRecord(root: string): InjectionRecord {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(root, RECORD_REL), 'utf-8')) as InjectionRecord;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The state for one host — `unobserved` when the record says nothing.
+ *
+ * Defaulting to `unobserved` rather than to a computed guess is the whole
+ * contract: a host nobody has looked at must never inherit a neighbour's
+ * verdict, and a bound slot must never imply a delivered body.
+ */
+export function stateFor(rec: InjectionRecord, host: string): InjectionState {
+    return rec[host]?.state ?? 'unobserved';
+}
+
+/**
+ * Is the concern bound on this host's slot? Computed from the manifest.
+ *
+ * Deliberately a separate function from `stateFor`, with a name that cannot be
+ * mistaken for it. This answers "could a body be emitted here", never "did one
+ * arrive".
+ */
+export function concernBound(
+    platforms: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>,
+    host: string,
+    slot: string,
+    concern: string,
+): boolean {
+    return (platforms[host]?.[slot] ?? []).includes(concern);
+}
+
+/** Does this host admit to `lean_projection.hosts` under E3? Observation only. */
+export function admissibleUnderE3(rec: InjectionRecord, host: string): boolean {
+    return stateFor(rec, host) === 'observed-true';
+}