prettyplay 0.0.2__py3-none-any.whl

prettyplay/.usages/lifecycle.md

@@ -0,0 +1,117 @@
+# Run lifecycle
+
+Domain: how a run is composed — runtimes, contexts, hooks, failures, strict mode, polling, steering. Audience: integrators wiring the library into a runner and CI.
+
+## Composition
+
+One runtime per test: each PrettyPlay builds its own runtime — its own configuration, browser process, LLM provider and attempt budgets. Tests never share browser state or budgets through the library; outcomes do not depend on the execution order. Constructing a test is cheap and requires no LLM credentials: the browser starts lazily on the first step. A config passed to the test overrides only the explicitly set values — everything else resolves from pyproject+env; the override reaches inside the nested browser group. When the process exits, every runtime stops its browser and driver synchronously before returning control to the terminal — scripts never leave browser processes behind.
+
+```python
+from prettyplay import BrowserConfig, PrettyConfig, PrettyPlay
+
+# a strict run with a fullscreen browser
+test = PrettyPlay(
+    cache_key="login",
+    config=PrettyConfig(
+        strict=True,
+        browser=BrowserConfig(screen="fullscreen", headless=False),
+    ),
+)
+
+# a local generation session with polling and steering
+test = PrettyPlay(
+    cache_key="login",
+    config=PrettyConfig(polling_timeout=8.0, interactive=True),
+)
+```
+
+## Wiring into a framework
+
+The library is framework-agnostic: no plugins, no base classes. Construct the object in your test, call the step methods, let failures propagate — the runner counts them as ordinary test failures. A few lines of glue are enough; the suite runs by the standard runner command.
+
+## Strict mode — replay-only CI runs
+
+`strict = true` (env PRETTYPLAY_STRICT, per-test override) turns the run into an honest replay: cached code executes exactly as stored and nothing is ever (re)generated. Settle polling still applies to cached code — re-executing it is execution, not generation.
+
+- A cache miss fails the step as IncurableStepError stating that strict mode forbids generation — an expected CI signal: generating a step is a deliberate non-strict act
+- A failed cached step is classified when LLM access is configured: product_defect raises ProductDefectError, rot/fixable/incurable raises IncurableStepError — never regenerated
+- Without LLM access the failure raises immediately by step type — an assertion step raises ProductDefectError, an action step raises IncurableStepError — each carrying the full underlying error; a WARNING is logged
+- Classifications are the only LLM calls; generation and healing budgets are never consumed
+
+Team workflow: generate locally where the LLM is reachable, commit the cache directory, run CI fully from the cache with no LLM keys — optionally with strict=true for guaranteed replay-only behavior.
+
+Template steps replay like any cached step: captures re-read from the current page, results validate and publish
+on the strict path exactly as on the ordinary replay; strict adds no generation, healing or new checks.
+
+## Settle polling
+
+`polling_timeout` (default None — off; 0 — explicit disable) opens one settle window per step execution, measured
+from the first execution of the step's code: a transient failure of a pollable kind re-executes the same code after
+`polling_delay` (default 0.5 s) until success or window end. Re-executions appear as settle_retry log records; no LLM
+budget is consumed. Locator ambiguity and Python-level errors of the step code never poll.
+
+## Interactive steering
+
+`interactive = true` (env PRETTYPLAY_INTERACTIVE, per-test override) arms the steering REPL for local generation
+sessions: when a step terminally fails with IncurableStepError, a terminal dialog opens — step, failed code, the
+terminal error render, the current page URL, a screenshot path, the commands — and every engineer message drives one
+regeneration whose complete code is shown for approval with run? [y/N] before it executes against the live page. A
+green turn heals the step and writes it back to the cache — only after the instruction compliance gate
+passes (a high finding never reaches the cache: the violation joins the history and the prompt reopens);
+quit/EOF/SIGINT/unreadable stdin raises the
+original terminal failure. The dialog opens only on IncurableStepError of a non-strict run — an LLMUnavailableError
+leaving the engine never reaches it (with a dead provider the dialog still opens and its local commands work; the
+first guidance message then declines and the original failure propagates) — and consumes no budgets.
+Keep it off in CI — an accidentally opened dialog would hang the run.
+
+## Group recovery
+
+Steps inside a group fail differently: on a non-strict run every failure that would be classified
+and healed per-step triggers one group-level diagnosis instead — the classification model sees the
+group prompt, every step's outcome and URL transition, and the current page. recoverable → the
+affected row regenerates and re-executes automatically (per-step cache write-back, loud
+reporting); product_defect → the test fails loudly. The recovery budget: every new cycle grants
+each row step a fresh healing counter, the number of cycles per group is capped by
+healing_attempts. Strict mode never recovers groups; a terminally failed group step still reaches
+the steering dialog with the group context available.
+
+## Hooks
+
+Implement the StepHooks callback contract and register the implementation — either pass the list to the keyword-only constructor parameter `hooks` (events are captured from the very construction) or call add_hooks before the first step. Step, generation, healing, cache and verdict events reach the handler synchronously. on_step_failed carries the full rendered failure message; on_step_verdict fires after it whenever the terminal failure carries an LLM verdict; on_step_finished closes every step exactly once, passed or failed. A group block frames itself with the four group lifecycle events — on_group_started on entry, then on_group_passed (a recovered group reports passed) or on_group_failed, and the closing on_group_finished exactly once. In strict mode generation and healing events never fire.
+
+## Failures
+
+Five kinds reach the runner:
+
+| Kind | Meaning | Reaction |
+|---|---|---|
+| ProductDefectError | a real regression — also an AssertionError: runners show a failure, not an error; the traceback is folded to the library boundary; aria-snapshot tails are removed from single-string exception arguments in the chain, preserving exception identities and links; other argument shapes and custom message rendering are outside this guarantee | treat as a bug — this failure is the value of the suite |
+| IncurableStepError | the step cannot be generated or healed — in strict mode also: the cache miss | follow the carried recommendation |
+| LLMUnavailableError | the LLM is down | only generation and healing are blocked; cached steps keep running |
+| ComplianceVerdictError | the instruction compliance gate could not obtain a usable verdict — the executed candidate is never cached unchecked | rerun the step to retry generation; a repeatedly malformed verdict points at the verdict model |
+| ConfigurationError | the settings are invalid | fix the named setting — the message lists the allowed values |
+
+ProductDefectError and IncurableStepError render one structured message — the first line
+with the class name of the terminal failure and the authored reason, the `---` separated step/error section, the
+conditional received/cause/Call log details section and the unpadded verdict block — and the same text reaches the
+exception message, the on_step_failed hook event and the log. When the LLM is unavailable the verdict is skipped quietly; the failure itself never waits for it.
+
+## Interactive sessions (IPython, Jupyter)
+
+The Playwright session lives in a background driver thread owned by the library: the thread that executes the steps never holds a running asyncio loop, so interactive hosts that drive their own prompt through asyncio (IPython, Jupyter) keep working after every step — passed or failed.
+
+The author escape hatch run_on_page crosses the same worker boundary the same way: the author callable executes wholly inside the worker thread with the genuine Page — the host thread keeps driving its own prompt loop.
+
+Each test owns its browser process: it starts on the first step of the test and stops when the test closes. In scripts every runtime stops automatically at process exit through its atexit hook. In an interactive session the process keeps living between cells, so close the test object explicitly when the interactive exploration is over:
+
+```python
+from prettyplay import PrettyPlay
+
+test = PrettyPlay("login-flow")
+test.step("open the login page")
+test.step("enter the login and password")
+test.expect("the «Welcome back» message appears")
+test.close()  # stops this test's browser and driver thread
+```
+
+Generation of the step cache remains a batch workflow: prefer a plain script or a pytest run over a REPL when generating many steps. The `interactive` setting of the previous section is a different thing entirely: it is the steering dialog of a stuck step, not a host mode.

prettyplay/.usages/steps.md

@@ -0,0 +1,169 @@
+# Writing steps
+
+Domain: authoring UI tests as plain sentences. Audience: engineers writing tests and integrators wiring the library into a test framework.
+
+## A test as a scenario
+
+```python
+from prettyplay import PrettyPlay
+
+
+def test_login():
+    t = PrettyPlay("login-flow")
+    t.step("open the login page")
+    t.step("enter the login and password")
+    t.step("click the «Sign in» button")
+    t.expect("the «Welcome back» message appears")
+    t.close()
+```
+
+Or with the context manager:
+
+```python
+with PrettyPlay("login-flow") as t:
+    t.step("open the login page")
+```
+
+## Step kinds
+
+- step(text) — performs what the sentence says
+- expect(text) — verifies what the sentence says; a legitimately failed expectation fails the test as a product defect
+
+## Step parameters
+
+- step(text, tries=3) — the total number of executions of the step's code (the first included);
+  replaces the time-bounded settle window for that step; the global polling settings stay
+  untouched; absorbed retries appear as settle_retry records only, the step stays green
+- step(text, delay=1.5) — a quiet pause in seconds before the step's code runs: the started event
+  fires, the declared seconds pass, then the code; a step never reached never pauses
+- step(text, vars={"expected": "Details"}) — the call-local string inputs; separate namespace from memory
+- The optional tries, delay and vars parameters are keyword-only and accepted by both step kinds; invalid values (zero/negative
+  tries, negative delay) and non-string vars values fail loudly at the call
+
+## Templates and step memory
+
+Capture an observation, navigate, verify — ordinary step and expect calls plus explicit template syntax:
+
+```python
+with PrettyPlay("item-name") as t:
+    t.step("Open https://shop.example/products")
+    t.step("Read the first item name into {% var name %}")
+    t.step("Open the item named {{ name }}")
+    t.expect("The page contains {{ name }}")
+```
+
+- `{% var name %}` declares where the step saves text read from the page; once the step is accepted, `name` is
+  available in later templates
+- Several captures in one step publish together — `t.step("Read the first item name into {% var first_name %} and
+  the second item name into {% var second_name %}")`; a successful recapture replaces the previous value; a failed
+  step publishes nothing
+- Memory survives navigation and belongs to one test execution — never shared across tests, concurrent runs included
+- A same-step read observes the previous value or fails with the unavailable name; use two steps to capture then use
+- Templates are ordinary Python strings — f-strings evaluate before PrettyPlay receives them
+
+Call-local inputs through the reserved `vars` namespace:
+
+```python
+t.expect("The page contains {{ name }} and {{ vars.expected }}", vars={"expected": "Details"})
+```
+
+- `{{ name }}` reads memory, `{{ vars.name }}` reads the call input — separate namespaces, neither overwrites the
+  other; call inputs never establish memory; values are strings only
+- Standard Jinja stays available (filters, conditions, `set` — template-local); missing values fail loudly naming
+  the name; author-written `| default(...)` and `is defined` behave as authored
+
+## Literal Jinja in existing sentences
+
+```python
+t.expect("The page contains {% raw %}{{ name }}{% endraw %}")
+```
+
+## Cache and replay limitation
+
+- Template sentences address the cache by their source: `{{ name }}` and `{{ Name }}` are different steps; runtime
+  values never enter the address
+- Cached code re-reads captures from the current page on every execution — a changed item name for the same
+  operation replays without regeneration
+- Accepted limitation: a template that changes the operation itself may let old cached code succeed at the previous
+  operation without triggering healing
+
+## Groups
+
+```python
+with t.group("accept cookies, fill and submit the order form") as g:
+    g.step("accept the cookie banner")
+    g.step("fill the email field", delay=0.5)
+    g.step("submit the form")
+    g.expect("the status shows order confirmed", tries=2)
+```
+
+- The group block is one coherent mini-scenario with a shared goal; inside, steps use the ordinary
+  authoring surface — retry count and start pause included
+- The block frames itself with the four group lifecycle events — on_group_started on entry, then
+  on_group_passed/on_group_failed and the closing on_group_finished on exit; a recovered group
+  reports passed
+- An empty group prompt fails loudly at entry; a group with zero steps emits only the group lifecycle events
+- Group membership changes no step's cache address: cached group steps replay as ordinary steps —
+  no LLM calls, strict replay-only included
+- On a non-strict run a failing group step is diagnosed with the whole group in view and the
+  affected row is regenerated and re-executed automatically — a product defect fails loudly,
+  recovery never loops forever
+- Group pace and pause: `with t.group("…", speed=30, delay=2) as g:` slows the pauses between the
+  group's steps (the same percent→pause mapping as the browser speed setting) and waits the
+  declared seconds before the group's first step — quiet, library-level pauses
+
+## The honest step context
+
+The step cycle carries an honest context window end to end: every generation, healing and
+steering request receives the step type (action or assertion), the prepared instruction with its input bindings and
+result declarations, and the verbatim per-step attempt history — every prior candidate
+with its outcome, its URL before -> after line, its complete code and complete error, the
+original cached code anchored first. The cache write is guarded by a two-dimension gate —
+instruction compliance and step adequacy — so a cached step contains the action the
+sentence asks for, not a check of an already-achieved state. All of this is internal: the
+authoring surface uses step() and expect() with optional vars; cache addressing uses the original
+template source.
+
+## Author page access
+
+The excluded-from-generation stateful actions are performed explicitly by the author — the callable runs wholly
+inside the driver worker thread and receives the genuine sync Page:
+
+    with PrettyPlay("videos-flow") as t:
+        t.step("open the videos page")
+        t.run_on_page(lambda page: page.route("**/api/videos", lambda route: route.fulfill(json={"items": []})))
+        t.expect("the page shows a list of videos")
+
+- Requires an opened page: call it after the first step — a loud error otherwise
+- The callable returns plain data; Playwright objects (locators, handles, pages, contexts) never cross back to the calling thread
+- Prompt rules do not bind the author: page.route, page.clock, tracing, HAR, CDP are the author's explicit tools
+- The callable must use the page API only — calling back into the test object (a step, a screenshot, a nested
+  run_on_page) re-enters the worker thread the action itself runs on and is rejected with a loud error instead of a
+  deadlock
+- The callable runs sequentially with the steps — the shared worker takes one unit at a time
+
+## Screenshots
+
+Two author-facing abilities on the test object:
+
+```python
+with PrettyPlay("login-flow") as t:
+    t.step("open the login page")
+    png = t.get_screenshot()  # full-page PNG bytes of the current state
+    t.save_screenshot("artifacts/home.png")  # write full-page PNG to an explicit path
+```
+
+- Both require an opened page: call them after the first step of the test
+- Nothing is captured automatically on failures — attaching screenshots to reports is the author's decision
+
+## Addressing
+
+The constructor arguments form the cache address: cache_key (mandatory) and cache_path (optional subdirectory). Equal cache keys in the shared root reuse one cached step across tests; a different language, step type or key is a different step. User instructions (generation_prompt, classification_prompt) take no part in the address — a cached step never regenerates because the instructions changed. Replayed cached code is never re-checked against the current instructions: purge the cache manually after changing them. The attempt history and the honest request inputs take no part in the address either.
+
+## What you see
+
+Step sentences go to the logger prettyplay at info level — the suite output reads as a plain-language scenario. A failed step renders one structured message — the first line with the class name of the terminal failure and the authored reason, the `---` separated step/error section, the conditional received/cause/Call log details section and the unpadded verdict block — identical in the runner output, the log and the on_step_failed hook. Every step ends with one closing on_step_finished event (passed or failed). Healing, cache writes and skipped writes are reported loudly through the same logger. Transient failures absorbed by the settle window appear as settle_retry records — the step itself stays green.
+
+## Limitations
+
+Step sentences land in the repository cache, the logs and the LLM requests: never put secrets or personal data into a step.

prettyplay/__init__.py

@@ -0,0 +1,18 @@
+"""Facade of the prettyplay root: the composition root of the library."""
+
+from .config import BrowserConfig, PrettyConfig
+from .executor import StepExecutor
+from .groups import StepGroup
+from .reporting import StepHooks
+from .runtime import PrettyplayRuntime
+from .scenario import PrettyPlay
+
+__all__ = [  # noqa: RUF022 — the facade listing order is fixed by the root cell contract
+    "PrettyPlay",
+    "StepHooks",
+    "PrettyConfig",
+    "BrowserConfig",
+    "PrettyplayRuntime",
+    "StepExecutor",
+    "StepGroup",
+]

prettyplay/cache/.usages/addressing.md

@@ -0,0 +1,44 @@
+# Step addressing
+
+Domain: step identity and addressing of the cache. Audience: engineers reasoning about step reuse and inspecting the repository cache.
+
+## Identity triple
+
+| Component | Source | Effect on identity |
+|---|---|---|
+| cache_key | the main object constructor argument | a different key — a different step |
+| step type | action vs assertion | the same sentence as action and as assertion — two steps |
+| normalized sentence | templates: NFC + trim (verbatim); ordinary: NFC, trim, whitespace collapse, casefold — a template addresses by its source; an ordinary sentence casefolds as before | «Click Sign in» equals «click  sign in »; a Russian sentence and its English translation are different steps |
+
+A missing cache entry for the computed address is a cache miss — the step is generated, not an error.
+
+## Template sentences
+
+A sentence containing Jinja markers (`{{`, `{%` or `{#`) is a template step:
+
+```python
+normalize_step_text("Read the first item name into {% var name %}")
+# NFC + trim only — case-sensitive names and expression whitespace stay significant
+```
+
+- `{{ name }}` and `{{ Name }}` are different steps — Jinja names are case-sensitive
+- Two templates differing only by prose case or spacing do not share an entry — a fresh generation, never a wrong hit
+- Runtime values never enter the address: the same template with different observed values reuses the same cached code, which re-reads captures on every execution
+
+## Normalize and address
+
+```python
+from prettyplay.cache import StepIdentity, normalize_step_text
+
+normalized = normalize_step_text("  Click   Sign In ")
+identity = StepIdentity(
+    cache_key="login-flow",
+    step_type="action",
+    normalized_text=normalized,
+)
+# identity.filename — the deterministic digest of the triple
+```
+
+## Layout
+
+The cache root defaults to <cwd>/.prettyplay/cache/ — the working directory of the run — and is set by cache_root. The optional subdirectory argument is part of the address: steps never leak across subdirectories; without a subdirectory, equal cache keys are reused across tests. One .py file per step.

prettyplay/cache/.usages/budgets.md

@@ -0,0 +1,51 @@
+# Attempt budgets
+
+Domain: generation and healing attempt budgets. Audience: engineers tuning budgets and reasoning about budget exhaustion.
+
+## Consume attempts
+
+```python
+from prettyplay.cache import RunBudgets
+
+budgets = RunBudgets(generation_limit=3, healing_limit=2)
+
+if budgets.try_generation(identity):
+    ...  # attempt allowed; False — budget exhausted, the caller reports incurability
+```
+
+## Semantics
+
+- Budgets are per step per test: every test owns its registry and starts with full limits — a step reused across tests gets a fresh budget in each test (N tests running one step in a process spend N × attempts in total)
+- Defaults: 3 generation attempts, 2 healing attempts — configurable in the project settings
+- An exhausted budget is the incurable failure, never an infinite loop
+- Budgets exist only in the memory of the running process — nothing is persisted
+
+## Healing-funded regenerations
+
+Two verdict-driven regenerations are paid from the healing budget via `try_healing`, exactly one each:
+
+- generation-budget exhaustion with a rot or fixable verdict grants one extra recommendation-carrying regeneration; a repeat failure is terminal — no reclassification
+- a failed candidate check (generation loop) classified rot or fixable gets one recommendation-carrying regeneration before the final terminal-kind classification
+
+A refused `try_healing` — the healing budget already exhausted — leaves the failure terminal: no unfunded regeneration ever runs.
+
+Settle re-executions of the same code never consume budgets — re-execution is execution, not generation. Interactive steering attempts never consume budgets either: the human in the loop is the bound.
+
+## Recovery budgets (groups)
+
+The group recovery engine draws on the same registry with two group-scoped operations:
+
+```python
+if budgets.open_group_cycle(group_key=group_prompt):
+    for step_identity in row:
+        budgets.refresh_healing(step_identity)  # a fresh full healing counter per cycle
+```
+
+- `open_group_cycle(group_key)` — consume one recovery cycle of the group; False — the per-group
+  cycle cap (the `healing_attempts` value) is exhausted → the terminal incurable failure
+- `refresh_healing(identity)` — at every new cycle each row step gets a fresh full healing
+  counter, so a second attempt is never starved by the first
+
+Ordinary per-step healing keeps its per-test pools unchanged. Row regenerations pay from the
+healing budget via the ordinary `try_healing`. Group cycle counters live only in the memory of the
+running process, like every budget.

prettyplay/cache/.usages/storage.md

@@ -0,0 +1,32 @@
+# Cache storage
+
+Domain: reading and writing the step cache. Audience: engineers inspecting cache files and building tooling around the store.
+
+## Read and write
+
+```python
+from prettyplay.cache import CachedStep, StepCache
+from prettyplay.config import Config
+from prettyplay.reporting import StepReporter
+
+cache = StepCache(config=Config(), path="checkout", reporter=StepReporter(hooks=[]))
+
+step = cache.load(identity)  # None on a cache miss
+if step is None:
+    # a miss means: generate the step, then store it
+    cache.save(CachedStep(identity=identity, code=step_code, created_at="2026-09-07"))
+```
+
+## File format
+
+Each file carries the metadata fields (step sentence, cache key, step type, creation date), then the `# --- step code ---` sentinel line, then the generated step code — top-level imports when present, then the fixed-form `def step` function, restored verbatim on load. Files carry no library version and are never invalidated by a library upgrade.
+
+## Write behavior
+
+- save never fails the run: a read-only cache or a busy Windows target skips the write loudly — save returns whether the step was stored (False on a skip; the on_cache_skipped hook carries the reason)
+- writes are atomic: a unique temporary file in the target directory, then an atomic replace; the last writer wins, a partial file never becomes visible
+- load always works, in every environment
+
+## Team workflow
+
+Generate locally where the LLM is reachable → commit the cache directory → CI runs the whole suite from the cache with no LLM keys at all.

prettyplay/cache/__init__.py

@@ -0,0 +1,8 @@
+"""Facade of the prettyplay.cache cell: repository step cache and addressing."""
+
+from .budgets import RunBudgets
+from .models import CachedStep, StepIdentity
+from .store import StepCache
+from .text import normalize_step_text
+
+__all__ = ["CachedStep", "RunBudgets", "StepCache", "StepIdentity", "normalize_step_text"]

prettyplay/cache/budgets.py

@@ -0,0 +1,93 @@
+"""Per-test attempt registry: how many tries a step still has in this test."""
+
+from .models import StepIdentity
+
+
+class RunBudgets:
+    """The per-test registry of generation and healing attempts per step — nothing persisted, process memory only.
+
+    Attributes:
+        _generation_limit: how many generation attempts a step may take per test.
+        _healing_limit: how many healing attempts a step may take per test.
+        _generation_used: attempts already spent per step in the generation pool.
+        _healing_used: attempts already spent per step in the healing pool.
+        _group_cycles_used: recovery cycles already opened per group in this test.
+    """
+
+    def __init__(self, generation_limit: int, healing_limit: int) -> None:
+        """Init the registry with separate generation and healing limits.
+
+        Args:
+            generation_limit: the per-step generation attempt limit of the test.
+            healing_limit: the per-step healing attempt limit of the test.
+        """
+        self._generation_limit = generation_limit
+        self._healing_limit = healing_limit
+        self._generation_used: dict[str, int] = {}
+        self._healing_used: dict[str, int] = {}
+        self._group_cycles_used: dict[str, int] = {}
+
+    def try_generation(self, identity: StepIdentity) -> bool:
+        """Spend one generation attempt of the step or refuse on exhaustion.
+
+        Args:
+            identity: the address of the step asking for an attempt.
+
+        Returns:
+            True when the attempt is granted and counted, False when the
+            per-test generation budget of the step is exhausted.
+        """
+        used = self._generation_used.get(identity.filename, 0)
+        if used >= self._generation_limit:
+            return False
+
+        self._generation_used[identity.filename] = used + 1
+
+        return True
+
+    def try_healing(self, identity: StepIdentity) -> bool:
+        """Spend one healing attempt of the step or refuse on exhaustion.
+
+        Args:
+            identity: the address of the step asking for an attempt.
+
+        Returns:
+            True when the attempt is granted and counted, False when the
+            per-test healing budget of the step is exhausted.
+        """
+        used = self._healing_used.get(identity.filename, 0)
+        if used >= self._healing_limit:
+            return False
+
+        self._healing_used[identity.filename] = used + 1
+
+        return True
+
+    def refresh_healing(self, identity: StepIdentity) -> None:
+        """Grant the step a fresh full healing counter.
+
+        Args:
+            identity: the address of the row step — the recovery refreshes
+                every row step at each new cycle; other steps' pools stay
+                untouched.
+        """
+        self._healing_used[identity.filename] = 0
+
+    def open_group_cycle(self, group_key: str) -> bool:
+        """Spend one recovery cycle of the group or refuse on exhaustion — the loop is never infinite.
+
+        Args:
+            group_key: the key of the group — its group prompt.
+
+        Returns:
+            True when a new cycle is open and counted, False when the
+            per-test cycle cap of the group (the healing limit) is
+            exhausted.
+        """
+        used = self._group_cycles_used.get(group_key, 0)
+        if used >= self._healing_limit:
+            return False
+
+        self._group_cycles_used[group_key] = used + 1
+
+        return True

prettyplay/cache/models.py

@@ -0,0 +1,55 @@
+"""In-memory models of the step cache: step addressing and a cached unit."""
+
+import hashlib
+
+from pydantic import BaseModel, ConfigDict
+
+#: Unit Separator: makes the identity concatenation unambiguous.
+_IDENTITY_SEPARATOR = "\x1f"
+
+
+class StepIdentity(BaseModel):
+    """The address of a step in the repository cache.
+
+    Attributes:
+        cache_key: the key of the test the step belongs to.
+        step_type: the kind of the step sentence ({action, assertion}).
+        normalized_text: the normalized step sentence.
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    cache_key: str
+    step_type: str
+    normalized_text: str
+
+    @property
+    def filename(self) -> str:
+        """Return the cache filename deterministically derived from the triple.
+
+        Returns:
+            The filename — the parts joined with the Unit Separator,
+            sha256-hashed, ``.py``-extended; the cache loader parses the
+            text and never imports the module by name.
+        """
+        identity_string = _IDENTITY_SEPARATOR.join((self.cache_key, self.step_type, self.normalized_text))
+        digest = hashlib.sha256(identity_string.encode("utf-8")).hexdigest()
+        return f"{digest}.py"
+
+
+class CachedStep(BaseModel):
+    """One unit of the step cache: a working step bound to its identity.
+
+    Attributes:
+        identity: the address of the step.
+        code: the step code — top-level imports when present, then the fixed
+            form ``def step(page) -> None:``; the cache stores and restores
+            the whole text verbatim.
+        created_at: the date the code was generated (ISO format).
+    """
+
+    model_config = ConfigDict(kw_only=True)
+
+    identity: StepIdentity
+    code: str
+    created_at: str