feat(capture): declare bounded projection coverage for Hermes and Gateway Sources #2437

目标

给 Hermes 和 Gateway 的现有 Content Source 捕获增加一个小型、版本化的投影覆盖声明，把 adapter 实际观察到的截断和省略绑定到同一份 Source payload。首先利用已有 metadata 持久化和读回路径，不迁移数据库，不改变 authority、generation eligibility 或 Memory 召回。

本 Issue 的 complete 只表示“相对于明确版本的受支持投影，没有额外容量舍弃”，不表示完整原始会话、逐字原件、真实事实或用户授权。

已有机制与真正缺口

基线：9c8f061cf76b4002641e8ca8a5d23a469f433e56，2026-11-03。

• Hermes provider.py::sync_turn 把 user/assistant 拼接文本裁到 50,000 字符，metadata 没有对应声明；它不捕获传入 messages 中的全部工具历史。
• _precompress_content_for_entries 返回 complete_checkpoint。optional 模式可接受有界前缀；required 模式在不完整时已拒绝。
• Gateway transcript.rs::turn_transcript / bounded 已有 omitted_steps 和 [truncated N bytes]，不缺文本截断标记。
• ContentSourceAdapter.resolve 和 ContentTextEvidenceProjection.project 已保留 metadata。
• project_atomic_memory_evidence 会将含 metadata 的 TextEvidence 作为模型证据；声明会增加输入字节/token。
• SourceRepository 比较的是整个 Source。相同 ID 增加 metadata 会产生 payload conflict，不能把它误当无条件向后兼容。

源码：Hermes 捕获、Gateway transcript、Source 冲突语义。

负责范围

必须分别保留：capture coverage、EvidenceManifest.incomplete、隐私 admission 的 coverage.complete、authority/verification、root independence。不得用同一个布尔量合并这些事实。

元数据契约

在现有 metadata 中增加命名空间键 powercontext_capture_coverage，不覆盖 kind/session_id/target_profile 或其他不相干字段：

{
  "powercontext_capture_coverage": {
    "schema": "powercontext.capture-coverage.v1",
    "projection": "hermes-turn-text.v1",
    "unit": "user_assistant_text_pair",
    "status": "complete",
    "reasons": []
  }
}

契约约束：

• schema 固定为上值。
• projection 只能是本 Issue 定义的三个版本化 profile：
  • hermes-turn-text.v1；
  • hermes-precompress-text.v1；
  • gateway-turn-text.v1。
• 对应 unit 分别为 user_assistant_text_pair、new_user_assistant_window、gateway_turn_projection。
• status 为 complete | partial | unknown。
• reasons 为去重、稳定排序的小型枚举数组：character_limit、field_byte_limit、transcript_byte_limit、unmeasured_projection。complete 的 reasons 必须为空；partial 必须包含至少一个实际观察到的损失原因；unknown 不得伪称未观察到损失。
• 对象限制 512 UTF-8 bytes。不得加入内容、路径、message ID 列表、逐字段原文、prompt、模型配置或秘密。
• 旧 metadata 缺键、未知 schema、错误字段或不支持的 profile，在解释时为 unknown，不推断为 complete。不得对历史记录回填。
• 这是捕获者的版本化声明，不是任意 HTTP caller 可以借此获得的权限。Core 不因这个键改变 authority 或资格。

把规范写成一个可引用的中英契约说明，并提供一份 Python/Rust 都使用的纯 synthetic JSON fixture。只共享数据契约；不建立跨语言运行时或插件框架。

三个 profile 的精确定义

Hermes completed turn

单元是当前实现拼接的 [user]... [assistant]... 文本对，不是完整工具 turn 或整个会话。

• 对拼接完成、裁剪前的字符串判断是否超过当前字符上限；发生实际裁剪即 partial/character_limit。
• 未裁剪则 complete，但仅相对于该文本对投影。
• 不通过搜索正文中的 [truncated] 等标记判断覆盖。
• 不改变原有正文、字符上限、角色选择、secret handling、source_id 或队列行为。

Hermes pre-compress

单元是宿主交给 provider、经现有 user/assistant 过滤和去重后，本次待捕获的新文本窗口。优先使用现有 evidence_messages。

• 现有投影完整容纳该窗口时声明 complete。
• optional 模式只捕获部分条目时声明 partial/character_limit。
• required 模式维持现有行为：超限时拒绝，不发送部分 Source、不推进已捕获快照。
• 角色过滤、宿主未提供的消息、排除的工具/系统内容，不得被描述成“原始会话完整”。
• 没有可捕获条目时不为了 coverage 创建空 Source。
• 保留现有 overlap/idempotency、Scope 固定和 durable capture 后 extraction 失败不否定 checkpoint 的语义。

Gateway normalized turn

单元是当前受支持 Chat/Responses 规范投影：最后一个 user 开始到 terminal assistant 的可见文本、工具调用/结果等；按既有策略排除注入 prepare、opaque reasoning、传输 ID 和不支持的媒体载荷。

• 复用实际执行 field byte 裁剪、whole-transcript step 舍弃时的事实，分别标记 field_byte_limit / transcript_byte_limit。
• 普通文本中的伪截断标记不改变声明。
• 不改变现有 omitted_steps、[truncated N bytes]、正文 JSON 格式、64 KiB/8 KiB 限制和终止响应判断。
• 因不支持的协议返回 None 时保持“不捕获”，不能新造一个 complete Source。
• 对不能测量完整性的已接受投影使用 unknown，而不是猜测完整。
• metadata 与内容必须来自同一次投影计算。可以在内部返回 text + 有界覆盖结果；无需全局状态、第二次解析 transcript 或修改公共 GateClient 协议。

身份、重放和升级兼容

SourceRepository 已拒绝同一身份的不同完整 payload；不得修改这一不变量。

1. 新 Source：声明与正文在同一次 capture 中提交。
2. 同版本重试：source_id、正文、声明和其他 metadata 必须确定性一致，不新增 journal position。
3. 旧 Source 无声明：保留原记录为 unknown，不写回、不添加新 Source ID 来偷偷复制同一事件。
4. Hermes 遇到 409 时，可以最多一次用完全相同正文与其他 metadata、仅去掉本次新增 coverage 键的 legacy payload 重试。只有 Server 的完整 payload 相等检查接受它，才能视为原 Source 的幂等重放。
5. legacy 重试仍失败则保留原冲突。不得把所有 409 当成功，不得删除其他 metadata、改正文或无限重试。401/403/网络失败不触发这条兼容路径。
6. 兼容重放成功不意味着旧 Source 获得了新声明，检查旧记录仍应为 unknown。
7. Gateway 已有 409 first-write-wins 处理，维持现有行为；不能因此声称新声明已经持久化。不要为这项 metadata 添加新网络探测。

所有兼容逻辑留在该 capture 操作的拥有边界，不给通用 HTTP 客户端加入与其他调用无关的分支。

与其他工作协调

• feat(memory): add versioned Source evidence declarations and neutral lifecycle projection #1975 / PR feat(memory): persist versioned Source evidence and neutral Atomic Memory projection #2004 拥有 Source authority/verification 和精确历史声明，本 Issue 不改它们的 enum、迁移或表。
• evaluation(workbuddy): measure joined-prompt self-ingestion before adding owned evidence projections #2069 已完成 host payload ownership 评估；本 Issue 不引入新正文过滤器或重定义 current-user ownership。
• evaluation(memory): measure bounded generation evidence admission for oversized and mixed Sources #2074 是大证据 admission 评估；本 Issue 不实施新的生产裁剪策略。
• 开放 PR feat(gateway): extract Atomic Memory over the agent's cached conversation prefix #2435 使用 Gateway metadata 传递 prefix extraction 信息；必须保留其他键，不复制、展开、清理或解释其 handle。
• feat(integrations): qualify pre-compaction checkpoint durability and failure semantics #2068 已建立生命周期契约。本 Issue 不提升 manifest 中任何宿主的 capability。

模型输入副作用与展示边界

这项 metadata 会经当前 TextEvidence 路径进入提取输入。实施者必须：

• 用 synthetic fixture 记录新增 JSON 字节数及现有 estimator 的输入预算变化，不宣称零开销。
• 保持完整输入预算检查；边界用例因新增开销不再容纳时，继续使用现有缩窗/拒绝语义，不能悄悄丢掉声明或放宽预算。
• 声明保持为数据，不从 Source 文本或任意 caller metadata 生成系统指令。
• 不新增数据库列、公共 OpenAPI 字段、Source 投影版本或 Artifact body 字段。
• 不承诺 coverage 自动穿过模型摘要进入最终 Memory/PreparedContext。后续若需要确定性派生传播或模型可见说明，应另列使用场景与契约。
• PC 已有 TRUST_POLICY、边界封装和完整预算计算；本 Issue 不新增通用 protected/Required 调度。

代码落点

• integrations/hermes/plugins/powercontext/provider.py、helpers.py：声明计算、capture 组合及窄兼容路径。
• gateway/crates/pc-gateway-core/src/transcript.rs、executor.rs：同一次投影的 coverage 与 metadata 合并。
• tests/integrations/test_hermes_provider.py：实际出站 payload 和 checkpoint 行为。
• gateway/crates/pc-gateway-core/tests/executor_semantics.rs 及现有 transcript tests：捕获输出和不改变渲染内容。
• Source/readback 与 extraction 的 focused E2E：沿现有持久化路径验证；runtime 源码原则上只读。
• 契约文档及共享 synthetic fixture：放在现有 integration conformance 组织下。

验收矩阵

• Hermes 短文本对 complete；超长 partial；正文和 source_id 保持原语义。
• optional 部分窗口 partial；required 超限不捕获；重叠窗口没有重复事实。
• Gateway 无损、字段截断、整步省略、同时发生和伪 marker 均准确。
• metadata 保留其他键，包括与 prefix extraction 类似的未知扩展键。
• 同事件重试不增加 journal position；旧无声明 Source 的兼容重放不修改历史。
• 真正不同正文/其他 metadata 的 409 不被吞掉。
• 缺失、未知、非法声明均不提升为 complete 或 authority。
• 通过真实 HTTP/SQLite capture、重启和现有 get_source 读回验证同一 Source payload；不是只检查构造字典。
• 通过实际 TextEvidence / AtomicMemoryEvidence 投影验证声明进入提取输入及预算成本；不要求调用真实模型。
• Scope A 的记录和声明不能在 Scope B 读回。
• 无数据库迁移、历史回填、Source ID 换代、Memory body 改写或召回变化。

验证

uv run pytest tests/integrations/test_hermes_provider.py -q
cargo test --manifest-path gateway/Cargo.toml -p pc-gateway-core
cargo clippy --manifest-path gateway/Cargo.toml -p pc-gateway-core --all-targets -- -D warnings

增加的 Source readback/extraction E2E 单独运行并列出命令。先检查实际 workspace/package 名称；若脚本入口已变化，使用现有等价命令，不创建新的测试框架。修改内容涉及的 Ruff/type checks 同步通过。