Design notes (repo)
Architecture truth lives in the repository, not on this site: docs/design/. The Design Document is the public narrative; when it and a truth source disagree, the truth source wins. This page is the index — every design doc is listed here so new ones cannot go missing.
Product-facing summaries live on the site: Abs, Language semantics, HOF relations, Limits, CLI reference.
Truth sources
| Design note | Covers | Status |
|---|---|---|
kernel-merge.md | The type system: Abs = shape × term × pred × conf as the single track (@nudojs/core/src/algebra) | Truth source |
cli-semantics.md | CLI product face, L1/L2 gates, any vs unknown, test case reports, check JSON | Truth source |
directive-scope.md | Directive scoping: function-level directives bind the nearest AST Function; single-source extraction contract (parser) | Contract |
evaluation.md | Single evaluation engine (transpile → exec), set semantics, fail-closed behavior | Landed |
refine-derivation.md | Three-tier effective contract: handwritten → generated → implicit; sidecar binding; drift codes | Landed |
hof-relations.md | HOF relations (fnRels / entryShapes) instead of a generic language | Implemented (P3 deferred) |
persistent-cache.md | .nudo/cache disk layer + ~/.cache/nudo/deps harvest; fail-open rules | Landed |
cache-invalidation.md | In-process session-cache invalidation contract | Contract + regression pins |
lsp-client-gaps.md | LSP client UI gaps — the tracked list behind LSP clients | Current |
limitations.md | Limitations that still constrain decisions; unresolved items | Living |
nan-finite-contracts.md | NaN-aware contract vocabulary (number().finite()) and sound relation-complement accumulation for sequential guard clauses (issue #185) | Landed (2026-11-14) |
generator-laziness.md | Generator bodies still run eagerly (Bug 212): why lazy generators are not implementable inside the current eager-snapshot model, the affected consumers, and the minimal transpile-side path to a sound over-approximation | Architecture debt (documented) |
architecture-debt.md | The 10 items blocked at the evaluation-model / Abs-representation layer (eager generator bodies, missing throws channel on relation/apply results, union dispatch by member name, no overload slot on fn shapes) — why they need dedicated scheduling | Architecture debt (ledger) |
Decision records
| ADR | Covers | Status |
|---|---|---|
adr-0001-semantic-index-and-evidence.md | Analysis-face consistency: one binding index (SemanticIndex) + typed evidence with fail-closed degradation (Evidence<T>); root-cause plan for the 34-bug audit (2026-11-14) | Accepted (stage 1 slice 4.2) |
Process notes
| Note | Covers |
|---|---|
plans/ | Dated working plans (e.g. removing the second engine) — history, not contracts |
docs/reports/ | Measured baselines (env coverage, OSS/agent performance) quoted by Performance and AI-native DX |
docs/examples/ | The CI-pinned example matrix (pnpm run verify:examples) |
How these notes are kept honest
- The docs site consumes them one-way: rendering rules and gates are described in Contributing — Docs maintenance.
- Each note carries a
Statusline;landednotes describe shipped behavior,contractnotes describe invariants with tests. - This index is gated: adding a file under
docs/design/without listing it here failspackages/website/tests/docs-coverage.test.ts.