@mrc2204/agent-smart-memo 5.1.0 → 5.1.2

package/dist/db/slot-db.js

@@ -13,6 +13,7 @@ import { mkdirSync, existsSync } from "node:fs";
 import { buildChunkArtifacts } from "../core/ingest/ingest-pipeline.js";
 import { extractSemanticBlocks } from "../core/ingest/semantic-block-extractor.js";
 import { buildSymbolId } from "../core/ingest/ids.js";
+import { populateUniversalCodeGraphForFile } from "../core/graph/code-graph-populator.js";
 import { GraphDB } from "./graph-db.js";
 import { getSlotTTL } from "../shared/memory-config.js";
 import { resolveLegacyStateDirInput, resolveSlotDbDir } from "../shared/slotdb-path.js";
@@ -632,6 +633,278 @@ export class SlotDB {
             updated_at: row.updated_at,
         };
     }
+    deindexProject(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const now = new Date().toISOString();
+        const reason = input.reason == null ? null : String(input.reason).trim() || null;
+        const fileCountStmt = this.db.prepare(`SELECT COUNT(*) as cnt FROM file_index_state
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`);
+        const chunkCountStmt = this.db.prepare(`SELECT COUNT(*) as cnt FROM chunk_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`);
+        const symbolCountStmt = this.db.prepare(`SELECT COUNT(*) as cnt FROM symbol_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`);
+        const files = Number(fileCountStmt.get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        const chunks = Number(chunkCountStmt.get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        const symbols = Number(symbolCountStmt.get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        this.db.prepare(`UPDATE file_index_state
+       SET index_state = 'stale', active = 0, tombstone_at = ?, indexed_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`).run(now, now, scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`UPDATE chunk_registry
+       SET index_state = 'stale', active = 0, tombstone_at = ?, indexed_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`).run(now, now, scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`UPDATE symbol_registry
+       SET index_state = 'stale', active = 0, tombstone_at = ?, indexed_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`).run(now, now, scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`UPDATE projects
+       SET lifecycle_status = 'deindexed', updated_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(now, scopeUserId, scopeAgentId, projectId);
+        this.insertIndexRun(scopeUserId, scopeAgentId, {
+            run_id: randomUUID(),
+            project_id: projectId,
+            index_profile: "default",
+            trigger_type: "manual",
+            state: "indexed",
+            started_at: now,
+            finished_at: now,
+            error_message: reason ? `deindex:${reason}` : "deindex",
+        });
+        return {
+            project_id: projectId,
+            lifecycle_status: "deindexed",
+            deindexed_at: now,
+            reason,
+            affected: {
+                files,
+                chunks,
+                symbols,
+            },
+            searchable: false,
+        };
+    }
+    detachProject(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const reason = input.reason == null ? null : String(input.reason).trim() || null;
+        if (project.lifecycle_status !== "deindexed") {
+            this.deindexProject(scopeUserId, scopeAgentId, {
+                project_id: projectId,
+                reason: reason || "detach_precondition_deindex",
+            });
+        }
+        const now = new Date().toISOString();
+        const aliasesRemoved = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM project_aliases
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        const trackerMappingsRemoved = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM project_tracker_mappings
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        this.db.prepare(`DELETE FROM project_aliases
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`DELETE FROM project_tracker_mappings
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`UPDATE projects
+       SET lifecycle_status = 'detached', repo_root = NULL, repo_remote_primary = NULL, active_version = NULL, updated_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(now, scopeUserId, scopeAgentId, projectId);
+        return {
+            project_id: projectId,
+            lifecycle_status: "detached",
+            detached_at: now,
+            reason,
+            detached_fields: {
+                repo_root: project.repo_root != null,
+                repo_remote_primary: project.repo_remote_primary != null,
+                active_version: project.active_version != null,
+                aliases_removed: aliasesRemoved,
+                tracker_mappings_removed: trackerMappingsRemoved,
+            },
+            searchable: false,
+            next_actions: {
+                reattach_via_register_or_update: true,
+                reversible_by_re_register: true,
+            },
+        };
+    }
+    unregisterProject(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        const mode = input.mode || "safe";
+        if (mode !== "safe") {
+            throw new Error("project.unregister currently supports mode='safe' only");
+        }
+        if (input.confirm !== true) {
+            throw new Error("project.unregister requires explicit confirm=true");
+        }
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const reason = input.reason == null ? null : String(input.reason).trim() || null;
+        let deindexedFirst = false;
+        if (project.lifecycle_status !== "deindexed") {
+            this.deindexProject(scopeUserId, scopeAgentId, {
+                project_id: projectId,
+                reason: reason || "unregister_precondition_deindex",
+            });
+            deindexedFirst = true;
+        }
+        const now = new Date().toISOString();
+        const aliasesRemoved = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM project_aliases
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        const trackerMappingsRemoved = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM project_tracker_mappings
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        this.db.prepare(`DELETE FROM project_aliases
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`DELETE FROM project_tracker_mappings
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+        this.db.prepare(`UPDATE projects
+       SET lifecycle_status = 'disabled', repo_root = NULL, repo_remote_primary = NULL, active_version = NULL, updated_at = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(now, scopeUserId, scopeAgentId, projectId);
+        this.upsertProjectRegistrationState(scopeUserId, scopeAgentId, {
+            project_id: projectId,
+            registration_status: "draft",
+            validation_status: "warn",
+            validation_notes: reason ? `unregistered:${reason}` : "unregistered",
+            completeness_score: 0,
+            missing_required_fields: ["project_alias", "repo_root"],
+            last_validated_at: now,
+        });
+        return {
+            project_id: projectId,
+            lifecycle_status: "disabled",
+            unregistered_at: now,
+            mode,
+            reason,
+            detached_fields: {
+                aliases_removed: aliasesRemoved,
+                tracker_mappings_removed: trackerMappingsRemoved,
+            },
+            registration_state: {
+                registration_status: "draft",
+                validation_status: "warn",
+            },
+            searchable: false,
+            audit: {
+                deindexed_first: deindexedFirst,
+                confirm_required: true,
+            },
+        };
+    }
+    purgePreviewProject(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const countBy = (table) => Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM ${table}
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+        const canPurge = project.lifecycle_status === "disabled";
+        const reason = canPurge
+            ? "safe to purge: lifecycle_status is disabled and explicit confirm is still required"
+            : `purge blocked: lifecycle_status must be disabled (current=${project.lifecycle_status})`;
+        return {
+            project_id: projectId,
+            current_lifecycle_status: project.lifecycle_status,
+            purge_guard: {
+                destructive: true,
+                allowed: canPurge,
+                reason,
+                requires_lifecycle_status: "disabled",
+                requires_confirm: true,
+            },
+            affected: {
+                project_row: 1,
+                aliases: countBy("project_aliases"),
+                tracker_mappings: countBy("project_tracker_mappings"),
+                registration_state: countBy("project_registration_state"),
+                index_runs: countBy("index_runs"),
+                watch_state: countBy("project_index_watch_state"),
+                file_index_state: countBy("file_index_state"),
+                chunk_registry: countBy("chunk_registry"),
+                symbol_registry: countBy("symbol_registry"),
+                task_registry: countBy("task_registry"),
+            },
+            previewed_at: new Date().toISOString(),
+        };
+    }
+    purgeProject(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        if (input.confirm !== true) {
+            throw new Error("project.purge requires explicit confirm=true");
+        }
+        const preview = this.purgePreviewProject(scopeUserId, scopeAgentId, { project_id: projectId });
+        if (!preview.purge_guard.allowed) {
+            throw new Error(preview.purge_guard.reason);
+        }
+        const now = new Date().toISOString();
+        const reason = input.reason == null ? null : String(input.reason).trim() || null;
+        const deleted = {
+            project_row: 1,
+            aliases: preview.affected.aliases,
+            tracker_mappings: preview.affected.tracker_mappings,
+            registration_state: preview.affected.registration_state,
+            index_runs: preview.affected.index_runs,
+            watch_state: preview.affected.watch_state,
+            file_index_state: preview.affected.file_index_state,
+            chunk_registry: preview.affected.chunk_registry,
+            symbol_registry: preview.affected.symbol_registry,
+            task_registry: preview.affected.task_registry,
+        };
+        this.db.exec("BEGIN");
+        try {
+            this.db.prepare(`DELETE FROM project_aliases
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM project_tracker_mappings
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM project_registration_state
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM index_runs
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM project_index_watch_state
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM file_index_state
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM chunk_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM symbol_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM task_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.prepare(`DELETE FROM projects
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`).run(scopeUserId, scopeAgentId, projectId);
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+        return {
+            project_id: projectId,
+            lifecycle_status: "purged",
+            purged_at: now,
+            reason,
+            deleted,
+            searchable: false,
+            recoverable: false,
+            audit: {
+                confirm_required: true,
+                allowed_from_lifecycle_status: "disabled",
+            },
+        };
+    }
     reindexProjectByDiff(scopeUserId, scopeAgentId, input) {
         const now = new Date().toISOString();
         const runId = randomUUID();
@@ -725,7 +998,7 @@ export class SlotDB {
                         });
                     }
                     for (const block of blocks) {
-                        if (!block.symbol_name || !["function", "class", "method"].includes(block.kind))
+                        if (!block.symbol_name || !["function", "class", "method", "tool"].includes(block.kind))
                             continue;
                         const symbolFqn = block.semantic_path || `${block.kind}:${block.symbol_name}`;
                         this.upsertSymbolRegistry(scopeUserId, scopeAgentId, {
@@ -744,6 +1017,14 @@ export class SlotDB {
                             indexed_at: nowIso,
                         });
                     }
+                    populateUniversalCodeGraphForFile(this.graph, scopeUserId, scopeAgentId, {
+                        projectId: input.project_id,
+                        relativePath,
+                        module: item?.module || null,
+                        language: language || "text",
+                        content,
+                        blocks,
+                    });
                 }
             }
             for (const relativePath of deleted) {
@@ -758,7 +1039,14 @@ export class SlotDB {
                 last_checksum_snapshot: checksumSnapshotRecord,
                 updated_at: nowIso,
             });
+            this.db.prepare(`UPDATE projects
+         SET lifecycle_status = 'active', updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND lifecycle_status = 'deindexed'`).run(nowIso, scopeUserId, scopeAgentId, input.project_id);
             this.finishIndexRun(scopeUserId, scopeAgentId, runId, "indexed", null, nowIso);
+            this.db.prepare(`UPDATE projects
+         SET lifecycle_status = 'active', updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?
+           AND lifecycle_status = 'deindexed'`).run(nowIso, scopeUserId, scopeAgentId, input.project_id);
             return {
                 run_id: runId,
                 project_id: input.project_id,
@@ -932,6 +1220,65 @@ export class SlotDB {
         if (!project) {
             throw new Error(`project_id '${projectId}' is not registered`);
         }
+        const isSearchDisabled = ["deindexed", "detached", "disabled", "purged"].includes(project.lifecycle_status);
+        if (isSearchDisabled) {
+            const files = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM file_index_state
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tombstone_at IS NOT NULL`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+            const chunks = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM chunk_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tombstone_at IS NOT NULL`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+            const symbols = Number(this.db.prepare(`SELECT COUNT(*) as cnt FROM symbol_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tombstone_at IS NOT NULL`).get(scopeUserId, scopeAgentId, projectId)?.cnt || 0);
+            const taskContextSelector = {
+                ...(input.task_context?.task_id ? { task_id: String(input.task_context.task_id).trim() } : {}),
+                ...(input.task_context?.tracker_issue_key ? { tracker_issue_key: String(input.task_context.tracker_issue_key).trim() } : {}),
+                ...(input.task_context?.task_title ? { task_title: String(input.task_context.task_title).trim() } : {}),
+            };
+            const reasonByLifecycle = {
+                deindexed: "project is deindexed; retrieval is disabled until reindex",
+                detached: "project is detached; retrieval is disabled until project is re-attached and reindexed",
+                disabled: "project is unregistered/disabled; retrieval is disabled until re-registration",
+                purged: "project is purged; retrieval is disabled",
+            };
+            return {
+                query,
+                project_id: projectId,
+                project_lifecycle_status: project.lifecycle_status,
+                searchable: false,
+                tombstone_summary: { files, chunks, symbols },
+                count: 0,
+                task_lineage_context: null,
+                task_context_resolution: {
+                    status: Object.keys(taskContextSelector).length > 0 ? "selector_not_resolved" : "not_requested",
+                    ...(Object.keys(taskContextSelector).length > 0
+                        ? { reason: reasonByLifecycle[project.lifecycle_status] || "project lifecycle disables retrieval" }
+                        : {}),
+                    selector: taskContextSelector,
+                    recoverable: project.lifecycle_status !== "purged",
+                },
+                results: [],
+                debug: input.debug
+                    ? {
+                        query_intent: {
+                            looks_code_intent: false,
+                            looks_identifier_query: false,
+                            query_tokens: [],
+                        },
+                        candidate_counts: {
+                            file_index_state: 0,
+                            symbol_registry: 0,
+                            chunk_registry: 0,
+                            task_registry: 0,
+                        },
+                        top_candidates: {
+                            file_index_state: [],
+                            symbol_registry: [],
+                            chunk_registry: [],
+                            task_registry: [],
+                        },
+                    }
+                    : undefined,
+            };
+        }
         const limit = Math.min(Math.max(Number(input.limit || 10), 1), 50);
         const queryLc = query.toLowerCase();
         const queryTokens = Array.from(new Set(queryLc.split(/[^a-z0-9._/-]+/i).map((t) => t.trim()).filter(Boolean)));
@@ -946,17 +1293,65 @@ export class SlotDB {
             }
             return matched / queryTokens.length;
         };
+        const exactMatchScore = (candidate) => {
+            const value = String(candidate || '').trim().toLowerCase();
+            if (!value)
+                return 0;
+            if (value === queryLc)
+                return 1;
+            if (value.endsWith(`.${queryLc}`))
+                return 0.92;
+            if (value.includes(`/${queryLc}`) || value.includes(`:${queryLc}`) || value.includes(`#${queryLc}`))
+                return 0.78;
+            return 0;
+        };
+        const codeIntentHints = ['function', 'class', 'method', 'symbol', 'route', 'endpoint', 'extractor', 'registry', 'chunk', 'snippet', 'code'];
+        const looksCodeIntent = codeIntentHints.some((hint) => queryLc.includes(hint)) || query.includes('/') || query.includes('_');
+        const looksIdentifierQuery = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(query) ||
+            /^[a-zA-Z_][a-zA-Z0-9_.#:-]*$/.test(query) ||
+            query.includes('::') ||
+            query.includes('.') ||
+            query.includes('_');
         const taskContextInput = input.task_context;
+        const taskContextSelector = {
+            ...(taskContextInput?.task_id ? { task_id: String(taskContextInput.task_id).trim() } : {}),
+            ...(taskContextInput?.tracker_issue_key ? { tracker_issue_key: String(taskContextInput.tracker_issue_key).trim() } : {}),
+            ...(taskContextInput?.task_title ? { task_title: String(taskContextInput.task_title).trim() } : {}),
+        };
         let lineageContext = null;
-        if (taskContextInput && (taskContextInput.task_id || taskContextInput.tracker_issue_key || taskContextInput.task_title)) {
-            lineageContext = this.getTaskLineageContext(scopeUserId, scopeAgentId, {
-                project_id: projectId,
-                task_id: taskContextInput.task_id,
-                tracker_issue_key: taskContextInput.tracker_issue_key,
-                task_title: taskContextInput.task_title,
-                include_parent_chain: taskContextInput.include_parent_chain,
-                include_related: taskContextInput.include_related,
-            });
+        let taskContextResolution = {
+            status: "not_requested",
+            selector: taskContextSelector,
+            recoverable: false,
+        };
+        if (Object.keys(taskContextSelector).length > 0) {
+            try {
+                lineageContext = this.getTaskLineageContext(scopeUserId, scopeAgentId, {
+                    project_id: projectId,
+                    task_id: taskContextInput?.task_id,
+                    tracker_issue_key: taskContextInput?.tracker_issue_key,
+                    task_title: taskContextInput?.task_title,
+                    include_parent_chain: taskContextInput?.include_parent_chain,
+                    include_related: taskContextInput?.include_related,
+                });
+                taskContextResolution = {
+                    status: "resolved",
+                    selector: taskContextSelector,
+                    recoverable: false,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!message.includes("task lineage focus not found for provided selector")) {
+                    throw error;
+                }
+                taskContextResolution = {
+                    status: "selector_not_resolved",
+                    reason: "task lineage focus not found for provided selector",
+                    selector: taskContextSelector,
+                    recoverable: true,
+                };
+            }
         }
         const lexicalPathPrefix = this.normalizeStringArray(input.path_prefix).map((p) => this.normalizeRelativePath(p)).filter(Boolean);
         const lexicalModules = new Set(this.normalizeStringArray(input.module).map((s) => s.toLowerCase()));
@@ -974,6 +1369,19 @@ export class SlotDB {
             }
         }
         const results = [];
+        const debugEnabled = input.debug === true;
+        const debugBuckets = {
+            file_index_state: [],
+            symbol_registry: [],
+            chunk_registry: [],
+            task_registry: [],
+        };
+        const pushDebug = (bucket, entry) => {
+            if (!debugEnabled)
+                return;
+            debugBuckets[bucket].push(entry);
+        };
+        const symbolRowsById = new Map();
         const fileStmt = this.db.prepare(`SELECT * FROM file_index_state
        WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`);
         const fileRows = fileStmt.all(scopeUserId, scopeAgentId, projectId);
@@ -998,10 +1406,28 @@ export class SlotDB {
             score += tokenScore(text) * 0.25;
             if (lineageContext && lineageContext.touched_files.includes(relativePath))
                 score += 0.35;
-            if (relativePath.includes("README") || relativePath.includes("docs/"))
+            if (looksCodeIntent) {
+                if (relativePath.includes('/docs/') || relativePath.startsWith('docs/') || relativePath.includes('README'))
+                    score -= 0.18;
+                if (relativePath.startsWith('src/') || relativePath.startsWith('tests/'))
+                    score += 0.14;
+            }
+            else if (relativePath.includes("README") || relativePath.includes("docs/")) {
                 score += 0.05;
+            }
+            if (looksIdentifierQuery) {
+                score -= 0.12;
+            }
             if (score <= 0.08)
                 continue;
+            pushDebug('file_index_state', {
+                relative_path: relativePath,
+                score: Number(score.toFixed(4)),
+                module: moduleName,
+                language,
+                text_exact: text.includes(queryLc),
+                token_score: Number(tokenScore(text).toFixed(4)),
+            });
             results.push({
                 source: "file_index_state",
                 id: String(row.file_id),
@@ -1023,6 +1449,7 @@ export class SlotDB {
             const symbolName = String(row.symbol_name || "");
             const symbolKind = String(row.symbol_kind || "");
             const symbolFqn = String(row.symbol_fqn || "");
+            symbolRowsById.set(String(row.symbol_id), row);
             if (lexicalPathPrefix.length > 0 && !lexicalPathPrefix.some((prefix) => relativePath.startsWith(prefix)))
                 continue;
             if (lexicalModules.size > 0 && !moduleName)
@@ -1038,12 +1465,37 @@ export class SlotDB {
             if (text.includes(queryLc))
                 score += 0.62;
             score += tokenScore(text) * 0.35;
+            score += exactMatchScore(symbolName) * 1.35;
+            score += exactMatchScore(symbolFqn) * 1.1;
+            if (looksIdentifierQuery) {
+                if (symbolName.toLowerCase() === queryLc)
+                    score += 1.8;
+                else if (symbolFqn.toLowerCase() === queryLc)
+                    score += 1.5;
+                else if (symbolFqn.toLowerCase().endsWith(`.${queryLc}`))
+                    score += 1.1;
+            }
             if (lineageContext && lineageContext.touched_symbols.includes(symbolName))
                 score += 0.3;
             if (lineageContext && lineageContext.touched_files.includes(relativePath))
                 score += 0.12;
+            if (looksCodeIntent && (relativePath.startsWith('src/') || relativePath.startsWith('tests/')))
+                score += 0.08;
+            if (looksIdentifierQuery)
+                score += 0.18;
             if (score <= 0.08)
                 continue;
+            pushDebug('symbol_registry', {
+                relative_path: relativePath,
+                symbol_name: symbolName,
+                symbol_fqn: symbolFqn,
+                symbol_kind: symbolKind,
+                score: Number(score.toFixed(4)),
+                exact_symbol: symbolName.toLowerCase() === queryLc,
+                exact_fqn: symbolFqn.toLowerCase() === queryLc,
+                suffix_fqn: symbolFqn.toLowerCase().endsWith(`.${queryLc}`),
+                token_score: Number(tokenScore(text).toFixed(4)),
+            });
             results.push({
                 source: "symbol_registry",
                 id: String(row.symbol_id),
@@ -1064,24 +1516,53 @@ export class SlotDB {
             const relativePath = String(row.relative_path || "");
             const chunkKind = String(row.chunk_kind || "");
             const symbolId = row.symbol_id ? String(row.symbol_id) : null;
+            const symbolRow = symbolId ? symbolRowsById.get(symbolId) : null;
+            const symbolName = symbolRow ? String(symbolRow.symbol_name || '') : '';
+            const symbolFqn = symbolRow ? String(symbolRow.symbol_fqn || '') : '';
             if (lexicalPathPrefix.length > 0 && !lexicalPathPrefix.some((prefix) => relativePath.startsWith(prefix)))
                 continue;
-            const text = `${relativePath} ${chunkKind} ${symbolId || ""}`.toLowerCase();
+            const text = `${relativePath} ${chunkKind} ${symbolId || ""} ${symbolName} ${symbolFqn}`.toLowerCase();
             let score = 0;
             if (text.includes(queryLc))
                 score += 0.6;
             score += tokenScore(text) * 0.4;
+            score += exactMatchScore(symbolName) * 0.9;
+            score += exactMatchScore(symbolFqn) * 0.7;
+            if (looksIdentifierQuery) {
+                if (symbolName.toLowerCase() === queryLc)
+                    score += 1.0;
+                else if (symbolFqn.toLowerCase() === queryLc)
+                    score += 0.85;
+            }
             if (lineageContext && lineageContext.touched_files.includes(relativePath))
                 score += 0.15;
+            if (looksCodeIntent) {
+                if (relativePath.includes('/docs/') || relativePath.startsWith('docs/') || relativePath.includes('README'))
+                    score -= 0.14;
+                if (relativePath.startsWith('src/') || relativePath.startsWith('tests/'))
+                    score += 0.1;
+            }
+            if (looksIdentifierQuery)
+                score += 0.12;
             if (score <= 0.08)
                 continue;
+            pushDebug('chunk_registry', {
+                relative_path: relativePath,
+                chunk_kind: chunkKind,
+                symbol_name: symbolName || null,
+                symbol_fqn: symbolFqn || null,
+                score: Number(score.toFixed(4)),
+                exact_symbol: symbolName ? symbolName.toLowerCase() === queryLc : false,
+                token_score: Number(tokenScore(text).toFixed(4)),
+            });
             results.push({
                 source: "chunk_registry",
                 id: String(row.chunk_id),
                 score,
                 project_id: projectId,
                 relative_path: relativePath,
-                snippet: `chunk ${chunkKind} in ${relativePath}`,
+                symbol_name: symbolName || undefined,
+                snippet: symbolName ? `chunk ${chunkKind} for symbol ${symbolName} in ${relativePath}` : `chunk ${chunkKind} in ${relativePath}`,
             });
         }
         const taskStmt = this.db.prepare(`SELECT * FROM task_registry
@@ -1123,6 +1604,13 @@ export class SlotDB {
             }
             if (score <= 0.08)
                 continue;
+            pushDebug('task_registry', {
+                task_id: task.task_id,
+                tracker_issue_key: task.tracker_issue_key,
+                task_title: task.task_title,
+                score: Number(score.toFixed(4)),
+                token_score: Number(tokenScore(text).toFixed(4)),
+            });
             results.push({
                 source: "task_registry",
                 id: task.task_id,
@@ -1141,9 +1629,208 @@ export class SlotDB {
         return {
             query,
             project_id: projectId,
+            project_lifecycle_status: project.lifecycle_status,
+            searchable: true,
             count: ranked.length,
             task_lineage_context: lineageContext,
+            task_context_resolution: taskContextResolution,
             results: ranked,
+            debug: debugEnabled
+                ? {
+                    query_intent: {
+                        looks_code_intent: looksCodeIntent,
+                        looks_identifier_query: looksIdentifierQuery,
+                        query_tokens: queryTokens,
+                    },
+                    candidate_counts: {
+                        file_index_state: debugBuckets.file_index_state.length,
+                        symbol_registry: debugBuckets.symbol_registry.length,
+                        chunk_registry: debugBuckets.chunk_registry.length,
+                        task_registry: debugBuckets.task_registry.length,
+                    },
+                    top_candidates: {
+                        file_index_state: debugBuckets.file_index_state.sort((a, b) => Number(b.score || 0) - Number(a.score || 0)).slice(0, 8),
+                        symbol_registry: debugBuckets.symbol_registry.sort((a, b) => Number(b.score || 0) - Number(a.score || 0)).slice(0, 8),
+                        chunk_registry: debugBuckets.chunk_registry.sort((a, b) => Number(b.score || 0) - Number(a.score || 0)).slice(0, 8),
+                        task_registry: debugBuckets.task_registry.sort((a, b) => Number(b.score || 0) - Number(a.score || 0)).slice(0, 8),
+                    },
+                }
+                : undefined,
+        };
+    }
+    queryProjectChangeOverlay(scopeUserId, scopeAgentId, input) {
+        let lineage = null;
+        const taskIdSelector = String(input.task_id || "").trim();
+        const trackerSelector = String(input.tracker_issue_key || "").trim();
+        const taskTitleSelector = String(input.task_title || "").trim();
+        const selector = {
+            ...(taskIdSelector ? { task_id: taskIdSelector } : {}),
+            ...(trackerSelector ? { tracker_issue_key: trackerSelector } : {}),
+            ...(taskTitleSelector ? { task_title: taskTitleSelector } : {}),
+        };
+        try {
+            lineage = this.getTaskLineageContext(scopeUserId, scopeAgentId, {
+                project_id: input.project_id,
+                task_id: input.task_id,
+                tracker_issue_key: input.tracker_issue_key,
+                task_title: input.task_title,
+                include_related: input.include_related,
+                include_parent_chain: input.include_parent_chain,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!message.includes("task lineage focus not found for provided selector")) {
+                throw error;
+            }
+            const unresolvedTaskId = taskIdSelector || `unresolved:${trackerSelector || taskTitleSelector || "selector"}`;
+            const unresolvedTitle = taskTitleSelector || "Unresolved task lineage selector";
+            return {
+                status: "selector_not_resolved",
+                reason: "task lineage focus not found for provided selector",
+                selector,
+                recoverable: true,
+                project_id: input.project_id,
+                focus: {
+                    task_id: unresolvedTaskId,
+                    task_title: unresolvedTitle,
+                    tracker_issue_key: trackerSelector || null,
+                },
+                changed_files: [],
+                related_symbols: [],
+                commit_refs: [],
+            };
+        }
+        const changedFiles = this.uniqueSorted((lineage.touched_files || []).map((p) => this.normalizeRelativePath(p)).filter(Boolean));
+        const relatedSymbolsMap = new Map();
+        for (const symbolName of lineage.touched_symbols || []) {
+            const normalized = String(symbolName || "").trim();
+            if (!normalized)
+                continue;
+            const key = `task_registry:${normalized}`;
+            if (!relatedSymbolsMap.has(key)) {
+                relatedSymbolsMap.set(key, {
+                    symbol_name: normalized,
+                    source: "task_registry",
+                });
+            }
+        }
+        if (changedFiles.length > 0) {
+            const placeholders = changedFiles.map(() => "?").join(",");
+            const stmt = this.db.prepare(`SELECT symbol_name, symbol_kind, symbol_fqn, relative_path
+         FROM symbol_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1
+           AND relative_path IN (${placeholders})
+         ORDER BY indexed_at DESC, symbol_name ASC`);
+            const rows = stmt.all(scopeUserId, scopeAgentId, input.project_id, ...changedFiles);
+            for (const row of rows) {
+                const symbolName = String(row.symbol_name || "").trim();
+                if (!symbolName)
+                    continue;
+                const relPath = row.relative_path ? String(row.relative_path) : undefined;
+                const symbolFqn = row.symbol_fqn ? String(row.symbol_fqn) : undefined;
+                const key = `symbol_registry:${symbolName}:${symbolFqn || ""}:${relPath || ""}`;
+                if (!relatedSymbolsMap.has(key)) {
+                    relatedSymbolsMap.set(key, {
+                        symbol_name: symbolName,
+                        symbol_kind: row.symbol_kind ? String(row.symbol_kind) : undefined,
+                        symbol_fqn: symbolFqn,
+                        relative_path: relPath,
+                        source: "symbol_registry",
+                    });
+                }
+            }
+        }
+        return {
+            status: "ok",
+            selector,
+            recoverable: false,
+            project_id: input.project_id,
+            focus: lineage.focus,
+            changed_files: changedFiles,
+            related_symbols: Array.from(relatedSymbolsMap.values()),
+            commit_refs: this.uniqueSorted(lineage.commit_refs || []),
+        };
+    }
+    getProjectFeaturePackProjectOnboardingIndexingSnapshot(scopeUserId, scopeAgentId, projectId) {
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const aliases = this.listProjects(scopeUserId, scopeAgentId)
+            .find((row) => row.project.project_id === projectId)?.aliases || [];
+        const registration = this.getProjectRegistrationState(scopeUserId, scopeAgentId, projectId);
+        const trackerStmt = this.db.prepare(`SELECT * FROM project_tracker_mappings
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?
+       ORDER BY updated_at DESC`);
+        const trackerMappings = trackerStmt.all(scopeUserId, scopeAgentId, projectId).map((row) => ({
+            id: String(row.id),
+            project_id: String(row.project_id),
+            scope_user_id: String(row.scope_user_id),
+            scope_agent_id: String(row.scope_agent_id),
+            tracker_type: String(row.tracker_type),
+            tracker_space_key: row.tracker_space_key ? String(row.tracker_space_key) : null,
+            tracker_project_id: row.tracker_project_id ? String(row.tracker_project_id) : null,
+            default_epic_key: row.default_epic_key ? String(row.default_epic_key) : null,
+            board_key: row.board_key ? String(row.board_key) : null,
+            active_version: row.active_version ? String(row.active_version) : null,
+            external_project_url: row.external_project_url ? String(row.external_project_url) : null,
+            created_at: String(row.created_at),
+            updated_at: String(row.updated_at),
+        }));
+        const fileStmt = this.db.prepare(`SELECT relative_path, module, language
+       FROM file_index_state
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1
+       ORDER BY indexed_at DESC, relative_path ASC
+       LIMIT 12`);
+        const recentFiles = fileStmt.all(scopeUserId, scopeAgentId, projectId).map((row) => ({
+            relative_path: String(row.relative_path),
+            module: row.module ? String(row.module) : null,
+            language: row.language ? String(row.language) : null,
+        }));
+        const symbolStmt = this.db.prepare(`SELECT symbol_name, symbol_kind, symbol_fqn, relative_path
+       FROM symbol_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1
+       ORDER BY indexed_at DESC, symbol_name ASC
+       LIMIT 16`);
+        const recentSymbols = symbolStmt.all(scopeUserId, scopeAgentId, projectId).map((row) => ({
+            symbol_name: String(row.symbol_name),
+            symbol_kind: String(row.symbol_kind),
+            symbol_fqn: String(row.symbol_fqn),
+            relative_path: String(row.relative_path),
+        }));
+        const taskStmt = this.db.prepare(`SELECT task_id, task_title, tracker_issue_key, task_status
+       FROM task_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?
+       ORDER BY updated_at DESC
+       LIMIT 12`);
+        const recentTasks = taskStmt.all(scopeUserId, scopeAgentId, projectId).map((row) => ({
+            task_id: String(row.task_id),
+            task_title: String(row.task_title),
+            tracker_issue_key: row.tracker_issue_key ? String(row.tracker_issue_key) : null,
+            task_status: row.task_status ? String(row.task_status) : null,
+        }));
+        const runStmt = this.db.prepare(`SELECT run_id, trigger_type, state, started_at, finished_at
+       FROM index_runs
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?
+       ORDER BY started_at DESC
+       LIMIT 8`);
+        const recentIndexRuns = runStmt.all(scopeUserId, scopeAgentId, projectId).map((row) => ({
+            run_id: String(row.run_id),
+            trigger_type: String(row.trigger_type),
+            state: String(row.state),
+            started_at: String(row.started_at),
+            finished_at: row.finished_at ? String(row.finished_at) : null,
+        }));
+        return {
+            project,
+            aliases,
+            registration,
+            tracker_mappings: trackerMappings,
+            recent_files: recentFiles,
+            recent_symbols: recentSymbols,
+            recent_tasks: recentTasks,
+            recent_index_runs: recentIndexRuns,
         };
     }
     runLegacyCompatibilityBackfill(scopeUserId, scopeAgentId, input = {}) {