@dahch/muninn 0.1.0 → 0.2.0

package/dist/service/memory-service.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { assertDocPath } from "../util/path-safety.js";
-import { getDatabase, ensureProject, findGitRoot, } from "../db/client.js";
+import { getDatabase, getReadOnlyDatabase, ensureProject, findGitRoot, tryGetGitRemote, } from "../db/client.js";
 export const VALID_CATEGORIES = [
     "decision",
     "convention",
@@ -17,6 +17,15 @@ export const VALID_ENTITY_TYPES = [
     "interface",
     "module",
 ];
+export const DEFAULT_SESSION_BRIEF_BUDGET = 8_000;
+export const MAX_SESSION_BRIEF_BUDGET = 20_000;
+export const MAX_SESSION_BRIEF_PATHS = 20;
+export const SESSION_BRIEF_RECENT_ACTIVITY_LIMIT = 20;
+export const DEFAULT_NEIGHBOR_DEPTH = 1;
+export const MAX_NEIGHBOR_DEPTH = 2;
+export const DEFAULT_NEIGHBOR_LIMIT = 20;
+export const MAX_NEIGHBOR_LIMIT = 50;
+export const SESSION_BRIEF_RELATED_LIMIT = MAX_NEIGHBOR_LIMIT;
 /**
  * Normalizes input symbols into canonical identifier, filePath, and entityType.
  */
@@ -151,6 +160,582 @@ export function sanitizeFtsQuery(query) {
     }
     return terms.join(" ");
 }
+function sessionBriefError(err) {
+    if (err instanceof Error && err.message.trim())
+        return err.message.trim();
+    const message = String(err).trim();
+    return message || "unknown error";
+}
+function resolveSessionBriefBudget(value) {
+    const budget = value ?? DEFAULT_SESSION_BRIEF_BUDGET;
+    if (!Number.isInteger(budget) || budget <= 0) {
+        throw new Error("budgetChars must be a positive integer");
+    }
+    if (budget > MAX_SESSION_BRIEF_BUDGET) {
+        throw new Error(`budgetChars cannot exceed ${MAX_SESSION_BRIEF_BUDGET} characters`);
+    }
+    return budget;
+}
+/**
+ * Resolve file/directory selections against the project root without touching the
+ * filesystem. The result is a deduplicated list of project-relative POSIX paths;
+ * an empty string means "the whole project root".
+ */
+function resolveSessionBriefPaths(paths, rootPath) {
+    const rawPaths = paths ?? [];
+    if (rawPaths.length > MAX_SESSION_BRIEF_PATHS) {
+        throw new Error(`At most ${MAX_SESSION_BRIEF_PATHS} paths may be requested for a session brief`);
+    }
+    const root = path.resolve(rootPath);
+    const resolved = rawPaths.map((raw) => {
+        if (typeof raw !== "string") {
+            throw new Error("Session brief paths must be strings");
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new Error("Session brief paths cannot be empty");
+        }
+        // Accept Windows and POSIX separators, then compare in one canonical form.
+        const withPlatformSeparators = trimmed.replace(/\\/g, path.sep);
+        const absolute = path.isAbsolute(withPlatformSeparators)
+            ? path.resolve(withPlatformSeparators)
+            : path.resolve(root, withPlatformSeparators);
+        const relative = path.relative(root, absolute);
+        if (relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)) {
+            throw new Error(`Path "${raw}" is outside the project root ${root}`);
+        }
+        return relative.split(path.sep).filter(Boolean).join("/");
+    });
+    return [...new Set(resolved)];
+}
+function normalizeIndexedFilePath(filePath, rootPath) {
+    let normalized = filePath.replace(/\\/g, "/");
+    if (path.isAbsolute(filePath)) {
+        const relative = path.relative(path.resolve(rootPath), path.resolve(filePath));
+        if (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)) {
+            normalized = relative.replace(/\\/g, "/");
+        }
+    }
+    return normalized
+        .replace(/^\.\/+/, "")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "");
+}
+function entityMatchesSelectedPaths(entityPath, selectedPaths, rootPath) {
+    if (selectedPaths.length === 0)
+        return false;
+    const normalized = normalizeIndexedFilePath(entityPath, rootPath);
+    return selectedPaths.some((selected) => selected === "" ||
+        normalized === selected ||
+        normalized.startsWith(`${selected}/`));
+}
+const NEIGHBOR_RELATION_ORDER = [
+    "imports",
+    "calls",
+    "implements",
+    "extends",
+    "references",
+];
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
+function compareEntities(left, right) {
+    if (left.identifier !== right.identifier) {
+        return left.identifier < right.identifier ? -1 : 1;
+    }
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+}
+/**
+ * Resolves an entity using the same exact, suffix, and prefix/path tiers used by
+ * symbol inspection. Callers always pass a concrete project id.
+ */
+function resolveEntityByIdentifier(db, projectId, identifier) {
+    if (!identifier || typeof identifier !== "string" || !identifier.trim()) {
+        return undefined;
+    }
+    const query = identifier.trim();
+    const exact = db
+        .prepare(`SELECT id, project_id, entity_type, identifier, file_path
+       FROM entities
+       WHERE project_id = ? AND identifier = ?`)
+        .get(projectId, query);
+    if (exact)
+        return exact;
+    const escapedQuery = escapeLikePattern(query);
+    const suffix = db
+        .prepare(`SELECT id, project_id, entity_type, identifier, file_path
+       FROM entities
+       WHERE project_id = ? AND (identifier LIKE '%::' || ? ESCAPE '\\' OR identifier LIKE '%.' || ? ESCAPE '\\')
+       ORDER BY identifier ASC, id ASC
+       LIMIT 1`)
+        .get(projectId, escapedQuery, escapedQuery);
+    if (suffix)
+        return suffix;
+    return db
+        .prepare(`SELECT id, project_id, entity_type, identifier, file_path
+       FROM entities
+       WHERE project_id = ? AND (identifier LIKE ? || '%' ESCAPE '\\' OR file_path = ?)
+       ORDER BY identifier ASC, id ASC
+       LIMIT 1`)
+        .get(projectId, escapedQuery, query);
+}
+function resolveNeighborDepth(value) {
+    if (value === null || value === undefined || !Number.isFinite(value)) {
+        return DEFAULT_NEIGHBOR_DEPTH;
+    }
+    const depth = Math.floor(value);
+    if (depth < 1)
+        return DEFAULT_NEIGHBOR_DEPTH;
+    return Math.min(depth, MAX_NEIGHBOR_DEPTH);
+}
+function resolveNeighborLimit(value) {
+    if (value === null || value === undefined || !Number.isFinite(value)) {
+        return DEFAULT_NEIGHBOR_LIMIT;
+    }
+    const limit = Math.floor(value);
+    if (limit < 1)
+        return DEFAULT_NEIGHBOR_LIMIT;
+    return Math.min(limit, MAX_NEIGHBOR_LIMIT);
+}
+function collectNeighbors(db, root, depthValue, limitValue) {
+    const depth = resolveNeighborDepth(depthValue);
+    const limit = resolveNeighborLimit(limitValue);
+    const visited = new Set([root.id]);
+    const flat = [];
+    let frontier = [root];
+    let truncated = false;
+    const outgoingStatement = db.prepare(`SELECT e.id, e.project_id, e.entity_type, e.identifier, e.file_path, ed.relation_type
+     FROM entity_dependencies ed
+     JOIN entities e ON e.id = ed.target_entity_id
+     WHERE ed.source_entity_id = ?
+     ORDER BY ed.relation_type ASC, e.identifier ASC, e.id ASC`);
+    const incomingStatement = db.prepare(`SELECT e.id, e.project_id, e.entity_type, e.identifier, e.file_path, ed.relation_type
+     FROM entity_dependencies ed
+     JOIN entities e ON e.id = ed.source_entity_id
+     WHERE ed.target_entity_id = ?
+     ORDER BY ed.relation_type ASC, e.identifier ASC, e.id ASC`);
+    outer: for (let level = 1; level <= depth && frontier.length > 0; level++) {
+        const nextFrontier = [];
+        const orderedFrontier = [...frontier].sort(compareEntities);
+        for (const current of orderedFrontier) {
+            const directions = [
+                { direction: "outgoing", rows: outgoingStatement.all(current.id) },
+                { direction: "incoming", rows: incomingStatement.all(current.id) },
+            ];
+            for (const { direction, rows } of directions) {
+                const orderedRows = [...rows].sort((left, right) => {
+                    const leftRelation = NEIGHBOR_RELATION_ORDER.indexOf(left.relation_type);
+                    const rightRelation = NEIGHBOR_RELATION_ORDER.indexOf(right.relation_type);
+                    if (leftRelation !== rightRelation) {
+                        return leftRelation - rightRelation;
+                    }
+                    return compareEntities(left, right);
+                });
+                for (const row of orderedRows) {
+                    if (visited.has(row.id))
+                        continue;
+                    if (flat.length >= limit) {
+                        truncated = true;
+                        break outer;
+                    }
+                    visited.add(row.id);
+                    const entity = {
+                        id: row.id,
+                        project_id: row.project_id,
+                        entity_type: row.entity_type,
+                        identifier: row.identifier,
+                        file_path: row.file_path,
+                    };
+                    flat.push({
+                        entity,
+                        relationType: row.relation_type,
+                        direction,
+                        depth: level,
+                    });
+                    nextFrontier.push(entity);
+                }
+            }
+        }
+        frontier = nextFrontier;
+    }
+    const groupsByKey = new Map();
+    for (const neighbor of flat) {
+        const key = `${neighbor.direction}:${neighbor.relationType}`;
+        const existing = groupsByKey.get(key);
+        if (existing) {
+            existing.neighbors.push(neighbor);
+        }
+        else {
+            groupsByKey.set(key, {
+                direction: neighbor.direction,
+                relationType: neighbor.relationType,
+                neighbors: [neighbor],
+            });
+        }
+    }
+    return {
+        entity: root,
+        depth,
+        limit,
+        groups: [...groupsByKey.values()],
+        neighbors: flat,
+        truncated,
+    };
+}
+function deriveSessionBriefProject(rootPath) {
+    const root = path.resolve(rootPath);
+    return {
+        id: null,
+        name: path.basename(root) || "project",
+        rootPath: root,
+        gitRemote: tryGetGitRemote(root),
+    };
+}
+function sessionBriefProjectFromRow(project) {
+    return {
+        id: project.id,
+        name: project.name,
+        rootPath: project.root_path,
+        gitRemote: project.git_remote,
+    };
+}
+function findSessionBriefProjectRow(db, rootPath) {
+    const root = path.resolve(rootPath);
+    return db
+        .prepare(`SELECT id, name, git_remote, root_path, created_at
+       FROM projects
+       WHERE root_path = ?`)
+        .get(root);
+}
+function formatCount(count) {
+    return count === null ? "unavailable" : String(count);
+}
+function appendBriefObservation(lines, observation, labelSuperseded) {
+    const supersededLabel = labelSuperseded && observation.status === "superseded"
+        ? ` — SUPERSEDED${observation.superseded_by
+            ? ` (replaced by \`${observation.superseded_by}\`)`
+            : ""}`
+        : "";
+    lines.push(`- **${observation.title}** \`[${observation.category}]\`${supersededLabel}`);
+    if (observation.topic_key) {
+        lines.push(`  Topic key: \`${observation.topic_key}\``);
+    }
+    const contentLines = observation.content.split(/\r?\n/);
+    for (const contentLine of contentLines) {
+        lines.push(`  ${contentLine}`);
+    }
+}
+function buildSessionBriefMarkdown(content) {
+    const lines = [];
+    lines.push(`# Session Brief: ${content.project.name}`, "");
+    lines.push("## Project");
+    lines.push(`- Name: ${content.project.name}`);
+    lines.push(`- Root: \`${content.project.rootPath}\``);
+    if (content.project.id) {
+        lines.push(`- ID: \`${content.project.id}\``);
+    }
+    if (content.project.gitRemote) {
+        lines.push(`- Git remote: ${content.project.gitRemote}`);
+    }
+    lines.push("", "## Counts");
+    lines.push(`- Observations: ${formatCount(content.counts.observations)}`);
+    lines.push(`- Entities: ${formatCount(content.counts.entities)}`);
+    lines.push(`- Links: ${formatCount(content.counts.links)}`);
+    const keyedDecisions = content.activeDecisions.keyed;
+    const unkeyedDecisions = content.activeDecisions.unkeyed;
+    if (keyedDecisions.length > 0 || unkeyedDecisions.length > 0) {
+        lines.push("", "## Active Decisions");
+        for (const group of keyedDecisions) {
+            lines.push("", `### Topic: ${group.topicKey}`);
+            for (const decision of group.decisions) {
+                appendBriefObservation(lines, decision, false);
+            }
+        }
+        if (unkeyedDecisions.length > 0) {
+            lines.push("", "### Unkeyed decisions");
+            for (const decision of unkeyedDecisions) {
+                appendBriefObservation(lines, decision, false);
+            }
+        }
+    }
+    if (content.recentActivity.length > 0) {
+        lines.push("", "## Recent Activity");
+        for (const observation of content.recentActivity) {
+            appendBriefObservation(lines, observation, true);
+        }
+    }
+    if (content.symbols.length > 0) {
+        lines.push("", "## Indexed Symbols");
+        for (const symbol of content.symbols) {
+            lines.push(`- \`${symbol.identifier}\` (${symbol.entity_type}) — \`${symbol.file_path}\``);
+        }
+    }
+    if (content.related.length > 0) {
+        lines.push("", "## Related Symbols");
+        for (const neighbor of content.related) {
+            lines.push(`- \`${neighbor.entity.identifier}\` (${neighbor.entity.entity_type}) — \`${neighbor.entity.file_path}\``);
+        }
+    }
+    if (content.notes.length > 0) {
+        lines.push("", "## Notes");
+        for (const note of content.notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    return lines.join("\n").trimEnd();
+}
+function applySessionBriefBudget(markdown, budgetChars) {
+    if (markdown.length <= budgetChars) {
+        return { markdown, truncated: false };
+    }
+    const marker = `\n\n[truncated: output limited to ${budgetChars} characters; increase budgetChars to see the rest]`;
+    if (budgetChars <= marker.length) {
+        // Use a compact marker in small budgets so some useful content still fits.
+        // Even a one-character budget must remain bounded and visibly clipped.
+        const shortMarker = "[truncated]";
+        const contentBudget = budgetChars - shortMarker.length;
+        if (contentBudget > 0) {
+            return {
+                markdown: markdown.slice(0, contentBudget) + shortMarker,
+                truncated: true,
+            };
+        }
+        return {
+            markdown: (shortMarker.slice(0, Math.max(0, budgetChars - 1)) + "…").slice(0, budgetChars),
+            truncated: true,
+        };
+    }
+    const keep = budgetChars - marker.length;
+    return {
+        markdown: markdown.slice(0, keep) + marker,
+        truncated: true,
+    };
+}
+/**
+ * Shared deterministic Markdown renderer used by the library, MCP and CLI.
+ * It measures the complete output, including headings, notes, and the marker,
+ * against `content.budgetChars`.
+ */
+export function renderSessionBrief(content) {
+    return applySessionBriefBudget(buildSessionBriefMarkdown(content), content.budgetChars).markdown;
+}
+function assembleSessionBrief(db, project, projectId, selectedPaths, budgetChars, notes, expandGraph = true) {
+    let counts = {
+        observations: 0,
+        entities: 0,
+        links: 0,
+    };
+    let keyed = [];
+    let unkeyed = [];
+    let recentActivity = [];
+    let symbols = [];
+    const related = [];
+    if (projectId) {
+        const countObservations = db
+            .prepare("SELECT COUNT(*) as count FROM observations WHERE project_id = ?")
+            .get(projectId)?.count;
+        const countEntities = db
+            .prepare("SELECT COUNT(*) as count FROM entities WHERE project_id = ?")
+            .get(projectId)?.count;
+        const countLinks = db
+            .prepare(`SELECT COUNT(*) as count
+         FROM observation_entities oe
+         JOIN observations o ON o.id = oe.observation_id
+         WHERE o.project_id = ?`)
+            .get(projectId)?.count;
+        counts = {
+            observations: countObservations ?? 0,
+            entities: countEntities ?? 0,
+            links: countLinks ?? 0,
+        };
+        const decisions = db
+            .prepare(`SELECT id, project_id, category, title, content, topic_key, status,
+                superseded_by, created_at, updated_at
+         FROM observations
+         WHERE project_id = ? AND category = 'decision' AND status = 'active'
+         ORDER BY topic_key ASC, updated_at DESC, created_at DESC, rowid DESC`)
+            .all(projectId);
+        const keyedMap = new Map();
+        for (const decision of decisions) {
+            if (!decision.topic_key) {
+                unkeyed.push(decision);
+                continue;
+            }
+            const group = keyedMap.get(decision.topic_key);
+            if (group) {
+                group.push(decision);
+            }
+            else {
+                keyedMap.set(decision.topic_key, [decision]);
+            }
+        }
+        keyed = [...keyedMap.entries()]
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([topicKey, groupDecisions]) => ({
+            topicKey,
+            decisions: groupDecisions,
+        }));
+        const listedDecisionIds = decisions.map((decision) => decision.id);
+        const activityParams = [projectId];
+        let exclusion = "";
+        if (listedDecisionIds.length > 0) {
+            exclusion = ` AND id NOT IN (${listedDecisionIds.map(() => "?").join(",")})`;
+            activityParams.push(...listedDecisionIds);
+        }
+        activityParams.push(String(SESSION_BRIEF_RECENT_ACTIVITY_LIMIT));
+        recentActivity = db
+            .prepare(`SELECT id, project_id, category, title, content, topic_key, status,
+                superseded_by, created_at, updated_at
+         FROM observations
+         WHERE project_id = ?${exclusion}
+         ORDER BY updated_at DESC, created_at DESC, rowid DESC
+         LIMIT ?`)
+            .all(...activityParams);
+        if (selectedPaths.length > 0) {
+            const indexed = db
+                .prepare(`SELECT id, project_id, entity_type, identifier, file_path
+           FROM entities
+           WHERE project_id = ?
+           ORDER BY file_path ASC, identifier ASC, rowid ASC`)
+                .all(projectId);
+            symbols = indexed.filter((entity) => entityMatchesSelectedPaths(entity.file_path, selectedPaths, project.rootPath));
+            if (symbols.length === 0) {
+                notes.push("No indexed symbols matched the selected path(s).");
+            }
+        }
+        if (expandGraph && symbols.length > 0) {
+            const relatedById = new Map();
+            // The related section exists to add what the selected paths did not name.
+            // A neighbor that is itself path-selected is already printed under
+            // "Indexed Symbols", so listing it again would spend the brief's budget
+            // on a duplicate and read like a second, different symbol.
+            const listedSymbolIds = new Set(symbols.map((symbol) => symbol.id));
+            let traversedNeighbor = false;
+            for (const symbol of symbols) {
+                if (relatedById.size >= SESSION_BRIEF_RELATED_LIMIT)
+                    break;
+                const traversal = collectNeighbors(db, symbol, DEFAULT_NEIGHBOR_DEPTH, SESSION_BRIEF_RELATED_LIMIT);
+                for (const neighbor of traversal.neighbors) {
+                    traversedNeighbor = true;
+                    if (relatedById.size >= SESSION_BRIEF_RELATED_LIMIT)
+                        break;
+                    if (listedSymbolIds.has(neighbor.entity.id))
+                        continue;
+                    if (!relatedById.has(neighbor.entity.id)) {
+                        relatedById.set(neighbor.entity.id, neighbor);
+                    }
+                }
+            }
+            related.push(...relatedById.values());
+            // "No neighbors" is only true when the graph had none to offer; a graph
+            // whose neighbors were all already listed omits the section silently.
+            if (!traversedNeighbor) {
+                notes.push("No indexed dependency neighbors were found for the selected symbol(s).");
+            }
+        }
+    }
+    else {
+        notes.push("No project record was found in the database; project identity was derived from the selected root.");
+        if (selectedPaths.length > 0) {
+            notes.push("Indexed symbols are unavailable because no project record exists for the selected root.");
+        }
+    }
+    const content = {
+        project,
+        activeDecisions: { keyed, unkeyed },
+        recentActivity,
+        symbols,
+        related,
+        counts,
+        notes,
+        budgetChars,
+    };
+    const rendered = applySessionBriefBudget(buildSessionBriefMarkdown(content), budgetChars);
+    return {
+        ...content,
+        truncated: rendered.truncated,
+        markdown: rendered.markdown,
+    };
+}
+function buildUnavailableSessionBrief(rootPath, selectedPaths, budgetChars, cause, projectRow) {
+    const project = projectRow
+        ? sessionBriefProjectFromRow(projectRow)
+        : deriveSessionBriefProject(rootPath);
+    const notes = [
+        `Muninn memory is unavailable (${sessionBriefError(cause)}); returning an empty session brief.`,
+    ];
+    if (selectedPaths.length > 0) {
+        notes.push("Indexed symbols are unavailable because the database could not be read.");
+    }
+    const content = {
+        project,
+        activeDecisions: { keyed: [], unkeyed: [] },
+        recentActivity: [],
+        symbols: [],
+        related: [],
+        counts: { observations: null, entities: null, links: null },
+        notes,
+        budgetChars,
+    };
+    const rendered = applySessionBriefBudget(buildSessionBriefMarkdown(content), budgetChars);
+    return {
+        ...content,
+        truncated: rendered.truncated,
+        markdown: rendered.markdown,
+    };
+}
+/**
+ * Read-only bootstrap entry point for the CLI and MCP default server.
+ *
+ * It never uses `getDatabase()` or `ensureProject()`: an existing database is
+ * opened read-only, and any missing/inaccessible/corrupt/uninitialized file
+ * yields an empty brief with a cause in `notes` instead of throwing or creating
+ * state.
+ */
+export function readSessionBrief(request = {}) {
+    const rootPath = path.resolve(request.projectRoot ?? findGitRoot() ?? process.cwd());
+    const budgetChars = resolveSessionBriefBudget(request.budgetChars);
+    const selectedPaths = resolveSessionBriefPaths(request.paths, rootPath);
+    const expandGraph = request.expandGraph !== false;
+    if (request.db) {
+        try {
+            const projectRow = findSessionBriefProjectRow(request.db, rootPath);
+            const project = projectRow
+                ? sessionBriefProjectFromRow(projectRow)
+                : deriveSessionBriefProject(rootPath);
+            return assembleSessionBrief(request.db, project, projectRow?.id ?? null, selectedPaths, budgetChars, [], expandGraph);
+        }
+        catch (err) {
+            return buildUnavailableSessionBrief(rootPath, selectedPaths, budgetChars, err);
+        }
+    }
+    let db;
+    try {
+        db = getReadOnlyDatabase(request.dbPath, rootPath);
+    }
+    catch (err) {
+        return buildUnavailableSessionBrief(rootPath, selectedPaths, budgetChars, err);
+    }
+    try {
+        const projectRow = findSessionBriefProjectRow(db, rootPath);
+        const project = projectRow
+            ? sessionBriefProjectFromRow(projectRow)
+            : deriveSessionBriefProject(rootPath);
+        return assembleSessionBrief(db, project, projectRow?.id ?? null, selectedPaths, budgetChars, [], expandGraph);
+    }
+    catch (err) {
+        return buildUnavailableSessionBrief(rootPath, selectedPaths, budgetChars, err);
+    }
+    finally {
+        if (db.open) {
+            db.close();
+        }
+    }
+}
 export class MemoryService {
     _db;
     _currentProject;
@@ -229,12 +814,31 @@ export class MemoryService {
         const topicKey = input.topicKey !== undefined
             ? input.topicKey
             : (input.topic_key ?? null);
+        const supersedesTopicKey = input.supersedesTopicKey !== undefined
+            ? input.supersedesTopicKey
+            : (input.supersedes_topic_key ?? null);
         const observationId = crypto.randomUUID();
         return this._db.transaction(() => {
             this._db
                 .prepare(`INSERT INTO observations (id, project_id, category, title, content, topic_key)
            VALUES (?, ?, ?, ?, ?, ?)`)
                 .run(observationId, projectId, category, input.title.trim(), input.content, topicKey);
+            // Explicit decision replacement is part of the same transaction: either
+            // the new decision and every supersession link commit together or not at
+            // all. Exclude the new row so it never supersedes itself.
+            if (category === "decision" &&
+                supersedesTopicKey !== undefined &&
+                supersedesTopicKey !== null) {
+                this._db
+                    .prepare(`UPDATE observations
+             SET status = 'superseded', superseded_by = ?, updated_at = CURRENT_TIMESTAMP
+             WHERE project_id = ?
+               AND category = 'decision'
+               AND topic_key = ?
+               AND status = 'active'
+               AND id != ?`)
+                    .run(observationId, projectId, supersedesTopicKey, observationId);
+            }
             const symbols = input.symbols ?? [];
             const selectEntityStmt = this._db.prepare(`SELECT id, project_id, entity_type, identifier, file_path
          FROM entities
@@ -260,7 +864,7 @@ export class MemoryService {
                 linkStmt.run(observationId, entity.id);
             }
             const observation = this._db
-                .prepare(`SELECT id, project_id, category, title, content, topic_key, created_at, updated_at
+                .prepare(`SELECT id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at
            FROM observations
            WHERE id = ?`)
                 .get(observationId);
@@ -336,6 +940,9 @@ export class MemoryService {
             conditions.push("o.category = ?");
             params.push(options.category);
         }
+        if (!options.includeSuperseded && !options.include_superseded) {
+            conditions.push("o.status = 'active'");
+        }
         if (!options?.allProjects) {
             const explicitProjectId = options?.projectId !== undefined
                 ? options.projectId
@@ -361,6 +968,8 @@ export class MemoryService {
         o.title,
         o.content,
         o.topic_key,
+        o.status,
+        o.superseded_by,
         o.created_at,
         o.updated_at,
         bm25(observations_fts) AS rank
@@ -404,6 +1013,8 @@ export class MemoryService {
             title: r.title,
             content: r.content,
             topic_key: r.topic_key,
+            status: r.status,
+            superseded_by: r.superseded_by,
             created_at: r.created_at,
             updated_at: r.updated_at,
             rank: r.rank,
@@ -420,6 +1031,9 @@ export class MemoryService {
             conditions.push("category = ?");
             params.push(options.category);
         }
+        if (!options?.includeSuperseded && !options?.include_superseded) {
+            conditions.push("status = 'active'");
+        }
         const topicKey = options?.topicKey !== undefined ? options.topicKey : options?.topic_key;
         if (topicKey !== undefined && topicKey !== null) {
             conditions.push("topic_key = ?");
@@ -444,7 +1058,7 @@ export class MemoryService {
         const limit = Math.min(Math.max(1, parsedLimit), 500);
         params.push(limit);
         const sql = `
-      SELECT id, project_id, category, title, content, topic_key, created_at, updated_at
+      SELECT id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at
       FROM observations
       ${whereClause}
       ORDER BY updated_at DESC, created_at DESC
@@ -463,6 +1077,8 @@ export class MemoryService {
             title: r.title,
             content: r.content,
             topic_key: r.topic_key,
+            status: r.status,
+            superseded_by: r.superseded_by,
             created_at: r.created_at,
             updated_at: r.updated_at,
             entities: entityMap.get(r.id) ?? [],
@@ -494,7 +1110,7 @@ export class MemoryService {
             throw new Error("symbol is required for linkSymbol");
         }
         const observation = this._db
-            .prepare(`SELECT id, project_id, category, title, content, topic_key, created_at, updated_at
+            .prepare(`SELECT id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at
          FROM observations
          WHERE id = ?`)
             .get(observationId);
@@ -533,12 +1149,6 @@ export class MemoryService {
             };
         })();
     }
-    /**
-     * Escapes LIKE pattern special characters (%, _, \)
-     */
-    _escapeLikePattern(str) {
-        return str.replace(/[\\%_]/g, "\\$&");
-    }
     /**
      * Inspects a symbol in Muninn memory, returning its entity metadata,
      * incoming and outgoing dependencies, and linked observations.
@@ -548,35 +1158,7 @@ export class MemoryService {
             return null;
         }
         const targetProjectId = projectId ?? this._currentProject.id;
-        const query = symbol.trim();
-        // 1. Try exact match
-        let entity = this._db
-            .prepare(`SELECT id, project_id, entity_type, identifier, file_path
-         FROM entities
-         WHERE project_id = ? AND identifier = ?`)
-            .get(targetProjectId, query);
-        const escapedQuery = this._escapeLikePattern(query);
-        // 2. Try suffix match (e.g. searching 'run' matches 'src/app.ts::run', or 'login' matches 'src/auth.ts::AuthManager.login')
-        // Supports matching class methods with canonical format <relPath>::<ClassName>.<methodName> (REV-005, REV-008, SEC-004)
-        if (!entity) {
-            entity = this._db
-                .prepare(`SELECT id, project_id, entity_type, identifier, file_path
-           FROM entities
-           WHERE project_id = ? AND (identifier LIKE '%::' || ? ESCAPE '\\' OR identifier LIKE '%.' || ? ESCAPE '\\')
-           ORDER BY identifier ASC
-           LIMIT 1`)
-                .get(targetProjectId, escapedQuery, escapedQuery);
-        }
-        // 3. Try prefix match or file_path match
-        if (!entity) {
-            entity = this._db
-                .prepare(`SELECT id, project_id, entity_type, identifier, file_path
-           FROM entities
-           WHERE project_id = ? AND (identifier LIKE ? || '%' ESCAPE '\\' OR file_path = ?)
-           ORDER BY identifier ASC
-           LIMIT 1`)
-                .get(targetProjectId, escapedQuery, query);
-        }
+        const entity = resolveEntityByIdentifier(this._db, targetProjectId, symbol.trim());
         if (!entity) {
             return null;
         }
@@ -617,7 +1199,7 @@ export class MemoryService {
         }));
         // Fetch linked observations
         const observations = this._db
-            .prepare(`SELECT o.id, o.project_id, o.category, o.title, o.content, o.topic_key, o.created_at, o.updated_at
+            .prepare(`SELECT o.id, o.project_id, o.category, o.title, o.content, o.topic_key, o.status, o.superseded_by, o.created_at, o.updated_at
          FROM observations o
          JOIN observation_entities oe ON oe.observation_id = o.id
          WHERE oe.entity_id = ?
@@ -629,9 +1211,45 @@ export class MemoryService {
                 outgoing,
                 incoming,
             },
+            neighbors: collectNeighbors(this._db, entity, DEFAULT_NEIGHBOR_DEPTH, DEFAULT_NEIGHBOR_LIMIT),
             observations,
         };
     }
+    /**
+     * Returns bounded, deterministic graph neighbors for an indexed symbol.
+     *
+     * Traversal follows stored `entity_dependencies` edges in both directions,
+     * groups them by direction and relation, and never returns the same entity
+     * twice. Depth is clamped to 1–2 (default 1) and the result limit to 1–50
+     * (default 20).
+     */
+    neighbors(identifier, options) {
+        if (!identifier || typeof identifier !== "string" || !identifier.trim()) {
+            return null;
+        }
+        const entity = resolveEntityByIdentifier(this._db, this._currentProject.id, identifier.trim());
+        if (!entity) {
+            return null;
+        }
+        return collectNeighbors(this._db, entity, options?.depth, options?.limit);
+    }
+    /**
+     * Builds the bounded, deterministic session brief from the already-initialized
+     * service database. This method itself only reads; the standalone
+     * {@link readSessionBrief} entry point is the one that opens a database
+     * read-only and fails open when it is missing or unusable.
+     */
+    getSessionBrief(options) {
+        const budgetChars = resolveSessionBriefBudget(options?.budgetChars);
+        const selectedPaths = resolveSessionBriefPaths(options?.paths, this._currentProject.root_path);
+        const expandGraph = options?.expandGraph !== false;
+        try {
+            return assembleSessionBrief(this._db, sessionBriefProjectFromRow(this._currentProject), this._currentProject.id, selectedPaths, budgetChars, [], expandGraph);
+        }
+        catch (err) {
+            return buildUnavailableSessionBrief(this._currentProject.root_path, selectedPaths, budgetChars, err, this._currentProject);
+        }
+    }
     /**
      * Retrieves aggregate counts of projects, observations, entities, and links.
      */
@@ -713,7 +1331,7 @@ export class MemoryService {
         let entityRows;
         if (options?.allProjects === true) {
             observations = this._db
-                .prepare(`SELECT id, project_id, category, title, content, topic_key, created_at, updated_at
+                .prepare(`SELECT id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at
            FROM observations
            ORDER BY created_at ASC`)
                 .all();
@@ -726,7 +1344,7 @@ export class MemoryService {
         }
         else {
             observations = this._db
-                .prepare(`SELECT id, project_id, category, title, content, topic_key, created_at, updated_at
+                .prepare(`SELECT id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at
            FROM observations
            WHERE project_id = ?
            ORDER BY created_at ASC`)
@@ -821,8 +1439,8 @@ export class MemoryService {
         const importTx = this._db.transaction(() => {
             const checkObsStmt = this._db.prepare("SELECT id FROM observations WHERE id = ?");
             const checkProjStmt = this._db.prepare("SELECT id FROM projects WHERE id = ?");
-            const insertObsStmt = this._db.prepare(`INSERT INTO observations (id, project_id, category, title, content, topic_key, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+            const insertObsStmt = this._db.prepare(`INSERT INTO observations (id, project_id, category, title, content, topic_key, status, superseded_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
             const findEntityStmt = this._db.prepare(`SELECT id, project_id, entity_type, identifier, file_path
          FROM entities
          WHERE project_id = ? AND identifier = ?`);
@@ -864,7 +1482,9 @@ export class MemoryService {
                     : (record.topicKey ?? null);
                 const createdAt = record.created_at ?? new Date().toISOString();
                 const updatedAt = record.updated_at ?? createdAt;
-                insertObsStmt.run(record.id, projectId, category, record.title, record.content, topicKey, createdAt, updatedAt);
+                const status = record.status === "superseded" ? "superseded" : "active";
+                const supersededBy = record.superseded_by ?? record.supersededBy ?? null;
+                insertObsStmt.run(record.id, projectId, category, record.title, record.content, topicKey, status, supersededBy, createdAt, updatedAt);
                 const symbols = record.entities ?? record.symbols ?? [];
                 if (Array.isArray(symbols)) {
                     for (const sym of symbols) {