qiskit-resume 0.2.0a1__tar.gz

qiskit_resume-0.2.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jihoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qiskit_resume-0.2.0a1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: qiskit-resume
+Version: 0.2.0a1
+Summary: Record & replay layer that lets any Qiskit Primitives workflow resume after interruption without re-spending QPU time.
+Author: Jihoon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/set3523/Qiskit-resume
+Project-URL: Issues, https://github.com/set3523/Qiskit-resume/issues
+Keywords: qiskit,quantum,checkpoint,resume,ibm-quantum,vqe,qaoa
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit>=1.4
+Requires-Dist: numpy>=1.23
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime>=0.30; extra == "ibm"
+Provides-Extra: examples
+Requires-Dist: qiskit-algorithms>=0.3; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scipy; extra == "dev"
+Dynamic: license-file
+
+# qiskit-resume
+
+**Run any Qiskit Primitives workflow so that it can be interrupted and resumed — without paying for the same QPU time twice.**
+
+> **Status: alpha (0.2.0a1).** Fully tested on local simulators (Qiskit 1.4 and 2.x, Linux and Windows).
+> The IBM path (job reconnection, QPU usage tracking) is tested against a fake service only so far;
+> a real-hardware check is the next milestone. The file format may still change before 0.2.0.
+
+Wrap your Estimator / Sampler, run your script inside `resume_run(...)`, and if it stops
+(quota used up, laptop closed, network, Ctrl+C), just run the same command again:
+
+- finished calls are **replayed instantly** from a local `.qresume` file,
+- a job that was still running on IBM is **reconnected**, not resubmitted,
+- only new work uses the QPU.
+
+It works for any algorithm (VQE, QAOA, sampling sweeps, your own loops) because it records
+*calls*, not algorithm state: on a rerun your Python code runs again from the top, gets the
+recorded answers, rebuilds its own state (optimizer memory included) and continues at the
+first unrecorded call. Built first for the IBM Quantum Open Plan (10 QPU minutes per rolling
+28 days), where every second counts.
+
+```python
+from qiskit.primitives import StatevectorEstimator      # or qiskit_ibm_runtime.EstimatorV2(mode=backend)
+import qiskit_resume as resume
+
+estimator = resume.wrap(StatevectorEstimator())
+
+with resume.resume_run("vqe.qresume"):
+    theta0 = resume.rng().uniform(-3.14, 3.14, ansatz.num_parameters)   # randomness that replays
+    res = minimize(lambda x: float(estimator.run([(ansatz, H, x)]).result()[0].data.evs),
+                   theta0, method="COBYLA")
+```
+
+## Install
+
+```bash
+pip install qiskit-resume            # Qiskit >= 1.4 (tested 1.4 and 2.6), Python >= 3.10
+pip install "qiskit-resume[ibm]"     # + qiskit-ibm-runtime: job reconnection, QPU usage
+```
+
+## What you wrap
+
+| `resume.wrap(...)` | recorded | on replay |
+|---|---|---|
+| `EstimatorV2` / `SamplerV2` (local or IBM) | question hash, job id (before waiting), result, QPU seconds | result from the file; running IBM job reconnected |
+| a pass manager — `resume.wrap(pm, backend=backend)` | transpiled circuit per (source circuit, device) | same circuit again, even if calibration changed |
+| a slow, side-effect-free function — `@resume.wrap` | return value per arguments | value from the file |
+
+Library algorithms that take an estimator (e.g. `qiskit_algorithms.VQE`) work too: pass the wrapped one.
+
+## Rules of thumb
+
+- **Randomness:** use `resume.rng()` / `resume.seed` (or seeded generators). Global `random`/`numpy`
+  and `qiskit_algorithms.algorithm_globals` are seeded automatically.
+- **Changed code:** if a replayed call asks a different question, you get a warning and execution
+  continues from there (`on_divergence="stop"` to stop instead). Earlier records are kept as history.
+- **Snapshots (optional):** `run.snapshot({...})` / `run.load_snapshot()` skip replaying the start.
+  Put *every* variable your loop needs in it; a missing one is detected and reported.
+- **Budget:** `resume_run(..., qpu_budget_s=120)` stops cleanly before the job that would exceed it.
+- **Device change** is detected, recorded and warned about (`on_backend_change="stop"` to stop).
+
+## Before spending QPU time
+
+```bash
+qresume selftest my_script.py -- my.qresume      # crash/resume at several points with synthetic results (no QPU)
+qresume check my_script.py --file my.qresume -- my.qresume   # can this file continue? (no IBM contact)
+qresume status my.qresume                        # calls, snapshots, device, QPU used, warnings
+```
+
+Other commands: `copy` (consistent copy while running), `export`, `quota`, `fork` (branch at a
+snapshot), `pack`/`unpack`, `compact`.
+
+## See it work
+
+[`examples/crash_and_resume.py`](https://github.com/set3523/Qiskit-resume/blob/master/examples/crash_and_resume.py) takes a plain Qiskit workload
+(VQE, QAOA, VQD from `qiskit_algorithms`, unmodified), wraps it, **kills the process part way**, runs it
+again and checks the result equals an uninterrupted run, logging every call to the console:
+
+```bash
+git clone https://github.com/set3523/Qiskit-resume && cd Qiskit-resume/examples
+pip install "qiskit-resume[examples]" scipy
+python crash_and_resume.py standard/qaoa_maxcut.py --kill-at-call 100 --compare
+```
+
+## Limits
+
+- A single circuit execution cannot be paused (quantum states can't be saved); interruption
+  granularity is one primitive call.
+- Code that is not deterministic in ways qiskit-resume can't seed (time, external data) may
+  diverge on replay — you'll be told where.
+- Calls not made through Primitives (`backend.run`, direct `Statevector` maths) are not recorded.
+
+## Documentation
+
+[DECISIONS](https://github.com/set3523/Qiskit-resume/blob/master/docs/DECISIONS.md) (why) ·
+[ARCHITECTURE](https://github.com/set3523/Qiskit-resume/blob/master/docs/ARCHITECTURE.md) (layers and flow) ·
+[CONTRACTS](https://github.com/set3523/Qiskit-resume/blob/master/docs/CONTRACTS.md) (every module's inputs/outputs) ·
+[Korean README](https://github.com/set3523/Qiskit-resume/blob/master/README_ko.md)
+
+License: MIT

qiskit_resume-0.2.0a1/README.md

@@ -0,0 +1,100 @@
+# qiskit-resume
+
+**Run any Qiskit Primitives workflow so that it can be interrupted and resumed — without paying for the same QPU time twice.**
+
+> **Status: alpha (0.2.0a1).** Fully tested on local simulators (Qiskit 1.4 and 2.x, Linux and Windows).
+> The IBM path (job reconnection, QPU usage tracking) is tested against a fake service only so far;
+> a real-hardware check is the next milestone. The file format may still change before 0.2.0.
+
+Wrap your Estimator / Sampler, run your script inside `resume_run(...)`, and if it stops
+(quota used up, laptop closed, network, Ctrl+C), just run the same command again:
+
+- finished calls are **replayed instantly** from a local `.qresume` file,
+- a job that was still running on IBM is **reconnected**, not resubmitted,
+- only new work uses the QPU.
+
+It works for any algorithm (VQE, QAOA, sampling sweeps, your own loops) because it records
+*calls*, not algorithm state: on a rerun your Python code runs again from the top, gets the
+recorded answers, rebuilds its own state (optimizer memory included) and continues at the
+first unrecorded call. Built first for the IBM Quantum Open Plan (10 QPU minutes per rolling
+28 days), where every second counts.
+
+```python
+from qiskit.primitives import StatevectorEstimator      # or qiskit_ibm_runtime.EstimatorV2(mode=backend)
+import qiskit_resume as resume
+
+estimator = resume.wrap(StatevectorEstimator())
+
+with resume.resume_run("vqe.qresume"):
+    theta0 = resume.rng().uniform(-3.14, 3.14, ansatz.num_parameters)   # randomness that replays
+    res = minimize(lambda x: float(estimator.run([(ansatz, H, x)]).result()[0].data.evs),
+                   theta0, method="COBYLA")
+```
+
+## Install
+
+```bash
+pip install qiskit-resume            # Qiskit >= 1.4 (tested 1.4 and 2.6), Python >= 3.10
+pip install "qiskit-resume[ibm]"     # + qiskit-ibm-runtime: job reconnection, QPU usage
+```
+
+## What you wrap
+
+| `resume.wrap(...)` | recorded | on replay |
+|---|---|---|
+| `EstimatorV2` / `SamplerV2` (local or IBM) | question hash, job id (before waiting), result, QPU seconds | result from the file; running IBM job reconnected |
+| a pass manager — `resume.wrap(pm, backend=backend)` | transpiled circuit per (source circuit, device) | same circuit again, even if calibration changed |
+| a slow, side-effect-free function — `@resume.wrap` | return value per arguments | value from the file |
+
+Library algorithms that take an estimator (e.g. `qiskit_algorithms.VQE`) work too: pass the wrapped one.
+
+## Rules of thumb
+
+- **Randomness:** use `resume.rng()` / `resume.seed` (or seeded generators). Global `random`/`numpy`
+  and `qiskit_algorithms.algorithm_globals` are seeded automatically.
+- **Changed code:** if a replayed call asks a different question, you get a warning and execution
+  continues from there (`on_divergence="stop"` to stop instead). Earlier records are kept as history.
+- **Snapshots (optional):** `run.snapshot({...})` / `run.load_snapshot()` skip replaying the start.
+  Put *every* variable your loop needs in it; a missing one is detected and reported.
+- **Budget:** `resume_run(..., qpu_budget_s=120)` stops cleanly before the job that would exceed it.
+- **Device change** is detected, recorded and warned about (`on_backend_change="stop"` to stop).
+
+## Before spending QPU time
+
+```bash
+qresume selftest my_script.py -- my.qresume      # crash/resume at several points with synthetic results (no QPU)
+qresume check my_script.py --file my.qresume -- my.qresume   # can this file continue? (no IBM contact)
+qresume status my.qresume                        # calls, snapshots, device, QPU used, warnings
+```
+
+Other commands: `copy` (consistent copy while running), `export`, `quota`, `fork` (branch at a
+snapshot), `pack`/`unpack`, `compact`.
+
+## See it work
+
+[`examples/crash_and_resume.py`](https://github.com/set3523/Qiskit-resume/blob/master/examples/crash_and_resume.py) takes a plain Qiskit workload
+(VQE, QAOA, VQD from `qiskit_algorithms`, unmodified), wraps it, **kills the process part way**, runs it
+again and checks the result equals an uninterrupted run, logging every call to the console:
+
+```bash
+git clone https://github.com/set3523/Qiskit-resume && cd Qiskit-resume/examples
+pip install "qiskit-resume[examples]" scipy
+python crash_and_resume.py standard/qaoa_maxcut.py --kill-at-call 100 --compare
+```
+
+## Limits
+
+- A single circuit execution cannot be paused (quantum states can't be saved); interruption
+  granularity is one primitive call.
+- Code that is not deterministic in ways qiskit-resume can't seed (time, external data) may
+  diverge on replay — you'll be told where.
+- Calls not made through Primitives (`backend.run`, direct `Statevector` maths) are not recorded.
+
+## Documentation
+
+[DECISIONS](https://github.com/set3523/Qiskit-resume/blob/master/docs/DECISIONS.md) (why) ·
+[ARCHITECTURE](https://github.com/set3523/Qiskit-resume/blob/master/docs/ARCHITECTURE.md) (layers and flow) ·
+[CONTRACTS](https://github.com/set3523/Qiskit-resume/blob/master/docs/CONTRACTS.md) (every module's inputs/outputs) ·
+[Korean README](https://github.com/set3523/Qiskit-resume/blob/master/README_ko.md)
+
+License: MIT

qiskit_resume-0.2.0a1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "qiskit-resume"
+dynamic = ["version"]
+description = "Record & replay layer that lets any Qiskit Primitives workflow resume after interruption without re-spending QPU time."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jihoon" }]
+keywords = ["qiskit", "quantum", "checkpoint", "resume", "ibm-quantum", "vqe", "qaoa"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "qiskit>=1.4",
+    "numpy>=1.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/set3523/Qiskit-resume"
+Issues = "https://github.com/set3523/Qiskit-resume/issues"
+
+[project.optional-dependencies]
+ibm = ["qiskit-ibm-runtime>=0.30"]
+examples = ["qiskit-algorithms>=0.3"]
+dev = ["pytest>=7.0", "scipy"]
+
+[project.scripts]
+qresume = "qiskit_resume.tools.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { attr = "qiskit_resume._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qiskit_resume*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p no:cacheprovider"

qiskit_resume-0.2.0a1/qiskit_resume/__init__.py

@@ -0,0 +1,51 @@
+"""qiskit-resume: record & replay for Qiskit Primitives workflows.
+
+Typical use::
+
+    import qiskit_resume as resume
+
+    estimator = resume.wrap(EstimatorV2(mode=backend))
+    with resume.resume_run("vqe.qresume"):
+        ...  # plain Qiskit code; rerun the same script after an interruption
+
+Design: docs/DECISIONS.md | structure: docs/ARCHITECTURE.md | contracts: docs/CONTRACTS.md
+"""
+
+from typing import Any
+
+from qiskit_resume._version import __version__
+from qiskit_resume.l0_disk.codec import EncodeError
+from qiskit_resume.l0_disk.db import AlreadyRunningError, IntegrityError
+from qiskit_resume.l1_record.runs import ImmutableSettingError
+from qiskit_resume.l4_api.primitive import BudgetExceeded, JobWaitTimeout, QuotaExhausted
+from qiskit_resume.l4_api.rng import NoActiveRunError, rng
+from qiskit_resume.l4_api.run import BackendChangedStop, DivergenceStop, ResumeRun, get_active_run, resume_run
+from qiskit_resume.l4_api.wrap import wrap
+
+__all__ = [
+    "AlreadyRunningError",
+    "BackendChangedStop",
+    "BudgetExceeded",
+    "DivergenceStop",
+    "EncodeError",
+    "ImmutableSettingError",
+    "IntegrityError",
+    "JobWaitTimeout",
+    "NoActiveRunError",
+    "QuotaExhausted",
+    "ResumeRun",
+    "__version__",
+    "get_active_run",
+    "resume_run",
+    "rng",
+    "seed",
+    "wrap",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "seed":  # resume.seed -> the active experiment's seed
+        from qiskit_resume.l4_api.rng import seed as _seed
+
+        return _seed()
+    raise AttributeError(f"module 'qiskit_resume' has no attribute {name!r}")

qiskit_resume-0.2.0a1/qiskit_resume/__main__.py

@@ -0,0 +1,3 @@
+from qiskit_resume.tools.cli import main
+
+raise SystemExit(main())

qiskit_resume-0.2.0a1/qiskit_resume/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0a1"

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/__init__.py

@@ -0,0 +1,5 @@
+"""L0 disk: the .qresume file, the blob store and the value codec.
+
+Knows nothing about Qiskit or what records mean.
+Depends on: standard library + numpy only. Contracts: docs/CONTRACTS.md section 1.
+"""

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/blobs/__init__.py

@@ -0,0 +1,13 @@
+"""l0_disk.blobs: content-addressed blob store (D-013 dedup).
+
+IN : bytes, kind
+OUT: BlobRef (str, SHA-256 hex); get(BlobRef) -> bytes; has(BlobRef) -> bool
+     content_hash(bytes) -> str
+Depends on: l0_disk.db
+Owns table: blobs
+Contract (signatures, types, errors, invariants): docs/CONTRACTS.md section 1.2
+"""
+
+from qiskit_resume.l0_disk.blobs.core import BlobStore, content_hash
+
+__all__ = ["BlobStore", "content_hash"]

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/blobs/core.py

@@ -0,0 +1,50 @@
+"""Content-addressed blob store inside the experiment DB (D-013 dedup).
+
+Identical payloads (same circuit, same observable, ...) are stored once and
+referenced by their SHA-256 hex digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+
+from qiskit_resume.l0_disk.db import ExperimentDB
+
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS blobs (
+    hash TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    data BLOB NOT NULL
+);
+"""
+
+
+def content_hash(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+class BlobStore:
+    def __init__(self, db: ExperimentDB) -> None:
+        db.ensure_schema(_DDL)
+        self._conn = db.conn
+
+    def put(self, data: bytes, *, kind: str = "raw") -> str:
+        """Store ``data`` (if new) and return its hash. Caller owns the transaction."""
+        h = content_hash(data)
+        self._conn.execute(
+            "INSERT OR IGNORE INTO blobs(hash, kind, size, data) VALUES (?, ?, ?, ?)",
+            (h, kind, len(data), sqlite3.Binary(data)),
+        )
+        return h
+
+    def get(self, h: str) -> bytes:
+        row = self._conn.execute("SELECT data FROM blobs WHERE hash = ?", (h,)).fetchone()
+        if row is None:
+            raise KeyError(f"blob not found: {h}")
+        return bytes(row[0])
+
+    def has(self, h: str) -> bool:
+        return self._conn.execute("SELECT 1 FROM blobs WHERE hash = ?", (h,)).fetchone() is not None

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/codec/__init__.py

@@ -0,0 +1,20 @@
+"""l0_disk.codec: value <-> bytes (D-013).
+
+IN : Python value (None/bool/int/float/complex/str/bytes/list/tuple/dict[str, ...]/numpy)
+OUT: bytes; decode(bytes) -> value
+     canonical_floats(array) -> bytes  12-significant-digit text used as hash input (shared by l1 and l3)
+Errors: EncodeError (with the path of the unstorable value, raised at record time)
+Option: allow_pickle=True (fragile across library versions)
+Depends on: nothing
+Contract (signatures, types, errors, invariants): docs/CONTRACTS.md section 1.3
+"""
+
+from qiskit_resume.l0_disk.codec.core import (
+    EncodeError,
+    canonical_floats,
+    canonical_scalar,
+    decode,
+    encode,
+)
+
+__all__ = ["EncodeError", "canonical_floats", "canonical_scalar", "decode", "encode"]

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/codec/core.py

@@ -0,0 +1,169 @@
+"""Binary value codec for user values (wrapped-function results, snapshots) and
+our own neutral records (D-013).
+
+Layout of an encoded value::
+
+    b"QRV1" | u32 header_len | header (UTF-8 JSON) | segment bytes ...
+
+The JSON header holds the structure. Numpy arrays (and, if allowed, pickles)
+are stored as raw binary segments and referenced from the header, so numbers
+inside arrays never go through text. Python floats in the header use ``repr``
+which round-trips exactly.
+
+Supported without pickle: None, bool, int, float, complex, str, bytes,
+list, tuple, dict (str keys), numpy arrays and numpy scalars.
+Anything else raises :class:`EncodeError` at encode time (fail fast, B7),
+with the path to the offending value.
+"""
+
+from __future__ import annotations
+
+import json
+import pickle
+import struct
+from typing import Any
+
+import numpy as np
+
+MAGIC = b"QRV1"
+_HDR = struct.Struct("<I")
+
+
+class EncodeError(TypeError):
+    """A value cannot be stored. ``path`` points at the offending element."""
+
+    def __init__(self, path: str, value: Any, hint: str = "") -> None:
+        self.path = path
+        msg = f"cannot store value at {path}: {type(value).__module__}.{type(value).__qualname__}"
+        if hint:
+            msg += f" - {hint}"
+        super().__init__(msg)
+
+
+_DEFAULT_HINT = (
+    "return plain numbers/lists/dicts or numpy arrays instead "
+    "(or opt in with allow_pickle=True, which may break across library versions)"
+)
+
+
+def encode(value: Any, *, allow_pickle: bool = False) -> bytes:
+    segments: list[bytes] = []
+
+    def add_segment(data: bytes) -> int:
+        segments.append(data)
+        return len(segments) - 1
+
+    def walk(v: Any, path: str) -> Any:
+        if v is None or isinstance(v, (bool, str)):
+            return v
+        if isinstance(v, int) and not isinstance(v, bool):
+            return v
+        if isinstance(v, float):
+            if v != v or v in (float("inf"), float("-inf")):
+                return {"__f__": repr(v)}
+            return v
+        if isinstance(v, complex):
+            return {"__c__": [v.real, v.imag]}
+        if isinstance(v, (bytes, bytearray, memoryview)):
+            return {"__b__": add_segment(bytes(v))}
+        if isinstance(v, np.ndarray):
+            if v.dtype.hasobject:
+                if allow_pickle:
+                    return {"__p__": add_segment(pickle.dumps(v, protocol=4))}
+                raise EncodeError(path, v, "object-dtype arrays are not supported; " + _DEFAULT_HINT)
+            arr = v if v.flags.c_contiguous else v.copy(order="C")  # keeps 0-d shape
+            return {
+                "__nd__": add_segment(arr.tobytes(order="C")),
+                "dtype": arr.dtype.str,
+                "shape": list(arr.shape),
+            }
+        if isinstance(v, np.generic):
+            return walk(np.asarray(v), path)  # 0-d array keeps the exact dtype
+        if isinstance(v, tuple):
+            return {"__t__": [walk(x, f"{path}[{i}]") for i, x in enumerate(v)]}
+        if isinstance(v, list):
+            return [walk(x, f"{path}[{i}]") for i, x in enumerate(v)]
+        if isinstance(v, dict):
+            out = {}
+            for k, x in v.items():
+                if not isinstance(k, str):
+                    raise EncodeError(f"{path}.<key {k!r}>", k, "dict keys must be str")
+                if k.startswith("__") and k.endswith("__"):
+                    raise EncodeError(f"{path}.{k}", k, "dunder keys are reserved")
+                out[k] = walk(x, f"{path}.{k}")
+            return out
+        if allow_pickle:
+            try:
+                return {"__p__": add_segment(pickle.dumps(v, protocol=4))}
+            except Exception as exc:  # noqa: BLE001
+                raise EncodeError(path, v, f"pickle failed: {exc}") from exc
+        raise EncodeError(path, v, _DEFAULT_HINT)
+
+    header_obj = {"v": walk(value, "value"), "seg": None}
+    header_obj["seg"] = [len(s) for s in segments]
+    header = json.dumps(header_obj, separators=(",", ":"), allow_nan=False).encode("utf-8")
+    return MAGIC + _HDR.pack(len(header)) + header + b"".join(segments)
+
+
+def decode(data: bytes) -> Any:
+    if data[:4] != MAGIC:
+        raise ValueError("not a qiskit-resume encoded value (bad magic)")
+    (hlen,) = _HDR.unpack_from(data, 4)
+    start = 4 + _HDR.size
+    header = json.loads(data[start : start + hlen].decode("utf-8"))
+    pos = start + hlen
+    segs: list[bytes] = []
+    for n in header["seg"]:
+        segs.append(data[pos : pos + n])
+        pos += n
+
+    def walk(v: Any) -> Any:
+        if isinstance(v, list):
+            return [walk(x) for x in v]
+        if isinstance(v, dict):
+            if "__nd__" in v:
+                arr = np.frombuffer(segs[v["__nd__"]], dtype=np.dtype(v["dtype"]))
+                return arr.reshape(tuple(v["shape"])).copy()
+            if "__t__" in v:
+                return tuple(walk(x) for x in v["__t__"])
+            if "__c__" in v:
+                return complex(*v["__c__"])
+            if "__f__" in v:
+                return float(v["__f__"])
+            if "__b__" in v:
+                return segs[v["__b__"]]
+            if "__p__" in v:
+                return pickle.loads(segs[v["__p__"]])  # only written when allow_pickle=True
+            return {k: walk(x) for k, x in v.items()}
+        return v
+
+    return walk(header["v"])
+
+
+def _fmt_sig(x: float, sig: int) -> str:
+    if x != x:
+        return "nan"
+    if x in (float("inf"), float("-inf")):
+        return "inf" if x > 0 else "-inf"
+    if x == 0.0:
+        return "0"
+    return format(x, f".{sig - 1}e")
+
+
+def canonical_floats(values: Any, *, sig_digits: int = 12) -> bytes:
+    """Canonical bytes of a real/complex array rounded to ``sig_digits`` significant digits (D-005).
+
+    Decimal text is exact and platform independent, so last-bit differences between
+    machines disappear while real changes (> 1e-12 relative) are kept. Shape is included.
+    """
+    arr = np.asarray(values)
+    if np.iscomplexobj(arr):
+        items = [f"{_fmt_sig(float(z.real), sig_digits)}{_fmt_sig(float(z.imag), sig_digits)}j"
+                 for z in arr.astype(np.complex128).ravel()]
+    else:
+        items = [_fmt_sig(float(x), sig_digits) for x in arr.astype(np.float64).ravel()]
+    return ("[" + "x".join(map(str, arr.shape)) + "]" + ",".join(items)).encode()
+
+
+def canonical_scalar(x: float, *, sig_digits: int = 12) -> str:
+    return _fmt_sig(float(x), sig_digits)

qiskit_resume-0.2.0a1/qiskit_resume/l0_disk/db/__init__.py

@@ -0,0 +1,36 @@
+"""l0_disk.db: the .qresume SQLite file (D-004, D-012, D-014).
+
+IN : file path
+OUT: ExperimentDB (tx(), get_meta/set_meta, ensure_schema(ddl), integrity_check(), close())
+     backup_copy(src, dst) -> Path      consistent copy, safe while running
+     verify_file(path)                  IntegrityError if damaged
+     running_info(path) -> dict | None  {host, pid, started_at} if a run holds the file
+Errors: AlreadyRunningError, IntegrityError, FormatError
+Depends on: nothing
+Owns table: meta
+Contract (signatures, types, errors, invariants): docs/CONTRACTS.md section 1.1
+"""
+
+from qiskit_resume.l0_disk.db.core import (
+    FORMAT_VERSION,
+    AlreadyRunningError,
+    ExperimentDB,
+    FormatError,
+    IntegrityError,
+    backup_copy,
+    running_info,
+    utc_now,
+    verify_file,
+)
+
+__all__ = [
+    "FORMAT_VERSION",
+    "AlreadyRunningError",
+    "ExperimentDB",
+    "FormatError",
+    "IntegrityError",
+    "backup_copy",
+    "running_info",
+    "utc_now",
+    "verify_file",
+]