feat(file-safety): file version token for the guarded-write path (A1, #1375) (#1383)

* feat(file-safety): add version token for the guarded-write path (A1, #1375)

Introduces the version token - dev:ino:size:mtimeNs:ctimeNs derived from a single fs.stat - a pure function of a file's on-disk state that every process computing from the same state agrees on. The compare-and-swap write guard (A2/A3) will compare the token observed at read time against the token recomputed before a write to detect stale or replaced files. No production callers yet: this is infrastructure for the file-write safety series (plan: easonLiangWorldedtech#33), part of upstream epic #1375.

* 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.

* 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).

* chore(ci): empty commit — re-trigger CI and the CodeRabbit current-head review gate (no code change)

---------

Co-authored-by: Eason Liang <easonliang28@gmail.com>

Author: easonLiangWorldedtech

src/utils/__tests__/versionToken.spec.ts

@@ -0,0 +1,105 @@
+import * as fs from "fs/promises"
+import * as os from "os"
+import * as path from "path"
+import type { BigIntStats } from "fs"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+
+import { computeVersionToken, versionTokenOfStat } from "../versionToken"
+
+// BigIntStats is a class-backed interface without a public constructor, so a
+// plain-object test double is the only practical way to pin the token format
+// without real files. Last-resort double assertion (test-local, per AGENTS.md).
+function makeStats(overrides: Partial<BigIntStats> = {}): BigIntStats {
+	// This repo's @types/node models every StatsBase field (including the *Ms
+	// fields) as the parameter type T, so all values here are bigint literals;
+	// the token only reads the *Ns fields. Single-step downcast from Partial to
+	// the full type (BigIntStats has no public constructor).
+	const base: Partial<BigIntStats> = {
+		dev: 7n,
+		ino: 4242n,
+		size: 1234n,
+		atimeMs: 1_700_000_000_000n,
+		mtimeMs: 1_700_000_000_123n,
+		ctimeMs: 1_700_000_000_789n,
+		birthtimeMs: 1_700_000_000_000n,
+		atimeNs: 1_700_000_000_000_000_000n,
+		mtimeNs: 1_700_000_000_123_456_789n,
+		ctimeNs: 1_700_000_000_789_999_999n,
+		birthtimeNs: 1_700_000_000_000_000_000n,
+	}
+	return { ...base, ...overrides } as BigIntStats
+}
+
+describe("versionTokenOfStat (A1, epic #1375)", () => {
+	it("is deterministic for an identical stat", () => {
+		expect(versionTokenOfStat(makeStats())).toBe(versionTokenOfStat(makeStats()))
+	})
+
+	it("matches the documented dev:ino:size:mtimeNs:ctimeNs format with exact decimal fields", () => {
+		expect(versionTokenOfStat(makeStats())).toBe("7:4242:1234:1700000000123456789:1700000000789999999")
+	})
+
+	it("distinguishes size changes at identical timestamps", () => {
+		expect(versionTokenOfStat(makeStats({ size: 1235n }))).not.toBe(versionTokenOfStat(makeStats()))
+	})
+
+	it("distinguishes a one-nanosecond mtime change", () => {
+		expect(versionTokenOfStat(makeStats({ mtimeNs: 1_700_000_000_123_456_790n }))).not.toBe(
+			versionTokenOfStat(makeStats()),
+		)
+	})
+
+	it("distinguishes a replaced file (dev/ino change) with identical content state", () => {
+		const replaced = makeStats({ dev: 8n, ino: 999n })
+		expect(versionTokenOfStat(replaced)).not.toBe(versionTokenOfStat(makeStats()))
+	})
+
+	it("renders nanosecond resolution exactly (no float quantization)", () => {
+		const base = versionTokenOfStat(makeStats())
+		const plusOneMicrosecond = versionTokenOfStat(makeStats({ mtimeNs: 1_700_000_000_123_457_789n }))
+		// 1_000 ns apart — the BigInt derivation must keep the delta exact.
+		const baseNs = BigInt(base.split(":")[3])
+		const microNs = BigInt(plusOneMicrosecond.split(":")[3])
+		expect(microNs - baseNs).toBe(1_000n)
+	})
+
+	it("handles sizes beyond Number.MAX_SAFE_INTEGER without precision loss", () => {
+		const size = 10_000_000_000_000_001n // 10^16 + 1 > 2^53
+		const token = versionTokenOfStat(makeStats({ size }))
+		expect(token).toBe(`7:4242:${size}:1700000000123456789:1700000000789999999`)
+	})
+})
+
+describe("computeVersionToken (A1, epic #1375)", () => {
+	let tmpDir: string
+	let file: string
+
+	beforeEach(async () => {
+		tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "version-token-"))
+		file = path.join(tmpDir, "seed.txt")
+		await fs.writeFile(file, "seed content", "utf8")
+	})
+
+	afterEach(async () => {
+		await fs.rm(tmpDir, { recursive: true, force: true })
+	})
+
+	it("derives the token from the on-disk state (single bigint stat)", async () => {
+		const token = await computeVersionToken(file)
+		expect(token).toBe(versionTokenOfStat(await fs.stat(file, { bigint: true })))
+	})
+
+	it("changes when the file content changes", async () => {
+		const before = await computeVersionToken(file)
+		// Different size + a new mtime — both must move the token.
+		await fs.writeFile(file, "seed content, extended", "utf8")
+		await new Promise((resolve) => setTimeout(resolve, 5))
+		expect(await computeVersionToken(file)).not.toBe(before)
+	})
+
+	it("rejects with ENOENT for an absent file", async () => {
+		await expect(computeVersionToken(path.join(tmpDir, "absent.txt"))).rejects.toMatchObject({
+			code: "ENOENT",
+		})
+	})
+})

src/utils/versionToken.ts

@@ -0,0 +1,48 @@
+import { stat } from "fs/promises"
+import type { BigIntStats } from "fs"
+
+/**
+ * Version token for the compare-and-swap write guard (upstream epic #1375, phase A1).
+ *
+ * A token is a pure function of a file's on-disk state, derived from a single
+ * `fs.stat(path, { bigint: true })`, so every process that observes the same file
+ * state (a second VS Code window, the CLI, the user's own editor tooling) computes
+ * the same token. The downstream guard phases (A2/A3) compare the token observed at
+ * read time with the token recomputed just before a write to detect "the file
+ * changed since the read" (stale) or "the file was replaced by a different file"
+ * (dev/ino change).
+ *
+ * Format: `dev:ino:size:mtimeNs:ctimeNs`
+ *
+ * Precision: the stat is fetched in `bigint` mode, so all five fields are exact
+ * `BigInt` values rendered as decimal strings — no float is involved anywhere.
+ * There is therefore no precision loss for large sizes or inodes (a Windows file ID
+ * exceeds 2^53 and is still exact), and the ns timestamps are the kernel's exact
+ * nanosecond values rather than a ms→ns derivation (no ~256 ns double-precision
+ * quantum). Guarantee: same disk state → same token, deterministic across
+ * processes; any change to size, file identity, or mtime/ctime → a different token.
+ *
+ * Platform note: on POSIX `ctime` is the last file-status change; on Windows it is
+ * the file creation time. The token only requires it to move when the file's
+ * metadata is replaced, which holds on both.
+ */
+
+/**
+ * Build the version token from an already-fetched `BigIntStats` — no I/O.
+ *
+ * Exported separately from {@link computeVersionToken} so tests can pin the exact
+ * format against synthetic stats.
+ */
+export function versionTokenOfStat(stats: BigIntStats): string {
+	return [stats.dev, stats.ino, stats.size, stats.mtimeNs, stats.ctimeNs].map((value) => value.toString()).join(":")
+}
+
+/**
+ * Compute the version token for a file (one `fs.stat` in bigint mode).
+ *
+ * Rejects with the underlying ENOENT (or equivalent) error when the file is absent;
+ * how an unobservable target is treated is decided by the guard layer (A3).
+ */
+export async function computeVersionToken(filePath: string): Promise<string> {
+	return versionTokenOfStat(await stat(filePath, { bigint: true }))
+}