# Tech Spec - DDD Effect Rust Providers CLI
## Rastreabilidade
- Orquestração: DDD Effect Rust Providers CLI
- Slug: ddd-effect-rust-providers-cli
- Stage: techspec
- Estado atual: approved
- Origem: PRD aprovado em `02-prd.md`, risk classification em `00-risk-classification.md`, discovery em `00-project-discovery.md`.
- Decisão: aprovado pelo humano em 2026-06-06; prosseguir para Tasks e Refinement obrigatório.
- Observação de Agent Team: subagentes não foram acionados porque o ambiente só permite spawn quando o usuário pede explicitamente delegação; esta Tech Spec incorpora revisões de arquitetura, segurança, contratos e testes no próprio documento.
## Visão técnica
A evolução deve preservar o CLI Rust como harness determinístico e transformar a arquitetura por fatias. A primeira fatia separa domínio, aplicação e infraestrutura dentro da mesma crate para reduzir risco. A segunda fatia introduz provider registry, config versionada e secret redaction. A terceira adiciona memória incremental auditável. A bridge Node+TypeScript com Effect.ts fica atrás de adapter opcional e não entra no caminho padrão offline.
A inspiração em Effect.ts deve ser traduzida para idioms Rust, não copiada literalmente. O core usa `Result<T, SddError>`, ports/traits, composition root e layers de runtime. Para composição assíncrona e middleware, a direção técnica é usar `tokio` para runtime async e avaliar `tower::Service`/`tower::Layer` para retry, timeout, telemetry e redaction ao redor de providers. Effect.ts entra no lado TypeScript apenas quando houver orquestração JS que se beneficie de Layers, resource safety e tracing do ecossistema Effect.
## Arquitetura
### Estado atual
- `src/main.rs` concentra parsing CLI, domínio, IO, rendering, artifact store, installer, clients, hooks e testes unitários.
- `Cargo.toml` expõe apenas um binário `sdd`.
- `build.rs` empacota arquivos gerenciados e ignora `docs/<orquestracao>/`.
- Não há workspace Node/TypeScript.
### Arquitetura alvo incremental
Primeira entrega mantém uma crate para evitar churn de packaging:
```text
src/
main.rs # composition root e Cli::parse
cli/ # clap args, command dispatch fino
domain/
artifact.rs # ArtifactStage, ArtifactState, ArtifactIndex
orchestration.rs # OrchestrationId, Checkpoint, Stage
risk.rs # RiskResult, RiskFactor, RiskPolicy
provider.rs # ProviderId, ModelId, Capability, AuthRef
memory.rs # MemoryEvent, Learning, EvidencePointer
application/
artifact_service.rs
orchestration_service.rs
provider_service.rs
memory_service.rs
client_surface_service.rs
runtime/
effect.rs # SddRuntime, Layer, Scope, Clock, Telemetry
errors.rs # SddError e Result alias
redaction.rs # Secret<T>, RedactedDisplay, scrubbers
infrastructure/
fs_store.rs
process_runner.rs
http_client.rs
providers/
openai_responses.rs
claude_agent.rs
gemini_generate_content.rs
opencode_gateway.rs
custom_openai.rs
node_effect_bridge.rs
packaging/
embedded.rs
install.rs
update.rs
```
Depois que essa divisão estabilizar, avaliar workspace:
```text
crates/sdd-core
crates/sdd-cli
crates/sdd-provider
crates/sdd-packaging
bridges/effect-ts
```
### Bounded contexts
- `cli`: entrada humana e resolução de flags/env/config.
- `orchestration`: fluxo SDD, checkpoints, estados e estágios.
- `artifact_store`: arquivos `docs/<slug>/`, schemas e traceability map.
- `risk`: classificação, políticas e evidências mínimas.
- `providers`: registry, capabilities, auth refs, requests/responses e adapters.
- `memory`: index derivado de artefatos aprovados/registrados.
- `clients`: Codex, Claude Code, opencode, Cursor, Devin, Antigravity, Trae.
- `install_update`: pacote embutido, preservação de estado local e migração.
- `hooks`: guardrails determinísticos e auditoria local.
### Runtime Effect-like em Rust
- `SddRuntime` agrega ports: filesystem, process runner, clock, telemetry, provider registry, artifact store e memory index.
- `Layer` representa dependências construíveis e substituíveis em teste.
- `Scope` registra cleanup explícito para arquivos temporários, processos e streams; não depender de async drop implícito.
- `SddError` substitui `anyhow` gradualmente nas camadas de domínio/aplicação; `anyhow` pode permanecer no boundary CLI até a migração fechar.
- Middleware de provider: redaction, timeout, retry, budget, telemetry e rate-limit.
### Bridge Node+TypeScript com Effect.ts
- Diretório opcional: `bridges/effect-ts/`.
- Protocolo: JSONL ou JSON request/response sobre stdin/stdout via `ProcessRunner`.
- Envelope estável:
```json
{
"schema_version": "sdd.bridge.v1",
"operation": "orchestration_step",
"provider": "claude",
"model": "configured-model",
"input": {},
"capabilities": ["tools", "streaming"],
"redaction": { "secrets": "env-only" }
}
```
- O CLI deve funcionar sem Node quando `bridge.enabled=false`.
- A bridge não lê secrets diretamente de arquivos do SDD; recebe apenas nomes de env vars ou tokens injetados em memória pelo processo pai quando estritamente necessário.
## Contratos
### CLI
Adicionar flags compartilhadas em comandos que podem chamar modelo:
```bash
sdd orchestration --provider claude --model "<model-id>" "<ideia>"
sdd prd --provider codex --model "<model-id>" --name "<ciclo>" "<entrada>"
sdd providers list
sdd providers doctor
sdd providers doctor --json
sdd memory status
sdd memory learn --name "<ciclo>"
```
Precedência:
```text
flags CLI > variáveis de ambiente > sdd.config.yaml > defaults sem rede
```
### Config
Adicionar bloco backward-compatible em `sdd.config.yaml` e presets:
```yaml
providers:
default: codex
offline_default: deterministic
profiles:
codex:
kind: openai_responses
base_url: https://api.openai.com/v1
auth_env: OPENAI_API_KEY
default_model: ""
capabilities: [text, json_schema, tools, streaming]
timeout_ms: 60000
retries: 2
token_budget: 12000
enabled: true
claude:
kind: claude_agent_sdk
auth_env: ANTHROPIC_API_KEY
default_model: ""
capabilities: [text, tools, streaming]
enabled: false
gemini:
kind: gemini_generate_content
auth_env: GEMINI_API_KEY
default_model: ""
capabilities: [text, multimodal]
enabled: false
opencode:
kind: opencode_gateway
auth_env: OPENCODE_API_KEY
default_model: ""
capabilities: [text, tools]
enabled: false
custom:
kind: openai_compatible
base_url: ""
auth_env: SDD_CUSTOM_PROVIDER_API_KEY
default_model: ""
capabilities: [text]
enabled: false
runtime:
node_effect_bridge:
enabled: false
command: pnpm
args: ["--dir", "bridges/effect-ts", "start"]
memory:
learning_enabled: true
index_path: .sdd/memory/learnings.jsonl
sources: [approved_artifacts, recorded_artifacts]
redact_secrets: true
```
### Provider port
Contrato Rust proposto:
```rust
pub trait ModelProvider {
fn id(&self) -> &ProviderId;
fn capabilities(&self) -> &[Capability];
fn complete(&self, request: ProviderRequest) -> ProviderFuture;
}
```
`ProviderFuture` deve ser object-safe sem forçar macro no primeiro passo:
```rust
pub type ProviderFuture =
Pin<Box<dyn Future<Output = Result<ProviderResponse, ProviderError>> + Send>>;
```
### Provider request/response
- `ProviderRequest`: stage, orchestration id, prompt, system/developer context, model, token budget, tool policy, output format, timeout.
- `ProviderResponse`: text, structured payload opcional, usage opcional, provider metadata redigida, finish reason.
- `ProviderError`: auth_missing, auth_invalid, rate_limited, timeout, unsupported_capability, invalid_request, provider_unavailable, unsafe_output, unknown.
### Memory contracts
- Fonte canônica continua sendo `docs/<slug>/` e `traceability-map.yaml`.
- `.sdd/memory/learnings.jsonl` é cache derivado e reconstruível.
- Cada learning precisa de `source_artifact`, `source_hash`, `confidence`, `created_at`, `summary`, `recommendation`, `applies_to`.
- Não armazenar prompt completo de usuário se ele não estiver em artefato aprovado/registrado.
## Dados
### Persistência
- `sdd.config.yaml`: novo bloco `providers`, `runtime` e `memory`.
- `sdd.config.example.yaml` e `presets/*.yaml`: defaults seguros, providers desabilitados quando exigirem secret.
- `schemas/provider-config.schema.json`: novo schema opcional para validar provider config.
- `.sdd/memory/learnings.jsonl`: índice derivado; pode ser removido e reconstruído.
- `docs/<slug>/traceability-map.yaml`: registrar provider/model usado somente por identificador, nunca segredo.
### Compatibilidade
- Configs antigas sem `providers` seguem válidas.
- `sdd doctor` deve emitir warning informativo, não failure, quando não houver provider remoto e o comando não exigir rede.
- `sdd update` preserva blocos `providers`, `runtime` e `memory` existentes, como já preserva estado local.
### Consumers
- CLI humano.
- Surface agents que chamam `sdd`.
- Hooks e `sdd ci`.
- Projetos instalados que versionam `sdd.config.yaml`, `.sdd/`, `AGENTS.md` e superfícies de clientes.
## Segurança
- Secrets são representados por `AuthRef::Env("OPENAI_API_KEY")`, nunca por valor.
- `Secret<T>` não implementa `Display`; logs usam `RedactedDisplay`.
- Scrubber central remove padrões de API key conhecidos e valores lidos de env antes de gravar stdout, artifacts, events ou memory.
- `providers doctor --json` retorna `present: true|false`, `source: env`, `name: OPENAI_API_KEY`; nunca retorna valor.
- Não ler arquivos de auth de terceiros por padrão. Para opencode, preferir env var ou subprocesso isolado; qualquer leitura de auth store local exige design próprio e checkpoint de segurança.
- Node bridge recebe somente envelope redigido; se precisar token em runtime, ele entra como env do subprocesso e não no payload.
- Testes negativos obrigatórios: secret em env não aparece em stdout, stderr, traceability, memory, review, events ou JSON.
## Performance
- Comandos determinísticos (`init`, `doctor`, `clients`, `artifact`, `validate-artifact`, `ci`) não devem inicializar HTTP client nem Node bridge.
- Provider calls usam timeout configurável e retry limitado; default sem rede deve ser rápido.
- Memory learning deve ser incremental por hash de artefato para evitar reprocessar tudo.
- Node bridge usa subprocesso sob demanda inicialmente; daemon persistente só depois de métricas provarem necessidade.
- `tower::Layer`/middleware pode centralizar timeout/retry/rate-limit sem espalhar lógica por adapter.
## Observabilidade
- Introduzir eventos estruturados redigidos:
```json
{
"event": "provider.request",
"provider": "claude",
"model": "configured-model",
"stage": "techspec",
"orchestration": "ddd-effect-rust-providers-cli",
"duration_ms": 1234,
"status": "ok",
"redacted": true
}
```
- `sdd providers doctor --json` deve ser estável para CI.
- `sdd memory status --json` mostra número de learnings, fontes indexadas, arquivos pendentes e último erro redigido.
- `sdd ci` deve validar JSON/schema/provider config sem chamar rede.
## Testes
- Unitários:
- parsing de `ProviderId`, `ModelId`, `Capability`, `AuthRef`.
- precedência flags/env/config/default.
- redaction de secrets reais e padrões conhecidos.
- serialização/deserialização de provider config.
- risk classifier reconhecendo `token`, `tokens`, `provider`, `api key`, `secret`.
- Integração CLI:
- `sdd providers list` sem config.
- `sdd providers doctor --json` com env presente/ausente.
- `sdd orchestration --provider custom --model test-model --dry-run`.
- comandos offline existentes continuam passando sem Node.
- `sdd update` preserva providers customizados.
- Contrato provider:
- fake provider local para sucesso, timeout, rate limit, auth missing e unsupported capability.
- nenhum teste CI depende de rede real.
- Bridge Node:
- teste ignorado ou feature-gated quando Node indisponível.
- teste de envelope JSON e falha redigida.
- Memory:
- indexa artefatos registrados/aprovados.
- ignora drafts quando configurado para fontes aprovadas.
- reconstrói cache por hash.
Comandos mínimos antes de merge:
```bash
cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release
target/release/sdd ci
```
## Riscos
- Refactor amplo: mitigar com módulos internos antes de workspace.
- Drift de APIs externas: isolar adapters e capabilities; documentação de provider fica em referência, não espalhada.
- Vazamento de secrets: bloquear com tipos e testes negativos.
- Node obrigatório sem querer: manter bridge desabilitada e comandos offline sem dependência Node.
- Provider "codex" ambíguo: documentar como perfil OpenAI/Codex inicialmente; separar `codex_cli` no futuro se houver contrato diferente.
- Memória opaca: memory index precisa ser derivado, auditável, reconstruível e apontar para artifacts.
## Plano de implementação
1. Preparar domínio e runtime mínimo sem mudar comportamento:
- Criar módulos `domain`, `application`, `runtime`, `infrastructure`.
- Mover tipos puros de artifact/risk/stage gradualmente.
- Manter comandos existentes e testes verdes.
2. Introduzir provider config e registry offline:
- Adicionar structs, parser, defaults e schema.
- Implementar `sdd providers list` e `sdd providers doctor`.
- Adicionar redaction central e testes negativos.
3. Conectar provider selection aos stages em modo dry-run/determinístico:
- Flags `--provider`, `--model`, `--offline`.
- Registrar provider/model redigidos no artifact metadata.
- Não chamar rede ainda sem adapter explícito.
4. Implementar adapters conhecidos por trás de feature/config:
- `openai_responses`/Codex-compatible.
- `gemini_generate_content`.
- `claude_agent_sdk` ou adapter equivalente aprovado no Refinement.
- `custom_openai`.
- `opencode_gateway` como integração isolada e conservadora.
5. Implementar memória incremental:
- `sdd memory status`, `sdd memory learn`.
- JSONL derivado com hashes e evidence pointers.
- Recomendações integradas a `sdd context recommend`.
6. Adicionar bridge Node+Effect.ts opcional:
- Criar `bridges/effect-ts` somente quando os adapters Rust não cobrirem o caso.
- Definir envelope JSON e testes feature-gated.
7. Atualizar pacote e docs:
- README, docs, clients, presets, schemas, examples.
- `sdd update` preservando blocos novos.
8. Refinement obrigatório:
- Quebrar em tasks pequenas, estimar, definir rollout e rollback.
- Confirmar quais adapters entram no MVP.
## Referências técnicas
- Effect.ts: https://effect.website/docs/getting-started/introduction/
- Effect Layers: https://effect.website/docs/requirements-management/layers/
- Tower Service/Layer: https://docs.rs/tower/latest/tower/
- Tokio runtime: https://docs.rs/tokio/latest/tokio/
- Reqwest HTTP client: https://docs.rs/reqwest/latest/reqwest/
- Serde derive: https://serde.rs/derive.html
- OpenAI Responses API: https://platform.openai.com/docs/api-reference/responses/object
- Claude Agent SDK: https://code.claude.com/docs/en/agent-sdk/overview
- Gemini generateContent: https://ai.google.dev/api/generate-content
- opencode providers: https://opencode.ai/docs/providers/