CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
fix(checkpointer): retain cubepi persistence schema
xf gonge014981e88c9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a7c587e..da7237b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,17 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]-## [0.14.0] - 2026-09-10+## [0.14.1] - 2026-09-10++### Fixed++- **The CubeLoop rename no longer renames the persistent Postgres/MySQL+ schema.** Physical tables, partitions, indexes, and the version marker remain+ `cubepi_*` at schema version 5, so an existing 0.13.6 database opens without+ DDL and historical host Alembic revisions remain reproducible. The withdrawn+ 0.14.0 release briefly used `cubeloop_*`; see the migration guide for the+ exceptional recovery procedure.+- **The transitional `cubepi` package accepts compatible 0.14 patch releases.**+ Its dependency and forwarded extras now use `cubeloop>=0.14.1,<0.15`.++## [0.14.0] - 2026-09-10 [YANKED]### Breaking- **Renamed CubePi / `cubepi` to CubeLoop / `cubeloop`.** The import path,PyPI project, CLI, docs site (`https://cubeloop.dev`), OTel vendor- namespace (`cubeloop.*`), and Postgres/MySQL table names (`cubeloop_*`)- all move. `pip install cubepi` 0.14+ is a transitional wrapper that- depends on `cubeloop` and warns. Postgres/MySQL hosts must run- `upgrade_v5_to_v6_op()` before opening 0.14. SQLite table names are- unchanged. See the [migration guide](https://cubeloop.dev/docs/migration/from-cubepi).+ namespace (`cubeloop.*`), and — incorrectly — Postgres/MySQL table names+ (`cubeloop_*`) all moved. This release was withdrawn because the database+ rename broke reproducible host Alembic histories and safe rollback. Use+ 0.14.1 or later. See the+ [migration guide](https://cubeloop.dev/docs/migration/from-cubepi).## [0.13.6] - 2026-09-04@@ -811,7 +824,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- **[0.2.0]** - 2026-05-10 — see the [release notes](https://github.com/cubeplexai/cubepi/releases/tag/v0.2.0).- **[0.1.0]** - 2026-05-09 — initial release. See the [release notes](https://github.com/cubeplexai/cubepi/releases/tag/v0.1.0).-[Unreleased]: https://github.com/cubeplexai/cubeloop/compare/v0.14.0...HEAD+[Unreleased]: https://github.com/cubeplexai/cubeloop/compare/v0.14.1...HEAD+[0.14.1]: https://github.com/cubeplexai/cubeloop/compare/v0.14.0...v0.14.1[0.14.0]: https://github.com/cubeplexai/cubeloop/compare/v0.13.6...v0.14.0[0.13.6]: https://github.com/cubeplexai/cubeloop/compare/v0.13.5...v0.13.6[0.13.5]: https://github.com/cubeplexai/cubeloop/compare/v0.13.4...v0.13.5diff --git a/compat/cubepi/README.md b/compat/cubepi/README.mdindex ac4d47d..e247b4f 100644--- a/compat/cubepi/README.md+++ b/compat/cubepi/README.md@@ -10,7 +10,8 @@ pip install cubeloopfrom cubeloop import Agent, tool```-This distribution is a transitional wrapper: it depends on `cubeloop==0.14.0`,+This distribution is a transitional wrapper: it depends on a compatible+`cubeloop>=0.14.1,<0.15`,re-exports the public API, and aliases `cubepi.*` imports onto `cubeloop.*`.Installing it prints a deprecation warning on first import.diff --git a/compat/cubepi/pyproject.toml b/compat/cubepi/pyproject.tomlindex 605754d..cc57425 100644--- a/compat/cubepi/pyproject.toml+++ b/compat/cubepi/pyproject.toml@@ -1,6 +1,6 @@[project]name = "cubepi"-version = "0.14.0"+version = "0.14.1"description = "DEPRECATED: Cubepi has been renamed to cubeloop. This package is a transitional wrapper."readme = "README.md"license = "MIT"@@ -13,17 +13,17 @@ classifiers = ["Programming Language :: Python :: 3.14",]dependencies = [- "cubeloop==0.14.0",+ "cubeloop>=0.14.1,<0.15",][project.optional-dependencies]-sqlite = ["cubeloop[sqlite]==0.14.0"]-postgres = ["cubeloop[postgres]==0.14.0"]-mysql = ["cubeloop[mysql]==0.14.0"]-mcp = ["cubeloop[mcp]==0.14.0"]-tracing = ["cubeloop[tracing]==0.14.0"]-tracing-otlp = ["cubeloop[tracing-otlp]==0.14.0"]-trace-cli = ["cubeloop[trace-cli]==0.14.0"]+sqlite = ["cubeloop[sqlite]>=0.14.1,<0.15"]+postgres = ["cubeloop[postgres]>=0.14.1,<0.15"]+mysql = ["cubeloop[mysql]>=0.14.1,<0.15"]+mcp = ["cubeloop[mcp]>=0.14.1,<0.15"]+tracing = ["cubeloop[tracing]>=0.14.1,<0.15"]+tracing-otlp = ["cubeloop[tracing-otlp]>=0.14.1,<0.15"]+trace-cli = ["cubeloop[trace-cli]>=0.14.1,<0.15"][project.scripts]cubepi = "cubepi.__main__:main"diff --git a/cubeloop/__init__.py b/cubeloop/__init__.pyindex 4982ab3..2cc26d2 100644--- a/cubeloop/__init__.py+++ b/cubeloop/__init__.py@@ -1,4 +1,4 @@-"""cubepi — Pythonic async-native agent framework."""+"""CubeLoop — Pythonic async-native agent framework."""from importlib.metadata import PackageNotFoundError, version as _pkg_versiondiff --git a/cubeloop/checkpointer/mysql/README.md b/cubeloop/checkpointer/mysql/README.mdindex d5fcf96..9daef31 100644--- a/cubeloop/checkpointer/mysql/README.md+++ b/cubeloop/checkpointer/mysql/README.md@@ -43,13 +43,13 @@ from cubeloop.checkpointer.mysql import cubeloop_metadata, EXPECTED_SCHEMA_VERSI| Symbol | Use ||---|---|| `cubeloop_metadata` | SQLAlchemy `MetaData` — set as Alembic `target_metadata` |-| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `6`) |+| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `5`) |The SQL helpers live in the `alembic_helpers` submodule:```pythonfrom cubeloop.checkpointer.mysql.alembic_helpers import (- messages_partition_clause, # the PARTITION BY KEY (...) clause for cubeloop_messages+ messages_partition_clause, # the PARTITION BY KEY (...) clause for cubepi_messagesadd_pending_request_column_op, # v1→v2 column addwrite_schema_version_op, # returns two ';'-separated statements)@@ -57,19 +57,19 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (## Tables-`cubeloop_metadata` defines the current (v6) tables:+`cubeloop_metadata` defines the current (v5) tables:| Table | Purpose ||---|---|-| `cubeloop_threads` | One row per thread; holds `pending_request JSON NULL` (HITL, v2+) |-| `cubeloop_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, `PARTITION BY KEY (thread_id)` into 64 partitions |-| `cubeloop_runs` | Per-run claim/completion (v4+) |-| `cubeloop_hitl_answers` | Durable HITL answers (v5+) |-| `cubeloop_schema_version` | Single-row version marker verified on connect |+| `cubepi_threads` | One row per thread; holds `pending_request JSON NULL` (HITL, v2+) |+| `cubepi_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, `PARTITION BY KEY (thread_id)` into 64 partitions |+| `cubepi_runs` | Per-run claim/completion (v4+) |+| `cubepi_hitl_answers` | Durable HITL answers (v5+) |+| `cubepi_schema_version` | Single-row version marker verified on connect |MySQL declares all partitions inline in the `CREATE TABLE` (unlike-Postgres, which uses one child table per partition). The `cubeloop_messages`-table has **no foreign key** to `cubeloop_threads` — MySQL forbids FKs on+Postgres, which uses one child table per partition). The `cubepi_messages`+table has **no foreign key** to `cubepi_threads` — MySQL forbids FKs onpartitioned tables.## Wiring Alembic (`env.py`)@@ -94,13 +94,13 @@ correct columns** (from `cubeloop_metadata`). Two things to add by hand:1. **KEY partitioning.** SQLAlchemy autogenerate cannot express MySQL`KEY` partitioning, so append the partition clause to the- `cubeloop_messages` table. Keep the autogenerated column list and add+ `cubepi_messages` table. Keep the autogenerated column list and addthe clause via `op.execute`:```pythonfrom cubeloop.checkpointer.mysql.alembic_helpers import messages_partition_clause- op.execute("ALTER TABLE cubeloop_messages " + messages_partition_clause())+ op.execute("ALTER TABLE cubepi_messages " + messages_partition_clause())````KEY` (not `HASH`) is required because `thread_id` is a `VARCHAR` —@@ -118,14 +118,14 @@ correct columns** (from `cubeloop_metadata`). Two things to add by hand:op.execute(stmt)```-> Do not hand-trim the `cubeloop_messages` columns. The checkpointer writes+> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes> and reads `(thread_id, seq, role, metadata, payload)`; dropping any of> them causes runtime SQL errors on the first append.## Upgrading schema versionsCubeLoop bumps `EXPECTED_SCHEMA_VERSION` when the schema changes; the-checkpointer refuses to connect if the row in `cubeloop_schema_version`+checkpointer refuses to connect if the row in `cubepi_schema_version`doesn't match. Each bump is one host migration.**v1 → v2** (HITL): adds `pending_request JSON NULL` to `cubepi_threads`.diff --git a/cubeloop/checkpointer/mysql/alembic_helpers.py b/cubeloop/checkpointer/mysql/alembic_helpers.pyindex 1a218c8..f5528f3 100644--- a/cubeloop/checkpointer/mysql/alembic_helpers.py+++ b/cubeloop/checkpointer/mysql/alembic_helpers.py@@ -1,9 +1,6 @@"""SQL helpers for host application alembic migrations (MySQL)."""-from cubeloop.checkpointer.mysql.models import (- EXPECTED_SCHEMA_VERSION,- PARTITION_COUNT,-)+from cubeloop.checkpointer.mysql.models import PARTITION_COUNTdef messages_partition_clause() -> str:@@ -80,21 +77,19 @@ def add_messages_run_id_column_op() -> str:def create_runs_table_op() -> str:- """Return SQL creating the partitioned ``cubeloop_runs`` parent table.+ """Return SQL creating the partitioned ``cubepi_runs`` parent table.- Current-schema factory (v6 names). Historical v3→v4 inlines the old- cubepi_runs CREATE and must not call this helper. NO FK to- ``cubeloop_threads`` — MySQL forbids FKs on partitioned tables.+ NO FK to ``cubepi_threads`` — MySQL forbids FKs on partitioned tables."""return (- "CREATE TABLE cubeloop_runs ("+ "CREATE TABLE cubepi_runs ("" thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,"" run_id VARCHAR(255) NOT NULL,"" claimed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,"" completed_at TIMESTAMP NULL,"" completion_seq BIGINT NULL,"" PRIMARY KEY (thread_id, run_id),"- " KEY ix_cubeloop_runs_thread_seq (thread_id, completion_seq)"+ " KEY ix_cubepi_runs_thread_seq (thread_id, completion_seq)"") ENGINE=InnoDB " + runs_partition_clause())@@ -126,20 +121,7 @@ def upgrade_v3_to_v4_op() -> str:if stmt.strip():op.execute(stmt)"""- # Inline the pre-rename cubepi_runs CREATE. create_runs_table_op() now- # emits cubeloop_runs names for fresh installs.- legacy_runs = (- "CREATE TABLE cubepi_runs ("- " thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,"- " run_id VARCHAR(255) NOT NULL,"- " claimed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,"- " completed_at TIMESTAMP NULL,"- " completion_seq BIGINT NULL,"- " PRIMARY KEY (thread_id, run_id),"- " KEY ix_cubepi_runs_thread_seq (thread_id, completion_seq)"- ") ENGINE=InnoDB " + runs_partition_clause()- )- return f"{add_messages_run_id_column_op()} {legacy_runs};"+ return f"{add_messages_run_id_column_op()} {create_runs_table_op()};"def create_hitl_answers_table_op() -> str:@@ -166,59 +148,8 @@ def upgrade_v4_to_v5_op() -> str:return create_hitl_answers_table_op() + ";"-def upgrade_v5_to_v6_op() -> str:- """Rename cubepi_* tables to cubeloop_* in one atomic RENAME TABLE.-- Includes cubepi_schema_version. KEY partitions ride with the table.-- Returns ';'-joined standalone statements (SET / PREPARE / EXECUTE).- Hosts must split the same way as ``write_schema_version_op``::-- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- op.execute(stmt)-- Complete (no-op) iff both cubeloop_threads and cubeloop_schema_version- already exist. If data tables moved but the version table did not,- only the leftover version table is renamed. Requires a complete v5;- missing cubepi_schema_version fails the whole rename.- """- rename_all = (- "RENAME TABLE "- "cubepi_threads TO cubeloop_threads, "- "cubepi_messages TO cubeloop_messages, "- "cubepi_runs TO cubeloop_runs, "- "cubepi_hitl_answers TO cubeloop_hitl_answers, "- "cubepi_schema_version TO cubeloop_schema_version"- )- rename_ver = "RENAME TABLE cubepi_schema_version TO cubeloop_schema_version"- return (- "SET @cp_new_th = ("- "SELECT COUNT(*) FROM information_schema.tables "- "WHERE table_schema = DATABASE() "- "AND table_name = 'cubeloop_threads'); "- "SET @cp_new_ver = ("- "SELECT COUNT(*) FROM information_schema.tables "- "WHERE table_schema = DATABASE() "- "AND table_name = 'cubeloop_schema_version'); "- "SET @cp_old_ver = ("- "SELECT COUNT(*) FROM information_schema.tables "- "WHERE table_schema = DATABASE() "- "AND table_name = 'cubepi_schema_version'); "- "SET @cp_sql = IF(@cp_new_th > 0 AND @cp_new_ver > 0, "- "'DO 0', "- "IF(@cp_new_th > 0 AND @cp_old_ver > 0, "- f"'{rename_ver}', "- f"'{rename_all}')); "- "PREPARE cp_v6 FROM @cp_sql; "- "EXECUTE cp_v6; "- "DEALLOCATE PREPARE cp_v6;"- )--def write_schema_version_op() -> str:- """Write EXPECTED_SCHEMA_VERSION to cubeloop_schema_version if that- table exists, else to cubepi_schema_version.+ """Return the immutable v5 schema-version write used by host migrations.Returns ';'-joined **standalone** statements. Hosts must split::@@ -226,24 +157,9 @@ def write_schema_version_op() -> str:if stmt.strip():op.execute(stmt)- No compound IF/THEN — internal semicolons would break the split contract.+ The two standalone statements preserve the documented split contract."""- n = EXPECTED_SCHEMA_VERSIONreturn (- "SET @cp_ver_new = ("- "SELECT COUNT(*) FROM information_schema.tables "- "WHERE table_schema = DATABASE() "- "AND table_name = 'cubeloop_schema_version'); "- f"SET @cp_del = IF(@cp_ver_new > 0, "- f"'DELETE FROM cubeloop_schema_version WHERE version <> {n}', "- f"'DELETE FROM cubepi_schema_version WHERE version <> {n}'); "- "PREPARE cp_stmt FROM @cp_del; "- "EXECUTE cp_stmt; "- "DEALLOCATE PREPARE cp_stmt; "- f"SET @cp_ins = IF(@cp_ver_new > 0, "- f"'INSERT IGNORE INTO cubeloop_schema_version (version) VALUES ({n})', "- f"'INSERT IGNORE INTO cubepi_schema_version (version) VALUES ({n})'); "- "PREPARE cp_stmt FROM @cp_ins; "- "EXECUTE cp_stmt; "- "DEALLOCATE PREPARE cp_stmt;"+ "DELETE FROM cubepi_schema_version WHERE version <> 5; "+ "INSERT IGNORE INTO cubepi_schema_version (version) VALUES (5);")diff --git a/cubeloop/checkpointer/mysql/checkpointer.py b/cubeloop/checkpointer/mysql/checkpointer.pyindex ef69737..17a537f 100644--- a/cubeloop/checkpointer/mysql/checkpointer.py+++ b/cubeloop/checkpointer/mysql/checkpointer.py@@ -68,7 +68,7 @@ _ROLE_TO_CLS: dict[str, type[Message]] = {def _deserialize_row(thread_id: str, seq: int, role: str, metadata: Any, payload: Any) -> Message:- """Deserialize one cubeloop_messages row; corruption raises typed."""+ """Deserialize one cubepi_messages row; corruption raises typed."""try:cls = _ROLE_TO_CLS.get(role)if cls is None:@@ -80,7 +80,7 @@ def _deserialize_row(raise CheckpointCorruptionError(thread_id=thread_id,backend="mysql",- row_ref=f"cubeloop_messages.seq={seq}",+ row_ref=f"cubepi_messages.seq={seq}",cause=exc,) from exc@@ -175,18 +175,29 @@ class MySQLCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:async with conn.cursor() as cur:- row, missing = await self._select_version(- cur, "cubeloop_schema_version"- )+ row, missing = await self._select_version(cur, "cubepi_schema_version")if not missing:if row is None:raise CubeloopSchemaUninitialized(- "cubeloop_schema_version table is empty. Host "+ "cubepi_schema_version table is empty. Host ""alembic migration must INSERT the current version ""(use write_schema_version_op()).")actual = row[0]if actual != EXPECTED_SCHEMA_VERSION:+ if actual > EXPECTED_SCHEMA_VERSION:+ raise CubeloopSchemaMismatch(+ expected=EXPECTED_SCHEMA_VERSION,+ actual=actual,+ hint=(+ "database schema is newer than this CubeLoop "+ "release. If withdrawn 0.14.0 wrote version 6, "+ "inspect the database and follow "+ "https://cubeloop.dev/docs/migration/"+ "from-cubepi#emergency-recovery-from-withdrawn-0140; "+ "do not run a forward migration."+ ),+ )steps = ", ".join(f"upgrade_v{v}_to_v{v + 1}_op()"for v in range(actual, EXPECTED_SCHEMA_VERSION)@@ -205,20 +216,20 @@ class MySQLCheckpointer:)return- legacy, legacy_missing = await self._select_version(- cur, "cubepi_schema_version"+ withdrawn, withdrawn_missing = await self._select_version(+ cur, "cubeloop_schema_version")- if not legacy_missing:- actual = 0 if legacy is None else int(legacy[0])+ if not withdrawn_missing and withdrawn is not None:+ actual = int(withdrawn[0])raise CubeloopSchemaMismatch(expected=EXPECTED_SCHEMA_VERSION,actual=actual,hint=(- "Generate a new alembic revision that calls "- "upgrade_v5_to_v6_op() + write_schema_version_op() "- "(see cubeloop.checkpointer.mysql.alembic_helpers) "- "and run `alembic upgrade head` against this "- "database."+ "database uses the withdrawn 0.14.0 cubeloop_* "+ "schema. Inspect it and follow "+ "https://cubeloop.dev/docs/migration/"+ "from-cubepi#emergency-recovery-from-withdrawn-0140; "+ "do not run a forward migration."),)@@ -234,14 +245,13 @@ class MySQLCheckpointer:actual=0,hint=("data tables exist but schema_version is missing; "- "cannot auto-classify. If tables are still cubepi_*, "- "CREATE TABLE cubepi_schema_version and INSERT 5, "- "then run upgrade_v5_to_v6_op(). Do not apply fresh "- "v6 CREATE TABLE on existing data."+ "cannot auto-classify. Restore cubepi_schema_version "+ "from the host's Alembic history; do not apply fresh "+ "CREATE TABLE statements on existing data."),)raise CubeloopSchemaUninitialized(- "cubeloop tables not found. Run host application's alembic upgrade."+ "cubepi tables not found. Run host application's alembic upgrade.")@staticmethod@@ -264,13 +274,13 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT seq, role, metadata, payload FROM cubeloop_messages "+ "SELECT seq, role, metadata, payload FROM cubepi_messages ""WHERE thread_id = %s ORDER BY seq",(thread_id,),)msg_rows = await cur.fetchall()await cur.execute(- "SELECT extra, parent_thread_id FROM cubeloop_threads "+ "SELECT extra, parent_thread_id FROM cubepi_threads ""WHERE thread_id = %s",(thread_id,),)@@ -310,12 +320,12 @@ class MySQLCheckpointer:# also swallow unrelated errors and emit a duplicate-key# warning when the row already exists.await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) ""ON DUPLICATE KEY UPDATE thread_id = thread_id",(thread_id,),)await cur.execute(- "SELECT thread_id FROM cubeloop_threads "+ "SELECT thread_id FROM cubepi_threads ""WHERE thread_id = %s FOR UPDATE",(thread_id,),)@@ -323,7 +333,7 @@ class MySQLCheckpointer:if run_ids:placeholders = ", ".join(["%s"] * len(run_ids))await cur.execute(- f"SELECT run_id FROM cubeloop_runs "+ f"SELECT run_id FROM cubepi_runs "f"WHERE thread_id = %s "f"AND run_id IN ({placeholders}) "f"AND completed_at IS NOT NULL",@@ -336,7 +346,7 @@ class MySQLCheckpointer:f"append on completed run thread={thread_id} runs={bad}")await cur.execute(- "SELECT COALESCE(MAX(seq), 0) FROM cubeloop_messages "+ "SELECT COALESCE(MAX(seq), 0) FROM cubepi_messages ""WHERE thread_id = %s",(thread_id,),)@@ -358,7 +368,7 @@ class MySQLCheckpointer:))await cur.executemany(- "INSERT INTO cubeloop_messages "+ "INSERT INTO cubepi_messages ""(thread_id, seq, role, metadata, payload, run_id) ""VALUES (%s, %s, %s, %s, %s, %s)",rows,@@ -371,9 +381,9 @@ class MySQLCheckpointer:async def claim_run(self, thread_id: str, run_id: str) -> None:"""Atomically claim a run_id on a thread.- Lazy-creates the cubeloop_threads row, takes a per-thread FOR UPDATE+ Lazy-creates the cubepi_threads row, takes a per-thread FOR UPDATElock to serialize concurrent claims for the same thread, then- checks cubeloop_runs for an existing row before inserting. The+ checks cubepi_runs for an existing row before inserting. Thepre-check matches the Postgres approach — using INSERT + catchingIntegrityError would also work, but a pre-SELECT lets usdistinguish in-flight vs completed cleanly without relying on the@@ -386,19 +396,19 @@ class MySQLCheckpointer:async with conn.cursor() as cur:# Lazy thread row creation (claim may precede any append).await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) ""ON DUPLICATE KEY UPDATE thread_id = thread_id",(thread_id,),)# Per-thread fence: serializes claim_run/append/fork on# the same thread (matches Postgres's pg_advisory_xact_lock).await cur.execute(- "SELECT thread_id FROM cubeloop_threads "+ "SELECT thread_id FROM cubepi_threads ""WHERE thread_id = %s FOR UPDATE",(thread_id,),)await cur.execute(- "SELECT completed_at FROM cubeloop_runs "+ "SELECT completed_at FROM cubepi_runs ""WHERE thread_id = %s AND run_id = %s",(thread_id, run_id),)@@ -412,7 +422,7 @@ class MySQLCheckpointer:f"thread={thread_id} run={run_id} in flight")await cur.execute(- "INSERT INTO cubeloop_runs (thread_id, run_id) VALUES (%s, %s)",+ "INSERT INTO cubepi_runs (thread_id, run_id) VALUES (%s, %s)",(thread_id, run_id),)await conn.commit()@@ -434,12 +444,12 @@ class MySQLCheckpointer:try:async with conn.cursor() as cur:await cur.execute(- "SELECT thread_id FROM cubeloop_threads "+ "SELECT thread_id FROM cubepi_threads ""WHERE thread_id = %s FOR UPDATE",(thread_id,),)await cur.execute(- "SELECT completed_at FROM cubeloop_runs "+ "SELECT completed_at FROM cubepi_runs ""WHERE thread_id = %s AND run_id = %s",(thread_id, run_id),)@@ -453,13 +463,13 @@ class MySQLCheckpointer:return # idempotent successawait cur.execute("SELECT COALESCE(MAX(completion_seq), 0) + 1 "- "FROM cubeloop_runs WHERE thread_id = %s "+ "FROM cubepi_runs WHERE thread_id = %s ""AND completion_seq IS NOT NULL",(thread_id,),)(next_seq,) = await cur.fetchone()await cur.execute(- "UPDATE cubeloop_runs SET completed_at = CURRENT_TIMESTAMP, "+ "UPDATE cubepi_runs SET completed_at = CURRENT_TIMESTAMP, ""completion_seq = %s ""WHERE thread_id = %s AND run_id = %s",(next_seq, thread_id, run_id),@@ -482,7 +492,7 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT pending_request, run_id FROM cubeloop_threads "+ "SELECT pending_request, run_id FROM cubepi_threads ""WHERE thread_id = %s",(thread_id,),)@@ -509,13 +519,13 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT 1 FROM cubeloop_threads WHERE thread_id = %s",+ "SELECT 1 FROM cubepi_threads WHERE thread_id = %s",(thread_id,),)if await cur.fetchone() is None:raise ThreadNotFoundError(f"thread={thread_id}")await cur.execute(- "SELECT completion_seq FROM cubeloop_runs "+ "SELECT completion_seq FROM cubepi_runs ""WHERE thread_id = %s AND run_id = %s",(thread_id, after_run_id),)@@ -526,10 +536,10 @@ class MySQLCheckpointer:)cutoff = cutoff_row[0]await cur.execute(- "SELECT seq, role, metadata, payload FROM cubeloop_messages "+ "SELECT seq, role, metadata, payload FROM cubepi_messages ""WHERE thread_id = %s AND ("" run_id IS NULL OR run_id IN ("- " SELECT run_id FROM cubeloop_runs "+ " SELECT run_id FROM cubepi_runs "" WHERE thread_id = %s "" AND completion_seq IS NOT NULL "" AND completion_seq <= %s"@@ -553,10 +563,10 @@ class MySQLCheckpointer:) -> None:"""Copy completed prefix of ``src_thread_id`` into ``new_thread_id``.- Threads-row first: the destination ``cubeloop_threads`` row is+ Threads-row first: the destination ``cubepi_threads`` row isinserted before the message + runs copies so callers see a- complete view if they probe mid-fork. There is no cubeloop_runs ->- cubeloop_threads FK on MySQL (partition limitation), but we keep+ complete view if they probe mid-fork. There is no cubepi_runs ->+ cubepi_threads FK on MySQL (partition limitation), but we keepthe same ordering for semantic parity with Postgres.Per-thread serialization: a ``SELECT … FOR UPDATE`` on the source@@ -571,7 +581,7 @@ class MySQLCheckpointer:async with conn.cursor() as cur:# Per-thread fence on the source thread.await cur.execute(- "SELECT thread_id FROM cubeloop_threads "+ "SELECT thread_id FROM cubepi_threads ""WHERE thread_id = %s FOR UPDATE",(src_thread_id,),)@@ -579,14 +589,14 @@ class MySQLCheckpointer:raise ThreadNotFoundError(f"thread={src_thread_id}")# Destination must not exist.await cur.execute(- "SELECT 1 FROM cubeloop_threads WHERE thread_id = %s",+ "SELECT 1 FROM cubepi_threads WHERE thread_id = %s",(new_thread_id,),)if await cur.fetchone() is not None:raise ThreadAlreadyExistsError(f"thread={new_thread_id}")# Cutoff: after_run_id must be completed on src.await cur.execute(- "SELECT completion_seq FROM cubeloop_runs "+ "SELECT completion_seq FROM cubepi_runs ""WHERE thread_id = %s AND run_id = %s",(src_thread_id, after_run_id),)@@ -598,7 +608,7 @@ class MySQLCheckpointer:cutoff = cutoff_row[0]# Build merged extra (carry parent's extra + fork metadata).await cur.execute(- "SELECT extra FROM cubeloop_threads WHERE thread_id = %s",+ "SELECT extra FROM cubepi_threads WHERE thread_id = %s",(src_thread_id,),)extra_row = await cur.fetchone()@@ -612,7 +622,7 @@ class MySQLCheckpointer:# with the Postgres FK-driven ordering, even though MySQL# has no FK on the partitioned messages/runs tables).await cur.execute(- "INSERT INTO cubeloop_threads "+ "INSERT INTO cubepi_threads ""(thread_id, parent_thread_id, forked_at_seq, extra) ""VALUES (%s, %s, %s, %s)",(@@ -624,13 +634,13 @@ class MySQLCheckpointer:)# Copy messages: legacy NULL run_id OR completed-at-cutoff.await cur.execute(- "INSERT INTO cubeloop_messages "+ "INSERT INTO cubepi_messages ""(thread_id, seq, role, metadata, payload, run_id) ""SELECT %s, seq, role, metadata, payload, run_id "- "FROM cubeloop_messages "+ "FROM cubepi_messages ""WHERE thread_id = %s AND ("" run_id IS NULL OR run_id IN ("- " SELECT run_id FROM cubeloop_runs "+ " SELECT run_id FROM cubepi_runs "" WHERE thread_id = %s "" AND completion_seq IS NOT NULL "" AND completion_seq <= %s"@@ -640,12 +650,12 @@ class MySQLCheckpointer:)# Copy completed runs satisfying the cutoff.await cur.execute(- "INSERT INTO cubeloop_runs "+ "INSERT INTO cubepi_runs ""(thread_id, run_id, claimed_at, completed_at, "" completion_seq) ""SELECT %s, run_id, claimed_at, completed_at, "" completion_seq "- "FROM cubeloop_runs "+ "FROM cubepi_runs ""WHERE thread_id = %s ""AND completion_seq IS NOT NULL ""AND completion_seq <= %s",@@ -667,12 +677,12 @@ class MySQLCheckpointer:# also swallow unrelated errors and emit a duplicate-key# warning when the row already exists.await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) ""ON DUPLICATE KEY UPDATE thread_id = thread_id",(thread_id,),)await cur.execute(- "SELECT extra FROM cubeloop_threads "+ "SELECT extra FROM cubepi_threads ""WHERE thread_id = %s FOR UPDATE",(thread_id,),)@@ -680,7 +690,7 @@ class MySQLCheckpointer:current = _decode_json(row[0]) if row is not None else {}merged = {**current, **extra}await cur.execute(- "UPDATE cubeloop_threads "+ "UPDATE cubepi_threads ""SET extra = %s, updated_at = CURRENT_TIMESTAMP ""WHERE thread_id = %s",(json.dumps(merged), thread_id),@@ -712,13 +722,13 @@ class MySQLCheckpointer:try:async with conn.cursor() as cur:await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) ""ON DUPLICATE KEY UPDATE thread_id = thread_id",(thread_id,),)if request is None:await cur.execute(- "UPDATE cubeloop_threads "+ "UPDATE cubepi_threads ""SET pending_request = NULL, run_id = NULL, ""updated_at = CURRENT_TIMESTAMP WHERE thread_id = %s",(thread_id,),@@ -726,7 +736,7 @@ class MySQLCheckpointer:else:payload = request.model_dump_json()await cur.execute(- "UPDATE cubeloop_threads "+ "UPDATE cubepi_threads ""SET pending_request = %s, run_id = %s, ""updated_at = CURRENT_TIMESTAMP WHERE thread_id = %s",(payload, run_id, thread_id),@@ -741,7 +751,7 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT pending_request FROM cubeloop_threads WHERE thread_id = %s",+ "SELECT pending_request FROM cubepi_threads WHERE thread_id = %s",(thread_id,),)row = await cur.fetchone()@@ -766,7 +776,7 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT run_id FROM cubeloop_threads "+ "SELECT run_id FROM cubepi_threads ""WHERE thread_id = %s AND pending_request IS NOT NULL",(thread_id,),)@@ -788,12 +798,12 @@ class MySQLCheckpointer:try:async with conn.cursor() as cur:await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) ""ON DUPLICATE KEY UPDATE thread_id = thread_id",(thread_id,),)await cur.execute(- "INSERT INTO cubeloop_hitl_answers "+ "INSERT INTO cubepi_hitl_answers ""(thread_id, run_id, question_id, answer) ""VALUES (%s, %s, %s, %s) ""ON DUPLICATE KEY UPDATE "@@ -817,7 +827,7 @@ class MySQLCheckpointer:async with self._pool.acquire() as conn:async with conn.cursor() as cur:await cur.execute(- "SELECT answer FROM cubeloop_hitl_answers "+ "SELECT answer FROM cubepi_hitl_answers ""WHERE thread_id = %s AND run_id = %s AND question_id = %s",(thread_id, _run_key(run_id), question_id),)@@ -841,7 +851,7 @@ class MySQLCheckpointer:async with conn.cursor() as cur:if question_ids is None:await cur.execute(- "DELETE FROM cubeloop_hitl_answers "+ "DELETE FROM cubepi_hitl_answers ""WHERE thread_id = %s AND run_id = %s",(thread_id, run_key),)@@ -850,7 +860,7 @@ class MySQLCheckpointer:if qids:placeholders = ",".join("%s" for _ in qids)await cur.execute(- "DELETE FROM cubeloop_hitl_answers "+ "DELETE FROM cubepi_hitl_answers ""WHERE thread_id = %s AND run_id = %s "f"AND question_id IN ({placeholders})",(thread_id, run_key, *qids),diff --git a/cubeloop/checkpointer/mysql/models.py b/cubeloop/checkpointer/mysql/models.pyindex 7c79f4b..473c35e 100644--- a/cubeloop/checkpointer/mysql/models.py+++ b/cubeloop/checkpointer/mysql/models.py@@ -16,7 +16,7 @@ import sqlalchemy as safrom sqlalchemy.dialects.mysql import JSON, LONGBLOB, VARCHARfrom sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column-EXPECTED_SCHEMA_VERSION = 6+EXPECTED_SCHEMA_VERSION = 5PARTITION_COUNT = 64cubeloop_metadata = sa.MetaData()@@ -29,13 +29,13 @@ class CubeloopBase(DeclarativeBase):class CubeloopThread(CubeloopBase):- __tablename__ = "cubeloop_threads"+ __tablename__ = "cubepi_threads"__table_args__ = {"mysql_engine": "InnoDB"}thread_id: Mapped[str] = mapped_column(_TID, primary_key=True)parent_thread_id: Mapped[str | None] = mapped_column(_TID,- sa.ForeignKey("cubeloop_threads.thread_id"),+ sa.ForeignKey("cubepi_threads.thread_id"),nullable=True,)forked_at_seq: Mapped[int | None] = mapped_column(sa.BigInteger, nullable=True)@@ -72,9 +72,9 @@ class CubeloopThread(CubeloopBase):class CubeloopMessage(CubeloopBase):- __tablename__ = "cubeloop_messages"+ __tablename__ = "cubepi_messages"__table_args__ = (- sa.Index("ix_cubeloop_messages_thread_run", "thread_id", "run_id"),+ sa.Index("ix_cubepi_messages_thread_run", "thread_id", "run_id"),{"mysql_engine": "InnoDB"},)@@ -92,7 +92,7 @@ class CubeloopMessage(CubeloopBase):payload: Mapped[bytes] = mapped_column(LONGBLOB, nullable=False)# v4: opaque host-side run identifier stamped on each message. Lets# fork/snapshot include only messages from completed runs. VARCHAR(255)- # to match the cubeloop_messages indexing convention (thread_id is also+ # to match the cubepi_messages indexing convention (thread_id is also# VARCHAR(255) — keeps the composite index cardinality consistent).run_id: Mapped[str | None] = mapped_column(VARCHAR(255),@@ -109,15 +109,15 @@ class CubeloopRun(CubeloopBase):"""v4 per-run lifecycle row.Primary key (thread_id, run_id). KEY-partitioned by thread_id to match- cubeloop_messages. NO FK to cubeloop_threads — MySQL forbids FKs on+ cubepi_messages. NO FK to cubepi_threads — MySQL forbids FKs onpartitioned tables. The partition clause cannot be expressed inSQLAlchemy declarative and lives in``alembic_helpers.runs_partition_clause()``."""- __tablename__ = "cubeloop_runs"+ __tablename__ = "cubepi_runs"__table_args__ = (- sa.Index("ix_cubeloop_runs_thread_seq", "thread_id", "completion_seq"),+ sa.Index("ix_cubepi_runs_thread_seq", "thread_id", "completion_seq"),{"mysql_engine": "InnoDB"},)@@ -136,7 +136,7 @@ class CubeloopRun(CubeloopBase):class CubeloopHitlAnswer(CubeloopBase):- __tablename__ = "cubeloop_hitl_answers"+ __tablename__ = "cubepi_hitl_answers"__table_args__ = {"mysql_engine": "InnoDB"}thread_id: Mapped[str] = mapped_column(_TID, primary_key=True)@@ -151,7 +151,7 @@ class CubeloopHitlAnswer(CubeloopBase):class CubeloopSchemaVersion(CubeloopBase):- __tablename__ = "cubeloop_schema_version"+ __tablename__ = "cubepi_schema_version"__table_args__ = {"mysql_engine": "InnoDB"}version: Mapped[int] = mapped_column(sa.Integer, primary_key=True)diff --git a/cubeloop/checkpointer/postgres/README.md b/cubeloop/checkpointer/postgres/README.mdindex a585811..edd7a2c 100644--- a/cubeloop/checkpointer/postgres/README.md+++ b/cubeloop/checkpointer/postgres/README.md@@ -39,13 +39,13 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VE| Symbol | Use ||---|---|| `cubeloop_metadata` | SQLAlchemy `MetaData` — set as Alembic `target_metadata` |-| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `6`) |+| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `5`) |The SQL helpers live in the `alembic_helpers` submodule:```pythonfrom cubeloop.checkpointer.postgres.alembic_helpers import (- create_message_partitions_op, # DDL for the 64 hash partitions of cubeloop_messages+ create_message_partitions_op, # DDL for the 64 hash partitions of cubepi_messagesadd_pending_request_column_op, # v1→v2 column add (idempotent, IF NOT EXISTS)write_schema_version_op, # sets schema_version to EXPECTED_SCHEMA_VERSION)@@ -53,15 +53,15 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (## Tables-`cubeloop_metadata` defines the current (v6) tables:+`cubeloop_metadata` defines the current (v5) tables:| Table | Purpose ||---|---|-| `cubeloop_threads` | One row per thread; holds `pending_request JSONB NULL` (HITL, v2+) |-| `cubeloop_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, **HASH-partitioned** on `thread_id` into 64 partitions |-| `cubeloop_runs` | Per-run claim/completion (v4+), HASH-partitioned |-| `cubeloop_hitl_answers` | Durable HITL answers (v5+) |-| `cubeloop_schema_version` | Single-row version marker verified on connect |+| `cubepi_threads` | One row per thread; holds `pending_request JSONB NULL` (HITL, v2+) |+| `cubepi_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, **HASH-partitioned** on `thread_id` into 64 partitions |+| `cubepi_runs` | Per-run claim/completion (v4+), HASH-partitioned |+| `cubepi_hitl_answers` | Durable HITL answers (v5+) |+| `cubepi_schema_version` | Single-row version marker verified on connect |## Wiring Alembic (`env.py`)@@ -87,14 +87,14 @@ correct columns** (they come straight from `cubeloop_metadata`). Two thingsSQLAlchemy autogenerate does not reliably produce, so add them to thegenerated migration yourself:-1. **Child partitions.** `cubeloop_messages` is HASH-partitioned on+1. **Child partitions.** `cubepi_messages` is HASH-partitioned on`thread_id` (the model declares this via`__table_args__["postgresql_partition_by"]`). Keep the autogenerated- `create_table` for `cubeloop_messages` — including all its columns — and+ `create_table` for `cubepi_messages` — including all its columns — andmake sure it carries `postgresql_partition_by="HASH (thread_id)"`. The64 child partitions are not autogenerated; create them with the helper.-2. **The version row.** Autogenerate creates the `cubeloop_schema_version`+2. **The version row.** Autogenerate creates the `cubepi_schema_version`table but never inserts a row.```python@@ -104,21 +104,21 @@ from cubeloop.checkpointer.postgres.alembic_helpers import ()def upgrade():- # ... autogenerated create_table() for cubeloop_threads,- # cubeloop_schema_version, and cubeloop_messages (keep ALL columns;- # ensure cubeloop_messages has postgresql_partition_by="HASH (thread_id)") ...+ # ... autogenerated create_table() for cubepi_threads,+ # cubepi_schema_version, and cubepi_messages (keep ALL columns;+ # ensure cubepi_messages has postgresql_partition_by="HASH (thread_id)") ...op.execute(create_message_partitions_op()) # the 64 child partitionsop.execute(write_schema_version_op()) # record EXPECTED_SCHEMA_VERSION```-> Do not hand-trim the `cubeloop_messages` columns. The checkpointer writes+> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes> and reads `(thread_id, seq, role, metadata, payload)`; dropping any of> them causes runtime SQL errors on the first append.## Upgrading schema versionsCubeLoop bumps `EXPECTED_SCHEMA_VERSION` when the schema changes; the-checkpointer refuses to connect if the row in `cubeloop_schema_version`+checkpointer refuses to connect if the row in `cubepi_schema_version`doesn't match. Each bump is one host migration.**v1 → v2** (HITL): adds `pending_request JSONB NULL` to `cubepi_threads`.diff --git a/cubeloop/checkpointer/postgres/alembic_helpers.py b/cubeloop/checkpointer/postgres/alembic_helpers.pyindex e46f513..f58e2ed 100644--- a/cubeloop/checkpointer/postgres/alembic_helpers.py+++ b/cubeloop/checkpointer/postgres/alembic_helpers.py@@ -1,20 +1,17 @@"""SQL helpers for host application alembic migrations."""-from cubeloop.checkpointer.postgres.models import (- EXPECTED_SCHEMA_VERSION,- PARTITION_COUNT,-)+from cubeloop.checkpointer.postgres.models import PARTITION_COUNTdef create_message_partitions_op() -> str:- """Return SQL DDL creating all 64 child partitions of cubeloop_messages.+ """Return SQL DDL creating all 64 child partitions of cubepi_messages.Call inside an alembic upgrade() via op.execute(), AFTER the parent- cubeloop_messages table has been created. Emits current (v6) names.+ cubepi_messages table has been created."""return "\n".join(- f"CREATE TABLE cubeloop_messages_p{i:02d} "- f"PARTITION OF cubeloop_messages "+ f"CREATE TABLE cubepi_messages_p{i:02d} "+ f"PARTITION OF cubepi_messages "f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"for i in range(PARTITION_COUNT))@@ -23,9 +20,8 @@ def create_message_partitions_op() -> str:def add_pending_request_column_op() -> str:"""Return SQL adding the v2 `pending_request` column to cubepi_threads.- Historical helper: still targets the pre-rename table name. Call inside- the host's alembic v1→v2 upgrade() via op.execute(). Idempotent under- repeated execution via IF NOT EXISTS.+ Call inside the host's alembic v1→v2 upgrade() via op.execute(). Idempotent+ under repeated execution via IF NOT EXISTS."""return "ALTER TABLE cubepi_threads ADD COLUMN IF NOT EXISTS pending_request JSONB"@@ -33,20 +29,19 @@ def add_pending_request_column_op() -> str:def add_run_id_column_op() -> str:"""Return SQL adding the v3 `run_id` column to cubepi_threads.- Historical helper: still targets the pre-rename table name.+ Call inside the host's alembic v2→v3 upgrade() via op.execute()."""return "ALTER TABLE cubepi_threads ADD COLUMN IF NOT EXISTS run_id TEXT"def create_runs_partitions_op() -> str:- """Return SQL DDL creating all child partitions of cubeloop_runs.+ """Return SQL DDL creating all child partitions of cubepi_runs.- Current-schema factory (v6 names). Historical v3→v4 inlines the old- cubepi_runs_pXX names and must not call this helper.+ Call after the partitioned cubepi_runs parent has been created."""return "\n".join(- f"CREATE TABLE cubeloop_runs_p{i:02d} "- f"PARTITION OF cubeloop_runs "+ f"CREATE TABLE cubepi_runs_p{i:02d} "+ f"PARTITION OF cubepi_runs "f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"for i in range(PARTITION_COUNT))@@ -55,15 +50,9 @@ def create_runs_partitions_op() -> str:def upgrade_v3_to_v4_op() -> str:"""Return SQL applying the v3→v4 schema changes.- Historical helper: still emits cubepi_* names, including inlined- cubepi_runs_pXX partitions (do not call create_runs_partitions_op()).+ Adds the run_id column and index, then creates cubepi_runs and its+ partitions."""- run_partitions = "\n".join(- f"CREATE TABLE cubepi_runs_p{i:02d} "- f"PARTITION OF cubepi_runs "- f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"- for i in range(PARTITION_COUNT)- )parts = ["ALTER TABLE cubepi_messages ADD COLUMN IF NOT EXISTS run_id TEXT;",(@@ -85,7 +74,7 @@ def upgrade_v3_to_v4_op() -> str:"CREATE INDEX IF NOT EXISTS ix_cubepi_runs_thread_seq ""ON cubepi_runs (thread_id, completion_seq);"),- run_partitions,+ create_runs_partitions_op(),]return "\n".join(parts)@@ -93,7 +82,7 @@ def upgrade_v3_to_v4_op() -> str:def upgrade_v4_to_v5_op() -> str:"""Return SQL applying the v4->v5 schema changes.- Historical helper: still emits cubepi_* names.+ Creates the durable HITL answer ledger table."""return ("CREATE TABLE IF NOT EXISTS cubepi_hitl_answers ("@@ -108,74 +97,10 @@ def upgrade_v4_to_v5_op() -> str:)-def upgrade_v5_to_v6_op() -> str:- """Rename cubepi_* tables/indexes/partitions to cubeloop_*.-- Complete (no-op) iff both cubeloop_threads and cubeloop_schema_version- exist. If data tables already moved but the version table did not,- rename the leftover. cubeloop_threads alone is not a no-op sentinel.-- Requires a complete v5 (including cubepi_schema_version). Missing- version table makes the rename fail as a whole.- """- message_parts = "\n".join(- f" ALTER TABLE cubepi_messages_p{i:02d} "- f"RENAME TO cubeloop_messages_p{i:02d};"- for i in range(PARTITION_COUNT)- )- run_parts = "\n".join(- f" ALTER TABLE cubepi_runs_p{i:02d} RENAME TO cubeloop_runs_p{i:02d};"- for i in range(PARTITION_COUNT)- )- return f"""-DO $$-BEGIN- IF to_regclass('cubeloop_threads') IS NOT NULL- AND to_regclass('cubeloop_schema_version') IS NOT NULL THEN- RETURN;- END IF;-- IF to_regclass('cubeloop_threads') IS NOT NULL- AND to_regclass('cubepi_schema_version') IS NOT NULL THEN- ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version;- RETURN;- END IF;-- ALTER TABLE cubepi_threads RENAME TO cubeloop_threads;- ALTER TABLE cubepi_messages RENAME TO cubeloop_messages;-{message_parts}- ALTER TABLE cubepi_runs RENAME TO cubeloop_runs;-{run_parts}- ALTER TABLE cubepi_hitl_answers RENAME TO cubeloop_hitl_answers;- ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version;- ALTER INDEX IF EXISTS ix_cubepi_messages_metadata_gin- RENAME TO ix_cubeloop_messages_metadata_gin;- ALTER INDEX IF EXISTS ix_cubepi_messages_thread_run- RENAME TO ix_cubeloop_messages_thread_run;- ALTER INDEX IF EXISTS ix_cubepi_runs_thread_seq- RENAME TO ix_cubeloop_runs_thread_seq;-END $$;-"""--def write_schema_version_op() -> str:- """Write EXPECTED_SCHEMA_VERSION to cubeloop_schema_version if that- table exists, else to cubepi_schema_version.-- One ``DO $$`` block so asyncpg / Alembic send it as a single statement.- """- n = EXPECTED_SCHEMA_VERSION- return f"""-DO $$-BEGIN- IF to_regclass('cubeloop_schema_version') IS NOT NULL THEN- DELETE FROM cubeloop_schema_version WHERE version <> {n};- INSERT INTO cubeloop_schema_version (version) VALUES ({n})- ON CONFLICT DO NOTHING;- ELSE- DELETE FROM cubepi_schema_version WHERE version <> {n};- INSERT INTO cubepi_schema_version (version) VALUES ({n})- ON CONFLICT DO NOTHING;- END IF;-END $$;-"""+ """Return the immutable v5 schema-version write used by host migrations."""+ return (+ "DELETE FROM cubepi_schema_version WHERE version <> 5; "+ "INSERT INTO cubepi_schema_version (version) VALUES (5) "+ "ON CONFLICT DO NOTHING;"+ )diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.pyindex 3f5bf4e..0e2d0b2 100644--- a/cubeloop/checkpointer/postgres/checkpointer.py+++ b/cubeloop/checkpointer/postgres/checkpointer.py@@ -52,6 +52,13 @@ def _schema_mismatch_hint(actual: int, expected: int) -> str:between ``actual`` and ``expected``, rather than hardcoding one versiontransition, so the hint stays correct as EXPECTED_SCHEMA_VERSION grows."""+ if actual > expected:+ return (+ "database schema is newer than this CubeLoop release. If withdrawn "+ "0.14.0 wrote version 6, inspect the database and follow "+ "https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"+ "from-withdrawn-0140; do not run a forward migration."+ )steps = ", ".join(f"upgrade_v{v}_to_v{v + 1}_op()" for v in range(actual, expected))return ("cubeloop was upgraded but host alembic is behind. "@@ -62,18 +69,16 @@ def _schema_mismatch_hint(actual: int, expected: int) -> str:)-_V5_TO_V6_HINT = (- "Generate a new alembic revision that calls "- "upgrade_v5_to_v6_op() + write_schema_version_op() "- "(see cubeloop.checkpointer.postgres.alembic_helpers) and run "- "`alembic upgrade head` against this database."-)-_MISSING_VERSION_TABLE_HINT = ("data tables exist but schema_version is missing; cannot auto-classify. "- "If tables are still cubepi_*, CREATE TABLE cubepi_schema_version and "- "INSERT 5, then run upgrade_v5_to_v6_op(). Do not apply fresh v6 "- "CREATE TABLE on existing data."+ "Restore cubepi_schema_version from the host's Alembic history; do not "+ "apply fresh CREATE TABLE statements on existing data."+)++_WITHDRAWN_V6_HINT = (+ "database uses the withdrawn 0.14.0 cubeloop_* schema. Inspect it and "+ "follow https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"+ "from-withdrawn-0140; do not run a forward migration.")@@ -105,7 +110,7 @@ _ROLE_TO_CLS: dict[str, type[Message]] = {def _deserialize_row(thread_id: str, r: Any) -> Message:- """Deserialize one cubeloop_messages row; corruption raises typed."""+ """Deserialize one cubepi_messages row; corruption raises typed."""try:cls = _ROLE_TO_CLS.get(r["role"])if cls is None:@@ -122,7 +127,7 @@ def _deserialize_row(thread_id: str, r: Any) -> Message:raise CheckpointCorruptionError(thread_id=thread_id,backend="postgres",- row_ref=f"cubeloop_messages.seq={r['seq']}",+ row_ref=f"cubepi_messages.seq={r['seq']}",cause=exc,) from exc@@ -172,37 +177,38 @@ class PostgresCheckpointer:async with self._pool.acquire() as conn:try:row = await conn.fetchrow(- "SELECT version FROM cubeloop_schema_version LIMIT 1"+ "SELECT version FROM cubepi_schema_version LIMIT 1")except asyncpg.UndefinedTableError:try:- legacy = await conn.fetchrow(- "SELECT version FROM cubepi_schema_version LIMIT 1"+ withdrawn = await conn.fetchrow(+ "SELECT version FROM cubeloop_schema_version LIMIT 1")- except asyncpg.UndefinedTableError as e:- has_data = await conn.fetchval(- "SELECT to_regclass('cubepi_threads') IS NOT NULL "- "OR to_regclass('cubeloop_threads') IS NOT NULL"+ except asyncpg.UndefinedTableError:+ withdrawn = None+ if withdrawn is not None:+ actual = int(withdrawn["version"])+ raise CubeloopSchemaMismatch(+ expected=EXPECTED_SCHEMA_VERSION,+ actual=actual,+ hint=_WITHDRAWN_V6_HINT,)- if has_data:- raise CubeloopSchemaMismatch(- expected=EXPECTED_SCHEMA_VERSION,- actual=0,- hint=_MISSING_VERSION_TABLE_HINT,- ) from e- raise CubeloopSchemaUninitialized(- "cubeloop tables not found. Run host application's "- "alembic upgrade."- ) from e- actual = 0 if legacy is None else int(legacy["version"])- raise CubeloopSchemaMismatch(- expected=EXPECTED_SCHEMA_VERSION,- actual=actual,- hint=_V5_TO_V6_HINT,+ has_data = await conn.fetchval(+ "SELECT to_regclass('cubepi_threads') IS NOT NULL "+ "OR to_regclass('cubeloop_threads') IS NOT NULL"+ )+ if has_data:+ raise CubeloopSchemaMismatch(+ expected=EXPECTED_SCHEMA_VERSION,+ actual=0,+ hint=_MISSING_VERSION_TABLE_HINT,+ )+ raise CubeloopSchemaUninitialized(+ "cubepi tables not found. Run host application's alembic upgrade.")if row is None:raise CubeloopSchemaUninitialized(- "cubeloop_schema_version table is empty. Host alembic "+ "cubepi_schema_version table is empty. Host alembic ""migration must INSERT the current version ""(use write_schema_version_op()).")@@ -217,12 +223,12 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:msg_rows = await conn.fetch(- "SELECT seq, role, metadata, payload FROM cubeloop_messages "+ "SELECT seq, role, metadata, payload FROM cubepi_messages ""WHERE thread_id = $1 ORDER BY seq",thread_id,)extra_row = await conn.fetchrow(- "SELECT extra, parent_thread_id FROM cubeloop_threads "+ "SELECT extra, parent_thread_id FROM cubepi_threads ""WHERE thread_id = $1",thread_id,)@@ -264,14 +270,14 @@ class PostgresCheckpointer:)# Lazy thread row creationawait conn.execute(- "INSERT INTO cubeloop_threads (thread_id) "+ "INSERT INTO cubepi_threads (thread_id) ""VALUES ($1) ON CONFLICT DO NOTHING",thread_id,)# Pre-flight: reject append on any completed run_id.if run_ids:done_rows = await conn.fetch(- "SELECT run_id FROM cubeloop_runs "+ "SELECT run_id FROM cubepi_runs ""WHERE thread_id = $1 AND run_id = ANY($2::text[]) ""AND completed_at IS NOT NULL",thread_id,@@ -284,7 +290,7 @@ class PostgresCheckpointer:)last_seq = (await conn.fetchval(- "SELECT COALESCE(MAX(seq), 0) FROM cubeloop_messages "+ "SELECT COALESCE(MAX(seq), 0) FROM cubepi_messages ""WHERE thread_id = $1",thread_id,)@@ -308,7 +314,7 @@ class PostgresCheckpointer:))await conn.executemany(- "INSERT INTO cubeloop_messages "+ "INSERT INTO cubepi_messages ""(thread_id, seq, role, metadata, payload, run_id) ""VALUES ($1, $2, $3, $4, $5, $6)",rows,@@ -324,7 +330,7 @@ class PostgresCheckpointer:)# Lazy thread row creation (claim may precede any append).await conn.execute(- "INSERT INTO cubeloop_threads (thread_id) "+ "INSERT INTO cubepi_threads (thread_id) ""VALUES ($1) ON CONFLICT (thread_id) DO NOTHING",thread_id,)@@ -332,7 +338,7 @@ class PostgresCheckpointer:# raise UniqueViolation (which would abort the txn before# we could distinguish in-flight vs completed).row = await conn.fetchrow(- "SELECT completed_at FROM cubeloop_runs "+ "SELECT completed_at FROM cubepi_runs ""WHERE thread_id = $1 AND run_id = $2",thread_id,run_id,@@ -346,7 +352,7 @@ class PostgresCheckpointer:f"thread={thread_id} run={run_id} in flight")await conn.execute(- "INSERT INTO cubeloop_runs (thread_id, run_id) VALUES ($1, $2)",+ "INSERT INTO cubepi_runs (thread_id, run_id) VALUES ($1, $2)",thread_id,run_id,)@@ -360,7 +366,7 @@ class PostgresCheckpointer:thread_id,)row = await conn.fetchrow(- "SELECT completed_at FROM cubeloop_runs "+ "SELECT completed_at FROM cubepi_runs ""WHERE thread_id = $1 AND run_id = $2",thread_id,run_id,@@ -373,12 +379,12 @@ class PostgresCheckpointer:return # idempotent successnext_seq = await conn.fetchval("SELECT COALESCE(MAX(completion_seq), 0) + 1 "- "FROM cubeloop_runs WHERE thread_id = $1 "+ "FROM cubepi_runs WHERE thread_id = $1 ""AND completion_seq IS NOT NULL",thread_id,)await conn.execute(- "UPDATE cubeloop_runs SET completed_at = now(), "+ "UPDATE cubepi_runs SET completed_at = now(), ""completion_seq = $3 ""WHERE thread_id = $1 AND run_id = $2",thread_id,@@ -392,7 +398,7 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:row = await conn.fetchrow(- "SELECT pending_request, run_id FROM cubeloop_threads "+ "SELECT pending_request, run_id FROM cubepi_threads ""WHERE thread_id = $1",thread_id,)@@ -410,13 +416,13 @@ class PostgresCheckpointer:async with self._pool.acquire() as conn:# Source thread must exist.t_row = await conn.fetchrow(- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",thread_id,)if t_row is None:raise ThreadNotFoundError(f"thread={thread_id}")cutoff = await conn.fetchval(- "SELECT completion_seq FROM cubeloop_runs "+ "SELECT completion_seq FROM cubepi_runs ""WHERE thread_id = $1 AND run_id = $2",thread_id,after_run_id,@@ -426,10 +432,10 @@ class PostgresCheckpointer:f"thread={thread_id} run={after_run_id} not completed")rows = await conn.fetch(- "SELECT seq, role, metadata, payload FROM cubeloop_messages "+ "SELECT seq, role, metadata, payload FROM cubepi_messages ""WHERE thread_id = $1 AND ("" run_id IS NULL OR run_id IN ("- " SELECT run_id FROM cubeloop_runs "+ " SELECT run_id FROM cubepi_runs "" WHERE thread_id = $1 "" AND completion_seq IS NOT NULL "" AND completion_seq <= $2"@@ -461,21 +467,21 @@ class PostgresCheckpointer:# / claim_run / save_extra / save_pending_request — so its# presence is the canonical "thread exists" gate).t_row = await conn.fetchrow(- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",src_thread_id,)if t_row is None:raise ThreadNotFoundError(f"thread={src_thread_id}")# Destination must not exist.dst_row = await conn.fetchrow(- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",new_thread_id,)if dst_row is not None:raise ThreadAlreadyExistsError(f"thread={new_thread_id}")# Cutoff: after_run_id must be completed on src.cutoff = await conn.fetchval(- "SELECT completion_seq FROM cubeloop_runs "+ "SELECT completion_seq FROM cubepi_runs ""WHERE thread_id = $1 AND run_id = $2",src_thread_id,after_run_id,@@ -486,7 +492,7 @@ class PostgresCheckpointer:)# Build merged extra (carry parent's extra + fork metadata).src_extra_row = await conn.fetchrow(- "SELECT extra FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT extra FROM cubepi_threads WHERE thread_id = $1",src_thread_id,)raw_extra = (@@ -499,9 +505,9 @@ class PostgresCheckpointer:if metadata is not None:base_extra["fork"] = json.loads(json.dumps(metadata))# INSERT destination threads row first to satisfy the- # cubeloop_messages / cubeloop_runs FKs on subsequent copies.+ # cubepi_messages / cubepi_runs FKs on subsequent copies.await conn.execute(- "INSERT INTO cubeloop_threads "+ "INSERT INTO cubepi_threads ""(thread_id, parent_thread_id, forked_at_seq, extra) ""VALUES ($1, $2, $3, $4::jsonb)",new_thread_id,@@ -512,13 +518,13 @@ class PostgresCheckpointer:# Copy messages whose run is NULL (legacy prefix) or completed# at or before cutoff. Preserve seq from the source.await conn.execute(- "INSERT INTO cubeloop_messages "+ "INSERT INTO cubepi_messages ""(thread_id, seq, role, metadata, payload, run_id) ""SELECT $1, seq, role, metadata, payload, run_id "- "FROM cubeloop_messages "+ "FROM cubepi_messages ""WHERE thread_id = $2 AND ("" run_id IS NULL OR run_id IN ("- " SELECT run_id FROM cubeloop_runs "+ " SELECT run_id FROM cubepi_runs "" WHERE thread_id = $2 "" AND completion_seq IS NOT NULL "" AND completion_seq <= $3"@@ -530,10 +536,10 @@ class PostgresCheckpointer:)# Copy completed runs satisfying the cutoff.await conn.execute(- "INSERT INTO cubeloop_runs "+ "INSERT INTO cubepi_runs ""(thread_id, run_id, claimed_at, completed_at, completion_seq) ""SELECT $1, run_id, claimed_at, completed_at, completion_seq "- "FROM cubeloop_runs "+ "FROM cubepi_runs ""WHERE thread_id = $2 ""AND completion_seq IS NOT NULL ""AND completion_seq <= $3",@@ -546,10 +552,10 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:await conn.execute(- "INSERT INTO cubeloop_threads (thread_id, extra, updated_at) "+ "INSERT INTO cubepi_threads (thread_id, extra, updated_at) ""VALUES ($1, $2::jsonb, now()) ""ON CONFLICT (thread_id) DO UPDATE "- "SET extra = cubeloop_threads.extra || EXCLUDED.extra, "+ "SET extra = cubepi_threads.extra || EXCLUDED.extra, "" updated_at = now()",thread_id,json.dumps(extra),@@ -576,13 +582,13 @@ class PostgresCheckpointer:async with conn.transaction():# Ensure thread row exists (lazy creation matches save_extra path).await conn.execute(- "INSERT INTO cubeloop_threads (thread_id) "+ "INSERT INTO cubepi_threads (thread_id) ""VALUES ($1) ON CONFLICT DO NOTHING",thread_id,)if request is None:await conn.execute(- "UPDATE cubeloop_threads "+ "UPDATE cubepi_threads ""SET pending_request = NULL, run_id = NULL, ""updated_at = now() WHERE thread_id = $1",thread_id,@@ -590,7 +596,7 @@ class PostgresCheckpointer:else:payload = request.model_dump_json()await conn.execute(- "UPDATE cubeloop_threads "+ "UPDATE cubepi_threads ""SET pending_request = $2::jsonb, run_id = $3, ""updated_at = now() WHERE thread_id = $1",thread_id,@@ -602,7 +608,7 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:row = await conn.fetchrow(- "SELECT pending_request FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT pending_request FROM cubepi_threads WHERE thread_id = $1",thread_id,)if row is None or row["pending_request"] is None:@@ -624,7 +630,7 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:row = await conn.fetchrow(- "SELECT run_id FROM cubeloop_threads "+ "SELECT run_id FROM cubepi_threads ""WHERE thread_id = $1 AND pending_request IS NOT NULL",thread_id,)@@ -643,12 +649,12 @@ class PostgresCheckpointer:async with self._pool.acquire() as conn:async with conn.transaction():await conn.execute(- "INSERT INTO cubeloop_threads (thread_id) "+ "INSERT INTO cubepi_threads (thread_id) ""VALUES ($1) ON CONFLICT DO NOTHING",thread_id,)await conn.execute(- "INSERT INTO cubeloop_hitl_answers "+ "INSERT INTO cubepi_hitl_answers ""(thread_id, run_id, question_id, answer) ""VALUES ($1, $2, $3, $4::jsonb) ""ON CONFLICT (thread_id, run_id, question_id) DO UPDATE "@@ -669,7 +675,7 @@ class PostgresCheckpointer:assert self._pool is not Noneasync with self._pool.acquire() as conn:row = await conn.fetchrow(- "SELECT answer FROM cubeloop_hitl_answers "+ "SELECT answer FROM cubepi_hitl_answers ""WHERE thread_id = $1 AND run_id = $2 AND question_id = $3",thread_id,_run_key(run_id),@@ -691,7 +697,7 @@ class PostgresCheckpointer:async with self._pool.acquire() as conn:if question_ids is None:await conn.execute(- "DELETE FROM cubeloop_hitl_answers "+ "DELETE FROM cubepi_hitl_answers ""WHERE thread_id = $1 AND run_id = $2",thread_id,run_key,@@ -701,7 +707,7 @@ class PostgresCheckpointer:if not qids:returnawait conn.execute(- "DELETE FROM cubeloop_hitl_answers "+ "DELETE FROM cubepi_hitl_answers ""WHERE thread_id = $1 AND run_id = $2 ""AND question_id = ANY($3::text[])",thread_id,diff --git a/cubeloop/checkpointer/postgres/models.py b/cubeloop/checkpointer/postgres/models.pyindex fcc4edb..81bdf92 100644--- a/cubeloop/checkpointer/postgres/models.py+++ b/cubeloop/checkpointer/postgres/models.py@@ -15,7 +15,7 @@ import sqlalchemy as safrom sqlalchemy.dialects.postgresql import JSONBfrom sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column-EXPECTED_SCHEMA_VERSION = 6+EXPECTED_SCHEMA_VERSION = 5PARTITION_COUNT = 64cubeloop_metadata = sa.MetaData()@@ -26,12 +26,12 @@ class CubeloopBase(DeclarativeBase):class CubeloopThread(CubeloopBase):- __tablename__ = "cubeloop_threads"+ __tablename__ = "cubepi_threads"thread_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)parent_thread_id: Mapped[str | None] = mapped_column(sa.Text,- sa.ForeignKey("cubeloop_threads.thread_id"),+ sa.ForeignKey("cubepi_threads.thread_id"),nullable=True,)forked_at_seq: Mapped[int | None] = mapped_column(sa.BigInteger, nullable=True)@@ -67,21 +67,21 @@ class CubeloopThread(CubeloopBase):class CubeloopMessage(CubeloopBase):- __tablename__ = "cubeloop_messages"+ __tablename__ = "cubepi_messages"__table_args__ = (sa.Index(- "ix_cubeloop_messages_metadata_gin",+ "ix_cubepi_messages_metadata_gin","metadata",postgresql_using="gin",postgresql_ops={"metadata": "jsonb_path_ops"},),- sa.Index("ix_cubeloop_messages_thread_run", "thread_id", "run_id"),+ sa.Index("ix_cubepi_messages_thread_run", "thread_id", "run_id"),{"postgresql_partition_by": "HASH (thread_id)"},)thread_id: Mapped[str] = mapped_column(sa.Text,- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),primary_key=True,)seq: Mapped[int] = mapped_column(sa.BigInteger, primary_key=True)@@ -107,14 +107,14 @@ class CubeloopMessage(CubeloopBase):class CubeloopRun(CubeloopBase):- __tablename__ = "cubeloop_runs"+ __tablename__ = "cubepi_runs"__table_args__ = (- sa.Index("ix_cubeloop_runs_thread_seq", "thread_id", "completion_seq"),+ sa.Index("ix_cubepi_runs_thread_seq", "thread_id", "completion_seq"),{"postgresql_partition_by": "HASH (thread_id)"},)thread_id: Mapped[str] = mapped_column(sa.Text,- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),primary_key=True,)run_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)@@ -130,11 +130,11 @@ class CubeloopRun(CubeloopBase):class CubeloopHitlAnswer(CubeloopBase):- __tablename__ = "cubeloop_hitl_answers"+ __tablename__ = "cubepi_hitl_answers"thread_id: Mapped[str] = mapped_column(sa.Text,- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),primary_key=True,)run_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)@@ -148,6 +148,6 @@ class CubeloopHitlAnswer(CubeloopBase):class CubeloopSchemaVersion(CubeloopBase):- __tablename__ = "cubeloop_schema_version"+ __tablename__ = "cubepi_schema_version"version: Mapped[int] = mapped_column(sa.Integer, primary_key=True)diff --git a/dev/plans/2026-09-10-retain-cubepi-schema.md b/dev/plans/2026-09-10-retain-cubepi-schema.mdnew file mode 100644index 0000000..c1fa372--- /dev/null+++ b/dev/plans/2026-09-10-retain-cubepi-schema.md@@ -0,0 +1,84 @@+# Retain `cubepi_*` persistence schema — implementation plan++**Spec:** [`dev/specs/2026-09-10-retain-cubepi-schema.md`](../specs/2026-09-10-retain-cubepi-schema.md)++**Worktree:** `.worktrees/2026-09-10-retain-cubepi-schema` on branch+`2026-09-10-retain-cubepi-schema`.++## 1. Prepare withdrawal communication++- Prepare the public incident/recovery page and v0.14.0 release-note amendment.+- Do not yank until the recovery page is merged and deployed (or the release note+ contains the complete recovery procedure inline).++## 2. Restore the v5 persistence contract++- Change Postgres/MySQL model table/index names back to `cubepi_*` while retaining+ `Cubeloop*` Python names and `cubeloop_metadata`.+- Set both database `EXPECTED_SCHEMA_VERSION` constants to 5.+- Restore all runtime and verification SQL identifiers to `cubepi_*`; remove the+ v6-specific diagnosis path.+- Restore Alembic helper SQL to the exact 0.13.6 storage semantics and remove+ `upgrade_v5_to_v6_op()`.+- Restore examples and backend READMEs.++## 3. Create and test the recovery source++- Add canonical machine-readable scripts at+ `website/static/recovery/0.14.0/postgres-v6-to-v5.sql` and+ `website/static/recovery/0.14.0/mysql-v6-to-v5.sql`. These are the only+ executable recovery source; EN/zh-Hans docs link to the same downloads and+ explain backup, stop-the-world, execution, and verification rather than+ maintaining translated SQL copies.+- Each script performs collision/mixed-state preflight before mutation and+ restores tables, Postgres partitions, indexes, and schema version 5.+- Test both scripts against an exact v6 fixture with data, indexes, constraints,+ and partitions; prove preflight failure leaves mixed/colliding schemas intact.++## 4. Lock down migration reproducibility++- Add golden exact-output tests for every 0.13.6 helper, including order, types,+ terminators, partition count, and MySQL statement splitting.+- Add representative host migration-chain fixtures for Postgres and MySQL.+- Test empty database → v5 replay, prebuilt v5 → open, and data round trips.+- Add a regression assertion that normal schema code contains no physical+ `cubeloop_*` identifiers.++## 5. Repair packaging and documentation++- Bump root and shim projects to 0.14.1 and change shim dependency/extras to+ `>=0.14.1,<0.15`.+- Rewrite the current and version-0.14 migration/checkpoint docs in English and+ zh-Hans; include isolated emergency reverse-rename instructions for 0.14.0.+- Correct the existing 0.14 pages in place; do not rerun docs version creation or+ alter versions/sidebars/latest-version state.+- Update recipes, generated API references as required, changelog, and release+ notes. Record why the 0.14 snapshot was corrected.++## 6. Verify locally++- `uv sync --all-extras --dev`+- Targeted Postgres/MySQL/helper/shim tests.+- `uv run pytest tests/`+- `uv run ruff check cubeloop/ tests/`+- `uv run ruff format --check cubeloop/ tests/`+- `uv run mypy cubeloop`+- Website tests and production build.+- Build both distributions and smoke-test them from a clean temporary venv.++## 7. Reviews, PR, and release++- Ask the user before entering the local Codex review loop.+- Run spec → plan → code reviews with `codex:rescue`, fixing until clean.+- Commit and push the branch; open the replacement PR with test evidence.+- Run the PR Codex poll/fix/`@codex` loop until clean and wait for CI.+- Merge and wait for the recovery page and downloadable scripts to deploy.+- Amend the v0.14.0 GitHub release, yank both 0.14.0 PyPI projects with the+ approved reason, verify their JSON metadata, and close #223 as superseded.+- Verify the merged `main` commit already contains the reviewed 0.14.1 versions+ and changelog from this PR. Explicitly skip `dev/runbooks/cut-doc-version.md`+ and never run `docusaurus docs:version 0.14`; the existing snapshot was+ corrected in place.+- Tag that exact clean `main` commit as v0.14.1, publish both wheels, then verify+ PyPI metadata and clean-machine installation of both `cubeloop==0.14.1` and+ `cubepi==0.14.1`.diff --git a/dev/specs/2026-09-10-retain-cubepi-schema.md b/dev/specs/2026-09-10-retain-cubepi-schema.mdnew file mode 100644index 0000000..034788f--- /dev/null+++ b/dev/specs/2026-09-10-retain-cubepi-schema.md@@ -0,0 +1,164 @@+# Keep the CubePi persistence schema after the CubeLoop rename++- **Date:** 2026-09-10+- **Status:** Approved for implementation+- **Branch / worktree:** `2026-09-10-retain-cubepi-schema` → `.worktrees/2026-09-10-retain-cubepi-schema`+- **Supersedes:** the database-rename portions of [`2026-09-09-rename-cubeloop.md`](2026-09-09-rename-cubeloop.md)+- **Incident release:** `cubeloop==0.14.0` / `cubepi==0.14.0`++## Confirmed decisions++| Decision | Choice |+|---|---|+| Product, package, imports, CLI | Remain CubeLoop / `cubeloop` |+| Postgres and MySQL physical names | Keep `cubepi_*` permanently |+| Schema version | Remain v5; the brand rename is not a schema change |+| 0.14.0 | Yank both PyPI distributions, without deleting files or the GitHub tag/release |+| Recovery scope | No runtime dual-schema support; document an emergency reverse rename for any early adopter |+| Replacement | Publish 0.14.1 after clean review and CI |++## 1. Problem++The 0.14.0 brand rename also renamed Postgres/MySQL tables and indexes and raised+the schema version from 5 to 6. That coupled a public identity change to a+persistent storage protocol. It made rolling deploys and application rollback+unsafe and, more importantly, changed the output of helpers imported by+historical host Alembic revisions. A v1 revision that was valid with 0.13 can+therefore fail when replayed with 0.14.++Migration files must be reproducible. A helper already used by a released host+migration must retain its original SQL semantics regardless of the installed+CubeLoop version.++## 2. Prior art and deliberate divergence++- LangGraph's Postgres checkpointer keeps an append-only ordered list of literal+ migrations; a migration's position is its version and old entries are not+ rewritten. CubeLoop keeps host-owned Alembic rather than adopting runtime DDL,+ but adopts the same immutability rule for exported helpers.+- pi-agent-core / the pi coding agent versions its persisted session format+ independently of its presentation and repository identity. Claude Code also+ treats on-disk project/user state as a compatibility surface rather than a+ branding surface.+- CubeLoop deliberately keeps the historical `cubepi_*` SQL namespace while its+ Python and product namespace is `cubeloop`. The storage name is a wire-format+ identifier, not user-facing branding.++## 3. Required behavior++### 3.1 Models and runtime SQL++Postgres and MySQL SQLAlchemy models, metadata, verification queries, runtime+queries, error row references, examples, and DDL documentation use:++- `cubepi_threads`+- `cubepi_messages` and Postgres `cubepi_messages_p00`…`p63`+- `cubepi_runs` and Postgres `cubepi_runs_p00`…`p63`+- `cubepi_hitl_answers`+- `cubepi_schema_version`+- `ix_cubepi_*` indexes++Python class names and metadata variables remain `Cubeloop*` and+`cubeloop_metadata`; only their physical SQL names retain the legacy namespace.+SQLite remains unchanged.++`EXPECTED_SCHEMA_VERSION` is 5 for Postgres and MySQL. A valid 0.13.6 database+must open directly under 0.14.1 without DDL.++### 3.2 Alembic helpers are immutable++Restore the complete Postgres and MySQL helper output to the 0.13.6 semantics.+Remove `upgrade_v5_to_v6_op()` from the supported public API and documentation.+`write_schema_version_op()` writes version 5 to `cubepi_schema_version` only.++Golden tests freeze the exact normalized output of every exported 0.13.6 helper,+including statement order, types, partition count, terminators, and MySQL's+semicolon-splitting contract. `write_schema_version_op()` becomes a permanently+frozen v5 writer rather than tracking `EXPECTED_SCHEMA_VERSION`. Future schema+work adds explicitly versioned writers and helpers; it must not retarget an+existing helper or derive historical SQL from a mutable package constant.++### 3.3 0.14.0 early-adopter recovery++0.14.1 does not silently detect or mutate `cubeloop_*` databases. The migration+guide contains conspicuous, dialect-specific emergency reverse-rename SQL for a+database that actually ran the withdrawn v6 migration. It instructs operators to:++1. stop all application instances;+2. back up the database;+3. rename tables, all Postgres child partitions, and indexes back;+4. write schema version 5;+5. verify object names and row counts before starting 0.14.1.++The recovery is not part of the normal upgrade path.++The documented SQL is executable source, not an untested snippet. Integration+tests create the exact withdrawn 0.14.0 v6 schema, insert representative data,+execute the documented recovery statements from a shared source verbatim, and+verify v5 names, partitions, indexes, constraints, row counts, version 5, and a+successful 0.14.1 checkpointer round trip. A preflight must detect name+collisions or mixed v5/v6 schemas and fail before executing any rename.++### 3.4 Compatibility distribution++Publish `cubepi==0.14.1` with the real package. Its dependency and forwarded+extras use `cubeloop>=0.14.1,<0.15`, allowing compatible 0.14 patch fixes while+preventing an unreviewed minor-version jump. Both distributions remain versioned+and published together.++### 3.5 Documentation and frozen 0.14 snapshot++Update current English and zh-Hans checkpointing/migration docs, backend READMEs,+examples, API reference inputs, and the existing 0.14 versioned snapshot.+Although frozen snapshots normally do not change, 0.14.0 is withdrawn and 0.14.1+is the supported 0.14 release, so the snapshot must describe the safe 0.14+contract. Correct only the affected persistence/migration pages in place and+keep those pages at current/snapshot parity. Do **not** rerun+`docusaurus docs:version 0.14` or change version/sidebars/latest-version state.+Record this exception in the changelog and release notes.++Close PR #223 as superseded, preserving it as incident context.++## 4. Yank and release operations++Yank both `cubeloop==0.14.0` and `cubepi==0.14.0` on PyPI with the reason:++> Withdrawn: the database table rename breaks reproducible host Alembic history+> and safe rollback. Use 0.14.1 or later.++The public incident/recovery page must be live before its link is used. Release+order is: merge and deploy that page; amend the GitHub 0.14.0 release notes;+yank both PyPI projects; then publish 0.14.1. If an emergency yank must happen+before the docs deploy, put self-contained recovery instructions in the GitHub+release notes first. Do not delete artifacts, tags, or the GitHub release.+TestPyPI may be yanked too if supported, but PyPI is the release blocker.++The 0.14.1 release follows the normal patch-release runbook, but does not rerun+the docs-version creation runbook. Do not tag or publish until local Codex review+is clean, CI passes, and the PR Codex review loop is clean.++## 5. Acceptance criteria++- Both PyPI 0.14.0 projects report all files as yanked with the agreed reason.+- A v5 Postgres/MySQL fixture opens and preserves data with 0.14.1 code and no DDL.+- Fresh host Alembic history creates only `cubepi_*`, ends at version 5, and the+ checkpointer operates on it.+- Golden tests prove the complete 0.13.6 helper output and MySQL split contract+ remain unchanged.+- Both dialects recover an exact v6 fixture with representative data by executing+ the shipped recovery source; mixed/colliding schemas fail before mutation.+- No supported code or normal docs reference `upgrade_v5_to_v6_op()` or require+ `cubeloop_*` database objects.+- Unit/integration tests, Ruff, formatting, mypy, and docs build pass.+- 0.14.1 wheels smoke-test both `cubeloop` and the `cubepi` shim.+- Current and version-0.14 English/zh-Hans docs state that physical DB names stay+ `cubepi_*` and include the exceptional 0.14.0 recovery path.++## 6. Out of scope++- Reverting the Python/package/CLI/domain/GitHub rename.+- Reverting the new tracing namespace or trace directory.+- Supporting mixed old/new table sets at runtime.+- Yanking any 0.13.x release.+- Renaming the physical database namespace in a later release without a new,+ separately approved expand/migrate/contract design.diff --git a/examples/checkpointing_mysql.py b/examples/checkpointing_mysql.pyindex e4af062..c852e2d 100644--- a/examples/checkpointing_mysql.py+++ b/examples/checkpointing_mysql.py@@ -49,16 +49,15 @@ THREAD_ID = "user-42"async def bootstrap_schema(dsn: str) -> None:- """Create the cubeloop v6 schema.+ """Create the CubeLoop checkpointer schema v5.- In a real deployment this is your Alembic migration. Existing v5- databases should call upgrade_v5_to_v6_op() instead of this CREATE.+ In a real deployment this DDL belongs in the host's Alembic history."""conn = await aiomysql.connect(autocommit=True, **_parse_dsn(dsn))try:async with conn.cursor() as cur:await cur.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,forked_at_seq BIGINT NULL,@@ -69,12 +68,12 @@ async def bootstrap_schema(dsn: str) -> None:updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMPON UPDATE CURRENT_TIMESTAMP,CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)- REFERENCES cubeloop_threads (thread_id)+ REFERENCES cubepi_threads (thread_id)) ENGINE=InnoDB""")await cur.execute("""- CREATE TABLE cubeloop_messages (+ CREATE TABLE cubepi_messages (thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,seq BIGINT NOT NULL,role VARCHAR(32) NOT NULL,@@ -83,17 +82,17 @@ async def bootstrap_schema(dsn: str) -> None:run_id VARCHAR(255) NULL,created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,PRIMARY KEY (thread_id, seq),- KEY ix_cubeloop_messages_thread_run (thread_id, run_id)+ KEY ix_cubepi_messages_thread_run (thread_id, run_id)) ENGINE=InnoDB """+ messages_partition_clause())await cur.execute(- "CREATE TABLE cubeloop_schema_version (version INT PRIMARY KEY) "+ "CREATE TABLE cubepi_schema_version (version INT PRIMARY KEY) ""ENGINE=InnoDB")await cur.execute(create_runs_table_op())await cur.execute("""- CREATE TABLE cubeloop_hitl_answers (+ CREATE TABLE cubepi_hitl_answers (thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,run_id VARCHAR(255) NOT NULL,question_id VARCHAR(255) NOT NULL,diff --git a/examples/checkpointing_postgres.py b/examples/checkpointing_postgres.pyindex 378557e..598e58b 100644--- a/examples/checkpointing_postgres.py+++ b/examples/checkpointing_postgres.py@@ -48,17 +48,16 @@ THREAD_ID = "user-42"async def bootstrap_schema(dsn: str) -> None:- """Create the cubeloop v6 schema.+ """Create the CubeLoop checkpointer schema v5.- In a real deployment this is your Alembic migration. Existing v5- databases should call upgrade_v5_to_v6_op() instead of this CREATE.+ In a real deployment this DDL belongs in the host's Alembic history."""conn = await asyncpg.connect(dsn)try:await conn.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY,- parent_thread_id TEXT REFERENCES cubeloop_threads(thread_id),+ parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),forked_at_seq BIGINT,extra JSONB NOT NULL DEFAULT '{}'::jsonb,pending_request JSONB,@@ -68,9 +67,9 @@ async def bootstrap_schema(dsn: str) -> None:);""")await conn.execute("""- CREATE TABLE cubeloop_messages (+ CREATE TABLE cubepi_messages (thread_id TEXT NOT NULL- REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,+ REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,seq BIGINT NOT NULL,role TEXT NOT NULL,metadata JSONB NOT NULL DEFAULT '{}'::jsonb,@@ -82,15 +81,15 @@ async def bootstrap_schema(dsn: str) -> None:""")await conn.execute(create_message_partitions_op())await conn.execute("""- CREATE INDEX ix_cubeloop_messages_metadata_gin- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);+ CREATE INDEX ix_cubepi_messages_metadata_gin+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);""")await conn.execute("""- CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY);+ CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);""")await conn.execute("""- CREATE TABLE cubeloop_runs (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id)+ 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(),@@ -101,8 +100,8 @@ async def bootstrap_schema(dsn: str) -> None:""")await conn.execute(create_runs_partitions_op())await conn.execute("""- CREATE TABLE cubeloop_hitl_answers (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id)+ 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,diff --git a/pyproject.toml b/pyproject.tomlindex f4d1a01..7ecaa28 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,6 +1,6 @@[project]name = "cubeloop"-version = "0.14.0"+version = "0.14.1"description = "Pythonic async-native agent framework"readme = "README.md"license = "MIT"diff --git a/tests/checkpointer/test_alembic_helper_contract.py b/tests/checkpointer/test_alembic_helper_contract.pynew file mode 100644index 0000000..7231c86--- /dev/null+++ b/tests/checkpointer/test_alembic_helper_contract.py@@ -0,0 +1,45 @@+"""Golden contracts for helpers embedded in host Alembic history."""++from __future__ import annotations++import hashlib++from cubeloop.checkpointer.mysql import alembic_helpers as mysql+from cubeloop.checkpointer.postgres import alembic_helpers as postgres+++def _sha(value: str) -> str:+ return hashlib.sha256(value.encode()).hexdigest()+++def test_postgres_v5_helper_output_is_immutable() -> None:+ expected = {+ "create_message_partitions_op": "57e8dd437c937ebefc18cdb48b627319391b5b3448c928d331f52e8fb617f852",+ "add_pending_request_column_op": "318dd4212e5132f47042b78fe9be9b7e07af021e22b652fa8075dd34aa538e88",+ "add_run_id_column_op": "3cd63949435a8b140ee47de04c765a8b52e125cd9cfefec95067db0f1a8164bf",+ "create_runs_partitions_op": "8c20242b0b93aa78683d0f68b341483632031486b409157177822a54470d7968",+ "upgrade_v3_to_v4_op": "69a190dbaa3c9ba842504a45fd54fc5d858d202faa6e025f72bf7882aa9853c6",+ "upgrade_v4_to_v5_op": "a1d3efc24502a2564a8a5aba3045a0df0c13af3000c35f18407cf48811451e56",+ "write_schema_version_op": "b2260726818d8ab4ea437f15cd6c91e272a703057b9ef6a106fe5f68130a55bc",+ }+ assert {name: _sha(getattr(postgres, name)()) for name in expected} == expected+++def test_mysql_v5_helper_output_and_split_contract_are_immutable() -> None:+ expected = {+ "messages_partition_clause": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",+ "add_pending_request_column_op": "666f5c76247cf46ad3e4aef2b57402593108ceefa4fcf71f59a528d3424ab9e3",+ "add_run_id_column_op": "f601e64528136e153c4e4e0c2f37b0067378c7eeef97dc5f2a544c17c3ea1f9b",+ "runs_partition_clause": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",+ "add_messages_run_id_column_op": "8c0406e13ccc0c027df75b98a6825cfa88bf750930eaeb59090fa3208cf91a69",+ "create_runs_table_op": "c2fd37e2e2eb1ec2f88f0bd41c866b25cbf965012a061c34ced90031e45faf32",+ "create_runs_partitions_op": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",+ "upgrade_v3_to_v4_op": "e6d0a93e5e3abf4b27805fe428b813a0ae8d420e01c78964dc20988e2628dc31",+ "create_hitl_answers_table_op": "7d92af42b539319943f0a4d23dd51c884294d1f4281f1848a09f11992776a47c",+ "upgrade_v4_to_v5_op": "e71d86abf7d5b2d1534c577051c97faecc2386d37a9831063d1c603c64bdeb86",+ "write_schema_version_op": "555d7168cf0880e2a821b1199dbf8f35ee953db5daca4ca9e177005b4674e624",+ }+ assert {name: _sha(getattr(mysql, name)()) for name in expected} == expected+ assert (+ len([s for s in mysql.write_schema_version_op().split(";") if s.strip()]) == 2+ )diff --git a/tests/checkpointer/test_hitl_answer_ledger_unit.py b/tests/checkpointer/test_hitl_answer_ledger_unit.pyindex 1d18f4a..8c858c7 100644--- a/tests/checkpointer/test_hitl_answer_ledger_unit.py+++ b/tests/checkpointer/test_hitl_answer_ledger_unit.py@@ -102,9 +102,9 @@ async def test_postgres_hitl_answer_ledger_crud() -> None:await cp.clear_hitl_answers("t-1", run_id="r-1")sqls = [sql for sql, _args in conn.exec_calls]- assert any("cubeloop_hitl_answers" in sql for sql in sqls)+ assert any("cubepi_hitl_answers" in sql for sql in sqls)assert any("ON CONFLICT (thread_id, run_id, question_id)" in sql for sql in sqls)- assert any("DELETE FROM cubeloop_hitl_answers" in sql for sql in sqls)+ assert any("DELETE FROM cubepi_hitl_answers" in sql for sql in sqls)@pytest.mark.asyncio@@ -142,9 +142,9 @@ async def test_mysql_hitl_answer_ledger_crud() -> None:await cp.clear_hitl_answers("t-1", run_id="r-1")sqls = [sql for sql, _params in conn.exec_calls]- assert any("cubeloop_hitl_answers" in sql for sql in sqls)+ assert any("cubepi_hitl_answers" in sql for sql in sqls)assert any("ON DUPLICATE KEY UPDATE" in sql for sql in sqls)- assert any("DELETE FROM cubeloop_hitl_answers" in sql for sql in sqls)+ assert any("DELETE FROM cubepi_hitl_answers" in sql for sql in sqls)@pytest.mark.asynciodiff --git a/tests/checkpointer/test_mysql.py b/tests/checkpointer/test_mysql.pyindex e9a59c5..442fd48 100644--- a/tests/checkpointer/test_mysql.py+++ b/tests/checkpointer/test_mysql.py@@ -1,5 +1,7 @@"""MySQLCheckpointer tests — mirrors test_postgres.py."""+from pathlib import Path+import aiomysqlimport pytest@@ -37,34 +39,34 @@ def test_models_import() -> None:cubeloop_metadata,)- assert EXPECTED_SCHEMA_VERSION == 6+ assert EXPECTED_SCHEMA_VERSION == 5assert PARTITION_COUNT == 64- assert CubeloopThread.__tablename__ == "cubeloop_threads"- assert CubeloopMessage.__tablename__ == "cubeloop_messages"- assert CubeloopHitlAnswer.__tablename__ == "cubeloop_hitl_answers"- assert CubeloopSchemaVersion.__tablename__ == "cubeloop_schema_version"- assert "cubeloop_threads" in cubeloop_metadata.tables- assert "cubeloop_messages" in cubeloop_metadata.tables- assert "cubeloop_hitl_answers" in cubeloop_metadata.tables- assert "cubeloop_schema_version" in cubeloop_metadata.tables+ 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.tablesdef test_threads_parent_self_fk_present() -> None:"""parent_thread_id keeps a self-FK (threads table is not partitioned)."""from cubeloop.checkpointer.mysql.models import cubeloop_metadata- threads = cubeloop_metadata.tables["cubeloop_threads"]+ threads = cubeloop_metadata.tables["cubepi_threads"]fk_targets = {fk.column.table.name for col in threads.columns for fk in col.foreign_keys}- assert "cubeloop_threads" in fk_targets+ assert "cubepi_threads" in fk_targetsdef test_messages_has_no_foreign_keys() -> None:"""messages table is partitioned, so no FK is allowed."""from cubeloop.checkpointer.mysql.models import cubeloop_metadata- msgs = cubeloop_metadata.tables["cubeloop_messages"]+ msgs = cubeloop_metadata.tables["cubepi_messages"]assert msgs.foreign_keys == set()@@ -76,9 +78,9 @@ def test_messages_has_no_metadata_index() -> None:"""from cubeloop.checkpointer.mysql.models import cubeloop_metadata- msgs = cubeloop_metadata.tables["cubeloop_messages"]+ msgs = cubeloop_metadata.tables["cubepi_messages"]idx_names = {idx.name for idx in msgs.indexes}- assert idx_names == {"ix_cubeloop_messages_thread_run"}+ assert idx_names == {"ix_cubepi_messages_thread_run"}def test_messages_partition_clause() -> None:@@ -90,26 +92,13 @@ def test_write_schema_version_op_clears_stale_then_inserts() -> None:from cubeloop.checkpointer.mysql.models import EXPECTED_SCHEMA_VERSIONsql = write_schema_version_op()- assert "cubeloop_schema_version" in sqlassert "cubepi_schema_version" in sqlassert f"WHERE version <> {EXPECTED_SCHEMA_VERSION}" in sql- assert "INSERT IGNORE INTO cubeloop_schema_version" in sql- assert "PREPARE cp_stmt FROM @cp_del" in sql+ assert "INSERT IGNORE INTO cubepi_schema_version" in sql+ assert len([stmt for stmt in sql.split(";") if stmt.strip()]) == 2assert sql.index("DELETE") < sql.index("INSERT")-def test_upgrade_v5_to_v6_op_is_idempotent_guarded() -> None:- from cubeloop.checkpointer.mysql.alembic_helpers import upgrade_v5_to_v6_op-- sql = upgrade_v5_to_v6_op()- assert "information_schema.tables" in sql- assert "cubeloop_threads" in sql- assert "cubeloop_schema_version" in sql- assert "PREPARE cp_v6 FROM @cp_sql" in sql- assert "RENAME TABLE" in sql- assert "DO 0" in sql--def test_role_of_known_message_types() -> None:from cubeloop.checkpointer.mysql.checkpointer import _role_offrom cubeloop.providers.base import (@@ -232,7 +221,7 @@ async def _setup_schema(dsn: str) -> None:try:async with conn.cursor() as cur:await cur.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,forked_at_seq BIGINT NULL,@@ -243,12 +232,12 @@ async def _setup_schema(dsn: str) -> None:updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMPON UPDATE CURRENT_TIMESTAMP,CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)- REFERENCES cubeloop_threads (thread_id)+ REFERENCES cubepi_threads (thread_id)) ENGINE=InnoDB""")await cur.execute("""- CREATE TABLE cubeloop_messages (+ CREATE TABLE cubepi_messages (thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,seq BIGINT NOT NULL,role VARCHAR(32) NOT NULL,@@ -257,18 +246,18 @@ async def _setup_schema(dsn: str) -> None:run_id VARCHAR(255) NULL,created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,PRIMARY KEY (thread_id, seq),- KEY ix_cubeloop_messages_thread_run (thread_id, run_id)+ KEY ix_cubepi_messages_thread_run (thread_id, run_id)) ENGINE=InnoDB """+ messages_partition_clause())await cur.execute("""- CREATE TABLE cubeloop_schema_version (+ CREATE TABLE cubepi_schema_version (version INT PRIMARY KEY) ENGINE=InnoDB""")await cur.execute(create_runs_table_op())await cur.execute("""- CREATE TABLE cubeloop_hitl_answers (+ CREATE TABLE cubepi_hitl_answers (thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,run_id VARCHAR(255) NOT NULL,question_id VARCHAR(255) NOT NULL,@@ -458,7 +447,7 @@ async def test_version_mismatch_raises(clean_mysql_db) -> None:conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))try:async with conn.cursor() as cur:- await cur.execute("UPDATE cubeloop_schema_version SET version = 999")+ await cur.execute("UPDATE cubepi_schema_version SET version = 999")finally:await conn.ensure_closed()@@ -469,6 +458,8 @@ async def test_version_mismatch_raises(clean_mysql_db) -> None:assert exc_info.value.expected == EXPECTED_SCHEMA_VERSIONassert exc_info.value.actual == 999+ assert "withdrawn 0.14.0" in str(exc_info.value)+ assert "call +" not in str(exc_info.value)@pytest.mark.asyncio@@ -569,7 +560,7 @@ async def test_empty_version_table_raises_uninitialized(clean_mysql_db) -> None:conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))try:async with conn.cursor() as cur:- await cur.execute("DELETE FROM cubeloop_schema_version")+ await cur.execute("DELETE FROM cubepi_schema_version")finally:await conn.ensure_closed()@@ -594,11 +585,9 @@ async def test_load_unknown_role_raises(clean_mysql_db) -> None:conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))try:async with conn.cursor() as cur:+ await cur.execute("INSERT INTO cubepi_threads (thread_id) VALUES ('t-bad')")await cur.execute(- "INSERT INTO cubeloop_threads (thread_id) VALUES ('t-bad')"- )- await cur.execute(- "INSERT INTO cubeloop_messages "+ "INSERT INTO cubepi_messages ""(thread_id, seq, role, metadata, payload) ""VALUES ('t-bad', 1, 'bogus', '{}', %s)",(payload,),@@ -610,7 +599,7 @@ async def test_load_unknown_role_raises(clean_mysql_db) -> None:with pytest.raises(CheckpointCorruptionError, match="unknown role in DB") as ei:await cp.load("t-bad")assert isinstance(ei.value.__cause__, ValueError)- assert ei.value.row_ref == "cubeloop_messages.seq=1"+ assert ei.value.row_ref == "cubepi_messages.seq=1"@pytest.mark.asyncio@@ -659,10 +648,10 @@ async def test_mysql_load_corrupt_row_raises_typed(clean_mysql_db) -> None:try:async with conn.cursor() as cur:await cur.execute(- "UPDATE cubeloop_messages SET payload = %s "+ "UPDATE cubepi_messages SET payload = %s ""WHERE thread_id = 't-corrupt' AND seq = ("" SELECT max_seq FROM (SELECT max(seq) AS max_seq "- " FROM cubeloop_messages WHERE thread_id = 't-corrupt') AS sub)",+ " FROM cubepi_messages WHERE thread_id = 't-corrupt') AS sub)",(b"\xc1 not msgpack",),)finally:@@ -674,17 +663,28 @@ async def test_mysql_load_corrupt_row_raises_typed(clean_mysql_db) -> None:err = excinfo.valueassert err.thread_id == "t-corrupt"assert err.backend == "mysql"- assert err.row_ref.startswith("cubeloop_messages.seq=")+ assert err.row_ref.startswith("cubepi_messages.seq=")assert err.__cause__ is not None@pytest.mark.asyncio-async def test_v5_to_v6_rename_is_idempotent_before_version_write(+async def test_existing_v5_schema_round_trip_without_migration(clean_mysql_db,) -> None:- """Rename can retry after a failure before write_schema_version_op."""from cubeloop.checkpointer.mysql import MySQLCheckpointer- from cubeloop.checkpointer.mysql.alembic_helpers import upgrade_v5_to_v6_op+ from cubeloop.providers.base import TextContent, UserMessage++ await _setup_schema_v5(clean_mysql_db)+ async with MySQLCheckpointer(clean_mysql_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+++async def test_withdrawn_v6_recovery_script_round_trip(clean_mysql_db) -> None:+ from cubeloop.checkpointer.mysql import MySQLCheckpointerfrom cubeloop.checkpointer.mysql.checkpointer import _parse_dsnfrom cubeloop.providers.base import TextContent, UserMessage@@ -692,30 +692,120 @@ async def test_v5_to_v6_rename_is_idempotent_before_version_write(conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))try:async with conn.cursor() as cur:- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- await cur.execute(stmt)- # Simulate Alembic failing before the version writer, then retry.- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- await cur.execute(stmt)- for stmt in write_schema_version_op().split(";"):- if stmt.strip():- await cur.execute(stmt)await cur.execute(- "SELECT table_name FROM information_schema.tables "+ "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', JSON_OBJECT())"+ )+ await cur.execute(+ "ALTER TABLE cubepi_messages RENAME INDEX "+ "ix_cubepi_messages_thread_run TO ix_cubeloop_messages_thread_run"+ )+ await cur.execute(+ "ALTER TABLE cubepi_runs RENAME INDEX "+ "ix_cubepi_runs_thread_seq TO ix_cubeloop_runs_thread_seq"+ )+ await cur.execute(+ "RENAME TABLE cubepi_threads TO cubeloop_threads, "+ "cubepi_messages TO cubeloop_messages, "+ "cubepi_runs TO cubeloop_runs, "+ "cubepi_hitl_answers TO cubeloop_hitl_answers, "+ "cubepi_schema_version TO cubeloop_schema_version"+ )+ await cur.execute("UPDATE cubeloop_schema_version SET version = 6")+ script = Path(+ "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"+ ).read_text()+ for statement in script.split(";"):+ if statement.strip():+ await cur.execute(statement)+ await cur.execute(+ "SELECT COUNT(*) FROM cubepi_threads WHERE thread_id = 'kept'"+ )+ assert (await cur.fetchone())[0] == 1+ await cur.execute("SELECT version FROM cubepi_schema_version")+ assert (await cur.fetchone())[0] == 5+ await cur.execute(+ "SELECT DISTINCT index_name FROM information_schema.statistics ""WHERE table_schema = DATABASE()")- names = {row[0] for row in await cur.fetchall()}+ index_names = {row[0] for row in await cur.fetchall()}+ assert "ix_cubepi_messages_thread_run" in index_names+ assert "ix_cubepi_runs_thread_seq" in index_names+ assert "ix_cubeloop_messages_thread_run" not in index_namesfinally:await conn.ensure_closed()- assert "cubeloop_threads" in names- assert "cubeloop_schema_version" in names- assert "cubepi_threads" not in names-async with MySQLCheckpointer(clean_mysql_db) as cp:- await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])- data = await cp.load("t-mig")+ await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])+ data = await cp.load("recovered")assert data is not Noneassert len(data.messages) == 1+++async def test_withdrawn_v6_recovery_collision_is_retryable(clean_mysql_db) -> None:+ from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn++ await _setup_schema_v5(clean_mysql_db)+ conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))+ try:+ async with conn.cursor() as cur:+ await cur.execute(+ "RENAME TABLE cubepi_threads TO cubeloop_threads, "+ "cubepi_messages TO cubeloop_messages, "+ "cubepi_runs TO cubeloop_runs, "+ "cubepi_hitl_answers TO cubeloop_hitl_answers, "+ "cubepi_schema_version TO cubeloop_schema_version"+ )+ await cur.execute(+ "CREATE TABLE cubepi_threads (thread_id VARCHAR(255) PRIMARY KEY)"+ )+ script = Path(+ "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"+ ).read_text()+ with pytest.raises(Exception):+ for statement in script.split(";"):+ if statement.strip():+ await cur.execute(statement)+ await cur.execute(+ "SELECT table_name FROM information_schema.tables "+ "WHERE table_schema = DATABASE() AND table_name IN "+ "('cubeloop_threads', 'cubepi_threads')"+ )+ assert {row[0] for row in await cur.fetchall()} == {+ "cubeloop_threads",+ "cubepi_threads",+ }+ await cur.execute("DROP TABLE cubepi_threads")+ for statement in script.split(";"):+ if statement.strip():+ await cur.execute(statement)+ await cur.execute(+ "SELECT COUNT(*) FROM information_schema.routines "+ "WHERE routine_schema = DATABASE() "+ "AND routine_name = 'cubeloop_0140_recovery_preflight'"+ )+ assert (await cur.fetchone())[0] == 0+ finally:+ await conn.ensure_closed()+++async def test_withdrawn_v6_schema_points_to_recovery(clean_mysql_db) -> None:+ from cubeloop.checkpointer.mysql import CubeloopSchemaMismatch, MySQLCheckpointer+ from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn++ conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))+ try:+ async with conn.cursor() as cur:+ await cur.execute(+ "CREATE TABLE cubeloop_schema_version "+ "(version INT PRIMARY KEY) ENGINE=InnoDB"+ )+ await cur.execute("INSERT INTO cubeloop_schema_version VALUES (6)")+ finally:+ await conn.ensure_closed()+ with pytest.raises(CubeloopSchemaMismatch) as exc_info:+ async with MySQLCheckpointer(clean_mysql_db):+ pass+ assert exc_info.value.actual == 6+ assert "withdrawn 0.14.0" in str(exc_info.value)diff --git a/tests/checkpointer/test_mysql_runs.py b/tests/checkpointer/test_mysql_runs.pyindex e9c0a3c..34446a6 100644--- a/tests/checkpointer/test_mysql_runs.py+++ b/tests/checkpointer/test_mysql_runs.py@@ -26,13 +26,13 @@ async def test_claim_run_creates_threads_row_lazily(mysql_v4_dsn) -> None:try:async with conn.cursor() as cur:await cur.execute(- "SELECT thread_id FROM cubeloop_threads WHERE thread_id = %s",+ "SELECT thread_id FROM cubepi_threads WHERE thread_id = %s",("t-lazy",),)row = await cur.fetchone()assert row is not Noneawait cur.execute(- "SELECT completed_at FROM cubeloop_runs "+ "SELECT completed_at FROM cubepi_runs ""WHERE thread_id = %s AND run_id = %s",("t-lazy", "r1"),)@@ -96,7 +96,7 @@ async def test_completion_seq_monotonic_per_thread(mysql_v4_dsn) -> None:try:async with conn.cursor() as cur:await cur.execute(- "SELECT run_id, completion_seq FROM cubeloop_runs "+ "SELECT run_id, completion_seq FROM cubepi_runs ""WHERE thread_id = %s ORDER BY completion_seq",("t",),)@@ -144,7 +144,7 @@ async def test_append_persists_run_id_into_column(mysql_v4_dsn) -> None:try:async with conn.cursor() as cur:await cur.execute(- "SELECT run_id FROM cubeloop_messages WHERE thread_id = %s",+ "SELECT run_id FROM cubepi_messages WHERE thread_id = %s",("t",),)row = await cur.fetchone()diff --git a/tests/checkpointer/test_mysql_schema.py b/tests/checkpointer/test_mysql_schema.pyindex 0da1f96..fb14659 100644--- a/tests/checkpointer/test_mysql_schema.py+++ b/tests/checkpointer/test_mysql_schema.py@@ -6,12 +6,12 @@ import pytestfrom cubeloop.checkpointer.mysql.models import EXPECTED_SCHEMA_VERSION-def test_expected_schema_version_is_6() -> None:- assert EXPECTED_SCHEMA_VERSION == 6+def test_expected_schema_version_is_5() -> None:+ assert EXPECTED_SCHEMA_VERSION == 5@pytest.mark.asyncio-async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:+async def test_cubepi_runs_table_present(mysql_v4_dsn) -> None:from cubeloop.checkpointer.mysql.checkpointer import _parse_dsncfg = _parse_dsn(mysql_v4_dsn)@@ -20,7 +20,7 @@ async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:async with conn.cursor() as cur:await cur.execute("SELECT column_name FROM information_schema.columns "- "WHERE table_schema = %s AND table_name = 'cubeloop_runs'",+ "WHERE table_schema = %s AND table_name = 'cubepi_runs'",(cfg["db"],),)rows = await cur.fetchall()@@ -37,7 +37,7 @@ async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:@pytest.mark.asyncio-async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:+async def test_cubepi_messages_has_run_id_column(mysql_v4_dsn) -> None:from cubeloop.checkpointer.mysql.checkpointer import _parse_dsncfg = _parse_dsn(mysql_v4_dsn)@@ -46,7 +46,7 @@ async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:async with conn.cursor() as cur:await cur.execute("SELECT data_type FROM information_schema.columns "- "WHERE table_schema = %s AND table_name = 'cubeloop_messages' "+ "WHERE table_schema = %s AND table_name = 'cubepi_messages' ""AND column_name = 'run_id'",(cfg["db"],),)@@ -57,7 +57,7 @@ async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:@pytest.mark.asyncio-async def test_cubeloop_hitl_answers_table_present(mysql_v4_dsn) -> None:+async def test_cubepi_hitl_answers_table_present(mysql_v4_dsn) -> None:from cubeloop.checkpointer.mysql.checkpointer import _parse_dsncfg = _parse_dsn(mysql_v4_dsn)@@ -67,7 +67,7 @@ async def test_cubeloop_hitl_answers_table_present(mysql_v4_dsn) -> None:await cur.execute("SELECT column_name FROM information_schema.columns ""WHERE table_schema = %s "- "AND table_name = 'cubeloop_hitl_answers'",+ "AND table_name = 'cubepi_hitl_answers'",(cfg["db"],),)rows = await cur.fetchall()diff --git a/tests/checkpointer/test_postgres.py b/tests/checkpointer/test_postgres.pyindex be02839..23f3bb4 100644--- a/tests/checkpointer/test_postgres.py+++ b/tests/checkpointer/test_postgres.py@@ -3,6 +3,8 @@Full E2E tests are in D1.3 once PostgresCheckpointer is implemented."""+from pathlib import Path+import asyncpgimport pytest@@ -18,23 +20,23 @@ def test_models_import() -> None:cubeloop_metadata,)- assert EXPECTED_SCHEMA_VERSION == 6+ assert EXPECTED_SCHEMA_VERSION == 5assert PARTITION_COUNT == 64- assert CubeloopThread.__tablename__ == "cubeloop_threads"- assert CubeloopMessage.__tablename__ == "cubeloop_messages"- assert CubeloopHitlAnswer.__tablename__ == "cubeloop_hitl_answers"- assert CubeloopSchemaVersion.__tablename__ == "cubeloop_schema_version"- assert "cubeloop_threads" in cubeloop_metadata.tables- assert "cubeloop_messages" in cubeloop_metadata.tables- assert "cubeloop_hitl_answers" in cubeloop_metadata.tables- assert "cubeloop_schema_version" in cubeloop_metadata.tables+ 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.tablesdef 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["cubeloop_messages"]+ msgs = cubeloop_metadata.tables["cubepi_messages"]# SQLAlchemy stores PG partition clause in info or dialect-specific args# Verify via dialect kwargsassert msgs.kwargs.get("postgresql_partition_by") == "HASH (thread_id)"@@ -44,9 +46,9 @@ 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["cubeloop_messages"]+ msgs = cubeloop_metadata.tables["cubepi_messages"]idx_names = [i.name for i in msgs.indexes]- assert "ix_cubeloop_messages_metadata_gin" in idx_names+ assert "ix_cubepi_messages_metadata_gin" in idx_namesdef test_create_message_partitions_op_yields_64_statements() -> None:@@ -55,7 +57,7 @@ def test_create_message_partitions_op_yields_64_statements() -> None:)sql = create_message_partitions_op()- assert sql.count("CREATE TABLE cubeloop_messages_p") == 64+ assert sql.count("CREATE TABLE cubepi_messages_p") == 64assert "modulus 64, remainder 0" in sqlassert "modulus 64, remainder 63" in sql@@ -67,8 +69,8 @@ def test_create_message_partitions_op_partitions_are_zero_padded() -> None:sql = create_message_partitions_op()# Partition names use 2-digit padding so they sort lexicographically- assert "cubeloop_messages_p00 " in sql- assert "cubeloop_messages_p63 " in sql+ assert "cubepi_messages_p00 " in sql+ assert "cubepi_messages_p63 " in sqldef test_write_schema_version_op_includes_expected_version() -> None:@@ -76,7 +78,7 @@ def test_write_schema_version_op_includes_expected_version() -> None:from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSIONsql = write_schema_version_op()- assert "cubeloop_schema_version" in sql+ assert "cubepi_schema_version" in sqlassert "cubepi_schema_version" in sqlassert f"VALUES ({EXPECTED_SCHEMA_VERSION})" in sqlassert "ON CONFLICT" in sql@@ -88,7 +90,7 @@ def test_write_schema_version_op_clears_stale_rows() -> None:from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSIONsql = write_schema_version_op()- assert "DELETE FROM cubeloop_schema_version" in sql+ assert "DELETE FROM cubepi_schema_version" in sqlassert "DELETE FROM cubepi_schema_version" in sqlassert f"WHERE version <> {EXPECTED_SCHEMA_VERSION}" in sqlassert sql.index("DELETE") < sql.index("INSERT")@@ -186,9 +188,9 @@ async def _setup_schema(dsn: str) -> None:conn = await asyncpg.connect(dsn)try:await conn.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY,- parent_thread_id TEXT REFERENCES cubeloop_threads(thread_id),+ parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),forked_at_seq BIGINT,extra JSONB NOT NULL DEFAULT '{}'::jsonb,pending_request JSONB,@@ -198,8 +200,8 @@ async def _setup_schema(dsn: str) -> None:);""")await conn.execute("""- CREATE TABLE cubeloop_messages (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,+ 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,@@ -211,21 +213,21 @@ async def _setup_schema(dsn: str) -> None:""")await conn.execute(create_message_partitions_op())await conn.execute("""- CREATE INDEX ix_cubeloop_messages_metadata_gin- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);+ CREATE INDEX ix_cubepi_messages_metadata_gin+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);""")await conn.execute("""- CREATE INDEX ix_cubeloop_messages_thread_run- ON cubeloop_messages (thread_id, run_id);+ CREATE INDEX ix_cubepi_messages_thread_run+ ON cubepi_messages (thread_id, run_id);""")await conn.execute("""- CREATE TABLE cubeloop_schema_version (+ CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);""")await conn.execute("""- CREATE TABLE cubeloop_runs (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,+ 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,@@ -235,12 +237,12 @@ async def _setup_schema(dsn: str) -> None:""")await conn.execute(create_runs_partitions_op())await conn.execute("""- CREATE INDEX ix_cubeloop_runs_thread_seq- ON cubeloop_runs (thread_id, completion_seq);+ CREATE INDEX ix_cubepi_runs_thread_seq+ ON cubepi_runs (thread_id, completion_seq);""")await conn.execute("""- CREATE TABLE cubeloop_hitl_answers (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,+ 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,@@ -406,7 +408,7 @@ async def test_version_mismatch_raises(clean_db) -> None:await _setup_schema(clean_db)conn = await asyncpg.connect(clean_db)try:- await conn.execute("UPDATE cubeloop_schema_version SET version = 999")+ await conn.execute("UPDATE cubepi_schema_version SET version = 999")finally:await conn.close()@@ -450,9 +452,9 @@ async def test_postgres_load_corrupt_row_raises_typed(clean_db) -> None:conn = await asyncpg.connect(clean_db)try:await conn.execute(- "UPDATE cubeloop_messages SET payload = $1 "+ "UPDATE cubepi_messages SET payload = $1 ""WHERE thread_id = 't-corrupt' AND seq = ("- " SELECT max(seq) FROM cubeloop_messages "+ " SELECT max(seq) FROM cubepi_messages "" WHERE thread_id = 't-corrupt')",b"\xc1 not msgpack",)@@ -465,7 +467,7 @@ async def test_postgres_load_corrupt_row_raises_typed(clean_db) -> None:err = excinfo.valueassert err.thread_id == "t-corrupt"assert err.backend == "postgres"- assert err.row_ref.startswith("cubeloop_messages.seq=")+ assert err.row_ref.startswith("cubepi_messages.seq=")assert err.__cause__ is not None@@ -481,7 +483,7 @@ async def test_postgres_load_unknown_role_raises_typed(clean_db) -> None:conn = await asyncpg.connect(clean_db)try:await conn.execute(- "UPDATE cubeloop_messages SET role = 'alien' WHERE thread_id = 't-role'"+ "UPDATE cubepi_messages SET role = 'alien' WHERE thread_id = 't-role'")finally:await conn.close()@@ -494,60 +496,114 @@ async def test_postgres_load_unknown_role_raises_typed(clean_db) -> None:@pytest.mark.asyncio-async def test_unmigrated_v5_raises_mismatch_not_uninitialized(clean_db) -> None:- from cubeloop.checkpointer.postgres import (- CubeloopSchemaMismatch,- PostgresCheckpointer,- )+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, UserMessageawait _setup_schema_v5(clean_db)- with pytest.raises(CubeloopSchemaMismatch) as ei:- async with PostgresCheckpointer(clean_db):- pass- assert ei.value.expected == 6- assert ei.value.actual == 5- assert "upgrade_v5_to_v6_op" in str(ei.value)+ 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_v5_to_v6_rename_then_round_trip(clean_db) -> None:- from cubeloop.checkpointer.postgres.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,- )+async def test_withdrawn_v6_recovery_script_round_trip(clean_db) -> None:from cubeloop.checkpointer.postgres import PostgresCheckpointerfrom cubeloop.providers.base import TextContent, UserMessageawait _setup_schema_v5(clean_db)conn = await asyncpg.connect(clean_db)try:- await conn.execute(upgrade_v5_to_v6_op())- await conn.execute(write_schema_version_op())- # Idempotent on complete v6.- await conn.execute(upgrade_v5_to_v6_op())- names = {- r["table_name"]- for r in await conn.fetch(- "SELECT table_name FROM information_schema.tables "- "WHERE table_schema = 'public'"+ await conn.execute(+ "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', '{}')"+ )+ await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")+ await conn.execute("ALTER TABLE cubepi_messages RENAME TO cubeloop_messages")+ for i in range(64):+ await conn.execute(+ f"ALTER TABLE cubepi_messages_p{i:02d} "+ f"RENAME TO cubeloop_messages_p{i:02d}"+ )+ await conn.execute("ALTER TABLE cubepi_runs RENAME TO cubeloop_runs")+ for i in range(64):+ await conn.execute(+ f"ALTER TABLE cubepi_runs_p{i:02d} RENAME TO cubeloop_runs_p{i:02d}"+ )+ await conn.execute(+ "ALTER TABLE cubepi_hitl_answers RENAME TO cubeloop_hitl_answers"+ )+ await conn.execute(+ "ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version"+ )+ await conn.execute(+ "ALTER INDEX ix_cubepi_messages_metadata_gin "+ "RENAME TO ix_cubeloop_messages_metadata_gin"+ )+ await conn.execute(+ "ALTER INDEX ix_cubepi_messages_thread_run "+ "RENAME TO ix_cubeloop_messages_thread_run"+ )+ await conn.execute(+ "ALTER INDEX ix_cubepi_runs_thread_seq "+ "RENAME TO ix_cubeloop_runs_thread_seq"+ )+ await conn.execute("UPDATE cubeloop_schema_version SET version = 6")+ await conn.execute(+ Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()+ )+ assert (+ await conn.fetchval(+ "SELECT count(*) FROM cubepi_threads WHERE thread_id = 'kept'"+ )+ == 1+ )+ assert await conn.fetchval("SELECT version FROM cubepi_schema_version") == 5+ assert (+ await conn.fetchval(+ "SELECT count(*) FROM pg_inherits i "+ "JOIN pg_class p ON p.oid = i.inhparent "+ "WHERE p.relname IN ('cubepi_messages', 'cubepi_runs')"+ )+ == 128+ )+ index_names = {+ row["indexname"]+ for row in await conn.fetch(+ "SELECT indexname FROM pg_indexes WHERE schemaname = current_schema()")}- assert "cubeloop_threads" in names- assert "cubeloop_messages" in names- assert "cubeloop_runs" in names- assert "cubeloop_hitl_answers" in names- assert "cubeloop_schema_version" in names- assert "cubepi_threads" not in names+ assert "ix_cubepi_messages_thread_run" in index_names+ assert "ix_cubepi_runs_thread_seq" in index_namesfinally:await conn.close()async with PostgresCheckpointer(clean_db) as cp:- await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])- data = await cp.load("t-mig")+ await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])+ data = await cp.load("recovered")assert data is not Noneassert len(data.messages) == 1+async def test_withdrawn_v6_recovery_collision_is_atomic(clean_db) -> None:+ await _setup_schema_v5(clean_db)+ conn = await asyncpg.connect(clean_db)+ try:+ await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")+ await conn.execute("CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY)")+ with pytest.raises(asyncpg.PostgresError):+ await conn.execute(+ Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()+ )+ await conn.execute("ROLLBACK")+ assert await conn.fetchval("SELECT to_regclass('cubeloop_threads')")+ assert await conn.fetchval("SELECT to_regclass('cubepi_threads')")+ finally:+ await conn.close()++@pytest.mark.asyncioasync def test_data_tables_without_version_table_are_not_uninitialized(clean_db,@@ -573,3 +629,30 @@ async def test_data_tables_without_version_table_are_not_uninitialized(passassert "Uninitialized" not in type(ei.value).__name__assert not isinstance(ei.value, CubeloopSchemaUninitialized)++[email protected]("stored_version", [5, 6])+async def test_withdrawn_v6_schema_points_to_recovery(+ clean_db, stored_version: int+) -> None:+ from cubeloop.checkpointer.postgres import (+ CubeloopSchemaMismatch,+ PostgresCheckpointer,+ )++ conn = await asyncpg.connect(clean_db)+ try:+ await conn.execute(+ "CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY)"+ )+ await conn.execute(+ "INSERT INTO cubeloop_schema_version VALUES ($1)", stored_version+ )+ finally:+ await conn.close()+ with pytest.raises(CubeloopSchemaMismatch) as exc_info:+ async with PostgresCheckpointer(clean_db):+ pass+ assert exc_info.value.actual == stored_version+ assert "withdrawn 0.14.0" in str(exc_info.value)diff --git a/tests/checkpointer/test_postgres_runs.py b/tests/checkpointer/test_postgres_runs.pyindex 2071d01..4279fa2 100644--- a/tests/checkpointer/test_postgres_runs.py+++ b/tests/checkpointer/test_postgres_runs.py@@ -19,12 +19,12 @@ async def test_claim_run_creates_threads_row_lazily(pg_v4_dsn):conn = await asyncpg.connect(pg_v4_dsn)try:row = await conn.fetchrow(- "SELECT thread_id FROM cubeloop_threads WHERE thread_id = $1",+ "SELECT thread_id FROM cubepi_threads WHERE thread_id = $1","t-lazy",)assert row is not Nonerun = await conn.fetchrow(- "SELECT completed_at FROM cubeloop_runs WHERE thread_id = $1 AND run_id = $2",+ "SELECT completed_at FROM cubepi_runs WHERE thread_id = $1 AND run_id = $2","t-lazy","r1",)@@ -86,7 +86,7 @@ async def test_completion_seq_monotonic_per_thread(pg_v4_dsn):conn = await asyncpg.connect(pg_v4_dsn)try:rows = await conn.fetch(- "SELECT run_id, completion_seq FROM cubeloop_runs "+ "SELECT run_id, completion_seq FROM cubepi_runs ""WHERE thread_id = $1 ORDER BY completion_seq","t",)@@ -132,7 +132,7 @@ async def test_append_persists_run_id_into_column(pg_v4_dsn):conn = await asyncpg.connect(pg_v4_dsn)try:row = await conn.fetchrow(- "SELECT run_id FROM cubeloop_messages WHERE thread_id = $1",+ "SELECT run_id FROM cubepi_messages WHERE thread_id = $1","t",)assert row is not Nonediff --git a/tests/checkpointer/test_postgres_schema.py b/tests/checkpointer/test_postgres_schema.pyindex 9a5f454..69d54f4 100644--- a/tests/checkpointer/test_postgres_schema.py+++ b/tests/checkpointer/test_postgres_schema.py@@ -5,21 +5,20 @@ from cubeloop.checkpointer.postgres.checkpointer import _schema_mismatch_hintfrom cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION-def test_expected_schema_version_is_6():- assert EXPECTED_SCHEMA_VERSION == 6---def test_schema_mismatch_hint_names_the_v5_to_v6_helper():- hint = _schema_mismatch_hint(actual=5, expected=6)- assert "upgrade_v5_to_v6_op()" in hint- assert "add_run_id_column_op" not in hint+def test_expected_schema_version_is_5():+ assert EXPECTED_SCHEMA_VERSION == 5def test_schema_mismatch_hint_names_every_step_across_multiple_versions():- hint = _schema_mismatch_hint(actual=3, expected=6)+ hint = _schema_mismatch_hint(actual=3, expected=5)assert "upgrade_v3_to_v4_op()" in hintassert "upgrade_v4_to_v5_op()" in hint- assert "upgrade_v5_to_v6_op()" in hint+++def test_newer_schema_hint_points_to_withdrawn_release_recovery():+ hint = _schema_mismatch_hint(actual=6, expected=5)+ assert "withdrawn 0.14.0" in hint+ assert "call +" not in hint@pytest.mark.asyncio@@ -28,7 +27,7 @@ async def test_cubepi_runs_table_present(pg_v4_dsn):try:rows = await conn.fetch("SELECT column_name FROM information_schema.columns "- "WHERE table_name = 'cubeloop_runs'"+ "WHERE table_name = 'cubepi_runs'")cols = {r["column_name"] for r in rows}assert {@@ -48,7 +47,7 @@ async def test_cubepi_messages_has_run_id_column(pg_v4_dsn):try:row = await conn.fetchrow("SELECT data_type FROM information_schema.columns "- "WHERE table_name = 'cubeloop_messages' AND column_name = 'run_id'"+ "WHERE table_name = 'cubepi_messages' AND column_name = 'run_id'")assert row is not Nonefinally:@@ -61,7 +60,7 @@ async def test_cubepi_hitl_answers_table_present(pg_v4_dsn):try:rows = await conn.fetch("SELECT column_name FROM information_schema.columns "- "WHERE table_name = 'cubeloop_hitl_answers'"+ "WHERE table_name = 'cubepi_hitl_answers'")cols = {r["column_name"] for r in rows}assert {diff --git a/tests/checkpointer/test_save_pending_request_run_id.py b/tests/checkpointer/test_save_pending_request_run_id.pyindex bf9af8a..c6c8e24 100644--- a/tests/checkpointer/test_save_pending_request_run_id.py+++ b/tests/checkpointer/test_save_pending_request_run_id.py@@ -145,9 +145,9 @@ async def _setup_pg_schema_v3(dsn: str) -> None:conn = await asyncpg.connect(dsn)try:await conn.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY,- parent_thread_id TEXT NULL REFERENCES cubeloop_threads(thread_id),+ parent_thread_id TEXT NULL REFERENCES cubepi_threads(thread_id),forked_at_seq BIGINT NULL,extra JSONB NOT NULL DEFAULT '{}'::jsonb,pending_request JSONB,@@ -157,8 +157,8 @@ async def _setup_pg_schema_v3(dsn: str) -> None:);""")await conn.execute("""- CREATE TABLE cubeloop_messages (- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,+ 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,@@ -169,11 +169,11 @@ async def _setup_pg_schema_v3(dsn: str) -> None:""")await conn.execute(create_message_partitions_op())await conn.execute("""- CREATE INDEX ix_cubeloop_messages_metadata_gin- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);+ CREATE INDEX ix_cubepi_messages_metadata_gin+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);""")await conn.execute("""- CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY);+ CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);""")await conn.execute(write_schema_version_op())finally:@@ -238,7 +238,7 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:try:async with conn.cursor() as cur:await cur.execute("""- CREATE TABLE cubeloop_threads (+ CREATE TABLE cubepi_threads (thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,forked_at_seq BIGINT NULL,@@ -249,12 +249,12 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMPON UPDATE CURRENT_TIMESTAMP,CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)- REFERENCES cubeloop_threads (thread_id)+ REFERENCES cubepi_threads (thread_id)) ENGINE=InnoDB""")await cur.execute("""- CREATE TABLE cubeloop_messages (+ CREATE TABLE cubepi_messages (thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,seq BIGINT NOT NULL,role VARCHAR(32) NOT NULL,@@ -266,7 +266,7 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:+ messages_partition_clause())await cur.execute("""- CREATE TABLE cubeloop_schema_version (+ CREATE TABLE cubepi_schema_version (version INT PRIMARY KEY) ENGINE=InnoDB""")diff --git a/uv.lock b/uv.lockindex b3a51a8..618f90e 100644--- a/uv.lock+++ b/uv.lock@@ -528,7 +528,7 @@ wheels = [[[package]]name = "cubeloop"-version = "0.14.0"+version = "0.14.1"source = { editable = "." }dependencies = [{ name = "anthropic" },@@ -624,7 +624,7 @@ dev = [[[package]]name = "cubepi"-version = "0.14.0"+version = "0.14.1"source = { editable = "compat/cubepi" }dependencies = [{ name = "cubeloop" },diff --git a/website/docs/guides/checkpointing/mysql.md b/website/docs/guides/checkpointing/mysql.mdindex e636840..29e3b49 100644--- a/website/docs/guides/checkpointing/mysql.md+++ b/website/docs/guides/checkpointing/mysql.md@@ -61,8 +61,8 @@ async with MySQLCheckpointer(## Schema-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`. Like+The checkpointer expects `cubepi_threads`, `cubepi_messages`,+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`. LikePostgres (and unlike SQLite), CubeLoop **does not create these for you** —it verifies on `__aenter__` that they exist with the expected`schema_version`.@@ -90,7 +90,7 @@ Then autogenerate a revision:alembic revision --autogenerate -m "add cubeloop checkpointer"```-The `cubeloop_messages` table is `KEY`-partitioned, which SQLAlchemy's+The `cubepi_messages` table is `KEY`-partitioned, which SQLAlchemy'sautogenerate cannot express, so append the partition clause and theschema-version write with the provided helpers:@@ -102,16 +102,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import ()def upgrade():- op.create_table("cubeloop_threads", ...)+ op.create_table("cubepi_threads", ...)op.create_table(- "cubeloop_messages", ...,+ "cubepi_messages", ...,mysql_engine="InnoDB",)# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:op.execute(- "ALTER TABLE cubeloop_messages " + messages_partition_clause()+ "ALTER TABLE cubepi_messages " + messages_partition_clause())- op.create_table("cubeloop_schema_version", ...)+ op.create_table("cubepi_schema_version", ...)# write_schema_version_op() returns two ';'-separated statements# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,# so split and execute each:@@ -128,31 +128,31 @@ again.## Data model```-cubeloop_threads+cubepi_threadsthread_id (PK) -- VARCHAR(255) utf8mb4_bin (case-sensitive)parent_thread_id -- self-FK, for forksforked_at_seq -- seq number at fork pointextra -- JSONcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- composite PK; partitioned by KEY(thread_id) into 64role -- "user" | "assistant" | "tool"metadata -- JSON (not indexed; see below)payload -- LONGBLOB (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- composite PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- composite PKanswer -- JSONanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -199,8 +199,8 @@ from `dict.update`.)`MySQLCheckpointer` implements the v4 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The-`parent_thread_id` / `forked_at_seq` columns on `cubeloop_threads`-record fork lineage; `cubeloop_runs` (added in v4) tracks per-run+`parent_thread_id` / `forked_at_seq` columns on `cubepi_threads`+record fork lineage; `cubepi_runs` (added in v4) tracks per-runclaim/completion state.See the [Conversation Forking](../agents/forking) guide for the user-facing@@ -258,34 +258,17 @@ def upgrade():op.execute(stmt)```-## Schema v5 → v6 migration+## CubeLoop rename-0.14 renames the MySQL tables from `cubepi_*` to `cubeloop_*`.-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14-checkpointer on an existing database:--```python-from cubeloop.checkpointer.mysql.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- op.execute(stmt)- for stmt in write_schema_version_op().split(";"):- if stmt.strip():- op.execute(stmt)-```--Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the-[migration guide](../../migration/from-cubepi).+The package rename does not change the persistence schema: physical names stay+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need+no migration. See the [migration guide](../../migration/from-cubepi), including+the exceptional recovery path for withdrawn 0.14.0.## Common pitfalls- **`CubeloopSchemaUninitialized`** — Your DB is empty, your migrations- didn't run, or the `cubeloop_schema_version` table is malformed. Apply+ didn't run, or the `cubepi_schema_version` table is malformed. Applythe host alembic upgrade first.- **`CubeloopSchemaMismatch`** — You upgraded CubeLoop but didn't generate anew migration. Generate one, apply it, and CubeLoop will start.@@ -296,7 +279,7 @@ Do not run the v6 `CREATE TABLE` helpers against a v5 database. See thehand-roll the DDL, keep that collation.- **`CheckpointCorruptionError` on `load()`** — A persisted message rowfailed to deserialize (bad msgpack payload, schema-invalid data, or an- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)locates the bad row for inspection or surgical repair; `thread_id` and`__cause__` carry the rest. CubeLoop never skips corrupt rows silently.diff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.mdindex 9cfc204..938a20b 100644--- a/website/docs/guides/checkpointing/postgres.md+++ b/website/docs/guides/checkpointing/postgres.md@@ -54,8 +54,8 @@ async with PostgresCheckpointer(## Schema-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`.+The checkpointer expects `cubepi_threads`, `cubepi_messages`,+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`.Unlike SQLite, CubeLoop**does not create these for you** — it verifies on `__aenter__` thatthey exist with the expected `schema_version`.@@ -89,9 +89,9 @@ alembic revision --autogenerate -m "add cubeloop checkpointer"Autogenerate emits the `CREATE TABLE`s from `cubeloop_metadata`, butSQLAlchemy `MetaData` **cannot model two things CubeLoop needs**, so addthem to the generated migration by hand: the 64 hash partitions of-`cubeloop_messages` (via `create_message_partitions_op()`), the 64-partitions of `cubeloop_runs` (via `create_runs_partitions_op()`), and-the `cubeloop_schema_version` row (via `write_schema_version_op()`). Use+`cubepi_messages` (via `create_message_partitions_op()`), the 64+partitions of `cubepi_runs` (via `create_runs_partitions_op()`), and+the `cubepi_schema_version` row (via `write_schema_version_op()`). Usethe helpers:```python@@ -104,8 +104,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (def upgrade():op.create_table(...) # auto-generated from cubeloop_metadata- op.execute(create_message_partitions_op()) # 64 hash partitions of cubeloop_messages- op.execute(create_runs_partitions_op()) # 64 hash partitions of cubeloop_runs+ op.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messages+ op.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runsop.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION```@@ -120,31 +120,31 @@ again.## Data model```-cubeloop_threads+cubepi_threadsthread_id (PK)parent_thread_id -- for forksforked_at_seq -- seq number at fork pointextra -- JSONBcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- composite PK; partitioned by HASH(thread_id) into 64role -- "user" | "assistant" | "tool"metadata -- JSONB (indexed via GIN)payload -- bytea (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- composite PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- composite PKanswer -- JSONBanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -182,7 +182,7 @@ The pool default of `min=1, max=10` is fine for most apps; bump`save_extra` does a JSONB merge, not a replace:```sql-extra = cubeloop_threads.extra || EXCLUDED.extra+extra = cubepi_threads.extra || EXCLUDED.extra```So writing `{"foo": 1}` then `{"bar": 2}` leaves `{"foo": 1, "bar":@@ -194,8 +194,8 @@ keys.`PostgresCheckpointer` implements the v4 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The-`parent_thread_id` and `forked_at_seq` columns on `cubeloop_threads`-record fork lineage; `cubeloop_runs` (the v4 partitioned table) tracks+`parent_thread_id` and `forked_at_seq` columns on `cubepi_threads`+record fork lineage; `cubepi_runs` (the v4 partitioned table) tracksper-run claim/completion state.See the [Conversation Forking](../agents/forking) guide for the user-facing@@ -246,26 +246,12 @@ def upgrade():op.execute(write_schema_version_op()) # bumps cubepi_schema_version to 5```-## Schema v5 → v6 migration+## CubeLoop rename-0.14 renames the Postgres tables from `cubepi_*` to `cubeloop_*`.-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14-checkpointer on an existing database:--```python-from cubeloop.checkpointer.postgres.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- op.execute(upgrade_v5_to_v6_op())- op.execute(write_schema_version_op()) # writes 6 into cubeloop_schema_version-```--Do not run the v6 `CREATE TABLE` helpers against a v5 database — they-would try to create tables that already exist under the old names.-See the [migration guide](../../migration/from-cubepi).+The package rename does not change the persistence schema: physical names stay+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need+no migration. See the [migration guide](../../migration/from-cubepi), including+the exceptional recovery path for withdrawn 0.14.0.## Common pitfalls@@ -295,7 +281,7 @@ See the [migration guide](../../migration/from-cubepi).— pass both to Alembic separately.- **`CheckpointCorruptionError` on `load()`** — A persisted message rowfailed to deserialize (bad msgpack payload, schema-invalid data, or an- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)locates the bad row for inspection or surgical repair; `thread_id` and`__cause__` carry the rest. CubeLoop never skips corrupt rows silently —dropping a message that carries `tool_calls` would leave thediff --git a/website/docs/migration/from-cubepi.md b/website/docs/migration/from-cubepi.mdindex 327a545..e201c52 100644--- a/website/docs/migration/from-cubepi.md+++ b/website/docs/migration/from-cubepi.md@@ -21,25 +21,37 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.+`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a+compatible CubeLoop 0.14 release, re-exports the public API, and aliases+`cubepi.*` imports.It warns on first import. Prefer depending on `cubeloop` directly.CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).-## Checkpointer schema v5 → v6+## Checkpointer schema stays at v5-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.+Postgres and MySQL keep their `cubepi_*` physical table and index names. They+are persistent protocol identifiers, not product branding. Schema version 5 is+unchanged, so an existing 0.13.6 database needs no migration for 0.14.1.SQLite table names were never prefixed; they stay `messages` / `runs` / ….-Existing databases: add an Alembic revision that runs-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that-helper — not “tables not found”.+Historical host Alembic revisions may import helpers from+`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their original+v1–v5 SQL. Do not add a rename revision.-If you have data tables but no `*_schema_version` table, do not apply the-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,-then run the v5→v6 helper.+### Emergency recovery from withdrawn 0.14.0++0.14.0 was yanked because it briefly renamed these database objects to+`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn+migration. Stop every application instance, take a verified backup, then run+the script for your database with an administrative SQL client:++- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)+- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)++The scripts refuse mixed/colliding schemas before renaming anything. Afterward,+verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5+database.## Tracingdiff --git a/website/docs/recipes/postgres-fastapi.md b/website/docs/recipes/postgres-fastapi.mdindex ff26ae5..7450637 100644--- a/website/docs/recipes/postgres-fastapi.md+++ b/website/docs/recipes/postgres-fastapi.md@@ -20,13 +20,13 @@ Before the service starts, run the CubeLoop schema migration. Thequickest way for this recipe:```bash-# Throwaway / recipe: copy the v6 bootstrap from-# examples/checkpointing_postgres.py (cubeloop_threads, cubeloop_messages +-# 64 partitions, cubeloop_runs + 64 partitions, cubeloop_hitl_answers,-# cubeloop_schema_version = 6).+# Throwaway / recipe: copy the v5 bootstrap from+# examples/checkpointing_postgres.py (cubepi_threads, cubepi_messages ++# 64 partitions, cubepi_runs + 64 partitions, cubepi_hitl_answers,+# cubepi_schema_version = 5).```-Existing v5 databases must run `upgrade_v5_to_v6_op()` instead of CREATE.+Existing v5 databases need no migration for the CubeLoop package rename.For a real deployment, generate this via Alembic — see[Postgres Checkpointing → Bootstrapping via Alembic](../guides/checkpointing/postgres#bootstrapping-via-alembic).diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.mdindex fab1637..33323fd 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md@@ -53,7 +53,7 @@ async with MySQLCheckpointer(## Schema-Checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。+Checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。若表不存在,会抛出 `CubeloopSchemaUninitialized`;若版本与当前 CubeLoop 版本不匹配,会抛出 `CubeloopSchemaMismatch`。生产数据库应由宿主应用的迁移系统(Alembic 等)管理,而非由第三方库管理。@@ -74,7 +74,7 @@ target_metadata = [my_app_metadata, cubeloop_metadata]alembic revision --autogenerate -m "add cubeloop checkpointer"```-`cubeloop_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:+`cubepi_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:```python# In a migration's upgrade():@@ -84,16 +84,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import ()def upgrade():- op.create_table("cubeloop_threads", ...)+ op.create_table("cubepi_threads", ...)op.create_table(- "cubeloop_messages", ...,+ "cubepi_messages", ...,mysql_engine="InnoDB",)# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:op.execute(- "ALTER TABLE cubeloop_messages " + messages_partition_clause()+ "ALTER TABLE cubepi_messages " + messages_partition_clause())- op.create_table("cubeloop_schema_version", ...)+ op.create_table("cubepi_schema_version", ...)# write_schema_version_op() returns two ';'-separated statements# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,# so split and execute each:@@ -152,8 +152,8 @@ cubepi_schema_version`MySQLCheckpointer` 实现了 v4 的 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` 协议方法,因此同时支持 `Agent.fork(...)` 和 `Agent.fork_once(...)`。-`cubeloop_threads` 上的 `parent_thread_id` / `forked_at_seq` 列-用于记录 fork 谱系;v4 新增的 `cubeloop_runs` 表用于追踪每个 run+`cubepi_threads` 上的 `parent_thread_id` / `forked_at_seq` 列+用于记录 fork 谱系;v4 新增的 `cubepi_runs` 表用于追踪每个 run的 claim/completion 状态。用户层 API 与语义详见@@ -186,28 +186,9 @@ def upgrade():保留 `run_id = NULL`,仍然可读;关于混合数据的 fork 资格规则,请参阅 [旧数据行为](../agents/forking#legacy-data-behaviour)。-## Schema v5 → v6 migration+## CubeLoop 更名-0.14 把 MySQL 表从 `cubepi_*` 重命名为 `cubeloop_*`。-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:--```python-from cubeloop.checkpointer.mysql.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- op.execute(stmt)- for stmt in write_schema_version_op().split(";"):- if stmt.strip():- op.execute(stmt)-```--不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper。详见-[从 cubepi 迁移](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。## 常见陷阱diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.mdindex 79dacfb..5b1e129 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md@@ -53,8 +53,8 @@ async with PostgresCheckpointer(## Schema-checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、-`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。+checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、+`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 SQLite 不同,CubeLoop **不会自动创建这些表**——它只在 `__aenter__` 时验证它们是否存在且 `schema_version` 是否匹配预期。@@ -75,7 +75,7 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VEtarget_metadata = [my_app_metadata, cubeloop_metadata]```-然后生成一个 revision 并执行。迁移还必须写入 `cubeloop_schema_version`。+然后生成一个 revision 并执行。迁移还必须写入 `cubepi_schema_version`。使用辅助函数:```python@@ -88,8 +88,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (def upgrade():op.create_table(...) # 从 cubeloop_metadata 自动生成- op.execute(create_message_partitions_op()) # cubeloop_messages 的 64 个哈希分区- op.execute(create_runs_partitions_op()) # cubeloop_runs 的 64 个哈希分区+ op.execute(create_message_partitions_op()) # cubepi_messages 的 64 个哈希分区+ op.execute(create_runs_partitions_op()) # cubepi_runs 的 64 个哈希分区op.execute(write_schema_version_op()) # 记录 EXPECTED_SCHEMA_VERSION```@@ -103,31 +103,31 @@ revision,再次调用 `op.execute(write_schema_version_op())`。## 数据模型```-cubeloop_threads+cubepi_threadsthread_id (PK)parent_thread_id -- 用于 forkforked_at_seq -- fork 点处的序列号extra -- JSONBcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- 复合 PK;按 HASH(thread_id) 分为 64 个分区role -- "user" | "assistant" | "tool"metadata -- JSONB(通过 GIN 索引)payload -- bytea (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- 复合 PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- 复合 PKanswer -- JSONBanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -162,7 +162,7 @@ advisory lock 让同一线程上的追加操作跨进程安全:`save_extra` 做的是 JSONB 合并,而不是替换:```sql-extra = cubeloop_threads.extra || EXCLUDED.extra+extra = cubepi_threads.extra || EXCLUDED.extra```所以先写 `{"foo": 1}` 再写 `{"bar": 2}` 会得到 `{"foo": 1, "bar": 2}`。@@ -172,7 +172,7 @@ extra = cubeloop_threads.extra || EXCLUDED.extra`parent_thread_id` + `forked_at_seq` 列用于支持[会话 Fork](../agents/forking):fork 会创建一个新的 thread,并在其-`cubeloop_threads` 行中写入指向源 thread 的 `parent_thread_id`,+`cubepi_threads` 行中写入指向源 thread 的 `parent_thread_id`,以及拷贝时源 thread 末尾的 `forked_at_seq`(最后一条已拷贝消息的`seq`)。@@ -201,24 +201,9 @@ def upgrade():关于混合数据的 fork 资格规则,请参阅[旧数据行为](../agents/forking#legacy-data-behaviour)。-## Schema v5 → v6 migration+## CubeLoop 更名-0.14 把 Postgres 表从 `cubepi_*` 重命名为 `cubeloop_*`。-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:--```python-from cubeloop.checkpointer.postgres.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- op.execute(upgrade_v5_to_v6_op())- op.execute(write_schema_version_op()) # 把 6 写入 cubeloop_schema_version-```--不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper——旧表已经在,只是名字还是 `cubepi_*`。-详见 [从 cubepi 迁移](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。## 常见坑diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.mdindex 327a545..e2da14e 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md@@ -1,19 +1,18 @@----title: From cubepi-description: "CubePi was renamed to CubeLoop in 0.14. How to update installs, imports, checkpointer schema, and traces."+title: 从 cubepi 迁移+description: "CubePi 在 0.14 更名为 CubeLoop;安装、导入、持久化和 trace 的迁移方法。"----# Migrating from cubepi+# 从 cubepi 迁移-0.14 renames the project from CubePi / `cubepi` to CubeLoop / `cubeloop`.-GitHub keeps the same repository (renamed in place to `cubeplexai/cubeloop`).-The docs site is https://cubeloop.dev.+0.14 将项目从 CubePi / `cubepi` 更名为 CubeLoop / `cubeloop`。GitHub 仓库+原地更名为 `cubeplexai/cubeloop`,文档站为 https://cubeloop.dev。-## Install and imports+## 安装与导入```bashpip install cubeloop-# extras are unchanged: cubeloop[sqlite], cubeloop[postgres], cubeloop[mysql], …+# extras 不变:cubeloop[sqlite]、cubeloop[postgres]、cubeloop[mysql]、…``````python@@ -21,36 +20,41 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.-It warns on first import. Prefer depending on `cubeloop` directly.+`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的+CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,+新项目应直接依赖 `cubeloop`。-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).+CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。-## Checkpointer schema v5 → v6+## Checkpointer schema 保持 v5-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.-SQLite table names were never prefixed; they stay `messages` / `runs` / ….+Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*`。这些名字属于+持久化协议,不是产品品牌。schema version 保持 5,因此已有 0.13.6 数据库升级到+0.14.1 不需要数据库迁移。SQLite 表名从未加品牌前缀,保持不变。-Existing databases: add an Alembic revision that runs-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that-helper — not “tables not found”.+历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`+导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-If you have data tables but no `*_schema_version` table, do not apply the-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,-then run the v5→v6 helper.+### 从已撤回的 0.14.0 紧急恢复-## Tracing+0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过+那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用+数据库管理客户端执行对应脚本:++- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)+- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)-New spans use `cubeloop.*` attributes and `cubeloop.turn` span names.-`cubeloop trace` still reads 0.13 JSONL that used `cubepi.*`.-Dashboards you own need their own attribute-name update.+脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。+正常 v5 数据库不要执行这些脚本。++## Tracing-Default JSONL directory is `./cubeloop-traces`.+新 span 使用 `cubeloop.*` 属性和 `cubeloop.turn` span 名。`cubeloop trace` 仍能读取+0.13 中使用 `cubepi.*` 的 JSONL;你自己的 dashboard 需要更新属性名。默认 JSONL+目录为 `./cubeloop-traces`。-## Environment variables+## 环境变量-`CUBELOOP_TEST_PG_DSN`, `CUBELOOP_TEST_MYSQL_DSN`, `CUBELOOP_PG_DSN`,-`CUBELOOP_MYSQL_DSN` replace the `CUBEPI_*` names. The old names are still-read if the new one is unset, for the rest of 0.x.+`CUBELOOP_TEST_PG_DSN`、`CUBELOOP_TEST_MYSQL_DSN`、`CUBELOOP_PG_DSN`、+`CUBELOOP_MYSQL_DSN` 替换对应的 `CUBEPI_*` 名称。新名称未设置时,0.x 的剩余+周期仍会读取旧名称。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.mdindex fab1637..33323fd 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md@@ -53,7 +53,7 @@ async with MySQLCheckpointer(## Schema-Checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。+Checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。若表不存在,会抛出 `CubeloopSchemaUninitialized`;若版本与当前 CubeLoop 版本不匹配,会抛出 `CubeloopSchemaMismatch`。生产数据库应由宿主应用的迁移系统(Alembic 等)管理,而非由第三方库管理。@@ -74,7 +74,7 @@ target_metadata = [my_app_metadata, cubeloop_metadata]alembic revision --autogenerate -m "add cubeloop checkpointer"```-`cubeloop_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:+`cubepi_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:```python# In a migration's upgrade():@@ -84,16 +84,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import ()def upgrade():- op.create_table("cubeloop_threads", ...)+ op.create_table("cubepi_threads", ...)op.create_table(- "cubeloop_messages", ...,+ "cubepi_messages", ...,mysql_engine="InnoDB",)# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:op.execute(- "ALTER TABLE cubeloop_messages " + messages_partition_clause()+ "ALTER TABLE cubepi_messages " + messages_partition_clause())- op.create_table("cubeloop_schema_version", ...)+ op.create_table("cubepi_schema_version", ...)# write_schema_version_op() returns two ';'-separated statements# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,# so split and execute each:@@ -152,8 +152,8 @@ cubepi_schema_version`MySQLCheckpointer` 实现了 v4 的 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` 协议方法,因此同时支持 `Agent.fork(...)` 和 `Agent.fork_once(...)`。-`cubeloop_threads` 上的 `parent_thread_id` / `forked_at_seq` 列-用于记录 fork 谱系;v4 新增的 `cubeloop_runs` 表用于追踪每个 run+`cubepi_threads` 上的 `parent_thread_id` / `forked_at_seq` 列+用于记录 fork 谱系;v4 新增的 `cubepi_runs` 表用于追踪每个 run的 claim/completion 状态。用户层 API 与语义详见@@ -186,28 +186,9 @@ def upgrade():保留 `run_id = NULL`,仍然可读;关于混合数据的 fork 资格规则,请参阅 [旧数据行为](../agents/forking#legacy-data-behaviour)。-## Schema v5 → v6 migration+## CubeLoop 更名-0.14 把 MySQL 表从 `cubepi_*` 重命名为 `cubeloop_*`。-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:--```python-from cubeloop.checkpointer.mysql.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- op.execute(stmt)- for stmt in write_schema_version_op().split(";"):- if stmt.strip():- op.execute(stmt)-```--不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper。详见-[从 cubepi 迁移](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。## 常见陷阱diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.mdindex 79dacfb..5b1e129 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md@@ -53,8 +53,8 @@ async with PostgresCheckpointer(## Schema-checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、-`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。+checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、+`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 SQLite 不同,CubeLoop **不会自动创建这些表**——它只在 `__aenter__` 时验证它们是否存在且 `schema_version` 是否匹配预期。@@ -75,7 +75,7 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VEtarget_metadata = [my_app_metadata, cubeloop_metadata]```-然后生成一个 revision 并执行。迁移还必须写入 `cubeloop_schema_version`。+然后生成一个 revision 并执行。迁移还必须写入 `cubepi_schema_version`。使用辅助函数:```python@@ -88,8 +88,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (def upgrade():op.create_table(...) # 从 cubeloop_metadata 自动生成- op.execute(create_message_partitions_op()) # cubeloop_messages 的 64 个哈希分区- op.execute(create_runs_partitions_op()) # cubeloop_runs 的 64 个哈希分区+ op.execute(create_message_partitions_op()) # cubepi_messages 的 64 个哈希分区+ op.execute(create_runs_partitions_op()) # cubepi_runs 的 64 个哈希分区op.execute(write_schema_version_op()) # 记录 EXPECTED_SCHEMA_VERSION```@@ -103,31 +103,31 @@ revision,再次调用 `op.execute(write_schema_version_op())`。## 数据模型```-cubeloop_threads+cubepi_threadsthread_id (PK)parent_thread_id -- 用于 forkforked_at_seq -- fork 点处的序列号extra -- JSONBcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- 复合 PK;按 HASH(thread_id) 分为 64 个分区role -- "user" | "assistant" | "tool"metadata -- JSONB(通过 GIN 索引)payload -- bytea (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- 复合 PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- 复合 PKanswer -- JSONBanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -162,7 +162,7 @@ advisory lock 让同一线程上的追加操作跨进程安全:`save_extra` 做的是 JSONB 合并,而不是替换:```sql-extra = cubeloop_threads.extra || EXCLUDED.extra+extra = cubepi_threads.extra || EXCLUDED.extra```所以先写 `{"foo": 1}` 再写 `{"bar": 2}` 会得到 `{"foo": 1, "bar": 2}`。@@ -172,7 +172,7 @@ extra = cubeloop_threads.extra || EXCLUDED.extra`parent_thread_id` + `forked_at_seq` 列用于支持[会话 Fork](../agents/forking):fork 会创建一个新的 thread,并在其-`cubeloop_threads` 行中写入指向源 thread 的 `parent_thread_id`,+`cubepi_threads` 行中写入指向源 thread 的 `parent_thread_id`,以及拷贝时源 thread 末尾的 `forked_at_seq`(最后一条已拷贝消息的`seq`)。@@ -201,24 +201,9 @@ def upgrade():关于混合数据的 fork 资格规则,请参阅[旧数据行为](../agents/forking#legacy-data-behaviour)。-## Schema v5 → v6 migration+## CubeLoop 更名-0.14 把 Postgres 表从 `cubepi_*` 重命名为 `cubeloop_*`。-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:--```python-from cubeloop.checkpointer.postgres.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- op.execute(upgrade_v5_to_v6_op())- op.execute(write_schema_version_op()) # 把 6 写入 cubeloop_schema_version-```--不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper——旧表已经在,只是名字还是 `cubepi_*`。-详见 [从 cubepi 迁移](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。## 常见坑diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.mdindex 327a545..e2da14e 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md@@ -1,19 +1,18 @@----title: From cubepi-description: "CubePi was renamed to CubeLoop in 0.14. How to update installs, imports, checkpointer schema, and traces."+title: 从 cubepi 迁移+description: "CubePi 在 0.14 更名为 CubeLoop;安装、导入、持久化和 trace 的迁移方法。"----# Migrating from cubepi+# 从 cubepi 迁移-0.14 renames the project from CubePi / `cubepi` to CubeLoop / `cubeloop`.-GitHub keeps the same repository (renamed in place to `cubeplexai/cubeloop`).-The docs site is https://cubeloop.dev.+0.14 将项目从 CubePi / `cubepi` 更名为 CubeLoop / `cubeloop`。GitHub 仓库+原地更名为 `cubeplexai/cubeloop`,文档站为 https://cubeloop.dev。-## Install and imports+## 安装与导入```bashpip install cubeloop-# extras are unchanged: cubeloop[sqlite], cubeloop[postgres], cubeloop[mysql], …+# extras 不变:cubeloop[sqlite]、cubeloop[postgres]、cubeloop[mysql]、…``````python@@ -21,36 +20,41 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.-It warns on first import. Prefer depending on `cubeloop` directly.+`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的+CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,+新项目应直接依赖 `cubeloop`。-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).+CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。-## Checkpointer schema v5 → v6+## Checkpointer schema 保持 v5-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.-SQLite table names were never prefixed; they stay `messages` / `runs` / ….+Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*`。这些名字属于+持久化协议,不是产品品牌。schema version 保持 5,因此已有 0.13.6 数据库升级到+0.14.1 不需要数据库迁移。SQLite 表名从未加品牌前缀,保持不变。-Existing databases: add an Alembic revision that runs-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that-helper — not “tables not found”.+历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`+导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-If you have data tables but no `*_schema_version` table, do not apply the-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,-then run the v5→v6 helper.+### 从已撤回的 0.14.0 紧急恢复-## Tracing+0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过+那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用+数据库管理客户端执行对应脚本:++- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)+- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)-New spans use `cubeloop.*` attributes and `cubeloop.turn` span names.-`cubeloop trace` still reads 0.13 JSONL that used `cubepi.*`.-Dashboards you own need their own attribute-name update.+脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。+正常 v5 数据库不要执行这些脚本。++## Tracing-Default JSONL directory is `./cubeloop-traces`.+新 span 使用 `cubeloop.*` 属性和 `cubeloop.turn` span 名。`cubeloop trace` 仍能读取+0.13 中使用 `cubepi.*` 的 JSONL;你自己的 dashboard 需要更新属性名。默认 JSONL+目录为 `./cubeloop-traces`。-## Environment variables+## 环境变量-`CUBELOOP_TEST_PG_DSN`, `CUBELOOP_TEST_MYSQL_DSN`, `CUBELOOP_PG_DSN`,-`CUBELOOP_MYSQL_DSN` replace the `CUBEPI_*` names. The old names are still-read if the new one is unset, for the rest of 0.x.+`CUBELOOP_TEST_PG_DSN`、`CUBELOOP_TEST_MYSQL_DSN`、`CUBELOOP_PG_DSN`、+`CUBELOOP_MYSQL_DSN` 替换对应的 `CUBEPI_*` 名称。新名称未设置时,0.x 的剩余+周期仍会读取旧名称。diff --git a/website/static/recovery/0.14.0/mysql-v6-to-v5.sql b/website/static/recovery/0.14.0/mysql-v6-to-v5.sqlnew file mode 100644index 0000000..52df85e--- /dev/null+++ b/website/static/recovery/0.14.0/mysql-v6-to-v5.sql@@ -0,0 +1,68 @@+-- Emergency recovery for databases created or migrated by withdrawn 0.14.0.+-- Stop all application instances and take a backup before running this file.+SET @cp_new_tables = (+ SELECT COUNT(*) FROM information_schema.tables+ WHERE table_schema = DATABASE() AND table_name IN (+ 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',+ 'cubeloop_hitl_answers', 'cubeloop_schema_version'+ )+);+SET @cp_old_tables = (+ SELECT COUNT(*) FROM information_schema.tables+ WHERE table_schema = DATABASE() AND table_name IN (+ 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',+ 'cubepi_hitl_answers', 'cubepi_schema_version'+ )+);+SET @cp_new_indexes = (+ SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics+ WHERE table_schema = DATABASE() AND index_name IN (+ 'ix_cubeloop_messages_metadata_gin',+ 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'+ )+);+SET @cp_old_indexes = (+ SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics+ WHERE table_schema = DATABASE() AND index_name IN (+ 'ix_cubepi_messages_metadata_gin',+ 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'+ )+);+SET @cp_fresh_indexes = (@cp_new_indexes > 0);+SET @cp_guard = IF(+ @cp_new_tables = 5 AND @cp_old_tables = 0+ AND ((@cp_new_indexes = 0 AND @cp_old_indexes = 2)+ OR (@cp_new_indexes = 2 AND @cp_old_indexes = 0)),+ 'DO 0',+ 'SELECT * FROM cubeloop_0140_recovery_preflight_failed'+);+PREPARE cp_guard FROM @cp_guard;+EXECUTE cp_guard;+DEALLOCATE PREPARE cp_guard;++RENAME TABLE+ cubeloop_threads TO cubepi_threads,+ cubeloop_messages TO cubepi_messages,+ cubeloop_runs TO cubepi_runs,+ cubeloop_hitl_answers TO cubepi_hitl_answers,+ cubeloop_schema_version TO cubepi_schema_version;++SET @cp_rename_message_index = IF(+ @cp_fresh_indexes,+ 'ALTER TABLE cubepi_messages RENAME INDEX ix_cubeloop_messages_thread_run TO ix_cubepi_messages_thread_run',+ 'DO 0'+);+PREPARE cp_stmt FROM @cp_rename_message_index;+EXECUTE cp_stmt;+DEALLOCATE PREPARE cp_stmt;+SET @cp_rename_run_index = IF(+ @cp_fresh_indexes,+ 'ALTER TABLE cubepi_runs RENAME INDEX ix_cubeloop_runs_thread_seq TO ix_cubepi_runs_thread_seq',+ 'DO 0'+);+PREPARE cp_stmt FROM @cp_rename_run_index;+EXECUTE cp_stmt;+DEALLOCATE PREPARE cp_stmt;++DELETE FROM cubepi_schema_version WHERE version <> 5;+INSERT IGNORE INTO cubepi_schema_version (version) VALUES (5);diff --git a/website/static/recovery/0.14.0/postgres-v6-to-v5.sql b/website/static/recovery/0.14.0/postgres-v6-to-v5.sqlnew file mode 100644index 0000000..7a6c03f--- /dev/null+++ b/website/static/recovery/0.14.0/postgres-v6-to-v5.sql@@ -0,0 +1,83 @@+-- Emergency recovery for databases migrated by withdrawn cubeloop 0.14.0.+-- Stop all application instances and take a backup before running this file.+BEGIN;++DO $$+DECLARE+ schema_name text := current_schema();+ new_count integer;+ old_count integer;+ new_index_count integer;+ old_index_count integer;+ i integer;+BEGIN+ SELECT count(*) INTO new_count+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace+ WHERE relname IN (+ 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',+ 'cubeloop_hitl_answers', 'cubeloop_schema_version'+ ) AND n.nspname = schema_name;+ SELECT count(*) INTO old_count+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace+ WHERE relname IN (+ 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',+ 'cubepi_hitl_answers', 'cubepi_schema_version'+ ) AND n.nspname = schema_name;+ IF new_count <> 5 OR old_count <> 0 THEN+ RAISE EXCEPTION+ 'expected a complete 0.14.0 schema (5 cubeloop tables, 0 cubepi tables); found % and %',+ new_count, old_count;+ END IF;+ SELECT count(*) INTO new_index_count+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace+ WHERE relkind = 'i' AND relname IN (+ 'ix_cubeloop_messages_metadata_gin',+ 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'+ ) AND n.nspname = schema_name;+ SELECT count(*) INTO old_index_count+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace+ WHERE relkind = 'i' AND relname IN (+ 'ix_cubepi_messages_metadata_gin',+ 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'+ ) AND n.nspname = schema_name;+ IF new_index_count <> 3 OR old_index_count <> 0 THEN+ RAISE EXCEPTION+ 'index preflight failed: expected 3 cubeloop indexes and 0 cubepi indexes';+ END IF;++ FOR i IN 0..63 LOOP+ IF to_regclass(format('%I.%I', schema_name, 'cubeloop_messages_p' || lpad(i::text, 2, '0'))) IS NULL+ OR to_regclass(format('%I.%I', schema_name, 'cubeloop_runs_p' || lpad(i::text, 2, '0'))) IS NULL+ OR to_regclass(format('%I.%I', schema_name, 'cubepi_messages_p' || lpad(i::text, 2, '0'))) IS NOT NULL+ OR to_regclass(format('%I.%I', schema_name, 'cubepi_runs_p' || lpad(i::text, 2, '0'))) IS NOT NULL THEN+ RAISE EXCEPTION 'partition preflight failed at suffix %', i;+ END IF;+ END LOOP;++ EXECUTE format('ALTER TABLE %I.cubeloop_threads RENAME TO cubepi_threads', schema_name);+ EXECUTE format('ALTER TABLE %I.cubeloop_messages RENAME TO cubepi_messages', schema_name);+ FOR i IN 0..63 LOOP+ EXECUTE format(+ 'ALTER TABLE %I.%I RENAME TO %I', schema_name,+ 'cubeloop_messages_p' || lpad(i::text, 2, '0'),+ 'cubepi_messages_p' || lpad(i::text, 2, '0')+ );+ END LOOP;+ EXECUTE format('ALTER TABLE %I.cubeloop_runs RENAME TO cubepi_runs', schema_name);+ FOR i IN 0..63 LOOP+ EXECUTE format(+ 'ALTER TABLE %I.%I RENAME TO %I', schema_name,+ 'cubeloop_runs_p' || lpad(i::text, 2, '0'),+ 'cubepi_runs_p' || lpad(i::text, 2, '0')+ );+ END LOOP;+ EXECUTE format('ALTER TABLE %I.cubeloop_hitl_answers RENAME TO cubepi_hitl_answers', schema_name);+ EXECUTE format('ALTER TABLE %I.cubeloop_schema_version RENAME TO cubepi_schema_version', schema_name);+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_metadata_gin RENAME TO ix_cubepi_messages_metadata_gin', schema_name);+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_thread_run RENAME TO ix_cubepi_messages_thread_run', schema_name);+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_runs_thread_seq RENAME TO ix_cubepi_runs_thread_seq', schema_name);+ EXECUTE format('DELETE FROM %I.cubepi_schema_version WHERE version <> 5', schema_name);+ EXECUTE format('INSERT INTO %I.cubepi_schema_version (version) VALUES (5) ON CONFLICT DO NOTHING', schema_name);+END $$;++COMMIT;diff --git a/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx b/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdxindex 71fbf3a..3efe10a 100644--- a/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx+++ b/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx@@ -807,9 +807,9 @@ claim_run(thread_id: str, run_id: str) -> NoneAtomically claim a run_id on a thread.-Lazy-creates the cubeloop_threads row, takes a per-thread FOR UPDATE+Lazy-creates the cubepi_threads row, takes a per-thread FOR UPDATElock to serialize concurrent claims for the same thread, then-checks cubeloop_runs for an existing row before inserting. The+checks cubepi_runs for an existing row before inserting. Thepre-check matches the Postgres approach — using INSERT + catchingIntegrityError would also work, but a pre-SELECT lets usdistinguish in-flight vs completed cleanly without relying on the@@ -880,10 +880,10 @@ fork(Copy completed prefix of `src_thread_id` into `new_thread_id`.-Threads-row first: the destination `cubeloop_threads` row is+Threads-row first: the destination `cubepi_threads` row isinserted before the message + runs copies so callers see a-complete view if they probe mid-fork. There is no cubeloop_runs ->-cubeloop_threads FK on MySQL (partition limitation), but we keep+complete view if they probe mid-fork. There is no cubepi_runs ->+cubepi_threads FK on MySQL (partition limitation), but we keepthe same ordering for semantic parity with Postgres.Per-thread serialization: a `SELECT … FOR UPDATE` on the sourcediff --git a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.mdindex e636840..29e3b49 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md@@ -61,8 +61,8 @@ async with MySQLCheckpointer(## Schema-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`. Like+The checkpointer expects `cubepi_threads`, `cubepi_messages`,+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`. LikePostgres (and unlike SQLite), CubeLoop **does not create these for you** —it verifies on `__aenter__` that they exist with the expected`schema_version`.@@ -90,7 +90,7 @@ Then autogenerate a revision:alembic revision --autogenerate -m "add cubeloop checkpointer"```-The `cubeloop_messages` table is `KEY`-partitioned, which SQLAlchemy's+The `cubepi_messages` table is `KEY`-partitioned, which SQLAlchemy'sautogenerate cannot express, so append the partition clause and theschema-version write with the provided helpers:@@ -102,16 +102,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import ()def upgrade():- op.create_table("cubeloop_threads", ...)+ op.create_table("cubepi_threads", ...)op.create_table(- "cubeloop_messages", ...,+ "cubepi_messages", ...,mysql_engine="InnoDB",)# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:op.execute(- "ALTER TABLE cubeloop_messages " + messages_partition_clause()+ "ALTER TABLE cubepi_messages " + messages_partition_clause())- op.create_table("cubeloop_schema_version", ...)+ op.create_table("cubepi_schema_version", ...)# write_schema_version_op() returns two ';'-separated statements# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,# so split and execute each:@@ -128,31 +128,31 @@ again.## Data model```-cubeloop_threads+cubepi_threadsthread_id (PK) -- VARCHAR(255) utf8mb4_bin (case-sensitive)parent_thread_id -- self-FK, for forksforked_at_seq -- seq number at fork pointextra -- JSONcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- composite PK; partitioned by KEY(thread_id) into 64role -- "user" | "assistant" | "tool"metadata -- JSON (not indexed; see below)payload -- LONGBLOB (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- composite PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- composite PKanswer -- JSONanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -199,8 +199,8 @@ from `dict.update`.)`MySQLCheckpointer` implements the v4 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The-`parent_thread_id` / `forked_at_seq` columns on `cubeloop_threads`-record fork lineage; `cubeloop_runs` (added in v4) tracks per-run+`parent_thread_id` / `forked_at_seq` columns on `cubepi_threads`+record fork lineage; `cubepi_runs` (added in v4) tracks per-runclaim/completion state.See the [Conversation Forking](../agents/forking) guide for the user-facing@@ -258,34 +258,17 @@ def upgrade():op.execute(stmt)```-## Schema v5 → v6 migration+## CubeLoop rename-0.14 renames the MySQL tables from `cubepi_*` to `cubeloop_*`.-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14-checkpointer on an existing database:--```python-from cubeloop.checkpointer.mysql.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- for stmt in upgrade_v5_to_v6_op().split(";"):- if stmt.strip():- op.execute(stmt)- for stmt in write_schema_version_op().split(";"):- if stmt.strip():- op.execute(stmt)-```--Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the-[migration guide](../../migration/from-cubepi).+The package rename does not change the persistence schema: physical names stay+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need+no migration. See the [migration guide](../../migration/from-cubepi), including+the exceptional recovery path for withdrawn 0.14.0.## Common pitfalls- **`CubeloopSchemaUninitialized`** — Your DB is empty, your migrations- didn't run, or the `cubeloop_schema_version` table is malformed. Apply+ didn't run, or the `cubepi_schema_version` table is malformed. Applythe host alembic upgrade first.- **`CubeloopSchemaMismatch`** — You upgraded CubeLoop but didn't generate anew migration. Generate one, apply it, and CubeLoop will start.@@ -296,7 +279,7 @@ Do not run the v6 `CREATE TABLE` helpers against a v5 database. See thehand-roll the DDL, keep that collation.- **`CheckpointCorruptionError` on `load()`** — A persisted message rowfailed to deserialize (bad msgpack payload, schema-invalid data, or an- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)locates the bad row for inspection or surgical repair; `thread_id` and`__cause__` carry the rest. CubeLoop never skips corrupt rows silently.diff --git a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.mdindex 9cfc204..938a20b 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md@@ -54,8 +54,8 @@ async with PostgresCheckpointer(## Schema-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`.+The checkpointer expects `cubepi_threads`, `cubepi_messages`,+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`.Unlike SQLite, CubeLoop**does not create these for you** — it verifies on `__aenter__` thatthey exist with the expected `schema_version`.@@ -89,9 +89,9 @@ alembic revision --autogenerate -m "add cubeloop checkpointer"Autogenerate emits the `CREATE TABLE`s from `cubeloop_metadata`, butSQLAlchemy `MetaData` **cannot model two things CubeLoop needs**, so addthem to the generated migration by hand: the 64 hash partitions of-`cubeloop_messages` (via `create_message_partitions_op()`), the 64-partitions of `cubeloop_runs` (via `create_runs_partitions_op()`), and-the `cubeloop_schema_version` row (via `write_schema_version_op()`). Use+`cubepi_messages` (via `create_message_partitions_op()`), the 64+partitions of `cubepi_runs` (via `create_runs_partitions_op()`), and+the `cubepi_schema_version` row (via `write_schema_version_op()`). Usethe helpers:```python@@ -104,8 +104,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (def upgrade():op.create_table(...) # auto-generated from cubeloop_metadata- op.execute(create_message_partitions_op()) # 64 hash partitions of cubeloop_messages- op.execute(create_runs_partitions_op()) # 64 hash partitions of cubeloop_runs+ op.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messages+ op.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runsop.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION```@@ -120,31 +120,31 @@ again.## Data model```-cubeloop_threads+cubepi_threadsthread_id (PK)parent_thread_id -- for forksforked_at_seq -- seq number at fork pointextra -- JSONBcreated_at / updated_at-cubeloop_messages+cubepi_messagesthread_id, seq -- composite PK; partitioned by HASH(thread_id) into 64role -- "user" | "assistant" | "tool"metadata -- JSONB (indexed via GIN)payload -- bytea (msgpack)created_at-cubeloop_runs+cubepi_runsthread_id, run_id -- composite PKclaimed_at / completed_atcompletion_seq-cubeloop_hitl_answers+cubepi_hitl_answersthread_id, run_id, question_id -- composite PKanswer -- JSONBanswered_at-cubeloop_schema_version+cubepi_schema_versionversion (PK)```@@ -182,7 +182,7 @@ The pool default of `min=1, max=10` is fine for most apps; bump`save_extra` does a JSONB merge, not a replace:```sql-extra = cubeloop_threads.extra || EXCLUDED.extra+extra = cubepi_threads.extra || EXCLUDED.extra```So writing `{"foo": 1}` then `{"bar": 2}` leaves `{"foo": 1, "bar":@@ -194,8 +194,8 @@ keys.`PostgresCheckpointer` implements the v4 `snapshot` / `fork` /`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The-`parent_thread_id` and `forked_at_seq` columns on `cubeloop_threads`-record fork lineage; `cubeloop_runs` (the v4 partitioned table) tracks+`parent_thread_id` and `forked_at_seq` columns on `cubepi_threads`+record fork lineage; `cubepi_runs` (the v4 partitioned table) tracksper-run claim/completion state.See the [Conversation Forking](../agents/forking) guide for the user-facing@@ -246,26 +246,12 @@ def upgrade():op.execute(write_schema_version_op()) # bumps cubepi_schema_version to 5```-## Schema v5 → v6 migration+## CubeLoop rename-0.14 renames the Postgres tables from `cubepi_*` to `cubeloop_*`.-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14-checkpointer on an existing database:--```python-from cubeloop.checkpointer.postgres.alembic_helpers import (- upgrade_v5_to_v6_op,- write_schema_version_op,-)--def upgrade():- op.execute(upgrade_v5_to_v6_op())- op.execute(write_schema_version_op()) # writes 6 into cubeloop_schema_version-```--Do not run the v6 `CREATE TABLE` helpers against a v5 database — they-would try to create tables that already exist under the old names.-See the [migration guide](../../migration/from-cubepi).+The package rename does not change the persistence schema: physical names stay+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need+no migration. See the [migration guide](../../migration/from-cubepi), including+the exceptional recovery path for withdrawn 0.14.0.## Common pitfalls@@ -295,7 +281,7 @@ See the [migration guide](../../migration/from-cubepi).— pass both to Alembic separately.- **`CheckpointCorruptionError` on `load()`** — A persisted message rowfailed to deserialize (bad msgpack payload, schema-invalid data, or an- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)locates the bad row for inspection or surgical repair; `thread_id` and`__cause__` carry the rest. CubeLoop never skips corrupt rows silently —dropping a message that carries `tool_calls` would leave thediff --git a/website/versioned_docs/version-0.14/migration/from-cubepi.md b/website/versioned_docs/version-0.14/migration/from-cubepi.mdindex 327a545..e201c52 100644--- a/website/versioned_docs/version-0.14/migration/from-cubepi.md+++ b/website/versioned_docs/version-0.14/migration/from-cubepi.md@@ -21,25 +21,37 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.+`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a+compatible CubeLoop 0.14 release, re-exports the public API, and aliases+`cubepi.*` imports.It warns on first import. Prefer depending on `cubeloop` directly.CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).-## Checkpointer schema v5 → v6+## Checkpointer schema stays at v5-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.+Postgres and MySQL keep their `cubepi_*` physical table and index names. They+are persistent protocol identifiers, not product branding. Schema version 5 is+unchanged, so an existing 0.13.6 database needs no migration for 0.14.1.SQLite table names were never prefixed; they stay `messages` / `runs` / ….-Existing databases: add an Alembic revision that runs-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that-helper — not “tables not found”.+Historical host Alembic revisions may import helpers from+`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their original+v1–v5 SQL. Do not add a rename revision.-If you have data tables but no `*_schema_version` table, do not apply the-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,-then run the v5→v6 helper.+### Emergency recovery from withdrawn 0.14.0++0.14.0 was yanked because it briefly renamed these database objects to+`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn+migration. Stop every application instance, take a verified backup, then run+the script for your database with an administrative SQL client:++- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)+- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)++The scripts refuse mixed/colliding schemas before renaming anything. Afterward,+verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5+database.## Tracingdiff --git a/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md b/website/versioned_docs/version-0.14/recipes/postgres-fastapi.mdindex ff26ae5..7450637 100644--- a/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md+++ b/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md@@ -20,13 +20,13 @@ Before the service starts, run the CubeLoop schema migration. Thequickest way for this recipe:```bash-# Throwaway / recipe: copy the v6 bootstrap from-# examples/checkpointing_postgres.py (cubeloop_threads, cubeloop_messages +-# 64 partitions, cubeloop_runs + 64 partitions, cubeloop_hitl_answers,-# cubeloop_schema_version = 6).+# Throwaway / recipe: copy the v5 bootstrap from+# examples/checkpointing_postgres.py (cubepi_threads, cubepi_messages ++# 64 partitions, cubepi_runs + 64 partitions, cubepi_hitl_answers,+# cubepi_schema_version = 5).```-Existing v5 databases must run `upgrade_v5_to_v6_op()` instead of CREATE.+Existing v5 databases need no migration for the CubeLoop package rename.For a real deployment, generate this via Alembic — see[Postgres Checkpointing → Bootstrapping via Alembic](../guides/checkpointing/postgres#bootstrapping-via-alembic).