dsh-evolution

LIMITATIONS

Known limitations

以下边界是显式记录在产品行为里的，不通过隐藏 patch 绕过。完整清单与剩余发布风险见 `COMPATIBILITY.md` 与 `RELEASE.md`。 1. **领域 evaluator 仍是 advisory。** `promotionGates` 是生产权威；领域 evaluator 提供记录在案的决策与“识别到 regression 即否决”的硬性 veto，但本插件尚未接入宿主提供的独立生产 baseline/test 指标。因此只有自定义指标时 evaluator 会返回 `reject`（不阻塞），真实独立指标接入待补。 2. **`continuous/` 与 `governance/` 领域模块已提取并单测通过，但未接入 orchestrator 实时循环。** 它们是纯领域实现，当前不启动第二套 Engine 或 scheduler；旧 `dockyard` 数据以文件形式完整保留，可用 `domainSeed` 载入。 3. **晋升是 Host-only，且不是安全沙箱。** 只有持久化晋升拒绝带 `client` 的 Package（`evolution_trial` 允许 Client half）；持久化源码走合作式 `Function(hostCode)()` gate，始终需要可信审批。 4. **依赖内部 / 未文档化宿主接口。** introspection 使用 `ctx.registry.values()`、`ctx.reflect.props/_getImpl()`、`ctx.events._hooks`、Fiber effect 元数据；Include adapter 使用公开但未文档化的 `root.data` / `store` / `Entry.fiber` / `Fiber.state` / `ctx.get()`。这些不是稳定跨版本公共契约，升级 DSH 前必须重新验收；`runtime.internal-api` 会逐探针报告可用性，缺失时降级为 `degraded`。 5. **手工 dispose 底层 bundle Fiber 的路径无法自我断言。** `disposeTrial` 走官方 runner 的 stop/undefine；直接 dispose bundle Fiber 会让探针自身注入的 `tools` 失活，因此不作为用户关闭流程。 6. **Trial 期间持续存在的外部漂移会拒绝恢复。** 恢复签名比较前后可观察清单，不重建基线，因此不能记录已自行恢复的瞬态漂移，也不能证明任意合作式代码或 disposer 的全部外部效果。 7. **事件签名密钥没有轮换 / 吊销流程。** `event-bridge.key` 只在该数据根首次创建，禁用与卸载都不会删除。 8. **file 后端的失败记忆是 last-writer-wins，`save()` 不做 fsync。** 同一数据根下两个 host 实例同时归档时，后写者会覆盖整份快照；断电时最后一次 `record()` 可能丢失。跨进程锁保护领域归档事务，不保护这个文件。它是有界、advisory 的失败记忆（`promotionGates` 仍是生产权威），单实例使用不触发。 9. **指标 ID 不是授权凭证。** 兜底 ID 使用 `crypto.randomUUID()`，同一记录只生成一次；调用方仍可提供 ID，不能把可猜测或不可猜测的 ID 当作权限控制。 10. **不提供供应链签名。** 未做 npm 发布、代码签名 / provenance（SLSA）或 SBOM；已启用 GitHub Code Scanning。 11. **宿主版本只在验收后扩展。** 列表之外的宿主由 `host.version` 报 `blocked`，不使用宽松范围绕过诊断阻断。 12. **`0.2.1-alpha.1` 与 `0.2.1-rc.2` 的 npm dist-tag 会移动。** 验收记录精确版本号。这里的日期取自一次历史验收运行写下的 `startedAt`（2026-10-17，当时该证据记录的候选是 `0.2.0-rc.13`）；`docs/evidence/dsh-0.2.1-rc.2.json` 每次重新固定都会重跑重写，当前 `startedAt` 已不是该日期。该日期查询 npm registry 得到 `alpha` 指向 `0.2.1-alpha.5`、`latest` 指向 `0.2.0-rc.2`、`next` 指向 `0.2.1-rc.2`。这些 tag 值不在验收证据中，是该日期对 registry 的只读快照；tag 后续会移动，仓库声明的仍是三个精确版本号。 13. **冷档案读取缓存依赖文件系统的纳秒 mtime，并占用内存。** 解析结果按“设备 + inode + 字节数 + 纳秒 mtime”缓存；在 mtime 精度只有秒级的文件系统上，同尺寸原地重写可能读不到新内容（插件自己追加会改变字节数，不受影响）。常驻成本约 **0.7 MiB heap / MiB 冷档案**（例如 28 MiB 冷档案约 20 MiB）；`compact()` 后丢弃重建。数字、假设和复现脚本见 `RELEASE.md` 第 6 节第 20 条与 `docs/performance/archive-read-cost.md`。 14. **只带显式 `knowledgeKey`、没有任何身份维度的知识事件会塌缩到同一个身份。** 已知、本轮未修：六个维度全空时身份落在常量桶（`knowledge:a615…`），不同显式 key 会合并成一行。本插件所有生产写入路径都会同时给出维度，所以普通使用遇不到；只有外部代码直接调用 `EvolutionMemory.recordKnowledgeEvent()` 且只给 `knowledgeKey` 时会触发。修复会改变持久化身份语义（需要迁移决策）并改动冻结身份基线。 15. **UTF-16 长度超过 240 的身份维度会得到新身份。** 旧实现按 UTF-16 code unit 只保留前 239 个单位（还会切在代理对中间），因此后缀不同的事实会被合并。现在前缀按 code point 切，并附完整文本的 16 位摘要；这类事实会被区分，旧行保留到 retention 到期。归一化后 UTF-16 长度 ≤ 240 的维度逐字节不变、身份不变；长度 > 240 时身份改变：code point 数 ≤ 240 时整段保留，> 240 时保留前 222 个 code point 并附 `…#` 与 16 位十六进制摘要，结果总长 240 个 code point。因此既有记录的身份、命中与保留结果只在后一类维度上变化。 16. **执行事件日志与领域标记表随历史单调增长；回收是显式 owner 操作，不自动运行。** `execution-events.jsonl` 每个执行事件一行（含 measurement / promotion / canary 事实），领域文档的 `applied` 每个去重身份一个 64 位十六进制 MAC（上限 9 类事件 × experiment 数）。代价是：启动时按日志字节线性读取并逐条验签，`flush()` 每个 pass 读取并 HMAC 整份已提交前缀并对整张标记表重算摘要，领域文档随标记数增长。`evolution_maintain` 是唯一的回收入口：`dryRun` 只报告字节与记录数，`confirmation: true` 才执行。归档侧沿用既有语义压缩（终态记录折叠为聚合行），被替换的 sealed 段以 `pending.files` 的 `removed` 条目在同一事务里发布，**只有新文件全部安装成功之后才删除**；日志侧先把被丢弃记录携带的 promotion / measurement 事实写进 evidence sidecar（`*.evidence.json`，hydration 链中优先级高于事件桥），再提交裁剪后的 marker 与 `retention` floor（被裁 marker 的 keyed 链、累计的裁剪数与被丢弃字节/记录数、原文件摘要 `prior`、保留尾部摘要 `tail`），最后才截断那些已证明被吸收的字节。顺序是安全论证的一部分：**先提交 floor、后截断**。floor 记录计划时整份日志的摘要（`prior`）与截断后保留前缀的摘要（`tail`），所以“floor 已提交、截断未发生或被打断”是一个可以由下一次 replay 幂等完成的已提交事务（先核对 `prior` 再重写，再核对 `tail`），不会变成永久拒绝；反过来（先截断、后提交）会让 floor 描述已经不存在的字节，第二次回收崩溃后无法恢复。replay 只信任 floor 描述的字节：日志必须要么以保留尾部开头（`continuation`），要么**恰好**是 floor 记录的 `prior` 文件（此时先幂等完成那次已提交的截断）。两者都不是时以 `E_DOMAIN_EVENT_LOG_FLOOR_MISMATCH` 拒绝吸收，而不是重放可能已裁剪 marker 的记录——空文件也一样：空日志不能证明保留字节没有丢，而接受它会让下一次追加造出永远对不上 floor 的头部，所以这里直接失败、把现场留给操作者（恢复那段保留字节，或换一个数据根）。