From d5562b05b70d091a63d6c8a634c45f147a9e826d Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Sun, 13 Sep 2026 16:33:25 +0800 Subject: [PATCH] docs: record approved historical type compatibility policy --- refactor/compatibility.md | 2 +- refactor/decisions.md | 1 + refactor/factory-compatibility-decision.md | 14 +++++++------- refactor/type-compatibility-policy.md | 22 ++++++++++++++++++++++ 4 files changed, 31 insertions(+), 8 deletions(-) create mode 100644 refactor/type-compatibility-policy.md diff --git a/refactor/compatibility.md b/refactor/compatibility.md index 6a0d27bf2..ec5e9c215 100644 --- a/refactor/compatibility.md +++ b/refactor/compatibility.md @@ -29,7 +29,7 @@ BASE 阶段必须同时采集：本分支起点源码、实际 npm 已发布 tar | --- | --- | | 内部重排、无可观察变化 | 原样保留契约，增加回归测试 | | 已公开且正在使用的功能 | 兼容门面转发，保持入口、返回值和时序；不能要求所有调用方改代码 | -| 源码与声明不一致 | 分别记录运行时和 TS 用户影响，先加精确重载或扩展类型；无法兼容时标为待决，不能静默收紧 | +| 源码与声明不一致 | 分别记录运行时和 TS 用户影响，先加精确重载或扩展类型；已获确认的历史声明冲突按[统一规则](type-compatibility-policy.md)执行，其余实质差异不能静默收紧 | | 文档描述了未实现的行为 | 核实发布包和使用样例，独立修复或明确记录；不把错误描述当作重构任务直接实现 | | 明确缺陷 | 建立复现、比较旧行为、记录修正差异和发布级别，避免为通过差分测试而永久保留缺陷 | | 无法验证的历史路径 | 标记缺证据及影响，不能计入兼容通过 | diff --git a/refactor/decisions.md b/refactor/decisions.md index cb5c50e12..2973c7cf9 100644 --- a/refactor/decisions.md +++ b/refactor/decisions.md @@ -29,6 +29,7 @@ | ADR-022 | 采用方向 | Chrome 不可用时使用 Codex 内置浏览器 | 用户明确授权；记录实际环境和能力范围，必要设备测试仍独立验收 | | ADR-023 | 已验证于 Audio Track | 参数类型纠正会破坏旧推断时，默认入口保留兼容类型，/runtime 复用相同运行文件提供精确类型 | PKG-AUDIO-04 的 Parameters 与无注解 update 实现证明 Partial/重载仍可能破坏旧用户；沿用核心的类型分层方向，具体包需独立编译与入口身份验证，不增加第二套实现或用 any 绕过 | | ADR-024 | 已验证于 CORE-24 | 切源播放意图归属当前操作，在公开 play/pause 命令入口更新，内部暂停不覆盖用户意图 | Audio-05 三引擎复现连续切源最终停在 0；新操作继承未完成操作的意图，显式暂停及其修订号终止旧恢复副作用，过期 Promise 仍保留原结算语义；不依赖用户回调之后才执行的事件监听器 | +| ADR-025 | 用户已确认，待实施验证 | 历史声明冲突以最新已发布类型形状为准，较早差异提供迁移，合法旧JS继续兼容，/runtime提供精确类型 | 2026-09-13明确答复“接受这条规则并继续”；覆盖Canvas/Ambilight/VTT Thumbnail/Multiple Subtitles，见[type-compatibility-policy.md](type-compatibility-policy.md)，不等同任务完成或发布授权 | ## 开始实现前需补齐的决定 diff --git a/refactor/factory-compatibility-decision.md b/refactor/factory-compatibility-decision.md index 9969adae2..9482660db 100644 --- a/refactor/factory-compatibility-decision.md +++ b/refactor/factory-compatibility-decision.md @@ -1,7 +1,8 @@ -# Canvas / Ambilight 工厂类型兼容取舍（待确认） +# Canvas / Ambilight 工厂类型兼容取舍（已确认，待实施） PKG-FACTORY-01 已复现当前声明的问题，但尚未修改生产声明，不能标记完成。 -本页推荐方案需要用户确认；Ads 的单独类型修正授权不适用于这里。 +2026-09-13用户已接受统一规则，见[确认记录](type-compatibility-policy.md)。本页推荐 +方向已授权；此前Ads单项授权之外的待决状态由此次确认替代，实施和验证仍须完成。 ## 问题与真实发布对照 @@ -64,15 +65,14 @@ module.default({}) 完整候选声明由 `scripts/factory-assignability.mjs` 的 declaration(pkg, 'latest-default') 生成。当前它只是可编译的核心签名提案，尚未加入全部命名类型、格式包装和安装验收， -不属于已经实施或批准的生产修复。 +属于已批准方向，尚不属于已经实施并验证的生产修复。 ## 决策与后续 -- 状态：待用户确认是否接受上述 1.0.0 TypeScript 导入迁移；不把大版本升级视为自动授权。 -- 若接受：修改两包声明和包装，补充 RuntimeFactory、全工厂赋值测试、编辑器和包内文档， +- 状态：用户已明确接受上述较早版本TypeScript导入迁移；不因批准而跳过验证。 +- 下一步：修改两包声明和包装，补充 RuntimeFactory、全工厂赋值测试、编辑器和包内文档， 重建并执行真实安装消费矩阵；保留逐版本负例，验证 JS 产物与浏览器证据，单独完成任务提交。 -- 若不接受：保留该风险与发布依赖，继续评估显式兼容入口；不把 optional .default、any、 - skipLibCheck 或删除历史消费者当作修复。 +- 仍不得把optional .default、any、skipLibCheck或删除历史消费者当作修复。 - PKG-CANVAS-05、PKG-AMBILIGHT-05、REL-01 仍依赖本任务完成。 证据：[编译矩阵](baselines/factory-compatibility-proposals.json)、 diff --git a/refactor/type-compatibility-policy.md b/refactor/type-compatibility-policy.md new file mode 100644 index 000000000..d5b1184f8 --- /dev/null +++ b/refactor/type-compatibility-policy.md @@ -0,0 +1,22 @@ +# 已确认的历史类型冲突规则 + +2026-09-13，用户对以下完整问题回答“接受这条规则并继续”：保留各包最新已发布 +版本的旧类型形状，较早版本的冲突写清迁移说明；所有合法旧JavaScript调用继续 +兼容，新增/runtime提供准确类型。本次明确涉及Canvas、Ambilight、VTT Thumbnail、 +Multiple Subtitles。此确认独立于此前Ads的参数推导修正。 + +## 实施约束 + +- 从真实npm归档确定最新已发布声明；不得把重构中的候选声明当成兼容基线。 +- 保留默认工厂的完整赋值关系、参数必需性、Parameters/ReturnType及模块形状， + 不以附加必填default属性或可选重载破坏普通替代函数。 +- 正确运行时异步结果、额外可选调用及自default别名通过独立/runtime类型描述， + 与根入口复用同一运行实现。 +- 对较早export=/export-default等互相矛盾的声明，保留历史失败证据并给出迁移 + 示例；这些被批准的类型差异不再等待重复确认。 +- 所有合法旧JS入口仍验证，不将类型取舍扩展成任意运行时破坏或删除旧分发入口。 +- 真实安装消费者、正反例、编辑器声明和包内文档通过后才完成相关任务。批准方案 + 不等同实现完成、风险自动关闭或发布授权。 + +适用任务：PKG-FACTORY-01、PKG-VTT-THUMB-04、PKG-MULTI-SUB-04。后续记录必须注明 +采用哪一个真实版本、哪些旧类型用法需要迁移，以及/runtime的具体形状。