feat(api)!: a saved answer is stamped with layout 1 and the specsolve version that wrote it, and one written by 0.1.0 or earlier is refused by name

[FBumann]

Prompt: we should add some sort of archive version or specsolve version to the archives to ensure backwards compat if we change sth later

Later: "use layout: 1".

Note

The following content was generated by AI.

Every saved answer, archives included, carried format.json as {"answer": 0}, whatever build wrote it. It now reads {"layout": 1, "specsolve": "<version>"}: a layout number that covers everything specsolve writes, and the version that wrote it. Breaking: 0.1.0 shipped without this, so an answer 0.1.0 wrote is refused.

What changes, why these choices, tests, gates, not done

What was there. relational/parquet.py stamped every answer directory with format.json. Every reader refused any other number with a LayoutError: load_result, scan_result, a sweep, a spill resume, and an archive's answer/. The number was held at 0 "while the layout is still moving", so every answer since the stamp was added, 0.1.0 and the alphas included, read as current. A layout change from here on could not have been told apart from any of them.

What changes

• The key is layout and the constant is LAYOUT = 1. The number covers what a result, a sweep and an archive write. A release that changes any of them raises it, and its notes name the change. The constant's comment, Result.save's docstring (which LayoutError points to) and AGENTS.md (under "Breaking changes are free") say so.
• format.json records specsolve: the version from the installed metadata, or null from a source tree nothing installed. It is written for the refusal message and for a human reading the file; no reader branches on it.
• The refusal names what it found: … holds a saved answer in layout 0, written by specsolve 0.0.1a359, and this package reads layout 1. … A stamp with no layout (what 0.1.0 and every earlier build wrote, {"answer": 0}) and a missing format.json both read … with no layout stamp …. Either way the message says to solve again and save.
• Answers written by 0.1.0 or earlier are refused by name, instead of being read as though their layout were current. Before 1.0 that is the stated rule, and the ! in the title marks the break for the release notes. An archive that 0.1.0 wrote still holds the spec and the data to solve again.

Why one stamp. An archive's answer/ is a saved answer and carries the same format.json, and reading an archive reads it through load_result. So one number covers results, sweeps and archives, and a second stamp at the archive root would be a second home for the same fact. The key is layout, not answer, because the number covers the archive's other members too.

Why the version comes from importlib.metadata: relational/ may import nothing from the package but errors (test_engine_is_isolated). This reads the same installed metadata as specsolve.__version__.

Tests

• test_a_saved_answer_is_stamped_with_its_layout_and_the_specsolve_that_wrote_it (new): a fresh save holds {"layout": 1, "specsolve": sps.__version__}.
• test_an_answer_in_another_layout_is_refused_by_name covers three cases: layout 0 from 0.0.1a359 (names the layout and the writer), 0.1.0's {"answer": 0}, and no format.json (both "with no layout stamp").
• On the first commit, both tests failed against the previous parquet.py and passed on the new one. That was checked by swapping the file back and restoring it from git.

Mutation table, from tools/mutate.py on fa8fc6a; the tree was clean after the run:

mutation	result
a stamp other than this layout is refused (parquet.py:73-82)	caught

Gates on the merge of main after #1769, in a uv environment (dev + docs groups, gurobi and xpress extras), because pixi cannot be installed here:

• ruff check . and ruff format --check . pass.
• pyrefly check: 0 errors.
• zensical build --strict builds, and the rendered API page carries the stamp paragraph under Result.save.
• pytest tests/test_docs_math.py tests/test_docstring_links.py: 70 passed.
• pytest -n auto: 4114 passed, 250 skipped, 1 xfailed.

Not done

• No reader for another layout. Before 1.0 nothing reads another layout back, and an archive holds the spec and the data to solve again.
• No mathspec version in the stamp. spec.yaml states the language version the file is written in.

🤖 Generated with Claude Code

https://claude.ai/code/session_016Pv7LzSgzt7Yn2K3ioyJXw

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 82 skipped benchmarks¹

---

_{Comparing claude/answer-layout-stamp (6529257) with main (8c783ca)²}

Footnotes

1. 82 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (c7ad4f2) during the generation of this report, so 8c783ca was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #34762820 | 📁 Comparing 6529257 against latest (c6af367)

  🔍 Preview build  

74 files changed · ± 74 modified

± Modified

• index.html
• about/index.html
• examples/index.html
• guide/index.html
• interactive/index.html
• lifecycle/index.html
• sweep/index.html
• tables/index.html
• about/architecture/index.html
• about/changelog/index.html
• and 64 more...