Refactor NNUNet primitives into testable production modules with explicit contracts

[vincenzoml]

Problem

voxlogica.primitives.nnunet.kernels contains operationally heavy logic (env setup, file orchestration, subprocess execution, data conversion) with broad responsibilities in one module.

Why this matters

• Harder to reason about failure modes and guarantee reproducibility.
• Difficult to test deterministically in CI and local dev.
• Contract boundaries with execution/storage are not sufficiently explicit for long-term maintainability.

Scope

1. Split NNUNet primitive implementation into layers:

• config/env resolution
• dataset staging/validation
• command execution adapter
• result parsing/reporting

2. Introduce strict input contract validation and structured error taxonomy.
3. Add dry-run mode for command generation and validation.
4. Add integration tests with lightweight fixtures + mocked command execution.
5. Document supported NNUNet/torch/python matrix and operational assumptions.

Non-goals

• Solving all CUDA/driver environment issues across platforms in one issue.
• End-to-end training benchmarks in CI.

Deliverables

• Refactored module set under primitives/nnunet/ with smaller focused units.
• Contract tests validating inputs/outputs and key error cases.
• Developer documentation for deployment and troubleshooting.

Acceptance criteria

• Core train/predict orchestration paths are covered by deterministic tests.
• Error reporting for missing env/dependencies/dataset format is actionable.
• Public primitive interface remains stable or documented with migration notes.

Risks

• Hidden behavior dependencies in current users' pipelines.

Mitigations

• Introduce compatibility adapter layer and staged deprecations.
• Provide explicit before/after examples in docs.