chore: align sqlite control plane architecture

- replace default Convex control-plane wording with Rust SQLite control-plane across architecture, AGENTS, Reasonix, and design docs - retire root Convex functions source and deploy script into recycle while keeping explicit cloud/compat/sync-replica boundaries - add control-plane migration guard/docs and keep CodeGraph refreshed after the SQLite control-plane cutover
2026-05-22 17:45:22 +08:00
parent 531e845600
commit 47e224d419
79 changed files with 7634 additions and 2600 deletions
@@ -9,8 +9,8 @@
 `3000` 继续是唯一浏览器公开入口，但 tree route 不再承载长期树域主语义。

 - Rust runtime 负责 tree command legality、canonical plan、write operation、domain event plan 与稳定 stream delta 语义。
- Next route 负责 cookie/auth、Convex client、browser/substrate 能力桥、CommandEnvelope、transport、artifact writer 调用与用户可见回包。
- Convex 继续作为 substrate 执行器，不重新生成 tree truth。
+- Rust `mnote-web` route 负责 session/actor、source-specific client、browser/substrate 能力桥、CommandEnvelope、transport、artifact writer 调用与用户可见回包；本文中的 Next route 是历史 thin-proxy 阶段记录。
+- Convex 仅在显式 cloud / compat source 下作为 substrate 执行器，不重新生成 tree truth；默认 local-first 路径走 LocalFS + Rust SQLite control-plane。

 ## 2. Thin Proxy Route

@@ -21,7 +21,7 @@
 它不重新定义树域协议。已有结论继续成立：

 - `tree-first graph kernel` 是长期对象真相层。
- `Convex` 继续作为本地自托管存储、实时、文件协作底座。
+- Rust SQLite control-plane 承接默认 auth / share / sync / AI policy 控制面，Convex 仅保留历史迁移源、显式 cloud source / compat / sync replica 边界。
 - `mnote-web` 是 Rust Web 主执行面，负责 projection、command、transport 与 realtime stream。
 - 前端和 tree shell 只消费稳定 projection，并持有本地交互态。

@@ -28,7 +28,7 @@ ConvexWorkspaceSource -> Tree Kernel -> file_tree / page_tree / page_aggregate -

 - `Convex` 不再是所有 workspace 的必经中介。
 - `Local Folder` 不经过 Convex，直接由 Rust source adapter 读取和写入本地文件系统。
- `Convex` 继续作为 cloud workspace 的 source adapter，负责同步、协作、权限、分享和远程资源。
+- `Convex` 仅作为显式 cloud / compat workspace 的 source adapter 或 sync replica；同步、协作、权限、分享默认控制面已由 Rust SQLite control-plane 承接。
 - 两者共用同一套 projection、command、preflight、runtime state 和 UI。
 - 差异只允许出现在 `WorkspaceSource` 的 capability、preflight plan 和 executor 中。

@@ -15,12 +15,12 @@
 - 使用本轮独立身份或独立 workspace 创建测试页面、子页面、附件、mindmap、table。
 - 对五类对象执行默认删除，确认进入对应垃圾箱。
 - 执行页面垃圾箱清空与资源垃圾箱清空。
- 查询 Convex，确认本轮 document / media_asset / mindmap / document_table / document_table_rows 不再存在。
+- 查询当前 source 的持久化状态；历史 Convex source smoke 才确认 document / media_asset / mindmap / document_table / document_table_rows 不再存在。
 - 记录关联清理边界：Storage、OCR、LightRAG、page references、recent pages、favorites。

 ## 推荐方案

-优先使用一次性 Convex Auth 用户：
+优先使用一次性 SQLite control-plane Auth 用户：

 1. 通过 Rust `/api/auth` 走 password `signUp`，邮箱使用 `mnote.trash.<timestamp>@example.com`。
 2. 使用同一 browser/request context 打开 `/`，触发 `workspaces.ensureDefaultWorkspace` 创建独立 personal workspace。
@@ -22,7 +22,7 @@

 - 不在默认测试账号既有 workspace 上执行批量删除。
 - 不对默认 workspace 执行 `emptyTrashByWorkspace`。
- 使用一次性 Convex Auth 用户注册后自动获得的默认 workspace。
+- 使用一次性 SQLite control-plane Auth 用户注册后自动获得的默认 workspace；旧 Convex Auth 只作为历史 compat 对照。
 - 清理仅针对本轮创建对象；如清理失败，只记录对象 ID，不扩大删除范围。

 ## 3. 建议脚本
@@ -18,7 +18,7 @@
  - `tree.resource.restore -> mediaAssets:patchById`
  - `tree.resource.purge -> mediaAssets:purgeById`
  - `tree.resource.rename -> mediaAssets:patchById`
- `storage-convex-bridge` 为上述命令提供默认 Convex 映射。
+- `storage-convex-bridge` 为上述命令提供历史 / cloud / compat source 的 Convex 映射；默认 local-first 资源生命周期不再依赖 Convex functions。
 - `wolai-frontend` 的 `/api/media/batch`：
  - `delete` 改为 `tree.resource.archive`
  - `restore` 改为 `tree.resource.restore`
@@ -54,14 +54,11 @@ pnpm test src/lib/documents/tree-command-client.test.ts src/lib/documents/restor
 真实浏览器 smoke：

 ```bash
-cd /mnt/Data1T/mnote/wolai-frontend
-npx convex dev --once --tail-logs disable --env-file ../.env.all --run ping:ping
-
 cd /mnt/Data1T/mnote
 node scripts/task429-trash-restore-location-reveal-smoke.js
 ```

-结果：通过。脚本使用一次性用户 / workspace，在 3000 主入口验证：
+结果：通过。脚本使用一次性用户 / workspace，在 3000 主入口验证；历史记录中曾需手工注册 Convex functions，当前默认 auth/session/control-plane 已切到 SQLite，不再要求先启动 Convex：

 - 删除子页面后通过 `tree.node.restore` 恢复，返回 `restore_location.parent_id` 为原父页面、`sort_order` 为原排序位。
 - 原排序位已被兄弟页面占用时，兄弟页面被后移，Convex 中不产生重复 `sort_order`。
@@ -63,15 +63,15 @@
 1. Next route 构造 `buildDocumentCommandEnvelope`
 2. `resolveRustBridgeCommandPlan`
 3. TS runtime 负责 transport dispatch
-4. Convex mutation 负责实际持久化
+4. source-specific executor 负责实际持久化；Convex mutation 仅属于历史 / cloud / compat source

 因此当前形态是：

- `Convex substrate`
+- `WorkspaceSource substrate`（Convex 仅为历史 / cloud / compat source）
 - `Rust semantic owner`
 - `TS runtime transport dispatcher`

-不是“Rust 已经直接替代 Convex 落库”。
+不是“所有 source 都由同一个前端 route 自行落库”；默认 local-first source 已继续演进为 Rust / LocalFS / SQLite control-plane。

 ### 2.3 当前仍留在前端的树语义