gloomberb 0.13.2 → 0.14.0

package/src/data/config/store/index.test.ts

@@ -72,6 +72,25 @@ test("existing users retain pending and completed plugin migrations", async () =
 });
 
 describe("sanitizeLayout", () => {
+  test("disk reload keeps explicit public and broker selections for fixed panes and their followers", async () => {
+    const dataDir = await createTempConfigDir();
+    const selections = [
+      { kind: "fixed", symbol: "ASML:XAMS", instrument: null, listing: { name: "ASML", exchange: "AMS", currency: "EUR", type: "EQUITY" } },
+      { kind: "fixed", symbol: "ES", instrument: { brokerId: "ibkr", brokerInstanceId: "retirement", conId: 123, symbol: "ES", localSymbol: "ESZ6", secType: "FUT", exchange: "CME", primaryExchange: "CME", currency: "USD", lastTradeDateOrContractMonth: "20261218", multiplier: "50", tradingClass: "ES" } },
+      { kind: "fixed", symbol: "SPY", instrument: { brokerId: "ibkr", brokerInstanceId: "taxable", symbol: "SPY", secType: "OPT", exchange: "SMART", currency: "USD", lastTradeDateOrContractMonth: "20260918", right: "P", strike: 700, multiplier: "100" } },
+    ];
+    const layout = { dockRoot: null, instances: [
+      ...selections.map((binding, i) => ({ instanceId: `ticker-research:${i}`, paneId: "ticker-research", binding })),
+      { instanceId: "follower", paneId: "chart-composer", binding: { kind: "follow", sourceInstanceId: "ticker-research:1" } },
+    ], floating: [...selections.map((_, i) => `ticker-research:${i}`), "follower"].map(instanceId => ({ instanceId, x: 0, y: 0, width: 80, height: 24 })), detached: [] };
+    await writeConfigJson(dataDir, createSavedConfig({ layout, layouts: [{ name: "Contracts", layout }] }));
+    const loaded = await loadConfig(dataDir);
+    await saveConfig(loaded);
+    const reopened = await loadConfig(dataDir);
+    expect(reopened.layout.instances.map(pane => pane.binding)).toEqual(layout.instances.map(pane => pane.binding));
+    expect(reopened.layouts[0]?.layout.instances.map(pane => pane.binding)).toEqual(layout.instances.map(pane => pane.binding));
+  });
+
   test("preserves an intentionally blank layout", () => {
     expect(sanitizeLayout({
       dockRoot: null,
@@ -86,6 +105,24 @@ describe("sanitizeLayout", () => {
     });
   });
 
+  test("keeps the pane lock across a save/load round trip", () => {
+    const layout = sanitizeLayout({
+      dockRoot: { kind: "pane", instanceId: "portfolio-list:locked" },
+      instances: [
+        {
+          instanceId: "portfolio-list:locked",
+          paneId: "portfolio-list",
+          binding: { kind: "none" },
+          locked: true,
+        },
+      ],
+      floating: [],
+      detached: [],
+    }, DEFAULT_LAYOUT);
+
+    expect(layout.instances[0]?.locked).toBe(true);
+  });
+
   test("prunes abandoned panes while retaining a hidden follow source", () => {
     const layout = sanitizeLayout({
       dockRoot: { kind: "pane", instanceId: "ticker-research:visible" },
@@ -791,6 +828,10 @@ describe("loadConfig", () => {
     expect(config.disabledPlugins).toEqual([
       "ticker-research",
       "market-overview",
+      // Extracted into their own plugins, so a legacy id now means the plugin
+      // of that name rather than the built-in that used to contain it.
+      "market-heatmap",
+      "fear-greed",
       "macro",
       "ibkr",
       "broker",

package/src/data/config/store/normalize.ts

@@ -4,6 +4,7 @@ import type {
   ChartPreferences,
   LayoutConfig,
   OnboardingProgress,
+  LayoutOrigin,
   SavedLayout,
 } from "../../../types/config";
 import {
@@ -179,24 +180,34 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+// Pane state is sanitized on every config write, and most of it is the same
+// objects as last time: the store replaces what changed and keeps the rest.
+// The result depends on nothing but the input, so it is kept per identity.
+const sanitizedValues = new WeakMap<object, unknown>();
+
 function sanitizeSerializableValue(value: unknown): unknown {
   if (value == null) return value;
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return value;
   }
+  if (typeof value !== "object") return undefined;
+  if (sanitizedValues.has(value)) return sanitizedValues.get(value);
+  let sanitized: unknown;
   if (Array.isArray(value)) {
-    return value
+    sanitized = value
       .map((entry) => sanitizeSerializableValue(entry))
       .filter((entry) => entry !== undefined);
-  }
-  if (isPlainRecord(value)) {
-    return Object.fromEntries(
+  } else if (isPlainRecord(value)) {
+    sanitized = Object.fromEntries(
       Object.entries(value)
         .map(([key, entry]) => [key, sanitizeSerializableValue(entry)])
         .filter(([, entry]) => entry !== undefined),
     );
+  } else {
+    sanitized = undefined;
   }
-  return undefined;
+  sanitizedValues.set(value, sanitized);
+  return sanitized;
 }
 
 function sanitizeSavedPaneState(
@@ -294,6 +305,52 @@ function sanitizeBrokerInstances(value: unknown): BrokerInstanceConfig[] {
     }));
 }
 
+function sanitizeLayoutOrigin(value: unknown): LayoutOrigin | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const origin = value as Partial<LayoutOrigin>;
+  if (
+    origin.kind !== "team"
+    || typeof origin.teamId !== "string" || !origin.teamId
+    || typeof origin.layoutId !== "string" || !origin.layoutId
+    || typeof origin.revision !== "number" || !Number.isInteger(origin.revision) || origin.revision < 1
+    || typeof origin.contentHash !== "string"
+    || typeof origin.syncedAt !== "string"
+  ) return undefined;
+  return {
+    kind: "team",
+    teamId: origin.teamId,
+    layoutId: origin.layoutId,
+    revision: origin.revision,
+    contentHash: origin.contentHash,
+    syncedAt: origin.syncedAt,
+  };
+}
+
+// Saved layouts are sanitized on every config write. A layout object that
+// has not been replaced since the last write sanitizes to the same result.
+const sanitizedLayouts = new WeakMap<object, LayoutConfig>();
+const sanitizedPaneStates = new WeakMap<object, { layout: LayoutConfig; result: ReturnType<typeof sanitizeSavedPaneState> }>();
+
+function sanitizeSavedLayoutOnce(value: unknown, fallbackLayout: LayoutConfig): LayoutConfig {
+  // An invalid value sanitizes to a copy of the fallback, which is not a
+  // function of the value alone.
+  if (!isLayoutConfig(value)) return sanitizeLayout(value, fallbackLayout);
+  const cached = sanitizedLayouts.get(value);
+  if (cached) return cached;
+  const layout = sanitizeLayout(value, fallbackLayout);
+  sanitizedLayouts.set(value, layout);
+  return layout;
+}
+
+function sanitizeSavedPaneStateOnce(value: unknown, layout: LayoutConfig): ReturnType<typeof sanitizeSavedPaneState> {
+  if (!value || typeof value !== "object") return sanitizeSavedPaneState(value, layout);
+  const cached = sanitizedPaneStates.get(value);
+  if (cached && cached.layout === layout) return cached.result;
+  const result = sanitizeSavedPaneState(value, layout);
+  sanitizedPaneStates.set(value, { layout, result });
+  return result;
+}
+
 function sanitizeSavedLayouts(
   value: unknown,
   fallbackLayout: LayoutConfig,
@@ -309,9 +366,9 @@ function sanitizeSavedLayouts(
       && typeof (entry as SavedLayout).name === "string",
     )
     .map((entry) => {
-      const layout = sanitizeLayout(entry.layout, fallbackLayout);
+      const layout = sanitizeSavedLayoutOnce(entry.layout, fallbackLayout);
       const placedPaneIds = new Set(getPlacedPaneInstanceIds(layout));
-      const paneState = sanitizeSavedPaneState((entry as { paneState?: unknown }).paneState, layout);
+      const paneState = sanitizeSavedPaneStateOnce((entry as { paneState?: unknown }).paneState, layout);
       return {
         id: typeof entry.id === "string" ? entry.id : undefined,
         name: entry.name,
@@ -323,6 +380,7 @@ function sanitizeSavedLayouts(
         activePanel: entry.activePanel === "right" || entry.activePanel === "left"
           ? entry.activePanel
           : undefined,
+        ...(sanitizeLayoutOrigin(entry.origin) ? { origin: sanitizeLayoutOrigin(entry.origin) } : {}),
       };
     });
 

package/src/data/fred-series.ts

@@ -1,12 +1,13 @@
+import { createPluginCache } from "./plugin-cache";
 import type {
   CloudFredObservationPayload,
   CloudFredSeriesInfoPayload,
 } from "../api-client";
-import type { PluginPersistence } from "../types/plugin";
 
 const CACHE_KIND = "fred-series";
 const CACHE_SOURCE = "gloomberb-cloud";
-const CACHE_SCHEMA_VERSION = 1;
+// Refresh persisted metadata that predates FRED's source coverage dates.
+const CACHE_SCHEMA_VERSION = 2;
 const CACHE_POLICY = {
   staleMs: 24 * 60 * 60 * 1000,
   expireMs: 30 * 24 * 60 * 60 * 1000,
@@ -15,6 +16,9 @@ const CACHE_POLICY = {
 export interface FredSeriesData {
   observations: CloudFredObservationPayload[];
   info: CloudFredSeriesInfoPayload | null;
+  fetchedAt?: string;
+  stale?: boolean;
+  coverage?: { observations: "available"; info: "available" | "unavailable" };
 }
 
 export interface FredSeriesRequest {
@@ -35,18 +39,16 @@ export interface FredSeriesLoadResult extends FredSeriesCacheEntry {
   refreshError?: string;
 }
 
-let persistence: PluginPersistence | null = null;
-const activeFetches = new Map<string, Promise<FredSeriesLoadResult>>();
+const cache = createPluginCache<FredSeriesData>({
+  kind: CACHE_KIND, source: CACHE_SOURCE, schemaVersion: CACHE_SCHEMA_VERSION, policy: CACHE_POLICY,
+});
 const hydratedSeries = new Map<string, FredSeriesCacheEntry>();
+export const attachFredSeriesPersistence = cache.attach;
 
 function seriesKey(seriesId: string): string {
   return seriesId.trim().toUpperCase();
 }
 
-export function attachFredSeriesPersistence(nextPersistence: PluginPersistence): void {
-  persistence = nextPersistence;
-}
-
 /** Hydrates server-fetched data for renderers that cannot call the cloud API directly. */
 export function hydrateFredSeries(entries: readonly (readonly [string, FredSeriesCacheEntry])[]): void {
   hydratedSeries.clear();
@@ -54,8 +56,7 @@ export function hydrateFredSeries(entries: readonly (readonly [string, FredSerie
 }
 
 export function resetFredSeriesPersistence(): void {
-  persistence = null;
-  activeFetches.clear();
+  cache.reset();
   hydratedSeries.clear();
 }
 
@@ -72,72 +73,27 @@ export function getCachedFredSeries(
   request: FredSeriesRequest,
   options?: { allowExpired?: boolean },
 ): FredSeriesCacheEntry | null {
-  const record = persistence?.getResource<FredSeriesData>(CACHE_KIND, cacheKey(request), {
-    sourceKey: CACHE_SOURCE,
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    allowExpired: options?.allowExpired,
-  });
-  if (!record) return null;
+  const entry = cache.get(cacheKey(request), options);
+  return entry ? withFredSourceFreshness(entry) : null;
+}
 
+export function withFredSourceFreshness<T extends FredSeriesCacheEntry>(entry: T): T {
+  const sourceTime = entry.data.fetchedAt ? Date.parse(entry.data.fetchedAt) : NaN;
   return {
-    data: record.value,
-    fetchedAt: record.fetchedAt,
-    stale: !!record.stale,
+    ...entry,
+    fetchedAt: Number.isFinite(sourceTime) ? Math.min(sourceTime, entry.fetchedAt) : entry.fetchedAt,
+    stale: entry.stale || entry.data.stale === true,
   };
 }
 
-function writeCache(key: string, data: FredSeriesData): void {
-  persistence?.setResource(CACHE_KIND, key, data, {
-    sourceKey: CACHE_SOURCE,
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    cachePolicy: CACHE_POLICY,
-  });
-}
-
 export async function loadCachedFredSeries(
   request: FredSeriesRequest,
   loader: () => Promise<FredSeriesData>,
   options?: { force?: boolean },
 ): Promise<FredSeriesLoadResult> {
-  const key = cacheKey(request);
   const cached = getCachedFredSeries(request);
-  if (!options?.force && cached && !cached.stale) {
-    return { ...cached, source: "cache" };
-  }
+  if (!options?.force && cached && !cached.stale) return { ...cached, source: "cache" };
   const hydrated = hydratedSeries.get(seriesKey(request.seriesId));
-  if (!options?.force && hydrated) {
-    return { ...hydrated, source: "cache" };
-  }
-
-  const activeFetch = activeFetches.get(key);
-  if (activeFetch) return activeFetch;
-
-  const fallback = cached ?? getCachedFredSeries(request, { allowExpired: true });
-  const fetchPromise = loader()
-    .then((data) => {
-      writeCache(key, data);
-      return {
-        data,
-        fetchedAt: Date.now(),
-        stale: false,
-        source: "network" as const,
-      };
-    })
-    .catch((error) => {
-      if (fallback) {
-        return {
-          ...fallback,
-          stale: true,
-          source: "stale-fallback" as const,
-          refreshError: error instanceof Error ? error.message : String(error),
-        };
-      }
-      throw error;
-    })
-    .finally(() => {
-      if (activeFetches.get(key) === fetchPromise) activeFetches.delete(key);
-    });
-
-  activeFetches.set(key, fetchPromise);
-  return fetchPromise;
+  if (!options?.force && hydrated) return { ...withFredSourceFreshness(hydrated), source: "cache" };
+  return withFredSourceFreshness(await cache.load(cacheKey(request), loader, options));
 }

package/src/{renderers/browser/persistence.ts → data/json-persistence.ts}

@@ -1,8 +1,8 @@
-import type { AppPersistencePort } from "../../core/app-service-ports";
-import type { PluginStateRecord } from "../../data/plugin-state-store";
-import type { SessionSnapshotRecord } from "../../data/session-store";
-import { DesktopMemoryResourceStore } from "../electrobun/view/resource-store";
-import { BROWSER_STORAGE_KEYS, SafeJsonStorage, type StorageLike } from "./storage";
+import type { AppPersistencePort } from "../core/app-service-ports";
+import type { PluginStateRecord } from "./plugin-state-store";
+import type { SessionSnapshotRecord } from "./session-store";
+import { MemoryResourceStore } from "./memory-resource-store";
+import { BROWSER_STORAGE_KEYS, SafeJsonStorage, type StorageLike } from "./json-storage";
 
 type PluginState = Record<string, Record<string, PluginStateRecord>>;
 type Sessions = Record<string, SessionSnapshotRecord>;
@@ -11,12 +11,12 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-export class BrowserPersistence implements AppPersistencePort {
-  readonly resources = new DesktopMemoryResourceStore();
+export class JsonPersistence implements AppPersistencePort {
+  readonly resources = new MemoryResourceStore();
   private readonly pluginStateData: SafeJsonStorage<PluginState>;
   private readonly sessionData: SafeJsonStorage<Sessions>;
 
-  constructor(storage: StorageLike) {
+  constructor(storage?: StorageLike) {
     this.pluginStateData = new SafeJsonStorage(storage, BROWSER_STORAGE_KEYS.pluginState, {}, (value): value is PluginState => isRecord(value));
     this.sessionData = new SafeJsonStorage(storage, BROWSER_STORAGE_KEYS.session, {}, (value): value is Sessions => isRecord(value));
   }

package/src/{renderers/browser/storage.ts → data/json-storage.ts}

@@ -9,21 +9,21 @@ export class SafeJsonStorage<T> {
   private value: T;
 
   constructor(
-    private readonly storage: StorageLike,
+    private readonly storage: StorageLike | undefined,
     readonly key: string,
     fallback: T,
     validate: (value: unknown) => value is T = (_value): _value is T => true,
   ) {
     this.value = fallback;
     try {
-      const raw = storage.getItem(key);
+      const raw = storage?.getItem(key) ?? null;
       if (raw !== null) {
         const parsed: unknown = JSON.parse(raw);
         if (!validate(parsed)) throw new Error("Invalid stored value");
         this.value = parsed;
       }
     } catch {
-      try { storage.removeItem(key); } catch {}
+      try { storage?.removeItem(key); } catch {}
     }
   }
 
@@ -33,12 +33,12 @@ export class SafeJsonStorage<T> {
 
   set(value: T): void {
     this.value = value;
-    try { this.storage.setItem(this.key, JSON.stringify(value)); } catch {}
+    try { this.storage?.setItem(this.key, JSON.stringify(value)); } catch {}
   }
 
   clear(fallback: T): void {
     this.value = fallback;
-    try { this.storage.removeItem(this.key); } catch {}
+    try { this.storage?.removeItem(this.key); } catch {}
   }
 }
 

package/src/{renderers/browser/ticker-repository.ts → data/json-ticker-repository.ts}

@@ -1,7 +1,7 @@
-import type { AppTickerRepositoryPort } from "../../core/app-service-ports";
-import { hydrateTickerMetadata } from "../../tickers/metadata";
-import type { TickerMetadata, TickerRecord } from "../../types/ticker";
-import { BROWSER_STORAGE_KEYS, SafeJsonStorage, type StorageLike } from "./storage";
+import type { AppTickerRepositoryPort } from "../core/app-service-ports";
+import { hydrateTickerMetadata } from "../tickers/metadata";
+import type { TickerMetadata, TickerRecord } from "../types/ticker";
+import { BROWSER_STORAGE_KEYS, SafeJsonStorage, type StorageLike } from "./json-storage";
 
 type StoredTickers = Record<string, TickerMetadata>;
 
@@ -21,11 +21,11 @@ function hydrate(metadata: TickerMetadata): TickerRecord | null {
   }
 }
 
-export class BrowserTickerRepository implements AppTickerRepositoryPort {
+export class JsonTickerRepository implements AppTickerRepositoryPort {
   private readonly data: SafeJsonStorage<StoredTickers>;
 
-  constructor(storage: StorageLike) {
-    this.data = new SafeJsonStorage(storage, BROWSER_STORAGE_KEYS.tickers, {}, (value): value is StoredTickers => isRecord(value));
+  constructor(storage?: StorageLike, tickers: readonly TickerRecord[] = []) {
+    this.data = new SafeJsonStorage(storage, BROWSER_STORAGE_KEYS.tickers, Object.fromEntries(tickers.map((ticker) => [normalizeSymbol(ticker.metadata.ticker), ticker.metadata])), (value): value is StoredTickers => isRecord(value));
   }
 
   async loadAllTickers(): Promise<TickerRecord[]> {

package/src/data/memory-resource-store.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { MemoryResourceStore } from "./memory-resource-store";
+
+describe("MemoryResourceStore", () => {
+  test("returns expired records only when requested", () => {
+    const store = new MemoryResourceStore();
+    const key = {
+      namespace: "plugins:prediction-markets",
+      kind: "catalog",
+      entityKey: "kalshi:all:all",
+      sourceKey: "remote",
+    };
+
+    store.set(key, ["expired"], {
+      cachePolicy: { staleMs: -2, expireMs: -1 },
+      fetchedAt: Date.now(),
+    });
+
+    expect(store.get(key)).toBeNull();
+    expect(store.get<string[]>(key, { allowExpired: true })?.value).toEqual([
+      "expired",
+    ]);
+  });
+});

package/src/{renderers/electrobun/view/resource-store.ts → data/memory-resource-store.ts}

@@ -4,7 +4,7 @@ import type {
   ListResourceOptions,
   ResourceCacheKey,
   SetResourceOptions,
-} from "../../../data/resource-store";
+} from "./resource-store";
 
 const DEFAULT_RESOURCE_SCHEMA_VERSION = 1;
 
@@ -34,7 +34,7 @@ function isStale(record: CachedResourceRecord): boolean {
   return record.staleAt < Date.now();
 }
 
-export class DesktopMemoryResourceStore {
+export class MemoryResourceStore {
   private readonly records = new Map<string, CachedResourceRecord>();
 
   get<T>(key: ResourceCacheKey, options: GetResourceOptions = {}): CachedResourceRecord<T> | null {

package/src/data/plugin-cache.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { MemoryPluginPersistence } from "../test-support/plugin-persistence";
+import { createPluginCache } from "./plugin-cache";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => { resolve = done; });
+  return { promise, resolve };
+}
+const makeCache = () => createPluginCache<number>({ kind: "test", source: "provider", policy: { staleMs: 60_000, expireMs: 120_000 } });
+
+test("reset prevents pending requests from writing into a newly attached plugin scope", async () => {
+  const oldStore = new MemoryPluginPersistence();
+  const nextStore = new MemoryPluginPersistence();
+  const cache = makeCache();
+  cache.attach(oldStore);
+  const old = deferred<number>();
+  const first = cache.load("key", () => old.promise);
+  await Promise.resolve();
+  cache.reset();
+  cache.attach(nextStore);
+  await cache.load("key", async () => 2);
+  old.resolve(1);
+  expect((await first).data).toBe(1);
+  expect(nextStore.getResource<number>("test", "key", { sourceKey: "provider" })?.value).toBe(2);
+  expect(oldStore.getResource("test", "key", { sourceKey: "provider" })).toBeNull();
+  expect(cache.get("key")?.data).toBe(2);
+});
+
+test("forced replacement cannot be overwritten or cleared by an older request", async () => {
+  const store = new MemoryPluginPersistence();
+  const cache = makeCache();
+  cache.attach(store);
+  const old = deferred<number>();
+  const replacement = deferred<number>();
+  const first = cache.load("key", () => old.promise);
+  const second = cache.load("key", () => replacement.promise, { force: true, replace: true });
+  const third = cache.load("key", async () => { throw new Error("must join replacement"); });
+  replacement.resolve(2);
+  expect((await second).data).toBe(2);
+  expect((await third).data).toBe(2);
+  old.resolve(1);
+  await first;
+  expect(cache.get("key")?.data).toBe(2);
+  expect(store.getResource<number>("test", "key", { sourceKey: "provider" })?.value).toBe(2);
+});

package/src/data/plugin-cache.ts

@@ -0,0 +1,89 @@
+import type { CachePolicy } from "../types/persistence";
+import type { PluginPersistence } from "../types/plugin";
+import { CachedQuery, type CachedValue } from "./cached-query";
+
+export interface PluginCacheResult<T> {
+  data: T;
+  fetchedAt: number;
+  stale: boolean;
+  refreshError?: string;
+  error?: unknown;
+  source: "cache" | "network" | "stale-fallback";
+}
+
+/** Shared persistence/request lifecycle; keys, codecs, validation and policies stay with the plugin. */
+export function createPluginCache<T, Stored = T>(options: {
+  kind: string;
+  source: string;
+  schemaVersion?: number;
+  policy: CachePolicy;
+  encode?: (value: T) => Stored;
+  decode?: (value: Stored) => T;
+}) {
+  let persistence: PluginPersistence | null = null;
+  let generation = 0;
+  const queries = new Map<string, CachedQuery<T>>();
+  const versions = new Map<string, number>();
+  const read = (key: string, allowExpired = false): CachedValue<T> | null => {
+    const record = persistence?.getResource<Stored>(options.kind, key, {
+      sourceKey: options.source, schemaVersion: options.schemaVersion ?? 1, allowExpired,
+    });
+    if (!record) return null;
+    let value: T;
+    try { value = options.decode ? options.decode(record.value) : record.value as unknown as T; }
+    catch { return null; } // A corrupt cache entry must not prevent a fresh load.
+    return {
+      value,
+      fetchedAt: record.fetchedAt,
+      staleAt: record.stale ? Math.min(record.staleAt, Date.now() - 1) : record.staleAt,
+      expiresAt: record.expiresAt,
+      source: options.source,
+    };
+  };
+  const reset = () => {
+    generation += 1;
+    persistence = null;
+    for (const query of queries.values()) query.dispose();
+    queries.clear();
+    versions.clear();
+  };
+  return {
+    attach(next: PluginPersistence) {
+      if (persistence !== next) reset();
+      persistence = next;
+    },
+    reset,
+    get(key: string, { allowExpired = false } = {}): PluginCacheResult<T> | null {
+      const cached = read(key, allowExpired) ?? queries.get(key)?.getSnapshot().result;
+      if (!cached || (!allowExpired && cached.expiresAt <= Date.now())) return null;
+      return { data: cached.value, fetchedAt: cached.fetchedAt, stale: cached.staleAt <= Date.now(), source: "cache" };
+    },
+    async load(key: string, loader: () => Promise<T>, { force = false, replace = false } = {}): Promise<PluginCacheResult<T>> {
+      let query = queries.get(key);
+      if (!query) {
+        query = new CachedQuery({ read: (allowExpired) => read(key, allowExpired) });
+        queries.set(key, query);
+      }
+      const owner = generation;
+      const before = query.getSnapshot().result;
+      const result = await query.load({ force, replace, fetch: async () => {
+        const version = (versions.get(key) ?? 0) + 1;
+        versions.set(key, version);
+        const value = await loader();
+        const fetchedAt = Date.now();
+        if (owner === generation && versions.get(key) === version) {
+          persistence?.setResource(options.kind, key, options.encode ? options.encode(value) : value, {
+            sourceKey: options.source, schemaVersion: options.schemaVersion ?? 1, cachePolicy: options.policy,
+          });
+        }
+        return { value, fetchedAt, staleAt: fetchedAt + options.policy.staleMs, expiresAt: fetchedAt + options.policy.expireMs, source: options.source };
+      } });
+      const error = result.refreshError;
+      return {
+        data: result.value, fetchedAt: result.fetchedAt, stale: !!error || result.staleAt <= Date.now(),
+        source: error ? "stale-fallback" : result === before ? "cache" : "network",
+        ...(error ? { error, refreshError: error instanceof Error ? error.message : String(error) } : {}),
+      };
+    },
+  };
+}

package/src/data/response-sequence.ts

@@ -0,0 +1,6 @@
+let responseSequence = 0;
+
+/** Runtime ordering of accepted source responses, never a source timestamp. */
+export function nextResponseSequence(): number {
+  return ++responseSequence;
+}