@devflow-tools/memory-engine 0.17.7 → 0.18.0

package/dist/memory-gate.js

@@ -1,3 +1,4 @@
+import { getDevFlowStateRoot, resolveStableProjectIdentity, stableRuntimeHash } from '@devflow-tools/sdk';
 import { SignalBuffer } from './signal-buffer.js';
 import { validateProjectRoot, hasForceInitSentinel, writeForceInitSentinel } from './project-validator.js';
 import { MemoryEngine } from './memory-engine.js';
@@ -7,13 +8,14 @@ import { groupEventsBySession, triageGroupsWithDisposition } from './event-group
 import { SUMMARY_SYSTEM, buildSummaryPrompt } from './session-summarizer.js';
 import { LeaseStore } from './lease-store.js';
 import { appendFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { isObservationType, observationDedupKey, } from './observation-types.js';
+import { isObservationType, } from './observation-types.js';
 import { evaluateObservationQuality } from './observation-quality.js';
 import { mergeSemanticEntities, normalizeEntityKey, normalizeSemanticMemory, } from './semantic-memory.js';
 import { validateEvidenceSpans, validateMemoryCapsules } from './memory-capsule.js';
 import { emitSemanticControlLog } from '@devflow-tools/telemetry';
+import { createMemoryEpisodeV1, createMemoryFactProposalV1 } from './memory-fact-provider-port.js';
+import { enrichExplicitMemory } from './explicit-memory-enricher.js';
 const BATCH_CONCEPT_STOP_WORDS = new Set([
     'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
     'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should',
@@ -56,7 +58,7 @@ function validateObservationBatch(observations) {
 }
 function logInvalidObservationBatch(projectRoot, batchId) {
     try {
-        const errorDir = join(homedir(), '.devflow', 'errors');
+        const errorDir = join(getDevFlowStateRoot(), 'errors');
         mkdirSync(errorDir, { recursive: true });
         appendFileSync(join(errorDir, 'memory-errors.log'), `${new Date().toISOString()} invalid_observation_batch project=${JSON.stringify(projectRoot)} batch=${JSON.stringify(batchId)}\n`, { mode: 0o600 });
     }
@@ -106,6 +108,7 @@ export class MemoryGate {
     projectValid;
     initPromise = null;
     projectRoot;
+    projectIdentity;
     embedder;
     needsColdFlush = true;
     analyzer = new SignalAnalyzer();
@@ -116,6 +119,7 @@ export class MemoryGate {
     ruleExtractionQueue = Promise.resolve();
     constructor(projectRoot, embedder) {
         this.projectRoot = projectRoot;
+        this.projectIdentity = resolveStableProjectIdentity(projectRoot);
         this.projectValid = hasForceInitSentinel(projectRoot);
         this.embedder = embedder ?? new EmbeddingProvider();
     }
@@ -124,8 +128,8 @@ export class MemoryGate {
         if (!this.engine)
             await this.forceWarmUp();
         const engine = this.requireEngine();
-        // Reserve the canonical event before running any signal analysis. API delivery
-        // and the local fallback can therefore race without duplicating signals.
+        // Reserve the canonical event before running any signal analysis so duplicate
+        // delivery cannot create duplicate signals.
         const inserted = engine.store.recordEvent({
             ...event,
             project: this.projectRoot,
@@ -154,7 +158,7 @@ export class MemoryGate {
         this.recentEvents.push(toolEvent);
         if (this.recentEvents.length > 20)
             this.recentEvents.shift();
-        // Aggregate signal strength as legacy score for buffer
+        // Aggregate signal strength for the event buffer.
         const maxStrength = signals.reduce((max, s) => Math.max(max, s.strength), 0);
         const aggregateScore = Math.min(1, signals.reduce((sum, s) => sum + s.strength * 0.3, maxStrength * 0.7));
         engine.store.updateEventScores(event.id, {
@@ -396,61 +400,92 @@ export class MemoryGate {
             logInvalidObservationBatch(this.projectRoot, batchId);
             throw new Error(`Distill batch ${batchId} failed semantic capsule validation: ${JSON.stringify(capsules.rejected)}`);
         }
-        let committedObservationCount = 0;
-        const transaction = this.getStoreDb().transaction(() => {
-            for (let index = 0; index < capsules.accepted.length; index++) {
-                const acceptedCapsule = capsules.accepted[index];
-                const obs = acceptedCapsule.observation;
-                const sourceEventIds = acceptedCapsule.capsule.sourceEvidenceIds;
-                const quality = evaluateObservationQuality({
-                    ...obs,
-                    source: 'distill',
-                    sourceEventIds,
-                }, sourceEvents.filter(event => sourceEventIds.includes(event.id)));
-                const exact = engine.store.findObservationByDedupKey(observationDedupKey(obs.type, obs.title));
-                if (exact) {
-                    engine.store.linkObservationToEvents(exact.id, sourceEventIds);
-                    engine.store.incrementObservationAccess(exact.id);
-                    committedObservationCount += 1;
-                    continue;
-                }
-                const semantic = normalizeSemanticMemory({
-                    project: this.projectRoot,
-                    type: obs.type,
-                    title: obs.title,
-                    narrative: obs.narrative ?? '',
-                    concepts: obs.concepts,
-                    subject: obs.subject,
-                    predicate: obs.predicate,
-                    value: obs.value,
-                    polarity: obs.polarity,
-                    entities: obs.entities,
-                    temporal: obs.temporal,
-                });
-                engine.store.acceptSemanticObservation({
-                    sessionId: lease.sessionIds[0] ?? '',
-                    project: this.projectRoot,
-                    type: obs.type,
-                    title: obs.title,
-                    narrative: obs.narrative,
-                    facts: obs.facts,
+        const corpus = buildMemorySourceCorpus(sourceEvents);
+        const episode = createMemoryEpisodeV1({
+            episodeId: `memory-episode:distill:${stableRuntimeHash({
+                ...this.projectIdentity, actorId: 'actor:devflow-distill', batchId, sourceEvents: lease.eventIds,
+            }).slice(0, 32)}`,
+            ...this.projectIdentity,
+            actorId: 'actor:devflow-distill',
+            sessionId: lease.sessionIds[0] ?? `distill:${batchId}`,
+            turnId: `distill:${batchId}`,
+            sourceMessageId: `distill:${batchId}`,
+            sourceKind: 'distill',
+            coldRecallEligible: false,
+            content: corpus.content,
+            sourceEventIds: lease.eventIds,
+            createdAt: Date.now(),
+        });
+        const providerReceipt = createMemoryProviderReceipt(episode.contentHash, 'mcp-memory-distill.v1', capsules.accepted.length);
+        const persistenceByProposalId = {};
+        const sourceEventIdsByProposalId = new Map();
+        const proposals = capsules.accepted.map((acceptedCapsule, index) => {
+            const obs = acceptedCapsule.observation;
+            const sourceEventIds = acceptedCapsule.capsule.sourceEvidenceIds;
+            const quality = evaluateObservationQuality({
+                ...obs,
+                source: 'distill',
+                sourceEventIds,
+            }, sourceEvents.filter(event => sourceEventIds.includes(event.id)));
+            const semantic = normalizeSemanticMemory({
+                project: this.projectIdentity.memoryNamespace,
+                type: obs.type,
+                title: obs.title,
+                narrative: obs.narrative ?? '',
+                concepts: obs.concepts,
+                subject: obs.subject,
+                predicate: obs.predicate,
+                value: obs.value,
+                polarity: obs.polarity,
+                entities: obs.entities,
+                temporal: obs.temporal,
+            });
+            const proposal = createMemoryFactProposalV1({
+                proposalId: `memory-fact-proposal:distill:${stableRuntimeHash({ batchId, index, title: obs.title }).slice(0, 32)}`,
+                providerExecutionId: providerReceipt.executionId, type: obs.type,
+                subject: semantic.subject, predicate: semantic.predicate, value: semantic.value,
+                polarity: semantic.polarity === 'negative' ? 'negative' : 'positive', statement: obs.narrative ?? obs.title,
+                scope: this.projectIdentity.memoryNamespace, confidence: obs.confidence,
+                sourceSpans: sourceEventIds.flatMap(eventId => {
+                    const span = corpus.spans.get(eventId);
+                    return span ? [{ sourceMessageId: episode.sourceMessageId, ...span }] : [];
+                }),
+                relatedCandidateHandles: [],
+                observedAt: episode.createdAt,
+                ...hostTemporalFields(obs.temporal),
+                enrichment: {
+                    ...withoutSemanticIdentity(semantic),
+                    type: obs.type, title: obs.title, narrative: obs.narrative ?? obs.title,
+                    facts: obs.facts ?? [], files: [], tools: [],
                     concepts: mergeSemanticEntities(normalizeBatchConcepts(obs), [semantic.subject, semantic.predicate, semantic.value], semantic.entities.map(normalizeEntityKey)),
-                    importance: obs.importance ?? 5,
-                    confidence: obs.confidence,
-                    source: 'distill',
-                    sourceEventIds,
-                    qualityStatus: quality.status,
-                    quarantineReason: quality.reason,
-                    qualityDetails: quality.details,
-                    failureCategory: quality.failureCategory ?? undefined,
-                    semantic,
-                    capsule: acceptedCapsule.capsule,
-                    projection: acceptedCapsule.projection,
-                });
-                committedObservationCount += 1;
+                    evidenceStatus: quality.status === 'accepted' ? 'verified' : 'unverified',
+                    evidence: [],
+                },
+            });
+            sourceEventIdsByProposalId.set(proposal.proposalId, sourceEventIds);
+            persistenceByProposalId[proposal.proposalId] = {
+                sessionId: lease.sessionIds[0], source: 'distill', importance: obs.importance,
+                qualityStatus: quality.status, quarantineReason: quality.reason,
+                qualityDetails: quality.details, failureCategory: quality.failureCategory ?? undefined,
+                capsule: acceptedCapsule.capsule, projection: acceptedCapsule.projection,
+            };
+            return proposal;
+        });
+        const applied = await engine.commands.commitEpisodeWithProposals({
+            episode, idempotencyKey: `distill-memory:${batchId}`,
+            proposals, providerReceipt, persistenceByProposalId,
+        });
+        const acceptedSourceEventIds = new Set();
+        for (const decision of applied.decisions) {
+            if (decision.operation !== 'hold') {
+                for (const eventId of sourceEventIdsByProposalId.get(decision.candidateId) ?? []) {
+                    acceptedSourceEventIds.add(eventId);
+                }
             }
-            if (committedObservationCount > 0)
-                engine.store.markEventsProcessed(lease.eventIds);
+        }
+        const transaction = this.getStoreDb().transaction(() => {
+            if (acceptedSourceEventIds.size > 0)
+                engine.store.markEventsProcessed([...acceptedSourceEventIds]);
             leases.createReceipt(batchId, validObs.length, lease.eventCount);
             leases.commitLease(batchId);
         });
@@ -460,7 +495,12 @@ export class MemoryGate {
             identity: { projectRoot: this.projectRoot, sessionId: lease.sessionIds[0] },
             level: 'info',
             timestamp: Date.now(),
-            data: { stage: 'distill_batch', batchId, observationCount: validObs.length, eventsMarked: lease.eventIds.length },
+            data: {
+                stage: 'distill_batch',
+                batchId,
+                observationCount: validObs.length,
+                eventsMarked: acceptedSourceEventIds.size,
+            },
         });
         return validObs.length;
     }
@@ -513,75 +553,92 @@ export class MemoryGate {
         if (capsules.rejected.length > 0 || capsules.accepted.length !== validObs.length) {
             throw new Error(`memory_commit_turn failed semantic capsule validation: ${JSON.stringify(capsules.rejected)}`);
         }
-        const saved = [];
         const existingIds = new Set(engine.store.listObservations().map(observation => observation.id));
         const turnId = eventTurnId(event, turnEventId);
-        this.getStoreDb().transaction(() => {
-            for (const acceptedCapsule of capsules.accepted) {
-                const observation = acceptedCapsule.observation;
-                const quality = evaluateObservationQuality({
-                    ...observation,
-                    source: 'manual',
-                    sourceEventIds: acceptedCapsule.capsule.sourceEvidenceIds,
-                }, [event]);
-                const semantic = normalizeSemanticMemory({
-                    project: this.projectRoot,
-                    type: observation.type,
-                    title: observation.title,
-                    narrative: observation.narrative ?? '',
-                    concepts: observation.concepts,
-                    subject: observation.subject,
-                    predicate: observation.predicate,
-                    value: observation.value,
-                    polarity: observation.polarity,
-                    entities: observation.entities,
-                    temporal: observation.temporal,
-                });
-                const write = engine.store.acceptSemanticObservation({
-                    sessionId,
-                    project: this.projectRoot,
-                    type: observation.type,
-                    title: observation.title,
-                    narrative: observation.narrative,
-                    facts: observation.facts,
+        const promptText = readCanonicalPrompt(event.payload, event.user_message);
+        const episodeContent = promptText || buildMemorySourceCorpus([event]).content;
+        const episode = createMemoryEpisodeV1({
+            episodeId: `memory-episode:turn:${stableRuntimeHash({
+                ...this.projectIdentity, actorId: 'actor:devflow-host', sessionId, turnId, turnEventId,
+            }).slice(0, 32)}`,
+            ...this.projectIdentity, actorId: 'actor:devflow-host', sessionId, turnId,
+            sourceMessageId: turnEventId, sourceKind: 'turn', coldRecallEligible: true,
+            content: episodeContent, sourceEventIds: [turnEventId], createdAt: event.created_at,
+        });
+        const providerReceipt = createMemoryProviderReceipt(episode.contentHash, 'mcp-memory-turn.v1', capsules.accepted.length);
+        const persistenceByProposalId = {};
+        const proposals = capsules.accepted.map((acceptedCapsule, index) => {
+            const observation = acceptedCapsule.observation;
+            const quality = evaluateObservationQuality({
+                ...observation,
+                source: 'manual',
+                sourceEventIds: acceptedCapsule.capsule.sourceEvidenceIds,
+            }, [event]);
+            const semantic = normalizeSemanticMemory({
+                project: this.projectIdentity.memoryNamespace,
+                type: observation.type,
+                title: observation.title,
+                narrative: observation.narrative ?? '',
+                concepts: observation.concepts,
+                subject: observation.subject,
+                predicate: observation.predicate,
+                value: observation.value,
+                polarity: observation.polarity,
+                entities: observation.entities,
+                temporal: observation.temporal,
+            });
+            const narrative = observation.narrative ?? observation.title;
+            const proposal = createMemoryFactProposalV1({
+                proposalId: `memory-fact-proposal:turn:${stableRuntimeHash({ turnEventId, index, title: observation.title }).slice(0, 32)}`,
+                providerExecutionId: providerReceipt.executionId, type: observation.type,
+                subject: semantic.subject, predicate: semantic.predicate, value: semantic.value,
+                polarity: semantic.polarity === 'negative' ? 'negative' : 'positive',
+                statement: narrative, scope: this.projectIdentity.memoryNamespace, confidence: observation.confidence,
+                sourceSpans: memoryPromptSourceSpans(turnEventId, episodeContent, observation.evidenceSpans),
+                relatedCandidateHandles: [],
+                observedAt: episode.createdAt,
+                ...hostTemporalFields(observation.temporal),
+                enrichment: {
+                    ...withoutSemanticIdentity(semantic),
+                    type: observation.type, title: observation.title, narrative,
+                    facts: observation.facts ?? [], files: [], tools: [],
                     concepts: mergeSemanticEntities(normalizeBatchConcepts(observation), [semantic.subject, semantic.predicate, semantic.value], semantic.entities.map(normalizeEntityKey)),
-                    importance: observation.importance,
-                    confidence: observation.confidence,
-                    source: 'distill',
-                    sourceEventIds: [turnEventId],
-                    qualityStatus: quality.status,
-                    quarantineReason: quality.reason,
-                    qualityDetails: quality.details,
-                    failureCategory: quality.failureCategory ?? undefined,
-                    semantic,
-                    capsule: acceptedCapsule.capsule,
-                    projection: acceptedCapsule.projection,
-                });
-                const row = write.row;
-                saved.push({
-                    id: row.id,
-                    type: row.type,
-                    title: row.title,
-                    content: row.narrative,
-                    source: row.source,
-                    scope: row.project,
-                    confidence: row.confidence,
-                    importance: row.importance,
-                    score: 1,
-                    createdAt: row.timestamp,
+                    evidenceStatus: quality.status === 'accepted' ? 'verified' : 'unverified',
+                    evidence: [{ kind: 'source_event', source: turnEventId, summary: 'Host memory candidate grounded in the canonical turn event.' }],
+                },
+            });
+            persistenceByProposalId[proposal.proposalId] = {
+                sessionId, source: 'distill', importance: observation.importance,
+                qualityStatus: quality.status, quarantineReason: quality.reason,
+                qualityDetails: quality.details, failureCategory: quality.failureCategory ?? undefined,
+                capsule: acceptedCapsule.capsule, projection: acceptedCapsule.projection,
+            };
+            return proposal;
+        });
+        const applied = await engine.commands.commitEpisodeWithProposals({
+            episode, idempotencyKey: `turn-memory:${turnEventId}`,
+            proposals, providerReceipt, persistenceByProposalId,
+        });
+        const saved = applied.recordIds.flatMap(id => {
+            const row = engine.store.getObservation(id);
+            return row ? [{
+                    id: row.id, type: row.type, title: row.title, content: row.narrative,
+                    source: row.source, scope: row.project, confidence: row.confidence,
+                    importance: row.importance, score: 1, createdAt: row.timestamp,
                     indexStatus: row.embedding ? 'indexed' : 'pending',
-                });
+                }] : [];
+        });
+        this.getStoreDb().transaction(() => {
+            for (const row of saved) {
                 engine.store.recordPendingTurnObservation({
-                    turnEventId,
-                    turnId,
-                    sessionId,
-                    project: this.projectRoot,
-                    observationId: row.id,
-                    createdByTurn: !existingIds.has(row.id),
+                    turnEventId, turnId, sessionId, project: this.projectIdentity.memoryNamespace,
+                    observationId: row.id, createdByTurn: !existingIds.has(row.id),
                     createdAt: event.created_at,
                 });
             }
-            engine.store.markEventsProcessed([turnEventId]);
+            if (applied.decisions.some(decision => decision.operation !== 'hold')) {
+                engine.store.markEventsProcessed([turnEventId]);
+            }
         })();
         return saved;
     }
@@ -615,110 +672,85 @@ export class MemoryGate {
         if (capsules.rejected.length > 0 || capsules.accepted.length !== validObs.length) {
             throw new Error(`Explicit memory refinement failed evidence validation: ${JSON.stringify(capsules.rejected)}`);
         }
-        const existingIds = new Set(engine.store.listObservations().map(observation => observation.id));
         const turnId = eventTurnId(event, turnEventId);
-        const memories = [];
-        const retiredMemoryIds = [];
-        const operations = [];
-        this.getStoreDb().transaction(() => {
-            for (const acceptedCapsule of capsules.accepted) {
-                const observation = acceptedCapsule.observation;
-                const semantic = normalizeSemanticMemory({
-                    project: this.projectRoot,
-                    type: observation.type,
-                    title: observation.title,
-                    narrative: observation.narrative ?? '',
-                    concepts: observation.concepts,
-                    subject: observation.subject,
-                    predicate: observation.predicate,
-                    value: observation.value,
-                    polarity: observation.polarity,
-                    entities: observation.entities,
-                    temporal: observation.temporal,
-                });
-                const write = engine.store.acceptSemanticObservation({
-                    sessionId,
-                    project: this.projectRoot,
-                    type: observation.type,
-                    title: observation.title,
-                    narrative: observation.narrative,
+        const episode = createMemoryEpisodeV1({
+            episodeId: `memory-episode:host:${stableRuntimeHash({
+                ...this.projectIdentity, actorId: 'actor:devflow-host', sessionId, turnId, turnEventId,
+                sourceHash: stableRuntimeHash(sourceText),
+            }).slice(0, 32)}`,
+            ...this.projectIdentity, actorId: 'actor:devflow-host', sessionId, turnId,
+            sourceMessageId: turnEventId, content: sourceText,
+            sourceEventIds: [turnEventId], createdAt: event.created_at,
+        });
+        const providerReceipt = createMemoryProviderReceipt(episode.contentHash, 'mcp-memory-refinement.v1', capsules.accepted.length);
+        const candidateHandles = createCandidateHandles(episode, capsules.accepted.flatMap(item => item.observation.referencedFactIds ?? []), id => engine.store.getObservation(id));
+        const handleByFactId = new Map(candidateHandles.flatMap(handle => handle.factId ? [[handle.factId, handle.handle]] : []));
+        const factProposals = capsules.accepted.map((acceptedCapsule, index) => {
+            const observation = acceptedCapsule.observation;
+            const narrative = observation.narrative ?? observation.evidenceSpans?.[0] ?? observation.title;
+            const semantic = normalizeSemanticMemory({
+                project: this.projectIdentity.memoryNamespace, type: observation.type, title: observation.title,
+                narrative, concepts: observation.concepts, subject: observation.subject,
+                predicate: observation.predicate, value: observation.value,
+                polarity: observation.polarity, entities: observation.entities, temporal: observation.temporal,
+            });
+            const base = enrichExplicitMemory({
+                projectRoot: this.projectRoot, content: narrative, sourceEventIds: [turnEventId],
+            });
+            const sourceSpans = (observation.evidenceSpans ?? []).map(span => {
+                const start = sourceText.indexOf(span);
+                return {
+                    sourceMessageId: turnEventId, start, end: start + span.length,
+                    textHash: stableRuntimeHash(span),
+                };
+            });
+            return createMemoryFactProposalV1({
+                proposalId: `memory-fact-proposal:host:${stableRuntimeHash({
+                    episodeId: episode.episodeId, index, title: observation.title,
+                }).slice(0, 32)}`,
+                providerExecutionId: providerReceipt.executionId, type: observation.type,
+                subject: semantic.subject, predicate: semantic.predicate, value: semantic.value,
+                polarity: semantic.polarity === 'negative' ? 'negative' : 'positive',
+                statement: narrative, scope: this.projectIdentity.memoryNamespace,
+                confidence: Math.max(0.9, observation.confidence), sourceSpans,
+                relatedCandidateHandles: (observation.referencedFactIds ?? []).flatMap(id => {
+                    const handle = handleByFactId.get(id);
+                    return handle ? [handle] : [];
+                }), observedAt: episode.createdAt,
+                ...hostTemporalFields(observation.temporal),
+                enrichment: {
+                    ...withoutSemanticIdentity(base), type: observation.type, title: observation.title, narrative,
                     facts: [...new Set([...(observation.facts ?? []), ...(observation.evidenceSpans ?? [])])],
                     concepts: mergeSemanticEntities(normalizeBatchConcepts(observation), [semantic.subject, semantic.predicate, semantic.value], semantic.entities.map(normalizeEntityKey)),
-                    importance: Math.max(8, observation.importance),
-                    confidence: Math.max(0.9, observation.confidence),
-                    source: 'explicit_intent',
-                    sourceEventIds: [turnEventId],
-                    qualityStatus: 'accepted',
-                    evidenceStatus: 'verified',
-                    evidenceDetails: (observation.evidenceSpans ?? []).map(span => ({
-                        kind: 'host_evidence_span',
-                        source: turnEventId,
-                        summary: span,
-                    })),
-                    semantic,
-                    capsule: acceptedCapsule.capsule,
-                    projection: acceptedCapsule.projection,
-                    preferIncomingNarrative: true,
-                });
-                const row = write.row;
-                operations.push(write.action.toLocaleLowerCase('en-US'));
-                memories.push({
-                    id: row.id,
-                    type: row.type,
-                    title: row.title,
-                    content: row.narrative,
-                    source: row.source,
-                    scope: row.project,
-                    confidence: row.confidence,
-                    importance: row.importance,
-                    score: 1,
-                    createdAt: row.timestamp,
+                    evidenceStatus: 'verified', ...withoutSemanticIdentity(semantic),
+                },
+            });
+        });
+        const applied = await engine.commands.commitEpisodeWithProposals({
+            episode, idempotencyKey: `host-memory-refinement:${turnEventId}`,
+            proposals: factProposals, providerReceipt, candidateHandles,
+        });
+        const memories = applied.factIds.flatMap(id => {
+            const row = engine.store.getObservation(id);
+            return row ? [{
+                    id: row.id, type: row.type, title: row.title, content: row.narrative,
+                    source: row.source, scope: row.project, confidence: row.confidence,
+                    importance: row.importance, score: 1, createdAt: row.timestamp,
                     indexStatus: row.embedding ? 'indexed' : 'pending',
-                });
-                engine.store.recordPendingTurnObservation({
-                    turnEventId,
-                    turnId,
-                    sessionId,
-                    project: this.projectRoot,
-                    observationId: row.id,
-                    createdByTurn: !existingIds.has(row.id),
-                    createdAt: event.created_at,
-                });
-            }
-            const constraintSpans = turnConstraints.flatMap(candidate => candidate.evidenceSpans ?? []);
-            const baseline = engine.store.listObservations({ project: this.projectRoot })
-                .filter(observation => observation.source === 'explicit_intent')
-                .filter(observation => parseLearningStringArray(observation.source_event_ids).includes(turnEventId));
-            const refinedIds = new Set(memories.map(memory => memory.id));
-            for (const observation of baseline) {
-                if (refinedIds.has(observation.id) || observation.resolution_state === 'superseded')
-                    continue;
-                const replacementIndex = durableCandidates.findIndex(candidate => ((candidate.evidenceSpans ?? []).some(span => sameGroundedClause(observation.narrative, span))));
-                const replacement = replacementIndex >= 0
-                    ? memories[replacementIndex]
-                    : durableCandidates.length === 1 ? memories[0] : undefined;
-                if (!replacement || replacement.id === observation.id)
-                    continue;
-                engine.store.setObservationResolution(observation.id, 'superseded', replacement.id);
-                engine.store.addSemanticObservationRelation(replacement.id, observation.id, 'supersedes');
-                retiredMemoryIds.push(observation.id);
-                operations.push('supersede');
-            }
-            for (const observation of baseline) {
-                if (observation.resolution_state === 'superseded' || retiredMemoryIds.includes(observation.id))
-                    continue;
-                if (!constraintSpans.some(span => sameGroundedClause(observation.narrative, span)))
-                    continue;
-                if (engine.store.quarantineObservation(observation.id, 'host_classified_turn_constraint', {
-                    turnId,
-                    eventId: turnEventId,
-                    evidenceSpans: constraintSpans,
-                })) {
-                    retiredMemoryIds.push(observation.id);
-                    operations.push('retire');
-                }
-            }
-        })();
+                }] : [];
+        });
+        const retiredMemoryIds = [...new Set(applied.decisions
+                .filter(decision => decision.operation === 'supersede' || decision.operation === 'retire')
+                .flatMap(decision => decision.referencedFactIds))];
+        const operations = applied.decisions.map(decision => decision.operation);
+        for (const memory of memories) {
+            engine.store.recordPendingTurnObservation({
+                turnEventId, turnId, sessionId, project: this.projectIdentity.memoryNamespace,
+                observationId: memory.id,
+                createdByTurn: operations.includes('add') || operations.includes('link') || operations.includes('supersede'),
+                createdAt: event.created_at,
+            });
+        }
         emitSemanticControlLog({
             event: 'memory.semantic.refined',
             identity: { projectRoot: this.projectRoot, sessionId, turnId },
@@ -750,7 +782,7 @@ export class MemoryGate {
             turnEventId,
             turnId: eventTurnId(event, turnEventId),
             sessionId,
-            project: this.projectRoot,
+            project: this.projectIdentity.memoryNamespace,
             status: 'skipped',
             reason,
         });
@@ -760,7 +792,7 @@ export class MemoryGate {
             await this.forceWarmUp();
         return this.requireEngine().store.finalizeTurnObservationDecision({
             ...input,
-            project: this.projectRoot,
+            project: this.projectIdentity.memoryNamespace,
         });
     }
     async reconcileTurnObservationLineage(turns) {
@@ -779,7 +811,7 @@ export class MemoryGate {
                 turnEventId: turn.eventId,
                 turnId: turn.turnId,
                 sessionId: turn.sessionId,
-                project: this.projectRoot,
+                project: this.projectIdentity.memoryNamespace,
                 status: turn.status,
                 receiptId: turn.receiptId,
                 memoryIds: turn.memoryIds,
@@ -795,71 +827,6 @@ export class MemoryGate {
     logInvalidDistillBatch(batchId) {
         logInvalidObservationBatch(this.projectRoot, batchId);
     }
-    /**
-     * Saves distilled observations from Claude and marks source events as processed.
-     * @deprecated Use saveDistilledObservationsByBatch(batchId, observations) instead.
-     */
-    async saveDistilledObservations(observations, sessionId) {
-        emitSemanticControlLog({
-            event: 'memory.write.degraded',
-            identity: { projectRoot: this.projectRoot, sessionId },
-            level: 'warn',
-            timestamp: Date.now(),
-            data: { stage: 'legacy_distill', reason: 'deprecated_session_write', fallback: 'legacy_compatibility_path' },
-        });
-        if (!this.engine)
-            return 0;
-        const validObs = validateObservationBatch(observations);
-        if (!validObs) {
-            logInvalidObservationBatch(this.projectRoot, `legacy:${sessionId}`);
-            return 0;
-        }
-        const engine = this.engine;
-        engine.store.ensureSession(sessionId, this.projectRoot, 'Distilled observation');
-        const events = engine.store.getSessionEvents(sessionId);
-        const unprocessedIds = events.filter(e => !e.processed).map(e => e.id);
-        let committedObservationCount = 0;
-        const transaction = this.getStoreDb().transaction(() => {
-            for (let index = 0; index < validObs.length; index += 1) {
-                const obs = validObs[index];
-                const quality = evaluateObservationQuality({
-                    ...obs,
-                    source: 'distill',
-                    sourceEventIds: unprocessedIds,
-                }, events.filter(event => unprocessedIds.includes(event.id)));
-                const row = engine.store.addObservation({
-                    sessionId,
-                    project: this.projectRoot,
-                    type: obs.type,
-                    title: obs.title,
-                    narrative: obs.narrative,
-                    facts: obs.facts,
-                    concepts: obs.concepts,
-                    importance: obs.importance,
-                    confidence: obs.confidence,
-                    source: 'distill',
-                    sourceEventIds: unprocessedIds,
-                    qualityStatus: quality.status,
-                    quarantineReason: quality.reason,
-                    qualityDetails: quality.details,
-                    failureCategory: quality.failureCategory ?? undefined,
-                });
-                engine.store.linkObservationToEvents(row.id, unprocessedIds);
-                committedObservationCount += 1;
-            }
-            if (committedObservationCount > 0)
-                engine.store.markEventsProcessed(unprocessedIds);
-        });
-        transaction();
-        emitSemanticControlLog({
-            event: 'memory.write.completed',
-            identity: { projectRoot: this.projectRoot, sessionId },
-            level: 'info',
-            timestamp: Date.now(),
-            data: { stage: 'legacy_distill', observationCount: validObs.length, eventsMarked: unprocessedIds.length },
-        });
-        return validObs.length;
-    }
     /** Returns the count of unprocessed events (for session-start hook). */
     getPendingEventCount(sessionId, triage = true) {
         if (!this.engine)
@@ -927,7 +894,7 @@ export class MemoryGate {
             event: 'memory.engine.transitioned', identity: { projectRoot: this.projectRoot }, level: 'info', timestamp: Date.now(),
             data: { from: 'cold', to: 'warming' },
         });
-        this.engine = new MemoryEngine(this.projectRoot, this.embedder);
+        this.engine = new MemoryEngine(this.projectRoot, this.embedder, this.projectIdentity);
         this.setLeaseStore(new LeaseStore(this.getStoreDb()));
         // Clean up zombie sessions (>24h active)
         try {
@@ -1033,14 +1000,14 @@ export class MemoryGate {
     getRetrievalRevision() {
         return this.engine?.getRetrievalRevision() ?? 0;
     }
-    async saveExplicitMemoryIntent(content, sessionId, sourceEventId) {
+    async saveExplicitMemoryIntent(content, provenance, sourceEventId) {
         if (!this.engine)
             await this.forceWarmUp();
         try {
-            const result = await this.requireEngine().saveExplicitMemoryIntent(content, sessionId, sourceEventId);
+            const result = await this.requireEngine().saveExplicitMemoryIntent(content, provenance, sourceEventId);
             emitSemanticControlLog({
                 event: 'memory.write.completed',
-                identity: { projectRoot: this.projectRoot, sessionId },
+                identity: { projectRoot: this.projectRoot, projectId: this.projectIdentity.projectId, sessionId: provenance.sessionId },
                 level: 'info',
                 timestamp: Date.now(),
                 data: {
@@ -1053,7 +1020,7 @@ export class MemoryGate {
         }
         catch (error) {
             emitSemanticControlLog({
-                event: 'memory.write.degraded', identity: { projectRoot: this.projectRoot, sessionId }, level: 'error', timestamp: Date.now(),
+                event: 'memory.write.degraded', identity: { projectRoot: this.projectRoot, projectId: this.projectIdentity.projectId, sessionId: provenance.sessionId }, level: 'error', timestamp: Date.now(),
                 data: { stage: 'explicit_memory', reason: memoryErrorReason(error) },
             });
             throw error;
@@ -1084,7 +1051,7 @@ export class MemoryGate {
             await this.forceWarmUp();
         return this.requireEngine().store.listObservations({
             sessionId,
-            project: this.projectRoot,
+            project: this.projectIdentity.memoryNamespace,
             qualityStatus: 'accepted',
             resolutionState: 'current',
         }).map(row => ({
@@ -1131,9 +1098,6 @@ export class MemoryGate {
             let indexed = [];
             try {
                 const embeddings = await this.embedder.embedBatch(texts);
-                if (embeddings.length !== rows.length) {
-                    throw new Error(`Observation vector count mismatch: ${rows.length} observations, ${embeddings.length} vectors`);
-                }
                 indexed = rows.map((row, index) => ({ id: row.id, embedding: embeddings[index] }));
             }
             catch {
@@ -1167,15 +1131,15 @@ export class MemoryGate {
             await this.forceWarmUp();
         return this.requireEngine().getCandidates();
     }
-    async approveCandidate(id) {
+    async approveCandidate(id, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().approveCandidate(id);
+        await this.requireEngine().approveCandidate(id, provenance);
     }
-    async rejectCandidate(id) {
+    async rejectCandidate(id, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().rejectCandidate(id);
+        await this.requireEngine().rejectCandidate(id, provenance);
     }
     async search(query, options) {
         if (!this.engine)
@@ -1213,41 +1177,46 @@ export class MemoryGate {
             throw error;
         }
     }
+    async searchWithDiagnostics(query, options) {
+        if (!this.engine)
+            await this.forceWarmUp();
+        return this.requireEngine().searchWithDiagnostics(query, options);
+    }
     async listMemories(filter) {
         if (!this.engine)
             await this.forceWarmUp();
         return this.requireEngine().listMemories(filter);
     }
-    async addMemory(entry) {
+    async addMemory(entry, provenance) {
         if (!this.engine) {
             await this.forceWarmUp();
         }
-        return this.requireEngine().addMemory(entry);
+        return this.requireEngine().addMemory(entry, provenance);
     }
-    async updateMemory(id, updates) {
+    async updateMemory(id, updates, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().updateMemory(id, updates);
+        await this.requireEngine().updateMemory(id, updates, provenance);
     }
-    async deleteMemory(id) {
+    async deleteMemory(id, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().deleteMemory(id);
+        await this.requireEngine().deleteMemory(id, provenance);
     }
     async getPendingMemories() {
         if (!this.engine)
             await this.forceWarmUp();
         return this.requireEngine().getPendingMemories();
     }
-    async approveMemory(id) {
+    async approveMemory(id, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().approveMemory(id);
+        await this.requireEngine().approveMemory(id, provenance);
     }
-    async rejectMemory(id) {
+    async rejectMemory(id, provenance) {
         if (!this.engine)
             await this.forceWarmUp();
-        await this.requireEngine().rejectMemory(id);
+        await this.requireEngine().rejectMemory(id, provenance);
     }
     async extractFromEventsRealtime(events) {
         if (!this.engine)
@@ -1278,7 +1247,18 @@ export class MemoryGate {
         const engine = this.requireEngine();
         const eventExists = engine.store.getSessionEvents(event.sessionId).some(existing => existing.id === event.id);
         if (!eventExists) {
-            await this.recordEvent(event);
+            await this.recordEvent({
+                id: event.id,
+                sessionId: event.sessionId,
+                tool: event.tool,
+                command: typeof event.payload.command === 'string' ? event.payload.command : undefined,
+                exitCode: typeof event.payload.exitCode === 'number' ? event.payload.exitCode : undefined,
+                stderr: typeof event.payload.stderr === 'string' ? event.payload.stderr : undefined,
+                durationMs: typeof event.payload.durationMs === 'number' ? event.payload.durationMs : undefined,
+                createdAt: event.createdAt,
+                kind: event.kind,
+                payload: event.payload,
+            });
         }
     }
     /** Drain the signal buffer without running summarizer. Events are already persisted. */
@@ -1328,14 +1308,62 @@ function readCanonicalPrompt(payloadJson, userMessage) {
     }
     return userMessage?.trim() ?? '';
 }
-function sameGroundedClause(narrative, evidenceSpan) {
-    const left = narrative.normalize('NFKC').trim().toLocaleLowerCase('en-US');
-    const right = evidenceSpan.normalize('NFKC').trim().toLocaleLowerCase('en-US');
-    if (left.length < 4 || right.length < 4)
-        return false;
-    return left === right || (right.includes(left) && left.length / right.length >= 0.7);
+function buildMemorySourceCorpus(events) {
+    let content = '';
+    const spans = new Map();
+    for (const event of events) {
+        const block = JSON.stringify({
+            id: event.id,
+            sessionId: event.session_id,
+            tool: event.tool,
+            command: event.command,
+            exitCode: event.exit_code,
+            stderr: event.stderr,
+            payload: event.payload,
+            createdAt: event.created_at,
+        });
+        const start = content.length;
+        content += block;
+        const end = content.length;
+        spans.set(event.id, { start, end, textHash: stableRuntimeHash(block) });
+        content += '\n';
+    }
+    return {
+        content: content.trimEnd() || 'No source event content was available.',
+        spans,
+    };
+}
+function memoryPromptSourceSpans(sourceMessageId, sourceText, evidenceSpans) {
+    const spans = [...new Set((evidenceSpans ?? []).map(value => value.trim()).filter(Boolean))]
+        .flatMap(span => {
+        const start = sourceText.indexOf(span);
+        if (start < 0)
+            return [];
+        return [{
+                sourceMessageId,
+                start,
+                end: start + span.length,
+                textHash: stableRuntimeHash(sourceText.slice(start, start + span.length)),
+            }];
+    });
+    if (spans.length > 0)
+        return spans;
+    return [{
+            sourceMessageId,
+            start: 0,
+            end: sourceText.length,
+            textHash: stableRuntimeHash(sourceText),
+        }];
+}
+function hostTemporalFields(temporal) {
+    const validFrom = temporal?.validFrom ? Date.parse(temporal.validFrom) : Number.NaN;
+    const validUntil = temporal?.validUntil ? Date.parse(temporal.validUntil) : Number.NaN;
+    return {
+        ...(Number.isFinite(validFrom) ? { validFrom } : {}),
+        ...(Number.isFinite(validUntil) ? { validUntil } : {}),
+    };
 }
-// --- L1 Rule Scorer (backward compat) ---
+// --- L1 Rule Scorer ---
 function scoreL1Rules(event) {
     let score = 0;
     const stderrText = event.stderr ?? '';
@@ -1399,5 +1427,34 @@ function scoreDialogSignals(message) {
 function memoryErrorReason(error) {
     return (error instanceof Error ? error.message : String(error)).trim().slice(0, 500) || 'memory_operation_failed';
 }
+function withoutSemanticIdentity(value) {
+    const { semanticKey: _semanticKey, facetKey: _facetKey, ...rest } = value;
+    return rest;
+}
+function createMemoryProviderReceipt(requestHash, providerVersion, proposalCount) {
+    const body = {
+        schemaVersion: 'provider-execution-receipt.v1',
+        receiptId: `memory-provider-receipt:${stableRuntimeHash({ requestHash, providerVersion }).slice(0, 32)}`,
+        executionId: `memory-provider-execution:${stableRuntimeHash({ requestHash, providerVersion, proposalCount }).slice(0, 32)}`,
+        requestHash, providerId: 'memory-host-boundary', providerVersion,
+        capability: 'memory_facts', status: 'ready',
+        proposalCount, acceptedCount: proposalCount, rejectedCount: 0,
+        reasonCodes: [], latencyMs: 0, createdAt: Date.now(),
+    };
+    return { ...body, receiptHash: stableRuntimeHash(body) };
+}
+function createCandidateHandles(episode, factIds, load) {
+    return [...new Set(factIds)].flatMap(factId => {
+        const fact = load(factId);
+        if (!fact || fact.project !== episode.memoryNamespace || fact.resolution_state !== 'current'
+            || !isObservationType(fact.type))
+            return [];
+        return [{
+                handle: `memory-candidate-handle:${stableRuntimeHash({ episodeId: episode.episodeId, factId }).slice(0, 32)}`,
+                statement: fact.narrative, type: fact.type, scope: fact.project,
+                slotIdentity: `memory-existing-slot:${fact.id}`, factId: fact.id,
+            }];
+    });
+}
 export { scoreL1Rules, scoreDialogSignals };
 //# sourceMappingURL=memory-gate.js.map