plasalid 0.6.10 → 0.7.0

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

@@ -34,6 +34,7 @@ export interface PostingRow {
     transaction_date?: string;
     transaction_description?: string;
     merchant_name?: string | null;
+    transaction_recurrence_id?: string | null;
 }
 /**
  * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
@@ -42,9 +43,10 @@ export interface PostingRow {
  */
 export declare function recordTransaction(db: Database.Database, input: TransactionInput): string;
 /**
- * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
- * both `recordTransaction` and the buffered-scan commit path; the latter
- * already runs inside its own transaction and must not open another.
+ * Validate structural invariants and assign an id. Pure (no DB writes).
+ * Balance equality is **not** checked here — `insertTransactionRows` closes any
+ * imbalance with an `equity:adjustments` posting at insert time, so callers
+ * can record whatever the source document (or the LLM) actually saw.
  */
 export declare function validateTransaction(input: TransactionInput): TransactionInput & {
     id: string;
@@ -52,7 +54,9 @@ export declare function validateTransaction(input: TransactionInput): Transactio
 /**
  * Insert-only counterpart to `recordTransaction`. The caller is responsible
  * for opening a transaction (or for accepting partial writes). Expects an
- * already-validated input from `validateTransaction`.
+ * already-validated input from `validateTransaction`. If the postings don't
+ * sum to zero, a closing entry on `equity:adjustments` is appended so the
+ * double-entry invariant always holds at the row level.
  */
 export declare function insertTransactionRows(db: Database.Database, input: TransactionInput & {
     id: string;
@@ -146,3 +150,23 @@ export interface FindCorrelatedTransactionsOptions {
  */
 export declare function findCorrelatedTransactions(db: Database.Database, opts?: FindCorrelatedTransactionsOptions): CorrelatedTransactionPair[];
 export declare function listPostings(db: Database.Database, opts?: ListPostingsOptions): PostingRow[];
+export interface TransactionGroup {
+    transaction_id: string;
+    date: string;
+    description: string;
+    merchant: string | null;
+    recurrence_id: string | null;
+    postings: PostingRow[];
+}
+/**
+ * Fold `listPostings` output into per-transaction groups, surfacing the header
+ * fields (date, description, merchant, recurrence) shared by every posting
+ * under that transaction. Assumes rows are already in transaction-id order —
+ * `listPostings` produces that ordering naturally via its `ORDER BY t.date DESC, t.id DESC`.
+ */
+export declare function groupByTransaction(postings: PostingRow[]): TransactionGroup[];
+export interface TransactionTotals {
+    transactions: number;
+    postings: number;
+}
+export declare function countTransactions(db: Database.Database): TransactionTotals;

package/dist/db/queries/transactions.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "crypto";
 import { upsertMerchant } from "./merchants.js";
-const TOLERANCE = 0.005;
+import { ensureStructuralAccount } from "./account-balance.js";
 /**
  * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
  * posting both debits and credits. Transaction-wrapped: postings never land
@@ -13,16 +13,15 @@ export function recordTransaction(db, input) {
     return validated.id;
 }
 /**
- * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
- * both `recordTransaction` and the buffered-scan commit path; the latter
- * already runs inside its own transaction and must not open another.
+ * Validate structural invariants and assign an id. Pure (no DB writes).
+ * Balance equality is **not** checked here — `insertTransactionRows` closes any
+ * imbalance with an `equity:adjustments` posting at insert time, so callers
+ * can record whatever the source document (or the LLM) actually saw.
  */
 export function validateTransaction(input) {
-    if (!input.postings || input.postings.length < 2) {
-        throw new Error("Transaction must contain at least two postings.");
+    if (!input.postings || input.postings.length < 1) {
+        throw new Error("Transaction must contain at least one posting.");
     }
-    let debitTotal = 0;
-    let creditTotal = 0;
     for (const p of input.postings) {
         const debit = p.debit ?? 0;
         const credit = p.credit ?? 0;
@@ -35,20 +34,18 @@ export function validateTransaction(input) {
         if (debit === 0 && credit === 0) {
             throw new Error("Each posting must have either a debit or a credit.");
         }
-        debitTotal += debit;
-        creditTotal += credit;
-    }
-    if (Math.abs(debitTotal - creditTotal) > TOLERANCE) {
-        throw new Error(`Transaction does not balance: debits ${debitTotal.toFixed(2)} vs credits ${creditTotal.toFixed(2)}.`);
     }
     return { ...input, id: input.id ?? `tx:${randomUUID()}` };
 }
 /**
  * Insert-only counterpart to `recordTransaction`. The caller is responsible
  * for opening a transaction (or for accepting partial writes). Expects an
- * already-validated input from `validateTransaction`.
+ * already-validated input from `validateTransaction`. If the postings don't
+ * sum to zero, a closing entry on `equity:adjustments` is appended so the
+ * double-entry invariant always holds at the row level.
  */
 export function insertTransactionRows(db, input) {
+    const postings = balanceWithAdjustment(db, input.postings);
     let merchantId = input.merchant_id ?? null;
     if (!merchantId && input.merchant) {
         merchantId = upsertMerchant(db, input.merchant).id;
@@ -57,10 +54,33 @@ export function insertTransactionRows(db, input) {
      VALUES (?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.date, input.description, merchantId, input.raw_descriptor ?? null, input.source_file_id ?? null, input.source_page ?? null);
     const insertPosting = db.prepare(`INSERT INTO postings (id, transaction_id, account_id, debit, credit, currency, memo, pii_flag)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
-    for (const p of input.postings) {
+    for (const p of postings) {
         insertPosting.run(`p:${randomUUID()}`, input.id, p.account_id, p.debit ?? 0, p.credit ?? 0, p.currency || "THB", p.memo ?? null, p.pii_flag ? 1 : 0);
     }
 }
+/**
+ * If the postings don't tie, append a closing entry on `equity:adjustments`.
+ * Sums in integer cents to avoid float drift — no tolerance constant needed.
+ * Returns the original list when already balanced.
+ */
+function balanceWithAdjustment(db, postings) {
+    let debitCents = 0;
+    let creditCents = 0;
+    for (const p of postings) {
+        debitCents += Math.round((p.debit ?? 0) * 100);
+        creditCents += Math.round((p.credit ?? 0) * 100);
+    }
+    const diffCents = debitCents - creditCents;
+    if (diffCents === 0)
+        return postings;
+    ensureStructuralAccount(db, "equity:adjustments");
+    const amount = Math.abs(diffCents) / 100;
+    const currency = postings[0]?.currency || "THB";
+    const adjustment = diffCents > 0
+        ? { account_id: "equity:adjustments", credit: amount, currency }
+        : { account_id: "equity:adjustments", debit: amount, currency };
+    return [...postings, adjustment];
+}
 export function updateTransaction(db, transactionId, fields) {
     const sets = [];
     const params = [];
@@ -308,6 +328,7 @@ export function listPostings(db, opts = {}) {
     return db.prepare(`SELECT p.id, p.transaction_id, p.account_id, p.debit, p.credit, p.currency, p.memo,
             a.name AS account_name, a.type AS account_type,
             t.date AS transaction_date, t.description AS transaction_description,
+            t.recurrence_id AS transaction_recurrence_id,
             m.canonical_name AS merchant_name
      FROM postings p
      JOIN transactions t ON t.id = p.transaction_id
@@ -317,3 +338,35 @@ export function listPostings(db, opts = {}) {
      ORDER BY t.date DESC, t.id DESC
      LIMIT ?`).all(...params, limit);
 }
+/**
+ * Fold `listPostings` output into per-transaction groups, surfacing the header
+ * fields (date, description, merchant, recurrence) shared by every posting
+ * under that transaction. Assumes rows are already in transaction-id order —
+ * `listPostings` produces that ordering naturally via its `ORDER BY t.date DESC, t.id DESC`.
+ */
+export function groupByTransaction(postings) {
+    const groups = [];
+    let current = null;
+    for (const p of postings) {
+        if (!current || current.transaction_id !== p.transaction_id) {
+            current = {
+                transaction_id: p.transaction_id,
+                date: p.transaction_date ?? "",
+                description: p.transaction_description ?? "",
+                merchant: p.merchant_name ?? null,
+                recurrence_id: p.transaction_recurrence_id ?? null,
+                postings: [],
+            };
+            groups.push(current);
+        }
+        current.postings.push(p);
+    }
+    return groups;
+}
+export function countTransactions(db) {
+    const row = db
+        .prepare(`SELECT (SELECT COUNT(*) FROM transactions) AS transactions,
+              (SELECT COUNT(*) FROM postings)     AS postings`)
+        .get();
+    return row;
+}

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

@@ -8,6 +8,8 @@ export interface RecordUnknownInput extends UnknownTarget {
     kind?: string | null;
     prompt: string;
     options?: string[];
+    /** Kind-specific structured context (e.g. partner ids for similar_accounts). */
+    context?: Record<string, unknown> | null;
 }
 export interface OpenUnknownRow {
     id: string;
@@ -17,6 +19,7 @@ export interface OpenUnknownRow {
     kind: string | null;
     prompt: string;
     options_json: string | null;
+    context_json: string | null;
     created_at: string;
 }
 /**
@@ -37,11 +40,6 @@ export declare function resolveUnknown(db: Database.Database, id: string, answer
  * the unknown id doesn't exist.
  */
 export declare function getUnknownTarget(db: Database.Database, id: string): UnknownTarget | null;
-/**
- * Clear `has_unknown` on the named transaction / account if no other open
- * unknowns still reference it. Safe to call after any resolution; idempotent.
- */
-export declare function maybeClearHasUnknownFlags(db: Database.Database, target: UnknownTarget): void;
 export interface CountOpenUnknownsScope {
     file_id?: string;
     transaction_id?: string;

package/dist/db/queries/unknowns.js

@@ -7,7 +7,7 @@ import { randomUUID } from "crypto";
  */
 export function recordUnknown(db, input) {
     const id = `cn:${randomUUID()}`;
-    db.prepare(`INSERT INTO unknowns (id, file_id, transaction_id, account_id, kind, prompt, options_json) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null);
+    db.prepare(`INSERT INTO unknowns (id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null, input.context ? JSON.stringify(input.context) : null);
     if (input.transaction_id) {
         db.prepare(`UPDATE transactions SET has_unknown = 1 WHERE id = ?`).run(input.transaction_id);
     }
@@ -43,7 +43,7 @@ export function getUnknownTarget(db, id) {
  * Clear `has_unknown` on the named transaction / account if no other open
  * unknowns still reference it. Safe to call after any resolution; idempotent.
  */
-export function maybeClearHasUnknownFlags(db, target) {
+function maybeClearHasUnknownFlags(db, target) {
     if (target.transaction_id) {
         const open = db
             .prepare(`SELECT 1 FROM unknowns WHERE transaction_id = ? AND resolved_at IS NULL LIMIT 1`)
@@ -85,7 +85,7 @@ export function countOpenUnknowns(db, scope = {}) {
 }
 export function listOpenUnknowns(db, limit = 50) {
     const capped = Math.min(Math.max(limit, 1), 200);
-    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, created_at
+    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
      FROM unknowns
      WHERE resolved_at IS NULL
      ORDER BY created_at ASC
@@ -106,7 +106,7 @@ export function listOpenUnknownsByKind(db, kinds, limit = 50) {
     const capped = Math.min(Math.max(limit, 1), 200);
     const placeholders = kinds.map(() => "?").join(",");
     const cases = kinds.map((_, i) => `WHEN ? THEN ${i}`).join(" ");
-    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, created_at
+    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
      FROM unknowns
      WHERE resolved_at IS NULL AND kind IN (${placeholders})
      ORDER BY CASE kind ${cases} ELSE ${kinds.length} END, created_at ASC

package/dist/db/schema.js

@@ -106,6 +106,7 @@ export function migrate(db) {
       kind TEXT,
       prompt TEXT NOT NULL,
       options_json TEXT,
+      context_json TEXT,
       answer TEXT,
       resolved_at TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
@@ -157,4 +158,11 @@ export function migrate(db) {
     CREATE INDEX IF NOT EXISTS action_log_correlation_idx ON action_log(correlation_id);
     CREATE INDEX IF NOT EXISTS action_log_created_idx ON action_log(created_at);
   `);
+    ensureColumn(db, "unknowns", "context_json", "TEXT");
+}
+function ensureColumn(db, table, column, type) {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (cols.some((c) => c.name === column))
+        return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
 }

package/dist/lib/runPasses.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic "drive a loop with named hooks" helper.
+ *
+ * The driver owns counting passes, stall detection, and the iteration cap.
+ * Everything else (work performed each pass, what to print when, how to react
+ * to stall vs success vs failure) lives in the hooks the caller supplies.
+ *
+ * The state `S` is whatever quantity decides "are we done?" — typically a
+ * remaining-work count, but it can be any value you can compare.
+ */
+export interface RunPassesOpts<S> {
+    /** Initial state (e.g. `countOpenUnknowns(db)`). */
+    initial: S;
+    /** Maximum number of passes before declaring failure. Must be >= 1. */
+    maxAttempts: number;
+    /** True when the work is finished and the loop should stop cleanly. */
+    isDone: (state: S) => boolean;
+    /**
+     * True when this pass made no progress vs the previous pass. Fires after
+     * the first pass at the earliest.
+     */
+    isStalled: (curr: S, prev: S) => boolean;
+    /** Run one pass; return the new state. Pass numbers are 1-indexed. */
+    onPass: (pass: number, state: S) => Promise<S>;
+    onStart?: (state: S) => void;
+    onStall?: (state: S) => void;
+    onSuccess?: (state: S) => void;
+    onFail?: (state: S) => void;
+}
+export declare function runPasses<S>(opts: RunPassesOpts<S>): Promise<S>;

package/dist/lib/runPasses.js

@@ -0,0 +1,15 @@
+export async function runPasses(opts) {
+    let state = opts.initial;
+    let prev = state;
+    opts.onStart?.(state);
+    for (let pass = 1; pass <= opts.maxAttempts && !opts.isDone(state); pass++) {
+        if (pass > 1 && opts.isStalled(state, prev)) {
+            opts.onStall?.(state);
+            return state;
+        }
+        prev = state;
+        state = await opts.onPass(pass, state);
+    }
+    (opts.isDone(state) ? opts.onSuccess : opts.onFail)?.(state);
+    return state;
+}

package/dist/resolver/pipeline.d.ts

@@ -3,14 +3,14 @@ export interface ResolveOptions {
     from?: string;
     to?: string;
     kind?: string;
-    interactive?: boolean;
-    /** Hard cap on unknowns handed to the agent in one run. Default 200. */
+    /** Hard cap on unknowns handed to the agent in one pass. Default 200. */
     limit?: number;
 }
 /**
- * Hand every open unknown to the resolve agent in a single invocation. The
- * agent surveys, applies memory-driven and heuristic resolutions silently,
- * groups what remains, asks the user once per group, and reports back via
- * mark_resolve_done. The pipeline just sets up plumbing and prints the report.
+ * Drain every open unknown by looping the resolve agent until the DB says
+ * we're done. Completion and stall detection both read from
+ * `countOpenUnknowns(db)` — the LLM has no "I'm done" signal; we trust state,
+ * not narration. The loop driver (`runPasses`) owns counting / cap / stall;
+ * the hooks below own everything else.
  */
 export declare function runResolve(opts?: ResolveOptions): Promise<string>;

package/dist/resolver/pipeline.js

@@ -1,38 +1,66 @@
+import chalk from "chalk";
 import { getDb } from "../db/connection.js";
 import { runResolveAgent } from "../ai/agent.js";
-import { listOpenUnknowns, listOpenUnknownsByKind } from "../db/queries/unknowns.js";
+import { countOpenUnknowns, listOpenUnknowns, listOpenUnknownsByKind, } from "../db/queries/unknowns.js";
 import { statusSpinner, makePromptUser, makeAgentOnProgress, } from "../cli/ux.js";
+import { runPasses } from "../lib/runPasses.js";
 import { buildResolveUserMessage } from "./prompts.js";
+const MAX_PASSES = 3;
 /**
- * Hand every open unknown to the resolve agent in a single invocation. The
- * agent surveys, applies memory-driven and heuristic resolutions silently,
- * groups what remains, asks the user once per group, and reports back via
- * mark_resolve_done. The pipeline just sets up plumbing and prints the report.
+ * Drain every open unknown by looping the resolve agent until the DB says
+ * we're done. Completion and stall detection both read from
+ * `countOpenUnknowns(db)` — the LLM has no "I'm done" signal; we trust state,
+ * not narration. The loop driver (`runPasses`) owns counting / cap / stall;
+ * the hooks below own everything else.
  */
 export async function runResolve(opts = {}) {
     const db = getDb();
-    const unknowns = opts.kind
-        ? listOpenUnknownsByKind(db, [opts.kind], opts.limit ?? 200)
-        : listOpenUnknowns(db, opts.limit ?? 200);
-    if (unknowns.length === 0)
-        return "No open unknowns.";
-    const interactive = opts.interactive ?? true;
-    const spinner = statusSpinner(`Resolving ${unknowns.length} unknown(s)...`);
-    const promptUser = interactive ? makePromptUser(spinner) : undefined;
-    let summary = "";
+    const scope = opts.kind ? { kind: opts.kind } : {};
+    const startOpen = countOpenUnknowns(db, scope);
+    if (startOpen === 0)
+        return "No unknowns to resolve.";
+    const spinner = statusSpinner(`Resolving ${startOpen} unknown(s)...`);
+    const promptUser = makePromptUser(spinner);
+    const onProgress = makeAgentOnProgress(spinner);
     try {
-        await runResolveAgent({
-            db,
-            prompt: { accountId: opts.accountId, from: opts.from, to: opts.to },
-            initialMessages: [{ role: "user", content: buildResolveUserMessage(unknowns) }],
-            agentCtx: { interactive, promptUser, onComplete: (s) => { summary = s; } },
-            onProgress: makeAgentOnProgress(spinner),
+        const finalOpen = await runPasses({
+            initial: startOpen,
+            maxAttempts: MAX_PASSES,
+            isDone: (open) => open === 0,
+            isStalled: (curr, prev) => curr >= prev,
+            onPass: async (pass, open) => {
+                spinner.text = `Resolving ${open} unknown(s) — pass ${pass}...`;
+                await runResolveAgent({
+                    db,
+                    prompt: { accountId: opts.accountId, from: opts.from, to: opts.to },
+                    initialMessages: [
+                        { role: "user", content: buildResolveUserMessage(listFor(db, opts, scope)) },
+                    ],
+                    agentCtx: { interactive: true, promptUser },
+                    onProgress,
+                });
+                return countOpenUnknowns(db, scope);
+            },
+            onStall: (open) => spinner.info(`Resolve made no progress (${open} left). Re-run \`plasalid resolve\` or inspect the data.`),
+            onSuccess: () => spinner.succeed("Resolve done."),
+            onFail: (open) => spinner.fail(`Resolve left ${open} unknown(s) open after ${MAX_PASSES} pass(es).`),
         });
-        spinner.succeed("Resolve done.");
+        return summarize(startOpen, finalOpen);
     }
     catch (err) {
         spinner.fail(`Resolve failed: ${err.message}`);
         throw err;
     }
-    return summary;
+}
+function listFor(db, opts, scope) {
+    const limit = opts.limit ?? 200;
+    return scope.kind
+        ? listOpenUnknownsByKind(db, [scope.kind], limit)
+        : listOpenUnknowns(db, limit);
+}
+function summarize(startOpen, stillOpen) {
+    const resolved = startOpen - stillOpen;
+    if (stillOpen === 0)
+        return chalk.green(`Resolved ${resolved} unknown(s).`);
+    return chalk.yellow(`Resolved ${resolved} of ${startOpen}; ${stillOpen} still open.`);
 }

package/dist/scanner/inspectors/similarities.js

@@ -24,42 +24,40 @@ function inspect(db, scope) {
             transaction_id: null,
             account_id: pair.a.id,
             kind: "similar_accounts",
-            prompt: `These two accounts look like the same thing (similarity ${pair.similarity}):\n  ${pair.a.id} — ${pair.a.name}\n  ${pair.b.id} — ${pair.b.name}`,
+            prompt: `These two accounts look like the same thing:\n  ${pair.a.name}\n  ${pair.b.name}`,
             options: [
-                `Merge ${pair.b.id} into ${pair.a.id}`,
-                `Merge ${pair.a.id} into ${pair.b.id}`,
+                `Merge ${pair.b.name} into ${pair.a.name}`,
+                `Merge ${pair.a.name} into ${pair.b.name}`,
                 "Keep separate",
                 "Skip",
             ],
+            context: { otherAccountId: pair.b.id },
         });
     }
     return out;
 }
 /**
- * `similar_accounts` unknowns (open OR resolved) embed the other account's id
- * in their options strings ("Merge X into Y"). Parse those out so we don't
- * re-flag a pair the user has already seen — including pairs they've already
- * answered "Keep separate" on a prior run.
+ * `similar_accounts` unknowns store the partner account id in `context_json`
+ * (`{otherAccountId}`); the row's own `account_id` is one half of the pair.
+ * Read both to skip pairs the user has already seen — including ones answered
+ * "Keep separate" on a prior run.
  */
 function loadAlreadyFlaggedAccountPairs(db) {
     const rows = db
-        .prepare(`SELECT account_id, options_json FROM unknowns
+        .prepare(`SELECT account_id, context_json FROM unknowns
        WHERE kind = 'similar_accounts' AND account_id IS NOT NULL`)
         .all();
     const out = new Set();
     for (const row of rows) {
-        if (!row.options_json)
+        if (!row.context_json)
             continue;
         try {
-            const options = JSON.parse(row.options_json);
-            for (const opt of options) {
-                const match = opt.match(/Merge (\S+) into (\S+)/);
-                if (match)
-                    out.add(pairKey(match[1], match[2]));
-            }
+            const ctx = JSON.parse(row.context_json);
+            if (ctx.otherAccountId)
+                out.add(pairKey(row.account_id, ctx.otherAccountId));
         }
         catch {
-            // skip malformed options_json
+            // skip malformed context_json
         }
     }
     return out;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "plasalid",
-  "version": "0.6.10",
+  "version": "0.7.0",
   "description": "Plasalid — The Harness Layer for Personal Finance",
   "keywords": [
     "finance",
     "harness",
-    "personal-finance",
+    "personal",
     "aggregator",
     "parser",
     "cli",