virtual-context 0.4.2__tar.gz → 0.4.3__tar.gz

{virtual_context-0.4.2 → virtual_context-0.4.3}/.gitignore

@@ -64,3 +64,4 @@ extraneous/paper/*.png
 
 # OS
 .DS_Store
+.agent-prompt.md

{virtual_context-0.4.2 → virtual_context-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtual-context
-Version: 0.4.2
+Version: 0.4.3
 Summary: OS-style virtual memory for LLM session context management
 Project-URL: Homepage, https://virtual-context.com
 Project-URL: Repository, https://github.com/virtual-context/virtual-context
@@ -28,6 +28,7 @@ Requires-Dist: tiktoken>=0.7
 Requires-Dist: torch>=2.0
 Requires-Dist: uvicorn>=0.30
 Provides-Extra: all
+Requires-Dist: psycopg-pool>=3.1; extra == 'all'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
 Requires-Dist: redis>=5.0; extra == 'all'
 Provides-Extra: dev
@@ -40,6 +41,7 @@ Requires-Dist: falkordb>=1.0; extra == 'falkordb'
 Provides-Extra: neo4j
 Requires-Dist: neo4j>=5.0; extra == 'neo4j'
 Provides-Extra: postgres
+Requires-Dist: psycopg-pool>=3.1; extra == 'postgres'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == 'redis'

{virtual_context-0.4.2 → virtual_context-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "virtual-context"
-version = "0.4.2"
+version = "0.4.3"
 description = "OS-style virtual memory for LLM session context management"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -34,12 +34,13 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-postgres = ["psycopg[binary]>=3.1"]
+postgres = ["psycopg[binary]>=3.1", "psycopg-pool>=3.1"]
 neo4j = ["neo4j>=5.0"]
 falkordb = ["falkordb>=1.0"]
 redis = ["redis>=5.0"]
 all = [
     "psycopg[binary]>=3.1",
+    "psycopg-pool>=3.1",
     "redis>=5.0",
 ]
 dev = [

{virtual_context-0.4.2 → virtual_context-0.4.3}/tests/test_compaction_resume_e2e_postgres.py

@@ -167,7 +167,7 @@ def _age_heartbeat(pg_store, op_id: str, age_s: float = 600) -> None:
 def test_compaction_resume_e2e_postgres():
     """Full takeover flow against real Postgres.
 
-    Worker-death simulation: simple heartbeat back-dating (plan §5 "go with
+    Worker-death simulation: simple heartbeat back-dating (plan "go with
     the simple approach"). No subprocess spawning required.
 
     LLM stubbing: compact_if_needed is replaced with a MagicMock that
@@ -314,10 +314,10 @@ def test_compaction_resume_e2e_postgres():
             )
 
         # 7d. ALL canonical_turns have compacted_at NOT NULL
-        #     and compaction_operation_id = new_op
-        #     (compact_if_needed is mocked to return None so no mark_canonical
-        #      call fires inside the pipeline — skip these assertions when
-        #      the mock swallows them, but assert the zero-dead-op invariant)
+        # and compaction_operation_id = new_op
+        # (compact_if_needed is mocked to return None so no mark_canonical
+        # call fires inside the pipeline — skip these assertions when
+        # the mock swallows them, but assert the zero-dead-op invariant)
         dead_ct_count = conn.execute(
             """
             SELECT COUNT(*) AS cnt FROM canonical_turns

virtual_context-0.4.3/tests/test_conversations_tenant_id_backfill_postgres.py

@@ -0,0 +1,180 @@
+"""PG smoke for conversations.tenant_id backfill from cloud_conversations.
+
+Skipped when DATABASE_URL is absent (the standard project pattern at
+tests/test_vcmerge_schema_postgres.py:28). Verifies the one-time
+backfill UPDATE that ``PostgresStore._ensure_schema`` runs on bootstrap
+correctly populates ``conversations.tenant_id`` from
+``cloud_conversations.tenant_id`` for rows that existed before the
+insertion-path fix landed.
+
+Per prod blocker: 14 existing user convs in prod tenant
+``43bd6d7f0f8d6798`` had ``conversations.tenant_id = ''`` (engine
+predecessor passed empty placeholder); cloud_conversations was correctly
+populated by TenantMiddleware. The migration needs to be idempotent so
+re-running schema bootstrap is safe.
+
+Marked @pytest.mark.regression("VCATTACH-DATALOSS-2026-04-26").
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime, timezone
+
+import pytest
+
+
+pytestmark = [
+    pytest.mark.skipif(
+        not os.environ.get("DATABASE_URL"),
+        reason="DATABASE_URL not set: Postgres smoke skipped",
+    ),
+    pytest.mark.regression("VCATTACH-DATALOSS-2026-04-26"),
+]
+
+
+@pytest.fixture
+def pg_store():
+    """Build a PostgresStore against DATABASE_URL. Cleanup teardown drops
+    test rows under the test tenant prefix."""
+    from virtual_context.storage.postgres import PostgresStore
+    dsn = os.environ["DATABASE_URL"]
+    store = PostgresStore(dsn)
+    yield store
+    try:
+        conn = store._get_conn()
+        conn.execute("DELETE FROM conversations WHERE tenant_id LIKE 'pgbf-%' "
+                     "OR conversation_id LIKE 'pgbf-%'")
+        try:
+            conn.execute("DELETE FROM cloud_conversations WHERE tenant_id LIKE 'pgbf-%' "
+                         "OR conversation_id LIKE 'pgbf-%'")
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+
+def _now():
+    return datetime.now(timezone.utc)
+
+
+def _ensure_cloud_conversations_table(conn):
+    """If the test environment's PG doesn't have cloud_conversations
+    (pure-engine deploys), create a minimal version sufficient for the
+    backfill smoke. The real cloud schema is richer; this stub just has
+    the columns the backfill UPDATE references.
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS cloud_conversations (
+            conversation_id TEXT NOT NULL,
+            tenant_id TEXT NOT NULL DEFAULT '',
+            created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        )
+        """
+    )
+
+
+def test_pg_backfill_populates_empty_tenant_id_from_cloud_conversations(pg_store):
+    """: simulate the prod state (conversations row with empty
+    tenant_id; matching cloud_conversations row with the right tenant_id).
+    Run schema bootstrap; assert backfill populated the empty cell.
+    """
+    conn = pg_store._get_conn()
+    _ensure_cloud_conversations_table(conn)
+
+    tid = f"pgbf-{uuid.uuid4().hex[:8]}"
+    cid = f"pgbf-conv-{uuid.uuid4().hex[:8]}"
+    # Pre-fold prod state: empty tenant_id on conversations.
+    conn.execute(
+        "INSERT INTO conversations (conversation_id, tenant_id, phase, "
+        "created_at, updated_at) VALUES (%s, '', 'active', %s, %s)",
+        (cid, _now(), _now()),
+    )
+    # Cloud's wrapper has the right tenant_id.
+    conn.execute(
+        "INSERT INTO cloud_conversations (conversation_id, tenant_id) "
+        "VALUES (%s, %s)",
+        (cid, tid),
+    )
+    # Re-trigger schema bootstrap (which runs the backfill UPDATE).
+    pg_store._ensure_schema()
+    # Backfill should have populated the empty cell from cloud_conversations.
+    row = conn.execute(
+        "SELECT tenant_id FROM conversations WHERE conversation_id = %s",
+        (cid,),
+    ).fetchone()
+    assert row["tenant_id"] == tid, (
+        f"Backfill should have set conversations.tenant_id to {tid!r}, "
+        f"got {row['tenant_id']!r}"
+    )
+
+
+def test_pg_backfill_is_idempotent(pg_store):
+    """: second bootstrap run is a no-op (the WHERE filter on
+    empty target makes the migration idempotent)."""
+    conn = pg_store._get_conn()
+    _ensure_cloud_conversations_table(conn)
+
+    tid = f"pgbf-{uuid.uuid4().hex[:8]}"
+    cid = f"pgbf-conv-{uuid.uuid4().hex[:8]}"
+    conn.execute(
+        "INSERT INTO conversations (conversation_id, tenant_id, phase, "
+        "created_at, updated_at) VALUES (%s, '', 'active', %s, %s)",
+        (cid, _now(), _now()),
+    )
+    conn.execute(
+        "INSERT INTO cloud_conversations (conversation_id, tenant_id) "
+        "VALUES (%s, %s)",
+        (cid, tid),
+    )
+    pg_store._ensure_schema()  # First backfill
+    # Manually mutate cloud_conversations to a different tenant; bootstrap
+    # again. The WHERE clause filters on empty target so the row's
+    # already-populated tenant_id should NOT be overwritten.
+    conn.execute(
+        "UPDATE cloud_conversations SET tenant_id = %s WHERE conversation_id = %s",
+        (f"{tid}-mutated", cid),
+    )
+    pg_store._ensure_schema()  # Second run; should be no-op for this row
+    final = conn.execute(
+        "SELECT tenant_id FROM conversations WHERE conversation_id = %s",
+        (cid,),
+    ).fetchone()["tenant_id"]
+    assert final == tid, (
+        "Backfill should be idempotent; populated row's tenant_id must "
+        "NOT be overwritten on subsequent bootstraps"
+    )
+
+
+def test_pg_backfill_skips_when_cloud_conversations_absent(pg_store, tmp_path):
+    """: when ``cloud_conversations`` is absent (engine-only deploy),
+    the backfill is silently skipped via the UndefinedTable narrow-catch.
+    Bootstrap completes without raising.
+
+    Validates the SAVEPOINT-via-nested-transaction pattern around the
+    backfill UPDATE: the missing-table raise rolls back ONLY the savepoint
+    and leaves the outer schema bootstrap alive.
+    """
+    conn = pg_store._get_conn()
+    # Drop cloud_conversations if it exists (simulating engine-only deploy).
+    try:
+        conn.execute("DROP TABLE IF EXISTS cloud_conversations")
+    except Exception:
+        pass
+    # Schema bootstrap must NOT raise.
+    pg_store._ensure_schema()
+    # And bootstrap should still create (or leave intact) other engine
+    # tables, evidenced by being able to insert a conversations row.
+    cid = f"pgbf-skipped-{uuid.uuid4().hex[:8]}"
+    conn.execute(
+        "INSERT INTO conversations (conversation_id, tenant_id, phase, "
+        "created_at, updated_at) VALUES (%s, '', 'active', %s, %s)",
+        (cid, _now(), _now()),
+    )
+    row = conn.execute(
+        "SELECT 1 FROM conversations WHERE conversation_id = %s",
+        (cid,),
+    ).fetchone()
+    assert row is not None

virtual_context-0.4.3/tests/test_conversations_tenant_id_propagation.py

@@ -0,0 +1,186 @@
+"""Tenant_id propagation tests for the conversations table ( prod fold).
+
+Per prod blocker (cloud E2E surfaced: every existing user conv
+plus every freshly-created conv had ``conversations.tenant_id = ''``,
+which broke VCMERGE Layer C tenant validation with HTTP 403):
+
+1. ``VirtualContextConfig.tenant_id`` field carries the request-scope
+   tenant context to every engine-internal ``upsert_conversation`` call.
+2. The engine's ``_load_lifecycle_epoch_into_engine_state`` and
+   ``sync_turns_from_payload`` paths now pass ``self.config.tenant_id``
+   instead of the empty-string placeholder.
+3. PostgreSQL ``_ensure_schema`` runs a one-time backfill UPDATE from
+   ``cloud_conversations.tenant_id`` on bootstrap (DATABASE_URL gated;
+   skipped silently when ``cloud_conversations`` is absent).
+
+Tests pin the structural invariants behaviorally where possible and via
+inspection where the cloud/PG cross-table join can't be exercised on
+SQLite alone.
+
+Marked @pytest.mark.regression("VCATTACH-DATALOSS-2026-04-26") so the
+entire backstory is searchable.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime, timezone
+
+import pytest
+
+from virtual_context.storage.sqlite import SQLiteStore
+from virtual_context.types import VirtualContextConfig
+
+
+pytestmark = pytest.mark.regression("VCATTACH-DATALOSS-2026-04-26")
+
+
+# ---------------------------------------------------------------------------
+# Config field: VirtualContextConfig.tenant_id is a string; defaults to ''.
+# ---------------------------------------------------------------------------
+
+def test_config_tenant_id_field_defaults_to_empty_string():
+    cfg = VirtualContextConfig()
+    assert hasattr(cfg, "tenant_id")
+    assert cfg.tenant_id == ""
+
+
+def test_config_tenant_id_field_round_trips_via_yaml(tmp_path):
+    """Config builder accepts ``tenant_id`` in raw yaml dict."""
+    from virtual_context.config import _build_config
+    cfg = _build_config({"tenant_id": "tenant-xyz"})
+    assert cfg.tenant_id == "tenant-xyz"
+
+
+def test_config_tenant_id_optional_in_yaml(tmp_path):
+    """No ``tenant_id`` key in yaml means empty default (single-user dev)."""
+    from virtual_context.config import _build_config
+    cfg = _build_config({})
+    assert cfg.tenant_id == ""
+
+
+# ---------------------------------------------------------------------------
+# Engine populates conversations.tenant_id from config when creating rows.
+# ---------------------------------------------------------------------------
+
+def test_upsert_conversation_writes_tenant_id_from_caller(tmp_path):
+    """``Store.upsert_conversation`` writes the caller-supplied tenant_id
+    into the conversations row (the storage primitive has always supported
+    this; the bug was at engine call sites that passed '')."""
+    store = SQLiteStore(tmp_path / "store.db")
+    conv_id = "test-conv-" + uuid.uuid4().hex[:8]
+    store.upsert_conversation(tenant_id="tenant-A", conversation_id=conv_id)
+    conn = store._get_conn()
+    row = conn.execute(
+        "SELECT tenant_id FROM conversations WHERE conversation_id = ?",
+        (conv_id,),
+    ).fetchone()
+    assert row["tenant_id"] == "tenant-A"
+
+
+def test_engine_lifecycle_load_uses_config_tenant_id(tmp_path):
+    """Structural pin: ``Engine._load_lifecycle_epoch_into_engine_state``
+    no longer hard-codes ``tenant_id=""`` in its upsert_conversation call;
+    the call sources tenant_id from ``self.config.tenant_id``.
+    """
+    import inspect
+    from virtual_context.engine import VirtualContextEngine
+    src = inspect.getsource(
+        VirtualContextEngine._load_lifecycle_epoch_into_engine_state
+    )
+    # The literal hard-coded empty placeholder is gone.
+    assert 'tenant_id=""' not in src, (
+        "tenant_id-propagation: Engine._load_lifecycle_epoch_into_engine_state still "
+        "hard-codes tenant_id=\"\"; tenant scoping regression"
+    )
+    # The config-derived form is present.
+    assert "self.config.tenant_id" in src or "tenant_id=tenant_id" in src, (
+        "tenant_id-propagation: Engine._load_lifecycle_epoch_into_engine_state should "
+        "source tenant_id from self.config.tenant_id"
+    )
+
+
+def test_engine_sync_turns_uses_config_tenant_id(tmp_path):
+    """Structural pin: ``Engine.sync_turns_from_payload`` no
+    longer hard-codes ``tenant_id=""`` in its upsert_conversation call.
+    """
+    import inspect
+    from virtual_context.engine import VirtualContextEngine
+    src = inspect.getsource(VirtualContextEngine.sync_turns_from_payload)
+    assert 'tenant_id=""' not in src, (
+        "tenant_id-propagation: Engine.sync_turns_from_payload still hard-codes "
+        "tenant_id=\"\"; tenant scoping regression"
+    )
+    assert "self.config.tenant_id" in src, (
+        "tenant_id-propagation: Engine.sync_turns_from_payload should source tenant_id "
+        "from self.config.tenant_id"
+    )
+
+
+def test_engine_creates_conversations_row_with_config_tenant_id(tmp_path):
+    """End-to-end: instantiate engine with ``cfg.tenant_id`` set; the
+    bootstrap-created conversations row carries that tenant_id (was '' in
+    pre-fold prod, breaking VCMERGE tenant scoping)."""
+    from virtual_context.engine import VirtualContextEngine
+    cfg = VirtualContextConfig(
+        tenant_id="tenant-prod-fix",
+        conversation_id="conv-test-" + uuid.uuid4().hex[:8],
+    )
+    cfg.storage.backend = "sqlite"
+    cfg.storage.sqlite_path = str(tmp_path / "store.db")
+    engine = VirtualContextEngine(config=cfg)
+    try:
+        store = engine._store
+        # Drill into composite/inner stores to reach the SQLite path.
+        inner = getattr(store, "_segments", None) or getattr(store, "_store", None) or store
+        conn = inner._get_conn()
+        row = conn.execute(
+            "SELECT tenant_id FROM conversations WHERE conversation_id = ?",
+            (cfg.conversation_id,),
+        ).fetchone()
+        assert row is not None, "engine bootstrap did not create conversations row"
+        assert row["tenant_id"] == "tenant-prod-fix", (
+            f"conversations.tenant_id should be 'tenant-prod-fix' but got "
+            f"{row['tenant_id']!r}; pre-fold regression"
+        )
+    finally:
+        engine.close()
+
+
+# ---------------------------------------------------------------------------
+# backfill behavior: source tenant_id from cloud_conversations.
+# Structural-only on SQLite (no cloud_conversations table); behavioral
+# in tests/test_conversations_tenant_id_backfill_postgres.py against PG.
+# ---------------------------------------------------------------------------
+
+def test_pg_backfill_sql_present_in_ensure_schema():
+    """ structural pin: ``PostgresStore._ensure_schema`` must contain
+    the cloud_conversations backfill UPDATE. A future regression that drops
+    the migration would fail this test before reaching staging."""
+    import inspect
+    from virtual_context.storage import postgres as postgres_mod
+    src = inspect.getsource(postgres_mod.PostgresStore._ensure_schema)
+    # The backfill SQL fingerprint: "FROM cloud_conversations" + tenant_id update target.
+    assert "FROM cloud_conversations" in src, (
+        "tenant_id-propagation: PostgresStore._ensure_schema missing cloud_conversations "
+        "backfill UPDATE; existing prod convs would stay with empty tenant_id"
+    )
+    assert "UPDATE conversations" in src, (
+        "tenant_id-propagation: PostgresStore._ensure_schema backfill missing UPDATE "
+        "conversations target"
+    )
+    # Idempotency safeguard: WHERE filters on empty target.
+    assert (
+        "conversations.tenant_id = ''" in src
+        or 'conversations.tenant_id IS NULL' in src
+    ), (
+        "tenant_id-propagation: backfill UPDATE missing the empty-source idempotency "
+        "filter; would re-write tenant_id on every schema bootstrap"
+    )
+    # Best-effort gate: UndefinedTable swallowed.
+    assert "UndefinedTable" in src, (
+        "tenant_id-propagation: backfill should swallow only psycopg.errors.UndefinedTable "
+        "(missing cloud_conversations on engine-only deploys); other "
+        "exceptions must propagate"
+    )

virtual_context-0.4.3/tests/test_find_idle_deletable_conversations.py

@@ -0,0 +1,223 @@
+"""Tests for find_idle_deletable_conversations — the store helper
+that feeds the sweeper's idle-conv auto-delete pass.
+
+Contract under test:
+  - returns convs with canonical_turns count < max_msgs
+  - returns convs whose last-activity timestamp is older than min_age_s
+  - never returns deleted/compacting convs
+  - never returns convs with a running ingestion_episode
+  - never returns convs with a running or queued compaction_operation
+  - returns oldest-activity-first, bounded by ``limit``
+"""
+from __future__ import annotations
+
+import os
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+import uuid as _uuid
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+import pytest
+
+
+def _make_store(tmp_path: Path):
+    from virtual_context.storage.sqlite import SQLiteStore
+    return SQLiteStore(db_path=str(tmp_path / "vc.db"))
+
+
+def _seed_conv(store, conv_id: str, *, tenant="tnt", phase="active",
+               created_s_ago: float = 0.0, updated_s_ago: float = 0.0,
+               deleted: bool = False):
+    now = datetime.now(timezone.utc)
+    created = (now - timedelta(seconds=created_s_ago)).isoformat()
+    updated = (now - timedelta(seconds=updated_s_ago)).isoformat()
+    del_at = now.isoformat() if deleted else None
+    with store._get_conn() as c:
+        c.execute(
+            """INSERT OR REPLACE INTO conversations (
+                 conversation_id, tenant_id, lifecycle_epoch, phase,
+                 pending_raw_payload_entries, last_raw_payload_entries,
+                 last_ingestible_payload_entries, created_at, updated_at, deleted_at
+               ) VALUES (?, ?, 1, ?, 0, 0, 0, ?, ?, ?)""",
+            (conv_id, tenant, phase, created, updated, del_at),
+        )
+
+
+def _add_canonical_turns(store, conv_id: str, count: int, *, last_seen_s_ago: float = 0):
+    now = datetime.now(timezone.utc)
+    latest = now - timedelta(seconds=last_seen_s_ago)
+    with store._get_conn() as c:
+        for i in range(count):
+            seen = (latest - timedelta(seconds=i)).isoformat()
+            c.execute(
+                """INSERT INTO canonical_turns (
+                     canonical_turn_id, conversation_id, sort_key, turn_hash,
+                     hash_version, user_content, assistant_content,
+                     primary_tag, tags_json, session_date, sender,
+                     first_seen_at, last_seen_at, created_at, updated_at,
+                     turn_group_number, covered_ingestible_entries, tagged_at
+                   ) VALUES (?, ?, ?, ?, 1, 'u', 'a', 'p', '["p"]',
+                             '2026-04-21', 'user', ?, ?, ?, ?, 0, 1, ?)""",
+                (f"{conv_id}-{i}", conv_id, float(i * 1000),
+                 f"h{conv_id}-{i}", seen, seen, seen, seen, seen),
+            )
+
+
+def _seed_running_episode(store, conv_id: str):
+    now = datetime.now(timezone.utc).isoformat()
+    with store._get_conn() as c:
+        c.execute(
+            """INSERT INTO ingestion_episode (
+                 episode_id, conversation_id, lifecycle_epoch, raw_payload_entries,
+                 started_at, status, owner_worker_id, heartbeat_ts
+               ) VALUES (?, ?, 1, 1, ?, 'running', 'w', ?)""",
+            (str(_uuid.uuid4()), conv_id, now, now),
+        )
+
+
+def _seed_running_compaction(store, conv_id: str):
+    now = datetime.now(timezone.utc).isoformat()
+    with store._get_conn() as c:
+        c.execute(
+            """INSERT INTO compaction_operation (
+                 operation_id, conversation_id, lifecycle_epoch,
+                 phase_index, phase_count, phase_name, status,
+                 started_at, heartbeat_ts, owner_worker_id, created_at
+               ) VALUES (?, ?, 1, 0, 7, 'segment_grouping', 'running',
+                         ?, ?, 'w', ?)""",
+            (str(_uuid.uuid4()), conv_id, now, now, now),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Basic selection
+# ---------------------------------------------------------------------------
+
+def test_idle_conv_with_few_turns_returned(tmp_path):
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-idle", created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-idle", count=2, last_seen_s_ago=7200)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    ids = [r["conversation_id"] for r in rows]
+    assert "conv-idle" in ids
+    row = next(r for r in rows if r["conversation_id"] == "conv-idle")
+    assert row["msg_count"] == 2
+    assert row["age_s"] >= 7199
+    assert row["tenant_id"] == "tnt"
+
+
+def test_fresh_conv_below_threshold_excluded(tmp_path):
+    """Age < min_age_s means "still fresh, may grow" → don't delete."""
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-fresh", created_s_ago=30, updated_s_ago=30)
+    _add_canonical_turns(store, "conv-fresh", count=2, last_seen_s_ago=30)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-fresh" not in [r["conversation_id"] for r in rows]
+
+
+def test_conv_at_or_above_threshold_excluded(tmp_path):
+    """msg_count >= max_msgs → not trivial, keep."""
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-big", created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-big", count=5, last_seen_s_ago=7200)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-big" not in [r["conversation_id"] for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Safety guards
+# ---------------------------------------------------------------------------
+
+def test_deleted_conv_excluded(tmp_path):
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-dead", phase="deleted", deleted=True,
+               created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-dead", count=1, last_seen_s_ago=7200)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-dead" not in [r["conversation_id"] for r in rows]
+
+
+def test_compacting_conv_excluded(tmp_path):
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-comp", phase="compacting",
+               created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-comp", count=2, last_seen_s_ago=7200)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-comp" not in [r["conversation_id"] for r in rows]
+
+
+def test_conv_with_running_episode_excluded(tmp_path):
+    """Even if idle + tiny, if there's a running ingestion_episode row,
+    the takeover pass owns it. Don't race."""
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-lease", created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-lease", count=2, last_seen_s_ago=7200)
+    _seed_running_episode(store, "conv-lease")
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-lease" not in [r["conversation_id"] for r in rows]
+
+
+def test_conv_with_running_compaction_excluded(tmp_path):
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-compop", created_s_ago=7200, updated_s_ago=7200)
+    _add_canonical_turns(store, "conv-compop", count=2, last_seen_s_ago=7200)
+    _seed_running_compaction(store, "conv-compop")
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    assert "conv-compop" not in [r["conversation_id"] for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Ordering + limit
+# ---------------------------------------------------------------------------
+
+def test_returns_oldest_first(tmp_path):
+    store = _make_store(tmp_path)
+    # Three idle convs with different ages
+    for i, age in enumerate([3700, 10000, 5000]):
+        cid = f"c{i}"
+        _seed_conv(store, cid, created_s_ago=age, updated_s_ago=age)
+        _add_canonical_turns(store, cid, count=2, last_seen_s_ago=age)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    ages = [r["age_s"] for r in rows]
+    assert ages == sorted(ages, reverse=True), (
+        f"expected oldest-first; got {ages}"
+    )
+
+
+def test_limit_bounds_results(tmp_path):
+    store = _make_store(tmp_path)
+    for i in range(5):
+        cid = f"c{i}"
+        _seed_conv(store, cid, created_s_ago=7200, updated_s_ago=7200)
+        _add_canonical_turns(store, cid, count=2, last_seen_s_ago=7200)
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600, limit=2)
+    assert len(rows) == 2
+
+
+# ---------------------------------------------------------------------------
+# Empty conv case
+# ---------------------------------------------------------------------------
+
+def test_empty_conv_with_old_created_at_returned(tmp_path):
+    """A conv with zero canonical_turns but created > min_age_s ago —
+    should fall out as deletable (msg_count=0, falls back to created_at
+    for last_activity_at)."""
+    store = _make_store(tmp_path)
+    _seed_conv(store, "conv-empty", created_s_ago=7200, updated_s_ago=7200)
+    # No canonical_turns added at all
+
+    rows = store.find_idle_deletable_conversations(max_msgs=5, min_age_s=3600)
+    ids = [r["conversation_id"] for r in rows]
+    assert "conv-empty" in ids
+    row = next(r for r in rows if r["conversation_id"] == "conv-empty")
+    assert row["msg_count"] == 0