@seedgrid/ai-toolkit 0.3.2 → 0.3.3

package/seedgridKB/SeedGrid/Produtos/Pulse/Protocolo-e-API.md

@@ -0,0 +1,191 @@
+---
+tags: [seedgrid, produto, pulse, protocolo, api, websocket]
+fonte: seedgrid-products/seedgrid-pulse (backend/PROTOCOL.md, backend/README.md, src/openapi.rs)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse — protocolo realtime e API HTTP
+
+Resumo do contrato. Fonte completa: `backend/PROTOCOL.md` (protocolVersion **1**) e a spec OpenAPI gerada pelo servidor. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · credenciais: [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação]].
+
+## Endereçamento
+
+Uma mensagem tem: `accountId` (da chave), `channel` (obrigatório), `event` (concreto, obrigatório), `group` e `user` (opcionais, independentes), `data`.
+
+| `group` | `user` | entrega para |
+|---|---|---|
+| — | — | todas as conexões **da conta** no canal |
+| G | — | quem assinou G |
+| — | U | as conexões do usuário U |
+| G | U | as conexões de U **que também assinaram** G |
+
+- `user` vem da **credencial** (subject), nunca do `subscribe`. `group` é **namespace, não autorização**: trate a mensagem como **sinal**, não como conteúdo sensível.
+- `group`/`user` não podem ser vazios nem conter `|`. Use `publicId`, nunca e-mail.
+- Fronteira = conta; sem destinatário a mensagem fica `pending` até alguém conectar (TTL expira).
+
+## Publicar (REST)
+
+```http
+POST /api/v1/messages
+x-api-key: <chave project>
+```
+
+```json
+{
+  "channel": "orders",
+  "event": "order.updated",
+  "user": "usr_7f3a9c1e",
+  "deliveryMode": "notification",
+  "data": { "orderId": "o-1", "status": "paid" },
+  "deliveryPolicy": { "maxAttempts": 5, "ttlSeconds": 3600, "retryBaseMs": 250, "retryMaxMs": 5000, "retryStrategy": "exponential" }
+}
+```
+
+Resposta: `{ "messageId": "msg_…", "status": "accepted", "createdAt": "…" }`. `deliveryPolicy` é opcional e limitada pelos tetos `*_CAP` do servidor (campo a campo em [[SeedGrid/Produtos/Pulse/Protocolo-e-API#deliveryPolicy: campo a campo|deliveryPolicy]]). Erros: 400 requisição malformada · 422 `deliveryPolicy`/endereçamento inválido · 401 credencial · 403 `ACCOUNT_MISMATCH`/chave `client` · 404/422 conta inexistente ou revogada, endereçamento ou `event` não concreto.
+
+## Delivery modes
+
+| Modo | Fim do ciclo | `ack` | `result` | DLQ |
+|---|---|---|---|---|
+| `notification` (padrão) | escrita no socket ⇒ `completed` | no-op | erro `result_not_applicable` | nunca |
+| `acknowledged` | `ack` do cliente ⇒ `completed` | termina | erro `result_not_applicable` | nunca |
+| `processed` | `result: success` ⇒ `completed` | ⇒ `delivered` | `success` / `retryable` / `permanent` | **sim** |
+
+Só o `processed` consome tentativas e chega à DLQ. Offline ou falha de transporte **não** vão à DLQ (a mensagem fica `pending`).
+
+## deliveryPolicy: campo a campo
+
+Opcional, por mensagem. Diz **como insistir**, não para quem entregar. Todo campo é opcional: ausente ⇒ vale o padrão do servidor. Uso nos SDKs: [[SeedGrid/Produtos/Pulse/SDKs|SDKs]].
+
+| Campo | Tipo | Padrão do servidor | O que faz |
+|---|---|---|---|
+| `maxAttempts` | inteiro > 0 | `20` (`DELIVERY_MAX_ATTEMPTS`) | Quantas falhas de **execução** (`result: retryable`) a mensagem aguenta. Só vale em `processed`. A cada `retryable` o contador sobe; quando passa de `maxAttempts` (ou seja, na falha de número `maxAttempts + 1`) a mensagem vai à **DLQ**. Falha de transporte (cliente offline, escrita no socket) **não** consome tentativa. `result: permanent` vai à DLQ na hora, independentemente deste valor. |
+| `ttlSeconds` | inteiro > 0 | `86400` = 1 dia (`DELIVERY_TTL_SECONDS`) | Validade da mensagem, contada a partir da publicação. Se ao fim do prazo ela ainda estiver `pending` (ninguém a recebeu), o estado vira `expired` e ela não é mais entregue. Vale para **todos** os modos. Expirar **não** manda para a DLQ nem consome tentativa. Veja [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Como o TTL é aplicado|Como o TTL é aplicado]]. |
+| `resultTimeoutSeconds` | inteiro > 0 (s) | `0` = **sem prazo** (`DELIVERY_RESULT_TIMEOUT_SECONDS`) | **Prazo de execução**, só em `processed`: segundos entre o `ack` e o `result`. Estourado sem `result`, vale como um `result: retryable` com motivo `result_timeout` (consome tentativa; esgotadas, vai à **DLQ**). Detalhes em [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]]. |
+| `retryBaseMs` | inteiro > 0 (ms) | `300` (`DELIVERY_RETRY_BASE_MS`) | Atraso antes da próxima tentativa. Na estratégia `exponential` é o atraso inicial; em `fixed` é o atraso de toda tentativa. |
+| `retryMaxMs` | inteiro > 0 (ms), `>= retryBaseMs` | `5000` (`DELIVERY_RETRY_MAX_MS`) | Teto do atraso entre tentativas. |
+| `retryStrategy` | `"fixed"` \| `"exponential"` | `exponential` (`DELIVERY_RETRY_STRATEGY`) | Como o atraso cresce. |
+
+**Cálculo do atraso** (Confirmado, `DeliveryPolicy::next_delay` no servidor), com *n* = número da tentativa que falhou:
+
+- `exponential`: `min(retryBaseMs × 2^(n−1), retryMaxMs)`. Com base 200 e teto 2000: 200, 400, 800, 1600, 2000, 2000…
+- `fixed`: `min(retryBaseMs, retryMaxMs)`, sempre o mesmo atraso.
+- No `result: retryable`, se o cliente mandar `retryAfterSecs`, **ele vale no lugar** do cálculo acima.
+- O mesmo atraso espaça as tentativas de transporte quando o destinatário está offline ou a escrita no socket falha (a mensagem fica `pending` até o TTL).
+
+**Validação** (rejeita com **422** `INVALID_MESSAGE_REQUEST`): qualquer campo numérico igual a `0` (inclusive `resultTimeoutSeconds`); `retryMaxMs < retryBaseMs` quando os dois vêm; `retryStrategy` diferente de `fixed`/`exponential` (minúsculas).
+
+**Tetos do servidor.** O que o publisher manda **nunca passa** do teto configurado (`DELIVERY_MAX_ATTEMPTS_CAP`, `DELIVERY_TTL_SECONDS_CAP`, `DELIVERY_RETRY_BASE_MS_CAP`, `DELIVERY_RETRY_MAX_MS_CAP`, `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP`): acima dele o valor é **reduzido em silêncio**, sem erro. Como cada teto, quando não definido, é igual ao padrão, **por padrão uma mensagem só consegue pedir menos que o padrão**: `maxAttempts: 50` vira `20`, `ttlSeconds: 604800` vira `86400`. Para permitir mais, suba o `*_CAP` no servidor ([[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]]). Dentro dos tetos, `retryMaxMs` nunca fica abaixo do `retryBaseMs` efetivo. Exceção: o teto do prazo de execução tem padrão `86400` (e não o valor do padrão, que é `0`), então o publisher consegue pedir até 1 dia mesmo com o recurso desligado por padrão; `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP=0` **proíbe** o prazo de execução.
+
+**Quando usar.** Em `notification` e `acknowledged` só o `ttlSeconds` (e o espaçamento das tentativas de transporte) importa; `maxAttempts` e a DLQ só entram em `processed`. Exemplo para um job que pode ser reentregue algumas vezes e deve morrer em 5 minutos:
+
+```json
+"deliveryMode": "processed",
+"deliveryPolicy": { "maxAttempts": 5, "ttlSeconds": 300, "resultTimeoutSeconds": 120, "retryBaseMs": 200, "retryMaxMs": 2000, "retryStrategy": "exponential" }
+```
+
+### Como o TTL é aplicado
+
+- **Quando é verificado.** A cada tentativa de entrega e por um verificador periódico que roda a cada `ceil(DELIVERY_RETRY_BASE_MS / 1000)` segundos, no mínimo 1 s (com o padrão de 300 ms, **a cada 1 s**). Na prática a mensagem expira com até ~1 s de atraso depois do prazo. Esse verificador usa o valor **do servidor**, não o `retryBaseMs` da mensagem. Ele **não** tem relação com o intervalo de limpeza (`DELIVERY_CLEANUP_INTERVAL_SECONDS`), que cuida só de retenção e lixeira.
+- **Só vale para `pending`.** O TTL mede quanto tempo a mensagem espera por um destinatário. Depois que o `ack` chega, uma mensagem `processed` fica `delivered`, e a partir daí o TTL **não a expira mais**. Quem cobre essa fase é o prazo de execução (`resultTimeoutSeconds`, veja abaixo). Sem esse prazo (o padrão é `0` = sem prazo), uma tarefa que o consumidor recebeu e nunca respondeu fica `delivered` até o `result` chegar ou até um operador descartar.
+- **Descarte manual antecipa o TTL.** Em Pendências, "descartar" (`POST /backlog/discard`) leva `pending` **e** `delivered` sem resultado para `expired` na hora. A mensagem continua visível em "Mensagens" e só é apagada pela retenção (`DELIVERY_CLEANUP_RETENTION_DAYS`).
+- **Lixeira.** Mensagem na lixeira não expira por TTL.
+- **Não confunda com o token.** `ttlSeconds` também existe em `issueConnectToken`, mas ali é a janela do token curto para **conectar** (padrão 300 s, teto 900 s). Os dois nomes são iguais e não têm relação entre si.
+- **O publisher não é avisado.** O publish responde `202 accepted` e pronto. Que a mensagem expirou aparece na UI (Mensagens, filtro `expired`), na métrica `delivery_expired_total` e no log de tentativas da mensagem (`outcome: expired`, `message_ttl_exceeded`).
+
+### Prazo de execução (resultTimeoutSeconds)
+
+Disponível a partir do Pulse **0.3.0** (Confirmado no commit `9dcbdad`). Cobre o caso da tarefa que o consumidor recebeu e travou.
+
+- **Só `processed`.** Em `notification` e `acknowledged` não há `result`, então o campo não tem efeito.
+- **Conta do `ack` até o `result`** (`delivered_at`). Cada nova entrega confirmada reinicia a contagem.
+- **Estourou sem `result`:** o servidor aplica o mesmo tratamento de um `result: retryable`: soma 1 à tentativa, devolve a mensagem a `pending` com o backoff da `deliveryPolicy` e a reentrega. Se `attemptCount > maxAttempts`, vai à DLQ com `lastExecutionError = "result_timeout"`. No log de tentativas aparece como `execution_retryable` com detalhe `result_timeout` (não existe outcome separado).
+- **Quando é verificado:** pelo mesmo verificador periódico do retry (a cada ~1 s com o padrão), então o estouro é detectado com até ~1 s de atraso.
+- **Padrão `0` = sem prazo** (`DELIVERY_RESULT_TIMEOUT_SECONDS`), para não mudar o comportamento de quem já usa o Pulse. Peça o prazo por mensagem, ou o operador define um padrão em Configurações. `0` **enviado** no `deliveryPolicy` é inválido (422); para não ter prazo, omita o campo.
+- **Teto:** `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP` (padrão `86400`; `0` proíbe). Acima do teto, o valor é reduzido em silêncio, como nos outros campos.
+- **`result` tardio é ignorado.** Se o `result` da tentativa antiga chegar depois do estouro, enquanto a mensagem espera a nova tentativa (`pending` com `lastExecutionError = "result_timeout"`), o servidor o ignora (sem erro de protocolo e sem alterar o estado). Depois que a nova tentativa é entregue e confirmada, o `result` volta a valer. **Limitação:** não há identificador de tentativa; um `result` antigo que chegue *depois* da reentrega ser confirmada é aceito.
+- **Mensagens antigas:** as `delivered` que já existiam antes da migration (`0013`) ficam **sem prazo**; o descarte manual em Pendências continua sendo a saída para elas.
+- **Cuidado (a tarefa pode rodar duas vezes).** Um prazo curto reentrega uma tarefa que ainda está em execução. Escolha um prazo **maior que o pior caso** da tarefa e torne o consumidor **idempotente** (deduplicando por `messageId`).
+- **Observabilidade:** motivo `result_timeout` na UI (tela de detalhes da mensagem: "Último erro de execução" e detalhe das tentativas; as telas de DLQ não mostram esse campo) e o campo opcional "Prazo de execução (s)" na tela Publicar e a métrica `seedgrid_pulse_delivery_result_timeout_total`. O endpoint `/meta` expõe o padrão e o teto (`deliveryPolicyDefaults.resultTimeoutSeconds` e `deliveryPolicyCaps.resultTimeoutSeconds`).
+
+## DLQ: quando uma mensagem vai para lá
+
+A DLQ (fila de mensagens mortas) guarda **tarefas** que desistiram de executar. Só entra nela mensagem em `processed`, por um destes dois caminhos:
+
+| Situação | Vai à DLQ? |
+|---|---|
+| Subscriber responde `result: permanent` | **Sim, na hora**, sem olhar as tentativas que sobram |
+| Subscriber responde `result: retryable` e as tentativas esgotam (`attemptCount > maxAttempts`) | **Sim** |
+| Subscriber responde `result: retryable` e ainda há tentativas | Não: volta a `pending` e é reentregue após o atraso do backoff (ou do `retryAfterSecs`) |
+| Tarefa `delivered` e o prazo de execução (`resultTimeoutSeconds`) estoura sem `result` | Conta como `retryable` com motivo `result_timeout`: volta a `pending` com backoff; **se as tentativas esgotam, sim**, com `lastExecutionError = "result_timeout"` |
+| Subscriber responde `result: success` | Não: `completed` |
+
+**Nunca vai à DLQ:**
+
+- `notification` e `acknowledged`, mesmo que o destinatário nunca receba (não há execução para falhar; `result` nesses modos é recusado com `result_not_applicable`).
+- Destinatário offline, ou falha ao escrever no socket: a mensagem fica `pending`, tenta de novo e não consome tentativa.
+- TTL vencido: vira `expired`.
+- Tarefa que o consumidor recebeu (`delivered`) e nunca respondeu, **quando não há prazo de execução** (`resultTimeoutSeconds` ausente e padrão `0`): não cai sozinha na DLQ; só o descarte manual a tira dali.
+
+**O que fazer com o que está na DLQ** (UI: Falhas, ou API `/dlq/*`, com as permissões `PULSE_DLQ_READ`, `PULSE_DLQ_REPLAY`, `PULSE_DLQ_CLEAN`):
+
+- **Reprocessar** (`POST /dlq/requeue`): a mensagem volta a `pending` com o contador de tentativas **zerado**, o erro anterior apagado e a **data de publicação reiniciada**, então o TTL também recomeça.
+- **Limpar** (`/dlq/clean`): vai para a lixeira da DLQ (`dlq_removed`); dá para restaurar (`/dlq/trash/restore`) ou apagar de vez (`/dlq/trash/purge`).
+- O motivo da última falha fica registrado (`reason` do `result`).
+
+## Conectar (WebSocket)
+
+```text
+GET /api/v1/connect?protocolVersion=1
+```
+
+Credencial por um de três caminhos (browser não envia header em WebSocket): header `Authorization: Bearer`, query `?access_token=`, ou subprotocolo `bearer, <credencial>` / `pulse.bearer.<credencial>`. Credencial inválida/ausente ⇒ 401 no upgrade.
+
+Fluxo:
+
+```text
+servidor → {"type":"connected","protocolVersion":1,"connectionId":"…"}
+cliente  → {"type":"subscribe","channels":["orders"],"groups":["loja:15"],"events":["order.*"]}
+servidor → {"type":"subscribed","accountId":"…","user":"…","channels":[…],"groups":[…,"user:<u>"],"events":[…]}
+servidor → {"type":"message","messageId":"…","channel":"…","event":"…","data":{…},"requiresAck":true,"deliveryMode":"processed"}
+cliente  → {"type":"ack","messageId":"…"}
+cliente  → {"type":"result","messageId":"…","outcome":"success"|"retryable"|"permanent","reason":"…","retryAfterSecs":30}
+```
+
+- `events`: filtro opcional; `*` só como último segmento e casa **um ou mais** segmentos (`order.*` casa `order.item.updated`, não `order`). Um `subscribe` novo **acumula** canais/grupos e **substitui** o filtro de eventos.
+- O cliente **não declara identidade**: `userId`/`user` enviados são ignorados.
+- Replay: ao assinar, o servidor entrega as pendências da conta que a conexão cobre.
+- Entrega é **at-least-once**: o cliente deve **deduplicar por `messageId`**; `result` é idempotente.
+
+Erros realtime: `unsupported_protocol_version`, `invalid_subscribe`, `invalid_ack`, `invalid_result`, `result_not_applicable`, `channel_not_allowed`, `unauthorized`, `internal_error`.
+
+Fechamentos: **`4403`** `credential_revoked` (chave/conta revogada — **não reconectar** com a mesma credencial); `4401` legado (token expirado; os SDKs ainda tratam).
+
+## Estados de uma mensagem
+
+`pending` → `delivered` → `completed` (terminal) · `dead_letter` (falha de execução) · `expired` (TTL) · `trashed` (na lixeira, só vinda de `pending`) · `dlq_removed` (lixeira da DLQ) · `acknowledged` (legado, lido como `delivered`).
+
+## Endpoints principais
+
+| Área | Endpoints |
+|---|---|
+| Mensagens | `POST/GET /api/v1/messages`, `GET /messages/{id}`, `POST /messages/trash`, `/trash/restore`, `/trash/purge` |
+| Pendências | `GET /backlog`, `POST /backlog/discard` |
+| DLQ | `POST /dlq/requeue`, `/dlq/clean`, `/dlq/trash/restore`, `/dlq/trash/purge` |
+| Conexões / presença / stats | `GET /connections`, `GET /presence/groups/{group}`, `GET /stats/connections`, `GET /stats/messages/aggregates` |
+| Token | `POST /connect-tokens` |
+| Contas | `GET/POST /accounts`, `/accounts/{id}`, `/activate`, `/revoke`, `/trash`, `/trash/restore`, `/purge`, `GET /accounts/{id}/deletion-summary`; chaves em `/accounts/{id}/keys` |
+| Ajustes | `GET /api/v1/admin/settings`; alterar/resetar um ajuste em `/api/v1/admin/settings/{key}` (`POST` altera, `DELETE` volta ao padrão) |
+| Operação | `GET /health`, `/ready`, `/meta`, `/metrics`, `/metrics/prometheus` |
+
+Lotes de lixeira: máximo **1000** ids (`400 BATCH_TOO_LARGE`); resposta `{requested, affected, skipped}`. Erros de domínio seguem RFC 7807 (`application/problem+json`).
+
+## Observabilidade por destinatário
+
+`GET /messages/{id}/recipients` e `GET /recipient-deliveries` (filtros `userId`, `groupId`, `messageId`, `connectionId`, `status`, `acknowledged`) mostram quem recebeu cada mensagem — o histórico serve de **prova de entrega**.
+
+## Compatibilidade
+
+Mudanças aditivas (campos opcionais, novos eventos) não mudam `protocolVersion`; mudar semântica de endereçamento, remover `ack` ou alterar o shape de `message` exige incremento. Ordem de rollout quando o protocolo muda: publicar SDKs ⇒ reinstalar agentes ⇒ subir servidor ⇒ UI.

package/seedgridKB/SeedGrid/Produtos/Pulse/SDKs.md

@@ -0,0 +1,287 @@
+---
+tags: [seedgrid, produto, pulse, sdk, publisher, subscriber]
+fonte: seedgrid-products/seedgrid-pulse/components
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse — SDKs
+
+Dois lados independentes, cada um com sua credencial e seu transporte. Copie/instale **só o lado que precisa**. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · exemplos prontos: [[SeedGrid/Produtos/Pulse/Exemplos|Exemplos]].
+
+| | **Publisher** | **Subscriber** |
+|---|---|---|
+| Papel | publicar mensagens e emitir token curto | conectar, assinar, receber, `ack`/`result` |
+| Roda em | backend confiável (API, worker, job) | navegador, app, agente |
+| Credencial | chave **`project`** (`x-api-key`) 🔒 | token curto (`getToken`) **ou** chave `client` (agente) |
+| Transporte | REST `POST /api/v1/messages` | WebSocket (reconecta sozinho) |
+| Regra de ouro | a chave **nunca** vai ao cliente | **nenhuma** chave no navegador/app |
+
+## Publishers (`components/publishers/`)
+
+| Linguagem | Pacote / coordenada | Versão (manifesto) | Entrada |
+|---|---|---|---|
+| Java 17+ | `br.com.seedgrid:seedgrid-pulse-publisher` (Maven Central) | `2026.10.0` | `PulsePublisher.builder().baseUrl().projectKey().build()` |
+| Next.js (server-only) | `@seedgrid/pulse-publisher-next` | `2026.09.0` | `createPulsePublisher({ baseUrl, projectKey })` |
+| Dart | `seedgrid_pulse_publisher` | `2026.9.1` | `PulsePublisher.create(baseUrl:, projectKey:)` |
+| PHP | `seedgrid/pulse-publisher` (Composer) | — | `HttpPulsePublisher::create(baseUrl:, projectKey:)` |
+| Rust | `seedgrid-pulse-publisher-rust` | `0.2.0` | `PulsePublisher::builder(url, key).build()?` |
+| Delphi | fonte em `src/` (XE6+/FPC) | — | `NewPulsePublisher(url, key)` |
+
+Todos oferecem: `publish(...)` com helpers de destino (`toUser`, `toGroup`, `toAccount`, e grupo+usuário), `deliveryMode`, `deliveryPolicy`, `metadata` e `issueConnectToken(...)`.
+
+Java:
+
+```java
+PulsePublisher publisher = PulsePublisher.builder()
+    .baseUrl(System.getenv("PULSE_BASE_URL"))
+    .projectKey(System.getenv("PULSE_PROJECT_KEY"))
+    .build();
+
+publisher.publish(PublishMessageInput.toUser(
+    "orders", "order.updated", "usr_7f3a9c1e", Map.of("orderId", "o-1")));
+
+// rota autenticada do SEU backend, para o navegador:
+ConnectToken token = publisher.issueConnectToken(
+    new IssueConnectTokenInput(sessao.publicId(), Duration.ofMinutes(5), List.of("orders")));
+```
+
+Next.js:
+
+```ts
+import "server-only";
+import { createPulsePublisher, message } from "@seedgrid/pulse-publisher-next";
+
+export const pulse = createPulsePublisher({
+  baseUrl: process.env.PULSE_BASE_URL!,
+  projectKey: process.env.PULSE_PROJECT_KEY!, // nunca NEXT_PUBLIC_*
+});
+
+await pulse.publish(message.toUser("orders", "order.updated", usuario.publicId, { orderId }));
+const token = await pulse.issueConnectToken({ subject: usuario.publicId, ttlSeconds: 300 });
+```
+
+PHP:
+
+```php
+$publisher = HttpPulsePublisher::create(baseUrl: getenv('PULSE_BASE_URL'), projectKey: getenv('PULSE_PROJECT_KEY'));
+$publisher->publish(PublishMessageInput::toUser('orders', 'order.updated', 'usr_7f3a9c1e', ['orderId' => 'o-1']));
+```
+
+Dart:
+
+```dart
+final publisher = PulsePublisher.create(
+  baseUrl: Platform.environment['PULSE_BASE_URL']!,
+  projectKey: Platform.environment['PULSE_PROJECT_KEY']!,
+);
+final result = await publisher.publish(
+  PublishMessageInput.toUser('orders', 'order.updated', 'usr_7f3a9c1e', {'orderId': 'o-1'}),
+);
+print(result.messageId);
+publisher.close();
+```
+
+Rust:
+
+```rust
+let publisher = PulsePublisher::builder(base_url, project_key).build()?;
+let result = publisher
+    .publish(PublishMessageInput::to_user("orders", "order.updated", "usr_7f3a9c1e", json!({ "orderId": "o-1" })))
+    .await?;
+println!("{}", result.message_id);
+```
+
+Delphi:
+
+```pascal
+Config := TPulsePublisherConfig.Create(GetEnvironmentVariable('PULSE_BASE_URL'), GetEnvironmentVariable('PULSE_PROJECT_KEY'));
+Publisher := TPulsePublisher.Create(Config, TIndyPulseHttpTransport.Create); // Delphi moderno: transporte NetHttp
+R := Publisher.Publish(TPublishMessageInput.ToUser('orders', 'order.updated', 'usr_7f3a9c1e', '{"orderId":"o-1"}'));
+Writeln(R.MessageId);
+```
+
+Variáveis recomendadas no backend: `PULSE_BASE_URL`, `PULSE_PROJECT_KEY` 🔒. Os exemplos completos de cada SDK ficam em `examples/` (ou `example/`) da pasta do pacote.
+
+### Publicar com modo e política de entrega
+
+`deliveryMode` escolhe o ciclo de vida da mensagem e `deliveryPolicy` diz **como insistir** (tentativas, validade, espaçamento). Os dois são opcionais e independentes; o significado campo a campo está em [[SeedGrid/Produtos/Pulse/Protocolo-e-API#deliveryPolicy: campo a campo|Protocolo e API]]. Omitidos, vale `notification` e os padrões do servidor. Um job que o consumidor precisa **executar** usa `processed` (único modo com `result`, retry de execução e DLQ):
+
+Java:
+
+```java
+publisher.publish(PublishMessageInput.builder()
+    .channel("render").event("render.requested").toUser("agent:render-node-7")
+    .data(Map.of("jobId", "job_9f2"))
+    .deliveryMode(DeliveryMode.PROCESSED)
+    .deliveryPolicy(DeliveryPolicy.builder()
+        .maxAttempts(5).ttlSeconds(300).resultTimeoutSeconds(120)
+        .retryBaseMs(200).retryMaxMs(2000)
+        .retryStrategy(RetryStrategy.EXPONENTIAL)
+        .build())
+    .build());
+```
+
+Next.js:
+
+```ts
+await pulse.publish({
+  channel: "render",
+  event: "render.requested",
+  target: { user: "agent:render-node-7" },
+  data: { jobId: "job_9f2" },
+  deliveryMode: "processed",
+  deliveryPolicy: { maxAttempts: 5, ttlSeconds: 300, resultTimeoutSeconds: 120, retryBaseMs: 200, retryMaxMs: 2000, retryStrategy: "exponential" },
+  metadata: { correlationId: "report-4471", source: "report-api" },
+});
+```
+
+PHP:
+
+```php
+$input = PublishMessageInput::toUser('render', 'render.requested', 'agent:render-node-7', ['jobId' => 'job_9f2'])
+    ->withDeliveryMode(DeliveryMode::Processed)
+    ->withDeliveryPolicy(new DeliveryPolicy(
+        maxAttempts: 5, ttlSeconds: 300, retryBaseMs: 200, retryMaxMs: 2000,
+        retryStrategy: RetryStrategy::Exponential,
+        resultTimeoutSeconds: 120, // último parâmetro do construtor
+    ))
+    ->withMetadata(new Metadata(correlationId: 'report-4471', source: 'report-api'));
+$publisher->publish($input);
+```
+
+Dart:
+
+```dart
+await publisher.publish(
+  PublishMessageInput.toUser('render', 'render.requested', 'agent:render-node-7', {'jobId': 'job_9f2'})
+      .withDeliveryMode(DeliveryMode.processed)
+      .withDeliveryPolicy(const DeliveryPolicy(
+        maxAttempts: 5, ttlSeconds: 300, retryBaseMs: 200, retryMaxMs: 2000,
+        retryStrategy: RetryStrategy.exponential,
+        resultTimeoutSeconds: 120,
+      ))
+      .withCorrelationId('report-4471'),
+);
+```
+
+Rust:
+
+```rust
+publisher.publish(
+    PublishMessageInput::to_user("render", "render.requested", "agent:render-node-7", json!({ "jobId": "job_9f2" }))
+        .with_delivery_mode(DeliveryMode::Processed)
+        .with_delivery_policy(DeliveryPolicy {
+            max_attempts: Some(5),
+            ttl_seconds: Some(300),
+            result_timeout_seconds: Some(120),
+            retry_base_ms: Some(200),
+            retry_max_ms: Some(2000),
+            retry_strategy: Some(RetryStrategy::Exponential),
+        }),
+).await?;
+```
+
+Delphi (campo `0`/`rsUnset` = omitir):
+
+```pascal
+Policy := TDeliveryPolicy.Empty;
+Policy.MaxAttempts := 5;
+Policy.TtlSeconds := 300;
+Policy.ResultTimeoutSeconds := 120;
+Policy.RetryBaseMs := 200;
+Policy.RetryMaxMs := 2000;
+Policy.RetryStrategy := rsExponential;
+R := Publisher.Publish(TPublishMessageInput.ToUser('render', 'render.requested', 'agent:render-node-7', '{"jobId":"job_9f2"}')
+  .WithDeliveryMode(dmProcessed)
+  .WithDeliveryPolicy(Policy));
+```
+
+Valores inválidos (`0`, `retryMaxMs < retryBaseMs`, estratégia desconhecida) voltam como **422** `INVALID_MESSAGE_REQUEST` e viram a exceção de validação do SDK (por exemplo `PulseValidationException`). Valores acima dos tetos do servidor **não** dão erro: são reduzidos ao teto.
+
+`resultTimeoutSeconds` (SDKs a partir do Pulse 0.3.0) é o prazo, em segundos, para o consumidor devolver o `result` depois do `ack`; só vale com `processed`. Omitido, vale o padrão do servidor (`0` = sem prazo). Cuidado: um prazo curto reentrega a tarefa ainda em execução, então use um valor maior que o pior caso e deduplique por `messageId`. Os SDKs não validam o valor (o servidor responde 422 para `0`). Notas por linguagem: PHP recebe o parâmetro **no fim** do construtor de `DeliveryPolicy`; no Rust, literais de `DeliveryPolicy` precisam do campo (ou `..Default::default()`); no Delphi, `ResultTimeoutSeconds = 0` omite o campo; no Java o construtor antigo continua existindo. Semântica completa: [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]].
+
+## Subscribers (`components/subscribers/`)
+
+| Plataforma | Pacote | Versão | Camada de framework |
+|---|---|---|---|
+| React / JS | `@seedgrid/pulse-subscriber-react` (npm) | `3.0.0` | hook `usePulseSubscriber` + core `PulseSubscriberClient` |
+| Angular 17+ | `@seedgrid/pulse-subscriber-angular` | `2.0.0` | `PulseSubscriberService` (Observables) + `providePulseSubscriber()` |
+| Flutter / Dart | `seedgrid_pulse_subscriber` | `2.0.0` | streams `states`, `messages` |
+| Rust | `seedgrid-pulse-subscriber-rust` | `0.2.0` | callbacks `on_message`, `on_state_change` |
+| Delphi | fonte em `src/` (Indy) | — | `IPulseSubscriber` (`NewPulseSubscriberIndy`) |
+
+Capacidades comuns: autenticação **só no handshake**; reconexão automática (backoff com jitter); **replay** do backlog ao reconectar (a assinatura é reenviada); `ack` (recebimento) e `reportResult` (execução); deduplicação por `messageId` opcional; `auth-error` ao receber `4403` (sem reconectar).
+
+> **Paridade (Confirmado — comparação dos SDKs em 2026-10):** `unsubscribe`, listas `subscribedChannels/Groups` e `autoAck` existem em React, Flutter e Delphi. O **Angular ainda não os tem** (guarda só a última assinatura); o exemplo Angular contorna isso.
+
+### React
+
+```tsx
+const { messages, connectionState, ack } = usePulseSubscriber({
+  getToken: async () => (await fetch("/api/realtime/connect", { method: "POST" })).json(),
+  subscription: { channels: ["orders"], groups: ["tenant:15"] },
+});
+```
+
+### Angular
+
+```ts
+providePulseSubscriber(() => {
+  const http = inject(HttpClient);
+  return {
+    getToken: () => firstValueFrom(http.post<PulseConnectToken>("/api/realtime/connect", {})),
+    subscription: { channels: ["orders"] },
+  };
+});
+// componente: inject(PulseSubscriberService).messages$ / state$ / ack({ messageId })
+```
+
+### Flutter
+
+```dart
+final subscriber = PulseSubscriber();
+subscriber.messages.listen((m) async { if (m.requiresAck) await subscriber.ack(AckInput(m.messageId)); });
+await subscriber.connect(ConnectInput(getToken: () async => PulseConnectToken.fromJson(await meuBackend.post('/api/realtime/connect'))));
+await subscriber.subscribe(const SubscribeInput(channels: ['orders']));
+```
+
+### Rust (agente, chave `client`)
+
+```rust
+let subscriber = PulseSubscriber::new();
+subscriber.on_message(|m| println!("{} em {}", m.event, m.channel));
+subscriber.connect(ConnectInput::new("http://localhost:18080", "<chave client>")).await?;
+subscriber.subscribe(SubscribeInput::channels(["orders"])).await?;
+```
+
+### Delphi
+
+```pascal
+FSub := NewPulseSubscriberIndy;
+FSub.UseAutoAck(True);
+FSub.OnMessage(App.OnMsg);
+FSub.Connect(TConnectInput.CreateWithToken(App.BuscarToken)); // ou TConnectInput.Create(url, chaveClient)
+FSub.Subscribe(TSubscribeInput.ForChannels(['orders']));
+```
+
+## Fluxo de ponta a ponta (navegador)
+
+```text
+ navegador ──(sessão)──▶ POST /api/realtime/connect   [rota do SEU backend]
+                                   │ issueConnectToken(subject = usuário da sessão)  [chave project]
+                                   ▼
+ navegador ◀── { token, expiresAt, connectUrl }
+ navegador ──WebSocket (access_token=pct_…)──▶ Pulse ──▶ message / ack / result
+```
+
+## Ack × result
+
+- `ack` confirma o **recebimento**; `result` informa o **resultado de execução** (`success`/`retryable`/`permanent`).
+- Só mensagens `processed` esperam `result`; em `notification`/`acknowledged` o servidor o recusa com `result_not_applicable`. Com `autoAck`/auto-ack nos SDKs que o têm, o SDK envia `ack` e, para `processed`, `result:success` depois que o seu handler retorna sem erro.
+- Entrega é at-least-once: **deduplique por `messageId`**.
+
+## Instalação a partir do fonte
+
+Nem todos os SDKs estão em registro público (Confirmado nos commits: Java em Maven Central, React no npm). Para os demais use dependência por caminho/cópia do fonte, como fazem os [[SeedGrid/Produtos/Pulse/Exemplos|exemplos]] (ex.: Flutter com `path: sdk/subscriber`). Cada SDK traz `INSTALLATION.md`, `CONFIGURATION.md`, `SECURITY.md`, `TROUBLESHOOTING.md` e `TESTING.md`.

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Configuracao.md

@@ -0,0 +1,128 @@
+---
+tags: [seedgrid, produto, pulse, servidor, configuracao, variaveis]
+fonte: seedgrid-products/seedgrid-pulse/backend (src/config.rs, env.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — variáveis de ambiente
+
+Todas as variáveis do **servidor**. As da UI estão em [[SeedGrid/Produtos/Pulse/UI/Configuracao|Configuração da UI]]. Arquitetura atual: **login-tenancy, banco único** — a separação entre clientes é lógica, por `company_id`. Sem `POSTGRES_URL` o servidor sobe em modo memória/dev com a plataforma desabilitada.
+
+Convenção: 🔒 = segredo (nunca em repositório/log); valores de exemplo são placeholders, **não** padrões.
+
+## Runtime (HTTP, WebSocket, CORS)
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `HTTP_HOST` | `127.0.0.1` | IP de bind. Em container use `0.0.0.0`. |
+| `HTTP_PORT` | `8080` | Porta HTTP. |
+| `WS_PATH` | `/ws` | Path do WebSocket legado (o endpoint do protocolo é `/api/v1/connect`). |
+| `CORS_ALLOWED_ORIGINS` | vazio | Lista separada por vírgula. Vazio = nenhuma origem liberada. |
+| `WS_HEARTBEAT_INTERVAL_SECONDS` | `30` | Heartbeat do WebSocket. |
+| `WS_IDLE_TIMEOUT_SECONDS` | `90` | Fecha conexão ociosa. |
+
+## Credenciais do Pulse 🔒
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_SERVER_KEY` | — | Chave **administrativa** (contas/chaves, métricas) em `x-api-key`. **Não publica** (403). Só em ENV; fica só com a operação do Pulse. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` | — | Segredo HMAC-SHA256 que assina o token curto de conexão. Sem ele, `POST /api/v1/connect-tokens` responde 503. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_PREVIOUS_SECRET` | — | Segredo anterior, aceito só na verificação (rotação sem derrubar tokens válidos). |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_TTL_SECS` | `300` | Validade do token quando o pedido não informa `ttlSeconds`. É a janela para **conectar**. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_MAX_TTL_SECS` | `900` | Teto: pedido acima → 422. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_KEY` | `600` | Emissões/min por chave `project`; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_SUBJECT` | `30` | Emissões/min por `subject` na mesma chave; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_PUBLIC_WS_URL` | — | Endereço **público** do WebSocket devolvido em `connectUrl`. Ausente = campo omitido. |
+
+Quem usa cada credencial: [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]].
+
+## Persistência e mensageria
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `POSTGRES_URL` | — | **Interruptor da plataforma.** Sem ela, security/login-tenancy/audit/apikeys ficam desligados. 🔒 |
+| `POSTGRES_RUN_MIGRATIONS` | `true` | Roda migrations na subida. |
+| `DELIVERY_STORE_BACKEND` | `memory` | `memory` \| `postgres`. Em produção, `postgres`. |
+| `BROKER_PROVIDER` | `memory` | `memory` \| `redis` \| `nats` \| `rabbitmq` (fallback `EVENT_BUS_BACKEND`). Valor desconhecido cai em `memory`. Detalhes e variáveis por provider: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]. |
+| `PRESENCE_BACKEND` | `memory` | `memory` \| `redis`. Multi-réplica ⇒ `redis`. |
+| `BROKER_REDIS_URL` | — | URL Redis-compatível (fallback `REDIS_URL`). 🔒 |
+| `BROKER_REDIS_CHANNEL` | `seedgrid:pulse:events` | Canal pub/sub (fallback `REDIS_PUBSUB_CHANNEL`). |
+| `BROKER_NATS_URL` | — | URL do NATS (`nats://host:4222`; fallback `NATS_URL`). Obrigatória com `nats`. 🔒 |
+| `BROKER_NATS_SUBJECT` | `seedgrid.pulse.events` | Subject do pub/sub. |
+| `BROKER_RABBITMQ_URL` | — | URL AMQP (fallbacks `RABBITMQ_URL`, `AMQP_URL`). Obrigatória com `rabbitmq`. 🔒 |
+| `BROKER_RABBITMQ_EXCHANGE` | `seedgrid.pulse.events` | Exchange fanout. |
+
+As URLs Redis-compatíveis servem para Valkey e Dragonfly sem mudar mais nada; ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+
+## Entrega (retry, TTL, limpeza)
+
+Os pares `*_CAP` são o **teto** que uma configuração por mensagem pode pedir; omitidos, assumem o valor base. Todos (exceto o intervalo de limpeza) são editáveis em runtime em **Configurações**.
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `DELIVERY_RETRY_STRATEGY` | `exponential` | `exponential` (qualquer outro valor = `fixed`: atraso constante de `DELIVERY_RETRY_BASE_MS`). |
+| `DELIVERY_RETRY_BASE_MS` | `300` | Backoff base. |
+| `DELIVERY_RETRY_MAX_MS` | `5000` | Backoff máximo. |
+| `DELIVERY_MAX_ATTEMPTS` | `20` | Tentativas de execução por mensagem (modo `processed`). |
+| `DELIVERY_TTL_SECONDS` | `86400` | TTL da mensagem (1 dia). |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS` | `0` (sem prazo) | **Prazo de execução** padrão (modo `processed`): segundos entre o `ack` e o `result`. `0` desliga. Estourado, vale como `retryable` com motivo `result_timeout`. Editável em Configurações, sem reinício. |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP` | `86400` (ou o padrão, se maior) | Teto do prazo que o publisher pode pedir; `0` **proíbe** o prazo de execução. |
+| `DELIVERY_RETRY_BASE_MS_CAP` / `DELIVERY_RETRY_MAX_MS_CAP` / `DELIVERY_MAX_ATTEMPTS_CAP` / `DELIVERY_TTL_SECONDS_CAP` | = valor base | Tetos para o override por mensagem. |
+| `DELIVERY_CLEANUP_INTERVAL_SECONDS` | `60` | Intervalo da varredura de retenção (`DELIVERY_CLEANUP_RETENTION_DAYS`) e da limpeza automática da lixeira. **Não** controla a expiração por TTL, que tem verificador próprio (a cada `ceil(DELIVERY_RETRY_BASE_MS/1000)` s, mínimo 1 s). Exige reinício. |
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` (nunca apaga) | **Dias** que uma mensagem em estado final (`completed`/`dead_letter`/`expired`) é mantida. `0` desliga a varredura: o histórico é prova. Obsoleta: `DELIVERY_CLEANUP_RETENTION_SECONDS` (lida só se a de dias não existir). |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` (só manual) | Dias na lixeira antes da limpeza automática. Cada limpeza vai ao audit como `system:pulse`. |
+
+Detalhes e as regras de lixeira: [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].
+
+## Security (login, JWT, RBAC)
+
+Habilitado com `POSTGRES_URL` **e** as chaves RSA. Nomes alinhados à extension Java `security` ([[SeedGrid/Extensions/security/Configuracao|Configuração do security]]).
+
+| Variável | Descrição |
+|---|---|
+| `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` | Caminhos do par RSA (primários). 🔒 |
+| `SECURITY_JWT_PRIVATE_KEY_PEM` / `SECURITY_JWT_PUBLIC_KEY_PEM` | PEM inline (secundário). 🔒 |
+| `SECURITY_JWT_ISSUER` / `SECURITY_JWT_KID` | Issuer e `kid` do JWT. |
+| `SECURITY_JWT_TTL` | Validade do access token, ISO-8601 (`PT8H`). |
+| `SECURITY_REFRESH_TOKEN_TTL` | Validade do refresh token (`P30D`). |
+| `SECURITY_PASSWORD_MIN_SIZE` / `_EXPIRATION_DAYS` / `_MAX_HISTORY` | Política de senha. |
+| `SECURITY_ENCRYPTION_KEY` | AES-256 (base64) da cripto de campo; obrigatória se usar TOTP. 🔒 |
+| `SECURITY_FRONTEND_BASE_URL` | Base da UI nos links de e-mail. |
+| `SEEDGRID_SECURITY_FIRST_ADMIN_USER_EMAIL` / `_NAME` / `_INITIAL_PASSWORD` | Bootstrap do primeiro admin. 🔒 |
+| `SEEDGRID_SECURITY_DEFAULT_COMPANY_CNPJ` / `_CORPORATE_NAME` / `_TRADE_NAME` | Company da plataforma (razão social e fantasia são obrigatórias no bootstrap). |
+
+### 2FA
+
+Desligado por padrão. `SEEDGRID_SECURITY_2F_ENABLED=true` liga; `_ALLOWED_METHODS` (`EMAIL,TOTP`), `_DEFAULT_METHOD` (`TOTP`), `_EMAIL_CODE_TTL`, `_SESSION_TTL`, `_VERIFY_MAX_ATTEMPTS` (5), `_TOTP_ISSUER` (`SeedGrid`; vale trocar para `SeedGrid Pulse`), `_TOTP_DIGITS` (6), `_TOTP_PERIOD` (30), `_TOTP_WINDOW` (1), `_BACKUP_CODES_COUNT` (10). WhatsApp: `SEEDGRID_SECURITY_2F_WHATSAPP_CHANNEL_ID` mais um provider em `SEEDGRID_WHATSAPP_API` (`evolution`/`cloud`) com credenciais ([[SeedGrid/Extensions/whatsapp/Configuracao|whatsapp]]).
+
+### E-mail (SMTP)
+
+`SECURITY_MAILER_USERNAME` e `_PASSWORD` ligam o SMTP real (🔒); `_HOST` (`smtp.gmail.com`), `_PORT` (587), `_START_TLS` (`REQUIRED`), `_FROM`. **Sem usuário e senha o e-mail só vai para o log** — confirmação, reset de senha e 2FA por e-mail não chegam.
+
+## Login-tenancy
+
+`SEEDGRID_LOGIN_TENANCY_APP_CODE` (`seedgrid-app`; use `seedgrid-pulse`), `_APP_NAME`, `_DATABASE_MIGRATE_AT_START` (`true`), `_DATABASE_BASELINE_ON_MIGRATE` (`true`), `_FOUNDATION_STATUS_ENABLED`, `_FOUNDATION_HEALTH_ENABLED`, `_BOOTSTRAP_ENABLED`, `_BOOTSTRAP_ADMIN_ENABLED`. Não existe flag "enabled": a dependência ativa o baseline. `SEEDGRID_SHOW_DEV_MESSAGE` (`false`) inclui detalhe interno nos erros — **nunca em produção**. Ver [[SeedGrid/Extensions/login-tenancy/Configuracao|login-tenancy]].
+
+## Audit
+
+`SEEDGRID_AUDIT_ENABLED` (`true`), `AUDIT_STRATEGY` (`JPA` = Postgres \| `MONGODB`), `SEEDGRID_AUDIT_DB_*` só para banco de auditoria separado, `SEEDGRID_AUDIT_MONGODB_URI`/`_DATABASE`. No deploy padrão as migrations de audit rodam no mesmo banco. A leitura é escopada por `company_id` via headers internos sobrescritos pelo JWT — não os repasse de proxy. Ver [[SeedGrid/Extensions/audit/Configuracao|audit]].
+
+## API keys
+
+`SEEDGRID_APIKEYS_PREFIX_LENGTH` (`8`), `SEEDGRID_APIKEYS_KEY_BYTES` (`32`). Ver [[SeedGrid/Extensions/apikeys/Configuracao|apikeys]].
+
+## Observabilidade
+
+`RUST_LOG` (ex.: `info`). Métricas: `GET /metrics` (JSON) e `GET /metrics/prometheus`; Prometheus e Grafana vêm no compose.
+
+## Variáveis removidas (não configure)
+
+As de multitenancy por subdomínio (`DOMAIN_SUFFIX`, `SEEDGRID_MULTITENANCY_*`, `PRODUCT_PREFIX`, `MULTITENANCY_MAILER_*`) foram eliminadas e são ignoradas. Backup (`BACKUP_*`) e billing (`SEEDGRID_BILLING_*`) não se aplicam ao Pulse hoje.
+
+## Pegadinhas
+
+- A chave de servidor nunca vai para produto nenhum nem para o serviço da UI.
+- Variável definida no EasyPanel **vence** o padrão de código: ao mudar um padrão, confira o ambiente.
+- `0` em retenção/limpeza significa **desligado** (não "apagar tudo").