@jmtrin/kevin-core 1.3.0

package/dist/Migrate.d.ts

@@ -0,0 +1,24 @@
+import type { Store } from "./Store.js";
+/**
+ * K13-008 (D13-04) — core-owns-migrations. Returns the directory containing
+ * the SQL migration files, resolved relative to the compiled location.
+ * Works both when running from src via tsx (src/.. → migrations) and from
+ * dist (dist/migrations).
+ */
+export declare function exportMigrationsDir(): string;
+export interface MigrateResult {
+    from: string;
+    to: string;
+    applied: string[];
+}
+export type PostApplyHook = (store: Store) => void;
+export declare const HOOK_NAMES: readonly ["tool.execute.before", "tool.execute.after", "chat.message", "experimental.chat.system.transform", "experimental.session.compacting", "event", "dispose"];
+export declare class Migrate {
+    private store;
+    private migrationsDir;
+    private readonly postApplyHooks;
+    constructor(store: Store, migrationsDir: string, postApplyHooks?: Record<string, PostApplyHook>);
+    registerPostApply(version: string, hook: PostApplyHook): void;
+    run(): Promise<MigrateResult>;
+    private listPending;
+}

package/dist/Migrate.js

@@ -0,0 +1,285 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * K13-008 (D13-04) — core-owns-migrations. Returns the directory containing
+ * the SQL migration files, resolved relative to the compiled location.
+ * Works both when running from src via tsx (src/.. → migrations) and from
+ * dist (dist/migrations).
+ */
+export function exportMigrationsDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const direct = join(here, "migrations");
+    if (existsSync(direct))
+        return direct;
+    return join(here, "..", "migrations");
+}
+// v0.9.0 (K9-001 / plan §5.3, D9-08) — the six hooks Kevin registers, in
+// hook-object order, plus `dispose` (v1.0.0 K10-013): the seventh
+// instrumented hook. Canonical list: the "010" post-apply hook seeds
+// hook_liveness from it, and HookLiveness (K9-009) wraps exactly these
+// names, so a future hook added here is visible in the table on the next
+// migration run.
+export const HOOK_NAMES = [
+    "tool.execute.before",
+    "tool.execute.after",
+    "chat.message",
+    "experimental.chat.system.transform",
+    "experimental.session.compacting",
+    "event",
+    "dispose",
+];
+// Built-in post-apply hooks, keyed by migration version. Each hook runs inside
+// the same transaction as the migration's DDL, so a hook failure rolls back the
+// whole migration. Hooks run when their version is applied. Migration 008's
+// reconciliation hook is also safe to run on later no-op starts (K7-002).
+const DEFAULT_POST_APPLY_HOOKS = {
+    // v0.2.0 Signal Quality: defensive backfill of memories.origin for legacy
+    // rows. The column is NOT NULL DEFAULT 'agent', so SQLite already populates
+    // pre-existing rows with 'agent' on ALTER TABLE. This hook is a belt-and-
+    // braces UPDATE that coerces any NULL/empty stragglers (which would only
+    // exist if a partial DB skipped the DEFAULT) back to 'agent'.
+    "003": (store) => {
+        store
+            .prepare("UPDATE memories SET origin = 'agent' WHERE origin IS NULL OR origin = ''")
+            .run();
+    },
+    // v0.3.0 Knowledge + Causality: backfill evidence_count and status for
+    // legacy rows. Columns have NOT NULL DEFAULT, so SQLite already populates
+    // pre-existing rows. This hook is belt-and-braces in case a partial DB
+    // skipped the defaults.
+    "004": (store) => {
+        store
+            .prepare("UPDATE memories SET evidence_count = 0 WHERE evidence_count IS NULL")
+            .run();
+        store
+            .prepare("UPDATE memories SET status = 'active' WHERE status IS NULL OR status = ''")
+            .run();
+    },
+    // v0.4.0 Signal over Noise: backfill recurrence_count for legacy rows.
+    // recurrence_count has NOT NULL DEFAULT 0, so SQLite already populates
+    // pre-existing rows; fix_args and last_injected_at are nullable and need
+    // no coercion. This hook is belt-and-braces in case a partial DB skipped
+    // the defaults.
+    "005": (store) => {
+        store
+            .prepare("UPDATE memories SET recurrence_count = 0 WHERE recurrence_count IS NULL")
+            .run();
+    },
+    // v0.5.0 (K5-002 / plan §6, D5-13) — Glass Box: re-derive the four
+    // injection counters from the ledger table instead of incrementing them.
+    // The rebuild remapped prior `effective` rows to `inconclusive`, so any
+    // pre-existing counter values would otherwise carry the v0.4 confound
+    // forward. Re-derivation is idempotent by construction and self-healing
+    // on earlier drift. No INSERTs: the rows are seeded by the migration SQL;
+    // a missing row makes the UPDATE a harmless no-op.
+    "006": (store) => {
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM kevin_injections) WHERE key = 'injections_total'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM kevin_injections WHERE outcome = 'effective') WHERE key = 'injections_effective'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM kevin_injections WHERE outcome = 'ineffective') WHERE key = 'injections_ineffective'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM kevin_injections WHERE outcome = 'inconclusive') WHERE key = 'injections_inconclusive'")
+            .run();
+    },
+    // v0.6.0 (K6-002 / plan §6, D6-08) — Pull: three re-derivations, all
+    // idempotent by re-derivation (same discipline as "006", D5-13).
+    // 1. Back-fill `inferable = 0` for the four non-`error` types still NULL:
+    //    they are `non_inferable` by rules 1 and 2 of plan §5.3
+    //    unconditionally. Guarded by `inferable IS NULL` so a re-run cannot
+    //    overwrite a classification produced later by inferability.classify().
+    //    `error` rows are left NULL and classified lazily.
+    // 2-3. proposals_created / artifact_writes_total are re-derived from
+    //    their tables; a missing row makes the UPDATE a harmless no-op.
+    "007": (store) => {
+        store
+            .prepare("UPDATE memories SET inferable = 0 WHERE inferable IS NULL AND type IN ('decision','rule','solution','pattern')")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM curation_proposals) WHERE key = 'proposals_created'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM artifact_writes WHERE outcome = 'written') WHERE key = 'artifact_writes_total'")
+            .run();
+    },
+    // v0.7.0 (K7-002 / plan §6, D7-02) — Truth: four re-derivations, all
+    // idempotent by re-derivation (same discipline as "006"/"007", D5-13).
+    // 1. Normalize any NULL truth_penalty to 0.0 (belt-and-braces; the column
+    //    is NOT NULL DEFAULT 0.0, so SQLite already back-fills on ALTER TABLE).
+    // 2-4. repo_facts_scanned / conflicts_detected / memories_contradicted
+    //    are re-derived from their tables, NOT trusted from the counters, so
+    //    the metrics survive a database restored from backup or edited by
+    //    hand. A missing row makes the UPDATE a harmless no-op.
+    "008": (store) => {
+        store
+            .prepare("UPDATE memories SET truth_penalty = 0.0 WHERE truth_penalty IS NULL")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM repo_facts) WHERE key = 'repo_facts_scanned'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM memory_conflicts) WHERE key = 'conflicts_detected'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM memories WHERE truth_penalty > 0.0) WHERE key = 'memories_contradicted'")
+            .run();
+    },
+    // v0.8.0 (K8-002 / plan §6.1, D8-03) — Team: three operations, all
+    // idempotent by re-derivation (same discipline as "006"/"007"/"008").
+    // 1. Back-fill the new scope from the old one: repo_id = project_id
+    //    keeps every pre-v0.8 row retrievable on the same machine with an
+    //    identical result set. Guarded by `repo_id IS NULL`; a row whose
+    //    project_id is also NULL keeps a NULL repo_id — the retrieval
+    //    path handles NULL as global (K8-007) instead of the hook faking
+    //    a value. No git-derived identity here: the hook runs inside a
+    //    migration and must not read the filesystem (K8-002 criterion).
+    // 2. Normalize the layer marker for any row written by a concurrent
+    //    v0.7.0 process between ALTER and hook (belt and braces; the
+    //    column DEFAULT already covers the ordinary case).
+    // 3. Re-derive shared_entries_total from state rather than trusting
+    //    an incremented value that may predate a crash.
+    "009": (store) => {
+        store
+            .prepare("UPDATE memories SET repo_id = project_id WHERE repo_id IS NULL")
+            .run();
+        store
+            .prepare("UPDATE memories SET layer = 'local' WHERE layer IS NULL OR layer = ''")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM shared_entries) WHERE key = 'shared_entries_total'")
+            .run();
+    },
+    // v0.9.0 (K9-001 / plan §6.1, D9-08) — Native: three operations, all
+    // idempotent by design.
+    // 1. Seed one hook_liveness row per name in HOOK_NAMES, with the
+    //    experimental flag derived from the hook's own `experimental.`
+    //    prefix and every counter at zero. Seeding eagerly (INSERT OR
+    //    IGNORE) makes a hook that has never fired a visible row with
+    //    fire_count = 0, not an absent row indistinguishable from a hook
+    //    Kevin does not register.
+    // 2. Re-derive hooks_dead_total from hook_liveness state rather than
+    //    trusting an incremented value (same discipline as "006"-"009").
+    // 3. Normalize any experimental flag that disagrees with its own
+    //    hook column's prefix — cheap, and it repairs a row hand-edited
+    //    during debugging.
+    "010": (store) => {
+        const seed = store.prepare("INSERT OR IGNORE INTO hook_liveness (hook, experimental) VALUES (?, ?)");
+        for (const name of HOOK_NAMES) {
+            seed.run(name, name.startsWith("experimental.") ? 1 : 0);
+        }
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM hook_liveness WHERE dead_since IS NOT NULL) WHERE key = 'hooks_dead_total'")
+            .run();
+        store
+            .prepare("UPDATE hook_liveness SET experimental = CASE WHEN hook LIKE 'experimental.%' THEN 1 ELSE 0 END")
+            .run();
+    },
+    // v1.0.0 (K10-005 / plan §6.1) — Proven: four operations, all idempotent.
+    // 1. Seed dispose row defensively.
+    // 2-3. Re-derive perf_budget_breaches and bench_runs_total.
+    // 4. Normalise NULL within_budget to 1.
+    "011": (store) => {
+        store
+            .prepare("INSERT OR IGNORE INTO hook_liveness (hook) VALUES ('dispose')")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM perf_samples WHERE within_budget = 0) WHERE key = 'perf_budget_breaches'")
+            .run();
+        store
+            .prepare("UPDATE kevin_metrics SET value = (SELECT COUNT(*) FROM bench_runs) WHERE key = 'bench_runs_total'")
+            .run();
+        store
+            .prepare("UPDATE perf_samples SET within_budget = 1 WHERE within_budget IS NULL")
+            .run();
+    },
+};
+export class Migrate {
+    store;
+    migrationsDir;
+    postApplyHooks;
+    constructor(store, migrationsDir, postApplyHooks) {
+        this.store = store;
+        this.migrationsDir = migrationsDir;
+        this.postApplyHooks = new Map(Object.entries({
+            ...DEFAULT_POST_APPLY_HOOKS,
+            ...(postApplyHooks ?? {}),
+        }));
+    }
+    registerPostApply(version, hook) {
+        this.postApplyHooks.set(version, hook);
+    }
+    async run() {
+        this.store.exec(`CREATE TABLE IF NOT EXISTS schema_version (
+         version TEXT PRIMARY KEY,
+         applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+       );`);
+        const currentRow = this.store
+            .prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1")
+            .get();
+        const from = currentRow?.version ?? "000";
+        const pending = this.listPending(from);
+        if (pending.length === 0) {
+            // v0.7.0 (K7-002) — heal drift in the 008 counters on a no-op
+            // startup while preserving `applied: []` idempotency. v0.8.0
+            // (K8-002 / plan §6.1) extends the same repair to the 009
+            // back-fill and the shared_entries_total re-derivation, and
+            // v0.9.0 (K9-001 / plan §6.1) to the 010 seeding,
+            // hooks_dead_total re-derivation and experimental
+            // normalization: all three hooks are idempotent by guarded
+            // updates and re-derivation, so a no-op startup can heal a
+            // crash that landed between the DDL and the hook without
+            // re-applying DDL.
+            if (from === "008" ||
+                from === "009" ||
+                from === "010" ||
+                from === "011") {
+                const repairHook = this.postApplyHooks.get(from);
+                if (repairHook)
+                    this.store.transaction(() => repairHook(this.store));
+            }
+            return { from, to: from, applied: [] };
+        }
+        const insertVersion = this.store.prepare("INSERT OR IGNORE INTO schema_version (version) VALUES (?)");
+        for (const migration of pending) {
+            const sql = readFileSync(join(this.migrationsDir, migration.file), "utf8");
+            this.store.transaction(() => {
+                this.store.exec(sql);
+                const hook = this.postApplyHooks.get(migration.version);
+                if (hook)
+                    hook(this.store);
+                insertVersion.run(migration.version);
+            });
+        }
+        return {
+            from,
+            to: pending[pending.length - 1].version,
+            applied: pending.map((m) => m.version),
+        };
+    }
+    // v1.1.0 (K11-015) — lexicographic ordering is valid through "999" because
+    // versions are zero-padded 3-digit strings ("001" … "999"). Any future
+    // migration beyond 999 must use a 4-digit prefix and this comparison must
+    // become numeric (parseInt). Until then, string > works and keeps the
+    // migration idempotency simple (plan §5.5, D11-??).
+    listPending(current) {
+        let files = [];
+        try {
+            files = readdirSync(this.migrationsDir).filter((f) => f.endsWith(".sql"));
+        }
+        catch {
+            return [];
+        }
+        files.sort();
+        return files
+            .map((file) => {
+            const match = file.match(/^(\w+?)_/);
+            return match ? { version: match[1], file } : null;
+        })
+            .filter((m) => m !== null && m.version > current);
+    }
+}

package/dist/PatternMiner.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * v0.2.0 PatternMiner (K2-021, plan §B6.10 / D2-08).
+ *
+ * Opt-in deterministic pattern miner. Reads recent `tool_calls` for a given
+ * project, groups consecutive ordered 2-grams of `(tool_name)` and 3-grams
+ * where the *middle* tool was a failure, and when a group reaches the
+ * threshold (default `N ≥ 5` distinct sessions), emits a single
+ * `type='pattern'`, `origin='pattern'` memory describing the pattern.
+ *
+ * Default OFF — must be enabled by setting `kevin_settings.patternminer_enabled`
+ * to `'1'`. Idempotent via SELECT-before-INSERT keyed on
+ * `(project_id, fingerprint, type='pattern', origin='pattern')`. Migration 003's
+ * partial UNIQUE index only covers `type='error' AND origin='reflector'`, so
+ * pattern memories cannot rely on a database uniqueness constraint — the
+ * SELECT check inside `mine()` is the single idempotency mechanism.
+ *
+ * NO LLM hop (D2-08). The emitted suggestion is a deterministic template built
+ * from the captured tool names.
+ */
+export interface PatternMinerOptions {
+    /** Minimum distinct sessions a pattern must appear in before emission.
+     * Default 5 (D2-08). */
+    threshold?: number;
+}
+export declare class PatternMiner {
+    private readonly store;
+    private readonly memoryService;
+    private readonly metrics;
+    private readonly threshold;
+    constructor(store: Store, memoryService: MemoryService, metrics?: Metrics | null, options?: PatternMinerOptions);
+    /**
+     * Mine patterns observed in `tool_calls` for the given project. Returns the
+     * number of NEW `pattern` memories emitted this cycle.
+     *
+     * When the opt-in flag `kevin_settings.patternminer_enabled` is not set to
+     * `'1'` (default), this is a no-op and returns 0.
+     *
+     * When `projectId` is null/undefined, mines tool_calls whose `project_id`
+     * IS NULL (legacy / opt-out flow). When `projectId` is a string, mines
+     * tool_calls scoped to that project only.
+     */
+    mine(projectId?: string | null): number;
+    private isEnabled;
+    private fetchToolCalls;
+    private collectCandidates;
+}

package/dist/PatternMiner.js

@@ -0,0 +1,132 @@
+import { fingerprint as computeFingerprint } from "./fingerprint.js";
+const DEFAULT_THRESHOLD = 5;
+const SETTING_KEY = "patternminer_enabled";
+export class PatternMiner {
+    store;
+    memoryService;
+    metrics;
+    threshold;
+    constructor(store, memoryService, metrics, options) {
+        this.store = store;
+        this.memoryService = memoryService;
+        this.metrics = metrics ?? null;
+        this.threshold = options?.threshold ?? DEFAULT_THRESHOLD;
+    }
+    /**
+     * Mine patterns observed in `tool_calls` for the given project. Returns the
+     * number of NEW `pattern` memories emitted this cycle.
+     *
+     * When the opt-in flag `kevin_settings.patternminer_enabled` is not set to
+     * `'1'` (default), this is a no-op and returns 0.
+     *
+     * When `projectId` is null/undefined, mines tool_calls whose `project_id`
+     * IS NULL (legacy / opt-out flow). When `projectId` is a string, mines
+     * tool_calls scoped to that project only.
+     */
+    mine(projectId) {
+        if (!this.isEnabled())
+            return 0;
+        const rows = this.fetchToolCalls(projectId ?? null);
+        if (rows.length === 0)
+            return 0;
+        const candidates = this.collectCandidates(rows);
+        if (candidates.length === 0)
+            return 0;
+        let emitted = 0;
+        for (const c of candidates) {
+            if (c.sessions.size < this.threshold)
+                continue;
+            const fp = computeFingerprint(c.content, projectId ?? undefined);
+            // Idempotency: migration 003's partial unique only covers
+            // (type='error', origin='reflector'). For pattern memories we
+            // SELECT to detect a prior emission with the same
+            // (project_id, fingerprint, type='pattern', origin='pattern').
+            const existing = this.store
+                .prepare(`SELECT id FROM memories
+					 WHERE type = 'pattern' AND origin = 'pattern'
+					   AND fingerprint = ?
+					   AND (project_id IS ? OR (project_id IS NULL AND ? IS NULL))
+					 LIMIT 1`)
+                .get(fp, projectId ?? null, projectId ?? null);
+            if (existing)
+                continue;
+            this.memoryService.save({
+                type: "pattern",
+                origin: "pattern",
+                fingerprint: fp,
+                content: c.content,
+                scope: "project",
+                projectId: projectId ?? undefined,
+                relevanceScore: 0.5,
+                sourceTool: "PatternMiner",
+            });
+            this.metrics?.incr("patterns_mined", 1);
+            emitted += 1;
+        }
+        return emitted;
+    }
+    isEnabled() {
+        const row = this.store
+            .prepare("SELECT value FROM kevin_settings WHERE key = ?")
+            .get(SETTING_KEY);
+        return row?.value === "1";
+    }
+    fetchToolCalls(projectId) {
+        const nullPid = projectId === null || projectId === undefined;
+        const sql = nullPid
+            ? `SELECT id, session_id, ts, tool, success FROM tool_calls
+			   WHERE project_id IS NULL
+			   ORDER BY session_id ASC, ts ASC`
+            : `SELECT id, session_id, ts, tool, success FROM tool_calls
+			   WHERE project_id = ?
+			   ORDER BY session_id ASC, ts ASC`;
+        const stmt = this.store.prepare(sql);
+        const rows = (nullPid ? stmt.all() : stmt.all(projectId));
+        return rows;
+    }
+    collectCandidates(rows) {
+        // Group rows by session_id preserving arrival order. The SQL already
+        // orders by (session_id ASC, ts ASC), so a sequential scan yields each
+        // session's tool_calls in execution order.
+        const bySession = new Map();
+        for (const r of rows) {
+            let list = bySession.get(r.session_id);
+            if (!list) {
+                list = [];
+                bySession.set(r.session_id, list);
+            }
+            list.push(r);
+        }
+        // 2-grams: ordered pair (a, b) of consecutive tool names per session.
+        // 3-grams: ordered triple (a, b, c) where the middle tool b failed
+        // (success = 0). These capture the "X→Y fails then Z" lifecycle that
+        // the plan §B6.10 calls out.
+        const map = new Map();
+        const record = (key, content, sessionId) => {
+            let cand = map.get(key);
+            if (!cand) {
+                cand = { key, content, sessions: new Set() };
+                map.set(key, cand);
+            }
+            cand.sessions.add(sessionId);
+        };
+        for (const [sessionId, list] of bySession) {
+            for (let i = 0; i < list.length - 1; i++) {
+                const a = list[i];
+                const b = list[i + 1];
+                const key2 = `2g::${a.tool}::${b.tool}`;
+                const content2 = `Pattern: tool "${a.tool}" followed by tool "${b.tool}". Review the ${a.tool}→${b.tool} contract before retrying.`;
+                record(key2, content2, sessionId);
+                if (i + 2 < list.length) {
+                    const c = list[i + 2];
+                    if (b.success === 0) {
+                        const key3 = `3g::${a.tool}::${b.tool}::${c.tool}`;
+                        const content3 = `Pattern: tool "${a.tool}" followed by failing tool "${b.tool}" then tool "${c.tool}". Review the ${a.tool}→${b.tool}(failed)→${c.tool} contract before retrying.`;
+                        record(key3, content3, sessionId);
+                    }
+                }
+            }
+        }
+        return Array.from(map.values());
+    }
+}

package/dist/QualityGate.d.ts

@@ -0,0 +1,124 @@
+import type { DispatchedLesson } from "./Reflector.js";
+/**
+ * v0.4.0 (K4-003/K4-004 / plan §5.1) — QualityGate.
+ *
+ * Pure, NO-LLM predicates deciding whether a lesson is worth injecting into
+ * the model's prompt. Principle 11: never inject noise.
+ *
+ * - `evaluate` — classifies a lesson (rescued errorType, non-generic
+ *   suggestion, isActionable, strength).
+ * - `rescueErrorType` — a dispatched code overrides the coarse
+ *   `errorType` (e.g. `'unknown'` → `'TS2304'`), fixing the defect where
+ *   lessons said "fails with unknown" even when the Reflector DID identify
+ *   the error code.
+ * - `canInject` — per-session + per-fingerprint admission rules (K4-004).
+ */
+/** The v0.1.x fallback suggestions. A lesson whose suggestion is one of these
+ * (and has no dispatched code) carries no actionable information. */
+export declare const GENERIC_SUGGESTIONS: ReadonlySet<string>;
+export declare function isGenericSuggestion(suggestion: string): boolean;
+export interface LessonQuality {
+    /** Rescued errorType: the dispatched code when one matched, else the
+     * coarse errorType (may be `'unknown'`). */
+    errorType: string;
+    /** The lesson's suggestion text (rule-produced or generic fallback). */
+    suggestion: string;
+    /** True when the lesson carries actionable information: a dispatched
+     * code exists OR the suggestion is not one of the generic fallbacks. */
+    isActionable: boolean;
+    /** `strong` when a code matched or the rescued errorType is not
+     * `'unknown'`; `weak` otherwise. */
+    strength: "strong" | "weak";
+}
+export interface QualityLesson {
+    errorType: string;
+    suggestion: string;
+}
+export interface InjectionContext {
+    /** Memory ids already injected in the current session. */
+    seenThisSession: Set<string>;
+    /** Failing tool_calls count for this fingerprint in the current session
+     * (0 = never recurred after injection). */
+    recurrenceCount: number;
+    /** v0.6.0 (K6-022 / plan §5.8) — the `injection_confidence_floor`
+     * setting, read once per plan/inject call by the ContextInjector.
+     * When present, a memory whose `confidence` is below it is rejected by
+     * the zero branch (before the seen-set). Undefined disables the branch:
+     * memories without a computed confidence are never dropped by it. */
+    confidenceFloor?: number;
+}
+/**
+ * v0.5.0 (K5-006 / plan §5.2, D5-04) — the reason a memory was rejected
+ * (or admitted). Every rejection reason maps 1:1 to an
+ * `injections_blocked_*` counter; a silent boolean is an unmeasurable
+ * policy (principle 16).
+ */
+export type GateReason = "ok" | "low_confidence" | "seen_this_session" | "ignored" | "not_active" | "recurrence" | "weak";
+export interface GateVerdict {
+    readonly allowed: boolean;
+    readonly reason: GateReason;
+}
+export declare const QualityGate: {
+    /**
+     * A dispatched code always overrides the coarse errorType for display:
+     * `'unknown'` + `TS2304` → `'TS2304'`.
+     */
+    rescueErrorType(dispatch: DispatchedLesson | null, errorType: string): string;
+    /** Classify a lesson per §5.1 rule 1 (rescue) and the generic ban. */
+    evaluate(lesson: QualityLesson, dispatch: DispatchedLesson | null, errorType: string): LessonQuality;
+    /**
+     * v0.4.0 (K4-004 / plan §5.1 rules 2-4) — admission gate evaluated at
+     * injection time. A lesson is injectable only when:
+     *
+     * 1. its memory id was not already injected this session (seen-set),
+     * 2. its memory is not `stale`,
+     * 3. its fingerprint has not recurred since injection (`recurrenceCount
+     *    === 0` — a lesson that failed to prevent the error leaves the
+     *    prompt),
+     * 4. it is actionable AND strong — weak lessons with generic suggestions
+     *    are never injected (unless `qualityGateEnabled = false` for debug,
+     *    K4-023).
+     *
+     * v0.5.0 (K5-006 / plan §5.2, D5-04) — the boolean form is a thin
+     * wrapper over `canInjectVerdict`; the reason is never discarded by
+     * callers that use the verdict form.
+     */
+    canInject(memory: {
+        id: string;
+        status?: string;
+        strength?: "strong" | "weak";
+        isActionable?: boolean;
+    }, ctx: InjectionContext, qualityGateEnabled?: boolean): boolean;
+    /**
+     * v0.5.0 (K5-006 / plan §5.2, D5-04) — the verdict form of `canInject`.
+     * Branch order preserves the v0.4.0 sequence with `ignored` inserted
+     * second:
+     *
+     * 0. `confidence < ctx.confidenceFloor` → `low_confidence` (v0.6.0,
+     *    K6-022 — runs FIRST: it is the cheapest check, and a memory below
+     *    the floor should not consume a seen-set slot it will never use)
+     * 1. seen this session            → `seen_this_session`
+     * 2. `memory.ignored === true`    → `ignored`
+     * 3. status !== 'active'          → `not_active`
+     * 4. recurrence in session        → `recurrence`
+     * 5. weak / not actionable        → `weak` (skipped entirely when
+     *    `qualityGateEnabled === false` — the debug flag bypasses the
+     *    quality check only, never the seen/ignored/status/recurrence bans)
+     *
+     * `ignored` is a human verdict (D5-07) and is enforced even in debug
+     * mode: the flag excludes a memory from retrieval entirely, so the gate
+     * is only ever asked about it defensively.
+     *
+     * The floor comparison is `>=`-admissive: a memory exactly AT the floor
+     * passes the branch (asserted in K6-022). A floor of '0' admits
+     * everything the other five branches allow.
+     */
+    canInjectVerdict(memory: {
+        id: string;
+        status?: string;
+        strength?: "strong" | "weak";
+        isActionable?: boolean;
+        ignored?: boolean;
+        confidence?: number;
+    }, ctx: InjectionContext, qualityGateEnabled?: boolean): GateVerdict;
+};