Content-addressed derivations (awareness)

Updated

July 30, 2026

Content-addressed derivations (awareness)

Goal: Explain input-addressed vs content-addressed derivations, know the experimental status and feature flags, run a tiny optional experiment or produce a documented status memo with primary-source links—without putting production Capstone (or 26.05 lab hosts) on CA.

Important

Content-addressed (CA) derivations remain an experimental path. This chapter is literacy and a sandbox experiment—not a mandate to migrate your host. Capstone A stays on default store semantics.

Why this chapter exists

Default Nix paths are input-addressed: the store hash fingerprints the build plan (derivations + inputs), not only the output bytes. Two builds that produce identical bytes can still get different paths if input metadata differs. CA aims at output-hash identity—powerful for early cutoff / better sharing—but the feature surface, UX, and nixpkgs readiness evolve. Experts need an honest mental model before blog hype.

You will hear CA in RFCs, release notes, and conference talks. Literacy prevents cargo-cult experimental-features on prod builders.

Theory 1 — Input-addressed world (today’s default)

inputs + build recipe  →  hash  →  /nix/store/<hash>-name

Consequences you already rely on:

Property Implication
Rebuild with same inputs Same path (reproducible address)
Different compiler flags Different path even if binary identical
FODs Special: output hash fixed; may network
Substitutes Trust signatures of builders/caches

Trust is “did we run this recipe (or accept a signed substitute for it)?”

FODs vs CA (do not conflate)

Fixed-output derivation CA derivations (experimental)
Classic use fetches, vendoring general builds
Hash of declared output content-addressed store model
Maturity Everyday Experimental

FODs already teach “hash the result” for a class of builds. CA generalizes the idea; it is not “FODs for everything tomorrow.”

Theory 2 — Content-addressed idea

build  →  output bytes  →  hash  →  /nix/store/<hash>-name

Aspirations:

Goal Intuition
Early cutoff If output already exists with same content hash, skip dependent rebuilds more aggressively
Better dedup Same bytes converge to same path across “recipes” that don’t matter
FODs generalized More builds behave like “hash the result”

Challenges:

  • Self-references in outputs (files embedding their own store path) need rewriting schemes
  • Granularity (per-output CA, etc.)
  • Cache/protocol/nixpkgs compatibility
  • Debugging mental model shift
  • Tooling and UX still moving

Theory 3 — Experimental feature surface

Exact names and defaults change across Nix versions. Always check:

nix --version
nix config show | grep -i experimental
man nix.conf | less   # search ca-derivations / content-address

Historically you will see flags in the family of:

  • ca-derivations
  • related: dynamic-derivations, cgroups, etc. (orthogonal but often discussed together)

Enable only on a lab profile:

# ephemeral lab — not Capstone default
nix.settings.experimental-features = [
  "nix-command"
  "flakes"
  "ca-derivations"  # if supported by your Nix
];

Or local:

# illustrative — confirm flag name for your version
nix build --experimental-features 'nix-command flakes ca-derivations' ...

Reading status (primary sources)

Prefer in this order:

  1. Nix release notes for your exact version
  2. Official Nix manual sections on store / experimental features
  3. nixpkgs issues/PRs tagged CA (for package readiness)
  4. RFCs / discourse RFCs (design intent)

Blogs are optional commentary after primary sources. Version-skew blogs are how people enable the wrong flag.

Theory 4 — What CA does not magically fix

Claim Reality
“CA = perfect reproducibility” Reproducibility is about determinism of builds; CA is about addressing
“CA replaces sandbox” Isolation still required
“Turn on CA, everything faster tomorrow” Needs package + toolchain readiness; may slow or break
“Signatures no longer matter” You still decide trust for substitutes
“Capstone should adopt CA” No for this book’s Capstone A

Theory 5 — Relationship to Capstone and 26.05

Capstone should stay on stable, default derivation mode unless you explicitly document a lab-only branch. DR wipe/rebuild proofs should not depend on experimental store semantics.

Your nixos-26.05 pin is about module and package stability. CA is a Nix daemon / store feature layer—orthogonal but coupled in operational risk if enabled fleet-wide.

Optional: track CA as a roadmap item in the retrospective—revisit when your Nix pin upgrades and primary sources look greener.

Theory 6 — Trust and substitutes under CA thinking

Even with CA aspirations, operations still answer:

Question Still true?
Who is allowed to write to my store? Yes
Which substituters do I trust? Yes
Do I verify signatures? Yes (policy)
Can a malicious builder hurt me? Yes

CA is not a substitute for binary-cache trust discipline or remote-builder trust.

Theory 7 — Operational decision template

## Store semantics decision
- Mode: input-addressed (default)
- CA experimental: enabled? no
- Revisit when: <Nix version + release notes criteria>
- Owner: <you>
- Rollback: remove feature flag; rebuild hosts on default

Paste into Capstone docs so future-you does not “just try CA” mid-freeze.

Worked example — Conceptual comparison card

Dimension Input-addressed Content-addressed (experimental)
Path hash from Recipe/inputs Output content (design)
Same bytes, different flags Different paths May converge
Ecosystem maturity Default everywhere Experimental / partial
Debugging familiarity High (this book) Lower; fewer blog runbooks
Prod recommendation (this book) Yes Not yet for Capstone

Lab 0 — Workspace

mkdir -p ~/lab/nixos/internals/ca
cd ~/lab/nixos/internals/ca

Lab 1 — Version & feature inventory (required)

nix --version | tee nix-version.txt
nix config show > nix-config.txt
grep -iE 'experimental|ca-|content' nix-config.txt || true

Open official docs for your version; save URLs in SOURCES.md (at least 2 primary links).

Write a 10–15 line status summary: what CA means, whether your Nix binary advertises the feature, and any warnings in the manual.

Lab 2 — Choose a track

Track A — Optional tiny experiment (if feature available)

  1. Enable ca-derivations (or current equivalent) only in a disposable VM or user nix.conf overlay you can revert.
  2. Build a trivial derivation twice with intentional non-semantic input noise if docs show how CA modes are requested for derivations (API differs by version—follow current manual).
  3. Compare store paths and nix path-info output.
  4. Capture logs in experiment/.
  5. Disable experimental CA for daily lab work if it complicates Capstone.

If the manual’s API is unclear or broken on your pin, stop and switch to Track B—do not thrash for hours.

Track B — Status memo without enabling (always acceptable)

Write CA-MEMO.md (≥1 page) covering:

  1. Input- vs content-addressed definitions
  2. Problems CA wants to solve
  3. Current experimental flags for your Nix version
  4. Known limitations (self-refs, ecosystem)
  5. Decision: not enabling on Capstone host, with revisit date (e.g. after next release notes)
  6. Primary source links
  7. Difference from FODs in your own words

Acceptance: Either Track A logs + revert proof, or Track B memo complete.

Lab 3 — Teach-back diagram

In NOTES.md, draw (ASCII is fine):

[user config] → eval → derivations → (IA path | CA path?) → substitute/build → store

Annotate where trust/signatures apply.

Lab 4 — Nixpkgs awareness scan

Search your local nixpkgs (or GitHub) for mentions:

# if you have nixpkgs checkout
rg -n "contentAddressed|__contentAddressed|ca-derivations" -g '*.nix' | head

Note whether anything in your critical path packages advertises CA—likely little for a lab host. Record findings.

Lab 5 — Explicit non-adoption

Add to Capstone docs (or lab notes):

## Store semantics
- Mode: input-addressed (default)
- CA: deferred until <date/criteria>
- Owner: <you>

This prevents a well-meaning future PR from flipping experimental flags mid-freeze.

Lab 6 — Analogy card (teach others)

Write three sentences max for a teammate:

  1. Input-addressed: “The address is the recipe’s fingerprint.”
  2. Content-addressed: “The address wants to be the loaf’s fingerprint.”
  3. Why Capstone waits: “Experimental + ecosystem partial; DR should not depend on it.”

If you cannot explain without jargon, revise CA-MEMO.md until you can.

Interaction with other internals chapters

Chapter Link to CA literacy
Evaluator Eval still produces plans; addressing is store-side
Store/daemon Feature flags live with daemon policy
Performance Early cutoff is the performance story—measure before enabling
Release notes Watch Nix + nixpkgs notes for CA maturity signals

Do not enable CA “for speed” without a benchmark and a rollback plan for the builder.

Common gotchas

Symptom / mistake What to do
Blog for Nix 2.X vs your 2.Y Trust nix --version + matching manual
Enabled CA on shared prod builder Revert; isolate experiments
Assuming path equality ⇒ bit equality always Still verify; trust model differs
Spending the whole session debugging experimental UX Fall back to Track B memo
Mixing CA talk with FOD confusion FODs already hash outputs for fetch class
Capstone depends on CA Redesign; default store only

Checkpoint

  • nix-version.txt + feature inventory
  • SOURCES.md with primary links
  • Track A experiment notes or Track B CA-MEMO.md
  • Explicit Capstone decision: stay input-addressed
  • Three personal gotchas

Commit

git add .
git commit -m "lab(nixos): CA derivations experimental awareness"

Write three personal gotchas before continuing.

Next

→ nixosTest mastery — harden checks for Capstone.