Discover Table compatibility and declared Row alignment

docs/table-compatibility.md

@@ -0,0 +1,37 @@
+# Table compatibility and declared Row alignment
+
+In **Bindings → Table / Columns**, select a Table and use **Discover / Validate Table** after Build and Refresh. The shared inspector lists Table-compatible collections, Row Components, and Column Attributes. Choosing a collection refreshes the comparisons; choosing a Row or Attribute only prepares the form. Explicit selections are preserved, and source changes still require Apply with ordinary host Undo/Redo.
+
+Document diagnostics describe applied declarations. Choices compare the collection requested by the form. Source/build changes clear choices, and obsolete responses cannot populate a changed form. The same target-side validation runs before preview: known errors block new previews, warnings allow preview, and invalid drafts remain saveable.
+
+## Table-specific runtime rules
+
+Table uses a direct read/write bean collection Attribute to obtain its element class, in addition to the ViewModel property providing an ObservableList. Generic ViewModels and subclasses use their Model's bean metadata; replacement ViewModels need bean metadata on the replacement itself. A property accessor alone can work for Repeat but does not satisfy Table's element-type lookup. Nested collection paths and raw/unresolvable generic element declarations are rejected when the known bean signatures prove the runtime cannot resolve them. Missing context, custom BeanInfo, unavailable classes and uncertain observable backing remain unverified.
+
+Columns must name direct simple read/write Attributes on that element class. The classifier follows NeitzelLib Table's rules: String, boolean, numeric primitives except char, Number, enum, Date/Calendar and TemporalAccessor/TemporalAmount. Complex objects, collections, arrays, char, missing setters/getters and nested paths are incompatible. No application BeanInfo, accessor, getter, constructor or static initializer is executed. Compatibility is declared type evidence, not a guarantee about null values, dynamic contents, injection or runtime code.
+
+Row candidates reuse Component resource/model-property checks and compare both declared Model and typed modelProperty with Table's element type. Manually typed Row classes are validated even if conventional resource scanning does not enumerate them. Named-module resource visibility and reflective access requirements remain those of the target runtime.
+
+## Alignment evidence and Row drafts
+
+The runtime assigns widths to the first N immediate Row children in Column order; trailing controls are allowed. For a Row declared as an HBox, discovery reads direct children or its explicit `children` wrapper and the root BindingList's Direct bindings. Each Column must correspond to a uniquely identified field with one unambiguous direct Attribute binding. Matching declarations receive an informational result. Different Attributes or too few declared fields produce a mismatch warning and **Open selected Row Component** remains available.
+
+Missing bindings, Computed bindings, Converters, nested property syntax, custom Row ViewModels, non-HBox layouts and unresolved content produce an unverified warning. Construction and runtime layout changes remain unverified even when declarations match. Warnings never silently rearrange either the Columns or the shared Row layout.
+
+Binding discovery now overlays captured open FXML documents from the active reactor, including unsaved Row drafts, and checks every captured document revision before returning. The request identity carries all captured revisions. A Row edit invalidates parent discovery through existing document notifications. This extends the same draft capture to the other binding inspectors; Java changes still require Build and Refresh.
+
+## Protocol and qualification
+
+Metadata format 5 and `bindings-v5` add bounded Table collection, Row and Attribute lists. Older binding capabilities are rejected; existing payload, snapshot, document identity and worker boundaries remain intact. No application classes enter either host.
+
+Automated tests cover the Table-specific bean rules, simple Attribute classifier, Row mismatch/unverified cases, non-initialization and metadata round trips. Both real target launch modes exercise discovery and error diagnostics. The shared host scenario checks choices, explicit selection/source preservation, an unsaved Row mismatch and restoration, invalid Column preview blocking, save and exact Undo/Redo. Run the bootstrap and registered IntelliJ checks in the [README](../README.md). No manual testing is required; previously skipped checks remain skipped.
+
+Generated metadata, automatic structural reference repair and IDE Problems integration remain subsequent work. Alignment inference deliberately remains conservative for arbitrary Row layouts and runtime behavior.
+
+### Qualification — 2026-11-13
+
+The full bootstrap gate passed: 115 unit/adapter tests with no failures, 36 target processes with 512 assertions, both native standalone modes, 48 lifecycle cycles, connected adapters and plugin packaging. Registered IntelliJ classpath and module-path qualification passed the new discovery/Row-draft scenario, exclusive JavaFX 26 native-library checks and worker shutdown. No manual testing was used.
+
+An initial fixture assertion was updated to accept informational alignment results while still rejecting warnings/errors. The first registered IntelliJ attempt encountered the previously recorded intermittent exact-source save assertion in an older projection scenario, before Table tests. Its diagnostic's second file read equaled the expected text (both 1,191 characters). The unchanged registered rerun passed both modes. No save implementation or exact-source assertion was weakened; the intermittent persistence-check issue remains a separate reliability follow-up.
+
+Local evidence: `/tmp/table-discovery-bootstrap-final.log`, `/tmp/table-discovery-registered-ide.log`, `/tmp/table-discovery-registered-ide-retry.log`, `target/connected-workflow/` and `target/ide-workflow/`. Generated qualification artifacts are not repository inputs.