quapp-perceval 0.0.1.dev1__tar.gz → 0.0.1.dev3__tar.gz

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-perceval
-Version: 0.0.1.dev1
+Version: 0.0.1.dev3
 Summary: Quapp common library supporting Quapp 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.13.dev3
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: perceval-quandela==1.2.1
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-perceval"
-version = "0.0.1.dev1"
+version = "0.0.1.dev3"
 description = "Quapp common library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]
@@ -16,7 +16,7 @@ classifiers = [
 ]
 keywords = ["quapp", "quapp-perceval", "quantum"]
 dependencies = [
-    "quapp-common==0.0.13.dev3",
+    "quapp-common==0.0.14.dev10",
     "perceval-quandela==1.2.1"
 ]
 requires-python = ">=3.9,<3.11"

quapp_perceval-0.0.1.dev3/quapp_perceval/__init__.py

@@ -0,0 +1,5 @@
+from .factory.perceval_handler_factory import PercevalHandlerFactory
+
+# 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_perceval-0.0.1.dev3/quapp_perceval/error_rules.py

@@ -0,0 +1,82 @@
+#  Quapp Platform Project
+#  error_rules.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Perceval-specific error classification rules.
+
+Registered into ``quapp_common.util.error_classifier`` when ``quapp_perceval`` is
+imported, so ``quapp-common`` never has to depend on Perceval.
+
+Matching is done on the class **NAME as a string**, never ``isinstance``, and
+nothing from ``perceval`` is imported. Same reason as the Qiskit version:
+``import quapp_perceval`` must not demand the vendor SDK, and the classifier has to
+work even when the SDK is absent.
+
+Without any rule here the system still runs: the classifier falls back on the
+phase, so the user just gets a generic ``EXECUTION_FAILED`` /
+``PROVIDER_INVOCATION_FAILED`` instead of a specific code.
+
+The first two rules key off messages **this lib itself** raises -- checked
+against the code, not guessed:
+
+    quapp_perceval/factory/perceval_provider_factory.py:32
+        Exception("Unsupported provider!")
+    quapp_perceval/factory/perceval_device_factory.py:37
+        Exception("Unsupported device!")
+    quapp_perceval/model/provider/quapp_perceval_provider.py:40
+        Exception('Unsupported device')
+
+The last rule matches Perceval exception names. If upstream renames them the rule
+becomes inert rather than broken -- the classifier just falls back on the phase.
+"""
+
+from quapp_common.enum.error_category import ErrorCategory
+from quapp_common.util.error_classifier import Rule, register_rules
+
+DOC_DEVICE = 'errors/perceval-device'
+DOC_CIRCUIT = 'errors/perceval-circuit'
+
+
+def _message(exception) -> str:
+    return str(exception).lower()
+
+
+def _name(exception) -> str:
+    return type(exception).__name__
+
+
+register_rules(
+        # ------------------ raised by quapp-perceval itself (checked against code)
+        Rule(match=lambda e: 'unsupported device' in _message(e)
+                             or 'unsupported provider' in _message(e),
+             category=ErrorCategory.PROVIDER_DEVICE,
+             code='PERCEVAL_DEVICE_UNSUPPORTED',
+             resolution="This device or provider is not supported by Quapp's "
+                        'Perceval lib yet.',
+             steps=('Check the device selected for the job',
+                    'quapp-perceval currently serves QUAO_QUANTUM_SIMULATOR'),
+             doc_slug=DOC_DEVICE),
+
+        Rule(match=lambda e: 'invalid circuit type' in _message(e),
+             category=ErrorCategory.USER_CODE,
+             code='PERCEVAL_INVALID_CIRCUIT_TYPE',
+             resolution='The circuit preparation function did not return a Perceval '
+                        'circuit.',
+             steps=('Check what your processing function returns',
+                    'The circuit must be a perceval.Circuit'),
+             doc_slug=DOC_CIRCUIT),
+
+        # ------------------------------------------------- Perceval's own exceptions
+        # Placed after the rules above: many Perceval exceptions inherit
+        # PercevalException, but matching is by NAME so only these exact names land
+        # here.
+        Rule(match=lambda e: _name(e) in {'PercevalError', 'CircuitError',
+                                          'ProcessorError', 'RPCError'},
+             category=ErrorCategory.SDK_RUNTIME,
+             code='PERCEVAL_SDK_ERROR',
+             resolution='Perceval failed while building or running the circuit. See '
+                        'the stack trace below.',
+             steps=('Read the rootCause to see which step Perceval rejected',
+                    'Check the mode count and processor configuration Perceval '
+                    'supports')),
+)

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/quapp_perceval/model/device/perceval_device.py

@@ -8,14 +8,14 @@ from quapp_common.model.device.custom_device import CustomDevice
 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.data.response.authentication import Authentication
 from quapp_common.data.response.custom_header import CustomHeader
 from quapp_common.data.device.circuit_running_option import CircuitRunningOption
 from quapp_common.enum.invocation_step import InvocationStep
 
+from quapp_common.config.log_context import phase
+from quapp_common.enum.runtime_phase import RuntimePhase
 from quapp_common.util.response_utils import build_error_job_response
 
 from quapp_common.data.callback.callback_url import CallbackUrl
@@ -66,13 +66,20 @@ class PercevalDevice(CustomDevice, ABC):
         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)
+            # A copy of Device.run_circuit that lost every `with phase(...)`, so
+            # until now no perceval log line carried a phase at all. COMPILATION
+            # stays separate from EXECUTION: a wrong circuit type and a provider
+            # rejecting the job are two different failures.
+            with phase(RuntimePhase.COMPILATION):
+                job = self._create_job(circuit=circuit, options=options)
 
-            job_result = self._get_job_result(job)
-            job_response.job_result = job_result
-            original_job_result = job_result
+            with phase(RuntimePhase.EXECUTION):
+                job_response.provider_job_id = self._get_provider_job_id(job)
+                job_response.job_status = self._get_job_status(job)
+
+                job_result = self._get_job_result(job)
+                job_response.job_result = job_result
+                original_job_result = job_result
 
             update_job_metadata(job_response=job_response,
                                 callback_url=execution_callback.on_done)
@@ -80,13 +87,17 @@ class PercevalDevice(CustomDevice, ABC):
             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)
@@ -143,19 +154,20 @@ class PercevalDevice(CustomDevice, ABC):
         update_job_metadata(job_response, analysis_callback.on_start)
 
         try:
-            self.logger.debug(
-                    "Producing histogram data from original job result")
+            with phase(RuntimePhase.ANALYSIS):
+                self.logger.debug(
+                        "Producing histogram data from original job result")
 
-            job_response.job_histogram = self._produce_histogram_data(
-                    original_job_result)
+                job_response.job_histogram = self._produce_histogram_data(
+                        original_job_result)
 
+                self.logger.debug(
+                        "Calculating execution time from parsed results")
+                self._calculate_execution_time(original_job_result)
+                job_response.execution_time = self.execution_time
 
-            self.logger.debug("Calculating execution time from parsed results")
-            self._calculate_execution_time(original_job_result)
-            job_response.execution_time = self.execution_time
-
-            self.logger.debug("Retrieving shot count from job result")
-            job_response.shots = self._get_shots(original_job_result)
+                self.logger.debug("Retrieving shot count from job result")
+                job_response.shots = self._get_shots(original_job_result)
 
             update_job_metadata(job_response, analysis_callback.on_done)
 
@@ -163,12 +175,15 @@ class PercevalDevice(CustomDevice, ABC):
             return job_response
 
         except Exception as exception:
-            self.logger.exception(
-                    f"Exception when analyzing job result: {exception}",
-                    exc_info=True)
-
-            job_response = build_error_job_response(exception, job_response,
-                                                    message='Error when analyzing job result')
+            # A logger.exception() 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, analysis_callback.on_error)
             return None

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/quapp_perceval/model/provider/quapp_perceval_provider.py

@@ -5,11 +5,11 @@
 #  quapp_perceval_provider.py
 #  Copyright © CITYNOW Co. Ltd. All rights reserved.
 
-from quapp_common.config.logging_config import job_logger
+from quapp_common.config.logging_config import logger
 from quapp_common.enum.provider_tag import ProviderTag
 from quapp_common.model.provider.provider import Provider
 
-logger = job_logger('QuappPercevalProvider')
+logger = logger.bind(context='QuappPercevalProvider')
 
 _PROVIDER_TAG = (
         getattr(ProviderTag, "QUANDELA_CLOUD", None)
@@ -35,6 +35,10 @@ class QuappPercevalProvider(Provider):
             token = self._authentication.get("apiKey")
 
             return RemoteProcessor(device_specification, token=token)
-        except Exception:
-            logger.exception(f'Unsupported device: {device_specification}')
-            raise Exception('Unsupported device')
+        except Exception as exception:
+            # A logger.exception() here would emit a second ERROR line: this error
+            # is logged again by build_error_job_response with the full envelope.
+            # `from` keeps the cause chain so the classifier can still read
+            # the SDK's original error.
+            raise Exception(
+                    f'Unsupported device: {device_specification}') from exception

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/quapp_perceval.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-perceval
-Version: 0.0.1.dev1
+Version: 0.0.1.dev3
 Summary: Quapp common library supporting Quapp 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.13.dev3
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: perceval-quandela==1.2.1
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/quapp_perceval.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 quapp_perceval/__init__.py
+quapp_perceval/error_rules.py
 quapp_perceval.egg-info/PKG-INFO
 quapp_perceval.egg-info/SOURCES.txt
 quapp_perceval.egg-info/dependency_links.txt
@@ -23,4 +24,5 @@ quapp_perceval/model/device/__init__.py
 quapp_perceval/model/device/perceval_device.py
 quapp_perceval/model/device/quapp_perceval_device.py
 quapp_perceval/model/provider/__init__.py
-quapp_perceval/model/provider/quapp_perceval_provider.py
+quapp_perceval/model/provider/quapp_perceval_provider.py
+tests/test_error_logging.py

{quapp_perceval-0.0.1.dev1 → quapp_perceval-0.0.1.dev3}/quapp_perceval.egg-info/requires.txt

@@ -1,4 +1,4 @@
-quapp-common==0.0.13.dev3
+quapp-common==0.0.14.dev10
 perceval-quandela==1.2.1
 
 [dev]

quapp_perceval-0.0.1.dev3/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)}'

quapp_perceval-0.0.1.dev1/quapp_perceval/__init__.py

@@ -1 +0,0 @@
-from .factory.perceval_handler_factory import PercevalHandlerFactory