Finalize replay cache partitioning

Author: Akarithos

docs/backend/replay.md

@@ -48,9 +48,10 @@ The normal startup path trusts cache metadata. It does not decompress every bloc
 to validate it; the file name and size are enough to publish availability, and
 decompressing the whole corpus on a cold boot would dominate startup time on
 modest hardware. A block is only read from disk when a viewer asks for it. If a
-cached block is missing or a viewer reports that it could not be decoded, the
-cache is corrected for that day and a diagnostic is recorded instead of leaving
-the stale coverage in place.
+cached block is missing, the cache is corrected for that day and a diagnostic is
+recorded instead of leaving the stale coverage in place. Browser-side decode
+failures stay browser-side: they raise diagnostics for the operator, but they do
+not ask the server to mutate cache state.
 
 ## Retention
 

docs/getting-started/configuration.md

@@ -113,12 +113,16 @@ behind the reverse proxy and let the proxy serve finalized artifacts directly:
 handle_path /api/replay/blocks/* {
 	root * /var/lib/ident/replay/blocks
 
-	@zstd_block path *.zst
+	@zstd_block {
+		path *.zst
+		file
+	}
 	header @zstd_block Content-Type application/octet-stream
 	header @zstd_block Cache-Control "public, max-age=31536000, immutable"
 
 	@accepts_zstd {
 		path *.zst
+		file
 		header Accept-Encoding *zstd*
 	}
 	header @accepts_zstd Content-Type application/json

ident/src/data/replay.test.ts

@@ -150,6 +150,66 @@ describe("replay data loading", () => {
     expect(selectDisplayTrailsByHex(st).abc123).toHaveLength(2);
   });
 
+  it("expands compact replay aircraft into the display aircraft shape", async () => {
+    const block = {
+      version: 2,
+      start: 120_000,
+      end: 180_000,
+      step_ms: 5_000,
+      frames: [
+        {
+          ts: 130_000,
+          aircraft: [
+            {
+              hex: "abc123",
+              type: "adsb_icao",
+              flight: "UAL123",
+              r: "N12345",
+              t: "B738",
+              lat: 34,
+              lon: -118,
+              alt_baro: 12000,
+              gs: 420,
+              track: 90,
+              seen_pos: 0.5,
+              rssi: -12,
+            },
+            {
+              hex: "ground1",
+              type: "adsb_icao",
+              alt_baro: "ground",
+            },
+          ],
+        },
+      ],
+    };
+    globalThis.fetch = vi.fn(async (url: string) =>
+      url.includes("manifest") ? responseJson(manifest()) : responseJson(block),
+    ) as never;
+
+    await refreshReplayManifest();
+    useIdentStore.getState().enterReplay(130_000);
+    await ensureReplayRange(120_000, 180_000);
+
+    const aircraft = selectDisplayAircraftMap(useIdentStore.getState());
+    expect(aircraft.get("abc123")).toMatchObject({
+      hex: "abc123",
+      idKind: "icao",
+      source: "adsb_icao",
+      flight: "UAL123",
+      reg: "N12345",
+      typeDesignator: "B738",
+      altBaroFt: 12000,
+      gsKt: 420,
+      trackDeg: 90,
+      seenPosSec: 0.5,
+      rssiDbfs: -12,
+    });
+    expect(aircraft.get("ground1")).toMatchObject({
+      onGround: true,
+    });
+  });
+
   it("does not request blocks that are already loaded", async () => {
     const block = replayBlock();
     globalThis.fetch = vi.fn(async (url: string) =>
@@ -574,16 +634,10 @@ describe("replay data loading", () => {
     await refreshReplayManifest();
     await ensureReplayRange(120_000, 180_000, { background: true });
 
-    expect(globalThis.fetch).toHaveBeenCalledTimes(4);
-    expect(globalThis.fetch).toHaveBeenCalledWith(
+    expect(globalThis.fetch).toHaveBeenCalledTimes(3);
+    expect(globalThis.fetch).not.toHaveBeenCalledWith(
       "/ident/api/replay/block-failure",
-      expect.objectContaining({
-        method: "POST",
-        body: JSON.stringify({
-          url: "/api/replay/blocks/120000-180000.json.zst",
-          reason: "decode_failed",
-        }),
-      }),
+      expect.anything(),
     );
     expect(warn).not.toHaveBeenCalledWith(
       "[ident replay] background block load failed",
@@ -600,6 +654,37 @@ describe("replay data loading", () => {
     );
   });
 
+  it("surfaces replay blocks whose frames normalize away", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    globalThis.fetch = vi.fn(async (url: string) =>
+      url.includes("manifest")
+        ? responseJson(manifest())
+        : responseJson({
+            version: 2,
+            start: 120_000,
+            end: 180_000,
+            step_ms: 5_000,
+            frames: [{ aircraft: [{ flight: "BROKEN" }] }],
+          }),
+    ) as never;
+
+    await refreshReplayManifest();
+    await ensureReplayRange(120_000, 180_000, { background: true });
+
+    expect(globalThis.fetch).not.toHaveBeenCalledWith(
+      "/ident/api/replay/block-failure",
+      expect.anything(),
+    );
+    expect(useIdentStore.getState().replay.error).toContain(
+      "Invalid replay block",
+    );
+    expect(
+      useIdentStore.getState().replay.cache[
+        "/api/replay/blocks/120000-180000.json.zst"
+      ],
+    ).toBeUndefined();
+  });
+
   it("retries malformed replay blocks and clears the matching error after recovery", async () => {
     let malformed = true;
     globalThis.fetch = vi.fn(async (url: string) => {

ident/src/data/replay.ts

@@ -203,7 +203,11 @@ function loadReplayBlock(block: ReplayBlockIndex): Promise<void> | null {
       );
       if (controller.signal.aborted) throw new ReplayLoadCanceled();
       const body = decodeReplayBlockResponse(bytes) as ReplayBlockFile;
-      if (body.version !== 2 || !Array.isArray(body.frames)) {
+      if (
+        body.version !== 2 ||
+        !Array.isArray(body.frames) ||
+        !hasReplayFrameSample(body.frames)
+      ) {
         throw new ReplayBlockFormatError(block.url);
       }
       useIdentStore.getState().setReplayBlock(block.url, body);
@@ -212,7 +216,6 @@ function loadReplayBlock(block: ReplayBlockIndex): Promise<void> | null {
         throw err;
       }
       if (err instanceof ReplayBlockFormatError) {
-        void reportReplayBlockFailure(block.url, "decode_failed");
         emitFrontendDiagnostic({
           severity: "warning",
           channel: "frontend.replay",
@@ -222,7 +225,6 @@ function loadReplayBlock(block: ReplayBlockIndex): Promise<void> | null {
         throw err;
       }
       if (err instanceof ReplayBlockBodyError) {
-        void reportReplayBlockFailure(block.url, "decode_failed");
         emitFrontendDiagnostic({
           severity: "warning",
           channel: "frontend.replay",
@@ -251,21 +253,14 @@ function loadReplayBlock(block: ReplayBlockIndex): Promise<void> | null {
   return load;
 }
 
-async function reportReplayBlockFailure(
-  url: string,
-  reason: "decode_failed" | "missing",
-): Promise<void> {
-  try {
-    await fetch(appPath("api/replay/block-failure"), {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      cache: "no-store",
-      body: JSON.stringify({ url, reason }),
-    });
-  } catch {
-    // Best-effort cache repair signal only; replay loading already reports
-    // the user-visible diagnostic above.
-  }
+function hasReplayFrameSample(frames: unknown[]): boolean {
+  return frames.some(
+    (frame) =>
+      frame != null &&
+      typeof frame === "object" &&
+      typeof (frame as { ts?: unknown }).ts === "number" &&
+      Number.isFinite((frame as { ts: number }).ts),
+  );
 }
 
 function abortStaleBlockLoads(