dsh-reference-anything 0.2.0

package/lib/store/store.js

@@ -0,0 +1,638 @@
+import { createHash } from 'node:crypto';
+import { ReferenceAnythingError } from "../errors.js";
+import { compareMatches, scoreTitle, snippet } from "../search.js";
+export const TURNS_PER_CHUNK = 50;
+/**
+ * Shortest query that may trigger a body scan. One character matches almost
+ * every conversation, which is neither useful nor worth the scan.
+ */
+export const CONTENT_MIN_QUERY = 2;
+/** Conversations a single body scan may examine, newest first. */
+export const CONTENT_SCAN_LIMIT = 300;
+/** Characters of one conversation a body scan reads before giving up on it. */
+export const CONTENT_SCAN_CHARS = 200_000;
+/** Stable final tie-breaker for equally relevant, equally recent conversations. */
+const PROVIDER_ORDER = {
+    chatgpt: 0, claude: 1, gemini: 2, deepseek: 3, grok: 4, kimi: 5,
+};
+export class ConversationStore {
+    domain;
+    conversations;
+    revisions;
+    chunks;
+    attachments;
+    syncStates;
+    observedAccountScopes = new Map();
+    constructor(domain) {
+        this.domain = domain;
+        this.conversations = domain.table('conversations');
+        this.revisions = domain.table('revisions');
+        this.chunks = domain.table('turn_chunks');
+        this.attachments = domain.table('attachments');
+        this.syncStates = domain.table('sync_states');
+    }
+    setActiveAccountScope(provider, accountScope) {
+        this.observedAccountScopes.set(provider, accountScope);
+    }
+    get settings() { return this.domain.global.get(); }
+    setSettings(settings) { return this.domain.global.set(settings); }
+    /** Remove every persisted transcript while retaining the title directory. */
+    async clearMirrorContent() {
+        for (const [key] of this.attachments.entries())
+            await retryWindowsReplace(() => this.attachments.delete(key));
+        for (const [key] of this.chunks.entries())
+            await retryWindowsReplace(() => this.chunks.delete(key));
+        for (const [key] of this.revisions.entries())
+            await retryWindowsReplace(() => this.revisions.delete(key));
+        for (const [key, row] of this.conversations.entries()) {
+            if (row.currentRevision === undefined)
+                continue;
+            const { currentRevision: _revision, ...metadata } = row;
+            await retryWindowsReplace(() => this.conversations.put(key, metadata));
+        }
+    }
+    static conversationKey(provider, accountScope, externalId) {
+        return Buffer.from(JSON.stringify([provider, accountScope, externalId])).toString('base64url');
+    }
+    static parseConversationKey(key) {
+        try {
+            const value = JSON.parse(Buffer.from(key, 'base64url').toString('utf8'));
+            if (!Array.isArray(value) || value.length !== 3 || !value.every(item => typeof item === 'string'))
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new ReferenceAnythingError('web conversation reference id is malformed', 'REFERENCE_INVALID_URI');
+        }
+    }
+    /**
+     * Rank conversations for a discovery surface, best match first.
+     *
+     * Three passes, each only reached when the one before it left room. Titles
+     * are matched loosely (see {@link scoreTitle}) because the `@` mention
+     * query can never contain a space; bodies are searched only when titles
+     * came up short, which is what makes the auto-generated "New chat" titles
+     * findable at all without paying for a scan on every keystroke.
+     * @param query - user query, provider prefix already stripped.
+     * @param provider - restrict to one provider.
+     * @param limit - maximum results.
+     * @returns matches, best first, capped at `limit`.
+     */
+    list(query, provider, limit) {
+        const needle = query.trim();
+        const activeScopes = this.activeAccountScopes();
+        const candidates = [...this.conversations.entries()]
+            .filter(([, row]) => !row.remoteMissing && (!provider || row.provider === provider)
+            && (!activeScopes.has(row.provider) || activeScopes.get(row.provider) === row.accountScope))
+            .sort(compareConversationRows);
+        if (needle === '') {
+            return candidates.slice(0, limit).map(([key, row]) => ({ key, row, via: 'recent' }));
+        }
+        const titled = [];
+        const unmatched = [];
+        for (const [key, row] of candidates) {
+            const match = scoreTitle(row.title, needle);
+            if (match)
+                titled.push({ key, row, match });
+            else
+                unmatched.push([key, row]);
+        }
+        titled.sort((a, b) => compareMatches(a.match, b.match)
+            || compareConversationRows([a.key, a.row], [b.key, b.row]));
+        const results = titled.slice(0, limit)
+            .map(({ key, row }) => ({ key, row, via: 'title' }));
+        if (results.length >= limit || needle.length < CONTENT_MIN_QUERY)
+            return results;
+        const pattern = new RegExp(needle.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'), 'iu');
+        for (const [key, row] of unmatched.slice(0, CONTENT_SCAN_LIMIT)) {
+            const hit = this.findInBody(key, row, pattern);
+            if (!hit)
+                continue;
+            results.push({ key, row, via: 'content', snippet: hit });
+            if (results.length >= limit)
+                break;
+        }
+        return results;
+    }
+    stats(providers) {
+        return providers.map((provider) => {
+            const conversations = [...this.conversations.entries()].filter(([, row]) => row.provider === provider && !row.remoteMissing);
+            const states = [...this.syncStates.entries()].map(([, row]) => row).filter(row => row.provider === provider);
+            const latest = newestByTimestamp(states, row => row.lastSyncAt);
+            const latestSuccessful = newestByTimestamp(states.filter(row => row.status === 'idle'), row => row.lastSyncAt);
+            // Old/imported records can have a blank or malformed `syncedAt` while
+            // still carrying a usable provider `updatedAt`. Consider both fields
+            // independently: `syncedAt || updatedAt` lets a truthy malformed value
+            // mask the valid fallback and leaves the provider card without a date.
+            const latestLocalUpdate = newestTimestamp(conversations.flatMap(([, row]) => [row.syncedAt, row.updatedAt]));
+            return {
+                provider, conversations: conversations.length, lastSyncedAt: latestSuccessful?.lastSyncAt || latestLocalUpdate,
+                status: latest?.status === 'running' ? 'syncing' : latest?.status === 'failed' ? 'error' : conversations.length ? 'ready' : 'empty',
+                ...(latest?.error ? { error: latest.error } : {}),
+            };
+        });
+    }
+    /**
+     * Search one conversation's stored turns for `pattern`.
+     *
+     * Reads chunks by key off the current revision rather than iterating the
+     * chunk table, whose `entries()` copies every record in the domain. Matching
+     * runs against the turn text in place — no lowercased copy is built, so the
+     * excerpt keeps its original casing and nothing is cached beside the
+     * records the domain already holds in memory.
+     * @returns the excerpt around the first hit, or undefined when there is none.
+     */
+    findInBody(conversationKey, row, pattern) {
+        if (!row.currentRevision)
+            return undefined;
+        const revision = this.revisions.get(`${conversationKey}:${row.currentRevision}`);
+        if (!revision)
+            return undefined;
+        let budget = CONTENT_SCAN_CHARS;
+        for (const chunkKey of revision.chunkKeys) {
+            for (const turn of this.chunks.get(chunkKey)?.turns ?? []) {
+                const at = turn.text.search(pattern);
+                if (at >= 0)
+                    return snippet(turn.text, at);
+                budget -= turn.text.length;
+                if (budget <= 0)
+                    return undefined;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Page through every stored conversation, including ones the provider no
+     * longer lists — a management view needs to surface `remoteMissing` rows
+     * so they can be cleaned up, unlike {@link list}'s mention/search surface.
+     */
+    page(query, provider, limit, offset) {
+        const needle = query.trim().toLocaleLowerCase();
+        const filtered = [...this.conversations.entries()]
+            .filter(([, row]) => !provider || row.provider === provider)
+            .filter(([, row]) => needle === '' || row.title.toLocaleLowerCase().includes(needle))
+            .sort((a, b) => recency(b[1]) - recency(a[1]));
+        return { items: filtered.slice(offset, offset + limit), total: filtered.length };
+    }
+    /**
+     * Permanently purge one conversation and everything derived from it.
+     *
+     * A sync job racing this call can resurrect a broken row (see
+     * {@link WebChatHistoryService.remove}, which guards against that at the
+     * service layer) — this method itself makes no atomicity promise beyond
+     * "delete whatever currently references this key."
+     * @returns whether a conversation with this key existed.
+     */
+    async remove(conversationKey) {
+        if (!this.conversations.get(conversationKey))
+            return false;
+        for (const [key, revision] of this.revisions.entries()) {
+            if (revision.conversationKey !== conversationKey)
+                continue;
+            for (const chunkKey of revision.chunkKeys)
+                await this.chunks.delete(chunkKey);
+            await this.revisions.delete(key);
+        }
+        for (const [key, row] of this.attachments.entries()) {
+            if (row.conversationKey === conversationKey)
+                await this.attachments.delete(key);
+        }
+        await this.conversations.delete(conversationKey);
+        return true;
+    }
+    /** Approximate payload bytes held by this domain; filesystem overhead is excluded. */
+    storageStats() {
+        const tables = [this.conversations, this.revisions, this.chunks, this.attachments, this.syncStates];
+        let bytes = 0;
+        for (const table of tables)
+            for (const [key, value] of table.entries()) {
+                bytes += Buffer.byteLength(JSON.stringify([key, value]), 'utf8');
+            }
+        const remoteMissing = [...this.conversations.entries()].filter(([, row]) => row.remoteMissing).length;
+        const oldAccountConversations = this.oldAccountConversationKeys().length;
+        return { bytes, conversations: this.conversations.size, remoteMissing, oldAccountConversations };
+    }
+    /** Permanently remove every row a complete remote scan marked as absent. */
+    async removeRemoteMissing() {
+        const keys = [...this.conversations.entries()].filter(([, row]) => row.remoteMissing).map(([key]) => key);
+        for (const key of keys)
+            await this.remove(key);
+        return keys.length;
+    }
+    /** Permanently remove conversations and sync metadata owned by inactive accounts. */
+    async removeOldAccounts() {
+        // Resolve the active scopes once. Removing sync-state rows while deriving
+        // this map could otherwise make the definition of "old" change mid-pass.
+        const activeScopes = this.activeAccountScopes();
+        const keys = this.oldAccountConversationKeys(activeScopes);
+        for (const key of keys)
+            await this.remove(key);
+        for (const [key, row] of this.syncStates.entries()) {
+            const activeScope = activeScopes.get(row.provider);
+            if (activeScope !== undefined && row.accountScope !== activeScope)
+                await this.syncStates.delete(key);
+        }
+        return keys.length;
+    }
+    async removeProvider(provider) {
+        const keys = [...this.conversations.entries()].filter(([, row]) => row.provider === provider).map(([key]) => key);
+        for (const key of keys)
+            await this.remove(key);
+        for (const [key, row] of this.syncStates.entries())
+            if (row.provider === provider)
+                await this.syncStates.delete(key);
+        return keys.length;
+    }
+    async removeOlderThan(days, now = Date.now()) {
+        const cutoff = now - Math.max(1, Math.trunc(days)) * 24 * 60 * 60 * 1000;
+        const keys = [...this.conversations.entries()].filter(([, row]) => recency(row) < cutoff).map(([key]) => key);
+        for (const key of keys)
+            await this.remove(key);
+        return keys.length;
+    }
+    /**
+     * One row per provider, aggregated across every account scope it has ever
+     * synced under. `status`/`error`/`lastSyncAt` come from whichever attempt is
+     * most recent — success or failure — so a background failure is never
+     * hidden behind an older successful scope's row. `lastCompleteScanAt` is
+     * the max across all of that provider's rows, so it never regresses just
+     * because the latest attempt failed before finishing.
+     */
+    syncStateSummary() {
+        const freshest = new Map();
+        const lastCompleteScan = new Map();
+        for (const [, row] of this.syncStates.entries()) {
+            const current = freshest.get(row.provider);
+            if (!current || Date.parse(row.lastSyncAt || '') > Date.parse(current.lastSyncAt || '')) {
+                freshest.set(row.provider, {
+                    provider: row.provider, status: row.status, lastSyncAt: row.lastSyncAt,
+                    lastCompleteScanAt: row.lastCompleteScanAt, error: row.error,
+                });
+            }
+            // `!seen` short-circuits the first real value in — `Date.parse('') > Date.parse(x)` is always
+            // false (NaN comparisons never succeed), so comparing straight through would silently drop it.
+            if (row.lastCompleteScanAt) {
+                const seen = lastCompleteScan.get(row.provider);
+                if (!seen || Date.parse(row.lastCompleteScanAt) > Date.parse(seen))
+                    lastCompleteScan.set(row.provider, row.lastCompleteScanAt);
+            }
+        }
+        return [...freshest.values()].map(state => ({ ...state, lastCompleteScanAt: lastCompleteScan.get(state.provider) || state.lastCompleteScanAt }));
+    }
+    /**
+     * Record what the provider's listing says about one conversation.
+     *
+     * Skips the write when nothing but `syncedAt` would change: under the JSON
+     * storage backend a single record write re-serializes and fsyncs the entire
+     * domain, so an unchanged history would otherwise cost one whole-mirror
+     * rewrite per conversation on every pass.
+     * @returns the conversation key, written or not.
+     */
+    async putConversation(row, accountScope) {
+        const key = ConversationStore.conversationKey(row.provider, accountScope, row.id);
+        const current = this.conversations.get(key);
+        // Directory rows only discover conversations. Once a detail snapshot is
+        // mirrored, its metadata stays authoritative until the matching detail
+        // fetch succeeds and commitRevision atomically publishes the provider's
+        // listing timestamp.
+        const hasMirroredTurns = current?.currentRevision !== undefined;
+        const next = {
+            provider: row.provider, accountScope, externalId: row.id,
+            title: row.title.trim() || row.id, url: row.url,
+            ...(current?.currentRevision ? { currentRevision: current.currentRevision } : {}),
+            createdAt: row.createdAt || current?.createdAt || '',
+            updatedAt: hasMirroredTurns ? current.updatedAt : row.updatedAt.trim(),
+            // Once a revision exists its turn count is the honest one: the provider
+            // counts turns this mirror drops (empty ones), so letting its number
+            // back in would flip the value on every metadata refresh.
+            messageCount: current?.currentRevision ? current.messageCount : Math.max(0, Math.trunc(row.messageCount || 0)),
+            partial: row.partial, remoteMissing: false, syncedAt: new Date().toISOString(),
+        };
+        if (current && sameConversation(current, next))
+            return key;
+        await this.conversations.put(key, next);
+        return key;
+    }
+    needsDetail(key, row, full) {
+        if (full)
+            return true;
+        const current = this.conversations.get(key);
+        return !current?.currentRevision || current.updatedAt !== row.updatedAt || current.partial !== row.partial;
+    }
+    /**
+     * Store one fetched transcript as an immutable revision and make it current.
+     *
+     * @param conversationKey - the conversation being updated; it must already exist.
+     * @param rows - the provider's turns, in any order.
+     * @param next - the listing row this transcript was fetched for. Supplying
+     * it folds the metadata update into the same write that publishes the
+     * revision, which is what keeps `updatedAt` — the only change signal
+     * {@link needsDetail} has — from advancing ahead of the content it describes.
+     * @returns the revision id, `sha256:<hex>` over the normalized turns.
+     */
+    async commitRevision(conversationKey, rows, next) {
+        const conversation = this.conversations.get(conversationKey);
+        if (!conversation)
+            throw new ReferenceAnythingError('conversation disappeared before its revision commit', 'REFERENCE_NOT_FOUND');
+        const activeRows = rows.filter(row => row.activeBranch !== false)
+            .sort((a, b) => a.ordinal - b.ordinal);
+        const turns = activeRows.map((row, ordinal) => ({
+            ordinal, messageId: String(row.messageId || ordinal), parentId: String(row.parentId || ''),
+            branchId: String(row.branchId || ''), role: row.role, text: String(row.text || ''),
+            createdAt: String(row.createdAt || ''), attachments: parseAttachments(row.attachmentsJson),
+        })).filter(turn => turn.text.trim() !== '' || turn.attachments.length > 0);
+        const canonical = JSON.stringify(turns);
+        const digest = createHash('sha256').update(canonical).digest('hex');
+        const revision = `sha256:${digest}`;
+        const revisionKey = `${conversationKey}:${revision}`;
+        const now = Date.now();
+        // A provider listing timestamp is authoritative when present. DOM-backed
+        // or partially compatible listings can omit it, so retain the newest
+        // message timestamp as a fallback instead of publishing an unknown date.
+        const newestTurnAt = turns.reduce((latest, turn) => {
+            const latestAt = parseTimestamp(latest);
+            const candidateAt = parseTimestamp(turn.createdAt);
+            return candidateAt !== undefined && (latestAt === undefined || candidateAt > latestAt) ? turn.createdAt : latest;
+        }, '');
+        const merged = {
+            ...conversation,
+            ...(next ? {
+                title: next.title.trim() || next.id, url: next.url, createdAt: next.createdAt,
+                updatedAt: next.updatedAt || newestTurnAt || conversation.updatedAt, partial: next.partial, remoteMissing: false,
+            } : newestTurnAt ? { updatedAt: newestTurnAt } : {}),
+            currentRevision: revision, messageCount: turns.length, syncedAt: new Date(now).toISOString(),
+        };
+        // The revision id IS the content hash, so an unchanged transcript commits
+        // back to the key it already occupies. Rewriting its chunks and
+        // attachments would cost one whole-domain rewrite each (JSON backend) to
+        // store bytes that are already there — the common case for a full rescan,
+        // and for any conversation whose `updatedAt` moved without its content.
+        if (conversation.currentRevision === revision && this.revisions.get(revisionKey)) {
+            await this.conversations.put(conversationKey, merged);
+            return revision;
+        }
+        const chunkKeys = [];
+        for (let index = 0; index * TURNS_PER_CHUNK < turns.length; index++) {
+            const chunkKey = `${revisionKey}:${index}`;
+            chunkKeys.push(chunkKey);
+            await this.chunks.put(chunkKey, {
+                conversationKey, revision, index,
+                turns: turns.slice(index * TURNS_PER_CHUNK, (index + 1) * TURNS_PER_CHUNK),
+            });
+        }
+        await this.revisions.put(revisionKey, {
+            conversationKey, revision, contentHash: digest, turnCount: turns.length,
+            activeBranch: activeRows.find(row => row.branchId)?.branchId || '', chunkKeys,
+            partial: merged.partial || activeRows.some(row => row.partial),
+            syncedAt: new Date(now).toISOString(), expiresAt: new Date(now).toISOString(),
+        });
+        for (const turn of turns)
+            for (const attachment of turn.attachments) {
+                await this.attachments.put(`${revisionKey}:${turn.ordinal}:${attachment.attachmentId}`, {
+                    ...attachment, conversationKey, revision, ordinal: turn.ordinal,
+                });
+            }
+        await this.conversations.put(conversationKey, merged);
+        await this.removeSupersededRevisions(conversationKey, revision);
+        return revision;
+    }
+    /**
+     * Most recently observed logged-in account per provider.
+     *
+     * A non-empty account scope is written as soon as account discovery and
+     * listing complete, even if later per-conversation work fails. Older local
+     * accounts remain manageable, but must not leak back into the @ picker.
+     */
+    activeAccountScopes() {
+        const active = new Map();
+        for (const [, row] of this.syncStates.entries()) {
+            if (!row.accountScope)
+                continue;
+            const at = Date.parse(row.lastSyncAt || '');
+            if (Number.isNaN(at))
+                continue;
+            const current = active.get(row.provider);
+            if (!current || at >= current.at)
+                active.set(row.provider, { scope: row.accountScope, at });
+        }
+        const result = new Map([...active].map(([provider, value]) => [provider, value.scope]));
+        for (const [provider, scope] of this.observedAccountScopes)
+            result.set(provider, scope);
+        return result;
+    }
+    oldAccountConversationKeys(activeScopes = this.activeAccountScopes()) {
+        return [...this.conversations.entries()].filter(([, row]) => {
+            const activeScope = activeScopes.get(row.provider);
+            // No known current account means there is no safe basis for deletion.
+            return activeScope !== undefined && row.accountScope !== activeScope;
+        }).map(([key]) => key);
+    }
+    /** Keep exactly the latest transcript revision for a conversation. */
+    async removeSupersededRevisions(conversationKey, keep) {
+        for (const [key, row] of this.revisions.entries()) {
+            if (row.conversationKey !== conversationKey || row.revision === keep)
+                continue;
+            for (const chunkKey of row.chunkKeys)
+                await this.chunks.delete(chunkKey);
+            for (const [attachmentKey, attachment] of this.attachments.entries()) {
+                if (attachment.conversationKey === conversationKey && attachment.revision === row.revision)
+                    await this.attachments.delete(attachmentKey);
+            }
+            await this.revisions.delete(key);
+        }
+    }
+    read(conversationKey, window) {
+        const conversation = this.conversations.get(conversationKey);
+        if (!conversation?.currentRevision)
+            throw new ReferenceAnythingError('conversation has not been synchronized', 'REFERENCE_NOT_FOUND');
+        let revision = conversation.currentRevision;
+        let end = window.before;
+        if (window.cursor !== undefined) {
+            const cursor = decodeCursor(window.cursor);
+            if (cursor.ref !== conversationKey)
+                throw new ReferenceAnythingError('cursor belongs to another reference', 'REFERENCE_INVALID_CURSOR');
+            revision = cursor.revision;
+            end = cursor.nextOrdinal;
+        }
+        const revisionRecord = this.revisions.get(`${conversationKey}:${revision}`);
+        if (!revisionRecord)
+            throw new ReferenceAnythingError('reference cursor revision has expired', 'REFERENCE_CURSOR_EXPIRED');
+        if (revision !== conversation.currentRevision)
+            throw new ReferenceAnythingError('reference cursor revision has expired', 'REFERENCE_CURSOR_EXPIRED');
+        const all = revisionRecord.chunkKeys.flatMap(key => this.chunks.get(key)?.turns ?? []);
+        const boundedEnd = Math.max(0, Math.min(end ?? all.length, all.length));
+        const start = Math.max(0, boundedEnd - Math.max(1, Math.trunc(window.limit)));
+        const nextCursor = start > 0 ? encodeCursor({ v: 1, ref: conversationKey, revision, nextOrdinal: start }) : undefined;
+        return {
+            ref: { source: 'web-chat', id: conversationKey }, label: conversation.title, origin: conversation.url,
+            updatedAt: parseTimestamp(conversation.updatedAt), provider: conversation.provider, revision,
+            partial: revisionRecord.partial, capturedAt: Date.parse(revisionRecord.syncedAt),
+            body: {
+                kind: 'conversation',
+                items: all.slice(start, boundedEnd).map((turn) => ({
+                    role: turn.role, text: turn.text,
+                    ...(turn.attachments.length ? { attachments: turn.attachments.map(attachment => ({
+                            attachmentId: attachment.attachmentId, kind: attachment.kind, name: attachment.name,
+                            mimeType: attachment.mimeType, size: attachment.size, status: attachment.status,
+                        })) } : {}),
+                })),
+                startIndex: start, totalTurns: all.length, hasOlder: start > 0,
+                ...(nextCursor ? { nextCursor } : {}), revision,
+            },
+        };
+    }
+    attachment(conversationKey, revision, attachmentId) {
+        return [...this.attachments.entries()].find(([, row]) => row.conversationKey === conversationKey
+            && row.revision === revision && row.attachmentId === attachmentId)?.[1];
+    }
+    async markRemoteMissing(provider, accountScope, seen) {
+        for (const [key, row] of this.conversations.entries()) {
+            if (row.provider !== provider || row.accountScope !== accountScope || seen.has(row.externalId) || row.remoteMissing)
+                continue;
+            await this.conversations.put(key, { ...row, remoteMissing: true });
+        }
+    }
+    async collectExpired(now = Date.now()) {
+        const expired = [];
+        for (const [key, revision] of this.revisions.entries()) {
+            const current = this.conversations.get(revision.conversationKey)?.currentRevision;
+            if (revision.revision === current)
+                continue;
+            expired.push([key, revision]);
+        }
+        if (expired.length === 0)
+            return;
+        // One pass over the attachments table for the whole sweep. Re-scanning it
+        // per expired revision was quadratic, and `entries()` copies every record
+        // each time it is called.
+        const byRevision = new Map();
+        for (const [key, row] of this.attachments.entries()) {
+            const group = `${row.conversationKey}\u0000${row.revision}`;
+            const bucket = byRevision.get(group);
+            if (bucket)
+                bucket.push(key);
+            else
+                byRevision.set(group, [key]);
+        }
+        for (const [key, revision] of expired) {
+            for (const chunkKey of revision.chunkKeys)
+                await this.chunks.delete(chunkKey);
+            for (const attachmentKey of byRevision.get(`${revision.conversationKey}\u0000${revision.revision}`) ?? []) {
+                await this.attachments.delete(attachmentKey);
+            }
+            await this.revisions.delete(key);
+        }
+    }
+}
+/** Antivirus/indexers may briefly hold the JSON target across its atomic rename on Windows. */
+async function retryWindowsReplace(operation) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const code = error.code;
+            if (process.platform !== 'win32' || (code !== 'EPERM' && code !== 'EBUSY') || attempt >= 7)
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, 25 * 2 ** attempt));
+        }
+    }
+}
+/** Whether two conversation records differ in anything but `syncedAt`, which always does. */
+function sameConversation(a, b) {
+    return a.provider === b.provider && a.accountScope === b.accountScope && a.externalId === b.externalId
+        && a.title === b.title && a.url === b.url && a.currentRevision === b.currentRevision
+        && a.createdAt === b.createdAt && a.updatedAt === b.updatedAt && a.messageCount === b.messageCount
+        && a.partial === b.partial && a.remoteMissing === b.remoteMissing;
+}
+/** Sort key for "most recently active", falling back to when we last saw it. */
+function recency(row) {
+    return parseTimestamp(row.updatedAt) ?? parseTimestamp(row.syncedAt) ?? 0;
+}
+/** Recency first, then the canonical provider order, then identity for determinism. */
+function compareConversationRows(a, b) {
+    return recency(b[1]) - recency(a[1])
+        || PROVIDER_ORDER[a[1].provider] - PROVIDER_ORDER[b[1].provider]
+        || a[0].localeCompare(b[0]);
+}
+function parseAttachments(raw) {
+    try {
+        const value = JSON.parse(raw || '[]');
+        if (!Array.isArray(value))
+            return [];
+        return value.map((item, index) => {
+            const row = item && typeof item === 'object' ? item : {};
+            const status = row.status === 'available' || row.status === 'expired' ? row.status : 'unavailable';
+            const locator = typeof row.locator === 'string' && row.locator ? row.locator : undefined;
+            const name = String(row.name ?? 'attachment');
+            const mimeType = String(row.mimeType ?? '');
+            return {
+                attachmentId: String(row.attachmentId ?? row.id ?? index),
+                kind: attachmentKind(row.kind ?? row.type, mimeType, name), name,
+                mimeType, size: Number(row.size ?? 0), status,
+                ...(locator ? { locator } : {}),
+            };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function attachmentKind(value, mimeType, name) {
+    if (value === 'image' || value === 'file')
+        return value;
+    if (mimeType.toLowerCase().startsWith('image/'))
+        return 'image';
+    return /\.(?:avif|bmp|gif|heic|heif|jpe?g|png|svg|tiff?|webp)$/i.test(name) ? 'image' : 'file';
+}
+function encodeCursor(value) {
+    return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+function decodeCursor(value) {
+    try {
+        const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        const row = parsed;
+        if (row.v !== 1 || typeof row.ref !== 'string' || typeof row.revision !== 'string'
+            || !Number.isInteger(row.nextOrdinal) || Number(row.nextOrdinal) < 0)
+            throw new Error();
+        return row;
+    }
+    catch {
+        throw new ReferenceAnythingError('reference cursor is malformed', 'REFERENCE_INVALID_CURSOR');
+    }
+}
+function parseTimestamp(value) {
+    if (!value)
+        return undefined;
+    const number = Number(value);
+    if (Number.isFinite(number))
+        return number < 10_000_000_000 ? number * 1000 : number;
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : date;
+}
+/** Return the original representation of the newest valid timestamp. */
+function newestTimestamp(values) {
+    let newest = '';
+    let newestAt;
+    for (const value of values) {
+        const at = parseTimestamp(value);
+        if (at !== undefined && (newestAt === undefined || at > newestAt)) {
+            newest = value;
+            newestAt = at;
+        }
+    }
+    return newest;
+}
+/** Select the newest row while ignoring blank or malformed timestamps. */
+function newestByTimestamp(rows, timestamp) {
+    let newest;
+    let newestAt;
+    for (const row of rows) {
+        const at = parseTimestamp(timestamp(row));
+        if (at !== undefined && (newestAt === undefined || at > newestAt)) {
+            newest = row;
+            newestAt = at;
+        }
+    }
+    return newest;
+}