Record pinned SPSS engine identity

Author: TonisOrmisson

docs/sav-profile.md

@@ -32,8 +32,7 @@ equivalence of supported values, order, and dictionary metadata.
 
 The `openstatspec capabilities` command and the
 `openstatspec.capability_matrix()` function are the machine-readable declaration
-of this boundary. They deliberately distinguish a supported feature from a
-feature that the underlying engine cannot observe or write faithfully.
+of this boundary. It records the pinned source commit and installed engine version, and the adapter stores the same identity in every import and export operation record. The matrix deliberately distinguishes a supported feature from a feature that the underlying engine cannot observe or write faithfully.
 
 | SPSS semantic | Pinned pyspssio status | Behaviour |
 | --- | --- | --- |

src/openstatspec/api.py

@@ -7,6 +7,7 @@
 from .core import CapabilityDeclaration
 from .core.results import result
 from .spss import export_dataset, import_dataset, inspect_source
+from .spss.sav import engine_identity
 from .sql import declared_profiles, validate_dataset
 
 
@@ -21,6 +22,7 @@ def capability_matrix() -> Mapping[str, Any]:
     fail-closed feature has no faithful writer route at all.
     """
     return {
+        "engine": engine_identity(),
         "spss": {
             "values": "supported", "variable_labels": "supported",
             "value_labels": "supported",

src/openstatspec/spss/sav.py

@@ -39,6 +39,14 @@
 )
 
 _UTF8_ENCODINGS = {"UTF-8", "UTF8"}
+def engine_identity() -> dict[str, str]:
+    """Return the exact pinned SPSS engine identity for audit records."""
+    return {
+        "package": "pyspssio",
+        "distribution": "TonisOrmisson/pyspssio",
+        "pinned_commit": "0b3f879",
+        "installed_version": str(pyspssio.__version__),
+    }
 
 
 def _dictionary(source_path: Path) -> tuple[dict[str, Any], dict[str, Any]]:
@@ -175,6 +183,7 @@ def inspect_sav(source: str | Path) -> dict[str, Any]:
     loss_report = _merge_loss_reports(tuple(loss_report.values()), _compat_name_loss_report(variables))
     return {
         "source_format": source_path.suffix[1:].upper(),
+        "engine": engine_identity(),
         "source_name": source_path.name,
         "source_sha256": _sha256(source_path),
         "source_encoding": metadata.get("encoding"),
@@ -224,6 +233,7 @@ def import_sav_dataset(*, source: str | Path, database_url: str, dataset_id: str
             if metadata.get("_var_sets") else {}
         ),
         fidelity_events=loss_report,
+        operation_details={"engine": engine_identity()},
     )
     return {**result, "loss_report": loss_report}
 
@@ -273,6 +283,7 @@ def export_sav_dataset(
         allowed_fidelity_events=tuple(
             event for event in loss_report if event["code"] in allow_loss
         ),
+        operation_details={"engine": engine_identity()},
     )
     return {
         "dataset_id": dataset_id,

src/openstatspec/sql/wide.py

@@ -737,6 +737,7 @@ def create_wide_dataset(
     multiple_response_sets: str = "{}",
     source_extensions: Mapping[str, Any] | None = None,
     fidelity_events: Iterable[Mapping[str, Any]] = (),
+    operation_details: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
     profile = validate_connection_url(database_url)
     engine = create_engine(database_url)
@@ -773,7 +774,7 @@ def create_wide_dataset(
         _migrate_catalog_columns(connection, datasets, variable_catalog, multiple_response_catalog)
         connection.execute(insert(operation_catalog).values(
             operation_id=operation_id, direction="import", status="running", dataset_id=dataset_id,
-            source=source_name, created_at=_now(), details=json.dumps({"variable_count": len(variables)}, sort_keys=True),
+            source=source_name, created_at=_now(), details=json.dumps({"variable_count": len(variables), **dict(operation_details or {})}, sort_keys=True),
         ))
         if connection.execute(select(datasets.c.dataset_id).where(datasets.c.dataset_id == dataset_id)).first():
             raise ValueError(f"Dataset {dataset_id!r} already exists; imports never overwrite a dataset.")
@@ -958,6 +959,7 @@ def read_fidelity_events(*, database_url: str, dataset_id: str) -> tuple[dict[st
 def record_export_operation(
     *, database_url: str, dataset_id: str, destination: str,
     allowed_fidelity_events: Iterable[Mapping[str, Any]],
+    operation_details: Mapping[str, Any] | None = None,
 ) -> str:
     """Persist a completed export and the fidelity loss explicitly accepted by its caller."""
     engine = create_engine(database_url)
@@ -971,7 +973,7 @@ def record_export_operation(
         connection.execute(insert(operations).values(
             operation_id=operation_id, direction="export", status="succeeded", dataset_id=dataset_id,
             destination=destination, created_at=_now(), completed_at=_now(),
-            details=json.dumps({"allow_loss": [event["code"] for event in events]}, sort_keys=True),
+            details=json.dumps({"allow_loss": [event["code"] for event in events], **dict(operation_details or {})}, sort_keys=True),
         ))
         rows = _event_rows(
             operation_id=operation_id, dataset_id=dataset_id, direction="export",

tests/test_cli.py

@@ -17,6 +17,7 @@ def test_cli_import_inspect_validate_and_export_emit_json(tmp_path, capsys) -> N
     assert openstatspec.cli.main(["inspect", str(source)]) == 0
     inspected = json.loads(capsys.readouterr().out)
     assert inspected["source_format"] == "SAV"
+    assert inspected["engine"]["pinned_commit"] == "0b3f879"
     assert inspected["source_sha256"]
     assert {event["code"] for event in inspected["loss_report"]} == {
         "documents-unobservable",
@@ -39,6 +40,7 @@ def test_cli_import_inspect_validate_and_export_emit_json(tmp_path, capsys) -> N
 
 def test_capability_matrix_is_public_and_cli_matches_engine_boundary(capsys) -> None:
     matrix = openstatspec.capability_matrix()
+    assert matrix["engine"]["pinned_commit"] == "0b3f879"
 
     assert matrix["spss"] == {
         "values": "supported",

tests/test_loss_reports.py

@@ -25,13 +25,17 @@ def test_persisted_import_fidelity_events_require_consent_after_reopen(tmp_path)
     assert {diagnostic.code for diagnostic in imported.diagnostics} == set(_REQUIRED_ENGINE_LOSS)
     connection = sqlite3.connect(database_path)
     assert {row[0] for row in connection.execute("select code from fidelity_event_catalog")} == set(_REQUIRED_ENGINE_LOSS)
+    import_details = json.loads(connection.execute("select details from operation_catalog order by created_at limit 1").fetchone()[0])
+    assert import_details["engine"]["pinned_commit"] == "0b3f879"
 
     with pytest.raises(UnsupportedOperationError, match="documents-unobservable"):
         openstatspec.export_sav(database_url=database, dataset_id="persisted", destination=blocked)
     assert not blocked.exists()
 
     exported = openstatspec.export_sav(database_url=database, dataset_id="persisted", destination=approved, allow_loss=_REQUIRED_ENGINE_LOSS)
     assert approved.exists()
+    export_details = json.loads(connection.execute("select details from operation_catalog where operation_id = ?", (exported["operation_id"],)).fetchone()[0])
+    assert export_details["engine"]["installed_version"] == pyspssio.__version__
     assert {diagnostic.code for diagnostic in exported.diagnostics} == set(_REQUIRED_ENGINE_LOSS)