Add experimental controls for degenerate TransnnMIL fusion

[matthewvaishnav]

Established defect

The historical TransnnMIL final fusion passes one TransMIL query token and one nnMIL key/value token through multi-head attention. With exactly one key, the attention softmax is one and the fused representation is invariant to the TransMIL query. Historical code and checkpoints remain untouched for reproducibility.

Experimental artifacts

This pull request adds three neutrally named controls:

• transnnmil_concat_experimental — concatenation plus projection;
• transnnmil_gate_experimental — sample-specific normalized gate;
• transnnmil_branch_attention_experimental — explicit branch-type embeddings, two-token self-attention, and separately named learned pooling weights.

No variant is described as corrected or improved before controlled training.

Hostile-review fixes completed

• factory integration for all three experimental model types;
• a dedicated PANDA fusion experiment trainer;
• topology explicitly rejected because the historical parent contains an unregistered forward-created projection;
• direct branch-token API rather than pretending to be nn.MultiheadAttention;
• historical query-invariance regression test;
• explicit branch identities;
• concat and gate baselines;
• checkpoint round-trip tests;
• branch-gradient and branch-sensitivity tests;
• separate names for branch-pooling and self-attention weights;
• targeted GitHub Actions CI;
• controlled evaluation and collapse-diagnostic protocol.

Current decision boundary

The defect diagnosis is established by code and mathematics. Architectural improvement is not established.

CI is passing, but this pull request should remain unmerged until the two open scientific/software-validity blockers are resolved:

• Block TransnnMIL performance claims until evaluation protocol matches the trainer #42: the trainer must implement the promised locked comparison protocol, including standalone nnMIL and TransMIL controls, immutable shared splits, a confirmation partition, repeated seeds, paired uncertainty estimates, and required collapse/runtime diagnostics;
• Raise executable coverage for PR #41 fusion implementations before merge #43: the new fusion implementations and factory paths require materially stronger direct executable coverage, including branch-gradient, branch-sensitivity, gate-boundedness, checkpoint, topology-rejection, and invalid-model tests.

Publication claims require repeated-seed PANDA comparisons against standalone nnMIL, standalone TransMIL, historical TransnnMIL, concat, gate, and branch-attention variants under an identical locked protocol. Results from the public PANDA development cohort must be labeled internal-development evidence rather than blinded external validation.

[matthewvaishnav]

CI review: the dedicated TransnnMIL fusion CI workflow passed, as did Quick Check, security, repository audit, root-layout, and paper-build checks. The repository-wide CI workflow is currently blocked only by the Black formatting step in Lint and Format Check; flake8 and mypy passed before the matrix was cancelled/skipped downstream. This is a mechanical formatting blocker, not evidence against the fusion tests or defect diagnosis. The draft should remain unmerged until the affected Python files are formatted and the full CI workflow is green.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 3.22581% with 180 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/models/transnnmil/transnnmil_branch_token.py	0.00%	66 Missing ⚠️
src/models/transnnmil/branch_token_fusion.py	0.00%	64 Missing ⚠️
src/models/factory.py	12.50%	42 Missing ⚠️
src/models/transnnmil/__init__.py	0.00%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!