ds4-context-core 0.1.1 → 0.2.0-beta.1

package/dist/persistence/repositories/memory-repository.js

@@ -1,17 +1,5 @@
+import { SqliteWriteCoordinator } from "../write-coordinator.js";
 import { parseMemoryMutation, parsePinMutation, } from "../../memory/memory-types.js";
-function runTransaction(database, operation) {
-    database.exec("BEGIN IMMEDIATE");
-    try {
-        const result = operation();
-        database.exec("COMMIT");
-        return result;
-    }
-    catch (error) {
-        if (database.isTransaction)
-            database.exec("ROLLBACK");
-        throw error;
-    }
-}
 function parseJson(value) {
     try {
         return JSON.parse(value);
@@ -20,17 +8,53 @@ function parseJson(value) {
         return undefined;
     }
 }
-function classificationFromMetadata(value) {
-    const metadata = parseJson(value);
-    if (!metadata || typeof metadata !== "object" || !("classification" in metadata))
+function stringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? [...new Set(value)]
+        : undefined;
+}
+function mutationProvenance(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const sourceEntryIds = stringList(record.sourceEntryIds);
+    const contradicts = stringList(record.contradicts);
+    if (typeof record.sourceSessionId !== "string"
+        || typeof record.mutationEntryId !== "string"
+        || !sourceEntryIds
+        || !contradicts) {
         return undefined;
-    const classification = metadata.classification;
-    return classification === "normal"
-        || classification === "internal"
-        || classification === "sensitive"
-        || classification === "local-only"
-        ? classification
+    }
+    return {
+        sourceSessionId: record.sourceSessionId,
+        ...(typeof record.sourceSessionFile === "string"
+            ? { sourceSessionFile: record.sourceSessionFile }
+            : {}),
+        mutationEntryId: record.mutationEntryId,
+        ...(typeof record.sourceBranchEntryId === "string"
+            ? { sourceBranchEntryId: record.sourceBranchEntryId }
+            : {}),
+        sourceEntryIds,
+        ...(typeof record.supersedes === "string" ? { supersedes: record.supersedes } : {}),
+        contradicts,
+    };
+}
+function metadata(value) {
+    const parsed = parseJson(value);
+    if (!parsed || typeof parsed !== "object")
+        return {};
+    const record = parsed;
+    const classification = record.classification === "normal"
+        || record.classification === "internal"
+        || record.classification === "sensitive"
+        || record.classification === "local-only"
+        ? record.classification
         : undefined;
+    const provenance = mutationProvenance(record.provenance);
+    return {
+        ...(classification ? { classification } : {}),
+        ...(provenance ? { provenance } : {}),
+    };
 }
 function entryIdFromKey(entryKey) {
     const separator = entryKey.indexOf(":");
@@ -41,36 +65,53 @@ function identityKey(item) {
         return undefined;
     return [item.scope, item.sessionId ?? "", item.projectPath ?? "", item.key].join("\0");
 }
+function memoryMutationMatchesSource(item, row) {
+    return item.scope === "session"
+        ? item.sessionId === row.session_id
+        : item.projectPath === row.source_project_path;
+}
+function pinMutationMatchesSource(item, row) {
+    return item.scope === "project"
+        ? item.projectPath === row.source_project_path
+        : item.sessionId === row.session_id;
+}
 function mapMemory(row, sourceEntryIds) {
+    const stored = metadata(row.metadata_json);
+    const fallbackSessionId = row.origin_session_id ?? row.session_id ?? "legacy";
     return {
         id: row.memory_id,
         scope: row.scope,
         ...(row.session_id ? { sessionId: row.session_id } : {}),
         ...(row.project_path ? { projectPath: row.project_path } : {}),
         ...(row.memory_key ? { key: row.memory_key } : {}),
-        ...(classificationFromMetadata(row.metadata_json)
-            ? { classification: classificationFromMetadata(row.metadata_json) }
-            : {}),
+        ...(stored.classification ? { classification: stored.classification } : {}),
         claim: row.claim,
         status: row.status,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
-        originSessionId: row.origin_session_id ?? row.session_id ?? "legacy",
+        originSessionId: fallbackSessionId,
         ...(row.superseded_by ? { supersededBy: row.superseded_by } : {}),
         ...(row.status_reason ? { statusReason: row.status_reason } : {}),
         sourceEntryIds,
+        provenance: stored.provenance ?? {
+            sourceSessionId: fallbackSessionId,
+            mutationEntryId: sourceEntryIds.at(-1) ?? row.memory_id,
+            sourceEntryIds,
+            contradicts: [],
+        },
     };
 }
 function mapPin(row) {
+    const stored = metadata(row.metadata_json);
+    const fallbackSessionId = row.session_id ?? "legacy";
+    const fallbackEntryId = row.source_entry_id ?? row.pin_id;
     return {
         id: row.pin_id,
         scope: row.scope,
         ...(row.session_id ? { sessionId: row.session_id } : {}),
         ...(row.project_path ? { projectPath: row.project_path } : {}),
         ...(row.branch_leaf_id ? { branchLeafId: row.branch_leaf_id } : {}),
-        ...(classificationFromMetadata(row.metadata_json)
-            ? { classification: classificationFromMetadata(row.metadata_json) }
-            : {}),
+        ...(stored.classification ? { classification: stored.classification } : {}),
         content: row.content,
         status: row.status,
         createdAt: row.created_at,
@@ -79,36 +120,145 @@ function mapPin(row) {
         ...(row.status_reason ? { statusReason: row.status_reason } : {}),
         ...(row.source_entry_id ? { sourceEntryId: row.source_entry_id } : {}),
         ...(row.source_file ? { sourceFile: row.source_file } : {}),
+        provenance: stored.provenance ?? {
+            sourceSessionId: fallbackSessionId,
+            mutationEntryId: fallbackEntryId,
+            sourceEntryIds: [fallbackEntryId],
+            contradicts: [],
+        },
     };
 }
 export class MemoryRepository {
     database;
-    constructor(database) {
+    writes;
+    constructor(database, writes = new SqliteWriteCoordinator(database)) {
         this.database = database;
+        this.writes = writes;
     }
     reconcileSession(sessionId, memoryMutations, pinMutations) {
-        return runTransaction(this.database, () => {
+        return this.writes.transaction("memory-reconcile-session", () => {
+            this.database.prepare(`
+        DELETE FROM project_memory_sessions AS source
+        WHERE source.session_id = ? AND source.status <> 'ready'
+          AND NOT EXISTS (
+            SELECT 1 FROM project_memory_source_exclusions AS exclusion
+            WHERE exclusion.project_path = source.project_path
+              AND exclusion.session_id = source.session_id
+          )
+      `).run(sessionId);
             this.database.prepare("DELETE FROM memory_mutations WHERE session_id = ?").run(sessionId);
             this.database.prepare("DELETE FROM pin_mutations WHERE session_id = ?").run(sessionId);
-            const insertMemoryMutation = this.database.prepare(`
-        INSERT INTO memory_mutations(
-          mutation_key, mutation_id, session_id, created_at, entry_order, payload_json
-        ) VALUES (?, ?, ?, ?, ?, ?)
-      `);
-            const insertPinMutation = this.database.prepare(`
-        INSERT INTO pin_mutations(
-          mutation_key, mutation_id, session_id, created_at, entry_order, payload_json
-        ) VALUES (?, ?, ?, ?, ?, ?)
-      `);
-            for (const mutation of memoryMutations) {
-                insertMemoryMutation.run(mutation.mutationKey, mutation.mutationId, mutation.sessionId, mutation.createdAt, mutation.entryOrder, JSON.stringify(mutation.payload));
+            this.insertMemoryMutations(memoryMutations);
+            this.insertPinMutations(pinMutations);
+            return this.materialize();
+        });
+    }
+    getProjectSourceState(projectPath, sessionId) {
+        const row = this.database.prepare(`
+      SELECT project_path, session_id, session_file, header_hash, file_size,
+        file_mtime_ms, checkpoint_offset, checkpoint_hash_start, checkpoint_hash,
+        indexed_records, indexed_mutations, malformed_lines, status, last_error,
+        indexed_at, NULL AS excluded_at, NULL AS exclusion_reason
+      FROM project_memory_sessions
+      WHERE project_path = ? AND session_id = ?
+    `).get(projectPath, sessionId);
+        return row ? this.mapProjectSourceCheckpoint(row) : undefined;
+    }
+    replaceProjectSource(checkpoint, memoryMutations, pinMutations) {
+        return this.writes.transaction("project-memory-source-rebuild", () => {
+            this.database.prepare("DELETE FROM memory_mutations WHERE session_id = ?").run(checkpoint.sessionId);
+            this.database.prepare("DELETE FROM pin_mutations WHERE session_id = ?").run(checkpoint.sessionId);
+            this.insertMemoryMutations(memoryMutations);
+            this.insertPinMutations(pinMutations);
+            this.writeProjectSourceState(checkpoint);
+            return this.materialize();
+        });
+    }
+    appendProjectSource(checkpoint, memoryMutations, pinMutations) {
+        return this.writes.transaction("project-memory-source-append", () => {
+            this.insertMemoryMutations(memoryMutations, true);
+            this.insertPinMutations(pinMutations, true);
+            this.writeProjectSourceState(checkpoint);
+            return this.materialize();
+        });
+    }
+    markProjectSourceUnavailable(projectPath, sessionId, status, error, indexedAt) {
+        return this.writes.transaction("project-memory-source-unavailable", () => {
+            const existing = this.getProjectSourceState(projectPath, sessionId);
+            if (!existing)
+                return undefined;
+            const lastError = error.slice(0, 1_000);
+            if (existing.status === status
+                && existing.indexedMutations === 0
+                && existing.lastError === lastError) {
+                return undefined;
             }
-            for (const mutation of pinMutations) {
-                insertPinMutation.run(mutation.mutationKey, mutation.mutationId, mutation.sessionId, mutation.createdAt, mutation.entryOrder, JSON.stringify(mutation.payload));
+            this.writeProjectSourceState({
+                ...existing,
+                indexedMutations: 0,
+                status,
+                lastError,
+                indexedAt,
+            });
+            return this.materialize();
+        });
+    }
+    setProjectSourceExcluded(projectPath, sessionId, excluded, excludedAt, reason) {
+        return this.writes.transaction("project-memory-source-exclusion", () => {
+            if (excluded) {
+                this.database.prepare(`
+          INSERT INTO project_memory_source_exclusions(project_path, session_id, excluded_at, reason)
+          VALUES (?, ?, ?, ?)
+          ON CONFLICT(project_path, session_id) DO UPDATE SET
+            excluded_at = excluded.excluded_at,
+            reason = excluded.reason
+        `).run(projectPath, sessionId, excludedAt, reason?.slice(0, 500) ?? null);
+            }
+            else {
+                this.database.prepare(`
+          DELETE FROM project_memory_source_exclusions
+          WHERE project_path = ? AND session_id = ?
+        `).run(projectPath, sessionId);
             }
             return this.materialize();
         });
     }
+    listProjectSources(projectPath) {
+        const rows = this.database.prepare(`
+      SELECT state.project_path, state.session_id, state.session_file, state.header_hash,
+        state.file_size, state.file_mtime_ms, state.checkpoint_offset,
+        state.checkpoint_hash_start, state.checkpoint_hash, state.indexed_records,
+        state.indexed_mutations, state.malformed_lines, state.status, state.last_error,
+        state.indexed_at, exclusion.excluded_at, exclusion.reason AS exclusion_reason,
+        (SELECT count(*) FROM memory_items AS memory
+          WHERE memory.scope = 'project' AND memory.project_path = state.project_path
+            AND memory.origin_session_id = state.session_id AND memory.status = 'active')
+          AS active_project_memories,
+        (SELECT count(*) FROM pins AS pin
+          WHERE pin.scope = 'project' AND pin.project_path = state.project_path
+            AND pin.session_id = state.session_id AND pin.status = 'active')
+          AS active_project_pins
+      FROM project_memory_sessions AS state
+      LEFT JOIN project_memory_source_exclusions AS exclusion
+        ON exclusion.project_path = state.project_path AND exclusion.session_id = state.session_id
+      WHERE state.project_path = ?
+      ORDER BY state.indexed_at DESC, state.session_id
+    `).all(projectPath);
+        return rows.map((row) => ({
+            projectPath: row.project_path,
+            sessionId: row.session_id,
+            sessionFile: row.session_file,
+            status: row.excluded_at !== null ? "excluded" : row.status,
+            indexedRecords: row.indexed_records,
+            indexedMutations: row.indexed_mutations,
+            malformedLines: row.malformed_lines,
+            activeProjectMemories: row.active_project_memories ?? 0,
+            activeProjectPins: row.active_project_pins ?? 0,
+            indexedAt: row.indexed_at,
+            ...(row.last_error ? { lastError: row.last_error } : {}),
+            ...(row.exclusion_reason ? { exclusionReason: row.exclusion_reason } : {}),
+        }));
+    }
     getMemory(id) {
         const row = this.database.prepare("SELECT * FROM memory_items WHERE memory_id = ?").get(id);
         return row ? mapMemory(row, this.memorySourceIds(id)) : undefined;
@@ -119,10 +269,11 @@ export class MemoryRepository {
       SELECT * FROM memory_items
       WHERE (
         (scope = 'session' AND session_id = ?)
-        OR (scope = 'project' AND project_path = ? AND ? = 1)
+        OR (scope = 'project' AND project_path = ? AND ? = 1
+          AND (? = 1 OR origin_session_id = ?))
       ) ${status}
       ORDER BY created_at DESC, memory_id
-    `).all(options.sessionId, options.projectPath, options.includeProject ? 1 : 0);
+    `).all(options.sessionId, options.projectPath, options.includeProject ? 1 : 0, options.includeCrossSessionProject ? 1 : 0, options.sessionId);
         const sources = this.memorySources(new Set(rows.map((row) => row.memory_id)));
         return rows.map((row) => mapMemory(row, sources.get(row.memory_id) ?? []));
     }
@@ -136,28 +287,30 @@ export class MemoryRepository {
       SELECT * FROM pins
       WHERE (
         (scope IN ('session', 'branch') AND session_id = ?)
-        OR (scope = 'project' AND project_path = ? AND ? = 1)
+        OR (scope = 'project' AND project_path = ? AND ? = 1
+          AND (? = 1 OR session_id = ?))
       ) ${status}
       ORDER BY created_at ASC, pin_id
-    `).all(options.sessionId, options.projectPath, options.includeProject ? 1 : 0);
+    `).all(options.sessionId, options.projectPath, options.includeProject ? 1 : 0, options.includeCrossSessionProject ? 1 : 0, options.sessionId);
         return rows.map(mapPin);
     }
-    stats(sessionId, projectPath) {
+    stats(sessionId, projectPath, includeCrossSessionProject = true) {
         const memories = this.database.prepare(`
       SELECT
         COALESCE(sum(status = 'active'), 0) AS active,
         COALESCE(sum(status <> 'active'), 0) AS inactive
       FROM memory_items
-      WHERE (scope = 'session' AND session_id = ?) OR (scope = 'project' AND project_path = ?)
-    `).get(sessionId, projectPath);
+      WHERE (scope = 'session' AND session_id = ?)
+         OR (scope = 'project' AND project_path = ? AND (? = 1 OR origin_session_id = ?))
+    `).get(sessionId, projectPath, includeCrossSessionProject ? 1 : 0, sessionId);
         const pins = this.database.prepare(`
       SELECT
         COALESCE(sum(status = 'active'), 0) AS active,
         COALESCE(sum(status <> 'active'), 0) AS inactive
       FROM pins
       WHERE (scope IN ('session', 'branch') AND session_id = ?)
-         OR (scope = 'project' AND project_path = ?)
-    `).get(sessionId, projectPath);
+         OR (scope = 'project' AND project_path = ? AND (? = 1 OR session_id = ?))
+    `).get(sessionId, projectPath, includeCrossSessionProject ? 1 : 0, sessionId);
         return {
             activeMemories: memories.active,
             inactiveMemories: memories.inactive,
@@ -171,8 +324,25 @@ export class MemoryRepository {
         const memories = new Map();
         const pins = new Map();
         const memoryRows = this.database.prepare(`
-      SELECT mutation_key, mutation_id, session_id, created_at, entry_order, payload_json
-      FROM memory_mutations ORDER BY created_at, session_id, entry_order, mutation_id, mutation_key
+      SELECT mutation.mutation_key, mutation.mutation_id, mutation.session_id,
+        session.session_file, session.project_path AS source_project_path,
+        mutation.created_at, mutation.entry_order, mutation.source_parent_entry_id,
+        CASE
+          WHEN exclusion.session_id IS NOT NULL THEN 0
+          WHEN source.status IS NOT NULL AND source.status <> 'ready' THEN 0
+          ELSE 1
+        END AS source_project_enabled,
+        mutation.payload_json
+      FROM memory_mutations AS mutation
+      JOIN sessions AS session ON session.session_id = mutation.session_id
+      LEFT JOIN project_memory_sessions AS source
+        ON source.project_path = session.project_path
+          AND source.session_id = mutation.session_id
+      LEFT JOIN project_memory_source_exclusions AS exclusion
+        ON exclusion.project_path = session.project_path
+          AND exclusion.session_id = mutation.session_id
+      ORDER BY mutation.created_at, mutation.session_id, mutation.entry_order,
+        mutation.mutation_id, mutation.mutation_key
     `).all();
         const memoryOperations = [];
         for (const row of memoryRows) {
@@ -189,8 +359,25 @@ export class MemoryRepository {
             this.applyMemoryMutation(memories, mutation, row, warnings, true);
         }
         const pinRows = this.database.prepare(`
-      SELECT mutation_key, mutation_id, session_id, created_at, entry_order, payload_json
-      FROM pin_mutations ORDER BY created_at, session_id, entry_order, mutation_id, mutation_key
+      SELECT mutation.mutation_key, mutation.mutation_id, mutation.session_id,
+        session.session_file, session.project_path AS source_project_path,
+        mutation.created_at, mutation.entry_order, mutation.source_parent_entry_id,
+        CASE
+          WHEN exclusion.session_id IS NOT NULL THEN 0
+          WHEN source.status IS NOT NULL AND source.status <> 'ready' THEN 0
+          ELSE 1
+        END AS source_project_enabled,
+        mutation.payload_json
+      FROM pin_mutations AS mutation
+      JOIN sessions AS session ON session.session_id = mutation.session_id
+      LEFT JOIN project_memory_sessions AS source
+        ON source.project_path = session.project_path
+          AND source.session_id = mutation.session_id
+      LEFT JOIN project_memory_source_exclusions AS exclusion
+        ON exclusion.project_path = session.project_path
+          AND exclusion.session_id = mutation.session_id
+      ORDER BY mutation.created_at, mutation.session_id, mutation.entry_order,
+        mutation.mutation_id, mutation.mutation_key
     `).all();
         const pinOperations = [];
         for (const row of pinRows) {
@@ -219,6 +406,15 @@ export class MemoryRepository {
             memory.item.status = "invalid";
             memory.item.statusReason = `Conflicts with active memory ${previousId}`;
             memory.item.updatedAt = Math.max(memory.item.updatedAt, memory.item.createdAt);
+            memory.item.provenance.contradicts = [
+                ...new Set([...memory.item.provenance.contradicts, previousId]),
+            ];
+            const previous = memories.get(previousId);
+            if (previous) {
+                previous.item.provenance.contradicts = [
+                    ...new Set([...previous.item.provenance.contradicts, memory.item.id]),
+                ];
+            }
             warnings.push(`Memory ${memory.item.id} invalidated because key conflicts with ${previousId}`);
         }
         this.database.exec(`
@@ -240,7 +436,10 @@ export class MemoryRepository {
         const insertMemorySource = this.database.prepare("INSERT OR IGNORE INTO memory_sources(memory_id, entry_key) VALUES (?, ?)");
         const insertMemoryFts = this.database.prepare("INSERT INTO memory_fts(claim, memory_id) VALUES (?, ?)");
         for (const { item, sourceKeys } of memories.values()) {
-            insertMemory.run(item.id, item.scope, item.sessionId ?? null, item.projectPath ?? null, item.claim, item.status, item.createdAt, null, item.key ?? null, item.originSessionId, item.updatedAt, item.statusReason ?? null, JSON.stringify({ ...(item.classification ? { classification: item.classification } : {}) }));
+            insertMemory.run(item.id, item.scope, item.sessionId ?? null, item.projectPath ?? null, item.claim, item.status, item.createdAt, null, item.key ?? null, item.originSessionId, item.updatedAt, item.statusReason ?? null, JSON.stringify({
+                ...(item.classification ? { classification: item.classification } : {}),
+                provenance: item.provenance,
+            }));
             for (const sourceKey of sourceKeys) {
                 if (availableEntryKeys.has(sourceKey))
                     insertMemorySource.run(item.id, sourceKey);
@@ -263,7 +462,10 @@ export class MemoryRepository {
             const sourceEntryId = item.sourceEntryId ?? item.id;
             const sourceEntryKey = item.sessionId ? `${item.sessionId}:${sourceEntryId}` : null;
             const sourceExists = sourceEntryKey ? availableEntryKeys.has(sourceEntryKey) : false;
-            insertPin.run(item.id, item.scope, item.sessionId ?? null, item.projectPath ?? null, item.content, sourceExists ? sourceEntryKey : null, sourceExists ? sourceEntryId : null, item.sourceFile ?? null, item.status, item.createdAt, item.branchLeafId ?? null, null, item.updatedAt, item.statusReason ?? null, JSON.stringify({ ...(item.classification ? { classification: item.classification } : {}) }));
+            insertPin.run(item.id, item.scope, item.sessionId ?? null, item.projectPath ?? null, item.content, sourceExists ? sourceEntryKey : null, sourceExists ? sourceEntryId : null, item.sourceFile ?? null, item.status, item.createdAt, item.branchLeafId ?? null, null, item.updatedAt, item.statusReason ?? null, JSON.stringify({
+                ...(item.classification ? { classification: item.classification } : {}),
+                provenance: item.provenance,
+            }));
         }
         const updateSupersededPin = this.database.prepare("UPDATE pins SET superseded_by = ? WHERE pin_id = ?");
         for (const item of pins.values()) {
@@ -284,9 +486,17 @@ export class MemoryRepository {
             if (mutation.operation === "status") {
                 const existing = memories.get(mutation.memoryId);
                 if (!existing) {
+                    if (row.source_project_enabled === 0)
+                        return;
                     warnings.push(`Memory status mutation ${mutation.mutationId} references missing ${mutation.memoryId}`);
                     return;
                 }
+                if (existing.item.scope === "project" && row.source_project_enabled === 0)
+                    return;
+                if (!memoryMutationMatchesSource(existing.item, row)) {
+                    warnings.push(`Memory status mutation ${mutation.mutationId} crosses its source project/session scope`);
+                    return;
+                }
                 existing.item.status = mutation.status;
                 existing.item.updatedAt = mutation.createdAt;
                 existing.item.statusReason = mutation.reason;
@@ -294,11 +504,25 @@ export class MemoryRepository {
                 return;
             }
             if (mutation.operation === "supersede") {
+                if (mutation.item.scope === "project" && row.source_project_enabled === 0)
+                    return;
                 const previous = memories.get(mutation.previousId);
                 if (!previous) {
                     warnings.push(`Memory supersession ${mutation.mutationId} references missing ${mutation.previousId}`);
                     return;
                 }
+                const replacement = memories.get(mutation.item.id);
+                if (!replacement
+                    || replacement.item.provenance.sourceSessionId !== row.session_id
+                    || replacement.item.provenance.mutationEntryId !== entryIdFromKey(row.mutation_key)) {
+                    warnings.push(`Memory supersession ${mutation.mutationId} has no valid replacement ${mutation.item.id}`);
+                    return;
+                }
+                if (previous.item.scope !== replacement.item.scope
+                    || !memoryMutationMatchesSource(previous.item, row)) {
+                    warnings.push(`Memory supersession ${mutation.mutationId} crosses its source project/session scope`);
+                    return;
+                }
                 previous.item.status = "superseded";
                 previous.item.supersededBy = mutation.item.id;
                 previous.item.updatedAt = mutation.createdAt;
@@ -309,6 +533,8 @@ export class MemoryRepository {
         if (mutation.operation === "status")
             return;
         const value = mutation.item;
+        if (value.scope === "project" && row.source_project_enabled === 0)
+            return;
         const existing = memories.get(value.id);
         if (existing) {
             if (existing.item.claim !== value.claim || existing.item.scope !== value.scope) {
@@ -320,10 +546,16 @@ export class MemoryRepository {
             warnings.push(`Project memory ${value.id} has no project path`);
             return;
         }
+        if (value.scope === "project" && value.projectPath !== row.source_project_path) {
+            warnings.push(`Project memory ${value.id} does not match its canonical source project`);
+            return;
+        }
         const sourceKeys = new Set([
             row.mutation_key,
             ...value.sourceEntryIds.map((entryId) => `${row.session_id}:${entryId}`),
         ]);
+        const mutationEntryId = entryIdFromKey(row.mutation_key);
+        const sourceEntryIds = [...new Set([mutationEntryId, ...value.sourceEntryIds])];
         const item = {
             id: value.id,
             scope: value.scope,
@@ -336,7 +568,18 @@ export class MemoryRepository {
             createdAt: value.createdAt,
             updatedAt: mutation.createdAt,
             originSessionId: row.session_id,
-            sourceEntryIds: [...new Set([entryIdFromKey(row.mutation_key), ...value.sourceEntryIds])],
+            sourceEntryIds,
+            provenance: {
+                sourceSessionId: row.session_id,
+                sourceSessionFile: row.session_file,
+                mutationEntryId,
+                ...(row.source_parent_entry_id
+                    ? { sourceBranchEntryId: row.source_parent_entry_id }
+                    : {}),
+                sourceEntryIds,
+                ...(mutation.operation === "supersede" ? { supersedes: mutation.previousId } : {}),
+                contradicts: [],
+            },
         };
         memories.set(item.id, { item, sourceKeys });
     }
@@ -345,9 +588,17 @@ export class MemoryRepository {
             if (mutation.operation === "status") {
                 const existing = pins.get(mutation.pinId);
                 if (!existing) {
+                    if (row.source_project_enabled === 0)
+                        return;
                     warnings.push(`Pin status mutation ${mutation.mutationId} references missing ${mutation.pinId}`);
                     return;
                 }
+                if (existing.scope === "project" && row.source_project_enabled === 0)
+                    return;
+                if (!pinMutationMatchesSource(existing, row)) {
+                    warnings.push(`Pin status mutation ${mutation.mutationId} crosses its source project/session scope`);
+                    return;
+                }
                 existing.status = mutation.status;
                 existing.updatedAt = mutation.createdAt;
                 existing.statusReason = mutation.reason;
@@ -355,11 +606,24 @@ export class MemoryRepository {
                 return;
             }
             if (mutation.operation === "supersede") {
+                if (mutation.item.scope === "project" && row.source_project_enabled === 0)
+                    return;
                 const previous = pins.get(mutation.previousId);
                 if (!previous) {
                     warnings.push(`Pin supersession ${mutation.mutationId} references missing ${mutation.previousId}`);
                     return;
                 }
+                const replacement = pins.get(mutation.item.id);
+                if (!replacement
+                    || replacement.provenance.sourceSessionId !== row.session_id
+                    || replacement.provenance.mutationEntryId !== entryIdFromKey(row.mutation_key)) {
+                    warnings.push(`Pin supersession ${mutation.mutationId} has no valid replacement ${mutation.item.id}`);
+                    return;
+                }
+                if (previous.scope !== replacement.scope || !pinMutationMatchesSource(previous, row)) {
+                    warnings.push(`Pin supersession ${mutation.mutationId} crosses its source project/session scope`);
+                    return;
+                }
                 previous.status = "superseded";
                 previous.supersededBy = mutation.item.id;
                 previous.updatedAt = mutation.createdAt;
@@ -370,6 +634,8 @@ export class MemoryRepository {
         if (mutation.operation === "status")
             return;
         const value = mutation.item;
+        if (value.scope === "project" && row.source_project_enabled === 0)
+            return;
         const existing = pins.get(value.id);
         if (existing) {
             if (existing.content !== value.content || existing.scope !== value.scope) {
@@ -381,10 +647,16 @@ export class MemoryRepository {
             warnings.push(`Project pin ${value.id} has no project path`);
             return;
         }
+        if (value.scope === "project" && value.projectPath !== row.source_project_path) {
+            warnings.push(`Project pin ${value.id} does not match its canonical source project`);
+            return;
+        }
         if (value.scope === "branch" && !value.branchLeafId) {
             warnings.push(`Branch pin ${value.id} has no branch leaf`);
             return;
         }
+        const mutationEntryId = entryIdFromKey(row.mutation_key);
+        const sourceEntryId = value.sourceEntryId ?? mutationEntryId;
         const item = {
             id: value.id,
             scope: value.scope,
@@ -396,13 +668,103 @@ export class MemoryRepository {
             status: "active",
             createdAt: value.createdAt,
             updatedAt: mutation.createdAt,
-            ...(value.sourceEntryId
-                ? { sourceEntryId: value.sourceEntryId }
-                : { sourceEntryId: entryIdFromKey(row.mutation_key) }),
+            sourceEntryId,
             ...(value.sourceFile ? { sourceFile: value.sourceFile } : {}),
+            provenance: {
+                sourceSessionId: row.session_id,
+                sourceSessionFile: row.session_file,
+                mutationEntryId,
+                ...(row.source_parent_entry_id
+                    ? { sourceBranchEntryId: row.source_parent_entry_id }
+                    : {}),
+                sourceEntryIds: [...new Set([sourceEntryId, mutationEntryId])],
+                ...(mutation.operation === "supersede" ? { supersedes: mutation.previousId } : {}),
+                contradicts: [],
+            },
         };
         pins.set(item.id, item);
     }
+    insertMemoryMutations(mutations, ignoreExisting = false) {
+        const insert = this.database.prepare(`
+      INSERT ${ignoreExisting ? "OR IGNORE" : ""} INTO memory_mutations(
+        mutation_key, mutation_id, session_id, created_at, entry_order,
+        source_parent_entry_id, payload_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        const existingIds = ignoreExisting
+            ? new Set(this.database.prepare("SELECT mutation_id FROM memory_mutations WHERE session_id = ?")
+                .all(mutations[0]?.sessionId ?? "")
+                .map((row) => row.mutation_id))
+            : new Set();
+        for (const mutation of mutations) {
+            if (existingIds.has(mutation.mutationId))
+                continue;
+            existingIds.add(mutation.mutationId);
+            insert.run(mutation.mutationKey, mutation.mutationId, mutation.sessionId, mutation.createdAt, mutation.entryOrder, mutation.sourceParentEntryId ?? null, JSON.stringify(mutation.payload));
+        }
+    }
+    insertPinMutations(mutations, ignoreExisting = false) {
+        const insert = this.database.prepare(`
+      INSERT ${ignoreExisting ? "OR IGNORE" : ""} INTO pin_mutations(
+        mutation_key, mutation_id, session_id, created_at, entry_order,
+        source_parent_entry_id, payload_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        const existingIds = ignoreExisting
+            ? new Set(this.database.prepare("SELECT mutation_id FROM pin_mutations WHERE session_id = ?")
+                .all(mutations[0]?.sessionId ?? "")
+                .map((row) => row.mutation_id))
+            : new Set();
+        for (const mutation of mutations) {
+            if (existingIds.has(mutation.mutationId))
+                continue;
+            existingIds.add(mutation.mutationId);
+            insert.run(mutation.mutationKey, mutation.mutationId, mutation.sessionId, mutation.createdAt, mutation.entryOrder, mutation.sourceParentEntryId ?? null, JSON.stringify(mutation.payload));
+        }
+    }
+    writeProjectSourceState(checkpoint) {
+        this.database.prepare(`
+      INSERT INTO project_memory_sessions(
+        project_path, session_id, session_file, header_hash, file_size,
+        file_mtime_ms, checkpoint_offset, checkpoint_hash_start, checkpoint_hash,
+        indexed_records, indexed_mutations, malformed_lines, status, last_error,
+        indexed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_path, session_id) DO UPDATE SET
+        session_file = excluded.session_file,
+        header_hash = excluded.header_hash,
+        file_size = excluded.file_size,
+        file_mtime_ms = excluded.file_mtime_ms,
+        checkpoint_offset = excluded.checkpoint_offset,
+        checkpoint_hash_start = excluded.checkpoint_hash_start,
+        checkpoint_hash = excluded.checkpoint_hash,
+        indexed_records = excluded.indexed_records,
+        indexed_mutations = excluded.indexed_mutations,
+        malformed_lines = excluded.malformed_lines,
+        status = excluded.status,
+        last_error = excluded.last_error,
+        indexed_at = excluded.indexed_at
+    `).run(checkpoint.projectPath, checkpoint.sessionId, checkpoint.sessionFile, checkpoint.headerHash, checkpoint.fileSize, checkpoint.fileMtimeMs, checkpoint.checkpointOffset, checkpoint.checkpointHashStart, checkpoint.checkpointHash ?? null, checkpoint.indexedRecords, checkpoint.indexedMutations, checkpoint.malformedLines, checkpoint.status, checkpoint.lastError ?? null, checkpoint.indexedAt);
+    }
+    mapProjectSourceCheckpoint(row) {
+        return {
+            projectPath: row.project_path,
+            sessionId: row.session_id,
+            sessionFile: row.session_file,
+            headerHash: row.header_hash,
+            fileSize: row.file_size,
+            fileMtimeMs: row.file_mtime_ms,
+            checkpointOffset: row.checkpoint_offset,
+            checkpointHashStart: row.checkpoint_hash_start,
+            ...(row.checkpoint_hash ? { checkpointHash: row.checkpoint_hash } : {}),
+            indexedRecords: row.indexed_records,
+            indexedMutations: row.indexed_mutations,
+            malformedLines: row.malformed_lines,
+            status: row.status,
+            ...(row.last_error ? { lastError: row.last_error } : {}),
+            indexedAt: row.indexed_at,
+        };
+    }
     memorySourceIds(memoryId) {
         return this.memorySources(new Set([memoryId])).get(memoryId) ?? [];
     }