@praxisui/table 8.0.0-beta.2 → 8.0.0-beta.21

package/README.md

@@ -163,6 +163,15 @@ Filtro runtime:
 - The default is `false`; hosts opt in when they want settings, authoring affordances and schema-drift UX.
 - Customization mode does not change the table data mode. It only gates configuration/editorial surfaces.
 
+## Praxis Semantic Assistant
+
+- The table assistant is part of the global Praxis semantic copilot experience, not a standalone table patch bot.
+- In customization mode, opening the assistant registers a `PraxisAssistantContextSnapshot` through `PraxisAssistantSessionRegistryService`.
+- The table session identity follows `table:{routeKey}:{componentInstanceId || tableId}` so multiple tables on the same page can preserve separate assistant sessions.
+- Minimizing the table shell keeps a global minimized session that the App Shell can reopen; the App Shell does not interpret or execute table semantics.
+- The table snapshot stores only safe context: table identity, target, context chips, manifest reference, resource path, schema field names, data/runtime digests, capability refs and governance hints.
+- Prompts that indicate shared business decisions, such as rules, policies, compliance, LGPD, approval, eligibility or access control, must be routed to governed `domain-rules` handoff instead of local table config patches.
+
 ## Migration Note
 
 - This release treats `enableCustomization=false` as the canonical default.
@@ -274,6 +283,25 @@ rowConditionalStyles: [
 ]
 ```
 
+O editor especializado tambem persiste `effects: RuleEffectDefinition[]` em
+`rowConditionalStyles` e `columns[].conditionalStyles`. O runtime consome esses
+efeitos diretamente e ainda preserva `cssClass`/`style` como fallback de
+compatibilidade, mantendo o ciclo abrir -> aplicar/salvar -> reabrir sem exigir
+que consumidores recompilem manualmente os efeitos visuais.
+
+Para renderizacao condicional, `columns[].conditionalRenderers` tambem aceita
+`effects: RuleEffectDefinition[]` como fonte canonica para renderer, tooltip e
+animacao. `rowConditionalRenderers` fica tipado no contrato publico para tooltip
+e animacao de linha, preservando os campos planos `tooltip`/`animation` como
+fallback.
+
+Colunas calculadas usam `columns[].computed.expression` como AST JSON Logic
+canonico. Regras, estilos e renderers condicionais podem referenciar esses
+valores via `computed.<field>`. Quando uma coluna calculada depende de outra
+coluna calculada, o runtime resolve a ordem de avaliacao por dependencias
+declaradas ou referencias `var: "computed.<field>"`, evitando que o resultado
+dependa da ordem fisica de `columns[]`.
+
 ```scss
 .app-table .mat-mdc-row.app-row--priority-high {
   background: linear-gradient(
@@ -469,6 +497,24 @@ O chrome conversacional, `sessionId`, `clientTurnId`, respostas rapidas e ciclo
 por `PraxisAssistantTurnOrchestratorService`; a semantica especifica da tabela continua em `TableAiAdapter` e no
 `TableAgenticAuthoringTurnFlow`.
 
+## Agentic Authoring & Manifest
+
+Para acoes globais de `toolbar`, `row` e `bulk`, o authoring agentic aceita somente `GlobalActionRef` governado:
+`actionId`, `payload`, `payloadExpr` e `meta`. O schema bloqueia propriedades arbitrarias e mantem `payloadExpr`
+como escape avancado explicito, nao como objeto livre. Configuracoes novas devem persistir a acao em
+`effects[].kind = "global-action"` com `effects[].globalAction`; `globalAction` plano permanece apenas como fallback
+de compatibilidade para documentos existentes.
+
+O `@praxisui/table` declara authoring agentic através de um `ComponentAuthoringManifest` canônico. O manifesto é a fonte versionada para descoberta de alvos, operações e validações de configuração da tabela.
+
+- **Component ID:** `praxis-table`
+- **Config Schema:** `TableConfig`
+- **Alvos Editáveis:** `column`, `computedColumn`, `renderer`, `conditionalRenderer`, `rowAction`, `toolbarAction`, `toolbar`, `filter`, `grouping`, `selection`, `export`, `appearance`, `expansion`, `rule`, `meta`, `bulkAction`, `contextAction`, `pagination`, `sorting`, `interaction`, `loading`, `emptyState`, `resizing`, `dragging`, `editing`, `messages`, `localization`, `performance`, `data`, `accessibility`.
+- **Famílias de Operações:** Operações com target resolvers próprios por operação, alinhadas ao contrato canônico de configuração da tabela e aos paths publicados pelo pacote.
+- **Validação:** Validadores determinísticos cobrem unicidade, integridade de caminhos, suporte a renderizadores, presets de formatação, segurança de estilos, segurança de resource binding somente em `expansion.detailSource.configure`, apresentação do detalhe expansível em `expansion.detailPresentation.configure`, e preservação de round-trip do editor.
+
+O manifesto (v2.0.0) é exportado como `PRAXIS_TABLE_AUTHORING_MANIFEST` e projetado no `ai_registry` como contrato canônico de authoring. Essa projeção não deve ser tratada como aprovação semântica automática: cada operação precisa manter evidência testada de target resolver, paths canônicos, efeitos coerentes e validators pertinentes ao que a operação realmente edita. O gate `validate:authoring-contracts` deve rejeitar cobertura nominal, como validators globais sem uso ou validators ligados a operações não relacionadas.
+
 ## 🚀 Instalação
 
 ```bash
@@ -502,7 +548,7 @@ Quando `resourcePath` é fornecido, a tabela se torna "inteligente":
 Neste exemplo:
 
 - `resourcePath="human-resources/departamentos"` instrui a tabela a se comunicar com o endpoint `/api/human-resources/departamentos`.
-- A tabela fará requisições como `POST /api/human-resources/departamentos/filter` para obter os dados e `GET /schemas/filtered?path=/api/human-resources/departamentos/all&operation=get&schemaType=response` para obter o schema estrutural usado no bootstrap das colunas.
+- A tabela fará requisições como `POST /api/human-resources/departamentos/filter` para obter os dados e `GET /schemas/filtered?path=/api/human-resources/departamentos/filter&operation=post&schemaType=response` para obter o schema estrutural usado no bootstrap das colunas.
 - `enableCustomization` controla explicitamente o gate de edição visual. O default canônico agora é `false`; declare `[enableCustomization]="true"` quando o host quiser expor customização e surfaces editoriais.
 
 ### Consulta Declarativa com `queryContext`
@@ -565,8 +611,8 @@ sequenceDiagram
 
     activate Crud_Service
     Crud_Service->>Crud_Service: schemaUrl() preserva o base path canônico
-    Crud_Service->>Crud_Service: Deriva path="/api/human-resources/departamentos/all"<br>operation="get", schemaType="response"
-    Crud_Service->>Docs_Controller: GET /schemas/filtered?path=.../all&operation=get&schemaType=response
+    Crud_Service->>Crud_Service: Deriva path="/api/human-resources/departamentos/filter"<br>operation="post", schemaType="response"
+    Crud_Service->>Docs_Controller: GET /schemas/filtered?path=.../filter&operation=post&schemaType=response
     deactivate Crud_Service
 
     activate Docs_Controller
@@ -938,7 +984,7 @@ onSchemaStatus(ev: { outdated: boolean; serverHash?: string; lastVerifiedAt?: st
 
 - O backend anota o schema com `x-ui.resource.idField` (e `idFieldValid`) via `/schemas/filtered`.
 - A tabela adota o campo identificador automaticamente com a seguinte precedência:
-  - `@Input() idField` → `crudContext.idField` → `config.meta.idField` (persistido) → `GenericCrudService.getResourceIdField()` (derivado do schema) → `'id'`.
+  - `config.meta.idField` (persistido) → contexto runtime/serviço derivado do schema → `'id'`.
   - Se `config.meta.idField` divergir do servidor, o componente alerta o usuário e mantém o valor do TableConfig até reconciliação.
 - A resolução ocorre no `loadSchema()` e também é considerada em tempo de execução para evitar corridas.
 - Para recursos cuja PK não é `id`, defina `getIdFieldName()` no controller backend correspondente.
@@ -956,12 +1002,12 @@ sequenceDiagram
 
   PT->>GS: configure(resourcePath)
   PT->>GS: getSchema()
-  GS->>GS: deriva path=/api/.../all + schemaType=response
-  GS->>Docs: GET /schemas/filtered?path=.../all&operation=get&schemaType=response
+  GS->>GS: deriva path=/api/.../filter + operation=post + schemaType=response
+  GS->>Docs: GET /schemas/filtered?path=.../filter&operation=post&schemaType=response
   Docs-->>GS: 200/304 schema + x-ui.resource.idField
   GS->>GS: cache + lastResourceMeta.idField
   GS-->>PT: FieldDefinition[] (normalizado)
-  Note over PT: idField = input || context || GS.getResourceIdField() || 'id'
+  Note over PT: idField = config.meta.idField || runtime/schema || 'id'
   PT->>PT: construir colunas e renderizar
 ```
 
@@ -986,7 +1032,7 @@ sequenceDiagram
 ### Troubleshooting rápido (idField)
 
 - A ação delete falhou por ID ausente: verifique se o schema contém `x-ui.resource.idField` e se a coluna correspondente existe no dataset.
-- O ID está em outra propriedade: defina `@Input() idField` ou `crudContext.idField` temporariamente; ajuste o backend com `getIdFieldName()` para persistir o comportamento.
+- O ID está em outra propriedade: defina `config.meta.idField` no TableConfig; ajuste o backend com `getIdFieldName()` para persistir o comportamento derivado do schema.
 - Cache 304 sem idField aplicado: confirme que o serviço recebeu o body pelo menos uma vez (200) e que `GenericCrudService.getResourceIdField()` retorna o valor esperado.
 
 ### Uso com Dados Locais (Client-Side)
@@ -1758,3 +1804,99 @@ Apache-2.0 — consulte `LICENSE` na raiz do workspace para detalhes.
 **Parte do Praxis UI Workspace**
 **Versão**: 2.0.0 (Unified Architecture)
 **Compatibilidade**: Angular 18+
+
+## Discovery contextual em ações por linha
+
+Use `actions.row.discovery.enabled=false` quando a tabela precisar operar em uma
+experiência corporativa estritamente curada pelo host. Nesse modo, o runtime
+mantém somente as ações declaradas em `actions.row.actions[]` e não adiciona
+ações descobertas dinamicamente por HATEOAS/capabilities.
+
+```ts
+actions: {
+  row: {
+    enabled: true,
+    display: 'buttons',
+    discovery: { enabled: false },
+    actions: [
+      { id: 'briefing', label: 'Briefing', action: 'inspect-surfaces' },
+      { id: 'capabilities', label: 'Capabilities', action: 'inspect-actions' },
+    ],
+  },
+}
+```
+
+O campo controla apenas a descoberta contextual de row actions. Ele não desativa
+`behavior.expansion.detail.source.mode="hypermedia"`; quando a expansão
+hypermedia estiver ativa, o detail ainda pode resolver `surfaces` e `actions`
+sob demanda ao expandir a linha. O default continua habilitado quando
+`actions.row.discovery.enabled` é omitido.
+
+## Row action para navegação interna
+
+Use `navigation.openRoute` quando a ação da linha precisar abrir uma rota
+interna levando o identificador do registro selecionado.
+
+```ts
+actions: {
+  row: {
+    enabled: true,
+    display: 'buttons',
+    discovery: { enabled: false },
+    actions: [
+      {
+        id: 'open-detail',
+        label: 'Abrir detalhe',
+        action: 'navigation.openRoute',
+        effects: [
+          {
+            kind: 'global-action',
+            globalAction: {
+              actionId: 'navigation.openRoute',
+              payload: {
+                path: '/clientes/detalhe',
+                query: {
+                  id: '${row.id}',
+                },
+              },
+            },
+          },
+        ],
+        globalAction: {
+          actionId: 'navigation.openRoute',
+          payload: {
+            path: '/clientes/detalhe',
+            query: {
+              id: '${row.id}',
+            },
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+O runtime da tabela resolve templates como `${row.id}` antes de executar a
+global action, o que permite reutilizar o mesmo contrato em `list` e `table`.
+Para configuracoes novas, `effects[].kind = 'global-action'` e o envelope
+canonico alinhado a `PraxisRuntimeGlobalActionEffect`; `globalAction` plano
+continua aceito como fallback de compatibilidade.
+O editor de acoes usa o mesmo adapter interno para toolbar, row e bulk actions:
+ao escolher novamente a mesma global action, ele preserva `payload` estruturado
+ou `payloadExpr` existente; ao trocar o `actionId`, ele descarta o payload antigo
+para evitar executar parametros de outra acao.
+
+As acoes por linha tambem usam Json Logic canonico para `visibleWhen` e
+`disabledWhen`. O editor de acoes preserva esses objetos no fluxo
+abrir -> aplicar/salvar -> reabrir, por exemplo:
+
+```ts
+{
+  id: 'edit-active',
+  label: 'Editar',
+  action: 'edit',
+  visibleWhen: { '===': [{ var: 'status' }, 'Ativo'] },
+  disabledWhen: { '===': [{ var: 'status' }, 'Bloqueado'] },
+}
+```

package/docs/DSL-Extensions-Guide.md

@@ -0,0 +1,23 @@
+# Guia Historico: Remocao da DSL Runtime
+
+O runtime DSL legado foi removido de `@praxisui/table`.
+
+Estado canonico atual:
+
+- JSON Logic e o unico contrato suportado para regras novas e para o editor de regras.
+- A tabela nao executa mais expressoes DSL em string no runtime.
+- Hosts que ainda possuam payloads DSL precisam migrar essas regras para JSON Logic antes de reutiliza-las.
+
+Nao existe mais:
+
+- registry publico de funcoes DSL
+- extensoes DSL publicas de data/JSON
+- path oficial de validacao DSL no runtime da tabela
+
+Para o caminho suportado, use:
+
+- [json-logic-operators-and-helpers.md](./json-logic-operators-and-helpers.md)
+- [praxis-table.json-api.md](../src/lib/praxis-table.json-api.md)
+- [table-rules-editor.component.ts](../src/lib/rules-editor/table-rules-editor.component.ts)
+
+Este arquivo permanece apenas para redirecionar links antigos que ainda apontavam para "DSL extensions".

package/docs/adr/2026-03-dynamic-filter-cross-lib-coupling.md

@@ -0,0 +1,107 @@
+---
+title: "ADR - Dynamic Filter as Cross-Library Feature"
+slug: "adr-dynamic-filter-cross-lib-coupling-2026-03"
+description: "Decisao de arquitetura para tratar o filtro dinamico como feature transversal entre table, dynamic-fields e metadata-starter, com documentacao e contrato coordenados."
+doc_type: "adr"
+document_kind: "adr-record"
+category: "architecture"
+audience:
+  - "frontend"
+  - "backend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "implemented"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "table"
+  - "dynamic-fields"
+  - "metadata-starter"
+  - "architecture"
+toc: true
+sidebar: true
+related_docs:
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-filter-troubleshooting-guide"
+last_updated: "2026-03-07"
+---
+
+# ADR: Dynamic Filter as Cross-Library Feature
+
+## Status
+
+`implemented`
+
+## Context
+
+Historicamente, o filtro dinâmico podia ser lido de forma fragmentada:
+
+- `table` como componente “dono” da experiência;
+- `dynamic-fields` como catálogo de controles;
+- `metadata-starter` como detalhe backend separado.
+
+Esse modelo é insuficiente para documentação e governança porque os problemas reais atravessam as três camadas.
+
+Exemplos concretos:
+
+- o `PraxisFilter` decide variantes inline e persistência local;
+- os campos `filter-*-inline` definem UX, acessibilidade e envelopes de interação;
+- o backend normaliza ranges e rejeita payload inválido com `FILTER_PAYLOAD_INVALID`.
+
+Se a documentação tratar essas partes como silos, o resultado é incompleto.
+
+## Decision
+
+Adotar oficialmente o filtro dinâmico como feature transversal do ecossistema Praxis.
+
+Isso implica:
+
+- a entrada principal de uso público continua em `@praxisui/table`;
+- contratos visuais e metadata dos inline continuam canônicos em `@praxisui/dynamic-fields`;
+- contrato HTTP, normalização e semântica operacional do payload devem citar explicitamente `praxis-metadata-starter`;
+- a documentação da feature deve ser pensada como trilha, e não como README solto por biblioteca.
+
+## Consequences
+
+### Positivas
+
+- documentação mais didática e completa;
+- troubleshooting mais rápido;
+- menos divergência entre frontend e backend;
+- maior clareza sobre onde documentar payload, range e settings.
+
+### Custos
+
+- manutenção documental coordenada entre bibliotecas;
+- necessidade de `related_docs` e slugs estáveis;
+- revisão mais cuidadosa quando a feature evoluir.
+
+## Non-goals
+
+- fundir fisicamente as bibliotecas;
+- mover os componentes inline para dentro de `table`;
+- duplicar documentação canônica entre libs.
+
+## Implementation Outline
+
+1. Manter `table` como ponto de entrada da jornada.
+2. Referenciar `dynamic-fields` como fonte de verdade para catálogo inline e metadata.
+3. Referenciar `metadata-starter` como fonte de verdade para payload backend e normalização.
+4. Publicar a trilha documental completa sob `projects/praxis-table/docs`.
+
+## Acceptance Criteria
+
+- trilha documental cobrindo arquitetura, integração host, payload, range, catálogo inline e troubleshooting;
+- referências explícitas ao `metadata-starter` nos documentos de contrato;
+- navegação consistente entre docs relacionados.
+
+## Source References
+
+- `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug publicado: `dynamic-fields-inline-components-guide`)
+- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java`
+- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java`

package/docs/adr/2026-03-filter-drawer-adapter-light-entrypoint.md

@@ -0,0 +1,105 @@
+---
+title: "ADR - Lightweight Filter Drawer Adapter Entrypoint for @praxisui/table"
+slug: "adr-table-filter-drawer-adapter-light-entrypoint-2026-03"
+description: "Decisao de arquitetura para expor um sub-entrypoint leve de filter drawer adapter em @praxisui/table e reduzir impacto de bundle inicial em apps host."
+doc_type: "adr"
+document_kind: "adr-record"
+category: "architecture"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "implemented"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "filter"
+  - "drawer"
+  - "adapter"
+  - "bundle"
+  - "entrypoint"
+toc: true
+sidebar: true
+last_updated: "2026-03-06"
+---
+
+# ADR: Lightweight Filter Drawer Adapter Entrypoint for `@praxisui/table`
+
+## Status
+
+`implemented`
+
+## Context
+
+Hosts que registram `FILTER_DRAWER_ADAPTER` no bootstrap podem carregar partes desnecessarias do pacote no `initial bundle`.
+
+No estado atual:
+- O token `FILTER_DRAWER_ADAPTER` e o contrato leve publicado vivem em `projects/praxis-table/filter-drawer-adapter/src/filter-drawer-adapter.ts`.
+- O barrel raiz (`projects/praxis-table/src/public-api.ts`) exporta tabela, filtro, editores e recursos adicionais.
+
+Resultado observado no issue cross-lib:
+- inflacao relevante de bundle inicial com adapters ativos.
+
+## Decision
+
+Adotar sub-entrypoint leve para o contrato do adapter:
+
+- Novo path de consumo recomendado: `@praxisui/table/filter-drawer-adapter`
+- Exportar somente:
+  - `FILTER_DRAWER_ADAPTER`
+  - `FilterDrawerAdapter`
+  - contratos minimos relacionados ao adapter
+
+Compatibilidade:
+- manter um unico caminho publico para consumo host via sub-entrypoint leve.
+- atualizar docs/boilerplates para usar o subpath leve.
+
+## Non-goals
+
+- Alterar comportamento de `PraxisFilter` em runtime.
+- Redesenhar o contrato funcional do adapter.
+
+## Implementation Outline
+
+1. Criar entrypoint secundario focado em adapter/token.
+2. Publicar o subpath via secondary entrypoint do `ng-packagr`.
+3. Atualizar docs de integracao e boilerplates para usar subpath leve.
+4. Medir bundle no host de referencia antes/depois.
+
+## Acceptance Criteria
+
+- Subpath novo publicado e adotavel em host.
+- Documentacao atualizada com recomendacao canonica.
+- Reducao relevante do `initial bundle` com adapters ativos (meta orientadora: `-40%` sobre baseline atual).
+
+Estado atual dos criterios:
+- Publicacao do subpath: concluida.
+- Documentacao canonica: concluida.
+- Benchmark de bundle no host de referencia: pendente.
+
+## Implementation Status
+
+- Implementado em `2026-03-06`:
+  - secondary entrypoint `projects/praxis-table/filter-drawer-adapter`
+  - export removido do barrel raiz `projects/praxis-table/src/public-api.ts`
+  - docs/boilerplates atualizados para recomendar `@praxisui/table/filter-drawer-adapter`
+- Validacao concluida nesta workspace:
+  - build da lib e publicacao do subpath em `dist/praxis-table/filter-drawer-adapter`
+- Medicao de bundle host:
+  - pendente de benchmark reproduzivel do host de referencia nesta workspace
+
+## Risks and Mitigations
+
+- Risco: diferenca pequena de bundle em alguns perfis de build.
+  - Mitigacao: capturar metricas por perfil (dev/prod) e registrar resultado real.
+- Risco: divergencia entre token interno e token publicado no sub-entrypoint.
+  - Mitigacao: garantir singleton compartilhado e validar identidade em spec dedicada.
+- Risco: boilerplates permanecerem em path inconsistente.
+  - Mitigacao: checklist de migracao em docs/templates e PRs de ajuste.
+
+## Source References
+
+- `projects/praxis-table/filter-drawer-adapter/src/filter-drawer-adapter.ts`
+- `projects/praxis-table/src/public-api.ts`
+- `docs/issues/drawer-adapters-bundle-entrypoints.md` (historico cross-lib)

package/docs/adr/2026-03-table-editor-idfield-decision.md

@@ -0,0 +1,85 @@
+# 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.