@glance-apps/sync 1.11.0 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,187 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.0.0",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/dbEngine.js

@@ -60,6 +60,28 @@ const ts = (v) => {
 // A window never becomes terminal: it only ever delays. Whatever the
 // interval, the next ordinary cycle after it expires probes again, with no
 // user action and no restart.
+// ─────────────────────────────────────────────────────────────────────────────
+// The pull-cursor durability contract (Phase 4b).
+//
+// pullRemoteChanges persists a cursor recording what this device has consumed.
+// Whether that is SAFE depends on something only the caller knows: whether
+// applyRemoteEntity made the row durable by the time it returned.
+//
+//   - lastGLANCE and lifeGLANCE write straight into Dexie, so it is durable
+//     immediately and the cursor may advance per page.
+//   - dayGLANCE applies into a per-cycle mirror that is DISCARDED on failure
+//     (commit-only-on-success). For it, a cursor advanced mid-pagination sits
+//     ahead of committed state: those rows are consumed, never committed,
+//     never re-listed by an incremental pull, and unreachable by its glitch
+//     heal — permanent row loss, demonstrated in the 1.10.0 survey.
+//
+// From 1.10.0 to 1.12.0 the per-page assumption was stated only in a source
+// comment, and 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.
+const PULL_CURSOR_MODES = ['end-of-pull', 'per-page', 'caller'];
+const DEFAULT_PULL_CURSOR_MODE = 'end-of-pull';
+
 const BACKOFF_BASE_S = 30;
 const MAX_PUSH_BACKOFF_S = 15 * 60; // writes, matching the file tier's upload cap
 const MAX_PULL_BACKOFF_S = 5 * 60;  // reads, matching the file tier's download cap
@@ -102,6 +124,27 @@ export const getOrCreateDeviceId = (storageKeyPrefix) => {
 
 // Storage keys shared between this engine and the connect/recovery flow in
 // vaultConnect.js. Defined once here so the two modules cannot drift.
+/**
+ * True when an error is this engine's own gate refusing a call (Phase 4a),
+ * rather than anything the server said.
+ *
+ * THE POINT OF THIS EXPORT is that a caller with its own retry ladder or
+ * circuit breaker must be able to tell "the package paused me" from "the
+ * request failed" WITHOUT string matching and without hardcoding a code
+ * literal that could drift. Treating a suppression as a failure is how two
+ * independent brakes compound: the app escalates its own cooldown on a pause
+ * the package already scheduled, and the device waits far longer than either
+ * layer intends while each looks correct in isolation.
+ *
+ * A suppressed error carries `retryAt` (epoch ms), so a caller that keeps its
+ * own schedule can ALIGN to this window rather than add a second one to it.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export const isSuppressedError = (err) =>
+  !!err && typeof err === 'object' && err.code === 'SYNC_SUPPRESSED';
+
 export const vaultCredentialKey = (storageKeyPrefix) => `${storageKeyPrefix}-vault-credential`;
 export const credentialHaltKey = (storageKeyPrefix) => `${storageKeyPrefix}-db-sync-credential-halt`;
 
@@ -123,7 +166,15 @@ export const credentialHaltKey = (storageKeyPrefix) => `${storageKeyPrefix}-db-s
  *
  * Data callbacks (the engine is data-shape agnostic):
  * @param {Function} config.getLocalEntity      - (entityId) => entity | null | Promise
- * @param {Function} config.applyRemoteEntity   - (entityId, entity) => void | Promise
+ * @param {Function} config.applyRemoteEntity   - (entityId, entity) => void | Promise.
+ *   DURABILITY MATTERS HERE, and what you promise decides pullCursorCommit
+ *   below. If this function has made the row durable by the time it resolves
+ *   (a direct store write), the pull cursor may safely advance page by page.
+ *   If it writes somewhere your caller may still DISCARD — a per-cycle mirror
+ *   committed only on success — then a cursor advanced mid-pagination sits
+ *   ahead of your committed state and those rows are lost: consumed, never
+ *   committed, never re-listed by an incremental pull. Declare the mode that
+ *   matches; the default assumes nothing.
  * @param {Function} config.applyRemoteDelete   - (entityId) => void | Promise
  * @param {Function} [config.isInsertOnly]       - (entity, entityId) => boolean
  * @param {Function} [config.getEntityLastModified] - (entity) => string|number (defaults to entity.lastModified)
@@ -133,6 +184,22 @@ export const credentialHaltKey = (storageKeyPrefix) => `${storageKeyPrefix}-db-s
  * @param {Function} [config.onError]      - (message, code, isHardStop) called with code 'KEY_MISMATCH' on a wrong key, 'VERIFIER_UNSUPPORTED' when the server can't host the verifier, or 'CREDENTIAL_INVALID' (isHardStop true) when the server rejects this device's credential — the cycle then halts until Phase 2.2 recovery exists
  * @param {Function} [config.onRowsSkipped] - (count, entityIds) called when a cycle skipped undecryptable rows
  * @param {boolean}  [config.allowUnverified=false] - operator escape hatch: downgrade VERIFIER_UNSUPPORTED to a logged warning and proceed (unsafe; off by default)
+ * @param {'end-of-pull'|'per-page'|'caller'} [config.pullCursorCommit='end-of-pull']
+ *   WHEN the pull cursor is persisted. Pick the one that matches what
+ *   applyRemoteEntity promises above; an unrecognised value is REFUSED at
+ *   construction rather than defaulted.
+ *   - 'end-of-pull' (default): once, after a fully successful pagination loop.
+ *     Safe for every caller, including one that has not thought about it. A
+ *     mid-pagination failure re-pulls from where the run started, which is
+ *     idempotent under entity-grain LWW.
+ *   - 'per-page': after each completed page. Requires a durable apply. Lets a
+ *     large backlog on a flaky connection resume from the last good page
+ *     instead of restarting — the 1.10.0 convergence fix, now opt-in.
+ *   - 'caller': the engine never persists the cursor. pullRemoteChanges
+ *     returns maxSeq and the caller commits it with setHighWaterMark once its
+ *     own state is durable. The only mode under which the cursor can never
+ *     sit ahead of committed state, because the caller decides when.
+ *     dbSyncCycle commits for itself on a fully successful cycle.
  */
 export const createDbSyncEngine = (config) => {
   const {
@@ -156,6 +223,7 @@ export const createDbSyncEngine = (config) => {
     onError,
     onRowsSkipped,
     allowUnverified = false,
+    pullCursorCommit = DEFAULT_PULL_CURSOR_MODE,
   } = config;
 
   if (!storageKeyPrefix) throw new Error('createDbSyncEngine: storageKeyPrefix is required');
@@ -168,6 +236,17 @@ export const createDbSyncEngine = (config) => {
     // verifier's single-row GET).
     throw new Error('createDbSyncEngine: accountId is required');
   }
+  // REFUSED, NOT DEFAULTED. A typo silently falling back to a default is the
+  // exact failure this contract exists to remove: 'perPage' or 'per_page'
+  // would quietly restore the unsafe behaviour on a caller that was trying to
+  // opt OUT of it, and nothing would say so until rows went missing. Matches
+  // the vault's strict auth-mode parsing.
+  if (!PULL_CURSOR_MODES.includes(pullCursorCommit)) {
+    throw new Error(
+      `createDbSyncEngine: pullCursorCommit must be one of ${PULL_CURSOR_MODES.map((m) => `'${m}'`).join(', ')}` +
+      ` (got ${JSON.stringify(pullCursorCommit)})`
+    );
+  }
   if (typeof getLocalEntity    !== 'function') throw new Error('createDbSyncEngine: getLocalEntity is required');
   if (typeof applyRemoteEntity !== 'function') throw new Error('createDbSyncEngine: applyRemoteEntity is required');
   if (typeof applyRemoteDelete !== 'function') throw new Error('createDbSyncEngine: applyRemoteDelete is required');
@@ -354,6 +433,13 @@ export const createDbSyncEngine = (config) => {
     const code = err && err.code;
     if (code === 'PASSPHRASE_REQUIRED' || code === 'ACCOUNT_ID_REQUIRED') return null;
     if (code === 'CREDENTIAL_INVALID') return null;
+    // SYNC_SUPPRESSED is this engine's OWN gate refusing a call (Phase 4a). It
+    // is not evidence about the server — no request was made — so letting it
+    // record a failure would let an open window feed itself: every suppressed
+    // call would extend the window that suppressed it, and a caller polling on
+    // a short interval would never see it close. It must never open, extend or
+    // escalate anything.
+    if (code === 'SYNC_SUPPRESSED') return null;
     // QUOTA_EXCEEDED keeps its own reason so its descriptor keeps surfacing —
     // but it is ONE window, not a second one stacked on a transport window.
     if (code === 'QUOTA_EXCEEDED') return 'quota';
@@ -397,6 +483,69 @@ export const createDbSyncEngine = (config) => {
     return reason;
   };
 
+  // ── The gate (Phase 4a) ───────────────────────────────────────────────────
+  //
+  // A primitive called while its window is open fails FAST, before any network
+  // call, with a typed SYNC_SUPPRESSED error. The shape deliberately mirrors
+  // the vault client's RATE_LIMITED (1.11.0): a typed `code`, a boolean the
+  // caller can test without string matching, and a `retryAt` so a caller with
+  // its own scheduler can ALIGN to this window rather than stack a second one
+  // on top of it.
+  //
+  // WHY THROW RATHER THAN RETURN A SKIPPED SHAPE. A return would let a
+  // composed caller that ignores the value treat a suppressed cycle as a
+  // successful one — committing a mirror 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 and was weighed: 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. That is the trade — see the PR.
+  const suppressedError = (w, direction) => {
+    const retryInMs = Math.max(0, w.until - Date.now());
+    const err = new Error(
+      `${direction} suppressed: backing off after ${w.code || 'a failure'}` +
+      ` — retrying in ~${Math.ceil(retryInMs / 1000)}s`
+    );
+    err.code = 'SYNC_SUPPRESSED';
+    // Redundant on purpose. `code` is the discriminator; `suppressed` is a
+    // second, cheaper one for a caller whose error handling branches on a
+    // boolean, so nobody has to reach for a string comparison.
+    err.suppressed = true;
+    err.direction = direction;          // 'push' | 'pull'
+    err.reason = w.reason;              // 'quota' | 'auth' | 'transport'
+    err.cause = null;
+    err.causeCode = w.code;             // the typed error that opened the window
+    err.retryAt = w.until;              // epoch ms
+    err.retryInMs = retryInMs;
+    return err;
+  };
+
+  // Throws when the direction's window is open. The single gate: every
+  // network-touching primitive calls it, and nothing else does.
+  const guardWindow = (w, direction) => {
+    if (isOpen(w)) throw suppressedError(w, direction);
+  };
+
+  // Throws when the device is under the credential halt. Enforcement of a
+  // halt has two halves, and a composed caller needs both: refuse to run
+  // while halted (here), and SET the halt when a rejection is seen (in each
+  // primitive's catch, via noteCredentialRejection). Only the pair works —
+  // a guard over a halt nothing sets never fires.
+  //
+  // This is a READ of durable state (localStorage), so unlike the windows it
+  // is safe to check in more than one place: the cycle keeps its own halt
+  // check for the reporting and result shape it owes the app, and this guard
+  // covers every other caller. Idempotent reads cannot compound; only
+  // mutating enforcement had to move to exactly one place.
+  const guardHalt = (context) => {
+    const halt = getCredentialHalt();
+    if (!halt) return;
+    const err = new Error(halt.message || `${context} refused: this device's credential was rejected`);
+    err.code = 'CREDENTIAL_INVALID';
+    err.halted = true;
+    throw err;
+  };
+
   // Over-quota state, preserved exactly as 3.3 exposed it: non-null from the
   // rejection until a write actually succeeds (not merely until the window
   // expires), so an app can keep rendering "X of Y used" while the client
@@ -446,19 +595,37 @@ export const createDbSyncEngine = (config) => {
   // when this instance went inert, { halted } when the device halted — so the
   // cycle result matches what isSuperseded()/isCredentialHalted() report,
   // whichever path the rejection arrived by.
-  const applyCredentialRejection = (err) => {
+  // STATE ONLY (Phase 4a). Split out of applyCredentialRejection so a
+  // primitive can set the halt without also firing the cycle's reporting.
+  // The split is what lets a composed caller — one that never calls
+  // dbSyncCycle — still halt on a rejected credential. The identity rule and
+  // the superseded-inertness decision are untouched; this is only about which
+  // half of the work runs.
+  //
+  // IDEMPOTENT, and it has to be: a primitive notes the rejection on its way
+  // out, and the cycle then reports it through applyCredentialRejection,
+  // which notes it again. setCredentialHalt overwrites with the same message
+  // and isBearerSuperseded is a pure read, so the second note changes
+  // nothing.
+  const noteCredentialRejection = (err) => {
     const message = err?.message || String(err);
-    let outcome;
     if (isBearerSuperseded()) {
       // Replaced by recovery and the app kept a stale reference: go inert in
       // memory — surfaced once, then silent — leaving the shared halt key
       // alone so the recovered engine keeps syncing.
       supersededInert = true;
-      outcome = { superseded: true };
-    } else {
-      setCredentialHalt(message);
-      outcome = { halted: true };
+      return { superseded: true };
     }
+    setCredentialHalt(message);
+    return { halted: true };
+  };
+
+  // STATE + REPORTING. The cycle's path, unchanged in behaviour: it owes the
+  // app an onError/onStatusChange and a truthful result flag, and a primitive
+  // called directly owes none of that.
+  const applyCredentialRejection = (err) => {
+    const message = err?.message || String(err);
+    const outcome = noteCredentialRejection(err);
     onError?.(message, 'CREDENTIAL_INVALID', true);
     onStatusChange?.('error');
     return outcome;
@@ -635,7 +802,7 @@ export const createDbSyncEngine = (config) => {
   // verifyAccountKey, which throws KEY_MISMATCH (before any upsert) if the
   // derived key doesn't match the account — so a device can never upload rows
   // under a non-matching key.
-  const pushDirtyRows = async () => {
+  const pushDirtyRowsUnguarded = async () => {
     const dirty = getDirtySet();
     if (dirty.length === 0) return { written: 0, deleted: 0, maxSeq: getPushAck() };
 
@@ -690,6 +857,49 @@ export const createDbSyncEngine = (config) => {
     return { written: upserts.length, deleted: deletes.length, maxSeq };
   };
 
+  /**
+   * The push, with its protections attached (Phase 4a).
+   *
+   * Every caller gets the halt, the window and the window bookkeeping —
+   * dbSyncCycle and a hand-composed cycle alike. The cycle no longer checks
+   * or records anything for the push; it reads the result of what happened
+   * here. See the module note on delegation.
+   */
+  const pushDirtyRows = async () => {
+    // The guards sit INSIDE the try on purpose. A suppressed error then takes
+    // the same path out as any other failure and passes through
+    // recordFailure — where the SYNC_SUPPRESSED do-not-delay rule is what
+    // stops an open window from feeding itself. Guarding outside the try
+    // would make that rule unreachable defensive code, and a later change
+    // that produced a suppression deeper in the call could silently start
+    // extending the window that caused it. (The negative control at
+    // scripts/verify-phase-4a.mjs found exactly this: with the guards
+    // outside, removing the rule broke nothing.)
+    try {
+      guardHalt('push');
+      guardWindow(pushBackoff, 'push');
+      const result = await pushDirtyRowsUnguarded();
+      // Any success resets the window and its strike count, exactly as the
+      // file tier does. For a quota window this is also what clears the
+      // over-quota state: the operator acted, and no client action was
+      // needed or taken.
+      clearWindow(pushBackoff);
+      return result;
+    } catch (err) {
+      // A rejected credential is noted (not reported) here, so a caller that
+      // never runs the cycle still halts. recordFailure then classifies it as
+      // do-not-delay and opens nothing, exactly as the cycle's path did.
+      // `err.halted` marks an error raised by guardHalt from the STORED halt,
+      // as opposed to a fresh rejection from the server. Re-noting the former
+      // would keep rewriting the halt's timestamp on every refused call, so
+      // "when the credential was rejected" would drift into "when we last
+      // refused a call".
+      if (err && err.code === 'CREDENTIAL_INVALID' && !err.halted) noteCredentialRejection(err);
+      recordFailure(pushBackoff, err, MAX_PUSH_BACKOFF_S);
+      throw err;
+    }
+  };
+
   // Decrypts and applies one row with entity-grain LWW. Mutates the supplied
   // `dirty` Set in place (and persists it) when a remote write supersedes a
   // dirty local copy, so we do not re-push a superseded version. Returns true if
@@ -788,7 +998,7 @@ export const createDbSyncEngine = (config) => {
   // wrong key has aborted with KEY_MISMATCH before we get here; any decrypt
   // failure now is an INDIVIDUAL bad row. Such a row is counted, quarantined,
   // and its cursor advanced past — it must never throw and wedge the cycle.
-  const pullRemoteChanges = async () => {
+  const pullRemoteChangesUnguarded = async () => {
     await ensureRootKey();
 
     let since = getHighWaterMark();
@@ -828,26 +1038,56 @@ export const createDbSyncEngine = (config) => {
         if (typeof R.seq === 'number') since = Math.max(since, R.seq);
       }
 
-      // Persist the cursor PER PAGE, not once at the end. Every row in a page
-      // reaches a terminal outcome before we get here — applied, quarantined,
-      // or skipped as engine-reserved — so the cursor may safely advance past
-      // the whole page. Previously a failure on page 3 discarded the progress
-      // of pages 1 and 2, so a large backlog on a flaky connection could
-      // re-download the same pages forever and never converge; that is exactly
-      // the situation backoff is meant to help, so the two changes belong
-      // together.
-      setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
+      // PER-PAGE COMMIT POINT ('per-page' only). Every row in a page reaches a
+      // terminal outcome before we get here — applied, quarantined, or skipped
+      // as engine-reserved — so a caller whose apply is durable may safely
+      // advance past the whole page. That is what lets a large backlog on a
+      // flaky connection resume from the last good page instead of
+      // re-downloading from the start forever (the 1.10.0 convergence fix).
+      //
+      // It is NOT the default, because it is only correct for a caller that
+      // has told us its apply is durable. See PULL_CURSOR_MODES.
+      if (pullCursorCommit === 'per-page') {
+        setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
+      }
 
       hasMore = !!more;
     }
 
-    // Pull is the sole writer of the pull cursor. Advance it (monotonically)
-    // from the highest seq we actually listed this run. Retained for the
-    // zero-page case, and harmless after the per-page advance above.
-    setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
+    // END-OF-PULL COMMIT POINT. Reached only when the whole pagination loop
+    // completed — a page that throws exits above and leaves the cursor where
+    // the run started, which is the 1.6.1 semantic and is safe for every
+    // caller regardless of how it applies rows.
+    //
+    // In 'caller' mode the engine writes nothing at all: the returned maxSeq
+    // is the caller's to commit (via setHighWaterMark) once its own state is
+    // durable. That is the only mode under which the cursor can never sit
+    // ahead of what the caller has committed, because the caller decides when.
+    if (pullCursorCommit !== 'caller') {
+      setHighWaterMark(Math.max(getHighWaterMark(), maxSeq));
+    }
     return { maxSeq, appliedRemote, applied, skipped, skippedEntityIds };
   };
 
+  /**
+   * The pull, with its protections attached (Phase 4a). Same contract as the
+   * guarded push above.
+   */
+  const pullRemoteChanges = async () => {
+    // Guards inside the try — see pushDirtyRows for why.
+    try {
+      guardHalt('pull');
+      guardWindow(pullBackoff, 'pull');
+      const result = await pullRemoteChangesUnguarded();
+      clearWindow(pullBackoff);
+      return result;
+    } catch (err) {
+      if (err && err.code === 'CREDENTIAL_INVALID' && !err.halted) noteCredentialRejection(err);
+      recordFailure(pullBackoff, err, MAX_PULL_BACKOFF_S);
+      throw err;
+    }
+  };
+
   // ── Step 3: update device cursor ──────────────────────────────────────────
   // Best-effort: a failure here only affects tombstone GC timing, never sync
   // correctness, so it is swallowed. lastSeenSeq reports the pull cursor (what
@@ -855,6 +1095,36 @@ export const createDbSyncEngine = (config) => {
   // progress is the conservative value for server-side tombstone GC, since it
   // never lets the server reclaim a tombstone this device has not yet seen.
   const updateDeviceCursor = async () => {
+    // THE THIRD PRIMITIVE IS DELIBERATELY DIFFERENT (Phase 4a): halt-gated,
+    // NOT window-gated, never recording, and never throwing.
+    //
+    // It never throws because it never has. Callers await it mid-cycle inside
+    // their own try blocks (dayGLANCE does, at dbEngine.js:839, before its
+    // commit), so a best-effort call that suddenly threw would abort cycles
+    // that today shrug this off — and in dayGLANCE's case trigger a cursor
+    // rollback. Suppression is reported in the RETURN value instead.
+    //
+    // It never records because a failure here only affects tombstone GC
+    // timing. It is not evidence that sync is failing, so it must not be able
+    // to open or extend a window.
+    //
+    // IT IS NOT GATED ON THE PULL WINDOW, and this is the one place the Phase
+    // 4a design review got it wrong before the tests corrected it. Once the
+    // pull records its own failure, the pull window is ALREADY OPEN by the
+    // time the cycle reaches this call — so a window gate here would suppress
+    // the cursor report on the very cycle the pull was attempted, silently
+    // undoing the 1.10.0 decoupling ("the cursor report runs whenever the
+    // pull was ATTEMPTED, success or failure"). Whether to report on a given
+    // cycle is a COMPOSITION decision about what just happened, which belongs
+    // to the caller; the cycle makes it from its own pullSkipped, and a
+    // composed caller makes its own. Delegation moved enforcement down, not
+    // orchestration.
+    //
+    // What it does enforce is the terminal one: a halted device writes
+    // nothing, from any caller. Rate-limit protection it gets for free from
+    // the vault client's module-scope brake (1.11.0), which fails
+    // vault.device() fast without any window logic here.
+    if (getCredentialHalt()) return { updated: false, suppressed: true };
     try {
       return await vault.device(app, {
         accountId,
@@ -919,45 +1189,43 @@ export const createDbSyncEngine = (config) => {
       // report still happens. The dirty set is untouched by a failed push
       // (pushDirtyRows only clears it on full ack), so backoff changes WHEN
       // rows are retried, never WHETHER they are.
+      // DELEGATED (Phase 4a). The cycle no longer gates and no longer
+      // records: the primitives own both, for every caller. All the cycle
+      // does here is separate "my own gate refused this" from "the server
+      // refused this", because only the second is a failure to report.
+      //
+      // Doing both would DOUBLE the escalation: strikes would increment once
+      // in the primitive and once here, turning the ladder into 30s, 120s,
+      // 480s instead of 30, 60, 120.
       let pushError = null;
       let pushSkipped = false;
-      if (isOpen(pushBackoff)) {
-        pushSkipped = true;
-      } else {
-        try {
-          await pushDirtyRows();
-          // Any success resets the window and its strike count, exactly as the
-          // file tier does. For a quota window this is also what clears the
-          // over-quota state: the operator acted, and no client action was
-          // needed or taken.
-          clearWindow(pushBackoff);
-        } catch (err) {
-          pushError = err;
-          recordFailure(pushBackoff, err, MAX_PUSH_BACKOFF_S);
-        }
+      try {
+        await pushDirtyRows();
+      } catch (err) {
+        if (err && err.code === 'SYNC_SUPPRESSED') pushSkipped = true;
+        else pushError = err;
       }
 
       onStatusChange?.('downloading');
       let pullError = null;
       let pullSkipped = false;
       let pull = { applied: 0, skipped: 0, skippedEntityIds: [] };
-      if (isOpen(pullBackoff)) {
-        pullSkipped = true;
-      } else {
-        try {
-          pull = await pullRemoteChanges();
-          clearWindow(pullBackoff);
-        } catch (err) {
-          pullError = err;
-          recordFailure(pullBackoff, err, MAX_PULL_BACKOFF_S);
-        }
-        // The cursor report runs whenever the pull was ATTEMPTED, success or
-        // failure — that is the 3.3 decoupling applied to the pull. It is
-        // skipped only when the pull itself was skipped, because firing a
-        // write every cycle at a server we are backing off from is the exact
-        // hammering this fix removes.
-        await updateDeviceCursor();
+      try {
+        pull = await pullRemoteChanges();
+      } catch (err) {
+        if (err && err.code === 'SYNC_SUPPRESSED') pullSkipped = true;
+        else pullError = err;
       }
+      // The cursor report runs whenever the pull was ATTEMPTED, success or
+      // failure — the 3.3 decoupling applied to the pull — and is skipped
+      // only when the pull never ran, because firing a write every cycle at a
+      // server we are backing off from is the hammering this removes.
+      //
+      // This is COMPOSITION, not enforcement: the cycle is deciding whether
+      // this cycle has anything to report, which is what a cycle is for. It
+      // reads pullSkipped, which the primitive told it. No window is checked
+      // here and none is written.
+      if (!pullSkipped) await updateDeviceCursor();
 
       // A rejected credential can surface from the push or the pull once the
       // key is verified in-session (ensureRootKey then makes no network call,
@@ -1000,6 +1268,20 @@ export const createDbSyncEngine = (config) => {
         };
       }
 
+      // THE CYCLE IS A CALLER TOO ('caller' mode). It commits the cursor here,
+      // at the one point it knows everything landed — the same point it claims
+      // lastSynced. Without this, an app that declared 'caller' and then used
+      // dbSyncCycle would never advance the cursor and would re-pull its whole
+      // backlog forever; the mode would be a footgun aimed at the caller that
+      // read the docs most carefully.
+      //
+      // Committing only on a fully successful cycle is deliberate, and mirrors
+      // what a commit-only-on-success composer does: if the push failed, that
+      // caller discards its applied state, so the cursor must not move either.
+      if (pullCursorCommit === 'caller' && typeof pull.maxSeq === 'number') {
+        setHighWaterMark(Math.max(getHighWaterMark(), pull.maxSeq));
+      }
+
       const now = new Date().toISOString();
       localStorage.setItem(KEY_LAST_SYNCED, now);
       onStatusChange?.('success');

package/src/index.js

@@ -40,7 +40,14 @@ export {
 } from './engine.js';
 
 // Phase 3: database transport (selected via transportMode: 'database').
-export { createDbSyncEngine, getOrCreateDeviceId } from './dbEngine.js';
+export {
+  createDbSyncEngine,
+  getOrCreateDeviceId,
+  // Phase 4a: tells a caller's own retry ladder that the engine paused this
+  // call, rather than that the request failed. Branching on it is what keeps
+  // an app's breaker from stacking a second cooldown on the engine's window.
+  isSuppressedError,
+} from './dbEngine.js';
 export {
   createVaultClient,
   // Per-account auth substrate (vault Phase 1.4b): unauthenticated auth-mode

package/types/index.d.ts

@@ -46,7 +46,14 @@ export type SyncErrorCode =
   // `status: 429` and `retryInMs`, so any ladder that already treats a real
   // 429 as transient handles it unchanged. Never a hard stop: the window is
   // self-expiring and a success both releases it and halves the escalation.
-  | 'RATE_LIMITED';
+  | 'RATE_LIMITED'
+  // DB transport (1.12.0): this engine's OWN gate refused the call, because
+  // the direction's backoff window is open. No request was made. Carries
+  // `suppressed: true`, `direction`, `retryAt` and `retryInMs`. Never a hard
+  // stop and never a failure — a caller with its own retry ladder should
+  // treat it as a scheduled pause and align to `retryAt` rather than
+  // escalating a second cooldown on top of it (see isSuppressedError).
+  | 'SYNC_SUPPRESSED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -628,6 +635,18 @@ export interface DbSyncEngineConfig {
   // and proceed without verification (unsafe — a wrong-key device could push
   // poison rows). Off by default so the safe behavior is the default.
   allowUnverified?: boolean;
+
+  /**
+   * WHEN the pull cursor is persisted. Must match what `applyRemoteEntity`
+   * promises: if it has NOT made the row durable by the time it resolves —
+   * it writes into a per-cycle mirror the caller may discard — then anything
+   * but `'end-of-pull'` or `'caller'` loses rows on a mid-pagination failure.
+   *
+   * An unrecognised value is refused at construction, not defaulted.
+   *
+   * @default 'end-of-pull'
+   */
+  pullCursorCommit?: PullCursorCommit;
 }
 
 /** Result of a DB sync cycle / pull: how many rows applied vs. quarantined. */
@@ -715,9 +734,22 @@ export interface DbSyncEngine {
   transportMode: 'database';
   sync(): Promise<DbSyncResult>;
   dbSyncCycle(): Promise<DbSyncResult>;
+  /**
+   * Pushes the dirty set. Enforces the push backoff window and the credential
+   * halt for EVERY caller (1.12.0), not only dbSyncCycle: rejects with
+   * `SYNC_SUPPRESSED` while the window is open and with `CREDENTIAL_INVALID`
+   * while the device is halted, in both cases without touching the network.
+   */
   pushDirtyRows(): Promise<{ written: number; deleted: number; maxSeq: number }>;
+  /** As pushDirtyRows, against the pull window. */
   pullRemoteChanges(): Promise<DbSyncResult & { maxSeq: number; appliedRemote: boolean }>;
-  updateDeviceCursor(): Promise<{ updated: boolean }>;
+  /**
+   * Best-effort cursor report. Never throws and never opens a window. Halted
+   * devices report nothing and get `{ updated: false, suppressed: true }`;
+   * deliberately NOT gated on the pull window, because whether a given cycle
+   * has anything to report is the caller's composition decision.
+   */
+  updateDeviceCursor(): Promise<{ updated: boolean; suppressed?: boolean }>;
   ensureRootKey(): Promise<void>;
 
   markDirty(entityId: string): void;
@@ -773,8 +805,48 @@ export interface DbSyncEngine {
   vault: VaultClient;
 }
 
+/**
+ * When the pull cursor is persisted. Chosen to match what the caller's
+ * `applyRemoteEntity` promises: an unrecognised value is refused at
+ * construction rather than defaulted.
+ *
+ * - `'end-of-pull'` (default) — once, after a fully successful pagination
+ *   loop. Safe for every caller, including one that has not thought about it.
+ * - `'per-page'` — after each completed page. Requires an apply that is
+ *   durable on return. Lets a large backlog resume from the last good page.
+ * - `'caller'` — the engine never persists; `pullRemoteChanges` returns
+ *   `maxSeq` and the caller commits it with `setHighWaterMark`.
+ */
+export type PullCursorCommit = 'end-of-pull' | 'per-page' | 'caller';
+
 export function createDbSyncEngine(config: DbSyncEngineConfig): DbSyncEngine;
 
+/**
+ * True when an error is the engine's own gate refusing a call (`SYNC_SUPPRESSED`)
+ * rather than anything the server said.
+ *
+ * For callers that keep their own retry ladder or circuit breaker: treating a
+ * suppression as a failure is how two independent brakes compound, each
+ * looking correct in isolation while the device waits far longer than either
+ * intends. Branch on this (or on `err.suppressed`) and align to `err.retryAt`.
+ */
+export function isSuppressedError(err: unknown): boolean;
+
+/** The shape of a `SYNC_SUPPRESSED` rejection. */
+export interface SyncSuppressedError extends Error {
+  code: 'SYNC_SUPPRESSED';
+  suppressed: true;
+  /** Which half was refused. */
+  direction: 'push' | 'pull';
+  /** Why the window is open. */
+  reason: 'quota' | 'auth' | 'transport' | null;
+  /** The typed error that opened the window. */
+  causeCode: string | null;
+  /** Epoch ms the window closes. */
+  retryAt: number;
+  retryInMs: number;
+}
+
 /**
  * Package-owned stable device identifier: generated once (crypto.randomUUID)
  * and persisted under `{prefix}-device-id`. Used for both the device cursor