@jmtrin/kevin-core 1.3.0

package/dist/replay.js

@@ -0,0 +1,215 @@
+import { Archiver } from "./Archiver.js";
+import { CausalChain } from "./CausalChain.js";
+import { ContextInjector } from "./ContextInjector.js";
+import { composeIdlePipeline } from "./idle-pipeline.js";
+import { InjectionLedger } from "./InjectionLedger.js";
+import { MemoryService } from "./MemoryService.js";
+import { Migrate, exportMigrationsDir } from "./Migrate.js";
+import { Reflector } from "./Reflector.js";
+import { Store } from "./Store.js";
+import { ToolCallObserver } from "./ToolCallObserver.js";
+import { Metrics } from "./metrics.js";
+export async function replay(transcript, opts) {
+    const store = new Store({ path: opts?.dbPath ?? ":memory:" });
+    await new Migrate(store, exportMigrationsDir()).run();
+    // Freeze retrieval BEFORE any query happens (K5-008): deterministic
+    // mode uses the DATE_NOW sentinel, ignores recency and never bumps.
+    store
+        .prepare("INSERT OR IGNORE INTO kevin_settings (key, value) VALUES ('deterministic_retrieval', '1')")
+        .run();
+    store
+        .prepare("UPDATE kevin_settings SET value = '1' WHERE key = 'deterministic_retrieval'")
+        .run();
+    // v0.6.0 (K6-022) — the release floor (0.6) blocks every
+    // single-observation memory the v0.5-era fixture exercises; the replay
+    // harness preserves the v0.5 push semantics it was recorded under, the
+    // same opt-out the legacy plugin harnesses apply.
+    store
+        .prepare("INSERT OR IGNORE INTO kevin_settings (key, value) VALUES ('injection_confidence_floor', '0')")
+        .run();
+    store
+        .prepare("UPDATE kevin_settings SET value = '0' WHERE key = 'injection_confidence_floor'")
+        .run();
+    const metrics = new Metrics(store);
+    const memoryService = new MemoryService(store, metrics);
+    const observer = new ToolCallObserver(store, metrics);
+    // v0.3.0 fix (mirrors index.ts) — the Reflector stamps
+    // tool_calls.error_fingerprint with the stderr-based fingerprint the
+    // error memory uses; without it the recurrence queries in settle and
+    // the feedback loop never match (tool_calls.fingerprint is keyed on
+    // `${tool}|${args}|${success}`, memories on a hash of stderr/stdout).
+    const linkErrorStmt = store.prepare("UPDATE tool_calls SET error_fingerprint = ? WHERE id = ?");
+    const reflector = new Reflector(memoryService, {
+        throttleMs: 0,
+        onLinkError: (callID, fp) => {
+            linkErrorStmt.run(fp, callID);
+        },
+    }, metrics);
+    const ledger = new InjectionLedger(store, metrics);
+    const injector = new ContextInjector(memoryService, metrics, ledger);
+    const causalChain = new CausalChain(store, memoryService, metrics);
+    // The Archiver reads the clock through this accessor, which is updated
+    // to the current event's `at` before each event is processed.
+    let currentAt = new Date(transcript.events[0]?.at ?? Date.now());
+    const archiver = new Archiver(store, memoryService, metrics, () => currentAt);
+    const lastUserQueryBySession = new Map();
+    const callCache = new Map();
+    function resolveQuery(sessionId) {
+        return lastUserQueryBySession.get(sessionId) ?? "";
+    }
+    for (const event of transcript.events) {
+        currentAt = new Date(event.at);
+        await handleEvent(event);
+    }
+    metrics.flush();
+    const outcomeRows = store
+        .prepare("SELECT outcome, COUNT(*) AS n FROM kevin_injections GROUP BY outcome")
+        .all();
+    const counts = {
+        unmeasured: 0,
+        effective: 0,
+        ineffective: 0,
+        inconclusive: 0,
+    };
+    for (const r of outcomeRows) {
+        counts[r.outcome] = r.n;
+    }
+    const total = outcomeRows.reduce((acc, r) => acc + r.n, 0);
+    const tokenValue = (key) => {
+        const row = store
+            .prepare("SELECT value FROM kevin_metrics WHERE key = ?")
+            .get(key);
+        return row?.value ?? 0;
+    };
+    return {
+        transcript: transcript.name,
+        memoriesCreated: totalMemories(store),
+        injections: {
+            total,
+            effective: counts.effective,
+            ineffective: counts.ineffective,
+            inconclusive: counts.inconclusive,
+            unmeasured: counts.unmeasured,
+        },
+        precisionRate: metrics.precisionRate(),
+        coverageRate: metrics.coverageRate(),
+        tokensInjected: {
+            prePrompt: tokenValue("tokens_injected_pre_prompt"),
+            compacting: tokenValue("tokens_injected_compacting"),
+        },
+        blocked: metrics.blockedSnapshot(),
+    };
+    async function handleEvent(event) {
+        switch (event.kind) {
+            case "session.created":
+                // Mirror of the live wiring (index.ts): a fresh session must
+                // not inherit the previous session's injection seen-set
+                // (plan §5.1 rule 3). Without this, a multi-session
+                // transcript would block every memory in session 2 with
+                // `seen_this_session` while the live plugin would admit it.
+                injector.onSessionCreated(event.sessionId);
+                return;
+            case "chat.message": {
+                const derived = injector.deriveQuery([
+                    { role: "user", content: event.text },
+                ]);
+                if (derived.length > 0) {
+                    lastUserQueryBySession.set(event.sessionId, derived);
+                }
+                return;
+            }
+            case "tool.before": {
+                callCache.set(event.callId, {
+                    tool: event.tool,
+                    args: event.args,
+                });
+                observer.onBefore({
+                    tool: event.tool,
+                    args: event.args,
+                    sessionId: event.sessionId,
+                    callID: event.callId,
+                    projectId: null,
+                }, {});
+                return;
+            }
+            case "tool.after": {
+                const cached = callCache.get(event.callId);
+                const tool = cached?.tool ?? "unknown";
+                const args = cached?.args ?? {};
+                const stderr = event.stderr ?? "";
+                const stdout = event.stdout ?? "";
+                observer.onAfter({
+                    tool,
+                    args,
+                    sessionId: event.sessionId,
+                    callID: event.callId,
+                    projectId: null,
+                }, { success: event.success, stdout, stderr, exitCode: event.exitCode });
+                if (!event.success) {
+                    await reflector.invoke({
+                        toolName: tool,
+                        argsSummary: observer.summarizeArgs(args),
+                        stderr,
+                        stdout,
+                        exitCode: event.exitCode,
+                        errorType: observer.inferErrorType(stderr, stdout, event.exitCode),
+                        sessionId: event.sessionId,
+                        callID: event.callId,
+                        projectId: null,
+                    });
+                }
+                else {
+                    causalChain.onSuccess(tool, args, null, event.sessionId);
+                }
+                return;
+            }
+            case "system.transform": {
+                const query = resolveQuery(event.sessionId);
+                if (!query)
+                    return;
+                const output = { system: [] };
+                injector.onSystemTransform({
+                    sessionID: event.sessionId,
+                    messages: [{ role: "user", content: query }],
+                }, output);
+                return;
+            }
+            case "compacting": {
+                const query = resolveQuery(event.sessionId);
+                if (!query)
+                    return;
+                const output = { context: [] };
+                injector.onCompacting({
+                    sessionID: event.sessionId,
+                    messages: [{ role: "user", content: query }],
+                }, output);
+                return;
+            }
+            case "session.idle": {
+                // K13-010 (D13-07) — single ORDER via composeIdlePipeline. Replay
+                // provides core-native implementations; adapter provides closures
+                // over its live services. The ORDER array is the single source.
+                await composeIdlePipeline({
+                    "ledger.settle": () => { ledger.settle(event.sessionId); },
+                    "archiver.run": () => { archiver.run(); },
+                    "metrics.flush": () => { metrics.flush(); },
+                    // core-native stubs for steps that are no-ops in hermetic replay
+                    // but keep ORDER parity with the adapter (e.g. pattern mining)
+                    "patternMiner.mine": () => { },
+                    "causalChain.onSessionIdle": () => { void causalChain.onSessionIdle(event.sessionId); },
+                });
+                return;
+            }
+        }
+    }
+}
+/**
+ * K13-010 — alias required by plan §4: runReplaySession is the core-native mount
+ * entry used by the parity harness (K13-011) and old tests. Signature mirrors
+ * `replay` but accepts env for future threading.
+ */
+export const runReplaySession = replay;
+function totalMemories(store) {
+    const row = store.prepare("SELECT COUNT(*) AS n FROM memories").get();
+    return row.n ?? 0;
+}

package/dist/sqlite-adapter.d.ts

@@ -0,0 +1,12 @@
+export interface SqliteStatement {
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    run(...params: unknown[]): void;
+}
+export interface SqliteAdapter {
+    prepare(sql: string): SqliteStatement;
+    transaction<T>(fn: () => T): () => T;
+    exec(sql: string): void;
+    close(): void;
+}
+export declare function createDatabase(path: string): SqliteAdapter;

package/dist/sqlite-adapter.js

@@ -0,0 +1,78 @@
+import { createRequire } from "node:module";
+const localRequire = createRequire(import.meta.url);
+function detectRuntime() {
+    if (typeof globalThis.Bun !== "undefined") {
+        return "bun";
+    }
+    return "node";
+}
+function loadBunDatabase(path) {
+    const mod = localRequire("bun:sqlite");
+    return new mod.Database(path);
+}
+/**
+ * Wrapper sobre `node:sqlite` (DatabaseSync, estable en Node 24+).
+ * API equivalente a better-sqlite3 excepto `transaction`, que implementamos
+ * manualmente con BEGIN/COMMIT/ROLLBACK.
+ */
+class NodeSqliteAdapter {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        return this.db.prepare(sql);
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+    transaction(fn) {
+        return () => {
+            this.db.exec("BEGIN");
+            try {
+                const result = fn();
+                this.db.exec("COMMIT");
+                return result;
+            }
+            catch (err) {
+                try {
+                    this.db.exec("ROLLBACK");
+                }
+                catch {
+                    // ignore rollback errors
+                }
+                throw err;
+            }
+        };
+    }
+}
+function loadNodeSqliteDatabase(path) {
+    const mod = localRequire("node:sqlite");
+    return new NodeSqliteAdapter(new mod.DatabaseSync(path));
+}
+function loadBetterSqliteDatabase(path) {
+    const D = localRequire("better-sqlite3");
+    const Ctor = "default" in D ? D.default : D;
+    return new Ctor(path);
+}
+function loadNodeDatabase(path) {
+    // 1) Prefer node:sqlite (built-in, sin binarios nativos que descargar).
+    //    Estable en Node 24+ sin flag; en Node 22/23 requiere --experimental-sqlite.
+    //    Si require falla (modulo ausente o flag deshabilitado), cae al fallback.
+    try {
+        return loadNodeSqliteDatabase(path);
+    }
+    catch {
+        // 2) Fallback a better-sqlite3 (Node 20 o Node 22/23 sin flag).
+        return loadBetterSqliteDatabase(path);
+    }
+}
+export function createDatabase(path) {
+    if (detectRuntime() === "bun") {
+        return loadBunDatabase(path);
+    }
+    return loadNodeDatabase(path);
+}

package/dist/time-ms.d.ts

@@ -0,0 +1 @@
+export declare function toMs(legacyValue: string | null | undefined, msValue: number | null | undefined): number | null;

package/dist/time-ms.js

@@ -0,0 +1,16 @@
+// v1.1.0 (K11-003/K11-004 / plan §5.2, D11-01) — millisecond helper.
+// Readers prefer _ms and fall back to legacy second-granularity column.
+// The helper is the single implementation imported by InjectionLedger and
+// CausalChain (moved here in K11-004 to avoid duplication).
+export function toMs(legacyValue, msValue) {
+    if (typeof msValue === "number" && !Number.isNaN(msValue))
+        return msValue;
+    if (!legacyValue)
+        return null;
+    // SQLite datetime('now') is 'YYYY-MM-DD HH:MM:SS' UTC
+    const iso = legacyValue.includes("T")
+        ? legacyValue
+        : `${legacyValue.replace(" ", "T")}Z`;
+    const n = Date.parse(iso);
+    return Number.isNaN(n) ? null : n;
+}

package/dist/tui-types.d.ts

@@ -0,0 +1,59 @@
+export interface ProposalView {
+    readonly id: string;
+    readonly kind: string;
+    readonly target_path: string;
+    readonly diff: string;
+    readonly memory_ids: readonly string[];
+    readonly created_at: string;
+    readonly truncated?: boolean;
+    readonly token?: string;
+}
+export interface ConflictView {
+    readonly id: string;
+    readonly kind: string;
+    readonly a_summary: string;
+    readonly b_summary: string;
+    readonly opened_at: string;
+}
+export interface HealthView {
+    readonly verdict: string;
+    readonly reason: string;
+    readonly hooks: readonly {
+        readonly hook: string;
+        readonly state: string;
+        readonly fire_count: number;
+        readonly expected_count: number;
+    }[];
+    readonly perf: readonly {
+        readonly scope: string;
+        readonly p95: number;
+        readonly budget_p95: number;
+        readonly within_budget: boolean;
+    }[];
+    readonly contract_digest: string;
+    readonly counters: Record<string, number>;
+}
+export interface TuiSnapshotSet {
+    readonly generatedAt: string;
+    readonly proposals: readonly ProposalView[];
+    readonly conflicts: readonly ConflictView[];
+    readonly health: HealthView;
+}
+export type TuiAction = {
+    readonly type: "approve";
+    readonly proposalId: string;
+    readonly token: string;
+} | {
+    readonly type: "reject";
+    readonly proposalId: string;
+    readonly token: string;
+    readonly note?: string;
+} | {
+    readonly type: "acknowledge";
+    readonly conflictId: string;
+};
+export interface ActionResult {
+    readonly action: TuiAction;
+    readonly status: "applied" | "rejected" | "stale_skipped" | "error";
+    readonly detail?: string;
+}

package/dist/tui-types.js

@@ -0,0 +1,4 @@
+// v1.2.0 (K12-002 / plan §4.2-§4.3) — shared view types (type-only module).
+// This file MUST contain only type/interface exports — zero runtime values.
+// The TUI module may import it ONLY as `import type`.
+export {};

package/dist/uuid.d.ts

@@ -0,0 +1 @@
+export declare function uuidv7(): string;

package/dist/uuid.js

@@ -0,0 +1,50 @@
+import { randomBytes } from "node:crypto";
+// UUID v7 generator — timestamp-ordered IDs.
+// Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+// First 48 bits: Unix timestamp (ms). Version nibble set to 7.
+// Variant nibble starts with binary 10.
+let lastTs = 0;
+let lastRandom = Buffer.alloc(10);
+function toHex(bytes) {
+    return bytes.toString("hex");
+}
+export function uuidv7() {
+    let ts = Date.now();
+    if (ts < lastTs)
+        ts = lastTs;
+    if (ts === lastTs) {
+        for (let i = 9; i >= 0; i--) {
+            if (lastRandom[i] === 0xff) {
+                lastRandom[i] = 0;
+            }
+            else {
+                lastRandom[i]++;
+                break;
+            }
+        }
+    }
+    else {
+        lastRandom = randomBytes(10);
+    }
+    lastTs = ts;
+    const rand = lastRandom;
+    const bytes = Buffer.alloc(16);
+    bytes[0] = Math.floor(ts / 2 ** 40) & 0xff;
+    bytes[1] = Math.floor(ts / 2 ** 32) & 0xff;
+    bytes[2] = (ts >>> 24) & 0xff;
+    bytes[3] = (ts >>> 16) & 0xff;
+    bytes[4] = (ts >>> 8) & 0xff;
+    bytes[5] = ts & 0xff;
+    bytes[6] = 0x70 | (rand[0] & 0x0f);
+    bytes[7] = rand[1];
+    bytes[8] = 0x80 | (rand[2] & 0x3f);
+    bytes[9] = rand[3];
+    bytes[10] = rand[4];
+    bytes[11] = rand[5];
+    bytes[12] = rand[6];
+    bytes[13] = rand[7];
+    bytes[14] = rand[8];
+    bytes[15] = rand[9];
+    const hex = toHex(bytes);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@jmtrin/kevin-core",
+  "version": "1.3.0",
+  "description": "Kevin core — host-agnostic deterministic brain (Bedrock)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ./scripts/copy-migrations.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}