@mrc2204/agent-smart-memo 4.1.3 → 5.0.1

package/dist/db/slot-db.js

@@ -77,6 +77,221 @@ export class SlotDB {
         this.db.exec(`
       CREATE INDEX IF NOT EXISTS idx_slots_updated
         ON slots(updated_at DESC)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS projects (
+        project_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_name TEXT NOT NULL,
+        repo_root TEXT,
+        repo_remote_primary TEXT,
+        active_version TEXT,
+        lifecycle_status TEXT NOT NULL DEFAULT 'active',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_user_id, scope_agent_id, project_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_scope_repo_root
+      ON projects(scope_user_id, scope_agent_id, repo_root)
+      WHERE repo_root IS NOT NULL AND repo_root != ''
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS project_aliases (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_alias TEXT NOT NULL,
+        is_primary INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(scope_user_id, scope_agent_id, project_alias)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_project_aliases_project
+      ON project_aliases(scope_user_id, scope_agent_id, project_id)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS project_tracker_mappings (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        tracker_type TEXT NOT NULL,
+        tracker_space_key TEXT,
+        tracker_project_id TEXT,
+        default_epic_key TEXT,
+        board_key TEXT,
+        active_version TEXT,
+        external_project_url TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(scope_user_id, scope_agent_id, project_id, tracker_type)
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS project_registration_state (
+        project_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        registration_status TEXT NOT NULL,
+        validation_status TEXT NOT NULL,
+        validation_notes TEXT,
+        completeness_score INTEGER NOT NULL DEFAULT 0,
+        missing_required_fields TEXT,
+        last_validated_at TEXT,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_user_id, scope_agent_id, project_id)
+      )
+    `);
+        // ASM-76 (v5.1) bootstrap: metadata/control plane schema for ingest & reindex lifecycle.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS index_runs (
+        run_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        index_profile TEXT NOT NULL,
+        trigger_type TEXT NOT NULL,
+        state TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        error_message TEXT,
+        PRIMARY KEY (scope_user_id, scope_agent_id, run_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_index_runs_project_state
+      ON index_runs(scope_user_id, scope_agent_id, project_id, state, started_at)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS file_index_state (
+        file_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        relative_path TEXT NOT NULL,
+        module TEXT,
+        language TEXT,
+        checksum TEXT NOT NULL,
+        last_commit_sha TEXT,
+        index_state TEXT NOT NULL,
+        active INTEGER NOT NULL DEFAULT 1,
+        tombstone_at TEXT,
+        indexed_at TEXT,
+        PRIMARY KEY (scope_user_id, scope_agent_id, file_id),
+        UNIQUE(scope_user_id, scope_agent_id, project_id, relative_path)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_file_state_project_path
+      ON file_index_state(scope_user_id, scope_agent_id, project_id, relative_path)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS chunk_registry (
+        chunk_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        file_id TEXT,
+        relative_path TEXT,
+        chunk_kind TEXT NOT NULL,
+        symbol_id TEXT,
+        task_id TEXT,
+        checksum TEXT NOT NULL,
+        qdrant_point_id TEXT,
+        index_state TEXT NOT NULL,
+        active INTEGER NOT NULL DEFAULT 1,
+        tombstone_at TEXT,
+        indexed_at TEXT,
+        PRIMARY KEY (scope_user_id, scope_agent_id, chunk_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_chunk_project_state
+      ON chunk_registry(scope_user_id, scope_agent_id, project_id, index_state, active)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS symbol_registry (
+        symbol_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        relative_path TEXT NOT NULL,
+        module TEXT,
+        language TEXT NOT NULL,
+        symbol_name TEXT NOT NULL,
+        symbol_fqn TEXT NOT NULL,
+        symbol_kind TEXT NOT NULL,
+        signature_hash TEXT,
+        index_state TEXT NOT NULL,
+        active INTEGER NOT NULL DEFAULT 1,
+        tombstone_at TEXT,
+        indexed_at TEXT,
+        PRIMARY KEY (scope_user_id, scope_agent_id, symbol_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_symbol_project_module_name
+      ON symbol_registry(scope_user_id, scope_agent_id, project_id, module, symbol_name)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS task_registry (
+        task_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        project_id TEXT NOT NULL,
+        task_title TEXT NOT NULL,
+        task_type TEXT,
+        task_status TEXT,
+        parent_task_id TEXT,
+        related_task_ids TEXT,
+        files_touched TEXT,
+        symbols_touched TEXT,
+        commit_refs TEXT,
+        diff_refs TEXT,
+        decision_notes TEXT,
+        tracker_issue_key TEXT,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_user_id, scope_agent_id, task_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_task_project_parent
+      ON task_registry(scope_user_id, scope_agent_id, project_id, parent_task_id)
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS migration_state (
+        migration_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        schema_from TEXT NOT NULL,
+        schema_to TEXT NOT NULL,
+        applied_at TEXT NOT NULL,
+        status TEXT NOT NULL,
+        notes TEXT,
+        PRIMARY KEY (scope_user_id, scope_agent_id, migration_id)
+      )
+    `);
+        // ASM-78 (v5.1) incremental reindex watch-state + diff/checksum control plane.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS project_index_watch_state (
+        project_id TEXT NOT NULL,
+        scope_user_id TEXT NOT NULL DEFAULT '',
+        scope_agent_id TEXT NOT NULL DEFAULT '',
+        last_source_rev TEXT,
+        last_checksum_snapshot TEXT NOT NULL DEFAULT '{}',
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scope_user_id, scope_agent_id, project_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_project_watch_updated
+      ON project_index_watch_state(scope_user_id, scope_agent_id, updated_at)
     `);
     }
     // --------------------------------------------------------------------------
@@ -222,9 +437,1066 @@ export class SlotDB {
         const result = stmt.get(scopeUserId, scopeAgentId);
         return result.cnt;
     }
+    registerProject(scopeUserId, scopeAgentId, input) {
+        const projectAlias = this.normalizeProjectAlias(input.project_alias);
+        if (!projectAlias) {
+            throw new Error("project_alias is required");
+        }
+        const now = new Date().toISOString();
+        const projectId = this.normalizeProjectId(input.project_id) || randomUUID();
+        const projectName = this.normalizeProjectName(input.project_name) || projectAlias;
+        const normalizedRepoRoot = this.normalizeRepoRoot(input.repo_root);
+        const normalizedRepoRemote = this.normalizeRepoRemote(input.repo_remote);
+        const existingAlias = this.getProjectByAlias(scopeUserId, scopeAgentId, projectAlias);
+        if (existingAlias && existingAlias.project.project_id !== projectId && !input.allow_alias_update) {
+            throw new Error(`project_alias \"${projectAlias}\" is already mapped to another project_id`);
+        }
+        let targetProjectId = projectId;
+        const existingByRepoRoot = input.reuse_existing_repo_root && normalizedRepoRoot
+            ? this.findProjectByRepoRoot(scopeUserId, scopeAgentId, normalizedRepoRoot)
+            : null;
+        if (existingByRepoRoot) {
+            targetProjectId = existingByRepoRoot.project_id;
+        }
+        const existing = this.getProjectById(scopeUserId, scopeAgentId, targetProjectId);
+        if (existing) {
+            const updateProject = this.db.prepare(`UPDATE projects
+         SET project_name = ?, repo_root = ?, repo_remote_primary = ?, active_version = ?, updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+            updateProject.run(projectName || existing.project_name, normalizedRepoRoot ?? existing.repo_root, normalizedRepoRemote ?? existing.repo_remote_primary, input.active_version ?? existing.active_version, now, scopeUserId, scopeAgentId, targetProjectId);
+        }
+        else {
+            const insertProject = this.db.prepare(`INSERT INTO projects (
+          project_id, scope_user_id, scope_agent_id, project_name, repo_root, repo_remote_primary, active_version, lifecycle_status, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)`);
+            insertProject.run(targetProjectId, scopeUserId, scopeAgentId, projectName, normalizedRepoRoot, normalizedRepoRemote, input.active_version || null, now, now);
+        }
+        this.upsertProjectAlias(scopeUserId, scopeAgentId, targetProjectId, projectAlias, true, now, input.allow_alias_update === true);
+        const project = this.getProjectById(scopeUserId, scopeAgentId, targetProjectId);
+        if (!project)
+            throw new Error("failed to persist project registry record");
+        const registration = this.upsertProjectRegistrationState(scopeUserId, scopeAgentId, {
+            project_id: targetProjectId,
+            registration_status: "registered",
+            validation_status: "ok",
+            validation_notes: null,
+            completeness_score: this.computeRegistrationCompleteness(project, projectAlias),
+            missing_required_fields: this.computeMissingRegistrationFields(project, projectAlias),
+            last_validated_at: now,
+        });
+        const alias = this.getProjectAlias(scopeUserId, scopeAgentId, projectAlias);
+        if (!alias)
+            throw new Error("failed to persist project alias");
+        return { project, alias, registration };
+    }
+    findProjectByRepoRoot(scopeUserId, scopeAgentId, repoRoot) {
+        const normalizedRepoRoot = this.normalizeRepoRoot(repoRoot);
+        if (!normalizedRepoRoot)
+            return null;
+        const stmt = this.db.prepare(`SELECT * FROM projects WHERE scope_user_id = ? AND scope_agent_id = ? AND repo_root = ? LIMIT 1`);
+        const row = stmt.get(scopeUserId, scopeAgentId, normalizedRepoRoot);
+        return row || null;
+    }
+    getProjectById(scopeUserId, scopeAgentId, projectId) {
+        const stmt = this.db.prepare(`SELECT * FROM projects WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, projectId);
+        return row || null;
+    }
+    getProjectAlias(scopeUserId, scopeAgentId, projectAlias) {
+        const normalizedAlias = this.normalizeProjectAlias(projectAlias);
+        const stmt = this.db.prepare(`SELECT * FROM project_aliases WHERE scope_user_id = ? AND scope_agent_id = ? AND project_alias = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, normalizedAlias);
+        return row || null;
+    }
+    getProjectByAlias(scopeUserId, scopeAgentId, projectAlias) {
+        const normalizedAlias = this.normalizeProjectAlias(projectAlias);
+        const stmt = this.db.prepare(`SELECT p.project_id, p.scope_user_id, p.scope_agent_id, p.project_name, p.repo_root, p.repo_remote_primary,
+              p.active_version, p.lifecycle_status, p.created_at, p.updated_at,
+              a.id as alias_id, a.project_alias, a.is_primary, a.created_at as alias_created_at, a.updated_at as alias_updated_at
+       FROM project_aliases a
+       JOIN projects p ON p.project_id = a.project_id
+         AND p.scope_user_id = a.scope_user_id
+         AND p.scope_agent_id = a.scope_agent_id
+       WHERE a.scope_user_id = ? AND a.scope_agent_id = ? AND a.project_alias = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, normalizedAlias);
+        if (!row)
+            return null;
+        return {
+            project: {
+                project_id: String(row.project_id),
+                scope_user_id: String(row.scope_user_id),
+                scope_agent_id: String(row.scope_agent_id),
+                project_name: String(row.project_name),
+                repo_root: row.repo_root ? String(row.repo_root) : null,
+                repo_remote_primary: row.repo_remote_primary ? String(row.repo_remote_primary) : null,
+                active_version: row.active_version ? String(row.active_version) : null,
+                lifecycle_status: String(row.lifecycle_status),
+                created_at: String(row.created_at),
+                updated_at: String(row.updated_at),
+            },
+            alias: {
+                id: String(row.alias_id),
+                project_id: String(row.project_id),
+                scope_user_id: String(row.scope_user_id),
+                scope_agent_id: String(row.scope_agent_id),
+                project_alias: String(row.project_alias),
+                is_primary: Number(row.is_primary),
+                created_at: String(row.alias_created_at),
+                updated_at: String(row.alias_updated_at),
+            },
+        };
+    }
+    listProjects(scopeUserId, scopeAgentId) {
+        const projectsStmt = this.db.prepare(`SELECT * FROM projects WHERE scope_user_id = ? AND scope_agent_id = ? ORDER BY updated_at DESC`);
+        const projects = projectsStmt.all(scopeUserId, scopeAgentId);
+        const aliasesStmt = this.db.prepare(`SELECT * FROM project_aliases WHERE scope_user_id = ? AND scope_agent_id = ? ORDER BY is_primary DESC, project_alias ASC`);
+        const aliases = aliasesStmt.all(scopeUserId, scopeAgentId);
+        const aliasesByProject = new Map();
+        for (const alias of aliases) {
+            const list = aliasesByProject.get(alias.project_id) || [];
+            list.push(alias);
+            aliasesByProject.set(alias.project_id, list);
+        }
+        return projects.map((project) => ({
+            project,
+            aliases: aliasesByProject.get(project.project_id) || [],
+            registration: this.getProjectRegistrationState(scopeUserId, scopeAgentId, project.project_id),
+        }));
+    }
+    setProjectTrackerMapping(scopeUserId, scopeAgentId, input) {
+        const now = new Date().toISOString();
+        const existing = this.getProjectTrackerMapping(scopeUserId, scopeAgentId, input.project_id, input.tracker_type);
+        if (existing) {
+            const stmt = this.db.prepare(`UPDATE project_tracker_mappings
+         SET tracker_space_key = ?, tracker_project_id = ?, default_epic_key = ?, board_key = ?,
+             active_version = ?, external_project_url = ?, updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tracker_type = ?`);
+            stmt.run(input.tracker_space_key || null, input.tracker_project_id || null, input.default_epic_key || null, input.board_key || null, input.active_version || null, input.external_project_url || null, now, scopeUserId, scopeAgentId, input.project_id, input.tracker_type);
+        }
+        else {
+            const stmt = this.db.prepare(`INSERT INTO project_tracker_mappings (
+          id, project_id, scope_user_id, scope_agent_id, tracker_type, tracker_space_key, tracker_project_id,
+          default_epic_key, board_key, active_version, external_project_url, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            stmt.run(randomUUID(), input.project_id, scopeUserId, scopeAgentId, input.tracker_type, input.tracker_space_key || null, input.tracker_project_id || null, input.default_epic_key || null, input.board_key || null, input.active_version || null, input.external_project_url || null, now, now);
+        }
+        const mapping = this.getProjectTrackerMapping(scopeUserId, scopeAgentId, input.project_id, input.tracker_type);
+        if (!mapping)
+            throw new Error("failed to persist project tracker mapping");
+        return mapping;
+    }
+    getProjectTrackerMapping(scopeUserId, scopeAgentId, projectId, trackerType) {
+        const stmt = this.db.prepare(`SELECT * FROM project_tracker_mappings WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tracker_type = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, projectId, trackerType);
+        return row || null;
+    }
+    getProjectRegistrationState(scopeUserId, scopeAgentId, projectId) {
+        const stmt = this.db.prepare(`SELECT * FROM project_registration_state WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, projectId);
+        if (!row)
+            return null;
+        return {
+            project_id: row.project_id,
+            scope_user_id: row.scope_user_id,
+            scope_agent_id: row.scope_agent_id,
+            registration_status: row.registration_status,
+            validation_status: row.validation_status,
+            validation_notes: row.validation_notes,
+            completeness_score: row.completeness_score,
+            missing_required_fields: this.parseJsonArrayField(row.missing_required_fields),
+            last_validated_at: row.last_validated_at,
+            updated_at: row.updated_at,
+        };
+    }
+    updateProjectRegistrationState(scopeUserId, scopeAgentId, input) {
+        return this.upsertProjectRegistrationState(scopeUserId, scopeAgentId, {
+            ...input,
+            validation_notes: input.validation_notes ?? null,
+            last_validated_at: input.last_validated_at ?? new Date().toISOString(),
+        });
+    }
+    getProjectIndexWatchState(scopeUserId, scopeAgentId, projectId) {
+        const stmt = this.db.prepare(`SELECT * FROM project_index_watch_state WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, projectId);
+        if (!row)
+            return null;
+        return {
+            project_id: row.project_id,
+            scope_user_id: row.scope_user_id,
+            scope_agent_id: row.scope_agent_id,
+            last_source_rev: row.last_source_rev,
+            last_checksum_snapshot: this.parseChecksumMap(row.last_checksum_snapshot),
+            updated_at: row.updated_at,
+        };
+    }
+    reindexProjectByDiff(scopeUserId, scopeAgentId, input) {
+        const now = new Date().toISOString();
+        const runId = randomUUID();
+        const triggerType = input.trigger_type || "incremental";
+        const indexProfile = (input.index_profile || "default").trim() || "default";
+        const sourceRev = input.source_rev?.trim() || null;
+        if (!input.project_id || !String(input.project_id).trim()) {
+            throw new Error("project_id is required");
+        }
+        const project = this.getProjectById(scopeUserId, scopeAgentId, input.project_id);
+        if (!project) {
+            throw new Error(`project_id '${input.project_id}' is not registered`);
+        }
+        const watch = this.getProjectIndexWatchState(scopeUserId, scopeAgentId, input.project_id);
+        const previousSnapshot = watch?.last_checksum_snapshot || {};
+        const currentSnapshot = new Map();
+        for (const item of input.paths || []) {
+            const relativePath = this.normalizeRelativePath(item.relative_path);
+            if (!relativePath)
+                continue;
+            const checksum = (item.checksum || "").trim() || "__missing__";
+            currentSnapshot.set(relativePath, checksum);
+        }
+        const changed = [];
+        const unchanged = [];
+        for (const [relativePath, checksum] of currentSnapshot.entries()) {
+            const prev = previousSnapshot[relativePath];
+            if (!prev || prev !== checksum)
+                changed.push(relativePath);
+            else
+                unchanged.push(relativePath);
+        }
+        const deleted = [];
+        for (const prevPath of Object.keys(previousSnapshot)) {
+            if (!currentSnapshot.has(prevPath))
+                deleted.push(prevPath);
+        }
+        this.insertIndexRun(scopeUserId, scopeAgentId, {
+            run_id: runId,
+            project_id: input.project_id,
+            index_profile: indexProfile,
+            trigger_type: triggerType,
+            state: "indexing",
+            started_at: now,
+            finished_at: null,
+            error_message: null,
+        });
+        try {
+            const nowIso = new Date().toISOString();
+            for (const relativePath of changed) {
+                const item = (input.paths || []).find((p) => this.normalizeRelativePath(p.relative_path) === relativePath);
+                this.upsertFileIndexState(scopeUserId, scopeAgentId, {
+                    file_id: this.makeScopedId(input.project_id, relativePath),
+                    project_id: input.project_id,
+                    relative_path: relativePath,
+                    module: item?.module || null,
+                    language: item?.language || null,
+                    checksum: currentSnapshot.get(relativePath) || "__missing__",
+                    last_commit_sha: sourceRev,
+                    index_state: "indexed",
+                    active: 1,
+                    tombstone_at: null,
+                    indexed_at: nowIso,
+                });
+            }
+            for (const relativePath of deleted) {
+                this.markFileIndexStateDeleted(scopeUserId, scopeAgentId, input.project_id, relativePath, nowIso);
+            }
+            const checksumSnapshotRecord = Object.fromEntries(currentSnapshot.entries());
+            this.upsertProjectIndexWatchState(scopeUserId, scopeAgentId, {
+                project_id: input.project_id,
+                last_source_rev: sourceRev,
+                last_checksum_snapshot: checksumSnapshotRecord,
+                updated_at: nowIso,
+            });
+            this.finishIndexRun(scopeUserId, scopeAgentId, runId, "indexed", null, nowIso);
+            return {
+                run_id: runId,
+                project_id: input.project_id,
+                trigger_type: triggerType,
+                index_profile: indexProfile,
+                source_rev: sourceRev,
+                changed,
+                unchanged,
+                deleted,
+                run_state: "indexed",
+                watch_state: {
+                    last_source_rev: sourceRev,
+                    updated_at: nowIso,
+                },
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error.message : String(error);
+            this.finishIndexRun(scopeUserId, scopeAgentId, runId, "error", err, new Date().toISOString());
+            throw error;
+        }
+    }
+    upsertTaskRegistryRecord(scopeUserId, scopeAgentId, input) {
+        const now = new Date().toISOString();
+        const taskId = String(input.task_id || "").trim();
+        const projectId = String(input.project_id || "").trim();
+        const taskTitle = String(input.task_title || "").trim();
+        if (!taskId)
+            throw new Error("task_id is required");
+        if (!projectId)
+            throw new Error("project_id is required");
+        if (!taskTitle)
+            throw new Error("task_title is required");
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        const existing = this.getTaskRegistryRecordById(scopeUserId, scopeAgentId, taskId);
+        const relatedTaskIds = this.normalizeStringArray(input.related_task_ids);
+        const filesTouched = this.normalizeStringArray(input.files_touched).map((p) => this.normalizeRelativePath(p)).filter(Boolean);
+        const symbolsTouched = this.normalizeStringArray(input.symbols_touched);
+        const commitRefs = this.normalizeStringArray(input.commit_refs);
+        const diffRefs = this.normalizeStringArray(input.diff_refs);
+        if (existing) {
+            const stmt = this.db.prepare(`UPDATE task_registry
+         SET project_id = ?, task_title = ?, task_type = ?, task_status = ?, parent_task_id = ?,
+             related_task_ids = ?, files_touched = ?, symbols_touched = ?, commit_refs = ?, diff_refs = ?,
+             decision_notes = ?, tracker_issue_key = ?, updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND task_id = ?`);
+            stmt.run(projectId, taskTitle, input.task_type ?? null, input.task_status ?? null, input.parent_task_id ?? null, JSON.stringify(relatedTaskIds), JSON.stringify(filesTouched), JSON.stringify(symbolsTouched), JSON.stringify(commitRefs), JSON.stringify(diffRefs), input.decision_notes ?? null, input.tracker_issue_key ?? null, now, scopeUserId, scopeAgentId, taskId);
+        }
+        else {
+            const stmt = this.db.prepare(`INSERT INTO task_registry (
+          task_id, scope_user_id, scope_agent_id, project_id, task_title, task_type, task_status, parent_task_id,
+          related_task_ids, files_touched, symbols_touched, commit_refs, diff_refs, decision_notes, tracker_issue_key, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            stmt.run(taskId, scopeUserId, scopeAgentId, projectId, taskTitle, input.task_type ?? null, input.task_status ?? null, input.parent_task_id ?? null, JSON.stringify(relatedTaskIds), JSON.stringify(filesTouched), JSON.stringify(symbolsTouched), JSON.stringify(commitRefs), JSON.stringify(diffRefs), input.decision_notes ?? null, input.tracker_issue_key ?? null, now);
+        }
+        const row = this.getTaskRegistryRecordById(scopeUserId, scopeAgentId, taskId);
+        if (!row)
+            throw new Error("failed to persist task registry record");
+        return row;
+    }
+    getTaskRegistryRecordById(scopeUserId, scopeAgentId, taskId) {
+        const normalizedTaskId = String(taskId || "").trim();
+        if (!normalizedTaskId)
+            return null;
+        const stmt = this.db.prepare(`SELECT * FROM task_registry WHERE scope_user_id = ? AND scope_agent_id = ? AND task_id = ?`);
+        const row = stmt.get(scopeUserId, scopeAgentId, normalizedTaskId);
+        if (!row)
+            return null;
+        return this.rowToTaskRecord(row);
+    }
+    getTaskRegistryRecordByTrackerIssueKey(scopeUserId, scopeAgentId, projectId, trackerIssueKey) {
+        const tracker = String(trackerIssueKey || "").trim();
+        if (!tracker)
+            return null;
+        const stmt = this.db.prepare(`SELECT * FROM task_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tracker_issue_key = ?
+       ORDER BY updated_at DESC LIMIT 1`);
+        const row = stmt.get(scopeUserId, scopeAgentId, projectId, tracker);
+        if (!row)
+            return null;
+        return this.rowToTaskRecord(row);
+    }
+    getTaskLineageContext(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`);
+        }
+        let focus = null;
+        if (input.task_id) {
+            const byId = this.getTaskRegistryRecordById(scopeUserId, scopeAgentId, input.task_id);
+            if (byId && byId.project_id === projectId)
+                focus = byId;
+        }
+        if (!focus && input.tracker_issue_key) {
+            focus = this.getTaskRegistryRecordByTrackerIssueKey(scopeUserId, scopeAgentId, projectId, input.tracker_issue_key);
+        }
+        if (!focus && input.task_title) {
+            const stmt = this.db.prepare(`SELECT * FROM task_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND lower(task_title) LIKE ?
+         ORDER BY updated_at DESC LIMIT 1`);
+            const row = stmt.get(scopeUserId, scopeAgentId, projectId, `%${String(input.task_title).trim().toLowerCase()}%`);
+            if (row)
+                focus = this.rowToTaskRecord(row);
+        }
+        if (!focus) {
+            throw new Error("task lineage focus not found for provided selector");
+        }
+        const includeParentChain = input.include_parent_chain !== false;
+        const includeRelated = input.include_related !== false;
+        const parentChain = [];
+        if (includeParentChain) {
+            let cursor = focus.parent_task_id;
+            const guard = new Set();
+            while (cursor && !guard.has(cursor)) {
+                guard.add(cursor);
+                const parent = this.getTaskRegistryRecordById(scopeUserId, scopeAgentId, cursor);
+                if (!parent)
+                    break;
+                parentChain.push(parent);
+                cursor = parent.parent_task_id;
+            }
+        }
+        const relatedTasks = [];
+        if (includeRelated) {
+            const seen = new Set();
+            for (const relatedId of focus.related_task_ids || []) {
+                if (!relatedId || seen.has(relatedId))
+                    continue;
+                seen.add(relatedId);
+                const related = this.getTaskRegistryRecordById(scopeUserId, scopeAgentId, relatedId);
+                if (related)
+                    relatedTasks.push(related);
+            }
+        }
+        const aggregate = [focus, ...parentChain, ...relatedTasks];
+        const touchedFiles = this.uniqueSorted(aggregate.flatMap((t) => t.files_touched || []));
+        const touchedSymbols = this.uniqueSorted(aggregate.flatMap((t) => t.symbols_touched || []));
+        const commitRefs = this.uniqueSorted(aggregate.flatMap((t) => t.commit_refs || []));
+        const decisionNotes = this.uniqueSorted(aggregate
+            .map((t) => String(t.decision_notes || "").trim())
+            .filter(Boolean));
+        return {
+            focus: {
+                project_id: projectId,
+                task_id: focus.task_id,
+                tracker_issue_key: focus.tracker_issue_key,
+                task_title: focus.task_title,
+            },
+            parent_chain: parentChain,
+            related_tasks: relatedTasks,
+            touched_files: touchedFiles,
+            touched_symbols: touchedSymbols,
+            commit_refs: commitRefs,
+            decision_notes: decisionNotes,
+        };
+    }
+    hybridSearchProjectContext(scopeUserId, scopeAgentId, input) {
+        const projectId = String(input.project_id || "").trim();
+        const query = String(input.query || "").trim();
+        if (!projectId)
+            throw new Error("project_id is required");
+        if (!query)
+            throw new Error("query is required");
+        const project = this.getProjectById(scopeUserId, scopeAgentId, projectId);
+        if (!project) {
+            throw new Error(`project_id '${projectId}' is not registered`);
+        }
+        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)));
+        const tokenScore = (text) => {
+            if (!queryTokens.length)
+                return 0;
+            const hay = text.toLowerCase();
+            const words = Array.from(new Set(hay.split(/[^a-z0-9]+/i).map((t) => t.trim()).filter(Boolean)));
+            let matched = 0;
+            for (const token of queryTokens) {
+                if (hay.includes(token)) {
+                    matched += 1;
+                    continue;
+                }
+                if (words.some((word) => word.startsWith(token) || token.startsWith(word))) {
+                    matched += 0.8;
+                }
+            }
+            return matched / queryTokens.length;
+        };
+        const taskContextInput = input.task_context;
+        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,
+            });
+        }
+        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()));
+        const lexicalLanguages = new Set(this.normalizeStringArray(input.language).map((s) => s.toLowerCase()));
+        const lexicalTaskIds = new Set(this.normalizeStringArray(input.task_id));
+        const lexicalIssueKeys = new Set(this.normalizeStringArray(input.tracker_issue_key).map((s) => s.toUpperCase()));
+        if (lineageContext) {
+            lexicalTaskIds.add(lineageContext.focus.task_id);
+            if (lineageContext.focus.tracker_issue_key)
+                lexicalIssueKeys.add(lineageContext.focus.tracker_issue_key.toUpperCase());
+            for (const t of [...lineageContext.parent_chain, ...lineageContext.related_tasks]) {
+                lexicalTaskIds.add(t.task_id);
+                if (t.tracker_issue_key)
+                    lexicalIssueKeys.add(t.tracker_issue_key.toUpperCase());
+            }
+        }
+        const results = [];
+        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);
+        for (const row of fileRows) {
+            const relativePath = String(row.relative_path || "");
+            const moduleName = row.module ? String(row.module) : null;
+            const language = row.language ? String(row.language) : null;
+            if (lexicalPathPrefix.length > 0 && !lexicalPathPrefix.some((prefix) => relativePath.startsWith(prefix)))
+                continue;
+            if (lexicalModules.size > 0 && !moduleName)
+                continue;
+            if (lexicalModules.size > 0 && moduleName && !lexicalModules.has(moduleName.toLowerCase()))
+                continue;
+            if (lexicalLanguages.size > 0 && !language)
+                continue;
+            if (lexicalLanguages.size > 0 && language && !lexicalLanguages.has(language.toLowerCase()))
+                continue;
+            const text = `${relativePath} ${moduleName || ""} ${language || ""}`.toLowerCase();
+            let score = 0;
+            if (text.includes(queryLc))
+                score += 0.55;
+            score += tokenScore(text) * 0.45;
+            if (lineageContext && lineageContext.touched_files.includes(relativePath))
+                score += 0.35;
+            if (relativePath.includes("README") || relativePath.includes("docs/"))
+                score += 0.05;
+            if (relativePath.includes("src/services/"))
+                score += 0.08;
+            if (relativePath.endsWith('.service.ts'))
+                score += 0.06;
+            if (score <= 0.12)
+                continue;
+            results.push({
+                source: "file_index_state",
+                id: String(row.file_id),
+                score,
+                project_id: projectId,
+                relative_path: relativePath,
+                module: moduleName,
+                language,
+                snippet: `file ${relativePath}${moduleName ? ` (module ${moduleName})` : ""}`,
+            });
+        }
+        const symbolStmt = this.db.prepare(`SELECT * FROM symbol_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND active = 1`);
+        const symbolRows = symbolStmt.all(scopeUserId, scopeAgentId, projectId);
+        for (const row of symbolRows) {
+            const relativePath = String(row.relative_path || "");
+            const moduleName = row.module ? String(row.module) : null;
+            const language = row.language ? String(row.language) : null;
+            const symbolName = String(row.symbol_name || "");
+            const symbolKind = String(row.symbol_kind || "");
+            const symbolFqn = String(row.symbol_fqn || "");
+            if (lexicalPathPrefix.length > 0 && !lexicalPathPrefix.some((prefix) => relativePath.startsWith(prefix)))
+                continue;
+            if (lexicalModules.size > 0 && !moduleName)
+                continue;
+            if (lexicalModules.size > 0 && moduleName && !lexicalModules.has(moduleName.toLowerCase()))
+                continue;
+            if (lexicalLanguages.size > 0 && !language)
+                continue;
+            if (lexicalLanguages.size > 0 && language && !lexicalLanguages.has(language.toLowerCase()))
+                continue;
+            const text = `${symbolName} ${symbolFqn} ${relativePath} ${moduleName || ""} ${symbolKind}`.toLowerCase();
+            let score = 0;
+            if (text.includes(queryLc))
+                score += 0.62;
+            score += tokenScore(text) * 0.4;
+            if (lineageContext && lineageContext.touched_symbols.includes(symbolName))
+                score += 0.3;
+            if (lineageContext && lineageContext.touched_files.includes(relativePath))
+                score += 0.12;
+            if (score <= 0.15)
+                continue;
+            results.push({
+                source: "symbol_registry",
+                id: String(row.symbol_id),
+                score,
+                project_id: projectId,
+                relative_path: relativePath,
+                module: moduleName,
+                language,
+                symbol_name: symbolName,
+                symbol_kind: symbolKind,
+                snippet: `symbol ${symbolName} (${symbolKind}) in ${relativePath}`,
+            });
+        }
+        const taskStmt = this.db.prepare(`SELECT * FROM task_registry
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+        const taskRows = taskStmt.all(scopeUserId, scopeAgentId, projectId);
+        for (const row of taskRows) {
+            const task = this.rowToTaskRecord(row);
+            const taskIssueKey = task.tracker_issue_key ? task.tracker_issue_key.toUpperCase() : null;
+            if (lexicalTaskIds.size > 0 && !lexicalTaskIds.has(task.task_id)) {
+                if (!taskIssueKey || !lexicalIssueKeys.has(taskIssueKey)) {
+                    // keep if user query still lexically matches strongly
+                }
+            }
+            const text = [
+                task.task_id,
+                task.task_title,
+                task.task_status || "",
+                task.tracker_issue_key || "",
+                ...(task.files_touched || []),
+                ...(task.symbols_touched || []),
+                ...(task.commit_refs || []),
+                task.decision_notes || "",
+            ].join(" ").toLowerCase();
+            let score = 0;
+            if (text.includes(queryLc))
+                score += 0.58;
+            score += tokenScore(text) * 0.35;
+            if (lexicalTaskIds.has(task.task_id))
+                score += 0.28;
+            if (taskIssueKey && lexicalIssueKeys.has(taskIssueKey))
+                score += 0.28;
+            if (lineageContext) {
+                if (task.task_id === lineageContext.focus.task_id)
+                    score += 0.35;
+                if (lineageContext.parent_chain.some((t) => t.task_id === task.task_id))
+                    score += 0.2;
+                if (lineageContext.related_tasks.some((t) => t.task_id === task.task_id))
+                    score += 0.2;
+            }
+            if (score <= 0.15)
+                continue;
+            results.push({
+                source: "task_registry",
+                id: task.task_id,
+                score,
+                project_id: projectId,
+                task_id: task.task_id,
+                task_title: task.task_title,
+                tracker_issue_key: task.tracker_issue_key,
+                snippet: `task ${task.task_id}: ${task.task_title}`,
+            });
+        }
+        const ranked = results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map((item) => ({ ...item, score: Number(item.score.toFixed(4)) }));
+        return {
+            query,
+            project_id: projectId,
+            count: ranked.length,
+            task_lineage_context: lineageContext,
+            results: ranked,
+        };
+    }
+    runLegacyCompatibilityBackfill(scopeUserId, scopeAgentId, input = {}) {
+        const mode = input.mode || "dry_run";
+        const source = input.source || "mixed";
+        const now = new Date().toISOString();
+        const onlyProjectIds = new Set(this.normalizeStringArray(input.only_project_ids));
+        const onlyAliases = new Set(this.normalizeStringArray(input.only_aliases).map((a) => this.normalizeProjectAlias(a)));
+        const projects = this.listProjects(scopeUserId, scopeAgentId);
+        const selected = projects.filter((row) => {
+            if (onlyProjectIds.size > 0 && !onlyProjectIds.has(row.project.project_id))
+                return false;
+            if (onlyAliases.size > 0) {
+                const aliases = row.aliases.map((a) => this.normalizeProjectAlias(a.project_alias));
+                if (!aliases.some((a) => onlyAliases.has(a)))
+                    return false;
+            }
+            return true;
+        });
+        let updatedAliases = 0;
+        let updatedMappings = 0;
+        let updatedRegistrations = 0;
+        let migrationStateUpserts = 0;
+        const items = [];
+        for (const row of selected) {
+            const project = row.project;
+            const warnings = [];
+            const actions = [];
+            const existingAliases = new Set(row.aliases.map((a) => this.normalizeProjectAlias(a.project_alias)).filter(Boolean));
+            const inferredAliases = this.inferBackfillAliases(project, existingAliases, source);
+            const inferredMappings = this.inferBackfillTrackerMappings(scopeUserId, scopeAgentId, project.project_id, project, source);
+            if (mode === "apply") {
+                for (const alias of inferredAliases) {
+                    if (existingAliases.has(alias))
+                        continue;
+                    this.upsertProjectAlias(scopeUserId, scopeAgentId, project.project_id, alias, false, now, false);
+                    existingAliases.add(alias);
+                    updatedAliases += 1;
+                    actions.push(`alias.backfilled:${alias}`);
+                }
+                for (const mapping of inferredMappings) {
+                    const existing = this.getProjectTrackerMapping(scopeUserId, scopeAgentId, project.project_id, mapping.tracker_type);
+                    if (existing
+                        && existing.tracker_space_key === mapping.tracker_space_key
+                        && existing.default_epic_key === mapping.default_epic_key
+                        && existing.tracker_project_id === mapping.tracker_project_id) {
+                        continue;
+                    }
+                    this.setProjectTrackerMapping(scopeUserId, scopeAgentId, {
+                        project_id: project.project_id,
+                        tracker_type: mapping.tracker_type,
+                        tracker_space_key: mapping.tracker_space_key || undefined,
+                        tracker_project_id: mapping.tracker_project_id || undefined,
+                        default_epic_key: mapping.default_epic_key || undefined,
+                    });
+                    updatedMappings += 1;
+                    actions.push(`tracker.backfilled:${mapping.tracker_type}`);
+                }
+            }
+            const primaryAlias = this.pickPrimaryAlias(existingAliases, project);
+            const completeness = this.computeRegistrationCompleteness(project, primaryAlias);
+            const missingFields = this.computeMissingRegistrationFields(project, primaryAlias);
+            const hasTracker = inferredMappings.length > 0 || Boolean(this.getProjectTrackerMapping(scopeUserId, scopeAgentId, project.project_id, "jira"));
+            const status = hasTracker && completeness >= 90 ? "validated" : "registered";
+            const validationStatus = missingFields.length === 0 ? "ok" : "warn";
+            const existingRegistration = this.getProjectRegistrationState(scopeUserId, scopeAgentId, project.project_id);
+            const shouldUpdateRegistration = !existingRegistration
+                || input.force_registration_state === true
+                || existingRegistration.registration_status === "draft"
+                || existingRegistration.validation_status !== validationStatus;
+            if (shouldUpdateRegistration) {
+                if (mode === "apply") {
+                    this.upsertProjectRegistrationState(scopeUserId, scopeAgentId, {
+                        project_id: project.project_id,
+                        registration_status: status,
+                        validation_status: validationStatus,
+                        validation_notes: `legacy_backfill:${source}`,
+                        completeness_score: completeness,
+                        missing_required_fields: missingFields,
+                        last_validated_at: now,
+                    });
+                    updatedRegistrations += 1;
+                    actions.push("registration.backfilled");
+                }
+            }
+            if (mode === "apply") {
+                this.upsertMigrationState(scopeUserId, scopeAgentId, {
+                    migration_id: `legacy-backfill:${project.project_id}`,
+                    schema_from: "legacy",
+                    schema_to: "5.1",
+                    applied_at: now,
+                    status: "migrated",
+                    notes: JSON.stringify({
+                        source,
+                        alias_count: inferredAliases.length,
+                        tracker_count: inferredMappings.length,
+                    }),
+                });
+                migrationStateUpserts += 1;
+            }
+            if (inferredAliases.length === 0) {
+                warnings.push("no additional alias inferred");
+            }
+            if (inferredMappings.length === 0) {
+                warnings.push("no tracker mapping inferred");
+            }
+            items.push({
+                project_id: project.project_id,
+                project_name: project.project_name,
+                inferred_aliases: inferredAliases,
+                inferred_tracker_mappings: inferredMappings,
+                actions,
+                warnings,
+            });
+        }
+        return {
+            mode,
+            source,
+            scanned_projects: projects.length,
+            candidates: selected.length,
+            updated_aliases: updatedAliases,
+            updated_tracker_mappings: updatedMappings,
+            updated_registration_states: updatedRegistrations,
+            migration_state_upserts: migrationStateUpserts,
+            items,
+        };
+    }
     // --------------------------------------------------------------------------
     // Helpers
     // --------------------------------------------------------------------------
+    normalizeProjectAlias(alias) {
+        return String(alias || "")
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/g, "-")
+            .replace(/[^a-z0-9._-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "");
+    }
+    normalizeRelativePath(pathInput) {
+        const normalized = String(pathInput || "")
+            .trim()
+            .replace(/\\/g, "/")
+            .replace(/^\.\//, "")
+            .replace(/\/+/g, "/");
+        return normalized;
+    }
+    makeScopedId(projectId, relativePath) {
+        return `${projectId}::${relativePath}`;
+    }
+    parseChecksumMap(raw) {
+        if (!raw)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return {};
+            const out = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                if (typeof key === "string" && typeof value === "string") {
+                    out[key] = value;
+                }
+            }
+            return out;
+        }
+        catch {
+            return {};
+        }
+    }
+    insertIndexRun(scopeUserId, scopeAgentId, input) {
+        const stmt = this.db.prepare(`INSERT INTO index_runs (
+        run_id, scope_user_id, scope_agent_id, project_id, index_profile, trigger_type, state, started_at, finished_at, error_message
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        stmt.run(input.run_id, scopeUserId, scopeAgentId, input.project_id, input.index_profile, input.trigger_type, input.state, input.started_at, input.finished_at, input.error_message);
+    }
+    finishIndexRun(scopeUserId, scopeAgentId, runId, state, errorMessage, finishedAt) {
+        const stmt = this.db.prepare(`UPDATE index_runs
+       SET state = ?, finished_at = ?, error_message = ?
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND run_id = ?`);
+        stmt.run(state, finishedAt, errorMessage, scopeUserId, scopeAgentId, runId);
+    }
+    upsertFileIndexState(scopeUserId, scopeAgentId, input) {
+        const existingStmt = this.db.prepare(`SELECT file_id FROM file_index_state
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND relative_path = ?`);
+        const existing = existingStmt.get(scopeUserId, scopeAgentId, input.project_id, input.relative_path);
+        if (existing) {
+            const updateStmt = this.db.prepare(`UPDATE file_index_state
+         SET module = ?, language = ?, checksum = ?, last_commit_sha = ?, index_state = ?, active = ?, tombstone_at = ?, indexed_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND file_id = ?`);
+            updateStmt.run(input.module, input.language, input.checksum, input.last_commit_sha, input.index_state, input.active, input.tombstone_at, input.indexed_at, scopeUserId, scopeAgentId, existing.file_id);
+            return;
+        }
+        const insertStmt = this.db.prepare(`INSERT INTO file_index_state (
+        file_id, scope_user_id, scope_agent_id, project_id, relative_path, module, language,
+        checksum, last_commit_sha, index_state, active, tombstone_at, indexed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        insertStmt.run(input.file_id, scopeUserId, scopeAgentId, input.project_id, input.relative_path, input.module, input.language, input.checksum, input.last_commit_sha, input.index_state, input.active, input.tombstone_at, input.indexed_at);
+    }
+    markFileIndexStateDeleted(scopeUserId, scopeAgentId, projectId, relativePath, tombstoneAt) {
+        const stmt = 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 relative_path = ?`);
+        stmt.run(tombstoneAt, tombstoneAt, scopeUserId, scopeAgentId, projectId, relativePath);
+    }
+    upsertProjectIndexWatchState(scopeUserId, scopeAgentId, input) {
+        const existing = this.getProjectIndexWatchState(scopeUserId, scopeAgentId, input.project_id);
+        const checksumJson = JSON.stringify(input.last_checksum_snapshot || {});
+        if (existing) {
+            const stmt = this.db.prepare(`UPDATE project_index_watch_state
+         SET last_source_rev = ?, last_checksum_snapshot = ?, updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+            stmt.run(input.last_source_rev, checksumJson, input.updated_at, scopeUserId, scopeAgentId, input.project_id);
+            return;
+        }
+        const stmt = this.db.prepare(`INSERT INTO project_index_watch_state (
+        project_id, scope_user_id, scope_agent_id, last_source_rev, last_checksum_snapshot, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?)`);
+        stmt.run(input.project_id, scopeUserId, scopeAgentId, input.last_source_rev, checksumJson, input.updated_at);
+    }
+    normalizeProjectId(projectId) {
+        return String(projectId || "").trim();
+    }
+    normalizeProjectName(projectName) {
+        return String(projectName || "").trim();
+    }
+    normalizeRepoRoot(repoRoot) {
+        const normalized = String(repoRoot || "").trim();
+        return normalized || null;
+    }
+    normalizeRepoRemote(repoRemote) {
+        const normalized = String(repoRemote || "").trim();
+        return normalized || null;
+    }
+    parseJsonArrayField(raw) {
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    normalizeStringArray(input) {
+        if (!Array.isArray(input))
+            return [];
+        return this.uniqueSorted(input
+            .map((item) => String(item || "").trim())
+            .filter(Boolean));
+    }
+    uniqueSorted(values) {
+        return Array.from(new Set(values.map((v) => String(v || "").trim()).filter(Boolean))).sort((a, b) => a.localeCompare(b));
+    }
+    inferBackfillAliases(project, existingAliases, source) {
+        const candidates = new Set();
+        if (source === "repo_root" || source === "mixed") {
+            if (project.repo_root) {
+                const parts = project.repo_root.replace(/\\/g, "/").split("/").filter(Boolean);
+                const leaf = parts[parts.length - 1] || "";
+                const normalized = this.normalizeProjectAlias(leaf);
+                if (normalized)
+                    candidates.add(normalized);
+            }
+        }
+        if (source === "repo_remote" || source === "mixed") {
+            if (project.repo_remote_primary) {
+                const remote = String(project.repo_remote_primary);
+                const m = remote.match(/[:\/]([^/]+?)\.git$/i) || remote.match(/[:\/]([^/]+?)$/i);
+                const repoName = m?.[1] || "";
+                const normalized = this.normalizeProjectAlias(repoName);
+                if (normalized)
+                    candidates.add(normalized);
+            }
+        }
+        const filtered = Array.from(candidates).filter((a) => !existingAliases.has(a));
+        return filtered.sort((a, b) => a.localeCompare(b));
+    }
+    inferBackfillTrackerMappings(scopeUserId, scopeAgentId, projectId, project, source) {
+        const result = [];
+        if (source === "repo_remote" || source === "mixed") {
+            const remote = String(project.repo_remote_primary || "").trim();
+            if (remote.includes("github.com")) {
+                result.push({
+                    tracker_type: "github",
+                    tracker_space_key: null,
+                    tracker_project_id: null,
+                    default_epic_key: null,
+                    confidence: 0.7,
+                    source: "repo_remote",
+                });
+            }
+        }
+        if (source === "task_registry" || source === "mixed") {
+            const stmt = this.db.prepare(`SELECT tracker_issue_key FROM task_registry
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ? AND tracker_issue_key IS NOT NULL AND tracker_issue_key != ''
+         ORDER BY updated_at DESC LIMIT 200`);
+            const rows = stmt.all(scopeUserId, scopeAgentId, projectId);
+            const keys = rows.map((r) => String(r.tracker_issue_key || "").trim()).filter(Boolean);
+            const jiraLike = keys
+                .map((key) => key.match(/^([A-Z][A-Z0-9_]+)-\d+$/)?.[1] || null)
+                .filter((x) => Boolean(x));
+            if (jiraLike.length > 0) {
+                const counts = new Map();
+                for (const p of jiraLike)
+                    counts.set(p, (counts.get(p) || 0) + 1);
+                const top = Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0];
+                if (top) {
+                    result.push({
+                        tracker_type: "jira",
+                        tracker_space_key: top[0],
+                        tracker_project_id: null,
+                        default_epic_key: `${top[0]}-1`,
+                        confidence: Math.min(0.95, 0.55 + top[1] * 0.03),
+                        source: "task_registry",
+                    });
+                }
+            }
+        }
+        const dedup = new Map();
+        for (const item of result) {
+            const key = `${item.tracker_type}:${item.tracker_space_key || ""}:${item.default_epic_key || ""}`;
+            const prev = dedup.get(key);
+            if (!prev || item.confidence > prev.confidence)
+                dedup.set(key, item);
+        }
+        return Array.from(dedup.values()).sort((a, b) => b.confidence - a.confidence);
+    }
+    pickPrimaryAlias(existingAliases, project) {
+        const aliases = Array.from(existingAliases).filter(Boolean).sort((a, b) => a.localeCompare(b));
+        if (aliases.length > 0)
+            return aliases[0];
+        const fromName = this.normalizeProjectAlias(project.project_name);
+        if (fromName)
+            return fromName;
+        return this.normalizeProjectAlias(project.project_id) || "project";
+    }
+    upsertMigrationState(scopeUserId, scopeAgentId, input) {
+        const existingStmt = this.db.prepare(`SELECT migration_id FROM migration_state
+       WHERE scope_user_id = ? AND scope_agent_id = ? AND migration_id = ?`);
+        const existing = existingStmt.get(scopeUserId, scopeAgentId, input.migration_id);
+        if (existing) {
+            const updateStmt = this.db.prepare(`UPDATE migration_state
+         SET schema_from = ?, schema_to = ?, applied_at = ?, status = ?, notes = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND migration_id = ?`);
+            updateStmt.run(input.schema_from, input.schema_to, input.applied_at, input.status, input.notes || null, scopeUserId, scopeAgentId, input.migration_id);
+            return;
+        }
+        const insertStmt = this.db.prepare(`INSERT INTO migration_state (
+        migration_id, scope_user_id, scope_agent_id, schema_from, schema_to, applied_at, status, notes
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        insertStmt.run(input.migration_id, scopeUserId, scopeAgentId, input.schema_from, input.schema_to, input.applied_at, input.status, input.notes || null);
+    }
+    rowToTaskRecord(row) {
+        return {
+            task_id: row.task_id,
+            scope_user_id: row.scope_user_id,
+            scope_agent_id: row.scope_agent_id,
+            project_id: row.project_id,
+            task_title: row.task_title,
+            task_type: row.task_type,
+            task_status: row.task_status,
+            parent_task_id: row.parent_task_id,
+            related_task_ids: this.parseJsonArrayField(row.related_task_ids),
+            files_touched: this.parseJsonArrayField(row.files_touched),
+            symbols_touched: this.parseJsonArrayField(row.symbols_touched),
+            commit_refs: this.parseJsonArrayField(row.commit_refs),
+            diff_refs: this.parseJsonArrayField(row.diff_refs),
+            decision_notes: row.decision_notes,
+            tracker_issue_key: row.tracker_issue_key,
+            updated_at: row.updated_at,
+        };
+    }
+    computeMissingRegistrationFields(project, alias) {
+        const missing = [];
+        if (!project.project_id)
+            missing.push("project_id");
+        if (!alias)
+            missing.push("project_alias");
+        if (!project.project_name)
+            missing.push("project_name");
+        return missing;
+    }
+    computeRegistrationCompleteness(project, alias) {
+        const requiredTotal = 3;
+        const requiredPresent = [project.project_id, alias, project.project_name].filter(Boolean).length;
+        const optionalTotal = 3;
+        const optionalPresent = [project.repo_root, project.repo_remote_primary, project.active_version].filter(Boolean).length;
+        return Math.round((requiredPresent / requiredTotal) * 80 + (optionalPresent / optionalTotal) * 20);
+    }
+    upsertProjectAlias(scopeUserId, scopeAgentId, projectId, projectAlias, isPrimary, now, allowAliasUpdate) {
+        const existingAlias = this.getProjectAlias(scopeUserId, scopeAgentId, projectAlias);
+        if (existingAlias) {
+            if (existingAlias.project_id !== projectId && !allowAliasUpdate) {
+                throw new Error(`project_alias \"${projectAlias}\" is already mapped to another project_id`);
+            }
+            const stmt = this.db.prepare(`UPDATE project_aliases SET project_id = ?, is_primary = ?, updated_at = ? WHERE id = ?`);
+            stmt.run(projectId, isPrimary ? 1 : 0, now, existingAlias.id);
+            return;
+        }
+        const insertStmt = this.db.prepare(`INSERT INTO project_aliases (id, project_id, scope_user_id, scope_agent_id, project_alias, is_primary, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        insertStmt.run(randomUUID(), projectId, scopeUserId, scopeAgentId, projectAlias, isPrimary ? 1 : 0, now, now);
+    }
+    upsertProjectRegistrationState(scopeUserId, scopeAgentId, input) {
+        const now = new Date().toISOString();
+        const existing = this.getProjectRegistrationState(scopeUserId, scopeAgentId, input.project_id);
+        const missingJson = JSON.stringify(input.missing_required_fields || []);
+        if (existing) {
+            const stmt = this.db.prepare(`UPDATE project_registration_state
+         SET registration_status = ?, validation_status = ?, validation_notes = ?, completeness_score = ?, missing_required_fields = ?, last_validated_at = ?, updated_at = ?
+         WHERE scope_user_id = ? AND scope_agent_id = ? AND project_id = ?`);
+            stmt.run(input.registration_status, input.validation_status, input.validation_notes, input.completeness_score, missingJson, input.last_validated_at, now, scopeUserId, scopeAgentId, input.project_id);
+        }
+        else {
+            const stmt = this.db.prepare(`INSERT INTO project_registration_state (project_id, scope_user_id, scope_agent_id, registration_status, validation_status, validation_notes, completeness_score, missing_required_fields, last_validated_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            stmt.run(input.project_id, scopeUserId, scopeAgentId, input.registration_status, input.validation_status, input.validation_notes, input.completeness_score, missingJson, input.last_validated_at, now);
+        }
+        const state = this.getProjectRegistrationState(scopeUserId, scopeAgentId, input.project_id);
+        if (!state)
+            throw new Error("failed to persist project_registration_state");
+        return state;
+    }
     rowToSlot(row) {
         let parsedValue;
         try {