# ADR-041 — Sementes (seeds) são exclusivamente demonstração

| Campo | Valor |
|---|---|
| **Status** | Aceito (2026-10-18) |
| **Data** | 2026-10-18 |
| **Plano de origem** | decisão do dono (revisão F5, 2026-10-18) |
| **Relacionadas** | ADR-001, ADR-003, ADR-013, ADR-014, ADR-015, ADR-017 |

## Contexto

A ADR-017 (§10) já dizia que *seeders são só demonstração, nunca pré-requisito*. Na prática, porém,
as sementes viviam **dentro** das camadas de produção — `modules/*/Database/Seeders/`,
`services/*/Seeders/`, `core/**/Seeders/` — e o `CoreDatabaseSeeder` importava uma delas. Isso
misturava dado ilustrativo com código de domínio:

- **Dependência acidental:** código de produção (ou o boot) podia acabar referenciando uma semente.
- **Fronteira borrada:** o gate de fronteiras e o token grep-friendly (ADR-004/013) precisavam
  **isentar** `Database/Seeders` — sintoma de que a semente não pertencia ali.
- **Métrica poluída:** a cobertura de `src/` contava sementes (0% cobertas) como código de domínio.
- **Ambiente novo frágil:** confundia-se *bootstrap* (referência vinda da migration) com *demo*.

## Decisão

1. **Semente é exclusivamente demonstração.** Não é bootstrap, não é pré-requisito, não é
   referência. Dado de referência vem da **migration/implementação** (ADR-017).
2. **Nenhum código de produção depende de uma semente.** O domínio (`core`/`services`/`layout`/
   `modules`) **nunca** importa `Demonstration\*`.
3. **Local canônico único:** `src/demonstration/{Module}/{Seed}.php` — namespace
   `Demonstration\{Module}` (PSR-4 `Demonstration\` → `src/demonstration/`). Fora das 4 camadas
   (ADR-003/013), fora dos módulos e dos services.
4. **Orquestrador:** `src/demonstration/CoreDatabaseSeeder.php` (`Demonstration\CoreDatabaseSeeder`)
   é o alvo do `db:seed` (bind em `CoreServiceProvider`) e do `migrate:fresh --seed`.
5. **Idempotência obrigatória** (ADR-001/017): chave natural (`firstOrCreate`/`updateOrCreate`);
   rodar duas vezes não duplica.
6. **Ponto de entrada único de demo:** `php artisan db:seed` (também usado pelo E2E). É a única forma
   suportada de popular demonstração.
7. **Métrica:** `src/demonstration/` é **excluído da cobertura de testes** (não é código de
   produção), mas **continua sob análise estática** (PHPStan) e é **exercitado por testes** —
   sementes quebradas ainda quebram o `make check`.
8. **Sem HTML/CSS** em semente (ADR-017) e **sem URL de CDN** (ADR-002): imagem real entra pelo
   service de Media (ADR-026).

## Justificativa (alternativas descartadas)

- **Sementes dentro do módulo/service** (`Database/Seeders`) — descartada: acopla demo a produção,
  exige isenção de gates e polui a cobertura.
- **Remover sementes por completo** — descartada: demonstração e E2E precisam de dados ilustrativos
  determinísticos; o problema é o *lugar*, não a existência.
- **Semente como bootstrap** (sem migration) — descartada: ambiente novo ficaria dependente de demo
  (ADR-017 §10).

## Consequências

**Positivas**
- Fronteira limpa: módulos/services/core sem dado ilustrativo; gates deixam de isentar seeders.
- Ambiente novo sobe só com `migrate` (sem seed); demo é explícita (`php artisan db:seed`).
- Cobertura mede **só** código de produção.

**Custos / negativas**
- Uma pasta a mais fora das 4 camadas (`src/demonstration/`) — deliberada e documentada.
- Ao criar um módulo, a semente (se houver) nasce fora dele; o gerador não cria sementes.

## Exemplo mínimo (comparativo)

```
// ❌ semente acoplada à camada de produção
src/modules/Publicacoes/Noticias/Database/Seeders/NoticiaSeeder.php   // Modules\Publicacoes\...
src/services/Layout/Seeders/LayoutProfileSeeder.php                   // Services\Layout\...
src/core/Internal/CoreDatabaseSeeder.php                              // importa a semente

// ✅ semente isolada, só demonstração
src/demonstration/Noticias/NoticiaSeeder.php        // Demonstration\Noticias\NoticiaSeeder
src/demonstration/Layout/LayoutProfileSeeder.php    // Demonstration\Layout\LayoutProfileSeeder
src/demonstration/CoreDatabaseSeeder.php            // Demonstration\CoreDatabaseSeeder
```

## Verificação

- `grep -rn "Demonstration\\\\" src/{core,services,layout,modules}` → só o **bind** em
  `CoreServiceProvider` (nenhuma outra referência de produção).
- `migrate:fresh` **sem** seeder deixa o sistema utilizável; `php artisan db:seed` 2× não duplica.
- `make check` verde (PHPStan analisa `src/demonstration`; testes exercitam as sementes).

## Referências

- `wiki/specs/10-migracoes-e-dados.md`; `wiki/plan/08-servicos-headless-persistencia.md`;
  `wiki/plan/13-modulo-piloto-blueprint.md`; ADR-017.