# Checklist de Completude: `TableAuthoringDocument`

## Objetivo

Este checklist existe para validar se o `TableAuthoringDocument` é realmente canônico.

Regra central:

> O documento persistível precisa carregar tudo que é semanticamente necessário para reconstruir o estado aplicado da tabela, sem depender do estado previamente aplicado do componente.

Se qualquer item abaixo depender de fallback vindo do runtime anterior, o round-trip ainda está incompleto.

## Critério de aceite

O documento será considerado completo quando:

1. editor visual e editor JSON produzirem o mesmo envelope persistível;
2. `toCanonicalConfig(document, context)` for suficiente para reconstruir o estado aplicado;
3. `buildApplyPlan(...)` não depender de `previousAppliedState` como mecanismo arquitetural;
4. o runtime adapter apenas executar o plano, sem recompor semântica ausente.

## Itens obrigatórios

### 1. Envelope persistível

- [ ] O JSON oficial de autoria é o envelope versionado (`kind`, `version`, `config`, `bindings`).
- [ ] O editor JSON da tabela edita esse envelope, não `TableConfig` cru.
- [ ] O editor visual devolve esse mesmo envelope.
- [ ] O parser aceita payload legado `__resourcePath__`, `__idField__`, `__horizontalScroll__`, mas a serialização nova não escreve esses campos.

### 2. Config principal

- [ ] `config.columns` é emitido integralmente pelo documento.
- [ ] `config.behavior` é emitido integralmente pelo documento.
- [ ] `config.toolbar`, `config.actions`, `config.export`, `config.messages`, `config.dialogs` e demais áreas editáveis são emitidas integralmente pelo documento.
- [ ] Nenhuma área semanticamente relevante depende de defaults implícitos não determinísticos do runtime.

### 3. Bindings persistíveis

- [ ] `resourcePath` tem representação canônica única em `bindings`.
- [ ] `horizontalScroll` tem representação canônica única em `bindings`.
- [ ] `idField` tem decisão provisória/documentada e não fica “metade bindings, metade meta” sem regra explícita.

### 4. `advancedFilters.settings`

- [ ] `advancedFilters.settings` é parte do documento quando semanticamente necessário.
- [ ] O pipeline visual da tabela reemite `advancedFilters.settings` de forma completa.
- [ ] `toCanonicalConfig()` não precisa buscar `advancedFilters.settings` no estado anterior do componente.
- [ ] `applyTableConfig()` não depende mais de fallback implícito baseado no estado interno previamente aplicado.

### 5. Coerções contextuais

- [ ] Coerção de `pagination.strategy` e `sorting.strategy` em modo local acontece em `toCanonicalConfig()`, não em `normalizeDocument()`.
- [ ] Essa coerção é puramente determinística e depende apenas de `document + projection context`.
- [ ] A coerção não reescreve silenciosamente o documento persistível.

### 6. Metadados de servidor

- [ ] `serverIdField`, `schemaId`, `schemaHash` não fazem parte do documento persistível por padrão.
- [ ] Divergências com servidor são tratadas como diagnóstico via contexto de validação.
- [ ] Anexar `schemaId`/`schemaHash` ao config persistido, quando necessário, é decisão explícita do runtime adapter/save flow.

### 7. Persistência paralela

- [ ] O design considera explicitamente artefatos persistidos fora do `TableConfig`.
- [ ] Overrides CRUD fora do `TableConfig` têm estratégia definida:
  - ou entram no documento de autoria,
  - ou permanecem explicitamente fora do escopo do piloto.
- [ ] Dirty state do editor não depende de informação que o documento não consegue representar.

## Itens de revisão arquitetural

### Documento

- [ ] O documento contém somente informação persistível e round-trippable.
- [ ] Nada transitório do host/sessão é serializado no envelope.
- [ ] A versão do documento está explícita e pronta para migração futura.

### Contexto

- [ ] Contexto de validação está separado de contexto de projeção.
- [ ] Contexto de runtime está separado de autoria.
- [ ] Nenhum dado transitório da execução vaza para o envelope persistível.

### Apply plan

- [ ] `buildApplyPlan(...)` produz um plano suficientemente explícito para o adapter não precisar recalcular a lógica principal.
- [ ] O plano informa diff suficiente para decisões de runtime relevantes.
- [ ] O adapter não recompõe semântica ausente do documento.

## Itens de teste obrigatórios

- [ ] `parseLegacyOrDocument()` migra corretamente payload legado.
- [ ] `serializeDocument()` nunca escreve campos `__...__`.
- [ ] `normalizeDocument()` é idempotente.
- [ ] `validateDocument()` acusa inconsistências estruturais do envelope.
- [ ] `toCanonicalConfig()` reconstrói config efetiva sem ler estado anterior do componente.
- [ ] `buildApplyPlan()` gera plano consistente para:
  - bind remoto
  - bind local/sem `resourcePath`
  - mudança de `horizontalScroll`
  - mudança de `idField`
  - mudança de `resourcePath`
- [ ] Editor visual -> serialize -> parse -> canonicalize produz o mesmo resultado que editor JSON -> canonicalize.

## Sinais de falha

Se qualquer um dos itens abaixo acontecer, o documento ainda não é canônico:

- o runtime precisa olhar para o estado anteriormente aplicado para “fechar” a configuração;
- o editor visual perde informação que o editor JSON preserva;
- o envelope persistido não basta para reproduzir o apply;
- `idField` ou outro campo crítico muda de significado conforme a superfície de edição;
- o adapter de runtime continua sendo o verdadeiro dono da inteligência semântica.

## Decisão prática do piloto

Antes de promover a arquitetura como padrão do ecossistema, este checklist deve estar majoritariamente verde no `praxis-table`.

Enquanto houver dependência real de recomposição por estado anterior, especialmente em `advancedFilters.settings`, a arquitetura deve ser tratada como piloto e não como padrão fechado.