@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/turn_end_transcript.ts

@@ -0,0 +1,216 @@
+/**
+ * Reading a Claude JSONL transcript tail, for the turn-end gate's detectors.
+ *
+ * Extracted from `hooks/turn_end_gate_hook.ts` for the reason its own detector
+ * E carries one line above its import: `_lib` is where this prose costs no
+ * ratchet debt. The gate reached 1,593 lines against a 1,500-line source
+ * budget when the shadow read landed, and `check_source_size_budget` only
+ * turns one way — so the choice was to extract or to delete comments that
+ * record why the reader is shaped as it is. This module is the extraction.
+ *
+ * Nothing about the behaviour moves: every function below is byte-identical to
+ * the version that lived in the gate, and the gate re-exports all three public
+ * names so no importer changes. The two guards this reader depends on stay
+ * where they are — `isSafeTranscriptPath` is the security-relevant
+ * home-confinement predicate and `isSyntheticPrompt` is the ordinal filter, and
+ * relocating either as a side effect of a size budget is exactly the drive-by
+ * this tree's diff discipline forbids.
+ */
+import * as fs from 'node:fs';
+
+import { isSyntheticPrompt } from '../language_mirror_hook.js';
+import { isSafeTranscriptPath } from '../hooks/end_review_nudge_hook.js';
+
+/**
+ * One tool call the assistant made, reduced to what a detector can reason
+ * about: the tool's name, the shell command when it is a shell call, and the
+ * target path when it is a file write.
+ *
+ * Nothing else is kept. A tool input can hold a whole file body, and this
+ * struct is what a refusal quotes back — so it is shaped to be INCAPABLE of
+ * carrying one, the same PII-exclusion-by-construction discipline
+ * `domain-safety-pii` § Surface 2 asks for in a log line.
+ */
+export interface ToolCall {
+    name: string;
+    /** `Bash` only — the command line, so "did anything verify" is answerable. */
+    command?: string;
+    /** Edit/Write only — the file the turn changed, used as the evidence span. */
+    path?: string;
+}
+
+export interface TranscriptTail {
+    lastAssistant: string;
+    /**
+     * Every assistant text of the CURRENT turn, in order — reset at each genuine
+     * user prompt exactly like `toolCalls`, and for the same reason: a question
+     * asked three turns ago was answered, a question asked earlier in THIS turn
+     * was not. Detector E reads it; the other four read `lastAssistant`, which is
+     * always the last element when this is non-empty.
+     *
+     * A tool-only assistant entry contributes NOTHING here. `_messageText`
+     * returns null for it and the collector skips it, so the ordinary shape of a
+     * working turn — prose, tool call, prose — produces two elements and not
+     * three. That is the whole false-positive surface of detector E, and it is
+     * closed here rather than in the detector.
+     */
+    assistantTurnTexts: string[];
+    /**
+     * How many GENUINE user prompts the transcript carries — harness-injected
+     * user-role entries excluded via `isSyntheticPrompt`. This is the turn's
+     * identity; see `alreadyRefusedTurn` for why the prompt's text is not.
+     */
+    turnOrdinal: number;
+    /**
+     * The tool calls of the CURRENT turn, in order — reset at every genuine user
+     * prompt, so a verification from three turns ago cannot vouch for an edit
+     * made now. `_messageText` keeps only `type === 'text'` blocks, which is why
+     * this needed its own extraction rather than a reading of `lastAssistant`:
+     * tool activity is not in the prose at all.
+     */
+    toolCalls: ToolCall[];
+}
+
+/**
+ * The last assistant text, plus the turn ordinal, from a Claude JSONL
+ * transcript. Mirrors `chat_history._extract_claude_transcript_response` for
+ * the assistant half.
+ *
+ * `isSyntheticPrompt` is applied to every user-role entry — the same filter
+ * `language_mirror_hook` uses, and for the same reason it was added there
+ * (round-5 § 6.5): a background-task notification and a `<system-reminder>`
+ * both occupy the user role without being chat messages. Counting them would
+ * move the turn ordinal mid-turn, which is R2 finding 3.
+ */
+export function readTranscriptTail(
+    transcriptPath: string,
+    opts: { homeDir?: string; maxBytes?: number } = {},
+): TranscriptTail {
+    const empty: TranscriptTail = {
+        lastAssistant: '',
+        turnOrdinal: 0,
+        toolCalls: [],
+        assistantTurnTexts: [],
+    };
+    if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
+    let lines: string[];
+    try {
+        // R2 finding 12: `maxBytes` was accepted in the options type and never
+        // used, so the declared cap was decoration. It is enforced here as well
+        // as inside `isSafeTranscriptPath`, because this is the read it bounds.
+        // The whole file still has to be walked — the turn ordinal is a count
+        // over all entries, not something a tail can answer — so the cap is the
+        // guard, not an optimisation.
+        if (opts.maxBytes !== undefined && fs.statSync(transcriptPath).size > opts.maxBytes) {
+            return empty;
+        }
+        lines = fs.readFileSync(transcriptPath, 'utf-8').split('\n');
+    } catch {
+        return empty;
+    }
+    let lastAssistant = '';
+    let turnOrdinal = 0;
+    let toolCalls: ToolCall[] = [];
+    let assistantTurnTexts: string[] = [];
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line) continue;
+        let obj: unknown;
+        try {
+            obj = JSON.parse(line);
+        } catch {
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) continue;
+        const entry = obj as Record<string, unknown>;
+        // Sidechain entries are a SUBAGENT's conversation recorded in the same
+        // JSONL. A subagent prompt is a genuine-looking user-role text entry
+        // appended mid-turn, so counting it moves the ordinal within the turn —
+        // finding 3's failure class in a new shape (R2 round 2, finding 3).
+        if (entry['isSidechain'] === true) continue;
+        const role = entry['type'];
+        if (role !== 'assistant' && role !== 'user') continue;
+        const msg = entry['message'];
+        if (typeof msg !== 'object' || msg === null || Array.isArray(msg)) continue;
+        const content = (msg as Record<string, unknown>)['content'];
+        // Tool calls are read BEFORE the text guard: an assistant entry that is
+        // only a tool_use block has no text at all, so `continue`-ing on a null
+        // text would drop exactly the entries this detector exists to see.
+        if (role === 'assistant') {
+            toolCalls.push(...extractToolCalls(content));
+        }
+        const text = _messageText(content);
+        if (text === null) continue;
+        if (role === 'assistant') {
+            lastAssistant = text;
+            assistantTurnTexts.push(text);
+        } else if (!isSyntheticPrompt(text)) {
+            turnOrdinal += 1;
+            // A genuine user prompt starts a new turn, so the previous turn's
+            // tool activity stops counting. Without this reset, a verification
+            // run three turns ago would vouch for an edit made now — the
+            // "fresh" in edit-without-FRESH-verification is this line.
+            toolCalls = [];
+            // Same boundary, same reason, for detector E: an options block the
+            // user has since replied to is answered, not dropped. Resetting on
+            // the identical line is what makes "in the SAME user turn" true of
+            // the array rather than merely intended.
+            assistantTurnTexts = [];
+        }
+    }
+    return {
+        lastAssistant: lastAssistant.trim(),
+        turnOrdinal,
+        toolCalls,
+        assistantTurnTexts,
+    };
+}
+
+/**
+ * Extract this entry's tool calls, keeping only name, shell command and target
+ * path. A tool input can hold a whole file body; nothing but those three fields
+ * is carried forward.
+ *
+ * Exported because `measure_turn_end_gate` scores detectors C and E over a real
+ * transcript corpus and therefore has to rebuild the same `ToolCall[]` the gate
+ * sees. A second extractor there would be a second dialect of "what the turn
+ * did", and the measurement would then be of that dialect rather than of the
+ * shipped gate — the exact population-parity defect that script's own header
+ * documents twice.
+ */
+export function extractToolCalls(content: unknown): ToolCall[] {
+    if (!Array.isArray(content)) return [];
+    const out: ToolCall[] = [];
+    for (const blk of content) {
+        if (typeof blk !== 'object' || blk === null || Array.isArray(blk)) continue;
+        const b = blk as Record<string, unknown>;
+        if (b['type'] !== 'tool_use') continue;
+        const name = b['name'];
+        if (typeof name !== 'string') continue;
+        const input = b['input'];
+        const call: ToolCall = { name };
+        if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
+            const inp = input as Record<string, unknown>;
+            const cmd = inp['command'];
+            if (typeof cmd === 'string') call.command = cmd;
+            const p = inp['file_path'] ?? inp['path'] ?? inp['notebook_path'];
+            if (typeof p === 'string') call.path = p;
+        }
+        out.push(call);
+    }
+    return out;
+}
+
+function _messageText(content: unknown): string | null {
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) return null;
+    const parts: string[] = [];
+    for (const blk of content) {
+        if (typeof blk !== 'object' || blk === null || Array.isArray(blk)) continue;
+        const b = blk as Record<string, unknown>;
+        if (b['type'] !== 'text') continue;
+        const t = b['text'];
+        if (typeof t === 'string') parts.push(t);
+    }
+    return parts.length > 0 ? parts.join('\n') : null;
+}

package/src/scripts/_lib/typed_op_grant.ts

@@ -0,0 +1,246 @@
+/**
+ * Who may authorise a typed op — `road-to-adversarial-verification-and-long-runs`
+ * 7.3.
+ *
+ * Under a mission the sequence is: a council check that the op belongs to the
+ * mission → a native ask naming the exact object → execute. The council sits
+ * BEFORE the ask and can only subtract.
+ *
+ * ```
+ * THE COUNCIL MAY VETO A TYPED OP. IT MAY NEVER GRANT ONE.
+ * A COUNCIL VERDICT ALONE NEVER PRODUCES THE GRANT, HOWEVER UNANIMOUS.
+ * THE GRANT COMES FROM THE ASK, AND THE ASK NAMES THE EXACT OBJECT.
+ * THE ASK ALSO NAMES THE VERB AND THE TURN. A CONFIRMATION THAT CANNOT SAY
+ * WHICH TURN IT CAME FROM IS NOT A THIS-TURN CONFIRMATION.
+ * ```
+ *
+ * **Why the asymmetry is the whole design.** ADR-257: an unpaid route may
+ * propose and score, never decide. A council that could grant would be a second
+ * authorisation path around `non-destructive-by-default`'s this-turn
+ * confirmation — and it would be the cheaper one, so it would become the only
+ * one. Letting it VETO adds a refusal without adding an authority, which is the
+ * only direction that is safe to add for free.
+ *
+ * **An UNAVAILABLE council does not block the op**, and that is deliberate
+ * rather than lax: the council is a filter, so its absence removes a filter and
+ * leaves the ask exactly where it was. Treating unavailability as a veto would
+ * make an unconfigured council a silent kill switch on every typed op — the
+ * same-shaped wrong guess `council-availability` exists over.
+ *
+ * **What the exactness check is, and why it is two tiers.** It used to be a
+ * shape-free heuristic — eight characters, one of them not a letter — which
+ * accepted `!!!!!!!!` and `all-branches` alike, so the "exact object" guarantee
+ * the Hard Floor rests on was not real. It is now a universal floor that every
+ * op passes through, plus a per-op shape where one is declared. The floor is
+ * deliberately the weakest claim that cannot be wrong (an object with no
+ * alphanumeric run names nothing); the shape is where a category is actually
+ * refused. An op with NO declared shape keeps the old heuristic above the floor
+ * rather than being refused by default, because a Hard-Floor ask that can never
+ * be answered is worse than a loose one. The residual that leaves is real and
+ * bounded: a category still grants for an op OUTSIDE the declared set, and the
+ * declared set is drawn from the Hard Floor's own list of gated operations.
+ *
+ * Pure.
+ */
+
+/** What the council said about this op. `null` when it was not consulted. */
+export type CouncilVerdict = 'in-mission' | 'out-of-mission' | 'unavailable' | null;
+
+/** The ask, as `non-destructive-by-default` requires it: an exact object. */
+export interface ExactObjectAsk {
+    /** e.g. `force-push`. Blank is not a verb, and a blank verb never grants. */
+    readonly op: string;
+    /**
+     * The object, named concretely — a branch and SHA, a recipient and subject,
+     * an amount and card-last4. A CATEGORY is not an object.
+     */
+    readonly object: string;
+    /** True once a human answered this ask. */
+    readonly confirmed: boolean;
+    /**
+     * The turn the human answered in, compared against the caller's current
+     * turn. A bare boolean cannot express the Hard Floor's THIS-TURN wording:
+     * an ask persisted into a mission record and read back after a restart is
+     * otherwise indistinguishable from a confirmation given a second ago. That
+     * replay-across-restart case is the concrete threat, and the sibling module
+     * `mission_record` is what makes it concrete.
+     */
+    readonly confirmed_turn: string;
+}
+
+export type GrantState = 'vetoed' | 'ask-required' | 'granted';
+
+export interface GrantDecision {
+    readonly state: GrantState;
+    readonly reason: string;
+}
+
+/** Whitespace-separated parts of an object, empties dropped. */
+function parts(object: string): string[] {
+    return object.trim().split(/\s+/).filter((p) => p.length > 0);
+}
+
+/** A part with its surrounding punctuation removed, so `@abc123,` reads as `abc123`. */
+function bare(part: string): string {
+    return part.replace(/^[^0-9a-z]+/i, '').replace(/[^0-9a-z]+$/i, '');
+}
+
+/** Does this text name anything at all? The universal floor, and the weakest claim made here. */
+function namesSomething(object: string): boolean {
+    return /[0-9a-z]{2,}/i.test(object);
+}
+
+/** A 7-to-40 character hex run — the token that pins a push to one commit. */
+function isSha(part: string): boolean {
+    return /^[0-9a-f]{7,40}$/i.test(bare(part));
+}
+
+/** An address-shaped part — the token that pins a send to one recipient. */
+function isRecipient(part: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[a-z]{2,}$/i.test(bare(part));
+}
+
+/** A money-shaped part — a decimal amount, or digits carrying a currency marker. */
+function isAmount(part: string): boolean {
+    return /\d[.,]\d{2}\b/.test(part) || (/\d/.test(part) && /[€$£]|\b(?:EUR|USD|GBP)\b/i.test(part));
+}
+
+/** A four-digit run — the card suffix that pins a purchase to one instrument. */
+function isCardSuffix(part: string): boolean {
+    return /(?:^|\D)\d{4}$/.test(bare(part)) && !isAmount(part);
+}
+
+/** Is there a part that carries a name, other than the one already accounted for? */
+function hasQualifier(ps: string[], accountedFor: (p: string) => boolean): boolean {
+    return ps.some((p) => !accountedFor(p) && /[0-9a-z]{2,}/i.test(bare(p)));
+}
+
+/**
+ * The declared per-op object shapes.
+ *
+ * Keyed by the typed-op vocabulary, looked up case-insensitively on a trimmed
+ * op. Only the ops whose exact object this repository has actually seen or that
+ * the roadmap specifies are declared — inventing a shape for an op with no
+ * example risks refusing the first real one, which is the Risk-1 direction.
+ *
+ * `tag-or-release` is deliberately absent: a release object may legitimately be
+ * a bare version, so a SHA requirement would refuse a real one.
+ */
+const OBJECT_SHAPES: ReadonlyMap<string, (object: string) => boolean> = new Map([
+    // A push names WHERE and WHICH COMMIT. The remote is optional — the shipped
+    // object in the unit fixture names a ref and a SHA and no remote, so
+    // requiring one would refuse an object this repository already ships.
+    ...(['push', 'force-push', 'merge-to-trunk', 'history-rewrite'] as const).map(
+        (op) =>
+            [
+                op,
+                (object: string): boolean => {
+                    const ps = parts(object);
+                    return ps.some(isSha) && hasQualifier(ps, isSha);
+                },
+            ] as const,
+    ),
+    [
+        'send',
+        (object: string): boolean => {
+            const ps = parts(object);
+            return ps.some(isRecipient) && hasQualifier(ps, isRecipient);
+        },
+    ] as const,
+    [
+        'purchase',
+        (object: string): boolean => {
+            const ps = parts(object);
+            return ps.some(isAmount) && ps.some(isCardSuffix);
+        },
+    ] as const,
+]);
+
+/**
+ * A named object must be specific enough to be checkable.
+ *
+ * Exported so the two tiers are testable separately: a caller can ask whether an
+ * object would survive the floor without also asking which op it belongs to.
+ */
+export function objectIsExact(op: string, object: string): boolean {
+    if (!namesSomething(object)) return false;
+    const shape = OBJECT_SHAPES.get(op.trim().toLowerCase());
+    if (shape !== undefined) return shape(object);
+    // No declared shape: the pre-existing heuristic, above the floor.
+    return object.trim().length >= 8 && /[^a-z ]/i.test(object);
+}
+
+/** An op names what is about to happen. Blank names nothing. */
+function opIsNamed(op: string): boolean {
+    return op.trim().length > 0;
+}
+
+/**
+ * Decide whether a typed op may proceed.
+ *
+ * The order is fixed: veto first, then the verb, then the confirmation, then
+ * the turn, then the object. A confirmed ask after a veto is still a veto —
+ * otherwise the veto would be advisory, and an advisory veto is not one. The
+ * verb is read before the object because it decides which object shape applies.
+ *
+ * `currentTurn` is REQUIRED rather than optional. An optional turn would make
+ * the this-turn check something a caller opts into, and a security check that
+ * is off by default is not one.
+ */
+export function grantFor(
+    verdict: CouncilVerdict,
+    ask: ExactObjectAsk,
+    currentTurn: string,
+): GrantDecision {
+    if (verdict === 'out-of-mission') {
+        return {
+            state: 'vetoed',
+            reason: `the council found ${ask.op} outside this mission; a veto is not overridden by a later confirmation`,
+        };
+    }
+    if (!opIsNamed(ask.op)) {
+        return {
+            state: 'ask-required',
+            reason: 'the ask names no operation — the verb that says what is about to happen is blank',
+        };
+    }
+    if (!ask.confirmed) {
+        return {
+            state: 'ask-required',
+            reason:
+                verdict === 'in-mission'
+                    ? `the council cleared ${ask.op}, which is not a grant — the ask still has to happen`
+                    : `${ask.op} needs a this-turn confirmation naming the exact object`,
+        };
+    }
+    if (currentTurn.trim().length === 0 || ask.confirmed_turn.trim().length === 0) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation for ${ask.op} carries no turn, so it cannot be shown to be this turn`,
+        };
+    }
+    if (ask.confirmed_turn !== currentTurn) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation for ${ask.op} was given in turn ${ask.confirmed_turn}, not this turn (${currentTurn})`,
+        };
+    }
+    if (!objectIsExact(ask.op, ask.object)) {
+        return {
+            state: 'ask-required',
+            reason: `the confirmation named "${ask.object}", which is a category rather than an object — an approval must name the exact thing`,
+        };
+    }
+    return { state: 'granted', reason: `confirmed this turn for ${ask.op} on ${ask.object}` };
+}
+
+/**
+ * Could this verdict, on its own, produce a grant?
+ *
+ * Exists as its own function so the Iron Law is CHECKABLE rather than merely
+ * stated: it returns false for every verdict, including a unanimous one, and a
+ * test asserts that over the whole domain.
+ */
+export function verdictAloneGrants(_verdict: CouncilVerdict): boolean {
+    return false;
+}

package/src/scripts/_lib/typed_op_watch.ts

@@ -0,0 +1,185 @@
+/**
+ * The guardrail watch over typed ops — `road-to-adversarial-verification-and-long-runs`
+ * 7.1, observation-only floor.
+ *
+ * The eleven typed ops are the Hard Floor's own list: the irreversible and
+ * externally-visible actions `non-destructive-by-default` gates. The layering is
+ * forge protection → the host hook where one is bound → this watch → model
+ * policy, and the watch exists because 7.2 measured the second layer and found
+ * SEVEN of eight hosts carry no refusing `pre_tool_use` binding at all.
+ *
+ * **This mode observes and takes no action. That is a design decision with a
+ * measured precondition, not caution.** K5 of the roadmap kills daemon
+ * enforcement before the observation floor, and the roadmap's own Risk 3 states
+ * the reason: a watchdog reading the reflog and shell history for typed ops can
+ * misclassify, and its enforcing action is stopping the host process — one false
+ * stop costs a twelve-hour run. So enforcement waits behind a measured
+ * false-positive rate under 1 % on the 30-session corpus, and
+ * {@link enforcementAllowed} refuses to unlock without that artefact.
+ *
+ * **What it can and cannot see, said plainly.** It reads lines — reflog entries,
+ * exposed shell history, forge event payloads. A line is not an intention: an op
+ * typed into a comment, a heredoc, or a string literal looks identical to one
+ * about to run. That is precisely why the first mode only writes down what it
+ * saw, and why the false-positive rate is the gate on doing anything more.
+ *
+ * Pure. The I/O — tailing a reflog, reading history, polling an event stream —
+ * belongs to the caller, so every classification is testable offline.
+ */
+
+/** The typed-op classes this watch recognises. */
+export const TYPED_OPS = [
+    'push',
+    'force-push',
+    'merge-to-trunk',
+    'tag-or-release',
+    'deploy',
+    'bulk-delete',
+    'history-rewrite',
+    'send',
+    'publish',
+    'purchase',
+    'submit',
+] as const;
+export type TypedOp = (typeof TYPED_OPS)[number];
+
+/** Where a line came from. Kept because the sources have different reliability. */
+export type WatchSource = 'reflog' | 'shell-history' | 'forge-event';
+
+export interface Observation {
+    readonly op: TypedOp;
+    readonly source: WatchSource;
+    /** The line, truncated. Evidence, never re-executed. */
+    readonly evidence: string;
+}
+
+/**
+ * The recognisers, most specific first.
+ *
+ * ORDER MATTERS and is asserted by a test: `git push --force` is a force-push,
+ * not a push, and a table walked in declaration order gives the specific class
+ * only if it is declared before the general one. A misordered table would report
+ * the milder op for the more dangerous line, which is the wrong direction for
+ * every downstream reader.
+ */
+const RECOGNISERS: readonly (readonly [TypedOp, RegExp])[] = [
+    ['force-push', /\bgit\b[^\n]*\bpush\b[^\n]*(--force\b|--force-with-lease\b|\s-f\b)/],
+    ['history-rewrite', /\bgit\b[^\n]*\b(rebase|filter-repo|filter-branch)\b|\bgit\b[^\n]*reset\s+--hard\b/],
+    ['merge-to-trunk', /\bgit\b[^\n]*\bmerge\b[^\n]*\b(main|master|trunk|production)\b|\bgh\b[^\n]*\bpr\b[^\n]*\bmerge\b/],
+    ['tag-or-release', /\bgit\b[^\n]*\bpush\b[^\n]*\b--tags?\b|\bgh\b[^\n]*\brelease\b[^\n]*\bcreate\b/],
+    ['deploy', /\b(terraform\s+apply|kubectl\s+apply|helm\s+(install|upgrade)|serverless\s+deploy)\b/],
+    ['bulk-delete', /\brm\s+-[a-z]*r[a-z]*f\b|\bgit\b[^\n]*\brm\s+-r\b|\b(DROP\s+TABLE|TRUNCATE)\b/i],
+    ['push', /\bgit\b[^\n]*\bpush\b/],
+    ['purchase', /\b(stripe|checkout|charge|payment)\b[^\n]*\b(create|confirm|capture)\b/i],
+    ['publish', /\bnpm\s+publish\b|\bgh\b[^\n]*\brelease\b[^\n]*\bupload\b/],
+    ['send', /\b(sendmail|mail\s+-s|curl\b[^\n]*\/messages\b)/],
+    ['submit', /\bcurl\b[^\n]*\s-X\s*POST\b[^\n]*\b(submit|apply|order)\b/i],
+];
+
+const EVIDENCE_MAX = 200;
+
+/**
+ * Classify one line, or `null` when nothing matched.
+ *
+ * Deliberately returns at most ONE op. A line is one action, and reporting two
+ * classes for it would double-count in the false-positive denominator the
+ * enforcement gate depends on.
+ */
+export function classifyLine(line: string, source: WatchSource): Observation | null {
+    for (const [op, re] of RECOGNISERS) {
+        if (re.test(line)) {
+            return { op, source, evidence: line.trim().slice(0, EVIDENCE_MAX) };
+        }
+    }
+    return null;
+}
+
+/** Classify a batch, preserving order and dropping non-matches. */
+export function observe(
+    lines: readonly string[],
+    source: WatchSource,
+): Observation[] {
+    return lines
+        .map((l) => classifyLine(l, source))
+        .filter((o): o is Observation => o !== null);
+}
+
+/** The two modes. There is no third, and `enforce` is gated. */
+export type WatchMode = 'observe' | 'enforce';
+
+/** The false-positive measurement the enforcing mode waits behind. */
+export interface FalsePositiveMeasurement {
+    /** Sessions the corpus covered. The roadmap names 30. */
+    readonly sessions: number;
+    readonly observations: number;
+    readonly falsePositives: number;
+    /** Where the artefact lives, so the claim is checkable. */
+    readonly artefact: string;
+}
+
+/** The corpus size the roadmap fixed before any measurement was taken. */
+export const REQUIRED_SESSIONS = 30;
+/** The rate enforcement waits behind. */
+export const MAX_FALSE_POSITIVE_RATE = 0.01;
+
+export interface EnforcementVerdict {
+    readonly allowed: boolean;
+    readonly reason: string;
+}
+
+/**
+ * May the enforcing mode be enabled?
+ *
+ * `null` — no measurement at all — is a refusal with its own reason, never a
+ * pass. A gate that unlocks when it cannot measure is the shape this whole
+ * roadmap is written against, and it is the one an absent-artefact check gets
+ * wrong by default.
+ */
+export function enforcementAllowed(
+    m: FalsePositiveMeasurement | null,
+): EnforcementVerdict {
+    if (m === null) {
+        return {
+            allowed: false,
+            reason:
+                'no false-positive measurement exists. Enforcement stops the host process; a ' +
+                'rate nobody measured is not a control (K5).',
+        };
+    }
+    if (m.sessions < REQUIRED_SESSIONS) {
+        return {
+            allowed: false,
+            reason: `measured over ${String(m.sessions)} session(s), below the ${String(REQUIRED_SESSIONS)} the corpus was fixed at`,
+        };
+    }
+    if (m.observations === 0) {
+        return {
+            allowed: false,
+            reason:
+                'zero observations: a rate over an empty denominator is not a measurement, ' +
+                'and it is the reading a broken recogniser produces',
+        };
+    }
+    const rate = m.falsePositives / m.observations;
+    if (rate >= MAX_FALSE_POSITIVE_RATE) {
+        return {
+            allowed: false,
+            reason: `false-positive rate ${rate.toFixed(4)} is not below ${String(MAX_FALSE_POSITIVE_RATE)}`,
+        };
+    }
+    return { allowed: true, reason: `rate ${rate.toFixed(4)} over ${String(m.observations)} observations in ${m.artefact}` };
+}
+
+/**
+ * What the watch does with an observation, per mode.
+ *
+ * In `observe` the action is always `record` — there is no branch that acts, so
+ * no configuration flips this mode into one that does.
+ */
+export function actionFor(
+    mode: WatchMode,
+    measurement: FalsePositiveMeasurement | null,
+): 'record' | 'record-and-ask' {
+    if (mode === 'observe') return 'record';
+    return enforcementAllowed(measurement).allowed ? 'record-and-ask' : 'record';
+}