@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/usage.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Unit tests for the usage helpers (src/usage.ts).
+ *
+ * Everything here runs against the injectable `UsageFs` seam — no real disk
+ * I/O — so we can (a) synthesize trees with symlinks/missing dirs and (b)
+ * count how many times the dir-walk actually runs, which is how we prove the
+ * TTL cache skips the walk on a hit.
+ *
+ * The path helpers (`vaultDir`, `assetsDir`, mirror resolution) DO read
+ * `process.env.PARACHUTE_HOME`; we point it at a tmp dir so the resolved paths
+ * are deterministic, but no files are written there — the fake fs intercepts
+ * every stat/readdir.
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const testDir = join(
+  tmpdir(),
+  `vault-usage-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+);
+process.env.PARACHUTE_HOME = testDir;
+
+const {
+  dbBytes,
+  dirSize,
+  UsageCache,
+  buildUsageReport,
+} = await import("./usage.ts");
+const { vaultDir, assetsDir } = await import("./config.ts");
+
+import type { UsageFs } from "./usage.ts";
+import type { VaultStats } from "../core/src/types.ts";
+import type { Dirent } from "fs";
+
+// ---------------------------------------------------------------------------
+// Fake filesystem builder
+//
+// A node is either a file (number = size in bytes), a dir (object mapping
+// names → nodes), or a symlink (special marker, never followed).
+// ---------------------------------------------------------------------------
+
+type FileNode = { kind: "file"; size: number };
+type DirNode = { kind: "dir"; children: Record<string, FsNode> };
+type LinkNode = { kind: "link" };
+type FsNode = FileNode | DirNode | LinkNode;
+
+const file = (size: number): FileNode => ({ kind: "file", size });
+const dir = (children: Record<string, FsNode>): DirNode => ({ kind: "dir", children });
+const link = (): LinkNode => ({ kind: "link" });
+
+function makeDirent(name: string, node: FsNode): Dirent {
+  return {
+    name,
+    isFile: () => node.kind === "file",
+    isDirectory: () => node.kind === "dir",
+    isSymbolicLink: () => node.kind === "link",
+    isBlockDevice: () => false,
+    isCharacterDevice: () => false,
+    isFIFO: () => false,
+    isSocket: () => false,
+  } as unknown as Dirent;
+}
+
+/**
+ * Build a fake `UsageFs` rooted at a set of absolute paths. `roots` maps an
+ * absolute path → the node that lives there. Lookups resolve a requested
+ * absolute path by walking from the matching root prefix. `readCount` exposes
+ * how many `readDir` calls happened (for cache assertions).
+ */
+function makeFakeFs(roots: Record<string, FsNode>): UsageFs & { readCount: number } {
+  function resolve(path: string): FsNode | undefined {
+    // Exact root match first.
+    if (roots[path]) return roots[path];
+    // Otherwise find the root that's a prefix and descend by segment.
+    for (const [rootPath, rootNode] of Object.entries(roots)) {
+      if (path === rootPath) return rootNode;
+      if (path.startsWith(rootPath + "/")) {
+        const rest = path.slice(rootPath.length + 1).split("/");
+        let cur: FsNode | undefined = rootNode;
+        for (const seg of rest) {
+          if (!cur || cur.kind !== "dir") return undefined;
+          cur = cur.children[seg];
+        }
+        return cur;
+      }
+    }
+    return undefined;
+  }
+
+  const fs = {
+    readCount: 0,
+    statFile(path: string) {
+      const node = resolve(path);
+      if (!node) throw new Error(`ENOENT: ${path}`);
+      return {
+        size: node.kind === "file" ? node.size : 0,
+        isDirectory: () => node.kind === "dir",
+        isSymbolicLink: () => node.kind === "link",
+      };
+    },
+    readDir(path: string): Dirent[] {
+      fs.readCount++;
+      const node = resolve(path);
+      if (!node || node.kind !== "dir") throw new Error(`ENOTDIR: ${path}`);
+      return Object.entries(node.children).map(([name, child]) => makeDirent(name, child));
+    },
+  };
+  return fs;
+}
+
+// ---------------------------------------------------------------------------
+// dbBytes — sums the WAL trio (vault.db + -wal + -shm)
+// ---------------------------------------------------------------------------
+
+describe("dbBytes (WAL-aware DB file sizing)", () => {
+  const VAULT = "journal";
+  const dbBase = join(vaultDir(VAULT), "vault.db");
+
+  test("sums vault.db + vault.db-wal + vault.db-shm", () => {
+    const fs = makeFakeFs({
+      [dbBase]: file(4096),
+      [`${dbBase}-wal`]: file(800),
+      [`${dbBase}-shm`]: file(32),
+    });
+    expect(dbBytes(VAULT, fs)).toBe(4096 + 800 + 32);
+  });
+
+  test("tolerates missing -wal/-shm (checkpointed at rest)", () => {
+    const fs = makeFakeFs({ [dbBase]: file(4096) });
+    // -wal and -shm absent → contribute 0, not an error.
+    expect(dbBytes(VAULT, fs)).toBe(4096);
+  });
+
+  test("missing DB entirely → 0", () => {
+    const fs = makeFakeFs({});
+    expect(dbBytes(VAULT, fs)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dirSize — recursive, missing-dir tolerant, symlink-safe
+// ---------------------------------------------------------------------------
+
+describe("dirSize (recursive directory byte sum)", () => {
+  const ROOT = "/fake/assets";
+
+  test("sums files across nested directories", () => {
+    const fs = makeFakeFs({
+      [ROOT]: dir({
+        "a.png": file(100),
+        "2026-06-03": dir({
+          "x.jpg": file(250),
+          nested: dir({ "y.pdf": file(50) }),
+        }),
+      }),
+    });
+    expect(dirSize(ROOT, fs)).toBe(100 + 250 + 50);
+  });
+
+  test("empty directory → 0", () => {
+    const fs = makeFakeFs({ [ROOT]: dir({}) });
+    expect(dirSize(ROOT, fs)).toBe(0);
+  });
+
+  test("missing directory → 0 (no throw)", () => {
+    const fs = makeFakeFs({});
+    expect(dirSize(ROOT, fs)).toBe(0);
+  });
+
+  test("does NOT follow symlinks (file or dir)", () => {
+    const fs = makeFakeFs({
+      [ROOT]: dir({
+        "real.png": file(100),
+        "linked-file": link(), // would be a file if followed
+        "linked-dir": link(), // would be a dir if followed
+      }),
+      // A target tree the symlink "points at" — if dirSize followed the link
+      // it would walk this and add 9999. It must NOT.
+      [join(ROOT, "linked-dir")]: dir({ "huge.bin": file(9999) }),
+    });
+    expect(dirSize(ROOT, fs)).toBe(100);
+  });
+
+  test("symlink loop does not hang (link is skipped, never descended)", () => {
+    // The classic infinite-walk trap: a dir containing a symlink to itself.
+    // Because we skip symlinks outright, this terminates immediately.
+    const fs = makeFakeFs({
+      [ROOT]: dir({
+        "f.png": file(10),
+        loop: link(),
+      }),
+    });
+    expect(dirSize(ROOT, fs)).toBe(10);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// UsageCache — 60s TTL, fresh bypass, invalidation, call-count proof
+// ---------------------------------------------------------------------------
+
+describe("UsageCache (dir-walk TTL cache)", () => {
+  const VAULT = "journal";
+  const assets = assetsDir(VAULT);
+
+  function fsWith(assetsBytes: number) {
+    return makeFakeFs({ [assets]: dir({ "a.png": file(assetsBytes) }) });
+  }
+
+  test("first read walks (cached:false); second read within TTL is cached (no walk)", () => {
+    const fs = fsWith(500);
+    let clock = 1_000;
+    const cache = new UsageCache(fs, () => clock, 60_000);
+
+    const first = cache.get(VAULT);
+    expect(first.cached).toBe(false);
+    expect(first.result.assets).toBe(500);
+    const afterFirst = fs.readCount;
+    expect(afterFirst).toBeGreaterThan(0);
+
+    clock += 30_000; // within the 60s TTL
+    const second = cache.get(VAULT);
+    expect(second.cached).toBe(true);
+    expect(second.result.assets).toBe(500);
+    // The cache MUST NOT have re-walked — call count is unchanged.
+    expect(fs.readCount).toBe(afterFirst);
+  });
+
+  test("entry expires after TTL → re-walks (cached:false)", () => {
+    const fs = fsWith(500);
+    let clock = 1_000;
+    const cache = new UsageCache(fs, () => clock, 60_000);
+
+    cache.get(VAULT); // prime
+    const afterPrime = fs.readCount;
+
+    clock += 60_001; // just past TTL
+    const stale = cache.get(VAULT);
+    expect(stale.cached).toBe(false);
+    expect(fs.readCount).toBeGreaterThan(afterPrime);
+  });
+
+  test("fresh:true bypasses a valid cache entry and re-walks", () => {
+    const fs = fsWith(500);
+    let clock = 1_000;
+    const cache = new UsageCache(fs, () => clock, 60_000);
+
+    cache.get(VAULT); // prime
+    const afterPrime = fs.readCount;
+
+    clock += 1_000; // well within TTL — a normal read would be cached
+    const forced = cache.get(VAULT, { fresh: true });
+    expect(forced.cached).toBe(false);
+    expect(fs.readCount).toBeGreaterThan(afterPrime);
+  });
+
+  test("invalidate() forces the next read to re-walk", () => {
+    const fs = fsWith(500);
+    let clock = 1_000;
+    const cache = new UsageCache(fs, () => clock, 60_000);
+
+    cache.get(VAULT); // prime
+    const afterPrime = fs.readCount;
+
+    cache.invalidate(VAULT);
+    clock += 1_000; // within TTL, but the entry is gone
+    const after = cache.get(VAULT);
+    expect(after.cached).toBe(false);
+    expect(fs.readCount).toBeGreaterThan(afterPrime);
+  });
+
+  test("no mirror configured → mirror:null (omitted from report)", () => {
+    // No mirror-config.yaml written for this vault → resolveVaultMirrorDir
+    // returns null → mirror is null.
+    const fs = fsWith(500);
+    const cache = new UsageCache(fs, () => 1_000, 60_000);
+    const { result } = cache.get(VAULT);
+    expect(result.mirror).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildUsageReport — shape + total math + mirror handling
+// ---------------------------------------------------------------------------
+
+describe("buildUsageReport", () => {
+  const VAULT = "journal";
+  const dbBase = join(vaultDir(VAULT), "vault.db");
+  const assets = assetsDir(VAULT);
+
+  function makeStats(overrides: Partial<VaultStats> = {}): VaultStats {
+    return {
+      totalNotes: 12,
+      earliestNote: null,
+      latestNote: null,
+      notesByMonth: [],
+      topTags: [],
+      tagCount: 4,
+      attachmentCount: 3,
+      linkCount: 7,
+      contentBytes: 1234,
+      ...overrides,
+    };
+  }
+
+  test("full shape: counts, bytes, total = db + assets, mirror omitted when none", () => {
+    const fs = makeFakeFs({
+      [dbBase]: file(4096),
+      [`${dbBase}-wal`]: file(900),
+      [assets]: dir({ "a.png": file(2000) }),
+    });
+    const cache = new UsageCache(fs, () => 1_000, 60_000);
+    const report = buildUsageReport(VAULT, makeStats(), { cache, fs, now: () => 1_700_000_000_000 });
+
+    expect(report.counts).toEqual({ notes: 12, attachments: 3, links: 7, tags: 4 });
+    expect(report.bytes.content).toBe(1234);
+    expect(report.bytes.db).toBe(4096 + 900);
+    expect(report.bytes.assets).toBe(2000);
+    // total = db + assets only. NOT content (logical, already inside db) and
+    // NOT mirror (projection).
+    expect(report.bytes.total).toBe(4096 + 900 + 2000);
+    expect(report.bytes).not.toHaveProperty("mirror");
+    expect(report.cached).toBe(false);
+    expect(report.computedAt).toBe(new Date(1_700_000_000_000).toISOString());
+  });
+
+  test("mirror is a separate line item, NOT added to total", () => {
+    // Configure an internal mirror so resolveVaultMirrorDir returns a dir.
+    const { writeMirrorConfigForVault, defaultMirrorConfig } = require("./mirror-config.ts");
+    writeMirrorConfigForVault(VAULT, { ...defaultMirrorConfig(), location: "internal", enabled: true });
+    const mirrorDir = join(vaultDir(VAULT), "mirror");
+
+    const fs = makeFakeFs({
+      [dbBase]: file(1000),
+      [assets]: dir({ "a.png": file(500) }),
+      [mirrorDir]: dir({ "note.md": file(8000) }),
+    });
+    const cache = new UsageCache(fs, () => 1_000, 60_000);
+    const report = buildUsageReport(VAULT, makeStats(), { cache, fs });
+
+    expect(report.bytes.mirror).toBe(8000);
+    // total stays db + assets — the 8000-byte mirror does not inflate it.
+    expect(report.bytes.total).toBe(1000 + 500);
+  });
+
+  test("cached flag reflects a cache hit", () => {
+    const fs = makeFakeFs({
+      [dbBase]: file(100),
+      [assets]: dir({}),
+    });
+    let clock = 1_000;
+    const cache = new UsageCache(fs, () => clock, 60_000);
+
+    const first = buildUsageReport(VAULT, makeStats(), { cache, fs });
+    expect(first.cached).toBe(false);
+
+    clock += 5_000;
+    const second = buildUsageReport(VAULT, makeStats(), { cache, fs });
+    expect(second.cached).toBe(true);
+  });
+});

package/src/usage.ts

@@ -0,0 +1,318 @@
+/**
+ * Per-vault usage monitoring — a cheap, read-scoped "how big is this vault"
+ * report (data footprint). Built for running many vaults for many users: the
+ * operator needs to see each vault's size, and a vault's own user should be
+ * able to see their own vault's footprint.
+ *
+ * The endpoint that consumes these helpers lives in `routing.ts` at
+ * `GET /vault/<name>/.parachute/usage` (read-scoped). This module owns the
+ * filesystem arithmetic and the dir-walk cache.
+ *
+ * Cost model:
+ *   - counts + contentBytes come from `getVaultStats` (a handful of indexed
+ *     COUNT/SUM queries) — cheap, computed on every request.
+ *   - `dbBytes` is three `statSync` calls (the WAL trio) — cheap, every request.
+ *   - the two recursive directory walks (`assets`, `mirror`) can traverse
+ *     thousands of files, so they go through a 60s TTL cache keyed by vault
+ *     name. `?fresh=1` bypasses the cache; an attachment upload invalidates it.
+ *
+ * Everything I/O-touching goes through an injectable `UsageFs` seam + an
+ * injectable clock so tests can assert call counts and TTL behavior without
+ * touching the real disk.
+ */
+
+import {
+  statSync as realStatSync,
+  readdirSync as realReaddirSync,
+  type Dirent,
+} from "fs";
+import { join } from "path";
+import { vaultDir, assetsDir } from "./config.ts";
+import { readMirrorConfigForVault, resolveMirrorPath } from "./mirror-config.ts";
+import type { VaultStats } from "../core/src/types.ts";
+
+// ---------------------------------------------------------------------------
+// Injectable seams
+// ---------------------------------------------------------------------------
+
+/**
+ * The minimal filesystem surface the usage helpers depend on. Injecting it
+ * lets tests count how many times the dir-walk runs (to prove the cache
+ * actually skips it) and synthesize a tree without writing real files.
+ *
+ * Symlink safety lives in the WALK, not in `statFile`: `dirSize` never
+ * descends into or sizes a symlink entry (it filters on
+ * `Dirent.isSymbolicLink()` before ever calling `statFile`), so a symlink
+ * loop can't hang the walk and a symlink pointing at a huge tree elsewhere
+ * can't inflate the count. `statFile` is therefore only ever called on real
+ * files / the WAL trio (which are never symlinks).
+ */
+export interface UsageFs {
+  /**
+   * `stat` (symlink-FOLLOWING, like `statSync`): returns the size of a file
+   * (or throws if absent — callers wrap in try/catch → 0). Following symlinks
+   * is safe here because dir descent already filters symlinks via
+   * `Dirent.isSymbolicLink()`, and the WAL files (`vault.db{,-wal,-shm}`) are
+   * never symlinks.
+   */
+  statFile(path: string): { size: number; isDirectory(): boolean; isSymbolicLink(): boolean };
+  /** `readdirSync(path, { withFileTypes: true })`. */
+  readDir(path: string): Dirent[];
+}
+
+/** Monotonic-enough clock seam: returns epoch millis. */
+export type Clock = () => number;
+
+/** Real filesystem implementation (production default). */
+export const realUsageFs: UsageFs = {
+  statFile: (path) => realStatSync(path),
+  readDir: (path) => realReaddirSync(path, { withFileTypes: true }),
+};
+
+// ---------------------------------------------------------------------------
+// Primitive byte counters
+// ---------------------------------------------------------------------------
+
+/**
+ * Physical bytes of a vault's SQLite database, WAL-aware: `vault.db` +
+ * `vault.db-wal` + `vault.db-shm`. The WAL (write-ahead log) and shared-memory
+ * index files hold committed-but-not-yet-checkpointed pages; ignoring them
+ * undercounts a busy vault. A missing `-wal`/`-shm` (the common case at rest,
+ * after a checkpoint) contributes 0 rather than erroring.
+ *
+ * This is the PHYSICAL DB-file size — it includes SQLite page overhead, free
+ * pages from deletes, etc. It is intentionally distinct from the LOGICAL
+ * `contentBytes` in `VaultStats` (sum of note-content UTF-8 bytes).
+ */
+export function dbBytes(vaultName: string, fs: UsageFs = realUsageFs): number {
+  const base = join(vaultDir(vaultName), "vault.db");
+  const candidates = [base, `${base}-wal`, `${base}-shm`];
+  let total = 0;
+  for (const path of candidates) {
+    total += safeFileSize(path, fs);
+  }
+  return total;
+}
+
+/** Size of a single file, or 0 if it's missing / unreadable. */
+function safeFileSize(path: string, fs: UsageFs): number {
+  try {
+    return fs.statFile(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Recursively sum the size of every regular file under `dirPath`.
+ *
+ *   - Missing directory → 0 (never throws; a vault may have no assets / no
+ *     mirror yet).
+ *   - Symlinks are NOT followed — a symlink (file or dir) is skipped entirely.
+ *     This guards against symlink loops (which would hang an infinite walk)
+ *     and against a symlink that points at a large tree outside the vault
+ *     inflating the reported footprint.
+ *
+ * Uses an explicit stack (not recursion) so a deep tree can't blow the call
+ * stack, and reads dirents with types so we avoid an extra `stat` per entry
+ * just to learn directory-ness.
+ */
+export function dirSize(dirPath: string, fs: UsageFs = realUsageFs): number {
+  let total = 0;
+  const stack: string[] = [dirPath];
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: Dirent[];
+    try {
+      entries = fs.readDir(current);
+    } catch {
+      // Missing/unreadable dir (including the root) → contributes 0.
+      continue;
+    }
+    for (const entry of entries) {
+      // Never follow symlinks — neither symlinked files nor symlinked dirs.
+      if (entry.isSymbolicLink()) continue;
+      const childPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(childPath);
+      } else if (entry.isFile()) {
+        total += safeFileSize(childPath, fs);
+      }
+      // Sockets/FIFOs/devices: ignored.
+    }
+  }
+  return total;
+}
+
+/**
+ * Resolve a vault's mirror directory on disk, or `null` when no mirror is
+ * configured / resolvable (never configured, or external-without-path). The
+ * usage endpoint reports `mirror: 0` (and omits it from the total) in that
+ * case.
+ */
+export function resolveVaultMirrorDir(vaultName: string): string | null {
+  const config = readMirrorConfigForVault(vaultName);
+  if (!config) return null;
+  return resolveMirrorPath(vaultDir(vaultName), config);
+}
+
+// ---------------------------------------------------------------------------
+// Dir-walk cache (the only expensive part)
+// ---------------------------------------------------------------------------
+
+export interface DirWalkResult {
+  /** Bytes under the vault's assets directory. */
+  assets: number;
+  /**
+   * Bytes under the vault's mirror directory, or `null` when no mirror is
+   * configured. `null` → omit `mirror` from the response (or report 0).
+   */
+  mirror: number | null;
+}
+
+interface CacheEntry {
+  value: DirWalkResult;
+  /** Epoch millis when this entry was computed. */
+  computedAt: number;
+}
+
+/** Default cache lifetime for the dir-walk numbers. */
+export const DIR_WALK_TTL_MS = 60_000;
+
+/**
+ * In-process, per-vault cache of the two dir-walk numbers. Module-level so it
+ * survives across requests within a server process. Tests construct their own
+ * `UsageCache` to get isolation + a controllable clock.
+ */
+export class UsageCache {
+  private readonly entries = new Map<string, CacheEntry>();
+
+  constructor(
+    private readonly fs: UsageFs = realUsageFs,
+    private readonly now: Clock = Date.now,
+    private readonly ttlMs: number = DIR_WALK_TTL_MS,
+  ) {}
+
+  /**
+   * Get the dir-walk numbers for a vault. Returns whether the numbers came
+   * from cache (`cached: true`) or were freshly walked (`cached: false`).
+   *
+   *   - `fresh: true` always recomputes (and refreshes the cache entry).
+   *   - Otherwise a non-expired entry is returned as-is (no walk); an absent
+   *     or expired entry triggers a walk + store.
+   */
+  get(vaultName: string, opts: { fresh?: boolean } = {}): { result: DirWalkResult; cached: boolean } {
+    const existing = this.entries.get(vaultName);
+    const ts = this.now();
+    if (!opts.fresh && existing && ts - existing.computedAt < this.ttlMs) {
+      return { result: existing.value, cached: true };
+    }
+    const value = this.compute(vaultName);
+    this.entries.set(vaultName, { value, computedAt: ts });
+    return { result: value, cached: false };
+  }
+
+  /** Drop a vault's cached dir-walk so the next read recomputes. */
+  invalidate(vaultName: string): void {
+    this.entries.delete(vaultName);
+  }
+
+  /** Run the (expensive) walks. */
+  private compute(vaultName: string): DirWalkResult {
+    const assets = dirSize(assetsDir(vaultName), this.fs);
+    const mirrorDir = resolveVaultMirrorDir(vaultName);
+    const mirror = mirrorDir === null ? null : dirSize(mirrorDir, this.fs);
+    return { assets, mirror };
+  }
+}
+
+/**
+ * The process-wide cache the live HTTP route uses. A single instance shared
+ * across requests gives the 60s TTL its meaning. `invalidateUsageCache` is the
+ * write-path hook (attachment upload, post-export).
+ */
+export const usageCache = new UsageCache();
+
+/** Invalidate the process-wide usage cache for a vault (write-path hook). */
+export function invalidateUsageCache(vaultName: string): void {
+  usageCache.invalidate(vaultName);
+}
+
+// ---------------------------------------------------------------------------
+// Report assembly (consumed by the HTTP route)
+// ---------------------------------------------------------------------------
+
+export interface UsageReport {
+  counts: {
+    notes: number;
+    attachments: number;
+    links: number;
+    tags: number;
+  };
+  bytes: {
+    /** Logical: sum of note-content UTF-8 bytes (from VaultStats). */
+    content: number;
+    /** Physical: vault.db + WAL + shm. */
+    db: number;
+    /** Bytes under the vault's assets directory (dir-walk, cached). */
+    assets: number;
+    /**
+     * Bytes under the vault's mirror directory (dir-walk, cached), present
+     * only when a mirror is configured. The mirror is a git PROJECTION of the
+     * same notes/attachments — it is NOT added to `total` (that would
+     * double-count the data); it's reported as a separate line item.
+     */
+    mirror?: number;
+    /**
+     * Physical on-disk footprint (db + assets); excludes content (inside db)
+     * and mirror (separate projection). This is the number an operator sizes a
+     * vault by.
+     */
+    total: number;
+  };
+  /** ISO-8601 timestamp of when this report was assembled. */
+  computedAt: string;
+  /** Whether the dir-walk numbers (assets/mirror) came from cache. */
+  cached: boolean;
+}
+
+/**
+ * Assemble the usage report for a vault. `stats` is the already-computed
+ * `getVaultStats()` result (counts + contentBytes); the cache supplies the two
+ * dir-walk numbers and reports whether they were cached.
+ *
+ * `total = db + assets` — the physical footprint. Mirror is a separate line
+ * item (projection of the same data; adding it double-counts). Content is the
+ * logical note size, already inside `db` physically.
+ */
+export function buildUsageReport(
+  vaultName: string,
+  stats: VaultStats,
+  opts: { fresh?: boolean; cache?: UsageCache; fs?: UsageFs; now?: Clock } = {},
+): UsageReport {
+  const cache = opts.cache ?? usageCache;
+  const { result, cached } = cache.get(vaultName, { fresh: opts.fresh });
+  const db = dbBytes(vaultName, opts.fs ?? realUsageFs);
+  const total = db + result.assets;
+
+  const bytes: UsageReport["bytes"] = {
+    content: stats.contentBytes,
+    db,
+    assets: result.assets,
+    total,
+  };
+  if (result.mirror !== null) bytes.mirror = result.mirror;
+
+  return {
+    counts: {
+      notes: stats.totalNotes,
+      attachments: stats.attachmentCount,
+      links: stats.linkCount,
+      tags: stats.tagCount,
+    },
+    bytes,
+    computedAt: new Date((opts.now ?? Date.now)()).toISOString(),
+    cached,
+  };
+}