@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/Extensions/privacy/Rust.md

@@ -0,0 +1,107 @@
+---
+tags: [seedgrid, extension, privacy, rust]
+fonte: rust/seedgrid-rust-crate-privacy
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# privacy — porte Rust (`seedgrid-rust-crate-privacy`)
+
+Porte da lib Java `seedgrid-quarkus-lib-privacy`. Lado Java: [[SeedGrid/Extensions/privacy/Visao-geral|Visão geral do privacy (Java)]] · [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy (Java)]]. Configuração Rust: [[SeedGrid/Extensions/privacy/Configuracao-Rust|Configuração Rust do privacy]].
+
+Base de privacidade LGPD/PII com duas capacidades: (1) **mascaramento** de dados pessoais em JSON/objetos; (2) **criptografia de campo at-rest** AES-256-GCM com **hash de busca** determinístico HMAC-SHA256. Crate puro (sem Axum/DB). **Confirmado** (`src/lib.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-privacy` (lib `seedgrid_privacy`) |
+| Versão | workspace `2026.10.14` |
+| Features | nenhuma |
+| Dependência SeedGrid | `seedgrid-macros` (derive `PersonalData`) |
+| Consumidores (Cargo.toml) | audit (reexporta `masking`), login-tenancy, security, subdomain-tenancy |
+
+## API pública
+| Módulo / símbolo | Papel |
+|---|---|
+| `masking`: `MaskingStrategy` (`Full`, `Format`, `Partial`, `Hash`, `Template`, `Remove`), `MaskRule` (`format`, `hash`, `remove`…), `mask_json`, `PersonalDataResolver`, `PersonalDataSanitizer`, `ResolvedRule`, `masker::{cpf, cnpj, cep}`, `sha256_hex` | mascaramento; caminhos `a.b`, `lista[].campo`; regra repetida segue a ordem de inserção do `LinkedHashMap` Java |
+| `crypto`: `CryptoService`, `AesGcmCryptoService::from_key_spec` / `from_raw_key`, `looks_encrypted`, `VERSION_PREFIX` (`v1`), `CryptoError` | cifra; formato `v1:BASE64(iv):BASE64(ct‖tag)` igual ao Java |
+| `search`: `SearchHashService`, `HmacSha256SearchHashService::from_key_spec`, `SearchNormalization` (`None`, `Canonical`, `Email`), `ValueNormalizer`, `DefaultValueNormalizer`, `SecureSearch`, `EncryptedFieldSearch` | hash de busca |
+| `field`: `CryptoProvider` (estado global), `EncryptedFieldConverter` (`from_provider`, `with_service`), `EncryptedFieldListener`, `SecureFieldsCarrier`, `SecureFieldDescriptor`, `apply_search_hashes_via_provider`, `FieldError`; constantes `ENCRYPTION_ENABLED_PROPERTY`, `CRYPTO_KEY_PROPERTY`, `SEARCH_KEY_PROPERTY` | integração com entidades (sem reflexão/JPA) |
+| `#[derive(PersonalData)]` (de `seedgrid-macros`) | gera `SecureFieldsCarrier` + `encrypt_personal_data`/`decrypt_personal_data` a partir de `#[personal_data(search = "...", normalize = "...")]` |
+
+### `CryptoProvider` (global)
+- `is_encryption_enabled()`: override programático (`set_encryption_enabled_for_tests`) vence; senão lê `SEEDGRID_PRIVACY_ENCRYPTION_ENABLED`; padrão `false`.
+- `get_crypto_service()` / `get_search_hash_service()`: o serviço configurado (`configure`, `configure_with_key`, `configure_search_hash_service`, `configure_search_with_key`) vence; senão é construído **sob demanda** a partir de `SEEDGRID_PRIVACY_CRYPTO_KEY` / `SEEDGRID_PRIVACY_SEARCH_KEY` e guardado em cache. Chave inválida → `None`.
+- `get_secure_search()`, `configure_normalizer`, `get_normalizer`, `reset_for_tests`.
+
+Fonte: `src/field.rs` → `impl CryptoProvider`. Detalhes em [[SeedGrid/Extensions/privacy/Configuracao-Rust|Configuração Rust]].
+
+## Exemplos
+Mascaramento:
+```rust
+use seedgrid_privacy::{mask_json, MaskRule, masker};
+use serde_json::json;
+
+let v = json!({ "cpf": "12345678900", "nome": "Joao", "email": "joao@x.com" });
+let out = mask_json(&v, &[
+    MaskRule::format("cpf", "***.***.***-**"),
+    MaskRule::hash("email"),
+    MaskRule::remove("nome"),
+]);
+assert_eq!(masker::cpf(Some("12345678900")), "***.***.***-00");
+```
+Derive (de `tests/personal_data_derive.rs`):
+```rust
+use seedgrid_privacy::{CryptoProvider, PersonalData, SecureFieldsCarrier};
+
+#[derive(PersonalData, Default)]
+struct User {
+    #[personal_data(search = "email_hash", normalize = "email")]
+    email: String,
+    email_hash: Option<String>,
+    #[personal_data(search = "whats_app_hash")] // normalize padrão = canonical
+    whats_app: Option<String>,
+    whats_app_hash: Option<String>,
+    #[personal_data] // cifra sem gerar hash
+    cnpj: Option<String>,
+}
+```
+
+## Testes
+Unitários em `src/*` (vetores portados do Java, ex.: `SHA-256("abc")`) e `tests/personal_data_derive.rs`. **Não executados.** Sem exemplo em `rust/examples/` (o `seedgrid-login-tenancy-example` usa a crate indiretamente).
+
+## Notas de comportamento
+
+- **Chave ausente/inválida com cifra ligada**: falha (fail-closed); o Rust devolve `CryptoError::InvalidKey` em vez de gravar em claro (`EncryptedFieldConverter::resolve_for_write`). Chave AES > 32 bytes é rejeitada (sem truncar).
+- As mensagens de erro de chave inválida citam `seedgrid.crypto.key` / `seedgrid.search.key` (`src/crypto.rs`, `src/search.rs` → `decode_key`); a propriedade Java é `seedgrid.privacy.crypto.key`.
+- `PARTIAL` com parâmetro negativo cai no padrão 2; `PARTIAL`/`TEMPLATE` contam caracteres Unicode (Java conta UTF-16).
+- Os enums `CryptoAlgorithm`/`SearchAlgorithm` não existem no Rust.
+
+## Enums
+Java: [[SeedGrid/Extensions/privacy/Enums|Enums do privacy (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `MaskingStrategy` | `src/masking.rs` | [[SeedGrid/Extensions/privacy/Enums#MaskingStrategy\|MaskingStrategy]] |
+| `SearchNormalization` | `src/search.rs` | [[SeedGrid/Extensions/privacy/Enums#SearchNormalization\|SearchNormalization]] |
+| `CryptoError`, `FieldError` | `src/crypto.rs`, `src/field.rs` | exceções |
+
+### MaskingStrategy
+Variantes: `Full`, `Format`, `Partial`, `Hash`, `Template`, `Remove` (os mesmos 6 valores do Java). Sem serde; as regras são montadas por código (`MaskRule::format/hash/remove…`).
+
+| Valor | Efeito (`mask_value`) |
+|---|---|
+| `Full` | valor fixo = `param` ou `***` |
+| `Format` | `param` como máscara pronta (vazio → `***`) |
+| `Partial` | só os últimos N caracteres visíveis (`param` = N, padrão 2; negativo cai em 2 — o Java estoura) |
+| `Hash` | SHA-256 hex minúsculo |
+| `Template` | `#` revela, `*` mascara, outro char é literal |
+| `Remove` | estrutural: remove o campo (`is_removal()`; `mask_value` devolve `None`) |
+
+Conta caracteres Unicode (o Java conta unidades UTF-16).
+
+### SearchNormalization
+`None` (padrão), `Canonical`, `Email` — iguais ao Java (`NONE`, `CANONICAL`, `EMAIL`). `None` = valor exato; `Canonical` = trim + NFD sem acentos + minúsculas + só `[a-z0-9]`; `Email` = trim + minúsculas. No derive: `normalize = "none"|"canonical"|"email"` (padrão `canonical`). Sem serde.
+
+`CryptoAlgorithm` (`AES_256_GCM`) e `SearchAlgorithm` (`HMAC_SHA256`) do Java **não existem** no Rust (o algoritmo é fixo).

package/seedgridKB/SeedGrid/Extensions/privacy/Visao-geral.md

@@ -0,0 +1,90 @@
+---
+tags: [seedgrid, library, privacy]
+fonte: java/seedgrid-quarkus-lib-privacy
+branch: main
+commit: 79f8b03eeb
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Privacy — Visão geral
+
+> [!info] Library, não extension Quarkus
+> `seedgrid-quarkus-lib-privacy` é uma **library Java** (jar único com índice Jandex), **não** uma extension Quarkus com `runtime`/`deployment`. Não há `@ConfigRoot`/`@ConfigMapping`; a config é lida via `ConfigProvider`. Documentada nesta estrutura por uniformidade.
+
+Configuração: [[SeedGrid/Extensions/privacy/Configuracao|Configuração do privacy]] · Enums: [[SeedGrid/Extensions/privacy/Enums|Enums do privacy]] · Exemplos: [[SeedGrid/Extensions/privacy/Exemplos|Exemplos do privacy]] · [[SeedGrid/Extensions/privacy/Rust|Porte Rust]]
+
+## Objetivo
+
+Primitivas de privacidade (LGPD/GDPR) para entidades JPA. **Confirmado** (`README.md`, código):
+1. **Secure Fields** — cifra reversível de campos `String` no banco (AES-256-GCM, formato `v1:base64(iv):base64(ciphertext)`) e hash determinístico HMAC-SHA256 (hex, 64 chars) num campo irmão para busca por igualdade. **Opt-in** por `seedgrid.privacy.encryption.enabled` (padrão desligado → grava valor cru).
+2. **Masking de PII** — redação one-way nas saídas (auditoria, export, e-mail, log, resposta de API) via `@PersonalData`/`@MaskRule` + `PersonalDataSanitizer`, ou valor a valor com `PersonalDataMasker`. Não usa chave e funciona nos dois modos.
+
+## Coordenadas e dependências
+
+| Item | Valor |
+|---|---|
+| groupId:artifactId | `br.com.seedgrid:seedgrid-privacy` |
+| Versão (pom) | `2026.07.27` |
+| Parent | `br.com.seedgrid:seedgrid-parent:2026.07.02` |
+| Dependências | `quarkus-arc`, `quarkus-hibernate-orm`, `quarkus-jackson`; testes: `quarkus-junit5`, AssertJ, Mockito, PostgreSQL + Testcontainers |
+| Dependências SeedGrid | nenhuma. É usada por `seedgrid-commons` (embeddables `Address`/`Contact`) e por extensions (audit, security, subdomain-tenancy — segundo o README) |
+
+Fonte: `java/seedgrid-quarkus-lib-privacy/pom.xml`. **Confirmado.**
+
+## Arquitetura
+
+```mermaid
+flowchart TB
+    subgraph SF["Secure Fields (estático, sem CDI no caminho JPA)"]
+        BOOT["CryptoBootstrap<br/>@Singleton @Startup"] -->|"se chaves presentes"| CP["CryptoProvider<br/>(estado estático)"]
+        CONV["EncryptedFieldAttributeConverter<br/>@Convert"] --> CP
+        LIS["EncryptedFieldListener<br/>@EntityListeners"] --> CP
+        SRCH["EncryptedFieldSearch"] --> CP
+        CP --> AES["AesGcmCryptoService<br/>(crypto.key)"]
+        CP --> HMAC["HmacSha256SearchHashService<br/>(search.key)"]
+    end
+    subgraph MK["Masking (CDI)"]
+        SAN["PersonalDataSanitizer<br/>@ApplicationScoped"] --> RES["PersonalDataResolver<br/>@ApplicationScoped (cache por classe)"]
+        MASK["PersonalDataMasker (estático)"] --> STRAT["MaskingStrategy"]
+        SAN --> STRAT
+    end
+```
+
+Fluxo do Secure Fields (**Confirmado**):
+- **Escrita** (`EncryptedFieldAttributeConverter#convertToDatabaseColumn`): flag desligado → grava cru; ligado → cifra (valor já `v1:` não é recifrado).
+- **Leitura** (`convertToEntityAttribute`): segue o **dado**, não o flag — valor `v1:...` é decifrado (exige `crypto.key`), valor cru volta como está.
+- **Hash** (`EncryptedFieldListener`, `@PrePersist`/`@PreUpdate`): só se `@EncryptedField.searchField` estiver preenchido e o flag ligado; aplica `SearchNormalization` (`NONE`/`CANONICAL`/`EMAIL`), desce recursivamente em campos `@Embeddable` (profundidade máx. 5); o campo de hash deve ser **irmão** no mesmo objeto, senão `IllegalStateException`.
+- **Busca**: `EncryptedFieldSearch#hashForSearch(valor[, normalização])` — usar a mesma normalização da anotação; `hashForSearch(valor)` usa `CANONICAL`.
+- `CryptoBootstrap` (startup) configura os serviços se as chaves existirem; senão os serviços são criados lazy no primeiro uso.
+
+## APIs públicas
+
+| Pacote/Símbolo | Papel |
+|---|---|
+| `@EncryptedField(searchField, normalize)` | marca campo `String` sensível (cifra sempre AES-256-GCM e hash sempre HMAC-SHA256) |
+| `EncryptedFieldAttributeConverter` | `AttributeConverter<String,String>` (`@Converter`, aplicar com `@Convert`) |
+| `EncryptedFieldListener` | entity listener (`@EntityListeners`) |
+| `EncryptedFieldSearch` | `hashForSearch(String)`, `hashForSearch(String, SearchNormalization)` |
+| `CryptoProvider` (estático) | `isEncryptionEnabled()`, `looksEncrypted()`, `getCryptoService()`, `getSearchHashService()`, `getSecureSearch()`, `configure*()`, `setEncryptionEnabledForTests()`, `resetForTests()`; constantes dos nomes de propriedade |
+| `CryptoService`, `SearchHashService`, `ValueNormalizer` (+ `AesGcmCryptoService`, `HmacSha256SearchHashService`, `DefaultValueNormalizer`) | interfaces/implementações substituíveis via `CryptoProvider.configure*` |
+| `CryptoProperties` | POJO `cryptoKey`/`searchKey` |
+| `masking.@PersonalData(type, maskWith)` | campo/getter com PII para redação |
+| `masking.@MaskRule(field, type, maskWith, remove)` | regra por caminho (`cpf`, `endereco.cep`, `dependentes[].cpf`), usada por quem chama (ex.: `@Audit`) |
+| `masking.MaskingStrategy` | `FULL`, `FORMAT`, `PARTIAL`, `HASH` (SHA-256), `TEMPLATE`, `REMOVE` |
+| `masking.PersonalDataSanitizer` (bean) | `sanitizeToJson(value, sourceType, rules)`, `sanitizeToJson(value, rules)`, `sanitize(value, type[, rules])` (fail-closed) |
+| `masking.PersonalDataResolver` (bean) | `resolveRules(Class)` |
+| `masking.PersonalDataMasker` (estático) | `mask(value, strategy, param)`, `cpf()`, `cnpj()`, `cep()` |
+
+Sem endpoints REST, eventos CDI ou migrations (as colunas cifradas/hash são do host; o exemplo usa `length = 512` para cifrado e `64` para hash).
+
+## Testes existentes (não executados)
+
+`src/test/java/br/com/seedgrid/privacy/`: `AesGcmCryptoServiceTest`, `HmacSha256SearchHashServiceTest`, `DefaultValueNormalizerTest`, `SearchNormalizationTest`, `EncryptedFieldAttributeConverterTest`, `EncryptedFieldListenerTest`, `EncryptionEnabledFlagTest`, `EncryptedFieldEmbeddableJpaTest` (JPA com `PrivacyTestPersistenceUnitInfo`, PostgreSQL/Testcontainers), `masking/{MaskingStrategy,PersonalDataMasker,PersonalDataResolver,PersonalDataSanitizer}Test`. ~57 anotações `@Test`/`@ParameterizedTest` por grep. Exemplo com testes de integração: `java/examples/seedgrid-privacy-example` (`CustomerEncryptionTest`, `PrivacySchemaBootstrapTest`). **Não executados.**
+
+## Limitações
+
+- **Validação no boot é parcial**: o `CryptoBootstrap` **não** verifica o flag nem a ausência de chaves; a falha ocorre no primeiro persist/hash/decifra. Por outro lado, uma chave **presente e inválida** (Base64 inválido ou < 32 bytes) lança no `CryptoBootstrap` mesmo com o flag desligado. **Confirmado** pelo código; que a exceção em bean `@Startup` aborta o boot é **Inferência**.
+- `crypto.key` com mais de 32 bytes passa no `KeyDecoder` (mínimo 32) mas o AES só aceita 16/24/32 bytes — falharia no primeiro `encrypt` (**Inferência**, comportamento do JCE). Use exatamente 32 bytes.
+- Estado global estático em `CryptoProvider` (não é bean CDI) — compartilhado por toda a JVM.
+- Para e-mail use `SearchNormalization.EMAIL`; `CANONICAL` remove a pontuação e faria e-mails diferentes colidirem (Javadoc de `SearchNormalization`).
+- Trocar de modo com dados existentes exige migração: desligado→ligado deixa registros antigos crus e sem hash; ligado→desligado exige a chave para ler valores `v1:`.

package/seedgridKB/SeedGrid/Extensions/realtime/Configuracao-Rust.md

@@ -0,0 +1,72 @@
+---
+tags: [seedgrid, extension, realtime, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-realtime
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# realtime — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/realtime/Rust|Porte Rust do realtime]] · Java: [[SeedGrid/Extensions/realtime/Configuracao|Configuração do realtime (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `RealtimeConfig` — `rust/seedgrid-rust-crate-realtime/src/config.rs` |
+| Mecanismo | `RealtimeConfig::from_env()` (= `from_lookup(std::env::var)`), `RealtimePublisher::from_env()`, ou struct do host |
+| Prefixo Java | `seedgrid.realtime` (`@ConfigMapping` em `java/seedgrid-quarkus-ext-realtime/runtime/.../configs/RealtimeConfig.java`) |
+| Leitura | no boot (`from_env`); o limite por minuto é fixado ao montar `rest::router` |
+
+Regra de leitura (`from_lookup`): valor `trim`ado; vazio = ausente; valor que não parseia → padrão.
+
+## Variáveis de ambiente
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_REALTIME_ENABLED` (Java `seedgrid.realtime.enabled`) | bool | `true` (case-insensitive) liga; qualquer outro valor desliga | `false` | Não | desligado: `connect` responde `{enabled:false}` e avisos são no-op | `RealtimePublisher::new` | exige URL + chave | `from_env()` | `config.rs`; `publisher.rs` → `new` |
+| `SEEDGRID_REALTIME_PULSE_BASE_URL` (Java `seedgrid.realtime.pulse.base-url`) | `Option<String>` | URL | — | Condicional: obrigatória se ligado | ligado sem ela → log de erro e realtime desligado | `PulsePublisher::builder` | `PULSE_PROJECT_KEY` | `from_env()` | `publisher.rs` → `new` |
+| 🔒 `SEEDGRID_REALTIME_PULSE_PROJECT_KEY` (Java `seedgrid.realtime.pulse.project-key`) | `Option<String>` | chave `project` do Pulse | — | Condicional: obrigatória se ligado | idem | idem | `PULSE_BASE_URL` | `from_env()` | idem |
+| `SEEDGRID_REALTIME_TOKEN_TTL` (Java `seedgrid.realtime.token-ttl`) | Duration | ISO `PTnHnMnS`; número = segundos; sufixos via `seedgrid_runtime::parse_duration` (ex.: `5m`, `300s`); `0`/inválido → padrão | `PT5M` (300 s) | Não | janela para **conectar** com o token (`ttl_seconds`, mínimo 1) | `issue_connect_token` | — | `from_env()` | `config.rs` → `parse_duration`; `publisher.rs` |
+| `SEEDGRID_REALTIME_CHANNELS` (Java `seedgrid.realtime.channels`) | `Option<Vec<String>>` | lista separada por vírgula | todos os da conta (`None`) | Não | channels que o token deixa assinar; também devolvidos no JSON | `issue_connect_token`, `connect` | — | `from_env()` | `config.rs`; `rest.rs` |
+| `SEEDGRID_REALTIME_CONNECT_RATE_PER_MINUTE` (Java `seedgrid.realtime.connect-rate-per-minute`) | u32 | inteiro ≥ 0; `0` desliga | `30` | Não | pedidos de token por minuto, por usuário, por instância | `ConnectRateLimiter` em `rest::router` | — | `from_env()`; fixado em `router()` | `config.rs`; `rest.rs`; `rate_limit.rs` |
+
+Mapeamento Java ↔ env: **Confirmado** (nomes dos métodos do `RealtimeConfig.java` + regra MicroProfile sem ambiguidade; o teste `reads_the_same_env_as_the_java_extension` usa esses nomes). Padrões iguais ao Java (`false`, `PT5M`, `30`).
+
+## Struct `RealtimeConfig`
+| Campo | `Default` |
+|---|---|
+| `enabled` | `false` |
+| `pulse_base_url` | `None` |
+| `pulse_project_key` | `None` |
+| `token_ttl` | 300 s |
+| `channels` | `None` |
+| `connect_rate_per_minute` | `30` |
+
+## Features Cargo
+Nenhuma.
+
+## Somente testes
+| Variável | Onde |
+|---|---|
+| `REALTIME_E2E_PULSE_URL`, 🔒 `REALTIME_E2E_SERVER_KEY` | `tests/pulse_e2e_it.rs` (`#[ignore]`) |
+
+## Configuração mínima
+```dotenv
+SEEDGRID_REALTIME_ENABLED=true
+SEEDGRID_REALTIME_PULSE_BASE_URL=http://<pulse-host>:<porta>
+SEEDGRID_REALTIME_PULSE_PROJECT_KEY=<SEGREDO:pulse-project-key>
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_REALTIME_ENABLED=true
+SEEDGRID_REALTIME_PULSE_BASE_URL=http://<pulse-host>:<porta>   # endereço visto pelo backend
+SEEDGRID_REALTIME_PULSE_PROJECT_KEY=<SEGREDO:pulse-project-key>
+SEEDGRID_REALTIME_TOKEN_TTL=PT5M                              # ou 300 / 5m
+SEEDGRID_REALTIME_CHANNELS=backup,report                      # vazio = todos
+SEEDGRID_REALTIME_CONNECT_RATE_PER_MINUTE=30                  # 0 desliga
+```
+
+## Receitas
+- **Desligado (padrão)**: nada a configurar; o front fica no polling.
+- **Avisos do backup**: `RealtimePublisher::from_env()` e passe-o em `BackupOverrides.user_events` ([[SeedGrid/Extensions/backup/Configuracao-Rust|Configuração Rust do backup]]).

package/seedgridKB/SeedGrid/Extensions/realtime/Configuracao.md

@@ -0,0 +1,104 @@
+---
+tags: [seedgrid, extension, realtime, configuracao]
+fonte: java/seedgrid-quarkus-ext-realtime
+branch: main
+commit: 8f13639b3c
+analisado-em: 2026-10-14
+---
+
+# Realtime (Quarkus) — configuração
+
+Voltar: [[SeedGrid/Extensions/realtime/Visao-geral|Visão geral do realtime]] · [[SeedGrid/Extensions/realtime/Exemplos|Exemplos]] · [[SeedGrid/Extensions/realtime/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixo | `seedgrid.realtime` |
+| Classe de config | `java/seedgrid-quarkus-ext-realtime/runtime/src/main/java/br/com/seedgrid/realtime/configs/RealtimeConfig.java` → `RealtimeConfig` (grupo aninhado `RealtimeConfig.Pulse`) |
+| Mecanismo | SmallRye `@ConfigMapping(prefix = "seedgrid.realtime")` + `@StaticInitSafe`; registrado também por `SeedgridRealtimeProcessor#config()` (`ConfigMappingBuildItem`) |
+| Fase | Runtime (ConfigMapping no módulo runtime). Na prática os valores são lidos uma vez, quando o bean `RealtimePublisher`/`ConnectRateLimiter` é criado. |
+| Outras fontes | Não há `microprofile-config.properties` no runtime nem `@ConfigProperty`/`ConfigProvider` adicionais. |
+
+Variáveis de ambiente: a regra MicroProfile se aplica sem ambiguidade a todas as chaves abaixo, e os nomes `SEEDGRID_REALTIME_*` estão confirmados no README e na mensagem de log de `RealtimePublisher#connect`.
+
+## 2. Propriedades da extension
+
+### Ativação e conexão com o Pulse
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.realtime.enabled` (env `SEEDGRID_REALTIME_ENABLED`) | `boolean` | `true`/`false` | `false` | Não | Liga o realtime. Desligado: `/realtime/connect` responde `200 {enabled:false}`, `publishToUser` é no-op e nada fala com o Pulse. | Liga a integração com o Pulse | Ligado exige `pulse.base-url` e `pulse.project-key`; se faltar algum, o realtime fica desligado e é logado ERROR (a aplicação sobe) | Runtime | Decl.: `RealtimeConfig#enabled()`. Consumo: `RealtimePublisher#connect(RealtimeConfig)` |
+| `seedgrid.realtime.pulse.base-url` (env `SEEDGRID_REALTIME_PULSE_BASE_URL`) | `Optional<String>` | URL do Pulse visível pelo backend (pode ser endereço interno) | — | Condicional: necessária quando `enabled=true` | Valor em branco é tratado como ausente (`filter(!isBlank)`). Passado a `PulsePublisher.builder().baseUrl(...)`. | Endereço do Pulse | Com `enabled=true` e sem valor → realtime desligado + log ERROR | Runtime | Decl.: `RealtimeConfig.Pulse#baseUrl()`. Consumo: `RealtimePublisher#connect` |
+| 🔒 `seedgrid.realtime.pulse.project-key` (env `SEEDGRID_REALTIME_PULSE_PROJECT_KEY`) | `Optional<String>` | chave `project` da conta no Pulse | — | Condicional: necessária quando `enabled=true` | Segredo; fica só no backend. Em branco = ausente. Enviada pelo SDK ao Pulse (header `x-api-key` nos testes). | Autenticar o backend no Pulse | Idem `base-url` | Runtime | Decl.: `RealtimeConfig.Pulse#projectKey()`. Consumo: `RealtimePublisher#connect` |
+
+### Token de conexão e limites
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.realtime.token-ttl` (env `SEEDGRID_REALTIME_TOKEN_TTL`) | `Duration` | ISO-8601 (`PT5M`) ou formatos aceitos pelo conversor de `Duration` do SmallRye | `PT5M` | Não | Janela para **conectar**; a conexão aberta segue depois do vencimento. Repassado ao Pulse em `IssueConnectTokenInput` (o teste com `PT2M` confirma o envio de `ttlSeconds: 120`). Sem validação local de faixa. | Validade do token | Só tem efeito com o realtime ligado | Runtime | Decl.: `RealtimeConfig#tokenTtl()`. Consumo: `RealtimePublisher#issueConnectToken` |
+| `seedgrid.realtime.channels` (env `SEEDGRID_REALTIME_CHANNELS`) | `Optional<List<String>>` | lista separada por vírgula | — (ausente = todos os channels da conta) | Não | Restringe os channels que o token deixa assinar; também é devolvido no corpo do `/realtime/connect`. | Escopo de assinatura | — | Runtime | Decl.: `RealtimeConfig#channels()`. Consumo: `RealtimePublisher#issueConnectToken`, `RealtimeController#connect` |
+| `seedgrid.realtime.connect-rate-per-minute` (env `SEEDGRID_REALTIME_CONNECT_RATE_PER_MINUTE`) | `int` | inteiro; `<= 0` desliga | `30` | Não | Pedidos de token por minuto **por usuário**, janela fixa de 60 s, em memória por instância. Excedido → `429` com `Retry-After` (segundos, mínimo 1). | Proteger a cota de emissões da project key | Só é consultado com o realtime ligado (o controller responde `enabled:false` antes) | Runtime | Decl.: `RealtimeConfig#connectRatePerMinute()`. Consumo: `ConnectRateLimiter(RealtimeConfig)` / `#tryAcquire` |
+
+Total: **6 propriedades públicas**.
+
+## 3. Propriedades de frameworks/bibliotecas
+
+A extension não define nem exige propriedades `quarkus.*`, `mp.*` ou `smallrye.*` (não há `microprofile-config.properties` nem `RunTimeConfigurationDefaultBuildItem`). Indiretamente, `@Authenticated` depende do mecanismo de autenticação configurado no host (ex.: JWT do `seedgrid-security`). (Inferência)
+
+## 4. Propriedades usadas só em testes
+
+Arquivo `runtime/src/test/resources/application.properties` e `FakePulse`:
+
+| Propriedade | Valor no teste | Observação |
+|---|---|---|
+| `quarkus.http.test-port` | `0` | porta aleatória |
+| `seedgrid.realtime.enabled` | `true` | `RealtimeDisabledTest` sobrescreve para `false` via `QuarkusTestProfile` |
+| `seedgrid.realtime.pulse.project-key` | `<SEGREDO:pulse-project-key-de-teste>` | valor fictício de teste (não copiado) |
+| `seedgrid.realtime.token-ttl` | `PT2M` | — |
+| `seedgrid.realtime.connect-rate-per-minute` | `1000` | evita 429 nos testes |
+| `seedgrid.realtime.pulse.base-url` | URL do WireMock | injetada por `FakePulse#start()` |
+
+## 5. Aliases, obsoletas, renomeações
+
+Nenhum alias encontrado. O README declara que a crate Rust usa "mesmo contrato: rota, corpo, config, eventos" — detalhes em [[SeedGrid/Extensions/realtime/Rust|Porte Rust]].
+
+## 6. Configuração mínima
+
+```properties
+seedgrid.realtime.enabled=true
+seedgrid.realtime.pulse.base-url=<URL-DO-PULSE-VISTA-PELO-BACKEND>
+seedgrid.realtime.pulse.project-key=${SEEDGRID_REALTIME_PULSE_PROJECT_KEY}
+```
+
+Sem nenhuma configuração a extension fica desligada (padrão `enabled=false`) e o endpoint responde `{enabled:false}`.
+
+## 7. Configuração completa comentada
+
+```properties
+# Liga o realtime (padrão: false)
+seedgrid.realtime.enabled=true
+# Pulse visto pelo backend (pode ser endereço interno)
+seedgrid.realtime.pulse.base-url=<URL-DO-PULSE>
+# SEGREDO: chave "project" da conta no Pulse. Use variável de ambiente.
+seedgrid.realtime.pulse.project-key=<SEGREDO:pulse-project-key>
+# Janela para conectar (padrão: PT5M)
+seedgrid.realtime.token-ttl=PT5M
+# Channels permitidos no token (ausente = todos os da conta)
+seedgrid.realtime.channels=backup,report
+# Pedidos de token por minuto, por usuário e por instância (padrão: 30; 0 desliga)
+seedgrid.realtime.connect-rate-per-minute=30
+```
+
+## 8. Receitas
+
+- **Desligar em um ambiente**: `SEEDGRID_REALTIME_ENABLED=false` (ou não definir). A tela recebe `{enabled:false}` e fica no polling.
+- **Restringir assinaturas a poucos channels**: `SEEDGRID_REALTIME_CHANNELS=backup,report`.
+- **Remover o limite de emissão** (ex.: testes de carga): `SEEDGRID_REALTIME_CONNECT_RATE_PER_MINUTE=0`.
+- **Pulse em rede interna**: aponte `pulse.base-url` para o endereço interno; o front usa o `connectUrl` devolvido pelo Pulse (não configurado aqui).
+
+## 9. Dúvidas e lacunas
+
+- O formato aceito de `Duration` além do ISO-8601 depende do conversor do SmallRye/Quarkus (Não confirmado neste repositório).
+- Não há validação local de `token-ttl` (negativo/zero); o comportamento fica a cargo do Pulse (Não confirmado).
+- Com várias réplicas, o limite de `connect-rate-per-minute` é por instância (Inferência).

package/seedgridKB/SeedGrid/Extensions/realtime/Exemplos.md

@@ -0,0 +1,104 @@
+---
+tags: [seedgrid, extension, realtime, exemplos]
+fonte: java/seedgrid-quarkus-ext-realtime
+branch: main
+commit: 8f13639b3c
+analisado-em: 2026-10-14
+---
+
+# Realtime (Quarkus) — exemplos
+
+Voltar: [[SeedGrid/Extensions/realtime/Visao-geral|Visão geral do realtime]] · [[SeedGrid/Extensions/realtime/Configuracao|Configuração]]
+
+## 1. Dependência
+
+Fonte: `README.md`.
+
+```xml
+<dependency>
+  <groupId>br.com.seedgrid</groupId>
+  <artifactId>seedgrid-realtime</artifactId>
+  <version>2026.10.08</version>
+</dependency>
+```
+
+## 2. Avisar um usuário pelo evento neutro (preferido)
+
+Fonte: `README.md` e `RealtimeEnabledTest#userEventIsPublishedToThatUser`. O processo não depende desta extension — só do `SgUserEvent` do `seedgrid-commons`. Construtor: `SgUserEvent(userPublicId, channel, event, data)`.
+
+```java
+import br.com.seedgrid.commons.events.SgUserEvent;
+import jakarta.enterprise.event.Event;
+import jakarta.inject.Inject;
+import java.util.Map;
+
+@Inject Event<SgUserEvent> userEvents;
+
+// Dentro da transação que grava o resultado: o aviso sai depois do commit (AFTER_SUCCESS).
+userEvents.fire(new SgUserEvent(userPublicId, "report", "report.finished.success",
+        Map.of("reportPublicId", report.getPublicId())));
+```
+
+`data` leva apenas identificadores; a tela busca o registro pela API normal.
+
+## 3. Avisar diretamente com o `RealtimePublisher`
+
+Fonte: assinatura de `RealtimePublisher#publishToUser(String, String, String, Map<String,Object>)`.
+
+```java
+import br.com.seedgrid.realtime.services.RealtimePublisher;
+
+@Inject RealtimePublisher realtime;
+
+// Assíncrono; nunca propaga erro. Desligado = no-op.
+realtime.publishToUser("backup", "backup.finished.success", userPublicId,
+        Map.of("exportPublicId", exportPublicId, "status", "DONE"));
+```
+
+## 4. Front pedindo o token
+
+Fonte: `RealtimeController` e tabela do `README.md`.
+
+```http
+POST /realtime/connect
+Authorization: Bearer <JWT-DO-USUARIO>
+```
+
+Respostas possíveis:
+
+```json
+{ "enabled": false }
+```
+
+```json
+{ "enabled": true, "token": "pct_...", "expiresAt": 1791119100, "connectUrl": "wss://...", "channels": ["backup"] }
+```
+
+`401` (sem usuário), `429` com `Retry-After`, `503` (Pulse indisponível → manter polling).
+
+## 5. Configuração por ambiente
+
+Fonte: `RealtimeConfig` e `README.md`. Detalhes em [[SeedGrid/Extensions/realtime/Configuracao|Configuração]].
+
+```bash
+SEEDGRID_REALTIME_ENABLED=true
+SEEDGRID_REALTIME_PULSE_BASE_URL=<URL-DO-PULSE>
+SEEDGRID_REALTIME_PULSE_PROJECT_KEY=<SEGREDO:pulse-project-key>
+SEEDGRID_REALTIME_TOKEN_TTL=PT5M
+```
+
+## 6. Testando com Pulse fingido
+
+Fonte: `runtime/src/test/java/br/com/seedgrid/realtime/FakePulse.java` — um `QuarkusTestResourceLifecycleManager` que sobe WireMock e devolve `seedgrid.realtime.pulse.base-url` apontando para ele.
+
+```java
+@QuarkusTest
+@QuarkusTestResource(FakePulse.class)
+class MeuTeste {
+    @Test
+    @TestSecurity(user = "7f3a9c1e-0000-4000-8000-000000000001")
+    void conecta() {
+        given().when().post("/realtime/connect").then().statusCode(200);
+    }
+}
+```

package/seedgridKB/SeedGrid/Extensions/realtime/Rust.md

@@ -0,0 +1,69 @@
+---
+tags: [seedgrid, extension, realtime, rust]
+fonte: rust/seedgrid-rust-crate-realtime
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# realtime — porte Rust (`seedgrid-rust-crate-realtime`)
+
+Porte da extensão Quarkus `seedgrid-quarkus-ext-realtime` ("mesmo env, mesma rota, mesmo JSON"). Lado Java: [[SeedGrid/Extensions/realtime/Visao-geral|Visão geral do realtime (Java)]] · [[SeedGrid/Extensions/realtime/Configuracao|Configuração do realtime (Java)]]. Configuração Rust: [[SeedGrid/Extensions/realtime/Configuracao-Rust|Configuração Rust do realtime]].
+
+Avisos em tempo real ao **usuário logado** via SeedGrid Pulse: entrega ao front um token curto de conexão (`POST /realtime/connect`) e publica os `SgUserEvent` da plataforma. **Confirmado** (`src/lib.rs`, README).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-realtime` (lib `seedgrid_realtime`) |
+| Versão | workspace `2026.10.14` |
+| Features | nenhuma |
+| Dependências SeedGrid | `seedgrid-runtime` (eventos `SgUserEvent`/`UserEventSink`, `parse_duration`); `seedgrid-pulse-publisher-rust` (path `../../../seedgrid-products/seedgrid-pulse/components/publishers/seedgrid-pulse-publisher-rust`, **fora** do `seedgrid-platform`) |
+| Dev-deps | `seedgrid-pulse-subscriber-rust` (também fora do repo), `wiremock` |
+
+Observação: o crate só compila com o repositório `seedgrid-products` presente ao lado de `seedgrid-platform` (**Confirmado** pelo `Cargo.toml`; o caminho existe nesta máquina em `seedgrid-products/...`).
+
+## API pública
+| Símbolo | Papel | Fonte |
+|---|---|---|
+| `RealtimeConfig` (`from_env`, `from_lookup`, `Default`), `config::parse_duration` | config | `src/config.rs` |
+| `RealtimePublisher::new(config)` / `from_env()` | cliente do Pulse; ligado sem URL ou chave → loga erro e fica desligado (a app sobe) | `src/publisher.rs` |
+| `RealtimePublisher::is_enabled`, `config`, `publish_to_user(channel, event, user_public_id, data)`, `issue_connect_token(user_public_id)` | publicação (nunca propaga erro) e emissão de token | `src/publisher.rs` |
+| `impl UserEventSink for RealtimePublisher` | publica `SgUserEvent` numa task própria (par do `@Observes(during = AFTER_SUCCESS)` Java) | `src/publisher.rs` |
+| `IssueError::{Disabled, Pulse}` | erro de emissão | `src/publisher.rs` |
+| `rest::router(publisher, Arc<dyn RealtimeIdentityResolver>)` | rota `POST /realtime/connect` | `src/rest.rs` |
+| trait `RealtimeIdentityResolver` | o host informa o usuário da sessão (ex.: `sub` do JWT) | `src/rest.rs` |
+| `RealtimeConnectResponse` | JSON de resposta (`enabled`, `token`, `expiresAt`, `connectUrl`, `channels`) | `src/rest.rs` |
+| `rate_limit::ConnectRateLimiter` | janela fixa de 1 min por usuário, em memória, por instância | `src/rate_limit.rs` |
+
+## Endpoint `POST /realtime/connect`
+| Status | Quando |
+|---|---|
+| 401 | sem usuário (vale mesmo com realtime desligado) |
+| 200 `{enabled:false}` | desligado ou não configurado |
+| 429 + `Retry-After` | limite `connect_rate_per_minute` excedido |
+| 200 `{enabled:true, token, expiresAt, connectUrl, channels}` | token emitido |
+| 503 | Pulse não respondeu/recusou |
+
+Fonte: `src/rest.rs` → `connect`.
+
+## Exemplo (doc de `src/lib.rs`)
+```rust
+use seedgrid_realtime::RealtimePublisher;
+use seedgrid_runtime::events::UserEventSink;
+
+let realtime = RealtimePublisher::from_env();
+let api = seedgrid_realtime::rest::router(realtime.clone(), identity);
+let user_events: Arc<dyn UserEventSink> = Arc::new(realtime.clone());
+// avisos do backup:
+let overrides = BackupOverrides { user_events: Arc::new(realtime), ..Default::default() };
+```
+Não há app em `rust/examples/` para realtime.
+
+## Testes
+- Unitários (`src/config.rs`: durações, mesmo env do Java, padrão desligado) e `tests/realtime_it.rs` (router contra Pulse simulado com `wiremock`: 401, 429, 503, desligado, publicação).
+- `tests/pulse_e2e_it.rs` (`#[ignore]`) contra Pulse real com `REALTIME_E2E_PULSE_URL` e `REALTIME_E2E_SERVER_KEY`.
+- **Não executados.**
+
+## Enums
+Sem enums de domínio. Enum público de erro: `IssueError` (`src/publisher.rs`) — `Disabled` (realtime desligado; `POST /realtime/connect` responde `{enabled:false}`) e `Pulse(PulseError)` (Pulse recusou ou não respondeu; vira HTTP 503).