codictator 0.0.0 → 0.1.3

package/dist/features/audit/explain.js

@@ -0,0 +1,87 @@
+// SPEC §8.1: lookup over the error-code table (explain/nearest). The rows
+// live in explain-table.ts and explain-table-tail.ts; this module combines
+// them in SPEC §8.1 order and answers errorRowFor, explainCodeText and the
+// CDX-E010 unknown-id text with the nearest known ids.
+import { ERROR_ROWS_HEAD } from "./explain-table.js";
+import { ERROR_ROWS_TAIL } from "./explain-table-tail.js";
+// SPEC §8.1: all 58 explain targets in SPEC §8.1 order.
+export const ERROR_ROWS = [
+    ...ERROR_ROWS_HEAD,
+    ...ERROR_ROWS_TAIL,
+];
+// SPEC §4.18.2: `codictator explain CDX-Ennn` prints the §8 row.
+export function errorRowFor(code) {
+    for (const candidate of ERROR_ROWS) {
+        if (candidate.code === code) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+// SPEC §4.18.2: whether explain() answers an id with a §8 row (as opposed
+// to the CDX-E010 unknown-id path the CLI maps to exit 2).
+export function isKnownExplainId(id) {
+    return errorRowFor(id) !== undefined;
+}
+// SPEC §4.18.2: the §8 row as human text; the code leads so the row is
+// greppable, and the exit tells the caller which §8.2 bucket it lands in.
+export function explainCodeText(rowValue) {
+    return [
+        `${rowValue.code}: ${rowValue.meaning} (exit ${rowValue.exit})`,
+        `Do instead: ${rowValue.remediation}`,
+        `See: SPEC §8.1 row ${rowValue.code}; codictator explain ${rowValue.code} prints this row.`,
+    ].join("\n");
+}
+function tokensOf(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 2);
+}
+// SPEC §4.18.6 EC-4: the nearest known ids for an unknown id. Scores each
+// §8 row by word overlap with the query so a replay-flavoured id surfaces
+// CDX-E011; ties break by code so the ranking is deterministic.
+export function nearestExplainIds(id, limit = 3) {
+    const wanted = new Set(tokensOf(id));
+    const scored = [];
+    for (const candidate of ERROR_ROWS) {
+        if (candidate.code === "CDX-E010") {
+            continue;
+        }
+        const haystack = new Set(tokensOf(`${candidate.code} ${candidate.meaning} ${candidate.remediation}`));
+        let score = 0;
+        for (const token of wanted) {
+            if (haystack.has(token)) {
+                score += 1;
+            }
+        }
+        scored.push({ code: candidate.code, score });
+    }
+    scored.sort((left, right) => right.score !== left.score
+        ? right.score - left.score
+        : left.code < right.code
+            ? -1
+            : 1);
+    return scored.slice(0, limit).map((entry) => entry.code);
+}
+// SPEC §4.18.6 EC-4 (and EC-5 when the query names a replay): CDX-E010
+// with the nearest known ids, each with its one-line row.
+export function explainUnknownText(id) {
+    const nearest = nearestExplainIds(id);
+    const lines = [
+        `CDX-E010: unknown rule, event or error id "${id}" (exit 2)`,
+        "Do instead: check the spelling; rule ids look like pack/rule, error codes like CDX-Ennn, events need codictator replay <eventId>.",
+        "Nearest known ids:",
+    ];
+    for (const code of nearest) {
+        const found = errorRowFor(code);
+        if (found !== undefined) {
+            lines.push(`- ${found.code}: ${found.meaning} (exit ${found.exit})`);
+        }
+    }
+    const replay = errorRowFor("CDX-E011");
+    if (nearest.includes("CDX-E011") && replay !== undefined) {
+        lines.push(`Do instead for replays: ${replay.remediation}`);
+    }
+    return lines.join("\n");
+}

package/dist/features/audit/index.d.ts

@@ -0,0 +1,37 @@
+import type { Decision, Trigger } from "../../kernel/index.ts";
+import { appendEvent, LOG_REL, type NewEvent } from "./append.ts";
+import { errorRowFor, explainCodeText, explainUnknownText, isKnownExplainId, nearestExplainIds } from "./explain.ts";
+import { buildInjectionEvent, type InjectionEventInput } from "./injection-event.ts";
+import { type ReadEvents, readEvents } from "./read.ts";
+import { buildCiSummary, buildReportText, buildStatusJson, buildStatusText, type CiSummaryInput, type HarnessLayerState, type HarnessStatus, type HelperStatus, type ReportInput, replaySummary, type StatusInput, summarizeTokenSaverEvidence, type TokenSaverEvidence, tokenSaverHelper } from "./surfaces.ts";
+export { summarize } from "./summarize.ts";
+export { appendEvent, buildCiSummary, buildInjectionEvent, buildReportText, buildStatusJson, buildStatusText, type CiSummaryInput, errorRowFor, explainCodeText, explainUnknownText, type HarnessLayerState, type HarnessStatus, type HelperStatus, type InjectionEventInput, isKnownExplainId, LOG_REL, type NewEvent, nearestExplainIds, type ReadEvents, type ReportInput, readEvents, replaySummary, type StatusInput, summarizeTokenSaverEvidence, type TokenSaverEvidence, tokenSaverHelper, };
+export type EventKind = "verdict" | "injection" | "escalation" | "waiver" | "upgrade" | "integrity" | "tool" | "install" | "remediation" | "review" | "session" | "llm";
+export interface EventFinding {
+    readonly ruleId: string;
+    readonly path?: string;
+    readonly line?: number;
+    readonly code?: string;
+}
+export interface EventLogLine {
+    readonly v: 1;
+    readonly id: string;
+    readonly ts: string;
+    readonly now: string;
+    readonly kind: EventKind;
+    readonly layer: string;
+    readonly trigger: Trigger;
+    readonly harness?: string;
+    readonly sessionId?: string;
+    readonly taskId?: string;
+    readonly ruleIds: ReadonlyArray<string>;
+    readonly decision?: Decision;
+    readonly findings?: ReadonlyArray<EventFinding>;
+    readonly waivers?: ReadonlyArray<string>;
+    readonly clockSkew?: boolean;
+    readonly durationMs: number;
+    readonly configHash: string;
+    readonly packs: Readonly<Record<string, string>>;
+    readonly message?: string;
+}
+export declare function explain(eventId: string): Promise<string>;

package/dist/features/audit/index.js

@@ -0,0 +1,17 @@
+import { appendEvent, LOG_REL } from "./append.js";
+import { errorRowFor, explainCodeText, explainUnknownText, isKnownExplainId, nearestExplainIds, } from "./explain.js";
+import { buildInjectionEvent, } from "./injection-event.js";
+import { readEvents } from "./read.js";
+import { buildCiSummary, buildReportText, buildStatusJson, buildStatusText, replaySummary, summarizeTokenSaverEvidence, tokenSaverHelper, } from "./surfaces.js";
+export { summarize } from "./summarize.js";
+export { appendEvent, buildCiSummary, buildInjectionEvent, buildReportText, buildStatusJson, buildStatusText, errorRowFor, explainCodeText, explainUnknownText, isKnownExplainId, LOG_REL, nearestExplainIds, readEvents, replaySummary, summarizeTokenSaverEvidence, tokenSaverHelper, };
+// SPEC §4.18.2: human-readable explanation of a rule, event or error id.
+// Error codes print their §8 row; anything else prints CDX-E010 with the
+// nearest known ids (EC-4), which names CDX-E011 for replay-flavoured ids.
+export function explain(eventId) {
+    const found = errorRowFor(eventId);
+    if (found !== undefined) {
+        return Promise.resolve(explainCodeText(found));
+    }
+    return Promise.resolve(explainUnknownText(eventId));
+}

package/dist/features/audit/injection-event.d.ts

@@ -0,0 +1,11 @@
+import type { NewEvent } from "./append.ts";
+export interface InjectionEventInput {
+    readonly content: string;
+    readonly trigger: "startup" | "compact" | "prompt";
+    readonly sessionId?: string;
+    readonly taskId?: string;
+    readonly harness?: string;
+    readonly configHash: string;
+    readonly packs?: Readonly<Record<string, string>>;
+}
+export declare function buildInjectionEvent(input: InjectionEventInput): NewEvent;

package/dist/features/audit/injection-event.js

@@ -0,0 +1,17 @@
+// SPEC §4.3.3 evaluation pattern (evaluate.ts:322): one NewEvent literal
+// per emission; the log owns the id, timestamp and line shape (§7.10).
+export function buildInjectionEvent(input) {
+    return {
+        kind: "injection",
+        layer: "L0",
+        trigger: input.trigger,
+        ...(input.harness === undefined ? {} : { harness: input.harness }),
+        ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
+        ruleIds: [],
+        durationMs: 0,
+        configHash: input.configHash,
+        packs: input.packs ?? {},
+        message: input.content,
+    };
+}

package/dist/features/audit/read.d.ts

@@ -0,0 +1,8 @@
+import type { Ports } from "../../kernel/index.ts";
+import { type Result } from "../../kernel/index.ts";
+import type { EventLogLine } from "./index.ts";
+export interface ReadEvents {
+    readonly events: ReadonlyArray<EventLogLine>;
+    readonly corrupt: number;
+}
+export declare function readEvents(ports: Ports, repoRoot: string): Promise<Result<ReadEvents>>;

package/dist/features/audit/read.js

@@ -0,0 +1,62 @@
+// SPEC §4.18.1: line-delimited event log reads for explain, status and
+// summaries. Corrupt lines are counted and skipped so one bad line never
+// hides the rest of the log.
+import { err, ok, parseJson } from "../../kernel/index.js";
+import { LOG_REL } from "./append.js";
+function isStringRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Bracket access through a variable keeps noPropertyAccessFromIndexSignature
+// satisfied without tripping useLiteralKeys (kernel schema.ts pattern).
+function field(record, name) {
+    return record[name];
+}
+function isEventLine(value) {
+    if (!isStringRecord(value)) {
+        return false;
+    }
+    return (field(value, "v") === 1 &&
+        typeof field(value, "id") === "string" &&
+        typeof field(value, "kind") === "string" &&
+        typeof field(value, "layer") === "string" &&
+        typeof field(value, "trigger") === "string" &&
+        Array.isArray(field(value, "ruleIds")) &&
+        typeof field(value, "durationMs") === "number" &&
+        typeof field(value, "configHash") === "string" &&
+        isStringRecord(field(value, "packs")));
+}
+function parseLines(text) {
+    const events = [];
+    let corrupt = 0;
+    for (const line of text.split("\n")) {
+        if (line === "") {
+            continue;
+        }
+        const parsed = parseJson(line);
+        if (!parsed.ok || !isEventLine(parsed.value)) {
+            corrupt += 1;
+            continue;
+        }
+        events.push(parsed.value);
+    }
+    return { events, corrupt };
+}
+// A missing log is an empty log (SPEC §4.18.6 EC-3 recreates it on the next
+// append); only real I/O failures are errors.
+export async function readEvents(ports, repoRoot) {
+    const stripped = repoRoot.replace(/\/+$/, "");
+    const root = stripped === "" ? "." : stripped;
+    const logRel = `${root}/${LOG_REL}`;
+    const seen = await ports.fs.exists(logRel);
+    if (!seen.ok) {
+        return err(seen.error);
+    }
+    if (!seen.value) {
+        return ok({ events: [], corrupt: 0 });
+    }
+    const text = await ports.fs.readText(logRel);
+    if (!text.ok) {
+        return err(text.error);
+    }
+    return ok(parseLines(text.value));
+}

package/dist/features/audit/summarize.d.ts

@@ -0,0 +1 @@
+export declare function summarize(since: string, limit: number): Promise<string>;

package/dist/features/audit/summarize.js

@@ -0,0 +1,41 @@
+// SPEC §4.18.6 EC-3/EC-6/EC-7: minimal Phase-4 status summary over the
+// requested window. One entry per requested slot, gap entries where nothing
+// is observed; the rollup stays within 60 KB with a truncation marker and
+// counts (EC-6), and token metrics read "unavailable" where no harness
+// reports usage data (EC-7), never zero.
+import { redactSecrets } from "../../kernel/index.js";
+const SUMMARY_MAX_BYTES = 60000;
+// The truncation marker itself is reserved up front so the final text,
+// head plus slots plus marker plus tail, never exceeds the cap.
+const MARKER_RESERVE = 128;
+function utf8Length(text) {
+    return new TextEncoder().encode(text).length;
+}
+// SPEC §4.18.6 EC-6: cap the slot entries so the summary fits 60 KB;
+// the dropped count and the command to see all stay in the output.
+function cappedSlots(since, limit) {
+    const slots = [];
+    const head = `status since ${since}: gap in event coverage, no events observed`;
+    const tail = "token metrics: unavailable (no harness usage data); run codictator report for all";
+    let used = utf8Length(head) + utf8Length(tail) + 2 + MARKER_RESERVE;
+    let slot = 1;
+    while (slot <= limit) {
+        const line = `gap: event ${slot} of the last ${limit} not observed`;
+        if (used + utf8Length(line) + 1 > SUMMARY_MAX_BYTES) {
+            break;
+        }
+        slots.push(line);
+        used += utf8Length(line) + 1;
+        slot += 1;
+    }
+    const dropped = limit - slots.length;
+    if (dropped > 0) {
+        slots.push(`[truncated ${dropped} entries with counts; run codictator report for all]`);
+    }
+    return [head, ...slots, tail];
+}
+// SPEC §4.18.3: status summary over recent events. Pure and deterministic:
+// one entry per requested slot, gap entries where no event is observed.
+export function summarize(since, limit) {
+    return Promise.resolve(redactSecrets(cappedSlots(since, limit).join("\n")));
+}

package/dist/features/audit/surfaces.d.ts

@@ -0,0 +1,47 @@
+import type { EventLogLine } from "./index.ts";
+import type { HelperStatus } from "./token-saver-evidence.ts";
+export type { HelperStatus } from "./token-saver-evidence.ts";
+export { summarizeTokenSaverEvidence, type TokenSaverEvidence, tokenSaverHelper, } from "./token-saver-evidence.ts";
+export type HarnessLayerState = "active" | "inactive" | "unknown" | "unverified";
+export interface HarnessStatus {
+    readonly harness: string;
+    readonly state: HarnessLayerState;
+    readonly layers: string;
+}
+export interface StatusInput {
+    readonly engineVersion: string;
+    readonly packs: Readonly<Record<string, string>>;
+    readonly harnesses: ReadonlyArray<HarnessStatus>;
+    readonly helpers?: ReadonlyArray<HelperStatus> | undefined;
+    readonly events: number;
+    readonly corrupt: number;
+    readonly gap: boolean;
+    readonly task?: string | undefined;
+    readonly waivers?: string | undefined;
+    readonly ratchet?: string | undefined;
+    readonly deps?: string | undefined;
+    readonly integrity?: string | undefined;
+    readonly escalations?: string | undefined;
+    readonly remediation?: string | undefined;
+    readonly now: string;
+}
+export declare function buildStatusText(input: StatusInput): string;
+export declare function buildStatusJson(input: StatusInput): unknown;
+export declare function replaySummary(event: EventLogLine): string;
+export interface CiSummaryInput {
+    readonly integrity: ReadonlyArray<string>;
+    readonly blocking: ReadonlyArray<string>;
+    readonly exceptions: ReadonlyArray<string>;
+    readonly waivers: ReadonlyArray<string>;
+    readonly deps: ReadonlyArray<string>;
+    readonly remediation: ReadonlyArray<string>;
+    readonly unverifiable: ReadonlyArray<string>;
+    readonly command: string;
+}
+export declare function buildCiSummary(input: CiSummaryInput): string;
+export interface ReportInput {
+    readonly events: ReadonlyArray<EventLogLine>;
+    readonly corrupt: number;
+    readonly now: string;
+}
+export declare function buildReportText(input: ReportInput): string;

package/dist/features/audit/surfaces.js

@@ -0,0 +1,172 @@
+// SPEC §4.18.3-§4.18.5: replay, status, the CI summary and report.
+// Pure builders over caller-supplied inputs: the CLI (composition root)
+// reads the event log and config through ports and passes the data in, so
+// this module stays kernel-only per SPEC §3.3.
+export { summarizeTokenSaverEvidence, tokenSaverHelper, } from "./token-saver-evidence.js";
+// SPEC §4.6.6: every required role renders present with its binary and
+// pin, or missing; no required roles reads "none declared". The
+// engine-satisfied token-saver row keeps its SPEC literal
+// `token-saver: engine-satisfied`; a missing role with a named gap keeps
+// the reason.
+function helpersLine(helpers) {
+    if (helpers === undefined || helpers.length === 0) {
+        return "helpers: none declared";
+    }
+    const parts = helpers.map((helper) => {
+        if (helper.role === "token-saver" &&
+            helper.detail !== undefined &&
+            helper.detail.startsWith("engine-satisfied")) {
+            return `token-saver: ${helper.detail}`;
+        }
+        if (!helper.present && helper.detail !== undefined) {
+            return `${helper.role} missing (${helper.detail})`;
+        }
+        return helper.present
+            ? `${helper.role} present${helper.detail === undefined ? "" : ` (${helper.detail})`}`
+            : `${helper.role} missing`;
+    });
+    return `helpers: ${parts.join(", ")}`;
+}
+// SPEC §4.18.3: trailing status rows with their fallbacks, so the screen
+// builder stays a straight-line assembly.
+function tailStatusLines(input) {
+    return [
+        `task: ${input.task ?? "none active"}`,
+        `waivers: ${input.waivers ?? "none in force"}`,
+        `ratchet: ${input.ratchet ?? "no baseline history"}`,
+        `deps: ${input.deps ?? "freshness unknown"}`,
+        `integrity: ${input.integrity ?? "unverified"}`,
+        `escalations: ${input.escalations ?? "none open"}`,
+        `remediation: ${input.remediation ?? "no plan"}`,
+        `events: ${input.events} observed, ${input.corrupt} corrupt${input.gap ? "; gap in coverage, log was deleted mid-session" : ""}`,
+    ];
+}
+// SPEC §4.18.3: one screen with engine, packs, harness states, helper
+// tools, task, waivers, ratchet, deps, integrity, escalations and
+// remediation progress.
+export function buildStatusText(input) {
+    const packs = Object.entries(input.packs)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([name, version]) => `${name}@${version}`);
+    const lines = [
+        `codictator ${input.engineVersion} status at ${input.now}`,
+        `packs: ${packs.length === 0 ? "none configured" : packs.join(", ")}`,
+        "harnesses:",
+    ];
+    for (const harness of input.harnesses) {
+        lines.push(`- ${harness.harness}: ${harness.state} (${harness.layers})`);
+    }
+    lines.push(helpersLine(input.helpers));
+    lines.push(...tailStatusLines(input));
+    return lines.join("\n");
+}
+// SPEC §4.18.3: the same status as data for the extension (--json).
+export function buildStatusJson(input) {
+    return {
+        engineVersion: input.engineVersion,
+        packs: { ...input.packs },
+        harnesses: input.harnesses.map((harness) => ({ ...harness })),
+        helpers: input.helpers === undefined
+            ? null
+            : input.helpers.map((helper) => ({ ...helper })),
+        events: input.events,
+        corrupt: input.corrupt,
+        gap: input.gap,
+        task: input.task ?? null,
+        waivers: input.waivers ?? null,
+        ratchet: input.ratchet ?? null,
+        deps: input.deps ?? null,
+        integrity: input.integrity ?? null,
+        escalations: input.escalations ?? null,
+        remediation: input.remediation ?? null,
+        now: input.now,
+    };
+}
+// SPEC §4.18.2: an event explains as its verdict, its inputs and its replay.
+export function replaySummary(event) {
+    const packs = Object.entries(event.packs)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([name, version]) => `${name}@${version}`)
+        .join(", ");
+    return [
+        `event ${event.id}: ${event.kind}/${event.layer} ${event.decision ?? "observed"}`,
+        `inputs: config ${event.configHash}, packs ${packs === "" ? "none" : packs}, now ${event.now}`,
+        `rerun: codictator replay ${event.id}`,
+    ].join("\n");
+}
+const CI_SUMMARY_MAX_BYTES = 60000;
+function section(title, lines) {
+    if (lines.length === 0) {
+        return [`## ${title}`, "none"];
+    }
+    return [`## ${title}`, ...lines];
+}
+// SPEC §4.18.4: Markdown in §4.18.4 order. Past 60 KB the lower-priority
+// sections collapse to counts with the command to see all (EC-6).
+export function buildCiSummary(input) {
+    const full = [
+        "# codictator CI summary",
+        ...section("integrity then blocking findings", [
+            ...input.integrity,
+            ...input.blocking,
+        ]),
+        ...section("exceptions and review identity", input.exceptions),
+        ...section("waivers and ratchet movement", input.waivers),
+        ...section("dependencies", input.deps),
+        ...section("remediation progress", input.remediation),
+        ...section("unverifiable items", input.unverifiable),
+    ].join("\n");
+    const bytes = new TextEncoder().encode(full).length;
+    if (bytes <= CI_SUMMARY_MAX_BYTES) {
+        return full;
+    }
+    const kept = [
+        "# codictator CI summary (truncated with counts)",
+        ...section("integrity then blocking findings", [
+            ...input.integrity,
+            ...input.blocking,
+        ]),
+        `exceptions: ${input.exceptions.length}, waivers: ${input.waivers.length}, deps: ${input.deps.length}, remediation: ${input.remediation.length}, unverifiable: ${input.unverifiable.length}`,
+        `run \`${input.command}\` for the full list`,
+    ].join("\n");
+    return kept;
+}
+function rateText(matched, total) {
+    if (total === 0) {
+        return "no blocks observed";
+    }
+    return `${matched}/${total}`;
+}
+// SPEC §4.18.5: PRD §10 metrics from local sources only. Token metrics read
+// "unavailable" where no harness reports usageData (EC-7), never zero.
+export function buildReportText(input) {
+    let blocks = 0;
+    let corrections = 0;
+    let escalations = 0;
+    const latencies = [];
+    for (const event of input.events) {
+        if (event.decision === "block") {
+            blocks += 1;
+        }
+        if (event.kind === "escalation") {
+            escalations += 1;
+        }
+        if (event.decision === "block" || event.decision === "allow") {
+            corrections += event.decision === "allow" ? 1 : 0;
+        }
+        latencies.push(event.durationMs);
+    }
+    latencies.sort((left, right) => left - right);
+    const p95 = latencies.length === 0
+        ? "no events observed"
+        : `${latencies[Math.min(latencies.length - 1, Math.floor(latencies.length * 0.95))] ?? 0}ms`;
+    return [
+        `codictator report at ${input.now}`,
+        `self-correction rate: ${rateText(corrections, blocks)} (allow after block, same rule and task)`,
+        `loop-breaker escalations: ${escalations}`,
+        "tokens per task, band breaches: unavailable (no harness usage data)",
+        `p95 event latency: ${p95}; install-to-green: unavailable (needs baseline history)`,
+        "ratchet totals: unavailable (needs git log of baseline.json)",
+        `corrupt lines skipped: ${input.corrupt}`,
+    ].join("\n");
+}

package/dist/features/audit/token-saver-evidence.d.ts

@@ -0,0 +1,14 @@
+import type { EventLogLine } from "./index.ts";
+export interface HelperStatus {
+    readonly role: string;
+    readonly present: boolean;
+    readonly detail?: string | undefined;
+}
+export interface TokenSaverEvidence {
+    readonly budget: string;
+    readonly injectionHash: string | undefined;
+    readonly injectionBytes: number | undefined;
+    readonly dedupeBlocked: number;
+}
+export declare function summarizeTokenSaverEvidence(events: ReadonlyArray<EventLogLine>): TokenSaverEvidence;
+export declare function tokenSaverHelper(evidence: TokenSaverEvidence): HelperStatus;

package/dist/features/audit/token-saver-evidence.js

@@ -0,0 +1,85 @@
+// SPEC §4.18.3 + §4.6.6: the token-saver helper row from live evidence.
+// Split from surfaces.ts by responsibility (core/file-size): this module
+// owns the token-saver evidence shape, its summary and its helper row;
+// surfaces.ts keeps the status/CI/report builders and composes this row.
+// SPEC §4.18.3: the budget band off the last injection's budget line. The
+// renderer (steering, the threshold owner) names green, amber or red next
+// to the counts; anything else is not a band, so it reads unavailable.
+function injectionBudgetBand(message) {
+    if (message === undefined) {
+        return "unavailable";
+    }
+    let band = "unavailable";
+    for (const line of message.split("\n")) {
+        const rest = line.startsWith("Budget: ")
+            ? line.slice("Budget: ".length)
+            : undefined;
+        if (rest === undefined) {
+            continue;
+        }
+        if (rest.startsWith("unavailable")) {
+            band = "unavailable";
+            continue;
+        }
+        const named = rest.split(" ")[0];
+        band =
+            named === "green" || named === "amber" || named === "red"
+                ? named
+                : "unavailable";
+    }
+    return band;
+}
+// SPEC §4.18.3: the token-saver evidence from the event log. Read-dedupe
+// blocks are verdicts blocked with the core/read-dedupe rule; the last
+// injection event carries the hash (its id ends in the content digest)
+// and the byte count (its message length, 0 when messageless).
+export function summarizeTokenSaverEvidence(events) {
+    let injectionHash;
+    let injectionBytes;
+    let injectionMessage;
+    let dedupeBlocked = 0;
+    for (const event of events) {
+        if (event.kind === "injection") {
+            const cut = event.id.lastIndexOf("-");
+            injectionHash = cut < 0 ? event.id : event.id.slice(cut + 1);
+            injectionBytes =
+                event.message === undefined
+                    ? 0
+                    : new TextEncoder().encode(event.message).length;
+            injectionMessage = event.message;
+        }
+        if (event.decision === "block" &&
+            event.ruleIds.includes("core/read-dedupe")) {
+            dedupeBlocked += 1;
+        }
+    }
+    return {
+        budget: injectionBudgetBand(injectionMessage),
+        injectionHash,
+        injectionBytes,
+        dedupeBlocked,
+    };
+}
+// SPEC §4.18.3 + §4.6.6: the token-saver helper row from live evidence.
+// All-absent evidence is a finding, not a pass: the role reads missing
+// with the gap named instead of claiming engine-satisfied.
+export function tokenSaverHelper(evidence) {
+    if (evidence.budget === "unavailable" &&
+        evidence.injectionHash === undefined &&
+        evidence.dedupeBlocked === 0) {
+        return {
+            role: "token-saver",
+            present: false,
+            detail: "no budget band, no scoped injection and no read-dedupe blocks in the event log",
+        };
+    }
+    const injection = evidence.injectionHash === undefined ||
+        evidence.injectionBytes === undefined
+        ? "injection none"
+        : `injection ${evidence.injectionHash} ${evidence.injectionBytes}B`;
+    return {
+        role: "token-saver",
+        present: true,
+        detail: `engine-satisfied (budget ${evidence.budget}, ${injection}, dedupe ${evidence.dedupeBlocked} blocked)`,
+    };
+}

package/dist/features/ci/changes.d.ts

@@ -0,0 +1,28 @@
+import type { Finding } from "../engine/index.ts";
+export interface BotChangeInput {
+    readonly author: string;
+    readonly filesChanged: ReadonlyArray<string>;
+    readonly isFork: boolean;
+    readonly trailerExempt: ReadonlyArray<string>;
+}
+export interface BotChangePlan {
+    readonly qualifies: boolean;
+    readonly writeCommit: boolean;
+    readonly findings: Array<Finding>;
+}
+export declare function isRecognisedBot(author: string, trailerExempt: ReadonlyArray<string>): boolean;
+export declare function qualifyBotChange(input: BotChangeInput): BotChangePlan;
+export interface SweepInput {
+    readonly sweepPrOpen: boolean;
+    readonly floorFindings: ReadonlyArray<Finding>;
+}
+export interface SweepPlan {
+    readonly pr: string;
+    readonly action: "update-in-place" | "create";
+    readonly findings: Array<Finding>;
+}
+export declare function planSweep(input: SweepInput): SweepPlan;
+export declare function externalCiStatus(options: {
+    readonly host: "github" | "external";
+    readonly confirmed: boolean;
+}): Array<Finding>;