tallyd 0.0.0-stage → 0.1.0

package/dist/cli/run.js

@@ -0,0 +1,1660 @@
+/**
+ * The commands.
+ *
+ * `run` is a pure function of its arguments and an environment: it takes the
+ * argv, a filesystem reader and a clock, and returns text plus an exit code.
+ * Nothing here touches `process` or `console`, which is what makes the whole
+ * CLI testable end to end without spawning anything.
+ *
+ * Exit codes carry meaning. Zero is success; 1 is a usage or input problem;
+ * and 2 is reserved for work that ran to completion and came out wrong — a
+ * reconciliation that does not balance, a trial balance that does not agree.
+ * A CI job that treats an unbalanced reconciliation as a pass is worse than no
+ * CI job at all.
+ */
+import { Money } from "../money/money.js";
+import { currency as lookupCurrency } from "../money/currency.js";
+import { addDays, compareDates, date, dateRange, daysBetween } from "../ledger/date.js";
+import { ledgerFromJson, ledgerToJson } from "../ledger/serialise.js";
+import { renderTrialBalance, trialBalance } from "../ledger/trialBalance.js";
+import { importStatement } from "../statement/index.js";
+import { incomeStatement, renderIncomeStatement } from "../reports/incomeStatement.js";
+import { balanceSheet, renderBalanceSheet } from "../reports/balanceSheet.js";
+import { ageing, renderAgeing } from "../reports/ageing.js";
+import { bankView } from "../reconcile/bankView.js";
+import { reconcile, significantReasons } from "../reconcile/matcher.js";
+import { reconciliationBridge, renderReconciliationBridge, statementClosingBalance, } from "../reconcile/bridge.js";
+import { measureAccuracy } from "../reconcile/accuracy.js";
+import { MatchMemory, MemoryDocumentError, renderMemory } from "../reconcile/memory.js";
+import { DecisionDocumentError, decisionsFor } from "../reconcile/decisions.js";
+import { generateBooks, statementCsv, } from "../demo/generator.js";
+import { dashboardData } from "../dashboard/model.js";
+import { renderDashboard } from "../dashboard/render.js";
+import { applyProposals, parseRules, PostingRuleError, proposeEntries, renderProposals, linesNeedingEntries, standardRules, summariseProposals, } from "../reconcile/posting.js";
+import { averageRate } from "../fx/average.js";
+import { GroupDocumentError, groupFromJson } from "../group/document.js";
+import { renderAggregation } from "../group/aggregate.js";
+import { renderEliminations } from "../group/intercompany.js";
+import { renderAcquisition } from "../group/acquisition.js";
+import { renderDisposal } from "../group/disposal.js";
+import { consolidate, renderConsolidation } from "../group/consolidate.js";
+import { compareConsolidations, renderComparative } from "../group/comparative.js";
+import { renderMovementSchedule, renderNetAssetsMovements } from "../group/movement.js";
+import { renderControlWindows } from "../group/timeline.js";
+import { GroupError } from "../group/structure.js";
+import { exposures, renderExposures } from "../fx/exposure.js";
+import { TranslationError, renderTranslation, translate, } from "../fx/translate.js";
+import { RevaluationError, renderRevaluation, revalue, } from "../fx/revaluation.js";
+import { RateDocumentError, ratesFromText } from "../fx/document.js";
+import { RateTable } from "../fx/table.js";
+import { ArgumentError, booleanFlag, parseArgs, renderFlags, requiredFlag, stringFlag, } from "./args.js";
+const COMMON = {
+    ledger: { kind: "string", short: "l", describe: "Ledger document (JSON)", placeholder: "file" },
+    json: { kind: "boolean", describe: "Emit JSON instead of text" },
+};
+const COMMANDS = {
+    report: {
+        describe: "Trial balance, income statement and balance sheet",
+        flags: {
+            ...COMMON,
+            "as-at": { kind: "string", describe: "Balance sheet date (default: today)", placeholder: "date" },
+            from: { kind: "string", describe: "Start of the income statement period", placeholder: "date" },
+            to: { kind: "string", describe: "End of the income statement period", placeholder: "date" },
+            compare: { kind: "string", describe: "Comparative period, as from:to", placeholder: "a:b" },
+            present: { kind: "string", short: "p", describe: "Also present the trial balance in this currency", placeholder: "code" },
+            rates: { kind: "string", short: "r", describe: "Rate table for --present (JSON or CSV)", placeholder: "file" },
+            base: { kind: "string", short: "b", describe: "Base currency for a CSV of bare currency columns", placeholder: "code" },
+            equity: { kind: "string", describe: "Translate equity at historical (default) or closing rates", placeholder: "how" },
+            "average-method": { kind: "string", describe: "daily (default) or quoted, for the P&L rate", placeholder: "how" },
+            stale: { kind: "string", describe: "Days a quote may be behind the date asked for", placeholder: "days" },
+        },
+    },
+    ageing: {
+        describe: "Outstanding items on a control account, bucketed by age",
+        flags: {
+            ...COMMON,
+            account: { kind: "string", short: "a", describe: "Control account code", placeholder: "code" },
+            "as-at": { kind: "string", describe: "Ageing date (default: today)", placeholder: "date" },
+            buckets: { kind: "string", describe: "Bucket boundaries in days (default 30,60,90)", placeholder: "n,n,n" },
+        },
+    },
+    reconcile: {
+        describe: "Match a bank statement against the ledger and print the review queue",
+        flags: {
+            ...COMMON,
+            statement: { kind: "string", short: "s", describe: "Bank statement (CSV or OFX)", placeholder: "file" },
+            account: { kind: "string", short: "a", describe: "Bank account code", placeholder: "code" },
+            currency: { kind: "string", describe: "Statement currency (default: the chart's)", placeholder: "code" },
+            "date-window": { kind: "string", describe: "Days either side a pair may differ", placeholder: "days" },
+            "no-groups": { kind: "boolean", describe: "Disable one-to-many matching" },
+            memory: { kind: "string", short: "m", describe: "Confirmed counterparties (JSON)", placeholder: "file" },
+        },
+    },
+    import: {
+        describe: "Show what the statement reader made of a file, without matching",
+        flags: {
+            statement: { kind: "string", short: "s", describe: "Bank statement (CSV or OFX)", placeholder: "file" },
+            currency: { kind: "string", describe: "Statement currency (default GBP)", placeholder: "code" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    accounts: {
+        describe: "Render the chart of accounts",
+        flags: { ...COMMON },
+    },
+    generate: {
+        describe: "Write a synthetic ledger and the bank statement that goes with it",
+        flags: {
+            out: { kind: "string", short: "o", describe: "Directory to write into", placeholder: "dir" },
+            seed: { kind: "string", describe: "Same seed, same books (default 1)", placeholder: "n" },
+            months: { kind: "string", describe: "Months to generate (default 3)", placeholder: "n" },
+            invoices: { kind: "string", describe: "Invoices a month (default 12)", placeholder: "n" },
+            start: { kind: "string", describe: "First day (default 2026-01-01)", placeholder: "date" },
+            currency: { kind: "string", describe: "Currency (default GBP)", placeholder: "code" },
+            truth: { kind: "boolean", describe: "Also write the ground-truth links as JSON" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    bench: {
+        describe: "Time the matcher over generated books of increasing size",
+        flags: {
+            seed: { kind: "string", describe: "Same seed, same books (default 1)", placeholder: "n" },
+            sizes: {
+                kind: "string",
+                describe: "Sizes as months:invoices (default 1:10,3:12,6:15,12:15)",
+                placeholder: "m:i,...",
+            },
+            repeat: { kind: "string", describe: "Runs per size, fastest wins (default 1)", placeholder: "n" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    dashboard: {
+        describe: "Write a self-contained HTML reconciliation dashboard",
+        flags: {
+            ledger: { kind: "string", short: "l", describe: "Ledger document (JSON)", placeholder: "file" },
+            statement: { kind: "string", short: "s", describe: "Bank statement (CSV or OFX)", placeholder: "file" },
+            account: { kind: "string", short: "a", describe: "Bank account code", placeholder: "code" },
+            out: { kind: "string", short: "o", describe: "Where to write the HTML", placeholder: "file" },
+            currency: { kind: "string", describe: "Statement currency (default: the chart's)", placeholder: "code" },
+            "date-window": { kind: "string", describe: "Days either side a pair may differ", placeholder: "days" },
+            "no-groups": { kind: "boolean", describe: "Disable one-to-many matching" },
+            memory: { kind: "string", short: "m", describe: "Confirmed counterparties (JSON)", placeholder: "file" },
+            rules: { kind: "string", short: "r", describe: "Classification rules for the implied entries (JSON)", placeholder: "file" },
+            suspense: { kind: "string", describe: "Existing account for lines no rule matched", placeholder: "code" },
+        },
+    },
+    post: {
+        describe: "Propose the journal entries a reconciled statement implies",
+        flags: {
+            ledger: { kind: "string", short: "l", describe: "Ledger document (JSON)", placeholder: "file" },
+            statement: { kind: "string", short: "s", describe: "Bank statement (CSV or OFX)", placeholder: "file" },
+            account: { kind: "string", short: "a", describe: "Bank account code", placeholder: "code" },
+            decisions: { kind: "string", short: "d", describe: "Reviewed decisions from the dashboard (JSON)", placeholder: "file" },
+            rules: { kind: "string", short: "r", describe: "Classification rules (JSON); the built-in set is used otherwise", placeholder: "file" },
+            suspense: { kind: "string", describe: "Existing account for lines no rule matched", placeholder: "code" },
+            out: { kind: "string", short: "o", describe: "Write the ledger with the entries applied", placeholder: "file" },
+            currency: { kind: "string", describe: "Statement currency (default: the chart's)", placeholder: "code" },
+            "date-window": { kind: "string", describe: "Days either side a pair may differ", placeholder: "days" },
+            "no-groups": { kind: "boolean", describe: "Disable one-to-many matching" },
+            memory: { kind: "string", short: "m", describe: "Confirmed counterparties (JSON)", placeholder: "file" },
+            strict: { kind: "boolean", describe: "Exit 2 when any line could not be classified" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    rates: {
+        describe: "Inspect a rate table, price a pair on a date, convert an amount",
+        flags: {
+            rates: { kind: "string", short: "r", describe: "Rate table (JSON or CSV)", placeholder: "file" },
+            base: { kind: "string", short: "b", describe: "Base currency for a CSV of bare currency columns", placeholder: "code" },
+            invert: { kind: "boolean", describe: "The CSV quotes the base per unit of the column" },
+            pair: { kind: "string", short: "p", describe: "Pair to price, as BASE/QUOTE", placeholder: "a/b" },
+            on: { kind: "string", describe: "Date to price it on (default: today)", placeholder: "date" },
+            amount: { kind: "string", describe: "Convert this amount from the pair's base", placeholder: "n" },
+            average: { kind: "string", describe: "Average over a period instead, as from:to", placeholder: "a:b" },
+            method: { kind: "string", describe: "Average method: daily (default) or quoted", placeholder: "how" },
+            stale: { kind: "string", describe: "Days a quote may be behind the date asked for", placeholder: "days" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    revalue: {
+        describe: "Retranslate foreign-currency balances at a closing rate",
+        flags: {
+            ledger: { kind: "string", short: "l", describe: "Ledger document (JSON)", placeholder: "file" },
+            rates: { kind: "string", short: "r", describe: "Rate table (JSON or CSV)", placeholder: "file" },
+            base: { kind: "string", short: "b", describe: "Base currency for a CSV of bare currency columns", placeholder: "code" },
+            "as-at": { kind: "string", describe: "Closing date (default: today)", placeholder: "date" },
+            out: { kind: "string", short: "o", describe: "Write the ledger with the revaluation applied", placeholder: "file" },
+            gain: { kind: "string", describe: "Income account for a net gain (default 4400)", placeholder: "code" },
+            loss: { kind: "string", describe: "Expense account for a net loss (default 5950)", placeholder: "code" },
+            exclude: { kind: "string", describe: "Accounts to leave alone, comma-separated", placeholder: "a,b" },
+            stale: { kind: "string", describe: "Days a quote may be behind the closing date", placeholder: "days" },
+            show: { kind: "boolean", describe: "Print the exposures and stop, without revaluing" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    consolidate: {
+        describe: "Consolidate a group of companies into one set of accounts",
+        flags: {
+            group: { kind: "string", short: "g", describe: "Group document (JSON)", placeholder: "file" },
+            rates: { kind: "string", short: "r", describe: "Rate table (JSON or CSV)", placeholder: "file" },
+            base: { kind: "string", short: "b", describe: "Base currency for a CSV of bare currency columns", placeholder: "code" },
+            "as-at": { kind: "string", describe: "Reporting date (default: the group document's)", placeholder: "date" },
+            from: { kind: "string", describe: "Start of the reporting period", placeholder: "date" },
+            to: { kind: "string", describe: "End of the reporting period", placeholder: "date" },
+            comparative: { kind: "string", describe: "Consolidate at this date too and show both columns", placeholder: "date" },
+            "comparative-from": { kind: "string", describe: "Start of the comparative period (default: the same length)", placeholder: "date" },
+            show: { kind: "string", describe: "workings (default), combined, eliminations, windows, movement, statements or all", placeholder: "what" },
+            "average-method": { kind: "string", describe: "daily (default) or quoted, for the P&L rate", placeholder: "how" },
+            stale: { kind: "string", describe: "Days a quote may be behind the date asked for", placeholder: "days" },
+            out: { kind: "string", short: "o", describe: "Write the consolidated ledger as a document", placeholder: "file" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+    learn: {
+        describe: "Fold reviewed decisions into the counterparty memory",
+        flags: {
+            memory: { kind: "string", short: "m", describe: "Memory file, created if absent", placeholder: "file" },
+            decisions: { kind: "string", short: "d", describe: "Reviewed decisions (JSON)", placeholder: "file" },
+            show: { kind: "boolean", describe: "Print what is remembered and write nothing" },
+            json: { kind: "boolean", describe: "Emit JSON instead of text" },
+        },
+    },
+};
+function usage() {
+    const width = Math.max(...Object.keys(COMMANDS).map((name) => name.length));
+    const lines = [
+        "tallyd — double-entry ledger and bank reconciliation",
+        "",
+        "Usage: tallyd <command> [options]",
+        "",
+        "Commands:",
+        ...Object.entries(COMMANDS).map(([name, command]) => `  ${name.padEnd(width + 2)}${command.describe}`),
+        "",
+        "Run 'tallyd <command> --help' for the options of a command.",
+        "",
+        "Exit codes: 0 success, 1 bad input, 2 the books do not agree.",
+    ];
+    return lines.join("\n");
+}
+function commandHelp(name) {
+    const command = COMMANDS[name];
+    return [`tallyd ${name} — ${command.describe}`, "", "Options:", renderFlags(command.flags)].join("\n");
+}
+function loadLedger(environment, path) {
+    return ledgerFromJson(environment.readFile(path));
+}
+function parseBoundaries(text) {
+    if (text === undefined)
+        return undefined;
+    const values = text
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "")
+        .map((part) => {
+        const value = Number(part);
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new ArgumentError(`--buckets wants positive whole numbers, got "${part}"`);
+        }
+        return value;
+    });
+    if (values.length === 0)
+        throw new ArgumentError("--buckets needs at least one boundary");
+    return values;
+}
+/**
+ * The memory named by `--memory`, or an empty one.
+ *
+ * A missing file is not an error the first time round: a reviewer who has not
+ * confirmed anything yet has an empty memory, and asking them to create a file
+ * full of nothing before they can reconcile would be silly.
+ */
+function loadMemory(environment, path) {
+    if (path === undefined)
+        return MatchMemory.empty();
+    try {
+        return MatchMemory.fromJson(environment.readFile(path));
+    }
+    catch (error) {
+        if (error instanceof MemoryDocumentError)
+            throw error;
+        return MatchMemory.empty();
+    }
+}
+/**
+ * Resolve the account to reconcile against.
+ *
+ * A grouping account is refused rather than reconciled. It exists in the chart
+ * and nothing has ever been posted to it, so reconciling it "succeeds": no
+ * ledger movements, no matches, and a bridge that is out by the entire
+ * statement while reporting nothing wrong. That is the worst kind of wrong
+ * answer, because it looks like an answer.
+ */
+function bankAccountFor(ledger, requested) {
+    if (requested !== undefined) {
+        const chart = ledger.chart;
+        if (chart !== undefined) {
+            if (!chart.has(requested)) {
+                throw new ArgumentError(`No account ${requested} in the chart`);
+            }
+            if (!chart.isPostable(requested)) {
+                const account = chart.get(requested);
+                const children = chart.children(requested).map((child) => child.code);
+                const advice = children.length > 0 ? `; reconcile one of ${children.join(", ")}` : "";
+                throw new ArgumentError(`Account ${requested} (${account.name}) cannot be posted to, so there is nothing to ` +
+                    `reconcile against it${advice}`);
+            }
+        }
+        return requested;
+    }
+    // "1110" is the bank account in the standard chart; fall back to the first
+    // posted asset account so an unusual chart still works without a flag.
+    if (ledger.chart?.has("1110") === true)
+        return "1110";
+    const asset = ledger.activeAccounts().find((code) => ledger.chart?.find(code)?.type === "asset");
+    if (asset === undefined) {
+        throw new ArgumentError("Could not guess the bank account; pass --account");
+    }
+    return asset;
+}
+// ------------------------------------------------------------------ commands
+function reportCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["report"].flags);
+    const ledger = loadLedger(environment, requiredFlag(parsed, "ledger"));
+    const asAtText = stringFlag(parsed, "as-at");
+    const asAt = asAtText === undefined ? environment.today() : date(asAtText);
+    const from = stringFlag(parsed, "from");
+    const to = stringFlag(parsed, "to");
+    const period = dateRange(from ?? "0001-01-01", to ?? asAt);
+    const compare = stringFlag(parsed, "compare");
+    let comparative;
+    if (compare !== undefined) {
+        const parts = compare.split(":");
+        if (parts.length !== 2)
+            throw new ArgumentError("--compare wants from:to");
+        comparative = dateRange(parts[0], parts[1]);
+    }
+    const balances = trialBalance(ledger, { asAt });
+    const profit = incomeStatement(ledger, period, comparative === undefined ? {} : { comparative });
+    const sheet = balanceSheet(ledger, asAt);
+    const agrees = balances.balanced && sheet.balanced;
+    // The books stay in the currency they are kept in; presenting is an extra
+    // reading of them, printed alongside rather than instead.
+    const presentIn = stringFlag(parsed, "present");
+    let translated;
+    if (presentIn !== undefined) {
+        const equityText = stringFlag(parsed, "equity") ?? "historical";
+        if (equityText !== "historical" && equityText !== "closing") {
+            throw new ArgumentError(`--equity wants historical or closing, got "${equityText}"`);
+        }
+        const methodText = stringFlag(parsed, "average-method") ?? "daily";
+        if (methodText !== "daily" && methodText !== "quoted") {
+            throw new ArgumentError(`--average-method wants daily or quoted, got "${methodText}"`);
+        }
+        const rates = stringFlag(parsed, "rates") === undefined ? RateTable.empty() : loadRates(environment, parsed);
+        try {
+            translated = translate(ledger, {
+                presentation: presentIn,
+                rates,
+                asAt,
+                period,
+                equityBasis: equityText,
+                averageMethod: methodText,
+            });
+        }
+        catch (error) {
+            if (error instanceof TranslationError)
+                throw new ArgumentError(error.message);
+            throw error;
+        }
+    }
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                asAt,
+                period: { from: period.from, to: period.to },
+                trialBalance: {
+                    balanced: balances.balanced,
+                    totalDebit: balances.totalDebit.toDecimalString(),
+                    totalCredit: balances.totalCredit.toDecimalString(),
+                },
+                incomeStatement: {
+                    income: profit.income.total.toDecimalString(),
+                    expenses: profit.expenses.total.toDecimalString(),
+                    netResult: profit.netResult.toDecimalString(),
+                },
+                balanceSheet: {
+                    assets: sheet.assets.total.toDecimalString(),
+                    liabilities: sheet.liabilities.total.toDecimalString(),
+                    equity: sheet.equity.total.toDecimalString(),
+                    balanced: sheet.balanced,
+                },
+                ...(translated === undefined
+                    ? {}
+                    : {
+                        presented: {
+                            currency: translated.presentation.code,
+                            closingRate: translated.closingRate?.toDecimalString(10) ?? null,
+                            averageRate: translated.averageRate?.toDecimalString(10) ?? null,
+                            averageMethod: translated.averageMethod,
+                            translationAdjustment: translated.translationAdjustment.toDecimalString(),
+                            totalDebit: translated.totalDebit.toDecimalString(),
+                            totalCredit: translated.totalCredit.toDecimalString(),
+                            rows: translated.rows.map((row) => ({
+                                account: row.account,
+                                name: row.name,
+                                basis: row.basis,
+                                functional: row.functional.toDecimalString(),
+                                presentation: row.presentation.toDecimalString(),
+                                rate: row.effectiveRate?.toDecimalString(10) ?? null,
+                            })),
+                        },
+                    }),
+            }, null, 2),
+            stderr: "",
+            code: agrees ? 0 : 2,
+        };
+    }
+    return {
+        stdout: [
+            renderTrialBalance(balances),
+            "",
+            renderIncomeStatement(profit),
+            "",
+            renderBalanceSheet(sheet),
+            ...(translated === undefined ? [] : ["", renderTranslation(translated)]),
+        ].join("\n"),
+        stderr: agrees ? "" : "The books do not agree; see the differences above.\n",
+        code: agrees ? 0 : 2,
+    };
+}
+function ageingCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["ageing"].flags);
+    const ledger = loadLedger(environment, requiredFlag(parsed, "ledger"));
+    const account = requiredFlag(parsed, "account");
+    const asAtText = stringFlag(parsed, "as-at");
+    const asAt = asAtText === undefined ? environment.today() : date(asAtText);
+    const boundaries = parseBoundaries(stringFlag(parsed, "buckets"));
+    const report = ageing(ledger, account, asAt, boundaries === undefined ? {} : { boundaries });
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                account: report.account,
+                asAt: report.asAt,
+                total: report.total.toDecimalString(),
+                buckets: report.buckets.map((bucket) => ({
+                    label: bucket.label,
+                    total: bucket.total.toDecimalString(),
+                    count: bucket.items.length,
+                })),
+                items: report.items.map((item) => ({
+                    reference: item.reference,
+                    raised: item.raised,
+                    days: item.daysOutstanding,
+                    outstanding: item.outstanding.toDecimalString(),
+                })),
+            }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    return { stdout: renderAgeing(report), stderr: "", code: 0 };
+}
+function reconciliationFor(environment, parsed, extraDecisions = []) {
+    const ledger = loadLedger(environment, requiredFlag(parsed, "ledger"));
+    const account = bankAccountFor(ledger, stringFlag(parsed, "account"));
+    const raw = environment.readFile(requiredFlag(parsed, "statement"));
+    const currencyCode = stringFlag(parsed, "currency") ??
+        ledger.chart?.find(account)?.currency.code ??
+        ledger.currenciesUsed()[0] ??
+        "GBP";
+    const imported = importStatement(raw, { currency: lookupCurrency(currencyCode), idPrefix: "BANK" });
+    const options = {};
+    const windowText = stringFlag(parsed, "date-window");
+    if (windowText !== undefined) {
+        const days = Number(windowText);
+        if (!Number.isInteger(days) || days < 0) {
+            throw new ArgumentError(`--date-window wants a whole number of days, got "${windowText}"`);
+        }
+        options.dateWindowDays = days;
+    }
+    if (booleanFlag(parsed, "no-groups"))
+        options.groupMatching = false;
+    const memory = loadMemory(environment, stringFlag(parsed, "memory")).learnAll(extraDecisions);
+    if (memory.size > 0)
+        options.memory = memory;
+    const books = bankView(ledger, account, { currency: currencyCode });
+    const result = reconcile(books, imported.lines, options);
+    return {
+        ledger,
+        account,
+        currencyCode,
+        imported,
+        books,
+        result,
+        memory,
+        bankClosingBalance: statementClosingBalance(imported.lines, Money.zero(currencyCode)),
+        bookClosingBalance: books.reduce((total, line) => total.plus(line.amount), Money.zero(currencyCode)),
+    };
+}
+function reconcileCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["reconcile"].flags);
+    const run = reconciliationFor(environment, parsed);
+    const { account, imported, result, memory } = run;
+    const bridge = reconciliationBridge(result, {
+        bankClosingBalance: run.bankClosingBalance,
+        bookClosingBalance: run.bookClosingBalance,
+    });
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                account,
+                format: imported.format,
+                statementLines: result.stats.statementLines,
+                bookLines: result.stats.bookLines,
+                matched: result.matched.map((match) => ({
+                    kind: match.kind,
+                    score: Number(match.scored.score.toFixed(4)),
+                    confidence: match.scored.confidence,
+                    book: match.book.map((line) => line.id),
+                    statement: match.statement.map((line) => line.id),
+                })),
+                suggested: result.suggested.map((match) => ({
+                    kind: match.kind,
+                    score: Number(match.scored.score.toFixed(4)),
+                    reasons: significantReasons(match),
+                    book: match.book.map((line) => line.id),
+                    statement: match.statement.map((line) => line.id),
+                })),
+                unmatchedBook: result.unmatchedBook.map((line) => line.id),
+                unmatchedStatement: result.unmatchedStatement.map((line) => line.id),
+                bridge: {
+                    bankClosingBalance: bridge.bankClosingBalance.toDecimalString(),
+                    bookClosingBalance: bridge.bookClosingBalance.toDecimalString(),
+                    adjustedBankBalance: bridge.adjustedBankBalance.toDecimalString(),
+                    adjustedBookBalance: bridge.adjustedBookBalance.toDecimalString(),
+                    difference: bridge.difference.toDecimalString(),
+                    reconciled: bridge.reconciled,
+                },
+            }, null, 2),
+            stderr: "",
+            code: bridge.reconciled ? 0 : 2,
+        };
+    }
+    const out = [];
+    out.push(`Reconciling ${account} against ${result.stats.statementLines} statement lines`);
+    if (memory.size > 0) {
+        out.push(`  ${memory.size} remembered ${memory.size === 1 ? "counterparty" : "counterparties"} in play`);
+    }
+    out.push(`  ${result.matched.length} matched, ${result.suggested.length} to review, ` +
+        `${result.unmatchedBook.length} + ${result.unmatchedStatement.length} unmatched`);
+    out.push("");
+    if (result.matched.length > 0) {
+        out.push("Matched");
+        for (const match of result.matched) {
+            out.push(`  ${match.scored.confidence.padEnd(7)}${match.scored.score.toFixed(3)}  ` +
+                `${match.statement.map((line) => `${line.date} ${line.description}`).join(" + ")}`);
+        }
+        out.push("");
+    }
+    if (result.suggested.length > 0) {
+        out.push("Review queue");
+        for (const match of result.suggested) {
+            out.push(`  ${match.scored.confidence.padEnd(7)}${match.scored.score.toFixed(3)}  ` +
+                `${match.statement.map((line) => `${line.date} ${line.description}`).join(" + ")}`);
+            for (const reason of significantReasons(match))
+                out.push(`      · ${reason}`);
+        }
+        out.push("");
+    }
+    out.push(renderReconciliationBridge(bridge));
+    return {
+        stdout: out.join("\n"),
+        stderr: bridge.reconciled ? "" : "The reconciliation does not balance.\n",
+        code: bridge.reconciled ? 0 : 2,
+    };
+}
+function importCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["import"].flags);
+    const raw = environment.readFile(requiredFlag(parsed, "statement"));
+    const currencyCode = stringFlag(parsed, "currency") ?? "GBP";
+    const imported = importStatement(raw, { currency: lookupCurrency(currencyCode), idPrefix: "BANK" });
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                format: imported.format,
+                warnings: imported.warnings,
+                errors: imported.errors.map((error) => ({ row: error.row, reason: error.reason })),
+                lines: imported.lines.map((line) => ({
+                    id: line.id,
+                    date: line.date,
+                    description: line.description,
+                    amount: line.amount.toDecimalString(),
+                })),
+            }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    const out = [];
+    out.push(`Bank statement — ${imported.format.toUpperCase()}`);
+    out.push(`  ${imported.lines.length} lines, ${imported.errors.length} errors`);
+    for (const warning of imported.warnings)
+        out.push(`  warning: ${warning}`);
+    out.push("");
+    for (const line of imported.lines) {
+        out.push(`  ${line.date}  ${line.amount.toDecimalString().padStart(12)}  ${line.description}`);
+    }
+    return { stdout: out.join("\n"), stderr: "", code: imported.errors.length === 0 ? 0 : 2 };
+}
+function accountsCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["accounts"].flags);
+    const ledger = loadLedger(environment, requiredFlag(parsed, "ledger"));
+    if (ledger.chart === undefined) {
+        return { stdout: "", stderr: "This ledger has no chart of accounts.\n", code: 1 };
+    }
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify(ledger.chart.toDefinitions(), null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    return { stdout: ledger.chart.render(), stderr: "", code: 0 };
+}
+function dashboardCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["dashboard"].flags);
+    const out = requiredFlag(parsed, "out");
+    if (environment.writeFile === undefined) {
+        throw new ArgumentError("This environment cannot write files");
+    }
+    const run = reconciliationFor(environment, parsed);
+    const { ledger, account, imported, books, result, bankClosingBalance, bookClosingBalance } = run;
+    // Every statement line gets a proposal, not only the ones currently
+    // unmatched: the page decides which are live from its own leftovers, so a
+    // rejection has to have something to show the moment it is made.
+    const implied = proposeEntries(imported.lines, {
+        account,
+        rules: rulesFor(environment, parsed),
+        ledger,
+        ...(stringFlag(parsed, "suspense") === undefined
+            ? {}
+            : { suspenseAccount: stringFlag(parsed, "suspense") }),
+    });
+    const html = renderDashboard(dashboardData({
+        ledger,
+        account,
+        books,
+        statement: imported.lines,
+        result,
+        bankClosingBalance,
+        bookClosingBalance,
+        statementFormat: imported.format,
+        implied,
+    }));
+    environment.writeFile(out, html);
+    const bridge = reconciliationBridge(result, { bankClosingBalance, bookClosingBalance });
+    return {
+        stdout: `Wrote ${out} — ${result.matched.length} matched, ${result.suggested.length} to review, ${Math.round(html.length / 1024)} KB, no network needed.`,
+        stderr: bridge.reconciled ? "" : "The reconciliation does not balance.\n",
+        code: bridge.reconciled ? 0 : 2,
+    };
+}
+// ------------------------------------------------------ generate and bench
+/** A positive whole number from a flag, or the default. */
+function countFlag(parsed, name, fallback) {
+    const text = stringFlag(parsed, name);
+    if (text === undefined)
+        return fallback;
+    const value = Number(text);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new ArgumentError(`--${name} wants a positive whole number, got "${text}"`);
+    }
+    return value;
+}
+function generatorOptionsFrom(parsed) {
+    const options = {
+        seed: countFlag(parsed, "seed", 1),
+        months: countFlag(parsed, "months", 3),
+        invoicesPerMonth: countFlag(parsed, "invoices", 12),
+    };
+    const start = stringFlag(parsed, "start");
+    const code = stringFlag(parsed, "currency");
+    return {
+        ...options,
+        ...(start === undefined ? {} : { start: date(start) }),
+        ...(code === undefined ? {} : { currency: lookupCurrency(code) }),
+    };
+}
+function generateCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["generate"].flags);
+    if (environment.writeFile === undefined) {
+        return { stdout: "", stderr: "This environment cannot write files.\n", code: 1 };
+    }
+    const directory = stringFlag(parsed, "out") ?? ".";
+    const generated = generateBooks(generatorOptionsFrom(parsed));
+    const ledgerPath = `${directory}/books.json`;
+    const statementPath = `${directory}/statement.csv`;
+    environment.writeFile(ledgerPath, ledgerToJson(generated.ledger));
+    environment.writeFile(statementPath, statementCsv(generated));
+    const written = [ledgerPath, statementPath];
+    if (booleanFlag(parsed, "truth")) {
+        const truthPath = `${directory}/truth.json`;
+        environment.writeFile(truthPath, `${JSON.stringify(generated.truth, null, 2)}\n`);
+        written.push(truthPath);
+    }
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({ written, summary: generated.summary }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    const summary = generated.summary;
+    return {
+        stdout: [
+            `Wrote ${written.join(", ")}`,
+            `  ${summary.entries} journal entries, ${summary.statementLines} statement lines`,
+            `  ${summary.explainable} lines a matcher could explain, of which ${summary.grouped} are batches`,
+            `  ${summary.bankOnly} bank-only, ${summary.ledgerOnly} still outstanding`,
+        ].join("\n"),
+        stderr: "",
+        code: 0,
+    };
+}
+function parseSizes(text) {
+    if (text === undefined) {
+        return [
+            { months: 1, invoices: 10 },
+            { months: 3, invoices: 12 },
+            { months: 6, invoices: 15 },
+            { months: 12, invoices: 15 },
+        ];
+    }
+    const sizes = text
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "")
+        .map((part) => {
+        const [months, invoices] = part.split(":");
+        const m = Number(months);
+        const i = Number(invoices);
+        if (!Number.isInteger(m) || m <= 0 || !Number.isInteger(i) || i <= 0) {
+            throw new ArgumentError(`--sizes wants months:invoices pairs, got "${part}"`);
+        }
+        return { months: m, invoices: i };
+    });
+    if (sizes.length === 0)
+        throw new ArgumentError("--sizes needs at least one size");
+    return sizes;
+}
+/**
+ * Time the matcher, and check it is still right while doing so.
+ *
+ * A benchmark that only reports wall time is a benchmark that will eventually
+ * celebrate a matcher that stopped matching. The generator knows which lines
+ * really belong together, so every timed run is scored against that too, and
+ * the accuracy columns sit next to the milliseconds.
+ */
+function benchCommand(_environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["bench"].flags);
+    const seed = countFlag(parsed, "seed", 1);
+    const repeat = countFlag(parsed, "repeat", 1);
+    const sizes = parseSizes(stringFlag(parsed, "sizes"));
+    const rows = sizes.map((size) => {
+        const generated = generateBooks({
+            seed,
+            months: size.months,
+            invoicesPerMonth: size.invoices,
+        });
+        const books = bankView(generated.ledger, generated.bankAccount);
+        let best = Number.POSITIVE_INFINITY;
+        let result = reconcile(books, generated.statement);
+        for (let run = 0; run < repeat; run++) {
+            const started = performance.now();
+            result = reconcile(books, generated.statement);
+            best = Math.min(best, performance.now() - started);
+        }
+        const accuracy = measureAccuracy(result, generated.truth);
+        const cross = books.length * generated.statement.length;
+        return {
+            months: size.months,
+            invoices: size.invoices,
+            bookLines: books.length,
+            statementLines: generated.statement.length,
+            milliseconds: Number(best.toFixed(1)),
+            pairsScored: result.stats.pairsScored,
+            /** Share of the full cross product that reached the scorer. */
+            scoredShare: cross === 0 ? 0 : Number((result.stats.pairsScored / cross).toFixed(5)),
+            precision: Number(accuracy.precision.toFixed(4)),
+            recall: Number(accuracy.recall.toFixed(4)),
+            recallWithSuggestions: Number(accuracy.recallWithSuggestions.toFixed(4)),
+        };
+    });
+    if (booleanFlag(parsed, "json")) {
+        return { stdout: JSON.stringify({ seed, repeat, rows }, null, 2), stderr: "", code: 0 };
+    }
+    const header = ["size", "books", "lines", "ms", "scored", "prec", "rec", "rec+"];
+    const body = rows.map((row) => [
+        `${row.months}m x${row.invoices}`,
+        String(row.bookLines),
+        String(row.statementLines),
+        row.milliseconds.toFixed(1),
+        `${(row.scoredShare * 100).toFixed(2)}%`,
+        `${(row.precision * 100).toFixed(1)}%`,
+        `${(row.recall * 100).toFixed(1)}%`,
+        `${(row.recallWithSuggestions * 100).toFixed(1)}%`,
+    ]);
+    const widths = header.map((cell, column) => Math.max(cell.length, ...body.map((row) => row[column].length)));
+    const format = (cells) => cells.map((cell, column) => cell.padStart(widths[column])).join("  ");
+    return {
+        stdout: [
+            `Matcher over generated books, seed ${seed}, best of ${repeat}`,
+            "",
+            format(header),
+            ...body.map(format),
+            "",
+            "scored is the share of all possible pairs that reached the scorer;",
+            "rec+ counts a correct suggestion as found, which is what a reviewer sees.",
+        ].join("\n"),
+        stderr: "",
+        code: 0,
+    };
+}
+/**
+ * Fold a reviewer's decisions into the memory.
+ *
+ * The decisions file is deliberately dumb: a list of `{ statement, book,
+ * accepted, on }`. That is what a review UI can emit, what a script can build
+ * from a spreadsheet, and what a person can write by hand when they want to
+ * teach the matcher one thing without clicking through a queue to do it.
+ */
+function learnCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["learn"].flags);
+    const memoryPath = requiredFlag(parsed, "memory");
+    const existing = loadMemory(environment, memoryPath);
+    if (booleanFlag(parsed, "show")) {
+        if (booleanFlag(parsed, "json")) {
+            return { stdout: JSON.stringify(existing.toDocument(), null, 2), stderr: "", code: 0 };
+        }
+        return { stdout: renderMemory(existing), stderr: "", code: 0 };
+    }
+    if (environment.writeFile === undefined) {
+        return { stdout: "", stderr: "This environment cannot write files.\n", code: 1 };
+    }
+    const decisions = readDecisions(environment, requiredFlag(parsed, "decisions"));
+    const updated = existing.learnAll(decisions);
+    environment.writeFile(memoryPath, updated.toJson());
+    const learned = updated.size - existing.size;
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({ memory: memoryPath, decisions: decisions.length, pairings: updated.size, new: learned }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    return {
+        stdout: [
+            `Read ${decisions.length} ${decisions.length === 1 ? "decision" : "decisions"}, wrote ${memoryPath}`,
+            `  ${updated.size} ${updated.size === 1 ? "pairing" : "pairings"} remembered, ${learned} new`,
+        ].join("\n"),
+        stderr: "",
+        code: 0,
+    };
+}
+/**
+ * Book what the statement says happened and the books do not know about.
+ *
+ * Only lines the matcher left *entirely* unexplained are proposed. A line
+ * sitting in the review queue has a ledger counterpart the matcher believes
+ * in; booking an entry for it as well would double-count it. Undecided means
+ * unproposed, which is the conservative reading and the right one.
+ *
+ * Decisions reach this command through the memory rather than through match
+ * ids. The decisions file has no ids in it on purpose — an id only means
+ * something against the exact reconciliation that produced it — so a
+ * confirmation raises the pair's score until it matches outright, and a
+ * rejection pushes it down until the statement line falls out of the queue and
+ * becomes something to book. The mechanism was already there; this command
+ * just points it at the right question.
+ */
+function postCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["post"].flags);
+    const decisionsPath = stringFlag(parsed, "decisions");
+    const decisions = decisionsPath === undefined ? [] : readDecisions(environment, decisionsPath);
+    const run = reconciliationFor(environment, parsed, decisions);
+    const { ledger, account, currencyCode, result, memory } = run;
+    const needing = linesNeedingEntries(result, memory);
+    const rules = rulesFor(environment, parsed);
+    const suspense = stringFlag(parsed, "suspense");
+    if (suspense !== undefined && ledger.chart?.isPostable(suspense) === false) {
+        throw new ArgumentError(`The suspense account ${suspense} is not one this chart can post to`);
+    }
+    const options = {
+        account,
+        rules,
+        ledger,
+        ...(suspense === undefined ? {} : { suspenseAccount: suspense }),
+    };
+    let proposals;
+    try {
+        proposals = proposeEntries(needing, options);
+    }
+    catch (error) {
+        if (error instanceof PostingRuleError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+    const summary = summariseProposals(proposals, currencyCode);
+    const out = stringFlag(parsed, "out");
+    let written;
+    if (out !== undefined) {
+        if (environment.writeFile === undefined) {
+            return { stdout: "", stderr: "This environment cannot write files.\n", code: 1 };
+        }
+        environment.writeFile(out, ledgerToJson(applyProposals(ledger, proposals)));
+        written = out;
+    }
+    const strict = booleanFlag(parsed, "strict");
+    const code = strict && summary.unclassified > 0 ? 2 : 0;
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                account,
+                proposals: proposals.map((proposal) => ({
+                    statementLine: proposal.line.id,
+                    date: proposal.line.date,
+                    description: proposal.line.description,
+                    amount: proposal.line.amount.toDecimalString(),
+                    outcome: proposal.outcome,
+                    rule: proposal.rule?.id ?? null,
+                    account: proposal.account,
+                    entry: proposal.entry?.id ?? null,
+                    reason: proposal.reason,
+                })),
+                summary: {
+                    total: summary.total,
+                    booked: summary.booked,
+                    skipped: summary.skipped,
+                    unclassified: summary.unclassified,
+                    alreadyBooked: summary.alreadyBooked,
+                    net: summary.net.toDecimalString(),
+                    byAccount: summary.byAccount.map((total) => ({
+                        account: total.account,
+                        amount: total.amount.toDecimalString(),
+                        count: total.count,
+                    })),
+                },
+                ...(written === undefined ? {} : { wrote: written }),
+            }, null, 2),
+            stderr: "",
+            code,
+        };
+    }
+    const lines = [
+        `${needing.length} statement ${needing.length === 1 ? "line has" : "lines have"} no counterpart in the books`,
+        "",
+        renderProposals(proposals, summary),
+    ];
+    if (suspense !== undefined) {
+        lines.push("", `Everything unmatched went to ${suspense}. A line the matcher merely failed to`, "match is not a line the books are missing, so check the queue before trusting this.");
+    }
+    if (written !== undefined) {
+        lines.push("", `Wrote ${written} with ${summary.booked} ${summary.booked === 1 ? "entry" : "entries"} applied.`);
+    }
+    else if (summary.booked > 0) {
+        lines.push("", "Nothing was written. Pass --out to apply these.");
+    }
+    return {
+        stdout: lines.join("\n"),
+        stderr: code === 2
+            ? `${summary.unclassified} line${summary.unclassified === 1 ? "" : "s"} could not be classified.\n`
+            : "",
+        code,
+    };
+}
+/**
+ * The classification rules for a run: the built-in set, or a file if one was
+ * named. Shared by `post` and by the dashboard's implied entries, so the two
+ * cannot disagree about what a line means.
+ */
+function rulesFor(environment, parsed) {
+    const path = stringFlag(parsed, "rules");
+    if (path === undefined)
+        return standardRules();
+    try {
+        return parseRules(environment.readFile(path));
+    }
+    catch (error) {
+        if (error instanceof PostingRuleError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+}
+/**
+ * Read a decisions file, in the same format the dashboard writes.
+ *
+ * The format lives in `reconcile/decisions.ts` so that "what the review UI
+ * emits" and "what this command accepts" cannot drift apart. Its errors are
+ * re-thrown as usage errors because from the command line that is what they
+ * are: a file the caller handed over that could not be read.
+ */
+function readDecisions(environment, path) {
+    try {
+        return decisionsFor(environment.readFile(path));
+    }
+    catch (error) {
+        if (error instanceof DecisionDocumentError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+}
+/**
+ * Read the rate table a command was pointed at.
+ *
+ * The format is sniffed rather than declared, because a rate file arrives from
+ * two places — a download from a provider, and something this engine wrote —
+ * and asking which is which at the command line adds a flag that would only
+ * ever be wrong.
+ */
+function loadRates(environment, parsed) {
+    const path = requiredFlag(parsed, "rates");
+    const options = {
+        ...(stringFlag(parsed, "base") === undefined
+            ? {}
+            : { base: stringFlag(parsed, "base") }),
+        ...(booleanFlag(parsed, "invert") ? { invert: true } : {}),
+        source: path,
+    };
+    let table;
+    try {
+        table = ratesFromText(environment.readFile(path), options);
+    }
+    catch (error) {
+        if (error instanceof RateDocumentError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+    const stale = stringFlag(parsed, "stale");
+    if (stale === undefined)
+        return table;
+    const days = Number(stale);
+    if (!Number.isInteger(days) || days < 0) {
+        throw new ArgumentError(`--stale wants a whole number of days, got "${stale}"`);
+    }
+    return table.withOptions({ maxStaleDays: days });
+}
+function splitPair(text) {
+    const parts = text.split("/");
+    if (parts.length !== 2)
+        throw new ArgumentError("--pair wants BASE/QUOTE, e.g. EUR/GBP");
+    const base = parts[0].trim().toUpperCase();
+    const quote = parts[1].trim().toUpperCase();
+    if (base === "" || quote === "")
+        throw new ArgumentError("--pair wants BASE/QUOTE, e.g. EUR/GBP");
+    return { base, quote };
+}
+/**
+ * Look at a rate table: what it holds, what it says a pair is worth on a day,
+ * and what an amount converts to at that price.
+ *
+ * Every answer carries its provenance. A rate that came through two legs and a
+ * three-day-old quote is a different kind of answer from a rate published that
+ * morning, and a revaluation posted from the first one should be able to say
+ * so when someone asks where the number came from.
+ */
+function ratesCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["rates"].flags);
+    const table = loadRates(environment, parsed);
+    const json = booleanFlag(parsed, "json");
+    const pairText = stringFlag(parsed, "pair");
+    if (pairText === undefined) {
+        const quotes = table.all();
+        const first = quotes[0];
+        const last = quotes[quotes.length - 1];
+        if (json) {
+            return {
+                stdout: JSON.stringify({
+                    quotes: table.size,
+                    pairs: table.pairs(),
+                    currencies: table.currencies(),
+                    from: first?.date ?? null,
+                    to: last?.date ?? null,
+                    maxStaleDays: table.maxStaleDays,
+                    maxLegs: table.maxLegs,
+                }, null, 2),
+                stderr: "",
+                code: 0,
+            };
+        }
+        const lines = [
+            `${table.size} ${table.size === 1 ? "quote" : "quotes"} over ${table.pairs().length} ` +
+                `${table.pairs().length === 1 ? "pair" : "pairs"}` +
+                (first === undefined ? "" : `, ${first.date} to ${last.date}`),
+            "",
+            ...table.pairs().map((pair) => {
+                const [base, quote] = pair.split("/");
+                const list = table.quotesFor(base, quote);
+                const oldest = list[0];
+                const newest = list[list.length - 1];
+                const noun = list.length === 1 ? "quote " : "quotes";
+                return (`  ${pair.padEnd(9)}${String(list.length).padStart(4)} ${noun}  ` +
+                    `${oldest.date} to ${newest.date}  latest ${newest.rate.toDecimalString(6)}`);
+            }),
+            "",
+            `Currencies: ${table.currencies().join(", ")}`,
+            `A quote may be up to ${table.maxStaleDays} days behind the date asked for, ` +
+                `and a price may cross up to ${table.maxLegs} pairs.`,
+        ];
+        return { stdout: lines.join("\n"), stderr: "", code: 0 };
+    }
+    const { base, quote } = splitPair(pairText);
+    const averageText = stringFlag(parsed, "average");
+    if (averageText !== undefined) {
+        const parts = averageText.split(":");
+        if (parts.length !== 2)
+            throw new ArgumentError("--average wants from:to");
+        const methodText = stringFlag(parsed, "method") ?? "daily";
+        if (methodText !== "daily" && methodText !== "quoted") {
+            throw new ArgumentError(`--method wants daily or quoted, got "${methodText}"`);
+        }
+        const found = averageRate(table, base, quote, parts[0], parts[1], methodText);
+        if (json) {
+            return {
+                stdout: JSON.stringify({
+                    pair: found.rate.pair,
+                    rate: found.rate.toDecimalString(10),
+                    method: found.method,
+                    from: found.range.from,
+                    to: found.range.to,
+                    observations: found.observations,
+                    lowest: found.lowest.toDecimalString(10),
+                    highest: found.highest.toDecimalString(10),
+                }, null, 2),
+                stderr: "",
+                code: 0,
+            };
+        }
+        return {
+            stdout: [
+                `${found.rate.pair} average ${found.range.from} to ${found.range.to}`,
+                `  ${found.rate.toDecimalString(6)}  (${found.method}, ${found.observations} ` +
+                    `${found.observations === 1 ? "observation" : "observations"})`,
+                `  low ${found.lowest.toDecimalString(6)}  high ${found.highest.toDecimalString(6)}`,
+            ].join("\n"),
+            stderr: "",
+            code: 0,
+        };
+    }
+    const onText = stringFlag(parsed, "on");
+    const on = onText === undefined ? environment.today() : date(onText);
+    const found = table.lookup(base, quote, on);
+    const amountText = stringFlag(parsed, "amount");
+    const converted = amountText === undefined
+        ? undefined
+        : found.rate.convert(Money.parse(amountText, lookupCurrency(base)));
+    if (json) {
+        return {
+            stdout: JSON.stringify({
+                pair: found.rate.pair,
+                on,
+                rate: found.rate.toDecimalString(10),
+                direct: found.direct,
+                via: found.via,
+                quoteDates: found.quoteDates,
+                staleDays: found.staleDays,
+                sources: found.sources,
+                ...(converted === undefined
+                    ? {}
+                    : {
+                        amount: Money.parse(amountText, lookupCurrency(base)).toDecimalString(),
+                        converted: converted.toDecimalString(),
+                        currency: converted.currency.code,
+                    }),
+            }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    const provenance = found.direct
+        ? `direct quote from ${found.quoteDates[0]}`
+        : `via ${found.via.join(" -> ")}, quotes ${found.quoteDates.join(", ")}`;
+    const lines = [
+        `${found.rate.toString()} on ${on}`,
+        `  ${provenance}`,
+        found.staleDays === 0
+            ? "  published that day"
+            : `  ${found.staleDays} ${found.staleDays === 1 ? "day" : "days"} behind the date asked for`,
+        `  source: ${found.sources.join(", ")}`,
+    ];
+    if (converted !== undefined) {
+        const original = Money.parse(amountText, lookupCurrency(base));
+        lines.push("", `  ${original.toString()}  ->  ${converted.toString()}`);
+    }
+    return { stdout: lines.join("\n"), stderr: "", code: 0 };
+}
+/**
+ * Retranslate what the books hold in another currency.
+ *
+ * The command computes and prints by default and only writes when told to,
+ * because a revaluation is a judgement about a date rather than a fact about
+ * one: the rate you use at the close is a choice, and the person making it
+ * should see the numbers before the ledger grows an entry.
+ */
+function revalueCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["revalue"].flags);
+    const ledger = loadLedger(environment, requiredFlag(parsed, "ledger"));
+    const asAtText = stringFlag(parsed, "as-at");
+    const asAt = asAtText === undefined ? environment.today() : date(asAtText);
+    const excludeText = stringFlag(parsed, "exclude");
+    const exclude = excludeText === undefined
+        ? undefined
+        : excludeText
+            .split(",")
+            .map((part) => part.trim())
+            .filter((part) => part !== "");
+    const functional = ledger.chart?.defaultCurrency.code ?? "GBP";
+    if (booleanFlag(parsed, "show")) {
+        const list = exposures(ledger, {
+            asAt,
+            ...(exclude === undefined ? {} : { exclude }),
+        });
+        if (booleanFlag(parsed, "json")) {
+            return {
+                stdout: JSON.stringify({
+                    asAt,
+                    functional,
+                    exposures: list.map((item) => ({
+                        account: item.account,
+                        name: item.name,
+                        currency: item.currency.code,
+                        foreignBalance: item.foreignBalance.toDecimalString(),
+                        carryingAmount: item.carryingAmount.toDecimalString(),
+                        impliedRate: item.impliedRate?.toDecimalString(10) ?? null,
+                        lastMovement: item.lastMovement,
+                    })),
+                }, null, 2),
+                stderr: "",
+                code: 0,
+            };
+        }
+        return { stdout: renderExposures(list, functional), stderr: "", code: 0 };
+    }
+    const rates = loadRates(environment, parsed);
+    const options = {
+        asAt,
+        rates,
+        ...(exclude === undefined ? {} : { exclude }),
+        ...(stringFlag(parsed, "gain") === undefined
+            ? {}
+            : { gainAccount: stringFlag(parsed, "gain") }),
+        ...(stringFlag(parsed, "loss") === undefined
+            ? {}
+            : { lossAccount: stringFlag(parsed, "loss") }),
+    };
+    let result;
+    try {
+        result = revalue(ledger, options);
+    }
+    catch (error) {
+        if (error instanceof RevaluationError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+    const out = stringFlag(parsed, "out");
+    let written;
+    if (out !== undefined) {
+        if (environment.writeFile === undefined) {
+            return { stdout: "", stderr: "This environment cannot write files.\n", code: 1 };
+        }
+        environment.writeFile(out, ledgerToJson(result.entry === null ? ledger : ledger.post(result.entry)));
+        written = out;
+    }
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                asAt: result.asAt,
+                functional: result.functional.code,
+                lines: result.lines.map((line) => ({
+                    account: line.account,
+                    name: line.name,
+                    currency: line.currency.code,
+                    foreignBalance: line.foreignBalance.toDecimalString(),
+                    carryingAmount: line.carryingAmount.toDecimalString(),
+                    closingAmount: line.closingAmount.toDecimalString(),
+                    adjustment: line.adjustment.toDecimalString(),
+                    closingRate: line.closingRate.toDecimalString(10),
+                    via: line.lookup.via,
+                    staleDays: line.lookup.staleDays,
+                })),
+                net: result.net.toDecimalString(),
+                gain: result.gain.toDecimalString(),
+                loss: result.loss.toDecimalString(),
+                entry: result.entry?.id ?? null,
+                ...(written === undefined ? {} : { written }),
+            }, null, 2),
+            stderr: "",
+            code: 0,
+        };
+    }
+    const lines = [renderRevaluation(result)];
+    if (written !== undefined) {
+        lines.push(result.entry === null
+            ? `Wrote ${written} unchanged.`
+            : `Wrote ${written} with ${result.entry.id} applied.`);
+    }
+    else if (result.entry !== null) {
+        lines.push("Nothing was written. Pass --out to apply it.");
+    }
+    return { stdout: lines.join("\n"), stderr: "", code: 0 };
+}
+/**
+ * Consolidate a group.
+ *
+ * The group document says who holds whom, where each company's books are, what
+ * faces what across the group, and what was paid for each subsidiary. This
+ * reads all of it, does the work, and prints as much of the working as asked
+ * for — because the number a reader will want to argue with is never the
+ * consolidated total, it is one of the figures that went into it.
+ *
+ * Exit code 2 when the consolidated ledger does not balance or its accounting
+ * equation leaves a residual: a consolidation that came out wrong ran to
+ * completion, and a job that treated that as a pass would be worse than none.
+ */
+/** A movement schedule as JSON: the lines as given, and what does not tie. */
+function scheduleToJson(schedule) {
+    return {
+        what: schedule.what,
+        opening: schedule.opening.toDecimalString(),
+        lines: schedule.lines.map((line) => ({
+            label: line.label,
+            amount: line.amount.toDecimalString(),
+        })),
+        rolledForward: schedule.rolledForward.toDecimalString(),
+        unexplained: schedule.unexplained.toDecimalString(),
+        closing: schedule.closing.toDecimalString(),
+        reconciles: schedule.reconciles,
+    };
+}
+function consolidateCommand(environment, argv) {
+    const parsed = parseArgs(argv, COMMANDS["consolidate"].flags);
+    const groupPath = requiredFlag(parsed, "group");
+    let group;
+    try {
+        group = groupFromJson(environment.readFile(groupPath));
+    }
+    catch (error) {
+        if (error instanceof GroupDocumentError || error instanceof GroupError) {
+            throw new ArgumentError(error.message);
+        }
+        throw error;
+    }
+    const missing = group.structure
+        .consolidated()
+        .filter((entity) => !group.ledgers.has(entity.code));
+    if (missing.length > 0) {
+        throw new ArgumentError(`${missing.map((e) => e.code).join(", ")} ${missing.length === 1 ? "has" : "have"} no ` +
+            `"ledger" in ${groupPath}, so there are no books to consolidate.`);
+    }
+    const ledgers = new Map();
+    for (const entity of group.structure.consolidated()) {
+        ledgers.set(entity.code, loadLedger(environment, group.ledgers.get(entity.code)));
+    }
+    const rates = stringFlag(parsed, "rates") === undefined
+        ? RateTable.empty()
+        : loadRates(environment, parsed);
+    if (!group.structure.isSingleCurrency && stringFlag(parsed, "rates") === undefined) {
+        throw new ArgumentError(`The group keeps books in ${group.structure.currencies().join(", ")}, so it needs --rates.`);
+    }
+    const asAtText = stringFlag(parsed, "as-at") ?? group.asAt;
+    if (asAtText === null || asAtText === undefined) {
+        throw new ArgumentError("A consolidation needs a reporting date: pass --as-at or set asAt.");
+    }
+    const asAt = date(asAtText);
+    const fromText = stringFlag(parsed, "from");
+    const toText = stringFlag(parsed, "to");
+    const period = fromText !== undefined || toText !== undefined
+        ? dateRange(fromText ?? String(asAt), toText ?? String(asAt))
+        : (group.period ?? undefined);
+    const methodText = stringFlag(parsed, "average-method") ?? group.averageMethod ?? undefined;
+    if (methodText !== undefined && methodText !== "daily" && methodText !== "quoted") {
+        throw new ArgumentError(`--average-method wants daily or quoted, got "${methodText}"`);
+    }
+    const consolidationOptions = (on, over) => ({
+        rates,
+        asAt: String(on),
+        ...(over === undefined ? {} : { period: over }),
+        ...(methodText === undefined ? {} : { averageMethod: methodText }),
+        ...(group.equityBasis === null ? {} : { equityBasis: group.equityBasis }),
+        intercompany: group.intercompany,
+        intragroupStock: group.intragroupStock,
+        acquisitions: group.acquisitions,
+        disposals: group.disposals,
+    });
+    // The comparative period defaults to one of the same length ending on the
+    // comparative date, which for the ordinary annual case is exactly the year
+    // before and needs nobody to type it out. Where the two periods are not the
+    // same length, --comparative-from says so.
+    const comparativeText = stringFlag(parsed, "comparative");
+    let priorPeriod;
+    let priorAsAt;
+    if (comparativeText !== undefined) {
+        priorAsAt = date(comparativeText);
+        if (compareDates(priorAsAt, asAt) !== -1) {
+            throw new ArgumentError(`--comparative ${comparativeText} is not before the reporting date ${asAt}.`);
+        }
+        const fromComparative = stringFlag(parsed, "comparative-from");
+        if (fromComparative !== undefined) {
+            priorPeriod = dateRange(fromComparative, String(priorAsAt));
+        }
+        else if (period !== undefined) {
+            priorPeriod = dateRange(String(addDays(priorAsAt, -daysBetween(period.from, period.to))), String(priorAsAt));
+        }
+    }
+    let result;
+    let compared;
+    try {
+        result = consolidate(group.structure, ledgers, consolidationOptions(asAt, period));
+        if (priorAsAt !== undefined) {
+            const priorResult = consolidate(group.structure, ledgers, consolidationOptions(priorAsAt, priorPeriod));
+            compared = compareConsolidations(priorResult, result, { rates });
+        }
+    }
+    catch (error) {
+        if (error instanceof GroupError)
+            throw new ArgumentError(error.message);
+        throw error;
+    }
+    const code = result.balanced && result.residual.isZero ? 0 : 2;
+    let written;
+    const outPath = stringFlag(parsed, "out");
+    if (outPath !== undefined) {
+        if (environment.writeFile === undefined) {
+            throw new ArgumentError("This environment cannot write files, so --out has nowhere to go.");
+        }
+        environment.writeFile(outPath, ledgerToJson(result.ledger));
+        written = outPath;
+    }
+    if (booleanFlag(parsed, "json")) {
+        return {
+            stdout: JSON.stringify({
+                group: result.group.name,
+                presentation: result.presentation.code,
+                asAt: result.asAt,
+                entities: result.group.consolidated().map((entity) => ({
+                    code: entity.code,
+                    name: entity.name,
+                    currency: entity.currency.code,
+                    effectiveInterest: entity.effective.toJSON(),
+                    nonControllingInterest: entity.nonControlling.toJSON(),
+                })),
+                notConsolidated: result.aggregation.excluded,
+                controlWindows: result.aggregation.entities.map((contribution) => ({
+                    entity: contribution.entity,
+                    from: contribution.control.window?.from ?? null,
+                    to: contribution.control.window?.to ?? null,
+                    whole: contribution.control.whole,
+                    acquiredDuring: contribution.control.acquiredDuring,
+                    disposedDuring: contribution.control.disposedDuring,
+                    readAt: contribution.readAt,
+                    applied: contribution.windowApplied,
+                    preAcquisitionResult: contribution.preAcquisitionResult.toDecimalString(),
+                    reason: contribution.control.reason,
+                })),
+                workings: result.workings.map((working) => ({
+                    entity: working.entity,
+                    acquired: working.acquisition.acquired,
+                    measurement: working.acquisition.measurement,
+                    consideration: working.acquisition.consideration.toDecimalString(),
+                    netAssetsAcquired: working.acquisition.netAssetsAcquired.toDecimalString(),
+                    goodwill: working.acquisition.goodwill.toDecimalString(),
+                    bargainGain: working.acquisition.bargainGain.toDecimalString(),
+                    netAssetsNow: working.netAssetsNow.toDecimalString(),
+                    profitForPeriod: working.profitForPeriod.toDecimalString(),
+                    nciProfitShare: working.nciProfitShare.toDecimalString(),
+                    nciClosing: working.nciClosing.toDecimalString(),
+                    postAcquisitionReserves: working.postAcquisitionReserves.toDecimalString(),
+                })),
+                disposals: result.disposals.map((working) => ({
+                    entity: working.entity,
+                    disposed: working.disposal.disposed,
+                    proceeds: working.disposal.proceeds.toDecimalString(),
+                    netAssetsRemoved: working.netAssetsRemoved.toDecimalString(),
+                    nciRemoved: working.nciRemoved.toDecimalString(),
+                    goodwillRemoved: working.goodwillRemoved.toDecimalString(),
+                    carryingAmount: working.disposal.carryingAmount.toDecimalString(),
+                    result: working.result.toDecimalString(),
+                    resultToDisposal: working.resultToDisposal.toDecimalString(),
+                    holderResult: working.disposal.holderResult.toDecimalString(),
+                })),
+                intercompany: {
+                    pairs: result.eliminations.pairs.length,
+                    eliminated: result.eliminations.totalEliminated.toDecimalString(),
+                    difference: result.eliminations.totalDifference.toDecimalString(),
+                    unpaired: result.eliminations.unmatched.map((item) => ({
+                        entity: item.side.entity,
+                        account: item.side.account,
+                        reason: item.reason,
+                    })),
+                },
+                unrealisedProfit: {
+                    consignments: result.unrealisedProfit.items.length,
+                    provided: result.unrealisedProfit.totalProvision.toDecimalString(),
+                    groupShare: result.unrealisedProfit.totalGroupShare.toDecimalString(),
+                    nciShare: result.unrealisedProfit.totalNciShare.toDecimalString(),
+                    notProvided: result.unrealisedProfit.unprovided.map((item) => ({
+                        seller: item.declaration.seller,
+                        holder: item.declaration.holder,
+                        account: item.declaration.account,
+                        reason: item.reason,
+                    })),
+                },
+                goodwill: result.goodwill.toDecimalString(),
+                nonControllingInterest: result.nonControllingInterest.toDecimalString(),
+                translationReserve: result.translationReserve.toDecimalString(),
+                investmentResidual: result.investmentResidual.toDecimalString(),
+                disposalResult: result.disposalResult.toDecimalString(),
+                disposalResidual: result.disposalResidual.toDecimalString(),
+                residual: result.residual.toDecimalString(),
+                balanced: result.balanced,
+                ...(compared === undefined
+                    ? {}
+                    : {
+                        comparative: {
+                            asAt: compared.comparativeAsAt,
+                            entered: compared.entered,
+                            left: compared.left,
+                            sound: compared.sound,
+                            rows: compared.rows.map((row) => ({
+                                account: row.account,
+                                name: row.name,
+                                current: row.current.toDecimalString(),
+                                prior: row.prior.toDecimalString(),
+                                movement: row.movement.toDecimalString(),
+                            })),
+                            netAssets: compared.netAssets.map((movement) => ({
+                                entity: movement.entity,
+                                opening: movement.opening.toDecimalString(),
+                                translationEffect: movement.translationEffect.toDecimalString(),
+                                result: movement.result.toDecimalString(),
+                                other: movement.other.toDecimalString(),
+                                closing: movement.closing.toDecimalString(),
+                                comparable: movement.comparable,
+                            })),
+                            nonControllingInterest: scheduleToJson(compared.nci),
+                            translationReserve: scheduleToJson(compared.translationReserve),
+                            goodwill: scheduleToJson(compared.goodwill),
+                        },
+                    }),
+                ...(written === undefined ? {} : { written }),
+            }, null, 2),
+            stderr: "",
+            code,
+        };
+    }
+    const show = stringFlag(parsed, "show") ?? "workings";
+    const known = ["workings", "combined", "eliminations", "windows", "movement", "statements", "all"];
+    if (!known.includes(show)) {
+        throw new ArgumentError(`--show wants one of ${known.join(", ")}, got "${show}"`);
+    }
+    const wants = (name) => show === "all" || show === name;
+    const sections = [];
+    sections.push(result.group.render());
+    sections.push("");
+    // Printed whenever any entity was not the group's for the whole period,
+    // whatever --show says: a consolidation covering nine months of one company
+    // and twelve of another should never be read without knowing that.
+    const partial = result.aggregation.entities.some((c) => c.control.acquiredDuring || c.control.disposedDuring);
+    if (wants("windows") || partial) {
+        sections.push(renderControlWindows(result.aggregation.entities.map((c) => c.control), (entity) => result.group.get(entity).name));
+        sections.push("");
+    }
+    if (wants("combined")) {
+        sections.push(renderAggregation(result.aggregation));
+        sections.push("");
+    }
+    if (wants("eliminations") && result.eliminations.pairs.length + result.eliminations.unmatched.length > 0) {
+        sections.push(renderEliminations(result.eliminations));
+        sections.push("");
+    }
+    if (wants("workings")) {
+        for (const working of result.workings) {
+            sections.push(renderAcquisition(working.acquisition));
+            sections.push("");
+        }
+        for (const working of result.disposals) {
+            sections.push(renderDisposal(working.disposal));
+            sections.push("");
+        }
+    }
+    sections.push(renderConsolidation(result));
+    if (compared !== undefined) {
+        sections.push("");
+        sections.push(renderComparative(compared));
+    }
+    if (compared !== undefined && (wants("movement") || show === "workings")) {
+        sections.push("");
+        sections.push(renderNetAssetsMovements(compared.netAssets, (entity) => compared.group.get(entity).name));
+        sections.push("");
+        sections.push(renderMovementSchedule(compared.nci));
+        sections.push("");
+        sections.push(renderMovementSchedule(compared.translationReserve));
+        sections.push("");
+        sections.push(renderMovementSchedule(compared.goodwill));
+    }
+    if (wants("statements")) {
+        sections.push("");
+        sections.push(renderTrialBalance(result.trialBalance));
+        sections.push("");
+        sections.push(renderIncomeStatement(incomeStatement(result.ledger, result.period, { currency: result.presentation })));
+        sections.push("");
+        sections.push(renderBalanceSheet(balanceSheet(result.ledger, result.asAt, { currency: result.presentation })));
+    }
+    if (written !== undefined) {
+        sections.push("");
+        sections.push(`Wrote the consolidated ledger to ${written}.`);
+    }
+    return {
+        stdout: sections.join("\n"),
+        stderr: code === 0 ? "" : "The consolidated ledger does not agree with itself.\n",
+        code,
+    };
+}
+const HANDLERS = {
+    report: reportCommand,
+    ageing: ageingCommand,
+    reconcile: reconcileCommand,
+    import: importCommand,
+    accounts: accountsCommand,
+    generate: generateCommand,
+    bench: benchCommand,
+    learn: learnCommand,
+    rates: ratesCommand,
+    revalue: revalueCommand,
+    consolidate: consolidateCommand,
+    dashboard: dashboardCommand,
+    post: postCommand,
+};
+/** Run one invocation. Never throws; every failure becomes an exit code. */
+export function run(argv, environment) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+        return { stdout: usage(), stderr: "", code: command === undefined ? 1 : 0 };
+    }
+    if (command === "--version" || command === "-v") {
+        return { stdout: "tallyd 0.1.0", stderr: "", code: 0 };
+    }
+    const handler = HANDLERS[command];
+    if (handler === undefined) {
+        return { stdout: "", stderr: `Unknown command: ${command}\n\n${usage()}\n`, code: 1 };
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        return { stdout: commandHelp(command), stderr: "", code: 0 };
+    }
+    try {
+        return handler(environment, rest);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { stdout: "", stderr: `${message}\n`, code: 1 };
+    }
+}