@kirjapro/mcp-server 0.8.0 → 0.8.2

package/dist/tools/reports.js

@@ -0,0 +1,869 @@
+import { z } from 'zod';
+import { getSupabase, getCompanyId } from '../auth.js';
+import { synthesizeIncomeStatementLines } from '../lib/incomeStatementSynthesis.js';
+import { toErrorContent, toResult, sanitizeDbError, roundCents, formatCurrency, helsinkiDateString, resolveOpenFiscalYear, tagUntrusted, ISO_DATE_SCHEMA, READ_ONLY_ANNOTATIONS, } from '../utils.js';
+/**
+ * Default income statement template id, resolved lazily on first call.
+ * Templates are seed-static (no admin UI), so a process-wide cache is safe;
+ * worst case after a redeploy we hit the DB once. Post-DT-039 the database
+ * holds a single `kululajikohtainen` row (KPA 1:1 § cost-of-sales) — the
+ * lookup matches by name only. Mirrors the web hook
+ * `useIncomeStatementTemplates.ts` which dropped its `is_default` filter for
+ * the same wave-sibling-doctrine-parity reason: if a future opt-in alt
+ * template flips the default flag, both surfaces continue to resolve.
+ */
+let cachedDefaultTemplateId = null;
+async function resolveDefaultIncomeStatementTemplate(supabase) {
+    if (cachedDefaultTemplateId)
+        return cachedDefaultTemplateId;
+    const { data, error } = await supabase
+        .from('income_statement_templates')
+        .select('id')
+        .eq('name', 'kululajikohtainen')
+        .maybeSingle();
+    if (error || !data) {
+        throw new Error('Default income statement template not found');
+    }
+    cachedDefaultTemplateId = data.id;
+    return data.id;
+}
+const INVOICE_STAT_BUCKET = z.object({
+    count: z.number(),
+    total: z.number(),
+});
+const DASHBOARD_OUTPUT_SHAPE = {
+    financial_summary: z
+        .object({
+        revenue: z.number(),
+        revenue_formatted: z.string(),
+        expenses: z.number(),
+        expenses_formatted: z.string(),
+        profit: z.number(),
+        profit_formatted: z.string(),
+        transaction_count: z.number(),
+        warning: z.string().optional(),
+    })
+        .passthrough(),
+    invoice_stats: z.object({
+        draft: INVOICE_STAT_BUCKET,
+        sent: INVOICE_STAT_BUCKET,
+        partial: INVOICE_STAT_BUCKET,
+        paid: INVOICE_STAT_BUCKET,
+        overdue: INVOICE_STAT_BUCKET,
+        cancelled: INVOICE_STAT_BUCKET,
+        no_due_date: INVOICE_STAT_BUCKET,
+    }),
+    bank_summary: z
+        .object({
+        accounts: z.array(z.object({
+            name: z.string(),
+            iban: z.string().nullable(),
+            balance: z.number(),
+        })),
+        total_balance: z.number(),
+        total_balance_formatted: z.string(),
+    })
+        .passthrough(),
+};
+/**
+ * Income statement shape (post-RPC migration, 2026-04-27).
+ *
+ * Sourced from `get_income_statement` RPC (range-based aggregation with the
+ * 5-digit-subaccount fix) plus client-side `synthesizeIncomeStatementLines`
+ * for the calculated subtotals (LIIKEVOITTO, RAHOITUS_TOTAL, ...).
+ *
+ * BREAKING vs the pre-RPC shape: dropped `revenue.accounts[]` and
+ * `expenses.accounts[]` per-account arrays. No live consumer in
+ * `src/components/chat/` or the AI system prompt referenced those fields;
+ * they were a leftover from the inline-join implementation. The remaining
+ * `revenue.total` / `expenses.total` and the new `subtotals` map cover
+ * every documented use case.
+ *
+ * `subtotals` uses `.partial().catchall(z.number())` so the structuredContent
+ * stays typed as `{[k: string]: unknown}` (skill `mcp-structured-content-
+ * index-signature`) while tolerating custom-template line_codes that aren't
+ * in the canonical kululajikohtainen list.
+ */
+const INCOME_STATEMENT_OUTPUT_SHAPE = {
+    period: z.object({ from: z.string(), to: z.string() }),
+    revenue: z.object({
+        total: z.number(),
+        total_formatted: z.string(),
+    }),
+    expenses: z.object({
+        total: z.number(),
+        total_formatted: z.string(),
+    }),
+    net_profit: z.number(),
+    net_profit_formatted: z.string().optional(),
+    subtotals: z
+        .object({
+        LIIKEVAIHTO: z.number(),
+        MATERIAALIT_TOTAL: z.number(),
+        HENKILOSTO_TOTAL: z.number(),
+        POISTOT_TOTAL: z.number(),
+        MUUT_KULUT: z.number(),
+        LIIKEVOITTO: z.number(),
+        RAHOITUS_TOTAL: z.number(),
+        VOITTO_ENNEN_SIIRTOJA: z.number(),
+        SIIRROT_TOTAL: z.number(),
+        TULOVEROT: z.number(),
+        TILIKAUDEN_TULOS: z.number(),
+    })
+        .partial()
+        .catchall(z.number()),
+    warning: z.string().optional(),
+};
+const ALV_SUMMARY_OUTPUT_SHAPE = {
+    period: z.object({ from: z.string(), to: z.string() }),
+    output_vat: z.unknown().optional(),
+    input_vat: z.unknown().optional(),
+    net_vat_payable: z.number().optional(),
+    net_vat_payable_formatted: z.string().optional(),
+    omavero_fields: z.unknown().optional(),
+    warning: z.string().optional(),
+    message: z.string().optional(),
+};
+const BALANCE_SHEET_ROW_SHAPE = z
+    .object({
+    account_number: z.string(),
+    name: z.string(),
+    account_type: z.string(),
+    balance: z.number(),
+})
+    .passthrough();
+const BALANCE_SHEET_OUTPUT_SHAPE = {
+    report_date: z.string(),
+    assets: z.object({
+        accounts: z.array(BALANCE_SHEET_ROW_SHAPE),
+        total: z.number(),
+        total_formatted: z.string(),
+    }),
+    liabilities: z.object({
+        accounts: z.array(BALANCE_SHEET_ROW_SHAPE),
+        total: z.number(),
+        total_formatted: z.string(),
+    }),
+    equity: z.object({
+        accounts: z.array(BALANCE_SHEET_ROW_SHAPE),
+        total: z.number(),
+        total_formatted: z.string(),
+        synthetic_tilikauden_tulos: z.number().optional(),
+        synthetic_note: z.string().optional(),
+    }),
+    total_liabilities_and_equity: z.number(),
+    balanced: z.boolean(),
+    warning: z.string().optional(),
+};
+const AGING_BUCKET_SHAPE = z.object({
+    label: z.string(),
+    count: z.number(),
+    total: z.number(),
+    total_formatted: z.string(),
+    invoices: z.array(z
+        .object({
+        invoice_number: z.string(),
+        customer: z.string().nullable().optional(),
+        total: z.number().nullable(),
+        due_date: z.string().nullable(),
+        days_overdue: z.number(),
+    })
+        .passthrough()),
+});
+const AR_AGING_OUTPUT_SHAPE = {
+    buckets: z.array(AGING_BUCKET_SHAPE),
+    no_due_date: z.object({
+        count: z.number(),
+        total: z.number(),
+        invoices: z.array(z.record(z.string(), z.unknown())),
+    }).passthrough(),
+    total_receivables: z.number(),
+    total_receivables_formatted: z.string(),
+    days_sales_outstanding: z.number(),
+};
+const GENERAL_LEDGER_OUTPUT_SHAPE = {
+    account: z.object({
+        account_number: z.string(),
+        name: z.string(),
+        account_type: z.string(),
+        balance_type: z.enum(['debit-normal', 'credit-normal']),
+    }),
+    entries: z.array(z
+        .object({
+        date: z.string(),
+        description: z.string().nullable(),
+        document_number: z.string().nullable(),
+        transaction_id: z.string().uuid(),
+        debit: z.number(),
+        credit: z.number(),
+        running_balance: z.number(),
+    })
+        .passthrough()),
+    entry_count: z.number(),
+    opening_balance: z.number(),
+    closing_balance: z.number(),
+    closing_balance_formatted: z.string(),
+    capped: z.boolean(),
+    capped_note: z.string().nullable(),
+};
+export function registerReportTools(server) {
+    // ---- Dashboard Stats ----
+    server.registerTool('kirjapro_get_dashboard', {
+        description: 'Get dashboard overview: revenue, expenses, profit, transaction count, invoice stats, bank balances, and AR aging for a fiscal year. Returns a comprehensive financial snapshot. If fiscalYearId is omitted, the single open fiscal year is used; specify it explicitly when multiple are open.',
+        inputSchema: {
+            fiscalYearId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe('Fiscal year UUID (auto-resolved to the open fiscal year if omitted)'),
+        },
+        outputSchema: DASHBOARD_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        let fiscalYearId;
+        if (params.fiscalYearId) {
+            fiscalYearId = params.fiscalYearId;
+        }
+        else {
+            const resolved = await resolveOpenFiscalYear(supabase, companyId);
+            if ('isError' in resolved)
+                return resolved;
+            fiscalYearId = resolved.id;
+        }
+        // Fetch fiscal year dates for scoping
+        const { data: fiscalYear, error: fyError } = await supabase
+            .from('fiscal_years')
+            .select('start_date, end_date')
+            .eq('id', fiscalYearId)
+            .eq('company_id', companyId)
+            .single();
+        if (fyError || !fiscalYear) {
+            return toErrorContent(`Fiscal year ${fiscalYearId} not found. Use kirjapro_list_fiscal_years to find available fiscal years.`);
+        }
+        // Parallel queries for performance
+        const JOURNAL_ENTRY_CAP = 50_000;
+        const [entriesResult, txCountResult, invoiceResult, bankResult] = await Promise.all([
+            // Revenue & expense totals from journal entries (capped to prevent OOM on large datasets)
+            supabase
+                .from('journal_entries')
+                .select(`
+            debit_amount, credit_amount,
+            account:accounts!inner(account_type),
+            transaction:transactions!inner(fiscal_year_id, company_id)
+          `, { count: 'exact' })
+                .eq('transaction.fiscal_year_id', fiscalYearId)
+                .eq('transaction.company_id', companyId)
+                .limit(JOURNAL_ENTRY_CAP),
+            // Transaction count
+            supabase
+                .from('transactions')
+                .select('*', { count: 'exact', head: true })
+                .eq('company_id', companyId)
+                .eq('fiscal_year_id', fiscalYearId),
+            // Invoice stats scoped to fiscal year date range
+            supabase
+                .from('invoices')
+                .select('id, status, total, due_date')
+                .eq('company_id', companyId)
+                .gte('invoice_date', fiscalYear.start_date)
+                .lte('invoice_date', fiscalYear.end_date),
+            // Bank balances
+            supabase
+                .from('bank_accounts')
+                .select('account_name, iban, current_balance')
+                .eq('company_id', companyId)
+                .eq('is_active', true),
+        ]);
+        // Calculate revenue and expenses
+        let revenue = 0;
+        let expenses = 0;
+        for (const entry of entriesResult.data || []) {
+            const accountType = entry.account?.account_type;
+            if (accountType === 'revenue') {
+                revenue += (entry.credit_amount || 0) - (entry.debit_amount || 0);
+            }
+            else if (accountType === 'expense') {
+                expenses += (entry.debit_amount || 0) - (entry.credit_amount || 0);
+            }
+        }
+        // Invoice stats — use Helsinki-local "today" so period attribution near
+        // midnight-UTC doesn't silently shift invoices into the wrong day.
+        const now = helsinkiDateString();
+        const invoices = invoiceResult.data || [];
+        const invoiceStats = {
+            draft: { count: 0, total: 0 },
+            sent: { count: 0, total: 0 },
+            partial: { count: 0, total: 0 },
+            paid: { count: 0, total: 0 },
+            overdue: { count: 0, total: 0 },
+            cancelled: { count: 0, total: 0 },
+            no_due_date: { count: 0, total: 0 },
+        };
+        for (const inv of invoices) {
+            // Null/empty due_date can't be compared against "today" safely.
+            // Surface these in their own bucket instead of silently leaving them
+            // as `sent` (which hides stuck invoices from the agent).
+            const hasDueDate = typeof inv.due_date === 'string' && inv.due_date.length > 0;
+            let status;
+            if (inv.status === 'sent' && !hasDueDate) {
+                status = 'no_due_date';
+            }
+            else if (inv.status === 'sent' && hasDueDate && inv.due_date < now) {
+                status = 'overdue';
+            }
+            else if (inv.status in invoiceStats) {
+                status = inv.status;
+            }
+            else {
+                continue;
+            }
+            invoiceStats[status].count++;
+            invoiceStats[status].total += inv.total || 0;
+        }
+        // Bank balances
+        const bankAccounts = (bankResult.data || []).map((b) => ({
+            name: b.account_name || 'Unnamed',
+            iban: b.iban,
+            balance: b.current_balance || 0,
+        }));
+        const totalBankBalance = bankAccounts.reduce((s, b) => s + b.balance, 0);
+        const entriesCapped = (entriesResult.count || 0) >= JOURNAL_ENTRY_CAP;
+        return toResult({
+            financial_summary: {
+                revenue: roundCents(revenue),
+                revenue_formatted: formatCurrency(revenue),
+                expenses: roundCents(expenses),
+                expenses_formatted: formatCurrency(expenses),
+                profit: roundCents(revenue - expenses),
+                profit_formatted: formatCurrency(revenue - expenses),
+                transaction_count: txCountResult.count || 0,
+                ...(entriesCapped && { warning: `Results capped at ${JOURNAL_ENTRY_CAP} journal entries. Totals may be approximate.` }),
+            },
+            invoice_stats: invoiceStats,
+            bank_summary: {
+                accounts: bankAccounts,
+                total_balance: roundCents(totalBankBalance),
+                total_balance_formatted: formatCurrency(totalBankBalance),
+            },
+        });
+    });
+    // ---- Income Statement ----
+    server.registerTool('kirjapro_get_income_statement', {
+        description: 'Generate income statement (tuloslaskelma) for a date range. Returns revenue / expense totals plus a `subtotals` map of every line_code in the default cost-of-sales template (kululajikohtainen) — including calculated subtotals such as LIIKEVOITTO, RAHOITUS_TOTAL, TILIKAUDEN_TULOS. fiscalYearId is accepted for backward compat but ignored: the underlying RPC scopes by company + date range only.',
+        inputSchema: {
+            fiscalYearId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe('Fiscal year UUID (accepted for backward compat; ignored by the RPC which scopes by date range)'),
+            dateFrom: ISO_DATE_SCHEMA
+                .describe('Period start date (YYYY-MM-DD)'),
+            dateTo: ISO_DATE_SCHEMA
+                .describe('Period end date (YYYY-MM-DD)'),
+        },
+        outputSchema: INCOME_STATEMENT_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        // fiscalYearId is intentionally not used here. The RPC aggregates by
+        // (company_id, transaction_date BETWEEN p_date_from AND p_date_to),
+        // which is the same scope the web report uses. Keeping the param in
+        // the input schema preserves backward compat with existing AI prompts.
+        let templateId;
+        try {
+            templateId = await resolveDefaultIncomeStatementTemplate(supabase);
+        }
+        catch (err) {
+            return toErrorContent(err instanceof Error ? err.message : 'Default income statement template not found');
+        }
+        // Fetch leaf-line amounts via the RPC — uses account_number_range_value()
+        // (rpad-to-5) to include 5-digit subaccounts within 4-digit parent ranges.
+        const { data: rpcRows, error } = await supabase.rpc('get_income_statement', {
+            p_company_id: companyId,
+            p_template_id: templateId,
+            p_date_from: params.dateFrom,
+            p_date_to: params.dateTo,
+        });
+        if (error) {
+            return toErrorContent(sanitizeDbError('Failed to generate income statement', error));
+        }
+        // Fetch the template's line_types so we can run the same synthesis the
+        // web hook runs. Order MUST follow display_order — calculated subtotals
+        // depend on prior-line amounts being in the map first.
+        const { data: lineTypes, error: lineTypesError } = await supabase
+            .from('income_statement_line_types')
+            .select('*')
+            .eq('template_id', templateId)
+            .order('display_order', { ascending: true });
+        if (lineTypesError || !lineTypes) {
+            return toErrorContent(sanitizeDbError('Failed to load income statement template lines', lineTypesError));
+        }
+        // RPC returns rows ONLY for leaf (range-based) line_codes; calculated
+        // subtotals (LIIKEVOITTO, ...) are synthesized below.
+        const currentByLine = new Map();
+        for (const row of rpcRows ?? []) {
+            currentByLine.set(row.line_code, Number(row.current_amount));
+        }
+        const { lines } = synthesizeIncomeStatementLines(lineTypes, currentByLine, new Map());
+        // Build `subtotals` from every materialized line in the synthesis result
+        // (both leaf rows and calculated subtotals), rounded for cents safety.
+        const subtotals = {};
+        for (const line of lines) {
+            subtotals[line.lineCode] = roundCents(line.currentAmount);
+        }
+        // Roll up legacy revenue/expenses totals so existing prompt phrasing
+        // ("revenue total", "expense total") still works. After Wave 0
+        // realignment (2026-04-27, plan: tuloslaskelma-rationalization-plan.md)
+        // every leaf row carries sign_convention='positive' and the RPC returns
+        // amounts in their natural sign — revenue rows positive, expense rows
+        // negative. Bucket by line_type ('credit'=revenue / 'debit'=expense)
+        // because signConvention is no longer a discriminator.
+        let totalRevenue = 0;
+        let totalExpenses = 0;
+        for (const line of lines) {
+            if (line.isCalculated)
+                continue;
+            if (line.lineType === 'debit') {
+                totalExpenses += -line.currentAmount;
+            }
+            else if (line.lineType === 'credit') {
+                totalRevenue += line.currentAmount;
+            }
+        }
+        // Prefer the synthesized bottom-line; fall back to liikevoitto, then to
+        // raw revenue-expenses for templates that don't define TILIKAUDEN_TULOS.
+        // Use key-presence checks (not truthiness) — a dormant or break-even
+        // year legitimately yields TILIKAUDEN_TULOS = 0, and `||` would skip it
+        // and report an inflated net_profit from the next fallback.
+        const netProfit = 'TILIKAUDEN_TULOS' in subtotals
+            ? subtotals.TILIKAUDEN_TULOS
+            : 'LIIKEVOITTO' in subtotals
+                ? subtotals.LIIKEVOITTO
+                : totalRevenue - totalExpenses;
+        return toResult({
+            period: { from: params.dateFrom, to: params.dateTo },
+            revenue: {
+                total: roundCents(totalRevenue),
+                total_formatted: formatCurrency(totalRevenue),
+            },
+            expenses: {
+                total: roundCents(totalExpenses),
+                total_formatted: formatCurrency(totalExpenses),
+            },
+            net_profit: roundCents(netProfit),
+            net_profit_formatted: formatCurrency(netProfit),
+            subtotals,
+        });
+    });
+    // ---- Balance Sheet ----
+    server.registerTool('kirjapro_get_balance_sheet', {
+        description: 'Generate balance sheet (tase) as of a specific date. Shows assets, liabilities, and equity with account-level detail. If fiscalYearId is omitted, the single open fiscal year is used.',
+        inputSchema: {
+            fiscalYearId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe('Fiscal year UUID (auto-resolved to the open fiscal year if omitted)'),
+            reportDate: ISO_DATE_SCHEMA
+                .describe('Report date (YYYY-MM-DD)'),
+        },
+        outputSchema: BALANCE_SHEET_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        let fiscalYearId;
+        if (params.fiscalYearId) {
+            fiscalYearId = params.fiscalYearId;
+        }
+        else {
+            const resolved = await resolveOpenFiscalYear(supabase, companyId);
+            if ('isError' in resolved)
+                return resolved;
+            fiscalYearId = resolved.id;
+        }
+        const BS_ENTRY_CAP = 50_000;
+        // Pull rev/expense entries alongside balance-sheet entries so we can
+        // synthesise mid-year tilikauden tulos (DT-043) for open fiscal years
+        // where account 3600 has no closing-entry balance yet. Without this,
+        // `balanced` reports false for every open-FY company, contradicting
+        // the web Tase (DT-041 + DT-043) and giving AI agents a false signal.
+        const { data: entries, count: bsEntryCount, error } = await supabase
+            .from('journal_entries')
+            .select(`
+          debit_amount, credit_amount,
+          account:accounts!inner(id, account_number, name, account_type),
+          transaction:transactions!inner(fiscal_year_id, transaction_date, company_id)
+        `, { count: 'exact' })
+            .eq('transaction.fiscal_year_id', fiscalYearId)
+            .eq('transaction.company_id', companyId)
+            .lte('transaction.transaction_date', params.reportDate)
+            .limit(BS_ENTRY_CAP);
+        if (error) {
+            return toErrorContent(sanitizeDbError("Failed to generate balance sheet", error));
+        }
+        // Aggregate by account. Keep rev/expense d-c sums for the synth path
+        // (DT-043) — they are NOT pushed onto assets/liabilities/equity arrays.
+        const accountTotals = new Map();
+        let synthRevExpDMinusC = 0;
+        let account3600Balance = 0;
+        for (const entry of entries || []) {
+            const acc = entry.account;
+            if (!acc)
+                continue;
+            const debit = entry.debit_amount || 0;
+            const credit = entry.credit_amount || 0;
+            if (acc.account_type === 'revenue' || acc.account_type === 'expense') {
+                synthRevExpDMinusC += debit - credit;
+                continue;
+            }
+            const balanceTypes = ['asset', 'liability', 'equity'];
+            if (!balanceTypes.includes(acc.account_type))
+                continue;
+            if (acc.account_number === '3600') {
+                account3600Balance += credit - debit;
+            }
+            const key = acc.account_number;
+            const existing = accountTotals.get(key) || {
+                account_number: acc.account_number,
+                name: acc.name,
+                account_type: acc.account_type,
+                balance: 0,
+            };
+            if (acc.account_type === 'asset') {
+                existing.balance += debit - credit;
+            }
+            else {
+                existing.balance += credit - debit;
+            }
+            accountTotals.set(key, existing);
+        }
+        const assets = [];
+        const liabilities = [];
+        const equity = [];
+        let totalAssets = 0;
+        let totalLiabilities = 0;
+        let totalEquity = 0;
+        for (const [, acc] of [...accountTotals].sort((a, b) => a[0].localeCompare(b[0]))) {
+            acc.balance = roundCents(acc.balance);
+            switch (acc.account_type) {
+                case 'asset':
+                    assets.push(acc);
+                    totalAssets += acc.balance;
+                    break;
+                case 'liability':
+                    liabilities.push(acc);
+                    totalLiabilities += acc.balance;
+                    break;
+                case 'equity':
+                    equity.push(acc);
+                    totalEquity += acc.balance;
+                    break;
+            }
+        }
+        const bsCapped = (bsEntryCount || 0) >= BS_ENTRY_CAP;
+        // DT-043: synthetic mid-year tilikauden tulos. When account 3600
+        // hasn't been posted to (open FY, closing entry deferred), surface
+        // the implied profit so totals balance. Skip when 3600 already has
+        // a balance (closed FY: closing entry done, would double-count).
+        // Sign: synthRevExpDMinusC = -profit under d-c convention; flip to
+        // +profit for display.
+        const syntheticTilikaudenTulos = account3600Balance === 0 ? roundCents(-synthRevExpDMinusC) : 0;
+        const totalEquityWithSynth = totalEquity + syntheticTilikaudenTulos;
+        return toResult({
+            report_date: params.reportDate,
+            assets: {
+                accounts: assets,
+                total: roundCents(totalAssets),
+                total_formatted: formatCurrency(totalAssets),
+            },
+            liabilities: {
+                accounts: liabilities,
+                total: roundCents(totalLiabilities),
+                total_formatted: formatCurrency(totalLiabilities),
+            },
+            equity: {
+                accounts: equity,
+                total: roundCents(totalEquityWithSynth),
+                total_formatted: formatCurrency(totalEquityWithSynth),
+                synthetic_tilikauden_tulos: syntheticTilikaudenTulos,
+                ...(syntheticTilikaudenTulos !== 0 && {
+                    synthetic_note: 'Tilikauden tulos (kesken) — kirjattu mukaan oma pääoma -summaan, mutta EI jakokelpoinen ennen tilinpäätöksen vahvistamista (OYL 13:5§).',
+                }),
+            },
+            total_liabilities_and_equity: roundCents(totalLiabilities + totalEquityWithSynth),
+            balanced: Math.abs(totalAssets - (totalLiabilities + totalEquityWithSynth)) < 0.01,
+            ...(bsCapped && { warning: `Results capped at ${BS_ENTRY_CAP} journal entries. Totals may be approximate.` }),
+        });
+    });
+    // ---- AR Aging ----
+    server.registerTool('kirjapro_get_ar_aging', {
+        description: 'Get accounts receivable aging report. Shows unpaid invoices grouped by days overdue: 0-30, 31-60, 61-90, 90+ days. Includes Days Sales Outstanding (DSO).',
+        inputSchema: {},
+        outputSchema: AR_AGING_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async () => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        const { data: invoices, error } = await supabase
+            .from('invoices')
+            .select('id, invoice_number, total, due_date, invoice_date, customers(name)')
+            .eq('company_id', companyId)
+            .in('status', ['sent', 'overdue']);
+        if (error) {
+            return toErrorContent(sanitizeDbError("Failed to get AR aging", error));
+        }
+        // Use Helsinki-local "today" so bucket assignment near midnight-UTC
+        // is consistent with get_dashboard's overdue detection (same helper).
+        const todayStr = helsinkiDateString();
+        const todayMs = Date.parse(todayStr);
+        const buckets = [
+            { label: '0-30 days', min: 0, max: 30, count: 0, total: 0, invoices: [] },
+            { label: '31-60 days', min: 31, max: 60, count: 0, total: 0, invoices: [] },
+            { label: '61-90 days', min: 61, max: 90, count: 0, total: 0, invoices: [] },
+            { label: '90+ days', min: 91, max: Infinity, count: 0, total: 0, invoices: [] },
+        ];
+        let totalReceivables = 0;
+        let weightedDays = 0;
+        const noDueDate = [];
+        for (const inv of invoices || []) {
+            // invoices.due_date is nullable in DB. `new Date(null)` yields NaN, and
+            // the old bucket.find(...)! returned undefined + crashed on count++.
+            // Surface null-due-date rows in a separate field so the agent can
+            // prompt the user to set a due date, rather than silently hiding them.
+            if (!inv.due_date) {
+                noDueDate.push({
+                    invoice_number: inv.invoice_number,
+                    customer: tagUntrusted(inv.customers?.name),
+                    total: inv.total || 0,
+                });
+                totalReceivables += inv.total || 0;
+                continue;
+            }
+            const dueMs = Date.parse(inv.due_date);
+            if (Number.isNaN(dueMs)) {
+                noDueDate.push({
+                    invoice_number: inv.invoice_number,
+                    customer: tagUntrusted(inv.customers?.name),
+                    total: inv.total || 0,
+                });
+                totalReceivables += inv.total || 0;
+                continue;
+            }
+            const daysOverdue = Math.max(0, Math.floor((todayMs - dueMs) / 86400000));
+            const bucket = buckets.find((b) => daysOverdue >= b.min && daysOverdue <= b.max);
+            if (!bucket)
+                continue;
+            bucket.count++;
+            bucket.total += inv.total || 0;
+            bucket.invoices.push({
+                invoice_number: inv.invoice_number,
+                customer: tagUntrusted(inv.customers?.name),
+                total: inv.total,
+                due_date: inv.due_date,
+                days_overdue: daysOverdue,
+            });
+            totalReceivables += inv.total || 0;
+            weightedDays += daysOverdue * (inv.total || 0);
+        }
+        // DSO = weighted average days
+        const dso = totalReceivables > 0 ? Math.round(weightedDays / totalReceivables) : 0;
+        return toResult({
+            buckets: buckets.map((b) => ({
+                label: b.label,
+                count: b.count,
+                total: roundCents(b.total),
+                total_formatted: formatCurrency(b.total),
+                invoices: b.invoices,
+            })),
+            no_due_date: {
+                count: noDueDate.length,
+                total: roundCents(noDueDate.reduce((s, i) => s + (i.total || 0), 0)),
+                invoices: noDueDate,
+            },
+            total_receivables: roundCents(totalReceivables),
+            total_receivables_formatted: formatCurrency(totalReceivables),
+            days_sales_outstanding: dso,
+        });
+    });
+    // ---- General Ledger ----
+    server.registerTool('kirjapro_get_general_ledger', {
+        description: 'Get general ledger (pääkirja) for a single account within a fiscal year. Shows all journal entries with running balance. Assets and expenses use debit-normal balance; liabilities, equity, and revenue use credit-normal. If fiscalYearId is omitted, the single open fiscal year is used.',
+        inputSchema: {
+            accountNumber: z.string().describe('Account number (e.g. "3000")'),
+            fiscalYearId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe('Fiscal year UUID (auto-resolved to the open fiscal year if omitted)'),
+            dateFrom: ISO_DATE_SCHEMA
+                .optional()
+                .describe('Start date filter (YYYY-MM-DD)'),
+            dateTo: ISO_DATE_SCHEMA
+                .optional()
+                .describe('End date filter (YYYY-MM-DD)'),
+        },
+        outputSchema: GENERAL_LEDGER_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        let fiscalYearId;
+        if (params.fiscalYearId) {
+            fiscalYearId = params.fiscalYearId;
+        }
+        else {
+            const resolved = await resolveOpenFiscalYear(supabase, companyId);
+            if ('isError' in resolved)
+                return resolved;
+            fiscalYearId = resolved.id;
+        }
+        // Resolve account number to get account details
+        const { data: account, error: accError } = await supabase
+            .from('accounts')
+            .select('id, account_number, name, account_type')
+            .eq('company_id', companyId)
+            .eq('account_number', params.accountNumber)
+            .single();
+        if (accError || !account) {
+            return toErrorContent(`Account "${params.accountNumber}" not found. Use kirjapro_list_accounts to see available accounts.`);
+        }
+        // Fetch journal entries for this account in the fiscal year. We fetch
+        // LEDGER_FETCH_LIMIT + 1 rows so we can detect truncation and surface
+        // a `capped: true` signal to the agent — otherwise a busy account
+        // silently returns a partial ledger and the closing balance is wrong.
+        const LEDGER_FETCH_LIMIT = 5000;
+        let query = supabase
+            .from('journal_entries')
+            .select(`
+          debit_amount, credit_amount,
+          transaction:transactions!inner(id, transaction_date, description, document_number, fiscal_year_id, company_id)
+        `)
+            .eq('account_id', account.id)
+            .eq('transaction.fiscal_year_id', fiscalYearId)
+            .eq('transaction.company_id', companyId)
+            .order('transaction(transaction_date)', { ascending: true })
+            .order('id', { ascending: true })
+            .range(0, LEDGER_FETCH_LIMIT);
+        if (params.dateFrom) {
+            query = query.gte('transaction.transaction_date', params.dateFrom);
+        }
+        if (params.dateTo) {
+            query = query.lte('transaction.transaction_date', params.dateTo);
+        }
+        const { data: entries, error } = await query;
+        if (error) {
+            return toErrorContent(sanitizeDbError("Failed to get general ledger", error));
+        }
+        // Determine balance direction: debit-normal for assets/expenses, credit-normal for others
+        const debitNormal = ['asset', 'expense'];
+        const isDebitNormal = debitNormal.includes(account.account_type);
+        // When dateFrom is applied, compute opening balance from entries
+        // before that date so the running balance starts correctly.
+        let openingBalance = 0;
+        if (params.dateFrom) {
+            const { data: priorEntries, error: priorErr } = await supabase
+                .from('journal_entries')
+                .select(`
+            debit_amount, credit_amount,
+            transaction:transactions!inner(fiscal_year_id, company_id, transaction_date)
+          `)
+                .eq('account_id', account.id)
+                .eq('transaction.fiscal_year_id', fiscalYearId)
+                .eq('transaction.company_id', companyId)
+                .lt('transaction.transaction_date', params.dateFrom);
+            if (!priorErr && priorEntries) {
+                for (const e of priorEntries) {
+                    const d = e.debit_amount || 0;
+                    const c = e.credit_amount || 0;
+                    openingBalance += isDebitNormal ? (d - c) : (c - d);
+                }
+                openingBalance = roundCents(openingBalance);
+            }
+        }
+        // Detect truncation and drop the probe row BEFORE computing running
+        // balance — otherwise the probe row's debit/credit would leak into the
+        // closing balance and break the invariant `entry_count == entries.length`.
+        const fetched = entries || [];
+        const capped = fetched.length > LEDGER_FETCH_LIMIT;
+        const consumed = capped ? fetched.slice(0, LEDGER_FETCH_LIMIT) : fetched;
+        // Build ledger with running balance
+        let runningBalance = openingBalance;
+        const ledgerEntries = [];
+        for (const entry of consumed) {
+            const tx = entry.transaction;
+            const debit = entry.debit_amount || 0;
+            const credit = entry.credit_amount || 0;
+            if (isDebitNormal) {
+                runningBalance += debit - credit;
+            }
+            else {
+                runningBalance += credit - debit;
+            }
+            ledgerEntries.push({
+                date: tx.transaction_date,
+                description: tx.description,
+                document_number: tx.document_number,
+                transaction_id: tx.id,
+                debit: roundCents(debit),
+                credit: roundCents(credit),
+                running_balance: roundCents(runningBalance),
+            });
+        }
+        return toResult({
+            account: {
+                account_number: account.account_number,
+                name: account.name,
+                account_type: account.account_type,
+                balance_type: isDebitNormal ? 'debit-normal' : 'credit-normal',
+            },
+            entries: ledgerEntries,
+            entry_count: ledgerEntries.length,
+            opening_balance: openingBalance,
+            closing_balance: roundCents(runningBalance),
+            closing_balance_formatted: formatCurrency(runningBalance),
+            capped,
+            capped_note: capped
+                ? `Result truncated at ${LEDGER_FETCH_LIMIT} entries. Closing balance is computed from fetched rows only and may not reflect the full fiscal-year total. Narrow the date range with dateFrom/dateTo to see the remainder.`
+                : null,
+        });
+    });
+    // ---- ALV Summary ----
+    server.registerTool('kirjapro_get_alv_summary', {
+        description: 'Get VAT (ALV) summary for a date range. Returns output/input VAT breakdown by rate and OmaVero field codes (301-320). For filing deadlines, read kirjapro://compliance/deadlines.',
+        inputSchema: {
+            dateFrom: ISO_DATE_SCHEMA
+                .describe('Period start date (YYYY-MM-DD)'),
+            dateTo: ISO_DATE_SCHEMA
+                .describe('Period end date (YYYY-MM-DD)'),
+        },
+        outputSchema: ALV_SUMMARY_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        const { data, error } = await supabase.rpc('get_alv_summary', {
+            p_company_id: companyId,
+            p_date_from: params.dateFrom,
+            p_date_to: params.dateTo,
+        });
+        if (error) {
+            return toErrorContent(sanitizeDbError("Failed to get ALV summary", error));
+        }
+        const result = data;
+        if (!result) {
+            return toResult({
+                period: { from: params.dateFrom, to: params.dateTo },
+                message: 'No VAT data found for this period.',
+            });
+        }
+        return toResult({
+            ...result,
+            period: { from: params.dateFrom, to: params.dateTo },
+            net_vat_payable_formatted: formatCurrency(result.net_vat_payable || 0),
+        });
+    });
+}