@jmtrin/opencode-kevin 0.2.0 → 0.4.0

package/dist/plugin/InjectionLedger.js

@@ -0,0 +1,189 @@
+import { uuidv7 } from "./uuid.js";
+export class InjectionLedger {
+    store;
+    metrics;
+    constructor(store, metrics) {
+        this.store = store;
+        this.metrics = metrics ?? null;
+    }
+    /**
+     * Records one injected memory. Idempotent at the row level (UUID PK);
+     * duplicates are expected only via the caller's per-session seen-set.
+     */
+    record(input) {
+        this.store
+            .prepare(`INSERT INTO kevin_injections
+				   (id, memory_id, fingerprint, session_id, hook, tokens, outcome)
+				 VALUES (?, ?, ?, ?, ?, ?, 'unmeasured')`)
+            .run(uuidv7(), input.memoryId, input.fingerprint, input.sessionId, input.hook, input.tokens);
+        this.metrics?.incr("injections_total", 1);
+    }
+    /**
+     * Settles every unmeasured injection of the session: a fingerprint that
+     * failed again (as a failing tool_call) after the injection is
+     * `ineffective`, otherwise `effective`. Idempotent — only
+     * `outcome = 'unmeasured'` rows are flipped, and the recurrence charge
+     * is `MAX(recurrence_count, n)` where n = all failing calls of the
+     * fingerprint after `injected_at` (a later idle re-computes n and
+     * catches up — plan §5.1 rule 4: 3 recurrences → stale).
+     *
+     * An ineffective injection also bumps the target memory's
+     * `recurrence_count` (negative evidence, plan §5.3) and stamps
+     * `last_injected_at`.
+     */
+    settle(sessionId) {
+        const injections = this.store
+            .prepare(`SELECT id, memory_id, fingerprint, injected_at, outcome
+				   FROM kevin_injections
+				  WHERE session_id = ?`)
+            .all(sessionId);
+        for (const inj of injections) {
+            // Same identity dimension CausalChain uses: the failing call's
+            // `error_fingerprint` (stamped by Reflector) or the legacy
+            // `fingerprint` hash. `ts` and `injected_at` are both
+            // `datetime('now')` text → lexicographic comparison is valid.
+            // COUNT (not LIMIT 1): every failing call after the injection
+            // is a recurrence — the charge must reach 3 so D4-06 expels
+            // the lesson.
+            //
+            // BUG-003 — the exemption is now bounded to the lesson's OWN
+            // creating call (memories.metadata.origin_call_id, stamped by
+            // Reflector). The old code excluded the session's FIRST failing
+            // call of the fingerprint, which is only the creating call when
+            // the lesson was born in THIS session; a lesson created in an
+            // earlier session had its first in-session failure (a genuine
+            // post-injection recurrence) wrongly exempted, inflating
+            // precision. Memories without a tracked creating call (agent-
+            // saved, test fixtures) get no exemption: only the `ts >=
+            // injected_at` bound applies.
+            const originCallId = readOriginCallId(this.store, inj.memory_id);
+            const countRow = this.store
+                .prepare(`SELECT COUNT(*) AS n FROM tool_calls
+					  WHERE session_id = ?
+					    AND success = 0
+					    AND COALESCE(error_fingerprint, fingerprint) = ?
+					    AND ts >= ?
+					    AND (? IS NULL OR id != ?)
+					 LIMIT 1`)
+                .get(sessionId, inj.fingerprint, inj.injected_at, originCallId, originCallId);
+            const n = countRow.n;
+            if (n >= 1) {
+                if (inj.outcome === "unmeasured") {
+                    this.store
+                        .prepare(`UPDATE kevin_injections SET outcome = 'ineffective'
+							  WHERE id = ?`)
+                        .run(inj.id);
+                    this.metrics?.incr("injections_ineffective", 1);
+                }
+                this.store
+                    .prepare(`UPDATE memories
+						    SET recurrence_count = MAX(recurrence_count, ?),
+						        last_injected_at = ?
+						  WHERE fingerprint = ? AND id = ?`)
+                    .run(countRow.n, inj.injected_at, inj.fingerprint, inj.memory_id);
+                // v0.4.0 (K4-025 / plan §5.1 rule 4, D4-06) — recurrence
+                // expels: a fingerprint at `recurrence_count >= 3` is
+                // demoted to `status='stale'` and never injected again
+                // (only a new causal pattern — from a linked fix —
+                // re-admits the lesson, not the stale error row).
+                this.store
+                    .prepare(`UPDATE memories SET status = 'stale'
+						  WHERE id = ? AND recurrence_count >= 3`)
+                    .run(inj.memory_id);
+            }
+            else if (inj.outcome === "unmeasured") {
+                this.store
+                    .prepare(`UPDATE kevin_injections SET outcome = 'effective'
+						  WHERE id = ?`)
+                    .run(inj.id);
+                this.metrics?.incr("injections_effective", 1);
+            }
+        }
+    }
+    /**
+     * Per-fingerprint failing tool-call counts for the session. Feeds
+     * QualityGate.canInject and the HITL suggestion block.
+     */
+    recurrencesFor(sessionId) {
+        const rows = this.store
+            .prepare(`SELECT COALESCE(error_fingerprint, fingerprint) AS fp
+				   FROM tool_calls
+				  WHERE session_id = ? AND success = 0
+				    AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)`)
+            .all(sessionId);
+        const out = new Map();
+        for (const r of rows) {
+            if (!r.fp)
+                continue;
+            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
+        }
+        return out;
+    }
+    /**
+     * v0.4.0 (K4-017) — recurrence counts for the QualityGate at
+     * injection time: only failing calls that happened AFTER the
+     * fingerprint was already injected this session count. The failure
+     * that *created* a lesson is not a recurrence — it precedes any
+     * injection (plan §5.1 rule 4, same `ts >= injected_at` semantics
+     * `settle` uses).
+     */
+    postInjectionRecurrencesFor(sessionId) {
+        const rows = this.store
+            .prepare(`SELECT COALESCE(t.error_fingerprint, t.fingerprint) AS fp
+				   FROM tool_calls t
+				  WHERE t.session_id = ? AND t.success = 0
+				    AND (t.error_fingerprint IS NOT NULL OR t.fingerprint IS NOT NULL)
+				    AND t.ts >= COALESCE(
+				          (SELECT MAX(injected_at) FROM kevin_injections
+				            WHERE session_id = t.session_id
+				              AND fingerprint = COALESCE(t.error_fingerprint, t.fingerprint)),
+				          '9999-12-31')`)
+            .all(sessionId);
+        const out = new Map();
+        for (const r of rows) {
+            if (!r.fp)
+                continue;
+            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
+        }
+        return out;
+    }
+    /** Number of rows for the session not yet settled (drives tests and settle). */
+    unsettledForSession(sessionId) {
+        const row = this.store
+            .prepare(`SELECT COUNT(*) AS n FROM kevin_injections
+				  WHERE session_id = ? AND outcome = 'unmeasured'`)
+            .get(sessionId);
+        return row.n;
+    }
+    /** Latest ledger rows for a session, newest first (used by tests/tools). */
+    rowsForSession(sessionId) {
+        return this.store
+            .prepare(`SELECT id, memory_id, fingerprint, session_id, hook, tokens,
+				        injected_at, outcome
+				   FROM kevin_injections
+				  WHERE session_id = ?
+				  ORDER BY injected_at ASC, id ASC`)
+            .all(sessionId);
+    }
+}
+/**
+ * BUG-003 — read `origin_call_id` (the failing tool_call that CREATED the
+ * memory) from memories.metadata, mirroring the feedback loop's
+ * `readOriginCallId` in MemoryService. Returns null when absent/malformed.
+ */
+function readOriginCallId(store, memoryId) {
+    const row = store
+        .prepare("SELECT metadata FROM memories WHERE id = ?")
+        .get(memoryId);
+    if (!row?.metadata)
+        return null;
+    try {
+        const parsed = JSON.parse(row.metadata);
+        const id = parsed?.origin_call_id;
+        return typeof id === "string" && id.length > 0 ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=InjectionLedger.js.map

package/dist/plugin/InjectionLedger.js.map

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

package/dist/plugin/LessonFixer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
+ *
+ * Zero-cost "Fixed by:" raw material from local data: when CausalChain
+ * links a success to a failing fingerprint, the linked tool_call's
+ * `args_summary` becomes a deterministic fix string stored in
+ * `memories.fix_args`. The default promotion path is pure local data —
+ * no LLM calls (principle 14).
+ */
+/** Max length of the `args_summary` embedded in a fix_args string. */
+export declare const FIX_ARGS_TRUNCATE = 120;
+export interface LinkedToolCall {
+    tool: string;
+    args_summary: string | null;
+}
+/**
+ * `"bash" with args "npm i -g rg"` style. Returns null when the linked
+ * call carries no args_summary (nothing to say).
+ */
+export declare function extractFixArgs(call: LinkedToolCall): string | null;
+export interface EnrichInput {
+    lesson: string;
+    fixArgs: string | null;
+    originalError: string | null;
+}
+/**
+ * Opt-in LLM phrasing hook (K4-015): receives the lesson, the
+ * deterministic fix_args and the original error; returns a one-line
+ * `Fix:` phrasing, or null to fall back to the deterministic text.
+ * May be async; never runs on the failure hot path.
+ */
+export type EnrichFn = (input: EnrichInput) => Promise<string | null>;
+export interface PatternLike {
+    content: string;
+    fixArgs: string | null;
+}
+/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
+export declare function deterministicFixLine(pattern: PatternLike): string;
+/**
+ * Promotion-time fix phrasing. Default path returns the deterministic
+ * `Fixed by: {fix_args}` line (or "" when there is none). When an
+ * `enrichFn` is supplied and returns a phrase, that phrase wins.
+ */
+export declare function enrichAtPromotion(pattern: PatternLike, enrichFn?: EnrichFn): Promise<string>;

package/dist/plugin/LessonFixer.js

@@ -0,0 +1,46 @@
+/**
+ * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
+ *
+ * Zero-cost "Fixed by:" raw material from local data: when CausalChain
+ * links a success to a failing fingerprint, the linked tool_call's
+ * `args_summary` becomes a deterministic fix string stored in
+ * `memories.fix_args`. The default promotion path is pure local data —
+ * no LLM calls (principle 14).
+ */
+/** Max length of the `args_summary` embedded in a fix_args string. */
+export const FIX_ARGS_TRUNCATE = 120;
+/**
+ * `"bash" with args "npm i -g rg"` style. Returns null when the linked
+ * call carries no args_summary (nothing to say).
+ */
+export function extractFixArgs(call) {
+    const raw = call.args_summary?.trim();
+    if (!raw)
+        return null;
+    const truncated = raw.length > FIX_ARGS_TRUNCATE
+        ? `${raw.slice(0, FIX_ARGS_TRUNCATE)}…`
+        : raw;
+    return `${call.tool} with args "${truncated}"`;
+}
+/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
+export function deterministicFixLine(pattern) {
+    return pattern.fixArgs ? `Fixed by: ${pattern.fixArgs}` : "";
+}
+/**
+ * Promotion-time fix phrasing. Default path returns the deterministic
+ * `Fixed by: {fix_args}` line (or "" when there is none). When an
+ * `enrichFn` is supplied and returns a phrase, that phrase wins.
+ */
+export async function enrichAtPromotion(pattern, enrichFn) {
+    if (enrichFn) {
+        const phrased = await enrichFn({
+            lesson: pattern.content,
+            fixArgs: pattern.fixArgs,
+            originalError: null,
+        });
+        if (phrased)
+            return phrased;
+    }
+    return deterministicFixLine(pattern);
+}
+//# sourceMappingURL=LessonFixer.js.map

package/dist/plugin/LessonFixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LessonFixer.js","sourceRoot":"","sources":["../../plugin/LessonFixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAOrC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAoB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,SAAS,GACd,GAAG,CAAC,MAAM,GAAG,iBAAiB;QAC7B,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG;QACvC,CAAC,CAAC,GAAG,CAAC;IACR,OAAO,GAAG,IAAI,CAAC,IAAI,eAAe,SAAS,GAAG,CAAC;AAChD,CAAC;AAqBD,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,OAAoB;IACxD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,OAAoB,EACpB,QAAmB;IAEnB,IAAI,QAAQ,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC;YAC9B,MAAM,EAAE,OAAO,CAAC,OAAO;YACvB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,aAAa,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAC7B,CAAC;IACD,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/plugin/MemoryService.d.ts

@@ -1,8 +1,8 @@
 import type { Store } from "./Store.js";
 import type { Metrics } from "./metrics.js";
-export type MemoryType = "error" | "pattern" | "decision" | "context";
+export type MemoryType = "error" | "pattern" | "decision" | "context" | "rule" | "solution";
 export type MemoryScope = "project" | "session";
-export type MemoryOrigin = "reflector" | "agent" | "pattern" | "retrospective";
+export type MemoryOrigin = "reflector" | "agent" | "pattern" | "retrospective" | "causal" | "imported";
 export interface Memory {
     id: string;
     type: MemoryType;
@@ -21,10 +21,26 @@ export interface Memory {
     fingerprint?: string | null;
     /** v0.2.0 — origin of the memory. */
     origin?: MemoryOrigin | null;
+    /** v0.3.0 — confidence derived from causal evidence (0..1). Only set by CausalChain. */
+    confidence?: number | null;
+    /** v0.3.0 — number of confirmed causal fix confirmations. */
+    evidenceCount?: number | null;
+    /** v0.3.0 — last time causal evidence was observed. */
+    lastVerifiedAt?: string | null;
+    /** v0.3.0 — lifecycle status. Default 'active'. */
+    status?: string | null;
+    /** v0.4.0 — deterministic capture of the linked fix call (K4-014). */
+    fixArgs?: string | null;
+    /** v0.4.0 (BUG-008/010) — negative evidence: how many times the
+     * fingerprint recurred after injection (demotes confidence). */
+    recurrenceCount?: number | null;
 }
 export interface SaveInput {
     type: MemoryType;
     content: string;
+    /** v0.4.0 (BUG-008) — preserve the original id on okf import;
+     * when absent a fresh uuidv7 is generated. */
+    id?: string;
     scope?: MemoryScope;
     relevanceScore?: number;
     sourceTool?: string;
@@ -37,6 +53,15 @@ export interface SaveInput {
     origin?: MemoryOrigin;
     /** v0.2.0 — explicit fingerprint. Auto-derived for `type='error'` if absent. */
     fingerprint?: string;
+    /** v0.3.0 — number of confirmed causal fix confirmations. */
+    evidenceCount?: number;
+    /** v0.3.0 — last time causal evidence was observed. */
+    lastVerifiedAt?: string;
+    /** v0.3.0 — lifecycle status. Default 'active'. */
+    status?: string;
+    /** v0.4.0 (BUG-008/010) — how many times the fingerprint recurred
+     * after injection (negative evidence, demotes confidence). */
+    recurrenceCount?: number;
 }
 export interface QueryInput {
     text: string;
@@ -48,6 +73,13 @@ export interface QueryInput {
      * behavior, per plan §B6.3 / K2-010).
      */
     full?: boolean;
+    /** v0.3.0 — when true, includes rows where status = 'superseded'.
+     * Default false (only active rows). */
+    includeSuperseded?: boolean;
+    /** v0.3.0 (BUG-001) — when true, the slim payload also carries
+     * `confidence`, `evidence_count` and `last_verified_at` (v0.3.0 K3
+     * evidence fields). Default false (minimal slim shape). */
+    evidence?: boolean;
 }
 /** v0.2.0 — slim query payload (K2-010). Snippet is a short content prefix;
  * `score` is the FTS5 BM25 score when available, falling back to
@@ -59,28 +91,88 @@ export interface SlimMemory {
     score: number;
     snippet: string;
 }
+/** v0.3.0 (BUG-001) — slim payload extended with the evidence fields when
+ * `query({ evidence: true })`. Fills the `kevin_query(evidence: true)`
+ * contract without falling back to the full `Memory` shape. */
+export interface SlimMemoryWithEvidence extends SlimMemory {
+    confidence: number | null;
+    evidence_count: number | null;
+    last_verified_at: string | null;
+}
 export interface GetRelevantInput {
     query?: string;
     maxTokens?: number;
     scope?: MemoryScope | "all";
+    /** v0.3.0 — when true, includes rows where status = 'superseded'.
+     * Default false (only active rows). */
+    includeSuperseded?: boolean;
+    /**
+     * v0.4.0 (BUG-016) — when false, the relevance bump (K2-023) is
+     * skipped. Used by ContextInjector's probe fetch so the decision and
+     * any retry both see the ORIGINAL ranking; the single bump is applied
+     * by the fetch that actually produces the injected block.
+     */
+    bump?: boolean;
 }
 export declare class MemoryService {
     private readonly metrics;
     constructor(store: Store, metrics?: Metrics | null);
     private store;
+    private hasRecurrenceColumn;
+    private _hasRecurrenceColumn;
     save(input: SaveInput): string;
     getById(id: string): Memory | null;
+    /**
+     * v0.4.0 (K4-016) — most recent ACTIVE memory for a fingerprint,
+     * optionally filtered by type. Feeds the HITL suggestion lookup
+     * (most-recurred fingerprint → its pattern memory).
+     */
+    getByFingerprint(fingerprint: string, type?: MemoryType): Memory | null;
     update(id: string, fields: Partial<Memory>): void;
     delete(id: string): void;
     /** v0.1.x behavior — returns full `Memory` rows. */
     query(input: QueryInput & {
         full: true;
     }): Memory[];
+    /** v0.3.0 (BUG-001) — slim rows carrying the evidence fields. */
+    query(input: QueryInput & {
+        evidence: true;
+    }): SlimMemoryWithEvidence[];
     /** v0.2.0 default — returns `SlimMemory` rows. */
     query(input: QueryInput): SlimMemory[];
+    private isCrossProjectEnabled;
+    /**
+     * v0.4.0 (K4-012) — read a kevin_settings flag by key. Falls back to
+     * the caller-provided default when the key is missing or the table is
+     * unavailable (legacy DB without the settings table).
+     */
+    getSetting(key: string, fallback?: string): string;
     private loadAll;
     private queryRelevant;
     getRelevant(input: GetRelevantInput): Memory[];
+    /**
+     * v0.4.0 (BUG-016) — apply the K2-023 relevance bump to a fixed slice
+     * of ids, exactly once. Lets ContextInjector probe without mutating
+     * and still bump the slice it actually injects.
+     */
+    bumpRelevance(ids: string[]): void;
+    /**
+     * v0.3.0 (K3-004) — Promote an error memory to a causal pattern.
+     *
+     * Creates a new `pattern` memory with `origin = 'causal'`, derived
+     * confidence, and evidence count. The original error memory is NOT
+     * deleted — the audit trail is preserved. Returns the new memory id,
+     * or null when the source error is not eligible (missing fingerprint,
+     * wrong type, or already promoted).
+     */
+    /**
+     * v0.4.0 (K4-009) — returns `{ id, created }` so callers can tell a
+     * newly-created pattern from an idempotent refresh.
+     */
+    promoteToPattern(errorId: string, evidenceCount: number, recurrenceCount?: number): {
+        id: string;
+        created: boolean;
+    } | null;
     /**
      * v0.2.0 (K2-026) — Feedback loop positive half (plan §B6.10 / D2-10).
      *
@@ -93,4 +185,33 @@ export declare class MemoryService {
      * Returns the number of memories that received a positive boost.
      */
     boostPositiveReflectors(sessionId: string): number;
+    /**
+     * v0.3.0 (K3-013) — Feedback loop negative half.
+     *
+     * For each reflector-sourced error memory from this session whose
+     * fingerprint DID recur as a failing tool_call (the lesson didn't
+     * prevent the error), decrement `relevance_score` by `RELEVANCE_PENALTY`
+     * (down to zero) and increment `evidence_count` as a negative signal.
+     * Agent-saved memories are NEVER penalized.
+     *
+     * Returns the number of memories penalized.
+     */
+    /**
+     * v0.3.0 fix — Mirror of the free function `countSupersedeCandidates`
+     * exposed as an instance method so `okf-import` (which holds a
+     * `MemoryService` reference but not the underlying `Store`) can count
+     * rows that `save()` will mark as superseded.
+     */
+    countSupersedeCandidates(type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;
+    penalizeRecurringReflectors(sessionId: string): number;
 }
+/**
+ * v0.3.0 fix — Count active memories that would be superseded by a new
+ * row with the given (type, fingerprint, projectId) tuple. Used by
+ * `okf-import` to populate `ImportResult.superseded` accurately.
+ *
+ * Matches the supersede logic in `save()`: only `decision` and `rule`
+ * types supersede prior rows with the same fingerprint. Returns 0 for
+ * any other type.
+ */
+export declare function countSupersedeCandidates(store: Store, type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;