ADR-0051：不可变语义编辑与可查询损失报告
状态：已采纳。
背景
Builder 只解决初始编写。导入后的增删、移动、图文修改和跨运行替换需要保留同一棵语义树；把内容转成普通文字会丢失字段、图片、链接和表格来源。警告可见性也不能代表是否发生损失。
决策
- 在模型模块增加
model.edit，不引入布局、字体或文件后端依赖。标准模型保持不可变，未修改的块继续复用；自定义 Block 仍是调用方可信对象。 DocumentEditor接受 Document、PageDocument 和 SectionedDocument。操作按声明顺序构造候选；全树 ID、表格覆盖、Unicode、字段、列表及显式传入的 Note 在发布候选前验证。中间步骤允许暂时悬空引用，但最终不能悬空。- 预检执行有界的纯模型变换并保存确切候选；
Prepared.execute()发布该候选，不接收另一个输入，也不再次执行编辑逻辑。两者均不代表后续文件 I/O 成功。 model.processing提供共享动作、处理方式、位置和报告值。动作优先级为逐操作、逐功能、逐格式、默认；默认 ERROR。WARN 和 IGNORE 采用相同处理，后者只抑制警告。- 跳过匹配、整块和整次请求分别定义。整块在内联格中指拥有该格的 Table；块格内段落以自身为块。跳过会撤销相应范围的暂存修改和损失。返回的
issues、losses和skipped始终可查询。 - 文字匹配为区分大小写、非重叠的字面匹配，不跨段落。跨同样式／同链接运行直接支持；跨不同运行默认失败，明确 DEGRADE 时继承首运行的完整样式与链接。图片、字段和部分字素簇只允许跳过，不能通过降级消费。
- 字素边界由 Java 21 的
Pattern \X确定；所有文字及运行须有合法代理对。不将这一入口推广为任意脚本的语义分词或字体塑形保证。 - 明确的删除、样式修改等是调用方请求的变化，另列
changes。为完成请求而发生的非预期样式／链接继承才列损失。不通过 WARN／IGNORE 放行结构、引用、预算、取消、超时和执行失败。
边界
共享策略值是后续导入和转换的基础，尚不改变旧 Web／DOCX 入口。自定义块只可在原模型中保留，不由此获得任意后端的原样写回能力。Note 必须显式提供；导航、批注和表单等独立引擎配置不在模型编辑结果内，调用方重新导出时仍需提供并验证。