Throw on a corrupt per-tab value and recover at the seam

parseSessionJson swallowed both JSON and schema-validation errors into an
indistinguishable null, hiding corruption and conflating it with a
legitimate absent value. Separate detecting corruption from deciding what
to do about it: deserialize now returns null only for an absent value and
throws (SyntaxError or ZodError) on a present-but-invalid one.

createSessionScopedAtom owns seeding policy, so it is the seam that
catches: a corrupt per-tab value (or a sessionStorage read that throws a
SecurityError when DOM storage is blocked) is logged and treated as a
miss, falling through to the breadcrumb then the default rather than
crashing app startup.

Update the per-tab-storage ADR to describe the throw-and-recover flow.

Author: kmcginnes

docs/adr/20260630-per-tab-session-scoped-storage-primitive.md

@@ -22,7 +22,7 @@ Extract the per-tab + breadcrumb mechanism into one primitive, `createSessionSco
 
 `createActiveConfigurationAtom` is refactored onto the primitive rather than left as a parallel implementation, so the seed-and-claim logic lives in exactly one place with one set of tests.
 
-A per-tab value crosses two backings with different serialization needs, so the primitive takes a **`SessionValueCodec<T>`**: the breadcrumb keeps the native value (structured clone preserves a `Set`), while `sessionStorage` holds only strings. The codec's `deserialize` validates the parsed string with **zod** and returns `null` for a missing, unparseable, or wrong-shape value, so a stale or hand-edited per-tab value falls through to the breadcrumb instead of seeding a bad shape. Graph-view layout's codec serializes its `activeToggles` `Set` as an array and rebuilds it on read via a zod `.transform`; schema-view layout is plain JSON. Active Connection's value is a bare id string, so its codec passes the string through and skips zod.
+A per-tab value crosses two backings with different serialization needs, so the primitive takes a **`SessionValueCodec<T>`**: the breadcrumb keeps the native value (structured clone preserves a `Set`), while `sessionStorage` holds only strings. The codec's `deserialize` returns `null` only for an absent value (a legitimate miss) and validates a present value with **zod**, _throwing_ on an unparseable or wrong-shape value rather than swallowing it. Detecting corruption is thus separate from deciding what to do about it: the seam (`createSessionScopedAtom`) catches the throw, logs it, and treats it as a miss so a stale or hand-edited per-tab value falls through to the breadcrumb instead of seeding a bad shape or crashing startup. Graph-view layout's codec serializes its `activeToggles` `Set` as an array and rebuilds it on read via a zod `.transform`; schema-view layout is plain JSON. Active Connection's value is a bare id string, so its codec passes the string through and skips zod.
 
 ## Considered Options
 
@@ -35,7 +35,7 @@ A per-tab value crosses two backings with different serialization needs, so the
 
 - **No migration.** The breadcrumb keeps each concept's existing localForage key and native shape; the codec only governs the per-tab `sessionStorage` round-trip. Existing stored layouts seed a fresh tab unchanged.
 - **Cold start can resume a layout set in a different tab** (last-writer-wins breadcrumb), the same honest "resume the most recent" semantics Active Connection accepts. Per the storage model — read once at creation, never re-read (`per-key-diff-merge` context) — no scope here has ever had live cross-tab sync; an already-open tab does not reflect another tab's change until it reloads.
-- **A corrupt or stale per-tab value self-heals.** `deserialize` returning `null` falls through to the breadcrumb then the default; breadcrumb **write** failures still surface through the persistence-status path (`storage-layer-owns-persistence-failure`). Appropriate for non-critical view preferences.
+- **A corrupt or stale per-tab value self-heals.** `deserialize` throws on a present-but-invalid value (and reading a blocked `sessionStorage` can throw a `SecurityError`); the seam catches either, logs a warning, and falls through to the breadcrumb then the default rather than crashing startup. Breadcrumb **write** failures still surface through the persistence-status path (`storage-layer-owns-persistence-failure`). Appropriate for non-critical view preferences.
 - **Rule for new atoms.** A concept that should diverge per tab uses `createSessionScopedAtom` with a codec; a shared Map-keyed collection uses `reconcileMapByKey` (`per-key-diff-merge`); a shared scalar uses plain `atomWithLocalForage`. Scope is now a visible choice at the atom's creation, not an implicit consequence of which factory was reached for.
 - The `sessionStorage` backing stays injectable, so per-tab isolation is tested directly with separate stores and separate `sessionStorage` mocks over one shared mock localForage.
 - This primitive is the `perTab` adapter that spike #1876 proposes to formalize alongside the other two scopes. This ADR records the **scope** decision; #1876 may later relocate where the logic lives without re-deciding it.

packages/graph-explorer/src/core/StateProvider/graphViewLayoutDefaults.test.ts

@@ -32,9 +32,13 @@ describe("graphViewLayoutCodec", () => {
     ).toStrictEqual(defaultGraphViewLayout);
   });
 
-  test("treats a missing or corrupt value as a miss", () => {
+  test("treats an absent value as a miss", () => {
     expect(graphViewLayoutCodec.deserialize(null)).toBeNull();
-    expect(graphViewLayoutCodec.deserialize("{ not json")).toBeNull();
-    expect(graphViewLayoutCodec.deserialize("{}")).toBeNull();
+    expect(graphViewLayoutCodec.deserialize("")).toBeNull();
+  });
+
+  test("throws on a corrupt value so the seam can discard it", () => {
+    expect(() => graphViewLayoutCodec.deserialize("{ not json")).toThrow();
+    expect(() => graphViewLayoutCodec.deserialize("{}")).toThrow();
   });
 });

packages/graph-explorer/src/core/StateProvider/schemaViewLayoutDefaults.test.ts

@@ -29,9 +29,13 @@ describe("schemaViewLayoutCodec", () => {
     ).toStrictEqual(defaultSchemaViewLayout);
   });
 
-  test("treats a missing or corrupt value as a miss", () => {
+  test("treats an absent value as a miss", () => {
     expect(schemaViewLayoutCodec.deserialize(null)).toBeNull();
-    expect(schemaViewLayoutCodec.deserialize("{ not json")).toBeNull();
-    expect(schemaViewLayoutCodec.deserialize("{}")).toBeNull();
+    expect(schemaViewLayoutCodec.deserialize("")).toBeNull();
+  });
+
+  test("throws on a corrupt value so the seam can discard it", () => {
+    expect(() => schemaViewLayoutCodec.deserialize("{ not json")).toThrow();
+    expect(() => schemaViewLayoutCodec.deserialize("{}")).toThrow();
   });
 });

packages/graph-explorer/src/core/StateProvider/sessionScopedStorage.test.ts

@@ -1,8 +1,10 @@
 import { createStore } from "jotai";
 import localForage from "localforage";
-import { beforeEach, describe, expect, test } from "vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
 import { z } from "zod";
 
+import { logger } from "@/utils";
+
 import {
   defaultGraphViewLayout,
   type GraphViewLayout,
@@ -113,7 +115,7 @@ describe("createSessionScopedAtom", () => {
     expect(store.get(atom)).toStrictEqual({ count: 42 });
   });
 
-  test("treats a corrupt session value as a miss and falls back to the breadcrumb", async () => {
+  test("discards a corrupt session value with a warning and falls back to the breadcrumb", async () => {
     await localForage.setItem<Counter>(KEY, { count: 7 });
     const sessionStorage = createInMemorySessionStorage();
     sessionStorage.setItem(KEY, "{ not valid json");
@@ -127,6 +129,28 @@ describe("createSessionScopedAtom", () => {
 
     const store = createStore();
     expect(store.get(atom)).toStrictEqual({ count: 7 });
+    expect(vi.mocked(logger.warn)).toHaveBeenCalledOnce();
+  });
+
+  test("recovers when reading sessionStorage throws, falling back to the breadcrumb", async () => {
+    await localForage.setItem<Counter>(KEY, { count: 7 });
+    const sessionStorage = createInMemorySessionStorage();
+    // DOM storage blocked: accessing the value throws a SecurityError rather
+    // than returning null. The seam must treat this as a miss, not crash boot.
+    vi.spyOn(sessionStorage, "getItem").mockImplementation(() => {
+      throw new DOMException("blocked", "SecurityError");
+    });
+
+    const atom = await createSessionScopedAtom<Counter>({
+      key: KEY,
+      defaultValue: { count: 0 },
+      codec: counterCodec,
+      sessionStorage,
+    });
+
+    const store = createStore();
+    expect(store.get(atom)).toStrictEqual({ count: 7 });
+    expect(vi.mocked(logger.warn)).toHaveBeenCalledOnce();
   });
 
   test("writing updates this tab synchronously and the breadcrumb in the background", async () => {

packages/graph-explorer/src/core/StateProvider/sessionScopedStorage.ts

@@ -2,6 +2,8 @@ import type { z } from "zod";
 
 import localForage from "localforage";
 
+import { logger } from "@/utils";
+
 import { persistThroughQueue } from "./persistence";
 import { resolveSessionStorage } from "./safeSessionStorage";
 import { createWriteThroughAtom } from "./writeThroughAtom";
@@ -22,10 +24,12 @@ export type SessionValueCodec<T> = {
 };
 
 /**
- * Parses a sessionStorage JSON string against `schema`, returning `null` for a
- * missing, unparseable, or schema-invalid value so the caller treats it as a
- * miss. This keeps a stale or hand-edited per-tab value from seeding the atom
- * with the wrong shape.
+ * Parses a sessionStorage JSON string against `schema`. Returns `null` only for
+ * an absent value (`null` or empty string) — a legitimate miss. A present but
+ * unparseable or schema-invalid value is corrupt and **throws** (`SyntaxError`
+ * from `JSON.parse` or `ZodError` from the schema); the seam that owns seeding
+ * (`createSessionScopedAtom`) catches it, so detecting corruption stays separate
+ * from deciding what to do about it.
  */
 export function parseSessionJson<T>(
   raw: string | null,
@@ -34,12 +38,7 @@ export function parseSessionJson<T>(
   if (raw === null || raw === "") {
     return null;
   }
-  try {
-    const result = schema.safeParse(JSON.parse(raw));
-    return result.success ? result.data : null;
-  } catch {
-    return null;
-  }
+  return schema.parse(JSON.parse(raw));
 }
 
 /**
@@ -75,7 +74,7 @@ export async function createSessionScopedAtom<T>({
   codec: SessionValueCodec<T>;
   sessionStorage?: Storage;
 }) {
-  let seedValue = codec.deserialize(sessionStorage.getItem(key));
+  let seedValue = readSessionSeed(sessionStorage, key, codec);
   if (seedValue === null) {
     // Cold start: seed from the shared breadcrumb and claim it into this tab's
     // sessionStorage, so a later reload reads this value back rather than
@@ -101,6 +100,31 @@ export async function createSessionScopedAtom<T>({
   );
 }
 
+/**
+ * Reads and decodes this tab's per-tab seed, recovering from a corrupt value.
+ *
+ * `codec.deserialize` throws on a present-but-invalid value (and reading
+ * sessionStorage itself can throw a `SecurityError` when DOM storage is
+ * blocked). Either is a recoverable miss: a stale or hand-edited per-tab value
+ * should not crash app startup, so it is logged and treated as absent, letting
+ * the caller fall through to the shared breadcrumb then the default.
+ */
+function readSessionSeed<T>(
+  sessionStorage: Storage,
+  key: string,
+  codec: SessionValueCodec<T>,
+): T | null {
+  try {
+    return codec.deserialize(sessionStorage.getItem(key));
+  } catch (error) {
+    logger.warn(
+      `Discarding corrupt per-tab value for "${key}"; falling back to the persisted breadcrumb.`,
+      error,
+    );
+    return null;
+  }
+}
+
 /** Applies a serialized value to sessionStorage, removing the key for `null`. */
 function writeSession(
   sessionStorage: Storage,