Add append-only research experiment ledger and integrate with temporal baseline CLI

[InsightofSPb]

Motivation

• Provide a small, durable, append-only experiment ledger to record provenance for manually launched CLI experiments without adding a runtime agent or registry.[1]
• Integrate the ledger with the existing CPU entrypoint tools/run_temporal_change_baselines.py so real CLI runs can record snapshots, stages, and output artifacts while preserving existing behaviour when the ledger is omitted.
• Ship a focused, deterministic surface (serialization/hashing, append/read/verify/reconstruct, and stage semantics) plus tests and lightweight CI to validate integrity and basic integration.

Description

• Add a new package research_ledger implementing canonical UTF-8 JSON serialization with sorted keys and finite-number rejection, immutable typed dataclasses (RunSnapshot, NewEvent, StoredEvent, ArtifactDescriptor, RunProjection), canonical SHA-256 hashing, recursive secret redaction, and a _freeze helper for stable in-memory objects (research_ledger/ledger.py).
• Implement per-run events.jsonl streams with contiguous sequence numbers, prev_event_hash and event_hash, an inter-process flock during append, flush+fsync before acknowledgement, torn final-line detection, append-only verification, deterministic in-memory reconstruct(), and a stage() context manager that records stage.started/stage.failed/stage.completed and re-raises original exceptions.
• Integrate optional ledger recording into tools/run_temporal_change_baselines.py via a --ledger-dir argument that is opt-in and preserves previous behaviour when omitted, record run.started, source/config/dataset/split/ontology snapshots, validate facade split leakage, wrap the baseline execution in a recorded stage, record the produced score CSV as an artifact.created with hash/size/path, and append run.completed or run.failed appropriately.
• Add focused tests tests/test_research_ledger.py (serialization, append/read round-trip, verification of mutation/deletion/insertion/reordering, concurrent writers, torn-line detection, stage failure recording, facade overlap rejection, metadata adapter) and tests/test_temporal_baseline_ledger_cli.py (synthetic PPM-based end-to-end CLI run that compares outputs with and without ledger recording and verifies artifact hash), add documentation docs/research_ledger.md, and add a lightweight GitHub Actions workflow .github/workflows/research-ledger.yml for CPU validation.

Testing

• Ran PYTHONPATH=/usr/lib/python3/dist-packages:$PYTHONPATH python -m pytest -q tests/test_research_ledger.py, which passed (11 passed).
• Ran formatting and static checks with python -m ruff format --check research_ledger tools/run_temporal_change_baselines.py tests/test_research_ledger.py tests/test_temporal_baseline_ledger_cli.py and python -m ruff check research_ledger tools/run_temporal_change_baselines.py tests/test_research_ledger.py tests/test_temporal_baseline_ledger_cli.py, both of which passed after minor fixes.
• Ran python -m compileall -q . and git diff --check to ensure byte-compile and whitespace checks passed.
• Note: attempts to run some tests and install optional runtime deps via pip were constrained by the execution environment (network/proxy restrictions and missing wheel installs); where necessary tests were adapted to use synthetic PPM fixtures or PYTHONPATH to system-provided packages so the core ledger tests and CLI integration tests could be exercised in CI-like CPU settings.

---

Codex Task