👻 Spectre-Driven Development

Um paradigma event-native onde o cockpit do desenvolvedor (Neoland) emite e consome os mesmos eventos que a frota de IA (SPECTRE).

Status: Concept v0.1
Componentes: Neoland (TUI Rust), SPECTRE (NATS JetStream), ADR-Ledger, PHANTOM, CEREBRO
Repositórios: neoland · spectre

🎯 Tese

Se serviços já conversam por eventos versionados, o desenvolvedor também deveria — o IDE/CLI vira cidadão de primeira classe do barramento.

1. Por que existe

O desenvolvimento moderno vive uma assimetria esquisita: microsserviços de produção já são event-driven, mas o dev loop (editor → CLI → run → log) permanece síncrono, baseado em stdout e captura ad-hoc. O desenvolvedor observa a frota por terceiro ombro: dashboards externos, tail de arquivos, agentes paralelos que não falam a mesma língua dos serviços.

Spectre-Driven Development (SDD) inverte essa relação: o cockpit do dev é Neoland, um cliente TUI Rust nativo do barramento NATS da SPECTRE. Cada ação relevante — abrir um chat, disparar uma inferência, aceitar um ADR, examinar VRAM — emite ou consome eventos tipados no mesmo stream da produção.

💡 SDD não é “IDE com plugin de Kafka”. É um contrato operacional: se um evento existe em prod, o dev o observa localmente com a mesma semântica — rastreável, versionável, auditável.

2. Princípios

Paridade de barramento: Tudo que acontece em prod tem espelho local. Nenhum evento é “apenas de debug”.
Eventos são o log: system.log.v1, llm.request.v1, vram.status.v1 substituem println! como sinal primário.
Governance-in-the-loop: Comandos que tocam políticas (adr accept, mudança de modelo) são validados contra knowledge_base.json antes de publicar no bus.
Zero-trust por default: Neoland se autentica com API key RBAC + HashiCorp Vault; cada evento carrega correlation_id e trace_id.
Fallback local-first: Se SPECTRE estiver offline, Neoland cai para infência local (Qwen 1.8B via ml-offload-api) e buffers eventos para replay.

3. Arquitetura

flowchart LR
	classDef dev fill:#1e1b4b,stroke:#a855f7,color:#fff;
	classDef bus fill:#312e81,stroke:#818cf8,color:#fff;
	classDef svc fill:#064e3b,stroke:#10b981,color:#fff;
	classDef gov fill:#451a03,stroke:#f59e0b,color:#fff;

	DEV["Neoland TUI<br>(ratatui + tokio)"]:::dev
	PROXY["spectre-proxy<br>zero-trust gateway"]:::bus
	BUS["NATS JetStream<br>event spine"]:::bus
	ADR["ADR-Ledger<br>policy gate"]:::gov
	PH["PHANTOM<br>local inference"]:::svc
	CB["CEREBRO<br>credit gate"]:::svc
	OBS["spectre-observability<br>TimescaleDB + Neo4j"]:::bus

	DEV -- "API key + mTLS" --> PROXY
	PROXY --> BUS
	BUS -- "llm.request.v1" --> PH
	BUS -- "llm.request.v1 (overflow)" --> CB
	BUS -- "governance.vote.v1" --> ADR
	BUS -- "*" --> OBS
	OBS -- "metrics stream" --> DEV

Neoland não fala HTTP direto com PHANTOM ou CEREBRO. Toda interação passa pelo spectre-proxy, que aplica RBAC + rate-limit + audit log antes de publicar no JetStream.

4. Contrato de Eventos (Dev ↔ Bus)

Evento	Direção	Ação do Dev	Consumido por / Resultado
`llm.request.v1`	Pub	Enviar prompt	PHANTOM / CEREBRO → `llm.response.v1` (Streaming chat Neoland TUI)
`inference.request.v1`	Pub	Rodar classificação	PHANTOM → `vram.status.v1` (Monitor live no header da TUI)
`system.metrics.v1`	Sub	Status do sistema	Neoland status line → `cost.incurred.v1` (FinOps pane)
`governance.proposal.v1`	Pub	`adr new` do dev	ADR-Ledger + peers → `governance.vote.v1` (Multi-sig approval)
`quality.report.v1`	Sub	Peer review auto	Neoland inbox → `hyprland.window.v1` (Context-switch hook)

5. Dev Loop Canon

sequenceDiagram
	participant D as Dev (Neoland TUI)
	participant P as spectre-proxy
	participant B as NATS JetStream
	participant A as ADR-Ledger
	participant F as PHANTOM
	participant C as CEREBRO
	participant O as Observability

	D->>P: API key + request (ctrl+enter)
	P->>B: publish llm.request.v1
	B->>A: policy-check (consent, budget)
	A-->>B: ok / veto
	B->>F: route (local-first)
	F-->>B: llm.response.v1 (stream)
	B-->>D: render tokens (SSE-like)
	F->>C: overflow if VRAM > 92%
	C-->>B: credit-validated cloud call
	B->>O: all events tapped
	O-->>D: vram.status.v1 / cost.incurred.v1

Cada keystroke significativo vira evento; cada evento vira linha no audit log; cada linha vira input para o próximo ADR.

6. Superfície Neoland (Mapeada)

Painel TUI	Eventos que Consome	Comando
Chat stream	`llm.response.v1`	`Ctrl+Enter`
System status	`system.metrics.v1`	Automático
ADR inbox	`governance.proposal.v1`	`Ctrl+G`
Presets 1–5	Profiles via TOML	`Ctrl+1..5`

7. Segurança & Governança

RBAC 3-tier: Admin > User > ReadOnly em todo endpoint do spectre-proxy.
Vault 3-tier: Cache 30s → Vault read → env fallback para API keys.
Audit log JSON append-only: 15 tipos de ação, PII sanitizada automática, alerta de brute force (>5 falhas/min).
Input validation: 100 KB prompt max, 1 MB request, null-byte strip, path-traversal guard.
ADR-0011…014: Formalizam essas decisões no ledger.

8. Roadmap SDD

v0.1 Neoland TUI: ratatui + crossterm, 5 presets, Tokyo Night.
v0.1 SPECTRE core: spectre-core + spectre-events + 30+ schemas.
v0.2 Bus nativo: Neoland consome vram.status.v1 + cost.incurred.v1 direto do JetStream (hoje: REST).
v0.3 Replay buffer: Offline → flush automático ao reconectar.
v0.4 ADR workflow: Ctrl+G abre editor de ADR, valida contra OPA, publica governance.proposal.v1.
v0.5 Cockpit multi-tenant: Um Neoland por dev, dashboards agregados em Neo4j.
v1.0 Mainstream: Documentação publicada na wiki e pacote em nixpkgs unstable.

9. Relação com o Paper (Source)

Este documento é o vetor 7.1 do paper Source (Modular Intelligent Stack with NixOS). Formaliza como o dev loop deixa de ser side-channel e passa a ser parte da mesma topologia event-driven governada por ADRs.

🧩 Resumo em uma frase: Spectre-Driven Development é desenvolvimento feito dentro do barramento, não contra ele.

🎯 Tese​

1. Por que existe​

2. Princípios​

3. Arquitetura​

4. Contrato de Eventos (Dev ↔ Bus)​

5. Dev Loop Canon​

6. Superfície Neoland (Mapeada)​

7. Segurança & Governança​

8. Roadmap SDD​

9. Relação com o Paper (Source)​