pycontextdb 0.4.0__tar.gz → 0.4.1__tar.gz

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.4.1 — 2026-08-24
+
+- NOOP audit entries now carry the existing memory ID and canonical slot
+  identifiers when a duplicate, explicit target, or unambiguous slot resolves
+  to a current memory. Ambiguous slot-only NOOPs fail closed, while all NOOPs
+  remain content-free and leave the memory version unchanged.
+
 ## 0.4.0 — 2026-08-23
 
 - Explicit deterministic `add` / `update` / `delete` / `noop` memory

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.0
+Version: 0.4.1
 Summary: The unified context layer for AI agents — memory you can act on without treating wishes as facts
 Project-URL: Homepage, https://github.com/atomsai/contextdb
 Project-URL: Documentation, https://contextdb.dev

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/contextdb/__init__.py

@@ -41,7 +41,7 @@ from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
 from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 __all__ = [
     "Clock",

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/contextdb/client.py

@@ -639,13 +639,26 @@ class ContextDB:
                     attribute=attribute,
                 )
                 if self._audit is not None:
+                    details: dict[str, object] = {
+                        "operation": EvolutionOperation.NOOP.value,
+                        "reason": safe_reason,
+                    }
+                    verified_slot = (
+                        canonicalize_slot(
+                            verified.entity_key,
+                            verified.attribute_key,
+                        )
+                        if verified is not None
+                        else None
+                    )
+                    if verified_slot is not None:
+                        details["entity"] = verified_slot.entity
+                        details["attribute"] = verified_slot.attribute
                     await self._audit.log(
                         operation="NOOP",
+                        memory_id=verified.id if verified is not None else None,
                         user_id=uid,
-                        details={
-                            "operation": EvolutionOperation.NOOP.value,
-                            "reason": safe_reason,
-                        },
+                        details=details,
                     )
             token = await store.consistency_token()
             return MemoryEvolutionResult(
@@ -890,12 +903,20 @@ class ContextDB:
             target = await self._evolution_target(
                 target_memory_id,
                 user_id=user_id,
-                require_current=False,
+                require_current=True,
             )
 
         slot = canonicalize_slot(entity, attribute)
-        if slot is not None:
-            if target is not None:
+        has_slot_reference = bool(entity and entity.strip()) and bool(
+            attribute and attribute.strip()
+        )
+        if has_slot_reference and slot is None:
+            raise EvolutionTargetRequiredError(
+                "NOOP entity/attribute must resolve to a slot"
+            )
+
+        if target is not None:
+            if slot is not None:
                 target_slot = canonicalize_slot(
                     target.entity_key,
                     target.attribute_key,
@@ -907,17 +928,27 @@ class ContextDB:
                     raise EvolutionOperationConflictError(
                         "target memory and requested entity/attribute identify different slots"
                     )
-            rows = await self._require_store().list_by_slot(
-                slot.entity,
-                slot.attribute,
-                user_id=user_id,
+            return target
+
+        if slot is None:
+            return None
+
+        rows = await self._require_store().list_by_slot(
+            slot.entity,
+            slot.attribute,
+            user_id=user_id,
+        )
+        current_at = self.clock()
+        current = [row for row in rows if row.is_valid_at(current_at)]
+        if not current:
+            raise EvolutionTargetNotFoundError(
+                f"{slot.entity}/{slot.attribute}"
             )
-            current = [row for row in rows if row.is_valid_at(self.clock())]
-            if not current:
-                raise EvolutionTargetNotFoundError(
-                    f"{slot.entity}/{slot.attribute}"
-                )
-        return target
+        if len(current) != 1:
+            raise EvolutionOperationConflictError(
+                "slot NOOP is ambiguous; pass target_memory_id"
+            )
+        return current[0]
 
     async def _evolve_delete_transactional(
         self,

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/contextdb/dynamics/trust.py

@@ -225,8 +225,11 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 await self._log_noop(
+                    candidate.id,
                     user_id,
                     reason="same_speaker_same_value",
+                    entity=item.entity_key,
+                    attribute=item.attribute_key,
                 )
                 return candidate, "noop"
             speakers.append(incoming_speaker)
@@ -495,7 +498,13 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 reason = "same_speaker_same_value"
-                await self._log_noop(user_id, reason=reason)
+                await self._log_noop(
+                    candidate.id,
+                    user_id,
+                    reason=reason,
+                    entity=slot.entity,
+                    attribute=slot.attribute,
+                )
                 return EvolutionWrite(
                     applied_operation=EvolutionOperation.NOOP,
                     outcome=EvolutionOutcome.NOOP,
@@ -543,7 +552,13 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 reason = "same_speaker_same_value"
-                await self._log_noop(user_id, reason=reason)
+                await self._log_noop(
+                    candidate.id,
+                    user_id,
+                    reason=reason,
+                    entity=slot.entity,
+                    attribute=slot.attribute,
+                )
                 return EvolutionWrite(
                     applied_operation=EvolutionOperation.NOOP,
                     outcome=EvolutionOutcome.NOOP,
@@ -768,17 +783,26 @@ class TrustEngine:
 
     async def _log_noop(
         self,
+        memory_id: str,
         user_id: str | None,
         *,
         reason: str,
+        entity: str | None,
+        attribute: str | None,
     ) -> None:
-        """Append a content-free NOOP audit without touching memory state."""
+        """Append scoped, content-free NOOP lineage without mutating memory."""
         if self.audit is not None:
+            details: dict[str, object] = {
+                "operation": EvolutionOperation.NOOP.value,
+                "reason": reason,
+            }
+            slot = canonicalize_slot(entity, attribute)
+            if slot is not None:
+                details["entity"] = slot.entity
+                details["attribute"] = slot.attribute
             await self.audit.log(
                 operation="NOOP",
+                memory_id=memory_id,
                 user_id=user_id,
-                details={
-                    "operation": EvolutionOperation.NOOP.value,
-                    "reason": reason,
-                },
+                details=details,
             )

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/docs/memory_evolution.md

@@ -33,9 +33,10 @@ canonicalized, and injection-shaped content is demoted.
 
 For an empty slot, ADD stores a new memory. If the same speaker repeats the
 same canonical slot value, the applied operation is NOOP: no row is inserted
-or updated and the memory version does not advance. The audit entry contains
-only the fixed operation and reason. A new independent speaker asserting the
-same value corroborates the current memory and applies as UPDATE.
+or updated and the memory version does not advance. The audit entry points to
+the existing memory and contains only the fixed operation and reason plus its
+canonical entity and attribute identifiers. A new independent speaker
+asserting the same value corroborates the current memory and applies as UPDATE.
 
 ADD fails with `EvolutionOperationConflictError` when the slot already holds a
 different value. Use UPDATE to correct an occupied slot.
@@ -83,9 +84,19 @@ the broader `forget_user()` and `verify_forgotten()` contracts.
 
 ## NOOP
 
-NOOP requires a nonempty reason of at most 256 characters. Optional target or
-slot references are scope-checked. The reason is passed through the configured
-PII processor before the content-free `NOOP` audit entry is appended.
+NOOP requires a nonempty reason of at most 256 characters. An optional
+`target_memory_id` must resolve to a current memory in the caller's scope. A
+slot-only reference resolves only when exactly one current occupant exists;
+an ambiguous contested slot raises `EvolutionOperationConflictError` and
+requires an explicit target. The resolved memory is returned and its ID is
+attached to the audit entry. A NOOP without a target or slot remains valid,
+returns no memory, and has no audit `memory_id`.
+
+The reason is passed through the configured PII processor and bounded to 256
+characters before the content-free `NOOP` audit entry is appended. When a
+memory resolves to a slot, the details include only the operation, processed
+reason, and canonical entity and attribute identifiers. They never include
+memory content, old or new values, raw user IDs, or PII annotation originals.
 
 NOOP does not change memory rows, vectors, or the memory version. Its result
 token therefore reports the same memory version visible before the operation

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycontextdb"
-version = "0.4.0"
+version = "0.4.1"
 description = "The unified context layer for AI agents — memory you can act on without treating wishes as facts"
 readme = "README.md"
 license = "Apache-2.0"

{pycontextdb-0.4.0 → pycontextdb-0.4.1}/tests/unit/test_memory_evolution.py

@@ -181,10 +181,12 @@ async def test_explicit_add_same_speaker_is_true_noop(
     assert [row.id for row in rows_after] == [row.id for row in rows_before]
     assert client.audit is not None
     noop = [entry for entry in await client.audit.get_history() if entry.operation == "NOOP"][-1]
-    assert noop.memory_id is None
+    assert noop.memory_id == first.memory.id
     assert noop.details == {
         "operation": "noop",
         "reason": "same_speaker_same_value",
+        "entity": "profile",
+        "attribute": "color",
     }
 
 
@@ -374,6 +376,174 @@ async def test_target_ids_are_scoped_and_missing_is_indistinguishable(
             )
     assert await client._require_store().get_raw(alice.memory.id) is not None
 
+    version = (await client.consistency_token()).memory_version
+    for target in (alice.memory.id, "missing-memory"):
+        with pytest.raises(EvolutionTargetNotFoundError):
+            await client.factual.evolve(
+                "noop",
+                target_memory_id=target,
+                noop_reason="already checked",
+                user_id="bob",
+            )
+    assert (await client.consistency_token()).memory_version == version
+    assert client.audit is not None
+    assert not [
+        entry
+        for entry in await client.audit.get_history(user_id="bob")
+        if entry.operation == "NOOP"
+    ]
+
+
+async def test_targeted_noop_returns_lineage_without_private_audit_values(
+    client: ContextDB,
+) -> None:
+    raw_content = "The profile color is blue for SSN 123-45-6789"
+    raw_user_id = "alice-private-user"
+    added = await client.factual.evolve(
+        "add",
+        raw_content,
+        source="user_stated",
+        entity="Profile",
+        attribute="Color",
+        user_id=raw_user_id,
+    )
+    assert added.memory is not None
+    assert added.memory.pii_annotations
+    version = added.consistency_token.memory_version
+
+    result = await client.factual.evolve(
+        "noop",
+        target_memory_id=added.memory.id,
+        user_id=raw_user_id,
+        noop_reason="duplicate reported by reviewer@example.com",
+    )
+
+    assert result.memory is not None
+    assert result.memory.id == added.memory.id
+    assert result.consistency_token.memory_version == version
+    assert result.noop_reason == "duplicate reported by [EMAIL]"
+    assert client.audit is not None
+    entry = [
+        entry
+        for entry in await client.audit.get_history(memory_id=added.memory.id)
+        if entry.operation == "NOOP"
+    ][-1]
+    assert entry.memory_id == added.memory.id
+    assert entry.details == {
+        "operation": "noop",
+        "reason": "duplicate reported by [EMAIL]",
+        "entity": "profile",
+        "attribute": "color",
+    }
+    serialized_details = str(entry.details)
+    for private_value in (
+        raw_content,
+        "123-45-6789",
+        "reviewer@example.com",
+        raw_user_id,
+        added.memory.content,
+        added.memory.pii_annotations[0].original,
+    ):
+        assert private_value not in serialized_details
+    assert {"content", "old_value", "new_value", "user_id", "pii_annotations"}.isdisjoint(
+        entry.details
+    )
+
+
+async def test_slot_noop_returns_unambiguous_current_memory(
+    client: ContextDB,
+) -> None:
+    added = await client.factual.evolve(
+        "add",
+        "The user has a peanut allergy",
+        source="user_stated",
+        entity="Customer",
+        attribute="Allergies",
+        user_id="alice",
+    )
+    assert added.memory is not None
+    version = added.consistency_token.memory_version
+
+    result = await client.factual.evolve(
+        "noop",
+        entity="CUSTOMER",
+        attribute="ALLERGIES",
+        user_id="alice",
+        noop_reason="already verified",
+    )
+
+    assert result.memory is not None
+    assert result.memory.id == added.memory.id
+    assert result.consistency_token.memory_version == version
+    assert client.audit is not None
+    entry = [
+        entry
+        for entry in await client.audit.get_history(memory_id=added.memory.id)
+        if entry.operation == "NOOP"
+    ][-1]
+    assert entry.details == {
+        "operation": "noop",
+        "reason": "already verified",
+        "entity": "user",
+        "attribute": "allergy",
+    }
+
+
+async def test_slot_noop_rejects_ambiguous_contested_slot(
+    client: ContextDB,
+) -> None:
+    first = await client.factual.evolve(
+        "add",
+        "The meeting is at 3pm",
+        source="user_stated",
+        entity="meeting",
+        attribute="time",
+        user_id="alice",
+    )
+    assert first.memory is not None
+    other = contextdb.init(
+        config=client.config,
+        session_id="independent-session",
+    )
+    try:
+        contested = await other.factual.evolve(
+            "update",
+            "The meeting is at 4pm",
+            source="user_stated",
+            entity="meeting",
+            attribute="time",
+            user_id="alice",
+        )
+        assert contested.outcome == EvolutionOutcome.CONTESTED
+        version = contested.consistency_token.memory_version
+        assert other.audit is not None
+        noops_before = [
+            entry
+            for entry in await other.audit.get_history(user_id="alice")
+            if entry.operation == "NOOP"
+        ]
+
+        with pytest.raises(EvolutionOperationConflictError, match="ambiguous"):
+            await other.factual.evolve(
+                "noop",
+                entity="meeting",
+                attribute="time",
+                user_id="alice",
+                noop_reason="already handled",
+            )
+
+        assert (await other.consistency_token()).memory_version == version
+        noops_after = [
+            entry
+            for entry in await other.audit.get_history(user_id="alice")
+            if entry.operation == "NOOP"
+        ]
+        assert [entry.id for entry in noops_after] == [
+            entry.id for entry in noops_before
+        ]
+    finally:
+        await other.close()
+
 
 async def test_explicit_noop_is_pii_safe_and_does_not_mutate_store(
     client: ContextDB,
@@ -454,3 +624,16 @@ async def test_existing_add_return_type_and_duplicate_id_are_compatible(
     assert isinstance(duplicate, MemoryItem)
     assert duplicate.id == first.id
     assert (await client.consistency_token()).memory_version == version
+    assert client.audit is not None
+    noop = [
+        entry
+        for entry in await client.audit.get_history(memory_id=first.id)
+        if entry.operation == "NOOP"
+    ][-1]
+    assert noop.memory_id == first.id
+    assert noop.details == {
+        "operation": "noop",
+        "reason": "same_speaker_same_value",
+        "entity": "profile",
+        "attribute": "color",
+    }