superlocalmemory 4.0.10 → 4.1.2

package/src/superlocalmemory/storage/migrations/M049_a_schema_version_marker_is_one_row.py

@@ -0,0 +1,201 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""One row per schema version, which is what every writer already assumed.
+
+WHAT WAS WRONG
+
+``schema_version`` records which schema versions have been applied. Six call
+sites write to it and every one of them uses ``INSERT OR IGNORE``, which reads
+as "record this version unless it is already recorded".
+
+There was no unique constraint on ``version``, and no index at all. With nothing
+to conflict against, ``OR IGNORE`` never ignores anything, so each of those call
+sites appended a duplicate on every run. Measured:
+
+    store          rows      distinct versions
+    live          3,496                      7
+    larger      234,348                      7
+
+That is the same seven facts written a third of a million times, and it grows
+every time the daemon starts or a maintenance cycle re-checks the schema.
+
+WHY THE INDEX AND NOT A CLEANUP JOB
+
+A retention rule would delete the duplicates and leave the cause, so the table
+would refill. The unique index makes ``INSERT OR IGNORE`` do what all six call
+sites already believe it does, which fixes the cause and makes the cleanup a
+one-off.
+
+WHAT IS KEPT
+
+The earliest row for each version -- the one recording when that version was
+actually first applied, which is the only one of the duplicates that carries
+true information. Where a duplicate set disagrees on ``description`` the first
+non-empty one wins, because later writers pass ``''``.
+
+WHY THE TABLE IS REBUILT AND NOT ALTERED
+
+SQLite cannot add a constraint to an existing table, and a UNIQUE INDEX cannot
+be created over data that already violates it -- so the duplicates come out
+first, in the same transaction that adds the index. If the two were separate,
+a writer between them would insert a duplicate and the index creation would
+fail on a store that had just been cleaned.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+
+logger = logging.getLogger(__name__)
+
+NAME = "M049_a_schema_version_marker_is_one_row"
+DB_TARGET = "memory"
+
+#: Additive: an index and fewer duplicate rows. An older build reading this
+#: table asks whether a version is present, which is unchanged. Writing to it
+#: with OR IGNORE now succeeds silently instead of appending, which is what the
+#: older build intended anyway.
+BREAKING_VERSION = 0
+
+_TABLE = "schema_version"
+_INDEX = "idx_schema_version_unique"
+
+DDL = """
+-- Deduplicate schema_version, keeping the earliest row per version, then make
+-- the column unique so INSERT OR IGNORE stops appending.
+"""
+
+
+def _has_table(conn: sqlite3.Connection) -> bool:
+    row = conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (_TABLE,)
+    ).fetchone()
+    return row is not None
+
+
+def apply(conn: sqlite3.Connection) -> None:
+    """Collapse the duplicates and add the constraint, in one transaction."""
+    if not _has_table(conn):
+        logger.info("M049: no %s table; nothing to do", _TABLE)
+        return
+
+    columns = {row[1] for row in conn.execute(f"PRAGMA table_info({_TABLE})")}
+    if "version" not in columns:
+        logger.info("M049: %s has no version column; nothing to do", _TABLE)
+        return
+    has_description = "description" in columns
+    has_applied_at = "applied_at" in columns
+
+    before = conn.execute(f"SELECT COUNT(*) FROM {_TABLE}").fetchone()[0]
+    distinct = conn.execute(
+        f"SELECT COUNT(DISTINCT version) FROM {_TABLE}"
+    ).fetchone()[0]
+
+    order_by = "applied_at ASC, rowid ASC" if has_applied_at else "rowid ASC"
+    # The row to keep for each version, chosen by when the version was recorded
+    # as landing. ``MIN(rowid)`` will not do: an ORDER BY inside a grouped
+    # subquery does not decide which row MIN() picks, so on a store where the
+    # duplicates were written out of order it kept a later stamp and deleted the
+    # original. Reproduced: rows dated 2026-01-01 and 2026-08-01 for one
+    # version, and the January one -- the true first application -- was the one
+    # that went.
+    # A window function, not a correlated subquery. Both are correct; only one
+    # finishes. The correlated form re-scans the whole table for every row, and
+    # on the store this migration exists for -- 234,348 rows over 7 versions --
+    # that is 7.8 billion row comparisons. Measured: it ran for more than
+    # twenty-five minutes at full CPU without completing, which on a first
+    # upgrade is indistinguishable from a hang. The window form ranks each
+    # partition once.
+    survivor = (
+        f"SELECT rowid FROM (SELECT rowid, ROW_NUMBER() OVER ("
+        f"PARTITION BY version ORDER BY {order_by}) AS rn FROM {_TABLE}"
+        f") WHERE rn = 1"
+    )
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        if has_description:
+            # A later duplicate may carry the only real description, and after
+            # the delete there is nothing left to read it from. So this runs
+            # FIRST, moving the earliest non-empty description onto the row that
+            # is about to survive. Running it afterwards -- as this once did --
+            # could only turn NULL into an empty string, which recovers nothing
+            # and reads in the log as though it had.
+            # One pass to find the best description per version, then one
+            # update joined against it. Correlated here for the same reason as
+            # above -- one scan per blank row -- would be just as slow.
+            conn.execute(f"""
+                CREATE TEMP TABLE IF NOT EXISTS _m049_best AS
+                SELECT version, description FROM (
+                    SELECT version, description, ROW_NUMBER() OVER (
+                        PARTITION BY version ORDER BY {order_by}
+                    ) AS rn
+                    FROM {_TABLE}
+                    WHERE description IS NOT NULL AND TRIM(description) <> ''
+                ) WHERE rn = 1
+            """)
+            conn.execute(
+                f"UPDATE {_TABLE} SET description = COALESCE(("
+                f"  SELECT description FROM _m049_best"
+                f"  WHERE _m049_best.version = {_TABLE}.version"
+                f"), '') "
+                f"WHERE description IS NULL OR TRIM(description) = ''"
+            )
+            conn.execute("DROP TABLE IF EXISTS _m049_best")
+        conn.execute(
+            f"DELETE FROM {_TABLE} WHERE rowid NOT IN ({survivor})"
+        )
+        conn.execute(
+            f"CREATE UNIQUE INDEX IF NOT EXISTS {_INDEX} ON {_TABLE}(version)"
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+    after = conn.execute(f"SELECT COUNT(*) FROM {_TABLE}").fetchone()[0]
+    logger.info(
+        "M049: %s went from %d row(s) to %d for %d distinct version(s)",
+        _TABLE, before, after, distinct,
+    )
+
+
+def repair(conn: sqlite3.Connection) -> None:
+    """Re-run. Idempotent: the delete and the index are both conditional."""
+    apply(conn)
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """One row per version, and a constraint that keeps it that way.
+
+    Both halves matter. Row count alone would pass on a freshly deduplicated
+    store that is about to refill; the index alone would pass on a store where
+    the index exists but was created before the duplicates were removed, which
+    SQLite would not allow but a hand-edited store could reach.
+    """
+    if not _has_table(conn):
+        return True
+    columns = {row[1] for row in conn.execute(f"PRAGMA table_info({_TABLE})")}
+    if "version" not in columns:
+        return True
+
+    total, distinct = conn.execute(
+        f"SELECT COUNT(*), COUNT(DISTINCT version) FROM {_TABLE}"
+    ).fetchone()
+    if total != distinct:
+        logger.error(
+            "M049 verify: %s holds %d rows for %d versions", _TABLE, total, distinct
+        )
+        return False
+
+    for row in conn.execute(f"PRAGMA index_list({_TABLE})"):
+        name, unique = row[1], row[2]
+        if not unique:
+            continue
+        indexed = [c[2] for c in conn.execute(f"PRAGMA index_info({name})")]
+        if indexed == ["version"]:
+            return True
+    logger.error("M049 verify: %s has no unique index on version", _TABLE)
+    return False

package/src/superlocalmemory/storage/migrations.py

@@ -38,9 +38,25 @@ def get_schema_version(conn: sqlite3.Connection) -> int:
 
 
 def set_schema_version(conn: sqlite3.Connection, version: int) -> None:
-    """Record a schema version upgrade."""
+    """Record a schema version upgrade. Stamping the same version twice is a
+    no-op rather than an error.
+
+    A version is a marker, not an event log: the store either is at a version or
+    is not. This table used to have no constraint saying so, and the call sites
+    that stamp it all believed they were idempotent -- one store had 234,348
+    rows describing seven distinct versions. The constraint exists now, and this
+    keeps the first stamp, because that is the one that says when the version
+    actually landed.
+    """
+    # OR IGNORE rather than ON CONFLICT(version): the constraint is added by a
+    # migration, so a store that has not run it yet has no unique index for a
+    # conflict target to name, and naming one there raises. OR IGNORE is correct
+    # both before and after -- a no-op once the constraint exists, and the
+    # previous append-only behaviour until it does, which that migration then
+    # collapses.
     conn.execute(
-        "INSERT INTO schema_version (version, applied_at, description) VALUES (?, ?, ?)",
+        "INSERT OR IGNORE INTO schema_version (version, applied_at, description) "
+        "VALUES (?, ?, ?)",
         (version, datetime.now(UTC).isoformat(), f"Migration to v{version}"),
     )
 

package/src/superlocalmemory/storage/models.py

@@ -29,7 +29,33 @@ class FactType(str, Enum):
     EPISODIC = "episodic"      # Events: who did what when
     SEMANTIC = "semantic"      # World knowledge: X is Y
     OPINION = "opinion"        # Subjective with confidence
-    TEMPORAL = "temporal"      # Time-bounded events with intervals
+    # Something the user intends to do later: a deadline, an appointment, a
+    # plan. Named "temporal" until 4.1.0, which collided with the retrieval
+    # channel of the same name — that one scores every fact by date proximity
+    # and has nothing to do with this. EdgeType.TEMPORAL and
+    # SignalType.TEMPORAL below are also unrelated and deliberately unchanged.
+    PROSPECTIVE = "prospective"
+
+    @classmethod
+    def _missing_(cls, value: object) -> "FactType | None":
+        """Read the old name for a planned event as the current one.
+
+        Renaming the type left every existing row spelled the old way until the
+        migration converts it, and a migration is allowed to have not run yet:
+        deferred migrations are applied after engine init and a failure there is
+        recorded, not raised. Without this, hydrating one of those rows raised
+        ``ValueError`` from the constructor and took the whole recall with it —
+        every channel, not just the fact. A store holding planned events lost
+        the ability to recall anything, which is precisely the population the
+        rename was for.
+
+        Reading the old spelling is therefore not a courtesy, it is what makes
+        the conversion safe to defer. Writing it is still impossible: a write
+        goes through the member, whose value is the new name.
+        """
+        if isinstance(value, str) and value.strip().lower() == "temporal":
+            return cls.PROSPECTIVE
+        return None
 
 
 class EdgeType(str, Enum):
@@ -441,6 +467,10 @@ class RecallResponse:
     score_contract_version: str = "2"
     calibration_status: str = "uncalibrated"
     calibration_id: str | None = None
+    #: Names this particular answer, so an outcome reported later can be tied
+    #: back to it exactly rather than guessed at from which memories overlap.
+    #: Empty means the answer was produced by a path that does not record one.
+    query_id: str = ""
     answer_confidence: float | None = None
     abstained: bool = False
     abstention_reason: str | None = None
@@ -459,3 +489,12 @@ class RecallResponse:
     # which two runs of one query are expected to agree. Sorted, so the field
     # is itself repeatable. Additive — backward compatible.
     incomplete_channels: tuple[str, ...] = ()
+    # What happened to each retrieval channel on this recall: ok / empty /
+    # error / timeout / disabled / not_configured / no_embedding. Absence and
+    # failure used to look identical from here — a channel that raises on every
+    # query and a channel that correctly found nothing both simply had no
+    # candidates, and the only trace was a log line. Keyed by channel name;
+    # ``retrieval.channel_status.CHANNEL_NAMES`` is the full set, so a missing
+    # key is a reporting gap and ``empty`` is an answer. Additive — backward
+    # compatible.
+    channel_status: dict[str, str] = field(default_factory=dict)

package/src/superlocalmemory/storage/projection_outbox.py

@@ -0,0 +1,346 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""The queue that makes a cross-engine projection write impossible to lose.
+
+The graph lives in CozoDB (RocksDB underneath) and the vectors in LanceDB. Both
+are separate storage engines from SQLite, so no transaction can span them and
+there is no two-phase commit to reach for. The obvious sequence — commit the
+fact, then write the projection — has a window in the middle. A process killed
+inside that window leaves a memory that exists in SQLite, is absent from the
+graph, and is therefore unrecallable, with nothing anywhere recording that it
+happened.
+
+This module is the transactional-outbox side of the answer. A row naming the
+fact is written **inside the same SQLite transaction as the fact itself**, so
+the intent to project is exactly as durable as the fact. A worker later claims
+the row, applies it to Cozo and Lance, and only then deletes it. Killed at any
+point, the row is still there and the work is retried.
+
+WHAT THE ROW CARRIES, AND WHY IT IS SO THIN
+-------------------------------------------
+Only a fact id, a profile, and an intent. Not the entities, not the edges, not
+the embedding. The drain re-reads the fact's current state from SQLite at the
+moment it projects.
+
+That choice buys idempotency for free. Replaying a row can only ever write the
+present truth, so a retry after a crash, a double delivery, and an intent that
+was superseded three times while queued all converge on the same correct
+projection. Serialising a snapshot into the row instead would mean replaying
+stale state over fresh state — the classic outbox bug.
+
+WHY THE PRIMARY KEY IS THE FACT ID
+----------------------------------
+It coalesces. Ten writes to one fact are one unit of work, because the drain
+re-derives everything anyway. It also puts a hard ceiling on the table:
+**at most one row per fact, so the queue can never exceed the store.** That is
+what makes it safe to queue unconditionally on a machine where no projection
+has been built yet — the backlog is bounded by the fact count and is precisely
+the set of facts a future migration needs to project.
+
+LATEST INTENT WINS
+------------------
+``op`` is replaced on conflict rather than appended, so a delete queued after an
+upsert leaves one row saying ``delete``. A queue that kept both would depend on
+draining them in order to avoid resurrecting a forgotten memory; this one cannot
+get that wrong because there is only ever one intent to read.
+
+``revision`` IS A CONCURRENCY TOKEN, NOT A COUNTER
+--------------------------------------------------
+The drain claims a row, spends time in Cozo, then clears it. A write landing in
+that gap must not be discarded. So every enqueue bumps ``revision``, and the
+clear is conditional on the revision the drain claimed. If it moved, the delete
+matches nothing and the new intent stays queued. A timestamp would not do:
+two enqueues inside one clock tick would be indistinguishable.
+
+FAILURE POLICY
+--------------
+``enqueue`` is allowed to raise, and the caller's transaction then rolls back
+the fact along with it. That is deliberate: this is a durability mechanism, and
+a durability mechanism that silently degrades to best-effort is the defect it
+exists to remove. The one expected absence — a store old enough not to have the
+table — is answered by :func:`is_available` rather than by an exception, so an
+un-migrated store keeps working and simply queues nothing.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+from typing import Any
+
+#: The table. Deliberately un-indexed beyond its primary key: the drain reads
+#: it in (attempts, revision) order, and no secondary index serves that, while
+#: every index costs another B-tree write on a path that runs on every store.
+#: The table is bounded by the fact count and its steady-state depth is zero, so
+#: a scan of it is a scan of nothing.
+#:
+#: Applied by ``schema.create_all_tables``, which the engine runs on every init
+#: — so an upgraded store gains the queue on first open with no migration and no
+#: manual step. There is deliberately NO migration for it: a migration can be
+#: skipped, deferred or fail, and if this table is absent then facts silently
+#: stop being projected. The invariant must not be contingent on a pass that can
+#: not run.
+DDL = """
+CREATE TABLE IF NOT EXISTS projection_outbox (
+    fact_id     TEXT PRIMARY KEY,
+    profile_id  TEXT NOT NULL,
+    op          TEXT NOT NULL DEFAULT 'upsert',
+    revision    INTEGER NOT NULL DEFAULT 1,
+    enqueued_at TEXT NOT NULL,
+    attempts    INTEGER NOT NULL DEFAULT 0,
+    last_error  TEXT
+);
+"""
+
+TABLE = "projection_outbox"
+
+#: The depth query, as a constant, because two surfaces need it against two
+#: different kinds of connection and a second copy is how two surfaces come to
+#: disagree about one number.
+DEPTH_SQL = "SELECT COUNT(*) FROM projection_outbox"
+
+OP_UPSERT = "upsert"
+OP_DELETE = "delete"
+
+#: The fact columns a projection is derived from. An update touching none of
+#: these changes nothing Cozo or Lance holds, so it must not queue work.
+#:
+#: ``access_count`` is the one that matters here: recall bumps it on every hit,
+#: so queueing on any update at all would put one row per returned memory per
+#: recall onto the drain worker — a self-inflicted denial of service for a
+#: column neither projection stores.
+PROJECTED_FACT_COLUMNS = frozenset({
+    "embedding",
+    "lifecycle",
+    "canonical_entities_json",
+    "canonical_entities",
+    "profile_id",
+    "scope",
+})
+
+_AVAILABILITY_ATTR = "_projection_outbox_available"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# Availability
+# ---------------------------------------------------------------------------
+
+def is_available(db: Any) -> bool:
+    """Whether this store has an outbox to queue into.
+
+    Cached on the manager after the first look. The table is created at engine
+    init before any fact can be stored, so it cannot appear or vanish part-way
+    through a process in a way that matters; paying a ``sqlite_master`` lookup
+    on every single write to prove that again would be the more expensive
+    mistake.
+    """
+    cached = getattr(db, _AVAILABILITY_ATTR, None)
+    if cached is not None:
+        return bool(cached)
+    try:
+        rows = db.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (TABLE,),
+        )
+        present = bool(rows)
+    except sqlite3.Error:
+        present = False
+    setattr(db, _AVAILABILITY_ATTR, present)
+    return present
+
+
+def forget_availability(db: Any) -> None:
+    """Drop the cached answer, so the next call looks again.
+
+    For the migration that creates the table on a manager already in use, and
+    for tests that remove it to exercise the un-migrated path.
+    """
+    if hasattr(db, _AVAILABILITY_ATTR):
+        delattr(db, _AVAILABILITY_ATTR)
+
+
+# ---------------------------------------------------------------------------
+# Enqueue — runs inside the caller's transaction
+# ---------------------------------------------------------------------------
+
+def enqueue(db: Any, fact_id: str, profile_id: str, op: str = OP_UPSERT) -> None:
+    """Queue one fact to be projected, in the caller's transaction.
+
+    Silent no-op when there is no table (see :func:`is_available`) or when the
+    fact id is empty — an empty id names nothing and would give the drain a row
+    it can never resolve.
+    """
+    if not fact_id or not is_available(db):
+        return
+    db.execute(
+        """INSERT INTO projection_outbox
+               (fact_id, profile_id, op, revision, enqueued_at, attempts, last_error)
+           VALUES (?, ?, ?, 1, ?, 0, NULL)
+           ON CONFLICT(fact_id) DO UPDATE SET
+               op          = excluded.op,
+               profile_id  = excluded.profile_id,
+               revision    = projection_outbox.revision + 1,
+               enqueued_at = excluded.enqueued_at,
+               attempts    = 0,
+               last_error  = NULL""",
+        (fact_id, profile_id or "default", op, _now()),
+    )
+
+
+def enqueue_many(
+    db: Any, fact_ids: object, profile_id: str, op: str = OP_UPSERT,
+) -> None:
+    """Queue several facts. Duplicates in the input collapse to one row each."""
+    if not is_available(db):
+        return
+    for fact_id in dict.fromkeys(fact_ids):
+        enqueue(db, fact_id, profile_id, op)
+
+
+def resolve_profile(db: Any, fact_id: str) -> str | None:
+    """Which tenant a fact belongs to, for a caller that was not told.
+
+    The drain never reads ``profile_id`` off the row — it re-reads the fact. The
+    column exists for one reason: erasure finds a tenant's tables by looking for
+    a ``profile_id`` column, so a row carrying the wrong tenant is a fact id
+    that survives that tenant's erasure. Anyone tempted to drop the column as
+    unused should read that sentence twice.
+
+    Falls back to an existing row's tenant so a re-queue by a caller with less
+    information cannot overwrite a correct answer with a guess.
+    """
+    for sql in (
+        "SELECT profile_id FROM atomic_facts WHERE fact_id = ?",
+        "SELECT profile_id FROM projection_outbox WHERE fact_id = ?",
+    ):
+        try:
+            rows = db.execute(sql, (fact_id,))
+        except sqlite3.Error:
+            continue
+        if rows:
+            found = dict(rows[0]).get("profile_id")
+            if found:
+                return str(found)
+    return None
+
+
+def enqueue_for_fact(db: Any, fact_id: str, op: str = OP_UPSERT) -> None:
+    """Queue a fact whose tenant the caller does not know."""
+    if not fact_id or not is_available(db):
+        return
+    enqueue(db, fact_id, resolve_profile(db, fact_id) or "default", op)
+
+
+# ---------------------------------------------------------------------------
+# Drain
+# ---------------------------------------------------------------------------
+
+def claim_batch(db: Any, limit: int = 200) -> list[dict[str, Any]]:
+    """The next rows to project, oldest intent first.
+
+    Claiming does not mark or lock anything. The row stays visible and stays
+    queued until :func:`resolve` clears it, so a worker that dies mid-batch
+    costs a repeat of work that is idempotent by construction — which is
+    cheaper and far easier to reason about than a lease that can expire while
+    its holder is still alive.
+    """
+    if not is_available(db):
+        return []
+    rows = db.execute(
+        "SELECT fact_id, profile_id, op, revision, attempts, enqueued_at "
+        "FROM projection_outbox ORDER BY attempts, revision LIMIT ?",
+        (int(limit),),
+    )
+    return [dict(r) for r in rows]
+
+
+def resolve(db: Any, fact_id: str, revision: int) -> bool:
+    """Clear a row the projections have accepted. Returns whether it cleared.
+
+    ``False`` means the fact was written again while this projection was in
+    flight, so a newer intent is queued and must not be discarded. The caller
+    does not need to do anything about it — the next drain picks it up.
+    """
+    if not is_available(db):
+        return False
+    db.execute(
+        "DELETE FROM projection_outbox WHERE fact_id = ? AND revision = ?",
+        (fact_id, int(revision)),
+    )
+    remaining = db.execute(
+        "SELECT 1 FROM projection_outbox WHERE fact_id = ? AND revision = ?",
+        (fact_id, int(revision)),
+    )
+    return not remaining
+
+
+def record_failure(db: Any, fact_id: str, error: str) -> int:
+    """Count a failed attempt and keep the row. Returns the new attempt count.
+
+    The row surviving is the whole point: a projection that cannot be written
+    stays visible in :func:`depth` instead of disappearing into a debug log.
+    """
+    if not is_available(db):
+        return 0
+    db.execute(
+        "UPDATE projection_outbox SET attempts = attempts + 1, last_error = ? "
+        "WHERE fact_id = ?",
+        (str(error)[:500], fact_id),
+    )
+    rows = db.execute(
+        "SELECT attempts FROM projection_outbox WHERE fact_id = ?", (fact_id,),
+    )
+    return int(dict(rows[0])["attempts"]) if rows else 0
+
+
+# ---------------------------------------------------------------------------
+# Health
+# ---------------------------------------------------------------------------
+
+def depth(db: Any) -> int:
+    """How many facts are queued and not yet projected.
+
+    Zero is the healthy steady state. A number that does not fall is a
+    projection that has stopped keeping up, which is the failure this whole
+    mechanism exists to make visible rather than silent.
+    """
+    if not is_available(db):
+        return 0
+    try:
+        rows = db.execute(f"{DEPTH_SQL} /* depth */")
+    except sqlite3.Error:
+        return 0
+    return int(tuple(rows[0])[0]) if rows else 0
+
+
+def stalled_count(db: Any, min_attempts: int = 3) -> int:
+    """Queued facts that have already failed to project ``min_attempts`` times.
+
+    Depth alone cannot tell a busy queue from a stuck one. This can: a row with
+    attempts on it has been tried and refused, so any non-zero answer here is a
+    defect with a fact id attached to it.
+    """
+    if not is_available(db):
+        return 0
+    try:
+        rows = db.execute(
+            "SELECT COUNT(*) AS n FROM projection_outbox WHERE attempts >= ?",
+            (int(min_attempts),),
+        )
+    except sqlite3.Error:
+        return 0
+    return int(dict(rows[0])["n"]) if rows else 0
+
+
+def health(db: Any) -> dict[str, Any]:
+    """The outbox as a status surface reads it."""
+    return {
+        "available": is_available(db),
+        "depth": depth(db),
+        "stalled": stalled_count(db),
+    }