@neetru/sdk 3.3.0 → 3.4.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to `@neetru/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.1] - 2026-08-20 — **fix(db offline): resiliência da fila offline + honestidade do transporte Documentos**
+
+Release **patch** (correção de resiliência + aditivos opcionais retrocompatíveis; nenhuma mudança de wire, nenhuma remoção de API). Camada offline `client.db` (Mundo Documentos).
+
+### Corrigido
+
+- **P1-C — fila offline sem dead-letter (mutação-veneno travava o FIFO de TODAS as coleções para sempre):** o `SyncEngine` só fazia `markRetry` em falha transiente, então uma mutação com 5xx/timeout persistente na menor `seq` era re-tentada a cada ciclo e bloqueava a fila inteira (head-of-line block). Agora, após esgotar o teto de tentativas (`MAX_MUTATION_ATTEMPTS = 8`), a mutação vira `failed` via `markFailed` (código antes morto) — sai do conjunto `queued`, então `drain()` para de devolvê-la e a fila **destrava** — e grava um `ConflictRecord` com razão nova `failed_max_attempts` (visível em `getConflicts()`). Adicionado **backoff exponencial keyed em `attempts`** (base 1s, teto 5min) na head do FIFO para não marretar o Core. Mutações atrás da head (nunca enviadas) voltam à fila **sem inflar `attempts`** (`requeueInflight`), evitando dead-letter por engano.
+- **P1-B — teto de 200 docs do transporte REST Documentos era silencioso e podia causar perda de dado:** o full-resync baixa no máximo 200 docs/coleção (paginação por cursor é tarefa do Core, fora do escopo do SDK). Agora, quando o retorno bate no teto, a coleção é reportada em `FullResyncResult.truncatedCollections`; o `SyncEngine` (a) **suprime a detecção-de-deleção-por-ausência** para ela (docs além do teto não viram mais tombstone por engano) e (b) persiste o sinal → `DbListResult.truncated === true` (+ `stale: true`). JSDoc público de `list()`/`NeetruDbOptions.dbId` documenta o teto. **Não** pagina (isso exigiria mudança no Core) — apenas sinaliza + documenta honestamente.
+
+### Adicionado (aditivo, opcional)
+
+- **P2-C — diagnóstico de falha de sync (antes engolido com "log silencioso"):** `SyncState.lastError?: string | null` (novo campo opcional, visível via `client.db.syncState` / `onSyncStateChanged`) reflete a última falha de ciclo (exceção nas fases ou dead-letter) e é resetado a cada ciclo bem-sucedido. Novo hook `client.db.onError(cb)` / `SyncEngine.onError(cb)` + tipo `SyncErrorEvent` exportado.
+- `DbListResult.truncated?: boolean` e `Mutation.lastAttemptAt?: number` (interno) — campos opcionais aditivos.
+
+### Alterado
+
+- **P2-A — aviso dev de `dbId` INVERTIDO:** antes avisava quando `dbId` estava AUSENTE; agora avisa quando `dbId` está **PRESENTE** — este é o caso perigoso (falsa sensação de isolamento server-side): dbIds distintos no mesmo tenant/produto **não** isolam os dados no servidor (co-mingling), pois as escritas Documentos sempre caem no datastore genérico escopado só por `x-neetru-tenant`. Continua dev-only, one-time, browser-only, sem efeito de wire.
+
+## [3.4.0] - 2026-08-15 — **feat(support): superfície "Product Feedback" — markResolvedSeen/recordSatisfactionAttempt/submitSatisfaction/contestTicket**
+
+Release **minor** (API pública aditiva no namespace `client.support`: 4 métodos novos + 9 campos novos em `SupportTicket` + 3 opcionais em `CreateTicketInput`).
+
+### Contexto
+
+Camada de dados do fluxo "Product Feedback" (report → resolvido → satisfação → contestação), contrato compartilhado entre Core (endpoints+schema), SDK (`@neetru/sdk` namespace `support`) e `@neetru/product-feedback` (neetru-libs). Ver `CONTRATO_PRODUCT_FEEDBACK_2026-08-15.md`. Decisões do owner: rating CSAT 1-5 (`number | null`); contestação incluída no v1 (4 estados).
+
+### Adicionado
+
+- **`createTicket(input)`**: aceita opcionais `pageUrl?: string`, `screenshotBase64?: string`, `consoleLogs?: string` — propagados no body do POST quando presentes.
+- **`SupportTicket`**: campos novos (todos nullable, mapeados defensivamente em `toTicket()`) — `pageUrl`, `screenshotUrl` (= `attachments[0] ?? null`), `resolvedAt`, `resolvedNotifiedAt`, `satisfactionAttempts` (default `0`), `lastSatisfactionAttemptAt`, `satisfiedAt`, `rating`, `satisfactionComment`.
+- **`markResolvedSeen(ticketId)`**: `POST /api/sdk/v1/support/tickets/{id}/resolved-seen` — marca a notificação de resolução como vista (idempotente no Core).
+- **`recordSatisfactionAttempt(ticketId)`**: `POST .../satisfaction-attempt` — registra exibição do modal de satisfação (regra-chave do fluxo: exibir já conta como tentativa, evita reprompt infinito).
+- **`submitSatisfaction({ ticketId, rating, comment?, skipped })`**: `POST .../satisfaction` — envia (ou pula) a avaliação CSAT.
+- **`contestTicket(ticketId, { comment? })`**: `POST .../contest` — reabre um ticket resolvido e zera o ciclo de satisfação/notificação.
+- Validação client-side antes de cada request: `ticketId` non-empty (`validation_failed`); em `submitSatisfaction`, `rating` inteiro 1-5 quando não-`null`; `comment` ≤ 2000 chars.
+- `MockSupport` espelha os 4 métodos novos in-memory (FSM coerente com o contrato) — modo dev/test sem fetch real.
+- Testes novos cobrindo cada método (path, `requireAuth`, validação client-side), propagação dos campos novos em `createTicket`, e mapeamento defensivo em `toTicket()`.
+
+### Corrigido (incluído neste minor — `bug_58811a43`)
+
+- **JSDoc de `NeetruDbOptions.dbId`** (`src/db/client-db.ts`): reescrito pra descrever o comportamento real (nomeia o cache offline LOCAL + filtro de subscription `nosql-vm`); explicita o que NÃO faz (não escopa as escritas REST — o escopo é `x-neetru-tenant`; não é usado pelo lease SQL, que usa `SqlOptions.database`). O texto antigo ("necessário para scoping das coleções") enganava.
+- **Aviso dev-only one-time** `warnMissingDbIdOnce` (`createNeetruDb`): `console.warn` único em contexto browser + fora de `prod` quando `dbId` está ausente. **Sem mudança de comportamento de wire.**
+
 ## [3.3.0] - 2026-08-09 — **feat(db-sql): motor de ambientes "suspenso" — `db_suspended` não-retryável + lease inicial LAZY**
 
 Release **minor** (API pública aditiva: novo `NeetruDbErrorCode` `db_suspended` + `NeetruError.reason`; `client.db.sql()` deixa de explodir o import quando o ambiente está fora no boot).

package/dist/ai.d.cts

@@ -1,3 +1,3 @@
-export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, aH as createAiNamespace } from './types-DQplLXIk.cjs';
+export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, aJ as createAiNamespace } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/ai.d.ts

@@ -1,3 +1,3 @@
-export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, aH as createAiNamespace } from './types-DslphKIM.js';
+export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, aJ as createAiNamespace } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/dist/auth.cjs

@@ -1584,6 +1584,7 @@ function toTicket(raw) {
   if (typeof r.id !== "string") {
     throw new NeetruError("invalid_response", "Ticket missing id");
   }
+  const firstAttachment = Array.isArray(r.attachments) && typeof r.attachments[0] === "string" ? r.attachments[0] : void 0;
   return {
     id: r.id,
     subject: typeof r.subject === "string" ? r.subject : "",
@@ -1592,9 +1593,28 @@ function toTicket(raw) {
     status: VALID_STATUSES.includes(r.status) ? r.status : "open",
     createdAt: typeof r.createdAt === "string" ? r.createdAt : (/* @__PURE__ */ new Date()).toISOString(),
     updatedAt: typeof r.updatedAt === "string" ? r.updatedAt : void 0,
-    productSlug: typeof r.productId === "string" ? r.productId : typeof r.productSlug === "string" ? r.productSlug : void 0
+    productSlug: typeof r.productId === "string" ? r.productId : typeof r.productSlug === "string" ? r.productSlug : void 0,
+    pageUrl: typeof r.pageUrl === "string" ? r.pageUrl : null,
+    screenshotUrl: typeof r.screenshotUrl === "string" ? r.screenshotUrl : firstAttachment ?? null,
+    resolvedAt: typeof r.resolvedAt === "string" ? r.resolvedAt : null,
+    resolvedNotifiedAt: typeof r.resolvedNotifiedAt === "string" ? r.resolvedNotifiedAt : null,
+    satisfactionAttempts: typeof r.satisfactionAttempts === "number" && Number.isFinite(r.satisfactionAttempts) ? r.satisfactionAttempts : 0,
+    lastSatisfactionAttemptAt: typeof r.lastSatisfactionAttemptAt === "string" ? r.lastSatisfactionAttemptAt : null,
+    satisfiedAt: typeof r.satisfiedAt === "string" ? r.satisfiedAt : null,
+    rating: typeof r.rating === "number" && Number.isFinite(r.rating) ? r.rating : null,
+    satisfactionComment: typeof r.satisfactionComment === "string" ? r.satisfactionComment : null
   };
 }
+function assertTicketId(ticketId) {
+  if (!ticketId || typeof ticketId !== "string") {
+    throw new NeetruError("validation_failed", "ticketId is required");
+  }
+}
+function assertValidComment(comment) {
+  if (typeof comment === "string" && comment.length > 2e3) {
+    throw new NeetruError("validation_failed", "comment max 2000 chars");
+  }
+}
 function resolveProductId(config, ...candidates) {
   for (const c of candidates) {
     if (typeof c === "string" && c.length > 0) {
@@ -1651,6 +1671,15 @@ function createSupportNamespace(config) {
       if (input.metadata && typeof input.metadata === "object") {
         body.metadata = input.metadata;
       }
+      if (typeof input.pageUrl === "string") {
+        body.pageUrl = input.pageUrl;
+      }
+      if (typeof input.screenshotBase64 === "string") {
+        body.screenshotBase64 = input.screenshotBase64;
+      }
+      if (typeof input.consoleLogs === "string") {
+        body.consoleLogs = input.consoleLogs;
+      }
       const raw = await httpRequest(config, {
         method: "POST",
         path: "/api/sdk/v1/support/tickets",
@@ -1676,6 +1705,74 @@ function createSupportNamespace(config) {
       });
       const list = Array.isArray(raw) ? raw : raw && typeof raw === "object" && "tickets" in raw ? raw.tickets ?? [] : [];
       return list.map(toTicket);
+    },
+    /**
+     * 3.4: marca a notificação de resolução como vista (`resolvedNotifiedAt`,
+     * idempotente no Core). Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/resolved-seen`.
+     */
+    async markResolvedSeen(ticketId) {
+      assertTicketId(ticketId);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/resolved-seen`,
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: registra uma tentativa de exibição do modal de satisfação
+     * (`satisfactionAttempts += 1`). Chamar no SHOW do modal, não na
+     * resposta. Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/satisfaction-attempt`.
+     */
+    async recordSatisfactionAttempt(ticketId) {
+      assertTicketId(ticketId);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/satisfaction-attempt`,
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: envia (ou pula) a avaliação de satisfação (CSAT 1-5). Endpoint
+     * canonical: `POST /api/sdk/v1/support/tickets/{id}/satisfaction`.
+     */
+    async submitSatisfaction(input) {
+      if (!input || typeof input !== "object") {
+        throw new NeetruError("validation_failed", "input is required");
+      }
+      assertTicketId(input.ticketId);
+      if (input.rating !== null && input.rating !== void 0) {
+        if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+          throw new NeetruError("validation_failed", "rating must be an integer 1-5 or null");
+        }
+      }
+      assertValidComment(input.comment);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(input.ticketId)}/satisfaction`,
+        body: {
+          rating: input.rating ?? null,
+          comment: input.comment ?? null,
+          skipped: input.skipped
+        },
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: contesta um ticket resolvido — reabre e zera o ciclo de
+     * satisfação/notificação. Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/contest`.
+     */
+    async contestTicket(ticketId, opts) {
+      assertTicketId(ticketId);
+      assertValidComment(opts?.comment);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/contest`,
+        body: { comment: opts?.comment ?? void 0 },
+        requireAuth: true
+      });
     }
   };
 }
@@ -2446,8 +2543,10 @@ var MutationQueue = class {
     await this.store.deleteMutation(mutationId);
   }
   /**
-   * Marca uma mutação como `failed` e registra o erro.
-   * Incrementa `attempts`. Chamado pelo SyncEngine em falha permanente.
+   * Marca uma mutação como `failed` (dead-letter) e registra o erro.
+   * Incrementa `attempts` e carimba `lastAttemptAt`. Chamado pelo SyncEngine
+   * quando a mutação esgota o teto de tentativas (mutação-veneno): sai do
+   * conjunto `queued`, então `drain()` para de devolvê-la e a fila DESTRAVA.
    */
   async markFailed(mutationId, error) {
     const mut = await this.store.getMutation(mutationId);
@@ -2456,12 +2555,14 @@ var MutationQueue = class {
       ...mut,
       status: "failed",
       lastError: error,
-      attempts: mut.attempts + 1
+      attempts: mut.attempts + 1,
+      lastAttemptAt: Date.now()
     });
   }
   /**
-   * Incrementa `attempts` e volta para `queued` (falha transiente com backoff).
-   * Chamado pelo SyncEngine em falha transiente (5xx, timeout).
+   * Incrementa `attempts`, carimba `lastAttemptAt` e volta para `queued`
+   * (falha transiente com backoff). Chamado pelo SyncEngine em falha
+   * transiente (5xx, timeout) da mutação que REALMENTE foi tentada.
    */
   async markRetry(mutationId, error) {
     const mut = await this.store.getMutation(mutationId);
@@ -2470,9 +2571,24 @@ var MutationQueue = class {
       ...mut,
       status: "queued",
       lastError: error,
-      attempts: mut.attempts + 1
+      attempts: mut.attempts + 1,
+      lastAttemptAt: Date.now()
     });
   }
+  /**
+   * Reverte uma mutação `inflight` de volta a `queued` SEM tocar em `attempts`
+   * nem `lastAttemptAt`. Usado para mutações que foram marcadas inflight mas
+   * NUNCA chegaram a ser enviadas (estavam atrás da head no FIFO e o push
+   * parou antes delas): contá-las como tentativa as empurraria pro dead-letter
+   * por engano, e adiaria seu envio via backoff sem que tenham falhado.
+   * No-op se a mutação não está mais `inflight`.
+   */
+  async requeueInflight(mutationId) {
+    const mut = await this.store.getMutation(mutationId);
+    if (!mut) return;
+    if (mut.status !== "inflight") return;
+    await this.store.putMutation({ ...mut, status: "queued" });
+  }
 };
 
 // src/db/field-value.ts
@@ -2517,6 +2633,10 @@ function hasFieldSentinel(data) {
 }
 
 // src/db/offline/sync-engine.ts
+var MAX_MUTATION_ATTEMPTS = 8;
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_CAP_MS = 5 * 60 * 1e3;
+var TRUNCATED_COLLECTIONS_META_KEY = "truncatedCollections";
 function hasSentinels(payload) {
   return payload !== null && hasFieldSentinel(payload);
 }
@@ -2551,6 +2671,8 @@ var SyncEngine = class {
   _state;
   /** Listeners de mudança de SyncState. */
   _stateListeners = /* @__PURE__ */ new Set();
+  /** Listeners de erro de ciclo de sync (P2-C — não mais engolido em silêncio). */
+  _errorListeners = /* @__PURE__ */ new Set();
   /** Cleanup functions dos listeners externos. */
   _cleanups = [];
   /** Timer de resync periódico. */
@@ -2609,6 +2731,19 @@ var SyncEngine = class {
       this._stateListeners.delete(cb);
     };
   }
+  /**
+   * Registra um hook de erro de sync (P2-C). Disparado quando um ciclo falha
+   * (exceção inesperada nas fases, falha de pull/resync ou dead-letter de uma
+   * mutação-veneno) — o que antes era engolido com "log silencioso".
+   * O mesmo diagnóstico também aparece em `SyncState.lastError`.
+   * Retorna uma função de unsubscribe.
+   */
+  onError(cb) {
+    this._errorListeners.add(cb);
+    return () => {
+      this._errorListeners.delete(cb);
+    };
+  }
   /**
    * Força um sync imediato (I3 §10.3 `flush()`).
    * Resolve quando a fila esvazia OU rejeita se o engine estiver destruído.
@@ -2641,8 +2776,10 @@ var SyncEngine = class {
       }
       await this._phase2Pull();
       this._phase3Realtime();
-      this._updateState({ status: "idle", lastSyncedAt: Date.now() });
+      this._updateState({ status: "idle", lastSyncedAt: Date.now(), lastError: null });
     } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this._recordSyncError("cycle", `ciclo de sync falhou: ${msg}`);
       this._updateState({ status: "idle" });
     } finally {
       this._syncing = false;
@@ -2677,6 +2814,9 @@ var SyncEngine = class {
   async _phase1Push() {
     const mutations = await this._queue.drain();
     if (mutations.length === 0) return true;
+    if (this._isInBackoff(mutations[0])) {
+      return true;
+    }
     for (const mut of mutations) {
       await this._queue.markInflight(mut.mutationId);
     }
@@ -2684,10 +2824,16 @@ var SyncEngine = class {
     try {
       result = await this._transport.pushMutations(mutations);
     } catch (err) {
-      for (const mut of mutations) {
-        const errMsg = err instanceof Error ? err.message : String(err);
-        await this._queue.markRetry(mut.mutationId, errMsg);
-      }
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const busChangesOnThrow = [];
+      const [head, ...behind] = mutations;
+      await this._retryOrDeadLetter(head, errMsg, busChangesOnThrow);
+      for (const mut of behind) {
+        await this._queue.requeueInflight(mut.mutationId);
+      }
+      if (busChangesOnThrow.length > 0) this._bus.emit(busChangesOnThrow);
+      this._refreshPendingWrites().catch(() => {
+      });
       return false;
     }
     const busChanges = [];
@@ -2714,8 +2860,16 @@ var SyncEngine = class {
     }
     const processedIds = new Set(result.results.map((r) => r.mutationId));
     const unprocessed = mutations.filter((m) => !processedIds.has(m.mutationId));
-    for (const mut of unprocessed) {
-      await this._queue.markRetry(mut.mutationId, "partial_push: muta\xE7\xE3o n\xE3o processada no lote");
+    if (unprocessed.length > 0) {
+      const [boundary, ...behind] = unprocessed;
+      await this._retryOrDeadLetter(
+        boundary,
+        "partial_push: muta\xE7\xE3o n\xE3o processada no lote",
+        busChanges
+      );
+      for (const mut of behind) {
+        await this._queue.requeueInflight(mut.mutationId);
+      }
     }
     if (busChanges.length > 0) {
       this._bus.emit(busChanges);
@@ -2907,6 +3061,67 @@ var SyncEngine = class {
       });
     }
   }
+  // ─── Dead-letter + backoff (P1-C) ────────────────────────────────────────────
+  /**
+   * Trata a falha transiente de UMA mutação que foi realmente tentada.
+   *
+   * - Se ainda há orçamento de tentativas → `markRetry` (volta pra fila com
+   *   backoff, `attempts++`).
+   * - Se esgotou (`attempts+1 >= MAX_MUTATION_ATTEMPTS`) → DEAD-LETTER:
+   *   `markFailed` (sai do conjunto `queued`, então `drain()` para de devolvê-la
+   *   e a fila FIFO DESTRAVA para as demais coleções) + grava um ConflictRecord
+   *   `failed_max_attempts` (o produto vê via `getConflicts()`) + limpa o estado
+   *   pending do doc no cache + registra `lastError`/dispara `onError`.
+   */
+  async _retryOrDeadLetter(mut, errMsg, busChanges) {
+    if (mut.attempts + 1 < MAX_MUTATION_ATTEMPTS) {
+      await this._queue.markRetry(mut.mutationId, errMsg);
+      return;
+    }
+    await this._queue.markFailed(mut.mutationId, errMsg);
+    const conflictRecord = {
+      collection: mut.collection,
+      docId: mut.docId,
+      mutationId: mut.mutationId,
+      losingData: mut.payload ?? {},
+      winningData: {},
+      reason: "failed_max_attempts",
+      detectedAt: Date.now(),
+      delivered: false
+    };
+    await this._store.appendConflict(conflictRecord);
+    const existing = await this._store.getDoc(mut.collection, mut.docId);
+    if (existing) {
+      await this._store.putDoc({
+        ...existing,
+        meta: { ...existing.meta, state: "synced", pendingMutationIds: [] }
+      });
+      busChanges.push({
+        type: "modified",
+        collection: mut.collection,
+        doc: { id: mut.docId, data: existing.data }
+      });
+    }
+    this._recordSyncError(
+      "push",
+      `muta\xE7\xE3o ${mut.mutationId} (${mut.collection}/${mut.docId}) descartada ap\xF3s ${mut.attempts + 1} tentativas: ${errMsg}`
+    );
+  }
+  /**
+   * `true` se a mutação (head do FIFO) ainda está dentro da janela de backoff
+   * desde a última tentativa falha. Só se aplica a mutações já tentadas
+   * (`attempts > 0` e `lastAttemptAt` carimbado).
+   */
+  _isInBackoff(mut) {
+    if (mut.attempts <= 0) return false;
+    const last = mut.lastAttemptAt;
+    if (typeof last !== "number") return false;
+    return Date.now() < last + this._backoffDelayMs(mut.attempts);
+  }
+  /** Backoff exponencial keyed em `attempts`, com teto `BACKOFF_CAP_MS`. */
+  _backoffDelayMs(attempts) {
+    return Math.min(BACKOFF_BASE_MS * 2 ** (attempts - 1), BACKOFF_CAP_MS);
+  }
   // ─── FASE 2 — pull (reconciliar o cache) ─────────────────────────────────────
   /**
    * Busca mudanças do servidor e aplica ao cache via ConflictResolver.
@@ -2946,10 +3161,14 @@ var SyncEngine = class {
     }
     const busChanges = [];
     await this._applyServerDocs(resyncResult.docs, busChanges, true);
+    const truncatedCollections = resyncResult.truncatedCollections ?? [];
+    const truncatedSet = new Set(truncatedCollections);
+    await this._store.setMeta(TRUNCATED_COLLECTIONS_META_KEY, truncatedCollections);
     const returnedKeys = new Set(
       resyncResult.docs.map((d) => `${d.collection}::${d.id}`)
     );
     for (const col of collections) {
+      if (truncatedSet.has(col)) continue;
       const queryResult = await this._store.listDocs(col, {});
       for (const { id } of queryResult.docs) {
         const key = `${col}::${id}`;
@@ -3109,7 +3328,8 @@ var SyncEngine = class {
       status: isOnline ? "idle" : "offline",
       pendingWrites: 0,
       lastSyncedAt: null,
-      isLeaderTab: this._tabCoordinator.isLeader()
+      isLeaderTab: this._tabCoordinator.isLeader(),
+      lastError: null
     };
   }
   /**
@@ -3119,7 +3339,7 @@ var SyncEngine = class {
   _updateState(partial) {
     const prev = this._state;
     const next = { ...prev, ...partial };
-    const changed = prev.status !== next.status || prev.pendingWrites !== next.pendingWrites || prev.lastSyncedAt !== next.lastSyncedAt || prev.isLeaderTab !== next.isLeaderTab;
+    const changed = prev.status !== next.status || prev.pendingWrites !== next.pendingWrites || prev.lastSyncedAt !== next.lastSyncedAt || prev.isLeaderTab !== next.isLeaderTab || (prev.lastError ?? null) !== (next.lastError ?? null);
     this._state = next;
     if (changed) {
       this._emitState(next);
@@ -3133,6 +3353,21 @@ var SyncEngine = class {
       }
     }
   }
+  /**
+   * P2-C: registra a falha de um ciclo de sync — antes engolida em silêncio.
+   * Publica em `SyncState.lastError` (visível via `onSyncStateChanged`) e
+   * dispara o hook `onError`. Nunca lança (diagnóstico é best-effort).
+   */
+  _recordSyncError(phase, message) {
+    this._updateState({ lastError: message });
+    const event = { phase, message, at: Date.now() };
+    for (const listener of this._errorListeners) {
+      try {
+        listener({ ...event });
+      } catch {
+      }
+    }
+  }
   /**
    * Atualiza `pendingWrites` no estado.
    * Chamado de forma assíncrona quando necessário.
@@ -3942,7 +4177,9 @@ var DbCollectionRefImpl = class {
     const isOnline = this._isOnline();
     const syncState = this._engine.getSyncState();
     const nextCursor = buildNextCursor(result.docs, effectiveLimit);
-    const stale = !isOnline || syncState.status === "offline";
+    const truncatedRaw = await this._store.getMeta(TRUNCATED_COLLECTIONS_META_KEY);
+    const truncated = Array.isArray(truncatedRaw) && truncatedRaw.includes(this._collection);
+    const stale = !isOnline || syncState.status === "offline" || truncated;
     const fromCache = hasPending || syncState.lastSyncedAt === null || stale;
     return {
       docs: result.docs.map((d) => ({ id: d.id, data: d.data })),
@@ -3950,7 +4187,8 @@ var DbCollectionRefImpl = class {
       fromCache,
       stale,
       hasPendingWrites: hasPending,
-      changes: []
+      changes: [],
+      truncated
     };
   }
   // ── CRUD ────────────────────────────────────────────────────────────────────
@@ -4396,6 +4634,9 @@ var NeetruDbDocumentsImpl = class {
   async getConflicts() {
     return this._store.listConflicts();
   }
+  onError(cb) {
+    return this._engine.onError(cb);
+  }
 };
 async function createOfflineDocumentsNamespace(opts) {
   const store = isIndexedDBUnavailable() ? new MemoryStore() : new LocalStore(opts.dbName);
@@ -4871,6 +5112,7 @@ var defaultWebSocketFactory = (url) => {
 // src/db/client-db.ts
 var DATASTORE_COLLECTION_ENDPOINT = (collection) => `/api/sdk/v1/datastore/${encodeURIComponent(collection)}`;
 var DATASTORE_DOC_ENDPOINT = (collection, docId) => `/api/sdk/v1/datastore/${encodeURIComponent(collection)}/${encodeURIComponent(docId)}`;
+var DOCUMENTS_RESYNC_PAGE_CAP = 200;
 function resolveTransport(transport, opts, config) {
   if (opts._transport) {
     return opts._transport;
@@ -4983,6 +5225,7 @@ function createRestSyncTransport(config) {
       const tenantHeaders = tenantScopeId ? { "x-neetru-tenant": tenantScopeId } : void 0;
       const now = Date.now();
       const docs = [];
+      const truncatedCollections = [];
       for (const collection of collections) {
         let raw;
         try {
@@ -4992,11 +5235,11 @@ function createRestSyncTransport(config) {
             requireAuth: true,
             retries: 2,
             headers: tenantHeaders,
-            // Teto do Core é 200. Coleções > 200 docs truncam silenciosamente
-            // aqui (paginação cursor é tarefa Core separada) — a detecção de
-            // deleção-por-ausência do SyncEngine NÃO deve rodar sobre truncamento,
-            // então mantemos o limite no máximo do servidor por ora.
-            query: { limit: 200 }
+            // Teto do Core (DOCUMENTS_RESYNC_PAGE_CAP). Coleções acima dele vêm
+            // TRUNCADAS — reportadas em `truncatedCollections` p/ o SyncEngine
+            // (a) NÃO rodar deleção-por-ausência e (b) sinalizar
+            // `DbListResult.truncated`. Paginação por cursor é tarefa Core (gated).
+            query: { limit: DOCUMENTS_RESYNC_PAGE_CAP }
           });
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -5007,6 +5250,9 @@ function createRestSyncTransport(config) {
         }
         const resp = raw;
         const items = Array.isArray(resp?.items) ? resp.items : [];
+        if (items.length >= DOCUMENTS_RESYNC_PAGE_CAP) {
+          truncatedCollections.push(collection);
+        }
         for (const item of items) {
           if (!item || typeof item !== "object") continue;
           const record = item;
@@ -5034,7 +5280,7 @@ function createRestSyncTransport(config) {
           });
         }
       }
-      return { docs, newWatermark: now };
+      return { docs, newWatermark: now, truncatedCollections };
     }
   };
 }
@@ -5096,7 +5342,20 @@ function buildTicketProvider(config, opts) {
     return ticket;
   };
 }
+var _hasWarnedDbIdIgnored = false;
+function warnDbIdIgnoredOnce(config, dbOpts) {
+  if (_hasWarnedDbIdIgnored) return;
+  if (!dbOpts.dbId) return;
+  if (config.env === "prod") return;
+  if (typeof window === "undefined") return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  _hasWarnedDbIdIgnored = true;
+  console.warn(
+    '[neetru/sdk] client.db recebeu `dbId` ("' + dbOpts.dbId + '") mas ele N\xC3O roteia nem escopa nada no servidor: as escritas do mundo Documentos (add/set/update/remove/list) SEMPRE caem no datastore gen\xE9rico do Core, escopado s\xF3 por tenant/produto (header x-neetru-tenant). `dbId` apenas nomeia o cache offline LOCAL (IndexedDB). ATEN\xC7\xC3O: usar dbIds distintos no MESMO tenant/produto N\xC3O isola os dados no servidor \u2014 eles se misturam (co-mingling). Veja o JSDoc de NeetruDbOptions.dbId.'
+  );
+}
 function createNeetruDb(config, dbOpts = {}) {
+  warnDbIdIgnoredOnce(config, dbOpts);
   let resolvedTransport;
   if (dbOpts.transport !== void 0) {
     resolvedTransport = dbOpts.transport;
@@ -5174,6 +5433,20 @@ function createNeetruDb(config, dbOpts = {}) {
     async getConflicts() {
       const docs = await getDocsPromise();
       return docs.getConflicts();
+    },
+    onError(cb) {
+      if (_docsResolved) return _docsResolved.onError(cb);
+      let unsub = null;
+      let cancelled = false;
+      getDocsPromise().then((docs) => {
+        if (!cancelled) {
+          unsub = docs.onError(cb);
+        }
+      });
+      return () => {
+        cancelled = true;
+        unsub?.();
+      };
     }
   };
 }
@@ -6519,7 +6792,18 @@ var MockSupport = class {
       severity: input.severity ?? "normal",
       status: "open",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      productSlug: input.productSlug
+      productSlug: input.productSlug,
+      // 3.4 (product-feedback): espelha o contrato — campos novos nullable,
+      // populados a partir do input quando fornecidos.
+      pageUrl: typeof input.pageUrl === "string" ? input.pageUrl : null,
+      screenshotUrl: typeof input.screenshotBase64 === "string" ? input.screenshotBase64 : null,
+      resolvedAt: null,
+      resolvedNotifiedAt: null,
+      satisfactionAttempts: 0,
+      lastSatisfactionAttemptAt: null,
+      satisfiedAt: null,
+      rating: null,
+      satisfactionComment: null
     };
     this._tickets.push(ticket);
     return ticket;
@@ -6530,6 +6814,62 @@ var MockSupport = class {
     }
     return [...this._tickets];
   }
+  _find(ticketId) {
+    if (!ticketId || typeof ticketId !== "string") {
+      throw new NeetruError("validation_failed", "ticketId is required");
+    }
+    const ticket = this._tickets.find((t) => t.id === ticketId);
+    if (!ticket) {
+      throw new NeetruError("not_found", `ticket ${ticketId} not found`);
+    }
+    return ticket;
+  }
+  /** 3.4: espelha `markResolvedSeen` — idempotente (só seta se ainda null). */
+  async markResolvedSeen(ticketId) {
+    const ticket = this._find(ticketId);
+    if (ticket.resolvedNotifiedAt === null) {
+      ticket.resolvedNotifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+  }
+  /** 3.4: espelha `recordSatisfactionAttempt` — incrementa contador. */
+  async recordSatisfactionAttempt(ticketId) {
+    const ticket = this._find(ticketId);
+    ticket.satisfactionAttempts += 1;
+    ticket.lastSatisfactionAttemptAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  /** 3.4: espelha `submitSatisfaction` — terminal, seta `satisfiedAt`. */
+  async submitSatisfaction(input) {
+    if (!input || typeof input !== "object") {
+      throw new NeetruError("validation_failed", "input is required");
+    }
+    if (input.rating !== null && input.rating !== void 0) {
+      if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+        throw new NeetruError("validation_failed", "rating must be an integer 1-5 or null");
+      }
+    }
+    if (typeof input.comment === "string" && input.comment.length > 2e3) {
+      throw new NeetruError("validation_failed", "comment max 2000 chars");
+    }
+    const ticket = this._find(input.ticketId);
+    ticket.satisfiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    ticket.rating = input.rating ?? null;
+    ticket.satisfactionComment = input.comment ?? null;
+  }
+  /** 3.4: espelha `contestTicket` — reabre e zera o ciclo de satisfação. */
+  async contestTicket(ticketId, opts) {
+    if (typeof opts?.comment === "string" && opts.comment.length > 2e3) {
+      throw new NeetruError("validation_failed", "comment max 2000 chars");
+    }
+    const ticket = this._find(ticketId);
+    ticket.status = "open";
+    ticket.resolvedAt = null;
+    ticket.resolvedNotifiedAt = null;
+    ticket.satisfactionAttempts = 0;
+    ticket.lastSatisfactionAttemptAt = null;
+    ticket.satisfiedAt = null;
+    ticket.rating = null;
+    ticket.satisfactionComment = null;
+  }
   /** Test helper. */
   __reset() {
     this._tickets = [];