设计笔记(仓库)
架构真源在仓库里,不在本站:docs/design/。设计文档 是面向公众的叙述;当它与真源冲突时,以真源为准。本页是索引——每篇设计笔记都列在这里,新增的不会再「隐形」。
面向产品的摘要在站内:Abs、语言语义、HOF 关系、边界、CLI 参考。
真源
| 设计笔记 | 覆盖内容 | 状态 |
|---|---|---|
kernel-merge.md | 类型系统:Abs = shape × term × pred × conf 单轨制(@nudojs/core/src/algebra) | 真源 |
cli-semantics.md | CLI 产品面、L1/L2 门禁、any 与 unknown、test 用例报告、check JSON | 真源 |
directive-scope.md | 指令作用域:函数级指令绑定 AST 最近 Function;抽取单源契约(parser) | 契约 |
evaluation.md | 单求值引擎(transpile → exec)、集合语义、fail-closed 行为 | 已落地 |
refine-derivation.md | 三层有效契约:手写 → 生成 → 隐式;侧车绑定;drift 诊断码 | 已落地 |
hof-relations.md | HOF 关系(fnRels / entryShapes),不造泛型语言 | 已实施(P3 暂缓) |
persistent-cache.md | .nudo/cache 磁盘层 + ~/.cache/nudo/deps harvest;fail-open 规则 | 已落地 |
cache-invalidation.md | 进程内会话缓存的失效契约 | 契约 + 回归钉扎 |
lsp-client-gaps.md | LSP 客户端 UI 缺口——LSP 客户端 背后的跟踪表 | 现行 |
limitations.md | 仍约束决策的限制与未决项 | 持续维护 |
nan-finite-contracts.md | NaN 感知的契约词汇(number().finite())与顺序守卫子句的关系补集累积(issue #185) | 已实施(2026-11-14) |
generator-laziness.md | 生成器体仍在构造期跑完(Bug 212):为什么在现有 eager 快照模型下无法实现惰性生成器、受影响的消费面清单,以及把它变成 sound 过近似的最小转译侧路径 | 架构债(已登记) |
architecture-debt.md | 卡在求值模型 / Abs 表示层的 10 条欠账(生成器体 eager、relation/apply 结果缺 throws 通道、union 按成员名分派、fn 形状无 overload 承载位)——为什么它们必须单独排期 | 架构债(台账) |
决策记录(ADR)
| ADR | 覆盖内容 | 状态 |
|---|---|---|
adr-0001-semantic-index-and-evidence.md | 分析面事实一致性:单一绑定索引(SemanticIndex)+ 显式降级证据(Evidence<T>),2026-11-14 审计 34 条 bug 的根因方案 | 已接受(阶段 1 切片 4.2) |
过程记录
| 笔记 | 覆盖内容 |
|---|---|
plans/ | 带日期的过程计划(如删除第二引擎)——历史,不是契约 |
docs/reports/ | 实测基线(env 覆盖率、OSS/agent 性能),性能 与 AI 原生 DX 引用它们 |
docs/examples/ | CI 钉住的示例矩阵(pnpm run verify:examples) |
这些笔记如何保鲜
- 文档站单向消费它们:渲染规则与门禁见贡献指南 — 文档维护。
- 每篇笔记都带
Status行;landed描述已上线行为,contract描述有测试的不变量。 - 本索引有门禁:往
docs/design/加文件而不在这里登记,packages/website/tests/docs-coverage.test.ts会红。