Fix integration Bell circuit fixture so simulator preflight accepts it

[splch]

Summary

Two related fixes for the same root cause: the upstream OpenAPI spec marks QisCircuitInput.qubits as optional and floating-point, but the simulator preflight (qp-circuit-service) requires it and qubit counts are integers. Without qubits, the preflight hits an unguarded IndexError that surfaces to the client as a generic UnexpectedCompilationError only after the test polls for 120s, masking the root cause as last status: submitted.

Fixture fix (tests/integration/test_simulator_job.py)

Adds qubits: 2 to the BELL_CIRCUIT fixture and switches to the singular target/control form (verified end-to-end against the simulator that it round-trips identically to the plural form).

OpenAPI overlay (openapi-overlay.yaml)

Codifies the same qubits requirement at the SDK level so this class of mistake fails at construction rather than after a 120s wait. Updates the README example and unit-test stub to match.

What openapi-overlay.yaml is

A patch file in the OpenAPI Overlay 1.0 format. It declares JSONPath-targeted edits to apply to openapi.json before client generation - here it removes the upstream required array on QisCircuitInput, replaces it with [circuit, gateset, qubits], and retypes qubits as integer / int32.

How it works

The codegen pipeline (documented in CONTRIBUTING.md and enforced by .github/workflows/generated.yml) conditionally applies the overlay if the file is present:

curl -sf https://api.ionq.co/v0.4/api-docs -o openapi.json

if [ -f openapi-overlay.yaml ]; then
    uvx oas-patch==0.6.0 overlay openapi.json openapi-overlay.yaml -o /tmp/patched-spec.json
else
    cp openapi.json /tmp/patched-spec.json
fi

uvx openapi-python-client==0.28.3 generate --path /tmp/patched-spec.json ...

The Generated code check workflow runs the same invocation on every PR and fails if ionq_core/ drifts from the patched spec. Spec drift against upstream is checked weekly by spec-drift.yml.

Why it's here (vs. fixing upstream)

The upstream spec is the source of truth for API-surface changes, but the overlay is the right home for SDK-level corrections that:

• Tighten contracts the API actually enforces but the spec under-specifies (qubits being required).
• Fix type mismatches between the spec and the wire format (qubits being integer-valued, not float).

Each overlay action carries a reason in the file's info.description so future maintainers know why it exists and can drop it once upstream catches up.

Test plan

• Submitted the corrected Bell payload directly to the simulator via the SDK; jobs reached completed (vs. UnexpectedCompilationError with the previous fixture).
• Regenerated ionq_core/ with the overlay applied; qubits is now a required int on QisCircuitInput (constructing without it is a TypeError at the SDK boundary).
• Unit tests pass (uv run pytest); the Generated code check workflow on this PR confirms generator output matches the committed files.
• Trigger Integration Tests workflow on this branch; expect test_submit_and_poll, TestCompletedJobEndpoints::*, and test_async_* to pass.

---

Important

Most code in ionq_core/ is auto-generated and overwritten on regeneration.
See CONTRIBUTING.md for which files are safe to edit.

Resolved

[splch]

The spec.openapis.org/overlay/v1.0.0 says the array "MUST contain at least one value.", so this openapi-overlay.yaml file will come and go.