plasalid 0.8.3 → 0.9.0

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;

package/dist/scanner/committer.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 "./rules.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 commitTransaction(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/parse.js

@@ -1,6 +1,8 @@
 import { runWithConcurrency } from "./concurrency.js";
 import { runScanWorker } from "./worker.js";
 import { errorMessage } from "./result.js";
+import { getActiveModel } from "../config.js";
+import { getProvider } from "../ai/providers/index.js";
 const MAX_FILE_WORKERS = 5;
 const MAX_SCAN_WORKERS_PER_FILE = 5;
 const HARD_CAP = 8;
@@ -44,18 +46,34 @@ export async function parsePhase(db, state, hooks) {
             });
     }
     /**
-     * Only flip files to "scanned" for groups that actually completed. On abort
-     * the pool leaves later groups unclaimed (their settled slot is undefined);
-     * those rows stay `pending` so a future re-scan can pick them up. Partial
-     * transactions already committed during the run stay (scanner is DB-direct).
+     * Flip each file's `scanned_files` row to its terminal status. Three cases:
+     *   - settled.ok        → 'scanned'  + stamp provider/model (provenance for re-scans).
+     *   - settled, !ok      → 'failed'   so the user sees it in `plasalid status`.
+     *   - unsettled, aborted → leave 'pending' so a future scan can resume.
+     *   - unsettled, !aborted → 'failed' (defensive — shouldn't happen, but better
+     *     a visible failed row than a silent pending one).
+     * Partial transactions already committed during the run stay (scanner is DB-direct).
      */
+    const aborted = state.signal?.aborted ?? false;
+    const provider = getProvider().name;
+    const model = getActiveModel();
+    const stampScanned = db.prepare(`UPDATE scanned_files SET status = 'scanned', scanned_at = datetime('now'), provider = ?, model = ? WHERE id = ?`);
+    const stampFailed = db.prepare(`UPDATE scanned_files SET status = 'failed', error = ? WHERE id = ?`);
     for (let i = 0; i < fileGroups.length; i++) {
-        if (!settled[i])
-            continue;
         const sfId = fileGroups[i].scannedFileId;
         if (!sfId)
             continue;
-        db.prepare(`UPDATE scanned_files SET status = 'scanned', scanned_at = datetime('now') WHERE id = ?`).run(sfId);
+        const r = settled[i];
+        if (r?.ok) {
+            stampScanned.run(provider, model, sfId);
+        }
+        else if (r && !r.ok) {
+            stampFailed.run(errorMessage(r.error), sfId);
+        }
+        else if (!aborted) {
+            stampFailed.run("worker did not produce a settled result", sfId);
+        }
+        // else: aborted + unsettled → leave pending for resume
     }
     await hooks.afterParse?.(state);
 }

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

@@ -0,0 +1,28 @@
+import type Database from "libsql";
+/**
+ * Structural key for a recurring-payment bucket. Same key across runs means
+ * the same (account, amount, currency, side) signature — the unit on which
+ * we learn "yes this recurs" / "no this doesn't" decisions.
+ *
+ * Embeds amount-in-cents because the recurrence identity *is* the amount:
+ * ฿199 monthly ≠ ฿299 monthly. The "no amounts in dedup keys" rule applies
+ * to merchant-category rules where amount varies; here it is intrinsic.
+ */
+export declare function recurrenceCandidateKey(accountId: string, amountCents: number, currency: string, side: "debit" | "credit"): string;
+/**
+ * Fast path. For every learned "Link as recurring" rule, attach any matching
+ * unlinked transaction to the existing recurrences row. One rules-table
+ * lookup and one recurrences-table lookup per `(account, currency, amount)`
+ * bucket — never re-runs the heuristic.
+ */
+export declare function applyRecurrenceRules(db: Database.Database): {
+    linked: number;
+};
+/**
+ * Slow path. Runs the heuristic, drops irregular cadences, and skips any
+ * bucket already covered by a rule (either decision — "Link" or "Not
+ * recurring" both mean "don't ask again") or by an already-open question
+ * with the same key. Each survivor becomes one `recurrence_candidate`
+ * question that flows through the existing clarifier pipeline.
+ */
+export declare function generateRecurrenceCandidateQuestions(db: Database.Database, scanId: string | null): number;

package/dist/scanner/recurrence-pipeline.js

@@ -0,0 +1,126 @@
+import { findRecurrenceCandidates, linkTransactionToRecurrence, } from "../db/queries/recurrences.js";
+import { recordQuestion } from "../db/queries/questions.js";
+import { formatAmount } from "../currency.js";
+/**
+ * Structural key for a recurring-payment bucket. Same key across runs means
+ * the same (account, amount, currency, side) signature — the unit on which
+ * we learn "yes this recurs" / "no this doesn't" decisions.
+ *
+ * Embeds amount-in-cents because the recurrence identity *is* the amount:
+ * ฿199 monthly ≠ ฿299 monthly. The "no amounts in dedup keys" rule applies
+ * to merchant-category rules where amount varies; here it is intrinsic.
+ */
+export function recurrenceCandidateKey(accountId, amountCents, currency, side) {
+    return `recurrence:${accountId}:${currency}:${amountCents}:${side}`;
+}
+const RULE_KIND = "recurrence_candidate";
+const ANSWER_LINK = "Link as recurring";
+/**
+ * Fast path. For every learned "Link as recurring" rule, attach any matching
+ * unlinked transaction to the existing recurrences row. One rules-table
+ * lookup and one recurrences-table lookup per `(account, currency, amount)`
+ * bucket — never re-runs the heuristic.
+ */
+export function applyRecurrenceRules(db) {
+    const rules = db.prepare(`SELECT key FROM rules WHERE kind = ? AND target = ?`).all(RULE_KIND, ANSWER_LINK);
+    if (rules.length === 0)
+        return { linked: 0 };
+    const unlinkedByKey = new Map();
+    const rows = db.prepare(`SELECT p.transaction_id,
+            p.account_id,
+            p.currency,
+            CASE WHEN p.debit > 0 THEN p.debit ELSE p.credit END AS amount,
+            CASE WHEN p.debit > 0 THEN 'debit' ELSE 'credit' END AS side
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     WHERE t.recurrence_id IS NULL
+       AND (p.debit > 0 OR p.credit > 0)`).all();
+    for (const r of rows) {
+        const key = recurrenceCandidateKey(r.account_id, Math.round(r.amount * 100), r.currency, r.side);
+        const bucket = unlinkedByKey.get(key) ?? [];
+        bucket.push(r);
+        unlinkedByKey.set(key, bucket);
+    }
+    let linked = 0;
+    for (const { key } of rules) {
+        const bucket = unlinkedByKey.get(key);
+        if (!bucket || bucket.length === 0)
+            continue;
+        const first = bucket[0];
+        const recurrence = db.prepare(`SELECT id FROM recurrences WHERE account_id = ? AND currency = ? AND amount_typical = ? LIMIT 1`).get(first.account_id, first.currency, Math.round(first.amount * 100) / 100);
+        if (!recurrence)
+            continue; // rule learned but aggregate row gone — let the heuristic re-surface
+        for (const r of bucket) {
+            linkTransactionToRecurrence(db, r.transaction_id, recurrence.id);
+            linked++;
+        }
+    }
+    return { linked };
+}
+/**
+ * Slow path. Runs the heuristic, drops irregular cadences, and skips any
+ * bucket already covered by a rule (either decision — "Link" or "Not
+ * recurring" both mean "don't ask again") or by an already-open question
+ * with the same key. Each survivor becomes one `recurrence_candidate`
+ * question that flows through the existing clarifier pipeline.
+ */
+export function generateRecurrenceCandidateQuestions(db, scanId) {
+    const coveredKeys = collectCoveredKeys(db);
+    const candidates = findRecurrenceCandidates(db).filter((c) => c.implied_frequency !== "irregular");
+    let created = 0;
+    for (const c of candidates) {
+        const amountCents = Math.round(c.amount * 100);
+        const side = c.side;
+        const key = recurrenceCandidateKey(c.account_id, amountCents, c.currency, side);
+        if (coveredKeys.has(key))
+            continue;
+        recordQuestion(db, {
+            transaction_id: null,
+            account_id: c.account_id,
+            file_id: null,
+            scan_id: scanId,
+            kind: RULE_KIND,
+            prompt: buildPrompt(c),
+            options: ["Link as recurring", "Not recurring", "Skip"],
+            context: {
+                rule_key: key,
+                account_id: c.account_id,
+                amount: c.amount,
+                currency: c.currency,
+                side: c.side,
+                transaction_ids: c.transactions.map((t) => t.id),
+                median_days_between: c.median_days_between,
+                implied_frequency: c.implied_frequency,
+            },
+        });
+        coveredKeys.add(key); // avoid duplicate inserts within this same call
+        created++;
+    }
+    return created;
+}
+function collectCoveredKeys(db) {
+    const ruleKeys = db.prepare(`SELECT key FROM rules WHERE kind = ?`).all(RULE_KIND);
+    const openQuestions = db.prepare(`SELECT context_json FROM questions WHERE kind = ?`).all(RULE_KIND);
+    const keys = new Set(ruleKeys.map((r) => r.key));
+    for (const q of openQuestions) {
+        if (!q.context_json)
+            continue;
+        try {
+            const parsed = JSON.parse(q.context_json);
+            if (typeof parsed?.rule_key === "string")
+                keys.add(parsed.rule_key);
+        }
+        catch {
+            // malformed context — ignore; the question already exists, generation
+            // wouldn't dedupe it anyway, so the worst case is a duplicate.
+        }
+    }
+    return keys;
+}
+function buildPrompt(c) {
+    const amountStr = formatAmount(c.amount, c.currency);
+    const sideLabel = c.side === "debit" ? "outflow" : "inflow";
+    return (`${c.transactions.length} ${sideLabel}s on \`${c.account_id}\` of ${amountStr} ` +
+        `every ~${c.median_days_between} days (looks ${c.implied_frequency}). ` +
+        `Link them as a recurring item?`);
+}