From 9252b4b7edee433cd85de35cf47b7f76c52a3f36 Mon Sep 17 00:00:00 2001
From: Kim Morrison <kim@tqft.net>
Date: Sat, 22 Aug 2026 03:37:51 +0000
Subject: [PATCH] refactor: qualify results schema terminology

---
 docs/catalog-metadata.md      | 2 +-
 scripts/v1_audit.py           | 6 +++---
 tests/python/test_v1_audit.py | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/catalog-metadata.md b/docs/catalog-metadata.md
index 01638aa4c..3fdf22cf7 100644
--- a/docs/catalog-metadata.md
+++ b/docs/catalog-metadata.md
@@ -55,7 +55,7 @@ through lifecycle metadata rather than deleting members.
 
 ## v1 evidence
 
-The audit tool reads either schema-v1 or schema-v2 result files and emits stable
+The audit tool reads either schema version 1 or schema version 2 result files and emits stable
 JSON and Markdown solve-count reports:
 
 ```bash
diff --git a/scripts/v1_audit.py b/scripts/v1_audit.py
index 5ef0c27c6..24a1c3d28 100644
--- a/scripts/v1_audit.py
+++ b/scripts/v1_audit.py
@@ -53,11 +53,11 @@ def _v1_records(data: Mapping[str, Any], path: pathlib.Path) -> Iterable[dict[st
             }
 
 
-def _v2_records(data: Mapping[str, Any], path: pathlib.Path) -> Iterable[dict[str, Any]]:
+def _schema_v2_records(data: Mapping[str, Any], path: pathlib.Path) -> Iterable[dict[str, Any]]:
     file_user = data.get("user")
     records = data.get("results")
     if not isinstance(records, list):
-        raise AuditError(f"{path}: v2 file requires results array")
+        raise AuditError(f"{path}: schema version 2 file requires results array")
     for index, record in enumerate(records):
         if not isinstance(record, dict):
             raise AuditError(f"{path}: results[{index}] must be an object")
@@ -87,7 +87,7 @@ def load_records(results_dir: pathlib.Path) -> tuple[list[dict[str, Any]], int]:
         if version == 1:
             loaded = _v1_records(data, path)
         elif version == 2:
-            loaded = _v2_records(data, path)
+            loaded = _schema_v2_records(data, path)
         else:
             raise AuditError(f"{path}: unsupported schema_version {version!r}")
         for record in loaded:
diff --git a/tests/python/test_v1_audit.py b/tests/python/test_v1_audit.py
index a00b94a3e..90b4583d2 100644
--- a/tests/python/test_v1_audit.py
+++ b/tests/python/test_v1_audit.py
@@ -17,7 +17,7 @@
 
 
 class V1AuditTest(unittest.TestCase):
-    def test_v1_and_v2_records_produce_deterministic_evidence(self):
+    def test_schema_v1_and_schema_v2_records_produce_deterministic_evidence(self):
         with tempfile.TemporaryDirectory() as directory:
             results = pathlib.Path(directory)
             (results / "v1.json").write_text(json.dumps({