clawmem 0.8.5 → 0.10.0

package/src/openclaw/transcript-resolver.ts

@@ -0,0 +1,441 @@
+/**
+ * ClawMem OpenClaw Plugin — Transcript path resolver
+ *
+ * Why this exists: the typed `PluginHookName` events that ClawMem subscribes
+ * to (`before_prompt_build`, `agent_end`) do NOT carry a `sessionFile` field
+ * in their event payload. ClawMem's hooks (precompact-extract,
+ * decision-extractor, handoff-generator, feedback-loop) all require a
+ * `transcript_path` to read the session JSONL — they call
+ * `validateTranscriptPath(input.transcriptPath ?? "")` and return empty on
+ * failure (no session_id fallback).
+ *
+ * Codex Turn N+2 caught this: §14.11's design fix moved precompact off
+ * `agent_end` (fire-and-forget) onto `before_prompt_build` (awaited), but
+ * neither event delivers `sessionFile`, so the load-bearing precompact
+ * path AND the eventually-consistent extractors were both no-ops.
+ *
+ * The fix: derive the transcript path from `sessionId` + `agentId` using
+ * OpenClaw's canonical layout from `src/config/sessions/paths.ts`:
+ *
+ *   <state-dir>/agents/<agentId>/sessions/<sessionId>.jsonl
+ *
+ * where:
+ *   - state-dir defaults to ~/.openclaw, overridable via OPENCLAW_STATE_DIR
+ *     or OPENCLAW_HOME env vars (mirrors `src/config/paths.ts:resolveStateDir`)
+ *   - agentId defaults to "main" (mirrors
+ *     `src/routing/session-key.ts:DEFAULT_AGENT_ID`)
+ *
+ * Events that DO carry `sessionFile` (`before_compaction`, `before_reset`,
+ * `after_compaction`, `session_end`) should pass that explicit value
+ * instead — the resolver is a fallback, not a replacement.
+ *
+ * The resolver is fail-open: returns undefined when the resolved path does
+ * not exist, the sessionId is invalid, or any underlying step throws.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * OpenClaw's default agent id (mirrors
+ * `openclaw/src/routing/session-key.ts:20` `DEFAULT_AGENT_ID = "main"`).
+ */
+export const DEFAULT_AGENT_ID = "main";
+
+/**
+ * Mirror of OpenClaw's session-id validation regex from
+ * `openclaw/src/config/sessions/paths.ts:61` `SAFE_SESSION_ID_RE`.
+ *
+ * Keeping the validation client-side prevents us from constructing
+ * paths with `..` or other separators when the upstream sessionId is
+ * malformed.
+ */
+const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
+
+/**
+ * Mirror of OpenClaw's agent-id validation/normalization from
+ * `openclaw/src/routing/session-key.ts:25` (`VALID_ID_RE`,
+ * `INVALID_CHARS_RE`, `LEADING_DASH_RE`, `TRAILING_DASH_RE`).
+ *
+ * Codex Turn N+3 caught that a simple `.toLowerCase()` is not equivalent
+ * to OpenClaw's full normalization: invalid characters must collapse to
+ * `-`, leading/trailing dashes get stripped, and the result is bounded
+ * to 64 characters. Mirroring this faithfully is critical because
+ * ClawMem's resolver MUST produce the same path string OpenClaw's
+ * `resolveSessionTranscriptPathInDir` would produce — otherwise the
+ * extractor hooks read the wrong file (or no file at all) for sessions
+ * whose agent id requires sanitization.
+ */
+const AGENT_ID_VALID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const AGENT_ID_INVALID_CHARS_RE = /[^a-z0-9_-]+/g;
+const AGENT_ID_LEADING_DASH_RE = /^-+/;
+const AGENT_ID_TRAILING_DASH_RE = /-+$/;
+
+/**
+ * Faithful mirror of `openclaw/src/routing/session-key.ts:91 normalizeAgentId`.
+ *
+ * - empty / whitespace → `DEFAULT_AGENT_ID` ("main")
+ * - already-valid id (case-insensitive) → returned lowercased
+ * - otherwise: lowercase, collapse invalid runs to `-`, strip leading +
+ *   trailing dashes, slice to 64 chars, fall back to `DEFAULT_AGENT_ID`
+ *   when the sanitized form is empty
+ */
+export function normalizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return DEFAULT_AGENT_ID;
+  const lowered = trimmed.toLowerCase();
+  if (AGENT_ID_VALID_RE.test(trimmed)) {
+    return lowered;
+  }
+  const sanitized = lowered
+    .replace(AGENT_ID_INVALID_CHARS_RE, "-")
+    .replace(AGENT_ID_LEADING_DASH_RE, "")
+    .replace(AGENT_ID_TRAILING_DASH_RE, "")
+    .slice(0, 64);
+  return sanitized || DEFAULT_AGENT_ID;
+}
+
+/**
+ * Legacy state-directory names that OpenClaw still falls back to when the
+ * new `.openclaw` directory does not exist on disk. Mirrors
+ * `openclaw/src/config/paths.ts:21` `LEGACY_STATE_DIRNAMES`.
+ *
+ * Codex Turn N+4 caught that the prior implementation always synthesized
+ * `~/.openclaw` and never checked whether OpenClaw was actually running
+ * from the legacy state root. This array preserves OpenClaw's pre-rebrand
+ * compatibility for installs that haven't been migrated.
+ */
+const LEGACY_STATE_DIRNAMES = [".clawdbot"] as const;
+const NEW_STATE_DIRNAME = ".openclaw";
+
+/**
+ * Resolve OpenClaw's state directory using the same precedence as
+ * `openclaw/src/config/paths.ts:resolveStateDir`:
+ *
+ *   1. `$OPENCLAW_STATE_DIR` if set (env override, no further fallback)
+ *   2. `$OPENCLAW_HOME` if set (replaces homedir; appends `.openclaw`)
+ *   3. `<home>/.openclaw` if the directory exists
+ *   4. `<home>/.clawdbot` (legacy) if it exists and `.openclaw` does not
+ *   5. `<home>/.openclaw` as the synthesized default
+ *
+ * Honors `OPENCLAW_TEST_FAST=1` to skip the existence checks (mirrors
+ * OpenClaw's behavior at `paths.ts:70-72`).
+ *
+ * Codex Turn N+4 fix: prior version skipped step 4 entirely. Upgraded-but-
+ * not-migrated installs would then point at a synthesized `.openclaw` path
+ * that doesn't exist, while OpenClaw itself runs from `.clawdbot`.
+ */
+export function resolveOpenClawStateDir(
+  env: NodeJS.ProcessEnv = process.env,
+  home: () => string = homedir,
+): string {
+  const stateOverride = env.OPENCLAW_STATE_DIR?.trim();
+  if (stateOverride) {
+    return resolveHomeRelative(stateOverride, home);
+  }
+
+  // OPENCLAW_HOME replaces the homedir entirely (mirrors
+  // `openclaw/src/infra/home-dir.ts:resolveRawHomeDir`). The state dir
+  // then becomes `<OPENCLAW_HOME>/.openclaw`.
+  const effectiveHome = (() => {
+    const homeOverride = env.OPENCLAW_HOME?.trim();
+    if (homeOverride) return resolveHomeRelative(homeOverride, home);
+    return home();
+  })();
+
+  const newDir = join(effectiveHome, NEW_STATE_DIRNAME);
+
+  if (env.OPENCLAW_TEST_FAST === "1") {
+    return newDir;
+  }
+
+  // Prefer the new dir when it exists.
+  try {
+    if (existsSync(newDir)) return newDir;
+  } catch {
+    // Fall through to legacy detection
+  }
+
+  // Legacy fallback: check each legacy name in order; first existing wins.
+  for (const legacyName of LEGACY_STATE_DIRNAMES) {
+    const legacyDir = join(effectiveHome, legacyName);
+    try {
+      if (existsSync(legacyDir)) return legacyDir;
+    } catch {
+      // Ignore and continue
+    }
+  }
+
+  // Synthesized default — OpenClaw bootstraps the new dir on first run.
+  return newDir;
+}
+
+function resolveHomeRelative(input: string, home: () => string): string {
+  if (input === "~") return home();
+  if (input.startsWith("~/")) return join(home(), input.slice(2));
+  return resolve(input);
+}
+
+/**
+ * Minimal SessionEntry shape ClawMem cares about. The full type lives in
+ * `openclaw/src/config/sessions/types.ts:111` and has many more fields,
+ * but the resolver only needs `sessionId` and `sessionFile`. Treating
+ * the rest of the JSON as `unknown` keeps ClawMem decoupled from
+ * OpenClaw's internal session model.
+ */
+type MinimalSessionEntry = {
+  sessionId?: unknown;
+  sessionFile?: unknown;
+  [key: string]: unknown;
+};
+
+/**
+ * Read `<sessionsDir>/sessions.json` and look up the entry whose
+ * `sessionFile` ClawMem should use. Mirrors OpenClaw's authoritative
+ * source of truth at `openclaw/src/config/sessions/store-read.ts:10`.
+ *
+ * Resolution order:
+ *   1. Exact key match `store[sessionKey]` (when caller has the full
+ *      session-store key like `agent:main:abc123`)
+ *   2. Scan entries for one whose `entry.sessionId === sessionId`
+ *
+ * Returns the resolved `sessionFile` path (made absolute against
+ * `sessionsDir` when stored as a relative basename) or undefined when:
+ *   - sessions.json does not exist or fails to parse
+ *   - no matching entry has a `sessionFile` field
+ *
+ * Fail-open: never throws. Codex Turn N+5 fix — sessions.json is the
+ * only authoritative way to disambiguate between base and topic-scoped
+ * transcript files when both exist for the same sessionId.
+ */
+function lookupSessionFileFromStore(params: {
+  sessionsDir: string;
+  sessionId: string;
+  sessionKey?: string;
+}): string | undefined {
+  const storePath = join(params.sessionsDir, "sessions.json");
+  let raw: string;
+  try {
+    raw = readFileSync(storePath, "utf-8");
+  } catch {
+    return undefined;
+  }
+  if (!raw.trim()) return undefined;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const store = parsed as Record<string, unknown>;
+
+  const resolveEntryFile = (entry: MinimalSessionEntry | undefined): string | undefined => {
+    const file = entry?.sessionFile;
+    if (typeof file !== "string" || !file.trim()) return undefined;
+    const trimmed = file.trim();
+    return isAbsolute(trimmed) ? trimmed : join(params.sessionsDir, trimmed);
+  };
+
+  // 1. Exact sessionKey match
+  if (params.sessionKey) {
+    const directEntry = store[params.sessionKey];
+    if (directEntry && typeof directEntry === "object" && !Array.isArray(directEntry)) {
+      const candidate = resolveEntryFile(directEntry as MinimalSessionEntry);
+      if (candidate) return candidate;
+    }
+  }
+
+  // 2. Scan for entry whose sessionId matches
+  for (const value of Object.values(store)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const entry = value as MinimalSessionEntry;
+    if (typeof entry.sessionId === "string" && entry.sessionId === params.sessionId) {
+      const candidate = resolveEntryFile(entry);
+      if (candidate) return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build the session-file basename. Mirrors the filename-construction
+ * branch in `openclaw/src/config/sessions/paths.ts:248-251`:
+ *
+ *   - no topicId: `<sessionId>.jsonl`
+ *   - topicId (string): `<sessionId>-topic-<encodeURIComponent(topicId)>.jsonl`
+ *   - topicId (number): `<sessionId>-topic-<topicId>.jsonl`
+ */
+function buildTranscriptFileName(sessionId: string, topicId?: string | number): string {
+  if (topicId === undefined || topicId === null || topicId === "") {
+    return `${sessionId}.jsonl`;
+  }
+  const encoded =
+    typeof topicId === "string" ? encodeURIComponent(topicId) : String(topicId);
+  return `${sessionId}-topic-${encoded}.jsonl`;
+}
+
+/**
+ * Derive the canonical OpenClaw session transcript path for a given
+ * (sessionId, agentId, sessionKey, topicId) tuple. Mirrors
+ * `openclaw/src/config/sessions/paths.ts:resolveSessionTranscriptPathInDir`
+ * including the topic-id filename branch and `resolveSessionFilePath`'s
+ * `entry.sessionFile` lookup against `sessions.json`.
+ *
+ * Resolution order (Codex Turn N+5 fix):
+ *   1. **Authoritative source-of-truth**: read `sessions.json` and look
+ *      up `entry.sessionFile` by sessionKey (exact match) or by scanning
+ *      for an entry whose `sessionId` matches. This is the same path
+ *      OpenClaw uses internally at
+ *      `openclaw/src/config/sessions/paths.ts:resolveSessionFilePath` —
+ *      the entry's sessionFile is the truth, regardless of whether the
+ *      transcript is base or topic-scoped.
+ *   2. If `params.topicId` is provided explicitly, use it:
+ *      `<sessionId>-topic-<encodeURIComponent(topicId)>.jsonl`
+ *   3. Try the base filename `<sessionId>.jsonl` if AND ONLY IF no
+ *      topic-scoped variants coexist. This prevents ClawMem from
+ *      silently picking the wrong transcript when both base and topic
+ *      files exist for the same sessionId without sessions.json metadata.
+ *   4. If only topic-scoped variants exist, return the single match
+ *      (unambiguous). Two or more topic variants without metadata is
+ *      ambiguous → fail-open.
+ *
+ * Returns undefined when:
+ *   - sessionId is missing or fails the SAFE_SESSION_ID_RE check
+ *   - none of the resolution steps find a file on disk
+ *   - the filesystem fallback is ambiguous (base + topic coexist, or
+ *     multiple topic variants exist) and sessions.json could not
+ *     disambiguate
+ *
+ * Fail-open: never throws. Each filesystem check is wrapped in a
+ * try/catch and ignored.
+ */
+export function resolveOpenClawSessionFile(params: {
+  sessionId?: string;
+  agentId?: string;
+  sessionKey?: string;
+  topicId?: string | number;
+  env?: NodeJS.ProcessEnv;
+}): string | undefined {
+  const sessionId = params.sessionId?.trim();
+  if (!sessionId) return undefined;
+  if (!SAFE_SESSION_ID_RE.test(sessionId)) return undefined;
+
+  // Use the full normalizeAgentId mirror — NOT a simple .toLowerCase().
+  const agentId = normalizeAgentId(params.agentId);
+
+  let stateDir: string;
+  try {
+    stateDir = resolveOpenClawStateDir(params.env);
+  } catch {
+    return undefined;
+  }
+
+  const sessionsDir = join(stateDir, "agents", agentId, "sessions");
+
+  // 1. AUTHORITATIVE: sessions.json lookup. This is OpenClaw's source
+  // of truth for which transcript file is active for a given session.
+  const fromStore = lookupSessionFileFromStore({
+    sessionsDir,
+    sessionId,
+    sessionKey: params.sessionKey,
+  });
+  if (fromStore) {
+    try {
+      if (existsSync(fromStore)) return fromStore;
+    } catch {
+      // Fall through to filesystem fallback
+    }
+  }
+
+  // 2. Explicit topic-id from caller wins (rare — typed-hook events
+  // don't carry topicId, but the API surface still supports it for
+  // tests and future callers).
+  if (params.topicId !== undefined && params.topicId !== null && params.topicId !== "") {
+    const explicitTopic = join(
+      sessionsDir,
+      buildTranscriptFileName(sessionId, params.topicId),
+    );
+    try {
+      if (existsSync(explicitTopic)) return explicitTopic;
+    } catch {
+      // Fall through
+    }
+    // Don't fall back to the base filename if caller asked for a specific
+    // topic — they explicitly want THAT file or nothing.
+    return undefined;
+  }
+
+  // 3 + 4. Filesystem fallback when sessions.json could not resolve.
+  // We need to enumerate the sessions dir to detect the base+topic
+  // coexistence case (Codex Turn N+5 finding) before deciding which
+  // file to return.
+  let baseExists = false;
+  try {
+    baseExists = existsSync(join(sessionsDir, `${sessionId}.jsonl`));
+  } catch {
+    baseExists = false;
+  }
+
+  let topicMatches: string[] = [];
+  try {
+    const topicPrefix = `${sessionId}-topic-`;
+    const entries = readdirSync(sessionsDir);
+    topicMatches = entries.filter(
+      (name) => name.startsWith(topicPrefix) && name.endsWith(".jsonl"),
+    );
+  } catch {
+    topicMatches = [];
+  }
+
+  // Codex Turn N+5 fix: when BOTH base and topic variants exist, the
+  // resolver cannot tell which is the active transcript without
+  // sessions.json metadata. Fail-open instead of preferring base.
+  if (baseExists && topicMatches.length > 0) {
+    return undefined;
+  }
+
+  // Base only → return base
+  if (baseExists && topicMatches.length === 0) {
+    return join(sessionsDir, `${sessionId}.jsonl`);
+  }
+
+  // Single topic-scoped variant → unambiguous, return it
+  if (!baseExists && topicMatches.length === 1) {
+    return join(sessionsDir, topicMatches[0]!);
+  }
+
+  // 0 matches → no transcript exists yet (new session)
+  // 2+ topic variants without base → ambiguous, fail-open
+  return undefined;
+}
+
+/**
+ * Pure-function variant of `resolveOpenClawSessionFile` that skips the
+ * filesystem existence check. Useful for unit tests that want to verify
+ * the path-construction logic without setting up a real OpenClaw state
+ * tree on disk.
+ */
+export function buildOpenClawSessionFilePath(params: {
+  sessionId: string;
+  agentId?: string;
+  topicId?: string | number;
+  env?: NodeJS.ProcessEnv;
+}): string | undefined {
+  const sessionId = params.sessionId?.trim();
+  if (!sessionId || !SAFE_SESSION_ID_RE.test(sessionId)) return undefined;
+  const agentId = normalizeAgentId(params.agentId);
+  let stateDir: string;
+  try {
+    stateDir = resolveOpenClawStateDir(params.env);
+  } catch {
+    return undefined;
+  }
+  const fileName = buildTranscriptFileName(sessionId, params.topicId);
+  return join(stateDir, "agents", agentId, "sessions", fileName);
+}

package/src/session-focus.ts

@@ -0,0 +1,227 @@
+/**
+ * Session-Scoped Focus (§11.4 — v0.9.0)
+ *
+ * Per-session topic primitive that biases context-surfacing ranking toward
+ * docs relevant to the declared working context — WITHOUT persisting any
+ * state to SQLite. Intra-session curation that cannot contaminate other
+ * sessions.
+ *
+ * Primary signal: per-session state file at
+ *   ~/.cache/clawmem/sessions/<session_id>.focus
+ *
+ * The env var CLAWMEM_SESSION_FOCUS is a DEBUG-ONLY override: it bypasses
+ * the per-session file entirely, and because it is a single process-wide
+ * variable it does NOT provide per-session scoping in multi-session host
+ * processes (e.g. a long-lived MCP server handling multiple Claude Code
+ * sessions). Use the file path for correctness; use the env var for
+ * ad-hoc single-session debugging only.
+ *
+ * All read paths are fail-open. Unreadable, corrupt, empty, missing,
+ * invalid-UTF-8, or oversized focus files return undefined and the
+ * caller proceeds with baseline ranking (byte-identical to pre-§11.4).
+ * The stage must NEVER half-apply a malformed topic.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import type { ScoredResult } from "./memory.ts";
+
+const MAX_TOPIC_LEN = 256;
+
+/**
+ * Resolve the root directory for session focus files. Defaults to
+ * `~/.cache/clawmem/sessions`, overridable via `CLAWMEM_FOCUS_ROOT`.
+ * The override is primarily a test hook (so `bun:test` can redirect
+ * writes to a tmp dir) but is also safe to use in production if an
+ * operator wants to relocate the focus files out of `$HOME`.
+ *
+ * Computed lazily on every call so env-var changes in tests take
+ * effect without module reload.
+ */
+export function focusRoot(): string {
+  const override = process.env.CLAWMEM_FOCUS_ROOT;
+  if (override && override.trim().length > 0) return override;
+  return path.join(os.homedir(), ".cache", "clawmem", "sessions");
+}
+
+export function focusFilePath(sessionId: string): string {
+  return path.join(focusRoot(), `${sessionId}.focus`);
+}
+
+/**
+ * Read the session focus topic. Returns undefined on any failure:
+ * - sessionId missing/empty
+ * - file does not exist
+ * - file unreadable (permissions, etc.)
+ * - file empty or whitespace-only
+ * - file exceeds MAX_TOPIC_LEN
+ * - file contains invalid UTF-8 (readFileSync throws)
+ *
+ * Never throws. Caller treats undefined as "no topic set" and skips
+ * the boost stage entirely.
+ */
+export function readSessionFocus(sessionId?: string): string | undefined {
+  if (!sessionId) return undefined;
+  try {
+    const p = focusFilePath(sessionId);
+    if (!fs.existsSync(p)) return undefined;
+    const raw = fs.readFileSync(p, { encoding: "utf-8" });
+    const topic = raw.trim();
+    if (!topic) return undefined;
+    if (topic.length > MAX_TOPIC_LEN) return undefined;
+    return topic;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write a session focus topic. Creates the sessions directory if needed.
+ * Overwrites any existing file. Throws on invalid input or I/O errors
+ * (caller surface — CLI command that should fail loudly on misuse).
+ */
+export function writeSessionFocus(sessionId: string, topic: string): void {
+  if (!sessionId || !sessionId.trim()) {
+    throw new Error("writeSessionFocus: sessionId required");
+  }
+  const trimmed = topic.trim();
+  if (!trimmed) {
+    throw new Error("writeSessionFocus: topic required");
+  }
+  if (trimmed.length > MAX_TOPIC_LEN) {
+    throw new Error(`writeSessionFocus: topic exceeds max length ${MAX_TOPIC_LEN}`);
+  }
+  fs.mkdirSync(focusRoot(), { recursive: true });
+  fs.writeFileSync(focusFilePath(sessionId), trimmed, { encoding: "utf-8" });
+}
+
+/**
+ * Clear a session focus. No-op if the file does not exist.
+ * Never throws (caller is typically "revert ranking to baseline").
+ */
+export function clearSessionFocus(sessionId: string): void {
+  if (!sessionId) return;
+  try {
+    const p = focusFilePath(sessionId);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  } catch {
+    /* ignore — clearing is best-effort */
+  }
+}
+
+/**
+ * Resolve the effective session focus topic by checking the per-session
+ * focus file first, then falling back to a provided env-var value (the
+ * CLAWMEM_SESSION_FOCUS debug override). Returns undefined when neither
+ * yields a valid topic.
+ *
+ * Precedence is file > env var because the file is the only signal
+ * that provides per-session scoping on multi-session host processes.
+ * Exposed here (rather than inlined at the call site) so the hook's
+ * precedence logic can be unit-tested directly without spinning up a
+ * full contextSurfacing invocation.
+ *
+ * Never throws. Never logs. Every failure path returns undefined and
+ * the caller treats that as "no topic set" (byte-identical to
+ * pre-§11.4 hook behavior).
+ */
+export function resolveSessionTopic(
+  sessionId: string | undefined,
+  envVar: string | undefined
+): string | undefined {
+  const fromFile = readSessionFocus(sessionId);
+  if (fromFile) return fromFile;
+  const fromEnv = envVar?.trim();
+  if (fromEnv) return fromEnv;
+  return undefined;
+}
+
+/**
+ * Case-insensitive tokenized AND-match against title + displayPath + body.
+ * Tokens shorter than 2 chars are dropped (common stopwords and typos).
+ * Returns true only if every remaining token appears in the haystack.
+ */
+function matchesTopic(result: ScoredResult, topic: string): boolean {
+  const tokens = topic
+    .toLowerCase()
+    .split(/\s+/)
+    .map(t => t.trim())
+    .filter(t => t.length >= 2);
+  if (tokens.length === 0) return false;
+
+  const haystack = [
+    result.title || "",
+    result.displayPath || "",
+    (result.body || "").slice(0, 800),
+  ]
+    .join(" ")
+    .toLowerCase();
+
+  return tokens.every(t => haystack.includes(t));
+}
+
+export interface TopicBoostOptions {
+  /** Multiplier applied to docs whose title/path/body match all topic tokens. Default 1.4. */
+  boostFactor?: number;
+  /**
+   * Multiplier applied to non-matching docs. Default 0.75.
+   * Clamped to a 0.5 floor so the boost is a re-ranker, not a hide —
+   * non-matching docs are demoted but never suppressed to zero.
+   */
+  demoteFactor?: number;
+}
+
+/**
+ * Apply session-topic boost/demote to a scored result set as a POST-COMPOSITE
+ * reranking pass. Runs AFTER applyCompositeScoring(...) and BEFORE threshold
+ * filtering (the specific architectural placement Codex approved in Turn 1 of
+ * the v0.9.0 design review).
+ *
+ * Behavior:
+ *   - Empty/undefined topic → returns input unchanged (no-op, byte-identical).
+ *   - Topic present but ZERO docs match → returns input unchanged (no-op).
+ *     This is the fail-open contract from the approved §11.4 spec: "topic
+ *     set + zero matching docs → proceed with the normal results." Without
+ *     this short-circuit, uniformly demoting every doc would push some
+ *     below the downstream threshold filter and silently shrink the
+ *     result set — a regression vs the no-topic baseline.
+ *     (Caught by Codex in §11.4 code review Turn 1, 2026-04-13.)
+ *   - Topic present AND at least one match → each result's compositeScore
+ *     is multiplied by either boostFactor (matching) or demoteFactor
+ *     (non-matching), then results are re-sorted descending.
+ *
+ * Matching is computed exactly once per result in a pre-pass so the
+ * short-circuit can decide without double-evaluating the token match.
+ *
+ * This is a pure function over the scored set — it does NOT call the DB,
+ * does NOT write SQLite state, does NOT touch any lifecycle column.
+ * Mutates compositeScore in place (consistent with existing scoring
+ * helpers in this codebase; single caller, single thread).
+ */
+export function applyTopicBoost<T extends ScoredResult>(
+  scored: T[],
+  topic: string | undefined,
+  options: TopicBoostOptions = {}
+): T[] {
+  if (!topic || !topic.trim()) return scored;
+  if (scored.length === 0) return scored;
+
+  const boostFactor = options.boostFactor ?? 1.4;
+  const demoteFactor = Math.max(options.demoteFactor ?? 0.75, 0.5);
+
+  // Pre-compute per-result match flags so we can early-return on zero
+  // matches without double-evaluating matchesTopic during the mutation
+  // pass. Caching is also a (small) perf win for any single call.
+  const matches = scored.map(r => matchesTopic(r, topic));
+  const anyMatch = matches.some(Boolean);
+  if (!anyMatch) return scored; // fail-open: baseline ordering preserved
+
+  for (let i = 0; i < scored.length; i++) {
+    const factor = matches[i] ? boostFactor : demoteFactor;
+    scored[i]!.compositeScore = scored[i]!.compositeScore * factor;
+  }
+
+  scored.sort((a, b) => b.compositeScore - a.compositeScore);
+  return scored;
+}

package/src/store.ts

@@ -711,6 +711,11 @@ function initializeDatabase(db: Database): void {
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_nodes_type ON entity_nodes(entity_type)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_nodes_vault ON entity_nodes(vault)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_nodes_mentions ON entity_nodes(mention_count DESC)`);
+  // §11.1 (v0.9.0): expression index backing the `LOWER(name) IN (...) AND vault = ?`
+  // batch lookup used by the context-surfacing entity-detection hot path.
+  // Without this index the batch query devolves into a full scan on large vaults.
+  // Idempotent via IF NOT EXISTS — existing vaults pick it up on next open.
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_nodes_lower_name ON entity_nodes(LOWER(name), vault)`);
 
   // Entity mentions: entity ↔ document junction table
   db.exec(`