Add versioned, cross-language Selene API models

.github/workflows/api_models.yml

@@ -0,0 +1,164 @@
+name: API model packages
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/api_models.yml"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "pyproject.toml"
+      - "selene-protocol/**"
+      - "uv.lock"
+  push:
+    branches:
+      - main
+      - 0.3-series
+    tags:
+      - "selene-api-models-v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    name: Python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+      - name: Test
+        run: uv run --locked --package selene-api-models --group test pytest selene-protocol/python/tests
+      - name: Build distributions
+        run: uv build --package selene-api-models --out-dir dist/python
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: selene-api-models-python
+          path: dist/python/*
+          if-no-files-found: error
+
+  rust:
+    name: Rust
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Test
+        run: cargo test --package selene-api-models
+      - name: Package
+        run: cargo package --allow-dirty --no-verify --package selene-api-models
+
+  typescript:
+    name: TypeScript
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Test
+        run: pnpm --dir selene-protocol/typescript test
+      - name: Prepare package directory
+        run: mkdir -p dist/typescript
+      - name: Package
+        run: pnpm --dir selene-protocol/typescript pack --pack-destination "$GITHUB_WORKSPACE/dist/typescript"
+      - name: Upload package
+        uses: actions/upload-artifact@v7
+        with:
+          name: selene-api-models-typescript
+          path: dist/typescript/*
+          if-no-files-found: error
+
+  verify-release-version:
+    name: Verify shared release version
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'selene-api-models-v')
+    needs: [python, rust, typescript]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check package versions match the tag
+        run: |
+          expected_version="${GITHUB_REF_NAME#selene-api-models-v}"
+          python3 - "$expected_version" <<'PY'
+          import json
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          expected = sys.argv[1]
+          versions = {
+              "Python": tomllib.loads(Path("selene-protocol/pyproject.toml").read_text())["project"]["version"],
+              "Rust": tomllib.loads(Path("selene-protocol/rust/Cargo.toml").read_text())["package"]["version"],
+              "TypeScript": json.loads(Path("selene-protocol/typescript/package.json").read_text())["version"],
+          }
+          mismatches = [f"{name}={version}" for name, version in versions.items() if version != expected]
+          if mismatches:
+              raise SystemExit(
+                  f"Release tag requires version {expected} in every API-model package; "
+                  + ", ".join(mismatches)
+              )
+          PY
+
+  publish-python:
+    name: Publish Python package
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'selene-api-models-v')
+    needs: [verify-release-version]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: selene-api-models-python
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  publish-rust:
+    name: Publish Rust crate
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'selene-api-models-v')
+    needs: [verify-release-version]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Publish
+        run: cargo publish --package selene-api-models
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  publish-typescript:
+    name: Publish TypeScript package
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'selene-api-models-v')
+    needs: [verify-release-version]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Publish
+        run: pnpm --dir selene-protocol/typescript publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/build_wheels.yml

@@ -10,7 +10,8 @@ on:
       - main
       - 0.3-series
     tags:
-      - "*"
+      - "selene-core-v*"
+      - "selene-sim-v*"
   workflow_dispatch:
 
 permissions:

.gitignore

@@ -40,5 +40,9 @@ __pycache__/
 _dist/
 
 wheelhouse/
+node_modules/
+selene-protocol/typescript/dist/
 !.cargo
 scratch/
+
+.idea

.release-please-manifest.json

@@ -1,4 +1,5 @@
 {
     "selene-core": "0.3.0",
-    ".": "0.3.0"
+    ".": "0.3.0",
+    "selene-protocol": "0.1.0"
 }

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 resolver = "2"
 members = [
+    "selene-protocol/rust",
     "selene-core",
     "selene-sim",
     "selene-ext/simulators/stim",

devenv.nix

@@ -12,6 +12,9 @@
       graph-easy
       libffi
       cargo-expand
+      nodejs_22
+      pnpm
+      typescript
     ];
 
     enterShell = ''
@@ -63,7 +66,9 @@
       };
       mypy = {
         enable = true;
-        args = ["--config=pyproject.toml"];
+        # Pre-commit invokes this hook concurrently for file batches. Disable
+        # Mypy's shared incremental cache to avoid cache-corruption assertions.
+        args = ["--config=pyproject.toml" "--no-incremental"];
         extraPackages = with pkgs.python3Packages; [
           types-pyyaml
         ];
@@ -73,6 +78,36 @@
           "selene-ext/simulators/stim/python/gate_definitions.py"
         ];
       };
+      api-models-python-test = {
+        enable = true;
+        name = "API models Python tests";
+        description = "Run the Python API model test suite.";
+        package = pkgs.uv;
+        entry = "uv run --locked --package selene-api-models --group test pytest selene-protocol/python/tests";
+        files = "^(selene-protocol/.*|Cargo\\.(toml|lock)|pyproject\\.toml|uv\\.lock|pnpm(-workspace)?\\.yaml|devenv\\.nix)$";
+        pass_filenames = false;
+      };
+      api-models-rust-test = {
+        enable = true;
+        name = "API models Rust tests";
+        description = "Run the Rust API model test suite.";
+        package = pkgs.cargo;
+        entry = "cargo test --package selene-api-models";
+        files = "^(selene-protocol/.*|Cargo\\.(toml|lock)|pyproject\\.toml|uv\\.lock|pnpm(-workspace)?\\.yaml|devenv\\.nix)$";
+        pass_filenames = false;
+      };
+      api-models-typescript-test = {
+        enable = true;
+        name = "API models TypeScript tests";
+        description = "Install locked dependencies and run the TypeScript API model test suite.";
+        package = pkgs.pnpm;
+        entry = "${pkgs.writeShellScript "api-models-typescript-test" ''
+          ${pkgs.pnpm}/bin/pnpm install --frozen-lockfile
+          ${pkgs.pnpm}/bin/pnpm --filter @quantinuum/selene-api-models test
+        ''}";
+        files = "^(selene-protocol/.*|Cargo\\.(toml|lock)|pyproject\\.toml|uv\\.lock|pnpm(-workspace)?\\.yaml|devenv\\.nix)$";
+        pass_filenames = false;
+      };
     };
   };
 }

justfile

@@ -14,6 +14,15 @@ test-py *TEST_ARGS: develop
 test-rs *TEST_ARGS:
     uv run cargo test {{TEST_ARGS}}
 
+test-ts:
+    pnpm install --frozen-lockfile
+    pnpm --filter @quantinuum/selene-api-models test
+
+test-api-models:
+    uv run --locked --package selene-api-models --group test pytest selene-protocol/python/tests
+    cargo test --package selene-api-models
+    just test-ts
+
 nitpicks:
     #!/usr/bin/env bash
     set -euo pipefail

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - selene-protocol/typescript

pyproject.toml

@@ -62,9 +62,10 @@ dev = [
 [tool.uv.sources]
 selene-sim = { workspace = true }
 selene-core = { workspace = true }
+selene-api-models = { workspace = true }
 
 [tool.uv.workspace]
-members = ["selene-core"]
+members = ["selene-core", "selene-protocol"]
 
 [tool.hatch.build.hooks.custom]
 path = "hatch_build.py"
@@ -142,6 +143,7 @@ norecursedirs = ['*.egg', '.*', 'build', 'target', 'dist', 'venv']
 [tool.deptry]
 known_first_party = [
   "selene_sim",
+  "selene_api_models",
   # Error models
   "selene_depolarizing_error_model_plugin",
   "selene_ideal_error_model_plugin",