quapp-pyquil 0.0.4.dev4__tar.gz → 0.0.4.dev5__tar.gz

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-pyquil
-Version: 0.0.4.dev4
+Version: 0.0.4.dev5
 Summary: QApp pyquil library supporting QApp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: <3.11,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: quapp-common==0.0.11.dev7
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: pyquil==4.15.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-pyquil"
-version = "0.0.4.dev4"
+version = "0.0.4.dev5"
 description = "QApp pyquil library supporting QApp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]
@@ -16,7 +16,7 @@ classifiers = [
 ]
 keywords = ["quapp", "qapp-pyquil", "quantum"]
 dependencies = [
-    "quapp-common==0.0.11.dev7",
+    "quapp-common==0.0.14.dev10",
     "pyquil==4.15.0"
 ]
 requires-python = ">=3.9,<3.11"

quapp_pyquil-0.0.4.dev5/quapp_pyquil/__init__.py

@@ -0,0 +1,5 @@
+
+
+# Imported for the side effect: register_rules() has to run before the
+# first job fails, so this import cannot be made lazy.
+from . import error_rules as _error_rules  # noqa: E402,F401

quapp_pyquil-0.0.4.dev5/quapp_pyquil/error_rules.py

@@ -0,0 +1,107 @@
+#  Quapp Platform Project
+#  error_rules.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""pyQuil / Rigetti-specific error classification rules.
+
+Registered into ``quapp_common.util.error_classifier`` when ``quapp_pyquil`` is
+imported, so ``quapp-common`` never has to depend on pyQuil.
+
+Matching is done on the class **NAME as a string** or on the message text, never
+``isinstance``, and nothing from ``pyquil`` / ``qcs_sdk`` is imported. The reason:
+the classifier has to work even when the SDK is absent.
+
+The first group of rules keys off messages **this lib itself** raises -- checked
+against the code, not guessed:
+
+    quapp_pyquil/model/provider/qapp_pyquil_provider.py:26
+        ValueError('[QAppPyquilProvider] Unsupported device')
+    quapp_pyquil/model/provider/rigetti_pyquil_provider.py:41
+        ValueError('[RigettiPyquilProvider] Unsupported device')
+    quapp_pyquil/factory/pyquil_device_factory.py:35
+        ValueError(f'Unsupported provider type: {provider_type}')
+    quapp_pyquil/factory/pyquil_provider_factory.py:25,36
+        ValueError(f'Unsupported SDK for provider type: {provider_type}')
+
+The last rule matches exception names from pyQuil 4.15 / qcs_sdk (the versions
+pinned in pyproject). If upstream renames them the rule becomes inert rather than
+broken -- the classifier just falls back on the phase.
+
+This lib is also the only one that opens ``RuntimePhase.POLLING``:
+``RigettiPyquilDevice`` really does loop waiting for a result, so a timeout while
+waiting on Rigetti stays separate from a failure at submit time.
+"""
+
+from quapp_common.enum.error_category import ErrorCategory
+from quapp_common.util.error_classifier import Rule, register_rules
+
+DOC_DEVICE = 'errors/pyquil-device'
+DOC_AUTH = 'errors/rigetti-auth'
+
+
+def _message(exception) -> str:
+    return str(exception).lower()
+
+
+def _name(exception) -> str:
+    return type(exception).__name__
+
+
+register_rules(
+        # ----------------- raised by quapp-pyquil itself (checked against code)
+        Rule(match=lambda e: 'unsupported device' in _message(e),
+             category=ErrorCategory.PROVIDER_DEVICE,
+             code='PYQUIL_DEVICE_UNSUPPORTED',
+             resolution="This device is not supported by Quapp's pyQuil lib "
+                        'yet.',
+             steps=('Check the device selected for the job',
+                    'On Rigetti the device name must be a valid QCS QPU or QVM'),
+             doc_slug=DOC_DEVICE),
+
+        Rule(match=lambda e: 'unsupported provider type' in _message(e)
+                             or 'unsupported sdk for provider type' in _message(e),
+             category=ErrorCategory.PROVIDER_DEVICE,
+             code='PYQUIL_PROVIDER_UNSUPPORTED',
+             resolution='This provider/SDK pair is not supported by '
+                        'quapp-pyquil yet.',
+             steps=('Check the providerTag sent with the invoke request',
+                    'quapp-pyquil serves QUAO_QUANTUM_SIMULATOR and RIGETTI'),
+             doc_slug=DOC_DEVICE),
+
+        # ---------------------------------------------- Rigetti QCS credentials
+        # rigetti_pyquil_provider.py uses OAuthSession/RefreshToken; an expired
+        # or wrong token is something the user can fix, not a platform fault.
+        Rule(match=lambda e: 'refresh token' in _message(e)
+                             or 'oauth' in _message(e)
+                             or 'qcs credentials' in _message(e),
+             category=ErrorCategory.AUTHENTICATION,
+             code='RIGETTI_TOKEN_INVALID',
+             resolution="Rigetti's QCS token is invalid or has expired.",
+             steps=('Check the Rigetti credential in your workspace',
+                    'Get a fresh refresh token from QCS and update it'),
+             doc_slug=DOC_AUTH,
+             retryable=False),
+
+        # ----------------------------------- pyQuil 4.15 / qcs_sdk exceptions
+        Rule(match=lambda e: _name(e) in {'QCSHTTPStatusError', 'QCSClientError',
+                                          'LoadClientConfigurationError'},
+             category=ErrorCategory.PROVIDER_UNAVAILABLE,
+             code='RIGETTI_API_UNAVAILABLE',
+             resolution="Rigetti's QCS API could not be reached.",
+             steps=('Try again in a few minutes',
+                    "Check the status of Rigetti's QCS service"),
+             retryable=True,
+             retry_after=120),
+
+        # Placed after every rule above: matching is by NAME, so only these exact
+        # names land here and no subclass gets swallowed.
+        Rule(match=lambda e: _name(e) in {'QuilError', 'QuilSyntaxError',
+                                          'ProgramError', 'ApiError'},
+             category=ErrorCategory.SDK_RUNTIME,
+             code='PYQUIL_SDK_ERROR',
+             resolution='pyQuil failed while building or running the program. '
+                        'See the stack trace below.',
+             steps=('Read the rootCause to see which step pyQuil rejected',
+                    'Check the Quil program and the qubit count the device '
+                    'supports')),
+)

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil/model/device/rigetti_pyquil_device.py

@@ -16,9 +16,11 @@ from quapp_common.data.response.job_response import JobResponse
 
 from quapp_common.component.callback.update_job_metadata import update_job_metadata
 from quapp_common.enum.status.job_status import JobStatus
-from quapp_common.enum.media_type import MediaType
 from quapp_common.enum.status.status_code import StatusCode
+from quapp_common.config.log_context import phase
 from quapp_common.data.callback.callback_url import CallbackUrl
+from quapp_common.enum.runtime_phase import RuntimePhase
+from quapp_common.util.response_utils import build_error_job_response
 import pickle
 import time
 
@@ -93,25 +95,36 @@ class RigettiPyquilDevice(Device):
         update_job_metadata(job_response=job_response,
                             callback_url=execution_callback.on_start)
         try:
-            job = self._create_job(circuit=circuit, options=options)
-            job_response.provider_job_id = self._get_provider_job_id(job)
-            job_response.job_status = self._get_job_status(job)
-            original_job_result = None
-
-            while True:
-                
-                self.logger.debug("fetching job result")
-
-                try:
-                    res = self._get_job_result(job)
-                    self.logger.debug("Job result: {}".format(res))
-                    if res.execution_duration_microseconds is not None:
-                        job_response.job_status = JobStatus.DONE.value
-                        original_job_result = res
-                        break
-                except Exception as e:
-                    self.logger.debug("Job result not ready yet: {}".format(str(e)))
-                time.sleep(5)
+            # A copy of Device.run_circuit that lost every `with phase(...)`, so
+            # until now no rigetti log line carried a phase at all. Three stages are
+            # kept apart because they fail for different reasons: a wrong circuit
+            # type (COMPILATION), Rigetti refusing the job (EXECUTION), and a job
+            # that was accepted but never returns a result (POLLING).
+            with phase(RuntimePhase.COMPILATION):
+                job = self._create_job(circuit=circuit, options=options)
+
+            with phase(RuntimePhase.EXECUTION):
+                job_response.provider_job_id = self._get_provider_job_id(job)
+                job_response.job_status = self._get_job_status(job)
+                original_job_result = None
+
+            # This is the only lib with a real result-waiting loop, and therefore the
+            # only place where RuntimePhase.POLLING means anything.
+            with phase(RuntimePhase.POLLING):
+                while True:
+                    self.logger.debug("fetching job result")
+
+                    try:
+                        res = self._get_job_result(job)
+                        self.logger.debug("Job result: {}".format(res))
+                        if res.execution_duration_microseconds is not None:
+                            job_response.job_status = JobStatus.DONE.value
+                            original_job_result = res
+                            break
+                    except Exception as e:
+                        self.logger.debug(
+                                "Job result not ready yet: {}".format(str(e)))
+                    time.sleep(5)
 
             self.logger.debug("Job result: {}".format(job_response))
 
@@ -121,12 +134,17 @@ class RigettiPyquilDevice(Device):
             return original_job_result, job_response
 
         except Exception as exception:
-            self.logger.debug("Execute job failed with error {}".format(str(exception)))
-
-            job_response.status_code = StatusCode.ERROR
-            job_response.content_type = MediaType.APPLICATION_JSON
-            job_response.job_status = JobStatus.ERROR.value
-            job_response.job_result = {"error": str(exception)}
+            # This used to be `{"error": str(exception)}`: no category, no phase,
+            # no rootCause -- exactly what left the Job Log without a readable
+            # reason. build_error_job_response fills the whole envelope and logs
+            # once itself, so the logger.debug that used to sit here is gone too,
+            # to avoid logging the same error twice.
+            job_response = build_error_job_response(
+                    exception, job_response,
+                    message='Error when executing job',
+                    stage='while running the circuit on the device',
+                    phase=RuntimePhase.EXECUTION,
+                    context=self._error_context())
 
             update_job_metadata(job_response=job_response,
                                 callback_url=execution_callback.on_error)
@@ -148,12 +166,16 @@ class RigettiPyquilDevice(Device):
                             callback_url=analysis_callback.on_start)
 
         try:
-            job_response.job_histogram = self._produce_histogram_data(original_job_result)
+            with phase(RuntimePhase.ANALYSIS):
+                job_response.job_histogram = self._produce_histogram_data(
+                        original_job_result)
+
+                self.execution_time = self._calculate_execution_time(
+                        original_job_result)
 
-            self.execution_time = self._calculate_execution_time(original_job_result)
-            
-            job_response.execution_time = self.execution_time
-            self.logger.debug("Execution time: {}".format(job_response.execution_time))
+                job_response.execution_time = self.execution_time
+                self.logger.debug(
+                        "Execution time: {}".format(job_response.execution_time))
 
             update_job_metadata(
                 job_response=job_response,
@@ -162,13 +184,15 @@ class RigettiPyquilDevice(Device):
             return job_response
 
         except Exception as exception:
-            self.logger.error("Invocation - Exception when analyst job result : {0}".format(
-                str(exception)))
-
-            job_response.status_code = StatusCode.ERROR
-            job_response.content_type = MediaType.APPLICATION_JSON
-            job_response.job_status = JobStatus.ERROR.value
-            job_response.job_result = {"error": str(exception)}
+            # A logger.error() here would emit a second ERROR line for the same
+            # failure: build_error_job_response already logs the full envelope.
+            # Two lines skew every metric that counts job_failed.
+            job_response = build_error_job_response(
+                    exception, job_response,
+                    message='Error when analyzing job result',
+                    stage='while analysing the job result',
+                    phase=RuntimePhase.ANALYSIS,
+                    context=self._error_context())
 
             update_job_metadata(job_response=job_response,
                                 callback_url=analysis_callback.on_error)

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil/model/provider/qapp_pyquil_provider.py

@@ -4,6 +4,11 @@
     Copyright © CITYNOW Co. Ltd. All rights reserved.
 """
 from quapp_common.config.logging_config import logger
+
+# The component name belongs in the `context` field, not in the text
+# of the message: left in the message, Grafana needs a regex to
+# filter on it.
+logger = logger.bind(context='QAppPyquilProvider')
 from quapp_common.enum.provider_tag import ProviderTag
 from quapp_common.model.provider.provider import Provider
 
@@ -12,11 +17,11 @@ from pyquil import get_qc
 
 class QAppPyquilProvider(Provider):
     def __init__(self, ):
-        logger.debug('[QAppPyquilProvider] get_backend()')
+        logger.debug('get_backend()')
         super().__init__(ProviderTag.QUAO_QUANTUM_SIMULATOR)
 
     def get_backend(self, device_specification):
-        logger.debug('[QAppPyquilProvider] get_backend()')
+        logger.debug('get_backend()')
 
         try:
             print(device_specification)
@@ -26,5 +31,5 @@ class QAppPyquilProvider(Provider):
             raise ValueError('[QAppPyquilProvider] Unsupported device')
 
     def collect_provider(self):
-        logger.debug('[QAppPyquilProvider] collect_provider()')
+        logger.debug('collect_provider()')
         return None

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil/model/provider/rigetti_pyquil_provider.py

@@ -4,6 +4,11 @@
     Copyright © CITYNOW Co. Ltd. All rights reserved.
 """
 from quapp_common.config.logging_config import logger
+
+# The component name belongs in the `context` field, not in the text
+# of the message: left in the message, Grafana needs a regex to
+# filter on it.
+logger = logger.bind(context='RigettiPyquilProvider')
 from quapp_common.enum.provider_tag import ProviderTag
 from quapp_common.model.provider.provider import Provider
 
@@ -21,11 +26,11 @@ class RigettiPyquilProvider(Provider):
         self.access_token = access_token
         self.api_url = api_url
         
-        logger.debug('[RigettiPyquilProvider] get_backend()')
+        logger.debug('get_backend()')
         super().__init__(ProviderTag.RIGETTI)
 
     def get_backend(self, device_specification) -> QuantumComputer:
-        logger.debug('[RigettiPyquilProvider] get_backend()')
+        logger.debug('get_backend()')
 
         try:
             auth = AuthServer(client_id=self.client_id, issuer=self.issuer)
@@ -41,5 +46,5 @@ class RigettiPyquilProvider(Provider):
             raise ValueError('[RigettiPyquilProvider] Unsupported device')
 
     def collect_provider(self):
-        logger.debug('[RigettiPyquilProvider] collect_provider()')
+        logger.debug('collect_provider()')
         return None

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-pyquil
-Version: 0.0.4.dev4
+Version: 0.0.4.dev5
 Summary: QApp pyquil library supporting QApp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: <3.11,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: quapp-common==0.0.11.dev7
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: pyquil==4.15.0
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 quapp_pyquil/__init__.py
+quapp_pyquil/error_rules.py
 quapp_pyquil.egg-info/PKG-INFO
 quapp_pyquil.egg-info/SOURCES.txt
 quapp_pyquil.egg-info/dependency_links.txt
@@ -26,4 +27,5 @@ quapp_pyquil/model/device/qapp_pyquil_device.py
 quapp_pyquil/model/device/rigetti_pyquil_device.py
 quapp_pyquil/model/provider/__init__.py
 quapp_pyquil/model/provider/qapp_pyquil_provider.py
-quapp_pyquil/model/provider/rigetti_pyquil_provider.py
+quapp_pyquil/model/provider/rigetti_pyquil_provider.py
+tests/test_error_logging.py

{quapp_pyquil-0.0.4.dev4 → quapp_pyquil-0.0.4.dev5}/quapp_pyquil.egg-info/requires.txt

@@ -1,4 +1,4 @@
-quapp-common==0.0.11.dev7
+quapp-common==0.0.14.dev10
 pyquil==4.15.0
 
 [dev]

quapp_pyquil-0.0.4.dev5/tests/test_error_logging.py

@@ -0,0 +1,304 @@
+#  Quapp Platform Project
+#  test_error_logging.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Locks four classes of error-logging bug, all found in real provider-lib code.
+
+1. **A copied hook lost its phase.** Some devices copied ``run_circuit`` /
+   ``_on_execution`` / ``_on_analysis`` wholesale from ``Device`` but dropped the
+   ``with phase(...)`` blocks, so that lib's log had no ``phase`` field at any
+   stage. Same class of bug as ``CustomDevice._on_analysis`` in quapp-common.
+
+2. **The error was flattened into a string.** ``job_response.job_result =
+   {"error": str(exception)}`` leaves the Job Log with a bare string: no
+   category, no phase, no rootCause -- exactly what the ticket complained about.
+
+3. **The error was logged twice.** ``logger.exception()`` immediately before
+   ``build_error_job_response`` emits a second ERROR line for the same failure,
+   skewing every metric that counts job_failed.
+
+4. **A fake job_id.** ``job_logger('SomeClass')`` -- the first argument of
+   ``job_logger()`` is the **job_id**. Passing a class name there sets a fake
+   job_id and it BEATS the real one (``_inject_job_context`` only fills keys that
+   are still None), so filtering by jobId in Grafana loses every line that
+   component logged.
+
+The tests discover files inside the package, so this file works for any lib
+without hardcoding names.
+"""
+
+import ast
+import io
+import pathlib
+import re
+import tokenize
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+# The first release carrying a phase for analysis/post-processing and one traceId
+# per job.
+MINIMUM_COMMON = '0.0.14.dev6'
+
+# Hooks already instrumented in quapp-common: copying one means copying its
+# phases too. _on_execution creates the job and then talks to the provider, which
+# is why it needs both -- a failed transpile and a rejected job are different
+# errors.
+INSTRUMENTED = {'_on_execution': {'COMPILATION', 'EXECUTION'},
+                '_on_analysis' : {'ANALYSIS'}}
+
+
+def package_root() -> pathlib.Path:
+    """The provider lib's package directory, inferred from the tree.
+
+    A few repos hold more than one package -- quapp-hpc also has
+    ``quapp_slurm_hpc``, which only contains ``runner.py`` for the Slurm node and
+    is not the provider lib. Pick by structural evidence (it has ``model/`` or
+    ``factory/``) rather than by name.
+    """
+    candidates = [d for d in REPO_ROOT.iterdir()
+                  if d.is_dir() and re.fullmatch(r'qu?app_\w+', d.name)
+                  and (d / '__init__.py').is_file()]
+    assert candidates, 'found no package at all'
+
+    if len(candidates) > 1:
+        providers = [d for d in candidates
+                     if (d / 'model').is_dir() or (d / 'factory').is_dir()]
+        assert len(providers) == 1, (
+            f'could not identify the provider package: '
+            f'{providers or candidates}')
+        return providers[0]
+
+    return candidates[0]
+
+
+PACKAGE = package_root()
+
+
+def code_only(path) -> str:
+    """Source with comments stripped out.
+
+    Needed because the explanatory comments *quote* the very code being banned
+    (``{"error": str(exception)}``, ``logger.exception(``). A raw scan would
+    report a false positive on the explanation itself.
+    """
+    source = path.read_text(encoding='utf-8')
+    kept = [token for token in
+            tokenize.generate_tokens(io.StringIO(source).readline)
+            if token.type != tokenize.COMMENT]
+    return tokenize.untokenize(kept)
+
+
+def phases_opened_in(source: str) -> set:
+    """The RuntimePhases opened with ``with phase(...)`` in a piece of code."""
+    tree = ast.parse(source.lstrip())
+    return {
+        argument.attr
+        for node in ast.walk(tree) if isinstance(node, ast.With)
+        for item in node.items if isinstance(item.context_expr, ast.Call)
+        if (getattr(item.context_expr.func, 'id', None)
+            or getattr(item.context_expr.func, 'attr', None)) == 'phase'
+        for argument in item.context_expr.args
+        if isinstance(argument, ast.Attribute)
+    }
+
+
+def python_files():
+    return sorted(PACKAGE.rglob('*.py'))
+
+
+# ------------------------------------------- (1) a copied hook keeps its phases
+
+def test_copied_hooks_keep_their_phases():
+    """Overriding an instrumented hook means copying its `with phase(...)` too."""
+    offenders = []
+    for path in python_files():
+        source = path.read_text(encoding='utf-8')
+        tree = ast.parse(source, filename=str(path))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.FunctionDef) \
+                    or node.name not in INSTRUMENTED:
+                continue
+            opened = phases_opened_in(ast.get_source_segment(source, node))
+            missing = INSTRUMENTED[node.name] - opened
+            if missing:
+                offenders.append(
+                        f'{path.name}::{node.name} is missing {sorted(missing)}')
+
+    assert not offenders, (
+        f'overridden hooks lost their phase: {offenders}. The original in '
+        f'quapp-common has `with phase(...)`; copying it without that leaves the '
+        f'log with no phase field.')
+
+
+def test_at_least_one_phase_is_opened_somewhere():
+    """A lib that overrides no hook needs none; one that does needs a phase."""
+    overrides = any(
+        isinstance(node, ast.FunctionDef) and node.name in INSTRUMENTED
+        for path in python_files()
+        for node in ast.walk(ast.parse(path.read_text(encoding='utf-8')))
+    )
+    if not overrides:
+        pytest.skip('lib overrides no hook; phases come from quapp-common')
+
+    opened = set()
+    for path in python_files():
+        opened |= phases_opened_in(path.read_text(encoding='utf-8'))
+    assert opened, 'hooks are overridden but no phase is opened'
+
+
+# --------------------------------- (2) no hand-rolled error string
+
+@pytest.mark.parametrize('path', python_files(), ids=lambda p: p.name)
+def test_no_hand_rolled_error_dict(path):
+    """`{"error": str(exception)}` bypasses the entire error envelope."""
+    assert '{"error": str(exception)}' not in code_only(path), (
+        f'{path.name}: flattens the error into a string, losing '
+        f'category/phase/rootCause. Use '
+        f'build_error_job_response(..., phase=..., context=...)')
+
+
+def test_error_envelope_carries_phase_and_context():
+    """Every build_error_job_response in the device needs phase= and context=."""
+    for path in python_files():
+        source = code_only(path)
+        calls = source.count('build_error_job_response(')
+        if not calls:
+            continue
+        assert source.count('phase=RuntimePhase.') >= calls, (
+            f'{path.name}: has {calls} error envelopes but is missing phase=, '
+            f'so the ErrorReport would come out with phase=None')
+        assert source.count('context=self._error_context()') >= calls, (
+            f'{path.name}: error envelope is missing context=, leaving support '
+            f'without the device/provider')
+
+
+# ------------------------------------------ (3) one error is logged once
+
+def test_no_duplicate_error_log_before_envelope():
+    """logger.exception()/logger.error() right before the envelope = 2 ERRORs."""
+    offenders = []
+    for path in python_files():
+        source = code_only(path)
+        for match in re.finditer(r'logger\.(exception|error)\(', source):
+            if 'build_error_job_response(' in source[match.end():match.end() + 400]:
+                line = source[:match.start()].count('\n') + 1
+                offenders.append(f'{path.name}:{line}')
+
+    assert not offenders, (
+        f'duplicate ERROR log before build_error_job_response at {offenders}; '
+        f'the envelope already logs once')
+
+
+# ------------------------------------------------- (4) no fake job_id
+
+@pytest.mark.parametrize('path', python_files(), ids=lambda p: p.name)
+def test_no_fake_job_logger_argument(path):
+    """`job_logger()` takes a real job_id; a component name belongs in `context`.
+
+    Two shapes of fake id are caught: a string literal (`job_logger('Provider')`)
+    and `__name__`, which quietly makes the job_id the dotted module path and
+    blows up jobId cardinality in Grafana as well as losing the real job.
+    """
+    tree = ast.parse(path.read_text(encoding='utf-8'), filename=str(path))
+
+    offenders = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not node.args:
+            continue
+        if (getattr(node.func, 'id', None)
+                or getattr(node.func, 'attr', None)) != 'job_logger':
+            continue
+        first = node.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            offenders.append(repr(first.value))
+        elif isinstance(first, ast.Name) and first.id == '__name__':
+            offenders.append('__name__')
+
+    assert not offenders, (
+        f'{path.name}: job_logger() got {offenders} -- those are fake job_ids. '
+        f"Use logger.bind(context='...') for the component name")
+
+
+def test_providers_bind_their_name_to_context():
+    """A provider that logs must bind its own name, so lines say where they came
+    from."""
+    providers = sorted((PACKAGE / 'model' / 'provider').glob('*.py'))
+    if not providers:
+        pytest.skip('lib has no model/provider directory')
+
+    offenders = []
+    for path in providers:
+        if path.name == '__init__.py':
+            continue
+        # code_only: several providers keep their old logging commented out, and
+        # a raw scan would flag those as if they still logged.
+        source = code_only(path)
+        if 'logger' not in source:
+            continue
+        if not re.search(r"logger\.bind\(context='[A-Za-z]+'\)", source):
+            offenders.append(path.name)
+
+    assert not offenders, (
+        f'providers that log without binding context: {offenders}. The component '
+        f'name must be a field, not text inside the message, or Grafana cannot '
+        f'filter on it')
+
+
+# ------------------------------------------ rules + the quapp-common pin
+
+def test_error_rules_module_exists():
+    assert (PACKAGE / 'error_rules.py').is_file(), \
+        "no error_rules.py, so this SDK's errors never get classified"
+
+
+def test_error_rules_are_registered_on_import():
+    init = (PACKAGE / '__init__.py').read_text(encoding='utf-8')
+    assert 'error_rules' in init, \
+        '__init__.py does not import error_rules, so the rules never register'
+
+
+def test_error_rules_imports_no_vendor_sdk():
+    """The classifier has to run even with the SDK absent, hence name matching."""
+    tree = ast.parse((PACKAGE / 'error_rules.py').read_text(encoding='utf-8'))
+
+    roots = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            roots.update(alias.name.split('.')[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module and not node.level:
+            roots.add(node.module.split('.')[0])
+
+    assert roots <= {'quapp_common'}, \
+        f'error_rules.py may only import quapp_common, but imports: {sorted(roots)}'
+
+
+def test_common_pin_is_exact_and_current():
+    version = pytest.importorskip('packaging.version')
+
+    text = (REPO_ROOT / 'pyproject.toml').read_text(encoding='utf-8')
+    assert not re.findall(r'"quapp-common\s*(>=|>|~=)', text), (
+        'quapp-common must be pinned with `==`: `>=` lets pip pick a higher '
+        'stable release that is missing the feature (which already happened '
+        'with quapp-qiskit 1.0.14)')
+
+    match = re.search(r'"quapp-common\s*==\s*([^"]+)"', text)
+    assert match, 'no quapp-common pin found'
+    assert version.Version(match.group(1)) >= version.Version(MINIMUM_COMMON), (
+        f'pin {match.group(1)} < {MINIMUM_COMMON}: that release has no phase for '
+        f'analysis/post-processing and still splits one job into two traceIds')
+
+
+def test_registered_rules_are_reachable():
+    """Runs for real: import the lib and read the registry. Skips without the SDK."""
+    package_name = PACKAGE.name
+    pytest.importorskip(package_name)
+    __import__(package_name)
+    from quapp_common.util.error_classifier import registered_rules
+
+    codes = {rule.code for rule in registered_rules()}
+    own = {code for code in codes if not code.startswith(
+            ('INPUT_', 'DEPENDENCY_', 'PROVIDER_', 'HANDLER_', 'PLATFORM_',
+             'COMPILATION_', 'EXECUTION_', 'ANALYSIS_', 'POST_'))}
+    assert own, f'no lib-specific rule registered, only generic ones: {sorted(codes)}'