plasalid 0.8.2 → 0.9.0

package/dist/db/queries/transactions.js

@@ -129,6 +129,87 @@ export function updatePosting(db, postingId, fields) {
 export function deleteTransaction(db, transactionId) {
     return db.prepare(`DELETE FROM transactions WHERE id = ?`).run(transactionId).changes;
 }
+/**
+ * Backfill primitive. Update every posting matching the filter in one SQL
+ * UPDATE, return the affected count plus a sample of ids so the caller (often
+ * an AI tool) can quote evidence back to the user.
+ *
+ * Refuses to run without at least one filter field (no "update everything"
+ * escape hatch) and without at least one set field. Also refuses a no-op
+ * recategorization where `set.account_id` equals `filter.account_id` —
+ * agents shouldn't waste tool calls on identity transforms.
+ *
+ * Safe-field policy mirrors `updatePosting`: account_id + memo only.
+ * Amount/currency corrections must go through delete + re-record to keep
+ * the transaction's debit=credit invariant intact.
+ */
+export function bulkUpdatePostings(db, filter, set) {
+    const filterFields = Object.keys(filter)
+        .filter((k) => filter[k] !== undefined && filter[k] !== "");
+    if (filterFields.length === 0) {
+        throw new Error("bulkUpdatePostings: at least one filter field is required.");
+    }
+    const setFields = Object.keys(set)
+        .filter((k) => set[k] !== undefined);
+    if (setFields.length === 0) {
+        throw new Error("bulkUpdatePostings: at least one set field is required.");
+    }
+    if (set.account_id !== undefined && set.account_id === filter.account_id) {
+        throw new Error("bulkUpdatePostings: set.account_id equals filter.account_id (no-op).");
+    }
+    const whereClauses = [];
+    const whereParams = [];
+    if (filter.account_id) {
+        whereClauses.push("p.account_id = ?");
+        whereParams.push(filter.account_id);
+    }
+    if (filter.currency) {
+        whereClauses.push("p.currency = ?");
+        whereParams.push(filter.currency);
+    }
+    if (filter.merchant_id) {
+        whereClauses.push("t.merchant_id = ?");
+        whereParams.push(filter.merchant_id);
+    }
+    if (filter.from) {
+        whereClauses.push("t.date >= ?");
+        whereParams.push(filter.from);
+    }
+    if (filter.to) {
+        whereClauses.push("t.date <= ?");
+        whereParams.push(filter.to);
+    }
+    if (filter.description_contains) {
+        whereClauses.push("LOWER(t.description) LIKE ?");
+        whereParams.push(`%${filter.description_contains.toLowerCase()}%`);
+    }
+    const matchIdsSql = `SELECT p.id
+       FROM postings p
+       JOIN transactions t ON t.id = p.transaction_id
+      WHERE ${whereClauses.join(" AND ")}`;
+    const sets = [];
+    const setParams = [];
+    if (set.account_id !== undefined) {
+        sets.push("account_id = ?");
+        setParams.push(set.account_id);
+    }
+    if (set.memo !== undefined) {
+        sets.push("memo = ?");
+        setParams.push(set.memo);
+    }
+    let affected = 0;
+    let sample = [];
+    const tx = db.transaction(() => {
+        const ids = db.prepare(matchIdsSql).all(...whereParams);
+        if (ids.length === 0)
+            return;
+        sample = ids.slice(0, 10).map((r) => r.id);
+        const placeholders = ids.map(() => "?").join(",");
+        affected = db.prepare(`UPDATE postings SET ${sets.join(", ")} WHERE id IN (${placeholders})`).run(...setParams, ...ids.map((r) => r.id)).changes;
+    });
+    tx();
+    return { affected, sample_posting_ids: sample };
+}
 /**
  * Heuristic duplicate finder: group transactions by (rounded total debit) and check
  * pairs whose date difference is ≤ toleranceDays. Returns groups with ≥2 members.
@@ -370,3 +451,8 @@ export function countTransactions(db) {
         .get();
     return row;
 }
+export function countTransactionsBySourceFile(db, fileId) {
+    return db
+        .prepare(`SELECT COUNT(*) AS n FROM transactions WHERE source_file_id = ?`)
+        .get(fileId).n;
+}

package/dist/db/schema.js

@@ -45,6 +45,8 @@ export function migrate(db) {
       status TEXT NOT NULL CHECK(status IN ('pending','scanned','failed')),
       raw_text TEXT,
       scanned_at TEXT,
+      provider TEXT,
+      model TEXT,
       error TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
@@ -110,10 +112,12 @@ export function migrate(db) {
       context_json TEXT,
       answer TEXT,
       resolved_at TEXT,
+      deferred_until TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
     CREATE INDEX IF NOT EXISTS questions_scan_idx ON questions(scan_id);
+    CREATE INDEX IF NOT EXISTS questions_deferred_idx ON questions(deferred_until);
 
     CREATE TABLE IF NOT EXISTS conversation_history (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -129,6 +133,19 @@ export function migrate(db) {
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE TABLE IF NOT EXISTS rules (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      kind TEXT NOT NULL,
+      key TEXT NOT NULL,
+      target TEXT NOT NULL,
+      evidence_count INTEGER NOT NULL DEFAULT 1,
+      last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(kind, key)
+    );
+
+    CREATE INDEX IF NOT EXISTS rules_kind_idx ON rules(kind);
+
     CREATE TABLE IF NOT EXISTS settings (
       key TEXT PRIMARY KEY,
       value TEXT NOT NULL

package/dist/scanner/clarifier-memory.d.ts

@@ -1,8 +1,20 @@
 import type Database from "libsql";
 import type { ClosedQuestion } from "../db/queries/questions.js";
 /**
- * Compact every closed question into a memories row (category `scanning_hint`).
- * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
- * an identical rule for the same kind + prompt won't be re-inserted.
+ * Compact every closed question worth learning from into a `rules` row. The
+ * deterministic clarifier pass looks rules up by `(kind, key)` via the
+ * UNIQUE index, so each evidence event UPSERTs — incrementing
+ * `evidence_count` and refreshing `last_seen_at` on repeats rather than
+ * appending a near-duplicate.
+ *
+ * A closure is NOT learned (no rule synthesized) when any of:
+ *   1. `kind` is in `RULE_KIND_DENYLIST` — failure-class kinds carry no
+ *      generalizable signal.
+ *   2. `answer` starts with `Skip` — skips are one-time recovery decisions,
+ *      not patterns the next scan should auto-apply.
+ *   3. `rule_key` is null — without a structural key the rule could only
+ *      match its own prose, which embeds dates/amounts and never re-fires.
+ *
+ * Returns the count of rules upserted (new or repeat-evidence).
  */
 export declare function synthesizeMemoryRules(db: Database.Database, closures: readonly ClosedQuestion[]): number;

package/dist/scanner/clarifier-memory.js

@@ -1,24 +1,45 @@
+import { upsertRule } from "../db/queries/rules.js";
 /**
- * Compact every closed question into a memories row (category `scanning_hint`).
- * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
- * an identical rule for the same kind + prompt won't be re-inserted.
+ * Compact every closed question worth learning from into a `rules` row. The
+ * deterministic clarifier pass looks rules up by `(kind, key)` via the
+ * UNIQUE index, so each evidence event UPSERTs — incrementing
+ * `evidence_count` and refreshing `last_seen_at` on repeats rather than
+ * appending a near-duplicate.
+ *
+ * A closure is NOT learned (no rule synthesized) when any of:
+ *   1. `kind` is in `RULE_KIND_DENYLIST` — failure-class kinds carry no
+ *      generalizable signal.
+ *   2. `answer` starts with `Skip` — skips are one-time recovery decisions,
+ *      not patterns the next scan should auto-apply.
+ *   3. `rule_key` is null — without a structural key the rule could only
+ *      match its own prose, which embeds dates/amounts and never re-fires.
+ *
+ * Returns the count of rules upserted (new or repeat-evidence).
  */
 export function synthesizeMemoryRules(db, closures) {
-    if (closures.length === 0)
-        return 0;
-    let inserted = 0;
-    const exists = db.prepare(`SELECT 1 FROM memories WHERE category = ? AND content = ? LIMIT 1`);
-    const insert = db.prepare(`INSERT INTO memories (content, category) VALUES (?, ?)`);
-    for (const c of closures) {
-        const body = formatRule(c);
-        if (exists.get("scanning_hint", body))
+    let upserted = 0;
+    for (const closure of closures) {
+        if (!isRuleSource(closure))
             continue;
-        insert.run(body, "scanning_hint");
-        inserted++;
+        upsertRule(db, { kind: closure.kind, key: closure.rule_key, target: closure.answer.trim() });
+        upserted++;
     }
-    return inserted;
+    return upserted;
 }
-function formatRule(c) {
-    const kindLabel = c.kind ?? "general";
-    return `[${kindLabel}] ${c.prompt.replace(/\s+/g, " ").trim()} -> ${c.answer.trim()}`;
+const RULE_KIND_DENYLIST = new Set([
+    "dirty_input",
+    "scan_truncated",
+    "boundary_continuation",
+]);
+function isRuleSource(c) {
+    if (!c.kind || !c.rule_key)
+        return false;
+    if (RULE_KIND_DENYLIST.has(c.kind))
+        return false;
+    if (isSkipAnswer(c.answer))
+        return false;
+    return true;
+}
+function isSkipAnswer(answer) {
+    return answer.trim().toLowerCase().startsWith("skip");
 }

package/dist/scanner/clarifier.d.ts

@@ -36,6 +36,7 @@ export declare const CLARIFIER_PASSES: readonly ClarifierPass[];
  * Single entry point shared by the in-scan resolve phase and the standalone
  * `plasalid clarify` command. Runs deterministic passes first, then (when
  * interactive) hands the leftovers to the LLM clarifier agent. Closed
- * questions get compacted into scanning_hint memories.
+ * questions get upserted into the rules table (keyed on the question's
+ * structural signature, not its prose).
  */
 export declare function runClarify(opts: RunClarifyOpts): Promise<ClarifySummary>;

package/dist/scanner/clarifier.js

@@ -1,29 +1,38 @@
 import { closeQuestion, listQuestions, countQuestions, } from "../db/queries/questions.js";
 import { updatePosting } from "../db/queries/transactions.js";
+import { findRule } from "../db/queries/rules.js";
 import { runClarifyAgent } from "../ai/agent.js";
 import { synthesizeMemoryRules } from "./clarifier-memory.js";
+import { applyRecurrenceRules, generateRecurrenceCandidateQuestions, } from "./recurrence.js";
 import { converge } from "./converge.js";
 const MAX_AGENT_PASSES = 3;
 /**
- * Apply deterministic passes via memory_rules lookups. Closes any question
- * whose prompt has a stored scanning_hint that already encodes the answer.
+ * Apply deterministic resolution via a `(kind, key)` indexed lookup in the
+ * rules table. The rule's `key` was computed at question-creation time
+ * (see `src/scanner/committer.ts`) from a stable structural signature — merchant id,
+ * normalized descriptor, account pair — so the same pattern matches
+ * across scans regardless of date, amount, or prompt prose.
  */
 const memoryRulePass = {
     name: "memory_rule",
-    kinds: ["uncategorized", "uncategorized_expense", "duplicate", "correlation", "recurrence_candidate", "similar_accounts", "boundary_continuation", "scan_truncated", "scan_commit_failure"],
+    kinds: [
+        "uncategorized",
+        "uncategorized_expense",
+        "duplicate",
+        "correlation",
+        "similar_accounts",
+        "boundary_continuation",
+        "scan_truncated",
+        "unknown_merchant",
+    ],
     async tryResolve(u, ctx) {
-        const rules = ctx.db
-            .prepare(`SELECT content FROM memories WHERE category = 'scanning_hint'`)
-            .all();
-        const key = canonicalKey(u);
-        for (const r of rules) {
-            const match = parseRule(r.content);
-            if (!match)
-                continue;
-            if (match.key === key)
-                return match.answer;
-        }
-        return null;
+        if (!u.kind)
+            return null;
+        const key = extractRuleKey(u.context_json);
+        if (!key)
+            return null;
+        const rule = findRule(ctx.db, u.kind, key);
+        return rule?.target ?? null;
     },
 };
 /**
@@ -69,12 +78,19 @@ export const CLARIFIER_PASSES = [
  * Single entry point shared by the in-scan resolve phase and the standalone
  * `plasalid clarify` command. Runs deterministic passes first, then (when
  * interactive) hands the leftovers to the LLM clarifier agent. Closed
- * questions get compacted into scanning_hint memories.
+ * questions get upserted into the rules table (keyed on the question's
+ * structural signature, not its prose).
  */
 export async function runClarify(opts) {
     const { db } = opts;
     const tally = {};
     const closures = [];
+    const autoLinked = applyRecurrenceRules(db).linked;
+    if (autoLinked > 0)
+        tally["recurrence_auto_link"] = autoLinked;
+    const generated = generateRecurrenceCandidateQuestions(db, opts.scanId ?? null);
+    if (generated > 0)
+        tally["recurrence_generation"] = generated;
     const initial = listQuestions(db, { scanId: opts.scanId, limit: 1000 });
     const total = initial.length;
     if (total === 0) {
@@ -182,16 +198,14 @@ function parseOptions(json) {
         return [];
     }
 }
-function canonicalKey(u) {
-    return `[${u.kind ?? "general"}] ${u.prompt.replace(/\s+/g, " ").trim()}`;
-}
-function parseRule(body) {
-    const idx = body.lastIndexOf(" -> ");
-    if (idx < 0)
+function extractRuleKey(contextJson) {
+    if (!contextJson)
         return null;
-    const key = body.slice(0, idx).trim();
-    const answer = body.slice(idx + 4).trim();
-    if (!key || !answer)
+    try {
+        const parsed = JSON.parse(contextJson);
+        return typeof parsed?.rule_key === "string" ? parsed.rule_key : null;
+    }
+    catch {
         return null;
-    return { key, answer };
+    }
 }

package/dist/scanner/commit-pipeline.d.ts

@@ -0,0 +1,56 @@
+import type Database from "libsql";
+import { type TransactionInput } from "../db/queries/transactions.js";
+/**
+ * Staged best-effort transaction commit.
+ *
+ * Each stage returns a tagged union. Side effects (raising questions,
+ * progress emission, placeholder account creation) flow through the
+ * `CommitHooks` interface so the pipeline stays pure-ish and testable.
+ *
+ * The only legitimate drop path is a `dirty_input` validation failure
+ * (no date, malformed amount, etc.). Every other resolution problem —
+ * unknown merchant, unknown account — is rescued in-place: NULL the
+ * merchant, fuzzy-match-or-create the account, raise a typed question
+ * for the clarifier to review later.
+ */
+export interface CommitContext {
+    readonly scanId: string | null;
+    readonly fileId: string | null;
+    readonly chunkId: string | null;
+    readonly progress: ProgressEmitter | null;
+}
+export interface ProgressEmitter {
+    emit(event: {
+        chunkId: string;
+        kind: "tx" | "question";
+    }): void;
+}
+export type CommitOutcome = {
+    ok: true;
+    transactionId: string;
+    raisedQuestions: number;
+} | {
+    ok: false;
+    reason: DropReason;
+    message: string;
+    raisedQuestions: number;
+};
+export type DropReason = "dirty_input";
+export interface CommitHooks {
+    onCommitted(transactionId: string): void;
+    onDirtyInput(input: TransactionInput, reason: string): void;
+    onUnknownMerchant(input: TransactionInput, transactionId: string, attemptedId: string): void;
+    onPlaceholderAccount(accountId: string, transactionId: string): void;
+    onSimilarAccount(originalId: string, matchedId: string, transactionId: string): void;
+}
+/**
+ * Default hook wiring: raises typed questions into the DB, ticks the
+ * progress emitter. Tests substitute their own hooks to inspect events
+ * without touching the question table.
+ *
+ * Question writes are gated on `ctx.scanId` — outside a scan there is no
+ * audit trail to attach to, so best-effort resolution still happens but
+ * the typed question is suppressed.
+ */
+export declare function defaultCommitHooks(db: Database.Database, ctx: CommitContext): CommitHooks;
+export declare function runCommitPipeline(db: Database.Database, ctx: CommitContext, input: TransactionInput, hooks?: CommitHooks): CommitOutcome;

package/dist/scanner/commit-pipeline.js

@@ -0,0 +1,204 @@
+import { validateTransaction, insertTransactionRows, } from "../db/queries/transactions.js";
+import { createAccount, findAccountById, findAccountsByFuzzyName, ensureStructuralAccount, ensureTopLevelRoot, TOP_LEVEL_TYPES, } from "../db/queries/account-balance.js";
+import { recordQuestion } from "../db/queries/questions.js";
+import { accountIdKey, accountPairKey, descriptorKey, } from "./rule-keys.js";
+/**
+ * Default hook wiring: raises typed questions into the DB, ticks the
+ * progress emitter. Tests substitute their own hooks to inspect events
+ * without touching the question table.
+ *
+ * Question writes are gated on `ctx.scanId` — outside a scan there is no
+ * audit trail to attach to, so best-effort resolution still happens but
+ * the typed question is suppressed.
+ */
+export function defaultCommitHooks(db, ctx) {
+    const tick = (kind) => {
+        if (ctx.progress && ctx.chunkId)
+            ctx.progress.emit({ chunkId: ctx.chunkId, kind });
+    };
+    const raise = (input) => {
+        if (!ctx.scanId)
+            return;
+        recordQuestion(db, { ...input, file_id: ctx.fileId, scan_id: ctx.scanId });
+        tick("question");
+    };
+    return {
+        onCommitted: () => tick("tx"),
+        onDirtyInput: (input, reason) => raise({
+            transaction_id: null,
+            account_id: null,
+            kind: "dirty_input",
+            prompt: `The scanner returned a row that couldn't be validated: ${reason}. ` +
+                `Raw description: "${input.description}" on ${input.date}.`,
+            context: { description: input.description, date: input.date, reason },
+        }),
+        onUnknownMerchant: (input, transactionId, attemptedId) => {
+            const descriptor = input.raw_descriptor || input.description;
+            raise({
+                transaction_id: transactionId,
+                account_id: null,
+                kind: "unknown_merchant",
+                prompt: `The scanner referenced merchant id "${attemptedId}" but no such merchant exists. ` +
+                    `Link "${descriptor}" to an existing merchant or leave it unlinked.`,
+                context: { rule_key: descriptorKey(descriptor), descriptor, attempted_id: attemptedId },
+            });
+        },
+        onPlaceholderAccount: (accountId, transactionId) => raise({
+            transaction_id: transactionId,
+            account_id: accountId,
+            kind: "uncategorized",
+            prompt: `A placeholder account was created for posting "${accountId}". ` +
+                `Confirm the category, merge into an existing account, or rename.`,
+            context: { rule_key: accountIdKey(accountId), placeholder_id: accountId },
+        }),
+        onSimilarAccount: (originalId, matchedId, transactionId) => raise({
+            transaction_id: transactionId,
+            account_id: matchedId,
+            kind: "similar_accounts",
+            prompt: `The scanner referenced "${originalId}" — the closest existing account is "${matchedId}". ` +
+                `Confirm they are the same, or split them apart.`,
+            context: {
+                rule_key: accountPairKey(originalId, matchedId),
+                original_id: originalId,
+                matched_id: matchedId,
+            },
+        }),
+    };
+}
+export function runCommitPipeline(db, ctx, input, hooks = defaultCommitHooks(db, ctx)) {
+    const validation = stageValidate(input);
+    if (!validation.ok) {
+        hooks.onDirtyInput(input, validation.reason);
+        return { ok: false, reason: "dirty_input", message: validation.reason, raisedQuestions: 1 };
+    }
+    const merchant = stageResolveMerchant(db, validation.validated);
+    const accounts = stageResolveAccounts(db, validation.validated);
+    const committed = {
+        ...validation.validated,
+        merchant_id: merchant.merchantId,
+        postings: accounts.postings,
+    };
+    const tx = db.transaction(() => insertTransactionRows(db, committed));
+    tx();
+    hooks.onCommitted(committed.id);
+    const raised = applyHints({ hooks, transactionId: committed.id, merchant, accounts, input });
+    return { ok: true, transactionId: committed.id, raisedQuestions: raised };
+}
+function stageValidate(input) {
+    try {
+        return { ok: true, validated: validateTransaction(input) };
+    }
+    catch (err) {
+        return { ok: false, reason: err?.message ?? String(err) };
+    }
+}
+function stageResolveMerchant(db, input) {
+    if (!input.merchant_id)
+        return { merchantId: null, attemptedUnknownId: null };
+    const exists = db.prepare(`SELECT 1 FROM merchants WHERE id = ?`).get(input.merchant_id);
+    if (exists)
+        return { merchantId: input.merchant_id, attemptedUnknownId: null };
+    return { merchantId: null, attemptedUnknownId: input.merchant_id };
+}
+function stageResolveAccounts(db, input) {
+    const postings = [];
+    const hints = [];
+    for (const p of input.postings) {
+        const resolved = resolveOnePosting(db, p);
+        postings.push(resolved.posting);
+        if (resolved.hint)
+            hints.push(resolved.hint);
+    }
+    return { postings, hints };
+}
+function resolveOnePosting(db, posting) {
+    if (findAccountById(db, posting.account_id)) {
+        return { posting, hint: null };
+    }
+    const matched = bestFuzzyMatch(db, posting.account_id);
+    if (matched) {
+        return {
+            posting: { ...posting, account_id: matched },
+            hint: { type: "similar_matched", originalId: posting.account_id, matchedId: matched },
+        };
+    }
+    const placeholderId = ensurePlaceholderAccount(db, posting.account_id);
+    return {
+        posting: { ...posting, account_id: placeholderId },
+        hint: { type: "placeholder_created", accountId: placeholderId },
+    };
+}
+const FUZZY_THRESHOLD = 0.7;
+function bestFuzzyMatch(db, accountId) {
+    const leaf = leafSegment(accountId).replace(/[-_]+/g, " ");
+    if (!leaf)
+        return null;
+    const matches = findAccountsByFuzzyName(db, leaf, FUZZY_THRESHOLD);
+    return matches[0]?.account.id ?? null;
+}
+function leafSegment(id) {
+    const segments = id.split(":");
+    return segments[segments.length - 1] ?? id;
+}
+/**
+ * Create the agent-supplied account id (and any missing intermediate parents)
+ * as placeholders so the transaction can land. If the id's top-level segment
+ * isn't a known account type, fall back to `expense:uncategorized`.
+ */
+function ensurePlaceholderAccount(db, accountId) {
+    const segments = accountId.split(":").filter(Boolean);
+    if (segments.length === 0)
+        return ensureUncategorizedFallback(db);
+    const type = segments[0];
+    if (!TOP_LEVEL_TYPES.includes(type))
+        return ensureUncategorizedFallback(db);
+    ensureTopLevelRoot(db, type);
+    for (let i = 2; i <= segments.length; i++) {
+        const id = segments.slice(0, i).join(":");
+        if (findAccountById(db, id))
+            continue;
+        const parentId = i === 1 ? null : segments.slice(0, i - 1).join(":");
+        const name = humanizeSegment(segments[i - 1]);
+        try {
+            createAccount(db, { id, name, type, parent_id: parentId });
+        }
+        catch (err) {
+            if (err?.code === "ACCOUNT_EXISTS")
+                continue;
+            return ensureUncategorizedFallback(db);
+        }
+    }
+    return accountId;
+}
+function ensureUncategorizedFallback(db) {
+    ensureStructuralAccount(db, "expense:uncategorized");
+    return "expense:uncategorized";
+}
+function humanizeSegment(segment) {
+    const spaced = segment.replace(/[-_]+/g, " ").trim();
+    if (!spaced)
+        return "Placeholder";
+    return spaced.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function applyHints(args) {
+    let raised = 0;
+    if (args.merchant.attemptedUnknownId) {
+        args.hooks.onUnknownMerchant(args.input, args.transactionId, args.merchant.attemptedUnknownId);
+        raised++;
+    }
+    for (const hint of args.accounts.hints) {
+        dispatchHint(hint, args.hooks, args.transactionId);
+        raised++;
+    }
+    return raised;
+}
+function dispatchHint(hint, hooks, transactionId) {
+    switch (hint.type) {
+        case "placeholder_created":
+            hooks.onPlaceholderAccount(hint.accountId, transactionId);
+            return;
+        case "similar_matched":
+            hooks.onSimilarAccount(hint.originalId, hint.matchedId, transactionId);
+            return;
+    }
+}

package/dist/scanner/committer.d.ts

@@ -0,0 +1,56 @@
+import type Database from "libsql";
+import { type TransactionInput } from "../db/queries/transactions.js";
+/**
+ * Staged best-effort transaction commit.
+ *
+ * Each stage returns a tagged union. Side effects (raising questions,
+ * progress emission, placeholder account creation) flow through the
+ * `CommitHooks` interface so the pipeline stays pure-ish and testable.
+ *
+ * The only legitimate drop path is a `dirty_input` validation failure
+ * (no date, malformed amount, etc.). Every other resolution problem —
+ * unknown merchant, unknown account — is rescued in-place: NULL the
+ * merchant, fuzzy-match-or-create the account, raise a typed question
+ * for the clarifier to review later.
+ */
+export interface CommitContext {
+    readonly scanId: string | null;
+    readonly fileId: string | null;
+    readonly chunkId: string | null;
+    readonly progress: ProgressEmitter | null;
+}
+export interface ProgressEmitter {
+    emit(event: {
+        chunkId: string;
+        kind: "tx" | "question";
+    }): void;
+}
+export type CommitOutcome = {
+    ok: true;
+    transactionId: string;
+    raisedQuestions: number;
+} | {
+    ok: false;
+    reason: DropReason;
+    message: string;
+    raisedQuestions: number;
+};
+export type DropReason = "dirty_input";
+export interface CommitHooks {
+    onCommitted(transactionId: string): void;
+    onDirtyInput(input: TransactionInput, reason: string): void;
+    onUnknownMerchant(input: TransactionInput, transactionId: string, attemptedId: string): void;
+    onPlaceholderAccount(accountId: string, transactionId: string): void;
+    onSimilarAccount(originalId: string, matchedId: string, transactionId: string): void;
+}
+/**
+ * Default hook wiring: raises typed questions into the DB, ticks the
+ * progress emitter. Tests substitute their own hooks to inspect events
+ * without touching the question table.
+ *
+ * Question writes are gated on `ctx.scanId` — outside a scan there is no
+ * audit trail to attach to, so best-effort resolution still happens but
+ * the typed question is suppressed.
+ */
+export declare function defaultCommitHooks(db: Database.Database, ctx: CommitContext): CommitHooks;
+export declare function commitTransaction(db: Database.Database, ctx: CommitContext, input: TransactionInput, hooks?: CommitHooks): CommitOutcome;