[jmarquisbq]

Summary

Correct storage contracts and error reporting used by out-of-core (OOC) pipelines, reduce repeated small mesh and image transfers, and add regression coverage for resident and disk-backed execution. Also correct periodic feature centroids, KMeans count validation, and numeric growth initialization. 189 files changed, +28,581 / −1,452 lines.

Coordinated companion PRs:

• BlueQuartzSoftware/SimplnxOoc#4 — BUG: Fix OOC Review Findings implements the HDF5 side of the new storage contracts and supplies tests using actual disk-backed arrays. Use it for OOC validation of these changes.
• BlueQuartzSoftware/DREAM3DNX#1171 — BUG: Fix OOC Review Findings consumes the bounded-read and checked-completion interfaces, presents diagnostics, and runs the combined OOC CI configuration. The public in-memory build remains independent of the private backend.

Storage and pipeline contracts

• Add an optional bounded extent-read interface with explicit scratch accounting and distinct success, unavailable, and failure results. Validate HDF5 selections before transfer and support caller-owned chunk-shape scratch.
• Preserve numeric growth initialization through copies and storage conversions, including explicit nonzero initialization and the existing diagnostic-fill policy.
• Propagate checked flush and finalization failures through arrays, NeighborLists, data structures, pipelines, recovery writes, and nxrunner, instead of reporting successful completion after a storage failure.
• Plan selected imports against the complete destination structure and validate references and storage choices before publishing imported objects.
• Preserve array-location restrictions when parameters are cloned, accept stores that meet those restrictions, and prevent later parallel-algorithm checks from re-enabling work already restricted to serial execution.
• Validate the two large-data thresholds and retain correction warnings for application and command-line consumers.

Filter correctness and OOC performance

• Default KMeans to one cluster and reject zero consistently in Direct and Scanline execution. Keep the separate sampling-policy issue outside this change.
• Compute periodic feature centroids from the arithmetic mean of unwrapped cell centers, with bounded occupancy scans and a defined fallback when the seam is ambiguous. Update the filter documentation and V&V records.
• Batch Identify Sample YZ transfers and the OOC paths for triangle normals, dihedral angles, face IPF colors, feature-face misorientation, shared feature faces, winding repair, and Laplacian smoothing. Verify Triangle Winding also batches its feature-volume and final-reversal stages.
• Reject invalid triangle vertex IDs before buffered coordinate access. Admit new mesh working buffers through the shared budget, honor partial grants, and use bounded coordinate access when a complete cache does not fit.
• Use temporary coordinate storage for low-memory OOC smoothing. Calculation failures preserve the original coordinates; final output-write failures can leave a completed prefix. Keep the default in-memory smoothing algorithm unchanged.
• Check Avizo source reads, output writes, flushes, closes, and size arithmetic. This does not change its sample-coordinate convention or binary coordinate separators.

Regression coverage and portability

• Add independently calculated centroid, triangle, smoothing, image, and complete writer-output expectations. Cover block boundaries, short transfers, cancellation, and injected failures.
• Verify selected algorithm paths and actual store types. Keep concrete HDF5 tests in the companion backend rather than treating an OOC algorithm flag as proof of disk-backed execution.
• Make floating-array comparisons reject mismatched NaNs. Isolate test and benchmark preferences, check cleanup, and keep the network-dependent citation check out of ordinary CTest runs.
• Admit the reviewed GCC and Apple standard-library configurations for bounded reads. Replacing those version checks remains a separate design task.

Test plan

• Full Windows in-memory Release, OOC Release, and OOC Debug builds passed for the final mesh fixes. The relevant mesh selections passed 32/32 in-memory and 63/63 in each OOC configuration.
• Additional connectivity, writer-coherence, preferences, and controller selections passed 17/17 in-memory and 38/38 in each OOC configuration.
• Independent triangle and smoothing expectations, actual HDF5 store checks, and failure/cancellation tests passed. Targeted before/after cases demonstrated that the regressions detect the repaired defects.
• The controlled smoothing benchmark passed correctness and cleanup checks: fitting-cache median 0.354 s versus 0.373 s before; constrained 64 KiB median 0.401 s versus 0.370 s before. These small, cached-file measurements are not whole-pipeline estimates.
• Required formatting checks passed. Scoped production clang-tidy checks passed for the final fixes; test-file framework/style diagnostics remain documented and are not a clean full-project static-analysis result.
• Resolve and confirm final Windows, Linux, and macOS CI, including the coordinated OOC builds. At the October 19 status check, Ubuntu Clang 16 reported a failure, formatting passed, and the other public build jobs were still running.

Laplacian smoothing still has approximately 32 bytes per vertex of older resident working arrays. The new buffers are bounded, but the whole algorithm is not yet bounded by the OOC working allowance. The broader all-filter OOC coverage audit remains a follow-up.

Related Issue

Related to #1532 — expands filter and failure-path coverage; does not complete the coverage inventory.

Related to #481 — adds import, geometry-reference, and persistence tests; does not complete all HDF5 coverage.

Related to #1756 — cluster-count validation is fixed; the initial-sampling hang remains deferred.

Related to #1768 — includes compatibility repairs; replacement of library-version gates remains deferred.

Related to #1835 — bounds the newer mesh buffers; the remaining 32 bytes per vertex is separate work.