plasalid 0.8.3 → 0.9.1

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

@@ -22,12 +22,17 @@ export interface QuestionRow {
     prompt: string;
     options_json: string | null;
     context_json: string | null;
+    deferred_until: string | null;
     created_at: string;
 }
 export interface ClosedQuestion {
     prompt: string;
     kind: string | null;
     answer: string;
+    /** Stable signature pulled from the question's context_json. When set, the
+     * rule synthesizer keys the learned rule on this (so future questions with
+     * different prose but the same key match). When null, no rule is learned. */
+    rule_key: string | null;
 }
 /**
  * Insert a new questions row and flip the `has_question` boolean on whichever
@@ -53,10 +58,22 @@ export interface CountQuestionsScope {
     account_id?: string;
     kind?: string;
     scan_id?: string;
+    /** When true, count deferred rows too (default false — defer hides). */
+    includeDeferred?: boolean;
 }
 export declare function countQuestions(db: Database.Database, scope?: CountQuestionsScope): number;
 export interface ListQuestionsOptions {
     limit?: number;
     scanId?: string;
+    /** When true, include deferred rows in the result (default false). */
+    includeDeferred?: boolean;
 }
 export declare function listQuestions(db: Database.Database, opts?: ListQuestionsOptions): QuestionRow[];
+/**
+ * Mark a question as deferred for `days` days from now. The default
+ * `listQuestions` / `countQuestions` filter hides deferred rows until the
+ * timestamp passes, so the clarifier won't re-encounter the question on the
+ * next run. Pass `includeDeferred: true` to those functions for an
+ * unfiltered view (e.g. for the rules / files browsers).
+ */
+export declare function deferQuestion(db: Database.Database, id: string, days: number): boolean;

package/dist/db/queries/questions.js

@@ -24,7 +24,7 @@ export function recordQuestion(db, input) {
  */
 export function closeQuestion(db, id, answer) {
     const row = db
-        .prepare(`SELECT prompt, kind, transaction_id, account_id FROM questions WHERE id = ?`)
+        .prepare(`SELECT prompt, kind, transaction_id, account_id, context_json FROM questions WHERE id = ?`)
         .get(id);
     if (!row)
         return null;
@@ -33,7 +33,23 @@ export function closeQuestion(db, id, answer) {
         transaction_id: row.transaction_id,
         account_id: row.account_id,
     });
-    return { prompt: row.prompt, kind: row.kind, answer };
+    return {
+        prompt: row.prompt,
+        kind: row.kind,
+        answer,
+        rule_key: extractRuleKey(row.context_json),
+    };
+}
+function extractRuleKey(contextJson) {
+    if (!contextJson)
+        return null;
+    try {
+        const parsed = JSON.parse(contextJson);
+        return typeof parsed?.rule_key === "string" ? parsed.rule_key : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Look up the transaction/account a question is attached to. Returns null when
@@ -65,6 +81,7 @@ function maybeClearHasQuestionFlags(db, target) {
             db.prepare(`UPDATE accounts SET has_question = 0 WHERE id = ?`).run(target.account_id);
     }
 }
+const ACTIVE_DEFERRED_CLAUSE = "(deferred_until IS NULL OR deferred_until <= datetime('now'))";
 export function countQuestions(db, scope = {}) {
     const conditions = [];
     const params = [];
@@ -88,23 +105,44 @@ export function countQuestions(db, scope = {}) {
         conditions.push("scan_id = ?");
         params.push(scope.scan_id);
     }
+    if (!scope.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
     const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
     const row = db
         .prepare(`SELECT COUNT(*) AS n FROM questions ${where}`)
         .get(...params);
     return row.n;
 }
+const ROW_COLUMNS = "id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, deferred_until, created_at";
 export function listQuestions(db, opts = {}) {
     const capped = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    const conditions = [];
+    const params = [];
     if (opts.scanId) {
-        return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
-       FROM questions
-       WHERE scan_id = ?
-       ORDER BY created_at ASC
-       LIMIT ?`).all(opts.scanId, capped);
+        conditions.push("scan_id = ?");
+        params.push(opts.scanId);
     }
-    return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+    if (!opts.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    params.push(capped);
+    return db.prepare(`SELECT ${ROW_COLUMNS}
      FROM questions
+     ${where}
      ORDER BY created_at ASC
-     LIMIT ?`).all(capped);
+     LIMIT ?`).all(...params);
+}
+/**
+ * Mark a question as deferred for `days` days from now. The default
+ * `listQuestions` / `countQuestions` filter hides deferred rows until the
+ * timestamp passes, so the clarifier won't re-encounter the question on the
+ * next run. Pass `includeDeferred: true` to those functions for an
+ * unfiltered view (e.g. for the rules / files browsers).
+ */
+export function deferQuestion(db, id, days) {
+    const safeDays = Math.max(1, Math.floor(days));
+    const result = db
+        .prepare(`UPDATE questions SET deferred_until = datetime('now', ?) WHERE id = ?`)
+        .run(`+${safeDays} days`, id);
+    return result.changes > 0;
 }

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

@@ -0,0 +1,31 @@
+import type Database from "libsql";
+export interface Rule {
+    id: number;
+    kind: string;
+    key: string;
+    target: string;
+    evidence_count: number;
+    last_seen_at: string;
+    created_at: string;
+}
+export interface UpsertRuleInput {
+    kind: string;
+    key: string;
+    target: string;
+}
+/**
+ * Insert a rule keyed on (kind, key), or — if one already exists — bump
+ * `evidence_count`, refresh `last_seen_at`, and overwrite `target` with the
+ * latest answer. The deterministic clarifier pass looks rules up via the
+ * UNIQUE(kind, key) index, so this is the only write path that keeps the
+ * rule store sparse and indexed.
+ */
+export declare function upsertRule(db: Database.Database, input: UpsertRuleInput): Rule;
+export declare function findRule(db: Database.Database, kind: string, key: string): Rule | null;
+export interface ListRulesOptions {
+    kind?: string;
+    limit?: number;
+}
+export declare function listRules(db: Database.Database, opts?: ListRulesOptions): Rule[];
+export declare function countRules(db: Database.Database): number;
+export declare function deleteRule(db: Database.Database, id: number): Rule | null;

package/dist/db/queries/rules.js

@@ -0,0 +1,55 @@
+/**
+ * Insert a rule keyed on (kind, key), or — if one already exists — bump
+ * `evidence_count`, refresh `last_seen_at`, and overwrite `target` with the
+ * latest answer. The deterministic clarifier pass looks rules up via the
+ * UNIQUE(kind, key) index, so this is the only write path that keeps the
+ * rule store sparse and indexed.
+ */
+export function upsertRule(db, input) {
+    db.prepare(`INSERT INTO rules (kind, key, target)
+     VALUES (?, ?, ?)
+     ON CONFLICT(kind, key) DO UPDATE SET
+       target = excluded.target,
+       evidence_count = evidence_count + 1,
+       last_seen_at = datetime('now')`).run(input.kind, input.key, input.target);
+    const row = findRule(db, input.kind, input.key);
+    if (!row)
+        throw new Error(`upsertRule: row vanished after upsert (${input.kind}, ${input.key})`);
+    return row;
+}
+export function findRule(db, kind, key) {
+    const row = db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules WHERE kind = ? AND key = ?`)
+        .get(kind, key);
+    return row ?? null;
+}
+export function listRules(db, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 500, 1), 5000);
+    if (opts.kind) {
+        return db
+            .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+         FROM rules WHERE kind = ?
+         ORDER BY last_seen_at DESC LIMIT ?`)
+            .all(opts.kind, limit);
+    }
+    return db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules
+       ORDER BY last_seen_at DESC LIMIT ?`)
+        .all(limit);
+}
+export function countRules(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM rules`).get();
+    return row.n;
+}
+export function deleteRule(db, id) {
+    const row = db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    db.prepare(`DELETE FROM rules WHERE id = ?`).run(id);
+    return row;
+}

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

@@ -89,6 +89,39 @@ export declare function updatePosting(db: Database.Database, postingId: string,
  * the postings automatically.
  */
 export declare function deleteTransaction(db: Database.Database, transactionId: string): number;
+export interface BulkUpdatePostingsFilter {
+    account_id?: string;
+    /** Case-insensitive substring match against `transactions.description`.
+     *  Use multiple bulk calls for descriptor variants — there is no regex. */
+    description_contains?: string;
+    currency?: string;
+    from?: string;
+    to?: string;
+    merchant_id?: string;
+}
+export interface BulkUpdatePostingsSet {
+    account_id?: string;
+    memo?: string | null;
+}
+export interface BulkUpdatePostingsResult {
+    affected: number;
+    sample_posting_ids: string[];
+}
+/**
+ * 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 declare function bulkUpdatePostings(db: Database.Database, filter: BulkUpdatePostingsFilter, set: BulkUpdatePostingsSet): BulkUpdatePostingsResult;
 export interface DuplicateGroupTransaction {
     id: string;
     date: string;
@@ -170,3 +203,4 @@ export interface TransactionTotals {
     postings: number;
 }
 export declare function countTransactions(db: Database.Database): TransactionTotals;
+export declare function countTransactionsBySourceFile(db: Database.Database, fileId: string): number;

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;