@hearthlog/module-finance 0.0.0-stage → 1.0.1

package/src/components/finance/TransactionSelectionBar.svelte

@@ -0,0 +1,200 @@
+<script lang="ts">
+    import type { TransactionSelectionSummary } from "../../data/transactions.js";
+    import { queryDatabase } from "@hearthlog/sdk/data";
+    import { formatMoney } from "@hearthlog/sdk/format";
+    import { Button } from "@hearthlog/sdk/ui";
+    import { DatePicker } from "@hearthlog/sdk/ui";
+    import { Field } from "@hearthlog/sdk/ui";
+    import { CommandOnly } from "@hearthlog/sdk/ui";
+    import { CommandModal } from "@hearthlog/sdk/ui";
+    import { CommandConfirmDialog } from "@hearthlog/sdk/ui";
+    import type { RowLike } from "./TimelineRowItem.svelte";
+
+    let {
+        selected,
+        visibleCount,
+        today,
+        onClear,
+        onSelectAll,
+        onMove,
+        onSetDone,
+        onDelete,
+    }: {
+        /** Selected rows, in list order. */
+        selected: RowLike[];
+        visibleCount: number;
+        today: string;
+        onClear: () => void;
+        onSelectAll: () => void;
+        onMove: (rows: RowLike[], date: string) => Promise<void>;
+        /** Marks the selected plans done, or restores rows done ahead of their day to plans. */
+        onSetDone: (rows: RowLike[], done: boolean) => Promise<void>;
+        onDelete: (rows: RowLike[]) => Promise<void>;
+    } = $props();
+
+    const empty: TransactionSelectionSummary = { count: 0, incomeTotal: 0, expenseTotal: 0, netTotal: 0 };
+    let summary = $state<TransactionSelectionSummary>({ ...empty });
+    let summaryLoading = $state(false);
+    let busy = $state(false);
+    let moveOpen = $state(false);
+    let moveDate = $state("");
+    let moveError = $state("");
+    let confirmDeleteOpen = $state(false);
+
+    const count = $derived(selected.length);
+    const allSelected = $derived(count > 0 && count === visibleCount);
+    // Plans can be marked done early; a row done ahead of its day can go back
+    // to plans. Rows whose day has passed are done by date and offer neither.
+    const statusAction = $derived.by(() => {
+        const plans = selected.filter((row) => row.kind === "planned");
+        if (plans.length > 0) return { label: "Mark done", done: true, rows: plans };
+        const ahead = selected.filter((row) => row.kind === "done" && row.date >= today);
+        return ahead.length > 0 ? { label: "Restore", done: false, rows: ahead } : null;
+    });
+    const noun = (value: number) => (value === 1 ? "transaction" : "transactions");
+    const deleteMessage = $derived.by(() => {
+        const names = selected.map((row) => row.name || "Untitled");
+        if (names.length === 1) return `Delete “${names[0]}”?`;
+        return `Remove these ${names.length} transactions: ${names.slice(0, 10).join(", ")}${names.length > 10 ? ", …" : ""}?`;
+    });
+
+    // Totals are a separate SQL query so ticking a checkbox never re-scans rows.
+    $effect(() => {
+        const ids = selected.map((row) => row.id);
+        if (ids.length === 0) {
+            summary = { ...empty };
+            summaryLoading = false;
+            return;
+        }
+        let cancelled = false;
+        summaryLoading = true;
+        queryDatabase((repositories) => repositories.transactions.getSelectionSummary(ids))
+            .then((result) => { if (!cancelled) summary = result; })
+            .catch(() => { if (!cancelled) summary = { ...empty }; })
+            .finally(() => { if (!cancelled) summaryLoading = false; });
+        return () => { cancelled = true; };
+    });
+
+    function openMove(): void {
+        moveDate = selected.map((row) => row.date).sort()[0] ?? today;
+        moveError = "";
+        moveOpen = true;
+    }
+
+    async function run(action: () => Promise<void>): Promise<boolean> {
+        if (busy || count === 0) return false;
+        busy = true;
+        try {
+            await action();
+            return true;
+        } catch {
+            return false;
+        } finally {
+            busy = false;
+        }
+    }
+
+    async function confirmMove(): Promise<void> {
+        const date = moveDate.trim().slice(0, 10);
+        if (!date) {
+            moveError = "Choose a date first.";
+            return;
+        }
+        moveError = "";
+        const targets = selected;
+        const moved = await run(() => onMove(targets, date));
+        if (moved) moveOpen = false;
+        else moveError = "The transactions could not be moved. Your values are still here.";
+    }
+
+    async function toggleDone(): Promise<void> {
+        const action = statusAction;
+        if (!action) return;
+        await run(() => onSetDone(action.rows, action.done));
+    }
+
+    async function confirmDelete(): Promise<void> {
+        confirmDeleteOpen = false;
+        const targets = selected;
+        await run(() => onDelete(targets));
+    }
+</script>
+
+{#snippet totals()}
+    {#if summaryLoading}
+        <span class="text-[var(--stor-muted-text)]">Calculating totals…</span>
+    {:else}
+        <div><span class="text-[var(--stor-muted-text)]">Income</span> <strong class="ml-1 tabular-nums">{formatMoney(summary.incomeTotal, { signed: true })}</strong></div>
+        <div><span class="text-[var(--stor-muted-text)]">Expenses</span> <strong class="ml-1 tabular-nums">{formatMoney(-summary.expenseTotal)}</strong></div>
+        <div><span class="text-[var(--stor-muted-text)]">Net</span> <strong class="ml-1 tabular-nums">{formatMoney(summary.netTotal)}</strong></div>
+    {/if}
+{/snippet}
+
+{#if count > 0}
+    <div class="sticky top-0 z-[4] hidden lg:block">
+        <div class="flex flex-wrap items-center gap-x-3 gap-y-1 bg-[var(--stor-surface-muted)] px-4 py-2 text-xs text-[var(--stor-muted-text)]" role="status">
+            {#if allSelected}
+                <span>All {count} {noun(count)} in this view {count === 1 ? "is" : "are"} selected.</span>
+                <button type="button" onclick={onClear} class="font-semibold text-[var(--stor-accent-strong)] hover:underline">Clear selection</button>
+            {:else}
+                <span>{count} of {visibleCount} {noun(visibleCount)} in this view {count === 1 ? "is" : "are"} selected.</span>
+                <button type="button" onclick={onSelectAll} class="font-semibold text-[var(--stor-accent-strong)] hover:underline">Select all {visibleCount}</button>
+            {/if}
+        </div>
+        <div class="flex flex-wrap items-center gap-x-6 gap-y-2 bg-[var(--stor-accent-soft)] px-4 py-2.5 text-sm" aria-label="Selected transaction totals">
+            <strong>{count} selected</strong>
+            {@render totals()}
+            <div class="ml-auto flex items-center gap-2">
+                <CommandOnly>
+                    <Button size="sm" disabled={busy} onclick={openMove}>Move</Button>
+                    {#if statusAction}<Button size="sm" variant="secondary" disabled={busy} onclick={() => void toggleDone()}>{statusAction.label}</Button>{/if}
+                    <Button size="sm" variant="ghost" class="text-[var(--stor-negative)]" disabled={busy} onclick={() => (confirmDeleteOpen = true)}>Delete</Button>
+                </CommandOnly>
+                <button type="button" onclick={onClear} class="h-9 px-2 text-sm text-[var(--stor-accent-strong)]">Clear selection</button>
+            </div>
+        </div>
+    </div>
+
+    <div class="fixed inset-x-3 bottom-[calc(var(--stor-mobile-bottom-inset)+var(--stor-mobile-nav-height)+var(--stor-mobile-stack-gap))] z-40 md:left-[116px] rounded-2xl bg-[var(--stor-surface-raised)] p-3 shadow-[var(--stor-elevation-3)] lg:hidden" aria-label="Selected transaction totals">
+        <div class="flex items-center justify-between gap-2">
+            <strong>{count} selected</strong>
+            <div class="flex items-center gap-3 text-sm">
+                {#if !allSelected}<button type="button" onclick={onSelectAll} class="min-h-11 text-[var(--stor-accent-strong)]">Select all {visibleCount}</button>{/if}
+                <button type="button" onclick={onClear} class="min-h-11 text-[var(--stor-accent-strong)]">Cancel</button>
+            </div>
+        </div>
+        <div class="mt-1 grid grid-cols-3 gap-2 text-sm [&_div]:flex [&_div]:flex-col">
+            {@render totals()}
+        </div>
+        <CommandOnly>
+            <div class="mt-3 grid gap-2 {statusAction ? 'grid-cols-3' : 'grid-cols-2'}">
+                {#if statusAction}<Button class="md:hidden" disabled={busy} onclick={() => void toggleDone()}>{statusAction.label === "Mark done" ? "Done" : statusAction.label}</Button>{/if}
+                <Button class={statusAction ? "max-md:!bg-transparent max-md:!text-[var(--stor-ink)] max-md:!shadow-none" : ""} disabled={busy} onclick={openMove}>Move</Button>
+                {#if statusAction}<Button variant="secondary" class="max-md:hidden" disabled={busy} onclick={() => void toggleDone()}>{statusAction.label}</Button>{/if}
+                <Button variant="ghost" class="bg-[var(--stor-negative-soft)] text-[var(--stor-negative)]" disabled={busy} onclick={() => (confirmDeleteOpen = true)}>Delete</Button>
+            </div>
+        </CommandOnly>
+    </div>
+{/if}
+
+<CommandModal show={moveOpen} title={count === 1 ? "Move 1 transaction" : `Move ${count} transactions`} onClose={() => (moveOpen = false)}>
+    <p class="text-sm text-[var(--stor-muted-text)]">Pick the new date for the selected {noun(count)}.</p>
+    <Field label="New date" htmlFor="move-transactions-date" class="mt-4">
+        <DatePicker id="move-transactions-date" bind:value={moveDate} clearable={false} />
+    </Field>
+    {#if moveError}
+        <p class="mt-2 text-sm text-[var(--stor-negative)]" role="alert">{moveError}</p>
+    {/if}
+    <div class="mt-5 flex items-center justify-end gap-2">
+        <Button variant="secondary" onclick={() => (moveOpen = false)} disabled={busy}>Cancel</Button>
+        <Button onclick={() => void confirmMove()} disabled={busy || !moveDate.trim()}>{busy ? "Moving…" : "Move here"}</Button>
+    </div>
+</CommandModal>
+
+<CommandConfirmDialog
+    show={confirmDeleteOpen}
+    title={count === 1 ? "Delete transaction?" : `Delete ${count} transactions?`}
+    message={deleteMessage}
+    onConfirm={confirmDelete}
+    onCancel={() => (confirmDeleteOpen = false)}
+/>

package/src/components/finance/timeline-months.svelte.ts

@@ -0,0 +1,37 @@
+import { BucketStore } from '@hearthlog/sdk/endless';
+import { queryDatabase } from '@hearthlog/sdk/data';
+import type { TimelineMonth, TimelineRow } from '../../data/finance-timeline.js';
+import { monthWindow, type TimelineShow } from '../../finance/timeline.js';
+
+export interface MonthData {
+    key: string;
+    stats: TimelineMonth;
+    /** SQL-ordered rows of the kind shown. */
+    rows: TimelineRow[];
+}
+
+/**
+ * Loaded months of the endless timeline. Each batch of months that scroll
+ * into view is one SQL session: month totals plus rows per month.
+ */
+export class TimelineMonths extends BucketStore<MonthData> {
+    constructor(params: () => { today: string; show: TimelineShow }) {
+        super(async (keys) => {
+            const { today, show } = params();
+            const result = await queryDatabase(async (repositories) => {
+                const [stats, ...rows] = await Promise.all([
+                    repositories.timeline.getMonths({ today, from: monthWindow(keys[0]).start, to: monthWindow(keys[keys.length - 1]).end, show }),
+                    ...keys.map((key) => repositories.timeline.getRows({ today, ...monthWindow(key), show })),
+                ]);
+                return { stats, rows };
+            });
+            const statsByMonth = new Map(result.stats.map((month) => [month.month, month]));
+            const months = new Map<string, MonthData>();
+            keys.forEach((key, index) => {
+                const stats = statsByMonth.get(key);
+                if (stats) months.set(key, { key, stats, rows: result.rows[index] });
+            });
+            return months;
+        }, '[Finance] Could not load timeline months');
+    }
+}

package/src/components/finance/transaction-draft.ts

@@ -0,0 +1,121 @@
+import { addDays, format, parseISO } from "date-fns";
+import type { Transaction } from "../../data/transactions.js";
+
+/** A daily repeat adds at most a year of transactions in one save. */
+export const MAX_REPEAT_DAYS = 366;
+
+export interface TransactionDraft {
+    id?: string;
+    name: string;
+    amount: number;
+    dueDate: string;
+    category: string;
+    status: "active" | "archived";
+    direction: "expense" | "income";
+    /**
+     * Where the category came from (`manual`, `history`, `ai:<model>`). Left
+     * undefined when the category was not touched, so a save keeps what is stored.
+     */
+    categorySource?: string;
+}
+
+export function createTransactionDraft(
+    dueDate: string,
+    transaction?: Transaction,
+): TransactionDraft {
+    if (!transaction) {
+        return {
+            name: "",
+            amount: 0,
+            dueDate,
+            category: "unknown",
+            status: "active",
+            direction: "expense",
+        };
+    }
+
+    return {
+        id: transaction.id,
+        name: transaction.name ?? "",
+        amount: Math.abs(transaction.amount),
+        dueDate: transaction.due_date?.slice(0, 10) ?? dueDate,
+        category: transaction.transaction_category || "unknown",
+        status:
+            transaction.transaction_status === "archived"
+                ? "archived"
+                : "active",
+        direction: transaction.amount >= 0 ? "income" : "expense",
+    };
+}
+
+/**
+ * Only an entry dated today asks whether it already happened: earlier days
+ * are done by their date and later days are plans.
+ */
+export function canMarkHappened(draft: TransactionDraft, today: string): boolean {
+    return draft.dueDate !== "" && draft.dueDate === today;
+}
+
+/** "Already happened" starts checked for a transaction that is done, and unchecked for a plan or a new entry. */
+export function defaultHappened(initialStatus: TransactionDraft["status"]): boolean {
+    return initialStatus === "archived";
+}
+
+/**
+ * An existing row marked done ahead of its day. It stays done on another
+ * later date, while a row that is done only because its day passed turns
+ * back into a plan.
+ */
+export function isDoneAhead(initial: TransactionDraft, today: string): boolean {
+    return !!initial.id && initial.status === "archived" && today !== "" && initial.dueDate >= today;
+}
+
+/**
+ * The status a save stores. Anything dated before today is done, today
+ * follows "Already happened", and a later date is a plan unless the row was
+ * already done ahead of its day.
+ */
+export function resolveDraftStatus(
+    draft: TransactionDraft,
+    today: string,
+    alreadyHappened: boolean,
+    doneAhead = false,
+): TransactionDraft["status"] {
+    if (!draft.dueDate || !today) return draft.id ? draft.status : "active";
+    if (draft.dueDate < today) return "archived";
+    if (draft.dueDate === today) return alreadyHappened ? "archived" : "active";
+    return doneAhead ? "archived" : "active";
+}
+
+/** A daily repeat covers two to {@link MAX_REPEAT_DAYS} whole days. */
+export function isRepeatDays(days: number): boolean {
+    return Number.isInteger(days) && days >= 2 && days <= MAX_REPEAT_DAYS;
+}
+
+/**
+ * The transactions one save creates: the draft itself, or one per day for a
+ * daily repeat of a new transaction. Days before today are done, today
+ * follows "Already happened", and later days stay plans.
+ */
+export function expandDraft(
+    draft: TransactionDraft,
+    days: number,
+    today: string,
+    alreadyHappened: boolean,
+    doneAhead = false,
+): TransactionDraft[] {
+    if (draft.id || !draft.dueDate || !isRepeatDays(days)) return [{ ...draft, status: resolveDraftStatus(draft, today, alreadyHappened, doneAhead) }];
+    const start = parseISO(draft.dueDate);
+    return Array.from({ length: days }, (_, index) => {
+        const day = { ...draft, dueDate: format(addDays(start, index), "yyyy-MM-dd") };
+        return { ...day, status: resolveDraftStatus(day, today, alreadyHappened) };
+    });
+}
+
+/** `28 Sep – 11 Oct`, naming the years only when the range crosses one. */
+export function formatDayRange(first: string, last: string): string {
+    const start = parseISO(first);
+    const end = parseISO(last);
+    const pattern = start.getFullYear() === end.getFullYear() ? "d MMM" : "d MMM yyyy";
+    return `${format(start, pattern)} – ${format(end, pattern)}`;
+}

package/src/data/assets.ts

@@ -0,0 +1,48 @@
+import type { Asset } from '@hearthlog/sdk/data';
+import type { ReadModelSession } from '@hearthlog/sdk/data';
+import { withTimeout } from '@hearthlog/sdk/data';
+
+export type { Asset };
+
+const DB_TIMEOUT_MS = 5000;
+
+export function createAssetRepository(session: ReadModelSession) {
+    return {
+        getAssets(): Promise<Asset[]> {
+            return withTimeout(
+                session.selectFrom('assets')
+                    .selectAll()
+                    .orderBy('created_at', 'asc')
+                    .orderBy('id', 'asc')
+                    .execute(),
+                DB_TIMEOUT_MS,
+                'getAssets query timed out',
+            );
+        },
+
+        async getSumOfAssetsByType(category: string): Promise<number> {
+            const result = await withTimeout(
+                session.selectFrom('assets')
+                    .select(({ fn }) => fn.sum('amount').as('sum'))
+                    .where('asset_type', '=', category)
+                    .executeTakeFirst(),
+                DB_TIMEOUT_MS,
+                'getSumOfAssetsByType query timed out',
+            );
+            return Number(result?.sum ?? 0);
+        },
+
+        getAssetsByType(assetType: string): Promise<Asset[]> {
+            return withTimeout(
+                session.selectFrom('assets')
+                    .selectAll()
+                    .where('asset_type', '=', assetType)
+                    .orderBy('created_at', 'asc')
+                    .orderBy('id', 'asc')
+                    .execute(),
+                DB_TIMEOUT_MS,
+                'getAssetsByType query timed out',
+            );
+        },
+    };
+}

package/src/data/budgets.ts

@@ -0,0 +1,123 @@
+import type { BudgetItem, BudgetPlan } from '@hearthlog/sdk/data';
+import type { ReadModelSession } from '@hearthlog/sdk/data';
+import { withTimeout } from '@hearthlog/sdk/data';
+import { sql } from 'kysely';
+
+const DB_TIMEOUT_MS = 5000;
+
+export interface BudgetPlanSummary extends BudgetPlan {
+    income_total: number;
+    expense_total: number;
+    item_count: number;
+}
+
+/** Name or amount sorting for one budget section; absent means creation order. */
+export type BudgetItemSort = 'name-asc' | 'name-desc' | 'amount-asc' | 'amount-desc';
+
+/** Income, expenses and net of a picked selection, aggregated in SQLite. */
+export interface BudgetItemSelectionSummary {
+    count: number;
+    incomeTotal: number;
+    expenseTotal: number;
+    /** Income minus expenses. */
+    netTotal: number;
+}
+
+/** Reads the `incomeSort` / `expenseSort` URL value; anything unknown falls back to creation order. */
+export function parseBudgetItemSort(value: string | null | undefined): BudgetItemSort | null {
+    return value === 'name-asc' || value === 'name-desc' || value === 'amount-asc' || value === 'amount-desc'
+        ? value
+        : null;
+}
+
+function toNumber(value: number | string | bigint | null | undefined): number {
+    const parsed = Number(value ?? 0);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function createBudgetRepository(session: ReadModelSession) {
+    return {
+        async getPlans(): Promise<BudgetPlanSummary[]> {
+            const result = await withTimeout(
+                session.execute(sql<BudgetPlan & {
+                    income_total: number | string | null;
+                    expense_total: number | string | null;
+                    item_count: number | string | null;
+                }>`
+                    SELECT plans.*,
+                        COALESCE(SUM(CASE WHEN items.item_type = 'income' THEN items.amount ELSE 0 END), 0) AS income_total,
+                        COALESCE(SUM(CASE WHEN items.item_type = 'expense' THEN items.amount ELSE 0 END), 0) AS expense_total,
+                        COUNT(items.id) AS item_count
+                    FROM ${session.table('budget_plans')} AS plans
+                    LEFT JOIN ${session.table('budget_items')} AS items
+                        ON items.tenant_id = plans.tenant_id
+                        AND items.log_id = plans.log_id
+                        AND items.plan_id = plans.id
+                    GROUP BY plans.id
+                    ORDER BY plans.created_at ASC, plans.id ASC
+                `),
+                DB_TIMEOUT_MS,
+                'Budget plans query timed out',
+            );
+            return result.rows.map((row) => ({
+                ...row,
+                income_total: toNumber(row.income_total),
+                expense_total: toNumber(row.expense_total),
+                item_count: toNumber(row.item_count),
+            }));
+        },
+
+        getPlanItems(planId: string, itemType: 'income' | 'expense', sort: BudgetItemSort | null = null): Promise<BudgetItem[]> {
+            const items = session.selectFrom('budget_items')
+                .selectAll()
+                .where('plan_id', '=', planId)
+                .where('item_type', '=', itemType);
+            // Ordering stays in SQL so the page never re-sorts loaded rows in JavaScript.
+            let ordered = items.orderBy('created_at', 'asc').orderBy('id', 'asc');
+            if (sort === 'amount-asc') ordered = items.orderBy('amount', 'asc').orderBy('id', 'asc');
+            else if (sort === 'amount-desc') ordered = items.orderBy('amount', 'desc').orderBy('id', 'asc');
+            else if (sort === 'name-asc') ordered = items.orderBy(sql`name COLLATE NOCASE`, 'asc').orderBy('id', 'asc');
+            else if (sort === 'name-desc') ordered = items.orderBy(sql`name COLLATE NOCASE`, 'desc').orderBy('id', 'asc');
+            return withTimeout(
+                ordered.execute(),
+                DB_TIMEOUT_MS,
+                'Budget items query timed out',
+            );
+        },
+
+        /**
+         * Income, expenses and net of a picked set of items. Selection totals are
+         * aggregated in SQLite so the page never sums rows in JavaScript.
+         */
+        async getSelectionSummary(ids: string[]): Promise<BudgetItemSelectionSummary> {
+            if (ids.length === 0) {
+                return { count: 0, incomeTotal: 0, expenseTotal: 0, netTotal: 0 };
+            }
+            const result = await withTimeout(
+                session.execute(sql<{
+                    selected_count: number | string | null;
+                    income_total: number | string | null;
+                    expense_total: number | string | null;
+                    net_total: number | string | null;
+                }>`
+                    SELECT
+                        COUNT(*) AS selected_count,
+                        COALESCE(SUM(CASE WHEN item_type = 'income' THEN amount ELSE 0 END), 0) AS income_total,
+                        COALESCE(SUM(CASE WHEN item_type = 'expense' THEN amount ELSE 0 END), 0) AS expense_total,
+                        COALESCE(SUM(CASE WHEN item_type = 'income' THEN amount ELSE -amount END), 0) AS net_total
+                    FROM ${session.table('budget_items')} AS items
+                    WHERE id IN (${sql.join(ids)})
+                `),
+                DB_TIMEOUT_MS,
+                'Budget item selection summary timed out',
+            );
+            const row = result.rows[0];
+            return {
+                count: toNumber(row?.selected_count),
+                incomeTotal: toNumber(row?.income_total),
+                expenseTotal: toNumber(row?.expense_total),
+                netTotal: toNumber(row?.net_total),
+            };
+        },
+    };
+}

package/src/data/definitions.ts

@@ -0,0 +1,135 @@
+/**
+ * Finance's persisted entities. Their names, tables, event prefixes, and
+ * fields are deployed data contracts: never rename them.
+ */
+
+import type { EntityDefinition } from '@hearthlog/sdk/entities';
+
+export const ENTITY_DEFINITIONS: EntityDefinition[] = [
+    {
+        name: "asset",
+        feature: "finance",
+        table: "assets",
+        fields: [
+            {
+                name: "name",
+                type: "string",
+                payloadKey: "name",
+                required: true,
+            },
+            {
+                name: "amount",
+                type: "number",
+                payloadKey: "amount",
+                required: true,
+            },
+            {
+                name: "asset_type",
+                type: "string",
+                payloadKey: "asset_type",
+                default: "asset",
+            },
+        ],
+        indexes: [{ name: "idx_assets_type", columns: ["asset_type"] }],
+    },
+    {
+        name: "transaction",
+        feature: "finance",
+        table: "transactions",
+        fields: [
+            { name: "name", type: "string", payloadKey: "name" },
+            {
+                name: "amount",
+                type: "number",
+                payloadKey: "amount",
+                required: true,
+            },
+            {
+                name: "due_date",
+                type: "datetime",
+                payloadKey: "due_date",
+                default: "datetime('now')",
+            },
+            {
+                name: "transaction_status",
+                type: "string",
+                payloadKey: "transaction_status",
+                default: "active",
+            },
+            {
+                name: "transaction_category",
+                type: "string",
+                payloadKey: "transaction_category",
+                default: "unknown",
+            },
+            // Where the category came from: `manual`, `history`, or `ai:<model>`.
+            // Empty for rows saved before provenance was kept.
+            {
+                name: "category_source",
+                type: "string",
+                payloadKey: "category_source",
+                default: "",
+                optionalInPayload: true,
+            },
+        ],
+        calendar: {
+            key: "tx-due",
+            dateField: "due_date",
+            titleField: "name",
+            subtitleField: "transaction_category",
+            label: "Transaction due",
+            presentation: { icon: "cash-clock", tone: "info", href: "/finance/{year}/{month}", rank: 30 },
+            group: { id: "transactions", label: "Transactions", icon: "cash-clock" },
+        },
+        indexes: [
+            {
+                name: "idx_transactions_scope_due_date",
+                columns: ["tenant_id", "log_id", "due_date"],
+            },
+            { name: "idx_transactions_due_date", columns: ["due_date"] },
+            {
+                name: "idx_transactions_status",
+                columns: ["transaction_status"],
+            },
+        ],
+    },
+    {
+        name: "budget_plan",
+        feature: "finance",
+        displayName: "Budget plan",
+        table: "budget_plans",
+        fields: [
+            { name: "name", type: "string", required: true },
+        ],
+        indexes: [
+            {
+                name: "idx_budget_plans_scope_created",
+                columns: ["tenant_id", "log_id", "created_at"],
+            },
+        ],
+    },
+    {
+        name: "budget_item",
+        feature: "finance",
+        displayName: "Budget item",
+        table: "budget_items",
+        fields: [
+            {
+                name: "plan_id",
+                type: "string",
+                payloadKey: "planId",
+                required: true,
+            },
+            { name: "name", type: "string", required: true },
+            { name: "amount", type: "number", required: true },
+            { name: "item_type", type: "string", payloadKey: "itemType", required: true },
+            { name: "category", type: "string", default: "other" },
+        ],
+        indexes: [
+            {
+                name: "idx_budget_items_scope_plan_type",
+                columns: ["tenant_id", "log_id", "plan_id", "item_type", "created_at"],
+            },
+        ],
+    },
+];