recallx 1.0.0

package/app/server/repositories.js

@@ -0,0 +1,2992 @@
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { getSqliteVecExtensionRuntime } from "./db.js";
+import { AppError, assertPresent } from "./errors.js";
+import { appendCurrentTelemetryDetails } from "./observability.js";
+import { computeMaintainedScores } from "./relation-scoring.js";
+import { buildSemanticChunks, buildSemanticDocumentText, normalizeTagList } from "./semantic/chunker.js";
+import { embedSemanticQueryText, normalizeSemanticProviderConfig, resolveSemanticEmbeddingProvider } from "./semantic/provider.js";
+import { createVectorIndexStore, VectorIndexStoreError } from "./semantic/vector-store.js";
+import { checksumText, createId, isPathWithinRoot, nowIso, parseJson, stableSummary } from "./utils.js";
+function normalizeArtifactPath(value) {
+    const withForwardSlashes = value.replace(/[\\/]+/g, "/");
+    const normalized = path.posix.normalize(withForwardSlashes);
+    return normalized === "." ? "" : normalized;
+}
+const SUMMARY_UPDATED_AT_KEY = "summaryUpdatedAt";
+const SUMMARY_SOURCE_KEY = "summarySource";
+const SEARCH_TAG_INDEX_VERSION = 1;
+const SEARCH_ACTIVITY_FTS_VERSION = 1;
+const SEMANTIC_INDEX_STATUS_VALUES = ["pending", "processing", "stale", "ready", "failed"];
+const SEMANTIC_ISSUE_STATUS_VALUES = ["pending", "stale", "failed"];
+const DEFAULT_SEMANTIC_CHUNK_AGGREGATION = "max";
+const SEMANTIC_TOP_K_CHUNK_COUNT = 2;
+const SEMANTIC_CONFIGURATION_CHANGED_REASON = "embedding.configuration_changed";
+const SEMANTIC_CONFIGURATION_SWEEP_LIMIT = 100;
+const SEMANTIC_PENDING_TRANSITION_KEYS_SETTING = "search.semantic.configuration.pendingKeys";
+const SEARCH_FEEDBACK_WINDOW_PADDING = 20;
+const SEARCH_FEEDBACK_MAX_WINDOW = 100;
+const ACTIVITY_RESULT_CAP_PER_TARGET = 2;
+const WORKSPACE_CAPTURE_INBOX_KEY = "workspace.capture.inboxNodeId";
+const SEARCH_FALLBACK_TOKEN_LIMIT = 5;
+const workspaceInboxSource = {
+    actorType: "system",
+    actorLabel: "RecallX",
+    toolName: "recallx-system"
+};
+function normalizeSearchText(value) {
+    return (value ?? "").normalize("NFKC").toLowerCase();
+}
+function tokenizeSearchQuery(query, maxTokens = 12) {
+    const matches = normalizeSearchText(query).match(/[\p{L}\p{N}]{2,}/gu) ?? [];
+    return Array.from(new Set(matches)).slice(0, maxTokens);
+}
+function createSearchFieldMatcher(query) {
+    const trimmedQuery = normalizeSearchText(query).trim();
+    if (!trimmedQuery) {
+        return null;
+    }
+    const tokens = tokenizeSearchQuery(trimmedQuery);
+    return {
+        trimmedQuery,
+        matchTerms: tokens.length ? tokens : [trimmedQuery]
+    };
+}
+function collectMatchedFields(matcher, candidates) {
+    if (!matcher) {
+        return [];
+    }
+    const matches = new Set();
+    for (const candidate of candidates) {
+        const haystack = normalizeSearchText(candidate.value);
+        if (!haystack) {
+            continue;
+        }
+        if (haystack.includes(matcher.trimmedQuery) || matcher.matchTerms.some((term) => haystack.includes(term))) {
+            matches.add(candidate.field);
+        }
+    }
+    return [...matches];
+}
+function buildSearchMatchReason(strategy, matchedFields) {
+    return {
+        strategy,
+        matchedFields
+    };
+}
+function mergeMatchReasons(left, right, strategy) {
+    return {
+        strategy,
+        matchedFields: Array.from(new Set([...(left?.matchedFields ?? []), ...(right?.matchedFields ?? [])]))
+    };
+}
+function computeWorkspaceRankBonus(index, total) {
+    if (total <= 0) {
+        return 0;
+    }
+    return Math.max(0, Math.round(((total - index) / total) * 24));
+}
+function computeWorkspaceSmartScore(input) {
+    return (computeWorkspaceRankBonus(input.index, input.total) +
+        computeWorkspaceRecencyBonusFromAge(input.nowMs - new Date(input.timestamp).getTime(), input.resultType) +
+        (input.resultType === "activity" ? 4 : 0) -
+        (input.contested ? 20 : 0));
+}
+function computeWorkspaceRecencyBonusFromAge(ageMs, resultType) {
+    if (ageMs <= 60 * 60 * 1000)
+        return resultType === "activity" ? 16 : 12;
+    if (ageMs <= 24 * 60 * 60 * 1000)
+        return resultType === "activity" ? 12 : 8;
+    if (ageMs <= 7 * 24 * 60 * 60 * 1000)
+        return resultType === "activity" ? 7 : 5;
+    if (ageMs <= 30 * 24 * 60 * 60 * 1000)
+        return resultType === "activity" ? 3 : 2;
+    return 0;
+}
+function clampSearchFeedbackDelta(value) {
+    return Math.min(Math.max(value, -2), 2);
+}
+function computeSearchFeedbackDelta(verdict, confidence) {
+    switch (verdict) {
+        case "useful":
+            return confidence;
+        case "not_useful":
+            return -confidence;
+        default:
+            return 0;
+    }
+}
+function clampConfidence(value) {
+    return Math.min(Math.max(value, 0), 1);
+}
+function normalizeTagValue(tag) {
+    return tag.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function readBooleanSetting(settings, key, fallback) {
+    return typeof settings[key] === "boolean" ? Boolean(settings[key]) : fallback;
+}
+function readStringSetting(settings, key) {
+    return typeof settings[key] === "string" ? String(settings[key]) : null;
+}
+function readNumberSetting(settings, key, fallback) {
+    const value = settings[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function normalizeSemanticIndexBackend(value) {
+    return value === "sqlite-vec" ? "sqlite-vec" : "sqlite";
+}
+function resolveActiveSemanticIndexBackend(configuredBackend, sqliteVecLoaded) {
+    if (configuredBackend === "sqlite-vec" && sqliteVecLoaded) {
+        return "sqlite-vec";
+    }
+    return "sqlite";
+}
+function resolveSemanticExtensionStatus(configuredBackend, sqliteVecLoaded) {
+    if (configuredBackend !== "sqlite-vec") {
+        return "disabled";
+    }
+    return sqliteVecLoaded ? "loaded" : "fallback";
+}
+function resolveSemanticEmbeddingSignature(input) {
+    const normalized = normalizeSemanticProviderConfig(input);
+    const provider = resolveSemanticEmbeddingProvider(normalized);
+    return {
+        provider: provider?.provider ?? normalized.provider,
+        model: provider?.model ?? normalized.model,
+        version: provider?.version ?? null
+    };
+}
+function readSemanticIndexSettingSnapshot(settings, runtime) {
+    const signature = resolveSemanticEmbeddingSignature({
+        provider: readStringSetting(settings, "search.semantic.provider"),
+        model: readStringSetting(settings, "search.semantic.model")
+    });
+    const configuredIndexBackend = normalizeSemanticIndexBackend(settings["search.semantic.indexBackend"]);
+    return {
+        enabled: readBooleanSetting(settings, "search.semantic.enabled", false),
+        provider: signature.provider,
+        model: signature.model,
+        version: signature.version,
+        configuredIndexBackend,
+        indexBackend: resolveActiveSemanticIndexBackend(configuredIndexBackend, runtime.sqliteVecLoaded),
+        extensionStatus: resolveSemanticExtensionStatus(configuredIndexBackend, runtime.sqliteVecLoaded),
+        extensionLoadError: configuredIndexBackend === "sqlite-vec" && !runtime.sqliteVecLoaded ? runtime.sqliteVecLoadError : null,
+        chunkEnabled: readBooleanSetting(settings, "search.semantic.chunk.enabled", false)
+    };
+}
+function shouldReindexForSemanticConfigChange(previous, next) {
+    return (previous.enabled !== next.enabled ||
+        previous.chunkEnabled !== next.chunkEnabled ||
+        previous.provider !== next.provider ||
+        previous.model !== next.model ||
+        previous.version !== next.version);
+}
+function buildSemanticContentHash(input) {
+    return checksumText(JSON.stringify({
+        title: input.title ?? "",
+        body: input.body ?? "",
+        summary: input.summary ?? "",
+        tags: normalizeTagList(input.tags)
+    }));
+}
+function semanticIssueStatusRank(status) {
+    switch (status) {
+        case "failed":
+            return 0;
+        case "stale":
+            return 1;
+        default:
+            return 2;
+    }
+}
+function encodeSemanticIssueCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeSemanticIssueCursor(cursor) {
+    if (!cursor) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (typeof parsed.statusRank !== "number" ||
+            !Number.isFinite(parsed.statusRank) ||
+            typeof parsed.updatedAt !== "string" ||
+            !parsed.updatedAt ||
+            typeof parsed.nodeId !== "string" ||
+            !parsed.nodeId) {
+            return null;
+        }
+        return {
+            statusRank: parsed.statusRank,
+            updatedAt: parsed.updatedAt,
+            nodeId: parsed.nodeId
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeSemanticChunkAggregation(value) {
+    return value === "topk_mean" ? "topk_mean" : DEFAULT_SEMANTIC_CHUNK_AGGREGATION;
+}
+function aggregateChunkSimilarities(similarities, aggregation) {
+    if (!similarities.length) {
+        return 0;
+    }
+    if (aggregation === "topk_mean") {
+        const topK = [...similarities].sort((left, right) => right - left).slice(0, SEMANTIC_TOP_K_CHUNK_COUNT);
+        return topK.reduce((sum, value) => sum + value, 0) / topK.length;
+    }
+    return Math.max(...similarities);
+}
+function updateSemanticSimilarityAccumulator(accumulator, similarity, aggregation) {
+    accumulator.matchedChunks += 1;
+    accumulator.maxSimilarity = Math.max(accumulator.maxSimilarity, similarity);
+    if (aggregation !== "topk_mean") {
+        return;
+    }
+    accumulator.topSimilarities.push(similarity);
+    accumulator.topSimilarities.sort((left, right) => right - left);
+    if (accumulator.topSimilarities.length > SEMANTIC_TOP_K_CHUNK_COUNT) {
+        accumulator.topSimilarities.length = SEMANTIC_TOP_K_CHUNK_COUNT;
+    }
+}
+function normalizeSemanticBonusSimilarity(similarity, minSimilarity) {
+    if (!Number.isFinite(similarity) || similarity < minSimilarity || minSimilarity >= 1) {
+        return 0;
+    }
+    return Math.min(1, Math.max(0, similarity - minSimilarity) / (1 - minSimilarity));
+}
+function computeSemanticRetrievalRank(similarity, settings) {
+    const normalizedSimilarity = normalizeSemanticBonusSimilarity(similarity, settings.minSimilarity);
+    return Number((normalizedSimilarity * settings.maxBonus).toFixed(4));
+}
+function bucketSemanticQueryLength(length) {
+    if (length <= 12) {
+        return "short";
+    }
+    if (length <= 32) {
+        return "medium";
+    }
+    return "long";
+}
+function mapNode(row) {
+    return {
+        id: String(row.id),
+        type: row.type,
+        status: row.status,
+        canonicality: row.canonicality,
+        visibility: String(row.visibility),
+        title: row.title ? String(row.title) : null,
+        body: row.body ? String(row.body) : null,
+        summary: row.summary ? String(row.summary) : null,
+        createdBy: row.created_by ? String(row.created_by) : null,
+        sourceType: row.source_type ? String(row.source_type) : null,
+        sourceLabel: row.source_label ? String(row.source_label) : null,
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        tags: parseJson(row.tags_json, []),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapRelation(row) {
+    return {
+        id: String(row.id),
+        fromNodeId: String(row.from_node_id),
+        toNodeId: String(row.to_node_id),
+        relationType: row.relation_type,
+        status: row.status,
+        createdBy: row.created_by ? String(row.created_by) : null,
+        sourceType: row.source_type ? String(row.source_type) : null,
+        sourceLabel: row.source_label ? String(row.source_label) : null,
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapActivity(row) {
+    return {
+        id: String(row.id),
+        targetNodeId: String(row.target_node_id),
+        activityType: row.activity_type,
+        body: row.body ? String(row.body) : null,
+        createdBy: row.created_by ? String(row.created_by) : null,
+        sourceType: row.source_type ? String(row.source_type) : null,
+        sourceLabel: row.source_label ? String(row.source_label) : null,
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapInferredRelation(row) {
+    return {
+        id: String(row.id),
+        fromNodeId: String(row.from_node_id),
+        toNodeId: String(row.to_node_id),
+        relationType: row.relation_type,
+        baseScore: Number(row.base_score),
+        usageScore: Number(row.usage_score),
+        finalScore: Number(row.final_score),
+        status: row.status,
+        generator: String(row.generator),
+        evidence: parseJson(row.evidence_json, {}),
+        lastComputedAt: String(row.last_computed_at),
+        expiresAt: row.expires_at ? String(row.expires_at) : null,
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapRelationUsageEvent(row) {
+    return {
+        id: String(row.id),
+        relationId: String(row.relation_id),
+        relationSource: row.relation_source,
+        eventType: row.event_type,
+        sessionId: row.session_id ? String(row.session_id) : null,
+        runId: row.run_id ? String(row.run_id) : null,
+        actorType: row.actor_type ? String(row.actor_type) : null,
+        actorLabel: row.actor_label ? String(row.actor_label) : null,
+        toolName: row.tool_name ? String(row.tool_name) : null,
+        delta: Number(row.delta),
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapSearchFeedbackEvent(row) {
+    return {
+        id: String(row.id),
+        resultType: String(row.result_type),
+        resultId: String(row.result_id),
+        verdict: String(row.verdict),
+        query: row.query ? String(row.query) : null,
+        sessionId: row.session_id ? String(row.session_id) : null,
+        runId: row.run_id ? String(row.run_id) : null,
+        actorType: row.actor_type ? String(row.actor_type) : null,
+        actorLabel: row.actor_label ? String(row.actor_label) : null,
+        toolName: row.tool_name ? String(row.tool_name) : null,
+        confidence: Number(row.confidence),
+        delta: Number(row.delta),
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapGovernanceEvent(row) {
+    return {
+        id: String(row.id),
+        entityType: row.entity_type,
+        entityId: String(row.entity_id),
+        eventType: row.event_type,
+        previousState: row.previous_state ? row.previous_state : null,
+        nextState: row.next_state,
+        confidence: Number(row.confidence),
+        reason: String(row.reason),
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapGovernanceState(row) {
+    return {
+        entityType: row.entity_type,
+        entityId: String(row.entity_id),
+        state: row.state,
+        confidence: Number(row.confidence),
+        reasons: parseJson(row.reasons_json, []),
+        lastEvaluatedAt: String(row.last_evaluated_at),
+        lastTransitionAt: String(row.last_transition_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapArtifact(row) {
+    return {
+        id: String(row.id),
+        nodeId: String(row.node_id),
+        path: String(row.path),
+        mimeType: row.mime_type ? String(row.mime_type) : null,
+        sizeBytes: row.size_bytes ? Number(row.size_bytes) : null,
+        checksum: row.checksum ? String(row.checksum) : null,
+        createdBy: row.created_by ? String(row.created_by) : null,
+        sourceLabel: row.source_label ? String(row.source_label) : null,
+        createdAt: String(row.created_at),
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapProvenance(row) {
+    return {
+        id: String(row.id),
+        entityType: String(row.entity_type),
+        entityId: String(row.entity_id),
+        operationType: String(row.operation_type),
+        actorType: String(row.actor_type),
+        actorLabel: row.actor_label ? String(row.actor_label) : null,
+        toolName: row.tool_name ? String(row.tool_name) : null,
+        toolVersion: row.tool_version ? String(row.tool_version) : null,
+        timestamp: String(row.timestamp),
+        inputRef: row.input_ref ? String(row.input_ref) : null,
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function mapLegacyReviewQueue(row) {
+    return {
+        id: String(row.id),
+        entityType: String(row.entity_type),
+        entityId: String(row.entity_id),
+        reviewType: String(row.review_type),
+        proposedBy: row.proposed_by ? String(row.proposed_by) : null,
+        createdAt: String(row.created_at),
+        status: String(row.status),
+        notes: row.notes ? String(row.notes) : null,
+        metadata: parseJson(row.metadata_json, {})
+    };
+}
+function withSummaryMetadata(metadata, summaryUpdatedAt, summarySource) {
+    return {
+        ...metadata,
+        [SUMMARY_UPDATED_AT_KEY]: summaryUpdatedAt,
+        [SUMMARY_SOURCE_KEY]: summarySource
+    };
+}
+function mapIntegration(row) {
+    return {
+        id: String(row.id),
+        name: String(row.name),
+        kind: String(row.kind),
+        status: String(row.status),
+        capabilities: parseJson(row.capabilities_json, []),
+        config: parseJson(row.config_json, {}),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at)
+    };
+}
+const RELATION_USAGE_ROLLUP_STATE_ID = "bootstrap";
+export class RecallXRepository {
+    db;
+    workspaceRoot;
+    workspaceKey;
+    sqliteVectorIndexStore;
+    sqliteVecVectorIndexStore;
+    sqliteVecRuntime;
+    constructor(db, workspaceRoot) {
+        this.db = db;
+        this.workspaceRoot = workspaceRoot;
+        this.workspaceKey = checksumText(path.resolve(workspaceRoot));
+        this.sqliteVecRuntime = getSqliteVecExtensionRuntime(db);
+        this.sqliteVectorIndexStore = createVectorIndexStore(db, {
+            backend: "sqlite",
+            workspaceKey: this.workspaceKey
+        });
+        this.sqliteVecVectorIndexStore = createVectorIndexStore(db, {
+            backend: "sqlite-vec",
+            workspaceKey: this.workspaceKey
+        });
+    }
+    resolveVectorIndexStore(backend) {
+        return backend === "sqlite-vec" ? this.sqliteVecVectorIndexStore : this.sqliteVectorIndexStore;
+    }
+    runInTransaction(operation) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = operation();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                // ignore rollback failures and rethrow the original error
+            }
+            throw error;
+        }
+    }
+    ensureRelationUsageRollupState(updatedAt = nowIso()) {
+        this.db
+            .prepare(`INSERT OR IGNORE INTO relation_usage_rollup_state (id, last_event_rowid, updated_at)
+         VALUES (?, 0, ?)`)
+            .run(RELATION_USAGE_ROLLUP_STATE_ID, updatedAt);
+    }
+    getRelationUsageRollupWatermark() {
+        this.ensureRelationUsageRollupState();
+        const row = this.db
+            .prepare(`SELECT last_event_rowid FROM relation_usage_rollup_state WHERE id = ?`)
+            .get(RELATION_USAGE_ROLLUP_STATE_ID);
+        return Number(row?.last_event_rowid ?? 0);
+    }
+    syncRelationUsageRollups() {
+        const lastEventRowid = this.getRelationUsageRollupWatermark();
+        const maxRowidRow = this.db
+            .prepare(`SELECT COALESCE(MAX(rowid), 0) AS max_rowid FROM relation_usage_events`)
+            .get();
+        const maxRowid = Number(maxRowidRow.max_rowid ?? 0);
+        if (maxRowid <= lastEventRowid) {
+            return;
+        }
+        const updatedAt = nowIso();
+        this.runInTransaction(() => {
+            this.db
+                .prepare(`INSERT INTO relation_usage_rollups (
+             relation_id, total_delta, event_count, last_event_at, last_event_rowid, updated_at
+           )
+           SELECT
+             relation_id,
+             COALESCE(SUM(delta), 0) AS total_delta,
+             COUNT(*) AS event_count,
+             MAX(created_at) AS last_event_at,
+             MAX(rowid) AS last_event_rowid,
+             ? AS updated_at
+           FROM relation_usage_events
+           WHERE rowid > ?
+           GROUP BY relation_id
+           ON CONFLICT(relation_id) DO UPDATE SET
+             total_delta = total_delta + excluded.total_delta,
+             event_count = event_count + excluded.event_count,
+             last_event_at = CASE
+               WHEN excluded.last_event_at > last_event_at THEN excluded.last_event_at
+               ELSE last_event_at
+             END,
+             last_event_rowid = CASE
+               WHEN excluded.last_event_rowid > last_event_rowid THEN excluded.last_event_rowid
+               ELSE last_event_rowid
+             END,
+             updated_at = excluded.updated_at`)
+                .run(updatedAt, lastEventRowid);
+            this.db
+                .prepare(`UPDATE relation_usage_rollup_state
+           SET last_event_rowid = ?, updated_at = ?
+           WHERE id = ?`)
+                .run(maxRowid, updatedAt, RELATION_USAGE_ROLLUP_STATE_ID);
+        });
+    }
+    touchNode(id) {
+        this.db.prepare(`UPDATE nodes SET updated_at = ? WHERE id = ?`).run(nowIso(), id);
+    }
+    upsertSemanticIndexState(params) {
+        const updatedAt = params.updatedAt ?? nowIso();
+        this.db
+            .prepare(`INSERT INTO node_index_state (
+           node_id, content_hash, embedding_status, embedding_provider, embedding_model, embedding_version, stale_reason, updated_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(node_id) DO UPDATE SET
+           content_hash = excluded.content_hash,
+           embedding_status = excluded.embedding_status,
+           embedding_provider = excluded.embedding_provider,
+           embedding_model = excluded.embedding_model,
+           embedding_version = excluded.embedding_version,
+           stale_reason = excluded.stale_reason,
+           updated_at = excluded.updated_at`)
+            .run(params.nodeId, params.contentHash ?? null, params.status, params.embeddingProvider ?? null, params.embeddingModel ?? null, params.embeddingVersion ?? null, params.staleReason ?? null, updatedAt);
+    }
+    markNodeSemanticIndexState(nodeId, reason, input = {}) {
+        this.upsertSemanticIndexState({
+            nodeId,
+            status: input.status ?? "pending",
+            staleReason: reason,
+            contentHash: input.contentHash,
+            updatedAt: input.updatedAt
+        });
+    }
+    syncNodeTags(nodeId, tags) {
+        const normalizedTags = normalizeTagList(tags);
+        this.db.prepare(`DELETE FROM node_tags WHERE node_id = ?`).run(nodeId);
+        if (!normalizedTags.length) {
+            return;
+        }
+        const insertStatement = this.db.prepare(`INSERT INTO node_tags (node_id, tag) VALUES (?, ?)`);
+        for (const tag of normalizedTags) {
+            insertStatement.run(nodeId, tag);
+        }
+    }
+    readSemanticIndexSettings() {
+        const settings = this.getSettings([
+            "search.semantic.enabled",
+            "search.semantic.provider",
+            "search.semantic.model",
+            "search.semantic.indexBackend",
+            "search.semantic.chunk.enabled",
+            "search.semantic.chunk.aggregation",
+            "search.semantic.workspaceFallback.enabled"
+        ]);
+        return {
+            ...readSemanticIndexSettingSnapshot(settings, {
+                sqliteVecLoaded: this.sqliteVecRuntime.isLoaded,
+                sqliteVecLoadError: this.sqliteVecRuntime.loadError
+            }),
+            chunkAggregation: normalizeSemanticChunkAggregation(settings["search.semantic.chunk.aggregation"]),
+            workspaceFallbackEnabled: readBooleanSetting(settings, "search.semantic.workspaceFallback.enabled", false)
+        };
+    }
+    getSemanticAugmentationSettings() {
+        const settings = this.getSettings([
+            "search.semantic.augmentation.minSimilarity",
+            "search.semantic.augmentation.maxBonus"
+        ]);
+        return {
+            minSimilarity: Math.min(Math.max(readNumberSetting(settings, "search.semantic.augmentation.minSimilarity", 0.2), 0), 1),
+            maxBonus: Math.max(readNumberSetting(settings, "search.semantic.augmentation.maxBonus", 18), 0)
+        };
+    }
+    markSemanticConfigurationMismatchesStale(limit = SEMANTIC_CONFIGURATION_SWEEP_LIMIT) {
+        const settings = this.readSemanticIndexSettings();
+        const rows = this.db
+            .prepare(`SELECT nis.node_id
+         FROM node_index_state nis
+         JOIN nodes n ON n.id = nis.node_id
+         WHERE n.status IN ('active', 'draft')
+           AND nis.embedding_status = 'ready'
+           AND (
+             nis.embedding_provider IS NOT ?
+             OR nis.embedding_model IS NOT ?
+             OR nis.embedding_version IS NOT ?
+           )
+         ORDER BY nis.updated_at ASC
+         LIMIT ?`)
+            .all(settings.provider, settings.model, settings.version, limit);
+        if (!rows.length) {
+            return 0;
+        }
+        const updatedAt = nowIso();
+        const updateStatement = this.db.prepare(`UPDATE node_index_state
+       SET embedding_status = 'stale', stale_reason = ?, updated_at = ?
+       WHERE node_id = ? AND embedding_status = 'ready'`);
+        for (const row of rows) {
+            updateStatement.run(SEMANTIC_CONFIGURATION_CHANGED_REASON, updatedAt, String(row.node_id));
+        }
+        return rows.length;
+    }
+    queueSemanticConfigurationReindex(reason = SEMANTIC_CONFIGURATION_CHANGED_REASON) {
+        const nodeIds = this.listSemanticIndexTargetNodeIds();
+        const updatedAt = nowIso();
+        this.queueSemanticReindexForNodeIds(nodeIds, reason, updatedAt);
+        this.writeSetting("search.semantic.last_backfill_at", updatedAt);
+    }
+    readPendingSemanticTransitionKeys() {
+        const value = this.getSettings([SEMANTIC_PENDING_TRANSITION_KEYS_SETTING])[SEMANTIC_PENDING_TRANSITION_KEYS_SETTING];
+        if (!Array.isArray(value)) {
+            return [];
+        }
+        return value
+            .filter((item) => typeof item === "string")
+            .filter((item) => item === "search.semantic.provider" || item === "search.semantic.model");
+    }
+    writePendingSemanticTransitionKeys(keys) {
+        this.writeSetting(SEMANTIC_PENDING_TRANSITION_KEYS_SETTING, keys);
+    }
+    updateSemanticSetting(key, value) {
+        const previousSettings = this.readSemanticIndexSettings();
+        this.writeSetting(key, value);
+        const nextSettings = this.readSemanticIndexSettings();
+        if (!shouldReindexForSemanticConfigChange(previousSettings, nextSettings)) {
+            if (key === "search.semantic.provider" || key === "search.semantic.model") {
+                const pendingKeys = new Set(this.readPendingSemanticTransitionKeys());
+                pendingKeys.delete(key);
+                this.writePendingSemanticTransitionKeys([...pendingKeys]);
+            }
+            return;
+        }
+        if (key === "search.semantic.provider" || key === "search.semantic.model") {
+            const pendingKeys = new Set(this.readPendingSemanticTransitionKeys());
+            pendingKeys.add(key);
+            if (!pendingKeys.has("search.semantic.provider") || !pendingKeys.has("search.semantic.model")) {
+                this.writePendingSemanticTransitionKeys([...pendingKeys]);
+                return;
+            }
+            this.writePendingSemanticTransitionKeys([]);
+        }
+        this.queueSemanticConfigurationReindex();
+    }
+    listPendingSemanticIndexRows(limit = 25) {
+        const rows = this.db
+            .prepare(`SELECT node_id, content_hash, embedding_status, stale_reason, updated_at
+         FROM node_index_state
+         WHERE embedding_status IN ('pending', 'stale')
+         ORDER BY updated_at ASC
+         LIMIT ?`)
+            .all(limit);
+        return rows.map((row) => ({
+            nodeId: String(row.node_id),
+            contentHash: row.content_hash ? String(row.content_hash) : null,
+            embeddingStatus: String(row.embedding_status),
+            staleReason: row.stale_reason ? String(row.stale_reason) : null,
+            updatedAt: String(row.updated_at)
+        }));
+    }
+    replaceSemanticChunks(nodeId, chunks, updatedAt) {
+        this.db.prepare(`DELETE FROM node_chunks WHERE node_id = ?`).run(nodeId);
+        if (!chunks.length) {
+            return;
+        }
+        const insertStatement = this.db.prepare(`INSERT INTO node_chunks (
+         node_id, ordinal, chunk_hash, chunk_text, token_count, start_offset, end_offset, updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const chunk of chunks) {
+            insertStatement.run(nodeId, chunk.ordinal, chunk.chunkHash, chunk.chunkText, chunk.tokenCount, chunk.startOffset, chunk.endOffset, updatedAt);
+        }
+    }
+    replaceSemanticEmbeddings(nodeId, params) {
+        this.db.prepare(`DELETE FROM node_embeddings WHERE owner_type = 'node' AND owner_id = ?`).run(nodeId);
+        if (!params.rows.length) {
+            return;
+        }
+        const insertStatement = this.db.prepare(`INSERT INTO node_embeddings (
+         owner_type, owner_id, chunk_ordinal, vector_ref, vector_blob, embedding_provider, embedding_model, embedding_version,
+         content_hash, status, created_at, updated_at
+       ) VALUES ('node', ?, ?, ?, ?, ?, ?, ?, ?, 'ready', ?, ?)`);
+        for (const row of params.rows) {
+            insertStatement.run(nodeId, row.chunkOrdinal, row.vectorRef, row.vectorBlob, params.provider, params.model, params.version, params.contentHash, params.updatedAt, params.updatedAt);
+        }
+    }
+    async syncSemanticDelete(vectorIndexStore, nodeId, finishedAt, params) {
+        await vectorIndexStore.deleteNode(nodeId);
+        this.runInTransaction(() => {
+            if (params.clearChunks) {
+                this.db.prepare(`DELETE FROM node_chunks WHERE node_id = ?`).run(nodeId);
+            }
+            this.db.prepare(`DELETE FROM node_embeddings WHERE owner_type = 'node' AND owner_id = ?`).run(nodeId);
+            this.upsertSemanticIndexState({
+                nodeId,
+                status: params.status,
+                staleReason: params.staleReason,
+                contentHash: params.contentHash,
+                embeddingProvider: params.embeddingProvider,
+                embeddingModel: params.embeddingModel,
+                embeddingVersion: params.embeddingVersion,
+                updatedAt: finishedAt
+            });
+        });
+    }
+    async processPendingSemanticIndex(limit = 25) {
+        const settings = this.readSemanticIndexSettings();
+        if (this.readPendingSemanticTransitionKeys().length) {
+            return {
+                processedNodeIds: [],
+                processedCount: 0,
+                readyCount: 0,
+                failedCount: 0,
+                remainingCount: this.listPendingSemanticIndexRows(limit).length,
+                mode: !settings.enabled || settings.provider === "disabled" || settings.model === "none" ? "chunk-only" : "provider-required"
+            };
+        }
+        this.markSemanticConfigurationMismatchesStale(limit);
+        const vectorIndexStore = this.resolveVectorIndexStore(settings.indexBackend);
+        const provider = resolveSemanticEmbeddingProvider({
+            provider: settings.provider,
+            model: settings.model
+        });
+        const pendingRows = this.listPendingSemanticIndexRows(limit);
+        const processedNodeIds = [];
+        const readyNodeIds = [];
+        const failedNodeIds = [];
+        for (const row of pendingRows) {
+            const startedAt = nowIso();
+            this.upsertSemanticIndexState({
+                nodeId: row.nodeId,
+                status: "processing",
+                staleReason: row.staleReason,
+                contentHash: row.contentHash,
+                embeddingProvider: settings.provider,
+                embeddingModel: settings.model,
+                updatedAt: startedAt
+            });
+            try {
+                const node = this.getNode(row.nodeId);
+                const contentHash = buildSemanticContentHash({
+                    title: node.title,
+                    body: node.body,
+                    summary: node.summary,
+                    tags: node.tags
+                });
+                const chunkText = buildSemanticDocumentText({
+                    title: node.title,
+                    summary: node.summary,
+                    body: node.body,
+                    tags: node.tags
+                });
+                const chunks = buildSemanticChunks(chunkText, settings.chunkEnabled);
+                const embeddingResults = provider && chunks.length
+                    ? await provider.embedBatch(chunks.map((chunk) => ({
+                        nodeId: node.id,
+                        chunkOrdinal: chunk.ordinal,
+                        contentHash,
+                        text: chunk.chunkText
+                    })))
+                    : [];
+                const finishedAt = nowIso();
+                if (node.status === "archived") {
+                    await this.syncSemanticDelete(vectorIndexStore, node.id, finishedAt, {
+                        clearChunks: true,
+                        contentHash,
+                        embeddingProvider: settings.provider,
+                        embeddingModel: settings.model,
+                        status: "ready",
+                        staleReason: null
+                    });
+                    readyNodeIds.push(node.id);
+                    processedNodeIds.push(row.nodeId);
+                    continue;
+                }
+                this.replaceSemanticChunks(node.id, chunks, finishedAt);
+                if (!settings.enabled || settings.provider === "disabled" || settings.model === "none" || !settings.provider || !settings.model) {
+                    await this.syncSemanticDelete(vectorIndexStore, node.id, finishedAt, {
+                        clearChunks: false,
+                        contentHash,
+                        embeddingProvider: settings.provider,
+                        embeddingModel: settings.model,
+                        status: "ready",
+                        staleReason: null
+                    });
+                    readyNodeIds.push(node.id);
+                    processedNodeIds.push(row.nodeId);
+                    continue;
+                }
+                if (provider && embeddingResults.length === chunks.length) {
+                    const ledgerRows = await vectorIndexStore.upsertNodeChunks({
+                        nodeId: node.id,
+                        chunks,
+                        embeddings: embeddingResults,
+                        contentHash,
+                        embeddingProvider: provider.provider,
+                        embeddingModel: provider.model ?? settings.model,
+                        embeddingVersion: provider.version,
+                        updatedAt: finishedAt
+                    });
+                    this.runInTransaction(() => {
+                        this.replaceSemanticEmbeddings(node.id, {
+                            provider: provider.provider,
+                            model: provider.model ?? settings.model,
+                            version: provider.version,
+                            contentHash,
+                            rows: ledgerRows,
+                            updatedAt: finishedAt
+                        });
+                        this.upsertSemanticIndexState({
+                            nodeId: node.id,
+                            status: "ready",
+                            staleReason: null,
+                            contentHash,
+                            embeddingProvider: provider.provider,
+                            embeddingModel: provider.model ?? settings.model,
+                            embeddingVersion: provider.version,
+                            updatedAt: finishedAt
+                        });
+                    });
+                    readyNodeIds.push(node.id);
+                    processedNodeIds.push(row.nodeId);
+                    continue;
+                }
+                await this.syncSemanticDelete(vectorIndexStore, node.id, finishedAt, {
+                    clearChunks: false,
+                    contentHash,
+                    embeddingProvider: settings.provider,
+                    embeddingModel: settings.model,
+                    status: "failed",
+                    staleReason: `embedding.provider_not_implemented:${settings.provider}`
+                });
+                failedNodeIds.push(node.id);
+            }
+            catch (error) {
+                const staleReason = error instanceof VectorIndexStoreError ? error.code : "embedding.node_not_found";
+                this.upsertSemanticIndexState({
+                    nodeId: row.nodeId,
+                    status: "failed",
+                    staleReason,
+                    contentHash: row.contentHash,
+                    embeddingProvider: settings.provider,
+                    embeddingModel: settings.model
+                });
+                failedNodeIds.push(row.nodeId);
+            }
+            processedNodeIds.push(row.nodeId);
+        }
+        return {
+            processedNodeIds,
+            processedCount: processedNodeIds.length,
+            readyCount: readyNodeIds.length,
+            failedCount: failedNodeIds.length,
+            remainingCount: this.listPendingSemanticIndexRows(limit).length,
+            mode: !settings.enabled || settings.provider === "disabled" || settings.model === "none" ? "chunk-only" : "provider-required"
+        };
+    }
+    ensureSearchTagIndex() {
+        const settings = this.getSettings(["search.tagIndex.version"]);
+        if (Number(settings["search.tagIndex.version"] ?? 0) >= SEARCH_TAG_INDEX_VERSION) {
+            return;
+        }
+        this.runInTransaction(() => {
+            this.db.prepare(`DELETE FROM node_tags`).run();
+            const rows = this.db
+                .prepare(`SELECT id, tags_json FROM nodes`)
+                .all();
+            const insertStatement = this.db.prepare(`INSERT INTO node_tags (node_id, tag) VALUES (?, ?)`);
+            for (const row of rows) {
+                const nodeId = String(row.id);
+                const tags = normalizeTagList(parseJson(row.tags_json, []));
+                for (const tag of tags) {
+                    insertStatement.run(nodeId, tag);
+                }
+            }
+            this.setSetting("search.tagIndex.version", SEARCH_TAG_INDEX_VERSION);
+        });
+    }
+    ensureActivitySearchIndex() {
+        const settings = this.getSettings(["search.activityFts.version"]);
+        if (Number(settings["search.activityFts.version"] ?? 0) >= SEARCH_ACTIVITY_FTS_VERSION) {
+            return;
+        }
+        this.runInTransaction(() => {
+            this.db.prepare(`INSERT INTO activities_fts(activities_fts) VALUES ('delete-all')`).run();
+            const rows = this.db
+                .prepare(`SELECT rowid, id, body FROM activities`)
+                .all();
+            const insertStatement = this.db.prepare(`INSERT INTO activities_fts(rowid, id, body) VALUES (?, ?, ?)`);
+            for (const row of rows) {
+                insertStatement.run(Number(row.rowid), String(row.id), row.body ? String(row.body) : "");
+            }
+            this.setSetting("search.activityFts.version", SEARCH_ACTIVITY_FTS_VERSION);
+        });
+    }
+    listSemanticIndexTargetNodeIds(limit) {
+        const rows = (limit === undefined
+            ? this.db
+                .prepare(`SELECT id
+               FROM nodes
+               WHERE status IN ('active', 'draft')
+               ORDER BY updated_at DESC`)
+                .all()
+            : this.db
+                .prepare(`SELECT id
+               FROM nodes
+               WHERE status IN ('active', 'draft')
+               ORDER BY updated_at DESC
+               LIMIT ?`)
+                .all(limit));
+        return rows.map((row) => String(row.id));
+    }
+    queueSemanticReindexForNodeIds(nodeIds, reason, updatedAt = nowIso()) {
+        const nodesById = this.getNodesByIds(nodeIds);
+        for (const nodeId of nodeIds) {
+            const node = nodesById.get(nodeId);
+            if (!node) {
+                continue;
+            }
+            const contentHash = buildSemanticContentHash({
+                title: node.title,
+                body: node.body,
+                summary: node.summary,
+                tags: node.tags
+            });
+            this.markNodeSemanticIndexState(node.id, reason, {
+                status: "pending",
+                contentHash,
+                updatedAt
+            });
+        }
+    }
+    queueSemanticReindexForNode(nodeId, reason = "manual.reindex") {
+        const node = this.getNode(nodeId);
+        const contentHash = buildSemanticContentHash({
+            title: node.title,
+            body: node.body,
+            summary: node.summary,
+            tags: node.tags
+        });
+        this.markNodeSemanticIndexState(node.id, reason, {
+            status: "pending",
+            contentHash
+        });
+        return node;
+    }
+    queueSemanticReindex(limit = 250, reason = "manual.reindex") {
+        const nodeIds = this.listSemanticIndexTargetNodeIds(limit);
+        const updatedAt = nowIso();
+        this.queueSemanticReindexForNodeIds(nodeIds, reason, updatedAt);
+        this.setSetting("search.semantic.last_backfill_at", updatedAt);
+        return {
+            queuedNodeIds: nodeIds,
+            queuedCount: nodeIds.length
+        };
+    }
+    getSemanticStatus() {
+        this.markSemanticConfigurationMismatchesStale();
+        const settings = this.getSettings([
+            "search.semantic.enabled",
+            "search.semantic.provider",
+            "search.semantic.model",
+            "search.semantic.indexBackend",
+            "search.semantic.chunk.enabled",
+            "search.semantic.last_backfill_at"
+        ]);
+        const semanticSettings = readSemanticIndexSettingSnapshot(settings, {
+            sqliteVecLoaded: this.sqliteVecRuntime.isLoaded,
+            sqliteVecLoadError: this.sqliteVecRuntime.loadError
+        });
+        const { version: _version, ...semanticStatusSettings } = semanticSettings;
+        const counts = Object.fromEntries(SEMANTIC_INDEX_STATUS_VALUES.map((status) => [status, 0]));
+        const rows = this.db
+            .prepare(`SELECT embedding_status, COUNT(*) AS total
+         FROM node_index_state
+         GROUP BY embedding_status`)
+            .all();
+        for (const row of rows) {
+            const status = String(row.embedding_status);
+            if (SEMANTIC_INDEX_STATUS_VALUES.includes(status)) {
+                counts[status] = Number(row.total ?? 0);
+            }
+        }
+        return {
+            ...semanticStatusSettings,
+            lastBackfillAt: readStringSetting(settings, "search.semantic.last_backfill_at"),
+            counts
+        };
+    }
+    listSemanticIssues(input = {}) {
+        this.markSemanticConfigurationMismatchesStale();
+        const limit = Math.min(Math.max(input.limit ?? 5, 1), 25);
+        const normalizedStatuses = (input.statuses?.length ? input.statuses : [...SEMANTIC_ISSUE_STATUS_VALUES]).filter((status, index, values) => SEMANTIC_ISSUE_STATUS_VALUES.includes(status) && values.indexOf(status) === index);
+        const statuses = normalizedStatuses.length ? normalizedStatuses : [...SEMANTIC_ISSUE_STATUS_VALUES];
+        const cursor = decodeSemanticIssueCursor(input.cursor);
+        const statusRankExpression = `CASE nis.embedding_status
+             WHEN 'failed' THEN 0
+             WHEN 'stale' THEN 1
+             ELSE 2
+           END`;
+        const whereClauses = [`nis.embedding_status IN (${statuses.map(() => "?").join(", ")})`];
+        const values = [...statuses];
+        if (cursor) {
+            whereClauses.push(`(
+          ${statusRankExpression} > ?
+          OR (${statusRankExpression} = ? AND nis.updated_at < ?)
+          OR (${statusRankExpression} = ? AND nis.updated_at = ? AND nis.node_id < ?)
+        )`);
+            values.push(cursor.statusRank, cursor.statusRank, cursor.updatedAt, cursor.statusRank, cursor.updatedAt, cursor.nodeId);
+        }
+        const rows = this.db
+            .prepare(`SELECT nis.node_id, n.title, nis.embedding_status, nis.stale_reason, nis.updated_at,
+                ${statusRankExpression} AS status_rank
+         FROM node_index_state nis
+         JOIN nodes n ON n.id = nis.node_id
+         WHERE ${whereClauses.join(" AND ")}
+         ORDER BY
+           status_rank ASC,
+           nis.updated_at DESC,
+           nis.node_id DESC
+         LIMIT ?`)
+            .all(...values, limit + 1);
+        const items = rows.slice(0, limit).map((row) => ({
+            nodeId: String(row.node_id),
+            title: row.title ? String(row.title) : null,
+            embeddingStatus: String(row.embedding_status),
+            staleReason: row.stale_reason ? String(row.stale_reason) : null,
+            updatedAt: String(row.updated_at)
+        }));
+        const hasMore = rows.length > limit;
+        const lastItem = items.at(-1);
+        return {
+            items,
+            nextCursor: hasMore && lastItem
+                ? encodeSemanticIssueCursor({
+                    statusRank: semanticIssueStatusRank(lastItem.embeddingStatus),
+                    updatedAt: lastItem.updatedAt,
+                    nodeId: lastItem.nodeId
+                })
+                : null
+        };
+    }
+    async rankSemanticCandidates(query, candidateNodeIds) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery || !candidateNodeIds.length) {
+            return new Map();
+        }
+        this.markSemanticConfigurationMismatchesStale();
+        const settings = this.readSemanticIndexSettings();
+        if (!settings.enabled || !settings.provider || !settings.model) {
+            return new Map();
+        }
+        const queryEmbedding = await embedSemanticQueryText({
+            provider: settings.provider,
+            model: settings.model,
+            text: normalizedQuery,
+        });
+        if (!queryEmbedding?.vector.length) {
+            return new Map();
+        }
+        const similarityByNode = new Map();
+        const matches = await this.resolveVectorIndexStore(settings.indexBackend).searchCandidates({
+            queryVector: queryEmbedding.vector,
+            candidateNodeIds,
+            embeddingProvider: settings.provider,
+            embeddingModel: settings.model,
+            embeddingVersion: settings.version
+        }).catch(() => []);
+        for (const match of matches) {
+            const accumulator = similarityByNode.get(match.nodeId) ?? {
+                matchedChunks: 0,
+                maxSimilarity: Number.NEGATIVE_INFINITY,
+                topSimilarities: []
+            };
+            updateSemanticSimilarityAccumulator(accumulator, match.similarity, settings.chunkAggregation);
+            similarityByNode.set(match.nodeId, accumulator);
+        }
+        const rankedMatches = new Map();
+        for (const [nodeId, accumulator] of similarityByNode.entries()) {
+            const similarities = settings.chunkAggregation === "topk_mean" ? accumulator.topSimilarities : [accumulator.maxSimilarity];
+            rankedMatches.set(nodeId, {
+                similarity: aggregateChunkSimilarities(similarities, settings.chunkAggregation),
+                matchedChunks: accumulator.matchedChunks
+            });
+        }
+        return rankedMatches;
+    }
+    listNodes(limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT id, type, title, summary, status, canonicality, source_label, updated_at, tags_json
+         FROM nodes
+         ORDER BY updated_at DESC
+         LIMIT ?`)
+            .all(limit);
+        return rows.map((row) => ({
+            id: String(row.id),
+            type: row.type,
+            title: row.title ? String(row.title) : null,
+            summary: row.summary ? String(row.summary) : null,
+            status: row.status,
+            canonicality: row.canonicality,
+            sourceLabel: row.source_label ? String(row.source_label) : null,
+            updatedAt: String(row.updated_at),
+            tags: parseJson(row.tags_json, [])
+        }));
+    }
+    listInferenceCandidateNodes(targetNodeId, limit = 200) {
+        const rows = this.db
+            .prepare(`SELECT * FROM nodes
+         WHERE id != ?
+           AND status = 'active'
+         ORDER BY updated_at DESC
+         LIMIT ?`)
+            .all(targetNodeId, limit);
+        return rows.map(mapNode);
+    }
+    listProjectMembershipIdsByNodeIds(nodeIds) {
+        if (!nodeIds.length) {
+            return new Map();
+        }
+        const uniqueIds = Array.from(new Set(nodeIds));
+        const memberships = new Map(uniqueIds.map((nodeId) => [nodeId, new Set()]));
+        const placeholders = uniqueIds.map(() => "?").join(", ");
+        const projectRows = this.db
+            .prepare(`SELECT id
+         FROM nodes
+         WHERE id IN (${placeholders})
+           AND type = 'project'`)
+            .all(...uniqueIds);
+        for (const row of projectRows) {
+            const nodeId = String(row.id);
+            memberships.get(nodeId)?.add(nodeId);
+        }
+        const relationRows = this.db
+            .prepare(`SELECT r.from_node_id AS node_id, r.to_node_id AS project_id
+         FROM relations r
+         JOIN nodes p ON p.id = r.to_node_id
+         WHERE r.status = 'active'
+           AND r.from_node_id IN (${placeholders})
+           AND p.type = 'project'
+           AND p.status = 'active'
+         UNION
+         SELECT r.to_node_id AS node_id, r.from_node_id AS project_id
+         FROM relations r
+         JOIN nodes p ON p.id = r.from_node_id
+         WHERE r.status = 'active'
+           AND r.to_node_id IN (${placeholders})
+           AND p.type = 'project'
+           AND p.status = 'active'`)
+            .all(...uniqueIds, ...uniqueIds);
+        for (const row of relationRows) {
+            const nodeId = String(row.node_id);
+            memberships.get(nodeId)?.add(String(row.project_id));
+        }
+        return new Map([...memberships.entries()].map(([nodeId, projectIds]) => [nodeId, Array.from(projectIds)]));
+    }
+    listArtifactKeysByNodeIds(nodeIds) {
+        if (!nodeIds.length) {
+            return new Map();
+        }
+        const uniqueIds = Array.from(new Set(nodeIds));
+        const artifactsByNode = new Map(uniqueIds.map((nodeId) => [nodeId, { exactPaths: new Set(), baseNames: new Set() }]));
+        const rows = this.db
+            .prepare(`SELECT node_id, path
+         FROM artifacts
+         WHERE node_id IN (${uniqueIds.map(() => "?").join(", ")})
+         ORDER BY created_at DESC`)
+            .all(...uniqueIds);
+        for (const row of rows) {
+            const nodeId = String(row.node_id);
+            const pathValue = normalizeSearchText(row.path ? String(row.path) : null);
+            if (!pathValue) {
+                continue;
+            }
+            const bucket = artifactsByNode.get(nodeId);
+            if (!bucket) {
+                continue;
+            }
+            bucket.exactPaths.add(pathValue);
+            bucket.baseNames.add(normalizeSearchText(path.basename(pathValue)));
+        }
+        return new Map([...artifactsByNode.entries()].map(([nodeId, values]) => [
+            nodeId,
+            {
+                exactPaths: Array.from(values.exactPaths),
+                baseNames: Array.from(values.baseNames)
+            }
+        ]));
+    }
+    listSharedProjectMemberNodeIds(targetNodeId, limit = 200) {
+        const projectIds = this.listProjectMembershipIdsByNodeIds([targetNodeId]).get(targetNodeId) ?? [];
+        if (!projectIds.length) {
+            return [];
+        }
+        const placeholders = projectIds.map(() => "?").join(", ");
+        const rows = this.db
+            .prepare(`SELECT node_id
+         FROM (
+           SELECT
+             CASE
+               WHEN r.from_node_id IN (${placeholders}) THEN r.to_node_id
+               ELSE r.from_node_id
+             END AS node_id,
+             MAX(r.created_at) AS last_related_at
+           FROM relations r
+           JOIN nodes n
+             ON n.id = CASE
+               WHEN r.from_node_id IN (${placeholders}) THEN r.to_node_id
+               ELSE r.from_node_id
+             END
+           WHERE r.status = 'active'
+             AND (
+               r.from_node_id IN (${placeholders})
+               OR r.to_node_id IN (${placeholders})
+             )
+             AND n.status = 'active'
+             AND n.id != ?
+           GROUP BY node_id
+         )
+         ORDER BY last_related_at DESC
+         LIMIT ?`)
+            .all(...projectIds, ...projectIds, ...projectIds, ...projectIds, targetNodeId, limit);
+        return rows.map((row) => String(row.node_id));
+    }
+    listNodesSharingArtifactPaths(targetNodeId, limit = 200) {
+        const artifactPaths = Array.from(new Set(this.listArtifacts(targetNodeId)
+            .map((artifact) => artifact.path)
+            .filter(Boolean)));
+        if (!artifactPaths.length) {
+            return [];
+        }
+        const rows = this.db
+            .prepare(`SELECT DISTINCT node_id
+         FROM artifacts
+         WHERE path IN (${artifactPaths.map(() => "?").join(", ")})
+           AND node_id != ?
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(...artifactPaths, targetNodeId, limit);
+        return rows.map((row) => String(row.node_id));
+    }
+    listInferenceTargetNodeIds(limit = 250) {
+        const rows = this.db
+            .prepare(`SELECT id
+         FROM nodes
+         WHERE status = 'active'
+         ORDER BY updated_at DESC
+         LIMIT ?`)
+            .all(limit);
+        return rows.map((row) => String(row.id));
+    }
+    searchNodes(input) {
+        if (input.query.trim()) {
+            try {
+                const result = this.searchNodesWithFts(input);
+                appendCurrentTelemetryDetails({
+                    ftsFallback: false,
+                    resultCount: result.items.length,
+                    totalCount: result.total
+                });
+                return result;
+            }
+            catch {
+                const fallbackResult = this.searchNodesWithLike(input);
+                appendCurrentTelemetryDetails({
+                    ftsFallback: true,
+                    resultCount: fallbackResult.items.length,
+                    totalCount: fallbackResult.total
+                });
+                return fallbackResult;
+            }
+        }
+        const result = this.searchNodesWithLike(input);
+        appendCurrentTelemetryDetails({
+            ftsFallback: false,
+            resultCount: result.items.length,
+            totalCount: result.total
+        });
+        return result;
+    }
+    searchActivities(input) {
+        if (input.query.trim()) {
+            try {
+                const result = this.searchActivitiesWithFts(input);
+                appendCurrentTelemetryDetails({
+                    ftsFallback: false,
+                    resultCount: result.items.length,
+                    totalCount: result.total
+                });
+                return result;
+            }
+            catch {
+                const fallbackResult = this.searchActivitiesWithLike(input);
+                appendCurrentTelemetryDetails({
+                    ftsFallback: true,
+                    resultCount: fallbackResult.items.length,
+                    totalCount: fallbackResult.total
+                });
+                return fallbackResult;
+            }
+        }
+        const result = this.searchActivitiesWithLike(input);
+        appendCurrentTelemetryDetails({
+            ftsFallback: false,
+            resultCount: result.items.length,
+            totalCount: result.total
+        });
+        return result;
+    }
+    listWorkspaceSemanticFallbackCandidateNodeIds(filters, settings, limit) {
+        if (!settings.provider || !settings.model) {
+            return [];
+        }
+        this.markSemanticConfigurationMismatchesStale();
+        const where = [
+            `n.status IN (${(filters?.status?.length ? filters.status : ["active", "draft"]).map(() => "?").join(", ")})`,
+            `nis.embedding_status = 'ready'`,
+            `nis.embedding_provider = ?`,
+            `nis.embedding_model = ?`,
+            `nis.embedding_version ${settings.version === null ? "IS NULL" : "= ?"}`
+        ];
+        const whereValues = [
+            ...(filters?.status?.length ? filters.status : ["active", "draft"]),
+            settings.provider,
+            settings.model,
+            ...(settings.version === null ? [] : [settings.version])
+        ];
+        if (filters?.types?.length) {
+            where.push(`n.type IN (${filters.types.map(() => "?").join(", ")})`);
+            whereValues.push(...filters.types);
+        }
+        if (filters?.sourceLabels?.length) {
+            where.push(`n.source_label IN (${filters.sourceLabels.map(() => "?").join(", ")})`);
+            whereValues.push(...filters.sourceLabels);
+        }
+        if (filters?.tags?.length) {
+            for (const tag of normalizeTagList(filters.tags)) {
+                where.push("EXISTS (SELECT 1 FROM node_tags nt WHERE nt.node_id = n.id AND nt.tag = ?)");
+                whereValues.push(tag);
+            }
+        }
+        const rows = this.db
+            .prepare(`SELECT n.id
+         FROM nodes n
+         JOIN node_index_state nis ON nis.node_id = n.id
+         WHERE ${where.join(" AND ")}
+         ORDER BY n.updated_at DESC
+         LIMIT ?`)
+            .all(...whereValues, limit);
+        return rows.map((row) => String(row.id));
+    }
+    buildWorkspaceSemanticFallbackNodeItems(candidateNodeIds, semanticMatches, settings) {
+        const rankedItems = [];
+        const candidateNodes = this.getNodesByIds(candidateNodeIds);
+        for (const nodeId of candidateNodeIds) {
+            const semanticMatch = semanticMatches.get(nodeId);
+            if (!semanticMatch) {
+                continue;
+            }
+            const retrievalRank = computeSemanticRetrievalRank(semanticMatch.similarity, settings);
+            if (retrievalRank <= 0) {
+                continue;
+            }
+            const node = candidateNodes.get(nodeId);
+            if (!node) {
+                continue;
+            }
+            rankedItems.push({
+                id: node.id,
+                type: node.type,
+                title: node.title,
+                summary: node.summary,
+                status: node.status,
+                canonicality: node.canonicality,
+                sourceLabel: node.sourceLabel,
+                updatedAt: node.updatedAt,
+                tags: node.tags,
+                matchReason: buildSearchMatchReason("semantic", ["semantic"]),
+                semanticSimilarity: Number(semanticMatch.similarity.toFixed(4)),
+                semanticRetrievalRank: retrievalRank
+            });
+        }
+        return rankedItems
+            .sort((left, right) => right.semanticRetrievalRank - left.semanticRetrievalRank || right.updatedAt.localeCompare(left.updatedAt))
+            .map(({ semanticSimilarity: _semanticSimilarity, semanticRetrievalRank: _semanticRetrievalRank, ...item }) => item);
+    }
+    async searchWorkspace(input, options = {}) {
+        const includeNodes = input.scopes.includes("nodes");
+        const includeActivities = input.scopes.includes("activities");
+        const requestedWindow = Math.min(input.limit + input.offset + SEARCH_FEEDBACK_WINDOW_PADDING, SEARCH_FEEDBACK_MAX_WINDOW);
+        const queryPresent = Boolean(input.query.trim());
+        const searchSort = input.sort === "smart" ? (queryPresent ? "relevance" : "updated_at") : input.sort;
+        const normalizedQuery = input.query.trim();
+        const nodeResults = includeNodes
+            ? this.searchNodes({
+                query: input.query,
+                filters: input.nodeFilters ?? {},
+                limit: requestedWindow,
+                offset: 0,
+                sort: searchSort
+            })
+            : { items: [], total: 0 };
+        const activityResults = includeActivities
+            ? this.searchActivities({
+                query: input.query,
+                filters: input.activityFilters ?? {},
+                limit: requestedWindow,
+                offset: 0,
+                sort: searchSort
+            })
+            : { items: [], total: 0 };
+        const fallbackTriggered = queryPresent && nodeResults.total + activityResults.total === 0;
+        const fallbackTokens = fallbackTriggered ? tokenizeSearchQuery(input.query, SEARCH_FALLBACK_TOKEN_LIMIT) : [];
+        const resolvedNodeResults = fallbackTokens.length >= 2 && includeNodes
+            ? this.searchWorkspaceNodeFallback(fallbackTokens, input.nodeFilters ?? {}, requestedWindow)
+            : nodeResults;
+        const resolvedActivityResults = fallbackTokens.length >= 2 && includeActivities
+            ? this.searchWorkspaceActivityFallback(fallbackTokens, input.activityFilters ?? {}, requestedWindow)
+            : activityResults;
+        const merged = this.mergeWorkspaceSearchResults(resolvedNodeResults.items, resolvedActivityResults.items, input.sort);
+        const deterministicResult = {
+            total: fallbackTokens.length >= 2
+                ? merged.length
+                : resolvedNodeResults.total + resolvedActivityResults.total,
+            items: merged.slice(input.offset, input.offset + input.limit)
+        };
+        const semanticSettings = this.readSemanticIndexSettings();
+        const telemetry = {
+            semanticFallbackEligible: false,
+            semanticFallbackAttempted: false,
+            semanticFallbackUsed: false,
+            semanticFallbackCandidateCount: 0,
+            semanticFallbackResultCount: 0,
+            semanticFallbackBackend: null,
+            semanticFallbackConfiguredBackend: semanticSettings.configuredIndexBackend,
+            semanticFallbackSkippedReason: null,
+            semanticFallbackQueryLengthBucket: queryPresent ? bucketSemanticQueryLength(normalizedQuery.length) : null
+        };
+        const appendWorkspaceSearchTelemetry = (result) => {
+            appendCurrentTelemetryDetails({
+                candidateCount: requestedWindow,
+                nodeCandidateCount: resolvedNodeResults.items.length,
+                activityCandidateCount: resolvedActivityResults.items.length,
+                resultCount: result.items.length,
+                totalCount: result.total,
+                fallbackTokenCount: fallbackTokens.length,
+                semanticFallbackEligible: telemetry.semanticFallbackEligible,
+                semanticFallbackAttempted: telemetry.semanticFallbackAttempted,
+                semanticFallbackUsed: telemetry.semanticFallbackUsed,
+                semanticFallbackCandidateCount: telemetry.semanticFallbackCandidateCount,
+                semanticFallbackResultCount: telemetry.semanticFallbackResultCount,
+                semanticFallbackBackend: telemetry.semanticFallbackBackend,
+                semanticFallbackConfiguredBackend: telemetry.semanticFallbackConfiguredBackend,
+                semanticFallbackSkippedReason: telemetry.semanticFallbackSkippedReason
+            });
+        };
+        const shouldAttemptSemanticFallback = includeNodes &&
+            semanticSettings.workspaceFallbackEnabled &&
+            queryPresent &&
+            normalizedQuery.length >= 6 &&
+            deterministicResult.total === 0 &&
+            semanticSettings.enabled &&
+            Boolean(semanticSettings.provider && semanticSettings.model);
+        if (!includeNodes) {
+            telemetry.semanticFallbackSkippedReason = "nodes_scope_disabled";
+        }
+        else if (!queryPresent) {
+            telemetry.semanticFallbackSkippedReason = "query_empty";
+        }
+        else if (normalizedQuery.length < 6) {
+            telemetry.semanticFallbackSkippedReason = "query_too_short";
+        }
+        else if (!semanticSettings.workspaceFallbackEnabled) {
+            telemetry.semanticFallbackSkippedReason = "workspace_fallback_disabled";
+        }
+        else if (deterministicResult.total > 0) {
+            telemetry.semanticFallbackSkippedReason = "deterministic_results_present";
+        }
+        else if (!semanticSettings.enabled) {
+            telemetry.semanticFallbackSkippedReason = "semantic_disabled";
+        }
+        else if (!semanticSettings.provider || !semanticSettings.model) {
+            telemetry.semanticFallbackSkippedReason = "semantic_provider_unconfigured";
+        }
+        if (shouldAttemptSemanticFallback) {
+            const candidateNodeIds = this.listWorkspaceSemanticFallbackCandidateNodeIds(input.nodeFilters ?? {}, semanticSettings, 200);
+            telemetry.semanticFallbackEligible = true;
+            telemetry.semanticFallbackCandidateCount = candidateNodeIds.length;
+            telemetry.semanticFallbackBackend = semanticSettings.indexBackend;
+            if (!candidateNodeIds.length) {
+                telemetry.semanticFallbackSkippedReason = "candidate_pool_empty";
+            }
+            else {
+                telemetry.semanticFallbackAttempted = true;
+                const runSemanticFallback = async () => {
+                    const semanticMatches = await this.rankSemanticCandidates(normalizedQuery, candidateNodeIds);
+                    const items = this.buildWorkspaceSemanticFallbackNodeItems(candidateNodeIds, semanticMatches, this.getSemanticAugmentationSettings()).map((node) => ({ resultType: "node", node }));
+                    return {
+                        items,
+                        resultCount: items.length
+                    };
+                };
+                try {
+                    const semanticResult = options.runSemanticFallbackSpan
+                        ? await options.runSemanticFallbackSpan({
+                            semanticFallbackCandidateCount: candidateNodeIds.length,
+                            semanticFallbackBackend: semanticSettings.indexBackend,
+                            semanticFallbackConfiguredBackend: semanticSettings.configuredIndexBackend,
+                            semanticFallbackQueryLengthBucket: telemetry.semanticFallbackQueryLengthBucket
+                        }, runSemanticFallback)
+                        : await runSemanticFallback();
+                    telemetry.semanticFallbackResultCount = semanticResult.resultCount;
+                    if (semanticResult.resultCount > 0) {
+                        telemetry.semanticFallbackUsed = true;
+                        const semanticWorkspaceResult = {
+                            total: semanticResult.resultCount,
+                            items: semanticResult.items
+                        };
+                        appendWorkspaceSearchTelemetry(semanticWorkspaceResult);
+                        return {
+                            ...semanticWorkspaceResult,
+                            telemetry
+                        };
+                    }
+                    telemetry.semanticFallbackSkippedReason = "semantic_no_matches";
+                }
+                catch (error) {
+                    telemetry.semanticFallbackSkippedReason =
+                        error instanceof VectorIndexStoreError ? error.code : "semantic_fallback_error";
+                }
+            }
+        }
+        appendWorkspaceSearchTelemetry(deterministicResult);
+        return {
+            ...deterministicResult,
+            telemetry
+        };
+    }
+    searchWorkspaceNodeFallback(tokens, filters, limit) {
+        if (!tokens.length) {
+            return { total: 0, items: [] };
+        }
+        const queryLikes = tokens.map((token) => `%${token}%`);
+        const tokenWhere = tokens
+            .map(() => `(lower(coalesce(n.title, '')) LIKE lower(?) OR lower(coalesce(n.body, '')) LIKE lower(?) OR lower(coalesce(n.summary, '')) LIKE lower(?))`)
+            .join(" OR ");
+        return this.runSearchQuery("nodes n", [`(${tokenWhere})`], queryLikes.flatMap((token) => [token, token, token]), "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, n.updated_at DESC", [], limit, 0, filters ?? {}, false, tokens.join(" "), "fallback_token");
+    }
+    searchWorkspaceActivityFallback(tokens, filters, limit) {
+        if (!tokens.length) {
+            return { total: 0, items: [] };
+        }
+        const queryLikes = tokens.map((token) => `%${token}%`);
+        const initialWhere = [
+            `(${tokens
+                .map(() => `(lower(coalesce(a.body, '')) LIKE lower(?) OR lower(coalesce(n.title, '')) LIKE lower(?) OR lower(coalesce(a.activity_type, '')) LIKE lower(?) OR lower(coalesce(a.source_label, '')) LIKE lower(?))`)
+                .join(" OR ")})`
+        ];
+        return this.runActivitySearchQuery({
+            from: "activities a JOIN nodes n ON n.id = a.target_node_id",
+            initialWhere,
+            initialWhereValues: queryLikes.flatMap((token) => [token, token, token, token]),
+            orderBy: "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, a.created_at DESC",
+            orderValues: [],
+            input: {
+                query: tokens.join(" "),
+                filters: filters ?? {},
+                limit,
+                offset: 0,
+                sort: "updated_at"
+            },
+            strategy: "fallback_token"
+        });
+    }
+    mergeWorkspaceSearchResults(nodeItems, activityItems, sort) {
+        const includeSmartScore = sort === "smart";
+        const nowMs = includeSmartScore ? Date.now() : 0;
+        const merged = [
+            ...nodeItems.map((node, index) => ({
+                resultType: "node",
+                node,
+                index,
+                total: nodeItems.length,
+                timestamp: node.updatedAt,
+                contested: node.status === "contested",
+                smartScore: includeSmartScore
+                    ? computeWorkspaceSmartScore({
+                        index,
+                        total: nodeItems.length,
+                        timestamp: node.updatedAt,
+                        resultType: "node",
+                        contested: node.status === "contested",
+                        nowMs
+                    })
+                    : 0
+            })),
+            ...activityItems.map((activity, index) => ({
+                resultType: "activity",
+                activity,
+                index,
+                total: activityItems.length,
+                timestamp: activity.createdAt,
+                contested: activity.targetNodeStatus === "contested",
+                smartScore: includeSmartScore
+                    ? computeWorkspaceSmartScore({
+                        index,
+                        total: activityItems.length,
+                        timestamp: activity.createdAt,
+                        resultType: "activity",
+                        contested: activity.targetNodeStatus === "contested",
+                        nowMs
+                    })
+                    : 0
+            }))
+        ];
+        if (sort === "updated_at") {
+            return merged
+                .sort((left, right) => right.timestamp.localeCompare(left.timestamp))
+                .map(({ index: _index, total: _total, timestamp: _timestamp, contested: _contested, smartScore: _smartScore, ...item }) => item);
+        }
+        if (sort === "smart") {
+            return merged
+                .sort((left, right) => right.smartScore - left.smartScore || right.timestamp.localeCompare(left.timestamp))
+                .map(({ index: _index, total: _total, timestamp: _timestamp, contested: _contested, smartScore: _smartScore, ...item }) => item);
+        }
+        return merged.map(({ index: _index, total: _total, timestamp: _timestamp, contested: _contested, smartScore: _smartScore, ...item }) => item);
+    }
+    searchNodesWithFts(input) {
+        const where = [];
+        const values = [];
+        const from = "nodes n JOIN nodes_fts fts ON fts.rowid = n.rowid";
+        let orderBy = "n.updated_at DESC";
+        where.push("nodes_fts MATCH ?");
+        values.push(input.query.trim());
+        if (input.sort === "relevance") {
+            orderBy = "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, bm25(nodes_fts, 3.0, 1.5, 2.0), n.updated_at DESC";
+        }
+        return this.runSearchQuery(from, where, values, orderBy, [], input.limit, input.offset, input.filters, input.sort === "relevance", input.query, "fts");
+    }
+    searchNodesWithLike(input) {
+        const where = [];
+        const values = [];
+        let orderBy = "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, n.updated_at DESC";
+        if (input.query.trim()) {
+            where.push(`(lower(coalesce(n.title, '')) LIKE lower(?) OR lower(coalesce(n.body, '')) LIKE lower(?) OR lower(coalesce(n.summary, '')) LIKE lower(?))`);
+            const queryLike = `%${input.query.trim()}%`;
+            values.push(queryLike, queryLike, queryLike);
+            if (input.sort === "relevance") {
+                orderBy = `
+          CASE
+            WHEN lower(coalesce(n.title, '')) LIKE lower(?) THEN 0
+            WHEN lower(coalesce(n.summary, '')) LIKE lower(?) THEN 1
+            ELSE 2
+          END,
+          CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END,
+          n.updated_at DESC
+        `;
+                values.push(queryLike, queryLike);
+            }
+        }
+        const orderValues = input.sort === "relevance" && input.query.trim() ? values.slice(-2) : [];
+        const whereValues = orderValues.length ? values.slice(0, -2) : values;
+        return this.runSearchQuery("nodes n", where, whereValues, orderBy, orderValues, input.limit, input.offset, input.filters, input.sort === "relevance", input.query, input.query.trim() ? "like" : "browse");
+    }
+    applySearchFeedbackBoost(items) {
+        if (items.length <= 1) {
+            return items;
+        }
+        const summaries = this.getSearchFeedbackSummaries("node", items.map((item) => item.id));
+        return [...items]
+            .map((item, index) => ({
+            item,
+            score: items.length - index +
+                clampSearchFeedbackDelta(summaries.get(item.id)?.totalDelta ?? 0) * 2 -
+                (item.status === "contested" ? 1 : 0)
+        }))
+            .sort((left, right) => right.score - left.score || right.item.updatedAt.localeCompare(left.item.updatedAt))
+            .map(({ item }) => item);
+    }
+    applyActivitySearchFeedbackBoost(items) {
+        if (items.length <= 1) {
+            return items;
+        }
+        const summaries = this.getSearchFeedbackSummaries("activity", items.map((item) => item.id));
+        return [...items]
+            .map((item, index) => ({
+            item,
+            score: items.length - index +
+                clampSearchFeedbackDelta(summaries.get(item.id)?.totalDelta ?? 0) * 2 -
+                (item.targetNodeStatus === "contested" ? 1 : 0)
+        }))
+            .sort((left, right) => right.score - left.score || right.item.createdAt.localeCompare(left.item.createdAt))
+            .map(({ item }) => item);
+    }
+    searchActivitiesWithFts(input) {
+        return this.runActivitySearchQuery({
+            from: "activities a JOIN activities_fts ON activities_fts.rowid = a.rowid JOIN nodes n ON n.id = a.target_node_id",
+            initialWhere: ["activities_fts MATCH ?"],
+            initialWhereValues: [input.query.trim()],
+            orderBy: input.sort === "relevance"
+                ? "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, bm25(activities_fts, 2.0, 1.0), a.created_at DESC"
+                : "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, a.created_at DESC",
+            orderValues: [],
+            input,
+            strategy: "fts"
+        });
+    }
+    searchActivitiesWithLike(input) {
+        const initialWhere = [];
+        const initialWhereValues = [];
+        let orderBy = "CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END, a.created_at DESC";
+        const orderValues = [];
+        if (input.query.trim()) {
+            const queryLike = `%${input.query.trim()}%`;
+            initialWhere.push(`(lower(coalesce(a.body, '')) LIKE lower(?) OR lower(coalesce(n.title, '')) LIKE lower(?) OR lower(coalesce(a.activity_type, '')) LIKE lower(?) OR lower(coalesce(a.source_label, '')) LIKE lower(?))`);
+            initialWhereValues.push(queryLike, queryLike, queryLike, queryLike);
+            if (input.sort === "relevance") {
+                orderBy = `
+          CASE
+            WHEN lower(coalesce(a.body, '')) LIKE lower(?) THEN 0
+            WHEN lower(coalesce(n.title, '')) LIKE lower(?) THEN 1
+            WHEN lower(coalesce(a.activity_type, '')) LIKE lower(?) THEN 2
+            ELSE 3
+          END,
+          CASE WHEN n.status = 'contested' THEN 1 ELSE 0 END,
+          a.created_at DESC
+        `;
+                orderValues.push(queryLike, queryLike, queryLike);
+            }
+        }
+        return this.runActivitySearchQuery({
+            from: "activities a JOIN nodes n ON n.id = a.target_node_id",
+            initialWhere,
+            initialWhereValues,
+            orderBy,
+            orderValues,
+            input,
+            strategy: input.query.trim() ? "like" : "browse"
+        });
+    }
+    capActivityResultsPerTarget(items) {
+        const counts = new Map();
+        const capped = [];
+        for (const item of items) {
+            const currentCount = counts.get(item.targetNodeId) ?? 0;
+            if (currentCount >= ACTIVITY_RESULT_CAP_PER_TARGET) {
+                continue;
+            }
+            counts.set(item.targetNodeId, currentCount + 1);
+            capped.push(item);
+        }
+        return capped;
+    }
+    runActivitySearchQuery(params) {
+        const where = [...params.initialWhere];
+        const whereValues = [...params.initialWhereValues];
+        const { input } = params;
+        if (input.filters.targetNodeIds?.length) {
+            where.push(`a.target_node_id IN (${input.filters.targetNodeIds.map(() => "?").join(", ")})`);
+            whereValues.push(...input.filters.targetNodeIds);
+        }
+        if (input.filters.activityTypes?.length) {
+            where.push(`a.activity_type IN (${input.filters.activityTypes.map(() => "?").join(", ")})`);
+            whereValues.push(...input.filters.activityTypes);
+        }
+        if (input.filters.sourceLabels?.length) {
+            where.push(`a.source_label IN (${input.filters.sourceLabels.map(() => "?").join(", ")})`);
+            whereValues.push(...input.filters.sourceLabels);
+        }
+        if (input.filters.createdAfter) {
+            where.push(`a.created_at >= ?`);
+            whereValues.push(input.filters.createdAfter);
+        }
+        if (input.filters.createdBefore) {
+            where.push(`a.created_at <= ?`);
+            whereValues.push(input.filters.createdBefore);
+        }
+        const whereClause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+        const countRow = this.db
+            .prepare(`SELECT COUNT(*) AS total
+         FROM ${params.from}
+         ${whereClause}`)
+            .get(...whereValues);
+        const useSearchFeedbackBoost = input.sort === "relevance";
+        const effectiveLimit = useSearchFeedbackBoost
+            ? Math.min(input.limit + input.offset + SEARCH_FEEDBACK_WINDOW_PADDING, SEARCH_FEEDBACK_MAX_WINDOW)
+            : input.limit;
+        const effectiveOffset = useSearchFeedbackBoost ? 0 : input.offset;
+        const rows = this.db
+            .prepare(`SELECT
+           a.id,
+           a.target_node_id,
+           a.activity_type,
+           a.body,
+           a.source_label,
+           a.created_at,
+           n.title AS target_title,
+           n.type AS target_type,
+           n.status AS target_status
+         FROM ${params.from}
+         ${whereClause}
+         ORDER BY ${params.orderBy}
+         LIMIT ? OFFSET ?`)
+            .all(...whereValues, ...params.orderValues, effectiveLimit, effectiveOffset);
+        const matcher = params.strategy === "browse" ? null : createSearchFieldMatcher(params.input.query);
+        const items = rows.map((row) => ({
+            id: String(row.id),
+            targetNodeId: String(row.target_node_id),
+            targetNodeTitle: row.target_title ? String(row.target_title) : null,
+            targetNodeType: row.target_type ? row.target_type : null,
+            targetNodeStatus: row.target_status ? row.target_status : null,
+            activityType: row.activity_type,
+            body: row.body ? String(row.body) : null,
+            sourceLabel: row.source_label ? String(row.source_label) : null,
+            createdAt: String(row.created_at),
+            matchReason: buildSearchMatchReason(params.strategy, collectMatchedFields(matcher, [
+                { field: "body", value: row.body ? String(row.body) : null },
+                { field: "targetNodeTitle", value: row.target_title ? String(row.target_title) : null },
+                { field: "activityType", value: row.activity_type ? String(row.activity_type) : null },
+                { field: "sourceLabel", value: row.source_label ? String(row.source_label) : null }
+            ]))
+        }));
+        const rankedItems = useSearchFeedbackBoost ? this.applyActivitySearchFeedbackBoost(items) : items;
+        const cappedItems = this.capActivityResultsPerTarget(rankedItems);
+        return {
+            total: Number(countRow.total ?? 0),
+            items: useSearchFeedbackBoost ? cappedItems.slice(input.offset, input.offset + input.limit) : cappedItems
+        };
+    }
+    runSearchQuery(from, initialWhere, initialWhereValues, orderBy, orderValues, limit, offset, filters, useSearchFeedbackBoost, query, strategy) {
+        const where = [...initialWhere];
+        const whereValues = [...initialWhereValues];
+        if (filters.types?.length) {
+            where.push(`n.type IN (${filters.types.map(() => "?").join(", ")})`);
+            whereValues.push(...filters.types);
+        }
+        if (filters.status?.length) {
+            where.push(`n.status IN (${filters.status.map(() => "?").join(", ")})`);
+            whereValues.push(...filters.status);
+        }
+        if (filters.sourceLabels?.length) {
+            where.push(`n.source_label IN (${filters.sourceLabels.map(() => "?").join(", ")})`);
+            whereValues.push(...filters.sourceLabels);
+        }
+        if (filters.tags?.length) {
+            for (const tag of normalizeTagList(filters.tags)) {
+                where.push("EXISTS (SELECT 1 FROM node_tags nt WHERE nt.node_id = n.id AND nt.tag = ?)");
+                whereValues.push(tag);
+            }
+        }
+        const whereClause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+        const countValues = whereValues;
+        const rowValues = [...whereValues, ...orderValues];
+        const countRow = this.db
+            .prepare(`SELECT COUNT(*) as total FROM ${from} ${whereClause}`)
+            .get(...countValues);
+        const effectiveLimit = useSearchFeedbackBoost ? Math.min(limit + offset + SEARCH_FEEDBACK_WINDOW_PADDING, SEARCH_FEEDBACK_MAX_WINDOW) : limit;
+        const effectiveOffset = useSearchFeedbackBoost ? 0 : offset;
+        const rows = this.db
+            .prepare(`SELECT n.id, n.type, n.title, n.body, n.summary, n.status, n.canonicality, n.source_label, n.updated_at, n.tags_json
+         FROM ${from}
+         ${whereClause}
+         ORDER BY ${orderBy}
+         LIMIT ? OFFSET ?`)
+            .all(...rowValues, effectiveLimit, effectiveOffset);
+        const matcher = strategy === "browse" ? null : createSearchFieldMatcher(query);
+        const items = rows.map((row) => {
+            const tags = parseJson(row.tags_json, []);
+            return {
+                id: String(row.id),
+                type: row.type,
+                title: row.title ? String(row.title) : null,
+                summary: row.summary ? String(row.summary) : null,
+                status: row.status,
+                canonicality: row.canonicality,
+                sourceLabel: row.source_label ? String(row.source_label) : null,
+                updatedAt: String(row.updated_at),
+                tags,
+                matchReason: buildSearchMatchReason(strategy, collectMatchedFields(matcher, [
+                    { field: "title", value: row.title ? String(row.title) : null },
+                    { field: "summary", value: row.summary ? String(row.summary) : null },
+                    { field: "body", value: row.body ? String(row.body) : null },
+                    { field: "tags", value: tags.join(" ") },
+                    { field: "sourceLabel", value: row.source_label ? String(row.source_label) : null }
+                ]))
+            };
+        });
+        const rankedItems = useSearchFeedbackBoost ? this.applySearchFeedbackBoost(items) : items;
+        return {
+            total: countRow.total,
+            items: useSearchFeedbackBoost ? rankedItems.slice(offset, offset + limit) : rankedItems
+        };
+    }
+    getNode(id) {
+        const row = this.db.prepare(`SELECT * FROM nodes WHERE id = ?`).get(id);
+        return mapNode(assertPresent(row, `Node ${id} not found`));
+    }
+    getNodesByIds(ids) {
+        if (!ids.length) {
+            return new Map();
+        }
+        const uniqueIds = Array.from(new Set(ids));
+        const rows = this.db
+            .prepare(`SELECT * FROM nodes WHERE id IN (${uniqueIds.map(() => "?").join(", ")})`)
+            .all(...uniqueIds);
+        return new Map(rows.map((row) => {
+            const node = mapNode(row);
+            return [node.id, node];
+        }));
+    }
+    ensureWorkspaceInboxNode() {
+        const settings = this.getSettings([WORKSPACE_CAPTURE_INBOX_KEY]);
+        const inboxNodeId = typeof settings[WORKSPACE_CAPTURE_INBOX_KEY] === "string" ? String(settings[WORKSPACE_CAPTURE_INBOX_KEY]) : null;
+        if (inboxNodeId) {
+            try {
+                const existing = this.getNode(inboxNodeId);
+                if (existing.type === "conversation" && existing.status !== "archived") {
+                    return existing;
+                }
+            }
+            catch {
+                // fall through and recreate the system inbox node
+            }
+        }
+        const inboxNode = this.createNode({
+            type: "conversation",
+            title: "Workspace Inbox",
+            body: "Default timeline for captured agent updates when no target node is specified.",
+            summary: "System-managed conversation node for untargeted capture activity.",
+            tags: ["inbox"],
+            source: workspaceInboxSource,
+            metadata: {
+                workspaceInbox: true,
+                systemManaged: true
+            },
+            resolvedCanonicality: "canonical",
+            resolvedStatus: "active"
+        });
+        this.setSetting(WORKSPACE_CAPTURE_INBOX_KEY, inboxNode.id);
+        return inboxNode;
+    }
+    createNode(input) {
+        const now = nowIso();
+        const id = createId("node");
+        const nextSummary = input.summary ?? stableSummary(input.title, input.body);
+        const nextMetadata = withSummaryMetadata(input.metadata, now, input.summary !== undefined ? "explicit" : "derived");
+        this.runInTransaction(() => {
+            this.db
+                .prepare(`INSERT INTO nodes (
+            id, type, status, canonicality, visibility, title, body, summary,
+            created_by, source_type, source_label, created_at, updated_at, tags_json, metadata_json
+          ) VALUES (?, ?, ?, ?, 'normal', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, input.type, input.resolvedStatus, input.resolvedCanonicality, input.title, input.body, nextSummary, input.source.actorLabel, input.source.actorType, input.source.actorLabel, now, now, JSON.stringify(input.tags), JSON.stringify(nextMetadata));
+            this.syncNodeTags(id, input.tags);
+            this.markNodeSemanticIndexState(id, "node.created", {
+                status: "pending",
+                contentHash: buildSemanticContentHash({
+                    title: input.title,
+                    body: input.body,
+                    summary: nextSummary,
+                    tags: input.tags
+                }),
+                updatedAt: now
+            });
+        });
+        return this.getNode(id);
+    }
+    updateNode(id, input) {
+        const existing = this.getNode(id);
+        const nextTitle = input.title ?? existing.title;
+        const nextBody = input.body ?? existing.body;
+        const existingDerivedSummary = stableSummary(existing.title, existing.body);
+        const shouldRefreshDerivedSummary = input.summary !== undefined
+            ? false
+            : input.title !== undefined || input.body !== undefined
+                ? !existing.summary || existing.summary === existingDerivedSummary
+                : false;
+        const nextSummary = input.summary !== undefined
+            ? input.summary
+            : shouldRefreshDerivedSummary
+                ? stableSummary(nextTitle, nextBody)
+                : existing.summary;
+        const nextTags = input.tags ?? existing.tags;
+        const mergedMetadata = input.metadata ? { ...existing.metadata, ...input.metadata } : existing.metadata;
+        const updatedAt = nowIso();
+        const nextMetadata = input.summary !== undefined
+            ? withSummaryMetadata(mergedMetadata, updatedAt, "explicit")
+            : shouldRefreshDerivedSummary
+                ? withSummaryMetadata(mergedMetadata, updatedAt, "derived")
+                : mergedMetadata;
+        const nextStatus = input.status ?? existing.status;
+        this.runInTransaction(() => {
+            this.db
+                .prepare(`UPDATE nodes
+           SET title = ?, body = ?, summary = ?, tags_json = ?, metadata_json = ?, status = ?, updated_at = ?
+           WHERE id = ?`)
+                .run(nextTitle, nextBody, nextSummary, JSON.stringify(nextTags), JSON.stringify(nextMetadata), nextStatus, updatedAt, id);
+            this.syncNodeTags(id, nextTags);
+            this.markNodeSemanticIndexState(id, "node.updated", {
+                status: "pending",
+                contentHash: buildSemanticContentHash({
+                    title: nextTitle,
+                    body: nextBody,
+                    summary: nextSummary,
+                    tags: nextTags
+                }),
+                updatedAt
+            });
+        });
+        return this.getNode(id);
+    }
+    refreshNodeSummary(id) {
+        const existing = this.getNode(id);
+        const updatedAt = nowIso();
+        const nextSummary = stableSummary(existing.title, existing.body);
+        const nextMetadata = withSummaryMetadata(existing.metadata, updatedAt, "manual_refresh");
+        this.db
+            .prepare(`UPDATE nodes
+         SET summary = ?, metadata_json = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(nextSummary, JSON.stringify(nextMetadata), updatedAt, id);
+        this.markNodeSemanticIndexState(id, "summary.refreshed", {
+            status: "pending",
+            contentHash: buildSemanticContentHash({
+                title: existing.title,
+                body: existing.body,
+                summary: nextSummary,
+                tags: existing.tags
+            }),
+            updatedAt
+        });
+        return this.getNode(id);
+    }
+    archiveNode(id) {
+        const updatedAt = nowIso();
+        this.db.prepare(`UPDATE nodes SET status = 'archived', updated_at = ? WHERE id = ?`).run(updatedAt, id);
+        this.markNodeSemanticIndexState(id, "node.archived", {
+            status: "stale",
+            updatedAt
+        });
+        return this.getNode(id);
+    }
+    setNodeCanonicality(id, canonicality) {
+        this.db.prepare(`UPDATE nodes SET canonicality = ?, updated_at = ? WHERE id = ?`).run(canonicality, nowIso(), id);
+        return this.getNode(id);
+    }
+    listRelatedNodes(nodeId, depth = 1, relationFilter) {
+        if (depth !== 1) {
+            throw new AppError(400, "INVALID_INPUT", "Only depth=1 is supported in the hot path");
+        }
+        const relationWhere = relationFilter?.length
+            ? `AND r.relation_type IN (${relationFilter.map(() => "?").join(", ")})`
+            : "";
+        const rows = this.db
+            .prepare(`SELECT
+           r.*,
+           CASE WHEN r.from_node_id = ? THEN r.to_node_id ELSE r.from_node_id END AS related_id
+         FROM relations r
+         WHERE (r.from_node_id = ? OR r.to_node_id = ?)
+           AND r.status != 'archived'
+           ${relationWhere}
+         ORDER BY r.created_at DESC`)
+            .all(nodeId, nodeId, nodeId, ...(relationFilter ?? []));
+        const relatedNodes = this.getNodesByIds(rows.map((row) => String(row.related_id)));
+        return rows.flatMap((row) => {
+            const node = relatedNodes.get(String(row.related_id));
+            if (!node) {
+                return [];
+            }
+            return [{
+                    relation: mapRelation(row),
+                    node
+                }];
+        });
+    }
+    listProjectMemberNodes(projectId, limit) {
+        const rows = this.db
+            .prepare(`SELECT
+           r.*,
+           CASE WHEN r.from_node_id = ? THEN r.to_node_id ELSE r.from_node_id END AS related_id
+         FROM relations r
+         JOIN nodes n
+           ON n.id = CASE WHEN r.from_node_id = ? THEN r.to_node_id ELSE r.from_node_id END
+         WHERE (r.from_node_id = ? OR r.to_node_id = ?)
+           AND r.relation_type = 'relevant_to'
+           AND r.status NOT IN ('archived', 'rejected')
+           AND n.status != 'archived'
+         ORDER BY r.created_at DESC
+         LIMIT ?`)
+            .all(projectId, projectId, projectId, projectId, limit);
+        const relatedNodes = this.getNodesByIds(rows.map((row) => String(row.related_id)));
+        return rows.flatMap((row) => {
+            const node = relatedNodes.get(String(row.related_id));
+            if (!node) {
+                return [];
+            }
+            return [{
+                    relation: mapRelation(row),
+                    node
+                }];
+        });
+    }
+    listRelationsBetweenNodeIds(nodeIds) {
+        if (!nodeIds.length) {
+            return [];
+        }
+        const uniqueIds = Array.from(new Set(nodeIds));
+        const placeholders = uniqueIds.map(() => "?").join(", ");
+        const rows = this.db
+            .prepare(`SELECT *
+         FROM relations
+         WHERE from_node_id IN (${placeholders})
+           AND to_node_id IN (${placeholders})
+           AND status NOT IN ('archived', 'rejected')
+         ORDER BY created_at ASC, id ASC`)
+            .all(...uniqueIds, ...uniqueIds);
+        return rows.map(mapRelation);
+    }
+    createRelation(input) {
+        const now = nowIso();
+        const id = createId("rel");
+        this.db
+            .prepare(`INSERT INTO relations (
+          id, from_node_id, to_node_id, relation_type, status, created_by, source_type,
+          source_label, created_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.fromNodeId, input.toNodeId, input.relationType, input.resolvedStatus, input.source.actorLabel, input.source.actorType, input.source.actorLabel, now, JSON.stringify(input.metadata));
+        return this.getRelation(id);
+    }
+    upsertInferredRelation(input) {
+        const existing = this.db
+            .prepare(`SELECT id FROM inferred_relations
+         WHERE from_node_id = ? AND to_node_id = ? AND relation_type = ? AND generator = ?`)
+            .get(input.fromNodeId, input.toNodeId, input.relationType, input.generator);
+        const id = existing?.id ?? createId("irel");
+        const now = nowIso();
+        this.db
+            .prepare(`INSERT INTO inferred_relations (
+          id, from_node_id, to_node_id, relation_type, base_score, usage_score, final_score, status,
+          generator, evidence_json, last_computed_at, expires_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(from_node_id, to_node_id, relation_type, generator) DO UPDATE SET
+          base_score = excluded.base_score,
+          usage_score = excluded.usage_score,
+          final_score = excluded.final_score,
+          status = excluded.status,
+          evidence_json = excluded.evidence_json,
+          last_computed_at = excluded.last_computed_at,
+          expires_at = excluded.expires_at,
+          metadata_json = excluded.metadata_json`)
+            .run(id, input.fromNodeId, input.toNodeId, input.relationType, input.baseScore, input.usageScore, input.finalScore, input.status, input.generator, JSON.stringify(input.evidence), now, input.expiresAt ?? null, JSON.stringify(input.metadata));
+        return this.getInferredRelationByIdentity(input.fromNodeId, input.toNodeId, input.relationType, input.generator);
+    }
+    getRelation(id) {
+        const row = this.db.prepare(`SELECT * FROM relations WHERE id = ?`).get(id);
+        return mapRelation(assertPresent(row, `Relation ${id} not found`));
+    }
+    getInferredRelation(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM inferred_relations WHERE id = ?`)
+            .get(id);
+        return mapInferredRelation(assertPresent(row, `Inferred relation ${id} not found`));
+    }
+    getInferredRelationByIdentity(fromNodeId, toNodeId, relationType, generator) {
+        const row = this.db
+            .prepare(`SELECT * FROM inferred_relations
+         WHERE from_node_id = ? AND to_node_id = ? AND relation_type = ? AND generator = ?`)
+            .get(fromNodeId, toNodeId, relationType, generator);
+        return mapInferredRelation(assertPresent(row, `Inferred relation ${fromNodeId}:${toNodeId}:${relationType}:${generator} not found`));
+    }
+    listInferredRelationsForNode(nodeId, limit = 20, status = "active") {
+        const rows = this.db
+            .prepare(`SELECT * FROM inferred_relations
+         WHERE status = ?
+           AND (from_node_id = ? OR to_node_id = ?)
+           AND (expires_at IS NULL OR expires_at > ?)
+         ORDER BY final_score DESC, last_computed_at DESC
+         LIMIT ?`)
+            .all(status, nodeId, nodeId, nowIso(), limit);
+        return rows.map(mapInferredRelation);
+    }
+    listInferredRelationsBetweenNodeIds(nodeIds, limit = 100, status = "active") {
+        if (!nodeIds.length) {
+            return [];
+        }
+        const uniqueIds = Array.from(new Set(nodeIds));
+        const placeholders = uniqueIds.map(() => "?").join(", ");
+        const rows = this.db
+            .prepare(`SELECT *
+         FROM inferred_relations
+         WHERE status = ?
+           AND from_node_id IN (${placeholders})
+           AND to_node_id IN (${placeholders})
+           AND (expires_at IS NULL OR expires_at > ?)
+         ORDER BY final_score DESC, last_computed_at DESC, id ASC
+         LIMIT ?`)
+            .all(status, ...uniqueIds, ...uniqueIds, nowIso(), limit);
+        return rows.map(mapInferredRelation);
+    }
+    expireAutoInferredRelationsForNode(nodeId, generators, keepRelationIds = []) {
+        if (!generators.length) {
+            return 0;
+        }
+        const where = [
+            `(from_node_id = ? OR to_node_id = ?)`,
+            `generator IN (${generators.map(() => "?").join(", ")})`,
+            `status != 'expired'`
+        ];
+        const values = [nodeId, nodeId, ...generators];
+        if (keepRelationIds.length) {
+            where.push(`id NOT IN (${keepRelationIds.map(() => "?").join(", ")})`);
+            values.push(...keepRelationIds);
+        }
+        const result = this.db
+            .prepare(`UPDATE inferred_relations
+         SET status = 'expired', last_computed_at = ?
+         WHERE ${where.join(" AND ")}`)
+            .run(nowIso(), ...values);
+        return Number(result.changes ?? 0);
+    }
+    appendRelationUsageEvent(input) {
+        const id = createId("rue");
+        const now = nowIso();
+        this.runInTransaction(() => {
+            const result = this.db
+                .prepare(`INSERT INTO relation_usage_events (
+            id, relation_id, relation_source, event_type, session_id, run_id, actor_type, actor_label,
+            tool_name, delta, created_at, metadata_json
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, input.relationId, input.relationSource, input.eventType, input.sessionId ?? null, input.runId ?? null, input.source?.actorType ?? null, input.source?.actorLabel ?? null, input.source?.toolName ?? null, input.delta, now, JSON.stringify(input.metadata));
+            const rowid = Number(result.lastInsertRowid ?? 0);
+            this.db
+                .prepare(`INSERT INTO relation_usage_rollups (
+             relation_id, total_delta, event_count, last_event_at, last_event_rowid, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(relation_id) DO UPDATE SET
+             total_delta = total_delta + excluded.total_delta,
+             event_count = event_count + excluded.event_count,
+             last_event_at = CASE
+               WHEN excluded.last_event_at > last_event_at THEN excluded.last_event_at
+               ELSE last_event_at
+             END,
+             last_event_rowid = CASE
+               WHEN excluded.last_event_rowid > last_event_rowid THEN excluded.last_event_rowid
+               ELSE last_event_rowid
+             END,
+             updated_at = excluded.updated_at`)
+                .run(input.relationId, input.delta, 1, now, rowid, now);
+            this.ensureRelationUsageRollupState(now);
+            this.db
+                .prepare(`UPDATE relation_usage_rollup_state
+           SET last_event_rowid = CASE
+             WHEN ? > last_event_rowid THEN ?
+             ELSE last_event_rowid
+           END,
+               updated_at = ?
+           WHERE id = ?`)
+                .run(rowid, rowid, now, RELATION_USAGE_ROLLUP_STATE_ID);
+        });
+        return this.getRelationUsageEvent(id);
+    }
+    getRelationUsageEvent(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM relation_usage_events WHERE id = ?`)
+            .get(id);
+        return mapRelationUsageEvent(assertPresent(row, `Relation usage event ${id} not found`));
+    }
+    listRelationUsageEvents(relationId, limit = 50) {
+        const rows = this.db
+            .prepare(`SELECT * FROM relation_usage_events
+         WHERE relation_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(relationId, limit);
+        return rows.map(mapRelationUsageEvent);
+    }
+    getRelationUsageSummaries(relationIds) {
+        if (!relationIds.length) {
+            return new Map();
+        }
+        const uniqueIds = Array.from(new Set(relationIds));
+        const readRows = () => this.db
+            .prepare(`SELECT
+             relation_id,
+             total_delta,
+             event_count,
+             last_event_at
+           FROM relation_usage_rollups
+           WHERE relation_id IN (${uniqueIds.map(() => "?").join(", ")})
+           ORDER BY relation_id`)
+            .all(...uniqueIds);
+        let rows = readRows();
+        if (rows.length < uniqueIds.length) {
+            this.syncRelationUsageRollups();
+            rows = readRows();
+        }
+        return new Map(rows.map((row) => [
+            String(row.relation_id),
+            {
+                relationId: String(row.relation_id),
+                totalDelta: Number(row.total_delta),
+                eventCount: Number(row.event_count),
+                lastEventAt: row.last_event_at ? String(row.last_event_at) : null
+            }
+        ]));
+    }
+    appendSearchFeedbackEvent(input) {
+        const id = createId("sfe");
+        const now = nowIso();
+        const delta = computeSearchFeedbackDelta(input.verdict, input.confidence);
+        this.runInTransaction(() => {
+            this.db
+                .prepare(`INSERT INTO search_feedback_events (
+            id, result_type, result_id, verdict, query, session_id, run_id, actor_type, actor_label,
+            tool_name, confidence, delta, created_at, metadata_json
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, input.resultType, input.resultId, input.verdict, input.query ?? null, input.sessionId ?? null, input.runId ?? null, input.source?.actorType ?? null, input.source?.actorLabel ?? null, input.source?.toolName ?? null, input.confidence, delta, now, JSON.stringify(input.metadata));
+            this.db
+                .prepare(`INSERT INTO search_feedback_rollups (
+             result_type, result_id, total_delta, event_count, useful_count, not_useful_count, uncertain_count, last_event_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(result_type, result_id) DO UPDATE SET
+             total_delta = total_delta + excluded.total_delta,
+             event_count = event_count + excluded.event_count,
+             useful_count = useful_count + excluded.useful_count,
+             not_useful_count = not_useful_count + excluded.not_useful_count,
+             uncertain_count = uncertain_count + excluded.uncertain_count,
+             last_event_at = CASE
+               WHEN excluded.last_event_at > last_event_at THEN excluded.last_event_at
+               ELSE last_event_at
+             END,
+             updated_at = excluded.updated_at`)
+                .run(input.resultType, input.resultId, delta, 1, input.verdict === "useful" ? 1 : 0, input.verdict === "not_useful" ? 1 : 0, input.verdict === "uncertain" ? 1 : 0, now, now);
+        });
+        return this.getSearchFeedbackEvent(id);
+    }
+    getSearchFeedbackEvent(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM search_feedback_events WHERE id = ?`)
+            .get(id);
+        return mapSearchFeedbackEvent(assertPresent(row, `Search feedback event ${id} not found`));
+    }
+    listSearchFeedbackEvents(resultType, resultId, limit = 50) {
+        const rows = this.db
+            .prepare(`SELECT * FROM search_feedback_events
+         WHERE result_type = ? AND result_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(resultType, resultId, limit);
+        return rows.map(mapSearchFeedbackEvent);
+    }
+    getSearchFeedbackSummaries(resultType, resultIds) {
+        if (!resultIds.length) {
+            return new Map();
+        }
+        const rows = this.db
+            .prepare(`SELECT
+           result_id,
+           total_delta,
+           event_count,
+           useful_count,
+           not_useful_count,
+           uncertain_count,
+           last_event_at
+         FROM search_feedback_rollups
+         WHERE result_type = ?
+           AND result_id IN (${resultIds.map(() => "?").join(", ")})
+         ORDER BY result_id`)
+            .all(resultType, ...resultIds);
+        return new Map(rows.map((row) => [
+            String(row.result_id),
+            {
+                resultType,
+                resultId: String(row.result_id),
+                totalDelta: Number(row.total_delta),
+                eventCount: Number(row.event_count),
+                usefulCount: Number(row.useful_count),
+                notUsefulCount: Number(row.not_useful_count),
+                uncertainCount: Number(row.uncertain_count),
+                lastEventAt: row.last_event_at ? String(row.last_event_at) : null
+            }
+        ]));
+    }
+    appendGovernanceEvent(params) {
+        const id = createId("gov");
+        const now = nowIso();
+        const confidence = clampConfidence(params.confidence);
+        const metadata = params.metadata ?? {};
+        this.db
+            .prepare(`INSERT INTO governance_events (
+          id, entity_type, entity_id, event_type, previous_state, next_state, confidence, reason, created_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, params.entityType, params.entityId, params.eventType, params.previousState ?? null, params.nextState, confidence, params.reason, now, JSON.stringify(metadata));
+        return {
+            id,
+            entityType: params.entityType,
+            entityId: params.entityId,
+            eventType: params.eventType,
+            previousState: params.previousState,
+            nextState: params.nextState,
+            confidence,
+            reason: params.reason,
+            createdAt: now,
+            metadata
+        };
+    }
+    getGovernanceEvent(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM governance_events WHERE id = ?`)
+            .get(id);
+        return mapGovernanceEvent(assertPresent(row, `Governance event ${id} not found`));
+    }
+    listGovernanceEvents(entityType, entityId, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT * FROM governance_events
+         WHERE entity_type = ? AND entity_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(entityType, entityId, limit);
+        return rows.map(mapGovernanceEvent);
+    }
+    upsertGovernanceState(params) {
+        const now = params.lastEvaluatedAt ?? nowIso();
+        const existing = params.previousState === undefined
+            ? this.getGovernanceStateNullable(params.entityType, params.entityId)
+            : params.previousState;
+        const lastTransitionAt = existing?.state === params.state ? existing.lastTransitionAt : now;
+        this.db
+            .prepare(`INSERT INTO governance_state (
+          entity_type, entity_id, state, confidence, reasons_json, last_evaluated_at, last_transition_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(entity_type, entity_id) DO UPDATE SET
+          state = excluded.state,
+          confidence = excluded.confidence,
+          reasons_json = excluded.reasons_json,
+          last_evaluated_at = excluded.last_evaluated_at,
+          last_transition_at = excluded.last_transition_at,
+          metadata_json = excluded.metadata_json`)
+            .run(params.entityType, params.entityId, params.state, clampConfidence(params.confidence), JSON.stringify(params.reasons), now, lastTransitionAt, JSON.stringify(params.metadata ?? {}));
+        return {
+            entityType: params.entityType,
+            entityId: params.entityId,
+            state: params.state,
+            confidence: clampConfidence(params.confidence),
+            reasons: [...params.reasons],
+            lastEvaluatedAt: now,
+            lastTransitionAt,
+            metadata: params.metadata ?? {}
+        };
+    }
+    getGovernanceState(entityType, entityId) {
+        const row = this.db
+            .prepare(`SELECT * FROM governance_state WHERE entity_type = ? AND entity_id = ?`)
+            .get(entityType, entityId);
+        return mapGovernanceState(assertPresent(row, `Governance state ${entityType}:${entityId} not found`));
+    }
+    getGovernanceStateNullable(entityType, entityId) {
+        const row = this.db
+            .prepare(`SELECT * FROM governance_state WHERE entity_type = ? AND entity_id = ?`)
+            .get(entityType, entityId);
+        return row ? mapGovernanceState(row) : null;
+    }
+    listGovernanceIssues(limit = 20, states) {
+        const effectiveStates = states?.length ? states : ["low_confidence", "contested"];
+        const nodeRows = this.db
+            .prepare(`SELECT
+           gs.*,
+           n.title AS display_title,
+           n.type AS display_subtitle
+         FROM governance_state gs
+         JOIN nodes n
+           ON gs.entity_type = 'node'
+          AND gs.entity_id = n.id
+         WHERE gs.state IN (${effectiveStates.map(() => "?").join(", ")})
+           AND n.status != 'archived'
+         ORDER BY CASE WHEN gs.state = 'contested' THEN 0 ELSE 1 END, gs.confidence ASC, gs.last_transition_at DESC
+         LIMIT ?`)
+            .all(...effectiveStates, limit);
+        const relationRows = this.db
+            .prepare(`SELECT
+           gs.*,
+           COALESCE(fn.title, r.from_node_id) || ' ' || r.relation_type || ' ' || COALESCE(tn.title, r.to_node_id) AS display_title,
+           r.status AS display_subtitle
+         FROM governance_state gs
+         JOIN relations r
+           ON gs.entity_type = 'relation'
+          AND gs.entity_id = r.id
+         LEFT JOIN nodes fn ON fn.id = r.from_node_id
+         LEFT JOIN nodes tn ON tn.id = r.to_node_id
+         WHERE gs.state IN (${effectiveStates.map(() => "?").join(", ")})
+           AND r.status != 'archived'
+         ORDER BY CASE WHEN gs.state = 'contested' THEN 0 ELSE 1 END, gs.confidence ASC, gs.last_transition_at DESC
+         LIMIT ?`)
+            .all(...effectiveStates, limit);
+        return [...nodeRows, ...relationRows]
+            .map((row) => ({
+            ...mapGovernanceState(row),
+            title: row.display_title ? String(row.display_title) : null,
+            subtitle: row.display_subtitle ? String(row.display_subtitle) : null
+        }))
+            .sort((left, right) => {
+            const leftPriority = left.state === "contested" ? 0 : left.state === "low_confidence" ? 1 : 2;
+            const rightPriority = right.state === "contested" ? 0 : right.state === "low_confidence" ? 1 : 2;
+            return leftPriority - rightPriority || left.confidence - right.confidence || right.lastTransitionAt.localeCompare(left.lastTransitionAt);
+        })
+            .slice(0, limit);
+    }
+    listNodeIdsForGovernance(limit = 100, entityIds) {
+        const rows = entityIds?.length
+            ? this.db
+                .prepare(`SELECT id
+             FROM nodes
+             WHERE id IN (${entityIds.map(() => "?").join(", ")})
+             ORDER BY updated_at DESC
+             LIMIT ?`)
+                .all(...entityIds, limit)
+            : this.db
+                .prepare(`SELECT id
+             FROM nodes
+             WHERE status != 'archived'
+             ORDER BY updated_at DESC
+             LIMIT ?`)
+                .all(limit);
+        return rows.map((row) => String(row.id));
+    }
+    listRelationIdsForGovernance(limit = 100, entityIds) {
+        const rows = entityIds?.length
+            ? this.db
+                .prepare(`SELECT id
+             FROM relations
+             WHERE id IN (${entityIds.map(() => "?").join(", ")})
+             ORDER BY created_at DESC
+             LIMIT ?`)
+                .all(...entityIds, limit)
+            : this.db
+                .prepare(`SELECT id
+             FROM relations
+             WHERE status != 'archived'
+             ORDER BY created_at DESC
+             LIMIT ?`)
+                .all(limit);
+        return rows.map((row) => String(row.id));
+    }
+    countContradictionRelations(nodeId) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS total
+         FROM relations
+         WHERE relation_type = 'contradicts'
+           AND status = 'active'
+           AND (from_node_id = ? OR to_node_id = ?)`)
+            .get(nodeId, nodeId);
+        return Number(row.total ?? 0);
+    }
+    listLegacyReviewItems(limit = 500) {
+        if (!this.hasLegacyReviewQueueTable()) {
+            return [];
+        }
+        const rows = this.db
+            .prepare(`SELECT * FROM review_queue ORDER BY created_at DESC LIMIT ?`)
+            .all(limit);
+        return rows.map(mapLegacyReviewQueue);
+    }
+    clearLegacyReviewQueue() {
+        if (!this.hasLegacyReviewQueueTable()) {
+            return;
+        }
+        this.db.prepare(`DELETE FROM review_queue`).run();
+    }
+    hasLegacyReviewQueueTable() {
+        const row = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'review_queue'`)
+            .get();
+        return Boolean(row?.name);
+    }
+    ensureLegacyReviewQueueTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS review_queue (
+        id TEXT PRIMARY KEY,
+        entity_type TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        review_type TEXT NOT NULL,
+        proposed_by TEXT,
+        created_at TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        notes TEXT,
+        metadata_json TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_review_queue_status ON review_queue(status);
+      CREATE INDEX IF NOT EXISTS idx_review_queue_status_type_created_at
+        ON review_queue(status, review_type, created_at DESC);
+    `);
+    }
+    createLegacyReviewItem(params) {
+        this.ensureLegacyReviewQueueTable();
+        const id = createId("rev");
+        this.db
+            .prepare(`INSERT INTO review_queue (
+          id, entity_type, entity_id, review_type, proposed_by, created_at, status, notes, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, params.entityType, params.entityId, params.reviewType, params.proposedBy, nowIso(), params.status ?? "pending", params.notes ?? null, JSON.stringify(params.metadata ?? {}));
+        const row = this.db.prepare(`SELECT * FROM review_queue WHERE id = ?`).get(id);
+        return mapLegacyReviewQueue(assertPresent(row, `Legacy review item ${id} not found`));
+    }
+    recomputeGovernanceTargets(input) {
+        const limit = input.limit;
+        const targetIds = input.entityIds?.length ? input.entityIds : undefined;
+        const nodeIds = !input.entityType || input.entityType === "node" ? this.listNodeIdsForGovernance(limit, targetIds) : [];
+        const relationIds = !input.entityType || input.entityType === "relation" ? this.listRelationIdsForGovernance(limit, targetIds) : [];
+        return { nodeIds, relationIds };
+    }
+    getPendingRelationUsageStats(since) {
+        const whereClause = since ? "WHERE created_at > ?" : "";
+        const bindings = since ? [since] : [];
+        const statsRow = this.db
+            .prepare(`SELECT
+           COUNT(*) AS event_count,
+           MIN(created_at) AS earliest_event_at,
+           MAX(created_at) AS latest_event_at
+         FROM relation_usage_events
+         ${whereClause}`)
+            .get(...bindings);
+        const relationRows = this.db
+            .prepare(`SELECT
+           relation_id,
+           MAX(created_at) AS latest_event_at
+         FROM relation_usage_events
+         ${whereClause}
+         GROUP BY relation_id
+         ORDER BY latest_event_at DESC`)
+            .all(...bindings);
+        return {
+            relationIds: relationRows.map((row) => String(row.relation_id)),
+            eventCount: Number(statsRow.event_count ?? 0),
+            earliestEventAt: statsRow.earliest_event_at ? String(statsRow.earliest_event_at) : null,
+            latestEventAt: statsRow.latest_event_at ? String(statsRow.latest_event_at) : null
+        };
+    }
+    recomputeInferredRelationScores(input) {
+        const where = [];
+        const values = [];
+        if (!input.relationIds?.length) {
+            where.push(`status != 'expired'`);
+        }
+        if (input.generator) {
+            where.push("generator = ?");
+            values.push(input.generator);
+        }
+        if (input.relationIds?.length) {
+            where.push(`id IN (${input.relationIds.map(() => "?").join(", ")})`);
+            values.push(...input.relationIds);
+        }
+        const whereClause = where.length ? `WHERE ${where.join(" AND ")}` : "";
+        const rows = this.db
+            .prepare(`SELECT * FROM inferred_relations
+         ${whereClause}
+         ORDER BY last_computed_at ASC
+         LIMIT ?`)
+            .all(...values, input.limit);
+        if (!rows.length) {
+            return {
+                updatedCount: 0,
+                expiredCount: 0,
+                items: []
+            };
+        }
+        const relationIds = rows.map((row) => String(row.id));
+        const summaries = this.getRelationUsageSummaries(relationIds);
+        const now = nowIso();
+        const updateStatement = this.db.prepare(`UPDATE inferred_relations
+       SET usage_score = ?, final_score = ?, status = ?, last_computed_at = ?
+       WHERE id = ?`);
+        let expiredCount = 0;
+        const items = [];
+        this.runInTransaction(() => {
+            for (const row of rows) {
+                const id = String(row.id);
+                const currentStatus = String(row.status);
+                const expiresAt = row.expires_at ? String(row.expires_at) : null;
+                const recomputed = computeMaintainedScores(Number(row.base_score), summaries.get(id), String(row.last_computed_at));
+                const nextStatus = expiresAt && expiresAt <= now ? "expired" : currentStatus;
+                if (nextStatus === "expired") {
+                    expiredCount += 1;
+                }
+                updateStatement.run(recomputed.usageScore, recomputed.finalScore, nextStatus, now, id);
+                items.push(mapInferredRelation({
+                    ...row,
+                    usage_score: recomputed.usageScore,
+                    final_score: recomputed.finalScore,
+                    status: nextStatus,
+                    last_computed_at: now
+                }));
+            }
+        });
+        return {
+            updatedCount: rows.length,
+            expiredCount,
+            items
+        };
+    }
+    countInferredRelations(status) {
+        const row = status
+            ? this.db.prepare(`SELECT COUNT(*) AS total FROM inferred_relations WHERE status = ?`).get(status)
+            : this.db.prepare(`SELECT COUNT(*) AS total FROM inferred_relations`).get();
+        return Number(row.total ?? 0);
+    }
+    updateRelationStatus(id, status) {
+        this.db.prepare(`UPDATE relations SET status = ? WHERE id = ?`).run(status, id);
+        return this.getRelation(id);
+    }
+    listNodeActivities(nodeId, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT * FROM activities WHERE target_node_id = ? ORDER BY created_at DESC LIMIT ?`)
+            .all(nodeId, limit);
+        return rows.map(mapActivity);
+    }
+    listActivitiesForNodeIds(nodeIds, limit = 200) {
+        if (!nodeIds.length) {
+            return [];
+        }
+        const uniqueIds = Array.from(new Set(nodeIds));
+        const rows = this.db
+            .prepare(`SELECT *
+         FROM activities
+         WHERE target_node_id IN (${uniqueIds.map(() => "?").join(", ")})
+         ORDER BY created_at ASC, id ASC
+         LIMIT ?`)
+            .all(...uniqueIds, limit);
+        return rows.map(mapActivity);
+    }
+    appendActivity(input) {
+        const id = createId("act");
+        const now = nowIso();
+        this.db
+            .prepare(`INSERT INTO activities (
+          id, target_node_id, activity_type, body, created_by, source_type, source_label, created_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.targetNodeId, input.activityType, input.body, input.source.actorLabel, input.source.actorType, input.source.actorLabel, now, JSON.stringify(input.metadata));
+        this.touchNode(input.targetNodeId);
+        this.markNodeSemanticIndexState(input.targetNodeId, "activity.appended", {
+            status: "pending",
+            updatedAt: now
+        });
+        return this.getActivity(id);
+    }
+    getActivity(id) {
+        const row = this.db.prepare(`SELECT * FROM activities WHERE id = ?`).get(id);
+        return mapActivity(assertPresent(row, `Activity ${id} not found`));
+    }
+    attachArtifact(input) {
+        const id = createId("art");
+        const now = nowIso();
+        const absolutePath = path.isAbsolute(input.path) ? input.path : path.resolve(this.workspaceRoot, input.path);
+        const realWorkspaceRoot = realpathSync(this.workspaceRoot);
+        if (!isPathWithinRoot(this.workspaceRoot, absolutePath)) {
+            throw new AppError(403, "FORBIDDEN", "Artifact path escapes workspace root.");
+        }
+        const artifactRoot = path.join(this.workspaceRoot, "artifacts");
+        const realArtifactRoot = realpathSync(artifactRoot);
+        if (!isPathWithinRoot(artifactRoot, absolutePath)) {
+            throw new AppError(403, "FORBIDDEN", "Artifact path must stay inside the workspace artifacts directory.");
+        }
+        let resolvedPath = "";
+        let stats = null;
+        try {
+            const entryStats = lstatSync(absolutePath);
+            if (entryStats.isSymbolicLink()) {
+                throw new AppError(403, "FORBIDDEN", "Artifact path must not be a symbolic link.");
+            }
+            resolvedPath = realpathSync(absolutePath);
+            if (!isPathWithinRoot(realWorkspaceRoot, resolvedPath)) {
+                throw new AppError(403, "FORBIDDEN", "Artifact path escapes workspace root.");
+            }
+            if (!isPathWithinRoot(realArtifactRoot, resolvedPath)) {
+                throw new AppError(403, "FORBIDDEN", "Artifact path must stay inside the workspace artifacts directory.");
+            }
+            stats = statSync(resolvedPath);
+            if (!stats.isFile()) {
+                throw new AppError(400, "INVALID_INPUT", "Artifact path must reference a regular file.");
+            }
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw error;
+            }
+            if (error instanceof Error &&
+                "code" in error &&
+                (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ELOOP")) {
+                throw new AppError(404, "NOT_FOUND", "Artifact path does not exist.");
+            }
+            throw error;
+        }
+        if (!stats) {
+            throw new AppError(500, "INTERNAL_ERROR", "Artifact metadata could not be read.");
+        }
+        this.db
+            .prepare(`INSERT INTO artifacts (
+          id, node_id, path, mime_type, size_bytes, checksum, created_by, source_label, created_at, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, input.nodeId, normalizeArtifactPath(path.relative(this.workspaceRoot, absolutePath)), input.mimeType ?? null, stats.size, checksumText(`${resolvedPath}:${stats.size}:${stats.mtimeMs}`), input.source.actorLabel, input.source.actorLabel, now, JSON.stringify(input.metadata));
+        this.markNodeSemanticIndexState(input.nodeId, "artifact.attached", {
+            status: "pending",
+            updatedAt: now
+        });
+        return this.getArtifact(id);
+    }
+    listArtifacts(nodeId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM artifacts WHERE node_id = ? ORDER BY created_at DESC`)
+            .all(nodeId);
+        return rows.map(mapArtifact);
+    }
+    getArtifact(id) {
+        const row = this.db.prepare(`SELECT * FROM artifacts WHERE id = ?`).get(id);
+        return mapArtifact(assertPresent(row, `Artifact ${id} not found`));
+    }
+    getWorkspaceKey() {
+        return this.workspaceKey;
+    }
+    hasArtifactAtPath(relativePath) {
+        const normalizedPath = normalizeArtifactPath(relativePath);
+        const row = this.db
+            .prepare(`SELECT 1 AS present FROM artifacts WHERE path = ? LIMIT 1`)
+            .get(normalizedPath);
+        return Boolean(row?.present);
+    }
+    recordProvenance(params) {
+        const id = createId("prov");
+        const timestamp = nowIso();
+        this.db
+            .prepare(`INSERT INTO provenance_events (
+          id, entity_type, entity_id, operation_type, actor_type, actor_label, tool_name, tool_version,
+          timestamp, input_ref, metadata_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, params.entityType, params.entityId, params.operationType, params.source.actorType, params.source.actorLabel, params.source.toolName, params.source.toolVersion ?? null, timestamp, params.inputRef ?? null, JSON.stringify(params.metadata ?? {}));
+        return this.getProvenance(id);
+    }
+    listProvenance(entityType, entityId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM provenance_events
+         WHERE entity_type = ? AND entity_id = ?
+         ORDER BY timestamp DESC`)
+            .all(entityType, entityId);
+        return rows.map(mapProvenance);
+    }
+    getProvenance(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM provenance_events WHERE id = ?`)
+            .get(id);
+        return mapProvenance(assertPresent(row, `Provenance ${id} not found`));
+    }
+    listIntegrations() {
+        const rows = this.db
+            .prepare(`SELECT * FROM integrations ORDER BY updated_at DESC`)
+            .all();
+        return rows.map(mapIntegration);
+    }
+    registerIntegration(input) {
+        const id = createId("int");
+        const now = nowIso();
+        this.db
+            .prepare(`INSERT INTO integrations (
+          id, name, kind, status, capabilities_json, config_json, created_at, updated_at
+        ) VALUES (?, ?, ?, 'active', ?, ?, ?, ?)`)
+            .run(id, input.name, input.kind, JSON.stringify(input.capabilities), JSON.stringify(input.config), now, now);
+        return this.getIntegration(id);
+    }
+    updateIntegration(id, input) {
+        const existing = this.getIntegration(id);
+        this.db
+            .prepare(`UPDATE integrations
+         SET name = ?, status = ?, capabilities_json = ?, config_json = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(input.name ?? existing.name, input.status ?? existing.status, JSON.stringify(input.capabilities ?? existing.capabilities), JSON.stringify(input.config ?? existing.config), nowIso(), id);
+        return this.getIntegration(id);
+    }
+    getIntegration(id) {
+        const row = this.db.prepare(`SELECT * FROM integrations WHERE id = ?`).get(id);
+        return mapIntegration(assertPresent(row, `Integration ${id} not found`));
+    }
+    getSettings(keys) {
+        const rows = keys?.length
+            ? this.db
+                .prepare(`SELECT * FROM settings WHERE key IN (${keys.map(() => "?").join(", ")})`)
+                .all(...keys)
+            : this.db.prepare(`SELECT * FROM settings`).all();
+        return Object.fromEntries(rows.map((row) => [String(row.key), parseJson(row.value_json, null)]));
+    }
+    writeSetting(key, value) {
+        this.db
+            .prepare(`INSERT INTO settings (key, value_json)
+         VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value_json = excluded.value_json`)
+            .run(key, JSON.stringify(value));
+    }
+    isSemanticReindexSettingKey(key) {
+        return (key === "search.semantic.enabled" ||
+            key === "search.semantic.provider" ||
+            key === "search.semantic.model" ||
+            key === "search.semantic.chunk.enabled");
+    }
+    setSetting(key, value) {
+        if (this.isSemanticReindexSettingKey(key)) {
+            this.updateSemanticSetting(key, value);
+            return;
+        }
+        this.writeSetting(key, value);
+    }
+    setSettings(values) {
+        const keys = Object.keys(values);
+        if (!keys.length) {
+            return;
+        }
+        const requiresSemanticCheck = keys.some((key) => this.isSemanticReindexSettingKey(key));
+        const previousSettings = requiresSemanticCheck ? this.readSemanticIndexSettings() : null;
+        for (const [key, value] of Object.entries(values)) {
+            this.writeSetting(key, value);
+        }
+        if (requiresSemanticCheck) {
+            this.writePendingSemanticTransitionKeys([]);
+        }
+        if (!requiresSemanticCheck || !previousSettings) {
+            return;
+        }
+        const nextSettings = this.readSemanticIndexSettings();
+        if (shouldReindexForSemanticConfigChange(previousSettings, nextSettings)) {
+            this.queueSemanticConfigurationReindex();
+        }
+    }
+    setSettingIfMissing(key, value) {
+        this.db
+            .prepare(`INSERT INTO settings (key, value_json)
+         VALUES (?, ?)
+         ON CONFLICT(key) DO NOTHING`)
+            .run(key, JSON.stringify(value));
+    }
+    ensureBaseSettings(settings) {
+        for (const [key, value] of Object.entries(settings)) {
+            this.setSettingIfMissing(key, value);
+        }
+    }
+    upsertBaseSettings(settings) {
+        this.setSettings(settings);
+    }
+}