feat: version runtime observability snapshots

Author: ndycode

lib/runtime/runtime-observability.ts

@@ -34,6 +34,7 @@ export interface RuntimeMetricsSnapshot {
 }
 
 export interface RuntimeObservabilitySnapshot {
+	version: number;
 	updatedAt: number;
 	currentRequestId: string | null;
 	responsesRequests: number;
@@ -46,6 +47,7 @@ export interface RuntimeObservabilitySnapshot {
 
 const SNAPSHOT_FILE_NAME = "runtime-observability.json";
 const PERSIST_RUNTIME_SNAPSHOT = process.env.VITEST !== "true";
+const RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION = 1;
 
 let snapshotState: RuntimeObservabilitySnapshot | null = null;
 let pendingWrite: Promise<void> | null = null;
@@ -56,6 +58,7 @@ function getSnapshotPath(): string {
 
 function createDefaultSnapshot(): RuntimeObservabilitySnapshot {
 	return {
+		version: RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION,
 		updatedAt: 0,
 		currentRequestId: null,
 		responsesRequests: 0,
@@ -148,7 +151,26 @@ export async function loadPersistedRuntimeObservabilitySnapshot(): Promise<Runti
 	}
 	try {
 		const raw = await fs.readFile(path, "utf-8");
-		return JSON.parse(raw) as RuntimeObservabilitySnapshot;
+		const parsed = JSON.parse(raw) as Partial<RuntimeObservabilitySnapshot> | null;
+		if (!parsed || typeof parsed !== "object") {
+			return null;
+		}
+		if (
+			typeof parsed.version === "number" &&
+			parsed.version !== RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION
+		) {
+			return null;
+		}
+		const base = createDefaultSnapshot();
+		return {
+			...base,
+			...parsed,
+			version: RUNTIME_OBSERVABILITY_SNAPSHOT_VERSION,
+				runtimeMetrics: {
+					...base.runtimeMetrics,
+					...(parsed.runtimeMetrics ?? {}),
+				},
+			};
 	} catch {
 		return null;
 	}

test/runtime-observability.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const readFileMock = vi.fn();
+vi.mock("node:fs", () => ({
+	existsSync: vi.fn(() => true),
+	promises: {
+		readFile: readFileMock,
+		writeFile: vi.fn(async () => undefined),
+		rename: vi.fn(async () => undefined),
+		unlink: vi.fn(async () => undefined),
+		mkdir: vi.fn(async () => undefined),
+	},
+}));
+
+vi.mock("../lib/runtime-paths.js", () => ({
+	getCodexMultiAuthDir: () => "/mock/.codex/multi-auth",
+}));
+
+describe("runtime observability snapshot versioning", () => {
+	beforeEach(() => {
+		vi.resetModules();
+	});
+
+	afterEach(() => {
+		readFileMock.mockReset();
+	});
+
+	it("normalizes legacy unversioned snapshots", async () => {
+		readFileMock.mockResolvedValueOnce(
+			JSON.stringify({
+				updatedAt: 1,
+				responsesRequests: 2,
+				runtimeMetrics: { totalRequests: 3 },
+			}),
+		);
+
+		const { loadPersistedRuntimeObservabilitySnapshot } = await import(
+			"../lib/runtime/runtime-observability.js"
+		);
+		const snapshot = await loadPersistedRuntimeObservabilitySnapshot();
+
+		expect(snapshot?.version).toBe(1);
+		expect(snapshot?.responsesRequests).toBe(2);
+		expect(snapshot?.runtimeMetrics.totalRequests).toBe(3);
+		expect(snapshot?.runtimeMetrics.failedRequests).toBe(0);
+	});
+
+	it("drops unknown future snapshot versions safely", async () => {
+		readFileMock.mockResolvedValueOnce(JSON.stringify({ version: 99 }));
+
+		const { loadPersistedRuntimeObservabilitySnapshot } = await import(
+			"../lib/runtime/runtime-observability.js"
+		);
+		const snapshot = await loadPersistedRuntimeObservabilitySnapshot();
+
+		expect(snapshot).toBeNull();
+	});
+});