CHANGES IN VERSION 4.0

NEW FEATURES

* Added opt-in supervised sparse soft-structured PCA through `msma()` using
  `structure.method`, `gammaX`, `history.method`, and `niterS4`.
* Added hard-exclusive structured PCA with
  `structure.method = "exclusive"`.
* Added `s4pca_reconstruct()` for training-data and new-data reconstruction.
* Added `s4pca_conformal_select()` for repeated split reconstruction-based
  selection of `lambdaX`, `gammaX`, and `comp`, with an optional overlap
  constraint and full-data refitting.
* Added `overlap_all`, `overlap_selected`, convergence diagnostics, and stored
  preprocessing information to structured-PCA results.

COMPATIBILITY

* Calls that do not request structured PCA retain the Version 3.2 dispatcher
  and computational paths.
* The manuscript-generating S4PCA code is retained as a frozen numerical
  reference. The refactored engine is tested against it at tolerance 1e-12.
* Unsupported combinations, including multiblock structured PCA, PLS,
  multi-column Z, and NMF-based super-level structured analysis, fail with
  explicit messages rather than silently changing interpretation.

VALIDATION AND DOCUMENTATION

* Added input-validation, diagnostics, public-API, reconstruction,
  model-selection, reproducibility, and Version 3.2 regression tests.
* Added a soft-structured PCA vignette and documentation for the two new public
  helper functions.
* Corrected UTF-8 metadata handling during documentation generation.

BUG FIXES

* Made reduced-dimension simulation fixtures safe for variable counts below
  the manuscript template size.
* Avoided use of the reserved R keyword `repeat` with `$` indexing.

CHANGES IN VERSION 3.2

NEW FEATURES

* Added sparse non-negative matrix factorization at the super level through
  sprmethod = "sNMF".
* Z can now contain multiple supervision variables in separate columns.
* Added con4spv to specify weights for combining multiple columns of Z.

COMPATIBILITY

* Calls using only version 3.1 functionality are dispatched to the preserved
  version 3.1 computational engine.
* The extended computational engine is used only when NMF, sNMF, multivariate
  Z, or con4spv is explicitly requested.

BUG FIXES

* A one-column matrix supplied to Z is now normalized to a vector before the
  preserved version 3.1 engine is called. This makes Z = z and Z = cbind(z)
  produce identical numerical results and returned objects.

PACKAGE CHECKS

* Renamed the internal legacy and extended computational engines so that they
  are not interpreted as unregistered S3 methods of the msma generic.

* Added the internal `.s4pca_fit_reference()` candidate engine and the first
  regression suite against the frozen manuscript-generating implementation.

* Added a validated internal S4PCA interface and diagnostic metadata while
  retaining the reference-compatible numerical engine unchanged.
* Added strict validation for data, supervision, tuning, iteration, and seed
  inputs.

* Fixed reduced-dimension S4PCA test fixtures and ensured the canonical UTF-8
  DESCRIPTION is installed before roxygen2 documentation generation.

PUBLIC S4PCA API

* Added opt-in S4PCA through `msma()` using `structure.method`, `gammaX`,
  `history.method`, and `niterS4`.
* Added public contract tests and a soft-structured PCA vignette.

S4PCA MODEL SELECTION

* Added `s4pca_reconstruct()` for training and new-data reconstruction.
* Added `s4pca_conformal_select()` for repeated split reconstruction-based
  selection of `lambdaX`, `gammaX`, and `comp`, with an overlap constraint.
* Updated the Version 3.2 versus Version 4.0 compatibility validation document.

* Fixed parsing of the repeated-split identifier by using bracket indexing for
  the reserved R keyword `repeat`.

RELEASE VALIDATION

* Added reproducible scripts for the independent Version 3.2 compatibility
  audit, the `mand` reverse-dependency check, and release-manifest generation.

* Reload the newly installed namespace after the build so interactive
  post-build tests see the current Version 4.0 exports generated by roxygen2.

* Removed a redundant source-tree NAMESPACE inspection test. Export status is
  already verified against the installed namespace, avoiding a context-only
  skip when tests are run from the development tree.

* Fixed the Milestone 6 compatibility runner to use absolute input, reference,
  source, and output paths when rendering from the validation directory.

* Corrected the `mand` reverse-dependency audit to install msma 4.0 into a
  genuinely isolated library and to separate compatibility checks from CRAN
  incoming same-version warnings.

* Made the `mand.Rcheck` log discovery robust to the Windows R front end,
  which may create the check directory in the development root even when the
  command is launched after changing to the reverse-dependency work directory.