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
docs(checkpointer): clarify v5 migration contract
xf gongbdf88a08855b
diff --git a/cubeloop/checkpointer/postgres/README.md b/cubeloop/checkpointer/postgres/README.mdindex edd7a2c..0318ab7 100644--- a/cubeloop/checkpointer/postgres/README.md+++ b/cubeloop/checkpointer/postgres/README.md@@ -108,7 +108,7 @@ def upgrade():# 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 partitions- op.execute(write_schema_version_op()) # record EXPECTED_SCHEMA_VERSION+ op.execute(write_schema_version_op()) # record historical schema v5```> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes@@ -131,7 +131,7 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (def upgrade():op.execute(add_pending_request_column_op()) # ADD COLUMN IF NOT EXISTS- op.execute(write_schema_version_op()) # bump to EXPECTED_SCHEMA_VERSION+ op.execute(write_schema_version_op()) # record historical schema v5def downgrade():op.execute("ALTER TABLE cubepi_threads DROP COLUMN IF EXISTS pending_request")diff --git a/website/docs/guides/checkpointing/mysql.md b/website/docs/guides/checkpointing/mysql.mdindex 40d602e..cc64412 100644--- a/website/docs/guides/checkpointing/mysql.md+++ b/website/docs/guides/checkpointing/mysql.md@@ -120,10 +120,9 @@ def upgrade():op.execute(stmt)```-`write_schema_version_op()` is idempotent: it deletes any rows from a-prior CubeLoop version and inserts the current one. When CubeLoop later-bumps `EXPECTED_SCHEMA_VERSION`, generate a new revision and run it-again.+`write_schema_version_op()` is the immutable historical v5 writer. It is+idempotent, deleting other version rows before inserting 5. A future schema+version must ship and use a new version-specific writer; do not reuse this one.## Data modeldiff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.mdindex 1500135..c691f64 100644--- a/website/docs/guides/checkpointing/postgres.md+++ b/website/docs/guides/checkpointing/postgres.md@@ -106,16 +106,13 @@ def upgrade():op.create_table(...) # auto-generated from cubeloop_metadataop.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messagesop.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runs- op.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION+ op.execute(write_schema_version_op()) # records historical schema v5```Both helpers return a SQL string — you pass them to `op.execute(...)`.-`write_schema_version_op()` is idempotent: it deletes any rows from a-prior CubeLoop version and inserts the current one.--When CubeLoop later upgrades and bumps `EXPECTED_SCHEMA_VERSION`, you-generate a new revision and call `op.execute(write_schema_version_op())`-again.+`write_schema_version_op()` is the immutable historical v5 writer. It is+idempotent, deleting other version rows before inserting 5. A future schema+version must ship and use a new version-specific writer; do not reuse this one.## Data modeldiff --git a/website/docs/migration/from-cubepi.md b/website/docs/migration/from-cubepi.mdindex c075245..91e929c 100644--- a/website/docs/migration/from-cubepi.md+++ b/website/docs/migration/from-cubepi.md@@ -38,8 +38,9 @@ Historical host Alembic revisions may import helpers from`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their originalv1–v5 SQL. Do not add a rename revision.-Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database-migration is required.+An existing schema-v5 database needs no rename migration. If the database is on+an earlier schema version, run its normal host Alembic migrations through v5+before opening the 0.14.1 checkpointer.## Tracingdiff --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 a975ede..e13e551 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@@ -102,7 +102,9 @@ def upgrade():op.execute(stmt)```-`write_schema_version_op()` 是幂等的:它会删除旧 CubeLoop 版本的记录行并插入当前版本。当 CubeLoop 之后更新 `EXPECTED_SCHEMA_VERSION` 时,生成新的 revision 并再次运行即可。+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入 5,+可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用这个+helper。## 数据模型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 34c8a1d..6deea7c 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@@ -90,15 +90,13 @@ def upgrade():op.create_table(...) # 从 cubeloop_metadata 自动生成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+ op.execute(write_schema_version_op()) # 记录历史 schema v5```两个辅助函数都返回 SQL 字符串——你需要传入 `op.execute(...)`。-`write_schema_version_op()` 是幂等的:它会删除之前 CubeLoop 版本的所有行,-然后插入当前版本。--当 CubeLoop 后续升级并提升了 `EXPECTED_SCHEMA_VERSION` 时,生成一个新的-revision,再次调用 `op.execute(write_schema_version_op())`。+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入+5,可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用+这个 helper。## 数据模型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 11a73e7..ac28432 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@@ -34,7 +34,8 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。+已有 schema v5 数据库不需要表名迁移。如果数据库仍是更早的 schema version,+请先通过宿主 Alembic migration 正常升级到 v5,再启动 0.14.1 checkpointer。## Tracingdiff --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 a975ede..e13e551 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@@ -102,7 +102,9 @@ def upgrade():op.execute(stmt)```-`write_schema_version_op()` 是幂等的:它会删除旧 CubeLoop 版本的记录行并插入当前版本。当 CubeLoop 之后更新 `EXPECTED_SCHEMA_VERSION` 时,生成新的 revision 并再次运行即可。+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入 5,+可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用这个+helper。## 数据模型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 34c8a1d..6deea7c 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@@ -90,15 +90,13 @@ def upgrade():op.create_table(...) # 从 cubeloop_metadata 自动生成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+ op.execute(write_schema_version_op()) # 记录历史 schema v5```两个辅助函数都返回 SQL 字符串——你需要传入 `op.execute(...)`。-`write_schema_version_op()` 是幂等的:它会删除之前 CubeLoop 版本的所有行,-然后插入当前版本。--当 CubeLoop 后续升级并提升了 `EXPECTED_SCHEMA_VERSION` 时,生成一个新的-revision,再次调用 `op.execute(write_schema_version_op())`。+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入+5,可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用+这个 helper。## 数据模型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 11a73e7..ac28432 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@@ -34,7 +34,8 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。+已有 schema v5 数据库不需要表名迁移。如果数据库仍是更早的 schema version,+请先通过宿主 Alembic migration 正常升级到 v5,再启动 0.14.1 checkpointer。## Tracingdiff --git a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.mdindex 40d602e..cc64412 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md@@ -120,10 +120,9 @@ def upgrade():op.execute(stmt)```-`write_schema_version_op()` is idempotent: it deletes any rows from a-prior CubeLoop version and inserts the current one. When CubeLoop later-bumps `EXPECTED_SCHEMA_VERSION`, generate a new revision and run it-again.+`write_schema_version_op()` is the immutable historical v5 writer. It is+idempotent, deleting other version rows before inserting 5. A future schema+version must ship and use a new version-specific writer; do not reuse this one.## Data modeldiff --git a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.mdindex 1500135..c691f64 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md@@ -106,16 +106,13 @@ def upgrade():op.create_table(...) # auto-generated from cubeloop_metadataop.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messagesop.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runs- op.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION+ op.execute(write_schema_version_op()) # records historical schema v5```Both helpers return a SQL string — you pass them to `op.execute(...)`.-`write_schema_version_op()` is idempotent: it deletes any rows from a-prior CubeLoop version and inserts the current one.--When CubeLoop later upgrades and bumps `EXPECTED_SCHEMA_VERSION`, you-generate a new revision and call `op.execute(write_schema_version_op())`-again.+`write_schema_version_op()` is the immutable historical v5 writer. It is+idempotent, deleting other version rows before inserting 5. A future schema+version must ship and use a new version-specific writer; do not reuse this one.## Data modeldiff --git a/website/versioned_docs/version-0.14/migration/from-cubepi.md b/website/versioned_docs/version-0.14/migration/from-cubepi.mdindex c075245..91e929c 100644--- a/website/versioned_docs/version-0.14/migration/from-cubepi.md+++ b/website/versioned_docs/version-0.14/migration/from-cubepi.md@@ -38,8 +38,9 @@ Historical host Alembic revisions may import helpers from`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their originalv1–v5 SQL. Do not add a rename revision.-Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database-migration is required.+An existing schema-v5 database needs no rename migration. If the database is on+an earlier schema version, run its normal host Alembic migrations through v5+before opening the 0.14.1 checkpointer.## Tracing