plasalid 0.7.1 → 0.7.3

package/dist/scanner/result.js

@@ -0,0 +1,19 @@
+/**
+ * Lightweight Result helpers shared across scanner subdomains. Use this
+ * instead of inline try/catch when a function can fail with a human-readable
+ * reason and the caller needs to branch on the outcome (decrypt, chunk parse,
+ * commit-one-transaction). Distinct from concurrency.ts `Settled<T>` — that
+ * type is owned by `runWithConcurrency` and includes an `error: unknown`;
+ * `Result<T>` stringifies the error up front for ergonomic message handling.
+ */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function tryExecute(fn) {
+    try {
+        return { ok: true, value: await fn() };
+    }
+    catch (err) {
+        return { ok: false, error: errorMessage(err) };
+    }
+}

package/dist/scanner/run-passes.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/scanner/run-passes.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/scanner/unlock.js

@@ -115,7 +115,7 @@ export function persistUnlockOutcome(db, filePath, outcome) {
             spinner.succeed(`Saved password for pattern ${pattern} in secure vault.`);
         }
         catch (err) {
-            spinner.fail(`Could not save password: ${err.message}`);
+            spinner.fail(`Could not save password: ${err instanceof Error ? err.message : String(err)}`);
             throw err;
         }
     }

package/dist/scanner/worker.d.ts

@@ -0,0 +1,19 @@
+import type Database from "libsql";
+import type { Chunk } from "./engine.js";
+import type { ScanHooks } from "./hooks.js";
+import type { ScanProgress } from "./progress.js";
+export interface ScanWorkerDeps {
+    readonly db: Database.Database;
+    readonly scanId: string;
+    readonly scannedFileId: string | undefined;
+    readonly progress: ScanProgress;
+    readonly chunk: Chunk;
+}
+/**
+ * Process one chunk: run the LLM scan agent over a single-page PDF blob with
+ * scanId + progress sink + scanned_files row injected through the agent
+ * context. Agent's record_transactions / note_question calls write directly to
+ * the DB; per-row ticks fan out via `progress.emit`. Failures land in the DB
+ * as a `chunk_failed` question so the clarifier can pick them up.
+ */
+export declare function runScanWorker(deps: ScanWorkerDeps, hooks: ScanHooks): Promise<void>;

package/dist/scanner/worker.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "crypto";
+import { runScanAgent } from "../ai/agent.js";
+import { recordQuestion } from "../db/queries/questions.js";
+import { buildDocumentBlock } from "./pdf/pdf.js";
+import { tryExecute } from "./result.js";
+/**
+ * Process one chunk: run the LLM scan agent over a single-page PDF blob with
+ * scanId + progress sink + scanned_files row injected through the agent
+ * context. Agent's record_transactions / note_question calls write directly to
+ * the DB; per-row ticks fan out via `progress.emit`. Failures land in the DB
+ * as a `chunk_failed` question so the clarifier can pick them up.
+ */
+export async function runScanWorker(deps, hooks) {
+    const workerId = `cw:${randomUUID()}`;
+    hooks.onWorkerStart?.(workerId, deps.chunk);
+    const outcome = await tryExecute(() => runScanAgent({
+        db: deps.db,
+        initialMessages: [
+            {
+                role: "user",
+                content: [
+                    buildDocumentBlock(deps.chunk.bytes, deps.chunk.fileName, deps.chunk.mime),
+                    { type: "text", text: buildChunkPrompt(deps.chunk) },
+                ],
+            },
+        ],
+        prompt: { fileName: deps.chunk.fileName },
+        agentCtx: {
+            interactive: false,
+            scanId: deps.scanId,
+            fileId: deps.scannedFileId,
+            chunkId: deps.chunk.chunkId,
+            progress: deps.progress,
+        },
+    }));
+    hooks.onWorkerEnd?.(workerId, deps.chunk, outcome.ok);
+    if (!outcome.ok)
+        recordChunkFailure(deps, outcome.error);
+}
+function recordChunkFailure(deps, error) {
+    try {
+        recordQuestion(deps.db, {
+            file_id: deps.scannedFileId ?? null,
+            scan_id: deps.scanId,
+            transaction_id: null,
+            account_id: null,
+            kind: "chunk_failed",
+            prompt: `Chunk ${deps.chunk.fileName} p${deps.chunk.pageNumber} failed to parse: ${error}.`,
+        });
+        deps.progress.emit({ chunkId: deps.chunk.chunkId, kind: "question" });
+    }
+    catch {
+        // failure to record a failure shouldn't crash the file worker
+    }
+}
+function buildChunkPrompt(chunk) {
+    return [
+        `You are parsing page ${chunk.pageNumber} of ${chunk.totalPages} of ${chunk.fileName}.`,
+        ``,
+        `Steps:`,
+        `1. Call list_accounts to see what already exists.`,
+        `2. If this page reveals an account that isn't in the chart yet, call create_account once.`,
+        `3. For every transaction on this page, call record_transactions (plural) with all rows in one batch.`,
+        `4. If the first or last row looks incomplete (no date, or no amount column visible — the row likely continues onto an adjacent page), call note_question with kind="boundary_continuation" and the raw row text. Do NOT invent missing fields.`,
+        `5. When done with this page, call mark_file_scanned with a short summary.`,
+    ].join("\n");
+}

package/dist/scanner/workers/chunkWorker.d.ts

@@ -0,0 +1,20 @@
+import type Database from "libsql";
+import type { ScanBuffer } from "../buffer/types.js";
+import type { Chunk, ScanHooks } from "../engine/types.js";
+export interface ChunkWorkerDeps {
+    readonly db: Database.Database;
+    readonly buffer: ScanBuffer;
+    readonly chunk: Chunk;
+}
+export interface ChunkWorkerResult {
+    readonly workerId: string;
+    readonly ok: boolean;
+    readonly error?: string;
+}
+/**
+ * Process one chunk: run the LLM scan agent over a single-page PDF blob with
+ * the shared Buffer + chunkId injected. The agent's `record_transactions`
+ * calls land in the shared buffer; events fan out to the auditor and the
+ * dashboard.
+ */
+export declare function runChunkWorker(deps: ChunkWorkerDeps, hooks: ScanHooks): Promise<ChunkWorkerResult>;

package/dist/scanner/workers/chunkWorker.js

@@ -0,0 +1,65 @@
+import { randomUUID } from "crypto";
+import { runScanAgent } from "../../ai/agent.js";
+import { buildDocumentBlock } from "../pdf.js";
+/**
+ * Process one chunk: run the LLM scan agent over a single-page PDF blob with
+ * the shared Buffer + chunkId injected. The agent's `record_transactions`
+ * calls land in the shared buffer; events fan out to the auditor and the
+ * dashboard.
+ */
+export async function runChunkWorker(deps, hooks) {
+    const workerId = `cw:${randomUUID()}`;
+    hooks.onWorkerStart?.(workerId, deps.chunk);
+    const outcome = await tryParseChunk(deps);
+    hooks.onWorkerEnd?.(workerId, deps.chunk, outcome.ok);
+    if (!outcome.ok)
+        await recordChunkFailure(deps.buffer, deps.chunk, outcome.error);
+    return { workerId, ...outcome };
+}
+async function tryParseChunk(deps) {
+    try {
+        await runScanAgent({
+            db: deps.db,
+            initialMessages: [
+                {
+                    role: "user",
+                    content: [
+                        buildDocumentBlock(deps.chunk.bytes, deps.chunk.fileName, deps.chunk.mime),
+                        { type: "text", text: buildChunkPrompt(deps.chunk) },
+                    ],
+                },
+            ],
+            prompt: { fileName: deps.chunk.fileName },
+            agentCtx: {
+                interactive: false,
+                buffer: deps.buffer,
+                chunkId: deps.chunk.chunkId,
+            },
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function recordChunkFailure(buffer, chunk, error) {
+    await buffer.appendUnknown({
+        chunkId: chunk.chunkId,
+        transaction_id: null,
+        account_id: null,
+        kind: "chunk_failed",
+        prompt: `Chunk ${chunk.fileName} p${chunk.pageNumber} failed to parse: ${error}.`,
+    });
+}
+function buildChunkPrompt(chunk) {
+    return [
+        `You are parsing page ${chunk.pageNumber} of ${chunk.totalPages} of ${chunk.fileName}.`,
+        ``,
+        `Steps:`,
+        `1. Call list_accounts to see what already exists.`,
+        `2. If this page reveals an account that isn't in the chart yet, call create_account once.`,
+        `3. For every transaction on this page, call record_transactions (plural) with all rows in one batch.`,
+        `4. If the first or last row looks incomplete (no date, or no amount column visible — the row likely continues onto an adjacent page), call note_unknown with kind="boundary_continuation" and the raw row text. Do NOT invent missing fields.`,
+        `5. When done with this page, call mark_file_scanned with a short summary.`,
+    ].join("\n");
+}

package/dist/scanner/workers/fileWorker.d.ts

@@ -0,0 +1,32 @@
+import type Database from "libsql";
+import { type ChunkWorkerDeps, type ChunkWorkerResult } from "./chunkWorker.js";
+import type { ScanBuffer } from "../buffer/types.js";
+import type { Chunk, ScanHooks } from "../engine/types.js";
+/**
+ * Strategy hook — pluggable parser for one chunk. Default is the LLM-driven
+ * runChunkWorker; tests and alternate flows (OCR-only, mock, dry-run) inject
+ * their own without modifying the file worker. Open for extension; closed
+ * for modification.
+ */
+export type ChunkWorkerFn = (deps: ChunkWorkerDeps, hooks: ScanHooks) => Promise<ChunkWorkerResult>;
+export interface FileWorkerDeps {
+    readonly db: Database.Database;
+    readonly buffer: ScanBuffer;
+    readonly fileId: string;
+    readonly chunks: readonly Chunk[];
+    readonly maxChunkWorkers: number;
+    /** Optional override; defaults to the LLM-backed runChunkWorker. */
+    readonly chunkWorkerFn?: ChunkWorkerFn;
+}
+export interface FileWorkerResult {
+    readonly workerId: string;
+    readonly fileId: string;
+    readonly ok: number;
+    readonly failed: number;
+}
+/**
+ * Process every chunk of one file in parallel up to `maxChunkWorkers`. The
+ * shared buffer + bus are dependency-injected; this function has no global
+ * state and never reaches outside its args.
+ */
+export declare function runFileWorker(deps: FileWorkerDeps, hooks: ScanHooks): Promise<FileWorkerResult>;

package/dist/scanner/workers/fileWorker.js

@@ -0,0 +1,22 @@
+import { randomUUID } from "crypto";
+import { runWithConcurrency } from "../concurrency.js";
+import { runChunkWorker } from "./chunkWorker.js";
+/**
+ * Process every chunk of one file in parallel up to `maxChunkWorkers`. The
+ * shared buffer + bus are dependency-injected; this function has no global
+ * state and never reaches outside its args.
+ */
+export async function runFileWorker(deps, hooks) {
+    const workerId = `fw:${randomUUID()}`;
+    const chunkFn = deps.chunkWorkerFn ?? runChunkWorker;
+    const tasks = deps.chunks.map(chunk => () => chunkFn({ db: deps.db, buffer: deps.buffer, chunk }, hooks));
+    const settled = await runWithConcurrency(tasks, deps.maxChunkWorkers);
+    let ok = 0, failed = 0;
+    for (const r of settled) {
+        if (!r.ok || !r.value.ok)
+            failed++;
+        else
+            ok++;
+    }
+    return { workerId, fileId: deps.fileId, ok, failed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plasalid",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Plasalid — The Harness Layer for Personal Finance",
   "keywords": [
     "finance",