gloomberb 0.13.2 → 0.14.0

package/src/types/plugin.ts

@@ -47,7 +47,7 @@ import type { DataProvider } from "./data-provider";
 import type { TickerFinancials } from "./financials";
 import type { CachePolicy, PersistedResourceValue } from "./persistence";
 import type { TickerRecord } from "./ticker";
-import type { InstrumentSearchResult } from "./instrument";
+import type { BrokerContractRef, InstrumentSearchResult, TickerListingRef } from "./instrument";
 import type { SyncContributor, SyncTransport } from "../sync/types";
 
 export interface GloomSlots {
@@ -81,6 +81,12 @@ export interface PanePortableShareDef {
     settings?: PaneSharePrivateFields;
     state?: PaneSharePrivateFields;
   };
+  /**
+   * Rewrites the instance before it leaves the device. The receiver has none
+   * of the sender's local ticker records, so anything resolved through them
+   * (a listing's venue, for example) must be pinned into the instance here.
+   */
+  prepare?(pane: PaneInstanceConfig, context: { tickers: ReadonlyMap<string, TickerRecord> }): PaneInstanceConfig;
 }
 
 export interface PaneDef {
@@ -207,6 +213,8 @@ export interface PaneTemplateContext {
   layout: LayoutConfig;
   focusedPaneId: string | null;
   activeTicker: string | null;
+  activeInstrument?: BrokerContractRef | null;
+  activeListing?: TickerListingRef;
   activeCollectionId: string | null;
 }
 
@@ -224,6 +232,8 @@ export interface PaneTemplateCreateOptions {
   symbols?: string[] | null;
   ticker?: TickerRecord | null;
   searchResult?: InstrumentSearchResult | null;
+  instrument?: BrokerContractRef | null;
+  listing?: TickerListingRef;
   /** Template-owned, validated data restored from a public pane share. */
   shareData?: unknown;
 }
@@ -382,6 +392,13 @@ interface CliLaunchEnvironment {
   terminalHeight: number;
 }
 
+/**
+ * The resume state the app writes at exit and reads at startup. A plugin whose
+ * CLI command launches the UI seeds it so the pane opens on what was asked for
+ * rather than on what the last session left behind.
+ */
+export type { AppSessionSnapshot } from "../core/state/session-persistence";
+
 export interface CliLaunchConfigResult<TLaunchState = unknown> {
   config: AppConfig;
   launchState?: TLaunchState;
@@ -555,6 +572,31 @@ export interface PluginConfigState {
   keys(): string[];
 }
 
+export interface PluginTeamStateEntry<T> {
+  value: T;
+  revision: number;
+  updatedBy: string;
+  updatedAt: string;
+}
+
+/**
+ * Plugin-owned data shared with a team, keyed per plugin. Writes take the
+ * revision they expect and fail when a teammate wrote first, so nothing is
+ * overwritten silently. Scoped to the active team unless a teamId is given.
+ */
+export interface PluginTeamState {
+  activeTeamId(): string | null;
+  get<T>(key: string, options?: { teamId?: string }): Promise<PluginTeamStateEntry<T> | null>;
+  list<T>(options?: { teamId?: string }): Promise<Array<PluginTeamStateEntry<T> & { key: string }>>;
+  set<T>(key: string, value: T, options?: { teamId?: string; expectRevision?: number }): Promise<{ revision: number }>;
+  delete(key: string, options?: { teamId?: string }): Promise<void>;
+  subscribe<T>(
+    key: string,
+    listener: (entry: PluginTeamStateEntry<T> | null) => void,
+    options?: { teamId?: string },
+  ): () => void;
+}
+
 export interface PluginPaneSettingsState {
   get<T = unknown>(paneId: string, key: string): T | null;
   set(paneId: string, key: string, value: unknown): Promise<void>;
@@ -602,11 +644,17 @@ export interface PinTickerOptions {
   floating?: boolean;
   paneType?: string;
   forceNewPane?: boolean;
+  /** Preserve a contract explicitly selected from instrument search. */
+  instrument?: BrokerContractRef | null;
+  listing?: TickerListingRef;
+  /** Select this research tab once the requested ticker has resolved. */
+  tabId?: string;
 }
 
 export interface GloomPluginContext {
   registerPane(pane: PaneDef): void;
-  registerPaneTemplate(template: PaneTemplateDef): void;
+  /** Returns a disposer; templates added after setup (team views) use it. */
+  registerPaneTemplate(template: PaneTemplateDef): () => void;
   registerCommand(command: CommandDef): void;
   registerCommandBarSearchProvider(provider: CommandBarSearchProvider): () => void;
   registerColumn(column: CustomColumnDef): void;
@@ -636,6 +684,7 @@ export interface GloomPluginContext {
   readonly resume: PluginResumeState;
   readonly configState: PluginConfigState;
   readonly paneSettings: PluginPaneSettingsState;
+  readonly teamState: PluginTeamState;
 
   createBrokerInstance(brokerType: string, label: string, values: Record<string, unknown>): Promise<BrokerInstanceConfig>;
   updateBrokerInstance(instanceId: string, values: Record<string, unknown>, options?: BrokerInstanceUpdateOptions): Promise<void>;
@@ -653,6 +702,8 @@ export interface GloomPluginContext {
   pinTicker(symbol: string, options?: PinTickerOptions): void;
   navigateTicker(symbol: string, options?: { sourcePaneId?: string | null }): void;
   openPaneSettings(paneId?: string): void;
+  /** Copies a live share link for a pane instance (the focused pane when omitted). */
+  sharePane(paneId?: string): void;
 
   on<K extends keyof PluginEvents>(event: K, handler: (payload: PluginEvents[K]) => void): () => void;
   emit<K extends keyof PluginEvents>(event: K, payload: PluginEvents[K]): void;
@@ -675,8 +726,34 @@ export type PluginTarget = "cli" | "tui" | "desktop" | "web";
 
 export const ALL_PLUGIN_TARGETS: readonly PluginTarget[] = ["cli", "tui", "desktop", "web"];
 
+/**
+ * One setting a plugin needs from the user before it is useful, such as an API
+ * key. Values are stored in the plugin's `configState` under `key`.
+ */
+export interface PluginConfigField {
+  key: string;
+  label: string;
+  type?: "text" | "password" | "number" | "select";
+  /** Shown under the field. Say where to get the value, not what the plugin does. */
+  description?: string;
+  placeholder?: string;
+  defaultValue?: string;
+  /** The plugin counts as "needs setup" while a required field is empty. Default true. */
+  required?: boolean;
+  options?: Array<{ label: string; value: string }>;
+}
+
 export interface GloomPlugin {
   id: string;
+  /**
+   * Where this plugin's saved state lives: its `pluginConfig` entry, its resume
+   * state, and the per-pane state its panes write. Defaults to `id`.
+   *
+   * Set it when a plugin is renamed, or moves out of this repository under a
+   * new id, so the threads, tabs, and defaults a user already has stay theirs.
+   * Everything else (the toggle, the marketplace, seeding) keys off `id`.
+   */
+  stateId?: string;
   name: string;
   version: string;
   description?: string;
@@ -685,8 +762,37 @@ export interface GloomPlugin {
   cliCommands?: CliCommandDef[];
   /** Defaults to every target when omitted. */
   targets?: readonly PluginTarget[];
+  /**
+   * Third-party hosts the plugin fetches from, as bare domains
+   * (`"api.example.com"`; a parent domain also covers its subdomains).
+   *
+   * Terminal and desktop reach anything, so this is informational there and
+   * is what the plugin directory shows under "Network access". On the web the
+   * browser cannot call a host that sends no CORS headers, so the hosted app
+   * proxies exactly the hosts the bundled plugins declare here and refuses
+   * the rest. A plugin that leaves a host out works on the desktop and fails
+   * on the web.
+   *
+   * Hosts reached on the plugin's behalf count too: `YahooHttpClient` collects
+   * a cookie from `fc.yahoo.com` before any screener call, so a plugin using it
+   * declares that host even though its own code never names it.
+   */
+  hosts?: readonly string[];
   /** Shown in the marketplace pane and on the website. */
   homepage?: string;
+  /**
+   * Settings the plugin cannot work without. Declaring them gives the plugin a
+   * "Set up <name>" command, a form the marketplace opens from its `s` key, and
+   * a `needs setup` status until every required field has a value. Read the
+   * values back with `ctx.configState.get(key)`.
+   */
+  configSchema?: PluginConfigField[];
+  /**
+   * Overrides the default readiness rule (every required `configSchema` field
+   * has a value) for plugins whose setup is not a plain form, such as a broker
+   * login or a file that must exist.
+   */
+  isConfigured?(values: Record<string, unknown>): boolean;
 
   setup?(ctx: GloomPluginContext): void | Promise<void>;
   dispose?(): void;

package/src/types/ticker.ts

@@ -1,9 +1,11 @@
-import type { BrokerContractRef } from "./instrument";
+import type { BrokerContractRef, PriceBasis } from "./instrument";
 
 export interface TickerPosition {
   portfolio: string;
   shares: number;
-  avgCost: number;
+  /** Absent when the source did not provide a finite cost; explicit zero is retained. */
+  avgCost?: number;
+  priceBasis?: PriceBasis;
   currency?: string;
   dateAcquired?: string;
   broker: string; // "manual" | future broker plugin IDs
@@ -17,6 +19,8 @@ export interface TickerPosition {
   brokerInstanceId?: string;
   brokerAccountId?: string;
   brokerContractId?: number;
+  /** Source-declared fallback contract identity when no canonical conId was supplied. */
+  brokerContractIdentity?: string;
 }
 
 export interface TickerMetadata {
@@ -50,10 +54,14 @@ export interface Portfolio {
   brokerInstanceId?: string;
   brokerAccountId?: string;
   lastSyncedAt?: number;
+  /** Set on paper portfolios shared with a team; the server holds the items. */
+  teamId?: string;
 }
 
 export interface Watchlist {
   id: string;
   name: string;
   description?: string;
+  /** Set on watchlists shared with a team; the server holds the items. */
+  teamId?: string;
 }

package/src/ui/context-menu.test.ts

@@ -55,7 +55,8 @@ describe("context menu item builders", () => {
 
   test("ticker menu includes plugin ticker actions and hides remove actions without memberships", () => {
     const registry = {
-      tickerActions: new Map([
+      getEnabledTickerActions() { return [...this.tickerActions.values()]; },
+    tickerActions: new Map([
         ["alert", {
           id: "alert",
           label: "Set Alert",

package/src/ui/context-menu.tsx

@@ -1,9 +1,7 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, type ReactNode } from "react";
 import { t, tf } from "../i18n";
 import { getSharedRegistry, type PluginRegistry } from "../plugins/registry";
-import type { TickerFinancials } from "../types/financials";
 import { TICKER_RESEARCH_PANE_ID } from "../types/config";
-import type { TickerRecord } from "../types/ticker";
 import {
   contextMenuDivider,
   hasRunnableContextMenuItem,
@@ -11,6 +9,8 @@ import {
   type ContextMenuDividerItem,
   type ContextMenuItem,
 } from "../types/context-menu";
+import type { TickerFinancials } from "../types/financials";
+import type { TickerRecord } from "../types/ticker";
 import { useRendererHost, useUiCapabilities } from "./host";
 
 interface ContextMenuEventLike {
@@ -269,7 +269,7 @@ export function tickerContextMenuItems({
   }
 
   const tickerActions = registry
-    ? [...registry.tickerActions.values()].filter((action) => !action.filter || action.filter(ticker))
+    ? registry.getEnabledTickerActions().filter((action) => !action.filter || action.filter(ticker))
     : [];
   if (tickerActions.length > 0) {
     items.push(contextMenuDivider("ticker:actions-divider"));

package/src/ui/host.tsx

@@ -1,7 +1,6 @@
 import { createContext, useContext, type ComponentType, type ReactNode, type Ref } from "react";
 import type { ContextMenuItem } from "../types/context-menu";
 import type { AppNotificationRequest } from "../types/plugin";
-import type { LiveStreamResolveRequest, ResolvedLiveStream } from "../types/media";
 import { formatCommandBarShortcut, getShortcutDisplayMode } from "../utils/shortcut-labels";
 import type { AsciiFontName } from "./ascii-font";
 
@@ -262,6 +261,12 @@ interface SpinnerMarkProps extends BoxProps {
 export interface AsciiTextProps extends BoxProps {
   text: string;
   font?: AsciiFontName;
+  /**
+   * Multiplier on the glyph cell. When set, DOM hosts paint the block glyphs
+   * themselves at that size instead of relying on a font that has them, so
+   * the art looks the same on every platform. Terminals ignore it.
+   */
+  scale?: number;
   color?: string;
   fg?: string;
   bg?: string;
@@ -401,7 +406,6 @@ export interface RendererHost {
   playTerminalMedia?(url: string, title?: string, options?: { muted?: boolean }): Promise<void>;
   /** Stop terminal playback started by `playTerminalMedia`. */
   stopTerminalMedia?(): void;
-  resolveLiveStream?(request: LiveStreamResolveRequest): Promise<ResolvedLiveStream>;
 }
 
 interface UiHostContextValue {

package/src/ui/index.tsx

@@ -85,14 +85,13 @@ export const Text = forwardRef<any, ComponentProps<UiHost["Text"]>>((props, ref)
   const { Text: HostText } = useUiHost();
   const rawProps = props as Record<string, unknown>;
   const onMouseDown = rawProps.onMouseDown as ((event?: unknown) => unknown) | undefined;
-  const label = remotePropLabel(rawProps)
-    ?? (typeof rawProps.children === "string" ? rawProps.children : undefined)
-    ?? (typeof rawProps.content === "string" ? rawProps.content : undefined);
   const remoteNodeId = useRemoteUiNode(
     onMouseDown
       ? {
         role: remotePropRole(rawProps, "text"),
-        label,
+        label: remotePropLabel(rawProps)
+          ?? (typeof rawProps.children === "string" ? rawProps.children : undefined)
+          ?? (typeof rawProps.content === "string" ? rawProps.content : undefined),
         actions: {
           press: (input) => onMouseDown(remoteEvent(input)),
         },

package/src/updater.test.ts

@@ -25,7 +25,7 @@ afterEach(() => {
 
 function expectedAssetName(compressed = false): string {
   const os = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "windows" : "linux";
-  const arch = os === "darwin" || process.arch === "arm64" ? "arm64" : "x64";
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
   const extension = os === "windows" ? ".exe" : "";
   return compressed ? `gloomberb-${os}-${arch}${extension}.gz` : `gloomberb-${os}-${arch}${extension}`;
 }
@@ -37,6 +37,22 @@ describe("getAssetBaseNameForRuntime", () => {
       arch: "x64",
     })).toBe("gloomberb-windows-x64.exe");
   });
+
+  test("keeps macOS arm64 runtimes on the arm64 asset", () => {
+    expect(getAssetBaseNameForRuntime({
+      platform: "darwin",
+      arch: "arm64",
+    })).toBe("gloomberb-darwin-arm64");
+  });
+
+  // An arm64 asset cannot run on an x64 macOS runtime, so it must never be
+  // offered as that runtime's update.
+  test("asks for an x64 asset on an x64 macOS runtime", () => {
+    expect(getAssetBaseNameForRuntime({
+      platform: "darwin",
+      arch: "x64",
+    })).toBe("gloomberb-darwin-x64");
+  });
 });
 
 describe("detectUpdateAction", () => {

package/src/updater.ts

@@ -62,8 +62,10 @@ export function getAssetBaseNameForRuntime(
     : runtimeProcess?.platform === "win32"
       ? "windows"
       : "linux";
-  // macOS x64 uses arm64 binary (runs via Rosetta 2)
-  const arch = os === "darwin" || runtimeProcess?.arch === "arm64" ? "arm64" : "x64";
+  // Always update to the architecture the current runtime actually is. macOS
+  // only publishes arm64 today, so an x64 macOS runtime resolves no asset and
+  // reports that instead of overwriting itself with an unrunnable binary.
+  const arch = runtimeProcess?.arch === "arm64" ? "arm64" : "x64";
   const extension = os === "windows" ? ".exe" : "";
   return `gloomberb-${os}-${arch}${extension}`;
 }

package/src/utils/dom-screenshot.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { renderedTextFragments } from "./dom-screenshot";
+
+function measuredLines(lines: { text: string; left: number; top: number }[]) {
+  const value = lines.map((line) => line.text).join("");
+  const boundaries: { start: number; end: number; left: number; top: number }[] = [];
+  let offset = 0;
+  for (const line of lines) {
+    boundaries.push({ start: offset, end: offset + line.text.length, left: line.left, top: line.top });
+    offset += line.text.length;
+  }
+  return { value, measure: (start: number, end: number) => boundaries.flatMap((line) => {
+    const from = Math.max(start, line.start);
+    const to = Math.min(end, line.end);
+    return to > from ? [{ left: line.left + (from - line.start) * 8, top: line.top, width: (to - from) * 8, height: 16 }] : [];
+  }) };
+}
+
+test("screenshot text retains a soft-wrapped research caveat on its measured lines", () => {
+  const fixture = measuredLines([
+    { text: "Latest available statements. SEC EPS uses ", left: 8, top: 20 },
+    { text: "corroborated split-adjusted share bases. ", left: 8, top: 38 },
+    { text: "Unverified bases are unavailable.", left: 8, top: 56 },
+  ]);
+  const result = renderedTextFragments(fixture.value, fixture.measure);
+  expect(result.map((fragment) => fragment.value)).toEqual([
+    "Latest available statements. SEC EPS uses ",
+    "corroborated split-adjusted share bases. ", "Unverified bases are unavailable.",
+  ]);
+  expect(result.map((fragment) => fragment.rect.top)).toEqual([20, 38, 56]);
+  expect(result.map((fragment) => fragment.value).join("")).toBe(fixture.value);
+});
+
+test("line fragments preserve explicit breaks, blank-line spacing and inline indentation", () => {
+  const fixture = measuredLines([
+    { text: "first\n\n", left: 40, top: 10 },
+    { text: "second ", left: 8, top: 46 },
+    { text: "wrapped", left: 8, top: 64 },
+  ]);
+  expect(renderedTextFragments(fixture.value, fixture.measure).map(({ value, rect }) => [value, rect.left, rect.top]))
+    .toEqual([["first\n\n", 40, 10], ["second ", 8, 46], ["wrapped", 8, 64]]);
+});
+
+test("range probes keep surrogate pairs intact and invisible text terminates", () => {
+  const fixture = measuredLines([{ text: "USD 🧾 ", left: 0, top: 0 }, { text: "evidence", left: 0, top: 18 }]);
+  const result = renderedTextFragments(fixture.value, (start, end) => {
+    expect(start).not.toBe(5); expect(end).not.toBe(5);
+    return fixture.measure(start, end);
+  });
+  expect(result.map((fragment) => fragment.value)).toEqual(["USD 🧾 ", "evidence"]);
+  expect(renderedTextFragments("hidden", () => [])).toEqual([]);
+});

package/src/utils/dom-screenshot.ts

@@ -1,5 +1,7 @@
 /// <reference lib="dom" />
 
+import { isScreenshotWatermarkVisible, setScreenshotWatermarkVisible } from "./screenshot-watermark";
+
 export interface PngScreenshot {
   pngBase64: string;
   width: number;
@@ -136,12 +138,54 @@ function fontFor(style: CSSStyleDeclaration): string {
   ].join(" ");
 }
 
-function textBaselineOffset(style: CSSStyleDeclaration, rect: DOMRect): number {
+function textBaselineOffset(style: CSSStyleDeclaration, rect: Pick<DOMRect, "height">): number {
   const fontSize = px(style.fontSize) || rect.height;
   const lineHeight = px(style.lineHeight) || rect.height || fontSize;
   return Math.max(fontSize * 0.78, (lineHeight + fontSize * 0.58) / 2);
 }
 
+type TextRect = Pick<DOMRect, "left" | "top" | "width" | "height">;
+
+/** Recover the browser's actual line breaks, including font and inline layout. */
+export function renderedTextFragments(
+  value: string,
+  measure: (start: number, end: number) => readonly TextRect[],
+): { value: string; rect: TextRect }[] {
+  const offsets = [0];
+  for (const character of value) offsets.push(offsets.at(-1)! + character.length);
+  const fragments: { value: string; rect: TextRect }[] = [];
+  let start = 0;
+  const visible = (rects: readonly TextRect[]) => rects.filter((rect) => rect.width > 0 && rect.height > 0);
+  while (start < offsets.length - 1) {
+    const remaining = visible(measure(offsets[start]!, value.length));
+    const first = remaining[0];
+    if (!first) break;
+    // Binary search by code-point boundaries; measuring every glyph in long
+    // research notes would add unnecessary layout work to each screenshot.
+    let low = start + 1;
+    let high = offsets.length - 1;
+    let end = low;
+    while (low <= high) {
+      const middle = Math.floor((low + high) / 2);
+      const rects = visible(measure(offsets[start]!, offsets[middle]!));
+      if (rects.every((rect) => Math.abs(rect.top - first.top) < 0.5)) {
+        end = middle;
+        low = middle + 1;
+      } else high = middle - 1;
+    }
+    const rects = visible(measure(offsets[start]!, offsets[end]!));
+    if (rects.length) {
+      const left = Math.min(...rects.map((rect) => rect.left));
+      fragments.push({ value: value.slice(offsets[start], offsets[end]), rect: {
+        left, top: first.top, height: Math.max(...rects.map((rect) => rect.height)),
+        width: Math.max(...rects.map((rect) => rect.left + rect.width)) - left,
+      } });
+    }
+    start = end;
+  }
+  return fragments;
+}
+
 function drawTextNode(
   context: CanvasRenderingContext2D,
   textNode: Text,
@@ -157,8 +201,7 @@ function drawTextNode(
   const range = document.createRange();
   range.selectNodeContents(textNode);
   const rects = Array.from(range.getClientRects()).filter((rect) => rect.width > 0 && rect.height > 0);
-  range.detach();
-  if (rects.length === 0) return;
+  if (rects.length === 0) { range.detach(); return; }
 
   context.fillStyle = style.color;
   context.font = fontFor(style);
@@ -166,17 +209,21 @@ function drawTextNode(
   context.textBaseline = "alphabetic";
   context.direction = style.direction === "rtl" ? "rtl" : "ltr";
 
-  const explicitLines = value.split(/\r?\n/);
-  if (explicitLines.length === rects.length) {
-    rects.forEach((rect, index) => {
-      const line = explicitLines[index] ?? "";
-      if (line.length === 0) return;
-      context.fillText(line, rect.left - origin.left, rect.top - origin.top + textBaselineOffset(style, rect));
-    });
-    return;
-  }
-
-  context.fillText(value, rects[0]!.left - origin.left, rects[0]!.top - origin.top + textBaselineOffset(style, rects[0]!));
+  try {
+    const fragments = rects.length === 1 ? [{ value, rect: rects[0]! }]
+      : renderedTextFragments(value, (start, end) => {
+        range.setStart(textNode, start);
+        range.setEnd(textNode, end);
+        return Array.from(range.getClientRects());
+      });
+    for (const fragment of fragments) {
+      const text = style.whiteSpace === "normal" || style.whiteSpace === "nowrap"
+        ? fragment.value.replace(/\s+/g, " ") : fragment.value.replace(/\r?\n/g, "");
+      if (!text) continue;
+      const rect = fragment.rect;
+      context.fillText(text, rect.left - origin.left, rect.top - origin.top + textBaselineOffset(style, rect));
+    }
+  } finally { range.detach(); }
 }
 
 function drawCanvasElement(
@@ -310,7 +357,15 @@ async function captureElementPngBase64(element: HTMLElement): Promise<PngScreens
   if (!context) throw new Error("Could not create pane screenshot.");
   context.scale(scale, scale);
   context.clearRect(0, 0, width, height);
-  drawElement(context, element, { left: rect.left, top: rect.top });
+  // Reveal the chart watermark only for the synchronous paint below: the
+  // browser never gets a frame in between, so the live UI does not flicker.
+  const watermarkWasVisible = isScreenshotWatermarkVisible();
+  setScreenshotWatermarkVisible(true);
+  try {
+    drawElement(context, element, { left: rect.left, top: rect.top });
+  } finally {
+    if (!watermarkWasVisible) setScreenshotWatermarkVisible(false);
+  }
 
   return {
     pngBase64: await blobToBase64(await canvasToPngBlob(canvas)),

package/src/utils/exchange-rate-snapshot.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { exchangeRateMetadata, MAX_FX_OBSERVATION_AGE_MS } from "./exchange-rate-snapshot";
+
+test("FX retention is bounded by observation age, independent of a recent fetch", () => {
+  const now = Date.parse("2026-09-10T22:00:00Z");
+  const sourceTime = now - 6 * 86_400_000;
+  const recent = { rate: 1.16, fromCurrency: "EUR", toCurrency: "USD", fetchedAt: new Date(now).toISOString() };
+  expect(exchangeRateMetadata({ ...recent, asOf: new Date(sourceTime).toISOString() }, "EUR", now))
+    .toMatchObject({ fetchedAt: now, asOf: sourceTime, expiresAt: sourceTime + MAX_FX_OBSERVATION_AGE_MS, staleAt: sourceTime + 3_600_000 });
+  for (const data of [
+    { ...recent, asOf: new Date(now - MAX_FX_OBSERVATION_AGE_MS).toISOString() },
+    { ...recent, asOf: new Date(now + 120_000).toISOString() },
+    { ...recent, asOf: "invalid" },
+    { ...recent, fetchedAt: "invalid" },
+    { ...recent, staleAt: "invalid" },
+    { ...recent, fromCurrency: "JPY" },
+  ]) expect(() => exchangeRateMetadata(data, "EUR", now)).toThrow();
+  expect(() => exchangeRateMetadata({ rate: 1.16 }, "EUR", now, now - MAX_FX_OBSERVATION_AGE_MS)).toThrow();
+  expect(exchangeRateMetadata({ ...recent, stale: true, asOf: new Date(now).toISOString() }, "EUR", now).staleAt).toBe(now);
+  expect(exchangeRateMetadata(1, "USD", now, 0)).toEqual({ staleAt: Infinity, expiresAt: Infinity, source: "identity" });
+  expect(() => exchangeRateMetadata(1.01, "USD", now, 0)).toThrow();
+});

package/src/utils/exchange-rate-snapshot.ts

@@ -0,0 +1,62 @@
+import type { ExchangeRateSnapshot } from "../types/exchange-rate";
+
+export const MAX_FX_OBSERVATION_AGE_MS = 7 * 24 * 60 * 60_000;
+const FX_FRESH_MS = 60 * 60_000;
+
+interface FxRateMetadata {
+  fetchedAt?: number;
+  asOf?: number;
+  staleAt?: number;
+  expiresAt?: number;
+  source?: string;
+}
+
+export function isUsableCachedExchangeRate(rate: number | null, currency: string,
+  timing: { asOf?: number; fetchedAt?: number | null }, now = Date.now()): boolean {
+  try {
+    exchangeRateMetadata({ rate, asOf: timing.asOf === undefined ? undefined : new Date(timing.asOf).toISOString() },
+      currency, now, timing.fetchedAt ?? undefined);
+    return true;
+  } catch { return false; }
+}
+
+/** Validate before numeric decoding, including persisted and legacy snapshots. */
+export function exchangeRateMetadata(value: unknown, currency: string, now = Date.now(), fallbackFetchedAt?: number): FxRateMetadata {
+  const data = typeof value === "number" ? { rate: value } : value as Partial<ExchangeRateSnapshot> | null;
+  const fail = () => { throw new Error(`Invalid or expired exchange rate for ${currency}/USD`); };
+  if (!data || typeof data !== "object" || !Number.isFinite(data.rate) || data.rate! <= 0
+    || (data.fromCurrency !== undefined && data.fromCurrency !== currency)
+    || (data.toCurrency !== undefined && data.toCurrency !== "USD")) return fail();
+  // The numeraire identity needs no market observation or upstream request.
+  if (currency === "USD") {
+    if (data.rate !== 1) return fail();
+    return { staleAt: Infinity, expiresAt: Infinity, source: "identity" };
+  }
+  const timestamp = (input: unknown): number | undefined => {
+    if (input === undefined) return undefined;
+    if (typeof input !== "string" || !Number.isFinite(Date.parse(input))) return fail();
+    return Date.parse(input);
+  };
+  const asOf = timestamp(data.asOf);
+  const fetchedAt = timestamp(data.fetchedAt) ?? fallbackFetchedAt;
+  const declaredStaleAt = timestamp(data.staleAt);
+  const observation = asOf ?? fetchedAt;
+  if ([asOf, fetchedAt].some((time) => time !== undefined && (!Number.isFinite(time) || time > now + 60_000))
+    || (observation !== undefined && now - observation >= MAX_FX_OBSERVATION_AGE_MS)) return fail();
+  const expiresAt = Math.min(fetchedAt === undefined ? Infinity : fetchedAt + MAX_FX_OBSERVATION_AGE_MS,
+    asOf === undefined ? Infinity : asOf + MAX_FX_OBSERVATION_AGE_MS);
+  if (expiresAt <= now) return fail();
+  const delay = typeof data.delayMinutes === "number" && Number.isFinite(data.delayMinutes) && data.delayMinutes >= 0
+    ? Math.min(data.delayMinutes, 15) * 60_000 : 0;
+  const staleAt = Math.min(declaredStaleAt ?? Infinity,
+    fetchedAt === undefined ? Infinity : fetchedAt + FX_FRESH_MS,
+    asOf === undefined ? Infinity : asOf + FX_FRESH_MS + delay,
+    data.stale === true ? now : Infinity);
+  return {
+    ...(fetchedAt !== undefined ? { fetchedAt } : {}),
+    asOf,
+    ...(Number.isFinite(expiresAt) ? { expiresAt } : {}),
+    ...(Number.isFinite(staleAt) ? { staleAt } : {}),
+    ...(typeof data.source === "string" ? { source: data.source } : {}),
+  };
+}

package/src/utils/exchanges.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   canonicalExchange,
+  canonicalTickerKey,
   CANONICAL_EXCHANGE_ALIASES,
   EXCHANGE_TIME_ZONES,
   parsePublicTickerKey,
@@ -36,3 +37,26 @@ describe("exchange metadata", () => {
     expect(parsePublicTickerKey("3hnx:xlon")).toEqual({ symbol: "3HNX", exchange: "LSE" });
   });
 });
+
+
+test("listing keys remain idempotent across persisted, public, and canonical forms", () => {
+  for (const exchange of ["LSE", "NASDAQ", "HKEX", "TSXV", "CSE", "XETRA"]) {
+    const publicKey = publicTickerKey("VOD", exchange);
+    const canonicalKey = canonicalTickerKey("VOD", exchange);
+    expect(publicTickerKey(publicKey, exchange)).toBe(publicKey);
+    expect(publicTickerKey(canonicalKey)).toBe(publicKey);
+    expect(canonicalTickerKey(publicKey, exchange)).toBe(canonicalKey);
+    expect(canonicalTickerKey(canonicalKey)).toBe(canonicalKey);
+    expect(parsePublicTickerKey(publicKey)).toEqual({ symbol: "VOD", exchange: canonicalExchange(exchange) });
+  }
+  // A saved UK listing cannot switch back to a remembered US listing.
+  expect(publicTickerKey("VOD:XLON", "NASDAQ")).toBe("VOD:XLON");
+  expect(canonicalTickerKey("VOD:XLON", "NASDAQ")).toBe("VOD:LSE");
+  expect(publicTickerKey("BRK.B")).toBe("BRK.B");
+});
+
+test("repeated exchange suffixes are repaired before provider and snapshot lookup", () => {
+  expect(parsePublicTickerKey("VOD:XLON:XLON")).toEqual({ symbol: "VOD", exchange: "LSE" });
+  expect(publicTickerKey("VOD:LSE:XLON", "LSE")).toBe("VOD:XLON");
+  expect(canonicalTickerKey("VOD:XLON:LSE")).toBe("VOD:LSE");
+});