# ReviewDocument 机器投影 schema 1.0

本文记录 `mdpolish.review.review_document_to_dict()`、`render_json_report()` 和 `parse_json_report()` 当前稳定的跨进程查询
口径。公共 Python 类型和运行校验以代码与测试为准；生产契约的设计理由见
[`0012-review-document-machine-projection.md`](../design/0012-review-document-machine-projection.md)，只读解析与本地页面边界见
[`0014-generic-local-reviewer.md`](../design/0014-generic-local-reviewer.md)。

## 1. Schema 身份与入口

每个投影都包含：

```json
{
  "schema_name": "mdpolish.review",
  "schema_version": "1.0"
}
```

schema 版本独立于 `mdpolish` 包版本和 modifier 版本。公共入口是：

```python
from mdpolish.review import parse_json_report, render_json_report, review_document_to_dict

payload = review_document_to_dict(review, detail="summary")
json_text = render_json_report(review, detail="full")
parsed = parse_json_report(json_text, expected_detail="full")
```

前两个生产入口只接受内存中的 `ReviewDocument`。JSON reporter 编码同 detail 的正式 dict，不定义另一套字段，也不读写文件。
reader 只接受内存字符串，返回新的普通 JSON 基本值容器；它不接收路径，也不恢复 `ReviewDocument`。

## 2. 顶层字段

| 字段 | JSON 类型 | 口径 |
| --- | --- | --- |
| `schema_name` | string | 固定为 `mdpolish.review` |
| `schema_version` | string | 当前固定为 `1.0` |
| `detail` | string | `summary`、`changes`、`full` |
| `status` | string | `success`、`failed`、`unstable` |
| `current_kind` | string | `success_output`、`partial_output` |
| `stages_complete` | boolean | 是否能证明全部 modifier transform 阶段完成 |
| `hash_contract` | object | 所有 Markdown 哈希的算法、编码和规范化口径 |
| `coordinate_contract` | object | span、行列和物理换行口径 |
| `input` | object | 输入文本摘要；`full` 增加正文 |
| `current` | object | 当前文本摘要；`full` 增加正文 |
| `counts` | object | modifier、完成阶段、实际修改、错误和残留候选数量 |
| `modifiers` | array | 全部 modifier 的权威顺序 |
| `stages` | array | 已完成 transform 阶段的权威顺序 |
| `errors` | array | Pipeline 记录的错误顺序 |
| `residual_proposals` | array | 只在 `changes` / `full` 出现；候选未应用 |

JSON object 成员顺序不构成语义。所有 array 顺序构成语义，消费者不得重新按 ID、哈希或文本排序后再解释位置。

## 3. 内容暴露等级

| 内容 | `summary` | `changes` | `full` |
| --- | ---: | ---: | ---: |
| 状态、哈希、位置口径和计数 | 是 | 是 | 是 |
| modifier id、版本和位置 | 是 | 是 | 是 |
| modifier 参数和 applicability | 否 | 是 | 是 |
| 阶段前后哈希、长度和修改数 | 是 | 是 | 是 |
| 实际修改的 reason、位置、`before` / `after` | 否 | 是 | 是 |
| 稳定错误代码和错误位置 | 是 | 是 | 是 |
| Python 诊断类型和错误消息 | 否 | 是 | 是 |
| 残留候选的 reason、`expected_text` / `replacement` | 否 | 是 | 是 |
| 输入、当前和阶段完整 Markdown | 否 | 否 | 是 |

默认是 `summary`。被隐藏的内容键不存在；`null` 和空字符串都不是“已隐藏”的替代值。`summary` 不含直接正文，但仍含
modifier identity、哈希和计数，不自动等于匿名、脱敏或适合公开传播。

## 4. 固定口径

### 4.1 哈希

```json
"hash_contract": {
  "algorithm": "sha256",
  "encoding": "utf-8",
  "normalization": "none"
}
```

哈希是精确 Markdown 的 `sha256(markdown.encode("utf-8")).hexdigest()`。不规范化 Unicode、BOM、空白、末尾换行或
CR/LF/CRLF。`Change.before_sha256` / `after_sha256` 是完整阶段快照哈希，不是修改片段哈希。

### 4.2 坐标

```json
"coordinate_contract": {
  "offset_unit": "unicode_code_point",
  "span_index_base": 0,
  "span_end": "exclusive",
  "location_index_base": 1,
  "physical_line_endings": ["lf", "crlf", "cr"]
}
```

- `span` 相对于所属 `ReviewStage.before_markdown`，使用 0-based Unicode code point 半开范围；
- `location.line` / `column` 指向 `span.start`，使用同一阶段修改前文本中的 1-based Unicode code point 位置；
- CRLF 形成一个物理换行，但在 offset 中占两个 code point；
- 不提供最终全文坐标、UTF-16、byte offset 或终端显示宽度。

所有整数都在 `0..2**53-1`；参数中的有符号整数在 `-(2**53-1)..2**53-1`。所有 float 必须有限。

## 5. 嵌套对象

### 5.1 文本摘要

`input`、`current` 以及 stage 的 `before` / `after` 都至少包含：

```json
{
  "sha256": "64 位小写十六进制",
  "code_point_length": 123
}
```

`full` 增加 `markdown`。`current.markdown` 是否为正式输出必须看根字段 `current_kind`；`partial_output` 不能当作成功结果。

### 5.2 Counts

```json
"counts": {
  "modifier_count": 3,
  "completed_stage_count": 2,
  "change_count": 5,
  "error_count": 1,
  "residual_proposal_count": 0
}
```

`change_count` 只统计已完成 stage 中的实际 `ReviewChange`，不含 residual proposal edit。零修改的完整 stage 仍计入
`completed_stage_count`。

### 5.3 Modifier

所有 detail：

```json
{
  "position": 0,
  "modifier_id": "example.normalize",
  "version": "1.0.0"
}
```

`changes` / `full` 增加 `parameters` 和 `applicability`。`parameters` 是有序 array-of-pairs；所有内部 tuple 继续投影成
array，不根据二元组外形猜成 JSON object：

```json
"parameters": [
  ["pattern", " {2,}"],
  ["replacement", " "]
]
```

### 5.4 Stage

所有 detail：

```json
{
  "modifier_position": 0,
  "before": {"sha256": "...", "code_point_length": 20},
  "after": {"sha256": "...", "code_point_length": 18},
  "change_count": 1
}
```

`changes` / `full` 增加 `changes` array；`full` 还给两个文本摘要增加 `markdown`。`modifier_position` 引用根
`modifiers[position]`，不复制 modifier 元数据。

### 5.5 实际 Change

只在 `changes` / `full` 出现：

```json
{
  "proposal_index": 0,
  "edit_index": 0,
  "reason": "修改原因",
  "location": {"line": 3, "column": 7},
  "span": {"start": 24, "end": 31},
  "before": "原片段",
  "after": "新片段",
  "before_sha256": "修改前完整阶段哈希",
  "after_sha256": "修改后完整阶段哈希"
}
```

### 5.6 Error

所有 detail 都含 `code`、`stage`、modifier 位置与身份。`changes` / `full` 再增加诊断用的 `diagnostic_type` 和
`message`。

| `stage` | 稳定 `code` |
| --- | --- |
| `preflight` | `run.preflight_failed` |
| `transform` | `run.transform_failed` |
| `final_review` | `run.final_review_failed` |

代码只稳定表达失败阶段。`diagnostic_type` 是 Python 异常类名，`message` 是人类消息，不能作为稳定程序分支条件。当前
`RunError` 没有保存更细的稳定原因；不能从类名或消息猜造更细代码。

### 5.7 Residual proposal

只在 `changes` / `full` 出现：

```json
{
  "modifier_position": 0,
  "proposal_index": 0,
  "snapshot_sha256": "当前完整快照哈希",
  "reason": "候选原因",
  "edits": [
    {
      "edit_index": 0,
      "span": {"start": 10, "end": 15},
      "expected_text": "原片段",
      "replacement": "候选片段"
    }
  ]
}
```

它是 final review 证据，没有应用，不进入 stage 或实际 change count。

## 6. JSON 编码

`render_json_report()` 固定使用标准库 JSON 的以下语义：

- `ensure_ascii=False`；
- `allow_nan=False`；
- `indent=2`；
- 无 UTF-8 BOM；
- 返回字符串末尾不额外添加换行。

返回值是 Python `str`。调用方保存或发送时负责 UTF-8 编码、媒体类型、权限和保留周期。库不接收路径或文件对象。

## 7. 只读解析保证

```python
from mdpolish.review import ReviewParseError, parse_json_report

payload = parse_json_report(json_text)
full_payload = parse_json_report(json_text, expected_detail="full")
```

`expected_detail` 可以省略，也可以显式指定 `summary`、`changes` 或 `full`。报告自己的 detail 不匹配时失败。返回结果是本次
解析新建的 dict/list；修改它不会恢复或改变 producer 侧的 `ReviewDocument`。

所有 detail 都检查：

- JSON object key 唯一，字符串可以严格编码为 UTF-8，整数和浮点数满足第 4 节范围；
- schema、detail、enum、稳定错误代码、数组顺序、引用位置和计数；
- `summary` / `changes` 没有越过各自的正文暴露边界；
- 状态、`current_kind`、错误阶段、完成阶段和残留候选相容。

`summary` 和 `changes` 没有完整阶段正文，reader 不会声称能验证不存在的文本。`full` 另外检查：

- input、current、所有 stage before/after 的码点长度和 SHA-256；
- 第一个阶段从 input 开始，相邻阶段首尾相接，最后一个完成阶段等于 current；
- Change span 的原文、位置、哈希、proposal/edit index、冲突和正式报告顺序；
- 用核心共用的精确编辑原语重放每个 Change 批次，结果与 stage after 完全相同；
- 零修改阶段的 before 和 after 完全相同；
- residual edit 的原文、范围、顺序和冲突。

任一步失败都抛出 `ReviewParseError`。顶层错误消息只包含字段路径和契约类别，不包含正文、modifier 参数、reason 或诊断消息。
reader 不调用 Modifier，不修复、截断或猜测损坏结果。

这是只读解析，不是反序列化。返回 dict 不能重新运行 Pipeline、恢复 Python 模型或获得原始 `TransformResult` 的权威身份。

## 8. 兼容策略

`schema_version` 使用 `MAJOR.MINOR`：

- 删除、改名、改类型、改变位置/哈希/顺序语义、改变已有 enum 或错误代码含义，需要提升 major；
- 在相同 detail 中新增更高敏感度的正文承载字段，需要提升 major，或增加必须显式请求的新 detail；
- 不改变旧字段解释的非正文可选字段，可以提升 minor；
- 实现修正为重新符合已有契约，不改变 schema 版本；
- schema 版本不跟随 Python 包版本自动变化。

同一 major 的消费者必须忽略未知 object 字段，但必须保持 array 顺序；不得把未知状态当成 `success`。消费者应拒绝自己不
支持的 schema major。

schema `1.0` 仍是单向生产契约。官方 reader 接受同一 major 的已知字段语义，并忽略未知 object 字段的语义；未知状态、
detail、enum 或坐标契约仍会失败。当前没有 `ReviewDocument` 反序列化器、JSON Schema 文件、历史迁移器或数据库 schema。