M4 — pls4all source split: EXTRACTION RECIPE

Status: scaffolded — 39 target stub files landed at their final paths. The actual function-body extraction is deferred to a focused refactor session because each cut must keep n4m_tests (265/265) green between commits and the surgery is genuinely 4 days of careful work per the roadmap budget. This document is the maintenance protocol that guides that session.

Source plan: docs/merge/M4/SPLIT_PLAN.md (produced by the Explore agent in parallel with M3).

Pre-flight per-extraction checklist

Before any single extraction commit:

1. n4m_tests is currently green (./build/dev-release/cpp/tests/n4m_tests reports 265 run, 0 failures, 0 skipped).

2. Work on the merge/import-donor branch.

3. The pls4all CMakeLists at cpp/src/CMakeLists.txt still references the source monoliths (core/model.cpp, core/extra_pls.cpp).

Phase 1 — extract helpers FIRST (load-bearing)

The agent’s analysis flags four cross-cutting helper blocks that MUST be extracted before any algorithm files, because anonymous-namespace helpers cannot be called across translation units:

Helper block	Lines in source	Target file	Linkage transition
model.cpp anon-namespace (L18–L1524, ~1500 lines) — center_scale_in_place, copy_matrix_checked, validate_fit_request, invert_square, dot, matrix_vector_product, read_value/write_value	model.cpp:18-1524	cpp/src/core/models/core/_common.{cpp,hpp}	anonymous → n4m::core::detail:: (or n4m::core::detail:: pre-M5) namespace; declare in _common.hpp
model.cpp PLS-shared helpers (simple_simpls is the cross-call from extra_pls; dominant_svd_pair, largest_symmetric_eigenvector, canonicalize_direction_sign, canonicalize_svd_pair_sign)	model.cpp:281-1524 selectively	cpp/src/core/models/pls/_common.{cpp,hpp}	same
extra_pls.cpp anon-namespace (L18–L306, ~290 lines) — soft_threshold, column_means, subtract_means, copy_matrix, squared_norm	extra_pls.cpp:18-306	cpp/src/core/models/sparse/_common.{cpp,hpp}	same

Critical: simple_simpls (extra_pls.cpp:97) is called by both fit_pls_sparse_simpls (model.cpp) AND extra_pls sparse variants. It MUST be extracted to a shared location accessible to both — the recommended location is models/pls/_common.{cpp,hpp} (since SIMPLS is canonically PLS-side).

Phase 1 commit pattern

M4 phase 1: extract models/core/_common — N anonymous-namespace helpers
  - cpp/src/core/models/core/_common.cpp (+~300 lines)
  - cpp/src/core/models/core/_common.hpp (+~80 lines, declarations)
  - cpp/src/core/model.cpp (−~300 lines, replaced by include of _common.hpp)
  - cpp/src/CMakeLists.txt (+1 entry: core/models/core/_common.cpp)
  - Verify: n4m_tests 265/265 still green

Repeat for pls/_common and sparse/_common. After Phase 1 (3 commits), 50 % of model.cpp’s bulk is extracted but no functional change.

Phase 2 — core PLS solvers (8 commits)

In topological order (dependencies first):

Order	Function	Source lines	Target	Helper deps
1	fit_pls_canonical_nipals + _svd	model.cpp:1819-1838	models/pls/canonical.cpp	core/_common, pls/_common
2	fit_pls_regression_nipals	model.cpp:1528-1818	models/pls/nipals.cpp	core/_common, pls/_common
3	fit_pls_regression_simpls	model.cpp:3685-3884	models/pls/simpls.cpp	core/_common, pls/_common (simple_simpls)
4	fit_pls_regression_svd	model.cpp:2895-3060	models/pls/svd.cpp	core/_common, pls/_common
5	fit_pls_svd (PLSSVD)	model.cpp:1839-1999	models/pls/plssvd.cpp	core/_common, pls/_common
6	fit_pls_regression_power	model.cpp:3061-3226	models/pls/power.cpp	core/_common, pls/_common
7	fit_pls_regression_randomized_svd	model.cpp:3227-3396	models/pls/randomized_svd.cpp	core/_common, pls/_common, common/svd.{c,h} (post-M2.5)
8	fit_pls_regression_kernel	model.cpp:2615-2894	models/pls/kernel.cpp	core/_common, pls/_common
9	fit_pls_regression_orthogonal_scores	model.cpp:2350-2614	models/pls/oscores.cpp	core/_common, pls/_common

Phase 3 — derived (2 commits)

#	Function	Source lines	Target
1	fit_pcr_svd	model.cpp:3397-3684	models/pcr/pcr.cpp
2	fit_opls_nipals	model.cpp:2000-2349	models/opls/opls.cpp

Phase 4 — classification (3 commits)

#	Function	Source lines	Target
1	fit_di_pls	model.cpp:3921-4162	models/classification/pls_da.cpp
2	fit_pls_qda	extra_pls.cpp:847-944	models/classification/pls_qda.cpp
3	fit_pls_cox	extra_pls.cpp:945-1029	models/classification/pls_cox.cpp

Phase 5 — sparse (4 commits)

#	Function	Source lines	Target
1	fit_pls_sparse_simpls	model.cpp:4163-4387	models/sparse/sparse_simpls.cpp
2	fit_sparse_pls_da	extra_pls.cpp:307-366	models/sparse/sparse_pls_da.cpp
3	fit_group_sparse_pls	extra_pls.cpp:367-444	models/sparse/group_sparse.cpp
4	fit_fused_sparse_pls	extra_pls.cpp:445-480	models/sparse/fused_sparse.cpp

Phase 6 — specialized + ensembles + transfer (12 commits)

#	Function	Source lines	Target
1	fit_cppls	extra_pls.cpp:481-550	models/specialized/cppls.cpp
2	fit_weighted_pls	extra_pls.cpp:551-616	models/specialized/weighted.cpp
3	fit_robust_pls	extra_pls.cpp:617-677	models/specialized/robust_huber.cpp
4	fit_ridge_pls	extra_pls.cpp:678-736	models/specialized/ridge.cpp
5	fit_continuum_regression	extra_pls.cpp:737-799	models/specialized/continuum.cpp
6	fit_missing_aware_nipals	extra_pls.cpp:1333-1397	models/specialized/missing_aware_nipals.cpp
7	fit_pls_glm	extra_pls.cpp:800-846	models/glm/pls_glm.cpp
8	fit_mir_pls	extra_pls.cpp:1243-1332	models/local/mir_pls.cpp
9	fit_pds	extra_pls.cpp:1030-1140	transfer/pds.cpp
10	fit_ds	extra_pls.cpp:1141-1242	transfer/ds.cpp
11	fit_bagging_pls + fit_boosting_pls + fit_random_subspace_pls	extra_pls.cpp:1477-1647	models/ensembles/{bagging,boosting,random_subspace}.cpp (3 commits)

Phase 7 — core dispatch (2 commits)

#	Function	Source lines	Target
1	predict_into + fit_model + transform_into + model_array	model.cpp:3885-3920 and 4388-4541	models/core/dispatch.cpp
2	approximate_press	extra_pls.cpp:1398-1476	models/core/approximate_press.cpp

Final cleanup

After all 7 phases land:

• cpp/src/core/model.cpp reduces to either an empty file (and is deleted) or to a tiny placeholder that just re-includes the new files (for backward-compat).

• Same for cpp/src/core/extra_pls.cpp.

• cpp/src/CMakeLists.txt no longer references the two monoliths; instead it picks up cpp/src/core/models/**/*.cpp and cpp/src/core/transfer/*.cpp (still explicit listing, no GLOB).

Per-commit gate

Each phase’s individual commit must pass:

1. cmake --build --preset dev-release builds without errors.

2. ./build/dev-release/cpp/tests/n4m_tests reports 265 run, 0 failures, 0 skipped.

3. ./build/dev-release/cpp/cli/n4m_cli --selfcheck reports selfcheck OK.

4. Optional: objdump -T build/dev-release/cpp/src/libn4m.so.1 | grep ' n4m_' | wc -l returns the same count as before the extraction (no symbol drop or duplication).

What is in M4 today (this commit)

• 39 stub files at all target paths under cpp/src/core/models/{pls,opls,pcr,sparse,multiblock,local,ensembles,specialized,classification,glm,core}/ and cpp/src/core/transfer/. Each stub carries a structured header naming the origin source, the line range to extract, and the function(s) it will receive.

• Two reports (SPLIT_PLAN.md from the Explore agent + this EXTRACTION_RECIPE.md).

• No changes to model.cpp, extra_pls.cpp, or cpp/src/CMakeLists.txt. pls4all builds unchanged, n4m_tests 265/265 green.

What is NOT done in M4

• The actual function-body extraction (Phases 1–7 above). The 28 algorithm extractions plus 3 helper extractions plus the cleanup are roadmap-budgeted at 4 days of careful work. They are deferred to a focused refactor session that can dedicate a build/test cycle per extraction.

• Multiblock subcategory has no stubs because all multiblock methods (mb_pls, n_pls, o2pls, so_pls, on_pls, rosa, multiblock_extensions) live in separate cpp/src/core/*.cpp files already — they need re-categorisation rather than extraction. Those moves are simpler and can land in M5/M6.

Sequencing within the merge

Per MERGE_ROADMAP.md §9 critical path: M3 → M4 → M5 → M6 → M7 → M8 → ...

The M4 scaffold unblocks M5 (ABI rename) because M5 operates on the monoliths in place. After M5, the post-rename monoliths can be extracted into the M4 stubs as planned here. The execution becomes:

1. M5 mechanical n4m_* → n4m_* rename on model.cpp, extra_pls.cpp in place.

2. M4 Phase 1 (extract helpers) on the renamed monoliths.

3. M4 Phases 2–7 on each algorithm.

This is the order the agent’s plan implies.