plasalid 0.7.0 → 0.7.2

package/dist/scanner/chunker/chunker.js

@@ -0,0 +1,60 @@
+let mupdfPromise = null;
+function getMupdf() {
+    if (!mupdfPromise)
+        mupdfPromise = import("mupdf");
+    return mupdfPromise;
+}
+/**
+ * Build one Chunk holding exactly page `pageIndex` of `file`. mupdf has no
+ * native page-range extract, so we clone the source doc and delete every
+ * other page, back-to-front so indices stay stable as we splice. Resource
+ * lifetime is contained in the try/finally so a saveToBuffer failure can't
+ * leak the cloned doc.
+ */
+async function extractPage(file, pageIndex, pageCount) {
+    const mupdf = await getMupdf();
+    const clone = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    try {
+        for (let j = pageCount - 1; j >= 0; j--) {
+            if (j !== pageIndex)
+                clone.deletePage(j);
+        }
+        const out = clone.saveToBuffer("decrypt");
+        return {
+            chunkId: `${file.path}#p${pageIndex + 1}`,
+            fileId: file.path,
+            fileName: file.fileName,
+            relPath: file.relPath,
+            pageNumber: pageIndex + 1,
+            totalPages: pageCount,
+            bytes: Buffer.from(out.asUint8Array()),
+            mime: file.mime,
+        };
+    }
+    finally {
+        clone.destroy();
+    }
+}
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export async function chunkPdf(file) {
+    const mupdf = await getMupdf();
+    const probe = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    let pageCount;
+    try {
+        pageCount = probe.countPages();
+    }
+    finally {
+        probe.destroy();
+    }
+    if (pageCount <= 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < pageCount; i++) {
+        chunks.push(await extractPage(file, i, pageCount));
+    }
+    return chunks;
+}

package/dist/scanner/chunker.d.ts

@@ -0,0 +1,7 @@
+import type { Chunk, DecryptedFile } from "./engine.js";
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export declare function chunkPdf(file: DecryptedFile): Promise<Chunk[]>;

package/dist/scanner/chunker.js

@@ -0,0 +1,60 @@
+let mupdfPromise = null;
+function getMupdf() {
+    if (!mupdfPromise)
+        mupdfPromise = import("mupdf");
+    return mupdfPromise;
+}
+/**
+ * Build one Chunk holding exactly page `pageIndex` of `file`. mupdf has no
+ * native page-range extract, so we clone the source doc and delete every
+ * other page, back-to-front so indices stay stable as we splice. Resource
+ * lifetime is contained in the try/finally so a saveToBuffer failure can't
+ * leak the cloned doc.
+ */
+async function extractPage(file, pageIndex, pageCount) {
+    const mupdf = await getMupdf();
+    const clone = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    try {
+        for (let j = pageCount - 1; j >= 0; j--) {
+            if (j !== pageIndex)
+                clone.deletePage(j);
+        }
+        const out = clone.saveToBuffer("decrypt");
+        return {
+            chunkId: `${file.path}#p${pageIndex + 1}`,
+            fileId: file.path,
+            fileName: file.fileName,
+            relPath: file.relPath,
+            pageNumber: pageIndex + 1,
+            totalPages: pageCount,
+            bytes: Buffer.from(out.asUint8Array()),
+            mime: file.mime,
+        };
+    }
+    finally {
+        clone.destroy();
+    }
+}
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export async function chunkPdf(file) {
+    const mupdf = await getMupdf();
+    const probe = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    let pageCount;
+    try {
+        pageCount = probe.countPages();
+    }
+    finally {
+        probe.destroy();
+    }
+    if (pageCount <= 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < pageCount; i++) {
+        chunks.push(await extractPage(file, i, pageCount));
+    }
+    return chunks;
+}

package/dist/scanner/converge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Drive a stateful loop toward convergence: keep running passes until the
+ * caller's `isDone` predicate is true (success), `isStalled` returns true
+ * across two passes (stall), or `maxAttempts` is exhausted (fail).
+ *
+ * The driver owns counting passes, stall detection, and the iteration cap.
+ * Everything else (work per pass, callbacks per terminal state) lives in the
+ * hooks the caller supplies. `S` is whatever quantity decides "are we done?".
+ */
+export interface ConvergeOpts<S> {
+    /** Initial state (e.g. `countQuestions(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 converge<S>(opts: ConvergeOpts<S>): Promise<S>;

package/dist/scanner/converge.js

@@ -0,0 +1,15 @@
+export async function converge(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/decrypt.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "./engine.js";
+import type { ScanHooks } from "./hooks.js";
+/**
+ * Phase 1 — walk the data dir, optionally filter by regex, decrypt each file
+ * sequentially (password prompts can't share a TTY). Output partitions into
+ * decrypted / skipped / failed via a kind-keyed dispatch map. Bootstrapped
+ * scanned_files rows are tagged onto each DecryptedFile.
+ */
+export declare function decryptPhase(db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/decrypt.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "crypto";
+import { readPdf } from "./pdf/pdf.js";
+import { unlockIfNeeded, persistUnlockOutcome } from "./pdf/unlock.js";
+import { scanDataDir } from "./walker.js";
+import { tryExecute } from "./result.js";
+function findScannedByHash(db, hash) {
+    return db
+        .prepare(`SELECT id FROM scanned_files WHERE file_hash = ?`)
+        .get(hash) ?? null;
+}
+async function decryptOne(db, file, opts) {
+    const read = await tryExecute(() => readPdf(file.path));
+    if (!read.ok)
+        return { kind: "failed", error: `read failed: ${read.error}` };
+    const pdf = read.value;
+    const existing = findScannedByHash(db, pdf.hash);
+    if (existing && !opts.force) {
+        return { kind: "skipped", existingScannedFileId: existing.id };
+    }
+    const unlock = await tryExecute(() => unlockIfNeeded({
+        db,
+        filePath: file.path,
+        bytes: pdf.bytes,
+        interactive: opts.interactive,
+    }));
+    if (!unlock.ok)
+        return { kind: "failed", error: unlock.error || "unlock failed" };
+    persistUnlockOutcome(db, file.path, unlock.value.outcome);
+    return {
+        kind: "decrypted",
+        file: {
+            path: file.path,
+            fileName: file.name,
+            relPath: file.relPath,
+            hash: pdf.hash,
+            mime: pdf.mime,
+            decryptedBytes: unlock.value.decrypted,
+            replacesPriorScannedFileId: existing?.id,
+        },
+    };
+}
+const APPLY = {
+    decrypted: (state, _file, o) => { state.decrypted.push(o.file); },
+    skipped: (state, file, o) => { state.skipped.push({ file, existingScannedFileId: o.existingScannedFileId }); },
+    failed: (state, file, o) => { state.failed.push({ file, error: o.error }); },
+};
+/**
+ * Bootstrap one scanned_files row per decrypted file. Chunk workers later
+ * stamp transactions with source_file_id, so the row must exist before any
+ * tool writes hit the DB. Status flips to 'scanned' after parse completes.
+ */
+function bootstrapScannedFiles(db, state) {
+    for (const file of state.decrypted) {
+        if (file.replacesPriorScannedFileId) {
+            db.prepare(`DELETE FROM scanned_files WHERE id = ?`).run(file.replacesPriorScannedFileId);
+        }
+        const sfId = `sf:${randomUUID()}`;
+        db.prepare(`INSERT INTO scanned_files (id, path, file_hash, mime, status) VALUES (?, ?, ?, ?, 'pending')`).run(sfId, file.path, file.hash, file.mime);
+        file.scannedFileId = sfId;
+    }
+}
+/**
+ * Phase 1 — walk the data dir, optionally filter by regex, decrypt each file
+ * sequentially (password prompts can't share a TTY). Output partitions into
+ * decrypted / skipped / failed via a kind-keyed dispatch map. Bootstrapped
+ * scanned_files rows are tagged onto each DecryptedFile.
+ */
+export async function decryptPhase(db, state, hooks) {
+    await hooks.beforeDecrypt?.(state);
+    const matcher = state.options.regex ? new RegExp(state.options.regex, "i") : null;
+    state.files = scanDataDir().filter(f => (matcher ? matcher.test(f.relPath) : true));
+    const interactive = state.options.interactive ?? true;
+    const force = !!state.options.force;
+    for (const file of state.files) {
+        const outcome = await decryptOne(db, file, { force, interactive });
+        APPLY[outcome.kind](state, file, outcome);
+    }
+    bootstrapScannedFiles(db, state);
+    await hooks.afterDecrypt?.(state);
+}

package/dist/scanner/engine/scanEngine.d.ts

@@ -0,0 +1,24 @@
+import type Database from "libsql";
+import type { CommitOutcome, Phase, PhaseName, RunScanOptions, ScanState } from "./types.js";
+import type { ScanHooks } from "../hooks/types.js";
+export interface ScanResult {
+    readonly scanId: string;
+    readonly state: ScanState;
+    readonly committed: CommitOutcome | null;
+    readonly aborted: boolean;
+}
+export declare const DEFAULT_PHASES: readonly {
+    name: PhaseName;
+    phase: Phase;
+}[];
+/**
+ * Composition root for a scan run. Builds the singleton subdomain instances
+ * (bus, buffer, audit engine) once, threads them through ScanState, then
+ * runs the phase chain. Auditor lifecycle wraps the whole chain so it sees
+ * every event from decrypt through commit.
+ *
+ * Per-run isolation: every call to runScan creates fresh instances. Nothing
+ * survives between scans.
+ */
+export declare function runScan(db: Database.Database, opts?: RunScanOptions, hooks?: ScanHooks): Promise<ScanResult>;
+export type { ScanState, ScanHooks, RunScanOptions, CommitOutcome, } from "./types.js";

package/dist/scanner/engine/scanEngine.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "crypto";
+import { createBus } from "../bus/engine.js";
+import { createBuffer } from "../buffer/engine.js";
+import { createAuditEngine } from "../audit/engine.js";
+import { AUDIT_PASSES } from "../audit/passes/index.js";
+import { decryptPhase } from "../phases/decrypt.js";
+import { chunkPhase } from "../phases/chunk.js";
+import { parsePhase } from "../phases/parse.js";
+import { reviewPhase } from "../phases/review.js";
+import { commitPhase } from "../phases/commit.js";
+export const DEFAULT_PHASES = [
+    { name: "decrypt", phase: decryptPhase },
+    { name: "chunk", phase: chunkPhase },
+    { name: "parse", phase: parsePhase },
+    { name: "review", phase: reviewPhase },
+    { name: "commit", phase: commitPhase },
+];
+/**
+ * Composition root for a scan run. Builds the singleton subdomain instances
+ * (bus, buffer, audit engine) once, threads them through ScanState, then
+ * runs the phase chain. Auditor lifecycle wraps the whole chain so it sees
+ * every event from decrypt through commit.
+ *
+ * Per-run isolation: every call to runScan creates fresh instances. Nothing
+ * survives between scans.
+ */
+export async function runScan(db, opts = {}, hooks = {}) {
+    const scanId = `sc:${randomUUID()}`;
+    const bus = createBus();
+    const buffer = createBuffer(scanId, bus);
+    const audit = createAuditEngine({ db, bus, buffer, passes: AUDIT_PASSES });
+    const state = {
+        scanId,
+        startedAt: Date.now(),
+        options: opts,
+        buffer,
+        bus,
+        files: [],
+        decrypted: [],
+        skipped: [],
+        failed: [],
+        chunks: [],
+        review: null,
+        committed: null,
+        errors: [],
+        auditApplied: {},
+    };
+    await fire(hooks.onStart, state);
+    audit.start();
+    const phases = opts.phases ?? DEFAULT_PHASES;
+    let aborted = false;
+    try {
+        for (const { name, phase } of phases) {
+            try {
+                await phase(db, state, hooks);
+            }
+            catch (err) {
+                state.errors.push({ phase: name, error: err });
+                await fire(hooks.onError, err, name, state);
+                aborted = true;
+                break;
+            }
+            if (name === "review" && state.review === "abort") {
+                aborted = true;
+                break;
+            }
+        }
+    }
+    finally {
+        audit.stop();
+        for (const [name, count] of Object.entries(audit.tally)) {
+            state.auditApplied[name] = count;
+        }
+        await fire(hooks.onFinish, state);
+    }
+    return { scanId, state, committed: state.committed, aborted };
+}
+async function fire(fn, ...args) {
+    if (!fn)
+        return;
+    try {
+        await fn(...args);
+    }
+    catch (err) {
+        console.error(`[scan-engine hook] ${err.message}`);
+    }
+}

package/dist/scanner/engine/types.d.ts

@@ -0,0 +1,90 @@
+import type Database from "libsql";
+import type { ScannedFile } from "../walker.js";
+import type { ScanBuffer } from "../buffer/types.js";
+import type { Bus } from "../bus/types.js";
+export type MaybePromise<T> = T | Promise<T>;
+export interface Chunk {
+    readonly chunkId: string;
+    readonly fileId: string;
+    readonly fileName: string;
+    readonly relPath: string;
+    readonly pageNumber: number;
+    readonly totalPages: number;
+    readonly bytes: Buffer;
+    readonly mime: string;
+}
+export interface DecryptedFile {
+    readonly path: string;
+    readonly fileName: string;
+    readonly relPath: string;
+    readonly hash: string;
+    readonly mime: string;
+    readonly decryptedBytes: Buffer;
+    readonly replacesPriorScannedFileId?: string;
+}
+export interface SkippedFile {
+    readonly file: ScannedFile;
+    readonly existingScannedFileId: string;
+}
+export interface FailedFile {
+    readonly file: ScannedFile;
+    readonly error: string;
+}
+export interface PhaseError {
+    readonly phase: PhaseName;
+    readonly target?: string;
+    readonly error: unknown;
+}
+export type PhaseName = "decrypt" | "chunk" | "parse" | "review" | "commit";
+export type ReviewDecision = "commit" | "abort";
+export interface CommitOutcome {
+    readonly transactions: number;
+    readonly accounts: number;
+    readonly merchants: number;
+    readonly unknowns: number;
+    readonly scannedFileIds: readonly string[];
+}
+export interface RunScanOptions {
+    regex?: string;
+    force?: boolean;
+    interactive?: boolean;
+    /** Max FileWorkers running concurrently. Default 5, hard cap 8. */
+    maxFileWorkers?: number;
+    /** Max ChunkWorkers per FileWorker. Default 5, hard cap 8. */
+    maxChunkWorkersPerFile?: number;
+    review?: boolean;
+    autoCommit?: boolean;
+    /**
+     * Override the phase chain. Default = the five built-in phases. Extending
+     * tests / alternate flows (dry-run, OCR-only) inject their own without
+     * editing the engine. Open for extension; closed for modification.
+     */
+    phases?: ReadonlyArray<{
+        name: PhaseName;
+        phase: Phase;
+    }>;
+}
+/**
+ * The state object threaded through every phase. Phases mutate it in place;
+ * hooks read it. The buffer + bus are interfaces — the engine owns the
+ * factory instances and injects them here.
+ */
+export interface ScanState {
+    readonly scanId: string;
+    readonly startedAt: number;
+    readonly options: RunScanOptions;
+    readonly buffer: ScanBuffer;
+    readonly bus: Bus;
+    files: ScannedFile[];
+    decrypted: DecryptedFile[];
+    skipped: SkippedFile[];
+    failed: FailedFile[];
+    chunks: Chunk[];
+    review: ReviewDecision | null;
+    committed: CommitOutcome | null;
+    errors: PhaseError[];
+    auditApplied: Record<string, number>;
+}
+import type { ScanHooks } from "../hooks/types.js";
+export type Phase = (db: Database.Database, state: ScanState, hooks: ScanHooks) => Promise<void>;
+export type { ScanHooks } from "../hooks/types.js";

package/dist/scanner/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/scanner/engine.d.ts

@@ -0,0 +1,90 @@
+import type Database from "libsql";
+import type { ScannedFile } from "./walker.js";
+import type { ScanHooks } from "./hooks.js";
+import type { ScanProgress } from "./progress.js";
+import type { ResolveSummary } from "./resolver.js";
+export interface Chunk {
+    readonly chunkId: string;
+    readonly fileId: string;
+    readonly fileName: string;
+    readonly relPath: string;
+    readonly pageNumber: number;
+    readonly totalPages: number;
+    readonly bytes: Buffer;
+    readonly mime: string;
+}
+export interface DecryptedFile {
+    readonly path: string;
+    readonly fileName: string;
+    readonly relPath: string;
+    readonly hash: string;
+    readonly mime: string;
+    readonly decryptedBytes: Buffer;
+    readonly replacesPriorScannedFileId?: string;
+    /** scanned_files.id assigned in decryptPhase so scan-worker tools can stamp source_file_id. */
+    scannedFileId?: string;
+}
+export interface SkippedFile {
+    readonly file: ScannedFile;
+    readonly existingScannedFileId: string;
+}
+export interface FailedFile {
+    readonly file: ScannedFile;
+    readonly error: string;
+}
+export interface PhaseError {
+    readonly phase: PhaseName;
+    readonly target?: string;
+    readonly error: unknown;
+}
+export type PhaseName = "decrypt" | "chunk" | "parse" | "resolve";
+export interface RunScanOptions {
+    regex?: string;
+    force?: boolean;
+    interactive?: boolean;
+    /** Max files processed concurrently. Default 5, hard cap 8. */
+    maxFileWorkers?: number;
+    /** Max scan workers per file (one per chunk). Default 5, hard cap 8. */
+    maxScanWorkersPerFile?: number;
+    /**
+     * Override the phase chain. Default = the four built-ins. Tests and alternate
+     * flows (dry-run, OCR-only) inject their own without editing this file.
+     */
+    phases?: ReadonlyArray<{
+        name: PhaseName;
+        phase: Phase;
+    }>;
+}
+/**
+ * The state object threaded through every phase. Phases mutate it in place;
+ * hooks read it. `progress` is the single-consumer event sink scan-worker
+ * tools emit into; the CLI subscribes to drive the dashboard.
+ */
+export interface ScanState {
+    readonly scanId: string;
+    readonly startedAt: number;
+    readonly options: RunScanOptions;
+    readonly progress: ScanProgress;
+    files: ScannedFile[];
+    decrypted: DecryptedFile[];
+    skipped: SkippedFile[];
+    failed: FailedFile[];
+    chunks: Chunk[];
+    resolveSummary: ResolveSummary | null;
+    errors: PhaseError[];
+}
+export type Phase = (db: Database.Database, state: ScanState, hooks: ScanHooks) => Promise<void>;
+export interface ScanResult {
+    readonly scanId: string;
+    readonly state: ScanState;
+}
+export declare const DEFAULT_PHASES: readonly {
+    name: PhaseName;
+    phase: Phase;
+}[];
+/**
+ * Composition root. Builds the progress sink once per scan run, threads it
+ * through ScanState, then runs the phase chain. Nothing survives between
+ * scans.
+ */
+export declare function runScan(db: Database.Database, opts?: RunScanOptions, hooks?: ScanHooks): Promise<ScanResult>;

package/dist/scanner/engine.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "crypto";
+import { createProgress } from "./progress.js";
+import { decryptPhase } from "./decrypt.js";
+import { parsePhase } from "./parse.js";
+import { chunkPdf } from "./pdf/chunker.js";
+import { runResolve } from "./resolver.js";
+import { errorMessage } from "./result.js";
+const chunkPhase = async (_db, state, hooks) => {
+    await hooks.beforeChunk?.(state);
+    for (const file of state.decrypted)
+        state.chunks.push(...await chunkPdf(file));
+    await hooks.afterChunk?.(state);
+};
+const resolvePhase = async (db, state, hooks) => {
+    await hooks.beforeResolve?.(state);
+    const summary = await runResolve({
+        db,
+        scanId: state.scanId,
+        interactive: state.options.interactive ?? true,
+    });
+    state.resolveSummary = summary;
+    await hooks.afterResolve?.(state, summary);
+};
+export const DEFAULT_PHASES = [
+    { name: "decrypt", phase: decryptPhase },
+    { name: "chunk", phase: chunkPhase },
+    { name: "parse", phase: parsePhase },
+    { name: "resolve", phase: resolvePhase },
+];
+/**
+ * Composition root. Builds the progress sink once per scan run, threads it
+ * through ScanState, then runs the phase chain. Nothing survives between
+ * scans.
+ */
+export async function runScan(db, opts = {}, hooks = {}) {
+    const scanId = `sc:${randomUUID()}`;
+    const progress = createProgress();
+    const state = {
+        scanId,
+        startedAt: Date.now(),
+        options: opts,
+        progress,
+        files: [],
+        decrypted: [],
+        skipped: [],
+        failed: [],
+        chunks: [],
+        resolveSummary: null,
+        errors: [],
+    };
+    await fire(hooks.onStart, state);
+    const phases = opts.phases ?? DEFAULT_PHASES;
+    await runPhaseChain(db, state, hooks, phases);
+    await fire(hooks.onFinish, state);
+    return { scanId, state };
+}
+async function runPhaseChain(db, state, hooks, phases) {
+    for (const { name, phase } of phases) {
+        const aborted = await tryPhase(db, state, hooks, name, phase);
+        if (aborted)
+            return;
+    }
+}
+async function tryPhase(db, state, hooks, name, phase) {
+    try {
+        await phase(db, state, hooks);
+        return false;
+    }
+    catch (err) {
+        state.errors.push({ phase: name, error: err });
+        await fire(hooks.onError, err, name, state);
+        return true;
+    }
+}
+async function fire(fn, ...args) {
+    if (!fn)
+        return;
+    try {
+        await fn(...args);
+    }
+    catch (err) {
+        console.error(`[scan-engine] ${errorMessage(err)}`);
+    }
+}

package/dist/scanner/file-worker.d.ts

@@ -0,0 +1,33 @@
+import type Database from "libsql";
+import { type ChunkWorkerDeps, type ChunkWorkerResult } from "./chunk-worker.js";
+import type { Chunk } from "./engine.js";
+import type { ScanHooks } from "./hooks.js";
+import type { ScanProgress } from "./progress.js";
+/**
+ * Pluggable chunk-parser strategy. Default is the LLM-driven runChunkWorker;
+ * tests and alternate flows (OCR-only, mock, dry-run) inject their own.
+ */
+export type ChunkWorkerFn = (deps: ChunkWorkerDeps, hooks: ScanHooks) => Promise<ChunkWorkerResult>;
+export interface FileWorkerDeps {
+    readonly db: Database.Database;
+    readonly scanId: string;
+    readonly scannedFileId: string | undefined;
+    readonly progress: ScanProgress;
+    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`.
+ * Chunk-worker tools write transactions + unknowns directly to the DB,
+ * scoped to `scanId`; per-row ticks fan out via the shared progress sink.
+ */
+export declare function runFileWorker(deps: FileWorkerDeps, hooks: ScanHooks): Promise<FileWorkerResult>;