Status: preview Contract: 0.1.0-preview Default: API disabled in production until a provider is configured Owner: platform / runtime

1. Problem

The preview quantum-job endpoint can queue simulator work, but its original in-process contract does not define ownership, idempotent submission, durable state transitions, retry limits, or a versioned response carrier. A guessed job identifier can also be polled or cancelled without proving that the caller created the job.

NM-RFC-0008 defines the provider-neutral 0.1 boundary needed before remote or hardware execution can be considered stable. It does not select a production queue, database, identity provider, or hardware vendor.

2. Request contract

POST /api/nm/jobs accepts JSON with the exact fields source, target, shots, and metadata. Unknown fields fail closed.

The UTF-8 request body is at most 260,000 bytes and source is at most 256,000 bytes.
source is a non-empty N/M program.
target is an identifier of 1–80 ASCII letters, digits, ., _, :, or -.
shots is an integer in 1..100000.
Metadata has at most 16 entries. Keys use [A-Za-z0-9_.-], are at most 40 UTF-8 bytes, and values are at most 160 UTF-8 bytes. Control characters are rejected rather than silently rewritten.
The Idempotency-Key header is required. It contains 8–128 ASCII letters, digits, ., _, :, or -.

The server binds an idempotency key to the authenticated tenant scope and a canonical request fingerprint. Repeating the same tenant, key, and request returns the existing job. Reusing the key for a different request returns 409 and never queues work. Concurrent duplicates must resolve to one reservation.

3. Ownership boundary

Every provider operation receives an opaque tenant identifier derived server-side from an authenticated subject or a protected client cookie. Raw cookie values, IP addresses, emails, and idempotency keys are not stored in the public job document.

Submission creates or reuses a job only inside the caller's tenant scope.
Poll and cancel require the same scope.
A missing client scope is unauthorized.
A job that belongs to another scope is reported as not found, preventing identifier enumeration.
Rate limiting remains independent from idempotency and uses a trusted client identity.

The preview cookie scope is an anonymous browser boundary, not an account-level authorization system. A production provider must replace or explicitly accept this limitation before the operational gate can pass.

4. State machine and retry

The only valid transitions are:

text

queued -> running -> succeeded
                  -> failed
queued ----------> cancelled
running ---------> cancelled

Terminal states are immutable. A stale worker completion cannot overwrite cancellation or another terminal outcome. The public document records attempts and maxAttempts; 0.1 permits at most two attempts. A validated N/M execution failure is deterministic and is not retried. An unexpected provider failure may be retried only while the attempt limit remains. Backoff and distributed lease semantics belong to the durable provider implementation.

State invariants:

queued and running contain neither result nor error.
succeeded contains exactly result.
failed contains exactly error.
cancelled contains neither result nor error.
updatedAt cannot precede createdAt.

5. Versioned carrier

Every public job document includes:

json

{
  "format": "nm-quantum-job",
  "version": "0.1",
  "contractVersion": "0.1.0-preview",
  "id": "job-id",
  "provider": "local-simulator",
  "status": "queued",
  "target": "browser-statevector",
  "metadata": {},
  "attempts": 0,
  "maxAttempts": 2,
  "createdAt": "2026-07-15T00:00:00.000Z",
  "updatedAt": "2026-07-15T00:00:00.000Z"
}

The canonical JSON Schema is published at /schemas/nm-quantum-job-0.1.schema.json. The 0.1 reader rejects unknown fields, formats, versions, state combinations, oversized collections, non-finite numbers, unsafe diagnostic strings, and malformed timestamps. The identity migration from 0.1 to 0.1 is explicit. No future-version down-conversion is attempted.

Result payloads are bounded. Output has at most 200 lines, diagnostics at most 100 items, probability/histogram collections at most 4096 items, and a serialized public job is at most 1 MiB. Program results preserve NM-RFC-0007 when present; a deliberate program error remains a successful engine execution.

6. Failure semantics

Stable public diagnostic families are:

Table 1
Code	Meaning
`NM-JOB-PARSE-001`	The JSON payload cannot be parsed.
`NM-JOB-TYPE-001`	A field has the wrong type or an unknown field is present.
`NM-JOB-VERSION-001`	Format, schema version, or contract version is unsupported.
`NM-JOB-LIMIT-001`	A documented byte, count, or numeric limit is exceeded.
`NM-JOB-STATE-001`	A document or transition violates the state machine.
`NM-JOB-IDEMPOTENCY-001`	An idempotency key is invalid or reused with another request.
`NM-JOB-TENANT-001`	The caller has no valid tenant scope.
`NM-JOB-PROVIDER-001`	The provider is absent or fails unexpectedly.

Validation errors do not leak source, metadata, tenant identifiers, provider internals, or stack traces.

7. Stability gates

This RFC can close local contract, hostile-input, concurrency, package, documentation, and performance gates. quantumJobApi remains preview, and the separate hardwareExecution capability remains experimental, until their applicable evidence gates are satisfied.

The public runNMQuantumJobStoreConformance harness freezes eleven provider-neutral checks: store opening, concurrent atomic reservation, idempotency conflict, tenant isolation, concurrent schedule claim, schedule-release rollback, compare-and-set terminal transition, reservation-discard rollback, restart persistence, expired-lease recovery, and isolated cleanup. A report is production-ready only when the adapter declares durable-production, returns fresh handles across simulated restarts, supplies lease-expiry and cleanup hooks, and passes every check. The in-memory reference intentionally fails the restart and lease checks. Passing this harness is necessary evidence, not a substitute for a live rollback drill or the operational window.

a selected durable production store/provider with atomic reservations and transitions;
account-grade tenant isolation or an explicitly approved anonymous security model;
distributed retry/lease recovery and provider rollback procedure;
remote-browser conformance evidence;
at least 14 days and 100 production sessions of error, latency, queue, retry, and cancellation telemetry.

7.1 Separate hardware preview-readiness evidence

nm-hardware-execution-readiness@0.1 is the fail-closed evidence boundary for considering hardwareExecution for preview. It does not choose or bundle a provider. One report must bind the same repository, exact 40-character candidate SHA, production deployment, provider account, QPU backend, durable store, queue, and region across:

eleven provider checks covering authenticated account identity, tenant and credential isolation, target discovery, retained real-QPU provenance, idempotent submission, provider-job correlation, terminal/cancellation mapping, retry classification, and bounded result validation;
all eleven durable-store conformance checks with durable-production status;
at least three retained real-QPU conformance jobs;
eight rollback scenarios covering reservation/submission ordering, worker restart, cancellation races, lease expiry, retry exhaustion, credential revocation, and deployment rollback within 15 minutes;
a ready 14-day / 100-submission operations report containing only the selected hardware provider and backend;
five retained JSON artifacts (provider-decision, store-conformance, provider-conformance, rollback-drill, and operations) whose bytes match their SHA-256 digests and whose values match the corresponding strict evidence sections; and
security, operations, and platform owner approvals made after the evidence window.

The authorized reviewer runs:

bash

npm run report:nm:hardware-execution-readiness -- --input <evidence.json> --artifact-root <retained-directory> --output <readiness.json> --check

Unknown fields, anonymous identity, ephemeral stores, simulator provenance, provider/deployment drift, missing bytes, digest drift, incomplete rollback, insufficient operations, and stale or missing reviews fail closed. Output deliberately excludes source, tenant identifiers, provider job identifiers, account secrets, and raw receipts. A passing JSON report is not a cryptographic signature and cannot by itself change the capability registry; retained provider receipts, account-security review, remote browser evidence, and an explicit release decision remain mandatory.

8. Non-goals

choosing a cloud queue, database, quantum vendor, billing model, or account system;
promising exactly-once hardware execution;
accepting arbitrary provider extensions in the 0.1 public document;
using the idempotency key as a rate-limit identity;
exposing raw tenant, cookie, IP, or internal lease data;
promoting quantumJobApi or hardwareExecution to stable in this RFC alone.