plasalid 0.4.1 → 0.5.0

package/dist/db/queries/transactions.js

@@ -0,0 +1,320 @@
+import { randomUUID } from "crypto";
+import { upsertMerchant } from "./merchants.js";
+const TOLERANCE = 0.005;
+/**
+ * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
+ * posting both debits and credits. Transaction-wrapped: postings never land
+ * without a header, header never lands without postings.
+ */
+export function recordTransaction(db, input) {
+    const validated = validateTransaction(input);
+    const tx = db.transaction(() => { insertTransactionRows(db, validated); });
+    tx();
+    return validated.id;
+}
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordTransaction` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export function validateTransaction(input) {
+    if (!input.postings || input.postings.length < 2) {
+        throw new Error("Transaction must contain at least two postings.");
+    }
+    let debitTotal = 0;
+    let creditTotal = 0;
+    for (const p of input.postings) {
+        const debit = p.debit ?? 0;
+        const credit = p.credit ?? 0;
+        if (debit < 0 || credit < 0) {
+            throw new Error("debit and credit values must be non-negative.");
+        }
+        if (debit > 0 && credit > 0) {
+            throw new Error("A single posting cannot debit and credit at the same time.");
+        }
+        if (debit === 0 && credit === 0) {
+            throw new Error("Each posting must have either a debit or a credit.");
+        }
+        debitTotal += debit;
+        creditTotal += credit;
+    }
+    if (Math.abs(debitTotal - creditTotal) > TOLERANCE) {
+        throw new Error(`Transaction does not balance: debits ${debitTotal.toFixed(2)} vs credits ${creditTotal.toFixed(2)}.`);
+    }
+    return { ...input, id: input.id ?? `tx:${randomUUID()}` };
+}
+/**
+ * Insert-only counterpart to `recordTransaction`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated input from `validateTransaction`.
+ */
+export function insertTransactionRows(db, input) {
+    let merchantId = input.merchant_id ?? null;
+    if (!merchantId && input.merchant) {
+        merchantId = upsertMerchant(db, input.merchant).id;
+    }
+    db.prepare(`INSERT INTO transactions (id, date, description, merchant_id, raw_descriptor, source_file_id, source_page)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.date, input.description, merchantId, input.raw_descriptor ?? null, input.source_file_id ?? null, input.source_page ?? null);
+    const insertPosting = db.prepare(`INSERT INTO postings (id, transaction_id, account_id, debit, credit, currency, memo, pii_flag)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const p of input.postings) {
+        insertPosting.run(`p:${randomUUID()}`, input.id, p.account_id, p.debit ?? 0, p.credit ?? 0, p.currency || "THB", p.memo ?? null, p.pii_flag ? 1 : 0);
+    }
+}
+export function updateTransaction(db, transactionId, fields) {
+    const sets = [];
+    const params = [];
+    if (fields.date !== undefined) {
+        sets.push("date = ?");
+        params.push(fields.date);
+    }
+    if (fields.description !== undefined) {
+        sets.push("description = ?");
+        params.push(fields.description);
+    }
+    if (fields.source_page !== undefined) {
+        sets.push("source_page = ?");
+        params.push(fields.source_page);
+    }
+    if (sets.length === 0)
+        return 0;
+    params.push(transactionId);
+    return db.prepare(`UPDATE transactions SET ${sets.join(", ")} WHERE id = ?`).run(...params).changes;
+}
+/**
+ * Safe single-posting edits only. Refuses changes to `debit`, `credit`, or `currency`
+ * because those would silently break the transaction's balance — to fix amounts the
+ * caller must delete the transaction and record a fresh one.
+ */
+export function updatePosting(db, postingId, fields) {
+    const sets = [];
+    const params = [];
+    if (fields.account_id !== undefined) {
+        sets.push("account_id = ?");
+        params.push(fields.account_id);
+    }
+    if (fields.memo !== undefined) {
+        sets.push("memo = ?");
+        params.push(fields.memo);
+    }
+    if (sets.length === 0)
+        return 0;
+    params.push(postingId);
+    return db.prepare(`UPDATE postings SET ${sets.join(", ")} WHERE id = ?`).run(...params).changes;
+}
+/**
+ * Delete a transaction. ON DELETE CASCADE on `postings.transaction_id` removes
+ * the postings automatically.
+ */
+export function deleteTransaction(db, transactionId) {
+    return db.prepare(`DELETE FROM transactions WHERE id = ?`).run(transactionId).changes;
+}
+/**
+ * Heuristic duplicate finder: group transactions by (rounded total debit) and check
+ * pairs whose date difference is ≤ toleranceDays. Returns groups with ≥2 members.
+ * Each transaction carries both account_ids (for follow-up tool calls) and
+ * account_names (for human-readable presentation to the user).
+ */
+export function findDuplicateTransactions(db, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 2));
+    const minAmount = opts.minAmount ?? 0;
+    const accountFilter = opts.accountId
+        ? `WHERE t.id IN (SELECT transaction_id FROM postings WHERE account_id = ?)`
+        : ``;
+    const params = opts.accountId ? [opts.accountId] : [];
+    const nameById = loadAccountNames(db);
+    const rows = db.prepare(`SELECT t.id, t.date, t.description,
+            COALESCE(SUM(p.debit), 0) AS amount,
+            GROUP_CONCAT(p.account_id) AS account_ids
+     FROM transactions t
+     LEFT JOIN postings p ON p.transaction_id = t.id
+     ${accountFilter}
+     GROUP BY t.id`).all(...params);
+    const candidates = rows
+        .filter(r => r.amount >= minAmount)
+        .map(r => {
+        const ids = (r.account_ids ?? "").split(",").filter(Boolean);
+        return {
+            id: r.id,
+            date: r.date,
+            description: r.description,
+            amount: Math.round(r.amount * 100) / 100,
+            account_ids: ids,
+            account_names: ids.map(id => nameById.get(id) ?? id),
+        };
+    });
+    const byAmount = new Map();
+    for (const e of candidates) {
+        const key = Math.round(e.amount * 100);
+        const arr = byAmount.get(key) ?? [];
+        arr.push(e);
+        byAmount.set(key, arr);
+    }
+    const groups = [];
+    for (const arr of byAmount.values()) {
+        if (arr.length < 2)
+            continue;
+        arr.sort((a, b) => a.date.localeCompare(b.date));
+        let current = [];
+        for (const e of arr) {
+            if (current.length === 0) {
+                current.push(e);
+                continue;
+            }
+            const last = current[current.length - 1];
+            if (dayDiff(last.date, e.date) <= toleranceDays) {
+                current.push(e);
+            }
+            else {
+                if (current.length >= 2)
+                    groups.push(current);
+                current = [e];
+            }
+        }
+        if (current.length >= 2)
+            groups.push(current);
+    }
+    return groups;
+}
+export function dayDiff(a, b) {
+    const aDate = Date.parse(a);
+    const bDate = Date.parse(b);
+    if (Number.isNaN(aDate) || Number.isNaN(bDate))
+        return Number.POSITIVE_INFINITY;
+    return Math.abs(Math.round((bDate - aDate) / 86_400_000));
+}
+/**
+ * Load all account id → name pairs into an in-memory map. Cheap on the small
+ * charts of accounts Plasalid deals with, and avoids GROUP_CONCAT join hacks
+ * (account names can contain commas which break a comma-separated concat, and
+ * SQLite's GROUP_CONCAT has no robust escape mechanism).
+ */
+function loadAccountNames(db) {
+    const map = new Map();
+    for (const row of db.prepare(`SELECT id, name FROM accounts`).all()) {
+        map.set(row.id, row.name);
+    }
+    return map;
+}
+/**
+ * Heuristic: surface pairs of transactions that look like the same money movement
+ * recorded against different accounts (e.g. a bank-to-card transfer that lands
+ * once on the bank statement and again on the card statement). Filters out
+ * pairs whose account-id sets overlap (those are duplicates, not correlations).
+ */
+export function findCorrelatedTransactions(db, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
+    const minAmount = opts.minAmount ?? 0;
+    const dateFilter = [];
+    const params = [];
+    if (opts.from) {
+        dateFilter.push("t.date >= ?");
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        dateFilter.push("t.date <= ?");
+        params.push(opts.to);
+    }
+    const where = dateFilter.length ? `WHERE ${dateFilter.join(" AND ")}` : "";
+    const nameById = loadAccountNames(db);
+    const rows = db.prepare(`SELECT t.id, t.date, t.description,
+            COALESCE(SUM(p.debit), 0) AS amount,
+            COALESCE(MAX(p.currency), 'THB') AS currency,
+            GROUP_CONCAT(p.account_id) AS account_ids
+     FROM transactions t
+     LEFT JOIN postings p ON p.transaction_id = t.id
+     ${where}
+     GROUP BY t.id`).all(...params);
+    const candidates = rows
+        .filter(r => r.amount >= minAmount)
+        .map(r => {
+        const ids = (r.account_ids ?? "").split(",").filter(Boolean);
+        return {
+            id: r.id,
+            date: r.date,
+            description: r.description,
+            amount: Math.round(r.amount * 100) / 100,
+            currency: r.currency || "THB",
+            account_ids: ids,
+            account_names: ids.map(id => nameById.get(id) ?? id),
+        };
+    });
+    return correlatePairs(candidates, { toleranceDays });
+}
+/**
+ * Pure pair-finder: given an array of candidates already filtered by amount
+ * and equipped with account_ids/names, return the cross-pairs that look like
+ * the same money movement on different accounts (date within toleranceDays,
+ * same amount + currency, non-overlapping account sets).
+ *
+ * Used by the DB-backed `findCorrelatedTransactions` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed transactions.
+ */
+export function correlatePairs(candidates, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
+    const buckets = new Map();
+    for (const e of candidates) {
+        const key = `${Math.round(e.amount * 100)}|${e.currency}`;
+        const arr = buckets.get(key) ?? [];
+        arr.push(e);
+        buckets.set(key, arr);
+    }
+    const pairs = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.length < 2)
+            continue;
+        bucket.sort((x, y) => x.date.localeCompare(y.date));
+        for (let i = 0; i < bucket.length; i++) {
+            for (let j = i + 1; j < bucket.length; j++) {
+                const a = bucket[i], b = bucket[j];
+                const gap = dayDiff(a.date, b.date);
+                if (gap > toleranceDays)
+                    break;
+                const overlap = a.account_ids.some(id => b.account_ids.includes(id));
+                if (overlap)
+                    continue;
+                pairs.push({
+                    amount: a.amount,
+                    currency: a.currency,
+                    day_gap: gap,
+                    a: { id: a.id, date: a.date, description: a.description, account_ids: a.account_ids, account_names: a.account_names },
+                    b: { id: b.id, date: b.date, description: b.description, account_ids: b.account_ids, account_names: b.account_names },
+                });
+            }
+        }
+    }
+    return pairs;
+}
+export function listPostings(db, opts = {}) {
+    const conditions = [];
+    const params = [];
+    if (opts.account_id) {
+        conditions.push("p.account_id = ?");
+        params.push(opts.account_id);
+    }
+    if (opts.from) {
+        conditions.push("t.date >= ?");
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        conditions.push("t.date <= ?");
+        params.push(opts.to);
+    }
+    if (opts.q) {
+        conditions.push("(t.description LIKE ? OR p.memo LIKE ? OR m.canonical_name LIKE ?)");
+        params.push(`%${opts.q}%`, `%${opts.q}%`, `%${opts.q}%`);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+    return db.prepare(`SELECT p.id, p.transaction_id, p.account_id, p.debit, p.credit, p.currency, p.memo,
+            a.name AS account_name, a.type AS account_type,
+            t.date AS transaction_date, t.description AS transaction_description,
+            m.canonical_name AS merchant_name
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     LEFT JOIN merchants m ON m.id = t.merchant_id
+     ${where}
+     ORDER BY t.date DESC, t.id DESC
+     LIMIT ?`).all(...params, limit);
+}

package/dist/db/schema.js

@@ -4,6 +4,7 @@ export function migrate(db) {
       id TEXT PRIMARY KEY,
       name TEXT NOT NULL,
       type TEXT NOT NULL CHECK(type IN ('asset','liability','income','expense','equity')),
+      parent_id TEXT REFERENCES accounts(id),
       subtype TEXT,
       bank_name TEXT,
       account_number_masked TEXT,
@@ -17,6 +18,25 @@ export function migrate(db) {
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE INDEX IF NOT EXISTS accounts_parent_idx ON accounts(parent_id);
+    CREATE INDEX IF NOT EXISTS accounts_type_idx ON accounts(type);
+
+    CREATE TABLE IF NOT EXISTS merchants (
+      id TEXT PRIMARY KEY,
+      canonical_name TEXT NOT NULL UNIQUE,
+      default_account_id TEXT REFERENCES accounts(id),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS merchant_aliases (
+      id TEXT PRIMARY KEY,
+      merchant_id TEXT NOT NULL REFERENCES merchants(id) ON DELETE CASCADE,
+      normalized_pattern TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS merchant_aliases_merchant_idx ON merchant_aliases(merchant_id);
+
     CREATE TABLE IF NOT EXISTS scanned_files (
       id TEXT PRIMARY KEY,
       path TEXT NOT NULL,
@@ -45,10 +65,12 @@ export function migrate(db) {
 
     CREATE INDEX IF NOT EXISTS recurrences_account_idx ON recurrences(account_id);
 
-    CREATE TABLE IF NOT EXISTS journal_entries (
+    CREATE TABLE IF NOT EXISTS transactions (
       id TEXT PRIMARY KEY,
       date TEXT NOT NULL,
       description TEXT NOT NULL,
+      merchant_id TEXT REFERENCES merchants(id),
+      raw_descriptor TEXT,
       source_file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
       source_page INTEGER,
       recurrence_id TEXT REFERENCES recurrences(id) ON DELETE SET NULL,
@@ -56,11 +78,14 @@ export function migrate(db) {
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
-    CREATE INDEX IF NOT EXISTS journal_entries_recurrence_idx ON journal_entries(recurrence_id);
+    CREATE INDEX IF NOT EXISTS transactions_recurrence_idx ON transactions(recurrence_id);
+    CREATE INDEX IF NOT EXISTS transactions_source_file_idx ON transactions(source_file_id);
+    CREATE INDEX IF NOT EXISTS transactions_date_idx ON transactions(date);
+    CREATE INDEX IF NOT EXISTS transactions_merchant_idx ON transactions(merchant_id);
 
-    CREATE TABLE IF NOT EXISTS journal_lines (
+    CREATE TABLE IF NOT EXISTS postings (
       id TEXT PRIMARY KEY,
-      entry_id TEXT NOT NULL REFERENCES journal_entries(id) ON DELETE CASCADE,
+      transaction_id TEXT NOT NULL REFERENCES transactions(id) ON DELETE CASCADE,
       account_id TEXT NOT NULL REFERENCES accounts(id),
       debit REAL NOT NULL DEFAULT 0,
       credit REAL NOT NULL DEFAULT 0,
@@ -70,16 +95,15 @@ export function migrate(db) {
       CHECK (debit >= 0 AND credit >= 0 AND (debit = 0 OR credit = 0))
     );
 
-    CREATE INDEX IF NOT EXISTS journal_lines_entry_idx ON journal_lines(entry_id);
-    CREATE INDEX IF NOT EXISTS journal_lines_account_idx ON journal_lines(account_id);
-    CREATE INDEX IF NOT EXISTS journal_entries_source_file_idx ON journal_entries(source_file_id);
-    CREATE INDEX IF NOT EXISTS journal_entries_date_idx ON journal_entries(date);
+    CREATE INDEX IF NOT EXISTS postings_transaction_idx ON postings(transaction_id);
+    CREATE INDEX IF NOT EXISTS postings_account_idx ON postings(account_id);
 
     CREATE TABLE IF NOT EXISTS concerns (
       id TEXT PRIMARY KEY,
       file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
-      entry_id TEXT REFERENCES journal_entries(id) ON DELETE CASCADE,
+      transaction_id TEXT REFERENCES transactions(id) ON DELETE CASCADE,
       account_id TEXT REFERENCES accounts(id) ON DELETE CASCADE,
+      kind TEXT,
       prompt TEXT NOT NULL,
       options_json TEXT,
       answer TEXT,
@@ -114,5 +138,23 @@ export function migrate(db) {
       use_count INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
+
+    CREATE TABLE IF NOT EXISTS action_log (
+      id TEXT PRIMARY KEY,
+      correlation_id TEXT NOT NULL,
+      command TEXT NOT NULL,
+      user_input TEXT,
+      action_type TEXT NOT NULL CHECK(action_type IN (
+        'create_account','update_account_metadata','record_transaction','adjust_balance',
+        'create_merchant','update_merchant_default'
+      )),
+      target_id TEXT NOT NULL,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      reverted_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS action_log_correlation_idx ON action_log(correlation_id);
+    CREATE INDEX IF NOT EXISTS action_log_created_idx ON action_log(created_at);
   `);
 }

package/dist/reviewer/pipeline.d.ts

@@ -10,9 +10,9 @@ export interface ReviewSummary {
     dryRun: boolean;
 }
 /**
- * Walk the existing journal with the review-profile agent: surface open
- * concerns, detect correlated transactions and recurrences, propose fixes,
- * apply them (or print "would do X" stubs when dryRun is on) after the user
- * confirms one step at a time.
+ * Walk the existing ledger with the review-profile agent: surface open
+ * concerns (uncategorized cleanup first), detect correlated transactions and
+ * recurrences, propose fixes, apply them (or print "would do X" stubs when
+ * dryRun is on) after the user confirms one step at a time.
  */
 export declare function runReview(opts?: ReviewOptions): Promise<ReviewSummary>;

package/dist/reviewer/pipeline.js

@@ -3,10 +3,10 @@ import { runReviewAgent } from "../ai/agent.js";
 import { statusSpinner, makePromptUser, makeAgentOnProgress, } from "../cli/ux.js";
 import { buildReviewUserMessage } from "./prompts.js";
 /**
- * Walk the existing journal with the review-profile agent: surface open
- * concerns, detect correlated transactions and recurrences, propose fixes,
- * apply them (or print "would do X" stubs when dryRun is on) after the user
- * confirms one step at a time.
+ * Walk the existing ledger with the review-profile agent: surface open
+ * concerns (uncategorized cleanup first), detect correlated transactions and
+ * recurrences, propose fixes, apply them (or print "would do X" stubs when
+ * dryRun is on) after the user confirms one step at a time.
  */
 export async function runReview(opts = {}) {
     const db = getDb();

package/dist/reviewer/prompts.js

@@ -5,7 +5,7 @@
  */
 export function buildReviewUserMessage(scope) {
     return [
-        `Review the local Plasalid journal.`,
+        `Review the local Plasalid ledger.`,
         ``,
         `Scope:`,
         `- account: ${scope.accountId ?? "all"}`,
@@ -14,9 +14,9 @@ export function buildReviewUserMessage(scope) {
         `- dry run: ${scope.dryRun ? "yes — write tools are no-ops" : "no — writes commit after confirmation"}`,
         ``,
         `Steps:`,
-        `1. Survey first: list_accounts, get_net_worth, count open concerns, then find_duplicate_entries, find_similar_accounts, find_unused_accounts, find_correlated_entries, find_recurrences. Hold the candidate list internally.`,
-        `2. Prioritize open concerns, then correlated transactions, then recurrences, then chart-of-accounts hygiene.`,
-        `3. Ask one focused question at a time via ask_user. After each answer, apply the change and re-survey only if the change invalidated other candidates.`,
+        `1. Survey first: list_accounts, get_net_worth, count open concerns (especially kind='uncategorized_expense'), then find_duplicate_transactions, find_similar_accounts, find_unused_accounts, find_correlated_transactions, find_recurrences. Hold the candidate list internally.`,
+        `2. Prioritize: (a) uncategorized expense cleanup — these are postings parked in expense:uncategorized awaiting a real category; resolving one should also call set_merchant_default_account when the transaction has a merchant, so future statements skip the categorizer. (b) other open concerns. (c) correlated transactions. (d) recurrences. (e) chart-of-accounts hygiene.`,
+        `3. Ask one focused question at a time via ask_user. Group sibling concerns (same merchant, same answer) via related_concern_ids so the user answers once. After each answer, apply the change and re-survey only if the change invalidated other candidates.`,
         `4. Loop until no open concerns remain (or the user keeps choosing "Skip — leave as is"). Then call mark_review_done with a short summary of what was applied, recorded, and skipped.`,
     ].join("\n");
 }

package/dist/scanner/buffer.d.ts

@@ -1,48 +1,51 @@
 import type Database from "libsql";
-import { type JournalEntryInput } from "../db/queries/journal.js";
+import { type TransactionInput } from "../db/queries/transactions.js";
 /**
- * One scan agent's pending writes. Journal entries and concerns accumulate
- * here while the LLM works; nothing hits the DB until `commit()` runs inside
- * a single SQLite transaction. If `commit()` throws, the transaction rolls
- * back and the DB stays exactly as it was before this file's scan began.
+ * One scan agent's pending writes. Transactions and concerns accumulate here
+ * while the LLM works; nothing hits the DB until `commit()` runs inside a
+ * single SQLite transaction. If `commit()` throws, the transaction rolls back
+ * and the DB stays exactly as it was before this file's scan began.
  *
- * Account writes (`create_account`, `update_account_metadata`) deliberately
- * bypass the buffer — they go directly to the DB through `account_mutex` so
- * concurrent agents see each other's account creations and don't duplicate.
+ * Account writes (`create_account`, `update_account_metadata`) and merchant
+ * writes deliberately bypass the buffer — they go directly to the DB through
+ * their own mutexes so concurrent agents see each other's creates and don't
+ * duplicate.
  */
 export interface BufferedConcern {
-    /** Synthesized when the LLM called note_concern with a buffered entry_id. */
-    entry_id: string | null;
+    /** Synthesized when the LLM called note_concern with a buffered transaction_id. */
+    transaction_id: string | null;
     account_id: string | null;
+    kind?: string | null;
     prompt: string;
     options?: string[];
 }
-export interface BufferedEntry {
-    /** Synthesized at queue-time so concerns can reference this entry. */
-    entry_id: string;
-    input: JournalEntryInput;
+export interface BufferedTransaction {
+    /** Synthesized at queue-time so concerns can reference this transaction. */
+    transaction_id: string;
+    input: TransactionInput;
 }
 export declare class BufferedWriteContext {
     readonly fileName: string;
-    readonly journalEntries: BufferedEntry[];
+    readonly transactions: BufferedTransaction[];
     readonly concerns: BufferedConcern[];
     doneSummary: string | null;
     constructor(fileName: string);
     /**
-     * Queue a journal entry. Returns the synthesized entry id so the agent can
-     * use it in subsequent note_concern calls inside the same file.
+     * Queue a transaction. Returns the synthesized transaction id so the agent
+     * can use it in subsequent note_concern calls inside the same file.
      */
-    appendEntry(input: JournalEntryInput): string;
+    appendTransaction(input: TransactionInput): string;
     appendConcern(concern: BufferedConcern): void;
     markDone(summary: string): void;
     get isDone(): boolean;
     /**
      * Replay all buffered writes inside one DB transaction. `scannedFileId` is
-     * stamped onto every entry and concern so they're attributable to this file.
-     * Returns `{ entries, concerns }` counts so the caller can report them.
+     * stamped onto every transaction and concern so they're attributable to this
+     * file. Returns `{ transactions, concerns }` counts so the caller can report
+     * them.
      */
     commit(db: Database.Database, scannedFileId: string): {
-        entries: number;
+        transactions: number;
         concerns: number;
     };
 }

package/dist/scanner/buffer.js

@@ -1,22 +1,22 @@
 import { randomUUID } from "crypto";
-import { insertJournalEntryRows, validateJournalEntry, } from "../db/queries/journal.js";
+import { insertTransactionRows, validateTransaction, } from "../db/queries/transactions.js";
 import { recordConcern } from "../db/queries/concerns.js";
 export class BufferedWriteContext {
     fileName;
-    journalEntries = [];
+    transactions = [];
     concerns = [];
     doneSummary = null;
     constructor(fileName) {
         this.fileName = fileName;
     }
     /**
-     * Queue a journal entry. Returns the synthesized entry id so the agent can
-     * use it in subsequent note_concern calls inside the same file.
+     * Queue a transaction. Returns the synthesized transaction id so the agent
+     * can use it in subsequent note_concern calls inside the same file.
      */
-    appendEntry(input) {
-        const entryId = `je:${randomUUID()}`;
-        this.journalEntries.push({ entry_id: entryId, input });
-        return entryId;
+    appendTransaction(input) {
+        const transactionId = `tx:${randomUUID()}`;
+        this.transactions.push({ transaction_id: transactionId, input });
+        return transactionId;
     }
     appendConcern(concern) {
         this.concerns.push(concern);
@@ -29,35 +29,35 @@ export class BufferedWriteContext {
     }
     /**
      * Replay all buffered writes inside one DB transaction. `scannedFileId` is
-     * stamped onto every entry and concern so they're attributable to this file.
-     * Returns `{ entries, concerns }` counts so the caller can report them.
+     * stamped onto every transaction and concern so they're attributable to this
+     * file. Returns `{ transactions, concerns }` counts so the caller can report
+     * them.
      */
     commit(db, scannedFileId) {
-        // Validate all entries up-front so a balance error throws before we open
-        // the transaction (clean failure with no partial state to roll back).
-        const validated = this.journalEntries.map(b => ({
+        const validated = this.transactions.map(b => ({
             buffered: b,
-            validated: validateJournalEntry({
+            validated: validateTransaction({
                 ...b.input,
-                id: b.entry_id,
+                id: b.transaction_id,
                 source_file_id: scannedFileId,
             }),
         }));
         const tx = db.transaction(() => {
             for (const { validated: v } of validated) {
-                insertJournalEntryRows(db, v);
+                insertTransactionRows(db, v);
             }
             for (const c of this.concerns) {
                 recordConcern(db, {
                     file_id: scannedFileId,
-                    entry_id: c.entry_id,
+                    transaction_id: c.transaction_id,
                     account_id: c.account_id,
+                    kind: c.kind ?? null,
                     prompt: c.prompt,
                     options: c.options,
                 });
             }
         });
         tx();
-        return { entries: this.journalEntries.length, concerns: this.concerns.length };
+        return { transactions: this.transactions.length, concerns: this.concerns.length };
     }
 }

package/dist/scanner/pipeline.d.ts

@@ -3,7 +3,7 @@ export interface ScanFileResult {
     name: string;
     relPath: string;
     status: ScanFileStatus;
-    entries: number;
+    transactions: number;
     concerns: number;
     error?: string;
 }
@@ -40,7 +40,7 @@ export interface ScanRunEvents {
     scanEnd?: (e: {
         fileName: string;
         status: "scanned" | "failed";
-        entries: number;
+        transactions: number;
         concerns: number;
         error?: string;
     }) => void;
@@ -57,4 +57,5 @@ export interface RunScanOptions {
     events?: ScanRunEvents;
 }
 export declare function compileMatcher(input: string): RegExp;
+/** Orchestration */
 export declare function runScan(opts?: RunScanOptions): Promise<ScanSummary>;