Skip to content

Commit 7f4a40a

Browse files
fix(utils): refuse ambiguous backup recency in jsonFileRecovery
Two leftover backups whose mtimes are exactly equal carry no evidence about which one is the newer committed state - mtime is the only recency signal recovery has - so the previous code picked whichever readdir listed first and then garbage-collected the other one. That is a silent, order-dependent choice between two committed states, and the loser is deleted, so the evidence disappears with it. Recovery now refuses on an exact tie: it restores nothing and deletes nothing, and both copies stay on disk for a human to read. That is the same fail-closed decision recovery already makes for a backup it cannot stat, so it is a rule the file already states, applied to the one input where its recency signal says nothing. AmbiguousBackupRecencyError carries code AMBIGUOUS_BACKUP_RECENCY plus targetPath, mtimeMs and both backup paths; its message names basenames only, because error telemetry captures message and stack and a workspace path there would carry the local username into that capture. The full paths stay on the properties for whoever has to decide between the two tied copies. Proof, all five rows in jsonFileRecovery.test.ts: the tie between two backups rejects with AmbiguousBackupRecencyError / AMBIGUOUS_BACKUP_RECENCY and leaves both copies on disk with the canonical path still absent; the different-mtime pair still restores the newest backup and garbage-collects the loser, which is the contract the tie rows must not break; three backups whose tie sits BELOW the winner (200, 100, 100) still restore the newest and remove both losers, so the guard cannot be widened into 'any duplicate mtime means refuse'; the same tie driven through the reader entry point (recoverMissingJsonFile) rejects and reports through the persistence trace; and the error message names basenames only while the full paths stay on targetPath, firstBackupPath and secondBackupPath. Negative controls and the mutation band for this unit are recorded on the PR body with their exits and byte pairs, as is the price of the delta at the tip this branch was cut from. Unit U5c-2 of the planned split of #2357 (plan of record: #1991 (comment)). Branch cut from main at d3d9cd4; it does not depend on the fileLock unit that merges before it: this file only calls withFileLock, which exists at that tip. No changeset, no CHANGELOG row (AGENTS.md). Co-Authored-By: Claude <[email protected]>
1 parent d3d9cd4 commit 7f4a40a

2 files changed

Lines changed: 173 additions & 3 deletions

File tree

‎src/utils/__tests__/jsonFileRecovery.test.ts‎

Lines changed: 128 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import * as path from "path"
44

55
import { acquireFileLock } from "../fileLock"
66
import { setPersistenceTraceSink } from "../../core/task-persistence/persistenceTrace"
7-
import { deleteJsonFile, recoverMissingJsonFile } from "../jsonFileRecovery"
7+
import { recoverInterruptedReplacement, deleteJsonFile, recoverMissingJsonFile } from "../jsonFileRecovery"
88
import { readFileWithMissingRetry } from "../../core/task-persistence/readFileWithMissingRetry"
99

1010
vi.mock("fs/promises", async () => {
@@ -57,6 +57,57 @@ describe("reader recovery", () => {
5757
await expect(fs.readFile(backup)).rejects.toMatchObject({ code: "ENOENT" })
5858
})
5959

60+
// The recency choice is `sort((a, b) => b.mtimeMs - a.mtimeMs)` followed by renaming
61+
// the head of that list. mtime is the only signal recovery has, so an exact tie says
62+
// nothing about which backup holds the committed content - the winner would be readdir
63+
// order, and the loser is unlinked. The tie is set with utimes rather than raced
64+
// against the clock, so the row does not depend on how fast two writes land; the
65+
// second row is the control that keeps this from being a test which merely asserts
66+
// "two backups means reject".
67+
it("refuses an exact mtime tie between two backups instead of picking by directory order", async () => {
68+
const otherBackup = path.join(dir, ".history_item.json.bak_2_other.tmp")
69+
await fs.writeFile(otherBackup, JSON.stringify({ other: true }))
70+
const shared = new Date(1_700_000_000_000)
71+
await fs.utimes(backup, shared, shared)
72+
await fs.utimes(otherBackup, shared, shared)
73+
74+
const error = await recoverInterruptedReplacement(target).then(
75+
() => undefined,
76+
(reason: unknown) => reason,
77+
)
78+
expect(error).toMatchObject({
79+
name: "AmbiguousBackupRecencyError",
80+
code: "AMBIGUOUS_BACKUP_RECENCY",
81+
mtimeMs: 1_700_000_000_000,
82+
})
83+
// The diagnostic has to name the magnitude it refused to guess about.
84+
expect(String((error as Error).message)).toContain("share mtime 1700000000000")
85+
86+
// Fail closed: nothing restored, nothing deleted, so both copies survive for a
87+
// human to read.
88+
await expect(fs.access(target)).rejects.toMatchObject({ code: "ENOENT" })
89+
expect(JSON.parse(await fs.readFile(backup, "utf8"))).toEqual({ committed: true })
90+
expect(JSON.parse(await fs.readFile(otherBackup, "utf8"))).toEqual({ other: true })
91+
})
92+
93+
it("restores the newer backup when two backups have different mtimes", async () => {
94+
const otherBackup = path.join(dir, ".history_item.json.bak_2_other.tmp")
95+
await fs.writeFile(otherBackup, JSON.stringify({ other: true }))
96+
const older = new Date(1_700_000_000_000)
97+
const newer = new Date(1_700_000_000_001)
98+
await fs.utimes(otherBackup, older, older)
99+
await fs.utimes(backup, newer, newer)
100+
101+
const recovery = await recoverInterruptedReplacement(target)
102+
103+
expect(recovery.foundLeftovers).toBe(true)
104+
expect(recovery.restoredFrom).toBe(backup)
105+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
106+
// The loser of a decided race is still garbage-collected, which is the contract the
107+
// tie row must not break.
108+
await expect(fs.access(otherBackup)).rejects.toMatchObject({ code: "ENOENT" })
109+
})
110+
60111
it("traces reader restoration and lock waiting", async () => {
61112
const sink = vi.fn()
62113
setPersistenceTraceSink(sink)
@@ -106,4 +157,80 @@ describe("reader recovery", () => {
106157
await expect(recoverMissingJsonFile(target)).resolves.toBe(false)
107158
await expect(fs.stat(dir)).rejects.toMatchObject({ code: "ENOENT" })
108159
})
160+
161+
it("restores the newest backup when two OLDER backups share a tie", async () => {
162+
// Three backups: 200, 100, 100. The tie sits BELOW the winner, so recency is decidable
163+
// and recovery must restore the newest copy and remove both losers. A guard that refused
164+
// every duplicate mtime - not just a tie for the newest slot - would fail this row, which
165+
// is what stops the two tie rows above from standing in for "any duplicate means refuse".
166+
const otherBackup = path.join(dir, ".history_item.json.bak_2_other.tmp")
167+
const thirdBackup = path.join(dir, ".history_item.json.bak_3_third.tmp")
168+
await fs.writeFile(otherBackup, JSON.stringify({ other: true }))
169+
await fs.writeFile(thirdBackup, JSON.stringify({ third: true }))
170+
const older = new Date(1_700_000_000_100)
171+
const newest = new Date(1_700_000_000_200)
172+
await fs.utimes(otherBackup, older, older)
173+
await fs.utimes(thirdBackup, older, older)
174+
await fs.utimes(backup, newest, newest)
175+
176+
const recovery = await recoverInterruptedReplacement(target)
177+
178+
expect(recovery.foundLeftovers).toBe(true)
179+
expect(recovery.restoredFrom).toBe(backup)
180+
expect(JSON.parse(await fs.readFile(target, "utf8"))).toEqual({ committed: true })
181+
await expect(fs.access(otherBackup)).rejects.toMatchObject({ code: "ENOENT" })
182+
await expect(fs.access(thirdBackup)).rejects.toMatchObject({ code: "ENOENT" })
183+
})
184+
185+
it("refuses a tie through the reader entry point and keeps both copies", async () => {
186+
// The refusal has to survive the path a reader actually takes: recoverMissingJsonFile runs
187+
// recovery under the lock and reports the failure through the persistence trace. Asserting
188+
// it here as well keeps a propagation or trace regression from passing while the internal
189+
// helper row still goes green.
190+
const otherBackup = path.join(dir, ".history_item.json.bak_2_other.tmp")
191+
await fs.writeFile(otherBackup, JSON.stringify({ other: true }))
192+
const shared = new Date(1_700_000_000_000)
193+
await fs.utimes(backup, shared, shared)
194+
await fs.utimes(otherBackup, shared, shared)
195+
const sink = vi.fn()
196+
setPersistenceTraceSink(sink)
197+
198+
await expect(recoverMissingJsonFile(target)).rejects.toMatchObject({
199+
name: "AmbiguousBackupRecencyError",
200+
code: "AMBIGUOUS_BACKUP_RECENCY",
201+
})
202+
203+
expect(sink).toHaveBeenCalledWith(expect.stringContaining('"stage":"json-recovery"'))
204+
expect(sink).toHaveBeenCalledWith(expect.stringContaining('"result":"failed"'))
205+
// Fail closed: the tie is still there for a human to decide about.
206+
await expect(fs.access(target)).rejects.toMatchObject({ code: "ENOENT" })
207+
expect(JSON.parse(await fs.readFile(backup, "utf8"))).toEqual({ committed: true })
208+
expect(JSON.parse(await fs.readFile(otherBackup, "utf8"))).toEqual({ other: true })
209+
})
210+
211+
it("keeps the tied paths out of the tie error message and on the error properties", async () => {
212+
// Error telemetry captures message and stack, and a workspace path carries the local
213+
// username into that capture. The message names the basenames it refused to choose between;
214+
// the full paths stay on the properties, which is where a human acts on them.
215+
const otherBackup = path.join(dir, ".history_item.json.bak_2_other.tmp")
216+
await fs.writeFile(otherBackup, JSON.stringify({ other: true }))
217+
const shared = new Date(1_700_000_000_000)
218+
await fs.utimes(backup, shared, shared)
219+
await fs.utimes(otherBackup, shared, shared)
220+
221+
const error = await recoverInterruptedReplacement(target).then(
222+
() => undefined,
223+
(reason: unknown) => reason,
224+
)
225+
const tie = error as Error & { targetPath: string; firstBackupPath: string; secondBackupPath: string }
226+
227+
expect(tie.name).toBe("AmbiguousBackupRecencyError")
228+
expect(tie.message).not.toContain(path.sep)
229+
expect(tie.message).not.toContain(dir)
230+
expect(tie.message).toContain("history_item.json")
231+
expect(tie.message).toContain("share mtime 1700000000000")
232+
expect(tie.targetPath).toBe(target)
233+
expect(tie.firstBackupPath).toContain(dir)
234+
expect(tie.secondBackupPath).toContain(dir)
235+
})
109236
})

‎src/utils/jsonFileRecovery.ts‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,36 @@ export async function deleteJsonFile(filePath: string): Promise<void> {
9999
})
100100
}
101101

102+
/**
103+
* Two leftover backups whose mtimes are exactly equal carry no evidence about which
104+
* one is the newer committed state - mtime is the only recency signal recovery has -
105+
* so choosing between them would be the order readdir happened to list them in, and
106+
* the loser of that order is garbage-collected below. Recovery refuses instead, the
107+
* same fail-closed decision it already makes for a backup it cannot stat: nothing is
108+
* restored and nothing is deleted, so both copies stay on disk for a human to read.
109+
*/
110+
class AmbiguousBackupRecencyError extends Error {
111+
readonly code = "AMBIGUOUS_BACKUP_RECENCY"
112+
readonly targetPath: string
113+
readonly mtimeMs: number
114+
readonly firstBackupPath: string
115+
readonly secondBackupPath: string
116+
constructor(targetPath: string, mtimeMs: number, firstBackupPath: string, secondBackupPath: string) {
117+
super(
118+
// Basenames, not absolute paths: this error travels to callers that report it, and error
119+
// telemetry captures message and stack, so a workspace path here would carry the local
120+
// username into that capture. The full paths stay on the properties for whoever has to
121+
// decide between the two tied copies.
122+
`Cannot tell which backup of ${path.basename(targetPath)} is the newest committed state: ${path.basename(firstBackupPath)} and ${path.basename(secondBackupPath)} share mtime ${mtimeMs}. Nothing was restored or deleted.`,
123+
)
124+
this.name = "AmbiguousBackupRecencyError"
125+
this.targetPath = targetPath
126+
this.mtimeMs = mtimeMs
127+
this.firstBackupPath = firstBackupPath
128+
this.secondBackupPath = secondBackupPath
129+
}
130+
}
131+
102132
/**
103133
* Heals the canonical path after an interrupted previous write. Must run
104134
* under the advisory lock and before any data is read or written: temp and
@@ -112,8 +142,9 @@ export async function deleteJsonFile(filePath: string): Promise<void> {
112142
* renamed to its backup but before the replacement landed. A process exit
113143
* at that point leaves the canonical path absent, which readers see as a
114144
* permanent ENOENT that no retry can repair, so the newest backup is
115-
* restored first. Leftover replacement and backup files are garbage
116-
* collected afterwards.
145+
* restored first, chosen by mtime. Two backups that share an exact mtime are
146+
* refused rather than split by directory order; see AmbiguousBackupRecencyError.
147+
* Leftover replacement and backup files are garbage collected afterwards.
117148
*
118149
* @returns Whether leftover files were found, and the backup path that was
119150
* restored, if any.
@@ -181,6 +212,18 @@ export async function recoverInterruptedReplacement(
181212
).filter((entry): entry is { backupPath: string; mtimeMs: number } => entry !== null)
182213
if (backupStats.length > 0) {
183214
backupStats.sort((a, b) => b.mtimeMs - a.mtimeMs)
215+
if (backupStats.length > 1 && backupStats[1].mtimeMs === backupStats[0].mtimeMs) {
216+
// mtime is the only recency signal here, and an exact tie carries none: the
217+
// winner would be the order readdir happened to list the two in, and the
218+
// loser is unlinked below. Refuse, as recovery already refuses a backup it
219+
// cannot stat.
220+
throw new AmbiguousBackupRecencyError(
221+
absoluteFilePath,
222+
backupStats[0].mtimeMs,
223+
backupStats[0].backupPath,
224+
backupStats[1].backupPath,
225+
)
226+
}
184227
const newestBackupPath = backupStats[0].backupPath
185228
try {
186229
await fs.rename(newestBackupPath, absoluteFilePath)

0 commit comments

Comments
 (0)