Telemetry and Artifact Schemas — Operating Quantum Computers

Quantum operations need schemas because memory is unreliable and notebooks are informal. A schema makes evidence comparable across providers, backends, compiler releases, and time.

These schemas are starting points, not standards.

B.1 Experiment bundle

Illustrative listing · yaml

experiment_bundle:
  experiment_id: uuid
  project_id: string
  owner: string
  created_at: timestamp
  intent:
    problem_class: string
    expected_output: string
    decision_context: string
  source:
    repository: string
    commit: string
    files:
      - path: string
        sha256: string
  dependencies:
    python: string
    sdk_versions: {}
    container_image: string
  validation:
    simulator_backend: string
    simulator_result_hash: string
    classical_baseline: string
  execution_plan:
    provider: string
    backend: string
    shots: int
    session_or_job_id: string
  artifacts:
    circuit_ir: string
    compiled_ir: string
    result_raw: string
    trust_report: string

Diagram loads as you read

B.1 Experiment bundle · Figure 1

View diagram source

flowchart TB
    Bundle[Experiment bundle] --> Intent[Intent]
    Bundle --> Source[Source]
    Bundle --> Dependencies[Dependencies]
    Bundle --> Validation[Validation]
    Bundle --> Execution[Execution plan]
    Bundle --> Artifacts[Artifacts]

B.2 Execution trace

Illustrative listing · yaml

execution_trace:
  trace_id: string
  spans:
    - span_id: string
      parent_span_id: string|null
      name: submit|compile|queue|execute|retrieve|analyze
      start_time: timestamp
      end_time: timestamp
      attributes:
        provider: string
        backend: string
        compiler_version: string
        target_model_version: string

Diagram loads as you read

B.2 Execution trace · Figure 2

View diagram source

sequenceDiagram
    participant Client
    participant Gateway
    participant Compiler
    participant Scheduler
    participant Provider
    participant Analyzer
    Client->>Gateway: submit trace_id
    Gateway->>Compiler: compile span
    Compiler->>Scheduler: schedule span
    Scheduler->>Provider: execute span
    Provider->>Analyzer: analyze span
    Analyzer-->>Client: report trace_id

B.3 Calibration snapshot

Illustrative listing · yaml

calibration_snapshot:
  backend: string
  snapshot_id: string
  valid_from: timestamp
  valid_until: timestamp|null
  qubits:
    - id: int
      t1_us: float|null
      t2_us: float|null
      readout_error: float|null
      frequency_ghz: float|null
  operations:
    - name: string
      qubits: [int]
      duration_ns: float|null
      error_estimate: float|null
  warnings:
    - qubit: int|null
      operation: string|null
      reason: string

Diagram loads as you read

B.3 Calibration snapshot · Figure 3

View diagram source

flowchart LR
    Snapshot[Calibration snapshot] --> Compiler[Compiler]
    Snapshot --> Scheduler[Scheduler]
    Snapshot --> Trust[Trust report]
    Snapshot --> Incident[Incident analysis]

B.4 Compiler report

Illustrative listing · yaml

compiler_report:
  compiler_version: string
  target_model_version: string
  source_artifact_hash: string
  compiled_artifact_hash: string
  metrics:
    logical_qubits: int
    physical_qubits_used: int
    depth: int
    duration_estimate_ns: float|null
    one_qubit_ops: int
    two_qubit_ops: int
    measurement_ops: int
    routing_overhead: float
    expected_success_proxy: float|null
  warnings:
    - code: string
      message: string
  rejected: false

Diagram loads as you read

B.4 Compiler report · Figure 4

View diagram source

flowchart TB
    Source[Source program] --> Compiler[Compiler]
    Compiler --> Native[Native artifact]
    Compiler --> Report[Compiler report]
    Report --> Admission[Admission control]
    Report --> Trust[Trust report]

B.5 Result evidence

Illustrative listing · yaml

result_evidence:
  run_id: string
  backend: string
  started_at: timestamp
  ended_at: timestamp
  shots: int
  raw_counts_uri: string
  processed_results:
    - name: string
      value: float|string|object
      uncertainty: float|null
      method: string
  mitigation:
    applied: bool
    methods: []
    validation_domain: string|null
  limitations:
    - string

Diagram loads as you read

B.5 Result evidence · Figure 5

View diagram source

flowchart LR
    Raw[Raw result] --> Process[Processing]
    Process --> Mitigation[Mitigation]
    Mitigation --> Estimate[Estimate]
    Estimate --> Evidence[Result evidence]

B.6 Facility telemetry summary

Illustrative listing · yaml

facility_telemetry_summary:
  backend: string
  window_start: timestamp
  window_end: timestamp
  cryogenic:
    base_temperature_mk:
      min: float|null
      max: float|null
      mean: float|null
    compressor_state_changes: int
  environment:
    room_temperature_c:
      min: float|null
      max: float|null
    vibration_alerts: int
  power:
    ups_events: int
    power_quality_alerts: int
  alarms:
    - time: timestamp
      severity: string
      message: string

Diagram loads as you read

B.6 Facility telemetry summary · Figure 6

View diagram source

flowchart TB
    Facility[Facility streams] --> Summary[Telemetry summary]
    Summary --> Bundle[Experiment bundle]
    Summary --> Incident[Incident analysis]
    Summary --> Dashboard[Ops dashboard]

B.7 Trust report

Illustrative listing · yaml

trust_report:
  report_id: string
  experiment_id: string
  conclusion:
    status: trusted|limited|invalid|exploratory
    summary: string
  result:
    values: []
    uncertainty: string
  provenance:
    source_hashes: []
    artifact_hashes: []
  hardware_context:
    provider: string
    backend: string
    calibration_snapshot: string
  compiler_context:
    compiler_version: string
    target_model_version: string
  statistics:
    shots: int
    confidence_method: string
  limitations:
    - string
  decision:
    recommended_use: string

Diagram loads as you read

B.7 Trust report · Figure 7

View diagram source

flowchart TB
    Trust[Trust report] --> Conclusion[Conclusion]
    Trust --> Result[Result]
    Trust --> Provenance[Provenance]
    Trust --> Hardware[Hardware]
    Trust --> Compiler[Compiler]
    Trust --> Statistics[Statistics]
    Trust --> Limits[Limitations]

B.8 Logical workload schema

Illustrative listing · yaml

logical_workload:
  workload_id: string
  algorithm: string
  logical_requirements:
    logical_qubits: int
    logical_cycles: int
    max_failure_probability: float
  resources:
    t_count: int|null
    t_depth: int|null
    magic_state_budget: int|null
  assumptions:
    code_family: string
    physical_error_rate: float
    decoder: string
  estimate:
    physical_qubits: int
    runtime_seconds: float
    estimate_tool: string

Diagram loads as you read

B.8 Logical workload schema · Figure 8

View diagram source

flowchart LR
    Logical[Logical workload] --> Estimate[Resource estimate]
    Estimate --> Admit[Logical admission]
    Admit --> Execute[Logical execution]
    Execute --> Evidence[Logical trust report]

B.9 Schema governance

Schemas should be versioned and migrated deliberately.

Diagram loads as you read

B.9 Schema governance · Figure 9

View diagram source

flowchart TB
    Schema[Schema change] --> Compat{Backward compatible?}
    Compat -- yes --> Minor[Minor version]
    Compat -- no --> Major[Major version]
    Minor --> Migrate[Test migration]
    Major --> Migrate
    Migrate --> Release[Release schema]
    Release --> Docs[Update docs and examples]

Minimum governance:

schema version in every artifact,
migration scripts for major changes,
compatibility tests with old experiment bundles,
deprecation windows,
clear ownership.

A quantum result that cannot be parsed later cannot be trusted later.