crewhaus 0.1.8 → 0.2.0

package/dist/scope-audit-drift.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Item 49 — scope-audit drift watch: the persistence + baseline-diff +
+ * boundary-drift core behind `crewhaus doctor --philosophy-alignment
+ * --json/--baseline/--accept-baseline`, factored out of the entry file
+ * `index.ts` (which runs a top-level argv switch and so cannot be imported
+ * by a test without executing the CLI). Side-effect-free on import and
+ * directly unit-testable, mirroring `scope-audit.ts` / `security-digest.ts`.
+ *
+ * The problem this closes: `doctor --philosophy-alignment` audited boundary
+ * call sites and tool scopes but was run-and-forget print-only — a
+ * regression (or a NEW un-classified ingress) looked identical to
+ * known-accepted findings, so nobody could gate CI on it. Three pieces:
+ *
+ *   1. Stable finding identity. Every audit finding now carries a
+ *      (class, file, symbol) triple; `findingId` hashes it so a finding
+ *      keeps its id across runs even when the human-facing label or reason
+ *      wording changes. Labels/reasons are deliberately NOT hashed. Renaming
+ *      or moving a file (or renaming a symbol) mints a NEW id by design —
+ *      the gate fails closed on the "new" finding and the baseline must be
+ *      re-accepted with --accept-baseline.
+ *
+ *   2. Baselined diffs, following `@crewhaus/regression-runner`'s `gate()`
+ *      shape (verdict + reason + report). `diffScopeAuditSnapshots` splits
+ *      current findings into new / accepted / resolved against
+ *      `.crewhaus/scope-audit/baseline.json`; the verdict fails ONLY on new
+ *      findings — legacy accepted findings never block, so the gate can be
+ *      adopted on a repo with known warts.
+ *
+ *   3. Boundary-site drift detection. The audit's canonical boundary list
+ *      is hardcoded (six sites in index.ts) and checks only that KNOWN
+ *      sites still call `classifyBoundary`; nothing caught a NEW
+ *      cross-trust ingress that skipped classification. `detectBoundaryDrift`
+ *      extends the same mechanism (read package sources, substring-match)
+ *      with a small set of conservative ingress signals derived from the
+ *      boundary-classifier TrustOrigin taxonomy, and flags packages that
+ *      match a signal but never reference the classification fabric.
+ *      Findings are REPORT-ONLY (warn, pass: true) in plain mode; only the
+ *      --baseline gate fails on them, and only when they are NEW.
+ */
+/** Finding classes the philosophy audit emits. `boundary-drift` is the new
+ *  detector; the rest map 1:1 onto the pre-existing printed checks. */
+export type PhilosophyFindingClass = "pillar-doc" | "package-presence" | "boundary-site" | "tool-scope" | "contributor-doc" | "boundary-drift";
+export type PhilosophyFinding = {
+    readonly class: PhilosophyFindingClass;
+    /** Repo-relative path the finding is about ("" for repo-level checks). */
+    readonly file: string;
+    /** Stable symbol within (class, file) — a site/tool/signal name. */
+    readonly symbol: string;
+    readonly label: string;
+    readonly pass: boolean;
+    /** warn+pass renders as "~" — informational, never fails plain doctor. */
+    readonly warn?: boolean;
+    readonly reason?: string;
+};
+/**
+ * Stable finding id: sha256 over the (class, file, symbol) identity triple,
+ * truncated to 12 hex chars (48 bits — collision-safe at this cardinality
+ * and short enough to read in a diff). Labels and reasons are excluded on
+ * purpose: rewording a message must not orphan a baselined finding.
+ *
+ * The NUL separator makes the triple unambiguous (no field can contain it).
+ * It MUST stay the `\u0000` ESCAPE SEQUENCE in this source: a literal NUL
+ * byte makes git treat the whole module as a binary blob (unreviewable
+ * diffs) and invites silent id-invalidation by NUL-stripping tools. The
+ * escape and the literal produce identical runtime bytes, so every existing
+ * findingId and accepted baseline stays valid — scope-audit-drift.test.ts
+ * pins both the source byte-hygiene and a known id value.
+ */
+export declare function findingId(f: Pick<PhilosophyFinding, "class" | "file" | "symbol">): string;
+/** A finding as persisted in a snapshot/baseline file. */
+export type PersistedFinding = PhilosophyFinding & {
+    readonly id: string;
+};
+export type ScopeAuditSnapshot = {
+    readonly version: 1;
+    readonly generatedAt: string;
+    /** Actionable findings only — see `isActionableFinding`. */
+    readonly findings: ReadonlyArray<PersistedFinding>;
+};
+export declare const SCOPE_AUDIT_RELPATH = ".crewhaus/scope-audit";
+export declare const SCOPE_AUDIT_BASELINE_FILENAME = "baseline.json";
+export declare function scopeAuditDir(rootDir: string): string;
+export declare function scopeAuditBaselinePath(rootDir: string): string;
+/** Dated snapshot path: `.crewhaus/scope-audit/<YYYY-MM-DD>.json` (UTC).
+ *  Re-running on the same day overwrites — the snapshot is a deterministic
+ *  function of the tree, so the latest run of the day is the record. */
+export declare function scopeAuditSnapshotPath(rootDir: string, now: () => number): string;
+/**
+ * What gets persisted (and therefore baselined/gated): hard failures, plus
+ * boundary-drift reports (which are warn-tier in plain mode but exactly the
+ * findings the drift watch exists to gate). Green checks and benign
+ * environment warns (e.g. "sibling ../docs not cloned") are excluded — they
+ * are not findings, and baselining them would make an absent docs checkout
+ * flip the gate.
+ */
+export declare function isActionableFinding(f: PhilosophyFinding): boolean;
+export declare function buildScopeAuditSnapshot(findings: ReadonlyArray<PhilosophyFinding>, now?: () => number): ScopeAuditSnapshot;
+/** Thrown on a malformed baseline/snapshot file. The CLI routes it through
+ *  `die()` — a gate whose accepted-set is unreadable must fail loudly, not
+ *  silently treat everything (or nothing) as new. */
+export declare class ScopeAuditBaselineError extends Error {
+    readonly name = "ScopeAuditBaselineError";
+}
+/** Read + validate a snapshot file; undefined when it does not exist. */
+export declare function loadScopeAuditSnapshot(path: string): ScopeAuditSnapshot | undefined;
+/** Gate verdict, following regression-runner's `gate()` shape
+ *  (verdict / reason / report arrays). */
+export type ScopeAuditGateVerdict = {
+    readonly verdict: "pass" | "fail";
+    readonly reason?: string;
+    /** In current but not the baseline — the ONLY thing that fails the gate. */
+    readonly newFindings: ReadonlyArray<PersistedFinding>;
+    /** In both — legacy accepted findings; never block. */
+    readonly acceptedFindings: ReadonlyArray<PersistedFinding>;
+    /** In the baseline but no longer current — fixed since acceptance. */
+    readonly resolvedFindings: ReadonlyArray<PersistedFinding>;
+};
+/**
+ * Diff the current snapshot against the last accepted baseline. Identity is
+ * the stable finding id, so wording changes don't churn the diff. A missing
+ * baseline (`undefined`) fails IF there is anything to accept — a gate that
+ * silently passed forever because nobody ever ran --accept-baseline would
+ * fabricate assurance — and passes on a genuinely clean tree.
+ */
+export declare function diffScopeAuditSnapshots(baseline: ScopeAuditSnapshot | undefined, current: ScopeAuditSnapshot): ScopeAuditGateVerdict;
+/**
+ * Scan `<repoRoot>/packages/<name>/src` for cross-trust ingress signals and
+ * flag packages that match one but never reference the classification
+ * fabric ({@link CLASSIFICATION_MARKERS}). Report-only by design: findings
+ * come back `pass: true, warn: true` so plain `doctor --philosophy-alignment`
+ * keeps exiting 0 on them; the --baseline gate is what fails, and only on
+ * findings that are NEW relative to the accepted baseline.
+ *
+ * Returns [] when `<repoRoot>/packages` does not exist (the audit is
+ * factory-repo-shaped, like the six-site check it extends).
+ */
+export declare function detectBoundaryDrift(repoRoot: string): PhilosophyFinding[];
+/** Render the gate verdict as the CLI's summary lines (baseline mode). */
+export declare function renderGateReport(diff: ScopeAuditGateVerdict): ReadonlyArray<string>;

package/dist/scope-audit-drift.js

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Stable finding id: sha256 over the (class, file, symbol) identity triple,
+ * truncated to 12 hex chars (48 bits — collision-safe at this cardinality
+ * and short enough to read in a diff). Labels and reasons are excluded on
+ * purpose: rewording a message must not orphan a baselined finding.
+ *
+ * The NUL separator makes the triple unambiguous (no field can contain it).
+ * It MUST stay the `\u0000` ESCAPE SEQUENCE in this source: a literal NUL
+ * byte makes git treat the whole module as a binary blob (unreviewable
+ * diffs) and invites silent id-invalidation by NUL-stripping tools. The
+ * escape and the literal produce identical runtime bytes, so every existing
+ * findingId and accepted baseline stays valid — scope-audit-drift.test.ts
+ * pins both the source byte-hygiene and a known id value.
+ */
+export function findingId(f) {
+    return createHash("sha256")
+        .update(`${f.class}\u0000${f.file}\u0000${f.symbol}`)
+        .digest("hex")
+        .slice(0, 12);
+}
+export const SCOPE_AUDIT_RELPATH = ".crewhaus/scope-audit";
+export const SCOPE_AUDIT_BASELINE_FILENAME = "baseline.json";
+export function scopeAuditDir(rootDir) {
+    return join(rootDir, SCOPE_AUDIT_RELPATH);
+}
+export function scopeAuditBaselinePath(rootDir) {
+    return join(scopeAuditDir(rootDir), SCOPE_AUDIT_BASELINE_FILENAME);
+}
+/** Dated snapshot path: `.crewhaus/scope-audit/<YYYY-MM-DD>.json` (UTC).
+ *  Re-running on the same day overwrites — the snapshot is a deterministic
+ *  function of the tree, so the latest run of the day is the record. */
+export function scopeAuditSnapshotPath(rootDir, now) {
+    return join(scopeAuditDir(rootDir), `${new Date(now()).toISOString().slice(0, 10)}.json`);
+}
+/**
+ * What gets persisted (and therefore baselined/gated): hard failures, plus
+ * boundary-drift reports (which are warn-tier in plain mode but exactly the
+ * findings the drift watch exists to gate). Green checks and benign
+ * environment warns (e.g. "sibling ../docs not cloned") are excluded — they
+ * are not findings, and baselining them would make an absent docs checkout
+ * flip the gate.
+ */
+export function isActionableFinding(f) {
+    return !f.pass || f.class === "boundary-drift";
+}
+export function buildScopeAuditSnapshot(findings, now = () => Date.now()) {
+    const actionable = findings
+        .filter(isActionableFinding)
+        .map((f) => ({ ...f, id: findingId(f) }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return { version: 1, generatedAt: new Date(now()).toISOString(), findings: actionable };
+}
+/** Thrown on a malformed baseline/snapshot file. The CLI routes it through
+ *  `die()` — a gate whose accepted-set is unreadable must fail loudly, not
+ *  silently treat everything (or nothing) as new. */
+export class ScopeAuditBaselineError extends Error {
+    name = "ScopeAuditBaselineError";
+}
+/** Read + validate a snapshot file; undefined when it does not exist. */
+export function loadScopeAuditSnapshot(path) {
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new ScopeAuditBaselineError(`${path} is not valid JSON (${err.message}) — re-accept with --accept-baseline`);
+    }
+    const snap = parsed;
+    if (snap.version !== 1 || !Array.isArray(snap.findings)) {
+        throw new ScopeAuditBaselineError(`${path} is not a v1 scope-audit snapshot — re-accept with --accept-baseline`);
+    }
+    return parsed;
+}
+/**
+ * Diff the current snapshot against the last accepted baseline. Identity is
+ * the stable finding id, so wording changes don't churn the diff. A missing
+ * baseline (`undefined`) fails IF there is anything to accept — a gate that
+ * silently passed forever because nobody ever ran --accept-baseline would
+ * fabricate assurance — and passes on a genuinely clean tree.
+ */
+export function diffScopeAuditSnapshots(baseline, current) {
+    if (baseline === undefined) {
+        if (current.findings.length === 0) {
+            return { verdict: "pass", newFindings: [], acceptedFindings: [], resolvedFindings: [] };
+        }
+        return {
+            verdict: "fail",
+            reason: `no accepted baseline and ${current.findings.length} finding(s) present — review them and run \`crewhaus doctor --philosophy-alignment --accept-baseline\``,
+            newFindings: [...current.findings],
+            acceptedFindings: [],
+            resolvedFindings: [],
+        };
+    }
+    const baselineById = new Map(baseline.findings.map((f) => [f.id, f]));
+    const currentIds = new Set(current.findings.map((f) => f.id));
+    const newFindings = current.findings.filter((f) => !baselineById.has(f.id));
+    const acceptedFindings = current.findings.filter((f) => baselineById.has(f.id));
+    const resolvedFindings = baseline.findings.filter((f) => !currentIds.has(f.id));
+    if (newFindings.length > 0) {
+        return {
+            verdict: "fail",
+            reason: `${newFindings.length} NEW finding(s) not in the accepted baseline (${newFindings
+                .map((f) => f.id)
+                .join(", ")})`,
+            newFindings,
+            acceptedFindings,
+            resolvedFindings,
+        };
+    }
+    return { verdict: "pass", newFindings, acceptedFindings, resolvedFindings };
+}
+// ---------------------------------------------------------------------------
+// Boundary-site drift detection
+// ---------------------------------------------------------------------------
+/**
+ * Markers that a package participates in the classification fabric. Any of
+ * these appearing in a package's sources exempts it from drift findings:
+ *   - classifyBoundary / boundary-classifier — the chokepoint itself;
+ *   - classifyInbound — channel-adapter-base's wrapper around it;
+ *   - chain-adapter-base — whose shared ingress helper classifies centrally,
+ *     so concrete chain adapters routing through it are covered.
+ * Same substring mechanism as the existing six-site check in index.ts.
+ */
+const CLASSIFICATION_MARKERS = [
+    "classifyBoundary",
+    "boundary-classifier",
+    "classifyInbound",
+    "chain-adapter-base",
+];
+/**
+ * Conservative cross-trust ingress signals, derived from the
+ * boundary-classifier TrustOrigin taxonomy. Deliberately small: each signal
+ * is a strong indicator that server/peer/user-controlled content enters the
+ * process. (Weak signals — e.g. the literal "SKILL.md", which appears in
+ * emitters and doc comments across the tree — are excluded; the baseline
+ * mechanism handles honest false positives, but the detector should not
+ * manufacture them.)
+ */
+const DRIFT_SIGNALS = [
+    {
+        symbol: "mcp-sdk-ingress",
+        origin: "mcp",
+        description: "imports the raw MCP SDK (server-controlled payloads enter here)",
+        contentNeedle: "@modelcontextprotocol/",
+    },
+    {
+        symbol: "federation-peer-ingress",
+        origin: "federation",
+        description: "consumes federation peer payloads (mTLS authenticates WHO, not WHAT)",
+        contentNeedle: "@crewhaus/federation-protocol",
+    },
+    {
+        symbol: "channel-inbound-ingress",
+        origin: "channel",
+        description: "normalizes inbound channel webhooks/messages",
+        packagePattern: /^channel-adapter-(?!base$).+/,
+    },
+    {
+        symbol: "chain-content-ingress",
+        origin: "chain",
+        description: "decodes chain RPC/event content",
+        packagePattern: /^chain-adapter-(?!base$).+/,
+    },
+];
+/** Concatenate a package's non-test .ts sources (recursively under src/). */
+function readPackageSources(srcDir) {
+    const chunks = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir).sort()) {
+            const full = join(dir, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue; // raced away / unreadable — skip, never crash the audit
+            }
+            if (isDir) {
+                walk(full);
+            }
+            else if (entry.endsWith(".ts") && !entry.endsWith(".test.ts") && !entry.endsWith(".d.ts")) {
+                try {
+                    chunks.push(readFileSync(full, "utf8"));
+                }
+                catch {
+                    // Unreadable source — skip; the audit reports on what it can see.
+                }
+            }
+        }
+    };
+    walk(srcDir);
+    return chunks.join("\n");
+}
+/**
+ * Scan `<repoRoot>/packages/<name>/src` for cross-trust ingress signals and
+ * flag packages that match one but never reference the classification
+ * fabric ({@link CLASSIFICATION_MARKERS}). Report-only by design: findings
+ * come back `pass: true, warn: true` so plain `doctor --philosophy-alignment`
+ * keeps exiting 0 on them; the --baseline gate is what fails, and only on
+ * findings that are NEW relative to the accepted baseline.
+ *
+ * Returns [] when `<repoRoot>/packages` does not exist (the audit is
+ * factory-repo-shaped, like the six-site check it extends).
+ */
+export function detectBoundaryDrift(repoRoot) {
+    const packagesDir = join(repoRoot, "packages");
+    if (!existsSync(packagesDir))
+        return [];
+    const findings = [];
+    for (const pkgName of readdirSync(packagesDir).sort()) {
+        const srcDir = join(packagesDir, pkgName, "src");
+        if (!existsSync(srcDir))
+            continue;
+        const source = readPackageSources(srcDir);
+        if (source === "")
+            continue;
+        const classified = CLASSIFICATION_MARKERS.some((m) => source.includes(m));
+        if (classified)
+            continue;
+        for (const signal of DRIFT_SIGNALS) {
+            const matches = signal.contentNeedle !== undefined
+                ? source.includes(signal.contentNeedle)
+                : signal.packagePattern.test(pkgName);
+            if (!matches)
+                continue;
+            const file = `packages/${pkgName}/src`;
+            findings.push({
+                class: "boundary-drift",
+                file,
+                symbol: signal.symbol,
+                label: `Pillar 3 drift — ${pkgName} ${signal.description} without classifyBoundary`,
+                pass: true,
+                warn: true,
+                reason: `${file} matches the "${signal.symbol}" cross-trust ingress signal (origin: ${signal.origin}) but never references the boundary-classification fabric — a new ingress that skips classifyBoundary is a security regression (AGENTS.md Pillar 3). If this ingress is classified downstream by design, accept it into the baseline with --accept-baseline.`,
+            });
+        }
+    }
+    return findings;
+}
+/** Render the gate verdict as the CLI's summary lines (baseline mode). */
+export function renderGateReport(diff) {
+    const lines = [];
+    for (const f of diff.newFindings) {
+        lines.push(`✗ NEW [${f.id}] ${f.label}${f.reason !== undefined ? ` — ${f.reason}` : ""}`);
+    }
+    for (const f of diff.acceptedFindings) {
+        lines.push(`• accepted [${f.id}] ${f.label}`);
+    }
+    for (const f of diff.resolvedFindings) {
+        lines.push(`✓ resolved [${f.id}] ${f.label} — no longer present; re-accept to shrink the baseline`);
+    }
+    lines.push(`baseline gate: ${diff.verdict}${diff.reason !== undefined ? ` — ${diff.reason}` : ""} ` +
+        `(${diff.newFindings.length} new, ${diff.acceptedFindings.length} accepted, ${diff.resolvedFindings.length} resolved)`);
+    return lines;
+}

package/dist/security-corpus.d.ts

@@ -0,0 +1,237 @@
+import { type PromptInjectionResult } from "@crewhaus/prompt-injection-detector";
+/** Every real regex-rule id in the current detector. A parsed notice id must
+ *  be a member of this set to be admitted (drops forged/renamed ids). */
+export declare const RULE_IDS: ReadonlySet<string>;
+export type SinceWindow = {
+    readonly sinceMs: number;
+    readonly label: string;
+};
+/** `<N>d` trailing window (default all-time when undefined) — a small local
+ *  parser so the module has no dependency on security-digest's copy. */
+export declare function parseCorpusSince(value: string | undefined, now?: () => number): SinceWindow;
+export type ObservedRuleHit = {
+    readonly rule: string;
+    /** How many redaction notices in the window named this rule. */
+    readonly count: number;
+};
+export type HarvestResult = {
+    /** Session event logs scanned. */
+    readonly sessionsScanned: number;
+    /** Redaction notices (malicious verdicts) found in the window. */
+    readonly redactions: number;
+    /** Per-rule observed block counts, ranked by count then id. */
+    readonly ruleHits: ReadonlyArray<ObservedRuleHit>;
+    /**
+     * Ids parsed out of notices that are NOT current rules (forged, or a rule
+     * that was renamed/removed since the notice was written). Reported so a
+     * removed-rule regression is visible; never turned into a corpus case.
+     */
+    readonly unknownIds: ReadonlyArray<string>;
+};
+/**
+ * Scan `<rootDir>/.crewhaus/sessions` for prompt-injection redaction notices
+ * and tally which detector rules fired. A missing dir yields an empty harvest
+ * (no throw — the command reports emptiness, it is not a gate on presence).
+ */
+export declare function harvestBlockedAttempts(opts: {
+    readonly rootDir: string;
+    readonly window: SinceWindow;
+}): HarvestResult;
+/**
+ * A small, deterministic exemplar STRING that a given rule matches, built at
+ * runtime from parts so no attack literal is stored in this source (and so a
+ * secret-shaped token in the exemplar is assembled, not committed — GitHub
+ * push-protection). Each entry is a minimal phrase the corresponding
+ * REGEX_RULES pattern hits; the mapping is asserted by the tests, so a rule
+ * whose exemplar stops matching (a pattern edit) is caught immediately.
+ *
+ * Rules without a hand-written exemplar fall back to `undefined`; the corpus
+ * still records the observed rule but the check treats it as
+ * "exemplar-unavailable" rather than a regression (a missing exemplar is a
+ * corpus gap, not a detector failure).
+ */
+export declare function exemplarForRule(ruleId: string): string | undefined;
+export type CorpusCase = {
+    /** Detector rule this case guards against regressing. */
+    readonly rule: string;
+    /** Observed production block count that motivated the case. */
+    readonly observed: number;
+    /** Deterministic positive fixture the detector must still block. Assembled
+     *  at runtime; never a harvested attack payload. */
+    readonly exemplar: string;
+    /**
+     * The exemplar's classification tier AT BUILD TIME (F2). `check` compares
+     * the CURRENT classification against this recorded baseline rather than a
+     * fixed "not clean" floor — a rule that used to earn `malicious` and now
+     * only reaches `suspicious` is real protection lost (only `malicious`
+     * redacts at runtime; `suspicious` content is passed through verbatim), so
+     * that drift must fail even though `suspicious !== clean`. A case built
+     * BEFORE this field existed (no `baselineTier` in the loaded JSON) falls
+     * back to the pre-F2 "not clean" floor — see `checkSecurityCorpus`.
+     */
+    readonly baselineTier: PromptInjectionResult["classification"];
+};
+export type SecurityCorpus = {
+    readonly version: 1;
+    readonly generatedAt: string;
+    readonly windowLabel: string;
+    /** Rules with a canonical exemplar that were observed blocking. */
+    readonly cases: ReadonlyArray<CorpusCase>;
+    /** Rules observed blocking but with no exemplar yet (corpus gaps). */
+    readonly withoutExemplar: ReadonlyArray<ObservedRuleHit>;
+    /** Notice ids that are not current rules (removed/renamed/forged). */
+    readonly unknownIds: ReadonlyArray<string>;
+};
+/**
+ * Build the regression corpus from a harvest. One case per observed rule that
+ * has a canonical exemplar; observed-but-exemplar-less rules are kept
+ * separately as gaps. Deterministic given (harvest, generatedAt) — `async`
+ * because each case's `baselineTier` (F2) is the exemplar's CURRENT
+ * classification, recorded once at build time so `check` can detect a later
+ * downward drift rather than only an absolute drop to `clean`.
+ */
+export declare function buildSecurityCorpus(harvest: HarvestResult, windowLabel: string, generatedAt?: string): Promise<SecurityCorpus>;
+export declare function corpusDir(rootDir: string): string;
+export declare function corpusPath(rootDir: string): string;
+export declare function candidateRulesPath(rootDir: string): string;
+/** Thrown on a malformed corpus file; the CLI routes it through `die()`. */
+export declare class SecurityCorpusError extends Error {
+    readonly name = "SecurityCorpusError";
+}
+export declare function loadSecurityCorpus(path: string): SecurityCorpus | undefined;
+export type CorpusCheckCaseResult = {
+    readonly rule: string;
+    /** Current detector classification of the exemplar. */
+    readonly classification: PromptInjectionResult["classification"];
+    /** The tier this case was pinned at when the corpus was built (F2). Cases
+     *  loaded from a pre-F2 corpus file have no recorded baseline; see
+     *  `checkSecurityCorpus` for the fallback in that case. */
+    readonly baselineTier: PromptInjectionResult["classification"] | undefined;
+    /**
+     * Passed = the CURRENT tier has not dropped below the RECORDED baseline
+     * tier (F2: drift, not an absolute `=== malicious` floor).
+     *
+     * At runtime only `malicious` redacts a tool output; `suspicious` content
+     * is passed through to the model verbatim (only logged/warned). So a rule
+     * that used to earn `malicious` and has drifted down to `suspicious` is
+     * real protection lost, even though the exemplar is still "not clean" —
+     * `stillBlocked` catches that drift where a bare `!== "clean"` check would
+     * pass it. A rule whose baseline was only ever `suspicious` (a single
+     * medium-severity rule, or a multi-rule payload that only reaches
+     * `suspicious` on its own — the detector's probabilistic-OR score makes the
+     * exact tier of a canonical single-rule exemplar an implementation detail)
+     * still passes as long as it holds at `suspicious`; it only fails if it
+     * drops all the way to `clean`. Pre-F2 corpus cases with no recorded
+     * baseline fall back to that same "not clean" floor.
+     */
+    readonly stillBlocked: boolean;
+};
+export type CorpusCheckResult = {
+    readonly verdict: "pass" | "fail";
+    readonly checked: number;
+    readonly regressions: ReadonlyArray<CorpusCheckCaseResult>;
+    readonly holding: ReadonlyArray<CorpusCheckCaseResult>;
+};
+/**
+ * Run every corpus case against the CURRENT detector and fail if any case's
+ * classification has DRIFTED DOWN from its recorded `baselineTier` (F2) — a
+ * detector regression, whether that drop is malicious→suspicious (real
+ * protection lost: only `malicious` redacts at runtime) or a drop all the way
+ * to `clean` (the rule stopped catching the attack entirely). A case with no
+ * recorded baseline (loaded from a pre-F2 corpus file) falls back to the
+ * original "not clean" floor. Exit-code-usable: the CLI maps
+ * `verdict === "fail"` to a non-zero exit. Uses `classifyText` with
+ * production defaults (no LLM layer), so the check is deterministic and
+ * offline.
+ */
+export declare function checkSecurityCorpus(corpus: SecurityCorpus): Promise<CorpusCheckResult>;
+/**
+ * A tool_result the detector scored `suspicious` (not blocked) but which
+ * carries the shape of an attack — a NEAR-MISS. The runtime keeps suspicious
+ * content verbatim (it only warns), so unlike malicious redactions the
+ * suspicious payloads ARE durable in the session log. We cannot know which
+ * were truly hostile, so these feed CANDIDATE rules for HUMAN review — never
+ * an auto-merge into REGEX_RULES.
+ */
+export type NearMiss = {
+    /** The (sanitized, redacted) suspicious content snippet. */
+    readonly snippet: string;
+    /** Structural signal that made it a near-miss (see NEAR_MISS_SIGNALS). */
+    readonly signal: string;
+};
+/**
+ * Deterministic structural signals for near-miss clustering. Each is a strong
+ * "looks like an instruction-injection attempt" shape that the current
+ * REGEX_RULES do NOT already hard-block. Kept conservative — a candidate rule
+ * a human ignores is cheap; a false candidate that gets merged is not (which
+ * is why merge is never automatic).
+ */
+export declare const NEAR_MISS_SIGNALS: ReadonlyArray<{
+    signal: string;
+    test: RegExp;
+}>;
+/**
+ * Redact anything PII/secret-shaped from a near-miss snippet, run through the
+ * SAME strong detector set the dataset/knowledge synthesis paths use
+ * (`SYNTHESIZE_PII_DETECTORS`, plus JWT/PEM — see `CANDIDATE_SECRET_DETECTORS`)
+ * rather than the narrow ad hoc email/blob/digit patterns this used to apply.
+ * This is used ONLY for in-memory clustering (dedup/support counting); the
+ * PERSISTED `candidate-rules.json` never stores this snippet at all — see
+ * `hashDescriptor` and F1. Deterministic, no raw values retained.
+ */
+export declare function redactSnippet(text: string): string;
+/** First 16 hex chars of SHA-256(redacted snippet) — a stable, non-reversible
+ *  descriptor for the reviewer's dedup/audit trail. Deliberately NOT an HMAC
+ *  (no per-tenant secret is plumbed into this module; this hash is a display
+ *  aid, not an allow-list key like `pii-redactor`'s `hmacValue`), and hashed
+ *  AFTER redaction so it identifies a "shape" (redacted form), never a raw
+ *  secret/PII value. */
+export declare function hashDescriptor(redacted: string): string;
+export type CandidateRule = {
+    /** Proposed stable rule id (namespaced `candidate-<signal>`). */
+    readonly id: string;
+    readonly signal: string;
+    /** How many distinct near-miss snippets clustered under this signal. */
+    readonly support: number;
+    /**
+     * Up to a few short, fully-redacted descriptors of clustered snippets, for
+     * the reviewer's context — NEVER a raw or lightly-redacted sample. Each
+     * entry is `hash:<16-hex>` `[<kinds redacted>]` `<short prefix>` where the
+     * prefix has already passed through `redactSnippet`'s strong secret+PII
+     * detector set and is clamped to `SAMPLE_PREFIX_LENGTH` chars. See F1.
+     */
+    readonly samples: ReadonlyArray<string>;
+    /** A conservative proposed regex SOURCE (string, never compiled/merged). */
+    readonly proposedPattern: string;
+    readonly note: string;
+};
+/** Build the persisted, hash-first descriptor for one clustered snippet. The
+ *  snippet has ALREADY passed through `redactSnippet`'s strong detector set;
+ *  this additionally truncates hard to `SAMPLE_PREFIX_LENGTH` so no full-length
+ *  secret — redacted or not — round-trips into `candidate-rules.json`. */
+export declare function describeSample(redactedSnippet: string): string;
+export type CandidateRulesFile = {
+    readonly version: 1;
+    readonly generatedAt: string;
+    /** Minimum cluster support required to emit a candidate. */
+    readonly minSupport: number;
+    readonly candidates: ReadonlyArray<CandidateRule>;
+};
+/**
+ * Harvest suspicious (near-miss) tool outputs from durable session logs. These
+ * are `tool_result` contents that are NOT redaction notices but match a
+ * NEAR_MISS_SIGNAL. Content is sanitized + redacted at parse time.
+ */
+export declare function harvestNearMisses(opts: {
+    readonly rootDir: string;
+    readonly window: SinceWindow;
+}): NearMiss[];
+/**
+ * Cluster near-misses by structural signal and emit CANDIDATE detector rules
+ * for any signal with >= minSupport DISTINCT snippets. Deterministic: the same
+ * near-misses always yield the same candidates. Output is a reviewed file the
+ * operator reads — it is NEVER merged into REGEX_RULES automatically.
+ */
+export declare function clusterCandidateRules(nearMisses: ReadonlyArray<NearMiss>, minSupport?: number, generatedAt?: string): CandidateRulesFile;
+export declare function renderCorpusBuildLines(corpus: SecurityCorpus): ReadonlyArray<string>;
+export declare function renderCorpusCheckLines(result: CorpusCheckResult): ReadonlyArray<string>;