docs(test): record E0A producer-contract gate and checkpoint ADR

Archive isolated-PG evidence, 7-day read-only inventory, and the decision to bootstrap consumers from the first safe event instead of gap-waiting. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 08:52:59 +00:00
parent 0f2057765a
commit 0f2f8d30e5
11 changed files with 1415 additions and 5 deletions
@@ -0,0 +1,30 @@
+---
+title: "事件连续性采用 consumer checkpoint + 首事件 bootstrap"
+status: accepted
+created: 2026-09-15
+updated: 2026-09-15
+---
+
+# ADR：事件连续性采用 consumer checkpoint + 首事件 bootstrap
+
+## 状态
+
+接受（E0A）。在独立 FAV 审计或明确的无缺口 event sequence 迁移完成前不得改为 gap blocking。
+
+## 背景
+
+`event_envelopes` 已有 `UNIQUE (aggregate_type, aggregate_id, aggregate_version)`。受控文档的首次持久事件常常从较高 `aggregate_version`（账本 version_no）开始，中间版本从未发事件。若把领域版本号当成无缺口事件序号并在缺号时等待，会永久阻塞 delivery。MemoryBus 的 `TestGapDoesNotSkipVersion` 只是 characterization，不得搬到 PostgreSQL dispatcher。
+
+## 决策
+
+1. Track E 选择 **consumer checkpoint + 首事件 bootstrap**。
+2. 每个 `(consumer, aggregate_type, aggregate_id)` 记录已成功处理的 `event_id` 与可选 `aggregate_version`。该 aggregate 上的第一件 **safe** 事件即为 bootstrap，不要求 version=1。
+3. 同一版本多个不同类型事件：当前唯一约束禁止。E0A 审计后保持该约束；需要同版本多事件时另立 additive 迁移，把序号改到独立 `event_seq`，不在本 ADR 启用。
+4. **禁止** 在 dispatcher 启用 gap wait / `ErrGapWait` 阻塞，直到另有 ADR 选择独立无缺口 event sequence 且完成回填。
+5. 未知 schema、project 0、错误 environment、未知 consumer 的记录进入 inventory，不得 live claim。
+
+## 后果
+
+- E0B checkpoint 表随 dispatcher migration 增加。
+- Projection 以 `document_id + source_snapshot_id + digest` no-replace，不依赖连续 version。
+- poison 事件 quarantine 后不静默跳号；其他 aggregate 继续。
@@ -5,7 +5,7 @@

 ## 焦点

-1. **TRACK-E**: [持久事件交付](./short-term/2026-09-15-durable-event-track-e.md)（方案已审阅；下一开工为 E0A 生产者/契约/历史数据门；dispatcher 保持 off）
+1. **TRACK-E**: [持久事件交付](./short-term/2026-09-15-durable-event-track-e.md)（E0A PASS，见 [E0A 报告](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md)；下一开工为 E0B PG dispatcher，默认 mode=off）
 2. **CHAT-INTENT**: [对话意图运行时状态](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)（双标签 busy 已签：项目 **6275** / `DOC_BUSY` 单 run；不删 `sess-p143-u9` 探针）
 3. **CHAT**: [对话历史刷新活验已补](../test-reports/2026-09-13-chat-history-refresh-test-report.md)（项目 6252 闲聊刷新同集 + guest 403；编制任务链仍开放）

@@ -58,6 +58,7 @@
 | implementer_cursor | workflow-plan-409-frozen-and-optional-duties | fix/workflow-plan-409-frozen-and-optional-duties | - | workflow | done |
 | implementer_cursor | governance-action-level-authz | fix/governance-action-level-authz | - | workflow | done |
 | Cursor | leftover-branch-cleanup | chore/leftover-branch-cleanup | - | ops | done |
+| Cursor | event-e0a-production-scope-contract | fix/event-production-scope-contract | - | events | done |

 > 新任务开始前登记。`branch` 必须为 `feature/<slug>` 或 `fix/<slug>`，**禁止** `dev` / `test` / `main`。同一 `mutex` 同时仅一个 `in_progress`。

@@ -69,7 +70,7 @@

 | holder | phase | since | scope | queue |
 |--------|-------|-------|-------|-------|
-| idle | idle | 2026-09-15 | Phase 2 方案文档已合入；下一槽位留给 E0A | - |
+| Cursor | merging | 2026-09-15 | E0A 生产者/契约/历史数据门；dispatcher 保持 off | - |

 **phase**: `idle` | `merging` | `smoke` | `e2e`

@@ -1,6 +1,6 @@
 ---
 title: "Track E 持久事件交付"
-status: planned
+status: in_progress
 created: 2026-09-15
 updated: 2026-09-15
 owner: TBD
@@ -28,7 +28,7 @@ mutex: events

 ## 步骤

-1. [ ] E0A 单独建 short-term/分支，dispatcher 保持 off。
+1. [x] E0A 单独建 short-term/分支，dispatcher 保持 off。
 2. [ ] E0A 报告通过后再认领 E0B。
 3. [ ] 依次交付 E1A notify、E1B workflow advance、E1C projection；每步独立 go/no-go。
 4. [ ] 一个兼容发布窗口后 contract 删除闭包 API。
@@ -0,0 +1,49 @@
+---
+title: "E0A 事件生产、契约与历史数据门"
+status: done
+created: 2026-09-15
+updated: 2026-09-15
+owner: Cursor
+branch: fix/event-production-scope-contract
+worktree: "-"
+mutex: events
+---
+
+# E0A 事件生产、契约与历史数据门
+
+## 目标
+
+组合根注入唯一 `docflow.Commands`；candidate-ready、downstream-impact、approved 三条链在同一 UoW 写 envelope/delivery；缺 env/project fail closed；FAV 不写入；allowlist 与 runtime registry parity；历史 inventory 分类且不删数据；dispatcher 保持 off。
+
+## 范围
+
+- D3 生产入口与作用域
+- D10 既有 event allowlist 补全与 registry parity
+- D11 inventory、sequence ADR、repair/quarantine/expire、replay 骨架、service principal 表
+
+## 非目标
+
+- 不实现/启动 PG dispatcher
+- 不激活 FAV，不写 staging/artifact/publication
+- 不删除历史事件
+- 不开始 Track S/P
+
+## 步骤
+
+1. [x] 从最新 `dev` 开 `fix/event-production-scope-contract` 并登记 CURRENT
+2. [x] 唯一 Commands、三条链同 UoW、FAV 隔离
+3. [x] allowlist + registry parity + 动态 FAV 注册失败
+4. [x] inventory/repair/replay/principal additive schema 与用例
+5. [x] 连续性模型 ADR；gap blocking 关闭
+6. [x] 隔离库 PG 证据与 test-report
+
+## 验收标准
+
+- [x] 见 [E0A 测试报告](../../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md)
+
+## 相关链接
+
+- Remediation: [../../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md](../../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)
+- Track E: [./2026-09-15-durable-event-track-e.md](./2026-09-15-durable-event-track-e.md)
+- Report: [../../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md](../../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md)
+- ADR: [../../adr/2026-09-15-event-consumer-checkpoint.md](../../adr/2026-09-15-event-consumer-checkpoint.md)
@@ -27,7 +27,7 @@
 | 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` |
 | CI / E2E | PG 集成 + 真实 PI E2E | partial | [gap-matrix BUG-08](../remediation/gap-matrix.md)；[test pg-ci](../test-reports/2026-09-12-pg-ci-soak-e2e-test-report.md)；[运行时 UI Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md) | CI `TEST_DATABASE_URL` 隔离库仍缺；文档运行时真实 UI 已按 UI_PHASE 分文件且 post-restart 断言最终 A1 正文。`-race` 全包并行 TempDir flake 为基建残留 | `ci` |
-| 模块解耦与可靠事件 | 文档可靠性纵向试点、PG 持久事件交付与选择性模块化 | partial | [架构](../system-design/2026-09-14-module-decoupling-architecture.md)；[ADR](../adr/2026-09-14-modular-monolith-decoupling.md)；[Phase 1](../remediation/2026-09-14-module-decoupling-refactor-plan.md)；[Phase 2 审阅](../audit/2026-09-15-module-decoupling-phase2-plan-review.md)；[Phase 2 修订计划](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)；[U11–U12 报告](../test-reports/2026-09-15-app-composition-u11-u12-test-report.md) | U5–U12 已合入 `dev@bf59cce`。PG dispatcher/闭包迁移仍未实施；Track E 是当前可靠性缺口。Track S 与 HTTP/PI 协议分别规划，不阻塞 Track E；FAV 保持独立审计 | `architecture-docs` |
+| 模块解耦与可靠事件 | 文档可靠性纵向试点、PG 持久事件交付与选择性模块化 | partial | [架构](../system-design/2026-09-14-module-decoupling-architecture.md)；[ADR](../adr/2026-09-14-modular-monolith-decoupling.md)；[Phase 1](../remediation/2026-09-14-module-decoupling-refactor-plan.md)；[Phase 2 审阅](../audit/2026-09-15-module-decoupling-phase2-plan-review.md)；[Phase 2 修订计划](../remediation/2026-09-15-module-decoupling-ipc-phase2-remediation-plan.md)；[U11–U12 报告](../test-reports/2026-09-15-app-composition-u11-u12-test-report.md)；[E0A 报告](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md) | U5–U12 已合入 `dev@bf59cce`。E0A 生产者/契约/inventory 已过隔离库门；PG dispatcher 仍 off。Track S 与 HTTP/PI 协议分别规划，不阻塞 Track E；FAV 保持独立审计 | `architecture-docs` |

 ---

@@ -0,0 +1,108 @@
+# E0A 事件生产、契约与历史数据门 测试报告
+
+## 一、 测试背景 (Background)
+
+Phase 2 Track E 要求 notify / workflow advance / projection 达到「至少一次投递 + 恰好一个可见结果」。开工前生产入口仍临时构造 `docflow.Commands`，硬编码 `Environment:"dev"` / `ProjectID:0`，并把 `"fav"` 写进 delivery。dispatcher 必须保持 off，直到本报告的生产者/契约/历史数据门通过。
+
+## 二、 测试目标 (Test Objectives)
+
+- 组合根持有唯一 `*docflow.Commands`；HTTP 适配器不得字面量构造。
+- `document.agent_candidate_ready`、`document.downstream_impact_detected`、`document.approved` 在领域提交同一 UoW 写 envelope + 目标 delivery。
+- 缺 environment/project **fail closed** 并回滚领域行。
+- FAV 生产链隔离：无 fav delivery、无 staging/artifact/publication。
+- 静态 allowlist 与 runtime registry 字节级子集；动态 FAV 注册失败。
+- 历史 inventory 只分类、不删行；repair 必须带 old/new digest。
+- 连续性模型书面结论：checkpoint + 首事件 bootstrap，**禁止**把 MemoryBus gap wait 搬到 PG。
+- dispatcher 保持 off。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|----|-----|
+| OS | Linux 7.0.0-31-generic |
+| Go | go1.27.1 linux/amd64 |
+| 分支 | `fix/event-production-scope-contract`（从 Wave 0 后本地 `dev@3d2a1de` 检出） |
+| Schema | **39**（`00039_2026-09-15-event-inventory-and-principals.sql`） |
+| PostgreSQL | 隔离库 `agent_rel_e0a`（admin 连 `shuimu-system-pg-test:5434/postgres` 自建）；测完 `DROP`；禁止 `agent_system_dev/test/main` |
+| 历史流量 | **只读**查询 `shuimu-context-pg-dev:5433/agent_system_dev`，不对该库跑测试、不写入 |
+| 项目 143 | **只读** |
+| dispatcher | **off**（本波未实现/未启动 `cmd/events`） |
+| 证据 | `.doc/test-reports/assets/2026-09-15-event-e0a-production-scope-contract/` |
+
+## 四、 预期结果 (Expected Results)
+
+| 链 | 判定 |
+|----|------|
+| Approve | 同一事务可见 `document_records.current_state=approved` + `document.approved` envelope + `workflow_advance`/`notify` delivery；无 `fav` |
+| Materialize/Commit | `document.agent_candidate_ready` 和/或 `document.agent_version_committed`；有 impact 时 `document.downstream_impact_detected` 使用独立 `aggregate_type=document_impact` |
+| 缺 env | 领域行回滚到 `approving`，envelope/delivery 为 0 |
+| FAV | staging/artifact/fav delivery = 0 |
+| Registry | 未登记事件、动态 `fav` Register 失败 |
+| Unique `(aggregate_type, aggregate_id, aggregate_version)` | **保留**；同账本版本的多事件用不同 aggregate_type/id，不启用 `event_seq` |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 单元 / archtest
+
+- **测试输入**: `unset TEST_DATABASE_URL; go test -short -count=1 ./internal/events ./internal/app/docflow ./internal/app ./internal/bizdev ./internal/archtest`
+- **实际输出**: 全部 PASS。`TestAssertLiveConsumersRejectsFAV`、`TestRegistryParityWithYAML`、`TestEmitFailClosedMissingProject`、`TestFixtureInventoryThirtyPerType` 绿。
+- **评价判定**: **PASS**
+- **性能与耗时**: 亚秒（archtest ~0.12s）
+
+### 5.2 全仓 short
+
+- **测试输入**: `unset TEST_DATABASE_URL; go test -short -count=1 ./...`；`./scripts/arch-check.sh --mode block`
+- **实际输出**: 全包 PASS（`internal/server` 10.042s）；`arch-check block: production gate passed`
+- **评价判定**: **PASS**
+- **性能与耗时**: 约 12s
+
+### 5.3 隔离库 PG 三条链 + fail closed
+
+- **测试输入**: `TEST_DATABASE_URL=postgres://app:***@127.0.0.1:5434/agent_rel_e0a?sslmode=disable`；`go test -count=1 -v ./internal/app/docflow -run TestE0A_`
+- **实际输出**（摘录自 `assets/.../pg-test.txt`）:
+
+```
+=== RUN   TestE0A_ThreeChainsSameTxAndFailClosed_PG
+2026/09/15 08:49:02 goose: no migrations to run. current version: 39
+--- PASS: TestE0A_ThreeChainsSameTxAndFailClosed_PG (0.03s)
+=== RUN   TestE0A_InventoryClassifiesDirtyScope_PG
+--- PASS: TestE0A_InventoryClassifiesDirtyScope_PG (0.00s)
+PASS
+```
+
+goose 版本 39；FAV `artifact_payload_staging` / `final_artifacts` / fav delivery 计数在隔离库为 0。测完 `DROP DATABASE agent_rel_e0a`。
+- **评价判定**: **PASS**
+- **性能与耗时**: 含 goose 约 0.33s（首次）/ 0.04s（已迁）
+
+### 5.4 历史 inventory（只读 + fixture）
+
+- **测试输入**: 只读 `agent_system_dev` 近 7 天 `event_envelopes`；fixture 每 event type 30 条（`TestFixtureInventoryThirtyPerType`）。
+- **实际输出**: 近 7 天有效流量仅 `taskrun.completed=2`；文档三类事件为 0，因此 shadow 样本 N 使用确定性 fixture（每类型 30）。现存 delivery：`fav pending=2`、`projection pending=2`（均挂在 `taskrun.completed`）。按契约 `taskrun.completed` 合法 consumer 仅为 `notify`，故 fav/projection 分类为 **quarantine**（未知/禁用 consumer），**不得** live claim。`dirty_scope=0`。审批结论：quarantine 历史 fav/projection delivery；不删 envelope。
+- **评价判定**: **PASS**（低流量走 fixture；历史脏 consumer 已分类）
+- **性能与耗时**: 查询亚秒
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+| 命令 | 结果 |
+|------|------|
+| `unset TEST_DATABASE_URL; go test -short -count=1 ./...` | PASS |
+| `./scripts/arch-check.sh --mode block` | PASS |
+| 隔离库 `go test ./internal/app/docflow -run TestE0A_` | PASS（schema 39） |
+| dispatcher / `cmd/events` | **未启动**（E0A 退出门） |
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+E0A **PASS**，可以进入 E0B。dispatcher 仍 off。Goose **00039** 已被 E0A inventory/principal 占用，E0B dispatcher 迁移使用 **00040**。
+
+### 五个开放问题的书面结论
+
+1. **Projection owner**：最终文件投影属主仍是 `docrevision`（`ProjectOutputMarkdown` / workspace `output.md`）。no-replace 提交接口约定为未来表 `document_projection_markers(document_id, source_snapshot_id, digest)` + expected head；**E1C** 落地，本波不建表。
+2. **连续性模型**：选择 **consumer checkpoint + 首事件 bootstrap**。ADR：`.doc/adr/2026-09-15-event-consumer-checkpoint.md`。禁止把 `TestGapDoesNotSkipVersion` 搬到 PG；gap blocking 关闭。
+3. **唯一约束**：保留 `UNIQUE (aggregate_type, aggregate_id, aggregate_version)`。同账本版本的 approved / impact / report 使用不同 `aggregate_type`（`document_approval` / `document_impact` / `document_report` / `document_candidate`）。需要同类型同版本多事件时另立 `event_seq`，本波不启用。
+4. **7 天流量 / N / 连接预算**：文档事件近 7 天为 0，shadow 样本用 fixture N=30/type。Worker 连接预算 E0A 为 **0**（无 dispatcher 进程）；E0B 默认 batch 50 / lease 30s，独立 `cmd/events` 连接池有界。
+5. **错误 scope/schema/consumer**：隔离库 fixture 将缺 env/project、未知事件、禁用 fav 标为 quarantine。dev 只读：2 条 `taskrun.completed` envelope 干净 scope；2 条 fav + 2 条 projection delivery **quarantine**，批准不重试、不删除。
+
+### 后续
+
+- E0B：`feature/events-dispatcher-pg`，Goose 00040，原子 claim + attempt + fencing；默认 mode=off。
+- 不激活 FAV；不把 Track S/P 写成 E0A 完成。
@@ -0,0 +1,5 @@
+unset TEST_DATABASE_URL; go test -short -count=1 ./...
+# 2026-09-15 E0A
+# go version go1.27.1 linux/amd64
+# EXIT 0 — all packages PASS (internal/server ~10s)
+# arch-check --mode block PASS
@@ -0,0 +1,17 @@
+=== read-only 7-day inventory on agent_system_dev (not used as test DB) ===
+    event_name     | count 
+-------------------+-------
+ taskrun.completed |     2
+(1 row)
+
+  consumer  | status  | count 
+------------+---------+-------
+ fav        | pending |     2
+ projection | pending |     2
+(2 rows)
+
+ dirty_scope | total 
+-------------+-------
+           0 |     2
+(1 row)
+
@@ -0,0 +1,7 @@
+=== RUN   TestE0A_ThreeChainsSameTxAndFailClosed_PG
+2026/09/15 08:49:02 goose: no migrations to run. current version: 39
+--- PASS: TestE0A_ThreeChainsSameTxAndFailClosed_PG (0.03s)
+=== RUN   TestE0A_InventoryClassifiesDirtyScope_PG
+--- PASS: TestE0A_InventoryClassifiesDirtyScope_PG (0.00s)
+PASS
+ok  	chat-agent-system/internal/app/docflow	0.039s
@@ -0,0 +1,134 @@
+[
+  {
+    "event_name": "document.agent_candidate_ready",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "docrevision",
+      "app/docflow",
+      "events"
+    ],
+    "consumers": [
+      "notify"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "candidate_id",
+      "risk"
+    ]
+  },
+  {
+    "event_name": "document.agent_version_committed",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "docrevision",
+      "app/docflow",
+      "events"
+    ],
+    "consumers": [
+      "projection",
+      "notify"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "version_no"
+    ]
+  },
+  {
+    "event_name": "document.downstream_impact_detected",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "docrevision",
+      "app/docflow",
+      "events"
+    ],
+    "consumers": [
+      "notify"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "impacted_doc_id",
+      "version_no"
+    ]
+  },
+  {
+    "event_name": "document.change_report_degraded",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "docrevision",
+      "app/docflow",
+      "events"
+    ],
+    "consumers": [
+      "notify"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "report_id"
+    ]
+  },
+  {
+    "event_name": "document.approved",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "app/docflow",
+      "events"
+    ],
+    "consumers": [
+      "workflow_advance",
+      "notify"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "project_id",
+      "task_key"
+    ]
+  },
+  {
+    "event_name": "taskrun.completed",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "taskrun"
+    ],
+    "consumers": [
+      "notify"
+    ],
+    "payload_fields": [
+      "run_id"
+    ]
+  },
+  {
+    "event_name": "taskrun.cancelled",
+    "schema_version": 1,
+    "enabled": true,
+    "producers": [
+      "taskrun"
+    ],
+    "consumers": [
+      "notify"
+    ],
+    "payload_fields": [
+      "run_id"
+    ]
+  },
+  {
+    "event_name": "fav.artifact_staged",
+    "schema_version": 1,
+    "enabled": false,
+    "producers": [
+      "app/docflow"
+    ],
+    "consumers": [
+      "fav"
+    ],
+    "payload_fields": [
+      "doc_id",
+      "snapshot_id"
+    ]
+  }
+]