docs(design): format records and their layering (#415)

[balbasty]

This PR adds docs/design/format-records.md, the design note for #415. Format classes hold a record of their file instead of inheriting a parser. The note also covers how the record relates to the format metadata of #233.

It records the design decided in #415:

• Layers:
  • the model API (Metadata, Image, Transformation);
  • the dispatchers (MetadataFormat, ImageFormat, TransformationFormat);
  • <X>Metadata holding the <X>Raw header record;
  • <X>Image/<X>Transformation holding <X>Metadata and a raw data object.
• Inheritance: only the stateless reader/writer bases are inherited. Each class delegates one level down: format object → metadata → raw.
• Data: raw is the only stored array, and data is a cached view decoded from it by exact, invertible to_model/to_disk pairs.
• Write precedence: the record, then the geometry from the model, then the header, then the data.
• Rules and public surface: private submodules; Raw and Metadata classes are public, proxies are private.
• Relation to the Design memo for the format-metadata framework #306 memo, and the implementation passes.

This is a living document. Its last section, "Open tensions and workarounds", is updated as the implementation PRs find problems, edge cases and workarounds. The implementation goes in stacked PRs, starting with the core (pass 1a) and NIfTI.

Documentation only. ruff check, ruff format --check and codespell are clean.

Refs #415, #233

🤖 Generated with Claude Code

https://claude.ai/code/session_01M3KmPTJ2CihFMCFaJ4twx8

---

Generated by Claude Code

[balbasty]

lint / spellcheck fails here for a reason outside this PR. The codespell-project/actions-codespell@v2 action could not build its Docker image: "Docker build failed with exit code 1", three attempts. No spell check ran.

The same failure came back on the one re-run. Nothing in this PR can fix it, since it only adds a Markdown file. The same check passed on main at 77e0807 a few hours ago, and uvx codespell -I codespell-ignore-words.txt is clean on this branch locally. I'll check again later and re-run once the action builds.

---

Generated by Claude Code