Production QPU provider adapter boundary

Status: proposed Revision: 1 (2026-08-11) Activation: server-only provider configuration; no new language feature flag Depends on: NM-RFC-0006 target constraints, NM-RFC-0008 quantum jobs, exact-version package resolution, and the existing hardwareExecution readiness contract Implementation gate: the section 14 review record plus an external provider/account/region decision are mandatory before implementation Does not change: hardwareExecution stability, provider selection, account policy, QPU availability, or any language syntax

1. Purpose

N/M has a provider-neutral quantum-job API, durable-store conformance, and a strict nm-hardware-execution-readiness@0.1 evaluator. It intentionally does not bundle a real QPU provider/account adapter. A local simulator adapter and synthetic provider fixture prove interface behavior, not hardware execution.

This RFC defines the minimum server-side adapter, submission, receipt, cost, credential, and failure boundary needed before one real provider can be implemented. It does not select a vendor. Revision 1 creates no adapter, credential, network call, public endpoint, capability promotion, or hardware evidence.

2. Trust boundary

A production adapter is trusted to translate one validated N/M quantum job into one provider job and to map the provider's immutable evidence back into the public contract. It is not trusted to:

• compile arbitrary unvalidated source;
• infer a target from a marketing name;
• expose credentials to the browser;
• retry mutations on another provider;
• replace missing hardware evidence with simulator output; or
• label provider acceptance as a scientifically correct result.

The adapter is loaded only in a server process. Browser bundles, shared URLs, logs, public job documents, telemetry, and error messages must contain no API key, refresh token, credential identifier, raw authorization header, or account secret.

3. Adapter contract

The conceptual nm-qpu-provider-adapter@0.1 interface has six operations:

discoverTargets(binding) -> target snapshot
reserve(request, tenant) -> local reservation
submit(reservation, compiled carrier) -> provider correlation
poll(correlation) -> mapped provider state
cancel(correlation) -> mapped cancellation state
fetchReceipt(correlation) -> retained immutable receipt

The implementation must also pass every provider-neutral store operation from NM-RFC-0008. reserve occurs durably before any provider mutation. submit uses the same tenant-bound idempotency fingerprint for every retry. A process crash after provider acceptance must be recoverable by provider-job correlation, not by blind resubmission.

The adapter has one immutable providerId, one configured account boundary, one region, and an explicit supported backend set per deployment. Mutable provider discovery is captured into a signed or operator-approved snapshot before compilation.

4. Target snapshot

nm-qpu-target-snapshot@0.1 contains:

• provider, account-scope, backend, region, and snapshot identities;
• capture and expiry timestamps;
• enabled/disabled qubits and directed coupling map;
• native gate set and parameter ranges;
• maximum shots, circuits, depth, and provider payload bytes;
• dynamic-circuit, reset, mid-circuit measurement, and conditional support;
• calibration reference only when supplied by the provider;
• queue/availability metadata labeled advisory; and
• canonical digest and approval provenance.

Compilation binds the exact snapshot digest. Expired snapshots fail closed. Advisory queue data never changes semantics and is not called a latency guarantee. Missing calibration is unavailable, never zero error.

5. Compiled submission carrier

nm-qpu-submission@0.1 is created before a provider call and contains:

• exact repository candidate, compiler, source, dependency-lock, and target snapshot digests;
• requested backend and target-native lowered circuit digest;
• strict QASM 3 or provider-neutral IR carrier plus format/version;
• shots and all provider-visible execution options;
• resource-budget report and target-constraint result;
• tenant-bound idempotency fingerprint;
• maximum authorized cost and quota reservation identity;
• creation/expiry times; and
• no credential material.

The carrier is immutable after reservation. Provider-specific translation is a pure, versioned operation over this carrier and the bound target snapshot. Translation must not silently drop unsupported dynamic control, reset, measurement, timing, or calibration semantics.

6. Credentials, account, and tenant isolation

• Credentials are server-only managed secrets, scoped to the selected account and minimum required provider permissions.
• The browser authenticates to the N/M server; it never authenticates directly to the provider through this adapter.
• Tenant ownership is derived server-side and is part of every reservation, poll, cancel, receipt, cost, and audit lookup.
• Cross-tenant identifiers return not-found semantics.
• Credential rotation supports overlapping read/poll access for already submitted jobs without allowing new submissions with a retired key.
• Revocation has a documented emergency stop and recovery procedure.

Account selection, data residency, retention, legal terms, and billing owner are external decisions and must be retained as an approved provider-decision artifact. This RFC cannot make them implicitly.

7. Cost and quota

Before submit, the server atomically reserves:

• the tenant's daily/monthly execution allowance;
• provider shot/circuit quota;
• a maximum currency amount in the configured billing currency; and
• a concurrency slot.

The provider's final billable usage reconciles the reservation. An ambiguous network failure after mutation keeps the reservation charged/pending until correlation or operator reconciliation proves otherwise. It is unsafe to release cost and automatically retry another provider.

Estimated cost, final provider cost, currency, pricing snapshot identity, and reconciliation status are retained separately from scientific results. An unknown final cost is not written as zero.

8. State mapping and retry

Provider states map into NM-RFC-0008's queued, running, succeeded, failed, and cancelled states. The raw state and mapping-version digest are retained in the private receipt.

Retry classes are explicit:

• safe read: bounded retry with backoff;
• mutation not sent: may retry using the same idempotency fingerprint;
• mutation accepted or ambiguous: correlate/poll, never blind resubmit;
• provider validation rejection: terminal, no retry;
• quota or cost rejection: terminal until a new authorized request;
• credential failure: terminal plus security/operations signal; and
• result validation failure: terminal and retained for investigation.

Automatic cross-provider failover is forbidden in revision 1. Simulator fallback is forbidden for a hardware request. A provider outage returns an explicit unavailable/failed result instead of synthetic success.

9. Cancellation

Cancellation is a request, not proof that hardware execution stopped. The adapter records:

• local cancellation request and timestamp;
• provider acknowledgement and raw provider state;
• whether execution may already have begun;
• terminal provider observation; and
• billable usage/cost reconciliation.

A late successful provider result cannot overwrite a locally committed cancelled public state, but its receipt and cost must still be retained and audited. Race behavior must pass the existing rollback-drill checks.

10. Hardware receipt

nm-qpu-receipt@0.1 is the immutable evidence carrier:

• provider/account/backend/region and provider job correlation;
• exact submission and target-snapshot digests;
• provider accepted/started/completed timestamps when available;
• raw-to-public state mapping version;
• requested and accepted shots;
• bounded count/histogram result with sum/count validation;
• provider result/payload digest and retained-object reference;
• calibration reference and capture time only when supplied;
• final cost and reconciliation state when supplied;
• cancellation/retry history; and
• adapter/runtime/deployment/exact-candidate provenance.

Public results expose only the bounded fields approved by NM-RFC-0008. Raw provider payloads remain private, encrypted, retention-bounded, and digest linked. A receipt proves provider provenance and mapping; it does not prove algorithm correctness, hardware fidelity, quantum advantage, or fault tolerance.

11. Diagnostics

Diagnostics exposed to users contain no provider payload, credential, tenant identifier, stack trace, or billing secret.

12. Readiness and evidence

Implementation does not promote hardwareExecution. Preview consideration still requires one exact candidate and deployment to satisfy the existing nm-hardware-execution-readiness@0.1 contract, including:

• all eleven provider checks;
• durable production store conformance;
• at least three retained real-QPU conformance jobs;
• rollback/recovery drill evidence;
• a reviewed 14-day operational window;
• byte-verified retained artifacts; and
• security, operations, and platform owner reviews.

Unit tests, mocked provider servers, simulator jobs, screenshots, and a JSON marked ready are not real-QPU evidence.

13. Acceptance

• One adapter passes hostile target, carrier, receipt, tenant, and credential boundary tests without contacting a provider.
• The selected provider's sandbox and production environments are distinguished and never merged into one evidence window.
• Crash-after-submit, ambiguous timeout, duplicate submission, polling restart, cancel race, quota rejection, credential revocation, and deployment rollback drills pass.
• Retained real-QPU counts sum exactly to accepted shots and bind the submitted carrier digest.
• No browser bundle or public response contains server credentials.
• Hardware requests never fall back to simulator or another provider.
• Existing capability status remains experimental until a separate authorized promotion decision.

14. Required review record

Approval must record reviewer identity, date, rationale, and a retained review artifact for every row, plus the exact provider/account/region decision. A merge, mock server, sandbox prototype, passing test, or simulator run is not approval. Until all rows are approved, no provider package, credential configuration, network mutation, production capability, or public QPU control may be added.

15. Implementation sequence

1. Select provider/account/region, identity model, billing owner, and retention policy through an external reviewed decision.
2. Implement strict target/submission/receipt readers and offline hostile tests.
3. Implement provider translation and a non-mutating discovery probe.
4. Add durable reserve/submit/correlate/poll/cancel behavior.
5. Add atomic cost/quota reconciliation and credential rotation drills.
6. Run retained sandbox conformance, then separately authorized production real-QPU evidence.
7. Evaluate the existing hardware readiness report; do not auto-promote.