Discover Converter capabilities and validate shared binding drafts

docs/binding-discovery.md

@@ -1,6 +1,6 @@
 # Shared Model and binding-target discovery
 
-This is the first stage-4 implementation slice: a read-only binding browser shared by standalone and IntelliJ. The [DirectBinding inspector](direct-binding-inspector.md) now uses discovered targets to start editable declarations. Converter discovery, generated metadata and the complete inspector remain subsequent work.
+This is the first stage-4 implementation slice: a read-only binding browser shared by standalone and IntelliJ. The [DirectBinding inspector](direct-binding-inspector.md) now uses discovered targets to start editable declarations. [Converter discovery and DirectBinding validation](converter-validation.md) now extend this slice; generated metadata and the complete inspector remain subsequent work.
 
 ## Use
 
@@ -12,13 +12,13 @@ For Person the browser exposes `name`, `rank`, `home`, `home.street`, and `visit
 
 ## Metadata boundary
 
-The fresh target worker loads classes without initialization and inspects signatures. It never constructs Models, Controllers, providers, controls or Converters, never invokes getters/property accessors, and never starts JavaFX. Application types stay outside both hosts. The independently negotiated `bindings-v1` capability adds the BINDINGS operation; it uses bounded UTF-8 metadata, build/context identity and document revisions, with zero image dimensions. Existing wire operation ordinals remain unchanged.
+The fresh target worker loads classes without initialization and inspects signatures. It never constructs Models, Controllers, providers, controls or Converters, never invokes getters/property accessors, and never starts JavaFX. Application types stay outside both hosts. The independently negotiated `bindings-v2` capability adds the BINDINGS operation; it uses bounded UTF-8 metadata, build/context identity and document revisions, with zero image dimensions. Existing wire operation ordinals remain unchanged.
 
 Model fallback follows NeitzelLib's public read/write JavaBean Attribute rules and simple/complex/collection classification. Nested paths expand to depth four with cycle diagnostics; collection paths expose declared element types without pretending a collection is a single nested Model. Explicit custom BeanInfo is not executed: types requiring it report a generated-metadata diagnostic. This slice does not yet expose custom/replacement ViewModel members, generated metadata, Computed methods or library-provided message properties. Its compatibility results describe the Model-Attribute binding case, not the complete custom ViewModel API.
 
 Targets come from public instance JavaFX observable-property accessors. The runtime requires writable `Property` accessors, so read-only targets remain visible as incompatible. Generic observable signatures and getter types identify the value type; incomplete or contradictory signatures remain unresolved. Component `model` targets use the Component resource's explicit Model declaration instead of treating Object as a specific type. Component resource metadata comes from the selected build; current-document metadata comes from the captured draft.
 
-Compatibility uses boxed declared types and target-runtime assignability: `view` tests Model-to-control, `model` the reverse, and `both` requires both. No implicit numeric/string conversion is assumed. Type mismatches require a compatible Converter; Converter availability/signatures are not yet discovered. Unknown Object types and collection variance remain unresolved, rather than being advertised as verified bindings. Results are potential type matches, not a check that a target is currently unbound or that all runtime access/injection conditions hold.
+Compatibility uses boxed declared types and target-runtime assignability: `view` tests Model-to-control, `model` the reverse, and `both` requires both. No implicit numeric/string conversion is assumed. Type mismatches require a compatible Converter; Converter availability and optional capabilities are checked by the DirectBinding inspector. Unknown Object types and collection variance remain unresolved, rather than being advertised as verified bindings. Results are potential type matches, not a check that a target is currently unbound or that all runtime access/injection conditions hold.
 
 ## Freshness and limits
 

docs/converter-validation.md

@@ -0,0 +1,38 @@
+# Converter discovery and binding validation
+
+Both hosts use the same **Bindings → Direct bindings → Find Converters / Validate** action. It checks the current document and lists Converter candidates for the form's Model path, target property and direction. Choose a candidate or keep an explicit class name, review the form, then **Apply binding**. Discovery and validation never edit FXML. Apply uses the existing source-preserving command and host Undo/Redo.
+
+A single compatible candidate is proposed only when the Converter field is empty. Multiple matches require a choice. Explicit selections, including unannotated classes, are retained. Form changes reject obsolete suggestions; document changes and builds invalidate validation. Results identify the draft revision and explicitly retained builds. Validation uses a separate target worker and leaves existing interactive sessions alone. New preview requests validate the current parent document before launching; known errors block the request, while warnings remain visible and saving stays available.
+
+## Optional capabilities
+
+The application-facing `designer-preview-api` artifact supplies a runtime-retained annotation with no JavaFX, Kit or IntelliJ dependency:
+
+```java
+@ConverterCapabilities(modelType = Integer.class,
+                       controlType = String.class,
+                       reverse = true)
+public class RankConverter implements de.neitzel.fx.view.Converter {
+    // Implement toControlValue and toAttributeValue.
+}
+```
+
+Import `de.neitzel.fxdesigner.preview.ConverterCapabilities`. Named modules using this annotation require `de.neitzel.fxdesigner.preview`. The annotation is tooling metadata; NeitzelLib's Converter interface and runtime behavior remain unchanged. No new NeitzelLib artifact is required.
+
+Metadata must be declared on the concrete class. An unannotated subclass does not inherit verified capabilities. Forward conversion is always required, including initialization of a converted `model` binding. `model` and `both` additionally require reverse conversion. Declaring reverse support while inheriting the interface's default throwing method is an error. Declared input/output types are checked with boxing and target-runtime assignability in each required direction. Plain bindings retain NeitzelLib's separate direction rules. NeitzelLib bypasses Converters for complex and collection Attributes; those paths get no proposals, and an explicit Converter produces a warning rather than a false compatibility claim.
+
+The chooser distinguishes compatible, incompatible, unverified and invalid candidates. Metadata is a declared contract, not a proof of implementation behavior. Unannotated Converters remain usable with a warning. Target previews still exercise conversion, and the real fixtures test conversion failure/value preservation and recovery through NeitzelLib's Message behavior.
+
+## Worker and validation boundary
+
+The worker indexes class headers in captured classpath/module-path directories and JARs, respecting multi-release JAR selection, then loads Converter descendants without initialization. It reads annotations and method signatures without constructing Converters or invoking application methods. The index is bounded to 100,000 classes and 256 candidates; the normal worker deadline and cancellation apply. Application classes never enter a host.
+
+`bindings-v2` negotiates metadata format 2, adding candidate and document-problem records to the existing BINDINGS operation without changing its wire ordinal. Older binding capabilities are not silently interpreted as this format. The UTF-8 payload, metadata counts, request identity, build identity and document-revision checks remain bounded.
+
+The validator covers attribute-form DirectBindings in root BindingLists: discoverable Model paths, control IDs, JavaFX property existence/writability, plain type compatibility, explicit Converter availability/capabilities and duplicate Direct/Computed targets. Known violations are errors. Unresolved types, incomplete/custom Model metadata, missing Model declarations and nested binding syntax produce warnings. Computed methods, custom/generated ViewModels, collection semantics, nested Component draft metadata, dependency injection availability and runtime method behavior are not fully validated in this slice. A warning does not certify that preview will succeed. Complete Problems-view integration and broader binding authoring remain later work.
+
+## Automated qualification
+
+Unit tests cover non-initialization, inherited/unannotated metadata, reverse-method inconsistencies, assignability, the special converted model-direction initialization rule, path/property errors and metadata round trips. Real classpath and named-module fixtures exercise discovery and validate the same application declarations without initializing Converters. Shared live-UI checks cover explicit preservation, a unique proposal requiring Apply, ambiguous matches requiring selection, unverified warnings, type-error preview blocking and source-preserving Undo/Redo in standalone and registered IntelliJ. Existing rendering, input and worker lifecycle checks remain enabled. No manual review is required for this slice; earlier skipped manual checks retain their recorded disposition.
+
+Qualification on 2026-11-13 passed: 79 Maven tests and 7 IntelliJ adapter tests; 34 target processes with 438 fixture assertions; 48 worker lifecycle cycles; connected workflows and live shared UI in standalone and registered IntelliJ for classpath and module-path applications. Native isolation, worker shutdown, bytecode/package boundaries and documentation checks passed. Final host logs contain no uncaught exceptions and no new native crash report appeared. The live regression exposed and fixed an automatic canvas-refresh race that replaced an in-flight chooser request; pending validation now also satisfies that preview request. Local evidence: `/tmp/converter-bootstrap.log`, `/tmp/converter-registered-ide.log`, and `/tmp/converter-protocol-test.log` (including rejection of the old binding capability).

docs/direct-binding-inspector.md

@@ -14,9 +14,9 @@ A target occupied by another DirectBinding or ComputedBinding requires **Replace
 
 ## Validation boundary
 
-Structural diagnostics cover duplicate targets, missing/ambiguous fx:id, empty property, malformed/missing Model path and invalid direction. These known errors block a new canvas/interactive preview request while allowing save and source repair. Type compatibility remains the separate discovery result; the editor does not yet prove path existence, Converter compatibility or runtime property availability. A syntactically valid but incompatible declaration can therefore still fail in the target runtime.
+Structural diagnostics cover duplicate targets, missing/ambiguous fx:id, empty property, malformed/missing Model path and invalid direction. [Converter discovery and binding validation](converter-validation.md) now add target-side path/property/type and capability checks, a shared chooser, and automatic validation before new previews. Saving and source repair remain available on errors.
 
-Converter names are preserved/editable text, not a discovered or verified Converter chooser. Generated/custom ViewModel metadata, Computed/Repeat/Table authoring, complete semantic diagnostics and identifier rename/copy/subtree-delete reference repair remain later stage-4 work.
+Generated/custom ViewModel metadata, Computed/Repeat/Table authoring, complete semantic diagnostics and identifier rename/copy/subtree-delete reference repair remain later stage-4 work.
 
 ## Automated qualification
 

docs/repository-bootstrap-plan.md

@@ -105,3 +105,7 @@ Manual review disposition (2026-11-13): the user accepted proceeding after the r
 ## Shared discovery: first stage-4 slice
 
 Implemented the [read-only binding browser](binding-discovery.md) in the shared Kit UI: target-side Person Attribute/path and collection-element discovery, Component Model declarations and direction-aware binding-target compatibility. Real classpath and module-path fixtures qualify both hosts. The [first editable DirectBinding inspector](direct-binding-inspector.md) adds creation, changing, removal and explicit conflict replacement through one source-preserving host undo command per operation. Remaining metadata categories and broader binding authoring retain their subsequent work packages.
+
+## Converter discovery and binding validation
+
+The [next shared stage-4 slice](converter-validation.md) adds optional concrete-class capabilities, non-initializing classpath/module-path discovery, reviewed Converter proposals and DirectBinding diagnostics with preview gating in both hosts. Full metadata, structural reference repair and Problems integration remain open.