weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ops): record PG ledger ID remap milestone

Browse Source 
Claim the document-revision mutex and document the 6158 first-generation not-found root cause without calling UI-03 done.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
weichen
2026-09-13 23:43:56 +00:00
co-authored by Cursor
parent 2d0fcb94bc
commit 4e0951fe70
9 changed files with 232 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.doc/audit/2026-09-13-document-revision-pg-id-remap.md
+43
View File
@@ -0,0 +1,43 @@
---
title: "首次生成 PG ID 未同步计数器导致 baseline 被误删"
status: in_progress
created: 2026-09-13
updated: 2026-09-13
severity: critical
---
# 首次生成 PG ID 未同步计数器导致 baseline 被误删
## 现象
第19轮真实 UI（schema 31，项目 `6158` / `doc_proj6158_intake`）：小队输出、baseline snapshot=249、version=217、candidate output snapshot=250 / report=175 均已落库，candidate 保持 `ready`，任务失败 `docrevision: not found`（`CommitAgentVersion` 找不到 input snapshot）。
## 根因分析
`openTemplatePGLocked` 把 PostgreSQL `RETURNING id` 写入 `s.snapshots[249]` / `s.versions[217]`，但**不推进** `nextSnapID` / `nextVerID` / `nextEvtID`。
当进程内计数器已因其它文档 hydration 停在 248 时：
1. `putSnapshotLocked` 执行 `nextSnapID++` 得到临时 ID **249**，覆盖真实 baseline；
2. `persistAgentCandidateLocked` 把输出重映射到 250 后 `delete(s.snapshots, 249)`，误删 baseline；
3. `CommitAgentVersion` 按 `InputSnapshotID=249` 查找 → `ErrNotFound`；
4. 任务失败，candidate 仍 `ready`（不得伪装成功）。
同类无条件 `delete(map, oldID)` 也存在于 version / event / report / candidate 持久化路径。
## 严重度
`critical`
## 关联整改
- Remediation: [../remediation/2026-09-13-document-revision-pg-id-remap.md](../remediation/2026-09-13-document-revision-pg-id-remap.md)
## 证据
- 失败归档（只读，不改不删）：`.doc/test-reports/assets/2026-09-13-document-revision-runtime-ui/schema31-round19-ui03-advisor-briefing-docrevision-not-found/`
- Playwright：`squad observation rejected: error_terminal:failed`
## 开放问题
- 本轮不重跑真实 UI-03；不得标 E2E 通过或任务 `done`
.doc/audit/INDEX.md
+6
View File
@@ -31,6 +31,12 @@
### 最新专项审计（2026-09-13）
**文件**: [2026-09-13-document-revision-pg-id-remap.md](./2026-09-13-document-revision-pg-id-remap.md)
**结论**: 项目 6158 首次生成 PG 已写入 snapshot 249 / candidate 250，但内存计数器未同步，临时 ID 覆盖并删除 baseline，commit `not found`。
**整改**: [short-term](../ops/short-term/2026-09-13-document-revision-pg-id-remap.md)
**文件**: [2026-09-13-document-revision-post-restart-final-snippet.md](./2026-09-13-document-revision-post-restart-final-snippet.md)
**结论**: 第二次 post-restart 已恢复 V3/r2 与正文；失败只因 phase-state 仍断言 UI-06 marker，未写入 UI-13b A1 最终持久正文。
.doc/ops/CURRENT.md
+6 -4
View File
@@ -1,12 +1,12 @@
# 当前焦点
**更新**: 2026-09-13
**production_ready**: no（DOCREV：第二次 post-restart 恢复链已见 V3/r2，bodySnippet 过期未重跑；不执行 env-service 重建 / 不声称 E2E 通过）
**production_ready**: no（DOCREV：6158 首次生成 PG 已落库但 commit not found；不执行 env-service 重建 / 不声称 E2E 通过）
## 焦点
1. **DOCREV-RT**: [post-restart 最终持久正文](short-term/2026-09-13-document-revision-post-restart-final-snippet.md)（`fix/document-revision-post-restart-final-snippet`；编码已提交，暂不合入；不声称 post-restart 通过）
2. **DOCREV-RT**: [post-restart 项目名 selector](short-term/2026-09-13-document-revision-post-restart-selector.md)（已合入 `dev@eb85b8a`）
1. **DOCREV-RT**: [文档账本 PG ID 重映射](short-term/2026-09-13-document-revision-pg-id-remap.md)（`fix/document-revision-pg-id-remap`；工程修复已提交，暂不合入；不声称 UI-03 通过）
2. **DOCREV-RT**: [post-restart 最终持久正文](short-term/2026-09-13-document-revision-post-restart-final-snippet.md)（已合入 `dev@fa6a033`）
3. **DOCREV-RT**: [质量修复子工作区契约](short-term/2026-09-13-document-revision-quality-repair-workspace-contract.md)（已合入 `dev@339e871`；仍 `in_progress`，待占槽重跑 UI-03）
## 并行认领
@@ -35,7 +35,8 @@
| Cursor-Auto | document-revision-duty-cell-assertion | fix/document-revision-duty-cell-assertion | - | document-revision-duty-cell-assertion | in_progress |
| Cursor-Auto | document-revision-reviewer-duty-sync | fix/document-revision-reviewer-duty-sync | - | document-revision-reviewer-duty-sync | done |
| Cursor-Auto | document-revision-post-restart-selector | fix/document-revision-post-restart-selector | - | document-revision-post-restart-selector | done |
| Cursor-Auto | document-revision-post-restart-final-snippet | fix/document-revision-post-restart-final-snippet | - | document-revision-post-restart-final-snippet | in_progress |
| Cursor-Auto | document-revision-post-restart-final-snippet | fix/document-revision-post-restart-final-snippet | - | document-revision-post-restart-final-snippet | done |
| Cursor-Auto | document-revision-pg-id-remap | fix/document-revision-pg-id-remap | - | document-revision | in_progress |
> 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。
@@ -87,3 +88,4 @@
| UI-13a 私密分类导航失败审计 | [../audit/2026-09-13-document-revision-workflow-category-navigation.md](../audit/2026-09-13-document-revision-workflow-category-navigation.md) |
| UI-13a 职责单元格误判审计 | [../audit/2026-09-13-document-revision-duty-cell-assertion.md](../audit/2026-09-13-document-revision-duty-cell-assertion.md) |
| UI-13a reviewer 职责未同步审计 | [../audit/2026-09-13-document-revision-reviewer-duty-sync.md](../audit/2026-09-13-document-revision-reviewer-duty-sync.md) |
| UI-03 首次生成 PG ID 误删 baseline | [../audit/2026-09-13-document-revision-pg-id-remap.md](../audit/2026-09-13-document-revision-pg-id-remap.md) |
.doc/ops/checklists/2026-09-13-document-revision-pg-id-remap.md
+23
View File
@@ -0,0 +1,23 @@
---
title: "PG ID 重映射收紧"
status: in_progress
created: 2026-09-13
updated: 2026-09-13
related_task: "2026-09-13-document-revision-pg-id-remap.md"
---
# PG ID 重映射收紧
## Wave 0
- [x] `adopt*ID` 推进 counter，仅删同一对象
- [x] 临时 ID 跳过已占用键（snapshot/version/event/report/candidate）
- [x] openTemplate / human / candidate / commit / noop event 全走 adopt
- [x] 纯函数 + 高序列首次生成 PG 回归
- [x] `gofmt` / `go vet` / `go test -short ./...`
- [ ] 真实 UI-03（本轮不做）
## 完成定义
- [x] 上述实现项有测试证据
- [ ] 现场 UI-03 仍开放，不得标 done
.doc/ops/handoffs/2026-09-13-document-revision-pg-id-remap.md
+59
View File
@@ -0,0 +1,59 @@
---
title: "PG ID 重映射：工程修复后交接"
created: 2026-09-13
from: Cursor-Auto
to: next-agent
status: open
---
# 交接：PG ID 重映射（暂不合入）
## 目标（下一位 Agent 应完成什么）
- 合入前占 CURRENT 集成槽位，再 `--no-ff` 合 `dev`；本轮禁止 merge / 重建容器 / 声称 E2E
- 真实 UI-03（项目 6158 同类首次生成）待占槽重跑
## 已完成
- 统一 `advanceID` / `nextFreeID` / `adopt*ID`
- 首次生成高序列碰撞：自动提交成功，V1 baseline 未丢，candidate committed，新 Service 可 hydration
## 未完成
- 真实 UI-03
- 合入 `dev`
## 认领 / 槽位状态
| 项 | 值 |
|----|-----|
| mutex 已释放 | no（`document-revision` 仍 `in_progress`） |
| 集成槽位 holder | 他人 e2e；本任务未占槽 |
| branch | `fix/document-revision-pg-id-remap` |
| worktree | - |
## 关键文件
| 路径 | 说明 |
|------|------|
| `internal/docrevision/ids.go` | counter / adopt |
| `internal/docrevision/pg_mutate.go` | PG 写入后 adopt |
| `internal/docrevision/pg_id_remap_test.go` | 隔离 PG 碰撞 |
## 如何验证
```bash
go test -short ./internal/docrevision ./...
go vet ./...
# 隔离库（可选）：
TEST_DATABASE_URL='...' go test ./internal/docrevision -count=1 -run 'HighSequenceFirstGen|AdoptSnapshot|PutSnapshotLocked'
```
## 风险 / Blocker
- 不得把 `ErrNotFound` 改成忽略；失败任务必须保持失败
## 相关链接
- CURRENT: [../CURRENT.md](../CURRENT.md)
- Task: [../short-term/2026-09-13-document-revision-pg-id-remap.md](../short-term/2026-09-13-document-revision-pg-id-remap.md)
.doc/ops/short-term/2026-09-13-document-revision-pg-id-remap.md
+56
View File
@@ -0,0 +1,56 @@
---
title: "文档账本 PG ID 与计数器重映射"
status: in_progress
created: 2026-09-13
updated: 2026-09-13
owner: Cursor-Auto
branch: fix/document-revision-pg-id-remap
worktree: "-"
mutex: document-revision
---
# 文档账本 PG ID 与计数器重映射
## 目标
堵住 schema31-round19：首次生成 PG 已写入 snapshot/version/candidate，但 `CommitAgentVersion` 因内存 map 误删 baseline 而 `not found`。
## 范围
- `internal/docrevision` ID 分配、adopt、PG persist
- 确定性单测 + 隔离 PG 回归
- audit / remediation / CURRENT / FEATURE-MATRIX / gap-matrix
## 非目标
- 不 merge、不启停/重建容器、不跑/声称真实 UI E2E、不 push
- 不删不改证据目录
- 不忽略 `ErrNotFound`，不伪造基线/报告
## 步骤
1. [x] 从 `dev@fa6a033` 开分支并登记 mutex
2. [x] 独立验证 openTemplate 不推进 counter + 无条件 delete 误删
3. [x] 统一 helper + 全路径 adopt
4. [x] `gofmt` / `go vet` / `go test -short` / 相关包测试
5. [x] 原子提交
## 验收标准
- [x] 占用 ID 不覆盖；adopt 只删同一对象
- [x] 高序列首次生成：自动提交、V2、candidate committed、baseline 未丢、重启 hydration
- [ ] 现场 UI-03（未跑）
## 相关链接
- Audit: [../../audit/2026-09-13-document-revision-pg-id-remap.md](../../audit/2026-09-13-document-revision-pg-id-remap.md)
- Remediation: [../../remediation/2026-09-13-document-revision-pg-id-remap.md](../../remediation/2026-09-13-document-revision-pg-id-remap.md)
- Checklist: [../checklists/2026-09-13-document-revision-pg-id-remap.md](../checklists/2026-09-13-document-revision-pg-id-remap.md)
- Handoff: [../handoffs/2026-09-13-document-revision-pg-id-remap.md](../handoffs/2026-09-13-document-revision-pg-id-remap.md)
## 证据 / 备注
- 基线：`dev@fa6a033`
- 验证：`gofmt`/`go vet` PASS；`go test -short ./...` PASS；隔离临时库 `HighSequenceFirstGen` PASS（拒绝 `agent_system_dev`，测完 DROP）
- 证据（只读）：`.doc/test-reports/assets/2026-09-13-document-revision-runtime-ui/schema31-round19-ui03-advisor-briefing-docrevision-not-found/`
- **未跑真实 UI-03，不得标 done**；**不得 merge / 启停容器 / E2E / push**
.doc/remediation/2026-09-13-document-revision-pg-id-remap.md
+37
View File
@@ -0,0 +1,37 @@
---
title: "同步 PG 返回 ID 与进程内计数器"
status: in_progress
created: 2026-09-13
updated: 2026-09-13
---
# 同步 PG 返回 ID 与进程内计数器
## 背景
链到 [../audit/2026-09-13-document-revision-pg-id-remap.md](../audit/2026-09-13-document-revision-pg-id-remap.md)。
## 目标
- 所有 PG 写入后统一 `adopt*ID`：推进 counter，且仅当 map 旧键仍指向**同一对象**才删除
- 临时 ID 分配跳过已占用键，避免覆盖其它文档的真实对象
- `MaterializeAgentOutput` 在「baseline DB ID == 下一临时 ID」序列下自动提交成功；不得忽略 `ErrNotFound`、不得伪造基线/报告、失败任务不得显示成功
## 分波次计划
| 波次 | 内容 | 验收 |
|------|------|------|
| Wave 0 | 统一 ID helper + 首次生成/多文档/重启 hydration 回归 | `gofmt` / `go vet` / `go test -short`；隔离 PG 碰撞用例 |
| Wave 1 | 占槽重跑真实 UI-03（本轮不做） | 任务成功且 V2/head 可见 |
## 验收标准
- [x] 纯函数：占用 ID 跳过；adopt 不删其它对象
- [x] PG：高序列首次生成自动提交、V2/head、candidate committed、seed baseline 未丢、新 Service hydration
- [ ] 真实 UI-03（本轮不做）
## 相关链接
- Audit: [../audit/2026-09-13-document-revision-pg-id-remap.md](../audit/2026-09-13-document-revision-pg-id-remap.md)
- Short-term: [../ops/short-term/2026-09-13-document-revision-pg-id-remap.md](../ops/short-term/2026-09-13-document-revision-pg-id-remap.md)
- gap-matrix 行: DOCREV-PG-ID-REMAP
.doc/remediation/gap-matrix.md
+1
View File
@@ -61,6 +61,7 @@
| CHAT-INTENT-STATE | 真实会话被诊断探针污染；只读查询误启动文档写任务；错误动作与编辑状态刷新后丢失 | **FAIL** | [audit](../audit/2026-09-13-conversation-intent-runtime-state.md)；dev `sess-p143-u9` / task run / lease 现场 | [remediation](./2026-09-13-conversation-intent-runtime-state-remediation.md) |
| ENV-RESTART-SOURCE | `docker compose restart` 只重启旧镜像，健康检查无法证明合入代码已部署 | **PASS** | `env-service.sh rebuild` + 真实摘要重测 | 集成冒烟统一使用 `dev rebuild` |
| DOCREV-RUNTIME-404 | revision-state 404；账本内存丢失；块保存/overlay 无效；agent 假报告 | **FAIL** | [audit](../audit/2026-09-13-document-revision-runtime-404.md)；`internal/docrevision/service.go` 仅 map | [remediation](./2026-09-13-document-revision-runtime-remediation.md) |
| DOCREV-PG-ID-REMAP | 首次生成 PG 已写 snapshot/candidate，commit 因内存误删 baseline 而 not found | **FIX-LANDED**（工程） | [audit](../audit/2026-09-13-document-revision-pg-id-remap.md)；证据 `schema31-round19-ui03-advisor-briefing-docrevision-not-found`；`fix/document-revision-pg-id-remap` | 占槽真实 UI-03 重跑；不忽略 ErrNotFound；不删证据 |
| DOCREV-UI03-CLIENT-SYNC | 小队完成后右栏仍模板；UI-03 选择器误命中 Banner；`pending_author_confirmation` 撞 chk；重试重复建 run | **FIX-LANDED**（工程） | [audit](../audit/2026-09-13-controlled-doc-client-sync-ui03.md)；分支 `fix/document-revision-runtime-ui03`：post-task sync、templateMatch intake 优先、goose 00030、Claim+idempotency | 合入前：schema30 **真实现卷**迁移独立验证；占槽真实 UI-03 重跑；勿把 stub 当验收 |
| DOCREV-SSE-IDEM-BUSY | SSE WriteTimeout 断线后同 turn 再 POST 误 409 DOC_BUSY + 重复聊天 | **FIX-LANDED**（工程） | [audit](../audit/2026-09-13-document-revision-sse-idempotency.md)；证据 [assets/2026-09-13-document-revision-runtime-ui](../test-reports/assets/2026-09-13-document-revision-runtime-ui/)；`fix/document-revision-sse-idempotency` | 占槽真实 UI-03 重跑；不删证据 |
| DOCREV-QUALITY-SELF-POLLUTE | 自检表引用禁词致 score=40 quality_failed；auto_repair 未启用；UI 映射 completed | **FIX-LANDED**（工程） | [audit](../audit/2026-09-13-document-revision-quality-gate-self-pollution.md)；workspace `intake_1789308825666278807` output.md:204；同分支 | 占槽真实重跑；不删证据 |
.doc/status/FEATURE-MATRIX.md
+1 -1
View File
@@ -21,7 +21,7 @@
| 工作流治理 | 三正式工作流 + 阶段门禁 | done | [remediation/three-workflows](../remediation/2026-09-12-three-workflows-strict-governance-remediation.md)；[test 2026-09-12](../test-reports/2026-09-12-three-workflows-governance-remediation-test-report.md) | Phase2 设计器 partial | `workflow` |
| IAM / 鉴权 | 项目级 API 鉴权 + RBAC | partial | [audit/authorization](../audit/authorization-matrix-v2.md)；[刷新恢复专项审计](../audit/2026-09-13-chat-history-refresh-disappears.md) | 历史读取端点补统一会话 owner + 阶段授权；旧 API 410 标注(BUG-11 partial) | `authz` |
| 文档治理 | 法定文档生命周期 + 租约 | done | [test docgov](../test-reports/2026-09-08-docgov-lifecycle-and-claiming-framework-test-report.md) | — | `docgov` |
| 文档版本与修改认知 | 智能体版本边界、人工修订标记、任意版本比较、变更报告与负责人通知 | partial | [test 2026-09-13](../test-reports/2026-09-13-document-revision-management-test-report.md)；[运行时审计](../audit/2026-09-13-document-revision-runtime-404.md)；[当前文档路由](../audit/2026-09-13-document-revision-active-doc-routing.md)；[行动表状态假阳性](../audit/2026-09-13-document-revision-quality-status-false-positive.md)；[ADR](../adr/2026-09-13-document-version-boundary.md) | **运行时 blocker**：PG 未接线→404/重启丢失；overlay/freeform 保存缺口；PI 叙事报告待集成；见 [runtime remediation](../remediation/2026-09-13-document-revision-runtime-remediation.md)。行动表状态「待续」窄豁免已落地，待占槽重跑 UI-03 | `docgov` |
| 文档版本与修改认知 | 智能体版本边界、人工修订标记、任意版本比较、变更报告与负责人通知 | partial | [test 2026-09-13](../test-reports/2026-09-13-document-revision-management-test-report.md)；[运行时审计](../audit/2026-09-13-document-revision-runtime-404.md)；[PG ID 重映射](../audit/2026-09-13-document-revision-pg-id-remap.md)；[ADR](../adr/2026-09-13-document-version-boundary.md) | **运行时 blocker**：首次生成 PG ID 未同步计数器会误删 baseline（工程修复在 `fix/document-revision-pg-id-remap`，未 UI 验收）；overlay/freeform 保存缺口；见 [runtime remediation](../remediation/2026-09-13-document-revision-runtime-remediation.md) | `docgov` |
| 前端工作台 | 三栏 + 块文档 + SSE | partial | [test workbench](../test-reports/2026-09-08-three-column-workbench-and-block-document-test-report.md)；[现场专项审计](../audit/2026-09-13-conversation-intent-runtime-state.md) | 错误卡片/任务进度/文档 busy 状态刷新恢复与人工抽检待完成 | `web` |
| PI Runner / 配置链 | pi-agent + MiniMax 真实链路 | done | [test piagent](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)；[container-env](../test-reports/2026-09-13-container-env-configuration-test-report.md) | — | `pi-agent` |
| 三环境运维 | dev/test/main + 共享 KB | done | [PROJECT.md](../../PROJECT.md) §4；四环境 healthy | — | `infra` |