feat(math): PCA warm start in clojure-legacy engine mode (PR-B)

[jucor]

Threads the previous tick's unit components into the power-iteration PCA as
start vectors when POLISMATH_ENGINE_MODE=clojure-legacy, matching Clojure
(conversation.clj:381-387 passes :start-vectors (get-in conv [:pca :comps])
into powerit-pca, pca.clj:86-105; new columns absorbed by 1-padding,
pca.clj:46-49). Default 'improved' mode is unchanged (cold recompute).

• pca_project_dataframe gains start_vectors (default None) and require_powerit
  (default False). With both absent the code path is BYTE-IDENTICAL to before.
  When a warm start is supplied — or required by legacy mode — and
  POLISMATH_PCA_IMPL=sklearn is set, we warn and fall back to power iteration:
  sklearn's SVD has no start-vector hook, so running it would silently drop the
  warm start (documented at the guard).
• powerit_pca already supported start_vectors + 1-padding + all-zero->None;
  this just wires production callers to it.
• Conversation._compute_pca: in legacy mode sets require_powerit=True and, when
  prev_pca has real comps, start_vectors = prev comps (empty/cold -> None, the
  deterministic random cold draw). prev_pca is captured in recompute() (PR-A).

Semantic judgment calls (integrator, please verify vs Clojure):

• Warm start is POSITIONAL: prev comps align to current columns by index, and
  new (appended) comments are 1-padded — exactly Clojure's behavior. Column
  removal/reorder would misalign, but Clojure is append-only here and
  _power_iteration truncates a too-long start vector defensively (pre-existing,
  pca.py:124-127) where Clojure would error.
• "legacy implies powerit" is enforced via require_powerit=True even on the
  cold first tick, so an operator setting PCA_IMPL=sklearn + legacy still gets
  powerit (with a warning).

TDD RED evidence (before implementing):
test_start_vectors_reach_powerit:
"TypeError: pca_project_dataframe() got an unexpected keyword argument
'start_vectors'"
test_legacy_tick2_receives_tick1_comps: "assert None is not None"
(tick 2 ran cold; no comps threaded)

Tests: 8 new (start_vectors threading, sklearn-conflict warning, improved
byte-identity, two-tick legacy warm start via spy, angle stability, cold-tick
cross-mode identity). Full suite 422 passed, 17 skipped, 47 xfailed.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

commit-id:be96f1da

---

Stack:

• docs(delphi): overnight pre-cutover audit (s6) — CUTOVER_RUNBOOK + journal #2659
• feat(delphi): zid-sharding for the math poller — one shard = one process #2658
• ci: run postgres integration tests #2637
• feat(delphi): poller-equivalence harness (goal condition 2) — PASSES live on vw + pc-meta-02 #2657
• feat(math): moderation + restart replay parity — mod_update, restart-seam restore, Q13-Q18 #2656
• docs(delphi): R1-parity goal docs, journal (2026-07-18 → 07-24 s5), quirks + divergence ledger #2626
• feat(delphi): Q12 carve-out — pin the cold-tick PCA start to ones in both replay drivers #2655
• feat(math): Q11 — replicate vectorz distance cancellation in legacy kmeans #2654
• feat(math): small-N degenerate parity — run the real math on tiny matrices in clojure-legacy mode #2653
• feat(delphi): Q10 carve-out — pin large-conv cutoffs to certify the deterministic full-PCA path #2652
• feat(delphi): replay loader resolves private datasets under real_data/.local #2651
• feat(math): Clojure hash-map iteration order for the in-conv greedy tie-break (legacy) #2650
• feat(math): clojure-legacy blob emission + selection parity — Clojure-exact math_main at step 0 #2649
• feat(delphi): acceptance canonicalization — suppress cross-engine ordering artifacts in certify comparer #2648
• feat(delphi): certify.py battery runner + focuser + fingerprint ledger (Spec A, Phase 0) #2647
• feat(delphi): prodclone extractor — feature-filtered dataset export (Spec B) #2646
• feat(math): un-mirror priority_metric (#2571 resolved) + Q2 prev-tick group-votes #2645
• feat(math): participant-ban leak replication in clojure-legacy mode (Q1) #2644
• feat(delphi): Clojure timing probe (Spec C) #2643
• feat(math): degenerate-tick group-clusterings overwrite + <2-participants edge (legacy mode) #2642
• refactor(math): move impl-flag resolver to polismath/utils/env_flags.py #2641
• feat(delphi): Python math poller service (phase 1) — Clojure math-container replacement #2625
• fix(delphi): Clojure-parity math writers + committing write path in PostgresClient #2624
• feat(math): in-conv greedy floor + persistent carry (PR-E) #2623
• feat(math): Clojure-exact base-cluster lineage + warm start (PR-C) #2622
• feat(math): replay harness H-B — Clojure Mode A driver (dev/replay.clj) + cross-language comparer shim #2621
• feat(math): group-k-smoother in clojure-legacy engine mode (PR-D smoother) #2620
• feat(math): PCA warm start in clojure-legacy engine mode (PR-B) #2640 ⬅
• feat(math): add POLISMATH_ENGINE_MODE flag + prev-tick warm-start scaffolding (PR-A) #2618
• feat(delphi): replay harness H-A — schedule spec+slicer, Python driver, store, step comparer, CLI #2639
• fix(delphi): cold-start generator copies FULL revote history (no DISTINCT ON dedup) #2638
• fix(math): correct comment-extremity sign in pca_project_cmnts (D1b) #2615
• docs(delphi): add math-algorithm history & routing-regression reference #2613

---

⚠️ Part of a stack created by spr. Do not merge manually using the UI - doing so may have unexpected results.

[Copilot]

Pull request overview

Adds Clojure-parity PCA warm-start behavior to the Python Delphi math pipeline when POLISMATH_ENGINE_MODE=clojure-legacy, by threading the previous tick’s PCA components into the power-iteration solver as start vectors, while keeping the default improved mode cold/recompute behavior unchanged.

Changes:

• Extend pca_project_dataframe to accept start_vectors and require_powerit, and ensure sklearn PCA is not used when warm-start/powerit is required (warn + fall back).
• In Conversation._compute_pca, when in legacy mode, require power-iteration and feed previous tick’s pca['comps'] as warm-start vectors when available.
• Add a dedicated test module covering threading, fallback warning, and two-tick warm-start behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
delphi/polismath/pca_kmeans_rep/pca.py	Adds warm-start/powerit forcing controls and sklearn-conflict warning/fallback; threads start_vectors into powerit_pca.
delphi/polismath/conversation/conversation.py	Wires legacy engine mode to require power-iteration and optionally seed PCA from previous tick comps.
delphi/tests/test_pca_warm_start.py	New tests validating warm-start threading, warning/fallback behavior, and cold-path invariance across modes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.