gloomberb 0.10.1 → 0.10.2

package/src/sources/provider-router/index.ts

@@ -18,8 +18,8 @@ import { routeSourcePriority } from "../../types/capability-route-source";
 import type { AnalystResearchData, CorporateActionsData, HolderData, OptionsChain, PricePoint, Quote, TickerFinancials } from "../../types/financials";
 import type { NewsArticle, NewsQuery } from "../../news/types";
 import type { BrokerContractRef, InstrumentSearchResult } from "../../types/instrument";
-import type { TimeRange } from "../../components/chart/core/types";
-import type { ChartResolutionSupport, ManualChartResolution } from "../../components/chart/core/resolution";
+import type { TimeRange } from "../../time-series/range";
+import type { ChartResolutionSupport, ManualChartResolution } from "../../time-series/resolution";
 import { debugLog } from "../../utils/debug-log";
 import { ProviderRouterBatchRoutes } from "./batches";
 import { ProviderRouterDocumentRoutes } from "./document-routes";

package/src/sources/provider-router/routing.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { getRouterEntityKey } from "./cache";
+import { makeRouterRequestIdentity } from "./routing";
+
+const deps = { getEntityKey: getRouterEntityKey };
+
+describe("router request identity", () => {
+  test("uses the same canonical variant for cache and revalidation identity", () => {
+    const identity = makeRouterRequestIdentity(deps, {
+      kind: "options-chain",
+      ticker: "aapl",
+      variantParts: [["exchange", "NASDAQ"], ["expiration", 1_800_000_000]],
+    });
+
+    expect(identity).toEqual({
+      kind: "options-chain",
+      entityKey: "AAPL",
+      variantKey: "exchange=NASDAQ;expiration=1800000000",
+      revalidationKey: "options-chain|AAPL|exchange=NASDAQ;expiration=1800000000",
+    });
+  });
+
+  test("does not collapse concurrent exchange variants", () => {
+    const nasdaq = makeRouterRequestIdentity(deps, {
+      kind: "holders",
+      ticker: "shop",
+      variantParts: [["exchange", "NASDAQ"]],
+    });
+    const tsx = makeRouterRequestIdentity(deps, {
+      kind: "holders",
+      ticker: "shop",
+      variantParts: [["exchange", "TSX"]],
+    });
+
+    expect(nasdaq.entityKey).toBe(tsx.entityKey);
+    expect(nasdaq.variantKey).not.toBe(tsx.variantKey);
+    expect(nasdaq.revalidationKey).not.toBe(tsx.revalidationKey);
+  });
+});

package/src/sources/provider-router/routing.ts

@@ -1,19 +1,32 @@
 import type { DataProvider, MarketDataRequestContext } from "../../types/data-provider";
 import { shouldLogProviderError } from "../provider-errors";
 import type { ProviderRouterCoreDeps, SourceResult } from "./route-types";
+import { buildVariantKey } from "./cache";
 
-export function makeRouterRevalidationKey(
+export interface RouterRequestIdentity {
+  kind: string;
+  entityKey: string;
+  variantKey: string;
+  revalidationKey: string;
+}
+
+export function makeRouterRequestIdentity(
   deps: Pick<ProviderRouterCoreDeps, "getEntityKey">,
-  kind: string,
-  ticker: string,
-  context?: MarketDataRequestContext,
-  extra?: string | number,
-): string {
-  return [
-    kind,
-    deps.getEntityKey(ticker, context?.instrument),
-    extra != null ? String(extra) : "",
-  ].join("|");
+  input: {
+    kind: string;
+    ticker: string;
+    context?: MarketDataRequestContext;
+    variantParts?: Array<[string, string | number | undefined | null]>;
+  },
+): RouterRequestIdentity {
+  const entityKey = deps.getEntityKey(input.ticker, input.context?.instrument);
+  const variantKey = buildVariantKey(input.variantParts ?? []);
+  return {
+    kind: input.kind,
+    entityKey,
+    variantKey,
+    revalidationKey: [input.kind, entityKey, variantKey].join("|"),
+  };
 }
 
 export function scheduleRouterRevalidation(

package/src/sources/provider-router/supplemental.ts

@@ -25,7 +25,7 @@ import {
 import type { ProviderRouterCoreDeps, SourceResult } from "./route-types";
 import {
   firstProviderResult,
-  makeRouterRevalidationKey,
+  makeRouterRequestIdentity,
   resolveProviderBySourceKey,
   scheduleRouterRevalidation,
 } from "./routing";
@@ -68,12 +68,17 @@ export class ProviderRouterSupplementalRoutes {
   }
 
   async getHolders(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<HolderData> {
-    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
-    const variantKeys = this.deps.getTickerVariantCandidates(exchange);
-    const cached = selectCachedResource<HolderData>(this.deps.resources, "holders", entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
+    const identity = makeRouterRequestIdentity(this.deps, {
+      kind: "holders",
+      ticker,
+      context,
+      variantParts: [["exchange", canonicalExchange(exchange)]],
+    });
+    const variantKeys = [...new Set([identity.variantKey, ""])];
+    const cached = selectCachedResource<HolderData>(this.deps.resources, identity.kind, identity.entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
     const forceRefresh = context?.cacheMode === "refresh";
     if (cached && !forceRefresh) {
-      scheduleRouterRevalidation(this.revalidationInFlight, makeRouterRevalidationKey(this.deps, "holders", ticker, context), async () => {
+      scheduleRouterRevalidation(this.revalidationInFlight, identity.revalidationKey, async () => {
         await this.revalidateHolders(ticker, exchange, context);
       });
       return cached.value;
@@ -86,12 +91,17 @@ export class ProviderRouterSupplementalRoutes {
   }
 
   async getAnalystResearch(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<AnalystResearchData> {
-    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
-    const variantKeys = this.deps.getTickerVariantCandidates(exchange);
-    const cached = this.selectCachedAnalystResearch(entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
+    const identity = makeRouterRequestIdentity(this.deps, {
+      kind: "analystResearch",
+      ticker,
+      context,
+      variantParts: [["exchange", canonicalExchange(exchange)]],
+    });
+    const variantKeys = [...new Set([identity.variantKey, ""])];
+    const cached = this.selectCachedAnalystResearch(identity.entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
     const forceRefresh = context?.cacheMode === "refresh";
     if (cached && !forceRefresh && !isAnalystResearchMissingRatingTargets(cached.value)) {
-      scheduleRouterRevalidation(this.revalidationInFlight, makeRouterRevalidationKey(this.deps, "analystResearch", ticker, context), async () => {
+      scheduleRouterRevalidation(this.revalidationInFlight, identity.revalidationKey, async () => {
         await this.revalidateAnalystResearch(ticker, exchange, context);
       });
       return cached.value;
@@ -104,12 +114,17 @@ export class ProviderRouterSupplementalRoutes {
   }
 
   async getCorporateActions(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<CorporateActionsData> {
-    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
-    const variantKeys = this.deps.getTickerVariantCandidates(exchange);
-    const cached = selectCachedResource<CorporateActionsData>(this.deps.resources, "corporateActions", entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
+    const identity = makeRouterRequestIdentity(this.deps, {
+      kind: "corporateActions",
+      ticker,
+      context,
+      variantParts: [["exchange", canonicalExchange(exchange)]],
+    });
+    const variantKeys = [...new Set([identity.variantKey, ""])];
+    const cached = selectCachedResource<CorporateActionsData>(this.deps.resources, identity.kind, identity.entityKey, variantKeys, this.deps.getProviderSourceKeys(), false);
     const forceRefresh = context?.cacheMode === "refresh";
     if (cached && !forceRefresh) {
-      scheduleRouterRevalidation(this.revalidationInFlight, makeRouterRevalidationKey(this.deps, "corporateActions", ticker, context), async () => {
+      scheduleRouterRevalidation(this.revalidationInFlight, identity.revalidationKey, async () => {
         await this.revalidateCorporateActions(ticker, exchange, context);
       });
       return cached.value;
@@ -167,9 +182,14 @@ export class ProviderRouterSupplementalRoutes {
   }
 
   async getOptionsChain(ticker: string, exchange?: string, expirationDate?: number, context?: MarketDataRequestContext): Promise<OptionsChain> {
-    const entityKey = this.deps.getEntityKey(ticker, context?.instrument);
+    const identity = makeRouterRequestIdentity(this.deps, {
+      kind: "options-chain",
+      ticker,
+      context,
+      variantParts: [["exchange", canonicalExchange(exchange)], ["expiration", expirationDate ?? "default"]],
+    });
     const variantKeys = [
-      buildVariantKey([["exchange", canonicalExchange(exchange)], ["expiration", expirationDate ?? "default"]]),
+      identity.variantKey,
       buildVariantKey([["expiration", expirationDate ?? "default"]]),
       "",
     ];
@@ -177,9 +197,9 @@ export class ProviderRouterSupplementalRoutes {
       ...this.deps.getBrokerCandidatesForContext(context, false).map((candidate) => this.deps.brokerSourceKey(candidate)),
       ...this.deps.getProviderSourceKeys(),
     ];
-    const cached = selectCachedResource<OptionsChain>(this.deps.resources, "options-chain", entityKey, variantKeys, sourceKeys, false);
+    const cached = selectCachedResource<OptionsChain>(this.deps.resources, identity.kind, identity.entityKey, variantKeys, sourceKeys, false);
     if (cached) {
-      scheduleRouterRevalidation(this.revalidationInFlight, makeRouterRevalidationKey(this.deps, "options-chain", ticker, context, expirationDate ?? "default"), async () => {
+      scheduleRouterRevalidation(this.revalidationInFlight, identity.revalidationKey, async () => {
         await this.revalidateOptionsChain(ticker, exchange, expirationDate, context);
       });
       return cached.value;

package/src/sources/sec-edgar/content.ts

@@ -1,3 +1,5 @@
+import { decodeHtmlEntities } from "../../utils/html-entities";
+
 const MAX_CONTENT_CHARS = 16_000;
 const OWNERSHIP_FORMS = new Set(["3", "3/A", "4", "4/A", "5", "5/A"]);
 
@@ -11,18 +13,6 @@ export function isPdfDocument(body: string, contentType = "", url = ""): boolean
     || /<PDF>/i.test(body);
 }
 
-function decodeHtmlEntities(text: string): string {
-  return text
-    .replace(/&nbsp;/gi, " ")
-    .replace(/&amp;/gi, "&")
-    .replace(/&lt;/gi, "<")
-    .replace(/&gt;/gi, ">")
-    .replace(/&quot;/gi, "\"")
-    .replace(/&#39;|&#x27;/gi, "'")
-    .replace(/&#(\d+);/g, (_match, digits: string) => String.fromCodePoint(Number(digits)))
-    .replace(/&#x([0-9a-f]+);/gi, (_match, hex: string) => String.fromCodePoint(parseInt(hex, 16)));
-}
-
 function collapseDocumentLines(text: string): string[] {
   const rawLines = text
     .replace(/\r/g, "")

package/src/sources/sec-edgar.ts

@@ -1,6 +1,7 @@
 import type { SecFilingDocument, SecFilingItem } from "../types/data-provider";
 import type { FinancialStatement } from "../types/financials";
 import { truncateWithEllipsis } from "../utils/text-wrap";
+import { decodeHtmlEntities } from "../utils/html-entities";
 import {
   PDF_FALLBACK_MESSAGE,
   extractFilingContent,
@@ -161,20 +162,8 @@ function normalizeDocumentName(value: string | undefined): string {
   return (value ?? "").trim().toLowerCase();
 }
 
-function decodeSecHtmlEntities(text: string): string {
-  return text
-    .replace(/ /gi, " ")
-    .replace(/&/gi, "&")
-    .replace(/&lt;/gi, "<")
-    .replace(/&gt;/gi, ">")
-    .replace(/&quot;/gi, "\"")
-    .replace(/&#39;|&#x27;/gi, "'")
-    .replace(/&#(\d+);/g, (_match, digits: string) => String.fromCodePoint(Number(digits)))
-    .replace(/&#x([0-9a-f]+);/gi, (_match, hex: string) => String.fromCodePoint(parseInt(hex, 16)));
-}
-
 function cleanSecTableText(value: string): string {
-  return decodeSecHtmlEntities(
+  return decodeHtmlEntities(
     value
       .replace(/<script[\s\S]*?<\/script>/gi, " ")
       .replace(/<style[\s\S]*?<\/style>/gi, " ")

package/src/sources/yahoo-finance/history.ts

@@ -1,9 +1,9 @@
-import type { TimeRange } from "../../components/chart/core/types";
+import type { TimeRange } from "../../time-series/range";
 import {
   normalizeChartResolutionSupport,
   type ChartResolutionSupport,
   type ManualChartResolution,
-} from "../../components/chart/core/resolution";
+} from "../../time-series/resolution";
 import type { PricePoint } from "../../types/financials";
 import { normalizeSubUnitCurrency } from "./mappers";
 import { getYahooSymbolsToTry } from "./symbols";

package/src/sources/yahoo-finance/options.ts

@@ -105,6 +105,11 @@ export async function loadYahooOptionsChainResult({
           expirationDates: result.expirationDates ?? [],
           calls: (opts?.calls ?? []).map((contract) => mapYahooOptionContract(contract)),
           puts: (opts?.puts ?? []).map((contract) => mapYahooOptionContract(contract)),
+          dataSource: "delayed",
+          feed: "yahoo",
+          delayMinutes: 15,
+          realtimeEligible: false,
+          asOf: new Date().toISOString(),
         },
         underlyingMarketState: normalizeYahooMarketState(result.quote?.marketState),
       };

package/src/sources/yahoo-finance.ts

@@ -1,10 +1,10 @@
 import type { Quote, PricePoint, TickerFinancials, OptionsChain, CompanyProfile, HolderData, AnalystResearchData, CorporateActionsData } from "../types/financials";
 import type { DataProvider, EarningsEvent, MarketDataRequestContext, NewsItem, SecFilingItem } from "../types/data-provider";
-import type { TimeRange } from "../components/chart/core/types";
+import type { TimeRange } from "../time-series/range";
 import {
   type ChartResolutionSupport,
   type ManualChartResolution,
-} from "../components/chart/core/resolution";
+} from "../time-series/resolution";
 import type { InstrumentSearchResult } from "../types/instrument";
 import { parseOptionSymbol } from "../utils/options";
 import { SecEdgarClient } from "./sec-edgar";

package/src/state/app/bootstrap.ts

@@ -1,5 +1,5 @@
 import type { Dispatch } from "react";
-import type { TickerRepository } from "../../data/ticker-repository";
+import type { AppTickerRepositoryPort } from "../../core/app-service-ports";
 import { findPaneInstance, isTickerPaneId, type AppConfig } from "../../types/config";
 import type { CachedFinancialsTarget, DataProvider } from "../../types/data-provider";
 import type { TickerFinancials } from "../../types/financials";
@@ -47,7 +47,7 @@ const startupLog = debugLog.createLogger("startup");
 
 export interface InitializeAppStateArgs {
   config: AppConfig;
-  tickerRepository: TickerRepository;
+  tickerRepository: AppTickerRepositoryPort;
   dataProvider: DataProvider;
   sessionSnapshot?: AppSessionSnapshot | null;
   dispatch: Dispatch<AppAction>;

package/src/state/app/context/index.tsx

@@ -12,7 +12,7 @@ import {
   type SetStateAction,
   type ReactNode,
 } from "react";
-import type { SessionStore } from "../../../data/session-store";
+import type { AppSessionStorePort } from "../../../core/app-service-ports";
 import { ThemeProvider } from "../../../theme/theme-context";
 import {
   findPaneInstance,
@@ -333,7 +333,7 @@ export function AppProvider({
 }: {
   config: AppConfig;
   children: ReactNode;
-  sessionStore?: SessionStore;
+  sessionStore?: AppSessionStorePort;
   sessionSnapshot?: AppSessionSnapshot | null;
   desktopBridge?: DesktopWindowBridge;
   desktopSnapshot?: DesktopSharedStateSnapshot | null;

package/src/state/hooks/quote-streaming.ts

@@ -1,9 +1,14 @@
-import { useEffect } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useAppActive } from "../app/activity";
 import type { QuoteSubscriptionTarget } from "../../types/data-provider";
+import type { Quote } from "../../types/financials";
 import { debugLog } from "../../utils/debug-log";
 import { normalizeSymbol } from "../../utils/exchanges";
 import { getSharedMarketDataCoordinator } from "../../market-data/coordinator";
+import { useQuoteEntries } from "../../market-data/hooks";
+import type { InstrumentRef } from "../../market-data/request-types";
+import type { QueryEntry } from "../../market-data/result-types";
+import { buildQuoteKey } from "../../market-data/selectors";
 
 const quoteStreamLog = debugLog.createLogger("quote-stream");
 
@@ -91,3 +96,63 @@ export function useQuoteStreaming(targets: QuoteSubscriptionTarget[]): void {
     };
   }, [appActive, coordinator, subscriptionKey]);
 }
+
+/**
+ * Subscribe to a bounded target set and observe the coordinator entries filled
+ * by that stream. This intentionally avoids per-symbol HTTP quote loads.
+ */
+export function useLiveQuoteEntries(targets: QuoteSubscriptionTarget[]): {
+  entries: Map<string, QueryEntry<Quote>>;
+  freshnessNow: number;
+  subscriptionStartedAt: number;
+} {
+  const appActive = useAppActive();
+  const normalizedTargets = targets.flatMap((target) => {
+    const normalized = normalizeQuoteStreamSubscriptionTarget(target);
+    return normalized ? [normalized] : [];
+  });
+  const targetKey = normalizedTargets
+    .map((target) => buildQuoteStreamSubscriptionKey(target))
+    .sort()
+    .join("\u001f");
+  const subscriptionKey = `${appActive ? "active" : "inactive"}\u001f${targetKey}`;
+  const subscriptionRef = useRef({
+    key: subscriptionKey,
+    startedAt: Date.now(),
+  });
+  if (subscriptionRef.current.key !== subscriptionKey) {
+    subscriptionRef.current = {
+      key: subscriptionKey,
+      startedAt: Date.now(),
+    };
+  }
+  const [freshnessNow, setFreshnessNow] = useState(() => Date.now());
+  const instruments = useMemo(() => {
+    const unique = new Map<string, InstrumentRef>();
+    for (const target of normalizedTargets) {
+      const instrument: InstrumentRef = {
+        symbol: target.symbol,
+        exchange: target.exchange,
+        brokerId: target.context?.brokerId,
+        brokerInstanceId: target.context?.brokerInstanceId,
+        instrument: target.context?.instrument ?? null,
+      };
+      unique.set(buildQuoteKey(instrument), instrument);
+    }
+    return [...unique.values()];
+  }, [targetKey]);
+
+  useEffect(() => {
+    setFreshnessNow(Date.now());
+    if (!appActive || normalizedTargets.length === 0) return;
+    const interval = setInterval(() => setFreshnessNow(Date.now()), 15_000);
+    return () => clearInterval(interval);
+  }, [appActive, targetKey]);
+
+  useQuoteStreaming(targets);
+  return {
+    entries: useQuoteEntries(instruments),
+    freshnessNow,
+    subscriptionStartedAt: subscriptionRef.current.startedAt,
+  };
+}

package/src/state/hooks/session-snapshot.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import type { SessionStore } from "../../data/session-store";
+import type { AppSessionStorePort } from "../../core/app-service-ports";
 import {
   buildAppSessionSnapshot,
   type AppSessionSnapshot,
@@ -12,7 +12,7 @@ import {
 } from "../persist-scheduler";
 
 export function usePersistSessionSnapshot(
-  sessionStore: SessionStore | undefined,
+  sessionStore: AppSessionStorePort | undefined,
   state: AppState,
   sessionId: string,
   schemaVersion: number,

package/src/state/selectors.ts

@@ -1,5 +1,4 @@
 import type { AppState } from "./app/context";
-import type { TickerRecord } from "../types/ticker";
 
 function getCollectionMembershipKey(state: AppState, collectionId: string | null): "portfolios" | "watchlists" | null {
   if (!collectionId) return null;
@@ -8,14 +7,6 @@ function getCollectionMembershipKey(state: AppState, collectionId: string | null
   return null;
 }
 
-export function getCollectionTickers(state: AppState, collectionId: string | null): TickerRecord[] {
-  const membershipKey = getCollectionMembershipKey(state, collectionId);
-  if (!collectionId || !membershipKey) return [];
-  return [...state.tickers.values()]
-    .filter((ticker) => ticker.metadata[membershipKey].includes(collectionId))
-    .sort((a, b) => a.metadata.ticker.localeCompare(b.metadata.ticker));
-}
-
 export function getCollectionTickerCount(state: AppState, collectionId: string | null): number {
   const membershipKey = getCollectionMembershipKey(state, collectionId);
   if (!collectionId || !membershipKey) return 0;

package/src/sync/controller.test.ts

@@ -46,6 +46,104 @@ test("does not push local state when the initial pull fails", async () => {
   expect(controller.getStatus()).toMatchObject({ phase: "error", error: "pull failed" });
 });
 
+test("rejects incompatible snapshot versions before applying or pushing", async () => {
+  let applied = 0;
+  let pushes = 0;
+  const contributor: SyncContributor = {
+    id: "test.settings",
+    schemaVersion: 2,
+    collect: () => ({ local: true }),
+    apply: () => {
+      applied += 1;
+    },
+  };
+  const snapshot = {
+    schemaVersion: SYNC_SNAPSHOT_SCHEMA_VERSION + 1,
+    appId: "gloomberb",
+    clientId: "future-client",
+    createdAt: "2026-07-26T00:00:00.000Z",
+    contributors: {},
+  } as unknown as SyncSnapshot;
+  const transport: SyncTransport = {
+    id: "future-snapshot",
+    isAvailable: () => true,
+    pullSnapshot: async () => ({ snapshot, revision: 1, updatedAt: snapshot.createdAt }),
+    pushSnapshot: async () => {
+      pushes += 1;
+      return { revision: 2, updatedAt: snapshot.createdAt };
+    },
+  };
+  const controller = new CloudSyncController();
+  controller.setRuntime({
+    getState: () => ({} as AppState),
+    dispatch: () => {},
+    tickerRepository: {} as TickerRepository,
+    getContributors: () => [{ pluginId: "test", contributor }],
+    getTransport: () => ({ pluginId: "test", transport }),
+  });
+
+  await controller.requestSync({ force: true });
+
+  expect(applied).toBe(0);
+  expect(pushes).toBe(0);
+  expect(controller.getStatus()).toMatchObject({
+    phase: "error",
+    error: `Unsupported sync snapshot schema version ${SYNC_SNAPSHOT_SCHEMA_VERSION + 1}; expected ${SYNC_SNAPSHOT_SCHEMA_VERSION}`,
+  });
+});
+
+test("rejects incompatible contributor versions before applying or pushing", async () => {
+  let applied = 0;
+  let pushes = 0;
+  const contributor: SyncContributor = {
+    id: "test.settings",
+    schemaVersion: 2,
+    collect: () => ({ local: true }),
+    apply: () => {
+      applied += 1;
+    },
+  };
+  const snapshot: SyncSnapshot = {
+    schemaVersion: SYNC_SNAPSHOT_SCHEMA_VERSION,
+    appId: "gloomberb",
+    clientId: "old-client",
+    createdAt: "2026-07-26T00:00:00.000Z",
+    contributors: {
+      "test.settings": {
+        schemaVersion: 1,
+        updatedAt: "2026-07-26T00:00:00.000Z",
+        payload: { remote: true },
+      },
+    },
+  };
+  const transport: SyncTransport = {
+    id: "old-contributor",
+    isAvailable: () => true,
+    pullSnapshot: async () => ({ snapshot, revision: 1, updatedAt: snapshot.createdAt }),
+    pushSnapshot: async () => {
+      pushes += 1;
+      return { revision: 2, updatedAt: snapshot.createdAt };
+    },
+  };
+  const controller = new CloudSyncController();
+  controller.setRuntime({
+    getState: () => ({} as AppState),
+    dispatch: () => {},
+    tickerRepository: {} as TickerRepository,
+    getContributors: () => [{ pluginId: "test", contributor }],
+    getTransport: () => ({ pluginId: "test", transport }),
+  });
+
+  await controller.requestSync({ force: true });
+
+  expect(applied).toBe(0);
+  expect(pushes).toBe(0);
+  expect(controller.getStatus()).toMatchObject({
+    phase: "error",
+    error: "Unsupported sync contributor schema for test.settings: 1; expected 2",
+  });
+});
+
 test("keeps startup layout changes while serializing pull and push", async () => {
   let state = createInitialState(createDefaultConfig("/tmp/gloomberb-sync-controller-test"));
   const dispatch = (action: AppAction) => {

package/src/sync/controller.ts

@@ -1,6 +1,6 @@
 import type { Dispatch } from "react";
 import type { AppAction, AppState } from "../core/state/app/state";
-import type { TickerRepository } from "../data/ticker-repository";
+import type { AppTickerRepositoryPort } from "../core/app-service-ports";
 import { stableStringify } from "../remote/revision";
 import {
   SYNC_SNAPSHOT_SCHEMA_VERSION,
@@ -25,7 +25,7 @@ export interface CloudSyncStatus {
 interface SyncRuntime {
   getState: () => AppState;
   dispatch: Dispatch<AppAction>;
-  tickerRepository: TickerRepository;
+  tickerRepository: AppTickerRepositoryPort;
   getContributors: () => RegisteredSyncContributor[];
   getTransport: () => RegisteredSyncTransport | null;
 }
@@ -223,11 +223,12 @@ export class CloudSyncController {
       if (!this.isCurrent(runtime, transport)) return false;
 
       if (response.snapshot) {
+        this.assertSnapshotCompatible(response.snapshot, runtime.getContributors());
         for (const entry of runtime.getContributors()) {
           if (!this.isCurrent(runtime, transport)) return false;
-          const payload = response.snapshot.contributors[entry.contributor.id]?.payload;
-          if (payload === undefined || !entry.contributor.apply) continue;
-          await entry.contributor.apply(payload, {
+          const contributorPayload = response.snapshot.contributors[entry.contributor.id];
+          if (!contributorPayload || !entry.contributor.apply) continue;
+          await entry.contributor.apply(contributorPayload.payload, {
             snapshot: response.snapshot,
             baselineState,
             state: runtime.getState(),
@@ -260,6 +261,29 @@ export class CloudSyncController {
     }
   }
 
+  private assertSnapshotCompatible(
+    snapshot: SyncSnapshot,
+    contributors: RegisteredSyncContributor[],
+  ): void {
+    if (snapshot.appId !== "gloomberb") {
+      throw new Error(`Unsupported sync snapshot app: ${String(snapshot.appId)}`);
+    }
+    if (snapshot.schemaVersion !== SYNC_SNAPSHOT_SCHEMA_VERSION) {
+      throw new Error(
+        `Unsupported sync snapshot schema version ${String(snapshot.schemaVersion)}; expected ${SYNC_SNAPSHOT_SCHEMA_VERSION}`,
+      );
+    }
+    for (const entry of contributors) {
+      const payload = snapshot.contributors[entry.contributor.id];
+      if (!payload || !entry.contributor.apply) continue;
+      if (payload.schemaVersion !== entry.contributor.schemaVersion) {
+        throw new Error(
+          `Unsupported sync contributor schema for ${entry.contributor.id}: ${payload.schemaVersion}; expected ${entry.contributor.schemaVersion}`,
+        );
+      }
+    }
+  }
+
   private async assembleSnapshot(runtime: SyncRuntime): Promise<SyncSnapshot> {
     const contributors = runtime.getContributors();
     const createdAt = nowIso();

package/src/sync/react.ts

@@ -1,6 +1,6 @@
 import { useEffect, useSyncExternalStore, type Dispatch } from "react";
 import type { AppAction, AppState } from "../core/state/app/state";
-import type { TickerRepository } from "../data/ticker-repository";
+import type { AppTickerRepositoryPort } from "../core/app-service-ports";
 import type { PluginRegistry } from "../plugins/registry";
 import { cloudSyncController } from "./controller";
 
@@ -8,7 +8,7 @@ interface CloudSyncRuntimeOptions {
   state: AppState;
   getState: () => AppState;
   dispatch: Dispatch<AppAction>;
-  tickerRepository: TickerRepository;
+  tickerRepository: AppTickerRepositoryPort;
   pluginRegistry: PluginRegistry;
   initialized: boolean;
 }

package/src/sync/types.ts

@@ -1,6 +1,6 @@
 import type { Dispatch } from "react";
 import type { AppAction, AppState } from "../core/state/app/state";
-import type { TickerRepository } from "../data/ticker-repository";
+import type { AppTickerRepositoryPort } from "../core/app-service-ports";
 
 export const SYNC_SNAPSHOT_SCHEMA_VERSION = 1;
 
@@ -30,7 +30,7 @@ export interface SyncApplyContext {
   getState: () => AppState;
   isCurrent: () => boolean;
   dispatch: Dispatch<AppAction>;
-  tickerRepository: TickerRepository;
+  tickerRepository: AppTickerRepositoryPort;
 }
 
 export interface SyncContributor {