plasalid 0.7.0 → 0.7.2

package/dist/db/queries/questions.js

@@ -0,0 +1,110 @@
+import { randomUUID } from "crypto";
+/**
+ * Insert a new questions row and flip the `has_question` boolean on whichever
+ * target (transaction / account) was named. Returns the new id. The id keeps
+ * the historical `cn:` prefix — it's opaque and nothing else references it,
+ * so the prefix is a no-op detail.
+ */
+export function recordQuestion(db, input) {
+    const id = `cn:${randomUUID()}`;
+    db.prepare(`INSERT INTO questions (id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.scan_id ?? null, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null, input.context ? JSON.stringify(input.context) : null);
+    if (input.transaction_id) {
+        db.prepare(`UPDATE transactions SET has_question = 1 WHERE id = ?`).run(input.transaction_id);
+    }
+    if (input.account_id) {
+        db.prepare(`UPDATE accounts SET has_question = 1 WHERE id = ?`).run(input.account_id);
+    }
+    return id;
+}
+/**
+ * Close a question by capturing its (prompt, kind, answer) tuple and
+ * deleting the row outright. Returns the captured tuple so callers can
+ * synthesize memory rules; returns null when the id doesn't exist.
+ */
+export function closeQuestion(db, id, answer) {
+    const row = db
+        .prepare(`SELECT prompt, kind, transaction_id, account_id FROM questions WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    db.prepare(`DELETE FROM questions WHERE id = ?`).run(id);
+    maybeClearHasQuestionFlags(db, {
+        transaction_id: row.transaction_id,
+        account_id: row.account_id,
+    });
+    return { prompt: row.prompt, kind: row.kind, answer };
+}
+/**
+ * Look up the transaction/account a question is attached to. Returns null when
+ * the question id doesn't exist.
+ */
+export function getQuestionTarget(db, id) {
+    const row = db
+        .prepare(`SELECT transaction_id, account_id FROM questions WHERE id = ?`)
+        .get(id);
+    return row ?? null;
+}
+/**
+ * Clear `has_question` on the named transaction / account if no other
+ * questions still reference it. Safe to call after any resolution; idempotent.
+ */
+function maybeClearHasQuestionFlags(db, target) {
+    if (target.transaction_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM questions WHERE transaction_id = ? LIMIT 1`)
+            .get(target.transaction_id);
+        if (!open)
+            db.prepare(`UPDATE transactions SET has_question = 0 WHERE id = ?`).run(target.transaction_id);
+    }
+    if (target.account_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM questions WHERE account_id = ? LIMIT 1`)
+            .get(target.account_id);
+        if (!open)
+            db.prepare(`UPDATE accounts SET has_question = 0 WHERE id = ?`).run(target.account_id);
+    }
+}
+export function countQuestions(db, scope = {}) {
+    const conditions = [];
+    const params = [];
+    if (scope.file_id) {
+        conditions.push("file_id = ?");
+        params.push(scope.file_id);
+    }
+    if (scope.transaction_id) {
+        conditions.push("transaction_id = ?");
+        params.push(scope.transaction_id);
+    }
+    if (scope.account_id) {
+        conditions.push("account_id = ?");
+        params.push(scope.account_id);
+    }
+    if (scope.kind) {
+        conditions.push("kind = ?");
+        params.push(scope.kind);
+    }
+    if (scope.scan_id) {
+        conditions.push("scan_id = ?");
+        params.push(scope.scan_id);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM questions ${where}`)
+        .get(...params);
+    return row.n;
+}
+export function listQuestions(db, opts = {}) {
+    const capped = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    if (opts.scanId) {
+        return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+       FROM questions
+       WHERE scan_id = ?
+       ORDER BY created_at ASC
+       LIMIT ?`).all(opts.scanId, capped);
+    }
+    return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+     FROM questions
+     ORDER BY created_at ASC
+     LIMIT ?`).all(capped);
+}

package/dist/db/queries/transactions.d.ts

@@ -9,7 +9,7 @@ export interface PostingInput {
     pii_flag?: boolean;
 }
 export interface TransactionInput {
-    /** Optional pre-assigned id. Used by the buffered-write path so unknowns recorded mid-scan can reference the transaction before commit. */
+    /** Optional pre-assigned id. Used by the buffered-write path so questions recorded mid-scan can reference the transaction before commit. */
     id?: string;
     date: string;
     description: string;

package/dist/db/queries/unknowns.d.ts

@@ -5,6 +5,7 @@ export interface UnknownTarget {
 }
 export interface RecordUnknownInput extends UnknownTarget {
     file_id: string | null;
+    scan_id?: string | null;
     kind?: string | null;
     prompt: string;
     options?: string[];
@@ -13,6 +14,7 @@ export interface RecordUnknownInput extends UnknownTarget {
 }
 export interface OpenUnknownRow {
     id: string;
+    scan_id: string | null;
     file_id: string | null;
     transaction_id: string | null;
     account_id: string | null;
@@ -22,6 +24,11 @@ export interface OpenUnknownRow {
     context_json: string | null;
     created_at: string;
 }
+export interface ClosedUnknown {
+    prompt: string;
+    kind: string | null;
+    answer: string;
+}
 /**
  * Insert a new unknowns row and flip the `has_unknown` boolean on whichever
  * target (transaction / account) was named. Returns the new id. The id keeps
@@ -30,11 +37,11 @@ export interface OpenUnknownRow {
  */
 export declare function recordUnknown(db: Database.Database, input: RecordUnknownInput): string;
 /**
- * Mark an existing unknown as resolved with the user's answer and, if no other
- * open unknowns reference the same target, clear the target's `has_unknown`
- * flag. Returns the unknown's target so callers can log or react.
+ * Close an open unknown by capturing its (prompt, kind, answer) tuple and
+ * deleting the row outright. Returns the captured tuple so callers can
+ * synthesize memory rules; returns null when the unknown id is unknown.
  */
-export declare function resolveUnknown(db: Database.Database, id: string, answer: string): UnknownTarget | null;
+export declare function closeUnknown(db: Database.Database, id: string, answer: string): ClosedUnknown | null;
 /**
  * Look up the transaction/account an unknown is attached to. Returns null when
  * the unknown id doesn't exist.
@@ -45,16 +52,11 @@ export interface CountOpenUnknownsScope {
     transaction_id?: string;
     account_id?: string;
     kind?: string;
+    scan_id?: string;
 }
 export declare function countOpenUnknowns(db: Database.Database, scope?: CountOpenUnknownsScope): number;
-export declare function listOpenUnknowns(db: Database.Database, limit?: number): OpenUnknownRow[];
-/**
- * Open unknowns filtered by `kind`, ordered by the position of the kind in the
- * input array (priority) then by created_at. Pass `["uncategorized","duplicate"]`
- * to drain uncategorized rows before duplicates.
- *
- * `kind` is free-text TEXT in the schema; canonical values used by built-ins:
- *   uncategorized, duplicate, correlation, recurrence_candidate,
- *   similar_accounts, file_password
- */
-export declare function listOpenUnknownsByKind(db: Database.Database, kinds: string[], limit?: number): OpenUnknownRow[];
+export interface ListOpenUnknownsOptions {
+    limit?: number;
+    scanId?: string;
+}
+export declare function listOpenUnknowns(db: Database.Database, opts?: ListOpenUnknownsOptions): OpenUnknownRow[];

package/dist/db/queries/unknowns.js

@@ -7,7 +7,8 @@ import { randomUUID } from "crypto";
  */
 export function recordUnknown(db, input) {
     const id = `cn:${randomUUID()}`;
-    db.prepare(`INSERT INTO unknowns (id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null, input.context ? JSON.stringify(input.context) : null);
+    db.prepare(`INSERT INTO unknowns (id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.scan_id ?? null, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null, input.context ? JSON.stringify(input.context) : null);
     if (input.transaction_id) {
         db.prepare(`UPDATE transactions SET has_unknown = 1 WHERE id = ?`).run(input.transaction_id);
     }
@@ -17,17 +18,22 @@ export function recordUnknown(db, input) {
     return id;
 }
 /**
- * Mark an existing unknown as resolved with the user's answer and, if no other
- * open unknowns reference the same target, clear the target's `has_unknown`
- * flag. Returns the unknown's target so callers can log or react.
+ * Close an open unknown by capturing its (prompt, kind, answer) tuple and
+ * deleting the row outright. Returns the captured tuple so callers can
+ * synthesize memory rules; returns null when the unknown id is unknown.
  */
-export function resolveUnknown(db, id, answer) {
-    const target = getUnknownTarget(db, id);
-    if (!target)
+export function closeUnknown(db, id, answer) {
+    const row = db
+        .prepare(`SELECT prompt, kind, transaction_id, account_id FROM unknowns WHERE id = ?`)
+        .get(id);
+    if (!row)
         return null;
-    db.prepare(`UPDATE unknowns SET answer = ?, resolved_at = datetime('now') WHERE id = ?`).run(answer, id);
-    maybeClearHasUnknownFlags(db, target);
-    return target;
+    db.prepare(`DELETE FROM unknowns WHERE id = ?`).run(id);
+    maybeClearHasUnknownFlags(db, {
+        transaction_id: row.transaction_id,
+        account_id: row.account_id,
+    });
+    return { prompt: row.prompt, kind: row.kind, answer };
 }
 /**
  * Look up the transaction/account an unknown is attached to. Returns null when
@@ -46,21 +52,21 @@ export function getUnknownTarget(db, id) {
 function maybeClearHasUnknownFlags(db, target) {
     if (target.transaction_id) {
         const open = db
-            .prepare(`SELECT 1 FROM unknowns WHERE transaction_id = ? AND resolved_at IS NULL LIMIT 1`)
+            .prepare(`SELECT 1 FROM unknowns WHERE transaction_id = ? LIMIT 1`)
             .get(target.transaction_id);
         if (!open)
             db.prepare(`UPDATE transactions SET has_unknown = 0 WHERE id = ?`).run(target.transaction_id);
     }
     if (target.account_id) {
         const open = db
-            .prepare(`SELECT 1 FROM unknowns WHERE account_id = ? AND resolved_at IS NULL LIMIT 1`)
+            .prepare(`SELECT 1 FROM unknowns WHERE account_id = ? LIMIT 1`)
             .get(target.account_id);
         if (!open)
             db.prepare(`UPDATE accounts SET has_unknown = 0 WHERE id = ?`).run(target.account_id);
     }
 }
 export function countOpenUnknowns(db, scope = {}) {
-    const conditions = ["resolved_at IS NULL"];
+    const conditions = [];
     const params = [];
     if (scope.file_id) {
         conditions.push("file_id = ?");
@@ -78,37 +84,27 @@ export function countOpenUnknowns(db, scope = {}) {
         conditions.push("kind = ?");
         params.push(scope.kind);
     }
+    if (scope.scan_id) {
+        conditions.push("scan_id = ?");
+        params.push(scope.scan_id);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
     const row = db
-        .prepare(`SELECT COUNT(*) AS n FROM unknowns WHERE ${conditions.join(" AND ")}`)
+        .prepare(`SELECT COUNT(*) AS n FROM unknowns ${where}`)
         .get(...params);
     return row.n;
 }
-export function listOpenUnknowns(db, limit = 50) {
-    const capped = Math.min(Math.max(limit, 1), 200);
-    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+export function listOpenUnknowns(db, opts = {}) {
+    const capped = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    if (opts.scanId) {
+        return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+       FROM unknowns
+       WHERE scan_id = ?
+       ORDER BY created_at ASC
+       LIMIT ?`).all(opts.scanId, capped);
+    }
+    return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
      FROM unknowns
-     WHERE resolved_at IS NULL
      ORDER BY created_at ASC
      LIMIT ?`).all(capped);
 }
-/**
- * Open unknowns filtered by `kind`, ordered by the position of the kind in the
- * input array (priority) then by created_at. Pass `["uncategorized","duplicate"]`
- * to drain uncategorized rows before duplicates.
- *
- * `kind` is free-text TEXT in the schema; canonical values used by built-ins:
- *   uncategorized, duplicate, correlation, recurrence_candidate,
- *   similar_accounts, file_password
- */
-export function listOpenUnknownsByKind(db, kinds, limit = 50) {
-    if (kinds.length === 0)
-        return [];
-    const capped = Math.min(Math.max(limit, 1), 200);
-    const placeholders = kinds.map(() => "?").join(",");
-    const cases = kinds.map((_, i) => `WHEN ? THEN ${i}`).join(" ");
-    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
-     FROM unknowns
-     WHERE resolved_at IS NULL AND kind IN (${placeholders})
-     ORDER BY CASE kind ${cases} ELSE ${kinds.length} END, created_at ASC
-     LIMIT ?`).all(...kinds, ...kinds, capped);
-}

package/dist/db/schema.js

@@ -14,7 +14,7 @@ export function migrate(db) {
       points_balance REAL,
       metadata_json TEXT,
       pii_flag INTEGER NOT NULL DEFAULT 0,
-      has_unknown INTEGER NOT NULL DEFAULT 0,
+      has_question INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
@@ -74,7 +74,7 @@ export function migrate(db) {
       source_file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
       source_page INTEGER,
       recurrence_id TEXT REFERENCES recurrences(id) ON DELETE SET NULL,
-      has_unknown INTEGER NOT NULL DEFAULT 0,
+      has_question INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
@@ -98,8 +98,9 @@ export function migrate(db) {
     CREATE INDEX IF NOT EXISTS postings_transaction_idx ON postings(transaction_id);
     CREATE INDEX IF NOT EXISTS postings_account_idx ON postings(account_id);
 
-    CREATE TABLE IF NOT EXISTS unknowns (
+    CREATE TABLE IF NOT EXISTS questions (
       id TEXT PRIMARY KEY,
+      scan_id TEXT,
       file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
       transaction_id TEXT REFERENCES transactions(id) ON DELETE CASCADE,
       account_id TEXT REFERENCES accounts(id) ON DELETE CASCADE,
@@ -112,6 +113,8 @@ export function migrate(db) {
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE INDEX IF NOT EXISTS questions_scan_idx ON questions(scan_id);
+
     CREATE TABLE IF NOT EXISTS conversation_history (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       role TEXT NOT NULL,
@@ -139,30 +142,5 @@ export function migrate(db) {
       use_count INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
-
-    CREATE TABLE IF NOT EXISTS action_log (
-      id TEXT PRIMARY KEY,
-      correlation_id TEXT NOT NULL,
-      command TEXT NOT NULL,
-      user_input TEXT,
-      action_type TEXT NOT NULL CHECK(action_type IN (
-        'create_account','update_account_metadata','record_transaction','adjust_balance',
-        'create_merchant','update_merchant_default'
-      )),
-      target_id TEXT NOT NULL,
-      payload_json TEXT NOT NULL,
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      reverted_at TEXT
-    );
-
-    CREATE INDEX IF NOT EXISTS action_log_correlation_idx ON action_log(correlation_id);
-    CREATE INDEX IF NOT EXISTS action_log_created_idx ON action_log(created_at);
   `);
-    ensureColumn(db, "unknowns", "context_json", "TEXT");
-}
-function ensureColumn(db, table, column, type) {
-    const cols = db.prepare(`PRAGMA table_info(${table})`).all();
-    if (cols.some((c) => c.name === column))
-        return;
-    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
 }

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

@@ -0,0 +1,31 @@
+import type Database from "libsql";
+import type { EventBus } from "./eventBus.js";
+import type { SharedBuffer } from "../buffer/sharedBuffer.js";
+import type { AuditPass } from "./passes/types.js";
+/**
+ * The Auditor subscribes to the EventBus and dispatches every event through
+ * a registered list of AuditPass instances. Events queue serially so passes
+ * don't race each other — within one event, every pass runs to completion
+ * before the next event is processed. This makes pass ordering deterministic
+ * (memory rule before merchant default, etc.).
+ *
+ * `drain()` resolves only when the queue is empty AND no pass is in flight —
+ * the parse phase calls it after all chunk workers complete so we don't
+ * commit while the auditor still has work pending.
+ */
+export declare class Auditor {
+    private readonly ctx;
+    private readonly passes;
+    private readonly bus;
+    private queue;
+    private running;
+    private unsubscribe;
+    private idleResolvers;
+    constructor(db: Database.Database, buffer: SharedBuffer, bus: EventBus, passes: readonly AuditPass[]);
+    get tally(): Readonly<Record<string, number>>;
+    start(): void;
+    stop(): void;
+    /** Resolves once the queue empties and no pass is currently in flight. */
+    drain(): Promise<void>;
+    private tick;
+}

package/dist/scanner/audit/auditor.js

@@ -0,0 +1,72 @@
+/**
+ * The Auditor subscribes to the EventBus and dispatches every event through
+ * a registered list of AuditPass instances. Events queue serially so passes
+ * don't race each other — within one event, every pass runs to completion
+ * before the next event is processed. This makes pass ordering deterministic
+ * (memory rule before merchant default, etc.).
+ *
+ * `drain()` resolves only when the queue is empty AND no pass is in flight —
+ * the parse phase calls it after all chunk workers complete so we don't
+ * commit while the auditor still has work pending.
+ */
+export class Auditor {
+    ctx;
+    passes;
+    bus;
+    queue = [];
+    running = false;
+    unsubscribe = null;
+    idleResolvers = [];
+    constructor(db, buffer, bus, passes) {
+        this.bus = bus;
+        this.passes = passes;
+        this.ctx = { db, buffer, tally: {} };
+    }
+    get tally() {
+        return this.ctx.tally;
+    }
+    start() {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = this.bus.subscribe(event => {
+            this.queue.push(event);
+            void this.tick();
+        });
+    }
+    stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+    }
+    /** Resolves once the queue empties and no pass is currently in flight. */
+    async drain() {
+        if (!this.running && this.queue.length === 0)
+            return;
+        return new Promise(resolve => { this.idleResolvers.push(resolve); });
+    }
+    async tick() {
+        if (this.running)
+            return;
+        this.running = true;
+        try {
+            while (this.queue.length > 0) {
+                const event = this.queue.shift();
+                for (const pass of this.passes) {
+                    if (!pass.handles(event))
+                        continue;
+                    try {
+                        await pass.apply(event, this.ctx);
+                    }
+                    catch (err) {
+                        console.error(`[auditor pass ${pass.name}] ${err.message}`);
+                    }
+                }
+            }
+        }
+        finally {
+            this.running = false;
+            const resolvers = this.idleResolvers.splice(0);
+            for (const r of resolvers)
+                r();
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { AuditEngine, AuditEngineDeps } from "./types.js";
+/**
+ * The in-flight audit engine. Subscribes to the bus, serializes events
+ * through a single async queue (deterministic pass ordering), and exposes
+ * drain() so the scanner engine can wait for the queue to empty between
+ * the parse phase and the review phase.
+ *
+ * No class, no `this` — every piece of state lives in the closure.
+ */
+export declare function createAuditEngine(deps: AuditEngineDeps): AuditEngine;

package/dist/scanner/audit/engine.js

@@ -0,0 +1,98 @@
+/**
+ * Precompute event-kind → handlers so dispatch doesn't iterate every pass
+ * for every event. New event kinds added later still go through this map,
+ * via the empty-array fallback.
+ */
+function buildPassIndex(passes) {
+    const index = new Map();
+    const probeKinds = [
+        "transaction_appended", "transaction_updated", "transaction_removed",
+        "unknown_appended", "unknown_closed",
+        "chunk_started", "chunk_completed", "worker_completed",
+    ];
+    for (const kind of probeKinds) {
+        const matching = passes.filter(p => probeHandles(p, kind));
+        if (matching.length > 0)
+            index.set(kind, matching);
+    }
+    return index;
+}
+/**
+ * Ask a pass if it handles a synthetic probe event for the given kind. We
+ * only care about the discriminator, so the rest of the fields can be dummy
+ * values — passes are expected to switch on `event.kind` and ignore shape.
+ */
+function probeHandles(pass, kind) {
+    const probe = { kind };
+    try {
+        return pass.handles(probe);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The in-flight audit engine. Subscribes to the bus, serializes events
+ * through a single async queue (deterministic pass ordering), and exposes
+ * drain() so the scanner engine can wait for the queue to empty between
+ * the parse phase and the review phase.
+ *
+ * No class, no `this` — every piece of state lives in the closure.
+ */
+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 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)
+                    continue;
+                for (const pass of handlers) {
+                    try {
+                        await pass.apply(event, ctx);
+                    }
+                    catch (err) {
+                        console.error(`[audit pass ${pass.name}] ${err.message}`);
+                    }
+                }
+            }
+        }
+        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; },
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { BufferedTransaction, BufferedUnknown, BufferSnapshot } from "../buffer/sharedBuffer.js";
+/**
+ * Typed event stream the SharedBuffer publishes and the Auditor subscribes to.
+ * Every buffer mutation produces an event so audit passes can react in flight
+ * instead of running as a post-commit sweep.
+ */
+export type BufferEvent = {
+    kind: "transaction_appended";
+    transaction: BufferedTransaction;
+    chunkId: string;
+} | {
+    kind: "transaction_updated";
+    transactionId: string;
+    before: BufferedTransaction;
+    after: BufferedTransaction;
+} | {
+    kind: "transaction_removed";
+    transactionId: string;
+    reason: string;
+} | {
+    kind: "unknown_appended";
+    unknown: BufferedUnknown;
+    chunkId: string;
+} | {
+    kind: "unknown_closed";
+    unknownId: string;
+    answer: string;
+} | {
+    kind: "chunk_started";
+    chunkId: string;
+    fileId: string;
+    pageNumber: number;
+} | {
+    kind: "chunk_completed";
+    chunkId: string;
+    fileId: string;
+    pageNumber: number;
+} | {
+    kind: "worker_completed";
+    workerId: string;
+    chunkId: string;
+    transactionsAdded: number;
+    unknownsAdded: number;
+};
+export type EventListener = (event: BufferEvent) => void | Promise<void>;
+export declare class EventBus {
+    private listeners;
+    private buffered;
+    subscribe(fn: EventListener): () => void;
+    /**
+     * Publish an event to every listener. Listener errors are caught and logged —
+     * a misbehaving pass never silences the bus for the rest.
+     */
+    publish(event: BufferEvent): void;
+    /** All events seen so far, in publish order. Useful for the review TUI summary. */
+    history(): readonly BufferEvent[];
+    /** Test helper. */
+    reset(): void;
+}
+export type { BufferSnapshot };