@jungjaehoon/mama-core 1.7.0 → 1.9.0

package/dist/memory/api.js

@@ -4,10 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getChannelSummary = exports.upsertChannelSummary = exports.LEXICAL_STOPWORDS = void 0;
+exports.buildDecisionId = buildDecisionId;
 exports.getLexicalQueryTokens = getLexicalQueryTokens;
 exports.loadEdgesForIds = loadEdgesForIds;
 exports.saveMemory = saveMemory;
 exports.saveMemoryWithTrustedProvenance = saveMemoryWithTrustedProvenance;
+exports.promoteMemoryStatus = promoteMemoryStatus;
 exports.buildProfile = buildProfile;
 exports.recallMemory = recallMemory;
 exports.ingestMemory = ingestMemory;
@@ -40,8 +42,18 @@ const search_quality_js_1 = require("../search/search-quality.js");
 const event_store_js_1 = require("./event-store.js");
 const provenance_js_1 = require("./provenance.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)}`;
+    // Non-ASCII topics (Korean etc.) used to collapse into bare underscore runs
+    // ("decision_______<ts>") - unreadable and near-colliding. Collapse the runs
+    // and fall back to a stable topic hash when nothing ASCII survives; the
+    // human-readable topic itself is stored verbatim in the topic column.
+    const safeTopic = topic
+        .replace(/[^a-z0-9_]+/gi, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+    // sha256 (not sha1) purely to keep SAST scanners quiet - this is an id slug, not crypto.
+    const slug = safeTopic || `t${node_crypto_1.default.createHash('sha256').update(topic).digest('hex').slice(0, 8)}`;
+    return `decision_${slug}_${Date.now()}_${node_crypto_1.default.randomUUID().slice(0, 8)}`;
 }
 function buildSaveEventReason(toolName, gatewayCallId) {
     const parts = ['saved'];
@@ -442,11 +454,16 @@ async function saveMemoryInternal(input, options) {
     const id = buildDecisionId(input.topic);
     const now = Date.now();
     const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)(options);
+    const targetStatus = input.status ?? 'active';
+    const shouldApplyEvolution = targetStatus === 'active';
     // Find evolution candidates: exact topic match first, then semantic search fallback
     const primaryScope = input.scopes.length > 0 ? input.scopes[0] : null;
     const excludeIds = new Set(input.excludeIds ?? []);
     let existingCandidates;
-    if (primaryScope) {
+    if (!shouldApplyEvolution) {
+        existingCandidates = [];
+    }
+    else if (primaryScope) {
         const scopeId = await (0, db_manager_js_1.ensureMemoryScope)(primaryScope.kind, primaryScope.id);
         existingCandidates = adapter
             .prepare(`
@@ -475,11 +492,14 @@ async function saveMemoryInternal(input, options) {
             .all(input.topic).filter((c) => !excludeIds.has(c.id));
     }
     // Semantic fallback: if no exact topic match, find similar memories via vector search
-    if (existingCandidates.length === 0) {
+    if (shouldApplyEvolution && existingCandidates.length === 0) {
         try {
             const queryText = `${input.topic} ${input.summary}`;
-            const embedding = await (0, embeddings_js_1.generateEmbedding)(queryText);
-            const semanticResults = await (0, db_manager_js_1.vectorSearch)(embedding, 3, 0.82);
+            const embedding = await (0, embeddings_js_1.generateEmbedding)(queryText, 'query');
+            // Exclude superseded history so a dense supersede chain cannot fill all 3
+            // candidate slots and hide the prior ACTIVE decision (which would break the
+            // evolution link and create an active duplicate).
+            const semanticResults = await (0, db_manager_js_1.vectorSearch)(embedding, 3, 0.82, undefined, Array.from(EXCLUDED_STATUSES));
             // Scope-filter semantic candidates when a primary scope is available
             let scopeFiltered = semanticResults;
             if (primaryScope) {
@@ -509,13 +529,15 @@ async function saveMemoryInternal(input, options) {
             // Semantic search unavailable — proceed with empty candidates
         }
     }
-    const evolution = (0, evolution_engine_js_1.resolveMemoryEvolution)({
-        incoming: { topic: input.topic, summary: input.summary, kind: input.kind },
-        existing: existingCandidates.map((c) => ({
-            ...c,
-            kind: (c.kind || 'fact'),
-        })),
-    });
+    const evolution = shouldApplyEvolution
+        ? (0, evolution_engine_js_1.resolveMemoryEvolution)({
+            incoming: { topic: input.topic, summary: input.summary, kind: input.kind },
+            existing: existingCandidates.map((c) => ({
+                ...c,
+                kind: (c.kind || 'fact'),
+            })),
+        })
+        : { edges: [] };
     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'
@@ -556,7 +578,7 @@ async function saveMemoryInternal(input, options) {
             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);
+                .run(input.kind, targetStatus, 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(`
@@ -609,22 +631,41 @@ async function saveMemoryInternal(input, options) {
         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)({
-            memory_id: id,
-            topic: input.topic,
-            truth_status: (input.status ?? 'active'),
-            effective_summary: input.summary,
-            effective_details: input.details,
-            trust_score: input.confidence ?? 0.5,
-            scope_refs: input.scopes,
-            supporting_event_ids: [],
-            superseded_by: undefined,
-        });
+    // Sync the adapter's status cache for every row whose status changed in the
+    // post-insert transaction: the saved row itself (status is written AFTER
+    // insertEmbedding populated the cache) and any rows just superseded. This makes
+    // the vectorSearch pre-filter correct within this session, not only after reload.
+    if (adapter.refreshDecisionStatusCache) {
+        const changedIds = [
+            id,
+            ...evolution.edges.filter((e) => e.type === 'supersedes').map((e) => e.to_id),
+        ];
+        const ridStmt = adapter.prepare('SELECT rowid FROM decisions WHERE id = ?');
+        for (const changedId of changedIds) {
+            const ridRow = ridStmt.get(changedId);
+            if (ridRow) {
+                adapter.refreshDecisionStatusCache(ridRow.rowid);
+            }
+        }
     }
-    catch {
-        // Truth projection is best-effort; do not fail the save
+    if (options?.projectTruth !== false) {
+        // Project to memory_truth table (best-effort; failure should not break save)
+        try {
+            await (0, truth_store_js_1.projectMemoryTruth)({
+                memory_id: id,
+                topic: input.topic,
+                truth_status: targetStatus,
+                effective_summary: input.summary,
+                effective_details: input.details,
+                trust_score: input.confidence ?? 0.5,
+                scope_refs: input.scopes,
+                supporting_event_ids: [],
+                superseded_by: undefined,
+            });
+        }
+        catch {
+            // Truth projection is best-effort; do not fail the save
+        }
     }
     return {
         success: true,
@@ -640,6 +681,156 @@ async function saveMemory(input) {
 async function saveMemoryWithTrustedProvenance(input, options) {
     return saveMemoryInternal((0, provenance_js_1.sanitizePublicSaveMemoryInput)(input), options);
 }
+async function promoteMemoryStatus(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const memoryId = input.memoryId;
+    const now = input.nowMs ?? Date.now();
+    const targetStatus = input.status;
+    const row = adapter
+        .prepare(`
+        SELECT id, topic, decision, reasoning, confidence, kind, summary, supersedes
+        FROM decisions
+        WHERE id = ?
+      `)
+        .get(memoryId);
+    if (!row) {
+        throw new Error(`Cannot promote missing memory ${memoryId}`);
+    }
+    const topic = String(row.topic);
+    const summary = String(row.summary ?? row.decision ?? '');
+    const details = String(row.reasoning ?? row.decision ?? '');
+    const kind = (row.kind ?? 'fact') || 'fact';
+    const scopes = batchLoadScopes(adapter, [memoryId]).get(memoryId) ?? [];
+    let evolution = { edges: [] };
+    if (targetStatus === 'active') {
+        const primaryScope = scopes[0] ?? null;
+        let existingCandidates;
+        if (primaryScope) {
+            const scopeId = await (0, db_manager_js_1.ensureMemoryScope)(primaryScope.kind, primaryScope.id);
+            existingCandidates = adapter
+                .prepare(`
+            SELECT d.id, d.topic, d.summary, d.kind
+            FROM decisions d
+            JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+            WHERE d.topic = ? AND msb.scope_id = ? AND d.id <> ?
+              AND (d.status = 'active' OR d.status IS NULL)
+              AND d.superseded_by IS NULL
+            ORDER BY d.created_at DESC
+            LIMIT 5
+          `)
+                .all(topic, scopeId, memoryId);
+        }
+        else {
+            existingCandidates = adapter
+                .prepare(`
+            SELECT id, topic, summary, kind
+            FROM decisions
+            WHERE topic = ? AND id <> ?
+              AND (status = 'active' OR status IS NULL)
+              AND superseded_by IS NULL
+            ORDER BY created_at DESC
+            LIMIT 5
+          `)
+                .all(topic, memoryId);
+        }
+        if (existingCandidates.length === 0) {
+            try {
+                const queryText = `${topic} ${summary}`;
+                const embedding = await (0, embeddings_js_1.generateEmbedding)(queryText, 'query');
+                // Same exclusion as saveMemoryInternal's fallback: superseded history must
+                // not crowd out the prior ACTIVE decision from the 3 candidate slots.
+                const semanticResults = await (0, db_manager_js_1.vectorSearch)(embedding, 3, 0.82, undefined, Array.from(EXCLUDED_STATUSES));
+                let scopeFiltered = semanticResults;
+                if (primaryScope) {
+                    const semIds = semanticResults.map((result) => String(result.id));
+                    const semScopeMap = batchLoadScopes(adapter, semIds);
+                    const scopeKey = `${primaryScope.kind}:${primaryScope.id}`;
+                    scopeFiltered = semanticResults.filter((result) => {
+                        const resultScopes = semScopeMap.get(String(result.id)) ?? [];
+                        return (resultScopes.length === 0 ||
+                            resultScopes.some((scope) => `${scope.kind}:${scope.id}` === scopeKey));
+                    });
+                }
+                existingCandidates = scopeFiltered
+                    .filter((result) => String(result.id) !== memoryId)
+                    .filter((result) => {
+                    const status = String(result.status || '');
+                    return !status || status === 'active' || status === '';
+                })
+                    .map((result) => ({
+                    id: String(result.id),
+                    topic: String(result.topic || ''),
+                    summary: String(result.decision || ''),
+                    kind: 'fact',
+                    _semanticMatch: true,
+                }));
+            }
+            catch {
+                // Semantic search unavailable — proceed with exact-match candidates only.
+            }
+        }
+        evolution = (0, evolution_engine_js_1.resolveMemoryEvolution)({
+            incoming: { topic, summary, kind },
+            existing: existingCandidates.map((candidate) => ({
+                ...candidate,
+                kind: (candidate.kind || 'fact'),
+            })),
+        });
+    }
+    const existingSupersedesTarget = typeof row.supersedes === 'string' && row.supersedes.length > 0 ? row.supersedes : null;
+    const supersedesTarget = evolution.edges.find((edge) => edge.type === 'supersedes')?.to_id ??
+        (targetStatus === 'active' ? existingSupersedesTarget : null);
+    adapter.transaction(() => {
+        const updated = adapter
+            .prepare('UPDATE decisions SET status = ?, supersedes = ?, updated_at = ? WHERE id = ?')
+            .run(targetStatus, supersedesTarget, now, memoryId);
+        if (updated.changes !== 1) {
+            throw new Error(`Cannot promote missing memory ${memoryId}`);
+        }
+        adapter
+            .prepare(`
+          INSERT OR REPLACE INTO memory_truth (
+            memory_id, topic, truth_status, effective_summary, effective_details, trust_score,
+            scope_refs, supporting_event_ids, superseded_by, contradicted_by, created_at, updated_at
+          )
+          VALUES (?, ?, ?, ?, ?, ?, ?, COALESCE((SELECT supporting_event_ids FROM memory_truth WHERE memory_id = ?), '[]'), NULL, NULL, COALESCE((SELECT created_at FROM memory_truth WHERE memory_id = ?), ?), ?)
+        `)
+            .run(memoryId, topic, targetStatus, summary, details, row.confidence ?? 0.5, JSON.stringify(scopes), memoryId, memoryId, now, 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(memoryId, now, edge.to_id);
+                adapter
+                    .prepare(`UPDATE memory_truth SET truth_status = 'superseded', superseded_by = ?, updated_at = ? WHERE memory_id = ?`)
+                    .run(memoryId, now, edge.to_id);
+            }
+            adapter
+                .prepare(`
+            INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+          `)
+                .run(memoryId, edge.to_id, edge.type, edge.reason ?? null, 1.0, now);
+        }
+    });
+    // Sync the adapter's status cache for every row whose status changed above.
+    // Without this, a row promoted OUT of an excluded status (e.g. stale->active)
+    // stays invisible to the vectorSearch pre-filter until the next full reload.
+    if (adapter.refreshDecisionStatusCache) {
+        const changedIds = [
+            memoryId,
+            ...evolution.edges.filter((e) => e.type === 'supersedes').map((e) => e.to_id),
+        ];
+        const ridStmt = adapter.prepare('SELECT rowid FROM decisions WHERE id = ?');
+        for (const id of changedIds) {
+            const ridRow = ridStmt.get(id);
+            if (ridRow) {
+                adapter.refreshDecisionStatusCache(ridRow.rowid);
+            }
+        }
+    }
+}
 async function buildProfile(scopes) {
     const records = await loadScopedMemories(scopes);
     return (0, profile_builder_js_1.classifyProfileEntries)(records);
@@ -704,11 +895,14 @@ async function recallMemory(query, options = {}) {
     let primaryQueryEmbedding = null;
     try {
         for (const sq of subQueries) {
-            const queryEmbedding = await (0, embeddings_js_1.generateEmbedding)(sq);
+            const queryEmbedding = await (0, embeddings_js_1.generateEmbedding)(sq, 'query');
             if (sq === query && primaryQueryEmbedding === null) {
                 primaryQueryEmbedding = queryEmbedding;
             }
-            const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, searchOptions.threshold, searchOptions.topicPrefix);
+            const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, searchOptions.threshold, searchOptions.topicPrefix, 
+            // Keep superseded history out of the candidate top-K at search time; the
+            // post-filter below stays the authority (and includeHistory restores it).
+            options.includeHistory ? undefined : Array.from(EXCLUDED_STATUSES));
             let filtered = vectorResults;
             let vectorScopeMap = new Map();
             if (options.scopes && options.scopes.length > 0) {
@@ -1318,6 +1512,17 @@ async function recallMemory(query, options = {}) {
         ];
     });
     fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || acceptedPrimaryIds.has(hit.source_id));
+    // Honor options.limit on the final memories (matched is RRF-rank-sorted, canonical
+    // dual-write appends last). Without this cap the full fusion set (hundreds of records)
+    // flowed into bundle.memories AND the per-record enrichment SQL loops below.
+    if (matched.length > requestedLimit) {
+        matched = matched.slice(0, requestedLimit);
+        // Keep bundle.fused_hits consistent with the capped memories: drop decision hits
+        // whose record no longer appears in `matched` (wiki hits are added below and are
+        // not keyed to memories).
+        const cappedIds = new Set(matched.map((record) => record.id));
+        fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || cappedIds.has(hit.source_id));
+    }
     const acceptedWikiFusedHits = Array.from(wikiScores.values())
         .sort((a, b) => b.score - a.score)
         .flatMap((entry) => {

package/dist/memory/provenance.d.ts

@@ -5,6 +5,7 @@ export interface TrustedProvenanceCapability {
 export interface TrustedMemoryWriteOptions {
     provenance: MemoryWriteProvenance;
     capability: TrustedProvenanceCapability;
+    projectTruth?: boolean;
 }
 export interface NormalizedMemoryProvenance {
     actor: MemoryEventRecord['actor'];

package/dist/memory/provenance.js

@@ -92,6 +92,7 @@ function appendProvenanceSourceRefs(options, refs) {
     assertTrustedProvenanceCapability(options.capability);
     return {
         capability: options.capability,
+        projectTruth: options.projectTruth,
         provenance: {
             ...options.provenance,
             source_refs: [...(options.provenance.source_refs ?? []), ...refs],

package/dist/memory-inject.js

@@ -77,7 +77,7 @@ async function injectDecisionContext(userMessage) {
 async function performMemoryInjection(userMessage, startTime) {
     // 1. Generate query embedding
     const { generateEmbedding } = await import('./embeddings.js');
-    const queryEmbedding = await generateEmbedding(userMessage);
+    const queryEmbedding = await generateEmbedding(userMessage, 'query');
     const embeddingLatency = Date.now() - startTime;
     (0, debug_logger_js_1.info)(`[MAMA] Embedding generation: ${embeddingLatency}ms`);
     // 2. Adaptive threshold (shorter queries need higher confidence)

package/dist/provenance/source-ref.d.ts

@@ -0,0 +1,29 @@
+import { type ContextRef } from '../context-compile/types.js';
+export declare const STRICT_SOURCE_REF_KINDS: readonly ["memory", "raw", "entity", "case", "decision", "os_task", "agent_situation_packet", "report_slot", "context_packet", "model_run", "tool_trace", "wiki_page", "report"];
+export type StrictSourceRefKind = (typeof STRICT_SOURCE_REF_KINDS)[number];
+export declare const LEGACY_SOURCE_REF_KINDS: readonly ["message", "conversation", "raw_memory"];
+export type LegacySourceRefKind = (typeof LEGACY_SOURCE_REF_KINDS)[number];
+export type SourceRef = {
+    kind: Exclude<StrictSourceRefKind, 'raw'>;
+    id: string;
+} | {
+    kind: 'raw';
+    id: string;
+    connector: string;
+    source_id?: string;
+    channel_id?: string | null;
+} | {
+    kind: 'legacy';
+    legacy_kind: LegacySourceRefKind;
+    id: string;
+};
+export declare function fromContextRef(ref: ContextRef): SourceRef;
+export declare function toContextRef(ref: SourceRef): ContextRef | null;
+export declare function fromVerifyArtifact(artifact: {
+    type: string;
+    id: string;
+}): SourceRef;
+export declare function parseSourceRefString(value: string): SourceRef;
+export declare function serializeSourceRef(ref: SourceRef): string;
+export declare function assertNonEmptySourceRefs(refs: readonly SourceRef[]): void;
+//# sourceMappingURL=source-ref.d.ts.map

package/dist/provenance/source-ref.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_SOURCE_REF_KINDS = exports.STRICT_SOURCE_REF_KINDS = void 0;
+exports.fromContextRef = fromContextRef;
+exports.toContextRef = toContextRef;
+exports.fromVerifyArtifact = fromVerifyArtifact;
+exports.parseSourceRefString = parseSourceRefString;
+exports.serializeSourceRef = serializeSourceRef;
+exports.assertNonEmptySourceRefs = assertNonEmptySourceRefs;
+const types_js_1 = require("../context-compile/types.js");
+exports.STRICT_SOURCE_REF_KINDS = [
+    'memory',
+    'raw',
+    'entity',
+    'case',
+    'decision',
+    'os_task',
+    'agent_situation_packet',
+    'report_slot',
+    'context_packet',
+    'model_run',
+    'tool_trace',
+    'wiki_page',
+    'report',
+];
+exports.LEGACY_SOURCE_REF_KINDS = ['message', 'conversation', 'raw_memory'];
+const STRICT_SOURCE_REF_KIND_SET = new Set(exports.STRICT_SOURCE_REF_KINDS);
+const CONTEXT_REF_KIND_SET = new Set(types_js_1.CONTEXT_REF_KINDS);
+const LEGACY_SOURCE_REF_KIND_SET = new Set(exports.LEGACY_SOURCE_REF_KINDS);
+const VERIFY_ARTIFACT_KIND_SET = new Set([
+    'decision',
+    'os_task',
+    'agent_situation_packet',
+    'report_slot',
+    'context_packet',
+    'model_run',
+    'tool_trace',
+]);
+function requiredString(value, field) {
+    if (typeof value !== 'string') {
+        throw new Error(`Source ref ${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`Source ref ${field} must not be empty`);
+    }
+    return trimmed;
+}
+function optionalString(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return requiredString(value, field);
+}
+function optionalNullableString(value, field) {
+    if (value === null) {
+        return null;
+    }
+    return optionalString(value, field);
+}
+function assertStrictSourceRefKind(kind) {
+    if (!STRICT_SOURCE_REF_KIND_SET.has(kind)) {
+        throw new Error(`Unsupported source ref kind: ${kind}`);
+    }
+}
+function assertLegacySourceRefKind(kind) {
+    if (!LEGACY_SOURCE_REF_KIND_SET.has(kind)) {
+        throw new Error(`Unsupported legacy source ref kind: ${kind}`);
+    }
+}
+function assertContextSourceRefKind(kind) {
+    if (kind === 'raw' || !CONTEXT_REF_KIND_SET.has(kind)) {
+        throw new Error(`Unsupported context source ref kind: ${kind}`);
+    }
+}
+function fromContextRef(ref) {
+    if (ref === null || ref === undefined) {
+        throw new Error('Context ref must not be null or undefined');
+    }
+    const input = ref;
+    const kind = requiredString(input.kind, 'kind');
+    if (kind === 'raw') {
+        const normalized = {
+            kind: 'raw',
+            id: requiredString(input.raw_id, 'raw_id'),
+            connector: requiredString(input.connector, 'connector'),
+        };
+        const sourceId = optionalString(input.source_id, 'source_id');
+        const channelId = optionalNullableString(input.channel_id, 'channel_id');
+        if (sourceId !== undefined) {
+            normalized.source_id = sourceId;
+        }
+        if (channelId !== undefined) {
+            normalized.channel_id = channelId;
+        }
+        return normalized;
+    }
+    assertContextSourceRefKind(kind);
+    return {
+        kind,
+        id: requiredString(input.id, 'id'),
+    };
+}
+function toContextRef(ref) {
+    if (ref === null || ref === undefined) {
+        return null;
+    }
+    switch (ref.kind) {
+        case 'memory':
+        case 'entity':
+        case 'case':
+            return {
+                kind: ref.kind,
+                id: requiredString(ref.id, 'id'),
+            };
+        case 'raw': {
+            const normalized = {
+                kind: 'raw',
+                raw_id: requiredString(ref.id, 'id'),
+                connector: requiredString(ref.connector, 'connector'),
+            };
+            const sourceId = optionalString(ref.source_id, 'source_id');
+            const channelId = optionalNullableString(ref.channel_id, 'channel_id');
+            if (sourceId !== undefined) {
+                normalized.source_id = sourceId;
+            }
+            if (channelId !== undefined) {
+                normalized.channel_id = channelId;
+            }
+            return normalized;
+        }
+        default:
+            return null;
+    }
+}
+function fromVerifyArtifact(artifact) {
+    if (artifact === null || artifact === undefined) {
+        throw new Error('Artifact must not be null or undefined');
+    }
+    const kind = requiredString(artifact.type, 'type');
+    if (!VERIFY_ARTIFACT_KIND_SET.has(kind)) {
+        throw new Error(`Unsupported verify artifact source ref kind: ${kind}`);
+    }
+    assertStrictSourceRefKind(kind);
+    if (kind === 'raw') {
+        throw new Error('Verify artifact source refs cannot use raw kind');
+    }
+    return {
+        kind,
+        id: requiredString(artifact.id, 'id'),
+    };
+}
+function parseSourceRefString(value) {
+    const rawValue = requiredString(value, 'value');
+    const parts = rawValue.split(':');
+    const kind = requiredString(parts[0], 'kind');
+    if (kind === 'raw') {
+        const connector = requiredString(parts[1], 'connector');
+        const id = requiredString(parts.slice(2).join(':'), 'id');
+        return { kind: 'raw', connector, id };
+    }
+    if (LEGACY_SOURCE_REF_KIND_SET.has(kind)) {
+        assertLegacySourceRefKind(kind);
+        return {
+            kind: 'legacy',
+            legacy_kind: kind,
+            id: requiredString(parts.slice(1).join(':'), 'id'),
+        };
+    }
+    assertStrictSourceRefKind(kind);
+    if (kind === 'raw') {
+        throw new Error('Raw source refs must include connector and id');
+    }
+    const sourceKind = kind;
+    return {
+        kind: sourceKind,
+        id: requiredString(parts.slice(1).join(':'), 'id'),
+    };
+}
+function serializeSourceRef(ref) {
+    if (ref === null || ref === undefined) {
+        throw new Error('Source ref must not be null or undefined');
+    }
+    switch (ref.kind) {
+        case 'raw':
+            return `raw:${requiredString(ref.connector, 'connector')}:${requiredString(ref.id, 'id')}`;
+        case 'legacy':
+            assertLegacySourceRefKind(ref.legacy_kind);
+            return `${ref.legacy_kind}:${requiredString(ref.id, 'id')}`;
+        default: {
+            assertStrictSourceRefKind(ref.kind);
+            return `${ref.kind}:${requiredString(ref.id, 'id')}`;
+        }
+    }
+}
+function assertNonEmptySourceRefs(refs) {
+    if (!Array.isArray(refs) || refs.length === 0) {
+        throw new Error('Source refs must not be empty');
+    }
+    for (const ref of refs) {
+        serializeSourceRef(ref);
+    }
+}
+//# sourceMappingURL=source-ref.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,6 +50,7 @@
     "./agent-situation": "./dist/agent-situation/index.js",
     "./agent-graph": "./dist/agent-graph/index.js",
     "./context-compile": "./dist/context-compile/index.js",
+    "./provenance/source-ref": "./dist/provenance/source-ref.js",
     "./edges/types": "./dist/edges/types.js",
     "./edges/store": "./dist/edges/store.js",
     "./edges/ref-validation": "./dist/edges/ref-validation.js"