apsimo 1.3.0__py3-none-any.whl

apsimo/world_model/sqlite/schema.sql

@@ -0,0 +1,132 @@
+-- Colony World Model SQLite schema
+-- All tables prefixed with wm_ to avoid collisions with existing schema.
+
+-- Base entity table (all types)
+CREATE TABLE IF NOT EXISTS wm_entities (
+  id              TEXT PRIMARY KEY,       -- we-<timestamp>-<random7>
+  name            TEXT NOT NULL,
+  entity_type     TEXT NOT NULL
+                    CHECK(entity_type IN (
+                      'person', 'company', 'project', 'product',
+                      'location', 'event', 'concept'
+                    )),
+  aliases         TEXT NOT NULL DEFAULT '[]',     -- JSON array
+  external_ids    TEXT NOT NULL DEFAULT '{}',     -- JSON object
+  properties      TEXT NOT NULL DEFAULT '{}',     -- JSON object
+  confidence      REAL NOT NULL DEFAULT 0.5,
+  first_seen      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  last_seen       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_wm_entities_type
+  ON wm_entities(entity_type);
+CREATE INDEX IF NOT EXISTS idx_wm_entities_name
+  ON wm_entities(name COLLATE NOCASE);
+CREATE INDEX IF NOT EXISTS idx_wm_entities_confidence
+  ON wm_entities(confidence DESC);
+
+-- Full-text search index on name + aliases
+CREATE VIRTUAL TABLE IF NOT EXISTS wm_entities_fts
+  USING fts5(
+    id UNINDEXED,
+    name,
+    aliases,
+    content='wm_entities',
+    content_rowid='rowid'
+  );
+
+-- Triggers to keep FTS in sync
+CREATE TRIGGER IF NOT EXISTS wm_entities_fts_insert
+  AFTER INSERT ON wm_entities BEGIN
+    INSERT INTO wm_entities_fts(rowid, id, name, aliases)
+      VALUES (new.rowid, new.id, new.name, new.aliases);
+  END;
+
+CREATE TRIGGER IF NOT EXISTS wm_entities_fts_update
+  AFTER UPDATE ON wm_entities BEGIN
+    INSERT INTO wm_entities_fts(wm_entities_fts, rowid, id, name, aliases)
+      VALUES ('delete', old.rowid, old.id, old.name, old.aliases);
+    INSERT INTO wm_entities_fts(rowid, id, name, aliases)
+      VALUES (new.rowid, new.id, new.name, new.aliases);
+  END;
+
+CREATE TRIGGER IF NOT EXISTS wm_entities_fts_delete
+  AFTER DELETE ON wm_entities BEGIN
+    INSERT INTO wm_entities_fts(wm_entities_fts, rowid, id, name, aliases)
+      VALUES ('delete', old.rowid, old.id, old.name, old.aliases);
+  END;
+
+-- Relationships
+CREATE TABLE IF NOT EXISTS wm_relationships (
+  id                    TEXT PRIMARY KEY,   -- wr-<timestamp>-<random7>
+  source_id             TEXT NOT NULL REFERENCES wm_entities(id) ON DELETE CASCADE,
+  target_id             TEXT NOT NULL REFERENCES wm_entities(id) ON DELETE CASCADE,
+  relationship_type     TEXT NOT NULL,
+  confidence            REAL NOT NULL DEFAULT 0.5,
+  valid_from            TEXT,               -- ISO8601; NULL = unknown start
+  valid_to              TEXT,               -- ISO8601; NULL = still active
+  properties            TEXT NOT NULL DEFAULT '{}',  -- JSON
+  source_observation_id TEXT,
+  created_at            TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  updated_at            TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_wm_rels_source
+  ON wm_relationships(source_id);
+CREATE INDEX IF NOT EXISTS idx_wm_rels_target
+  ON wm_relationships(target_id);
+CREATE INDEX IF NOT EXISTS idx_wm_rels_type
+  ON wm_relationships(relationship_type);
+CREATE INDEX IF NOT EXISTS idx_wm_rels_active
+  ON wm_relationships(valid_to)
+  WHERE valid_to IS NULL;
+CREATE INDEX IF NOT EXISTS idx_wm_rels_temporal
+  ON wm_relationships(valid_from, valid_to);
+
+-- Observations (provenance trail)
+CREATE TABLE IF NOT EXISTS wm_observations (
+  id              TEXT PRIMARY KEY,         -- wo-<timestamp>-<random7>
+  entity_id       TEXT REFERENCES wm_entities(id) ON DELETE CASCADE,
+  relationship_id TEXT REFERENCES wm_relationships(id) ON DELETE CASCADE,
+  observation     TEXT NOT NULL,
+  source          TEXT,
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_wm_obs_entity
+  ON wm_observations(entity_id, created_at DESC);
+
+-- Merge proposals
+CREATE TABLE IF NOT EXISTS wm_merge_proposals (
+  id              TEXT PRIMARY KEY,         -- mp-<timestamp>-<random7>
+  candidate_id    TEXT NOT NULL REFERENCES wm_entities(id) ON DELETE CASCADE,
+  existing_id     TEXT NOT NULL REFERENCES wm_entities(id) ON DELETE CASCADE,
+  match_confidence REAL NOT NULL,
+  match_reason    TEXT NOT NULL,
+  evidence        TEXT NOT NULL DEFAULT '{}',   -- JSON
+  status          TEXT NOT NULL DEFAULT 'pending'
+                    CHECK(status IN ('pending', 'approved', 'rejected', 'expired')),
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  resolved_at     TEXT
+);
+
+-- Merge audit log
+CREATE TABLE IF NOT EXISTS wm_merge_log (
+  id                      TEXT PRIMARY KEY,  -- ma-<timestamp>-<random7>
+  surviving_id            TEXT NOT NULL,
+  retired_id              TEXT NOT NULL,
+  relationships_repointed INTEGER NOT NULL DEFAULT 0,
+  properties_updated      INTEGER NOT NULL DEFAULT 0,
+  executed_by             TEXT NOT NULL,     -- "auto" | "owner_approved"
+  merge_proposal_id       TEXT,
+  created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS wm_schema_migrations (
+  version     TEXT PRIMARY KEY,
+  applied_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  description TEXT
+);

apsimo/world_model/store.py

@@ -0,0 +1,545 @@
+"""World Model primary store interface.
+
+SQLite is the canonical typed-observation backend. Neo4j and PostgreSQL are
+legacy entity/relationship adapters without typed-observation support.
+All callers must use this interface and never access the backend directly.
+"""
+
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+from collections import deque
+
+from .config import WorldModelConfig
+from .constants import CAUSAL_RELATIONSHIP_TYPES
+from .entities import BaseEntity
+from .relationships import WorldRelationship
+from .sqlite.backend import SQLiteBackend
+
+logger = logging.getLogger(__name__)
+
+
+def _is_causal(rel_type: str) -> bool:
+    return str(rel_type or "").strip().upper() in CAUSAL_RELATIONSHIP_TYPES
+
+# Optional inline belief-maintenance hook (item 7): called as
+# cb(entity_id, key, old_value, new_value, old_conf, new_conf) when a
+# property UPDATE changes an existing value, so the superseded value gets an
+# audit row. Set at boot by the server; never raises into the write path.
+_property_audit_hook = None
+
+
+def set_property_audit_hook(cb) -> None:
+    global _property_audit_hook
+    _property_audit_hook = cb
+
+
+@dataclass
+class GraphNeighborhoodResult:
+    center: BaseEntity
+    reachable: List[BaseEntity]
+    edges: List[WorldRelationship]
+    hop_counts: Dict[str, int]       # entity_id → min hops from center
+    truncated: bool = False          # True if max_nodes reached
+
+
+@dataclass
+class WorldModelStats:
+    total_entities: int
+    entities_by_type: Dict[str, int]
+    total_relationships: int
+    active_relationships: int
+    total_observations: int
+    merge_proposals_pending: int
+
+
+class WorldModelStore:
+    """Primary interface to the Colony World Model entity graph.
+
+    SQLite is selected by default. Explicit legacy Neo4j/Postgres configurations
+    may fall back to SQLite when credentials or drivers are missing. Typed
+    observation methods reject an actual legacy backend rather than claiming
+    equivalent provenance, correction, temporal-view or erasure behavior.
+    All methods are async. Callers MUST NOT access the backing store directly.
+    """
+
+    def __init__(self, config: Optional[WorldModelConfig] = None) -> None:
+        self._config = config or WorldModelConfig()
+        self._backend: Optional[SQLiteBackend] = None
+
+    async def connect(self) -> None:
+        """Initialize and connect to the storage backend."""
+        if self._config.backend == "neo4j":
+            try:
+                from apsimo.world_model.neo4j.backend import Neo4jBackend
+                neo4j_uri = self._config.neo4j_uri
+                neo4j_db = self._config.neo4j_database
+                neo4j_user = os.environ.get("NEO4J_USER", "neo4j")
+                neo4j_pass = os.environ.get("NEO4J_PASSWORD", "")
+                if neo4j_uri and neo4j_pass:
+                    self._backend = Neo4jBackend(
+                        uri=neo4j_uri,
+                        database=neo4j_db,
+                        username=neo4j_user,
+                        password=neo4j_pass,
+                    )
+                else:
+                    logger.warning("NEO4J_URI or NEO4J_PASSWORD not set — falling back to sqlite")
+                    self._backend = SQLiteBackend(self._config.sqlite_path)
+            except ImportError:
+                logger.warning("neo4j driver not installed — falling back to sqlite")
+                self._backend = SQLiteBackend(self._config.sqlite_path)
+        elif self._config.backend == "postgres":
+            try:
+                from apsimo.world_model.postgres.backend import PostgresBackend
+                pg_conn = os.environ.get("WORLD_MODEL_PG_CONNECTION", "")
+                if pg_conn:
+                    self._backend = PostgresBackend(pg_conn)
+                else:
+                    logger.warning("WORLD_MODEL_PG_CONNECTION not set — falling back to sqlite")
+                    self._backend = SQLiteBackend(self._config.sqlite_path)
+            except ImportError:
+                logger.warning("asyncpg not installed — falling back to sqlite")
+                self._backend = SQLiteBackend(self._config.sqlite_path)
+        elif self._config.backend == "sqlite":
+            self._backend = SQLiteBackend(self._config.sqlite_path)
+        else:
+            logger.warning("WorldModel backend '%s' not supported — defaulting to sqlite", self._config.backend)
+            self._backend = SQLiteBackend(self._config.sqlite_path)
+        await self._backend.connect()
+
+    async def close(self) -> None:
+        if self._backend:
+            await self._backend.close()
+
+    async def __aenter__(self) -> "WorldModelStore":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    # ── Entity reads ──────────────────────────────────────────────────────────
+
+    async def get_entity(
+        self,
+        entity_id: str,
+        min_confidence: float = 0.30,
+    ) -> Optional[BaseEntity]:
+        """Fetch a single entity by ID.
+
+        Returns None if the entity does not exist or falls below min_confidence.
+        """
+        entity = await self._backend.get_entity(entity_id)
+        if entity and entity.confidence >= min_confidence:
+            return entity
+        return None
+
+    async def find_entities(
+        self,
+        query: str,
+        entity_type: Optional[str] = None,
+        min_confidence: float = 0.30,
+        limit: int = 20,
+    ) -> List[BaseEntity]:
+        """Full-text search across entity names and aliases."""
+        return await self._backend.find_entities(
+            query=query,
+            entity_type=entity_type,
+            min_confidence=min_confidence,
+            limit=limit,
+        )
+
+    async def get_entity_by_external_id(
+        self,
+        key: str,
+        value: str,
+    ) -> Optional[BaseEntity]:
+        """Look up an entity by external ID key/value pair."""
+        return await self._backend.get_entity_by_external_id(key, value)
+
+    # ── Graph traversal ───────────────────────────────────────────────────────
+
+    async def get_neighborhood(
+        self,
+        entity_id: str,
+        max_hops: int = 2,
+        relationship_types: Optional[List[str]] = None,
+        min_confidence: float = 0.30,
+        max_nodes: int = 200,
+    ) -> GraphNeighborhoodResult:
+        """BFS neighborhood traversal up to max_hops from entity_id.
+
+        MUST NOT exceed max_hops = 5 regardless of caller input.
+        """
+        max_hops = min(max_hops, self._config.max_graph_hops)
+        center = await self._backend.get_entity(entity_id)
+        if not center:
+            return GraphNeighborhoodResult(
+                center=None, reachable=[], edges=[], hop_counts={}, truncated=False
+            )
+
+        visited: Dict[str, int] = {entity_id: 0}
+        frontier = deque([entity_id])
+        reachable: List[BaseEntity] = []
+        edges: List[WorldRelationship] = []
+        truncated = False
+
+        while frontier:
+            current_id = frontier.popleft()
+            current_hop = visited[current_id]
+            if current_hop >= max_hops:
+                continue
+
+            neighbors = await self._backend.get_neighbors(
+                current_id, min_confidence=min_confidence,
+                relationship_types=relationship_types,
+            )
+            for neighbor, rel in neighbors:
+                # Query-only causal guard (H2.5, belt-and-braces over the
+                # backend exclusion): an untyped traversal never returns or
+                # walks causal edges; only explicitly typed queries do.
+                if not relationship_types and _is_causal(rel.relationship_type):
+                    continue
+                edges.append(rel)
+                if neighbor.id not in visited:
+                    hop = current_hop + 1
+                    visited[neighbor.id] = hop
+                    reachable.append(neighbor)
+                    if len(reachable) >= max_nodes:
+                        truncated = True
+                        break
+                    frontier.append(neighbor.id)
+            if truncated:
+                break
+
+        hop_counts = {eid: h for eid, h in visited.items() if eid != entity_id}
+        return GraphNeighborhoodResult(
+            center=center,
+            reachable=reachable,
+            edges=edges,
+            hop_counts=hop_counts,
+            truncated=truncated,
+        )
+
+    async def find_path(
+        self,
+        source_id: str,
+        target_id: str,
+        max_hops: int = 5,
+        min_confidence: float = 0.30,
+    ) -> Optional[List[WorldRelationship]]:
+        """Find shortest path between two entities via BFS.
+
+        Returns ordered list of relationships, or None if no path exists.
+        """
+        max_hops = min(max_hops, self._config.max_graph_hops)
+        if source_id == target_id:
+            return []
+
+        # BFS with path tracking
+        visited: Dict[str, Optional[tuple]] = {source_id: None}  # id → (prev_id, rel)
+        frontier = deque([(source_id, 0)])
+
+        while frontier:
+            current_id, hops = frontier.popleft()
+            if hops >= max_hops:
+                continue
+            neighbors = await self._backend.get_neighbors(
+                current_id, min_confidence=min_confidence
+            )
+            for neighbor, rel in neighbors:
+                # Query-only causal guard: untyped path-finding never walks
+                # causal edges (see get_neighborhood).
+                if _is_causal(rel.relationship_type):
+                    continue
+                if neighbor.id not in visited:
+                    visited[neighbor.id] = (current_id, rel)
+                    if neighbor.id == target_id:
+                        # Reconstruct path
+                        path = []
+                        node = target_id
+                        while visited[node] is not None:
+                            prev_id, edge = visited[node]
+                            path.append(edge)
+                            node = prev_id
+                        path.reverse()
+                        return path
+                    frontier.append((neighbor.id, hops + 1))
+        return None
+
+    async def find_common_neighbors(
+        self,
+        entity_id_a: str,
+        entity_id_b: str,
+        max_hops: int = 1,
+    ) -> List[BaseEntity]:
+        """Return entities reachable from both A and B within max_hops."""
+        result_a = await self.get_neighborhood(entity_id_a, max_hops=max_hops)
+        result_b = await self.get_neighborhood(entity_id_b, max_hops=max_hops)
+        ids_a = {e.id for e in result_a.reachable}
+        ids_b = {e.id for e in result_b.reachable}
+        shared_ids = ids_a & ids_b
+        return [e for e in result_a.reachable if e.id in shared_ids]
+
+    # ── Relationship reads ────────────────────────────────────────────────────
+
+    async def query_relationships(
+        self,
+        source_id: Optional[str] = None,
+        target_id: Optional[str] = None,
+        relationship_type: Optional[str] = None,
+        target_types: Optional[List[str]] = None,
+        active_only: bool = False,
+        min_confidence: float = 0.30,
+        limit: int = 100,
+    ) -> List[WorldRelationship]:
+        """Query relationships with flexible filtering.
+
+        Query-only causal guard (H2.5): when ``relationship_type`` is None
+        (an untyped, generic read) causal edges are excluded — enforced in
+        every backend and re-checked here so no backend drift can leak them.
+        Only explicitly typed queries (and /world/causal/*) return them.
+        """
+        rels = await self._backend.query_relationships(
+            source_id=source_id,
+            target_id=target_id,
+            relationship_type=relationship_type,
+            target_types=target_types,
+            active_only=active_only,
+            min_confidence=min_confidence,
+            limit=limit,
+        )
+        if not relationship_type:
+            rels = [r for r in rels if not _is_causal(r.relationship_type)]
+        return rels
+
+    async def query_at_time(
+        self,
+        entity_id: str,
+        as_of: str,
+        relationship_types: Optional[List[str]] = None,
+    ) -> List[WorldRelationship]:
+        """Return relationships active at a specific point in time.
+        Untyped calls exclude causal edges (query-only guard, H2.5)."""
+        rels = await self._backend.query_at_time(
+            entity_id=entity_id, as_of=as_of, relationship_types=relationship_types
+        )
+        if not relationship_types:
+            rels = [r for r in rels if not _is_causal(r.relationship_type)]
+        return rels
+
+    # ── Entity writes ─────────────────────────────────────────────────────────
+
+    async def upsert_entity(self, entity: BaseEntity) -> BaseEntity:
+        """Insert or update an entity. Returns the surviving entity."""
+        result = await self._backend.upsert_entity(entity)
+        self._emit_change("entity_upsert", entity_id=getattr(result, "id", None))
+        return result
+
+    async def update_entity_property(
+        self,
+        entity_id: str,
+        property_key: str,
+        property_value: Any,
+        confidence: float,
+    ) -> None:
+        """Update a legacy descriptive property if its confidence is higher.
+
+        This is not current operational truth. New operational consumers use
+        record_property_observation/property_state with explicit provenance.
+        """
+        # Capture the pre-update value so a supersession can be audited
+        # (item 7 inline hook). Best-effort; never blocks the write.
+        old_value, old_conf = None, 0.0
+        if _property_audit_hook is not None:
+            try:
+                prior = await self._backend.get_entity(entity_id)
+                if prior is not None:
+                    props = getattr(prior, "properties", {}) or {}
+                    old_value = props.get(property_key,
+                                          getattr(prior, property_key, None))
+                    old_conf = float(props.get(f"_conf_{property_key}",
+                                               prior.confidence) or 0.0)
+            except Exception:
+                old_value = None
+        await self._backend.update_entity_property(
+            entity_id, property_key, property_value, confidence
+        )
+        if (_property_audit_hook is not None and old_value not in (None, "")
+                and str(old_value) != str(property_value)
+                and confidence >= old_conf):
+            try:
+                _property_audit_hook(entity_id, property_key, old_value,
+                                     property_value, old_conf, confidence)
+            except Exception:
+                logger.debug("property audit hook failed", exc_info=True)
+        self._emit_change("entity_property_update", entity_id=entity_id, property_key=property_key)
+
+    async def reinforce_entity(self, entity_id: str) -> None:
+        """Record a repeat mention without raising evidential confidence.
+
+        Familiarity updates last_seen/count. No-op on unsupported backends.
+        """
+        fn = getattr(self._backend, "reinforce_entity", None)
+        if fn is None:
+            logger.debug("reinforce_entity unsupported by %s backend",
+                         type(self._backend).__name__)
+            return
+        await fn(entity_id)
+
+    async def add_entity_alias(self, entity_id: str, alias: str) -> None:
+        """Add an alias to an entity's alias list if not already present."""
+        await self._backend.add_entity_alias(entity_id, alias)
+        self._emit_change("entity_alias_added", entity_id=entity_id)
+
+    # ── Relationship writes ───────────────────────────────────────────────────
+
+    async def upsert_relationship(
+        self, relationship: WorldRelationship
+    ) -> WorldRelationship:
+        """Insert or update a relationship."""
+        result = await self._backend.upsert_relationship(relationship)
+        self._emit_change(
+            "relationship_upsert",
+            relationship_id=getattr(result, "id", None),
+        )
+        return result
+
+    async def close_relationship(
+        self, relationship_id: str, valid_to: str
+    ) -> None:
+        """Mark a relationship as ended by setting valid_to."""
+        await self._backend.close_relationship(relationship_id, valid_to)
+        self._emit_change("relationship_closed", relationship_id=relationship_id)
+
+    # ── Event emission ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _emit_change(change_type: str, **payload: Any) -> None:
+        """Broadcast a world_model_changed event. Best-effort — never raises."""
+        try:
+            from apsimo.events.broadcaster import emit as _emit
+            _emit(
+                "world_model_changed",
+                {"change_type": change_type, **{k: v for k, v in payload.items() if v is not None}},
+            )
+        except Exception:
+            pass
+
+    # ── Observations ─────────────────────────────────────────────────────────
+
+    async def record_property_observation(self, **kwargs):
+        """Append one scoped assertion; producers must supply canonical evidence.
+
+        SQLite is the qualified observation backend in this release. Other
+        adapters remain valid for legacy entities/edges and report unsupported
+        rather than substituting old unqualified property values.
+        """
+        from .observations import observation
+        put = getattr(self._backend, 'put_property_observation', None)
+        if put is None:
+            raise NotImplementedError('typed_world_observations_require_sqlite')
+        data = observation(**kwargs)
+        if await self.get_entity(data['entity_id'], min_confidence=0) is None:
+            raise ValueError('world_observation_entity_not_found')
+        result = await put(data)
+        self._emit_change('property_observed', entity_id=data['entity_id'], observation_id=data['observation_id'])
+        return result
+
+    async def property_state(self, entity_id, property_key, *, subject_person_id,
+                             viewer_scope, shareability, as_of=None, source_ledger=None):
+        from .observations import project, iso
+        reader = getattr(self._backend, 'current_property_observations', None)
+        if reader is None:
+            raise NotImplementedError('typed_world_observations_require_sqlite')
+        moment = iso(as_of if as_of is not None else datetime.now(timezone.utc).isoformat())
+        rows = await reader(entity_id, property_key, subject_person_id=subject_person_id,
+                            viewer_scope=viewer_scope, shareability=shareability, as_of=moment)
+        from .source_reports import validate_reports
+        rows = validate_reports(rows, source_ledger)
+        return project(rows, entity_id=entity_id, property_key=property_key,
+            subject_person_id=subject_person_id, viewer_scope=viewer_scope, shareability=shareability,
+            as_of=moment, coverage_limited=len(rows) >= 2001)
+
+    async def erase_property_evidence(self, evidence_refs, *, subject_person_id):
+        eraser = getattr(self._backend, 'erase_property_evidence', None)
+        if eraser is None:
+            raise NotImplementedError('typed_world_observations_require_sqlite')
+        removed = await eraser(evidence_refs, subject_person_id=subject_person_id)
+        if removed:
+            self._emit_change('property_evidence_invalidated', observation_ids=removed)
+        return removed
+
+    async def property_views(self, entity_ids, *, subject_person_id, viewer_scope, shareability,
+                             as_of=None, source_ledger=None, limit=8):
+        """Bounded scoped facts about already-relevant entities for turn context."""
+        keys = getattr(self._backend, 'property_keys', None)
+        if keys is None:
+            raise NotImplementedError('typed_world_observations_require_sqlite')
+        limit = max(1, min(int(limit), 32))
+        result = []
+        for entity_id in list(dict.fromkeys(entity_ids))[:8]:
+            properties = await keys(entity_id, subject_person_id=subject_person_id, viewer_scope=viewer_scope,
+                                    shareability=shareability, limit=limit)
+            for key in properties:
+                result.append(await self.property_state(entity_id, key, subject_person_id=subject_person_id,
+                    viewer_scope=viewer_scope, shareability=shareability, as_of=as_of, source_ledger=source_ledger))
+                if len(result) >= limit:
+                    return result
+        return result
+
+    async def add_observation(
+        self,
+        entity_id: Optional[str],
+        relationship_id: Optional[str],
+        observation: str,
+        source: str,
+    ) -> str:
+        """Record a raw observation string for an entity or relationship."""
+        return await self._backend.add_observation(
+            entity_id, relationship_id, observation, source
+        )
+
+    # ── Maintenance ───────────────────────────────────────────────────────────
+
+    async def prune(self, ttl_days: Optional[int] = None,
+                    max_confidence: Optional[float] = None) -> Dict[str, Any]:
+        """Remove low-confidence entities that haven't been seen within the
+        TTL (config: low_confidence_entity_ttl_days / min_confidence_for_query
+        by default). High-confidence entities are never pruned regardless of
+        age. Returns {"status", "pruned", "cutoff", "max_confidence"};
+        backends without a prune primitive report skipped instead of lying."""
+        backend_prune = getattr(self._backend, "prune_entities", None)
+        if backend_prune is None:
+            return {"status": "skipped",
+                    "reason": f"{type(self._backend).__name__} has no prune"}
+        ttl = int(ttl_days if ttl_days is not None
+                  else self._config.low_confidence_entity_ttl_days)
+        ceiling = float(max_confidence if max_confidence is not None
+                        else self._config.min_confidence_for_query)
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=ttl)
+                  ).strftime("%Y-%m-%dT%H:%M:%SZ")
+        pruned = await backend_prune(cutoff, ceiling)
+        if pruned:
+            logger.info("world model pruned %d stale low-confidence entities "
+                        "(last_seen < %s, confidence < %.2f)",
+                        pruned, cutoff, ceiling)
+        return {"status": "ok", "pruned": pruned, "cutoff": cutoff,
+                "max_confidence": ceiling}
+
+    # ── Stats ─────────────────────────────────────────────────────────────────
+
+    async def get_stats(self) -> WorldModelStats:
+        """Return summary statistics for the world model graph."""
+        raw = await self._backend.get_stats()
+        return WorldModelStats(
+            total_entities=raw["total_entities"],
+            entities_by_type=raw["entities_by_type"],
+            total_relationships=raw["total_relationships"],
+            active_relationships=raw["active_relationships"],
+            total_observations=raw["total_observations"],
+            merge_proposals_pending=raw["merge_proposals_pending"],
+        )