Skip to content
knixl

ADR 0004: Whole-file taint, user code in separate files

Status: accepted

Context

Section titled “Context”

Taint (detecting that a generated file was hand-edited) could be tracked per node, preserving user edits inside otherwise-generated files via sentinel comment regions.

Decision

Section titled “Decision”

Taint is whole-file, keyed by a blake3 hash recorded in the lock. Generated files are 100% generated. User code lives in separate, never-generated modules imported alongside.

Consequences

Section titled “Consequences”
  • Detection is a hash comparison. No marker parsing, no AST diffing generated-vs-on-disk, none of the fragility those bring.
  • Stale (input changed) and Drifted (file hand-edited) are told apart by a third hash: if disk still matches the lock, the change came from inputs, not a human.
  • Every generated file carries a header (Generated by knixl ... do NOT edit ... overrides go in a sibling) so the contract is visible where someone would be tempted to edit.
  • The raw-nix escape still lets inline Nix into a generated file, but it comes from the KDL, so it is part of the generated content and hashes with it.