prettyplay 0.0.0__py3-none-any.whl

prettyplay/engine/.usages/healing.md

@@ -0,0 +1,31 @@
+# Step healing
+
+Domain: healing a failed cached step. Audience: library internals and engineers reasoning about healed runs.
+
+## Heal
+
+```python
+healed = healer.heal(
+    step=failed_step, error="element not found: button «Sign in»", previous_steps=["open the login page"], page=page
+)
+```
+
+The classification verdict decides the path:
+
+| Category | Path |
+|---|---|
+| rot | regenerate from the current page within the healing budget (default 2), execute, save back to the cache, report loudly |
+| product_defect | raise ProductDefectError carrying the verdict — category, explanation and recommendation all reach the exception message, the on_step_verdict hook and the log |
+| incurable | raise IncurableStepError carrying the verdict; the reason names the incurability cause |
+
+## Rules
+
+- Anti-masking: healing never turns a product defect into a green test
+- The healed code replaces the cached code only after a successful execution
+- Generation and healing attempts live in one per-test registry — owned by the runtime of the test — with separate per-step limits (default 3 and 2)
+- A regeneration budget exhaustion after rot raises IncurableStepError carrying the verdict of the original rot classification — no extra LLM request
+- Provider unavailability during the classification raises LlmUnavailableError — an explicit infrastructure failure
+
+## Verdicts
+
+Every terminal failure carries its verdict in full: the exception message starts with the primary reason and appends the verdict render; the same three fields reach on_step_verdict and the structured log record.

prettyplay/engine/CODEMANIFEST

@@ -0,0 +1,215 @@
+Imports:
+  - Types:
+      - Config
+    From: prettyplay/config
+  - Types:
+      - StepReporter
+    From: prettyplay/reporting
+  - Types:
+      - ProductDefectError
+      - IncurableStepError
+      - LlmUnavailableError
+      - FailureVerdict
+    From: prettyplay/failures
+  - Types:
+      - PageFacade
+    Usages:
+      - facade
+    From: prettyplay/driver
+  - Types:
+      - StepCache
+      - StepIdentity
+      - CachedStep
+      - RunBudgets
+    From: prettyplay/cache
+  - Types:
+      - LlmProvider
+      - FailureClassification
+    Usages:
+      - classification
+    From: prettyplay/llm
+
+Usages:
+  conventions: .goga/usages/conventions.md
+  system_prompt: |
+    You generate executable Python code for one step of a web UI test.
+
+    Input you receive:
+    - STEP: the step sentence in a natural language
+    - PREVIOUS STEPS: the sentences of the previous steps of the test, in order
+    - PAGE SNAPSHOT: the accessibility snapshot of the current page
+    - SCREENSHOT: an image of the page, when attached
+    - PAGE API: the exact surface listing of the page facade — call nothing outside it
+    - USER INSTRUCTIONS: the project's code style guidance, when configured
+    - CODE: the existing step code that failed (regeneration requests only)
+    - ERROR: the failure description of the existing code (regeneration requests only)
+
+    Output exactly one Python code block with one function of the fixed form:
+
+    def step(page) -> None:
+        ...
+
+    Rules:
+    - The function receives exactly one argument: the page facade. Never import anything, never use other libraries
+    - Work only through the page API: the request carries the exact surface listing of the page facade — call nothing outside it
+    - For an assertion sentence end with an expectation call; for an action sentence perform the actions
+    - Locating by role and accessible name is preferred; by visible text next; by label for form fields
+    - Attribute, CSS and XPath locating exist for elements without accessible names — the accessibility-first priority stands unless USER INSTRUCTIONS say otherwise
+    - Scroll abilities exist for scenario scrolling: bring an element into view, scroll by an amount, to the page end or start, inside a scrollable container
+    - No fixed delays, no sleeps, no explicit waits — the facade waits itself
+    - The step must complete exactly what STEP says — nothing more, nothing less
+    - Output only the code block, no explanations
+  classification_prompt: |
+    You classify a failure of a web UI test step.
+
+    Input you receive:
+    - STEP: the step sentence
+    - CODE: the step code that failed
+    - ERROR: the failure description
+    - PAGE SNAPSHOT: the accessibility snapshot of the current page
+    - SCREENSHOT: an image of the page, when attached
+
+    Answer with exactly one line of the form:
+    category | explanation | recommendation
+
+    where category is one of:
+    - rot — the UI changed (selectors, texts, structure) and the step can be regenerated for the same intent
+    - product_defect — the step works as written but the expected behavior of the application is genuinely broken
+    - incurable — the step sentence no longer matches reality, the intent is ambiguous, or regeneration cannot help
+
+    explanation: one short sentence why. recommendation: one short sentence what the engineer should do.
+    Output only that single line — no code, no extra text.
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `facade` from Imports for the page API the generated code works through.
+  Use `classification` from Imports for the healing decision categories.
+  Use `system_prompt` as the system prompt of every code generation request.
+  Use `classification_prompt` as the system prompt of every failure classification request.
+  Use `facade` from Imports as the single source of the page API surface for generation requests.
+
+  The fixed form of step code: one function receiving exactly one argument — the `PageFacade` of the test; the function body works only through `PageFacade` and the LocatorFacade element API.
+  Every attempt — generation or healing — consumes the shared per-step budget of the test; exhaustion is the incurable failure, never an infinite loop.
+  Healing never masks a product defect: a classified product_defect fails the test loudly; a healed step is reported loudly and written back to the cache.
+  Every terminal failure carries a verdict — a `FailureVerdict` of category, explanation, recommendation — fully present in the exception message, the verdict hook event and the log; an unavailable LLM skips the verdict quietly with a WARNING, the failure itself is never delayed or distorted — the quiet skip applies to verdicts enriching an already-decided failure; the classification driving the healing decision surfaces as the infrastructure failure.
+  A failed check of a candidate stops the generation retries: a check that executed and did not hold is classified, not regenerated.
+  The page API surface listing sent to the provider mirrors `facade` from Imports exactly — the listing and the practice change together.
+  The user instructions of the project settings — the generation_prompt field of `Config` — reach generation and regeneration requests only; classification requests never carry them; the instructions take no part in the step address: a cached step never regenerates because the instructions changed.
+
+---
+
+"StepGenerator(config: Config, provider: LlmProvider, cache: StepCache, budgets: RunBudgets, reporter: StepReporter)":
+  location: generator.py
+  annotations: |
+    The generation engine: produce working step code for an unknown step, executing candidates against the live page.
+
+    `config`: project settings — the screenshot flag and the generation instructions.
+    `provider`: the LLM port.
+    `cache`: the step cache — a generated step is stored on success.
+    `budgets`: the per-test attempt registry.
+    `reporter`: the visibility point.
+  methods:
+    "generate(identity: StepIdentity, step_text: str, previous_steps: list[str], page: PageFacade) -> step: CachedStep": |
+      Generate and store a new step.
+
+      Algorithm:
+      1. Ask the budgets registry try_generation for the step identity; a refused attempt is the incurable failure
+      2. Collect the request inputs: the page accessibility snapshot, the step sentence, `previous_steps`, and the page API surface from `facade`; add the page screenshot when the project settings enable screenshots
+      3. Request step code from the provider port generate_step_code passing `system_prompt` as the system prompt, the page API surface listing taken from `facade`, and the user instructions — the effective config generation_prompt — when non-empty
+      4. Execute the candidate with `run_step_code` against `page`
+      5. On success: build `CachedStep`, save it to the cache, return it
+      6. On a candidate failure that is an AssertionError — a check that executed and did not hold: stop the retries immediately and classify via `classify_step_failure`; a product_defect verdict raises `ProductDefectError` carrying the verdict, any other verdict raises `IncurableStepError` carrying it — the reason names the failed candidate check; provider unavailability at this classification is skipped quietly with a WARNING — `IncurableStepError` is raised without a verdict, the reason naming the failed candidate check (the failed check is the primary signal, the verdict is enrichment)
+      7. On any other candidate failure: repeat from step 1 with the fresh failure description and the fresh snapshot, while attempts remain
+      8. On budget exhaustion: classify the last candidate via `classify_step_failure` and raise `IncurableStepError` carrying the verdict — the reason names the exhausted pool and the last candidate failure; provider unavailability at this classification is skipped quietly with a WARNING, the failure raises without a verdict
+      9. Report on_generation_started for every attempt
+
+      Requirements:
+      - Every generation request carries the exact page API surface taken from `facade` from Imports: the model always sees the precise list of calls it may use
+      - Provider unavailability of a generation request surfaces as `LlmUnavailableError` immediately — no retry on it
+      - Provider unavailability of a failed-check classification is skipped quietly with a WARNING: the failure raises without a verdict — the failed check itself is the primary signal
+      - Exactly one failed check stops the retries: the attempt budget is never spent on a legitimately failing assertion
+      - A verdict requested on this path fully reaches the raised error
+    "regenerate(identity: StepIdentity, step_text: str, previous_steps: list[str], page: PageFacade, existing_code: str, error: str) -> step: CachedStep": |
+      Regenerate a failed step for healing.
+
+      Algorithm:
+      1. The same loop as the generate method with three additions: every provider request carries `existing_code` and `error` and the user instructions — the effective config generation_prompt — when non-empty; attempts consume the healing budget via try_healing; a budget exhaustion raises `IncurableStepError` without classification — the healer attaches the verdict of its own classification, no extra LLM request is made (the failed-check classification of the generate loop applies on both pools)
+
+"run_step_code(code: str, page: PageFacade)":
+  location: execution.py
+  annotations: |
+    Execute step code of the fixed form against the page facade of the test.
+
+    `code`: the step code text.
+    `page`: the page facade of the current test.
+
+    Algorithm:
+    1. Compile and load `code` as a module in an isolated namespace
+    2. Resolve the step function of the fixed form — the single callable receiving the page facade
+    3. Call it with `page`
+
+    Requirements:
+    - A failure inside the step code propagates to the caller as-is: the engine classifies it, this routine never swallows or retries
+    - Executing step code loads no LLM provider and touches no network beyond the page itself
+
+    Constraints:
+    - Execute only step code produced by generation or loaded from the cache — never arbitrary file content
+
+"classify_step_failure(config: Config, provider: LlmProvider, step_text: str, code: str, error: str, page: PageFacade) -> classification: FailureClassification":
+  location: classification.py
+  annotations: |
+    Classify a step failure: collect the page state and ask the provider — the single classification call for both engines.
+
+    `config`: project settings — the screenshot flag.
+    `provider`: the LLM port.
+    `step_text`: the sentence of the failed step.
+    `code`: the step code that failed.
+    `error`: the human-readable failure description.
+    `page`: the page facade of the current test.
+    `classification`: the `FailureClassification` verdict.
+
+    Algorithm:
+    1. Collect the classification inputs: the step sentence, the failed code, the `error` text, the fresh page snapshot — plus the screenshot when enabled
+    2. Ask the provider port classify_failure passing `classification_prompt` as the system prompt
+    3. Return the verdict
+
+    Constraints:
+    - Provider unavailability propagates to the caller: this routine never swallows it — the calling path decides whether it is a terminal infrastructure failure or a quiet verdict skip
+
+"StepHealer(config: Config, provider: LlmProvider, generator: StepGenerator, cache: StepCache, budgets: RunBudgets, reporter: StepReporter)":
+  location: healer.py
+  annotations: |
+    The healing engine: classify a failed cached step, regenerate rot, never mask a defect.
+
+    `config`: project settings — the screenshot flag.
+    `provider`: the LLM port for classification.
+    `generator`: the regeneration engine.
+    `cache`: the step cache for the healed write-back.
+    `budgets`: the per-test attempt registry.
+    `reporter`: the visibility point.
+  methods:
+    "heal(step: CachedStep, error: str, previous_steps: list[str], page: PageFacade) -> step: CachedStep": |
+      Classify and heal a failed cached step.
+
+      `previous_steps`: the sentences of the previous steps of the test, in execution order — scenario context for regeneration.
+
+      Algorithm:
+      1. Classify the failure via `classify_step_failure` — the verdict is a `FailureClassification`
+      2. Report on_healing_started with the category
+      3. product_defect: raise `ProductDefectError` carrying the verdict built from the classification — the message states what was expected against what was observed; the recommendation reaches the error through the verdict
+      4. incurable: raise `IncurableStepError` carrying the verdict; the reason names the classification explanation of incurability
+      5. rot: regenerate via the generator regenerate — its loop executes the candidate and stores the healed step on success; report on_healed with the explanation of what was rot and what changed, return the healed step
+      6. A regeneration budget exhaustion inside step 5 surfaces as `IncurableStepError` carrying the verdict of the step 1 classification — the reason names the exhausted pool; no extra LLM request is made
+      7. Provider unavailability of the classification surfaces as `LlmUnavailableError` — an explicit infrastructure failure
+
+      Requirements:
+      - Anti-masking: healing may only turn a rot-failed step green; a classified product defect always fails the test
+      - The healed code replaces the cached code only after a successful execution
+      - Every verdict produced on the paths of this method fully reaches the raised error
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The agent engine of prettyplay: step code generation with execution in the loop and failed-check classification, the fixed-form execution routine, the shared classification call, and healing with anti-masking and verdicts on terminal failures.

prettyplay/engine/__init__.py

@@ -0,0 +1,8 @@
+"""Facade of the prettyplay.engine cell: generation, execution and healing of step code."""
+
+from .classification import classify_step_failure
+from .execution import run_step_code
+from .generator import StepGenerator
+from .healer import StepHealer
+
+__all__ = ["StepGenerator", "StepHealer", "classify_step_failure", "run_step_code"]

prettyplay/engine/classification.py

@@ -0,0 +1,69 @@
+"""The shared classification call: collect the page state and ask the provider."""
+
+from ..config import Config
+from ..driver import PageFacade
+from ..llm import FailureClassification, LlmProvider
+
+#: System prompt of every classification request; used by both engines, applied verbatim.
+CLASSIFICATION_PROMPT = """You classify a failure of a web UI test step.
+
+Input you receive:
+- STEP: the step sentence
+- CODE: the step code that failed
+- ERROR: the failure description
+- PAGE SNAPSHOT: the accessibility snapshot of the current page
+- SCREENSHOT: an image of the page, when attached
+
+Answer with exactly one line of the form:
+category | explanation | recommendation
+
+where category is one of:
+- rot — the UI changed (selectors, texts, structure) and the step can be regenerated for the same intent
+- product_defect — the step works as written but the expected behavior of the application is genuinely broken
+- incurable — the step sentence no longer matches reality, the intent is ambiguous, or regeneration cannot help
+
+explanation: one short sentence why. recommendation: one short sentence what the engineer should do.
+Output only that single line — no code, no extra text."""
+
+
+def classify_step_failure(  # noqa: PLR0913, PLR0917 — the parameter list is fixed by the engine contract
+    config: Config,
+    provider: LlmProvider,
+    step_text: str,
+    code: str,
+    error: str,
+    page: PageFacade,
+) -> FailureClassification:
+    """Classify a step failure: collect the page state and ask the provider.
+
+    The single classification call for both engines — the generator failed-check
+    stop and exhaustion, the healer verdict. Provider unavailability propagates
+    to the caller: this routine never swallows it — the calling path decides
+    whether it is a terminal infrastructure failure or a quiet verdict skip.
+
+    Args:
+        config: project settings; ``send_screenshots`` attaches page images.
+        provider: the LLM port implementation classifying the failure.
+        step_text: the sentence of the failed step.
+        code: the step code that failed.
+        error: the human-readable failure description.
+        page: the page facade of the current test.
+
+    Returns:
+        The classification verdict.
+
+    Raises:
+        LlmUnavailableError: the provider service failed; the calling path
+            decides the handling.
+    """
+    snapshot = page.aria_snapshot()
+    screenshot = page.screenshot() if config.send_screenshots else None
+
+    return provider.classify_failure(
+        prompt=CLASSIFICATION_PROMPT,
+        step_text=step_text,
+        code=code,
+        error=error,
+        snapshot=snapshot,
+        screenshot=screenshot,
+    )

prettyplay/engine/execution.py

@@ -0,0 +1,25 @@
+"""Execution of step code of the fixed form against the page facade of the test."""
+
+from ..driver import PageFacade
+
+
+def run_step_code(code: str, page: PageFacade) -> None:
+    """Execute step code of the fixed form against the page facade of the test.
+
+    The code is compiled and loaded in an isolated namespace; the step
+    function of the fixed form — the single callable named ``step`` — is
+    resolved and called with the page facade. A failure inside the step code
+    propagates to the caller as-is: the engine classifies it, this routine
+    never swallows or retries. No module is registered in ``sys.modules`` and
+    no provider or network beyond the page itself is touched.
+
+    Args:
+        code: the step code text produced by generation or loaded from the cache.
+        page: the page facade of the current test.
+    """
+    namespace: dict[str, object] = {}
+    # the engine contract: exec of the fixed-form step code in an isolated namespace
+    exec(compile(code, "<prettyplay-step>", "exec"), namespace)
+
+    fn = namespace["step"]
+    fn(page)

prettyplay/engine/generator.py

@@ -0,0 +1,318 @@
+"""Generation of working step code: LLM candidates executed against the live page in a loop."""
+
+import logging
+from datetime import date
+
+from ..cache import CachedStep, RunBudgets, StepCache, StepIdentity
+from ..config import Config
+from ..driver import PageFacade
+from ..failures import FailureVerdict, IncurableStepError, LlmUnavailableError, ProductDefectError
+from ..llm import FailureClassification, LlmProvider
+from ..reporting import StepReporter
+from .classification import classify_step_failure
+from .execution import run_step_code
+from .text import first_line_short
+
+logger = logging.getLogger("prettyplay")
+
+#: System prompt of every generation request; applied verbatim by the provider.
+SYSTEM_PROMPT = """You generate executable Python code for one step of a web UI test.
+
+Input you receive:
+- STEP: the step sentence in a natural language
+- PREVIOUS STEPS: the sentences of the previous steps of the test, in order
+- PAGE SNAPSHOT: the accessibility snapshot of the current page
+- SCREENSHOT: an image of the page, when attached
+- PAGE API: the exact surface listing of the page facade — call nothing outside it
+- USER INSTRUCTIONS: the project's code style guidance, when configured
+- CODE: the existing step code that failed (regeneration requests only)
+- ERROR: the failure description of the existing code (regeneration requests only)
+
+Output exactly one Python code block with one function of the fixed form:
+
+def step(page) -> None:
+    ...
+
+Rules:
+- The function receives exactly one argument: the page facade. Never import anything, never use other libraries
+- Work only through the page API: the request carries the exact surface listing of the page facade — call nothing outside it
+- For an assertion sentence end with an expectation call; for an action sentence perform the actions
+- Locating by role and accessible name is preferred; by visible text next; by label for form fields
+- Attribute, CSS and XPath locating exist for elements without accessible names — the accessibility-first priority stands unless USER INSTRUCTIONS say otherwise
+- Scroll abilities exist for scenario scrolling: bring an element into view, scroll by an amount, to the page end or start, inside a scrollable container
+- No fixed delays, no sleeps, no explicit waits — the facade waits itself
+- The step must complete exactly what STEP says — nothing more, nothing less
+- Output only the code block, no explanations"""
+
+#: Frozen surface listing of the driver facade — the only calls step code may make.
+#: Mirrors ``prettyplay/driver/.usages/facade.md`` verbatim; the driver facade is a
+#: backward-compatibility contract, so this constant changes only together with it.
+#: ``close()`` stays out: it is a runtime method of PrettyTest, not of step code.
+PAGE_API_SURFACE = """page.open(url)                    — navigate and wait for load
+page.find_by_role(role, name)     — element by aria role and accessible name
+page.find_by_label(label)         — element by associated label
+page.find_by_text(text)           — element by visible text
+page.find_by_attribute(name, value) — element by attribute value — data-* attributes
+page.find_by_css(selector)        — element by CSS selector
+page.find_by_xpath(xpath)         — element by XPath expression
+page.aria_snapshot()              — accessibility-tree page state
+page.screenshot()                 — full-page PNG bytes
+page.url                          — current URL
+page.scroll_to_element(element)            — bring an element into the viewport (works inside scrollable ancestors)
+page.scroll_down(pixels)                   — scroll the page down by an amount
+page.scroll_up(pixels)                     — scroll the page up by an amount
+page.scroll_to_bottom()                    — scroll to the end of the page
+page.scroll_to_top()                       — scroll to the start of the page
+page.scroll_into_view(element, container)  — bring an element into view inside a specific scrollable container
+page.scroll_container_down(container, pixels) — scroll a scrollable container down by an amount
+page.scroll_container_up(container, pixels)   — scroll a scrollable container up by an amount
+element.click()                   — click with auto-wait
+element.fill(value)               — set input text
+element.select_option(value)      — choose an option
+element.expect_visible()          — assert visible
+element.expect_text(text)         — assert text
+element.expect_enabled()          — assert enabled"""
+
+
+class StepGenerator:
+    """Generates working step code by executing LLM candidates against the live page.
+
+    Each attempt is one provider request: the generator snapshots the page,
+    asks for code of the fixed form, and immediately executes the candidate.
+    A failing candidate is retried as a regeneration request carrying the code
+    and its error, until one candidate works or the attempt budget of the step
+    runs out. Only a proven candidate is cached — failures are never stored.
+
+    Attributes:
+        _config: project settings; the screenshot flag feeds the requests.
+        _provider: the LLM port implementation doing the requests.
+        _cache: the store where working steps are saved.
+        _budgets: the per-test attempt registry of the engine.
+        _reporter: the visibility point for generation and cache events.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        provider: LlmProvider,
+        cache: StepCache,
+        budgets: RunBudgets,
+        reporter: StepReporter,
+    ) -> None:
+        """Keep the collaborators of the generation loop.
+
+        Args:
+            config: project settings; ``send_screenshots`` attaches page images.
+            provider: the LLM port implementation.
+            cache: the store of working steps.
+            budgets: the per-test attempt registry.
+            reporter: the visibility point for engine events.
+        """
+        self._config = config
+        self._provider = provider
+        self._cache = cache
+        self._budgets = budgets
+        self._reporter = reporter
+
+    def generate(
+        self,
+        identity: StepIdentity,
+        step_text: str,
+        previous_steps: list[str],
+        page: PageFacade,
+    ) -> CachedStep:
+        """Generate step code until a candidate works, then cache it.
+
+        Args:
+            identity: the address of the step.
+            step_text: the sentence of the step.
+            previous_steps: the sentences of the previous steps of the test.
+            page: the live page facade the candidates run against.
+
+        Returns:
+            The cached step holding the proven code.
+
+        Raises:
+            IncurableStepError: the generation attempt budget is exhausted.
+            LlmUnavailableError: the provider service failed; no retry.
+        """
+        return self._loop(identity, step_text, previous_steps, page, "generation", None, None)
+
+    def regenerate(  # noqa: PLR0913, PLR0917 — the signature is fixed by the engine contract
+        self,
+        identity: StepIdentity,
+        step_text: str,
+        previous_steps: list[str],
+        page: PageFacade,
+        existing_code: str,
+        error: str,
+    ) -> CachedStep:
+        """Regenerate step code starting from the failed candidate.
+
+        The loop is the generation loop; the differences are the healing budget
+        pool and the failed code and error carried by the first request.
+
+        Args:
+            identity: the address of the step.
+            step_text: the sentence of the step.
+            previous_steps: the sentences of the previous steps of the test.
+            page: the live page facade the candidates run against.
+            existing_code: the cached step code that failed.
+            error: the failure description of the existing code.
+
+        Returns:
+            The cached step holding the proven regenerated code.
+
+        Raises:
+            IncurableStepError: the healing attempt budget is exhausted.
+            LlmUnavailableError: the provider service failed; no retry.
+        """
+        return self._loop(identity, step_text, previous_steps, page, "healing", existing_code, error)
+
+    def _loop(  # noqa: PLR0913, PLR0917 — the shared attempt loop with its fixed inputs
+        self,
+        identity: StepIdentity,
+        step_text: str,
+        previous_steps: list[str],
+        page: PageFacade,
+        pool: str,
+        existing_code: str | None,
+        error: str | None,
+    ) -> CachedStep:
+        """Run the shared attempt loop until a candidate works or the budget runs out.
+
+        A failed check — a candidate ``AssertionError`` — stops the retries at
+        once and is classified: the attempt budget is never spent on a
+        legitimately failing assertion. Any other candidate failure is retried
+        as a regeneration request carrying the code and its error. When the
+        budget runs out, the generation pool classifies the last candidate;
+        the healing pool raises without classification — the healer attaches
+        the verdict it already holds, so no extra LLM request is made.
+
+        Args:
+            identity: the address of the step.
+            step_text: the sentence of the step.
+            previous_steps: the sentences of the previous steps of the test.
+            page: the live page facade the candidates run against.
+            pool: the budget pool name — "generation" or "healing".
+            existing_code: the failed code of the first request, if any.
+            error: the failure description of the first request, if any.
+
+        Returns:
+            The cached step holding the proven code.
+
+        Raises:
+            ProductDefectError: a failed candidate check classified as a
+                genuine product defect.
+            IncurableStepError: the attempt budget of the step is exhausted,
+                or a failure classified as incurable.
+            LlmUnavailableError: the provider service failed; no retry.
+        """
+        attempt = 0
+        code = None
+        spend = self._budgets.try_generation if pool == "generation" else self._budgets.try_healing
+
+        while True:
+            if not spend(identity):
+                # candidate cause is part of the reason contract: «the specific incurability cause»
+                reason = f"{pool} attempt budget exhausted"
+
+                if error:
+                    reason = f"{reason}; last failure: {error}"
+                if pool == "healing":
+                    raise IncurableStepError(
+                        step_text,
+                        reason,
+                        None,  # healer attaches the verdict — no second LLM request
+                    )
+                if error is None:
+                    raise IncurableStepError(
+                        step_text,
+                        reason,
+                        None,  # nothing to classify: no candidates existed
+                    )
+
+                raise IncurableStepError(step_text, reason, self._classify(step_text, code, error, page))
+
+            attempt += 1
+            self._reporter.emit("on_generation_started", {"step_text": step_text, "attempt": attempt})
+
+            snapshot = page.aria_snapshot()
+            screenshot = page.screenshot() if self._config.send_screenshots else None
+
+            code = self._provider.generate_step_code(
+                prompt=SYSTEM_PROMPT,
+                user_instructions=self._config.generation_prompt,
+                step_text=step_text,
+                previous_steps=previous_steps,
+                snapshot=snapshot,
+                screenshot=screenshot,
+                page_api=PAGE_API_SURFACE,
+                existing_code=existing_code,
+                error=error,
+            )
+
+            try:
+                run_step_code(code, page)
+            except AssertionError as check_failure:
+                # failed check: attempts not spent — classify and stop
+                reason = f"candidate check failed: {first_line_short(check_failure)}"
+                verdict = self._classify(step_text, code, reason, page)
+                if verdict is not None and verdict.category == "product_defect":
+                    raise ProductDefectError(step_text, first_line_short(check_failure), verdict) from None
+                raise IncurableStepError(step_text, reason, verdict) from None
+            except Exception as candidate_error:  # other candidate failures heal via retry
+                existing_code = code
+                error = first_line_short(candidate_error)
+            else:
+                break
+
+        step = CachedStep(
+            identity=identity,
+            code=code,
+            created_at=date.today().isoformat(),  # noqa: DTZ011 — calendar date of step creation
+        )
+        self._cache.save(step)
+
+        return step
+
+    def _classify(self, step_text: str, code: str | None, error: str, page: PageFacade) -> FailureVerdict | None:
+        """Classify a failure through the shared routine with the quiet skip.
+
+        Every classification inside the loop enriches an already-decided
+        failure, so an unavailable LLM yields no verdict — the failure never
+        waits for it and never turns into an infrastructure error.
+
+        Args:
+            step_text: the sentence of the failed step.
+            code: the code of the last candidate.
+            error: the failure description of the candidate.
+            page: the live page facade of the test.
+
+        Returns:
+            The verdict of the classification, or ``None`` when the LLM was
+            unavailable — the quiet skip logs a WARNING.
+        """
+        try:
+            classification = classify_step_failure(self._config, self._provider, step_text, code, error, page)
+        except LlmUnavailableError:
+            logger.warning("verdict skipped: llm unavailable")
+            return None
+
+        return _verdict(classification)
+
+
+def _verdict(classification: FailureClassification) -> FailureVerdict:
+    """Build the verdict value object carried by the terminal errors.
+
+    Args:
+        classification: the classification verdict of the provider.
+
+    Returns:
+        The frozen verdict of the terminal failure.
+    """
+    return FailureVerdict(
+        category=classification.category,
+        explanation=classification.explanation,
+        recommendation=classification.recommendation,
+    )