th-hotel-simple/docs/project/requirements/M012-fixed-channel-parsing-agent-v1-runtime-integration-change-request-v1.md

# M012 / Fixed-Channel Parsing Agent v1 Runtime Integration Change Request v1

| 项 | 内容 |
|---|---|
| 状态 | **CP5 TEST SUPERAGENT BINDING + LIVE CONTRACT SMOKE COMPLETE — automatic worker / production HOLD** |
| 日期 | 2026-08-14 |
| 最近修订 | 2026-08-17（公开Trace传递与安全投影本地完成；未复跑真实Provider） |
| 目标 | 信息系统消费公共 Parser 输出，调用 Parsing Agent v1.0，并在本地确定性合并 |
| 渠道 | QBD、LIANTAI；不含 LIANTAI_FIT |
| Checkpoint | `M012-fixed-channel-parsing-agent-v1-runtime-integration` |
| 影响范围 | Backend / Layer 3 contracts / SourceMessage / Booking worker / SuperAgent adapter / Booking PostgreSQL / Test / Docs |
| 发布边界 | 测试平台 Profile/Skill/外部应用已绑定并完成受控真实 Provider 冒烟；自动 worker、production、PMS/Opera 仍关闭 |

## 1. 背景与当前运行事实

固定渠道公共 Parser 已按 ADR-008 完成，QBD/LianTai 默认 `parse()` 均返回
`ParserResult(meta,status,facts[],agent_materials[])`。真实样本批准基线为：

- QBD：114 facts / 4 WAITING materials；
- LianTai：70 facts / 6 materials；
- 扩大 Parser 专项及真实样本：0 failures/errors。

Parsing Agent v1.0 已按 ADR-009 完成 Skill/schema/reference/fixture/validator/package 和独立中文 Main
Prompt，输出为中立 `structured_mentions[]`，不再输出 Trace、部门或最终业务分类。当前 Agent 专项 22/22、
Python 全套 50/50、15成员 source/archive/manifest 严格校验均通过。2026-08-14 已将对应 Prompt 与 Skill
绑定到测试 SuperAgent Profile，并完成真实契约冒烟；源发布包仍保持 `HOLD/INTERNAL_ONLY`，不代表生产发布。

CP4 已在默认关闭的 v1 分支中接通上述公共契约；默认开关仍保留 legacy 链：

```text
Current message + current attachment bytes
→ BookingPostgresMessageOrchestrator
→ BookingContractAssembler.parseLegacy()
→ optional old Field Recovery（默认/生产关闭）
→ legacy ParsedFactSet
→ Context / Layer 5
```

v1 分支现已具备 request/evidence builder、provider-neutral port、SuperAgent adapter、response validator、
local merger、Layer 3 effective result、pre-Context durable execution/worker、双入口 SourceMessage、Parser FAILED
受控fallback，以及latest Layer3ResultV2 direct handoff/同run current Layer4/5/6 continuation。旧compatibility
projection只保留为CP6前legacy资产。测试平台绑定和真实 adapter 契约冒烟已完成；尚未做的是部署环境 Secret
注入、自动 worker 启用、完整 AgentBus→PostgreSQL 主链 smoke、业务 required-fact catalog、MySQL V30/运行保障
Gate和CP6 legacy退出。获批非生产 PostgreSQL V1–V6 migration/restart/lease/concurrency smoke 已于2026-08-12
通过；运行保障Gate尚缺告警/人工恢复运行手册。

## 2. 权威基线

实施必须同时遵守：

1. ADR-008 与 `M012-qbd-liantai-parser-output-contract-v1.md`；
2. ADR-009 与 `M012-fixed-channel-parsing-agent-v1-contract.md`；
3. ADR-005 的 per-agent external app/token；
4. SourceMessage 先落库、AgentBus callback 不等待外部 Agent；
5. Layer 3 中立结构、Layer 4 Context/RateRoom、Layer 5 业务判断、Layer 6 Validator 的既有边界。

如旧 Recovery、C03-v2、`Layer3ContractsV2`、旧 contribution service 或历史 CR 与上述基线冲突，
只能作为迁移证据，不得扩展成新 v1 行为。

## 3. 目标与非目标

### 3.1 目标

1. 两个入口都以持久 SourceMessage 作为 Current/History 唯一来源。
2. 主链调用公共 `parse()` 并保存 ParserResult，不在 v1 分支调用 `parseLegacy()`。
3. 信息系统确定性组装完整 v1 request 和 evidence registry。
4. 通过 provider-neutral Port 调用 Parsing Agent，使用 fake/mock 完成常规验收。
5. 信息系统严格校验 Agent 返回，并在本地确定性合并。
6. 输出权威 `effective_facts[]`、中立 `structured_mentions[]` 和 `review_items[]`，并承接其余合法中立结构。
7. 持久化执行状态、幂等、重试、审计与 failure codes，进程重启后可恢复。
8. 将最终八数组Layer3无业务解释地投影latest Layer3ResultV2，并以同run续接当前Layer4/5/6；V2无槽位审计放sidecar。
9. 以独立checkpoint退役compatibility/legacy，不在本次删除历史资产。

### 3.2 非目标

- 不修改已验收的 Parser 十类事实、QBD/LianTai Profile 规则或真实样本口径。
- 不让 Agent 覆盖 Parser facts、创建 TaskCard、写数据库业务状态或调用 PMS/Opera。
- 不让 Layer 3 决定 business type、Trace、linked action、部门、Rate Code 或 canonical Room。
- 不把 Main Prompt 放进 Skill 包，也不在本 CR 中修改 Prompt 内容。
- 不新增 Controller、MCP、浏览器或第三方入站接口。
- 不在首个 runtime checkpoint 删除所有旧 Recovery/legacy 资产。
- 不在代码合并时自动启用 production 或真实 Provider。

## 4. 目标数据流

```text
Manual EML / AgentBus
→ capture or bind Current SourceMessage
→ resolve QBD/LIANTAI Profile
→ run public deterministic Parser on current attachment
→ persist immutable ParserResult + controlled fallback snapshot
→ create/reuse durable Parsing Agent execution
→ worker reloads Current revision + ordered History revisions
→ build history_bodies[] + evidence registry + request
→ request preflight validation
→ FixedChannelParsingAgentPort
→ strict result decoding + semantic validation
→ deterministic local merger + completeness review
→ persist authoritative FixedChannelLayer3Result
→ latest Layer3ResultV2 neutral projection + controlled audit sidecar
→ same-run current Layer 4 / Layer 5 / Layer 6
```

入口在 execution 入队后结束；Provider 等待只能发生在 worker。Worker 不依赖入口内存里的附件 bytes，
因为公共 ParserResult 和 fallback snapshot 已持久化。

## 5. 输入快照与调用规则

### 5.1 Current

- 读取确切 `source_message_id + revision` 的完整 subject/body。
- Current attachment 只在同步 Parser 阶段使用；Agent 只接收 ParserResult 和登记后的文本 evidence。
- 当前正文不得由旧 `BookingAgentInputMaterialPolicy` 裁剪或截断。

### 5.2 History

- 由内部 SourceMessage repository/query 按 conversation identity 和稳定 sequence 读取。
- 正文完整传递、不截断；每项固定 source id、revision、sequence、content hash。
- 不传 History 附件、附件文件名、附件 URL、附件 evidence 或附件 bytes。
- 后台 builder 不调用会产生“员工读取原文”审计副作用的 UI original-read service。

### 5.3 Parser Results

- v1 分支只消费公共 `FixedChannelParserContracts.ParserResult`。
- 当前首版维持一个消息中恰好一个匹配固定渠道 workbook 的既有不变量，是否扩展需审批。
- Parser `FAILED` 必须 `facts=[]` 且 `agent_materials=[]`；只能由外层受控 fallback/review 处理。
- material 的 `target_ref` 按 Parser 契约可为 `null`，不得为满足 Agent schema 伪造 target。

### 5.4 调用矩阵（已实现）

建议每个通过入口、酒店、SourceMessage 和版本校验的 Current message 至多创建一个逻辑 request：

| Current/Parser 条件 | 建议行为 | 状态 |
|---|---|---|
| Parser SUCCESS，有 facts/materials | 同一逻辑execution调用一次；fallback为空 | Implemented |
| Parser SUCCESS，只有 facts | 仍调用，以解析完整 Current/History | Implemented |
| Parser SUCCESS，只有 materials | 调用一次 | Implemented |
| Parser SUCCESS，facts/materials 均空 | body-only同样调用一次；不以正文关键词决定渠道/跳过 | Implemented |
| Parser FAILED，有系统授权 Current-only fallback | 同一逻辑execution调用；只使用持久化有界fallback | Implemented |
| Parser FAILED，无 fallback | 仍处理完整邮件主题/正文；附件生成稳定blocker | Implemented |
| 渠道/Profile/版本未验证 | 不外呼；入口或 request preflight 失败 | Implemented |

无论采用哪一矩阵，都必须以稳定 call/no-call reason code 和唯一 request hash 审计。

## 6. Evidence Registry 提案

### 6.1 Evidence 类型

- Current subject；
- Current body；
- ordered History body；
- Parser facts/materials 的准确来源引用；
- 信息系统显式授权的 Current-only fallback。

History attachment 永远不属于 registry。

### 6.2 稳定身份

建议 ID 输入至少包含：

```text
evidence_schema_version
source_message_id
source_revision
scope/current_or_history
section/subject_or_body_or_parser_or_fallback
unicode_code_point_start
unicode_code_point_end
sha256(exact_source_text)
```

相同快照重复组装必须得到相同 ID。span 以 Unicode code point 计数，不使用 UTF-16 code unit；
`source_text` 必须是保存 revision 的准确子串，不做 trim、翻译或换行归一化后再定位。

### 6.3 分段建议（待审批）

为兼顾准确引用和可复核性，建议登记：

1. 完整 subject/body block；
2. 非空行 block；
3. 按受控标点形成的 clause block；
4. Parser material 与 fallback 的精确 block；
5. 对相同 source/revision/span/hash 去重。

分段只建立文本索引，不预判语义。若完整 request 超过 Provider 明确上限，preflight 失败；禁止删除 History、
缩短正文或通过摘要替代原文。

## 7. Request Builder 与 Preflight Validator

Request Builder 只接收已验证的内部 snapshot，不直接下载附件或查询 Provider。输出必须精确匹配
`fixed-channel-parsing-agent-input-v1.0.schema.json` 及配套 semantic rules。

Preflight 至少验证：

- channel/profile 精确配对和所有 contract/schema/profile/rule versions；
- Current/History source identity、revision、sequence、hash；
- ParserResult identity、status、facts/materials 和 attachment hash；
- evidence spans、exact text 与 ID 稳定性；
- fallback 只来自 Current 且在系统允许范围；
- target/fact/material/evidence 引用闭合；
- unknown fields、重复 IDs、超限和禁止数据；
- material optional target 的版本兼容策略。

Preflight 失败不得调用 Provider。

## 8. Provider-neutral Port 与 SuperAgent Adapter

建议 workflow Port：

```text
FixedChannelParsingAgentPort
  invoke(ValidatedParsingAgentRequest, InvocationContext)
  -> ParsingAgentInvocationResult
```

Port 不暴露 SuperAgent session/SSE DTO、token 或 HTTP exception。`InvocationContext` 仅包含稳定幂等键、
deadline、获准版本和安全审计关联。

SuperAgent adapter：

- 使用 `booking.parsing-agent.open-api.*` 独立配置；
- 复用 `SuperAgentOpenApiClientFactory` 和通用 session/SSE/run-status/recovery transport；
- 使用专属 external app/token，不回退到旧 Recovery/Booking Business/global key；
- 将 request 序列化为单一 canonical JSON payload；
- 限制响应大小与 deadline，只接受完整 final/end + successful run；
- 返回 resolved Profile ID供本地强校验，并把actual published version写入运行审计；
- 不把 raw provider answer 写入普通日志或业务 artifact。

常规 CI 只用 fake/mock adapter；真实连接属于单独 release gate。

## 9. Response Validator

Server 不把 Python validator 作为运行时依赖。建议采用严格 Java DTO（unknown property fail）加显式语义
validator，并用同一 canonical fixture 与 Python offline oracle 做 parity。

### 2026-08-17 ADR-018 修订

严格 DTO decode 继续作为整份结构门槛；跨请求语义 Validator 改为逐项验收。整份返回只在
request/message/version/Parser refs/fallback refs 身份不一致时拒绝。身份正确后，只按项目检查引用身份、来源
和 Parser 权威；失败项目及其依赖项目被移除，其他结果继续进入 Merger。以下早期“任一失败拒绝整份”和
“每个 material 必须由 response Validator 恰好闭合”的口径不再适用。

当前必须验证：

1. 顶层八组数组存在且无额外字段；
2. 所有 result IDs 全局唯一；
3. target、fact、material、evidence 引用均存在且类型正确；
4. `source_text/source_label` 可由 evidence registry 还原；单片段精确匹配或多片段共同覆盖Current原文均可，
   `sequence`只承担展示顺序；
5. History 不能单独支持本次 candidate fact/relationship/mention/display；
6. candidate fact 不覆盖 Parser 异值；有明确 conflict review 时只保留为复核材料，Merger仍保留Parser值；
7. structured mention scope/target/quantity/source-room/evidence 合法；
8. forbidden business/Trace/department/TaskCard/RateRoom/PMS 字段在任何层级都不存在；
9. 已返回的 material disposition 引用身份与来源合法；缺少某项 disposition 不升级为整份失败；
10. Agent 声明的 conflict/review 与 Parser facts/materials 一致；未知引用只拒绝受影响项目。

candidate 业务值类型与完整性不再由本层作为整份门槛，继续由 Layer 5/6按已识别业务处理。严格 DTO 自身
结构失败仍整份拒绝；逐项恢复不覆盖无法反序列化的 Provider JSON。

## 10. Deterministic Local Merger

Merger 输入仅为 immutable ParserResult、validated Agent result 和冻结的 completeness policy。

规则：

- Parser facts 原样进入 `effective_facts[]`，保留来源与 rule ref；
- Agent candidate 与同 fact key Parser fact 同值时按批准规则合并 provenance，不替换 Parser 值；
- 异值只保留 Parser fact并生成 conflict review；
- 没有 Parser fact时，只有 Current/Parser material/fallback evidence 合法且 target 唯一的候选可成为有效事实；
- History-only、非法 target、非法 role 或引用不足的候选不得进入 effective view；
- 已通过验收的 material disposition保持审计引用；缺少处置不再由本层把整份Agent结果判失败；
- required fact 完全缺失时由 merger/completeness policy 生成 review；
- 合法 `structured_mentions[]`、display、binding、relationship 保持中立，不转成 Trace、部门或业务类型；
- 标准化排序、ID 和 review code 必须在重放中稳定。

### 10.1 最终结果拓扑（已实现）

权威八数组结果经本地merge后，确定性投影为latest Layer3ResultV2；以下中立内容均保留：

```json
{
  "effective_facts": [],
  "structured_mentions": [],
  "display_information": [],
  "target_bindings": [],
  "relationships": [],
  "review_items": []
}
```

V2没有直接业务槽位的Agent target、fact authority、exact v1 target/material/review引用保存在
`FIXED_CHANNEL_LAYER3_V2_AUDIT` sidecar。不得把 mention 塞入十类 Parser fact，也不得丢弃合法
display/binding/relationship；不得在投影器生成business type、Trace、部门、TaskCard、Room或Rate。

## 11. Orchestration 与持久化

### 11.1 入口

- AgentBus：维持先 capture SourceMessage，再触发 Booking；Parser 后只 enqueue execution。
- 手工 EML：PostgreSQL 分支补齐 capture/bind Current SourceMessage，再进入同一 Parser/execution 路径。
- 两条入口不得因来源不同生成不同 request/evidence/merge 规则。

### 11.2 Execution/outbox

实施时以 `server/src/main/resources/db/booking-postgresql/migration/` 的下一可用 Flyway 版本新增表，不能在
本 CR 预占固定编号。建议字段：

- execution id、hotel id、processing run id；
- source message id/revision、parser result artifact key；
- request hash、idempotency key、contract/profile versions；
- status、attempt、next attempt；
- lease owner/token、locked until、fencing version；
- provider session/run/resolved profile/version；
- response hash、safe failure code；
- created/updated/started/completed UTC timestamps。

领取、续租、完成、失败与重试使用 CAS/fencing 或等价单所有者语义。重复 SourceMessage/callback/replay
只能复用同一逻辑 execution，不产生双权威 artifact。

### 11.3 Artifact 与审计

- SourceMessage original store 继续唯一保存完整邮件正文和附件。
- Booking artifact 保存 public ParserResult、controlled fallback snapshot、normalized validated Agent result、
  authoritative Layer 3 result。
- invocation audit 保存 refs/hashes/versions/status/failure code/provider metadata；不默认复制完整 request body
  或 raw answer。
- 所有记录绑定 hotel + processing run + SourceMessage，沿用 processing-run retention 和访问边界。

## 12. Failure Policy 提案（待审批）

| Failure | 建议系统行为 | Parser facts | 自动业务处理 |
|---|---|---|---|
| Request internal invariant 失败 | run FAILED，记录安全 system code | 保留 artifact | 禁止 |
| Payload 超 Provider 限额 | 不调用；生成 blocker review/受控失败 | 保留 | 禁止 |
| Provider timeout/unavailable | 按稳定幂等键重试；耗尽后 blocker review | 保留 | 禁止 clean task |
| Invalid JSON/schema/forbidden field | 拒绝整份 result；blocker review | 保留 | 禁止 |
| Resolved profile/version mismatch | 契约失败，不 merge | 保留 | 禁止 |
| Parser FAILED，无 fallback | system failure/blocker review | 无 partial | 禁止 |
| Agent candidate 与 Parser 冲突 | Parser 值保留；生成 conflict review | 不变 | 仅人工风险路径 |
| material 未闭合/required fact 缺失 | 生成稳定 review item | 已确认 facts 保留 | 由 Layer 6 fail closed |

是否同时把 provider/contract failure 标记为 processing-run `FAILED`，或保留 run 并以 `BLOCKER review` 继续到
人工页面，需要在 CP0 确认。

## 13. Legacy 迁移与回滚

### 13.1 切换原则

- 新 v1 feature 默认 false，production 显式 false。
- v1 false：维持 `parseLegacy()` 与当前旧链。
- v1 true：使用公共 `parse()` + v1 execution/Agent/merger；旧 Field Recovery 强制 false。
- 不提供 legacy/v1 双写模式，不进行双外部 Agent 调用。
- 新固定渠道 Layer 3 result 直接投影latest `Layer3ResultV2`并进入同run当前Layer4/5/6。compatibility
  projector只保留feature关闭/CP6前legacy代码，不再作为新路径权威下游。

### 13.2 回滚

关闭 v1 feature 即恢复 legacy 分支；不删除 execution、artifacts、audit 或历史 migration。未完成 execution
进入获准的 held/cancelled 状态，不能在关闭后继续外呼。具体状态名在 failure policy 审批后冻结。

### 13.3 独立退役

运行观察和 rollback 演练通过后，另开 checkpoint：先移除 runtime 调用，再逐步删除 `parseLegacy()`、
旧 Field Recovery、`Layer3ContractsV2`、`FixedChannelParsingAgentContributionService` 及专属测试。历史 migration
和审计数据永不因代码清理删除。

## 14. 安全与数据边界

- INTERNAL_ONLY，不新增外部入口或权限面。
- 所有查询、artifact、execution 和审计都绑定 hotel 与 processing run。
- Secret 只由部署 Secret 注入；仓库、测试、日志、异常、文档中无真实 key。
- 不外发 History attachments、附件 URL、数据库标识、PMS/Opera 数据或用户未授权上下文。
- 不保存隐藏推理；raw provider answer 默认不持久化。
- 日志使用稳定 ID/hash/failure code，不输出完整正文或 material raw content。
- Provider output 不能直接写 TaskCard、订单、PMS/Opera 或最终业务状态。

## 15. 实施 Checkpoints

1. **CP0 Contract Gate**：技术架构、版本策略和失败矩阵已批准；business completeness catalog 与 release evidence 仍为放行Gate。
2. **CP1 Local Core**：v1 DTO、History/evidence/request builder、validators、merger、fake Port 与 parity tests。
3. **CP2 Durable Execution**：Booking PostgreSQL execution/outbox、claim/fencing/retry/audit 与 fake worker。
4. **CP3 SuperAgent Adapter**：专属 config/wrapper/adapter，仅用 mocked transport 验收。
5. **CP4 Runtime Wiring**：双入口 SourceMessage、公共 ParserResult、FAILED fallback、worker、merge、direct V2 projection和same-run continuation。
6. **CP5 Controlled Release**：平台 Prompt/Skill/Profile/app 绑定证据和无 PII smoke；production 另行批准。
7. **CP6 Legacy Exit**：观察期后独立删除旧 runtime 调用与契约。

每个 checkpoint 独立完成 focused tests、全量相关回归、security review 与 project-doc post-task gate。

## 16. 测试与验收

最低新增测试：

- Java DTO/schema canonical round-trip 和 unknown-field negatives；
- Python/Java fixture parity；
- 完整 History、无 History attachment、Unicode spans、稳定 IDs、超限不截断；
- request identity/version/fallback/ref preflight；
- response forbidden keys、exact source、History-only、Parser conflict、material closure；
- merger immutability、same/different value、deterministic replay、completeness、neutral structures；
- fake Port 与 mocked SuperAgent success/failure/recovery/profile mismatch；
- durable enqueue/claim/fencing/retry/restart/duplicate callback；
- Manual EML 与 AgentBus 同契约集成；
- legacy/v1 互斥与 rollback；
- Secret/PII/raw answer/attachment 不落日志和审计。

回归基线不得下降：QBD 114/4、LianTai 70/6、Parser 扩大样本 0 failures/errors、Agent 22/22、Python
50/50，以及后端 focused/full suite。

## 17. 预计文件归属

| 范围 | 预计归属 |
|---|---|
| v1 runtime DTO | `workflows/reservation/common/dto/booking/layer3/v1` |
| Builder/Validator/Merger | `workflows/reservation/booking/service` 与 `service.impl` |
| Provider-neutral Port | `workflows/reservation/booking/service` |
| SourceMessage History query | `platform/message` 内部 repository/service |
| Execution persistence | `workflows/reservation/booking/repository` + Booking PostgreSQL migration |
| SuperAgent adapter | `integrations/ai/superagent/adapter` + 专属 properties/wrapper |
| Orchestration anchors | `ReservationBookingEmailIntakeServiceImpl`、`AgentBusFrameProcessor`、`BookingContractAssembler`、`BookingPostgresMessageOrchestrator` |
| Config | `application*.yml` 的 `booking.parsing-agent.*`；默认/production false |
| Tests | 对应 server unit/integration、canonical fixtures 与 Python package regression |

共享热点文件只有在对应 checkpoint 开始前重新检查 ownership/diff 后才修改。

## 18. CP0 Approval Checklist

- [x] 接受带审计闭环的八数组 `FixedChannelLayer3Result` topology。
- [x] optional material `target_ref` 采用“字段必有、值可空”的v1.0 pre-release schema纠正。
- [x] 冻结 exact Agent call/no-call matrix。
- [x] 冻结完整文本＋行/句片段＋附件材料的 evidence segmentation 与超限不截断行为。
- [x] 冻结 History conversation/revision/order sidecar 规则。
- [x] 冻结 failure → Parser-only blocker review / internal execution failed 映射。
- [ ] QBD/LianTai required-fact completeness catalog；通过本地policy注入，未配置时阻塞自动业务放行。
- [x] 首版维持0个body-only或恰好1个匹配workbook，多匹配fail closed。
- [ ] CP5 前提供专属 Main Prompt/Skill/Profile/app/token 绑定证据。

上述技术项已经用户授权由Codex决定，CP1–CP4可以在默认关闭、fake/mock、无真实客资的条件下推进。
required-fact业务目录与CP5平台证据未关闭前，不得启用真实Provider或自动业务放行。

## 19. 当前隔离实现状态（2026-08-12）

已完成一个不依赖上述 open gates、且完全未接线的结果接收切片：

- `FixedChannelParsingAgentResultContracts` 镜像冻结 v1 result envelope，并实施纯结果内部不变量；
- `FixedChannelParsingAgentResultDecoder` 使用严格 Jackson 反序列化，拒绝未知字段、尾随内容、重复 JSON key、
  缺失必填字段及非法版本/引用形状；
- canonical QBD/LianTai expected result 可严格 round-trip，负向测试覆盖禁止业务字段、重复 output/material
  disposition、scope/target、fallback ref 与 incomplete mention/review 闭环。

该切片没有 Spring 注册、workflow Port、Provider Adapter、request/evidence builder、跨输入 response validator、
Merger、配置、DDL 或编排接线，因此不改变现有 `parseLegacy`/旧 Recovery 运行行为，也不解除
`HOLD/INTERNAL_ONLY`。验证结果为专项 Java 10/10、相关 Java focused 34/34、Agent 21/21、Python 49/49。
后端全量 `mvn test` 共运行 693 tests，0 failures、6 errors、8 skipped；6 个 error 全部来自旧 v0.2
测试引用已删除的 Trace/schema/fixtures，作为兼容迁移项保留，未恢复过时资产。

## 20. CP0技术授权与nullable material target纠正（2026-08-12）

用户已明确委托Codex决定并推进技术方案；ADR-010技术Gate因此关闭，离线CP1–CP4获准在默认关闭、
fake/mock、无真实客资条件下实施。business required-fact catalog和CP5平台绑定仍是自动业务/真实Provider
放行Gate。

Parser material `target_ref`按已冻结业务/Java契约纠正为required-but-nullable；Parser fact target继续必须为
对象。该修正属于从未发布且持续HOLD的v1.0 schema表达纠错，不创建v1.1双轨，不修改Main Prompt。
Agent专项22/22、Python全套50/50通过；15成员包确定性重建和`--check`通过，当前SHA-256为
`3ee9bbb90107078710958df15901c87cbea7be219ab6cb29540ab348e3f02ff2`。本次hash更新来自canonical
evidence span发布前纠正；Main Prompt SHA、成员数量和HOLD状态不变。

## 21. CP1纯本地核心完成状态（2026-08-12）

默认关闭、无Spring/Provider/数据库接线的CP1核心已完成：

- v1 request/result/final Layer3强类型DTO与严格result decoder；
- 完整Current/History、Unicode code-point、稳定ID/hash的evidence registry和request builder；
- Provider调用前request preflight与返回后的跨输入semantic validator；
- 八数组`FixedChannelLayer3Result`、Parser不可覆盖的deterministic merger和Parser-only failure结果；
- required-fact policy端口；未配置时明确BLOCKER，禁止猜测酒店业务目录；
- provider-neutral Port、test-only fake和无运行态接线的local pipeline。

Java联合focused 59/59、Agent专项22/22、Python全套50/50通过。Profile平台ID/version白名单、持久execution、
真实SuperAgent adapter、主链接线与legacy迁移仍分别属于CP2–CP5；当前没有真实外部调用，发布继续
`HOLD/INTERNAL_ONLY`。

## 22. CP2持久Execution与Worker完成状态（2026-08-12）

默认不注册worker、不调用真实Provider的CP2离线核心已完成：

- Booking PostgreSQL V5定义durable execution、四类normalized artifact、lease、fencing、retry与终态约束；
- repository实施精确run/source/revision入队、幂等冲突核对、`SKIP LOCKED`领取、过期接管、续租和CAS；
- artifact必须为JSON object且hash匹配，同type只能幂等重放，不得用新payload覆盖旧快照；
- 终态前必须已有Parser和同hash Layer3 artifact；`SUCCEEDED`额外要求validated Agent artifact；
- 无Spring接线durable worker支持heartbeat、指数backoff、重试耗尽Parser-only review与崩溃后更高fence恢复；
- local handler从内部loader重建v1 request，重新核对identity/hash/bytes/History revisions/version，只保存
  Parser/fallback、validated Agent result和authoritative Layer3，不保存raw answer。

timeout/unavailable进入持久重试；invalid JSON/schema/profile等可预期契约失败直接形成Parser-only
blocker；内部request/persistence invariant不发布权威Layer3。CP1+CP2 Java联合focused 83/83、Agent
22/22、Python 50/50通过。本checkpoint未连接真实PostgreSQL，未注册scheduler/SourceMessage
loader，未调用SuperAgent/AgentBus/PMS/Opera；runtime继续`HOLD/INTERNAL_ONLY`。

## 23. CP3专属SuperAgent Adapter完成状态（2026-08-12）

默认/production关闭、仅mocked transport验收的CP3已完成：

- 新增`booking.parsing-agent.*`专属properties、独立API key与expected Profile ID栅栏；不回退旧
  Recovery、Booking Business、Debug EML、AgentBus或global key；
- 专属wrapper只复用`SuperAgentOpenApiClientFactory`及既有session/SSE/run-status/recovery transport；
- provider-neutral adapter发送完整AgentRequest JSON，使用hash subject与稳定request/idempotency identity，
  有界限制request/message/response UTF-8 bytes并在独立executor中执行整体deadline；
- Trace被配置门禁强制关闭；实际resolved Profile ID必须与部署值精确一致，published version只作运行审计；
- payload oversize、invalid response和profile mismatch立即形成Parser-only终态review；timeout/unavailable由CP2
  durable worker重试；executor拒绝fail fast，不回退入口/worker线程执行；
- Provider已返回但被本地栅栏拒绝时，只把response hash及安全session/run/Profile/model/token metadata交给
  execution审计，不保存raw answer或完整request。

CP1–CP3与共享SuperAgent transport联合focused 119/119、Agent 22/22、Python 50/50通过。该历史checkpoint未
调用真实SuperAgent/AgentBus/PostgreSQL/PMS/Opera，未填写真实Profile/token，未注册scheduler、
SourceMessage loader、pipeline/worker bean或主链；`booking.parsing-agent.enabled`默认false且production
显式false。后续 CP4 已完成运行接线；business required-fact catalog和CP5平台绑定证据仍未完成，runtime继续
`HOLD/INTERNAL_ONLY`。

## 24. CP4内部运行链接线与验收状态（2026-08-12 历史checkpoint；下游边界已由第26节取代）

CP4 已完成并在 fake/mock、无真实外部调用边界内验收：

- 手工 EML 与 AgentBus 都先持久化/复用 SourceMessage，再以 `source-message-inbox:<id>` 进入 Booking；
  同一 SourceMessage 的重复 frame 使用相同 Booking 幂等键，changed duplicate 保留首份来源事实且不重放下游；
- v1 固定渠道分支对恰好一个完整 Current workbook 调公共 `parse()`；body-only 建零 ParserResult request；
  不完整或多 workbook 调用前失败。该分支不调用 `parseLegacy()`、旧 Recovery 或 `Layer3ContractsV2`；
- Source snapshot loader 读取 exact Current subject/body 与完整有序 History body，History 附件、URL、bytes 均不
  进入 request/evidence；revision、Unicode span、hash 与机器读取审计闭合；
- public Parser artifact、execution enqueue 和 run Parser 状态同一 Booking PostgreSQL 事务；worker 的 normalized
  artifacts、execution completion、权威 Layer3、compatibility projection 与 Context 同一事务。内部失败同事务
  标记 execution/run failed，不发布半成品；
- 权威 `FIXED_CHANNEL_LAYER3_RESULT` 持久保留八数组，包括 `effective_facts[]`、中立
  `structured_mentions[]` 和 `review_items[]`；`EFFECTIVE_PARSED_FACT_SET` 仅供现有 Context 兼容。BEFORE 和
  中立结构只形成版本化 neutral hint，不能变成 Trace、部门、Rate Code、TaskCard 或 PMS 决定；
- Booking PostgreSQL V6 扩展 runtime artifact allowlist；MySQL V30 保存 exact original subject。既有 V5 migration
  未改写。v1/旧 Field Recovery 启动互斥；默认与 production 的 enabled/provider/worker 均为 false；
- 该历史CP4 checkpoint当时不调用 Layer 5 Business Agent：required-fact policy 未配置、有 review 或需要 Agent
  的路径都停在 Context。第26节的direct V2 handoff已以同run continuation取代该下游边界。

验证：CP4 定向 Java 233 tests，0 failures/errors、7 skipped；排除两组明确属于 CP6 的旧 v0.2 测试后，
其余主流程 Java 782 tests，0 failures/errors、8 skipped。原始全量 789 tests 仍有 6 个 FileNotFound errors，
全部来自 `FixedChannelParsingAgentContributionServiceTest` 与 `FixedChannelParsingAgentV02ContractTest` 读取已删除
v0.2 schema/fixtures，CP4 新 failure 为 0。Agent 22/22、Python 50/50、Skill source/archive/manifest 严格校验通过。

CP4 不等于生产启用：真实 Provider/scheduler 未注册，未调用 AgentBus WebSocket、PMS 或 Opera。CP4 收口后，
用户另行批准的非生产 PostgreSQL Gate 已完成V1–V6 migration、幂等启动、restart/lease/fencing/concurrency
smoke；没有调用Provider，测试数据已清理。CP5 前仍须补齐专属 Main Prompt/Skill/Profile/app/token/API
exposure 绑定证据、无 PII 合成 smoke、MySQL V30真实migration smoke、required-fact 业务目录，以及 v1
terminal failure 的人工重放/告警runbook。CP6 之前不得删除
`parseLegacy()`、旧 Recovery、`Layer3ContractsV2` 或旧 contribution service。

## 25. CP4后PostgreSQL基础设施Gate（2026-08-12）

- 目标测试库经只读门禁确认为PostgreSQL 15.14 writable primary、非superuser角色和预期数据库/schema owner；
- 旧`schema_migration`与仓库V001完全一致，八张旧业务表均为空；Flyway以version 0记录旧模型共存，不删除、
  重命名或回填旧对象，随后成功应用V1–V6；
- 两个独立Spring上下文验证进程重启后的过期lease接管：新owner由attempt/fence 1推进到2，旧owner续租和终态
  写入均被拒绝；两个独立连接池并发claim同一execution时只有一个成功；
- 真实PgJDBC暴露`Instant`无法直接绑定`TIMESTAMPTZ`的问题，repository统一以`Timestamp`写入，领域契约不变；
- 正式opt-in PostgreSQL smoke 1/1、repository focused 7/7、当前主流程Java（排除两组CP6历史类）789项均
  0 failures/errors（9 skipped）；合成数据归零、旧业务表仍为空、无跨schema外键；
- 该Gate未授权或启动CP5 Provider/scheduler、CP6删除、MySQL、PMS或Opera。MySQL V30和告警/人工恢复runbook
  仍是自动运行发布前置条件，但不阻塞第27节的受控测试平台绑定与合成契约冒烟。

## 26. CP4 V2 direct handoff 与 Parser FAILED fallback（2026-08-13）

在不改变ADR-010核心决策、冻结Agent Schema/Main Prompt/Skill或Parser契约的前提下，CP4主链补齐如下：

- 当前`@Primary BookingMessageOrchestratorV2Impl`对已验证QBD/LianTai执行公共Parser，持久化ParserResult与
  fallback snapshot，原子enqueue并把同一run标记`AWAITING_PARSING_AGENT`；入口随即返回，不执行Layer4–7；
- worker本地严格校验/merge后，以`FixedChannelLayer3V2Projector`直接生成latest `Layer3ResultV2`；targets、
  bindings、relationships、neutral mentions、display、reviews、evidence、material dispositions完整保留，V2无槽位
  的authority和exact v1审计保存`FIXED_CHANNEL_LAYER3_V2_AUDIT`；
- `BookingV2Layer3Continuation`以相同run执行当前Layer4/5/6并保存现有Layer7 confirmation projection边界；
  callback/终态重放不重复Parsing Agent或Layer5，不创建第二run；
- expected Agent失败生成Parser-only blocker后仍同run fail closed；内部identity/persistence/downstream invariant
  标记execution/run failed，不发布半成品或继续下游；
- Parser FAILED fallback只授权唯一Current `.xlsx`且严格匹配source/revision/attachment/hash/MIME/size；最多
  2 MiB、4 visible sheets、200 visible rows、800 visible scalar cells、512 code points/cell、20,000 total，任一超限
  整体拒绝且不截断。公式、宏、链接、图片、注释、隐藏内容、URL-like scalar、损坏workbook、History附件、
  bytes/Base64和外部下载全部拒绝；worker只读持久snapshot；
- FAILED无fallback仍接收完整Current主题/正文并生成`PARSER_FAILED_NO_AUTHORIZED_FALLBACK`；SUCCESS fallback、
  identity不一致、未知evidence、重复/缺失material disposition、越界cell均fail closed；
- AgentBus收到新固定渠道queued warning时抑制旧realtime dispatch；feature关闭、非固定渠道、未接管路径不变。
- `SOURCE_ROOM_NAME`的raw值与workbook Evidence继续保留；normalized值必须来自Profile Parser已成功解析的
  `sourceRoomType`，V2 projector不得重新归一。无法确定标准房型时不发布该fact而进入material/review；Layer4
  继续exact-only，不新增fuzzy、contains或空格/连字符等价，也不改Roomtype authority/catalog。

补充E2E覆盖QBD与普通LianTai：`ONE BEDROOM SUITE DBL`与直接`ONE-BEDROOM-SUITE-DBL`均在Layer3/V2保留
标准normalized值并由Layer4解析`RM2`，原文/Evidence可审计，Rate/早餐结果一致；Q10、Garden、Pool及未知label
回归通过（QBD均为`GRPA1/含早/BUALUANG`，普通LianTai均为`LBLT/不含早`）。最终本地fake/mock focused为
149 tests（142 executed、7 real-sample skipped、0 failures/errors）。全量后端902
tests、1 failure、0 errors、9 skipped；唯一failure为范围外并行V4 controller用例
`ReservationV4CommandControllerTest.shouldResolveRoomInformationReviewWhenDisplayPayloadAlreadyUsesStableModel`
（expected 200、actual 400），未在本专项修改。未调用真实Provider、AgentBus WebSocket、真实数据库、PMS或Opera。
默认和production的Parsing Agent/provider/worker仍false；CP5、CP6、frontend与外部写入继续HOLD。

## 27. CP5 测试 SuperAgent 绑定与真实契约冒烟（2026-08-14）

用户明确授权调用测试环境 AgentBus/SuperAgent、禁止调用 PMS/Opera 后，CP5 在“测试平台绑定＋受控合成
Provider 调用”边界内完成。AgentBus 是入站消息入口，SuperAgent 是异步 Provider；二者不是同一个调用，
本次没有启动 AgentBus WebSocket 或部署自动 worker。

### 27.1 平台绑定证据

按 ADR-005 使用两个互不共享 Secret 的 external app，公开 Open Agent API 仍由 token 绑定 Profile：

| Agent | Profile ID | 已发布版本 ID | 模型 | 唯一启用 Skill | Main Prompt trimmed SHA-256 |
| --- | --- | --- | --- | --- | --- |
| Booking Business Agent | `85ab8334-4e1c-4716-8ec0-9c3c099cec9b` | `9fed48c0-1f53-4d5a-8ba0-52865c738d83`（v7） | `deepseek-v4-pro` | `booking-desk-event` | `a54a0c12dc2a815af04f970999101f474913c21aafff72c3d1d8d5ead5cdc47f` |
| Fixed-channel Parsing Agent | `ea56cb01-72f0-4ef2-9a73-40cfae1abcd4` | `8b30ebe9-180c-433b-89cf-9c59933b618a`（v8） | `deepseek-v4-pro` | `fixed-channel-core-parsing-agent` | `b59891f4cbd043a35c0ed76ba57d5d733a6d6816e6a2455b899514c568279e2` |

两份平台 Prompt 与仓库独立 Main Prompt 在去除平台归一化的尾部空白后逐字一致；Main Prompt 仍未打入
`.skill` 包。两个 Profile 均通过平台发布检查 11/11，API 与 stream 开启，MCP、memory、Profile calls 和
公开 Trace 均关闭，最大并发为 2。平台 ID 可进入非敏感配置，external app Secret 不写入仓库、文档或日志。

### 27.2 真实 Provider 契约结果

- Booking：Java opt-in smoke通过1/1，耗时52.782秒；真实返回精确命中上述Profile/v7，经过当前
  `BookingBusinessAgentInputV1`投影、严格CandidateDecisionV2 decoder和Layer6 validator，
  `canonical-new-payment`合成样本包含合法`NEW_BOOKING` target。另一次直接transport smoke以general语义得到
  evidence-closed的`GENERAL_NOTIFICATION`。
- Parsing：Java opt-in smoke 通过 1/1，耗时 202.146 秒；真实返回精确命中上述 Profile/v8，使用 LianTai
  canonical 合成 fixture，经过当前 adapter、deadline、严格 decoder 与 response validator，完整答案超过
  2,000 字符且契约校验通过。
- 真实 Parsing 调用暴露平台公共 `message.final` 约 2,000 字符上限：同一 SSE 中较早、
  `finish_reason=stop` 的 assistant message 含完整 JSON，而 `message.final` 是其严格前缀。共享 SSE parser
  已收紧为：只有 core final 是当前完整 stop 内容的严格前缀时才保留完整内容；不同内容的显式 core final
  仍保持权威。Parsing 默认整体等待上限据实由 120 秒提高为 240 秒。

### 27.3 本地配置、验证与未放行边界

- 默认配置已锁定两个已验证 Profile/version；所有 enabled/provider/worker 开关仍为 `false`，production
  继续硬关闭。部署 Secret 未写入任何配置文件。
- SuperAgent transport/config/adapter focused：53 tests，0 failures、0 errors、2 个真实测试默认 skip。
- 后端全量稳定复跑：953 tests，1 failure、0 errors、11 skipped。唯一失败是并行 V4 范围外既有用例
  `ReservationV4CommandControllerTest.shouldResolveRoomInformationReviewWhenDisplayPayloadAlreadyUsesStableModel`
  （expected 200、actual 400），不经过本次 CP5 代码。
- 本次没有连接 AgentBus WebSocket、没有部署或重启应用 worker、没有执行数据库 migration/lease smoke，
  没有调用 PMS/Opera，也没有开始 CP6 删除。

因此，CP5 的测试平台身份、Prompt/Skill/Profile/version 绑定及两条真实 Provider 契约调用已经闭环；要形成
自动运行发布，仍须在指定非生产部署中注入独立 Secret、重启并启用选定 worker，执行完整
AgentBus→SourceMessage→PostgreSQL execution→两 Agent→Layer 6 smoke，补齐监控/告警/人工重放手册和所需
required-fact 业务目录。若部署仍走 MySQL 主路径，还需完成 V30 migration 验证。production、V2→V4
authoritative writer、PMS/Opera 与 CP6 均需单独批准。

## 28. 公开 Trace 主线修订（2026-08-17）

M012 Processing Run全生命周期日志已确认要求当前fixed-channel Parsing Agent调用携带
`include_trace=true`。`booking.parsing-agent.open-api.include-trace`现默认true，显式false由properties校验
在Provider调用前fail closed；第23节“Trace强制关闭”和第27.1节“测试平台公开Trace关闭”仅保留为当时
checkpoint/平台状态，不再表示当前信息系统调用契约。legacy Field Recovery的no-Trace兼容边界不变。

Trace模式只有公开`run.completed(status=success)`和顶层`end`同时存在才成功；core `message.final`只提供
进程内最终JSON，不能替代完成证据。安全`public_trace_events`通过既有adapter进入Parsing execution audit/
回放，可保留`reasoning.summary`等公开摘要；`message.delta`/`message.final`文本不写可持久Trace，URL、Secret、
Authorization、Cookie与CSRF统一脱敏并限长，raw answer与完整request继续不保存。

属性/SSE/安全投影/两条业务主链37项与共享client loopback 4项聚焦测试全部通过。本修订未调用真实SuperAgent、
数据库、AgentBus WebSocket、PMS/Opera，未开启Parsing Agent/provider/worker或production开关；平台能力启用和
目标环境live smoke仍是部署门禁。