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

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

@@ -8,6 +8,9 @@ build/
 # Virtual environment
 .venv/
 
+# Infrastructure configs (contains secrets — never commit)
+infrastructure/
+
 # Testing
 .pytest_cache/
 
@@ -27,15 +30,22 @@ scripts/*
 !scripts/install.ps1
 !scripts/install.sh
 
+# Environment files (API keys)
+.env
+
 # Config files (may contain API keys)
 virtual-context-*.yaml
 !virtual-context.yaml.example
 
 # Internal docs
 CHANGELOG.md
+CLAUDE.md
 docs/superpowers/
 docs/competitive-analysis.md
 diagnostics/
+specs/
+tests_timing_report.md
+tests_by_section.sh
 uv.lock
 extraneous/paper/virtual_context_paper_latest.md
 extraneous/paper/data/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtual-context
-Version: 0.3.8
+Version: 0.4.2
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "virtual-context"
-version = "0.3.8"
+version = "0.4.2"
 description = "OS-style virtual memory for LLM session context management"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -67,6 +67,15 @@ exclude = [
     ".virtualcontext/",
     "*.db",
     "*.log",
+    # Internal / private — never ship in sdist
+    "CLAUDE.md",
+    "tests_timing_report.md",
+    "tests_by_section.sh",
+    "specs/",
+    "virtual-context.yaml",
+    ".github/",
+    ".gitignore",
+    ".worktrees/",
 ]
 artifacts = [
     "virtual_context/proxy/static/*",

{virtual_context-0.3.8 → virtual_context-0.4.2}/tests/haiku/test_compaction.py

@@ -94,8 +94,8 @@ class TestCompactionCycle:
             history = _simulate_turns(engine, pairs)
 
             # Compaction should have fired
-            assert engine._engine_state.compacted_through > 0, (
-                f"Expected compaction, but _compacted_through={engine._engine_state.compacted_through}"
+            assert engine._engine_state.compacted_prefix_messages > 0, (
+                f"Expected compaction, but _compacted_through={engine._engine_state.compacted_prefix_messages}"
             )
 
             # Post-compaction retrieval should still work
@@ -204,7 +204,7 @@ class TestCompactionCycle:
             history = _simulate_turns(engine, pairs)
 
             # Should have compacted multiple times
-            assert engine._engine_state.compacted_through > 0
+            assert engine._engine_state.compacted_prefix_messages > 0
 
             # Engine should still respond without errors
             result = engine.on_message_inbound("What topics did we cover?", history)

virtual_context-0.4.2/tests/test_active_compaction_op_invariants.py

@@ -0,0 +1,172 @@
+"""Task 16: ProxyState._active_compaction_op four-site lifecycle invariant.
+
+Tests:
+  18a: test_takeover_sets_active_compaction_op_before_submit
+  18b: test_wrapper_finally_clears_active_compaction_op_on_normal_exit
+  18c: test_wrapper_finally_clears_active_compaction_op_on_exception
+  18d: test_submit_exception_clears_active_compaction_op  (regression guard)
+
+Test 18e (same-worker re-enter after submit exception) is deferred to
+tests/test_compacting_phase_takeover.py (Task 18) because it requires the
+handle_prepare_payload compacting-branch takeover wiring that Task 18 adds.
+"""
+from __future__ import annotations
+
+import os
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+from concurrent.futures import Future
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# 18a: _submit_compaction_request sets _active_compaction_op BEFORE submitting
+# the future when preexisting_operation_id is provided.
+# ---------------------------------------------------------------------------
+
+def test_takeover_sets_active_compaction_op_before_submit(tmp_path: Path):
+    """_active_compaction_op must be set to preexisting_operation_id before
+    the thread-pool submit call so the takeover predicate is already live if
+    a concurrent worker checks between set and submit.
+    """
+    from tests.test_handle_prepare_payload import _make_proxy_state
+
+    state = _make_proxy_state(tmp_path)
+
+    captured_op_at_submit: list[str | None] = []
+
+    original_submit = state._compact_pool.submit
+
+    def capturing_submit(fn, *args, **kwargs):
+        # Capture the value of _active_compaction_op at the moment submit fires
+        captured_op_at_submit.append(state._active_compaction_op)
+        # Return a done future so the wrapper doesn't block
+        f: Future[None] = Future()
+        f.set_result(None)
+        return f
+
+    with patch.object(state._compact_pool, "submit", side_effect=capturing_submit), \
+         patch.object(state, "_run_compact_wrapper"):
+        state._submit_compaction_request(
+            history=[],
+            signal=None,
+            turn=0,
+            target_end=5,
+            turn_id="",
+            preexisting_operation_id="op-abc-123",
+        )
+
+    assert len(captured_op_at_submit) == 1, "submit must be called exactly once"
+    assert captured_op_at_submit[0] == "op-abc-123", (
+        f"_active_compaction_op must equal preexisting_operation_id at submit time, "
+        f"got {captured_op_at_submit[0]!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 18b: _run_compact_wrapper finally clears _active_compaction_op on normal exit
+# ---------------------------------------------------------------------------
+
+def test_wrapper_finally_clears_active_compaction_op_on_normal_exit(tmp_path: Path):
+    """After _run_compact_wrapper returns normally, _active_compaction_op must
+    be None regardless of what it was set to before the call.
+    """
+    from tests.test_handle_prepare_payload import _make_proxy_state
+
+    state = _make_proxy_state(tmp_path)
+    state._active_compaction_op = "op-should-be-cleared"
+
+    with patch.object(state, "_run_compact", return_value=None):
+        state._run_compact_wrapper(
+            history=[],
+            signal=None,
+            turn=0,
+            target_end=5,
+            turn_id="",
+            preexisting_operation_id="op-should-be-cleared",
+        )
+
+    assert state._active_compaction_op is None, (
+        f"_active_compaction_op must be None after wrapper normal exit, "
+        f"got {state._active_compaction_op!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 18c: _run_compact_wrapper finally clears _active_compaction_op on exception
+# ---------------------------------------------------------------------------
+
+def test_wrapper_finally_clears_active_compaction_op_on_exception(tmp_path: Path):
+    """Even when _run_compact raises, _run_compact_wrapper's finally block must
+    clear _active_compaction_op so future takeover checks are not blocked.
+    """
+    from tests.test_handle_prepare_payload import _make_proxy_state
+
+    state = _make_proxy_state(tmp_path)
+    state._active_compaction_op = "op-raise-case"
+
+    with patch.object(state, "_run_compact", side_effect=RuntimeError("boom")):
+        # The wrapper must NOT re-raise (it already swallows exceptions via
+        # the existing try/finally structure — the finally still runs).
+        try:
+            state._run_compact_wrapper(
+                history=[],
+                signal=None,
+                turn=0,
+                target_end=5,
+                turn_id="",
+                preexisting_operation_id="op-raise-case",
+            )
+        except Exception:
+            # Whether the wrapper propagates or swallows, _active_compaction_op
+            # must be None after the call returns/raises.
+            pass
+
+    assert state._active_compaction_op is None, (
+        f"_active_compaction_op must be None after wrapper exception exit, "
+        f"got {state._active_compaction_op!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# 18d: submit exception clears _active_compaction_op (CRITICAL regression guard)
+# ---------------------------------------------------------------------------
+
+def test_submit_exception_clears_active_compaction_op(tmp_path: Path):
+    """If the thread-pool submit() call itself raises (e.g. pool shutdown),
+    _submit_compaction_request must clear _active_compaction_op back to None
+    so subsequent requests are not permanently blocked by a stale op-id.
+
+    This is the regression guard: without the except-clause cleanup, a pool
+    shutdown exception would leave _active_compaction_op set forever and every
+    future takeover check would see a non-None value for an operation that
+    never ran.
+    """
+    from tests.test_handle_prepare_payload import _make_proxy_state
+
+    state = _make_proxy_state(tmp_path)
+
+    assert state._active_compaction_op is None, "pre-condition: starts as None"
+
+    with patch.object(
+        state._compact_pool,
+        "submit",
+        side_effect=RuntimeError("pool is shut down"),
+    ):
+        with pytest.raises(RuntimeError, match="pool is shut down"):
+            state._submit_compaction_request(
+                history=[],
+                signal=None,
+                turn=0,
+                target_end=5,
+                turn_id="",
+                preexisting_operation_id="op-submit-fail",
+            )
+
+    assert state._active_compaction_op is None, (
+        f"_active_compaction_op must be reset to None after submit() raises, "
+        f"got {state._active_compaction_op!r}"
+    )

virtual_context-0.4.2/tests/test_canonical_row_epoch_guards.py

@@ -0,0 +1,224 @@
+"""Tests for epoch-guarded ``iter_untagged_canonical_rows`` +
+``mark_canonical_row_tagged`` on the SQLite backend.
+
+Both methods scope their SQL to ``conversations.lifecycle_epoch`` so a stale
+caller (whose in-memory epoch no longer matches the authoritative row) sees
+zero rows on iter and a ``False`` return on mark. This keeps concurrent
+delete/resurrect workflows from letting a background tagger touch rows that
+belong to a new lifecycle.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from virtual_context.storage.sqlite import SQLiteStore
+from virtual_context.core.canonical_turns import utcnow_iso
+
+
+def _seed_canonical_row(
+    s: SQLiteStore,
+    *,
+    conv_id: str,
+    canonical_id: str,
+    sort_key: float,
+    tagged: bool = False,
+) -> None:
+    now = utcnow_iso()
+    with s._get_conn() as conn:
+        conn.execute(
+            """
+            INSERT INTO canonical_turns (
+                canonical_turn_id, conversation_id, turn_hash, hash_version,
+                normalized_user_text, normalized_assistant_text,
+                user_content, assistant_content,
+                sort_key, source_batch_id, first_seen_at, last_seen_at,
+                covered_ingestible_entries, tagged_at,
+                created_at, updated_at
+            ) VALUES (?, ?, ?, 1, 'u','a','u_raw','a_raw', ?, 'b', ?, ?, 1, ?, ?, ?)
+            """,
+            (
+                canonical_id,
+                conv_id,
+                f"h_{canonical_id}",
+                sort_key,
+                now,
+                now,
+                now if tagged else None,
+                now,
+                now,
+            ),
+        )
+
+
+def test_iter_untagged_returns_untagged_in_sort_key_order(tmp_path: Path) -> None:
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t0", sort_key=3000.0)
+    _seed_canonical_row(s, conv_id="c", canonical_id="t1", sort_key=1000.0)
+    _seed_canonical_row(s, conv_id="c", canonical_id="t2", sort_key=2000.0)
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id="c", expected_lifecycle_epoch=1, batch_size=10,
+    )
+    ids_in_order = [r.canonical_turn_id for r in rows]
+    assert ids_in_order == ["t1", "t2", "t0"]  # sorted by sort_key
+
+
+def test_iter_untagged_respects_batch_size(tmp_path: Path) -> None:
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    for i in range(5):
+        _seed_canonical_row(s, conv_id="c", canonical_id=f"t{i}", sort_key=float(i * 1000))
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id="c", expected_lifecycle_epoch=1, batch_size=2,
+    )
+    assert len(rows) == 2
+
+
+def test_iter_untagged_excludes_tagged_rows(tmp_path: Path) -> None:
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t_tagged", sort_key=1000.0, tagged=True)
+    _seed_canonical_row(s, conv_id="c", canonical_id="t_pending", sort_key=2000.0, tagged=False)
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id="c", expected_lifecycle_epoch=1, batch_size=10,
+    )
+    assert [r.canonical_turn_id for r in rows] == ["t_pending"]
+
+
+def test_iter_untagged_returns_empty_on_epoch_mismatch(tmp_path: Path) -> None:
+    """SQL-level epoch guard. Stale-epoch caller sees no rows even if rows exist."""
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t0", sort_key=1000.0)
+    s.mark_conversation_deleted("c")
+    s.increment_lifecycle_epoch_on_resurrect("c")  # epoch=2
+    # Seed a new-lifecycle row.
+    _seed_canonical_row(s, conv_id="c", canonical_id="t_new", sort_key=2000.0)
+    # Stale caller: epoch=1.
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id="c", expected_lifecycle_epoch=1, batch_size=10,
+    )
+    assert rows == []  # sees nothing
+    # Current caller: epoch=2 — sees both (t0 from old lifecycle not purged, plus t_new).
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id="c", expected_lifecycle_epoch=2, batch_size=10,
+    )
+    assert len(rows) == 2
+
+
+def test_mark_canonical_row_tagged_sets_timestamp(tmp_path: Path) -> None:
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t_pending", sort_key=1000.0)
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id="t_pending", conversation_id="c",
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is True
+    with s._get_conn() as conn:
+        row = conn.execute(
+            "SELECT tagged_at FROM canonical_turns WHERE canonical_turn_id='t_pending'"
+        ).fetchone()
+    assert row[0] is not None
+
+
+def test_mark_canonical_row_tagged_rejects_on_epoch_mismatch(tmp_path: Path) -> None:
+    """Proves SQL-level epoch guard on the mark boundary."""
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t0", sort_key=1000.0)
+    s.mark_conversation_deleted("c")
+    s.increment_lifecycle_epoch_on_resurrect("c")  # epoch=2
+    # Stale caller tries to mark a row that still exists.
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id="t0", conversation_id="c",
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False
+    with s._get_conn() as conn:
+        row = conn.execute(
+            "SELECT tagged_at FROM canonical_turns WHERE canonical_turn_id='t0'"
+        ).fetchone()
+    assert row[0] is None  # untouched
+
+
+def test_mark_canonical_row_tagged_is_idempotent_for_already_tagged(tmp_path: Path) -> None:
+    """Calling mark_canonical_row_tagged a second time on an already-tagged row returns False (no-op)."""
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    _seed_canonical_row(s, conv_id="c", canonical_id="t0", sort_key=1000.0, tagged=True)
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id="t0", conversation_id="c",
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False  # already tagged, WHERE tagged_at IS NULL excludes it
+
+
+def test_mark_canonical_row_tagged_wrong_conversation_id_returns_false(tmp_path: Path) -> None:
+    """Belt-and-suspenders: mismatched conversation_id doesn't accidentally mark another conversation's row."""
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c1")
+    s.upsert_conversation(tenant_id="t", conversation_id="c2")
+    _seed_canonical_row(s, conv_id="c1", canonical_id="t0", sort_key=1000.0)
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id="t0", conversation_id="c2",  # wrong conv
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False
+
+
+def test_iter_untagged_uses_partial_index(tmp_path: Path) -> None:
+    """``iter_untagged_canonical_rows`` must drive the partial index
+    ``idx_canonical_turns_conv_untagged`` and NOT fall back to a full scan.
+
+    The A19 implementation originally routed through the
+    ``canonical_turns_ordinal`` VIEW so the row parser could read
+    ``row["turn_number"]``. SQLite's planner cannot push the partial index
+    through the view's ``ROW_NUMBER()`` co-routine, producing a plan like
+    ``CO-ROUTINE canonical_turns_ordinal + SCAN ct + USE TEMP B-TREE FOR
+    ORDER BY`` — O(all rows in conversation) regardless of
+    ``tagged_at``. The tagger calls this in a tight loop; missing the index
+    is the regression this test locks in.
+    """
+    s = SQLiteStore(tmp_path / "vc.db")
+    s.upsert_conversation(tenant_id="t", conversation_id="c")
+    with s._get_conn() as conn:
+        plan = list(conn.execute(
+            """
+            EXPLAIN QUERY PLAN
+            SELECT ct.canonical_turn_id, ct.conversation_id, ct.turn_group_number,
+                   ct.sort_key, ct.turn_hash, ct.hash_version,
+                   ct.normalized_user_text, ct.normalized_assistant_text,
+                   ct.user_content, ct.assistant_content,
+                   ct.user_raw_content, ct.assistant_raw_content,
+                   ct.primary_tag, ct.tags_json, ct.session_date, ct.sender,
+                   ct.fact_signals_json, ct.code_refs_json,
+                   ct.tagged_at, ct.compacted_at,
+                   ct.first_seen_at, ct.last_seen_at,
+                   ct.source_batch_id, ct.created_at, ct.updated_at
+              FROM canonical_turns AS ct
+              JOIN conversations AS c
+                ON c.conversation_id = ct.conversation_id
+             WHERE ct.conversation_id = ?
+               AND ct.tagged_at IS NULL
+               AND c.lifecycle_epoch = ?
+             ORDER BY ct.sort_key ASC
+             LIMIT ?
+            """,
+            ("c", 1, 10),
+        ).fetchall())
+    detail = " | ".join(str(tuple(row)) for row in plan)
+    assert "idx_canonical_turns_conv_untagged" in detail, (
+        f"iter_untagged_canonical_rows is not using the partial index. "
+        f"Plan was: {detail}"
+    )
+    # Also guard against the view regression: a plan that mentions
+    # ``canonical_turns_ordinal`` or ``TEMP B-TREE FOR ORDER BY`` means we
+    # fell back to the view path and lost the index.
+    assert "canonical_turns_ordinal" not in detail, (
+        f"Query must not route through the view. Plan was: {detail}"
+    )
+    assert "TEMP B-TREE FOR ORDER BY" not in detail, (
+        f"Query must not fall back to a temp sort. Plan was: {detail}"
+    )

virtual_context-0.4.2/tests/test_canonical_row_epoch_guards_postgres.py

@@ -0,0 +1,200 @@
+"""Tests for epoch-guarded ``iter_untagged_canonical_rows`` +
+``mark_canonical_row_tagged`` on the Postgres backend.
+
+Skipped unless ``VC_TEST_POSTGRES_URL`` is set. Mirrors
+``test_canonical_row_epoch_guards.py`` (SQLite) 1:1 so both backends stay in
+lockstep on the SQL-level epoch fence. ``conversations.conversation_id`` is
+``TEXT PRIMARY KEY`` (aligned with ``canonical_turns.conversation_id``), and
+``canonical_turns.canonical_turn_id`` is ``UUID``, so test conversation IDs
+use ``str(uuid.uuid4())`` and canonical IDs use ``uuid.uuid4()``.
+``source_batch_id`` is also UUID, so the seed helper generates a fresh UUID
+per row. psycopg3 adapts ``datetime`` directly so we pass
+``datetime.now(timezone.utc)`` rather than ISO strings for the
+``TIMESTAMPTZ`` lifecycle columns on ``canonical_turns`` — except that
+``tagged_at`` / ``first_seen_at`` / ``last_seen_at`` / ``created_at`` /
+``updated_at`` on ``canonical_turns`` are ``TEXT`` in the Postgres schema
+(not TIMESTAMPTZ), so ISO strings are the right shape for those.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime, timezone
+
+import pytest
+
+PG_URL = os.environ.get("VC_TEST_POSTGRES_URL")
+pytestmark = pytest.mark.skipif(not PG_URL, reason="VC_TEST_POSTGRES_URL not set")
+
+
+def _store():
+    from virtual_context.storage.postgres import PostgresStore  # deferred
+    return PostgresStore(PG_URL)
+
+
+def _fresh(conv_id: str | None = None):
+    """Create a fresh conversation with a unique UUID and return (store, conv_id)."""
+    conv_id = conv_id or str(uuid.uuid4())
+    s = _store()
+    s.upsert_conversation(tenant_id="t", conversation_id=conv_id)
+    return s, conv_id
+
+
+def _seed_canonical_row(
+    s,
+    *,
+    conv_id: str,
+    canonical_id: str,
+    sort_key: float,
+    tagged: bool = False,
+) -> None:
+    now_iso = datetime.now(timezone.utc).isoformat()
+    conn = s._get_conn()
+    conn.execute(
+        """
+        INSERT INTO canonical_turns (
+            canonical_turn_id, conversation_id, turn_hash, hash_version,
+            normalized_user_text, normalized_assistant_text,
+            user_content, assistant_content,
+            sort_key, source_batch_id, first_seen_at, last_seen_at,
+            covered_ingestible_entries, tagged_at,
+            created_at, updated_at
+        ) VALUES (%s, %s, %s, 1, 'u','a','u_raw','a_raw', %s, %s, %s, %s, 1, %s, %s, %s)
+        """,
+        (
+            canonical_id,
+            conv_id,
+            f"h_{canonical_id}",
+            sort_key,
+            uuid.uuid4(),  # source_batch_id (UUID)
+            now_iso,
+            now_iso,
+            now_iso if tagged else None,
+            now_iso,
+            now_iso,
+        ),
+    )
+
+
+def test_iter_untagged_returns_untagged_in_sort_key_order_pg():
+    s, cid = _fresh()
+    ids = [str(uuid.uuid4()) for _ in range(3)]
+    _seed_canonical_row(s, conv_id=cid, canonical_id=ids[0], sort_key=3000.0)
+    _seed_canonical_row(s, conv_id=cid, canonical_id=ids[1], sort_key=1000.0)
+    _seed_canonical_row(s, conv_id=cid, canonical_id=ids[2], sort_key=2000.0)
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id=cid, expected_lifecycle_epoch=1, batch_size=10,
+    )
+    ids_in_order = [r.canonical_turn_id for r in rows]
+    assert ids_in_order == [ids[1], ids[2], ids[0]]  # sorted by sort_key
+
+
+def test_iter_untagged_respects_batch_size_pg():
+    s, cid = _fresh()
+    for i in range(5):
+        _seed_canonical_row(
+            s, conv_id=cid, canonical_id=str(uuid.uuid4()),
+            sort_key=float(i * 1000),
+        )
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id=cid, expected_lifecycle_epoch=1, batch_size=2,
+    )
+    assert len(rows) == 2
+
+
+def test_iter_untagged_excludes_tagged_rows_pg():
+    s, cid = _fresh()
+    t_tagged = str(uuid.uuid4())
+    t_pending = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=t_tagged, sort_key=1000.0, tagged=True)
+    _seed_canonical_row(s, conv_id=cid, canonical_id=t_pending, sort_key=2000.0, tagged=False)
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id=cid, expected_lifecycle_epoch=1, batch_size=10,
+    )
+    assert [r.canonical_turn_id for r in rows] == [t_pending]
+
+
+def test_iter_untagged_returns_empty_on_epoch_mismatch_pg():
+    """SQL-level epoch guard. Stale-epoch caller sees no rows even if rows exist."""
+    s, cid = _fresh()
+    old_id = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=old_id, sort_key=1000.0)
+    s.mark_conversation_deleted(cid)
+    s.increment_lifecycle_epoch_on_resurrect(cid)  # epoch=2
+    # Seed a new-lifecycle row.
+    new_id = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=new_id, sort_key=2000.0)
+    # Stale caller: epoch=1.
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id=cid, expected_lifecycle_epoch=1, batch_size=10,
+    )
+    assert rows == []  # sees nothing
+    # Current caller: epoch=2 — sees both (old from old lifecycle not purged, plus new).
+    rows = s.iter_untagged_canonical_rows(
+        conversation_id=cid, expected_lifecycle_epoch=2, batch_size=10,
+    )
+    assert len(rows) == 2
+
+
+def test_mark_canonical_row_tagged_sets_timestamp_pg():
+    s, cid = _fresh()
+    t_pending = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=t_pending, sort_key=1000.0)
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id=t_pending, conversation_id=cid,
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is True
+    conn = s._get_conn()
+    row = conn.execute(
+        "SELECT tagged_at FROM canonical_turns WHERE canonical_turn_id = %s",
+        (t_pending,),
+    ).fetchone()
+    assert row["tagged_at"] is not None
+
+
+def test_mark_canonical_row_tagged_rejects_on_epoch_mismatch_pg():
+    """Proves SQL-level epoch guard on the mark boundary."""
+    s, cid = _fresh()
+    t0 = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=t0, sort_key=1000.0)
+    s.mark_conversation_deleted(cid)
+    s.increment_lifecycle_epoch_on_resurrect(cid)  # epoch=2
+    # Stale caller tries to mark a row that still exists.
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id=t0, conversation_id=cid,
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False
+    conn = s._get_conn()
+    row = conn.execute(
+        "SELECT tagged_at FROM canonical_turns WHERE canonical_turn_id = %s",
+        (t0,),
+    ).fetchone()
+    assert row["tagged_at"] is None  # untouched
+
+
+def test_mark_canonical_row_tagged_is_idempotent_for_already_tagged_pg():
+    """Calling mark_canonical_row_tagged a second time on an already-tagged row returns False (no-op)."""
+    s, cid = _fresh()
+    t0 = str(uuid.uuid4())
+    _seed_canonical_row(s, conv_id=cid, canonical_id=t0, sort_key=1000.0, tagged=True)
+    ok = s.mark_canonical_row_tagged(
+        canonical_turn_id=t0, conversation_id=cid,
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False  # already tagged, WHERE tagged_at IS NULL excludes it
+
+
+def test_mark_canonical_row_tagged_wrong_conversation_id_returns_false_pg():
+    """Belt-and-suspenders: mismatched conversation_id doesn't accidentally mark another conversation's row."""
+    s1, c1 = _fresh()
+    _, c2 = _fresh()
+    t0 = str(uuid.uuid4())
+    _seed_canonical_row(s1, conv_id=c1, canonical_id=t0, sort_key=1000.0)
+    ok = s1.mark_canonical_row_tagged(
+        canonical_turn_id=t0, conversation_id=c2,  # wrong conv
+        expected_lifecycle_epoch=1,
+    )
+    assert ok is False