@jmtrin/kevin-core 1.3.0

package/dist/kevin_bench.js

@@ -0,0 +1,83 @@
+/**
+ * K10-019 — kevin_bench: reports what `npm run bench` recorded.
+ *
+ * It NEVER runs the benchmark — running it from inside a live session
+ * would measure the session and pollute the user's database. The module
+ * imports nothing from scripts/bench.ts; the corpus digest of the on-disk
+ * corpus is recomputed here with the same fnv1a64 discipline so a result
+ * computed from a different corpus is visibly a different measurement.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveEnv } from "./env.js";
+import { fnv1a64 } from "./fingerprint.js";
+function onDiskCorpusDigest(cwd) {
+    try {
+        const dir = join(cwd, "bench", "corpus");
+        statSync(dir);
+        const mem = readFileSync(join(dir, "memories.jsonl"), "utf8");
+        const q = readFileSync(join(dir, "queries.jsonl"), "utf8");
+        return {
+            digest: fnv1a64(`${mem}\n${q}`),
+            queries: q.split("\n").filter((l) => l.trim().length > 0).length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function noRuns() {
+    return {
+        has_runs: false,
+        hint: "npm run bench",
+    };
+}
+export function buildKevinBench(deps, args, env) {
+    if (args.action === "status") {
+        const count = deps.store
+            .prepare("SELECT COUNT(*) AS c FROM bench_runs")
+            .get();
+        if (!count || count.c === 0)
+            return noRuns();
+        const latest = deps.store
+            .prepare("SELECT corpus_digest, contract_digest, package_version, runtime, ran_at FROM bench_runs ORDER BY id DESC LIMIT 1")
+            .get();
+        if (!latest)
+            return noRuns();
+        const disk = onDiskCorpusDigest(deps.cwd ?? resolveEnv(env).projectRoot);
+        return {
+            has_runs: true,
+            total_runs: count.c,
+            corpus_digest: latest.corpus_digest,
+            contract_digest: latest.contract_digest,
+            package_version: latest.package_version,
+            runtime: latest.runtime,
+            last_ran_at: latest.ran_at,
+            corpus_on_disk: disk === null ? null : disk.digest,
+            matches_disk_corpus: disk !== null && disk.digest === latest.corpus_digest,
+        };
+    }
+    const latest = deps.store
+        .prepare("SELECT corpus_digest, contract_digest, package_version, runtime, ran_at FROM bench_runs ORDER BY id DESC LIMIT 1")
+        .get();
+    if (!latest)
+        return noRuns();
+    const rows = deps.store
+        .prepare("SELECT arm, k, precision_at_k, recall_at_k, mrr FROM bench_runs WHERE corpus_digest = ? AND ran_at = ?")
+        .all(latest.corpus_digest, latest.ran_at);
+    return {
+        has_runs: true,
+        corpus_digest: latest.corpus_digest,
+        contract_digest: latest.contract_digest,
+        package_version: latest.package_version,
+        runtime: latest.runtime,
+        ran_at: latest.ran_at,
+        arms: rows.map((r) => ({
+            arm: r.arm,
+            k: r.k,
+            precision_at_k: r.precision_at_k,
+            recall_at_k: r.recall_at_k,
+            mrr: r.mrr,
+        })),
+    };
+}

package/dist/kevin_conflicts.d.ts

@@ -0,0 +1,9 @@
+import type { ConflictDetector } from "./ConflictDetector.js";
+import type { Store } from "./Store.js";
+export interface KevinConflictsDeps {
+    store: Store;
+    detector: ConflictDetector;
+    projectId: string;
+}
+export type ConflictAction = "list" | "acknowledge" | "resolve";
+export declare function executeKevinConflicts(deps: KevinConflictsDeps, action: ConflictAction, id?: string, keep?: string, requestedStatus?: "open" | "acknowledged" | "resolved"): Record<string, unknown>;

package/dist/kevin_conflicts.js

@@ -0,0 +1,50 @@
+export function executeKevinConflicts(deps, action, id, keep, requestedStatus) {
+    if (action === "acknowledge") {
+        if (!id)
+            return { error: "missing_id" };
+        // Mirror resolve()'s honesty: acknowledging a nonexistent or foreign id
+        // must not be reported as a success.
+        const row = deps.store
+            .prepare("SELECT id FROM memory_conflicts WHERE id = ? AND project_id = ?")
+            .get(id, deps.projectId);
+        if (!row)
+            return { error: "not_found", id };
+        deps.detector.acknowledge(id);
+        return { id, status: "acknowledged" };
+    }
+    if (action === "resolve") {
+        if (!id || !keep)
+            return { error: "missing_id_or_keep" };
+        const row = deps.store
+            .prepare("SELECT memory_a, memory_b FROM memory_conflicts WHERE id = ? AND project_id = ?")
+            .get(id, deps.projectId);
+        if (!row)
+            return { error: "not_found", id };
+        if (keep !== row.memory_a && keep !== row.memory_b) {
+            return { error: "invalid_keep", id, keep };
+        }
+        deps.detector.resolve(id, keep);
+        return {
+            id,
+            status: "resolved",
+            kept: keep,
+            other: keep === row.memory_a ? row.memory_b : row.memory_a,
+        };
+    }
+    const status = requestedStatus ?? "open";
+    const rows = deps.store
+        .prepare(`SELECT id, kind, memory_a, memory_b, fact_id, detail, status, detected_at
+			 FROM memory_conflicts WHERE project_id = ? AND status = ?
+			 ORDER BY detected_at, id`)
+        .all(deps.projectId, status);
+    const counts = deps.store
+        .prepare(`SELECT status, COUNT(*) AS n FROM memory_conflicts
+			 WHERE project_id = ? GROUP BY status`)
+        .all(deps.projectId);
+    return {
+        open: counts.find((row) => row.status === "open")?.n ?? 0,
+        acknowledged: counts.find((row) => row.status === "acknowledged")?.n ?? 0,
+        resolved: counts.find((row) => row.status === "resolved")?.n ?? 0,
+        conflicts: rows,
+    };
+}

package/dist/kevin_contract.d.ts

@@ -0,0 +1,8 @@
+export interface KevinContractDeps {
+    packageVersion: string;
+}
+export interface KevinContractArgs {
+    clause?: string;
+    format?: "summary" | "full";
+}
+export declare function buildKevinContract(deps: KevinContractDeps, args: KevinContractArgs): Record<string, unknown>;

package/dist/kevin_contract.js

@@ -0,0 +1,59 @@
+/**
+ * K10-018 — kevin_contract: the frozen surface, inspectable at runtime.
+ *
+ * Read-only. Returns the live contract with its digest and per-clause
+ * stability/since/deprecation; with `clause`, one clause's full value.
+ * No filesystem paths, no project ids, no LLM, no network.
+ */
+import { contractDigest, describeContract, } from "./contract.js";
+export function buildKevinContract(deps, args) {
+    const contract = describeContract();
+    const digest = contractDigest(contract);
+    const format = args.format ?? "summary";
+    if (args.clause !== undefined) {
+        const clause = contract.clauses.find((c) => c.id === args.clause);
+        if (!clause) {
+            return {
+                error: "unknown_clause",
+                clause: args.clause,
+                known_clauses: contract.clauses.map((c) => c.id),
+            };
+        }
+        return {
+            contract_version: contract.contractVersion,
+            digest,
+            package_version: deps.packageVersion,
+            clause: {
+                id: clause.id,
+                title: clause.title,
+                stability: clause.stability,
+                since: clause.since,
+                ...(clause.deprecated ? { deprecated: clause.deprecated } : {}),
+                ...(clause.replacement ? { replacement: clause.replacement } : {}),
+                value: clause.value,
+            },
+        };
+    }
+    if (format === "full") {
+        return {
+            contract_version: contract.contractVersion,
+            digest,
+            package_version: deps.packageVersion,
+            clauses: contract.clauses,
+            deprecated: contract.clauses.filter((c) => c.deprecated).map((c) => c.id),
+        };
+    }
+    return {
+        contract_version: contract.contractVersion,
+        digest,
+        package_version: deps.packageVersion,
+        clauses: contract.clauses.map((c) => ({
+            id: c.id,
+            title: c.title,
+            stability: c.stability,
+            since: c.since,
+            ...(c.deprecated ? { deprecated: c.deprecated } : {}),
+        })),
+        deprecated: contract.clauses.filter((c) => c.deprecated).map((c) => c.id),
+    };
+}

package/dist/kevin_doctor.d.ts

@@ -0,0 +1,63 @@
+import { type KevinEnv } from "./env.js";
+import type { Store } from "./Store.js";
+import type { HostSurface } from "./host.js";
+import type { SettingsReader } from "./native.js";
+export interface DoctorHook {
+    readonly hook: string;
+    readonly experimental: boolean;
+    readonly state: "live" | "dead" | "unknown";
+    readonly fire_count: number;
+    readonly expected_count: number;
+    readonly since?: string;
+}
+export interface DoctorReport {
+    readonly host: {
+        readonly plugin_version: string | null;
+        readonly flavour: string;
+        readonly shell_available: boolean;
+        readonly v2: {
+            readonly skill: boolean;
+            readonly reference: boolean;
+        };
+    };
+    readonly hooks: DoctorHook[];
+    readonly dependencies: {
+        readonly declared: string[];
+        readonly zod_copies: number | null;
+        readonly note?: string;
+    };
+    readonly native: {
+        readonly enabled: boolean;
+        readonly registered: {
+            readonly skill: boolean;
+            readonly reference: boolean;
+        };
+        readonly verified: {
+            readonly skill: boolean;
+            readonly reference: boolean;
+        };
+    };
+    /** v1.0.0 (K10-021) — scopes whose most recent sample exceeded their
+     * p95 budget. Omitted entirely on pre-011 databases (no table). */
+    readonly perf?: {
+        readonly scopes_over_budget: readonly string[];
+    };
+    readonly verdict: "healthy" | "degraded" | "unknown";
+    readonly reason: string;
+    readonly partial: boolean;
+}
+/**
+ * Count resolved zod copies under `cwd`'s dependency tree. The expected
+ * value after K9-005 is 1; a second copy is exactly the regression this
+ * field exists to catch. On any walk failure the count is `null` and the
+ * note says so — never a guess.
+ */
+export declare function countZodCopies(cwd: string): {
+    copies: number | null;
+    note?: string;
+};
+export interface DoctorOptions {
+    /** Directory to walk for zod copies; defaults to env.projectRoot. */
+    readonly zodRoot?: string;
+}
+export declare function buildDoctor(store: Store, host: HostSurface, settings: SettingsReader, options?: DoctorOptions, env?: KevinEnv): DoctorReport;

package/dist/kevin_doctor.js

@@ -0,0 +1,197 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { resolveEnv } from "./env.js";
+import { reduceVerdict, } from "./HookLiveness.js";
+import { HOOK_NAMES } from "./Migrate.js";
+/** Dead first, then unknown, then live — the failure is the first thing
+ * on screen. Ties break on the canonical hook name. */
+const STATE_ORDER = {
+    dead: 0,
+    unknown: 1,
+    live: 2,
+};
+/** The hooks block is pure SQL over the persisted hook_liveness table:
+ * the dead flag is materialized at expect() time (K9-010) so flush() can
+ * persist dead_since even when report() never runs — this block reads
+ * that persisted state, independent of any live HookLiveness object. */
+function hooksBlock(store) {
+    let rows = [];
+    try {
+        rows = store
+            .prepare("SELECT hook, experimental, fire_count, expected_count, dead_since FROM hook_liveness")
+            .all();
+    }
+    catch {
+        return { hooks: [], partial: true };
+    }
+    // Only hooks the plugin knows about are reported; a foreign row (from
+    // a future release) is skipped, mirroring HookLiveness.loadFromDb.
+    const reports = rows
+        .filter((row) => HOOK_NAMES.includes(row.hook))
+        .map((row) => ({
+        hook: row.hook,
+        experimental: row.experimental === 1,
+        state: row.fire_count > 0
+            ? "live"
+            : row.dead_since !== null
+                ? "dead"
+                : "unknown",
+        firstSeenAt: null,
+        lastSeenAt: null,
+        fireCount: row.fire_count,
+        expectedCount: row.expected_count,
+        deadSince: row.dead_since,
+    }));
+    reports.sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state] ||
+        a.hook.localeCompare(b.hook));
+    const hooks = reports.map((r) => ({
+        hook: r.hook,
+        experimental: r.experimental,
+        state: r.state,
+        fire_count: r.fireCount,
+        expected_count: r.expectedCount,
+        ...(r.deadSince !== null ? { since: r.deadSince } : {}),
+    }));
+    return { hooks, partial: false };
+}
+/**
+ * Count resolved zod copies under `cwd`'s dependency tree. The expected
+ * value after K9-005 is 1; a second copy is exactly the regression this
+ * field exists to catch. On any walk failure the count is `null` and the
+ * note says so — never a guess.
+ */
+export function countZodCopies(cwd) {
+    try {
+        if (!existsSync(cwd)) {
+            return { copies: null, note: "zod resolution walk failed" };
+        }
+        const seen = new Set();
+        const stack = [cwd];
+        let copies = 0;
+        // Bounded walk: node_modules is normally shallow; nested copies
+        // (node_modules/<pkg>/node_modules/zod) sit within a few levels.
+        for (let depth = 0; stack.length > 0 && depth < 8; depth += 1) {
+            const next = [];
+            for (const dir of stack) {
+                const nm = join(dir, "node_modules");
+                if (!existsSync(nm))
+                    continue;
+                let entries;
+                try {
+                    entries = readdirSync(nm, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    if (entry.name === "zod") {
+                        const pkg = join(nm, "zod", "package.json");
+                        if (existsSync(pkg) && !seen.has(pkg)) {
+                            seen.add(pkg);
+                            copies += 1;
+                        }
+                    }
+                    else if (entry.name !== ".bin" && entry.name !== ".cache") {
+                        next.push(join(nm, entry.name));
+                    }
+                }
+            }
+            stack.length = 0;
+            stack.push(...next);
+        }
+        return { copies };
+    }
+    catch {
+        return { copies: null, note: "zod resolution walk failed" };
+    }
+}
+/** v1.0.0 (K10-021) — scopes whose most recent perf sample breached the
+ * p95 budget. The within_budget flag is materialized by Perf.flush()
+ * against the frozen BUDGETS; this block reads that persisted verdict
+ * and never re-aggregates. A missing table (pre-011 DB) yields no
+ * block rather than an empty one, matching the hooks precedent. */
+function perfOverBudget(store) {
+    try {
+        const rows = store
+            .prepare("SELECT DISTINCT scope FROM perf_samples WHERE within_budget = 0 ORDER BY scope")
+            .all();
+        return rows.map((r) => r.scope);
+    }
+    catch {
+        return null;
+    }
+}
+function lastRegistration(store, surface) {
+    try {
+        const row = store
+            .prepare("SELECT surface, registered, verified FROM native_registrations WHERE surface = ? ORDER BY attached_at DESC, id DESC LIMIT 1")
+            .get(surface);
+        if (!row)
+            return { registered: false, verified: false };
+        return { registered: row.registered === 1, verified: row.verified === 1 };
+    }
+    catch {
+        return { registered: false, verified: false };
+    }
+}
+export function buildDoctor(store, host, settings, options = {}, env) {
+    // The host block comes from the frozen probe result captured at
+    // construction — kevin_doctor never re-probes (K9-004: probe once,
+    // freeze, reuse).
+    const hooks = hooksBlock(store);
+    let verdict = reduceVerdict(hooks.hooks.map((h) => ({
+        hook: h.hook,
+        experimental: h.experimental,
+        state: h.state,
+        firstSeenAt: null,
+        lastSeenAt: null,
+        fireCount: h.fire_count,
+        expectedCount: h.expected_count,
+        deadSince: h.since ?? null,
+    })));
+    // v1.0.0 (K10-021) — a slow plugin is not healthy even when every
+    // hook is live. A budget breach degrades the verdict and names the
+    // scope; a dead hook keeps its reason; `unknown` is never rounded up.
+    const breaches = perfOverBudget(store);
+    if (breaches !== null &&
+        breaches.length > 0 &&
+        verdict.verdict !== "degraded") {
+        verdict = {
+            verdict: "degraded",
+            reason: `perf budget exceeded: ${breaches.join(", ")}`,
+        };
+    }
+    const zod = countZodCopies(options.zodRoot ?? resolveEnv(env).projectRoot);
+    const enabled = settings.getSetting("native_registration_enabled", "0") === "1";
+    return {
+        host: {
+            plugin_version: host.pluginVersion,
+            flavour: host.flavour,
+            shell_available: host.hasShell,
+            v2: { skill: host.v2.skill, reference: host.v2.reference },
+        },
+        hooks: hooks.hooks,
+        dependencies: {
+            declared: ["@opencode-ai/plugin"],
+            zod_copies: zod.copies,
+            ...(zod.note !== undefined ? { note: zod.note } : {}),
+        },
+        native: {
+            enabled,
+            registered: {
+                skill: lastRegistration(store, "skill").registered,
+                reference: lastRegistration(store, "reference").registered,
+            },
+            verified: {
+                skill: lastRegistration(store, "skill").verified,
+                reference: lastRegistration(store, "reference").verified,
+            },
+        },
+        verdict: verdict.verdict,
+        reason: verdict.reason,
+        ...(breaches !== null ? { perf: { scopes_over_budget: breaches } } : {}),
+        partial: hooks.partial,
+    };
+}

package/dist/kevin_facts.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { RepoTruth } from "./RepoTruth.js";
+import type { Store } from "./Store.js";
+/**
+ * v0.7.0 (K7-009 / plan §5.7) — `kevin_facts`.
+ *
+ * The user-facing answer to "why did Kevin stop suggesting that?". Lists the
+ * repository facts the current project was scanned for and every memory that
+ * was de-ranked by a contradiction, with its `truth_penalty`, `contradicted_at`
+ * and the human-readable reasons. Pure read apart from the optional re-scan. No
+ * LLM, no network, no hot-path cost.
+ */
+export interface KevinFactsDeps {
+    store: Store;
+    memoryService: MemoryService;
+    repoTruth: RepoTruth;
+    projectId: string;
+}
+export interface PenalizedMemory {
+    id: string;
+    type: string;
+    truth_penalty: number;
+    contradicted_at: string | null;
+    reasons: string[];
+}
+export interface KevinFactsResult {
+    project_id: string;
+    scanned_at: string | null;
+    truncated: {
+        is_truncated: true;
+        count: number;
+    } | {
+        is_truncated: false;
+    };
+    facts: {
+        file: string;
+        key_path: string;
+        value: string;
+    }[];
+    penalized: PenalizedMemory[];
+}
+export declare function buildKevinFacts(deps: KevinFactsDeps, refresh: boolean): KevinFactsResult;

package/dist/kevin_facts.js

@@ -0,0 +1,36 @@
+export function buildKevinFacts(deps, refresh) {
+    if (refresh)
+        deps.repoTruth.scan();
+    // Penalized memories: scoped to the project, only those with a penalty.
+    const rows = deps.store
+        .prepare(`SELECT id, type, truth_penalty, contradicted_at
+			 FROM memories
+			 WHERE project_id = ? AND truth_penalty > 0
+			 ORDER BY created_at`)
+        .all(deps.projectId);
+    const penalized = rows.map((r) => {
+        const mem = deps.memoryService.getById(r.id);
+        return {
+            id: r.id,
+            type: r.type,
+            truth_penalty: r.truth_penalty,
+            contradicted_at: r.contradicted_at,
+            reasons: mem ? deps.repoTruth.contradictions(mem) : [],
+        };
+    });
+    const stored = deps.repoTruth.facts();
+    const truncatedFact = stored.find((f) => f.keyPath === "_truncated");
+    const facts = stored
+        .filter((f) => f.keyPath !== "_truncated")
+        .map((f) => ({ file: f.file, key_path: f.keyPath, value: f.value }));
+    const scanned_at = deps.repoTruth.scannedAt();
+    return {
+        project_id: deps.projectId,
+        scanned_at,
+        truncated: truncatedFact
+            ? { is_truncated: true, count: Number(truncatedFact.value) || 0 }
+            : { is_truncated: false },
+        facts,
+        penalized,
+    };
+}

package/dist/kevin_forget.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { SharedLayer } from "./SharedLayer.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+export interface ForgetInput {
+    ids: string[];
+    confirm?: boolean;
+}
+export interface Deps {
+    store: Store;
+    memoryService: MemoryService;
+    sharedLayer: SharedLayer;
+    okfPath: string;
+    metrics: Metrics;
+}
+export interface ForgetResult {
+    action: "forget";
+    ok: boolean;
+    dry_run: boolean;
+    per_id: Array<{
+        id: string;
+        archived: boolean;
+        reason?: string;
+        tombstone?: {
+            entry_id: string;
+            planned: boolean;
+            applied: boolean;
+        };
+    }>;
+    noop?: boolean;
+    reason?: string;
+}
+export declare function handleForget(input: ForgetInput, deps: Deps): ForgetResult;