# P1R7 Source Owner Propagation 全局执行版

## 结论

本执行版只定义 P1R-7 Source Owner Propagation 的全局落地顺序、子阶段拆分、review gate、验证门槛和当前 AI 草稿处理规则；不实现代码，不提交，不推送，不推进 completed。

总执行主线：

```mermaid
flowchart TB
    GlobalReview["全局审阅版<br/>已双 review PASS"] --> GlobalPlan["全局执行版<br/>本文件，待双 review"]
    GlobalPlan --> Freeze["冻结全局合同<br/>用户可见 Events 不替代内部 Source/Authorization"]
    Freeze --> P7bPlan["P1R-7b 子计划<br/>AI terminal event"]
    P7bPlan --> P7bImpl["P1R-7b 实现<br/>AI outbox + worker + Events evidence"]
    P7bImpl --> NextDecision{"下一 owner 选择"}
    NextDecision --> P7c["P1R-7c Knowledge<br/>source status / projection notification"]
    NextDecision --> P7e["P1R-7e Account<br/>security / quota notification 备选"]
    P7c --> P7d["P1R-7d Market<br/>lifecycle / governance notification"]
    P7e --> P7d
    P7d --> P7f["P1R-7f Content<br/>用户可见 content/task notification"]
    P7f --> Approval["P1R-7 completed approval<br/>用户单独批准"]
```

硬边界：

1. 当前 AI outbox / V17 / docs 草稿在 P1R-7b 子计划修订并双 review PASS 前不得继续测试、提交、推送或作为完成证据。
2. 全局方案只定义“用户可见 Events 发布链路”，不替代正式 Source / Authorization 内部传播链路。
3. 每个 owner 的实现都必须 fresh implementer + fresh spec review + fresh quality / feasibility review。
4. completed approval 必须另起任务，不能由任何 dedicated gate 或 owner evidence 自动推出。

## 范围

本执行版负责：

- 固化 P1R-7 全局 source owner propagation 合同。
- 定义后续 P1R-7b/c/d/e/f 子计划顺序和拆分条件。
- 定义每个子计划必须继承的通用验证门槛。
- 定义当前 dirty AI 草稿如何进入 P1R-7b 子计划复审。

本执行版不负责：

- 不改业务代码、迁移、OpenAPI、scanner、coverage JSON/Markdown。
- 不运行 Maven / pnpm / Flyway / coverage scanner full verification。
- 不清理或回退当前 dirty/untracked baseline。
- 不把 `streamEvents`、P1R-7、Market 或任何 owner 标为 `completed`。

## 已验证事实

### 工作区与 review gate

1. 正确工作区为 `/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。
2. 当前分支为 `dev/1.0.0`，远端 `origin/dev/1.0.0` 已 ff-only 对齐。
3. 当前 HEAD 为 `fa29753 test(p1r): 收口 Events SSE 门禁`。
4. 当前 `git status --short --branch` 显示未提交 AI P1R-7b 草稿、V17 migration 草稿和 `docs/agent-specs/` 文档草稿。
5. 受保护文件定向 `git status --short` 无输出。
6. `docs/agent-specs/2026-06-06-P1R7SourceOwnerPropagation全局审阅版.md` 已通过 fresh spec review：
   - Kant / `019e9987-ca59-7370-bc49-9938eb93c70f` / PASS。
7. 同一全局审阅版已通过 fresh quality / feasibility review：
   - Hubble / `019e998b-2d82-7200-9289-c6c8dd37f744` / PASS。

### Coverage 与状态边界

1. 当前 coverage summary：
   - `totalOperations = 233`
   - `completedOperations = 100`
   - `needsVerificationOperations = 133`
   - `incompleteOperations = 0`
   - `genericPersistenceOperations = 0`
   - `ssePlaceholderOperations = 0`
2. Events 当前唯一 operation 为 `streamEvents GET /app-api/muse/events = dedicated / needs_verification`。
3. Market 当前 32 operations 均为 `dedicated / needs_verification`。
4. P1R-7a 收口文档明确：P1R-7a 未接入 source owner propagation，未运行 source owner publish tests。

### 全局设计事实

1. `CLAUDE.md` 将 Source 传播定为“事件驱动 + 各模块自治”。
2. `design-docs/架构-02-核心数据结构与双轨模型.md` 明确不需要独立 source 模块。
3. `design-docs/后端-03-关键流程实现与接口契约.md` 明确异步失败不得回滚已提交 Canonical。
4. P1R-7a 执行版已固定 source owner 本域 outbox + worker 调用 Events API；Events server 不反向依赖 source owner server。
5. Events owner 当前已有 `EventsPublishApi`、`EventsPublishReqDTO`、commandId/source tuple 幂等、payload sanitizer、accepted-only 可见查询和 SSE stream。

## 推断

1. 全局执行顺序应先冻结通用合同，再修订 P1R-7b AI 子计划；否则当前 AI 草稿可能继续携带单点设计里的事务和 dirty baseline 风险。
2. AI 仍是第一实现切片，因为它已有 terminal fact、ownerUserId、runtime job 和 focused test 基础。
3. Knowledge 适合作为第二个 source status propagation owner，但如果后续目标更偏用户通知而非来源状态传播，Account security event 可以作为更低风险 second slice 备选。
4. Market 应排在 AI/Knowledge 之后，因为 Market Account projection outbox 与 Events publish outbox 职责不同，直接复用风险较高。
5. Content 需要先界定内部领域事件与用户可见事件，否则容易把 BlockSavedEvent 等内部 trigger 过度推送到 SSE。

## 假设

1. 后续 owner 允许在本域新增 publish outbox 或等价状态表。
2. 后续 owner server 允许新增 `muse-module-events-api` 依赖。
3. 现有 Events OpenAPI 事件类型足够覆盖第一轮用户可见摘要；如果不够，应另起合同变更审批。
4. 当前 AI 草稿可以作为 P1R-7b 子计划的候选素材，但必须经过执行版修订、双 review 和本地验证后才能继续。

## 全局合同

### 依赖合同

1. Source owner server 可以依赖 `muse-module-events-api`。
2. Source owner server 不得依赖 `muse-module-events-server`。
3. `muse-module-events-server` 不得依赖 AI / Knowledge / Market / Member / Content server。
4. `muse-server` 可以装配 Events server 与各 source owner server。
5. 每个 owner 子计划必须包含 Maven dependency tree 验证命令。

### 发布 envelope 合同

每个 owner 子计划必须固定：

| 字段 | 要求 |
|---|---|
| `commandId` | 稳定短幂等键，长度 `<= 128`，推荐 `<owner>_evt:<sha256-32>` |
| `tenantId` | 必填，worker 必须恢复租户上下文 |
| `ownerUserId` | 必填，决定 SSE 可见性 |
| `sourceOwner` | 固定 owner 枚举 |
| `sourceType` | 固定业务事实类型 |
| `sourceId` | 本域事实稳定 id 或业务 id |
| `sourceRevision` | 本域事实版本；缺失时必须在子计划解释占位语义 |
| `eventType` | 只能使用 Events OpenAPI 已声明类型 |
| `resourceType/resourceId` | UI 定位对象，不参与替代 source tuple 幂等 |
| `payloadSummary` | OpenAPI allowlist 安全摘要 |
| `emittedAt` | 本域事实发生时间 |

### 用户可见事件判定

每个候选事件进入 SSE 前必须满足：

1. 用户需要实时感知。
2. 用户可据此采取动作或理解当前工作状态。
3. payload 能压缩为 OpenAPI 已声明 schema 的安全摘要。
4. 不需要暴露内部 source propagation、授权快照、worker、风控或 provider raw 细节。
5. 能提供稳定 source tuple、commandId、ownerUserId 和 emittedAt。

默认不进入 SSE：

1. 内部 followup trigger。
2. projection rebuild / worker heartbeat / retry job 状态。
3. 需要完整正文、知识资料、provider raw、授权详情或安全原始证据才能解释的事件。

### Outbox 合同

每个 owner 子计划必须包含：

1. `queued/running/retryable/published/dead_letter` 或等价状态。
2. `attempt_count` 或等价 claim 次数字段。
3. `max_attempt` 配置。
4. `next_retry_at`。
5. `claimed_at`。
6. `claim_expires_at`。
7. 固定退避策略。
8. claim 索引。
9. `FOR UPDATE SKIP LOCKED` 或等价原子领取机制。
10. `ON CONFLICT DO NOTHING` / `insertIgnore` + 回查，禁止把唯一约束异常作为正常幂等路径。
11. `published_event_id` / `published_sequence_no` 或等价回写字段。
12. `last_error_code` / `last_error_message` 安全错误摘要。
13. 中文日志，包含 owner、tenantId、ownerUserId、source tuple、outboxId、attempt、状态转换和错误摘要。

### Payload 合同

每个 owner 子计划必须列出：

1. 允许的 `eventType`。
2. 每个 `eventType` 的 payload allowlist。
3. 需要丢弃或归一化的敏感字段。
4. payload invalid 时的 fail-closed 状态和错误码。
5. rejected/blocked 后不得进入 SSE 可见查询的验证方式。

## 子阶段执行顺序

### Task 0：冻结总执行版

目标：

- 本文件完成 fresh spec review + fresh quality / feasibility review 双 PASS。
- 双 PASS 前不修订 P1R-7b 子计划，不继续 AI 草稿测试或实现。

验收：

- Reviewer 明确 PASS。
- 如有 FAIL，先修订本文件并重审。
- protected files 仍无改动。

### Task 1：P1R-7b 子计划修订

目标：

- 修订 `docs/agent-specs/2026-06-06-P1R7bSourceOwnerPropagation执行版.md`。
- 将它从“AI 单点执行版”改为“全局执行版下的 AI 第一切片子计划”。
- 明确当前 AI 草稿的处理策略：修订沿用、拆分提交或用户批准后清理。

必须补充：

1. 继承本执行版的依赖合同、envelope 合同、outbox 合同和 payload 合同。
2. 明确 AI 只发布用户可见 terminal `done/error` 摘要。
3. 明确 AI outbox 创建不得依赖捕获 `DuplicateKeyException` 作为正常幂等路径。
4. 明确 P1R-7b 只处理 AI，不处理 Knowledge / Market / Account / Content。
5. 明确 P1R-7b 不推进 completed。

Review gate：

- Fresh spec compliance review。
- Fresh quality / feasibility review。
- 双 PASS 前不得继续当前 AI 草稿实现。

### Task 2：P1R-7b AI 实现收口

目标：

- 在 P1R-7b 子计划双 PASS 后，处理当前 AI 草稿或由 fresh implementer 重做。
- 实现 AI terminal event -> AI publish outbox -> AI worker -> EventsPublishApi -> `muse_unified_event` -> SSE 可见证据。

必须验证：

1. AI focused tests。
2. Outbox mapper/service/worker tests。
3. Events publish accepted/rejected/blocked/duplicate tests。
4. SSE visible query tests。
5. Dependency tree：AI 只依赖 events-api，不依赖 events-server；Events server 不依赖 source owner server。
6. Migration SQL test 和 Flyway `_test`。
7. protected files 无改动。

Review gate：

- 每个实现 Task fresh implementer。
- 每个实现 Task fresh spec review。
- 每个实现 Task fresh quality / feasibility review。

### Task 3：第二 owner 选择决策

目标：

- 在 AI 第一切片通过后，只读评估第二 owner 是 Knowledge source status 还是 Account security notification。

选择规则：

1. 如果目标是 source status propagation 证据优先，选择 Knowledge。
2. 如果目标是用户可见通知链路低风险扩展优先，选择 Account security event。
3. 不因 Market 有 outbox 命名而优先选择 Market。
4. Content 进入前必须先冻结内部事件与用户可见事件判定。
5. 如果 Account security event 先于 Market 落地，阶段编号仍保留 P1R-7e，不重命名 P1R-7d，避免阶段编号反向改写历史计划。

输出：

- `docs/agent-specs/YYYY-MM-DD-P1R7c...审阅版.md`。
- fresh spec review + fresh quality review。

### Task 4：P1R-7c / P1R-7e 子计划与实现

目标：

- 按 Task 3 决策进入 Knowledge 或 Account。
- 每个 owner 都必须先产出单独审阅版，再产出单独执行版；审阅版和执行版各自 fresh spec review + fresh quality / feasibility review 双 PASS 后，才允许进入该 owner 实现。

必须继承：

- 本执行版的全局合同。
- P1R-7b 的复用经验，但不得复制 AI payload / 状态机细节到不匹配 owner。

### Task 5：Market 与 Content 后续切片

目标：

- Market 先拆清 Account projection outbox 与 Events publish outbox 职责。
- Content 先拆清内部 followup trigger 与用户可见 Events notification。

进入条件：

- 至少已有两个 owner 的 Events publish 链路通过验证，或者用户明确要求优先 Market / Content。

### Task 6：P1R-7 completed approval 预检

目标：

- 汇总 Events owner + 各 source owner evidence。
- 只读判断是否具备 completed approval 申请条件。

必须包含：

1. coverage 当前状态。
2. 所有 owner 的测试证据。
3. HTTP / SSE / DB / Flyway / dependency / protected file evidence。
4. 未覆盖 owner 和未覆盖失败路径清单。

边界：

- 该 task 只做预检，不自动标 completed。
- completed approval 必须用户单独批准。

## 验证命令模板

每个 owner 子计划必须按实际模块填充以下模板：

```bash
cd /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
git status --short --branch
git status --short -- docs/api-contracts/market/openapi.yaml docs/api-contracts/ai/openapi.yaml docs/api-contracts/knowledge/openapi.yaml docs/api-contracts/events/openapi.yaml muse-cloud/scripts/p1r-audit-api-coverage.py docs/superpowers/reports/p1r-api-coverage.json docs/superpowers/reports/p1r-api-coverage.md
```

```bash
cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl <owner-module> -am -Dtest=<focused-tests> -Dsurefire.failIfNoSpecifiedTests=false test
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl muse-server -am -Dtest=<p1r-gate-tests> -Dsurefire.failIfNoSpecifiedTests=false test
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl <owner-module> -am dependency:tree
```

Flyway `_test` 必须使用独立测试库，且必须显式清空 JVM 代理参数或证明代理不会影响内网 PostgreSQL 连接。

## 当前 dirty baseline 处理规则

当前未提交 AI P1R-7b 草稿包括：

- AI module POM、runtime projection service、job service 与相关测试改动。
- AI publish outbox service / mapper / DO 新文件。
- `muse-cloud/sql/muse/V17__extend_ai_events_publish_outbox.sql`。
- P1R-7b migration SQL/Flyway test 草稿。
- `docs/agent-specs/` 文档草稿。

处理规则：

1. 本执行版双 PASS 前，不继续测试或实现这些草稿。
2. P1R-7b 子计划修订时必须显式决定这些草稿是“修订沿用”还是“废弃重做”。
3. 如果选择修订沿用，必须补证据证明草稿已符合本执行版全局合同。
4. 如果选择废弃重做，必须先征得用户明确批准后才能清理相关 dirty/untracked 文件。
5. 任何情况下不得回退用户或其他代理的无关改动。

## 完成条件

本总执行版完成条件：

1. 本文件存在且内容覆盖全局合同、子阶段顺序、验证模板、dirty baseline 处理规则。
2. Fresh spec compliance review PASS。
3. Fresh quality / feasibility review PASS。
4. protected files 无改动。
5. 输出下一步：修订 P1R-7b 子计划，而不是直接继续 AI 实现。
6. 本轮 reviewer 只读审查文档，不运行 full verification；review PASS 不能解释为实现验证 PASS。

P1R-7 全链路完成条件不在本文件完成范围内；它必须在 P1R-7 completed approval 任务中单独判断。

## 回滚策略

本执行版只新增文档；若 review FAIL：

1. 只修订本文件和必要的 `.agent` 说明。
2. 不回退代码草稿。
3. 不修改 protected files。
4. 不运行 full verification。

若后续实现阶段发现全局合同错误：

1. 停止对应 owner 实现。
2. 回到全局审阅版 / 执行版修订。
3. 重新 fresh spec review + fresh quality review。