@tobq/boardclip 0.0.0-stage → 2.1.107

package/lib/quick-paste.js

@@ -0,0 +1,187 @@
+'use strict';
+// Robust quick-paste orchestrator (numpad slots + panel number keys).
+//
+// The failure this module fixes: BoardClip quick-paste must (1) put a saved
+// item onto the clipboard, (2) synthesize Ctrl/Cmd+V into the foreground app,
+// then (3) restore the user's previous clipboard. Steps 2 and 3 race — Ctrl+V
+// is asynchronous (it only injects a keystroke; the target app reads the
+// clipboard whenever it next drains its input queue), so a fixed delay before
+// restoring the previous clipboard is unreliable. Under load the target reads
+// AFTER we've already restored → it pastes the previous clip. That is the
+// "pastes random old stuff, worse under lag" bug.
+//
+// The orchestrator makes the sequence robust regardless of platform strategy:
+//   * SERIALIZES requests through a promise chain (rapid presses queue instead
+//     of being dropped — no more "press it 3 times").
+//   * COALESCES duplicate requests for the same slot inside a short window
+//     (belt-and-suspenders against key auto-repeat that slips past the hook).
+//   * VERIFIES the macro actually landed on the clipboard before pasting
+//     (a synchronous write can still be observed late under contention).
+//   * MEASURES real scheduler lag and ADAPTS the pre-restore delay to it, with
+//     a generous floor/ceiling, so a laggy machine waits longer before restore.
+//   * RESTORES SAFELY: only overwrites the clipboard if it still holds our
+//     macro, so we never clobber something the user copied mid-sequence.
+//
+// Everything here is dependency-injected and pure so it runs under a plain-node
+// test with a fake clipboard + a fake "late-reading target" (see
+// test/numpad-paste.test.js). main.js wires the real Electron clipboard and the
+// platform paste primitive. There is a SINGLE delivery mechanism — put the item
+// on the clipboard, synthesize Ctrl/Cmd+V, safe-restore the previous clipboard —
+// which is the SAME primitive the panel-click paste uses. Numpad therefore can
+// never diverge into typing keystrokes (an earlier keystroke-injection mode
+// turned newlines into Enter presses and fired unintended sends; it was removed).
+
+const DEFAULT_CONFIG = {
+  restore: true,            // restore the user's previous clipboard afterwards
+  verifyTries: 12,          // how many times to re-check the macro landed
+  verifyIntervalMs: 8,      // spacing between verify checks (~100ms budget)
+  minRestoreDelayMs: 400,   // floor before restoring (target needs time to read)
+  maxRestoreDelayMs: 1200,  // ceiling so restore never hangs forever
+  lagMultiplier: 3,         // restore delay grows this * measured scheduler lag
+  coalesceMs: 90,           // drop same-key repeats that arrive within this window
+};
+
+function createQuickPaster(deps) {
+  const {
+    snapshot,               // () => opaque backup of current clipboard
+    restore,                // (backup) => void — write backup back
+    writeItem,              // (item) => void — put the macro on the clipboard
+    clipboardMatchesItem,   // (item) => bool — does the clipboard hold the macro?
+    paste,                  // async () => pasteResult — synthesize Ctrl/Cmd+V
+    sleep,                  // (ms) => Promise
+    now = () => Date.now(),
+    log = () => {},
+    getConfig = () => ({}),
+  } = deps;
+
+  let chain = Promise.resolve();
+  let running = false;
+  const lastStartByKey = new Map();
+
+  function config() {
+    return { ...DEFAULT_CONFIG, ...(getConfig() || {}) };
+  }
+
+  // Wait until the clipboard actually reflects the macro. A synchronous
+  // clipboard write can still be observed late while the system is busy, and
+  // pasting before it lands is exactly how stale content sneaks through.
+  async function verifySet(item, cfg, trace) {
+    for (let attempt = 1; attempt <= cfg.verifyTries; attempt++) {
+      let matched = false;
+      try { matched = !!clipboardMatchesItem(item); } catch { matched = false; }
+      if (matched) {
+        if (attempt > 1) log('quick_paste.set_verified_late', { ...trace, attempts: attempt });
+        return { ok: true, attempts: attempt };
+      }
+      if (attempt < cfg.verifyTries) await sleep(cfg.verifyIntervalMs);
+    }
+    log('quick_paste.set_unverified', { ...trace, attempts: cfg.verifyTries });
+    return { ok: false, attempts: cfg.verifyTries };
+  }
+
+  // Measure how much longer than requested a short sleep actually took — a
+  // direct read of current scheduler/system lag, which we fold into the
+  // pre-restore delay so a laggy machine gives the target more time.
+  async function measureLag(sampleMs) {
+    const t0 = now();
+    await sleep(sampleMs);
+    return Math.max(0, (now() - t0) - sampleMs);
+  }
+
+  async function timedDeliver({ item, paste: doPaste, cfg, trace }) {
+    writeItem(item);
+    const verify = await verifySet(item, cfg, trace);
+    // Scheduler-lag proxy: how much our own short sleeps overrun is a real
+    // signal of local system load (a bogged machine both delays us AND makes
+    // the target slower to read). Sample either side of the paste and take the
+    // worse. It's a mild safety bump — the configured floor is the main lever;
+    // we cannot measure the target process's read latency from here.
+    const lagBefore = await measureLag(20);
+    const pasteResult = await doPaste();
+    const lagAfter = await measureLag(20);
+    const lag = Math.max(lagBefore, lagAfter);
+    const restoreDelay = Math.min(
+      cfg.maxRestoreDelayMs,
+      Math.max(cfg.minRestoreDelayMs, cfg.minRestoreDelayMs + lag * cfg.lagMultiplier),
+    );
+    log('quick_paste.timed_wait', { ...trace, lag_ms: Math.round(lag), restore_delay_ms: Math.round(restoreDelay) });
+    await sleep(restoreDelay);
+    return { verified: verify.ok, verifyAttempts: verify.attempts, pasteResult, restoreDelay };
+  }
+
+  async function runOne(item, opts) {
+    const cfg = config();
+    const trace = opts.trace || {};
+    const startedAt = now();
+    running = true;
+
+    let backup = null;
+    let outcome = { ok: false };
+    try {
+      // A request may supply its own paste primitive (e.g. macOS needs the
+      // target app name captured at request time); otherwise use the dep.
+      const doPaste = typeof opts.paste === 'function' ? opts.paste : paste;
+
+      backup = snapshot();
+      const delivered = await timedDeliver({ item, paste: doPaste, cfg, trace });
+      outcome = { ok: true, ...delivered };
+
+      if (cfg.restore) {
+        // Only restore if the clipboard still holds our macro. If it changed,
+        // the user (or another app) put something new there — never clobber it.
+        let stillMacro = true;
+        try { stillMacro = !!clipboardMatchesItem(item); } catch { stillMacro = true; }
+        if (stillMacro) {
+          try { restore(backup); outcome.restored = true; }
+          catch (e) { outcome.restored = false; outcome.restoreError = e && e.message; }
+        } else {
+          outcome.restored = false;
+          outcome.restoreSkipped = 'clipboard_changed';
+          log('quick_paste.restore_skipped', { ...trace, reason: 'clipboard_changed' });
+        }
+      }
+    } catch (e) {
+      outcome = { ok: false, error: e && e.message };
+      log('quick_paste.error', { ...trace, error: e && e.message });
+    } finally {
+      running = false;
+      log('quick_paste.done', { ...trace, total_ms: now() - startedAt, ...summarize(outcome) });
+    }
+    return outcome;
+  }
+
+  function summarize(o) {
+    return {
+      verified: o.verified,
+      restored: o.restored,
+      restore_skipped: o.restoreSkipped,
+    };
+  }
+
+  // Enqueue a quick-paste. Returns a promise for the outcome. Rapid presses
+  // serialize; same-key repeats inside coalesceMs are dropped as duplicates.
+  function request(item, opts = {}) {
+    const cfg = config();
+    const key = opts.coalesceKey != null ? String(opts.coalesceKey) : null;
+    if (key != null) {
+      const prev = lastStartByKey.get(key);
+      if (prev != null && now() - prev < cfg.coalesceMs) {
+        log('quick_paste.coalesced', { ...(opts.trace || {}), key });
+        return Promise.resolve({ ok: false, coalesced: true });
+      }
+      lastStartByKey.set(key, now());
+    }
+    const next = chain.then(() => runOne(item, opts));
+    // Keep the chain alive even if one op throws.
+    chain = next.catch(() => {});
+    return next;
+  }
+
+  return {
+    request,
+    busy: () => running,
+    _config: config,
+  };
+}
+
+module.exports = { createQuickPaster, DEFAULT_CONFIG };

package/lib/retention.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Shared retention policy for on-disk buffers (history backups, the external-edit
+// archive, ...). Pure and side-effect-free so the policy is unit-testable without
+// the filesystem: callers enumerate the dir into { mtimeMs, size } entries, this
+// decides WHICH to evict, the caller unlinks them.
+//
+// Any combination of caps may be supplied; each is skipped when its option is
+// absent, and they compose in this order (a file removed by an earlier cap is not
+// reconsidered):
+//   - maxAgeMs:  drop entries older than the cutoff (needs `now`)
+//   - maxFiles:  keep only the newest N survivors
+//   - maxBytes:  evict oldest survivors until the total is within the cap
+// Eviction is always oldest-first (LRU by mtime).
+
+function planRetention(entries, { maxFiles, maxBytes, maxAgeMs, now } = {}) {
+  const sorted = [...entries].sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+  const remove = new Set();
+  const survivors = () => sorted.filter((e) => !remove.has(e));
+
+  if (maxAgeMs != null && now != null) {
+    for (const e of sorted) if (now - e.mtimeMs > maxAgeMs) remove.add(e);
+  }
+
+  if (maxFiles != null) {
+    const live = survivors();
+    for (let i = 0; i < live.length - maxFiles; i++) remove.add(live[i]); // oldest excess
+  }
+
+  if (maxBytes != null) {
+    let total = survivors().reduce((sum, e) => sum + (e.size || 0), 0);
+    for (const e of sorted) {
+      if (remove.has(e)) continue;
+      if (total <= maxBytes) break;
+      remove.add(e);
+      total -= e.size || 0;
+    }
+  }
+
+  return sorted.filter((e) => remove.has(e));
+}
+
+module.exports = { planRetention };

package/lib/sync-delta.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// Delta sync: ONE changes feed shared by P2P (v2 /delta endpoints) and the
+// cloud journals (sync/<device>/<revision>.json files in each provider folder).
+//
+// Model (CouchDB `_changes?since=seq` on top of the existing union merge):
+//  - `createChangeTracker` keeps, per entry (item / tombstone / group tombstone
+//    / supersede / conflict record / the small synced settings), the LOCAL
+//    revision at which that entry last changed on THIS device, whatever its
+//    source (own capture, P2P, cloud). Revisions are a per-device monotonic
+//    counter, so cursors are "the sender's revision" and never compare clocks
+//    across devices.
+//  - `deltaSince(since)` selects every entry whose arrival revision is newer
+//    than the cursor. Applying a delta is the existing `foldRemoteState` union
+//    merge, which only ever ADDS or UPDATES (deletion needs a tombstone), so a
+//    partial history is safe by construction and re-sending is idempotent.
+//  - Restart safety: the tracker is persisted lazily (sync-state.json). On load
+//    the start revision jumps to max(persisted + 1, Date.now()), and any entry
+//    whose arrival was lost (crash inside the lazy-write window) is stamped with
+//    the new start revision, so it is re-sent to every peer once. Over-sending
+//    is harmless; under-sending would be a silent hole, so the bias is deliberate.
+
+const crypto = require('crypto');
+const clipboardModel = require('./clipboard-model');
+
+const PROTOCOL = 2;
+const K_ITEM = 'i:';
+const K_TOMB = 't:';
+const K_GTOMB = 'g:';
+const K_SUP = 's:';
+const K_CONF = 'c:';
+const K_SETTINGS = 'S';
+
+function hashJson(value) {
+  return crypto.createHash('sha1').update(JSON.stringify(value === undefined ? null : value)).digest('hex').slice(0, 20);
+}
+
+// The mutation clock is THE "newer" signal the merge itself uses (capture/edit,
+// pin/groups/numpad, title, ts correction), so it is the right change signal
+// here too; the blob refs cover a formatting payload arriving for an existing
+// clip without any clock change.
+function itemFingerprint(item) {
+  return [
+    clipboardModel.itemMutationClock(item),
+    item.textRef || '', item.htmlRef || '', item.rtfRef || '', item.image || '',
+    item.textHash || '', item.htmlHash || '', item.rtfHash || '',
+  ].join('|');
+}
+
+// Synced settings minus the three big time-stamped lists (which are tracked
+// entry by entry) and minus anything that is not user data.
+function settingsSmall(syncedSettings) {
+  const small = { ...(syncedSettings || {}) };
+  delete small.tombstones;
+  delete small.group_tombstones;
+  delete small.supersedes;
+  return small;
+}
+
+function conflictFingerprint(record) {
+  return `${record.updatedAt || 0}|${record.resolved ? 1 : 0}|${hashJson(record.result || null)}`;
+}
+
+function startRevisionAfterLoad(persistedRevision, now = Date.now()) {
+  return Math.max((Number(persistedRevision) || 0) + 1, now);
+}
+
+function createChangeTracker({ revision = 0, entries = {}, now = Date.now } = {}) {
+  const map = new Map();
+  for (const [key, entry] of Object.entries(entries || {})) {
+    if (entry && Number.isFinite(entry.a)) map.set(key, { a: entry.a, f: String(entry.f || '') });
+  }
+  let rev = Number(revision) || 0;
+  let dirty = false;
+
+  function bump() {
+    rev += 1;
+    dirty = true;
+    return rev;
+  }
+
+  // Stamp every entry the view holds that is new or changed with the current
+  // revision; forget entries the view no longer holds. Returns the changed keys.
+  function observe(view) {
+    const seen = new Set();
+    const changed = [];
+    const touch = (key, fingerprint) => {
+      seen.add(key);
+      const current = map.get(key);
+      if (current && current.f === fingerprint) return;
+      map.set(key, { a: rev, f: fingerprint });
+      changed.push(key);
+    };
+    for (const item of view.items || []) {
+      if (!item) continue;
+      touch(K_ITEM + clipboardModel.itemKey(item), itemFingerprint(item));
+    }
+    for (const t of view.tombstones || []) if (t && t.id) touch(K_TOMB + t.id, String(t.deletedAt || 0));
+    for (const g of view.groupTombstones || []) if (g && g.name) touch(K_GTOMB + g.name, String(g.deletedAt || 0));
+    for (const s of view.supersedes || []) if (s && s.from && s.to) touch(K_SUP + s.from + '>' + s.to, String(s.updatedAt || 0));
+    const records = view.conflicts && Array.isArray(view.conflicts.records) ? view.conflicts.records : [];
+    for (const c of records) if (c && c.id) touch(K_CONF + c.id, conflictFingerprint(c));
+    touch(K_SETTINGS, hashJson(settingsSmall(view.settings)));
+    for (const key of [...map.keys()]) if (!seen.has(key)) { map.delete(key); dirty = true; }
+    if (changed.length) dirty = true;
+    return changed;
+  }
+
+  // Everything that arrived after `since`, as a self-describing envelope.
+  function deltaSince(since, view, meta = {}) {
+    const cursor = Number(since) || 0;
+    const newer = key => {
+      const entry = map.get(key);
+      return !entry || entry.a > cursor;
+    };
+    const items = [];
+    for (const item of view.items || []) {
+      if (item && newer(K_ITEM + clipboardModel.itemKey(item))) items.push(item);
+    }
+    const tombstones = (view.tombstones || []).filter(t => t && t.id && newer(K_TOMB + t.id));
+    const groupTombstones = (view.groupTombstones || []).filter(g => g && g.name && newer(K_GTOMB + g.name));
+    const supersedes = (view.supersedes || []).filter(s => s && s.from && s.to && newer(K_SUP + s.from + '>' + s.to));
+    const records = view.conflicts && Array.isArray(view.conflicts.records) ? view.conflicts.records : [];
+    const conflicts = records.filter(c => c && c.id && newer(K_CONF + c.id));
+    const includeSettings = newer(K_SETTINGS);
+    const envelope = {
+      v: PROTOCOL,
+      deviceId: meta.deviceId || '',
+      deviceName: meta.deviceName || '',
+      build: meta.build || '',
+      port: meta.port || 0,
+      since: cursor,
+      revision: rev,
+      originClock: now(),
+      full: cursor <= 0 || items.length === (view.items || []).length,
+      history: items,
+      tombstones,
+      group_tombstones: groupTombstones,
+      supersedes,
+    };
+    if (conflicts.length) envelope.conflicts = { records: conflicts };
+    if (includeSettings) envelope.settings = settingsSmall(view.settings);
+    if (typeof meta.assetsOf === 'function') envelope.assets = meta.assetsOf(items);
+    return envelope;
+  }
+
+  function isEmpty(envelope) {
+    return !envelope.history.length && !envelope.tombstones.length && !envelope.group_tombstones.length
+      && !envelope.supersedes.length && !envelope.conflicts && !envelope.settings;
+  }
+
+  function serialize() {
+    return { revision: rev, entries: Object.fromEntries(map) };
+  }
+
+  return {
+    get revision() { return rev; },
+    get size() { return map.size; },
+    get dirty() { return dirty; },
+    markClean() { dirty = false; },
+    bump,
+    observe,
+    deltaSince,
+    isEmpty,
+    serialize,
+  };
+}
+
+function isEnvelope(value) {
+  return !!(value && typeof value === 'object' && value.v === PROTOCOL && value.deviceId && Array.isArray(value.history));
+}
+
+// The (remoteHistory, remoteSettings, remoteConflicts) triple foldRemoteState
+// already consumes, built from an envelope. Items are still in STORED form
+// (blob refs); the caller hydrates after fetching missing assets.
+function envelopeToRemoteState(envelope) {
+  return {
+    remoteHistory: Array.isArray(envelope.history) ? envelope.history : [],
+    remoteSettings: {
+      ...(envelope.settings || {}),
+      tombstones: Array.isArray(envelope.tombstones) ? envelope.tombstones : [],
+      group_tombstones: Array.isArray(envelope.group_tombstones) ? envelope.group_tombstones : [],
+      supersedes: Array.isArray(envelope.supersedes) ? envelope.supersedes : [],
+    },
+    remoteConflicts: envelope.conflicts && typeof envelope.conflicts === 'object' ? envelope.conflicts : {},
+  };
+}
+
+// Ids an envelope can have touched in the merged history: its items, its
+// tombstones, and both ends of its edit lineages. Used for O(delta) change
+// detection instead of stringifying the whole 8 MB history twice per apply.
+function touchedIds(envelope) {
+  const ids = new Set();
+  for (const item of envelope.history || []) if (item) ids.add(clipboardModel.itemKey(item));
+  for (const t of envelope.tombstones || []) if (t && t.id) ids.add(t.id);
+  for (const s of envelope.supersedes || []) { if (s && s.from) ids.add(s.from); if (s && s.to) ids.add(s.to); }
+  return ids;
+}
+
+function historyChangedBy(before, after, ids) {
+  if (before.length !== after.length) return true;
+  const beforeById = new Map();
+  for (const item of before) if (item) beforeById.set(clipboardModel.itemKey(item), item);
+  const afterById = new Map();
+  for (const item of after) if (item) afterById.set(clipboardModel.itemKey(item), item);
+  if (beforeById.size !== afterById.size) return true;
+  for (const id of ids) {
+    const a = beforeById.get(id);
+    const b = afterById.get(id);
+    if (!a && !b) continue;
+    if (!a || !b) return true;
+    if (a !== b && JSON.stringify(a) !== JSON.stringify(b)) return true;
+  }
+  return false;
+}
+
+module.exports = {
+  PROTOCOL,
+  createChangeTracker,
+  startRevisionAfterLoad,
+  settingsSmall,
+  itemFingerprint,
+  isEnvelope,
+  envelopeToRemoteState,
+  touchedIds,
+  historyChangedBy,
+};

package/lib/sync-journal.js

@@ -0,0 +1,181 @@
+'use strict';
+
+// Cloud-folder change journals. Instead of rewriting the whole
+// clipboard-history.json on every copy (8 MB per copy per provider), each
+// device appends ONE small NEW file per change under
+//   <provider>/sync/<deviceId>/<revision16>.json
+// holding the delta envelope (lib/sync-delta.js) since its previous journal
+// write to that folder. Readers list the other devices' directories and apply
+// every file newer than their per-device cursor. The monolith stays as a
+// periodic SNAPSHOT (cold start, pre-v2 readers) and the writer prunes its own
+// journal files once a snapshot covers them.
+//
+// Files are only ever CREATED (tmp + rename to a fresh name), never rewritten:
+// Google Drive File Stream forks an object when a rename lands on an existing
+// name (lib/fork-names.js), so nothing here renames over an existing file.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const blobStore = require('./blob-store');
+
+const JOURNAL_DIR = 'sync';
+const FOLDER_ID_FILE = '.boardclip-folder-id';
+const NAME_RE = /^(\d{16})\.json$/;
+const DEVICE_RE = /^[a-z0-9_-]{1,64}$/i;
+
+function safeDeviceId(deviceId) {
+  const value = String(deviceId || '').replace(/[^a-z0-9_-]/ig, '').slice(0, 64);
+  return DEVICE_RE.test(value) ? value : '';
+}
+
+function journalName(revision) {
+  return String(Math.max(0, Math.floor(Number(revision) || 0))).padStart(16, '0') + '.json';
+}
+
+function parseJournalName(name) {
+  const match = NAME_RE.exec(String(name || ''));
+  return match ? Number(match[1]) : null;
+}
+
+function journalRoot(syncPath) {
+  return path.join(syncPath, JOURNAL_DIR);
+}
+
+function deviceDir(syncPath, deviceId) {
+  return path.join(journalRoot(syncPath), safeDeviceId(deviceId));
+}
+
+// [{ deviceId, revision, path }] for every journal file in the folder, sorted by
+// device then revision. `excludeDeviceId` skips the caller's own files.
+async function listJournal(syncPath, { excludeDeviceId = '' } = {}) {
+  let devices = [];
+  try { devices = await fs.promises.readdir(journalRoot(syncPath), { withFileTypes: true }); } catch { return []; }
+  const out = [];
+  const skip = safeDeviceId(excludeDeviceId);
+  for (const entry of devices) {
+    if (!entry.isDirectory()) continue;
+    const deviceId = safeDeviceId(entry.name);
+    if (!deviceId || deviceId === skip) continue;
+    let names = [];
+    try { names = await fs.promises.readdir(path.join(journalRoot(syncPath), entry.name)); } catch { continue; }
+    for (const name of names) {
+      const revision = parseJournalName(name);
+      if (revision == null) continue;
+      out.push({ deviceId, revision, path: path.join(journalRoot(syncPath), entry.name, name) });
+    }
+  }
+  out.sort((a, b) => a.deviceId.localeCompare(b.deviceId) || a.revision - b.revision);
+  return out;
+}
+
+async function writeJournalEntry(syncPath, deviceId, envelope) {
+  const dir = deviceDir(syncPath, deviceId);
+  if (!safeDeviceId(deviceId)) throw new Error('journal: invalid device id');
+  await fs.promises.mkdir(dir, { recursive: true });
+  const finalPath = path.join(dir, journalName(envelope.revision));
+  const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.tmp`;
+  const json = JSON.stringify(envelope);
+  await fs.promises.writeFile(tmpPath, json);
+  await fs.promises.rename(tmpPath, finalPath);
+  return { path: finalPath, bytes: Buffer.byteLength(json) };
+}
+
+async function readJournalEntry(filePath) {
+  try {
+    const parsed = blobStore.parseJsonText(await fs.promises.readFile(filePath, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Delete this device's own journal files that a snapshot already covers
+// (revision <= upToRevision) and that are old enough for every reader to have
+// consumed them. Returns how many were removed.
+async function pruneJournal(syncPath, deviceId, { upToRevision = 0, olderThanMs = 60 * 60 * 1000, now = Date.now() } = {}) {
+  const dir = deviceDir(syncPath, deviceId);
+  let names = [];
+  try { names = await fs.promises.readdir(dir); } catch { return 0; }
+  let removed = 0;
+  for (const name of names) {
+    const revision = parseJournalName(name);
+    const isTmp = /\.tmp$/.test(name);
+    if (revision == null && !isTmp) continue;
+    const file = path.join(dir, name);
+    try {
+      const stats = await fs.promises.stat(file);
+      if (now - stats.mtimeMs < olderThanMs) continue;
+      if (!isTmp && revision > upToRevision) continue;
+      await fs.promises.unlink(file);
+      removed++;
+    } catch {}
+  }
+  return removed;
+}
+
+async function countJournal(syncPath, deviceId) {
+  try {
+    const names = await fs.promises.readdir(deviceDir(syncPath, deviceId));
+    return names.filter(name => parseJournalName(name) != null).length;
+  } catch {
+    return 0;
+  }
+}
+
+// A stable id stored INSIDE the folder, so two mount paths of the same cloud
+// folder (Google Drive on G: and H:) are recognised as one provider.
+async function folderIdentity(syncPath) {
+  const marker = path.join(syncPath, FOLDER_ID_FILE);
+  try {
+    const raw = (await fs.promises.readFile(marker, 'utf-8')).trim();
+    if (/^[a-f0-9]{32}$/i.test(raw)) return raw.toLowerCase();
+  } catch {}
+  const id = crypto.randomBytes(16).toString('hex');
+  try {
+    await fs.promises.mkdir(syncPath, { recursive: true });
+    await fs.promises.writeFile(marker, id, { flag: 'wx' });
+    return id;
+  } catch {
+    // Lost a race with another writer (or a read-only folder): re-read, else
+    // fall back to the path itself so the folder is still treated as unique.
+    try {
+      const raw = (await fs.promises.readFile(marker, 'utf-8')).trim();
+      if (/^[a-f0-9]{32}$/i.test(raw)) return raw.toLowerCase();
+    } catch {}
+    return `path:${syncPath}`;
+  }
+}
+
+// entries: [{ path, id }] -> { primary: [path], duplicateOf: { path: primaryPath } }
+function dedupeByIdentity(entries) {
+  const byId = new Map();
+  const primary = [];
+  const duplicateOf = {};
+  for (const entry of entries) {
+    if (!entry || !entry.path) continue;
+    const id = entry.id || `path:${entry.path}`;
+    const first = byId.get(id);
+    if (first) { duplicateOf[entry.path] = first; continue; }
+    byId.set(id, entry.path);
+    primary.push(entry.path);
+  }
+  return { primary, duplicateOf };
+}
+
+module.exports = {
+  JOURNAL_DIR,
+  FOLDER_ID_FILE,
+  safeDeviceId,
+  journalName,
+  parseJournalName,
+  journalRoot,
+  deviceDir,
+  listJournal,
+  writeJournalEntry,
+  readJournalEntry,
+  pruneJournal,
+  countJournal,
+  folderIdentity,
+  dedupeByIdentity,
+};