@glance-apps/sync 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-11
+
+### Added
+
+- **The snapshot-file sync cycle** (`runSnapshotFileCycle`), moved here from
+  dayGLANCE so every GLANCE app's iCloud and Direct Access tiers run one
+  cycle. A snapshot-file transport is a local file something else ferries
+  between devices (an iCloud container, a Nextcloud / Drive / Dropbox /
+  Syncthing folder): no server, no ETag. The cycle reads the whole file,
+  merges it with local state, applies what changed locally, and writes the
+  merged result back, with every data-safety guard the dayGLANCE loop grew
+  on devices: the seed guard (`evaluateMissingSnapshot`), the empty-state
+  guard, the first-run restore prompt (`shouldPromptFirstRun`), the content
+  gate (a write needs a real difference, not just a merge flag), the
+  made-here-or-relayed rule with relays staggered by writer rank
+  (`relayDecision`, `relayWaitMs`, `noteWriter`, `readWriters`), the write
+  throttle, and the envelope rules (the file decides, the switch decides the
+  first write; a wanted envelope with no key ready is held, never written
+  plaintext). Pure over an injected transport and `io`; the app's storage
+  keys and any strip of slices the file must not carry come in through `io`
+  (`localModifiedKey`, `lastLocalEditAt`, `localItemCount`, `hasData`,
+  `outgoing`). The read classification is `classifySnapshotText`.
+- **The slice comparison** the cycle decides writes and applies with
+  (`sliceDiffs`, `describeSliceDiff`, `writeWorthy`, `canonicalJson`,
+  `explainSnapshotMerge`), so an app's diagnostics can run the identical
+  function the cycle runs.
+
+No existing export changes. dayGLANCE's local copies become wrappers over
+these; lastGLANCE's Direct Access tier (its Phase 7b) builds on them.
+
 ## [2.0.0] - 2026-08-30
 
 > ### ⚠️ ACTION REQUIRED for lastGLANCE and lifeGLANCE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -70,6 +70,31 @@ export {
 // from a rejected credential: re-enrollment that rotates the dead credential
 // away server-side.
 export { connectVaultSyncEngine, recoverVaultSyncEngine } from './vaultConnect.js';
+// 2.1.0: the snapshot-file cycle (iCloud, Direct Access) and the slice
+// comparison it decides writes and applies with. Pure over an injected
+// transport; see src/snapshotFileSync.js.
+export {
+  runSnapshotFileCycle,
+  classifySnapshotText,
+  evaluateMissingSnapshot,
+  shouldPromptFirstRun,
+  payloadHasData,
+  relayDecision,
+  relayWaitMs,
+  noteWriter,
+  readWriters,
+  RELAY_CONFIRM_MS,
+  RELAY_STAGGER_MS,
+  MISSING_GRACE_MS,
+} from './snapshotFileSync.js';
+export {
+  canonicalJson,
+  describeSliceDiff,
+  sliceDiffs,
+  writeWorthy,
+  explainSnapshotMerge,
+  PER_MERGE_STAMPS,
+} from './snapshotMergeExplain.js';
 export {
   setupDbRootKey,
   initDbRootKey,

package/src/snapshotFileSync.js

@@ -0,0 +1,480 @@
+/**
+ * @glance-apps/sync 2.1.0: the snapshot-file sync cycle, moved here from
+ * dayGLANCE's src/sync/snapshotFileSync.js so every GLANCE app's iCloud and
+ * Direct Access tiers run one cycle (dayGLANCE's docs/direct-access-sync.md).
+ *
+ * A snapshot-file transport is a local file that something else ferries
+ * between devices: an iCloud ubiquity container, a Nextcloud / Google Drive /
+ * Dropbox / Syncthing folder. There is no server and no ETag, so the cycle
+ * is: read the whole file, merge it with local state by the same three-way
+ * merge the WebDAV tier uses, apply what changed locally, and write the
+ * merged result back. Pure: the transport, the merge, the apply, the crypto
+ * and the app's storage keys all come in through the arguments. Every guard
+ * has a test that fails when it is removed:
+ *
+ *   • an ABSENT file is seeded from local data, but only once the seed guard
+ *     (evaluateMissingSnapshot) says absence is not a transient eviction, and
+ *     only when the payload is not an empty copy of a populated store;
+ *   • a 'downloading' placeholder and an unparseable file skip the cycle;
+ *   • an 'error' object is surfaced, never merged;
+ *   • an encrypted envelope is decrypted when the key is cached; when it cannot
+ *     be, the transport decides whether local data may be written over it as
+ *     plaintext (iCloud: yes, it is a legacy cleanup inside Apple's container;
+ *     Direct Access: never, the folder is someone else's cloud);
+ *   • a real snapshot stamps the transport's own last-synced key BEFORE the
+ *     first-run prompt, because reading it is what proves the transport works;
+ *   • a fresh device facing a populated snapshot is asked, not restored;
+ *   • writes are throttled per transport so a daemon's round-trip is not raced;
+ *   • health-store counts are stripped from every copy written out, on the
+ *     transports that ask for it (`io.outgoing`): dayGLANCE's iCloud file does,
+ *     for Apple's guideline 5.1.3; Direct Access is someone else's folder and
+ *     carries them, exactly as GLANCEvault and WebDAV do;
+ *   • a write happens only when what would be written differs from the file,
+ *     and an apply only when the merged data differs from local state. The
+ *     merge's own flags are necessary, not sufficient: with the strip above
+ *     they fired on every cycle of every Mac holding health counts, and the
+ *     resulting identical rewrites starved every phone (2026-10-05);
+ *   • a change made on this device is written at once; a change that reached
+ *     this device by another road is only relayed once the file has sat
+ *     unchanged, still lacking it, for RELAY_CONFIRM_MS. A change reaches a
+ *     device by two roads at different speeds, GLANCEvault in seconds and the
+ *     folder's syncing tool in tens of seconds, so the second Mac learned of
+ *     an iPhone's edit from the vault, found its folder copy stale, wrote the
+ *     same data with a fresh stamp, and Nextcloud reported a conflict on
+ *     every change (2026-10-08). Deferring every write by one poll did not
+ *     help: it held the originating device's write back too, which only
+ *     lengthened the window in which the others relayed it. "Made here" is
+ *     the device's own last-edit stamp (`io.lastLocalEditAt`, set by the persist
+ *     pass for an edit and not for an apply) being newer than this device's
+ *     last write to, or before that last read of, this file.
+ *
+ * Nothing here touches React. An app's hook owns the poll, the mutex and the
+ * prompt state (dayGLANCE: hooks/useSnapshotFileSync.js); the app owns i18n
+ * and status UI.
+ */
+
+import { sliceDiffs, writeWorthy } from './snapshotMergeExplain.js';
+
+// ─── The seed guard ────────────────────────────────────────────────────────────
+
+/**
+ * How long an absent snapshot is assumed to be a temporary eviction. iCloud
+ * and the folder tools restore an evicted file within seconds; ten minutes is
+ * far past that while still being a delay a user would sit through.
+ */
+export const MISSING_GRACE_MS = 10 * 60 * 1000;
+
+/**
+ * Whether an absent file may be seeded, or is an eviction to wait out.
+ *
+ * @param {object} s
+ * @param {boolean} s.hasSyncedBefore  this device has previously read a real snapshot
+ * @param {number}  s.missingSince     epoch ms of the first consecutive sighting of
+ *                                     the file as absent, or 0 if it was present last cycle
+ * @param {number}  s.now              epoch ms
+ * @param {number} [s.graceMs]
+ * @returns {{skip: boolean, missingSince: number}}
+ *   skip         — true to leave the file alone this cycle
+ *   missingSince — the value to carry into the next cycle (0 clears the streak)
+ */
+export function evaluateMissingSnapshot({ hasSyncedBefore, missingSince, now, graceMs = MISSING_GRACE_MS } = {}) {
+  // Never synced: nothing can have been evicted, so this is a real first run
+  // and seeding is the correct, necessary behaviour.
+  if (!hasSyncedBefore) return { skip: false, missingSince: 0 };
+  // First cycle seeing it absent: start the clock and wait.
+  if (!missingSince) return { skip: true, missingSince: now };
+  // Still inside the window: keep waiting, preserving the original sighting so
+  // the window measures the whole streak rather than restarting every cycle.
+  if (now - missingSince < graceMs) return { skip: true, missingSince };
+  // Gone long enough that eviction no longer explains it. Seed, and clear the
+  // streak so the next absence starts its own window.
+  return { skip: false, missingSince: 0 };
+}
+
+// ─── The first-run prompt ──────────────────────────────────────────────────────
+
+/**
+ * A fresh install facing populated remote data is asked whether to restore
+ * rather than restored silently: only when no decision was recorded, the
+ * remote copy has data, this device has none, and the transport is reachable.
+ */
+export function shouldPromptFirstRun({ decided, remoteHasData, localHasData, available = true } = {}) {
+  return !!(!decided && remoteHasData && !localHasData && available);
+}
+
+/** The default `io.hasData`: any non-empty array in the data. Apps that know their content slices pass their own. */
+export function payloadHasData(data) {
+  if (!data || typeof data !== 'object') return false;
+  return Object.values(data).some((v) => Array.isArray(v) && v.length > 0);
+}
+
+// The two stamps an app keeps around the cycle are the app's own storage keys,
+// handed in through `io`: `io.localModifiedKey` (stamped on every apply, so the
+// app's other engines see the device changed) and `io.lastLocalEditAt` (when
+// this device itself last changed its data, set by the app's persist pass for
+// an edit made here and not for an apply from a transport).
+
+/**
+ * How long a change that reached this device by another road must stay
+ * missing from an unchanged file before this device relays it. Longer than
+ * the folder's syncing tool takes to deliver the originating device's own
+ * write (Nextcloud's desktop client polls every 30 s without push), so the
+ * relay only happens when nobody else carried it.
+ */
+export const RELAY_CONFIRM_MS = 90 * 1000;
+
+/**
+ * The relay rule, shared with the event-set cycle (intents/folderIntents.js):
+ * a change this device did not make goes out only once the same difference
+ * (`fingerprint`, against the file version it was seen on) has been seen
+ * again RELAY_CONFIRM_MS later. Returns whether to write now and the pending
+ * look to carry: a different fingerprint starts over, the same one is kept.
+ *
+ * @param {{fingerprint: string, at: number}|null} pending
+ * @param {string} fingerprint
+ * @param {number} now
+ * @returns {{write: boolean, pending: {fingerprint: string, at: number}}}
+ */
+export function relayDecision(pending, fingerprint, now, waitMs = RELAY_CONFIRM_MS) {
+  if (pending && pending.fingerprint === fingerprint && now - pending.at >= waitMs) {
+    return { write: true, pending };
+  }
+  return { write: false, pending: (!pending || pending.fingerprint !== fingerprint) ? { fingerprint, at: now } : pending };
+}
+
+/**
+ * Relays are staggered across devices, a minute per rank. A change that
+ * arrives by another road (the vault's push nudge, an edit from a phone whose
+ * folder tool round-trips slowly) reaches every device on the folder within
+ * the same second, so with one relay clock they all wrote the same file
+ * together, 90 s later, and the folder kept a conflict copy per pair (two
+ * Macs, 2026-10-10). Each writer stamps its device id in the file header;
+ * each device ranks itself among the writers it has seen there, and waits an
+ * extra RELAY_STAGGER_MS per rank. The first-ranked device writes at 90 s;
+ * the next sees the file catch up before its own clock runs out and drops
+ * the relay. A device that has not seen the others yet ranks first, collides
+ * at most once, then learns them from the file.
+ */
+export const RELAY_STAGGER_MS = 60 * 1000;
+const WRITERS_LIMIT = 32;
+
+/** The writers seen in a transport's file, under `${transport.lastSyncedKey}:writers`. */
+export function readWriters(storage, key) {
+  try {
+    const v = JSON.parse(storage?.getItem(key) ?? '[]');
+    return Array.isArray(v) ? v.filter((w) => typeof w === 'string') : [];
+  } catch { return []; }
+}
+
+/** Records a writer id read from the file. Returns true when it was new. */
+export function noteWriter(storage, key, writer) {
+  if (typeof writer !== 'string' || !writer) return false;
+  const seen = readWriters(storage, key);
+  if (seen.includes(writer)) return false;
+  seen.push(writer);
+  try { storage?.setItem(key, JSON.stringify(seen.slice(-WRITERS_LIMIT))); } catch { /* ignore */ }
+  return true;
+}
+
+/** This device's relay wait: RELAY_CONFIRM_MS plus a minute per rank among the writers seen (its own id included). */
+export function relayWaitMs(storage, key, self) {
+  if (typeof self !== 'string' || !self) return RELAY_CONFIRM_MS;
+  const ids = [...new Set([...readWriters(storage, key), self])].sort();
+  return RELAY_CONFIRM_MS + ids.indexOf(self) * RELAY_STAGGER_MS;
+}
+
+/**
+ * Classifies the raw text a transport read.
+ *
+ * @param {string|null|undefined} str
+ * @returns {{kind: 'absent'}
+ *        | {kind: 'unparseable'}
+ *        | {kind: 'downloading'}
+ *        | {kind: 'error', error: string}
+ *        | {kind: 'snapshot', remote: object}}
+ */
+export function classifySnapshotText(str) {
+  if (!str || str === 'null') return { kind: 'absent' };
+  let remote;
+  try { remote = JSON.parse(str); } catch { return { kind: 'unparseable' }; }
+  if (remote?.downloading) return { kind: 'downloading' };
+  if (remote?.error) return { kind: 'error', error: String(remote.error) };
+  return { kind: 'snapshot', remote };
+}
+
+/**
+ * Runs one cycle. Never throws for a transport outcome; a thrown error from
+ * `io` (a bug) propagates so the caller's `finally` still releases its lock.
+ *
+ * @param {object} args
+ * @param {object} args.transport
+ * @param {string}   args.transport.id                     for log lines
+ * @param {() => Promise<string|null>} args.transport.read
+ * @param {(text: string) => Promise<boolean>} args.transport.write
+ * @param {string}   args.transport.lastSyncedKey          storage key this transport stamps
+ * @param {() => boolean} args.transport.firstRunDecided   has the user answered the restore prompt
+ * @param {number}   args.transport.writeThrottleMs
+ * @param {boolean}  args.transport.allowsPlaintextReseed  may an undecryptable envelope be overwritten
+ * @param {() => boolean} [args.transport.encryptsWrites]  the per-device switch: seed and upgrade as an envelope
+ * @param {object} args.io
+ * @param {() => object} args.io.buildSyncPayload          `{ version, lastModified?, data }`
+ * @param {(data: object, opts: {allowEmpty: boolean}) => void} args.io.applyEngineData
+ * @param {(local: object, remote: object, retentionDays: number) => {data: object, localChanged: boolean, remoteChanged: boolean, deviceLocalKeys?: string[]}} args.io.mergeSyncData
+ * @param {(payload: object) => object} [args.io.outgoing]  what the transport actually writes, from the plaintext payload (a strip of slices the file must not carry); identity by default
+ * @param {number}   args.io.syncRetentionDays
+ * @param {(envelope: object) => boolean} args.io.isEncryptedEnvelope
+ * @param {(envelope: object) => Promise<object>} args.io.decryptData
+ * @param {(payload: object) => Promise<object>} [args.io.encryptData]  plaintext payload → envelope
+ * @param {() => boolean} [args.io.encryptionReady]  can encryptData succeed now (a key or the passphrase is in memory)
+ * @param {Storage}  args.io.storage                        localStorage-like
+ * @param {() => string|null} [args.io.lastLocalEditAt]      when this device itself last changed its data (absent: never, every change is relayed)
+ * @param {string} [args.io.localModifiedKey]                 stamped with the time of every apply, for the app's other engines
+ * @param {() => number} [args.io.localItemCount]             how many items the app's own storage holds (the empty-state guard: a payload of nothing over a store of something is not seeded)
+ * @param {(data: object) => boolean} [args.io.hasData]       does a payload carry anything worth restoring (default payloadHasData)
+ * @param {string|(() => string)} [args.io.deviceId]          stamped as `writtenBy` in the file header; ranks this device's relay (relayWaitMs)
+ * @param {() => number} [args.io.now]
+ * @param {Console}  [args.io.log]
+ * @param {{missingSince: number, lastWriteAt: number, lastWrittenAt?: number, pendingWrite?: {fingerprint: string, at: number}|null}} args.state  carried between cycles
+ * @returns {Promise<{state: {missingSince: number, lastWriteAt: number, lastWrittenAt: number, pendingWrite: object|null}, outcome: object}>}
+ *   outcome.kind is one of:
+ *     'skipped'   (reason: 'missing-grace' | 'empty-state-guard' | 'downloading' |
+ *                  'unparseable' | 'no-data' | 'encrypted-unreadable' | 'key-needed')
+ *                 encrypted-unreadable carries needsKey: true when no key and no
+ *                 passphrase are in memory (the prompt collects one), false when
+ *                 the key in memory is the wrong one
+ *     'seeded'    the absent file was written from local data (wrote: boolean)
+ *     'reseeded'  an undecryptable envelope was replaced with local plaintext
+ *     'error'     (reason: 'unavailable', error) the transport reported an error
+ *     'prompted'  (info) a first-run restore choice is needed; nothing was written
+ *     'merged'    (localChanged, remoteChanged, applied, wrote, deferred, ownEdits, keyNeeded)
+ *                 deferred: a relay is wanted and waits for the file to catch up
+ *                 ownEdits: this device has a change of its own not yet written
+ *                 keyNeeded: a write is wanted as an envelope and no key is ready
+ *
+ * Encryption (docs/direct-access-sync.md, Phase 6): the file decides, the
+ * switch decides the first write. A file read as an envelope is written back
+ * as an envelope whatever the switch says (never downgrade someone else's
+ * cloud folder); a plaintext or absent file is written as an envelope when
+ * `transport.encryptsWrites()` is on. Every guard, the content gate and the
+ * made-here rule look at plaintext, before the envelope. A wanted envelope
+ * with no key ready is held, never written plaintext.
+ */
+export async function runSnapshotFileCycle({ transport, io, state }) {
+  const log = io.log ?? console;
+  const now = io.now ?? Date.now;
+  const next = {
+    missingSince: state?.missingSince ?? 0,
+    lastWriteAt: state?.lastWriteAt ?? 0,
+    // The last SUCCESSFUL write to this file (lastWriteAt counts attempts, for
+    // the throttle), or before any, the read before this cycle: the baseline
+    // an edit made here has to be newer than to count as not yet written.
+    lastWrittenAt: state?.lastWrittenAt ?? 0,
+    pendingWrite: state?.pendingWrite ?? null,
+  };
+  const lastLocalEdit = (() => {
+    try {
+      const v = io.lastLocalEditAt ? io.lastLocalEditAt() : null;
+      const t = v ? new Date(v).getTime() : NaN;
+      return Number.isFinite(t) ? t : 0;
+    } catch { return 0; }
+  })();
+  const deviceId = (() => {
+    try { const v = typeof io.deviceId === 'function' ? io.deviceId() : io.deviceId; return typeof v === 'string' && v ? v : null; }
+    catch { return null; }
+  })();
+  const writersKey = `${transport.lastSyncedKey}:writers`;
+  // The header every write carries: who wrote it (relayWaitMs).
+  const header = () => (deviceId ? { writtenBy: deviceId } : {});
+
+  // Writing faster than the daemon's round-trip piles conflict versions onto
+  // the remote; skip writes inside the window. The next poll re-runs the merge
+  // and writes any genuinely deferred change. The stamp is taken before the
+  // write so a failing write is throttled like a succeeding one.
+  const throttledWrite = async (text) => {
+    if (now() - next.lastWriteAt < transport.writeThrottleMs) return false;
+    next.lastWriteAt = now();
+    const ok = await transport.write(text);
+    if (!ok) log.error(`[${transport.id}] snapshot write failed`);
+    return ok;
+  };
+  // What the transport actually writes, from the plaintext payload: an app
+  // may strip slices a file must not carry (dayGLANCE's iCloud file leaves out
+  // HealthKit-derived counts for Apple's guideline 5.1.3). The strip reads
+  // plaintext, before any envelope, and never touches what is applied locally.
+  const strip = typeof io.outgoing === 'function' ? (payload) => io.outgoing(payload) ?? payload : (payload) => payload;
+
+  const read = classifySnapshotText(await transport.read());
+
+  // The file decides; the switch decides the first write.
+  const envelopeRead = read.kind === 'snapshot' && !!io.isEncryptedEnvelope(read.remote);
+  const envelopeOut = envelopeRead || !!transport.encryptsWrites?.();
+  const canEncrypt = typeof io.encryptData === 'function' && (io.encryptionReady ? !!io.encryptionReady() : true);
+  const keyNeeded = envelopeOut && !canEncrypt;
+  // Serialised after the health strip (the strip reads plaintext).
+  const encode = async (payload) => JSON.stringify(envelopeOut ? await io.encryptData(payload) : payload);
+  const outgoing = (payload) => encode(strip(payload));
+
+  if (read.kind === 'absent') {
+    // No remote file yet — seed it with local data, but only if the absence is
+    // real (not a transient eviction) and state is hydrated: if React state is
+    // empty while localStorage has tasks, seeding would wipe the remote copy.
+    const missing = evaluateMissingSnapshot({
+      hasSyncedBefore: !!io.storage.getItem(transport.lastSyncedKey),
+      missingSince: next.missingSince,
+      now: now(),
+    });
+    next.missingSince = missing.missingSince;
+    if (missing.skip) return { state: next, outcome: { kind: 'skipped', reason: 'missing-grace' } };
+    const localCount = typeof io.localItemCount === 'function' ? (io.localItemCount() || 0) : 0;
+    const payload = io.buildSyncPayload();
+    const hasData = io.hasData ?? payloadHasData;
+    if (localCount > 0 && !hasData(payload.data)) {
+      return { state: next, outcome: { kind: 'skipped', reason: 'empty-state-guard' } };
+    }
+    if (keyNeeded) return { state: next, outcome: { kind: 'skipped', reason: 'key-needed' } };
+    const wrote = await throttledWrite(await outgoing({ ...payload, ...header() }));
+    return { state: next, outcome: { kind: 'seeded', wrote } };
+  }
+
+  // Exists but is still coming down from the cloud, or is mid-write by the
+  // daemon: let the next poll retry.
+  if (read.kind === 'downloading') return { state: next, outcome: { kind: 'skipped', reason: 'downloading' } };
+  if (read.kind === 'unparseable') return { state: next, outcome: { kind: 'skipped', reason: 'unparseable' } };
+  if (read.kind === 'error') {
+    return { state: next, outcome: { kind: 'error', reason: 'unavailable', error: read.error } };
+  }
+
+  let remote = read.remote;
+  if (envelopeRead) {
+    let needsKey = false;
+    try { remote = await io.decryptData(remote); }
+    catch (decErr) {
+      log.warn(`[${transport.id}] encrypted snapshot could not be decrypted:`, decErr?.message ?? decErr);
+      needsKey = decErr?.code === 'PASSPHRASE_REQUIRED';
+      remote = null;
+    }
+    if (!remote?.data) {
+      if (!transport.allowsPlaintextReseed) {
+        // Someone else's cloud folder: never downgrade a file we cannot read.
+        // Nothing is applied and nothing is written; with no key in memory
+        // at all the caller prompts for the passphrase.
+        return { state: next, outcome: { kind: 'skipped', reason: 'encrypted-unreadable', needsKey } };
+      }
+      // iCloud's legacy-envelope cleanup: the file could not be followed, so
+      // this is the one write that is plaintext by design.
+      const wrote = await throttledWrite(JSON.stringify(strip(io.buildSyncPayload())));
+      return { state: next, outcome: { kind: 'reseeded', wrote } };
+    }
+  }
+  if (!remote?.data) return { state: next, outcome: { kind: 'skipped', reason: 'no-data' } };
+
+  // A real snapshot came back, so the transport demonstrably works from this
+  // device. Record that — it is what a later absence is measured against — and
+  // record it BEFORE the first-run prompt: reading the snapshot is what proves
+  // the transport works, whatever the user then chooses to do with it.
+  const previousRead = (() => {
+    try { const v = io.storage.getItem(transport.lastSyncedKey); const t = v ? new Date(v).getTime() : NaN; return Number.isFinite(t) ? t : 0; }
+    catch { return 0; }
+  })();
+  io.storage.setItem(transport.lastSyncedKey, new Date(now()).toISOString());
+  next.missingSince = 0;
+  if (!next.lastWrittenAt) next.lastWrittenAt = previousRead;
+  if (remote.writtenBy !== deviceId) noteWriter(io.storage, writersKey, remote.writtenBy);
+
+  // First launch on a device with no data of its own, facing a populated
+  // remote copy. Ask instead of restoring silently (shouldPromptFirstRun).
+  const localData = io.buildSyncPayload().data;
+  const hasData = io.hasData ?? payloadHasData;
+  if (shouldPromptFirstRun({
+    decided: transport.firstRunDecided(),
+    remoteHasData: hasData(remote.data),
+    localHasData: hasData(localData),
+    available: true,
+  })) {
+    return {
+      state: next,
+      outcome: {
+        kind: 'prompted',
+        info: {
+          // The app names its own slices; these two are dayGLANCE's and stay
+          // for its prompt. An app with other slices reads `data` itself.
+          taskCount: remote.data.tasks?.length ?? 0,
+          inboxCount: remote.data.unscheduledTasks?.length ?? 0,
+          lastModified: remote.lastModified ?? null,
+          data: remote.data,
+        },
+      },
+    };
+  }
+
+  const { data: mergedData, localChanged, remoteChanged, deviceLocalKeys = [] } =
+    io.mergeSyncData(localData, remote.data, io.syncRetentionDays);
+
+  // The merge's flags say whether it picked anything from either side. They do
+  // NOT say whether the file or the device would actually change, and the two
+  // questions differ: the iCloud write strips HealthKit-derived habit counts
+  // (the app's strip), so a device that holds those counts (any Mac
+  // receiving them through GLANCEvault) sees them "missing" from the file on
+  // every cycle, and the flag alone rewrote an identical stripped file every
+  // 15 s on every Mac in a fleet — which kept every phone's copy non-current
+  // and its edits stuck for minutes (2026-10-05). So a write needs a flag AND
+  // a real difference between what would be written and the file; an apply
+  // needs the flag AND a real difference between the merged data and local
+  // state. snapshotMergeExplain.js is that comparison, and an app's
+  // diagnostics panel can run the identical function. An order-only difference
+  // does not count for the write: the merge keeps each device's own order,
+  // so writing it changes nothing on the other device (writeWorthy).
+  const outPayload = strip({
+    version: 2,
+    lastModified: new Date(now()).toISOString(),
+    ...header(),
+    data: mergedData,
+  });
+  const applyNeeded = localChanged && sliceDiffs(mergedData, localData, { ignoreDropped: true }).length > 0;
+  // Device-local keys (the merge names them) are left out of the file
+  // question: every device keeps its own value, so the file's is nobody's.
+  const writable = (remoteChanged || localChanged)
+    ? writeWorthy(sliceDiffs(outPayload.data, remote.data, { ignoreKeys: deviceLocalKeys }))
+    : [];
+  const writeNeeded = writable.length > 0;
+
+  if (applyNeeded) {
+    // Apply the FULL merged data locally (health-sourced counts stay on-device).
+    io.applyEngineData(mergedData, { allowEmpty: !!remote.lastModified });
+    if (io.localModifiedKey) io.storage.setItem(io.localModifiedKey, new Date(now()).toISOString());
+  }
+
+  // Made here, or relayed (header). A change of this device's own goes out
+  // now. Anything else is relayed only after the file has sat unchanged,
+  // still lacking it, for RELAY_CONFIRM_MS: what was seen (the differences a
+  // write would resolve, against the file version they were seen on) has to
+  // be seen again that much later. A different file version starts over,
+  // since the slower road may just have delivered it.
+  const ownEdits = lastLocalEdit > next.lastWrittenAt;
+  let wrote = false;
+  let deferred = false;
+  if (writeNeeded && keyNeeded) {
+    // An envelope is wanted and nothing can seal it: hold the write where it
+    // is (the relay clock, if any, keeps running) and say so.
+  } else if (writeNeeded && ownEdits) {
+    wrote = await throttledWrite(await encode(outPayload));
+    if (wrote) next.lastWrittenAt = now();
+    next.pendingWrite = null;
+  } else if (writeNeeded) {
+    const fingerprint = `${remote.lastModified ?? ''}\u0000${writable.map((d) => d.summary).join('\n')}`;
+    const decision = relayDecision(next.pendingWrite, fingerprint, now(), relayWaitMs(io.storage, writersKey, deviceId));
+    next.pendingWrite = decision.pending;
+    if (decision.write) {
+      wrote = await throttledWrite(await encode(outPayload));
+      if (wrote) next.lastWrittenAt = now();
+    } else {
+      deferred = true;
+    }
+  } else {
+    next.pendingWrite = null;
+  }
+  return {
+    state: next,
+    outcome: { kind: 'merged', localChanged, remoteChanged, applied: applyNeeded, wrote, deferred, ownEdits, keyNeeded: writeNeeded && keyNeeded },
+  };
+}

package/src/snapshotMergeExplain.js

@@ -0,0 +1,254 @@
+/**
+ * Compares what a snapshot-file sync cycle would write and apply against what
+ * is already there, slice by slice.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────
+ * On 2026-10-05 every Mac in a fleet was seen rewriting dayglance-sync.json on
+ * every cycle: each diagnostics report showed the file modified ~30 ms after
+ * the cycle's read, with nothing changed on any device. Every such write made
+ * the phone's copy non-current, the phone then waited minutes for the download,
+ * and edits made on the phone in that window reached nobody.
+ *
+ * The cause was a collision of two correct rules. The iCloud write strips
+ * HealthKit-derived habit counts from the file (Apple guideline 5.1.3,
+ * the app's strip), while the Macs hold those counts locally because
+ * they arrive through GLANCEvault. So every merge saw 214 days of counts the
+ * file lacked, raised `remoteChanged`, wrote a stripped file identical to the
+ * one already there, and did it again next cycle. The merge's change flags
+ * answer "did the merge pick anything from local?", not "would the file
+ * change?", and only the second question should start a write.
+ *
+ * So the cycle now asks both: a write needs a flag AND a real difference
+ * between the outgoing (stripped) data and the file; an apply needs a flag AND
+ * a real difference between the merged data and local state. This module is
+ * that comparison, and the diagnostics panel runs the identical function so
+ * what it reports is what the cycle decides.
+ *
+ * Comparison rules: arrays of ids are matched by id with order noted
+ * separately, scalar lists compare as sets, maps by entry, everything else by
+ * canonical JSON. Absent and empty slices are equal, and so are absent and
+ * empty entries inside a map. Slices the merge
+ * re-stamps on every run (the tombstone fence) are ignored. For the apply
+ * question, slices the merge output simply does not carry are ignored too:
+ * applyEngineData leaves absent keys alone.
+ *
+ * Pure: no React, no storage, no bridge.
+ */
+
+/** JSON with object keys sorted at every level, so equal content compares equal. */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+const isIdList = (v) =>
+  Array.isArray(v) && v.length > 0 && v.every((x) => x && typeof x === 'object' && x.id !== undefined);
+const isPrimitiveList = (v) =>
+  Array.isArray(v) && v.every((x) => x === null || typeof x !== 'object');
+
+/**
+ * Slices the merge re-stamps on every run by design, so they differ from the
+ * file on every cycle without meaning anything. `tombstonePrunedBefore` is the
+ * fixed 60-day tombstone fence, recomputed from the clock each merge
+ * (the app's merge wrapper). The write decision never reads them; neither does this report.
+ */
+export const PER_MERGE_STAMPS = ['tombstonePrunedBefore'];
+
+/** An absent slice and an empty one are the same thing to every consumer. */
+const isEmptyish = (v) =>
+  v === undefined || v === null
+  || (Array.isArray(v) && v.length === 0)
+  || (typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0);
+
+/**
+ * Describes how `merged` differs from `other` for one slice, or null when it
+ * does not. `other` is the file for the write question, local state for the
+ * apply question.
+ *
+ * @returns {null | {key: string, kind: string, summary: string}}
+ */
+export function describeSliceDiff(key, merged, other) {
+  if (PER_MERGE_STAMPS.includes(key)) return null;
+  if (isEmptyish(merged) && isEmptyish(other)) return null;
+  const mergedMissing = merged === undefined;
+  const otherMissing = other === undefined;
+  if (mergedMissing && otherMissing) return null;
+  if (otherMissing) return { key, kind: 'added', summary: `${key}: added` };
+  if (mergedMissing) return { key, kind: 'dropped', summary: `${key}: dropped` };
+
+  // Collections of ids: match by id so an order change is reported as what it
+  // is rather than as every item differing.
+  if ((isIdList(merged) || isIdList(other)) && Array.isArray(merged) && Array.isArray(other)) {
+    const byId = (list) => new Map(list.filter((x) => x && x.id !== undefined).map((x) => [String(x.id), x]));
+    const m = byId(merged);
+    const o = byId(other);
+    // Name up to five ids per group: a report that says "-1 only on other
+    // side" without the id cannot be acted on (an Android inbox task the merge
+    // kept dropping, 2026-10-06).
+    const sample = (ids) => (ids.length ? ` (${ids.slice(0, 5).join(', ')}${ids.length > 5 ? ', …' : ''})` : '');
+    // A changed id names the fields that differ (up to four), so "habits: 1
+    // changed" says WHAT about the row differs (2026-10-09).
+    const fields = (a, b) => {
+      const keys = [...new Set([...Object.keys(a || {}), ...Object.keys(b || {})])].sort()
+        .filter((k) => canonicalJson(a?.[k]) !== canonicalJson(b?.[k]));
+      return keys.length ? `: ${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', …' : ''}` : '';
+    };
+    const changedIds = [];
+    const onlyMergedIds = [];
+    const onlyOtherIds = [];
+    for (const [id, item] of m) {
+      if (!o.has(id)) { onlyMergedIds.push(id); continue; }
+      if (canonicalJson(item) !== canonicalJson(o.get(id))) changedIds.push(`${id}${fields(item, o.get(id))}`);
+    }
+    for (const id of o.keys()) if (!m.has(id)) onlyOtherIds.push(id);
+    const changed = changedIds.length;
+    const onlyMerged = onlyMergedIds.length;
+    const onlyOther = onlyOtherIds.length;
+    const orderDiffers = changed === 0 && onlyMerged === 0 && onlyOther === 0
+      && merged.map((x) => String(x?.id)).join('\u0000') !== other.map((x) => String(x?.id)).join('\u0000');
+    if (!changed && !onlyMerged && !onlyOther && !orderDiffers) return null;
+    const parts = [];
+    if (changed) parts.push(`${changed} changed${sample(changedIds)}`);
+    if (onlyMerged) parts.push(`+${onlyMerged} only in result${sample(onlyMergedIds)}`);
+    if (onlyOther) parts.push(`-${onlyOther} only on other side${sample(onlyOtherIds)}`);
+    if (orderDiffers) parts.push('order differs');
+    return { key, kind: orderDiffers && parts.length === 1 ? 'order' : 'items', summary: `${key}: ${parts.join(', ')}` };
+  }
+
+  // Lists of scalars (completedTaskUids and the like): set arithmetic.
+  if (isPrimitiveList(merged) && isPrimitiveList(other)) {
+    const m = new Set(merged.map(canonicalJson));
+    const o = new Set(other.map(canonicalJson));
+    let plus = 0;
+    let minus = 0;
+    for (const v of m) if (!o.has(v)) plus += 1;
+    for (const v of o) if (!m.has(v)) minus += 1;
+    if (!plus && !minus) {
+      if (merged.length !== other.length) return { key, kind: 'duplicates', summary: `${key}: same set, ${merged.length} vs ${other.length} entries` };
+      return null;
+    }
+    return { key, kind: 'set', summary: `${key}: +${plus} / -${minus}` };
+  }
+
+  if (canonicalJson(merged) === canonicalJson(other)) return null;
+
+  // Maps keyed by something (habitLogs, dailyNotes, dayWindows…): say how many.
+  // An empty entry and an absent one are the same thing here too: the HealthKit
+  // strip leaves a day whose only count it removed as `{}`, and the file may
+  // hold that day or not depending on which device last wrote it.
+  if (merged && other && typeof merged === 'object' && typeof other === 'object' && !Array.isArray(merged) && !Array.isArray(other)) {
+    const keys = new Set([...Object.keys(merged), ...Object.keys(other)]);
+    let n = 0;
+    for (const k of keys) {
+      if (isEmptyish(merged[k]) && isEmptyish(other[k])) continue;
+      if (canonicalJson(merged[k]) !== canonicalJson(other[k])) n += 1;
+    }
+    if (n === 0) return null;
+    return { key, kind: 'map', summary: `${key}: ${n} of ${keys.size} entries differ` };
+  }
+  return { key, kind: 'value', summary: `${key}: differs` };
+}
+
+/**
+ * Every slice in which `a` differs from `b`.
+ *
+ * @param {object} a    the data about to be written or applied
+ * @param {object} b    the data already there (file, or local state)
+ * @param {{ignoreDropped?: boolean, ignoreKeys?: Iterable<string>}} [opts]
+ *        ignoreDropped: skip slices `a` does not carry at all (for the apply
+ *        question: absent keys are left alone); ignoreKeys: slices to leave
+ *        out altogether (the merge's device-local keys, for the write question:
+ *        every device keeps its own value, so the file's is nobody's business)
+ * @returns {Array<{key: string, kind: string, summary: string}>}
+ */
+export function sliceDiffs(a, b, { ignoreDropped = false, ignoreKeys = [] } = {}) {
+  const skip = new Set(ignoreKeys);
+  const keys = [...new Set([...Object.keys(a || {}), ...Object.keys(b || {})])].sort();
+  const out = [];
+  for (const k of keys) {
+    if (skip.has(k)) continue;
+    if (ignoreDropped && a?.[k] === undefined) continue;
+    const d = describeSliceDiff(k, a?.[k], b?.[k]);
+    if (d) out.push(d);
+  }
+  return out;
+}
+
+/**
+ * The differences a write can actually resolve. An order-only difference in
+ * an id-keyed list is not one: the merge keeps each device's own order
+ * (mergeArrayById preserves local order and appends remote-only items), so
+ * writing it never changes the other device's order, and two devices that
+ * order a list differently would rewrite the file in turn forever. Two Macs
+ * did, over todayRoutines (2026-10-05). The difference is still reported;
+ * it just does not start a write.
+ */
+export const writeWorthy = (diffs) => diffs.filter((d) => d.kind !== 'order');
+
+/**
+ * Runs the merge and explains its outcome, with the write and apply decisions
+ * the cycle makes from it.
+ *
+ * @param {object} args
+ * @param {object} args.local          this device's payload `data` (buildSyncPayload().data)
+ * @param {object} args.remote         the file's `data`
+ * @param {number} args.retentionDays
+ * @param {(local, remote, retentionDays) => {data: object, localChanged: boolean, remoteChanged: boolean, deviceLocalKeys?: string[]}} args.merge
+ * @param {(data: object) => object} [args.outgoing]  what the transport would
+ *        actually write (the iCloud HealthKit strip); identity by default
+ * @returns {{
+ *   localChanged: boolean, remoteChanged: boolean,   the merge's own flags
+ *   fileDiffs: Array<{key, kind, summary}>,          outgoing vs file
+ *   deviceDiffs: Array<{key, kind, summary}>,        merged vs local (dropped slices ignored)
+ *   wouldWrite: boolean,                             a flag AND a file difference a write can resolve
+ *   wouldApply: boolean,                             localChanged AND a device difference
+ *   writeFlagWithoutDiff: boolean,                   a write flag with no file difference a write could resolve
+ *   applyFlagWithoutDiff: boolean,                   an apply flag with no device difference
+ *   flagWithoutDiff: boolean,                        either of the two
+ *   error: string|null,
+ * }}
+ */
+export function explainSnapshotMerge({ local, remote, retentionDays, merge, outgoing = (d) => d }) {
+  const empty = {
+    localChanged: false, remoteChanged: false, fileDiffs: [], deviceDiffs: [],
+    wouldWrite: false, wouldApply: false,
+    writeFlagWithoutDiff: false, applyFlagWithoutDiff: false, flagWithoutDiff: false, error: null,
+  };
+  let result;
+  try {
+    result = merge(local, remote, retentionDays);
+  } catch (err) {
+    return { ...empty, error: err?.message ?? String(err) };
+  }
+  const merged = result?.data ?? {};
+  const localChanged = !!result?.localChanged;
+  const remoteChanged = !!result?.remoteChanged;
+  let out;
+  try { out = outgoing(merged) ?? merged; } catch (err) { return { ...empty, localChanged, remoteChanged, error: err?.message ?? String(err) }; }
+  // Device-local keys (the app's merge wrapper, result.deviceLocalKeys) are left out of
+  // the file question: the file holds whichever device wrote last, and a
+  // write would change what no device reads.
+  const fileDiffs = sliceDiffs(out, remote, { ignoreKeys: result?.deviceLocalKeys ?? [] });
+  const deviceDiffs = sliceDiffs(merged, local, { ignoreDropped: true });
+  const flagged = remoteChanged || localChanged;
+  const writable = writeWorthy(fileDiffs);
+  // Each flag is judged against its own question. A Mac over a Direct Access
+  // folder reported "apply YES" with no device difference under a note about
+  // a skipped WRITE (2026-10-08): the note has to name the flag that fired.
+  const writeFlagWithoutDiff = remoteChanged && writable.length === 0;
+  const applyFlagWithoutDiff = localChanged && deviceDiffs.length === 0;
+  return {
+    localChanged,
+    remoteChanged,
+    fileDiffs,
+    deviceDiffs,
+    wouldWrite: flagged && writable.length > 0,
+    wouldApply: localChanged && deviceDiffs.length > 0,
+    writeFlagWithoutDiff,
+    applyFlagWithoutDiff,
+    flagWithoutDiff: writeFlagWithoutDiff || applyFlagWithoutDiff,
+    error: null,
+  };
+}

package/types/index.d.ts

@@ -904,3 +904,136 @@ export function recoverVaultSyncEngine(
   enrolled: true;
   deviceId: string;
 }>;
+
+// ---------------------------------------------------------------------------
+// Snapshot-file cycle (2.1.0): iCloud, Direct Access
+// ---------------------------------------------------------------------------
+
+/** How a transport's read is classified (classifySnapshotText). */
+export type SnapshotRead =
+  | { kind: 'absent' }
+  | { kind: 'downloading' }
+  | { kind: 'unparseable' }
+  | { kind: 'error'; error: string }
+  | { kind: 'snapshot'; remote: Record<string, unknown> };
+
+export function classifySnapshotText(text: string | null | undefined): SnapshotRead;
+
+export interface SnapshotFileTransport {
+  /** For log lines. */
+  id?: string;
+  read(): Promise<string | null>;
+  write(text: string): Promise<boolean>;
+  /** The storage key this transport stamps on every real read (the seed guard's "has synced before"). */
+  lastSyncedKey: string;
+  /** Has the user answered the first-run restore prompt. */
+  firstRunDecided(): boolean;
+  writeThrottleMs: number;
+  /** May an undecryptable envelope be overwritten with plaintext (iCloud: yes, a legacy cleanup; a folder: never). */
+  allowsPlaintextReseed: boolean;
+  /** The per-device switch that seeds and upgrades the file as an envelope. */
+  encryptsWrites?(): boolean;
+}
+
+export interface SnapshotFileIo {
+  buildSyncPayload(): { version: number; lastModified?: string; data: Record<string, unknown> };
+  applyEngineData(data: Record<string, unknown>, opts: { allowEmpty: boolean }): void;
+  mergeSyncData(local: Record<string, unknown>, remote: Record<string, unknown>, retentionDays: number): {
+    data: Record<string, unknown>;
+    localChanged: boolean;
+    remoteChanged: boolean;
+    /** Slices every device keeps its own value of; left out of the write question. */
+    deviceLocalKeys?: string[];
+  };
+  syncRetentionDays: number;
+  isEncryptedEnvelope(value: unknown): boolean;
+  decryptData(envelope: unknown): Promise<Record<string, unknown>>;
+  /** Plaintext payload to envelope; required when a transport encrypts or an envelope is read. */
+  encryptData?(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Can encryptData succeed now (a key or the passphrase is in memory). */
+  encryptionReady?(): boolean;
+  /** What the transport actually writes, from the plaintext payload (a strip of slices the file must not carry). */
+  outgoing?(payload: Record<string, unknown>): Record<string, unknown>;
+  storage: Pick<Storage, 'getItem' | 'setItem'>;
+  /** When this device itself last changed its data (ISO); absent: every change is relayed. */
+  lastLocalEditAt?(): string | null;
+  /** Stamped with the time of every apply, for the app's other engines. */
+  localModifiedKey?: string;
+  /** How many items the app's own store holds (the empty-state guard). */
+  localItemCount?(): number;
+  /** Does a payload carry anything worth restoring (default payloadHasData). */
+  hasData?(data: Record<string, unknown>): boolean;
+  /** Stamped as `writtenBy` in the file header; ranks this device's relay. */
+  deviceId?: string | (() => string);
+  now?(): number;
+  log?: Pick<Console, 'warn' | 'error'>;
+}
+
+export interface SnapshotFileState {
+  missingSince: number;
+  lastWriteAt: number;
+  lastWrittenAt?: number;
+  pendingWrite?: { fingerprint: string; at: number } | null;
+}
+
+export type SnapshotFileOutcome =
+  | { kind: 'skipped'; reason: 'missing-grace' | 'empty-state-guard' | 'downloading' | 'unparseable' | 'no-data' | 'key-needed' }
+  | { kind: 'skipped'; reason: 'encrypted-unreadable'; needsKey: boolean }
+  | { kind: 'seeded'; wrote: boolean }
+  | { kind: 'reseeded'; wrote: boolean }
+  | { kind: 'error'; reason: 'unavailable'; error: string }
+  | { kind: 'prompted'; info: { taskCount: number; inboxCount: number; lastModified: string | null; data: Record<string, unknown> } }
+  | { kind: 'merged'; localChanged: boolean; remoteChanged: boolean; applied: boolean; wrote: boolean; deferred: boolean; ownEdits: boolean; keyNeeded: boolean };
+
+/**
+ * One cycle of snapshot-file sync over an injected transport: the seed guard,
+ * the first-run prompt, the content gate, the made-here-or-relayed rule with
+ * relays staggered by writer rank, and the envelope rules (the file decides,
+ * the switch decides the first write). See src/snapshotFileSync.js.
+ */
+export function runSnapshotFileCycle(args: {
+  transport: SnapshotFileTransport;
+  io: SnapshotFileIo;
+  state: SnapshotFileState | null | undefined;
+}): Promise<{ state: Required<SnapshotFileState>; outcome: SnapshotFileOutcome }>;
+
+export const RELAY_CONFIRM_MS: number;
+export const RELAY_STAGGER_MS: number;
+export const MISSING_GRACE_MS: number;
+
+export function evaluateMissingSnapshot(s?: { hasSyncedBefore?: boolean; missingSince?: number; now?: number; graceMs?: number }): { skip: boolean; missingSince: number };
+export function shouldPromptFirstRun(s?: { decided?: boolean; remoteHasData?: boolean; localHasData?: boolean; available?: boolean }): boolean;
+export function payloadHasData(data: unknown): boolean;
+
+/** The relay rule: write once the same fingerprint has been seen for `waitMs`; a different one starts over. */
+export function relayDecision(
+  pending: { fingerprint: string; at: number } | null,
+  fingerprint: string,
+  now: number,
+  waitMs?: number,
+): { write: boolean; pending: { fingerprint: string; at: number } };
+/** RELAY_CONFIRM_MS plus RELAY_STAGGER_MS per writer that sorts before this device among those seen. */
+export function relayWaitMs(storage: Pick<Storage, 'getItem'>, key: string, self: string | null): number;
+export function noteWriter(storage: Pick<Storage, 'getItem' | 'setItem'>, key: string, writer: unknown): boolean;
+export function readWriters(storage: Pick<Storage, 'getItem'>, key: string): string[];
+
+/** A slice-level difference between two snapshot data objects. */
+export interface SliceDiff { key: string; kind: string; summary: string }
+export function canonicalJson(value: unknown): string;
+export function describeSliceDiff(key: string, merged: unknown, other: unknown): SliceDiff | null;
+export function sliceDiffs(a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined, opts?: { ignoreDropped?: boolean; ignoreKeys?: Iterable<string> }): SliceDiff[];
+export function writeWorthy(diffs: SliceDiff[]): SliceDiff[];
+export const PER_MERGE_STAMPS: string[];
+export function explainSnapshotMerge(args: {
+  local: Record<string, unknown>;
+  remote: Record<string, unknown>;
+  retentionDays: number;
+  merge: SnapshotFileIo['mergeSyncData'];
+  outgoing?: (data: Record<string, unknown>) => Record<string, unknown>;
+}): {
+  localChanged: boolean; remoteChanged: boolean;
+  fileDiffs: SliceDiff[]; deviceDiffs: SliceDiff[];
+  wouldWrite: boolean; wouldApply: boolean;
+  writeFlagWithoutDiff: boolean; applyFlagWithoutDiff: boolean; flagWithoutDiff: boolean;
+  error: string | null;
+};