qCompute — Routing Engine

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

The Routing Engine determines:

backend selection
frame reuse vs. new frame
tier escalation
drift‑overflow routing
measurement routing
meta routing
environment legality
token requirements

Routing is deterministic, governed, and replay‑verifiable.

qCompute computes structure, not amplitudes.

1. Purpose#

Router receives a validated operator and decides:

backend
frame action (reuse or new)
routing reason
environment legality
token requirements

Router emits routing metadata for capture and replay.

2. Routing Inputs#

Router receives:

operator:
  name
  tier
  params

session:
  environment
  token_state
  current_frame

frame:
  tier
  backend
  drift_state

backend_profiles:
  legality
  tier_binding
  drift_envelope

All fields are required.

3. Backend Selection#

Backend is determined by tier binding:

Tier	Backend
r1	local-sim
r2	hybrid-sim
r3	hardware-qpu-2

Backend legality is checked against environment:

sandbox: r1, r2
production: r1, r2, r3
archive: none

If illegal:

allowed: false
reason: "backend illegal in environment"

4. Frame Reuse vs. New Frame#

Router decides whether to reuse the current frame or open a new one.

4.1 Reuse Frame#

Allowed when:

tier does not escalate
drift does not overflow
operator is not measurement
operator is not meta
operator is not r3
environment does not change

4.2 New Frame#

Required when:

tier escalation (r1 → r2, r2 → r3)
tier decrease (measurement)
r3 operator
meta operator
drift overflow
environment transition
backend change

Router must always choose the strongest trigger.

5. Routing Reasons#

Router emits one canonical reason:

"tier-binding"
"tier-escalation"
"tier-decrease"
"measurement"
"meta"
"r3-requires-new-frame"
"backend-change"
"environment-transition"
"drift-overflow"
"token-required"

Only one reason is emitted per operator.

6. Token Requirements#

Token is required for:

r3 operators
sandbox → production transition
production → archive transition

If missing:

allowed: false
reason: "token required"

7. Routing Algorithm (Deterministic)#

1. Determine backend from tier.
2. Check backend legality in environment.
3. Check token requirements.
4. Determine if tier escalates or decreases.
5. Check for measurement or meta operator.
6. Check drift overflow.
7. Check environment transition.
8. Decide frame_action = reuse | new.
9. Emit routing reason.
10. Emit routing metadata.

Router never uses heuristics.
Router never uses randomness.

8. Routing Metadata (Capture)#

Each operator produces:

routing:
  backend: "<backend-id>"
  frame_action: "reuse" | "new"
  reason: "<canonical-reason>"

Each frame produces:

frame_backend:
  id: "<backend-id>"
  tier_support: [...]
  drift_profile: "<low|medium|high>"

All fields are required.

9. Replay Verification#

Replay recomputes routing:

backend selection
frame boundaries
tier escalation
tier decrease
drift overflow
environment transitions
token requirements

Replay must confirm:

routing reason matches canonical logic
frame boundaries match routing logic
backend legality is preserved
environment legality is preserved
drift overflow is correct
token requirements are satisfied

Replay is deterministic and read‑only.

10. Invariants#

r1 → local-sim
r2 → hybrid-sim
r3 → hardware-qpu-2
r3 always opens new frame
measurement always opens new frame
meta always opens new frame
drift overflow always opens new frame
tier may increase but never decrease within a frame
environment transitions always open new frame
archive forbids all operators

11. Summary#

Router provides:

deterministic backend selection
deterministic frame boundaries
deterministic routing reasons
deterministic legality enforcement

Router is the structural decision engine of qCompute.