feat: add clinical SLM memory preflight

[maziyarpanahi]

Pull Request

Description

Adds a deterministic, local-only memory admission check for local clinical SLM
loading. The preflight estimates weight, KV-cache, context, batch, and runtime
overhead bytes from bounded artifact metadata and an explicit runtime profile.
Loads that cannot preserve the configured headroom are rejected before model
construction with an aggregate, value-free resource report.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition/improvement

Changes Made

• Added ClinicalSLMRuntimeProfile, artifact metadata normalization, and
  deterministic memory estimation for weights, cache, context, batch, and
  runtime overhead.
• Added a fail-closed ClinicalSLMMemoryPreflightReport with stable
  memory_budget_exceeded and headroom_insufficient reason codes, aggregate
  byte arithmetic, and a normalized artifact fingerprint.
• Kept the preflight dependency-free and metadata-only: it makes no network
  call, imports no optional backend, and does not open model weight bytes.
• Added synthetic offline regression coverage for deterministic output,
  component manifests, local metadata paths, stat-only binary paths, alias
  normalization, shortfalls, and value-free errors.
• Added the memory-preflight guide and registered it in MkDocs and the
  publication contract.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this change with different models/inputs

Exact local validation:

• .venv/bin/python -m pytest tests/unit/models/test_clinical_slm_memory.py -q — 9 passed
• .venv/bin/python -m pytest tests/unit/models/test_bootstrap_check.py tests/unit/models/test_bundled.py -q — 29 passed
• make format — passed; 2,036 files left unchanged
• make lint — passed
• make format-check — passed; 2,036 files already formatted
• uv run --frozen --extra dev mypy openmed/models/clinical_slm_memory.py tests/unit/models/test_clinical_slm_memory.py — passed
• .venv/bin/python -m py_compile openmed/models/clinical_slm_memory.py tests/unit/models/test_clinical_slm_memory.py — passed
• git diff --cached --check — passed before commit
• make docs-build — passed; staged Pages artifact and publication validation completed

The documentation build emitted the repository’s existing Material-for-MkDocs,
un-navigated-page, and revision-timestamp notices; it did not fail. No
model-backed inference or real clinical inputs were used.

Checks intentionally not run: the full repository test suite, model-backed or
integration/benchmark gates, Swift/OpenMedKit checks (no Swift files changed),
remote CI checks, and gh pr checks --watch.

Documentation

• I have updated the documentation accordingly
• I have added docstrings to new functions/classes
• I have updated the CHANGELOG.md

The changelog and release metadata are intentionally unchanged; this PR does
not bump or publish a release.

Code Quality

• I ran make format, make lint, and make format-check
• For Swift/OpenMedKit changes, I ran make format-swift and make lint-swift
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings

Dependencies

• I have not added any new dependencies
• OR I have added new dependencies and they are justified because: ____

The implementation uses only the Python standard library; no package or lock
file changes are required.

Checklist

• I have read the contributing guide, Code of Conduct, and maintainer guide
• My commits have clear, descriptive messages
• I have squashed/organized my commits appropriately

Related Issues

Closes #2759

Screenshots/Examples

No UI changes. The documentation includes a synthetic weights_bytes example
and the exact weight/cache/context/batch arithmetic. Reports contain aggregate
resource values and a fingerprint only; they do not contain patient data,
credentials, model identifiers, paths, prompts, or model contents.