From 06abea90d4244c48a047b5c4a7dc4cd786615851 Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Fri, 4 Sep 2026 22:03:07 -0400 Subject: [PATCH 1/6] Prepare coordinated 0.7.0 release without publishing --- .github/workflows/ci.yml | 4 +- .github/workflows/gocronx-matcher.yml | 2 +- .github/workflows/intrepid-orderbook.yml | 6 +- .github/workflows/orderbook-rs.yml | 2 +- .github/workflows/release.yml | 4 +- CHANGELOG.md | 3 + CONTRIBUTING.md | 4 +- Makefile | 4 +- README.md | 3 + docs/release.md | 30 ++++--- docs/releases/0.7.0.md | 95 +++++++++++++++++++++++ packaging/tracebook-sim/pyproject.toml | 4 +- src/tracebook/_version.py | 2 +- tests/test_coinbase_corpus.py | 10 ++- tests/test_distribution_split_verifier.py | 2 +- tests/test_external_integrations.py | 10 +-- tests/test_release_metadata.py | 25 +++++- tools/verify_distribution_split.py | 2 +- 18 files changed, 173 insertions(+), 39 deletions(-) create mode 100644 docs/releases/0.7.0.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9014c42..aa8b5a5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/.github/workflows/gocronx-matcher.yml b/.github/workflows/gocronx-matcher.yml index c3b6d96..e0dabdf 100644 --- a/.github/workflows/gocronx-matcher.yml +++ b/.github/workflows/gocronx-matcher.yml @@ -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 diff --git a/.github/workflows/intrepid-orderbook.yml b/.github/workflows/intrepid-orderbook.yml index 4baaa3e..7390ed5 100644 --- a/.github/workflows/intrepid-orderbook.yml +++ b/.github/workflows/intrepid-orderbook.yml @@ -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 @@ -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 @@ -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 diff --git a/.github/workflows/orderbook-rs.yml b/.github/workflows/orderbook-rs.yml index 362f20c..67cbd04 100644 --- a/.github/workflows/orderbook-rs.yml +++ b/.github/workflows/orderbook-rs.yml @@ -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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ca579af..939e2ba 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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: | @@ -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 \ diff --git a/CHANGELOG.md b/CHANGELOG.md index 92d1ef5..8a79caf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. + - Kept Rust adapter input quantities independent of report display precision. Both native adapters now share exact checked 12-place integer encoding and reject quantities outside that domain rather than pre-rounding orders. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97eead7..b617b8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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 ``` diff --git a/Makefile b/Makefile index baf144f..ebe66b6 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/README.md b/README.md index 23a850b..bf7fb76 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/release.md b/docs/release.md index 35d7bfb..a31a689 100644 --- a/docs/release.md +++ b/docs/release.md @@ -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`. @@ -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 \ @@ -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 ( @@ -92,10 +97,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; @@ -110,11 +115,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 @@ -127,8 +132,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 @@ -146,7 +151,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 ``` @@ -161,7 +166,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 diff --git a/docs/releases/0.7.0.md b/docs/releases/0.7.0.md new file mode 100644 index 0000000..dad7220 --- /dev/null +++ b/docs/releases/0.7.0.md @@ -0,0 +1,95 @@ +# 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. +- 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. + +## 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. + +## Publication Gates Still To Complete + +1. Land the reviewed consolidation PR with required Python and native CI green, + then review the version-preparation changes against that exact source. +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. The alert API was unavailable during + preparation, so this item is not recorded as passed. +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. diff --git a/packaging/tracebook-sim/pyproject.toml b/packaging/tracebook-sim/pyproject.toml index 84ffd24..30d8909 100644 --- a/packaging/tracebook-sim/pyproject.toml +++ b/packaging/tracebook-sim/pyproject.toml @@ -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" @@ -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", ] diff --git a/src/tracebook/_version.py b/src/tracebook/_version.py index 11b0728..fc6e695 100644 --- a/src/tracebook/_version.py +++ b/src/tracebook/_version.py @@ -1,3 +1,3 @@ """Package version metadata.""" -__version__ = "0.6.0" +__version__ = "0.7.0" diff --git a/tests/test_coinbase_corpus.py b/tests/test_coinbase_corpus.py index 720c01b..fa35541 100644 --- a/tests/test_coinbase_corpus.py +++ b/tests/test_coinbase_corpus.py @@ -6,6 +6,8 @@ import pytest +from tracebook import __version__ +from tracebook.corpus import coinbase as corpus_module from tracebook.corpus import ( CoinbaseCorpusError, CoinbaseSanitizer, @@ -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", @@ -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, diff --git a/tests/test_distribution_split_verifier.py b/tests/test_distribution_split_verifier.py index d9ee340..e6138f0 100644 --- a/tests/test_distribution_split_verifier.py +++ b/tests/test_distribution_split_verifier.py @@ -77,7 +77,7 @@ def _valid_pair( sim_payload: dict[str, bytes] | None = None, ): root_payload = { - "tracebook/__init__.py": b'__version__ = "0.6.0"\n', + "tracebook/__init__.py": f'__version__ = "{EXPECTED_VERSION}"\n'.encode("utf-8"), "tracebook/conformance/__init__.py": b"", "tracebook/conformance/cli.py": b"def main():\n return 0\n", } diff --git a/tests/test_external_integrations.py b/tests/test_external_integrations.py index e099202..8a10980 100644 --- a/tests/test_external_integrations.py +++ b/tests/test_external_integrations.py @@ -168,7 +168,7 @@ def test_orderbook_rs_documentation_and_ci_lock_the_proof_profile(): assert "--profile fifo-full-v1" in workflow assert "--events-per-trace 100" in workflow assert "sha256:95c3dac9d27b770a5cccebe9ff16b6e71af443001d633b640983f02f3e04b3c9" in workflow - assert "sha256:c04a07cbdb9931232162ef1a05740221311f3b2fa21b9b552093a2706a12c488" in workflow + assert "sha256:10c162a1a6db2a7715e98af54871cc7a94675f2e7c4fe3754e18c48157c0371c" in workflow assert "--test-fault=drop-first-trade" in workflow assert 'assert report["divergence"]["event_index"] == 3' in workflow assert "failure-bc8b19d3e0e3441a98db" in workflow @@ -199,7 +199,7 @@ def test_gocronx_matcher_integration_is_pinned_qualified_and_honest_about_assump assert "awaiting an upstream" in readme assert "stable public inspection contract" in readme assert "tracebook-conformance qualify" in workflow - assert "sha256:1636620f5f0f6b65fd425a6021424e9c7678bec5215555556c70a929c5e0b144" in workflow + assert "sha256:64746a4a21bc3fef7c88e58d749da2adb51cb74fac211088174aba26dc6746ed" in workflow assert "actions/upload-artifact@v7" in workflow @@ -225,9 +225,9 @@ def test_intrepid_orderbook_is_pinned_qualified_and_retains_the_fok_boundary(): assert "incoming quantity times each potentially crossed maker's" in readme assert "6/9" in readme assert "failure-1ce2954857800b3a068d" in readme - assert "sha256:f8db775baabe7e665d45bbb920a67e43d405acf445de4951617df68ffa24eb69" in workflow - assert "sha256:08bf641bfa57da1892d744c08bca0be00f5ac1ade580ae8fcf7f195f0fcad6eb" in workflow - assert "sha256:81a095f9804852ff7035f4c3d428a51ae3d0e8e4b81ec335128c6af15b6f65bd" in workflow + assert "sha256:5bb06673e36f6ecf7a328285275d7d72b6f1e22e40f139d628411d8fb8bb222b" in workflow + assert "sha256:baee6faa893cd5576f5fe42985250f1ce210d47c402c2c80de563088ff41dc85" in workflow + assert "sha256:ed59a8437c413f3376546ac6bc61452eb08ac75d008667fd619b185e4785f5a2" in workflow assert "$.observation.outcome.reason" in workflow assert "intrepidkarthi/orderbook` v0.26.0" in root_readme assert "integrations/intrepid_orderbook/" in architecture diff --git a/tests/test_release_metadata.py b/tests/test_release_metadata.py index d1b85ee..9d123ff 100644 --- a/tests/test_release_metadata.py +++ b/tests/test_release_metadata.py @@ -1,4 +1,5 @@ import json +import re from pathlib import Path try: @@ -8,6 +9,7 @@ import tracebook from tracebook._version import __version__ +from tools.verify_distribution_split import EXPECTED_VERSION ROOT = Path(__file__).resolve().parents[1] ROOT_DEVELOPMENT_EXTRAS = ("dev",) @@ -28,13 +30,30 @@ def test_runtime_version_has_single_source_of_truth(): metadata = _pyproject() assert tracebook.__version__ == __version__ - assert __version__ == "0.6.0" + assert __version__ == "0.7.0" assert metadata["project"]["dynamic"] == ["version"] assert metadata["tool"]["setuptools"]["dynamic"]["version"] == { "attr": "tracebook._version.__version__" } +def test_release_command_gates_match_the_prepared_package_version(): + assert EXPECTED_VERSION == __version__ + for relative_path in ( + "Makefile", + ".github/workflows/ci.yml", + ".github/workflows/release.yml", + "CONTRIBUTING.md", + "docs/release.md", + ): + contents = (ROOT / relative_path).read_text(encoding="utf-8") + versions = re.findall(r"--expected-version\s+(\d+\.\d+\.\d+)", contents) + assert versions, f"{relative_path} omits the coordinated version check" + assert set(versions) == {__version__}, relative_path + draft = ROOT / "docs" / "releases" / f"{__version__}.md" + assert "Draft — not published" in draft.read_text(encoding="utf-8") + + def test_distribution_name_cli_and_typing_metadata_are_release_ready(): metadata = _pyproject() project = metadata["project"] @@ -105,9 +124,9 @@ def test_simulator_facade_has_exact_version_dependency_and_no_packages(): assert _pyproject()["build-system"]["requires"] == build_requirements assert metadata["build-system"]["requires"] == build_requirements assert project["name"] == "tracebook-sim" - assert project["version"] == "0.6.0" + assert project["version"] == __version__ assert project["dependencies"] == [ - "tracebook-conformance==0.6.0", + f"tracebook-conformance=={__version__}", "numpy>=2.2.6", "psutil>=7.2.2", ] diff --git a/tools/verify_distribution_split.py b/tools/verify_distribution_split.py index 764a5f7..38eebf8 100644 --- a/tools/verify_distribution_split.py +++ b/tools/verify_distribution_split.py @@ -34,7 +34,7 @@ from pathlib import Path from typing import Iterable, Mapping, Sequence -EXPECTED_VERSION = "0.6.0" +EXPECTED_VERSION = "0.7.0" LEGACY_VERSION = "0.5.0" OFFICIAL_LEGACY_WHEEL_SHA256 = "d190e1c2af83e5d853b0734b4d9627b1a8f6707e0fbab391015d2d94437cd4da" CONFORMANCE_DISTRIBUTION = "tracebook-conformance" From 93d3b6e5dc567987dcd1ad3bca51df882f69d2a9 Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Fri, 4 Sep 2026 22:39:15 -0400 Subject: [PATCH 2/6] Fix release-code review findings; preserve frozen research --- CHANGELOG.md | 5 + docs/book-replay-conformance.md | 10 +- docs/pr-84-review-disposition.md | 94 +++++++++++ docs/release.md | 2 + integrations/gocronx_matcher/README.md | 3 + integrations/gocronx_matcher/src/adapter.rs | 35 +++- integrations/intrepid_orderbook/README.md | 2 +- integrations/intrepid_orderbook/adapter.go | 2 +- .../intrepid_orderbook/adapter_test.go | 47 ++++++ integrations/intrepid_orderbook/protocol.go | 11 +- integrations/orderbook_rs/README.md | 10 +- integrations/orderbook_rs/src/adapter.rs | 39 ++++- integrations/rust_protocol/src/quantity.rs | 40 ++++- src/tracebook/book_replay/artifacts.py | 72 +++++++-- src/tracebook/book_replay/campaign.py | 2 +- src/tracebook/book_replay/cli.py | 5 +- src/tracebook/book_replay/external.py | 16 +- src/tracebook/book_replay/model.py | 16 ++ src/tracebook/book_replay/protocol.py | 73 ++++++--- src/tracebook/book_replay/reference.py | 12 +- src/tracebook/conformance/model.py | 5 +- tests/fixtures/faulty_book_replay_adapter.py | 4 +- tests/test_book_replay.py | 153 ++++++++++++++++++ tests/test_book_replay_artifacts.py | 77 ++++++++- tests/test_book_replay_campaign.py | 47 ++---- tests/test_distribution_privacy.py | 19 +++ tests/test_integration_workflow_coverage.py | 77 ++++++++- tools/verify_distribution_privacy.py | 3 +- 28 files changed, 761 insertions(+), 120 deletions(-) create mode 100644 docs/pr-84-review-disposition.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a79caf..9c4ea5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ The project follows [Keep a Changelog](https://keepachangelog.com/) conventions. 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. +- Addressed the release-code findings from PR #84: fail closed on L3 shutdown + and malformed protocol values, preserve exact decimal probe arithmetic, + protect staged artifacts against ordinary source-path replacement, reject + zero-normalized Rust observations, and enforce Go IOC/FOK numeric limits. + Frozen research findings remain separately documented and unresolved. - Kept Rust adapter input quantities independent of report display precision. Both native adapters now share exact checked 12-place integer encoding and reject quantities outside that domain rather than pre-rounding orders. diff --git a/docs/book-replay-conformance.md b/docs/book-replay-conformance.md index 5f07a2f..59d46bc 100644 --- a/docs/book-replay-conformance.md +++ b/docs/book-replay-conformance.md @@ -112,12 +112,20 @@ files created by that attempt. These are individual file commits, not a filesystem-wide transaction: abrupt process termination can leave a complete trace without its report. Only use the pair after the command completes. Sibling `.NAME.tracebook-in-progress` reservations and `.tracebook-stage-*` -temporary files are removed on normal completion, with cleanup attempted on +private staging directories are removed on normal completion, with cleanup attempted on handled errors. Filesystem cleanup failures or competing replacements can leave sidecars. After a forced stop or cleanup failure, retain the artifacts and use fresh output names for a new invocation; do not remove a live process's reservations. +Staged payloads live in owner-only, read-only directories and publication uses +the open directory descriptor, so replacing a staging directory's parent entry +cannot substitute another payload. Published files are owner-readable. This +protects against ordinary concurrent file writers, not privileged processes or +same-user code deliberately changing permissions or writing through an already +open descriptor. Use a trusted output directory; these filesystem guards are +not a sandbox for hostile code running as your user. + ## Generated Campaigns And Reduction The v1 generator uses a specified SplitMix64 stream rather than Python's diff --git a/docs/pr-84-review-disposition.md b/docs/pr-84-review-disposition.md new file mode 100644 index 0000000..0547b6a --- /dev/null +++ b/docs/pr-84-review-disposition.md @@ -0,0 +1,94 @@ +# PR #84 Review Disposition + +This records the 30 comments in the initial automated review of +[PR #84](https://github.com/Taz33m/tracebook/pull/84), against `0c98e18`. +It is a disposition of that review, not release approval or a new experiment +result. Source and regression tests, not the review's severity labels, determine +the implemented changes. + +## Release-code fixes + +The following 17 comments are addressed in the release implementation. Comment +IDs identify the original GitHub review comments. Existing qualified-profile +identities and retained evidence are not rewritten to accommodate a change. + +| Comment ID | Change | Regression / verification surface | +| --- | --- | --- | +| 3939088988 | Close the L3 adapter before emitting `complete`; a failed close is one terminal adapter error, with no retry. | `test_server_close_failure_is_one_terminal_adapter_error` | +| 3939088991 | Both Rust adapters fail before emitting a positive fill/remainder normalized to zero. Inputs remain exact native lots. | Shared quantity tests and both adapters' `positive_fills_and_remainders_cannot_be_emitted_as_zero` | +| 3939089005 | Share the faulty FIFO-reordering fixture between in-process and external tests; retain each existing engine identity. | Existing campaign, reduction, and failure-ID regressions | +| 3939089008 | Validate typed L3 outcomes, fills, snapshot entries, and book collections during construction. | `test_invalid_in_process_observation_is_classified_as_protocol_failure` | +| 3939089018 | Correct the orderbook-rs translation contract: 12 native decimal places, independent output precision. | Quantity conversion regressions and README review | +| 3939089021 | Exact FIFO probe subtraction independent of ambient Decimal precision; remove context-rounding from shared canonical formatting too. | `test_probe_subtraction_and_canonical_values_are_exact_at_any_context_precision` | +| 3939089023 | Separate client decoding/validation failures from exceptions raised inside adapters. | Factory/apply/snapshot exception tests and malformed-payload test | +| 3939089028 | Require actual non-negative integer snapshot/finish counters; reject booleans, missing values, null, floats, and strings. | Parameterized session-counter tests | +| 3939089029 | Require Go snapshot/finish counters and an object event payload, without zero-value defaults accepting missing/null fields. | `TestServerRejectsMissingNullAndMistypedRequiredFields` | +| 3939089032 | Normalize timeout conversion errors, including oversized integers, into the public L3 error contract. | `test_external_timeout_overflow_is_a_public_validation_error` | +| 3939089038 | Wrap invalid ready-frame engine metadata as a book-replay protocol error and reap the child. | Invalid-metadata/child-reaping regression | +| 3939089052 | Stage in a private read-only directory and link relative to its open descriptor. Protect the payload entry from ordinary competing writers and anchor publication across directory replacement. | Stage-entry and stage-directory replacement tests, plus existing rollback/competing-destination tests | +| 3939089055 | Count price relocation only when the price actually changes, not on side-only updates. | `test_side_only_update_does_not_claim_price_relocation_coverage` | +| 3939089057 | Apply the documented conservative same-side aggregate envelope to IOC/FOK as well as GTC limit orders; retain the market exemption. | `TestSideAggregateEnvelopeIncludesIOCAndFOKButNotMarket` | +| 3939089063 | Report symlink-loop path resolution as a controlled CLI error before starting a candidate. | Symlink-loop CLI regression | +| 3939089067 | Handle corrupt deflated source inventories as a failed distribution privacy check. | Corrupt real ZIP-block regression | +| 3939089071 | Bound the workflow path reader to `on.pull_request.paths`, allowing comments, blank lines, different indentation, and other trigger keys. | Positive layout variants and negative job/other-trigger regressions | + +Two limits matter when interpreting these fixes: + +- Insufficient output precision is an operational error, not a semantic + rejection or a successful qualification. Native matching inputs are not + rounded, inflated, retried, or silently removed. The Python CLOB reference + also rejects zero normalized positive quantities; its positive-value wire + contract has not been relaxed. +- Artifact publication is not a security sandbox against root or same-user + code deliberately changing permissions or writing through existing file + descriptors. Use trusted output directories. Normal concurrent writers must + not overwrite destinations, and rollback preserves competing files. The + directory-permission test is intentionally skipped when running as root. + +## Frozen research findings — open, not silently patched + +These 13 findings are in the historical/hash-bound research harness. The +accepted scope leaves that code, frozen inputs, evaluator material, and retained +results unchanged. They remain open pending a separate research disposition; +the release fixes above do not resolve them. + +| Comment ID | Reported issue | Required next decision/check | +| --- | --- | --- | +| 3939088982 | V2 Claude auth-route probe inherits ambient environment. | Audit route-binding evidence locally; use a sanitized, explicit environment in a newly versioned runner. | +| 3939088984 | V2 finalization failure before verdict can quarantine a completed provider turn. | Audit lifecycle receipts without rerunning providers; a future runner needs a durable provider-completion barrier before finalization. | +| 3939088987 | V2 frozen snapshots permit symbolic links. | Assess snapshot inventories and provider read boundaries locally; preregister an explicit link policy for future runs. | +| 3939088994 | Baseline live copy is not checked against its frozen source before launch. | Audit existing snapshot bindings; bind and verify copied workspaces in a future runner. | +| 3939089000 | Baseline command success can outlive a failed/timed-out provider. | Audit lifecycle exit receipts; separate transport completion and semantic outcomes in a new runner. | +| 3939089002 | Treatment technical verdict handling exempts some unsuccessful provider exits/timeouts. | Audit treatment lifecycle verdicts separately from V2, which has its own completion checks. | +| 3939089010 | Missing/unreadable V2 bound file can escape as `OSError`. | Add controlled validation errors in a future version, preserving frozen hash bindings. | +| 3939089043 | Baseline missing reported model falls back to `opus`. | Treat absent model evidence as missing, not observed identity, in a separately versioned audit/fix. | +| 3939089045 | Baseline permits an execution-time timeout override. | Compare receipts to the preregistered budget before deciding whether existing runs are affected. | +| 3939089048 | Baseline candidate/gold paths lack private-root confinement. | Audit declared paths locally; enforce resolved boundaries in a new runner. | +| 3939089050 | Baseline case IDs admit path components. | Audit manifest IDs; enforce a safe identifier grammar in a new runner. | +| 3939089056 | Treatment validation omits some workspace evidence artifacts. | Audit artifact completeness locally and specify required evidence in a new validator version. | +| 3939089060 | Baseline quarantine checks a verdict sentinel that baseline does not write. | Distinguish completed turns from incomplete interruptions using lifecycle receipts, not a missing sentinel. | + +These are source-level risks, not proof that a particular completed cohort was +contaminated. Do not pool different harness generations, modify an old frozen +runner in place, reinterpret missing metadata as observed evidence, or rerun a +completed provider turn. An approved audit should be local and preserve every +interruption artifact; any necessary future collection needs a new versioned +protocol and explicit authorization. No private gold or evaluator artifacts +belong in a provider request or this public document. + +## Release gate + +Local verification of the fixes passed: Python 3.13 had 651 passing tests, +one skip, and 82.38% coverage; the focused Python 3.10 regressions passed too. +Formatting, lint, type checking, static security checks, pinned Rust 1.88/Go +1.23.5 checks, distribution privacy, and sdist/wheel agreement passed. +Fresh 5,000-event qualifications retained the exact orderbook-rs, gocronx, Go +FIFO-limit, and Go partial-fill identities. The Go full-profile FOK failure and +the Nautilus 2,500-event positive campaign/three-event negative control retained +their expected identities and reduced trace. These are local checks; consult +the PR for the latest remote CI and review state. + +Keep the research conversations open until their disposition is agreed. Passing +release tests does not justify dismissing those comments, bypassing repository +protections, merging the PR, or publishing a tag. The previous maintainer +invitation and its immutable source/wheel references remain unchanged. diff --git a/docs/release.md b/docs/release.md index a31a689..4023dec 100644 --- a/docs/release.md +++ b/docs/release.md @@ -70,6 +70,8 @@ python -m pip check ## Remote Verification +- Review the [PR #84 disposition](pr-84-review-disposition.md): release-code + fixes do not close the separately frozen research findings or authorize a release. - Push to a branch and wait for Ubuntu GitHub Actions on Python 3.10 through 3.13. - Confirm the native `orderbook-rs` integration passes its fixed trace, `7/9` diff --git a/integrations/gocronx_matcher/README.md b/integrations/gocronx_matcher/README.md index 8cc1ed1..f36838d 100644 --- a/integrations/gocronx_matcher/README.md +++ b/integrations/gocronx_matcher/README.md @@ -50,6 +50,9 @@ traces, 10/10 covered capabilities, and 28 candidate process runs. The adapter scales prices into integer ticks and quantities into fixed twelve-place native lots. `quantity_decimal_places` controls output rounding only; it never rounds submitted order, reduction, or replacement quantities. +If normalization would turn a positive fill or remainder into zero, the session +fails with an adapter error before emitting that invalid observation. Use enough +output precision for the trace; this does not round or resubmit native orders. For example, at output precision zero, crossing a `2.4` buy with a `3.5` sell leaves native quantity `1.1`, reported as `1`. Nonrepresentable quantities are rejected before submission, and invalid replacement quantities preserve the diff --git a/integrations/gocronx_matcher/src/adapter.rs b/integrations/gocronx_matcher/src/adapter.rs index 86ec5e8..0b0d39b 100644 --- a/integrations/gocronx_matcher/src/adapter.rs +++ b/integrations/gocronx_matcher/src/adapter.rs @@ -75,7 +75,7 @@ impl AdapterConfig { Ok(canonical_decimal(price)) } - fn format_quantity(&self, units: u64) -> String { + fn format_quantity(&self, units: u64) -> Result { self.quantity_encoding.format(units) } } @@ -389,7 +389,7 @@ impl Adapter { buy_order_id: trade.buy_id.get(), sell_order_id: trade.sell_id.get(), price: self.config.format_price(trade.price.get())?, - quantity: self.config.format_quantity(trade.quantity.get()), + quantity: self.config.format_quantity(trade.quantity.get())?, }) } @@ -432,7 +432,7 @@ impl Adapter { Ok(RestingOrder { order_id: order.order_id, price: self.config.format_price(order.price)?, - remaining_quantity: self.config.format_quantity(order.remaining), + remaining_quantity: self.config.format_quantity(order.remaining)?, owner, order_type: "LIMIT", }) @@ -617,6 +617,35 @@ mod tests { assert_eq!(state.books[0].asks[0].remaining_quantity, "1"); } + #[test] + fn positive_fills_and_remainders_cannot_be_emitted_as_zero() { + for (maker, taker) in [(0.4, None), (1.0, Some(0.4)), (1.0, Some(0.6))] { + let mut adapter = Adapter::new(ConfigWire { + quantity_decimal_places: 0, + ..ConfigWire::default() + }) + .unwrap(); + let first = serde_json::from_value::(serde_json::json!({ + "op":"new","symbol":"TEST","order_id":1,"side":"BUY","price":100,"quantity":maker + })) + .unwrap(); + let result = if let Some(quantity) = taker { + adapter.apply(&first, 1).unwrap(); + let second = serde_json::from_value::(serde_json::json!({ + "op":"new","symbol":"TEST","order_id":2,"side":"SELL","price":100,"quantity":quantity + })).unwrap(); + adapter.apply(&second, 2) + } else { + adapter.apply(&first, 1) + }; + assert!( + result + .unwrap_err() + .contains("positive quantity cannot be represented") + ); + } + } + #[test] fn output_precision_does_not_round_reduce_or_replace_inputs() { let mut adapter = Adapter::new(ConfigWire { diff --git a/integrations/intrepid_orderbook/README.md b/integrations/intrepid_orderbook/README.md index 03f28ea..f2d9f83 100644 --- a/integrations/intrepid_orderbook/README.md +++ b/integrations/intrepid_orderbook/README.md @@ -42,7 +42,7 @@ precision is lower. The native arithmetic has a bounded domain: - price ticks and scaled quantities must be positive and fit signed `int64`; -- before admitting a limit order, the adapter requires its full quantity plus +- before admitting a limit, IOC, or FOK order, the adapter requires its full quantity plus all resting quantity on its side to fit signed `int64` (replacement excludes the old order); - under pro-rata, incoming quantity times each potentially crossed maker's diff --git a/integrations/intrepid_orderbook/adapter.go b/integrations/intrepid_orderbook/adapter.go index 51a642a..7de94e0 100644 --- a/integrations/intrepid_orderbook/adapter.go +++ b/integrations/intrepid_orderbook/adapter.go @@ -252,7 +252,7 @@ func (book *bookHarness) checkQuantityCapacity( return errors.New("quantity exceeds the native int64 pro-rata product range") } } - if orderType == "LIMIT" && quantity > math.MaxInt64-sameSideTotal { + if orderType != "MARKET" && quantity > math.MaxInt64-sameSideTotal { return errors.New("quantity exceeds the native int64 side aggregate range") } return nil diff --git a/integrations/intrepid_orderbook/adapter_test.go b/integrations/intrepid_orderbook/adapter_test.go index b59400e..7c49251 100644 --- a/integrations/intrepid_orderbook/adapter_test.go +++ b/integrations/intrepid_orderbook/adapter_test.go @@ -173,6 +173,53 @@ func TestServerHandshakeAndEmptyCompletion(t *testing.T) { } } +func TestServerRejectsMissingNullAndMistypedRequiredFields(t *testing.T) { + for _, frame := range []string{ + `{"type":"finish"}`, `{"type":"finish","event_count":null}`, + `{"type":"finish","event_count":false}`, `{"type":"finish","event_count":"0"}`, + `{"type":"finish","event_count":0.0}`, `{"type":"finish","event_count":-1}`, + `{"type":"snapshot"}`, `{"type":"snapshot","index":null}`, + `{"type":"snapshot","index":true}`, `{"type":"snapshot","index":"0"}`, + `{"type":"event","index":1}`, `{"type":"event","index":1,"event":null}`, + `{"type":"event","index":1,"event":[]}`, `{"type":"event","index":1,"event":false}`, + } { + t.Run(frame, func(t *testing.T) { + input := `{"type":"hello","protocol":"tracebook.conformance","protocol_version":1}` + "\n" + frame + var output bytes.Buffer + if status := serve(strings.NewReader(input), &output); status != 2 { + t.Fatalf("status = %d, output = %s", status, output.String()) + } + lines := strings.Split(strings.TrimSpace(output.String()), "\n") + if len(lines) != 2 || !strings.Contains(lines[1], `"code":"PROTOCOL_ERROR"`) { + t.Fatalf("expected ready and one protocol error: %s", output.String()) + } + }) + } +} + +func TestSideAggregateEnvelopeIncludesIOCAndFOKButNotMarket(t *testing.T) { + for _, orderType := range []string{"LIMIT", "IOC", "FOK", "MARKET"} { + t.Run(orderType, func(t *testing.T) { + harness := testAdapter(t, configWire{}) + first := applyForTest(t, harness, limitEvent("1", "BUY", "0.01", "4700000000000")) + event := limitEvent("2", "BUY", "0.01", "4700000000000") + event.OrderType = orderType + got := applyForTest(t, harness, event) + if got.StateHash != first.StateHash || len(got.Trades) != 0 { + t.Fatalf("unsupported aggregate mutated the book: %#v", got) + } + if orderType == "MARKET" { + if got.Outcome.Status != "applied" { + t.Fatalf("market order lost its aggregate exemption: %#v", got) + } + } else if got.Outcome.Status != "rejected" || got.Outcome.Message == nil || + !strings.Contains(*got.Outcome.Message, "side aggregate range") { + t.Fatalf("expected pre-mutation aggregate rejection: %#v", got) + } + }) + } +} + func TestServerHandshakeReportsInjectedEvidenceIdentity(t *testing.T) { previousRevision, previousSnapshot := engineRevision, engineSnapshot t.Cleanup(func() { diff --git a/integrations/intrepid_orderbook/protocol.go b/integrations/intrepid_orderbook/protocol.go index 6c08c55..b8f66a6 100644 --- a/integrations/intrepid_orderbook/protocol.go +++ b/integrations/intrepid_orderbook/protocol.go @@ -304,6 +304,9 @@ func runServer(decoder *json.Decoder, writer *bufio.Writer) error { } switch kind { case "event": + if raw := object["event"]; len(raw) == 0 || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) { + return protocolError("event payload must be an object") + } var frame eventFrame if err := decodeObject(object, &frame); err != nil { return protocolError(err.Error()) @@ -321,12 +324,12 @@ func runServer(decoder *json.Decoder, writer *bufio.Writer) error { } case "snapshot": var frame struct { - Index uint64 `json:"index"` + Index *uint64 `json:"index"` } if err := decodeObject(object, &frame); err != nil { return protocolError(err.Error()) } - if frame.Index != lastIndex { + if frame.Index == nil || *frame.Index != lastIndex { return protocolError("snapshot index does not match the last event") } state, err := adapter.snapshot() @@ -340,12 +343,12 @@ func runServer(decoder *json.Decoder, writer *bufio.Writer) error { } case "finish": var frame struct { - EventCount uint64 `json:"event_count"` + EventCount *uint64 `json:"event_count"` } if err := decodeObject(object, &frame); err != nil { return protocolError(err.Error()) } - if frame.EventCount != lastIndex { + if frame.EventCount == nil || *frame.EventCount != lastIndex { return protocolError("finish event_count does not match the last event") } return writeFrame(writer, map[string]any{ diff --git a/integrations/orderbook_rs/README.md b/integrations/orderbook_rs/README.md index 323ecdd..5e4329d 100644 --- a/integrations/orderbook_rs/README.md +++ b/integrations/orderbook_rs/README.md @@ -230,8 +230,14 @@ artifacts under `target/` are excluded. rounding, are stored as integer ticks, and return as canonical decimal strings. This is intentionally not exact decimal division at half-tick boundaries; for example, `1.015 / 0.01` snaps to `1.01`. -- Quantities use fixed-point `u64` units at `quantity_decimal_places`; a value - that rounds to zero or overflows that range is rejected. +- Quantities use fixed-point `u64` units at 12 native decimal places. Inputs + requiring finer precision or exceeding that native range are rejected without + rounding. `quantity_decimal_places` controls output normalization only; it + never changes the quantity submitted to the engine. + If output normalization would turn a positive fill or remainder into zero, + the session fails with an adapter error before emitting an invalid observation. + Choose enough output precision for the trace; low-precision configurations + outside the recorded profiles are not qualified by those results. - Real owners map deterministically to `Hash32`. Anonymous owners receive a unique per-order identity so STP does not make unrelated anonymous orders self-match or reject them for a missing user ID. diff --git a/integrations/orderbook_rs/src/adapter.rs b/integrations/orderbook_rs/src/adapter.rs index b1b0c1e..c2e15ae 100644 --- a/integrations/orderbook_rs/src/adapter.rs +++ b/integrations/orderbook_rs/src/adapter.rs @@ -114,7 +114,7 @@ impl AdapterConfig { Ok(canonical_decimal(price)) } - fn format_quantity(&self, units: u64) -> String { + fn format_quantity(&self, units: u64) -> Result { self.quantity_encoding.format(units) } } @@ -614,7 +614,7 @@ impl Adapter { buy_order_id, sell_order_id, price: self.config.format_price(trade.price().as_u128())?, - quantity: self.config.format_quantity(trade.quantity().as_u64()), + quantity: self.config.format_quantity(trade.quantity().as_u64())?, }); } } @@ -655,7 +655,7 @@ impl Adapter { Ok(RestingOrder { order_id, price: self.config.format_price(order.price().as_u128())?, - remaining_quantity: self.config.format_quantity(visible_quantity(order)), + remaining_quantity: self.config.format_quantity(visible_quantity(order))?, owner, order_type: "LIMIT", }) @@ -779,8 +779,8 @@ mod tests { let high = serde_json::Number::from_str("1.2355").unwrap(); assert_eq!(config.quantity_units(&low).unwrap(), 1_234_500_000_000); assert_eq!(config.quantity_units(&high).unwrap(), 1_235_500_000_000); - assert_eq!(config.format_quantity(1_234_500_000_000), "1.234"); - assert_eq!(config.format_quantity(1_235_500_000_000), "1.236"); + assert_eq!(config.format_quantity(1_234_500_000_000).unwrap(), "1.234"); + assert_eq!(config.format_quantity(1_235_500_000_000).unwrap(), "1.236"); } #[test] @@ -813,6 +813,35 @@ mod tests { assert_eq!(state.books[0].asks[0].remaining_quantity, "1"); } + #[test] + fn positive_fills_and_remainders_cannot_be_emitted_as_zero() { + for (maker, taker) in [(0.4, None), (1.0, Some(0.4)), (1.0, Some(0.6))] { + let mut adapter = Adapter::new(ConfigWire { + quantity_decimal_places: 0, + ..ConfigWire::default() + }) + .unwrap(); + let first = serde_json::from_value::(serde_json::json!({ + "op":"new","symbol":"TEST","order_id":1,"side":"BUY","price":100,"quantity":maker + })) + .unwrap(); + let result = if let Some(quantity) = taker { + adapter.apply(&first, 1).unwrap(); + let second = serde_json::from_value::(serde_json::json!({ + "op":"new","symbol":"TEST","order_id":2,"side":"SELL","price":100,"quantity":quantity + })).unwrap(); + adapter.apply(&second, 2) + } else { + adapter.apply(&first, 1) + }; + assert!( + result + .unwrap_err() + .contains("positive quantity cannot be represented") + ); + } + } + #[test] fn output_precision_does_not_round_reduce_or_replace_inputs() { let mut adapter = Adapter::new(ConfigWire { diff --git a/integrations/rust_protocol/src/quantity.rs b/integrations/rust_protocol/src/quantity.rs index ead2ae1..41009b8 100644 --- a/integrations/rust_protocol/src/quantity.rs +++ b/integrations/rust_protocol/src/quantity.rs @@ -60,7 +60,7 @@ impl QuantityEncoding { coefficient.checked_mul(multiplier).ok_or_else(range_error) } - pub fn format(&self, units: u64) -> String { + pub fn format(&self, units: u64) -> Result { let places = self.output_decimal_places.min(NATIVE_DECIMAL_PLACES); let divisor = 10_u64.pow(NATIVE_DECIMAL_PLACES - places); let mut rounded = units / divisor; @@ -71,15 +71,23 @@ impl QuantityEncoding { // With divisor >= 10, incrementing the quotient cannot overflow. rounded += 1; } + if rounded == 0 { + return Err(format!( + "positive quantity cannot be represented at quantity_decimal_places={}", + self.output_decimal_places + )); + } let scale = 10_u64.pow(places); let whole = rounded / scale; let fraction = rounded % scale; if fraction == 0 { - return whole.to_string(); + return Ok(whole.to_string()); } - format!("{whole}.{fraction:0width$}", width = places as usize) - .trim_end_matches('0') - .to_string() + Ok( + format!("{whole}.{fraction:0width$}", width = places as usize) + .trim_end_matches('0') + .to_string(), + ) } } @@ -155,7 +163,7 @@ mod tests { ] { assert!(encoding.units(&number(text)).is_err(), "{text}"); } - assert_eq!(encoding.format(u64::MAX), "18446744.073709551615"); + assert_eq!(encoding.format(u64::MAX).unwrap(), "18446744.073709551615"); } #[test] @@ -170,10 +178,28 @@ mod tests { ] { let encoding = QuantityEncoding::new(places).unwrap(); assert_eq!( - encoding.format(encoding.units(&number(text)).unwrap()), + encoding + .format(encoding.units(&number(text)).unwrap()) + .unwrap(), expected ); } assert!(QuantityEncoding::new(19).is_err()); } + + #[test] + fn unrepresentable_positive_observations_fail_instead_of_emitting_zero() { + for (places, text) in [(0, "0.4"), (0, "0.5"), (3, "0.0004"), (11, "1e-12")] { + let encoding = QuantityEncoding::new(places).unwrap(); + let units = encoding.units(&number(text)).unwrap(); + assert!(units > 0); + assert!( + encoding + .format(units) + .unwrap_err() + .contains("cannot be represented") + ); + } + assert!(QuantityEncoding::new(12).unwrap().format(0).is_err()); + } } diff --git a/src/tracebook/book_replay/artifacts.py b/src/tracebook/book_replay/artifacts.py index f762a14..12f2eea 100644 --- a/src/tracebook/book_replay/artifacts.py +++ b/src/tracebook/book_replay/artifacts.py @@ -28,10 +28,15 @@ class OutputReservation: def __init__(self, destination: str | Path) -> None: path = Path(destination).expanduser() self._requested_target = path.absolute() - self.target = path.parent.resolve() / path.name + try: + self.target = path.parent.resolve() / path.name + except RuntimeError as exc: + raise BookReplayError(f"cannot resolve book-replay path: {exc}") from exc self._lock_name = f".{self.target.name}.tracebook-in-progress" - self._stage_name = f".tracebook-stage-{uuid.uuid4().hex}" + self._stage_directory_name = f".tracebook-stage-{uuid.uuid4().hex}" + self._stage_name = "payload" self._parent_fd: Optional[int] = None + self._stage_directory_fd: Optional[int] = None self._lock_fd: Optional[int] = None self._stage_fd: Optional[int] = None self._published = False @@ -50,7 +55,21 @@ def __enter__(self) -> "OutputReservation": self._require_absent() flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) self._lock_fd = os.open(self._lock_name, flags, 0o600, dir_fd=self._parent_fd) - self._stage_fd = os.open(self._stage_name, flags, 0o600, dir_fd=self._parent_fd) + os.mkdir(self._stage_directory_name, mode=0o700, dir_fd=self._parent_fd) + self._stage_directory_fd = os.open( + self._stage_directory_name, + os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0), + dir_fd=self._parent_fd, + ) + self._stage_fd = os.open( + self._stage_name, flags, 0o400, dir_fd=self._stage_directory_fd + ) + # Keep the source entry in a private, non-writable directory. The + # write descriptor remains usable, but another normal file writer + # cannot replace the source entry in the validate/link window. + # Linking relative to this directory's descriptor also survives a + # competing rename/replacement of its entry in the output parent. + os.fchmod(self._stage_directory_fd, 0o500) self.validate() except BaseException: try: @@ -74,13 +93,16 @@ def _require_absent(self) -> None: return raise BookReplayError(f"book-replay output already exists: {self.target}") - def _owns_entry(self, name: str, descriptor: Optional[int]) -> bool: - if self._parent_fd is None or descriptor is None: + def _owns_entry( + self, name: str, descriptor: Optional[int], *, directory: Optional[int] = None + ) -> bool: + directory = self._parent_fd if directory is None else directory + if directory is None or descriptor is None: return False try: - return _identity( - os.stat(name, dir_fd=self._parent_fd, follow_symlinks=False) - ) == _identity(os.fstat(descriptor)) + return _identity(os.stat(name, dir_fd=directory, follow_symlinks=False)) == _identity( + os.fstat(descriptor) + ) except OSError: return False @@ -90,7 +112,10 @@ def validate(self) -> None: if ( not self._same_parent() or not self._owns_entry(self._lock_name, self._lock_fd) - or not self._owns_entry(self._stage_name, self._stage_fd) + or not self._owns_entry(self._stage_directory_name, self._stage_directory_fd) + or not self._owns_entry( + self._stage_name, self._stage_fd, directory=self._stage_directory_fd + ) ): raise BookReplayError(f"book-replay output reservation changed: {self.target}") self._require_absent() @@ -123,7 +148,7 @@ def publish(self) -> None: os.link( self._stage_name, self.target.name, - src_dir_fd=self._parent_fd, + src_dir_fd=self._stage_directory_fd, dst_dir_fd=self._parent_fd, follow_symlinks=False, ) @@ -144,14 +169,19 @@ def rollback(self) -> None: def close(self) -> None: error: Optional[OSError] = None - for name, descriptor in ( - (self._stage_name, self._stage_fd), - (self._lock_name, self._lock_fd), + if self._stage_directory_fd is not None: + try: + os.fchmod(self._stage_directory_fd, 0o700) + except OSError as exc: + error = exc + for name, descriptor, directory in ( + (self._stage_name, self._stage_fd, self._stage_directory_fd), + (self._lock_name, self._lock_fd, self._parent_fd), ): if descriptor is not None: try: - if self._owns_entry(name, descriptor): - os.unlink(name, dir_fd=self._parent_fd) + if self._owns_entry(name, descriptor, directory=directory): + os.unlink(name, dir_fd=directory) except OSError as exc: error = error or exc finally: @@ -160,6 +190,18 @@ def close(self) -> None: except OSError as exc: error = error or exc self._stage_fd = self._lock_fd = None + if self._stage_directory_fd is not None: + try: + if self._owns_entry(self._stage_directory_name, self._stage_directory_fd): + os.rmdir(self._stage_directory_name, dir_fd=self._parent_fd) + except OSError as exc: + error = error or exc + finally: + try: + os.close(self._stage_directory_fd) + except OSError as exc: + error = error or exc + self._stage_directory_fd = None if self._parent_fd is not None: try: os.close(self._parent_fd) diff --git a/src/tracebook/book_replay/campaign.py b/src/tracebook/book_replay/campaign.py index c696658..f860485 100644 --- a/src/tracebook/book_replay/campaign.py +++ b/src/tracebook/book_replay/campaign.py @@ -307,7 +307,7 @@ def measure_book_replay_coverage( if previous.side == event.side and previous.price == event.price: if Decimal(event.quantity or "0") > Decimal(previous.quantity or "0"): covered.add("same-level-upsize") - else: + elif previous.price != event.price: covered.add("price-relocation") active[key] = event elif event.op == "delete": diff --git a/src/tracebook/book_replay/cli.py b/src/tracebook/book_replay/cli.py index 2b4ab45..60ae764 100644 --- a/src/tracebook/book_replay/cli.py +++ b/src/tracebook/book_replay/cli.py @@ -125,7 +125,10 @@ def _emit( def _require_distinct_paths(*paths: Optional[str]) -> None: - resolved = [Path(path).expanduser().resolve() for path in paths if path is not None] + try: + resolved = [Path(path).expanduser().resolve() for path in paths if path is not None] + except RuntimeError as exc: + raise BookReplayError(f"cannot resolve book-replay path: {exc}") from exc if len(resolved) != len(set(resolved)) or any( left in right.parents or right in left.parents for index, left in enumerate(resolved) diff --git a/src/tracebook/book_replay/external.py b/src/tracebook/book_replay/external.py index 14101ae..f2a286b 100644 --- a/src/tracebook/book_replay/external.py +++ b/src/tracebook/book_replay/external.py @@ -11,6 +11,7 @@ from pathlib import Path from typing import Deque, Mapping, Optional, Sequence +from ..conformance.model import ConformanceError from .model import ( PROTOCOL_NAME, PROTOCOL_VERSION, @@ -46,16 +47,20 @@ def __init__( if not isinstance(argument, str) or not argument: raise BookReplayError("candidate command arguments must be non-empty strings") normalized_command.append(argument) + try: + normalized_timeout = float(timeout_seconds) + except (TypeError, ValueError, OverflowError) as exc: + raise BookReplayError("timeout_seconds must be a positive finite number") from exc if ( isinstance(timeout_seconds, bool) or not isinstance(timeout_seconds, (int, float)) - or not math.isfinite(float(timeout_seconds)) - or timeout_seconds <= 0 + or not math.isfinite(normalized_timeout) + or normalized_timeout <= 0 ): raise BookReplayError("timeout_seconds must be a positive finite number") self.command = tuple(normalized_command) - self.timeout_seconds = float(timeout_seconds) + self.timeout_seconds = normalized_timeout self._closed = False self._broken = False self._last_index = 0 @@ -112,7 +117,10 @@ def __init__( raise BookReplayProtocolError("ready message reported the wrong protocol") if ready.get("protocol_version") != PROTOCOL_VERSION: raise BookReplayProtocolError("ready message reported the wrong protocol version") - self.metadata = EngineMetadata.from_dict(ready.get("engine", {})) + try: + self.metadata = EngineMetadata.from_dict(ready.get("engine", {})) + except ConformanceError as exc: + raise BookReplayProtocolError(f"invalid ready engine metadata: {exc}") from exc except Exception: self._broken = True self._shutdown() diff --git a/src/tracebook/book_replay/model.py b/src/tracebook/book_replay/model.py index 96c0ef9..57b42c5 100644 --- a/src/tracebook/book_replay/model.py +++ b/src/tracebook/book_replay/model.py @@ -213,6 +213,12 @@ class BookReplaySnapshot: def __post_init__(self) -> None: object.__setattr__(self, "symbol", _symbol(self.symbol)) + for name in ("bids", "asks"): + orders = getattr(self, name) + if not isinstance(orders, tuple) or any( + not isinstance(order, RestingBookOrder) for order in orders + ): + raise BookReplayError(f"{name} must be a tuple of RestingBookOrder values") order_ids = [order.order_id for order in self.bids + self.asks] if len(order_ids) != len(set(order_ids)): raise BookReplayError(f"book {self.symbol!r} contains duplicate order ids") @@ -246,6 +252,10 @@ class BookReplayState: books: Tuple[BookReplaySnapshot, ...] = () def __post_init__(self) -> None: + if not isinstance(self.books, tuple) or any( + not isinstance(book, BookReplaySnapshot) for book in self.books + ): + raise BookReplayError("books must be a tuple of BookReplaySnapshot values") symbols = [book.symbol for book in self.books] if symbols != sorted(symbols) or len(symbols) != len(set(symbols)): raise BookReplayError("book snapshots must have unique symbols in sorted order") @@ -282,6 +292,12 @@ class BookReplayObservation: def __post_init__(self) -> None: object.__setattr__(self, "index", _positive_int(self.index, "observation index")) + if not isinstance(self.outcome, Outcome): + raise BookReplayError("observation outcome must be an Outcome") + if not isinstance(self.fills, tuple) or any( + not isinstance(fill, SimulatedFill) for fill in self.fills + ): + raise BookReplayError("observation fills must be a tuple of SimulatedFill values") if ( not isinstance(self.state_hash, str) or len(self.state_hash) != _HASH_LENGTH diff --git a/src/tracebook/book_replay/protocol.py b/src/tracebook/book_replay/protocol.py index 9ad8dfc..2fa16e4 100644 --- a/src/tracebook/book_replay/protocol.py +++ b/src/tracebook/book_replay/protocol.py @@ -32,6 +32,26 @@ def close(self) -> None: ... BookReplayAdapterFactory = Callable[[BookReplayConfig], BookReplayAdapter] +class _RequestError(ValueError): + """Invalid client input, distinct from exceptions inside an adapter.""" + + +def _message(line: str) -> dict: + try: + message = json.loads(line) + except json.JSONDecodeError as exc: + raise _RequestError(str(exc)) from exc + if not isinstance(message, dict): + raise _RequestError("protocol message must be an object") + return message + + +def _index(value: object, name: str) -> int: + if isinstance(value, bool) or not isinstance(value, int) or value < 0: + raise _RequestError(f"{name} must be a non-negative integer") + return value + + def _write_message(stream: TextIO, payload: dict) -> None: stream.write(json.dumps(payload, separators=(",", ":"), allow_nan=False) + "\n") stream.flush() @@ -50,15 +70,19 @@ def serve_book_replay_stdio( try: first_line = source.readline() if not first_line: - raise ValueError("expected hello message") - hello = json.loads(first_line) - if not isinstance(hello, dict) or hello.get("type") != "hello": - raise ValueError("first message must be hello") + raise _RequestError("expected hello message") + hello = _message(first_line) + if hello.get("type") != "hello": + raise _RequestError("first message must be hello") if hello.get("protocol") != PROTOCOL_NAME: - raise ValueError(f"protocol must be {PROTOCOL_NAME!r}") - if hello.get("protocol_version") != PROTOCOL_VERSION: - raise ValueError(f"protocol_version must be {PROTOCOL_VERSION}") - adapter = adapter_factory(BookReplayConfig.from_dict(hello.get("config", {}))) + raise _RequestError(f"protocol must be {PROTOCOL_NAME!r}") + if _index(hello.get("protocol_version"), "protocol_version") != PROTOCOL_VERSION: + raise _RequestError(f"protocol_version must be {PROTOCOL_VERSION}") + try: + config = BookReplayConfig.from_dict(hello.get("config", {})) + except (TypeError, ValueError) as exc: + raise _RequestError(str(exc)) from exc + adapter = adapter_factory(config) _write_message( sink, { @@ -72,25 +96,24 @@ def serve_book_replay_stdio( for line in source: if not line.strip(): continue - message = json.loads(line) - if not isinstance(message, dict): - raise ValueError("protocol message must be an object") + message = _message(line) message_type = message.get("type") if message_type == "event": - index = message.get("index") - if isinstance(index, bool) or not isinstance(index, int) or index <= 0: - raise ValueError("event index must be a positive integer") + index = _index(message.get("index"), "event index") if index != last_index + 1: - raise ValueError("event indexes must be contiguous and start at 1") - event = BookReplayEvent.from_mapping(message.get("event", {})) + raise _RequestError("event indexes must be contiguous and start at 1") + try: + event = BookReplayEvent.from_mapping(message.get("event", {})) + except (TypeError, ValueError) as exc: + raise _RequestError(str(exc)) from exc observation = adapter.apply(event, index) if observation.index != index: raise ValueError("adapter returned the wrong observation index") last_index = index _write_message(sink, observation.to_dict(include_type=True)) elif message_type == "snapshot": - if message.get("index") != last_index: - raise ValueError("snapshot index does not match the last event") + if _index(message.get("index"), "snapshot index") != last_index: + raise _RequestError("snapshot index does not match the last event") _write_message( sink, { @@ -100,14 +123,18 @@ def serve_book_replay_stdio( }, ) elif message_type == "finish": - if message.get("event_count") != last_index: - raise ValueError("finish event_count does not match the last event") + if _index(message.get("event_count"), "finish event_count") != last_index: + raise _RequestError("finish event_count does not match the last event") + # Completion includes shutdown. Detach first so a failing close + # produces one error and is never retried by the cleanup path. + closing, adapter = adapter, None + closing.close() _write_message(sink, {"type": "complete", "event_count": last_index}) return 0 else: - raise ValueError(f"unsupported protocol message type: {message_type!r}") - raise ValueError("protocol ended before finish") - except (BrokenPipeError, json.JSONDecodeError, TypeError, ValueError) as exc: + raise _RequestError(f"unsupported protocol message type: {message_type!r}") + raise _RequestError("protocol ended before finish") + except (_RequestError, BrokenPipeError) as exc: try: _write_message(sink, {"type": "error", "code": "PROTOCOL_ERROR", "message": str(exc)}) except BrokenPipeError: diff --git a/src/tracebook/book_replay/reference.py b/src/tracebook/book_replay/reference.py index 907b966..fe1c54f 100644 --- a/src/tracebook/book_replay/reference.py +++ b/src/tracebook/book_replay/reference.py @@ -3,7 +3,7 @@ from __future__ import annotations from dataclasses import dataclass -from decimal import Decimal +from decimal import Decimal, localcontext from typing import Dict, List, Tuple, cast from .._version import __version__ @@ -159,7 +159,15 @@ def _probe(self, event: BookReplayEvent) -> Tuple[SimulatedFill, ...]: quantity=canonical_decimal(quantity), ) ) - remaining -= quantity + # Align both coefficients before subtracting. The ambient + # Decimal context must not erase small FIFO fills. + with localcontext() as context: + exponent = min( + cast(int, remaining.as_tuple().exponent), + cast(int, quantity.as_tuple().exponent), + ) + context.prec = max(remaining.adjusted(), quantity.adjusted()) - exponent + 2 + remaining -= quantity if remaining == 0: return tuple(fills) return tuple(fills) diff --git a/src/tracebook/conformance/model.py b/src/tracebook/conformance/model.py index 9890bc8..0fd86f5 100644 --- a/src/tracebook/conformance/model.py +++ b/src/tracebook/conformance/model.py @@ -54,7 +54,10 @@ def canonical_decimal(value: Any, decimal_places: Optional[int] = None) -> str: raise ConformanceError(f"numeric value cannot be normalized: {value!r}") from exc if number == 0: return "0" - return format(number.normalize(), "f") + # Decimal.normalize() applies the ambient precision and can silently round + # an otherwise exact value. Strip insignificant zeros from fixed-point text. + rendered = format(number, "f") + return rendered.rstrip("0").rstrip(".") if "." in rendered else rendered def _positive_int(value: Any, field_name: str) -> int: diff --git a/tests/fixtures/faulty_book_replay_adapter.py b/tests/fixtures/faulty_book_replay_adapter.py index 4adc250..8525798 100644 --- a/tests/fixtures/faulty_book_replay_adapter.py +++ b/tests/fixtures/faulty_book_replay_adapter.py @@ -12,11 +12,11 @@ class FaultyBookReplayAdapter: - def __init__(self, config): + def __init__(self, config, engine_name="faulty-book-replay-test-adapter"): self._inner = ReferenceBookReplayAdapter(config) self._reorder = False self.metadata = EngineMetadata( - "faulty-book-replay-test-adapter", + engine_name, "1", "Python", ) diff --git a/tests/test_book_replay.py b/tests/test_book_replay.py index fbcf208..2d9528a 100644 --- a/tests/test_book_replay.py +++ b/tests/test_book_replay.py @@ -1,6 +1,7 @@ import io import json import sys +from decimal import Decimal, localcontext from pathlib import Path import pytest @@ -23,12 +24,164 @@ serve_book_replay_stdio, ) from tracebook.book_replay.cli import main +from tracebook.book_replay.model import Outcome, SimulatedFill ROOT = Path(__file__).parents[1] PROFILE_TRACE = ROOT / "src" / "tracebook" / "book_replay" / "fixtures" / f"{PROFILE_NAME}.jsonl" EXAMPLE_ADAPTER = ROOT / "examples" / "book_replay_adapter.py" +def _serve_test(factory, *messages, hello_overrides=None): + hello = dict(type="hello", protocol=PROTOCOL_NAME, protocol_version=PROTOCOL_VERSION) + hello.update(hello_overrides or {}) + source = io.StringIO("".join(json.dumps(item) + "\n" for item in (hello, *messages))) + sink = io.StringIO() + status = serve_book_replay_stdio(factory, source, sink) + return status, [json.loads(line) for line in sink.getvalue().splitlines()] + + +def test_server_close_failure_is_one_terminal_adapter_error(): + instances = [] + + class BrokenClose(ReferenceBookReplayAdapter): + def __init__(self, config): + super().__init__(config) + self.close_calls = 0 + instances.append(self) + + def close(self): + self.close_calls += 1 + raise ValueError("shutdown failed") + + status, messages = _serve_test(BrokenClose, dict(type="finish", event_count=0)) + assert status == 2 + assert [item["type"] for item in messages] == ["ready", "error"] + assert messages[-1]["code"] == "ADAPTER_ERROR" + assert instances[0].close_calls == 1 + + +@pytest.mark.parametrize("stage", ["factory", "apply", "snapshot"]) +@pytest.mark.parametrize("exception", [TypeError, ValueError]) +def test_server_adapter_exceptions_are_not_client_errors(stage, exception): + closed = [] + + class BrokenAdapter(ReferenceBookReplayAdapter): + def __init__(self, config): + if stage == "factory": + raise exception("adapter bug") + super().__init__(config) + + def apply(self, event, index): + if stage == "apply": + raise exception("adapter bug") + return super().apply(event, index) + + def snapshot(self): + raise exception("adapter bug") + + def close(self): + closed.append(True) + + request = ( + dict(type="event", index=1, event=_event().to_dict()) + if stage == "apply" + else dict(type="snapshot", index=0) + ) + status, messages = _serve_test(BrokenAdapter, request) + assert status == 2 + assert messages[-1]["code"] == "ADAPTER_ERROR" + assert len(closed) == (0 if stage == "factory" else 1) + + +@pytest.mark.parametrize("kind,field", [("snapshot", "index"), ("finish", "event_count")]) +@pytest.mark.parametrize("value", [None, False, True, 0.0, "0", -1, "missing"]) +def test_server_requires_integer_session_counters(kind, field, value): + request = {"type": kind} + if value != "missing": + request[field] = value + status, messages = _serve_test(ReferenceBookReplayAdapter, request) + assert status == 2 + assert [item["type"] for item in messages] == ["ready", "error"] + assert messages[-1]["code"] == "PROTOCOL_ERROR" + + +def test_server_invalid_payload_is_a_client_error(): + status, messages = _serve_test( + ReferenceBookReplayAdapter, dict(type="event", index=1, event=None) + ) + assert status == 2 + assert messages[-1]["code"] == "PROTOCOL_ERROR" + status, messages = _serve_test(ReferenceBookReplayAdapter, hello_overrides={"config": None}) + assert status == 2 + assert messages[0]["code"] == "PROTOCOL_ERROR" + + +@pytest.mark.parametrize("field,value", [("outcome", {}), ("fills", (object(),)), ("fills", None)]) +def test_invalid_in_process_observation_is_classified_as_protocol_failure(field, value): + class Malformed(ReferenceBookReplayAdapter): + def apply(self, event, index): + fields = dict( + index=index, + outcome=Outcome("applied"), + fills=(), + state_hash=self.snapshot().digest(), + order_count=0, + ) + fields[field] = value + return BookReplayObservation(**fields) + + report = run_book_replay([_event()], Malformed) + assert report.operational_failure + assert report.divergence.category == "protocol" + assert report.divergence.kind == "adapter_error" + + +@pytest.mark.parametrize("precision", [3, 28, 60]) +def test_probe_subtraction_and_canonical_values_are_exact_at_any_context_precision(precision): + tiny = "0.0000000000000000000000000000000000000001" + leftover = "0." + "9" * 40 + with localcontext() as context: + context.prec = precision + adapter = ReferenceBookReplayAdapter(BookReplayConfig()) + adapter.apply(_event(order_id=1, quantity=tiny), 1) + adapter.apply(_event(order_id=2, quantity="1"), 2) + before = adapter.snapshot() + observation = adapter.apply(_event("probe", quantity="1"), 3) + assert observation.fills == (SimulatedFill("100", tiny), SimulatedFill("100", leftover)) + assert adapter.snapshot() == before + with localcontext() as context: + context.prec = 100 + assert sum(Decimal(fill.quantity) for fill in observation.fills) == Decimal(1) + + +def test_external_timeout_overflow_is_a_public_validation_error(): + with pytest.raises(BookReplayError, match="positive finite"): + ExternalBookReplayAdapter(["never-started"], BookReplayConfig(), timeout_seconds=10**400) + + +def test_external_invalid_metadata_is_a_protocol_error_and_child_is_reaped(monkeypatch): + import subprocess + + processes = [] + popen = subprocess.Popen + + def capture_process(*args, **kwargs): + process = popen(*args, **kwargs) + processes.append(process) + return process + + monkeypatch.setattr(subprocess, "Popen", capture_process) + script = ( + "import json,sys; hello=json.loads(sys.stdin.readline()); " + "hello.update(type='ready',engine={}); print(json.dumps(hello),flush=True); " + "sys.stdin.read()" + ) + with pytest.raises(BookReplayProtocolError, match="invalid ready engine metadata"): + ExternalBookReplayAdapter([sys.executable, "-c", script], BookReplayConfig()) + assert len(processes) == 1 + assert processes[0].poll() is not None + + def _event(op="add", **overrides): values = { "op": op, diff --git a/tests/test_book_replay_artifacts.py b/tests/test_book_replay_artifacts.py index c229d66..2bb9e66 100644 --- a/tests/test_book_replay_artifacts.py +++ b/tests/test_book_replay_artifacts.py @@ -204,6 +204,23 @@ def fail_second(source, target, **kwargs): assert set(tmp_path.iterdir()) == {trace} +@pytest.mark.parametrize("command", ["run", "sample"]) +def test_cli_symlink_loop_is_controlled_before_candidate(tmp_path, monkeypatch, capsys, command): + trace = tmp_path / "trace.jsonl" + _trace(trace) + loop = tmp_path / "loop" + loop.symlink_to(loop) + _forbid_candidate(monkeypatch) + arguments = ( + ["sample", str(loop)] + if command == "sample" + else _command("run", trace, loop / "report.json", tmp_path / "unused") + ) + assert cli.main(arguments) == 2 + assert "Traceback" not in capsys.readouterr().err + assert set(tmp_path.iterdir()) == {trace, loop} + + def test_late_destination_creation_is_never_overwritten(tmp_path, monkeypatch): trace, report = tmp_path / "trace.jsonl", tmp_path / "report.json" _trace(trace) @@ -314,10 +331,65 @@ def interrupt_after_link(source, target, **kwargs): assert set(tmp_path.iterdir()) == {trace} +@pytest.mark.skipif(os.geteuid() == 0, reason="root can deliberately bypass directory permissions") +def test_stage_entry_cannot_be_replaced_between_validation_and_link(tmp_path, monkeypatch): + report = tmp_path / "report.json" + link = os.link + + def replace_stage(source, target, **kwargs): + # The old implementation allowed this unlink, then linked the foreign + # replacement and left it at report.json after its failed validation. + os.unlink(source, dir_fd=kwargs["src_dir_fd"]) + descriptor = os.open( + source, os.O_WRONLY | os.O_CREAT | os.O_EXCL, dir_fd=kwargs["src_dir_fd"] + ) + os.write(descriptor, b"foreign bytes") + os.close(descriptor) + link(source, target, **kwargs) + + monkeypatch.setattr(artifacts.os, "link", replace_stage) + monkeypatch.setattr(artifacts.os, "supports_dir_fd", os.supports_dir_fd | {replace_stage}) + with artifacts.reserve_outputs(str(report)) as outputs: + with pytest.raises(PermissionError): + artifacts.publish_outputs([(outputs[str(report)], b"owned bytes")]) + assert not report.exists() + assert list(tmp_path.iterdir()) == [] + + +def test_replacing_stage_directory_path_cannot_change_published_inode(tmp_path, monkeypatch): + report = tmp_path / "report.json" + link = os.link + with artifacts.reserve_outputs(str(report)) as outputs: + output = outputs[str(report)] + stage = tmp_path / output._stage_directory_name + moved = tmp_path / "moved-stage" + + def replace_directory(source, target, **kwargs): + # macOS requires write permission on a directory being renamed; + # emulate a writer that can rename it, then restore its protection. + stage.chmod(0o700) + stage.rename(moved) + moved.chmod(0o500) + stage.mkdir() + (stage / source).write_bytes(b"foreign replacement") + link(source, target, **kwargs) + + monkeypatch.setattr(artifacts.os, "link", replace_directory) + artifacts.publish_outputs([(output, b"owned bytes")]) + assert report.read_bytes() == b"owned bytes" + assert (stage / output._stage_name).read_bytes() == b"foreign replacement" + assert list(moved.iterdir()) == [] + + def test_cleanup_failure_still_closes_all_descriptors_and_other_sidecars(tmp_path, monkeypatch): reservation = artifacts.OutputReservation(tmp_path / "report.json") reservation.__enter__() - descriptors = (reservation._stage_fd, reservation._lock_fd, reservation._parent_fd) + descriptors = ( + reservation._stage_fd, + reservation._lock_fd, + reservation._stage_directory_fd, + reservation._parent_fd, + ) unlink = os.unlink def fail_stage_cleanup(name, **kwargs): @@ -332,7 +404,8 @@ def fail_stage_cleanup(name, **kwargs): for descriptor in descriptors: with pytest.raises(OSError): os.fstat(descriptor) - assert {path.name for path in tmp_path.iterdir()} == {reservation._stage_name} + assert {path.name for path in tmp_path.iterdir()} == {reservation._stage_directory_name} + assert (tmp_path / reservation._stage_directory_name / reservation._stage_name).is_file() def test_trace_serialization_failure_precedes_any_artifact_write(tmp_path, monkeypatch): diff --git a/tests/test_book_replay_campaign.py b/tests/test_book_replay_campaign.py index d0f4c54..82a720f 100644 --- a/tests/test_book_replay_campaign.py +++ b/tests/test_book_replay_campaign.py @@ -3,15 +3,12 @@ from pathlib import Path import pytest +from tests.fixtures.faulty_book_replay_adapter import FaultyBookReplayAdapter from tracebook.book_replay import ( BOOK_REPLAY_CAPABILITIES, BookReplayError, BookReplayEvent, - BookReplayObservation, - BookReplaySnapshot, - BookReplayState, - EngineMetadata, ReferenceBookReplayAdapter, generate_book_replay_trace, measure_book_replay_coverage, @@ -25,39 +22,17 @@ FAULTY_ADAPTER = ROOT / "tests" / "fixtures" / "faulty_book_replay_adapter.py" -class _ReorderingAdapter: +class _ReorderingAdapter(FaultyBookReplayAdapter): def __init__(self, config): - self._inner = ReferenceBookReplayAdapter(config) - self._reorder = False - self.metadata = EngineMetadata("reordering-test-adapter", "1", "Python") - - def apply(self, event, index): - observation = self._inner.apply(event, index) - if event.op == "update" and event.order_id == 1: - self._reorder = True - state = self.snapshot() - return BookReplayObservation( - index, - observation.outcome, - observation.fills, - state.digest(), - state.order_count, - ) - - def snapshot(self): - state = self._inner.snapshot() - if not self._reorder: - return state - books = [] - for book in state.books: - bids = list(book.bids) - if book.symbol == "TEST" and len(bids) >= 2: - bids[0], bids[1] = bids[1], bids[0] - books.append(BookReplaySnapshot(book.symbol, tuple(bids), book.asks)) - return BookReplayState(tuple(books)) - - def close(self): - self._inner.close() + super().__init__(config, engine_name="reordering-test-adapter") + + +def test_side_only_update_does_not_claim_price_relocation_coverage(): + add = BookReplayEvent("add", "TEST", 1, "BUY", "100", "1") + side_change = BookReplayEvent("update", "TEST", 1, "SELL", "100", "1") + price_change = BookReplayEvent("update", "TEST", 1, "SELL", "101", "1") + assert "price-relocation" not in measure_book_replay_coverage([[add, side_change]]).covered + assert "price-relocation" in measure_book_replay_coverage([[add, price_change]]).covered def test_generator_is_deterministic_and_scaffold_covers_every_capability(): diff --git a/tests/test_distribution_privacy.py b/tests/test_distribution_privacy.py index 509578e..c8bbec9 100644 --- a/tests/test_distribution_privacy.py +++ b/tests/test_distribution_privacy.py @@ -8,6 +8,7 @@ import sys import tarfile import zipfile +import zlib from pathlib import Path import pytest @@ -15,6 +16,24 @@ from tools.verify_distribution_privacy import PrivacyError, main, verify_artifact ROOT = Path(__file__).resolve().parents[1] + + +def test_privacy_gate_handles_corrupt_deflated_inventory(tmp_path, capsys): + artifact = tmp_path / "corrupt.whl" + with zipfile.ZipFile(artifact, "w", compression=zipfile.ZIP_DEFLATED) as archive: + archive.writestr("fixture.egg-info/SOURCES.txt", "pyproject.toml\n") + # Preserve the ZIP index, but corrupt the compressed block's type bits. + data = bytearray(artifact.read_bytes()) + filename_length = int.from_bytes(data[26:28], "little") + extra_length = int.from_bytes(data[28:30], "little") + data[30 + filename_length + extra_length] = 7 + artifact.write_bytes(data) + with pytest.raises(zlib.error): + verify_artifact(artifact) + assert main([str(artifact)]) == 1 + assert "distribution privacy check failed" in capsys.readouterr().err + + PRIVATE_PATHS = ( "experiments/private/agent-qualification-v2/gold.json", "experiments/private/agent-qualification-v2/execution/controller.py", diff --git a/tests/test_integration_workflow_coverage.py b/tests/test_integration_workflow_coverage.py index f6d2971..eccf8ec 100644 --- a/tests/test_integration_workflow_coverage.py +++ b/tests/test_integration_workflow_coverage.py @@ -17,18 +17,79 @@ } -def _pull_request_paths(workflow): - source = (ROOT / ".github" / "workflows" / f"{workflow}.yml").read_text(encoding="utf-8") - # Read this deliberately simple YAML sequence without adding PyYAML to the - # dependency-free package's test requirements. Do not search job bodies, - # where a mentioned path cannot cause the workflow to run. - match = re.search(r"^ pull_request:\n paths:\n((?: - .+\n)+)", source, re.M) - assert match is not None, f"{workflow} must declare pull_request.paths" - patterns = [ast.literal_eval(line.removeprefix(" - ")) for line in match[1].splitlines()] +def _mapping_block(lines, key): + """Read a block in our workflows' block-style YAML subset, not job text.""" + lines = [line for line in lines if line.strip() and not line.lstrip().startswith("#")] + assert lines, f"missing YAML mapping: {key}" + base = min(len(line) - len(line.lstrip()) for line in lines) + for index, line in enumerate(lines): + indent = len(line) - len(line.lstrip()) + if indent != base or not re.fullmatch(rf"['\"]?{key}['\"]?:\s*(?:#.*)?", line.strip()): + continue + block = [] + for child in lines[index + 1 :]: + if len(child) - len(child.lstrip()) <= indent: + break + block.append(child) + return block + raise AssertionError(f"missing YAML mapping: {key}") + + +def _parse_pull_request_paths(source): + # Intentionally support block mappings and quoted positive path sequences + # used here. Unsupported YAML fails closed, without a new runtime dependency. + block = source.splitlines() + for key in ("on", "pull_request", "paths"): + block = _mapping_block(block, key) + assert block and all(line.strip().startswith("- ") for line in block) + patterns = [ast.literal_eval(line.strip().removeprefix("- ")) for line in block] assert all(isinstance(pattern, str) and not pattern.startswith("!") for pattern in patterns) return patterns +def _pull_request_paths(workflow): + source = (ROOT / ".github" / "workflows" / f"{workflow}.yml").read_text(encoding="utf-8") + return _parse_pull_request_paths(source) + + +@pytest.mark.parametrize("indent", [2, 4]) +def test_path_reader_allows_comments_blank_lines_and_other_trigger_keys(indent): + space = " " * indent + source = "\n".join( + [ + "on:", + f"{space}pull_request: # keep native proofs attached", + f"{space * 2}branches:", + f"{space * 3}- 'main'", + "", + f"{space * 2}# runtime inputs", + f"{space * 2}paths:", + f"{space * 3}- 'src/**' # reference", + "", + f"{space * 3}# shared crate", + f'{space * 3}- "integrations/**"', + f"{space}push:", + f"{space * 2}paths:", + f"{space * 3}- 'ignored/**'", + "jobs:", + f"{space}pull_request:", + f"{space * 2}paths:", + f"{space * 3}- 'wrong/**'", + ] + ) + assert _parse_pull_request_paths(source) == ["src/**", "integrations/**"] + + +def test_path_reader_cannot_use_paths_from_jobs_or_another_trigger(): + for source in ( + "jobs:\n pull_request:\n paths:\n - 'src/**'", + "on:\n push:\n paths:\n - 'src/**'\n" + " pull_request:\n branches:\n - 'main'", + ): + with pytest.raises(AssertionError, match="missing YAML mapping"): + _parse_pull_request_paths(source) + + def _matches(path, pattern): # The checked workflows use only literal paths and positive * / ** globs. # Unlike fnmatch, a single * must not match a directory separator. diff --git a/tools/verify_distribution_privacy.py b/tools/verify_distribution_privacy.py index 79694dd..f67fadf 100644 --- a/tools/verify_distribution_privacy.py +++ b/tools/verify_distribution_privacy.py @@ -12,6 +12,7 @@ import sys import tarfile import zipfile +import zlib from pathlib import Path, PurePosixPath, PureWindowsPath from typing import Sequence @@ -112,7 +113,7 @@ def main(argv: Sequence[str] | None = None) -> int: try: for artifact in args.artifacts: verify_artifact(artifact) - except (PrivacyError, OSError, tarfile.TarError, zipfile.BadZipFile) as error: + except (PrivacyError, OSError, tarfile.TarError, zipfile.BadZipFile, zlib.error) as error: print(f"distribution privacy check failed: {error}", file=sys.stderr) return 1 print(f"Distribution privacy verified for {len(args.artifacts)} artifacts.") From dc03c210f0a2b212f16cc1c92bd2917a1985d735 Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Sat, 5 Sep 2026 02:49:37 -0400 Subject: [PATCH 3/6] Fix remaining release-code review follow-ups --- CHANGELOG.md | 3 ++ docs/pr-84-review-disposition.md | 32 ++++++++++++- integrations/rust_protocol/src/quantity.rs | 17 ++++++- src/tracebook/book_replay/artifacts.py | 46 +++++++++++++++---- src/tracebook/book_replay/cli.py | 10 ++-- src/tracebook/book_replay/protocol.py | 2 +- tests/test_book_replay.py | 24 ++++++++-- tests/test_book_replay_artifacts.py | 53 ++++++++++++++++++++++ 8 files changed, 168 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c4ea5f..6cd092a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ The project follows [Keep a Changelog](https://keepachangelog.com/) conventions. 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. +- Fixed four PR #84 follow-ups: clean owned staging directories when opening + fails, classify adapter broken-pipe failures correctly, distinguish zero + quantities from precision loss, and handle symlink loops in CLI input paths. - Addressed the release-code findings from PR #84: fail closed on L3 shutdown and malformed protocol values, preserve exact decimal probe arithmetic, protect staged artifacts against ordinary source-path replacement, reject diff --git a/docs/pr-84-review-disposition.md b/docs/pr-84-review-disposition.md index 0547b6a..e0a95f4 100644 --- a/docs/pr-84-review-disposition.md +++ b/docs/pr-84-review-disposition.md @@ -1,7 +1,8 @@ # PR #84 Review Disposition This records the 30 comments in the initial automated review of -[PR #84](https://github.com/Taz33m/tracebook/pull/84), against `0c98e18`. +[PR #84](https://github.com/Taz33m/tracebook/pull/84), against `0c98e18`, +and the four follow-up comments against `e65416a`. It is a disposition of that review, not release approval or a new experiment result. Source and regression tests, not the review's severity labels, determine the implemented changes. @@ -45,6 +46,25 @@ Two limits matter when interpreting these fixes: not overwrite destinations, and rollback preserves competing files. The directory-permission test is intentionally skipped when running as root. +## Follow-up release-code fixes + +All four follow-up findings are addressed without changing positive-value +normalization, matching semantics, or frozen research files. + +| Comment ID | Change | Regression / verification surface | +| --- | --- | --- | +| 3939212113 | Retain the staging directory's identity before opening it, remove only a matching entry on setup failure, and reject an opened replacement before writing or changing its permissions. | `test_stage_directory_setup_failure_cleans_only_owned_entries`: failed open, competing replacement, and descriptor closure | +| 3939212117 | Reserve `PROTOCOL_ERROR` for explicit client validation failures; adapter `BrokenPipeError` follows the adapter-error path, including shutdown. | Close/factory/apply/snapshot regressions plus a broken output pipe; close remains single-shot | +| 3939212124 | Diagnose an exact zero as a nonpositive quantity; retain the separate precision-loss error for positive quantities that round to zero. | Shared Rust zero-diagnostic test at 0, 12, and 18 places, plus existing positive rounding tests | +| 3939212131 | Use the same narrow path-resolution guard for CLI inputs and distinct-path checks. | Actual input symlink loops for both `run` and `minimize`, including Python 3.10's `RuntimeError` behavior | + +The still-open duplicate-fixture comment, `3939089005`, is already addressed +by `e65416a`: `tests/test_book_replay_campaign.py` imports the shared +`FaultyBookReplayAdapter`. Its small `_ReorderingAdapter` subclass only supplies +the historical engine name; it contains no fault, snapshot, or shutdown logic. +Existing campaign and reduced-failure identities remain covered by regression +tests. This is a stale release-code conversation, not a deferred research issue. + ## Frozen research findings — open, not silently patched These 13 findings are in the historical/hash-bound research harness. The @@ -78,7 +98,7 @@ belong in a provider request or this public document. ## Release gate -Local verification of the fixes passed: Python 3.13 had 651 passing tests, +Local verification of the initial fixes passed: Python 3.13 had 651 passing tests, one skip, and 82.38% coverage; the focused Python 3.10 regressions passed too. Formatting, lint, type checking, static security checks, pinned Rust 1.88/Go 1.23.5 checks, distribution privacy, and sdist/wheel agreement passed. @@ -88,6 +108,14 @@ the Nautilus 2,500-event positive campaign/three-event negative control retained their expected identities and reduced trace. These are local checks; consult the PR for the latest remote CI and review state. +Follow-up verification passed separately: Python 3.13 had 661 passing tests, +one skip, and 82.38% coverage. The focused L3 protocol, artifact, and campaign +suite passed all 114 tests on Python 3.10. All 33 Rust tests across the shared +protocol and both adapters passed with Rust 1.88, along with clippy and rustfmt. +Python formatting, lint, type checking, static security checks, and compilation +also passed. This follow-up did not recollect provider runs or rewrite retained +qualification artifacts; the initial verification above remains historical. + Keep the research conversations open until their disposition is agreed. Passing release tests does not justify dismissing those comments, bypassing repository protections, merging the PR, or publishing a tag. The previous maintainer diff --git a/integrations/rust_protocol/src/quantity.rs b/integrations/rust_protocol/src/quantity.rs index 41009b8..25ab00d 100644 --- a/integrations/rust_protocol/src/quantity.rs +++ b/integrations/rust_protocol/src/quantity.rs @@ -61,6 +61,9 @@ impl QuantityEncoding { } pub fn format(&self, units: u64) -> Result { + if units == 0 { + return Err("quantity must be positive".to_string()); + } let places = self.output_decimal_places.min(NATIVE_DECIMAL_PLACES); let divisor = 10_u64.pow(NATIVE_DECIMAL_PLACES - places); let mut rounded = units / divisor; @@ -200,6 +203,18 @@ mod tests { .contains("cannot be represented") ); } - assert!(QuantityEncoding::new(12).unwrap().format(0).is_err()); + } + + #[test] + fn zero_observations_report_nonpositive_quantity_not_precision_loss() { + for places in [0, 12, 18] { + assert_eq!( + QuantityEncoding::new(places) + .unwrap() + .format(0) + .unwrap_err(), + "quantity must be positive" + ); + } } } diff --git a/src/tracebook/book_replay/artifacts.py b/src/tracebook/book_replay/artifacts.py index 12f2eea..9fdc5c7 100644 --- a/src/tracebook/book_replay/artifacts.py +++ b/src/tracebook/book_replay/artifacts.py @@ -37,6 +37,7 @@ def __init__(self, destination: str | Path) -> None: self._stage_name = "payload" self._parent_fd: Optional[int] = None self._stage_directory_fd: Optional[int] = None + self._stage_directory_identity: Optional[tuple[int, int]] = None self._lock_fd: Optional[int] = None self._stage_fd: Optional[int] = None self._published = False @@ -56,11 +57,23 @@ def __enter__(self) -> "OutputReservation": flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0) self._lock_fd = os.open(self._lock_name, flags, 0o600, dir_fd=self._parent_fd) os.mkdir(self._stage_directory_name, mode=0o700, dir_fd=self._parent_fd) - self._stage_directory_fd = os.open( + # Retain the identity even if opening the newly created directory + # fails. Cleanup must not remove a replacement at the same name. + self._stage_directory_identity = _identity( + os.stat(self._stage_directory_name, dir_fd=self._parent_fd, follow_symlinks=False) + ) + stage_directory_fd = os.open( self._stage_directory_name, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0), dir_fd=self._parent_fd, ) + try: + if _identity(os.fstat(stage_directory_fd)) != self._stage_directory_identity: + raise BookReplayError(f"book-replay output reservation changed: {self.target}") + except BaseException: + os.close(stage_directory_fd) + raise + self._stage_directory_fd = stage_directory_fd self._stage_fd = os.open( self._stage_name, flags, 0o400, dir_fd=self._stage_directory_fd ) @@ -120,6 +133,21 @@ def validate(self) -> None: raise BookReplayError(f"book-replay output reservation changed: {self.target}") self._require_absent() + def _owns_stage_directory(self) -> bool: + if self._parent_fd is None or self._stage_directory_identity is None: + return False + try: + return ( + _identity( + os.stat( + self._stage_directory_name, dir_fd=self._parent_fd, follow_symlinks=False + ) + ) + == self._stage_directory_identity + ) + except OSError: + return False + def _same_parent(self) -> bool: if self._parent_fd is None: return False @@ -190,18 +218,18 @@ def close(self) -> None: except OSError as exc: error = error or exc self._stage_fd = self._lock_fd = None + try: + if self._owns_stage_directory(): + os.rmdir(self._stage_directory_name, dir_fd=self._parent_fd) + except OSError as exc: + error = error or exc + self._stage_directory_identity = None if self._stage_directory_fd is not None: try: - if self._owns_entry(self._stage_directory_name, self._stage_directory_fd): - os.rmdir(self._stage_directory_name, dir_fd=self._parent_fd) + os.close(self._stage_directory_fd) except OSError as exc: error = error or exc - finally: - try: - os.close(self._stage_directory_fd) - except OSError as exc: - error = error or exc - self._stage_directory_fd = None + self._stage_directory_fd = None if self._parent_fd is not None: try: os.close(self._parent_fd) diff --git a/src/tracebook/book_replay/cli.py b/src/tracebook/book_replay/cli.py index 60ae764..127d609 100644 --- a/src/tracebook/book_replay/cli.py +++ b/src/tracebook/book_replay/cli.py @@ -124,11 +124,15 @@ def _emit( print(f"Report written: {Path(output)}") -def _require_distinct_paths(*paths: Optional[str]) -> None: +def _resolve_path(path: str) -> Path: try: - resolved = [Path(path).expanduser().resolve() for path in paths if path is not None] + return Path(path).expanduser().resolve() except RuntimeError as exc: raise BookReplayError(f"cannot resolve book-replay path: {exc}") from exc + + +def _require_distinct_paths(*paths: Optional[str]) -> None: + resolved = [_resolve_path(path) for path in paths if path is not None] if len(resolved) != len(set(resolved)) or any( left in right.parents or right in left.parents for index, left in enumerate(resolved) @@ -171,7 +175,7 @@ def main(argv: Optional[List[str]] = None) -> int: return 0 return 2 if campaign.failure.minimization.report.operational_failure else 1 - events_path = Path(args.events).expanduser().resolve() + events_path = _resolve_path(args.events) events_output = args.events_output if args.command == "minimize" else None _require_distinct_paths(str(events_path), args.output, events_output) with reserve_outputs(args.output, events_output) as outputs: diff --git a/src/tracebook/book_replay/protocol.py b/src/tracebook/book_replay/protocol.py index 2fa16e4..efba6b7 100644 --- a/src/tracebook/book_replay/protocol.py +++ b/src/tracebook/book_replay/protocol.py @@ -134,7 +134,7 @@ def serve_book_replay_stdio( else: raise _RequestError(f"unsupported protocol message type: {message_type!r}") raise _RequestError("protocol ended before finish") - except (_RequestError, BrokenPipeError) as exc: + except _RequestError as exc: try: _write_message(sink, {"type": "error", "code": "PROTOCOL_ERROR", "message": str(exc)}) except BrokenPipeError: diff --git a/tests/test_book_replay.py b/tests/test_book_replay.py index 2d9528a..065787b 100644 --- a/tests/test_book_replay.py +++ b/tests/test_book_replay.py @@ -40,7 +40,8 @@ def _serve_test(factory, *messages, hello_overrides=None): return status, [json.loads(line) for line in sink.getvalue().splitlines()] -def test_server_close_failure_is_one_terminal_adapter_error(): +@pytest.mark.parametrize("exception", [ValueError, BrokenPipeError]) +def test_server_close_failure_is_one_terminal_adapter_error(exception): instances = [] class BrokenClose(ReferenceBookReplayAdapter): @@ -51,7 +52,7 @@ def __init__(self, config): def close(self): self.close_calls += 1 - raise ValueError("shutdown failed") + raise exception("shutdown failed") status, messages = _serve_test(BrokenClose, dict(type="finish", event_count=0)) assert status == 2 @@ -61,7 +62,7 @@ def close(self): @pytest.mark.parametrize("stage", ["factory", "apply", "snapshot"]) -@pytest.mark.parametrize("exception", [TypeError, ValueError]) +@pytest.mark.parametrize("exception", [TypeError, ValueError, BrokenPipeError]) def test_server_adapter_exceptions_are_not_client_errors(stage, exception): closed = [] @@ -93,6 +94,23 @@ def close(self): assert len(closed) == (0 if stage == "factory" else 1) +def test_server_broken_output_pipe_returns_failure_and_closes_adapter_once(): + closed = [] + + class Adapter(ReferenceBookReplayAdapter): + def close(self): + closed.append(True) + + class BrokenSink(io.StringIO): + def write(self, value): + raise BrokenPipeError("output pipe closed") + + hello = dict(type="hello", protocol=PROTOCOL_NAME, protocol_version=PROTOCOL_VERSION) + source = io.StringIO(json.dumps(hello) + "\n") + assert serve_book_replay_stdio(Adapter, source, BrokenSink()) == 2 + assert closed == [True] + + @pytest.mark.parametrize("kind,field", [("snapshot", "index"), ("finish", "event_count")]) @pytest.mark.parametrize("value", [None, False, True, 0.0, "0", -1, "missing"]) def test_server_requires_integer_session_counters(kind, field, value): diff --git a/tests/test_book_replay_artifacts.py b/tests/test_book_replay_artifacts.py index 2bb9e66..532872f 100644 --- a/tests/test_book_replay_artifacts.py +++ b/tests/test_book_replay_artifacts.py @@ -221,6 +221,22 @@ def test_cli_symlink_loop_is_controlled_before_candidate(tmp_path, monkeypatch, assert set(tmp_path.iterdir()) == {trace, loop} +@pytest.mark.parametrize("command", ["run", "minimize"]) +def test_cli_input_symlink_loop_is_controlled_before_candidate( + tmp_path, monkeypatch, capsys, command +): + loop = tmp_path / "loop" + loop.symlink_to(loop) + _forbid_candidate(monkeypatch) + + arguments = _command(command, loop, tmp_path / "report.json", tmp_path / "reduced.jsonl") + assert cli.main(arguments) == 2 + error = capsys.readouterr().err + assert error.startswith("Error:") + assert "Traceback" not in error + assert set(tmp_path.iterdir()) == {loop} + + def test_late_destination_creation_is_never_overwritten(tmp_path, monkeypatch): trace, report = tmp_path / "trace.jsonl", tmp_path / "report.json" _trace(trace) @@ -381,6 +397,43 @@ def replace_directory(source, target, **kwargs): assert list(moved.iterdir()) == [] +@pytest.mark.parametrize( + "replace_directory,fail_open", [(False, True), (True, True), (True, False)] +) +def test_stage_directory_setup_failure_cleans_only_owned_entries( + tmp_path, monkeypatch, replace_directory, fail_open +): + reservation = artifacts.OutputReservation(tmp_path / "report.json") + stage = tmp_path / reservation._stage_directory_name + moved = tmp_path / "moved-stage" + open_descriptor = os.open + descriptors = [] + + def inject_stage_open(path, *args, **kwargs): + if path == reservation._stage_directory_name: + if replace_directory: + stage.rename(moved) + stage.mkdir(mode=0o500) + if fail_open: + raise OSError("injected stage directory open failure") + descriptor = open_descriptor(path, *args, **kwargs) + descriptors.append(descriptor) + return descriptor + + monkeypatch.setattr(artifacts.os, "open", inject_stage_open) + monkeypatch.setattr(artifacts.os, "supports_dir_fd", os.supports_dir_fd | {inject_stage_open}) + error = OSError if fail_open else artifacts.BookReplayError + with pytest.raises(error, match="open failure" if fail_open else "reservation changed"): + reservation.__enter__() + for descriptor in descriptors: + with pytest.raises(OSError): + os.fstat(descriptor) + assert set(tmp_path.iterdir()) == ({stage, moved} if replace_directory else set()) + if replace_directory: + assert list(stage.iterdir()) == list(moved.iterdir()) == [] + assert stage.stat().st_mode & 0o777 == 0o500 + + def test_cleanup_failure_still_closes_all_descriptors_and_other_sidecars(tmp_path, monkeypatch): reservation = artifacts.OutputReservation(tmp_path / "report.json") reservation.__enter__() From 34047004e9031484b1ee9700f93967d4ee25acc9 Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Sat, 5 Sep 2026 04:15:37 -0400 Subject: [PATCH 4/6] Record agreed deferral of frozen research findings to issue 85 --- docs/pr-84-review-disposition.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/pr-84-review-disposition.md b/docs/pr-84-review-disposition.md index e0a95f4..ea94fb3 100644 --- a/docs/pr-84-review-disposition.md +++ b/docs/pr-84-review-disposition.md @@ -58,19 +58,25 @@ normalization, matching semantics, or frozen research files. | 3939212124 | Diagnose an exact zero as a nonpositive quantity; retain the separate precision-loss error for positive quantities that round to zero. | Shared Rust zero-diagnostic test at 0, 12, and 18 places, plus existing positive rounding tests | | 3939212131 | Use the same narrow path-resolution guard for CLI inputs and distinct-path checks. | Actual input symlink loops for both `run` and `minimize`, including Python 3.10's `RuntimeError` behavior | -The still-open duplicate-fixture comment, `3939089005`, is already addressed +The duplicate-fixture comment, `3939089005`, was already addressed by `e65416a`: `tests/test_book_replay_campaign.py` imports the shared `FaultyBookReplayAdapter`. Its small `_ReorderingAdapter` subclass only supplies the historical engine name; it contains no fault, snapshot, or shutdown logic. Existing campaign and reduced-failure identities remain covered by regression -tests. This is a stale release-code conversation, not a deferred research issue. +tests. Its stale release-code conversation was resolved with source and test +evidence; it is not a deferred research issue. -## Frozen research findings — open, not silently patched +## Frozen research findings — explicitly deferred, not fixed These 13 findings are in the historical/hash-bound research harness. The accepted scope leaves that code, frozen inputs, evaluator material, and retained -results unchanged. They remain open pending a separate research disposition; -the release fixes above do not resolve them. +results unchanged. On 2026-09-05 the maintainer explicitly authorized transferring +all 13 findings to [follow-up issue #85](https://github.com/Taz33m/tracebook/issues/85) +so this release-code PR can merge after its remaining fix and checks. That issue +preserves every original review link and an unchecked item for each finding. +The PR conversations are resolved only as an agreed transfer: these findings +remain open in the follow-up, not fixed or dismissed as false positives. The +release fixes above do not resolve the underlying research risks. | Comment ID | Reported issue | Required next decision/check | | --- | --- | --- | @@ -116,7 +122,10 @@ Python formatting, lint, type checking, static security checks, and compilation also passed. This follow-up did not recollect provider runs or rewrite retained qualification artifacts; the initial verification above remains historical. -Keep the research conversations open until their disposition is agreed. Passing -release tests does not justify dismissing those comments, bypassing repository -protections, merging the PR, or publishing a tag. The previous maintainer -invitation and its immutable source/wheel references remain unchanged. +The agreed transfer to issue #85 supersedes the earlier instruction to keep +these 13 PR conversations open pending a disposition. Keep the follow-up issue +open until its evidence-backed completion criteria are reviewed. Passing release +tests does not dismiss those risks or justify bypassing repository protections. +The remaining release-code review and required checks must pass before the +authorized merge; no tag or package publication is authorized. The previous +maintainer invitation and its immutable source/wheel references remain unchanged. From e2b8a39b665ff0a4129e5b189f5d559ab182502f Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Sat, 5 Sep 2026 04:25:26 -0400 Subject: [PATCH 5/6] Report unverified staging residue without unsafe cleanup --- CHANGELOG.md | 3 + docs/book-replay-conformance.md | 16 ++++ docs/pr-84-review-disposition.md | 31 ++++++- src/tracebook/book_replay/artifacts.py | 19 ++++- tests/test_book_replay_artifacts.py | 108 +++++++++++++++++++++++++ 5 files changed, 173 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6cd092a..2f99ac7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ The project follows [Keep a Changelog](https://keepachangelog.com/) conventions. 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. - Fixed four PR #84 follow-ups: clean owned staging directories when opening fails, classify adapter broken-pipe failures correctly, distinguish zero quantities from precision loss, and handle symlink loops in CLI input paths. diff --git a/docs/book-replay-conformance.md b/docs/book-replay-conformance.md index 59d46bc..00896db 100644 --- a/docs/book-replay-conformance.md +++ b/docs/book-replay-conformance.md @@ -118,6 +118,22 @@ leave sidecars. After a forced stop or cleanup failure, retain the artifacts and use fresh output names for a new invocation; do not remove a live process's reservations. +If the first metadata read after creating a staging directory fails, the +command exits `2` before starting a candidate. It explicitly reports that +ownership could not be verified, automatic directory cleanup was skipped, and +the original path of possible staging residue. That entry is left untouched: +it may be the empty directory from this attempt, a competing replacement, or +already moved/deleted. Owned lock cleanup is still attempted and opened +descriptors are closed. This is a reported cleanup limitation, not a guarantee +that every failed setup leaves no sidecars. + +For recovery, first ensure no process is using the output directory. Inspect +the reported path and any parent-directory moves; the diagnostic is not proof +of ownership. Remove only an empty directory independently confirmed to belong +to the failed attempt, using non-recursive removal. Leave uncertain entries, +symlinks, other writers' data, and nonempty directories untouched, and use fresh +output names. Do not run a blanket cleanup of `.tracebook-stage-*` paths. + Staged payloads live in owner-only, read-only directories and publication uses the open directory descriptor, so replacing a staging directory's parent entry cannot substitute another payload. Published files are owner-readable. This diff --git a/docs/pr-84-review-disposition.md b/docs/pr-84-review-disposition.md index ea94fb3..dd74df3 100644 --- a/docs/pr-84-review-disposition.md +++ b/docs/pr-84-review-disposition.md @@ -2,7 +2,8 @@ This records the 30 comments in the initial automated review of [PR #84](https://github.com/Taz33m/tracebook/pull/84), against `0c98e18`, -and the four follow-up comments against `e65416a`. +the four follow-up comments against `e65416a`, and the cleanup follow-up +against `f035e0c`. It is a disposition of that review, not release approval or a new experiment result. Source and regression tests, not the review's severity labels, determine the implemented changes. @@ -66,6 +67,28 @@ Existing campaign and reduced-failure identities remain covered by regression tests. Its stale release-code conversation was resolved with source and test evidence; it is not a deferred research issue. +## Initial staging identity failure — agreed conservative handling + +Comment [3939788196](https://github.com/Taz33m/tracebook/pull/84#discussion_r3939788196) +correctly identifies a possible empty-directory residue when the first `stat` +after `mkdir` fails. With neither an identity nor a directory descriptor, the +runner cannot safely distinguish that entry from a competing replacement. + +The maintainer explicitly approved retaining an unverified entry, reporting +an explicit error, and adding tests/documentation before merge. The runner now +raises `BookReplayError` with the original possible-residue path and the reason +automatic directory cleanup was skipped. CLI commands exit `2` before candidate +execution, retain the underlying exception as the cause, and still attempt +owned-lock cleanup and close open descriptors. Known-ownership cleanup remains +unchanged. This addresses silent residue through an agreed, observable failure +contract; it does not claim automatic removal when ownership is unknown. + +Regression tests cover the original empty directory, empty and populated +competing directories, a replacement symlink, a moved-away entry, descriptor +closure, and all four CLI commands. Recovery instructions in +[book-replay conformance](book-replay-conformance.md) require independently +verified ownership and prohibit blanket or recursive removal of uncertain paths. + ## Frozen research findings — explicitly deferred, not fixed These 13 findings are in the historical/hash-bound research harness. The @@ -122,6 +145,12 @@ Python formatting, lint, type checking, static security checks, and compilation also passed. This follow-up did not recollect provider runs or rewrite retained qualification artifacts; the initial verification above remains historical. +The final initial-identity error handling passed 670 Python 3.13 tests with one +skip and 82.39% coverage, plus all 123 focused L3 tests on Python 3.10. Its nine +new regression cases failed before the change and passed afterward. Formatting, +lint, type checking, static security checks, compilation, and whitespace checks +passed. No frozen research files or retained qualification artifacts changed. + The agreed transfer to issue #85 supersedes the earlier instruction to keep these 13 PR conversations open pending a disposition. Keep the follow-up issue open until its evidence-backed completion criteria are reviewed. Passing release diff --git a/src/tracebook/book_replay/artifacts.py b/src/tracebook/book_replay/artifacts.py index 9fdc5c7..376ffec 100644 --- a/src/tracebook/book_replay/artifacts.py +++ b/src/tracebook/book_replay/artifacts.py @@ -59,9 +59,22 @@ def __enter__(self) -> "OutputReservation": os.mkdir(self._stage_directory_name, mode=0o700, dir_fd=self._parent_fd) # Retain the identity even if opening the newly created directory # fails. Cleanup must not remove a replacement at the same name. - self._stage_directory_identity = _identity( - os.stat(self._stage_directory_name, dir_fd=self._parent_fd, follow_symlinks=False) - ) + try: + self._stage_directory_identity = _identity( + os.stat( + self._stage_directory_name, dir_fd=self._parent_fd, follow_symlinks=False + ) + ) + except OSError as exc: + # mkdir gives no inode/descriptor. Do not guess ownership or + # remove a replacement when this first identity read fails. + residue = self.target.parent / self._stage_directory_name + raise BookReplayError( + "staging directory ownership could not be verified; " + "automatic directory cleanup skipped; " + f"possible staging residue at original path {str(residue)!r}. " + f"Inspect its location and ownership before manual cleanup: {exc}" + ) from exc stage_directory_fd = os.open( self._stage_directory_name, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0), diff --git a/tests/test_book_replay_artifacts.py b/tests/test_book_replay_artifacts.py index 532872f..1461a8c 100644 --- a/tests/test_book_replay_artifacts.py +++ b/tests/test_book_replay_artifacts.py @@ -434,6 +434,114 @@ def inject_stage_open(path, *args, **kwargs): assert stage.stat().st_mode & 0o777 == 0o500 +@pytest.mark.parametrize("replacement", ["none", "empty", "populated", "symlink", "missing"]) +def test_initial_stage_stat_failure_reports_unverified_entry_without_removing_it( + tmp_path, monkeypatch, replacement +): + reservation = artifacts.OutputReservation(tmp_path / "report.json") + stage = tmp_path / reservation._stage_directory_name + moved = tmp_path / "moved-stage" + stat, open_descriptor = os.stat, os.open + descriptors = [] + failure = OSError("injected initial staging stat failure") + + def fail_stage_stat(path, *args, **kwargs): + if path == reservation._stage_directory_name: + if replacement != "none": + stage.rename(moved) + if replacement in ("empty", "populated"): + stage.mkdir() + if replacement == "populated": + (stage / "foreign").write_bytes(b"another writer's evidence") + stage.chmod(0o500) + elif replacement == "symlink": + stage.symlink_to(moved, target_is_directory=True) + raise failure + return stat(path, *args, **kwargs) + + def track_open(*args, **kwargs): + descriptor = open_descriptor(*args, **kwargs) + descriptors.append(descriptor) + return descriptor + + monkeypatch.setattr(artifacts.os, "stat", fail_stage_stat) + monkeypatch.setattr(artifacts.os, "open", track_open) + monkeypatch.setattr( + artifacts.os, "supports_dir_fd", os.supports_dir_fd | {fail_stage_stat, track_open} + ) + monkeypatch.setattr( + artifacts.os, "rmdir", lambda *_args, **_kwargs: pytest.fail("removing unverified entry") + ) + monkeypatch.setattr( + artifacts.os, "fchmod", lambda *_args: pytest.fail("changing unverified permissions") + ) + + with pytest.raises( + artifacts.BookReplayError, match="automatic directory cleanup skipped" + ) as caught: + reservation.__enter__() + assert caught.value.__cause__ is failure + assert repr(str(stage)) in str(caught.value) + assert "possible staging residue" in str(caught.value) + assert "ownership could not be verified" in str(caught.value) + assert len(descriptors) == 2 # Only the parent and lock were opened. + for descriptor in descriptors: + with pytest.raises(OSError): + os.fstat(descriptor) + expected = {stage} if replacement == "none" else {moved} + if replacement not in ("none", "missing"): + expected.add(stage) + assert set(tmp_path.iterdir()) == expected + if replacement in ("empty", "populated"): + assert stage.stat().st_mode & 0o777 == 0o500 + if replacement == "populated": + assert (stage / "foreign").read_bytes() == b"another writer's evidence" + elif replacement == "symlink": + assert stage.is_symlink() and stage.readlink() == moved + if moved.exists(): + assert list(moved.iterdir()) == [] + + +@pytest.mark.parametrize("command", ["run", "minimize", "campaign", "sample"]) +def test_cli_reports_initial_stage_stat_failure_before_candidate( + tmp_path, monkeypatch, capsys, command +): + trace = tmp_path / "trace.jsonl" + _trace(trace) + _forbid_candidate(monkeypatch) + stat = os.stat + stages = [] + + def fail_stage_stat(path, *args, **kwargs): + if isinstance(path, str) and path.startswith(".tracebook-stage-"): + stages.append(path) + raise OSError("injected initial staging stat failure") + return stat(path, *args, **kwargs) + + monkeypatch.setattr(artifacts.os, "stat", fail_stage_stat) + monkeypatch.setattr(artifacts.os, "supports_dir_fd", os.supports_dir_fd | {fail_stage_stat}) + arguments = ( + ["sample", str(tmp_path / "sample")] + if command == "sample" + else _command(command, trace, tmp_path / "report.json", tmp_path / "reduced.jsonl") + ) + assert cli.main(arguments) == 2 + output = capsys.readouterr() + assert output.out == "" + assert output.err.startswith("Error:") and "Traceback" not in output.err + assert "automatic directory cleanup skipped" in output.err + assert len(stages) == 1 + parent = tmp_path / "sample" if command == "sample" else tmp_path + stage = parent / stages[0] + assert repr(str(stage)) in output.err + assert stage.is_dir() and list(stage.iterdir()) == [] + if command == "sample": + assert set(parent.iterdir()) == {stage} + assert set(tmp_path.iterdir()) == {trace, parent} + else: + assert set(tmp_path.iterdir()) == {trace, stage} + + def test_cleanup_failure_still_closes_all_descriptors_and_other_sidecars(tmp_path, monkeypatch): reservation = artifacts.OutputReservation(tmp_path / "report.json") reservation.__enter__() From b0f2403f7f337c8703b6689689e6f85dd0971cb8 Mon Sep 17 00:00:00 2001 From: Tazeem Mahashin Date: Sat, 5 Sep 2026 04:37:52 -0400 Subject: [PATCH 6/6] Finalize release-candidate scope and record publication holds --- docs/releases/0.7.0.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/releases/0.7.0.md b/docs/releases/0.7.0.md index dad7220..4765976 100644 --- a/docs/releases/0.7.0.md +++ b/docs/releases/0.7.0.md @@ -25,6 +25,10 @@ claimed by this document. Public 0.6.0 remains the install target until release. 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. @@ -33,6 +37,9 @@ The corrected 24-run research aggregate is included in the source record: 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 @@ -76,14 +83,28 @@ 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. -## Publication Gates Still To Complete +## Release Decision And Remaining Publication Gates -1. Land the reviewed consolidation PR with required Python and native CI green, - then review the version-preparation changes against that exact source. +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. The alert API was unavailable during - preparation, so this item is not recorded as passed. +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.