plasalid 0.3.4 → 0.4.1

package/dist/db/queries/journal.js

@@ -6,6 +6,17 @@ const TOLERANCE = 0.005;
  * a header, header never lands without lines.
  */
 export function recordJournalEntry(db, entry) {
+    const validated = validateJournalEntry(entry);
+    const tx = db.transaction(() => { insertJournalEntryRows(db, validated); });
+    tx();
+    return validated.id;
+}
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordJournalEntry` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export function validateJournalEntry(entry) {
     if (!entry.lines || entry.lines.length < 2) {
         throw new Error("Journal entry must contain at least two lines.");
     }
@@ -29,19 +40,21 @@ export function recordJournalEntry(db, entry) {
     if (Math.abs(debitTotal - creditTotal) > TOLERANCE) {
         throw new Error(`Journal entry does not balance: debits ${debitTotal.toFixed(2)} vs credits ${creditTotal.toFixed(2)}.`);
     }
-    const entryId = `je:${randomUUID()}`;
-    const insertHeader = db.prepare(`INSERT INTO journal_entries (id, date, description, source_file_id, source_page)
-     VALUES (?, ?, ?, ?, ?)`);
+    return { ...entry, id: entry.id ?? `je:${randomUUID()}` };
+}
+/**
+ * Insert-only counterpart to `recordJournalEntry`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated entry from `validateJournalEntry`.
+ */
+export function insertJournalEntryRows(db, entry) {
+    db.prepare(`INSERT INTO journal_entries (id, date, description, source_file_id, source_page)
+     VALUES (?, ?, ?, ?, ?)`).run(entry.id, entry.date, entry.description, entry.source_file_id ?? null, entry.source_page ?? null);
     const insertLine = db.prepare(`INSERT INTO journal_lines (id, entry_id, account_id, debit, credit, currency, memo, pii_flag)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
-    const tx = db.transaction(() => {
-        insertHeader.run(entryId, entry.date, entry.description, entry.source_file_id ?? null, entry.source_page ?? null);
-        for (const line of entry.lines) {
-            insertLine.run(`jl:${randomUUID()}`, entryId, line.account_id, line.debit ?? 0, line.credit ?? 0, line.currency || "THB", line.memo ?? null, line.pii_flag ? 1 : 0);
-        }
-    });
-    tx();
-    return entryId;
+    for (const line of entry.lines) {
+        insertLine.run(`jl:${randomUUID()}`, entry.id, line.account_id, line.debit ?? 0, line.credit ?? 0, line.currency || "THB", line.memo ?? null, line.pii_flag ? 1 : 0);
+    }
 }
 export function updateJournalEntry(db, entryId, fields) {
     const sets = [];
@@ -104,13 +117,7 @@ export function findDuplicateEntries(db, opts = {}) {
         ? `WHERE je.id IN (SELECT entry_id FROM journal_lines WHERE account_id = ?)`
         : ``;
     const params = opts.accountId ? [opts.accountId] : [];
-    // Small chart of accounts → a single name lookup beats 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).
-    const nameById = new Map();
-    for (const row of db.prepare(`SELECT id, name FROM accounts`).all()) {
-        nameById.set(row.id, row.name);
-    }
+    const nameById = loadAccountNames(db);
     const rows = db.prepare(`SELECT je.id, je.date, je.description,
             COALESCE(SUM(jl.debit), 0) AS amount,
             GROUP_CONCAT(jl.account_id) AS account_ids
@@ -164,13 +171,118 @@ export function findDuplicateEntries(db, opts = {}) {
     }
     return groups;
 }
-function dayDiff(a, b) {
+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 entries 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 findCorrelatedEntries(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("je.date >= ?");
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        dateFilter.push("je.date <= ?");
+        params.push(opts.to);
+    }
+    const where = dateFilter.length ? `WHERE ${dateFilter.join(" AND ")}` : "";
+    const nameById = loadAccountNames(db);
+    const rows = db.prepare(`SELECT je.id, je.date, je.description,
+            COALESCE(SUM(jl.debit), 0) AS amount,
+            COALESCE(MAX(jl.currency), 'THB') AS currency,
+            GROUP_CONCAT(jl.account_id) AS account_ids
+     FROM journal_entries je
+     LEFT JOIN journal_lines jl ON jl.entry_id = je.id
+     ${where}
+     GROUP BY je.id`).all(...params);
+    const entries = 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(entries, { 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 `findCorrelatedEntries` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed entries.
+ */
+export function correlatePairs(entries, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
+    // Bucket by (amount-cents, currency) so we only compare entries that could
+    // plausibly pair. O(n) bucketing + O(k²) per bucket dominates only when many
+    // entries share the same amount.
+    const buckets = new Map();
+    for (const e of entries) {
+        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; // bucket is sorted by date
+                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 listJournalLines(db, opts = {}) {
     const conditions = [];
     const params = [];

package/dist/db/queries/recurrences.d.ts

@@ -0,0 +1,33 @@
+import type Database from "libsql";
+export type RecurrenceFrequency = "weekly" | "biweekly" | "monthly" | "annually";
+export interface RecurrenceCandidate {
+    account_id: string;
+    account_name: string;
+    amount: number;
+    currency: string;
+    side: "debit" | "credit";
+    entries: {
+        id: string;
+        date: string;
+        description: string;
+    }[];
+    median_days_between: number;
+    implied_frequency: RecurrenceFrequency | "irregular";
+}
+export interface FindRecurrencesOptions {
+    accountId?: string;
+    /** Minimum sightings to qualify. Default 3. */
+    minOccurrences?: number;
+}
+export declare function findRecurrenceCandidates(db: Database.Database, opts?: FindRecurrencesOptions): RecurrenceCandidate[];
+export interface RecordRecurrenceInput {
+    account_id: string;
+    description: string;
+    frequency: RecurrenceFrequency;
+    amount_typical?: number | null;
+    currency?: string;
+    entry_ids: string[];
+    notes?: string | null;
+}
+export declare function recordRecurrence(db: Database.Database, input: RecordRecurrenceInput): string;
+export declare function linkEntryToRecurrence(db: Database.Database, entryId: string, recurrenceId: string): void;

package/dist/db/queries/recurrences.js

@@ -0,0 +1,130 @@
+import { randomUUID } from "crypto";
+import { dayDiff } from "./journal.js";
+export function findRecurrenceCandidates(db, opts = {}) {
+    const minOccurrences = Math.max(2, opts.minOccurrences ?? 3);
+    const accountFilter = opts.accountId ? `AND jl.account_id = ?` : ``;
+    const params = opts.accountId ? [opts.accountId] : [];
+    const rows = db.prepare(`SELECT jl.account_id,
+            a.name AS account_name,
+            jl.currency,
+            CASE WHEN jl.debit > 0 THEN jl.debit ELSE jl.credit END AS amount,
+            CASE WHEN jl.debit > 0 THEN 'debit' ELSE 'credit' END AS side,
+            je.id AS entry_id,
+            je.date,
+            je.description
+     FROM journal_lines jl
+     JOIN journal_entries je ON je.id = jl.entry_id
+     JOIN accounts a ON a.id = jl.account_id
+     WHERE je.recurrence_id IS NULL
+       AND (jl.debit > 0 OR jl.credit > 0)
+       ${accountFilter}
+     ORDER BY jl.account_id, jl.currency, amount, je.date`).all(...params);
+    const buckets = new Map();
+    for (const r of rows) {
+        const key = `${r.account_id}|${r.currency}|${Math.round(r.amount * 100)}|${r.side}`;
+        const arr = buckets.get(key) ?? [];
+        arr.push(r);
+        buckets.set(key, arr);
+    }
+    const candidates = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.length < minOccurrences)
+            continue;
+        const dates = bucket.map(r => r.date);
+        const diffs = [];
+        for (let i = 1; i < dates.length; i++) {
+            diffs.push(dayDiff(dates[i - 1], dates[i]));
+        }
+        const median = medianOf(diffs);
+        candidates.push({
+            account_id: bucket[0].account_id,
+            account_name: bucket[0].account_name,
+            amount: Math.round(bucket[0].amount * 100) / 100,
+            currency: bucket[0].currency,
+            side: bucket[0].side,
+            entries: bucket.map(r => ({ id: r.entry_id, date: r.date, description: r.description })),
+            median_days_between: median,
+            implied_frequency: classifyFrequency(median),
+        });
+    }
+    return candidates;
+}
+function medianOf(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function classifyFrequency(medianDays) {
+    if (medianDays >= 6 && medianDays <= 8)
+        return "weekly";
+    if (medianDays >= 13 && medianDays <= 15)
+        return "biweekly";
+    if (medianDays >= 27 && medianDays <= 32)
+        return "monthly";
+    if (medianDays >= 360 && medianDays <= 370)
+        return "annually";
+    return "irregular";
+}
+const FREQ_PERIOD_DAYS = {
+    weekly: 7,
+    biweekly: 14,
+    monthly: 30,
+    annually: 365,
+};
+export function recordRecurrence(db, input) {
+    if (!input.entry_ids || input.entry_ids.length === 0) {
+        throw new Error("recordRecurrence requires at least one entry_id.");
+    }
+    const placeholders = input.entry_ids.map(() => "?").join(",");
+    const dateRows = db.prepare(`SELECT date FROM journal_entries WHERE id IN (${placeholders}) ORDER BY date ASC`).all(...input.entry_ids);
+    if (dateRows.length === 0) {
+        throw new Error("None of the supplied entry_ids exist.");
+    }
+    const firstSeen = dateRows[0].date;
+    const lastSeen = dateRows[dateRows.length - 1].date;
+    const nextExpected = addDays(lastSeen, FREQ_PERIOD_DAYS[input.frequency]);
+    const id = `rc:${randomUUID()}`;
+    const tx = db.transaction(() => {
+        db.prepare(`INSERT INTO recurrences
+         (id, account_id, description, frequency, amount_typical, currency,
+          first_seen_date, last_seen_date, next_expected_date, notes)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.account_id, input.description, input.frequency, input.amount_typical ?? null, input.currency || "THB", firstSeen, lastSeen, nextExpected, input.notes ?? null);
+        const updateEntry = db.prepare(`UPDATE journal_entries SET recurrence_id = ? WHERE id = ?`);
+        for (const entryId of input.entry_ids)
+            updateEntry.run(id, entryId);
+    });
+    tx();
+    return id;
+}
+export function linkEntryToRecurrence(db, entryId, recurrenceId) {
+    const recurrence = db
+        .prepare(`SELECT frequency FROM recurrences WHERE id = ?`)
+        .get(recurrenceId);
+    if (!recurrence)
+        throw new Error(`Recurrence ${recurrenceId} not found.`);
+    const entry = db
+        .prepare(`SELECT date FROM journal_entries WHERE id = ?`)
+        .get(entryId);
+    if (!entry)
+        throw new Error(`Entry ${entryId} not found.`);
+    const tx = db.transaction(() => {
+        db.prepare(`UPDATE journal_entries SET recurrence_id = ? WHERE id = ?`).run(recurrenceId, entryId);
+        // Recompute first/last/next from the full member set so the recurrence
+        // metadata stays in sync after every attach.
+        const span = db
+            .prepare(`SELECT MIN(date) AS first, MAX(date) AS last FROM journal_entries WHERE recurrence_id = ?`)
+            .get(recurrenceId);
+        const nextExpected = addDays(span.last, FREQ_PERIOD_DAYS[recurrence.frequency]);
+        db.prepare(`UPDATE recurrences SET first_seen_date = ?, last_seen_date = ?, next_expected_date = ? WHERE id = ?`).run(span.first, span.last, nextExpected, recurrenceId);
+    });
+    tx();
+}
+function addDays(dateIso, days) {
+    const t = Date.parse(dateIso);
+    if (Number.isNaN(t))
+        return dateIso;
+    const next = new Date(t + days * 86_400_000);
+    return next.toISOString().slice(0, 10);
+}

package/dist/db/schema.js

@@ -13,6 +13,7 @@ export function migrate(db) {
       points_balance REAL,
       metadata_json TEXT,
       pii_flag INTEGER NOT NULL DEFAULT 0,
+      has_concern INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
@@ -21,22 +22,42 @@ export function migrate(db) {
       path TEXT NOT NULL,
       file_hash TEXT NOT NULL UNIQUE,
       mime TEXT NOT NULL,
-      status TEXT NOT NULL CHECK(status IN ('pending','scanned','needs_input','failed')),
+      status TEXT NOT NULL CHECK(status IN ('pending','scanned','failed')),
       raw_text TEXT,
       scanned_at TEXT,
       error TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE TABLE IF NOT EXISTS recurrences (
+      id TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+      description TEXT NOT NULL,
+      frequency TEXT NOT NULL CHECK(frequency IN ('weekly','biweekly','monthly','annually')),
+      amount_typical REAL,
+      currency TEXT NOT NULL DEFAULT 'THB',
+      first_seen_date TEXT,
+      last_seen_date TEXT,
+      next_expected_date TEXT,
+      notes TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS recurrences_account_idx ON recurrences(account_id);
+
     CREATE TABLE IF NOT EXISTS journal_entries (
       id TEXT PRIMARY KEY,
       date TEXT NOT NULL,
       description TEXT NOT NULL,
       source_file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
       source_page INTEGER,
+      recurrence_id TEXT REFERENCES recurrences(id) ON DELETE SET NULL,
+      has_concern INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE INDEX IF NOT EXISTS journal_entries_recurrence_idx ON journal_entries(recurrence_id);
+
     CREATE TABLE IF NOT EXISTS journal_lines (
       id TEXT PRIMARY KEY,
       entry_id TEXT NOT NULL REFERENCES journal_entries(id) ON DELETE CASCADE,
@@ -54,9 +75,11 @@ export function migrate(db) {
     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 TABLE IF NOT EXISTS pending_questions (
+    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,
+      account_id TEXT REFERENCES accounts(id) ON DELETE CASCADE,
       prompt TEXT NOT NULL,
       options_json TEXT,
       answer TEXT,

package/dist/reviewer/pipeline.d.ts

@@ -0,0 +1,18 @@
+export interface ReviewOptions {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun?: boolean;
+    interactive?: boolean;
+}
+export interface ReviewSummary {
+    summary: string;
+    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.
+ */
+export declare function runReview(opts?: ReviewOptions): Promise<ReviewSummary>;

package/dist/reviewer/pipeline.js

@@ -0,0 +1,46 @@
+import { getDb } from "../db/connection.js";
+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.
+ */
+export async function runReview(opts = {}) {
+    const db = getDb();
+    const interactive = opts.interactive ?? true;
+    const dryRun = !!opts.dryRun;
+    const scope = {
+        accountId: opts.accountId,
+        from: opts.from,
+        to: opts.to,
+        dryRun,
+    };
+    const spinner = statusSpinner(`Reviewing${dryRun ? " (dry-run)" : ""}...`);
+    const promptUser = interactive ? makePromptUser(spinner) : undefined;
+    let summary = "";
+    try {
+        await runReviewAgent({
+            db,
+            prompt: scope,
+            initialMessages: [
+                { role: "user", content: buildReviewUserMessage(scope) },
+            ],
+            agentCtx: {
+                interactive,
+                dryRun,
+                promptUser,
+                onComplete: (s) => { summary = s; },
+            },
+            onProgress: makeAgentOnProgress(spinner),
+        });
+        spinner.succeed(dryRun ? "Review complete (dry-run — no writes)." : "Review complete.");
+    }
+    catch (err) {
+        spinner.fail(`Review failed: ${err.message}`);
+        throw err;
+    }
+    return { summary, dryRun };
+}

package/dist/reviewer/prompts.d.ts

@@ -0,0 +1,12 @@
+export interface ReviewScope {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun: boolean;
+}
+/**
+ * Kickoff message the review agent receives. The persona + chart-of-accounts
+ * snapshot live in the system prompt (`buildReviewSystemPrompt`); this is
+ * the per-session instruction.
+ */
+export declare function buildReviewUserMessage(scope: ReviewScope): string;

package/dist/reviewer/prompts.js

@@ -0,0 +1,22 @@
+/**
+ * Kickoff message the review agent receives. The persona + chart-of-accounts
+ * snapshot live in the system prompt (`buildReviewSystemPrompt`); this is
+ * the per-session instruction.
+ */
+export function buildReviewUserMessage(scope) {
+    return [
+        `Review the local Plasalid journal.`,
+        ``,
+        `Scope:`,
+        `- account: ${scope.accountId ?? "all"}`,
+        `- from: ${scope.from ?? "all time"}`,
+        `- to: ${scope.to ?? "now"}`,
+        `- 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.`,
+        `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/account_mutex.d.ts

@@ -0,0 +1 @@
+export declare function runExclusive<T>(fn: () => Promise<T> | T): Promise<T>;

package/dist/scanner/account_mutex.js

@@ -0,0 +1,16 @@
+/**
+ * Process-wide serialization for write operations that race when multiple scan
+ * agents run in parallel. Each in-flight `create_account` / `update_account_metadata`
+ * is held inside `runExclusive` so the SQLite write + the subsequent read-back
+ * by another agent's `list_accounts` are consistent.
+ *
+ * Single tail-promise queue: cheap, deterministic, no extra deps.
+ */
+let tail = Promise.resolve();
+export function runExclusive(fn) {
+    const next = tail.then(() => fn());
+    // Swallow rejection so a thrown callback doesn't poison the queue for the
+    // next caller. The caller still sees the rejection through `next`.
+    tail = next.catch(() => undefined);
+    return next;
+}

package/dist/scanner/buffer.d.ts

@@ -0,0 +1,48 @@
+import type Database from "libsql";
+import { type JournalEntryInput } from "../db/queries/journal.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.
+ *
+ * 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.
+ */
+export interface BufferedConcern {
+    /** Synthesized when the LLM called note_concern with a buffered entry_id. */
+    entry_id: string | null;
+    account_id: 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 declare class BufferedWriteContext {
+    readonly fileName: string;
+    readonly journalEntries: BufferedEntry[];
+    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.
+     */
+    appendEntry(input: JournalEntryInput): 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.
+     */
+    commit(db: Database.Database, scannedFileId: string): {
+        entries: number;
+        concerns: number;
+    };
+}

package/dist/scanner/buffer.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "crypto";
+import { insertJournalEntryRows, validateJournalEntry, } from "../db/queries/journal.js";
+import { recordConcern } from "../db/queries/concerns.js";
+export class BufferedWriteContext {
+    fileName;
+    journalEntries = [];
+    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.
+     */
+    appendEntry(input) {
+        const entryId = `je:${randomUUID()}`;
+        this.journalEntries.push({ entry_id: entryId, input });
+        return entryId;
+    }
+    appendConcern(concern) {
+        this.concerns.push(concern);
+    }
+    markDone(summary) {
+        this.doneSummary = summary;
+    }
+    get isDone() {
+        return this.doneSummary !== null;
+    }
+    /**
+     * 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.
+     */
+    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 => ({
+            buffered: b,
+            validated: validateJournalEntry({
+                ...b.input,
+                id: b.entry_id,
+                source_file_id: scannedFileId,
+            }),
+        }));
+        const tx = db.transaction(() => {
+            for (const { validated: v } of validated) {
+                insertJournalEntryRows(db, v);
+            }
+            for (const c of this.concerns) {
+                recordConcern(db, {
+                    file_id: scannedFileId,
+                    entry_id: c.entry_id,
+                    account_id: c.account_id,
+                    prompt: c.prompt,
+                    options: c.options,
+                });
+            }
+        });
+        tx();
+        return { entries: this.journalEntries.length, concerns: this.concerns.length };
+    }
+}

package/dist/scanner/concurrency.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run an array of async task factories with a fixed concurrency bound. Resolves
+ * to an array of results in the same order as the input tasks (regardless of
+ * completion order). Any rejection settles that slot with `undefined` and the
+ * caller is responsible for tracking failures — but since each task is wrapped
+ * in `Promise.resolve()` and pushed through `try/catch`, one task throwing
+ * never aborts the rest of the run.
+ *
+ * No new dependency. Simple worker-pool: kicks off up to `n` tasks, then each
+ * worker pulls the next index from a shared cursor until the queue is drained.
+ */
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, n: number): Promise<Array<T | {
+    error: unknown;
+}>>;