design record: every build emits one

Result gains a record field with a default. Nothing existing moves and the report dict is untouched, so all 123 oracle cases are unmoved at 506 passed. A rejected profile still raises before this point and gets no record, which is correct because there is no model to preserve.

The record learns the stock and fit from the Geo the build actually used, so it describes what was built rather than what was asked for. Those agree today and the record will keep saying so if they ever stop.

code_revision resolves once per process from MECHCOMP_REVISION, then git rev-parse, then unknown. Never a guess: unknown tells you the part may not be reproducible, while a plausible wrong sha would send someone to the wrong commit. A dirty tree is reported as such, since a model built from uncommitted edits cannot be regenerated from a revision alone. Caching matters because assemble runs 123 times in the suite and would otherwise shell out to git twice per build.

The end to end test builds a part, renders its record, parses it back from nothing but the text, rebuilds from the parsed parameters, and asserts the report is identical key for key across five profiles. If that fails the record is a description rather than a recipe.

Method correction. The mutation harness had been letting pytest write bytecode, and a write landing inside one mtime tick could be masked by a stale pyc. That made one real defect appear to survive and, more importantly, means every mutation result reported earlier in this work was optimistic by an unknown amount. Rerun with bytecode disabled, all nine mutations caught. The earlier sets are worth rerunning under the corrected method.

tests/test_design_record.py

@@ -265,6 +265,153 @@ def test_missing_report_keys_are_omitted_not_invented():
     assert "MASS_G" not in rec.verification
 
 
+def test_build_emits_a_record_that_regenerates_the_same_report():
+    """
+    The end-to-end claim, asserted rather than argued.
+
+    Build something. Render its record. Read the record back with nothing but
+    the text. Rebuild from the parsed parameters. The report must be
+    identical, key for key. If it is not, the record is a description of a
+    part rather than a means of rebuilding it, and preservation is a claim we
+    cannot make.
+    """
+    build = pytest.importorskip("mechcomp.profiles").build
+
+    for profile, params in (
+        ("Y", {}),
+        ("Y", {"fit_clearance_mm": 0.15}),
+        ("T", {"t_stem_web_mm": 1.6, "bundle_count": 2}),
+        ("Three-Fin", {"three_fin_bore_side_mm": 15.0}),
+        ("A Frame", {"a_frame_leg_angle_deg": 53}),
+    ):
+        first = build(family="3x", profile=profile, params=params)
+        assert first.record is not None, "build produced no design record"
+
+        text = first.record.render()
+        recovered = type(first.record).parse(text)
+
+        assert recovered.input_id == first.record.input_id
+        assert recovered.family == "3x"
+        assert recovered.profile == profile
+
+        # Rebuild using ONLY what came out of the text.
+        again = build(family=recovered.family, profile=recovered.profile,
+                      params=recovered.params)
+
+        assert again.report == first.report, (
+            "regenerating %s from its own design record produced a different "
+            "report" % profile)
+        assert again.record.input_id == first.record.input_id
+        assert again.record.build_id == first.record.build_id
+
+
+def test_tuning_a_parameter_changes_the_identity_of_the_part():
+    """
+    The failure this whole module exists to prevent: two prints at different
+    settings that cannot be told apart afterwards.
+    """
+    build = pytest.importorskip("mechcomp.profiles").build
+
+    seen = {}
+    for clearance in (0.15, 0.2, 0.25, 0.3):
+        r = build(family="3x", profile="Y",
+                  params={"fit_clearance_mm": clearance})
+        ident = r.record.input_id
+        assert ident not in seen, (
+            "clearance %s and %s produced the same input_id -- two different "
+            "parts would be indistinguishable" % (clearance, seen.get(ident)))
+        seen[ident] = clearance
+        assert "fit_clearance_mm=%r" % clearance in r.record.render()
+
+
+def test_record_describes_the_stock_and_fit_actually_used():
+    build = pytest.importorskip("mechcomp.profiles").build
+
+    r = build(family="3x", profile="Y",
+              params={"strap_width_mm": 13.4, "fit_clearance_mm": 0.15,
+                      "bundle_count": 2})
+    text = r.record.render()
+
+    # Target the stock line itself. Asserting "13.4" appears somewhere
+    # in the record is not enough -- it also appears as strap_width_mm in
+    # the parameter block, so a designation hardcoded to the family
+    # default would pass unnoticed.
+    stock_lines = [l.strip() for l in text.splitlines()
+                   if l.strip().startswith("stock ")]
+    assert stock_lines, "no stock line in the record"
+    assert stock_lines[0].startswith("stock 13.4 x 0.508 mm x2, stack 1.016 mm"), (
+        stock_lines)
+
+    assert "clearance 0.1500 mm per face" in text
+    assert "build parameters" in text
+
+
+def test_a_rejected_profile_produces_no_model_and_no_record():
+    """There is nothing to preserve, and the rejection is unchanged."""
+    profiles = pytest.importorskip("mechcomp.profiles")
+
+    with pytest.raises(profiles.ProfileRejected):
+        profiles.build(family="3x", profile="Y",
+                       params={"min_wall_mm": 0})
+
+
+def test_code_revision_is_resolved_or_honestly_unknown():
+    """
+    Never a guess. "unknown" tells you the part may not be reproducible; a
+    plausible wrong revision would send someone to the wrong commit.
+    """
+    from mechcomp.design_record import code_revision
+
+    rev = code_revision()
+    assert rev
+    assert rev == code_revision(), "code_revision is not stable per process"
+    if rev != "unknown":
+        head = rev[:-len("-dirty")] if rev.endswith("-dirty") else rev
+        assert len(head) >= 7
+        assert all(c in "0123456789abcdef" for c in head), rev
+
+
+def test_code_revision_honours_an_explicit_revision(monkeypatch):
+    import mechcomp.design_record as dr
+
+    monkeypatch.setattr(dr, "_CODE_REVISION", None)
+    monkeypatch.setenv("MECHCOMP_REVISION", "deadbee")
+    assert dr.code_revision() == "deadbee"
+
+
+def test_code_revision_is_cached_not_recomputed(monkeypatch):
+    # Caching is not a micro-optimisation. Without it every build shells
+    # out to git twice, and assemble runs 123 times in the acceptance
+    # suite alone -- a subprocess in a geometry compilers build path.
+    import mechcomp.design_record as dr
+
+    monkeypatch.setattr(dr, "_CODE_REVISION", None)
+    monkeypatch.setenv("MECHCOMP_REVISION", "first00")
+    assert dr.code_revision() == "first00"
+
+    monkeypatch.setenv("MECHCOMP_REVISION", "second0")
+    assert dr.code_revision() == "first00", (
+        "code_revision recomputed instead of using its cache")
+
+
+def test_code_revision_falls_back_to_unknown_not_a_fabrication(monkeypatch):
+    # When git cannot answer, the record must say so. A plausible wrong
+    # sha would send someone to the wrong commit, which is worse than
+    # admitting the part may not be reproducible.
+    import subprocess
+
+    import mechcomp.design_record as dr
+
+    monkeypatch.setattr(dr, "_CODE_REVISION", None)
+    monkeypatch.delenv("MECHCOMP_REVISION", raising=False)
+
+    def refuse(*a, **k):
+        raise OSError("git unavailable")
+
+    monkeypatch.setattr(subprocess, "run", refuse)
+    assert dr.code_revision() == "unknown"
+
+
 def test_bools_survive_the_round_trip():
     """``length_view`` is a string and some profile extras are bools."""
     assert canonical_value(True) == "true"