feat(context): add ErasureCoordinator for cross-store entity erasure

CHANGELOG.md

@@ -11,6 +11,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`ErasureCoordinator` completes the erasure workflow `purge_node()` only starts — the graph node was removed while the same content survived verbatim in `AgentMemory` and as an embedding** (closes #1018) by @pravit-amp
+  - New `semantica/context/erasure.py`, exporting `ErasureCoordinator` and `ErasureReceipt` from `semantica.context`. `purge_node()`/`purge_edge()` (#957) are graph-scope by design and their changelog entry documents this gap explicitly; the changelog also names GDPR Article 17 as the motivation, and an Article 17 erasure that removes the node while the content stays retrievable by similarity search is not an erasure — it is worse than not offering one, because `purge_node()` returns `True` and writes a tombstone attesting the content is gone
+  - The coordinator **composes** the existing public APIs — nothing in `context_graph.py` or `agent_memory.py` changes behaviorally, and `ContextGraph` keeps its documented graph-scope contract rather than acquiring references to `AgentMemory`/`vector_store` that would invert the dependency
+  - `erase_entity(entity_id, reason=..., at=..., vector_ids=...)` returns an `ErasureReceipt`; `erase_entities([...])` returns one receipt per entity, in order, so one entity's failure does not stop the rest
+  - **Honest partial reporting is the point.** Each store reports one of five statuses — `erased`, `not_found`, `not_configured` (store never bound; normal), `unsupported` (store cannot delete at all; retrying will not help), `failed` — and `receipt.complete` is `False` when any store reports `unsupported`/`failed`, with `receipt.incomplete_stores` naming them. A receipt reading `graph: erased, memory: 14 erased, vectors: unsupported on faiss` is actionable; a bare `True` is a compliance liability
+  - **Erasure runs outward-in: vectors → memory → graph.** The graph tombstone is the durable attestation that an erasure happened, so writing it first would let a crash mid-cascade leave a record claiming more than occurred. Erasing the graph last means a partial failure leaves the node present and the receipt incomplete — recoverable and honest; the reverse is neither
+  - **Partial failure is a result, not an exception**: a store that raises is recorded as `failed` (with the exception type) and the remaining legs still run, rather than aborting into a half-erased state with no record of which half
+  - **The memory sweep cannot be silently truncated.** `find_by_entity(entity_id, limit=10)` returned `results[:limit]`, so the obvious hand-rolled cascade erases the first ten items and reports success — an erasure check computed from a page already truncated by the very `limit` it was called with. The coordinator sweeps in pages until dry (deleting as it goes, so the next page is the remainder) rather than passing one large number that is only correct until someone exceeds it, then **re-queries once after the sweep** and reports `failed` with the residual count if anything survived. It also stops rather than spinning if `batch_delete` reports no progress on a non-empty page. Note `find_by_entity` returns items keyed `memory_id`, not `id`
+  - **`unsupported` vector backends are detected by probing, not by calling and catching.** `faiss_store.py`, `milvus_store.py` and `weaviate_store.py` expose no delete at all (FAISS cannot remove from a flat index without a rebuild), while the `VectorStore` facade declares `delete_vectors()` for *every* backend and only raises `NotImplementedError` once called — so probing the facade alone cannot tell a deletable backend from a delete-less one, and the coordinator looks at the backend it wraps. Probing also keeps a missing method distinguishable from an `AttributeError` raised *inside* a working one, which is exactly where guessing wrong produces a false clean bill of health. `NotImplementedError` at call time is still caught and reported as `unsupported`; a store returning `False` is reported as `failed`
+  - Backends are reached under either supported name — `delete_vectors(ids)` (pinecone/qdrant) or `delete(ids)` (pgvector/sqlite-vec) — and the receipt records which was used
+  - `vector_store` defaults to `memory.vector_store` when a memory is supplied, stays overridable for deployments binding a store the memory does not own, and accepts `False` to disable the vector leg. Vectors owned by memory items are removed by the memory leg's own `delete_memory()` cascade; the explicit vector leg covers entity-keyed embeddings written by something other than `AgentMemory`
+  - The receipt's `erased_at` is normalized through `ContextGraph`'s own temporal normalizer, so the receipt and the tombstone written by the same erasure cannot disagree about when it happened; an unparseable `at` is rejected before any store is touched rather than half way through the cascade
+  - `purge_node()`'s docstring now points at the coordinator, so callers reading the graph-scope caveat find the thing that completes the workflow
+  - New `tests/context/test_erasure_coordinator.py`: 39 tests against **real** `ContextGraph`/`AgentMemory` instances rather than mocks — the bug lives in the interaction between them, so mocking it away would test nothing. Covers the 25-items-on-one-entity regression that fails against a naive single `find_by_entity()` call, all three vector-backend shapes (`delete_vectors`/`delete`/neither) plus the facade-over-delete-less-backend shape, residual/no-progress/no-identifier memory failures, partial failure continuing the cascade, idempotency, receipt serialization, and `at` normalization
+  - Full `tests/context/` suite: 608 passed
+  - **Fixed during review** (Qodo): `erase_entity()` resolved `erased_at` up front but passed the caller's original `at` down to `purge_node()`, so on the default `at=None` path the coordinator and the graph each took their own `now()` and the receipt attested to a different instant than the tombstone it points at — breaking the one invariant this module states most loudly. The resolved timestamp is now passed to the graph. The existing test passed only because it supplied an explicit `at`, which hides the drift; a regression test now covers the `at=None` path that callers actually use
+  - **Fixed during review** (Qodo): the vectors leg treated any return value other than the literal `False` as success, but no in-repo backend returns a bool — Qdrant returns `{"status": <UpdateStatus>}` and Pinecone `{"deleted": True}`, so every dict was read as a success and the backend's own account of the delete was discarded. Delete results are now interpreted by shape (bool, dict with explicit failure markers, `None` for a void method, anything else at face value) and the backend payload is recorded in the receipt as `backend_result`, stringified so the receipt stays JSON-serializable as the audit record it is meant to be. Bool markers are matched by identity so a `0` count is not read as `False`, and string markers match as substrings so an enum rendering as `"UpdateStatus.FAILED"` is not read as a success
+  - **Fixed during review** (Qodo): the constructor's "at least one store" guard used `not vector_store`, rejecting a valid store whose `__bool__`/`__len__` makes an empty instance falsey, and reporting `vector_store=None` in the error when an object had been passed; it now distinguishes `None` (absent) from `False` (deliberately disabled) from any other value (provided), and echoes what it actually received
+  - **Fixed during review** (Qodo): `at` annotations accepted only `str`/`datetime` while the shared `ContextGraph` normalizer they delegate to also takes epoch seconds; widened to `int`/`float` with the docstrings updated, so the coordinator no longer advertises less than the graph API it wraps
+  - **Known limitation, unchanged by this PR**: erasure still cannot be *completed* on FAISS/Milvus/Weaviate — `delete_vectors()` is declared on the `VectorStore` facade (`vector_store.py:786`) but not implemented across the backend set, under at least three different names. That is worth its own issue; the coordinator ships reporting `unsupported` and starts reporting `erased` for those backends once it is fixed, with no API change here
+
 - **First-class CrewAI integration** (#962)
   - New `pip install semantica[crewai]` extra (`crewai>=0.80.0`) — crewai core provides `BaseTool`/`BaseKnowledgeSource`, so `crewai-tools` is intentionally not included, and the extra is intentionally **not** part of the `all` bundle: crewai hard-requires `chromadb~=1.1.0`, which is affected by the unpatched pre-auth code-injection CVE-2026-45829 (see `integrations/crewai/README.md`)
   - `integrations/crewai/SemanticaKGTool` — a CrewAI `BaseTool` exposing 5 KG actions (`extract_entities`, `extract_relations`, `add_to_graph`, `query_graph`, `find_related`) backed by `NERExtractor` / `RelationExtractor` / `ContextGraph`; supports both sync `run()` and async `arun()`

docs/reference/context.md

@@ -25,6 +25,7 @@ icon: "brain"
 | `DecisionRecorder` | Record decisions with embeddings, causal chains, and metadata |
 | `PolicyEngine` | Policy management: `add_policy()`, `check_compliance()`, `get_applicable_policies()` |
 | `CausalChainAnalyzer` | Trace how decisions influenced each other: `get_causal_chain(decision_id)` |
+| `ErasureCoordinator` | Erase an entity across graph, memory, and vector store, returning an auditable `ErasureReceipt` |
 
 
 ## What You Get
@@ -632,6 +633,100 @@ queried together safely. Vector-store writes are deferred until the in-memory im
 commits; adapter synchronization remains best-effort and logs failures.
 
 
+## ErasureCoordinator
+
+`ContextGraph.purge_node()` is scoped to one graph: the node is removed and a
+tombstone is written, but the same content can still be live as an `AgentMemory`
+item and as an embedding in the vector store. `ErasureCoordinator` drives the
+cascade across every bound store and returns an `ErasureReceipt` recording what
+each one reported.
+
+```python
+from semantica.context import AgentMemory, ContextGraph, ErasureCoordinator
+
+coordinator = ErasureCoordinator(graph=graph, memory=memory)
+
+receipt = coordinator.erase_entity(
+    "customer-4471",
+    reason="GDPR Art. 17 request #882",
+)
+
+if not receipt.complete:
+    # These stores may still hold the entity; handle them out of band.
+    print(receipt.incomplete_stores)
+```
+
+<Warning>
+Check the receipt — the call returning is not proof the data is gone. FAISS,
+Milvus, and Weaviate expose no delete method, so erasure cannot be completed on
+those backends today; the receipt reports `unsupported` rather than a success it
+did not achieve.
+</Warning>
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `graph` | `ContextGraph` | `None` | Anything exposing `purge_node()` |
+| `memory` | `AgentMemory` | `None` | Anything exposing `find_by_entity()` and `batch_delete()` |
+| `vector_store` | `VectorStore` | `memory.vector_store` | Store holding entity-keyed embeddings; pass `False` to disable the leg |
+
+At least one store is required; a store that is not supplied reports
+`not_configured` rather than being silently skipped.
+
+### Methods
+
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `erase_entity(entity_id, reason, at, vector_ids)` | `ErasureReceipt` | Erase one entity from every bound store |
+| `erase_entities(entity_ids, reason, at)` | `List[ErasureReceipt]` | One receipt per entity, in order; one failure does not stop the rest |
+
+### Store Statuses
+
+| Status | Meaning |
+| :--- | :--- |
+| `erased` | Reached, data removed. On the vectors leg this means the store accepted the delete for the ids given — backends offer no portable existence check, so it is not a count of embeddings that were really there |
+| `not_found` | Reached, held nothing for this entity |
+| `not_configured` | No such store was bound — normal, not a failure |
+| `unsupported` | The store cannot delete at all; retrying will not help |
+| `failed` | The store was reached and the deletion did not succeed |
+
+### ErasureReceipt
+
+| Member | Type | Description |
+| :--- | :--- | :--- |
+| `entity_id` | `str` | Entity the erasure was requested for |
+| `reason` | `Optional[str]` | Recorded in the receipt and the graph tombstone |
+| `erased_at` | `str` | ISO-8601; matches the tombstone's `purged_at` |
+| `stores` | `Dict[str, Dict]` | Per-store outcome keyed `vectors`, `memory`, `graph` |
+| `complete` | `bool` | `False` when any store reports `unsupported` or `failed` |
+| `incomplete_stores` | `List[str]` | Stores that may still hold the entity's data |
+| `to_dict()` | `Dict` | Serialized receipt, safe to persist as an audit record |
+
+```python
+receipt.to_dict()
+# {
+#   "entity_id": "customer-4471",
+#   "reason": "GDPR Art. 17 request #882",
+#   "erased_at": "2026-08-16T09:03:36.813220",
+#   "complete": False,
+#   "stores": {
+#     "vectors": {"status": "unsupported", "backend": "faiss",
+#                 "detail": "backend exposes no delete()/delete_vectors(); ..."},
+#     "memory":  {"status": "erased", "items": 14},
+#     "graph":   {"status": "erased", "nodes": 1, "edges": 3},
+#   },
+# }
+```
+
+Erasure runs outward-in — vectors, then memory, then the graph. The tombstone is
+the durable attestation that an erasure happened, so it is written last: a crash
+mid-cascade leaves the node present and the receipt incomplete, rather than a
+tombstone claiming more than actually happened. A store that raises is recorded
+as `failed` and the remaining stores are still erased. Erasing the same entity
+twice returns a receipt saying there was nothing left to do rather than raising.
+
+
 ## PolicyEngine
 
 `PolicyEngine` manages versioned policies stored in the knowledge graph. Policies are stored as nodes and can be linked to decisions:

semantica/context/__init__.py

@@ -111,6 +111,7 @@
 from .context_retriever import ContextRetriever, RetrievedContext, TemporalGraphRetriever
 from .decision_context import DecisionContext
 from .entity_linker import EntityLink, EntityLinker, LinkedEntity
+from .erasure import ErasureCoordinator, ErasureReceipt
 
 # Decision tracking imports
 from .decision_models import (
@@ -145,6 +146,9 @@
     "ContextRetriever",
     "RetrievedContext",
     "TemporalGraphRetriever",
+    # Cross-store erasure
+    "ErasureCoordinator",
+    "ErasureReceipt",
     # Decision tracking models
     "Decision",
     "DecisionContextModel", 

semantica/context/context_graph.py

@@ -1731,7 +1731,11 @@ def purge_node(
 
         Scope is this graph only. Copies held elsewhere (``AgentMemory``, a
         bound vector store, an exported file) are not reached, so this is one
-        step of an erasure workflow, not the whole of it.
+        step of an erasure workflow, not the whole of it. Callers who need the
+        whole workflow -- and a receipt recording which stores it actually
+        reached -- should drive this through
+        :class:`~semantica.context.erasure.ErasureCoordinator` rather than
+        treating a ``True`` here as proof the content is gone.
 
         Args:
             node_id: Node to purge.

semantica/context/context_usage.md

@@ -239,6 +239,82 @@ print(f"Python importance score: {importance.get('degree', 0)}")
 
 ---
 
+## 🧹 Erasing an Entity Everywhere - ErasureCoordinator
+
+`purge_node()` removes an entity from **one graph**. The same content can still be
+sitting in agent memory and in your vector store, so purge on its own is one step
+of an erasure workflow rather than the whole of it.
+
+`ErasureCoordinator` drives the whole cascade and hands you a receipt saying what
+it actually managed to erase.
+
+```python
+from semantica.context import AgentMemory, ContextGraph, ErasureCoordinator
+
+coordinator = ErasureCoordinator(graph=knowledge, memory=memory)
+
+receipt = coordinator.erase_entity(
+    "customer-4471",
+    reason="GDPR Art. 17 request #882",
+)
+
+if receipt.complete:
+    print("Erased everywhere")
+else:
+    print("Still holding data:", receipt.incomplete_stores)
+```
+
+### Always Check the Receipt
+
+The receipt is the point of the feature — **do not treat the call itself as proof
+the data is gone**. Each store reports one of five statuses:
+
+| Status | Meaning |
+|---|---|
+| `erased` | Reached, data removed (on the vectors leg: the store accepted the delete for the ids given) |
+| `not_found` | Reached, held nothing for this entity |
+| `not_configured` | No such store was bound — normal, not a failure |
+| `unsupported` | The store cannot delete at all; retrying will not help |
+| `failed` | The store was reached and the deletion did not succeed |
+
+```python
+receipt.to_dict()
+# {
+#   "entity_id": "customer-4471",
+#   "reason": "GDPR Art. 17 request #882",
+#   "erased_at": "2026-08-16T09:03:36.813220",
+#   "complete": False,
+#   "stores": {
+#     "vectors": {"status": "unsupported", "backend": "faiss",
+#                 "detail": "backend exposes no delete()/delete_vectors(); ..."},
+#     "memory":  {"status": "erased", "items": 14},
+#     "graph":   {"status": "erased", "nodes": 1, "edges": 3},
+#   },
+# }
+```
+
+`complete` is `False` when any store reports `unsupported` or `failed`, which is
+your signal to handle that store out of band. FAISS, Milvus and Weaviate expose
+no delete method today, so erasure genuinely cannot be completed on them — the
+coordinator says so rather than reporting a success it did not achieve.
+
+### Good to Know
+
+- **Order is vectors → memory → graph.** The graph tombstone is the durable record
+  that an erasure happened, so it is written last: a crash mid-cascade leaves the
+  node present and the receipt incomplete, rather than a tombstone claiming more
+  than actually happened.
+- **A failing store does not abort the rest.** Partial failure is recorded in the
+  receipt and the remaining stores are still erased.
+- **Every store is optional.** `ErasureCoordinator(graph=graph)` is fine; the other
+  legs report `not_configured`.
+- **It is idempotent.** Erasing the same entity twice returns a receipt saying
+  there was nothing left to do, rather than raising.
+- **Batch:** `coordinator.erase_entities([...], reason=...)` returns one receipt per
+  entity, in order, so one entity's failure does not stop the others.
+
+---
+
 ## 🔄 Using Both Together - The Complete Setup
 
 ### Your Smart Agent System