import { open, type FileHandle } from "node:fs/promises"; import { vi } from "vitest"; import { phaseGate } from "./lifecycleHarness.js"; /** Pause after one selected file chunk reaches the operating system. */ export const holdFirstFileRead = async (path: string) => { const probe = await open(path, "r"); const identity = await probe.stat(); const fileHandlePrototype = Object.getPrototypeOf(probe) as { read( buffer: Buffer, offset: number, length: number, position: number | null, ): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>; }; await probe.close(); let totalReadBytes = 0; let readCount = 0; const firstRead = phaseGate(); const read = fileHandlePrototype.read; vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function ( this: FileHandle, ...args: [Buffer, number, number, number | null] ) { const current = await this.stat(); const isTarget = current.dev === identity.dev && current.ino === identity.ino; const result = await read.call(this, ...args); if (!isTarget) return result; totalReadBytes += result.bytesRead; readCount += 1; if (readCount === 1) await firstRead.hold(); return result; }); return { /** Wait until the first read is held; fails if `operation` settles first. */ reached: firstRead.reached, release: () => firstRead.release(), get readCount() { return readCount; }, get totalReadBytes() { return totalReadBytes; }, }; };