@event4u/agent-config 14.11.0 → 14.13.0

package/src/scripts/_lib/gate_baseline.ts

@@ -32,8 +32,10 @@
  * Dates are plain `YYYY-MM-DD`; ages are whole days in UTC, so the verdict does
  * not depend on the machine's timezone.
  */
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import process from 'node:process';
 
 /** Days a baseline may sit unchanged before it must be fixed or reaffirmed. */
 export const STALE_AFTER_DAYS = 56;
@@ -105,12 +107,132 @@ export function loadBaselines(repoRoot: string, relPath: string = BASELINE_REL):
     } catch {
         return { gates: {} };
     }
+    return parseBaselines(raw);
+}
+
+function parseBaselines(raw: string): BaselineFile {
     const parsed = JSON.parse(raw) as Partial<BaselineFile>;
     const out: BaselineFile = { gates: parsed.gates ?? {} };
     if (parsed.$comment !== undefined) out.$comment = parsed.$comment;
     return out;
 }
 
+/**
+ * A baseline-resolution failure, which is a HARD error and never a fallback.
+ *
+ * `loadBaselines` returns an empty ratchet when the file is missing, and that
+ * is correct for a working-tree read: a repository with no baseline file has no
+ * ratchet. It is NOT correct for a target-commit read. There, a failure to
+ * resolve the ref or the blob means the governing policy could not be
+ * determined — and silently falling back to the working tree would let an
+ * infrastructure error change which policy applies, invisibly. The AI council
+ * was unanimous on this point (2026-08-25) and stated it applies to whichever
+ * invariant won.
+ */
+export class BaselineResolutionError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'BaselineResolutionError';
+    }
+}
+
+/**
+ * Read the baseline as it stands at a specific commit.
+ *
+ * `road-to-merge-surface-zero` Phase 3.1, under the **ABSOLUTE invariant** the
+ * AI council picked 2/2 on 2026-08-25 to resolve blocker B5.
+ *
+ * ## Why the target commit and not the merge base
+ *
+ * The merge-base read was the roadmap's original proposal and it selects the
+ * *contribution* invariant: a PR passes if it did not worsen the state it
+ * branched from. The worked example that killed it uses numbers this repository
+ * actually carries — `main` tightens `ci-parity:local-only` 165 → 160, a PR that
+ * branched earlier measures 163, the merge-base read returns 165, the PR
+ * **passes**, and after it merges `main` measures 163 against a baseline of 160.
+ * **A tightening is undone by a PR that never touched the baseline file and
+ * never saw a red.**
+ *
+ * The remedy of checking both was refused on a correctness ground rather than a
+ * preference: **violation counts are not necessarily compositional.** Conflict
+ * resolution, file movement, generated outputs and interactions with changes on
+ * `main` can make a prospective merge regress even when the isolated PR delta is
+ * non-positive. If trunk health is the invariant, the merge RESULT is what has
+ * to be measured.
+ *
+ * ## Why the TARGET commit specifically, and not the merge tree
+ *
+ * The count is measured on the prospective merge tree; the **policy** is read
+ * from the target. Reading the baseline out of the merge tree would let a PR
+ * loosen the very number it is being judged against, in the same diff.
+ *
+ * @throws BaselineResolutionError when the ref or the blob cannot be resolved.
+ */
+export function loadBaselinesAt(
+    repoRoot: string,
+    targetRef: string,
+    relPath: string = BASELINE_REL,
+    run: (args: string[]) => string = (args) =>
+        execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }),
+): BaselineFile {
+    let sha: string;
+    try {
+        sha = run(['rev-parse', '--verify', `${targetRef}^{commit}`]).trim();
+    } catch {
+        throw new BaselineResolutionError(
+            `cannot resolve target ref "${targetRef}" — the governing baseline is unknown, ` +
+                'and a working-tree fallback would let an infrastructure error decide the policy.',
+        );
+    }
+    let raw: string;
+    try {
+        raw = run(['show', `${sha}:${relPath}`]);
+    } catch {
+        throw new BaselineResolutionError(
+            `${relPath} does not exist at ${sha.slice(0, 9)} ("${targetRef}") — this is a ` +
+                'resolution failure, NOT an empty ratchet. A missing blob at a named commit ' +
+                'means the read was wrong, not that the ratchet is empty.',
+        );
+    }
+    try {
+        return parseBaselines(raw);
+    } catch {
+        throw new BaselineResolutionError(
+            `${relPath} at ${sha.slice(0, 9)} is not parseable JSON — refusing to continue ` +
+                'with an unknown policy.',
+        );
+    }
+}
+
+/**
+ * The merge-base reading, kept as a DIAGNOSTIC and never as the verdict.
+ *
+ * Both council seats asked for this explicitly. It does not decide pass/fail; it
+ * distinguishes two failures a reader cannot otherwise tell apart:
+ *
+ *   - `branch-regression` — the branch itself made the count worse. Fix the code.
+ *   - `main-tightened` — the branch is unchanged and `main` improved underneath
+ *     it. Rebase, then re-run.
+ *
+ * The distinction matters because the remediations differ, and one seat was
+ * pointed about the wording: "rebase and re-run" is incomplete advice for a PR
+ * that genuinely reintroduced violations, so a diagnostic must say which case it
+ * is rather than always suggesting a rebase.
+ */
+export type RegressionCause = 'branch-regression' | 'main-tightened' | 'none';
+
+export function diagnoseRegression(opts: {
+    actual: number;
+    targetBaseline: number;
+    mergeBaseBaseline: number | null;
+}): RegressionCause {
+    if (opts.actual <= opts.targetBaseline) return 'none';
+    if (opts.mergeBaseBaseline === null) return 'branch-regression';
+    // The branch is at or under the policy it branched from, and it still
+    // exceeds the target's policy: main tightened while this work was open.
+    return opts.actual <= opts.mergeBaseBaseline ? 'main-tightened' : 'branch-regression';
+}
+
 export interface RatchetOptions {
     /** Gate name — the key in the baseline file. */
     gate: string;
@@ -122,6 +244,12 @@ export interface RatchetOptions {
     baselineRel?: string;
     /** Override "now" as `YYYY-MM-DD` (tests); defaults to the current UTC date. */
     today?: string;
+    /**
+     * Read the governing baseline from this commit instead of the working tree.
+     * Defaults to `process.env[TARGET_REF_ENV]`; absent means a local run with
+     * no merge to judge, which is not the same as a failed resolution.
+     */
+    targetRef?: string;
 }
 
 /**
@@ -131,9 +259,30 @@ export interface RatchetOptions {
  * does not print or exit. A gate with no entry behaves exactly as it did before
  * the ratchet existed: any violation fails.
  */
+/**
+ * The env var that switches every ratchet onto the ABSOLUTE invariant at once.
+ *
+ * Set it to the target ref (`origin/main`, or the base SHA a PR job already
+ * knows) and all 18 `checkRatchet` call sites read the governing baseline from
+ * that commit instead of the working tree — no per-gate migration, no chance of
+ * migrating seventeen and forgetting one.
+ *
+ * **Unset is not a fallback.** A local run with no target configured has no
+ * merge to judge, so the working-tree read is the right and only answer there.
+ * What the council forbade is different and is honoured: a target that IS
+ * configured and fails to resolve throws, rather than quietly reverting to the
+ * working tree and changing the governing policy on an infrastructure error.
+ */
+export const TARGET_REF_ENV = 'GATE_BASELINE_TARGET_REF';
+
 export function checkRatchet(opts: RatchetOptions): BaselineVerdict {
     const { gate, actual } = opts;
-    const file = loadBaselines(opts.repoRoot, opts.baselineRel ?? BASELINE_REL);
+    const rel = opts.baselineRel ?? BASELINE_REL;
+    const target = opts.targetRef ?? process.env[TARGET_REF_ENV];
+    const file =
+        target !== undefined && target !== ''
+            ? loadBaselinesAt(opts.repoRoot, target, rel)
+            : loadBaselines(opts.repoRoot, rel);
     const entry = file.gates[gate];
 
     if (entry === undefined) {

package/src/scripts/_lib/generated_by.ts

@@ -0,0 +1,66 @@
+/**
+ * The attribution line a generated artifact carries.
+ *
+ * `road-to-consumer-repo-reality` Phase 1, step 1.4: "A generated file that
+ * names the script that wrote it becomes a lie the moment that script moves.
+ * Emit a stable, resolvable reference instead."
+ *
+ * IT ALREADY HAPPENED, which is why this module exists rather than a style
+ * note. Measured 2026-08-26 across `src/`, ten generated artifacts named their
+ * generator by literal path and **six of those paths did not resolve**:
+ *
+ *   scripts/audit_user_type_axis.py   scripts/adoption_report.py
+ *   scripts/skill_overlap.py          scripts/gen_discovery_baseline.py
+ *   scripts/generate_ownership_matrix.py
+ *   scripts/generate_pack_manifests.ts
+ *
+ * The first five were retired by the py2ts migration (ADR-200) and the sixth by
+ * the `scripts/` → `src/scripts/` move. Each artifact kept telling its reader to
+ * go look at a file that is not there — the same over-reporting failure Phase 1
+ * measures in consumer root instruction files, produced by this package's own
+ * generators.
+ *
+ * THE STABLE REFERENCE IS THE COMMAND, NOT THE PATH. A path is an
+ * implementation detail that a refactor moves; the command a human runs to
+ * regenerate is the thing that stays true, and it is also the only half of the
+ * attribution a reader can act on. Where no command exists, the generator's
+ * MODULE NAME is used — stable under a directory move, and greppable.
+ */
+
+/**
+ * `Generated by <ref>. Do not edit.` — with `ref` a command or a module name,
+ * never a path.
+ *
+ * @param ref     the regeneration command (`agent-config sync`, `task sync`) or
+ *                the generator's module name (`regenerate_index`). A value
+ *                containing a path separator is a bug this function refuses
+ *                rather than emits, because emitting it is exactly the defect.
+ * @param detail  optional trailing clause, e.g. a source description. No
+ *                timestamp: a regenerated timestamp makes every run a diff.
+ */
+export function generatedBy(ref: string, detail?: string): string {
+    if (ref.includes('/') || ref.includes('\\')) {
+        throw new Error(
+            `generatedBy: "${ref}" contains a path separator. The attribution must be a command or a ` +
+                'module name — a literal path becomes wrong the moment the file moves, which is the ' +
+                'defect this helper exists to prevent (road-to-consumer-repo-reality 1.4).',
+        );
+    }
+    const tail = detail === undefined || detail.trim() === '' ? '' : ` ${detail.trim()}`;
+    return `Generated by \`${ref}\`. Do not edit.${tail}`;
+}
+
+/** The same line as a markdown blockquote, the shape most emitters use. */
+export function generatedByQuote(ref: string, detail?: string): string {
+    return `> ${generatedBy(ref, detail)}`;
+}
+
+/** The same line as an italic footer, for artifacts that use one. */
+export function generatedByItalic(ref: string, detail?: string): string {
+    return `_${generatedBy(ref, detail)}_`;
+}
+
+/** The same line as a `#` comment, for YAML and INI-shaped output. */
+export function generatedByComment(ref: string, detail?: string): string {
+    return `# ${generatedBy(ref, detail)}`;
+}

package/src/scripts/_lib/harness_evolution_guards.ts

@@ -0,0 +1,229 @@
+/**
+ * Pre-registered guards for the governed harness-evolution programme.
+ *
+ * `road-to-governed-harness-evolution` Phase 0, steps 0.4, 0.5 and 0.6. All
+ * three are PRE-REGISTRATION: the runner they guard does not exist yet (Phases
+ * 1-7 are unbuilt), and that is the point — a budget invariant written after
+ * the first run is a description of what was spent, and a leakage abort written
+ * after the first leak is a post-mortem.
+ *
+ * The three guards, and the failure each exists to make impossible:
+ *
+ *   0.4 EVALUATOR TRUST BOUNDARY. The parent design named which fields are
+ *       proposer-visible and which are evaluator-private, and stopped at the
+ *       naming. A declared boundary that nothing checks is a boundary that
+ *       holds until the first convenient exception. {@link discloseToProposer}
+ *       refuses a holdout field and records every field it did release.
+ *
+ *   0.5 BUDGET INVARIANT. Candidate count, trial repetitions and a spend
+ *       ceiling, fixed BEFORE the run and aborting rather than truncating. A
+ *       truncated run yields `underpowered`, which `paired_verdict` refuses to
+ *       call a pass (`_lib/paired_verdict.ts:26`) and which a reader mistakes
+ *       for one.
+ *
+ *   0.6 EPISTEMIC STOP CONDITIONS. A spend cap stops on cost; most of the
+ *       reasons to stop are about VALIDITY. Each condition below carries a
+ *       detector or is explicitly marked model-carried — never implied to be
+ *       checked when it is not.
+ *
+ * Nothing here spends, fetches, or writes. The guards are pure functions over
+ * declared state so a future runner can call them before it does any of those.
+ */
+
+/**
+ * What a field may be shown to.
+ *
+ * `holdout` is the load-bearing member: it names a value whose disclosure
+ * INVALIDATES the run rather than merely leaking information, which is why
+ * {@link discloseToProposer} aborts on it instead of redacting.
+ */
+export type VisibilityClass =
+    /** The proposer may read it. Candidate text, public metric names, the task. */
+    | 'proposer-visible'
+    /** The evaluator reads it; the proposer never does. Per-trial raw scores. */
+    | 'evaluator-private'
+    /** Sealed-partition truth. Disclosure invalidates the run, not just the trial. */
+    | 'holdout';
+
+/** One observation field and the boundary it sits behind. */
+export interface FieldVisibility {
+    readonly field: string;
+    readonly visibility: VisibilityClass;
+}
+
+/** A field released to a proposer, with the class it was released under. */
+export interface DisclosureRecord {
+    readonly field: string;
+    readonly visibility: VisibilityClass;
+}
+
+export class HoldoutLeakError extends Error {
+    readonly field: string;
+    constructor(field: string) {
+        super(
+            `holdout leakage: field '${field}' is class 'holdout' and reached proposer context. ` +
+                'The run is INVALID, not degraded — a proposer that has seen sealed truth cannot ' +
+                'be evaluated against it, and no later stage can undo that. Abort, do not redact.',
+        );
+        this.name = 'HoldoutLeakError';
+        this.field = field;
+    }
+}
+
+/**
+ * Release an observation to a proposer, recording every field released.
+ *
+ * Fails CLOSED on an undeclared field: a field with no `visibility_class` is
+ * treated as `holdout`, because the alternative — defaulting to visible —
+ * makes forgetting to classify a new field silently equivalent to publishing
+ * it. Step 0.4's whole subject is that a declared boundary nothing checks is
+ * not a boundary.
+ *
+ * @throws {HoldoutLeakError} on the first holdout or undeclared field.
+ */
+export function discloseToProposer(
+    observation: Readonly<Record<string, unknown>>,
+    schema: readonly FieldVisibility[],
+    log: DisclosureRecord[],
+): Record<string, unknown> {
+    const byField = new Map(schema.map((f) => [f.field, f.visibility]));
+    const out: Record<string, unknown> = {};
+    for (const field of Object.keys(observation)) {
+        const visibility = byField.get(field) ?? 'holdout';
+        if (visibility === 'holdout') throw new HoldoutLeakError(field);
+        if (visibility !== 'proposer-visible') continue;
+        log.push({ field, visibility });
+        out[field] = observation[field];
+    }
+    return out;
+}
+
+/** The budget fixed before a run. Every field is a ceiling, never a target. */
+export interface RunBudget {
+    readonly maxCandidates: number;
+    readonly maxTrialsPerCandidate: number;
+    /** Spend ceiling in whole cents, so no float ever decides an abort. */
+    readonly maxSpendCents: number;
+}
+
+/** What a run intends to do, as declared before it starts. */
+export interface RunPlan {
+    readonly candidates: number;
+    readonly trialsPerCandidate: number;
+    readonly estimatedSpendCents: number;
+}
+
+export class BudgetExceededError extends Error {
+    readonly dimension: 'candidates' | 'trials' | 'spend';
+    constructor(dimension: 'candidates' | 'trials' | 'spend', planned: number, ceiling: number) {
+        super(
+            `budget invariant: planned ${dimension} ${String(planned)} exceeds the pre-registered ` +
+                `ceiling ${String(ceiling)}. ABORTING BEFORE THE RUN, not truncating it — a ` +
+                'truncated run yields `underpowered`, which paired_verdict refuses to call a pass ' +
+                'and which a reader mistakes for one.',
+        );
+        this.name = 'BudgetExceededError';
+        this.dimension = dimension;
+    }
+}
+
+/**
+ * Check a plan against the pre-registered budget, BEFORE anything is spent.
+ *
+ * The order is deliberate — candidates, then trials, then spend. The first two
+ * are free to check and the third is the one an operator argues about; failing
+ * on a countable dimension first makes the message actionable without any
+ * pricing discussion.
+ *
+ * @throws {BudgetExceededError} on the first dimension over its ceiling.
+ */
+export function assertWithinBudget(plan: RunPlan, budget: RunBudget): void {
+    if (plan.candidates > budget.maxCandidates) {
+        throw new BudgetExceededError('candidates', plan.candidates, budget.maxCandidates);
+    }
+    if (plan.trialsPerCandidate > budget.maxTrialsPerCandidate) {
+        throw new BudgetExceededError('trials', plan.trialsPerCandidate, budget.maxTrialsPerCandidate);
+    }
+    if (plan.estimatedSpendCents > budget.maxSpendCents) {
+        throw new BudgetExceededError('spend', plan.estimatedSpendCents, budget.maxSpendCents);
+    }
+}
+
+/**
+ * A stop condition, and whether anything actually checks it.
+ *
+ * `detector: null` means MODEL-CARRIED and is written out rather than left to
+ * inference. This repository's own records name the coverage-inflation failure
+ * — a condition listed as if it were enforced when nothing enforces it — often
+ * enough that the honest field is cheaper than the audit that finds it later.
+ */
+export interface StopCondition {
+    readonly id: string;
+    readonly why: string;
+    /** The exported detector's name, or `null` for model-carried. */
+    readonly detector: string | null;
+}
+
+/**
+ * The four epistemic stop conditions, from the roadmap's step 0.6.
+ *
+ * Both parent designs carried eight or nine stop conditions; the master
+ * compressed them into the budget cap. A spend cap stops on COST, and these
+ * stop on VALIDITY — stopping with INDETERMINATE is a valid result, and an
+ * honest null is a success when it prevents unnecessary architecture.
+ */
+export const STOP_CONDITIONS: readonly StopCondition[] = [
+    {
+        id: 'holdout-underpowered',
+        why: 'the sealed partition no longer carries enough discordant trials for the exact sign test to resolve, so every verdict it produces is `underpowered` by construction',
+        detector: 'holdoutUnderpowered',
+    },
+    {
+        id: 'evaluator-leakage',
+        why: 'a holdout field reached proposer context; the run is invalid rather than degraded, and no later stage can undo it',
+        detector: 'discloseToProposer',
+    },
+    {
+        id: 'diversity-collapse',
+        why: 'the candidate set has collapsed to semantic duplicates, so the trials measure sampling noise rather than a difference between candidates',
+        detector: 'diversityCollapsed',
+    },
+    {
+        id: 'cross-component-interference',
+        why: 'two components changed in one run and credit cannot be assigned to either',
+        // Honest null: deciding whether two changes interfere needs a causal
+        // model of the components, and this programme has none. Marked
+        // model-carried rather than given a detector that would pattern-match
+        // on file paths and report confidence it does not have.
+        detector: null,
+    },
+];
+
+/**
+ * Has the candidate set collapsed to semantic duplicates?
+ *
+ * Deterministic and deliberately crude: normalise, then count DISTINCT
+ * candidates. Below `minDistinct` the set is collapsed. No embedding, no model
+ * call — a detector that needs a model to decide whether to stop a model run is
+ * a detector that can fail in the same way as the thing it watches.
+ *
+ * Normalisation is case- and whitespace-folding only. Two candidates differing
+ * by a synonym read as distinct here, which UNDER-detects; that direction is
+ * chosen on purpose, because a false stop discards a valid run while a missed
+ * stop is caught by the verdict coming back `no-change`.
+ */
+export function diversityCollapsed(candidates: readonly string[], minDistinct = 2): boolean {
+    const normalised = new Set(candidates.map((c) => c.trim().toLowerCase().replace(/\s+/g, ' ')));
+    return normalised.size < minDistinct;
+}
+
+/**
+ * Is the holdout partition too small for the exact sign test to resolve?
+ *
+ * Mirrors `paired_verdict`'s own floor rather than restating a number:
+ * `MIN_DISCORDANT` there is DERIVED from the exact test at ALPHA, not chosen,
+ * so a second hard-coded constant here would be a fork of a derivation.
+ */
+export function holdoutUnderpowered(discordantTrials: number, minDiscordant: number): boolean {
+    return discordantTrials < minDiscordant;
+}

package/src/scripts/_lib/hook_effect_probe.ts

@@ -0,0 +1,141 @@
+/**
+ * Does any of this configuration take effect here?
+ * (`road-to-delivered-cost-truth` Phase 3.)
+ *
+ * `doctorShell` states its own scope: Node version, package-root resolution,
+ * whether the Bash dispatcher exists. That is an ENVIRONMENT probe. It cannot
+ * answer whether a bound hook actually fires on this host — which is the
+ * question that decides whether any of the configuration this suite ships is
+ * doing anything here.
+ *
+ * FIVE STATES, NOT FOUR. The roadmap named four binding states; both council
+ * seats (2026-08-28, 2/2, resolving `how-far-the-effect-probe-may-reach` as
+ * option (c)) split one of them, and the split is real:
+ *
+ *   effective        fired, and a deny would have been honoured
+ *   bound-discarded  fired, and the host discards its output
+ *   bound-not-fired  the manifest binds it, and no dispatch was observed
+ *   unbound          the manifest does not bind it on this host
+ *   unknown          it was not safe to probe
+ *
+ * `bound-not-fired` and `unknown` were one bucket in the four-state model, and
+ * collapsing them hides the difference between "the host ignored it" and "we
+ * declined to look".
+ *
+ * ELIGIBILITY IS MEASURED, NOT DECLARED. Option (c) as written restricts
+ * dispatch to concerns that DECLARE themselves side-effect free, and both seats
+ * then said the same thing from different directions: a self-declared property
+ * nothing verifies is a weak control this repository flags as a defect
+ * elsewhere, and the dispatch should be sandboxed even for declared-safe
+ * concerns. Taken together that makes the declaration redundant — so this module
+ * measures the property instead: run the concern against a scratch root, compare
+ * the tree before and after, and treat any write as ineligible. A concern that
+ * writes is reported `unknown`, which is the honest answer and never a success.
+ *
+ * `unknown` IS NEVER RENDERED AS `effective`. That is the one rule every seat
+ * stated independently, and it is what the three coverage metrics exist to keep
+ * visible: a report can be truthful about each concern and still mislead, if
+ * almost nothing was actually probed.
+ */
+
+export const PROBE_STATES = ['effective', 'bound-discarded', 'bound-not-fired', 'unbound', 'unknown'] as const;
+export type ProbeState = (typeof PROBE_STATES)[number];
+
+/** The verdict a whole host gets. */
+export const HOST_VERDICTS = ['effective', 'partial', 'inert', 'unknown'] as const;
+export type HostVerdict = (typeof HOST_VERDICTS)[number];
+
+export interface ConcernProbe {
+    concern: string;
+    slot: string;
+    state: ProbeState;
+    /** Always populated — for `unknown` it is the reason the probe declined. */
+    reason: string;
+    /** Did the sandbox observe a write? `null` when no dispatch was attempted. */
+    wrote_in_sandbox: boolean | null;
+}
+
+export interface Coverage {
+    /** dispatched / total — tests the control itself. */
+    dispatch_rate: number;
+    /** non-unknown / total — where an answer exists at all. */
+    known_state_rate: number;
+    /** (effective + bound-discarded) / total — actual observed confidence. */
+    verified_rate: number;
+}
+
+export interface HostReport {
+    host: string;
+    probes: ConcernProbe[];
+    coverage: Coverage;
+    verdict: HostVerdict;
+    /** For `partial`, the slots that are inert. Empty otherwise. */
+    inert_slots: string[];
+    reason: string;
+}
+
+function rate(n: number, d: number): number {
+    return d === 0 ? 0 : n / d;
+}
+
+export function coverageOf(probes: readonly ConcernProbe[]): Coverage {
+    const total = probes.length;
+    const dispatched = probes.filter((p) => p.wrote_in_sandbox !== null).length;
+    const known = probes.filter((p) => p.state !== 'unknown').length;
+    const verified = probes.filter((p) => p.state === 'effective' || p.state === 'bound-discarded').length;
+    return {
+        dispatch_rate: rate(dispatched, total),
+        known_state_rate: rate(known, total),
+        verified_rate: rate(verified, total),
+    };
+}
+
+/**
+ * One verdict for the host.
+ *
+ * The ordering is the honesty: `unknown` is checked BEFORE `effective`, so a run
+ * that could not establish anything can never present itself as a working
+ * configuration. A single `effective` among a hundred `unknown`s is `unknown`,
+ * not `partial` — because the hundred were not measured, and `partial` is a
+ * claim about what IS inert rather than about what was not looked at.
+ */
+export function hostVerdict(probes: readonly ConcernProbe[]): { verdict: HostVerdict; inert: string[]; reason: string } {
+    if (probes.length === 0) {
+        return { verdict: 'unknown', inert: [], reason: 'no concern is bound on this host, so there is nothing to probe' };
+    }
+    const known = probes.filter((p) => p.state !== 'unknown');
+    if (known.length === 0) {
+        return {
+            verdict: 'unknown',
+            inert: [],
+            reason: `none of the ${String(probes.length)} bound concern(s) could be probed safely — no state was established`,
+        };
+    }
+    const effective = known.filter((p) => p.state === 'effective');
+    const inertProbes = known.filter((p) => p.state === 'bound-discarded' || p.state === 'bound-not-fired' || p.state === 'unbound');
+    const inert = [...new Set(inertProbes.map((p) => p.slot))].sort();
+
+    if (effective.length === 0) {
+        return {
+            verdict: 'inert',
+            inert,
+            reason: `no probed concern reached the model on this host (${String(known.length)} of ${String(probes.length)} probed)`,
+        };
+    }
+    if (inertProbes.length === 0 && known.length === probes.length) {
+        return { verdict: 'effective', inert: [], reason: `every bound concern (${String(probes.length)}) took effect` };
+    }
+    return {
+        verdict: 'partial',
+        inert,
+        reason:
+            `${String(effective.length)} of ${String(probes.length)} bound concern(s) took effect; ` +
+            `inert slot(s): ${inert.length === 0 ? 'none' : inert.join(', ')}` +
+            (known.length < probes.length ? ` · ${String(probes.length - known.length)} could not be probed` : ''),
+    };
+}
+
+export function buildHostReport(host: string, probes: readonly ConcernProbe[]): HostReport {
+    const v = hostVerdict(probes);
+    return { host, probes: [...probes], coverage: coverageOf(probes), verdict: v.verdict, inert_slots: v.inert, reason: v.reason };
+}