@praxisui/dynamic-form 9.0.0-beta.9 → 9.0.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.0-beta.9",
+  "version": "9.0.0-rc.1",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -9,13 +9,13 @@
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.0-beta.9",
-    "@praxisui/dynamic-fields": "^9.0.0-beta.9",
-    "@praxisui/metadata-editor": "^9.0.0-beta.9",
-    "@praxisui/rich-content": "^9.0.0-beta.9",
-    "@praxisui/settings-panel": "^9.0.0-beta.9",
-    "@praxisui/visual-builder": "^9.0.0-beta.9",
-    "@praxisui/core": "^9.0.0-beta.9",
+    "@praxisui/ai": "^9.0.0-rc.1",
+    "@praxisui/dynamic-fields": "^9.0.0-rc.1",
+    "@praxisui/metadata-editor": "^9.0.0-rc.1",
+    "@praxisui/rich-content": "^9.0.0-rc.1",
+    "@praxisui/settings-panel": "^9.0.0-rc.1",
+    "@praxisui/visual-builder": "^9.0.0-rc.1",
+    "@praxisui/core": "^9.0.0-rc.1",
     "rxjs": "^7.8.0"
   },
   "dependencies": {
@@ -30,6 +30,7 @@
   "keywords": [
     "angular",
     "praxisui",
+    "praxis",
     "dynamic-form",
     "metadata",
     "schema-driven",
@@ -46,7 +47,10 @@
     ".": {
       "types": "./types/praxisui-dynamic-form.d.ts",
       "default": "./fesm2022/praxisui-dynamic-form.mjs"
+    },
+    "./ai/component-registry.json": {
+      "default": "./ai/component-registry.json"
     }
   },
   "type": "module"
-}
+}

package/src/lib/config-editor/praxis-dynamic-form-config-editor.json-api.md

@@ -58,7 +58,9 @@ Este documento e a referencia canonica da API JSON de praxis-dynamic-form-config
 - O editor visual e o editor JSON operam sobre `DynamicFormAuthoringDocument`.
 - O editor JSON aceita apenas o envelope canônico; payloads legados pertencem aos caminhos de compatibilidade do runtime.
 - `Apply` e `Save` emitem um snapshot canonico completo com semantica `replace-all`.
-- Em comandos condicionais, o editor visual autora `globalAction.payload` estruturado; `globalAction.payloadExpr` fica reservado ao JSON avancado e e preservado no round-trip quando nenhum payload estruturado e definido.
+- Em comandos condicionais, o editor visual autora o efeito primario `effects[0].globalAction.payload` estruturado; `globalAction.payloadExpr` fica reservado ao JSON avancado e e preservado no round-trip quando nenhum payload estruturado e definido.
+- Regras com multiplos `effects` continuam JSON-avancadas para autoria completa; ao editar o efeito primario pela UI, efeitos secundarios existentes sao preservados para evitar perda silenciosa.
+- Em `formCommandRules[].policy`, o editor visual autora os campos comuns `distinct`, `distinctBy` e `runOnInitialEvaluation`; campos avancados vindos do JSON, como `trigger`, `debounceMs`, `errorPolicy` e `missingValuePolicy`, sao preservados no preview/apply, mas nao sao expostos como controles visuais completos.
 - `config`, `bindings` e `contextSnapshot` substituem integralmente o estado autoral anterior.
 - Ausencia de `bindings.mode` limpa o binding persistido e restaura o modo default efetivo do host.
 - Ausencia de `contextSnapshot.backConfig`, `contextSnapshot.presentation` ou `contextSnapshot.schemaPrefs` significa remocao explicita do bloco ausente.
@@ -101,7 +103,7 @@ Este documento e a referencia canonica da API JSON de praxis-dynamic-form-config
 | `messages` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
 | `metadata` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
@@ -139,7 +141,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | messages | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
 | hooks | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
 | formRules | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
-| formRulesState | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
+| formRulesState | Estado interno de round-trip do builder visual. | verified | internal-derived | Gerado pelo editor a partir de `formRules`; nao escrever diretamente. |
 
 ### Nested configuration blocks
 
@@ -152,7 +154,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `messages` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | internal-derived | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 
@@ -329,7 +331,7 @@ A entrada operacional vem via `SETTINGS_PANEL_DATA` (injetado pelo settings pane
 | `messages` | Active | Editado na aba Mensagens. |
 | `hooks` | Active | Editado na aba Hooks e JSON. |
 | `formRules` | Active | Gerado pela aba Regras (visual builder). |
-| `formRulesState` | Active | Persistido para round-trip sem perda. |
+| `formRulesState` | Internal | Persistido somente como estado de round-trip do builder visual; nao e contrato autoravel. |
 | `hints` | Active | Editado na aba Dicas e Tooltips. |
 | `api` | Partial | Sem aba dedicada; passa por JSON editor quando presente. |
 | `metadata` | Partial | Mantido em round-trip; sem painel dedicado. |
@@ -410,7 +412,7 @@ Correcao: e diff estrutural para UX do painel, nao auditoria de negocio.
 | `messages` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
 | `metadata` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |

package/src/lib/praxis-dynamic-form.json-api.md

@@ -24,6 +24,7 @@ source_of_truth:
   - "projects/praxis-dynamic-form/src/lib/ai/form-ai.adapter.ts"
   - "projects/praxis-ai/src/lib/core/models/assistant-context.models.ts"
   - "projects/praxis-ai/src/lib/core/services/assistant-session-registry.service.ts"
+  - "projects/praxis-ai/src/lib/core/services/agentic-authoring-turn-client.service.ts"
   - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts"
   - "projects/praxis-dynamic-form/src/lib/utils/prepare-submit-payload.ts"
   - "projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts"
@@ -34,8 +35,8 @@ source_of_truth:
   - "projects/praxis-core/src/lib/services/dynamic-form.service.ts"
   - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
   - "projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md"
-source_of_truth_last_verified: "2026-05-02"
-last_updated: "2026-05-02"
+source_of_truth_last_verified: "2026-07-16"
+last_updated: "2026-07-16"
 toc: true
 sidebar: true
 tags:
@@ -82,6 +83,8 @@ Contrato operacional:
 - a identidade canonica da sessao segue `form:{routeKey}:{componentInstanceId || formId || 'form'}`;
 - o contexto assistivel publico e `PraxisAssistantContextSnapshot`, com `identity`, `target`, `contextItems`, `authoringManifestRef`, `resourcePath`, `schemaFields`, digests seguros e hints de governanca;
 - o snapshot pode apontar para `field`, `schemaBackedField`, `localField`, `section`, `row`, `column`, `visualBlock`, `formAction`, `message` ou `rule`, mas nao deve transportar `form.value`, `rawFormData`, config completa, notas privadas, estado runtime bruto, diagnostics arbitrarios, `pendingPatch`, `File`, `Blob`, bytes, base64 ou `previewUrl`;
+- turnos do assistente usam `AgenticAuthoringTurnClientService` e `/api/praxis/config/ai/authoring/turn/stream/**`; indisponibilidade do transporte falha de forma fechada e nao reabre o caminho legado `getPatch`;
+- o grounding do turno pode incluir `schemaFields` e `dataProfile` estruturais produzidos pelo adapter, mas nunca valores dos controles; anexos sao reduzidos a nome, tipo, MIME, tamanho, origem e indicador de preview;
 - edicao local so pode ser aplicada quando a resposta for compilada para `componentEditPlan` validado pelo manifesto autoral do componente;
 - patches livres retornados por backend/LLM sem plano compilado sao rejeitados pelo turn flow;
 - pedidos sobre regra de negocio compartilhada, elegibilidade, compliance, LGPD, politica, acesso, aprovacao, publicacao, materializacao ou enforcement devem virar handoff governado para `domain-rules`, nao patch local de formulario;
@@ -129,9 +132,11 @@ Essa fronteira preserva a premissa de plataforma: o formulario materializa e exp
 | `messages` | not-specified | not-specified | n/a | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | Active | Aplicadas no pipeline de regras do runtime. |
 | `formCommandRules` | not-specified | not-specified | n/a | Active | Regras condicionais de comando avaliadas sobre `formData` estabilizado depois de `formRules`; primeiro corte suporta `global-action`. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | not-specified | not-specified | n/a | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |
+| `helpPresentation` | `FormHelpPresentationConfig` | No | `{ display: "inline" }` | Active | Politica visual para exibir `hint`/`helpText` dos campos sem alterar semantica dos DTOs; erros de validacao continuam inline. |
+| `presentation` | `FormPresentationConfig` | No | runtime defaults | Active | Preferencias tipadas de label/value para modos read-only e presentation. Valores numericos de tamanho e largura sao materializados como comprimentos CSS em `px`; o mesmo shape alimenta o snapshot canonico do editor. |
 | `fieldMetadata[].array` | `FieldArrayConfig` | No | n/a | Active | Contrato de Editable Collection apenas quando `fieldMetadata[].controlType === "array"` ou quando `x-ui.array` foi publicado explicitamente. |
 
 Nota editorial:
@@ -192,7 +197,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `api` | not-specified | not-specified | n/a | component-defined | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | not-specified | not-specified | n/a | component-defined | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | component-defined | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | not-specified | not-specified | n/a | component-defined | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | internal-derived | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | component-defined | Integracao de ciclo (before/after) via runtime de hooks. |
 | `sections[].sectionHeader` | `FormSectionHeaderConfig` | No | n/a | Active | Header visual rico da seção com suporte a avatar dinâmico resolvido a partir de `formData`. |
 
@@ -241,7 +246,7 @@ the canonical remote entity loaded through `resourcePath` and `resourceId`.
 | `readUrl` | `string \| null \| undefined` | No | component-input | resolved via API origin and `{id}` placeholders | URL concreta de leitura publicada por surface `VIEW`/`READ_PROJECTION`; quando presente, substitui `crud.getById` na hidratação da entidade. |
 | `submitUrl` | `string \| null \| undefined` | Conditional | component-input | resolved via API origin | URL concreta de submit publicada por surface/action; exige `submitMethod` quando usada para envio HTTP. |
 | `submitMethod` | `'post' \| 'put' \| 'patch' \| null \| undefined` | Conditional | component-input | normalized lowercase | Método HTTP concreto de submit publicado por surface/action; exige `submitUrl` quando usado para envio HTTP. |
-| `responseSchemaUrl` | `string \| null \| undefined` | No | component-input | diagnostic only | Schema de resposta para diagnóstico e follow-up de runtime. |
+| `responseSchemaUrl` | `string \| null \| undefined` | No | component-input | diagnostic only | Schema de resposta para diagnóstico e follow-up; não compõe campos editáveis nem o payload do comando. |
 | `enableCustomization` | `boolean` | No | component-input | boolean coercion | Alterna UX de edição visual/configuração. |
 | `formId` | `string \| undefined` | Yes (corporate flow) | component-input | component key scoping | Obrigatório para ciclo corporativo com persistência e sync. |
 | `componentInstanceId` | `string \| undefined` | No | component-input | component key scoping | Isola persistência por instância. |
@@ -559,7 +564,7 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 
 | Input | Tipo | Default | Status | Runtime notes |
 | --- | --- | --- | --- | --- |
-| `config` | `FormConfig` | `{ sections: [] }` | Active | Contrato principal consumido no ciclo inteiro. |
+| `config` | `FormConfig` | `{ sections: [] }` | Active | Contrato principal consumido no ciclo inteiro. `sections` é opcional somente para forms schema-driven com grounding explícito (`metadata.source='schema'`, schema metadata ou fonte runtime como `schemaUrl`/`resourcePath`); ausência de layout manual é normalizada internamente como array vazio e permite que `layoutPolicy`/schema materializem agrupamentos. |
 | `resourcePath` | `string \| undefined` | `undefined` | Active | Habilita carga de schema/dados remotos. Opcional quando `schemaUrl` explícito é fornecido. |
 | `resourceId` | `string \| number \| undefined` | `undefined` | Active | Carrega entidade no modo `edit/view`. |
 | `mode` | `'create' \| 'edit' \| 'view'` | `'create'` | Active | Governa submit, leitura e apresentacao. |
@@ -571,11 +576,13 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `domainRules` | `PraxisDynamicFormDomainRulesOptions \| boolean \| null` | `null` | Active | Opt-in para carregar materializacoes de regras compartilhadas em `/api/praxis/config/domain-rules/materializations` e combina-las com `config.formRules`. |
 | `submitUrl` | `string \| undefined` | `undefined` | Active | Executa submit canonico publicado por `surface` ou `action`, sem inferencia local de CRUD. |
 | `submitMethod` | `'post' \| 'put' \| 'patch' \| undefined` | `undefined` | Active | Metodo HTTP do submit canonico; deve acompanhar `submitUrl`. |
-| `responseSchemaUrl` | `string \| undefined` | `undefined` | Active | Porta diagnóstica/read-only para hosts que precisem inspecionar o contrato de resposta do backend. |
+| `responseSchemaUrl` | `string \| undefined` | `undefined` | Active | Porta diagnóstica/read-only; não deve ser usada para mesclar propriedades do schema de resposta no formulário de comando. |
 | `enableCustomization` | `boolean` | `false` | Active | Habilita UX de customizacao do layout. |
 | `formId` | `string \| undefined` | `undefined` | Active | Chave de persistencia e identidade logica. |
 | `componentInstanceId` | `string \| undefined` | `undefined` | Active | Isola instancias com mesmo `formId`. |
 | `layout` | `FormLayout \| undefined` | `undefined` | Partial | Funciona como override estrutural em parte dos fluxos de layout/editor. |
+| `generatedLayoutPreset` | `'default' \| 'compactPresentation'` | `'default'` | Active | Usado apenas ao criar a configuracao inicial a partir de schema/metadata; nao reprocessa layouts persistidos ou authorados. |
+| `layoutPolicy` | `DynamicFormLayoutPolicy \| null` | `null` | Active | Politica opt-in para materializar layout a partir do schema atual. Use `source: 'schema'` com `persistence: 'transient'` para detalhe/read-only e command forms schema-driven sem persistir `sections` geradas nem reabrir configuracao local salva; politicas de host em `config`, como `helpPresentation`, continuam sendo aplicadas ao layout materializado. Em `mode='view'`, `intent: 'detail'` ou `preset: 'compactPresentation'` ativa apresentacao quando `presentationModeGlobal` nao foi informado; use `[presentationModeGlobal]=false` para controles read-only tradicionais. No preset `compactPresentation`, `x-ui.width` explicito empacota campos em linhas de 12 colunas e tem precedencia sobre `detailSummary.columns` por default; campos sem width permanecem full-width, a menos que `detailSummary.columns`/`responsiveColumns` declare a densidade do resumo. Use `detailSummary.widthPrecedence='summary'` quando a densidade do resumo read-only deve sobrescrever `x-ui.width` apenas nessa surface compacta. No preset `groupedCommand`, `groupedCommand.orphanFieldExpansion` controla linhas com um unico campo: `medium-and-wide` (default) expande spans 6/8, `preserve` mantem o width publicado e `all` tambem expande campos compactos. Use `responsiveColumns`, por exemplo `{ lg: 3, md: 2, sm: 1 }`, para drawers, side sheets e painéis corporativos estreitos sem copiar `FormConfig.sections` locais. `schemaType` e `schemaOperation` sao validados contra `schemaUrl` quando a URL declara esses parametros. |
 | `backConfig` | `BackConfig \| undefined` | `undefined` | Active | Integra retorno/navegacao no painel de configuracao; `confirmOnDirty` tem precedencia sobre `behavior.confirmOnUnsavedChanges` no cancel. |
 | `hooks` | `FormHooksLayout \| undefined` | `undefined` | Active | Override direto de hooks sobre `config.hooks`. |
 | `customEndpoints` | `EndpointConfig` | `{}` | Active | Override de endpoints no CRUD service interno. |
@@ -588,8 +595,34 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `readonlyModeGlobal` | `boolean \| null` | `null` | Active | Estado global de leitura propagado para loader. |
 | `disabledModeGlobal` | `boolean \| null` | `null` | Active | Estado global de desabilitado propagado para loader. |
 | `presentationModeGlobal` | `boolean \| null` | `null` | Active | Modo apresentacao global (efetivo em `view`). |
+| `fieldIconPolicy` | `'all' \| 'presentation-only' \| 'none'` | `'all'` | Active | Controla icones `prefixIcon`/`suffixIcon` vindos da metadata dos campos. `all` preserva o comportamento atual; `presentation-only` mantem icones decorativos no modo apresentacao e oculta os slots de icone em controles input/read-only tradicionais; `none` oculta esses slots em todos os modos. |
 | `visibleGlobal` | `boolean \| null` | `null` | Active | Visibilidade global propagada para loader. |
 
+In `compactPresentation` runtime detail surfaces, rows, columns and sections are visible only when
+they contain at least one field that can be materialized after metadata visibility and field-rule
+overrides are resolved. Boolean values, including `false`, are valid presentation values and must
+not be treated as empty detail content. If no field in a section is materialized, the section is
+hidden instead of rendering an orphan title.
+
+#### Migration baseline for ErgonX-style screens
+
+For enterprise migrations that must become templates for many screens, `layoutPolicy`,
+`helpPresentation` and `fieldIconPolicy` should be selected as part of the DTO/schema
+handoff, not patched locally after visual review.
+
+Recommended baseline:
+
+| Surface | Inputs | Contract gate |
+| --- | --- | --- |
+| Detail/read-only | `layoutPolicy.source='schema'`, `intent='detail'`, `preset='compactPresentation'`, `persistence='transient'`, `schemaType='response'` | Response DTO publishes business grouping, order, labels, value presentation and safe widths. |
+| Create/edit | `layoutPolicy.source='schema'`, `intent='command'`, `preset='groupedCommand'`, `persistence='transient'`, `schemaType='request'` | Request DTO/write contract publishes only editable fields, validators, options and help text required for the command. |
+| Dense command drawer | `config.helpPresentation.display='auto'` with `preferPopoverForControls` for select, checkbox, toggle, date/datepickers and numeric controls | DTO help text is semantic and not a substitute for validation messages. |
+| Input-heavy operational form | `fieldIconPolicy='presentation-only'` | Icons remain useful in read-only presentation but do not crowd editable controls. |
+
+If a field requires a local label, local help text, local option mapping or local code/description
+composition to look correct, the schema is not ready for scalable migration. Fix the backend DTO,
+OpenAPI `x-ui` metadata or option/value-presentation contract first.
+
 #### Regras compartilhadas materializadas
 
 `domainRules` separa regra corporativa compartilhavel de regra materializada no `FormConfig`. Quando habilitado, o componente consulta o backend de configuracao via `DomainRuleFormRulesService`, transforma cada materializacao em `FormLayoutRule` e aplica a lista combinada:
@@ -686,7 +719,7 @@ Precedencias importantes:
 | `api` | Declared-only | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | Active | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | Internal | Persistido somente como estado de round-trip do builder visual; nao e contrato autoravel. |
 | `hooks` | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |
 
@@ -863,7 +896,7 @@ O runtime emite `target-not-found` quando uma regra aponta para `section`, `row`
 | `api` | not-specified | not-specified | n/a | Declared-only | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | not-specified | not-specified | n/a | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | Active | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | not-specified | not-specified | n/a | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |