Shared diagnostics and frozen PCA references

Verified against source 748ee444 (Methods 1.3.8, ABI 2.20) plus the local wide-matrix T²/Q correction. A source capability and an installed binary’s availability are separate facts. No release is implied by this local audit.

Fit on calibration, project everything else

The existing n4m_decomposition_flexible_pca_* C interface provides PCA without requesting full-spectrum moments. Its fit state owns the calibration means and loadings; transform is const and does not fit on the evaluated batch.

n4m_pp_flex_pca_handle_t *pca = NULL;
n4m_status_t status = n4m_decomposition_flexible_pca_create(&pca, 5.0);
/* Check status after every call. All matrix views contain caller-owned f64
   buffers; training_scores is n_train x 5, test_scores is n_test x 5. */
status = n4m_decomposition_flexible_pca_fit(pca, X_train);
status = n4m_decomposition_flexible_pca_transform(pca, X_train, training_scores);
status = n4m_decomposition_flexible_pca_transform(pca, X_test, test_scores);
n4m_decomposition_flexible_pca_destroy(pca);

The same recipe is available to Rust through the public C ABI and to Python/JS through FlexiblePCA.fit/transform. Keep sample/group identities and physical axis units in the owning protocol. Missing values must be resolved using the declared calibration-only preprocessing policy before fitting: this interface does not silently impute them. Scaling is a separate, training-fitted operator; PCA itself centres features and does not standardize them implicitly.

n4m_preflight_pca_compute (ABI 2.19) additionally supplies calibration scores, loadings, retained eigenvalues and exact full-spectrum moments. Its ABI 2.20 _resolved counterpart publishes the variance resolution and unresolved flags. These are one-shot calibration diagnostics, not a reusable fitted handle. Do not sum retained eigenvalues and present them as exact full-spectrum moments.

The 250-million-product refusal reported in issue #45 predates current 1.3.8. Current preflight_pca_budget.hpp bounds the whole computation (2.4 billion long-double multiply-add equivalents, 1 GiB working memory), including the eigensolver ceiling. This change is already upstream; the local fix does not raise or remove that guard. The regression witness uses the exact 390 x 2,151 shape, verifies exact moments, and proves that held-out projection leaves the training scores bit-identical. On this Linux release build its synthetic rank-two matrix and frozen projection took 0.333 seconds. This is one local measurement, not a Windows, browser or representative production benchmark.

API reuse matrix

Requested operation	Existing owner and interface	Scientific contract / limit
Training PCA and frozen test projection	Methods decomposition.h: n4m_decomposition_flexible_pca_create/fit/transform	Existing stateful API, including older ABI 2.17 consumers; no full moments required. Test data never enter fit.
Exact covariance moments, eigenvalues and accuracy	Methods metrics.h: n4m_preflight_pca_compute, _resolved	ABI 2.19 / 2.20 respectively. Numerical and work budgets are explicit.
Calibration T² and Q plus limits	Methods outlier_detection.h: n4m_outlier_detection_hotelling_t2{,_resolved}, n4m_outlier_detection_q_residuals	T² uses resolved rank; Q uses Jackson–Mudholkar approximation. Local correction supports tall and wide matrices using the existing compact SVD. These batch procedures refit the supplied batch: they are not frozen test-domain scores.
Full PCA-based domain monitor	Methods metrics.h: n4m_stats_pca_monitor	Use its documented reference/monitor contract; preserve the population, retained components, numerical domain and uncertainty assumptions.
Physical-axis alignment	Methods transform/resampling.h: n4m_transform_resampler_*	Supply physical axis coordinates and units; feature indices are not wavelengths.
SNV	Methods metrics.h: n4m_preflight_snv_compute; transform/scatter.h	Row-local transformation; never a replacement for sampling/provenance validation.
Offset/gain correction to a fitted mean reference	Methods transform/scatter.h: n4m_transform_msc_fit/transform/get_reference	MSC transformation exists. A separately named RMS/SAM/offset/gain report must declare its reference, normalization and masks.
Local polynomial noise proxy	Methods n4m_preflight_noise_proxy_compute	Mask-aware SG residual RMS corrected by smoothing noise gain; edges are not padded. A proxy under a locally polynomial signal, not an SNR or a physical-cause probability.
Distribution summaries	Methods n4m_preflight_summary_compute	Use declared units/validity masks. This does not automatically equal RMS to a supplied spectrum.
Nearest neighbours	Methods n4m_preflight_nearest_neighbors	Native bounded kernel. A ratio of neighbour distances is not automatically the LOF algorithm.
HDBSCAN, partition comparison	Methods n4m_cluster_hdbscan, n4m_preflight_adjusted_rand_index, n4m_cluster_jaccard_matrix	Keep representation, distance protocol, seed and populations in Preflight/Domains.
Caller-reference spectral SAM/RMS, spike/jump/clip ratios	No equivalent dedicated summary entry point verified in this public surface	Preserve as explicitly unsupported until a protocol and native kernel/parity fixture are qualified; do not quietly substitute a different reference or an index-axis formula.
Physical root-cause hypotheses and operational actions	Preflight / Domains / consuming product	Keep heuristic strength, evidence coverage and causal validation separate. These interpretations do not belong in generic Methods kernels.

The shared C ABI is the portable boundary for Linux and Windows; the JS package builds that same core to WASM. Local native and WASM tests verify the wide T²/Q correction against constant-band padding, which preserves covariance geometry, including a constant, unresolved subspace. Existing tall, rank-deficient, nonfinite, scale, numerical-domain and exact-moment tests remain in the suite. No new exported symbol, struct layout or ABI minor version is introduced.