@glance-apps/sync 1.10.0 → 2.0.0

package/types/index.d.ts

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