pycontextdb 0.4.5__tar.gz → 0.4.6__tar.gz

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.4.6 — 2026-10-08
+
+- A lower-trust write no longer replaces a first-party fact in its slot.
+  Writes made under one user id share a speaker, so a third-party document or
+  an agent inference stored for that user superseded what the user had said,
+  and the user would then be asked to confirm the document's value. A
+  user-stated or confirmed fact now stays current and the slot is contested
+  until `confirm()`. Corrections of equal or higher trust still supersede.
+  Advisory: GHSA-vpf9-5xgr-3x8m.
+- `factual.recall_for_action` and `factual.pending_confirmations` accept the
+  `entity` and `attribute` an action needs. With them, only current facts in
+  that slot count, read exactly rather than by similarity, and the read is
+  audited like a recall. Without them nothing changes: any trusted memory the
+  query retrieves counts, whether or not it answers the request.
+- The slot vocabulary (version 2) adds `user/billing_email`, `user/work_phone`,
+  and `user/work_address`. A user's billing email, work phone, or work address
+  no longer replaces their personal one. An email filed as a billing email
+  stays there instead of being moved to `user/email` and stored as
+  `agent_inferred`.
+
 ## 0.4.5 — 2026-10-05
 
 - `forget_user` no longer deletes other users' memories. It added every graph

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.5
+Version: 0.4.6
 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
@@ -118,7 +118,7 @@ Hermetic, reproducible — run the suite yourself: `python benchmarks/run_benchm
 
 Speed is table stakes. The production failure that gets agents fired is **acting on a wish as if it were a fact**: a caller says *"I'd like to come in Thursday"* and the agent answers *"we penciled you in."* A wish and a confirmed fact are the same object in every memory store on the market — so ContextDB types them.
 
-Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
+Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. Pass the `entity` and `attribute` an action needs, such as `entity="user", attribute="email"`, so only that slot's facts can justify it. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
 
 On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that severs graph edges without touching other users' memories, and **tenant/agent isolation enforced at the storage layer**.
 

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/README.md

@@ -52,7 +52,7 @@ Hermetic, reproducible — run the suite yourself: `python benchmarks/run_benchm
 
 Speed is table stakes. The production failure that gets agents fired is **acting on a wish as if it were a fact**: a caller says *"I'd like to come in Thursday"* and the agent answers *"we penciled you in."* A wish and a confirmed fact are the same object in every memory store on the market — so ContextDB types them.
 
-Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
+Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. Pass the `entity` and `attribute` an action needs, such as `entity="user", attribute="email"`, so only that slot's facts can justify it. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
 
 On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that severs graph edges without touching other users' memories, and **tenant/agent isolation enforced at the storage layer**.
 

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/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.5"
+__version__ = "0.4.6"
 
 __all__ = [
     "Clock",

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/contextdb/client.py

@@ -48,7 +48,12 @@ from contextdb.core.models import (
     MemoryType,
 )
 from contextdb.core.policy import TrustPolicy
-from contextdb.core.slots import canonicalize_slot, infer_negation, infer_slot
+from contextdb.core.slots import (
+    canonicalize_slot,
+    infer_negation,
+    infer_slot,
+    slot_supported_by,
+)
 from contextdb.dynamics.trust import TrustEngine, infer_action_relevant, speaker_id
 from contextdb.privacy.injection import screen_injection
 from contextdb.privacy.pii_detector import PIIDetector
@@ -389,7 +394,7 @@ class ContextDB:
         inferred = infer_slot(source_text)
         chosen = explicit or inferred
         if explicit is not None and inferred is not None:
-            if (explicit.entity, explicit.attribute) != (inferred.entity, inferred.attribute):
+            if not slot_supported_by(explicit, inferred):
                 chosen = inferred
                 item.epistemic_source = "agent_inferred"
                 item.confidence = min(item.confidence, 0.4)
@@ -1991,8 +1996,18 @@ class ContextDB:
         self,
         user_id: str | None = None,
         limit: int = 100,
+        *,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
-        """Facts that are action-relevant and do not yet pass the trust policy."""
+        """Facts that are action-relevant and do not yet pass the trust policy.
+
+        With ``entity`` and ``attribute``, only the current facts in that slot.
+        """
+        if entity is not None or attribute is not None:
+            rows = await self.slot_facts(entity, attribute, user_id=user_id)
+            pending = [item for item in rows if self.trust_policy.requires_confirmation(item)]
+            return pending[:limit]
         uid = self._resolve_user(user_id)
         await self._ensure_init()
         store = self._require_store()
@@ -2001,6 +2016,45 @@ class ContextDB:
         )
         return [item for item in rows if self.trust_policy.requires_confirmation(item)]
 
+    async def slot_facts(
+        self,
+        entity: str | None,
+        attribute: str | None,
+        *,
+        user_id: str | None = None,
+        as_of: datetime | None = None,
+    ) -> list[MemoryItem]:
+        """Current facts in one slot, read exactly rather than by similarity.
+
+        A similarity search returns the nearest memories whether or not they
+        answer the request. When the caller knows which slot an action needs,
+        this is the evidence that action may rely on.
+        """
+        slot = canonicalize_slot(entity, attribute)
+        if slot is None:
+            raise ValueError("entity and attribute are both required to name a slot")
+        uid = self._resolve_user(user_id)
+        await self._ensure_init()
+        store = self._require_store()
+        moment = as_of or self.clock()
+        rows = await store.list_by_slot(slot.entity, slot.attribute, user_id=uid)
+        items = sorted(
+            (m for m in rows if m.memory_type == MemoryType.FACTUAL and m.is_valid_at(moment)),
+            key=lambda m: m.write_generation,
+            reverse=True,
+        )
+        audit_details = {
+            "slot": [slot.entity, slot.attribute],
+            "hits": len(items),
+            "returned_ids": [m.id for m in items],
+            "as_of": moment.isoformat(),
+            "abstained": not items,
+        }
+        if self._audit is not None and self.config.enable_read_audit:
+            await self._audit.log(operation="SLOT_READ", user_id=uid, details=audit_details)
+        await self._emit("read_audit", user_id=uid, audit_details=audit_details)
+        return items
+
     # ------------------------------------------------------------------ #
     # Typed memory surfaces
     # ------------------------------------------------------------------ #

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/contextdb/core/slots.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
-SLOT_VOCAB_VERSION = "1"
+SLOT_VOCAB_VERSION = "2"
 
 # Canonical (entity, attribute) → class. The class drives the per-class
 # corroboration bar in :class:`TrustPolicy`.
@@ -31,8 +31,11 @@ SLOT_VOCAB: dict[tuple[str, str], str] = {
     ("reservation", "time"): "booking",
     ("reservation", "day"): "booking",
     ("user", "email"): "contact",
+    ("user", "billing_email"): "contact",
     ("user", "phone"): "contact",
+    ("user", "work_phone"): "contact",
     ("user", "address"): "contact",
+    ("user", "work_address"): "contact",
     ("user", "name"): "identity",
     ("account", "number"): "identity",
     ("account", "pin"): "identity",
@@ -77,6 +80,15 @@ _ATTRIBUTE_ALIASES: dict[str, str] = {
     "mobile": "phone",
     "allergies": "allergy",
     "allergic": "allergy",
+    "invoice_email": "billing_email",
+    "office_phone": "work_phone",
+    "office_address": "work_address",
+}
+
+# Slots the text slotter cannot tell from a broader one: any email address
+# reads as user/email, whether it is personal or where invoices go.
+_REFINES: dict[tuple[str, str], tuple[str, str]] = {
+    ("user", "billing_email"): ("user", "email"),
 }
 
 
@@ -111,6 +123,13 @@ def canonicalize_slot(entity: str | None, attribute: str | None) -> Slot | None:
     return Slot(entity=ent, attribute=attr, slot_class=slot_class)
 
 
+def slot_supported_by(explicit: Slot, inferred: Slot) -> bool:
+    """Whether the slot the text implies is consistent with the one chosen."""
+    chosen = (explicit.entity, explicit.attribute)
+    implied = (inferred.entity, inferred.attribute)
+    return chosen == implied or _REFINES.get(chosen) == implied
+
+
 _WEEKDAYS = (
     "monday",
     "tuesday",

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/contextdb/dynamics/trust.py

@@ -137,6 +137,21 @@ def speaker_id(
     return "anonymous"
 
 
+def _first_party(item: MemoryItem) -> bool:
+    return item.confirmed or item.epistemic_source == "user_stated"
+
+
+def outranks(current: MemoryItem, incoming: MemoryItem) -> bool:
+    """Whether ``incoming`` may not replace ``current`` in a slot.
+
+    Speaker identity alone cannot tell a user's correction from a document
+    the agent stored on the user's behalf: both arrive under the same user.
+    A first-party or confirmed fact is therefore never superseded by a
+    lower-trust write; the slot is contested instead.
+    """
+    return _first_party(current) and not _first_party(incoming)
+
+
 class TrustEngine:
     """Slot-aware write path used by ``factual.add`` and consolidation."""
 
@@ -252,20 +267,27 @@ class TrustEngine:
             )
             return updated, "corroborated"
 
+        protected = [c for c in current if outranks(c, item)]
         same_speaker = [
-            c for c in current if incoming_speaker in (c.corroborated_by or [])
+            c
+            for c in current
+            if c not in protected and incoming_speaker in (c.corroborated_by or [])
         ]
         other_speaker = [
-            c for c in current if incoming_speaker not in (c.corroborated_by or [])
+            c
+            for c in current
+            if c not in protected and incoming_speaker not in (c.corroborated_by or [])
         ]
 
         item.write_generation = max_gen + 1
         # Independent speakers asserting different values: contest, do not
-        # last-write-win. Same-speaker corrections still supersede.
-        if other_speaker and not same_speaker and not item.pending_consolidation:
+        # last-write-win. Same-speaker corrections still supersede, except a
+        # lower-trust write never replaces a first-party fact.
+        contest = protected + ([] if same_speaker else other_speaker)
+        if contest and not item.pending_consolidation:
             item.contested = True
             stored = await self.store.add(item)
-            for candidate in other_speaker:
+            for candidate in contest:
                 await self.store.update(candidate.id, contested=True)
                 await self._log(
                     "CONFLICT",
@@ -278,8 +300,13 @@ class TrustEngine:
                         "old_value": candidate.content,
                         "new_value": stored.content,
                         "speaker": incoming_speaker,
+                        "reason": (
+                            "outranked_source" if candidate in protected else "other_speaker"
+                        ),
                     },
                 )
+            for candidate in [c for c in current if c not in contest]:
+                await self._supersede(candidate, stored, user_id, item, now)
             await self._log(
                 "CREATE",
                 stored.id,
@@ -297,25 +324,9 @@ class TrustEngine:
         for candidate in current:
             if item.pending_consolidation and not candidate.pending_consolidation:
                 continue
-            await self.store.update(
-                candidate.id,
-                valid_until=now,
-                superseded_by=stored.id,
-                contested=False,
-            )
-            await self._log(
-                "SUPERSEDE",
-                candidate.id,
-                user_id,
-                {
-                    "superseded_by": stored.id,
-                    "entity": item.entity_key,
-                    "attribute": item.attribute_key,
-                    "old_value": candidate.content,
-                    "new_value": stored.content,
-                    "generation": item.write_generation,
-                },
-            )
+            if candidate in protected:
+                continue
+            await self._supersede(candidate, stored, user_id, item, now)
             outcome = "superseded"
         await self._log(
             "CREATE",
@@ -325,6 +336,34 @@ class TrustEngine:
         )
         return stored, outcome
 
+    async def _supersede(
+        self,
+        candidate: MemoryItem,
+        stored: MemoryItem,
+        user_id: str | None,
+        item: MemoryItem,
+        now: datetime,
+    ) -> None:
+        await self.store.update(
+            candidate.id,
+            valid_until=now,
+            superseded_by=stored.id,
+            contested=False,
+        )
+        await self._log(
+            "SUPERSEDE",
+            candidate.id,
+            user_id,
+            {
+                "superseded_by": stored.id,
+                "entity": item.entity_key,
+                "attribute": item.attribute_key,
+                "old_value": candidate.content,
+                "new_value": stored.content,
+                "generation": item.write_generation,
+            },
+        )
+
     async def evolve_write(
         self,
         item: MemoryItem,
@@ -591,22 +630,24 @@ class TrustEngine:
                 previous_memory_ids=previous_ids,
             )
 
+        protected = [candidate for candidate in current if outranks(candidate, item)]
         same_speaker = [
             candidate
             for candidate in current
-            if incoming_speaker in candidate.corroborated_by
+            if candidate not in protected and incoming_speaker in candidate.corroborated_by
         ]
         other_speaker = [
             candidate
             for candidate in current
-            if incoming_speaker not in candidate.corroborated_by
+            if candidate not in protected and incoming_speaker not in candidate.corroborated_by
         ]
         item.write_generation = max_generation + 1
 
-        if other_speaker and not same_speaker:
+        contest = protected + ([] if same_speaker else other_speaker)
+        if contest:
             item.contested = True
             stored = await self.store.add(item)
-            for candidate in other_speaker:
+            for candidate in contest:
                 await self.store.update(candidate.id, contested=True)
                 await self._log(
                     "CONFLICT",
@@ -619,8 +660,13 @@ class TrustEngine:
                         "old_value": candidate.content,
                         "new_value": stored.content,
                         "speaker": incoming_speaker,
+                        "reason": (
+                            "outranked_source" if candidate in protected else "other_speaker"
+                        ),
                     },
                 )
+            for candidate in [c for c in current if c not in contest]:
+                await self._supersede(candidate, stored, user_id, item, now)
             await self._log(
                 "CREATE",
                 stored.id,

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/contextdb/memory/factual.py

@@ -166,12 +166,24 @@ class FactualMemory:
         as_of: datetime | None = None,
         *,
         user_id: str | None = None,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
-        """Recall only facts an agent may act on without confirming first."""
+        """Recall only facts an agent may act on without confirming first.
+
+        Without a slot, any trusted memory the query retrieves counts, related
+        or not. Pass the ``entity`` and ``attribute`` the action needs to rely
+        only on trusted facts in that slot.
+        """
         policy = self.client.trust_policy
-        candidates = await self.recall(
-            query, top_k=top_k * 4, as_of=as_of, user_id=self._user(user_id)
-        )
+        if entity is not None or attribute is not None:
+            candidates = await self.client.slot_facts(
+                entity, attribute, user_id=self._user(user_id), as_of=as_of
+            )
+        else:
+            candidates = await self.recall(
+                query, top_k=top_k * 4, as_of=as_of, user_id=self._user(user_id)
+            )
         return [m for m in candidates if policy.is_trusted(m)][:top_k]
 
     async def confirm(self, memory_id: str, user_id: str | None = None) -> MemoryItem:
@@ -182,10 +194,13 @@ class FactualMemory:
         self,
         user_id: str | None = None,
         limit: int = 100,
+        *,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
         """Action-relevant facts that still need a yes from the user."""
         return await self.client.pending_confirmations(
-            user_id=self._user(user_id), limit=limit
+            user_id=self._user(user_id), limit=limit, entity=entity, attribute=attribute
         )
 
     async def update_fact(

{pycontextdb-0.4.5 → pycontextdb-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycontextdb"
-version = "0.4.5"
+version = "0.4.6"
 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.5 → pycontextdb-0.4.6}/tests/evals/test_trust_model.py

@@ -28,7 +28,7 @@ import pytest
 import pytest_asyncio
 
 import contextdb
-from contextdb import ContextDB, ContextDBConfig
+from contextdb import ContextDB, ContextDBConfig, EvolutionOutcome
 from contextdb.core.exceptions import ConfigError
 from contextdb.core.models import MemoryType
 from contextdb.integrations.prompting import (
@@ -1384,3 +1384,207 @@ async def test_eval_pii_query_retrieves_redacted_memory(db: ContextDB) -> None:
     hits = await db.search("please look up jane.doe@example.com")
     assert any("[EMAIL]" in h.content for h in hits), [h.content for h in hits]
     assert all("jane.doe@example.com" not in h.content for h in hits)
+
+
+async def test_eval_lower_trust_write_contests_a_user_stated_slot(db: ContextDB) -> None:
+    """A document stored under the user's id contests their fact; it never replaces it."""
+    mine = await db.factual.add(
+        "The meeting is at 3pm",
+        source="user_stated",
+        confidence=0.9,
+        action_relevant=True,
+        entity="meeting",
+        attribute="time",
+    )
+    planted = await db.factual.add(
+        "Forwarded vendor note: the meeting moved to 4pm",
+        source="third_party",
+        confidence=0.9,
+        action_relevant=True,
+        entity="meeting",
+        attribute="time",
+    )
+    inferred = await db.factual.add(
+        "From that note, the meeting is probably at 5pm",
+        source="agent_inferred",
+        confidence=0.9,
+        action_relevant=True,
+        entity="meeting",
+        attribute="time",
+    )
+    assert planted.contested is True
+    assert inferred.contested is True
+    kept = await db.get(mine.id)
+    assert kept is not None
+    assert kept.valid_until is None
+    assert kept.contested is True
+    assert await db.factual.recall_for_action("when is the meeting") == []
+
+    await db.factual.confirm(mine.id)
+    trusted = await db.factual.recall_for_action("when is the meeting")
+    assert [m.id for m in trusted] == [mine.id]
+    closed = await db.get(inferred.id)
+    assert closed is not None
+    assert closed.superseded_by == mine.id
+
+
+async def test_eval_corrections_of_equal_or_higher_trust_still_supersede(
+    db: ContextDB,
+) -> None:
+    guess = await db.factual.add(
+        "The meeting is at 3pm",
+        source="agent_inferred",
+        confidence=0.9,
+        action_relevant=True,
+        entity="meeting",
+        attribute="time",
+    )
+    stated = await db.factual.add(
+        "Actually, the meeting is at 4pm",
+        source="user_stated",
+        confidence=0.9,
+        action_relevant=True,
+        entity="meeting",
+        attribute="time",
+    )
+    assert stated.contested is False
+    replaced = await db.get(guess.id)
+    assert replaced is not None
+    assert replaced.superseded_by == stated.id
+
+    first = await db.factual.add(
+        "Partner note: party of 4",
+        source="third_party",
+        action_relevant=True,
+        entity="reservation",
+        attribute="party_size",
+    )
+    second = await db.factual.add(
+        "Partner note: party of 6",
+        source="third_party",
+        action_relevant=True,
+        entity="reservation",
+        attribute="party_size",
+    )
+    assert second.contested is False
+    older = await db.get(first.id)
+    assert older is not None
+    assert older.superseded_by == second.id
+
+
+async def test_eval_explicit_update_from_a_document_contests_a_user_fact(
+    db: ContextDB,
+) -> None:
+    added = await db.factual.evolve(
+        "add",
+        "The meeting is at 3pm",
+        source="user_stated",
+        entity="meeting",
+        attribute="time",
+    )
+    assert added.memory is not None
+    update = await db.factual.evolve(
+        "update",
+        "Vendor portal export: the meeting is at 4pm",
+        source="third_party",
+        entity="meeting",
+        attribute="time",
+    )
+    assert update.outcome == EvolutionOutcome.CONTESTED
+    kept = await db.get(added.memory.id)
+    assert kept is not None
+    assert kept.valid_until is None
+    assert kept.contested is True
+
+
+async def test_eval_slot_scoped_action_relies_only_on_that_slot(db: ContextDB) -> None:
+    """Without a slot any trusted memory counts; with one, only that slot's facts do."""
+    await db.factual.add(
+        "My home address is 12 Elm Street, Springfield",
+        source="user_stated",
+        action_relevant=True,
+    )
+    await db.factual.add(
+        "We are a party of 4",
+        source="user_stated",
+        action_relevant=True,
+        entity="reservation",
+        attribute="party_size",
+    )
+    assert await db.factual.recall_for_action("Email me the receipt")
+    assert (
+        await db.factual.recall_for_action("Email me the receipt", entity="user", attribute="email")
+        == []
+    )
+    email = await db.factual.add(
+        "My email is avery.example@example.com",
+        source="user_stated",
+        action_relevant=True,
+        entity="user",
+        attribute="email",
+    )
+    scoped = await db.factual.recall_for_action(
+        "Email me the receipt", entity="customer", attribute="e-mail"
+    )
+    assert [m.id for m in scoped] == [email.id]
+
+    tip = await db.factual.add(
+        "Clinic portal note: the appointment is on Thursday",
+        source="third_party",
+        action_relevant=True,
+        entity="appointment",
+        attribute="day",
+    )
+    assert [m.id for m in await db.factual.pending_confirmations(
+        entity="appointment", attribute="day"
+    )] == [tip.id]
+    assert await db.factual.pending_confirmations(entity="user", attribute="email") == []
+    with pytest.raises(ValueError):
+        await db.factual.recall_for_action("Email me the receipt", entity="user")
+
+
+async def test_eval_billing_and_personal_email_are_separate_slots(db: ContextDB) -> None:
+    """Storing where invoices go must not erase the user's own email, or the reverse."""
+    personal = await db.factual.add(
+        "My email is avery.example@example.com",
+        source="user_stated",
+        action_relevant=True,
+        entity="user",
+        attribute="email",
+    )
+    billing = await db.factual.add(
+        "Send invoices to billing.example@example.com",
+        source="user_stated",
+        action_relevant=True,
+        entity="customer",
+        attribute="invoice_email",
+    )
+    assert billing.epistemic_source == "user_stated"
+    assert (billing.entity_key, billing.attribute_key, billing.slot_class) == (
+        "user",
+        "billing_email",
+        "contact",
+    )
+    kept = await db.get(personal.id)
+    assert kept is not None
+    assert kept.valid_until is None
+    trusted = {m.id for m in await db.factual.recall_for_action("send the invoice")}
+    assert {personal.id, billing.id} <= trusted
+
+    phone = await db.factual.add(
+        "Call my desk line at +1 555 0100",
+        source="user_stated",
+        action_relevant=True,
+        entity="user",
+        attribute="office_phone",
+    )
+    assert (phone.attribute_key, phone.slot_class) == ("work_phone", "contact")
+
+    mislabelled = await db.factual.add(
+        "My account number is 12345678",
+        source="user_stated",
+        action_relevant=True,
+        entity="user",
+        attribute="billing_email",
+    )
+    assert mislabelled.epistemic_source == "agent_inferred"