Skip to main content

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 noteCoversStatus
kernel-merge.mdThe type system: Abs = shape × term × pred × conf as the single track (@nudojs/core/src/algebra)Truth source
cli-semantics.mdCLI product face, L1/L2 gates, any vs unknown, test case reports, check JSONTruth source
directive-scope.mdDirective scoping: function-level directives bind the nearest AST Function; single-source extraction contract (parser)Contract
evaluation.mdSingle evaluation engine (transpile → exec), set semantics, fail-closed behaviorLanded
refine-derivation.mdThree-tier effective contract: handwritten → generated → implicit; sidecar binding; drift codesLanded
hof-relations.mdHOF relations (fnRels / entryShapes) instead of a generic languageImplemented (P3 deferred)
persistent-cache.md.nudo/cache disk layer + ~/.cache/nudo/deps harvest; fail-open rulesLanded
cache-invalidation.mdIn-process session-cache invalidation contractContract + regression pins
lsp-client-gaps.mdLSP client UI gaps — the tracked list behind LSP clientsCurrent
limitations.mdLimitations that still constrain decisions; unresolved itemsLiving
nan-finite-contracts.mdNaN-aware contract vocabulary (number().finite()) and sound relation-complement accumulation for sequential guard clauses (issue #185)Landed (2026-11-14)
generator-laziness.mdGenerator 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-approximationArchitecture debt (documented)
architecture-debt.mdThe 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 schedulingArchitecture debt (ledger)

Decision records​

ADRCoversStatus
adr-0001-semantic-index-and-evidence.mdAnalysis-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​

NoteCovers
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 Status line; landed notes describe shipped behavior, contract notes describe invariants with tests.
  • This index is gated: adding a file under docs/design/ without listing it here fails packages/website/tests/docs-coverage.test.ts.