Skip to content

Commit 2c1582b

Browse files
committed
fix(file-safety): derive the version token from exact BigInt stats (A1, #1375)
CodeRabbit finding on this PR: the default numeric fs.stat() loses precision (values above 2^53 are rounded, including Windows file IDs) and the ms->ns derivation introduced a double-precision quantum. Fixed by fetching the stat with { bigint: true }: all five token fields (dev, ino, size, mtimeNs, ctimeNs) are exact BigInt values rendered as decimal strings, with no float anywhere. The sub-ms test now asserts an exact 1_000 ns delta instead of bounded drift, and a regression test pins a size of 10^16+1 (> Number.MAX_SAFE_INTEGER).
1 parent 13188d2 commit 2c1582b

2 files changed

Lines changed: 65 additions & 79 deletions

File tree

‎src/utils/__tests__/versionToken.spec.ts‎

Lines changed: 42 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,72 @@
11
import * as fs from "fs/promises"
22
import * as os from "os"
33
import * as path from "path"
4-
import type { Stats } from "fs"
4+
import type { BigIntStats } from "fs"
55
import { afterEach, beforeEach, describe, expect, it } from "vitest"
66

77
import { computeVersionToken, versionTokenOfStat } from "../versionToken"
88

9-
// Stats is a class-backed interface without a public constructor, so a plain-object
10-
// test double is the only practical way to pin the token format without real files.
11-
// Last-resort double assertion (test-local, per AGENTS.md).
12-
function makeStats(overrides: Partial<Stats> = {}): Stats {
13-
const base: Partial<Stats> = {
14-
dev: 7,
15-
ino: 4242,
16-
size: 1234,
17-
atimeMs: 1_700_000_000_000,
18-
mtimeMs: 1_700_000_000_123.456,
19-
ctimeMs: 1_700_000_000_789.999,
20-
birthtimeMs: 1_700_000_000_000,
9+
// BigIntStats is a class-backed interface without a public constructor, so a
10+
// plain-object test double is the only practical way to pin the token format
11+
// without real files. Last-resort double assertion (test-local, per AGENTS.md).
12+
function makeStats(overrides: Partial<BigIntStats> = {}): BigIntStats {
13+
// This repo's @types/node models every StatsBase field (including the *Ms
14+
// fields) as the parameter type T, so all values here are bigint literals;
15+
// the token only reads the *Ns fields. Single-step downcast from Partial to
16+
// the full type (BigIntStats has no public constructor).
17+
const base: Partial<BigIntStats> = {
18+
dev: 7n,
19+
ino: 4242n,
20+
size: 1234n,
21+
atimeMs: 1_700_000_000_000n,
22+
mtimeMs: 1_700_000_000_123n,
23+
ctimeMs: 1_700_000_000_789n,
24+
birthtimeMs: 1_700_000_000_000n,
25+
atimeNs: 1_700_000_000_000_000_000n,
26+
mtimeNs: 1_700_000_000_123_456_789n,
27+
ctimeNs: 1_700_000_000_789_999_999n,
28+
birthtimeNs: 1_700_000_000_000_000_000n,
2129
}
22-
return { ...base, ...overrides } as unknown as Stats
30+
return { ...base, ...overrides } as BigIntStats
2331
}
2432

2533
describe("versionTokenOfStat (A1, epic #1375)", () => {
2634
it("is deterministic for an identical stat", () => {
2735
expect(versionTokenOfStat(makeStats())).toBe(versionTokenOfStat(makeStats()))
2836
})
2937

30-
it("matches the documented dev:ino:size:mtimeNs:ctimeNs format", () => {
31-
const expected = [
32-
"7",
33-
"4242",
34-
"1234",
35-
Math.round(1_700_000_000_123.456 * 1e6).toString(),
36-
Math.round(1_700_000_000_789.999 * 1e6).toString(),
37-
].join(":")
38-
expect(versionTokenOfStat(makeStats())).toBe(expected)
38+
it("matches the documented dev:ino:size:mtimeNs:ctimeNs format with exact decimal fields", () => {
39+
expect(versionTokenOfStat(makeStats())).toBe("7:4242:1234:1700000000123456789:1700000000789999999")
3940
})
4041

4142
it("distinguishes size changes at identical timestamps", () => {
42-
expect(versionTokenOfStat(makeStats({ size: 1235 }))).not.toBe(versionTokenOfStat(makeStats()))
43+
expect(versionTokenOfStat(makeStats({ size: 1235n }))).not.toBe(versionTokenOfStat(makeStats()))
4344
})
4445

45-
it("distinguishes mtime changes at identical size", () => {
46-
expect(versionTokenOfStat(makeStats({ mtimeMs: 1_700_000_000_124 }))).not.toBe(versionTokenOfStat(makeStats()))
46+
it("distinguishes a one-nanosecond mtime change", () => {
47+
expect(versionTokenOfStat(makeStats({ mtimeNs: 1_700_000_000_123_456_790n }))).not.toBe(
48+
versionTokenOfStat(makeStats()),
49+
)
4750
})
4851

4952
it("distinguishes a replaced file (dev/ino change) with identical content state", () => {
50-
const replaced = makeStats({ dev: 8, ino: 999 })
53+
const replaced = makeStats({ dev: 8n, ino: 999n })
5154
expect(versionTokenOfStat(replaced)).not.toBe(versionTokenOfStat(makeStats()))
5255
})
5356

54-
it("preserves sub-ms mtime resolution in the ns field", () => {
55-
const wholeMs = versionTokenOfStat(makeStats({ mtimeMs: 1_700_000_000_123 }))
56-
const halfMsLater = versionTokenOfStat(makeStats({ mtimeMs: 1_700_000_000_123.5 }))
57-
expect(halfMsLater).not.toBe(wholeMs)
58-
// 0.5 ms = 500_000 ns. The float-derived ns field is quantized (~256 ns at
59-
// this epoch), so allow a bounded drift instead of asserting an exact value.
60-
const diff = Number(halfMsLater.split(":")[3]) - Number(wholeMs.split(":")[3])
61-
expect(Math.abs(diff - 500_000)).toBeLessThanOrEqual(512)
57+
it("renders nanosecond resolution exactly (no float quantization)", () => {
58+
const base = versionTokenOfStat(makeStats())
59+
const plusOneMicrosecond = versionTokenOfStat(makeStats({ mtimeNs: 1_700_000_000_123_457_789n }))
60+
// 1_000 ns apart — the BigInt derivation must keep the delta exact.
61+
const baseNs = BigInt(base.split(":")[3])
62+
const microNs = BigInt(plusOneMicrosecond.split(":")[3])
63+
expect(microNs - baseNs).toBe(1_000n)
6264
})
6365

64-
it("handles sizes beyond 32 bits without precision loss", () => {
65-
const size = 5_000_000_000 // > 2^32
66+
it("handles sizes beyond Number.MAX_SAFE_INTEGER without precision loss", () => {
67+
const size = 10_000_000_000_000_001n // 10^16 + 1 > 2^53
6668
const token = versionTokenOfStat(makeStats({ size }))
67-
expect(token).toContain(`:4242:${size}:`)
69+
expect(token).toBe(`7:4242:${size}:1700000000123456789:1700000000789999999`)
6870
})
6971
})
7072

@@ -82,9 +84,9 @@ describe("computeVersionToken (A1, epic #1375)", () => {
8284
await fs.rm(tmpDir, { recursive: true, force: true })
8385
})
8486

85-
it("derives the token from the on-disk state (single stat)", async () => {
87+
it("derives the token from the on-disk state (single bigint stat)", async () => {
8688
const token = await computeVersionToken(file)
87-
expect(token).toBe(versionTokenOfStat(await fs.stat(file)))
89+
expect(token).toBe(versionTokenOfStat(await fs.stat(file, { bigint: true })))
8890
})
8991

9092
it("changes when the file content changes", async () => {

‎src/utils/versionToken.ts‎

Lines changed: 23 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,48 @@
11
import { stat } from "fs/promises"
2-
import type { Stats } from "fs"
2+
import type { BigIntStats } from "fs"
33

44
/**
55
* Version token for the compare-and-swap write guard (upstream epic #1375, phase A1).
66
*
77
* A token is a pure function of a file's on-disk state, derived from a single
8-
* `fs.stat`, so every process that observes the same file state (a second VS Code
9-
* window, the CLI, the user's own editor tooling) computes the same token. The
10-
* downstream guard phases (A2/A3) compare the token observed at read time with the
11-
* token recomputed just before a write to detect "the file changed since the read"
12-
* (stale) or "the file was replaced by a different file" (dev/ino change).
8+
* `fs.stat(path, { bigint: true })`, so every process that observes the same file
9+
* state (a second VS Code window, the CLI, the user's own editor tooling) computes
10+
* the same token. The downstream guard phases (A2/A3) compare the token observed at
11+
* read time with the token recomputed just before a write to detect "the file
12+
* changed since the read" (stale) or "the file was replaced by a different file"
13+
* (dev/ino change).
1314
*
1415
* Format: `dev:ino:size:mtimeNs:ctimeNs`
1516
*
16-
* Resolution note: Node exposes modification/change times as float milliseconds,
17-
* so the ns fields are derived as `Math.round(mtimeMs * 1e6)`. The integer-to-double
18-
* conversion is correctly rounded, so the derivation is deterministic across
19-
* processes, but it is quantized by double precision (~256 ns at the current epoch).
20-
* Two file states whose timestamps differ by less than the quantum derive the same
21-
* ns field; in practice distinct states differ by at least the OS clock resolution
22-
* (and no write workload produces mtimes closer than that), so the guard contract
23-
* holds: same disk state → same token; changed state → a different token in all
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.
17+
* Precision: the stat is fetched in `bigint` mode, so all five fields are exact
18+
* `BigInt` values rendered as decimal strings — no float is involved anywhere.
19+
* There is therefore no precision loss for large sizes or inodes (a Windows file ID
20+
* exceeds 2^53 and is still exact), and the ns timestamps are the kernel's exact
21+
* nanosecond values rather than a ms→ns derivation (no ~256 ns double-precision
22+
* quantum). Guarantee: same disk state → same token, deterministic across
23+
* processes; any change to size, file identity, or mtime/ctime → a different token.
24+
*
25+
* Platform note: on POSIX `ctime` is the last file-status change; on Windows it is
26+
* the file creation time. The token only requires it to move when the file's
27+
* metadata is replaced, which holds on both.
3328
*/
3429

35-
/** Derive an ns-scale field from Node's float milliseconds (see module docs). */
36-
function nsFromMs(ms: number): string {
37-
return Math.round(ms * 1e6).toString()
38-
}
39-
4030
/**
41-
* Build the version token from an already-fetched `Stats` — no I/O.
31+
* Build the version token from an already-fetched `BigIntStats` — no I/O.
4232
*
4333
* Exported separately from {@link computeVersionToken} so tests can pin the exact
4434
* format against synthetic stats.
4535
*/
46-
export function versionTokenOfStat(stats: Stats): string {
47-
return [
48-
stats.dev.toString(),
49-
stats.ino.toString(),
50-
stats.size.toString(),
51-
nsFromMs(stats.mtimeMs),
52-
nsFromMs(stats.ctimeMs),
53-
].join(":")
36+
export function versionTokenOfStat(stats: BigIntStats): string {
37+
return [stats.dev, stats.ino, stats.size, stats.mtimeNs, stats.ctimeNs].map((value) => value.toString()).join(":")
5438
}
5539

5640
/**
57-
* Compute the version token for a file (one `fs.stat`).
41+
* Compute the version token for a file (one `fs.stat` in bigint mode).
5842
*
5943
* Rejects with the underlying ENOENT (or equivalent) error when the file is absent;
6044
* how an unobservable target is treated is decided by the guard layer (A3).
6145
*/
6246
export async function computeVersionToken(filePath: string): Promise<string> {
63-
return versionTokenOfStat(await stat(filePath))
47+
return versionTokenOfStat(await stat(filePath, { bigint: true }))
6448
}

0 commit comments

Comments
 (0)