fix(comments): correct canary justification and expand failure guidance in padding tests

CMakeLists.txt

@@ -604,15 +604,15 @@ target_link_libraries(app_version_tests PRIVATE app_version)
 add_test(NAME app_version_tests COMMAND app_version_tests)
 
 # Anti-normalization padding canary (see tests/test_app_version_padding.cpp for the full
-# rationale). The live-version assertions in app_version_tests can only DETECT a
+# rationale). The live-version assertions in app_version_tests are version-shape-blind:
-# "reconstruct the string from numeric components" regression when the live version
+# relative checks (e.g. appVersion() == stampVersion()) hold whether the string was
-# happens to be zero-padded — at an unpadded version (e.g. 0.9.8) the reconstruction
+# threaded verbatim or reconstructed from numeric components, at any version, padded or
-# coincides with the verbatim string and the check silently goes vacuous. So: run the
+# not — the live suite cannot detect a reconstruct-from-components regression at all.
-# SAME version_generated.h.in template through configure_file a second time with a
+# So: run the SAME version_generated.h.in template through configure_file a second time
-# SYNTHETIC padded version, and compile the SAME src/app_version.cpp against that header
+# with a SYNTHETIC padded version, and compile the SAME src/app_version.cpp against that
-# (include-dir substitution — the canary target never sees the live generated/ dir).
+# header (include-dir substitution — the canary target never sees the live generated/
-# The "0.9.01" here is a permanent test fixture, NOT the shipped version (see also the
+# dir). The "0.9.01" here is a permanent test fixture, NOT the shipped version (see also
-# source-of-truth comment at the top of this file for the live-version invariant); it
+# the source-of-truth comment at the top of this file for the live-version invariant); it
 # must match the literals in test_app_version_padding.cpp and must never be bumped on
 # release.
 #

tests/test_app_version_padding.cpp

@@ -2,11 +2,10 @@
 // string threading (Phase V, V1 leading-zero fidelity). No REAPER, no framework.
 //
 // WHY THIS EXECUTABLE EXISTS: test_app_version.cpp pins stampVersion() relative to the
-// live configure_file'd version string — but a live-version assertion can only DETECT a
+// live configure_file'd version string — but a relative assertion (e.g. appVersion() ==
-// "reconstruct the string from numeric components" regression when the live version
+// stampVersion()) is version-shape-blind: it holds whether the string was threaded
-// happens to be zero-padded. "0.9.01" reconstructed via integers renders "0.9.1" and
+// verbatim or reconstructed from numeric components, at any version, padded or not.
-// trips it; "0.9.8" reconstructs to itself, so at an unpadded version the check passes
+// The live suite therefore cannot detect a reconstruct-from-components regression at all.
-// whether or not the code regressed — the guard silently goes vacuous while green.
 // Padded and unpadded versions are both legitimate (Daniel's ruling), so the guard must
 // not depend on the shipped version's shape.
 //
@@ -67,9 +66,11 @@ static void testCanaryFixtureIsNonVacuous() {
         std::to_string(wv.parsed.major) + "." +
         std::to_string(wv.parsed.minor) + "." +
         std::to_string(wv.parsed.patch);
-    // If this fails, the fixture is unpadded and the canary guards nothing.
+    // If this fails, one of two causes: (1) the fixture was changed to an unpadded form
-    // Restore a zero-padded fixture (e.g. "0.9.01") in CMakeLists.txt and
+    // (e.g. "0.9.1") — restore a zero-padded fixture (e.g. "0.9.01") in CMakeLists.txt
-    // update the matching literals in this file.
+    // and update the matching literals in this file; or (2) the fixture is still padded
+    // but app_version.cpp regressed to parse-and-reprint — in that case
+    // testPaddedVersionSurvivesThreadingVerbatim also fails, pointing at the real cause.
     CHECK(reprinted != stampVersion());
 }