create-agent-rig 0.8.0 → 0.9.0

package/packages/cli/dist/policy/core/evidence-matrix.js

@@ -0,0 +1,94 @@
+/**
+ * The capability evidence matrix (RP-36, absorbing the discovery component of
+ * the item it supersedes): one row per concrete harness surface, saying what
+ * was observed, on exactly which version, when, and where the proof is.
+ *
+ * The rule that gives the matrix its value is that its validator refuses an
+ * incomplete row: a row without an exact version or an observed
+ * date-time reads like evidence and is not one, because neither "which build
+ * was this" nor "was this before or after the change" can be answered from it.
+ * This module owns validation only; a caller that persists rows owns storage.
+ * Both halves are checked — `packages/cli/test/policy-coverage.test.ts` ›
+ * "refuses the harness version %j, because it names a range or a moving target
+ * rather than a build" and › "refuses an observedAt that is not an ISO-8601
+ * date-time with a zone (%j)". Documentation claims are not rows; a row records
+ * live behaviour that was seen.
+ *
+ * A row whose status is anything but `SUPPORTED` must say why, and a
+ * `SUPPORTED` row must not — the shape is closed in both directions, per ›
+ * "refuses a %s row that does not say why it is not supported".
+ *
+ * Every field of the shape is checked and every problem is reported at once,
+ * the way `./declaration.ts` does it, so a caller fixes a row in one pass: ›
+ * "reports every problem at once rather than stopping at the first".
+ *
+ * Why the row is shaped this way, and what it deliberately does not check, is
+ * `docs/decisions/capability-coverage.md`.
+ */
+import { CAPABILITY_STATES } from './vocabulary.js';
+import { carriesField, exactVersion, ISO_8601, isRecord, matching, member, nonBlankString, ownField, unknownKeys, } from './validation.js';
+const KEYS = [
+    'harness',
+    'surface',
+    'harnessVersion',
+    'os',
+    'observedAt',
+    'mechanism',
+    'observableSignal',
+    'status',
+    'downgradeReason',
+    'evidencePointer',
+];
+const REQUIRED_TEXT = [
+    'harness',
+    'surface',
+    'harnessVersion',
+    'os',
+    'mechanism',
+    'observableSignal',
+    'evidencePointer',
+];
+/** Validate an unknown value as one matrix row, reporting every problem at once. */
+export function validateEvidenceRow(input) {
+    if (!isRecord(input)) {
+        return { ok: false, problems: [{ field: '', message: 'an evidence row is an object' }] };
+    }
+    const problems = [];
+    unknownKeys(problems, input, KEYS);
+    // EVERY field is read through `ownField`, not off the record directly. A row
+    // is evidence only insofar as it CARRIES what it was validated on: a value
+    // reached through the prototype chain, or held in a non-enumerable own
+    // property, validates and then serialises to nothing — "a row that reads like
+    // evidence and is not one", which is the shape this module exists to refuse.
+    // `unknownKeys` already judges the row by `Object.keys`, and `ownField` is
+    // that same notion, so the closed-shape check and the field reads cannot
+    // disagree about what the row contains.
+    for (const field of REQUIRED_TEXT)
+        nonBlankString(problems, field, ownField(input, field));
+    exactVersion(problems, 'harnessVersion', ownField(input, 'harnessVersion'));
+    matching(problems, 'observedAt', ownField(input, 'observedAt'), ISO_8601, 'an ISO-8601 date-time with a zone');
+    const status = ownField(input, 'status');
+    const known = member(problems, 'status', status, CAPABILITY_STATES);
+    const carriesReason = carriesField(input, 'downgradeReason');
+    if (known && status !== 'SUPPORTED') {
+        if (carriesReason)
+            nonBlankString(problems, 'downgradeReason', ownField(input, 'downgradeReason'));
+        else
+            problems.push({ field: 'downgradeReason', message: 'must be a non-blank string' });
+    }
+    // The shape is closed in both directions: a supported row has no reason to
+    // give, so a `downgradeReason` on one is refused rather than ignored. Left
+    // unchecked, the field went unvalidated on that branch and the narrowing
+    // below handed back a value typed `string` that was not one.
+    if (known && status === 'SUPPORTED' && carriesReason) {
+        problems.push({
+            field: 'downgradeReason',
+            message: 'a SUPPORTED row has nothing to explain, so it carries no downgrade reason',
+        });
+    }
+    if (problems.length > 0)
+        return { ok: false, problems };
+    // Every field above was checked against the shape, so the narrowing is the
+    // type the checks just established rather than an assertion over them.
+    return { ok: true, value: input };
+}

package/packages/cli/dist/policy/core/probe.js

@@ -0,0 +1,442 @@
+/**
+ * The capability probe (RP-36): given a declaration, a harness adapter and
+ * that surface's hook-wiring snapshot, what can this surface actually enforce?
+ *
+ * ONE active read of a snapshot the caller supplies. This module cannot fetch
+ * one, which bounds what IT does — it does not, on its own, stop a caller
+ * looping it, and the header of an earlier draft claimed otherwise. What
+ * records the occasion of a probe is `./coverage.ts`, whose `coverageFromProbe`
+ * requires a `ProbeTrigger` and refuses a word outside that vocabulary:
+ * `policy-coverage.test.ts` › "refuses the trigger %j, because the coverage
+ * contract accepts only a declared surface-change trigger".
+ *
+ * The four answers, each pinned in `packages/cli/test/policy-coverage.test.ts`:
+ *
+ * | input | answer | pinned by |
+ * | --- | --- | --- |
+ * | a group naming exactly the declared tools and RUNNING the hook | `SUPPORTED` | › "reads the real %s command as running the hook, because it is what the rig really ships" |
+ * | the hook run under that event, but by no group naming exactly those tools | `DEGRADED` | › "reads a wiring that drops a declared tool as DEGRADED, naming the tool that is missing" |
+ * | a readable snapshot that runs the hook nowhere under that event | `UNSUPPORTED` | › "reads a hook wired nowhere under the policy event as UNSUPPORTED, naming the hook path" |
+ * | a snapshot, or any level of wiring under it, in a shape this module cannot read | `INTEGRATION-FAILED` | › "reports INTEGRATION-FAILED when %s, naming the event it could not read" |
+ *
+ * 🔴 The last two rows are a distinction, not a duplicate, and collapsing them
+ * costs something in each direction. `rules/invariants.md` states the rule
+ * under "Refusing to inspect is a third outcome": a field that is simply
+ * ABSENT leaves nothing to judge, while a field PRESENT in an unreadable shape
+ * is exactly the case worth reporting. Read as one, either an honest absence
+ * becomes a false alarm or an unreadable surface becomes a quiet, uncounted
+ * zero — the second being the shape a past guard here actually shipped. The
+ * costly case is an element BESIDE a valid group whose STRUCTURE cannot be
+ * read, held by › "does not report SUPPORTED when an unreadable element sits
+ * beside a valid group, because that is a partial read". ⚠ That is the
+ * structural level only. A readable command that merely names the hook in an
+ * unverified spelling does NOT outrank a group carrying the generated command:
+ * a hook list is conjunctive, so an entry the probe could not verify cannot
+ * un-run one it did verify, and the surface reads `SUPPORTED`.
+ *
+ * Neither weak answer passes silently on the path this module's own callers
+ * take: `./coverage.ts` › `qualifierFor` maps both to `UNVERIFIABLE`, and
+ * `./decision-record.ts` refuses a record carrying either state with an
+ * unqualified verdict — › "refuses the silent pass an unwired surface would
+ * otherwise produce, and accepts it once qualifierFor speaks".
+ *
+ * ⚠ That used to be a claim about records built the ordinary way, narrower than
+ * "by construction", because `./decision-record.ts` decided whether a verdict
+ * carries a qualifier with `in` — a verdict object INHERITING one satisfied the
+ * check and then serialised without it. RP-153 brought that reader, and
+ * `./declaration.ts`, onto the same own-and-enumerable rule this module and
+ * `./evidence-matrix.ts` already used, so the gap this paragraph named is
+ * closed. `docs/decisions/capability-coverage.md` records the limits that
+ * remain — an accessor read twice (RP-157), and an array hole that serialises
+ * as `null` and is read by nothing (RP-161). A contract that claims cover it
+ * does not have is worse than one that names the gap, which is why this
+ * paragraph is corrected rather than deleted.
+ *
+ * The rationale, including what this deliberately does not do, is
+ * `docs/decisions/capability-coverage.md`.
+ */
+import { carriesField, isRecord, ownField, quote } from './validation.js';
+/**
+ * The longest hook command this module will parse.
+ *
+ * A command comes off a file on disk, and every line of work done on untrusted
+ * input in a module whose callers fail open is a line that can be made
+ * expensive (`rules/invariants.md`, "A guard that fails open must do provably
+ * bounded work"). Past the cap the command is not read at all, and the refusal
+ * reads `INTEGRATION-FAILED` — not `UNSUPPORTED`, because a command nobody
+ * looked at is not evidence that the mechanism is absent. An earlier version of
+ * this sentence said the opposite of the code, which is the sentence a
+ * maintainer would read before "simplifying" the branch back into the silent
+ * absence this design removed: › "refuses a command one byte over the cap
+ * rather than reading it, even though it names no hook".
+ *
+ * The margin, measured rather than asserted over every wiring snapshot this
+ * rig ships: the longest command in any of them is 131 bytes, so 4096 is ~31x
+ * the longest. An earlier draft of
+ * this comment claimed "two orders of magnitude", which was wrong by 3x and
+ * which nothing checked — the cited test pins that the cap ADMITS the shipped
+ * commands, not any ratio: › "states its command-length cap as a whole number,
+ * and one that admits the commands the rig ships".
+ */
+export const MAX_HOOK_COMMAND_LENGTH = 4096;
+/**
+ * How many tool names a reason may list before it says "and N more".
+ *
+ * The names come out of the snapshot's own matcher, so an unbounded join is
+ * both unbounded work and an unbounded string in an operator's terminal: ›
+ * "keeps the reason short when a thousand tools are added, and says how many it
+ * did not name".
+ */
+export const MAX_NAMED_TOOLS_IN_REASON = 5;
+/**
+ * How much STRUCTURE this module will read before it refuses to read any.
+ *
+ * 🔴 Capping each command's length bounded the wrong axis alone. A snapshot is
+ * outside data, and its cardinalities were the caller's to choose: a hundred
+ * thousand groups, each carrying a hundred thousand hooks, is a snapshot whose
+ * every command is inside the length cap and whose total work is bounded by
+ * nothing. `rules/invariants.md` ("A guard that fails open must do provably
+ * bounded work") makes that the whole test — not "is it fast on realistic
+ * input" but "can any input make it do unbounded work at all" — and a consumer
+ * of this answer reads an absent verdict as no finding, so exhausting this
+ * module is a way to be reported on by nobody.
+ *
+ * Each cap is checked BEFORE the level it bounds is walked, and each refusal is
+ * `INTEGRATION-FAILED` naming the number crossed — never `UNSUPPORTED`, because
+ * a level nobody walked is not evidence that the mechanism is absent. That is
+ * the rule the over-long command already follows.
+ *
+ * A cap must admit the wiring this rig really ships, and that is asserted where
+ * the shipped file is actually opened rather than described here. Two tests, and
+ * the difference between them is the point: `test/template/policy-coverage.test.ts`
+ * (absent in a generated rig) › "keeps every level of the %s wiring this rig
+ * ships inside the caps the probe will read" reads each adapter's own surface
+ * file and measures its group, hook and matcher sizes against these three
+ * numbers, so a shipped surface file that grows past one of them goes red;
+ * `packages/cli/test/policy-coverage.test.ts` › "admits every level of the %s
+ * wiring this rig really ships, so no cap refuses honest work" makes the same
+ * assertion over the REGISTRY-DERIVED fixture, which is narrower and cannot
+ * stand in for the file. An earlier version of this paragraph quoted the three
+ * measured sizes and cited only the second test — a figure nothing regenerates,
+ * pointing at a test that never opens the thing it described.
+ *
+ * This module cannot name a surface file itself, and
+ * `test/template/policy-declaration.test.ts` › "no file under src/policy/core
+ * mentions a harness, a vendor, a native tool or a native path" is what stops it
+ * trying. The refusal direction is held in the unit file,
+ * `packages/cli/test/policy-coverage.test.ts` › "refuses a snapshot carrying
+ * one group more than it will read, naming the limit it crossed".
+ *
+ * ⚠ `MAX_MATCHER_LENGTH` is NOT set from the longest matcher this rig ships,
+ * which is far shorter. A cap is a promise about what
+ * this module still reads, and the contract had already made a wider one: ›
+ * "keeps the reason short when a thousand tools are added, and says how many it
+ * did not name" hands the probe a 4,935-character matcher and requires a
+ * `DEGRADED` answer with a bounded reason. Setting the cap below that would
+ * have turned an answer the suite already demands into a refusal — a cap
+ * chosen from the typical size rather than from the promise, which is how a
+ * bound quietly becomes a behaviour change. 8192 is the first power of two
+ * above what is already read.
+ *
+ * The work that admits is still bounded, and the product is what matters rather
+ * than any one factor: at most `MAX_HOOK_GROUPS` × `MAX_HOOKS_PER_GROUP` hook
+ * entries are classified, each against a fixed number of adapter fields capped
+ * at `MAX_HOOK_COMMAND_LENGTH`, and each group's matcher yields at most
+ * `MAX_MATCHER_LENGTH / 2` tools compared against a declaration of a handful.
+ */
+export const MAX_HOOK_GROUPS = 64;
+export const MAX_HOOKS_PER_GROUP = 64;
+export const MAX_MATCHER_LENGTH = 8192;
+/** One horizontal tab, named so no source line carries an invisible one. */
+const TAB = String.fromCharCode(9);
+/**
+ * The command as a shell would word it, for comparison only.
+ *
+ * Runs of spaces and tabs collapse to one space, and a single leading or
+ * trailing space is then dropped. Those two are the whole tolerance — stated
+ * together because an omitted one is as misleading as an invented one, and the
+ * trim was missing from the first version of this paragraph. Space and tab are
+ * the only default IFS
+ * characters that separate WORDS without separating COMMANDS. A newline does
+ * separate commands — `node` on one line and the hook path on the next is two
+ * commands, the second executing the hook file directly — so collapsing it
+ * would manufacture a match against the generated string and hand back the one
+ * answer this module must never give without evidence. The same holds for
+ * carriage return, vertical tab, form feed and a non-breaking space, none of
+ * which a shell splits words on at all.
+ *
+ * Pinned in `packages/cli/test/policy-coverage.test.ts` (absent in a generated
+ * rig) › "still reads a %s wiring with %s as SUPPORTED, because a shell
+ * separates words on both" and, in the other direction, › "refuses a %s wiring
+ * whose spaces became %s, because a shell does not separate words on it".
+ */
+const normalise = (command) => 
+// The tab is split out rather than matched: a literal tab inside a character
+// class is a control character to a regular expression, which `no-control-regex`
+// refuses - and rightly, because it is invisible to a reader.
+command.split(TAB).join(' ').replace(/ +/g, ' ').replace(/^ | $/g, '');
+/**
+ * Classify one hook entry by comparing every command the harness generates for
+ * this hook against the field it belongs to — never by parsing any of them.
+ *
+ * 🔴 This replaced a partial shell parser, and the reason is worth keeping
+ * because it was expensive to learn. Three gate rounds tried to decide "does
+ * this command execute the hook?" by reading shell syntax. Each round closed a
+ * class of false `SUPPORTED` and opened a new one: a `.bak` neighbour, then a
+ * conditional `&&` segment, then a quoted mention the splitter cut through,
+ * then an unterminated quote, a mismatched brace, a backgrounding `&` on a
+ * later segment, and finally an assignment whose command substitution can fail
+ * — which cannot be refused, because it is the shape this rig's own derived
+ * command uses. The input surface was the whole shell grammar and the error
+ * was asymmetric, so a partial parser could not win.
+ *
+ * The rig GENERATES its own wiring, so the probe compares against what it
+ * would generate. There is no grammar left to lose to.
+ *
+ * EVERY declared field must match, because a surface can run a different
+ * spelling per platform: reading only the first left a guard that had been
+ * replaced on one platform reading as enforced on all of them.
+ *
+ * The substring test survives, and its FAILURE DIRECTION is what makes that
+ * safe: it now only chooses between `INTEGRATION-FAILED` and `UNSUPPORTED` —
+ * two non-passing answers — so a false positive can no longer reach
+ * `SUPPORTED`. That inversion is the design: › "never reaches SUPPORTED from a
+ * mere mention of the hook path, whichever spelling the mention takes".
+ *
+ * ⚠ What it costs, stated because it is a real loss: a hand-written wiring
+ * that genuinely runs the hook — a bare `node <hookPath>`, a flag before the
+ * path, a different spelling of the same variable — is `INTEGRATION-FAILED`
+ * rather than `SUPPORTED`. That is "I cannot verify this" in place of a
+ * confident answer, which is the direction this contract is required to err
+ * in, but a rig wiring its hooks by hand will read as unverifiable.
+ *
+ * Over the length cap a command is not read at all: refusing to inspect is a
+ * third outcome, and a guard that did not look may not report that it found
+ * nothing (`rules/invariants.md`, "Refusing to inspect is a third outcome, not
+ * a match and not an error"). An adapter that generates NO command is the same
+ * outcome for the same reason — there is nothing to compare against, so there
+ * is nothing verified — but it carries its OWN cause and its own sentence,
+ * because the fault is in the adapter rather than in the surface being read: ›
+ * "refuses %s under a matcher that matches the declaration exactly, because
+ * there was nothing to compare it against", with the two refusals held apart
+ * by › "does not borrow the sentence of a wiring that really did name the
+ * hook, which still gets it".
+ */
+const classify = (entry, surface) => {
+    const fields = Object.keys(surface.commands);
+    // An adapter that generates no command names nothing to compare against, and
+    // `matched` starts true — so without this, EVERY hook entry, including an
+    // empty one, ran the loop zero times and came back as running the hook. A
+    // surface whose adapter says nothing about what it would generate is one this
+    // module can verify nothing about, which is `INTEGRATION-FAILED`, never a
+    // pass. The two shipped adapters both declare commands, so nothing today
+    // takes this branch; the type admits `{}` and adding an adapter is a
+    // documented extension point, which is how a new adapter would have been
+    // handed "every policy enforced" for free.
+    //
+    // 🔴 Its own cause, not a borrowed one. The first version returned
+    // `'spelling'`, which made the refusal say "something under <event> names
+    // <hookPath>" for a hook entry of `{}` — nothing named anything, and
+    // `mentions` had not even been computed. That is the failure this union
+    // exists to prevent, stated above and again at the ladder below, and both
+    // reviewers found it in the same round. The defect is also in the ADAPTER
+    // rather than the surface, and the sentence has to say so, or an operator
+    // goes looking through a wiring file that is fine.
+    if (fields.length === 0)
+        return { kind: 'unreadable', cause: 'nothing-generated' };
+    let matched = true;
+    let mentions = false;
+    for (const field of fields) {
+        const wired = entry[field] ?? '';
+        if (wired.length > MAX_HOOK_COMMAND_LENGTH)
+            return { kind: 'unreadable', cause: 'oversize' };
+        const generated = surface.commands[field] ?? [];
+        if (!generated.some((spelling) => normalise(spelling) === normalise(wired)))
+            matched = false;
+        if (wired.includes(surface.hookPath))
+            mentions = true;
+    }
+    if (matched)
+        return { kind: 'runs' };
+    return mentions ? { kind: 'unreadable', cause: 'spelling' } : { kind: 'unrelated' };
+};
+const toolsOf = (matcher) => matcher.split('|').filter((tool) => tool !== '');
+const sameTools = (declared, wired) => declared.length === wired.length && declared.every((tool) => wired.includes(tool));
+/** What the declaration names and the wiring does not, and the reverse. */
+const differenceOf = (declared, wired) => ({
+    missing: declared.filter((tool) => !wired.includes(tool)),
+    extra: wired.filter((tool) => !declared.includes(tool)),
+});
+/**
+ * Name a bounded number of tools, each escaped.
+ *
+ * Both properties are required of a string assembled from a matcher that came
+ * off disk: bounded, or one probe produces a megabyte of diagnostic; escaped,
+ * or a segment carrying a newline and an ANSI sequence forges a line of the
+ * report it appears in. Held by › "escapes a tool name carrying a newline and
+ * an ANSI sequence, so a matcher cannot forge a line of the report".
+ */
+const names = (tools) => {
+    const shown = tools.slice(0, MAX_NAMED_TOOLS_IN_REASON).map(quote).join(', ');
+    const unnamed = tools.length - MAX_NAMED_TOOLS_IN_REASON;
+    return unnamed > 0 ? `${shown}, and ${String(unnamed)} more` : shown;
+};
+const describeDifference = (missing, extra) => {
+    const parts = [];
+    if (missing.length > 0)
+        parts.push(`does not cover ${names(missing)}`);
+    if (extra.length > 0)
+        parts.push(`also covers ${names(extra)}, which the policy does not`);
+    return parts.join('; ');
+};
+const unreadable = (what) => ({
+    state: 'INTEGRATION-FAILED',
+    reason: `the surface snapshot could not be read: ${what}`,
+});
+/**
+ * Probe one policy against one surface's snapshot. Pure: the snapshot is the
+ * caller's to obtain, and `snapshot` is `unknown` on purpose — the shape is
+ * checked at every level rather than trusted, because a surface file is
+ * outside data and a level silently skipped is a partial read reported as a
+ * whole one.
+ */
+export function probePolicy(policy, adapter, snapshot) {
+    if (!isRecord(snapshot)) {
+        return unreadable('it is not an object carrying a hooks field');
+    }
+    // Every level below is read through `carriesField`/`ownField` rather than
+    // with `in` and a bracket read. A snapshot is outside data, and the question
+    // this module answers is what the SURFACE wires — so a value the surface's
+    // own serialisation would not carry is not wiring, whether it sits on a
+    // prototype or in a non-enumerable own property. Reading one as wiring
+    // reported a hook that serialises as `{}` as running the generated command,
+    // which is the false SUPPORTED this contract exists to make impossible.
+    if (carriesField(snapshot, 'hooks') && !isRecord(ownField(snapshot, 'hooks'))) {
+        return unreadable('its hooks field is not an object of event names');
+    }
+    const surface = adapter.nativeSurfaceOf(policy);
+    const hooksField = ownField(snapshot, 'hooks');
+    const wiring = isRecord(hooksField) ? hooksField : {};
+    // An event that is ABSENT contributes no groups and is not a finding; an
+    // event PRESENT in a shape this cannot read is the finding. An event key the
+    // record does not itself carry is the first of those, not the second.
+    const groups = [];
+    if (carriesField(wiring, surface.event)) {
+        const under = ownField(wiring, surface.event);
+        if (!Array.isArray(under)) {
+            return unreadable(`the value under ${surface.event} is not a list of groups`);
+        }
+        if (under.length > MAX_HOOK_GROUPS) {
+            return unreadable(`${surface.event} carries more than ${String(MAX_HOOK_GROUPS)} groups, so none of them was read`);
+        }
+        for (const group of under) {
+            if (!isRecord(group)) {
+                return unreadable(`a group under ${surface.event} is not an object`);
+            }
+            const groupHooks = ownField(group, 'hooks');
+            if (!Array.isArray(groupHooks)) {
+                return unreadable(`the hooks of a group under ${surface.event} are not a list`);
+            }
+            if (groupHooks.length > MAX_HOOKS_PER_GROUP) {
+                return unreadable(`a group under ${surface.event} carries more than ${String(MAX_HOOKS_PER_GROUP)} hooks, so none of them was read`);
+            }
+            const hooks = [];
+            for (const hook of groupHooks) {
+                if (!isRecord(hook)) {
+                    return unreadable(`a hook under ${surface.event} is not an object`);
+                }
+                // Every field this harness generates a command for has to be there and
+                // be a string. An absent one is not an honest absence: the harness
+                // writes them all, so a hook missing one is a wiring this module
+                // cannot vouch for on the platform that field serves.
+                const entry = {};
+                for (const field of Object.keys(surface.commands)) {
+                    const wired = ownField(hook, field);
+                    if (typeof wired !== 'string') {
+                        return unreadable(`a hook under ${surface.event} has no readable ${field}`);
+                    }
+                    entry[field] = wired;
+                }
+                hooks.push(entry);
+            }
+            // The matcher is a level like any other, and it is the level the
+            // SUPPORTED/DEGRADED decision is read from. Coercing a present-but-
+            // unreadable one to `undefined` made it the EMPTY matcher, so an
+            // unreadable group answered DEGRADED — a level skipped, reported as a
+            // whole read. Absent stays absent; present-and-unreadable is a finding.
+            const carriedMatcher = ownField(group, 'matcher');
+            if (carriesField(group, 'matcher') && typeof carriedMatcher !== 'string') {
+                return unreadable(`the matcher of a group under ${surface.event} is not a string`);
+            }
+            if (typeof carriedMatcher === 'string' && carriedMatcher.length > MAX_MATCHER_LENGTH) {
+                return unreadable(`the matcher of a group under ${surface.event} is longer than ${String(MAX_MATCHER_LENGTH)} characters and was not read`);
+            }
+            groups.push({
+                matcher: typeof carriedMatcher === 'string' ? carriedMatcher : undefined,
+                hooks,
+            });
+        }
+    }
+    const declared = toolsOf(surface.matcher);
+    // One pass, three kinds. Whether anything merely NAMED the hook is carried
+    // across groups, because that is what separates "nothing here wires this"
+    // from "something here names it and I cannot verify that it runs" — the
+    // ABSENT/UNREADABLE pair this module keeps at every other level.
+    const running = [];
+    const refusals = new Set();
+    for (const group of groups) {
+        let runsHere = false;
+        for (const hook of group.hooks) {
+            const kind = classify(hook, surface);
+            if (kind.kind === 'runs')
+                runsHere = true;
+            else if (kind.kind === 'unreadable')
+                refusals.add(kind.cause);
+        }
+        if (runsHere)
+            running.push(group);
+    }
+    if (running.length === 0) {
+        // A cause that really happened, chosen from what was observed. Three of
+        // them now, and each has its own sentence for the same reason: a refusal
+        // that borrows another's cause sends an operator to the wrong file.
+        // `nothing-generated` is answered first because it is a fact about the
+        // ADAPTER — every entry under the event was classified by it, so no
+        // per-entry cause it might sit beside is informative.
+        if (refusals.has('nothing-generated')) {
+            return {
+                state: 'INTEGRATION-FAILED',
+                reason: `the ${adapter.harness} adapter generates no command for this policy, so nothing under ${surface.event} could be compared against one and whether ${surface.hookPath} runs cannot be verified`,
+            };
+        }
+        if (refusals.has('spelling')) {
+            return {
+                state: 'INTEGRATION-FAILED',
+                reason: `something under ${surface.event} names ${surface.hookPath}, but in no command this harness generates, so whether the hook runs cannot be verified from this surface`,
+            };
+        }
+        if (refusals.has('oversize')) {
+            return {
+                state: 'INTEGRATION-FAILED',
+                reason: `a command under ${surface.event} is longer than ${String(MAX_HOOK_COMMAND_LENGTH)} characters and was not read, so whether ${surface.hookPath} runs cannot be verified from this surface`,
+            };
+        }
+        return {
+            state: 'UNSUPPORTED',
+            reason: `no group under ${surface.event} runs ${surface.hookPath}, so the mechanism is absent on this surface`,
+        };
+    }
+    if (running.some((group) => sameTools(declared, toolsOf(group.matcher ?? '')))) {
+        return { state: 'SUPPORTED' };
+    }
+    // Every group running the hook differs from the declaration; report the
+    // closest one, so the reason names a real discrepancy rather than a union of
+    // several. "Closest" is the fewest tools out of place.
+    const differences = running.map((group) => differenceOf(declared, toolsOf(group.matcher ?? '')));
+    const sizeOf = (d) => d.missing.length + d.extra.length;
+    const closest = differences.reduce((best, d) => (sizeOf(d) < sizeOf(best) ? d : best));
+    return {
+        state: 'DEGRADED',
+        reason: `${surface.hookPath} runs under ${surface.event}, but the matcher ${describeDifference(closest.missing, closest.extra)}`,
+    };
+}