oraql-contracts 0.1.0__py3-none-any.whl

oraql/contracts/contract_examples.py

@@ -0,0 +1,73 @@
+"""One valid example instance per contract (a 2-atom Bell-pair program), numbers computed here."""
+import math, json, hashlib
+
+def sha(o):
+    return hashlib.sha256(json.dumps(o, sort_keys=True).encode()).hexdigest()[:16]
+
+def examples():
+    t2, t1 = 1000.0, 5.0e6          # us, assumed values for the example only
+    t_cz = 0.4                       # us, assumed
+    pauli2 = [0.0] * 15
+    pauli2[14] = 2e-3                # ZZ
+    pauli2[2] = 1e-3                 # IZ
+    pauli2[11] = 1e-3                # ZI
+    phys = {
+        "schema_version": "0.1.0", "profile_id": "example", "species": "Rb87",
+        "sites": [{"id": 0, "x": 0.0, "y": 0.0, "zone": "entangling", "trap": "tweezer_array"},
+                  {"id": 1, "x": 4.0, "y": 0.0, "zone": "entangling", "trap": "tweezer_array"}],
+        "parameters": [
+            {"name": "t2_us", "value": t2, "unit": "us", "source": "assumed", "valid_lo": 1.0, "valid_hi": 1e6},
+            {"name": "blockade_radius_um", "value": 8.0, "unit": "um", "source": "assumed"},
+            {"name": "c6_ghz_um6", "value": 30.0, "unit": "GHz*um^6", "source": "computed",
+             "method": "ARC 3.x, PairStateInteractions(Rubidium87, 53,0,0.5, ...).getC6perturbatively", "note": "illustrative value"},
+        ]}
+    upd = {"schema_version": "0.1.0", "experiment_id": "ramsey-0001", "experiment_kind": "ramsey_t2",
+           "timestamp": "2026-10-08T12:00:00Z", "data_ref": "data/ramsey-0001.csv",
+           "fits": [{"name": "t2_us", "value": 950.0, "unit": "us", "stderr": 30.0, "reduced_chi2": 1.1}],
+           "updates": [{"name": "t2_us", "old_value": 1000.0, "new_value": 950.0, "unit": "us", "prior_weight": 0.2}]}
+    cal = {"schema_version": "0.1.0", "physical_ref": sha(phys), "cz_protocol": "time_optimal_two_pulse",
+           "generated_at": "2026-10-08T12:05:00Z",
+           "primitives": [
+               {"primitive": "rz", "arity": 1, "duration_us": 0.0, "pauli1": {"px": 0.0, "py": 0.0, "pz": 1e-5}, "p_loss": [0.0]},
+               {"primitive": "cz", "arity": 2, "duration_us": t_cz, "pauli2": {"p": pauli2},
+                "p_loss": [2e-3, 2e-3], "p_loss_corr": [1e-4, 1e-3, 0.05], "twirl_residual": 3e-4}],
+           "idle": {"t1_us": t1, "t2_us": t2, "loss_rate_per_us": 1e-7},
+           "readout": {"p_flip_0to1": 0.002, "p_flip_1to0": 0.01, "p_loss_readout": 0.003, "duration_us": 5000.0},
+           "approximations": [{"kind": "coherent_error", "bound": 3e-4, "note": "twirled, coherent part dropped"},
+                              {"kind": "leakage_as_loss", "note": "Rydberg decay treated as loss"}]}
+    ops = [
+        {"op_id": 0, "name": "rx", "targets": [0], "params": [math.pi / 2], "start_us": 0.0, "duration_us": 0.5, "source_op": 0,
+         "noise": [{"kind": "pauli1", "targets": [0], "p": [0.0, 0.0, 1e-5]}], "spectators": [1]},
+        {"op_id": 1, "name": "cz", "targets": [0, 1], "start_us": 0.5, "duration_us": t_cz, "source_op": 1, "parallel_group": 0, "zone": "entangling",
+         "noise": [{"kind": "pauli2", "targets": [0, 1], "p": pauli2},
+                   {"kind": "loss", "targets": [0], "p": [2e-3]}, {"kind": "loss", "targets": [1], "p": [2e-3]}]},
+        {"op_id": 2, "name": "measure", "targets": [0], "start_us": 0.9, "duration_us": 5000.0, "source_op": 2, "measure_slot": 0,
+         "noise": [{"kind": "readout_flip", "targets": [0], "p": [0.002]}, {"kind": "loss", "targets": [0], "p": [0.003]}]},
+        {"op_id": 3, "name": "measure", "targets": [1], "start_us": 0.9, "duration_us": 5000.0, "source_op": 2, "measure_slot": 1, "parallel_group": 1,
+         "noise": [{"kind": "readout_flip", "targets": [1], "p": [0.002]}, {"kind": "loss", "targets": [1], "p": [0.003]}]},
+    ]
+    nat = {"schema_version": "0.1.0", "n_atoms": 2, "calibration_ref": sha(cal), "ops": ops, "total_duration_us": 5000.9, "diagnostics": []}
+    doc = {"format_version": "0.1.0", "dialect": "nadsl", "n_qubits": 2,
+           "statements": [
+               {"kind": "gate", "name": "rx", "targets": [0], "args": [math.pi / 2]},
+               {"kind": "gate", "name": "cz", "targets": [0, 1]},
+               {"kind": "measure", "name": "m", "targets": [0, 1]}],
+           "text": "rx(1.5707963267948966) 0\ncz 0 1\nm 0 1\n"}
+    low = {"schema_version": "0.1.0", "circuit_ref": sha(doc), "native_target": "gemini_one_zone", "calibration_ref": sha(cal),
+           "qubit_map": [{"circuit_qubit": 0, "atom_id": 0}, {"circuit_qubit": 1, "atom_id": 1}],
+           "lowered": [{"circuit_op": 0, "native_ops": [0], "rule": "identity", "exact": True, "feed_forward": "none"},
+                       {"circuit_op": 1, "native_ops": [1], "rule": "identity", "exact": True, "feed_forward": "none"},
+                       {"circuit_op": 2, "native_ops": [2, 3], "rule": "measure_all", "exact": True, "feed_forward": "none"}],
+           "scheduler": "asap", "native_program_ref": sha(nat), "diagnostics": []}
+    logical = {"schema_version": "0.1.0",
+               "blocks": [{"block_id": 0, "code": "repetition", "distance": 3, "data_qubits": [0, 1, 2], "ancilla_qubits": [3, 4],
+                           "rounds": 1, "stabilizers": ["ZZI", "IZZ"]}],
+               "detectors": [{"id": 0, "meas_indices": [0]}, {"id": 1, "meas_indices": [1]}],
+               "observables": [{"id": 0, "meas_indices": [2]}], "loss_policy": "erasure_decode", "circuit_ref": sha(doc)}
+    req = {"schema_version": "0.1.0", "native_program_ref": sha(nat), "backend": "GT", "emit_mode": "python_api", "shots": 100000, "seed": 1,
+           "truncation": {"min_abs_coeff": 1e-10}}
+    res = {"schema_version": "0.1.0", "request_ref": sha(req), "backend": "GT", "outcomes": [[0, 0], [1, 1], [2, 0]], "measure_labels": [0, 1],
+           "std_error": 0.003, "lost_fraction": [0.003, 0.003],
+           "truncation_report": {"biased_low": False}, "diagnostics": []}
+    return {"PhysicalParameters": phys, "CalibrationUpdate": upd, "CalibrationRecord": cal, "NativeProgram": nat,
+            "CircuitLowering": low, "LogicalLowering": logical, "ProgramDocument": doc, "BackendRequest": req, "BackendResult": res}

oraql/contracts/contracts.py

@@ -0,0 +1,466 @@
+"""Single source of truth for the interface contracts of the neutral-atom DSL stack.
+
+Everything else is generated from this module:
+  - packages/oraql-contracts/src/oraql/contracts/data/schemas/*.json        (JSON Schema, draft 2020-12)
+  - the contract tables in design/01_architecture.md
+  - the dependency diagram (scripts/architecture_diagram.py)
+Run `python -m scripts.build_architecture` from the repo root to regenerate.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+
+BASE_URI = "https://nadsl.local/schemas/"
+UNIT_NONE = "1"
+
+
+@dataclass
+class F:
+    """One typed field. type grammar: number | integer | string | boolean | enum:a|b|c |
+    ref:Record | array<T> (T any of the above). n fixes an array length."""
+    name: str
+    type: str
+    unit: str = UNIT_NONE
+    rng: tuple | None = None
+    desc: str = ""
+    req: bool = True
+    n: int | None = None
+
+
+@dataclass
+class Record:
+    name: str
+    file: str
+    desc: str
+    fields: list[F]
+
+
+@dataclass
+class Contract:
+    name: str          # root record name, also the diagram node label
+    file: str          # schema file
+    layers: tuple      # (producer layer id, consumer layer id)
+    pair: str          # interface it belongs to
+    producer: str
+    consumer: str
+    status: str        # existing format / adapter / new
+    reuse: str
+    invariants: list[str]
+
+
+LAYERS = {
+    "L1": "Physical hardware and array",
+    "L2": "Pulse and calibration",
+    "L3": "Native gates and movement",
+    "L4": "Circuit",
+    "L5": "Logical / QEC",
+    "B": "PPVM backend",
+}
+
+P = (0.0, 1.0)
+
+RECORDS: list[Record] = [
+    # ---------------------------------------------------------------- common
+    Record("Diagnostic", "common.json", "A compile or validation message. Unsupported constructs are never dropped silently.", [
+        F("code", "string", desc="stable id, for example `PPVM-UNSUPPORTED-COHERENT`"),
+        F("severity", "enum:error|warning|info"),
+        F("construct", "string", desc="name of the construct, for example `coherent_crosstalk`"),
+        F("layer", "enum:L1|L2|L3|L4|L5|B", desc="layer that raised it"),
+        F("message", "string"),
+        F("location", "string", desc="op id, statement index or parameter name", req=False),
+        F("reduction", "string", desc="approximation applied instead, when severity is warning", req=False),
+    ]),
+    Record("Pauli1Probs", "common.json", "Single-qubit Pauli channel, PPVM `pauli_error(p=[px,py,pz])`.", [
+        F("px", "number", rng=P, desc="X error probability"),
+        F("py", "number", rng=P, desc="Y error probability"),
+        F("pz", "number", rng=P, desc="Z error probability"),
+    ]),
+    Record("Pauli2Probs", "common.json", "Two-qubit Pauli channel, PPVM `two_qubit_pauli_error(p=[...15])`.", [
+        F("p", "array<number>", rng=P, n=15, desc="order IX IY IZ XI XX XY XZ YI YX YY YZ ZI ZX ZY ZZ, identity is 1 minus the sum"),
+    ]),
+    Record("ApproximationNote", "common.json", "A recorded reduction of a physical effect to Pauli+loss.", [
+        F("kind", "enum:coherent_error|leakage|leakage_as_loss|amplitude_damping_twirl|crosstalk|motional_heating|readout_flip|state_dependent_loss|other"),
+        F("bound", "number", rng=(0.0, 1.0), desc="norm bound on what was discarded, dimensionless", req=False),
+        F("note", "string"),
+    ]),
+    # ---------------------------------------------------------------- C1
+    Record("PhysicalParameters", "physical_parameters.json", "Parameters of atoms, traps, interaction and hardware. Produced by L1, consumed by L2.", [
+        F("schema_version", "string", desc="semver of this schema"),
+        F("profile_id", "string", desc="named device profile, for example `rb87_evered2023`"),
+        F("species", "string", desc="for example `Rb87`"),
+        F("sites", "array<ref:Site>", desc="atom array geometry"),
+        F("parameters", "array<ref:ParameterEntry>", desc="named parameters, names fixed in 02_physical.md"),
+    ]),
+    Record("Site", "physical_parameters.json", "One trap site.", [
+        F("id", "integer", rng=(0, None), desc="atom or site index, unique"),
+        F("x", "number", unit="um", desc="x position"),
+        F("y", "number", unit="um", desc="y position"),
+        F("zone", "string", desc="storage, entangling or readout zone name"),
+        F("trap", "enum:slm|aod|tweezer_array"),
+    ]),
+    Record("ParameterEntry", "physical_parameters.json", "One physical parameter with its provenance.", [
+        F("name", "string", desc="for example `t2_us`, `c6`, `blockade_radius_um`"),
+        F("value", "number", unit="per entry `unit`", desc="value in the unit stated by `unit`"),
+        F("unit", "string", desc="unit string, for example `us`, `um`, `MHz`, `rad/us*um^6`"),
+        F("source", "enum:citation|computed|assumed|calibrated", desc="the `assumed` flag is mandatory for unsourced values"),
+        F("citation", "string", desc="DOI or arXiv id, required when source is citation", req=False),
+        F("method", "string", desc="package, version and call, required when source is computed", req=False),
+        F("locator", "string", desc="figure, table or page in the cited work", req=False),
+        F("note", "string", desc="free text: derivation, bound or reason for an assumption", req=False),
+        F("uncertainty", "number", unit="per entry `unit`", rng=(0, None), desc="1 sigma", req=False),
+        F("valid_lo", "number", unit="per entry `unit`", desc="lowest physical value", req=False),
+        F("valid_hi", "number", unit="per entry `unit`", desc="highest physical value", req=False),
+    ]),
+    # ---------------------------------------------------------------- C2
+    Record("CalibrationUpdate", "calibration_update.json", "Fitted result of one calibration experiment and the parameter updates it implies. Produced from L1 data, consumed by L2.", [
+        F("schema_version", "string"),
+        F("experiment_id", "string"),
+        F("experiment_kind", "enum:ramsey_t2|rabi|t1|cz_benchmark|loss_scan|readout_histogram|other"),
+        F("timestamp", "string", desc="ISO 8601, UTC"),
+        F("data_ref", "string", desc="path or URI of raw data or the plot image (QCalEval style)", req=False),
+        F("fits", "array<ref:FitResult>"),
+        F("updates", "array<ref:ParameterUpdate>"),
+    ]),
+    Record("FitResult", "calibration_update.json", "One fitted quantity.", [
+        F("name", "string", desc="must match a `ParameterEntry.name`"),
+        F("value", "number", unit="per `unit`"),
+        F("unit", "string"),
+        F("stderr", "number", unit="per `unit`", rng=(0, None)),
+        F("reduced_chi2", "number", rng=(0, None), desc="goodness of fit", req=False),
+    ]),
+    Record("ParameterUpdate", "calibration_update.json", "Change applied to a `PhysicalParameters` entry.", [
+        F("name", "string"),
+        F("old_value", "number", unit="per `unit`"),
+        F("new_value", "number", unit="per `unit`"),
+        F("unit", "string"),
+        F("prior_weight", "number", rng=P, desc="weight of the old value in a Bayesian blend"),
+    ]),
+    # ---------------------------------------------------------------- C3
+    Record("CalibrationRecord", "calibration_record.json", "Pauli+loss channels per native primitive, exactly as PPVM consumes them. Produced by L2, consumed by L3.", [
+        F("schema_version", "string"),
+        F("physical_ref", "string", desc="sha256 of the `PhysicalParameters` document it was derived from"),
+        F("cz_protocol", "string", desc="pluggable CZ implementation id, default `time_optimal_two_pulse`"),
+        F("generated_at", "string", desc="ISO 8601, UTC"),
+        F("primitives", "array<ref:PrimitiveChannel>"),
+        F("idle", "ref:IdleModel", desc="rates for spectators and waiting atoms"),
+        F("readout", "ref:ReadoutModel"),
+        F("approximations", "array<ref:ApproximationNote>", desc="everything the twirl discarded"),
+    ]),
+    Record("PrimitiveChannel", "calibration_record.json", "Noise attached to one native primitive.", [
+        F("primitive", "enum:rz|rx|ry|r|global_r|cz|move|reset", desc="native primitive name"),
+        F("arity", "integer", rng=(1, 2)),
+        F("duration_us", "number", unit="us", rng=(0, None)),
+        F("pauli1", "ref:Pauli1Probs", desc="present when arity is 1, per target qubit", req=False),
+        F("pauli2", "ref:Pauli2Probs", desc="present when arity is 2", req=False),
+        F("p_loss", "array<number>", rng=P, desc="independent loss probability per target, length equals arity"),
+        F("p_loss_corr", "array<number>", rng=P, n=3, desc="optional [p0,p1,p2] of `correlated_loss_channel`, arity 2 only", req=False),
+        F("p_leak", "array<number>", rng=P, desc="part of `p_loss` per target that stays trapped in a non-qubit sublevel (leaked: dark to later gates until a reset, read as a classical bit); the rest is lost", req=False),
+        F("p_out_joint", "array<number>", rng=P, n=8, desc="arity 2: joint probabilities of the two atoms ending in qubit (q), leaked (k) or lost (l), cells qk ql kq kk kl lq lk ll (first letter = first target); q,q is 1 minus the sum", req=False),
+        F("p_out_alone", "array<number>", rng=P, n=2, desc="arity 2: [leaked, lost] of an atom whose partner is already gone (single-atom pulse); its sum is p2 of `p_loss_corr`", req=False),
+        F("twirl_residual", "number", rng=P, desc="norm of the discarded non-Pauli part of the simulated process", req=False),
+    ]),
+    Record("IdleModel", "calibration_record.json", "Idle noise as a function of waiting time t. Consumers evaluate it at t.", [
+        F("t1_us", "number", unit="us", rng=(0, None)),
+        F("t2_us", "number", unit="us", rng=(0, None)),
+        F("loss_rate_per_us", "number", unit="1/us", rng=(0, None), desc="trap lifetime loss, p_loss(t) = 1 - exp(-rate t)"),
+    ]),
+    Record("ReadoutModel", "calibration_record.json", "Measurement errors.", [
+        F("p_flip_0to1", "number", rng=P, desc="P(report 1 given 0)"),
+        F("p_flip_1to0", "number", rng=P, desc="P(report 0 given 1)"),
+        F("p_loss_readout", "number", rng=P, desc="loss during imaging"),
+        F("p_leak_reads_one", "number", rng=P, desc="probability that a leaked atom reads as 1", req=False),
+        F("duration_us", "number", unit="us", rng=(0, None)),
+    ]),
+    # ---------------------------------------------------------------- C4
+    Record("NativeProgram", "native_program.json", "Scheduled native ops, each with its noise attached. Produced by L3, consumed by the backend.", [
+        F("schema_version", "string"),
+        F("n_atoms", "integer", rng=(1, 2048), desc="PPVM `MAX_N_QUBITS` is 2048"),
+        F("calibration_ref", "string", desc="sha256 of the `CalibrationRecord` used"),
+        F("ops", "array<ref:NativeOpRecord>", desc="ordered by start_us, then op_id"),
+        F("total_duration_us", "number", unit="us", rng=(0, None), desc="critical path of the schedule"),
+        F("diagnostics", "array<ref:Diagnostic>", req=False),
+    ]),
+    Record("NativeOpRecord", "native_program.json", "The native-op-with-noise record.", [
+        F("op_id", "integer", rng=(0, None), desc="unique, increasing"),
+        F("name", "enum:rz|rx|ry|r|global_r|cz|move|idle|measure|reset"),
+        F("targets", "array<integer>", desc="atom ids"),
+        F("params", "array<number>", unit="rad", desc="rotation angles, or move vector in um for `move`", req=False),
+        F("start_us", "number", unit="us", rng=(0, None)),
+        F("duration_us", "number", unit="us", rng=(0, None)),
+        F("zone", "string", desc="zone in which the op acts", req=False),
+        F("parallel_group", "integer", rng=(0, None), desc="ops with equal group run simultaneously", req=False),
+        F("spectators", "array<integer>", desc="atoms that idle during this op and receive idle noise", req=False),
+        F("noise", "array<ref:NoiseChannel>", desc="channels applied after the ideal op, in order"),
+        F("source_op", "integer", rng=(-1, None), desc="index of the circuit statement it came from, -1 if inserted by the scheduler"),
+        F("measure_slot", "integer", rng=(0, None), desc="position in the measurement record, `measure` only", req=False),
+    ]),
+    Record("NoiseChannel", "native_program.json", "One PPVM channel. `p` has a fixed length per kind.", [
+        F("kind", "enum:pauli1|pauli2|loss|correlated_loss|asymmetric_loss|reset_loss|amplitude_damping|readout_flip|leak|correlated_leak_loss",
+          desc="p length: pauli1 3, pauli2 15, loss 1, correlated_loss 3, asymmetric_loss 2, reset_loss 0, amplitude_damping 1, readout_flip 1, "
+               "leak 2 ([p, p_reads_one]), correlated_leak_loss 11 (the 8 cells of `p_out_joint`, the 2 of `p_out_alone`, p_reads_one). "
+               "A leaked atom skips later gates like a lost one, a reset returns it to the qubit, and its measurement gives 1 with p_reads_one"),
+        F("targets", "array<integer>", desc="atom ids, 1 or 2 depending on kind"),
+        F("p", "array<number>", rng=P, desc="probabilities, see kind"),
+    ]),
+    # ---------------------------------------------------------------- C5
+    Record("CircuitLowering", "circuit_lowering.json", "Result of lowering a circuit to the native set. Produced by the L3 compiler from an L4 circuit.", [
+        F("schema_version", "string"),
+        F("circuit_ref", "string", desc="sha256 of the canonical `ProgramDocument` text"),
+        F("native_target", "string", desc="native gate set id, for example `gemini_one_zone`"),
+        F("calibration_ref", "string"),
+        F("qubit_map", "array<ref:QubitPlacement>"),
+        F("lowered", "array<ref:LoweredOp>"),
+        F("scheduler", "enum:asap|alap|layered"),
+        F("native_program_ref", "string", desc="sha256 of the resulting `NativeProgram`"),
+        F("diagnostics", "array<ref:Diagnostic>"),
+    ]),
+    Record("QubitPlacement", "circuit_lowering.json", "Circuit qubit to atom.", [
+        F("circuit_qubit", "integer", rng=(0, None)),
+        F("atom_id", "integer", rng=(0, None), desc="`Site.id`"),
+    ]),
+    Record("LoweredOp", "circuit_lowering.json", "Provenance of one circuit statement.", [
+        F("circuit_op", "integer", rng=(0, None), desc="statement index"),
+        F("native_ops", "array<integer>", desc="`NativeOpRecord.op_id` list"),
+        F("rule", "string", desc="rewrite rule id, for example `cx_to_h_cz_h`"),
+        F("exact", "boolean", desc="equal to the source up to global phase"),
+        F("approx_error", "number", rng=P, desc="unitary infidelity bound when not exact", req=False),
+        F("feed_forward", "enum:none|outcome|loss_flag", desc="classical condition kept on the lowered ops"),
+    ]),
+    # ---------------------------------------------------------------- C6
+    Record("LogicalLowering", "logical_lowering.json", "Logical program expanded to a physical circuit. Produced by L5, consumed by L4.", [
+        F("schema_version", "string"),
+        F("blocks", "array<ref:CodeBlock>"),
+        F("detectors", "array<ref:Detector>"),
+        F("observables", "array<ref:LogicalObservable>"),
+        F("loss_policy", "enum:erasure_decode|postselect|ignore", desc="how LOST outcomes are used by the decoder"),
+        F("circuit_ref", "string", desc="sha256 of the emitted physical `ProgramDocument`"),
+    ]),
+    Record("CodeBlock", "logical_lowering.json", "One code block.", [
+        F("block_id", "integer", rng=(0, None)),
+        F("code", "enum:repetition|css_4_2_2|bacon_shor|five_qubit|surface_patch|distillation_15to1|other"),
+        F("distance", "integer", rng=(1, None)),
+        F("data_qubits", "array<integer>", desc="circuit qubit ids"),
+        F("ancilla_qubits", "array<integer>", desc="circuit qubit ids"),
+        F("rounds", "integer", rng=(0, None), desc="syndrome rounds"),
+        F("stabilizers", "array<string>", desc="Pauli words over `data_qubits` positions, for example `ZZI`"),
+    ]),
+    Record("Detector", "logical_lowering.json", "Parity of measurement records that is deterministic without noise (Stim `DETECTOR`).", [
+        F("id", "integer", rng=(0, None)),
+        F("meas_indices", "array<integer>", desc="absolute indices into the measurement record"),
+        F("coords", "array<number>", unit="um or round index", req=False),
+    ]),
+    Record("LogicalObservable", "logical_lowering.json", "Logical observable (Stim `OBSERVABLE_INCLUDE`).", [
+        F("id", "integer", rng=(0, None)),
+        F("meas_indices", "array<integer>"),
+    ]),
+    # ---------------------------------------------------------------- C7
+    Record("ProgramDocument", "program_document.json", "Structured form of a DSL program. The builder produces it, the printer renders it, the parser reads it back. Lives at L4.", [
+        F("format_version", "string"),
+        F("dialect", "enum:nadsl|stim|bloqade_squin|openqasm3", desc="dialect of `text`"),
+        F("n_qubits", "integer", rng=(1, 2048)),
+        F("statements", "array<ref:Statement>"),
+        F("text", "string", desc="canonical printed form, `parse(text)` reproduces `statements`"),
+    ]),
+    Record("Statement", "program_document.json", "One statement of the program.", [
+        F("kind", "enum:gate|noise|loss|measure|reset|feed_forward|detector|observable|tick|repeat|annotation"),
+        F("name", "string", desc="lower case op name, PPVM or Stim spelling"),
+        F("targets", "array<integer>", desc="circuit qubit ids, or measurement offsets for detectors"),
+        F("args", "array<number>", unit="rad for angles, 1 for probabilities", desc="arguments", req=False),
+        F("condition", "string", desc="feed-forward predicate, for example `rec[-1]` or `lost(3)`", req=False),
+        F("body", "array<integer>", desc="statement indices inside a `repeat`", req=False),
+        F("repeat_count", "integer", rng=(1, None), req=False),
+    ]),
+    # ---------------------------------------------------------------- C8
+    Record("BackendRequest", "backend_request.json", "What the backend is asked to compute. Produced by L3 or L4 drivers, consumed by the backend.", [
+        F("schema_version", "string"),
+        F("native_program_ref", "string", desc="sha256 of the `NativeProgram`"),
+        F("backend", "enum:GT|GTS|PS|LPS", desc="PPVM class"),
+        F("emit_mode", "enum:python_api|stim_text", desc="stim_text only if the program has no loss, rotations or feed-forward"),
+        F("shots", "integer", rng=(1, None), desc="sampled backends only", req=False),
+        F("seed", "integer", rng=(0, None), req=False),
+        F("observable", "string", desc="Pauli word for PS and LPS, for example `Z0Z1`", req=False),
+        F("truncation", "ref:Truncation"),
+    ]),
+    Record("Truncation", "backend_request.json", "PPVM truncation settings.", [
+        F("min_abs_coeff", "number", rng=(0, None), desc="drop terms below this magnitude, PPVM default 1e-10"),
+        F("max_pauli_weight", "integer", rng=(1, None), desc="PS and LPS only", req=False),
+        F("max_loss_weight", "integer", rng=(0, None), desc="LPS only", req=False),
+        F("preserve_strings", "array<string>", desc="Pauli words never truncated, PS and LPS only", req=False),
+    ]),
+    # ---------------------------------------------------------------- C9
+    Record("BackendResult", "backend_result.json", "Outcome of a backend run. Produced by the backend, consumed by L4 and L5.", [
+        F("schema_version", "string"),
+        F("request_ref", "string", desc="sha256 of the `BackendRequest`"),
+        F("backend", "enum:GT|GTS|PS|LPS"),
+        F("outcomes", "array<array<integer>>", rng=(0, 2), desc="shots x measurements, 0 ZERO, 1 ONE, 2 LOST", req=False),
+        F("measure_labels", "array<integer>", desc="`measure_slot` of each column", req=False),
+        F("expectation", "number", desc="PS and LPS: overlap with |0..0>", req=False),
+        F("std_error", "number", rng=(0, None), desc="sampled backends: standard error, PS and LPS: 0", req=False),
+        F("lost_fraction", "array<number>", rng=P, desc="per measured atom", req=False),
+        F("truncation_report", "ref:TruncationReport"),
+        F("diagnostics", "array<ref:Diagnostic>"),
+    ]),
+    Record("TruncationReport", "backend_result.json", "Effect of truncation.", [
+        F("n_terms", "integer", rng=(0, None), desc="Pauli terms at the end, PS and LPS", req=False),
+        F("max_weight_seen", "integer", rng=(0, None), req=False),
+        F("biased_low", "boolean", desc="true if any truncation was active, magnitudes are then underestimated"),
+    ]),
+]
+
+CONTRACTS: list[Contract] = [
+    Contract("PhysicalParameters", "physical_parameters.json", ("L1", "L2"), "L1-L2", "L1 parameter store (ARC, literature, assumed)", "L2 twirl and calibration",
+             "new", "values imported from ARC (Python API); Pulser `Register` JSON for `sites` import and export",
+             ["Every `ParameterEntry` has a unit; `source=citation` requires `citation`; `source=assumed` is never promoted without a `CalibrationUpdate`.",
+              "`valid_lo <= value <= valid_hi` when both are given.",
+              "`Site.id` is unique and `Site` coordinates are in um."]),
+    Contract("CalibrationUpdate", "calibration_update.json", ("L1", "L2"), "L1-L2", "calibration experiment fit (data from L1)", "L2 parameter store",
+             "new", "plot and data references follow the QCalEval layout; fit result shape borrowed from Qibocal and Qiskit Experiments",
+             ["`FitResult.name` matches a `ParameterEntry.name`; units agree.",
+              "`ParameterUpdate.new_value` lies in `[valid_lo, valid_hi]` of that entry, or the update is rejected with a `Diagnostic`.",
+              "Updates are append-only, `old_value` equals the value at the time."]),
+    Contract("CalibrationRecord", "calibration_record.json", ("L2", "L3"), "L2-L3", "L2 Lindblad simulation plus Pauli twirl", "L3 scheduler",
+             "adapter", "convertible to and from `GeminiNoiseModelABC` fields of bloqade-circuit (same 15-key two-qubit order as PPVM); `p` lists map one to one to PPVM `pauli_error`, `two_qubit_pauli_error`, `loss_channel`, `correlated_loss_channel`",
+             ["All probabilities are in [0,1]; `px+py+pz <= 1`; the 15 entries of `pauli2.p` sum to at most 1.",
+              "Two-qubit order is IX IY IZ XI XX XY XZ YI YX YY YZ ZI ZX ZY ZZ.",
+              "If `p_loss_corr = [p0,p1,p2]` is present then `p0 + 2*p1 <= 1`.",
+              "`len(p_loss) == arity`; `p_leak`, when present, has the same length and `p_leak <= p_loss` per target.",
+              "If `p_out_joint` is present then its sum is at most 1; its cells with both atoms out sum to `p0` of `p_loss_corr`, those with one out to `2*p1`.",
+              "Pure dephasing reduces to `pz = (1 - exp(-t/t2))/2`, `px = py = 0` (checked in the 03 spec).",
+              "Every discarded effect appears in `approximations`."]),
+    Contract("NativeProgram", "native_program.json", ("L3", "B"), "L3-B", "L3 scheduler", "backend lowering",
+             "adapter", "ops map to bloqade-lanes `.sst` and QMAP `.naviz` schedules for the ideal part; noise attaches in `NoiseChannel`",
+             ["Ops with the same `parallel_group` have equal `start_us` and disjoint `targets`.",
+              "No two ops on the same atom overlap in time: `start_us + duration_us <= next start_us` per atom.",
+              "`total_duration_us == max(start_us + duration_us)`.",
+              "`len(NoiseChannel.p)` equals the length stated for its `kind`; every channel is a valid distribution.",
+              "Every spectator in `spectators` is not a target of any op in the same time slice.",
+              "`measure` ops carry a unique `measure_slot`."]),
+    Contract("CircuitLowering", "circuit_lowering.json", ("L4", "L3"), "L3-L4", "L3 compiler", "L4 users and L3 scheduler",
+             "adapter", "input is a `ProgramDocument` (Stim, OpenQASM 3, Qiskit, Cirq or Bloqade squin import); output feeds bloqade-lanes or QMAP when the placement is delegated",
+             ["`qubit_map` is injective.",
+              "Every circuit statement index appears in exactly one `LoweredOp`.",
+              "If `exact` is false then `approx_error` is present.",
+              "Every `native_ops` id exists in the referenced `NativeProgram`.",
+              "A statement with `feed_forward != none` keeps its classical condition on every lowered op."]),
+    Contract("LogicalLowering", "logical_lowering.json", ("L5", "L4"), "L4-L5", "L5 code library", "L4 circuit builder",
+             "adapter", "emits Stim-compatible `DETECTOR` and `OBSERVABLE_INCLUDE` semantics (Stim, tqec); decoder input is a Stim DEM for PyMatching",
+             ["Data and ancilla qubit ids are disjoint within a block and across blocks.",
+              "`len(stabilizers[i]) == len(data_qubits)`; stabilizers commute.",
+              "Each detector is deterministic in the noiseless circuit.",
+              "Repetition code of distance d has d data, d-1 ancilla qubits and 2(d-1) CZ per round with a CZ-based syndrome extraction (counted in 06 spec).",
+              "`loss_policy=erasure_decode` requires the backend to return `LOST` outcomes (backend GT)."]),
+    Contract("ProgramDocument", "program_document.json", ("L4", "L3"), "L3-L4", "L4 builder or parser", "L3 compiler, printer, exporters",
+             "existing", "text dialects `stim` (Stim text, loss rejected), `openqasm3`, `bloqade_squin` import and export; the `nadsl` dialect is Stim-like text extended with loss, rotations and feed-forward",
+             ["Round trip: `parse(print(doc)).statements == doc.statements` for dialect `nadsl`.",
+              "`n_qubits` bounds every target.",
+              "A `loss` statement is never exported to dialect `stim`; the exporter raises a `Diagnostic` naming the construct.",
+              "Feed-forward `condition` is `rec[-k]` or `lost(q)` and refers to an earlier measurement."]),
+    Contract("BackendRequest", "backend_request.json", ("L3", "B"), "L3-B", "driver of L3 or L4", "backend lowering",
+             "adapter", "PPVM Python API; Stim text via `StimProgram.parse` for the restricted subset",
+             ["`backend=PS` or `LPS` requires `observable`; `backend=GT` or `GTS` requires `shots`.",
+              "`backend=PS` rejects any loss channel in the program; `LPS` is needed.",
+              "`emit_mode=stim_text` only if no `loss`, `r*` rotation, `u3`, `cz_block` or `feed_forward` statement exists.",
+              "`max_loss_weight` is set only for `LPS`; `max_pauli_weight` and `preserve_strings` only for `PS` or `LPS`."]),
+    Contract("BackendResult", "backend_result.json", ("B", "L4"), "L3-B", "backend", "L4 (feed-forward, analysis) and L5 (decoding)",
+             "adapter", "`outcomes` equals the PPVM `sample_stim(as_numpy=True)` array layout (0 ZERO, 1 ONE, 2 LOST); Stim measurement record layout otherwise",
+             ["`outcomes` columns equal the number of `measure` ops.",
+              "`LOST` (2) is never reported as 0 or 1.",
+              "Exactly one of `outcomes` or `expectation` is present.",
+              "`truncation_report.biased_low` is true whenever `max_pauli_weight`, `max_loss_weight` or `min_abs_coeff > 0` removed a term."]),
+]
+
+PAIRS = [
+    ("L1-L2", "L1 Physical", "L2 Pulse and calibration", ["PhysicalParameters", "CalibrationUpdate"]),
+    ("L2-L3", "L2 Pulse and calibration", "L3 Native gates and movement", ["CalibrationRecord"]),
+    ("L3-L4", "L3 Native gates and movement", "L4 Circuit", ["CircuitLowering", "ProgramDocument"]),
+    ("L4-L5", "L4 Circuit", "L5 Logical", ["LogicalLowering"]),
+    ("L3-B", "L3 Native gates and movement", "PPVM backend", ["NativeProgram", "BackendRequest", "BackendResult"]),
+]
+
+# ---------------------------------------------------------------------------
+def record_by_name():
+    return {r.name: r for r in RECORDS}
+
+
+def _type_schema(f: F, rec_file: str):
+    t = f.type
+    lo, hi = f.rng if f.rng else (None, None)
+
+    def base(t, with_range):
+        if t.startswith("enum:"):
+            return {"enum": t[5:].split("|")}
+        if t.startswith("ref:"):
+            name = t[4:]
+            target = record_by_name()[name].file
+            return {"$ref": (f"#/$defs/{name}" if target == rec_file else f"{target}#/$defs/{name}")}
+        s = {"type": t}
+        if with_range and t in ("number", "integer"):
+            if lo is not None:
+                s["minimum"] = lo
+            if hi is not None:
+                s["maximum"] = hi
+        return s
+
+    if t.startswith("array<array<"):
+        inner = t[len("array<array<"):-2]
+        s = {"type": "array", "items": {"type": "array", "items": base(inner, True)}}
+    elif t.startswith("array<"):
+        inner = t[6:-1]
+        s = {"type": "array", "items": base(inner, True)}
+        if f.n is not None:
+            s["minItems"] = s["maxItems"] = f.n
+    else:
+        s = base(t, True)
+    if f.unit != UNIT_NONE:
+        s["x-unit"] = f.unit
+    if f.desc:
+        s["description"] = f.desc
+    return s
+
+
+def record_schema(rec: Record):
+    return {
+        "type": "object",
+        "description": rec.desc,
+        "properties": {f.name: _type_schema(f, rec.file) for f in rec.fields},
+        "required": [f.name for f in rec.fields if f.req],
+        "additionalProperties": False,
+    }
+
+
+def build_schemas():
+    """Return {filename: schema dict}."""
+    files = {}
+    for rec in RECORDS:
+        files.setdefault(rec.file, []).append(rec)
+    out = {}
+    for fn, recs in files.items():
+        s = {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": BASE_URI + fn,
+             "$defs": {r.name: record_schema(r) for r in recs}}
+        if fn != "common.json":
+            s["title"] = recs[0].name
+            s["$ref"] = f"#/$defs/{recs[0].name}"
+        else:
+            s["title"] = "Shared definitions"
+        out[fn] = s
+    return out
+
+
+def type_label(f: F):
+    t = f.type.replace("enum:", "enum ").replace("ref:", "").replace("|", " / ")
+    t = t.replace("array<array<", "array of array of ").replace("array<", f"array{'[%d]' % f.n if f.n else ''} of ").replace(">", "")
+    return t
+
+
+def fmt_range(f: F):
+    if not f.rng:
+        return "-"
+    lo, hi = f.rng
+    return f"[{'-inf' if lo is None else lo}, {'inf' if hi is None else hi}]"
+
+
+def record_table(rec: Record):
+    rows = ["| Field | Type | Unit | Range | Req. | Meaning |", "|---|---|---|---|---|---|"]
+    for f in rec.fields:
+        u = "-" if f.unit == UNIT_NONE else f.unit
+        rows.append(f"| `{f.name}` | {type_label(f)} | {u} | {fmt_range(f)} | {'yes' if f.req else 'no'} | {f.desc or '-'} |")
+    return "\n".join(rows)