# ADR: Decisão Provisória Sobre `idField` no `TableAuthoringDocument`

## Status

Proposto

## Contexto

Durante o desenho do `tableEditorCapability`, surgiu uma ambiguidade estrutural sobre `idField`.

No código atual de `praxis-table`, `idField` aparece em dois papéis:

- como resolução operacional do host/runtime para identificar linhas;
- como metadado persistido em `config.meta.idField` em alguns fluxos de apply/save.

Isso cria ambiguidade arquitetural:

- se `idField` for binding operacional, ele deve viver fora do `TableConfig` canônico;
- se `idField` for semântica persistível do componente, ele deve viver no `TableConfig` e não em bindings paralelos.

Enquanto essa decisão não for estabilizada, o contrato do documento de autoria permanece frágil.

## Decisão

Para o piloto de `praxis-table`, adotar temporariamente `idField` como parte de `bindings`, não como parte obrigatória de `config.meta`.

Shape provisório:

```ts
interface TableBindings {
  resourcePath?: string | null;
  idField?: string;
  horizontalScroll?: 'auto' | 'wrap' | 'none';
}

interface TableAuthoringDocument {
  kind: 'praxis.table.editor';
  version: 1;
  config: TableConfig;
  bindings?: TableBindings;
}
```

## Regras decorrentes

1. O documento persistível de autoria deve serializar `bindings.idField`, não depender de `config.meta.idField`.
2. O parser de legado pode ler `config.meta.idField` e migrar para `bindings.idField`.
3. `toCanonicalConfig()` não deve reescrever `config.meta.idField` por padrão.
4. Se o runtime quiser persistir `meta.idField` por compatibilidade, isso deve ser decisão explícita do adapter/save flow, não efeito implícito da capability.
5. A revisão futura deve decidir se:
   - `idField` permanece binding de integração, ou
   - `idField` sobe para semântica persistível do `TableConfig`.

## Motivo da decisão

Essa opção minimiza acoplamento prematuro com a semântica atual do runtime e evita consolidar como padrão algo que ainda parece misturar:

- identidade persistível do componente
- integração com dataset/servidor

Também permite migrar o protocolo sem bloquear o piloto do `tableEditorCapability`.

## Consequências

### Positivas

- simplifica a primeira iteração do documento canônico;
- evita duplicação automática entre `bindings.idField` e `config.meta.idField`;
- deixa explícito que a decisão definitiva ainda está em aberto.

### Negativas

- o piloto conviverá temporariamente com duas representações possíveis de `idField`;
- adapters de compatibilidade talvez precisem continuar lendo/escrevendo `meta.idField` por um tempo;
- a generalização cross-component ainda não fica fechada.

## Critério para revisão futura

Antes de promover o modelo como padrão do ecossistema, revisar esta ADR e decidir de forma definitiva:

1. `idField` é binding operacional do host?
2. `idField` é semântica persistível do componente?
3. existe necessidade real de ambos?

Sem essa decisão, o contrato do documento continua semanticamente ambíguo.