# Step 7: math-solver-adapters

## Sprint Contract

### Objective
Implement vector, sparse matrix, and linear solver interfaces plus a deterministic test solver adapter while preserving future MKL/TBB adapter boundaries.

### Required Reading
- /AGENTS.md
- /PROGRESS.md
- /PLAN.md
- /docs/README.md
- /docs/HARNESS_ENGINEERING.md
- /docs/ARCHITECTURE.md
- /docs/ADR.md
- /docs/NUMERICAL_CONVENTIONS.md
- /phases/1-linear-static-mitc4/step6.md

### Scope
- Add minimal vector and sparse matrix abstractions needed by assembly and linear static solving.
- Add a linear solver interface with deterministic test implementation.
- Keep MKL/TBB-specific code behind adapter boundaries if any placeholder is added.
- Surface solver singularity diagnostics in a structured way.

### Allowed Files
- `include/**`
- `src/**`
- `tests/**`
- `docs/ADR.md` if adapter decisions need clarification
- `PLAN.md`
- `PROGRESS.md`
- `phases/1-linear-static-mitc4/index.json`

### Explicit Non-Goals
- Do not require Intel oneAPI installation for Phase 1 unit tests.
- Do not expose MKL, TBB, or HDF5 APIs in solver core headers.
- Do not implement element assembly or analysis algorithms in this step.

### Tests To Write First
- Sparse pattern and insertion tests with int64 indices.
- Deterministic small linear solve tests.
- Singular solve diagnostic tests.
- Adapter-boundary tests or compile checks showing core APIs do not include MKL/TBB headers.

### Reference Artifacts
- None.

### Acceptance Commands
```bash
python scripts/validate_workspace.py
```

### Evaluator Checklist
- Core math interfaces are dependency-clean.
- Singular solver failures produce diagnostics, not crashes or silent NaNs.
- Tests cover sparse storage, solve success, and solve failure.
- Future MKL acceleration remains possible without changing solver core contracts.

### Handoff Requirements
- Record math interfaces, validation, and adapter caveats in `PROGRESS.md`.
- Update `PLAN.md` if MKL/TBB integration becomes a future task.
- Update the matching phase index entry: use `completed` with a one-line `summary`, or `blocked` with `blocked_reason`, or `error` with `error_message`.

## Verification
1. Run the acceptance command.
2. Inspect public headers for third-party API leakage.

## Do Not
- Do not optimize sparse storage before correctness and testability are established.