@mulmoclaude/accounting-plugin 1.2.0 → 1.2.2

package/dist/server.js

@@ -1,4 +1,4 @@
-import { A as resolveFiscalYearEnd, B as ACCOUNTING_API, D as isFiscalYearEnd, F as ACCOUNTING_BOOKS_CHANNEL, I as BOOK_EVENT_KINDS, L as bookChannel, M as errorMessage, N as isRecord, P as isUnknownArray, R as ACCOUNT_TYPES, S as FISCAL_YEAR_END_MONTHS, T as fiscalYearEndMonth, V as ACCOUNTING_ACTIONS, _ as SUPPORTED_COUNTRY_CODES, j as ACCOUNTING_DIRS, n as TIME_SERIES_METRICS, t as TIME_SERIES_GRANULARITIES, y as isSupportedCountryCode, z as BALANCE_SHEET_ACCOUNT_TYPES } from "./shared-qp9j-GTD.js";
+import { A as resolveFiscalYearEnd, B as BALANCE_SHEET_ACCOUNT_TYPES, D as isFiscalYearEnd, F as isUnknownArray, H as ACCOUNTING_API, I as ACCOUNTING_BOOKS_CHANNEL, L as BOOK_EVENT_KINDS, M as errorMessage, N as hasStringProp, P as isRecord, R as bookChannel, S as FISCAL_YEAR_END_MONTHS, T as fiscalYearEndMonth, U as ACCOUNTING_ACTIONS, V as JOURNAL_ENTRY_KINDS, _ as SUPPORTED_COUNTRY_CODES, j as ACCOUNTING_DIRS, n as TIME_SERIES_METRICS, t as TIME_SERIES_GRANULARITIES, y as isSupportedCountryCode, z as ACCOUNT_TYPES } from "./shared-xYPtGNvH.js";
 import { Router } from "express";
 import { randomUUID } from "node:crypto";
 import { promises } from "node:fs";
@@ -62,254 +62,6 @@ var log = {
 	debug: (namespace, msg, data) => (deps?.logger ?? consoleLogger).debug(namespace, msg, data)
 };
 //#endregion
-//#region src/server/io.ts
-var root = (workspaceRoot) => workspaceRoot ?? defaultWorkspaceRoot();
-function accountingRoot(workspaceRoot) {
-	return path.join(root(workspaceRoot), ACCOUNTING_DIRS.accounting);
-}
-function configPath(workspaceRoot) {
-	return path.join(accountingRoot(workspaceRoot), "config.json");
-}
-/** Allowed shape for a book id used as a directory name. Defense
-*  against path traversal: a crafted id like "../../config" or
-*  "/tmp/x" would otherwise let `bookRoot` escape the
-*  `data/accounting/books/` tree, since every write path joins
-*  `bookId` directly into the filesystem. The first character is
-*  alphanumeric to forbid leading dashes / underscores that some
-*  shells / docs render confusingly; `_` and `-` are allowed inside.
-*  64 chars is plenty for any reasonable book name. */
-var SAFE_BOOK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
-function isSafeBookId(bookId) {
-	return typeof bookId === "string" && SAFE_BOOK_ID_RE.test(bookId);
-}
-function assertSafeBookId(bookId) {
-	if (!isSafeBookId(bookId)) throw new Error(`accounting: invalid bookId ${JSON.stringify(bookId)} (allowed: alphanumeric / _ / -; 1-64 chars; cannot start with _ or -)`);
-}
-function bookRoot(bookId, workspaceRoot) {
-	assertSafeBookId(bookId);
-	return path.join(root(workspaceRoot), ACCOUNTING_DIRS.accountingBooks, bookId);
-}
-function accountsPath(bookId, workspaceRoot) {
-	return path.join(bookRoot(bookId, workspaceRoot), "accounts.json");
-}
-function journalDir(bookId, workspaceRoot) {
-	return path.join(bookRoot(bookId, workspaceRoot), "journal");
-}
-function journalFileFor(bookId, period, workspaceRoot) {
-	return path.join(journalDir(bookId, workspaceRoot), `${period}.jsonl`);
-}
-function snapshotsDir(bookId, workspaceRoot) {
-	return path.join(bookRoot(bookId, workspaceRoot), "snapshots");
-}
-function snapshotFileFor(bookId, period, workspaceRoot) {
-	return path.join(snapshotsDir(bookId, workspaceRoot), `${period}.json`);
-}
-async function fileExists(filePath) {
-	try {
-		await promises.access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/** Strict variant of `readJsonOrNull` from `./json.ts`: returns null
-*  on ENOENT but RETHROWS other read errors and parse failures so a
-*  corrupted accounting journal surfaces rather than silently
-*  collapsing to "no data". `./json.ts` keeps the permissive
-*  variant for user-config files where a single bad keystroke
-*  shouldn't 500 the server. */
-async function readJsonStrict(filePath) {
-	try {
-		const raw = await promises.readFile(filePath, "utf-8");
-		return JSON.parse(raw);
-	} catch (err) {
-		if (isEnoent(err)) return null;
-		throw err;
-	}
-}
-/** Migrate a legacy calendar-quarter `fiscalYearEnd` token ("Q1".."Q4")
-*  to its closing-month number in memory so every downstream consumer
-*  (reports, time-series, the UI selects) sees one shape. Absent stays
-*  absent — the field is optional and resolves to the default on read;
-*  we don't stamp an explicit December onto a book that never chose one.
-*  Nothing is written back here (no auto-migrate on disk). */
-function normalizeBookFiscalYearEnd(book) {
-	if (book.fiscalYearEnd === void 0) return book;
-	const resolved = resolveFiscalYearEnd(book.fiscalYearEnd);
-	return book.fiscalYearEnd === resolved ? book : {
-		...book,
-		fiscalYearEnd: resolved
-	};
-}
-async function readConfig(workspaceRoot) {
-	const config = await readJsonStrict(configPath(workspaceRoot));
-	if (!config) return null;
-	return {
-		...config,
-		books: config.books.map(normalizeBookFiscalYearEnd)
-	};
-}
-async function writeConfig(config, workspaceRoot) {
-	await writeJsonAtomic(configPath(workspaceRoot), config);
-}
-async function readAccounts(bookId, workspaceRoot) {
-	return await readJsonStrict(accountsPath(bookId, workspaceRoot)) ?? [];
-}
-async function writeAccounts(bookId, accounts, workspaceRoot) {
-	await writeJsonAtomic(accountsPath(bookId, workspaceRoot), accounts);
-}
-/** Convert a YYYY-MM-DD date string to its YYYY-MM month bucket. The
-*  month bucket dictates which JSONL file the entry lives in. */
-function periodFromDate(date) {
-	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error(`accounting: invalid date format ${JSON.stringify(date)} (expected YYYY-MM-DD)`);
-	return date.slice(0, 7);
-}
-/** Append one entry to the appropriate month's JSONL.
-*
-*  Uses POSIX append-only semantics (`fs.appendFile` → `O_APPEND`).
-*  Two concurrent callers landing in the same month file are
-*  serialised by the kernel — neither overwrites the other, which
-*  is the bug the previous read-modify-write implementation had.
-*
-*  Crash mid-write: an entry shorter than `PIPE_BUF` (≥ 512 bytes
-*  on every supported platform) writes atomically; a single
-*  serialised `JournalEntry` is comfortably under that. If the
-*  process is killed during the syscall the worst case is a torn
-*  trailing line, which `readJournalMonth` already tolerates by
-*  skipping unparseable lines and surfacing a `skipped` count to
-*  the caller. */
-async function appendJournal(bookId, entry, workspaceRoot) {
-	const file = journalFileFor(bookId, periodFromDate(entry.date), workspaceRoot);
-	await promises.mkdir(path.dirname(file), { recursive: true });
-	await promises.appendFile(file, `${JSON.stringify(entry)}\n`, { encoding: "utf-8" });
-}
-function groupEntriesByPeriod(entries) {
-	const byPeriod = /* @__PURE__ */ new Map();
-	for (const entry of entries) {
-		const period = periodFromDate(entry.date);
-		const list = byPeriod.get(period) ?? [];
-		list.push(entry);
-		byPeriod.set(period, list);
-	}
-	return byPeriod;
-}
-/** Append a batch of entries: same-period entries are concatenated
-*  into one `appendFile` call so the whole same-period chunk hits
-*  the kernel as a single `O_APPEND` write — small chunks (under
-*  `PIPE_BUF`, ≥ 512 bytes on every supported platform) are
-*  guaranteed atomic by POSIX, and `O_APPEND` serialises with any
-*  concurrent appender (a parallel `appendJournal` / `addEntries`
-*  call can never overwrite our write or vice versa). Cross-period
-*  batches loop one append per period; each is independently
-*  concurrency-safe but their union is not transactional across
-*  files (out of scope for the append-only JSONL design). */
-async function appendJournalBatch(bookId, entries, workspaceRoot) {
-	if (entries.length === 0) return;
-	const byPeriod = groupEntriesByPeriod(entries);
-	for (const [period, items] of byPeriod) {
-		const file = journalFileFor(bookId, period, workspaceRoot);
-		await promises.mkdir(path.dirname(file), { recursive: true });
-		const chunk = items.map((entry) => `${JSON.stringify(entry)}\n`).join("");
-		await promises.appendFile(file, chunk, { encoding: "utf-8" });
-	}
-}
-/** Read a single month's JSONL. Malformed lines are skipped (logged
-*  by the caller; this layer just returns the parseable subset) so
-*  one bad line doesn't lock the user out of their book. */
-async function readJournalMonth(bookId, period, workspaceRoot) {
-	const file = journalFileFor(bookId, period, workspaceRoot);
-	let raw;
-	try {
-		raw = await promises.readFile(file, "utf-8");
-	} catch (err) {
-		if (isEnoent(err)) return {
-			entries: [],
-			skipped: 0
-		};
-		throw err;
-	}
-	const entries = [];
-	let skipped = 0;
-	for (const line of raw.split("\n")) {
-		if (line.trim() === "") continue;
-		try {
-			entries.push(JSON.parse(line));
-		} catch {
-			skipped += 1;
-		}
-	}
-	return {
-		entries,
-		skipped
-	};
-}
-/** List the YYYY-MM periods that have a journal file on disk, sorted
-*  ascending. Useful for full-history scans (rebuilding snapshots
-*  from scratch). */
-async function listJournalPeriods(bookId, workspaceRoot) {
-	let names;
-	try {
-		names = await promises.readdir(journalDir(bookId, workspaceRoot));
-	} catch (err) {
-		if (isEnoent(err)) return [];
-		throw err;
-	}
-	return names.filter((name) => /^\d{4}-\d{2}\.jsonl$/.test(name)).map((name) => name.slice(0, 7)).sort();
-}
-async function readSnapshot(bookId, period, workspaceRoot) {
-	return readJsonStrict(snapshotFileFor(bookId, period, workspaceRoot));
-}
-async function writeSnapshot(bookId, snapshot, workspaceRoot) {
-	const file = snapshotFileFor(bookId, snapshot.period, workspaceRoot);
-	await promises.mkdir(path.dirname(file), { recursive: true });
-	await writeJsonAtomic(file, snapshot, { uniqueTmp: true });
-}
-/** Drop snapshot files for all periods >= `fromPeriod`. The next
-*  read regenerates them. Idempotent: missing files are silently
-*  ignored. */
-async function invalidateSnapshotsFrom(bookId, fromPeriod, workspaceRoot) {
-	let names;
-	try {
-		names = await promises.readdir(snapshotsDir(bookId, workspaceRoot));
-	} catch (err) {
-		if (isEnoent(err)) return { removed: [] };
-		throw err;
-	}
-	const removed = [];
-	for (const name of names) {
-		const match = /^(\d{4}-\d{2})\.json$/.exec(name);
-		if (!match) continue;
-		const [, period] = match;
-		if (period >= fromPeriod) {
-			await promises.rm(path.join(snapshotsDir(bookId, workspaceRoot), name), { force: true });
-			removed.push(period);
-		}
-	}
-	return { removed: removed.sort() };
-}
-/** Drop ALL snapshots for a book — used by `rebuildSnapshots()`
-*  with no `from`. Equivalent to `invalidateSnapshotsFrom("0000-00")`
-*  but reads more clearly at call sites. */
-async function invalidateAllSnapshots(bookId, workspaceRoot) {
-	return invalidateSnapshotsFrom(bookId, "0000-00", workspaceRoot);
-}
-async function bookExists(bookId, workspaceRoot) {
-	return fileExists(bookRoot(bookId, workspaceRoot));
-}
-async function ensureBookDir(bookId, workspaceRoot) {
-	await promises.mkdir(bookRoot(bookId, workspaceRoot), { recursive: true });
-	await promises.mkdir(journalDir(bookId, workspaceRoot), { recursive: true });
-	await promises.mkdir(snapshotsDir(bookId, workspaceRoot), { recursive: true });
-}
-/** Recursively delete a book's directory. Used by `deleteBook` after
-*  the config has been updated to drop the entry. */
-async function removeBookDir(bookId, workspaceRoot) {
-	await promises.rm(bookRoot(bookId, workspaceRoot), {
-		recursive: true,
-		force: true
-	});
-}
-//#endregion
 //#region src/server/journal.ts
 /** Floating-point tolerance for the debit = credit check. Currency
 *  amounts arrive as JavaScript numbers (the on-wire format is JSON,
@@ -411,7 +163,7 @@ function buildLine(raw) {
 *  belong to the caller, because journal entries and opening balances
 *  disagree about them. Returns null when nothing usable came out —
 *  the caller drops the line rather than reading fields off it. */
-function parseJournalLine(raw, idx, errors) {
+function parseJournalLine$1(raw, idx, errors) {
 	if (!isRecord(raw)) {
 		errors.push({
 			field: `lines[${idx}]`,
@@ -437,7 +189,7 @@ function validateEntryLine(line, idx, accountCodes, errors) {
 function parseEntryLines(raw, accountCodes, errors) {
 	const lines = [];
 	raw.forEach((rawLine, idx) => {
-		const line = parseJournalLine(rawLine, idx, errors);
+		const line = parseJournalLine$1(rawLine, idx, errors);
 		if (line === null) return;
 		validateEntryLine(line, idx, accountCodes, errors);
 		lines.push(line);
@@ -465,6 +217,20 @@ function parseOptionalString(value, field, errors) {
 		message: `${field} must be a string when supplied`
 	});
 }
+var isOptionalString = (value) => value === void 0 || typeof value === "string";
+var isOptionalNumber = (value) => value === void 0 || typeof value === "number";
+function isJournalLine(value) {
+	return hasStringProp(value, "accountCode") && isOptionalNumber(value.debit) && isOptionalNumber(value.credit) && isOptionalString(value.memo) && isOptionalString(value.taxRegistrationId);
+}
+/** Checks every field `JournalEntry` and `JournalLine` declare, so a value
+*  that passes really is one. Used when reading the journal JSONL back:
+*  everything this module ever wrote satisfies it (`id` / `date` / `kind` /
+*  `lines` / `createdAt` have been required since the plugin's first
+*  release), while a line that doesn't is exactly the line that takes the
+*  whole book down — `report.ts` iterates `entry.lines` unguarded. */
+function isJournalEntry(value) {
+	return hasStringProp(value, "id") && hasStringProp(value, "date") && hasStringProp(value, "createdAt") && JOURNAL_ENTRY_KINDS.some((kind) => kind === value.kind) && isUnknownArray(value.lines) && value.lines.every(isJournalLine) && isOptionalString(value.memo) && isOptionalString(value.voidedEntryId) && isOptionalString(value.voidReason) && isOptionalString(value.replacesEntryId);
+}
 /** Normalize a journal line before persistence: trim string fields
 *  and drop empty-string optionals so the JSONL doesn't accumulate
 *  noise like `"taxRegistrationId":""`. Pure — does not mutate
@@ -611,6 +377,257 @@ function voidedIdSet(entries) {
 	return set;
 }
 //#endregion
+//#region src/server/io.ts
+var root = (workspaceRoot) => workspaceRoot ?? defaultWorkspaceRoot();
+function accountingRoot(workspaceRoot) {
+	return path.join(root(workspaceRoot), ACCOUNTING_DIRS.accounting);
+}
+function configPath(workspaceRoot) {
+	return path.join(accountingRoot(workspaceRoot), "config.json");
+}
+/** Allowed shape for a book id used as a directory name. Defense
+*  against path traversal: a crafted id like "../../config" or
+*  "/tmp/x" would otherwise let `bookRoot` escape the
+*  `data/accounting/books/` tree, since every write path joins
+*  `bookId` directly into the filesystem. The first character is
+*  alphanumeric to forbid leading dashes / underscores that some
+*  shells / docs render confusingly; `_` and `-` are allowed inside.
+*  64 chars is plenty for any reasonable book name. */
+var SAFE_BOOK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+function isSafeBookId(bookId) {
+	return typeof bookId === "string" && SAFE_BOOK_ID_RE.test(bookId);
+}
+function assertSafeBookId(bookId) {
+	if (!isSafeBookId(bookId)) throw new Error(`accounting: invalid bookId ${JSON.stringify(bookId)} (allowed: alphanumeric / _ / -; 1-64 chars; cannot start with _ or -)`);
+}
+function bookRoot(bookId, workspaceRoot) {
+	assertSafeBookId(bookId);
+	return path.join(root(workspaceRoot), ACCOUNTING_DIRS.accountingBooks, bookId);
+}
+function accountsPath(bookId, workspaceRoot) {
+	return path.join(bookRoot(bookId, workspaceRoot), "accounts.json");
+}
+function journalDir(bookId, workspaceRoot) {
+	return path.join(bookRoot(bookId, workspaceRoot), "journal");
+}
+function journalFileFor(bookId, period, workspaceRoot) {
+	return path.join(journalDir(bookId, workspaceRoot), `${period}.jsonl`);
+}
+function snapshotsDir(bookId, workspaceRoot) {
+	return path.join(bookRoot(bookId, workspaceRoot), "snapshots");
+}
+function snapshotFileFor(bookId, period, workspaceRoot) {
+	return path.join(snapshotsDir(bookId, workspaceRoot), `${period}.json`);
+}
+async function fileExists(filePath) {
+	try {
+		await promises.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Strict variant of `readJsonOrNull` from `./json.ts`: returns null
+*  on ENOENT but RETHROWS other read errors and parse failures so a
+*  corrupted accounting journal surfaces rather than silently
+*  collapsing to "no data". `./json.ts` keeps the permissive
+*  variant for user-config files where a single bad keystroke
+*  shouldn't 500 the server. */
+async function readJsonStrict(filePath) {
+	try {
+		const raw = await promises.readFile(filePath, "utf-8");
+		return JSON.parse(raw);
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		throw err;
+	}
+}
+/** Migrate a legacy calendar-quarter `fiscalYearEnd` token ("Q1".."Q4")
+*  to its closing-month number in memory so every downstream consumer
+*  (reports, time-series, the UI selects) sees one shape. Absent stays
+*  absent — the field is optional and resolves to the default on read;
+*  we don't stamp an explicit December onto a book that never chose one.
+*  Nothing is written back here (no auto-migrate on disk). */
+function normalizeBookFiscalYearEnd(book) {
+	if (book.fiscalYearEnd === void 0) return book;
+	const resolved = resolveFiscalYearEnd(book.fiscalYearEnd);
+	return book.fiscalYearEnd === resolved ? book : {
+		...book,
+		fiscalYearEnd: resolved
+	};
+}
+async function readConfig(workspaceRoot) {
+	const config = await readJsonStrict(configPath(workspaceRoot));
+	if (!config) return null;
+	return {
+		...config,
+		books: config.books.map(normalizeBookFiscalYearEnd)
+	};
+}
+async function writeConfig(config, workspaceRoot) {
+	await writeJsonAtomic(configPath(workspaceRoot), config);
+}
+async function readAccounts(bookId, workspaceRoot) {
+	return await readJsonStrict(accountsPath(bookId, workspaceRoot)) ?? [];
+}
+async function writeAccounts(bookId, accounts, workspaceRoot) {
+	await writeJsonAtomic(accountsPath(bookId, workspaceRoot), accounts);
+}
+/** Convert a YYYY-MM-DD date string to its YYYY-MM month bucket. The
+*  month bucket dictates which JSONL file the entry lives in. */
+function periodFromDate(date) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error(`accounting: invalid date format ${JSON.stringify(date)} (expected YYYY-MM-DD)`);
+	return date.slice(0, 7);
+}
+/** Append one entry to the appropriate month's JSONL.
+*
+*  Uses POSIX append-only semantics (`fs.appendFile` → `O_APPEND`).
+*  Two concurrent callers landing in the same month file are
+*  serialised by the kernel — neither overwrites the other, which
+*  is the bug the previous read-modify-write implementation had.
+*
+*  Crash mid-write: an entry shorter than `PIPE_BUF` (≥ 512 bytes
+*  on every supported platform) writes atomically; a single
+*  serialised `JournalEntry` is comfortably under that. If the
+*  process is killed during the syscall the worst case is a torn
+*  trailing line, which `readJournalMonth` already tolerates by
+*  skipping unparseable lines and surfacing a `skipped` count to
+*  the caller. */
+async function appendJournal(bookId, entry, workspaceRoot) {
+	const file = journalFileFor(bookId, periodFromDate(entry.date), workspaceRoot);
+	await promises.mkdir(path.dirname(file), { recursive: true });
+	await promises.appendFile(file, `${JSON.stringify(entry)}\n`, { encoding: "utf-8" });
+}
+function groupEntriesByPeriod(entries) {
+	const byPeriod = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const period = periodFromDate(entry.date);
+		const list = byPeriod.get(period) ?? [];
+		list.push(entry);
+		byPeriod.set(period, list);
+	}
+	return byPeriod;
+}
+/** Append a batch of entries: same-period entries are concatenated
+*  into one `appendFile` call so the whole same-period chunk hits
+*  the kernel as a single `O_APPEND` write — small chunks (under
+*  `PIPE_BUF`, ≥ 512 bytes on every supported platform) are
+*  guaranteed atomic by POSIX, and `O_APPEND` serialises with any
+*  concurrent appender (a parallel `appendJournal` / `addEntries`
+*  call can never overwrite our write or vice versa). Cross-period
+*  batches loop one append per period; each is independently
+*  concurrency-safe but their union is not transactional across
+*  files (out of scope for the append-only JSONL design). */
+async function appendJournalBatch(bookId, entries, workspaceRoot) {
+	if (entries.length === 0) return;
+	const byPeriod = groupEntriesByPeriod(entries);
+	for (const [period, items] of byPeriod) {
+		const file = journalFileFor(bookId, period, workspaceRoot);
+		await promises.mkdir(path.dirname(file), { recursive: true });
+		const chunk = items.map((entry) => `${JSON.stringify(entry)}\n`).join("");
+		await promises.appendFile(file, chunk, { encoding: "utf-8" });
+	}
+}
+/** One JSONL line, or null when it isn't a journal entry — unparseable JSON
+*  and JSON of the wrong shape are the same failure to a caller that can only
+*  skip the line. */
+function parseJournalLine(line) {
+	try {
+		const parsed = JSON.parse(line);
+		return isJournalEntry(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/** Read a single month's JSONL. Malformed lines are skipped (logged
+*  by the caller; this layer just returns the parseable subset) so
+*  one bad line doesn't lock the user out of their book. */
+async function readJournalMonth(bookId, period, workspaceRoot) {
+	const file = journalFileFor(bookId, period, workspaceRoot);
+	let raw;
+	try {
+		raw = await promises.readFile(file, "utf-8");
+	} catch (err) {
+		if (isEnoent(err)) return {
+			entries: [],
+			skipped: 0
+		};
+		throw err;
+	}
+	const parsed = raw.split("\n").filter((line) => line.trim() !== "").map(parseJournalLine);
+	const entries = parsed.filter((entry) => entry !== null);
+	return {
+		entries,
+		skipped: parsed.length - entries.length
+	};
+}
+/** List the YYYY-MM periods that have a journal file on disk, sorted
+*  ascending. Useful for full-history scans (rebuilding snapshots
+*  from scratch). */
+async function listJournalPeriods(bookId, workspaceRoot) {
+	let names;
+	try {
+		names = await promises.readdir(journalDir(bookId, workspaceRoot));
+	} catch (err) {
+		if (isEnoent(err)) return [];
+		throw err;
+	}
+	return names.filter((name) => /^\d{4}-\d{2}\.jsonl$/.test(name)).map((name) => name.slice(0, 7)).sort();
+}
+async function readSnapshot(bookId, period, workspaceRoot) {
+	return readJsonStrict(snapshotFileFor(bookId, period, workspaceRoot));
+}
+async function writeSnapshot(bookId, snapshot, workspaceRoot) {
+	const file = snapshotFileFor(bookId, snapshot.period, workspaceRoot);
+	await promises.mkdir(path.dirname(file), { recursive: true });
+	await writeJsonAtomic(file, snapshot, { uniqueTmp: true });
+}
+/** Drop snapshot files for all periods >= `fromPeriod`. The next
+*  read regenerates them. Idempotent: missing files are silently
+*  ignored. */
+async function invalidateSnapshotsFrom(bookId, fromPeriod, workspaceRoot) {
+	let names;
+	try {
+		names = await promises.readdir(snapshotsDir(bookId, workspaceRoot));
+	} catch (err) {
+		if (isEnoent(err)) return { removed: [] };
+		throw err;
+	}
+	const removed = [];
+	for (const name of names) {
+		const match = /^(\d{4}-\d{2})\.json$/.exec(name);
+		if (!match) continue;
+		const [, period] = match;
+		if (period >= fromPeriod) {
+			await promises.rm(path.join(snapshotsDir(bookId, workspaceRoot), name), { force: true });
+			removed.push(period);
+		}
+	}
+	return { removed: removed.sort() };
+}
+/** Drop ALL snapshots for a book — used by `rebuildSnapshots()`
+*  with no `from`. Equivalent to `invalidateSnapshotsFrom("0000-00")`
+*  but reads more clearly at call sites. */
+async function invalidateAllSnapshots(bookId, workspaceRoot) {
+	return invalidateSnapshotsFrom(bookId, "0000-00", workspaceRoot);
+}
+async function bookExists(bookId, workspaceRoot) {
+	return fileExists(bookRoot(bookId, workspaceRoot));
+}
+async function ensureBookDir(bookId, workspaceRoot) {
+	await promises.mkdir(bookRoot(bookId, workspaceRoot), { recursive: true });
+	await promises.mkdir(journalDir(bookId, workspaceRoot), { recursive: true });
+	await promises.mkdir(snapshotsDir(bookId, workspaceRoot), { recursive: true });
+}
+/** Recursively delete a book's directory. Used by `deleteBook` after
+*  the config has been updated to drop the entry. */
+async function removeBookDir(bookId, workspaceRoot) {
+	await promises.rm(bookRoot(bookId, workspaceRoot), {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
 //#region src/server/openingBalances.ts
 /** Find the existing opening entry for a book, if any. Multiple
 *  openings shouldn't coexist (the route enforces void-then-append),
@@ -648,7 +665,7 @@ function parseOpeningLines(raw, accounts, errors) {
 	const accountByCode = new Map(accounts.map((account) => [account.code, account]));
 	const lines = [];
 	raw.forEach((rawLine, idx) => {
-		const line = parseJournalLine(rawLine, idx, errors);
+		const line = parseJournalLine$1(rawLine, idx, errors);
 		if (line === null) return;
 		validateOpeningAccount(line, idx, accountByCode, errors);
 		lines.push(line);
@@ -1643,19 +1660,22 @@ function coerceFiscalYearEndInput(raw) {
 	if (!isFiscalYearEnd(month)) throw unsupportedFiscalYearEndError(raw);
 	return month;
 }
-/** Boundary checks shared by updateBook (name / country only —
-*  fiscalYearEnd is coerced + validated separately via
-*  `coerceFiscalYearEndInput`). Throws on the first failure so the
-*  surrounding function stays under the cognitive-complexity threshold;
-*  each rule is also unit-testable independently via the service entry
-*  point. */
-function validateUpdateBookInput(input) {
+/** Boundary checks for updateBook (name / country only — fiscalYearEnd is
+*  coerced + validated separately via `coerceFiscalYearEndInput`). Throws on
+*  the first failure so the surrounding function stays under the
+*  cognitive-complexity threshold, and hands back the country to persist:
+*  `undefined` = the field was omitted, `""` = explicit clear. */
+function parseUpdateBookInput(input) {
 	if (input.name !== void 0 && (typeof input.name !== "string" || input.name.trim() === "")) throw new AccountingError(400, "name must be a non-empty string when supplied");
-	if (input.country !== void 0 && input.country !== "" && !isSupportedCountryCode(input.country)) throw unsupportedCountryError(input.country);
+	const { country } = input;
+	if (country === void 0 || country === "") return country;
+	if (!isSupportedCountryCode(country)) throw unsupportedCountryError(country);
+	return country;
 }
 async function createBook(input, workspaceRoot) {
 	if (typeof input.name !== "string" || input.name.trim() === "") throw new AccountingError(400, "name is required");
-	if (input.country !== void 0 && !isSupportedCountryCode(input.country)) throw unsupportedCountryError(input.country);
+	const { country } = input;
+	if (country !== void 0 && !isSupportedCountryCode(country)) throw unsupportedCountryError(country);
 	const fiscalYearEnd = coerceFiscalYearEndInput(input.fiscalYearEnd) ?? 12;
 	const config = await loadOrInitConfig(workspaceRoot);
 	const bookId = input.id ?? await generateBookId(config, workspaceRoot);
@@ -1666,7 +1686,7 @@ async function createBook(input, workspaceRoot) {
 		id: bookId,
 		name: input.name,
 		currency: input.currency ?? DEFAULT_CURRENCY,
-		...input.country ? { country: input.country } : {},
+		...country ? { country } : {},
 		fiscalYearEnd,
 		createdAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
@@ -1680,15 +1700,15 @@ async function updateBook(input, workspaceRoot) {
 	const config = await loadOrInitConfig(workspaceRoot);
 	const target = findBook(config, input.bookId);
 	if (!target) throw new AccountingError(404, `book ${JSON.stringify(input.bookId)} not found`);
-	validateUpdateBookInput(input);
+	const country = parseUpdateBookInput(input);
 	const fiscalYearEnd = coerceFiscalYearEndInput(input.fiscalYearEnd);
 	const next = {
 		...target,
 		...input.name !== void 0 ? { name: input.name } : {},
-		...input.country !== void 0 && input.country !== "" ? { country: input.country } : {},
+		...country ? { country } : {},
 		...fiscalYearEnd !== void 0 ? { fiscalYearEnd } : {}
 	};
-	if (input.country === "") delete next.country;
+	if (country === "") delete next.country;
 	await writeConfig({ books: config.books.map((book) => book.id === input.bookId ? next : book) }, workspaceRoot);
 	publishBooksChanged();
 	return { book: next };
@@ -1959,12 +1979,14 @@ function ensureValidYmd(label, value) {
 	return value;
 }
 function ensureMetric(value) {
-	if (typeof value !== "string" || !TIME_SERIES_METRICS.includes(value)) throw new AccountingError(400, `getTimeSeries: metric must be one of ${TIME_SERIES_METRICS.join(", ")}`);
-	return value;
+	const metric = TIME_SERIES_METRICS.find((candidate) => candidate === value);
+	if (metric === void 0) throw new AccountingError(400, `getTimeSeries: metric must be one of ${TIME_SERIES_METRICS.join(", ")}`);
+	return metric;
 }
 function ensureGranularity(value) {
-	if (typeof value !== "string" || !TIME_SERIES_GRANULARITIES.includes(value)) throw new AccountingError(400, `getTimeSeries: granularity must be one of ${TIME_SERIES_GRANULARITIES.join(", ")}`);
-	return value;
+	const granularity = TIME_SERIES_GRANULARITIES.find((candidate) => candidate === value);
+	if (granularity === void 0) throw new AccountingError(400, `getTimeSeries: granularity must be one of ${TIME_SERIES_GRANULARITIES.join(", ")}`);
+	return granularity;
 }
 function resolveAccountCode(metric, raw) {
 	if (metric === "accountBalance") {