docs: investigate optional pgembed event store backend

[wuxianliang]

Summary

• add a read-only architecture investigation for an optional pgembed-backed LoopX state-event store
• distinguish the Markdown-to-event canonical truth migration from the file-to-pgembed physical provider migration
• document process ownership, fencing, export/import, rollback, packaging, platform, security, and phased rollout constraints

Key conclusion

The first safe seam is the existing append-only state-event store, but it is not yet the canonical todo write path. Phase one should keep the file/Markdown path canonical and use pgembed as an internal read-only shadow/parity provider rather than expose a global storage_backend=file|pgembed switch.

Validation

• verified cited LoopX read/write paths and rollout gates against current code
• checked pgembed public API, process lifecycle, package/platform constraints, and PostgreSQL-major migration behavior against the local pgembed repository
• scanned the report for credentials, local absolute paths, raw logs/evidence, and private organizational context
• confirmed the branch contains only docs/investigations/loopx-pgembed-storage-backend-2026-08-12.md

Scope

Documentation/investigation only. No runtime behavior, benchmark, permission, destructive Git, public evidence-policy, or launch behavior changes.

[huangruiteng]

详细中文评审

精确评审头： 3128@f36ac7b1a9de0384395c2a0ef6eac37992063175

动机

在已关闭的 #3126 基础上，本 PR 以同一日期文件名重新提交，把原先“待调查/待综合”的骨架补全为一份可执行的架构调查结论。背景是 LoopX 的持久化路径由多套文件协议组成（Markdown active state、JSONL event ledger、run artifact、task lease、domain state、registry/authority），引入 pgembed 之前必须先回答“是否存在一个合理的全局 storage backend seam”。文档给出的核心结论是：不能先做笼统的 storage_backend=file|pgembed，必须把“Markdown → event canonical”的语义迁移与“file → pgembed”的物理迁移拆成两条轴，第一阶段只交付 provider-neutral event-store seam、文件默认实现和 pgembed read-only shadow/parity。

改动思路

调查从真实代码证据出发而不是从 PR 元数据推断：先定位 AppendOnlyStateEventStore 的 load/append/append_many 语义（幂等 event_id、冲突检测、单调 append_sequence、逐项追加非原子、无显式 fsync），再逐条核对 todo canonical 写链（list/add/update/complete 仍以 Markdown 为写入真相，事件投影只参与 overlay/fallback），并核对 migration bridge 与 write-correctness 两个 gate 的真实语义（均 fail closed，且没有生产消费者证明其是 backend switch）。随后排除九个常见假设，给出 root cause、分阶段建议、决策矩阵、预防措施和未决问题清单。整体思路是“先证明真实 seam，再谈 provider 切换”，并明确反目标（禁止全局开关、禁止双 active writer、禁止静默 fallback）。

具体改动

单文件、纯文档：docs/investigations/loopx-pgembed-storage-backend-2026-08-12.md（+230 行），无运行时代码、无 benchmark/permission/evidence-policy 改动。

关键内容讲解

• §2 canonical 读写链表格：我按 exact-head 实测核对，行号基本吻合：list_goal_todos（todos.py:412）、add_goal_todo（852）、update_goal_todo（1137）、complete_goal_todo（1507）；AppendOnlyStateEventStore（event_sourced_state.py:543-585）的 load/append/append_many 语义与文档描述一致；event_writeback.py:336 的直接构造点准确。
• §3 两个 gate：event_store_migration_bridge.wait_for_event_read_path 实测位于 76 行（文档引用 45-95，函数范围一致，行号有小漂移）；local_state_write_correctness.preview_only 位于 85 行（文档引用 29-100），结论“只约束 dry-run/shadow，不拦截真实 Markdown 写”成立。
• §5 extension/provider 生命周期：manifest 的 entrypoint/python_module 约束（manifest.py:195）、install/enable/doctor 的 bounded 语义（runtime.py:132 起）、subprocess readiness 与 process group 限制（readiness/process_runtime）与文档结论一致：现有 extension runtime 足以交付 provider 包，但不能独自拥有 PostgreSQL postmaster 生命周期。
• §8/§9 验收门槛与未决问题：列出 replay parity、幂等/冲突、坏行/partial append、fencing、rollback/export、PostgreSQL major 迁移和 supervisor namespace 范围选择，边界清楚。

对主干的风险

纯文档改动对主干无运行时风险。需要管理的是读者把“调查结论”误读为已批准的实施蓝图；文档已通过反目标与 phase-one 范围明确限定（不做全局开关、不迁 run history/lease/domain state/registry、不引入 pgvector、不允许 silent fallback），风险可控。外部事实方面，我复核了 PyPI pgembed 元数据（requires-python >=3.12 属实）和上游 pyproject.toml；平台矩阵、许可证与 TimescaleDB 捆绑等仍以上游仓库为准，文档自身也要求实施前做 distribution/legal review，属于合理留白。分支无 CI checks（docs-only 分支未配置 checks），本次验证以 exact-head 代码抽查、外部事实核对和公开/私有边界扫描完成。

我的整体评价

APPROVE。 这是一份完成度高、证据扎实的架构调查：结论与 exact-head 代码一致，公开/私有边界干净（无凭据、无本地绝对路径、无内部链接），分阶段建议可回退，决策矩阵覆盖了主要误设计风险。无阻塞项，无实质 P2 建议。合并与上线仍按 loopx-pr-merge 的评审/合并流程执行。

---

English Verdict

APPROVE — exact head f36ac7b1a9de0384395c2a0ef6eac37992063175.

Docs-only investigation (1 file, +230 lines) that replaces the closed #3126 skeleton with verified findings: the safe seam is the existing append-only state-event store, not a global storage_backend switch; normal todo lifecycle remains Markdown-canonical; pgembed should land as an optional shadow/parity provider. In-repo code citations were spot-checked at the exact head and match; PyPI/upstream metadata confirms requires-python >=3.12; no credentials, local paths, or internal links found. No CI checks are configured for this docs-only branch; validation was local exact-head review plus bounded external fact-checking. No blockers.

[huangruiteng]

仓库有一份 nokv 的 rfc 想做类似事情（跨 host 的 state 云端共享），里面也讨论了相关问题并有推进，请调研一下 nokv 的 rfc 设计，两个提案尽量共享底座能力的提升。 也请加入飞书 loopx 的开发群，可一起讨论设计和分工；

[huangruiteng]

详细中文评审（重审确认）

精确评审头： 3128@f36ac7b1a9de0384395c2a0ef6eac37992063175

动机

按全队列重审要求复核本 PR（pgembed 存储后端架构调查，docs-only）。exact head 自 10:31Z owner CHANGES_REQUESTED 后未变；文档本身技术价值充分（此前 APPROVE），但 owner 提出的协调动作尚未完成。

改动思路

调查文档把“全局 storage backend”收窄为 provider-neutral state-event store seam，区分 Markdown→event 语义迁移与 file→pgembed 物理迁移，结论与 exact head 代码一致。

具体改动（关键内容讲解）

• owner asks（blocking，作者动作）：10:31:05Z CR 要求——(1) 调研仓库 nokv RFC 的跨 host state 云端共享设计；(2) 让两个提案共享底座能力；(3) 加入飞书 LoopX 开发群讨论设计分工。当前 head 未体现这些动作。
• 技术结论：我此前的 APPROVE 仍成立（代码引用核对一致、公开安全）；本 CR 属协调/设计对齐，不是代码缺陷。

对主干的风险

低。纯文档；风险在于若未与 nokv RFC 对齐就推进实现，可能产生重复底座。因此 owner 的协调要求应在合入前完成。

我的整体评价

REQUEST_CHANGES（确认 owner 结论；技术内容保持认可）。 修复要求：作者完成 nokv RFC 调研、在文档中给出共享底座方案，并按 owner 要求参与讨论；完成后再复审。

---

English Verdict

REQUEST_CHANGES — exact head f36ac7b1a9de0384395c2a0ef6eac37992063175.

Confirms the owner's asks: research the nokv RFC, align both proposals on shared base capabilities, and coordinate in the LoopX dev group before merge. The document's technical content remains sound (prior approval stands); this CR is design-alignment, not a code defect.