Durable QML training checkpoints

• Status: runtime experimental
• Contract: 0.1-runtime-experimental
• Artifact: nm-training-checkpoint@0.1
• Schema: /schemas/nm-training-checkpoint-0.1.schema.json
• Stable 0.1 default: disabled
• Owners: QML runtime and tooling

Problem

NM-RFC-0004 restores the best validation parameters inside one supervised run, but it deliberately does not define a persistence format or resume behavior. Treating that in-memory metadata as a durable checkpoint would lose optimizer state, source identity, frozen dataset identity, and corruption evidence.

This RFC introduces a separate bounded artifact and continuation API. It does not change the N/M source grammar or the stable parser default.

Contract

An nm-training-checkpoint@0.1 document embeds:

• the exact N/M source and language version;
• expectation-objective or frozen supervised dataset identity;
• GD learning rate, objective, seed, completed step count, initial/current parameters, cost and parameter histories, and circuit-evaluation count;
• final validation/test evidence for supervised workloads;
• source, deterministic state, and whole-artifact FNV-1a digests;
• an explicit reproducibility mode and resume-boundary evaluation policy.

The JSON reader rejects unknown fields, future versions, malformed source, non-finite values, mismatched parameter names, inconsistent history lengths, unknown datasets, split drift, and digest mismatches.

Exact resume boundary

Contract 0.1 supports gd only. GD continuation needs the current parameter vector but no hidden momentum or moment estimate. The runtime patches the round-trippable parameter values into the original source, executes the bounded additional segment with the same learning rate and objective, verifies that the segment starts at the saved parameter/cost state, and then returns a new immutable checkpoint.

Momentum velocity, Adam moments, SPSA RNG position, and QNG metric state are not serialized in 0.1. Requests to create a durable checkpoint for momentum, adam, spsa, or qng fail with NM-QML-CHECKPOINT-004; the runtime never resets those states silently and never labels an approximate restart as exact resume.

Circuit-evaluation counts are segment-additive and include the extra evaluation at a resume boundary. Parameter and cost trajectories remain identical to uninterrupted GD execution; timing is excluded from deterministic identity.

Cancellation and persistence integrity

A checkpoint is emitted only after a complete successful segment. Resume never mutates its input document. Worker cancellation can terminate an active benchmark or training request before UI state is replaced, so a cancelled or partial segment cannot overwrite the last valid artifact.

FNV-1a detects accidental source/state/document corruption but is not a signature or authenticity proof. Remote object stores, concurrent writers, encrypted artifacts, and cryptographic signing are outside this contract.

Product surfaces

• Core exposes create, validate, import, serialize, resume, JSON Schema, and model-package conversion helpers.
• CLI provides nm checkpoint create, nm checkpoint resume, and nm checkpoint model; all write canonical JSON to stdout and leave input files unchanged.
• Quantum AI can download the successful GD member of a benchmark as the same checkpoint format.
• Model conversion uses the existing validated nm-model@0.1 contract instead of inventing a second inference format.

Diagnostics

Promotion boundary

The capability remains experimental. Preview consideration requires a current-candidate Windows/Linux and Node 20/22 conformance/performance matrix, a maximum 100-step carrier ratchet, and an explicit decision on whether a later version serializes Momentum/Adam/SPSA/QNG optimizer state.