@glance-apps/sync 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -7,6 +7,180 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-08-01
+
+**Should you take this release?** Yes, for any deployment using the database
+(GLANCEvault) transport. Until now the DB sync engine had **no backoff of any
+kind**: on a persistent failure it re-sent the same request on every cycle,
+forever, at whatever rate the app polls. A server that was down, a device
+offline, a wrong token — all of them produced an unbounded request loop. This
+release adds the backoff the file tier has always had, and fixes two related
+defects found alongside it. The file-tier (WebDAV) engine is untouched.
+
+### Fixed
+
+- **The DB engine no longer hammers a failing server.** Both directions now
+  back off: 30s doubling to a 15-minute cap for pushes and a 5-minute cap for
+  pulls, with a flat one hour on an authentication failure — the file tier's
+  numbers, escalation curve and reset rule. Any success resets the window and
+  its strike count. A window only ever **delays**: the next ordinary cycle
+  after it expires probes again, with no user action and no restart, and
+  dirty rows are never dropped — backoff changes *when* a push is retried,
+  never *whether* it is.
+  - Unlike the file tier's, the DB engine's backoff is **self-enforcing**: the
+    engine skips its own work when called too soon. (The file tier's is
+    advisory — nothing reads `uploadBackoffUntil` except its getter, so
+    honouring it is the app's job. That is exactly why the hammering was live
+    in every published version.) `getUploadBackoffUntil()` and
+    `getDownloadBackoffUntil()` are exposed with the same names and meaning as
+    the file tier's so one scheduler can treat both tiers alike, but honouring
+    them is now an optimisation rather than a duty.
+- **A failed pull no longer aborts the cycle.** 1.9.0 contained push failures
+  but left pull failures throwing past the device-cursor report. A pull error
+  is now captured the same way, so the cursor still reports on a cycle whose
+  pull failed.
+- **The pull cursor is persisted per page.** It was written only after the
+  whole pagination loop, so a failure on page 3 discarded the progress of
+  pages 1 and 2 — a large backlog on a flaky connection could re-download the
+  same pages indefinitely and never converge. Every row in a page reaches a
+  terminal outcome (applied, quarantined, or skipped as engine-reserved)
+  before the page ends, so the cursor may safely advance past each completed
+  page.
+- **A rejected credential surfacing from the push or pull now halts.** Once
+  the key is verified in-session, `ensureRootKey` makes no network call, so a
+  mid-session revocation is first seen by the push or the pull — and 1.9.0's
+  error capture routed those away from the halt path. They now reach exactly
+  the same halt logic as before; the halt itself, its identity rule, and the
+  `invalid credential` body match are unchanged.
+
+### Changed
+
+- **Over-quota suppression is now one case of the backoff ladder**, not a
+  parallel mechanism. Its behaviour is unchanged — same curve, same
+  in-memory lifetime, still surfacing `QUOTA_EXCEEDED` with its descriptor on
+  every suppressed cycle so apps can render "X of Y used" — but
+  `getQuotaState()` and `isQuotaSuppressed()` are now derived from the push
+  window rather than a separate variable.
+- **A shared-mode 401 is now delayed rather than retried immediately.** It
+  opens the one-hour auth window instead of being re-sent every cycle. It is
+  still not terminal and still not the credential halt: it self-resumes.
+- New: `getBackoffState()` returns `{ push, pull }` windows with `until`,
+  `reason` (`'quota' | 'auth' | 'transport'`), `code`, `strikes` and `since`.
+  The `reason` is what lets an app distinguish a one-hour auth backoff from a
+  thirty-second transport one without inferring it from the timestamp.
+- The cycle result gains `pullFailed`, `pullSkipped` and `pullErrorCode`,
+  mirroring the push fields added in 1.9.0.
+
+### Notes
+
+- **Classes that are never delayed**, deliberately: `PASSPHRASE_REQUIRED` and
+  `ACCOUNT_ID_REQUIRED` fire before any network call and clear the instant the
+  app supplies the value, so a window would make the app feel broken for 30
+  seconds after a user types their passphrase; and `CREDENTIAL_INVALID` is
+  owned by the (terminal) credential halt, so stacking a window on it would be
+  meaningless at best. `QUOTA_EXCEEDED` opens exactly one window, its own.
+- **For app integration — do not render backoff from the last `onError`
+  message.** On a cycle suppressed by a quiet (transport or auth) window, the
+  cycle's usual `onError(null, null, false)` reset still fires and nothing is
+  re-surfaced, so an app that remembers the last error string will see it
+  *cleared* while `onStatusChange` reads `'error'`. This is deliberate (quiet
+  windows report once; repeating every cycle is the noise this release
+  removes). Render standing backoff from `getBackoffState()` — `reason` plus
+  `until` gives "retrying in Xs" — and treat `onError` as an event stream, not
+  a status store. Quota windows are the exception and keep re-surfacing
+  `QUOTA_EXCEEDED` with the descriptor each cycle.
+- The cycle result now reports a superseded stale instance truthfully:
+  `{ superseded: true }` rather than `{ halted: true }`, matching
+  `isSuperseded()` / `isCredentialHalted()` whichever path the credential
+  rejection arrived by.
+- A healthy client is unaffected: no window is ever opened, no added latency,
+  and an identical request pattern.
+
+## [1.9.0] - 2026-08-01
+
+**Should you take this release?** Yes if you run, or might run, a GLANCEvault
+server with a row cap configured (`GLANCEVAULT_QUOTA_*`, server Phase 3.2).
+Also yes for the sync-reliability fix below, which applies to **every**
+deployment including shared mode and unconfigured servers: before this
+release, a failed push also cost you the pull, so a device whose writes were
+failing silently stopped receiving other devices' changes too. Nothing here
+changes behavior against a server with no quota configured, which is and will
+remain the common case.
+
+### Fixed
+
+- **A failed push no longer prevents the pull.** The DB sync cycle threw
+  straight from a push failure to its error handler, so `pullRemoteChanges`
+  and the device-cursor report never ran. A device that could not write — for
+  *any* reason: a transport blip, a 500, a server-side cap — also stopped
+  **reading**, and silently fell behind its peers. The push error is now
+  captured, the pull and cursor run regardless, and the error is reported
+  after. Applies to every transport failure, not just the quota case that
+  exposed it. Behavior on a fully successful cycle is unchanged.
+  - A cycle whose push failed but whose pull succeeded now returns
+    `{ applied, skipped, skippedEntityIds, pushFailed: true, pushErrorCode,
+    quota }` — the pull's own numbers are reported as usual, and `onError`
+    fires with the push error's code and `isHardStop: false`. `lastSynced` is
+    deliberately **not** advanced (the device is not fully in step), and the
+    dirty rows are retained for the next cycle exactly as before.
+- **A quota rejection is no longer mislabelled "update your server".** The key
+  verifier's establishing write is a net-new entity, so a fresh device on an
+  account at the row cap gets a 413 there — and every error on that path was
+  relabelled `VERIFIER_UNSUPPORTED` ("Your GLANCEvault server needs to be
+  updated to support key verification"), sending the user to fix a server
+  that is working correctly. `QUOTA_EXCEEDED` now passes through that
+  classifier, the same way `CREDENTIAL_INVALID` and the client-readiness
+  codes already did.
+
+### Added
+
+- **Over-quota handling for the reachable dimension (server Phase 3.2 /
+  client Phase 3.3).** A 413 or 429 carrying the server's quota body
+  (`{ error: "quota exceeded", quota, limit, used, requested }`) is now typed
+  as `QUOTA_EXCEEDED` and carries the parsed descriptor, so consumers no
+  longer have to substring-match an error message to tell a quota rejection
+  from any other failure.
+  - **Never a halt.** A quota condition is the opposite of a rejected
+    credential: it clears when the operator raises the limit or reclaim runs
+    — with **no client action at all** — so the engine keeps running.
+    `isHardStop` is always `false`, nothing is persisted, and there is no
+    recovery entry point and nothing to clear.
+  - **Bounded, self-resuming suppression** instead of retrying a doomed write
+    every cycle: after a rejection the engine skips the *write* for 30s,
+    doubling on repeat to a 15-minute cap (the file tier's backoff shape),
+    while pulls and cursor reports continue untouched. The next ordinary
+    cycle after the window probes again; a write that gets through clears the
+    state by itself. Raising the server limit is picked up with no restart,
+    no re-enrollment, and no user action.
+  - New state queries: `getQuotaState()` (the descriptor plus `since` /
+    `retryAt`, in memory only) and `isQuotaSuppressed()`.
+  - **Defensive parse.** A body earns the typed classification only with the
+    exact wording, a non-empty `quota` string, and three finite numbers.
+    A missing field, a non-JSON body, a 413 with no quota fields, the legacy
+    SSE `{"error":"too many connections for account"}` 429, or an older
+    server that never sends this shape all degrade to the generic
+    `VAULT_ERROR` handled before — never a throw, never a mis-classification.
+    An **unrecognised** `quota` dimension from a newer server is passed
+    through verbatim and still treated as a quota condition, since the remedy
+    is the same; render an unfamiliar dimension generically.
+
+### Notes
+
+- **Scope: `rows` is the only quota dimension this package can reach.** The
+  server enforces `storage` and `concurrent-uploads` at the blob path, and
+  `intents` at the intents route; this package has no blob path (media is
+  stripped at the adapter boundary) and no intents path (that is
+  `@glance-apps/intents`), and no SSE client. So "text syncs while media
+  fails" is not something this package can exercise. Handling for those
+  dimensions belongs with the media transport work that would call them, and
+  was deliberately not written here.
+- **Known gap, not fixed here:** the DB engine has no backoff of any kind
+  outside the quota window above. On a persistent write failure the same
+  dirty rows are re-pushed on every cycle indefinitely, where the file tier
+  has exponential backoff with an auth-failure escalation. This is a real
+  defect with a live blast radius and it wants its own change rather than a
+  corner of this one.
+
 ## [1.8.0] - 2026-07-31
 
 ### Added
@@ -62,6 +236,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   credential minted and then lost to a persistence failure is superseded by
   the next successful enrollment for the same `(accountId, deviceId)`.
 
+### Fixed
+
+- **Device cursors now report on installs that never configured a
+  `deviceId`, automatically on upgrade.** Such installs have never updated
+  their device cursor: the cursor step silently no-opped (`{updated:
+  false}`) whenever no `deviceId` was passed, so the server's tombstone GC
+  had no cursor for those devices. On upgrade, a device id is generated and
+  persisted (`{prefix}-device-id`) at engine construction, and cursor
+  reporting begins on the first completed sync cycle — **no app changes
+  required**; this applies to plain `createDbSyncEngine` construction, not
+  only the new connect flow, and identically in shared and per-account
+  mode. Installs that already pass an explicit `deviceId` are unaffected
+  and keep using it. Operator note: an install this fixes has no prior
+  cursor history, so the newly generated id strands nothing.
+  (This shipped in 1.7.0's device-identity work but 1.7.0 was never
+  published; it reaches consumers with this release.)
+
+### Upgrade notes
+
+Two behavior changes arrive with the fix above, without opt-in:
+
+- **Engine construction now touches localStorage.** `getOrCreateDeviceId`
+  reads and writes `{prefix}-device-id` at construction time; previously
+  construction deferred all localStorage access to cycle time. In an
+  environment without a `localStorage` global, construction now fails where
+  it previously succeeded and failed later at first sync. Theoretical for
+  browser and WebView hosts (all three GLANCE apps), but if construction
+  throws before any network activity, look here first.
+- **Injected `vaultClient` consumers see new `device()` calls.** An engine
+  constructed with `config.vaultClient` and no `deviceId` previously made
+  zero `device()` calls; it now makes one per cycle. A mock or bridge
+  client without a `device()` method will throw inside the cursor step —
+  swallowed and warned, never fatal — but the console warning is new and
+  recurring. Affects tests with mock clients and native shells that inject
+  a bridge client.
+
 ## [1.7.0] - 2026-07-31
 
 ### Added

package/package.json

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

package/src/dbEngine.js

@@ -36,6 +36,35 @@ const ts = (v) => {
   return Number.isNaN(t) ? 0 : t;
 };
 
+// ── The backoff ladder ──────────────────────────────────────────────────────
+//
+// ONE windowing mechanism for every recoverable failure, carrying a `reason`.
+// It replaces the separate quota-suppression window added in 3.3, which was
+// already built to this shape — this consolidates two parallel things rather
+// than forcing two different ones together.
+//
+// The numbers, the escalation curve, the reset rule and the in-memory
+// lifetime are the FILE TIER'S (src/engine.js): 30s doubling to a 15-minute
+// cap for writes and a 5-minute cap for reads, a flat hour on an auth
+// failure, and any success resets both the counter and the window. That file
+// was read and deliberately not refactored.
+//
+// The ONE thing that differs, and the reason this fix exists: the file tier's
+// backoff is ADVISORY — nothing reads uploadBackoffUntil except its getter,
+// so honouring it is the calling app's job. That is why "the DB engine
+// hammers" is live in every published version. Here the engine ENFORCES its
+// own window (it skips the work when called too soon, exactly as 3.3's quota
+// suppression did) AND exposes the same getters, so a scheduler can still be
+// smart without being obliged to be.
+//
+// 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.
+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
+const AUTH_BACKOFF_MS = 60 * 60 * 1000; // flat hour, matching AUTH_FAILURE_BACKOFF_MS
+
 // randomUUID is missing in some non-secure-context WebViews; getRandomValues
 // is everywhere the rest of this package's crypto already runs.
 const randomUUID = () => {
@@ -197,6 +226,22 @@ export const createDbSyncEngine = (config) => {
   // stale reference the app forgot after recovery dies quietly instead of
   // hammering the server with a dead credential.
   let supersededInert = false;
+  // The two backoff windows. IN MEMORY ONLY, like the file tier's: a restart
+  // clears them, which is the right default — a relaunch is a user signalling
+  // "try now", and the failure re-opens the window immediately if it persists.
+  // Nothing here is persisted, so nothing can outlive the condition it
+  // describes or need a clearing path.
+  const newWindow = () => ({
+    until: 0,        // epoch ms; the work is skipped while this is in the future
+    strikes: 0,      // consecutive failures, driving the escalation
+    reason: null,    // 'quota' | 'auth' | 'transport'
+    code: null,      // the typed error code that opened it
+    message: null,
+    quota: null,     // the parsed descriptor, when reason === 'quota'
+    since: null,     // ISO of the most recent failure
+  });
+  const pushBackoff = newWindow();
+  const pullBackoff = newWindow();
   // Per-session cache: once the derived root key is proven against the account's
   // existing data (Part A), we never re-verify for the life of this engine.
   let verified = false;
@@ -293,6 +338,132 @@ export const createDbSyncEngine = (config) => {
     localStorage.setItem(KEY_CRED_HALT, JSON.stringify({ message, at: new Date().toISOString() }));
   };
 
+  // ── The backoff ladder: classify, open, clear ─────────────────────────────
+
+  // WHICH FAILURES OPEN A WINDOW. Returns null for the classes that must NOT
+  // be delayed:
+  //  - Readiness (PASSPHRASE_REQUIRED / ACCOUNT_ID_REQUIRED) fires BEFORE any
+  //    network call and clears the instant the app supplies the value. A
+  //    30-second delay after a user types their passphrase would read as
+  //    broken. The file tier has no equivalent class, so copying it faithfully
+  //    would have missed this.
+  //  - CREDENTIAL_INVALID is owned by the credential halt, which is terminal.
+  //    Stacking a window on top would be meaningless at best and could soften
+  //    a terminal state at worst.
+  const backoffReasonFor = (err) => {
+    const code = err && err.code;
+    if (code === 'PASSPHRASE_REQUIRED' || code === 'ACCOUNT_ID_REQUIRED') return null;
+    if (code === 'CREDENTIAL_INVALID') 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';
+    // A shared-mode 401 ("invalid device token") is a wrong/rotated token: it
+    // will not fix itself in 30 seconds and hammering an auth endpoint is the
+    // worst kind of noise, so it gets the file tier's flat hour. This is NOT
+    // the credential halt — it stays retryable and self-resuming.
+    //
+    // `cause` is consulted because the key verifier re-wraps whatever it hits
+    // as VERIFIER_UNSUPPORTED (keeping the original on err.cause), which would
+    // otherwise hide a 401 behind a fresh error carrying no status.
+    if (err && (err.status === 401 || (err.cause && err.cause.status === 401))) return 'auth';
+    return 'transport';
+  };
+
+  const openWindow = (w, err, reason, maxSeconds) => {
+    w.strikes += 1;
+    const ms = reason === 'auth'
+      ? AUTH_BACKOFF_MS
+      : Math.min(BACKOFF_BASE_S * Math.pow(2, w.strikes - 1), maxSeconds) * 1000;
+    w.until = Date.now() + ms;
+    w.reason = reason;
+    w.code = (err && err.code) || 'NETWORK_ERROR';
+    w.message = err?.message || String(err);
+    w.quota = reason === 'quota' && err && err.quota ? err.quota : null;
+    w.since = new Date().toISOString();
+  };
+
+  const clearWindow = (w) => {
+    w.until = 0; w.strikes = 0; w.reason = null;
+    w.code = null; w.message = null; w.quota = null; w.since = null;
+  };
+
+  const isOpen = (w) => w.until > Date.now();
+
+  // Record a failure against a window, honouring the do-not-delay classes.
+  // Returns the reason, or null when the failure opened no window.
+  const recordFailure = (w, err, maxSeconds) => {
+    const reason = backoffReasonFor(err);
+    if (reason) openWindow(w, err, reason, maxSeconds);
+    return reason;
+  };
+
+  // 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
+  // probes. Now derived from the push window rather than a parallel variable.
+  const getQuotaState = () => {
+    if (pushBackoff.reason !== 'quota') return null;
+    const d = pushBackoff.quota;
+    return {
+      quota: d ? d.quota : 'unknown',
+      limit: d ? d.limit : null,
+      used: d ? d.used : null,
+      requested: d ? d.requested : null,
+      message: pushBackoff.message,
+      since: pushBackoff.since,
+      retryAt: new Date(pushBackoff.until).toISOString(),
+    };
+  };
+  const isQuotaSuppressed = () => pushBackoff.reason === 'quota' && isOpen(pushBackoff);
+
+  // PER-REASON SURFACING on a cycle whose work was SKIPPED because a window is
+  // open. A quota window keeps surfacing QUOTA_EXCEEDED with its descriptor
+  // every cycle, because apps render "X of Y used" from it and a UI built
+  // after the rejection must still learn about it. A transport or auth window
+  // stays quiet after its first signal — the failure was already reported and
+  // repeating it every cycle is the noise this fix exists to remove. The
+  // status still reads 'error' in both cases: sync genuinely is not working.
+  //
+  // APP-INTEGRATION CONSEQUENCE (deliberate, do not "fix" by re-surfacing):
+  // because the cycle's onError(null) reset still fires on suppressed cycles,
+  // a quiet window means the app's LAST onError MESSAGE is cleared while
+  // onStatusChange reads 'error'. An app must therefore render standing
+  // backoff from getBackoffState() (reason + until — "retrying in Xs"), not
+  // from a remembered onError string. Surface this when integrating the
+  // three apps.
+  const surfaceStandingWindow = (w) => {
+    if (w.reason === 'quota') onError?.(w.message, 'QUOTA_EXCEEDED', false);
+  };
+
+  // The credential-rejection path, extracted UNCHANGED from the cycle's catch
+  // so a 401 surfacing from the push or the pull reaches exactly the same
+  // logic it always reached from ensureRootKey. Nothing about the halt, the
+  // identity rule, or the superseded-inertness decision is altered — this is
+  // only about where the error is allowed to arrive from. Under NO
+  // circumstances does the engine re-enroll here; recovery is user-initiated
+  // (recoverVaultSyncEngine).
+  // Returns the truthful result flag for the cycle to spread — { superseded }
+  // 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) => {
+    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 };
+    }
+    onError?.(message, 'CREDENTIAL_INVALID', true);
+    onStatusChange?.('error');
+    return outcome;
+  };
+
   // The halt-set identity rule (Phase 2.2). The halt key is shared by every
   // engine instance on this device, so a STALE instance — one still holding a
   // credential that recovery has since replaced — must not be able to re-set
@@ -355,8 +526,13 @@ export const createDbSyncEngine = (config) => {
   // Likewise a rejected credential (401 "invalid credential") is an auth
   // outcome, not a capability one: pass it through so the cycle's halt
   // handling sees it — and so allowUnverified can never wave a revoked
-  // device through.
-  const isPassThrough = (err) => isClientNotReady(err) || (err && err.code === 'CREDENTIAL_INVALID');
+  // device through. A quota rejection (Phase 3.3) is the same kind of
+  // mistake to make: the verifier's establishing write is a net-new entity,
+  // so an account at the row cap gets a 413 here, and relabelling it
+  // VERIFIER_UNSUPPORTED tells the user to update a server that is working
+  // correctly. Pass it through so the cycle reports the truth.
+  const isPassThrough = (err) =>
+    isClientNotReady(err) || (err && (err.code === 'CREDENTIAL_INVALID' || err.code === 'QUOTA_EXCEEDED'));
 
   const verifierUnsupported = (cause) => {
     if (isPassThrough(cause)) throw cause;
@@ -652,11 +828,22 @@ 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));
+
       hasMore = !!more;
     }
 
     // Pull is the sole writer of the pull cursor. Advance it (monotonically)
-    // from the highest seq we actually listed this run.
+    // 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));
     return { maxSeq, appliedRemote, applied, skipped, skippedEntityIds };
   };
@@ -702,52 +889,135 @@ export const createDbSyncEngine = (config) => {
       return { applied: 0, skipped: 0, skippedEntityIds: [], halted: true };
     }
     if (syncing) return;
+
+    // Nothing at all can proceed while the key is unverified AND both windows
+    // are open: proving the key needs the network, and both directions are
+    // backed off. (Once verified in-session, ensureRootKey is a local check,
+    // so a single open window only skips its own half of the cycle.)
+    if (!verified && isOpen(pushBackoff) && isOpen(pullBackoff)) {
+      surfaceStandingWindow(pushBackoff);
+      onStatusChange?.('error');
+      return {
+        applied: 0, skipped: 0, skippedEntityIds: [],
+        pushSkipped: true, pullSkipped: true, quota: getQuotaState(),
+      };
+    }
+
     syncing = true;
     onStatusChange?.('uploading');
     onError?.(null, null, false);
     try {
       // Part A first: prove the key before we push anything. A globally wrong
       // key aborts here with KEY_MISMATCH (push gated, nothing uploaded) rather
-      // than quarantining thousands of rows one by one on the pull.
+      // than quarantining thousands of rows one by one on the pull. A failure
+      // here blocks BOTH directions, so it opens both windows (see the catch).
       await ensureRootKey();
 
-      await pushDirtyRows();
+      // PARTIAL FUNCTION (3.3, extended here to the pull). A failure in one
+      // direction must never cost the other: the push error is captured, the
+      // pull runs, and the pull's own error is captured too so the cursor
+      // 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.
+      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);
+        }
+      }
+
       onStatusChange?.('downloading');
-      const pull = await pullRemoteChanges();
-      await updateDeviceCursor();
+      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();
+      }
+
+      // A rejected credential can surface from the push or the pull once the
+      // key is verified in-session (ensureRootKey then makes no network call,
+      // so it is no longer the first thing to see a 401). Route it to the
+      // halt path from wherever it surfaced — the halt logic itself is
+      // untouched.
+      const credentialRejection =
+        (pushError && pushError.code === 'CREDENTIAL_INVALID' && pushError) ||
+        (pullError && pullError.code === 'CREDENTIAL_INVALID' && pullError) || null;
+      if (credentialRejection) {
+        const outcome = applyCredentialRejection(credentialRejection);
+        return { applied: pull.applied, skipped: pull.skipped, skippedEntityIds: pull.skippedEntityIds, ...outcome };
+      }
+
+      if (pull.skipped > 0) onRowsSkipped?.(pull.skipped, pull.skippedEntityIds);
+
+      // lastSynced means "this device is fully in step with the server", so a
+      // cycle with any failed or skipped half does not claim it.
+      if (pushError || pushSkipped || pullError || pullSkipped) {
+        // Report the fresh failure if there was one; otherwise this is a
+        // suppressed cycle, and only a quota window keeps speaking.
+        if (pushError || pullError) {
+          const err = pushError || pullError;
+          onError?.(err?.message || String(err), (err && err.code) || 'NETWORK_ERROR', false);
+        } else {
+          surfaceStandingWindow(pushSkipped ? pushBackoff : pullBackoff);
+        }
+        onStatusChange?.('error');
+        return {
+          applied: pull.applied,
+          skipped: pull.skipped,
+          skippedEntityIds: pull.skippedEntityIds,
+          pushFailed: !!pushError,
+          pushSkipped,
+          pushErrorCode: pushError ? ((pushError.code) || 'NETWORK_ERROR') : (pushSkipped ? pushBackoff.code : undefined),
+          pullFailed: !!pullError,
+          pullSkipped,
+          pullErrorCode: pullError ? ((pullError.code) || 'NETWORK_ERROR') : (pullSkipped ? pullBackoff.code : undefined),
+          quota: getQuotaState(),
+        };
+      }
 
       const now = new Date().toISOString();
       localStorage.setItem(KEY_LAST_SYNCED, now);
       onStatusChange?.('success');
 
-      if (pull.skipped > 0) onRowsSkipped?.(pull.skipped, pull.skippedEntityIds);
       return { applied: pull.applied, skipped: pull.skipped, skippedEntityIds: pull.skippedEntityIds };
     } catch (err) {
+      // Only ensureRootKey reaches here now (push and pull are captured
+      // above). It gates both directions, so its failure opens both windows.
       // eslint-disable-next-line no-console
       console.error(`[${appId}] db sync cycle error:`, err);
       const code = err && err.code ? err.code : 'NETWORK_ERROR';
       if (code === 'CREDENTIAL_INVALID') {
-        // The server rejected this engine's credential. Under NO circumstances
-        // does the engine re-enroll here: enrollment is non-idempotent, so an
-        // automatic retry would mint a server row per failure and would let a
-        // revoked device silently re-admit itself. Recovery is user-initiated
-        // only (recoverVaultSyncEngine).
-        if (isBearerSuperseded()) {
-          // This instance was replaced by recovery and the app kept a stale
-          // reference. Go inert in memory — surfaced once, then silent — and
-          // leave the shared halt key alone so the recovered engine keeps
-          // syncing.
-          supersededInert = true;
-          onError?.(err?.message || String(err), 'CREDENTIAL_INVALID', true);
-        } else {
-          // Persist the stop so no future cycle retries (a rejected
-          // credential never heals by retry) and surface it as a hard stop.
-          setCredentialHalt(err?.message || String(err));
-          onError?.(err?.message || String(err), 'CREDENTIAL_INVALID', true);
-        }
-      } else {
-        onError?.(err?.message || String(err), code, false);
+        const outcome = applyCredentialRejection(err);
+        return { applied: 0, skipped: 0, skippedEntityIds: [], ...outcome };
       }
+      const reason = recordFailure(pushBackoff, err, MAX_PUSH_BACKOFF_S);
+      if (reason) recordFailure(pullBackoff, err, MAX_PULL_BACKOFF_S);
+      onError?.(err?.message || String(err), code, false);
       onStatusChange?.('error');
       return { applied: 0, skipped: 0, skippedEntityIds: [] };
     } finally {
@@ -797,6 +1067,27 @@ export const createDbSyncEngine = (config) => {
     // True once this instance proved its bearer was superseded by recovery
     // and went inert (in-memory only; a fresh instance is unaffected).
     isSuperseded: () => supersededInert,
+    // Over-quota state (Phase 3.3): null when clear, else the parsed
+    // descriptor plus when the next probe is due. In-memory only, never a
+    // hard stop, and there is nothing to clear — it lifts by itself once the
+    // server accepts a write again. Now derived from the push backoff window.
+    getQuotaState,
+    isQuotaSuppressed,
+
+    // Backoff. The timestamps use the file tier's getter names and meaning
+    // (epoch ms before which that direction will not be attempted), so a
+    // scheduler can treat both tiers identically. Unlike the file tier the
+    // engine ALSO enforces them itself, so honouring them is optional.
+    getUploadBackoffUntil:   () => pushBackoff.until,
+    getDownloadBackoffUntil: () => pullBackoff.until,
+    // The full picture, because the timestamp alone cannot distinguish a
+    // one-hour auth backoff from a thirty-second transport one without
+    // inferring from its magnitude. `reason` is 'quota' | 'auth' |
+    // 'transport'; `code` is the typed error that opened the window.
+    getBackoffState: () => ({
+      push: { until: pushBackoff.until, reason: pushBackoff.reason, code: pushBackoff.code, strikes: pushBackoff.strikes, since: pushBackoff.since },
+      pull: { until: pullBackoff.until, reason: pullBackoff.reason, code: pullBackoff.code, strikes: pullBackoff.strikes, since: pullBackoff.since },
+    }),
     deviceId: resolvedDeviceId,
 
     // Sub-modules

package/src/vaultClient.js

@@ -39,6 +39,45 @@ class VaultError extends Error {
   }
 }
 
+// Quota rejection parsing (GLANCEvault Phase 3.2 / client Phase 3.3).
+//
+// The server rejects an over-quota write with 413 (storage-shaped: `storage`,
+// `rows`) or 429 (volume/concurrency-shaped: `intents`, `concurrent-uploads`)
+// and a uniform body:
+//   { error: "quota exceeded", quota, limit, used, requested }
+// The three numbers are bytes for `storage` and counts otherwise, and are
+// meant to render "X of Y used" directly.
+//
+// DEFENSIVE BY CONSTRUCTION — this shape is a contract across two repos, so
+// a body must earn the typed classification rather than be assumed into it.
+// ALL of: the exact `error` wording, a non-empty string `quota`, and three
+// finite numbers. Anything short of that (a missing field, a non-JSON body, a
+// 413 with no quota fields at all, an older server that never sends this
+// shape) degrades to the generic VAULT_ERROR the client already handled —
+// never a throw, never a mis-classification.
+//
+// The `quota` DIMENSION is deliberately NOT allowlisted. A newer server may
+// add dimensions, and an unknown one is still a quota condition with the same
+// remedy (wait; it clears when the operator acts, with no client action), so
+// passing the string through verbatim is more truthful than pretending the
+// rejection was a generic failure. Consumers that do not recognise a
+// dimension render it generically. See the PR for this decision.
+//
+// The legacy SSE per-account cap (429 {"error":"too many connections for
+// account"}) predates this shape and is NOT a quota rejection: its wording
+// fails the `error` check on the first line, so it degrades generically with
+// no special-casing. Nothing in this package speaks SSE regardless.
+const parseQuotaBody = (status, body, bodyError) => {
+  if (status !== 413 && status !== 429) return null;
+  if (bodyError !== 'quota exceeded') return null;
+  if (!body || typeof body.quota !== 'string' || body.quota === '') return null;
+  const { limit, used, requested } = body;
+  if (typeof limit !== 'number' || !Number.isFinite(limit)) return null;
+  if (typeof used !== 'number' || !Number.isFinite(used)) return null;
+  if (typeof requested !== 'number' || !Number.isFinite(requested)) return null;
+  return { quota: body.quota, limit, used, requested };
+};
+
 // Shared by createVaultClient and the standalone pre-credential helpers below.
 const resolveFetch = (fetchImpl, context) => {
   const doFetch = fetchImpl || globalThis.fetch;
@@ -200,9 +239,10 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
   // non-JSON, or unrecognized body degrades to the generic VAULT_ERROR, so
   // the client's correctness never depends on server wording.
   const errorFromResponse = async (res, context) => {
+    let body = null;
     let bodyError = null;
     try {
-      const body = await res.json();
+      body = await res.json();
       if (body && typeof body.error === 'string') bodyError = body.error;
     } catch {
       // Empty or non-JSON error body: keep the generic classification.
@@ -212,6 +252,16 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
       err.code = 'CREDENTIAL_INVALID';
       return err;
     }
+    const quota = parseQuotaBody(res.status, body, bodyError);
+    if (quota) {
+      const err = new VaultError(
+        `${context} failed: ${res.status} — ${quota.quota} quota exceeded (${quota.used} of ${quota.limit}, requested ${quota.requested})`,
+        res.status
+      );
+      err.code = 'QUOTA_EXCEEDED';
+      err.quota = quota;
+      return err;
+    }
     return new VaultError(`${context} failed: ${res.status}`, res.status);
   };
 

package/types/index.d.ts

@@ -32,7 +32,15 @@ export type SyncErrorCode =
   // credential (401 "invalid credential"). Surfaced with isHardStop === true;
   // the engine persists a halt and stops retrying. Recovery (re-enrollment)
   // is Phase 2.2 — nothing in this version clears the halt.
-  | 'CREDENTIAL_INVALID';
+  | 'CREDENTIAL_INVALID'
+  // DB transport: the server rejected a write because the account is over a
+  // configured quota (413 storage-shaped / 429 volume-shaped, Phase 3.2).
+  // ALWAYS isHardStop === false — a quota condition clears when the operator
+  // raises the limit or reclaim runs, with NO client action, so the engine
+  // never halts on it. The parsed descriptor rides on the engine's
+  // getQuotaState(); the engine suppresses further writes for a bounded,
+  // self-resuming window while the pull keeps running.
+  | 'QUOTA_EXCEEDED';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -519,6 +527,74 @@ export interface DbSyncResult {
   applied: number;
   skipped: number;
   skippedEntityIds: string[];
+  /** True when the push threw but the pull still ran (Phase 3.3 partial function). */
+  pushFailed?: boolean;
+  /** True when the push was skipped because its backoff window is open. */
+  pushSkipped?: boolean;
+  /** The push error's code when pushFailed/pushSkipped — the pull's own result is still reported above. */
+  pushErrorCode?: SyncErrorCode | string;
+  /** True when the pull threw but the cursor report still ran. */
+  pullFailed?: boolean;
+  /** True when the pull was skipped because its backoff window is open. */
+  pullSkipped?: boolean;
+  /** The pull error's code when pullFailed/pullSkipped. */
+  pullErrorCode?: SyncErrorCode | string;
+  /** The standing over-quota descriptor, when one applies. */
+  quota?: QuotaState | null;
+  /** True when the cycle no-opped because the credential halt is set. */
+  halted?: boolean;
+  /** True when the cycle no-opped because this instance's credential was superseded. */
+  superseded?: boolean;
+}
+
+/**
+ * Over-quota state (Phase 3.3). IN MEMORY ONLY — this describes server-side
+ * state that changes without the client (an operator raises a limit, reclaim
+ * runs, intents expire), so it is never persisted and there is nothing to
+ * clear: it lifts by itself when a write succeeds again.
+ *
+ * `quota` is the server's dimension string, passed through verbatim — the
+ * known values are 'storage' | 'rows' | 'intents' | 'concurrent-uploads', but
+ * a newer server may add dimensions, so treat an unrecognised one generically
+ * rather than assuming it cannot happen. The numbers are bytes for 'storage'
+ * and counts otherwise, and render "X of Y used" directly; they are null only
+ * in the defensive case where a rejection was typed without a full body.
+ */
+/**
+ * One backoff window. The DB engine keeps two (push and pull) and enforces
+ * them itself; both are IN MEMORY ONLY, like the file tier's, so a restart
+ * clears them — a relaunch is a user saying "try now", and a persisting
+ * failure re-opens the window immediately.
+ *
+ * A window only ever DELAYS: the next cycle after `until` probes again, with
+ * no user action and no restart. Failures that must not be delayed at all
+ * (PASSPHRASE_REQUIRED / ACCOUNT_ID_REQUIRED, which clear the moment the app
+ * supplies the value) and failures owned by another state (CREDENTIAL_INVALID,
+ * which halts) never open one.
+ */
+export interface BackoffWindow {
+  /** Epoch ms; the direction is skipped while this is in the future. 0 when clear. */
+  until: number;
+  /** Consecutive failures driving the escalation (30s doubling; 15 min push cap, 5 min pull cap). */
+  strikes: number;
+  /** 'quota' (keeps surfacing its descriptor), 'auth' (flat hour on a 401), 'transport' (quiet after one signal). */
+  reason: 'quota' | 'auth' | 'transport' | null;
+  /** The typed error code that opened the window. */
+  code: SyncErrorCode | string | null;
+  /** ISO timestamp of the most recent failure. */
+  since: string | null;
+}
+
+export interface QuotaState {
+  quota: string;
+  limit: number | null;
+  used: number | null;
+  requested: number | null;
+  message: string;
+  /** ISO timestamp of the most recent rejection. */
+  since: string;
+  /** ISO timestamp after which the engine probes again, on its own. */
+  retryAt: string;
 }
 
 /** A row quarantined after failing to decrypt under the (verified) account key. */
@@ -564,6 +640,25 @@ export interface DbSyncEngine {
   getCredentialHalt(): { message: string; at: string } | null;
   /** True once this instance proved its bearer was superseded by recovery and went inert (in-memory only). */
   isSuperseded(): boolean;
+  /** The standing over-quota descriptor, or null. In-memory only; never a hard stop; nothing to clear. */
+  getQuotaState(): QuotaState | null;
+  /** True while the bounded over-quota window is open (writes skipped, pulls continue). */
+  isQuotaSuppressed(): boolean;
+
+  /**
+   * Epoch ms before which the push/pull will not be attempted, or 0. Same
+   * getter names and meaning as the file engine's, so one scheduler can treat
+   * both tiers identically — but unlike the file tier, the DB engine also
+   * ENFORCES these itself, so honouring them is an optimisation, not a duty.
+   */
+  getUploadBackoffUntil(): number;
+  getDownloadBackoffUntil(): number;
+  /**
+   * The full backoff picture. `reason` distinguishes a one-hour auth window
+   * from a thirty-second transport one without inferring from the timestamp's
+   * magnitude, which is what an app needs to tell a user why and for how long.
+   */
+  getBackoffState(): { push: BackoffWindow; pull: BackoffWindow };
   /** The resolved stable device identity this engine runs as. */
   deviceId: string;