detree-vm 0.1.0__tar.gz

detree_vm-0.1.0/.clang-format

@@ -0,0 +1,121 @@
+---
+# Derived from the Gaudi project's .clang-format; kept identical across the
+# repositories that share this C++ style.
+---
+Language: Cpp
+BasedOnStyle: Google
+AccessModifierOffset: -2
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: Always
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: AllIfsAndElse
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: true
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterObjCDeclaration: false
+  AfterStruct: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: true
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: true
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit: 95
+CommentPragmas: '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat: false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks: Preserve
+IncludeCategories:
+  - Regex: ^"(llvm|llvm-c|clang|clang-c)/
+    Priority: 2
+  - Regex: ^(<|"(gtest|gmock|isl|json)/)
+    Priority: 3
+  - Regex: .*
+    Priority: 1
+IncludeIsMainRegex: (Test)?$
+IndentCaseLabels: false
+IndentPPDirectives: AfterHash
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd: ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: All
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 60
+PenaltyBreakFirstLessLess: 30
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Left
+ReflowComments: true
+SortIncludes: CaseSensitive
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: true
+Standard: c++11
+TabWidth: 8
+UseTab: Never
+---
+Language: Json
+IndentWidth: 4
+ColumnLimit: 95

detree_vm-0.1.0/.github/release.yml

@@ -0,0 +1,18 @@
+changelog:
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking
+    - title: New Features
+      labels:
+        - feature
+    - title: Bug Fixes and Performance Improvements
+      labels:
+        - performance
+        - bug-fix
+    - title: Documentation
+      labels:
+        - documentation
+    - title: Other Changes
+      labels:
+        - '*'

detree_vm-0.1.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,55 @@
+name: deploy-docs
+
+# Two entries: a manual deploy from any branch, and the release workflow, which
+# calls this after PyPI so the published site always matches the tag. The site
+# is the same `-W` build the `run-tests` docs job runs, so a broken page fails a
+# pull request before it can fail a release.
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# A deploy in progress must not be cancelled: it would leave Pages serving a
+# half-uploaded site.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build the site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+          activate-environment: true
+          enable-cache: true
+      # The documentation group carries Sphinx and the theme; the project itself
+      # is not installed because `docs/conf.py` imports from `src/`.
+      - name: Install the documentation toolchain
+        run: uv pip install --group docs
+      - name: Build the site
+        run: >-
+          .venv/bin/sphinx-build -b html -c docs -d build/docs/doctrees -W
+          docs build/docs/html
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: build/docs/html
+
+  deploy:
+    name: deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

detree_vm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,207 @@
+name: Release
+
+# A tag is the only trigger: the wheel version comes from setuptools_scm, and a
+# release must be reproducible from the tagged commit (ADR 0009). A manual run
+# would publish a branch build, so there is no `workflow_dispatch`.
+on:
+  push:
+    tags: [v*]
+
+permissions:
+  contents: read
+
+env:
+  # The release build never sets DETREE_SHIP_BACKEND: the default is the Rust
+  # machine, and `both` would put the C++ library in the wheel, which
+  # tools/inspect_wheel.py rejects.
+  PYTHON_VERSION: '3.13'
+
+jobs:
+  test:
+    # The whole test workflow, not a shortened copy: no wheel is built and
+    # nothing is published until the tagged commit passes what main passes.
+    uses: ./.github/workflows/run-tests.yml
+
+  wheels:
+    name: wheel (${{ matrix.name }})
+    needs: [test]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: manylinux-x86_64
+            runner: ubuntu-24.04
+            image: quay.io/pypa/manylinux_2_28_x86_64
+          - name: manylinux-aarch64
+            runner: ubuntu-24.04-arm
+            image: quay.io/pypa/manylinux_2_28_aarch64
+          - name: macos-arm64
+            runner: macos-15
+          - name: windows-x64
+            runner: windows-2022
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v6
+
+      # The manylinux image is the only way to get a manylinux tag: a wheel
+      # built on the runner's glibc would repair to `linux_<arch>` and pip would
+      # never select it. `SETUPTOOLS_SCM_PRETEND_VERSION` removes the need for
+      # git inside the container.
+      - name: Build manylinux wheel
+        if: matrix.image
+        shell: bash
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          docker run --rm -v "$PWD:/work" -w /work \
+            -e SETUPTOOLS_SCM_PRETEND_VERSION \
+            "${{ matrix.image }}" bash -lc '
+              set -euo pipefail
+              curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
+              . "$HOME/.cargo/env"
+              python=/opt/python/cp313-cp313/bin/python
+              "$python" -m pip install --quiet uv auditwheel
+              "$python" -m uv build --wheel --out-dir raw
+              "$python" -m auditwheel repair raw/*.whl -w dist
+            '
+
+      - uses: astral-sh/setup-uv@v7
+        if: ${{ !matrix.image }}
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - uses: dtolnay/rust-toolchain@stable
+        if: ${{ !matrix.image }}
+
+      - name: Build native wheel
+        if: ${{ !matrix.image }}
+        shell: bash
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          uv build --wheel --out-dir dist
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.name }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  sdist:
+    name: sdist
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - run: uv build --sdist --out-dir dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  inspect:
+    name: inspect artifacts
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Check the wheel contract
+        run: python3 tools/inspect_wheel.py dist/*.whl
+      - name: Check the sdist carries the build sources
+        run: |
+          tar -tzf dist/*.tar.gz > sdist.txt
+          for path in kernel/cpp/CMakeLists.txt kernel/rust/src/lib.rs kernel/rust/Cargo.toml spec/isa.toml; do
+            grep -q "/$path$" sdist.txt || { echo "missing $path"; exit 1; }
+          done
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  smoke:
+    name: smoke (${{ matrix.runner }})
+    needs: [wheels]
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-latest, macos-15, windows-2022]
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Install and run the wheel
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv venv /tmp/detree-release
+          if [ -f /tmp/detree-release/bin/python ]; then
+            python=/tmp/detree-release/bin/python
+          else
+            python=/tmp/detree-release/Scripts/python.exe
+          fi
+          # The local wheel is the only source for the new version; the index is
+          # allowed for numpy, which is a real dependency.
+          uv pip install --python "$python" --no-deps --find-links dist \
+            --prerelease=allow detree-vm
+          uv pip install --python "$python" numpy
+          "$python" -m detree backends
+          "$python" -c "import detree; assert detree.include_dir().joinpath('detree.h').is_file()"
+
+  pypi:
+    name: publish to PyPI
+    needs: [inspect, smoke]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/detree-vm
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  notes:
+    name: release notes
+    needs: [pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+  docs:
+    # After PyPI, so the published site describes a version that exists. The
+    # permissions are raised here because the caller's top-level `contents:
+    # read` would otherwise be all the called workflow could use.
+    name: deploy docs
+    needs: [pypi]
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: ./.github/workflows/deploy-docs.yml

detree_vm-0.1.0/.github/workflows/run-tests.yml

@@ -0,0 +1,188 @@
+name: run-tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  # The release workflow calls this file so a tag is tested by exactly the CI
+  # that main runs, not by a second copy of the commands.
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The wheel is py3-none, so one compiled library serves every
+        # interpreter; the matrix runs the pure-Python and the compiled paths
+        # against every interpreter the metadata claims.
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+          enable-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install
+        run: DETREE_SHIP_BACKEND=both uv pip install -e . --group dev
+      - name: Pre-commit
+        if: matrix.python-version == '3.13'
+        run: uv run pre-commit run --all-files
+        env:
+          SKIP: rustfmt
+      - name: Tests
+        run: uv run pytest -v
+
+  cpp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure
+        run: cmake -S kernel -B build/cpp -DDETREE_BUILD_TESTS=ON
+      - name: Build
+        run: cmake --build build/cpp -j4
+      - name: Test
+        run: ctest --test-dir build/cpp --output-on-failure
+
+  sanitizers:
+    # The C++ machine is the porting reference, so undefined behavior there is
+    # worth catching even though the release ships Rust.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure
+        run: >
+          cmake -S kernel -B build/sanitize -DDETREE_BUILD_TESTS=ON
+          -DCMAKE_BUILD_TYPE=Debug
+          -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
+          -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+          -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined"
+      - name: Build
+        run: cmake --build build/sanitize -j4
+      - name: Test
+        run: ctest --test-dir build/sanitize --output-on-failure
+        env:
+          ASAN_OPTIONS: detect_leaks=1:abort_on_error=1
+          UBSAN_OPTIONS: halt_on_error=1:print_stacktrace=1
+
+  rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - name: Format
+        run: cargo fmt --manifest-path kernel/rust/Cargo.toml --all -- --check
+      - name: Test
+        run: cargo test --manifest-path kernel/rust/Cargo.toml
+      - name: Build
+        run: cargo build --manifest-path kernel/rust/Cargo.toml --release
+
+  conformance:
+    # Three machines, one suite. The install builds both compiled libraries and
+    # the tests are run through the venv directly: `uv run` re-syncs the
+    # editable install to the Rust-only default, after which the `[cpp]` cases
+    # skip instead of fail and a green run proves nothing.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+          activate-environment: true
+          enable-cache: true
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install both machines
+        run: >-
+          DETREE_SHIP_BACKEND=both uv pip install -e . --group dev
+          --reinstall-package detree-vm
+      - name: Both libraries are installed
+        # A skipped backend is not a passing backend, so fail here rather than
+        # read a green suite that only ran the Python reference.
+        run: >-
+          .venv/bin/python -c "import sys; from detree.abi.libs import library_path;
+          missing = [n for n in ('cpp', 'rust') if library_path(n) is None];
+          sys.exit(f'missing compiled machine: {missing}' if missing else 0)"
+      - name: Backend identity
+        run: .venv/bin/python -m pytest -q tests/test_backends.py
+      - name: Python reference
+        run: DETREE_BACKEND=python .venv/bin/python -m pytest -q -rs
+      - name: C++ machine
+        run: DETREE_BACKEND=cpp .venv/bin/python -m pytest -q -rs
+      - name: Rust machine
+        run: DETREE_BACKEND=rust .venv/bin/python -m pytest -q -rs
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+          activate-environment: true
+          enable-cache: true
+      - name: Install the documentation toolchain
+        run: uv pip install --group docs
+      - name: ISA tables
+        run: python3 tools/gen_isa.py --check
+      - name: Optimizer document
+        run: python3 tools/gen_opt.py --check
+      - name: Documentation
+        run: python3 tools/check_docs.py
+      - name: Golden corpus
+        run: python3 tools/golden.py --check
+      # The deploy workflow publishes this build, so a broken page has to fail
+      # the pull request instead of the release. `-W` is the same flag.
+      - name: Build the site
+        run: >-
+          .venv/bin/sphinx-build -b html -c docs -d build/docs/doctrees -W
+          docs build/docs/html
+
+  package:
+    # The release artifact is part of the product: build it on every change and
+    # check the wheel contract (one Rust library, the C header, a py3-none tag)
+    # before a tag ever exists.
+    #
+    # Skipped on a tag: `release.yml` builds the four artifacts it publishes and
+    # its `inspect` job runs the same contract checks, so a wheel built here
+    # would never be shipped and would only repeat the work.
+    if: github.ref_type != 'tag'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.13'
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build
+        run: |
+          uv build --wheel --out-dir dist
+          uv build --sdist --out-dir dist
+      - name: Wheel contract
+        run: python3 tools/inspect_wheel.py dist/*.whl
+      - name: Sdist carries the build sources
+        run: |
+          tar -tzf dist/*.tar.gz > sdist.txt
+          for path in kernel/cpp/CMakeLists.txt kernel/rust/src/lib.rs kernel/rust/Cargo.toml spec/isa.toml; do
+            grep -q "/$path$" sdist.txt || { echo "missing $path"; exit 1; }
+          done
+      - name: Install the wheel in a clean environment
+        run: |
+          uv venv /tmp/detree-wheel
+          uv pip install --python /tmp/detree-wheel/bin/python --no-deps \
+            --find-links dist --prerelease=allow detree-vm
+          uv pip install --python /tmp/detree-wheel/bin/python numpy
+          /tmp/detree-wheel/bin/python -m detree backends

detree_vm-0.1.0/.github/workflows/semantic-pr-titles.yml

@@ -0,0 +1,25 @@
+name: Lint PR
+
+# `pull_request`, not `pull_request_target`: from 2026-12-02 GitHub blocks the
+# target trigger by default in public repositories, and this check only reads
+# the event payload, so it needs neither the base checkout nor a secret.
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+
+permissions:
+  pull-requests: read
+
+jobs:
+  title:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      # The title becomes the squash commit subject, so it is held to the same
+      # Conventional Commits rule as a hand-written commit (CONTRIBUTING.md).
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}