gloomberb 0.13.2 → 0.14.0

package/src/market-data/snapshot-provider.test.ts

@@ -0,0 +1,93 @@
+import { expect, test } from "bun:test";
+import type { DataProvider } from "../types/data-provider";
+import type { PricePoint, TickerFinancials } from "../types/financials";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { createSnapshotDataProvider } from "./snapshot-provider";
+
+function financials(symbol: string, price: number): TickerFinancials {
+  return {
+    quote: { symbol, price, currency: "USD", change: 0, changePercent: 0, lastUpdated: 1 },
+    annualStatements: [], quarterlyStatements: [], priceHistory: [],
+  };
+}
+
+test("mixed snapshot/live batches preserve order and only delegate missing instruments", async () => {
+  const captured = financials("AAPL", 100);
+  const live = financials("MSFT", 200);
+  const liveTargets = [{ symbol: "MSFT", exchange: "NASDAQ" }];
+  const targets = [...liveTargets, { symbol: "AAPL", exchange: "NASDAQ" }];
+  let calls = 0;
+  const fallback = createTestDataProvider({
+    async getTickerFinancialsBatch(missing, settings) {
+      calls++;
+      expect(missing).toEqual(liveTargets);
+      expect(settings).toEqual({ forceRefresh: true });
+      return missing.map((target) => ({ target, financials: live }));
+    },
+    async getQuotesBatch(missing) {
+      calls++;
+      expect(missing).toEqual(liveTargets);
+      return missing.map((target) => ({ target, quote: live.quote! }));
+    },
+  });
+  const provider = createSnapshotDataProvider({ financials: [["AAPL:NASDAQ", captured]] }, fallback);
+  expect((await provider.getTickerFinancialsBatch!(targets, { forceRefresh: true })).map((result) => result.financials)).toEqual([live, captured]);
+  expect((await provider.getQuotesBatch!(targets)).map((result) => result.quote)).toEqual([live.quote!, captured.quote!]);
+  expect(calls).toBe(2);
+  const cached = provider.getCachedFinancialsForTargets!([targets[1]!]);
+  expect(cached).toBeInstanceOf(Map);
+  expect((cached as Map<string, TickerFinancials>).get("AAPL")).toBe(captured);
+});
+
+test("snapshot matching respects exchanges and delegated methods retain their receiver", async () => {
+  const captured = financials("AAPL", 100);
+  const otherListing = financials("AAPL", 300);
+  const options = { underlyingSymbol: "AAPL", expirationDates: [], calls: [], puts: [] };
+  let fallback: DataProvider;
+  fallback = createTestDataProvider({
+    async getTickerFinancials(symbol, exchange) {
+      expect(this).toBe(fallback);
+      expect([symbol, exchange]).toEqual(["AAPL", "NYSE"]);
+      return otherListing;
+    },
+    async getArticleSummary() { expect(this).toBe(fallback); return "live summary"; },
+    getCachedQuery() { throw new Error("live cache must not bypass captured options"); },
+  });
+  const provider = createSnapshotDataProvider({ financials: [["AAPL:NASDAQ", captured]], optionsChains: [["AAPL:NASDAQ", options]] }, fallback);
+  expect(await provider.getTickerFinancials("aapl", "NASDAQ")).toBe(captured);
+  expect(await provider.getTickerFinancials("AAPL", "NYSE")).toBe(otherListing);
+  const summary = provider.getArticleSummary;
+  expect(await summary("https://example.com")).toBe("live summary");
+  expect(await provider.getOptionsChain!("AAPL", "NASDAQ")).toBe(options);
+  expect(provider.getCachedQuery).toBeUndefined();
+});
+
+test("captured intraday data rejects other intervals and clips explicit windows without refetching", async () => {
+  const points: PricePoint[] = [0, 5, 10].map((minute) => ({ date: new Date(Date.UTC(2026, 8, 3, 13, 30 + minute)), close: minute }));
+  const captured = { symbol: "AAPL", exchange: "NASDAQ", resolution: "5m" as const, points, unavailableReason: null };
+  let liveCalls = 0;
+  const fallback = createTestDataProvider({
+    async getDetailedPriceHistory() { liveCalls++; return points; },
+  });
+  const provider = createSnapshotDataProvider({ financials: [], intradayHistories: [captured] }, fallback);
+  expect(await provider.getDetailedPriceHistory!("AAPL", "NASDAQ", points[0]!.date, points[2]!.date, "5m")).toEqual(points.slice(0, 2));
+  expect(await provider.getPriceHistoryForResolution!("AAPL", "NASDAQ", "1D", "1m")).toEqual([]);
+  expect(liveCalls).toBe(0);
+  await provider.getDetailedPriceHistory!("AAPL", "NYSE", points[0]!.date, points[2]!.date, "5m");
+  expect(liveCalls).toBe(1);
+  const unavailable = createSnapshotDataProvider({ financials: [], intradayHistories: [{ ...captured, points: [], unavailableReason: "Session unavailable" }] }, fallback);
+  await expect(unavailable.getPriceHistory("AAPL", "NASDAQ", "1D")).rejects.toThrow("Session unavailable");
+  await expect(unavailable.getDetailedPriceHistory!("AAPL", "NASDAQ", points[0]!.date, points[2]!.date, "1m")).rejects.toThrow("Session unavailable");
+});
+
+test("an ordinary captured snapshot cannot satisfy an explicit extended history request", async () => {
+ const captured = financials("MSFT", 100), extended = { ...captured, annualStatements: [{ date: "2010-06-30", totalRevenue: 100 }] };
+ let requests = 0;
+ const provider = createSnapshotDataProvider({ financials: [["MSFT:NASDAQ", captured]] }, createTestDataProvider({
+  async getTickerFinancials(_symbol, _exchange, context) { requests++; expect(context?.statementHistory).toBe("extended"); return extended; },
+ }));
+ expect(await provider.getTickerFinancials("MSFT", "NASDAQ")).toBe(captured);
+ expect(await provider.getTickerFinancials("MSFT", "NASDAQ", { statementHistory: "extended" })).toBe(extended);
+ expect((await provider.getTickerFinancialsBatch!([{ symbol: "MSFT", exchange: "NASDAQ", statementHistory: "extended" }]))[0]?.financials).toBe(extended);
+ expect(requests).toBe(2);
+});

package/src/market-data/snapshot-provider.ts

@@ -0,0 +1,175 @@
+import type { MarketDataRequestContext, DataProvider, CachedFinancialsTarget, TickerFinancialsBatchResult, QuoteBatchResult } from "../types/data-provider";
+import type { OptionsChain, PricePoint, Quote, TickerFinancials } from "../types/financials";
+import { canonicalExchange, canonicalTickerKey, parsePublicTickerKey } from "../utils/exchanges";
+import { clipPriceHistoryToRange } from "../time-series/history-window";
+import { getPresetResolution, normalizeChartResolutionSupport, TIME_RANGE_ORDER, type ManualChartResolution } from "../time-series/resolution";
+import type { InstrumentRef } from "./request-types";
+import { instrumentIdentityKey } from "../utils/instrument-identity";
+import { quoteMetadataFromQuote } from "./quotes/metadata";
+
+export interface SnapshotMarketData {
+  financials: ReadonlyArray<readonly [string, TickerFinancials]>;
+  instrumentFinancials?: ReadonlyArray<{ instrument: InstrumentRef; financials: TickerFinancials }>;
+  intradayHistories?: ReadonlyArray<{
+    target?: InstrumentRef;
+    symbol: string;
+    exchange: string;
+    resolution: ManualChartResolution;
+    points: PricePoint[];
+    unavailableReason: string | null;
+    /** Metadata already fetched to validate the captured history's price domain. */
+    quote?: Quote;
+  }>;
+  optionsChains?: ReadonlyArray<readonly [string, OptionsChain]>;
+}
+
+/** Exact captured identity, retaining the snapshot API's public venue alias matching. */
+export function snapshotInstrumentKey(instrument: InstrumentRef): string {
+  const parsed = parsePublicTickerKey(instrument.symbol);
+  return instrumentIdentityKey({ ...instrument, symbol: parsed.symbol,
+    exchange: canonicalExchange(parsed.exchange ?? instrument.exchange),
+    brokerId: instrument.brokerId ?? instrument.instrument?.brokerId,
+    brokerInstanceId: instrument.brokerInstanceId ?? instrument.instrument?.brokerInstanceId,
+  });
+}
+
+/** A captured result is authoritative; trying another interval cannot repair it. */
+export class SnapshotHistoryUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SnapshotHistoryUnavailableError";
+  }
+}
+
+const SNAPSHOT_RESOLUTIONS = normalizeChartResolutionSupport(
+  TIME_RANGE_ORDER.map((maxRange) => ({ resolution: getPresetResolution(maxRange), maxRange })),
+);
+
+function lookup<T>(entries: ReadonlyArray<readonly [string, T]>) {
+  const values = new Map(entries.map(([key, value]) => {
+    const { symbol, exchange } = parsePublicTickerKey(key);
+    return [canonicalTickerKey(symbol, exchange), value] as const;
+  }));
+  return (symbol: string, exchange?: string) => (
+    values.get(canonicalTickerKey(symbol, exchange)) ?? values.get(canonicalTickerKey(symbol))
+  );
+}
+
+async function seededBatch<T, R>(targets: T[], find: (target: T) => R | undefined, load: (missing: T[]) => Promise<R[]>): Promise<R[]> {
+  const results = targets.map(find);
+  const missing = targets.filter((_, index) => results[index] === undefined);
+  if (!missing.length) return results as R[];
+  const loaded = await load(missing);
+  let index = 0;
+  return results.map((result) => result ?? loaded[index++]!);
+}
+
+/** A captured dataset wins for its instruments; everything else uses the live provider. */
+export function createSnapshotDataProvider(snapshot: SnapshotMarketData, fallback: DataProvider): DataProvider {
+  const publicFinancials = lookup(snapshot.financials);
+  const exactFinancials = new Map((snapshot.instrumentFinancials ?? []).map(entry => [snapshotInstrumentKey(entry.instrument), entry.financials]));
+  const financials = (symbol: string, exchange?: string, context?: MarketDataRequestContext) =>
+    exactFinancials.get(snapshotInstrumentKey({ symbol, exchange, ...context }))
+      ?? (context?.instrument ? undefined : publicFinancials(symbol, exchange));
+  const options = lookup(snapshot.optionsChains ?? []);
+  const publicIntraday = lookup((snapshot.intradayHistories ?? []).filter(history => !history.target?.instrument)
+    .map(history => [canonicalTickerKey(history.symbol, history.exchange), history]));
+  const exactIntraday = new Map((snapshot.intradayHistories ?? []).flatMap(history => history.target ? [[snapshotInstrumentKey(history.target), history] as const] : []));
+  const intraday = (symbol: string, exchange?: string, context?: MarketDataRequestContext) =>
+    exactIntraday.get(snapshotInstrumentKey({ symbol, exchange, ...context }))
+      ?? (context?.instrument ? undefined : publicIntraday(symbol, exchange));
+  const history = (symbol: string, exchange?: string, resolution?: string, context?: MarketDataRequestContext) => {
+    const captured = intraday(symbol, exchange, context);
+    if (captured?.unavailableReason) throw new SnapshotHistoryUnavailableError(captured.unavailableReason);
+    if (captured && resolution && captured.resolution !== resolution) return [];
+    return captured?.points ?? financials(symbol, exchange, context)?.priceHistory;
+  };
+  const overrides: Partial<DataProvider> = {
+    async getTickerFinancials(symbol, exchange, context) {
+      return (context?.statementHistory === "extended" ? undefined : financials(symbol, exchange, context)) ?? fallback.getTickerFinancials(symbol, exchange, context);
+    },
+    getCachedFinancialsForTargets(targets, settings) {
+      const captured = new Map<string, TickerFinancials>();
+      const missing: CachedFinancialsTarget[] = [];
+      // This legacy cache API returns one entry per symbol. Distinct targets
+      // cannot be represented there; the identity-bearing batch API can.
+      const identities = new Map<string, Set<string>>();
+      for (const target of targets) {
+        const symbol = target.symbol.trim().toUpperCase();
+        const keys = identities.get(symbol) ?? new Set<string>();
+        keys.add(snapshotInstrumentKey(target));
+        identities.set(symbol, keys);
+      }
+      for (const target of targets) {
+        if (identities.get(target.symbol.trim().toUpperCase())!.size > 1) continue;
+        const value = target.statementHistory === "extended" ? undefined : financials(target.symbol, target.exchange, target);
+        if (value) captured.set(target.symbol.trim().toUpperCase(), value);
+        else missing.push(target);
+      }
+      const live = missing.length ? fallback.getCachedFinancialsForTargets?.(missing, settings) : undefined;
+      const merge = (values?: Map<string, TickerFinancials>) => new Map([...values ?? [], ...captured]);
+      return live instanceof Promise ? live.then(merge) : merge(live);
+    },
+    getTickerFinancialsBatch(targets, settings) {
+      return seededBatch(targets, (target): TickerFinancialsBatchResult | undefined => {
+        const value = target.statementHistory === "extended" ? undefined : financials(target.symbol, target.exchange, target);
+        return value ? { target, financials: value } : undefined;
+      }, (missing) => fallback.getTickerFinancialsBatch?.(missing, settings) ?? Promise.all(missing.map(async (target) => ({
+        target, financials: await fallback.getTickerFinancials(target.symbol, target.exchange, target),
+      }))));
+    },
+    async getQuote(symbol, exchange, context) {
+      return intraday(symbol, exchange, context)?.quote ?? financials(symbol, exchange, context)?.quote ?? fallback.getQuote(symbol, exchange, context);
+    },
+    async getQuoteMetadata(symbol, exchange, context) {
+      const captured = financials(symbol, exchange, context);
+      if (captured?.quoteMetadata) return captured.quoteMetadata;
+      const quote = intraday(symbol, exchange, context)?.quote ?? captured?.quote;
+      if (quote) return quoteMetadataFromQuote(quote);
+      return fallback.getQuoteMetadata?.(symbol, exchange, context)
+        ?? fallback.getQuote(symbol, exchange, context).then(quoteMetadataFromQuote);
+    },
+    getQuotesBatch(targets, settings) {
+      return seededBatch(targets, (target): QuoteBatchResult | undefined => {
+        const quote = intraday(target.symbol, target.exchange, target.context)?.quote ?? financials(target.symbol, target.exchange, target.context)?.quote;
+        return quote ? { target, quote } : undefined;
+      }, (missing) => fallback.getQuotesBatch?.(missing, settings) ?? Promise.all(missing.map(async (target) => ({
+        target, quote: await fallback.getQuote(target.symbol, target.exchange, target.context),
+      }))));
+    },
+    async getOptionsChain(symbol, exchange, expirationDate, context) {
+      const captured = context?.instrument ? undefined : options(symbol, exchange);
+      if (captured) return captured;
+      if (!fallback.getOptionsChain) throw new Error(`No options data available for ${symbol}.`);
+      return fallback.getOptionsChain(symbol, exchange, expirationDate, context);
+    },
+    async getPriceHistory(symbol, exchange, range, context) {
+      const points = history(symbol, exchange, undefined, context);
+      return points ? clipPriceHistoryToRange(points, range) : fallback.getPriceHistory(symbol, exchange, range, context);
+    },
+    async getPriceHistoryForResolution(symbol, exchange, range, resolution, context) {
+      const points = history(symbol, exchange, resolution, context);
+      return points ? clipPriceHistoryToRange(points, range)
+        : fallback.getPriceHistoryForResolution?.(symbol, exchange, range, resolution, context)
+          ?? fallback.getPriceHistory(symbol, exchange, range, context);
+    },
+    async getDetailedPriceHistory(symbol, exchange, start, end, resolution, context) {
+      const points = history(symbol, exchange, resolution, context);
+      if (!points) return fallback.getDetailedPriceHistory?.(symbol, exchange, start, end, resolution, context) ?? [];
+      return points.filter((point) => point.date.getTime() >= start.getTime() && point.date.getTime() < end.getTime());
+    },
+    getChartResolutionSupport(symbol, exchange, context) {
+      return financials(symbol, exchange, context) || intraday(symbol, exchange, context) ? SNAPSHOT_RESOLUTIONS
+        : fallback.getChartResolutionSupport?.(symbol, exchange, context) ?? SNAPSHOT_RESOLUTIONS;
+    },
+  };
+  return new Proxy(fallback, {
+    get(target, property) {
+      // A live query handle could bypass the captured options through the
+      // coordinator. Live fallback methods still use their provider's cache.
+      if (property === "getCachedQuery") return undefined;
+      const value = Reflect.get(overrides, property) ?? Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

package/src/market-data/ticker-price-returns.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import type { TickerFinancials } from "../types/financials";
+import { computeTickerPriceReturns } from "./ticker-price-returns";
+
+test("dated return projection cannot recover undated summaries when history is absent", () => {
+  const financials: TickerFinancials = {
+    annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    fundamentals: { return1Y: .12, return3Y: .4 },
+  };
+  expect(computeTickerPriceReturns(financials)).toEqual({ return1Y: undefined, return3Y: undefined });
+  expect(computeTickerPriceReturns(null)).toEqual({ return1Y: undefined, return3Y: undefined });
+});
+
+test("return projection preserves the bond history guard and independent compatible equity quotes", () => {
+  const financials: TickerFinancials = {
+    annualStatements: [], quarterlyStatements: [],
+    priceHistory: [{ date: new Date("2025-09-10"), close: 100 }, { date: new Date("2026-09-10"), close: 100 }],
+    quote: { symbol: "CONTROL", currency: "USD", price: 105, change: 5, changePercent: 5, lastUpdated: Date.parse("2026-09-11"), instrumentType: "BOND", priceBasis: "per-unit" },
+  };
+  expect(computeTickerPriceReturns(financials).return1Y).toBe(0);
+  financials.quote!.instrumentType = "ETF";
+  expect(computeTickerPriceReturns(financials).return1Y).toBe(.05);
+  expect(computeTickerPriceReturns(financials, "BOND").return1Y).toBe(0);
+  financials.quote = undefined;
+  expect(computeTickerPriceReturns(financials).return1Y).toBe(0);
+});

package/src/market-data/ticker-price-returns.ts

@@ -0,0 +1,18 @@
+import { hasUnknownBondHistoryBasis } from "../time-series/chart-data";
+import type { Fundamentals, TickerFinancials } from "../types/financials";
+import { appendQuoteToPriceReturnHistory, buildPriceReturnFields } from "./performance";
+
+/** Summary return fields have no dated coverage. Rebuild them from observations,
+ * including when an older cached summary supplied a since-inception return. */
+export function computeTickerPriceReturns(
+  financials: TickerFinancials | null,
+  assetCategory?: string,
+): Pick<Fundamentals, "return1Y" | "return3Y"> {
+  const quote = hasUnknownBondHistoryBasis(financials?.quote, assetCategory, financials?.quoteMetadata?.instrumentType)
+    ? undefined : financials?.quote;
+  const fields = buildPriceReturnFields(appendQuoteToPriceReturnHistory(financials?.priceHistory ?? [], quote));
+  return {
+    return1Y: fields.find((field) => field.id === "1Y")?.value ?? undefined,
+    return3Y: fields.find((field) => field.id === "3Y")?.value ?? undefined,
+  };
+}

package/src/news/aggregator.test.ts

@@ -490,8 +490,8 @@ describe("NewsService", () => {
   });
 
   it("appends paged news instead of replacing the first page", async () => {
-    const first = makeItem({ url: "https://example.com/a", title: "First" });
-    const second = makeItem({ url: "https://example.com/b", title: "Second" });
+    const first = makeItem({ url: "https://example.com/a", title: "First", publishedAt: new Date("2026-01-02") });
+    const second = makeItem({ url: "https://example.com/b", title: "Second", publishedAt: new Date("2026-01-01") });
     const fetchNewsPage = mock(async (query: { cursor?: string }) => (
       query.cursor === "page-2"
         ? { articles: [second], nextCursor: null }
@@ -520,8 +520,8 @@ describe("NewsService", () => {
   });
 
   it("keeps paged news past the query page size", async () => {
-    const first = makeItem({ url: "https://example.com/a", title: "First" });
-    const second = makeItem({ url: "https://example.com/b", title: "Second" });
+    const first = makeItem({ url: "https://example.com/a", title: "First", publishedAt: new Date("2026-01-02") });
+    const second = makeItem({ url: "https://example.com/b", title: "Second", publishedAt: new Date("2026-01-01") });
     const fetchNewsPage = mock(async (query: { cursor?: string }) => (
       query.cursor === "page-2"
         ? { articles: [second], nextCursor: "page-3" }
@@ -578,3 +578,19 @@ describe("NewsService", () => {
     expect(state.nextCursor).toBe("page-3");
   });
 });
+
+it("retains usable articles and source-owned failure status until a successful replacement", async () => {
+  const service = new NewsService();
+  let failed = true;
+  service.register(newsProvider({ id: "feeds", name: "Feeds", provider: {
+    fetchNews: async () => [],
+    fetchNewsPage: async () => ({ articles: [makeItem({ url: "https://example.com/available" })], error: failed ? "1 of 2 RSS feeds unavailable." : null }),
+  } }));
+  const first = await service.load({ feed: "latest" });
+  expect(first.articles).toHaveLength(1);
+  expect(first.error).toBe("1 of 2 RSS feeds unavailable.");
+  expect(first.phase).toBe("ready");
+  failed = false;
+  expect((await service.load({ feed: "latest" })).error).toBeNull();
+  service.stop();
+});

package/src/news/aggregator.ts

@@ -10,6 +10,7 @@ import {
   filterNewsArticlesForQuery,
   markDetailCapableArticle,
   mergeNewsArticle,
+  newsArticleRevision,
   normalizeNewsCategory,
   normalizeNewsFeed,
   normalizeNewsQuery,
@@ -37,6 +38,7 @@ interface SourceFetchResult {
   articles: NewsArticle[];
   sourceIds: string[];
   failedSourceIds: string[];
+  errors: string[];
   nextCursor: string | null;
 }
 
@@ -216,6 +218,17 @@ export class NewsService {
     const sources = this.enabledSources({ feed: "latest" })
       .filter((source) => !!source.provider.fetchNewsStory);
 
+    const requestedRevisions = new Map<NewsQueryEntry, string>();
+    for (const entry of this.queries.values()) {
+      const article = entry.state.articles.find((article) => article.id === storyId);
+      if (article) requestedRevisions.set(entry, newsArticleRevision(article));
+    }
+    let failed = false;
+    let olderDetail: NewsArticle | null = null;
+    const commitDetail = (article: NewsArticle) => {
+      this.mergeStoryDetail(article, requestedRevisions);
+      return this.articles.find((current) => current.id === storyId) ?? article;
+    };
     for (const source of sources) {
       try {
         const article = await this.trackSourceRequest(
@@ -224,13 +237,23 @@ export class NewsService {
           () => source.provider.fetchNewsStory?.(storyId) ?? Promise.resolve(null),
         );
         if (!article) continue;
-        this.mergeStoryDetail(article);
-        return article;
+        if (article.id !== storyId) throw new Error("Story detail identity mismatch.");
+        const current = this.articles.find((current) => current.id === storyId);
+        if (current && article.publishedAt < current.publishedAt) {
+          if (!olderDetail || article.publishedAt > olderDetail.publishedAt) olderDetail = article;
+          continue;
+        }
+        return commitDetail(article);
       } catch {
+        failed = true;
         // Continue to lower-priority sources.
       }
     }
 
+    // A newer fallback is preferred. Otherwise older, explicitly dated source
+    // items can enrich the timeline without rolling back the known headline.
+    if (olderDetail) return commitDetail(olderDetail);
+    if (failed) throw new Error("Story detail unavailable.");
     return null;
   }
 
@@ -283,9 +306,12 @@ export class NewsService {
           articles,
           // A partial failure still has stories, so it stays ready and reports
           // the gap instead of pretending the feed is complete.
-          error: result.failedSourceIds.length > 0
-            ? `${result.failedSourceIds.length} of ${result.failedSourceIds.length + result.sourceIds.length} news sources unavailable.`
-            : null,
+          error: [
+            result.failedSourceIds.length > 0
+              ? `${result.failedSourceIds.length} of ${result.failedSourceIds.length + result.sourceIds.length} news sources unavailable.`
+              : null,
+            ...result.errors,
+          ].filter(Boolean).join(" ") || null,
           updatedAt: this.now(),
           sourceIds: result.sourceIds,
           nextCursor: hasOlderPages ? entry.state.nextCursor : result.nextCursor,
@@ -378,7 +404,7 @@ export class NewsService {
   private async readSourcePage(
     source: NewsCapability,
     query: NewsQuery,
-  ): Promise<{ articles: NewsArticle[]; nextCursor: string | null }> {
+  ): Promise<{ articles: NewsArticle[]; nextCursor: string | null; error?: string | null }> {
     if (source.provider.fetchNewsPage) {
       const page = await this.trackSourceRequest(
         source,
@@ -388,6 +414,7 @@ export class NewsService {
       return {
         articles: page.articles.map((article) => markDetailCapableArticle(source, article)),
         nextCursor: page.nextCursor ?? null,
+        error: page.error,
       };
     }
     const articles = (await this.trackSourceRequest(
@@ -408,6 +435,7 @@ export class NewsService {
           articles: page.articles,
           sourceIds: [newsCapabilitySourceId(source)],
           failedSourceIds,
+          errors: page.error ? [page.error] : [],
           nextCursor: page.nextCursor,
         };
         if (page.articles.length > 0) return result;
@@ -416,7 +444,7 @@ export class NewsService {
         failedSourceIds.push(newsCapabilitySourceId(source));
       }
     }
-    return firstEmpty ?? { articles: [], sourceIds: [], failedSourceIds, nextCursor: null };
+    return firstEmpty ?? { articles: [], sourceIds: [], failedSourceIds, errors: [], nextCursor: null };
   }
 
   private async fetchMergedNews(query: NewsQuery, sources: NewsCapability[]): Promise<SourceFetchResult> {
@@ -427,6 +455,7 @@ export class NewsService {
       })),
     );
     const articles: NewsArticle[] = [];
+    const errors: string[] = [];
     const sourceIds: string[] = [];
     const failedSourceIds: string[] = [];
     let nextCursor: string | null = null;
@@ -437,10 +466,11 @@ export class NewsService {
         return;
       }
       articles.push(...result.value.page.articles);
+      if (result.value.page.error) errors.push(result.value.page.error);
       sourceIds.push(newsCapabilitySourceId(result.value.source));
       nextCursor ??= result.value.page.nextCursor;
     });
-    return { articles, sourceIds, failedSourceIds, nextCursor };
+    return { articles, sourceIds, failedSourceIds, errors, nextCursor };
   }
 
   private trackSourceRequest<T>(
@@ -486,12 +516,12 @@ export class NewsService {
     this.articles = dedupeNewsArticles([...this.queries.values()].flatMap((entry) => entry.state.articles));
   }
 
-  private mergeStoryDetail(article: NewsArticle): void {
+  private mergeStoryDetail(article: NewsArticle, requestedRevisions: Map<NewsQueryEntry, string>): void {
     let changed = false;
     for (const entry of this.queries.values()) {
       let stateChanged = false;
       const nextArticles = entry.state.articles.map((existing) => {
-        if (existing.id !== article.id) return existing;
+        if (existing.id !== article.id || requestedRevisions.get(entry) !== newsArticleRevision(existing)) return existing;
         stateChanged = true;
         changed = true;
         return mergeNewsArticle(existing, article);

package/src/news/news-model.ts

@@ -138,7 +138,29 @@ function selectDetailArticle(
   return null;
 }
 
+function newsArticleSummaryRevision(article: NewsArticle): string {
+  return JSON.stringify([article.id, article.publishedAt.getTime(), article.title, article.summary, article.url, article.source]);
+}
+
+export function newsArticleRevision(article: NewsArticle): string {
+  return JSON.stringify([newsArticleSummaryRevision(article), article.items ?? []]);
+}
+
 function mergeDuplicateArticle(existing: NewsArticle, item: NewsArticle): NewsArticle {
+  if (existing.id === item.id) {
+    // A story's newer publication supersedes its earlier importance score.
+    // For equal timestamps, the first (freshly fetched) correction wins;
+    // identical content can still carry a higher cross-source ranking.
+    const sameSummary = newsArticleSummaryRevision(existing) === newsArticleSummaryRevision(item);
+    const compatibleTimeline = !hasStoryItems(existing) || !hasStoryItems(item)
+      || newsArticleRevision(existing) === newsArticleRevision(item);
+    const winner = item.publishedAt > existing.publishedAt
+      || (sameSummary && compatibleTimeline && item.importance > existing.importance) ? item : existing;
+    const other = winner === item ? existing : item;
+    return !hasStoryItems(winner) && sameSummary && hasStoryItems(other)
+      ? { ...winner, items: other.items }
+      : winner;
+  }
   const winner = shouldReplaceDuplicate(existing, item)
     ? { ...existing, ...item }
     : existing;
@@ -152,8 +174,15 @@ function mergeDuplicateArticle(existing: NewsArticle, item: NewsArticle): NewsAr
 }
 
 export function dedupeNewsArticles(items: NewsArticle[]): NewsArticle[] {
-  const byKey = new Map<string, NewsArticle>();
+  // A publisher can correct a story's URL. Collapse stable IDs first so the
+  // same story cannot survive twice under its old and new URLs.
+  const byId = new Map<string, NewsArticle>();
   for (const item of items) {
+    const existing = byId.get(item.id);
+    byId.set(item.id, existing ? mergeDuplicateArticle(existing, item) : item);
+  }
+  const byKey = new Map<string, NewsArticle>();
+  for (const item of byId.values()) {
     const key = articleKey(item);
     const existing = byKey.get(key);
     if (!existing) {
@@ -168,10 +197,12 @@ export function dedupeNewsArticles(items: NewsArticle[]): NewsArticle[] {
 export function mergeNewsArticle(base: NewsArticle, detail: NewsArticle): NewsArticle {
   const detailItems = detail.items ?? [];
   const baseItems = base.items ?? [];
+  const olderDetail = detail.publishedAt < base.publishedAt;
   return {
     ...base,
     ...detail,
-    items: detailItems.length > 0 ? detailItems : baseItems,
+    ...(olderDetail ? base : {}),
+    items: olderDetail && baseItems.length > 0 ? baseItems : detailItems.length > 0 ? detailItems : baseItems,
   };
 }
 

package/src/news/types.ts

@@ -70,6 +70,8 @@ export interface NewsQuery {
 export type NewsQueryPhase = "idle" | "loading" | "ready" | "refreshing" | "error";
 
 export interface NewsPage {
+  /** Active source failure, including a partial failure with usable articles. */
+  error?: string | null;
   articles: NewsArticle[];
   nextCursor?: string | null;
 }

package/src/pane-settings.ts

@@ -71,3 +71,27 @@ export function deletePaneSetting(
   delete nextSettings[key];
   return setPaneSettings(layout, paneId, Object.keys(nextSettings).length > 0 ? nextSettings : undefined);
 }
+
+/**
+ * Reserved settings key for the pane lock. The value lives on the instance
+ * rather than in pane settings so a plugin's `applyValue` never sees it and a
+ * published layout never carries someone else's lock.
+ */
+export const PANE_LOCK_SETTING_KEY = "pane.locked";
+
+export function isPaneLocked(instance: PaneInstanceConfig | null | undefined): boolean {
+  return instance?.locked === true;
+}
+
+export function isPaneLockedInLayout(layout: LayoutConfig, paneId: string): boolean {
+  return isPaneLocked(findPaneInstance(layout, paneId));
+}
+
+export function setPaneLocked(layout: LayoutConfig, paneId: string, locked: boolean): LayoutConfig {
+  const current = findPaneInstance(layout, paneId);
+  if (!current || isPaneLocked(current) === locked) return layout;
+  return updatePaneInstance(layout, paneId, (instance) => ({
+    ...instance,
+    locked: locked ? true : undefined,
+  }));
+}