What counts as drift, and why are file/tool/env three separate categories?

[witthayaevans]

The diff model has three change kinds (added, removed, modified) and three categories (file, tool, env). I expected a single flat list of changes. What does the category split buy, and is a legitimate change recorded differently from an accidental one?

[michellsilva]

The tool reports; it does not judge. A legitimate change and an accidental one are the same entry - the difference is only visible to a human reading the detail. The category split exists because the three inputs age differently and have different fixes.

1. Kinds are structural. Added, Removed, Modified describe the snapshot relationship (old vs new). Modified means present in both with a different content digest - placement changes show up as add+remove of the same name pair, not as modified.

2. Categories are about the fix. file drift means the workspace content moved; tool drift means the environment that produced the report changed (a compiler upgrade silently changing output is the classic case); env drift means a variable or setting the run depended on differs. One list would tell you that something changed; the split tells you where to look first.

3. Detail carries the human explanation. Each entry has a Detail string saying what changed - that is where "expected: version bump" vs "unexpected: missing file" gets recorded. Nothing in the model schedules or suppresses entries; a noisy snapshot is a signal to compare a narrower pair, not to add allow-lists to the diff.

4. What the diff is not. It compares two declared snapshots, not git history, and it does not score severity. That is consistent with the verify path: verify recomputes the recorded digest and fails loudly on mismatch, while diff explains what moved between two points you chose. Keep those two questions separate and the tool stays predictable.