superlocalmemory 4.0.10 → 4.1.2

package/src/superlocalmemory/core/admission.py

@@ -26,6 +26,8 @@ from __future__ import annotations
 
 import functools
 import logging
+import os
+import sqlite3
 from typing import TYPE_CHECKING, FrozenSet
 
 from superlocalmemory.core.actor_context import ActorContext, ActorRole, Transport
@@ -122,6 +124,9 @@ _REQUIRED_MCP_GATES: frozenset[str] = frozenset({
     "link_memory_to_code",
     # Tranche G — mesh_inbox marks messages as read (POST to mesh broker)
     "mesh_inbox",
+    "fetch",
+    "list_recent",
+    "session_init",
 })
 
 
@@ -187,9 +192,17 @@ def _resolve_deployment() -> "DeploymentConfig":
     try:
         from superlocalmemory.core.config import load_deployment_config
         result = load_deployment_config(config_toml_path=config_path)
-    except Exception as exc:
-        logger.debug("admission: load_deployment_config raised (unexpected): %s", exc)
-        return DEPLOYMENT_PERSONAL
+    except Exception as exc:  # noqa: BLE001
+        # config.toml exists and parsed as TOML; only its interpretation failed.
+        # Returning PERSONAL here would hand owner access to a store that may
+        # well be enterprise. Step 2 already returned PERSONAL for the fresh
+        # install with no config at all, which is the case that needs to stay
+        # frictionless.
+        logger.warning(
+            "admission: config.toml is present but could not be interpreted "
+            "(%s) -- fail-closed (treating as enterprise).", exc,
+        )
+        return DEPLOYMENT_ENTERPRISE
 
     # D1 fail-closed: [deployment] section present but mode is unrecognized or
     # absent means someone tried to configure enterprise and a typo/omission
@@ -326,6 +339,173 @@ def admit(
 # @admits decorator for async MCP tools
 # ---------------------------------------------------------------------------
 
+
+# ---------------------------------------------------------------------------
+# Company mode has two switches, and this is where they become one
+# ---------------------------------------------------------------------------
+
+#: Environment variable carrying the caller's user session over a transport that
+#: has no request to put a header on. The dashboard issues the same token, so
+#: this is not a second credential system -- it is the only channel the MCP
+#: surface offers for presenting the one that already exists.
+_SESSION_ENV = "SLM_USER_SESSION"
+
+_RBAC_ROLE_TO_ACTOR = {
+    "admin": ActorRole.ADMIN,
+    "member": ActorRole.MEMBER,
+    "viewer": ActorRole.VIEWER,
+}
+
+
+def _rbac_engine():
+    """The workspace's role store, or None when there is not one.
+
+    Built from the data root rather than from an HTTP app state, because the
+    callers here have no request. Failures return None, which then reads as
+    "personal mode" -- safe, because a workspace with no role store has no roles
+    to enforce.
+    """
+    try:
+        from superlocalmemory.access.rbac import RbacEngine
+        from superlocalmemory.infra.data_root import canonical_data_root
+
+        path = canonical_data_root() / "memory.db"
+        if not path.exists():
+            return None
+        return RbacEngine(str(path))
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("admission: no role store available: %s", exc)
+        return None
+
+
+def _company_mode_active(deployment) -> bool:
+    """Whether a login is required, by EITHER of the two switches.
+
+    THE DEFECT THIS CLOSES
+
+    "Company mode" was two independent settings that nobody had joined up:
+    ``deployment`` in config.toml, which this module read, and ``require_login``
+    in the workspace's own settings, which the dashboard toggle writes and which
+    the HTTP routes read. Turning company mode on from the dashboard therefore
+    changed what HTTP would allow and changed nothing here.
+
+    Measured on a real store: with ``require_login`` on, two users configured,
+    and the viewer's role denying WRITE, an MCP write resolved to
+    ``local-operator`` with role ``owner`` and succeeded -- while the same write
+    over HTTP returned 401. The role check was not bypassed by a missing call;
+    it was bypassed because this path was still being told the workspace was
+    personal.
+
+    Either switch now means the same thing on every transport.
+    """
+    if getattr(deployment, "is_enterprise", False):
+        return True
+    rbac = _rbac_engine()
+    if rbac is None:
+        return False
+    try:
+        return bool(rbac.require_login())
+    except sqlite3.OperationalError as exc:
+        # "No such table" means the role tables were never created, which means
+        # roles were never set up, which is a personal install. Failing closed on
+        # THIS is not caution -- it is refusing every write on every store that
+        # has never used company mode, which is nearly all of them. It was caught
+        # by an existing test whose second MCP write started failing once a store
+        # file appeared in the data root.
+        if "no such table" in str(exc).lower():
+            logger.debug("admission: no role tables; personal workspace")
+            return False
+        logger.warning(
+            "admission: the login policy is unreadable (%s); treating the "
+            "workspace as requiring one", exc,
+        )
+        return True
+    except Exception as exc:  # noqa: BLE001 -- an unreadable policy is not a licence
+        logger.warning(
+            "admission: cannot read the login policy (%s); treating the "
+            "workspace as requiring one", exc,
+        )
+        return True
+
+
+def _target_profile(explicit: str = "") -> str:
+    """The workspace a call will actually touch.
+
+    An explicit argument wins when the caller supplies one. Otherwise this reads
+    the same ``profiles.json`` the engine and the HTTP layer read, because that
+    is where the write is going to land.
+
+    THE DEFECT THIS CLOSES
+
+    The role check used to key off ``kwargs.get("profile_id")``. ``remember``
+    has no such parameter, so every role lookup resolved against ``default``
+    while the write went to whichever workspace was active. A user who is an
+    admin on ``default`` and a viewer on ``team`` passed the check on
+    ``default`` and wrote to ``team`` -- which HTTP would have refused.
+    """
+    name = (explicit or "").strip()
+    if name:
+        return name
+    try:
+        from superlocalmemory.server.profile_runtime import current_request_profile
+
+        runtime = current_request_profile()
+        if runtime:
+            return str(runtime)
+    except Exception as exc:  # noqa: BLE001 -- no request context is normal off HTTP
+        logger.debug("admission: no request profile in scope: %s", exc)
+    try:
+        import json as _json
+
+        from superlocalmemory.infra.data_root import canonical_data_root
+
+        config_file = canonical_data_root() / "profiles.json"
+        if config_file.exists():
+            data = _json.loads(config_file.read_text(encoding="utf-8"))
+            active = str(data.get("active_profile", "") or "").strip()
+            if active:
+                return active
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("admission: cannot read the active workspace: %s", exc)
+    return "default"
+
+
+def _session_principal(profile: str) -> tuple[str, str, FrozenSet[ActorRole] | None]:
+    """Resolve the caller from a session token in the environment.
+
+    Returns ``(principal_id, raw_token, roles)``. An empty principal means the
+    caller could not be identified, which ``resolve_actor`` turns into ANONYMOUS
+    and ``admit`` then denies -- so an unset or expired token fails closed.
+    """
+    token = os.environ.get(_SESSION_ENV, "").strip()
+    if not token:
+        return "", "", None
+    rbac = _rbac_engine()
+    if rbac is None:
+        return "", "", None
+    try:
+        user = rbac.resolve_session(token)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("admission: session lookup failed: %s", exc)
+        return "", "", None
+    if not user:
+        return "", "", None
+    role = None
+    try:
+        role = rbac.get_role(user["user_id"], profile or "default")
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("admission: role lookup failed: %s", exc)
+    # No membership on this workspace is not the same as MEMBER. Falling back to
+    # a write-capable default here would hand every authenticated user write
+    # access to every workspace on the machine.
+    actor_role = _RBAC_ROLE_TO_ACTOR.get(
+        getattr(role, "value", role) if role is not None else "", None,
+    )
+    if actor_role is None:
+        return user["user_id"], token, frozenset({ActorRole.ANONYMOUS})
+    return user["user_id"], token, frozenset({actor_role})
+
+
 def admits(kind: OperationKind):
     """Decorator that gates an async MCP tool function via the policy registry.
 
@@ -348,9 +528,21 @@ def admits(kind: OperationKind):
         @functools.wraps(fn)
         async def wrapper(*args, **kwargs):
             deployment = _resolve_deployment()
-            tier = "enterprise" if deployment.is_enterprise else "personal"
-            mode = "company" if deployment.is_enterprise else "local"
-            actor = resolve_actor(Transport.MCP, tier=tier, mode=mode)
+            # Either switch means company mode. Reading only the config file is
+            # what let a dashboard toggle change HTTP and leave this transport
+            # writing as the machine owner.
+            company = _company_mode_active(deployment)
+            tier = "enterprise" if company else "personal"
+            mode = "company" if company else "local"
+            principal, token, roles = ("", "", None)
+            if company:
+                principal, token, roles = _session_principal(
+                    _target_profile(kwargs.get("profile_id", "") or ""),
+                )
+            actor = resolve_actor(
+                Transport.MCP, tier=tier, mode=mode,
+                principal=principal, session=token, roles=roles,
+            )
             try:
                 admit(kind, actor, mode=mode)
             except AdmissionDenied as exc:
@@ -373,6 +565,7 @@ def gate_cli_mutation(
     *,
     principal: str = "",
     roles: FrozenSet[ActorRole] | None = None,
+    profile: str = "",
 ) -> None:
     """Gate a CLI mutation command. Exits with code 1 if denied.
 
@@ -385,25 +578,48 @@ def gate_cli_mutation(
     kind      : Operation being performed.
     principal : Authenticated CLI principal (from session store / login token).
     roles     : Explicit roles for an authenticated enterprise user.
+    profile   : Workspace the command will touch. Empty means the active one.
     """
     import sys
     deployment = _resolve_deployment()
-    tier = "enterprise" if deployment.is_enterprise else "personal"
-    mode = "company" if deployment.is_enterprise else "local"
+    # Either switch means company mode -- the same rule the MCP gate uses. This
+    # gate used to read config.toml alone, so turning per-user access on from
+    # the dashboard changed HTTP and MCP and left every CLI write running as the
+    # machine owner.
+    company = _company_mode_active(deployment)
+    tier = "enterprise" if company else "personal"
+    mode = "company" if company else "local"
+    session = ""
+    if company and not principal:
+        # A CLI caller identifies itself the same way an MCP caller does. With
+        # no token the principal stays empty, resolve_actor returns ANONYMOUS,
+        # and admit denies -- which is the intended answer for an unauthenticated
+        # write on a workspace that requires a login.
+        principal, session, resolved_roles = _session_principal(
+            _target_profile(profile),
+        )
+        if roles is None:
+            roles = resolved_roles
     actor = resolve_actor(
         Transport.CLI,
         tier=tier,
         mode=mode,
         principal=principal,
+        session=session,
         roles=roles,
     )
     try:
         admit(kind, actor, mode=mode)
     except AdmissionDenied as exc:
+        # Name something the reader can actually do. This used to say
+        # "log in with 'slm login'", and there is no such command -- so the one
+        # instruction the message gave was a dead end.
         print(
             f"[slm] Operation denied ({exc.decision.reason}). "
-            "This workspace requires authentication. "
-            "Log in with 'slm login' or contact your workspace administrator.",
+            "This workspace requires a signed-in user. Sign in on the dashboard "
+            "(slm dashboard), copy your session token, and put it in the "
+            "SLM_USER_SESSION environment variable -- or ask whoever "
+            "administers this workspace for access.",
             flush=True,
         )
         sys.exit(1)
@@ -515,7 +731,11 @@ def enforce_read_scope(
     is left alone so the server default applies.
     """
     deployment = _resolve_deployment()
-    if not deployment.is_enterprise:
+    # Both switches, for the same reason the write gates read both: a dashboard
+    # toggle used to leave this path unclamped, so a viewer could ask for
+    # include_global=True over MCP and pull another workspace's facts into the
+    # candidate set while HTTP refused the same request.
+    if not _company_mode_active(deployment):
         return include_global, include_shared
 
     reg = registry if registry is not None else _DEFAULT_REGISTRY

package/src/superlocalmemory/core/backend_orchestrator.py

@@ -21,6 +21,9 @@ import logging
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from superlocalmemory.core.projection_drain import ProjectionDrain
+from superlocalmemory.storage import projection_outbox
+
 if TYPE_CHECKING:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.storage.database import DatabaseManager
@@ -80,6 +83,12 @@ class BackendOrchestrator:
         self._lancedb: Any = None
         self._tiers: Any = None
         self._backend_cache: dict[str, str] = {}
+        # Given accessors, not backends: a promotion or a rollback replaces
+        # them underneath the worker, and a reference captured here would keep
+        # writing into the projection that was just swapped out.
+        self._drain = ProjectionDrain(
+            db, self.get_graph_backend, self.get_vector_backend,
+        )
 
     # ------------------------------------------------------------------
     # Daemon Startup
@@ -107,6 +116,19 @@ class BackendOrchestrator:
 
         self._recover_interrupted_scale_promotion()
 
+        # Reconcile what the config CLAIMS against what is on disk, before
+        # anything reads either -- and before the early return below, because
+        # the stores that need reconciling are exactly the ones that take it.
+        #
+        # This used to sit after that return, so it ran only for a store already
+        # in the promoted state. The real case it was written for is a store
+        # whose settings name a graph and a vector backend, whose state is
+        # `verified` rather than `promoted`, and where neither directory exists:
+        # the settings kept the claim, the reconcile never ran, and every
+        # restart preserved it. The test asserted the call appeared before
+        # another call in the source text, which is true either way.
+        self._reconcile_backend_selection()
+
         # Backends may be installed with the product, but installing a wheel
         # is not authorization to mutate an existing data root.  Only a
         # verified, explicit promotion may initialize and migrate projections.
@@ -120,6 +142,11 @@ class BackendOrchestrator:
             # SQLite graph.  A no-op (and never even starts the build) for the
             # vast majority of installs, which sit far below the threshold.
             self._maybe_schedule_auto_promote()
+            # Started even with no projection open. A pass with no backend
+            # returns without touching a row, and starting it here means a
+            # promotion that completes mid-session has a worker waiting for it
+            # rather than a queue nobody is reading.
+            self._drain.start()
             return
 
         # 3. Initialize CozoDB if available
@@ -145,9 +172,14 @@ class BackendOrchestrator:
         except Exception as exc:
             logger.warning("TierManager backend registration failed (non-fatal): %s", exc)
 
-        logger.info("BackendOrchestrator: daemon ready (cozo=%s, lancedb=%s)",
-                     "active" if self._cozo and self._cozo_status() == "active" else "off",
-                     "active" if self._lancedb and self._lancedb_status() == "active" else "off")
+        self._drain.start()
+
+        logger.info(
+            "BackendOrchestrator: daemon ready (cozo=%s, lancedb=%s, queued=%d)",
+            "active" if self._cozo and self._cozo_status() == "active" else "off",
+            "active" if self._lancedb and self._lancedb_status() == "active" else "off",
+            projection_outbox.depth(self._db),
+        )
 
     def _maybe_schedule_auto_promote(self) -> None:
         """Schedule a delayed, one-shot scale auto-promote check (v3.8.5).
@@ -164,7 +196,23 @@ class BackendOrchestrator:
         cfg = self._config
         if not getattr(cfg, "scale_auto_promote_enabled", True):
             return
-        if getattr(cfg, "scale_engine_state", "local_core") != "local_core":
+        # Only a store that has finished promoting has nothing left to do.
+        #
+        # This used to skip every state except ``local_core``, which made
+        # ``prepared`` and ``verified`` terminal: the daemon above returns
+        # early for anything that is not ``promoted``, so the backends never
+        # started, and this refused to finish the promotion that would have
+        # started them. A store that got as far as building and checking its
+        # projection then sat on SQLite forever while its own config named Cozo
+        # and LanceDB as the backends — measured on a real store whose
+        # ``backend_status`` read lancedb=not_initialized under
+        # ``scale_engine_state=verified``.
+        #
+        # ``run_auto_promote`` already resumes a half-finished stage
+        # (``_resumable_stage``) and applies the size threshold and the
+        # repair-required check itself, so it is the right place for every
+        # decision except "there is nothing left to do".
+        if str(getattr(cfg, "scale_engine_state", "local_core")).lower() == "promoted":
             return
         try:
             delay = float(os.environ.get("SLM_AUTO_PROMOTE_DELAY_S", "300"))
@@ -198,11 +246,14 @@ class BackendOrchestrator:
             import os
 
             cfg = self._config
-            if getattr(cfg, "scale_engine_state", "local_core") != "local_core":
+            # Same rule as the scheduler that armed this timer: only a store
+            # that has finished has nothing left to do. Fixing the scheduler
+            # alone would have armed a timer whose callback still refused.
+            if str(getattr(cfg, "scale_engine_state", "local_core")).lower() == "promoted":
                 return
             threshold = int(
                 os.environ.get("SLM_AUTO_PROMOTE_MIN_EDGES", "")
-                or getattr(cfg, "scale_auto_promote_min_edges", 1_000_000)
+                or getattr(cfg, "scale_auto_promote_min_edges", 100_000)
             )
             edges = self._count_default_edges()
             if edges < threshold:
@@ -237,6 +288,75 @@ class BackendOrchestrator:
                 exc,
             )
 
+    def _reconcile_backend_selection(self) -> None:
+        """Stop the config claiming a backend the store does not have.
+
+        THE STATE THIS REPAIRS
+
+        On a real store: ``graph_backend='cozo'``, ``vector_backend='lancedb'``,
+        ``scale_engine_state='verified'`` -- and neither the ``cozo/`` nor the
+        ``lance/`` directory existed, with no promotion journal to explain it.
+        Something wrote the selection a completed promotion writes, without a
+        promotion having completed.
+
+        Nothing corrected it. ``recover_interrupted_promotion`` acts only when a
+        journal exists, so with no journal it returns immediately and the claim
+        survives every restart. The dashboard then reports the configured backend
+        while retrieval uses SQLite, which is the disagreement a person notices
+        last and trusts first.
+
+        WHAT THIS DOES NOT DO
+
+        It does not disable anything. ``auto`` still detects and initialises both
+        projections when their libraries are installed, so the only thing removed
+        is the false claim. It leaves ``verified`` alone -- that is a legitimate
+        waypoint meaning "parity checked, not yet promoted" -- and only resets
+        ``promoted``, which asserts a swap that plainly did not happen. And it
+        never touches a selection whose directory is present, nor one with a
+        journal still open, because those belong to the promotion lifecycle.
+        """
+        try:
+            from superlocalmemory.core.scale_engine import ScaleEngineManager
+
+            manager = ScaleEngineManager(self._config, profile_id="default")
+            if manager.promotion_journal_path.exists():
+                return  # the recovery path owns this
+            cozo_path, lance_path = manager.active_paths
+        except Exception as exc:  # noqa: BLE001 -- reconciliation is best effort
+            logger.debug("Backend reconciliation skipped: %s", exc)
+            return
+
+        corrections: list[str] = []
+        graph = getattr(self._config, "graph_backend", "auto") or "auto"
+        if graph not in ("auto", "sqlite") and not cozo_path.exists():
+            corrections.append(f"graph_backend {graph!r} -> 'auto' (no {cozo_path.name}/)")
+            self._config.graph_backend = "auto"
+        vector = getattr(self._config, "vector_backend", "auto") or "auto"
+        if vector not in ("auto", "sqlite-vec") and not lance_path.exists():
+            corrections.append(
+                f"vector_backend {vector!r} -> 'auto' (no {lance_path.name}/)"
+            )
+            self._config.vector_backend = "auto"
+        state = getattr(self._config, "scale_engine_state", "") or ""
+        if state == "promoted" and not (cozo_path.exists() or lance_path.exists()):
+            corrections.append("scale_engine_state 'promoted' -> 'local_core'")
+            self._config.scale_engine_state = "local_core"
+
+        if not corrections:
+            return
+        try:
+            self._config.save()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Backend selection is inconsistent with the data directory and "
+                "could not be corrected (%s): %s", exc, "; ".join(corrections),
+            )
+            return
+        logger.warning(
+            "Backend selection did not match the data directory; corrected: %s",
+            "; ".join(corrections),
+        )
+
     def _recover_interrupted_scale_promotion(self) -> None:
         """Repair an interrupted promotion; never auto-mutate a legacy root."""
         try:
@@ -261,90 +381,44 @@ class BackendOrchestrator:
     # ------------------------------------------------------------------
 
     def sync_new_fact(self, fact: Any) -> None:
-        """Sync a newly stored fact to CozoDB and LanceDB.
-
-        Called AFTER SQLite write in store_pipeline.
-        Non-blocking, best-effort. Failures are logged, not raised.
+        """Signal that a stored fact needs projecting.
+
+        The projection itself is not written here. It used to be — inline, on
+        the caller's thread, with every failure swallowed into a debug line —
+        and that is the defect the outbox replaced. The intent to project was
+        already committed to ``projection_outbox`` in the same SQLite
+        transaction as the fact, so all that is left to do is wake the worker
+        that owns the projections.
+
+        Kept as a method because callers name this operation, and because a
+        caller that reaches it without an outbox row (an old store, mid-upgrade)
+        should still get its fact projected rather than silently skipped.
         """
-        try:
-            tier = getattr(fact, "lifecycle", "active")
-        except Exception:
-            tier = "active"
-
-        if tier in ("active", "warm"):
-            if self._cozo and self._cozo_status() == "active":
-                self._sync_fact_entities(fact)
-
-            if self._lancedb and self._lancedb_status() == "active":
-                self._sync_fact_embedding(fact)
-
-    def _sync_fact_entities(self, fact: Any) -> None:
-        """Synchronize one fact's canonical entity bridge and fact edges."""
-        try:
-            # Retrying ingestion must not retain stale fact/entity links.
-            self._cozo.remove_fact(fact.fact_id)
-            entities = getattr(fact, "canonical_entities", []) or []
-            profile_id = getattr(fact, "profile_id", "default") or "default"
-            for eid in entities:
-                rows = self._db.execute(
-                    "SELECT canonical_name, entity_type, fact_count FROM canonical_entities "
-                    "WHERE entity_id = ? AND profile_id = ?",
-                    (eid, profile_id),
-                )
-                if rows:
-                    entity = dict(rows[0])
-                    self._cozo.add_entity(
-                        eid,
-                        entity.get("canonical_name") or eid,
-                        entity.get("entity_type") or "concept",
-                        {"fact_count": int(entity.get("fact_count") or 0)},
-                        profile_id,
-                    )
-            self._cozo.add_fact_entities(fact.fact_id, entities, profile_id)
-            for row in self._db.execute(
-                "SELECT source_id, target_id, edge_type, weight FROM graph_edges "
-                "WHERE profile_id = ? AND (source_id = ? OR target_id = ?)",
-                (profile_id, fact.fact_id, fact.fact_id),
-            ):
-                edge = dict(row)
-                self._cozo.add_edge(
-                    edge["source_id"], edge["target_id"], edge.get("edge_type") or "related",
-                    float(edge.get("weight") or 1.0), profile_id=profile_id,
-                )
-        except Exception as exc:
-            logger.debug("CozoDB incremental sync skipped: %s", exc)
-
-    def _sync_fact_embedding(self, fact: Any) -> None:
-        """Sync fact's embedding to LanceDB."""
-        try:
-            embedding = getattr(fact, "embedding", None)
-            if embedding:
-                tier = getattr(fact, "lifecycle", "active")
-                self._lancedb.add_vectors(
-                    [fact.fact_id], [embedding], [tier],
-                    getattr(fact, "profile_id", "default") or "default",
-                )
-        except Exception as exc:
-            logger.debug("LanceDB incremental sync skipped: %s", exc)
+        fact_id = getattr(fact, "fact_id", None)
+        if fact_id:
+            projection_outbox.enqueue(
+                self._db, fact_id, getattr(fact, "profile_id", None) or "default",
+            )
+        self._drain.notify()
 
     def sync_deleted_fact(self, fact_id: str) -> None:
-        """Remove a fact from derived projections after canonical deletion."""
-        if self._cozo and self._cozo_status() == "active":
-            try:
-                self._cozo.remove_fact(fact_id)
-            except Exception as exc:
-                logger.warning("Cozo deletion sync failed for %s: %s", fact_id[:16], exc)
-        if self._lancedb and self._lancedb_status() == "active":
-            try:
-                self._lancedb.remove_vector(fact_id)
-            except Exception as exc:
-                logger.warning("Lance deletion sync failed for %s: %s", fact_id[:16], exc)
+        """Signal that a deleted fact must leave the projections.
+
+        A forgotten memory still present in the graph or the vector index is
+        still recallable, so the removal is queued with the same durability as
+        the delete itself.
+        """
+        if fact_id:
+            projection_outbox.enqueue_for_fact(
+                self._db, fact_id, projection_outbox.OP_DELETE,
+            )
+        self._drain.notify()
 
     def sync_changed_fact(self, fact_id: str) -> None:
         """Refresh projections after an authorized canonical fact update."""
-        fact = self._db.get_fact(fact_id)
-        if fact is not None:
-            self.sync_new_fact(fact)
+        if fact_id:
+            projection_outbox.enqueue_for_fact(self._db, fact_id)
+        self._drain.notify()
 
     # ------------------------------------------------------------------
     # Backend Access
@@ -411,8 +485,40 @@ class BackendOrchestrator:
                 "LanceDB not active. Install: pip install superlocalmemory[lancedb]"
             )
 
+        outbox = projection_outbox.health(self._db)
+        outbox["draining"] = self._drain.running
+        result["projection_queue"] = outbox
+        if outbox["stalled"]:
+            result["warnings"].append(
+                f"{outbox['stalled']} memory/memories could not be projected into "
+                "the graph or vector store. Run `slm doctor` for the ids."
+            )
+
         return result
 
+    # ------------------------------------------------------------------
+    # Projection queue
+    # ------------------------------------------------------------------
+
+    def drain_projections(self, limit: int = 200) -> dict[str, Any]:
+        """Apply queued facts now, on the calling thread.
+
+        For the CLI, for a repair pass, and for any caller that needs the
+        projections current before it reads them rather than a few milliseconds
+        later. Ordinary writes do not need this — they signal the worker.
+        """
+        return self._drain.drain_once(limit=limit).as_dict()
+
+    def outbox_health(self) -> dict[str, Any]:
+        """Queue depth and stalled count, for the status surfaces."""
+        health = projection_outbox.health(self._db)
+        health["draining"] = self._drain.running
+        return health
+
+    def stop(self) -> None:
+        """Stop the drain worker. For daemon shutdown and for tests."""
+        self._drain.stop()
+
     # ------------------------------------------------------------------
     # Internal: Detection
     # ------------------------------------------------------------------