@jungjaehoon/mama-core 1.7.0 → 1.8.1

package/dist/db-adapter/node-sqlite-adapter.js

@@ -88,6 +88,12 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
     _vectorSearchEnabled = true;
     vectorCache = new Map();
     topicCache = new Map();
+    // Effective status (status, falling back to outcome) per decision rowid. Used as a
+    // search-time optimization only - recallMemory's post-filter stays the authority
+    // (this cache can lag a status UPDATE until the next reloadVectorCache).
+    statusCache = new Map();
+    decisionsHasStatusColumns = false;
+    decisionsColumnInfoChecked = false;
     constructor(config = {}) {
         super();
         this.config = config;
@@ -140,6 +146,46 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
     reloadVectorCache() {
         this.loadVectorCache();
     }
+    // Re-read one decision's effective status into the cache. MUST be called after
+    // any status transition that can move a row OUT of an excluded state (e.g.
+    // promoteMemoryStatus staging->active): the vectorSearch pre-filter drops
+    // excluded rowids before the api post-filter ever sees them, so a stale
+    // excluded entry would make an active row unrecallable until restart.
+    refreshDecisionStatusCache(rowid) {
+        if (!this.isConnected()) {
+            throw new Error('Database not connected');
+        }
+        if (!this.decisionsColumnInfoChecked) {
+            this.refreshDecisionColumnInfo();
+        }
+        const cacheSelect = this.decisionsHasStatusColumns
+            ? 'SELECT topic, status, outcome FROM decisions WHERE rowid = ?'
+            : 'SELECT topic, NULL AS status, NULL AS outcome FROM decisions WHERE rowid = ?';
+        const row = this.prepare(cacheSelect).get(rowid);
+        if (!row) {
+            this.statusCache.delete(rowid);
+            this.topicCache.delete(rowid);
+            return;
+        }
+        this.topicCache.set(rowid, row.topic);
+        const effectiveStatus = row.status || row.outcome;
+        if (effectiveStatus) {
+            this.statusCache.set(rowid, effectiveStatus);
+        }
+        else {
+            this.statusCache.delete(rowid);
+        }
+    }
+    refreshDecisionColumnInfo() {
+        if (!this.db)
+            return new Set();
+        const decisionCols = new Set(this.db.prepare('PRAGMA table_info(decisions)').all().map((c) => c.name));
+        this.decisionsHasStatusColumns = decisionCols.has('status') && decisionCols.has('outcome');
+        // Only latch "checked" once the decisions table actually exists - introspecting
+        // a not-yet-migrated DB must not stop later calls from re-checking.
+        this.decisionsColumnInfoChecked = decisionCols.size > 0;
+        return decisionCols;
+    }
     loadVectorCache() {
         if (!this.db)
             return;
@@ -149,6 +195,7 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         if (tableCheck.length === 0) {
             this.vectorCache.clear();
             this.topicCache.clear();
+            this.statusCache.clear();
             return;
         }
         const start = Date.now();
@@ -161,11 +208,26 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                 this.vectorCache.set(row.rowid, vec);
             }
         }
-        // Load topic cache for scoped vector search
+        // Load topic + effective-status caches for scoped/filtered vector search.
+        // Legacy partial schemas may lack status/outcome (they are added by later
+        // migrations, and loadVectorCache also runs at connect time, before
+        // runMigrations) - introspect columns so prepare() cannot crash on them.
+        // A missing column just leaves statusCache empty; the api-layer post-filter
+        // remains the authority.
         this.topicCache.clear();
-        const topicRows = this.db.prepare('SELECT rowid, topic FROM decisions').all();
+        this.statusCache.clear();
+        const decisionCols = this.refreshDecisionColumnInfo();
+        const statusSelect = decisionCols.has('status') ? 'status' : 'NULL AS status';
+        const outcomeSelect = decisionCols.has('outcome') ? 'outcome' : 'NULL AS outcome';
+        const topicRows = this.db
+            .prepare(`SELECT rowid, topic, ${statusSelect}, ${outcomeSelect} FROM decisions`)
+            .all();
         for (const row of topicRows) {
             this.topicCache.set(row.rowid, row.topic);
+            const effectiveStatus = row.status || row.outcome;
+            if (effectiveStatus) {
+                this.statusCache.set(row.rowid, effectiveStatus);
+            }
         }
         const count = this.vectorCache.size;
         const elapsed = Date.now() - start;
@@ -220,7 +282,7 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             throw error;
         }
     }
-    vectorSearch(embedding, limit = 5, topicPrefix) {
+    vectorSearch(embedding, limit = 5, topicPrefix, excludeStatuses) {
         if (!this.isConnected()) {
             throw new Error('Database not connected');
         }
@@ -228,6 +290,7 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         const effectiveLimit = Math.max(limit, 1);
         const bestMatches = [];
         let minScore = -Infinity;
+        const excluded = excludeStatuses && excludeStatuses.length > 0 ? new Set(excludeStatuses) : null;
         for (const [rowid, candidate] of this.vectorCache) {
             if (candidate.length !== queryVector.length)
                 continue;
@@ -237,6 +300,13 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                 if (!topic || !topic.startsWith(topicPrefix))
                     continue;
             }
+            // Pre-filter by effective status so superseded history does not occupy
+            // top-K slots (the api-layer post-filter remains the authority)
+            if (excluded) {
+                const status = this.statusCache.get(rowid);
+                if (status && excluded.has(status))
+                    continue;
+            }
             const similarity = (0, embeddings_js_1.cosineSimilarity)(candidate, queryVector);
             if (bestMatches.length < effectiveLimit) {
                 bestMatches.push({ rowid, similarity, distance: 1 - similarity });
@@ -269,9 +339,7 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         const result = stmt.run(rowid, buffer);
         // Keep in-memory caches in sync
         this.vectorCache.set(rowid, vec);
-        const topicRow = this.prepare('SELECT topic FROM decisions WHERE rowid = ?').get(rowid);
-        if (topicRow)
-            this.topicCache.set(rowid, topicRow.topic);
+        this.refreshDecisionStatusCache(rowid);
         return result;
     }
     getLastInsertRowid() {
@@ -331,6 +399,11 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                     (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} recovered successfully`);
                     continue;
                 }
+                if (message.includes('duplicate column') && version === 39) {
+                    this.recoverConnectorEventOperatorSeqMigration039();
+                    (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Migration ${file} recovered successfully`);
+                    continue;
+                }
                 if (message.includes('duplicate column')) {
                     (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Migration ${file} skipped (duplicate column - already applied)`);
                     this.prepare('INSERT OR IGNORE INTO schema_version (version) VALUES (?)').run(version);
@@ -395,6 +468,18 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                 this.recoverConnectorEventScopeMigration034();
                 (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped connector event scope migration');
             }
+            const connectorColumnsAfterScopeRepair = this.tableColumns('connector_event_index');
+            const hasMissingOperatorSeqFeature = !connectorColumnsAfterScopeRepair.has('operator_ingest_seq') ||
+                !this.tableExists('connector_event_index_operator_seq_cursors') ||
+                !this.indexExists('idx_connector_event_index_operator_scope_seq') ||
+                !this.indexExists('idx_connector_event_index_operator_cursor_order') ||
+                !this.triggerExists('trg_connector_event_index_operator_ingest_seq_ai') ||
+                !this.triggerExists('trg_connector_event_index_operator_ingest_seq_explicit_ai') ||
+                !this.schemaVersionExists(39);
+            if (hasMissingOperatorSeqFeature) {
+                this.recoverConnectorEventOperatorSeqMigration039();
+                (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped connector event operator sequence migration');
+            }
         }
         if (!this.tableExists('twin_edges')) {
             this.applyRepairMigration(migrationsDir, '035-create-twin-edges.sql', 'twin edge ledger');
@@ -406,6 +491,33 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         if (!this.tableExists('context_packets')) {
             this.applyRepairMigration(migrationsDir, '037-create-context-packets.sql', 'context packet store');
         }
+        // TOMBSTONE (M6, 2026-07): the vnext_* operator tables (vnext_operator_cursors,
+        // vnext_operator_commits, operator_no_updates, worker_proposals) lost their last
+        // living reader/writer when the vNext parallel runtime was deleted in M4 (PR #120).
+        // They are intentionally KEPT: this repair path re-creates them on any DB that
+        // skipped migration 038, vnext_operator_commits holds an FK to
+        // vnext_operator_cursors, and shipped migrations are append-only. Do not drop
+        // them without also removing this repair block, the 040/041 repair/asserts below,
+        // and the schema-contract tests that pin them.
+        if (!this.tableExists('vnext_operator_cursors') ||
+            !this.tableExists('vnext_operator_commits') ||
+            !this.tableExists('operator_no_updates') ||
+            !this.tableExists('worker_proposals')) {
+            this.applyRepairMigration(migrationsDir, '038-create-vnext-operator-contracts.sql', 'vNext operator contracts');
+        }
+        // TOMBSTONE (M6, 2026-07): operator_memory_commit_intents (migrations 040/041)
+        // has no living reader/writer since M4 (PR #120). Kept for the same reasons as
+        // the 038 family above; the fail-loud asserts below still protect personal DBs
+        // that skipped or corrupted these migrations.
+        if (!this.tableExists('operator_memory_commit_intents') ||
+            !this.indexExists('idx_operator_memory_commit_intents_cursor_created')) {
+            this.applyRepairMigration(migrationsDir, '040-create-operator-memory-commit-intents.sql', 'operator memory commit intents');
+        }
+        this.assertMigration040BaseComplete();
+        if (!this.hasOperatorMemoryCommitIntentClaimInvariant()) {
+            this.applyRepairMigration(migrationsDir, '041-enforce-operator-memory-commit-claim-invariant.sql', 'operator memory commit claim invariant');
+        }
+        this.assertMigration041Complete();
     }
     applyRepairMigration(migrationsDir, fileName, label) {
         const migrationPath = path_1.default.join(migrationsDir, fileName);
@@ -425,6 +537,64 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             throw new Error(`Repair migration ${fileName} failed: ${message}`);
         }
     }
+    operatorMemoryCommitIntentTableSql() {
+        const tableDefinition = this.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name = 'operator_memory_commit_intents'").get();
+        return tableDefinition?.sql ?? '';
+    }
+    hasOperatorMemoryCommitIntentClaimInvariant() {
+        const sql = this.operatorMemoryCommitIntentTableSql();
+        return (sql.includes("(status = 'saving' AND claim_token IS NOT NULL)") &&
+            sql.includes("(status != 'saving' AND claim_token IS NULL)"));
+    }
+    assertMigration040BaseComplete() {
+        if (!this.tableExists('operator_memory_commit_intents')) {
+            throw new Error('Migration 040 recovery failed: missing table operator_memory_commit_intents');
+        }
+        const columns = this.tableColumns('operator_memory_commit_intents');
+        for (const column of [
+            'intent_id',
+            'cursor_name',
+            'idempotency_key',
+            'expected_memory_count',
+            'memory_payload_hash',
+            'memory_ids_json',
+            'source_refs_json',
+            'status',
+            'claim_token',
+            'created_at_ms',
+            'updated_at_ms',
+        ]) {
+            if (!columns.has(column)) {
+                throw new Error(`Migration 040 recovery failed: missing operator_memory_commit_intents.${column}`);
+            }
+        }
+        for (const indexName of ['idx_operator_memory_commit_intents_cursor_created']) {
+            if (!this.indexExists(indexName)) {
+                throw new Error(`Migration 040 recovery failed: missing index ${indexName}`);
+            }
+        }
+        const sql = this.operatorMemoryCommitIntentTableSql();
+        for (const fragment of [
+            'idempotency_key TEXT NOT NULL UNIQUE',
+            'expected_memory_count INTEGER NOT NULL CHECK (expected_memory_count > 0)',
+            "memory_payload_hash TEXT NOT NULL CHECK (memory_payload_hash LIKE 'sha256:%')",
+            'memory_ids_json TEXT NOT NULL CHECK (json_valid(memory_ids_json))',
+            'source_refs_json TEXT NOT NULL CHECK (json_valid(source_refs_json))',
+            "status TEXT NOT NULL CHECK (status IN ('pending', 'saving', 'saved', 'promoted'))",
+            'created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0)',
+            'updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= created_at_ms)',
+        ]) {
+            if (!sql.includes(fragment)) {
+                throw new Error(`Migration 040 recovery failed: incompatible operator_memory_commit_intents table definition missing ${fragment}`);
+            }
+        }
+    }
+    assertMigration041Complete() {
+        this.assertMigration040BaseComplete();
+        if (!this.hasOperatorMemoryCommitIntentClaimInvariant()) {
+            throw new Error('Migration 041 recovery failed: incompatible operator_memory_commit_intents table definition missing claim invariant');
+        }
+    }
     recoverMemoryProvenanceMigration032() {
         this.transaction(() => {
             const expectedDecisionColumns = [
@@ -534,6 +704,142 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             }
         }
     }
+    recoverConnectorEventOperatorSeqMigration039() {
+        this.transaction(() => {
+            const columns = this.tableColumns('connector_event_index');
+            if (!columns.has('operator_ingest_seq')) {
+                this.exec(`
+          ALTER TABLE connector_event_index
+            ADD COLUMN operator_ingest_seq INTEGER CHECK (
+              operator_ingest_seq IS NULL OR operator_ingest_seq >= 1
+            )
+        `);
+            }
+            this.exec(`
+        CREATE TABLE IF NOT EXISTS connector_event_index_operator_seq_cursors (
+          source_connector TEXT NOT NULL,
+          channel TEXT NOT NULL DEFAULT '',
+          next_seq INTEGER NOT NULL CHECK (next_seq >= 1),
+          PRIMARY KEY (source_connector, channel)
+        )
+      `);
+            this.exec(`
+        WITH ranked_events AS (
+          SELECT
+            event_index_id,
+            ROW_NUMBER() OVER (
+              PARTITION BY source_connector, COALESCE(channel, '')
+              ORDER BY rowid ASC
+            ) AS operator_seq
+          FROM connector_event_index
+        )
+        UPDATE connector_event_index
+        SET operator_ingest_seq = (
+          SELECT operator_seq
+          FROM ranked_events
+          WHERE ranked_events.event_index_id = connector_event_index.event_index_id
+        )
+        WHERE operator_ingest_seq IS NULL
+      `);
+            this.exec(`
+        INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
+          source_connector,
+          channel,
+          next_seq
+        )
+        SELECT
+          source_connector,
+          COALESCE(channel, ''),
+          COALESCE(MAX(operator_ingest_seq), 0) + 1
+        FROM connector_event_index
+        GROUP BY source_connector, COALESCE(channel, '')
+      `);
+            this.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_connector_event_index_operator_scope_seq
+          ON connector_event_index(source_connector, COALESCE(channel, ''), operator_ingest_seq)
+          WHERE operator_ingest_seq IS NOT NULL
+      `);
+            this.exec(`
+        CREATE INDEX IF NOT EXISTS idx_connector_event_index_operator_cursor_order
+          ON connector_event_index(source_connector, channel, operator_ingest_seq)
+      `);
+            this.exec(`
+        CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_operator_ingest_seq_ai
+        AFTER INSERT ON connector_event_index
+        WHEN NEW.operator_ingest_seq IS NULL
+        BEGIN
+          INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
+            source_connector,
+            channel,
+            next_seq
+          )
+          VALUES (NEW.source_connector, COALESCE(NEW.channel, ''), 1);
+
+          UPDATE connector_event_index
+          SET operator_ingest_seq = (
+            SELECT next_seq
+            FROM connector_event_index_operator_seq_cursors
+            WHERE source_connector = NEW.source_connector
+              AND channel = COALESCE(NEW.channel, '')
+          )
+          WHERE event_index_id = NEW.event_index_id;
+
+          UPDATE connector_event_index_operator_seq_cursors
+          SET next_seq = next_seq + 1
+          WHERE source_connector = NEW.source_connector
+            AND channel = COALESCE(NEW.channel, '');
+        END
+      `);
+            this.exec(`
+        CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_operator_ingest_seq_explicit_ai
+        AFTER INSERT ON connector_event_index
+        WHEN NEW.operator_ingest_seq IS NOT NULL
+        BEGIN
+          INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
+            source_connector,
+            channel,
+            next_seq
+          )
+          VALUES (NEW.source_connector, COALESCE(NEW.channel, ''), 1);
+
+          UPDATE connector_event_index_operator_seq_cursors
+          SET next_seq = CASE
+            WHEN next_seq <= NEW.operator_ingest_seq THEN NEW.operator_ingest_seq + 1
+            ELSE next_seq
+          END
+          WHERE source_connector = NEW.source_connector
+            AND channel = COALESCE(NEW.channel, '');
+        END
+      `);
+            this.assertMigration039Complete();
+            this.prepare('INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)').run(39, 'Add connector event operator ingest sequence');
+        });
+    }
+    assertMigration039Complete() {
+        const columns = this.tableColumns('connector_event_index');
+        if (!columns.has('operator_ingest_seq')) {
+            throw new Error('Migration 039 recovery failed: missing connector_event_index.operator_ingest_seq');
+        }
+        if (!this.tableExists('connector_event_index_operator_seq_cursors')) {
+            throw new Error('Migration 039 recovery failed: missing connector_event_index_operator_seq_cursors');
+        }
+        for (const indexName of [
+            'idx_connector_event_index_operator_scope_seq',
+            'idx_connector_event_index_operator_cursor_order',
+        ]) {
+            if (!this.indexExists(indexName)) {
+                throw new Error(`Migration 039 recovery failed: missing index ${indexName}`);
+            }
+        }
+        for (const triggerName of [
+            'trg_connector_event_index_operator_ingest_seq_ai',
+            'trg_connector_event_index_operator_ingest_seq_explicit_ai',
+        ]) {
+            if (!this.triggerExists(triggerName)) {
+                throw new Error(`Migration 039 recovery failed: missing trigger ${triggerName}`);
+            }
+        }
+    }
     tableColumns(tableName) {
         if (!SQLITE_IDENTIFIER_PATTERN.test(tableName)) {
             throw new Error('Invalid SQLite table identifier');
@@ -552,6 +858,17 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         const row = this.prepare("SELECT name FROM sqlite_master WHERE type='index' AND name = ?").get(indexName);
         return row?.name === indexName;
     }
+    triggerExists(triggerName) {
+        const row = this.prepare("SELECT name FROM sqlite_master WHERE type='trigger' AND name = ?").get(triggerName);
+        return row?.name === triggerName;
+    }
+    schemaVersionExists(version) {
+        if (!this.tableExists('schema_version')) {
+            return false;
+        }
+        const row = this.prepare('SELECT version FROM schema_version WHERE version = ?').get(version);
+        return row?.version === version;
+    }
     migrateFromVssMemories() {
         try {
             const vssTables = this.prepare(`SELECT name FROM sqlite_master WHERE name='vss_memories'`).all();

package/dist/db-manager.d.ts

@@ -26,9 +26,10 @@ export interface DatabaseAdapter {
     prepare: (sql: string) => PreparedStatement;
     transaction: <T>(fn: () => T) => T;
     insertEmbedding: (rowid: number, embedding: Float32Array | number[]) => void;
-    vectorSearch: (embedding: Float32Array | number[], limit: number, topicPrefix?: string) => Promise<VectorSearchResult[] | null> | VectorSearchResult[] | null;
+    vectorSearch: (embedding: Float32Array | number[], limit: number, topicPrefix?: string, excludeStatuses?: readonly string[]) => Promise<VectorSearchResult[] | null> | VectorSearchResult[] | null;
     vectorSearchEnabled: boolean;
     reloadVectorCache?: () => void;
+    refreshDecisionStatusCache?: (rowid: number) => void;
     getDbPath?: () => string;
     dbPath?: string;
     constructor: {
@@ -110,16 +111,14 @@ export interface SemanticEdges {
     synthesized_by: SemanticEdgeItem[];
 }
 /**
- * Initialize SQLite database adapter and connect
+ * Fail loud if stored vectors predate the e5 query/passage prefix scheme.
  *
- * Lazy initialization: Only connects when first accessed
- * Creates database file at ~/.claude/mama-memory.db by default
- *
- * Single-flight guard: Concurrent callers await the same promise
- * to prevent multiple adapters/migrations running simultaneously.
- *
- * @returns SQLite database connection
+ * Migration 042 records 'e5-prefixed-v1' on a fresh DB and 'legacy-unprefixed' on a DB
+ * that already held vectors at upgrade time. If the marker is not current AND legacy
+ * vectors exist, cosine search would be non-discriminative, so we throw with the exact
+ * re-embed command instead of silently serving degraded results. No-fallback by design.
  */
+export declare function assertEmbeddingSchemeCurrent(adapter: DatabaseAdapter): void;
 export declare function initDB(): Promise<unknown>;
 export declare function assertTestProcessIsNotUsingRealDb(effectivePath?: string, effectivePathSource?: string): void;
 /**
@@ -172,7 +171,7 @@ export declare function insertEmbedding(decisionRowid: number, embedding: Float3
  * @param threshold - Minimum similarity threshold (default: 0.7)
  * @returns Array of decisions with similarity scores, or empty array
  */
-export declare function vectorSearch(queryEmbedding: Float32Array | number[], limit?: number, threshold?: number, topicPrefix?: string): Promise<DecisionRecord[]>;
+export declare function vectorSearch(queryEmbedding: Float32Array | number[], limit?: number, threshold?: number, topicPrefix?: string, excludeStatuses?: readonly string[]): Promise<DecisionRecord[]>;
 /**
  * Decision input for storage
  */

package/dist/db-manager.js

@@ -22,6 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertEmbeddingSchemeCurrent = assertEmbeddingSchemeCurrent;
 exports.initDB = initDB;
 exports.assertTestProcessIsNotUsingRealDb = assertTestProcessIsNotUsingRealDb;
 exports.getDB = getDB;
@@ -48,6 +49,7 @@ const os_1 = __importDefault(require("os"));
 const debug_logger_js_1 = require("./debug-logger.js");
 const progress_indicator_js_1 = require("./progress-indicator.js");
 const index_js_1 = require("./db-adapter/index.js");
+const embeddings_js_1 = require("./embeddings.js");
 // Database adapter instance (singleton)
 let dbAdapter = null;
 let dbConnection = null;
@@ -67,6 +69,56 @@ const REAL_USER_DB_PATH = path_1.default.join(os_1.default.homedir(), '.claude',
  *
  * @returns SQLite database connection
  */
+function countRows(adapter, table) {
+    try {
+        const row = adapter.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+        return row?.n ?? 0;
+    }
+    catch {
+        return 0; // table may not exist on very old DBs
+    }
+}
+/**
+ * Fail loud if stored vectors predate the e5 query/passage prefix scheme.
+ *
+ * Migration 042 records 'e5-prefixed-v1' on a fresh DB and 'legacy-unprefixed' on a DB
+ * that already held vectors at upgrade time. If the marker is not current AND legacy
+ * vectors exist, cosine search would be non-discriminative, so we throw with the exact
+ * re-embed command instead of silently serving degraded results. No-fallback by design.
+ */
+function assertEmbeddingSchemeCurrent(adapter) {
+    let scheme = 'legacy-unprefixed';
+    try {
+        const row = adapter
+            .prepare("SELECT value FROM embedding_meta WHERE key = 'embedding_prefix_scheme'")
+            .get();
+        if (row?.value)
+            scheme = row.value;
+    }
+    catch {
+        // embedding_meta missing (pre-042). runMigrations creates it, so this path
+        // only hits if migrations did not run; fall through to the vector check.
+    }
+    if (scheme === embeddings_js_1.EMBEDDING_PREFIX_SCHEME)
+        return; // current
+    const legacyVectors = countRows(adapter, 'embeddings') + countRows(adapter, 'wiki_page_embeddings');
+    if (legacyVectors > 0) {
+        const dbPath = resolveAdapterDbPath(adapter) ?? '<db>';
+        throw new Error(`[embedding-guard] ${dbPath} holds ${legacyVectors} vectors written WITHOUT the e5 ` +
+            `query/passage prefix (scheme='${scheme}', code requires '${embeddings_js_1.EMBEDDING_PREFIX_SCHEME}'). ` +
+            `Cosine search would be non-discriminative. Re-embed before starting:\n` +
+            `  MAMA_DB_PATH="${dbPath}" node packages/mama-core/scripts/re-embed-migration.mjs`);
+    }
+    // No legacy vectors present: safe. Upgrade the marker so we do not re-check.
+    try {
+        adapter
+            .prepare("INSERT OR REPLACE INTO embedding_meta (key, value) VALUES ('embedding_prefix_scheme', ?)")
+            .run(embeddings_js_1.EMBEDDING_PREFIX_SCHEME);
+    }
+    catch {
+        // best-effort; if embedding_meta truly missing, nothing to guard yet
+    }
+}
 async function initDB() {
     assertTestProcessIsNotUsingRealDb();
     // Already initialized - return immediately
@@ -92,6 +144,7 @@ async function initDB() {
             if (typeof dbAdapter.reloadVectorCache === 'function') {
                 dbAdapter.reloadVectorCache();
             }
+            assertEmbeddingSchemeCurrent(dbAdapter); // fail loud on legacy vectors + new code
             isInitialized = true;
             (0, debug_logger_js_1.info)(`[db-manager] Database initialized (${dbAdapter.constructor.name})`);
             (0, progress_indicator_js_1.logComplete)('Database ready');
@@ -259,11 +312,11 @@ async function insertEmbedding(decisionRowid, embedding) {
  * @param threshold - Minimum similarity threshold (default: 0.7)
  * @returns Array of decisions with similarity scores, or empty array
  */
-async function vectorSearch(queryEmbedding, limit = 5, threshold = 0.7, topicPrefix) {
+async function vectorSearch(queryEmbedding, limit = 5, threshold = 0.7, topicPrefix, excludeStatuses) {
     const adapter = getAdapter();
     try {
-        // Brute-force cosine similarity over all embeddings (with optional topic pre-filter)
-        const results = await adapter.vectorSearch(queryEmbedding, limit * 3, topicPrefix);
+        // Brute-force cosine similarity over all embeddings (with optional topic/status pre-filter)
+        const results = await adapter.vectorSearch(queryEmbedding, limit * 3, topicPrefix, excludeStatuses);
         if (!results || results.length === 0) {
             return []; // No keyword fallback - fast fail
         }
@@ -327,6 +380,7 @@ async function insertDecisionWithEmbedding(decision) {
         (0, debug_logger_js_1.info)(`[db-manager] Generating embedding for decision (topic length: ${decision.topic?.length || 0})`);
         let embedding = null;
         try {
+            // e5 passage role (default) - stored vector
             embedding = await generateEnhancedEmbedding({
                 topic: decision.topic,
                 decision: decision.decision,
@@ -570,7 +624,7 @@ async function queryVectorSearch(params) {
     const { generateEmbedding } = await import('./embeddings.js');
     try {
         // Generate embedding for query
-        const embedding = await generateEmbedding(query);
+        const embedding = await generateEmbedding(query, 'query');
         const cutoffTime = Date.now() - timeWindow;
         const candidates = await adapter.vectorSearch(embedding, limit * 5);
         if (!candidates || candidates.length === 0) {
@@ -777,6 +831,7 @@ async function reindexEmbeddings(onProgress) {
     let completed = 0;
     for (const row of decisions) {
         try {
+            // e5 passage role (default) - stored vector
             const embedding = await generateEnhancedEmbedding({
                 topic: row.topic,
                 decision: row.decision,

package/dist/embedding-client.d.ts

@@ -11,6 +11,7 @@
  *
  * @module embedding-client
  */
+import type { EmbeddingRole } from './embeddings.js';
 export declare const DEFAULT_PORT: number;
 export declare const HOST = "127.0.0.1";
 export declare const TIMEOUT_MS = 500;
@@ -33,9 +34,10 @@ export declare function isServerRunning(): Promise<boolean>;
  * Generate embedding via HTTP server
  *
  * @param text - Text to embed
+ * @param role - e5 role: 'passage' (default, stored text) or 'query' (search)
  * @returns Embedding or null if failed
  */
-export declare function getEmbeddingFromServer(text: string): Promise<Float32Array | null>;
+export declare function getEmbeddingFromServer(text: string, role?: EmbeddingRole): Promise<Float32Array | null>;
 /**
  * Get server status
  */

package/dist/embedding-client.js

@@ -76,9 +76,10 @@ async function isServerRunning() {
  * Generate embedding via HTTP server
  *
  * @param text - Text to embed
+ * @param role - e5 role: 'passage' (default, stored text) or 'query' (search)
  * @returns Embedding or null if failed
  */
-async function getEmbeddingFromServer(text) {
+async function getEmbeddingFromServer(text, role = 'passage') {
     const port = getServerPort();
     try {
         const controller = new AbortController();
@@ -86,7 +87,7 @@ async function getEmbeddingFromServer(text) {
         const response = await fetch(`http://${exports.HOST}:${port}/embed`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ text }),
+            body: JSON.stringify({ text, role }),
             signal: controller.signal,
         });
         clearTimeout(timeout);

package/dist/embedding-server/index.d.ts

@@ -14,6 +14,7 @@
  */
 import type { IncomingMessage, ServerResponse, Server as HTTPServer } from 'http';
 export declare const SHUTDOWN_TOKEN: string;
+import type { EmbeddingRole } from '../embeddings.js';
 export declare const DEFAULT_PORT: number;
 export declare const HOST = "127.0.0.1";
 export declare const PORT_FILE: string;
@@ -42,6 +43,7 @@ export interface ServerOptions {
     sessionStore?: SessionStore;
     graphHandler?: RequestHandler;
 }
+export declare function resolveEmbeddingRole(raw: unknown): EmbeddingRole;
 /**
  * Clean up port file on exit
  */