@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,109 @@
+---
+tags: [seedgrid, extension, billing, rust]
+fonte: rust/seedgrid-rust-crate-billing
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# billing — porte Rust (`seedgrid-rust-crate-billing`)
+
+Porte das extensões Quarkus `seedgrid-billing-core` + `seedgrid-billing-stripe`. Lado Java: [[SeedGrid/Extensions/billing/Visao-geral|Visão geral do billing (Java)]] · [[SeedGrid/Extensions/billing/Configuracao|Configuração do billing (Java)]]. Configuração Rust: [[SeedGrid/Extensions/billing/Configuracao-Rust|Configuração Rust do billing]].
+
+Domínio de billing independente de provedor (planos, assinaturas, uso), SPI de provedor, `BillingEventHandler` do host, dispatcher de webhook idempotente, router Axum (checkout/portal/webhook) e backend Stripe (cliente `reqwest` + verificação de assinatura). **Confirmado** (`src/lib.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-billing` (lib `seedgrid_billing`) |
+| Versão | workspace `2026.10.14` |
+| Features | `postgres` (default; `sqlx`, repositório e migrations), `stripe` (default; `reqwest`, `hmac`, `sha2`, `hex`) |
+| Dependência SeedGrid | `seedgrid-rust-crate-resilience` (rate limit) |
+| Consumidores | login-tenancy, subdomain-tenancy (doc de `src/lib.rs`) |
+
+## API pública principal
+| Símbolo | Papel | Fonte |
+|---|---|---|
+| `BillingService::new(Arc<dyn BillingProvider>)` | fachada: `create_checkout`, `create_portal`, `process_webhook`, `change_subscription_plan`, `cancel_subscription(_immediately)`, `pause/resume/reactivate_subscription`, `list_invoices`, `get_upcoming_invoice`, `get_subscription`, `preview_plan_change`… | `src/service.rs` |
+| traits `BillingProvider`, `BillingCatalogProvider`, `BillingUsageProvider` | SPI; capacidades detectadas por `as_catalog()`/`as_usage()` (equivalente ao `instanceof` do Java) | `src/spi.rs` |
+| trait `BillingEventHandler` | lógica de domínio do host para eventos | `src/spi.rs` |
+| `BillingEventDispatcher::new(service, repo, Option<handler>)` | idempotência por `(provider, event_id)` | `src/dispatcher.rs` |
+| `BillingApiState::new` / `::builder(..).authorizer(..).build()` | estado do router; guard default `AllowAllBillingAuthorizer` | `src/state.rs` |
+| `router(state)` | rotas abaixo | `src/routes.rs` |
+| `checkout_rate_limit()`, `portal_rate_limit()`, `webhook_rate_limit()` | `SeedGridRateLimit` (`billing-checkout` 30/min, `billing-portal` 30/min, `billing-webhook` 300/min) para o host acoplar o middleware do resilience | `src/routes.rs` |
+| `stripe::StripeBillingProvider::new(StripeConfig)` | backend Stripe; Test Clock em chaves `sk_test` | `src/stripe/provider.rs` |
+| `stripe::ensure_product_bootstrap` | garante o produto base no startup (opt-in por `product`) — o host precisa chamar | `src/stripe/bootstrap.rs` |
+| `BillingPlatform::assemble(Option<&PgPool>, BillingOverrides)` | montagem "estilo CDI": exige Postgres **e** `api_key` Stripe; roda migrations | `src/platform.rs` (features `postgres`+`stripe`) |
+| `migrate` / `MIGRATOR` | `0500_create_billing_events.sql`, `0501_add_permissions.sql`; histórico `_sqlx_migrations_billing` | `src/lib.rs` |
+| `openapi()` | spec utoipa | `src/apidoc.rs` |
+
+Permissões (constantes em `src/state.rs`): `BILLING_CHECKOUT_CREATE`, `BILLING_PORTAL_CREATE`, `BILLING_SUBSCRIPTION_READ`.
+
+## Endpoints
+| Método | Path | Permissão |
+|---|---|---|
+| POST | `/billing/checkout` | `BILLING_CHECKOUT_CREATE` |
+| POST | `/billing/portal` | `BILLING_PORTAL_CREATE` |
+| GET | `/billing/subscription` | `BILLING_SUBSCRIPTION_READ` — **só no Rust** (extensão deliberada) |
+| POST | `/public/billing/webhook` | público (assinatura do Stripe) |
+
+## Exemplo (doc de `src/lib.rs`)
+```rust
+use std::sync::Arc;
+use seedgrid_billing::{
+    migrate, BillingService, BillingEventDispatcher, BillingApiState, router,
+    PgBillingEventRepository, config::StripeConfig, stripe::StripeBillingProvider,
+};
+
+migrate(&pool).await?;
+let provider = Arc::new(StripeBillingProvider::new(StripeConfig::from_env()));
+let service = BillingService::new(provider);
+let repo = Arc::new(PgBillingEventRepository::new(pool));
+let dispatcher = BillingEventDispatcher::new(service.clone(), repo, /* handler */ None);
+let app = router(BillingApiState::new(service, dispatcher));
+```
+Alternativa: `BillingPlatform::assemble(Some(&pool), BillingOverrides { event_handler: Some(handler) })`. Não há app em `rust/examples/` para billing.
+
+## Testes
+- Unitários em `src/*` (inclui teste de alias `STRPE` em `config.rs` e `ensure_product` no provider).
+- `tests/pg_billing_events_it.rs` (`#[ignore]`, `BILLING_IT_PG_URL`); `tests/stripe_transport_it.rs` (`BILLING_STRIPE_IT_BASE`, `BILLING_STRIPE_IT_KEY`).
+- **Não executados.**
+
+## Limitações
+
+- A rota `GET /billing/subscription` existe só no Rust.
+- O `seedgrid-billing-core` Java tem grupos de configuração (`seedgrid.billing.trial`, `.catalog`, `.checkout`, `.portal`, `.access-gate`, `.feature-gate`, `.reconciliation`, `.api`, `.plan-term.additional-attributes`, `business-timezone`, `currency`, `overage-meter-name`, `persistence-unit`) que **não têm contraparte** em `src/config.rs` do Rust (Confirmado).
+
+## Enums
+Equivalentes Java: [[SeedGrid/Extensions/billing/Enums|Enums do billing (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `BillingEventType` | `src/domain.rs` | [[SeedGrid/Extensions/billing/Enums#BillingEventType\|BillingEventType]] |
+| `RecurringInterval` | `src/dtos.rs` | [[SeedGrid/Extensions/billing/Enums#RecurringInterval\|RecurringInterval]] |
+| `AggregationFormula` | `src/dtos.rs` | [[SeedGrid/Extensions/billing/Enums#AggregationFormula\|AggregationFormula]] |
+| `TiersMode` | `src/dtos.rs` | [[SeedGrid/Extensions/billing/Enums#TiersMode\|TiersMode]] |
+| `BillingError` | `src/error.rs` | exceções do billing |
+| `HttpMethod` (`Get`, `Post`, `Delete`) | `src/stripe/transport.rs` | interno do transporte Stripe |
+
+### BillingEventType
+`#[serde(rename_all = "SCREAMING_SNAKE_CASE")]`; `name()` = nome Java; é o valor da coluna `billing_events.type VARCHAR(50)` (sem CHECK). Mapeamento do Stripe (`stripe/translate.rs` → `map_event_type`):
+
+| Valor | Evento Stripe |
+|---|---|
+| `CheckoutCompleted` (`CHECKOUT_COMPLETED`) | `checkout.session.completed` |
+| `PaymentConfirmed` (`PAYMENT_CONFIRMED`) | `invoice.paid` |
+| `PaymentFailed` (`PAYMENT_FAILED`) | `invoice.payment_failed` |
+| `SubscriptionCreated` (`SUBSCRIPTION_CREATED`) | `customer.subscription.created` |
+| `SubscriptionUpdated` (`SUBSCRIPTION_UPDATED`) | `customer.subscription.updated` |
+| `SubscriptionCanceled` (`SUBSCRIPTION_CANCELED`) | `customer.subscription.deleted` |
+| `RefundCreated` (`REFUND_CREATED`) | `charge.refunded` |
+| `DisputeOpened` (`DISPUTE_OPENED`) | `charge.dispute.created` |
+
+Qualquer outro tipo de evento → `BillingError::UnsupportedEvent` (o webhook responde 204). Os 8 valores são **iguais** aos do Java.
+
+### RecurringInterval / AggregationFormula / TiersMode
+`#[serde(rename_all = "UPPERCASE")]`. `RecurringInterval` = `DAY`, `WEEK`, `MONTH`, `YEAR` (Stripe `day`/`week`/`month`/`year`; ausente → `MONTH`). `AggregationFormula` = `SUM`, `COUNT`, `LAST` (ausente → `SUM`; `LAST` é mapeado para `sum` no Stripe, lacuna herdada do Java). `TiersMode` = `GRADUATED`, `VOLUME`. Valores iguais ao Java.
+
+### BillingError
+`Unsupported`, `InvalidWebhook` (400 no webhook), `UnsupportedEvent` (204), `Provider` (500), `Forbidden` (403), `Config`, `Json`, `Database` (feature `postgres`), `Internal`.

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

@@ -0,0 +1,181 @@
+---
+tags: [seedgrid, extension, billing, quarkus]
+fonte: java/seedgrid-quarkus-ext-billing
+branch: main
+commit: ba38efc347
+analisado-em: 2026-10-14
+---
+
+# Billing (Quarkus): visão geral
+
+Assinaturas prontas para hosts Quarkus. Cobre planos, condições comerciais (terms), trial, checkout, portal do cliente, troca de plano, cancelamento, ciclo de cobrança, contadores de uso (franquia e excedente por contador) e webhook. Tudo é exposto em endpoints REST da própria extension. O gateway de pagamento fica atrás da SPI `BillingProvider`, e há um provider pronto para **Stripe**.
+
+- Configuração: [[SeedGrid/Extensions/billing/Configuracao|Configuração do billing]]
+- Exemplos: [[SeedGrid/Extensions/billing/Exemplos|Exemplos do billing]]
+- Enums: [[SeedGrid/Extensions/billing/Enums|Enums do billing]]
+- Porte Rust: [[SeedGrid/Extensions/billing/Rust|Porte Rust]]
+
+> Segundo o README, "o host não conhece billing": ele adiciona a dependência e configura `seedgrid.billing.*`. Não escreve controller, entity, migration nem handler de webhook. Se cobra por uso, declara os contadores (`UsageMeterContributor`) e marca onde contar (`@ConsumesUsage`). **Confirmado** (README e `integration-tests`, que sobem um app sem nenhuma classe de billing própria).
+
+## Módulos Maven e coordenadas
+
+Agregador: `br.com.seedgrid:seedgrid-billing:2026.10.14-1` (parent `br.com.seedgrid:seedgrid-parent:2026.07.02`).
+
+| Submódulo | Parent | Artefatos | Papel |
+|---|---|---|---|
+| `seedgrid-billing-core` | `seedgrid-billing-parent:2026.10.14-1` | runtime `seedgrid-billing-core`, deployment `seedgrid-billing-core-deployment`, `integration-tests` (não publicado) | modelo, REST, regras, SPIs, migrations |
+| `seedgrid-billing-stripe` | `seedgrid-billing-stripe-parent:2026.10.14-1` | runtime `seedgrid-billing-stripe`, deployment `seedgrid-billing-stripe-deployment`, `integration-tests` | `StripeBillingProvider` (stripe-java `26.12.0`) e `StripeProductBootstrap` |
+
+O groupId é sempre `br.com.seedgrid`. As features Quarkus são `seedgrid-billing-core` e `seedgrid-billing-stripe`, declaradas em `SeedgridBillingProcessor` e `SeedgridBillingStripeProcessor`.
+
+### Dependências SeedGrid (runtime do core)
+
+| Artefato | Versão no pom | Para quê |
+|---|---|---|
+| `seedgrid-security` | 2026.10.08 | `Company`, `User`, `Permission`, `@PlatformScope`, `UserService.deactivateUserInCompany` |
+| `seedgrid-commons` | 2026.10.08 | `ApiExceptionExtension`, `ProblemType`, `BaseEntity` |
+| `seedgrid-audit-core` | 2026.09.25 | `@Audit` em serviços administrativos |
+| `seedgrid-privacy` | 2026.07.27 | dependência declarada (uso específico não investigado) |
+| `seedgrid-resilience-core` | 2026.07.08 | `@SeedGridRateLimit` no webhook, checkout e portal |
+| `seedgrid-notification-api` | 2026.10.08 (`seedgrid.notification.version`) | catálogo e publicação dos eventos `billing.*` |
+
+Também depende do Quarkus: `arc`, `hibernate-orm`, `jdbc-postgresql`, `flyway`, `rest-jackson`, `hibernate-validator` e `smallrye-openapi`.
+
+**Quem depende do billing:** `login-tenancy` e `subdomain-tenancy` (o billing não conhece nenhum deles). Ver [[SeedGrid/Extensions/login-tenancy/Visao-geral|login-tenancy]] e [[SeedGrid/Extensions/subdomain-tenancy/Visao-geral|subdomain-tenancy]].
+
+## Arquitetura
+
+```mermaid
+flowchart LR
+    Client -->|/me/*, /admin/*| REST[Controllers do core]
+    REST --> SVC[Services: Plan, Trial, Checkout, SubscriptionChange, Usage...]
+    SVC --> BS[BillingService]
+    BS --> SPI{{BillingProvider SPI}}
+    SPI --> STRIPE[StripeBillingProvider]
+    Stripe((Stripe)) -->|POST /public/billing/webhook| WH[BillingWebhookController]
+    WH --> SPI
+    WH --> H[SubscriptionBillingEventHandler]
+    SVC --> DB[(tabelas billing via BillingEntityManager)]
+    SVC -. eventos CDI .-> OBS[Observers do host / notification]
+```
+
+Pacotes de `br.com.seedgrid.billing`:
+
+| Pacote | Conteúdo |
+|---|---|
+| `annotations` | `@ConsumesUsage`, `@RequiresPlanFeature` |
+| `configs` | `BillingConfig`, mais um `@ConfigMapping` por grupo e `BusinessTimeZone` |
+| `controllers` | `AdminPlan`, `AdminSubscription`, `AdminAccount`, `AdminBilling`, `Subscription`, `PlanCatalog`, `Usage`, `MeBilling`, `BillingWebhook`, `RestControllerPath` |
+| `filters` | `BillingApiToggleFilter` (api.enabled), `AccessGateFilter` (bloqueio geral), `BillingApiOpenApiFilter` |
+| `interceptors` | interceptors das duas anotações |
+| `repositories` | JPA puro sobre `BillingEntityManager` |
+| `services` | regras de negócio |
+| `spis` (+`impl`) | pontos de extensão |
+| `notifications` | `BillingNotificationCatalog`, `BillingLifecycleNotificationObserver`, `UserAccessEmailObserver` |
+
+No **build**, o deployment coleta todo `@ConsumesUsage` e cria o bean sintético `ConsumesUsageSites`. No **startup**, `UsageMeterCatalog` recusa um contador não declarado e informa o método na mensagem. **Confirmado** (`SeedgridBillingProcessor#consumesUsageSites`).
+
+Modelo: `Plan` 1:N `PlanTerm` 1:N `PlanTermMeter`. `Account` 1:N `Subscription` (N:1 `PlanTerm`) 1:N `BillingCycle` 1:N `BillingCycleMeter`. `Account` 1:N `Purchase`. **Confirmado** (`entities/`).
+
+## APIs públicas e pontos de integração
+
+### Anotações
+- `@ConsumesUsage(meter = "...", units = 1)`: checa antes da execução e contabiliza só se o método retornar normalmente. O `meter` é obrigatório.
+- `@RequiresPlanFeature(value = "PERMISSAO", message = "")`: responde 402 `FEATURE_NOT_IN_PLAN` (ou `TRIAL_EXPIRED`).
+
+### SPIs (todas com default `@DefaultBean`, exceto o provider)
+| SPI | Default | Assinatura principal |
+|---|---|---|
+| `BillingProvider` | — (fornecido por `seedgrid-billing-stripe`) | `createCheckout`, `createPortal`, `parseAndVerifyWebhook`, `changeSubscriptionPlan(..., List<String> newMeteredPriceIds)`, ... |
+| `BillingCatalogProvider` | — (opcional; Stripe implementa) | `createPrice`, `ensureProduct`, `archivePrice`, ... |
+| `BillingUsageProvider` | — (opcional; Stripe implementa) | `ensureMeter`, `createMeteredPrice`, `reportUsage` |
+| `UsageMeterContributor` | nenhum contador | `List<UsageMeterDefinition> meters()` (`record UsageMeterDefinition(String code, String label)`) |
+| `PlanTermAdditionalFieldsValidator` | `DefaultPlanTermAdditionalFieldsValidator` | `validate(PlanTerm, Map<String, JsonNode>)` |
+| `PlanTermUsageChecker` | `DefaultPlanTermUsageChecker` | `isInUse(Collection<Long>)` |
+| `CurrentAccountResolver` | `DefaultCurrentAccountResolver` | `requireCurrentUser()`, `requireCurrentAccount()`, `billingContactEmail()` |
+| `AccountMembersGateway` | `CompanyAccountMembersGateway` | `activeUsers`, `isResponsible`, `deactivate`, `findByPublicIds` |
+| `BillingAccountScope` | `UnrestrictedBillingAccountScope` | `Optional<Set<Long>> visibleCompanyIds()` |
+| `BillingEventHandler` | `SubscriptionBillingEventHandler` | `handle(BillingEvent)` |
+
+> **Inferência:** um host precisa de **exatamente um** bean `BillingProvider`. `BillingService` o injeta direto, e os testes usam dublês (`NoopBillingProvider`, `FakeBillingProvider`). Sem o módulo Stripe nem provider próprio, a injeção ficaria insatisfeita. Não executei para confirmar.
+
+### Serviço programático
+`UsageService#assertCanConsume(Account, String meter, int units)` e `UsageService#consume(Account, String meter, int units, String idempotencyKey)`. O `consume` é `@Transactional` e retorna `UsageConsumedEvent`.
+
+### Endpoints REST (`RestControllerPath`)
+| Método | Caminho | Acesso |
+|---|---|---|
+| GET/POST | `/admin/plans` | plataforma + `PLAN_READ`/`PLAN_CREATE` |
+| GET/PUT/DELETE | `/admin/plans/{planId}` | plataforma + `PLAN_*` |
+| GET/POST | `/admin/plans/{planId}/terms` | plataforma + `PLAN_TERM_*` |
+| PATCH/DELETE | `/admin/plans/{planId}/terms/{termId}` | plataforma + `PLAN_TERM_*` |
+| POST | `/admin/plans/{planId}/terms/{termId}/publish`, `/archive` | plataforma + `PLAN_TERM_*` |
+| GET/PATCH | `/admin/plans/trial` | plataforma + `PLAN_TERM_*` |
+| GET/POST | `/admin/subscriptions` | plataforma + `SUBSCRIPTION_*` |
+| GET | `/admin/accounts`, `/admin/accounts/{accountId}`, `/admin/accounts/options`, `/admin/accounts/{accountId}/history` | plataforma + `ACCOUNT_READ`/`ACCOUNT_OPTIONS_READ` |
+| POST | `/admin/accounts/{accountId}/grant-units`, `/grant-trial-days` | plataforma + `ACCOUNT_GRANT_USAGE` |
+| GET | `/admin/billing/meters`, `/admin/billing/overview` | plataforma |
+| GET | `/me/subscription`, `/me/plans`, `/me/usage` | autenticado |
+| GET/POST | `/me/billing/checkout`, `/me/billing/checkout/preview` | autenticado |
+| POST | `/me/billing/portal`, `/change-plan`, `/cancel`, `/reactivate`, `/cancel-scheduled-change`, `/trial-ended` | autenticado |
+| GET | `/me/billing/change-preview`, `/invoices`, `/upcoming` | autenticado |
+| GET/PUT | `/me/billing/downgrade-user-selection` | autenticado |
+| POST | `/public/billing/webhook` | pública (assinatura do provider) |
+
+Os caminhos são **Confirmados** em `RestControllerPath`. As permissões vêm do README. Com `seedgrid.billing.api.enabled=false`, todos os prefixos exceto o webhook respondem 404 e somem do OpenAPI (`RestControllerPath.API_PREFIXES`).
+
+Rate limit via resilience (**Confirmado**, `@SeedGridRateLimit`):
+
+| configKey | Endpoint | Limite |
+|---|---|---|
+| `billing-webhook` | webhook | 300/min |
+| `billing-checkout` | `POST /me/billing/checkout` | 30/min |
+| `billing-portal` | `POST /me/billing/portal` | 30/min |
+
+### Eventos CDI
+| Evento | Tipos | Observação |
+|---|---|---|
+| `SubscriptionLifecycleEvent` | `ACTIVATED, UPGRADED, DOWNGRADE_SCHEDULED, DOWNGRADE_CANCELED, CANCELLATION_REQUESTED, CANCELED, REACTIVATED, PAST_DUE, TRIAL_ENDED` | Disparado dentro da transação. Após o commit, a extension publica `billing.*` no notification. |
+| `UserAccessEvent` | `LOSS_SCHEDULED, LOSS_APPLIED, RESTORED` | A extension envia o e-mail (templates `templates/billing-default/`, sobrescrevíveis em `templates/billing/`). |
+| `UsageConsumedEvent` | — | Um por consumo contabilizado, com o `meter`. |
+
+### Stripe (`seedgrid-billing-stripe`)
+- `StripeBillingProvider` implementa `BillingProvider`, `BillingCatalogProvider` e `BillingUsageProvider`.
+- Mapeia os eventos Stripe para `BillingEventType`: `checkout.session.completed`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.created/updated/deleted`, `charge.refunded`, `charge.dispute.created`.
+- Com chave `sk_test*`, cria customers presos a um Test Clock (desligável).
+- `StripeProductBootstrap` garante o produto base no startup (best-effort).
+
+## Migrations
+`db/migration/billing`, de **V500 a V513** (tabela de histórico default `flyway_schema_history_billing`):
+
+| Versão | Conteúdo |
+|---|---|
+| V500 | `billing_events` |
+| V501 | permissões de checkout/portal |
+| V502 | `accounts`, `plans`, `plan_terms` |
+| V503 | timestamps com fuso |
+| V504 | `max_users`, `plan_term_permissions` |
+| V505 | plano/term TRIAL com IDs fixos |
+| V506 | `trial_days` |
+| V507 | `additional_attributes jsonb` |
+| V508 | colunas `BaseEntity` |
+| V509 | `tenant_subscriptions`, `subscription_billing_cycles`, `billing_purchases` |
+| V510 | permissões `PLAN_*`, `PLAN_TERM_*`, `SUBSCRIPTION_*` |
+| V511 | `billing_account_history`, permissões `ACCOUNT_*` |
+| V512 | audiences |
+| V513 | `plan_term_meters`, `billing_cycle_meters` |
+
+**Confirmado** (arquivos SQL e README do core).
+
+## Testes (não executados)
+- `seedgrid-billing-core/runtime/src/test`: unitários Mockito sem Quarkus. Cobrem services (`UsageServiceTest`, `SeatServiceTest`, `TrialEndedNotifierTest`, `PlanPublicationServiceTest`...), filtros (`AccessGateFilterTest`, `BillingApiToggleFilterTest`, `BillingPathsTest`), `BillingEntityManagerTest` e notificações.
+- `seedgrid-billing-core/integration-tests`: PostgreSQL via Testcontainers. Cobrem `SubscriptionFlowTest`, `UsageTest`, `FeatureGateTest`, `AccessGateEnabledTest`, `ApiDisabledTest`, `AdminAccountTest`, `AdminAccountScopeTest`, `AdminPlanTest`, `BillingOverviewTest`, `LegacyHostSchemaMigrationTest`, entre outros.
+- `deployment/src/test`: smoke (`SeedgridBillingTest`, `SeedgridBillingDevModeTest`, `SeedgridBillingStripeTest`...).
+- `seedgrid-billing-stripe/runtime/src/test`: `StripeBillingProviderTest`.
+
+## Limitações
+- Colunas antigas (`plan_terms.overage_price`, `provider_overage_price_id`, `subscription_billing_cycles.*_units`) continuam no banco, **inertes**, até o seedgrid-report migrar os dados (CHANGELOG 2026.10.08).
+- O billing depende da security. Com Flyway nativo, o host precisa listar `db/migration/security` e `db/migration/billing` (comentário em `deployment/src/test/resources/application.properties`).
+- O `microprofile-config.properties` do core redefine `quarkus.flyway.*` com ordinal 100. Ver [[SeedGrid/Extensions/billing/Configuracao|Configuração]], seção de frameworks.
+- Os assuntos dos e-mails de acesso estão fixos em código, com "SeedGrid App" (`UserAccessEmails`). Não há propriedade para mudá-los.
+- Não há job de expiração de trial: a verificação acontece a cada chamada.

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

@@ -0,0 +1,40 @@
+---
+tags: [seedgrid, extension, broker, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-broker
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# broker — Configuração Rust
+
+Visão geral: [[SeedGrid/Extensions/broker/Visao-geral|Visão geral do broker]]. Não há equivalente Java.
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Mecanismo | **argumentos de construtor e structs** passados pelo host; as crates **não leem variáveis de ambiente** (`grep` por `env::var` em `crates/` sem resultado — **Confirmado**) |
+| Seleção de backend | feita pelo host (ex.: `BROKER_PROVIDER` no `seedgrid-pulse` e no exemplo) |
+| Leitura | na construção do broker |
+| Features Cargo | nenhuma em nenhuma das 5 crates |
+
+## Parâmetros por backend
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `MemoryBroker::new(capacity)` | usize | ≥ 1 (0 vira 1) | `512` (`Default`) | Não | capacidade do `broadcast`; assinante atrasado além disso deixa de receber | `MemoryBroker` | buffer do `mpsc` por assinante é fixo em 512 | construtor | `crates/seedgrid-broker-memory/src/lib.rs` |
+| `RedisBroker::connect(url, _)` | &str | URL `redis://` / `rediss://` aceita pelo crate `redis` | — | Sim | conecta e faz `PING` (falha → erro) | `RedisBroker` | — | construtor | `crates/seedgrid-broker-redis/src/lib.rs` |
+| `RedisBroker::connect(_, channel)` | &str | nome de canal | — | Sim | canal único de PUBLISH/SUBSCRIBE; vazio só é rejeitado pela função livre `connect` | idem | — | construtor | idem |
+| `NatsConfig.url` / `NatsConfig.subject` | String | — | sem `Default` | Sim (struct) | apenas armazenados (scaffold) | uso não encontrado | — | `NatsBroker::connect` | `crates/seedgrid-broker-nats/src/lib.rs` |
+| `RabbitMqConfig.url` / `.exchange` / `.routing_key` | String | — | sem `Default` | Sim (struct) | apenas armazenados (scaffold) | uso não encontrado | — | `RabbitMqBroker::connect` | `crates/seedgrid-broker-rabbitmq/src/lib.rs` |
+
+## Variáveis de ambiente do host/exemplo (não lidas pelas crates)
+| Variável | Valores | Padrão no exemplo | Onde |
+|---|---|---|---|
+| `BROKER_PROVIDER` | `memory`, `redis` (outro → erro) | `memory` | `rust/examples/seedgrid-broker-example/src/main.rs` → `build_broker` |
+| `BROKER_REDIS_URL` | URL Redis | `redis://localhost:6379` | idem |
+| `BROKER_REDIS_CHANNEL` | nome de canal | `seedgrid` | idem |
+| `RUST_LOG` | filtro `tracing` | — | idem |
+
+## Receitas
+- **Testes/dev**: `Arc::new(MemoryBroker::default())`.
+- **Produção (várias instâncias)**: `RedisBroker::connect("redis://<host>:6379", "<canal>")`; todas as instâncias devem usar o mesmo canal.

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

@@ -0,0 +1,114 @@
+---
+tags: [seedgrid, extension, broker, rust]
+fonte: rust/seedgrid-rust-crate-broker
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# broker — Visão geral (só Rust)
+
+Abstração de **mensageria pub/sub** da plataforma SeedGrid. Define um contrato único (`Broker`) e backends que o implementam; o host programa contra o trait e escolhe o backend na composição (por configuração dele). **Não existe extensão Java equivalente** (**Confirmado**: não há `seedgrid-quarkus-ext-broker` em `java/`). Configuração: [[SeedGrid/Extensions/broker/Configuracao-Rust|Configuração Rust do broker]].
+
+Caso de uso principal: o produto `seedgrid-pulse` (fora do `seedgrid-platform`), que escolhe o backend por `BROKER_PROVIDER`.
+
+## Crates (sub-workspace)
+Diretório `rust/seedgrid-rust-crate-broker/crates/`; as 5 crates são membros do workspace raiz `rust/Cargo.toml` e herdam `version` (`2026.10.14`), `edition` (**2024**), `license` (`MIT`), `authors` e dependências de `[workspace.package]`/`[workspace.dependencies]`. Não há `Cargo.toml` próprio na raiz de `seedgrid-rust-crate-broker` (era um workspace aninhado, absorvido — comentário em `rust/Cargo.toml`).
+
+| Crate | Papel | Estado (**Confirmado** no código) |
+|---|---|---|
+| `seedgrid-broker-spi` | contrato: `Broker`, `BrokerMessage`, `BackendKind`, `BrokerReceiver`, `DynBroker` | estável |
+| `seedgrid-broker-memory` | backend in-process (`tokio::sync::broadcast`) | funcional |
+| `seedgrid-broker-redis` | backend Redis Pub/Sub (canal RESP único) | funcional |
+| `seedgrid-broker-nats` | `NatsConfig` + `NatsBroker` | **scaffold**: `publish`/`subscribe` retornam erro "ainda nao foi implementado" |
+| `seedgrid-broker-rabbitmq` | `RabbitMqConfig` + `RabbitMqBroker` | **scaffold**: idem |
+
+Nenhuma crate tem features Cargo ou dependência de outras crates SeedGrid além do SPI.
+
+## Contrato (`crates/seedgrid-broker-spi/src/lib.rs`)
+```rust
+pub type BrokerReceiver = mpsc::Receiver<BrokerMessage>;
+pub type DynBroker = Arc<dyn Broker>;
+
+pub struct BrokerMessage {
+    pub topic: String,
+    pub payload: Vec<u8>,
+    pub headers: BTreeMap<String, String>, // #[serde(default)]
+    pub key: Option<String>,               // omitido no JSON quando None
+}
+// BrokerMessage::new(topic, payload).with_header(k, v).with_key(k)
+
+pub enum BackendKind { Memory, Redis, Nats, RabbitMq }
+
+#[async_trait]
+pub trait Broker: Send + Sync {
+    fn backend_kind(&self) -> BackendKind;
+    async fn publish(&self, message: BrokerMessage) -> Result<()>;   // anyhow::Result
+    async fn subscribe(&self) -> Result<BrokerReceiver>;
+}
+```
+
+## Fluxo
+```mermaid
+sequenceDiagram
+    participant C as Consumidor (host)
+    participant B as Broker
+    participant I as Infra (Redis)
+    participant P as Produtor (host)
+    C->>B: subscribe() -> BrokerReceiver (mpsc 512)
+    B->>I: SUBSCRIBE <canal>
+    P->>B: publish(BrokerMessage)
+    B->>I: PUBLISH <canal> <json>
+    I-->>B: mensagem
+    B-->>C: BrokerMessage (host filtra por topic)
+```
+- **Canal único**: o `subscribe()` entrega **todas** as mensagens; `topic` é só um campo para roteamento no host, não um filtro do backend.
+- Só chega o que foi publicado **depois** da inscrição (memory e redis).
+
+## Comportamento por backend
+| Backend | Detalhes (**Confirmado**) |
+|---|---|
+| memory | `MemoryBroker::new(capacity)` (mínimo 1; `Default` = 512). `publish` ignora a falta de inscritos (mensagem descartada, `Ok(())`). Cada `subscribe` cria uma task que repassa para um `mpsc` de 512. Se o assinante ficar para trás além da capacidade, `broadcast::Receiver::recv` retorna `Lagged` e o laço `while let Ok(..)` **termina** — a assinatura para de entregar sem erro (**Inferência** a partir da API do tokio; comportamento não testado no repositório). |
+| redis | `RedisBroker::connect(url, channel)` abre o cliente e faz `PING`. `publish` serializa a mensagem em JSON (`serde_json`) e faz `PUBLISH` no canal. `subscribe` (serializado por mutex) abre um pubsub, assina o canal e repassa a um `mpsc` de 512; payloads que não decodificam são logados (`warn`) e descartados; fim do stream encerra a task. A função livre `seedgrid_broker_redis::connect(url, channel)` valida canal não vazio; `RedisBroker::connect` **não** valida. |
+| nats / rabbitmq | `connect(config)` só guarda a config; `publish`/`subscribe` falham. |
+
+## Exemplo (de `rust/examples/seedgrid-broker-example/src/main.rs`)
+```rust
+async fn build_broker() -> Result<DynBroker> {
+    let provider = std::env::var("BROKER_PROVIDER").unwrap_or_else(|_| "memory".to_string());
+    match provider.as_str() {
+        "memory" => Ok(Arc::new(MemoryBroker::default())),
+        "redis" => {
+            let url = std::env::var("BROKER_REDIS_URL").unwrap_or_else(|_| "redis://localhost:6379".to_string());
+            let channel = std::env::var("BROKER_REDIS_CHANNEL").unwrap_or_else(|_| "seedgrid".to_string());
+            Ok(Arc::new(RedisBroker::connect(&url, &channel).await?))
+        }
+        other => anyhow::bail!("BROKER_PROVIDER desconhecido: {other} (use memory|redis)"),
+    }
+}
+
+let mut rx = broker.subscribe().await?;          // assinar ANTES de publicar
+broker.publish(BrokerMessage::new("pedidos.criado", br#"{"id":1}"#.to_vec())).await?;
+let msg = rx.recv().await;
+```
+A leitura de env acima é do **exemplo**, não das crates.
+
+## Testes
+- Unitário: `publishes_to_subscribers` em `crates/seedgrid-broker-memory/src/lib.rs`.
+- Nenhum teste nas crates redis/nats/rabbitmq/spi.
+- E2E Testcontainers: `rust/examples/seedgrid-broker-example/tests/broker_e2e.rs` (memória + Redis).
+- **Não executados.**
+
+## Limitações
+- NATS e RabbitMQ sem implementação.
+- Sem reconexão automática no Redis (fim do stream encerra a assinatura).
+- Sem garantia de entrega (pub/sub puro; perde mensagens sem assinante).
+
+## Enums
+Sem equivalente Java (módulo só Rust).
+
+| Enum | Arquivo | Variantes |
+|---|---|---|
+| `BackendKind` | `crates/seedgrid-broker-spi/src/lib.rs` | `Memory`, `Redis`, `Nats`, `RabbitMq` |
+
+`BackendKind` é devolvido por `Broker::backend_kind()` e não é serializado (sem serde); `Nats` e `RabbitMq` só são retornados pelos esqueletos, cujos `publish`/`subscribe` falham. A escolha do backend (`BROKER_PROVIDER=memory|redis` no exemplo) é texto do host, não este enum.

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

@@ -0,0 +1,73 @@
+---
+tags: [seedgrid, extension, cache, rust, configuracao]
+fonte: rust/seedgrid-rust-crate-cache
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# cache — Configuração Rust
+
+Visão do crate: [[SeedGrid/Extensions/cache/Rust|Porte Rust do cache]] · Java: [[SeedGrid/Extensions/cache/Configuracao|Configuração do cache (Java)]].
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Struct | `CacheConfig` (+ enum `ProviderDownLog`) — `rust/seedgrid-rust-crate-cache/src/config.rs` |
+| Mecanismo | `CacheConfig::from_env()`, `CacheConfig::new(hosts)` ou literal; passada a `RedisCache::connect` / `CacheBackend::Distributed` |
+| Prefixo Java | `seedgrid.cache.*` (fachada que faz alias de `quarkus.redis.*` via `RelocateConfigSourceInterceptor`) |
+| Precedência | `SEEDGRID_CACHE_<X>` > `QUARKUS_REDIS_<X>` (exceto `IF_PROVIDER_IS_DOWN`, sem fallback) — `alias_resolve` |
+| Leitura | quando o host chama `from_env()`; no workspace, só o exemplo `seedgrid-cache-example` chama |
+| Backend in-memory | sem configuração |
+
+Valores são `trim`ados; vazio conta como ausente (`alias_resolve`).
+
+## Variáveis de ambiente
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_CACHE_HOSTS` / fallback `QUARKUS_REDIS_HOSTS` (Java `seedgrid.cache.hosts` / `quarkus.redis.hosts`) | String | `host:porta`, `redis://...`, `rediss://...`; lista por vírgula (só o 1º é usado) | `localhost:6379` | Não | montado em URL por `redis_url()` (prefixa `redis://` se faltar esquema) | `RedisCache::connect` | `password` | `from_env()` | `config.rs` → `from_env`, `redis_url`; `redis_backend.rs` → `connect` |
+| 🔒 `SEEDGRID_CACHE_PASSWORD` / `QUARKUS_REDIS_PASSWORD` | `Option<String>` | texto | — | Não | injetada como `:<senha>@` na URL se ela ainda não tiver `@` | `redis_url()` | `hosts` | `from_env()` | `config.rs` |
+| `SEEDGRID_CACHE_TIMEOUT` / `QUARKUS_REDIS_TIMEOUT` | `Option<Duration>` | número = segundos; `Nms`, `Ns`, `Nm`; `PTnS`/`PTnM` | — | Não | timeout de conexão **e** de resposta; inválido → ignorado | `RedisCache::connect` | — | `from_env()` | `config.rs` → `parse_duration`; `redis_backend.rs` |
+| `SEEDGRID_CACHE_IF_PROVIDER_IS_DOWN` (Java `seedgrid.cache.if-provider-is-down`) | `ProviderDownLog` | `WARN`, `ERROR` (case-insensitive); outro → `WARN` | `WARN` | Não | só muda o nível do log; Rust sempre degrada (Java `ERROR` relança) | `RedisCache` (`on_provider_down`) | sem fallback `QUARKUS_REDIS_*` | `from_env()` | `config.rs`; `redis_backend.rs` |
+
+Mapeamento Java: **Confirmado** — o nome `seedgrid.cache.if-provider-is-down` está em `java/seedgrid-quarkus-lib-cache/.../CacheProviderFailSoft.java` (`PROP`); a relação `seedgrid.cache.*` ↔ `quarkus.redis.*` está no interceptor Java (comentários lidos). A conversão para env segue a regra MicroProfile sem ambiguidade.
+
+## Struct `CacheConfig`
+| Campo | Tipo | `Default` |
+|---|---|---|
+| `hosts` | String | `localhost:6379` |
+| `password` | `Option<String>` | `None` |
+| `timeout` | `Option<Duration>` | `None` |
+| `if_provider_is_down` | `ProviderDownLog` | `Warn` |
+
+`RedisCache::connect_url` e `from_connection` ignoram `CacheConfig` e usam `Warn`; `with_provider_down_log` sobrescreve.
+
+## Features Cargo
+| Feature | Padrão | Efeito |
+|---|---|---|
+
+## Somente testes / exemplos
+| Variável | Onde |
+|---|---|
+| `SEEDGRID_CACHE_TEST_URL` | `tests/redis_backend.rs` (default `redis://localhost:6379`) |
+| `RUST_LOG` | exemplo |
+
+## Configuração mínima
+```dotenv
+SEEDGRID_CACHE_HOSTS=localhost:6379
+```
+
+## Configuração completa comentada
+```dotenv
+SEEDGRID_CACHE_HOSTS=redis://<host>:6379     # ou host:porta; rediss:// para TLS
+SEEDGRID_CACHE_PASSWORD=<SEGREDO:redis-password>
+SEEDGRID_CACHE_TIMEOUT=5s                    # 5 | 5s | 500ms | PT5S
+SEEDGRID_CACHE_IF_PROVIDER_IS_DOWN=WARN      # WARN|ERROR (apenas nível de log)
+# Fallback se SEEDGRID_CACHE_* faltar:
+# QUARKUS_REDIS_HOSTS=redis://<host>:6379
+```
+
+## Receitas
+- **Dev/single-node**: não configure nada e use `default_cache()` / `InMemoryCache::new()`.
+- **Redis/Valkey/Dragonfly**: `SEEDGRID_CACHE_HOSTS` + `build(CacheBackend::Distributed { flavor, config: CacheConfig::from_env() })`.
+- **Reaproveitar env de um host Quarkus**: `QUARKUS_REDIS_HOSTS`/`QUARKUS_REDIS_PASSWORD` funcionam como fallback.

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

@@ -0,0 +1,112 @@
+---
+tags: [seedgrid, library, cache, configuracao]
+fonte: java/seedgrid-quarkus-lib-cache
+branch: main
+commit: 14bd916a09
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Cache — Configuração
+
+Voltar: [[SeedGrid/Extensions/cache/Visao-geral|Visão geral do cache]] · [[SeedGrid/Extensions/cache/Exemplos|Exemplos do cache]] · [[SeedGrid/Extensions/cache/Rust|Porte Rust]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos | `seedgrid.cache.*` (próprio + fachada/alias de `quarkus.redis.*`) |
+| Classes de config | Nenhuma `@ConfigMapping`/`@ConfigRoot`. Leitura direta via `ConfigProvider` em `CacheProviderFailSoft`; alias via `SeedGridCacheConfigRelocateInterceptor` (SmallRye `RelocateConfigSourceInterceptor`) |
+| Default embutido | `seedgrid-cache-core/src/main/resources/META-INF/microprofile-config.properties` (ordinal MP padrão 100 → `application.properties` do host, ordinal 250, sobrescreve) |
+| Fase | Runtime. `if-provider-is-down` é relido **a cada falha** do backend (sem cache), logo mudanças de fonte dinâmica valem na hora. O alias vale para qualquer fase em que o interceptor esteja carregado (ver dúvidas) |
+| Seleção de backend | **Não há propriedade**: o provider ativo é o que estiver no classpath (`seedgrid-cache-redis`/`-valkey`/`-dragonfly`); sem nenhum, usa `DefaultSeedGridCache` in-memory |
+
+Mecanismo de leitura investigado: `@ConfigMapping`, `@ConfigRoot`, `@ConfigProperty`, `ConfigProvider`, `microprofile-config.properties`, `META-INF/services`, `application.properties` de testes. Só `CacheProviderFailSoft#level()` lê config diretamente.
+
+## 2. Propriedades próprias
+
+### 2.1 Política de falha do backend
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.cache.if-provider-is-down` | `String` (parse para enum `CacheProviderFailSoft.Level`) | `WARN`, `ERROR` (case-insensitive; qualquer outro valor ou ausência → `WARN`) — ver [[SeedGrid/Extensions/cache/Enums#Level|Level]] | `WARN` (no `microprofile-config.properties` da lib e no `orElse("WARN")` do código) | Não | `WARN`: loga WARN e degrada (`get*` → vazio, `increment` → `0`, `put`/`delete` → no-op); a request continua. `ERROR`: loga ERROR e relança a `RuntimeException` do backend | Lida em toda falha de `getString/getBytes/getLong/putString/putBytes/putLong/increment/delete` dos providers RESP. **Não** afeta `withLock` nem o `DefaultSeedGridCache` | Não é relocada para `quarkus.redis.*` (o relocate só mexe em nomes que começam com `quarkus.redis.`). Equivalente no crate Rust é sempre fail-soft | Runtime (relida a cada falha) | Declaração: `seedgrid-cache-core/.../commons/spi/CacheProviderFailSoft.java` → `PROP`, `level()`; default: `seedgrid-cache-core/src/main/resources/META-INF/microprofile-config.properties`. Consumo: `SeedGridCacheRedis`, `SeedGridCacheValkey`, `SeedGridCacheDragonfly` via `CacheProviderFailSoft.get/run` |
+
+Variável de ambiente: `SEEDGRID_CACHE_IF_PROVIDER_IS_DOWN` — **Inferência** (regra MP; a lib lê o nome exato via `ConfigProvider`, então a regra de conversão do `EnvConfigSource` se aplica sem ambiguidade).
+
+### 2.2 Fachada `seedgrid.cache.*` → `quarkus.redis.*` (alias)
+
+Mecanismo (**Confirmado** em `SeedGridCacheConfigRelocateInterceptor#relocate` e `SeedGridCacheConfigRelocateInterceptorTest`): quando qualquer código pede `quarkus.redis.<sufixo>`, o interceptor procura primeiro `seedgrid.cache.<sufixo>`; se não houver valor, usa `quarkus.redis.<sufixo>`. Portanto **qualquer** propriedade do `quarkus-redis-client` pode ser escrita com o prefixo `seedgrid.cache.`, e `seedgrid.cache.*` tem precedência sobre `quarkus.redis.*` quando ambas existem.
+
+Tipos, valores aceitos e padrões são os do `quarkus-redis-client` (Quarkus 3.30.8) — **não definidos pela SeedGrid**; consulte a documentação do Quarkus. As chaves abaixo são as citadas no código/testes/README da lib:
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.cache.<sufixo>` | conforme `quarkus.redis.<sufixo>` | conforme Quarkus | conforme Quarkus | Não | Alias de `quarkus.redis.<sufixo>`; vence o nome nativo | `quarkus-redis-client` (consumido pelo `RedisDataSource` injetado nos providers) | Fallback: `quarkus.redis.<sufixo>` | A da propriedade Quarkus correspondente | `seedgrid-cache-core/.../config/SeedGridCacheConfigRelocateInterceptor.java` → `relocate(String)`; registro: `META-INF/services/io.smallrye.config.ConfigSourceInterceptor` |
+| `seedgrid.cache.hosts` | conforme `quarkus.redis.hosts` (URIs `redis://host:porta`) | conforme Quarkus | conforme Quarkus (sem valor, o client padrão do Quarkus é usado; dev services podem subir um servidor) | Condicional — necessária em produção quando um provider RESP está no classpath (sem ela o client não aponta para o servidor real). **Inferência** | Endereço do servidor Redis/Valkey/Dragonfly | `RedisDataSource` default | Alias de `quarkus.redis.hosts` | Runtime (Quarkus) | Testes: `SeedGridCacheConfigRelocateInterceptorTest`, `RedisAliasTestResource#start()`, `ValkeyAliasTestResource`, `DragonflyAliasTestResource`; README |
+| `seedgrid.cache.password` 🔒 | conforme `quarkus.redis.password` | — | — | Condicional (servidor com AUTH) | Senha do servidor | `RedisDataSource` | Alias de `quarkus.redis.password` | Runtime (Quarkus) | `SeedGridCacheConfigRelocateInterceptorTest`; `README.md` (`${CACHE_PASSWORD:}`) |
+| `seedgrid.cache.timeout` | conforme `quarkus.redis.timeout` (`Duration`, ex.: `PT5S`) | conforme Quarkus | conforme Quarkus | Não | Timeout do client | `RedisDataSource` | Alias de `quarkus.redis.timeout` | Runtime (Quarkus) | `SeedGridCacheConfigRelocateInterceptorTest`; `README.adoc` |
+| `seedgrid.cache.max-pool-size` | conforme `quarkus.redis.max-pool-size` (int) | conforme Quarkus | conforme Quarkus | Não | Tamanho do pool | `RedisDataSource` | Alias de `quarkus.redis.max-pool-size` | Runtime (Quarkus) | `SeedGridCacheConfigRelocateInterceptorTest`; `README.md`, `README.adoc` |
+| `seedgrid.cache.max-pool-waiting` | conforme `quarkus.redis.max-pool-waiting` (int) | conforme Quarkus | conforme Quarkus | Não | Fila de espera do pool | `RedisDataSource` | Alias de `quarkus.redis.max-pool-waiting` | Runtime (Quarkus) | `README.adoc` (sem teste) |
+
+Variáveis de ambiente para o alias (ex.: `SEEDGRID_CACHE_HOSTS`): **Inferência** — o interceptor pede o nome exato `seedgrid.cache.hosts`, que o `EnvConfigSource` resolve pela regra MP. `QUARKUS_REDIS_HOSTS` continua funcionando como fallback. Não testado.
+
+## 3. Propriedades de frameworks usadas/recomendadas
+
+| Propriedade | Situação | Origem |
+|---|---|---|
+| `quarkus.redis.*` | Continua aceita como fallback do alias (compatibilidade) | `SeedGridCacheConfigRelocateInterceptor` |
+| `quarkus.arc.selected-alternatives` | Usada nos testes para habilitar o provider (`...SeedGridCacheRedis` etc.). Em apps normais os providers já são alternativas habilitadas por `@Priority(1)` — **Inferência** | `seedgrid-cache-*/src/test/resources/application.properties` |
+| `quarkus.redis.devservices.enabled` | Desligada nos testes para provar o relocate. Também poderia ser escrita como `seedgrid.cache.devservices.enabled` pelo alias — **Inferência** (propriedade build-time; depende de o interceptor estar ativo no build, não testado) | idem |
+| `quarkus.index-dependency.*` | **Não** necessária: `seedgrid-cache-core` empacota `META-INF/jandex.idx` (`jandex-maven-plugin` nos poms) | `pom.xml`; comentário em `java/examples/seedgrid-cache-example/src/main/resources/application.properties` |
+
+## 4. Propriedades só de testes/exemplos
+
+| Propriedade | Onde | Observação |
+|---|---|---|
+| `quarkus.redis.devservices.enabled=false` | `seedgrid-cache-{redis,valkey,dragonfly}/src/test/resources/application.properties` | garante que só `seedgrid.cache.hosts` configure o client |
+| `quarkus.arc.selected-alternatives=<provider>` | idem | habilita o provider testado |
+| `seedgrid.cache.hosts` (dinâmica, URL do container) | `*AliasTestResource#start()` | injetada pelo test resource |
+| `seedgrid.cache.example.item-ttl` (`Duration`, default `PT30S` no `@ConfigProperty`) | `java/examples/seedgrid-cache-example` → `CatalogService` | **propriedade do exemplo, não da lib** (apesar do prefixo); não é relocada |
+
+## 5. Aliases, obsoletas, renomeações
+
+- `seedgrid.cache.<x>` ↔ `quarkus.redis.<x>` (alias, precedência para `seedgrid.cache.*`). **Confirmado.**
+- Clientes nomeados: pelo código, `quarkus.redis.<nome>.hosts` também é procurado como `seedgrid.cache.<nome>.hosts` (o relocate é por prefixo). Ambos os prefixos funcionam; os providers SeedGrid usam só o client `@Default`. **Inferência** (sem teste).
+- Nenhuma propriedade obsoleta encontrada.
+
+## 6. Configuração mínima
+
+```properties
+# Com um provider RESP no classpath (seedgrid-cache-redis | -valkey | -dragonfly):
+seedgrid.cache.hosts=redis://<host>:6379
+```
+
+Sem provider no classpath não é necessária nenhuma propriedade (cache in-memory).
+
+## 7. Configuração completa comentada
+
+```properties
+# Reação a falha do backend distribuído: WARN (fail-soft, padrão) | ERROR (fail-closed, relança)
+seedgrid.cache.if-provider-is-down=WARN
+
+# --- Fachada de quarkus.redis.* (qualquer chave do quarkus-redis-client vale com este prefixo) ---
+seedgrid.cache.hosts=redis://<host>:6379
+seedgrid.cache.password=<SEGREDO:cache-password>
+seedgrid.cache.timeout=PT5S          # exemplo de Duration ISO-8601; padrão é o do Quarkus
+seedgrid.cache.max-pool-size=16      # exemplo; padrão é o do Quarkus
+seedgrid.cache.max-pool-waiting=100  # exemplo; padrão é o do Quarkus
+```
+
+Os valores numéricos/Duration acima são exemplos de formato, não padrões.
+
+## 8. Receitas
+
+- **Dev local / instância única sem servidor**: dependa só de `seedgrid-cache-core`; nada a configurar (`DefaultSeedGridCache`).
+- **Produção multi-instância com Redis**: adicione `seedgrid-cache-redis` + `seedgrid.cache.hosts` (+ `password` se houver AUTH). Trocar para Valkey/Dragonfly = trocar o artifact; a config continua a mesma.
+- **Cache crítico (não pode servir dado "degradado")**: `seedgrid.cache.if-provider-is-down=ERROR` — operações relançam a exceção do backend.
+- **Migração de config legada**: `quarkus.redis.*` existente continua funcionando; migre para `seedgrid.cache.*` quando quiser (o novo vence).
+
+## 9. Dúvidas e lacunas
+
+- **Não confirmado**: se o interceptor (registrado via `ServiceLoader`) é aplicado também na fase de build do Quarkus — relevante para chaves build-time como `devservices.*`. Os ITs só provam runtime (`hosts`).
+- **Não confirmado**: comportamento de `withLock` quando o backend cai (não é envolvido por `CacheProviderFailSoft`; a exceção propaga).
+- Equivalência exata com a config do crate Rust: ver [[SeedGrid/Extensions/cache/Configuracao-Rust|Configuração Rust do cache]].