@mulmoclaude/accounting-plugin 1.1.0 → 1.2.1

package/dist/server.js

@@ -1,9 +1,39 @@
-import { A as resolveFiscalYearEnd, D as isFiscalYearEnd, F as bookChannel, L as BALANCE_SHEET_ACCOUNT_TYPES, M as errorMessage, N as ACCOUNTING_BOOKS_CHANNEL, P as BOOK_EVENT_KINDS, R as ACCOUNTING_API, S as FISCAL_YEAR_END_MONTHS, T as fiscalYearEndMonth, _ as SUPPORTED_COUNTRY_CODES, j as ACCOUNTING_DIRS, n as TIME_SERIES_METRICS, t as TIME_SERIES_GRANULARITIES, y as isSupportedCountryCode, z as ACCOUNTING_ACTIONS } from "./shared-MOpJ1kUa.js";
+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 { Router } from "express";
 import { randomUUID } from "node:crypto";
 import { promises } from "node:fs";
 import path from "node:path";
 import { isEnoent, writeJsonAtomic } from "@mulmoclaude/core/files";
+//#region src/server/bodyFields.ts
+var optionalString = (value) => typeof value === "string" ? value : void 0;
+var optionalRecord = (value) => isRecord(value) ? value : void 0;
+/** Rebuilt field by field rather than narrowed with a predicate, so the
+*  returned object is one this function actually proved. A half-formed
+*  `{ kind: "month" }` reads as absent and the caller raises its own
+*  "period is required" — previously it reached the report builders and
+*  produced an `undefined-01` date. */
+var optionalReportPeriod = (value) => {
+	const period = optionalRecord(value);
+	if (period?.kind === "month" && typeof period.period === "string") return {
+		kind: "month",
+		period: period.period
+	};
+	if (period?.kind === "range" && typeof period.from === "string" && typeof period.to === "string") return {
+		kind: "range",
+		from: period.from,
+		to: period.to
+	};
+};
+/** The two fields the addEntries narration quotes back, read out of a
+*  service payload that is only `unknown` to the router. */
+var describeEntry = (entry) => {
+	const record = optionalRecord(entry);
+	return {
+		id: optionalString(record?.id),
+		date: optionalString(record?.date)
+	};
+};
+//#endregion
 //#region src/server/context.ts
 var deps = null;
 /** Called once by the host before the accounting router is mounted. */
@@ -286,7 +316,7 @@ async function removeBookDir(bookId, workspaceRoot) {
 *  so amounts are doubles). 0.005 keeps two-decimal currency math
 *  honest while accepting the floating-point noise of summing
 *  many lines. */
-var EQUALITY_TOLERANCE$1 = .005;
+var EQUALITY_TOLERANCE = .005;
 function lineHasExactlyOneSide(line) {
 	return (typeof line.debit === "number" && line.debit !== 0) !== (typeof line.credit === "number" && line.credit !== 0);
 }
@@ -325,36 +355,115 @@ function netBalance(lines) {
 	}
 	return net;
 }
-/** Pure validation. Does not throw; returns a list of issues so the
-*  REST handler can return a structured 400 instead of an opaque
-*  500. */
-function validateLine(line, idx, accountCodes, errors) {
-	if (!line.accountCode || !accountCodes.has(line.accountCode)) errors.push({
+function checkTaxRegistrationId(value, idx, errors) {
+	if (value === void 0) return;
+	if (typeof value !== "string") {
+		errors.push({
+			field: `lines[${idx}].taxRegistrationId`,
+			message: "must be a string"
+		});
+		return;
+	}
+	if (value.trim().length > 32) errors.push({
+		field: `lines[${idx}].taxRegistrationId`,
+		message: `must be at most 32 characters (got ${value.trim().length})`
+	});
+}
+/** One issue per bad field, so a caller fixing a line learns about all
+*  of them at once. Returns whether the line came through clean. */
+function checkLineFields(raw, idx, errors) {
+	const issuesBefore = errors.length;
+	const { accountCode, debit, credit, memo, taxRegistrationId } = raw;
+	if (typeof accountCode !== "string") errors.push({
 		field: `lines[${idx}].accountCode`,
-		message: `unknown account code ${JSON.stringify(line.accountCode)}`
+		message: "accountCode must be a string"
 	});
-	if (line.debit !== void 0 && !isNonNegativeNumber(line.debit)) errors.push({
+	if (debit !== void 0 && !isNonNegativeNumber(debit)) errors.push({
 		field: `lines[${idx}].debit`,
 		message: "debit must be a non-negative finite number"
 	});
-	if (line.credit !== void 0 && !isNonNegativeNumber(line.credit)) errors.push({
+	if (credit !== void 0 && !isNonNegativeNumber(credit)) errors.push({
 		field: `lines[${idx}].credit`,
 		message: "credit must be a non-negative finite number"
 	});
+	if (memo !== void 0 && typeof memo !== "string") errors.push({
+		field: `lines[${idx}].memo`,
+		message: "memo must be a string"
+	});
+	checkTaxRegistrationId(taxRegistrationId, idx, errors);
+	return errors.length === issuesBefore;
+}
+/** Re-tested rather than assigned straight through: `checkLineFields`
+*  proved each of these, but only a `typeof` narrows them for the
+*  compiler. */
+function buildLine(raw) {
+	const { accountCode, debit, credit, memo, taxRegistrationId } = raw;
+	if (typeof accountCode !== "string") return null;
+	const line = { accountCode };
+	if (typeof debit === "number") line.debit = debit;
+	if (typeof credit === "number") line.credit = credit;
+	if (typeof memo === "string") line.memo = memo;
+	if (typeof taxRegistrationId === "string") line.taxRegistrationId = taxRegistrationId;
+	return line;
+}
+/** Narrow one wire value to a `JournalLine`, pushing an issue per bad
+*  field. Shape only: account existence and the debit/credit-side rule
+*  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) {
+	if (!isRecord(raw)) {
+		errors.push({
+			field: `lines[${idx}]`,
+			message: "each line must be an object with an accountCode and a debit or credit amount"
+		});
+		return null;
+	}
+	if (!checkLineFields(raw, idx, errors)) return null;
+	return buildLine(raw);
+}
+/** The rules a journal line answers to on top of its shape: the code
+*  must name a real account, and exactly one side carries an amount. */
+function validateEntryLine(line, idx, accountCodes, errors) {
+	if (!line.accountCode || !accountCodes.has(line.accountCode)) errors.push({
+		field: `lines[${idx}].accountCode`,
+		message: `unknown account code ${JSON.stringify(line.accountCode)}`
+	});
 	if (!lineHasExactlyOneSide(line)) errors.push({
 		field: `lines[${idx}]`,
 		message: "each line must set exactly one of debit or credit (and to a non-zero amount)"
 	});
-	if (line.taxRegistrationId !== void 0) {
-		if (typeof line.taxRegistrationId !== "string") errors.push({
-			field: `lines[${idx}].taxRegistrationId`,
-			message: "must be a string"
-		});
-		else if (line.taxRegistrationId.trim().length > 32) errors.push({
-			field: `lines[${idx}].taxRegistrationId`,
-			message: `must be at most 32 characters (got ${line.taxRegistrationId.trim().length})`
-		});
-	}
+}
+function parseEntryLines(raw, accountCodes, errors) {
+	const lines = [];
+	raw.forEach((rawLine, idx) => {
+		const line = parseJournalLine(rawLine, idx, errors);
+		if (line === null) return;
+		validateEntryLine(line, idx, accountCodes, errors);
+		lines.push(line);
+	});
+	return lines;
+}
+/** Report the debit = credit imbalance — but only when every line was
+*  readable. A line that failed to parse contributes nothing to the sum,
+*  so an entry that balances perfectly would otherwise be told it
+*  doesn't, sending the caller off to "fix" amounts that were never
+*  wrong. Naming the unreadable line is the actionable message; the
+*  balance is worth re-checking once it's a line. */
+function checkBalances(lines, expectedLineCount, subject, errors) {
+	if (lines.length !== expectedLineCount) return;
+	const net = netBalance(lines);
+	if (Math.abs(net) > EQUALITY_TOLERANCE) errors.push({
+		field: "lines",
+		message: `Σ debit − Σ credit = ${net.toFixed(4)}; ${subject} must balance`
+	});
+}
+function parseOptionalString(value, field, errors) {
+	if (value === void 0 || typeof value === "string") return value;
+	errors.push({
+		field,
+		message: `${field} must be a string when supplied`
+	});
 }
 /** Normalize a journal line before persistence: trim string fields
 *  and drop empty-string optionals so the JSONL doesn't accumulate
@@ -369,13 +478,26 @@ function normalizeLine(line) {
 	}
 	return out;
 }
-function validateEntry(input) {
+/** Parse one entry off the wire. Does not throw: every rejection comes
+*  back as a list of issues so the REST handler can return a structured
+*  400 instead of an opaque 500. Parse rather than validate — the
+*  narrowed entry rides along on success, so `makeEntry` never has to
+*  take the caller's word for the shape. */
+function parseEntry(raw, accounts) {
+	if (!isRecord(raw)) return {
+		ok: false,
+		errors: [{
+			field: "entry",
+			message: "each entry must be an object with a date and a lines array"
+		}]
+	};
 	const errors = [];
-	if (!isValidCalendarDate(input.date)) errors.push({
+	const date = typeof raw.date === "string" && isValidCalendarDate(raw.date) ? raw.date : null;
+	if (date === null) errors.push({
 		field: "date",
-		message: `expected YYYY-MM-DD calendar date, got ${JSON.stringify(input.date)}`
+		message: `expected YYYY-MM-DD calendar date, got ${JSON.stringify(raw.date)}`
 	});
-	if (!Array.isArray(input.lines) || input.lines.length < 2) {
+	if (!isUnknownArray(raw.lines) || raw.lines.length < 2) {
 		errors.push({
 			field: "lines",
 			message: "an entry needs at least two lines (one debit, one credit)"
@@ -385,20 +507,26 @@ function validateEntry(input) {
 			errors
 		};
 	}
-	const accountCodes = new Set(input.accounts.map((account) => account.code));
-	input.lines.forEach((line, idx) => validateLine(line, idx, accountCodes, errors));
-	const net = netBalance(input.lines);
-	if (Math.abs(net) > EQUALITY_TOLERANCE$1) errors.push({
-		field: "lines",
-		message: `Σ debit − Σ credit = ${net.toFixed(4)}; entry must balance`
-	});
-	return {
-		ok: errors.length === 0,
+	const lines = parseEntryLines(raw.lines, new Set(accounts.map((account) => account.code)), errors);
+	checkBalances(lines, raw.lines.length, "entry", errors);
+	const memo = parseOptionalString(raw.memo, "memo", errors);
+	const replacesEntryId = parseOptionalString(raw.replacesEntryId, "replacesEntryId", errors);
+	if (errors.length > 0 || date === null) return {
+		ok: false,
 		errors
 	};
+	return {
+		ok: true,
+		entry: {
+			date,
+			lines,
+			memo,
+			replacesEntryId
+		}
+	};
 }
-/** Build a JournalEntry — validation is the caller's responsibility
-*  (it should have called `validateEntry` first). The id is a fresh
+/** Build a JournalEntry from lines something already parsed
+*  (`parseEntry` / `parseOpening`). The id is a fresh
 *  UUID; createdAt is the wall clock at the moment of creation.
 *  Lines are normalized so optional string fields don't persist as
 *  empty strings. */
@@ -484,7 +612,6 @@ function voidedIdSet(entries) {
 }
 //#endregion
 //#region src/server/openingBalances.ts
-var EQUALITY_TOLERANCE = .005;
 /** Find the existing opening entry for a book, if any. Multiple
 *  openings shouldn't coexist (the route enforces void-then-append),
 *  but if they do the most recent by `createdAt` wins so callers
@@ -499,22 +626,34 @@ function findActiveOpening(entries) {
 	}
 	return active;
 }
-function validateLineAccountTypes(input, errors) {
-	const accountByCode = new Map(input.accounts.map((account) => [account.code, account]));
-	input.lines.forEach((line, idx) => {
-		const acct = accountByCode.get(line.accountCode);
-		if (!acct) {
-			errors.push({
-				field: `lines[${idx}].accountCode`,
-				message: `unknown account code ${JSON.stringify(line.accountCode)}`
-			});
-			return;
-		}
-		if (!BALANCE_SHEET_ACCOUNT_TYPES.includes(acct.type)) errors.push({
+function validateOpeningAccount(line, idx, accountByCode, errors) {
+	const acct = accountByCode.get(line.accountCode);
+	if (!acct) {
+		errors.push({
 			field: `lines[${idx}].accountCode`,
-			message: `account ${acct.code} is type ${acct.type}; opening balances may only reference balance-sheet accounts (asset / liability / equity)`
+			message: `unknown account code ${JSON.stringify(line.accountCode)}`
 		});
+		return;
+	}
+	if (!BALANCE_SHEET_ACCOUNT_TYPES.includes(acct.type)) errors.push({
+		field: `lines[${idx}].accountCode`,
+		message: `account ${acct.code} is type ${acct.type}; opening balances may only reference balance-sheet accounts (asset / liability / equity)`
+	});
+}
+/** Opening lines are narrowed by the same shape parser the journal
+*  uses, but they answer to different rules afterwards: balance-sheet
+*  accounts only, and no "exactly one side" requirement — the opening
+*  form lets a user carry both columns on one account. */
+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);
+		if (line === null) return;
+		validateOpeningAccount(line, idx, accountByCode, errors);
+		lines.push(line);
 	});
+	return lines;
 }
 function validateAsOfPredatesEverything(input, errors) {
 	const voided = voidedIdSet(input.existingEntries);
@@ -531,20 +670,21 @@ function validateAsOfPredatesEverything(input, errors) {
 		}
 	}
 }
-/** Validate inputs for `setOpeningBalances`. Caller passes the full
-*  list of journal entries in the book so we can check the
-*  "asOfDate must precede every other entry" rule. An opening with
+/** Parse the inputs for `setOpeningBalances`, returning the narrowed
+*  lines so the caller can persist what was actually checked. Caller
+*  passes the full list of journal entries in the book so we can check
+*  the "asOfDate must precede every other entry" rule. An opening with
 *  zero lines is accepted as a no-op marker — it satisfies the
 *  "book has an opening" gate the UI uses without committing the
 *  user to specific balances on day one (they can replace it
 *  later). */
-function validateOpening(input) {
+function parseOpening(input) {
 	const errors = [];
 	if (!isValidCalendarDate(input.asOfDate)) errors.push({
 		field: "asOfDate",
 		message: `expected YYYY-MM-DD calendar date, got ${JSON.stringify(input.asOfDate)}`
 	});
-	if (!Array.isArray(input.lines)) {
+	if (!isUnknownArray(input.lines)) {
 		errors.push({
 			field: "lines",
 			message: "lines must be an array"
@@ -554,20 +694,64 @@ function validateOpening(input) {
 			errors
 		};
 	}
-	validateLineAccountTypes(input, errors);
-	const net = netBalance(input.lines);
-	if (Math.abs(net) > EQUALITY_TOLERANCE) errors.push({
-		field: "lines",
-		message: `Σ debit − Σ credit = ${net.toFixed(4)}; opening must balance`
-	});
+	const lines = parseOpeningLines(input.lines, input.accounts, errors);
+	checkBalances(lines, input.lines.length, "opening", errors);
 	validateAsOfPredatesEverything(input, errors);
-	return {
-		ok: errors.length === 0,
+	if (errors.length > 0) return {
+		ok: false,
 		errors
 	};
+	return {
+		ok: true,
+		lines
+	};
 }
 //#endregion
 //#region src/server/accountNormalize.ts
+function isAccountType(value) {
+	return ACCOUNT_TYPES.some((accountType) => accountType === value);
+}
+/** Narrow a wire payload to an `Account`. `name` and `type` are as
+*  required as `code`: an account persisted without a type is invisible
+*  to every report, which groups rows by it. */
+function parseAccountInput(raw) {
+	if (!isRecord(raw)) return {
+		ok: false,
+		message: "account is required — pass an object with code, name, and type"
+	};
+	const { code, name, type, note, active } = raw;
+	if (typeof code !== "string" || code.length === 0) return {
+		ok: false,
+		message: "account code is required"
+	};
+	if (typeof name !== "string" || name.trim() === "") return {
+		ok: false,
+		message: "account name is required"
+	};
+	if (!isAccountType(type)) return {
+		ok: false,
+		message: `account type ${JSON.stringify(type)} is invalid — must be one of: ${ACCOUNT_TYPES.join(", ")}`
+	};
+	if (note !== void 0 && typeof note !== "string") return {
+		ok: false,
+		message: "account note must be a string when supplied"
+	};
+	if (active !== void 0 && typeof active !== "boolean") return {
+		ok: false,
+		message: "account active must be a boolean when supplied"
+	};
+	const account = {
+		code,
+		name,
+		type
+	};
+	if (typeof note === "string") account.note = note;
+	if (typeof active === "boolean") account.active = active;
+	return {
+		ok: true,
+		account
+	};
+}
 function normalizeStoredAccount(input, existing) {
 	const stored = {
 		code: input.code,
@@ -1531,44 +1715,65 @@ async function listAccounts(input, workspaceRoot) {
 		accounts: await readAccounts(bookId, workspaceRoot)
 	};
 }
-async function upsertAccount(input, workspaceRoot) {
-	const bookId = resolveBookId(await loadOrInitConfig(workspaceRoot), input.bookId);
-	if (typeof input.account?.code !== "string" || input.account.code.length === 0) throw new AccountingError(400, "account code is required");
-	if (input.account.code.startsWith("_")) throw new AccountingError(400, `account code ${JSON.stringify(input.account.code)} is reserved (codes starting with _ are used for synthetic report rows)`);
-	const accounts = await readAccounts(bookId, workspaceRoot);
-	const existingIdx = accounts.findIndex((account) => account.code === input.account.code);
+/** Parse the caller's account, then apply the one rule the chart owns
+*  rather than the record: codes starting with `_` are reserved for the
+*  synthetic rows the report layer injects (e.g. `_currentEarnings` in
+*  the Equity section). A user account there would either duplicate a
+*  B/S row or hide a real account behind the synthetic label. */
+function parseUpsertAccount(raw) {
+	const parsed = parseAccountInput(raw);
+	if (!parsed.ok) throw new AccountingError(400, parsed.message);
+	if (parsed.account.code.startsWith("_")) throw new AccountingError(400, `account code ${JSON.stringify(parsed.account.code)} is reserved (codes starting with _ are used for synthetic report rows)`);
+	return parsed.account;
+}
+/** Insert or replace the account in the chart. The whitelist +
+*  active-flag policy lives in normalizeStoredAccount (see
+*  ./accountNormalize.ts) so it stays unit-testable in isolation.
+*  `previousType` is null for a new code — callers use it to decide
+*  whether aggregation across periods just changed meaning. */
+function applyAccount(accounts, account) {
+	const existingIdx = accounts.findIndex((stored) => stored.code === account.code);
+	const existing = existingIdx >= 0 ? accounts[existingIdx] : void 0;
+	const stored = normalizeStoredAccount(account, existing);
 	const next = [...accounts];
-	const oldType = existingIdx >= 0 ? accounts[existingIdx].type : null;
-	const stored = normalizeStoredAccount(input.account, existingIdx >= 0 ? accounts[existingIdx] : void 0);
 	if (existingIdx >= 0) next[existingIdx] = stored;
 	else next.push(stored);
+	return {
+		next,
+		previousType: existing ? existing.type : null
+	};
+}
+async function upsertAccount(input, workspaceRoot) {
+	const bookId = resolveBookId(await loadOrInitConfig(workspaceRoot), input.bookId);
+	const account = parseUpsertAccount(input.account);
+	const { next, previousType } = applyAccount(await readAccounts(bookId, workspaceRoot), account);
 	await writeAccounts(bookId, next, workspaceRoot);
-	if (oldType !== null && oldType !== input.account.type) {
+	if (previousType !== null && previousType !== account.type) {
 		scheduleRebuild(bookId, "0000-00", workspaceRoot);
 		await invalidateAllSnapshots(bookId, workspaceRoot);
 	}
 	publishBookChange(bookId, { kind: BOOK_EVENT_KINDS.accounts });
 	return {
 		bookId,
-		account: { ...input.account },
+		account,
 		accounts: next
 	};
 }
-function collectBatchValidationFailures(items, accounts) {
+function parseBatchEntries(items, accounts) {
 	const failures = [];
-	for (let idx = 0; idx < items.length; idx++) {
-		const item = items[idx];
-		const validation = validateEntry({
-			date: item.date,
-			lines: item.lines,
-			accounts
+	const parsed = [];
+	items.forEach((item, index) => {
+		const result = parseEntry(item, accounts);
+		if (result.ok) parsed.push(result.entry);
+		else failures.push({
+			index,
+			errors: result.errors
 		});
-		if (!validation.ok) failures.push({
-			index: idx,
-			errors: validation.errors
-		});
-	}
-	return failures;
+	});
+	return {
+		failures,
+		items: parsed
+	};
 }
 function buildBatchEntries(items) {
 	return items.map((item) => makeEntry({
@@ -1584,11 +1789,11 @@ function earliestPeriodOf(entries) {
 }
 async function addEntries(input, workspaceRoot) {
 	const bookId = resolveBookId(await loadOrInitConfig(workspaceRoot), input.bookId);
-	if (!Array.isArray(input.entries) || input.entries.length === 0) throw new AccountingError(400, "addEntries: entries must be a non-empty array");
+	if (!isUnknownArray(input.entries) || input.entries.length === 0) throw new AccountingError(400, "addEntries: entries must be a non-empty array");
 	const accounts = await readAccounts(bookId, workspaceRoot);
-	const failures = collectBatchValidationFailures(input.entries, accounts);
+	const { failures, items } = parseBatchEntries(input.entries, accounts);
 	if (failures.length > 0) throw new AccountingError(400, "invalid journal entries", failures);
-	const built = buildBatchEntries(input.entries);
+	const built = buildBatchEntries(items);
 	await appendJournalBatch(bookId, built, workspaceRoot);
 	const earliestPeriod = earliestPeriodOf(built);
 	scheduleRebuild(bookId, earliestPeriod, workspaceRoot);
@@ -1667,13 +1872,13 @@ async function setOpeningBalances(input, workspaceRoot) {
 	const bookId = resolveBookId(await loadOrInitConfig(workspaceRoot), input.bookId);
 	const accounts = await readAccounts(bookId, workspaceRoot);
 	const all = await readAllEntries(bookId, workspaceRoot);
-	const validation = validateOpening({
+	const parsed = parseOpening({
 		asOfDate: input.asOfDate,
 		lines: input.lines,
 		accounts,
 		existingEntries: all
 	});
-	if (!validation.ok) throw new AccountingError(400, "invalid opening balances", validation.errors);
+	if (!parsed.ok) throw new AccountingError(400, "invalid opening balances", parsed.errors);
 	const existing = findActiveOpening(all);
 	if (existing) {
 		const { reverse, marker } = makeVoidEntries(existing, "replaced via setOpeningBalances", localDateString());
@@ -1682,7 +1887,7 @@ async function setOpeningBalances(input, workspaceRoot) {
 	}
 	const opening = makeEntry({
 		date: input.asOfDate,
-		lines: input.lines,
+		lines: parsed.lines,
 		memo: input.memo ?? "Opening balances",
 		kind: "opening"
 	});
@@ -1862,17 +2067,18 @@ async function handleOpenBook(rest) {
 }
 async function handleGetReport(rest) {
 	const kind = typeof rest.kind === "string" ? rest.kind : "";
-	const periodInput = rest.period;
-	const bookId = rest.bookId;
+	const periodInput = optionalReportPeriod(rest.period);
+	const bookId = optionalString(rest.bookId);
+	const periodRequired = (label) => new AccountingError(400, `${label}: period is required — { kind: "month", period: "YYYY-MM" } or { kind: "range", from: "YYYY-MM-DD", to: "YYYY-MM-DD" }`);
 	if (kind === "balance") {
-		if (!periodInput) throw new AccountingError(400, "getReport balance: period is required");
+		if (!periodInput) throw periodRequired("getReport balance");
 		return getBalanceSheetReport({
 			bookId,
 			period: periodInput
 		});
 	}
 	if (kind === "pl") {
-		if (!periodInput) throw new AccountingError(400, "getReport pl: period is required");
+		if (!periodInput) throw periodRequired("getReport pl");
 		return getProfitLossReport({
 			bookId,
 			period: periodInput
@@ -1919,44 +2125,44 @@ var ACTION_HANDLERS = {
 		bookId: typeof rest.bookId === "string" ? rest.bookId : "",
 		confirm: rest.confirm === true
 	}),
-	[ACCOUNTING_ACTIONS.getAccounts]: (rest) => listAccounts({ bookId: rest.bookId }),
+	[ACCOUNTING_ACTIONS.getAccounts]: (rest) => listAccounts({ bookId: optionalString(rest.bookId) }),
 	[ACCOUNTING_ACTIONS.upsertAccount]: (rest) => upsertAccount({
-		bookId: rest.bookId,
+		bookId: optionalString(rest.bookId),
 		account: rest.account
 	}),
 	[ACCOUNTING_ACTIONS.addEntries]: (rest) => addEntries({
-		bookId: rest.bookId,
-		entries: rest.entries ?? []
+		bookId: optionalString(rest.bookId),
+		entries: rest.entries
 	}),
 	[ACCOUNTING_ACTIONS.voidEntry]: (rest) => voidEntry({
-		bookId: rest.bookId,
+		bookId: optionalString(rest.bookId),
 		entryId: typeof rest.entryId === "string" ? rest.entryId : "",
-		reason: rest.reason,
-		voidDate: rest.voidDate
+		reason: optionalString(rest.reason),
+		voidDate: optionalString(rest.voidDate)
 	}),
 	[ACCOUNTING_ACTIONS.getJournalEntries]: (rest) => listEntries({
-		bookId: rest.bookId,
-		from: rest.from,
-		to: rest.to,
-		accountCode: rest.accountCode
+		bookId: optionalString(rest.bookId),
+		from: optionalString(rest.from),
+		to: optionalString(rest.to),
+		accountCode: optionalString(rest.accountCode)
 	}),
-	[ACCOUNTING_ACTIONS.getOpeningBalances]: (rest) => getOpeningBalances({ bookId: rest.bookId }),
+	[ACCOUNTING_ACTIONS.getOpeningBalances]: (rest) => getOpeningBalances({ bookId: optionalString(rest.bookId) }),
 	[ACCOUNTING_ACTIONS.setOpeningBalances]: (rest) => setOpeningBalances({
-		bookId: rest.bookId,
+		bookId: optionalString(rest.bookId),
 		asOfDate: typeof rest.asOfDate === "string" ? rest.asOfDate : "",
 		lines: rest.lines ?? [],
-		memo: rest.memo
+		memo: optionalString(rest.memo)
 	}),
 	[ACCOUNTING_ACTIONS.getReport]: handleGetReport,
 	[ACCOUNTING_ACTIONS.getTimeSeries]: (rest) => getTimeSeriesReport({
-		bookId: rest.bookId,
+		bookId: optionalString(rest.bookId),
 		metric: rest.metric,
 		granularity: rest.granularity,
 		from: rest.from,
 		to: rest.to,
 		accountCode: rest.accountCode
 	}),
-	[ACCOUNTING_ACTIONS.rebuildSnapshots]: (rest) => rebuildSnapshots({ bookId: rest.bookId })
+	[ACCOUNTING_ACTIONS.rebuildSnapshots]: (rest) => rebuildSnapshots({ bookId: optionalString(rest.bookId) })
 };
 var PREVIEW_ACTIONS = /* @__PURE__ */ new Set([
 	ACCOUNTING_ACTIONS.openBook,
@@ -1975,43 +2181,50 @@ var MESSAGE_BUILDERS = {
 		return `Mounted the accounting app in the canvas${typeof bookId === "string" ? ` (book id: ${bookId})` : ""}.${booksFragment}`;
 	},
 	[ACCOUNTING_ACTIONS.createBook]: (fields) => {
-		const book = fields.book;
-		return `${book?.name ? `A new book named ${JSON.stringify(book.name)}` : "A new book"} has been created${book?.id ? ` (id: ${book.id})` : ""}. Next required step: set opening balances via setOpeningBalances — the journal-entry, ledger, and report tabs are locked until an opening (even an empty one) is saved.`;
+		const book = optionalRecord(fields.book);
+		const name = optionalString(book?.name);
+		const bookId = optionalString(book?.id);
+		return `${name ? `A new book named ${JSON.stringify(name)}` : "A new book"} has been created${bookId ? ` (id: ${bookId})` : ""}. Next required step: set opening balances via setOpeningBalances — the journal-entry, ledger, and report tabs are locked until an opening (even an empty one) is saved.`;
 	},
 	[ACCOUNTING_ACTIONS.upsertAccount]: (fields) => {
-		const account = fields.account;
-		if (account?.code && account?.name) return `Upserted account ${account.code} ${JSON.stringify(account.name)}.`;
+		const account = optionalRecord(fields.account);
+		const code = optionalString(account?.code);
+		const name = optionalString(account?.name);
+		if (code && name) return `Upserted account ${code} ${JSON.stringify(name)}.`;
 		return "Updated the chart of accounts.";
 	},
 	[ACCOUNTING_ACTIONS.addEntries]: (fields) => {
-		const entries = Array.isArray(fields.entries) ? fields.entries : [];
+		const entries = (isUnknownArray(fields.entries) ? fields.entries : []).map(describeEntry);
 		if (entries.length === 0) return "Posted 0 journal entries.";
 		if (entries.length === 1) {
 			const [entry] = entries;
-			const idFragment = entry?.id ? ` (id: ${entry.id})` : "";
-			return `Posted a journal entry on ${entry?.date ?? "the requested date"}${idFragment}.`;
+			const idFragment = entry.id ? ` (id: ${entry.id})` : "";
+			return `Posted a journal entry on ${entry.date ?? "the requested date"}${idFragment}.`;
 		}
-		const summary = entries.map((entry) => `${entry?.date ?? "?"} (id: ${entry?.id ?? "?"})`).join(", ");
+		const summary = entries.map((entry) => `${entry.date ?? "?"} (id: ${entry.id ?? "?"})`).join(", ");
 		return `Posted ${entries.length} journal entries: ${summary}.`;
 	},
 	[ACCOUNTING_ACTIONS.voidEntry]: (fields) => {
-		return `Voided the entry; a reversing pair was posted on ${fields.reverseEntry?.date ?? "today"}.`;
+		return `Voided the entry; a reversing pair was posted on ${optionalString(optionalRecord(fields.reverseEntry)?.date) ?? "today"}.`;
 	},
 	[ACCOUNTING_ACTIONS.setOpeningBalances]: (fields) => {
-		const opening = fields.openingEntry;
+		const opening = optionalRecord(fields.openingEntry);
 		const verb = fields.replacedExisting === true ? "replaced" : "set";
-		const date = opening?.date ?? "the requested date";
-		const lines = Array.isArray(opening?.lines) ? opening.lines : [];
+		const date = optionalString(opening?.date) ?? "the requested date";
+		const openingLines = opening?.lines;
+		const lines = isUnknownArray(openingLines) ? openingLines : [];
 		return `Opening balances were ${verb} as of ${date}.${lines.length > 0 ? ` Lines: ${JSON.stringify(lines)}.` : ""}`;
 	},
 	[ACCOUNTING_ACTIONS.deleteBook]: (fields) => {
-		const bookId = fields.deletedBookId;
-		const name = fields.deletedBookName;
+		const bookId = optionalString(fields.deletedBookId);
+		const name = optionalString(fields.deletedBookName);
 		return `Deleted ${name ? `the book ${JSON.stringify(name)}` : "the book"}${bookId ? ` (id: ${bookId})` : ""}.`;
 	},
 	[ACCOUNTING_ACTIONS.updateBook]: (fields) => {
-		const book = fields.book;
-		return `Updated ${book?.name ? JSON.stringify(book.name) : "the book"}${book?.country ? ` (country: ${book.country})` : ""}.`;
+		const book = optionalRecord(fields.book);
+		const bookName = optionalString(book?.name);
+		const country = optionalString(book?.country);
+		return `Updated ${bookName ? JSON.stringify(bookName) : "the book"}${country ? ` (country: ${country})` : ""}.`;
 	}
 };
 function previewMessage(action, fields) {
@@ -2023,7 +2236,7 @@ async function dispatch(body) {
 	if (!Object.hasOwn(ACTION_HANDLERS, action)) throw new AccountingError(400, `unknown action ${JSON.stringify(action)}`);
 	const handler = ACTION_HANDLERS[action];
 	const result = await handler(rest);
-	const handlerFields = result && typeof result === "object" ? result : { value: result };
+	const handlerFields = isRecord(result) ? result : { value: result };
 	const dataField = PREVIEW_ACTIONS.has(action) ? { data: {
 		action,
 		...handlerFields