@rohirik/openltm-core 2.8.0

package/src/janitor/providers/types.ts

@@ -0,0 +1,154 @@
+/**
+ * types.ts — Provider interfaces for the janitor system.
+ * Supports embedding generation (for semantic search/dedup)
+ * and LLM calls (for smart promote/dedup decisions).
+ */
+
+/** A single embedding vector — float32 array stored as BLOB in SQLite. */
+export type EmbeddingVector = Float32Array;
+
+/** Input for batch embedding generation. */
+export interface EmbedInput {
+  /** Text strings to embed. */
+  texts: string[];
+}
+
+/** Result from embedding generation. */
+export interface EmbedResult {
+  /** Embedding vectors, one per input text. Same order as input. */
+  vectors: EmbeddingVector[];
+  /** Model used for generation. */
+  model: string;
+  /** Dimensionality of each vector. */
+  dimensions: number;
+  /** Total tokens consumed (for cost tracking). */
+  totalTokens: number;
+}
+
+/** Embedding provider — generates vector representations of text. */
+export interface EmbeddingProvider {
+  /** Provider name for display/logging. */
+  readonly name: string;
+  /** Generate embeddings for a batch of texts. */
+  embed(input: EmbedInput): Promise<EmbedResult>;
+  /** Verify the provider is configured and reachable. */
+  verify(): Promise<{ ok: boolean; error?: string }>;
+}
+
+/** A single chat message for LLM calls. */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+/** Input for LLM chat completion. */
+export interface ChatInput {
+  messages: ChatMessage[];
+  /** Max tokens to generate. */
+  maxTokens?: number;
+  /** Temperature (0.0 = deterministic, 1.0 = creative). */
+  temperature?: number;
+  /** If true, expect JSON output. */
+  jsonMode?: boolean;
+}
+
+/** Result from LLM chat completion. */
+export interface ChatResult {
+  content: string;
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+}
+
+/** LLM provider — used for smart dedup/promote decisions. */
+export interface LLMProvider {
+  readonly name: string;
+  chat(input: ChatInput): Promise<ChatResult>;
+  verify(): Promise<{ ok: boolean; error?: string }>;
+}
+
+/** Settings keys used by the janitor for provider configuration. */
+export const SETTING_KEYS = {
+  /** Embedding provider */
+  EMBED_PROVIDER: "ltm.embed.provider",
+  /** LLM provider for smart decisions */
+  LLM_PROVIDER: "ltm.llm.provider",
+  // Gemini
+  GEMINI_API_KEY: "ltm.gemini.apiKey",
+  GEMINI_EMBED_MODEL: "ltm.gemini.embedModel",
+  GEMINI_LLM_MODEL: "ltm.gemini.llmModel",
+  // OpenRouter
+  OPENROUTER_API_KEY: "ltm.openrouter.apiKey",
+  OPENROUTER_EMBED_MODEL: "ltm.openrouter.embedModel",
+  OPENROUTER_LLM_MODEL: "ltm.openrouter.llmModel",
+  // Ollama
+  OLLAMA_BASE_URL: "ltm.ollama.baseUrl",
+  OLLAMA_EMBED_MODEL: "ltm.ollama.embedModel",
+  OLLAMA_LLM_MODEL: "ltm.ollama.llmModel",
+  // OpenAI
+  OPENAI_API_KEY: "ltm.openai.apiKey",
+  OPENAI_EMBED_MODEL: "ltm.openai.embedModel",
+  OPENAI_LLM_MODEL: "ltm.openai.llmModel",
+  // Anthropic (LLM only)
+  ANTHROPIC_API_KEY: "ltm.anthropic.apiKey",
+  ANTHROPIC_LLM_MODEL: "ltm.anthropic.llmModel",
+  // Cohere
+  COHERE_API_KEY: "ltm.cohere.apiKey",
+  COHERE_EMBED_MODEL: "ltm.cohere.embedModel",
+  COHERE_LLM_MODEL: "ltm.cohere.llmModel",
+  // Decay
+  DECAY_GRACE_DAYS: "ltm.decay.graceDays",
+  DECAY_RATE: "ltm.decay.rate",
+  DECAY_MIN_CONFIDENCE: "ltm.decay.minConfidence",
+  // Promote & Janitor
+  PROMOTE_MIN_IMPORTANCE: "ltm.promote.minImportance",
+  JANITOR_INTERVAL_MINUTES: "ltm.janitor.intervalMinutes",
+  // Janitor run tracking (Phase 4)
+  JANITOR_LAST_RUN_AT:          "ltm.janitor.lastRunAt",
+  JANITOR_LAST_DECAY_REFRESHED: "ltm.janitor.lastDecayRefreshed",
+  JANITOR_LAST_DEPRECATED:      "ltm.janitor.lastDeprecated",
+  JANITOR_LAST_ARCHIVED:        "ltm.janitor.lastArchived",
+  // Cross-process sync (Phase 8 X1) — opt-in, requires Honker pub/sub
+  CROSS_PROCESS_SYNC: "ltm.crossProcessSync",
+} as const;
+
+/** Default values for all settings. */
+export const SETTING_DEFAULTS: Record<string, string> = {
+  [SETTING_KEYS.EMBED_PROVIDER]: "gemini",
+  [SETTING_KEYS.LLM_PROVIDER]: "gemini",
+  [SETTING_KEYS.GEMINI_API_KEY]: "",
+  [SETTING_KEYS.GEMINI_EMBED_MODEL]: "text-embedding-004",
+  [SETTING_KEYS.GEMINI_LLM_MODEL]: "gemini-2.0-flash",
+  [SETTING_KEYS.OPENROUTER_API_KEY]: "",
+  [SETTING_KEYS.OPENROUTER_EMBED_MODEL]: "openai/text-embedding-3-small",
+  [SETTING_KEYS.OPENROUTER_LLM_MODEL]: "google/gemini-2.0-flash-001",
+  [SETTING_KEYS.OLLAMA_BASE_URL]: "http://localhost:11434",
+  [SETTING_KEYS.OLLAMA_EMBED_MODEL]: "nomic-embed-text",
+  [SETTING_KEYS.OLLAMA_LLM_MODEL]: "llama3.2",
+  [SETTING_KEYS.OPENAI_API_KEY]: "",
+  [SETTING_KEYS.OPENAI_EMBED_MODEL]: "text-embedding-3-small",
+  [SETTING_KEYS.OPENAI_LLM_MODEL]: "gpt-4o-mini",
+  [SETTING_KEYS.ANTHROPIC_API_KEY]: "",
+  [SETTING_KEYS.ANTHROPIC_LLM_MODEL]: "claude-haiku-4-5-20251001",
+  [SETTING_KEYS.COHERE_API_KEY]: "",
+  [SETTING_KEYS.COHERE_EMBED_MODEL]: "embed-v4.0",
+  [SETTING_KEYS.COHERE_LLM_MODEL]: "command-r-plus",
+  [SETTING_KEYS.DECAY_GRACE_DAYS]: "30",
+  [SETTING_KEYS.DECAY_RATE]: "0.02",
+  [SETTING_KEYS.DECAY_MIN_CONFIDENCE]: "0.2",
+  [SETTING_KEYS.PROMOTE_MIN_IMPORTANCE]: "3",
+  [SETTING_KEYS.JANITOR_INTERVAL_MINUTES]: "0",
+  [SETTING_KEYS.JANITOR_LAST_RUN_AT]:          "",
+  [SETTING_KEYS.JANITOR_LAST_DECAY_REFRESHED]: "0",
+  [SETTING_KEYS.JANITOR_LAST_DEPRECATED]:      "0",
+  [SETTING_KEYS.JANITOR_LAST_ARCHIVED]:        "0",
+  [SETTING_KEYS.CROSS_PROCESS_SYNC]: "off",
+};
+
+/** Provider type identifiers. */
+export type ProviderType = "gemini" | "openrouter" | "ollama" | "openai" | "anthropic" | "cohere";
+
+/** Get a default setting value, guaranteed non-undefined. */
+export function getDefault(key: string): string {
+  return SETTING_DEFAULTS[key] ?? "";
+}

package/src/janitor/providers/utils.ts

@@ -0,0 +1,35 @@
+/**
+ * utils.ts — Shared helpers for all janitor providers.
+ * Eliminates copy-paste of getApiKey / getModel patterns.
+ */
+import { getSetting } from "../../shared-db.js";
+import { getDefault } from "./types.js";
+
+/** Create a getter for an API key setting, with env-var fallback and missing-key error. */
+export function makeApiKeyGetter(
+  settingKey: string,
+  envVar: string,
+  providerName: string,
+): () => string {
+  return () => {
+    const key = getSetting(settingKey) || process.env[envVar] || "";
+    if (!key)
+      throw new Error(
+        `${providerName} API key not configured. Set it in Settings or ${envVar} env var.`,
+      );
+    return key;
+  };
+}
+
+/** Create a getter for a model setting, with defaults fallback. */
+export function makeModelGetter(settingKey: string): () => string {
+  return () => getSetting(settingKey) || getDefault(settingKey);
+}
+
+/** Build the standard `{ ok: false, error }` result for a failed HTTP response. */
+export async function httpErrorResult(
+  res: Response,
+): Promise<{ ok: false; error: string }> {
+  const body = await res.text();
+  return { ok: false, error: `${res.status}: ${body}` };
+}

package/src/janitor/supersedes.ts

@@ -0,0 +1,199 @@
+/**
+ * supersedes.ts — Manage supersedes relations between memories.
+ * When a new memory supersedes an old one, the old memory is marked
+ * as 'superseded' and a directed relation is created.
+ */
+import { getDb } from "../shared-db.js";
+
+/**
+ * Mark a memory as superseding another.
+ * - Creates a 'supersedes' relation from newId -> oldId
+ * - Sets the old memory's status to 'superseded'
+ * - Optionally transfers tags from old to new
+ */
+export function supersede(
+  newId: number,
+  oldId: number,
+  transferTags = true,
+): void {
+  const db = getDb();
+
+  const newMem = db.query("SELECT id, status FROM memories WHERE id = ?").get(newId) as { id: number; status: string } | undefined;
+  const oldMem = db.query("SELECT id, status FROM memories WHERE id = ?").get(oldId) as { id: number; status: string } | undefined;
+
+  if (!newMem) throw new Error(`New memory ${newId} not found`);
+  if (!oldMem) throw new Error(`Old memory ${oldId} not found`);
+  if (newId === oldId) throw new Error("Cannot supersede self");
+
+  db.transaction(() => {
+    db.run(
+      `INSERT OR IGNORE INTO memory_relations (source_memory_id, target_memory_id, relationship_type)
+       VALUES (?, ?, 'supersedes')`,
+      [newId, oldId],
+    );
+    db.run("UPDATE memories SET status = 'superseded' WHERE id = ?", [oldId]);
+    if (transferTags) {
+      db.run(
+        `INSERT OR IGNORE INTO memory_tags (memory_id, tag_id)
+         SELECT ?, tag_id FROM memory_tags WHERE memory_id = ?`,
+        [newId, oldId],
+      );
+    }
+    db.run("UPDATE context_items SET memory_id = ? WHERE memory_id = ?", [newId, oldId]);
+  })();
+}
+
+export function getSupersededChain(
+  memoryId: number,
+): Array<{ id: number; content: string; created_at: string }> {
+  const db = getDb();
+  const chain: Array<{ id: number; content: string; created_at: string }> = [];
+  const visited = new Set<number>();
+  const queue = [memoryId];
+
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    if (visited.has(currentId)) continue;
+    visited.add(currentId);
+
+    const superseded = db.query(
+      `SELECT m.id, m.content, m.created_at
+       FROM memories m
+       JOIN memory_relations r ON r.target_memory_id = m.id
+       WHERE r.source_memory_id = ? AND r.relationship_type = 'supersedes'`
+    ).all(currentId) as typeof chain;
+
+    for (const s of superseded) {
+      chain.push(s);
+      queue.push(s.id);
+    }
+  }
+
+  return chain;
+}
+
+export function getSupersededBy(
+  memoryId: number,
+): { id: number; content: string } | null {
+  const db = getDb();
+  return db.query(
+    `SELECT m.id, m.content
+     FROM memories m
+     JOIN memory_relations r ON r.source_memory_id = m.id
+     WHERE r.target_memory_id = ? AND r.relationship_type = 'supersedes'
+     LIMIT 1`
+  ).get(memoryId)  as { id: number; content: string } | null ?? null;
+}
+
+export function unsupersede(newId: number, oldId: number): void {
+  const db = getDb();
+
+  db.transaction(() => {
+    db.run(
+      `DELETE FROM memory_relations
+       WHERE source_memory_id = ? AND target_memory_id = ? AND relationship_type = 'supersedes'`,
+      [newId, oldId],
+    );
+
+    const stillSuperseded = db.query(
+      `SELECT COUNT(*) as cnt FROM memory_relations
+       WHERE target_memory_id = ? AND relationship_type = 'supersedes'`
+    ).get(oldId) as { cnt: number } | undefined;
+
+    if ((stillSuperseded?.cnt ?? 0) === 0) {
+      db.run("UPDATE memories SET status = 'active' WHERE id = ? AND status = 'superseded'", [oldId]);
+    }
+  })();
+}
+
+// ============================================================
+// Contradiction detection
+// ============================================================
+
+export interface Contradiction {
+  olderId: number;
+  olderContent: string;
+  newerId: number;
+  newerContent: string;
+  term: string;
+}
+
+const CONTRADICTION_PAIRS = [
+  ["npm", "bun"],
+  ["yarn", "bun"],
+  ["npm", "pnpm"],
+  ["rest", "graphql"],
+  ["sql", "nosql"],
+  ["mysql", "postgres"],
+  ["javascript", "typescript"],
+  ["js", "ts"],
+  ["class", "functional"],
+  ["oop", "functional"],
+];
+
+export function detectContradictions(
+  projectScope: string | null,
+): Contradiction[] {
+  const db = getDb();
+  const contradictions: Contradiction[] = [];
+
+  let memories: Array<{ id: number; content: string; category: string; created_at: string }>;
+  if (projectScope) {
+    memories = db.query(
+      `SELECT id, content, category, created_at FROM memories WHERE project_scope = ? AND status = 'active'`
+    ).all(projectScope) as typeof memories;
+  } else {
+    memories = db.query(
+      `SELECT id, content, category, created_at FROM memories WHERE project_scope IS NULL AND status = 'active'`
+    ).all() as typeof memories;
+  }
+
+  for (const mem of memories) {
+    const content = mem.content.toLowerCase();
+
+    for (const [term1, term2] of CONTRADICTION_PAIRS) {
+      if (content.includes(term1)) {
+        const opposite = memories.filter(
+          m => m.id !== mem.id &&
+            m.content.toLowerCase().includes(term2) &&
+            m.category === mem.category,
+        );
+
+        for (const opp of opposite) {
+          if (new Date(opp.created_at) > new Date(mem.created_at)) {
+            contradictions.push({
+              olderId: mem.id,
+              olderContent: mem.content,
+              newerId: opp.id,
+              newerContent: opp.content,
+              term: `${term1} vs ${term2}`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return contradictions;
+}
+
+export function applyContradictions(contradictions: Contradiction[]): number {
+  const db = getDb();
+  let applied = 0;
+
+  for (const con of contradictions) {
+    const existing = db.query(
+      `SELECT id FROM memories WHERE id = ? AND superseded_by IS NOT NULL`
+    ).get(con.olderId) as { id: number } | null;
+
+    if (existing) continue;
+
+    db.run(
+      `UPDATE memories SET superseded_by = ?, superseded_at = datetime('now') WHERE id = ?`,
+      [con.newerId, con.olderId],
+    );
+    applied++;
+  }
+
+  return applied;
+}

package/src/lib/honker.ts

@@ -0,0 +1,54 @@
+/**
+ * lib/honker.ts — process-wide lazy handle to the Honker runtime.
+ *
+ * Honker (durable queues, pub/sub, scheduler) is an OPTIONAL loadable SQLite
+ * extension. honker-bun's `open()` manages its OWN connection + update watcher
+ * over the same openltm.db file, so queue/events/scheduler share a single handle
+ * created here. Everything degrades to null when:
+ *   - the capability probe reports honker unavailable (getCapabilities().honker)
+ *   - LTM_HONKER_EXT is unset / the binary is missing
+ *   - the honker-bun package isn't installed, or open() throws
+ *
+ * NOTHING here throws — callers branch on a null handle and fall back to the
+ * pre-Honker behaviour (inline embed, HTTP poll, file-watcher).
+ */
+import type { HonkerDb, HonkerModule } from "./honkerTypes.js";
+import { getCapabilities, locateSystemSqlite } from "../extensions.js";
+import { DB_PATH } from "../shared-db.js";
+
+let _handle: HonkerDb | null | undefined = undefined;
+
+/**
+ * Return the shared Honker handle, opening it once on first use. Returns null
+ * (cached) whenever Honker is unavailable. Synchronous — honker-bun's open() is
+ * synchronous and we require the package lazily so an absent install is a no-op.
+ */
+export function getHonker(): HonkerDb | null {
+  if (_handle !== undefined) return _handle;
+  _handle = openHonker();
+  return _handle;
+}
+
+function openHonker(): HonkerDb | null {
+  if (!getCapabilities().honker) return null;
+  const ext = process.env["LTM_HONKER_EXT"];
+  if (!ext) return null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require("@russellthehippo/honker-bun") as HonkerModule;
+    const lib = locateSystemSqlite();
+    return mod.open(DB_PATH, ext, lib ? { sqliteLibPath: lib } : {});
+  } catch {
+    return null;
+  }
+}
+
+/** True when a live Honker handle is available. */
+export function isHonkerAvailable(): boolean {
+  return getHonker() !== null;
+}
+
+/** Test-only: drop the cached handle (does not close it). */
+export function _resetHonkerForTesting(): void {
+  _handle = undefined;
+}

package/src/lib/honkerTypes.ts

@@ -0,0 +1,109 @@
+/**
+ * honkerTypes.ts — minimal structural types for the Honker runtime surface we
+ * use. We deliberately do NOT `import` from @russellthehippo/honker-bun: it
+ * ships raw .ts with internal type errors that tsc would compile (skipLibCheck
+ * only skips .d.ts), and it is an OPTIONAL dependency that may be absent in
+ * consumer installs. These local types keep the build self-contained and let
+ * every Honker call site stay strongly typed against the verified API.
+ */
+
+export interface HonkerEnqueueOptions {
+  delay?: number;
+  runAt?: number;
+  priority?: number;
+  expires?: number;
+  tx?: HonkerTransaction;
+}
+
+export interface HonkerQueueOptions {
+  visibilityTimeoutS?: number;
+  maxAttempts?: number;
+}
+
+export interface HonkerJob {
+  readonly id: number;
+  readonly queue: string;
+  readonly payload: unknown;
+  readonly workerId: string;
+  readonly attempts: number;
+  ack(): boolean;
+  retry(delaySec: number, errorMsg: string): boolean;
+  fail(errorMsg: string): boolean;
+  heartbeat(extendSec: number): boolean;
+}
+
+export interface HonkerClaimWaker {
+  tryNext(workerId: string): HonkerJob | null;
+  next(workerId: string, opts?: { signal?: AbortSignal }): Promise<HonkerJob | null>;
+  close(): void;
+}
+
+export interface HonkerQueue {
+  readonly name: string;
+  enqueue(payload: unknown, opts?: HonkerEnqueueOptions): number;
+  claimBatch(workerId: string, n: number): HonkerJob[];
+  claimOne(workerId: string): HonkerJob | null;
+  ackBatch(ids: number[], workerId: string): number;
+  sweepExpired(): number;
+  nextClaimAt(): number | null;
+  claimWaker(opts?: { idlePollS?: number | null; pollMs?: number | null }): HonkerClaimWaker;
+}
+
+export interface HonkerTransaction {
+  readonly raw: unknown;
+  commit(): void;
+  rollback(): void;
+}
+
+export interface HonkerScheduledTask {
+  name: string;
+  queue: string;
+  schedule?: string;
+  cron?: string;
+  payload: unknown;
+  priority?: number;
+  expiresS?: number | null;
+}
+
+export interface HonkerScheduledFire {
+  name: string;
+  queue: string;
+  fire_at: number;
+  job_id: number;
+}
+
+export interface HonkerScheduler {
+  add(task: HonkerScheduledTask): void;
+  remove(name: string): number;
+  tick(): HonkerScheduledFire[];
+  soonest(): number;
+  /** Leader-elected blocking loop — only the lock holder ticks. */
+  run(opts: { owner: string; signal: AbortSignal }): Promise<void>;
+}
+
+export interface HonkerNotification {
+  id: number;
+  channel: string;
+  payload: unknown;
+}
+
+export interface HonkerDb {
+  readonly raw: unknown;
+  queue(name: string, opts?: HonkerQueueOptions): HonkerQueue;
+  scheduler(): HonkerScheduler;
+  notify(channel: string, payload: unknown, opts?: { tx?: HonkerTransaction }): number;
+  listen(
+    channel: string,
+    opts?: { signal?: AbortSignal; pollMs?: number },
+  ): AsyncIterableIterator<HonkerNotification>;
+  transaction(): HonkerTransaction;
+  close(): void;
+}
+
+export interface HonkerModule {
+  open(
+    path: string,
+    extensionPath: string,
+    opts?: { sqliteLibPath?: string; watcherBackend?: string | null },
+  ): HonkerDb;
+}

package/src/lib/jsonlLogger.ts

@@ -0,0 +1,92 @@
+/**
+ * jsonlLogger.ts — Structured JSONL event log for the LTM plugin.
+ *
+ * Write path: ${CLAUDE_PLUGIN_DATA}/logs/ltm.jsonl
+ * Rotation: 10MB → keep last 7MB (byte-slice, no rename needed).
+ *
+ * Supplements hookLogger.ts — does NOT replace it.
+ * Never throws — all errors are silently swallowed to protect hook execution.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+
+export interface LtmEvent {
+  ts: string;
+  hook: string;
+  event: string;
+  project?: string;
+  count?: number;
+  durationMs?: number;
+  detail?: string;
+  level?: "info" | "warn" | "error";
+}
+
+const MAX_BYTES  = 10 * 1024 * 1024;  // 10 MB
+const KEEP_BYTES =  7 * 1024 * 1024;  //  7 MB kept after rotation
+const ROTATE_INTERVAL_MS = 60_000;     // at most one rotation check per minute
+
+let _logPath: string | null = null;
+let _dirEnsured = false;
+let _lastRotateCheck = 0;
+
+export function getLogPath(): string {
+  if (_logPath) return _logPath;
+  const base = process.env.CLAUDE_PLUGIN_DATA
+    ?? join(homedir(), ".claude", "plugins", "data", "OpenLtm-openltm");
+  _logPath = join(base, "logs", "ltm.jsonl");
+  return _logPath;
+}
+
+function ensureDir(logPath: string): void {
+  if (_dirEnsured) return;
+  mkdirSync(dirname(logPath), { recursive: true });
+  _dirEnsured = true;
+}
+
+function maybeRotate(logPath: string): void {
+  const now = Date.now();
+  if (now - _lastRotateCheck < ROTATE_INTERVAL_MS) return;
+  _lastRotateCheck = now;
+  try {
+    if (!existsSync(logPath)) return;
+    const size = statSync(logPath).size;
+    if (size <= MAX_BYTES) return;
+    // Slice the tail — keep the most recent KEEP_BYTES
+    const content = readFileSync(logPath);
+    writeFileSync(logPath, content.slice(content.length - KEEP_BYTES));
+  } catch { /* rotation failure is non-fatal */ }
+}
+
+export function emitEvent(event: LtmEvent): void {
+  try {
+    const logPath = getLogPath();
+    ensureDir(logPath);
+    maybeRotate(logPath);
+    const entry: LtmEvent = { ...event, ts: event.ts ?? new Date().toISOString() };
+    appendFileSync(logPath, JSON.stringify(entry) + "\n");
+  } catch { /* never throw from logger */ }
+}
+
+export function readRecentEvents(limit: number): LtmEvent[] {
+  try {
+    const logPath = getLogPath();
+    if (!existsSync(logPath)) return [];
+    const lines = readFileSync(logPath, "utf-8").trim().split("\n").filter(Boolean);
+    const tail = lines.slice(-Math.max(limit, 0));
+    const events: LtmEvent[] = [];
+    for (const line of tail) {
+      try { events.push(JSON.parse(line) as LtmEvent); } catch { /* skip malformed lines */ }
+    }
+    return events;
+  } catch {
+    return [];
+  }
+}
+
+/** Reset cached state — test-only. */
+export function _resetForTesting(): void {
+  _logPath = null;
+  _dirEnsured = false;
+  _lastRotateCheck = 0;
+}

package/src/lib/writeQueue.ts

@@ -0,0 +1,28 @@
+/**
+ * writeQueue.ts — Serialises all DB writes through a promise-chain queue.
+ * Prevents concurrent write corruption (W12).
+ */
+import type { Database } from "bun:sqlite";
+
+export class WriteQueue {
+  private tail: Promise<unknown> = Promise.resolve();
+
+  enqueue<T>(fn: () => T | Promise<T>, db?: Database): Promise<T> {
+    const next = this.tail.then(async () => {
+      if (!db) return fn();
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const result = await Promise.resolve(fn());
+        db.exec("COMMIT");
+        return result;
+      } catch (err) {
+        try { db.exec("ROLLBACK"); } catch {}
+        throw err;
+      }
+    });
+    this.tail = next.catch(() => {}); // prevent unhandled rejection on queue
+    return next as Promise<T>;
+  }
+}
+
+export const writeQueue = new WriteQueue();