diff --git a/CHANGELOG.md b/CHANGELOG.md index d1175d7..f58e26b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,9 @@ The project follows [Keep a Changelog](https://keepachangelog.com/) conventions. category while preventing a specific classified failure from broadening. A generic execution drift may still narrow to the queue-priority defect exposed by removing causal noise. +- Unified conformance event hashing and JSONL artifact writing behind one + canonical UTF-8 encoder. Valid non-ASCII symbols now produce artifact bytes + that match their reported trace SHA-256. ## 0.6.0 - 2026-07-27 diff --git a/docs/conformance.md b/docs/conformance.md index 5b830dd..6e42336 100644 --- a/docs/conformance.md +++ b/docs/conformance.md @@ -566,6 +566,12 @@ adapter shutdown also fails after that divergence, optional `close_error` evidence is attached without replacing the first drift; the command still exits `2`. +Trace SHA-256 values cover the exact canonical JSONL bytes emitted for normalized +events: UTF-8, sorted object keys, compact separators, one trailing newline per +event, and no non-finite numbers. Non-ASCII symbols remain UTF-8 rather than JSON +escape sequences, so a written trace and its reported hash share one byte +contract. + Minimization reports use `artifact_type = "tracebook.conformance.minimization"` and include original and minimized counts, run count, reduction percentage, minimality/budget status, diff --git a/src/tracebook/conformance/campaign.py b/src/tracebook/conformance/campaign.py index bd9c3a5..d50338f 100644 --- a/src/tracebook/conformance/campaign.py +++ b/src/tracebook/conformance/campaign.py @@ -26,6 +26,7 @@ ConformanceError, EngineMetadata, canonical_decimal, + canonical_event_jsonl_line, trace_sha256, ) from .protocol import AdapterFactory @@ -845,17 +846,9 @@ def _write_json(path: Path, payload: dict) -> None: def _write_events(path: Path, events: Sequence[MarketEvent]) -> None: - with path.open("w", encoding="utf-8") as handle: + with path.open("wb") as handle: for event in events: - handle.write( - json.dumps( - event.to_dict(), - sort_keys=True, - separators=(",", ":"), - allow_nan=False, - ) - + "\n" - ) + handle.write(canonical_event_jsonl_line(event)) _RESERVATION_MARKER = ".tracebook-campaign-reservation" diff --git a/src/tracebook/conformance/cli.py b/src/tracebook/conformance/cli.py index 0a0a085..ebd6ac9 100644 --- a/src/tracebook/conformance/cli.py +++ b/src/tracebook/conformance/cli.py @@ -25,7 +25,12 @@ from .exit_codes import exit_code_for_artifact from .junit import write_junit from .minimize import minimize_failing_trace -from .model import ConformanceConfig, ConformanceError, PinnedCandidateIdentity +from .model import ( + ConformanceConfig, + ConformanceError, + PinnedCandidateIdentity, + canonical_event_jsonl_line, +) from .qualification import _QualificationOutputReservation, run_qualification from .reproduce import ( discover_failure_metadata, @@ -261,17 +266,9 @@ def _emit_junit(report: dict, output: Optional[str]) -> None: def _write_events(events, output: str) -> None: path = Path(output) path.parent.mkdir(parents=True, exist_ok=True) - with path.open("w", encoding="utf-8") as handle: + with path.open("wb") as handle: for event in events: - handle.write( - json.dumps( - event.to_dict(), - sort_keys=True, - separators=(",", ":"), - allow_nan=False, - ) - + "\n" - ) + handle.write(canonical_event_jsonl_line(event)) def _require_distinct_paths(*paths: Optional[str]) -> None: diff --git a/src/tracebook/conformance/model.py b/src/tracebook/conformance/model.py index b7f6027..9890bc8 100644 --- a/src/tracebook/conformance/model.py +++ b/src/tracebook/conformance/model.py @@ -513,23 +513,29 @@ def from_dict(cls, data: Mapping[str, Any]) -> "Observation": ) -def trace_sha256(events: Sequence[Any]) -> str: - """Hash normalized events using the canonical JSONL representation.""" - digest = hashlib.sha256() - for event in events: - try: - payload = event.to_dict() - except AttributeError as exc: - raise ConformanceError("trace entries must provide to_dict()") from exc - encoded = json.dumps( +def canonical_event_jsonl_line(event: Any) -> bytes: + """Encode one normalized event as its canonical UTF-8 JSONL line.""" + try: + payload = event.to_dict() + except AttributeError as exc: + raise ConformanceError("trace entries must provide to_dict()") from exc + return ( + json.dumps( payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False, ) - digest.update(encoded.encode("utf-8")) - digest.update(b"\n") + + "\n" + ).encode("utf-8") + + +def trace_sha256(events: Sequence[Any]) -> str: + """Hash normalized events using the canonical JSONL representation.""" + digest = hashlib.sha256() + for event in events: + digest.update(canonical_event_jsonl_line(event)) return "sha256:" + digest.hexdigest() diff --git a/tests/test_conformance.py b/tests/test_conformance.py index 77cefe8..ce8fa42 100644 --- a/tests/test_conformance.py +++ b/tests/test_conformance.py @@ -1,3 +1,4 @@ +import hashlib import io import json import sys @@ -5,6 +6,7 @@ from xml.etree import ElementTree import pytest +import tracebook.conformance.campaign as campaign_module from hypothesis import given, settings, strategies as st from tracebook import OrderBook, OrderSide @@ -32,12 +34,14 @@ run_conformance_suite, serve_stdio, ) +from tracebook.conformance.cli import _write_events as write_cli_events from tracebook.conformance.cli import main from tracebook.conformance.classification import ( FailureSignature, preserves_failure_signature, ) from tracebook.conformance.exit_codes import exit_code_for_artifact +from tracebook.conformance.model import trace_sha256 from tracebook.events import MarketEvent, load_market_events ROOT = Path(__file__).parents[1] @@ -318,6 +322,21 @@ def test_delta_debugging_reduces_to_a_one_event_reproducer(): assert budget_limited.report.trace_hash == budget_limited.to_dict()["minimized_trace_sha256"] +def test_event_artifacts_use_the_hashed_canonical_jsonl_bytes(tmp_path): + events = (_event(symbol="Σ"),) + cli_output = tmp_path / "cli.jsonl" + campaign_output = tmp_path / "campaign.jsonl" + + write_cli_events(events, str(cli_output)) + campaign_module._write_events(campaign_output, events) + + encoded = cli_output.read_bytes() + assert campaign_output.read_bytes() == encoded + assert "Σ".encode("utf-8") in encoded + assert b"\\u03a3" not in encoded + assert trace_sha256(events) == "sha256:" + hashlib.sha256(encoded).hexdigest() + + def test_minimizer_preserves_queue_priority_failure_class(): events = generate_campaign_trace("fifo-limit-v1", seed=0, event_count=5)