@glance-apps/sync 1.8.0 → 1.11.0

package/types/index.d.ts

@@ -32,7 +32,21 @@ 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'
+  // 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';
 
@@ -414,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 }>;
@@ -422,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: {
@@ -429,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. */
@@ -519,6 +635,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 +748,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;