feat: Add versioned, cross-language Selene API models by trvto · Pull Request #212 · Quantinuum/selene

trvto · 2026-09-01T14:09:06Z

Introduces the selene-trace workspace for versioned, serializable Selene API models.

Add versionless "legacy" trace schema for old schema currently in use.
Adds trace schema v0.1.0 plus Python, Rust, and TypeScript packages.
- v0.1.0 introduces two top level objects: Trace and Traces, which both carry a required schema version.
- OpaquePayload.tag is encoded as canonical hexadecimal strings in JSON for cross-language precision safety.
- Other integer values are restricted to values js can handle automatically
- The api packages can read in legacy data and convert to the v0.1.0 schema
Adds validation, examples, compatibility documentation, CI, Just recipes, and pre-commit coverage.
Coordinates package releases under a shared selene-api-models-v tag.
Immutably publishes schemas to GitHub pages

Before the first release, configure:

A PyPI trusted publisher for selene-api-models, tied to this repository’s api_models.yml workflow. -> Done
Repository secret CARGO_REGISTRY_TOKEN, authorized to publish selene-api-models on crates.io. -> Done
Setup trusted publishing for "@quantinuum/selene-api-models"

…arsed with javascript

…except for OpaquePayload.tag

…buildwheel

Copilot

Copilot review overview

🟡 Changes recommended

Critical cross-language compatibility and precision issues, plus unresolved release workflow and dependency problems, block approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5 · 3 · 1

Open (9)

Use URL-safe Base64 encoding for protocol bytes · New
Accept standard Base64 in the legacy trace adapter · New
Constrain Gate integers to JavaScript-safe values · New
Constrain KeyValuePair integer values to safe ranges · New
Accept standard Base64 in legacy trace validation · New
Install pnpm before enabling setup-node's pnpm cache · New
Enforce uint64 bounds in the schema · New
Reject versionless collections as legacy traces · New
Preserve Trace compatibility or document required schema_version · New

What changed in this PR

Adds versioned Selene trace schemas with synchronized Python, Rust, and TypeScript models, legacy conversion, documentation, examples, and release automation.

Changes:

Adds legacy and v0.1.0 trace schemas with validation and compatibility adapters.
Adds cross-language packages, tests, and examples.
Updates producers, snapshots, packaging, CI, and publishing workflows.

Review identified unresolved cross-language encoding, precision, compatibility, schema-validation, and workflow/dependency issues.

File	Reviewed change
`uv.lock`	Adds workspace dependencies.
`selene-sim/python/tests/snapshots/test_unparsed/test_ghz_trace_unparsed/legacy/trace.json`	Updates legacy trace snapshot.
`selene-sim/python/tests/snapshots/test_unparsed/test_ghz_trace_unparsed/default/trace.json`	Updates trace snapshot.
`selene-sim/python/tests/snapshots/test_trace/test_ghz_trace/legacy/trace.json`	Updates legacy trace snapshot.
`selene-sim/python/tests/snapshots/test_trace/test_ghz_trace/default/trace.json`	Updates trace snapshot.
`selene-sim/python/selene_sim/event_hooks/instruction_log.py`	Emits versioned traces.
`selene-protocol/typescript/tsconfig.json`	Configures TypeScript compilation.
`selene-protocol/typescript/test/protocol.test.mjs`	Tests TypeScript models and compatibility.
`selene-protocol/typescript/src/trace.ts`	Implements TypeScript models and adapters.
`selene-protocol/typescript/src/index.ts`	Exports the TypeScript API.
`selene-protocol/typescript/README.md`	Documents TypeScript usage.
`selene-protocol/typescript/package.json`	Defines the npm package.
`selene-protocol/scripts/check_schema_immutability.py`	Checks schema immutability.
`selene-protocol/schemas/trace/legacy.schema.json`	Defines the legacy schema.
`selene-protocol/schemas/trace/0.1.0.schema.json`	Defines schema v0.1.0.
`selene-protocol/rust/src/trace.rs`	Implements Rust models and adapters.
`selene-protocol/rust/src/lib.rs`	Exports the Rust module.
`selene-protocol/rust/README.md`	Documents Rust usage.
`selene-protocol/rust/Cargo.toml`	Defines the Rust crate.
`selene-protocol/README.md`	Documents protocol structure.
`selene-protocol/python/tests/test_trace.py`	Tests Python trace models.
`selene-protocol/python/tests/test_schema.py`	Tests schema consistency.
`selene-protocol/python/selene_api_models/trace.py`	Implements Python models and adapters.
`selene-protocol/python/selene_api_models/schema.py`	Provides packaged schemas.
`selene-protocol/python/selene_api_models/__init__.py`	Exports Python APIs.
`selene-protocol/python/README.md`	Documents Python usage.
`selene-protocol/pyproject.toml`	Defines the Python package.
`selene-protocol/examples/trace/traces.json`	Adds a collection example.
`selene-protocol/examples/trace/minimal.json`	Adds a minimal example.
`selene-protocol/examples/trace/legacy.json`	Adds a legacy example.
`selene-protocol/examples/trace/all-event-types.json`	Adds event coverage examples.
`selene-protocol/docs/versioning.md`	Documents versioning.
`selene-protocol/docs/trace/legacy.md`	Documents legacy traces.
`selene-protocol/docs/trace/0.1.0.md`	Documents version 0.1.0.
`selene-protocol/docs/publishing.md`	Documents coordinated publishing.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_zero_length_arrays/interface1/trace.json`	Updates argreader trace snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_zero_length_arrays/interface1/pass.json`	Updates argreader pass snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_zero_length_arrays/interface0/trace.json`	Updates argreader trace snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_zero_length_arrays/interface0/pass.json`	Updates argreader pass snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_trace/interface1/trace.json`	Updates argreader trace snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_trace/interface1/pass.json`	Updates argreader pass snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_trace/interface0/trace.json`	Updates argreader trace snapshot.
`selene-ext/utilities/argreader/python/tests/snapshots/test_argreader/test_arg_reader_trace/interface0/pass.json`	Updates argreader pass snapshot.
`selene-ext/utilities/argreader/python/selene_argreader_plugin/trace_pass.py`	Preserves trace version during filtering.
`selene-ext/runtimes/soft_rz/python/tests/snapshots/test_batching/test_batching_behaviour/trace_batching_8.json`	Updates batching snapshot.
`selene-ext/runtimes/soft_rz/python/tests/snapshots/test_batching/test_batching_behaviour/trace_batching_2.json`	Updates batching snapshot.
`selene-ext/runtimes/soft_rz/python/tests/snapshots/test_batching/test_batching_behaviour/trace_batching_1.json`	Updates batching snapshot.
`selene-core/python/selene_core/trace.py`	Re-exports the public trace models.
`selene-core/pyproject.toml`	Adds the API-model dependency and schema packaging.
`selene-core/hatch_build.py`	Packages the canonical schema.
`release-please-config.json`	Coordinates releases.
`pyproject.toml`	Adds workspace and test configuration.
`pnpm-workspace.yaml`	Defines the TypeScript workspace.
`pnpm-lock.yaml`	Locks TypeScript dependencies.
`justfile`	Adds API-model recipes.
`devenv.nix`	Adds tooling and checks.
`Cargo.toml`	Adds the Rust workspace member.
`Cargo.lock`	Locks Rust dependencies.
`.release-please-manifest.json`	Tracks the API-model version.
`.gitignore`	Ignores generated artifacts.
`.github/workflows/publish_schemas.yml`	Publishes schemas.
`.github/workflows/build_wheels.yml`	Updates wheel-build triggers.
`.github/workflows/api_models.yml`	Tests and publishes API packages.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Copilot review overview

🟡 Changes recommended

Unresolved cross-language validation inconsistencies and CI/cache gaps can produce incompatible or stale artifacts.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

Support unpadded base64url decoding in Rust · New

Resolved since last review (7)

Restrict current model to URL-safe base64
Fix TypeScript package-relative release path
Fix Rust package-relative release path
Enforce encoding constraints for legacy payloads
Align legacy integer bounds with upgrade validation
Constrain legacy integers to JavaScript-safe range
Enforce base64url validation in the canonical schema

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Copilot

Copilot review overview

🔵 Needs a closer look

Python currently coerces non-boolean predicate results that the schema and other bindings reject.

Review effort: Balanced
Findings: None

Resolved since last review (1)

Support unpadded base64url decoding in Rust

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Previously missed (1)

In code that hasn't changed since last review

Use strict boolean validation for parse_trace result

selene-trace/python/selene_api_models/trace.py:149

result uses Pydantic's coercing boolean type, so parse_trace accepts schema-invalid JSON such as "result": 1 or "result": "false" and normalizes it, while the JSON Schema and Rust/TypeScript bindings require an actual boolean. Use the existing strict boolean alias here so all bindings validate the same wire values.

Copilot

Copilot review overview

🔵 Needs a closer look

TypeScript parsing and constructor composition can fail unexpectedly, while Rust rejects Base64 accepted by the canonical schemas.

Review effort: Balanced
Findings: None

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Previously missed (3)

In code that hasn't changed since last review

Align Base64 pad-bit validation across implementations

selene-trace/rust/src/trace.rs:234

The checked-in Base64 patterns and the TypeScript/Python bindings accept encodings with non-zero unused pad bits (for example, "Zh==" decodes to b"f"), but base64's default URL_SAFE engines reject them. Consequently, a document valid under either published schema can fail only in Rust. Either configure this decoder to match the accepted grammar or enforce canonical pad bits consistently in both schemas and the other bindings.

Guard BigInt conversion after regex validation fails

selene-trace/typescript/src/trace.ts:28

Zod continues into this refinement after a preceding regex check has marked the parse invalid, so inputs such as "abc" call BigInt("abc") and throw SyntaxError. As a result, UInt64DecimalStringSchema.safeParse and safeParseTrace can throw instead of returning a failed parse. Guard the conversion so every invalid string remains a Zod validation failure.

Allow constructors to accept normalized trace outputs

selene-trace/typescript/src/trace.ts:260

These constructors are not composable with their own normalized outputs. createTraceData converts an opaque tag from a decimal string to bigint, but createTraces reparses it through an input schema that accepts only strings, so createTraces([createTraceData(opaqueEvents)]) throws; similarly, the README's createTraceData(document.events) does not type-check when document is parsed. The constructor layer should accept normalized EventRecord/TraceData values as well as wire inputs without weakening the wire parsers.

Copilot

Copilot review overview

🟡 Changes recommended

The declared decimal tag encoding conflicts with the hexadecimal contract implemented by the schema, bindings, examples, and documentation.

Review effort: Balanced
Findings: 1

Open (1)

OpaquePayload.tag contract mismatches documented decimal and enforced hexadecim… · New

Files not reviewed (1)

pnpm-lock.yaml: Generated file

trvto · 2026-10-07T14:05:11Z

+    "OpaquePayload": {
+      "properties": {
+        "kind": { "const": "OpaquePayload", "default": "OpaquePayload", "title": "Kind", "type": "string" },
+        "tag": { "format": "uint64-hex", "pattern": "^0x(0|[1-9A-F][0-9A-F]{0,15})(?![\\s\\S])", "title": "Tag", "type": "string" },


Updated pr description

jake-arkinstall · 2026-10-08T09:31:35Z

+    steps:
+      - uses: actions/checkout@v6
+      - name: Check package versions match the tag
+        run: |


IIRC you can have a step invoke python directly by using shell: python, then make the run contents just the python script. Might be cleaner than bash/heredoc.

OTOH there may be a good case for turning this into a file and having it invokable locally as part of a git check.

I now check that the package versions match using a separate script on every commit. The script prints the shared version on success and I use it here in a normal shell to compare to the release version.

jake-arkinstall · 2026-10-08T09:33:27Z

+          --base "$BASE_SHA"
+          --head "$HEAD_SHA"
+      - name: Validate and stage schemas
+        run: |


Same here - could make it a direct python script, could make it a locally invokable file.

(ultimately, I'm not a fan of detailed steps that can't be trivially debugged locally - they always go wrong just when you need to hurry a release!)

Similar setup here now

jake-arkinstall · 2026-10-08T09:51:39Z

  "networkx>=2.6,<4",
-  "pydantic~=2.12",
  "pydot>=4.0.0",
+  "selene-api-models~=0.1.0",


I would prefer selene_trace as the package name.

If you think this will only ever include trace stuff happy to go with that. If we add something later that isn't a trace it would be a bit awkward.

trvto added 6 commits August 31, 2026 16:38

add versioned trace schema and api packages

ad830e8

add ci build test and release for api models

8d72b83

exclude selene-api-models from selene-sim cargo lock version updater

79fcf01

make kind required

20864d0

use decimal strings for serializing uint64 so they can be correctly p…

3144818

…arsed with javascript

update justfile and git hooks

bf02eb4

trvto requested a review from jake-arkinstall as a code owner September 1, 2026 14:09

trvto added 7 commits September 1, 2026 16:13

install pnpm before node on ci

e6fac0b

Merge branch '0.3-series' into travis/versioned-trace-schema

41fd9d7

fix devenv, add legacy schema and conversion, revert back to js ints …

171d534

…except for OpaquePayload.tag

add immutable publishing of schemas to github pages

1ce6fa7

Merge branch '0.3-series' into travis/versioned-trace-schema

91c4824

print schema info on validation success

f3fb1fa

use check immutable script, also in pre-commit

706351e

trvto force-pushed the travis/versioned-trace-schema branch from 9490178 to 706351e Compare September 23, 2026 16:10

make python api models py3.10 compatible, use wheel build of it in ci…

8bc6ae0

…buildwheel

trvto force-pushed the travis/versioned-trace-schema branch from f069a8a to 8bc6ae0 Compare September 23, 2026 18:30

trvto added 4 commits September 23, 2026 20:46

fix install order

8c3691f

dont overcomplicate wheel builds

6501ba2

update snapshots

766e17f

add traces as top level schema

4a40501

trvto requested a lite review from Copilot September 24, 2026 09:07

Copilot started reviewing on behalf of trvto September 24, 2026 09:07 View session

Copilot AI reviewed Sep 24, 2026

View reviewed changes

trvto added 6 commits September 24, 2026 11:52

fix legacy base64 issues

b0b7e2f

restrict values of all integer types

6a66710

install pnpm before setup-node

01b5c9f

reject 'traces' in legacy trace schema

cd0c97e

enforce conformity of OpaquePayload.tag to uint64 values through pattern

0cf998d

update docstring

fdbe4bc

trvto requested a balanced review from Copilot September 24, 2026 14:34

Copilot started reviewing on behalf of trvto September 24, 2026 14:34 View session

Copilot AI reviewed Sep 24, 2026

View reviewed changes

Comment thread selene-trace/rust/src/trace.rs Outdated

trvto added 2 commits September 24, 2026 17:13

use npm trusted publishing

2aa0833

fix base64url padding in rust

7d4f727

trvto requested a balanced review from Copilot September 25, 2026 07:56

Copilot started reviewing on behalf of trvto September 25, 2026 07:57 View session

Copilot AI reviewed Sep 25, 2026

View reviewed changes

use strictbool in python model

1cde984

trvto requested a balanced review from Copilot September 28, 2026 09:54

Copilot started reviewing on behalf of trvto September 28, 2026 09:55 View session

Copilot AI reviewed Sep 28, 2026

View reviewed changes

trvto added 3 commits October 7, 2026 14:37

use hex strings for OpaquePayload.tag

95620e5

align on accepted base64, allow bigint tags in typescript constructors

05fd1cf

Merge branch '0.3-series' into travis/versioned-trace-schema

5bf8fad

trvto changed the title ~~Add versioned, cross-language Selene API models~~ feat: Add versioned, cross-language Selene API models Oct 7, 2026

simpler fix for wheel build test file naming problem

51dae66

trvto requested a balanced review from Copilot October 7, 2026 13:54

Copilot started reviewing on behalf of trvto October 7, 2026 13:56 View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

jake-arkinstall reviewed Oct 8, 2026

View reviewed changes

Comment thread devenv.nix Outdated

trvto added 5 commits October 8, 2026 13:37

check package versions match locally, use script on ci

4270169

validate schema ids locally, use script on ci

c860962

use languages.javascript in devenv

2d0fd94

pin ziglang minor version

1ef0eef

regenerate uv.lock

684f785

jake-arkinstall added this pull request to stack #236 October 8, 2026 15:11

Conversation

trvto commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

trvto commented Sep 1, 2026 •

edited

Loading