alphacouncil-agent 0.9.4 → 1.0.1

package/mcp/lib/xbrl-aggregates.mjs

@@ -0,0 +1,153 @@
+/**
+ * Fiscal-year aggregates assembled from an aligned XBRL series.
+ *
+ * These answer "what does this filer report for year N", not "is that good". Debt is summed
+ * from non-overlapping buckets and names the ones a filer omits; tangible book deducts what
+ * is tagged and records the reading when a concept is absent from the whole document; the
+ * trailing-four-quarters window checks its own seams. Each returns null rather than zero when
+ * the filings do not support the figure -- a company with unknown debt is not a debt-free one.
+ */
+
+import {
+  DEBT_BUCKETS,
+  FUNDAMENTAL_CONCEPTS,
+  alignYear,
+  daysBetween,
+  decimal,
+  fiscalYearOf,
+  gap,
+} from "./xbrl-series.mjs";
+
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+/**
+ * Both endpoints on one profit basis. Pairing a NOPAT endpoint with a net-income endpoint
+ * would difference two different quantities and call the result a return.
+ */
+/** Four contiguous quarters ending at `index`, or null when a quarter is missing or overlaps. */
+/**
+ * Profit for the incremental-return window: NOPAT when the tax inputs exist, otherwise net
+ * income -- and the basis is named in the output rather than left for the reader to guess.
+ */
+/**
+ * Tangible book value: equity less goodwill and intangibles.
+ *
+ * A filer with goodwill on its balance sheet must tag it, so a concept absent from every
+ * period of the document is evidence of nil rather than a data gap -- and that reading is
+ * still written into `assumptions`. A concept reported in other years but not this one is
+ * treated as a genuine misalignment and refuses to compute.
+ */
+/**
+ * Total debt for one fiscal year.
+ *
+ * A single combined tag wins outright. Otherwise the three non-overlapping buckets are summed
+ * and the ones a filer does not report are named in `missing_buckets` rather than assumed
+ * away silently. No bucket at all is null, never zero: a company with unknown debt is not a
+ * debt-free company.
+ */
+export function totalDebtForYear(series, fiscalYear) {
+  const combined = series.debt_combined.find((entry) => entry.fiscal_year === fiscalYear);
+  if (combined) {
+    return { value: combined.value, entries: [combined], buckets: ["debt_combined"], missing_buckets: [] };
+  }
+  const present = DEBT_BUCKETS
+    .map((bucket) => ({ bucket, entry: series[bucket].find((item) => item.fiscal_year === fiscalYear) }))
+    .filter((item) => item.entry);
+  if (!present.length) return null;
+  return {
+    value: sum(present.map((item) => item.entry.value)),
+    entries: present.map((item) => item.entry),
+    buckets: present.map((item) => item.bucket),
+    missing_buckets: DEBT_BUCKETS.filter((bucket) => !present.some((item) => item.bucket === bucket)),
+  };
+}
+
+export function tangibleBookForYear(series, fiscalYear) {
+  const equity = series.equity.find((entry) => entry.fiscal_year === fiscalYear);
+  if (!equity) return null;
+  const deductions = [];
+  const assumptions = [];
+  const entries = [equity];
+  for (const concept of ["goodwill", "intangibles"]) {
+    const entry = series[concept].find((item) => item.fiscal_year === fiscalYear);
+    if (entry) {
+      deductions.push({ concept, tag: entry.tag, value: entry.value });
+      entries.push(entry);
+      continue;
+    }
+    if (series[concept].length) return { misaligned: concept };
+    assumptions.push(`${concept} is not tagged in any period of this filer's Company Facts and is treated as 0`);
+  }
+  return {
+    value: equity.value - sum(deductions.map((item) => item.value)),
+    equity: equity.value,
+    deductions,
+    assumptions,
+    entries,
+  };
+}
+
+export function profitForYear(series, fiscalYear) {
+  const nopat = alignYear(series, ["operating_income", "tax_expense", "pretax_income"], fiscalYear);
+  if (nopat.ok && nopat.entries.pretax_income.value > 0) {
+    const rate = nopat.entries.tax_expense.value / nopat.entries.pretax_income.value;
+    if (rate >= 0 && rate < 1) {
+      return {
+        basis: "nopat",
+        value: nopat.entries.operating_income.value * (1 - rate),
+        effective_tax_rate: decimal(rate),
+        entries: nopat.used,
+      };
+    }
+  }
+  const netIncome = series.net_income.find((entry) => entry.fiscal_year === fiscalYear);
+  if (!netIncome) return null;
+  return { basis: "net_income", value: netIncome.value, effective_tax_rate: null, entries: [netIncome] };
+}
+
+export function fourQuarters(quarters, index) {
+  if (index < 3) return null;
+  const window = quarters.slice(index - 3, index + 1);
+  const span = daysBetween(window[0].start, window.at(-1).end);
+  if (span < 330 || span > 400) return null;
+  for (let position = 1; position < window.length; position += 1) {
+    const seam = daysBetween(window[position - 1].end, window[position].start);
+    if (seam < -5 || seam > 15) return null;
+  }
+  return { total: sum(window.map((entry) => entry.val)), window };
+}
+
+export function matchedProfits(series, startYear, endYear) {
+  const profits = [startYear, endYear].map((year) => profitForYear(series, year));
+  if (profits.some((profit) => !profit)) return null;
+  if (profits.every((profit) => profit.basis === "nopat")) return { basis: "nopat", profits };
+  const fallback = [startYear, endYear]
+    .map((year) => series.net_income.find((entry) => entry.fiscal_year === year));
+  if (fallback.some((entry) => !entry)) return null;
+  return {
+    basis: "net_income",
+    profits: fallback.map((entry) => ({ basis: "net_income", value: entry.value, entries: [entry] })),
+  };
+}
+
+export function investedCapital(series, fiscalYear) {
+  const alignment = alignYear(series, ["equity", "cash"], fiscalYear);
+  if (!alignment.ok) return null;
+  const debt = totalDebtForYear(series, fiscalYear);
+  if (!debt) return null;
+  return {
+    value: alignment.entries.equity.value + debt.value - alignment.entries.cash.value,
+    period_end: alignment.period_end,
+    entries: [...alignment.used, ...debt.entries],
+  };
+}
+
+export function ebitdaForYear(series, fiscalYear) {
+  const alignment = alignYear(series, ["operating_income", "depreciation_amortisation"], fiscalYear);
+  if (!alignment.ok) return null;
+  return {
+    value: alignment.entries.operating_income.value + alignment.entries.depreciation_amortisation.value,
+    entries: alignment.used,
+  };
+}

package/mcp/lib/xbrl-series.mjs

@@ -0,0 +1,341 @@
+/**
+ * XBRL series plumbing shared by every derived fundamental.
+ *
+ * Nothing here knows what a metric means. It answers four mechanical questions about SEC
+ * Company Facts documents -- which periods exist for a concept, which of them align, when the
+ * newest input became public, and how a computed number is packaged with its lineage -- and
+ * `fundamentals.mjs` builds the operating figures on top. Separating them keeps the alignment
+ * rules in one place: a metric that quietly aligned differently from its neighbours would be
+ * the kind of defect no test asks about.
+ *
+ * All network access goes through sec.mjs, which owns the throttle and the User-Agent.
+ */
+
+import { CONCEPTS, annualSeries } from "./sec.mjs";
+import { sha256 } from "./personas-v3/canonical.mjs";
+
+export const TOOL_ID = "sec_fundamentals";
+export const TOOL_VERSION = "1.0.0";
+const HASH_DOMAIN = "alphacouncil.fundamentals.sec-companyfacts.v1";
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+export const decimal = (value) => Number(value.toFixed(6));
+const DAY_MS = 86_400_000;
+export const daysBetween = (from, to) => Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
+
+/** Two facts claiming the same period may not disagree by more than this. */
+export const MAX_ALIGNMENT_DRIFT_DAYS = 45;
+
+/**
+ * Concept aliases, ordered by preference, on top of the ones sec.mjs already publishes.
+ *
+ * Aliases inside one entry are the same economic quantity under different taxonomies. They
+ * are never a fallback to a different concept: total liabilities is not reconstructed from
+ * an equity subtraction, and a missing depreciation tag stays missing.
+ */
+export const FUNDAMENTAL_CONCEPTS = Object.freeze({
+  revenue: { tags: CONCEPTS.revenue, unit: "USD" },
+  net_income: { tags: CONCEPTS.netIncome, unit: "USD" },
+  operating_income: { tags: CONCEPTS.operatingIncome, unit: "USD" },
+  capex: { tags: CONCEPTS.capex, unit: "USD" },
+  equity: { tags: CONCEPTS.equity, unit: "USD" },
+  depreciation_amortisation: {
+    tags: [
+      "DepreciationDepletionAndAmortization",
+      "DepreciationAmortizationAndAccretionNet",
+      "DepreciationAndAmortization",
+      "Depreciation",
+    ],
+    unit: "USD",
+  },
+  current_assets: { tags: ["AssetsCurrent"], unit: "USD" },
+  total_liabilities: { tags: ["Liabilities"], unit: "USD" },
+  goodwill: { tags: ["Goodwill"], unit: "USD" },
+  intangibles: { tags: ["IntangibleAssetsNetExcludingGoodwill", "FiniteLivedIntangibleAssetsNet"], unit: "USD" },
+  cash: {
+    tags: [
+      "CashAndCashEquivalentsAtCarryingValue",
+      "CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents",
+    ],
+    unit: "USD",
+  },
+  // Debt buckets are non-overlapping by construction so they can be summed. `debt_combined`
+  // is the whole of it in one tag and wins outright when a filer publishes it.
+  debt_combined: { tags: ["DebtLongtermAndShorttermCombinedAmount"], unit: "USD" },
+  debt_long_term_noncurrent: { tags: ["LongTermDebtNoncurrent", "LongTermDebtAndCapitalLeaseObligations"], unit: "USD" },
+  debt_long_term_current: { tags: ["LongTermDebtCurrent", "LongTermDebtAndCapitalLeaseObligationsCurrent"], unit: "USD" },
+  debt_short_term: { tags: ["ShortTermBorrowings", "OtherShortTermBorrowings", "CommercialPaper"], unit: "USD" },
+  tax_expense: { tags: ["IncomeTaxExpenseBenefit"], unit: "USD" },
+  pretax_income: {
+    tags: [
+      "IncomeLossFromContinuingOperationsBeforeIncomeTaxesExtraordinaryItemsNoncontrollingInterest",
+      "IncomeLossFromContinuingOperationsBeforeIncomeTaxesMinorityInterestAndIncomeLossFromEquityMethodInvestments",
+    ],
+    unit: "USD",
+  },
+  diluted_shares: {
+    tags: ["WeightedAverageNumberOfDilutedSharesOutstanding", "WeightedAverageNumberOfDilutedSharesOutstandingBasicAndDiluted"],
+    // Share concepts are filed under `shares`, not USD. Asking for USD returns nothing, which
+    // is how the screen's dilution rule once reported "skipped" for every company alive.
+    unit: "shares",
+  },
+});
+
+export const DEBT_BUCKETS = Object.freeze(["debt_long_term_noncurrent", "debt_long_term_current", "debt_short_term"]);
+
+/** A date-only SEC field becomes an explicit UTC instant; anything unparseable becomes null. */
+export function toInstant(value) {
+  if (typeof value !== "string" || value.length < 10) return null;
+  const time = Date.parse(value.length === 10 ? `${value}T00:00:00.000Z` : value);
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+
+/** The fiscal year a period belongs to, taken from its end date -- the sec.mjs convention. */
+export const fiscalYearOf = (end) => Number(String(end).slice(0, 4));
+
+/* -------------------------------------------------------------- series and alignment -- */
+
+/** One concept's annual history, flattened the way screen.mjs flattens it. */
+export function conceptSeries(companyFacts, concept, asOf) {
+  const spec = FUNDAMENTAL_CONCEPTS[concept];
+  const found = annualSeries(companyFacts, spec.tags, { asOf, unit: spec.unit });
+  if (!found) return [];
+  return found.series.map((entry) => Object.freeze({
+    concept,
+    tag: entry.tag || found.tag,
+    unit: spec.unit,
+    start: entry.start || null,
+    end: entry.end,
+    filed: entry.filed || null,
+    accession: entry.accn || null,
+    value: entry.val,
+    fiscal_year: fiscalYearOf(entry.end),
+  }));
+}
+
+export function loadSeries(companyFacts, asOf) {
+  return Object.freeze(Object.fromEntries(Object.keys(FUNDAMENTAL_CONCEPTS)
+    .map((concept) => [concept, conceptSeries(companyFacts, concept, asOf)])));
+}
+
+/**
+ * Quarterly history for a concept. sec.mjs only merges annual periods, so this mirrors its
+ * rules for ~quarter-length durations: alias preference decides a period, a later filing of
+ * the same alias supersedes an earlier one, and nothing filed after `asOf` is visible.
+ */
+export function quarterlySeries(companyFacts, tags, { asOf = null, unit = "USD" } = {}) {
+  const cutoff = asOf ? new Date(asOf).getTime() : null;
+  const byEnd = new Map();
+  for (const tag of tags) {
+    const entries = companyFacts?.facts?.["us-gaap"]?.[tag]?.units?.[unit];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry.form !== "10-Q" && entry.form !== "10-K") continue;
+      if (!entry.start || !entry.end || !Number.isFinite(entry.val)) continue;
+      const days = daysBetween(entry.start, entry.end);
+      if (days < 80 || days > 100) continue;
+      if (cutoff && new Date(entry.filed).getTime() > cutoff) continue;
+      const prior = byEnd.get(entry.end);
+      if (!prior) {
+        byEnd.set(entry.end, { ...entry, tag });
+      } else if (prior.tag === tag && new Date(entry.filed) > new Date(prior.filed)) {
+        byEnd.set(entry.end, { ...entry, tag });
+      }
+    }
+  }
+  if (!byEnd.size) return null;
+  return [...byEnd.values()].sort((left, right) => Date.parse(left.end) - Date.parse(right.end));
+}
+
+/** The newest filing instant across a set of entries -- the moment the metric became public. */
+export function publicInstant(entries) {
+  const instants = entries.map((entry) => toInstant(entry.filed)).filter(Boolean);
+  if (instants.length !== entries.length) return null;
+  return instants.sort().at(-1);
+}
+
+/**
+ * The most recent fiscal year in which every named concept has a value.
+ *
+ * Aligning matters more than it looks: pairing this year's net income with last year's
+ * balance sheet because one tag stopped being filed is exactly the stale-period carry-forward
+ * this module exists to refuse.
+ */
+export function alignLatest(series, concepts) {
+  const missing = concepts.filter((concept) => !series[concept]?.length);
+  if (missing.length) return { ok: false, reason: "missing_tag", missing };
+
+  const byYear = concepts.map((concept) => new Map(series[concept].map((entry) => [entry.fiscal_year, entry])));
+  const shared = [...byYear[0].keys()].filter((year) => byYear.every((map) => map.has(year)));
+  if (!shared.length) return { ok: false, reason: "no_common_period", missing: [] };
+
+  const fiscalYear = Math.max(...shared);
+  const entries = concepts.map((concept, index) => byYear[index].get(fiscalYear));
+  return finishAlignment(entries, concepts, fiscalYear);
+}
+
+/** The same alignment, pinned to a stated fiscal year rather than to the newest one. */
+export function alignYear(series, concepts, fiscalYear) {
+  const picked = concepts.map((concept) => series[concept]?.find((entry) => entry.fiscal_year === fiscalYear));
+  const missing = concepts.filter((concept, index) => !picked[index]);
+  if (missing.length) return { ok: false, reason: "no_common_period", missing };
+  return finishAlignment(picked, concepts, fiscalYear);
+}
+
+export function finishAlignment(entries, concepts, fiscalYear) {
+  const ends = entries.map((entry) => Date.parse(entry.end));
+  if (Math.max(...ends) - Math.min(...ends) > MAX_ALIGNMENT_DRIFT_DAYS * DAY_MS) {
+    return { ok: false, reason: "period_misaligned", missing: [] };
+  }
+  const publicAt = publicInstant(entries);
+  if (!publicAt) return { ok: false, reason: "missing_filing_date", missing: [] };
+
+  const starts = entries.map((entry) => entry.start).filter(Boolean).sort();
+  return {
+    ok: true,
+    fiscal_year: fiscalYear,
+    period_start: starts[0] || null,
+    period_end: entries.map((entry) => entry.end).sort().at(-1),
+    public_at: publicAt,
+    entries: Object.fromEntries(concepts.map((concept, index) => [concept, entries[index]])),
+    used: entries,
+  };
+}
+
+/** Merge alignments that must describe the same balance sheet or the same fiscal year. */
+export function combineAlignments(alignments) {
+  const ends = alignments.map((alignment) => Date.parse(alignment.period_end));
+  if (Math.max(...ends) - Math.min(...ends) > MAX_ALIGNMENT_DRIFT_DAYS * DAY_MS) {
+    return { ok: false, reason: "period_misaligned", missing: [] };
+  }
+  const used = alignments.flatMap((alignment) => alignment.used);
+  const starts = used.map((entry) => entry.start).filter(Boolean).sort();
+  return {
+    ok: true,
+    fiscal_year: Math.max(...alignments.map((alignment) => alignment.fiscal_year)),
+    period_start: starts[0] || null,
+    period_end: alignments.map((alignment) => alignment.period_end).sort().at(-1),
+    public_at: alignments.map((alignment) => alignment.public_at).sort().at(-1),
+    entries: Object.assign({}, ...alignments.map((alignment) => alignment.entries)),
+    used,
+  };
+}
+
+/* ------------------------------------------------------------------------------- gaps -- */
+
+export const tagsFor = (concepts) => concepts.flatMap((concept) => FUNDAMENTAL_CONCEPTS[concept]?.tags || []);
+
+export function gap({ factId, component = null, code, detail, missingTags = [] }) {
+  return Object.freeze({
+    metric: factId,
+    component,
+    code,
+    detail,
+    missing_tags: Object.freeze([...missingTags]),
+  });
+}
+
+/** Turn a failed alignment into a gap that names the concept and every tag that was tried. */
+export function alignmentGap(factId, alignment, concepts, component = null) {
+  if (alignment.reason === "missing_tag" || (alignment.reason === "no_common_period" && alignment.missing.length)) {
+    const missingTags = tagsFor(alignment.missing);
+    return gap({
+      factId,
+      component,
+      code: alignment.reason,
+      detail: alignment.reason === "missing_tag"
+        ? `no XBRL tag for ${alignment.missing.join(", ")} in Company Facts (tried ${missingTags.join(", ")})`
+        : `${alignment.missing.join(", ")} is not reported for the aligned fiscal year`,
+      missingTags,
+    });
+  }
+  const detail = {
+    no_common_period: `no fiscal year in which all of ${concepts.join(", ")} are reported together`,
+    period_misaligned: `${concepts.join(", ")} disagree on the period end by more than ${MAX_ALIGNMENT_DRIFT_DAYS} days`,
+    missing_filing_date: `an input carries no filing date, so public_at cannot be taken from the filing`,
+  }[alignment.reason] || `inputs unavailable for ${concepts.join(", ")}`;
+  return gap({ factId, component, code: alignment.reason, detail, missingTags: tagsFor(concepts) });
+}
+
+/* --------------------------------------------------------------------- metric factory -- */
+
+const CONFIDENCE = Object.freeze({ reported: 0.95, rederived: 0.9, estimated: 0.6 });
+
+export function sourceRecords(entries) {
+  const seen = new Set();
+  const records = [];
+  for (const entry of entries) {
+    const key = `${entry.tag}:${entry.accession || entry.filed}:${entry.end}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    records.push(Object.freeze({
+      concept: entry.concept,
+      tag: entry.tag,
+      accession: entry.accession,
+      filed: entry.filed,
+      period_end: entry.end,
+      unit: entry.unit,
+      value: entry.value,
+    }));
+  }
+  return Object.freeze(records);
+}
+
+/**
+ * `sec:companyfacts:<cik>:<tag>:<accession|filed>:<period_end>` -- the identity the typed-fact
+ * adapter already knows how to parse back into a filing locator.
+ */
+export function sourceIds(cik, entries) {
+  return Object.freeze([...new Set(sourceRecords(entries)
+    .map((record) => `sec:companyfacts:${cik}:${record.tag}:${record.accession || record.filed}:${record.period_end}`))]);
+}
+
+export function buildMetric({
+  factId,
+  valueKind,
+  value,
+  unit,
+  currency = null,
+  scale = null,
+  ratioDenominator = null,
+  alignment,
+  cik,
+  derivation,
+  inputs,
+  assumptions,
+  components = null,
+}) {
+  const derived = derivation !== "reported";
+  const parameters = { hash_domain: HASH_DOMAIN, fact_id: factId, tool_id: TOOL_ID, tool_version: TOOL_VERSION };
+  return Object.freeze({
+    fact_id: factId,
+    value_kind: valueKind,
+    value,
+    unit,
+    currency,
+    scale,
+    ratio_denominator: ratioDenominator,
+    // A metric may declare itself a point-in-time quantity, in which case the span its inputs
+    // were aligned over is not the period it covers and stating one would be wrong.
+    period_start: alignment.suppressInterval ? null : alignment.period_start,
+    period_end: alignment.suppressInterval ? null : alignment.period_end,
+    fiscal_year: Number.isInteger(alignment.fiscal_year) ? alignment.fiscal_year : null,
+    // Never the clock: the newest filing among the inputs is the moment this became knowable.
+    public_at: alignment.public_at,
+    derivation,
+    confidence: CONFIDENCE[derivation],
+    source_ids: sourceIds(cik, alignment.used),
+    source_records: sourceRecords(alignment.used),
+    inputs: Object.freeze(inputs),
+    components: components ? Object.freeze(components) : null,
+    assumptions: Object.freeze([...assumptions]),
+    tool_id: derived ? TOOL_ID : null,
+    tool_version: derived ? TOOL_VERSION : null,
+    // A reported figure is not a calculation, so it carries no calculation hash -- which is
+    // exactly what the typed-fact contract requires of `derivation: "reported"`.
+    calculation_hash: derived ? sha256({ ...parameters, inputs, assumptions, value }) : null,
+  });
+}
+
+/* -------------------------------------------------------------- shared derived pieces -- */
+

package/mcp/lib/xlsx.mjs

@@ -0,0 +1,155 @@
+/**
+ * Read an .xlsx with Node built-ins and nothing else.
+ *
+ * An xlsx is a ZIP of XML parts, and `zlib.inflateRawSync` is enough to open one. Extracted
+ * from the fund adapter because it has no fund-domain knowledge at all: any publisher that
+ * ships a workbook -- issuer holdings, an academic dataset -- reads through the same three
+ * steps. Adding a spreadsheet dependency to a zero-dependency package is not worth it for
+ * what fits in a hundred lines.
+ *
+ * Everything unusual fails closed. This reads the ordinary single-workbook shape; it is not a
+ * general ZIP implementation and must not quietly behave like one.
+ */
+
+import { inflateRawSync } from "node:zlib";
+
+/**
+ * Minimal ZIP central-directory reader.
+ *
+ * An xlsx is a ZIP of XML parts, and `zlib.inflateRawSync` is enough to read one, so a workbook is
+ * readable without adding a dependency. Entries are located through the CENTRAL directory
+ * rather than the local headers on purpose: when the archive uses a data descriptor, the
+ * local header's sizes are zeroed and only the central directory is truthful.
+ *
+ * Everything unusual fails closed. This reads the one archive shape SSGA publishes; it is not
+ * a general ZIP implementation and must not silently behave like one.
+ */
+export function unzip(buffer) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+  if (buf.length < 22 || buf.readUInt32LE(0) !== 0x04034b50) {
+    throw new Error("response is not a ZIP/xlsx container");
+  }
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= 0; i -= 1) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error("xlsx container has no end-of-central-directory record");
+  if (buf.readUInt16LE(eocd + 10) === 0xffff) throw new Error("ZIP64 xlsx containers are not supported");
+
+  const count = buf.readUInt16LE(eocd + 10);
+  let offset = buf.readUInt32LE(eocd + 16);
+  const entries = new Map();
+  for (let i = 0; i < count; i += 1) {
+    if (offset + 46 > buf.length || buf.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("xlsx central directory is malformed");
+    }
+    const flags = buf.readUInt16LE(offset + 8);
+    const method = buf.readUInt16LE(offset + 10);
+    const compressedSize = buf.readUInt32LE(offset + 20);
+    const nameLen = buf.readUInt16LE(offset + 28);
+    const extraLen = buf.readUInt16LE(offset + 30);
+    const commentLen = buf.readUInt16LE(offset + 32);
+    const localOffset = buf.readUInt32LE(offset + 42);
+    const name = buf.toString("utf8", offset + 46, offset + 46 + nameLen);
+    if (flags & 0x0001) throw new Error(`xlsx entry ${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw new Error(`xlsx entry ${name} uses unsupported compression method ${method}`);
+    const localNameLen = buf.readUInt16LE(localOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localOffset + 28);
+    const start = localOffset + 30 + localNameLen + localExtraLen;
+    const raw = buf.subarray(start, start + compressedSize);
+    entries.set(name, () => (method === 0 ? raw : inflateRawSync(raw)).toString("utf8"));
+    offset += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+const XML_ENTITIES = Object.freeze({ "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&amp;": "&" });
+const unescapeXml = (text) => String(text).replace(/&(?:lt|gt|quot|apos|amp);/gu, (m) => XML_ENTITIES[m]);
+
+/** Concatenate every <t> inside an element: a shared string may be split into rich-text runs. */
+export const xmlText = (fragment) => {
+  let out = "";
+  for (const match of String(fragment).matchAll(/<t[^>]*>([\s\S]*?)<\/t>/gu)) out += match[1];
+  return unescapeXml(out);
+};
+
+/** "AB12" -> 27. Cells are addressed, not ordered: empty cells are simply absent. */
+export const columnIndex = (ref) => {
+  const letters = /^([A-Z]+)/u.exec(String(ref || "").toUpperCase());
+  if (!letters) return -1;
+  return [...letters[1]].reduce((acc, ch) => acc * 26 + (ch.charCodeAt(0) - 64), 0) - 1;
+};
+
+export function xlsxRows(sheetXml, sharedStrings) {
+  const rows = [];
+  for (const rowMatch of sheetXml.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/gu)) {
+    const cells = [];
+    for (const cellMatch of rowMatch[1].matchAll(/<c\s+r="([A-Z]+\d+)"([^>]*)>([\s\S]*?)<\/c>/gu)) {
+      const index = columnIndex(cellMatch[1]);
+      if (index < 0) continue;
+      const type = /t="([^"]+)"/u.exec(cellMatch[2])?.[1] || "n";
+      const body = cellMatch[3];
+      const value = /<v>([\s\S]*?)<\/v>/u.exec(body)?.[1];
+      if (type === "s") cells[index] = sharedStrings[Number(value)] ?? null;
+      else if (type === "inlineStr") cells[index] = xmlText(/<is>([\s\S]*?)<\/is>/u.exec(body)?.[1] || "");
+      else cells[index] = value === undefined ? null : unescapeXml(value);
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * Open a workbook: every sheet's rows, plus the date system its serials are counted in.
+ *
+ * The date system is not optional detail. A workbook written by Mac Excel sets
+ * `date1904="1"` and its serials sit 1,462 days from the default epoch -- read with the wrong
+ * one, every date is silently four years and a day early, which looks entirely plausible and
+ * is how a current dataset gets mistaken for a stale one.
+ *
+ * Callers locate their header row by content rather than by offset: publishers move the table
+ * when the surrounding label and disclosure rows change length.
+ */
+export function readWorkbook(buffer) {
+  const entries = unzip(buffer);
+  const workbookPart = entries.get("xl/workbook.xml");
+  const date1904 = workbookPart ? /date1904\s*=\s*"(?:1|true)"/iu.test(workbookPart()) : false;
+  const sharedPart = entries.get("xl/sharedStrings.xml");
+  const sharedStrings = sharedPart
+    ? [...sharedPart().matchAll(/<si>([\s\S]*?)<\/si>/gu)].map((match) => xmlText(match[1]))
+    : [];
+  const sheets = [...entries.keys()]
+    .filter((name) => /^xl\/worksheets\/[^/]+\.xml$/u.test(name))
+    .sort()
+    .map((name) => ({ name, rows: xlsxRows(entries.get(name)(), sharedStrings) }));
+  if (!sheets.length) throw new Error("workbook contains no worksheet part");
+  return { date1904, sheets };
+}
+
+/**
+ * Excel serial date to ISO, honouring the workbook's date system.
+ *
+ * In the default 1900 system day 1 is 1900-01-01 and the format wrongly treats 1900 as a leap
+ * year, so serials at or above 60 carry an extra day that has to come back out. The 1904
+ * system has neither quirk.
+ */
+export function excelSerialToIso(serial, { date1904 = false } = {}) {
+  const value = Number(serial);
+  if (!Number.isFinite(value) || value < 0) return null;
+  const epoch = date1904 ? Date.UTC(1904, 0, 1) : Date.UTC(1899, 11, 31);
+  const days = date1904 ? value : (value >= 60 ? value - 1 : value);
+  return new Date(epoch + (days * 86400000)).toISOString().slice(0, 10);
+}
+
+export function readWorkbookRows(buffer, { sheetPath = null } = {}) {
+  const entries = unzip(buffer);
+  const sharedPart = entries.get("xl/sharedStrings.xml");
+  const sharedStrings = sharedPart
+    ? [...sharedPart().matchAll(/<si>([\s\S]*?)<\/si>/gu)].map((match) => xmlText(match[1]))
+    : [];
+  const target = sheetPath
+    || [...entries.keys()].find((name) => /^xl\/worksheets\/sheet1\.xml$/u.test(name))
+    || [...entries.keys()].find((name) => /^xl\/worksheets\/.+\.xml$/u.test(name));
+  if (!target) throw new Error("workbook contains no worksheet part");
+  return xlsxRows(entries.get(target)(), sharedStrings);
+}