qCompute — Public API

File: qc_API.md
Layer: RTT‑Inside Compute Harness
Status: Canonical (2026)

This document defines the public API surface for qCompute.

The API is:

• structural
• deterministic
• environment‑aware
• drift‑bounded
• replay‑safe

The API does not simulate amplitudes or physical states.

1. Session API#

Create a session#

session = qSession(env="sandbox", backend="auto")

Arguments:

• env: "sandbox" | "production" | "archive"
• backend: "auto" or explicit backend ID

Deploy a token#

session.deploy_token("token-id")

Tokens are required for:

• sandbox → production
• production → archive
• r3 operators

Transition environment#

session.transition("production")
session.transition("archive")

Rules:

• sandbox → production (token required)
• production → archive (token required)
• archive → (forbidden)

Save trace#

session.save_trace("example.qtrace")

Produces an append‑only .qtrace ledger.

2. Operator API#

Operators are invoked directly on the session:

session.h(q=0)
session.cx(q1=0, q2=1)
session.measure(q=0)
session.pulse(q=0, duration=20, amplitude=0.5)

Operator families:

• r1: primitive
• r2: composite
• r3: pulse
• measurement
• meta

All operators pass through:

1. Validator
2. Router
3. Frame Manager
4. Drift Engine
5. Capture

3. r1 Operators (Primitive)#

session.x(q=0)
session.y(q=0)
session.z(q=0)
session.h(q=0)
session.s(q=0)
session.t(q=0)

Rules:

• allowed in sandbox + production
• low drift
• backend: local-sim

4. r2 Operators (Composite)#

session.cx(q1=0, q2=1)
session.cz(q1=0, q2=1)
session.swap(q1=0, q2=1)

Rules:

• allowed in sandbox + production
• medium drift
• backend: hybrid-sim
• tier escalation opens new frame

5. r3 Operators (Pulse)#

session.pulse(q=0, duration=20, amplitude=0.5)

Rules:

• production only
• token required
• backend: hardware-qpu-2
• always opens new frame
• high drift

6. Measurement Operators#

session.measure(q=0)

Rules:

• allowed in sandbox + production
• forces tier decrease
• forces new frame

7. Meta Operators#

session.barrier()
session.flush()

Rules:

• allowed in sandbox + production
• always open new frame
• zero drift

8. Replay API#

Load a trace:

replay = qReplay("example.qtrace")

Access reconstructed structures:

replay.session
replay.frames
replay.operators
replay.transitions

Replay is:

• deterministic
• read‑only
• invariant‑checking
• hash‑verified

9. Error Model#

All structural errors raise:

qComputeError("<canonical reason>")

Canonical reasons:

• "invalid grammar"
• "invalid arguments"
• "illegal in environment"
• "backend mismatch"
• "backend illegal in environment"
• "tier decrease inside frame"
• "token required"
• "archive terminal"
• "illegal transition"
• "drift bound exceeded"
• "hash chain invalid"

No other strings are permitted.

10. Summary#

The qCompute API provides:

• session creation
• environment transitions
• token deployment
• operator invocation
• trace capture
• replay verification

The API is structural, deterministic, and governed.