@framers/agentos 0.10.10 → 0.10.12

package/dist/cognition/memory/retrieval/store/MemoryStore.js

@@ -144,6 +144,205 @@ function blobToEmbedding(blob) {
         return null;
     return Array.from(new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4));
 }
+const WeakRefImplementation = typeof WeakRef === 'function' ? WeakRef : undefined;
+const FinalizationRegistryImplementation = typeof FinalizationRegistry === 'function' ? FinalizationRegistry : undefined;
+function createReference(target) {
+    if (WeakRefImplementation)
+        return new WeakRefImplementation(target);
+    // Compatibility fallback for runtimes without WeakRef. MemoryStore.dispose
+    // deterministically removes the strong registration.
+    return { deref: () => target };
+}
+const namespaceCoordinators = new WeakMap();
+const vectorStoreNamespaces = new WeakMap();
+function getNamespaceCoordinator(namespace) {
+    let coordinator = namespaceCoordinators.get(namespace);
+    if (!coordinator) {
+        coordinator = {
+            deleteEpoch: 0,
+            pendingOperations: 0,
+            operations: new Map(),
+            stores: new Set(),
+        };
+        namespaceCoordinators.set(namespace, coordinator);
+    }
+    return coordinator;
+}
+function compactNamespaceCoordinator(namespace, coordinator) {
+    for (const reference of coordinator.stores) {
+        if (!reference.deref())
+            coordinator.stores.delete(reference);
+    }
+    if (coordinator.stores.size === 0 &&
+        coordinator.pendingOperations === 0 &&
+        coordinator.operations.size === 0 &&
+        namespaceCoordinators.get(namespace) === coordinator) {
+        namespaceCoordinators.delete(namespace);
+    }
+}
+const storeFinalizer = FinalizationRegistryImplementation
+    ? new FinalizationRegistryImplementation((registration) => {
+        const coordinator = namespaceCoordinators.get(registration.namespace);
+        if (!coordinator)
+            return;
+        coordinator.stores.delete(registration.reference);
+        compactNamespaceCoordinator(registration.namespace, coordinator);
+    })
+    : null;
+function registerCoordinationTarget(namespace, target) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    const reference = createReference(target);
+    const registration = { namespace, reference };
+    coordinator.stores.add(reference);
+    storeFinalizer?.register(target, registration, reference);
+    return registration;
+}
+function unregisterCoordinationTarget(registration) {
+    storeFinalizer?.unregister(registration.reference);
+    const coordinator = namespaceCoordinators.get(registration.namespace);
+    if (!coordinator)
+        return;
+    coordinator.stores.delete(registration.reference);
+    compactNamespaceCoordinator(registration.namespace, coordinator);
+}
+function vectorStoreNamespace(vectorStore, collectionPrefix) {
+    let namespaces = vectorStoreNamespaces.get(vectorStore);
+    if (!namespaces) {
+        namespaces = new Map();
+        vectorStoreNamespaces.set(vectorStore, namespaces);
+    }
+    let namespace = namespaces.get(collectionPrefix);
+    if (!namespace) {
+        namespace = {};
+        namespaces.set(collectionPrefix, namespace);
+    }
+    return namespace;
+}
+function markTraceDeleted(namespace, traceId, authoritative = true) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target)
+            target.markDeleted(traceId, authoritative);
+        else
+            coordinator.stores.delete(reference);
+    }
+}
+function releaseDeleteAuthority(namespace, traceId) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target)
+            target.releaseDeleteAuthority(traceId);
+        else
+            coordinator.stores.delete(reference);
+    }
+}
+async function evictDeletedTrace(namespace, traceId, fallback, requiredTarget) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    const targets = new Set();
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target)
+            targets.add(target);
+        else
+            coordinator.stores.delete(reference);
+    }
+    if (requiredTarget)
+        targets.add(requiredTarget);
+    const outcomes = await Promise.all([...targets].map((target) => target.evictDeleted(traceId, fallback)));
+    return outcomes.every(Boolean);
+}
+function hasDeletedTrace(namespace, traceId) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target?.isDeleted(traceId))
+            return true;
+        if (!target)
+            coordinator.stores.delete(reference);
+    }
+    return false;
+}
+function hasAuthoritativeDelete(namespace, traceId) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target?.isDeleteAuthoritative(traceId))
+            return true;
+        if (!target)
+            coordinator.stores.delete(reference);
+    }
+    return false;
+}
+async function reviveTrace(namespace, trace, embedding, source, sourceAlreadyWritten = true) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    const targets = [];
+    for (const reference of coordinator.stores) {
+        const target = reference.deref();
+        if (target)
+            targets.push(target);
+        else
+            coordinator.stores.delete(reference);
+    }
+    // Fan-out is intentionally limited to deletion-to-active transitions.
+    // General active-update cache coherence has different latency and provider
+    // cost semantics and remains outside this deletion-safety coordinator.
+    if (!targets.some((target) => target.isDeleted(trace.id))) {
+        return source.revive(trace, embedding, sourceAlreadyWritten);
+    }
+    const outcomes = await Promise.all(targets.map((target) => target.revive(trace, embedding, sourceAlreadyWritten && target === source)));
+    return outcomes.every(Boolean);
+}
+function getDeleteEpoch(namespace) {
+    return getNamespaceCoordinator(namespace).deleteEpoch;
+}
+function isTraceDeletePending(namespace, traceId) {
+    const coordinator = namespaceCoordinators.get(namespace);
+    return (coordinator?.operations.get(traceId)?.pendingDeletes ?? 0) > 0;
+}
+async function withTraceOperation(namespace, traceId, kind, operation) {
+    const coordinator = getNamespaceCoordinator(namespace);
+    let state = coordinator.operations.get(traceId);
+    if (!state) {
+        state = { tail: Promise.resolve(), pending: 0, pendingDeletes: 0 };
+        coordinator.operations.set(traceId, state);
+    }
+    const operationState = state;
+    const blockedByDelete = kind === 'normal' && operationState.pendingDeletes > 0;
+    if (kind === 'delete') {
+        operationState.pendingDeletes += 1;
+        coordinator.deleteEpoch += 1;
+        markTraceDeleted(namespace, traceId);
+    }
+    const previous = operationState.tail;
+    let release;
+    const completion = new Promise((resolve) => {
+        release = resolve;
+    });
+    operationState.tail = previous.then(() => completion, () => completion);
+    operationState.pending += 1;
+    coordinator.pendingOperations += 1;
+    await previous.catch(() => undefined);
+    try {
+        return await operation({
+            blockedByDelete,
+            isDeletePending: () => kind === 'normal' && operationState.pendingDeletes > 0,
+        });
+    }
+    finally {
+        if (kind === 'delete')
+            operationState.pendingDeletes -= 1;
+        operationState.pending -= 1;
+        coordinator.pendingOperations -= 1;
+        release?.();
+        if (operationState.pending === 0 &&
+            coordinator.operations.get(traceId) === operationState) {
+            coordinator.operations.delete(traceId);
+        }
+        compactNamespaceCoordinator(namespace, coordinator);
+    }
+}
 // ---------------------------------------------------------------------------
 // MemoryStore
 // ---------------------------------------------------------------------------
@@ -155,6 +354,8 @@ export class MemoryStore {
         this.embeddingCache = new Map();
         /** Process-local deletion barrier for asynchronous vector refreshes and hydration. */
         this.tombstonedTraceIds = new Set();
+        /** Tombstones whose local delete has not been durably confirmed. */
+        this.authoritativeTombstoneIds = new Set();
         /** Track concrete scopes we have seen, so retrieval never falls back to a fake wildcard scope. */
         this.knownScopes = new Map();
         /**
@@ -166,19 +367,52 @@ export class MemoryStore {
         this.brain = null;
         /** Whether {@link MemoryStore.ensureHydratedFromBrain} has already run for this instance. */
         this.brainHydrated = false;
+        this.disposed = false;
+        /** Brain attachment is immutable once any memory operation has started. */
+        this.brainAttachmentLocked = false;
         this.config = config;
         this.decay = config.decayConfig ?? DEFAULT_DECAY_CONFIG;
         this.mechanismsEngine = config.mechanismsEngine;
+        this.coordinationTarget = {
+            isDeleted: (traceId) => this.tombstonedTraceIds.has(traceId),
+            isDeleteAuthoritative: (traceId) => this.authoritativeTombstoneIds.has(traceId),
+            markDeleted: (traceId, authoritative) => this.markDeletedLocally(traceId, authoritative),
+            releaseDeleteAuthority: (traceId) => this.authoritativeTombstoneIds.delete(traceId),
+            evictDeleted: (traceId, fallback) => this.evictDeletedLocally(traceId, fallback),
+            revive: (trace, embedding, source) => this.reviveLocally(trace, embedding, source),
+        };
+        this.coordinationNamespace = vectorStoreNamespace(config.vectorStore, config.collectionPrefix);
+        this.coordinationRegistration = registerCoordinationTarget(this.coordinationNamespace, this.coordinationTarget);
     }
     /**
      * Attach a Brain for durable write-through persistence.
      * Once attached, all store/softDelete/recordAccess operations also
-     * write to the brain's `memory_traces` table.
+     * write to the brain's `memory_traces` table. Initial attachment must happen
+     * before any memory operation; after that, only another handle with the same
+     * coordination token can be supplied.
      *
      * @param brain - Brain instance (already initialized with schema)
+     * @throws When attachment is late or would switch backing resources.
      */
     setBrain(brain) {
+        this.assertNotDisposed();
+        if (this.brain) {
+            if (this.brain.coordinationToken !== brain.coordinationToken) {
+                throw new Error('MemoryStore.setBrain: cannot switch to a different backing resource');
+            }
+            this.brain = brain;
+            return;
+        }
+        if (this.brainAttachmentLocked) {
+            throw new Error('MemoryStore.setBrain: attach a Brain before starting memory operations');
+        }
+        const previousRegistration = this.coordinationRegistration;
         this.brain = brain;
+        this.coordinationNamespace = brain.coordinationToken;
+        this.coordinationRegistration = registerCoordinationTarget(this.coordinationNamespace, this.coordinationTarget);
+        if (previousRegistration) {
+            unregisterCoordinationTarget(previousRegistration);
+        }
     }
     /**
      * Access the attached Brain for export/import operations.
@@ -187,6 +421,190 @@ export class MemoryStore {
     getBrain() {
         return this.brain;
     }
+    /**
+     * Remove this store from sibling coordination. Recall and mutation methods
+     * reject after disposal; diagnostic cache accessors remain available.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        if (this.coordinationRegistration) {
+            unregisterCoordinationTarget(this.coordinationRegistration);
+            this.coordinationRegistration = null;
+        }
+        this.disposed = true;
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new Error('MemoryStore: operation attempted after dispose');
+        }
+    }
+    beginOperation() {
+        this.assertNotDisposed();
+        this.brainAttachmentLocked = true;
+    }
+    markDeletedLocally(traceId, authoritative = true) {
+        // Passive sibling coordination is still resource-specific state. Once it
+        // arrives, this store cannot safely migrate that state to another Brain.
+        this.brainAttachmentLocked = true;
+        this.tombstonedTraceIds.add(traceId);
+        if (authoritative)
+            this.authoritativeTombstoneIds.add(traceId);
+        this.embeddingCache.delete(traceId);
+        const trace = this.traceCache.get(traceId);
+        if (trace) {
+            trace.isActive = false;
+            trace.updatedAt = Date.now();
+        }
+    }
+    async evictDeletedLocally(traceId, fallback) {
+        this.markDeletedLocally(traceId, false);
+        const trace = this.traceCache.get(traceId) ?? fallback;
+        this.embeddingCache.delete(traceId);
+        if (!trace)
+            return true;
+        const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
+        try {
+            const result = await this.config.vectorStore.delete(collection, [traceId]);
+            return (result.failedCount ?? 0) === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async reviveLocally(trace, embedding, source) {
+        this.brainAttachmentLocked = true;
+        if (source) {
+            const cached = this.traceCache.get(trace.id);
+            if (cached)
+                cached.isActive = true;
+            this.tombstonedTraceIds.delete(trace.id);
+            this.authoritativeTombstoneIds.delete(trace.id);
+            return true;
+        }
+        const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
+        try {
+            const result = await this.config.vectorStore.upsert(collection, [{
+                    id: trace.id,
+                    textContent: trace.content,
+                    embedding,
+                    metadata: traceToMetadata(trace),
+                }]);
+            if ((result?.failedCount ?? 0) > 0)
+                return false;
+            const revivedTrace = {
+                ...trace,
+                entities: [...trace.entities],
+                tags: [...trace.tags],
+                provenance: { ...trace.provenance },
+                emotionalContext: { ...trace.emotionalContext },
+                associatedTraceIds: [...trace.associatedTraceIds],
+            };
+            this.traceCache.set(trace.id, revivedTrace);
+            this.embeddingCache.set(trace.id, [...embedding]);
+            this.registerScope(trace.scope, trace.scopeId);
+            this.tombstonedTraceIds.delete(trace.id);
+            this.authoritativeTombstoneIds.delete(trace.id);
+            return true;
+        }
+        catch {
+            // Keep the sibling tombstone when its vector index cannot be revived.
+            return false;
+        }
+    }
+    async getDurableTraceRows(traceIds, brain = this.brain) {
+        const rowsById = new Map();
+        if (!brain || traceIds.length === 0)
+            return { ok: true, rows: rowsById };
+        try {
+            const uniqueIds = [...new Set(traceIds)];
+            for (let offset = 0; offset < uniqueIds.length; offset += 400) {
+                const chunk = uniqueIds.slice(offset, offset + 400);
+                const placeholders = chunk.map(() => '?').join(', ');
+                const rows = await brain.all(`SELECT id, type, scope, content, embedding, strength, created_at,
+                  last_accessed, retrieval_count, tags, emotions, metadata, deleted
+             FROM memory_traces
+            WHERE brain_id = ? AND id IN (${placeholders})`, [brain.brainId, ...chunk]);
+                for (const row of rows)
+                    rowsById.set(row.id, row);
+            }
+            return { ok: true, rows: rowsById };
+        }
+        catch {
+            return { ok: false, rows: new Map() };
+        }
+    }
+    async reconcileDurableTraceStates(traceIds, namespace, brain) {
+        if (!brain || traceIds.length === 0)
+            return true;
+        const initial = await this.getDurableTraceRows(traceIds, brain);
+        if (!initial.ok)
+            return false;
+        let validationAvailable = true;
+        const stateChanges = new Set();
+        for (const traceId of new Set(traceIds)) {
+            const row = initial.rows.get(traceId);
+            if (!row || row.deleted === 1 || hasDeletedTrace(namespace, traceId)) {
+                stateChanges.add(traceId);
+            }
+        }
+        await Promise.all([...stateChanges].map((traceId) => withTraceOperation(namespace, traceId, 'normal', async ({ blockedByDelete }) => {
+            if (blockedByDelete)
+                return;
+            const confirmed = await this.getDurableTraceRows([traceId], brain);
+            if (!confirmed.ok) {
+                validationAvailable = false;
+                return;
+            }
+            const row = confirmed.rows.get(traceId);
+            if (!row) {
+                // Once a Brain is attached, provider-only documents are
+                // unvalidated. Re-read while holding the per-trace queue before
+                // fencing so a concurrent store cannot publish its durable row
+                // between validation and this local tombstone.
+                markTraceDeleted(namespace, traceId, false);
+                return;
+            }
+            const trace = this.rowToTrace(row);
+            if (row.deleted === 1) {
+                markTraceDeleted(namespace, row.id, false);
+                releaseDeleteAuthority(namespace, row.id);
+                // Cross-process validation is deliberately non-destructive.
+                // A concurrent revival can write its new vector before its
+                // active SQL row; deleting here based on the older tombstone
+                // would erase that fresh vector. Explicit softDelete/retry owns
+                // provider cleanup, while this durable fence blocks recall.
+                return;
+            }
+            if (!hasDeletedTrace(namespace, row.id) ||
+                hasAuthoritativeDelete(namespace, row.id)) {
+                return;
+            }
+            const embedding = blobToEmbedding(row.embedding);
+            if (!embedding || !isUsableEmbedding(embedding))
+                return;
+            await reviveTrace(namespace, trace, embedding, this.coordinationTarget, false);
+        })));
+        return validationAvailable;
+    }
+    /**
+     * Return the subset of cached trace IDs that remain recallable after a
+     * fail-closed durable-state check. Used by non-vector recall paths such as
+     * graph association injection so a tombstone cannot bypass vector filters.
+     */
+    async filterRecallableTraceIds(traceIds) {
+        this.beginOperation();
+        const uniqueIds = [...new Set(traceIds)];
+        const validated = await this.reconcileDurableTraceStates(uniqueIds, this.coordinationNamespace, this.brain);
+        if (!validated)
+            return new Set();
+        return new Set(uniqueIds.filter((traceId) => {
+            const trace = this.traceCache.get(traceId);
+            return Boolean(trace?.isActive &&
+                !this.tombstonedTraceIds.has(traceId) &&
+                !isTraceDeletePending(this.coordinationNamespace, traceId));
+        }));
+    }
     /**
      * Hydrate the in-memory vector store + scope registry from the attached
      * Brain on first use. The Brain is the durable backing store, but the vector
@@ -197,59 +615,81 @@ export class MemoryStore {
      * best-effort: a SQL/schema error must never break the query path.
      */
     async ensureHydratedFromBrain() {
-        if (this.brainHydrated || !this.brain)
+        if (this.brainHydrated)
+            return;
+        const brain = this.brain;
+        if (!brain)
             return;
         this.brainHydrated = true; // set first: a failure must not retry on every query
+        const namespace = this.coordinationNamespace;
+        const hydrationDeleteEpoch = getDeleteEpoch(namespace);
         try {
             // Bound the per-instance load: a fresh facade (and on request-scoped
             // hosts, every request) hydrates, so we cap at the most-recent traces to
             // keep the SQL read + vector upserts bounded for very long-lived scopes.
             // A process-level facade cache (so hydration runs once, not per request)
             // is the follow-up optimisation; the cap keeps the un-cached path safe.
-            const rows = await this.brain.all(`SELECT id, type, scope, content, embedding, strength, created_at,
+            const rows = await brain.all(`SELECT id, type, scope, content, embedding, strength, created_at,
                 last_accessed, retrieval_count, tags, emotions, metadata
            FROM memory_traces
           WHERE brain_id = ? AND deleted = 0
           ORDER BY created_at DESC
-          LIMIT ?`, [this.brain.brainId, MemoryStore.HYDRATION_LIMIT]);
+          LIMIT ?`, [brain.brainId, MemoryStore.HYDRATION_LIMIT]);
             for (const row of rows) {
-                if (this.tombstonedTraceIds.has(row.id) || this.traceCache.has(row.id))
-                    continue;
-                const embedding = blobToEmbedding(row.embedding);
-                // Legacy rows (persisted before durable embeddings) stored null and are
-                // skipped — they become recallable once re-mentioned + re-stored.
-                if (embedding == null || !isUsableEmbedding(embedding))
-                    continue;
-                const trace = this.rowToTrace(row);
-                const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
-                try {
-                    const exists = this.config.vectorStore.collectionExists
-                        ? await this.config.vectorStore.collectionExists(collection)
-                        : true;
-                    if (!exists) {
-                        await this.config.vectorStore.createCollection?.(collection, this.config.embeddingDimension ?? embedding.length, { overwriteIfExists: false });
+                await withTraceOperation(namespace, row.id, 'normal', async ({ blockedByDelete, isDeletePending }) => {
+                    if (blockedByDelete ||
+                        this.tombstonedTraceIds.has(row.id) ||
+                        this.traceCache.has(row.id)) {
+                        return;
                     }
-                }
-                catch {
-                    // Provider auto-creates the collection or does not expose existence checks.
-                }
-                if (this.tombstonedTraceIds.has(row.id))
-                    continue;
-                await this.config.vectorStore.upsert(collection, [
-                    { id: trace.id, textContent: trace.content, embedding, metadata: traceToMetadata(trace) },
-                ]);
-                if (this.tombstonedTraceIds.has(row.id)) {
+                    // A delete may finish after the bulk SELECT but before this row's
+                    // operation slot. Recheck only when deletion activity occurred.
+                    if (getDeleteEpoch(namespace) !== hydrationDeleteEpoch) {
+                        const stillActive = await brain.get('SELECT id FROM memory_traces WHERE brain_id = ? AND id = ? AND deleted = 0', [brain.brainId, row.id]);
+                        if (!stillActive)
+                            return;
+                    }
+                    const embedding = blobToEmbedding(row.embedding);
+                    // Legacy rows persisted without embeddings become recallable once
+                    // they are mentioned and stored again.
+                    if (embedding == null || !isUsableEmbedding(embedding))
+                        return;
+                    const trace = this.rowToTrace(row);
+                    const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
                     try {
-                        await this.config.vectorStore.delete(collection, [row.id]);
+                        const exists = this.config.vectorStore.collectionExists
+                            ? await this.config.vectorStore.collectionExists(collection)
+                            : true;
+                        if (!exists) {
+                            await this.config.vectorStore.createCollection?.(collection, this.config.embeddingDimension ?? embedding.length, { overwriteIfExists: false });
+                        }
                     }
                     catch {
-                        // Query and getByScope also enforce the process-local tombstone.
+                        // Provider auto-creates the collection or omits existence checks.
                     }
-                    continue;
-                }
-                this.traceCache.set(trace.id, trace);
-                this.embeddingCache.set(trace.id, embedding);
-                this.registerScope(trace.scope, trace.scopeId);
+                    const upsertResult = await this.config.vectorStore.upsert(collection, [
+                        {
+                            id: trace.id,
+                            textContent: trace.content,
+                            embedding,
+                            metadata: traceToMetadata(trace),
+                        },
+                    ]);
+                    if ((upsertResult?.failedCount ?? 0) > 0)
+                        return;
+                    if (isDeletePending() || this.tombstonedTraceIds.has(row.id)) {
+                        try {
+                            await this.config.vectorStore.delete(collection, [row.id]);
+                        }
+                        catch {
+                            // The queued delete retries after this operation releases.
+                        }
+                        return;
+                    }
+                    this.traceCache.set(trace.id, trace);
+                    this.embeddingCache.set(trace.id, embedding);
+                    this.registerScope(trace.scope, trace.scopeId);
+                });
             }
         }
         catch {
@@ -304,6 +744,29 @@ export class MemoryStore {
      * and record as episodic memory in the knowledge graph.
      */
     async store(trace) {
+        this.beginOperation();
+        const namespace = this.coordinationNamespace;
+        const brain = this.brain;
+        await withTraceOperation(namespace, trace.id, 'normal', async ({ blockedByDelete, isDeletePending }) => {
+            if (blockedByDelete) {
+                throw new Error('MemoryStore.store: trace deletion is already in progress');
+            }
+            const embedding = await this.storeWithTraceLock(trace, brain, namespace);
+            if (!isDeletePending()) {
+                await reviveTrace(namespace, trace, embedding, this.coordinationTarget);
+            }
+        });
+    }
+    async storeWithTraceLock(trace, brain, namespace) {
+        // Calling store with an existing ID is the explicit revival operation.
+        // Build active metadata without mutating a caller-provided cached
+        // tombstone until the vector provider has accepted the write.
+        const activeUpdatedAt = Date.now();
+        const activeTrace = {
+            ...trace,
+            isActive: true,
+            updatedAt: activeUpdatedAt,
+        };
         const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
         // Generate embedding
         const embeddingResponse = await this.config.embeddingManager.generateEmbeddings({
@@ -332,9 +795,59 @@ export class MemoryStore {
             id: trace.id,
             textContent: trace.content,
             embedding,
-            metadata: traceToMetadata(trace),
+            metadata: traceToMetadata(activeTrace),
         };
-        await this.config.vectorStore.upsert(collection, [doc]);
+        const upsertResult = await this.config.vectorStore.upsert(collection, [doc]);
+        if ((upsertResult?.failedCount ?? 0) > 0) {
+            throw new Error(`MemoryStore.store: vector provider rejected trace ${trace.id}; ` +
+                `${upsertResult.failedCount} document write failed`);
+        }
+        // The Brain is authoritative whenever attached. Persist before publishing
+        // the active trace to caches or secondary graph indexes; otherwise a
+        // failed write would look successful locally and then be fenced as a
+        // provider-only document on the next durable recall.
+        if (brain) {
+            try {
+                const { dialect } = brain.features;
+                const result = await brain.run(dialect.insertOrReplace('memory_traces', ['brain_id', 'id', 'type', 'scope', 'content', 'embedding', 'strength', 'created_at', 'last_accessed', 'retrieval_count', 'tags', 'emotions', 'metadata', 'deleted'], ['?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '0'], 'brain_id, id'), [
+                    brain.brainId,
+                    trace.id,
+                    trace.type,
+                    trace.scope,
+                    trace.content,
+                    embeddingToBlob(embedding),
+                    trace.encodingStrength,
+                    trace.createdAt,
+                    trace.lastAccessedAt,
+                    trace.retrievalCount,
+                    JSON.stringify(trace.tags),
+                    JSON.stringify(trace.emotionalContext),
+                    JSON.stringify({
+                        scopeId: trace.scopeId,
+                        provenance: trace.provenance,
+                        entities: trace.entities,
+                        stability: trace.stability,
+                        importance: trace.importance,
+                        associatedTraceIds: trace.associatedTraceIds,
+                        structuredData: trace.structuredData,
+                    }),
+                ]);
+                if (result.changes === 0) {
+                    throw new Error('durable write affected no rows');
+                }
+            }
+            catch {
+                trace.isActive = false;
+                // The SQL error is ambiguous: another process may already have
+                // committed a successful store for the same trace. Fence this
+                // process non-authoritatively, but do not erase a shared provider
+                // vector that could belong to that successful writer.
+                markTraceDeleted(namespace, trace.id, false);
+                throw new Error('MemoryStore.store: durable trace write failed');
+            }
+        }
+        trace.isActive = true;
+        trace.updatedAt = activeUpdatedAt;
         // Record in knowledge graph as episodic memory. Step 13: thread
         // `trace.entities` through as `entityIds` (slugified for deterministic
         // lookup). Previously hardcoded to `[]`, which silenced the sixth
@@ -375,42 +888,7 @@ export class MemoryStore {
         this.traceCache.set(trace.id, trace);
         this.embeddingCache.set(trace.id, embedding);
         this.registerScope(trace.scope, trace.scopeId);
-        // Re-storing an id is an explicit revival: lift the deletion barrier so
-        // the fresh trace is not filtered out of recall as a stale tombstone.
-        this.tombstonedTraceIds.delete(trace.id);
-        // Write-through to Brain for durability.
-        // The SQL row mirrors the in-memory cache so traces survive restart.
-        if (this.brain) {
-            try {
-                const { dialect } = this.brain.features;
-                await this.brain.run(dialect.insertOrReplace('memory_traces', ['brain_id', 'id', 'type', 'scope', 'content', 'embedding', 'strength', 'created_at', 'last_accessed', 'retrieval_count', 'tags', 'emotions', 'metadata', 'deleted'], ['?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '?', '0'], 'brain_id, id'), [
-                    this.brain.brainId,
-                    trace.id,
-                    trace.type,
-                    trace.scope,
-                    trace.content,
-                    embeddingToBlob(embedding), // durable so recall survives a fresh instance (see ensureHydratedFromBrain)
-                    trace.encodingStrength,
-                    trace.createdAt,
-                    trace.lastAccessedAt,
-                    trace.retrievalCount,
-                    JSON.stringify(trace.tags),
-                    JSON.stringify(trace.emotionalContext),
-                    JSON.stringify({
-                        scopeId: trace.scopeId,
-                        provenance: trace.provenance,
-                        entities: trace.entities,
-                        stability: trace.stability,
-                        importance: trace.importance,
-                        associatedTraceIds: trace.associatedTraceIds,
-                        structuredData: trace.structuredData,
-                    }),
-                ]);
-            }
-            catch {
-                // Write-through is best-effort — in-memory store is primary
-            }
-        }
+        return embedding;
     }
     // =========================================================================
     // Query
@@ -419,8 +897,11 @@ export class MemoryStore {
      * Query memory traces with cognitive scoring.
      */
     async query(queryText, currentMood, options = {}) {
+        this.beginOperation();
         const now = Date.now();
         const topK = options.topK ?? 20;
+        const namespace = this.coordinationNamespace;
+        const brain = this.brain;
         // Cold-start durability: load durable traces from the attached Brain into
         // the in-memory index (+ scope registry) before the first query, so recall
         // survives a fresh MemoryStore instance (e.g. a new request-scoped facade).
@@ -499,6 +980,19 @@ export class MemoryStore {
         // Search across scopes
         const allCandidates = [];
         const vectorSearchStart = Date.now();
+        if (this.tombstonedTraceIds.size > 0) {
+            const localStateAvailable = await this.reconcileDurableTraceStates([...this.tombstonedTraceIds], namespace, brain);
+            if (!localStateAvailable) {
+                return {
+                    scored: [],
+                    partial: [],
+                    timings: {
+                        vectorSearchMs: Date.now() - vectorSearchStart,
+                        scoringMs: 0,
+                    },
+                };
+            }
+        }
         for (const { scope, scopeId } of scopes) {
             const collection = collectionName(this.config.collectionPrefix, scope, scopeId);
             try {
@@ -507,9 +1001,14 @@ export class MemoryStore {
                     filter: metadataFilter,
                     includeMetadata: true,
                 });
+                const durableStateAvailable = await this.reconcileDurableTraceStates(results.documents.map((document) => document.id), namespace, brain);
+                if (!durableStateAvailable)
+                    continue;
                 for (const result of results.documents) {
-                    if (this.tombstonedTraceIds.has(result.id))
+                    if (this.tombstonedTraceIds.has(result.id) ||
+                        isTraceDeletePending(namespace, result.id)) {
                         continue;
+                    }
                     const tracePartial = metadataToTracePartial(result.metadata ?? {});
                     const cached = this.traceCache.get(result.id);
                     const trace = cached ??
@@ -574,13 +1073,16 @@ export class MemoryStore {
             weights: effectiveWeights,
         };
         const scoringStart = Date.now();
-        const scored = scoreAndRankTraces(allCandidates, scoringContext).slice(0, topK);
-        const partial = detectPartiallyRetrieved(allCandidates, now, scoringContext);
+        const activeCandidates = allCandidates.filter((candidate) => candidate.trace.isActive &&
+            !this.tombstonedTraceIds.has(candidate.trace.id) &&
+            !isTraceDeletePending(namespace, candidate.trace.id));
+        const scored = scoreAndRankTraces(activeCandidates, scoringContext).slice(0, topK);
+        const partial = detectPartiallyRetrieved(activeCandidates, now, scoringContext);
         const scoringMs = Date.now() - scoringStart;
         // Cognitive mechanisms: RIF + FOK
         if (this.mechanismsEngine && scored.length > 0) {
             const cutoff = scored[scored.length - 1].retrievalScore;
-            this.mechanismsEngine.onRetrieval(scored, allCandidates, cutoff, []);
+            this.mechanismsEngine.onRetrieval(scored, activeCandidates, cutoff, []);
         }
         return { scored, partial, timings: { vectorSearchMs, scoringMs } };
     }
@@ -592,6 +1094,16 @@ export class MemoryStore {
      * Updates decay parameters via spaced repetition.
      */
     async recordAccess(traceId) {
+        this.beginOperation();
+        const namespace = this.coordinationNamespace;
+        const brain = this.brain;
+        return withTraceOperation(namespace, traceId, 'normal', async ({ blockedByDelete, isDeletePending }) => {
+            if (blockedByDelete)
+                return null;
+            return this.recordAccessWithTraceLock(traceId, isDeletePending, brain);
+        });
+    }
+    async recordAccessWithTraceLock(traceId, isDeletePending, brain) {
         const trace = this.traceCache.get(traceId);
         if (this.tombstonedTraceIds.has(traceId) || !trace?.isActive)
             return null;
@@ -648,7 +1160,7 @@ export class MemoryStore {
         }
         // Deletion can race the asynchronous embedding or vector refresh above.
         // If it won, remove any document the late refresh may have restored.
-        if (!trace.isActive) {
+        if (isDeletePending() || !trace.isActive) {
             try {
                 await this.config.vectorStore.delete(collection, [traceId]);
             }
@@ -659,9 +1171,9 @@ export class MemoryStore {
             return null;
         }
         // Write-through: update access metadata in the durable SQL store
-        if (this.brain) {
+        if (brain) {
             try {
-                await this.brain.run('UPDATE memory_traces SET last_accessed = ?, retrieval_count = ?, strength = ? WHERE brain_id = ? AND id = ? AND deleted = 0', [trace.lastAccessedAt, trace.retrievalCount, trace.encodingStrength, this.brain.brainId, traceId]);
+                await brain.run('UPDATE memory_traces SET last_accessed = ?, retrieval_count = ?, strength = ? WHERE brain_id = ? AND id = ? AND deleted = 0', [trace.lastAccessedAt, trace.retrievalCount, trace.encodingStrength, brain.brainId, traceId]);
             }
             catch {
                 // Best-effort persistence
@@ -683,23 +1195,29 @@ export class MemoryStore {
      * topK) and does not guarantee completeness.
      */
     async getByScope(scope, scopeId, type) {
+        this.beginOperation();
+        const namespace = this.coordinationNamespace;
+        const brain = this.brain;
         await this.ensureHydratedFromBrain();
-        // Return from cache + filter
-        const results = [];
-        for (const trace of this.traceCache.values()) {
-            if (!this.tombstonedTraceIds.has(trace.id) &&
-                trace.isActive &&
-                trace.scope === scope &&
-                trace.scopeId === scopeId) {
-                if (!type || trace.type === type) {
-                    results.push(trace);
-                }
-            }
-        }
+        const collectCachedResults = () => [...this.traceCache.values()].filter((trace) => !this.tombstonedTraceIds.has(trace.id) &&
+            trace.isActive &&
+            trace.scope === scope &&
+            trace.scopeId === scopeId &&
+            (!type || trace.type === type));
+        let results = collectCachedResults();
+        const collection = collectionName(this.config.collectionPrefix, scope, scopeId);
+        const cachedStateAvailable = await this.reconcileDurableTraceStates([
+            ...results.map((trace) => trace.id),
+            ...this.tombstonedTraceIds,
+        ], namespace, brain);
+        if (!cachedStateAvailable)
+            return [];
+        // Reconciliation can revive a trace while waiting behind an in-flight
+        // store. Refresh the snapshot so that revival is visible in this call.
+        results = collectCachedResults();
         // Fallback: if cache is empty for this scope, query the vector store.
         if (results.length === 0) {
             try {
-                const collection = collectionName(this.config.collectionPrefix, scope, scopeId);
                 const dim = this.config.embeddingDimension ?? 1536;
                 const zeroVector = new Array(dim).fill(0);
                 const filter = { isActive: 1 };
@@ -712,9 +1230,14 @@ export class MemoryStore {
                     includeMetadata: true,
                     includeTextContent: true,
                 });
+                const providerStateAvailable = await this.reconcileDurableTraceStates(queryResult.documents.map((document) => document.id), namespace, brain);
+                if (!providerStateAvailable)
+                    return [];
                 for (const doc of queryResult.documents) {
-                    if (this.tombstonedTraceIds.has(doc.id))
+                    if (this.tombstonedTraceIds.has(doc.id) ||
+                        isTraceDeletePending(namespace, doc.id)) {
                         continue;
+                    }
                     if (!doc.metadata)
                         continue;
                     const cached = this.traceCache.get(doc.id);
@@ -745,7 +1268,9 @@ export class MemoryStore {
                 // Vector store query may fail (collection not found, etc.); return empty.
             }
         }
-        return results;
+        return results.filter((trace) => trace.isActive &&
+            !this.tombstonedTraceIds.has(trace.id) &&
+            !isTraceDeletePending(namespace, trace.id));
     }
     /**
      * Re-upsert a trace's metadata to the vector store using the cached
@@ -758,10 +1283,22 @@ export class MemoryStore {
      * not be durably updated.
      */
     async persistTraceMetadata(traceId) {
+        this.beginOperation();
+        const namespace = this.coordinationNamespace;
+        await withTraceOperation(namespace, traceId, 'normal', async ({ blockedByDelete, isDeletePending }) => {
+            if (blockedByDelete)
+                return;
+            await this.persistTraceMetadataWithTraceLock(traceId, isDeletePending);
+        });
+    }
+    async persistTraceMetadataWithTraceLock(traceId, isDeletePending) {
         const trace = this.traceCache.get(traceId);
         const embedding = this.embeddingCache.get(traceId);
-        if (this.tombstonedTraceIds.has(traceId) || !trace || !embedding)
+        if (this.tombstonedTraceIds.has(traceId) ||
+            !trace?.isActive ||
+            !embedding) {
             return;
+        }
         const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
         const doc = {
             id: trace.id,
@@ -771,6 +1308,9 @@ export class MemoryStore {
         };
         try {
             await this.config.vectorStore.upsert(collection, [doc]);
+            if (isDeletePending() || !trace.isActive) {
+                await this.config.vectorStore.delete(collection, [traceId]);
+            }
         }
         catch {
             // Best-effort persistence — the in-memory mutation already
@@ -778,12 +1318,19 @@ export class MemoryStore {
         }
     }
     /**
-     * Soft-delete a trace.
+     * Soft-delete a trace and preserve the local barrier if durable persistence
+     * cannot confirm the tombstone.
+     *
+     * @throws When an attached Brain cannot persist the tombstone or the trace
+     *   has no durable row to update.
      */
     async softDelete(traceId) {
-        // Establish the deletion barrier before any awaited lookup or provider
-        // operation so a concurrent hydration or metadata refresh cannot win.
-        this.tombstonedTraceIds.add(traceId);
+        this.beginOperation();
+        const namespace = this.coordinationNamespace;
+        const brain = this.brain;
+        await withTraceOperation(namespace, traceId, 'delete', async () => this.softDeleteWithTraceLock(traceId, namespace, brain));
+    }
+    async softDeleteWithTraceLock(traceId, namespace, brain) {
         let trace = this.traceCache.get(traceId);
         // A caller may delete before the first recall hydrates this process-local
         // cache. Load just the requested row so we can invalidate the correct
@@ -793,12 +1340,12 @@ export class MemoryStore {
         // retry — filtering them out made that failure permanent, because a
         // fresh instance found no row, skipped the vector delete entirely, and
         // the stale document stayed recallable forever.
-        if (!trace && this.brain) {
+        if (!trace && brain) {
             try {
-                const row = await this.brain.get(`SELECT id, type, scope, content, embedding, strength, created_at,
+                const row = await brain.get(`SELECT id, type, scope, content, embedding, strength, created_at,
                   last_accessed, retrieval_count, tags, emotions, metadata, deleted
              FROM memory_traces
-            WHERE brain_id = ? AND id = ?`, [this.brain.brainId, traceId]);
+            WHERE brain_id = ? AND id = ?`, [brain.brainId, traceId]);
                 if (row) {
                     trace = this.rowToTrace(row);
                     // A tombstoned row is loaded solely to name the collection for
@@ -821,38 +1368,36 @@ export class MemoryStore {
             trace.isActive = false;
             trace.updatedAt = Date.now();
         }
-        // Write-through: mark trace as deleted in the durable SQL store
-        if (this.brain) {
+        // Write-through: mark trace as deleted in the durable SQL store. Keep the
+        // local delete authoritative until this succeeds so a transient SQL error
+        // cannot be misread as an external revival on the next recall.
+        let durableDeleteError = false;
+        if (brain) {
             try {
-                await this.brain.run('UPDATE memory_traces SET deleted = 1 WHERE brain_id = ? AND id = ?', [this.brain.brainId, traceId]);
+                const result = await brain.run('UPDATE memory_traces SET deleted = 1 WHERE brain_id = ? AND id = ?', [brain.brainId, traceId]);
+                if (result.changes > 0) {
+                    releaseDeleteAuthority(namespace, traceId);
+                }
+                else {
+                    durableDeleteError = true;
+                }
             }
             catch {
-                // Best-effort persistence
+                durableDeleteError = true;
             }
         }
-        // The vector store is a derived recall index, so removing this document
-        // preserves soft-delete semantics while preventing stale same-process
-        // recall. The durable Brain row remains as the tombstone source of truth.
-        if (trace) {
-            const collection = collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId);
-            let evicted = false;
-            try {
-                const result = await this.config.vectorStore.delete(collection, [traceId]);
-                // Providers like Qdrant report failures through the result instead of
-                // throwing; a reported failure leaves the document live in the shared
-                // index, where a fresh process (whose caches carry no tombstone) would
-                // recall it as active. The durable tombstone keeps this retryable via
-                // the lookup above.
-                evicted = (result.failedCount ?? 0) === 0;
-            }
-            catch {
-                // Query and getByScope also reject cached tombstones defensively.
-            }
-            if (!evicted) {
-                console.warn(`[MemoryStore] vector eviction incomplete for trace ${traceId} in ${collection}; ` +
-                    'the soft-deleted document may persist in a shared index until softDelete is retried');
-            }
-            this.embeddingCache.delete(traceId);
+        // Every live store attached to this backing resource owns an independent
+        // hot vector index. Evict all of them before the delete operation resolves.
+        const evicted = await evictDeletedTrace(namespace, traceId, trace, this.coordinationTarget);
+        if (!evicted) {
+            const location = trace
+                ? collectionName(this.config.collectionPrefix, trace.scope, trace.scopeId)
+                : 'an unresolved collection';
+            console.warn(`[MemoryStore] vector eviction incomplete for trace ${traceId} in ${location}; ` +
+                'the soft-deleted document may persist in a shared index until softDelete is retried');
+        }
+        if (durableDeleteError) {
+            throw new Error('MemoryStore.softDelete: durable tombstone write failed');
         }
     }
     /**