oh-my-muse/docs/agent-specs/2026-06-08-P1R7fContentSourceOwnerPropagation审阅版.md

P1R7f Content Source Owner Propagation 审阅版

结论

推荐进入 P1R-7f，但第一切片只覆盖 Content 用户保存 Block 后形成的 canonical source attribution 事实，不覆盖全部 Content 写命令、导入、解析、导出、planning、meta projection 或 completed approval。

推荐方案：

1. 选择 ContentAppServiceImpl.saveBlock 成功后写入的 muse_content_block_source_attribution(source_status=active) 作为 Content 第一批 source fact。
2. 新增 Content 本域 Events publish outbox / worker，调用 EventsPublishApi，发布 Events 已声明的 notification/source_status_change。
3. 不把 Block 正文、sourceSnapshot 原始对象、auditReason、authorizationSnapshotId 或 lineage payload 放入 Events payload。
4. 不修改 OpenAPI、scanner 或 coverage report；不推进 Content / Events / P1R-7 completed。

flowchart LR
    Save["App saveBlock command"] --> Block["muse_content_block<br/>content + revision"]
    Save --> Attr["muse_content_block_source_attribution<br/>blockId + revision + active"]
    Attr --> Outbox["Content events publish outbox<br/>queued / running / retryable / published / dead_letter"]
    Outbox --> Worker["Content worker<br/>claim + retry + stale-claim guard"]
    Worker --> Api["EventsPublishApi<br/>events-api only"]
    Api --> Unified[("muse_unified_event<br/>notification / source_status_change")]
    Unified --> SSE["/app-api/muse/events<br/>work owner visible"]

本审阅版只冻结目标、非目标、取舍、风险和验收标准。执行版、实现和提交必须在本审阅版 fresh spec review + fresh quality / feasibility review 双 PASS 后再继续。

Review Gate

P1R-7f 审阅版已通过 fresh review：

• Harvey spec / scope review：PASS，无 P0/P1/P2；已验证本审阅版严格停留在 Content saveBlock -> block source attribution -> Events notification 第一切片，没有把 completed、OpenAPI、coverage 或全部 Content 写命令混入。
• Chandrasekhar quality / feasibility review：PASS，无 P0/P1/P2；已验证 saveBlock -> muse_content_block_source_attribution(source_status=active) -> Content outbox -> EventsPublishApi -> muse_unified_event -> SSE 路径可落地，并确认 Content 不应误用 chunk，执行版必须加入防误用 chunk 的测试或静态 gate。

Halley quality reviewer 长时间超时未返回，已丢弃，不计入 review gate。

审阅版双 PASS 只允许进入执行版编写，不代表 P1R-7f 实现完成，也不代表 Content / Events / P1R-7 completed。执行版完成后仍必须派发 fresh execution spec review + fresh execution quality / feasibility review；执行版双 PASS 前不得实现代码、提交、push 或推进 completed。

已验证事实

工作区与状态

• 正确 worktree：/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0。
• 分支：dev/1.0.0。
• 当前 HEAD：68cee5d test(p1r): 收口 Account 事件传播真实链路门禁。
• 当前分支与 origin/dev/1.0.0 对齐。
• git pull --ff-only origin dev/1.0.0 返回 Already up to date.。
• 当前 coverage summary：
  • completedOperations=100
  • needsVerificationOperations=133
  • incompleteOperations=0
  • genericPersistenceOperations=0
  • ssePlaceholderOperations=0
• Content 51 operations 当前均为 dedicated / needs_verification。
• 受保护文件 staged / unstaged diff 为空：
  • docs/api-contracts/account/openapi.yaml
  • 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

全局 P1R-7 边界

• P1R-7a 到 P1R-7e 已分别覆盖 Events SSE、AI、Knowledge、Market、Account source owner propagation evidence。
• P1R-7b / 7c / 7d / 7e 均只把对应真实链路推进到 needs_verification evidence，不代表 Events / P1R-7 / 对应业务域 completed。
• P1R-7 全局审阅版把 P1R-7f 定义为 Content canonical change / block saved / export task event propagation，状态口径仍是只推进 needs_verification 证据。
• P1R-7 completed approval 预检明确：如果 Account / Content 仍是硬前置，则应继续 P1R-7e Account 与 P1R-7f Content，而不是直接 completed。Account 已在 P1R-7e 收口并推送，因此 Content 是剩余 owner 切片。

Events 可复用合同

• EventsPublishReqDTO 已包含 commandId、tenantId、ownerUserId、sourceOwner、sourceType、sourceId、sourceRevision、eventType、resourceType、resourceId、payloadSummary、emittedAt。
• EventsPublishServiceImpl 先按 commandId 回放，再按 source tuple 回放。
• docs/api-contracts/events/openapi.yaml 已声明 notification 事件，SSENotificationEvent.data.type 允许 source_status_change。
• EventsPublishServiceImpl 与 EventsStreamServiceImpl 均允许 notification subtype source_status_change。
• Events 当前没有 block_saved notification subtype；本阶段不得新增 subtype 或修改 Events OpenAPI。
• SSEChunkEvent 语义是 AI 生成文本片段，要求 content/sequenceNo。Content block saved 不应使用 chunk，否则会泄露正文或伪造 AI chunk 语义。

Content 当前事实模型

• Content owner 位于 muse-module-content/muse-module-content-server。
• muse-module-content-server/pom.xml 当前没有依赖 muse-module-events-api，也没有依赖 muse-module-events-server。
• 最新 migration 当前是 V20__extend_account_events_publish_outbox.sql；若 P1R-7f 进入实现且 live 文件列表不变，下一 migration 应为 V21。
• ContentAppServiceImpl.saveBlock 在同一事务内：
  • 用 ContentCommandService.reserveCommand 对 commandId 做幂等预占。
  • 通过 requireOwnedBlock(userId, workId, blockId) 校验作品 owner。
  • 校验 Block expectedRevision。
  • 更新 muse_content_block.content_text / word_count / revision。
  • 写入 muse_content_block_source_attribution，其中 workId、blockId、revision、sourceType、sourceObjectId、sourceVersion、authorizationSnapshotId、sourceStatus=active。
  • 调用 ContentAuditService.recordSucceededWithAudit 写入 command result snapshot 与 audit 摘要。
• muse_content_block_source_attribution 有独立自增 id，并有唯一约束 (tenant_id, block_id, revision)。
• WorkDO.ownerUserId 是作品 owner；saveBlock 的 userId 经 owner guard 后与该 owner 一致。
• BlockSaveReqVO 要求 commandId、content、expectedRevision 和 sourceSnapshot。

推断

• P1R-7f 第一切片应选择 saveBlock，因为它是 Content 自有 canonical change，具备 owner、workId、blockId、revision、commandId、requestHash、source attribution 和审计链路。
• muse_content_block_source_attribution 比 muse_content_block 更适合作为第一批 source fact：它表达“该 Block revision 的来源状态 active”，可以自然映射到 source_status_change，并避免把正文变化伪装成 AI chunk。
• 复用 notification/source_status_change 是当前不改 OpenAPI 下的最小可行方案；如果未来产品需要明确的 block_saved subtype，应另起 Events OpenAPI 合同审批。
• 不应把 Content 全部写命令放进 P1R-7f 第一切片。create_block、delete_block、splitBlock、mergeBlocks、导入、解析、导出、planning、meta projection 都有不同语义和不同敏感 payload 边界，混入会扩大 blast radius。
• muse_content_block_source_attribution 是 source fact，不应直接兼任 publish outbox。它没有 claim lease、attempt、retry、published event、dead_letter、last_error 等发布补偿语义。

假设

• P1R-7f 允许在 Content owner 内新增独立 Events publish outbox 表或等价状态表。
• P1R-7f 允许 muse-module-content-server 新增对 muse-module-events-api 的直接依赖，但不允许依赖 muse-module-events-server。
• Content block save notification 的 SSE owner 是作品 owner，即 WorkDO.ownerUserId / 当前 app userId。
• source_status_change 可以表达 Content block source attribution 从用户保存命令进入 active 状态的用户可见摘要。

目标

1. 证明 Content source owner 的真实 Block 保存事实可以通过 Content 本域 publish outbox / worker 发布到 Events。
2. 让作品 owner 可以通过统一 SSE 看到自己的 Block 来源状态变更摘要。
3. 建立 Content 与 Events 的单向依赖证据：Content server 依赖 events-api，不依赖 events-server；Events server 不反向依赖 Content server。
4. 为后续 Content create/delete/split/merge/import/export/planning/meta projection 等事件扩展保留清晰边界。

非目标

1. 不把 Content 51 operations 从 needs_verification 推进到 completed。
2. 不把 Events streamEvents 或总 P1R-7 推进到 completed。
3. 不修改 Content / Events OpenAPI。
4. 不修改 coverage scanner 或 coverage report。
5. 不发布 Block 正文、完整 sourceSnapshot、lineage payload、license restriction、authorizationSnapshotId、auditReason、requestHash、command result snapshot 或错误堆栈。
6. 不覆盖 create_block、delete_block、splitBlock、mergeBlocks、mergeBlockSuggestion、import/parse/export、planning、meta projection、admin risk action。
7. 不让 Events server 查询 Content 表。
8. 不把 SSE chunk 用作 Content block save 事件。

推荐方案

事件选择

第一批只允许：

Content source fact	触发入口	Events eventType	notification type	SSE owner
muse_content_block_source_attribution(source_status=active)	ContentAppServiceImpl.saveBlock	notification	source_status_change	WorkDO.ownerUserId

暂不选择：

候选事实	暂不选择原因
muse_content_block 正文变化	直接以正文变化为 SSE payload 有泄露风险；应通过 source attribution 摘要表达
create_block	创建类命令首次执行前 targetId 为空，source tuple 和 replay 边界需要单独冻结
delete_block	删除前 source attribution 是 deleted snapshot，用户可见语义与保存不同
splitBlock / mergeBlocks	一次命令可能影响多个 Block 和章节 revision，第一切片不扩大结构编辑语义
import / parse / export task	异步任务状态和文件凭证边界不同，容易误暴露内部任务或下载信息
planning / meta projection	更接近 AI / Meta 协作投影，需单独定义用户可见摘要
admin risk action	属于治理动作，已有 Market governance 类似模式但 Content 侧需单独审阅

Payload allowlist

第一批 payload 只允许：

{
  "type": "source_status_change",
  "message": "内容来源状态已更新",
  "resourceRef": {
    "resourceType": "content_block",
    "resourceId": 8001
  },
  "timestamp": "2026-06-08T12:00:00"
}

执行版可以把 message 收窄为安全固定枚举，例如：

• 内容来源状态已更新
• Block 来源状态已更新

不得把以下字段放入 Events payload：

• Block 正文 contentText
• 请求正文 content
• sourceSnapshot 原始对象
• sourceObjectId
• authorizationSnapshotId
• lineagePayload
• licenseRestrictionSnapshot
• auditReason
• requestHash
• resultSnapshot
• 错误堆栈

Outbox 边界

推荐新增独立 Content Events publish outbox：

• source table：muse_content_block_source_attribution。
• source tuple：sourceOwner=content，sourceType=content_block_source_attribution，sourceId=blockId，sourceRevision=blockRevision。
• commandId：稳定短幂等键，建议 content_evt:<sha256(tenantId|blockId|revision|source_status_change)>。
• 唯一约束：建议覆盖 (tenant_id, block_id, block_revision, notification_type)，避免同一 Block revision 重复发布。
• 状态机：queued/running/retryable/published/dead_letter。
• claim：必须原子领取，具备 lease / retry / attempt ownership。
• 终态回写：必须绑定本次 claimed attempt，避免 stale worker 覆盖新 claim。
• worker 默认关闭，配置启用后才 claim。
• invalid owner、invalid payload 或 missing attribution 必须 fail-closed，不得发布给 owner 0 或其他用户。

依赖边界

• Content server 可以依赖 muse-module-events-api。
• Content server 不得依赖 muse-module-events-server。
• Events server 不得依赖 Content server。
• muse-server 作为装配层可以同时包含 Content server 与 Events server。

关键取舍

• 选择 saveBlock，不选择全部 Content 写命令：第一切片需要最小真实链路，避免把结构编辑、任务状态和治理语义混在一起。
• 选择 block source attribution，不选择正文本身：source attribution 是已落库、可审计、可脱敏的 source fact；正文不应进入统一 SSE payload。
• 选择 notification/source_status_change，不新增 block_saved：当前 Events 合同已声明该 subtype；新增 subtype 必须另起 OpenAPI 审批。
• 不使用 SSE chunk：chunk 是 AI 生成文本片段语义，Content 保存正文不应伪造为 AI chunk，也不应发布正文片段。
• 不复用 attribution 表作为 publish queue：source fact 与 publish compensation 是两个职责，混用会缺 claim、retry 和 dead_letter 证据。

影响范围

• 直接影响：
  • Content saveBlock source attribution 发布链路。
  • Content server 依赖 events-api。
  • Content 本域 outbox / worker / migration / focused tests。
  • Events unified event focused E2E。
• 间接影响：
  • P1R-7 completed approval 的 source owner evidence 更完整。
• 不影响：
  • OpenAPI 合同。
  • coverage scanner / coverage report。
  • Content 51 operations completion status。
  • Content saveBlock 同步返回语义。
  • Import / parse / export / planning / meta projection / admin governance 业务逻辑。

风险与兼容性

• 语义风险：source_status_change 原先主要用于 Knowledge；执行版必须说明 Content 使用该 subtype 的语义边界，不能把它扩展成万能通知。
• 事件重复风险：同一 (blockId, revision) retry 不能创建多条 unified event；必须用 commandId 与 source tuple 双重幂等。
• 敏感信息风险：正文、sourceSnapshot 原文、authorizationSnapshotId、lineage、license restriction 和 auditReason 不得进入 payload。
• owner 风险：SSE owner 必须是作品 owner，不能由 path 参数或 payload 自带 owner 推断。
• 并发风险：saveBlock 已有 revision guard；outbox 创建必须与成功 attribution 写入同事务，且不能在 command replay 分支重复写 outbox。
• 可达性风险：如果实现时发现 sourceAttributionMapper.insert 后无法可靠拿到 attribution id，应以 (blockId, revision) 作为 source tuple，不为拿 id 改动既有 mapper 行为。
• 兼容性：新增 outbox 与 worker 默认关闭，不改变现有 Content API 同步返回语义。

验收标准

审阅版通过后，执行版必须包含：

1. Content outbox DO / Mapper / Service / Worker / 配置 / V21 migration 的文件边界。
2. ContentAppServiceImpl.saveBlock 在 Block 更新和 attribution 写入后同事务创建 outbox 的事务边界。
3. payload exact allowlist 与敏感字段拒绝策略。
4. worker success / duplicate / retryable / CommonResult error / rejected / blocked / dead_letter / stale claim tests。
5. Content saveBlock source fact -> Content outbox -> worker -> EventsPublishApi -> muse_unified_event -> SSE visible focused E2E。
6. dependency gate：Content server 有 events-api、无 events-server；Events server 无 AI / Knowledge / Market / Member / Content server。
7. V21 SQL 静态 gate 与 Flyway _test。
8. P1R mixed gates 继续确认 AI / Knowledge / Market / Account source owner gates 不回退，Content 仍为 dedicated / needs_verification。
9. coverage scanner 只在 /tmp 隔离副本运行，真实 worktree protected diff 为空。
10. git diff --check 和 protected staged / unstaged diff gate。

待确认项

1. 是否接受 P1R-7f 第一切片只覆盖 saveBlock，其他 Content 写命令进入后续切片。
2. 是否接受在不改 OpenAPI 的前提下复用 notification/source_status_change 表达 Content block source attribution active。
3. 如果 reviewer 认为 source_status_change 语义不适配 Content，是否先停止 P1R-7f 实现，改走 Events OpenAPI subtype 变更审批。