1.0.0

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+# Lightweight quality gates on every PR: formatting and lints for both languages. The heavier
+# gates (full test suite, big-endian emulation) live in full-tests.yml and run on demand — either
+# from the Actions tab or via a `/ci-full` / `/ci-endian` PR comment.
+#
+# These mirror `task format` / `task lint`; keep the two in sync.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    name: format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: cargo fmt
+        run: cargo fmt --all -- --check
+      - uses: astral-sh/setup-uv@v5
+      - name: ruff format
+        working-directory: ben-py
+        run: uvx ruff format --check .
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: cargo clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - uses: astral-sh/setup-uv@v5
+      - name: ruff check
+        working-directory: ben-py
+        run: uvx ruff check .

.github/workflows/ci_cd.yml

@@ -1,4 +1,4 @@
-name: Build & publish pyben wheels
+name: Build & publish ben-py wheels
 
 on:
   push:
@@ -14,7 +14,7 @@ on:
     #     options: [testpypi, pypi]
 
 env:
-  PKG_DIR: pyben
+  PKG_DIR: ben-py
   OUT_DIR: dist
 
 permissions:
@@ -42,6 +42,14 @@ jobs:
             --release
             --locked
             --out ${{ env.OUT_DIR }}
+      # Smoke-test the built wheel in a clean venv before it can be published. aarch64 wheels are
+      # cross-built and cannot execute on this runner, so only the native target is smoked.
+      - name: Smoke test wheel
+        if: matrix.target == 'x86_64'
+        run: |
+          python3 -m venv /tmp/wheel-smoke
+          /tmp/wheel-smoke/bin/pip install ${{ env.PKG_DIR }}/${{ env.OUT_DIR }}/*.whl
+          /tmp/wheel-smoke/bin/python .github/workflows/wheel_smoke.py
       - uses: actions/upload-artifact@v4
         with:
           name: wheels-linux-${{ matrix.target }}
@@ -75,6 +83,12 @@ jobs:
             --target universal2-apple-darwin
             --out ${{ env.OUT_DIR }}
 
+      - name: Smoke test wheel
+        run: |
+          python3 -m venv /tmp/wheel-smoke
+          /tmp/wheel-smoke/bin/pip install ${{ env.PKG_DIR }}/${{ env.OUT_DIR }}/*.whl
+          /tmp/wheel-smoke/bin/python .github/workflows/wheel_smoke.py
+
       - uses: actions/upload-artifact@v4
         with:
           name: wheels-macos-universal2
@@ -103,6 +117,13 @@ jobs:
             --release
             --locked
             --out ${{ env.OUT_DIR }}
+      - name: Smoke test wheel
+        shell: pwsh
+        run: |
+          python -m venv $env:TEMP\wheel-smoke
+          $wheel = Get-ChildItem "${{ env.PKG_DIR }}\${{ env.OUT_DIR }}\*.whl" | Select-Object -First 1
+          & "$env:TEMP\wheel-smoke\Scripts\pip" install $wheel.FullName
+          & "$env:TEMP\wheel-smoke\Scripts\python" .github\workflows\wheel_smoke.py
       - uses: actions/upload-artifact@v4
         with:
           name: wheels-windows
@@ -112,7 +133,7 @@ jobs:
     name: windows (ARM64, abi3)
     runs-on: windows-11-arm
     env:
-      PKG_DIR: pyben
+      PKG_DIR: ben-py
       OUT_DIR: dist
     steps:
       - uses: actions/checkout@v4
@@ -131,6 +152,13 @@ jobs:
             --locked
             --out ${{ env.OUT_DIR }}
             --target aarch64-pc-windows-msvc
+      - name: Smoke test wheel
+        shell: pwsh
+        run: |
+          python -m venv $env:TEMP\wheel-smoke
+          $wheel = Get-ChildItem "${{ env.PKG_DIR }}\${{ env.OUT_DIR }}\*.whl" | Select-Object -First 1
+          & "$env:TEMP\wheel-smoke\Scripts\pip" install $wheel.FullName
+          & "$env:TEMP\wheel-smoke\Scripts\python" .github\workflows\wheel_smoke.py
       - uses: actions/upload-artifact@v4
         with:
           name: wheels-windows-arm64

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    name: Build & execute docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ben-py
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      # Builds the PyO3 extension (so autodoc reads live docstrings) and installs the
+      # render + execution doc dependencies.
+      - name: Install docs dependencies
+        run: uv sync --no-dev --extra docs --extra docs-exec
+
+      # NB_EXECUTION_MODE=cache executes every tutorial notebook end to end; -W turns
+      # any Sphinx warning (including a notebook cell error) into a build failure, so
+      # the docs cannot drift from the live API without CI catching it.
+      - name: Build docs (execute notebooks, warnings as errors)
+        env:
+          NB_EXECUTION_MODE: cache
+        run: uv run sphinx-build -W -b dirhtml docs docs/_build
+
+      # Run every Python code block in the Markdown docs against the live API.
+      - name: Test documentation code snippets
+        run: uv run --with pytest pytest tests/test_docs_snippets.py -q
+
+      - name: Check documentation links
+        run: uv run sphinx-build -b linkcheck docs docs/_build/linkcheck
+
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: ben-py/docs/_build

.github/workflows/full-tests.yml

@@ -0,0 +1,167 @@
+name: Full tests (on demand)
+
+# The heavy gates, run only when asked:
+#
+#   - From the Actions tab via "Run workflow" (workflow_dispatch), picking any branch.
+#   - From a PR by commenting `/ci-full` (Rust + Python suites + big-endian), `/ci-endian`
+#     (big-endian only), or `/ci-fuzz` (time-boxed coverage-guided fuzzing). Comment triggers
+#     are restricted to the repo owner, members, and collaborators, because the jobs check out
+#     and execute the PR head.
+#
+# Note: GitHub only evaluates `issue_comment` triggers against the workflow file on the default
+# branch, so the comment commands start working once this file lands on main.
+
+on:
+  workflow_dispatch:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write # eyes-reaction acknowledgment on the triggering comment
+
+jobs:
+  decide:
+    name: decide what to run
+    runs-on: ubuntu-latest
+    outputs:
+      run_full: ${{ steps.flags.outputs.run_full }}
+      run_endian: ${{ steps.flags.outputs.run_endian }}
+      run_fuzz: ${{ steps.flags.outputs.run_fuzz }}
+      ref: ${{ steps.flags.outputs.ref }}
+    steps:
+      - name: compute trigger flags
+        id: flags
+        # The comment body is passed through env rather than interpolated into the script, so a
+        # hostile comment cannot inject shell.
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          IS_PR_COMMENT: ${{ github.event.issue.pull_request != null }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          AUTHOR_ASSOCIATION: ${{ github.event.comment.author_association }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          DISPATCH_REF: ${{ github.ref }}
+        run: |
+          run_full=false
+          run_endian=false
+          run_fuzz=false
+          ref="$DISPATCH_REF"
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            run_full=true
+            run_endian=true
+            run_fuzz=true
+          elif [ "$IS_PR_COMMENT" = "true" ]; then
+            case "$AUTHOR_ASSOCIATION" in
+              OWNER|MEMBER|COLLABORATOR)
+                case "$COMMENT_BODY" in
+                  *"/ci-full"*) run_full=true; run_endian=true ;;
+                esac
+                case "$COMMENT_BODY" in
+                  *"/ci-endian"*) run_endian=true ;;
+                esac
+                case "$COMMENT_BODY" in
+                  *"/ci-fuzz"*) run_fuzz=true ;;
+                esac
+                ;;
+            esac
+            ref="refs/pull/$PR_NUMBER/head"
+          fi
+          {
+            echo "run_full=$run_full"
+            echo "run_endian=$run_endian"
+            echo "run_fuzz=$run_fuzz"
+            echo "ref=$ref"
+          } >> "$GITHUB_OUTPUT"
+      - name: acknowledge the triggering comment
+        if: github.event_name == 'issue_comment' && (steps.flags.outputs.run_full == 'true' || steps.flags.outputs.run_endian == 'true' || steps.flags.outputs.run_fuzz == 'true')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh api
+          repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions
+          -f content=eyes
+
+  rust-tests:
+    name: rust tests
+    needs: decide
+    if: needs.decide.outputs.run_full == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.ref }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: fast suite
+        run: cargo test
+      - name: ignored-gated stress suite
+        run: >-
+          cargo test -- --ignored
+          --skip generate_format_stability_fixtures
+          --skip regenerate_twodelta_fixtures
+          --skip generate_pcompress_interop_fixture
+
+  python-tests:
+    name: python tests
+    needs: decide
+    if: needs.decide.outputs.run_full == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.ref }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: astral-sh/setup-uv@v5
+      - name: sync environment
+        working-directory: ben-py
+        run: uv sync --all-groups
+      - name: build extension
+        working-directory: ben-py
+        run: uv run maturin develop
+      - name: pytest
+        working-directory: ben-py
+        run: uv run pytest tests/
+
+  big-endian:
+    name: big-endian suite (s390x under QEMU)
+    needs: decide
+    if: needs.decide.outputs.run_endian == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.ref }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+      - name: cross test on s390x
+        run: cross test -p binary-ensemble --target s390x-unknown-linux-gnu
+
+  fuzz:
+    name: coverage-guided fuzzing (time-boxed)
+    needs: decide
+    if: needs.decide.outputs.run_fuzz == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.decide.outputs.ref }}
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-fuzz
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: fuzz every read surface (120s per target)
+        run: task fuzz FUZZ_SECONDS=120
+      - name: upload crash artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-artifacts
+          path: fuzz/artifacts/

.github/workflows/wheel_smoke.py

@@ -0,0 +1,43 @@
+"""Smoke test for a freshly built binary_ensemble wheel.
+
+Run inside a clean venv that has the wheel (and nothing else from this repo) installed: imports
+the extension module and round-trips a tiny ensemble through encode/decode. Catches wheels that
+build but cannot load (bad abi3 configuration, missing symbols) or that load but cannot reach the
+Rust core, before they are published.
+"""
+
+import json
+import pathlib
+import tempfile
+
+import binary_ensemble as be
+
+LINES = [
+    {"assignment": [1, 1, 2, 2], "sample": 1},
+    {"assignment": [2, 2, 1, 1], "sample": 2},
+    {"assignment": [2, 2, 1, 1], "sample": 3},
+]
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = pathlib.Path(tmp)
+        src = tmp_path / "src.jsonl"
+        ben = tmp_path / "out.ben"
+        back = tmp_path / "round.jsonl"
+
+        src.write_text(
+            "".join(json.dumps(line, separators=(",", ":")) + "\n" for line in LINES)
+        )
+        be.encode_jsonl_to_ben(src, ben, overwrite=True, variant="standard")
+        be.decode_ben_to_jsonl(ben, back, overwrite=True)
+
+        assert src.read_bytes() == back.read_bytes(), (
+            f"wheel round-trip mismatch:\n{src.read_text()!r}\n!=\n{back.read_text()!r}"
+        )
+
+    print("wheel smoke test passed")
+
+
+if __name__ == "__main__":
+    main()

.gitignore

@@ -7,4 +7,5 @@ dev_files
 demo
 
 __pycache__
-*.so
+*.so
+/ben-py/docs/code-theme-preview.md