@glance-apps/sync 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -7,6 +7,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-08-30
+
+**Should you take this release?** Yes if you use the GLANCEvault transport, and
+immediately if anything in your bundle writes to it on a timer. This release is
+the client-side answer to a 2026-08-30 incident in which an intent-cleanup loop
+in the dayGLANCE Obsidian plugin deleted rows that were already tombstones. The
+server re-tombstoned on every call — fresh seq, fresh SSE nudge — which put the
+row back above the caller's cursor and fed the loop its own output. It ran for
+hours and saturated the server's per-IP rate budget, and it was **invisible**:
+every delete was fire-and-forget behind a `.catch(() => {})`, so nothing failed
+loudly enough to notice. Two patches landed elsewhere (the plugin no longer
+deletes tombstones; the vault's `softDeleteRow` is now idempotent). This release
+adds the protection and the visibility **by construction**, so no caller has to
+remember them and no loop can be silent. No server changes: the wire contract is
+untouched.
+
+### Added
+
+- **The intents transport.** `intentsBatch(accountId, events)` and
+  `intentsList(accountId, { since, limit })` wrap the server's existing
+  `/intents/*` endpoints, so apps can drop their hand-rolled raw-fetch
+  transports and inherit this client's auth, error classification, brake and
+  meter. `intentsBatch` is insert-only server-side — a re-sent `eventId` is a
+  no-op — so retrying an ambiguous failure is safe by construction.
+  - **Pure transport**: the `envelope` is opaque here and is never decoded or
+    inspected. The codec, and the per-envelope key derivation it needs, stays
+    in `@glance-apps/intents`; this package carries the transport without
+    carrying the crypto.
+- **A device-wide request brake.** Any real 429 now pauses *every* vault
+  request in the bundle realm: 30s, doubling per burst to a 10-minute ceiling,
+  one arming per burst (a concurrent fan-out that all meets the limiter costs
+  one escalation step, not ten). While paused, calls fail fast — **before
+  touching the network** — with a `VaultError` carrying `status: 429`,
+  `code: 'RATE_LIMITED'` and `retryInMs`.
+  - It is at **module scope, not per client instance**, deliberately: the thing
+    it protects is shared by every client in the process (the server's per-IP
+    budget), so the state that models it belongs to the realm. A separately
+    bundled copy — the Obsidian plugin's, say — is its own realm, which is
+    correct: separate process, separate traffic.
+  - **Decay, never amnesty.** A 2xx releases the pause but only *halves* the
+    escalation memory (below the 30s base it drains to zero). This is the fix
+    for the earlier app-side brake, which reset escalation to zero on *any*
+    success: on a saturated shared budget an occasional cheap request slips
+    into a fresh limiter window and returns 200, and each lucky 200 wiped the
+    whole 30s→480s escalation and re-licensed full cadence. Halving keeps the
+    storm's level in memory — the next 429 re-arms at 2× what is left — while a
+    genuine recovery still drains to nothing in a few quiet successes.
+  - Reads: `isVaultRateLimited()` and `vaultBrakeStatus()`, for callers that
+    prefer to sit a whole cycle out pre-flight. Escape hatch:
+    `createVaultClient({ brake: false })` opts a client out of both the gate
+    and the arming.
+- **A budget meter.** Requests are counted per rolling minute and attributed by
+  method name. Crossing a soft threshold (default 300/min — half the server's
+  default per-IP budget, configurable) logs **one** line per window naming the
+  top contributors: `[vault] budget: 412 requests in the last minute (soft
+  limit 300) — top: intentsList 210, batch 130, deleteRow 72`. Visibility only;
+  it never throttles. Its whole argument is that it needs no theory about *why*
+  a loop is running, so the next storm is an attributed event on day one rather
+  than an afternoon of archaeology.
+- **A write-loop detector — the success-side signal.** Failure visibility
+  already existed; what was missing on the day was the signal for everything
+  "succeeding" pathologically. The client now keeps a bounded per-`entityId`
+  history across `batch` upserts and `deleteRow`, and warns loudly (once per id
+  per window) when four **redundant** writes to one id land inside ten minutes.
+  Diagnostic only — never a brake.
+  - A write is redundant when it cannot have changed the row's state from what
+    the previous write to that id left it. Three shapes qualify: a **polarity
+    flip** (the delete-and-resupply loop), a **repeat delete** (re-deleting a
+    row that is already a tombstone — the incident's own shape: same polarity
+    every time, no content at all), and an **identical-content rewrite**.
+  - **Fails open by construction**: the rule needs repeated events on the
+    *same* id, so a first sync, a large import, or a bulk cleanup deleting many
+    different ids — many ids, one event each — can never trigger it, however
+    large. A bounded retry of one failed delete does not reach the threshold
+    either.
+  - Both thresholds are tunable via `configureVaultDiagnostics`. Four redundant
+    writes means five events (upsert/delete/upsert/delete/upsert, or five
+    deletes of one tombstone), which no human edit pattern produces and every
+    delete/resupply or re-tombstone loop produces within seconds; ten minutes
+    is long enough to catch a loop running on a 60s sync cycle and short enough
+    that a week of ordinary edits never accumulates into it.
+- `getVaultStats()` returns all three in one read: brake status, the last
+  rolling minute of requests by method, and the current write-loop suspects.
+  `configureVaultDiagnostics(options)` tunes the visibility-only thresholds and
+  the log sink; `resetVaultDiagnostics()` clears everything (for tests).
+
+### Changed
+
+- Every `createVaultClient` method now passes through the brake and the meter.
+  The only behaviour change a healthy caller can observe is the new
+  `RATE_LIMITED` rejection while a window is open — and only after the server
+  has already answered a real 429.
+- A **429 arms the brake only when it is a rate-limiter hit**, never when it is
+  an over-quota rejection. The server uses 429 for both and they call for
+  opposite handling: a limiter hit means "stop asking for a while" (exactly
+  what the brake does), while a quota rejection means the account is full,
+  clears only when an operator acts, and already has its own self-resuming
+  window in the DB engine. Gating on it would hide `QUOTA_EXCEEDED` and its
+  descriptor behind `RATE_LIMITED` and leave apps unable to render "X of Y
+  used". The quota shape is recognised as narrowly as before, so anything that
+  is not unmistakably a quota body is treated as a limiter hit.
+
+### Notes
+
+- **Not gated**: `fetchVaultHealth` and `enrollVaultDevice`. Both are
+  pre-credential, user-initiated, one-shot calls — `/healthz` is the
+  unauthenticated probe you reach for *while* diagnosing a stuck client, and
+  refusing it during a braked window would take away the diagnostic just when
+  it is wanted.
+- **For lastGLANCE / lifeGLANCE**: safe to take at leisure (semver-minor).
+  During a braked window, client calls fail fast with `VaultError { status:
+  429, code: 'RATE_LIMITED' }` instead of hitting the wire; any ladder that
+  already treats a real 429 as transient — they all do — handles it unchanged.
+  The meter and the write-loop warnings come along for free.
+- An AES-GCM envelope carries a fresh random IV, so identical plaintext does
+  not produce an identical envelope: for encrypted payloads it is the polarity
+  flip that fires the detector, and the identical-content rule covers plaintext
+  and deterministic payloads.
+
 ## [1.10.0] - 2026-08-01
 
 **Should you take this release?** Yes, for any deployment using the database

package/README.md

@@ -158,6 +158,71 @@ Pass `encryptionEnabled: true` in the sync config object stored via `engine.setC
 | `createProviders(config)` | Creates cloud sync provider objects (`nextcloud`, `koofr`, `webdav`). |
 | `normalizeEtag(raw)` | Normalizes a raw ETag header value for If-Match use: strips a weak-validator prefix (`W/"abc"` → `"abc"`) and the content-coding suffixes some servers append inside the quotes (`"abc-gzip"` / `"abc-br"` → `"abc"`). Quotes are preserved; `null`/`undefined` pass through unchanged. |
 
+### GLANCEvault client
+
+| Export | Description |
+|--------|-------------|
+| `createVaultClient(config)` | HTTP client for a GLANCEvault server. `config` is `{ vaultUrl, vaultToken, fetchImpl?, brake? }`. Every method carries the Bearer token, classifies errors uniformly (`CREDENTIAL_INVALID`, `QUOTA_EXCEEDED`, `RATE_LIMITED`, else `VaultError` with `.status`), and passes through the module-scope brake and budget meter. |
+| `fetchVaultHealth(config)` | Unauthenticated `GET /healthz`. Returns `{ status, version, schemaVersion, authMode }`, with `authMode` normalized to `'shared'` on servers that predate the field. |
+| `enrollVaultDevice(config)` | Exchanges the admin-configured bootstrap secret for this device's own credential (`POST /enroll`). The credential is returned once and never again. |
+
+**`VaultClient` methods:**
+
+| Method | Description |
+|--------|-------------|
+| `batch(app, { accountId, rows })` | Upserts rows (`{ entityId, envelope, createdAt }`). Returns `{ written, maxSeq }`. |
+| `list(app, { accountId, since })` | One page of rows with `seq > since`. Returns `{ rows, hasMore }`. |
+| `getRow(app, entityId, accountId)` | Fetches one row; `null` on 404. |
+| `deleteRow(app, entityId, accountId, opts?)` | Soft-deletes a row. `opts.deletedAt` (epoch ms) stamps the tombstone for delete-vs-edit LWW. |
+| `device(app, { accountId, deviceId, lastSeenSeq })` | Updates this device's cursor. |
+| `getSalt(accountId)` / `putSalt(accountId, salt)` | Reads/registers the account root-key salt as a `Uint8Array` (first-write-wins). |
+| `intentsBatch(accountId, events)` | Appends intent events (`{ eventId, envelope, expiresAt }`) via `POST /intents/batch`. **Insert-only** — a re-sent `eventId` is a server no-op, so retrying an ambiguous failure is safe. Returns `{ written, maxSeq }`. |
+| `intentsList(accountId, { since, limit })` | One ascending page of non-expired intent events with `seq > since` via `GET /intents/list`. Returns `{ rows, hasMore }`; the server pages at 500. |
+
+The intents surface is **pure transport**: the `envelope` is opaque here and is
+never decoded or inspected. The codec (and the per-envelope key derivation it
+needs) stays in `@glance-apps/intents` — see `deriveKeyForSalt` above.
+
+### Request diagnostics
+
+One brake, one budget meter and one write-loop history per **bundle realm** —
+not per client instance. They model a resource every client in the process
+shares: the server's per-IP request budget. A separately bundled copy of this
+package (an Obsidian plugin, say) is its own realm, which is correct — it is a
+separate process with its own traffic.
+
+| Export | Description |
+|--------|-------------|
+| `isVaultRateLimited()` | `true` while the brake is engaged. For callers that would rather sit a whole cycle out pre-flight than fire a call and catch the rejection. |
+| `vaultBrakeStatus()` | `{ braked, until, memoryMs, retryInMs }`. |
+| `getVaultStats()` | The brake status, the last rolling minute of requests attributed by method, and the entityIds whose write history looks loop-shaped. |
+| `configureVaultDiagnostics(options?)` | Tunes the visibility-only thresholds (`softLimitPerMinute`, `loopTransitions`, `loopWindowMs`) and the log sink. The brake's curve is deliberately not configurable. |
+| `resetVaultDiagnostics()` | Clears all three and restores the defaults. For tests. |
+
+**The brake.** Any real 429 pauses *every* vault request in the realm: 30s,
+doubling per burst to a 10-minute ceiling, with one arming per burst. While
+paused, calls fail fast — before touching the network — with a `VaultError`
+carrying `status: 429`, `code: 'RATE_LIMITED'` and `retryInMs`, so retry
+ladders that already treat a real 429 as transient need no new code. A 2xx
+releases the pause but only **halves** the escalation memory, so the next 429
+re-arms at the storm's level; a genuine recovery drains to zero in a few quiet
+successes. An over-quota 429 (`QUOTA_EXCEEDED`) is not a limiter hit and does
+not arm it. `createVaultClient({ brake: false })` opts a client out of both the
+gate and the arming — an escape hatch for tests.
+
+**The budget meter and the write-loop detector** are visibility only; neither
+ever throttles. The meter logs one attributable line per minute when a realm
+crosses a soft threshold (default 300/min, half the server's default per-IP
+budget). The detector keeps a bounded per-`entityId` write history across
+`batch` upserts and `deleteRow` and warns once per id per window when four
+**redundant** writes to one id land inside ten minutes. A write is redundant
+when it cannot have changed the row's state from what the previous write to
+that id left it: a polarity flip, a **repeat delete** (re-deleting a row that
+is already a tombstone — the shape of the incident this was built for), or a
+rewrite with identical content. It fails open by construction: the rule needs
+repeated events on the *same* id, so a first sync, a large import, or a bulk
+cleanup deleting many different ids can never trigger it.
+
 ### Auto-backup
 
 | Export | Description |

package/package.json

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

package/src/index.js

@@ -47,6 +47,14 @@ export {
   // discovery and the bootstrap-secret -> per-device-credential exchange.
   fetchVaultHealth,
   enrollVaultDevice,
+  // Module-scope request diagnostics (1.11.0). The brake gates every client
+  // call after a real 429; the budget meter and the write-loop detector are
+  // visibility only. All three are per bundle realm, not per client.
+  isVaultRateLimited,
+  vaultBrakeStatus,
+  getVaultStats,
+  configureVaultDiagnostics,
+  resetVaultDiagnostics,
 } from './vaultClient.js';
 // The packaged connect flow: discover -> branch -> enroll if needed ->
 // persist credential -> build engine. Apps hand it a secret or token and get

package/src/vaultClient.js

@@ -14,6 +14,13 @@
 //   POST   /sync/:app/device                     update device cursor, { updated }
 //   GET    /salt/:accountId                      fetch the account root-key salt
 //   PUT    /salt/:accountId                      register a salt (first-write-wins)
+//   POST   /intents/batch                        append intent events, { written, maxSeq }
+//   GET    /intents/list?accountId=&since=&limit= intent events after a cursor, { rows, hasMore }
+//
+// Every client method is gated by a module-scope brake and counted by a
+// module-scope budget meter, and the two write methods keep a bounded
+// per-entity history that warns on loop-shaped traffic. See the diagnostics
+// block below for why those live at module scope and what they cost.
 //
 // Auth models (vault Phase 1.4b — the client half of per-account credentials):
 // a vault runs in one of two modes, discoverable unauthenticated via
@@ -39,6 +46,425 @@ class VaultError extends Error {
   }
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Module-scope diagnostics (1.11.0): the brake, the budget meter, the
+// write-loop detector.
+//
+// WHY MODULE SCOPE, NOT PER CLIENT INSTANCE. All three protect (or observe) a
+// resource that is shared by every client in the process: the server's
+// per-IP request budget. Two clients built by the same bundle are two views
+// of one traffic stream, so the state that models that stream belongs to the
+// module — one brake, one meter, one write history per *bundle realm*. The
+// app is one realm; a plugin that bundles its own copy of this package is a
+// separate realm, which is correct: it is a separate process with its own
+// traffic and its own IP budget slice.
+//
+// WHY BY CONSTRUCTION. The incident these exist for (2026-08-30) was a
+// fire-and-forget delete loop that re-tombstoned rows for hours and saturated
+// the server's per-IP budget. Every request "succeeded" or failed into a
+// swallowed `.catch(() => {})`. A protection a caller has to remember to
+// apply is a protection that is missing on the day it matters, so the brake
+// gates every network method of every client, and the meter and the write
+// history observe them all whether or not anyone reads the stats.
+// ═══════════════════════════════════════════════════════════════════════════
+
+// --- The brake ---
+// 30s doubling to a 10-minute ceiling. The ceiling is a deliberate stopping
+// point rather than unbounded growth: a client that has waited ten minutes
+// and is still being limited is in a condition an operator has to fix, and
+// waiting twenty would only make the recovery slower once they do.
+const BRAKE_BASE_MS = 30_000;
+const BRAKE_CEILING_MS = 600_000;
+
+// --- The budget meter ---
+// 300/min is half of GLANCEvault's default 600/min per-IP budget: crossing
+// half the budget in a minute is not yet a failure, which is exactly when a
+// warning is still useful. The window is rolling; samples older than a minute
+// are pruned on every record, and the buffer is hard-capped so a runaway loop
+// can never grow it without bound (a dropped sample only under-counts a
+// number that is already far past the threshold).
+const BUDGET_WINDOW_MS = 60_000;
+const DEFAULT_SOFT_LIMIT = 300;
+const BUDGET_SAMPLE_CAP = 20_000;
+const BUDGET_TOP_N = 3;
+
+// --- The write-loop detector ---
+// K=4 redundant writes inside M=10 minutes. A write is redundant when it
+// cannot have changed the row's state from what the previous write to the
+// same entityId left it: a polarity flip, a repeat delete, or an
+// identical-content rewrite (see isRedundantWrite for why each counts). K=4
+// means five events — upsert/delete/upsert/delete/upsert, or five deletes of
+// one tombstone — which no human edit pattern produces and every
+// delete/resupply or re-tombstone loop produces within seconds.
+// M=10min is long enough to catch a slow loop running on a 60s sync cycle
+// and short enough that a week of ordinary edits never accumulates into it.
+// Both are configurable via configureVaultDiagnostics for callers whose
+// cadence makes different numbers right.
+//
+// FAILS OPEN BY CONSTRUCTION: the rule is per-entityId and needs consecutive
+// events on the SAME id, so a first sync or a large import — many DIFFERENT
+// ids, one event each — can never trigger it however big it is.
+const DEFAULT_LOOP_TRANSITIONS = 4;
+const DEFAULT_LOOP_WINDOW_MS = 10 * 60_000;
+const WRITE_HISTORY_PER_ID = 8;   // >= K+1 events, so the ring always holds a full detection
+const WRITE_HISTORY_IDS = 500;    // LRU-capped: the map is bounded regardless of traffic
+
+let diagnosticsConfig = {
+  softLimitPerMinute: DEFAULT_SOFT_LIMIT,
+  loopTransitions: DEFAULT_LOOP_TRANSITIONS,
+  loopWindowMs: DEFAULT_LOOP_WINDOW_MS,
+  logger: null,
+};
+
+const diagLog = (level, message) => {
+  const sink = diagnosticsConfig.logger || console;
+  const fn = typeof sink[level] === 'function' ? sink[level] : sink.log;
+  if (typeof fn === 'function') fn.call(sink, message);
+};
+
+const secs = (ms) => Math.round(ms / 1000);
+
+// ---------------------------------------------------------------------------
+// The brake
+// ---------------------------------------------------------------------------
+
+const brakeState = { until: 0, memoryMs: 0 };
+
+/**
+ * The gate. Returns a typed error when the brake is engaged, or null.
+ *
+ * The error is deliberately shaped like a REAL 429 (`status: 429`) so every
+ * retry ladder already sitting on top of this client — the DB engine's
+ * backoff, an app's bounded retry — treats it as the transient it is with no
+ * new code. `code: 'RATE_LIMITED'` and `retryInMs` are additive: a caller
+ * that wants to sit the whole cycle out can branch on them.
+ */
+const brakeGate = () => {
+  const now = Date.now();
+  if (brakeState.until <= now) return null;
+  const retryInMs = brakeState.until - now;
+  const err = new VaultError(
+    `vault requests are paused: rate-limited by the server, retry in ~${Math.ceil(retryInMs / 1000)}s`,
+    429
+  );
+  err.code = 'RATE_LIMITED';
+  err.retryInMs = retryInMs;
+  return err;
+};
+
+/**
+ * Arms the brake on a real 429. ONE ARMING PER BURST: a 429 that arrives
+ * while the brake is already engaged never compounds the delay, so a
+ * concurrent fan-out of ten requests that all meet the limiter costs one
+ * escalation step, not ten.
+ */
+const brakeArm = (label) => {
+  const now = Date.now();
+  if (brakeState.until > now) return;
+  brakeState.memoryMs = brakeState.memoryMs === 0
+    ? BRAKE_BASE_MS
+    : Math.min(brakeState.memoryMs * 2, BRAKE_CEILING_MS);
+  brakeState.until = now + brakeState.memoryMs;
+  // The once-per-incident report, and the only loud line the brake prints.
+  // It names the method that met the limiter because that is the single most
+  // useful fact when the storm is someone else's loop.
+  diagLog('warn', `[vault] BRAKE: rate-limited (429) on ${label} — vault requests paused for ~${secs(brakeState.memoryMs)}s`);
+};
+
+/**
+ * DECAY, NEVER AMNESTY. A success clears the gate but only HALVES the
+ * escalation memory (below the 30s base it drains to zero).
+ *
+ * This is the lesson from the first brake built for this ecosystem, which
+ * reset escalation to zero on ANY success. On a saturated SHARED budget the
+ * occasional cheap request slips into a fresh limiter window and returns 200
+ * — and each lucky 200 wiped the entire 30s->480s escalation and re-licensed
+ * full cadence. It backed off, escalated, forgot, and started over, forever.
+ *
+ * Halving keeps the storm's level in memory: the next 429 re-arms at 2x what
+ * is left (so a lucky success cannot buy back full cadence), while a genuine
+ * recovery drains to zero in a few quiet successes and costs nothing.
+ */
+const brakeNoteSuccess = () => {
+  const wasBraked = brakeState.until > Date.now();
+  brakeState.until = 0;
+  if (brakeState.memoryMs === 0) return;
+  const before = brakeState.memoryMs;
+  const halved = Math.floor(before / 2);
+  brakeState.memoryMs = halved < BRAKE_BASE_MS ? 0 : halved;
+  diagLog(
+    'info',
+    `[vault] brake ${wasBraked ? 'released' : 'decay'}: escalation memory ${secs(before)}s -> ${secs(brakeState.memoryMs)}s`
+  );
+};
+
+/**
+ * The brake's state, for callers that would rather sit a whole cycle out
+ * pre-flight than fire a call and catch RATE_LIMITED.
+ *
+ * @returns {{ braked: boolean, until: number|null, memoryMs: number, retryInMs: number }}
+ */
+export function vaultBrakeStatus() {
+  const now = Date.now();
+  const braked = brakeState.until > now;
+  return {
+    braked,
+    until: brakeState.until || null,
+    memoryMs: brakeState.memoryMs,
+    retryInMs: braked ? brakeState.until - now : 0,
+  };
+}
+
+/** Convenience read: is the shared brake engaged right now? */
+export function isVaultRateLimited() {
+  return brakeState.until > Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// The budget meter
+// ---------------------------------------------------------------------------
+//
+// VISIBILITY ONLY — the meter never throttles anything. Its argument is that
+// it needs no theory about WHY a loop is running: it counts requests and
+// names who made them, so the next storm is an attributed event on day one
+// instead of an afternoon of archaeology.
+
+const meterState = { samples: [], lastReportAt: 0, dropped: 0 };
+
+const meterPrune = (now) => {
+  const cutoff = now - BUDGET_WINDOW_MS;
+  const s = meterState.samples;
+  let i = 0;
+  while (i < s.length && s[i].at <= cutoff) i += 1;
+  if (i > 0) s.splice(0, i);
+};
+
+const meterTally = () => {
+  const counts = new Map();
+  for (const sample of meterState.samples) {
+    counts.set(sample.label, (counts.get(sample.label) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+};
+
+const meterRecord = (label) => {
+  const now = Date.now();
+  meterPrune(now);
+  if (meterState.samples.length >= BUDGET_SAMPLE_CAP) {
+    // Hard cap: a loop cannot grow the buffer without bound. Dropping the
+    // oldest samples only under-counts a number already far past the limit.
+    const excess = meterState.samples.length - BUDGET_SAMPLE_CAP + 1;
+    meterState.samples.splice(0, excess);
+    meterState.dropped += excess;
+  }
+  meterState.samples.push({ at: now, label });
+
+  const total = meterState.samples.length;
+  if (total <= diagnosticsConfig.softLimitPerMinute) return;
+  // ONE line per window: after reporting, stay quiet for a full minute. A
+  // storm that lasts an hour prints sixty attributable lines, not a million.
+  if (meterState.lastReportAt !== 0 && now - meterState.lastReportAt < BUDGET_WINDOW_MS) return;
+  meterState.lastReportAt = now;
+  const top = meterTally().slice(0, BUDGET_TOP_N).map(([name, n]) => `${name} ${n}`).join(', ');
+  diagLog('warn', `[vault] budget: ${total} requests in the last minute (soft limit ${diagnosticsConfig.softLimitPerMinute}) — top: ${top}`);
+};
+
+// ---------------------------------------------------------------------------
+// The write-loop detector (success-side visibility)
+// ---------------------------------------------------------------------------
+//
+// Failure visibility exists. What was missing on the day of the incident was
+// the signal for everything "succeeding" pathologically: every request
+// returned 200 and every caller swallowed its promise, so a delete/resupply
+// loop was indistinguishable from healthy traffic until the server's budget
+// ran out. This ring is the client-level answer — diagnostic only, never a
+// brake, and it fails open.
+
+const writeHistory = new Map(); // entityId -> { events: [...], warnedAt }
+
+// FNV-1a over a bounded prefix. Cheap enough to run on every row of every
+// batch, and only ever used to spot an IDENTICAL rewrite (see
+// isRedundantWrite). Never decoded, only hashed.
+const hashContent = (value) => {
+  if (typeof value !== 'string' || value === '') return null;
+  const span = value.length > 4096 ? value.slice(0, 4096) : value;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < span.length; i += 1) {
+    h ^= span.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return `${value.length}:${(h >>> 0).toString(36)}`;
+};
+
+/**
+ * Is this consecutive pair of writes to one entityId REDUNDANT — a write that
+ * cannot have changed the row's state from what the previous write left it?
+ *
+ * Three shapes qualify, and the third is the founding incident's:
+ *
+ *  1. A POLARITY FLIP (upsert -> delete or delete -> upsert). The
+ *     write-flip / delete-and-resupply loop.
+ *  2. An IDENTICAL-CONTENT REWRITE (upsert -> upsert, same content). Note
+ *     that an AES-GCM envelope carries a fresh random IV, so identical
+ *     plaintext does NOT produce an identical envelope: this rule fires for
+ *     plaintext and deterministic payloads, while shape 1 covers encrypted
+ *     ones.
+ *  3. A REPEAT DELETE (delete -> delete). Re-deleting a row that is already
+ *     a tombstone is redundant by definition — and it is exactly the loop
+ *     this detector was built for: the Obsidian plugin's cleanup called
+ *     deleteRow on rows that were already tombstones, the server re-tombstoned
+ *     each time with a fresh seq, and that pushed the row back above the
+ *     caller's cursor to be deleted again. Same polarity every time, no
+ *     content at all, so neither of the first two rules sees it. A detector
+ *     that misses its own origin story is not a detector.
+ *
+ * A bounded retry of one failed delete does not reach K on its own; a ladder
+ * that retries the same delete K times inside the window is itself worth
+ * knowing about, and is the same shape as the incident.
+ */
+const isRedundantWrite = (prev, cur) => {
+  if (prev.polarity !== cur.polarity) return true;
+  if (prev.polarity === 'delete') return true;
+  return prev.contentHash != null && prev.contentHash === cur.contentHash;
+};
+
+const countTransitions = (events, now) => {
+  const cutoff = now - diagnosticsConfig.loopWindowMs;
+  const recent = events.filter((e) => e.at >= cutoff);
+  let transitions = 0;
+  for (let i = 1; i < recent.length; i += 1) {
+    if (isRedundantWrite(recent[i - 1], recent[i])) transitions += 1;
+  }
+  return transitions;
+};
+
+const renderHistory = (events) => events
+  .map((e) => (e.polarity === 'upsert' ? 'upsert' : 'delete'))
+  .join(' -> ');
+
+/**
+ * Records one write against an entityId and warns — loudly, at most once per
+ * id per window — when its recent history looks like a loop.
+ *
+ * Recorded at INTENT time (before the request), so a loop that is being
+ * gated by the brake or rejected by the server is still visible as a loop.
+ */
+const noteWrite = (entityId, polarity, envelope) => {
+  if (typeof entityId !== 'string' || entityId === '') return;
+  const now = Date.now();
+  let rec = writeHistory.get(entityId);
+  if (rec) writeHistory.delete(entityId); // re-insert keeps Map iteration order LRU
+  else rec = { events: [], warnedAt: 0 };
+  rec.events.push({
+    polarity,
+    at: now,
+    contentHash: polarity === 'upsert' ? hashContent(envelope) : null,
+  });
+  if (rec.events.length > WRITE_HISTORY_PER_ID) rec.events.shift();
+  writeHistory.set(entityId, rec);
+  while (writeHistory.size > WRITE_HISTORY_IDS) {
+    writeHistory.delete(writeHistory.keys().next().value);
+  }
+
+  const transitions = countTransitions(rec.events, now);
+  if (transitions < diagnosticsConfig.loopTransitions) return;
+  if (rec.warnedAt !== 0 && now - rec.warnedAt < diagnosticsConfig.loopWindowMs) return;
+  rec.warnedAt = now;
+  diagLog(
+    'warn',
+    `[vault] WRITE LOOP? entity ${entityId}: ${transitions} redundant writes (polarity flips, repeat deletes or identical rewrites) in the last ${Math.round(diagnosticsConfig.loopWindowMs / 60_000)} min — ${renderHistory(rec.events)}`
+  );
+};
+
+const writeLoopSuspects = () => {
+  const now = Date.now();
+  const suspects = [];
+  for (const [entityId, rec] of writeHistory) {
+    const transitions = countTransitions(rec.events, now);
+    if (transitions === 0) continue;
+    suspects.push({
+      entityId,
+      transitions,
+      warned: rec.warnedAt !== 0,
+      history: rec.events.map((e) => ({ polarity: e.polarity, at: e.at, contentHash: e.contentHash })),
+    });
+  }
+  return suspects.sort((a, b) => b.transitions - a.transitions).slice(0, 20);
+};
+
+// ---------------------------------------------------------------------------
+// The shared stats surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Everything the module-scope diagnostics know, in one read: the brake's
+ * state, the last rolling minute of request counts attributed by method, and
+ * the entityIds whose recent write history looks loop-shaped.
+ *
+ * @returns {{ brake: object, requests: object, writeLoopSuspects: Array }}
+ */
+export function getVaultStats() {
+  const now = Date.now();
+  meterPrune(now);
+  const byMethod = {};
+  for (const [label, n] of meterTally()) byMethod[label] = n;
+  return {
+    brake: vaultBrakeStatus(),
+    requests: {
+      lastMinute: meterState.samples.length,
+      softLimitPerMinute: diagnosticsConfig.softLimitPerMinute,
+      byMethod,
+      droppedSamples: meterState.dropped,
+    },
+    writeLoopSuspects: writeLoopSuspects(),
+  };
+}
+
+/**
+ * Tunes the visibility-only thresholds. The brake's curve is deliberately NOT
+ * configurable: it is a protection for someone else's server, and an app that
+ * could widen it would eventually widen it.
+ *
+ * @param {object} [options]
+ * @param {number} [options.softLimitPerMinute] - budget-meter warn threshold (default 300)
+ * @param {number} [options.loopTransitions]    - write-loop K (default 4)
+ * @param {number} [options.loopWindowMs]       - write-loop M (default 10min)
+ * @param {object|null} [options.logger]        - console-shaped sink for the diagnostic lines
+ */
+export function configureVaultDiagnostics(options = {}) {
+  if (typeof options.softLimitPerMinute === 'number' && options.softLimitPerMinute > 0) {
+    diagnosticsConfig.softLimitPerMinute = options.softLimitPerMinute;
+  }
+  if (typeof options.loopTransitions === 'number' && options.loopTransitions > 0) {
+    diagnosticsConfig.loopTransitions = options.loopTransitions;
+  }
+  if (typeof options.loopWindowMs === 'number' && options.loopWindowMs > 0) {
+    diagnosticsConfig.loopWindowMs = options.loopWindowMs;
+  }
+  if ('logger' in options) diagnosticsConfig.logger = options.logger || null;
+  return { ...diagnosticsConfig };
+}
+
+/**
+ * Clears the brake, the meter and the write history, and restores the default
+ * thresholds. For tests — module-scope state is per realm and would otherwise
+ * carry between cases.
+ */
+export function resetVaultDiagnostics() {
+  brakeState.until = 0;
+  brakeState.memoryMs = 0;
+  meterState.samples.length = 0;
+  meterState.lastReportAt = 0;
+  meterState.dropped = 0;
+  writeHistory.clear();
+  diagnosticsConfig = {
+    softLimitPerMinute: DEFAULT_SOFT_LIMIT,
+    loopTransitions: DEFAULT_LOOP_TRANSITIONS,
+    loopWindowMs: DEFAULT_LOOP_WINDOW_MS,
+    logger: null,
+  };
+}
+
 // Quota rejection parsing (GLANCEvault Phase 3.2 / client Phase 3.3).
 //
 // The server rejects an over-quota write with 413 (storage-shaped: `storage`,
@@ -200,16 +626,25 @@ export async function enrollVaultDevice({ vaultUrl, enrollmentSecret, accountId,
 /**
  * Creates a vault client bound to a server URL and token.
  *
+ * Every network method of the returned client passes through the module-scope
+ * brake and budget meter (see the diagnostics block at the top of this file).
+ * That is deliberate: protection a caller has to remember to apply is
+ * protection that is missing on the day it matters.
+ *
  * @param {object} config
  * @param {string} config.vaultUrl   - base URL of the GLANCEvault server
  * @param {string} config.vaultToken - Bearer token: the shared device token
  *   (shared mode) or this device's enrolled credential (per-account mode)
  * @param {Function} [config.fetchImpl] - fetch implementation (defaults to global fetch)
+ * @param {boolean} [config.brake=true] - set false to opt this client out of the
+ *   shared brake (it neither gates on nor arms it). An escape hatch for tests
+ *   that need the wire on every call; production callers should leave it on.
  */
-export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
+export function createVaultClient({ vaultUrl, vaultToken, fetchImpl, brake = true } = {}) {
   const base = requireBaseUrl(vaultUrl, 'createVaultClient');
   if (!vaultToken) throw new Error('createVaultClient: vaultToken is required');
   const doFetch = resolveFetch(fetchImpl, 'createVaultClient');
+  const brakeEnabled = brake !== false;
   const authHeaders = (extra = {}) => ({
     Authorization: `Bearer ${vaultToken}`,
     ...extra,
@@ -230,6 +665,29 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     return res;
   };
 
+  /**
+   * The one door every network method goes through: gate, meter, send, and
+   * report a 2xx back to the brake.
+   *
+   * `label` is the METHOD NAME (batch, intentsList, deleteRow, ...) — the
+   * brake's arming line and the meter's attribution both name it, so the
+   * report says who met the limiter rather than just that someone did.
+   *
+   * A gated call throws BEFORE the fetch and is deliberately silent and
+   * unmetered: it never reaches the wire, so it is not budget the server
+   * spent, and the arming line already reported the incident once.
+   */
+  const send = async (label, method, path, opts) => {
+    if (brakeEnabled) {
+      const gated = brakeGate();
+      if (gated) throw gated;
+    }
+    meterRecord(label);
+    const res = await request(method, path, opts);
+    if (brakeEnabled && res && res.ok) brakeNoteSuccess();
+    return res;
+  };
+
   // Error-body inspection is BEST-EFFORT and deliberately narrow. The server
   // made the 401 body wording the only signal separating shared mode's
   // "invalid device token" (server misconfigured / wrong token) from
@@ -238,7 +696,7 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
   // exact wording upgrades the code to CREDENTIAL_INVALID; a missing,
   // 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) => {
+  const errorFromResponse = async (res, context, label) => {
     let body = null;
     let bodyError = null;
     try {
@@ -247,13 +705,25 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     } catch {
       // Empty or non-JSON error body: keep the generic classification.
     }
+    // A 429 arms the shared brake — but only a RATE-LIMITER 429, not an
+    // over-quota one. The server uses 429 for both, and they call for
+    // opposite handling: a limiter hit means "you are asking too often, stop
+    // for a while" (exactly what the brake is), while a quota rejection means
+    // "this account is full", clears only when an operator acts, and already
+    // has its own self-resuming window in the DB engine. Gating on a quota
+    // 429 would mask QUOTA_EXCEEDED and its descriptor behind RATE_LIMITED
+    // and leave the engine unable to render "X of Y used". So the arming
+    // decision waits until the body has been parsed and the quota shape ruled
+    // out — see parseQuotaBody for how narrowly that shape is recognised.
+    const quotaShaped = parseQuotaBody(res.status, body, bodyError);
+    if (res.status === 429 && !quotaShaped && brakeEnabled) brakeArm(label || context);
     if (res.status === 401 && bodyError === 'invalid credential') {
       const err = new VaultError(`${context} failed: 401 — the server rejected this device's credential`, 401);
       err.code = 'CREDENTIAL_INVALID';
       return err;
     }
-    const quota = parseQuotaBody(res.status, body, bodyError);
-    if (quota) {
+    if (quotaShaped) {
+      const quota = quotaShaped;
       const err = new VaultError(
         `${context} failed: ${res.status} — ${quota.quota} quota exceeded (${quota.used} of ${quota.limit}, requested ${quota.requested})`,
         res.status
@@ -265,9 +735,9 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     return new VaultError(`${context} failed: ${res.status}`, res.status);
   };
 
-  const jsonOrThrow = async (res, context) => {
+  const jsonOrThrow = async (res, context, label) => {
     if (!res.ok) {
-      throw await errorFromResponse(res, context);
+      throw await errorFromResponse(res, context, label);
     }
     return res.json();
   };
@@ -293,10 +763,17 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      */
     async batch(app, { accountId, rows }) {
       requireAccountId(accountId, 'batch upsert');
-      const res = await request('POST', `/sync/${encodeURIComponent(app)}/batch`, {
+      // Recorded at intent time, before the wire: a loop that is being gated
+      // by the brake or rejected by the server is still a loop worth naming.
+      if (Array.isArray(rows)) {
+        for (const row of rows) {
+          if (row) noteWrite(row.entityId, 'upsert', row.envelope);
+        }
+      }
+      const res = await send('batch', 'POST', `/sync/${encodeURIComponent(app)}/batch`, {
         body: { accountId, rows },
       });
-      return jsonOrThrow(res, 'batch upsert');
+      return jsonOrThrow(res, 'batch upsert', 'batch');
     },
 
     /**
@@ -305,10 +782,10 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      */
     async list(app, { accountId, since }) {
       requireAccountId(accountId, 'list');
-      const res = await request('GET', `/sync/${encodeURIComponent(app)}/list`, {
+      const res = await send('list', 'GET', `/sync/${encodeURIComponent(app)}/list`, {
         query: { accountId, since: String(since) },
       });
-      return jsonOrThrow(res, 'list');
+      return jsonOrThrow(res, 'list', 'list');
     },
 
     /**
@@ -316,11 +793,11 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      */
     async getRow(app, entityId, accountId) {
       requireAccountId(accountId, 'get row');
-      const res = await request('GET', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
+      const res = await send('getRow', 'GET', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
         query: { accountId },
       });
       if (res.status === 404) return null;
-      return jsonOrThrow(res, 'get row');
+      return jsonOrThrow(res, 'get row', 'getRow');
     },
 
     /**
@@ -334,13 +811,14 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      */
     async deleteRow(app, entityId, accountId, opts = {}) {
       requireAccountId(accountId, 'delete row');
+      noteWrite(entityId, 'delete');
       const query = { accountId };
       if (opts && opts.deletedAt != null) query.deletedAt = String(opts.deletedAt);
-      const res = await request('DELETE', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
+      const res = await send('deleteRow', 'DELETE', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
         query,
       });
       if (res.status === 404) return null;
-      return jsonOrThrow(res, 'delete row');
+      return jsonOrThrow(res, 'delete row', 'deleteRow');
     },
 
     /**
@@ -350,10 +828,10 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      */
     async device(app, { accountId, deviceId, lastSeenSeq }) {
       requireAccountId(accountId, 'device cursor');
-      const res = await request('POST', `/sync/${encodeURIComponent(app)}/device`, {
+      const res = await send('device', 'POST', `/sync/${encodeURIComponent(app)}/device`, {
         body: { accountId, deviceId, lastSeenSeq },
       });
-      return jsonOrThrow(res, 'device cursor');
+      return jsonOrThrow(res, 'device cursor', 'device');
     },
 
     /**
@@ -361,9 +839,9 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * salt is registered yet (404).
      */
     async getSalt(accountId) {
-      const res = await request('GET', `/salt/${encodeURIComponent(accountId)}`);
+      const res = await send('getSalt', 'GET', `/salt/${encodeURIComponent(accountId)}`);
       if (res.status === 404) return null;
-      const body = await jsonOrThrow(res, 'get salt');
+      const body = await jsonOrThrow(res, 'get salt', 'getSalt');
       return body && body.salt ? fromBase64(body.salt) : null;
     },
 
@@ -377,11 +855,70 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
      * @returns {Promise<Uint8Array>}
      */
     async putSalt(accountId, salt) {
-      const res = await request('PUT', `/salt/${encodeURIComponent(accountId)}`, {
+      const res = await send('putSalt', 'PUT', `/salt/${encodeURIComponent(accountId)}`, {
         body: { salt: toBase64(salt) },
       });
-      const body = await jsonOrThrow(res, 'put salt');
+      const body = await jsonOrThrow(res, 'put salt', 'putSalt');
       return body && body.salt ? fromBase64(body.salt) : salt;
     },
+
+    // ───────────────────────── intents transport (1.11.0) ────────────────────
+    //
+    // The client half of GLANCEvault's /intents/* surface, so apps can drop
+    // their hand-rolled raw-fetch transports and inherit this client's auth,
+    // error classification, brake and meter. PURE TRANSPORT: the envelope is
+    // OPAQUE here and is never decoded, inspected or validated — the codec
+    // (and the per-envelope key derivation it needs) stays in
+    // @glance-apps/intents on the app side, which is why this package can
+    // carry the transport without carrying the crypto.
+    //
+    // The wire contract below is what the server already serves; nothing in
+    // this release changes it.
+
+    /**
+     * Appends intent events. INSERT-ONLY: the server ignores an eventId it
+     * has already stored, so a re-sent batch after an ambiguous failure is a
+     * no-op rather than a duplicate — retries are safe by construction.
+     *
+     * POST {vaultUrl}/intents/batch
+     *   body { accountId, events: [{ eventId, envelope, expiresAt }] }
+     *
+     * @param {string} accountId
+     * @param {Array<{ eventId: string, envelope: string, expiresAt: string }>} events
+     *   envelope is an opaque base64 string; expiresAt is an ISO timestamp.
+     * @returns {Promise<{ written: number, maxSeq: number }>}
+     */
+    async intentsBatch(accountId, events) {
+      requireAccountId(accountId, 'intents batch');
+      if (!Array.isArray(events)) {
+        const err = new Error('intents batch: events must be an array of { eventId, envelope, expiresAt }.');
+        err.code = 'EVENTS_REQUIRED';
+        throw err;
+      }
+      const res = await send('intentsBatch', 'POST', '/intents/batch', {
+        body: { accountId, events },
+      });
+      return jsonOrThrow(res, 'intents batch', 'intentsBatch');
+    },
+
+    /**
+     * Fetches intent events with seq > since, ascending, one page per call.
+     * The server returns only non-expired rows and pages at 500.
+     *
+     * GET {vaultUrl}/intents/list?accountId=&since=&limit=
+     *
+     * @param {string} accountId
+     * @param {object} [opts]
+     * @param {number} [opts.since=0] - exclusive seq cursor
+     * @param {number} [opts.limit]   - page size; omitted lets the server choose
+     * @returns {Promise<{ rows: Array<{ eventId: string, envelope: string, seq: number, expiresAt: string, serverMtime: string }>, hasMore: boolean }>}
+     */
+    async intentsList(accountId, { since = 0, limit } = {}) {
+      requireAccountId(accountId, 'intents list');
+      const query = { accountId, since: String(since) };
+      if (limit != null) query.limit = String(limit);
+      const res = await send('intentsList', 'GET', '/intents/list', { query });
+      return jsonOrThrow(res, 'intents list', 'intentsList');
+    },
   };
 }

package/types/index.d.ts

@@ -40,7 +40,13 @@ export type SyncErrorCode =
   // 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';
+  | 'QUOTA_EXCEEDED'
+  // DB transport (1.11.0): the module-scope brake is engaged after a real 429,
+  // so this call failed FAST without touching the network. Carries
+  // `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';
 
 export type SyncStatus = 'idle' | 'uploading' | 'downloading' | 'success' | 'error';
 
@@ -422,6 +428,23 @@ export interface VaultPulledRow extends Partial<VaultRow> {
   envelope?: string;
 }
 
+/**
+ * One intent event on the wire. `envelope` is OPAQUE to this package — it is
+ * never decoded or inspected; the codec lives in `@glance-apps/intents`.
+ */
+export interface VaultIntentEvent {
+  eventId: string;
+  /** Opaque base64 payload. */
+  envelope: string;
+  /** ISO 8601. */
+  expiresAt: string;
+}
+
+export interface VaultIntentRow extends VaultIntentEvent {
+  seq: number;
+  serverMtime: string;
+}
+
 export interface VaultClient {
   batch(app: string, args: { accountId: string; rows: VaultRow[] }): Promise<{ written: number; maxSeq: number }>;
   list(app: string, args: { accountId: string; since: number }): Promise<{ rows: VaultPulledRow[]; hasMore: boolean }>;
@@ -430,6 +453,10 @@ export interface VaultClient {
   device(app: string, args: { accountId: string; deviceId: string; lastSeenSeq: number }): Promise<{ updated: boolean }>;
   getSalt(accountId: string): Promise<Uint8Array | null>;
   putSalt(accountId: string, salt: Uint8Array): Promise<Uint8Array>;
+  /** Appends intent events. Insert-only: a re-sent eventId is a server no-op. */
+  intentsBatch(accountId: string, events: VaultIntentEvent[]): Promise<{ written: number; maxSeq: number }>;
+  /** Fetches non-expired intent events with seq > since, ascending. One page per call. */
+  intentsList(accountId: string, opts?: { since?: number; limit?: number }): Promise<{ rows: VaultIntentRow[]; hasMore: boolean }>;
 }
 
 export function createVaultClient(config: {
@@ -437,8 +464,89 @@ export function createVaultClient(config: {
   /** Shared device token, or the device's enrolled credential in per-account mode. */
   vaultToken: string;
   fetchImpl?: typeof fetch;
+  /**
+   * Set false to opt this client out of the module-scope brake — it then
+   * neither gates on nor arms it. An escape hatch for tests that need the
+   * wire on every call; production callers should leave it on.
+   * @default true
+   */
+  brake?: boolean;
 }): VaultClient;
 
+// ---------------------------------------------------------------------------
+// Module-scope request diagnostics (1.11.0)
+// ---------------------------------------------------------------------------
+//
+// One brake, one budget meter and one write-loop history per BUNDLE REALM,
+// not per client instance: they model a resource every client in the process
+// shares — the server's per-IP request budget. A separately bundled copy
+// (e.g. an Obsidian plugin) is its own realm, which is correct: separate
+// process, separate traffic.
+
+export interface VaultBrakeStatus {
+  /** Is the brake engaged right now? While engaged, every client call fails fast with RATE_LIMITED. */
+  braked: boolean;
+  /** Epoch ms the current window expires, or null when not braked. */
+  until: number | null;
+  /** Escalation memory. Doubles per 429 burst to a 10-minute ceiling; a success halves it. */
+  memoryMs: number;
+  /** Milliseconds left in the window, 0 when not braked. */
+  retryInMs: number;
+}
+
+export interface VaultWriteLoopSuspect {
+  entityId: string;
+  /**
+   * Redundant writes counted inside the window: polarity flips, repeat
+   * deletes of an already-deleted row, or identical-content rewrites.
+   */
+  transitions: number;
+  /** Whether the loud one-per-window warning has fired for this id. */
+  warned: boolean;
+  history: Array<{ polarity: 'upsert' | 'delete'; at: number; contentHash: string | null }>;
+}
+
+export interface VaultStats {
+  brake: VaultBrakeStatus;
+  requests: {
+    /** Requests that reached the wire in the last rolling minute. */
+    lastMinute: number;
+    softLimitPerMinute: number;
+    /** Attribution by client method name, e.g. { intentsList: 210, batch: 130 }. */
+    byMethod: Record<string, number>;
+    /** Samples dropped by the buffer's hard cap (only ever under-counts a storm). */
+    droppedSamples: number;
+  };
+  writeLoopSuspects: VaultWriteLoopSuspect[];
+}
+
+/** Is the shared brake engaged? For callers that prefer to sit a cycle out pre-flight. */
+export function isVaultRateLimited(): boolean;
+
+/** The brake's full state. */
+export function vaultBrakeStatus(): VaultBrakeStatus;
+
+/** Brake status, per-minute request counts by method, and write-loop suspects in one read. */
+export function getVaultStats(): VaultStats;
+
+/**
+ * Tunes the visibility-only thresholds. The brake's curve is deliberately not
+ * configurable — it protects someone else's server.
+ */
+export function configureVaultDiagnostics(options?: {
+  /** Budget-meter warn threshold. @default 300 */
+  softLimitPerMinute?: number;
+  /** Write-loop K: redundant writes to one entityId before warning. @default 4 */
+  loopTransitions?: number;
+  /** Write-loop M. @default 600000 (10 minutes) */
+  loopWindowMs?: number;
+  /** Console-shaped sink for the diagnostic lines. Defaults to `console`. */
+  logger?: { warn?: (m: string) => void; info?: (m: string) => void; log?: (m: string) => void } | null;
+}): { softLimitPerMinute: number; loopTransitions: number; loopWindowMs: number; logger: unknown };
+
+/** Clears the brake, the meter and the write history, and restores the defaults. For tests. */
+export function resetVaultDiagnostics(): void;
+
 // Per-account auth (vault Phase 1.4b).
 
 /** Which trust model a GLANCEvault server runs. Discoverable via fetchVaultHealth. */