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

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

@@ -64,3 +64,7 @@ extraneous/paper/*.png
 
 # OS
 .DS_Store
+.agent-prompt.md
+
+# Riptide artifacts (cloud-synced)
+.humanlayer/tasks/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtual-context
-Version: 0.4.2
+Version: 0.4.4
 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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "virtual-context"
-version = "0.4.2"
+version = "0.4.4"
 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.4/tests/test_admin_backfill_cli.py

@@ -0,0 +1,171 @@
+"""Tests for the ``admin backfill-tag-summaries`` CLI subcommand.
+
+Covers the storage-override flags + ``DATABASE_URL`` env fallback
+introduced so the subcommand runs inside containers that don't have a
+config file mounted at a standard path.
+"""
+
+from __future__ import annotations
+
+import os
+
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+from types import SimpleNamespace
+
+import pytest
+
+from virtual_context.cli.main import _apply_storage_overrides
+from virtual_context.types import StorageConfig, VirtualContextConfig
+
+
+def _make_config(*, backend="sqlite", postgres_dsn="", sqlite_path=".db"):
+    return VirtualContextConfig(
+        storage=StorageConfig(
+            backend=backend,
+            postgres_dsn=postgres_dsn,
+            sqlite_path=sqlite_path,
+        ),
+    )
+
+
+def test_storage_override_explicit_flag_wins(monkeypatch):
+    """Explicit ``--postgres-dsn`` overrides whatever config carried."""
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    config = _make_config(backend="sqlite", postgres_dsn="from-config")
+    args = SimpleNamespace(
+        config=None,
+        storage_backend="postgres",
+        postgres_dsn="postgresql://override/db",
+        sqlite_path=None,
+    )
+    _apply_storage_overrides(config, args)
+    assert config.storage.backend == "postgres"
+    assert config.storage.postgres_dsn == "postgresql://override/db"
+
+
+def test_storage_override_sqlite_path_flag(monkeypatch):
+    """``--sqlite-path`` overrides ``storage.sqlite_path``."""
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    config = _make_config(backend="sqlite", sqlite_path=".db")
+    args = SimpleNamespace(
+        config=None,
+        storage_backend=None,
+        postgres_dsn=None,
+        sqlite_path="/tmp/override.db",
+    )
+    _apply_storage_overrides(config, args)
+    assert config.storage.sqlite_path == "/tmp/override.db"
+    # Backend unchanged because no --storage-backend flag.
+    assert config.storage.backend == "sqlite"
+
+
+def test_storage_override_database_url_env_fallback(monkeypatch):
+    """When no flag and no ``-c`` are given, ``DATABASE_URL`` env
+    promotes the engine to Postgres with that DSN. Covers the
+    container-based invocation shape where ops just runs the
+    subcommand with the env already set by the container runtime."""
+    monkeypatch.setenv("DATABASE_URL", "postgresql://from-env/db")
+    config = _make_config(backend="sqlite", postgres_dsn="")
+    args = SimpleNamespace(
+        config=None,
+        storage_backend=None,
+        postgres_dsn=None,
+        sqlite_path=None,
+    )
+    _apply_storage_overrides(config, args)
+    assert config.storage.backend == "postgres"
+    assert config.storage.postgres_dsn == "postgresql://from-env/db"
+
+
+def test_storage_override_database_url_skipped_when_config_provided(monkeypatch):
+    """When the caller passes ``-c``, the env fallback DOES NOT fire;
+    the config file is treated as authoritative."""
+    monkeypatch.setenv("DATABASE_URL", "postgresql://from-env/db")
+    config = _make_config(backend="sqlite", postgres_dsn="")
+    args = SimpleNamespace(
+        config="/some/config.yaml",
+        storage_backend=None,
+        postgres_dsn=None,
+        sqlite_path=None,
+    )
+    _apply_storage_overrides(config, args)
+    # Backend + DSN unchanged because ``-c`` was given.
+    assert config.storage.backend == "sqlite"
+    assert config.storage.postgres_dsn == ""
+
+
+def test_storage_override_database_url_skipped_when_any_flag_set(monkeypatch):
+    """When ANY storage flag is set, the env fallback does NOT fire
+    (explicit flags are authoritative)."""
+    monkeypatch.setenv("DATABASE_URL", "postgresql://from-env/db")
+    config = _make_config(backend="sqlite")
+    args = SimpleNamespace(
+        config=None,
+        storage_backend=None,
+        postgres_dsn=None,
+        sqlite_path="/tmp/explicit.db",
+    )
+    _apply_storage_overrides(config, args)
+    # Only the sqlite_path flag applies; env fallback is skipped.
+    assert config.storage.sqlite_path == "/tmp/explicit.db"
+    assert config.storage.backend == "sqlite"
+    assert config.storage.postgres_dsn == ""
+
+
+def test_storage_override_no_change_when_no_flags_and_no_env(monkeypatch):
+    """Defaults intact when neither flags, ``-c``, nor ``DATABASE_URL``
+    are present. (``-c`` absent means ``load_config()`` already returned
+    defaults; this assertion guards against accidental mutation.)"""
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    config = _make_config(backend="sqlite", sqlite_path=".db")
+    args = SimpleNamespace(
+        config=None,
+        storage_backend=None,
+        postgres_dsn=None,
+        sqlite_path=None,
+    )
+    _apply_storage_overrides(config, args)
+    assert config.storage.backend == "sqlite"
+    assert config.storage.postgres_dsn == ""
+    assert config.storage.sqlite_path == ".db"
+
+
+def test_cli_parser_accepts_new_storage_flags():
+    """End-to-end parser smoke test: the ``admin backfill-tag-summaries``
+    subparser accepts the three new flags + ``DATABASE_URL`` precedence
+    metadata in the help text."""
+    from virtual_context.cli.main import main as _main
+    import argparse
+
+    # Re-build the parser the way ``main()`` does, then parse a sample
+    # invocation. (Doing a full ``main()`` call would actually run the
+    # backfill; we only need argument parsing here.)
+    parser = argparse.ArgumentParser(prog="virtual-context")
+    parser.add_argument("--config", "-c")
+    subparsers = parser.add_subparsers(dest="command")
+    admin_parser = subparsers.add_parser("admin")
+    admin_sub = admin_parser.add_subparsers(dest="admin_command")
+    backfill_parser = admin_sub.add_parser("backfill-tag-summaries")
+    backfill_parser.add_argument("conversation_id")
+    backfill_parser.add_argument("--tenant-id", default="")
+    backfill_parser.add_argument("--force-rebuild", action="store_true")
+    backfill_parser.add_argument(
+        "--storage-backend",
+        choices=("sqlite", "postgres", "filesystem"),
+    )
+    backfill_parser.add_argument("--postgres-dsn")
+    backfill_parser.add_argument("--sqlite-path")
+
+    args = parser.parse_args([
+        "admin", "backfill-tag-summaries", "conv-xyz",
+        "--tenant-id", "t1",
+        "--storage-backend", "postgres",
+        "--postgres-dsn", "postgresql://h/db",
+    ])
+    assert args.conversation_id == "conv-xyz"
+    assert args.tenant_id == "t1"
+    assert args.storage_backend == "postgres"
+    assert args.postgres_dsn == "postgresql://h/db"
+    assert args.sqlite_path is None
+    assert args.force_rebuild is False

{virtual_context-0.4.2 → virtual_context-0.4.4}/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.4/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.4/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"
+    )