Status: runtime experimental
Contract: 0.2.0-runtime-experimental
Feature flag: experimental.qmlTrainingControls=true
Stable 0.1 default: disabled
Owners: language and QML runtime

Problem

N/M train blocks can select an objective, optimizer, step count, loss, and embedded dataset. Dataset-backed execution reports one final validation result, but source cannot state when validation runs, when training should stop, how the learning rate changes, or which parameter state is considered the best checkpoint. Hiding those choices in a host UI makes experiments difficult to reproduce across Core, CLI, Worker, and Quantum AI Studio.

This RFC introduces a bounded source and runtime contract. The first parser-only stage established AST and diagnostic parity; the current runtime-experimental stage executes the controls deterministically for frozen supervised embedded-dataset splits while retaining explicit feature negotiation.

Proposed syntax

module qml_training_controls;
param theta: Angle = 0.1;

fn main() {
  let q: QReg<2> = qreg[2];
  encode(sample_row(), q, method: "reupload");
  CNOT(q[0], q[1]);
  X(q[1]);
  Ry(q[1], theta);
  let cost = expect Z(q[1]);

  train {
    objective: minimize cost;
    optimizer: adam(lr = 0.2);
    steps: 40;
    loss: cross_entropy;
    dataset: xor_2d;
    validation: split = validation, every = 5;
    early_stopping: metric = validation_loss, patience = 3, min_delta = 0.001;
    scheduler: step(every = 10, factor = 0.5, min_lr = 0.01);
    checkpoint: best(metric = validation_loss);
  }
  return cost;
}

Directive order is not semantic. Each directive can appear at most once.

AST contract

NMTrainBlock gains four optional fields:

validation: fixed split: "validation" and every in 1..100;
earlyStopping: metric, patience in 1..100, and finite minDelta in [0,1];
scheduler: kind: "step", every in 1..100, multiplicative factor in (0,1), and optional minimumLearningRate in [0,5];
checkpoint: strategy: "best" and a validation metric.

NMProgram.qmlTrainingControls records the feature negotiation and 0.2.0-runtime-experimental contract version. Existing train blocks have byte-equivalent AST and printer output when the feature flag is absent.

Semantic constraints

Every control requires a supervised dataset directive.
Validation, early stopping, and checkpointing use the embedded dataset's frozen validation split. Arbitrary source-defined split expressions are outside this RFC.
Early stopping and checkpointing require an explicit validation directive.
A cadence cannot exceed the declared training step count.
validation_accuracy is maximized; validation_loss is minimized.
The scheduler multiplies the current learning rate by factor at each interval and never goes below min_lr.
Validation runs after a completed update whenever completedSteps % every == 0, and once at the final completed step when it is not already on the cadence.
Early stopping counts consecutive non-improving validation checks, not optimizer steps. patience = 1 therefore stops after the first non-improving validation check.
Checkpoint ties keep the earliest best state. When checkpointing is enabled, the selected parameters are restored before final train and validation metrics are calculated.
A checkpoint is in-memory parameter metadata. This RFC does not define filesystem paths, remote object storage, resume tokens, or executable model deserialization.

Runtime-experimental rollout boundary

At contract 0.2.0-runtime-experimental, the feature flag enables parsing, canonical source printing, and deterministic local supervised execution. Runtime evidence records every validation checkpoint, effective learning-rate history, early-stop selection, completed/requested steps, and the best in-memory parameter checkpoint. Best checkpoint parameters are restored before the final train/validation result is reported.

The same opt-in is carried by CLI --experimental-qml-training-controls, LSP initializationOptions.nm.experimental.qmlTrainingControls, the VS Code nm.experimental.qmlTrainingControls setting, Worker run/train requests, and the Playground session toggle. Worker progress includes the effective learning rate. Cancelling a negotiated train request uses the existing train-cancel terminal path and terminates the request-scoped worker, so a cancelled result cannot overwrite newer UI state.

NM-QML-109 is the fail-closed runtime diagnostic for invalid, missing, or non-finite controlled-training evidence. Stable parsing remains disabled by default, so an unnegotiated source cannot silently opt into the runtime behavior.

Promotion beyond experimental still requires the current-candidate Windows/Linux and Node 20/22 conformance/performance matrix. Durable exact-GD checkpoint/resume is now defined separately by NM-RFC-0009; it is not silently implied by the in-memory checkpoint directive and does not change this source-syntax contract.

Diagnostics

Tablo 1
Code	Meaning
`NM-PARSE-060`	A training-control directive was used without explicit feature enable
`NM-PARSE-061`	A directive is malformed, duplicated, unknown, or outside its limit
`NM-QML-108`	Parsed controls form an incompatible train-block configuration
`NM-QML-109`	Runtime overrides, callbacks, or evidence violated the bounded contract

Compatibility and non-goals

Stable N/M 0.1 parsing and execution are unchanged.
Existing dataset-backed training and its final validation summary remain unchanged when no control directive is present.
This RFC does not add arbitrary datasets, k-fold validation, asynchronous checkpoint I/O, resume-after-crash, distributed training, metric expressions, scheduler composition, or unbounded callback execution.
The current runtime stage includes Core/CLI/LSP/VS Code/Worker/Playground negotiation, source-printer round trips, deterministic validation/early-stop/scheduler/checkpoint evidence, cancellation-safe Worker termination, EN/TR docs, a maximum-workload ratchet, and clean package exports. Broader promotion additionally requires current-candidate Windows/Linux and Node 20/22 matrix evidence.