Skip to content

Commit 13188d2

Browse files
committed
docs(file-safety): correct ino precision bounds in version token (A1, #1375)
Review finding: 'ino is an exact integer' was overstated. Node exposes ino as a float64 number: exact for small POSIX inode numbers, but on modern Windows the file ID exceeds 2^53 so Node's own value is already rounded (verified on node v25: non-zero ino, isSafeInteger=false). It remains deterministic per file (same file -> same token), so the token contract is unchanged; change detection rests on exact dev/size plus the mtime/ctime ns fields. Document the bound instead of claiming exactness.
1 parent 131d18d commit 13188d2

1 file changed

Lines changed: 9 additions & 2 deletions

File tree

‎src/utils/versionToken.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,15 @@ import type { Stats } from "fs"
2121
* ns field; in practice distinct states differ by at least the OS clock resolution
2222
* (and no write workload produces mtimes closer than that), so the guard contract
2323
* holds: same disk state → same token; changed state → a different token in all
24-
* realistic cases. dev, ino and size are exact integers, so any size or file
25-
* identity change is always detected regardless of the timestamp quantum.
24+
* realistic cases. `dev` and `size` are exact integers. `ino` is Node's
25+
* `number` (float64): exact for small POSIX inode numbers, but on modern Windows
26+
* the underlying file ID exceeds 2^53, so Node's own value is already rounded —
27+
* still deterministic per file (same file → same token), but not guaranteed
28+
* injective across distinct files. Change detection therefore rests on size +
29+
* mtime/ctime: any size change is always detected regardless of the timestamp
30+
* quantum, and a replacement whose size and timestamps are indistinguishable is
31+
* undetectable by any scheme reading the same Stats — the detect-and-reread
32+
* stance (no lockfile) accepts that.
2633
*/
2734

2835
/** Derive an ns-scale field from Node's float milliseconds (see module docs). */

0 commit comments

Comments
 (0)