@jmtrin/opencode-kevin 0.4.0 → 0.5.0

package/README.md

@@ -8,6 +8,7 @@ Kevin is an [OpenCode](https://opencode.ai) plugin that **observes** every agent
 - **Global memory**: a single `~/.opencode-kevin/kevin.db` shared across all your projects (WAL mode → safe for concurrent sessions). No per-project folders.
 - **Knowledge + Causality (v0.3.0)**: causal failure→fix chains, `kevin_why` explanations, OKF export/import, a supersede model, and human-in-the-loop AGENTS.md suggestions.
 - **Signal over Noise (v0.4.0)**: a quality gate that stores weak lessons without injecting them, an injection ledger with honest `precision_rate`, two-sided confidence, and a fixed compacting hook.
+- **Glass Box (v0.5.0)**: honest measurement replaces estimates — three-way injection settlement (`effective` / `ineffective` / `inconclusive`), human feedback that actually moves confidence, a strict dry-run `kevin_trace`, a read-only `kevin_audit`, memory lifecycle completion (`superseded_by`, `ignored`, `archived`), and a hermetic replay harness. See [How Kevin measures itself](#how-kevin-measures-itself).
 - **Audited**: the v0.4.0 bug catalog (`docs/Kevin_v0.4.0_Bugs.md`) is fully closed — 16/16 bugs fixed and regression-tested (evidence in `kevin_query`/`kevin_get`, OKF round-trip fidelity, causal refresh guard, redaction precision, cross-session isolation).
 - **Standalone**: works without any other plugin. With the ecosystem, it learns more richly.
 
@@ -33,7 +34,7 @@ For a **single project**, put the same `plugin` array in `./opencode.json` or `.
 
 ### 2. Restart OpenCode
 
-Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes ten tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`, `kevin_config`.
+Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes thirteen tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`, `kevin_config`, `kevin_feedback`, `kevin_trace`, `kevin_audit` (v0.5.0 adds the last three).
 
 ### 3. Where data lives
 
@@ -116,7 +117,7 @@ Use `:memory:` for `dbPath` in tests.
   ┌─────────────────┐               │
   │   SHARE          │◄──────────────┘
   │ ContextInjector  │  injects relevant lessons pre-prompt
-  │                  │  (1500 tokens) + on compacting (2000)
+  │                  │  (900 tokens, configurable via pre_prompt_budget_tokens) + on compacting (2000)
   │                  │  + <protect> + id: line (v0.2.0)
   │                  │  + origin-aware rank (v0.2.0)
   │                  │  + <kevin-suggestion> after negative
@@ -137,7 +138,7 @@ Use `:memory:` for `dbPath` in tests.
 
 ## Tools
 
-Kevin exposes 10 tools callable by the agent:
+Kevin exposes 13 tools callable by the agent:
 
 ### `kevin_save`
 
@@ -188,7 +189,7 @@ kevin_recall({ query: "auth", limit: 3 })
 
 ### `kevin_status`
 
-Global counts and metrics. v0.2.0 adds `memories_reflector`, `memories_agent`, `memories_pattern` and a `metrics` object; v0.3.0 adds `memories_causal` and 3 more seeded counters (`patterns_causal`, `causal_links`, `memories_superseded`); v0.4.0 adds the precision block: `injections_total`, `injections_effective`, `injections_ineffective`, `precision_rate`, `patterns_promoted_new`, and per-origin `recurrence_by_origin`.
+Global counts and metrics. v0.2.0 adds `memories_reflector`, `memories_agent`, `memories_pattern` and a `metrics` object; v0.3.0 adds `memories_causal` and 3 more seeded counters (`patterns_causal`, `causal_links`, `memories_superseded`); v0.4.0 adds the precision block: `injections_total`, `injections_effective`, `injections_ineffective`, `precision_rate`, `patterns_promoted_new`, and per-origin `recurrence_by_origin`. v0.5.0 adds `injections_inconclusive`, `coverage_rate`, `blocked`, `memories_ignored`, `memories_archived` and `feedback { positive, negative }`.
 
 ```
 kevin_status({})
@@ -197,10 +198,14 @@ kevin_status({})
 //      "metrics": { "tokens_injected_pre_prompt": 51, "tokens_injected_compacting": 0,
 //                   "reflections_throttled": 3, "duplicate_suppressions": 2,
 //                   "tool_calls_deduped": 0, "patterns_mined": 0,
-//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0 },
-//      "injections_total": 14, "injections_effective": 11, "injections_ineffective": 3,
-//      "precision_rate": 0.79, "patterns_promoted_new": 2,
-//      "recurrence_by_origin": { "reflector": 3, "causal": 1 } }
+//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0,
+//                   "injections_inconclusive": 9, "injections_blocked_seen": 1, ... },
+//      "injections_total": 14, "injections_effective": 2, "injections_ineffective": 3,
+//      "injections_inconclusive": 9, "precision_rate": 0.40, "coverage_rate": 0.36,
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0, "ignored": 1 },
+//      "memories_ignored": 1, "memories_archived": 4,
+//      "feedback": { "positive": 2, "negative": 1 },
+//      "patterns_promoted_new": 2, "recurrence_by_origin": { "reflector": 3, "causal": 1 } }
 ```
 
 ### `kevin_retrospective`
@@ -245,7 +250,44 @@ kevin_config({ action: "set", key: "quality_gate_enabled", value: "0" })
 // → { "ok": true }
 ```
 
-Known keys: `quality_gate_enabled`, `lesson_snippet_injection`, `llm_reflection_enabled`, `cross_project_enabled`, `patternminer_enabled`, `tool_calls_dedup_enabled` (v0.4.0).
+Known keys: `quality_gate_enabled`, `lesson_snippet_injection`, `llm_reflection_enabled`, `cross_project_enabled`, `patternminer_enabled`, `tool_calls_dedup_enabled` (v0.4.0), `deterministic_retrieval`, `pre_prompt_budget_tokens`, `archive_after_days` (v0.5.0).
+
+### `kevin_feedback` (v0.5.0)
+
+Rates an injected memory and makes the rating count. `verdict` is `useful` | `wrong` | `outdated` | `ignore`. The first three are stored in `memory_feedback` and move `kevin_why`'s confidence (`+0.05` / `-0.1` per count); **`ignore` is a hard action** — the memory is stamped `ignored = 1` and excluded from retrieval, queries and injection.
+
+```
+kevin_feedback({ memory_id: "0195a3b2-...", verdict: "wrong", note: "the fix was wrong" })
+// → { "ok": true, "verdict": "wrong" }
+```
+
+### `kevin_trace` (v0.5.0)
+
+Strict dry-run: predicts exactly which memories `onSystemTransform` WOULD inject for a query (optionally `session_id`, `tag` and `cap`), with **zero side effects** — no counters, no ledger rows, no seen-set writes, no relevance bumps. Rejected items carry their `GateReason` (`seen_this_session` | `weak` | `recurrence` | `stale` | `ignored`).
+
+```
+kevin_trace({ query: "tsc error" })
+// → { "query": "tsc error", "tag": "context", "cap": 900, "would_inject": true,
+//      "total_tokens": 82,
+//      "admitted": [ { "id": "...", "type": "error", "decision": "admitted", "tokens": 62 } ],
+//      "blocked": [ { "id": "...", "type": "error", "decision": "blocked", "reason": "seen_this_session", "tokens": 20 } ] }
+```
+
+### `kevin_audit` (v0.5.0)
+
+Read-only report of the whole system state: memories by `status`/`origin`/`type`, injection outcomes with `precision_rate`/`coverage_rate`, the five `blocked` counters, feedback by verdict, tokens injected. `verbose: true` adds the settings block. No writes, no LLM; on a pre-006 database it returns what it can with `"partial": true`.
+
+```
+kevin_audit({})
+// → { "memories": { "total": 42, "by_status": { "active": 37, "stale": 1, "archived": 4 },
+//                   "by_origin": { "reflector": 12, "agent": 30 }, "by_type": { "error": 20, ... },
+//                   "ignored": 1, "archived": 4, "with_feedback": 3, "superseded_with_target": 2 },
+//      "injections": { "total": 14, "effective": 2, "ineffective": 3, "inconclusive": 9,
+//                      "unmeasured": 0, "precision_rate": 0.40, "coverage_rate": 0.36 },
+//      "blocked": { "seen": 1, "weak": 0, "recurrence": 2, "stale": 0, "ignored": 1 },
+//      "feedback": { "positive": 2, "negative": 1, "by_verdict": { "useful": 2, "wrong": 1 } },
+//      "tokens": { "pre_prompt": 51, "compacting": 0 }, "partial": false }
+```
 
 ---
 
@@ -253,6 +295,27 @@ Known keys: `quality_gate_enabled`, `lesson_snippet_injection`, `llm_reflection_
 
 Weak lessons — errors the reflector cannot dispatch to a deterministic rule — are **stored but never injected** while `quality_gate_enabled = '1'` (default). Injection now goes through a ledger: every pre-prompt/compacting injection is recorded and settled as effective or ineffective at session idle, so `kevin_status` reports the honest picture (`injections_total`, `injections_effective/ineffective`, `precision_rate`, `patterns_promoted_new`) instead of raw "lessons shared" counts. Recurrences demote lessons (`recurrence_count` → `stale`) and lower confidence. Debug mode: `kevin_config({ action: "set", key: "quality_gate_enabled", value: "0" })` re-injects weak lessons with a `(low confidence)` marker.
 
+## How Kevin measures itself (v0.5.0)
+
+Every injection is settled at `session.idle` into one of **four outcomes**:
+
+| Outcome | Meaning | Counts toward precision? |
+|---|---|---|
+| `effective` | A linked fix was observed after the injection | yes (numerator) |
+| `ineffective` | The same error recurred after the injection | yes (denominator) |
+| `inconclusive` | Neither — the error did not recur, but no fix was seen either | no |
+| `unmeasured` | Session went idle before settlement could run | no |
+
+- **`precision_rate`** = `effective / (effective + ineffective)`. The v0.4.0 definition counted "did not recur" as success — measuring absence of recurrence, not effect. **Your precision rate will look lower on v0.5.0. That is the honest number.** Existing `effective` rows were remapped to `inconclusive` by migration 006.
+- **`coverage_rate`** = `(effective + ineffective) / total` — the share of injections that were actually measured. Reported alongside precision so a low measurable fraction stays visible instead of hiding behind a large total.
+- **`blocked`** counts every gate rejection by reason (`seen_this_session`, `weak`, `recurrence`, `stale`, `ignored`) — a rejection you did not count did not happen.
+
+`kevin_trace` shows you the plan *before* it happens (dry run, zero side effects); `kevin_audit` reads the whole picture after; `kevin_feedback` lets a human correct it — and the correction moves the confidence number `kevin_why` reports.
+
+## Replay harness (v0.5.0)
+
+`npm run replay` runs every transcript in `tests/replay/fixtures/` through the plugin against an in-memory database with a frozen clock and prints one table row per transcript (memories created, injection outcomes, `precision_rate`, `coverage_rate`, tokens). Record your own session as a JSON array of typed events (`session.created`, `chat.message`, `tool.before`, `tool.after`, `system.transform`, `compacting`, `session.idle`) with ISO-8601 `at` timestamps, drop it into `tests/replay/fixtures/`, and re-run. The `at` timestamps are the only source of time during replay.
+
 ---
 
 ## Hooks
@@ -263,7 +326,7 @@ Kevin subscribes to 6 OpenCode hooks:
 |---|---|
 | `tool.execute.before` | Records tool call start (callID + redacted args) |
 | `tool.execute.after` | Records result (id = callID); on failure → Reflector.invoke async (throttled); on success → CausalChain.onSuccess links the fix (v0.3.0) |
-| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (1500 tokens) + optional `<kevin-suggestion>` (v0.3.0) |
+| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (900 tokens by default, configurable) + optional `<kevin-suggestion>` (v0.3.0) |
 | `experimental.session.compacting` | Re-injects lessons in `<kevin-memory>` after compacting (2000 tokens) + optional `<kevin-suggestion>` |
 | `event` (`session.created`) | Captures current `sessionID` |
 | `event` (`session.idle`) | Generates retrospective.md; boosts positive lessons (v0.2.0); penalizes recurring failures (v0.3.0); promotes causal patterns + mines patterns (opt-in); flushes metrics |
@@ -292,6 +355,18 @@ KevinPlugin(input, {
 });
 ```
 
+### Settings (v0.5.0)
+
+Read/write via `kevin_config({ action: "list" | "set", ... })`. v0.5.0 adds:
+
+| Setting | Default | Effect |
+|---|---|---|
+| `deterministic_retrieval` | `"0"` | Freezes Kevin's internal clock (recency factor 1.0, no relevance bumps) — for hermetic tests and the replay harness |
+| `pre_prompt_budget_tokens` | `"900"` | Pre-prompt injection cap, clamped to `[100, 4000]` (was a hard-coded 1500) |
+| `archive_after_days` | `"30"` | Age at which stale non-pattern memories are retired to `archived` on `session.idle` |
+
+All settings are stored as TEXT in `kevin_settings`; values are compared against `"1"` for booleans.
+
 ---
 
 ## Development
@@ -302,8 +377,9 @@ cd opencode-kevin
 npm install
 npm run typecheck   # tsc --noEmit (strict)
 npm run lint        # biome check .
-npm test            # vitest run (unit + integration + e2e)
+npm test            # vitest run (unit + integration + e2e + replay)
 npm run verify      # post-install verification
+npm run replay      # replay report over tests/replay/fixtures (v0.5.0)
 ```
 
 ### Publishing (maintainer)

package/dist/migrations/006_v05_glassbox.sql

@@ -0,0 +1,118 @@
+-- ============================================================================
+-- 006_v05_glassbox.sql — v0.5.0 "Glass Box"
+--
+-- Honest measurement, human feedback, lifecycle completion.
+--
+-- Section 1: rebuild kevin_injections to admit a fourth outcome.
+-- Section 2: human feedback storage.
+-- Section 3: memory lifecycle columns.
+-- Section 4: metric seeds.
+-- Section 5: setting seeds.
+-- Section 6: schema_version.
+-- ============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. kevin_injections: add 'inconclusive'.
+--
+-- SQLite cannot ALTER a CHECK constraint, so the table must be rebuilt.
+-- Migration 004 set this precedent. kevin_injections has no FTS5 triggers,
+-- so unlike 004 this is a straight four-step rebuild.
+--
+-- Existing rows with outcome='effective' are remapped to 'inconclusive'.
+-- This is not data loss: v0.4's 'effective' meant "the error did not recur",
+-- which is the exact definition of the new 'inconclusive' bucket. Rows that
+-- genuinely earned the new 'effective' will be re-settled naturally, and the
+-- post-apply hook re-derives the counters from the table.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS kevin_injections_new (
+  id          TEXT PRIMARY KEY,
+  memory_id   TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  session_id  TEXT NOT NULL,
+  hook        TEXT NOT NULL CHECK (hook IN ('pre_prompt','compacting')),
+  tokens      INTEGER NOT NULL,
+  injected_at TEXT NOT NULL DEFAULT (datetime('now')),
+  outcome     TEXT NOT NULL DEFAULT 'unmeasured'
+              CHECK (outcome IN ('unmeasured','effective','ineffective','inconclusive'))
+);
+
+INSERT INTO kevin_injections_new
+  (id, memory_id, fingerprint, session_id, hook, tokens, injected_at, outcome)
+SELECT
+  id, memory_id, fingerprint, session_id, hook, tokens, injected_at,
+  CASE WHEN outcome = 'effective' THEN 'inconclusive' ELSE outcome END
+FROM kevin_injections;
+
+DROP TABLE kevin_injections;
+ALTER TABLE kevin_injections_new RENAME TO kevin_injections;
+
+CREATE INDEX IF NOT EXISTS idx_injections_fp      ON kevin_injections(fingerprint);
+CREATE INDEX IF NOT EXISTS idx_injections_session ON kevin_injections(session_id);
+CREATE INDEX IF NOT EXISTS idx_injections_outcome ON kevin_injections(outcome);
+
+-- ---------------------------------------------------------------------------
+-- 2. Human feedback. Append-only audit trail; the hot path reads the
+--    denormalized counters on `memories` (section 3), never this table.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS memory_feedback (
+  id         TEXT PRIMARY KEY,
+  memory_id  TEXT NOT NULL,
+  verdict    TEXT NOT NULL CHECK (verdict IN ('useful','wrong','outdated','ignore')),
+  session_id TEXT,
+  note       TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_memory  ON memory_feedback(memory_id);
+CREATE INDEX IF NOT EXISTS idx_feedback_created ON memory_feedback(created_at);
+
+-- ---------------------------------------------------------------------------
+-- 3. Memory lifecycle and feedback columns.
+--
+--    feedback_positive / feedback_negative are SEPARATE from evidence_count
+--    and recurrence_count by design: human judgement is evidence about the
+--    memory, causal counters are evidence about the world. Mixing them was
+--    the confidence-poisoning defect closed in v0.4.0.
+--
+--    superseded_by has no REFERENCES clause on purpose. Store enables
+--    PRAGMA foreign_keys=ON, and a hard FK would block deletion of a memory
+--    that superseded another.
+-- ---------------------------------------------------------------------------
+ALTER TABLE memories ADD COLUMN feedback_positive INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN feedback_negative INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN ignored           INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN superseded_by     TEXT;
+ALTER TABLE memories ADD COLUMN archived_at       TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_memories_ignored  ON memories(ignored);
+CREATE INDEX IF NOT EXISTS idx_memories_archived ON memories(archived_at);
+
+-- ---------------------------------------------------------------------------
+-- 4. Metric seeds. Order matches the additions to METRIC_KEYS in metrics.ts.
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('injections_inconclusive',      0),
+  ('injections_blocked_seen',      0),
+  ('injections_blocked_weak',      0),
+  ('injections_blocked_recurrence',0),
+  ('injections_blocked_stale',     0),
+  ('injections_blocked_ignored',   0),
+  ('feedback_positive_total',      0),
+  ('feedback_negative_total',      0),
+  ('memories_archived',            0);
+
+-- ---------------------------------------------------------------------------
+-- 5. Setting seeds. Values are TEXT, always. Read them with an explicit
+--    string comparison or an explicit Number() parse — never `=== 1`.
+--    (That exact mistake kept cross_project_enabled unreachable for the
+--    whole of v0.3.0.)
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('deterministic_retrieval',    '0'),
+  ('pre_prompt_budget_tokens', '900'),
+  ('archive_after_days',        '30');
+
+-- ---------------------------------------------------------------------------
+-- 6. Version marker.
+-- ---------------------------------------------------------------------------
+INSERT OR IGNORE INTO schema_version (version) VALUES ('006');

package/dist/plugin/Archiver.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * v0.5.0 Archiver (K5-012 / plan §5.4, D5-05).
+ *
+ * Lifecycle tail of the memory loop: reflectors mark a lesson `stale` when
+ * its fingerprint recurred enough times (penalizeRecurringReflectors,
+ * migration 003), but nothing ever retires those rows — they keep
+ * circulating through status filters and inflating counts. The Archiver
+ * runs on `session.idle` and retires stale memories whose last activity
+ * (`updated_at`, falling back to `last_verified_at`) is older than
+ * `archive_after_days` (kevin_settings, seeded '30' in migration 006).
+ *
+ * Rules:
+ *  - Only `status = 'stale'` rows with `archived_at IS NULL`.
+ *  - `type != 'pattern'`: a pattern is the FIXED form of a fingerprint
+ *    (K4-025); archiving it would break kevin_why and the recurrence
+ *    re-admission path (QualityGate rule 4).
+ *  - Clock: the injection clock (K5-008) — tests freeze it; production
+ *    defaults to `new Date()`. Never `Date.now()` inside.
+ *  - `memories_archived` is bumped by the batch size, once per run.
+ *  - Pre-006 DBs (no `archived_at`) degrade to a no-op.
+ *
+ * Archived rows remain queryable with `includeSuperseded: true`-style
+ * reads (status filter is exclusive, not destructive).
+ */
+export declare class Archiver {
+    private readonly store;
+    private readonly memoryService;
+    private readonly metrics;
+    private readonly now;
+    constructor(store: Store, memoryService: MemoryService, metrics?: Metrics | null, now?: () => Date);
+    /**
+     * Archives every eligible stale memory. Returns the number of rows
+     * retired. Idempotent: archived rows are excluded by `archived_at IS
+     * NULL`, so a second run archives nothing.
+     */
+    run(): number;
+    private archiveAfterDays;
+    private hasArchivedColumn;
+}

package/dist/plugin/Archiver.js

@@ -0,0 +1,98 @@
+/**
+ * v0.5.0 Archiver (K5-012 / plan §5.4, D5-05).
+ *
+ * Lifecycle tail of the memory loop: reflectors mark a lesson `stale` when
+ * its fingerprint recurred enough times (penalizeRecurringReflectors,
+ * migration 003), but nothing ever retires those rows — they keep
+ * circulating through status filters and inflating counts. The Archiver
+ * runs on `session.idle` and retires stale memories whose last activity
+ * (`updated_at`, falling back to `last_verified_at`) is older than
+ * `archive_after_days` (kevin_settings, seeded '30' in migration 006).
+ *
+ * Rules:
+ *  - Only `status = 'stale'` rows with `archived_at IS NULL`.
+ *  - `type != 'pattern'`: a pattern is the FIXED form of a fingerprint
+ *    (K4-025); archiving it would break kevin_why and the recurrence
+ *    re-admission path (QualityGate rule 4).
+ *  - Clock: the injection clock (K5-008) — tests freeze it; production
+ *    defaults to `new Date()`. Never `Date.now()` inside.
+ *  - `memories_archived` is bumped by the batch size, once per run.
+ *  - Pre-006 DBs (no `archived_at`) degrade to a no-op.
+ *
+ * Archived rows remain queryable with `includeSuperseded: true`-style
+ * reads (status filter is exclusive, not destructive).
+ */
+export class Archiver {
+    store;
+    memoryService;
+    metrics;
+    now;
+    constructor(store, memoryService, metrics, now = () => new Date()) {
+        this.store = store;
+        this.memoryService = memoryService;
+        this.metrics = metrics ?? null;
+        this.now = now;
+    }
+    /**
+     * Archives every eligible stale memory. Returns the number of rows
+     * retired. Idempotent: archived rows are excluded by `archived_at IS
+     * NULL`, so a second run archives nothing.
+     */
+    run() {
+        if (!this.hasArchivedColumn())
+            return 0;
+        const days = this.archiveAfterDays();
+        if (days <= 0)
+            return 0;
+        const now = this.now();
+        const cutoff = formatSqliteUtc(new Date(now.getTime() - days * 86_400_000));
+        this.store
+            .prepare(`UPDATE memories
+				    SET status = 'archived', archived_at = ?, updated_at = ?
+				  WHERE status = 'stale'
+				    AND type != 'pattern'
+				    AND archived_at IS NULL
+				    AND updated_at < ?`)
+            .run(formatSqliteUtc(now), formatSqliteUtc(now), cutoff);
+        const changed = this.store.prepare("SELECT changes() AS n").get();
+        const n = changed.n;
+        if (n > 0)
+            this.metrics?.incr("memories_archived", n);
+        return n;
+    }
+    archiveAfterDays() {
+        try {
+            const raw = this.memoryService.getSetting("archive_after_days", "30");
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : 30;
+        }
+        catch {
+            return 30;
+        }
+    }
+    hasArchivedColumn() {
+        return hasArchivedColumnCached(this.store);
+    }
+}
+const archivedColumnCache = new WeakMap();
+function hasArchivedColumnCached(store) {
+    const cached = archivedColumnCache.get(store);
+    if (cached !== undefined)
+        return cached;
+    try {
+        store.prepare("SELECT archived_at FROM memories LIMIT 1").get();
+        archivedColumnCache.set(store, true);
+        return true;
+    }
+    catch {
+        archivedColumnCache.set(store, false);
+        return false;
+    }
+}
+/** 'YYYY-MM-DD HH:MM:SS' UTC — the format SQLite `datetime('now')` uses,
+ * so lexicographic comparisons against `updated_at` are valid. */
+function formatSqliteUtc(d) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+//# sourceMappingURL=Archiver.js.map

package/dist/plugin/Archiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Archiver.js","sourceRoot":"","sources":["../../plugin/Archiver.ts"],"names":[],"mappings":"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"}

package/dist/plugin/ContextInjector.d.ts

@@ -1,5 +1,6 @@
 import type { InjectionLedger } from "./InjectionLedger.js";
 import type { MemoryService } from "./MemoryService.js";
+import { type GateReason } from "./QualityGate.js";
 import { type Metrics } from "./metrics.js";
 export declare const QUALITY_GATE_SETTING = "quality_gate_enabled";
 export declare const SNIPPET_INJECTION_SETTING = "lesson_snippet_injection";
@@ -21,6 +22,26 @@ export interface CompactingInput {
 export interface CompactingOutput {
     context: string[];
 }
+export interface InjectionPlanItem {
+    id: string;
+    type: string;
+    decision: "admitted" | "blocked";
+    /** Gate reason when blocked; null for admitted items. */
+    reason?: GateReason;
+    /** Estimated tokens this memory would contribute to the block. */
+    tokens: number;
+}
+export interface InjectionPlan {
+    query: string;
+    tag: "context" | "memory";
+    cap: number;
+    would_inject: boolean;
+    /** Estimated tokens of the block that WOULD be produced (0 when
+     * nothing would be injected). */
+    total_tokens: number;
+    admitted: InjectionPlanItem[];
+    blocked: InjectionPlanItem[];
+}
 export declare class ContextInjector {
     private memoryService;
     private metrics;
@@ -76,13 +97,64 @@ export declare class ContextInjector {
      * `QualityGate.canInject` (session seen-set + recurrence + strength),
      * and each admitted memory is recorded in the `InjectionLedger`
      * (plan §5.2 — one row per injected memory).
+     *
+     * v0.5.0 (K5-014 / plan §8.10) — the pipeline is decomposed into
+     * `fetchSlice` (ranked retrieval + budget overflow) + `evaluate`
+     * (pure gate verdicts) + this orchestrator, so the read-only `plan()`
+     * can mirror it without any side effect (D5-08).
      */
     private inject;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — the ranked-retrieval stage shared by
+     * `inject` and `plan`. With `dry = true` it is a strict read:
+     *
+     *  - the probe fetch never bumps (BUG-016), like the live path;
+     *  - the overflow retry ALSO fetches with `bump: false` (the live path
+     *    lets the retry fetch bump once — that is the only difference);
+     *  - the no-retry bump is skipped.
+     *
+     * This is what lets `plan()` predict the EXACT slice the live path
+     * would inject without mutating a single relevance score.
+     */
+    private fetchSlice;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10, D5-08) — PUBLIC read-only prediction of
+     * what `inject` WOULD do for a query: same retrieval, same gate, zero
+     * side effects. Never moves a counter, never writes the seen-set, never
+     * bumps relevance, never records ledger rows. `kevin_trace` (K5-015)
+     * surfaces this to the agent; tests freeze the clock + settings around
+     * it.
+     */
+    plan(query: string, options?: {
+        tag?: "context" | "memory";
+        cap?: number;
+        sessionId?: string;
+    }): InjectionPlan;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — PURE gate evaluation shared by `admit`
+     * (live path) and `plan` (read-only path): returns the verdict for every
+     * candidate plus the seen-set as it WOULD look afterwards. Never writes
+     * state — the caller decides whether to persist.
+     */
+    private evaluate;
+    /**
+     * v0.5.0 (K5-017 / plan §8.11, D5-11) — the effective pre-prompt cap,
+     * read at call time from `pre_prompt_budget_tokens` (seeded "900" by
+     * migration 006). Clamped to [100, 4000]; a non-numeric value falls
+     * back to 900. `kevin_trace` reports the value used via `plan().cap`.
+     */
+    private prePromptCap;
     /**
      * v0.4.0 (K4-017) — QualityGate admission: filters the ranked slice to
      * memories that may be injected this session, updating the session
      * seen-set.
      *
+     * v0.5.0 (K5-007 / plan §5.2, D5-04) — uses `canInjectVerdict` and
+     * increments the matching `injections_blocked_*` counter for every
+     * rejection, so gate policy becomes measurable. When `dryRun === true`
+     * the counters stay untouched (D5-08) — and so does the seen-set
+     * (a dry run is a strict read, K5-014).
+     *
      * BUG-005 — strength/actionability now go through the REAL
      * `QualityGate.evaluate` semantics (plan §5.1 rules 1-2), which this
      * class had only re-derived from `metadata.dispatch`: