跳转至

05 Execution Bundle Model

Purpose

This chapter defines the bundle-based execution artifact model.

Core Rule

Program execution must be representable as a coordinated bundle of artifacts rather than a single text file. The bundle is the normative delivery unit for execution, replay, audit, and interchange.

The reference Word drafts explicitly recommend a bundle rather than a standalone .qasm file. This recommendation is retained here as a normative architectural rule.

Bundle Composition

A v0.1 execution bundle is centered on:

  • a canonical UQCI program
  • manifest.json
  • devicespec.json
  • calset.json
  • optional pulseir.json
  • optional compatibility export such as program.qasm

Additional metadata artifacts may be included when they are clearly versioned and do not blur the canonical and normative roles of the required artifacts.

Manifest Role

The manifest is the artifact inventory and entrypoint description. It identifies bundle versioning, profile context, artifact locations, integrity-related metadata, and optional targeting information.

In practical tooling, the manifest may name a primary entry artifact for exchange or execution flow. That convenience must not change the deeper rule that UQCI IR remains the semantic source of truth.

Sidecar Semantics

DeviceSpec and CalSet are not optional commentary if execution depends on device constraints or calibration state. They are normative sidecars that complete the execution context required for practical realization.

Their roles are distinct:

  • DeviceSpec describes the device capability and constraint envelope
  • CalSet describes versioned runtime calibration context
  • Manifest describes the bundle itself as an auditable and transferable unit

Bundle Objectives

The bundle model exists to support:

  • exchangeability of programs
  • verifiability of execution assumptions
  • traceability of produced results
  • replayability for debugging, audit, and regression testing

The reference drafts show a simple bundle directory shape with a program entry, manifest, device description, calibration set, and optional pulseir and metadata files. Repository implementations may vary in file naming, but the conceptual bundle shape should remain recognizable and auditable.

Compatibility Exports

When OpenQASM is included in a bundle, it remains a compatibility artifact. The canonical truth is still the UQCI program and its normative sidecars.

This distinction matters especially for OQ-0 through OQ-X export workflows. A bundle may carry OpenQASM for interchange, inspection, or toolchain integration while still depending on sidecars for execution-relevant context.

Practical Constraint

The execution bundle should stay practical in v0.1. It must be rich enough to preserve execution assumptions and interoperability, but not so overloaded that every experimental artifact becomes mandatory.