joobq 0.1.0__py3-none-any.whl

joobq/__init__.py

@@ -0,0 +1,1645 @@
+# Code generated by joobqui-selfhosted sdk:generate (v0.1.0) from JoobQ Polyglot SDK Gateway API. DO NOT EDIT.
+# Supported Gateway Operations:
+#   - POST /api/v1/sdk/batches: Create a Pro batch of jobs with completion callbacks, filled and sealed in one call (Pro)
+#   - GET /api/v1/sdk/batches/{id}: Read a Pro batch's progress: pending, succeeded and failed members (Pro)
+#   - POST /api/v1/sdk/blueprints: Register a workflow blueprint, versioned by its content hash
+#   - POST /api/v1/sdk/jobs: Enqueue a background job onto a queue
+#   - POST /api/v1/sdk/jobs/batch: Enqueue up to 500 background jobs in one call
+#   - GET /api/v1/sdk/openapi.json: Describe the Polyglot SDK Gateway API as an OpenAPI 3.1 document
+#   - POST /api/v1/sdk/rate-limit: Reserve one slot of a sliding-window rate limit (Pro)
+#   - POST /api/v1/sdk/schedules: Register a code-declared cron/recurring job or workflow schedule, idempotent by name
+#   - POST /api/v1/sdk/tasks/ack: Settle up to 100 task leases in one call, each completed or failed
+#   - POST /api/v1/sdk/tasks/heartbeat: Extend every lease a worker holds in one call and check each for cancellation
+#   - POST /api/v1/sdk/tasks/poll: Claim due jobs and workflow steps from unpaused queues
+#   - POST /api/v1/sdk/tasks/{token}/complete: Commit task completion and output
+#   - POST /api/v1/sdk/tasks/{token}/fail: Record structured polyglot task failure and stack frames
+#   - POST /api/v1/sdk/tasks/{token}/heartbeat: Extend an active task lease and check for cancellation
+#   - POST /api/v1/sdk/workers/register: Register or heartbeat a polyglot SDK worker
+#   - POST /api/v1/sdk/workers/{id}/deregister: Deregister a polyglot SDK worker on shutdown
+#   - POST /api/v1/sdk/workflows: Start a durable workflow execution
+#   - GET /api/v1/sdk/workflows/{id}: Describe one workflow run: status, output, failure and search attributes
+#   - GET /api/v1/sdk/workflows/{id}/history: The events of a workflow run, after after_seq, at most limit
+#   - POST /api/v1/sdk/workflows/{id}/query: Ask a workflow run a read-only question
+#   - GET /api/v1/sdk/workflows/{id}/result: The outcome of a workflow, following continue-as-new; waits up to wait_ms for it to close
+#   - POST /api/v1/sdk/workflows/{id}/search-attributes: Set and remove search attributes of a workflow's open run
+#   - POST /api/v1/sdk/workflows/{id}/signal: Deliver an asynchronous signal to a running workflow
+#   - POST /api/v1/sdk/workflows/{id}/updates: Send an update to a running workflow and wait for its outcome
+# NOTE: Queue & workflow management (pause, resume, redrive, cancel, terminate) is intentionally
+# excluded from SDKs and must be performed via the JoobQUI Operator Console (/ui/).
+
+from __future__ import annotations
+import http.client
+import json
+import os
+import queue as _queue
+import random
+import signal as _signal
+import socket
+import sys
+import threading
+import time
+import traceback
+import urllib.parse
+import urllib.request
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Type, Union
+
+SDK_VERSION = "0.1.0"
+
+
+
+class NonRetryableError(Exception):
+    """Raised by a Job or Workflow Activity when a failure is permanent and must not be retried."""
+
+
+@dataclass
+class RetryPolicy:
+    attempts: int = 3
+    initial_ms: int = 1000
+    backoff: float = 2.0
+    maximum_ms: int = 30000
+    # Error types (the exception's class name, as the worker reports it) that end the step without another attempt.
+    non_retryable: List[str] = field(default_factory=list)
+
+
+def retry_policy(
+    attempts: int = 3,
+    initial_ms: int = 1000,
+    backoff: float = 2.0,
+    maximum_ms: int = 30000,
+    non_retryable: Optional[List[str]] = None,
+) -> RetryPolicy:
+    return RetryPolicy(attempts=attempts, initial_ms=initial_ms, backoff=backoff, maximum_ms=maximum_ms,
+                       non_retryable=list(non_retryable or []))
+
+
+@dataclass
+class DataRef:
+    expr: str
+
+    def to_expr(self) -> str:
+        return self.expr
+
+
+def input(key: Optional[str] = None) -> DataRef:
+    return DataRef("${input}" if not key else f"${{input.{key}}}")
+
+
+def output(step_name: str, key: Optional[str] = None) -> DataRef:
+    return DataRef(
+        f"${{steps.{step_name}.output}}"
+        if not key
+        else f"${{steps.{step_name}.output.{key}}}"
+    )
+
+
+def update_input(key: Optional[str] = None) -> DataRef:
+    """The input of the update being handled (`${update.input...}`): for an update's `validate`, `input` and `result`."""
+    return DataRef("${update.input}" if not key else f"${{update.input.{key}}}")
+
+
+def ref(path: str) -> DataRef:
+    clean = path.strip()
+    if clean.startswith("${") and clean.endswith("}"):
+        return DataRef(clean)
+    return DataRef(f"${{{clean}}}")
+
+
+def _lookup_path(root: Any, dotted: str) -> Any:
+    cur = root
+    for part in dotted.split("."):
+        if not part:
+            continue
+        if isinstance(cur, dict):
+            cur = cur.get(part)
+        else:
+            cur = getattr(cur, part, None)
+        if cur is None:
+            return None
+    return cur
+
+
+def resolve_references(spec: Any, workflow_input: Any, checkpoints: Dict[str, Any]) -> Any:
+    if spec is None:
+        return workflow_input
+    if isinstance(spec, DataRef):
+        expr = spec.expr
+        if expr == "${input}":
+            return workflow_input
+        if expr.startswith("${input.") and expr.endswith("}"):
+            return _lookup_path(workflow_input, expr[8:-1])
+        if expr.startswith("${steps.") and expr.endswith("}"):
+            rest = expr[8:-1]
+            parts = rest.split(".")
+            step_name = parts[0]
+            step_out = checkpoints.get(step_name)
+            if len(parts) <= 2:
+                return step_out
+            return _lookup_path(step_out, ".".join(parts[2:]))
+        if expr == "${steps}":
+            return dict(checkpoints)
+        if expr.startswith("${") and expr.endswith("}"):
+            return _lookup_path({"input": workflow_input, "steps": checkpoints}, expr[2:-1])
+        return expr
+    if isinstance(spec, dict):
+        return {k: resolve_references(v, workflow_input, checkpoints) for k, v in spec.items()}
+    if isinstance(spec, list):
+        return [resolve_references(v, workflow_input, checkpoints) for v in spec]
+    return spec
+
+
+def _extract_step_dependencies(spec: Any) -> List[str]:
+    deps: List[str] = []
+    if isinstance(spec, DataRef):
+        if spec.expr.startswith("${steps."):
+            step_name = spec.expr[8:-1].split(".")[0]
+            if step_name and step_name not in deps:
+                deps.append(step_name)
+    elif isinstance(spec, dict):
+        for v in spec.values():
+            for d in _extract_step_dependencies(v):
+                if d not in deps:
+                    deps.append(d)
+    elif isinstance(spec, list):
+        for v in spec:
+            for d in _extract_step_dependencies(v):
+                if d not in deps:
+                    deps.append(d)
+    return deps
+
+
+def _collect_references(spec: Any) -> List[str]:
+    """The `${...}` references a step input makes (what a blueprint sends: never the literal values around them)."""
+    found: List[str] = []
+    if isinstance(spec, DataRef):
+        found.append(spec.expr)
+    elif isinstance(spec, dict):
+        for v in spec.values():
+            found.extend(r for r in _collect_references(v) if r not in found)
+    elif isinstance(spec, (list, tuple)):
+        for v in spec:
+            found.extend(r for r in _collect_references(v) if r not in found)
+    return found
+
+
+def _template(spec: Any, where: str) -> Any:
+    """A child's or continued run's input as the engine resolves it: references (`input()`, `output()`, `ref()`) in
+    dicts and lists. Literal values are refused: compute a constant in a step and refer to its output."""
+    if isinstance(spec, DataRef):
+        return spec.expr
+    if isinstance(spec, dict):
+        return {k: _template(v, f"{where}.{k}") for k, v in spec.items()}
+    if isinstance(spec, (list, tuple)):
+        return [_template(v, f"{where}[{i}]") for i, v in enumerate(spec)]
+    raise ValueError(f"{where}: {spec!r} is not a reference; the engine resolves this input, so only references are sent")
+
+
+def _callable_name(target: Any) -> Optional[str]:
+    if isinstance(target, type):
+        return getattr(target, "job_name", None) or target.__name__
+    name = getattr(target, "__name__", None) or getattr(type(target), "__name__", None)
+    return None if not name or name == "<lambda>" or name == "function" else name
+
+
+@dataclass
+class Gate:
+    """Puts a step on one side of a change (versioning): the step runs only for runs whose version of `change` is within
+    `min..max` (open ended when None), and is skipped otherwise. A new run takes the change's `max`."""
+    change: str
+    min: Optional[int] = None
+    max: Optional[int] = None
+
+
+def gate(change: str, *, min: Optional[int] = None, max: Optional[int] = None) -> Gate:
+    if min is None and max is None:
+        raise ValueError(f"gate on {change!r} needs a min or a max")
+    return Gate(change, min, max)
+
+
+@dataclass
+class UpdateDef:
+    name: str
+    handler: Optional[Callable[[Any, "ExecutionContext"], Any]] = None
+    validate: Optional[DataRef] = None
+    message: Optional[str] = None
+    input: Any = None
+    result: Any = None
+    timeout_ms: Optional[int] = None
+
+
+@dataclass
+class Compensation:
+    handler: Callable[[Any, "ExecutionContext"], Any]
+    input: Any = None
+    activity_name: Optional[str] = None
+
+
+def compensation(
+    handler: Union[Callable[[Any, "ExecutionContext"], Any], Type[Any], Any],
+    *,
+    input: Any = None,
+) -> Compensation:
+    fn = _normalize_callable(handler)
+    return Compensation(handler=fn, input=input, activity_name=_callable_name(handler))
+
+
+def _normalize_callable(target: Any) -> Callable[[Any, "ExecutionContext"], Any]:
+    if isinstance(target, type) and hasattr(target, "perform"):
+        def _invoke_cls(payload: Any, ctx: "ExecutionContext") -> Any:
+            inst = target()
+            return inst.perform(payload, ctx)
+        return _invoke_cls
+    if hasattr(target, "perform") and callable(getattr(target, "perform")):
+        return getattr(target, "perform")
+    if callable(target):
+        return target
+    raise TypeError(f"Expected callable or Activity/Job with perform(payload, ctx), got {target!r}")
+
+
+class Job:
+    """Declarative Job base class mirroring Crystal's `JoobQ::Job`."""
+
+    job_name: Optional[str] = None
+    queue: str = "default"
+    retries: int = 3
+    expires_ms: Optional[int] = None
+    encrypted_fields: List[str] = []
+    unique_ttl_ms: Optional[int] = None
+
+    @classmethod
+    def resolved_name(cls) -> str:
+        return cls.job_name or cls.__name__
+
+    @staticmethod
+    def perform(payload: Any, ctx: "ExecutionContext") -> Any:
+        raise NotImplementedError("Subclasses of Job must implement perform(payload, ctx)")
+
+    @classmethod
+    def enqueue(cls, client: "JoobQClient", payload: Any = None, **kwargs: Any) -> Dict[str, Any]:
+        return client.enqueue(cls, payload, **kwargs)
+
+
+def job(
+    name: Optional[str] = None,
+    *,
+    queue: str = "default",
+    retries: int = 3,
+    expires_ms: Optional[int] = None,
+    encrypted_fields: Optional[List[str]] = None,
+    unique_ttl_ms: Optional[int] = None,
+) -> Callable[[Callable[[Any, "ExecutionContext"], Any]], Type[Job]]:
+    """Decorator for defining a `Job` from a function with `JoobQ::Job` metadata."""
+
+    def _decorator(fn: Callable[[Any, "ExecutionContext"], Any]) -> Type[Job]:
+        job_type_name = name or fn.__name__
+        attrs = {
+            "job_name": job_type_name,
+            "queue": queue,
+            "retries": retries,
+            "expires_ms": expires_ms,
+            "encrypted_fields": list(encrypted_fields or []),
+            "unique_ttl_ms": unique_ttl_ms,
+            "perform": staticmethod(fn),
+        }
+        return type(job_type_name, (Job,), attrs)
+
+    return _decorator
+
+
+@dataclass
+class WorkflowStepDef:
+    kind: str  # "step" | "wait_for" | "timer" | "child" | "parallel" | "sequence"
+    name: str
+    handler: Optional[Callable[[Any, "ExecutionContext"], Any]] = None
+    input_spec: Any = None
+    retry: Optional[RetryPolicy] = None
+    compensate: Optional[Compensation] = None
+    signal_name: Optional[str] = None
+    timeout_ms: Optional[int] = None
+    duration_ms: Optional[int] = None
+    children: List["WorkflowStepDef"] = field(default_factory=list)
+    activity_name: Optional[str] = None
+    after: List[str] = field(default_factory=list)
+    heartbeat_ms: Optional[int] = None
+    schedule_to_start_ms: Optional[int] = None
+    only_if: Optional[DataRef] = None
+    workflow_name: Optional[str] = None
+    gate: Optional[Gate] = None
+    non_cancellable: bool = False
+
+
+class WorkflowBlueprint:
+    """Declarative workflow builder (the engine conducts the run and its compensations), mirroring `JoobQPro::Workflows::DSL`."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        version: int = 1,
+        timeout_ms: Optional[int] = None,
+        task_queue: str = "workflows",
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.timeout_ms = timeout_ms
+        self.task_queue = task_queue
+        self.steps: List[WorkflowStepDef] = []
+        self.queries: Dict[str, DataRef] = {}
+        self._declared_steps: set[str] = set()
+        self.continuation: Optional[Dict[str, Any]] = None
+        self.changes: Dict[str, Dict[str, int]] = {}
+        self.updates: Dict[str, UpdateDef] = {}
+        self._in_scope = False
+
+    def _validate_and_register(self, step_name: str, input_spec: Any, after: Optional[List[str]] = None) -> None:
+        if step_name in self._declared_steps:
+            raise ValueError(f"Duplicate workflow step name '{step_name}' in workflow '{self.name}'")
+        for dep in after or []:
+            if dep not in self._declared_steps:
+                raise ValueError(f"Step '{step_name}' in workflow '{self.name}' waits (after=) for unknown or downstream step '{dep}'")
+        for dep in _extract_step_dependencies(input_spec):
+            if dep not in self._declared_steps:
+                raise ValueError(
+                    f"Step '{step_name}' in workflow '{self.name}' references output of unknown or downstream step '{dep}'"
+                )
+        self._declared_steps.add(step_name)
+
+    def query(self, name: str, expr: DataRef) -> "WorkflowBlueprint":
+        self.queries[name] = expr
+        return self
+
+    def step(
+        self,
+        name: str,
+        activity: Union[Callable[[Any, "ExecutionContext"], Any], Type[Any], Any],
+        *,
+        input: Any = None,
+        retry: Optional[RetryPolicy] = None,
+        compensate: Optional[Compensation] = None,
+        after: Optional[List[str]] = None,
+        timeout_ms: Optional[int] = None,
+        heartbeat_ms: Optional[int] = None,
+        schedule_to_start_ms: Optional[int] = None,
+        only_if: Optional[DataRef] = None,
+        gate: Optional[Gate] = None,
+    ) -> "WorkflowBlueprint":
+        """A step. `after` names earlier steps it also waits for (on top of what precedes it, e.g. a sibling in a
+        `parallel` group); `timeout_ms` limits one attempt, `heartbeat_ms` how long the handler may go without calling
+        `ctx.heartbeat()`, `schedule_to_start_ms` how long the step may wait for a worker; `only_if` (a reference) runs
+        the step only when it is truthy, else the step is skipped; `gate` (see `gate()`) runs it only on one side of a
+        change. The engine enforces them."""
+        self._check_condition(name, only_if)  # before the name is declared: a step cannot gate on itself
+        self._validate_and_register(name, input, after)
+        self.steps.append(
+            WorkflowStepDef(
+                kind="step",
+                name=name,
+                handler=_normalize_callable(activity),
+                activity_name=_callable_name(activity),
+                input_spec=input,
+                retry=retry,
+                compensate=compensate,
+                after=list(after or []),
+                timeout_ms=timeout_ms,
+                heartbeat_ms=heartbeat_ms,
+                schedule_to_start_ms=schedule_to_start_ms,
+                only_if=only_if,
+                gate=gate,
+            )
+        )
+        return self
+
+    def _check_condition(self, name: str, only_if: Optional[DataRef]) -> None:
+        if only_if is None:
+            return
+        if not isinstance(only_if, DataRef):
+            raise ValueError(f"Step '{name}' in workflow '{self.name}': only_if must be a reference (input(), output(), ref())")
+        for dep in _extract_step_dependencies(only_if):
+            if dep not in self._declared_steps:
+                raise ValueError(f"Step '{name}' in workflow '{self.name}': only_if refers to unknown or downstream step '{dep}'")
+
+    def wait_for(self, name: str, *, signal: str, timeout_ms: int = 600_000,
+                 after: Optional[List[str]] = None, only_if: Optional[DataRef] = None,
+                 compensate: Optional[Compensation] = None, gate: Optional[Gate] = None) -> "WorkflowBlueprint":
+        """Waits for a signal. `compensate` undoes it (its input defaults to the signal's payload) when the run fails."""
+        self._check_condition(name, only_if)
+        self._validate_and_register(name, None, after)
+        self.steps.append(
+            WorkflowStepDef(kind="wait_for", name=name, signal_name=signal, timeout_ms=timeout_ms, after=list(after or []),
+                            only_if=only_if, compensate=compensate, gate=gate)
+        )
+        return self
+
+    def timer(self, name: str, *, for_ms: int, after: Optional[List[str]] = None, only_if: Optional[DataRef] = None,
+              compensate: Optional[Compensation] = None, gate: Optional[Gate] = None) -> "WorkflowBlueprint":
+        """Waits for a time. `compensate` undoes it (its input defaults to the timer's output) when the run fails."""
+        self._check_condition(name, only_if)
+        self._validate_and_register(name, None, after)
+        self.steps.append(WorkflowStepDef(kind="timer", name=name, duration_ms=for_ms, after=list(after or []),
+                                          only_if=only_if, compensate=compensate, gate=gate))
+        return self
+
+    def child(self, name: str, workflow_def: Union["WorkflowBlueprint", str], *, input: Any = None,
+              compensate: Optional[Compensation] = None, after: Optional[List[str]] = None,
+              only_if: Optional[DataRef] = None, gate: Optional[Gate] = None) -> "WorkflowBlueprint":
+        """Runs another workflow (a blueprint or its name) as a step; its output is the child run's output, its failure
+        the step's. The engine starts the child and resolves `input` (references only: `input()`, `output()`, `ref()`,
+        in dicts and lists; the run's input when omitted). A child is not retried: give the child's own steps retries,
+        and the child workflow a `timeout_ms`. The child workflow must be registered before a run reaches this step."""
+        if input is not None:
+            _template(input, f"{name}.input")
+        self._check_condition(name, only_if)
+        self._validate_and_register(name, input, after)
+        child_name = workflow_def.name if isinstance(workflow_def, WorkflowBlueprint) else str(workflow_def)
+        self.steps.append(WorkflowStepDef(kind="child", name=name, workflow_name=child_name, input_spec=input,
+                                          compensate=compensate, after=list(after or []), only_if=only_if, gate=gate))
+        return self
+
+    def continue_as_new(self, *, input: Any = None, only_if: Optional[DataRef] = None, max_runs: Optional[int] = None,
+                        max_events: Optional[int] = None) -> "WorkflowBlueprint":
+        """When the run ends (and `only_if` is truthy), it closes `continued_as_new` and a fresh run of this workflow starts
+        with `input` (references only, resolved by the engine; the same input when omitted), at most `max_runs` runs."""
+        policy: Dict[str, Any] = {}
+        if input is not None:
+            policy["input"] = _template(input, "continue_as_new.input")
+        if only_if is not None:
+            if not isinstance(only_if, DataRef):
+                raise ValueError("continue_as_new: only_if must be a reference (input(), output(), ref())")
+            policy["only_if"] = only_if.expr
+        if max_runs is not None:
+            policy["max_runs"] = max_runs
+        if max_events is not None:
+            policy["max_events"] = max_events
+        self.continuation = policy
+        return self
+
+    def change(self, change_id: str, *, min: int = 0, max: int = 1) -> "WorkflowBlueprint":
+        """Declares a change (versioning, like Temporal's getVersion): runs that reach a gated step fresh take `max`,
+        runs that went past it on the old path keep 0; steps pick a side with `gate=gate(change_id, min=..., max=...)`.
+        Raise `min` only once no open run is on an older path."""
+        if min > max:
+            raise ValueError(f"change {change_id!r} in workflow {self.name!r}: min is above max")
+        self.changes[change_id] = {"min": min, "max": max}
+        return self
+
+    def update(self, name: str, handler: Optional[Union[Callable[[Any, "ExecutionContext"], Any], Type[Any], Any]] = None, *,
+               validate: Optional[DataRef] = None, message: Optional[str] = None, input: Any = None, result: Any = None,
+               timeout_ms: Optional[int] = None) -> "WorkflowBlueprint":
+        """An update handler (`JoobQClient.update_workflow`): `validate` (a reference, e.g. `update_input("name")`) must be
+        truthy or the update is rejected with `message`; then `handler` runs as a step of the run (its payload is `input`,
+        by default the update's input, and its return value is the result), or, without one, `result` (a template of
+        references) is the result. References may read the run (`input()`, `output()`) and `update_input()`."""
+        if name in self.updates:
+            raise ValueError(f"Duplicate update {name!r} in workflow {self.name!r}")
+        if validate is not None and not isinstance(validate, DataRef):
+            raise ValueError(f"update {name!r}: validate must be a reference (update_input(), input(), output(), ref())")
+        if input is not None:
+            _template(input, f"update {name}.input")
+        if result is not None:
+            _template(result, f"update {name}.result")
+        fn = _normalize_callable(handler) if handler is not None else None
+        self.updates[name] = UpdateDef(name, fn, validate, message, input, result, timeout_ms)
+        return self
+
+    def scope(self, name: str, build_fn: Callable[["WorkflowBlueprint"], Any], *, timeout_ms: Optional[int] = None,
+              non_cancellable: bool = False) -> "WorkflowBlueprint":
+        """A cancellation scope: its steps run in sequence and can be cancelled as a unit (from the console or API,
+        or after `timeout_ms` from its first step's start) while the rest of the run goes on; a cancelled step counts as
+        finished with a null output. A `non_cancellable` scope holds cleanup that still runs when the workflow is cancelled,
+        times out or fails (it cannot have a timeout). A running step sees a cancel through `ctx.heartbeat()`.
+        Scopes do not nest."""
+        if self._in_scope:
+            raise ValueError(f"scope {name!r} in workflow {self.name!r} is inside another scope: scopes do not nest")
+        if non_cancellable and timeout_ms is not None:
+            raise ValueError(f"scope {name!r} is non_cancellable and cannot time out")
+        inner = WorkflowBlueprint(f"{self.name}:scope", version=self.version, timeout_ms=self.timeout_ms, task_queue=self.task_queue)
+        inner._declared_steps = set(self._declared_steps)
+        inner._in_scope = True
+        build_fn(inner)
+        if not inner.steps:
+            raise ValueError(f"scope {name!r} in workflow {self.name!r} has no steps")
+        self._declared_steps.update(inner._declared_steps)
+        self.steps.append(WorkflowStepDef(kind="scope", name=name, children=inner.steps, timeout_ms=timeout_ms,
+                                          non_cancellable=non_cancellable))
+        return self
+
+    def parallel(self, build_fn: Callable[["WorkflowBlueprint"], Any]) -> "WorkflowBlueprint":
+        branch = WorkflowBlueprint(f"{self.name}:parallel", version=self.version, timeout_ms=self.timeout_ms, task_queue=self.task_queue)
+        branch._declared_steps = set(self._declared_steps)
+        branch._in_scope = self._in_scope
+        build_fn(branch)
+        self._declared_steps.update(branch._declared_steps)
+        self.steps.append(WorkflowStepDef(kind="parallel", name=f"parallel_{len(self.steps) + 1}", children=branch.steps))
+        return self
+
+    def sequence(self, build_fn: Callable[["WorkflowBlueprint"], Any]) -> "WorkflowBlueprint":
+        seq = WorkflowBlueprint(f"{self.name}:sequence", version=self.version, timeout_ms=self.timeout_ms, task_queue=self.task_queue)
+        seq._declared_steps = set(self._declared_steps)
+        seq._in_scope = self._in_scope
+        build_fn(seq)
+        self._declared_steps.update(seq._declared_steps)
+        self.steps.append(WorkflowStepDef(kind="sequence", name=f"sequence_{len(self.steps) + 1}", children=seq.steps))
+        return self
+
+    def to_blueprint(self) -> Dict[str, Any]:
+        """The workflow's structure as data, as the worker registers it with the gateway (`CONTRACT.md`)."""
+
+        def node(s: WorkflowStepDef) -> Dict[str, Any]:
+            out: Dict[str, Any] = {"name": s.name, "kind": s.kind}
+            if s.kind in ("parallel", "sequence", "scope"):
+                out["children"] = [node(c) for c in s.children]
+                if s.kind == "scope":
+                    if s.timeout_ms is not None:
+                        out["timeout_ms"] = s.timeout_ms
+                    if s.non_cancellable:
+                        out["non_cancellable"] = True
+            elif s.kind == "wait_for":
+                out.update({"signal": s.signal_name, "timeout_ms": s.timeout_ms})
+            elif s.kind == "timer":
+                out["for_ms"] = s.duration_ms
+            elif s.kind == "child":
+                out["workflow"] = s.workflow_name
+                if s.input_spec is not None:
+                    out["input"] = _template(s.input_spec, f"{s.name}.input")
+            else:
+                out["activity"] = s.activity_name
+                out["references"] = _collect_references(s.input_spec) if s.input_spec is not None else ["${input}"]
+                for key, value in (("timeout_ms", s.timeout_ms), ("heartbeat_ms", s.heartbeat_ms),
+                                   ("schedule_to_start_ms", s.schedule_to_start_ms)):
+                    if value is not None:
+                        out[key] = value
+                if s.retry is not None:
+                    out["retry"] = {"attempts": s.retry.attempts, "initial_ms": s.retry.initial_ms,
+                                    "backoff": s.retry.backoff, "maximum_ms": s.retry.maximum_ms}
+                    if s.retry.non_retryable:
+                        out["retry"]["non_retryable"] = list(s.retry.non_retryable)
+            if s.kind in ("step", "wait_for", "timer", "child"):
+                if s.compensate is not None:
+                    comp_in = s.compensate.input if s.compensate.input is not None else output(s.name)
+                    out["compensate"] = {"activity": s.compensate.activity_name, "references": _collect_references(comp_in)}
+                if s.only_if is not None:
+                    out["only_if"] = s.only_if.expr
+                if s.gate is not None:
+                    out["gate"] = {"change": s.gate.change, **({"min": s.gate.min} if s.gate.min is not None else {}),
+                                   **({"max": s.gate.max} if s.gate.max is not None else {})}
+            if s.after:
+                out["after"] = list(s.after)
+            return out
+
+        blueprint: Dict[str, Any] = {
+            "name": self.name,
+            "version": self.version,
+            "task_queue": self.task_queue,
+            "queries": {k: v.to_expr() for k, v in self.queries.items()},
+            "nodes": [node(s) for s in self.steps],
+        }
+        if self.timeout_ms is not None:
+            blueprint["timeout_ms"] = self.timeout_ms  # the whole run's deadline, enforced by the engine
+        if self.continuation is not None:
+            blueprint["continue_as_new"] = dict(self.continuation)
+        if self.changes:
+            blueprint["changes"] = [{"id": cid, **bounds} for cid, bounds in self.changes.items()]
+        if self.updates:
+            blueprint["updates"] = {u.name: _update_spec(u) for u in self.updates.values()}
+        return blueprint
+
+    def activities(self) -> Dict[str, Callable[[Any, "ExecutionContext"], Any]]:
+        """The handlers of this workflow's steps, by the activity name the engine sends them under (`<workflow>/<step>`,
+        compensations `<workflow>/<step>/compensate`, update handlers `<workflow>/@update/<name>`). Each runs its step
+        once: the engine conducts the run (it retries, compensates and waits). A step's input is resolved against the
+        run's input (the task's payload) and the outputs of the steps that completed (the task's checkpoints)."""
+        found: Dict[str, Callable[[Any, "ExecutionContext"], Any]] = {}
+
+        def step_activity(node: WorkflowStepDef) -> Callable[[Any, "ExecutionContext"], Any]:
+            def run(workflow_input: Any, ctx: "ExecutionContext") -> Any:
+                assert node.handler is not None
+                return node.handler(resolve_references(node.input_spec, workflow_input, ctx.task.checkpoints), ctx)
+            return run
+
+        def compensation_activity(node: WorkflowStepDef, comp: Compensation) -> Callable[[Any, "ExecutionContext"], Any]:
+            def run(workflow_input: Any, ctx: "ExecutionContext") -> Any:
+                spec = comp.input if comp.input is not None else output(node.name)
+                return comp.handler(resolve_references(spec, workflow_input, ctx.task.checkpoints), ctx)
+            return run
+
+        def update_activity(update: UpdateDef) -> Callable[[Any, "ExecutionContext"], Any]:
+            def run(update_payload: Any, ctx: "ExecutionContext") -> Any:
+                assert update.handler is not None
+                return update.handler(update_payload, ctx)  # the engine resolved the handler's input already
+            return run
+
+        def visit(nodes: List[WorkflowStepDef]) -> None:
+            for node in nodes:
+                if node.kind in ("sequence", "parallel", "scope"):
+                    visit(node.children)
+                else:
+                    if node.kind == "step":
+                        found[_activity_name(self.name, node.name)] = step_activity(node)
+                    if node.compensate is not None:  # a step, wait, timer or child can be undone
+                        found[_activity_name(self.name, node.name, True)] = compensation_activity(node, node.compensate)
+
+        visit(self.steps)
+        for update in self.updates.values():
+            if update.handler is not None:
+                found[_update_activity(self.name, update.name)] = update_activity(update)
+        return found
+
+
+def _update_spec(update: UpdateDef) -> Dict[str, Any]:
+    spec: Dict[str, Any] = {}
+    if update.handler is not None:
+        spec["handler"] = True
+    if update.validate is not None:
+        spec["validate"] = update.validate.expr
+    if update.message:
+        spec["message"] = update.message
+    if update.input is not None:
+        spec["input"] = _template(update.input, f"update {update.name}.input")
+    if update.result is not None:
+        spec["result"] = _template(update.result, f"update {update.name}.result")
+    if update.timeout_ms is not None:
+        spec["timeout_ms"] = update.timeout_ms
+    return spec
+
+
+def _update_activity(workflow_name: str, update: str) -> str:
+    """The activity the engine sends an update handler of an SDK workflow under."""
+    return f"{workflow_name}/@update/{update}"
+
+
+def _activity_name(workflow_name: str, step: str, compensate: bool = False) -> str:
+    """The activity the engine sends a step (or its compensation) of an SDK workflow under."""
+    return f"{workflow_name}/{step}/compensate" if compensate else f"{workflow_name}/{step}"
+
+
+def workflow(
+    name: str,
+    *,
+    version: int = 1,
+    timeout_ms: Optional[int] = None,
+    task_queue: str = "workflows",
+) -> WorkflowBlueprint:
+    """A workflow blueprint. `timeout_ms` is the whole run's deadline (none by default), enforced by the engine."""
+    return WorkflowBlueprint(name, version=version, timeout_ms=timeout_ms, task_queue=task_queue)
+
+
+@dataclass
+class LeasedTask:
+    lease_token: str
+    kind: str
+    id: str
+    queue: str
+    name: str
+    attempt: int
+    max_retries: int
+    payload: Any
+    context: Dict[str, Any] = field(default_factory=dict)
+    workflow_id: Optional[str] = None
+    step_id: Optional[str] = None
+    checkpoints: Dict[str, Any] = field(default_factory=dict)  # a step's: the outputs of the run's completed steps
+    lease_until_ms: int = 0
+    heartbeat_ms: Optional[int] = None  # an engine step's heartbeat timeout: call ctx.heartbeat() more often than this
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "LeasedTask":
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in raw.items() if k in known})
+
+
+class ExecutionContext:
+    """Carries the propagated request `context`, heartbeating, and downstream context-forwarding helpers. Handlers
+    reach the application's own dependencies directly: the worker runs inside the booted application."""
+
+    def __init__(self, task: LeasedTask, worker_id: str, client: "JoobQClient", lease_ttl_ms: int = 30000,
+                 transport: Optional["_Transport"] = None) -> None:
+        self.task = task
+        self.worker_id = worker_id
+        self.client = client
+        self.lease_ttl_ms = lease_ttl_ms
+        self._transport = transport
+        self.context: Dict[str, Any] = dict(task.context or {})
+        self._last_beat_ms = float("-inf")
+        self._beat_cancel = False
+
+    @property
+    def attempt(self) -> int:
+        return self.task.attempt
+
+    @property
+    def dedupe_key(self) -> str:
+        wf = self.task.workflow_id or self.task.id
+        step = self.task.step_id or self.task.name
+        return f"{wf}:{step}:{self.task.attempt}"
+
+    def heartbeat(self, lease_ttl_ms: Optional[int] = None) -> bool:
+        """True when the run was cancelled. Inside a running worker this answers what the worker's last lease renewal
+        said, without waiting for the gateway (the worker renews every lease on its own). For a step with
+        `heartbeat_ms` it also tells the engine the step is alive (at most every third of `heartbeat_ms`): the worker's
+        own renewals do not, so a handler that stops calling this is timed out."""
+        if self.task.heartbeat_ms:
+            now = time.monotonic() * 1000
+            if now - self._last_beat_ms >= max(100, self.task.heartbeat_ms // 3):
+                self._last_beat_ms = now
+                try:
+                    res = self.client.heartbeat_task(self.task.lease_token, self.worker_id, lease_ttl_ms or self.lease_ttl_ms)
+                    self._beat_cancel = bool(res.get("cancel_requested", False))
+                except Exception:
+                    pass  # the next window's beat tries again; the engine's deadline decides
+            if self._beat_cancel:
+                return True
+        if self._transport is not None:
+            return self._transport.cancel_requested(self.task.lease_token)
+        res = self.client.heartbeat_task(self.task.lease_token, self.worker_id, lease_ttl_ms or self.lease_ttl_ms)
+        return bool(res.get("cancel_requested", False))
+
+    def enqueue(self, job_cls: Type[Job], payload: Any = None, **kwargs: Any) -> Dict[str, Any]:
+        merged_ctx = {**self.context, **(kwargs.pop("context", None) or {})}
+        return self.client.enqueue(job_cls, payload, context=merged_ctx, **kwargs)
+
+    def enqueue_job(self, queue: str, job_type: str, payload: Any = None, **kwargs: Any) -> Dict[str, Any]:
+        merged_ctx = {**self.context, **(kwargs.pop("context", None) or {})}
+        return self.client.enqueue_job(queue, job_type, payload, context=merged_ctx, **kwargs)
+
+    def start(self, workflow_def: WorkflowBlueprint, input_data: Any = None, **kwargs: Any) -> Dict[str, Any]:
+        merged_ctx = {**self.context, **(kwargs.pop("context", None) or {})}
+        return self.client.start(workflow_def, input_data, context=merged_ctx, **kwargs)
+
+    def start_workflow(self, name: str, input_data: Any = None, **kwargs: Any) -> Dict[str, Any]:
+        merged_ctx = {**self.context, **(kwargs.pop("context", None) or {})}
+        return self.client.start_workflow(name, input_data, context=merged_ctx, **kwargs)
+
+    def register_schedule(self, name: str, job_type: str, queue: str, **kwargs: Any) -> Dict[str, Any]:
+        return self.client.register_schedule(name, job_type, queue, **kwargs)
+
+    def rate_limit(self, key: str, limit: int, period_ms: int) -> Dict[str, Any]:
+        return self.client.rate_limit(key, limit, period_ms)
+
+    def create_batch(self, jobs: List[Any], **kwargs: Any) -> Dict[str, Any]:
+        """`JoobQClient.create_batch`; the members and callbacks carry this handler's context."""
+        merged_ctx = {**self.context, **(kwargs.pop("context", None) or {})}
+        return self.client.create_batch(jobs, context=merged_ctx, **kwargs)
+
+    def get_batch(self, batch_id: str) -> Dict[str, Any]:
+        return self.client.get_batch(batch_id)
+
+    def describe_workflow(self, workflow_id: str) -> Dict[str, Any]:
+        return self.client.describe_workflow(workflow_id)
+
+    def workflow_result(self, workflow_id: str, wait_ms: int = 0) -> Dict[str, Any]:
+        return self.client.workflow_result(workflow_id, wait_ms)
+
+    def workflow_history(self, workflow_id: str, after_seq: int = 0, limit: int = 200) -> List[Dict[str, Any]]:
+        return self.client.workflow_history(workflow_id, after_seq, limit)
+
+    def query_workflow(self, workflow_id: str, name: str) -> Any:
+        return self.client.query_workflow(workflow_id, name)
+
+    def signal_workflow(self, workflow_id: str, name: str, payload: Any = None) -> Dict[str, Any]:
+        return self.client.signal_workflow(workflow_id, name, payload)
+
+    def update_workflow(self, workflow_id: str, name: str, input: Any = None, *, update_id: Optional[str] = None,
+                        wait_ms: Optional[int] = None) -> Dict[str, Any]:
+        return self.client.update_workflow(workflow_id, name, input, update_id=update_id, wait_ms=wait_ms)
+
+    def upsert_workflow_attributes(self, workflow_id: str, set: Optional[Dict[str, Any]] = None,
+                                   remove: Optional[List[str]] = None) -> Dict[str, Any]:
+        return self.client.upsert_workflow_attributes(workflow_id, set, remove)
+
+
+def _seg(value: str) -> str:
+    """A workflow id as one URL path segment."""
+    return urllib.parse.quote(str(value), safe="")
+
+
+def failure(exc: BaseException, retryable: bool = True) -> Dict[str, Any]:
+    """The fields that report `exc` to the gateway (`fail`, and a `fail` item of `ack_tasks`)."""
+    frames = [
+        {"file": f.filename, "line": f.lineno or 0, "function": f.name}
+        for f in traceback.extract_tb(exc.__traceback__)
+    ]
+    return {
+        "error_class": exc.__class__.__name__,
+        "error_message": (str(exc) or exc.__class__.__name__)[:4000],
+        "retryable": retryable,
+        "sdk_language": "python",
+        "stack_frames": frames,
+        "raw_stacktrace": "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))[-4000:],
+    }
+
+
+class GatewayError(Exception):
+    """The gateway answered with an error status (`status`, the JSON error envelope as `body`)."""
+
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"gateway answered {status}: {body[:300]}")
+        self.status = status
+        self.body = body
+
+
+class JoobQClient:
+    def __init__(
+        self,
+        gateway_url: str,
+        token: str,
+        context_provider: Optional[Callable[[], Dict[str, Any]]] = None,
+    ) -> None:
+        self.gateway_url = gateway_url.rstrip("/")
+        self.token = token
+        self.context_provider = context_provider
+        self._url = urllib.parse.urlsplit(self.gateway_url)
+        self._local = threading.local()  # one kept-alive connection per thread
+        # Seconds one gateway call may take. A worker lowers it (`JoobQWorker`): a call that hangs for longer than a
+        # lease would let every lease the worker holds expire while its tasks still run.
+        self.request_timeout: float = 60.0
+        self._async: Optional[ThreadPoolExecutor] = None
+        self._async_lock = threading.Lock()
+
+    def _resolve_context(self, explicit: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        ambient = self.context_provider() if self.context_provider else {}
+        return {**(ambient or {}), **(explicit or {})}
+
+    def enqueue(
+        self,
+        job_cls: Type[Job],
+        payload: Any = None,
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        jid: Optional[str] = None,
+        delay_ms: int = 0,
+        run_at_ms: Optional[int] = None,
+        expires_ms: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        unique_key: Optional[str] = None,
+        unique_mode: str = "while_locked",
+    ) -> Dict[str, Any]:
+        return self.enqueue_job(
+            queue=job_cls.queue,
+            job_type=job_cls.resolved_name(),
+            payload=payload,
+            context=context,
+            jid=jid,
+            max_retries=job_cls.retries,
+            delay_ms=delay_ms,
+            run_at_ms=run_at_ms,
+            expires_ms=expires_ms if expires_ms is not None else job_cls.expires_ms,
+            timeout_ms=timeout_ms,
+            encrypt_fields=list(job_cls.encrypted_fields or []),
+            unique_key=unique_key,
+            unique_ttl_ms=job_cls.unique_ttl_ms,
+            unique_mode=unique_mode,
+        )
+
+    def enqueue_job(
+        self,
+        queue: str,
+        job_type: str,
+        payload: Any = None,
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        jid: Optional[str] = None,
+        max_retries: int = 3,
+        delay_ms: int = 0,
+        run_at_ms: Optional[int] = None,
+        expires_ms: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+        encrypt_fields: Optional[List[str]] = None,
+        unique_key: Optional[str] = None,
+        unique_ttl_ms: Optional[int] = None,
+        unique_mode: str = "while_locked",
+    ) -> Dict[str, Any]:
+        return self._post("/api/v1/sdk/jobs", self._job_body(queue, job_type, payload, context=context, jid=jid,
+                                                             max_retries=max_retries, delay_ms=delay_ms,
+                                                             run_at_ms=run_at_ms, expires_ms=expires_ms,
+                                                             timeout_ms=timeout_ms,
+                                                             encrypt_fields=encrypt_fields, unique_key=unique_key,
+                                                             unique_ttl_ms=unique_ttl_ms, unique_mode=unique_mode))
+
+    def _job_body(self, queue: str, job_type: str, payload: Any = None, *, context: Optional[Dict[str, Any]] = None,
+                  jid: Optional[str] = None, max_retries: int = 3, delay_ms: int = 0,
+                  run_at_ms: Optional[int] = None, expires_ms: Optional[int] = None, timeout_ms: Optional[int] = None,
+                  encrypt_fields: Optional[List[str]] = None, unique_key: Optional[str] = None,
+                  unique_ttl_ms: Optional[int] = None, unique_mode: str = "while_locked") -> Dict[str, Any]:
+        return {
+            "queue": queue,
+            "job_type": job_type,
+            "payload": payload if payload is not None else {},
+            "context": self._resolve_context(context),
+            "jid": jid,
+            "max_retries": max_retries,
+            "delay_ms": delay_ms,
+            "run_at_ms": run_at_ms,
+            "expires_ms": expires_ms,
+            "timeout_ms": timeout_ms,
+            "encrypt_fields": encrypt_fields or [],
+            "unique_key": unique_key,
+            "unique_ttl_ms": unique_ttl_ms,
+            "unique_mode": unique_mode,
+        }
+
+    def enqueue_many(self, jobs: List[Any], *, context: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """Enqueues many jobs with `POST /sdk/jobs/batch` (500 per call). Each item is `(JobClass, payload)`,
+        `(JobClass, payload, {"delay_ms": ..., "jid": ..., "unique_key": ...})` or a dict of `enqueue_job` arguments
+        (`queue`, `job_type`, `payload`, ...). Answers one `{jid, queue, status}` per job, in order."""
+        bodies = [self._item_body(item, context) for item in jobs]
+        out: List[Dict[str, Any]] = []
+        for start in range(0, len(bodies), 500):
+            out.extend(self._post("/api/v1/sdk/jobs/batch", {"jobs": bodies[start:start + 500]}).get("jobs", []))
+        return out
+
+    def _item_body(self, item: Any, context: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """One job of `enqueue_many` or `create_batch`: a dict of `enqueue_job` arguments or `(JobClass, payload[, opts])`."""
+        if isinstance(item, dict):
+            spec = dict(item)
+            spec.setdefault("context", context)
+            return self._job_body(spec.pop("queue"), spec.pop("job_type"), spec.pop("payload", None), **spec)
+        job_cls, payload, opts = (tuple(item) + ({},))[:3]
+        return self._job_body(job_cls.queue, job_cls.resolved_name(), payload,
+                              context=opts.get("context", context), jid=opts.get("jid"),
+                              max_retries=job_cls.retries, delay_ms=opts.get("delay_ms", 0),
+                              run_at_ms=opts.get("run_at_ms"),
+                              expires_ms=opts.get("expires_ms", job_cls.expires_ms),
+                              timeout_ms=opts.get("timeout_ms"),
+                              encrypt_fields=list(job_cls.encrypted_fields or []),
+                              unique_key=opts.get("unique_key"), unique_ttl_ms=job_cls.unique_ttl_ms,
+                              unique_mode=opts.get("unique_mode", "while_locked"))
+
+    def create_batch(self, jobs: List[Any], *, on_complete: Any = None, on_success: Any = None, on_failure: Any = None,
+                     description: Optional[str] = None, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Creates a Pro batch with `POST /sdk/batches`: 1 to 1000 member jobs (the shapes `enqueue_many` takes, without a
+        `unique_key`) and callback jobs (the same shapes). `on_failure` is enqueued at the first dead member,
+        `on_complete` once every member completed or was dead-lettered, `on_success` then too when none was dead; each
+        once, with `{"batch": {id, kind, total, succeeded, failed}}` merged into its payload. Answers
+        `{batch_id, total, jobs: [{jid, queue, status}]}`. 402 pro_required without a Pro licence."""
+        body: Dict[str, Any] = {"description": description, "jobs": [self._batch_item_body(item, context) for item in jobs]}
+        for kind, callback in (("on_complete", on_complete), ("on_success", on_success), ("on_failure", on_failure)):
+            if callback is not None:
+                body[kind] = self._batch_item_body(callback, context)
+        return self._post("/api/v1/sdk/batches", body)
+
+    def _batch_item_body(self, item: Any, context: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """One member or callback of `create_batch`: the batch's `context` merged key by key under the job's own (the
+        job's keys win)."""
+        base = dict(context or {})
+        if isinstance(item, dict):
+            spec = dict(item)
+            spec["context"] = {**base, **(spec.get("context") or {})}
+            return self._item_body(spec, None)
+        job_cls, payload, opts = (tuple(item) + ({},))[:3]
+        opts = dict(opts or {})
+        opts["context"] = {**base, **(opts.get("context") or {})}
+        return self._item_body((job_cls, payload, opts), None)
+
+    def get_batch(self, batch_id: str) -> Dict[str, Any]:
+        """A Pro batch's progress: `{batch_id, description, status, total, pending, succeeded, failed, created_at,
+        finished_at}`; `status` is pending, then success (no member dead) or complete."""
+        return self._get(f"/api/v1/sdk/batches/{_seg(batch_id)}")
+
+    def enqueue_async(self, job_cls: Type[Job], payload: Any = None, **kwargs: Any) -> "Future[Dict[str, Any]]":
+        """`enqueue` on a background thread: the future holds `{jid, queue, status}` once the gateway stored the job
+        (or the error). Use it when the caller must not wait; `enqueue` answers only once the job is stored."""
+        with self._async_lock:
+            if self._async is None:
+                self._async = ThreadPoolExecutor(max_workers=8, thread_name_prefix="joobq-enqueue")
+        return self._async.submit(self.enqueue, job_cls, payload, **kwargs)
+
+    def start(
+        self,
+        workflow_def: WorkflowBlueprint,
+        input_data: Any = None,
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        workflow_id: Optional[str] = None,
+        search_attributes: Optional[Dict[str, Any]] = None,
+        build: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self.start_workflow(
+            name=workflow_def.name,
+            input_data=input_data,
+            context=context,
+            workflow_id=workflow_id,
+            search_attributes=search_attributes,
+            build=build,
+        )
+
+    def start_workflow(
+        self,
+        name: str,
+        input_data: Any = None,
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        workflow_id: Optional[str] = None,
+        search_attributes: Optional[Dict[str, Any]] = None,
+        build: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self._post("/api/v1/sdk/workflows", {
+            "name": name,
+            "input": input_data,
+            "context": self._resolve_context(context),
+            "id": workflow_id,
+            "search_attributes": search_attributes,
+            "build": build,
+        })
+
+    def signal_workflow(self, workflow_id: str, name: str, payload: Any = None) -> Dict[str, Any]:
+        return self._post(f"/api/v1/sdk/workflows/{workflow_id}/signal", {
+            "name": name,
+            "payload": payload,
+        })
+
+    def update_workflow(self, workflow_id: str, name: str, input: Any = None, *, update_id: Optional[str] = None,
+                        wait_ms: Optional[int] = None) -> Dict[str, Any]:
+        """Sends an update to a running workflow's update handler (Pro) and waits up to `wait_ms` (100 to 30000, default
+        10000) for its outcome: {update_id, name, status, result, error, reason, message}. `status` is completed,
+        rejected (validate failed: `reason`, `message`), failed, or accepted when the handler had not answered in time
+        (send again with the same `update_id` to wait for the same update)."""
+        body: Dict[str, Any] = {"name": name, "input": input}
+        if update_id is not None:
+            body["update_id"] = update_id
+        if wait_ms is not None:
+            body["wait_ms"] = int(wait_ms)
+        return self._post(f"/api/v1/sdk/workflows/{_seg(workflow_id)}/updates", body)
+
+    def describe_workflow(self, workflow_id: str) -> Dict[str, Any]:
+        """One run (Pro): {id, name, status, closed, run, started_at, closed_at, continued_to, output, failure,
+        attributes, queries}. Payload fields with secret-looking names are masked, as in the console."""
+        return self._get(f"/api/v1/sdk/workflows/{_seg(workflow_id)}")
+
+    def workflow_result(self, workflow_id: str, wait_ms: int = 0) -> Dict[str, Any]:
+        """The run at the end of the workflow's continue-as-new chain (Pro), waiting up to `wait_ms` (at most 25000)
+        for it to close; same shape as `describe_workflow`. `closed` false means it was still open when the wait ended."""
+        return self._get(f"/api/v1/sdk/workflows/{_seg(workflow_id)}/result?wait_ms={int(wait_ms)}")
+
+    def workflow_history(self, workflow_id: str, after_seq: int = 0, limit: int = 200) -> List[Dict[str, Any]]:
+        """The run's events after `after_seq` (Pro), at most `limit`, oldest first."""
+        res = self._get(f"/api/v1/sdk/workflows/{_seg(workflow_id)}/history?after_seq={int(after_seq)}&limit={int(limit)}")
+        return res.get("items", [])
+
+    def query_workflow(self, workflow_id: str, name: str) -> Any:
+        """Asks the run a read-only question (Pro); returns the answer."""
+        return self._post(f"/api/v1/sdk/workflows/{_seg(workflow_id)}/query", {"name": name}).get("result")
+
+    def upsert_workflow_attributes(self, workflow_id: str, set: Optional[Dict[str, Any]] = None,
+                                   remove: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Sets and/or removes search attributes of the workflow's open run (Pro); returns {id, attributes}."""
+        return self._post(f"/api/v1/sdk/workflows/{_seg(workflow_id)}/search-attributes", {"set": set, "remove": remove})
+
+    def register_schedule(
+        self,
+        name: str,
+        job_type: str,
+        queue: str,
+        *,
+        cron: Optional[str] = None,
+        every: Optional[str] = None,
+        timezone: str = "UTC",
+        payload: Any = None,
+        max_retries: int = 3,
+        encrypt_fields: Optional[List[str]] = None,
+        unique_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Registers a cron/recurring job schedule, idempotent by `name`. Pass exactly one of `cron` or `every`
+        (`every` is "<count> <unit>", e.g. "30 seconds", "5 minutes"). Returns {id, name, kind, created}."""
+        return self._post("/api/v1/sdk/schedules", {
+            "name": name,
+            "kind": "job",
+            "cron": cron,
+            "every": every,
+            "timezone": timezone,
+            "queue": queue,
+            "job_type": job_type,
+            "payload": payload if payload is not None else {},
+            "max_retries": max_retries,
+            "encrypt_fields": encrypt_fields or [],
+            "unique_key": unique_key,
+        })
+
+    def rate_limit(self, key: str, limit: int, period_ms: int) -> Dict[str, Any]:
+        """Reserves one slot of a sliding-window rate limit (Pro), returning {allowed, retry_after_ms}. `allowed` false
+        gives the ms until a slot frees up. 402 pro_required without a Pro licence."""
+        return self._post("/api/v1/sdk/rate-limit", {"key": key, "limit": limit, "period_ms": period_ms})
+
+    def register_blueprint(self, workflow_def: WorkflowBlueprint, worker_id: Optional[str] = None) -> Dict[str, Any]:
+        """Sends the workflow's blueprint; the gateway keeps each new content hash (`created`) and ignores a known one."""
+        return self._post("/api/v1/sdk/blueprints", {
+            "name": workflow_def.name,
+            "sdk_language": "python",
+            "worker_id": worker_id,
+            "blueprint": workflow_def.to_blueprint(),
+        })
+
+    def register_worker(
+        self,
+        worker_id: str,
+        task_queues: List[str],
+        *,
+        concurrency: int = 4,
+        service_name: Optional[str] = None,
+        team: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self._post("/api/v1/sdk/workers/register", {
+            "worker_id": worker_id,
+            "sdk_language": "python",
+            "sdk_version": SDK_VERSION,
+            "service_name": service_name,
+            "team": team or os.environ.get("JOOBQ_TEAM"),
+            "host": socket.gethostname(),
+            "pid": os.getpid(),
+            "task_queues": task_queues,
+            "concurrency": concurrency,
+            "delivery_mode": "poll",
+        })
+
+    def deregister_worker(self, worker_id: str) -> Dict[str, Any]:
+        return self._post(f"/api/v1/sdk/workers/{worker_id}/deregister", {})
+
+    def poll_tasks(
+        self,
+        worker_id: str,
+        task_queues: List[str],
+        *,
+        max_tasks: int = 1,
+        timeout_ms: int = 0,
+        lease_ttl_ms: int = 30000,
+    ) -> List[LeasedTask]:
+        res = self._post("/api/v1/sdk/tasks/poll", {
+            "worker_id": worker_id,
+            "task_queues": task_queues,
+            "max_tasks": max_tasks,
+            "timeout_ms": timeout_ms,
+            "lease_ttl_ms": lease_ttl_ms,
+        })
+        return [LeasedTask.from_dict(t) for t in res.get("tasks", [])]
+
+    def heartbeat_task(
+        self,
+        lease_token: str,
+        worker_id: str,
+        lease_ttl_ms: int = 30000,
+    ) -> Dict[str, Any]:
+        return self._post(f"/api/v1/sdk/tasks/{lease_token}/heartbeat", {
+            "worker_id": worker_id,
+            "lease_ttl_ms": lease_ttl_ms,
+        })
+
+    def complete_task(
+        self,
+        lease_token: str,
+        worker_id: str,
+        output: Any = None,
+    ) -> Dict[str, Any]:
+        return self._post(f"/api/v1/sdk/tasks/{lease_token}/complete", {
+            "worker_id": worker_id,
+            "output": output,
+        })
+
+    def fail_task(
+        self,
+        lease_token: str,
+        worker_id: str,
+        exc: BaseException,
+        *,
+        retryable: bool = True,
+    ) -> Dict[str, Any]:
+        return self._post(f"/api/v1/sdk/tasks/{lease_token}/fail",
+                          {"worker_id": worker_id, **failure(exc, retryable)})
+
+    def ack_tasks(self, worker_id: str, items: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Settles up to 100 leases in one call (`POST /sdk/tasks/ack`): items are `{token, outcome: "complete", output}`
+        or `{token, outcome: "fail", **failure(exc)}`; each gets its own result."""
+        return self._post("/api/v1/sdk/tasks/ack", {"worker_id": worker_id, "items": items})
+
+    def heartbeat_tasks(self, worker_id: str, leases: List[Dict[str, Any]], lease_ttl_ms: int = 30000) -> Dict[str, Any]:
+        """Renews many leases in one call (`POST /sdk/tasks/heartbeat`): `leases` are `{token}`."""
+        return self._post("/api/v1/sdk/tasks/heartbeat", {"worker_id": worker_id, "lease_ttl_ms": lease_ttl_ms,
+                                                          "leases": leases})
+
+    def _connection(self) -> http.client.HTTPConnection:
+        """This thread's kept-alive connection to the gateway (through the environment's HTTP proxy, if any)."""
+        conn = getattr(self._local, "conn", None)
+        if conn is not None:
+            return conn
+        scheme, host = self._url.scheme or "http", self._url.hostname or "localhost"
+        port = self._url.port or (443 if scheme == "https" else 80)
+        proxy = urllib.request.getproxies().get(scheme)
+        if proxy and urllib.request.proxy_bypass(host):
+            proxy = None
+        self._local.absolute = False
+        if proxy:
+            p = urllib.parse.urlsplit(proxy if "://" in proxy else "http://" + proxy)
+            if scheme == "https":
+                conn = http.client.HTTPSConnection(p.hostname, p.port or 80, timeout=self.request_timeout)
+                conn.set_tunnel(host, port)
+            else:
+                conn = http.client.HTTPConnection(p.hostname, p.port or 80, timeout=self.request_timeout)
+                self._local.absolute = True
+        else:
+            cls = http.client.HTTPSConnection if scheme == "https" else http.client.HTTPConnection
+            conn = cls(host, port, timeout=self.request_timeout)
+        self._local.conn = conn
+        self._local.used = False
+        return conn
+
+    def _drop_connection(self) -> None:
+        conn = getattr(self._local, "conn", None)
+        if conn is not None:
+            conn.close()
+        self._local.conn = None
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return self._send("POST", path, body)
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        return self._send("GET", path, None)
+
+    def _send(self, method: str, path: str, body: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        target = (self._url.path or "") + path
+        while True:
+            conn = self._connection()
+            reused = self._local.used
+            try:
+                conn.request(method, f"{self.gateway_url}{path}" if self._local.absolute else target, data, headers)
+                resp = conn.getresponse()
+                raw = resp.read()
+            except (http.client.RemoteDisconnected, BrokenPipeError, ConnectionResetError):
+                self._drop_connection()
+                if reused:
+                    continue  # the gateway closed the kept-alive connection while it was idle: once more, on a new one
+                raise
+            except Exception:
+                self._drop_connection()
+                raise
+            self._local.used = True
+            if resp.will_close:
+                self._drop_connection()
+            if resp.status >= 400:
+                raise GatewayError(resp.status, raw.decode("utf-8", "replace"))
+            return json.loads(raw.decode("utf-8")) if raw else {}
+
+
+class _Transport:
+    """Every gateway call a running worker makes, on threads of its own: handler threads never wait for HTTP.
+
+    - the poller long-polls for leases into a small buffer (free slots plus `prefetch`) that handlers take from;
+    - the acker sends the outcomes handlers queue (`POST /sdk/tasks/ack`, up to 100 per call, after at most
+      `ack_linger_ms`), retrying while the gateway is unavailable: a task stays leased (and renewed) until its outcome
+      is acknowledged. The outcome queue holds `ack_buffer` items: when it is full, handlers wait;
+    - the heartbeater renews every lease the worker holds in one call (`POST /sdk/tasks/heartbeat`) every third of the
+      lease, and registers the worker every 10 s."""
+
+    def __init__(self, worker: "JoobQWorker") -> None:
+        self.worker = worker
+        self.client = worker.client
+        self.lock = threading.Condition()
+        self.ready: "_queue.Queue[Optional[LeasedTask]]" = _queue.Queue()
+        self.acks: "_queue.Queue[Dict[str, Any]]" = _queue.Queue(maxsize=worker.ack_buffer)
+        self.leased: Dict[str, LeasedTask] = {}  # every lease held: buffered, running, or waiting for its ack
+        self.held = 0  # buffered + running
+        self.cancelled: Dict[str, bool] = {}
+        self.acker_done = threading.Event()  # set: the acker exits once the outcome queue is empty
+        self.give_up = threading.Event()  # set: the drain timeout passed, unsent outcomes are left to their leases
+        self.stopped = threading.Event()
+        self.running = False
+
+    # -- handler side ---------------------------------------------------------------------------------------------
+    def settle(self, item: Dict[str, Any]) -> None:
+        """Queues an outcome for the acker; waits while the queue is full (back-pressure)."""
+        while True:
+            try:
+                self.acks.put(item, timeout=0.5)
+                return
+            except _queue.Full:
+                if self.give_up.is_set():
+                    return  # left to its lease
+
+    def cancel_requested(self, token: str) -> bool:
+        with self.lock:
+            return self.cancelled.get(token, False)
+
+    def release(self, token: str) -> None:
+        with self.lock:
+            self.leased.pop(token, None)
+            self.cancelled.pop(token, None)
+
+    # -- threads --------------------------------------------------------------------------------------------------
+    def handle(self) -> None:
+        while True:
+            task = self.ready.get()
+            if task is None:
+                return
+            try:
+                self.worker.process_task(task)
+            except Exception as exc:  # process_task reports handler errors itself: this is a bug in the worker
+                print(f"joobq: task {task.id} could not be settled: {exc!r}", file=sys.stderr)
+            finally:
+                with self.lock:
+                    self.held -= 1
+                    self.lock.notify_all()
+
+    def poll(self, poll_interval_sec: float) -> None:
+        w = self.worker
+        capacity = w.concurrency + w.prefetch
+        backoff = poll_interval_sec
+        while not w._stopping.is_set():
+            with self.lock:
+                while self.held >= capacity and not w._stopping.is_set():
+                    self.lock.wait(0.5)
+                room = capacity - self.held
+            if w._stopping.is_set():
+                return
+            try:
+                tasks = self.client.poll_tasks(w.worker_id, w.task_queues, max_tasks=min(room, 100),
+                                               timeout_ms=w.poll_timeout_ms, lease_ttl_ms=w.lease_ttl_ms)
+                backoff = poll_interval_sec
+                w._refused = None
+            except Exception as exc:
+                w._report_refusal("poll for tasks", exc)
+                w._stopping.wait(backoff + random.random() * 0.1)
+                backoff = min(backoff * 2, 5.0)
+                continue
+            with self.lock:
+                for task in tasks:
+                    self.leased[task.lease_token] = task
+                self.held += len(tasks)
+            for task in tasks:
+                self.ready.put(task)
+
+    def ack(self) -> None:
+        linger = self.worker.ack_linger_ms / 1000.0
+        while True:
+            try:
+                first = self.acks.get(timeout=0.1)
+            except _queue.Empty:
+                if self.acker_done.is_set():
+                    return
+                continue
+            batch = [first]
+            deadline = time.monotonic() + linger
+            while len(batch) < 100:
+                left = deadline - time.monotonic()
+                try:
+                    batch.append(self.acks.get(timeout=left) if left > 0 else self.acks.get_nowait())
+                except _queue.Empty:
+                    break
+            self.send_acks(batch)
+
+    def send_acks(self, batch: List[Dict[str, Any]]) -> None:
+        delay = 0.25
+        while True:
+            try:
+                self.client.ack_tasks(self.worker.worker_id, batch)
+                break  # a refused item (its lease is gone) is not sent again either
+            except GatewayError as err:
+                if err.status == 413 and len(batch) > 1:  # too large for one call: in halves
+                    half = len(batch) // 2
+                    self.send_acks(batch[:half])
+                    self.send_acks(batch[half:])
+                    return
+                if err.status < 500 and err.status != 429:
+                    print(f"joobq: the gateway refused {len(batch)} outcomes: {err}", file=sys.stderr)
+                    break
+            except Exception:
+                pass
+            if self.give_up.wait(delay):
+                break  # shutting down: the leases bring these tasks back
+            delay = min(delay * 2, 5.0)
+        for item in batch:
+            self.release(item["token"])
+
+    def heartbeat(self) -> None:
+        w = self.worker
+        every = max(0.5, w.lease_ttl_ms / 3000.0)
+        last_reg = time.monotonic()
+        while not self.stopped.wait(every):
+            with self.lock:
+                tokens = list(self.leased)
+            for start in range(0, len(tokens), 500):
+                chunk = tokens[start:start + 500]
+                try:
+                    res = self.client.heartbeat_tasks(w.worker_id, [{"token": t} for t in chunk], w.lease_ttl_ms)
+                except Exception:
+                    continue  # renewed with the next heartbeat
+                with self.lock:
+                    for lease in res.get("leases", []):
+                        token = lease.get("lease_token")
+                        if lease.get("error"):
+                            self.leased.pop(token, None)  # gone: its outcome will be refused, nothing to renew
+                        elif token in self.leased:
+                            self.cancelled[token] = bool(lease.get("cancel_requested"))
+            if time.monotonic() - last_reg > 10.0 and not w._stopping.is_set():
+                try:
+                    w._register_blueprints()
+                    w._register()
+                except Exception:
+                    pass
+                last_reg = time.monotonic()
+
+    def run(self, poll_interval_sec: float) -> None:
+        w = self.worker
+        self.running = True
+        threads = [threading.Thread(target=self.handle, name=f"joobq-task-{i}", daemon=True) for i in range(w.concurrency)]
+        acker = threading.Thread(target=self.ack, name="joobq-acker", daemon=True)
+        beat = threading.Thread(target=self.heartbeat, name="joobq-heartbeat", daemon=True)
+        for t in threads + [acker, beat]:
+            t.start()
+        self.poll(poll_interval_sec)  # until stop()
+        deadline = time.monotonic() + w.drain_timeout_sec
+        with self.lock:
+            while self.held > 0 and time.monotonic() < deadline:
+                self.lock.wait(0.05)
+        for _ in threads:
+            self.ready.put(None)
+        self.acker_done.set()
+        acker.join(max(0.0, deadline - time.monotonic()))
+        if acker.is_alive():
+            self.give_up.set()
+            acker.join(5.0)
+        self.give_up.set()
+        self.stopped.set()
+        beat.join(5.0)
+        self.running = False
+
+
+class JoobQWorker:
+    """In-app worker: runs up to `concurrency` jobs and workflow steps at once inside the booted application, and
+    drains on SIGTERM/SIGINT. Its gateway calls (poll, outcomes, heartbeats) run
+    on threads of their own (`_Transport`), so a handler never waits for HTTP."""
+
+    def __init__(
+        self,
+        client: JoobQClient,
+        worker_id: str,
+        task_queues: Optional[List[str]] = None,
+        *,
+        concurrency: int = 4,
+        service_name: Optional[str] = None,
+        team: Optional[str] = None,
+        lease_ttl_ms: int = 30000,
+        poll_timeout_ms: int = 5000,
+        drain_timeout_sec: float = 30.0,
+        prefetch: Optional[int] = None,
+        ack_buffer: Optional[int] = None,
+        ack_linger_ms: int = 5,
+    ) -> None:
+        self.client = client
+        self.worker_id = worker_id
+        self.task_queues = list(task_queues or [])
+        self.concurrency = max(1, concurrency)
+        self.service_name = service_name
+        self.team = team
+        self.lease_ttl_ms = lease_ttl_ms
+        self.poll_timeout_ms = poll_timeout_ms
+        # One hung call must not outlast the leases: a poll waits `poll_timeout_ms` at the gateway, and a sixth of a
+        # lease on top keeps a renewal that hangs well inside the lease (10 s with the defaults).
+        bound = poll_timeout_ms / 1000.0 + lease_ttl_ms / 6000.0
+        if getattr(client, "request_timeout", None) is not None and client.request_timeout > bound:
+            client.request_timeout = bound
+        self.drain_timeout_sec = drain_timeout_sec
+        # Leases held beyond the free slots, so a handler that finishes finds its next task at once.
+        self.prefetch = max(0, prefetch if prefetch is not None else max(1, self.concurrency // 2))
+        # Outcomes queued for the acker before handlers wait for it.
+        self.ack_buffer = max(1, ack_buffer if ack_buffer is not None else 4 * self.concurrency)
+        self.ack_linger_ms = max(0, ack_linger_ms)
+        self._handlers: Dict[str, Callable[[Any, ExecutionContext], Any]] = {}
+        self._workflows: Dict[str, WorkflowBlueprint] = {}
+        self._middlewares: List[Callable[[ExecutionContext, Callable[[], Any]], Any]] = []
+        self._stopping = threading.Event()
+        self._blueprints_sent: set = set()
+        self._transport = _Transport(self)
+
+    def use(self, middleware: Callable[[ExecutionContext, Callable[[], Any]], Any]) -> "JoobQWorker":
+        self._middlewares.append(middleware)
+        return self
+
+    def register_job(self, job_cls: Type[Job]) -> "JoobQWorker":
+        if job_cls.queue and job_cls.queue not in self.task_queues:
+            self.task_queues.append(job_cls.queue)
+        self._handlers[job_cls.resolved_name()] = _normalize_callable(job_cls)
+        return self
+
+    def register_workflow(self, workflow_def: WorkflowBlueprint) -> "JoobQWorker":
+        if workflow_def.task_queue and workflow_def.task_queue not in self.task_queues:
+            self.task_queues.append(workflow_def.task_queue)
+        self._workflows[workflow_def.name] = workflow_def
+        # The engine conducts the workflow's runs and sends each step as its own task.
+        self._handlers.update(workflow_def.activities())
+        return self
+
+    def handle_job(self, job_type: str, handler: Callable[[Any, ExecutionContext], Any]) -> "JoobQWorker":
+        self._handlers[job_type] = handler
+        return self
+
+    def process_task(self, task: LeasedTask) -> Dict[str, Any]:
+        handler = self._handlers.get(task.name)
+        if not handler:
+            self._settle(task, {"outcome": "fail", **failure(NonRetryableError(f"No handler registered for {task.name!r}"), False)})
+            return {"status": "failed"}
+        # Everything that can raise for this task is inside the try: a task with no outcome keeps its lease renewed for
+        # ever. BaseException, so that a handler calling sys.exit() (or raising anything else that is not an Exception)
+        # fails its task instead of ending the handler thread without a word.
+        try:
+            transport = self._transport if self._transport.running else None
+            ctx = ExecutionContext(task, self.worker_id, self.client, self.lease_ttl_ms, transport)
+
+            def invoke(idx: int) -> Any:
+                if idx < len(self._middlewares):
+                    return self._middlewares[idx](ctx, lambda: invoke(idx + 1))
+                return handler(task.payload, ctx)
+
+            output = invoke(0)
+        except BaseException as exc:
+            if isinstance(exc, KeyboardInterrupt):
+                raise
+            retryable = not isinstance(exc, NonRetryableError)
+            self._settle(task, {"outcome": "fail", **failure(exc, retryable)})
+            return {"status": "failed"}
+        self._settle(task, {"outcome": "complete", "output": output})
+        return {"status": "completed", "output": output}
+
+    def _report_refusal(self, what: str, exc: BaseException) -> None:
+        """Says once, on stderr, that the gateway refuses this worker (a wrong or rotated token, no Pro key): it goes
+        on retrying, and without this line it would sit idle with nothing in its output."""
+        status = getattr(exc, "status", None)
+        if not isinstance(status, int) or status < 400 or status >= 500 or status in (408, 429):
+            return
+        if getattr(self, "_refused", None) != status:
+            self._refused = status
+            print(f"joobq: the gateway refuses this worker ({what}): {exc}. Retrying; check the SDK token and the server's licence.", file=sys.stderr)
+
+    def _settle(self, task: LeasedTask, item: Dict[str, Any]) -> None:
+        """Hands the outcome to the acker; outside a running worker (`process_task` called directly) it is sent here."""
+        item = {"token": task.lease_token, **item}
+        if self._transport.running:
+            self._transport.settle(item)
+        else:
+            self._report(lambda: self.client.ack_tasks(self.worker_id, [item]))
+
+    def _report(self, call: Callable[[], Any]) -> None:
+        """Sends an outcome, retrying while the gateway is unavailable; a lost outcome is left to the lease."""
+        delay = 0.25
+        for _ in range(6):
+            try:
+                call()
+                return
+            except GatewayError as err:
+                if err.status < 500:
+                    return  # the outcome was refused: nothing to retry
+            except Exception:
+                pass
+            time.sleep(delay)
+            delay = min(delay * 2, 5.0)
+
+    def stop(self) -> None:
+        """Stops polling; `start` returns once the running tasks have finished and their outcomes are acknowledged
+        (or `drain_timeout_sec` passed)."""
+        self._stopping.set()
+        with self._transport.lock:
+            self._transport.lock.notify_all()
+
+    def _register(self) -> None:
+        self.client.register_worker(self.worker_id, self.task_queues, concurrency=self.concurrency,
+                                    service_name=self.service_name, team=self.team)
+
+    def _register_blueprints(self) -> None:
+        """Registers every workflow's blueprint once; one the gateway refuses (4xx) is logged and not sent again."""
+        for name, wf in list(self._workflows.items()):
+            if name in self._blueprints_sent:
+                continue
+            try:
+                self.client.register_blueprint(wf, self.worker_id)
+                self._blueprints_sent.add(name)
+            except GatewayError as err:
+                if err.status >= 500:
+                    raise
+                self._blueprints_sent.add(name)
+                print(f"joobq: blueprint of {name!r} refused: {err}", file=sys.stderr)
+
+    def start(self, poll_interval_sec: float = 0.25, install_signal_handlers: bool = True) -> None:
+        """Runs the worker until SIGTERM/SIGINT or `stop()`, then drains the running tasks, sends their outcomes and
+        deregisters."""
+        if install_signal_handlers and threading.current_thread() is threading.main_thread():
+            for sig in (_signal.SIGTERM, _signal.SIGINT):
+                _signal.signal(sig, lambda *_: self.stop())
+        backoff = poll_interval_sec
+        while not self._stopping.is_set():
+            try:
+                self._register_blueprints()  # first: a worker that shows up has its blueprints in
+                self._register()
+                self._refused = None
+                break
+            except Exception as exc:
+                self._report_refusal("register", exc)
+                self._stopping.wait(backoff + random.random() * 0.1)
+                backoff = min(backoff * 2, 5.0)
+        self._transport.run(poll_interval_sec)
+        try:
+            self.client.deregister_worker(self.worker_id)
+        except Exception:
+            pass
+
+    run = start
+