@jungjaehoon/mama-core 1.4.2 → 1.5.0

package/dist/memory/api.js

@@ -19,6 +19,7 @@ exports.ingestConversation = ingestConversation;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const db_manager_js_1 = require("../db-manager.js");
 const embeddings_js_1 = require("../embeddings.js");
+const wiki_page_index_js_1 = require("../cases/wiki-page-index.js");
 const profile_builder_js_1 = require("./profile-builder.js");
 const bootstrap_builder_js_1 = require("./bootstrap-builder.js");
 const evolution_engine_js_1 = require("./evolution-engine.js");
@@ -30,6 +31,8 @@ const types_js_1 = require("./types.js");
 const channel_summary_store_js_1 = require("./channel-summary-store.js");
 Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: function () { return channel_summary_store_js_1.getChannelSummary; } });
 Object.defineProperty(exports, "upsertChannelSummary", { enumerable: true, get: function () { return channel_summary_store_js_1.upsertChannelSummary; } });
+const recall_bridge_js_1 = require("../entities/recall-bridge.js");
+const read_identity_js_1 = require("../entities/read-identity.js");
 function buildDecisionId(topic) {
     const safeTopic = topic.replace(/[^a-z0-9_]+/gi, '_').toLowerCase();
     return `decision_${safeTopic}_${Date.now()}_${node_crypto_1.default.randomUUID().slice(0, 8)}`;
@@ -58,8 +61,128 @@ function toMemoryRecord(row, scopes, fallbackSource) {
         created_at: row.created_at,
         updated_at: row.updated_at ?? row.created_at,
         event_date: row.event_date ?? null,
+        event_datetime: typeof row.event_datetime === 'number' && Number.isFinite(row.event_datetime)
+            ? row.event_datetime
+            : null,
     };
 }
+function loadEventDateTimeForObservations(adapter, observationIds) {
+    const uniqueIds = Array.from(new Set(observationIds.filter(Boolean)));
+    if (uniqueIds.length === 0) {
+        return null;
+    }
+    const placeholders = uniqueIds.map(() => '?').join(', ');
+    const row = adapter
+        .prepare(`
+        SELECT MAX(COALESCE(timestamp_observed, created_at)) AS event_datetime
+        FROM entity_observations
+        WHERE id IN (${placeholders})
+      `)
+        .get(...uniqueIds);
+    return typeof row?.event_datetime === 'number' && Number.isFinite(row.event_datetime)
+        ? row.event_datetime
+        : null;
+}
+function getTimelineEntityKindPriority(kind) {
+    switch (kind) {
+        case 'work_item':
+            return 0;
+        case 'project':
+            return 1;
+        case 'organization':
+            return 2;
+        case 'person':
+            return 3;
+        default:
+            return 99;
+    }
+}
+function resolveTimelineTargetEntityIdFromObservations(adapter, observationIds) {
+    const uniqueIds = Array.from(new Set(observationIds.filter(Boolean)));
+    if (uniqueIds.length === 0) {
+        return null;
+    }
+    const placeholders = uniqueIds.map(() => '?').join(', ');
+    const rows = adapter
+        .prepare(`
+        SELECT
+          n.id AS entity_id,
+          n.kind AS entity_kind,
+          COUNT(*) AS matched_observations
+        FROM entity_lineage_links l
+        JOIN entity_nodes n
+          ON n.id = l.canonical_entity_id
+        WHERE l.entity_observation_id IN (${placeholders})
+          AND l.status = 'active'
+          AND n.status = 'active'
+          AND n.merged_into IS NULL
+        GROUP BY n.id, n.kind
+      `)
+        .all(...uniqueIds);
+    rows.sort((left, right) => {
+        const kindDelta = getTimelineEntityKindPriority(left.entity_kind) -
+            getTimelineEntityKindPriority(right.entity_kind);
+        if (kindDelta !== 0) {
+            return kindDelta;
+        }
+        if (right.matched_observations !== left.matched_observations) {
+            return right.matched_observations - left.matched_observations;
+        }
+        return left.entity_id.localeCompare(right.entity_id);
+    });
+    return rows[0]?.entity_id ?? null;
+}
+function buildTimelineEventForSave(adapter, memoryId, topic, entityObservationIds, timelineEvent) {
+    if (!timelineEvent) {
+        return null;
+    }
+    const resolvedEntityId = timelineEvent.entity_id ??
+        resolveTimelineTargetEntityIdFromObservations(adapter, entityObservationIds);
+    if (!resolvedEntityId) {
+        return null;
+    }
+    return {
+        id: timelineEvent.id ?? `et_${node_crypto_1.default.randomUUID()}`,
+        entity_id: resolvedEntityId,
+        event_type: timelineEvent.event_type,
+        role: timelineEvent.role ?? null,
+        valid_from: timelineEvent.valid_from ?? null,
+        valid_to: timelineEvent.valid_to ?? null,
+        observed_at: timelineEvent.observed_at ?? null,
+        source_ref: timelineEvent.source_ref ?? `decision:${memoryId}`,
+        summary: timelineEvent.summary,
+        details: timelineEvent.details ??
+            JSON.stringify({
+                memory_id: memoryId,
+                topic,
+            }),
+    };
+}
+function insertTimelineEventForSave(adapter, event, createdAt) {
+    adapter
+        .prepare(`
+        INSERT INTO entity_timeline_events (
+          id, entity_id, event_type, role, valid_from, valid_to, observed_at,
+          source_ref, summary, details, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(event.id, event.entity_id, event.event_type, event.role, event.valid_from, event.valid_to, event.observed_at, event.source_ref, event.summary, event.details, createdAt);
+}
+function cleanupFailedMemorySave(adapter, memoryId) {
+    const row = adapter.prepare(`SELECT rowid FROM decisions WHERE id = ?`).get(memoryId);
+    if (!row) {
+        return;
+    }
+    const cleanup = () => {
+        adapter.prepare(`DELETE FROM embeddings WHERE rowid = ?`).run(row.rowid);
+        adapter.prepare(`DELETE FROM decisions WHERE id = ?`).run(memoryId);
+    };
+    const txResult = adapter.transaction(cleanup);
+    if (typeof txResult === 'function') {
+        txResult();
+    }
+}
 function batchLoadScopes(adapter, memoryIds) {
     const scopeMap = new Map();
     if (memoryIds.length === 0)
@@ -90,9 +213,9 @@ async function loadScopedMemories(scopes) {
         rows = adapter
             .prepare(`
           SELECT id, topic, decision, reasoning, confidence, created_at, updated_at, trust_context,
-                 kind, status, summary, event_date
+                 kind, status, summary, event_date, event_datetime
           FROM decisions
-          ORDER BY created_at DESC
+          ORDER BY COALESCE(event_datetime, created_at) DESC, created_at DESC
         `)
             .all();
     }
@@ -102,11 +225,11 @@ async function loadScopedMemories(scopes) {
         rows = adapter
             .prepare(`
           SELECT DISTINCT d.id, d.topic, d.decision, d.reasoning, d.confidence, d.created_at,
-                 d.updated_at, d.trust_context, d.kind, d.status, d.summary, d.event_date
+                 d.updated_at, d.trust_context, d.kind, d.status, d.summary, d.event_date, d.event_datetime
           FROM decisions d
           JOIN memory_scope_bindings msb ON msb.memory_id = d.id
           WHERE msb.scope_id IN (${placeholders})
-          ORDER BY d.created_at DESC
+          ORDER BY COALESCE(d.event_datetime, d.created_at) DESC, d.created_at DESC
         `)
             .all(...scopeIds);
     }
@@ -364,6 +487,11 @@ async function saveMemory(input) {
         })),
     });
     const supersedesTarget = evolution.edges.find((edge) => edge.type === 'supersedes')?.to_id ?? null;
+    const entityObservationIds = Array.from(new Set(input.entityObservationIds ?? []));
+    const eventDateTime = typeof input.eventDateTime === 'number'
+        ? input.eventDateTime
+        : loadEventDateTimeForObservations(adapter, entityObservationIds);
+    const timelineEvent = buildTimelineEventForSave(adapter, id, input.topic, entityObservationIds, input.timelineEvent);
     await (0, db_manager_js_1.insertDecisionWithEmbedding)({
         id,
         topic: input.topic,
@@ -375,6 +503,7 @@ async function saveMemory(input) {
         updated_at: now,
         trust_context: JSON.stringify({ source: input.source }),
         event_date: input.eventDate ?? null,
+        event_datetime: eventDateTime,
     });
     // Pre-resolve scope IDs before the synchronous transaction
     const resolvedScopeIds = [];
@@ -383,36 +512,56 @@ async function saveMemory(input) {
         resolvedScopeIds.push({ scopeId, isPrimary: index === 0 });
     }
     // Wrap all post-insert mutations in a transaction for atomicity
-    adapter.transaction(() => {
-        adapter
-            .prepare(`
-          UPDATE decisions
-          SET kind = ?, status = ?, summary = ?, is_static = ?, trust_context = ?, updated_at = ?
-          WHERE id = ?
-        `)
-            .run(input.kind, input.status ?? 'active', input.summary, input.kind === 'preference' || input.kind === 'constraint' ? 1 : 0, JSON.stringify({ source: input.source }), now, id);
-        for (const { scopeId, isPrimary } of resolvedScopeIds) {
+    try {
+        adapter.transaction(() => {
             adapter
                 .prepare(`
-            INSERT OR REPLACE INTO memory_scope_bindings (memory_id, scope_id, is_primary)
-            VALUES (?, ?, ?)
+            UPDATE decisions
+            SET kind = ?, status = ?, summary = ?, is_static = ?, trust_context = ?, updated_at = ?
+            WHERE id = ?
           `)
-                .run(id, scopeId, isPrimary ? 1 : 0);
-        }
-        for (const edge of evolution.edges) {
-            if (edge.type === 'supersedes') {
+                .run(input.kind, input.status ?? 'active', input.summary, input.kind === 'preference' || input.kind === 'constraint' ? 1 : 0, JSON.stringify({ source: input.source }), now, id);
+            for (const { scopeId, isPrimary } of resolvedScopeIds) {
                 adapter
-                    .prepare(`UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?`)
-                    .run(id, now, edge.to_id);
+                    .prepare(`
+              INSERT OR REPLACE INTO memory_scope_bindings (memory_id, scope_id, is_primary)
+              VALUES (?, ?, ?)
+            `)
+                    .run(id, scopeId, isPrimary ? 1 : 0);
             }
-            adapter
-                .prepare(`
-            INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
-            VALUES (?, ?, ?, ?, ?, ?)
-          `)
-                .run(id, edge.to_id, edge.type, edge.reason ?? null, 1.0, now);
-        }
-    });
+            for (const entityObservationId of entityObservationIds) {
+                adapter
+                    .prepare(`
+              INSERT OR IGNORE INTO decision_entity_sources (
+                decision_id, entity_observation_id, relation_type, created_at
+              ) VALUES (?, ?, ?, ?)
+            `)
+                    .run(id, entityObservationId, 'support', now);
+            }
+            if (timelineEvent) {
+                insertTimelineEventForSave(adapter, timelineEvent, now);
+            }
+            for (const edge of evolution.edges) {
+                if (edge.type === 'supersedes') {
+                    adapter
+                        .prepare(`UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?`)
+                        .run(id, now, edge.to_id);
+                }
+                adapter
+                    .prepare(`
+              INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
+              VALUES (?, ?, ?, ?, ?, ?)
+            `)
+                    .run(id, edge.to_id, edge.type, edge.reason ?? null, 1.0, now);
+            }
+        });
+    }
+    catch (error) {
+        cleanupFailedMemorySave(adapter, id);
+        const rollbackError = (error instanceof Error ? error : new Error(String(error)));
+        rollbackError.memoryId = id;
+        throw rollbackError;
+    }
     // Project to memory_truth table (best-effort; failure should not break save)
     try {
         await (0, truth_store_js_1.projectMemoryTruth)({
@@ -430,7 +579,13 @@ async function saveMemory(input) {
     catch {
         // Truth projection is best-effort; do not fail the save
     }
-    return { success: true, id };
+    return {
+        success: true,
+        id,
+        saved_decision_id: id,
+        timeline_event_id: timelineEvent?.id ?? null,
+        timeline_event_ids: timelineEvent ? [timelineEvent.id] : [],
+    };
 }
 async function buildProfile(scopes) {
     const records = await loadScopedMemories(scopes);
@@ -445,7 +600,9 @@ const EXCLUDED_STATUSES = new Set([
 async function recallMemory(query, options = {}) {
     const bundle = (0, types_js_1.createEmptyRecallBundle)(query);
     let matched = [];
+    let fusedHits = [];
     let retrievalSource = 'none';
+    const projectionMode = process.env.MAMA_ENTITY_PROJECTION_MODE ?? 'shadow';
     let _lexicalRecords = null;
     const loadLexical = async () => {
         if (_lexicalRecords === null) {
@@ -458,6 +615,7 @@ async function recallMemory(query, options = {}) {
     const isAggregation = /\b(how many|how much|total|all|every|each|count|number of)\b/.test(lowerQuery);
     const hasMultipleEntities = /\b(and|or|vs|versus|compared|between)\b/.test(lowerQuery);
     const vectorLimit = isAggregation ? 50 : 20;
+    const requestedLimit = Math.max(1, Math.floor(options.limit ?? 10));
     // Multi-query decomposition: extract sub-queries for complex questions
     const subQueries = [query];
     if (hasMultipleEntities) {
@@ -474,9 +632,13 @@ async function recallMemory(query, options = {}) {
     await (0, db_manager_js_1.initDB)();
     // Channel 1: Vector search (semantic similarity) — run all sub-queries
     const vectorMatched = [];
+    let primaryQueryEmbedding = null;
     try {
         for (const sq of subQueries) {
             const queryEmbedding = await (0, embeddings_js_1.generateEmbedding)(sq);
+            if (sq === query && primaryQueryEmbedding === null) {
+                primaryQueryEmbedding = queryEmbedding;
+            }
             const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, 0.3, options.topicPrefix);
             let filtered = vectorResults;
             if (options.scopes && options.scopes.length > 0) {
@@ -508,6 +670,8 @@ async function recallMemory(query, options = {}) {
                     source: { package: 'mama-core', source_type: 'vector_search' },
                     created_at: result.created_at ?? Date.now(),
                     updated_at: result.created_at ?? Date.now(),
+                    event_date: result.event_date ?? null,
+                    event_datetime: result.event_datetime ?? null,
                 });
             }
         } // end sub-query loop
@@ -587,7 +751,7 @@ async function recallMemory(query, options = {}) {
                 for (const ftsRow of ftsResults) {
                     const row = adapter
                         .prepare(`SELECT id, topic, decision, reasoning, confidence, created_at, updated_at,
-                    trust_context, kind, status, summary, event_date
+                    trust_context, kind, status, summary, event_date, event_datetime
              FROM decisions WHERE id = ?`)
                         .get(ftsRow.id);
                     if (!row)
@@ -688,6 +852,66 @@ async function recallMemory(query, options = {}) {
         rrfScores.set(r.id, { record: r, score: rrfScore });
     }
     const sortedRrf = Array.from(rrfScores.values()).sort((a, b) => b.score - a.score);
+    const decisionFusedHits = sortedRrf.map((entry) => ({
+        source_type: 'decision',
+        source_id: entry.record.id,
+        record: entry.record,
+        fused_rank_score: entry.score,
+    }));
+    let hasWikiHits = false;
+    const wikiScores = new Map();
+    const wikiVectorRankMap = new Map();
+    try {
+        const adapter = (0, db_manager_js_1.getAdapter)();
+        const wikiFtsHits = (0, wiki_page_index_js_1.ftsSearchWikiPages)(adapter, query, requestedLimit * 2);
+        let wikiVectorHits = [];
+        if (primaryQueryEmbedding) {
+            try {
+                wikiVectorHits = (0, wiki_page_index_js_1.vectorSearchWikiPages)(adapter, primaryQueryEmbedding, requestedLimit * 2);
+            }
+            catch (wikiVectorErr) {
+                (0, debug_logger_js_1.warn)(`[recallMemory] Wiki vector search failed: ${wikiVectorErr instanceof Error ? wikiVectorErr.message : String(wikiVectorErr)}`);
+            }
+        }
+        for (let i = 0; i < wikiVectorHits.length; i++) {
+            wikiVectorRankMap.set(wikiVectorHits[i].record.id, i);
+        }
+        for (let i = 0; i < wikiFtsHits.length; i++) {
+            const hit = wikiFtsHits[i];
+            const lexScore = 1 / (RRF_K + i + 1);
+            const vecRank = wikiVectorRankMap.get(hit.record.id);
+            const vecBoost = vecRank !== undefined ? 0.2 * (1 / (RRF_K + vecRank + 1)) : 0;
+            wikiScores.set(hit.record.id, {
+                record: hit.record,
+                score: lexScore + vecBoost,
+            });
+        }
+        for (let i = 0; i < wikiVectorHits.length; i++) {
+            const hit = wikiVectorHits[i];
+            if (wikiScores.has(hit.record.id)) {
+                continue;
+            }
+            wikiScores.set(hit.record.id, {
+                record: hit.record,
+                score: 0.15 * (1 / (RRF_K + i + 1)),
+            });
+        }
+        hasWikiHits = wikiScores.size > 0;
+    }
+    catch (wikiFtsErr) {
+        (0, debug_logger_js_1.warn)(`[recallMemory] Wiki FTS search failed: ${wikiFtsErr instanceof Error ? wikiFtsErr.message : String(wikiFtsErr)}`);
+    }
+    const wikiFusedHits = Array.from(wikiScores.values())
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => ({
+        source_type: 'wiki_page',
+        source_id: entry.record.source_locator,
+        record: entry.record,
+        fused_rank_score: entry.score,
+        ...(entry.record.page_type === 'case' ? { page_type: 'case' } : {}),
+        ...(entry.record.case_id ? { case_id: entry.record.case_id } : {}),
+    }));
+    fusedHits = [...decisionFusedHits, ...wikiFusedHits].sort((left, right) => right.fused_rank_score - left.fused_rank_score);
     // Normalize RRF scores to 0-1 range so downstream consumers (threshold filters,
     // similarity displays) get meaningful values.  The raw RRF score for K=60 tops out
     // around 0.033, which is misleading when compared against similarity thresholds.
@@ -705,6 +929,42 @@ async function recallMemory(query, options = {}) {
     else if (lexicalCandidates.length > 0) {
         retrievalSource = 'lexical_search';
     }
+    if (hasWikiHits) {
+        retrievalSource = retrievalSource === 'none' ? 'wiki_page' : `${retrievalSource}+wiki_page`;
+    }
+    let canonicalMatched = [];
+    if (projectionMode !== 'off') {
+        try {
+            canonicalMatched = await (0, recall_bridge_js_1.queryCanonicalEntities)(query, options.scopes ?? [], { limit: 10 });
+            if (projectionMode === 'dual-write' && canonicalMatched.length > 0) {
+                const seenIds = new Set(matched.map((item) => item.id));
+                for (const canonical of canonicalMatched) {
+                    if (!seenIds.has(canonical.id)) {
+                        matched.push(canonical);
+                        seenIds.add(canonical.id);
+                    }
+                }
+                retrievalSource =
+                    retrievalSource === 'none' ? 'entity_canonical' : `${retrievalSource}+entity_canonical`;
+            }
+            else if (projectionMode === 'shadow' && canonicalMatched.length > 0) {
+                retrievalSource =
+                    retrievalSource === 'none' ? 'shadow_entity_probe' : `${retrievalSource}+shadow_probe`;
+            }
+        }
+        catch (canonicalErr) {
+            (0, debug_logger_js_1.warn)(`[recallMemory] Canonical entity recall failed: ${canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr)}`);
+        }
+    }
+    if (matched.length > 0) {
+        const readIdentityIndex = await (0, read_identity_js_1.loadDecisionReadIdentityIndex)(matched.filter((record) => !record.read_identity).map((record) => record.id));
+        for (const record of matched) {
+            if (record.read_identity) {
+                continue;
+            }
+            record.read_identity = (0, read_identity_js_1.resolveReadIdentity)(record, readIdentityIndex.get(record.id) ?? []);
+        }
+    }
     // Enrich active records with summaries from their superseded predecessors.
     // When ingestConversation extracts multiple facts under the same topic, only
     // the last survives as "active" — the earlier ones become superseded and are
@@ -807,6 +1067,7 @@ async function recallMemory(query, options = {}) {
             // Graph expansion is best-effort; do not fail recall
         }
     }
+    bundle.fused_hits = fusedHits;
     bundle.search_meta.scope_order = (options.scopes ?? []).map((scope) => scope.kind);
     bundle.search_meta.retrieval_sources = [retrievalSource];
     if (options.includeProfile) {
@@ -828,6 +1089,7 @@ async function ingestMemory(input) {
         scopes: input.scopes ?? [],
         source: input.source,
         eventDate: input.eventDate,
+        eventDateTime: input.eventDateTime,
     });
 }
 async function evolveMemory(input) {

package/dist/memory/types.d.ts

@@ -1,3 +1,5 @@
+import type { ConnectorEventSearchHit } from '../connectors/types.js';
+import type { ReadIdentity } from '../entities/read-identity.js';
 export declare const MEMORY_SCOPE_KINDS: readonly ["global", "user", "channel", "project"];
 export type MemoryScopeKind = (typeof MEMORY_SCOPE_KINDS)[number];
 export declare const MEMORY_KINDS: readonly ["decision", "preference", "constraint", "lesson", "fact", "task", "schedule", "compiled"];
@@ -38,6 +40,9 @@ export interface MemoryRecord {
     updated_at: number | string;
     /** ISO 8601 date when the event actually occurred (e.g. "2023-01-15"). Null if not set. */
     event_date?: string | null;
+    /** Source event timestamp in milliseconds when known. Null if not set. */
+    event_datetime?: number | null;
+    read_identity?: ReadIdentity;
 }
 export interface MemoryEdge {
     from_id: string;
@@ -57,6 +62,8 @@ export interface ProfileSnapshot {
 export interface RecallBundle {
     profile: ProfileSnapshot;
     memories: MemoryRecord[];
+    /** Phase 3: cross-connector event hits, populated when searchWithConnectorEvents=true */
+    connector_event_hits?: ConnectorEventSearchHit[];
     graph_context: {
         primary: MemoryRecord[];
         expanded: MemoryRecord[];
@@ -68,10 +75,12 @@ export interface RecallBundle {
         retrieval_sources: string[];
     };
 }
+/** Phase 3: unified search result type — memory-authored or connector-enriched. */
+export type MemorySearchResultHit = MemoryRecord | ConnectorEventSearchHit;
 export interface MemoryEventRecord {
     event_id: string;
-    event_type: 'observed_conversation' | 'save' | 'supersede' | 'contradict' | 'mark_stale' | 'quarantine' | 'no_op' | 'audit_failed' | 'notice_sent';
-    actor: 'memory_agent' | 'main_agent' | 'user' | 'system';
+    event_type: 'observed_conversation' | 'save' | 'supersede' | 'contradict' | 'mark_stale' | 'quarantine' | 'no_op' | 'audit_failed' | 'notice_sent' | 'provenance.empty_batch' | 'provenance.link_write_failed' | 'connector_event_index.retention_swept' | 'case.link_created' | 'case.link_revoked' | 'case.membership_pinned' | 'case.membership_unpinned' | 'case.source_promoted' | 'case.freshness_drifted' | 'automation.job.started' | 'automation.job.succeeded' | 'automation.job.failed' | 'automation.job.skipped_concurrent' | 'review.bulk.approved' | 'review.bulk.rejected' | 'review.bulk.deferred' | 'canary.drift.false_merge_rate' | 'canary.drift.projection_fragmentation_rate' | 'canary.drift.replay_stale' | 'auth.role_denied' | 'ontology.proposal' | 'ontology.approval' | 'repair.approval' | 'case.fast_write_applied' | 'case.fast_write_lock_skipped' | 'case.correction_applied' | 'case.correction_reverted' | 'case.correction_superseded' | 'case.membership_tombstoned' | 'case.merged' | 'case.split' | 'case.membership_matched' | 'case.membership_candidate';
+    actor: 'memory_agent' | 'main_agent' | 'user' | 'system' | `user:${string}` | `user_uuid:${string}` | `local:${string}` | `actor:${string}` | 'token:bearer';
     source_turn_id?: string;
     memory_id?: string;
     topic?: string;

package/dist/search/feedback-store.d.ts

@@ -0,0 +1,59 @@
+import type { RunResult } from '../db-adapter/statement.js';
+import { type QuestionType } from './question-type.js';
+export type SearchFeedbackKind = 'shown' | 'accept' | 'reject' | 'hide' | 'click';
+export type SearchFeedbackSourceType = 'decision' | 'checkpoint' | 'wiki_page' | 'case' | 'connector_event';
+export interface SearchFeedbackInput {
+    result_id: string;
+    session_id?: string | null;
+    query: string;
+    result_source_type: SearchFeedbackSourceType;
+    result_source_id: string;
+    feedback_kind: SearchFeedbackKind;
+    question_type?: QuestionType | null;
+    shown_index: number;
+    result_case_id?: string | null;
+    clicked_result_rank?: number | null;
+    created_at?: string;
+}
+export interface ListSearchFeedbackOptions {
+    since?: string;
+    until?: string;
+    limit?: number;
+}
+export interface SearchFeedbackRow {
+    feedback_id: string;
+    query: string;
+    query_hash_hex: string;
+    question_type: QuestionType;
+    result_source_type: SearchFeedbackSourceType;
+    result_source_id: string;
+    case_id: string | null;
+    feedback_kind: SearchFeedbackKind;
+    rank_position: number;
+    score_before: number | null;
+    score_after: number | null;
+    session_id: string | null;
+    actor: string;
+    metadata_json: string | null;
+    created_at: string;
+    updated_at: string | null;
+}
+export interface RecordSearchFeedbackResult {
+    feedback_id: string;
+    query_hash: string;
+    deduped: boolean;
+}
+export interface FeedbackStoreAdapter {
+    prepare(sql: string): {
+        run(...params: unknown[]): RunResult;
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+    transaction?<T>(fn: () => T): T | (() => T);
+}
+export declare function hashQuery(query: string): string;
+export declare function getFeedbackRetentionDays(adapter: FeedbackStoreAdapter): number;
+export declare function compactShownSearchFeedback(adapter: FeedbackStoreAdapter, retentionDays?: number): number;
+export declare function recordSearchFeedback(adapter: FeedbackStoreAdapter, input: SearchFeedbackInput): RecordSearchFeedbackResult;
+export declare function listSearchFeedback(adapter: FeedbackStoreAdapter, options?: ListSearchFeedbackOptions): SearchFeedbackRow[];
+//# sourceMappingURL=feedback-store.d.ts.map