Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

19.3 KB
Raw Blame
"""PostgresCheckpointer tests (D1) — smoke imports.

Full E2E tests are in D1.3 once PostgresCheckpointer is implemented.
"""

import asyncpg
import pytest


def test_models_import() -> None:
    from cubeloop.checkpointer.postgres.models import (
        EXPECTED_SCHEMA_VERSION,
        PARTITION_COUNT,
        CubeloopHitlAnswer,
        CubeloopMessage,
        CubeloopSchemaVersion,
        CubeloopThread,
        cubeloop_metadata,
    )

    assert EXPECTED_SCHEMA_VERSION == 5
    assert PARTITION_COUNT == 64
    assert CubeloopThread.__tablename__ == "cubepi_threads"
    assert CubeloopMessage.__tablename__ == "cubepi_messages"
    assert CubeloopHitlAnswer.__tablename__ == "cubepi_hitl_answers"
    assert CubeloopSchemaVersion.__tablename__ == "cubepi_schema_version"
    assert "cubepi_threads" in cubeloop_metadata.tables
    assert "cubepi_messages" in cubeloop_metadata.tables
    assert "cubepi_hitl_answers" in cubeloop_metadata.tables
    assert "cubepi_schema_version" in cubeloop_metadata.tables


def test_cubepi_message_has_partition_by() -> None:
    """The CubepiMessage table declares HASH partitioning."""
    from cubeloop.checkpointer.postgres.models import cubeloop_metadata

    msgs = cubeloop_metadata.tables["cubepi_messages"]
    # SQLAlchemy stores PG partition clause in info or dialect-specific args
    # Verify via dialect kwargs
    assert msgs.kwargs.get("postgresql_partition_by") == "HASH (thread_id)"


def test_cubepi_message_has_gin_index() -> None:
    """The GIN index on metadata is registered."""
    from cubeloop.checkpointer.postgres.models import cubeloop_metadata

    msgs = cubeloop_metadata.tables["cubepi_messages"]
    idx_names = [i.name for i in msgs.indexes]
    assert "ix_cubepi_messages_metadata_gin" in idx_names


def test_create_message_partitions_op_yields_64_statements() -> None:
    from cubeloop.checkpointer.postgres.alembic_helpers import (
        create_message_partitions_op,
    )

    sql = create_message_partitions_op()
    assert sql.count("CREATE TABLE cubepi_messages_p") == 64
    assert "modulus 64, remainder 0" in sql
    assert "modulus 64, remainder 63" in sql


def test_create_message_partitions_op_partitions_are_zero_padded() -> None:
    from cubeloop.checkpointer.postgres.alembic_helpers import (
        create_message_partitions_op,
    )

    sql = create_message_partitions_op()
    # Partition names use 2-digit padding so they sort lexicographically
    assert "cubepi_messages_p00 " in sql
    assert "cubepi_messages_p63 " in sql


def test_write_schema_version_op_includes_expected_version() -> None:
    from cubeloop.checkpointer.postgres.alembic_helpers import write_schema_version_op
    from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION

    sql = write_schema_version_op()
    assert "cubepi_schema_version" in sql
    assert "cubepi_schema_version" in sql
    assert f"VALUES ({EXPECTED_SCHEMA_VERSION})" in sql
    assert "ON CONFLICT" in sql


def test_write_schema_version_op_clears_stale_rows() -> None:
    """A prior version's row must be removed so _verify_schema sees the new one."""
    from cubeloop.checkpointer.postgres.alembic_helpers import write_schema_version_op
    from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION

    sql = write_schema_version_op()
    assert "DELETE FROM cubepi_schema_version" in sql
    assert "DELETE FROM cubepi_schema_version" in sql
    assert f"WHERE version <> {EXPECTED_SCHEMA_VERSION}" in sql
    assert sql.index("DELETE") < sql.index("INSERT")


def test_schema_uninitialized_is_schema_error() -> None:
    from cubeloop.checkpointer.postgres.exceptions import (
        CubeloopSchemaError,
        CubeloopSchemaUninitialized,
    )

    err = CubeloopSchemaUninitialized("tables missing")
    assert isinstance(err, CubeloopSchemaError)


def test_schema_mismatch_carries_expected_actual() -> None:
    from cubeloop.checkpointer.postgres.exceptions import CubeloopSchemaMismatch

    err = CubeloopSchemaMismatch(expected=2, actual=1, hint="run alembic")
    assert err.expected == 2
    assert err.actual == 1
    assert "expected=2" in str(err)
    assert "actual=1" in str(err)
    assert "run alembic" in str(err)


def test_schema_mismatch_without_hint() -> None:
    from cubeloop.checkpointer.postgres.exceptions import CubeloopSchemaMismatch

    err = CubeloopSchemaMismatch(expected=2, actual=1)
    # No hint suffix
    assert "expected=2" in str(err)
    assert "actual=1" in str(err)


def test_role_of_known_message_types() -> None:
    """_role_of maps each concrete Message subclass to its role string."""
    from cubeloop.checkpointer.postgres.checkpointer import _role_of
    from cubeloop.providers.base import (
        AssistantMessage,
        TextContent,
        ToolResultMessage,
        Usage,
        UserMessage,
    )

    assert _role_of(UserMessage(content=[TextContent(text="x")])) == "user"
    assert (
        _role_of(AssistantMessage(content=[TextContent(text="x")], usage=Usage()))
        == "assistant"
    )
    tr = ToolResultMessage(
        tool_call_id="tc-1",
        tool_name="t",
        content=[TextContent(text="ok")],
    )
    assert _role_of(tr) == "tool"


def test_role_of_rejects_unknown_message_type() -> None:
    """_role_of raises for anything that isn't User/Assistant/ToolResult."""
    from cubeloop.checkpointer.postgres.checkpointer import _role_of

    class FakeMessage:
        pass

    with pytest.raises(TypeError, match="unknown Message type"):
        _role_of(FakeMessage())  # type: ignore[arg-type]


@pytest.mark.asyncio
async def test_append_empty_messages_is_noop() -> None:
    """append([]) returns early without touching the pool — no DB needed."""
    from cubeloop.checkpointer.postgres import PostgresCheckpointer

    cp = PostgresCheckpointer("postgresql://unreachable-host/none")
    # Pool intentionally never created — early return must precede the assert.
    assert cp._pool is None
    await cp.append("thread-x", [])


# ---------------------------------------------------------------------------
# D1.3 E2E tests — require a real Postgres instance
# ---------------------------------------------------------------------------


async def _setup_schema(dsn: str) -> None:
    """Fresh v6 schema — canonical current DDL, no historical helpers."""
    from cubeloop.checkpointer.postgres.alembic_helpers import (
        create_message_partitions_op,
        create_runs_partitions_op,
        write_schema_version_op,
    )

    conn = await asyncpg.connect(dsn)
    try:
        await conn.execute("""
            CREATE TABLE cubepi_threads (
                thread_id TEXT PRIMARY KEY,
                parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),
                forked_at_seq BIGINT,
                extra JSONB NOT NULL DEFAULT '{}'::jsonb,
                pending_request JSONB,
                run_id TEXT,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
            );
        """)
        await conn.execute("""
            CREATE TABLE cubepi_messages (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
                seq BIGINT NOT NULL,
                role TEXT NOT NULL,
                metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
                payload BYTEA NOT NULL,
                run_id TEXT,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                PRIMARY KEY (thread_id, seq)
            ) PARTITION BY HASH (thread_id);
        """)
        await conn.execute(create_message_partitions_op())
        await conn.execute("""
            CREATE INDEX ix_cubepi_messages_metadata_gin
            ON cubepi_messages USING GIN (metadata jsonb_path_ops);
        """)
        await conn.execute("""
            CREATE INDEX ix_cubepi_messages_thread_run
            ON cubepi_messages (thread_id, run_id);
        """)
        await conn.execute("""
            CREATE TABLE cubepi_schema_version (
                version INTEGER PRIMARY KEY
            );
        """)
        await conn.execute("""
            CREATE TABLE cubepi_runs (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
                run_id TEXT NOT NULL,
                claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                completed_at TIMESTAMPTZ,
                completion_seq BIGINT,
                PRIMARY KEY (thread_id, run_id)
            ) PARTITION BY HASH (thread_id);
        """)
        await conn.execute(create_runs_partitions_op())
        await conn.execute("""
            CREATE INDEX ix_cubepi_runs_thread_seq
            ON cubepi_runs (thread_id, completion_seq);
        """)
        await conn.execute("""
            CREATE TABLE cubepi_hitl_answers (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
                run_id TEXT NOT NULL,
                question_id TEXT NOT NULL,
                answer JSONB NOT NULL,
                answered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                PRIMARY KEY (thread_id, run_id, question_id)
            );
        """)
        await conn.execute(write_schema_version_op())
    finally:
        await conn.close()


async def _setup_schema_v5(dsn: str) -> None:
    """Historical v5 (cubepi_* names) via frozen v1–v5 helpers."""
    from cubeloop.checkpointer.postgres.alembic_helpers import (
        add_pending_request_column_op,
        add_run_id_column_op,
        upgrade_v3_to_v4_op,
        upgrade_v4_to_v5_op,
    )
    from cubeloop.checkpointer.postgres.models import PARTITION_COUNT

    conn = await asyncpg.connect(dsn)
    try:
        await conn.execute("""
            CREATE TABLE cubepi_threads (
                thread_id TEXT PRIMARY KEY,
                parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),
                forked_at_seq BIGINT,
                extra JSONB NOT NULL DEFAULT '{}'::jsonb,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
            );
        """)
        await conn.execute("""
            CREATE TABLE cubepi_messages (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
                seq BIGINT NOT NULL,
                role TEXT NOT NULL,
                metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
                payload BYTEA NOT NULL,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                PRIMARY KEY (thread_id, seq)
            ) PARTITION BY HASH (thread_id);
        """)
        await conn.execute(add_pending_request_column_op())
        await conn.execute(add_run_id_column_op())
        for i in range(PARTITION_COUNT):
            await conn.execute(
                f"CREATE TABLE cubepi_messages_p{i:02d} "
                f"PARTITION OF cubepi_messages "
                f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i})"
            )
        await conn.execute("""
            CREATE INDEX ix_cubepi_messages_metadata_gin
            ON cubepi_messages USING GIN (metadata jsonb_path_ops);
        """)
        await conn.execute("""
            CREATE TABLE cubepi_schema_version (
                version INTEGER PRIMARY KEY
            );
        """)
        await conn.execute(upgrade_v3_to_v4_op())
        await conn.execute(upgrade_v4_to_v5_op())
        await conn.execute("INSERT INTO cubepi_schema_version (version) VALUES (5)")
    finally:
        await conn.close()


@pytest.mark.asyncio
async def test_postgres_checkpointer_round_trip(clean_db) -> None:
    """Append + load round-trips messages with metadata."""
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import (
        AssistantMessage,
        TextContent,
        Usage,
        UserMessage,
    )

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        msg1 = UserMessage(
            content=[TextContent(text="hello")],
            metadata={"memory_snapshot": {"id": "m1"}},
        )
        msg2 = AssistantMessage(
            content=[TextContent(text="hi back")],
            usage=Usage(),
            metadata={"cost_cents": 5},
        )
        await cp.append("t-1", [msg1, msg2])
        data = await cp.load("t-1")

    assert data is not None
    assert len(data.messages) == 2
    assert isinstance(data.messages[0], UserMessage)
    assert isinstance(data.messages[1], AssistantMessage)
    assert data.messages[0].metadata == {"memory_snapshot": {"id": "m1"}}
    assert data.messages[1].metadata == {"cost_cents": 5}
    # Round-trip content
    assert data.messages[0].content[0].text == "hello"
    assert data.messages[1].content[0].text == "hi back"


@pytest.mark.asyncio
async def test_postgres_checkpointer_save_extra_merges(clean_db) -> None:
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import TextContent, UserMessage

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        await cp.append("t-2", [UserMessage(content=[TextContent(text="x")])])
        await cp.save_extra("t-2", {"a": 1})
        await cp.save_extra("t-2", {"b": 2})
        data = await cp.load("t-2")

    assert data is not None
    assert data.extra == {"a": 1, "b": 2}


@pytest.mark.asyncio
async def test_postgres_checkpointer_seq_monotonic(clean_db) -> None:
    """Multiple append batches produce strictly monotonic seqs."""
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import TextContent, UserMessage

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        msgs1 = [UserMessage(content=[TextContent(text=str(i))]) for i in range(5)]
        await cp.append("t-3", msgs1)
        msgs2 = [UserMessage(content=[TextContent(text=str(i))]) for i in range(5, 10)]
        await cp.append("t-3", msgs2)
        data = await cp.load("t-3")

    assert data is not None
    assert len(data.messages) == 10
    texts = [m.content[0].text for m in data.messages]
    assert texts == [str(i) for i in range(10)]


@pytest.mark.asyncio
async def test_uninitialized_schema_raises(clean_db) -> None:
    """Empty DB (no cubepi tables) → CubepiSchemaUninitialized."""
    from cubeloop.checkpointer.postgres import (
        CubeloopSchemaUninitialized,
        PostgresCheckpointer,
    )

    with pytest.raises(CubeloopSchemaUninitialized):
        async with PostgresCheckpointer(clean_db):
            pass


@pytest.mark.asyncio
async def test_version_mismatch_raises(clean_db) -> None:
    """Schema present but version != EXPECTED → CubepiSchemaMismatch."""
    from cubeloop.checkpointer.postgres import (
        CubeloopSchemaMismatch,
        PostgresCheckpointer,
    )

    await _setup_schema(clean_db)
    conn = await asyncpg.connect(clean_db)
    try:
        await conn.execute("UPDATE cubepi_schema_version SET version = 999")
    finally:
        await conn.close()

    with pytest.raises(CubeloopSchemaMismatch) as exc_info:
        async with PostgresCheckpointer(clean_db):
            pass
    from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION

    assert exc_info.value.expected == EXPECTED_SCHEMA_VERSION
    assert exc_info.value.actual == 999


@pytest.mark.asyncio
async def test_empty_thread_load_returns_none(clean_db) -> None:
    """Loading an unknown thread returns None."""
    from cubeloop.checkpointer.postgres import PostgresCheckpointer

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        data = await cp.load("nonexistent-thread")
    assert data is None


@pytest.mark.asyncio
async def test_postgres_load_corrupt_row_raises_typed(clean_db) -> None:
    """One bad payload row surfaces as CheckpointCorruptionError naming the
    row — not a raw msgpack error that hides which row is bad."""
    from cubeloop.checkpointer.exceptions import CheckpointCorruptionError
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import TextContent, UserMessage

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        await cp.append(
            "t-corrupt",
            [
                UserMessage(content=[TextContent(text="ok")]),
                UserMessage(content=[TextContent(text="will corrupt")]),
            ],
        )
        conn = await asyncpg.connect(clean_db)
        try:
            await conn.execute(
                "UPDATE cubepi_messages SET payload = $1 "
                "WHERE thread_id = 't-corrupt' AND seq = ("
                "  SELECT max(seq) FROM cubepi_messages "
                "  WHERE thread_id = 't-corrupt')",
                b"\xc1 not msgpack",
            )
        finally:
            await conn.close()

        with pytest.raises(CheckpointCorruptionError) as excinfo:
            await cp.load("t-corrupt")

    err = excinfo.value
    assert err.thread_id == "t-corrupt"
    assert err.backend == "postgres"
    assert err.row_ref.startswith("cubepi_messages.seq=")
    assert err.__cause__ is not None


@pytest.mark.asyncio
async def test_postgres_load_unknown_role_raises_typed(clean_db) -> None:
    from cubeloop.checkpointer.exceptions import CheckpointCorruptionError
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import TextContent, UserMessage

    await _setup_schema(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        await cp.append("t-role", [UserMessage(content=[TextContent(text="ok")])])
        conn = await asyncpg.connect(clean_db)
        try:
            await conn.execute(
                "UPDATE cubepi_messages SET role = 'alien' WHERE thread_id = 't-role'"
            )
        finally:
            await conn.close()

        with pytest.raises(CheckpointCorruptionError) as excinfo:
            await cp.load("t-role")

    assert isinstance(excinfo.value.__cause__, ValueError)
    assert "alien" in str(excinfo.value)


@pytest.mark.asyncio
async def test_existing_v5_schema_round_trip_without_migration(clean_db) -> None:
    from cubeloop.checkpointer.postgres import PostgresCheckpointer
    from cubeloop.providers.base import TextContent, UserMessage

    await _setup_schema_v5(clean_db)
    async with PostgresCheckpointer(clean_db) as cp:
        await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])
        data = await cp.load("t-mig")
    assert data is not None
    assert len(data.messages) == 1


@pytest.mark.asyncio
async def test_data_tables_without_version_table_are_not_uninitialized(
    clean_db,
) -> None:
    from cubeloop.checkpointer.postgres import (
        CubeloopSchemaMismatch,
        CubeloopSchemaUninitialized,
        PostgresCheckpointer,
    )

    conn = await asyncpg.connect(clean_db)
    try:
        await conn.execute("CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY)")
    finally:
        await conn.close()

    with pytest.raises(CubeloopSchemaMismatch) as ei:
        async with PostgresCheckpointer(clean_db):
            pass
    assert ei.value.actual == 0
    with pytest.raises(CubeloopSchemaMismatch):
        async with PostgresCheckpointer(clean_db):
            pass
    assert "Uninitialized" not in type(ei.value).__name__
    assert not isinstance(ei.value, CubeloopSchemaUninitialized)