prism-mcp-server 4.2.0 → 4.6.0

package/dist/server.js

@@ -70,6 +70,8 @@ import { acquireLock, registerShutdownHandlers } from "./lifecycle.js";
 // correct backend (Supabase or SQLite) with proper error handling.
 import { getStorage } from "./storage/index.js";
 import { getSettingSync, initConfigStorage } from "./storage/configStorage.js";
+import { getTracer, initTelemetry } from "./utils/telemetry.js";
+import { context as otelContext, trace, SpanStatusCode } from "@opentelemetry/api";
 // ─── Import Tool Definitions (schemas) and Handlers (implementations) ─────
 import { WEB_SEARCH_TOOL, BRAVE_WEB_SEARCH_CODE_MODE_TOOL, LOCAL_SEARCH_TOOL, BRAVE_LOCAL_SEARCH_CODE_MODE_TOOL, CODE_MODE_TRANSFORM_TOOL, BRAVE_ANSWERS_TOOL, RESEARCH_PAPER_ANALYSIS_TOOL, webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, braveLocalSearchCodeModeHandler, codeModeTransformHandler, braveAnswersHandler, researchPaperAnalysisHandler, } from "./tools/index.js";
 // Session memory tools — only used if Supabase is configured
@@ -84,6 +86,8 @@ SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL,
 SESSION_HEALTH_CHECK_TOOL, 
 // ─── Phase 2: GDPR Memory Deletion tool definition ───
 SESSION_FORGET_MEMORY_TOOL, 
+// ─── Phase 2: GDPR Export tool definition ───
+SESSION_EXPORT_MEMORY_TOOL, 
 // ─── v3.1: TTL Retention tool ───
 KNOWLEDGE_SET_RETENTION_TOOL, 
 // v4.0: Active Behavioral Memory tools
@@ -98,10 +102,14 @@ sessionSaveImageHandler, sessionViewImageHandler,
 sessionHealthCheckHandler, 
 // ─── Phase 2: GDPR Memory Deletion handler ───
 sessionForgetMemoryHandler, 
+// ─── Phase 2: GDPR Export handler ───
+sessionExportMemoryHandler, 
 // ─── v3.1: TTL Retention handler ───
 knowledgeSetRetentionHandler, 
 // v4.0: Active Behavioral Memory handlers
 sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, 
+// v4.2: Knowledge Sync Rules
+KNOWLEDGE_SYNC_RULES_TOOL, knowledgeSyncRulesHandler, 
 // ─── v3.0: Agent Hivemind tools ───
 AGENT_REGISTRY_TOOLS, agentRegisterHandler, agentHeartbeatHandler, agentListTeamHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
@@ -159,6 +167,10 @@ function buildSessionMemoryTools(autoloadList) {
         SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
         KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
         KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
+        // ─── v4.2: Knowledge Sync Rules tool ───
+        KNOWLEDGE_SYNC_RULES_TOOL, // knowledge_sync_rules — sync graduated insights to IDE rules files
+        // ─── Phase 2: GDPR Export tool ───
+        SESSION_EXPORT_MEMORY_TOOL, // session_export_memory — full portability export (Article 20)
     ];
 }
 // ─── v0.4.0: Resource Subscription Tracking ──────────────────────
@@ -534,148 +546,221 @@ export function createServer() {
     //   - session_search_memory (Enhancement #4)
     // The server reference is passed to sessionSaveHandoffHandler so it
     // can trigger resource update notifications on successful saves.
+    //
+    // v4.6.0: Every tool call is wrapped in a root OTel span (mcp.call_tool).
+    // The span is parented via AsyncLocalStorage context propagation — all
+    // child spans from LLM adapters and background workers are automatically
+    // nested under this root span in Jaeger/Zipkin without explicit ref-passing.
+    // When otel_enabled=false, getTracer() returns a no-op tracer — zero overhead.
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        try {
-            const { name, arguments: args } = request.params;
-            if (!args) {
-                throw new Error("No arguments provided");
+        const { name, arguments: args } = request.params;
+        // Start the root span for this MCP tool invocation.
+        // All child spans (llm.generate_text, worker.vlm_caption, etc.) are
+        // automatically parented to this span via the propagated context.
+        const rootSpan = getTracer().startSpan("mcp.call_tool", {
+            attributes: {
+                "tool.name": name,
+                // Capture the project attribute if present (most memory tools have it)
+                "project": args?.project ?? "unknown",
+            },
+        });
+        // context.with() sets the root span as the active span for the duration
+        // of this async operation. AsyncLocalStorage ensures the context flows
+        // through await chains — including fire-and-forget workers launched
+        // within the handler body (e.g. imageCaptioner, embeddings backfill).
+        return otelContext.with(trace.setSpan(otelContext.active(), rootSpan), async () => {
+            try {
+                if (!args) {
+                    throw new Error("No arguments provided");
+                }
+                let result;
+                switch (name) {
+                    // ── Search & Analysis Tools (always available) ──
+                    case "brave_web_search":
+                        result = await webSearchHandler(args);
+                        break;
+                    case "brave_web_search_code_mode":
+                        result = await braveWebSearchCodeModeHandler(args);
+                        break;
+                    case "brave_local_search":
+                        result = await localSearchHandler(args);
+                        break;
+                    case "brave_local_search_code_mode":
+                        result = await braveLocalSearchCodeModeHandler(args);
+                        break;
+                    case "code_mode_transform":
+                        result = await codeModeTransformHandler(args);
+                        break;
+                    case "brave_answers":
+                        result = await braveAnswersHandler(args);
+                        break;
+                    case "gemini_research_paper_analysis":
+                        result = await researchPaperAnalysisHandler(args);
+                        break;
+                    // ── Session Memory Tools (only callable when Supabase is configured) ──
+                    // REVIEWER NOTE: Even though these tools won't appear in the
+                    // tool list without Supabase, we still guard each handler call
+                    // in case of direct invocation.
+                    case "session_save_ledger":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionSaveLedgerHandler(args);
+                        break;
+                    case "session_save_handoff":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        // REVIEWER NOTE: v0.4.0 passes the server reference so the
+                        // handler can trigger resource update notifications after
+                        // a successful save. See notifyResourceUpdate() above.
+                        result = await sessionSaveHandoffHandler(args, server);
+                        break;
+                    case "session_load_context":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionLoadContextHandler(args);
+                        break;
+                    case "knowledge_search":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeSearchHandler(args);
+                        break;
+                    case "knowledge_forget":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeForgetHandler(args);
+                        break;
+                    // ─── v0.4.0: New Session Memory Tools ───
+                    case "session_compact_ledger":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await compactLedgerHandler(args);
+                        break;
+                    case "session_search_memory":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionSearchMemoryHandler(args);
+                        break;
+                    // ─── v2.0: Time Travel Tools ───
+                    case "memory_history":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await memoryHistoryHandler(args);
+                        break;
+                    case "memory_checkout":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await memoryCheckoutHandler(args);
+                        break;
+                    // ─── v2.0: Visual Memory Tools ───
+                    case "session_save_image":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionSaveImageHandler(args);
+                        break;
+                    case "session_view_image":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionViewImageHandler(args);
+                        break;
+                    // ─── v2.2.0: Health Check Tool ───
+                    case "session_health_check":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionHealthCheckHandler(args);
+                        break;
+                    // ─── Phase 2: GDPR Memory Deletion Tool ───
+                    case "session_forget_memory":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionForgetMemoryHandler(args);
+                        break;
+                    // ─── Phase 2: GDPR Export Tool ───
+                    case "session_export_memory":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionExportMemoryHandler(args);
+                        break;
+                    case "knowledge_set_retention":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeSetRetentionHandler(args);
+                        break;
+                    // ─── v4.0: Active Behavioral Memory Tools ───
+                    case "session_save_experience":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await sessionSaveExperienceHandler(args);
+                        break;
+                    case "knowledge_upvote":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeUpvoteHandler(args);
+                        break;
+                    case "knowledge_downvote":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeDownvoteHandler(args);
+                        break;
+                    // ─── v4.2: Knowledge Sync Rules Tool ───
+                    case "knowledge_sync_rules":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        result = await knowledgeSyncRulesHandler(args);
+                        break;
+                    // ─── v3.0: Agent Hivemind Tools ───
+                    case "agent_register":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured.");
+                        if (!PRISM_ENABLE_HIVEMIND)
+                            throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
+                        result = await agentRegisterHandler(args);
+                        break;
+                    case "agent_heartbeat":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured.");
+                        if (!PRISM_ENABLE_HIVEMIND)
+                            throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
+                        result = await agentHeartbeatHandler(args);
+                        break;
+                    case "agent_list_team":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured.");
+                        if (!PRISM_ENABLE_HIVEMIND)
+                            throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
+                        result = await agentListTeamHandler(args);
+                        break;
+                    default:
+                        result = {
+                            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                            isError: true,
+                        };
+                }
+                rootSpan.setStatus({ code: SpanStatusCode.OK });
+                return result;
             }
-            switch (name) {
-                // ── Search & Analysis Tools (always available) ──
-                case "brave_web_search":
-                    return await webSearchHandler(args);
-                case "brave_web_search_code_mode":
-                    return await braveWebSearchCodeModeHandler(args);
-                case "brave_local_search":
-                    return await localSearchHandler(args);
-                case "brave_local_search_code_mode":
-                    return await braveLocalSearchCodeModeHandler(args);
-                case "code_mode_transform":
-                    return await codeModeTransformHandler(args);
-                case "brave_answers":
-                    return await braveAnswersHandler(args);
-                case "gemini_research_paper_analysis":
-                    return await researchPaperAnalysisHandler(args);
-                // ── Session Memory Tools (only callable when Supabase is configured) ──
-                // REVIEWER NOTE: Even though these tools won't appear in the
-                // tool list without Supabase, we still guard each handler call
-                // in case of direct invocation.
-                case "session_save_ledger":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionSaveLedgerHandler(args);
-                case "session_save_handoff":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    // REVIEWER NOTE: v0.4.0 passes the server reference so the
-                    // handler can trigger resource update notifications after
-                    // a successful save. See notifyResourceUpdate() above.
-                    return await sessionSaveHandoffHandler(args, server);
-                case "session_load_context":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionLoadContextHandler(args);
-                case "knowledge_search":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await knowledgeSearchHandler(args);
-                case "knowledge_forget":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await knowledgeForgetHandler(args);
-                // ─── v0.4.0: New Session Memory Tools ───
-                case "session_compact_ledger":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await compactLedgerHandler(args);
-                case "session_search_memory":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionSearchMemoryHandler(args);
-                // ─── v2.0: Time Travel Tools ───
-                case "memory_history":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await memoryHistoryHandler(args);
-                case "memory_checkout":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await memoryCheckoutHandler(args);
-                // ─── v2.0: Visual Memory Tools ───
-                case "session_save_image":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionSaveImageHandler(args);
-                case "session_view_image":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionViewImageHandler(args);
-                // ─── v2.2.0: Health Check Tool ───
-                case "session_health_check":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionHealthCheckHandler(args);
-                // ─── Phase 2: GDPR Memory Deletion Tool ───
-                case "session_forget_memory":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionForgetMemoryHandler(args);
-                // ─── v3.1: TTL Retention Tool ───
-                case "knowledge_set_retention":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await knowledgeSetRetentionHandler(args);
-                // ─── v4.0: Active Behavioral Memory Tools ───
-                case "session_save_experience":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await sessionSaveExperienceHandler(args);
-                case "knowledge_upvote":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await knowledgeUpvoteHandler(args);
-                case "knowledge_downvote":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
-                    return await knowledgeDownvoteHandler(args);
-                // ─── v3.0: Agent Hivemind Tools ───
-                case "agent_register":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured.");
-                    if (!PRISM_ENABLE_HIVEMIND)
-                        throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
-                    return await agentRegisterHandler(args);
-                case "agent_heartbeat":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured.");
-                    if (!PRISM_ENABLE_HIVEMIND)
-                        throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
-                    return await agentHeartbeatHandler(args);
-                case "agent_list_team":
-                    if (!SESSION_MEMORY_ENABLED)
-                        throw new Error("Session memory not configured.");
-                    if (!PRISM_ENABLE_HIVEMIND)
-                        throw new Error("Hivemind not enabled. Set PRISM_ENABLE_HIVEMIND=true.");
-                    return await agentListTeamHandler(args);
-                default:
-                    return {
-                        content: [{ type: "text", text: `Unknown tool: ${name}` }],
-                        isError: true,
-                    };
+            catch (error) {
+                console.error(`Error in tool handler: ${error instanceof Error ? error.message : String(error)}`);
+                rootSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                rootSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
             }
-        }
-        catch (error) {
-            console.error(`Error in tool handler: ${error instanceof Error ? error.message : String(error)}`);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
+            finally {
+                // Always end the root span — even on error — to avoid span leaks
+                // in the BatchSpanProcessor's in-memory queue.
+                rootSpan.end();
+            }
+        });
     });
     return server;
 }
@@ -754,6 +839,11 @@ export async function startServer() {
     // during the Initialize handshake — zero extra latency for resource reads.
     // initConfigStorage() is local SQLite only (~5ms), safe to await.
     await initConfigStorage();
+    // v4.6.0: Initialize OTel AFTER the settings cache is warm so that
+    // initTelemetry() can read otel_enabled/otel_endpoint from getSettingSync()
+    // synchronously. This is a synchronous call — no await needed.
+    // No-op when otel_enabled=false (the default).
+    initTelemetry();
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/storage/sqlite.js

@@ -1391,4 +1391,56 @@ export class SqliteStorage {
         });
         debugLog(`[SqliteStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta}`);
     }
+    // ─── v4.2: Graduated Insights Query ──────────────────────────
+    //
+    // Returns ledger entries that have "graduated" — i.e., their
+    // importance score has reached the threshold (default 7).
+    // Used by knowledge_sync_rules to physically write insights
+    // into .cursorrules / .clauderules files at the project repo path.
+    async getGraduatedInsights(project, userId, minImportance = 7) {
+        const result = await this.db.execute({
+            sql: `SELECT id, project, user_id, role, summary, importance,
+                   event_type, decisions, created_at
+            FROM session_ledger
+            WHERE project = ? AND user_id = ?
+              AND importance >= ?
+              AND deleted_at IS NULL
+              AND archived_at IS NULL
+            ORDER BY importance DESC, created_at DESC`,
+            args: [project, userId, minImportance],
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            project: row.project,
+            user_id: row.user_id,
+            role: row.role || "global",
+            summary: row.summary,
+            importance: Number(row.importance),
+            event_type: row.event_type || "session",
+            decisions: this.parseJsonColumn(row.decisions),
+            created_at: row.created_at,
+            conversation_id: "",
+        }));
+    }
+    // ─── v4.3: Standalone Importance Decay ────────────────────
+    //
+    // Extracted from expireByTTL so decay can be triggered independently
+    // (e.g. fire-and-forget from session_save_ledger) without needing
+    // an active TTL retention policy.
+    async decayImportance(project, userId, decayDays) {
+        const result = await this.db.execute({
+            sql: `UPDATE session_ledger
+            SET importance = MAX(0, importance - 1)
+            WHERE project = ? AND user_id = ?
+              AND importance > 0
+              AND event_type != 'session'
+              AND created_at < datetime('now', '-' || ? || ' days')
+              AND deleted_at IS NULL`,
+            args: [project, userId, decayDays],
+        });
+        const decayed = result.rowsAffected || 0;
+        if (decayed > 0) {
+            debugLog(`[SqliteStorage] decayImportance: reduced ${decayed} entries for "${project}" (>${decayDays}d old)`);
+        }
+    }
 }

package/dist/storage/supabase.js

@@ -356,31 +356,90 @@ export class SupabaseStorage {
         catch (e) {
             debugLog("[SupabaseStorage] expireByTTL failed: " + (e instanceof Error ? e.message : String(e)));
         }
+        // Fix #5: Decay importance parity with SQLite.
+        // NOTE: Unlike SQLite (which decays on every session_save_ledger health sweep),
+        // Supabase decay is TTL-gated — it only runs when knowledge_set_retention has
+        // been configured for this project. Projects without a TTL policy will not
+        // experience importance decay. Future improvement: fire this from
+        // sessionSaveLedgerHandler (fire-and-forget) to achieve full parity.
+        try {
+            await supabaseRpc("prism_decay_importance", {
+                p_project: project,
+                p_user_id: userId,
+                p_days: 30,
+            });
+            debugLog(`[SupabaseStorage] Importance decay sweep completed for "${project}"`);
+        }
+        catch (e) {
+            // Non-fatal: decay is a best-effort background operation
+            debugLog("[SupabaseStorage] prism_decay_importance failed (non-fatal): " + (e instanceof Error ? e.message : String(e)));
+        }
         // Supabase PATCH doesn't return rowsAffected — return 0 (UI doesn't need exact count)
         debugLog(`[SupabaseStorage] TTL sweep completed for "${project}" (cutoff: ${cutoffStr})`);
         return { expired: 0 };
     }
     // ─── v4.0: Insight Graduation ──────────────────────────────────
     async adjustImportance(id, delta, userId) {
-        // Supabase PATCH can't do MAX(0, importance + delta) directly.
-        // Fetch current value first, compute new, then patch.
+        // Fix #4: Use atomic RPC instead of read-then-write.
+        // prism_adjust_importance computes MAX(0, importance + delta) in one
+        // SQL UPDATE, eliminating the race condition in the old pattern.
         try {
-            const data = await supabaseGet("session_ledger", {
-                id: `eq.${id}`,
-                user_id: `eq.${userId}`,
-                select: "importance",
+            await supabaseRpc("prism_adjust_importance", {
+                p_id: id,
+                p_user_id: userId,
+                p_delta: delta,
             });
-            const rows = Array.isArray(data) ? data : [];
-            const current = rows[0]?.importance ?? 0;
-            const newVal = Math.max(0, current + delta);
-            await supabasePatch("session_ledger", { importance: newVal }, {
-                id: `eq.${id}`,
-                user_id: `eq.${userId}`,
+            debugLog(`[SupabaseStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta} via RPC`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            debugLog("[SupabaseStorage] adjustImportance failed: " + msg);
+            throw e; // Fix #3: rethrow so handlers can surface isError:true
+        }
+    }
+    // ─── v4.2: Graduated Insights Query ──────────────────────────
+    async getGraduatedInsights(project, userId, minImportance = 7) {
+        const data = await supabaseGet("session_ledger", {
+            project: `eq.${project}`,
+            user_id: `eq.${userId}`,
+            importance: `gte.${minImportance}`,
+            deleted_at: "is.null",
+            archived_at: "is.null",
+            select: "id,project,user_id,role,summary,importance,event_type,decisions,created_at",
+            order: "importance.desc,created_at.desc",
+        });
+        const rows = Array.isArray(data) ? data : [];
+        return rows.map((r) => ({
+            id: r.id,
+            project: r.project,
+            user_id: r.user_id,
+            role: r.role || "global",
+            summary: r.summary,
+            importance: r.importance || 0,
+            event_type: r.event_type || "session",
+            decisions: Array.isArray(r.decisions) ? r.decisions : [],
+            created_at: r.created_at,
+            conversation_id: "",
+        }));
+    }
+    // ─── v4.3: Standalone Importance Decay ─────────────────────
+    //
+    // Calls the prism_decay_importance RPC (migration 028) directly,
+    // decoupled from expireByTTL so it can be triggered fire-and-forget
+    // from session_save_ledger without a TTL policy being active.
+    async decayImportance(project, userId, decayDays) {
+        try {
+            await supabaseRpc("prism_decay_importance", {
+                p_project: project,
+                p_user_id: userId,
+                p_days: decayDays,
             });
-            debugLog(`[SupabaseStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta} (${current} → ${newVal})`);
+            debugLog(`[SupabaseStorage] decayImportance: sweep completed for "${project}" (>${decayDays}d old)`);
         }
         catch (e) {
-            debugLog("[SupabaseStorage] adjustImportance failed: " + (e instanceof Error ? e.message : String(e)));
+            // Non-fatal: decay is best-effort — log and rethrow so fire-and-forget caller can see it
+            debugLog("[SupabaseStorage] decayImportance failed: " + (e instanceof Error ? e.message : String(e)));
+            throw e;
         }
     }
 }

package/dist/storage/supabaseMigrations.js

@@ -56,7 +56,48 @@ export const MIGRATIONS = [
           AND deleted_at IS NULL AND archived_at IS NULL;
     `,
     },
-    // Future migrations go here (version 28+)
+    {
+        version: 28,
+        name: "importance_rpcs",
+        sql: `
+      -- Fix #4: Atomic importance adjustment — eliminates read-then-write race condition
+      CREATE OR REPLACE FUNCTION prism_adjust_importance(
+        p_id TEXT, p_user_id TEXT, p_delta INTEGER
+      )
+      RETURNS void
+      LANGUAGE plpgsql
+      SECURITY DEFINER
+      AS $$
+      BEGIN
+        UPDATE session_ledger
+        SET importance = GREATEST(0, importance + p_delta)
+        WHERE id = p_id AND user_id = p_user_id;
+      END;
+      $$;
+
+      -- Fix #5: Importance decay — parity with SQLite backend
+      CREATE OR REPLACE FUNCTION prism_decay_importance(
+        p_project TEXT, p_user_id TEXT, p_days INTEGER
+      )
+      RETURNS void
+      LANGUAGE plpgsql
+      SECURITY DEFINER
+      AS $$
+      BEGIN
+        UPDATE session_ledger
+        SET importance = GREATEST(0, importance - 1)
+        WHERE project = p_project
+          AND user_id = p_user_id
+          AND importance > 0
+          AND event_type <> 'session'
+          AND created_at < now() - (p_days || ' days')::interval
+          AND deleted_at IS NULL
+          AND archived_at IS NULL;
+      END;
+      $$;
+    `,
+    },
+    // Future migrations go here (version 29+)
 ];
 /**
  * Current schema version — derived from the MIGRATIONS array.