跳到主要内容

设计笔记(仓库)

架构真源在仓库里,不在本站:docs/design/。设计文档 是面向公众的叙述;当它与真源冲突时,以真源为准。本页是索引——每篇设计笔记都列在这里,新增的不会再「隐形」。

面向产品的摘要在站内:Abs、语言语义、HOF 关系、边界、CLI 参考。

真源​

设计笔记覆盖内容状态
kernel-merge.md类型系统:Abs = shape × term × pred × conf 单轨制(@nudojs/core/src/algebra)真源
cli-semantics.mdCLI 产品面、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.mdHOF 关系(fnRels / entryShapes),不造泛型语言已实施(P3 暂缓)
persistent-cache.md.nudo/cache 磁盘层 + ~/.cache/nudo/deps harvest;fail-open 规则已落地
cache-invalidation.md进程内会话缓存的失效契约契约 + 回归钉扎
lsp-client-gaps.mdLSP 客户端 UI 缺口——LSP 客户端 背后的跟踪表现行
limitations.md仍约束决策的限制与未决项持续维护
nan-finite-contracts.mdNaN 感知的契约词汇(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 会红。