@jungjaehoon/mama-core 1.5.0 → 1.7.0

package/dist/agent-situation/types.d.ts

@@ -0,0 +1,195 @@
+import type { MemoryScopeRef } from '../memory/types.js';
+import type { TwinRef } from '../edges/types.js';
+export type SituationFocus = 'decisions' | 'risks' | 'open_questions' | 'cases' | 'raw';
+export type SituationRefKind = TwinRef['kind'] | 'memory';
+export interface SituationRef {
+    kind: SituationRefKind;
+    id: string;
+}
+export interface SituationProjectRef {
+    kind: 'project';
+    id: string;
+}
+export interface AgentSituationEffectiveFilters {
+    scopes: MemoryScopeRef[];
+    connectors: string[];
+    project_refs: SituationProjectRef[];
+    tenant_id: string;
+    as_of?: string | null;
+}
+export interface AgentSituationCacheKeyInput extends AgentSituationEffectiveFilters {
+    range_start_ms: number;
+    range_end_ms: number;
+    focus: SituationFocus[];
+    limit: number;
+    ranking_policy_version: string;
+}
+export interface AgentSituationCacheKeyResult {
+    cacheKey: string;
+    canonicalInput: AgentSituationCacheKeyInput;
+    canonicalJson: string;
+    filtersHash: string;
+    scopeHash: string;
+}
+export type SituationCaveatCode = 'connector_stale' | 'some_sources_unavailable' | 'low_confidence_visible_memory' | 'graph_api_unavailable_until_m6' | 'case_visibility_incomplete' | 'no_visible_sources';
+export interface SituationSourceCoverage {
+    connector?: string;
+    channel_id?: string | null;
+    memory_scope?: MemoryScopeRef;
+    raw_count: number;
+    memory_count: number;
+    case_count: number;
+    edge_count: number;
+    last_seen: string | null;
+    stale: boolean;
+}
+export interface SituationBriefing {
+    decisions: string[];
+    facts: string[];
+    open_questions: string[];
+    risks: string[];
+}
+export interface SituationRankedItem {
+    ref: SituationRef;
+    kind: string;
+    score: number;
+    reasons: string[];
+    caveats: string[];
+}
+export interface SituationPendingHumanQuestion {
+    memory_id: string;
+    title: string;
+    summary: string;
+}
+export interface SituationEntityCluster {
+    label: string;
+    entity_refs: Array<{
+        kind: 'entity';
+        id: string;
+    }>;
+    source_refs: Array<{
+        kind: 'raw' | 'memory' | 'case';
+        id: string;
+    }>;
+    caveats: string[];
+}
+export interface SituationRecommendedTool {
+    tool: 'raw.search' | 'raw.searchAll' | 'raw.window' | 'memory.recall' | 'graph.neighborhood';
+    args: Record<string, unknown>;
+    reason: string;
+    expected_refs: SituationRef[];
+}
+export interface AgentSituationPacket {
+    packet_id: string;
+    scope: MemoryScopeRef[];
+    range_start: string;
+    range_end: string;
+    generated_at: string;
+    freshness: Record<string, unknown>;
+    source_coverage: SituationSourceCoverage[];
+    briefing: SituationBriefing;
+    ranked_items: SituationRankedItem[];
+    top_memory_refs: string[];
+    pending_human_questions: SituationPendingHumanQuestion[];
+    entity_clusters: SituationEntityCluster[];
+    recommended_next_tools: SituationRecommendedTool[];
+    ranking_policy_version: string;
+    ttl_seconds: number;
+    generated_from_slice_ids: string[];
+    caveats: string[];
+    cache: {
+        hit: boolean;
+        cache_key: string;
+        expires_at: string;
+    };
+}
+export interface AgentSituationInput {
+    scope: MemoryScopeRef[];
+    range_start_ms: number;
+    range_end_ms: number;
+    focus: SituationFocus[];
+    limit: number;
+    effective_filters: AgentSituationEffectiveFilters;
+    envelope_hash: string;
+    agent_id: string;
+    model_run_id: string;
+    ranking_policy_version?: string;
+    refresh?: boolean;
+    now_ms?: number;
+}
+export interface AgentSituationPacketRecord {
+    packet_id: string;
+    cache_key: string;
+    scope_json: string;
+    scope: MemoryScopeRef[];
+    scope_hash: string;
+    range_start_ms: number;
+    range_end_ms: number;
+    focus_json: string;
+    focus: SituationFocus[];
+    envelope_hash: string;
+    envelope_effective_filters_json: string;
+    envelope_effective_filters: AgentSituationEffectiveFilters;
+    envelope_effective_filters_hash: string;
+    ranking_policy_version: string;
+    generated_at: number;
+    expires_at: number;
+    ttl_seconds: number;
+    freshness_json: string;
+    freshness: Record<string, unknown>;
+    source_coverage_json: string;
+    source_coverage: SituationSourceCoverage[];
+    briefing_json: string;
+    briefing: SituationBriefing;
+    ranked_items_json: string;
+    ranked_items: SituationRankedItem[];
+    top_memory_refs_json: string;
+    top_memory_refs: string[];
+    pending_human_questions_json: string;
+    pending_human_questions: SituationPendingHumanQuestion[];
+    entity_clusters_json: string;
+    entity_clusters: SituationEntityCluster[];
+    recommended_next_tools_json: string;
+    recommended_next_tools: SituationRecommendedTool[];
+    generated_from_slice_ids_json: string;
+    generated_from_slice_ids: string[];
+    caveats_json: string;
+    caveats: string[];
+    agent_id: string;
+    model_run_id: string;
+    input_snapshot_ref: string;
+    source_refs_json: string;
+    source_refs: SituationRef[];
+    tenant_id: string;
+    project_id: string;
+    memory_scope_kind: MemoryScopeRef['kind'];
+    memory_scope_id: string;
+    created_at: number;
+}
+export interface AgentSituationLease {
+    cache_key: string;
+    ranking_policy_version: string;
+    lease_owner: string;
+    lease_expires_at: number;
+    created_at: number;
+}
+export interface AgentSituationCandidate {
+    ref: SituationRef;
+    kind: string;
+    title: string;
+    summary: string;
+    timestamp_ms: number;
+    confidence?: number | null;
+    status?: string | null;
+    is_open_question?: boolean;
+    has_debate_edge?: boolean;
+    connector?: string | null;
+    channel_id?: string | null;
+    scope?: MemoryScopeRef | null;
+}
+export interface SituationScore {
+    score: number;
+    reasons: string[];
+    caveats: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent-situation/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cases/search-rollup.d.ts

@@ -1,4 +1,5 @@
 import type { AdapterLike } from './wiki-page-index.js';
+import type { SearchHitDiagnostics } from '../search/search-quality.js';
 export type { AdapterLike };
 export interface SearchRollupLeafHit {
     source_type: 'decision' | 'checkpoint' | 'wiki_page' | 'connector_event';
@@ -7,6 +8,7 @@ export interface SearchRollupLeafHit {
     page_type?: 'case';
     case_id?: string | null;
     record: unknown;
+    retrieval_diagnostics?: SearchHitDiagnostics;
 }
 export interface SearchRollupResult {
     source_type: 'decision' | 'checkpoint' | 'wiki_page' | 'case' | 'standalone_connector_hit';
@@ -14,6 +16,8 @@ export interface SearchRollupResult {
     case_id: string | null;
     score: number;
     contributing_leaves?: string[];
+    contributing_leaf_diagnostics?: Record<string, SearchHitDiagnostics>;
+    retrieval_diagnostics?: SearchHitDiagnostics;
     record: unknown;
 }
 export declare function rollUpSearchHits(input: {

package/dist/cases/search-rollup.js

@@ -17,6 +17,72 @@ function stringOrNull(value) {
     }
     return String(value);
 }
+function searchHitDiagnostics(value) {
+    const object = objectRecord(value);
+    if (!object) {
+        return undefined;
+    }
+    if (typeof object.retrieval_source !== 'string' ||
+        !(object.vector_similarity === null || typeof object.vector_similarity === 'number') ||
+        typeof object.is_vector_only !== 'boolean' ||
+        typeof object.lexical_support !== 'boolean' ||
+        typeof object.entity_support !== 'boolean' ||
+        typeof object.scope_support !== 'boolean' ||
+        (object.graph_source !== 'primary' &&
+            object.graph_source !== 'expanded' &&
+            object.graph_source !== null) ||
+        !Array.isArray(object.confirmation_signals) ||
+        !Array.isArray(object.metadata_signals) ||
+        typeof object.candidate_threshold_used !== 'number') {
+        return undefined;
+    }
+    // Type assertion is safe: every required field of SearchHitDiagnostics has been
+    // validated above (including the array-typed signals consumed by diagnosticsRank).
+    return value;
+}
+function leafDiagnostics(leaf) {
+    const record = objectRecord(leaf.record);
+    return leaf.retrieval_diagnostics ?? searchHitDiagnostics(record?.retrieval_diagnostics);
+}
+function diagnosticsRank(diagnostics) {
+    let rank = 0;
+    rank += diagnostics.confirmation_signals.length * 100;
+    if (diagnostics.lexical_support) {
+        rank += 20;
+    }
+    if (diagnostics.entity_support) {
+        rank += 20;
+    }
+    if (diagnostics.graph_source === 'primary') {
+        rank += 10;
+    }
+    if (!diagnostics.is_vector_only) {
+        rank += 1;
+    }
+    return rank;
+}
+function betterDiagnostics(candidate, current) {
+    if (!current) {
+        return true;
+    }
+    return diagnosticsRank(candidate) > diagnosticsRank(current);
+}
+function diagnosticsRecord(diagnosticsByLeaf) {
+    if (diagnosticsByLeaf.size === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(Array.from(diagnosticsByLeaf.entries()).sort(([left], [right]) => left.localeCompare(right)));
+}
+function attachLeafDiagnostics(group, leaf) {
+    const diagnostics = leafDiagnostics(leaf);
+    if (!diagnostics) {
+        return;
+    }
+    group.contributing_leaf_diagnostics.set(leaf.source_id, diagnostics);
+    if (betterDiagnostics(diagnostics, group.retrieval_diagnostics)) {
+        group.retrieval_diagnostics = diagnostics;
+    }
+}
 function placeholders(values) {
     if (values.length === 0) {
         throw new Error('Cannot build SQL IN clause for an empty value list.');
@@ -104,11 +170,17 @@ function upsertOrphan(orphans, leaf) {
     if (existing && existing.score >= leaf.fused_rank_score) {
         return;
     }
+    const diagnostics = leafDiagnostics(leaf);
+    const contributingLeafDiagnostics = diagnostics ? { [leaf.source_id]: diagnostics } : undefined;
     orphans.set(key, {
         source_type: leaf.source_type === 'connector_event' ? 'standalone_connector_hit' : leaf.source_type,
         source_id: leaf.source_id,
         case_id: null,
         score: leaf.fused_rank_score,
+        ...(diagnostics ? { retrieval_diagnostics: diagnostics } : {}),
+        ...(contributingLeafDiagnostics
+            ? { contributing_leaf_diagnostics: contributingLeafDiagnostics }
+            : {}),
         record: leaf.record,
     });
 }
@@ -121,10 +193,15 @@ function upsertDirectCase(directCases, adapter, leaf, caseId) {
             score: leaf.fused_rank_score,
             max_leaf_score: leaf.fused_rank_score,
             contributing_leaves: new Set([leaf.source_id]),
+            contributing_leaf_diagnostics: new Map(),
             dedupe_keys: new Set([leaf.source_id]),
             record: withCaseId(leaf.record, survivorCaseId),
         });
     }
+    const group = directCases.get(survivorCaseId);
+    if (group) {
+        attachLeafDiagnostics(group, leaf);
+    }
     return survivorCaseId;
 }
 function upsertCaseGroup(groups, adapter, leaf, survivorCaseId) {
@@ -136,6 +213,7 @@ function upsertCaseGroup(groups, adapter, leaf, survivorCaseId) {
             score: 0,
             max_leaf_score: 0,
             contributing_leaves: new Set(),
+            contributing_leaf_diagnostics: new Map(),
             dedupe_keys: new Set(),
             record: loadCaseRecord(adapter, survivorCaseId),
         };
@@ -146,6 +224,7 @@ function upsertCaseGroup(groups, adapter, leaf, survivorCaseId) {
     }
     group.dedupe_keys.add(dedupeKey);
     group.contributing_leaves.add(leaf.source_id);
+    attachLeafDiagnostics(group, leaf);
     group.score += leaf.fused_rank_score;
     group.max_leaf_score = Math.max(group.max_leaf_score, leaf.fused_rank_score);
 }
@@ -154,12 +233,17 @@ function groupToResult(group) {
         case_id: group.case_id,
     };
     const record = { ...baseRecord, max_leaf_score: group.max_leaf_score };
+    const contributingLeafDiagnostics = diagnosticsRecord(group.contributing_leaf_diagnostics);
     return {
         source_type: 'case',
         source_id: group.case_id,
         case_id: group.case_id,
         score: group.score,
         contributing_leaves: Array.from(group.contributing_leaves).sort((left, right) => left.localeCompare(right)),
+        ...(contributingLeafDiagnostics
+            ? { contributing_leaf_diagnostics: contributingLeafDiagnostics }
+            : {}),
+        ...(group.retrieval_diagnostics ? { retrieval_diagnostics: group.retrieval_diagnostics } : {}),
         record,
     };
 }

package/dist/cases/wiki-page-index.js

@@ -153,7 +153,7 @@ function buildFtsQuery(query) {
         .match(/[\p{L}\p{N}_]+/gu)
         ?.filter((token) => token.length > 0);
     if (!tokens || tokens.length === 0) {
-        return query;
+        return '';
     }
     return tokens.map((token) => `"${token.replace(/"/g, '""')}"`).join(' OR ');
 }
@@ -264,6 +264,10 @@ function ftsSearchWikiPages(adapter, query, limit) {
     if (!searchTableExists(adapter, 'wiki_pages_fts')) {
         return [];
     }
+    const ftsQuery = buildFtsQuery(query);
+    if (!ftsQuery) {
+        return [];
+    }
     const schema = readSchema(adapter);
     const rows = adapter
         .prepare(`
@@ -273,7 +277,7 @@ function ftsSearchWikiPages(adapter, query, limit) {
         ORDER BY raw
         LIMIT ?
       `)
-        .all(buildFtsQuery(query), boundedLimit);
+        .all(ftsQuery, boundedLimit);
     const hits = [];
     for (const row of rows) {
         const record = selectByFtsPageId(adapter, schema, row.page_id);

package/dist/connectors/event-index.d.ts

@@ -23,6 +23,7 @@ interface StalenessOptions {
     stalenessWarnAfterMs?: number;
     unhealthyAfterMs?: number;
 }
+export declare function mapConnectorEventIndexRecord(row: Record<string, unknown>): ConnectorEventIndexRecord;
 export declare function connectorEventIndexId(sourceConnector: string, sourceId: string): string;
 export declare function connectorEventContentHash(input: {
     source_connector: string;

package/dist/connectors/event-index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapConnectorEventIndexRecord = mapConnectorEventIndexRecord;
 exports.connectorEventIndexId = connectorEventIndexId;
 exports.connectorEventContentHash = connectorEventContentHash;
 exports.upsertConnectorEventIndex = upsertConnectorEventIndex;
@@ -89,6 +90,11 @@ function mapConnectorEventIndexRow(row) {
             : null,
         event_date: row.event_date === null ? null : String(row.event_date),
         source_timestamp_ms: Number(row.source_timestamp_ms),
+        source_cursor: row.source_cursor === null ? null : String(row.source_cursor),
+        tenant_id: row.tenant_id === null ? null : String(row.tenant_id),
+        project_id: row.project_id === null ? null : String(row.project_id),
+        memory_scope_kind: row.memory_scope_kind === null ? null : String(row.memory_scope_kind),
+        memory_scope_id: row.memory_scope_id === null ? null : String(row.memory_scope_id),
         metadata_json: row.metadata_json === null ? null : String(row.metadata_json),
         artifact_locator: row.artifact_locator === null ? null : String(row.artifact_locator),
         artifact_title: row.artifact_title === null ? null : String(row.artifact_title),
@@ -98,6 +104,9 @@ function mapConnectorEventIndexRow(row) {
         expires_at: row.expires_at === null ? null : String(row.expires_at),
     };
 }
+function mapConnectorEventIndexRecord(row) {
+    return mapConnectorEventIndexRow(row);
+}
 function mapConnectorCursorRow(row) {
     return {
         connector_name: String(row.connector_name),
@@ -158,10 +167,11 @@ function upsertConnectorEventIndex(adapter, input) {
           INSERT INTO connector_event_index (
             event_index_id, source_connector, source_type, source_id, source_locator,
             channel, author, title, content, event_datetime, event_date, source_timestamp_ms,
-            metadata_json, artifact_locator, artifact_title, content_hash, indexed_at,
-            updated_at, expires_at
+            source_cursor, tenant_id, project_id, memory_scope_kind, memory_scope_id,
+            metadata_json, artifact_locator, artifact_title, content_hash, indexed_at, updated_at,
+            expires_at
           )
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
           ON CONFLICT(source_connector, source_id) DO UPDATE SET
             source_type = excluded.source_type,
             source_locator = excluded.source_locator,
@@ -172,6 +182,11 @@ function upsertConnectorEventIndex(adapter, input) {
             event_datetime = excluded.event_datetime,
             event_date = excluded.event_date,
             source_timestamp_ms = excluded.source_timestamp_ms,
+            source_cursor = excluded.source_cursor,
+            tenant_id = excluded.tenant_id,
+            project_id = excluded.project_id,
+            memory_scope_kind = excluded.memory_scope_kind,
+            memory_scope_id = excluded.memory_scope_id,
             metadata_json = excluded.metadata_json,
             artifact_locator = excluded.artifact_locator,
             artifact_title = excluded.artifact_title,
@@ -179,7 +194,7 @@ function upsertConnectorEventIndex(adapter, input) {
             updated_at = excluded.updated_at,
             expires_at = excluded.expires_at
         `)
-            .run(eventIndexId, input.source_connector, input.source_type, input.source_id, input.source_locator ?? null, input.channel ?? null, input.author ?? null, input.title ?? null, input.content, eventDatetime, eventDate, sourceTimestampMs, metadataJson, input.artifact_locator ?? null, input.artifact_title ?? null, contentHash, input.indexed_at ?? timestamp, timestamp, input.expires_at ?? null);
+            .run(eventIndexId, input.source_connector, input.source_type, input.source_id, input.source_locator ?? null, input.channel ?? null, input.author ?? null, input.title ?? null, input.content, eventDatetime, eventDate, sourceTimestampMs, input.source_cursor ?? null, input.tenant_id ?? null, input.project_id ?? null, input.memory_scope_kind ?? null, input.memory_scope_id ?? null, metadataJson, input.artifact_locator ?? null, input.artifact_title ?? null, contentHash, input.indexed_at ?? timestamp, timestamp, input.expires_at ?? null);
         const saved = getConnectorEventIndexRecord(adapter, input.source_connector, input.source_id);
         if (!saved) {
             throw new Error(`Failed to read connector_event_index row after upsert: ${input.source_connector}/${input.source_id}`);

package/dist/connectors/raw-query.d.ts

@@ -0,0 +1,18 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { RawSearchHit, RawSearchInput, RawSearchResult, RawSearchScopeFilter } from './types.js';
+type RawQueryAdapter = Pick<DatabaseAdapter, 'prepare'>;
+interface RawWindowInput {
+    connectors?: string[];
+    scopes?: RawSearchScopeFilter[];
+    before?: number;
+    after?: number;
+}
+export declare function searchRaw(adapter: RawQueryAdapter, input: RawSearchInput): RawSearchResult;
+export declare function searchAllRaw(adapter: RawQueryAdapter, input: RawSearchInput): RawSearchResult;
+export declare function getRawById(adapter: RawQueryAdapter, rawId: string, visibility: Pick<RawSearchInput, 'connectors' | 'scopes'>): RawSearchHit | null;
+export declare function getRawWindow(adapter: RawQueryAdapter, rawId: string, input: RawWindowInput): {
+    target: RawSearchHit;
+    items: RawSearchHit[];
+} | null;
+export type { RawSearchHit, RawSearchInput, RawSearchResult, RawSearchScopeFilter, } from './types.js';
+//# sourceMappingURL=raw-query.d.ts.map