Skip to content
Draft
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
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,13 @@ jobs:
--conformance-sdist dist/conformance/*.tar.gz \
--sim-wheel dist/simulator/*.whl \
--sim-sdist dist/simulator/*.tar.gz \
--expected-version 0.6.0
--expected-version 0.7.0

- name: Verify distribution ownership and clean-install contracts
if: matrix.python-version == '3.13'
run: |
python tools/verify_distribution_split.py \
--expected-version 0.6.0 \
--expected-version 0.7.0 \
--conformance-wheel dist/conformance/*.whl \
--sim-wheel dist/simulator/*.whl \
--resolver-runtime-checks
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/gocronx-matcher.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ jobs:
(Path(os.environ["REPORT_ROOT"]) / "qualification" / "qualification.json").read_text()
)
assert report["qualified"] is True
assert report["qualification_id"] == "sha256:1636620f5f0f6b65fd425a6021424e9c7678bec5215555556c70a929c5e0b144"
assert report["qualification_id"] == "sha256:64746a4a21bc3fef7c88e58d749da2adb51cb74fac211088174aba26dc6746ed"
assert report["candidate_runs"] == 28
assert report["campaign"]["generated_events"] == 5000
assert report["campaign"]["semantic_coverage"]["coverage_ratio"] == 1.0
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/intrepid-orderbook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ jobs:
(Path(os.environ["REPORT_ROOT"]) / "fifo-limit" / "qualification.json").read_text()
)
assert report["qualified"] is True
assert report["qualification_id"] == "sha256:f8db775baabe7e665d45bbb920a67e43d405acf445de4951617df68ffa24eb69"
assert report["qualification_id"] == "sha256:5bb06673e36f6ecf7a328285275d7d72b6f1e22e40f139d628411d8fb8bb222b"
assert report["campaign"]["campaign_id"] == "sha256:59d70645ff13f12fa4af23af69631714df22ef5f25cd1104b0c1124f98f71f6a"
assert report["candidate_runs"] == 28
assert report["suite"]["report"]["conformant_cases"] == 3
Expand Down Expand Up @@ -141,7 +141,7 @@ jobs:
(Path(os.environ["REPORT_ROOT"]) / "fifo-partial" / "qualification.json").read_text()
)
assert report["qualified"] is True
assert report["qualification_id"] == "sha256:08bf641bfa57da1892d744c08bca0be00f5ac1ade580ae8fcf7f195f0fcad6eb"
assert report["qualification_id"] == "sha256:baee6faa893cd5576f5fe42985250f1ce210d47c402c2c80de563088ff41dc85"
assert report["campaign"]["campaign_id"] == "sha256:297f895b99ac26f92287ababd1dcc25b68b0be98787e9b9d814d5cd241769cf9"
assert report["candidate_runs"] == 28
assert report["suite"]["report"]["conformant_cases"] == 3
Expand Down Expand Up @@ -184,7 +184,7 @@ jobs:
(Path(os.environ["REPORT_ROOT"]) / "fifo-full" / "failure.json").read_text()
)
assert report["qualified"] is False
assert report["qualification_id"] == "sha256:81a095f9804852ff7035f4c3d428a51ae3d0e8e4b81ec335128c6af15b6f65bd"
assert report["qualification_id"] == "sha256:ed59a8437c413f3376546ac6bc61452eb08ac75d008667fd619b185e4785f5a2"
assert report["campaign"]["campaign_id"] == "sha256:61464afc70170352bc6eecb6ccb22f120d05166d6f5cb7926ce5d43adf8a6b41"
assert failure["failure_id"] == "failure-1ce2954857800b3a068d"
assert failure["original_event_count"] == 7
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/orderbook-rs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ jobs:
(Path(os.environ["REPORT_ROOT"]) / "qualification" / "qualification.json").read_text()
)
assert report["qualified"] is True
assert report["qualification_id"] == "sha256:c04a07cbdb9931232162ef1a05740221311f3b2fa21b9b552093a2706a12c488"
assert report["qualification_id"] == "sha256:10c162a1a6db2a7715e98af54871cc7a94675f2e7c4fe3754e18c48157c0371c"
assert report["candidate_runs"] == 28
assert report["campaign"]["generated_events"] == 5000
assert report["campaign"]["semantic_coverage"]["coverage_ratio"] == 1.0
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ jobs:
--conformance-sdist dist/conformance/*.tar.gz \
--sim-wheel dist/simulator/*.whl \
--sim-sdist dist/simulator/*.tar.gz \
--expected-version 0.6.0
--expected-version 0.7.0

- name: Verify distribution ownership and clean-install contracts
run: |
Expand All @@ -135,7 +135,7 @@ jobs:
--dest dist/legacy \
"tracebook-sim==0.5.0"
python tools/verify_distribution_split.py \
--expected-version 0.6.0 \
--expected-version 0.7.0 \
--conformance-wheel dist/conformance/*.whl \
--sim-wheel dist/simulator/*.whl \
--legacy-wheel dist/legacy/tracebook_sim-0.5.0-py3-none-any.whl \
Expand Down
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ The project follows [Keep a Changelog](https://keepachangelog.com/) conventions.

## Unreleased

Prepared version: **0.7.0**. See the [draft release notes](docs/releases/0.7.0.md).
This version has not been published; 0.6.0 remains the public install target.

- Made initial staging-identity failures explicit: report the possible residue
path and skipped cleanup, preserve unverified entries, and exit before starting
a candidate. Documented conservative manual recovery without blanket deletion.
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ python -m build --sdist --wheel --outdir dist/simulator packaging/tracebook-sim
python tools/verify_distribution_privacy.py dist/conformance/* dist/simulator/*
python -m twine check dist/conformance/* dist/simulator/*
python tools/verify_distribution_split.py \
--expected-version 0.6.0 \
--expected-version 0.7.0 \
--conformance-wheel dist/conformance/*.whl \
--sim-wheel dist/simulator/*.whl \
--resolver-runtime-checks
Expand All @@ -49,7 +49,7 @@ python tools/verify_sdist_wheel_agreement.py \
--conformance-sdist dist/conformance/*.tar.gz \
--sim-wheel dist/simulator/*.whl \
--sim-sdist dist/simulator/*.tar.gz \
--expected-version 0.6.0
--expected-version 0.7.0
python tools/smoke_conformance_wheel.py dist/conformance/*.whl
```

Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -97,12 +97,12 @@ build:
--conformance-sdist dist/conformance/*.tar.gz \
--sim-wheel dist/simulator/*.whl \
--sim-sdist dist/simulator/*.tar.gz \
--expected-version 0.6.0
--expected-version 0.7.0

# Prove wheel ownership, clean installs, migration, and uninstall safety
verify-distribution-split: build
$(PYTHON_VENV) tools/verify_distribution_split.py \
--expected-version 0.6.0 \
--expected-version 0.7.0 \
--conformance-wheel dist/conformance/*.whl \
--sim-wheel dist/simulator/*.whl

Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ failure to a deterministic JSONL reproducer.

## Quick Start

The source tree is preparing **0.7.0**; see the [draft release notes](docs/releases/0.7.0.md).
It is not published yet. The install commands below intentionally use public 0.6.0.

Tracebook requires Python 3.10-3.13. Install the dependency-light conformance
distribution and materialize the current hash-verified adversarial suite:

Expand Down
30 changes: 18 additions & 12 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

`tracebook` is still alpha software. Use this checklist before cutting any public release or tagged benchmark claim.

The prepared source version is **0.7.0**, not yet published. The
[draft 0.7.0 notes](releases/0.7.0.md) list the release scope and remaining
publication gates. Public installation examples, citation metadata, and
support policy still describe the latest public release, 0.6.0.

## Version And Changelog

1. Update `src/tracebook/_version.py`.
Expand Down Expand Up @@ -41,7 +46,7 @@ python -m pip download \
--dest dist/legacy \
"tracebook-sim==0.5.0"
python tools/verify_distribution_split.py \
--expected-version 0.6.0 \
--expected-version 0.7.0 \
--conformance-wheel dist/conformance/*.whl \
--sim-wheel dist/simulator/*.whl \
--legacy-wheel dist/legacy/tracebook_sim-0.5.0-py3-none-any.whl \
Expand All @@ -52,7 +57,7 @@ python tools/verify_sdist_wheel_agreement.py \
--conformance-sdist dist/conformance/*.tar.gz \
--sim-wheel dist/simulator/*.whl \
--sim-sdist dist/simulator/*.tar.gz \
--expected-version 0.6.0
--expected-version 0.7.0
python tools/smoke_conformance_wheel.py dist/conformance/*.whl
python -m pip check
(
Expand Down Expand Up @@ -94,10 +99,10 @@ Configure a PyPI Trusted Publisher for both distribution names:
- workflow: `release.yml`
- environment: `pypi`

`tracebook-conformance` is a new project name in 0.6.0, so create its pending
Trusted Publisher on PyPI before publishing the first release. Do not publish
the facade until that exact conformance version can be downloaded from the
public index.
`tracebook-conformance` was introduced in 0.6.0. Confirm both existing Trusted
Publishers still match the workflow and environment before the next release.
Do not publish the facade until that exact conformance version can be
downloaded from the public index.

Repository settings enforce pull requests and the Ubuntu/Python 3.10-3.13 CI
matrix on `main`. The `pypi` deployment environment accepts only `v*` tags;
Expand All @@ -112,11 +117,11 @@ and only then publishes `tracebook-sim`.
After publishing, verify the lightweight path from a clean environment:

```bash
python -m pip install --no-cache-dir "tracebook-conformance==0.6.0"
python -m pip install --no-cache-dir "tracebook-conformance==0.7.0"
python -c "import tracebook; print(tracebook.__version__)"
tracebook-conformance --help
python -m pip check
python -m pip download --no-deps --no-binary=:all: "tracebook-conformance==0.6.0"
python -m pip download --no-deps --no-binary=:all: "tracebook-conformance==0.7.0"
```

Extract the downloaded sdist in a blank repository, build
Expand All @@ -129,8 +134,8 @@ binary on the reduced regression case.
Verify the full facade independently in a second clean environment:

```bash
python -m pip install --no-cache-dir "tracebook-sim==0.6.0"
python -c "import importlib.metadata as m; assert m.version('tracebook-conformance') == m.version('tracebook-sim') == '0.6.0'"
python -m pip install --no-cache-dir "tracebook-sim==0.7.0"
python -c "import importlib.metadata as m; assert m.version('tracebook-conformance') == m.version('tracebook-sim') == '0.7.0'"
tracebook-sim --version
tracebook-benchmark --version
tracebook-dashboard --version
Expand All @@ -148,7 +153,7 @@ that move to `tracebook-conformance`:
```bash
python -m pip install "tracebook-sim==0.5.0"
python -m pip uninstall -y tracebook-sim
python -m pip install "tracebook-sim==0.6.0"
python -m pip install "tracebook-sim==0.7.0"
python -m pip check
```

Expand All @@ -163,7 +168,8 @@ Release notes should include:
- compatibility notes
- known limitations

For 0.6.0, begin with [`docs/releases/0.6.0.md`](releases/0.6.0.md). The
For the next release, begin with the [draft 0.7.0 notes](releases/0.7.0.md).
The [0.6.0 notes](releases/0.6.0.md) document the distribution split. The
[0.5.0 notes](releases/0.5.0.md) document qualification as a public contract,
the [0.4.1 notes](releases/0.4.1.md) document the first upstream semantic
review, and the [0.4.0 notes](releases/0.4.0.md) document the failure-corpus
Expand Down
116 changes: 116 additions & 0 deletions docs/releases/0.7.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# Tracebook 0.7.0: Captured Evidence And Separate Book-Replay Contracts

**Draft — not published.** Both distribution versions are prepared as 0.7.0.
No release date, public tag, PyPI upload, or independent adoption outcome is
claimed by this document. Public 0.6.0 remains the install target until release.

## Release Scope

- Captured two-run qualification: candidate identity checks, clean evidence
roots, and `evidence-init` / `evidence-verify` for complete, unchanged,
byte-identical qualification bundles.
- A separate `l3-book-replay-v1` contract for market-data add/update/delete
events and non-mutating FIFO fill probes. It includes a pinned optional
NautilusTrader adapter, deterministic generated campaigns, reduction, and a
retained injected queue-priority negative control. This is not a submitted-
order matching-engine contract or a claim about Nautilus's fill simulator.
- A pinned native Go adapter for `intrepidkarthi/orderbook`, with FIFO-limit
and partial-fill qualifications. The retained unfillable-FOK example is a
contract difference, not an upstream defect claim.
- Checked native Rust quantity encoding: output display precision no longer
rounds order, reduction, or replacement input before matching. Inputs must
fit the adapters' exact 12-place integer domain; this is not a claim of
unrestricted precision equivalence with a binary-floating-point engine.
- Stricter stdio shutdown and no-clobber L3 report/reduced-trace publication.
Existing output paths now fail before candidate execution. New complete
artifacts publish individually, with reduced traces before reports; abrupt
interruption is not a cross-file atomic transaction.
If the first staging-directory identity read fails, the CLI reports possible
residue and exits before starting a candidate. Unverified entries are kept;
[manual recovery](../book-replay-conformance.md) requires independently
confirmed ownership, not blanket deletion of staging paths.
- Distribution privacy gates, clean-install/migration checks, and native CI
trigger coverage for the reference/runtime code those integrations execute.

The corrected 24-run research aggregate is included in the source record:
1/12 safe passes with public documentation versus 5/12 with the frozen skill.
That improvement was confined to boundary judgment; neither arm safely
qualified the compatible engine. Frozen protocols, historical evidence,
private gold, and evaluator artifacts are not revised for this release.
The 13 frozen-harness review findings remain explicitly deferred in
[issue #85](https://github.com/Taz33m/tracebook/issues/85). Merging the
release-code fixes does not fix or dismiss those research findings.

## Install After Publication

These commands are future post-publication instructions, not available package
downloads today. If an environment contains the monolithic `tracebook-sim`
0.5.x, first uninstall that legacy owner:

```bash
python -m pip uninstall -y tracebook-sim
```

For the dependency-light conformance commands:

```bash
python -m pip install "tracebook-conformance==0.7.0"
```

For simulation, replay, benchmarks, and the other workbench commands:

```bash
python -m pip install "tracebook-sim==0.7.0"
```

The facade remains package-less and pins the exact conformance version. Its
seven console scripts and the conformance command keep their distribution
ownership. Python 3.10–3.13 is the supported package matrix; the optional
Nautilus 2.0.0rc3 integration is separately exercised on Python 3.14 and is not
a mandatory package dependency. Native adapters remain out of process.

The L3 entry point is `python -m tracebook.book_replay`; no new console script
is claimed. See [book-replay conformance](../book-replay-conformance.md) and
[captured onboarding](../independent-onboarding.md) for the exact workflows.

## Evidence Compatibility

Existing profile names, generator versions, suite hashes, trace bytes, and
retained failure controls keep their meaning. A qualification ID covers the
full report, including reference-engine version metadata, so a fresh 0.7.0
qualification can have a different ID from an otherwise equivalent 0.6.0 run.
Do not relabel old artifacts or rewrite frozen experiment evidence. The sent
maintainer invitation remains pinned to its tested pre-release source revision
and wheel hash; a release-based attempt is new evidence.

## Release Decision And Remaining Publication Gates

The reviewed consolidation landed in
[PR #84](https://github.com/Taz33m/tracebook/pull/84) on 2026-09-05, at merge
commit `9059f171dfc751eff4c8f048af7d0878d2b5aca0`. All nine Actions jobs and
the Cubic check passed on its exact head, with no unresolved conversations at
merge. The version-preparation branch has been reconciled with that source.
This does not substitute for checks on the new version-preparation revision.

The [project's external-use release gate](../../PROJECT_PLAN.md#next-release-gate)
still applies. Repository-owned evidence and an unanswered invitation cannot
establish independent adoption or time to first qualification. Publication
requires that evidence or an explicit maintainer decision to change the gate;
technical preparation does not silently waive it.

1. Review and land the version-preparation changes through the protected branch
workflow, with checks on the exact proposed revision.
2. Run the release candidate's remote checks and coordinated package gates;
retain both wheel hashes and source-archive agreement results.
3. Review dependency/security alerts. On 2026-09-05, GitHub's alert API returned
HTTP 403 and reported that Dependabot alerts are disabled for this repository.
This is not evidence of zero alerts; security-alert review remains unverified.
4. In the final release commit, set the actual release date and 0.7.0 citation
URL in `CITATION.cff`, mark the new minor line in `SECURITY.md`, update public
install examples, and move these notes and the changelog out of draft.
5. Confirm both PyPI Trusted Publishers and the tag-only environment, then
publish through the coordinated workflow: conformance first, facade only
after the exact dependency wheel is downloadable and hash-verified.

Preparation does not authorize a tag or package upload. Repository-owned
campaigns and the sent maintainer invitation are not independent adoption.
4 changes: 2 additions & 2 deletions packaging/tracebook-sim/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "tracebook-sim"
version = "0.6.0"
version = "0.7.0"
description = "Compatibility facade for Tracebook simulation, replay, profiling, and visualization tools"
readme = { file = "README.md", content-type = "text/markdown" }
requires-python = ">=3.10"
Expand Down Expand Up @@ -35,7 +35,7 @@ classifiers = [
"Topic :: Scientific/Engineering",
]
dependencies = [
"tracebook-conformance==0.6.0",
"tracebook-conformance==0.7.0",
"numpy>=2.2.6",
"psutil>=7.2.2",
]
Expand Down
2 changes: 1 addition & 1 deletion src/tracebook/_version.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""Package version metadata."""

__version__ = "0.6.0"
__version__ = "0.7.0"
10 changes: 9 additions & 1 deletion tests/test_coinbase_corpus.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

import pytest

from tracebook import __version__
from tracebook.corpus import coinbase as corpus_module
from tracebook.corpus import (
CoinbaseCorpusError,
CoinbaseSanitizer,
Expand Down Expand Up @@ -124,6 +126,7 @@ def test_compact_sanitizer_rewrites_schema_when_removing_fields():
def test_prepare_verify_and_tamper_detection(tmp_path):
corpus, manifest = _prepare(tmp_path)

assert manifest["tool"] == {"name": "tracebook", "version": __version__}
assert set(path.name for path in corpus.iterdir()) == {
"snapshot.json",
"feed.jsonl",
Expand Down Expand Up @@ -164,7 +167,12 @@ def test_checked_synthetic_corpus_reproduces_exactly():
}


def test_checked_synthetic_corpus_regenerates_byte_for_byte(tmp_path):
def test_checked_synthetic_corpus_regenerates_byte_for_byte(tmp_path, monkeypatch):
# The corpus identity includes producer-version provenance. Pin only that
# historical metadata when testing byte reproduction; normal preparation
# above must still record the current version. Keep the frozen fixture intact.
historical = json.loads((CORPUS / "manifest.json").read_text(encoding="utf-8"))
monkeypatch.setattr(corpus_module, "__version__", historical["tool"]["version"])
regenerated = tmp_path / "regenerated"
prepare_coinbase_corpus(
SNAPSHOT,
Expand Down
Loading