@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,229 @@
+---
+tags: [seedgrid, extension, resilience, exemplos]
+fonte: java/seedgrid-quarkus-ext-resilience
+branch: main
+commit: eff41304f8
+analisado-em: 2026-10-14
+---
+
+# Exemplos — SeedGrid Resilience (Quarkus)
+
+Voltar: [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral do resilience]] · Propriedades: [[SeedGrid/Extensions/resilience/Configuracao|Configuração do resilience]]
+
+Pacote base: `br.com.seedgrid.resilience.core.runtime`. Exemplos baseados em `README.md`, `README.adoc` e nas assinaturas reais das anotações/SPIs.
+
+## Dependência
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-resilience-core</artifactId>
+    <version>2026.10.13</version>
+</dependency>
+<!-- estado distribuído: um provider de cache (ex.: Redis) -->
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-cache-redis</artifactId>
+    <version>2026.10.13</version>
+</dependency>
+```
+
+Versão `2026.10.13` = pom atual de `seedgrid-quarkus-ext-resilience` e de `seedgrid-quarkus-lib-cache`. **Confirmado**.
+
+## 1. Rate limit básico (por IP)
+
+Fonte: `README.md`.
+
+```java
+import java.time.temporal.ChronoUnit;
+import br.com.seedgrid.resilience.core.runtime.ratelimiter.annotations.SeedGridRateLimit;
+
+@Path("/auth")
+public class SignupResource {
+
+    @POST
+    @Path("/signup")
+    @SeedGridRateLimit(permits = 5, window = 1, windowUnit = ChronoUnit.MINUTES)
+    public Response signup(SignupRequest req) { ... }   // 5 req/min por IP
+}
+```
+
+Ao estourar: HTTP 429 com `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, `X-RateLimit-Reset` e `Retry-After` (via `RateLimitExceptionMapper`).
+
+## 2. Limiters independentes ajustáveis por properties
+
+Fonte: `README.md`.
+
+```java
+@SeedGridRateLimit(configKey = "login", permits = 100, window = 1, windowUnit = ChronoUnit.MINUTES)
+public AuthResponseDTO login(LoginDTO dto) { ... }
+
+@SeedGridRateLimit(configKey = "export-create", permits = 10, window = 1, windowUnit = ChronoUnit.HOURS)
+public Response createExport(ExportRequest req) { ... }
+```
+
+```properties
+seedgrid.ratelimit.login.permits=200
+seedgrid.ratelimit.login.window=PT30S
+seedgrid.ratelimit.export-create.algorithm=token-bucket
+seedgrid.ratelimit.export-create.burst-capacity=3
+```
+
+## 3. Token bucket com rajada e espaçamento mínimo
+
+Fonte: `README.adoc` § "Exemplo de Token Bucket".
+
+```java
+import br.com.seedgrid.resilience.core.runtime.ratelimiter.enums.RateLimitAlgorithm;
+
+@SeedGridRateLimit(
+    permits = 10,
+    window = 1,
+    windowUnit = ChronoUnit.MINUTES,
+    algorithm = RateLimitAlgorithm.TOKEN_BUCKET,
+    burstCapacity = 20,
+    minSpacing = 200,
+    minSpacingUnit = ChronoUnit.MILLIS)
+public void syncProducts() { ... }
+```
+
+`minSpacing` não tem efeito com `FIXED_WINDOW` (ver [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral]]).
+
+## 4. Cota compartilhada entre métodos (`GROUP`)
+
+Fonte: `README.adoc` § "Compartilhando cota com GROUP". Observe que `KeyScope` fica no pacote `circuitbreaker.enums`.
+
+```java
+import br.com.seedgrid.resilience.core.runtime.circuitbreaker.enums.KeyScope;
+
+@SeedGridRateLimit(permits = 300, window = 1, windowUnit = ChronoUnit.MINUTES,
+                   group = "email-provider", scope = KeyScope.GROUP)
+public void sendWelcomeEmail(...) { ... }
+
+@SeedGridRateLimit(permits = 300, window = 1, windowUnit = ChronoUnit.MINUTES,
+                   group = "email-provider", scope = KeyScope.GROUP)
+public void sendResetEmail(...) { ... }
+```
+
+## 5. Contexto sem HTTP (jobs, consumers)
+
+Fonte: Javadoc de `SeedGridRateLimit#identity` e `README.adoc`.
+
+```java
+import br.com.seedgrid.resilience.core.runtime.ratelimiter.spi.AnonymousIdentityResolver;
+
+@SeedGridRateLimit(permits = 10, window = 1, windowUnit = ChronoUnit.MINUTES,
+                   identity = AnonymousIdentityResolver.class)
+public void consume(Message msg) { ... }
+```
+
+## 6. Identidade customizada (SPI `IdentityResolver`)
+
+Fonte: `README.md`. Assinatura real: `String resolve(SeedGridInvocationContext ctx)`; nunca retornar `null`.
+
+```java
+import br.com.seedgrid.resilience.core.runtime.core.SeedGridInvocationContext;
+import br.com.seedgrid.resilience.core.runtime.ratelimiter.spi.IdentityResolver;
+
+@ApplicationScoped
+public class TenantIdentityResolver implements IdentityResolver {
+    @Override
+    public String resolve(SeedGridInvocationContext ctx) {
+        return ctx.tenantId().orElse("anonymous");
+    }
+}
+
+@SeedGridRateLimit(permits = 1000, window = 1, windowUnit = ChronoUnit.HOURS,
+                   identity = TenantIdentityResolver.class)
+public Report generate(...) { ... }
+```
+
+O `RateLimitService` busca o resolver via `CDI.current().select(classe)`; se não for bean resolvível, instancia pelo construtor sem argumentos.
+
+## 7. Publicando tenant/operação no contexto
+
+A chave do rate limit inclui os atributos `tenantId` e `operation` do `SeedGridInvocationContext` corrente. A extension não preenche esse contexto; o host pode usar `ThreadLocalSeedGridInvocationContext` (API real: `set`, `clear`, `runWith`, `callWith`). Implementação ilustrativa do contexto (a interface exige `header`, `method`, `path`, `remoteIp`, `attribute`, `tags`):
+
+```java
+import java.util.Map;
+import java.util.Optional;
+import br.com.seedgrid.resilience.core.runtime.core.SeedGridInvocationContext;
+import br.com.seedgrid.resilience.core.runtime.core.ThreadLocalSeedGridInvocationContext;
+
+record JobContext(Map<String, Object> attrs) implements SeedGridInvocationContext {
+    public Optional<String> header(String name) { return Optional.empty(); }
+    public Optional<String> method() { return Optional.empty(); }
+    public Optional<String> path() { return Optional.empty(); }
+    public Optional<String> remoteIp() { return Optional.empty(); }
+    public Optional<Object> attribute(String name) { return Optional.ofNullable(attrs.get(name)); }
+    public Optional<Map<String, String>> tags() { return Optional.empty(); }
+}
+
+ThreadLocalSeedGridInvocationContext.runWith(
+    new JobContext(Map.of("tenantId", "acme", "operation", "sync-products")),
+    () -> productSync.syncProducts());
+// chave resultante: rl:acme:sync-products:<escopo>:<identidade>
+```
+
+## 8. Circuit breaker com fallback
+
+Fonte: `README.md`.
+
+```java
+import br.com.seedgrid.resilience.core.runtime.circuitbreaker.annotations.SeedGridCircuitBreaker;
+
+@ApplicationScoped
+public class PaymentGateway {
+
+    @SeedGridCircuitBreaker(
+        name = "payments",
+        failureRateThreshold = 50.0,
+        minimumNumberOfCalls = 20,
+        openStateDurationMs = 30_000,
+        permittedCallsInHalfOpen = 10,
+        fallbackMethod = "paymentsFallback")
+    public PaymentResult charge(Order order) { ... }
+
+    // precisa ser público; procurado como (params..., Exceção), (params...) ou ()
+    public PaymentResult paymentsFallback(Order order, Exception cause) { ... }
+}
+```
+
+Sem fallback, circuito aberto lança `CircuitBreakerOpenException` (`circuitName()`, `retryAfterMs()`), que **não** tem `ExceptionMapper` na extension. Exemplo de mapper no host (usa só a API pública da exceção):
+
+```java
+import br.com.seedgrid.resilience.core.runtime.circuitbreaker.exceptions.CircuitBreakerOpenException;
+
+@Provider
+public class CircuitOpenMapper implements ExceptionMapper<CircuitBreakerOpenException> {
+    @Override
+    public Response toResponse(CircuitBreakerOpenException ex) {
+        return Response.status(503)
+                .header("Retry-After", (ex.retryAfterMs() + 999) / 1000)
+                .build();
+    }
+}
+```
+
+## 9. Circuit breaker com slow calls e exceções filtradas
+
+```java
+import br.com.seedgrid.resilience.core.runtime.circuitbreaker.enums.SlidingWindowType;
+
+@SeedGridCircuitBreaker(
+    name = "erp",
+    windowType = SlidingWindowType.TIME_BASED,
+    slidingWindowSize = 60,                 // em TIME_BASED: 60 segundos (e até 60 registros)
+    slowCallDurationThresholdMs = 2_000,
+    slowCallRateThreshold = 80.0,
+    recordExceptions = { java.io.IOException.class },
+    ignoreExceptions = { IllegalArgumentException.class })
+public ErpResponse fetch(String id) { ... }
+```
+
+Override em produção:
+
+```properties
+seedgrid.circuitbreaker.erp.slow-call-duration=PT3S
+seedgrid.circuitbreaker.erp.enabled=false   # kill switch
+```

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

@@ -0,0 +1,80 @@
+---
+tags: [seedgrid, extension, resilience, rust]
+fonte: rust/seedgrid-rust-crate-resilience
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# resilience — porte Rust (`seedgrid-rust-crate-resilience`)
+
+Porte da extensão Quarkus `seedgrid-quarkus-ext-resilience`. Lado Java: [[SeedGrid/Extensions/resilience/Visao-geral|Visão geral do resilience (Java)]] · [[SeedGrid/Extensions/resilience/Configuracao|Configuração do resilience (Java)]]. Configuração Rust: [[SeedGrid/Extensions/resilience/Configuracao-Rust|Configuração Rust do resilience]].
+
+Entrega **apenas** Circuit Breaker e Rate Limiter, ambos guardando estado num `SeedGridCacheProvider` (in-memory ou distribuído). Não há retry, timeout nem bulkhead. **Confirmado** (`src/lib.rs`).
+
+## Identificação
+| Item | Valor |
+|---|---|
+| Pacote Cargo | `seedgrid-rust-crate-resilience` (lib `seedgrid_resilience`) |
+| Versão | workspace `2026.10.14` |
+| Features | nenhuma |
+| Dependência SeedGrid | `seedgrid-rust-crate-cache` |
+| Consumidores | security (`src/ratelimit.rs`), backup e billing (seams de rate limit), `seedgrid-runtime` (macros `#[rate_limit]`/`#[circuit_breaker]`) |
+
+## Arquitetura
+No Java, CB e rate limit são interceptors CDI (`@SeedGridCircuitBreaker`, `@SeedGridRateLimit`). Em Rust:
+- **Circuit Breaker**: `circuit_breaker(name, CircuitBreakerConfig, cache)` devolve uma guarda `CircuitBreaker` com `call(fut)` / `call_with_fallback(fut, fallback)`; estado em `CacheBackedCircuitBreakerStore` (chave `cb:<name>`). Config efetiva por `CircuitBreakerConfigResolver::resolve(&SeedGridCircuitBreaker, nome)`.
+- **Rate Limiter**: `RateLimitService::new(cache, Arc<dyn ConfigSource>)` + `try_acquire(&SeedGridRateLimit, &InvocationInfo, ctx)`; algoritmos `FIXED_WINDOW`, `SLIDING_WINDOW`, `TOKEN_BUCKET`; chave `rl:<tenant>[:<operação>]:<escopo>:<identidade>`. Para Axum: `ServiceRateLimiter` + `rate_limit_middleware` (429 + headers `X-RateLimit-*`).
+- Ordem: rate limit é a camada mais externa (prioridade Java 1000), circuit breaker por dentro (1010).
+- As macros de `seedgrid-runtime` (`#[rate_limit]`, `#[circuit_breaker]`) geram essa fiação — ver [[SeedGrid/Extensions/runtime/Visao-geral|Visão geral do runtime]].
+
+## API pública
+| Módulo | Símbolos |
+|---|---|
+| `config` | `ConfigSource` (trait tipada: `get_bool/long/int/double/duration/string`), `EmptyConfigSource`, `MapConfigSource`, `ConfigValue` |
+| `circuitbreaker` | `SeedGridCircuitBreaker`, `CircuitBreakerConfig` (+ builder), `CircuitBreakerConfigResolver`, `CircuitBreakerStore`, `CacheBackedCircuitBreakerStore`, `circuit_breaker`, `CircuitBreaker`, `AsErrorClass`, `ErrorClass`, `CircuitBreakerOpenException`, `SlidingWindowType` |
+| `ratelimiter` | `SeedGridRateLimit`, `InvocationInfo`, `RateLimitService`, `Clock`, `RateLimiter`, `ServiceRateLimiter`, `rate_limit_middleware`, `apply_rate_limit_headers`, `IdentityResolver` (`IpIdentityResolver` — usa `X-Forwarded-For`/`X-Real-IP`; `AnonymousIdentityResolver`), `SeedGridInvocationContext`, `MapInvocationContext`, `RateLimitExceededException`, `RateLimitAlgorithm`, `KeyScope` (`Method`, `Class`, `Group`), `TimeUnit` |
+
+## Exemplos
+Circuit breaker (doc de `src/circuitbreaker/guard.rs`):
+```rust
+let cache = Arc::new(InMemoryCache::new());
+let cfg = CircuitBreakerConfig::builder().name("backup-upload").build();
+let cb = circuit_breaker("backup-upload", cfg, cache);
+let r: Result<u8, _> = cb.call(async { Ok::<u8, MinhaFalha>(1) }).await;
+```
+Rate limit numa rota Axum (padrão usado por backup/billing; seams `export_create_rate_limit`, `checkout_rate_limit`…):
+```rust
+let service = Arc::new(RateLimitService::new(cache, Arc::new(EmptyConfigSource)));
+let limiter: Arc<dyn RateLimiter> = Arc::new(ServiceRateLimiter::new(
+    service, seedgrid_billing::routes::checkout_rate_limit(), InvocationInfo::new("POST /billing/checkout", "billing")));
+let route = route.layer(axum::middleware::from_fn_with_state(limiter, rate_limit_middleware));
+```
+(O segundo bloco é **Inferência** montada a partir das assinaturas de `ServiceRateLimiter::new` e do doc de `rate_limit_middleware`; não há esse trecho literal no repositório.) Exemplo executável com macros: `rust/seedgrid-runtime/examples/resilience_audit.rs`.
+
+## Testes
+`tests/circuit_breaker_config_resolver.rs`, `circuit_breaker_store.rs`, `http_headers.rs`, `identity_resolver.rs`, `rate_limit_algorithms.rs`, `rate_limit_service_config_override.rs` (+ unitários). **Não executados.** Sem app em `rust/examples/`.
+
+## Notas de comportamento
+
+Valores inválidos de `algorithm`/`window-type` e config inválida (`permits <= 0`, `window <= 0`) causam **panic**.
+
+## Enums
+Java: [[SeedGrid/Extensions/resilience/Enums|Enums do resilience (Java)]].
+
+| Enum | Arquivo | Java equivalente |
+|---|---|---|
+| `RateLimitAlgorithm` | `src/ratelimiter/enums.rs` | [[SeedGrid/Extensions/resilience/Enums#RateLimitAlgorithm\|RateLimitAlgorithm]] |
+| `KeyScope` | idem | [[SeedGrid/Extensions/resilience/Enums#KeyScope\|KeyScope]] |
+| `TimeUnit` | idem | `java.time.temporal.ChronoUnit` (subconjunto) |
+| `CircuitState` | `src/circuitbreaker/enums.rs` | [[SeedGrid/Extensions/resilience/Enums#CircuitState\|CircuitState]] |
+| `SlidingWindowType` | idem | [[SeedGrid/Extensions/resilience/Enums#SlidingWindowType\|SlidingWindowType]] |
+| `CircuitBreakerError<E>` (`Open`, `Inner`) | `src/circuitbreaker/guard.rs` | exceções do circuito |
+| `ConfigValue` (`Bool`, `Long`, `Int`, `Double`, `Duration`, `Str`) | `src/config.rs` | tipo do valor numa `MapConfigSource` |
+
+Nenhum tem serde. Os nomes em texto vêm da `ConfigSource` (normalizados por trim, maiúsculas, `-` → `_`).
+- **RateLimitAlgorithm**: `FixedWindow` (`FIXED_WINDOW`, padrão), `TokenBucket` (`TOKEN_BUCKET`), `SlidingWindow` (`SLIDING_WINDOW`). Valor desconhecido na config → *panic*. Iguais ao Java.
+- **KeyScope**: `Method` (padrão), `Class`, `Group` (cai na assinatura do método se `group` vazio). Só definido em código (não há override por config).
+- **TimeUnit**: `Millis`, `Seconds`, `Minutes`, `Hours`. Nota: o Java aceita qualquer `ChronoUnit`; o Rust só estes 4.
+- **CircuitState**: `Closed` (0), `Open` (1), `HalfOpen` (2). Os ordinais entram na serialização binária do estado no cache (`ordinal`/`from_ordinal`; ordinal inválido → `Closed`). Iguais ao Java.
+- **SlidingWindowType**: `CountBased` (padrão), `TimeBased` (o tamanho da janela vira segundos). A config `window-type` aceita `COUNT_BASED`/`TIME_BASED` (inválido → *panic*).

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

@@ -0,0 +1,112 @@
+---
+tags: [seedgrid, extension, resilience]
+fonte: java/seedgrid-quarkus-ext-resilience
+branch: main
+commit: eff41304f8
+analisado-em: 2026-10-14
+---
+
+# SeedGrid Resilience (Quarkus) — Visão geral
+
+Extension Quarkus de **rate limiting** e **circuit breaker** declarativos. O desenvolvedor anota métodos/classes CDI com `@SeedGridRateLimit` ou `@SeedGridCircuitBreaker`; interceptors CDI aplicam a regra e guardam o estado no `SeedGridCacheProvider` (lib `seedgrid-cache`), de modo que, com um provider distribuído (Redis/Valkey/Dragonfly), o limite/circuito é compartilhado entre instâncias. A anotação define os valores padrão; com `configKey` (rate limit) ou `name` (circuit breaker) os valores podem ser sobrescritos por properties em runtime.
+
+- Configuração completa: [[SeedGrid/Extensions/resilience/Configuracao|Configuração do resilience]]
+- Enums (`RateLimitAlgorithm`, `KeyScope`, `SlidingWindowType`, `CircuitState`): [[SeedGrid/Extensions/resilience/Enums|Enums do resilience]]
+- Exemplos: [[SeedGrid/Extensions/resilience/Exemplos|Exemplos do resilience]]
+- Crate equivalente: [[SeedGrid/Extensions/resilience/Rust|Porte Rust]]
+- Dependência de cache: [[SeedGrid/Extensions/cache/Visao-geral|Visão geral do cache]]
+
+> Não é baseada em MicroProfile Fault Tolerance / SmallRye Fault Tolerance: não há dependência `quarkus-smallrye-fault-tolerance` nem uso de `@Retry`/`@CircuitBreaker` do MP. Propriedades no formato `<classe>/<método>/<Anotação>/<param>` **não** se aplicam. **Confirmado** (poms e imports).
+
+## Módulos e coordenadas
+
+| Módulo | groupId | artifactId | Versão | Papel |
+|---|---|---|---|---|
+| raiz (`pom.xml`) | `br.com.seedgrid` | `seedgrid-resilience-core-parent` | `2026.10.13` | POM agregador; parent `seedgrid-parent:2026.07.02`. Módulos: `deployment`, `runtime` |
+| `runtime` | `br.com.seedgrid` | `seedgrid-resilience-core` | `2026.10.13` | Anotações, interceptors, serviços, SPI, filtros JAX-RS. Gera `META-INF/jandex.idx` (jandex-maven-plugin) |
+| `deployment` | `br.com.seedgrid` | `seedgrid-resilience-core-deployment` | `2026.10.13` | `SeedgridResilienceCoreProcessor`: só registra a feature `seedgrid-resilience-core` |
+| `integration-tests` | `br.com.seedgrid` | `seedgrid-resilience-core-integration-tests` | — | **Não** listado em `<modules>` do POM raiz; contém apenas um recurso "hello" de template |
+
+Observações:
+- `quarkus-extension.yaml`: nome "SeedGrid Resilience Core", status `preview`.
+
+## Dependências
+
+| Dependência | Escopo | Uso |
+|---|---|---|
+| `io.quarkus:quarkus-arc` | compile | CDI / interceptors |
+| `br.com.seedgrid:seedgrid-cache-core:2026.10.13` | compile | `SeedGridCacheProvider` (`increment`, `getBytes`, `putBytes`, `withLock`) |
+| `jakarta.ws.rs:jakarta.ws.rs-api` | provided | `RateLimitExceptionMapper`, `RateLimitContainerResponseFilter` |
+| `io.quarkus:quarkus-vertx-http` | provided | `IpIdentityResolver` (injeção opcional de `HttpServerRequest`) |
+| `seedgrid-cache-redis`, `quarkus-redis-client`, testcontainers, mockito | test | Testes |
+
+Provider de cache: o `seedgrid-cache-core` traz `DefaultSeedGridCache` como `@DefaultBean` (em memória); os providers `seedgrid-cache-redis`/`-valkey`/`-dragonfly` são `@Alternative`. Sem um provider distribuído no classpath, o estado de rate limit/circuit breaker fica **por processo** (`DefaultSeedGridCache`, `@DefaultBean` em `seedgrid-cache-core`; o teste `SeedgridResilienceCoreTest` sobe sem provider nem config). **Confirmado**.
+
+## Arquitetura e fluxo
+
+```mermaid
+flowchart LR
+    CALL["Chamada a método anotado"] --> RLI["RateLimitInterceptor<br/>prioridade LIBRARY_BEFORE"]
+    RLI --> RLS["RateLimitService<br/>(lê seedgrid.ratelimit.{configKey}.*)"]
+    RLS --> IDR["IdentityResolver"]
+    RLS --> ALG["Fixed / Sliding / Token bucket"]
+    ALG --> CACHE[("SeedGridCacheProvider")]
+    RLI -->|"negado"| EX429["RateLimitExceededException → 429"]
+    RLI --> CBI["CircuitBreakerInterceptor<br/>prioridade LIBRARY_BEFORE+10"]
+    CBI --> CBR["CircuitBreakerConfigResolver<br/>(lê seedgrid.circuitbreaker.{name}.*)"]
+    CBI --> STORE["CacheBackedCircuitBreakerStore"] --> CACHE
+    CBI --> M["método de negócio / fallbackMethod"]
+```
+
+### Rate limit (`@SeedGridRateLimit`)
+1. `RateLimitInterceptor` resolve a anotação: método → método na classe alvo → hierarquia de classes → interfaces.
+2. `RateLimitService#tryAcquire`: se `configKey` não vazio e `seedgrid.ratelimit.{configKey}.enabled=false`, permite sem contar. Senão resolve identidade, permits, janela, min-spacing, burst e algoritmo (config vence anotação quando há `configKey`), valida (`permits > 0`, `window > 0`, `burstCapacity >= 0`, `minSpacing >= 0`, senão `IllegalArgumentException`).
+3. Chave no cache: `rl:{tenant}:{operation}:{scope}:{identity}` (sem `operation` quando vazio). `tenant` vem do atributo `tenantId` do `SeedGridInvocationContext` (padrão `no-tenant`); `operation` do atributo `operation`. `scope`: `METHOD` → assinatura do método; `CLASS` → nome da classe alvo; `GROUP` → `group` (ou assinatura se vazio).
+4. Algoritmos:
+   - `FIXED_WINDOW`: `cache.increment(key, window)`. **Não aplica `minSpacing`** (o campo é ignorado nesse algoritmo — **Confirmado**).
+   - `SLIDING_WINDOW`: lista de timestamps sob `withLock`; aplica `minSpacing`.
+   - `TOKEN_BUCKET`: capacidade = `burstCapacity` (ou `permits` se 0), reposição `permits/window`; aplica `minSpacing`.
+5. Negado → `RateLimitExceededException`; `RateLimitExceptionMapper` (JAX-RS) responde **429** com `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, `X-RateLimit-Reset` e `Retry-After` (segundos, arredondados para cima).
+6. Permitido e `emitHeaders=true` → `RateLimitHeaderCarrier` (ThreadLocal) e `RateLimitContainerResponseFilter` acrescentam `X-RateLimit-Limit/Remaining/Reset` à resposta.
+
+### Circuit breaker (`@SeedGridCircuitBreaker`)
+1. `CircuitBreakerInterceptor` resolve a anotação (método → método na classe alvo → hierarquia).
+2. Kill switch: `seedgrid.circuitbreaker.{name}.enabled=false` → chama o método direto.
+3. Nome do circuito = `name` ou, se vazio, assinatura `Classe#metodo(tipos)`. Chave no cache: `cb:{nome}`.
+4. `CacheBackedCircuitBreakerStore` (sob `withLock` de 1 s): estados `CLOSED` → `OPEN` (taxa de falha ≥ `failureRateThreshold` ou, se `slowCallDurationThresholdMs > 0`, taxa de lentas ≥ `slowCallRateThreshold`, após `minimumNumberOfCalls`) → `HALF_OPEN` após `openStateDurationMs` → `CLOSED` quando `permittedCallsInHalfOpen` sondas têm sucesso, ou volta a `OPEN` na primeira falha.
+5. Janela: ring buffer de tamanho `slidingWindowSize`. Em `TIME_BASED`, `slidingWindowSize` é **também** a duração em segundos da janela (e o tamanho máximo do buffer). Alterar `slidingWindowSize` descarta o estado salvo. TTL do estado: `max(openStateDurationMs*2, 1h)`.
+6. Exceções: conta como falha se for subclasse de algum `recordExceptions` e não de `ignoreExceptions` (ignore vence).
+7. Circuito aberto → `CircuitBreakerOpenException(circuitName, retryAfterMs)`; com `fallbackMethod`, chama o fallback. O fallback também é chamado em **qualquer** exceção do método (mesmo as ignoradas). Assinaturas procuradas, em ordem: `(params..., TipoDaExceção ou superclasse)`, `(params...)`, `()`; precisa ser método **público** (`Class#getMethod`).
+
+## APIs públicas e pontos de integração
+
+| Tipo | Símbolo | Descrição |
+|---|---|---|
+| Anotação (InterceptorBinding) | `...ratelimiter.annotations.SeedGridRateLimit` | `permits`, `window`, `windowUnit`, `algorithm`, `burstCapacity`, `minSpacing`, `minSpacingUnit`, `identity`, `group`, `scope`, `emitHeaders`, `configKey` (detalhes em [[SeedGrid/Extensions/resilience/Configuracao\|Configuração]]) |
+| Anotação (InterceptorBinding) | `...circuitbreaker.annotations.SeedGridCircuitBreaker` | `name`, `slidingWindowSize`, `windowType`, `failureRateThreshold`, `slowCallDurationThresholdMs`, `slowCallRateThreshold`, `minimumNumberOfCalls`, `openStateDurationMs`, `permittedCallsInHalfOpen`, `recordExceptions`, `ignoreExceptions`, `fallbackMethod` |
+| SPI | `...ratelimiter.spi.IdentityResolver` | `String resolve(SeedGridInvocationContext ctx)`; prontos: `IpIdentityResolver` (X-Forwarded-For → X-Real-IP → remote address → `anonymous`), `AnonymousIdentityResolver` |
+| SPI | `...circuitbreaker.spi.CircuitBreakerStore` | `allowCall`, `onSuccess`, `onError`; implementação `CacheBackedCircuitBreakerStore` (`@ApplicationScoped`, sem `@DefaultBean`) |
+| SPI | `...ratelimiter.algorithm.RateLimitAlgorithmStrategy` | `acquire(SeedGridCacheProvider, RateLimitRequest)` |
+| Contexto | `...core.SeedGridInvocationContext` / `ThreadLocalSeedGridInvocationContext` | `set/clear/runWith/callWith`; atributos `tenantId` e `operation` entram na chave do rate limit. A extension **não** popula esse contexto: o host precisa fazê-lo (senão usa `EmptySeedGridInvocationContext`) |
+| Beans CDI | `RateLimitService`, `RateLimitService.Clock`, `CircuitBreakerConfigResolver`, algoritmos | `@ApplicationScoped` |
+| Exceções | `RateLimitExceededException` (mapeada para 429), `CircuitBreakerOpenException` | `CircuitBreakerOpenException` **não** tem `ExceptionMapper` na extension — **Inferência**: em endpoint REST sem fallback vira erro 500 se o host não mapear |
+| JAX-RS | `RateLimitExceptionMapper`, `RateLimitContainerResponseFilter` (`@Provider`) | Headers `X-RateLimit-*`, `Retry-After` |
+
+Endpoints REST próprios: nenhum no runtime (o `integration-tests` tem só `GET /seedgrid-resilience-core` de template). Migrations: nenhuma. Eventos: nenhum.
+
+## Testes existentes (não executados)
+
+| Local | Tipo | Cobre |
+|---|---|---|
+| `runtime/src/test/.../ratelimiter/RateLimitAlgorithmsIT.java` | IT com Redis (Testcontainers, `disabledWithoutDocker`) | Os 3 algoritmos: limite, reset, min-spacing, burst, refill |
+| `runtime/src/test/.../circuitbreaker/CircuitBreakerStoreIT.java` | IT com Redis | Transições de estado, slow calls, record/ignore, janela por tempo, persistência |
+| `runtime/src/test/.../ratelimiter/services/RateLimitServiceConfigOverrideTest.java` | Unitário (Mockito `Config`) | Overrides `seedgrid.ratelimit.checkout.*`, kebab-case em `algorithm`, sem `configKey` ignora config |
+| `runtime/src/test/.../circuitbreaker/configs/CircuitBreakerConfigResolverTest.java` | Unitário | Overrides `seedgrid.circuitbreaker.payments.*`, sem `name` ignora config, `enabled` |
+| `runtime/src/test/.../ratelimiter/spi/IpIdentityResolverTest.java`, `AnonymousIdentityResolverTest.java` | Unitário | Resolução de identidade |
+| `deployment/src/test/.../SeedgridResilienceCoreTest.java`, `SeedgridResilienceCoreDevModeTest.java` | QuarkusUnitTest / DevModeTest | Boot sem camada HTTP e sem config |
+
+## Limitações
+- `minSpacing` não tem efeito com `FIXED_WINDOW`.
+- O kill switch do rate limiter (`enabled=false`) ainda emite headers `X-RateLimit-*` (limite = `permits` da anotação), quando `emitHeaders=true`.
+- Valores inválidos de `algorithm`/`window-type` só falham na chamada (`IllegalArgumentException` de `Enum.valueOf`), não no boot.
+- `CircuitBreakerOpenException` sem mapper HTTP.

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

@@ -0,0 +1,90 @@
+---
+tags: [seedgrid, extension, runtime, rust, configuracao]
+fonte: rust/seedgrid-runtime, rust/seedgrid-macros
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# runtime — Configuração Rust
+
+Visão geral: [[SeedGrid/Extensions/runtime/Visao-geral|Visão geral do runtime]]. Não há equivalente Java (o análogo é o comportamento do container Quarkus).
+
+## Cabeçalho
+| Item | Valor |
+|---|---|
+| Mecanismos | (1) `BootstrapOptions` em runtime; (2) **atributos das macros** (fixados em compilação); (3) uma leitura de ambiente: `default_gate(key)` |
+| Variáveis de ambiente | **nenhum nome fixo**: `default_gate` lê a variável cujo nome é o valor de `#[scheduled(enabled_if = "...")]` (`rust/seedgrid-runtime/src/bootstrap.rs` → `default_gate`) |
+| Features Cargo | nenhuma (nas duas crates) |
+
+## Runtime: `BootstrapOptions` e gate
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Leitura | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `BootstrapOptions.fail_fast` | bool | — | `true` | Não | primeiro erro de `#[startup]` aborta o boot (`Err` com contexto); `false` loga e segue | `run_startups` | — | `bootstrap_with` | `src/bootstrap.rs` |
+| `BootstrapOptions.run_startup` | bool | — | `true` | Não | roda as `#[startup]` | `bootstrap_with` | — | idem | idem |
+| `BootstrapOptions.run_scheduled` | bool | — | `true` | Não | spawna as `#[scheduled]` | `bootstrap_with` | — | idem | idem |
+| `BootstrapOptions.gate` (`with_gate`) | `Fn(&str) -> bool` | — | `default_gate` | Não | decide se cada `enabled_if` está ligado | `spawn_all_scheduled` | `enabled_if` | idem | idem |
+| `<valor de enabled_if>` (env var dinâmica) | bool | `true`, `1`, `yes`, `on` (case-insensitive, `trim`); ausente/outro = desligado | desligado | Condicional: só para tasks com `enabled_if` | task não é spawnada quando falso (log `info`) | `default_gate` | substituível por `with_gate` | no `bootstrap` | `src/bootstrap.rs` → `default_gate` |
+
+No workspace, nenhuma crate de plataforma declara `enabled_if`; só aparecem `FEATURE_REPORTS` (teste `tests/macros.rs`) e `REPORTS_ENABLED` (doc) como exemplos.
+
+## Macros (configuração em compilação)
+
+### `#[startup]`
+| Atributo | Tipo | Padrão | Observação |
+|---|---|---|---|
+| `priority` | i32 | `100` (neutra; `seedgrid-macros/src/lib.rs` → `startup`) | menor roda antes |
+
+### `#[scheduled]` (exatamente um de `cron`/`every`)
+| Atributo | Tipo | Padrão | Observação |
+|---|---|---|---|
+| `cron` | String | — | quartz de 6 campos (`seg min hora dia-mes mes dia-semana`); inválido → task não iniciada (log de erro) |
+| `every` | String | — | `Nms`, `Ns`, `Nm`, `Nh`, `Nd`; zero/inválido → não iniciada |
+| `enabled_if` | String | — (sempre ligada) | nome da env var do gate |
+| `concurrent` | bool | `false` (SKIP) | `true` = PROCEED |
+| `delay` | String | — | atraso inicial, mesmo formato de `every` |
+
+### `#[default_provider]`
+`spi` (obrigatório), `provider`, `priority` (padrão `0`; maior vence em `resolve_spi`).
+
+### `#[rate_limit]` (→ `seedgrid-resilience`)
+| Atributo | Padrão | Observação |
+|---|---|---|
+| `config_key` | `""` | habilita overrides `seedgrid.ratelimit.<key>.*` da `ConfigSource` do `RateLimitService` ([[SeedGrid/Extensions/resilience/Configuracao-Rust\|Configuração Rust do resilience]]) |
+| `permits` | `5` | |
+| `window` | `"30s"` | |
+| `algorithm` | `"fixed_window"` | `fixed_window`, `sliding_window`, `token_bucket` |
+| `service` | — | **obrigatório**: caminho de função que devolve `Arc<RateLimitService>` |
+| `context` | `EmptySeedGridInvocationContext` | expressão de contexto (limite global por método se omitido) |
+
+Retorno exigido: `Result<T, E>` com `E: From<RateLimitExceededException>`.
+
+### `#[circuit_breaker]` (→ `seedgrid-resilience`)
+| Atributo | Padrão | Observação |
+|---|---|---|
+| `name` | — | **obrigatório** |
+| `failure_rate_threshold` | `50.0` | |
+| `open_state_duration` | `"30s"` | |
+| `minimum_number_of_calls` | `20` | |
+| `sliding_window_size` | `100` | |
+| `cache` | — | **obrigatório**: provider de `Arc<InMemoryCache>` ou `Arc<dyn SeedGridCacheProvider>` |
+| `fallback` | — | função sem argumentos com o mesmo `Result<T, E>` |
+
+### `#[audited]` (→ `seedgrid-audit`)
+`entity` (FQCN, obrigatório), `operation` (`CREATE`, `UPDATE`, `DELETE`, `READ`, `OTHER`; obrigatório), `description`, `auditor` (obrigatório; provider de `impl Auditor`), `user` (expr), `context` (expr `AuditContext`, vence `user`), `before` (expr avaliada antes do corpo), `mask_rules` (expr `Vec<MaskRule>`), `capture_return` (padrão `true` em CREATE/UPDATE; serializa `Ok(T)`, exige `T: Serialize`). Audita só no sucesso.
+
+### `#[derive(PersonalData)]` (→ `seedgrid-privacy`)
+Atributo de campo `#[personal_data(...)]` (alias `#[encrypted(...)]`): `search = "campo_hash"`, `normalize = "email" | "canonical" | "none"` (padrão `canonical`), `nested` (desce em struct que também deriva `PersonalData`). Ver [[SeedGrid/Extensions/privacy/Configuracao-Rust|Configuração Rust do privacy]].
+
+Fonte de todos os atributos: `rust/seedgrid-macros/src/lib.rs` (parsers `meta.path.is_ident(...)`) e README do runtime. Padrões de `#[startup]` e `#[rate_limit]` conferidos nos parsers; os de `#[circuit_breaker]` são `Option` no parser e o valor efetivo vem dos defaults de `SeedGridCircuitBreaker` (README; **Inferência** coerente com `config_resolver.rs`); os de `#[audited]` vêm do README.
+
+## Somente exemplos/testes
+| Variável | Onde |
+|---|---|
+| `FEATURE_REPORTS` | `tests/macros.rs` (gate de teste) |
+| `RUST_LOG` | não usado; os exemplos fixam o nível em código |
+
+## Receitas
+- **Ligar uma rotina só em produção**: `#[scheduled(cron = "0 0 3 * * ?", enabled_if = "NIGHTLY_JOB_ENABLED")]` + `NIGHTLY_JOB_ENABLED=true` no ambiente.
+- **Gate a partir de outra fonte (ex.: arquivo de config)**: `bootstrap_with(BootstrapOptions::new().with_gate(|k| minha_config.flag(k)))`.
+- **Boot tolerante a falhas**: `BootstrapOptions { fail_fast: false, ..Default::default() }`.

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

@@ -0,0 +1,114 @@
+---
+tags: [seedgrid, extension, runtime, rust]
+fonte: rust/seedgrid-runtime, rust/seedgrid-macros
+branch: main
+commit: be738a2d1e
+analisado-em: 2026-10-14
+---
+
+# runtime — Visão geral (só Rust: `seedgrid-runtime` + `seedgrid-macros`)
+
+Par de crates que reproduz em Rust, **em tempo de compilação**, o auto-wiring do Quarkus/CDI que os hosts SeedGrid têm no Java: anotar funções e chamar um único `bootstrap()`. Não há extensão Java equivalente (é infraestrutura do lado Rust). Configuração e referência dos atributos das macros: [[SeedGrid/Extensions/runtime/Configuracao-Rust|Configuração Rust do runtime]].
+
+| Crate | Papel |
+|---|---|
+| `seedgrid-runtime` (lib `seedgrid_runtime`) | registro `inventory`, `bootstrap()`/`RuntimeHandles`, motor de agendamento (cron/intervalo), eventos ao usuário (`events`); reexporta as macros, `inventory` e `anyhow` |
+| `seedgrid-macros` (lib `seedgrid_macros`, `proc-macro = true`) | attribute macros `#[startup]`, `#[scheduled]`, `#[default_provider]`, `#[rate_limit]`, `#[circuit_breaker]`, `#[audited]` e o derive `#[derive(PersonalData)]` |
+
+Ambas: versão do workspace `2026.10.14`, edição 2021, MSRV 1.82, sem features Cargo. `seedgrid-runtime` depende de `seedgrid-macros`, `inventory 0.3`, `tokio`, `chrono`; resilience, cache e audit são só **dev-dependencies** (exemplo/teste). Recomendação do README: depender só de `seedgrid-runtime` (o código gerado usa `::seedgrid_runtime::...`); a exceção é `#[derive(PersonalData)]`, que gera `::seedgrid_privacy::...` e é reexportado pela crate privacy.
+
+## Mapeamento CDI/Quarkus → Rust
+| Java | Rust | Fase |
+|---|---|---|
+| `@Observes StartupEvent` / `@Startup` + `@Priority` | `#[startup(priority = N)]` (menor roda antes) | 1 |
+| `@Scheduled(cron / every)` | `#[scheduled(cron = "...")]` / `#[scheduled(every = "...")]` | 1 |
+| gate `{config.key}` do `@Scheduled` | `#[scheduled(..., enabled_if = "ENV_VAR")]` | 1 |
+| `ConcurrentExecution.SKIP` / `PROCEED` | `concurrent = false` (padrão) / `true` | 1 |
+| `@DefaultBean` | `#[default_provider(spi, provider, priority)]` + `resolve_spi` (só metadados; maior prioridade vence) | 1 |
+| `@SeedGridRateLimit` | `#[rate_limit(...)]` → `seedgrid-resilience` | 2 |
+| `@SeedGridCircuitBreaker` | `#[circuit_breaker(...)]` → `seedgrid-resilience` | 2 |
+| `@Audit` | `#[audited(...)]` → `seedgrid-audit` | 3 |
+| `@PersonalData` / `@EncryptedField` | `#[derive(PersonalData)]` → `seedgrid-privacy` | — |
+| `Event<SgUserEvent>` + `@Observes(AFTER_SUCCESS)` | `events::UserEventSink` / `SgUserEvent` | — |
+| boot / shutdown do container | `bootstrap()`, `bootstrap_with(opts)` / `RuntimeHandles::shutdown()` | 1 |
+
+Fonte: `rust/seedgrid-runtime/src/lib.rs`.
+
+## Arquitetura
+```mermaid
+flowchart LR
+    A["#[startup] / #[scheduled] / #[default_provider]"] -- inventory::submit! --> R[(slices globais em link-time)]
+    R --> B["bootstrap()"]
+    B -->|ordem de priority| S["roda #[startup] (sequencial)"]
+    B -->|enabled_if via gate| T["spawn_scheduled_boxed (tokio)"]
+    T --> H[RuntimeHandles]
+    L["libs: spawn_scheduled(SpawnConfig, factory)"] --> T
+```
+- Fase 1 usa `inventory`: o linker precisa manter os símbolos (funciona em binários, exemplos e testes de integração; numa lib nunca referenciada pelo binário, itens podem ser descartados — caveat do README).
+- Fases 2/3 **não** usam `inventory`: são interceptors por função que embrulham o corpo e obtêm dependências via funções-provider sem argumentos (`service`, `cache`, `auditor`).
+- `startup` com erro: `fail_fast = true` (padrão) aborta o boot; senão loga e continua. Erros de `#[scheduled]` só são logados (a task sobrevive).
+
+## API pública (`seedgrid-runtime`)
+| Grupo | Símbolos | Fonte |
+|---|---|---|
+| Boot | `bootstrap()`, `bootstrap_with(BootstrapOptions)`, `BootstrapOptions { fail_fast, run_startup, run_scheduled, gate }`, `BootstrapOptions::with_gate`, `default_gate`, `EnabledGate` | `src/bootstrap.rs` |
+| Handles | `RuntimeHandles::{scheduled_task_count, task_names, abort_all, shutdown}` | idem |
+| Agendamento programático (para libs) | `spawn_scheduled(SpawnConfig, factory) -> JoinHandle`, `SpawnConfig::{new, concurrent, with_initial_delay}`, `RunSchedule::{cron, every, from_spec}`, `JobFactory` | `src/scheduler.rs` |
+| Cron / duração | `CronSchedule::{parse, matches, next_after}` (quartz de 6 campos: `*`, `?`, `*/n`, `a-b`, `a,b`; dia da semana 0=domingo, aceita 7), `parse_duration` (`ms`, `s`, `m`, `h`, `d`; zero → `None`) | `src/cron.rs` |
+| Registro | `StartupItem`, `ScheduledItem`, `ScheduleSpec`, `SpiBinding`, `TaskRunner`, `BoxFuture`, `resolve_spi`, `startup_items_sorted`, `scheduled_items` | `src/registry.rs` |
+| Eventos | `events::{SgUserEvent, UserEventSink, NoopUserEventSink, noop_user_event_sink}` | `src/events.rs` |
+
+## Quem usa no workspace (**Confirmado** por grep)
+| Crate | O que usa |
+|---|---|
+| backup | `events::{UserEventSink, SgUserEvent, noop_user_event_sink}` (aviso de export concluído) |
+| realtime | `events::*` (implementa `UserEventSink`), `parse_duration` |
+| subdomain-tenancy | `spawn_scheduled`, `RunSchedule`, `SpawnConfig`, `CronSchedule`, `events` |
+| privacy | `#[derive(PersonalData)]` (via `seedgrid-macros`) |
+| — | Nenhuma crate de plataforma usa `#[startup]`, `#[scheduled]`, `#[rate_limit]`, `#[circuit_breaker]` ou `#[audited]` fora dos exemplos/testes do runtime |
+
+## Exemplo (de `rust/seedgrid-runtime/examples/quickstart.rs`)
+```rust
+use anyhow::Result;
+use seedgrid_runtime::{scheduled, startup};
+
+#[startup(priority = 10)]
+async fn seed_database() -> Result<()> { Ok(()) }
+
+#[scheduled(every = "2s")]
+async fn heartbeat() -> Result<()> { Ok(()) }
+
+#[scheduled(cron = "0 0 * * * *")]
+async fn hourly_report() -> Result<()> { Ok(()) }
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let handles = seedgrid_runtime::bootstrap().await?;
+    tokio::time::sleep(std::time::Duration::from_millis(5100)).await;
+    handles.shutdown().await;
+    Ok(())
+}
+```
+Fases 2/3 completas: `rust/seedgrid-runtime/examples/resilience_audit.rs` (`cargo run -p seedgrid-runtime --example resilience_audit`). API programática (doc de `src/scheduler.rs`):
+```rust
+let schedule = RunSchedule::cron("0 0 * * * ?").expect("cron valido");
+let handle = spawn_scheduled(SpawnConfig::new("nightly_cleanup", schedule), || async { Ok(()) });
+```
+
+## Testes
+`rust/seedgrid-runtime/tests/macros.rs` (coleta e ordem de `#[startup]`, gate `enabled_if` ligado/desligado, task disparando, `default_provider`) e `tests/resilience_audit.rs` (macros de Fase 2/3); unitários em `src/cron.rs`. **Não executados.**
+
+## Limitações
+- `#[startup]`/`#[scheduled]` não recebem argumentos; a função deve ser `async fn() -> anyhow::Result<()>` ou `-> ()`.
+- Empate de `priority` tem ordem indefinida.
+- `#[default_provider]` registra só metadados (sem DI real) — roadmap do README.
+
+## Enums
+Sem equivalente Java. Públicos:
+
+| Enum | Arquivo | Variantes / uso |
+|---|---|---|
+| `ScheduleSpec` | `seedgrid-runtime/src/registry.rs` | `Cron(&'static str)` ou `Every(&'static str)` — gerado por `#[scheduled(cron=…)]` / `#[scheduled(every=…)]` (exatamente um dos dois) |
+| `RunSchedule` | `seedgrid-runtime/src/scheduler.rs` | `Interval(Duration)` ou `Cron(CronSchedule)` — schedule já compilado (`RunSchedule::cron`, `every`, `from_spec`); `None` se a expressão for inválida |
+
+As macros (`seedgrid-macros`) não definem enums; o derive `PersonalData` usa `SearchNormalization` ([[SeedGrid/Extensions/privacy/Rust#Enums|Enums do privacy Rust]]).