@openparachute/vault 0.5.1 → 0.5.2-rc.2

package/src/transcription-worker.ts

@@ -25,8 +25,11 @@
  *    (Whisper API shape). Response is `{ text: string }`.
  * 3. On success:
  *    - If `note.metadata.transcribe_stub === true`, replace the
- *      `_Transcript pending._` placeholder with the transcript, or the
- *      whole note body if the placeholder is absent. Clear the stub marker.
+ *      `_Transcript pending._` placeholder (or a prior `_Transcription
+ *      unavailable._` failure marker, on a retry) with the transcript. If
+ *      neither marker is present (user edited the note while pending),
+ *      APPEND the transcript rather than overwriting the body. Clear the
+ *      stub marker.
  *    - Mark `attachment.metadata.transcribe_status = "done"` and record
  *      `transcript` + `transcribe_done_at`.
  *    - If the vault's `audio_retention` is `"until_transcribed"`, unlink
@@ -50,13 +53,13 @@
 
 import { join, normalize } from "path";
 import { existsSync, readFileSync, unlinkSync } from "fs";
-import type { Store, Attachment } from "../core/src/types.ts";
+import type { Store, Attachment, Note } from "../core/src/types.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
 import { appendContextPart, fetchContextEntries, type ContextPayload } from "./context.ts";
 import type { TriggerIncludeContext } from "./config.ts";
 import { upsertTranscriptNote } from "./transcript-note.ts";
 
-/** Placeholder pattern written by Lens's voice-memo stub. */
+/** Placeholder pattern written by the voice-memo capture stub. */
 const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
 
 /**
@@ -65,9 +68,33 @@ const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
  * Lens's now-removed scribe client; owning it here means a failed upload
  * stops reading "Transcript pending" forever regardless of which client
  * uploaded the audio.
+ *
+ * NOTE: the notes-ui status chip (parachute-surface TranscriptionStatus.tsx)
+ * keys off this exact string, so don't change the copy without a coordinated
+ * change there. A friendlier "retry available" copy + chip affordance is a
+ * tracked parachute-surface follow-up.
  */
 const TRANSCRIPT_UNAVAILABLE = "_Transcription unavailable._";
 
+/**
+ * On a successful (re)transcription of a legacy in-body memo, the transcript
+ * replaces whichever marker is currently in the body — the original
+ * `_Transcript pending._` on a first-try success, OR `_Transcription
+ * unavailable._` if a prior attempt failed and we're now retrying. Matching
+ * both means a retried success lands in the same spot a first-try success
+ * would, preserving the surrounding capture body (the `![[memo]]` embed,
+ * the `_Recorded …_` line, the header).
+ *
+ * Deliberately NO `/g` flag — `.replace` swaps only the FIRST match. A
+ * canonical capture body holds exactly one marker, so first-match is the
+ * correct target. `applyFailureMarker`'s includes-guard (no-op when the
+ * marker is already present) prevents markers accumulating across repeated
+ * terminal failures, so the body never carries two of the same marker. A
+ * hand-edited body that somehow contains both markers patches only the
+ * first — accepted (degenerate, operator-induced).
+ */
+const TRANSCRIPT_SUCCESS_TARGET = /_Transcript pending\._|_Transcription unavailable\._/;
+
 /**
  * Default sweep cadence (ms). The sweep is the safety net for backoff-
  * queued items, items that arrived while the server was down, or dispatches
@@ -202,6 +229,100 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
    */
   const inFlightAttachments = new Set<string>();
 
+  /**
+   * Apply a surgical note transform under optimistic concurrency (vault#435).
+   *
+   * The worker's marker/transcript writes are read-modify-write cycles
+   * (`getNote` → transform → `updateNote`). Without a precondition, a user
+   * edit landing between the read and the write is silently clobbered —
+   * the same static-write/stale-read class as vault#208.
+   *
+   * `transform(note)` returns the surgical update to apply (`content` and/or
+   * `metadata`), or `null` when the fresh state means there's nothing to do
+   * (e.g. the stub was cleared, or the marker is already present — the
+   * idempotency guards from #434 live inside the transform, so they re-run
+   * against whatever we re-read). The transform MUST be pure w.r.t. the note
+   * it's handed — it's invoked once per read, and re-invoked on the fresh
+   * read after a conflict.
+   *
+   * Policy on conflict (worker = resilient, never crash the sweep):
+   *   1. First write conflicts → re-read, re-run the transform against fresh
+   *      content, write with the fresh precondition.
+   *   2. Second write also conflicts → fall back to a precondition-less write
+   *      ONLY when `safeWithoutPrecondition(freshNote)` says the transform is
+   *      still safe against the latest content (e.g. the surgical-replace
+   *      target is still present, or an append is always-safe). Otherwise
+   *      skip + log — better to leave the note as the user last left it than
+   *      to blind-overwrite a third concurrent edit.
+   *
+   * All errors are logged + swallowed: a note-write failure must not mask the
+   * attachment-level result we already recorded, nor crash the sweep.
+   */
+  async function applyNoteTransformWithOC(
+    store: Store,
+    noteId: string,
+    op: string,
+    transform: (note: Note) => { content?: string; metadata?: Record<string, unknown> } | null,
+    safeWithoutPrecondition: (note: Note) => boolean,
+  ): Promise<void> {
+    try {
+      const note = await store.getNote(noteId);
+      if (!note) return;
+      const update = transform(note);
+      if (update === null) return;
+
+      try {
+        await store.updateNote(note.id, {
+          ...update,
+          skipUpdatedAt: true,
+          if_updated_at: note.updatedAt,
+        });
+        return;
+      } catch (err: any) {
+        if (!err || err.code !== "CONFLICT") throw err;
+      }
+
+      // Conflict — a user edit landed between read and write. Re-read,
+      // re-apply the same surgical transform against the fresh content, and
+      // write with the fresh precondition.
+      const fresh = await store.getNote(noteId);
+      if (!fresh) return;
+      const reUpdate = transform(fresh);
+      if (reUpdate === null) return;
+
+      try {
+        await store.updateNote(fresh.id, {
+          ...reUpdate,
+          skipUpdatedAt: true,
+          if_updated_at: fresh.updatedAt,
+        });
+        return;
+      } catch (err: any) {
+        if (!err || err.code !== "CONFLICT") throw err;
+      }
+
+      // Double conflict (a third edit raced the retry). Last resort: apply
+      // without a precondition ONLY if the transform is still safe against
+      // the latest content. Otherwise skip — don't clobber the user.
+      const latest = await store.getNote(noteId);
+      if (!latest) return;
+      if (!safeWithoutPrecondition(latest)) {
+        logger.error(
+          `[transcribe] ${op}: note ${noteId} kept changing under us (double conflict); skipping to avoid clobbering a concurrent edit`,
+        );
+        return;
+      }
+      const finalUpdate = transform(latest);
+      if (finalUpdate === null) return;
+      await store.updateNote(latest.id, {
+        ...finalUpdate,
+        skipUpdatedAt: true,
+      });
+    } catch (err) {
+      logger.error(`[transcribe] ${op}: failed to apply to note ${noteId}:`, err);
+    }
+  }
+
   async function processOne(vault: string, attachment: Attachment): Promise<void> {
     // Dedupe: another path (sweep vs hook kick, or a duplicate dispatch)
     // is already working this attachment. Drop — its result is durable
@@ -217,33 +338,58 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
 
   /**
    * On a terminal failure (maxAttempts exhausted, or audio file missing),
-   * swap the stub placeholder for the "unavailable" marker — otherwise
-   * Lens's voice memo sits reading "Transcript pending" forever. Mirrors
-   * the success-path note write in shape: only touches the note when
+   * record the "unavailable" marker on the note — otherwise the voice memo
+   * sits reading "Transcript pending" forever. Only touches the note when
    * `transcribe_stub === true`, clears the stub marker, uses `skipUpdatedAt`
    * so the note's modification time still reflects user intent. Errors
    * are logged and swallowed so a note-write failure doesn't mask the
    * attachment failure we're trying to record.
+   *
+   * Body policy (finding F — never destroy content):
+   *   - Placeholder PRESENT → surgical replace of `_Transcript pending._`
+   *     with the marker. The `![[memo]]` embed + any surrounding text survive.
+   *   - Marker ALREADY PRESENT → no-op (idempotent; a double-terminal-failure
+   *     must not stack markers).
+   *   - Otherwise (placeholder absent — the user edited the note while it was
+   *     pending) → APPEND `\n\n` + marker to the existing content. The old
+   *     code full-replaced the body here, destroying the embed AND the user's
+   *     edits. We append instead so nothing is lost. If the content is empty,
+   *     the marker alone becomes the body (avoids a leading blank line).
    */
   async function applyFailureMarker(store: Store, noteId: string): Promise<void> {
-    const note = await store.getNote(noteId);
-    if (!note) return;
-    const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
-    if (noteMeta.transcribe_stub !== true) return;
-
-    const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
-      ? note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE)
-      : TRANSCRIPT_UNAVAILABLE;
-    const { transcribe_stub: _drop, ...restMeta } = noteMeta;
-    try {
-      await store.updateNote(note.id, {
-        content: body,
-        metadata: restMeta,
-        skipUpdatedAt: true,
-      });
-    } catch (err) {
-      logger.error(`[transcribe] failed to apply failure marker to note ${note.id}:`, err);
-    }
+    // OC-guarded (vault#435): the read-transform-write below is re-run against
+    // fresh content on a conflict so a concurrent user edit isn't clobbered.
+    // The transform is pure w.r.t. the note it's handed; the stub-set and
+    // marker-already-present idempotency guards re-evaluate on the re-read.
+    await applyNoteTransformWithOC(
+      store,
+      noteId,
+      "apply-failure-marker",
+      (note) => {
+        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+        if (noteMeta.transcribe_stub !== true) return null;
+
+        let body: string;
+        if (TRANSCRIPT_PLACEHOLDER.test(note.content)) {
+          body = note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE);
+        } else if (note.content.includes(TRANSCRIPT_UNAVAILABLE)) {
+          // Marker already present — nothing to do. Clear the stub and
+          // return without rewriting the body so we don't stack markers.
+          body = note.content;
+        } else {
+          body = note.content.length > 0
+            ? `${note.content}\n\n${TRANSCRIPT_UNAVAILABLE}`
+            : TRANSCRIPT_UNAVAILABLE;
+        }
+        const { transcribe_stub: _drop, ...restMeta } = noteMeta;
+        return { content: body, metadata: restMeta };
+      },
+      // Last-resort (double-conflict) safety: only blind-write while the note
+      // still carries the stub opt-in. If a racing edit cleared it, the user
+      // opted out — skip rather than re-stamp the marker. The body transform
+      // itself is non-destructive (surgical replace / no-op / append).
+      (note) => ((note.metadata as Record<string, unknown> | undefined)?.transcribe_stub === true),
+    );
   }
 
   /**
@@ -411,26 +557,48 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         logger.error(`[transcribe] failed to write transcript note for attachment ${attachment.id}:`, err);
       }
     } else {
-      // Legacy stub-patching path (Lens voice memo flow).
-      const note = await store.getNote(attachment.noteId);
-      if (note) {
-        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
-        if (noteMeta.transcribe_stub === true) {
-          const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
-            ? note.content.replace(TRANSCRIPT_PLACEHOLDER, transcript)
-            : transcript;
-          const { transcribe_stub: _drop, ...restMeta } = noteMeta;
-          try {
-            await store.updateNote(note.id, {
-              content: body,
-              metadata: restMeta,
-              skipUpdatedAt: true,
-            });
-          } catch (err) {
-            logger.error(`[transcribe] failed to apply transcript to note ${note.id}:`, err);
+      // Legacy stub-patching path (voice memo flow). Only acts when the note
+      // still carries the `transcribe_stub` opt-in — a user edit clearing it
+      // before the transcript arrives opts out of the overwrite. OC-guarded
+      // (vault#435): re-applied against fresh content on a conflict so a
+      // concurrent user edit isn't clobbered.
+      await applyNoteTransformWithOC(
+        store,
+        attachment.noteId,
+        "apply-transcript",
+        (note) => {
+          const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+          if (noteMeta.transcribe_stub !== true) return null;
+          // Body policy (finding F — never destroy content):
+          //   - placeholder OR failure-marker present → surgical replace in
+          //     place (a retried success replaces the `_Transcription
+          //     unavailable._` marker, landing exactly where a first-try
+          //     success would). The embed + surrounding capture body survive.
+          //   - neither present (user edited the note while pending) → APPEND
+          //     the transcript instead of full-replacing the body, so the
+          //     user's edits + the `![[memo]]` embed are preserved. The old
+          //     code full-replaced here, which destroyed both.
+          let body: string;
+          if (TRANSCRIPT_SUCCESS_TARGET.test(note.content)) {
+            // Function replacer, NOT a string — speech-to-text is arbitrary
+            // user content, and String.replace treats `$&`, `$\``, `$'`,
+            // `$1`-`$9` as special patterns in a string replacement. A
+            // transcript containing `$&` would otherwise inject the matched
+            // marker text into the body. `() => transcript` returns the text
+            // verbatim.
+            body = note.content.replace(TRANSCRIPT_SUCCESS_TARGET, () => transcript);
+          } else {
+            body = note.content.length > 0
+              ? `${note.content}\n\n${transcript}`
+              : transcript;
           }
-        }
-      }
+          const { transcribe_stub: _drop, ...restMeta } = noteMeta;
+          return { content: body, metadata: restMeta };
+        },
+        // Last-resort (double-conflict) safety: only blind-write while the
+        // stub opt-in survives. A racing edit that cleared it opts out.
+        (note) => ((note.metadata as Record<string, unknown> | undefined)?.transcribe_stub === true),
+      );
     }
 
     // Always record the transcript on the attachment, even if the note

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);
+  });
+});