Document the one-second mtime change-detection window as a known limitation #12

New Issue

2026-08-09T03:45:25+02:00

clawbot commented

2026-08-09 03:45:25 +02:00

Change detection compares old.mtime < ev.rec.mtime (scan.go:246) where mtime is ModTime().Unix() (scan.go:574, scan.go:713) — whole seconds. A file rewritten in place, at the same size, within the same wall-clock second as the recorded mtime is classified unchanged and keeps its stale hashes forever. No later scan will ever notice.

The code matches the spec: README §Database defines mtime as Unix seconds and §scan mode describes the skip rule in those terms. The problem is that README §scan mode also promises "the database only ever contains signatures verified by the most recent scan that covered them", which reads as a stronger guarantee than the implementation gives.

Two ways to close the gap.

Option A (recommended): document it. Add it to the existing "Known limitation (accepted)" list. Cost: zero. The window requires a same-second, same-size, in-place rewrite, which is rare for the target workload of media, downloads and extracted archives.

Option B: store nanosecond mtime. Eliminates the window permanently, and pre-1.0 is the only free moment to change the schema. But PRAGMA user_version would go to 2, and README §Database makes any unrecognized version fatal — so every existing database is invalidated and every deployment pays a full re-hash of every file. At the stated 150 TB scale that is a very expensive answer to a very rare failure.

Going with Option A. Reopen or comment if you would rather pay for Option B before the tag; after 1.0 it becomes a real migration.

Definition of done

README §scan mode adds the one-second window to the "Known limitation (accepted)" entries, stating the exact conditions (same size, in-place rewrite, within the same second as the recorded mtime) and the consequence (stale hashes retained indefinitely).
The over-strong "only ever contains signatures verified by the most recent scan" sentence is softened so it does not contradict the limitation.
Docs-only change; no code, no schema change.
make check green.

Change detection compares `old.mtime < ev.rec.mtime` (`scan.go:246`) where mtime is `ModTime().Unix()` (`scan.go:574`, `scan.go:713`) — whole seconds. A file rewritten in place, at the same size, within the same wall-clock second as the recorded mtime is classified `unchanged` and keeps its stale hashes forever. No later scan will ever notice. The code matches the spec: README §Database defines `mtime` as Unix seconds and §scan mode describes the skip rule in those terms. The problem is that README §scan mode also promises "the database only ever contains signatures verified by the most recent scan that covered them", which reads as a stronger guarantee than the implementation gives. Two ways to close the gap. **Option A (recommended): document it.** Add it to the existing "Known limitation (accepted)" list. Cost: zero. The window requires a same-second, same-size, in-place rewrite, which is rare for the target workload of media, downloads and extracted archives. **Option B: store nanosecond mtime.** Eliminates the window permanently, and pre-1.0 is the only free moment to change the schema. But `PRAGMA user_version` would go to 2, and README §Database makes any unrecognized version fatal — so every existing database is invalidated and every deployment pays a full re-hash of every file. At the stated 150 TB scale that is a very expensive answer to a very rare failure. Going with Option A. Reopen or comment if you would rather pay for Option B before the tag; after 1.0 it becomes a real migration. ## Definition of done 1. README §scan mode adds the one-second window to the "Known limitation (accepted)" entries, stating the exact conditions (same size, in-place rewrite, within the same second as the recorded mtime) and the consequence (stale hashes retained indefinitely). 2. The over-strong "only ever contains signatures verified by the most recent scan" sentence is softened so it does not contradict the limitation. 3. Docs-only change; no code, no schema change. 4. `make check` green.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:45:25 +02:00

clawbot referenced this issue

2026-08-09 03:47:54 +02:00

Land golangci-lint v2.12.2 and the canonical .golangci.yml on main #3

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/sfdupes#12