Status: runtime-experimental Contract: 0.2.0-runtime-experimental Default: disabled Owner: language / runtime

1. Problem

N/M 0.1 parses return as a structural statement, but the browser runtime does not publish its value. The public SimulationResult.success field therefore describes engine execution only and cannot represent a deliberate user-program error without being confused with a parser, compiler, worker, or simulator failure.

NM-RFC-0007 adds an explicitly negotiated result contract for the current executable entry point:

module typed_result;

fn main() -> Result<Int, Error> {
  let q = qreg[1];
  let measured: Bit = measure(q[0]);
  let encoded: Int = bit_to_int(measured);
  return ok(encoded);
}

A deliberate program error uses a bounded symbolic code:

return error("NO_VALID_SAMPLE");

Stable N/M 0.1 behavior is unchanged. The signature and typed returns are accepted only when experimental.functionResults=true is negotiated. Typed expressions reuse the NM-RFC-0005 classical value semantics; a caller must negotiate typedClassicalValues as well when the source declares Int, Float, or bounded arrays.

2. Type and control-flow contract

The signature is exactly fn main() -> Result<T, Error>.
T is Bit, Int, Float, Array<Bit,N>, Array<Int,N>, or Array<Float,N> with N in 1..256.
Contract 0.2 requires exactly one final top-level return ok(expression); or return error("CODE");.
Branch, loop, match, observe, test, property, and snapshot returns are rejected. This keeps outcome selection deterministic until function-local control-flow analysis is versioned.
Error codes use ASCII upper snake case, begin with A-Z, and contain at most 64 UTF-8 bytes. Free-form messages and stack traces are not part of the user result.
No implicit Bit/Int/Float or array conversion occurs.

Only main is executable in the current runtime. Named functions, parameters, recursion, higher-order results, generic error types, ? propagation, and exhaustive result matching require later RFCs.

3. Engine and program outcome separation

SimulationResult.success continues to mean that parsing, validation, compilation, worker transport, and simulation completed successfully. A negotiated execution additionally publishes programResult:

json

{
  "success": true,
  "programResult": {
    "contractVersion": "0.2.0-runtime-experimental",
    "status": "error",
    "error": { "code": "NO_VALID_SAMPLE" },
    "line": 5
  }
}

programResult.status === "error" does not change engine success to false. Parser/type/runtime failures never fabricate a user-program error result. This invariant is identical in Core, Worker, CLI JSON, and Playground output.

4. Diagnostics

Tablo 1
Code	Meaning
`NM-PARSE-066`	Typed result syntax was used without explicit negotiation.
`NM-PARSE-067`	Signature, result type, return form, or error code is malformed or out of bounds.
`NM-TYPE-025`	`ok(...)` does not exactly match the declared result type.
`NM-TYPE-026`	Return is missing, duplicated, non-final, or nested in unsupported control flow.
`NM-RUNTIME-033`	A previously validated result expression failed at runtime.

All diagnostics are errors. The runtime must not coerce a value, convert a runtime failure into error("..."), continue after a result, or publish partial programResult evidence.

5. Carrier and compatibility

The AST, canonical printer, JSON IR, and strict OpenQASM 3 sidecar preserve the declared Result<T, Error> type and typed return expression. OpenQASM 2 has no equivalent program-result contract and must reject negotiated sources rather than silently erase it.

Unknown result fields, result kinds, types, error shapes, or future contract versions fail closed. No persistent migration promise applies while the capability is experimental.

6. Non-goals

exception throwing, catch/finally, stack traces, or free-form error text;
treating parser/compiler/runtime diagnostics as user error values;
arbitrary named function execution, recursion, or generic functions;
implicit numeric conversion or dynamic arrays;
branch-sensitive return analysis and result propagation operators;
mapping a user error code to HTTP status, process failure, or provider failure.