Internals and currency
Internals and currency
This part of the standalone NixOS book is organized by topic (normal book chapters), not by a calendar. Read linearly when building depth; skip and search when you already operate a flake host and need a reference answer.
Prerequisites. You should already rebuild a flake-defined NixOS host, write or heavily consume modules, pin inputs with flake.lock, and have at least one real service path (SSH, proxy, or data) under declarative control. Internals last is deliberate: evaluator and daemon vocabulary is most useful after you have scars from rebuilds, not before.
What this part is for. After host, layout, secrets, packaging, and fleet chapters, the remaining skill is currency under change: explain why eval hangs, why a type error appears only on merge, who may write the store, how releases and upgrades actually work, and how to keep an architecture honest. Capstone proof (wipe/rebuild, rollback, tests) depends on this literacy even when Capstone code lives in the next part.
Learning outcomes
When you leave this part you should be able to:
- Force evaluation intentionally, diagnose infinite recursion, and use
trace/tryEval/seq/deepSeqwithout cargo-culting them.
- Choose module types, merge with
mkIf/mkMerge/ priorities, and fail bad configs at eval time with assertions.
- Explain multi-user trust, GC roots, sandbox isolation, and substituter signature policy on a live machine.
- Measure rebuild time (eval vs substitute vs build), tune
max-jobs/cores/ builders, and reject “sandbox off for speed.”
- Describe input-addressed vs content-addressed derivations and keep production hosts on default store semantics until criteria say otherwise.
- Harden
nixosTest/ flakechecksso waits are unit/port based, not blindsleep.
- Sample the adjacent ecosystem once, with a keep/drop decision that protects Capstone main.
- Steelman Guix, image-based OS families, and Ansible against your workloads.
- Read official release notes into an IMPACT checklist; plan a staged upgrade with rollback gates.
- Inject and recover lab failures into a durable playbook; freeze architecture and gaps before Capstone thrash.
Chapter map
| Chapter | Theme | You can leave when… |
|---|---|---|
| The evaluator | Thunks, WHNF, cycles, trace toolkit | You can reproduce and fix three recursion shapes and force one real flake leaf safely |
| Module system in depth | Types, merge, priorities, assertions | One production module is typed; bad configs fail at eval |
| Store and daemon | Multi-user trust, roots, sandbox, signatures | You map live roots and annotate a sandbox build log |
| Nix performance | Jobs/cores, eval cost, cache, builders | Before/after timings exist with justified settings |
| CA derivations (awareness) | IA vs CA, experimental flags | Status memo or lab experiment; Capstone stays default store |
| nixosTest mastery | Driver API, flakes, multi-node, CI | Suite inventory; sleep-only waits removed from critical path |
| Ecosystem map | devenv / Snowfall / nix-darwin (pick one) | COMPARE.md keep/drop without rewriting Capstone main |
| Comparative landscape | NixOS vs Guix vs images vs Ansible | Honest scorecard + essay with “when not NixOS” |
| Reading release notes | 26.05 method, IMPACT tags, stateVersion | Annotated checklist against your flake |
| Upgrade planning | 26.05→next runbook, gates, rollback | Dry-run upgrade document with abort criteria |
| Troubleshooting drills | Inject/recover on disposable VM | ≥2 playbook entries with diagnose/fix/prevent |
| Architecture review | Map repo → Capstone A gaps | ARCHITECTURE.md + prioritized GAPS.md |
How this part connects
Language / modules (earlier parts)
│
▼
Evaluator + types ← debug eval failures at the source
│
▼
Store / daemon / perf ← trust, isolation, time budget
│
▼
CA literacy + tests ← experimental awareness; proof harness
│
▼
Ecosystem + compare ← adopt tools and OS choices deliberately
│
▼
Release + upgrade ← currency under nixpkgs cadence
│
▼
Troubleshoot + arch ← playbooks + freeze before Capstone
│
▼
Capstone part ← implement, prove, recover| Earlier part | What you reuse here |
|---|---|
| Concepts | Store paths, derivations, modern CLI |
| NixOS host | Rebuild modes, custom modules as consumer |
| Home & layout | Flake layout, locks, checks |
| Services & security | Secrets, firewall, proxy consumers |
| Packaging | FODs, caches, remote builders vocabulary |
| Ops & fleet | nixosTest intro, CI, GC, backups, deploy tools |
Suggested study modes
| Mode | Approach |
|---|---|
| Linear depth | Chapters in table order; one lab workspace per chapter under ~/lab/nixos/internals/<topic>/ |
| Reference | Jump via symptoms: infinite recursion → evaluator; silent option loss → module priorities; GC surprise → store/daemon |
| Pre-Capstone sprint | Architecture review first if your repo is chaotic; then evaluator + modules + tests; upgrade notes last if pin is already stable |
| Ops only | Store/daemon, performance, troubleshooting, release notes, upgrade planning |
Prefer disposable VMs and nixos-rebuild build / nix build …toplevel over thrashing a daily driver. Console access before firewall experiments is non-negotiable.
Lab workspace convention
Use topic paths (not calendar folders):
mkdir -p ~/lab/nixos/internals/{evaluator,modules,store-daemon,perf,ca,tests,ecosystem,compare,release-notes,upgrade,troubleshoot,architecture}Artifacts worth keeping in git (your flake or a notes repo):
| Artifact | From |
|---|---|
NOTES.md / personal gotchas |
Every chapter |
TYPES.md, PRIORITIES.md |
Modules |
ROOTS.md, TRUST.md |
Store/daemon |
PERF.md, BUILDERS.md |
Performance |
CA-MEMO.md or experiment logs |
CA awareness |
SUITE.md |
nixosTest mastery |
COMPARE.md |
Ecosystem |
SCORECARD.md, ESSAY.md |
Comparative landscape |
IMPACT.md |
Release notes |
UPGRADE-*.md |
Upgrade planning |
playbook/PL-*.md |
Troubleshooting |
ARCHITECTURE.md, GAPS.md, CAPSTONE-A.md |
Architecture review |
Acceptance bar for the part
You do not need every optional experiment green. You do need:
- One real infinite-recursion fix documented
- One module redesigned with real types + ≥2 assertions
- Live GC-root classification and sandbox left on
- Before/after rebuild timing with justified
max-jobs/cores
- Explicit decision: Capstone on default (input-addressed) store
- At least one flake check/
nixosTestwithout blindsleepas the only wait
- Keep/drop decision for one ecosystem trial without rewriting Capstone main
- Comparative essay that includes when you would not choose NixOS
IMPACT.mdfor 26.05 (or your pin) with ACTION/VERIFY items
- Upgrade runbook skeleton with rollback commands
- ≥2 playbook entries from real inject/recover drills
- Architecture + gap list ready to drive Capstone
Baseline and policy
| Item | Book default |
|---|---|
| Nix | 2.34.x class — verify with nix --version |
| nixpkgs / NixOS | 26.05 pin in Capstone and lab hosts |
| Store semantics | Input-addressed default; CA is literacy only |
| Secrets | Paths only in modules; sops-nix primary |
| Experimental features | Enable only with revert plan on disposable builders |
No day-calendar framing in this book part. Chapter order is pedagogical, not a schedule. Study pacing is yours.
Common traps in this part
| Trap | Better move |
|---|---|
| Enabling CA on the only builder “for speed” | Memo + criteria; keep Capstone default |
deepSeq everywhere to “fix” laziness |
Redesign option dependencies |
mkForce on every host option |
Fix module defaults and boundaries |
| Tool tourism (devenv + Snowfall + darwin in one weekend) | Try one; score; decide |
| Upgrade Friday night with six input bumps | Branch, nixpkgs first, gates, lab first |
| Architecture doc never opened again | Link from CAPSTONE-A.md; gaps with acceptance tests |
Next
→ The evaluator — thunks, force, and recursion diagnostics.
When architecture and gaps are frozen, continue to Capstone and recovery.