gloomberb 0.18.2 → 0.18.4

package/src/updater/index.ts

@@ -1,5 +1,15 @@
 import type { UpdateChannel } from "../types/config";
+import { reportUpdateFailure, type UpdateInstallKind } from "../telemetry/update-failures";
+import { detectLinuxLibc, type LinuxLibc } from "../utils/linux-libc";
 import { compareSemver, isPrereleaseVersion } from "../utils/semver";
+import { PACKAGE_NAME } from "../version";
+import {
+  classifyUpdateError,
+  httpStatusFailureCode,
+  type UpdateFailure,
+  type UpdateFailureCode,
+  type UpdateFailurePhase,
+} from "./failure";
 import {
   GITHUB_LATEST_RELEASE_API_URL,
   GITHUB_RELEASES_API_URL,
@@ -49,6 +59,8 @@ export interface UpdateProgress {
   message?: string;
   /** With `ready`: this host can apply the update and relaunch on request. */
   canRestart?: boolean;
+  /** With `error`: the step that failed and why, which the header says in a few words. */
+  failure?: UpdateFailure;
 }
 
 export type UpdateAction =
@@ -68,7 +80,7 @@ export type UpdateCheckResult =
   /** `notice`: why a newer-looking state is not an update, such as a nightly build waiting for a stable release. */
   | { kind: "current"; notice?: string }
   | { kind: "disabled" }
-  | { kind: "error"; error: string };
+  | { kind: "error"; error: string; failure?: UpdateFailure };
 
 /**
  * On the stable channel a nightly build is never replaced by an older stable
@@ -101,6 +113,7 @@ export function setUpdateHost(host: UpdateHost | null): void {
 
 export function getAssetBaseNameForRuntime(
   runtimeProcess: Pick<NodeJS.Process, "platform" | "arch"> | null = getRuntimeProcess(),
+  libc: LinuxLibc | null = detectLinuxLibc(),
 ): string {
   const os = runtimeProcess?.platform === "darwin"
     ? "darwin"
@@ -111,8 +124,10 @@ export function getAssetBaseNameForRuntime(
   // 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";
+  // A musl system keeps the musl build: the glibc one cannot start there.
+  const variant = os === "linux" && libc === "musl" ? "-musl" : "";
   const extension = os === "windows" ? ".exe" : "";
-  return `gloomberb-${os}-${arch}${extension}`;
+  return `gloomberb-${os}-${arch}${variant}${extension}`;
 }
 
 function getAssetBaseName(): string {
@@ -269,7 +284,7 @@ export function detectUpdateAction(
     || entrypoint.includes("/.bun/install/")
     || entrypoint.includes("/install/global/")
   ) {
-    return { kind: "manual", command: "bun install -g gloomberb@latest" };
+    return { kind: "manual", command: `bun install -g ${PACKAGE_NAME}@latest` };
   }
 
   if (
@@ -292,7 +307,7 @@ export function detectUpdateAction(
     || entrypoint.includes("/lib/node_modules/")
     || entrypoint.includes("/node_modules/")
   ) {
-    return { kind: "manual", command: "npm install -g gloomberb@latest" };
+    return { kind: "manual", command: `npm install -g ${PACKAGE_NAME}@latest` };
   }
 
   return null;
@@ -302,6 +317,23 @@ export function canSelfUpdate(release: Pick<ReleaseInfo, "updateAction"> | null
   return release?.updateAction.kind === "self" || release?.updateAction.kind === "desktop";
 }
 
+/**
+ * Whether the install-update key has something to retry: a release this build
+ * can install itself whose last attempt failed. A fresh one downloads on its
+ * own, and a manual or managed one names its own command. (A downloaded
+ * desktop update has its own use of the key: restarting into it.)
+ */
+export function canRetryUpdate(state: {
+  updateAvailable: ReleaseInfo | null;
+  updateProgress: UpdateProgress | null;
+  updateCheckInProgress: boolean;
+}): boolean {
+  return !!state.updateAvailable
+    && state.updateProgress?.phase === "error"
+    && !state.updateCheckInProgress
+    && canSelfUpdate(state.updateAvailable);
+}
+
 /** A downloaded update this host can install and relaunch into when the user asks. */
 export function canRestartToApply(progress: UpdateProgress | null | undefined): boolean {
   return progress?.phase === "ready" && progress.canRestart === true;
@@ -344,6 +376,11 @@ export async function checkForUpdateDetailed(
     return { kind: "disabled" };
   }
   const nightly = channel === "nightly" && updateAction.kind === "self";
+  const failed = (error: string, code: UpdateFailureCode, targetVersion?: string): UpdateCheckResult => {
+    const failure: UpdateFailure = { phase: "check", code };
+    reportUpdateFailure(failure, { targetVersion, channel: nightly ? "nightly" : "stable" });
+    return { kind: "error", error, failure };
+  };
 
   let timeout: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -356,7 +393,7 @@ export async function checkForUpdateDetailed(
     });
 
     if (!res.ok) {
-      return { kind: "error", error: `GitHub returned ${res.status}` };
+      return failed(`GitHub returned ${res.status}`, httpStatusFailureCode(res.status));
     }
 
     const payload = await res.json();
@@ -379,16 +416,10 @@ export async function checkForUpdateDetailed(
 
     const asset = resolveReleaseAsset(data.assets);
     if (!asset) {
-      return {
-        kind: "error",
-        error: `No compatible release asset found for ${getAssetBaseName()}`,
-      };
+      return failed(`No compatible release asset found for ${getAssetBaseName()}`, "no_build", version);
     }
     if (!asset.checksum) {
-      return {
-        kind: "error",
-        error: `Release asset ${asset.name} is missing a valid SHA-256 digest`,
-      };
+      return failed(`Release asset ${asset.name} is missing a valid SHA-256 digest`, "no_build", version);
     }
 
     return {
@@ -406,12 +437,10 @@ export async function checkForUpdateDetailed(
     };
   } catch (error: unknown) {
     if (error instanceof Error && error.name === "AbortError") {
-      return { kind: "error", error: "Update check timed out" };
+      return failed("Update check timed out", "timeout");
     }
-    return {
-      kind: "error",
-      error: error instanceof Error ? error.message : "Update check failed",
-    };
+    const code = classifyUpdateError(error);
+    return failed(error instanceof Error ? error.message : "Update check failed", code === "unknown" && error instanceof SyntaxError ? "bad_response" : code);
   } finally {
     if (timeout) clearTimeout(timeout);
   }
@@ -483,7 +512,7 @@ export async function performUpdate(
       error: action.kind === "manual"
         ? `Run ${action.command}`
         : action.kind === "managed"
-          ? `Update through the package manager that installed Gloomberb: ${action.reason}.`
+          ? `Update through the package manager that installed Gloom: ${action.reason}.`
           : "This update type is unavailable in the current runtime.",
     });
     return;
@@ -501,20 +530,26 @@ export async function performUpdate(
   if (!execPath) {
     onProgress({
       phase: "error",
-      error: "Self-update is unavailable when running from source or via Bun/Node. Relaunch the packaged gloomberb binary to update.",
+      error: "Self-update is unavailable when running from source or via Bun/Node. Relaunch the packaged gloom binary to update.",
     });
     return;
   }
 
   const checksum = /^[a-f\d]{64}$/i.exec(release.checksum ?? "")?.[0].toLowerCase();
+  const fail = (failure: UpdateFailure, error: string) => {
+    reportUpdateFailure(failure, { targetVersion: release.version, channel: release.channel });
+    onProgress({ phase: "error", error, failure });
+  };
   if (!checksum) {
-    onProgress({ phase: "error", error: "Self-update requires a valid SHA-256 checksum." });
+    fail({ phase: "verify", code: "no_build" }, "Self-update requires a valid SHA-256 checksum.");
     return;
   }
 
   const updatePath = execPath + ".update";
   const oldPath = execPath + ".old";
   let unlinkUpdatePath: ((path: string) => void) | null = null;
+  /** The step under way, which a thrown error is reported against. */
+  let phase: UpdateFailurePhase = "download";
 
   try {
     // Not import(): Bun folds even a specifier held in a variable and bundles
@@ -531,7 +566,7 @@ export async function performUpdate(
 
     const res = await fetch(release.downloadUrl);
     if (!res.ok || !res.body) {
-      throw new Error(`Download failed: ${res.status}`);
+      throw new UpdateStepError({ phase: "download", code: httpStatusFailureCode(res.status) }, `Download failed: ${res.status}`);
     }
 
     const contentLength = Number(res.headers.get("content-length") || 0);
@@ -540,7 +575,18 @@ export async function performUpdate(
     let received = 0;
 
     while (true) {
-      const { done, value } = await reader.read();
+      let chunk: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        // The connection broke partway: whatever it says, the file is incomplete.
+        const code = classifyUpdateError(error);
+        throw new UpdateStepError(
+          { phase: "download", code: code === "timeout" ? code : "interrupted" },
+          error instanceof Error ? error.message : "Download interrupted",
+        );
+      }
+      const { done, value } = chunk;
       if (done) break;
       chunks.push(value);
       received += value.length;
@@ -551,7 +597,14 @@ export async function performUpdate(
         });
       }
     }
+    if (contentLength > 0 && received < contentLength) {
+      throw new UpdateStepError(
+        { phase: "download", code: "interrupted" },
+        `Download stopped at ${received} of ${contentLength} bytes`,
+      );
+    }
 
+    phase = "verify";
     const downloaded = new Uint8Array(received);
     let offset = 0;
     for (const chunk of chunks) {
@@ -560,11 +613,12 @@ export async function performUpdate(
     }
     const actual = createHash("sha256").update(downloaded).digest("hex");
     if (actual !== checksum) {
-      throw new Error(`Checksum mismatch: expected ${checksum}, got ${actual}`);
+      throw new UpdateStepError({ phase: "verify", code: "corrupt" }, `Checksum mismatch: expected ${checksum}, got ${actual}`);
     }
     const nextBinary = release.compressed
       ? new Uint8Array(gunzipSync(downloaded))
       : downloaded;
+    phase = "apply";
     await Bun.write(updatePath, nextBinary);
     chmodSync(updatePath, 0o755);
 
@@ -600,9 +654,24 @@ export async function performUpdate(
     try {
       unlinkUpdatePath?.(updatePath);
     } catch { /* Intentional ignore: Remove a partial update download while the original failure is reported through update progress. */ }
-    onProgress({
-      phase: "error",
-      error: err instanceof Error ? err.message : "Update failed",
-    });
+    const failure = err instanceof UpdateStepError ? err.failure : { phase, code: classifyUpdateError(err) };
+    fail(failure, err instanceof Error ? err.message : "Update failed");
   }
 }
+
+/** A failed step whose code is known where it is thrown. */
+class UpdateStepError extends Error {
+  constructor(readonly failure: UpdateFailure, message: string) {
+    super(message);
+    this.name = "UpdateStepError";
+  }
+}
+
+/** How the running terminal app was installed, as update failure reports name it. */
+export function terminalInstallKind(action: UpdateAction | null = detectUpdateAction()): UpdateInstallKind {
+  if (!action) return "terminal-source";
+  if (action.kind === "self") return "terminal-binary";
+  if (action.kind === "managed") return "terminal-managed";
+  if (action.kind === "manual") return "terminal-package-manager";
+  return "unknown";
+}

package/src/utils/calendar-date.ts

@@ -43,6 +43,8 @@ const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const YEAR_LAST = /^(\d{1,2})([/.-])(\d{1,2})\2(\d{4})$/;
 /** A four-digit year first, written another way than YYYY-MM-DD: 2026/10/14, 2026.10.14, 2026-10-4. */
 const YEAR_FIRST = /^(\d{4})([/.-])(\d{1,2})\2(\d{1,2})$/;
+/** The year, month and day marked as Japanese and Chinese write them (2026年10月14日), and Korean (2026년 10월 14일). */
+const MARKED = /^(\d{4})\s*[年년]\s*(\d{1,2})\s*[月월]\s*(\d{1,2})\s*[日일]$/;
 /** The day written day first with dots, as most of Europe writes it: 14.10.2026, 1.10.2026. */
 const DOTTED = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/;
 /** The month named before the day: Oct 14 2026, October 14, 2026, Sept. 1st 2026. */
@@ -58,6 +60,11 @@ export const DATE_OPTION_EXAMPLES = '2026-10-01, 1.10.2026 or "Oct 1 2026"';
 /** The same for a form's date field, typed without quotes. */
 export const DATE_FIELD_EXAMPLES = "2026-10-01, 1.10.2026 or Oct 1 2026";
 
+/** The formats a date option takes, with one more word it reads besides (`latest`): a date, or that word. */
+export function dateOptionFormatsOr(word: string): string {
+  return `${DATE_OPTION_FORMATS.replace(" or ", ", ")} or ${word}`;
+}
+
 /** 1 to 12 for a month's name or its first three letters (Sept too); null for any other word. */
 function monthNumber(name: string): number | null {
   const word = name.toLowerCase();
@@ -66,16 +73,22 @@ function monthNumber(name: string): number | null {
 }
 
 /**
- * A date as people type it, as YYYY-MM-DD: YYYY-MM-DD itself, DD.MM.YYYY
- * (dots are written day first), and the month named on either side of the
- * day (Oct 14 2026, 14 October 2026). Null for anything else, and for a day
- * the calendar does not have. A slash is written both ways round (10/14 in
- * the US, 14/10 in Europe), so a slashed date is never read as one.
+ * A date as people type it, as YYYY-MM-DD: YYYY-MM-DD itself, the year first
+ * with other separators (2026/10/14, 2026.10.14), the year, month and day
+ * marked (2026年10月14日), DD.MM.YYYY (dots after the day are written day
+ * first), and the month named on either side of the day (Oct 14 2026, 14
+ * October 2026). Null for anything else, and for a day the calendar does not
+ * have. A slash after the day or the month is written both ways round (10/14
+ * in the US, 14/10 in Europe), so 10/14/2026 is never read as a date.
  */
 export function readCalendarDate(value: string): string | null {
   const text = value.trim().replace(/\s+/g, " ");
   const iso = ISO_DATE.exec(text);
   if (iso) return calendarDay(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+  const yearFirst = YEAR_FIRST.exec(text);
+  if (yearFirst) return calendarDay(Number(yearFirst[1]), Number(yearFirst[3]), Number(yearFirst[4]));
+  const marked = MARKED.exec(text);
+  if (marked) return calendarDay(Number(marked[1]), Number(marked[2]), Number(marked[3]));
   const dotted = DOTTED.exec(text);
   if (dotted) return calendarDay(Number(dotted[3]), Number(dotted[2]), Number(dotted[1]));
   const monthFirst = MONTH_FIRST.exec(text);
@@ -94,14 +107,11 @@ export function readCalendarDate(value: string): string | null {
 /**
  * The YYYY-MM-DD date that a date written another way plainly names, to
  * offer as the one to type: 14/10/2026 and 10/14/2026 are 2026-10-14, since a
- * part over 12 can only be the day, and 2026/10/14 is too. Null when both
- * parts could be the month (03/04/2026), and for text that is not a date of
- * the calendar.
+ * part over 12 can only be the day. Null when both parts could be the month
+ * (03/04/2026), and for text that is not a date of the calendar.
  */
 function isoDateReading(value: string): string | null {
   const text = value.trim();
-  const yearFirst = YEAR_FIRST.exec(text);
-  if (yearFirst) return calendarDay(Number(yearFirst[1]), Number(yearFirst[3]), Number(yearFirst[4]));
   const yearLast = YEAR_LAST.exec(text);
   if (!yearLast) return null;
   const [first, second, year] = [Number(yearLast[1]), Number(yearLast[3]), Number(yearLast[4])];
@@ -109,6 +119,16 @@ function isoDateReading(value: string): string | null {
   return first <= 12 && second > 12 ? calendarDay(year, first, second) : calendarDay(year, second, first);
 }
 
+/**
+ * What to type instead of a date written another way that plainly names one:
+ * `type --from 2026-10-14 for 14/10/2026`. Null for anything else. `option` is
+ * how the option is typed (`--from`), or empty for a form's field.
+ */
+export function dateOptionHint(value: string, option: string): string | null {
+  const reading = isoDateReading(value);
+  return reading ? `type ${option ? `${option} ` : ""}${reading} for ${value.trim()}` : null;
+}
+
 /**
  * Why a date option's value is no date, naming the formats it takes: with
  * the date to type for one written another way that plainly names it
@@ -125,11 +145,8 @@ export function dateOptionError(
   } = {},
 ): string {
   const format = `Use ${subject} as ${formats}`;
-  const typed = option ? `${option} ` : "";
-  const reading = isoDateReading(value);
-  return reading
-    ? `${format}: type ${typed}${reading} for ${value.trim()}.`
-    : `${format}, such as ${typed}${example ?? isoDateToday(now)}.`;
+  const hint = dateOptionHint(value, option);
+  return hint ? `${format}: ${hint}.` : `${format}, such as ${option ? `${option} ` : ""}${example ?? isoDateToday(now)}.`;
 }
 
 /**

package/src/utils/cash-runway.ts

@@ -0,0 +1,241 @@
+import type { CompanyProfile, FinancialStatement } from "../types/financials";
+import { formatNumber } from "./format";
+import { latestFinancialPeriod } from "./latest-financial-period";
+
+/**
+ * Months of cash: cash and short-term investments at the latest balance sheet
+ * over the cash the operations used per month. One computation behind
+ * `ticker`, the Overview and FA's Liquidity tab.
+ *
+ * The burn is operating cash flow, the line a 10-Q reports for the quarter:
+ * a quarter's over 3 months, the trailing year's over 12. Both are given
+ * because a quarter swings for a company paid in lumps (a collaboration's
+ * upfront payment one quarter, none the next), and the year smooths that.
+ * Positive operating cash flow is no burn. Capital expenditure and financing
+ * are left out: a raise is cash in, not less burn.
+ */
+
+export const QUARTER_MONTHS = 3;
+export const YEAR_MONTHS = 12;
+const MAX_DISPLAY_MONTHS = 120;
+export const SHORT_RUNWAY_HISTORY = "< 4 quarters";
+
+/** Financial firms' operating cash flow includes their financing business, not operating burn. */
+export function excludesCashRunway(profile?: Pick<CompanyProfile, "sector" | "industry">): boolean {
+  return /financ|bank|broker|insur|capital markets/i.test(`${profile?.sector ?? ""} ${profile?.industry ?? ""}`);
+}
+
+/** The method, as the reports state it under the figures; cash alone when no short-term investments are reported. */
+export function runwayMethod(includesShortTerm = true): string {
+  const cash = includesShortTerm ? "cash + ST investments" : "cash (no ST investments reported)";
+  return `Runway: ${cash} over operating cash burn per month (the quarter's operating cash flow ÷ 3, the trailing year's ÷ 12). Values over ${MAX_DISPLAY_MONTHS} months are shown as > ${MAX_DISPLAY_MONTHS} mo.`;
+}
+
+const DAY_MS = 86_400_000;
+/** A fiscal year ending within this many days of a quarter is that quarter's trailing year, as FA reads it. */
+const SAME_PERIOD_END_DAYS = 7;
+
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+export interface RunwayLiquidity {
+  amount: number;
+  /** False when the filer reports no total with short-term investments and the amount is cash alone. */
+  includesShortTerm: boolean;
+}
+
+/** Whether the filer reports cash and short-term investments as a total in any period on file. */
+export function reportsShortTermTotal(statements: Iterable<FinancialStatement>): boolean {
+  for (const statement of statements) if (finite(statement.cashCashEquivalentsAndShortTermInvestments)) return true;
+  return false;
+}
+
+/**
+ * Cash, cash equivalents and short-term investments as reported; cash alone
+ * when the filer reports no such total. A filer that reports it in other
+ * periods (`totalOnFile`) holds short-term investments, so a period without
+ * the total is a missing line: Viking's March 2025 quarter has only its 37.9M
+ * of cash on file, the quarter after 807.7M with its investments.
+ */
+export function cashAndShortTermInvestments(statement: FinancialStatement, totalOnFile = false): RunwayLiquidity | null {
+  if (finite(statement.cashCashEquivalentsAndShortTermInvestments)) {
+    return { amount: statement.cashCashEquivalentsAndShortTermInvestments, includesShortTerm: true };
+  }
+  if (totalOnFile) return null;
+  return finite(statement.cashAndCashEquivalents) ? { amount: statement.cashAndCashEquivalents, includesShortTerm: false } : null;
+}
+
+/** Cash used by operations per month over a period of `months`, or "no-burn" when they brought cash in. */
+export function monthlyOperatingBurn(operatingCashFlow: number | undefined, months: number): number | "no-burn" | undefined {
+  if (!finite(operatingCashFlow)) return undefined;
+  return operatingCashFlow >= 0 ? "no-burn" : -operatingCashFlow / months;
+}
+
+/** Months the cash lasts at a monthly burn above zero; none left is zero months. */
+export function runwayMonths(liquidity: number, monthlyBurn: number): number {
+  return Math.max(0, liquidity) / monthlyBurn;
+}
+
+export type RunwayEstimate =
+  | { kind: "months"; months: number; monthlyBurn: number; operatingCashFlow: number }
+  | { kind: "no-burn"; operatingCashFlow: number };
+
+function estimate(liquidity: number, operatingCashFlow: number | undefined, months: number): RunwayEstimate | null {
+  const burn = monthlyOperatingBurn(operatingCashFlow, months);
+  if (burn === undefined) return null;
+  return burn === "no-burn"
+    ? { kind: "no-burn", operatingCashFlow: operatingCashFlow! }
+    : { kind: "months", months: runwayMonths(liquidity, burn), monthlyBurn: burn, operatingCashFlow: operatingCashFlow! };
+}
+
+const days = (from: string, to: string) => (Date.parse(to) - Date.parse(from)) / DAY_MS;
+
+/**
+ * Operating cash flow over the year to a quarter, as FA's quarterly columns
+ * read a trailing flow: the fiscal year when one ends with the quarter,
+ * otherwise the four consecutive quarters to it summed. Distinguishes a short
+ * history from a missing operating cash flow line.
+ */
+function trailingOperatingCashFlowValue(
+  quarter: FinancialStatement,
+  quarterlyStatements: readonly FinancialStatement[],
+  annualStatements: readonly FinancialStatement[],
+): number | "short-history" | "not-reported" {
+  const year = annualStatements.find((candidate) => (
+    Math.abs(days(quarter.date, candidate.date)) <= SAME_PERIOD_END_DAYS
+    && (!candidate.currency || !quarter.currency || candidate.currency === quarter.currency)
+  ));
+  if (year) return finite(year.operatingCashFlow) ? year.operatingCashFlow : "not-reported";
+  const sorted = [...quarterlyStatements].sort((a, b) => a.date.localeCompare(b.date));
+  const index = sorted.findIndex((statement) => statement.date === quarter.date);
+  if (index < 3) return "short-history";
+  const four = sorted.slice(index - 3, index + 1);
+  // Four rows need not cover twelve months: a skipped quarter or a half-year report is not a year.
+  for (let at = 1; at < four.length; at += 1) {
+    const gap = days(four[at - 1]!.date, four[at]!.date);
+    if (!Number.isFinite(gap) || gap < 60 || gap > 120) return "short-history";
+  }
+  if (new Set(four.map((statement) => statement.currency)).size > 1) return "short-history";
+  const flows = four.map((statement) => statement.operatingCashFlow);
+  return flows.every(finite) ? flows.reduce((sum, value) => sum + value, 0) : "not-reported";
+}
+
+export function trailingOperatingCashFlow(
+  quarter: FinancialStatement,
+  quarterlyStatements: readonly FinancialStatement[],
+  annualStatements: readonly FinancialStatement[],
+): number | null {
+  const flow = trailingOperatingCashFlowValue(quarter, quarterlyStatements, annualStatements);
+  return typeof flow === "number" ? flow : null;
+}
+
+export interface CashRunway {
+  /** The balance sheet's date: the latest quarter's end. */
+  periodEnd: string;
+  currency?: string;
+  liquidity: number;
+  includesShortTerm: boolean;
+  /** At the latest quarter's burn. */
+  quarter: RunwayEstimate | null;
+  /** At the trailing year's burn. */
+  trailing: RunwayEstimate | null;
+  trailingGap?: "short-history" | "not-reported";
+}
+
+/**
+ * Runway at the latest quarter's balance sheet. Null without a quarter, its
+ * cash (or its total with short-term investments, for a filer that reports
+ * one elsewhere), or any operating cash flow to measure a burn by.
+ */
+export function cashRunway({ quarterlyStatements, annualStatements, profile }: {
+  quarterlyStatements: readonly FinancialStatement[];
+  annualStatements: readonly FinancialStatement[];
+  profile?: Pick<CompanyProfile, "sector" | "industry">;
+}): CashRunway | null {
+  if (excludesCashRunway(profile)) return null;
+  const quarter = latestFinancialPeriod(quarterlyStatements, (row) => row.date);
+  if (!quarter) return null;
+  const liquidity = cashAndShortTermInvestments(quarter, reportsShortTermTotal([...quarterlyStatements, ...annualStatements]));
+  if (!liquidity) return null;
+  const quarterly = estimate(liquidity.amount, quarter.operatingCashFlow, QUARTER_MONTHS);
+  const trailingFlow = trailingOperatingCashFlowValue(quarter, quarterlyStatements, annualStatements);
+  const trailing = estimate(liquidity.amount, typeof trailingFlow === "number" ? trailingFlow : undefined, YEAR_MONTHS);
+  if (!quarterly && !trailing) return null;
+  return {
+    periodEnd: quarter.date,
+    ...(quarter.currency ? { currency: quarter.currency } : {}),
+    liquidity: liquidity.amount,
+    includesShortTerm: liquidity.includesShortTerm,
+    quarter: quarterly,
+    trailing,
+    ...(typeof trailingFlow === "string" ? { trailingGap: trailingFlow } : {}),
+  };
+}
+
+/** "12.0 months", to the tenth FA's runway rows show. */
+export function formatRunwayMonths(months: number, unit = "months"): string {
+  return months > MAX_DISPLAY_MONTHS ? `> ${MAX_DISPLAY_MONTHS} mo` : `${formatNumber(months, 1)}${unit ? ` ${unit}` : ""}`;
+}
+
+/** Whether either burn measure finds the company using cash. */
+export function burnsCash(runway: CashRunway | null | undefined): runway is CashRunway {
+  return runway?.quarter?.kind === "months" || runway?.trailing?.kind === "months";
+}
+
+/** A prospectus for an offering that raises cash: a shelf takedown (424B5) or an underwritten offering (424B4). */
+const OFFERING_FORMS = ["424B5", "424B4"] as const;
+
+export interface OfferingFiling {
+  form: string;
+  /** YYYY-MM-DD */
+  filed: string;
+  /** Two prospectuses on one day are two offerings (shares and convertible notes). */
+  accessionNumber?: string;
+}
+
+/**
+ * Offering prospectuses filed on or after a balance sheet's date, oldest first:
+ * cash the balance sheet, and a runway on it, do not include yet.
+ */
+export function offeringsAfter(filings: readonly OfferingFiling[], periodEnd: string): OfferingFiling[] {
+  return filings
+    .map((filing) => ({ ...filing, form: filing.form.trim().toUpperCase().replace(/\/A$/, ""), filed: filing.filed.slice(0, 10) }))
+    .filter((filing) => (OFFERING_FORMS as readonly string[]).includes(filing.form) && filing.filed >= periodEnd)
+    .sort((a, b) => a.filed.localeCompare(b.filed));
+}
+
+const MAX_NOTED_DATES = 3;
+
+/** "424B5 offering filed 2026-09-23 and 2026-09-25, after the 2026-06-30 balance sheet; cash and runway predate it." */
+export function offeringNote(offerings: readonly OfferingFiling[], periodEnd: string): string | null {
+  if (offerings.length === 0) return null;
+  const forms = [...new Set(offerings.map((filing) => filing.form))].join("/");
+  const allDates = [...new Set(offerings.map((filing) => filing.filed))].sort();
+  const dates = allDates.slice(-MAX_NOTED_DATES);
+  const omitted = allDates.length - dates.length;
+  const earlier = omitted ? ` (${omitted} earlier ${omitted === 1 ? "date" : "dates"} omitted)` : "";
+  const relation = allDates.includes(periodEnd) ? "on or after" : "after";
+  const when = dates.length === 1 ? dates[0] : `${dates.slice(0, -1).join(", ")} and ${dates.at(-1)}`;
+  return `${forms} offering filed ${when}${earlier}, ${relation} the ${periodEnd} balance sheet; cash and runway predate it.`;
+}
+
+interface OfferingFilingsClient {
+  getCloudSecFilings(params: { ticker: string; forms?: readonly string[]; limit?: number }, options?: { signal?: AbortSignal }): Promise<{
+    filings: Array<{ form: string; filingDate: string; accessionNumber?: string }>;
+  }>;
+}
+
+const OFFERING_FILING_LIMIT = 10;
+
+/** A US company's latest offering prospectuses, newest first. */
+export async function fetchOfferingFilings(client: OfferingFilingsClient, ticker: string, signal?: AbortSignal): Promise<OfferingFiling[]> {
+  const { filings } = await client.getCloudSecFilings({ ticker, forms: OFFERING_FORMS, limit: OFFERING_FILING_LIMIT }, signal ? { signal } : undefined);
+  // A server that predates the form filter sends every form: offeringsAfter keeps the offerings.
+  return filings.flatMap((filing) => {
+    if (!filing || typeof filing.form !== "string" || typeof filing.filingDate !== "string"
+      || !/^\d{4}-\d{2}-\d{2}(?:$|T)/.test(filing.filingDate)) return [];
+    const filed = filing.filingDate.slice(0, 10);
+    const parsed = new Date(filed);
+    if (!Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== filed) return [];
+    return [{ form: filing.form, filed, ...(typeof filing.accessionNumber === "string" ? { accessionNumber: filing.accessionNumber } : {}) }];
+  });
+}

package/src/utils/central-banks.ts

@@ -69,6 +69,48 @@ export function centralBankNamed(query: string): CentralBank | null {
   return CENTRAL_BANKS.find((bank) => centralBankNames(bank).some((name) => nameKey(name) === wanted)) ?? null;
 }
 
+/** Words a query puts beside a bank's name when it asks for its policy rate: "Bank of Japan rate", "ECB rate decision", "Fed funds rate". */
+const POLICY_RATE_WORDS = new Set([
+  "rate", "rates", "policy", "interest", "decision", "decisions", "meeting", "meetings", "target", "funds",
+  "cash", "repo", "key", "base", "deposit", "benchmark", "official", "overnight", "hike", "hikes", "cut", "cuts",
+  "monetary", "current", "latest", "today",
+]);
+
+/** Where `name` sits in `words` as whole words, or -1. */
+function wordsIndex(words: readonly string[], name: readonly string[]): number {
+  for (let start = 0; start + name.length <= words.length; start += 1) {
+    if (name.every((word, offset) => words[start + offset] === word)) return start;
+  }
+  return -1;
+}
+
+/**
+ * The bank a query asks about: named on its own (`centralBankNamed`), or by
+ * a name with words that ask for its policy rate around it ("bank of japan
+ * rate", "Federal Reserve rate", "BOE base rate"), or its jurisdiction with
+ * "policy rate" or "interest rate" ("Japan policy rate"). Null for anything
+ * else, a name inside a longer phrase ("Bank of Japan bonds").
+ */
+export function centralBankAskedAbout(query: string): CentralBank | null {
+  const named = centralBankNamed(query);
+  if (named) return named;
+  const words = nameKey(query).split(" ").filter(Boolean);
+  let found: { bank: CentralBank; length: number } | null = null;
+  for (const bank of CENTRAL_BANKS) {
+    const names = centralBankNames(bank).map((name) => ({ words: nameKey(name).split(" "), place: false }));
+    for (const name of [...names, { words: nameKey(bank.place).split(" "), place: true }]) {
+      const start = wordsIndex(words, name.words);
+      if (start < 0 || (found && found.length >= name.words.length)) continue;
+      const rest = [...words.slice(0, start), ...words.slice(start + name.words.length)];
+      if (rest.length === 0 || !rest.every((word) => POLICY_RATE_WORDS.has(word))) continue;
+      // A country with a rate ("Japan rate") may be its currency or bonds; a policy or interest rate is the bank's.
+      if (name.place && !rest.includes("policy") && !rest.includes("interest")) continue;
+      found = { bank, length: name.words.length };
+    }
+  }
+  return found?.bank ?? null;
+}
+
 /** The bank whose board row reads a FRED series (DFEDTARU is the Fed's), else null. */
 export function centralBankCiting(fredSeriesId: string): CentralBank | null {
   const wanted = fredSeriesId.trim().toUpperCase();