# 架构设计原则

用以下原则裁决 owner、状态、生命周期和抽象力度，只展开与当前决策直接相关的项：

- `information-expert`：职责归拥有所需事实和不变量的对象。
- `single-complete-owner`：同一事实、状态变化和生命周期只有一个权威且完整的 owner；owner 覆盖创建、状态、不变量、生命周期和对外语义。
- `minimal-responsibility-surface`：上层只提供 owner 无法自知的外部事实、用户选择或真实策略点。
- `high-cohesion-low-coupling`：一起变化且必须同步的状态放在一起；调用方不依赖内部细节。
- `tell-dont-ask`：调用业务意图，不读散字段后在 owner 外拼流程。
- `simple-structure-first`：对象、数组、局部函数或现有 owner 足够时，不升级为新 service、manager 或 context。
- `abstractions-pay-rent`：抽象必须消除真实重复、保护不变量或隔离稳定变化点，收益大于名字、文件、跳转和合同成本。
- `evidence-before-generality`：先服务已确认的用户路径和当前调用者；动态发现、多实现路由、registry/resolver/provider 层、namespace、分页、通用 DSL、capability 或扩展槽不能只凭未来可能性进入首版合同。第二个消费者、既有重复 owner、明确排期或昂贵持久迁移属于当前证据；没有证据时，需求出现后再增加通常更便宜。
- `balanced-complexity`：同时审计过小端的错误边界、重复生命周期和迁移债，以及过大端的无消费者抽象、状态和验证面；按全生命周期净复杂度选平衡点，不把最小改动或最大扩展性当目标。
- `constructor-builds-graph`：constructor 只建立同步确定的长期对象图；load/start/reload/stop/dispose 承担副作用。
- `cqs-pure-read`：read/get/list/status 不暗中改变状态；mutation 表达业务意图。
- `equivalence-by-construction`：当多个入口、宿主、实现或持久状态被要求语义等价时，让它们收敛到同一权威 owner、规范表示和状态迁移，并使旧实现与平行路径从正常链路中不可达；禁止靠消费者逐点补丁、复制规则或穷举黑盒场景拼装等价。测试只证明该机制及其不变量未被破坏，不负责用样例数量制造等价性。
- `no-compatibility-by-default`：兼容必须由真实存量证据驱动；不能把旧命名、聊天引用、曾写过或刚发布过的草案虚构成历史消费者。无真实依据时直接更新已知引用并删除旧入口；判定见下节。
- `deletion-first`：新增前先删除重复入口、平行 owner、无语义 wrapper 和过期兼容；不为行数指标损害可读性和合同安全。

判断顺序：先写最小完整路径、事实、不变量、生命周期与已知变化轴；找到 information expert；要求跨入口等价时收敛到同一 owner；列出过小端与过大端成本；删除重复 owner 和透传层；逐个审计新增名词的当前证据与全生命周期净收益；冻结保留、删除、延后项。

输出命中的原则、违反点、推荐 owner、删除与延后项、生命周期边界，以及过小端、平衡点、过大端的关键代价。不能用“可扩展”或“最小改动”单独证明方案正确。
## 真实存量与兼容证据

准备新增或保留旧入口、字段别名、迁移适配、legacy分支或重定向时，先回答：**谁现在依赖它？有什么证据？为何不能直接一起更新？** 兼容设计方承担举证责任，不能把“不知道是否有人用”描述成“有历史存量”。

- 可用依据包括已运行且不能同步升级的实际使用方、真实持久化数据、可定位的独立客户端，以及明确生效的对外版本支持承诺；记录来源与具体影响。真实对外承诺可以构成约束，不以缺少使用遥测为由擅自破坏。
- Git里存在过、聊天里贴过旧路径、刚改过名、AI先前写了一个方案、单独一条发布记录或假想用户，都不单独证明兼容必要性。未落地/未形成存量的机制直接采用正确路径，更新当前引用，删除旧入口；过程历史留在Git或日志，不用跳转文件保存历史。
- 证据存在时仍选择最窄迁移/过渡边界，写清消费者、必要性、可观察方式与删除条件；内部能一起更新的调用方直接迁移，不为一次重命名建立长期双路径。缺少关键证据先核对事实，不默认增加兼容层，也不虚构“绝无用户”。

反例：未投入使用的文档从A改名B，只更新引用并删除A；不能因聊天引用过A就保留跳转。真实客户端仍读取旧协议或已有持久数据时，则先处理其实际升级/迁移约束，不能机械套用删除。

# 公开闭集变体的传播合同

新增或扩展公开 schema、union、protocol、runtime kind 或其它闭集 variant 时，设计必须形成传播矩阵，从 producer 逐项核对真实适用的 parser/validator、序列化与持久化、索引/目录、transport/分发、安装/升级以及最终 runtime/UI consumer。不适用项写明依据。类型编译、本地入口或单个 consumer 通过，不能支持“能力已完整支持”的结论。
