aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/daemon/triggers/email/imapConnection.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/imapConnection.ts — v4.5 Phase 4a.
+ *
+ * Thin wrapper around imap-simple. Adds:
+ *   - exponential backoff reconnect (1s → 60s capped at 60s)
+ *   - IMAP ID command on connect (defends against servers that
+ *     disconnect unidentified clients — see audit §8)
+ *   - UIDVALIDITY tracking for cross-restart UID correctness
+ *   - typed Promise interface (imap-simple's surface is mostly
+ *     callback-shaped underneath)
+ *
+ * Lifecycle:
+ *   const ic = createImapConnection(spec.imap, log);
+ *   await ic.connect();
+ *   await ic.openMailbox(spec.mailbox);
+ *   const uids = await ic.searchAll();              // seed seenUids
+ *   const unseen = await ic.searchUnseen();         // poll
+ *   const msg = await ic.fetchMessage(uid);
+ *   await ic.markSeen(uid);
+ *   await ic.disconnect();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKOFF_CONSTANTS = void 0;
+exports.createImapConnection = createImapConnection;
+exports.nextBackoffMs = nextBackoffMs;
+const imaps = __importStar(require("imap-simple"));
+const version_1 = require("../../../../version");
+const BACKOFF_INITIAL_MS = 1000;
+const BACKOFF_MAX_MS = 60000;
+const BACKOFF_MULTIPLIER = 2;
+const noopLog = (_l, _m) => undefined;
+function createImapConnection(opts) {
+    const cfg = opts.config;
+    const log = opts.log ?? noopLog;
+    let conn = null;
+    let backoffMs = BACKOFF_INITIAL_MS;
+    let currentMailbox = null;
+    let currentUidValidity = 0;
+    const buildConfig = () => ({
+        imap: {
+            host: cfg.host,
+            port: cfg.port,
+            user: cfg.user,
+            password: cfg.password,
+            tls: cfg.tls,
+            authTimeout: cfg.authTimeoutMs,
+            // Reasonable production defaults — imap-simple passes these to node-imap.
+            tlsOptions: { rejectUnauthorized: true },
+        },
+    });
+    const sendIdCommand = (c) => new Promise((resolve) => {
+        // imap-simple exposes the raw node-imap Connection via .imap.
+        // Some servers (NetEase 163) disconnect without an ID exchange:
+        //   "BYE Unsafe Login. Please contact kefu@188.com for help".
+        // Apply unconditionally — other servers ignore it.
+        try {
+            const c2 = c;
+            if (c2.imap?.id) {
+                c2.imap.id({ name: 'Aiden', version: version_1.VERSION, vendor: 'Taracod' }, (_err) => resolve());
+            }
+            else {
+                resolve();
+            }
+        }
+        catch {
+            // Older imap-simple versions don't expose .id — treat as no-op.
+            resolve();
+        }
+    });
+    return {
+        async connect() {
+            try {
+                conn = await imaps.connect(buildConfig());
+                await sendIdCommand(conn);
+                backoffMs = BACKOFF_INITIAL_MS; // reset on success
+                log('info', `[email] imap connected (${cfg.host}:${cfg.port} ${cfg.user})`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                log('error', `[email] imap connect failed: ${msg}`);
+                throw e;
+            }
+        },
+        async disconnect() {
+            if (!conn)
+                return;
+            try {
+                conn.end();
+            }
+            catch { /* best-effort */ }
+            conn = null;
+            currentMailbox = null;
+            currentUidValidity = 0;
+        },
+        isConnected() {
+            return conn !== null;
+        },
+        async openMailbox(mailbox) {
+            if (!conn)
+                throw new Error('[email] not connected');
+            // imap-simple openBox typed surface is awkward — accept Mailbox
+            // object back.
+            const box = await conn.openBox(mailbox);
+            currentMailbox = mailbox;
+            currentUidValidity = box.uidvalidity ?? 0;
+            return { uidValidity: currentUidValidity };
+        },
+        async searchAll() {
+            if (!conn)
+                throw new Error('[email] not connected');
+            const results = await conn.search(['ALL'], { bodies: ['HEADER.FIELDS (MESSAGE-ID)'], markSeen: false });
+            return results.map((r) => r.attributes.uid);
+        },
+        async searchUnseen() {
+            if (!conn)
+                throw new Error('[email] not connected');
+            const results = await conn.search(['UNSEEN'], { bodies: ['HEADER.FIELDS (MESSAGE-ID)'], markSeen: false });
+            return results.map((r) => r.attributes.uid);
+        },
+        async fetchMessage(uid) {
+            if (!conn)
+                throw new Error('[email] not connected');
+            try {
+                const fetched = await conn.search([['UID', String(uid)]], {
+                    // Fetch full RFC822 source — mailparser handles MIME.
+                    bodies: [''],
+                    markSeen: false,
+                });
+                if (fetched.length === 0)
+                    return null;
+                const m = fetched[0];
+                const part = m.parts.find((p) => p.which === '');
+                if (!part)
+                    return null;
+                const raw = Buffer.isBuffer(part.body) ? part.body : Buffer.from(part.body, 'utf-8');
+                return {
+                    uid: m.attributes.uid,
+                    raw,
+                    flags: m.attributes.flags ?? [],
+                    internalDate: m.attributes.date ?? new Date(),
+                };
+            }
+            catch (e) {
+                log('warn', `[email] fetch uid ${uid} failed: ${e instanceof Error ? e.message : String(e)}`);
+                return null;
+            }
+        },
+        async markSeen(uid) {
+            if (!conn)
+                throw new Error('[email] not connected');
+            try {
+                await conn.addFlags(uid, '\\Seen');
+            }
+            catch (e) {
+                log('warn', `[email] markSeen uid ${uid} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        },
+    };
+}
+/**
+ * Compute the next exponential-backoff delay given the previous one.
+ * Pure — used by the orchestrator's reconnect loop.
+ */
+function nextBackoffMs(prev) {
+    return Math.min(BACKOFF_MAX_MS, Math.max(BACKOFF_INITIAL_MS, prev * BACKOFF_MULTIPLIER));
+}
+exports.BACKOFF_CONSTANTS = Object.freeze({
+    initialMs: BACKOFF_INITIAL_MS,
+    maxMs: BACKOFF_MAX_MS,
+    multiplier: BACKOFF_MULTIPLIER,
+});

package/dist/core/v4/daemon/triggers/email/index.js

@@ -0,0 +1,332 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/index.ts — v4.5 Phase 4a.
+ *
+ * Email IMAP trigger orchestrator. Wires together the supporting
+ * modules:
+ *   - imapConnection.ts       — IMAP wrapper + reconnect
+ *   - automatedSender.ts      — noreply/bounce filter
+ *   - allowlist.ts            — per-trigger sender allowlist
+ *   - bodyExtractor.ts        — mailparser + text/attachment extraction
+ *   - emailSeenStore.ts       — SQLite forensic table
+ *   - seenUids.ts             — in-memory bounded dedup set
+ *
+ * Public API: `createEmailTrigger(opts) → EmailTriggerHandle`.
+ *
+ * Lifecycle per trigger (one trigger = one IMAP connection):
+ *   1. Connect, ID command, open mailbox, capture UIDVALIDITY.
+ *   2. Seed seenUids from UID SEARCH ALL — all pre-existing messages
+ *      are SKIPPED on first run; reconcile-equivalent of the file
+ *      watcher's skip_existing default.
+ *   3. Poll loop (spec.pollIntervalMs):
+ *      a. UID SEARCH UNSEEN
+ *      b. For each new UID not in seenUids:
+ *         - fetchMessage(uid) → raw bytes
+ *         - mailparser → headers + body + attachments
+ *         - isAutomatedSender? → skip (status='skipped_automated')
+ *         - allowlist.isAllowed? if not → skip (status='skipped_unauth')
+ *         - allowedSubjectPatterns? if mismatched → skip
+ *           (status='skipped_subject')
+ *         - extractEmailBody(raw, policy)
+ *         - INSIDE A DB TRANSACTION:
+ *             triggerBus.insert(...) → eventId
+ *             emailSeenStore.record(... status='processed', eventId)
+ *         - Only AFTER the tx commit: markSeen(uid) on the server.
+ *           Order matters — crash mid-write loses our record but
+ *           the server flag is still unset, so next poll re-fetches.
+ *      c. seenUids.add(uid) in every branch (skip + processed)
+ *   4. On error: log, close connection, backoff, reconnect.
+ *   5. On shutdown: resourceRegistry.close() → disconnect.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmailTrigger = createEmailTrigger;
+const mailparser_1 = require("mailparser");
+const imapConnection_1 = require("./imapConnection");
+const emailSeenStore_1 = require("./emailSeenStore");
+const seenUids_1 = require("./seenUids");
+const allowlist_1 = require("./allowlist");
+const automatedSender_1 = require("./automatedSender");
+const bodyExtractor_1 = require("./bodyExtractor");
+const noopLog = (_l, _m) => undefined;
+const DEGRADED_FAILURE_THRESHOLD = 5;
+function createEmailTrigger(opts) {
+    const log = opts.log ?? noopLog;
+    const seenUids = (0, seenUids_1.createSeenUids)();
+    const allowlist = (0, allowlist_1.compileSenderAllowlist)(opts.spec.allowedSenders);
+    const subjectRegexes = (opts.spec.allowedSubjectPatterns ?? [])
+        .map((s) => new RegExp(s));
+    const seenStore = opts.emailSeenStore ?? (0, emailSeenStore_1.createEmailSeenStore)({ db: opts.db });
+    const stats = {
+        connected: false,
+        totalPolls: 0,
+        totalMessages: 0,
+        skippedAutomated: 0,
+        skippedUnauth: 0,
+        skippedSubject: 0,
+        processed: 0,
+        consecutiveFailures: 0,
+        lastPollAt: null,
+        lastError: null,
+        degraded: false,
+    };
+    const connection = (opts.connectionFactory
+        ? opts.connectionFactory(opts.spec.imap, log)
+        : (0, imapConnection_1.createImapConnection)({ config: opts.spec.imap, log }));
+    let paused = false;
+    let stopped = false;
+    let pollTimer = null;
+    let backoffMs = imapConnection_1.BACKOFF_CONSTANTS.initialMs;
+    let currentUidValidity = 0;
+    const runConnect = async () => {
+        try {
+            await connection.connect();
+            const box = await connection.openMailbox(opts.spec.mailbox);
+            currentUidValidity = box.uidValidity;
+            stats.connected = true;
+            stats.consecutiveFailures = 0;
+            stats.degraded = false;
+            backoffMs = imapConnection_1.BACKOFF_CONSTANTS.initialMs;
+            // Seed seenUids from UID SEARCH ALL — all pre-existing UIDs
+            // are SKIPPED, not processed. (Matches the file-watcher
+            // skip_existing default.)
+            try {
+                const all = await connection.searchAll();
+                seenUids.seed(all);
+                log('info', `[email] ${opts.watcherId} seeded ${all.length} pre-existing UIDs (UIDVALIDITY=${currentUidValidity})`);
+            }
+            catch (e) {
+                log('warn', `[email] ${opts.watcherId} seed failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return true;
+        }
+        catch (e) {
+            stats.connected = false;
+            stats.consecutiveFailures += 1;
+            stats.lastError = e instanceof Error ? e.message : String(e);
+            if (stats.consecutiveFailures >= DEGRADED_FAILURE_THRESHOLD) {
+                stats.degraded = true;
+            }
+            return false;
+        }
+    };
+    const processOne = async (uid) => {
+        stats.totalMessages += 1;
+        const fetched = await connection.fetchMessage(uid);
+        if (!fetched) {
+            // Message vanished (deleted between search + fetch). Mark it
+            // seen so we don't loop.
+            seenUids.add(uid);
+            return;
+        }
+        // Parse just enough headers + body to make the filter decision.
+        // We pass the raw bytes onward to extractEmailBody (which calls
+        // simpleParser again — accepted tradeoff: mailparser is fast
+        // enough for typical email sizes and the surface stays clean).
+        const parsed = await (0, mailparser_1.simpleParser)(fetched.raw).catch(() => null);
+        if (!parsed) {
+            stats.lastError = `parse failure for uid ${uid}`;
+            seenStore.record({
+                routeId: opts.watcherId,
+                mailbox: opts.spec.mailbox,
+                uidValidity: currentUidValidity,
+                uid,
+                messageId: null,
+                fromAddress: null,
+                subject: null,
+                receivedAt: fetched.internalDate.getTime(),
+                triggerEventId: null,
+                status: 'failed',
+            });
+            seenUids.add(uid);
+            return;
+        }
+        const fromAddress = parsed.from?.value?.[0]?.address ?? '';
+        const messageId = parsed.messageId ?? null;
+        const subject = parsed.subject ?? null;
+        const receivedAt = (parsed.date ?? fetched.internalDate).getTime();
+        // Normalize headers to a plain string→string map for our filter.
+        const headers = {};
+        for (const [k, v] of parsed.headers.entries()) {
+            headers[k.toLowerCase()] = Array.isArray(v) ? String(v[0] ?? '') : String(v);
+        }
+        const skipReason = (0, automatedSender_1.isAutomatedSender)(fromAddress, headers) ? 'skipped_automated' :
+            !allowlist.isAllowed(fromAddress) ? 'skipped_unauth' :
+                (subjectRegexes.length > 0 && !subjectRegexes.some((r) => subject != null && r.test(subject)))
+                    ? 'skipped_subject' :
+                    null;
+        if (skipReason) {
+            if (skipReason === 'skipped_automated')
+                stats.skippedAutomated += 1;
+            if (skipReason === 'skipped_unauth')
+                stats.skippedUnauth += 1;
+            if (skipReason === 'skipped_subject')
+                stats.skippedSubject += 1;
+            seenStore.record({
+                routeId: opts.watcherId,
+                mailbox: opts.spec.mailbox,
+                uidValidity: currentUidValidity,
+                uid,
+                messageId,
+                fromAddress,
+                subject,
+                receivedAt,
+                triggerEventId: null,
+                status: skipReason,
+            });
+            seenUids.add(uid);
+            // For unauth/automated: DO NOT mark \Seen on server — leave
+            // the message as unread so the human user sees it in their
+            // mail client. (Per audit §6.)
+            return;
+        }
+        // Extract body + attachments per policy.
+        const body = await (0, bodyExtractor_1.extractEmailBody)({
+            raw: fetched.raw,
+            maxBodyBytes: opts.spec.maxBodyBytes,
+            attachmentPolicy: opts.spec.attachmentPolicy,
+        });
+        // Single tx: trigger_events insert + email_seen record. This
+        // sequence is the lesson from the audit — persist locally BEFORE
+        // marking \Seen on the server. Crash between tx and markSeen
+        // means next poll re-fetches; better than losing record.
+        const tx = opts.db.transaction(() => {
+            const insertResult = opts.triggerBus.insert({
+                source: 'email',
+                sourceKey: opts.watcherId,
+                idempotencyKey: `${currentUidValidity}::${uid}::${messageId ?? ''}`,
+                payload: {
+                    from: fromAddress,
+                    subject,
+                    body: body.text,
+                    truncated: body.truncated,
+                    textKind: body.textKind,
+                    quotedReplyStripped: body.quotedReplyStripped,
+                    messageId,
+                    inReplyTo: parsed.inReplyTo ?? null,
+                    references: parsed.references ?? null,
+                    receivedAt,
+                    mailbox: opts.spec.mailbox,
+                    attachments: body.attachments,
+                    headers,
+                    deliveryMode: opts.spec.deliverOnly ? 'deliver_only' : 'agent',
+                },
+            });
+            seenStore.record({
+                routeId: opts.watcherId,
+                mailbox: opts.spec.mailbox,
+                uidValidity: currentUidValidity,
+                uid,
+                messageId,
+                fromAddress,
+                subject,
+                receivedAt,
+                triggerEventId: insertResult.id,
+                status: 'processed',
+            });
+            return { eventId: insertResult.id };
+        });
+        tx();
+        // AFTER the tx commits: mark \Seen on the IMAP server.
+        await connection.markSeen(uid);
+        seenUids.add(uid);
+        stats.processed += 1;
+    };
+    const pollOnce = async () => {
+        if (paused || stopped)
+            return;
+        if (!connection.isConnected()) {
+            const ok = await runConnect();
+            if (!ok) {
+                log('warn', `[email] ${opts.watcherId} reconnect backoff ${backoffMs}ms`);
+                scheduleNext(backoffMs);
+                backoffMs = (0, imapConnection_1.nextBackoffMs)(backoffMs);
+                return;
+            }
+        }
+        stats.lastPollAt = Date.now();
+        stats.totalPolls += 1;
+        try {
+            const uids = await connection.searchUnseen();
+            for (const uid of uids) {
+                if (paused || stopped)
+                    break;
+                if (seenUids.has(uid))
+                    continue;
+                try {
+                    await processOne(uid);
+                }
+                catch (e) {
+                    stats.lastError = e instanceof Error ? e.message : String(e);
+                    log('error', `[email] ${opts.watcherId} processOne uid ${uid} failed: ${stats.lastError}`);
+                }
+            }
+            stats.consecutiveFailures = 0;
+            backoffMs = imapConnection_1.BACKOFF_CONSTANTS.initialMs;
+            scheduleNext(opts.spec.pollIntervalMs);
+        }
+        catch (e) {
+            stats.connected = false;
+            stats.consecutiveFailures += 1;
+            stats.lastError = e instanceof Error ? e.message : String(e);
+            if (stats.consecutiveFailures >= DEGRADED_FAILURE_THRESHOLD) {
+                stats.degraded = true;
+            }
+            try {
+                await connection.disconnect();
+            }
+            catch { /* noop */ }
+            log('warn', `[email] ${opts.watcherId} poll error: ${stats.lastError}; backoff ${backoffMs}ms`);
+            scheduleNext(backoffMs);
+            backoffMs = (0, imapConnection_1.nextBackoffMs)(backoffMs);
+        }
+    };
+    const scheduleNext = (ms) => {
+        if (pollTimer) {
+            clearTimeout(pollTimer);
+            pollTimer = null;
+        }
+        if (stopped)
+            return;
+        pollTimer = setTimeout(() => { void pollOnce(); }, ms);
+        if (typeof pollTimer.unref === 'function')
+            pollTimer.unref();
+    };
+    // Kick off the first poll cycle async — return the handle synchronously.
+    void pollOnce();
+    const close = async () => {
+        stopped = true;
+        if (pollTimer) {
+            clearTimeout(pollTimer);
+            pollTimer = null;
+        }
+        try {
+            await connection.disconnect();
+        }
+        catch { /* best-effort */ }
+        stats.connected = false;
+    };
+    const resourceId = opts.registry.register({
+        kind: 'imap_connection',
+        owner: opts.watcherId,
+        metadata: { host: opts.spec.imap.host, user: opts.spec.imap.user, mailbox: opts.spec.mailbox },
+        close,
+    });
+    return {
+        watcherId: opts.watcherId,
+        resourceId,
+        pause() { paused = true; },
+        resume() {
+            paused = false;
+            // Re-arm immediately on resume.
+            scheduleNext(0);
+        },
+        close,
+        stats() { return { ...stats }; },
+    };
+}

package/dist/core/v4/daemon/triggers/email/seenUids.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/seenUids.ts — v4.5 Phase 4a.
+ *
+ * In-memory bounded UID dedup set. Hot-path "have we seen this
+ * UID in the current daemon session?" check.
+ *
+ * Bounded at MAX (default 2000) — when we cross MAX, drop the
+ * lower half. IMAP UIDs are monotonic per UIDVALIDITY, so old
+ * UIDs are safe to drop: the IMAP server's `\Seen` flag is the
+ * cross-restart authority, and our `email_seen` SQLite table
+ * is the cross-restart forensic trail. The in-memory set is
+ * just a fast filter to avoid round-tripping every UID to
+ * `email_seen` on every poll.
+ *
+ * Per-trigger instance — each email trigger has its own SeenUids.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_SEEN_UIDS = void 0;
+exports.createSeenUids = createSeenUids;
+exports.DEFAULT_MAX_SEEN_UIDS = 2000;
+function createSeenUids(maxSize = exports.DEFAULT_MAX_SEEN_UIDS) {
+    const set = new Set();
+    const trim = () => {
+        if (set.size <= maxSize)
+            return { dropped: 0 };
+        // Drop the LOWER half — IMAP UIDs monotonic per UIDVALIDITY.
+        // Sort ascending; keep the upper half (newer UIDs).
+        const sorted = [...set].sort((a, b) => a - b);
+        const keep = sorted.slice(Math.floor(sorted.length / 2));
+        const dropped = sorted.length - keep.length;
+        set.clear();
+        for (const u of keep)
+            set.add(u);
+        return { dropped };
+    };
+    return {
+        has(uid) { return set.has(uid); },
+        add(uid) {
+            set.add(uid);
+            if (set.size > maxSize)
+                trim();
+        },
+        seed(uids) {
+            for (const u of uids)
+                set.add(u);
+            if (set.size > maxSize)
+                trim();
+        },
+        size() { return set.size; },
+        trim,
+        reset() { set.clear(); },
+    };
+}

package/dist/core/v4/daemon/triggers/fileObservationsStore.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/fileObservationsStore.ts — v4.5 Phase 2.
+ *
+ * Writer for the `file_observations` table (schema v2). Each row
+ * tracks the most-recent state we've observed for one (watcher_id,
+ * abs_path) pair: size, mtime, file_key, optional content hash,
+ * timestamps + the linked trigger_event id.
+ *
+ * Reconciliation reads these on boot to decide which paths to skip
+ * vs which to emit catch-up events for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileObservationsStore = createFileObservationsStore;
+function rowToTs(r) {
+    return {
+        id: r.id,
+        watcherId: r.watcher_id,
+        absPath: r.abs_path,
+        fileKey: r.file_key,
+        size: r.size,
+        mtimeMs: r.mtime_ms,
+        contentHash: r.content_hash,
+        lastEventType: r.last_event_type,
+        lastSeenAt: r.last_seen_at,
+        lastProcessedAt: r.last_processed_at,
+        lastEventId: r.last_event_id,
+        lastStatus: r.last_status,
+        coalescedCount: r.coalesced_count,
+    };
+}
+function createFileObservationsStore(opts) {
+    const db = opts.db;
+    return {
+        upsert(input) {
+            const now = Date.now();
+            const tx = db.transaction(() => {
+                const existing = db
+                    .prepare('SELECT id, coalesced_count FROM file_observations WHERE watcher_id = ? AND abs_path = ?')
+                    .get(input.watcherId, input.absPath);
+                if (existing) {
+                    db.prepare(`UPDATE file_observations
+                SET file_key        = ?,
+                    size            = ?,
+                    mtime_ms        = ?,
+                    content_hash    = COALESCE(?, content_hash),
+                    last_event_type = ?,
+                    last_seen_at    = ?,
+                    coalesced_count = coalesced_count + ?
+              WHERE id = ?`).run(input.fileKey, input.size, input.mtimeMs, input.contentHash, input.eventType, now, input.coalescedDelta ?? 0, existing.id);
+                    return existing.id;
+                }
+                const r = db
+                    .prepare(`INSERT INTO file_observations
+               (watcher_id, abs_path, file_key, size, mtime_ms,
+                content_hash, last_event_type, last_seen_at,
+                last_status, coalesced_count)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?)`)
+                    .run(input.watcherId, input.absPath, input.fileKey, input.size, input.mtimeMs, input.contentHash, input.eventType, now, input.coalescedDelta ?? 0);
+                return Number(r.lastInsertRowid);
+            });
+            return tx();
+        },
+        markProcessed({ observationId, eventId, status }) {
+            db.prepare(`UPDATE file_observations
+            SET last_processed_at = ?,
+                last_event_id     = COALESCE(?, last_event_id),
+                last_status       = ?
+          WHERE id = ?`).run(Date.now(), eventId, status, observationId);
+        },
+        listForWatcher(watcherId) {
+            const rows = db
+                .prepare('SELECT * FROM file_observations WHERE watcher_id = ? ORDER BY abs_path')
+                .all(watcherId);
+            return rows.map(rowToTs);
+        },
+        get(watcherId, absPath) {
+            const r = db
+                .prepare('SELECT * FROM file_observations WHERE watcher_id = ? AND abs_path = ?')
+                .get(watcherId, absPath);
+            return r ? rowToTs(r) : null;
+        },
+        deleteForWatcher(watcherId) {
+            db.prepare('DELETE FROM file_observations WHERE watcher_id = ?').run(watcherId);
+        },
+    };
+}