@morroc/open-ledger 0.14.1

package/dist/ingest/commit.js

@@ -0,0 +1,313 @@
+import { config } from "../config.js";
+import { resolveOnePosting, resolveMerchantId, } from "../accounts/resolve.js";
+import { findAccountCurrency } from "../db/queries/accounts.js";
+import { insertTransaction, insertLinkedTransactions, validateTransaction, } from "../db/queries/transactions.js";
+import { deriveTransactionId, deriveGroupId, newTransactionId, newGroupId } from "../lib/ids.js";
+import { toMinorUnits } from "../lib/money.js";
+import { ISO_DATE_RE } from "../lib/date.js";
+import { recordQuestion } from "../db/queries/questions.js";
+/**
+ * Ledger-design §5: both legs must share a currency (derived from the accounts,
+ * never trusted from input); a cross-currency move needs a linked conversion pair.
+ */
+export const CURRENCY_MISMATCH_HINT = "add a linked conversion pair (one leg per currency, sharing a group)";
+const NON_WORD = /[^\p{L}\p{N}]+/gu;
+function normalizeForKey(raw) {
+    return raw.toLowerCase().replace(NON_WORD, " ").replace(/\s+/g, " ").trim();
+}
+function descriptorKey(descriptor) {
+    return `descriptor:${normalizeForKey(descriptor)}`;
+}
+function accountIdKey(id) {
+    return `account:${id}`;
+}
+function accountPairKey(a, b) {
+    const [lo, hi] = [a, b].sort();
+    return `account-pair:${lo}|${hi}`;
+}
+/**
+ * Every raise() no-ops when `ctx.batchId` is null; raised questions attach to
+ * `transaction_id`, or none for pre-insert failures.
+ */
+export function defaultTransactionCommitHooks(db, ctx) {
+    const raise = (input) => {
+        if (!ctx.batchId)
+            return;
+        recordQuestion(db, { ...input, file_id: ctx.fileId, batch_id: ctx.batchId });
+    };
+    return {
+        onCommitted: () => { },
+        onDirtyInput: (input, reason) => raise({
+            transaction_id: null,
+            account_id: null,
+            kind: "dirty_input",
+            prompt: `The ingest input produced a transaction 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 ingest input 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 },
+            });
+        },
+        // Empty on purpose: a well-formed placeholder path is unambiguous, so it is
+        // recorded for the resolution summary but raises no question.
+        onPlaceholderAccount: () => { },
+        onUncategorizedFallback: (side, accountId, transactionId) => raise({
+            transaction_id: transactionId,
+            account_id: accountId,
+            kind: "uncategorized",
+            prompt: `The ${side} side couldn't be matched to a well-formed account and was booked to ` +
+                `"${accountId}". Recategorize it onto a real account, or re-run with a full ` +
+                `colon-path hint (e.g. expense:food:dining).`,
+            context: { rule_key: accountIdKey(accountId), placeholder_id: accountId, side },
+        }),
+        onSimilarAccount: (side, originalId, matchedId, transactionId) => raise({
+            transaction_id: transactionId,
+            account_id: matchedId,
+            kind: "similar_accounts",
+            prompt: `The ingest input referenced "${originalId}" for the ${side} side — 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,
+                side,
+            },
+        }),
+        onCurrencyMismatch: (input, debit, credit) => raise({
+            transaction_id: null,
+            account_id: null,
+            kind: "currency_mismatch",
+            prompt: `Transaction "${input.description}" on ${input.date} moves money between ` +
+                `${debit.id} (${debit.currency}) and ${credit.id} (${credit.currency}), which use ` +
+                `different currencies. A single transaction can't cross currencies — record it as a ` +
+                `linked conversion pair (one transaction out of ${debit.currency}, one into ` +
+                `${credit.currency}, sharing a group) so the FX conversion is explicit.`,
+            context: { debit, credit, date: input.date, description: input.description },
+        }),
+    };
+}
+function validateRawTransaction(input) {
+    if (!ISO_DATE_RE.test(input.date ?? "")) {
+        return { ok: false, reason: "date must be an ISO date (YYYY-MM-DD)." };
+    }
+    if (!input.description || !input.description.trim()) {
+        return { ok: false, reason: "description must not be empty." };
+    }
+    if (!input.debit_account_id || !input.debit_account_id.trim()) {
+        return { ok: false, reason: "debit_account_id must not be empty." };
+    }
+    if (!input.credit_account_id || !input.credit_account_id.trim()) {
+        return { ok: false, reason: "credit_account_id must not be empty." };
+    }
+    if (input.debit_account_id === input.credit_account_id) {
+        return { ok: false, reason: "debit and credit accounts must differ." };
+    }
+    if (typeof input.amount !== "number" || !Number.isFinite(input.amount) || input.amount <= 0) {
+        return { ok: false, reason: "amount must be a positive number." };
+    }
+    return { ok: true };
+}
+function accountCurrency(db, id) {
+    return findAccountCurrency(db, id) || config.displayCurrency;
+}
+/** Inputs are distinct (validated upstream), so both sides landing on one account
+ *  means fuzzy matching over-collapsed them: that side is re-resolved with `skipFuzzy`.
+ *  A non-fuzzy collision is left for the dirty_input backstop to catch. */
+function resolveTransactionAccounts(db, debitAccountId, creditAccountId) {
+    let debitRes = resolveOnePosting(db, { account_id: debitAccountId });
+    let creditRes = resolveOnePosting(db, { account_id: creditAccountId });
+    let debitId = debitRes.posting.account_id;
+    let creditId = creditRes.posting.account_id;
+    if (debitId === creditId && debitRes.hint?.type === "similar_matched") {
+        debitRes = resolveOnePosting(db, { account_id: debitAccountId }, { skipFuzzy: true });
+        debitId = debitRes.posting.account_id;
+    }
+    if (debitId === creditId && creditRes.hint?.type === "similar_matched") {
+        creditRes = resolveOnePosting(db, { account_id: creditAccountId }, { skipFuzzy: true });
+        creditId = creditRes.posting.account_id;
+    }
+    const hints = [];
+    if (debitRes.hint)
+        hints.push({ side: "debit", hint: debitRes.hint });
+    if (creditRes.hint)
+        hints.push({ side: "credit", hint: creditRes.hint });
+    return { debitId, creditId, hints };
+}
+/** Currency comes from the resolved accounts, never from input (ledger-design §5).
+ *  A cross-currency pair is reported as a mismatch rather than merged. */
+function deriveTransactionCurrency(db, debitId, creditId) {
+    const debitCur = accountCurrency(db, debitId);
+    const creditCur = accountCurrency(db, creditId);
+    if (debitCur !== creditCur) {
+        return {
+            ok: false,
+            debit: { id: debitId, currency: debitCur },
+            credit: { id: creditId, currency: creditCur },
+        };
+    }
+    return { ok: true, currency: debitCur };
+}
+/** Doesn't touch the transactions table, but resolving may create placeholder
+ *  accounts — on a currency mismatch those side effects remain with nothing inserted. */
+function prepareTransaction(db, ctx, input) {
+    const raw = validateRawTransaction(input);
+    if (!raw.ok)
+        return { ok: false, reason: "dirty_input", message: raw.reason };
+    const { debitId, creditId, hints } = resolveTransactionAccounts(db, input.debit_account_id, input.credit_account_id);
+    const cur = deriveTransactionCurrency(db, debitId, creditId);
+    if (!cur.ok) {
+        return {
+            ok: false,
+            reason: "currency_mismatch",
+            message: `debit ${cur.debit.id} is ${cur.debit.currency}, credit ${cur.credit.id} is ${cur.credit.currency}`,
+            debit: cur.debit,
+            credit: cur.credit,
+        };
+    }
+    const currency = cur.currency;
+    const currencyOverridden = !!input.currency && input.currency !== currency;
+    const amountMinor = toMinorUnits(input.amount, currency);
+    const merchant = resolveMerchantId(db, input.merchant_id);
+    const id = ctx.fileHash && input.row_index != null
+        ? deriveTransactionId(ctx.fileHash, input.source_page ?? 0, input.row_index, input.leg_index ?? undefined)
+        : input.id ?? newTransactionId();
+    const built = {
+        id,
+        group_id: input.group_id ?? null,
+        date: input.date,
+        description: input.description,
+        merchant_id: merchant.merchantId,
+        merchant: input.merchant ?? null,
+        raw_descriptor: input.raw_descriptor ?? null,
+        source_file_id: input.source_file_id ?? ctx.fileId ?? null,
+        source_page: input.source_page ?? null,
+        debit_account_id: debitId,
+        credit_account_id: creditId,
+        amount: amountMinor,
+        currency,
+        code: input.code ?? null,
+        user_ref: input.user_ref ?? null,
+    };
+    // Backstop: resolution can collapse two ids onto one account, which
+    // validateTransaction catches as debit == credit.
+    const v = validateTransaction(built);
+    if (!v.ok)
+        return { ok: false, reason: "dirty_input", message: v.reason };
+    return { ok: true, prepared: { input: built, hints, merchant, currencyOverridden, raw: input } };
+}
+function applyTransactionHints(hooks, transactionId, prepared) {
+    let raised = 0;
+    if (prepared.merchant.attemptedUnknownId) {
+        hooks.onUnknownMerchant(prepared.raw, transactionId, prepared.merchant.attemptedUnknownId);
+        raised++;
+    }
+    for (const { side, hint } of prepared.hints) {
+        if (hint.type === "placeholder_created") {
+            hooks.onPlaceholderAccount(side, hint.accountId, transactionId);
+            continue;
+        }
+        if (hint.type === "uncategorized_fallback") {
+            hooks.onUncategorizedFallback(side, hint.accountId, transactionId);
+            raised++;
+            continue;
+        }
+        hooks.onSimilarAccount(side, hint.originalId, hint.matchedId, transactionId);
+        raised++;
+    }
+    return raised;
+}
+/** A duplicate re-commit is a no-op: no questions raised, no balance change. */
+export function commitTransaction(db, ctx, input, hooks = defaultTransactionCommitHooks(db, ctx)) {
+    const prep = prepareTransaction(db, ctx, input);
+    if (!prep.ok) {
+        if (prep.reason === "currency_mismatch") {
+            hooks.onCurrencyMismatch(input, prep.debit, prep.credit);
+        }
+        else {
+            hooks.onDirtyInput(input, prep.message);
+        }
+        return { ok: false, reason: prep.reason, message: prep.message, raisedQuestions: 1 };
+    }
+    const { id, duplicate } = insertTransaction(db, prep.prepared.input);
+    if (duplicate) {
+        return {
+            ok: true,
+            transactionId: id,
+            duplicate: true,
+            raisedQuestions: 0,
+            currencyOverridden: prep.prepared.currencyOverridden,
+        };
+    }
+    hooks.onCommitted(id);
+    const raised = applyTransactionHints(hooks, id, prep.prepared);
+    return {
+        ok: true,
+        transactionId: id,
+        duplicate: false,
+        raisedQuestions: raised,
+        currencyOverridden: prep.prepared.currencyOverridden,
+    };
+}
+function mergeHeaderLeg(header, leg, groupId, legIndex) {
+    return {
+        group_id: groupId,
+        date: header.date,
+        description: leg.description ?? header.description,
+        raw_descriptor: header.raw_descriptor ?? null,
+        source_file_id: header.source_file_id ?? null,
+        source_page: header.source_page ?? null,
+        merchant: header.merchant ?? null,
+        merchant_id: header.merchant_id ?? null,
+        debit_account_id: leg.debit_account_id,
+        credit_account_id: leg.credit_account_id,
+        amount: leg.amount,
+        currency: leg.currency ?? null,
+        code: leg.code ?? null,
+        user_ref: leg.user_ref ?? null,
+        row_index: header.row_index ?? null,
+        leg_index: legIndex,
+    };
+}
+/** Atomic under one group_id: every leg is prepared first; if any fails, nothing is inserted. */
+export function commitLinkedTransactions(db, ctx, header, legs, hooks = defaultTransactionCommitHooks(db, ctx)) {
+    if (legs.length === 0) {
+        return { ok: false, reason: "dirty_input", message: "linked transaction has no legs.", raisedQuestions: 0 };
+    }
+    const groupId = header.group_id ??
+        (ctx.fileHash && header.row_index != null
+            ? deriveGroupId(ctx.fileHash, header.source_page ?? 0, header.row_index)
+            : newGroupId());
+    const preps = [];
+    for (let i = 0; i < legs.length; i++) {
+        const raw = mergeHeaderLeg(header, legs[i], groupId, i);
+        const prep = prepareTransaction(db, ctx, raw);
+        if (!prep.ok) {
+            if (prep.reason === "currency_mismatch") {
+                hooks.onCurrencyMismatch(raw, prep.debit, prep.credit);
+            }
+            else {
+                hooks.onDirtyInput(raw, prep.message);
+            }
+            return { ok: false, reason: prep.reason, message: prep.message, raisedQuestions: 1 };
+        }
+        preps.push(prep.prepared);
+    }
+    const { results, group_id } = insertLinkedTransactions(db, preps.map((p) => p.input), { group_id: groupId });
+    let raised = 0;
+    for (let i = 0; i < preps.length; i++) {
+        const r = results[i];
+        if (r.duplicate)
+            continue;
+        hooks.onCommitted(r.id);
+        raised += applyTransactionHints(hooks, r.id, preps[i]);
+    }
+    return { ok: true, group_id, results, raisedQuestions: raised };
+}

package/dist/ingest/dedup.js

@@ -0,0 +1,35 @@
+import { deleteTransaction } from "../db/queries/transactions.js";
+import { findDuplicateTransactions, } from "../db/queries/transactions-dedup.js";
+/**
+ * Within each group, keeps the earliest transaction and deletes exact
+ * matches on merchant, file, date, and amount (integer minor units, no
+ * rounding needed). The group finder already excludes linked legs.
+ */
+export function autoMergeStrictDuplicateTransactions(db) {
+    let merged = 0;
+    for (const group of findDuplicateTransactions(db)) {
+        merged += autoMergeStrictGroup(db, group);
+    }
+    return { merged };
+}
+function autoMergeStrictGroup(db, group) {
+    const sorted = [...group].sort((a, b) => {
+        const d = a.date.localeCompare(b.date);
+        return d !== 0 ? d : a.id.localeCompare(b.id);
+    });
+    const head = sorted[0];
+    if (!head.merchant_id || !head.source_file_id)
+        return 0;
+    let deleted = 0;
+    for (let i = 1; i < sorted.length; i++) {
+        const cand = sorted[i];
+        if (cand.merchant_id === head.merchant_id &&
+            cand.source_file_id === head.source_file_id &&
+            cand.date === head.date &&
+            cand.amount === head.amount) {
+            deleteTransaction(db, cand.id);
+            deleted++;
+        }
+    }
+    return deleted;
+}

package/dist/ingest/prepare.js

@@ -0,0 +1,241 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { config, getCacheDir, getDataDir } from "../config.js";
+import { findFileByHash, findFileById, insertPendingFile, replaceFile, } from "../db/queries/files.js";
+import { extractFile } from "../extract/extract.js";
+import { resolveOcr } from "../extract/ocr.js";
+import { isEncryptedPdf } from "../extract/pdf.js";
+import { SOURCES, loadSource } from "../extract/source.js";
+import { tryExecute } from "../lib/result.js";
+import { findCandidates, unlockNonInteractive } from "./vault.js";
+function walk(dir, root, out) {
+    const entries = tryExecute(() => readdirSync(dir));
+    if (!entries.ok)
+        return;
+    for (const entry of entries.value) {
+        if (entry.startsWith("."))
+            continue;
+        const full = resolve(dir, entry);
+        const stat = tryExecute(() => statSync(full));
+        if (!stat.ok)
+            continue;
+        if (stat.value.isDirectory()) {
+            walk(full, root, out);
+            continue;
+        }
+        if (!stat.value.isFile())
+            continue;
+        if (!SOURCES[extname(entry).toLowerCase()])
+            continue;
+        out.push({ path: full, relPath: relative(root, full).split(sep).join("/") });
+    }
+}
+const UNLOCKED = { encrypted: false, vaultCandidates: 0 };
+/** Only a PDF can be locked, and only a PDF can be unopenable — an image needs neither probe. */
+async function encryptionOf(db, source) {
+    if (source.kind !== "pdf")
+        return { ok: true, value: UNLOCKED };
+    const probe = await tryExecute(() => isEncryptedPdf(source.bytes));
+    if (!probe.ok)
+        return probe;
+    if (!probe.value)
+        return { ok: true, value: UNLOCKED };
+    return {
+        ok: true,
+        value: {
+            encrypted: true,
+            vaultCandidates: findCandidates(db, source.path, config.dbEncryptionKey).length,
+        },
+    };
+}
+function unreadableEntry(file, note) {
+    return { ...file, hash: null, fileId: null, status: "unreadable", ...UNLOCKED, note };
+}
+/**
+ * A file this harness can't read becomes an `unreadable` row, rather than
+ * sinking the whole listing.
+ */
+export async function discoverFiles(db, opts = {}) {
+    const root = getDataDir();
+    const walked = [];
+    walk(root, root, walked);
+    const entries = [];
+    for (const file of walked) {
+        if (opts.regex && !opts.regex.test(file.relPath))
+            continue;
+        const loaded = loadSource(file.path);
+        if (!loaded.ok) {
+            entries.push(unreadableEntry(file, loaded.message));
+            continue;
+        }
+        const encryption = await encryptionOf(db, loaded.value);
+        if (!encryption.ok) {
+            entries.push(unreadableEntry(file, encryption.error));
+            continue;
+        }
+        const known = findFileByHash(db, loaded.value.hash);
+        entries.push({
+            ...file,
+            hash: loaded.value.hash,
+            fileId: known?.id ?? null,
+            status: known ? known.status : "new",
+            ...encryption.value,
+        });
+    }
+    return entries;
+}
+function newFileId() {
+    return `sf:${randomUUID()}`;
+}
+function pendingRow(source, fileId) {
+    return { id: fileId, path: source.path, file_hash: source.hash, mime: source.mime };
+}
+/** Pending row keyed by content hash, so re-registering the same bytes is a
+ *  no-op that returns the existing id. */
+export function registerPendingFile(db, source) {
+    const known = findFileByHash(db, source.hash);
+    if (known)
+        return { fileId: known.id, alreadyKnown: true };
+    const fileId = newFileId();
+    insertPendingFile(db, pendingRow(source, fileId));
+    return { fileId, alreadyKnown: false };
+}
+/** Resolution order: absolute, data-dir-relative, cwd-relative, then `sf:` file id; null if none match. */
+export function resolveEntryPath(db, entryOrId) {
+    if (isAbsolute(entryOrId) && existsSync(entryOrId))
+        return entryOrId;
+    const viaDataDir = resolve(getDataDir(), entryOrId);
+    if (existsSync(viaDataDir))
+        return viaDataDir;
+    const viaCwd = resolve(entryOrId);
+    if (existsSync(viaCwd))
+        return viaCwd;
+    const byId = findFileById(db, entryOrId);
+    if (byId)
+        return byId.path;
+    return null;
+}
+function replaceFileRow(db, priorId, source, fileId) {
+    replaceFile(db, priorId, pendingRow(source, fileId));
+    cleanCache(priorId);
+}
+const UNLOCK_FAILED = {
+    password_required: "the PDF is locked and no stored password opened it",
+    wrong_password: "the supplied password did not open the PDF",
+};
+/** Images are never locked; decrypted PDF bytes stay in memory — only extracted text is written to disk. */
+async function readableBytes(db, source, password) {
+    if (source.kind !== "pdf")
+        return { ok: true, bytes: source.bytes };
+    // Passes an already-unlocked source through untouched; throws on bytes mupdf can't open at all.
+    const attempt = await tryExecute(() => unlockNonInteractive(db, source.bytes, source.path, { password }));
+    if (!attempt.ok)
+        return { ok: false, reason: "pdf_unreadable", message: attempt.error };
+    const unlocked = attempt.value;
+    if (!unlocked.ok) {
+        return { ok: false, reason: unlocked.reason, message: UNLOCK_FAILED[unlocked.reason] };
+    }
+    return { ok: true, bytes: unlocked.decrypted };
+}
+const DOCUMENT_FILE = "document.txt";
+/** Markers give every row a 1-based page to cite as `source_page`. */
+function documentText(pages) {
+    return `${pages.map((page) => `--- page ${page.page} ---\n${page.text}`).join("\n\n")}\n`;
+}
+/** Rebuilt per prepare, so a prior run's artifacts can never be mistaken for this one's. */
+function freshDir(dir) {
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+function writeDocument(extraction, target) {
+    freshDir(target.dir);
+    const document = resolve(target.dir, DOCUMENT_FILE);
+    writeFileSync(document, documentText(extraction.pages), { mode: 0o600 });
+    return {
+        ok: true,
+        fileId: target.fileId,
+        kind: "text",
+        source: extraction.source,
+        textLayer: extraction.textLayer,
+        model: extraction.model,
+        pageCount: extraction.pages.length,
+        document,
+        pages: extraction.pages.map((page) => ({ page: page.page, chars: page.text.length })),
+        failedPages: extraction.failedPages,
+    };
+}
+function writePages(extraction, target) {
+    const head = {
+        ok: true,
+        fileId: target.fileId,
+        kind: "images",
+        source: extraction.source,
+        textLayer: extraction.textLayer,
+        pageCount: extraction.pages.length,
+        dpi: extraction.dpi,
+    };
+    // An untouched image is read where it lies; only a prior run's artifacts could be there to mislead.
+    if (extraction.source === "original") {
+        rmSync(target.dir, { recursive: true, force: true });
+        const pages = extraction.pages.map((page) => ({ page: page.page, path: target.sourcePath }));
+        return { ...head, pages };
+    }
+    freshDir(target.dir);
+    const pages = [];
+    for (const page of extraction.pages) {
+        const path = resolve(target.dir, `p${page.page}.png`);
+        writeFileSync(path, page.bytes, { mode: 0o600 });
+        pages.push({ page: page.page, path });
+    }
+    return { ...head, pages };
+}
+const WRITE_ARTIFACTS = {
+    text: writeDocument,
+    images: writePages,
+};
+/** A failure leaves the ledger exactly as it found it. */
+export async function prepareFile(db, entryOrId, opts = {}) {
+    const absPath = resolveEntryPath(db, entryOrId);
+    if (absPath === null) {
+        return { ok: false, reason: "not_found", message: `no ingest entry or file at "${entryOrId}"` };
+    }
+    const loaded = loadSource(absPath);
+    if (!loaded.ok)
+        return { ok: false, reason: loaded.reason, message: loaded.message };
+    const source = loaded.value;
+    // Every case but --force's swap (see replaceFileRow) registers now: a file
+    // that never opens still needs an id for `ingest fail`.
+    const prior = opts.force ? findFileByHash(db, source.hash) : null;
+    const fileId = prior ? newFileId() : registerPendingFile(db, source).fileId;
+    const readable = await readableBytes(db, source, opts.password);
+    if (!readable.ok)
+        return readable;
+    const extracted = await extractFile({ kind: source.kind, mime: source.mime, bytes: readable.bytes, path: source.path }, { ocr: resolveOcr(), overrides: { rescan: opts.rescan, noOcr: opts.noOcr } });
+    if (!extracted.ok)
+        return { ok: false, reason: extracted.reason, message: extracted.message };
+    const target = {
+        fileId,
+        dir: resolve(getCacheDir(), fileId),
+        sourcePath: source.path,
+    };
+    const written = WRITE_ARTIFACTS[extracted.value.kind](extracted.value, target);
+    if (prior)
+        replaceFileRow(db, prior.id, source, fileId);
+    return written;
+}
+export function cleanCache(fileId) {
+    const base = getCacheDir();
+    if (fileId) {
+        const dir = resolve(base, fileId);
+        if (!existsSync(dir))
+            return { removed: [] };
+        rmSync(dir, { recursive: true, force: true });
+        return { removed: [dir] };
+    }
+    if (!existsSync(base))
+        return { removed: [] };
+    const removed = readdirSync(base).map((name) => resolve(base, name));
+    rmSync(base, { recursive: true, force: true });
+    return { removed };
+}

package/dist/ingest/vault.js

@@ -0,0 +1,56 @@
+import { basename } from "node:path";
+import { config } from "../config.js";
+import { listPasswordSecrets, recordPasswordUse, upsertPassword, } from "../db/queries/vault.js";
+import { isEncryptedPdf, unlockPdf } from "../extract/pdf.js";
+// The SQL and the at-rest encryption live in src/db/queries/vault.ts; the
+// mupdf mechanism in src/extract/pdf.ts.
+const REGEX_META = /[.*+?^${}()|[\]\\]/g;
+const SEPARATORS = /[_\-\s.]/;
+const MIN_PREFIX_LEN = 3;
+/** Short or non-alpha prefixes fall back to escaped+digit-collapse to avoid `^a.*`-style false positives. */
+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}$`;
+}
+/** A pattern that no longer compiles must not sink the whole lookup. */
+function safeTest(pattern, target) {
+    try {
+        return new RegExp(pattern, "i").test(target);
+    }
+    catch {
+        return false;
+    }
+}
+/** Stored passwords whose pattern matches this file's name, most-used first. */
+export function findCandidates(db, filePath, dbKey) {
+    const target = basename(filePath);
+    return listPasswordSecrets(db, dbKey).filter((row) => safeTest(row.pattern, target));
+}
+/** Non-interactive unlock for the agent-CLI harness: no prompts, no spinners. */
+export async function unlockNonInteractive(db, bytes, filename, opts) {
+    if (!(await isEncryptedPdf(bytes))) {
+        return { ok: true, decrypted: bytes };
+    }
+    for (const cand of findCandidates(db, filename, config.dbEncryptionKey)) {
+        const result = await unlockPdf(bytes, cand.password);
+        if (result.ok) {
+            recordPasswordUse(db, cand.id);
+            return { ok: true, decrypted: result.decrypted };
+        }
+    }
+    const password = opts.password ?? "";
+    if (!password)
+        return { ok: false, reason: "password_required" };
+    const result = await unlockPdf(bytes, password);
+    if (!result.ok) {
+        return { ok: false, reason: "wrong_password" };
+    }
+    upsertPassword(db, suggestPattern(filename), password, config.dbEncryptionKey);
+    return { ok: true, decrypted: result.decrypted };
+}

package/dist/lib/date.js

@@ -0,0 +1,6 @@
+/** UTC, not local time. */
+export function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** ISO calendar date shape (YYYY-MM-DD). Shape only — no calendar validity check. */
+export const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;

package/dist/lib/ids.js

@@ -0,0 +1,25 @@
+import { createHash, randomUUID } from "crypto";
+/**
+ * `tx:` + sha256("<hash>|<page>|<row>[|<leg>]") — deterministic, so re-ingesting the
+ * same file is idempotent. Omitting `legIndex` makes the hash match `deriveGroupId`'s.
+ */
+export function deriveTransactionId(fileHash, page, rowIndex, legIndex) {
+    const base = `${fileHash}|${page}|${rowIndex}`;
+    const material = legIndex != null ? `${base}|${legIndex}` : base;
+    return "tx:" + createHash("sha256").update(material).digest("hex").slice(0, 16);
+}
+/** `tg:` + the same hash as legless `deriveTransactionId(fileHash, page, rowIndex)`. */
+export function deriveGroupId(fileHash, page, rowIndex) {
+    return "tg:" + createHash("sha256").update(`${fileHash}|${page}|${rowIndex}`).digest("hex").slice(0, 16);
+}
+/** Groups a commit run's raised questions. */
+export function newBatchId() {
+    return `ib:${randomUUID()}`;
+}
+/** For a row without deterministic source coordinates. */
+export function newTransactionId() {
+    return `tx:${randomUUID()}`;
+}
+export function newGroupId() {
+    return `tg:${randomUUID()}`;
+}