plasalid 0.7.1 → 0.7.2

package/dist/scanner/file-worker.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "crypto";
+import { runWithConcurrency } from "./concurrency.js";
+import { runChunkWorker } from "./chunk-worker.js";
+/**
+ * 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 async function runFileWorker(deps, hooks) {
+    const workerId = `fw:${randomUUID()}`;
+    const chunkFn = deps.chunkWorkerFn ?? runChunkWorker;
+    const tasks = deps.chunks.map(chunk => () => chunkFn({
+        db: deps.db,
+        scanId: deps.scanId,
+        scannedFileId: deps.scannedFileId,
+        progress: deps.progress,
+        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)
+            ok++;
+        else
+            failed++;
+    }
+    return { workerId, fileId: deps.fileId, ok, failed };
+}

package/dist/scanner/fileWorker.d.ts

@@ -0,0 +1,33 @@
+import type Database from "libsql";
+import { type ChunkWorkerDeps, type ChunkWorkerResult } from "./chunkWorker.js";
+import type { ScanBuffer } from "./buffer.js";
+import type { Chunk } from "./engine.js";
+import type { ScanHooks } from "./hooks.js";
+/**
+ * Pluggable chunk-parser strategy. 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/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)
+            ok++;
+        else
+            failed++;
+    }
+    return { workerId, fileId: deps.fileId, ok, failed };
+}

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

@@ -0,0 +1,25 @@
+import type { Chunk, ScanState, CommitOutcome, PhaseName } from "../engine/types.js";
+import type { BufferSnapshot } from "../buffer/types.js";
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Lifecycle hooks the scanner engine fires at phase edges. CLI registers
+ * spinner/Ink hooks; tests register assertions. Every hook is optional and
+ * best-effort — a hook that throws gets logged and the phase continues.
+ */
+export interface ScanHooks {
+    onStart?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeDecrypt?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterDecrypt?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeChunk?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterChunk?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeParse?(s: Readonly<ScanState>): MaybePromise<void>;
+    onWorkerStart?(workerId: string, chunk: Chunk): void;
+    onWorkerEnd?(workerId: string, chunk: Chunk, ok: boolean): void;
+    afterParse?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeReview?(s: Readonly<ScanState>, snapshot: BufferSnapshot): MaybePromise<void>;
+    afterReview?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeCommit?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterCommit?(s: Readonly<ScanState>, outcome: CommitOutcome): MaybePromise<void>;
+    onError?(err: unknown, phase: PhaseName, s: Readonly<ScanState>): MaybePromise<void>;
+    onFinish?(s: Readonly<ScanState>): MaybePromise<void>;
+}

package/dist/scanner/hooks/types.js

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

package/dist/scanner/hooks.d.ts

@@ -0,0 +1,23 @@
+import type { Chunk, ScanState, PhaseName } from "./engine.js";
+import type { ResolveSummary } from "./resolver.js";
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Lifecycle hooks the engine fires at phase edges. CLI registers spinner/Ink
+ * hooks; tests register assertions. Every hook is optional and best-effort —
+ * a hook that throws gets logged and the phase continues.
+ */
+export interface ScanHooks {
+    onStart?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeDecrypt?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterDecrypt?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeChunk?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterChunk?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeParse?(s: Readonly<ScanState>): MaybePromise<void>;
+    onWorkerStart?(workerId: string, chunk: Chunk): void;
+    onWorkerEnd?(workerId: string, chunk: Chunk, ok: boolean): void;
+    afterParse?(s: Readonly<ScanState>): MaybePromise<void>;
+    beforeResolve?(s: Readonly<ScanState>): MaybePromise<void>;
+    afterResolve?(s: Readonly<ScanState>, summary: ResolveSummary): MaybePromise<void>;
+    onError?(err: unknown, phase: PhaseName, s: Readonly<ScanState>): MaybePromise<void>;
+    onFinish?(s: Readonly<ScanState>): MaybePromise<void>;
+}

package/dist/scanner/hooks.js

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

package/dist/scanner/parse.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "./engine.js";
+import type { ScanHooks } from "./hooks.js";
+/**
+ * Phase 3 — two-tier fan-out: up to `maxFile` files in parallel, each file
+ * processing up to `maxChunk` chunks in parallel. Chunk-worker tools write
+ * transactions and questions directly to the DB (scoped to `scanId`) and tick
+ * the shared progress sink.
+ */
+export declare function parsePhase(db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/parse.js

@@ -0,0 +1,47 @@
+import { runWithConcurrency } from "./concurrency.js";
+import { runScanWorker } from "./worker.js";
+import { errorMessage } from "./result.js";
+const DEFAULT_MAX_FILE_WORKERS = 5;
+const DEFAULT_MAX_SCAN_WORKERS_PER_FILE = 5;
+const HARD_CAP = 8;
+const clamp = (n, fallback) => Math.min(HARD_CAP, Math.max(1, n ?? fallback));
+/**
+ * Phase 3 — two-tier fan-out: up to `maxFile` files in parallel, each file
+ * processing up to `maxChunk` chunks in parallel. Chunk-worker tools write
+ * transactions and questions directly to the DB (scoped to `scanId`) and tick
+ * the shared progress sink.
+ */
+export async function parsePhase(db, state, hooks) {
+    await hooks.beforeParse?.(state);
+    const maxFile = clamp(state.options.maxFileWorkers, DEFAULT_MAX_FILE_WORKERS);
+    const maxChunk = clamp(state.options.maxScanWorkersPerFile, DEFAULT_MAX_SCAN_WORKERS_PER_FILE);
+    const fileGroups = state.decrypted
+        .map(file => ({
+        fileId: file.path,
+        scannedFileId: file.scannedFileId,
+        chunks: state.chunks.filter(c => c.fileId === file.path),
+    }))
+        .filter(g => g.chunks.length > 0);
+    const fileTasks = fileGroups.map(group => () => {
+        const chunkTasks = group.chunks.map(chunk => () => runScanWorker({
+            db,
+            scanId: state.scanId,
+            scannedFileId: group.scannedFileId,
+            progress: state.progress,
+            chunk,
+        }, hooks));
+        return runWithConcurrency(chunkTasks, maxChunk);
+    });
+    const settled = await runWithConcurrency(fileTasks, maxFile);
+    for (let i = 0; i < settled.length; i++) {
+        const r = settled[i];
+        if (!r.ok)
+            state.errors.push({ phase: "parse", target: fileGroups[i].fileId, error: errorMessage(r.error) });
+    }
+    for (const file of state.decrypted) {
+        if (!file.scannedFileId)
+            continue;
+        db.prepare(`UPDATE scanned_files SET status = 'scanned', scanned_at = datetime('now') WHERE id = ?`).run(file.scannedFileId);
+    }
+    await hooks.afterParse?.(state);
+}

package/dist/scanner/passes/index.d.ts

@@ -0,0 +1,8 @@
+import type { AuditPass } from "./types.js";
+/**
+ * Audit-pass registry. The audit engine indexes these by their declared
+ * `kinds` at startup and dispatches matching passes per buffer event.
+ * Append to the array to extend; do not edit the engine.
+ */
+export declare const AUDIT_PASSES: readonly AuditPass[];
+export type { AuditPass };

package/dist/scanner/passes/index.js

@@ -0,0 +1,6 @@
+/**
+ * Audit-pass registry. The audit engine indexes these by their declared
+ * `kinds` at startup and dispatches matching passes per buffer event.
+ * Append to the array to extend; do not edit the engine.
+ */
+export const AUDIT_PASSES = [];

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

@@ -0,0 +1,22 @@
+import type Database from "libsql";
+import type { BufferEvent, EventKind } from "../bus.js";
+import type { ScanBuffer } from "../buffer.js";
+export interface AuditContext {
+    readonly db: Database.Database;
+    readonly buffer: ScanBuffer;
+    /** Optional tally bucket — passes increment their own count for the review summary. */
+    readonly tally: Record<string, number>;
+}
+/**
+ * Deterministic rule-based reaction to a BufferEvent. Passes mutate the
+ * ScanBuffer (apply memory rules, dedup, link to recurrences, etc.) so data
+ * lands clean before the review TUI sees it.
+ *
+ * Declare which event kinds you care about up front via `kinds` — the audit
+ * engine indexes once and dispatches only the matching passes per event.
+ */
+export interface AuditPass {
+    readonly name: string;
+    readonly kinds: readonly EventKind[];
+    apply(event: BufferEvent, ctx: AuditContext): Promise<void>;
+}

package/dist/scanner/passes/types.js

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

package/dist/scanner/pdf/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/pdf/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/pdf/password-store.d.ts

@@ -0,0 +1,34 @@
+import type Database from "libsql";
+export interface StoredPassword {
+    id: string;
+    pattern: string;
+    password: string;
+    useCount: number;
+    lastUsedAt: string | null;
+}
+/**
+ * Derive a regex from a filename. Strategy: take the leading alphabetic-ish
+ * prefix (up to the first separator: underscore, hyphen, space, or dot) and
+ * wildcard everything after it. Looser than a literal match — `AcctSt_May26.pdf`
+ * and `AcctSt_Jun26.pdf` share the same pattern.
+ *
+ * Falls back to the older digit-collapse strategy when the prefix is too short
+ * (<3 chars) or doesn't start with a letter, so we don't end up with overly
+ * generic patterns like `^a.*` or `^\d+.*`.
+ *
+ * Examples:
+ *   `AcctSt_May26.pdf`          → `^acctst.*`
+ *   `KBank-Savings-2026-01.pdf` → `^kbank.*`
+ *   `statement.pdf`             → `^statement.*`
+ *   `1234567890.pdf`            → `^\d+\.pdf$`           (fallback)
+ *   `e-statement.pdf`           → `^e\-statement\.pdf$`  (fallback — prefix too short)
+ */
+export declare function suggestPattern(filename: string): string;
+/** Stored passwords whose pattern matches the basename of `filePath`. */
+export declare function findCandidates(db: Database.Database, filePath: string, dbKey: string): StoredPassword[];
+/**
+ * Upsert by pattern. If the pattern already exists the row is replaced — useful
+ * when the bank rotates the password for a recurring statement series.
+ */
+export declare function savePassword(db: Database.Database, pattern: string, password: string, dbKey: string): string;
+export declare function recordUse(db: Database.Database, id: string): void;

package/dist/scanner/pdf/password-store.js

@@ -0,0 +1,83 @@
+import { randomUUID } from "crypto";
+import { basename } from "path";
+import { encryptSecret, decryptSecret } from "../../db/encryption.js";
+const REGEX_META = /[.*+?^${}()|[\]\\]/g;
+const SEPARATORS = /[_\-\s.]/;
+const MIN_PREFIX_LEN = 3;
+/**
+ * Derive a regex from a filename. Strategy: take the leading alphabetic-ish
+ * prefix (up to the first separator: underscore, hyphen, space, or dot) and
+ * wildcard everything after it. Looser than a literal match — `AcctSt_May26.pdf`
+ * and `AcctSt_Jun26.pdf` share the same pattern.
+ *
+ * Falls back to the older digit-collapse strategy when the prefix is too short
+ * (<3 chars) or doesn't start with a letter, so we don't end up with overly
+ * generic patterns like `^a.*` or `^\d+.*`.
+ *
+ * Examples:
+ *   `AcctSt_May26.pdf`          → `^acctst.*`
+ *   `KBank-Savings-2026-01.pdf` → `^kbank.*`
+ *   `statement.pdf`             → `^statement.*`
+ *   `1234567890.pdf`            → `^\d+\.pdf$`           (fallback)
+ *   `e-statement.pdf`           → `^e\-statement\.pdf$`  (fallback — prefix too short)
+ */
+export function suggestPattern(filename) {
+    const name = basename(filename).toLowerCase();
+    const prefix = name.split(SEPARATORS)[0];
+    if (prefix.length >= MIN_PREFIX_LEN && /^[a-z]/.test(prefix)) {
+        return `^${prefix.replace(REGEX_META, "\\$&")}.*`;
+    }
+    const escaped = name.replace(REGEX_META, "\\$&");
+    const collapsed = escaped.replace(/\d+/g, "\\d+");
+    return `^${collapsed}$`;
+}
+/** Stored passwords whose pattern matches the basename of `filePath`. */
+export function findCandidates(db, filePath, dbKey) {
+    const target = basename(filePath);
+    const rows = db
+        .prepare(`SELECT id, pattern, password_encrypted, use_count, last_used_at
+       FROM file_passwords
+       ORDER BY use_count DESC, last_used_at DESC NULLS LAST, created_at ASC`)
+        .all();
+    return rows
+        .filter(r => safeTest(r.pattern, target))
+        .map(r => ({
+        id: r.id,
+        pattern: r.pattern,
+        password: decryptSecret(r.password_encrypted, dbKey),
+        useCount: r.use_count,
+        lastUsedAt: r.last_used_at,
+    }));
+}
+function safeTest(pattern, target) {
+    try {
+        return new RegExp(pattern, "i").test(target);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Upsert by pattern. If the pattern already exists the row is replaced — useful
+ * when the bank rotates the password for a recurring statement series.
+ */
+export function savePassword(db, pattern, password, dbKey) {
+    const encrypted = encryptSecret(password, dbKey);
+    const existing = db
+        .prepare(`SELECT id FROM file_passwords WHERE pattern = ?`)
+        .get(pattern);
+    if (existing) {
+        db.prepare(`UPDATE file_passwords
+       SET password_encrypted = ?, use_count = 0, last_used_at = NULL
+       WHERE id = ?`).run(encrypted, existing.id);
+        return existing.id;
+    }
+    const id = `fp:${randomUUID()}`;
+    db.prepare(`INSERT INTO file_passwords (id, pattern, password_encrypted) VALUES (?, ?, ?)`).run(id, pattern, encrypted);
+    return id;
+}
+export function recordUse(db, id) {
+    db.prepare(`UPDATE file_passwords
+     SET use_count = use_count + 1, last_used_at = datetime('now')
+     WHERE id = ?`).run(id);
+}

package/dist/scanner/pdf/pdf-unlock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Thin wrapper around the mupdf WASM library. Lazy-imported on first call so
+ * the WASM module isn't loaded for data dirs that contain only plaintext PDFs.
+ */
+export declare function isEncrypted(bytes: Buffer): Promise<boolean>;
+export interface UnlockResult {
+    ok: boolean;
+    /** Set when `ok === true`. Plaintext (decrypted) PDF bytes ready to forward. */
+    decrypted?: Buffer;
+}
+/**
+ * Attempt to unlock and re-save `bytes` as an unencrypted PDF using `password`.
+ * Returns `{ ok: false }` on wrong password or non-PDF input. Returns
+ * `{ ok: true, decrypted }` on success. If the input wasn't encrypted to begin
+ * with, returns `{ ok: true, decrypted: bytes }` unchanged.
+ */
+export declare function unlock(bytes: Buffer, password: string): Promise<UnlockResult>;

package/dist/scanner/pdf/pdf-unlock.js

@@ -0,0 +1,50 @@
+/**
+ * Thin wrapper around the mupdf WASM library. Lazy-imported on first call so
+ * the WASM module isn't loaded for data dirs that contain only plaintext PDFs.
+ */
+let mupdfPromise = null;
+/** mupdf's authenticatePassword returns 0 on a wrong password, non-zero on success. */
+const MUPDF_AUTH_FAILED = 0;
+function getMupdf() {
+    if (!mupdfPromise) {
+        mupdfPromise = import("mupdf");
+    }
+    return mupdfPromise;
+}
+export async function isEncrypted(bytes) {
+    const mupdf = await getMupdf();
+    const doc = mupdf.Document.openDocument(bytes, "application/pdf");
+    try {
+        return doc.needsPassword();
+    }
+    finally {
+        doc.destroy();
+    }
+}
+/**
+ * Attempt to unlock and re-save `bytes` as an unencrypted PDF using `password`.
+ * Returns `{ ok: false }` on wrong password or non-PDF input. Returns
+ * `{ ok: true, decrypted }` on success. If the input wasn't encrypted to begin
+ * with, returns `{ ok: true, decrypted: bytes }` unchanged.
+ */
+export async function unlock(bytes, password) {
+    const mupdf = await getMupdf();
+    const doc = mupdf.Document.openDocument(bytes, "application/pdf");
+    try {
+        if (!(doc instanceof mupdf.PDFDocument)) {
+            return { ok: false };
+        }
+        if (!doc.needsPassword()) {
+            return { ok: true, decrypted: bytes };
+        }
+        const result = doc.authenticatePassword(password);
+        if (result === MUPDF_AUTH_FAILED) {
+            return { ok: false };
+        }
+        const out = doc.saveToBuffer("decrypt");
+        return { ok: true, decrypted: Buffer.from(out.asUint8Array()) };
+    }
+    finally {
+        doc.destroy();
+    }
+}

package/dist/scanner/pdf/pdf.d.ts

@@ -0,0 +1,17 @@
+import type { DocumentBlock } from "../../ai/provider.js";
+export interface LoadedFile {
+    bytes: Buffer;
+    hash: string;
+    mime: string;
+    fileName: string;
+}
+/**
+ * Read a local PDF, hash its bytes, and return everything the scan pipeline
+ * needs to decide whether to skip / re-scan / unlock the file. The hash is
+ * sha256 of the original on-disk bytes (still encrypted if the PDF is
+ * password-protected) — that's what the dedup contract relies on, so we can
+ * recognize the same file across re-scans regardless of unlock state.
+ */
+export declare function readPdf(path: string): LoadedFile;
+/** Build an Anthropic-compatible document content block from PDF bytes. */
+export declare function buildDocumentBlock(bytes: Buffer, fileName: string, mime?: string): DocumentBlock;

package/dist/scanner/pdf/pdf.js

@@ -0,0 +1,36 @@
+import { readFileSync, statSync } from "fs";
+import { createHash } from "crypto";
+import { basename, extname } from "path";
+const MIME_BY_EXT = {
+    ".pdf": "application/pdf",
+};
+const MAX_BYTES = 30 * 1024 * 1024;
+/**
+ * Read a local PDF, hash its bytes, and return everything the scan pipeline
+ * needs to decide whether to skip / re-scan / unlock the file. The hash is
+ * sha256 of the original on-disk bytes (still encrypted if the PDF is
+ * password-protected) — that's what the dedup contract relies on, so we can
+ * recognize the same file across re-scans regardless of unlock state.
+ */
+export function readPdf(path) {
+    const ext = extname(path).toLowerCase();
+    const mime = MIME_BY_EXT[ext];
+    if (!mime) {
+        throw new Error(`Unsupported file extension: ${ext}. Plasalid v1 only ingests PDFs.`);
+    }
+    const stat = statSync(path);
+    if (stat.size > MAX_BYTES) {
+        throw new Error(`File too large (${stat.size} bytes). Limit is ${MAX_BYTES} bytes.`);
+    }
+    const bytes = readFileSync(path);
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    return { bytes, hash, mime, fileName: basename(path) };
+}
+/** Build an Anthropic-compatible document content block from PDF bytes. */
+export function buildDocumentBlock(bytes, fileName, mime = "application/pdf") {
+    return {
+        type: "document",
+        source: { type: "base64", media_type: mime, data: bytes.toString("base64") },
+        title: fileName,
+    };
+}

package/dist/scanner/pdf/state-machine.d.ts

@@ -0,0 +1,60 @@
+import type { StoredPassword } from "./password-store.js";
+/**
+ * Pure state machine for the unlock phase of a single file scan. Side effects
+ * (mupdf calls, prompts, DB reads) live in the orchestrator; this module only
+ * encodes the transition logic so it can be exhaustively unit-tested.
+ */
+export declare const MAX_PASSWORD_ATTEMPTS = 10;
+export type UnlockOutcome = {
+    kind: "plaintext";
+} | {
+    kind: "from-store";
+    storedId: string;
+} | {
+    kind: "from-user";
+    password: string;
+};
+export type UnlockState = {
+    kind: "init";
+} | {
+    kind: "trying-stored";
+    candidates: StoredPassword[];
+} | {
+    kind: "awaiting-user";
+    attempt: number;
+} | {
+    kind: "done";
+    decrypted: Buffer;
+    outcome: UnlockOutcome;
+} | {
+    kind: "failed";
+    reason: string;
+};
+export type UnlockEvent = {
+    kind: "INSPECTED_PLAINTEXT";
+    bytes: Buffer;
+} | {
+    kind: "INSPECTED_ENCRYPTED";
+    candidates: StoredPassword[];
+} | {
+    kind: "STORED_UNLOCK_OK";
+    decrypted: Buffer;
+    usedStoredId: string;
+} | {
+    kind: "STORED_UNLOCK_EXHAUSTED";
+} | {
+    kind: "USER_CANCELLED";
+} | {
+    kind: "UNLOCK_OK";
+    decrypted: Buffer;
+    password: string;
+} | {
+    kind: "UNLOCK_FAIL";
+};
+export declare function isTerminal(state: UnlockState): boolean;
+/**
+ * Pure transition. Throws if the event doesn't make sense for the current state;
+ * the orchestrator never produces such combinations, so reaching the throw is a
+ * programmer error worth surfacing loudly.
+ */
+export declare function transition(state: UnlockState, event: UnlockEvent): UnlockState;