plasalid 0.7.0 → 0.7.2

package/dist/scanner/audit/eventBus.js

@@ -0,0 +1,35 @@
+export class EventBus {
+    listeners = new Set();
+    buffered = [];
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => { this.listeners.delete(fn); };
+    }
+    /**
+     * Publish an event to every listener. Listener errors are caught and logged —
+     * a misbehaving pass never silences the bus for the rest.
+     */
+    publish(event) {
+        this.buffered.push(event);
+        for (const fn of this.listeners) {
+            try {
+                const r = fn(event);
+                if (r && typeof r.catch === "function") {
+                    r.catch(err => console.error(`[EventBus listener] ${err.message}`));
+                }
+            }
+            catch (err) {
+                console.error(`[EventBus listener] ${err.message}`);
+            }
+        }
+    }
+    /** All events seen so far, in publish order. Useful for the review TUI summary. */
+    history() {
+        return this.buffered;
+    }
+    /** Test helper. */
+    reset() {
+        this.listeners.clear();
+        this.buffered = [];
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { AuditPass } from "./types.js";
+/**
+ * Registry of all audit passes the Auditor runs against the SharedBuffer in
+ * flight. Order matters — earlier passes get first crack at each event. Add new
+ * passes here.
+ *
+ * Currently empty; passes are added in follow-up tasks (memoryRule, merchantDefault,
+ * dedupe, correlation, recurrenceLink, boundaryContinuation).
+ */
+export declare const AUDIT_PASSES: readonly AuditPass[];
+export type { AuditPass };

package/dist/scanner/audit/passes/index.js

@@ -0,0 +1,9 @@
+/**
+ * Registry of all audit passes the Auditor runs against the SharedBuffer in
+ * flight. Order matters — earlier passes get first crack at each event. Add new
+ * passes here.
+ *
+ * Currently empty; passes are added in follow-up tasks (memoryRule, merchantDefault,
+ * dedupe, correlation, recurrenceLink, boundaryContinuation).
+ */
+export const AUDIT_PASSES = [];

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

@@ -0,0 +1,23 @@
+import type Database from "libsql";
+import type { BufferEvent } from "../../bus/types.js";
+import type { ScanBuffer } from "../../buffer/types.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>;
+}
+/**
+ * One audit pass — a deterministic, rule-based reaction to a BufferEvent.
+ * Passes mutate the Buffer (apply memory rules, dedup, link to existing
+ * recurrences, etc.) so the data lands clean before the review TUI sees it.
+ *
+ * Passes are NOT LLM agents — they're cheap deterministic code that runs on
+ * every relevant event. The LLM only runs in chunk workers (parsing one page)
+ * and in the review TUI's ask-user drill-down for residual unknowns.
+ */
+export interface AuditPass {
+    readonly name: string;
+    handles(event: BufferEvent): boolean;
+    apply(event: BufferEvent, ctx: AuditContext): Promise<void>;
+}

package/dist/scanner/audit/passes/types.js

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

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

@@ -0,0 +1,27 @@
+import type Database from "libsql";
+import type { Bus } from "../bus/types.js";
+import type { ScanBuffer } from "../buffer/types.js";
+import type { AuditPass } from "./passes/types.js";
+export interface AuditEngineDeps {
+    readonly db: Database.Database;
+    readonly bus: Bus;
+    readonly buffer: ScanBuffer;
+    readonly passes: readonly AuditPass[];
+}
+/**
+ * The audit engine's public surface. The scanner engine creates one of these
+ * at the composition root, calls start() before the parse phase fans out the
+ * chunk workers, and stop() in the finally — guaranteeing every in-flight
+ * mutation gets a chance to react before commit reads the buffer snapshot.
+ */
+export interface AuditEngine {
+    /** Begin subscribing to the bus. */
+    start(): void;
+    /** Unsubscribe and ignore any further events. */
+    stop(): void;
+    /** Resolve once the queue empties and no pass is in flight. */
+    drain(): Promise<void>;
+    /** Per-pass mutation counts the review TUI surfaces. */
+    readonly tally: Readonly<Record<string, number>>;
+}
+export type { AuditPass } from "./passes/types.js";

package/dist/scanner/audit/types.js

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

package/dist/scanner/auditor.d.ts

@@ -0,0 +1,51 @@
+import type Database from "libsql";
+import type { Bus, 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 the event kinds you care about up front via `kinds` — the audit
+ * engine indexes once at startup and dispatches only the matching passes per
+ * event. Append to AUDIT_PASSES to extend; do not edit the engine.
+ */
+export interface AuditPass {
+    readonly name: string;
+    readonly kinds: readonly EventKind[];
+    apply(event: BufferEvent, ctx: AuditContext): Promise<void>;
+}
+export declare const AUDIT_PASSES: readonly AuditPass[];
+export interface AuditEngineDeps {
+    readonly db: Database.Database;
+    readonly bus: Bus;
+    readonly buffer: ScanBuffer;
+    readonly passes: readonly AuditPass[];
+}
+/**
+ * Reactive event consumer. The scanner engine creates one at the composition
+ * root, starts it before any phase runs, and stops it in the `finally` —
+ * guaranteeing every in-flight mutation is processed before commit reads
+ * the buffer snapshot.
+ */
+export interface AuditEngine {
+    start(): void;
+    stop(): void;
+    /** Resolves once the queue empties and no pass is in flight. */
+    drain(): Promise<void>;
+    /** Per-pass mutation counts the review TUI surfaces. */
+    readonly tally: Readonly<Record<string, number>>;
+    /** Live queue + processed counters + loaded-pass count for the dashboard pulse. */
+    readonly stats: {
+        readonly pending: number;
+        readonly processed: number;
+        readonly passCount: number;
+    };
+}
+export declare function createAuditEngine(deps: AuditEngineDeps): AuditEngine;

package/dist/scanner/auditor.js

@@ -0,0 +1,80 @@
+export const AUDIT_PASSES = [];
+function buildPassIndex(passes) {
+    const index = new Map();
+    for (const pass of passes) {
+        for (const kind of pass.kinds) {
+            const list = index.get(kind) ?? [];
+            list.push(pass);
+            index.set(kind, list);
+        }
+    }
+    return index;
+}
+async function dispatch(event, handlers, ctx) {
+    for (const pass of handlers) {
+        try {
+            await pass.apply(event, ctx);
+        }
+        catch (err) {
+            console.error(`[audit pass ${pass.name}] ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+export function createAuditEngine(deps) {
+    const tally = {};
+    const ctx = { db: deps.db, buffer: deps.buffer, tally };
+    const passIndex = buildPassIndex(deps.passes);
+    const queue = [];
+    let unsubscribe = null;
+    let running = false;
+    let processed = 0;
+    let idleResolvers = [];
+    const tick = async () => {
+        if (running)
+            return;
+        running = true;
+        try {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                const handlers = passIndex.get(event.kind);
+                if (handlers)
+                    await dispatch(event, handlers, ctx);
+                processed++;
+            }
+        }
+        finally {
+            running = false;
+            const resolvers = idleResolvers;
+            idleResolvers = [];
+            for (const r of resolvers)
+                r();
+        }
+    };
+    return {
+        start() {
+            if (unsubscribe)
+                return;
+            unsubscribe = deps.bus.subscribe((event) => {
+                queue.push(event);
+                void tick();
+            });
+        },
+        stop() {
+            unsubscribe?.();
+            unsubscribe = null;
+        },
+        drain() {
+            if (!running && queue.length === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => {
+                idleResolvers.push(resolve);
+            });
+        },
+        get tally() {
+            return tally;
+        },
+        get stats() {
+            return { pending: queue.length, processed, passCount: deps.passes.length };
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { Bus } from "../bus/types.js";
+import type { ScanBuffer } from "./types.js";
+/**
+ * The shared buffer factory. One instance per scan run — the scanner engine
+ * creates it once at the composition root and threads it to every chunk
+ * worker, audit pass, and commit phase. Mutations publish typed events on
+ * the bus so the auditor can react in flight.
+ */
+export declare function createBuffer(scanId: string, bus: Bus): ScanBuffer;

package/dist/scanner/buffer/engine.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "crypto";
+/**
+ * Serial async mutex. Mutations chain so two concurrent callers don't see
+ * each other's half-written state. Reads bypass the mutex — they only ever
+ * see committed values (Map .set is atomic in single-threaded JS).
+ */
+function createMutex() {
+    let chain = Promise.resolve();
+    return {
+        runExclusive(fn) {
+            const next = chain.then(() => fn());
+            chain = next.catch(() => undefined);
+            return next;
+        },
+    };
+}
+function emptyState(scanId) {
+    return {
+        scanId,
+        transactions: new Map(),
+        unknowns: new Map(),
+        accountsCreated: new Set(),
+        merchantsCreated: new Set(),
+        fileIds: new Set(),
+    };
+}
+function snapshotOf(state) {
+    return {
+        transactions: Array.from(state.transactions.values()),
+        unknowns: Array.from(state.unknowns.values()),
+        accountsCreated: Array.from(state.accountsCreated),
+        merchantsCreated: Array.from(state.merchantsCreated),
+        fileIds: Array.from(state.fileIds),
+    };
+}
+function sizeOf(state) {
+    let open = 0;
+    for (const u of state.unknowns.values())
+        if (u.answer === null)
+            open++;
+    return { transactions: state.transactions.size, unknowns: state.unknowns.size, openUnknowns: open };
+}
+/**
+ * The shared buffer factory. One instance per scan run — the scanner engine
+ * creates it once at the composition root and threads it to every chunk
+ * worker, audit pass, and commit phase. Mutations publish typed events on
+ * the bus so the auditor can react in flight.
+ */
+export function createBuffer(scanId, bus) {
+    const state = emptyState(scanId);
+    const mutex = createMutex();
+    const appendTransaction = (input, chunkId) => mutex.runExclusive(() => {
+        const id = `tx:${randomUUID()}`;
+        const tx = { transaction_id: id, chunkId, input };
+        state.transactions.set(id, tx);
+        bus.publish({ kind: "transaction_appended", transaction: tx, chunkId });
+        return id;
+    });
+    const updateTransaction = (id, mut) => mutex.runExclusive(() => {
+        const before = state.transactions.get(id);
+        if (!before)
+            return false;
+        const after = mut(before);
+        state.transactions.set(id, after);
+        bus.publish({ kind: "transaction_updated", transactionId: id, before, after });
+        return true;
+    });
+    const removeTransaction = (id, reason) => mutex.runExclusive(() => {
+        if (!state.transactions.delete(id))
+            return false;
+        bus.publish({ kind: "transaction_removed", transactionId: id, reason });
+        return true;
+    });
+    const appendUnknown = (input) => mutex.runExclusive(() => {
+        const id = `bu:${randomUUID()}`;
+        const u = { ...input, unknown_id: id, answer: null };
+        state.unknowns.set(id, u);
+        bus.publish({ kind: "unknown_appended", unknown: u, chunkId: u.chunkId });
+        return id;
+    });
+    const closeUnknown = (id, answer) => mutex.runExclusive(() => {
+        const u = state.unknowns.get(id);
+        if (!u || u.answer !== null)
+            return false;
+        state.unknowns.set(id, { ...u, answer });
+        bus.publish({ kind: "unknown_closed", unknownId: id, answer });
+        return true;
+    });
+    function* filterTransactions(predicate) {
+        for (const tx of state.transactions.values())
+            if (predicate(tx))
+                yield tx;
+    }
+    return {
+        scanId,
+        appendTransaction,
+        updateTransaction,
+        removeTransaction,
+        appendUnknown,
+        closeUnknown,
+        recordFile: (fileId) => { state.fileIds.add(fileId); },
+        recordAccountCreated: (accountId) => { state.accountsCreated.add(accountId); },
+        recordMerchantCreated: (merchantId) => { state.merchantsCreated.add(merchantId); },
+        snapshot: () => snapshotOf(state),
+        size: () => sizeOf(state),
+        getTransaction: (id) => state.transactions.get(id),
+        filterTransactions,
+        openUnknowns: () => Array.from(state.unknowns.values()).filter(u => u.answer === null),
+    };
+}

package/dist/scanner/buffer/sharedBuffer.d.ts

@@ -0,0 +1,78 @@
+import type { TransactionInput } from "../../db/queries/transactions.js";
+import type { EventBus } from "../audit/eventBus.js";
+/**
+ * One in-flight transaction, owned by the SharedBuffer. The id is synthesized
+ * on append so the agent can reference it later (e.g. attach a note_unknown).
+ * `chunkId` records which chunk worker created it — audit passes use this to
+ * detect cross-chunk dedup candidates and boundary continuations.
+ */
+export interface BufferedTransaction {
+    readonly transaction_id: string;
+    readonly chunkId: string;
+    input: TransactionInput;
+}
+export interface BufferedUnknown {
+    readonly unknown_id: string;
+    readonly chunkId: string | null;
+    transaction_id: string | null;
+    account_id: string | null;
+    kind: string | null;
+    prompt: string;
+    options?: string[];
+    /** Null until the auditor or review TUI closes it. */
+    answer: string | null;
+}
+export interface BufferSnapshot {
+    readonly transactions: readonly BufferedTransaction[];
+    readonly unknowns: readonly BufferedUnknown[];
+    readonly accountsCreated: readonly string[];
+    readonly merchantsCreated: readonly string[];
+    readonly fileIds: readonly string[];
+}
+/**
+ * The single in-memory ledger every chunk worker writes to during a scan run.
+ * Mutex-guarded so concurrent workers and audit passes can mutate safely; reads
+ * are lock-free. Publishes a typed event on every mutation so the Auditor can
+ * react in flight.
+ *
+ * Account and merchant creates do NOT live here — they hit the DB directly
+ * through their own per-name mutexes so parallel workers see each other's
+ * creates. The buffer just records which ones were created during this run
+ * (for the review summary and revert).
+ */
+export declare class SharedBuffer {
+    readonly scanId: string;
+    private transactions;
+    private unknowns;
+    private accountsCreated;
+    private merchantsCreated;
+    private fileIds;
+    private mutex;
+    private bus;
+    constructor(scanId: string);
+    bindEventBus(bus: EventBus): void;
+    recordFile(fileId: string): void;
+    recordAccountCreated(accountId: string): void;
+    recordMerchantCreated(merchantId: string): void;
+    appendTransaction(input: TransactionInput, chunkId: string): Promise<string>;
+    updateTransaction(id: string, mutate: (current: BufferedTransaction) => BufferedTransaction): Promise<boolean>;
+    removeTransaction(id: string, reason: string): Promise<boolean>;
+    appendUnknown(input: Omit<BufferedUnknown, "unknown_id" | "answer">): Promise<string>;
+    closeUnknown(id: string, answer: string): Promise<boolean>;
+    snapshot(): BufferSnapshot;
+    /**
+     * Snapshot of just the open (unanswered) unknowns. The review TUI's
+     * drill-down asks the user about these.
+     */
+    openUnknowns(): BufferedUnknown[];
+    /** Lookup by id without taking the mutex — readers don't need to serialize. */
+    getTransaction(id: string): BufferedTransaction | undefined;
+    /** Iterate transactions matching a filter without copying the whole map. */
+    filterTransactions(predicate: (tx: BufferedTransaction) => boolean): IterableIterator<BufferedTransaction>;
+    size(): {
+        transactions: number;
+        unknowns: number;
+        openUnknowns: number;
+    };
+    private emit;
+}

package/dist/scanner/buffer/sharedBuffer.js

@@ -0,0 +1,130 @@
+import { randomUUID } from "crypto";
+function createMutex() {
+    let chain = Promise.resolve();
+    return {
+        async runExclusive(fn) {
+            const next = chain.then(() => fn());
+            chain = next.catch(() => undefined);
+            return next;
+        },
+    };
+}
+/**
+ * The single in-memory ledger every chunk worker writes to during a scan run.
+ * Mutex-guarded so concurrent workers and audit passes can mutate safely; reads
+ * are lock-free. Publishes a typed event on every mutation so the Auditor can
+ * react in flight.
+ *
+ * Account and merchant creates do NOT live here — they hit the DB directly
+ * through their own per-name mutexes so parallel workers see each other's
+ * creates. The buffer just records which ones were created during this run
+ * (for the review summary and revert).
+ */
+export class SharedBuffer {
+    scanId;
+    transactions = new Map();
+    unknowns = new Map();
+    accountsCreated = new Set();
+    merchantsCreated = new Set();
+    fileIds = new Set();
+    mutex = createMutex();
+    bus = null;
+    constructor(scanId) {
+        this.scanId = scanId;
+    }
+    bindEventBus(bus) {
+        this.bus = bus;
+    }
+    recordFile(fileId) {
+        this.fileIds.add(fileId);
+    }
+    recordAccountCreated(accountId) {
+        this.accountsCreated.add(accountId);
+    }
+    recordMerchantCreated(merchantId) {
+        this.merchantsCreated.add(merchantId);
+    }
+    async appendTransaction(input, chunkId) {
+        return this.mutex.runExclusive(() => {
+            const id = `tx:${randomUUID()}`;
+            const tx = { transaction_id: id, chunkId, input };
+            this.transactions.set(id, tx);
+            this.emit({ kind: "transaction_appended", transaction: tx, chunkId });
+            return id;
+        });
+    }
+    async updateTransaction(id, mutate) {
+        return this.mutex.runExclusive(() => {
+            const before = this.transactions.get(id);
+            if (!before)
+                return false;
+            const after = mutate(before);
+            this.transactions.set(id, after);
+            this.emit({ kind: "transaction_updated", transactionId: id, before, after });
+            return true;
+        });
+    }
+    async removeTransaction(id, reason) {
+        return this.mutex.runExclusive(() => {
+            if (!this.transactions.delete(id))
+                return false;
+            this.emit({ kind: "transaction_removed", transactionId: id, reason });
+            return true;
+        });
+    }
+    async appendUnknown(input) {
+        return this.mutex.runExclusive(() => {
+            const id = `bu:${randomUUID()}`;
+            const u = { ...input, unknown_id: id, answer: null };
+            this.unknowns.set(id, u);
+            this.emit({ kind: "unknown_appended", unknown: u, chunkId: u.chunkId ?? "" });
+            return id;
+        });
+    }
+    async closeUnknown(id, answer) {
+        return this.mutex.runExclusive(() => {
+            const u = this.unknowns.get(id);
+            if (!u || u.answer !== null)
+                return false;
+            this.unknowns.set(id, { ...u, answer });
+            this.emit({ kind: "unknown_closed", unknownId: id, answer });
+            return true;
+        });
+    }
+    snapshot() {
+        return {
+            transactions: Array.from(this.transactions.values()),
+            unknowns: Array.from(this.unknowns.values()),
+            accountsCreated: Array.from(this.accountsCreated),
+            merchantsCreated: Array.from(this.merchantsCreated),
+            fileIds: Array.from(this.fileIds),
+        };
+    }
+    /**
+     * Snapshot of just the open (unanswered) unknowns. The review TUI's
+     * drill-down asks the user about these.
+     */
+    openUnknowns() {
+        return Array.from(this.unknowns.values()).filter(u => u.answer === null);
+    }
+    /** Lookup by id without taking the mutex — readers don't need to serialize. */
+    getTransaction(id) {
+        return this.transactions.get(id);
+    }
+    /** Iterate transactions matching a filter without copying the whole map. */
+    *filterTransactions(predicate) {
+        for (const tx of this.transactions.values())
+            if (predicate(tx))
+                yield tx;
+    }
+    size() {
+        let open = 0;
+        for (const u of this.unknowns.values())
+            if (u.answer === null)
+                open++;
+        return { transactions: this.transactions.size, unknowns: this.unknowns.size, openUnknowns: open };
+    }
+    emit(event) {
+        this.bus?.publish(event);
+    }
+}

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

@@ -0,0 +1,67 @@
+import type { TransactionInput } from "../../db/queries/transactions.js";
+/**
+ * One in-flight transaction owned by the Buffer. The id is synthesized on
+ * append so the chunk worker can reference it in the same agent turn (e.g.
+ * to attach a note_unknown). `chunkId` records who created it — audit passes
+ * use this to detect cross-chunk duplicates and boundary continuations.
+ */
+export interface BufferedTransaction {
+    readonly transaction_id: string;
+    readonly chunkId: string;
+    input: TransactionInput;
+}
+export interface BufferedUnknown {
+    readonly unknown_id: string;
+    readonly chunkId: string | null;
+    transaction_id: string | null;
+    account_id: string | null;
+    kind: string | null;
+    prompt: string;
+    options?: string[];
+    /** Null until the auditor or review TUI closes it. */
+    answer: string | null;
+}
+export interface BufferSnapshot {
+    readonly transactions: readonly BufferedTransaction[];
+    readonly unknowns: readonly BufferedUnknown[];
+    readonly accountsCreated: readonly string[];
+    readonly merchantsCreated: readonly string[];
+    readonly fileIds: readonly string[];
+}
+/**
+ * Internal state of the Buffer — held inside the createBuffer closure. Exposed
+ * for tests that need to inspect raw shape; phases use the snapshot API.
+ */
+export interface BufferState {
+    readonly scanId: string;
+    readonly transactions: Map<string, BufferedTransaction>;
+    readonly unknowns: Map<string, BufferedUnknown>;
+    readonly accountsCreated: Set<string>;
+    readonly merchantsCreated: Set<string>;
+    readonly fileIds: Set<string>;
+}
+/**
+ * Public API every consumer (chunk workers, audit passes, review TUI, commit
+ * phase) talks to. Mutations are serialized through the Buffer's internal
+ * mutex; reads (snapshot, size, filterTransactions) are lock-free.
+ */
+export interface ScanBuffer {
+    readonly scanId: string;
+    appendTransaction(input: TransactionInput, chunkId: string): Promise<string>;
+    updateTransaction(id: string, mut: (current: BufferedTransaction) => BufferedTransaction): Promise<boolean>;
+    removeTransaction(id: string, reason: string): Promise<boolean>;
+    appendUnknown(input: Omit<BufferedUnknown, "unknown_id" | "answer">): Promise<string>;
+    closeUnknown(id: string, answer: string): Promise<boolean>;
+    recordFile(fileId: string): void;
+    recordAccountCreated(accountId: string): void;
+    recordMerchantCreated(merchantId: string): void;
+    snapshot(): BufferSnapshot;
+    size(): {
+        transactions: number;
+        unknowns: number;
+        openUnknowns: number;
+    };
+    getTransaction(id: string): BufferedTransaction | undefined;
+    filterTransactions(predicate: (tx: BufferedTransaction) => boolean): IterableIterator<BufferedTransaction>;
+    openUnknowns(): BufferedUnknown[];
+}

package/dist/scanner/buffer/types.js

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