Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions docs/conformance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
13 changes: 3 additions & 10 deletions src/tracebook/conformance/campaign.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
ConformanceError,
EngineMetadata,
canonical_decimal,
canonical_event_jsonl_line,
trace_sha256,
)
from .protocol import AdapterFactory
Expand Down Expand Up @@ -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"
Expand Down
19 changes: 8 additions & 11 deletions src/tracebook/conformance/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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:
Expand Down
28 changes: 17 additions & 11 deletions src/tracebook/conformance/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()


Expand Down
19 changes: 19 additions & 0 deletions tests/test_conformance.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
import hashlib
import io
import json
import sys
from pathlib import Path
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
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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)

Expand Down