prettyplay 0.0.2__py3-none-any.whl

prettyplay/engine/steering/steering.py

@@ -0,0 +1,765 @@
+"""Interactive steering of a terminally stuck step: the engineer-in-the-loop REPL."""
+
+import contextlib
+import logging
+import tempfile
+from datetime import date
+from pathlib import Path
+
+from ...cache import CachedStep, StepCache, StepIdentity
+from ...config import Config
+from ...driver import PageFacade
+from ...failures import ComplianceVerdictError, IncurableStepError, LLMUnavailableError
+from ...llm import ComplianceFinding, LLMProvider, ScenarioStep
+from ...reporting import StepReporter
+from ..attempts import (
+    OUTCOME_COMPLIANCE_BLOCKED,
+    OUTCOME_EXECUTION_FAILED,
+    OUTCOME_FAILED_CHECK,
+    OUTCOME_REJECTED,
+    StepAttempt,
+)
+from ..compliance import check_step_compliance
+from ..execution import bind_step_inputs, run_step_code
+from ..renderer import PreparedStep, StepMemory, validate_step_result
+from ..text import format_step_error
+
+logger = logging.getLogger("prettyplay")
+
+#: System prompt of every guided regeneration request of the steering dialog.
+#: Frozen mirror of ``.goga/usages/prompts/step_generation.md`` (the section after
+#: the ``---`` separator) — the single source of the prompt; the constant changes
+#: only together with the file. A local copy of the engine constant, not an
+#: import: frozen mirrors stay cell-owned, no runtime read of ``.goga/`` ever
+#: happens.
+SYSTEM_PROMPT = """You generate executable Python code for one step of a web UI test.
+
+Input you receive:
+- STEP TYPE: action or assertion — the kind of the step
+- STEP: the prepared instruction of the step — the plain-text sentence with actual values embedded
+- INPUTS: the call input bindings, one name = value line each — present when the step carries inputs
+- RESULTS: the declared result names — present when the step declares captures; the code must return a dictionary of exactly these names to non-blank strings observed on the page
+- PREVIOUS STEPS: the sentences of the previous steps of the test, in order
+- PAGE SNAPSHOT: the accessibility snapshot of the current page
+- PAGE URL: the current URL of the page, when present
+- SCREENSHOT: an image of the page, when attached
+- CHEAT SHEET: a compact reference of useful Playwright sync API idioms — guidance, not an allowlist; everything standard stays allowed
+- USER INSTRUCTIONS: the project's binding code style guidance, when configured
+- HISTORY: the verbatim record of every attempt of this step so far, when present — the original cached code first when it exists; each record carries the attempt outcome, the URL before -> after line, the complete candidate code and the complete error
+- RECOMMENDATION: the diagnosis of the classification that preceded this regeneration, when present
+- USER GUIDANCE: the engineer guidance message of the interactive steering, when present
+
+Output exactly one Python code block with one function of the fixed form:
+
+- without RESULTS: def step(page) -> None: ...
+- with RESULTS: def step(page) -> dict[str, str] | None: ... — return the dictionary of exactly the declared names to values actually read from the current page
+
+Rules:
+- The function receives exactly one argument: the page — the genuine Playwright sync Page; the whole step runs inside the driver worker thread
+- The global `step_inputs` is supplied fresh on every execution: captured values are available by name and call-local INPUTS under `step_inputs["vars"]`. Read changing values from it instead of hardcoding the current STEP or INPUTS values into cached code
+- Import from playwright.sync_api and the Python standard library only — no third-party
+  libraries; imports are global only: at the top level of the code block, before `def
+  step`, never inside the function body
+- Work through the standard Playwright sync API: locator factories, actions, waits, expect chains, plain asserts on immediate reads — everything standard is allowed; the CHEAT SHEET is guidance, never a boundary
+- Assertions: for an assertion sentence end with a check — a waiting expect(...) chain for dynamic content, or an immediate read with a plain Python assert (assert locator.count() > 1)
+- When the request carries a RESULTS block: read every declared value from the current page — never fabricate, never reuse values from HISTORY; return all declared names in one dictionary; every value is a non-blank string; a missing observation fails the step rather than fabricating a value
+- No fixed delays, no sleeps, no wait_for_timeout — locators and expect chains auto-wait
+- The runtime owns the page lifecycle: never call page.close() or context.close()
+- No stateful actions that outlive the step on the page shared by the whole test: page.route, page.clock, add_init_script, tracing, HAR, CDP — excluded from generated code; a cached step would poison every later step far from the cause
+- Dialogs: capture with the stock means — with page.expect_event("dialog") as info: — perform the triggering action inside the block, read info.value.type, info.value.message, info.value.default_value, then info.value.accept() or info.value.dismiss()
+- Popups and new tabs: capture with with page.expect_popup() as popup_info: — trigger the opening action inside the block, work through popup_info.value; page.bring_to_front() raises a page above the others
+- Content inside an iframe goes through page.frame_locator(selector) — locate elements within the returned scope; nested frames chain
+- Scrolling: locator.scroll_into_view_if_needed() and page.mouse.wheel(dx, dy) are the standard means
+- The page state may already include the effects of prior attempts or manual intervention — the HISTORY records and their URL before -> after lines show what already happened. Regeneration after failed attempts never rides the leftover state of those attempts: an action step repeats its action through the page even when the page looks done. A first attempt — no HISTORY — works on the page the previous steps produced: the PAGE URL line and the snapshot show where they landed
+- An action step performs its action and ends there — no trailing check that confirms the action's own completion; the following steps of the test carry their own expectations
+- An assertion step only observes the current page — never navigate, click, type or fill; passive observation such as scroll_into_view_if_needed() stays allowed
+- RECOMMENDATION and USER GUIDANCE carry the diagnosis and the engineer's intent — follow them when they conflict with your first instinct
+- USER INSTRUCTIONS are binding for everything below the safety core of these Rules: follow them when configured; silently ignoring an instruction is a violation
+- The safety core of these Rules always outranks the instructions: the fixed function form, the import rule, the lifecycle rule, the stateful-action exclusions, no fixed delays. An instruction conflicting with a Rule or demanding a stateful action is unfollowable: never implement it silently — raise in the step code with the message "instruction conflicts with rule Y" naming the conflict, so the failure surfaces loudly
+- Prefer-type instructions are conditional by their own wording: follow them when the page offers the option — best-effort with a graceful fallback is compliance
+- The step must complete exactly what STEP says — nothing more, nothing less
+- Output only the code block, no explanations"""
+
+#: The compact standard Playwright sync API reference of every guided request;
+#: guidance, not an allowlist — everything standard stays allowed.
+#: Frozen mirror of ``.goga/usages/prompts/step_cheatsheet.md`` — the whole file, verbatim
+#: (the practice has no ``---`` separator, so the whole-file rule is the only mirror
+#: rule with no extraction logic to drift); the constant changes only together with
+#: the file. A local copy of the engine constant, not an import — the same
+#: frozen-mirror rule; no runtime read of ``.goga/`` ever happens.
+CHEAT_SHEET = """# Playwright cheat sheet
+
+The compact standard Playwright sync API reference carried by every step-code generation and regeneration request
+of prettyplay — referenced by the engine and steering cells as the `cheat_sheet` practice; rendered by the provider
+implementations as the leading CHEAT SHEET block of the user content. Guidance, not an allowlist: everything
+standard stays allowed — the error-driven regeneration loop is the second line of defense against hallucinated
+calls. Target audience: the generation model — a model that knows Playwright weakly writes a correct step from
+this reference alone.
+
+## Locator factories
+
+    page.get_by_role("button", name="Sign in")
+    page.get_by_label("Username")
+    page.get_by_text("Welcome back")
+    page.get_by_placeholder("Search")
+    page.get_by_alt_text("Logo")
+    page.get_by_title("Close")
+    page.get_by_test_id("submit")
+    page.locator("css selector | //xpath | [data-qa=row]")
+
+## Narrowing
+
+    locator.first / locator.last / locator.nth(2)
+    locator.filter(has_text="Product X")
+    locator.and_(other) / locator.or_(other)
+
+## Actions
+
+    .click() / .dblclick() / .click(button="right")
+    .fill("text") / .clear() / .press("Enter") / .press("Control+A")
+    .check() / .uncheck() / .hover() / .select_option("v")
+    .drag_to(target) / .set_input_files("path.png")
+
+## Navigation and waits
+
+    page.goto(url) / page.go_back() / page.go_forward() / page.reload()
+    page.wait_for_url("**/dashboard") / page.wait_for_load_state("networkidle")
+    page.url  # the current URL — an immediate read beside the waiting forms
+
+## Waiting assertions — expect chains
+
+    from playwright.sync_api import expect
+
+    expect(locator).to_be_visible() / to_be_hidden()
+    expect(locator).to_be_enabled() / to_be_checked()
+    expect(locator).to_have_text("...") / to_contain_text("...")
+    expect(locator).to_have_value("v") / to_have_attribute("href", "/docs")
+    expect(page).to_have_url("**/dashboard") / to_have_title("Dashboard")
+
+## Count forms — "the page shows a list of X"
+
+    items = page.get_by_role("listitem")
+    assert items.count() > 1
+
+An exact count: `expect(items).to_have_count(3)`. One check per meaning — a visibility expect
+plus a count assert on the same locator verifies one fact twice.
+
+## Immediate reads with plain asserts
+
+    assert locator.count() >= 1
+    assert "Dashboard" in page.title()
+    assert "/dashboard" in page.url
+
+## Dialogs
+
+    with page.expect_event("dialog") as info:
+        page.get_by_role("button", name="Delete").click()
+    dialog = info.value
+    dialog.type / dialog.message / dialog.default_value
+    dialog.accept() / dialog.dismiss() / dialog.accept("the answer")
+
+## Popups and new tabs
+
+    with page.expect_popup() as popup_info:
+        page.get_by_role("link", name="Open docs").click()
+    popup = popup_info.value
+    popup.bring_to_front()
+
+## Frames
+
+    frame = page.frame_locator("#checkout")
+    frame.get_by_role("button", name="Pay").click()
+
+## Scrolling
+
+    locator.scroll_into_view_if_needed()
+    page.mouse.wheel(0, 600)
+"""
+
+#: The local commands of the dialog — context services without an LLM request.
+_LOCAL_COMMANDS = frozenset({"snapshot", "screenshot", "error", "code"})
+
+#: The banner label column — every banner label aligns to the widest one,
+#: ``commands:``. The banner's own presentation padding; the render text
+#: inside stays unpadded.
+_BANNER_LABEL_WIDTH = len("commands:")
+
+#: Prefix of the temporary screenshot file of a dialog.
+_SCREENSHOT_PREFIX = "prettyplay-steering-"
+
+#: The explanation of the ``on_healed`` event of an interactively healed step.
+_HEALED_EXPLANATION = "healed interactively by engineer guidance"
+
+
+class StepSteering:
+    """Steers a terminally stuck step back to green through engineer-approved turns; no budget is ever consumed.
+
+    Attributes:
+        _config: project settings; the generation instructions and the
+            screenshot flag feed the guided requests.
+        _provider: the LLM port implementation of the guided requests.
+        _cache: the store the healed step is written back to.
+        _reporter: the visibility point of the healed step.
+        _screenshot_path: the path of the one temporary screenshot file of
+            the current dialog; ``None`` — the dialog took no screenshot
+            yet.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        provider: LLMProvider,
+        cache: StepCache,
+        reporter: StepReporter | None,
+    ) -> None:
+        """Keep the collaborators of the steering dialog.
+
+        Args:
+            config: project settings; ``generation_prompt`` renders into every
+                guided request, ``send_screenshots`` attaches page images.
+            provider: the LLM port implementation of the guided requests.
+            cache: the store the healed step is written back to.
+            reporter: the visibility point of the healed step; ``None`` — the
+                hook-less default reporter, so an omitted reporter never
+                breaks the healed-step report.
+        """
+        self._config = config
+        self._provider = provider
+        self._cache = cache
+        self._reporter = reporter if reporter is not None else StepReporter([])
+        self._screenshot_path: str | None = None
+
+    def steer(  # noqa: PLR0913, PLR0917 — the signature is fixed by the steering contract
+        self,
+        failure: IncurableStepError,
+        identity: StepIdentity,
+        prepared: PreparedStep,
+        step_type: str,
+        previous_steps: list[ScenarioStep],
+        group_prompt: str | None,
+        page: PageFacade,
+        attempt_history: list[StepAttempt],
+        memory: StepMemory,
+    ) -> CachedStep | None:
+        """Run the steering dialog over a terminal failure.
+
+        Args:
+            failure: the terminal failure about to propagate — the source of
+                the failed code, the underlying error and the verdict.
+            identity: the address of the stuck step — the healed step is
+                written back under it.
+            prepared: the render product of the stuck step — threaded from
+                the executor; the banner and every guided request carry the
+                prepared instruction with its INPUTS and RESULTS blocks; the
+                declared names gate the result of an approved turn.
+            step_type: action or assertion — carried into every guided
+                request and the gate verdict.
+            previous_steps: the typed scenario records of the previous steps
+                of the test — each the prepared instruction plus its
+                permanent group membership; carried into every guided
+                request unchanged, the provider renders the marked entries.
+            group_prompt: the group prompt of the stuck step's group;
+                ``None`` — an ordinary step, no group framing; non-empty —
+                every guided request of this dialog carries the group framing
+                (the GROUP PROMPT block before the scenario context, rendered
+                by the provider).
+            page: the live page facade of the test.
+            attempt_history: the shared per-step attempt history grown by
+                the engine loops and anchored by record 0 — rendered into
+                every guided request; the dialog appends every completed
+                turn to it.
+            memory: the test memory — the publication point of the accepted
+                turn; the validated captures of a green turn publish with
+                its write-back, after the compliance gate.
+
+        Returns:
+            The healed cached step on a successful approved turn; ``None`` —
+            the dialog was declined or died: the caller propagates the
+            original failure. Every completed turn appends one record into
+            the shared history; a green turn validates its result and passes
+            the compliance gate before the publication and the write-back —
+            a high finding never reaches the cache.
+
+        Raises:
+            KeyboardInterrupt: a SIGINT outside the prompts and the approval
+                gate escapes directly — never swallowed into a turn or a
+                heal.
+        """
+        self._screenshot_path = None  # a fresh dialog owns no screenshot file yet
+        self._render_banner(failure, prepared.instruction, page)
+        logger.info("steering_opened", extra={"step_text": prepared.instruction})
+
+        while True:
+            message = self._await_guidance(failure, prepared.instruction, page)
+            if message is None:  # quit, EOF, SIGINT or an unreadable stdin — declined
+                return None
+
+            logger.info("steering_guidance", extra={"guidance": message})
+            print("regenerating with USER GUIDANCE")
+
+            try:
+                code = self._guided_request(
+                    prepared, step_type, previous_steps, group_prompt, page, message, attempt_history
+                )
+            except LLMUnavailableError as outcome:
+                print(f"provider unavailable: {outcome}")
+                return None
+
+            try:
+                approved = self._confirm_run(code)
+            except (EOFError, KeyboardInterrupt, OSError):  # a dead approval prompt declines the dialog
+                logger.info("steering_declined", extra={"step_text": prepared.instruction})
+                return None
+
+            if not approved:  # the code never runs — one read, the same URL on both sides
+                url = self._guarded_url(page) or ""
+                attempt_history.append(_record(code, "", OUTCOME_REJECTED, url, url))
+                continue
+
+            url_before = self._guarded_url(page) or ""
+            try:
+                with bind_step_inputs(memory.snapshot(), prepared.inputs):
+                    result = run_step_code(code, page)  # bare — the settle window never re-arms inside the dialog
+            except Exception as outcome:  # a red turn returns to the prompt, never escapes
+                print(f"turn failed: {outcome}")
+                url_after = self._guarded_url(page) or ""
+                attempt_history.append(
+                    _record(code, format_step_error(outcome), _outcome_label(outcome), url_before, url_after)
+                )
+                continue
+            url_after = self._guarded_url(page) or ""
+
+            # the deterministic result gate: an approved green turn is accepted only by a
+            # validated result — a violation is a red turn of the identical failed-check channel
+            captures, violation_text = _validated_captures(prepared, result)
+
+            if violation_text is not None:
+                print(f"turn failed: {violation_text}")
+                attempt_history.append(_record(code, violation_text, OUTCOME_FAILED_CHECK, url_before, url_after))
+                continue
+
+            # the gate sits outside the execution try/except: its hard failures end the
+            # dialog, they never degrade into a red turn of the executed candidate; the
+            # history it judges holds every prior turn — the candidate rides the CODE block
+            try:
+                findings = check_step_compliance(
+                    self._config,
+                    self._provider,
+                    prepared,
+                    step_type,
+                    code,
+                    attempt_history,
+                )
+            except (LLMUnavailableError, ComplianceVerdictError) as gate_failure:
+                print(f"compliance gate failed: {gate_failure}")
+                logger.warning(
+                    "compliance gate failed",
+                    extra={"step_text": prepared.instruction, "gate_failure": str(gate_failure)},
+                )
+                return None  # the green candidate stays unchecked — the original failure propagates
+
+            high = _high_finding(findings)
+            if high is not None:  # the violation never reaches the cache — steer the fix
+                violation = f"{high.dimension} violation: {high.instruction} — {high.explanation}"
+                print(f"compliance violation — not written back: {violation}")
+                attempt_history.append(_record(code, violation, OUTCOME_COMPLIANCE_BLOCKED, url_before, url_after))
+                continue
+
+            _medium_warning(prepared.instruction, findings)  # medium and low findings are visible, never blocking
+
+            memory.publish(captures)  # publication rides the acceptance — after validation and the gate
+            return self._write_back(prepared.instruction, identity, code)
+
+    def _render_banner(self, failure: IncurableStepError, instruction: str, page: PageFacade) -> None:
+        """Render the context banner of the dialog.
+
+        Args:
+            failure: the terminal failure the dialog opens over — the source
+                of the failed code and the terminal render.
+            instruction: the prepared instruction of the stuck step — the
+                banner header names it; the raw template sentence never
+                reaches the dialog surface.
+            page: the live page facade of the test.
+        """
+        print(f'── step "{instruction}" — about to raise IncurableStepError ──')
+        print(_banner_line("code:", failure.code))
+        print(_banner_line("error:", str(failure)))
+
+        url = self._guarded_url(page)
+
+        if url is not None:
+            print(_banner_line("url:", url))
+
+        path = self._screenshot_file(page)
+
+        if path is not None:
+            print(_banner_line("shot:", path))
+
+        print(_banner_line("commands:", "snapshot | screenshot | error | code | quit"))
+
+    def _confirm_run(self, code: str) -> bool:
+        """Show the complete generated code and read the strict approval answer.
+
+        Args:
+            code: the complete generated step code of this turn.
+
+        Returns:
+            ``True`` — a bare ``y`` approved the execution; ``False`` — any
+            other answer: the candidate reaches the live page only through
+            this gate.
+
+        Raises:
+            EOFError: the approval prompt hit the end of the input.
+            KeyboardInterrupt: a SIGINT arrived at the approval prompt.
+            OSError: the approval prompt cannot read stdin at all.
+        """
+        print("generated code:")
+        print(code)
+
+        return input("run? [y/N] ").strip() == "y"
+
+    def _guarded_url(self, page: PageFacade) -> str | None:
+        """Read the current URL; a failed interaction degrades to None.
+
+        Args:
+            page: the live page facade of the test.
+
+        Returns:
+            The current URL of the page; ``None`` when the read failed —
+            its failure text was printed.
+        """
+        try:
+            return page.url
+        except Exception as failure:  # a dead page never kills the dialog
+            print(f"url unavailable: {failure}")
+            return None
+
+    def _await_guidance(self, failure: IncurableStepError, instruction: str, page: PageFacade) -> str | None:
+        """Read guidance lines until one is a real guidance message.
+
+        Args:
+            failure: the terminal failure the dialog opens over.
+            instruction: the prepared instruction of the stuck step — the
+                decline log names it.
+            page: the live page facade of the test.
+
+        Returns:
+            The raw guidance message; ``None`` — quit, EOF, SIGINT or an
+            unreadable stdin ended the dialog declined. Blank lines
+            re-prompt; local commands serve the context.
+        """
+        while True:
+            message = self._read_guidance(instruction)
+            if message is None:
+                return None
+
+            command = message.strip()
+            if not command:  # blank line — re-prompt, no LLM request, no history
+                continue
+            if command in _LOCAL_COMMANDS:
+                self._serve_local_command(command, failure, page)
+                continue
+
+            return message
+
+    def _read_guidance(self, instruction: str) -> str | None:
+        """Read one guidance line from the prompt.
+
+        Args:
+            instruction: the prepared instruction of the stuck step — the
+                decline log names it.
+
+        Returns:
+            The raw guidance message; ``None`` — quit, EOF, SIGINT or an
+            unreadable stdin ended the dialog declined.
+        """
+        try:
+            message = input("guidance> ")
+        except (EOFError, KeyboardInterrupt, OSError):  # an unreadable stdin (captured CI) declines like EOF
+            logger.info("steering_declined", extra={"step_text": instruction})
+            return None
+
+        if message.strip() == "quit":
+            logger.info("steering_declined", extra={"step_text": instruction})
+            return None
+
+        return message
+
+    def _serve_local_command(self, command: str, failure: IncurableStepError, page: PageFacade) -> None:
+        """Serve one local context command without an LLM request.
+
+        Args:
+            command: the command name — one of snapshot, screenshot, error,
+                code.
+            failure: the terminal failure the dialog opens over.
+            page: the live page facade of the test.
+        """
+        if command == "snapshot":
+            print("snapshot:")
+            print(self._guarded_snapshot(page))
+            return
+        if command == "screenshot":
+            path = self._screenshot_file(page)
+            if path is not None:
+                print(path)
+            return
+        if command == "error":
+            print(f"error:    {failure.error}")
+            return
+
+        print("code:")  # the code command — the last of the fixed set
+        print(failure.code)
+
+    def _guided_request(  # noqa: PLR0913, PLR0917 — the fixed request inputs of the port signature
+        self,
+        prepared: PreparedStep,
+        step_type: str,
+        previous_steps: list[ScenarioStep],
+        group_prompt: str | None,
+        page: PageFacade,
+        guidance: str,
+        attempt_history: list[StepAttempt],
+    ) -> str:
+        """Run one guided regeneration request against the provider.
+
+        Args:
+            prepared: the render product of the stuck step — the prepared
+                instruction rides the request with its INPUTS and RESULTS
+                blocks; the raw template sentence never reaches the request.
+            step_type: action or assertion — carried into the request.
+            previous_steps: the typed scenario records of the previous steps
+                of the test — carried unchanged.
+            group_prompt: the group prompt of the stuck step's group;
+                ``None`` — an ordinary step, no group framing.
+            page: the live page facade of the test.
+            guidance: the engineer guidance message of this turn.
+            attempt_history: the shared per-step attempt history — rendered
+                record by record into the HISTORY block of the request;
+                record 0 anchors the original failure.
+
+        Returns:
+            The generated step code of the fixed form — the fresh page state
+            plus the render product and the step type compose the request;
+            the guidance message rides the USER GUIDANCE block.
+
+        Raises:
+            LLMUnavailableError: the provider request failed; the caller ends
+                the dialog.
+        """
+        screenshot = self._guarded_screenshot_bytes(page) if self._config.send_screenshots else None
+
+        return self._provider.generate_step_code(
+            prompt=SYSTEM_PROMPT,
+            user_instructions=self._config.generation_prompt,
+            instruction=prepared.instruction,
+            step_type=step_type,
+            previous_steps=previous_steps,
+            group_prompt=group_prompt,
+            inputs=prepared.inputs,
+            declarations=prepared.declarations,
+            snapshot=self._guarded_snapshot(page),
+            page_url=self._guarded_url(page),
+            screenshot=screenshot,
+            cheat_sheet=CHEAT_SHEET,
+            attempt_history=[record.render() for record in attempt_history],
+            recommendation=None,  # the verdict diagnosis is banner-only — the live guidance replaces it
+            guidance=guidance,
+        )
+
+    def _write_back(self, instruction: str, identity: StepIdentity, code: str) -> CachedStep:
+        """Write the proven guided step back to the cache and report it healed.
+
+        Args:
+            instruction: the prepared instruction of the stuck step — the
+                healed event names it.
+            identity: the address of the stuck step.
+            code: the step code that just worked on the live page.
+
+        Returns:
+            The healed cached step, already stored and reported.
+        """
+        step = CachedStep(
+            identity=identity,
+            code=code,
+            created_at=date.today().isoformat(),  # noqa: DTZ011 — calendar date of the healed step
+        )
+        stored = self._cache.save(step)
+
+        self._reporter.emit("on_healed", {"step_text": instruction, "explanation": _HEALED_EXPLANATION})
+
+        if stored:
+            print("step green — healed step written to the cache")
+        else:  # the skip reason rides the on_cache_skipped event — the console line never claims a write that failed
+            print("step green — cache write skipped (best-effort cache)")
+
+        return step
+
+    def _guarded_snapshot(self, page: PageFacade) -> str:
+        """Read the accessibility snapshot; a failed interaction degrades to empty.
+
+        Args:
+            page: the live page facade of the test.
+
+        Returns:
+            The full accessibility snapshot; empty when the interaction
+            failed — its failure text was printed.
+        """
+        try:
+            return page.aria_snapshot()
+        except Exception as failure:  # a dead page never kills the dialog
+            print(f"snapshot unavailable: {failure}")
+            return ""
+
+    def _screenshot_file(self, page: PageFacade) -> str | None:
+        """Write a full PNG to the one temporary file of the dialog; return its path.
+
+        Args:
+            page: the live page facade of the test.
+
+        Returns:
+            The path of the written file — one file per dialog, overwritten
+            by every later screenshot; ``None`` when the interaction failed.
+        """
+        path = self._screenshot_path
+        fresh = path is None  # the first screenshot of the dialog allocates the one file
+
+        try:
+            png = page.screenshot()
+
+            if fresh:
+                with tempfile.NamedTemporaryFile(prefix=_SCREENSHOT_PREFIX, suffix=".png", delete=False) as target:
+                    path = target.name
+                    target.write(png)
+            else:  # every later screenshot of the dialog overwrites the one file
+                Path(path).write_bytes(png)
+        except Exception as failure:  # a dead page never kills the dialog
+            if fresh and path is not None:
+                with contextlib.suppress(OSError):
+                    Path(path).unlink()  # a partial write leaves nothing worth inspecting
+            print(f"screenshot unavailable: {failure}")
+            return None
+
+        self._screenshot_path = path
+        return path
+
+    def _guarded_screenshot_bytes(self, page: PageFacade) -> bytes | None:
+        """Read the screenshot bytes of a guided request; a failed interaction degrades to None.
+
+        Args:
+            page: the live page facade of the test.
+
+        Returns:
+            The full-page PNG bytes; ``None`` when the interaction failed —
+            its failure text was printed.
+        """
+        try:
+            return page.screenshot()
+        except Exception as failure:  # a dead page never kills the dialog
+            print(f"screenshot unavailable: {failure}")
+            return None
+
+
+def _high_finding(findings: list[ComplianceFinding]) -> ComplianceFinding | None:
+    """Return the first high finding of a gate verdict — either dimension blocks.
+
+    Args:
+        findings: the findings of the verdict, in the verdict's own ordering.
+
+    Returns:
+        The first finding of priority high, or ``None`` when the verdict
+        holds none — the guidance prompt reopens and the next candidate is
+        gated anew.
+    """
+    return next((finding for finding in findings if finding.priority == "high"), None)
+
+
+def _medium_warning(instruction: str, findings: list[ComplianceFinding]) -> None:
+    """Log the medium and low findings a green turn passed with.
+
+    A verdict without findings warns nothing — the clean pass stays quiet.
+
+    Args:
+        instruction: the prepared instruction of the gated step.
+        findings: the non-blocking findings of both dimensions of the verdict.
+    """
+    if not findings:
+        return
+
+    logger.warning(
+        "compliance findings passed",
+        extra={
+            "step_text": instruction,
+            "findings": [
+                f"{finding.priority} {finding.dimension}: {finding.instruction} — {finding.explanation}"
+                for finding in findings
+            ],
+        },
+    )
+
+
+def _outcome_label(outcome: BaseException) -> str:
+    """Pick the outcome label of a red turn by its exception kind.
+
+    Args:
+        outcome: the exception the executed candidate raised.
+
+    Returns:
+        The failed-check label for an ``AssertionError``, the
+        execution-failed label for every other failure.
+    """
+    return OUTCOME_FAILED_CHECK if isinstance(outcome, AssertionError) else OUTCOME_EXECUTION_FAILED
+
+
+def _record(code: str, error: str, outcome: str, url_before: str, url_after: str) -> StepAttempt:
+    """Compose one verbatim attempt record — the shape every turn-append site shares.
+
+    Args:
+        code: the complete candidate code of the turn.
+        error: the complete failure text of the turn; empty on no error.
+        outcome: the outcome label constant of the turn.
+        url_before: the page URL read immediately before the turn's execution.
+        url_after: the page URL read immediately after the turn's execution.
+
+    Returns:
+        The immutable record appended to the shared per-step attempt history.
+    """
+    return StepAttempt(code=code, error=error, outcome=outcome, url_before=url_before, url_after=url_after)
+
+
+def _validated_captures(prepared: PreparedStep, result: object) -> tuple[dict[str, str], str | None]:
+    """Validate the returned result of an approved green turn against the render product.
+
+    Args:
+        prepared: the render product of the stuck step — the declaration set
+            the returned result must satisfy.
+        result: the step function's return, passed through by the run
+            primitive.
+
+    Returns:
+        The validated captures with no violation; an empty captures with the
+        formatted deterministic violation text when the result contract
+        failed — the violation joins the failed-check channel of the dialog.
+    """
+    try:
+        return validate_step_result(prepared, result), None
+    except AssertionError as violation:
+        return {}, format_step_error(violation)
+
+
+def _banner_line(label: str, text: str) -> str:
+    """Align one banner label with its value text.
+
+    Args:
+        label: the banner label including its colon.
+        text: the value text of the line; its continuation lines indent to
+            the value column.
+
+    Returns:
+        The aligned banner line with its continuation lines — the label pads
+        to the label column, multi-line values indent to the value column.
+    """
+    value_column = " " * (_BANNER_LABEL_WIDTH + 1)
+    head, *tail = text.splitlines() or [""]  # an empty value renders its label alone
+    lines = [f"{label.ljust(_BANNER_LABEL_WIDTH)} {head}", *(value_column + line for line in tail)]
+
+    return "\n".join(line.rstrip() for line in lines)