schemathesis 4.0.0a2__py3-none-any.whl → 4.0.0a4__py3-none-any.whl

schemathesis/specs/openapi/schemas.py

@@ -41,11 +41,12 @@ from schemathesis.generation.case import Case
 from schemathesis.generation.meta import CaseMetadata
 from schemathesis.generation.overrides import Override, OverrideMark, check_no_override_mark
 from schemathesis.openapi.checks import JsonSchemaError, MissingContentType
+from schemathesis.specs.openapi.stateful import links
 
 from ...generation import GenerationConfig, GenerationMode
 from ...hooks import HookContext, HookDispatcher
 from ...schemas import APIOperation, APIOperationMap, ApiStatistic, BaseSchema, OperationDefinition
-from . import links, serialization
+from . import serialization
 from ._cache import OperationCache
 from ._hypothesis import openapi_cases
 from .converter import to_json_schema, to_json_schema_recursive
@@ -66,8 +67,8 @@ from .stateful import create_state_machine
 if TYPE_CHECKING:
     from hypothesis.strategies import SearchStrategy
 
-    from ...auths import AuthStorage
-    from ...stateful.state_machine import APIStateMachine
+    from schemathesis.auths import AuthStorage
+    from schemathesis.generation.stateful import APIStateMachine
 
 HTTP_METHODS = frozenset({"get", "put", "post", "delete", "options", "head", "patch", "trace"})
 SCHEMA_ERROR_MESSAGE = "Ensure that the definition complies with the OpenAPI specification"
@@ -155,7 +156,6 @@ class BaseOpenAPISchema(BaseSchema):
             return True
         if self.filter_set.is_empty():
             return False
-        path = self.get_full_path(path)
         # Attribute assignment is way faster than creating a new namespace every time
         operation = _ctx_cache.operation
         operation.method = method
@@ -174,30 +174,64 @@ class BaseOpenAPISchema(BaseSchema):
             return statistic
 
         resolve = self.resolver.resolve
+        resolve_path_item = self._resolve_path_item
         should_skip = self._should_skip
         links_field = self.links_field
 
+        # For operationId lookup
+        selected_operations_by_id: set[str] = set()
+        # Tuples of (method, path)
+        selected_operations_by_path: set[tuple[str, str]] = set()
+        collected_links: list[dict] = []
+
         for path, path_item in paths.items():
             try:
-                if "$ref" in path_item:
-                    _, path_item = resolve(path_item["$ref"])
-                for method, definition in path_item.items():
-                    if method not in HTTP_METHODS:
-                        continue
-                    statistic.operations.total += 1
-                    is_selected = not should_skip(path, method, definition)
-                    if is_selected:
-                        statistic.operations.selected += 1
-                    for response in definition.get("responses", {}).values():
-                        if "$ref" in response:
-                            _, response = resolve(response["$ref"])
-                        defined_links = response.get(links_field)
-                        if defined_links is not None:
-                            statistic.links.total += len(defined_links)
-                            if is_selected:
-                                statistic.links.selected = len(defined_links)
+                scope, path_item = resolve_path_item(path_item)
+                self.resolver.push_scope(scope)
+                try:
+                    for method, definition in path_item.items():
+                        if method not in HTTP_METHODS:
+                            continue
+                        statistic.operations.total += 1
+                        is_selected = not should_skip(path, method, definition)
+                        if is_selected:
+                            statistic.operations.selected += 1
+                            # Store both identifiers
+                            if "operationId" in definition:
+                                selected_operations_by_id.add(definition["operationId"])
+                            selected_operations_by_path.add((method, path))
+                        for response in definition.get("responses", {}).values():
+                            if "$ref" in response:
+                                _, response = resolve(response["$ref"])
+                            defined_links = response.get(links_field)
+                            if defined_links is not None:
+                                statistic.links.total += len(defined_links)
+                                if is_selected:
+                                    collected_links.extend(defined_links.values())
+                finally:
+                    self.resolver.pop_scope()
             except SCHEMA_PARSING_ERRORS:
                 continue
+
+        def is_link_selected(link: dict) -> bool:
+            if "$ref" in link:
+                _, link = resolve(link["$ref"])
+
+            if "operationId" in link:
+                return link["operationId"] in selected_operations_by_id
+            else:
+                try:
+                    scope, _ = resolve(link["operationRef"])
+                    path, method = scope.rsplit("/", maxsplit=2)[-2:]
+                    path = path.replace("~1", "/").replace("~0", "~")
+                    return (method, path) in selected_operations_by_path
+                except Exception:
+                    return False
+
+        for link in collected_links:
+            if is_link_selected(link):
+                statistic.links.selected += 1
+
         return statistic
 
     def _operation_iter(self) -> Generator[dict[str, Any], None, None]:
@@ -331,28 +365,24 @@ class BaseOpenAPISchema(BaseSchema):
     def _into_err(self, error: Exception, path: str | None, method: str | None) -> Err[InvalidSchema]:
         __tracebackhide__ = True
         try:
-            full_path = self.get_full_path(path) if isinstance(path, str) else None
-            self._raise_invalid_schema(error, full_path, path, method)
+            self._raise_invalid_schema(error, path, method)
         except InvalidSchema as exc:
             return Err(exc)
 
     def _raise_invalid_schema(
         self,
         error: Exception,
-        full_path: str | None = None,
         path: str | None = None,
         method: str | None = None,
     ) -> NoReturn:
         __tracebackhide__ = True
         if isinstance(error, RefResolutionError):
-            raise InvalidSchema.from_reference_resolution_error(
-                error, path=path, method=method, full_path=full_path
-            ) from None
+            raise InvalidSchema.from_reference_resolution_error(error, path=path, method=method) from None
         try:
             self.validate()
         except jsonschema.ValidationError as exc:
-            raise InvalidSchema.from_jsonschema_error(exc, path=path, method=method, full_path=full_path) from None
-        raise InvalidSchema(SCHEMA_ERROR_MESSAGE, path=path, method=method, full_path=full_path) from error
+            raise InvalidSchema.from_jsonschema_error(exc, path=path, method=method) from None
+        raise InvalidSchema(SCHEMA_ERROR_MESSAGE, path=path, method=method) from error
 
     def validate(self) -> None:
         with suppress(TypeError):
@@ -550,8 +580,7 @@ class BaseOpenAPISchema(BaseSchema):
             responses = operation.definition.raw["responses"]
         except KeyError as exc:
             path = operation.path
-            full_path = self.get_full_path(path) if isinstance(path, str) else None
-            self._raise_invalid_schema(exc, full_path, path, operation.method)
+            self._raise_invalid_schema(exc, path, operation.method)
         status_code = str(response.status_code)
         if status_code in responses:
             return self.resolver.resolve_in_scope(responses[status_code], operation.definition.scope)
@@ -569,13 +598,7 @@ class BaseOpenAPISchema(BaseSchema):
         return scopes, definitions.get("headers")
 
     def as_state_machine(self) -> type[APIStateMachine]:
-        try:
-            return create_state_machine(self)
-        except OperationNotFound as exc:
-            raise LoaderError(
-                kind=LoaderErrorKind.OPEN_API_INVALID_SCHEMA,
-                message=f"Invalid Open API link definition: Operation `{exc.item}` not found",
-            ) from exc
+        return create_state_machine(self)
 
     def add_link(
         self,
@@ -626,7 +649,12 @@ class BaseOpenAPISchema(BaseSchema):
     def get_links(self, operation: APIOperation) -> dict[str, dict[str, Any]]:
         result: dict[str, dict[str, Any]] = defaultdict(dict)
         for status_code, link in links.get_all_links(operation):
-            result[status_code][link.name] = link
+            if isinstance(link, Ok):
+                name = link.ok().name
+            else:
+                name = link.err().name
+            result[status_code][name] = link
+
         return result
 
     def get_tags(self, operation: APIOperation) -> list[str] | None:

schemathesis/specs/openapi/stateful/__init__.py

@@ -1,32 +1,40 @@
 from __future__ import annotations
 
-from collections import defaultdict
+from dataclasses import dataclass
 from functools import lru_cache
 from typing import TYPE_CHECKING, Any, Callable, Iterator
 
 from hypothesis import strategies as st
 from hypothesis.stateful import Bundle, Rule, precondition, rule
 
+from schemathesis.core.errors import InvalidStateMachine
 from schemathesis.core.result import Ok
+from schemathesis.core.transforms import UNRESOLVABLE
+from schemathesis.engine.recorder import ScenarioRecorder
+from schemathesis.generation import GenerationMode
 from schemathesis.generation.case import Case
 from schemathesis.generation.hypothesis import strategies
 from schemathesis.generation.stateful.state_machine import APIStateMachine, StepInput, StepOutput, _normalize_name
 from schemathesis.schemas import APIOperation
-
-from ....generation import GenerationMode
-from ..links import OpenApiLink, get_all_links
-from ..utils import expand_status_code
+from schemathesis.specs.openapi.stateful.control import TransitionController
+from schemathesis.specs.openapi.stateful.links import OpenApiLink, get_all_links
+from schemathesis.specs.openapi.utils import expand_status_code
 
 if TYPE_CHECKING:
     from schemathesis.generation.stateful.state_machine import StepOutput
-
-    from ..schemas import BaseOpenAPISchema
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
 
 FilterFunction = Callable[["StepOutput"], bool]
 
 
 class OpenAPIStateMachine(APIStateMachine):
     _response_matchers: dict[str, Callable[[StepOutput], str | None]]
+    _transitions: ApiTransitions
+
+    def __init__(self) -> None:
+        self.recorder = ScenarioRecorder(label="Stateful tests")
+        self.control = TransitionController(self._transitions)
+        super().__init__()
 
     def _get_target_for_result(self, result: StepOutput) -> str | None:
         matcher = self._response_matchers.get(result.case.operation.label)
@@ -36,81 +44,155 @@ class OpenAPIStateMachine(APIStateMachine):
 
 
 # The proportion of negative tests generated for "root" transitions
-NEGATIVE_TEST_CASES_THRESHOLD = 20
+NEGATIVE_TEST_CASES_THRESHOLD = 10
 
 
-def create_state_machine(schema: BaseOpenAPISchema) -> type[APIStateMachine]:
-    """Create a state machine class.
+@dataclass
+class OperationTransitions:
+    """Transitions for a single operation."""
 
-    It aims to avoid making calls that are not likely to lead to a stateful call later. For example:
-      1. POST /users/
-      2. GET /users/{id}/
+    __slots__ = ("incoming", "outgoing")
 
-    This state machine won't make calls to (2) without having a proper response from (1) first.
-    """
+    def __init__(self) -> None:
+        self.incoming: list[OpenApiLink] = []
+        self.outgoing: list[OpenApiLink] = []
+
+
+@dataclass
+class ApiTransitions:
+    """Stores all transitions grouped by operation."""
+
+    __slots__ = ("operations",)
+
+    def __init__(self) -> None:
+        # operation label -> its transitions
+        self.operations: dict[str, OperationTransitions] = {}
+
+    def add_outgoing(self, source: str, link: OpenApiLink) -> None:
+        """Record an outgoing transition from source operation."""
+        self.operations.setdefault(source, OperationTransitions()).outgoing.append(link)
+        self.operations.setdefault(link.target.label, OperationTransitions()).incoming.append(link)
+
+
+@dataclass
+class RootTransitions:
+    """Classification of API operations that can serve as entry points."""
+
+    __slots__ = ("reliable", "fallback")
+
+    def __init__(self) -> None:
+        # Operations likely to succeed and provide data for other transitions
+        self.reliable: set[str] = set()
+        # Operations that might work but are less reliable
+        self.fallback: set[str] = set()
+
+
+def collect_transitions(operations: list[APIOperation]) -> ApiTransitions:
+    """Collect all transitions between operations."""
+    transitions = ApiTransitions()
+
+    selected_labels = {operation.label for operation in operations}
+    errors = []
+    for operation in operations:
+        for _, link in get_all_links(operation):
+            if isinstance(link, Ok):
+                if link.ok().target.label in selected_labels:
+                    transitions.add_outgoing(operation.label, link.ok())
+            else:
+                errors.append(link.err())
+
+    if errors:
+        raise InvalidStateMachine(errors)
+
+    return transitions
+
+
+def create_state_machine(schema: BaseOpenAPISchema) -> type[APIStateMachine]:
     operations = [result.ok() for result in schema.get_all_operations() if isinstance(result, Ok)]
     bundles = {}
-    incoming_transitions = defaultdict(list)
+    transitions = collect_transitions(operations)
     _response_matchers: dict[str, Callable[[StepOutput], str | None]] = {}
-    # Statistic structure follows the links and count for each response status code
+
+    # Create bundles and matchers
     for operation in operations:
         all_status_codes = tuple(operation.definition.raw["responses"])
         bundle_matchers = []
-        for _, link in get_all_links(operation):
-            bundle_name = f"{operation.label} -> {link.status_code}"
-            bundles[bundle_name] = Bundle(bundle_name)
-            incoming_transitions[link.target.label].append(link)
-            bundle_matchers.append((bundle_name, make_response_filter(link.status_code, all_status_codes)))
+
+        if operation.label in transitions.operations:
+            # Use outgoing transitions
+            for link in transitions.operations[operation.label].outgoing:
+                bundle_name = f"{operation.label} -> {link.status_code}"
+                bundles[bundle_name] = Bundle(bundle_name)
+                bundle_matchers.append((bundle_name, make_response_filter(link.status_code, all_status_codes)))
+
         if bundle_matchers:
             _response_matchers[operation.label] = make_response_matcher(bundle_matchers)
+
     rules = {}
     catch_all = Bundle("catch_all")
 
+    # We want stateful testing to be effective and focus on meaningful transitions.
+    # An operation is considered as a "root" transition (entry point) if it satisfies certain criteria
+    # that indicate it's likely to succeed and provide data for other transitions.
+    # For example:
+    #   - POST operations that create resources
+    #   - GET operations without path parameters (e.g., GET /users/ to list all users)
+    #
+    # We avoid adding operations as roots if they:
+    #   1. Have incoming transitions that will provide proper data
+    #      Example: If POST /users/ -> GET /users/{id} exists, we don't need
+    #      to generate random user IDs for GET /users/{id}
+    #   2. Are unlikely to succeed with random data
+    #      Example: GET /users/{id} with random ID is likely to return 404
+    #
+    # This way we:
+    #   1. Maximize the chance of successful transitions
+    #   2. Don't waste the test budget (limited number of steps) on likely-to-fail operations
+    #   3. Focus on transitions that are designed to work together via links
+
+    roots = classify_root_transitions(operations, transitions)
+
     for target in operations:
-        incoming = incoming_transitions.get(target.label)
-        if incoming is not None:
-            for link in incoming:
-                bundle_name = f"{link.source.label} -> {link.status_code}"
-                name = _normalize_name(f"{link.status_code} -> {target.label}")
-                rules[name] = precondition(ensure_non_empty_bundle(bundle_name))(
-                    transition(
-                        name=name,
-                        target=catch_all,
-                        input=bundles[bundle_name].flatmap(
-                            into_step_input(target=target, link=link, modes=schema.generation_config.modes)
-                        ),
+        if target.label in transitions.operations:
+            incoming = transitions.operations[target.label].incoming
+            if incoming:
+                for link in incoming:
+                    bundle_name = f"{link.source.label} -> {link.status_code}"
+                    name = _normalize_name(
+                        f"{link.source.label} -> {link.status_code} -> {link.name} -> {target.label}"
                     )
+                    assert name not in rules, name
+                    rules[name] = precondition(is_transition_allowed(bundle_name, link.source.label, target.label))(
+                        transition(
+                            name=name,
+                            target=catch_all,
+                            input=bundles[bundle_name].flatmap(
+                                into_step_input(target=target, link=link, modes=schema.generation_config.modes)
+                            ),
+                        )
+                    )
+            if target.label in roots.reliable or (not roots.reliable and target.label in roots.fallback):
+                name = _normalize_name(f"RANDOM -> {target.label}")
+                if len(schema.generation_config.modes) == 1:
+                    case_strategy = target.as_strategy(generation_mode=schema.generation_config.modes[0])
+                else:
+                    _strategies = {
+                        method: target.as_strategy(generation_mode=method) for method in schema.generation_config.modes
+                    }
+
+                    @st.composite  # type: ignore[misc]
+                    def case_strategy_factory(
+                        draw: st.DrawFn, strategies: dict[GenerationMode, st.SearchStrategy] = _strategies
+                    ) -> Case:
+                        if draw(st.integers(min_value=0, max_value=99)) < NEGATIVE_TEST_CASES_THRESHOLD:
+                            return draw(strategies[GenerationMode.NEGATIVE])
+                        return draw(strategies[GenerationMode.POSITIVE])
+
+                    case_strategy = case_strategy_factory()
+
+                rules[name] = precondition(is_root_allowed(target.label))(
+                    transition(name=name, target=catch_all, input=case_strategy.map(StepInput.initial))
                 )
-        elif any(
-            incoming.source.label == target.label
-            for transitions in incoming_transitions.values()
-            for incoming in transitions
-        ):
-            # No incoming transitions, but has at least one outgoing transition
-            # For example, POST /users/ -> GET /users/{id}/
-            # The source operation has no prerequisite, but we need to allow this rule to be executed
-            # in order to reach other transitions
-            name = _normalize_name(f"{target.label} -> X")
-            if len(schema.generation_config.modes) == 1:
-                case_strategy = target.as_strategy(generation_mode=schema.generation_config.modes[0])
-            else:
-                _strategies = {
-                    method: target.as_strategy(generation_mode=method) for method in schema.generation_config.modes
-                }
-
-                @st.composite  # type: ignore[misc]
-                def case_strategy_factory(
-                    draw: st.DrawFn, strategies: dict[GenerationMode, st.SearchStrategy] = _strategies
-                ) -> Case:
-                    if draw(st.integers(min_value=0, max_value=99)) < NEGATIVE_TEST_CASES_THRESHOLD:
-                        return draw(strategies[GenerationMode.NEGATIVE])
-                    return draw(strategies[GenerationMode.POSITIVE])
-
-                case_strategy = case_strategy_factory()
-
-            rules[name] = precondition(ensure_links_followed)(
-                transition(name=name, target=catch_all, input=case_strategy.map(StepInput.initial))
-            )
 
     return type(
         "APIWorkflow",
@@ -119,69 +201,110 @@ def create_state_machine(schema: BaseOpenAPISchema) -> type[APIStateMachine]:
             "schema": schema,
             "bundles": bundles,
             "_response_matchers": _response_matchers,
+            "_transitions": transitions,
             **rules,
         },
     )
 
 
+def classify_root_transitions(operations: list[APIOperation], transitions: ApiTransitions) -> RootTransitions:
+    """Find operations that can serve as root transitions."""
+    roots = RootTransitions()
+
+    for operation in operations:
+        # Skip if operation has no outgoing transitions
+        operation_transitions = transitions.operations.get(operation.label)
+        if not operation_transitions or not operation_transitions.outgoing:
+            continue
+
+        if is_likely_root_transition(operation, operation_transitions):
+            roots.reliable.add(operation.label)
+        else:
+            roots.fallback.add(operation.label)
+
+    return roots
+
+
+def is_likely_root_transition(operation: APIOperation, transitions: OperationTransitions) -> bool:
+    """Check if operation is likely to succeed as a root transition."""
+    # POST operations with request bodies are likely to create resources
+    if operation.method == "post" and operation.body:
+        return True
+
+    # GET operations without path parameters are likely to return lists
+    if operation.method == "get" and not operation.path_parameters:
+        return True
+
+    return False
+
+
 def into_step_input(
     target: APIOperation, link: OpenApiLink, modes: list[GenerationMode]
 ) -> Callable[[StepOutput], st.SearchStrategy[StepInput]]:
     def builder(_output: StepOutput) -> st.SearchStrategy[StepInput]:
         @st.composite  # type: ignore[misc]
         def inner(draw: st.DrawFn, output: StepOutput) -> StepInput:
-            transition_data = link.extract(output)
+            transition = link.extract(output)
 
             kwargs: dict[str, Any] = {
                 container: {
                     name: extracted.value.ok()
                     for name, extracted in data.items()
-                    if isinstance(extracted.value, Ok) and extracted.value.ok() is not None
+                    if isinstance(extracted.value, Ok) and extracted.value.ok() not in (None, UNRESOLVABLE)
                 }
-                for container, data in transition_data.parameters.items()
+                for container, data in transition.parameters.items()
             }
+
             if (
-                transition_data.request_body is not None
-                and isinstance(transition_data.request_body.value, Ok)
+                transition.request_body is not None
+                and isinstance(transition.request_body.value, Ok)
+                and transition.request_body.value.ok() is not UNRESOLVABLE
                 and not link.merge_body
             ):
-                kwargs["body"] = transition_data.request_body.value.ok()
+                kwargs["body"] = transition.request_body.value.ok()
             cases = strategies.combine([target.as_strategy(generation_mode=mode, **kwargs) for mode in modes])
             case = draw(cases)
             if (
-                transition_data.request_body is not None
-                and isinstance(transition_data.request_body.value, Ok)
+                transition.request_body is not None
+                and isinstance(transition.request_body.value, Ok)
+                and transition.request_body.value.ok() is not UNRESOLVABLE
                 and link.merge_body
             ):
-                new = transition_data.request_body.value.ok()
+                new = transition.request_body.value.ok()
                 if isinstance(case.body, dict) and isinstance(new, dict):
                     case.body = {**case.body, **new}
                 else:
                     case.body = new
-            return StepInput(case=case, transition=transition_data)
+            return StepInput(case=case, transition=transition)
 
         return inner(output=_output)
 
     return builder
 
 
-def ensure_non_empty_bundle(bundle_name: str) -> Callable[[APIStateMachine], bool]:
-    def inner(machine: APIStateMachine) -> bool:
-        return bool(machine.bundles.get(bundle_name))
+def is_transition_allowed(bundle_name: str, source: str, target: str) -> Callable[[OpenAPIStateMachine], bool]:
+    def inner(machine: OpenAPIStateMachine) -> bool:
+        return bool(machine.bundles.get(bundle_name)) and machine.control.allow_transition(source, target)
 
     return inner
 
 
-def ensure_links_followed(machine: APIStateMachine) -> bool:
-    # If there are responses that have links to follow, reject any rule without incoming transitions
-    for bundle in machine.bundles.values():
-        if bundle:
-            return False
-    return True
+def is_root_allowed(label: str) -> Callable[[OpenAPIStateMachine], bool]:
+    def inner(machine: OpenAPIStateMachine) -> bool:
+        return machine.control.allow_root_transition(label, machine.bundles)
+
+    return inner
 
 
 def transition(*, name: str, target: Bundle, input: st.SearchStrategy[StepInput]) -> Callable[[Callable], Rule]:
-    def step_function(self: APIStateMachine, input: StepInput) -> StepOutput | None:
+    def step_function(self: OpenAPIStateMachine, input: StepInput) -> StepOutput | None:
+        if input.transition is not None:
+            self.recorder.record_case(
+                parent_id=input.transition.parent_id, transition=input.transition, case=input.case
+            )
+        else:
+            self.recorder.record_case(parent_id=None, transition=None, case=input.case)
+        self.control.record_step(input, self.recorder)
         return APIStateMachine._step(self, input=input)
 
     step_function.__name__ = name

schemathesis/specs/openapi/stateful/control.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from schemathesis.engine.recorder import ScenarioRecorder
+from schemathesis.generation.stateful.state_machine import DEFAULT_STATEFUL_STEP_COUNT
+
+if TYPE_CHECKING:
+    from requests.structures import CaseInsensitiveDict
+
+    from schemathesis.generation.stateful.state_machine import StepInput
+    from schemathesis.specs.openapi.stateful import ApiTransitions
+
+
+# It is enough to be able to catch double-click type of issues
+MAX_OPERATIONS_PER_SOURCE_CAP = 2
+# Maximum number of concurrent root sources (e.g., active users in the system)
+MAX_ROOT_SOURCES = 2
+
+
+def _get_max_operations_per_source(transitions: ApiTransitions) -> int:
+    """Calculate global limit based on number of sources to maximize diversity of used API calls."""
+    sources = len(transitions.operations)
+
+    if sources == 0:
+        return MAX_OPERATIONS_PER_SOURCE_CAP
+
+    # Total steps divided by number of sources, but never below the cap
+    return max(MAX_OPERATIONS_PER_SOURCE_CAP, DEFAULT_STATEFUL_STEP_COUNT // sources)
+
+
+@dataclass
+class TransitionController:
+    """Controls which transitions can be executed in a state machine."""
+
+    __slots__ = ("transitions", "max_operations_per_source", "statistic")
+
+    def __init__(self, transitions: ApiTransitions) -> None:
+        # Incoming & outgoing transitions available in the state machine
+        self.transitions = transitions
+        self.max_operations_per_source = _get_max_operations_per_source(transitions)
+        # source -> derived API calls
+        self.statistic: dict[str, dict[str, Counter[str]]] = {}
+
+    def record_step(self, input: StepInput, recorder: ScenarioRecorder) -> None:
+        """Record API call input."""
+        case = input.case
+
+        if (
+            case.operation.label in self.transitions.operations
+            and self.transitions.operations[case.operation.label].outgoing
+        ):
+            # This API operation has outgoing transitions, hence record it as a source
+            entry = self.statistic.setdefault(input.case.operation.label, {})
+            entry[input.case.id] = Counter()
+
+        if input.transition is not None:
+            # Find immediate parent and record as derived operation
+            parent = recorder.cases[input.transition.parent_id]
+            source = parent.value.operation.label
+            case_id = parent.value.id
+
+            if source in self.statistic and case_id in self.statistic[source]:
+                self.statistic[source][case_id][case.operation.label] += 1
+
+    def allow_root_transition(self, source: str, bundles: dict[str, CaseInsensitiveDict]) -> bool:
+        """Decide if this root transition should be allowed now."""
+        if len(self.statistic.get(source, {})) < MAX_ROOT_SOURCES:
+            return True
+
+        # If all non-root operations are blocked, then allow root ones to make progress
+        history = {name.split("->")[0].strip() for name, values in bundles.items() if values}
+        return all(
+            incoming.source.label not in history
+            or not self.allow_transition(incoming.source.label, incoming.target.label)
+            for transitions in self.transitions.operations.values()
+            for incoming in transitions.incoming
+            if transitions.incoming
+        )
+
+    def allow_transition(self, source: str, target: str) -> bool:
+        """Decide if this transition should be allowed now."""
+        existing = self.statistic.get(source, {})
+        total = sum(metric.get(target, 0) for metric in existing.values())
+        return total < self.max_operations_per_source