@rohirik/openltm-core 2.11.0 → 2.12.2

package/README.md

@@ -22,6 +22,7 @@ idempotent — safe to run multiple times.
 
 - Adds the `ltm` MCP server entry (`bunx @rohirik/openltm-core mcp-serve`)
 - Wires three lifecycle hooks: `SessionStart`, `PreCompact`, `PostEditCheck`
+- `SessionStart` now emits a portable Prior Knowledge prefill directly from `openltm-core`; the other two are safe no-ops unless the full Claude plugin checkout is installed
 
 ### OpenCode (`opencode.json`)
 
@@ -54,6 +55,8 @@ config directories.
 
 ## Programmatic API
 
+Installers are registry-driven under `INSTALL_TARGETS`, so adding a new host now means defining one target entry (detect + install) instead of editing the CLI orchestrator in multiple places.
+
 ```typescript
 import { installClaude, installOpenCode, installPi, detectAgents } from "@rohirik/openltm-core/cli";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.11.0",
+  "version": "2.12.2",
   "description": "Shared LTM storage engine — path-agnostic SQLite core used by Claude Code, OpenCode, and Pi adapters",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@clack/prompts": "^1.3.0",
     "@iarna/toml": "^2.2.5",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "bun-types": "^1.0.0",
     "sqlite-vec": "0.1.9",
     "zod": "^4.3.6"

package/src/__tests__/cli/hook.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+
+const dbPath = `/tmp/test-openltm-hook-${process.pid}-${Date.now()}.db`;
+const SCHEMA_PATH = join(import.meta.dir, "..", "..", "schema.sql");
+
+beforeAll(async () => {
+  const { runPendingMigrations, _setDbForTesting } = await import("../../index.js");
+  const db = new Database(dbPath, { create: true });
+  db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;");
+  db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  await runPendingMigrations(db);
+  _setDbForTesting(db);
+}, 30_000);
+
+afterAll(() => {
+  try { unlinkSync(dbPath); } catch {}
+  try { unlinkSync(`${dbPath}-shm`); } catch {}
+  try { unlinkSync(`${dbPath}-wal`); } catch {}
+});
+
+describe("cli hook dispatcher", () => {
+  it("builds a SessionStart prefill block from hook stdin JSON", async () => {
+    const { learn } = await import("../../index.js");
+    const { buildHookOutput } = await import("../../cli/hook.js");
+
+    learn({
+      content: "SessionStart should restore this memory",
+      category: "pattern",
+      importance: 3,
+      project_scope: "hook-project",
+      skipExport: true,
+    });
+
+    const output = await buildHookOutput("SessionStart", JSON.stringify({ cwd: "/tmp/hook-project" }));
+    expect(output).toContain("Prior Knowledge");
+    expect(output).toContain("restore this memory");
+  });
+
+  it("keeps non-SessionStart hook events as safe no-ops", async () => {
+    const { buildHookOutput } = await import("../../cli/hook.js");
+    expect(await buildHookOutput("PreCompact", JSON.stringify({ cwd: "/tmp/hook-project" }))).toBe("");
+    expect(await buildHookOutput("PostEditCheck", JSON.stringify({ cwd: "/tmp/hook-project" }))).toBe("");
+  });
+});

package/src/__tests__/prefill.test.ts

@@ -0,0 +1,56 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+
+const dbPath = `/tmp/test-openltm-prefill-${process.pid}-${Date.now()}.db`;
+const SCHEMA_PATH = join(import.meta.dir, "..", "schema.sql");
+
+beforeAll(async () => {
+  const { runPendingMigrations, _setDbForTesting } = await import("../index.js");
+  const db = new Database(dbPath, { create: true });
+  db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;");
+  db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  await runPendingMigrations(db);
+  _setDbForTesting(db);
+}, 30_000);
+
+afterAll(() => {
+  try { unlinkSync(dbPath); } catch {}
+  try { unlinkSync(`${dbPath}-shm`); } catch {}
+  try { unlinkSync(`${dbPath}-wal`); } catch {}
+});
+
+describe("prefill helpers", () => {
+  it("returns empty output when no memories exist", async () => {
+    const { buildPrefillContext } = await import("../index.js");
+    expect(buildPrefillContext({ project: "empty-prefill-project", maxMemories: 4 })).toBe("");
+  });
+
+  it("builds a compact shared prefill block from globals + project memories", async () => {
+    const { buildPrefillContext, deriveProjectFromCwd, learn } = await import("../index.js");
+
+    learn({
+      content: "Global guardrail — prefer Bun commands in this repo",
+      category: "workflow",
+      importance: 4,
+      skipExport: true,
+    });
+    learn({
+      content: "Project decision — adapter hooks should use the shared prefill builder",
+      category: "architecture",
+      importance: 3,
+      project_scope: "prefill-project",
+      skipExport: true,
+    });
+
+    expect(deriveProjectFromCwd("/tmp/prefill-project")).toBe("prefill-project");
+
+    const block = buildPrefillContext({ project: "prefill-project", maxMemories: 6, maxLines: 18 });
+    expect(block).toContain("## Prior Knowledge (LTM)");
+    expect(block).toContain("Global:");
+    expect(block).toContain("Project (prefill-project):");
+    expect(block).toContain("prefer Bun commands");
+    expect(block).toContain("shared prefill builder");
+  });
+});

package/src/cli/bin.ts

@@ -9,8 +9,8 @@
  *   bunx @rohirik/openltm-core --pi               # Pi only
  *   bunx @rohirik/openltm-core --dry-run --claude # preview without writing
  *
- *   bunx @rohirik/openltm-core hook --name <hookName>  # lifecycle hook stub
- *   bunx @rohirik/openltm-core mcp-serve               # MCP server (future)
+ *   bunx @rohirik/openltm-core hook --name <hookName>  # lifecycle hook entrypoint
+ *   bunx @rohirik/openltm-core mcp-serve               # MCP server
  */
 import { runInstallCli } from "./install.js";
 import { runHook } from "./hook.js";
@@ -32,7 +32,7 @@ function printHelp(): void {
       "  Sub-commands:",
       "    memory <cmd>          Read/write memories from the shell (learn, recall,",
       "                          forget, relate, context) — run 'memory --help'",
-      "    hook --name <event>   Lifecycle hook stub (for Claude Code hook wiring)",
+      "    hook --name <event>   Lifecycle hook entrypoint (SessionStart prefill + safe no-ops)",
       "    mcp-serve             Start the LTM MCP server (stdio)",
       "",
       "  If no target flags are given, agents are auto-detected.",
@@ -63,7 +63,7 @@ async function main(): Promise<void> {
       process.stderr.write("  ltm hook: missing --name argument\n");
       process.exit(1);
     }
-    runHook(hookName);
+    await runHook(hookName);
     return;
   }
 

package/src/cli/detect.ts

@@ -7,37 +7,9 @@
  *
  * Pure function — accepts a homedir argument so tests can supply a tmp dir.
  */
-import { existsSync } from "fs";
-import { join } from "path";
 import os from "os";
 import type { DetectResult } from "./types.js";
-
-/**
- * Probe for an OpenCode config directory using the standard path resolution
- * order: $XDG_CONFIG_HOME/opencode → ~/.config/opencode → (darwin only)
- * ~/Library/Application Support/opencode.
- */
-function probeOpenCode(homedir: string): boolean {
-  const xdg = process.env["XDG_CONFIG_HOME"];
-  if (xdg && existsSync(join(xdg, "opencode"))) return true;
-  if (existsSync(join(homedir, ".config", "opencode"))) return true;
-  if (process.platform === "darwin") {
-    if (existsSync(join(homedir, "Library", "Application Support", "opencode"))) return true;
-  }
-  return false;
-}
-
-/**
- * Probe for a Pi config using the three known locations:
- * ~/.pi/ | ~/pi.toml | ~/.pi/config.toml
- */
-function probePi(homedir: string): boolean {
-  return (
-    existsSync(join(homedir, ".pi")) ||
-    existsSync(join(homedir, "pi.toml")) ||
-    existsSync(join(homedir, ".pi", "config.toml"))
-  );
-}
+import { INSTALL_TARGETS } from "./targets.js";
 
 /**
  * detectAgents — inspect the filesystem to determine which AI coding agents
@@ -47,9 +19,8 @@ function probePi(homedir: string): boolean {
  * @returns DetectResult with boolean flags for each supported agent.
  */
 export function detectAgents(homedir: string = os.homedir()): DetectResult {
-  return {
-    claude: existsSync(join(homedir, ".claude")),
-    opencode: probeOpenCode(homedir),
-    pi: probePi(homedir),
-  };
+  return INSTALL_TARGETS.reduce<DetectResult>((acc, target) => {
+    acc[target.id] = target.detect(homedir);
+    return acc;
+  }, { claude: false, opencode: false, pi: false });
 }

package/src/cli/hook.ts

@@ -1,25 +1,63 @@
 /**
- * cli/hook.ts — Hook dispatcher stub.
+ * cli/hook.ts — Lightweight Claude-compatible hook dispatcher.
  *
- * Full hook logic lives in the Claude Code plugin (hooks/src/).
- * When invoked via `bunx @rohirik/openltm-core hook --name <hookName>`, this
- * stub exits cleanly (exit 0) so Claude Code does not treat the absent hook
- * runner as an error.
- *
- * A future phase can wire actual hook logic here once openltm-core ships the
- * compiled hook handlers.
+ * For bunx installs we support a portable SessionStart prefill directly from
+ * openltm-core so users still get an "already pre-filled" experience without
+ * the full Claude plugin checkout. Other hook events are safe no-ops.
  */
+import { buildPrefillContext, deriveProjectFromCwd } from "../prefill.js";
+
+function parseHookCwd(raw: string): string {
+  if (!raw.trim()) return "";
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const cwd = parsed["cwd"]
+      ?? parsed["working_directory"]
+      ?? (parsed["session"] as Record<string, unknown> | undefined)?.["cwd"];
+    return typeof cwd === "string" ? cwd : "";
+  } catch {
+    return "";
+  }
+}
+
+export async function buildHookOutput(name: string, rawInput: string): Promise<string> {
+  switch (name) {
+    case "SessionStart": {
+      const cwd = parseHookCwd(rawInput);
+      if (!cwd) return "";
+      const project = deriveProjectFromCwd(cwd);
+      if (!project) return "";
+      return buildPrefillContext({ project, maxMemories: 10, maxLines: 18 });
+    }
+    case "PreCompact":
+    case "PostEditCheck":
+      return "";
+    default:
+      return "";
+  }
+}
+
+async function readStdin(): Promise<string> {
+  let result = "";
+  try {
+    for await (const chunk of Bun.stdin.stream()) {
+      result += new TextDecoder().decode(chunk);
+    }
+  } catch {
+    // stdin may be absent in some hook invocations
+  }
+  return result;
+}
 
 /**
- * runHook — stub dispatcher for LTM lifecycle hooks.
+ * runHook — dispatch a lifecycle hook.
  *
- * @param name - Hook event name (e.g. "SessionStart", "PreCompact").
+ * SessionStart emits a compact Prior Knowledge block when memories exist.
+ * Other events intentionally no-op until a richer host-independent contract is
+ * extracted from the full Claude plugin hook suite.
  */
-export function runHook(name: string): void {
-  // Stub: full hook logic requires the Claude Code plugin.
-  // Exit 0 so Claude Code does not break when the hook is registered.
-  process.stderr.write(
-    `LTM: hook '${name}' via bunx not yet supported — install the Claude Code plugin for full hook support\n`,
-  );
-  process.exit(0);
+export async function runHook(name: string): Promise<void> {
+  const raw = await readStdin();
+  const output = await buildHookOutput(name, raw);
+  if (output) process.stdout.write(output);
 }

package/src/cli/index.ts

@@ -20,3 +20,5 @@ export { detectAgents } from "./detect.js";
 export { installClaude } from "./claude.js";
 export { installOpenCode } from "./opencode.js";
 export { installPi } from "./pi.js";
+export { INSTALL_TARGETS, getInstallTarget } from "./targets.js";
+export type { InstallTargetDefinition } from "./targets.js";

package/src/cli/install.ts

@@ -11,11 +11,9 @@
  */
 import * as clack from "@clack/prompts";
 import { detectAgents } from "./detect.js";
-import { installClaude } from "./claude.js";
-import { installOpenCode } from "./opencode.js";
-import { installPi } from "./pi.js";
 import type { CliInstallOptions, CliInstallResult, InstallStep, InstallResult } from "./types.js";
 import { InstallTarget } from "./types.js";
+import { INSTALL_TARGETS } from "./targets.js";
 
 // ── Known targets set (legacy validation) ────────────────────────────────────
 
@@ -124,53 +122,19 @@ export async function runInstallCli(opts: CliRunOpts): Promise<CliRunResult> {
 
   const results: InstallResult[] = [];
 
-  // Claude
-  if (targets.claude) {
+  for (const target of INSTALL_TARGETS) {
+    if (!targets[target.id]) continue;
     const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into Claude Code…");
-    const r = await installClaude({ homedir, dryRun });
+    if (s) s.start(`Installing into ${target.label}…`);
+    const r = await target.install({ homedir, dryRun });
     results.push(r);
     if (s) {
       if (r.status === "installed") {
-        s.stop(`Claude Code: installed${dryRun ? " (dry-run)" : ""}`);
+        s.stop(`${target.label}: installed${dryRun ? " (dry-run)" : ""}`);
       } else if (r.status === "skipped") {
-        s.stop("Claude Code: already configured (skipped)");
+        s.stop(`${target.label}: already configured (skipped)`);
       } else {
-        s.stop(`Claude Code: error — ${r.detail ?? "unknown error"}`);
-      }
-    }
-  }
-
-  // OpenCode
-  if (targets.opencode) {
-    const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into OpenCode…");
-    const r = await installOpenCode({ homedir, dryRun });
-    results.push(r);
-    if (s) {
-      if (r.status === "installed") {
-        s.stop(`OpenCode: installed${dryRun ? " (dry-run)" : ""}`);
-      } else if (r.status === "skipped") {
-        s.stop("OpenCode: already configured (skipped)");
-      } else {
-        s.stop(`OpenCode: error — ${r.detail ?? "unknown error"}`);
-      }
-    }
-  }
-
-  // Pi
-  if (targets.pi) {
-    const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into Pi…");
-    const r = await installPi({ dryRun });
-    results.push(r);
-    if (s) {
-      if (r.status === "installed") {
-        s.stop(`Pi: installed${dryRun ? " (dry-run)" : ""}`);
-      } else if (r.status === "skipped") {
-        s.stop("Pi: already configured (skipped)");
-      } else {
-        s.stop(`Pi: error — ${r.detail ?? "unknown error"}`);
+        s.stop(`${target.label}: error — ${r.detail ?? "unknown error"}`);
       }
     }
   }

package/src/cli/targets.ts

@@ -0,0 +1,62 @@
+import type { InstallResult } from "./types.js";
+import { installClaude } from "./claude.js";
+import { installOpenCode } from "./opencode.js";
+import { installPi } from "./pi.js";
+import { existsSync } from "fs";
+import { join } from "path";
+
+export interface InstallTargetDefinition {
+  id: "claude" | "opencode" | "pi";
+  label: string;
+  detect: (homedir: string) => boolean;
+  install: (opts: { homedir?: string; dryRun?: boolean }) => Promise<InstallResult>;
+}
+
+function detectClaude(homedir: string): boolean {
+  return existsSync(join(homedir, ".claude"));
+}
+
+function detectOpenCode(homedir: string): boolean {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg && existsSync(join(xdg, "opencode"))) return true;
+  if (existsSync(join(homedir, ".config", "opencode"))) return true;
+  if (process.platform === "darwin") {
+    if (existsSync(join(homedir, "Library", "Application Support", "opencode"))) return true;
+  }
+  return false;
+}
+
+function detectPi(homedir: string): boolean {
+  return (
+    existsSync(join(homedir, ".pi")) ||
+    existsSync(join(homedir, "pi.toml")) ||
+    existsSync(join(homedir, ".pi", "config.toml"))
+  );
+}
+
+export const INSTALL_TARGETS: readonly InstallTargetDefinition[] = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    detect: detectClaude,
+    install: ({ homedir, dryRun }) => installClaude({ homedir, dryRun }),
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    detect: detectOpenCode,
+    install: ({ homedir, dryRun }) => installOpenCode({ homedir, dryRun }),
+  },
+  {
+    id: "pi",
+    label: "Pi",
+    detect: detectPi,
+    install: ({ dryRun }) => installPi({ dryRun }),
+  },
+] as const;
+
+export function getInstallTarget(id: InstallTargetDefinition["id"]): InstallTargetDefinition {
+  const target = INSTALL_TARGETS.find((entry) => entry.id === id);
+  if (!target) throw new Error(`Unknown install target: ${id}`);
+  return target;
+}

package/src/index.ts

@@ -43,6 +43,10 @@ export { categorise } from "./recall/categorise.js";
 export { buildExplainer, computeTemperature } from "./recall/explainer.js";
 export type { MemoryTemperature, RecallExplainer, ExplainerInput } from "./recall/explainer.js";
 
+// Session prefill helpers
+export { buildPrefillContext, deriveProjectFromCwd, selectPrefillMemories } from "./prefill.js";
+export type { PrefillOptions, PrefillSelection } from "./prefill.js";
+
 // Embedding providers
 export * from "./providers/index.js";
 export { WriteQueue, writeQueue } from "./lib/writeQueue.js";

package/src/migrations.ts

@@ -210,6 +210,352 @@ export function parseMigration(content: string): ParsedMigration {
   return { up, down };
 }
 
+// ── R-2: fail-closed self-heal gate ─────────────────────────────────────────────
+// The old runPendingMigrations() catch treated any `duplicate column name` /
+// `already exists` error as proof the migration could be recorded. That is
+// unsound: db.exec(up) aborts at the FIRST failing statement, so the error only
+// proves the first colliding statement — nothing about later columns, tables,
+// indexes, or backfills. The recorder must never trust the error string; it must
+// independently prove the whole post-migration state against the live schema.
+
+function skipWs(s: string, pos: number): number {
+  while (pos < s.length && /\s/.test(s.charAt(pos))) pos++;
+  return pos;
+}
+
+/**
+ * Match a single SQL keyword at `pos` (whitespace before it is skipped),
+ * case-insensitively. Returns the position just past the keyword, or null if
+ * `kw` does not appear there as a whole word.
+ */
+function matchKeyword(s: string, pos: number, kw: string): number | null {
+  const p = skipWs(s, pos);
+  const raw = s.slice(p, p + kw.length);
+  if (raw.toUpperCase() !== kw) return null;
+  const after = p + kw.length;
+  if (after < s.length && /[A-Za-z0-9_]/.test(s.charAt(after))) return null;
+  return after;
+}
+
+/**
+ * If the text at `pos` begins `IF NOT EXISTS`, return the position just past
+ * it; otherwise return `pos` unchanged. Only the exact `IF NOT EXISTS` keyword
+ * sequence is recognised.
+ */
+function consumeIfNotExists(s: string, pos: number): number {
+  const ifEnd = matchKeyword(s, pos, "IF");
+  if (ifEnd === null) return pos;
+  const notEnd = matchKeyword(s, ifEnd, "NOT");
+  if (notEnd === null) return pos;
+  const existsEnd = matchKeyword(s, notEnd, "EXISTS");
+  return existsEnd === null ? pos : existsEnd;
+}
+
+/**
+ * Match a single SQL identifier starting at `pos`: a bare `[A-Za-z_][A-Za-z0-9_]*`
+ * name or one of the quoted forms `"..."`, `` `...` ``, `[...]`. Returns the
+ * unquoted name and the position just past the identifier, or null if none starts
+ * there.
+ */
+function matchIdent(s: string, pos: number): { name: string; end: number } | null {
+  if (pos >= s.length) return null;
+  const ch = s.charAt(pos);
+  if (ch === '"' || ch === "`") {
+    let i = pos + 1;
+    let name = "";
+    for (; i < s.length; i++) {
+      if (s.charAt(i) === ch) {
+        if (s.charAt(i + 1) === ch) {
+          name += ch;
+          i++;
+          continue;
+        }
+        return { name, end: i + 1 };
+      }
+      name += s.charAt(i);
+    }
+    return null; // unterminated quote
+  }
+  if (ch === "[") {
+    const end = s.indexOf("]", pos + 1);
+    if (end === -1) return null;
+    return { name: s.slice(pos + 1, end), end: end + 1 };
+  }
+  const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(s.slice(pos));
+  return m ? { name: m[0], end: pos + m[0].length } : null;
+}
+
+/**
+ * True when `tail` (the column-definition remainder of an `ALTER TABLE ... ADD
+ * COLUMN <col>` statement) contains nothing beyond a plain column definition.
+ * Rejects a top-level comma (SQLite multi-action ALTER) and any top-level
+ * DROP/RENAME keyword, so a statement such as `ALTER TABLE t ADD COLUMN a, DROP
+ * COLUMN b` can never slip through. Commas and keywords inside parentheses or
+ * string literals are allowed (CHECK constraints, functional defaults).
+ */
+function isColumnDefinitionTail(tail: string): boolean {
+  let depth = 0;
+  let quote: string | null = null;
+  for (let i = 0; i < tail.length; i++) {
+    const ch = tail.charAt(i);
+    if (quote !== null) {
+      if (ch === quote) {
+        if (tail.charAt(i + 1) === quote) {
+          i++; // doubled quote inside a string literal
+          continue;
+        }
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth === 0 && ch === ",") return false;
+    if (
+      depth === 0 &&
+      ((ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z") || ch === "_")
+    ) {
+      if (/^(DROP|RENAME)\b/i.test(tail.slice(i))) return false;
+    }
+  }
+  return true;
+}
+
+export type DdlTargetKind =
+  | "alter-add-column"
+  | "create-table"
+  | "create-index"
+  | "create-trigger";
+
+export interface DdlTarget {
+  kind: DdlTargetKind;
+  /** Table / index / trigger name that must exist in the live schema. */
+  name: string;
+  /** Column name that must exist on `name` (only for "alter-add-column"). */
+  column?: string;
+  /** Table an index is built on (informational — the index itself is verified). */
+  onTable?: string;
+}
+
+/**
+ * Parse a single SQL statement into one of the four DDL forms the self-heal
+ * gate can prove against the live schema:
+ *
+ *   - `ALTER TABLE <t> ADD [COLUMN] <c> <column-definition>`
+ *   - `CREATE TABLE [IF NOT EXISTS] <t> ( ... )`
+ *   - `CREATE [UNIQUE] INDEX [IF NOT EXISTS] <i> ON <t> ( ... )`
+ *   - `CREATE [TEMP|TEMPORARY] TRIGGER [IF NOT EXISTS] <t> ...`
+ *
+ * Returns null for anything else — UPDATE / INSERT / DELETE, DROP, ALTER ...
+ * RENAME, CREATE VIEW / VIRTUAL TABLE, PRAGMA writes, VACUUM, REPLACE,
+ * multi-action ALTER — so the gate refuses to self-heal whenever any statement
+ * is not one of the supported forms.
+ */
+export function parseStatementDdl(stmt: string): DdlTarget | null {
+  const s = stmt.trim();
+  if (s.length === 0) return null;
+  const start = skipWs(s, 0);
+
+  // ── CREATE forms ──────────────────────────────────────────────────────────
+  const createEnd = matchKeyword(s, start, "CREATE");
+  if (createEnd !== null) {
+    // CREATE TABLE [IF NOT EXISTS] <t> ( ... )
+    const tableEnd = matchKeyword(s, createEnd, "TABLE");
+    if (tableEnd !== null) {
+      const ident = matchIdent(s, skipWs(s, consumeIfNotExists(s, tableEnd)));
+      if (ident === null) return null;
+      const after = skipWs(s, ident.end);
+      // Require the column-list form — rejects `CREATE TABLE ... AS SELECT`.
+      if (after >= s.length || s.charAt(after) !== "(") return null;
+      return { kind: "create-table", name: ident.name };
+    }
+
+    // CREATE [UNIQUE] INDEX [IF NOT EXISTS] <i> ON <t> ( ... )
+    const uniqueEnd = matchKeyword(s, createEnd, "UNIQUE");
+    const indexStart = uniqueEnd !== null ? uniqueEnd : createEnd;
+    const indexEnd = matchKeyword(s, indexStart, "INDEX");
+    if (indexEnd !== null) {
+      const ident = matchIdent(s, skipWs(s, consumeIfNotExists(s, indexEnd)));
+      if (ident === null) return null;
+      const onEnd = matchKeyword(s, ident.end, "ON");
+      if (onEnd === null) return null;
+      const tableIdent = matchIdent(s, skipWs(s, onEnd));
+      if (tableIdent === null) return null;
+      const after = skipWs(s, tableIdent.end);
+      if (after >= s.length || s[after] !== "(") return null;
+      return { kind: "create-index", name: ident.name, onTable: tableIdent.name };
+    }
+
+    // CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <i> ...
+    const tempEnd = matchKeyword(s, createEnd, "TEMP");
+    const tmpEnd = tempEnd !== null ? tempEnd : matchKeyword(s, createEnd, "TEMPORARY");
+    const triggerEnd = matchKeyword(s, tmpEnd ?? createEnd, "TRIGGER");
+    if (triggerEnd !== null) {
+      const ident = matchIdent(s, skipWs(s, consumeIfNotExists(s, triggerEnd)));
+      if (ident === null) return null;
+      return { kind: "create-trigger", name: ident.name };
+    }
+
+    return null; // CREATE VIEW / CREATE VIRTUAL TABLE / any other CREATE form
+  }
+
+  // ── ALTER TABLE <t> ADD [COLUMN] <c> <column-definition> ──────────────────
+  const alterEnd = matchKeyword(s, start, "ALTER");
+  if (alterEnd !== null) {
+    const tableEnd = matchKeyword(s, alterEnd, "TABLE");
+    if (tableEnd === null) return null;
+    const tableIdent = matchIdent(s, skipWs(s, tableEnd));
+    if (tableIdent === null) return null;
+    const addEnd = matchKeyword(s, tableIdent.end, "ADD");
+    if (addEnd === null) return null;
+    const columnEnd = matchKeyword(s, addEnd, "COLUMN");
+    const columnStart = columnEnd !== null ? columnEnd : addEnd;
+    const columnIdent = matchIdent(s, skipWs(s, columnStart));
+    if (columnIdent === null) return null;
+    if (!isColumnDefinitionTail(s.slice(skipWs(s, columnIdent.end)))) return null;
+    return { kind: "alter-add-column", name: tableIdent.name, column: columnIdent.name };
+  }
+
+  return null;
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** True when `column` exists on `table` in the live schema (PRAGMA table_info). */
+function columnExists(db: Database, table: string, column: string): boolean {
+  const rows = db
+    .query<{ name: string }, []>(`PRAGMA table_info(${quoteIdent(table)})`)
+    .all();
+  return rows.some((r) => r.name === column);
+}
+
+/** True when a table / index / trigger of `name` exists in the live schema. */
+function schemaObjectExists(
+  db: Database,
+  type: "table" | "index" | "trigger",
+  name: string,
+): boolean {
+  const row = db
+    .query<{ cnt: number }, [string, string]>(
+      "SELECT COUNT(*) AS cnt FROM sqlite_master WHERE type = ? AND name = ?",
+    )
+    .get(type, name);
+  return (row?.cnt ?? 0) > 0;
+}
+
+/**
+ * Narrow, source-independent recovery gate. Called from the error catch in
+ * `runPendingMigrations` instead of trusting the error string.
+ *
+ * Splits `up` into statements and requires every statement to be one of the
+ * four supported DDL forms (`parseStatementDdl`), then verifies every declared
+ * schema target (column / table / index / trigger) against the LIVE schema. If
+ * any statement is unrecognised, data-changing, or destructive, or any declared
+ * target is missing, this throws and the runner fails closed — it refuses to
+ * record the version.
+ *
+ * Empty marker migrations (no DDL) never reach the caller's catch and return
+ * here defensively with nothing to prove.
+ */
+export function assertSelfHealEligible(db: Database, up: string): void {
+  const statements = up
+    .split(";")
+    .map((stmt) => stmt.trim())
+    .filter((stmt) => stmt.length > 0);
+
+  if (statements.length === 0) return;
+
+  const targets: DdlTarget[] = [];
+  for (const statement of statements) {
+    const target = parseStatementDdl(statement);
+    if (target === null) {
+      throw new Error(
+        `statement is not a supported idempotent DDL form (ALTER TABLE ... ADD COLUMN, ` +
+          `CREATE TABLE, CREATE INDEX, CREATE TRIGGER): "${statement}"`,
+      );
+    }
+    targets.push(target);
+  }
+
+  for (const target of targets) {
+    switch (target.kind) {
+      case "alter-add-column":
+        if (!columnExists(db, target.name, target.column!)) {
+          throw new Error(
+            `column "${target.column}" is missing on table "${target.name}"`,
+          );
+        }
+        break;
+      case "create-table":
+        if (!schemaObjectExists(db, "table", target.name)) {
+          throw new Error(`table "${target.name}" does not exist`);
+        }
+        break;
+      case "create-index":
+        if (!schemaObjectExists(db, "index", target.name)) {
+          throw new Error(`index "${target.name}" does not exist`);
+        }
+        break;
+      case "create-trigger":
+        if (!schemaObjectExists(db, "trigger", target.name)) {
+          throw new Error(`trigger "${target.name}" does not exist`);
+        }
+        break;
+    }
+  }
+}
+
+/**
+ * Integrity check that runs at the top of `runPendingMigrations`, before any
+ * pending work is selected. For every applied version it recomputes
+ * `sha256(file.content)` from the on-disk migration file and requires exact
+ * equality with the recorded checksum. An edited or renamed migration file, or
+ * a missing file for an applied version, stops the whole run. There is no
+ * allowlist to bypass this — recorded state is never trusted.
+ */
+export function verifyRecordedChecksums(
+  db: Database,
+  files: MigrationFile[],
+  applied: Set<number>,
+): void {
+  if (applied.size === 0) return;
+
+  const fileByVersion = new Map(files.map((f) => [f.version, f] as const));
+  const rows = db
+    .query<{ version: number; checksum: string }, []>(
+      "SELECT version, checksum FROM _schema_version",
+    )
+    .all();
+
+  for (const row of rows) {
+    const file = fileByVersion.get(row.version);
+    if (file === undefined) {
+      throw new Error(
+        `[migrations] fail closed: applied version ${row.version} has no matching migration file`,
+      );
+    }
+    const current = computeChecksum(file.content);
+    if (current !== row.checksum) {
+      throw new Error(
+        `[migrations] fail closed: checksum mismatch for applied version ${row.version} ` +
+          `(${file.name}); recorded ${row.checksum} != current ${current}. Refusing to continue.`,
+      );
+    }
+  }
+}
+
 // ── Core migration actions ─────────────────────────────────────────────────────
 
 export interface MigrationResult {
@@ -224,6 +570,13 @@ export async function runPendingMigrations(db?: Database): Promise<MigrationResu
 
   const files = await getMigrationFiles();
   const applied = getAppliedVersions(_db);
+
+  // R-2: before any pending work is selected, prove every already-recorded
+  // version still matches its on-disk migration file. An edited or renamed
+  // migration file, or a missing file, stops the whole run — recorded state
+  // is never trusted.
+  verifyRecordedChecksums(_db, files, applied);
+
   const pending = files.filter((f) => !applied.has(f.version));
 
   if (pending.length === 0) return [];
@@ -245,16 +598,25 @@ export async function runPendingMigrations(db?: Database): Promise<MigrationResu
         );
       })();
     } catch (err: unknown) {
-      const msg = (err as { message?: string }).message ?? "";
-      // Column was already added by shared-db.ts runMigrations() — self-heal by recording as applied
-      if (msg.includes("duplicate column name") || msg.includes("already exists")) {
-        _db.run(
-          `INSERT OR IGNORE INTO _schema_version (version, name, checksum) VALUES (?, ?, ?)`,
-          [file.version, file.name, checksum],
+      // R-2: a duplicate-column / already-exists error only proves the FIRST
+      // colliding statement failed — db.exec(up) aborts there, so later
+      // columns, tables, indexes, and backfills may still be missing. Never
+      // trust the error string: self-heal only when every statement is a
+      // supported idempotent DDL form AND every declared schema target is
+      // verifiably present in the live schema. Otherwise fail closed.
+      try {
+        assertSelfHealEligible(_db, up);
+      } catch (selfHealErr: unknown) {
+        throw new Error(
+          `Migration ${file.version} (${file.name}) failed and is not self-heal eligible; ` +
+            `refusing to record it. Original error: ${(err as Error).message}. ` +
+            `Self-heal refusal: ${(selfHealErr as Error).message}`,
         );
-      } else {
-        throw err;
       }
+      _db.run(
+        `INSERT OR IGNORE INTO _schema_version (version, name, checksum) VALUES (?, ?, ?)`,
+        [file.version, file.name, checksum],
+      );
     }
 
     results.push({ version: file.version, name: file.name, action: "applied" });

package/src/prefill.ts

@@ -0,0 +1,89 @@
+/**
+ * prefill.ts — Shared session-start context builder for host adapters.
+ *
+ * Keeps the "already pre-filled" experience consistent across Claude Code,
+ * OpenCode, Pi, and any future host that can call into openltm-core.
+ */
+import { getContextMerge, type Memory } from "./db.js";
+import { readConfigSync } from "./config.js";
+
+export interface PrefillOptions {
+  project: string;
+  maxMemories?: number;
+  maxGlobalMemories?: number;
+  maxLines?: number;
+  header?: string;
+}
+
+export interface PrefillSelection {
+  globals: Memory[];
+  scoped: Memory[];
+}
+
+const DEFAULT_HEADER = "## Prior Knowledge (LTM)";
+
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function clampPositiveInt(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return fallback;
+  return Math.floor(value);
+}
+
+function formatMemory(memory: Pick<Memory, "id" | "content" | "category" | "importance">): string {
+  return `- [${memory.id}] (${memory.category}/${memory.importance}) ${oneLine(memory.content)}`;
+}
+
+function trimLines(lines: string[], maxLines: number): string[] {
+  if (lines.length <= maxLines) return lines;
+  const trimmed = lines.slice(0, Math.max(0, maxLines - 1));
+  trimmed.push("… (truncated)");
+  return trimmed;
+}
+
+export function deriveProjectFromCwd(cwd: string): string {
+  return cwd.replace(/\/$/, "").split("/").pop() ?? "";
+}
+
+export function selectPrefillMemories(project: string, opts: Omit<PrefillOptions, "project"> = {}): PrefillSelection {
+  const cfg = readConfigSync();
+  const configuredTopN = cfg.ltm?.injectTopN;
+  const maxMemories = clampPositiveInt(opts.maxMemories, configuredTopN ?? 8);
+  const desiredGlobals = clampPositiveInt(opts.maxGlobalMemories, Math.min(3, Math.max(1, Math.ceil(maxMemories / 3))));
+
+  const merged = getContextMerge(project);
+
+  const globals = merged.globals.slice(0, Math.min(desiredGlobals, maxMemories));
+  const remaining = Math.max(0, maxMemories - globals.length);
+  const scoped = merged.scoped.slice(0, remaining);
+
+  if (scoped.length < remaining && globals.length < maxMemories) {
+    const refillGlobals = merged.globals.slice(globals.length, Math.min(merged.globals.length, maxMemories - scoped.length));
+    globals.push(...refillGlobals);
+  }
+
+  return { globals, scoped };
+}
+
+export function buildPrefillContext(opts: PrefillOptions): string {
+  const maxLines = clampPositiveInt(opts.maxLines, 18);
+  const { globals, scoped } = selectPrefillMemories(opts.project, opts);
+  if (globals.length === 0 && scoped.length === 0) return "";
+
+  const lines: string[] = [opts.header ?? DEFAULT_HEADER, ""];
+
+  if (globals.length > 0) {
+    lines.push("Global:");
+    for (const memory of globals) lines.push(formatMemory(memory));
+    lines.push("");
+  }
+
+  if (scoped.length > 0) {
+    lines.push(`Project (${opts.project}):`);
+    for (const memory of scoped) lines.push(formatMemory(memory));
+    lines.push("");
+  }
+
+  return trimLines(lines, maxLines).join("\n").trimEnd() + "\n";
+}

package/src/recall/explainer.ts

@@ -27,6 +27,10 @@ export interface ExplainerInput {
   semanticScore?: number | null;
 }
 
+function roundScore(value: number): number {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
 /** Compute memory temperature from access pattern. */
 export function computeTemperature(
   recallCount: number,
@@ -49,7 +53,7 @@ export function buildExplainer(input: ExplainerInput): RecallExplainer {
   const daysSince = input.last_recalled_at
     ? (Date.now() - new Date(input.last_recalled_at).getTime()) / 86_400_000
     : 90;
-  const recencyBoost = Math.max(0, 1 - daysSince / 90);
+  const recencyBoost = roundScore(Math.max(0, 1 - daysSince / 90));
 
   const ftsRank = input.ftsRank ?? null;
   const semanticScore = input.semanticScore ?? null;
@@ -70,7 +74,7 @@ export function buildExplainer(input: ExplainerInput): RecallExplainer {
     semanticScore,
     importanceBoost,
     recencyBoost,
-    totalScore,
+    totalScore: roundScore(totalScore),
     temperature: computeTemperature(input.recall_count, input.last_recalled_at),
   };
 }