@glance-apps/sync 1.11.0 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,217 @@ 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
+>
+> **Add `pullCursorCommit: 'per-page'` to your `createDbSyncEngine` config when
+> you take this release.** Without it you lose 1.10.0's mid-pagination resume
+> and silently regain the convergence bug it fixed: a large backlog on a flaky
+> connection re-downloads from the start on every failure instead of resuming
+> from the last good page.
+>
+> It will not look like a config gap. It will look like a network problem,
+> weeks after the bump, and nobody will connect the two. One line prevents it.
+
+**Should you take this release?** Yes, and read this entry before you do — it is
+the only release so far that changes what an existing caller gets **without that
+caller changing any code**.
+
+Since 1.10.0, `pullRemoteChanges` has persisted the pull cursor **per page**, on
+the assumption that a row is durable the moment `applyRemoteEntity` returns.
+That is true for a caller writing straight into its store. It is false for a
+caller applying into a per-cycle mirror it discards on failure
+(commit-only-on-success): those rows are consumed, the cursor advances past
+them, they are never committed, an incremental pull never re-lists them, and a
+glitch heal cannot reach them because they were never in a snapshot. That is
+permanent row loss, and it was demonstrated as such.
+
+The assumption was stated only in a source comment. The config contract
+documenting `applyRemoteEntity` said nothing about durability at all. **A
+caller cannot honour a contract it is never shown** — so it is now a declared,
+validated mode, and the default is the safe one.
+
+### Changed — BREAKING
+
+- **`pullCursorCommit` now controls when the pull cursor is persisted, and it
+  defaults to `'end-of-pull'`.** Previously the engine always behaved as
+  `'per-page'`, with no way to say otherwise.
+
+  | Mode | When the cursor advances | For |
+  |---|---|---|
+  | `'end-of-pull'` **(new default)** | Once, after a fully successful pagination loop | Any caller that has not thought about it |
+  | `'per-page'` | After each completed page — 1.10.0 behaviour | A caller whose apply is durable on return |
+  | `'caller'` | Never; the engine writes nothing | A commit-only-on-success composer |
+
+  Under `'end-of-pull'`, a mid-pagination failure re-pulls from where the run
+  started. Re-applying already-applied rows is idempotent under entity-grain
+  LWW, so the cost is bandwidth; the cost of the old default, for the wrong
+  caller, was rows.
+
+  In `'caller'` mode `pullRemoteChanges` returns `maxSeq` and the caller
+  commits it with `setHighWaterMark` once its own state is durable. No new API
+  was needed — `setHighWaterMark` was already public. `dbSyncCycle` commits for
+  itself on a fully successful cycle, so declaring `'caller'` and continuing to
+  use the cycle still converges.
+
+- **An unrecognised `pullCursorCommit` is REFUSED at construction**, not
+  defaulted. `'perPage'`, `'per_page'` or `'PER-PAGE'` throw with a message
+  naming every valid mode and the value actually passed. A typo silently
+  falling back to a default is precisely the failure this contract exists to
+  remove: it would quietly restore the unsafe behaviour on a caller that was
+  trying to opt out of it.
+
+### Why this is 2.0.0
+
+No API signature changed, and by the letter of this package's old versioning
+note — "breaking changes to the public API or the sync envelope schema" — this
+would have been a minor. That note was too narrow, and has been widened
+(see the README): **a behavioural default that changes what an existing caller
+gets without that caller changing code is breaking**, because the version
+number is the only signal that cannot be skipped. Under-signalling here costs a
+field bug that presents as a flaky connection; over-signalling costs a digit.
+
+### Why the default was flipped, and what argued against it
+
+The default is what the next composed caller inherits by saying nothing, and
+the next composed caller is an Obsidian plugin. Inheriting the unsafe path by
+saying nothing is exactly what put a data-loss bug in front of dayGLANCE.
+
+The alternative was real and was weighed: keep `'per-page'` as the default and
+require an explicit opt-out from callers needing the safe path. It costs the
+shipping consumers nothing and needs no major bump. It loses on the one point
+that matters — the unsafe path stays the thing you get by default — and the
+tiebreaker was sequencing rather than principle: all three consumers are
+touching engine config for 1.12.0 anyway, so the safe default costs them one
+extra line in a change they are already making. Had those landed far apart, the
+decision would have gone the other way.
+
+### Notes
+
+- **dayGLANCE's cursor rollback stays.** It covers two loss windows and
+  `'end-of-pull'` closes only the first. The second — the pull succeeded but a
+  later step (push, heal, commit) threw, so the mirror was discarded anyway —
+  is invisible to this package. Only `'caller'` mode closes both, and adopting
+  it is dayGLANCE's call on its own schedule.
+- **Per-page convergence does not come back for dayGLANCE under any mode.** It
+  needs per-page *durable* commits, which an all-or-nothing merge-aware commit
+  does not provide.
+- Not closed here: the cycle-only `syncing` re-entrancy guard (see 1.12.0).
+
+## [1.12.0] - 2026-08-30
+
+**Should you take this release?** Yes if anything in your app calls
+`pushDirtyRows`, `pullRemoteChanges` or `updateDeviceCursor` directly instead of
+`dbSyncCycle`. Until now the two tiers had unequal safety: the cycle carried
+backoff, over-quota suppression and the credential halt, and the primitives
+beneath it carried none. A caller composing its own cycle silently opted out of
+all three, with no signal that it had. This release moves enforcement down into
+the primitives, so every caller inherits it by construction. **If you only ever
+call `dbSyncCycle`, nothing about this release changes what your app does.**
+
+### Changed
+
+- **The three primitives now enforce their own protections.**
+  `pushDirtyRows` and `pullRemoteChanges` refuse to run while their direction's
+  backoff window is open, rejecting with a typed `SYNC_SUPPRESSED` error
+  *before* any network call, and they open, escalate and clear those windows
+  themselves. Both also refuse while the device is under the credential halt,
+  and both now SET the halt when a rejection reaches them — a guard over a halt
+  that nothing sets never fires, so it took both halves.
+- **`dbSyncCycle` delegates entirely downward.** It no longer checks a window
+  or records a failure; it distinguishes "my own gate refused this" from "the
+  server refused this" and reports as before. Enforcing in both places would
+  have **doubled the escalation** — `strikes` incrementing once in the
+  primitive and once in the cycle turns the ladder into 30s, 120s, 480s instead
+  of 30, 60, 120. The alternative shape (primitives no-op when called from
+  inside the cycle) was rejected: it makes correctness depend on a caller
+  passing a flag, which is the exact defect this release removes, relocated one
+  layer down.
+- **`updateDeviceCursor` is deliberately different**: halt-gated, but *not*
+  window-gated, never recording and never throwing. It reports a refusal as
+  `{ updated: false, suppressed: true }`. It cannot throw because callers await
+  it mid-cycle inside their own try blocks, and it is not window-gated because
+  the pull now records its own failure — so the window is already open by the
+  time the cursor report runs on the very cycle the pull was attempted, and
+  gating there would silently undo 1.10.0's decoupling ("the cursor report runs
+  whenever the pull was ATTEMPTED, success or failure"). Whether a cycle has
+  anything to report is a composition decision that stays with the caller.
+
+### Added
+
+- `SYNC_SUPPRESSED`: the typed rejection from the engine's own gate. It carries
+  `suppressed: true`, `direction` (`'push' | 'pull'`), `reason`, `causeCode`,
+  and `retryAt` / `retryInMs`.
+- `isSuppressedError(err)` — exported so a caller can tell a pause from a
+  failure **without string matching and without hardcoding a code literal**.
+
+### Notes for callers with their own retry ladder or circuit breaker
+
+- **Do not treat `SYNC_SUPPRESSED` as a failure.** This is the one integration
+  hazard in the release. An app that escalates its own cooldown on every thrown
+  error will escalate on a pause this engine already scheduled — two brakes
+  compounding, each correct in isolation, with the device waiting far longer
+  than either layer intends. Branch on `isSuppressedError(err)` (or
+  `err.suppressed`) and align to `err.retryAt` rather than adding a second
+  window on top of it.
+- **This cannot be made structurally impossible from inside the package.** The
+  app owns its breaker and reacts to what it catches; the only way to remove
+  the caller's judgement entirely would be for the package to own the whole
+  retry, which means adopting `dbSyncCycle` — exactly what composed callers
+  compose to avoid. So the signal is made as unmissable as we can: a typed
+  code, a redundant boolean, an exported predicate, and a retry deadline to
+  align to.
+- **Why a throw and not a skipped return value.** A return lets a caller that
+  ignores it treat a suppressed cycle as a successful one — committing state
+  built from a pull that never ran, and resetting its own breaker on a cycle
+  that did nothing. Throwing converts the worst failure mode from "silently
+  wrong" to "loudly refused". The argument the other way is real: a return
+  needs no `catch`, and a caller that forgets to special-case the code turns a
+  deliberate pause into what looks like an error. The `RATE_LIMITED` precedent
+  from 1.11.0 settled it — one shape for "the client refused this", not two.
+- **A direct call that fails now opens a window**, so an immediate retry of a
+  failed primitive is refused rather than re-sent. Retrying after `retryAt` is
+  the supported pattern; this is what the cycle has always done.
+
+### Notes
+
+- **Not closed by this release** (reported, deliberately unfixed): the
+  `syncing` re-entrancy guard is still cycle-only, so a composed caller can
+  overlap primitive calls. See the PR for what that does and why it is a
+  different shape of problem from the two this release addresses.
+- The cursor durability contract is Phase 4b and lands separately.
+
 ## [1.11.0] - 2026-08-30
 
 **Should you take this release?** Yes if you use the GLANCEvault transport, and

package/README.md

@@ -238,6 +238,8 @@ TypeScript declarations for all of the above are in `types/index.d.ts`.
 
 This package follows [Semantic Versioning](https://semver.org/). Breaking changes to the public API or the sync envelope schema will result in a major version bump.
 
+A **change to a behavioural default** counts as breaking and gets a major bump too, even when no API signature changes. The test is whether a dependent that changes none of its own code can get different behaviour by taking the release: if it can, the version number has to say so, because the changelog is the thing people skip. 2.0.0 flipped the pull-cursor default from per-page to end-of-pull on exactly this basis.
+
 ## License
 
 MIT

package/package.json

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