mulmoclaude 0.5.2 → 0.6.0

package/server/accounting/snapshotCache.ts

@@ -0,0 +1,333 @@
+// Monthly balance snapshot cache.
+//
+// Source of truth: the journal JSONL files. Snapshots are derived
+// state — `data/accounting/books/<id>/snapshots/YYYY-MM.json` is
+// only ever a perf optimization. The invariant we maintain:
+//
+//   for any (book, period) pair,
+//     getOrBuildSnapshot(book, period)
+//   ===
+//     aggregateBalances(<all entries up to period end>)
+//
+// I.e. running with snapshots and running without snapshots must
+// produce byte-identical results. The unit test for this lives in
+// `test/accounting/test_snapshotCache.ts`.
+//
+// Rebuild policy: writes call `scheduleRebuild(bookId, fromPeriod)`
+// after invalidating stale snapshot files. Each book has at most one
+// rebuild in flight; additional writes during a running rebuild merge
+// into a single queued follow-up (so a burst of N writes runs at most
+// two rebuilds). `getOrBuildSnapshot` keeps a lazy fallback so a
+// report requested before the rebuild reaches that month is still
+// correct — it just builds inline.
+//
+// Test API: `awaitRebuildIdle(bookId)` and `inspectRebuildQueue(bookId)`
+// are diagnostics that let tests assert on queue state without
+// sleep-and-poll. Production code never needs them.
+
+import {
+  invalidateSnapshotsFrom as ioInvalidateFrom,
+  invalidateAllSnapshots as ioInvalidateAll,
+  listJournalPeriods,
+  readJournalMonth,
+  readSnapshot,
+  writeSnapshot,
+} from "../utils/files/accounting-io.js";
+import { aggregateBalances } from "./report.js";
+import { publishBookChange } from "./eventPublisher.js";
+import { log } from "../system/logger/index.js";
+import { ACCOUNTING_BOOK_EVENT_KINDS } from "../../src/config/pubsubChannels.js";
+import type { AccountBalance, JournalEntry, MonthSnapshot } from "./types.js";
+
+function previousPeriod(period: string): string {
+  // YYYY-MM → previous YYYY-MM. December rolls back to the previous
+  // year's December.
+  const [year, month] = period.split("-").map((segment) => parseInt(segment, 10));
+  if (month === 1) return `${(year - 1).toString().padStart(4, "0")}-12`;
+  return `${year.toString().padStart(4, "0")}-${(month - 1).toString().padStart(2, "0")}`;
+}
+
+function mergeBalances(base: readonly AccountBalance[], delta: readonly AccountBalance[]): AccountBalance[] {
+  const map = new Map<string, number>();
+  for (const row of base) map.set(row.accountCode, row.netDebit);
+  for (const row of delta) {
+    map.set(row.accountCode, (map.get(row.accountCode) ?? 0) + row.netDebit);
+  }
+  return Array.from(map.entries())
+    .map(([accountCode, netDebit]) => ({ accountCode, netDebit }))
+    .sort((lhs, rhs) => lhs.accountCode.localeCompare(rhs.accountCode));
+}
+
+async function buildEmptySnapshot(bookId: string, period: string, workspaceRoot?: string): Promise<MonthSnapshot> {
+  const empty: MonthSnapshot = { period, balances: [], builtAt: new Date().toISOString() };
+  await writeSnapshot(bookId, empty, workspaceRoot);
+  return empty;
+}
+
+/** Build a snapshot at end-of-`period` for one book, lazily relying
+ *  on the previous month's snapshot if it exists. Falls all the way
+ *  back to the earliest journal month if no upstream snapshot is
+ *  available. Always writes the result to disk before returning. */
+export async function getOrBuildSnapshot(bookId: string, period: string, workspaceRoot?: string): Promise<MonthSnapshot> {
+  const cached = await readSnapshot(bookId, period, workspaceRoot);
+  if (cached) return cached;
+
+  // Earliest journal month determines where the recursion stops.
+  // If the book has no journal at all, return an empty snapshot.
+  const periods = await listJournalPeriods(bookId, workspaceRoot);
+  if (periods.length === 0 || period < periods[0]) {
+    return buildEmptySnapshot(bookId, period, workspaceRoot);
+  }
+
+  const { entries } = await readJournalMonth(bookId, period, workspaceRoot);
+  const monthDelta = aggregateBalances(entries);
+
+  // Get the prior month's closing snapshot — recurse, which will
+  // either hit cache or build the chain back to the start.
+  let priorBalances: readonly AccountBalance[] = [];
+  if (period > periods[0]) {
+    const prior = previousPeriod(period);
+    const priorSnap = await getOrBuildSnapshot(bookId, prior, workspaceRoot);
+    priorBalances = priorSnap.balances;
+  }
+  const merged = mergeBalances(priorBalances, monthDelta);
+  const snap: MonthSnapshot = {
+    period,
+    balances: merged,
+    builtAt: new Date().toISOString(),
+  };
+  await writeSnapshot(bookId, snap, workspaceRoot);
+  return snap;
+}
+
+/** Compute closing balances at end-of-`period` from journal alone,
+ *  bypassing the snapshot cache. Used by the byte-equality
+ *  invariant test, and as a safety net for "compute without
+ *  trusting cache" paths. */
+export async function balancesAtEndOf(bookId: string, period: string, workspaceRoot?: string): Promise<AccountBalance[]> {
+  const periods = await listJournalPeriods(bookId, workspaceRoot);
+  const all: JournalEntry[] = [];
+  for (const monthKey of periods) {
+    if (period < monthKey) break;
+    const { entries } = await readJournalMonth(bookId, monthKey, workspaceRoot);
+    for (const entry of entries) all.push(entry);
+  }
+  return aggregateBalances(all);
+}
+
+/** Drop snapshots for `fromPeriod` and later. Re-export from
+ *  accounting-io for callers that conceptually live in the cache
+ *  layer (so they don't reach into the IO module). */
+export async function invalidateSnapshotsFrom(bookId: string, fromPeriod: string, workspaceRoot?: string): Promise<{ removed: string[] }> {
+  return ioInvalidateFrom(bookId, fromPeriod, workspaceRoot);
+}
+
+/** Drop all snapshots and rebuild from scratch. Used by the
+ *  `rebuildSnapshots` admin action. Returns the periods that were
+ *  rebuilt. */
+export async function rebuildAllSnapshots(bookId: string, workspaceRoot?: string): Promise<{ rebuilt: string[] }> {
+  await ioInvalidateAll(bookId, workspaceRoot);
+  const periods = await listJournalPeriods(bookId, workspaceRoot);
+  for (const monthKey of periods) {
+    await getOrBuildSnapshot(bookId, monthKey, workspaceRoot);
+  }
+  return { rebuilt: periods };
+}
+
+// ── async rebuild queue ────────────────────────────────────────────
+//
+// Per-book queue. A `running` promise represents the in-flight
+// rebuild. While it's running, additional `scheduleRebuild` calls
+// merge their `fromPeriod` into `pendingFromPeriod` (taking the
+// minimum so the next pass covers everyone's invalidation), and we
+// kick off a follow-up once the current one resolves.
+
+interface RebuildQueueEntry {
+  running: Promise<void>;
+  pendingFromPeriod: string | null;
+  pendingWorkspaceRoot: string | undefined;
+  coalescedWriteCount: number;
+  runningFromPeriod: string;
+  /** Set by `cancelRebuild` (called from `deleteBook`). The runRebuild
+   *  loop checks before each write so a rebuild cannot resurrect the
+   *  book directory after `removeBookDir` has run. */
+  cancelled: boolean;
+}
+
+const rebuildQueues = new Map<string, RebuildQueueEntry>();
+
+function minPeriod(lhs: string | null, rhs: string): string {
+  if (lhs === null) return rhs;
+  return lhs < rhs ? lhs : rhs;
+}
+
+function isInvalidatedDuringRebuild(bookId: string, period: string): boolean {
+  // A pending invalidation that covers `period` means the queued
+  // follow-up rebuild will redo this period. Skip the in-flight
+  // write so we don't pollute the cache with stale data while a
+  // fresher computation is queued. Without this guard, the
+  // sequence "rebuild reads journal → caller writes a new entry →
+  // caller invalidates → rebuild writes (stale) snapshot" leaves
+  // the cache lying about the latest state.
+  const queue = rebuildQueues.get(bookId);
+  return queue !== undefined && queue.pendingFromPeriod !== null && period >= queue.pendingFromPeriod;
+}
+
+function isCancelled(bookId: string): boolean {
+  return rebuildQueues.get(bookId)?.cancelled === true;
+}
+
+async function runRebuild(bookId: string, fromPeriod: string, workspaceRoot: string | undefined): Promise<void> {
+  const startedAt = Date.now();
+  log.info("accounting", "snapshot rebuild started", { bookId, fromPeriod });
+  publishBookChange(bookId, { kind: ACCOUNTING_BOOK_EVENT_KINDS.snapshotsRebuilding, period: fromPeriod });
+  const periods = await listJournalPeriods(bookId, workspaceRoot);
+  const targets = periods.filter((monthKey) => monthKey >= fromPeriod);
+  let written = 0;
+  for (const monthKey of targets) {
+    if (isCancelled(bookId)) break;
+    if (isInvalidatedDuringRebuild(bookId, monthKey)) break;
+    // Compute fresh from journal — bypasses getOrBuildSnapshot's
+    // own write side-effect so the staleness check below is the
+    // only writer in the rebuild path.
+    const balances = await balancesAtEndOf(bookId, monthKey, workspaceRoot);
+    if (isCancelled(bookId)) break;
+    if (isInvalidatedDuringRebuild(bookId, monthKey)) break;
+    await writeSnapshot(bookId, { period: monthKey, balances, builtAt: new Date().toISOString() }, workspaceRoot);
+    if (isCancelled(bookId)) {
+      // The book was deleted between our last check and the write —
+      // `writeSnapshot` will have re-created the book directory tree
+      // via mkdir-recursive. Undo it so we don't leave an orphaned
+      // directory after `deleteBook` has run.
+      await ioInvalidateFrom(bookId, monthKey, workspaceRoot);
+      break;
+    }
+    if (isInvalidatedDuringRebuild(bookId, monthKey)) {
+      // A concurrent invalidate raced ahead between our last check
+      // and the disk write. The data we just wrote may be stale
+      // relative to the latest journal — undo so the queued
+      // follow-up rebuild starts from a clean slate.
+      await ioInvalidateFrom(bookId, monthKey, workspaceRoot);
+      break;
+    }
+    written += 1;
+    publishBookChange(bookId, { kind: ACCOUNTING_BOOK_EVENT_KINDS.snapshotsReady, period: monthKey });
+  }
+  log.info("accounting", "snapshot rebuild done", { bookId, periods: written, durationMs: Date.now() - startedAt });
+}
+
+function startRebuild(bookId: string, fromPeriod: string, workspaceRoot: string | undefined): RebuildQueueEntry {
+  const entry: RebuildQueueEntry = {
+    running: Promise.resolve(),
+    pendingFromPeriod: null,
+    pendingWorkspaceRoot: undefined,
+    coalescedWriteCount: 1,
+    runningFromPeriod: fromPeriod,
+    cancelled: false,
+  };
+  entry.running = runRebuild(bookId, fromPeriod, workspaceRoot)
+    .catch((err) => {
+      // A rebuild failure is logged but does not poison the queue —
+      // the next `scheduleRebuild` call will start a fresh promise.
+      log.error("accounting", "snapshot rebuild failed", { bookId, fromPeriod, error: err instanceof Error ? err.message : String(err) });
+    })
+    .then(() => {
+      // Drain any work that piled up while we were running.
+      const current = rebuildQueues.get(bookId);
+      if (!current) return;
+      // If the book was cancelled mid-rebuild (e.g. deleteBook ran),
+      // drop the queue entry entirely — we must not start a successor
+      // that would re-create the deleted book directory.
+      if (current.cancelled) {
+        rebuildQueues.delete(bookId);
+        return;
+      }
+      if (current.pendingFromPeriod !== null) {
+        const nextFrom = current.pendingFromPeriod;
+        const nextRoot = current.pendingWorkspaceRoot;
+        const carriedCount = current.coalescedWriteCount;
+        const successor = startRebuild(bookId, nextFrom, nextRoot);
+        successor.coalescedWriteCount += carriedCount;
+        rebuildQueues.set(bookId, successor);
+      } else {
+        rebuildQueues.delete(bookId);
+      }
+    });
+  return entry;
+}
+
+/** Schedule a background rebuild for `bookId` starting at `fromPeriod`.
+ *  Multiple calls during an in-flight rebuild coalesce into a single
+ *  follow-up rebuild that covers the minimum `fromPeriod` seen.
+ *  Returns immediately — the rebuild runs on its own promise chain. */
+export function scheduleRebuild(bookId: string, fromPeriod: string, workspaceRoot?: string): void {
+  const existing = rebuildQueues.get(bookId);
+  if (!existing) {
+    rebuildQueues.set(bookId, startRebuild(bookId, fromPeriod, workspaceRoot));
+    return;
+  }
+  existing.pendingFromPeriod = minPeriod(existing.pendingFromPeriod, fromPeriod);
+  existing.pendingWorkspaceRoot = workspaceRoot;
+  existing.coalescedWriteCount += 1;
+}
+
+/** Test/diagnostic: resolves when no rebuild is running or queued for
+ *  `bookId`. Also called by `deleteBook` after `cancelRebuild` to
+ *  ensure a previously running rebuild has fully stopped before the
+ *  caller removes the book's directory on disk. */
+export async function awaitRebuildIdle(bookId: string): Promise<void> {
+  while (rebuildQueues.has(bookId)) {
+    const entry = rebuildQueues.get(bookId);
+    if (!entry) return;
+    await entry.running;
+  }
+}
+
+/** Mark the book's in-flight rebuild as cancelled. The runRebuild
+ *  loop checks before each write and bails out, so a subsequent
+ *  `removeBookDir` cannot race with a `writeSnapshot` that would
+ *  re-create the directory tree. Pair with `awaitRebuildIdle(bookId)`
+ *  to wait for the in-flight rebuild to finish bailing. */
+export function cancelRebuild(bookId: string): void {
+  const entry = rebuildQueues.get(bookId);
+  if (!entry) return;
+  entry.cancelled = true;
+  // Drop pending too — a cancelled book should not get a successor
+  // rebuild after the in-flight one drains.
+  entry.pendingFromPeriod = null;
+}
+
+/** Test/diagnostic: snapshot of the per-book queue state. Stable
+ *  enough to assert against; fields may grow over time. */
+export function inspectRebuildQueue(bookId: string): {
+  running: boolean;
+  runningFromPeriod: string | null;
+  pendingFromPeriod: string | null;
+  coalescedWriteCount: number;
+} {
+  const entry = rebuildQueues.get(bookId);
+  if (!entry) {
+    return { running: false, runningFromPeriod: null, pendingFromPeriod: null, coalescedWriteCount: 0 };
+  }
+  return {
+    running: true,
+    runningFromPeriod: entry.runningFromPeriod,
+    pendingFromPeriod: entry.pendingFromPeriod,
+    coalescedWriteCount: entry.coalescedWriteCount,
+  };
+}
+
+/** Test-only — drain all in-flight rebuilds, then drop queue state.
+ *  Awaiting first means a leftover rebuild can't continue writing
+ *  into the next test's tmp dir after we clear the bookkeeping. */
+export async function _resetRebuildQueueForTesting(): Promise<void> {
+  // Mark everything cancelled so loops bail at their next checkpoint
+  // instead of continuing through every period.
+  for (const entry of rebuildQueues.values()) {
+    entry.cancelled = true;
+    entry.pendingFromPeriod = null;
+  }
+  const pending = Array.from(rebuildQueues.values()).map((entry) => entry.running);
+  await Promise.allSettled(pending);
+  rebuildQueues.clear();
+}

package/server/accounting/timeSeries.ts

@@ -0,0 +1,265 @@
+// Time-series aggregation for the accounting plugin: bucketise a
+// date range by month / fiscal quarter / fiscal year and roll up a
+// metric (revenue / expense / net income / closing balance of a
+// specific account) into a chart-ready `(label, value)[]` series.
+//
+// LLM-facing only — the in-canvas Accounting `<View>` keeps using
+// `getReport` for its tab-driven UI. `getTimeSeries` exists so a
+// single tool round-trip can answer "chart my quarterly revenue
+// over the last two years" without the LLM fanning out N calls and
+// stitching the buckets itself.
+//
+// Pure module: no I/O, no service-layer awareness. Caller hands in
+// the entries / accounts already loaded; we return the points.
+
+import type { Account, AccountType, JournalEntry } from "./types.js";
+import { aggregateBalances } from "./report.js";
+import { fiscalYearEndMonth, type FiscalYearEnd } from "../../src/plugins/accounting/fiscalYear.js";
+import {
+  TIME_SERIES_GRANULARITIES,
+  TIME_SERIES_METRICS,
+  type TimeSeriesGranularity,
+  type TimeSeriesMetric,
+} from "../../src/plugins/accounting/timeSeriesEnums.js";
+
+export { TIME_SERIES_GRANULARITIES, TIME_SERIES_METRICS };
+export type { TimeSeriesGranularity, TimeSeriesMetric };
+
+export interface Bucket {
+  /** Inclusive YYYY-MM-DD lower bound. */
+  from: string;
+  /** Inclusive YYYY-MM-DD upper bound. */
+  to: string;
+  /** Chart x-axis label. Format depends on granularity:
+   *  "YYYY-MM" / "FY{endYear}-Q{1..4}" / "FY{endYear}". For fiscal
+   *  years that don't align with the calendar year (Q1/Q2/Q3 books)
+   *  the FY is named by its END calendar year — matches Japanese
+   *  "令和7年度" convention (Apr 2025 - Mar 2026 = FY2026). */
+  label: string;
+}
+
+export interface TimeSeriesPoint {
+  label: string;
+  from: string;
+  to: string;
+  /** Single number, natural-sign per metric. Revenue and net income
+   *  positive when income exceeds expense; expense reported as a
+   *  positive cost; account balance follows the account's display
+   *  sign (assets debit-positive, liabilities/equity credit-positive). */
+  value: number;
+}
+
+// ── date arithmetic (pure, no Date for parsing/formatting) ─────────
+
+function pad2(num: number): string {
+  return String(num).padStart(2, "0");
+}
+
+function fmtYmd(year: number, month: number, day: number): string {
+  return `${year}-${pad2(month)}-${pad2(day)}`;
+}
+
+interface YmdParts {
+  year: number;
+  month: number;
+  day: number;
+}
+
+function parseYmd(value: string): YmdParts {
+  const [year, month, day] = value.split("-").map((segment) => parseInt(segment, 10));
+  return { year, month, day };
+}
+
+function lastDayOf(year: number, month: number): number {
+  // UTC day 0 of next month = last day of this month, immune to TZ.
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function addDay(date: YmdParts): YmdParts {
+  const stepped = new Date(Date.UTC(date.year, date.month - 1, date.day + 1));
+  return {
+    year: stepped.getUTCFullYear(),
+    month: stepped.getUTCMonth() + 1,
+    day: stepped.getUTCDate(),
+  };
+}
+
+// ── fiscal-year arithmetic (year-month, no Date) ───────────────────
+
+interface FyAnchor {
+  /** Calendar year the fiscal year STARTED in. */
+  fyStartYear: number;
+  /** Calendar year the fiscal year ENDS in (used for labelling). */
+  fyEndYear: number;
+  /** First calendar month of the fiscal year (1-based). */
+  startMonth: number;
+}
+
+function fyAnchorFor(date: YmdParts, end: FiscalYearEnd): FyAnchor {
+  const closingMonth = fiscalYearEndMonth(end);
+  const startMonth = (closingMonth % 12) + 1; // month after the close
+  // FY containing date: started this calendar year if date.month is
+  // at-or-after startMonth, else previous calendar year. Q4 books
+  // (startMonth = 1) always land in the same calendar year — covered
+  // by the same predicate.
+  const fyStartYear = date.month >= startMonth ? date.year : date.year - 1;
+  const fyEndYear = closingMonth === 12 ? fyStartYear : fyStartYear + 1;
+  return { fyStartYear, fyEndYear, startMonth };
+}
+
+// ── per-granularity bucket lookup ──────────────────────────────────
+
+function monthBucketContaining(date: YmdParts): Bucket {
+  return {
+    from: fmtYmd(date.year, date.month, 1),
+    to: fmtYmd(date.year, date.month, lastDayOf(date.year, date.month)),
+    label: `${date.year}-${pad2(date.month)}`,
+  };
+}
+
+function quarterBucketContaining(date: YmdParts, end: FiscalYearEnd): Bucket {
+  const anchor = fyAnchorFor(date, end);
+  const offset = (date.month - anchor.startMonth + 12) % 12; // 0..11
+  const qIdx = Math.floor(offset / 3); // 0..3
+  // Flat month-index from the calendar epoch makes year rollover
+  // arithmetic trivial.
+  const startFlat = anchor.fyStartYear * 12 + (anchor.startMonth - 1) + qIdx * 3;
+  const endFlat = startFlat + 2;
+  const qStartYear = Math.floor(startFlat / 12);
+  const qStartMonth = (startFlat % 12) + 1;
+  const qEndYear = Math.floor(endFlat / 12);
+  const qEndMonth = (endFlat % 12) + 1;
+  return {
+    from: fmtYmd(qStartYear, qStartMonth, 1),
+    to: fmtYmd(qEndYear, qEndMonth, lastDayOf(qEndYear, qEndMonth)),
+    label: `FY${anchor.fyEndYear}-Q${qIdx + 1}`,
+  };
+}
+
+function yearBucketContaining(date: YmdParts, end: FiscalYearEnd): Bucket {
+  const anchor = fyAnchorFor(date, end);
+  const startFlat = anchor.fyStartYear * 12 + (anchor.startMonth - 1);
+  const endFlat = startFlat + 11;
+  const yStartYear = Math.floor(startFlat / 12);
+  const yStartMonth = (startFlat % 12) + 1;
+  const yEndYear = Math.floor(endFlat / 12);
+  const yEndMonth = (endFlat % 12) + 1;
+  return {
+    from: fmtYmd(yStartYear, yStartMonth, 1),
+    to: fmtYmd(yEndYear, yEndMonth, lastDayOf(yEndYear, yEndMonth)),
+    label: `FY${anchor.fyEndYear}`,
+  };
+}
+
+function bucketContaining(date: YmdParts, granularity: TimeSeriesGranularity, end: FiscalYearEnd): Bucket {
+  if (granularity === "month") return monthBucketContaining(date);
+  if (granularity === "quarter") return quarterBucketContaining(date, end);
+  return yearBucketContaining(date, end);
+}
+
+/** Walk inclusive `[from, to]` and return every bucket that overlaps
+ *  it, ordered ascending by `from`. The first bucket is the one
+ *  CONTAINING `from` — it can extend earlier than `from`; the last
+ *  bucket is the one CONTAINING `to` — it can extend past `to`. The
+ *  caller's response echoes the input range so the LLM can label the
+ *  chart truthfully ("Revenue Apr 2025 – Sep 2026" even though the
+ *  outermost buckets cover Apr-Jun 2025 and Jul-Sep 2026). */
+export function bucketize(input: { from: string; to: string; granularity: TimeSeriesGranularity; fiscalYearEnd: FiscalYearEnd }): Bucket[] {
+  if (input.from > input.to) return [];
+  const start = parseYmd(input.from);
+  const result: Bucket[] = [];
+  let bucket = bucketContaining(start, input.granularity, input.fiscalYearEnd);
+  // Buckets are contiguous; once a bucket's `from` is past `input.to`
+  // every subsequent bucket is too.
+  while (bucket.from <= input.to) {
+    result.push(bucket);
+    const next = addDay(parseYmd(bucket.to));
+    bucket = bucketContaining(next, input.granularity, input.fiscalYearEnd);
+  }
+  return result;
+}
+
+// ── value computation ──────────────────────────────────────────────
+
+/** Convert raw netDebit to natural-sign presentation per account
+ *  type. Mirrors the helper in `report.ts` (kept private there). */
+function naturalSign(type: AccountType, netDebit: number): number {
+  if (type === "asset" || type === "expense") return netDebit;
+  return -netDebit;
+}
+
+interface PresentationTotals {
+  income: number;
+  expense: number;
+}
+
+/** Sum presented income and expense values across the supplied
+ *  entries. Used for window-based metrics (revenue / expense /
+ *  netIncome). Opening entries reference B/S accounts only and so
+ *  contribute zero to either total — including them is harmless. */
+function presentedPlTotals(entries: readonly JournalEntry[], accountTypeByCode: ReadonlyMap<string, AccountType>): PresentationTotals {
+  const balances = aggregateBalances(entries);
+  let income = 0;
+  let expense = 0;
+  for (const row of balances) {
+    const type = accountTypeByCode.get(row.accountCode);
+    if (!type) continue;
+    if (type === "income") income += naturalSign(type, row.netDebit);
+    else if (type === "expense") expense += naturalSign(type, row.netDebit);
+  }
+  return { income, expense };
+}
+
+function entriesInWindow(entries: readonly JournalEntry[], from: string, toDate: string): JournalEntry[] {
+  return entries.filter((entry) => entry.date >= from && entry.date <= toDate);
+}
+
+function entriesUpTo(entries: readonly JournalEntry[], toDate: string): JournalEntry[] {
+  return entries.filter((entry) => entry.date <= toDate);
+}
+
+function valueForBucket(input: {
+  bucket: Bucket;
+  entries: readonly JournalEntry[];
+  accounts: readonly Account[];
+  metric: TimeSeriesMetric;
+  accountCode?: string;
+}): number {
+  const accountTypeByCode = new Map(input.accounts.map((acct) => [acct.code, acct.type]));
+  if (input.metric === "accountBalance") {
+    const code = input.accountCode;
+    if (!code) return 0; // guarded at the route — defensive zero.
+    const type = accountTypeByCode.get(code);
+    if (!type) return 0;
+    const cumulative = entriesUpTo(input.entries, input.bucket.to);
+    const balances = aggregateBalances(cumulative);
+    const row = balances.find((balance) => balance.accountCode === code);
+    return row ? naturalSign(type, row.netDebit) : 0;
+  }
+  const window = entriesInWindow(input.entries, input.bucket.from, input.bucket.to);
+  const totals = presentedPlTotals(window, accountTypeByCode);
+  if (input.metric === "revenue") return totals.income;
+  if (input.metric === "expense") return totals.expense;
+  return totals.income - totals.expense; // netIncome
+}
+
+export function buildTimeSeries(input: {
+  buckets: readonly Bucket[];
+  entries: readonly JournalEntry[];
+  accounts: readonly Account[];
+  metric: TimeSeriesMetric;
+  accountCode?: string;
+}): TimeSeriesPoint[] {
+  return input.buckets.map((bucket) => ({
+    label: bucket.label,
+    from: bucket.from,
+    to: bucket.to,
+    value: valueForBucket({
+      bucket,
+      entries: input.entries,
+      accounts: input.accounts,
+      metric: input.metric,
+      accountCode: input.accountCode,
+    }),
+  }));
+}