S1 — Amend ADR-002: io/ is a codec the frames call, not a layer above them (closes C-82)

[Polichinel]

S1 of epic #240. Closes #241 and register C-82. Documentation only — src/ is untouched, no public API changes, CONFORMANCE_FLOOR stays 1.0.0.

The problem

ADR-002 §Decision said io/ "sits at the top, imports the frames to serialize them" and "Nothing lower may import io/", and §Forbidden Patterns listed "a frame importing io/" as an architectural violation. docs/standards/physical_architecture_standard.md:48-49 restated it; :67 made it an operational Circular Dependency Guard.

The code is the inverse. io/npz.py and io/arrow.py import only json, pathlib, typing, numpy, pyarrow and views_frames._typing — neither imports a frame. feature_frame.py:21, prediction_frame.py:20 and target_frame.py:18 each do from views_frames.io import npz and call npz.save(...) / npz.load(...). The pattern the ADR forbade was used in three of the leaf's core files.

Why the documents move and not the code

1. Persistable puts persistence on the frame. protocols.py:62 declares save(directory) / load(directory, mmap) as frame methods. Once persistence is a frame method, the frame must reach the serializer.
2. C-09 is the origin. Resolved 2026-06-21 (v0.1.0): "io/npz operates on a generic frame state dict; the I/O layer carries no per-frame schema." That resolution inverted the dependency. Neither topology document was amended — fourteen months, until Run the import contracts as a gate, and register what writing them turned up (#238) #239's import contracts forced the question.
3. The result serves ADR-002's own goal better than its prescription did. The stated aim was that io/ change "for its own reasons, not when a frame's schema changes." io/ never importing a frame guarantees that more strongly than io/ importing three of them.

save/load are frozen v1 surface (ADR-018), so correcting the code would be a MAJOR bump with a cross-repo merge train — to fix a documentation error.

Amended, not superseded

ADR-000 says a changed decision is superseded, not erased — but the decision did not change. Direction is still one-way and acyclic (grimp: 36 modules, 89 dependencies, zero cycles). Only the factual claim about which way io/ runs was wrong. That is an amendment, following ADR-019's precedent (**Status:** Accepted (amended … — see *Amendments* below)).

What changed

• docs/ADRs/002_topology_and_dependency_rules.md — an Amendment blockquote recording the above; the intra-package section rewritten to name all eleven leaf modules (it named four, omitting _typing — the highest fan-in in the leaf at 8 — plus metadata, io and conformance); the §Layering Principle worked example reversed; the §Forbidden Patterns clause corrected; the §Context passage that named the wrong failure mode fixed.
• docs/standards/physical_architecture_standard.md — the layering paragraph and Circular Dependency Guard. The directory tree in that file is stale in other ways and is deliberately untouched here — that is C-84 / S2 (S2 — Rewrite the physical-architecture standard's directory tree (closes C-84) (Epic #240) #242), which is blocked on this PR precisely because both edit this file.
• docs/CICs/Protocols.md — records that Persistable is why the frames depend on io/. Last reviewed moved from 2026-06-24 (the oldest CIC, and the protocol at the centre of this).
• pyproject.toml — the [tool.importlinter] comment no longer says the ADR is out of date, now that it isn't.
• reports/technical_risk_register.md — C-82 closed and moved to Resolved; open 18 → 17, resolved 64 → 65.

Verification

Per register C-77's discipline, the resolution pastes evidence rather than describing it.

Every stale claim is gone — the only remaining occurrences anywhere under docs/ are inside the amendment text explaining the correction:

$ grep -rn "sits at the top\|imports the frames to serialize\|a frame importing \`io/\`\|no core module may import" docs/ README.md CLAUDE.md
docs/ADRs/002_topology_and_dependency_rules.md:8:  (amendment text)
docs/ADRs/002_topology_and_dependency_rules.md:9:  (amendment text)

All eleven modules checked against find src/views_frames -name '*.py' — _typing, metadata, spatial_level, _validation, io, index, protocols, feature_frame, prediction_frame, target_frame, conformance: all present, none missing.

$ uv run lint-imports          → 2 kept, 0 broken
$ bash docs/validate_docs.sh   → PASSED
$ uv run ruff check .          → All checks passed
$ uv run ruff format --check . → 77 files already formatted
$ uv run mypy src/             → no issues in 36 source files
$ uv run pytest --cov --cov-fail-under=100 → 100.00%, green

⚠ One deliberate intermediate state

physical_architecture_standard.md is more internally inconsistent after this PR than before it, and that is intentional. The corrected layering paragraph now names _typing and metadata as the lowest layer — neither appears in the directory tree ten lines above, because that tree still omits them.

The tree is C-84 / #242, the next story, and it is blocked on this PR precisely because both edit this file. Fixing the tree here would reopen the conflict the split exists to prevent. Flagging it so a reviewer reads the mismatch as scheduled rather than missed.

Not in this PR

The rest of the physical-architecture standard's staleness — a tree showing one of three packages, omitting metadata.py / _typing.py / conformance/, and listing two files that never shipped — is C-84 / #242, the next story.

🤖 Generated with Claude Code