qtwist 5.0.0__tar.gz

qtwist-5.0.0/LICENSE

@@ -0,0 +1,15 @@
+Q-TWIST — PROPRIETARY SOFTWARE
+
+Copyright (c) 2026 Q-TWIST. All rights reserved.
+
+This software is the proprietary property of Q-TWIST. It is licensed for
+use only under the terms of a separate written license agreement with
+Q-TWIST. No rights are granted except as expressly set forth in such an
+agreement. Unauthorized reproduction, distribution, or use is prohibited.
+
+The Q-TWIST Python SDK (`pip install qtwist`) and web console are 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 non-infringement.
+
+For licensing inquiries, contact Q-TWIST.

qtwist-5.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include pyproject.toml
+include README.md
+include LICENSE
+
+recursive-include qtwist *.py
+recursive-include qtwist/web *.py *.html *.css *.js
+recursive-include qtwist_core *.py *.pt *.json py.typed
+recursive-include tests *.py
+
+prune build
+prune dist
+prune .venv
+prune research
+
+global-exclude *.pyc __pycache__

qtwist-5.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: qtwist
+Version: 5.0.0
+Summary: Q-TWIST: certified-methodology digital twin for noisy quantum processors — engines, Python SDK, and web console.
+Author: Q-TWIST
+License: Proprietary
+Project-URL: Homepage, https://qtwist.example
+Keywords: quantum,simulation,certified,digital-twin,noise
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: threadpoolctl>=3.0
+Requires-Dist: qiskit>=1.0
+Requires-Dist: qiskit-aer>=0.14
+Requires-Dist: qiskit-ibm-runtime>=0.40
+Requires-Dist: quimb>=1.8
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: billing
+Requires-Dist: razorpay>=2.0; extra == "billing"
+Provides-Extra: full
+Requires-Dist: torch>=2.0; extra == "full"
+Requires-Dist: razorpay>=2.0; extra == "full"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# Q-TWIST v5.0 (Beta) — The Honest Oracle
+
+Q-TWIST is a physics-constrained quantum-circuit inference engine that tells
+you **what it can simulate, to what error, and whether your circuit is worth
+running on real hardware** — and refuses, honestly, when it cannot. No silent
+wrong numbers. No "certified digital twin" marketing. Rigorous L1 error bounds,
+and an explicit refusal with a fix when a circuit is out of envelope.
+
+It ships in two tiers:
+
+* **FREE** — a local **`AerSimulator`-style drop-in** that runs on your laptop
+  CPU. Drop it into any Qiskit expectation-value workflow. No token, no bill.
+* **PRO** — a **metered cloud GPU instance** unlocked by a premium token.
+  Costs are previewed *before* every run (IBM-style credit wallet). Adds the
+  **QPU-Readiness Oracle**: a plain-English verdict on whether your circuit is
+  good to submit to a real QPU.
+
+> Live QPU routing is **roadmap**, not shipped. Everything today is classical
+> simulation + an honest readiness verdict. See `qpu_backend.py` for the scaffold.
+
+## Install
+
+```
+python -m pip install qtwist
+```
+
+(Optional full-stack extras for Qiskit circuit input and the adaptive-MPS
+engine: `python -m pip install -e ".[full]"`.)
+
+## Quickstart — free local drop-in
+
+You only need standard Qiskit. `QtwistSimulator` mirrors `AerSimulator`'s
+`run()` / `result()` surface for the expectation-value workflow:
+
+```python
+from qiskit import QuantumCircuit
+from qtwist.aer_compat import QtwistSimulator
+
+# 20-qubit transverse-field Ising model, 3 layers
+qc = QuantumCircuit(20)
+for _ in range(3):
+    for i in range(19):
+        qc.rzz(0.5, i, i + 1)
+    for i in range(20):
+        qc.rx(0.3, i)
+
+sim = QtwistSimulator(instance="local")          # free, laptop CPU
+res = sim.run(qc, observable="Z0Z1", epsilon_target=0.05).result()
+
+print(f"<Z0 Z1> = {res.value():+.6f}  +/-  {res.error:.4f}")
+print(res.explain())                            # QPU-Readiness Oracle verdict
+```
+
+For small circuits (n ≤ 18) on the laptop you can also sample counts:
+
+```python
+counts = res.get_counts(shots=1024)             # Qiskit bit-order (LSB-first)
+```
+
+## The QPU-Readiness Oracle
+
+Every result carries a `qpu_readiness` verdict — the one thing you want to
+know before spending real QPU queue time:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `READY_FOR_QPU` | Within Q-TWIST's validated envelope; value trustworthy within the reported L1 bound | Run it on hardware to validate the physics |
+| `NEEDS_FIXES` | Rejected only for a fixable issue (long-range gate, multi-controlled gate, wrong topology) | Apply the listed suggestions, re-run |
+| `INTRACTABLE` | Beyond classical simulation / QPU-advantage territory | Run on hardware directly if you must; Q-TWIST can't pre-validate |
+
+```python
+print(res.explain())
+# [QPU-Readiness: READY_FOR_QPU]
+# Circuit is within Q-TWIST's validated envelope.  The simulated value ...
+#   value=+0.993923  L1 bound=0.1287  cert=UNCERTIFIED (no live QPU validation)
+```
+
+## Quickstart — premium cloud tier (metered)
+
+```python
+from qtwist.aer_compat import QtwistSimulator
+from qtwist.pricing import Wallet
+
+wallet = Wallet(token="PRO_TOKEN")              # $99 base = 100 credits
+sim = QtwistSimulator(instance="cloud:PRO_TOKEN", wallet=wallet, topology="1D_chain")
+
+print(sim.estimate(qc))                          # pre-flight cost, never bills
+# [PRO / cloud] engine=ENGINE_D n=20 depth=39 -- est. 0.97 credits (~$0.96) ...
+
+res = sim.run(qc, observable="Z0Z1").result()    # charged only after confirm
+print(res.explain())
+```
+
+Tiers:
+| Tier | Runs on | Billing | Capability Classifier | QPU-Readiness Oracle |
+|---|---|---|---|---|
+| FREE | laptop CPU | free | instant | yes (local) |
+| PRO | cloud GPU | metered credit wallet (~1 credit ≈ 1 GPU-min, $99/100) | instant | yes (cloud) |
+| ENTERPRISE | on-prem / custom | quote-based | instant | roadmap |
+
+## What you get, honestly
+
+| Regime | What it means | What you get |
+|---|---|---|
+| CERTIFIED | within envelope, error budget below target, **validated against a live QPU ground truth** | certified expectation + 9-term budget (requires a real `qpu_backend`) |
+| UNCERTIFIED | simulated and consistency-checked, but no QPU was available to validate | honest value + budget, marked UNCERTIFIED |
+| REJECTED | no engine envelope can simulate this circuit | `RejectionResult` with reason + reformulation suggestions, zero compute spent |
+
+We never market "Certified" without a live QPU behind it, and we never claim
+live QPU integration that isn't shipped.
+
+## Topology support
+
+`QTWISTBackend(topology=...)` and `predict(..., topology=...)` accept:
+
+* `"1D_chain"` — Engine D (adaptive MPS) envelope, up to 1024 qubits
+* `"2D_heavy_hex"` — shallow circuits via Engine C; deep heavy-hex is rejected with routing guidance
+* `"all_to_all"` — fully connected, any engine that fits
+* a Qiskit `CouplingMap` — edges are read from the map (1D chains are detected automatically)
+
+## Verification
+
+```
+python prelaunch_audit.py          # 61/61 correctness + honesty checks
+python poc_scientist_programs.py   # 10 real scientist programs
+python poc_research_suite.py       # 1024-qubit QEC via Engine C
+python user_acceptance_test.py     # 20-qubit TFIM sweep + 100-qubit rejection
+python realworld_test.py           # ordinary Qiskit programs vs exact reference
+```

qtwist-5.0.0/README.md

@@ -0,0 +1,129 @@
+# Q-TWIST v5.0 (Beta) — The Honest Oracle
+
+Q-TWIST is a physics-constrained quantum-circuit inference engine that tells
+you **what it can simulate, to what error, and whether your circuit is worth
+running on real hardware** — and refuses, honestly, when it cannot. No silent
+wrong numbers. No "certified digital twin" marketing. Rigorous L1 error bounds,
+and an explicit refusal with a fix when a circuit is out of envelope.
+
+It ships in two tiers:
+
+* **FREE** — a local **`AerSimulator`-style drop-in** that runs on your laptop
+  CPU. Drop it into any Qiskit expectation-value workflow. No token, no bill.
+* **PRO** — a **metered cloud GPU instance** unlocked by a premium token.
+  Costs are previewed *before* every run (IBM-style credit wallet). Adds the
+  **QPU-Readiness Oracle**: a plain-English verdict on whether your circuit is
+  good to submit to a real QPU.
+
+> Live QPU routing is **roadmap**, not shipped. Everything today is classical
+> simulation + an honest readiness verdict. See `qpu_backend.py` for the scaffold.
+
+## Install
+
+```
+python -m pip install qtwist
+```
+
+(Optional full-stack extras for Qiskit circuit input and the adaptive-MPS
+engine: `python -m pip install -e ".[full]"`.)
+
+## Quickstart — free local drop-in
+
+You only need standard Qiskit. `QtwistSimulator` mirrors `AerSimulator`'s
+`run()` / `result()` surface for the expectation-value workflow:
+
+```python
+from qiskit import QuantumCircuit
+from qtwist.aer_compat import QtwistSimulator
+
+# 20-qubit transverse-field Ising model, 3 layers
+qc = QuantumCircuit(20)
+for _ in range(3):
+    for i in range(19):
+        qc.rzz(0.5, i, i + 1)
+    for i in range(20):
+        qc.rx(0.3, i)
+
+sim = QtwistSimulator(instance="local")          # free, laptop CPU
+res = sim.run(qc, observable="Z0Z1", epsilon_target=0.05).result()
+
+print(f"<Z0 Z1> = {res.value():+.6f}  +/-  {res.error:.4f}")
+print(res.explain())                            # QPU-Readiness Oracle verdict
+```
+
+For small circuits (n ≤ 18) on the laptop you can also sample counts:
+
+```python
+counts = res.get_counts(shots=1024)             # Qiskit bit-order (LSB-first)
+```
+
+## The QPU-Readiness Oracle
+
+Every result carries a `qpu_readiness` verdict — the one thing you want to
+know before spending real QPU queue time:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `READY_FOR_QPU` | Within Q-TWIST's validated envelope; value trustworthy within the reported L1 bound | Run it on hardware to validate the physics |
+| `NEEDS_FIXES` | Rejected only for a fixable issue (long-range gate, multi-controlled gate, wrong topology) | Apply the listed suggestions, re-run |
+| `INTRACTABLE` | Beyond classical simulation / QPU-advantage territory | Run on hardware directly if you must; Q-TWIST can't pre-validate |
+
+```python
+print(res.explain())
+# [QPU-Readiness: READY_FOR_QPU]
+# Circuit is within Q-TWIST's validated envelope.  The simulated value ...
+#   value=+0.993923  L1 bound=0.1287  cert=UNCERTIFIED (no live QPU validation)
+```
+
+## Quickstart — premium cloud tier (metered)
+
+```python
+from qtwist.aer_compat import QtwistSimulator
+from qtwist.pricing import Wallet
+
+wallet = Wallet(token="PRO_TOKEN")              # $99 base = 100 credits
+sim = QtwistSimulator(instance="cloud:PRO_TOKEN", wallet=wallet, topology="1D_chain")
+
+print(sim.estimate(qc))                          # pre-flight cost, never bills
+# [PRO / cloud] engine=ENGINE_D n=20 depth=39 -- est. 0.97 credits (~$0.96) ...
+
+res = sim.run(qc, observable="Z0Z1").result()    # charged only after confirm
+print(res.explain())
+```
+
+Tiers:
+| Tier | Runs on | Billing | Capability Classifier | QPU-Readiness Oracle |
+|---|---|---|---|---|
+| FREE | laptop CPU | free | instant | yes (local) |
+| PRO | cloud GPU | metered credit wallet (~1 credit ≈ 1 GPU-min, $99/100) | instant | yes (cloud) |
+| ENTERPRISE | on-prem / custom | quote-based | instant | roadmap |
+
+## What you get, honestly
+
+| Regime | What it means | What you get |
+|---|---|---|
+| CERTIFIED | within envelope, error budget below target, **validated against a live QPU ground truth** | certified expectation + 9-term budget (requires a real `qpu_backend`) |
+| UNCERTIFIED | simulated and consistency-checked, but no QPU was available to validate | honest value + budget, marked UNCERTIFIED |
+| REJECTED | no engine envelope can simulate this circuit | `RejectionResult` with reason + reformulation suggestions, zero compute spent |
+
+We never market "Certified" without a live QPU behind it, and we never claim
+live QPU integration that isn't shipped.
+
+## Topology support
+
+`QTWISTBackend(topology=...)` and `predict(..., topology=...)` accept:
+
+* `"1D_chain"` — Engine D (adaptive MPS) envelope, up to 1024 qubits
+* `"2D_heavy_hex"` — shallow circuits via Engine C; deep heavy-hex is rejected with routing guidance
+* `"all_to_all"` — fully connected, any engine that fits
+* a Qiskit `CouplingMap` — edges are read from the map (1D chains are detected automatically)
+
+## Verification
+
+```
+python prelaunch_audit.py          # 61/61 correctness + honesty checks
+python poc_scientist_programs.py   # 10 real scientist programs
+python poc_research_suite.py       # 1024-qubit QEC via Engine C
+python user_acceptance_test.py     # 20-qubit TFIM sweep + 100-qubit rejection
+python realworld_test.py           # ordinary Qiskit programs vs exact reference
+```

qtwist-5.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qtwist"
+version = "5.0.0"
+description = "Q-TWIST: certified-methodology digital twin for noisy quantum processors — engines, Python SDK, and web console."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Q-TWIST" }]
+keywords = ["quantum", "simulation", "certified", "digital-twin", "noise"]
+dependencies = [
+    "numpy>=2.0",
+    "scipy>=1.11",
+    "threadpoolctl>=3.0",
+    "qiskit>=1.0",
+    "qiskit-aer>=0.14",
+    "qiskit-ibm-runtime>=0.40",
+    "quimb>=1.8",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.0",
+    "python-multipart>=0.0.9",
+]
+
+[project.optional-dependencies]
+torch = ["torch>=2.0"]
+billing = ["razorpay>=2.0"]
+full = ["torch>=2.0", "razorpay>=2.0"]
+test = ["pytest>=8.0", "httpx>=0.27"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[project.scripts]
+qtwist = "qtwist.cli:main"
+
+[project.urls]
+Homepage = "https://qtwist.example"
+
+[tool.setuptools.packages.find]
+include = ["qtwist*", "qtwist_core*"]
+
+[tool.setuptools.package-data]
+qtwist_core = ["certification/models/*.pt", "certification/models/*.json", "py.typed"]
+qtwist = ["web/static/*.html", "web/static/*.css", "web/static/*.js"]

qtwist-5.0.0/qtwist/__init__.py

@@ -0,0 +1,11 @@
+# Q-TWIST v5.0-beta — Python SDK Package
+
+__version__ = "5.0.0-beta"
+
+# Expose the engine packages (physics / router / core / certification) as
+# top-level importable modules via the qtwist_core path shim.
+import qtwist_core  # noqa: F401
+
+from qtwist.api import QTWISTBackend, PredictionResult, RejectionResult
+
+__all__ = ["QTWISTBackend", "PredictionResult", "RejectionResult"]

qtwist-5.0.0/qtwist/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m qtwist.cli` execution."""
+from qtwist.cli import main
+
+if __name__ == "__main__":
+    main()

qtwist-5.0.0/qtwist/aer_compat.py

@@ -0,0 +1,265 @@
+"""
+AerSimulator-compatible drop-in for Q-TWIST.
+
+Free / local tier
+-----------------
+    from qtwist.aer_compat import QtwistSimulator
+
+    sim = QtwistSimulator(instance="local")
+    job = sim.run(qc, observable="Z0Z1", epsilon_target=0.05)
+    res = job.result()
+    print(res.value())          # expectation <Z0Z1>
+    print(res.explain())        # QPU-Readiness Oracle verdict
+    counts = res.get_counts()   # for small circuits (n <= 18) on the laptop
+
+This is a behavioral drop-in for the *expectation-value* workflow that
+Q-TWIST is built for.  It deliberately does NOT pretend to be a generic
+sampler for giant circuits -- that is what the paid cloud GPU tier is for.
+
+Premium / cloud tier
+--------------------
+    sim = QtwistSimulator(instance="cloud:PRO_TOKEN", topology="grid_2d")
+    res = sim.run(qc, observable="Z0Z1")
+
+The same call returns the value + the QPU-Readiness Oracle verdict.  Live
+QPU routing is roadmap-only (see qpu_backend.py); everything here is
+classical simulation + an honest readiness verdict.
+"""
+from typing import Optional
+
+from qtwist.api import QTWISTBackend, PredictionResult, decompose_to_native
+from qtwist.pricing import PricingEngine, Wallet, CostEstimate
+from qtwist.payments import EntitlementStore, token_from_instance
+
+
+def _entry_qubits(entry) -> tuple:
+    """Extract the qubit indices carried by a GateEntry / tuple / entry."""
+    if isinstance(entry, (list, tuple)):
+        qubits = entry[1] if len(entry) > 1 else ()
+        return tuple(qubits) if isinstance(qubits, (list, tuple)) else (qubits,)
+    return tuple(getattr(entry, "qubits", ()))
+
+
+def _infer_n_qubits(circuit) -> int:
+    """Number of qubits, including for native layer lists (no ``num_qubits``).
+
+    Layer-list circuits come in without a ``num_qubits`` attribute; billing
+    must not silently fall back to n=0 (which would floor-price every run).
+    The count is derived from the maximum qubit index used by a gate.
+    """
+    if hasattr(circuit, "num_qubits") and circuit.num_qubits:
+        return int(circuit.num_qubits)
+    m = -1
+    layers = getattr(circuit, "data", circuit) or []
+    for layer in layers:
+        items = getattr(layer, "data", layer) or layer
+        for entry in items:
+            for q in _entry_qubits(entry):
+                try:
+                    i = int(q)
+                except (TypeError, ValueError):
+                    continue
+                if i > m:
+                    m = i
+    return m + 1 if m >= 0 else 0
+
+
+class QtwistResult:
+    """Aer-like result object returned by ``QtwistJob.result()``."""
+
+    def __init__(self, pred: PredictionResult, circuit=None, n_qubits: int = 0):
+        self._pred = pred
+        self._circuit = circuit
+        self._n = n_qubits
+
+    # --- Aer-compatible surface ---
+    def value(self):
+        """Expectation value of the requested observable."""
+        return self._pred.value
+
+    @property
+    def status(self) -> str:
+        return self._pred.status
+
+    @property
+    def error(self) -> float:
+        return self._pred.epsilon_total
+
+    @property
+    def rejection_reason(self) -> Optional[str]:
+        return self._pred.rejection_reason
+
+    def reformulations(self):
+        return list(self._pred.reformulations)
+
+    # --- QPU-Readiness Oracle ---
+    def qpu_readiness(self) -> dict:
+        return self._pred.qpu_readiness
+
+    def explain(self) -> str:
+        return self._pred.explain()
+
+    # --- best-effort counts (small circuits only) ---
+    def get_counts(self, shots: int = 1024) -> dict:
+        """
+        Sample Z-basis bitstring counts (local laptop tier).
+
+        Uses the noise-free TrajectorySampler (Engine A) statevector, which
+        returns counts in Qiskit bit order (qubit 0 = rightmost character).
+
+        Only available for ``n <= 18`` qubits -- beyond that, classical
+        wavefunction sampling is not what the free tier is for; use the
+        cloud GPU tier or stick to ``value()`` for the expectation.
+        """
+        if self._circuit is None:
+            raise RuntimeError("counts not available for this result")
+        if self._n > 18:
+            raise RuntimeError(
+                f"get_counts() for n={self._n} requires the cloud GPU tier; "
+                f"use value() for the expectation on the local tier."
+            )
+        from qtwist.api import normalize_circuit
+        from core.engine_a import TrajectorySampler
+        from physics.lindbladian import LindbladianParams
+
+        ic, nq = normalize_circuit(decompose_to_native(self._circuit))
+        lp = LindbladianParams(
+            n_qubits=nq,
+            T1={i: 1e12 for i in range(nq)},
+            T2={i: 2e12 for i in range(nq)},
+            omega_q={i: 5.0 for i in range(nq)},
+            zz_coupling={}, cr_echo_IX={}, cr_echo_IY={},
+            spectator_phases={}, readout_xtalk={}, topology=[],
+            calibration_timestamp="noise-free-counts",
+            gate_errors={}, gate_durations={}, gate_errors_1q={},
+            readout_errors={},
+        )
+        sa = TrajectorySampler(nq, epsilon_target=1e-9)
+        for layer in ic:
+            for entry in layer:
+                sa.apply_gate_and_noise(
+                    gate=entry[0], qubits=tuple(entry[1]),
+                    lindbladian_params=lp, trajectory_seed=0,
+                    angle=getattr(entry, "angle", None),
+                )
+        return sa.measure(shots=shots)
+
+    def __repr__(self) -> str:
+        return self._pred.certification_block
+
+
+class QtwistJob:
+    """Aer-like job: ``sim.run(...).result()``."""
+
+    def __init__(self, result: QtwistResult):
+        self._result = result
+
+    def result(self) -> QtwistResult:
+        return self._result
+
+
+class QtwistSimulator:
+    """
+    Drop-in replacement for ``qiskit_aer.AerSimulator`` for the
+    expectation-value workflow, with the QPU-Readiness Oracle attached.
+
+    Parameters
+    ----------
+    instance : str
+        "local" (free CPU tier) or "cloud:<TOKEN>" (paid cloud GPU tier).
+    api_token : str
+        Token for the cloud tier (ignored on "local").
+    topology : str | None
+        "chain_1d", "grid_2d", "all_to_all" -- hint for routing.
+    """
+
+    def __init__(self, instance: str = "local", api_token: str = "none",
+                 topology=None, wallet: Optional[Wallet] = None):
+        self.instance = instance
+        # Paid tiers (PRO / ENTERPRISE) both require a bought token + instance
+        # and are metered through a Wallet.  The instance string carries the
+        # entitlement minted by ``RazorpayBilling.provision``; the api_token
+        # is the credential presented with it.
+        self.tier = PricingEngine.tier_for(instance)
+        self._premium = self.tier in ("pro", "enterprise")
+        token = api_token if self._premium else "none"
+        self.backend = QTWISTBackend(api_token=token, topology=topology)
+        self.wallet = wallet
+        self.entitlement = None
+        self._store = None
+        # Resolve a paid entitlement (if any) so a minted ``cloud:<TOKEN>``
+        # string binds a Wallet funded with the actually-purchased credits.
+        self._persist = False
+        if self._premium:
+            ent = EntitlementStore.default().resolve_instance(instance)
+            if ent is not None and ent.active:
+                self.entitlement = ent
+                self._store = EntitlementStore.default()
+                # A store-backed entitlement means every charged credit is
+                # persisted, whether the wallet was auto-built here or
+                # supplied by the caller (double-spend guard).
+                self._persist = True
+                if wallet is None:
+                    self.wallet = Wallet(
+                        token=ent.token, tier=ent.tier,
+                        credits_remaining=ent.credits,
+                    )
+
+    def depth(self, circuit) -> int:
+        if hasattr(circuit, "depth"):
+            return circuit.depth()
+        return len(getattr(circuit, "data", circuit) or [])
+
+    def estimate(self, circuit, observable: str = "Z0Z1",
+                 epsilon_target: float = 0.05) -> CostEstimate:
+        """
+        Pre-flight cost preview (Honest Oracle promise): see the bill
+        BEFORE running.  Never charges.
+
+        Uses the same decomposed circuit as ``run`` so the preview exactly
+        matches the charge the user will see.
+        """
+        dec = decompose_to_native(circuit)
+        pred = self.backend.predict(
+            dec, observable=observable, epsilon_target=epsilon_target
+        )
+        nq = _infer_n_qubits(dec)
+        return PricingEngine.estimate(
+            self.instance, pred.engine, nq, self.depth(dec)
+        )
+
+    def run(self, circuit, observable: str = "Z0Z1",
+            epsilon_target: float = 0.05, charge: bool = True) -> QtwistJob:
+        # Fail CLOSED on billing: a paid tier never runs for free.  Without
+        # a funded wallet (no active entitlement, or a caller wallet with no
+        # credits) there is nothing to meter, so refuse before computing.
+        if self._premium and charge and self.wallet is None:
+            raise RuntimeError(
+                "PRO/ENTERPRISE run requires a funded wallet: this instance "
+                "does not match an active paid entitlement and no wallet was "
+                "supplied. Use estimate() for a pre-flight preview, or top up "
+                "via the Q-TWIST billing portal (Razorpay)."
+            )
+        # Intercept non-native gates (SWAP, RXX, ...) before the engines.
+        circuit = decompose_to_native(circuit)
+        pred = self.backend.predict(
+            circuit, observable=observable, epsilon_target=epsilon_target
+        )
+        nq = _infer_n_qubits(circuit)
+        # cloud tier: charge the pre-flight estimate before returning
+        if self._premium and charge:
+            # Never bill a run that was REJECTED -- no compute was delivered.
+            if not pred.rejection_reason:
+                est = PricingEngine.estimate(
+                    self.instance, pred.engine, nq, self.depth(circuit)
+                )
+                if est.credits > 0:
+                    self.wallet.charge(est.credits)
+                    # Persist the consumed balance so re-instantiating the
+                    # simulator does not re-grant the full purchased credits
+                    # (double-spend guard).
+                    if self._persist and self.entitlement is not None:
+                        self._store.decrement(
+                            self.entitlement.token, est.credits
+                        )
+        return QtwistJob(QtwistResult(pred, circuit=circuit, n_qubits=nq))