quapp-common 0.0.14.dev6__tar.gz → 0.0.14.dev7__tar.gz

{quapp_common-0.0.14.dev6/quapp_common.egg-info → quapp_common-0.0.14.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.14.dev6
+Version: 0.0.14.dev7
 Summary: Quapp common library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-common"
-version = "0.0.14.dev6"
+version = "0.0.14.dev7"
 description = "Quapp common library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/async_tasks/async_invocation_task.py

@@ -62,10 +62,11 @@ class AsyncInvocationTask(AsyncTask):
             if job_id is None:
                 raise Exception("Job ID is missing from event")
 
-            # Trước đây chỗ này gọi logger.add(sink=sys.stderr, ...) cho MỖI
-            # request: sau N job có N+1 sink và mỗi dòng log in N+1 lần. Sink đã
-            # được cấu hình một lần trong logging_config; ở đây chỉ cần bind
-            # context để mọi log sau đó tự có job_id/trace_id.
+            # This used to call logger.add(sink=sys.stderr, ...) for EVERY
+            # request: after N jobs there were N+1 sinks and every line printed
+            # N+1 times. The sinks are configured once in logging_config; all
+            # that is needed here is binding the context so every later line
+            # carries job_id/trace_id on its own.
             job_log = bind_job(job_id)
 
             # Define the blocking work

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/async_tasks/post_processing_task.py

@@ -41,8 +41,8 @@ class PostProcessingTask(AsyncTask):
                 job_result_post_processing = self.post_processing_fn(
                         self.promise.job_result)
 
-                # print() cũ ghi thẳng ra stdout, không qua sink nên không được
-                # redact và không có job_id.
+                # The old print() went straight to stdout, bypassing the
+                # sink, so it was neither redacted nor tagged with a job_id.
                 self.logger.debug(
                         f"Parsing job result: type={type(job_result_post_processing).__name__}")
                 job_response.job_result = parse(job_result_post_processing)

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/backend/invocation.py

@@ -130,9 +130,10 @@ class Invocation(ABC):
             self.logger.debug(
                     f"Executing job with provider tag: {provider_tag.value}")
 
-            # PROVIDER_INVOCATION tách riêng khỏi EXECUTION: lỗi authenticate
-            # với provider và lỗi provider từ chối circuit là hai chuyện khác
-            # nhau, trước đây cùng ra nhãn EXECUTION.
+            # PROVIDER_INVOCATION is kept apart from EXECUTION: failing to
+            # authenticate with the provider and the provider rejecting the
+            # circuit are two different things, and they used to share the
+            # EXECUTION label.
             with phase(RuntimePhase.PROVIDER_INVOCATION):
                 provider = self._create_provider()
 

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/backend/job_fetching.py

@@ -182,9 +182,10 @@ class JobFetching(ABC):
         PostProcessingTask(post_processing_fn=post_processing_fn,
                            promise=promise).do()
 
-    # Trước đây hai method dưới là @staticmethod nhưng vẫn dùng `self.logger`,
-    # nên chúng raise NameError ngay khi được gọi -- biến lỗi analysis thành một
-    # lỗi vô nghĩa hoàn toàn khác. Bỏ @staticmethod để `self` hợp lệ.
+    # The two methods below used to be @staticmethod while still using
+    # `self.logger`, so they raised NameError the moment they were called --
+    # turning an analysis error into a completely unrelated, meaningless one.
+    # Dropping @staticmethod makes `self` valid.
     def __produce_histogram_data(self, job_result) -> Any | None:
         """
 

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/bridge.py

@@ -47,10 +47,10 @@ class SubprocessBridge:
         logger.info(f"SubprocessBridge.processing: dispatching to {self.language.value} | sdk={self.sdk}")
         logger.debug(f"SubprocessBridge.processing: input_keys={list(invocation_input.keys())}")
 
-        # dispatch() đã raise HandlerRuntimeError cho mọi trường hợp lỗi
-        # (structured error, exit code khác 0, signal, output không hợp lệ) với
-        # đầy đủ error_type / stack của runner, nên ở đây không cần kiểm
-        # status == "error" nữa.
+        # dispatch() already raises HandlerRuntimeError for every failure
+        # mode (structured error, non-zero exit code, signal, unusable output)
+        # carrying the runner's error_type and stack, so there is no need to
+        # check status == "error" here any more.
         result = dispatch(self.language, {
             "action": "processing",
             "input": invocation_input
@@ -61,12 +61,12 @@ class SubprocessBridge:
             raise HandlerRuntimeError(
                     language=self.language.value, action='processing',
                     error_type='InvalidOutput',
-                    message="Handler không trả về field 'result'.")
+                    message="The handler returned no 'result' field.")
         if not isinstance(payload, dict):
             raise HandlerRuntimeError(
                     language=self.language.value, action='processing',
                     error_type='InvalidOutput',
-                    message=f"Field 'result' phải là object, nhận được "
+                    message=f"The 'result' field must be an object, got "
                             f"{type(payload).__name__}.")
 
         fmt = payload.get("format")
@@ -105,7 +105,7 @@ class SubprocessBridge:
             raise HandlerRuntimeError(
                     language=self.language.value, action='post_processing',
                     error_type='InvalidOutput',
-                    message="Handler không trả về field 'result'.")
+                    message="The handler returned no 'result' field.")
 
         logger.info(f"SubprocessBridge.post_processing: completed successfully | result type={type(payload).__name__}")
         return payload

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/circuit_adapter.py

@@ -2,25 +2,27 @@
 #  circuit_adapter.py
 #  Copyright © CITYNOW Co. Ltd. All rights reserved.
 
-"""Chuyển circuit từ định dạng trung gian (OpenQASM / QUBO / JSON) sang object
-native của từng SDK.
-
-Mọi SDK được import LAZY, ngay bên trong handler cần nó. Lý do:
-
-``quapp-common`` không được phụ thuộc SDK nào. Mỗi lib con
-(``quapp-qiskit``, ``qapp-pennylane``, ...) tự khai báo SDK của nó, và một
-function image chỉ cài đúng SDK nó dùng. Nếu file này import ở module level thì:
-
-- ``import quapp_common.component.bridge`` đòi có ĐỦ 6 SDK cùng lúc, kể cả khi
-  function chỉ chạy Qiskit -- điều này vô hiệu hoá thiết kế lazy-import của
-  ``js-*/index.py`` trong quapp-sdk-templates (comment trong đó ghi rõ ý định
-  "so the server can start even if optional dependencies are missing");
-- cài chung 6 SDK gây xung đột version thật, đã xảy ra với ``pytket``/``lark``
-  và ``pennylane-rigetti``/``pyquil``.
-
-Khi SDK thiếu, handler raise ``ModuleNotFoundError`` -- classifier map thành
-``DEPENDENCY_MISSING`` và user nhận được hướng dẫn thêm package vào
-requirements.txt.
+"""Convert a circuit from an intermediate format (OpenQASM / QUBO / JSON) into
+the native object of each SDK.
+
+Every SDK is imported LAZILY, inside the handler that needs it. The reason:
+
+``quapp-common`` must not depend on any SDK. Each child lib
+(``quapp-qiskit``, ``qapp-pennylane``, ...) declares its own SDK, and a function
+image installs only the SDK it actually uses. Importing at module level here
+would mean:
+
+- ``import quapp_common.component.bridge`` demanding ALL 6 SDKs at once, even
+  when the function only runs Qiskit -- which defeats the lazy-import design of
+  ``js-*/index.py`` in quapp-sdk-templates (whose comment states the intent
+  outright: "so the server can start even if optional dependencies are
+  missing");
+- installing all 6 SDKs together causes real version conflicts; it already
+  happened with ``pytket``/``lark`` and ``pennylane-rigetti``/``pyquil``.
+
+When an SDK is missing, the handler raises ``ModuleNotFoundError`` -- the
+classifier maps that to ``DEPENDENCY_MISSING`` and the user is told to add the
+package to requirements.txt.
 """
 
 import importlib
@@ -34,21 +36,22 @@ logger = logger.bind(context=__name__)
 
 
 def _require(module_name: str, package_hint: str = None):
-    """Import module của SDK, báo lỗi rõ ràng nếu thiếu.
+    """Import an SDK module, failing with a clear message when it is absent.
 
-    @param module_name: tên module cần import, ví dụ 'qiskit.qasm2'.
-    @param package_hint: tên package trên PyPI để nhắc user, nếu khác module.
-    @raise ModuleNotFoundError: giữ đúng kiểu này để classifier phân loại thành
-                                DEPENDENCY_MISSING.
+    @param module_name: the module to import, e.g. 'qiskit.qasm2'.
+    @param package_hint: the PyPI package name to mention to the user, when it
+                         differs from the module name.
+    @raise ModuleNotFoundError: deliberately this exact type, so the classifier
+                                maps it to DEPENDENCY_MISSING.
     """
     try:
         return importlib.import_module(module_name)
     except ImportError as exception:
         package = package_hint or module_name.split('.')[0]
         raise ModuleNotFoundError(
-                f"SDK '{package}' chưa được cài trong function image nhưng "
-                f"circuit cần nó. Thêm '{package}' vào requirements.txt của "
-                f"function rồi deploy lại.") from exception
+                f"SDK '{package}' is not installed in the function image but "
+                f"the circuit needs it. Add '{package}' to the function's "
+                f"requirements.txt and deploy again.") from exception
 
 
 def _qiskit_quantum_circuit():
@@ -56,9 +59,9 @@ def _qiskit_quantum_circuit():
 
 
 def _load_qasm_circuit(qasm_str: str):
-    """Parse OpenQASM 2.0 string thành Qiskit QuantumCircuit.
+    """Parse an OpenQASM 2.0 string into a Qiskit QuantumCircuit.
 
-    Tương thích Qiskit >= 1.0 (``qiskit.qasm2.loads``) và < 1.0
+    Compatible with Qiskit >= 1.0 (``qiskit.qasm2.loads``) and < 1.0
     (``QuantumCircuit.from_qasm_str``).
     """
     try:

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/device/device_selection.py

@@ -65,17 +65,17 @@ class DeviceSelection:
                     'Select device fail with status code: {0}'.format(
                             response.status_code))
 
-            # Không đưa response.content thô vào exception: nội dung này chảy
-            # vào job_result rồi hiện lên UI, và có thể mang theo credential.
+            # Do not put raw response.content on the exception: it flows
+            # into job_result and onto the UI, and may carry a credential.
             raise ValueError(
                     f'Select device failed with status code '
-                    f'{response.status_code}. Xem Function Log để biết chi tiết.')
+                    f'{response.status_code}. See the Function Log for details.')
 
         try:
             response_dict = response.json().get("data")
 
-            # response_dict chứa cả `authentication` = token của provider, nên
-            # chỉ log các field không phải secret.
+            # response_dict also holds `authentication`, the provider token,
+            # so only the non-secret fields are logged.
             logger.debug(
                     'Select device successfully: providerTag={0}, deviceName={1}'.format(
                             response_dict.get("providerTag"),

{quapp_common-0.0.14.dev6 → quapp_common-0.0.14.dev7}/quapp_common/component/dispatcher.py

@@ -2,24 +2,26 @@
 #  dispatcher.py
 #  Copyright © CITYNOW Co. Ltd. All rights reserved.
 
-"""Dispatch request tới runner của các runtime không phải Python (JS / Q# / C).
+"""Dispatch a request to the runner of a non-Python runtime (JS / Q# / C).
 
-Về error handling: trước đây ``subprocess.run`` được gọi với ``check=True``, nên
-``CalledProcessError`` được raise TRƯỚC khi kịp đọc output của runner. Hệ quả là
-nhánh ``_extract_error_message()`` -- vốn để đọc ``{"status":"error",...}`` mà
-``handler_runner.c`` đã phát ra đúng chuẩn -- thành dead code, và user chỉ nhận
-được ``Command '[...]' returned non-zero exit status 1``.
+On error handling: ``subprocess.run`` used to be called with ``check=True``, so
+``CalledProcessError`` was raised BEFORE the runner's output could be read. As a
+result the ``_extract_error_message()`` branch -- written to read the
+``{"status":"error",...}`` that ``handler_runner.c`` already emits correctly --
+was dead code, and all the user ever saw was
+``Command '[...]' returned non-zero exit status 1``.
 
-Nay ``check=True`` được bỏ và output được phân loại thành ``HandlerRuntimeError``
-mang đủ ngữ cảnh: loại lỗi, message, stack của runner, exit code, signal. Sáu
-tình huống được phân biệt:
+``check=True`` is now gone and the output is classified into a
+``HandlerRuntimeError`` carrying the full context: error kind, message, the
+runner's stack, exit code, signal. Six situations are told apart:
 
-    1. runner không tồn tại trong image (lỗi build, không phải lỗi user)
+    1. the runner is absent from the image (a build problem, not the user's)
     2. timeout
-    3. process bị signal (returncode < 0) -- ví dụ handler.c segfault, stdout rỗng
-    4. runner phát structured error trên stdout theo contract
-    5. exit code khác 0 nhưng không có structured error -- lấy stderr
-    6. exit code 0 nhưng stdout không phải JSON hợp lệ
+    3. the process was signalled (returncode < 0) -- e.g. handler.c segfaults and
+       stdout is empty
+    4. the runner emitted a structured error on stdout per the contract
+    5. a non-zero exit code with no structured error -- fall back to stderr
+    6. exit code 0 but stdout is not valid JSON
 """
 
 import json
@@ -50,15 +52,15 @@ RUNNER_MAP = {
     },
 }
 
-# Giới hạn độ dài stack/stderr đưa vào exception để không làm phình job_result.
+# Cap the stack/stderr length carried on the exception so job_result stays small.
 _MAX_DETAIL_LENGTH = 8000
 
 
 class HandlerRuntimeError(RuntimeError):
-    """Lỗi phát sinh trong handler do user viết (JS / Q# / C).
+    """An error raised inside the user-written handler (JS / Q# / C).
 
-    Giữ lại stack trace của runtime gốc (JS stack, .NET stack) -- đây mới là thứ
-    user cần để sửa handler, không phải traceback Python.
+    Keeps the original runtime's stack trace (JS stack, .NET stack) -- that is
+    what the user needs in order to fix the handler, not a Python traceback.
     """
 
     def __init__(self, language: str, action: str = None,
@@ -96,8 +98,9 @@ def dispatch(language: Language, request_data: dict,
         Parsed JSON dict from the subprocess stdout.
 
     Raises:
-        ValueError: khi language chưa có runner.
-        HandlerRuntimeError: khi handler lỗi, crash, timeout hoặc trả output sai.
+        ValueError: when the language has no runner configured.
+        HandlerRuntimeError: when the handler errors, crashes, times out or
+            returns unusable output.
     """
     runner = RUNNER_MAP.get(language)
     if runner is None:
@@ -123,16 +126,17 @@ def dispatch(language: Language, request_data: dict,
                 f"Handler runner timed out after {effective_timeout}s")
         raise HandlerRuntimeError(
                 language=language.value, action=action, error_type='Timeout',
-                message=f'Handler vượt giới hạn thời gian {effective_timeout}s.',
+                message=f'The handler exceeded its {effective_timeout}s time limit.',
                 stack=_truncate(exception.stderr)) from exception
     except FileNotFoundError as exception:
-        # Runner không có trong image -- lỗi build/deploy, không phải lỗi user.
+        # The runner is absent from the image -- a build/deploy problem, not the
+        # user's code.
         logger.bind(event='runner_missing').error(
                 f"Handler runner not found: {runner['command']}")
         raise HandlerRuntimeError(
                 language=language.value, action=action,
                 error_type='RunnerNotFound',
-                message=f"Không tìm thấy runner '{runner['command'][0]}' trong "
+                message=f"Runner '{runner['command'][0]}' was not found in the "
                         f"function image.") from exception
 
     if result.stderr:
@@ -140,16 +144,16 @@ def dispatch(language: Language, request_data: dict,
 
     output = _safe_json(result.stdout)
 
-    # (3) Bị kết thúc bởi signal: returncode âm. Thường gặp nhất là handler.c
-    # truy cập bộ nhớ không hợp lệ -- process chết, stdout rỗng.
+    # (3) Killed by a signal: negative returncode. The most common case is
+    # handler.c touching invalid memory -- the process dies with empty stdout.
     if result.returncode is not None and result.returncode < 0:
         name = _signal_name(-result.returncode)
         logger.bind(event='runner_signal', signal_name=name).error(
                 f"Handler runner killed by {name}")
         raise HandlerRuntimeError(
                 language=language.value, action=action, error_type='Signal',
-                message=f'Handler bị kết thúc bởi signal {name}. Thường do truy '
-                        f'cập bộ nhớ không hợp lệ trong handler.',
+                message=f'The handler was killed by signal {name}, usually an '
+                        f'invalid memory access inside the handler.',
                 stack=_truncate(result.stderr), exit_code=result.returncode,
                 signal_name=name)
 
@@ -157,7 +161,7 @@ def dispatch(language: Language, request_data: dict,
     if isinstance(output, dict) and output.get('status') == 'error':
         detail = output.get('error')
         if isinstance(detail, str):
-            # Contract cũ: `error` là một string. Vẫn phải đọc được.
+            # Older contract: `error` is a plain string. Still has to be read.
             detail = {'message': detail}
         detail = detail or {}
         message = (detail.get('message') or output.get('stack')
@@ -172,9 +176,9 @@ def dispatch(language: Language, request_data: dict,
                 stack=_truncate(detail.get('stack') or result.stderr),
                 exit_code=result.returncode)
 
-    # (5) Exit khác 0 nhưng không có structured error -- lấy stderr làm message.
-    # Đây là đường đi hiện tại của handler_runner.js và handler_runner.cs, vốn
-    # ghi stack ra stderr rồi exit 1.
+    # (5) Non-zero exit with no structured error -- use stderr as the message.
+    # This is the path handler_runner.js and handler_runner.cs currently take:
+    # they write the stack to stderr and exit 1.
     if result.returncode != 0:
         message = (result.stderr or '').strip() \
                   or f'Handler exited with code {result.returncode}'
@@ -187,15 +191,15 @@ def dispatch(language: Language, request_data: dict,
                 error_type='NonZeroExit', message=message,
                 stack=_truncate(result.stderr), exit_code=result.returncode)
 
-    # (6) Exit 0 nhưng output không dùng được.
+    # (6) Exit 0 but the output is unusable.
     if output is None:
         logger.bind(event='runner_invalid_output').error(
                 'Handler runner produced no valid JSON on stdout')
         raise HandlerRuntimeError(
                 language=language.value, action=action,
                 error_type='InvalidOutput',
-                message='Handler không trả về JSON hợp lệ trên stdout. Kiểm tra '
-                        'xem có print/console.log lẫn vào output không.',
+                message='The handler did not return valid JSON on stdout. Check '
+                        'for stray print/console.log mixed into the output.',
                 stack=_truncate(result.stdout), exit_code=result.returncode)
 
     return output
@@ -225,7 +229,7 @@ def is_subprocess_language(language_str: str) -> bool:
 
 
 def _safe_json(text):
-    """Parse JSON, trả None nếu không parse được (thay vì raise)."""
+    """Parse JSON, returning None when it will not parse (instead of raising)."""
     if not text:
         return None
     try:
@@ -251,8 +255,8 @@ def _truncate(text, limit: int = _MAX_DETAIL_LENGTH):
 def _extract_error_message(result) -> str:
     """Extract the most meaningful error message from a failed subprocess.
 
-    Giữ lại cho tương thích ngược với code gọi từ ngoài; logic phân loại chính
-    đã chuyển vào `dispatch()`.
+    Kept for backward compatibility with outside callers; the main classification
+    logic has moved into `dispatch()`.
 
     Priority order:
       1. Structured JSON on stdout  – {"status":"error","error":"..."}

quapp_common-0.0.14.dev7/quapp_common/config/log_context.py

@@ -0,0 +1,201 @@
+#  Quapp Platform Project
+#  log_context.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Per-job logging context.
+
+Why it exists: previously every call site had to pass ``job_id`` into
+``job_logger()`` by hand, and many of them forgot -- ``Device.__init__``,
+``Provider``, ``DeviceSelection`` and the ``*Factory`` classes all used
+``logger.bind(context='...')`` or called ``job_logger()`` with no argument, so
+their lines landed in the ``"QuappLibs"`` context and could not be attached to
+any job in the Job Log UI.
+
+The fix: bind the context ONCE at the start of the request into ``contextvars``.
+Every line logged afterwards -- including third-party library lines coming
+through ``InterceptHandler`` -- then carries ``job_id`` / ``trace_id`` / ``sdk``
+/ ``provider`` / ``device`` on its own.
+
+Threading note: ``contextvars`` does NOT propagate through
+``ThreadPoolExecutor.submit()``. ``circuit_running_pool`` is used for analysis
+and finalization, so those two phases lose the context unless the pool copies it
+-- see ``thread_config.ContextAwareThreadPoolExecutor`` (Phase 1).
+"""
+
+import contextvars
+import time
+import uuid
+from contextlib import contextmanager
+
+from loguru import logger
+
+from ..enum.runtime_phase import RuntimePhase
+
+JOB_ID = 'job_id'
+TRACE_ID = 'trace_id'
+
+_CONTEXT_KEYS = (JOB_ID, TRACE_ID, 'sdk', 'provider', 'device',
+                 'provider_job_id')
+
+_JOB_CONTEXT: contextvars.ContextVar[dict] = contextvars.ContextVar(
+        'quapp_job_context', default={})
+
+_PHASE: contextvars.ContextVar['RuntimePhase | None'] = contextvars.ContextVar(
+        'quapp_phase', default=None)
+
+# The phase an exception most recently escaped from.
+#
+# This needs its own variable because `phase()` resets _PHASE in its `finally`,
+# while the `except` block that handles the error almost always sits OUTSIDE the
+# `with phase(...)` block:
+#
+#     try:
+#         with phase(RuntimePhase.COMPILATION):
+#             transpile(...)
+#     except Exception:            # <- _PHASE is already None here
+#         build_error_job_response(...)
+#
+# Without this variable every ErrorReport would carry phase=None and the
+# phase-based fallback would never run.
+_FAILED_PHASE: contextvars.ContextVar[
+    'RuntimePhase | None'] = contextvars.ContextVar(
+        'quapp_failed_phase', default=None)
+
+
+def bind_job(job_id: str = None, *, sdk=None, provider=None, device=None,
+             provider_job_id=None, trace_id=None):
+    """Initialise the context for one job and return the bound logger.
+
+    Call it once, as early as possible -- ``Handler.__init__`` or ``index.py``.
+
+    @param job_id: the job id on the Quapp backend side
+    @param trace_id: generated when not supplied; used to join Function Log to
+                     Job Log
+    @return: a logger with the whole context bound
+    """
+    # A job gets bound twice (AsyncInvocationTask, then Handler.__init__).
+    # Previously each call generated a fresh trace_id, so one job ended up with
+    # two different traceIds and filtering by traceId lost the lines at the
+    # entry point. Keep the existing trace while it is still the same job; a
+    # different job must get a new trace, never a mixed one.
+    current = _JOB_CONTEXT.get()
+    inherited = (current.get(TRACE_ID)
+                 if current.get(JOB_ID) in (None, job_id) else None)
+
+    context = {JOB_ID          : job_id,
+               TRACE_ID        : trace_id or inherited or uuid.uuid4().hex[:16],
+               'sdk'           : sdk,
+               'provider'      : provider,
+               'device'        : device,
+               'provider_job_id': provider_job_id}
+    _JOB_CONTEXT.set(context)
+    _FAILED_PHASE.set(None)
+    return logger.bind(**context)
+
+
+def enrich_job_context(**fields):
+    """Add fields once more is known (device_name after device selection,
+    provider_job_id after submit...). Only keys in _CONTEXT_KEYS are accepted.
+
+    @return: a logger bound to the updated context
+    """
+    context = dict(_JOB_CONTEXT.get())
+    context.update(
+            {key: value for key, value in fields.items() if key in _CONTEXT_KEYS})
+    _JOB_CONTEXT.set(context)
+    return logger.bind(**context)
+
+
+def job_context() -> dict:
+    """Snapshot of the current context. Empty dict when nothing is bound yet."""
+    return dict(_JOB_CONTEXT.get())
+
+
+def current_job_id() -> str | None:
+    return _JOB_CONTEXT.get().get(JOB_ID)
+
+
+def trace_id() -> str | None:
+    return _JOB_CONTEXT.get().get(TRACE_ID)
+
+
+def current_phase():
+    """The RuntimePhase currently open, or None."""
+    return _PHASE.get()
+
+
+def failed_phase():
+    """The phase an exception most recently escaped from in this job, or None."""
+    return _FAILED_PHASE.get()
+
+
+def effective_phase():
+    """The phase to classify an error with: the open one, else the failed one.
+
+    This is the function the error-reporting path should call -- an `except`
+    block is nearly always outside `with phase(...)`, so `current_phase()` on
+    its own would return None.
+    """
+    return _PHASE.get() or _FAILED_PHASE.get()
+
+
+def current_phase_value():
+    """The str value of the open phase, for binding onto log lines."""
+    phase = _PHASE.get()
+    return phase.value if phase is not None else None
+
+
+@contextmanager
+def phase(runtime_phase: RuntimePhase):
+    """Mark a runtime phase.
+
+    It does three things at once:
+
+    1. stamps ``phase`` onto every line logged inside, including third-party
+       library lines coming through ``InterceptHandler``;
+    2. emits ``phase_start`` / ``phase_end`` / ``phase_failed`` events with
+       ``duration_ms`` -- exactly the data the UI needs to draw a timeline and
+       point at the step where the job died;
+    3. supplies the phase to the classifier when an exception flies out, with no
+       call site having to pass it by hand.
+
+    Phases may nest: a child phase restores its parent on exit.
+
+    @return: a logger bound to the context plus the phase
+    """
+    token = _PHASE.set(runtime_phase)
+    bound = logger.bind(**_JOB_CONTEXT.get(), phase=runtime_phase.value)
+    started = time.perf_counter()
+    bound.bind(event='phase_start').info(f'{runtime_phase.value} started')
+
+    try:
+        yield bound
+    except BaseException:
+        # Record it so the outer except block -- where _PHASE has already been
+        # reset -- still knows which phase the error escaped from.
+        _FAILED_PHASE.set(runtime_phase)
+        elapsed = _elapsed_ms(started)
+        # WARNING rather than DEBUG: this is a timeline marker and has to be
+        # visible at LOG_LEVEL=INFO. No traceback attached, because
+        # build_error_job_response logs the full exception right after -- that
+        # avoids printing the stack twice.
+        bound.bind(event='phase_failed', duration_ms=elapsed).warning(
+                f'{runtime_phase.value} failed after {elapsed} ms')
+        raise
+    else:
+        elapsed = _elapsed_ms(started)
+        bound.bind(event='phase_end', duration_ms=elapsed).info(
+                f'{runtime_phase.value} completed in {elapsed} ms')
+    finally:
+        _PHASE.reset(token)
+
+
+def _elapsed_ms(started: float) -> float:
+    return round((time.perf_counter() - started) * 1000, 2)
+
+
+def reset() -> None:
+    """Clear the context. Mainly used by tests."""
+    _JOB_CONTEXT.set({})
+    _PHASE.set(None)
+    _FAILED_PHASE.set(None)