prettyplay 0.0.0__py3-none-any.whl

prettyplay/.usages/lifecycle.md

@@ -0,0 +1,50 @@
+# Run lifecycle
+
+Domain: how a run is composed — runtimes, contexts, hooks, failures. Audience: integrators wiring the library into a runner and CI.
+
+## Composition
+
+One runtime per test: each PrettyTest 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. When the process exits, every runtime stops its browser and driver synchronously before returning control to the terminal — scripts never leave browser processes behind.
+
+## 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.
+
+## Hooks
+
+Implement the StepHooks callback contract and register the implementation with add_hooks before the first step — step, generation, healing, cache and verdict events reach the handler synchronously. on_step_verdict fires after on_step_failed whenever the terminal failure carries an LLM verdict.
+
+## Failures
+
+Four 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 | treat as a bug — this failure is the value of the suite |
+| IncurableStepError | the step cannot be generated or healed | follow the carried recommendation |
+| LlmUnavailableError | the LLM is down | only generation and healing are blocked; cached steps keep running |
+| ConfigurationError | the settings are invalid | fix the named setting — the message lists the allowed values |
+
+ProductDefectError and IncurableStepError carry the LLM verdict — category, explanation, recommendation — in the exception message, the on_step_verdict hook event and the log. When the LLM is unavailable the verdict is skipped quietly; the failure itself never waits for it.
+
+## Team workflow
+
+Generate locally where the LLM is reachable, commit the cache directory, run CI fully from the cache with no LLM keys.
+
+## 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.
+
+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 PrettyTest
+
+test = PrettyTest("login-flow")
+test.action("open the login page")
+test.action("enter the login and password")
+test.assertion("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.

prettyplay/.usages/steps.md

@@ -0,0 +1,56 @@
+# 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 PrettyTest
+
+
+def test_login():
+    t = PrettyTest("login-flow")
+    t.action("open the login page")
+    t.action("enter the login and password")
+    t.action("click the «Sign in» button")
+    t.assertion("the «Welcome back» message appears")
+    t.close()
+```
+
+Or with the context manager:
+
+```python
+with PrettyTest("login-flow") as t:
+    t.action("open the login page")
+```
+
+## Step kinds
+
+- action(text) — performs what the sentence says
+- assertion(text) — verifies what the sentence says; a legitimately failed expectation fails the test as a product defect
+
+## Screenshots
+
+Two author-facing abilities on the test object:
+
+```python
+with PrettyTest("login-flow") as t:
+    t.action("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.
+
+## What you see
+
+Step sentences go to the logger prettyplay at info level — the suite output reads as a plain-language scenario. Healing, cache writes and skipped writes are reported loudly through the same logger.
+
+## Limitations
+
+Step sentences land in the repository cache, the logs and the LLM requests: never put secrets or personal data into a step.

prettyplay/CODEMANIFEST

@@ -0,0 +1,182 @@
+Imports:
+  - Types:
+      - Config AS PrettyConfig
+      - load_config
+    From: prettyplay/config
+  - Types:
+      - StepHooks
+      - StepReporter
+    Usages:
+      - hooks
+    From: prettyplay/reporting
+  - Types:
+      - ProductDefectError
+      - IncurableStepError
+      - LlmUnavailableError
+      - PrettyplayError
+    Usages:
+      - taxonomy
+    From: prettyplay/failures
+  - Types:
+      - DriverSession
+      - PageFacade
+    From: prettyplay/driver
+  - Types:
+      - StepCache
+      - StepIdentity
+      - normalize_step_text
+      - RunBudgets
+    From: prettyplay/cache
+  - Types:
+      - LlmProvider
+      - create_provider
+    From: prettyplay/llm
+  - Types:
+      - StepGenerator
+      - StepHealer
+      - run_step_code
+    Usages:
+      - generation
+      - healing
+    From: prettyplay/engine
+
+Usages:
+  conventions: .goga/usages/conventions.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `taxonomy` from Imports for the failure kinds the step methods propagate.
+  Use `hooks` from Imports for the callback contract accepted by add_hooks.
+  Use `generation` and `healing` from Imports for the engine cycles the executor delegates to.
+
+  The facade of the library: one main object per test; the engineer writes steps as plain sentences and reads the suite as a scenario.
+  Framework-agnostic: no plugin machinery, no runner integration — the integrator wires the library in a few lines.
+  Step sentences are visible in the test output through the standard logger prettyplay; step texts land in the cache and in LLM requests — never put secrets or personal data into a step sentence.
+  `PrettyConfig` — the public name of the settings model — is re-exported by this facade (see the embedding).
+
+---
+
+->PrettyConfig: {}
+
+"PrettyTest(cache_key: str, cache_path: str | None, config: PrettyConfig | None)":
+  location: scenario.py
+  annotations: |
+    The main integrator object — one instance per test. Owns the cache addressing and the isolated browser context of the test; the step cycle is delegated to `StepExecutor`.
+
+    `cache_key`: the mandatory explicit context key — part of the step address; equal keys in the shared root reuse steps across tests.
+    `cache_path`: the optional cache subdirectory — part of the address; steps never leak across subdirectories.
+    `config`: per-test overrides — the same full model; explicitly set values win, unset/empty fields resolve from pyproject+env; None — everything resolves from pyproject+env, as before.
+
+    Supports the context manager protocol: exit closes the test.
+
+    Algorithm:
+    1. Resolve the effective config: `load_config` with overrides = config
+    2. Build the own `PrettyplayRuntime` with the effective config — no process-wide singleton exists
+    3. Construct the per-test reporter: `StepReporter` with an empty hooks list; add_hooks appends to it
+    4. Construct the per-test `StepCache` from the runtime config, `cache_path` and the reporter
+    5. Construct `StepGenerator` and `StepHealer` from the runtime config, provider and budgets, the step cache and the reporter
+    6. Construct `StepExecutor` with `cache_key`, the cache, the engines, the runtime budgets and the reporter
+    7. The test page opens lazily on the first step via the runtime open_page
+
+    Requirements:
+    - Construction is cheap: the browser starts lazily on the first step; no LLM credentials are required to construct
+    - The instance holds no cross-test state: identical outcomes regardless of execution order
+  properties:
+    "cache_key -> str": |
+      The explicit context key, exposed for diagnostics.
+  methods:
+    "action(text: str)": |
+      Execute the action step `text`.
+
+      Delegates to the executor execute with the step type action, the sentence and the test page; failures propagate by kind — `ProductDefectError`, `IncurableStepError`, `LlmUnavailableError` (see `taxonomy`).
+      A `PrettyplayError` leaving this method carries its traceback folded to the library boundary: internal library frames — engine, healing, provider — do not appear in what the runner shows.
+    "assertion(text: str)": |
+      Execute the assertion step `text` — a legitimately failed expectation surfaces as the product defect failure.
+
+      Delegates to the executor execute with the step type assertion; failures propagate by kind — `ProductDefectError`, `IncurableStepError`, `LlmUnavailableError` (see `taxonomy`).
+      A `PrettyplayError` leaving this method carries its traceback folded to the library boundary: internal library frames — engine, healing, provider — do not appear in what the runner shows.
+    "get_screenshot() -> image: bytes": |
+      Return a full-page PNG image of the current state of the test page — uniform with the facade screenshot.
+
+      `image`: the full-page PNG bytes.
+
+      Requirements:
+      - Requires an opened test page: calling before the first step raises a loud actionable `PrettyplayError` telling to run a step first
+      - No screenshot is taken automatically on step failures: the decision to capture belongs to the test author
+    "save_screenshot(filepath: str)": |
+      Write a full-page PNG image of the current state of the test page to `filepath`.
+
+      `filepath`: the explicit destination path chosen by the user — any directory, any filename; no default directory is imposed.
+
+      Requirements:
+      - Requires an opened test page: calling before the first step raises a loud actionable `PrettyplayError` telling to run a step first
+      - A write failure — e.g. a missing parent directory — surfaces as a loud actionable `PrettyplayError`; nothing is created silently
+    "add_hooks(hooks: StepHooks)": |
+      Register a callback implementation (see `hooks`); applies to the steps of this test.
+    "close()": |
+      Close the test page context and stop the whole runtime of this test — the browser process, the Playwright driver and the driver thread; idempotent; the context manager exit does the same.
+
+"StepExecutor(cache_key: str, cache: StepCache, generator: StepGenerator, healer: StepHealer, budgets: RunBudgets, reporter: StepReporter)":
+  location: executor.py
+  annotations: |
+    The owner of the step cycle: cache hit — execute; cache miss — generate and store; cached failure — heal.
+
+    `cache_key`: the context key of the owning test object.
+    `cache`: the step cache of the test.
+    `generator` and `healer`: the engines (see `generation` and `healing` from Imports).
+    `budgets`: the per-test attempt registry.
+    `reporter`: the visibility point.
+  methods:
+    "execute(step_text: str, step_type: str, page: PageFacade)": |
+      Run one step through the full cycle.
+
+      Algorithm:
+      1. Report on_step_started with the sentence and the step type
+      2. Build the step identity: `normalize_step_text`, then `StepIdentity` with the test cache key and the step type
+      3. Load the cached step: a hit executes its code with `run_step_code` against `page`
+      4. On a hit execution failure: delegate to the healer heal with the failure description and the scenario context — a healed step is already re-executed and stored by the engine
+      5. On a miss: the generator generate — the engine stores the step on success
+      6. Append the sentence to the scenario context of the test — the previous step texts feed the next generation
+      7. Report on_step_passed; on a failed step report on_step_failed with the sentence, the step type and the short error description — then, when the terminal failure carries a verdict, report on_step_verdict with the sentence and the three verdict fields; finally raise by kind — `ProductDefectError`, `IncurableStepError`, `LlmUnavailableError` (see `taxonomy`)
+
+      Requirements:
+      - The scenario context lives per test: steps of different tests never mix
+      - A cached step executes with no LLM involvement whatsoever
+      - An assertion step surfaces a legitimately failed expectation as the product defect failure
+
+"PrettyplayRuntime(config: PrettyConfig)":
+  location: runtime.py
+  annotations: |
+    The per-test composition root: one instance per test, owning everything the steps of that test share.
+
+    `config`: the effective settings of the test.
+
+    Requirements:
+    - One instance serves exactly one test: construction starts nothing expensive — the browser, the provider and the budgets belong to this test alone
+  properties:
+    "config -> PrettyConfig": |
+      The effective settings of the test.
+    "driver -> DriverSession": |
+      The browser process of this test, created lazily.
+    "budgets -> RunBudgets": |
+      The attempt registry of the test — one budget per step within the test.
+    "provider -> LlmProvider": |
+      The LLM provider instance, created lazily on first access via `create_provider`.
+
+      Requirements:
+      - Constructing the runtime never requires LLM credentials: a missing key surfaces as the infrastructure failure on the first generation or classification request
+  methods:
+    "open_page() -> page: PageFacade": |
+      Open a fresh isolated browser context and return its page facade — one per test.
+    "close()": |
+      Stop the browser, the Playwright driver and the driver thread of this test; safe when nothing was started.
+
+      Requirements:
+      - Every instance registers its own close with atexit, so the driver stops synchronously before the process exits even when no test closes the runtime explicitly; manual calls stay valid and idempotent
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The facade of prettyplay: the per-test scenario object with screenshot abilities, the step cycle executor with verdict reporting, and the per-test composition root.

prettyplay/__init__.py

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

prettyplay/cache/.usages/addressing.md

@@ -0,0 +1,31 @@
+# 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 | NFC, trim, whitespace collapse, casefold | «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.
+
+## 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 <repo root>/.prettyplay/cache/ 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,21 @@
+# 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

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) followed by the generated step code of the fixed form. 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
+- 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/CODEMANIFEST

@@ -0,0 +1,152 @@
+Imports:
+  - Types:
+      - Config
+    From: prettyplay/config
+  - Types:
+      - StepReporter
+    Usages:
+      - hooks
+    From: prettyplay/reporting
+
+Usages:
+  conventions: .goga/usages/conventions.md
+
+Annotations: |
+  Use `conventions` for code writing rules and testing.
+  Use `hooks` from Imports for the payload contract of the cache events.
+
+  The cache is a repository artifact: one .py file per step, addressed deterministically; the cache is always read, writes are best-effort.
+  Step identity is intentional: the same normalized sentence in the same context is one step; a different language, a different step type or a different cache key is a different step.
+  RunBudgets lives in this cell because its accounting key is `StepIdentity`: per-test attempt accounting stays next to the addressing it is keyed by.
+
+---
+
+"normalize_step_text(text: str) -> normalized: str":
+  location: text.py
+  annotations: |
+    Normalize a step sentence for identity and addressing.
+
+    `text`: the raw step sentence as written by the engineer.
+    `normalized`: the normalized sentence.
+
+    Algorithm:
+    1. Apply Unicode NFC normalization
+    2. Trim leading and trailing whitespace
+    3. Collapse internal whitespace runs to single spaces
+    4. Apply casefold
+
+    Requirements:
+    - Pure function: no I/O, no locale dependence
+    - «Нажать Войти» and «нажать  войти » normalize to the same string; a Russian sentence and its English translation stay different
+
+"StepIdentity(cache_key: str, step_type: str, normalized_text: str)":
+  location: models.py
+  annotations: |
+    The address of a cache step: the triple (cache_key, step_type, normalized_text) plus the deterministic file name derived from it.
+
+    `cache_key`: the explicit context key set by the integrator on the main object.
+    `step_type`: action or assertion.
+    `normalized_text`: the step sentence after `normalize_step_text`.
+  properties:
+    "cache_key -> str": |
+      The explicit context key of the step address.
+    "step_type -> str": |
+      The step kind: action or assertion.
+    "normalized_text -> str": |
+      The normalized step sentence.
+    "filename -> str": |
+      The deterministic cache file name.
+
+      Algorithm:
+      1. Build the identity string: cache_key, step_type and normalized_text joined with an unambiguous separator
+      2. Hash the string with sha256
+      3. Compose the file name from the hex digest
+
+      Requirements:
+      - The same triple always yields the same file name; any difference in the triple yields a different one
+      - The digest identifies the file unambiguously inside the cache directory
+
+"CachedStep(identity: StepIdentity, code: str, created_at: str)":
+  location: models.py
+  annotations: |
+    One cached step in memory: the metadata and the generated code of the step, as stored in its cache file.
+
+    `identity`: the step address.
+    `code`: the generated step code of the fixed form.
+    `created_at`: the creation date.
+
+    Requirements:
+    - The cache file is a valid Python module: metadata fields first, then the step code; importing the module and reading the fields reconstructs the step
+    - The file carries no library version field and is never invalidated by a library upgrade
+  properties:
+    "identity -> StepIdentity": |
+      The step address.
+    "code -> str": |
+      The generated step code of the fixed form.
+    "created_at -> str": |
+      The creation date.
+
+"StepCache(config: Config, path: str | None, reporter: StepReporter | None)":
+  location: store.py
+  annotations: |
+    The repository store of cache steps: addressing, atomic writes and the read-only mode.
+
+    `config`: project settings; the cache_root setting is the cache root.
+    `path`: the optional subdirectory inside the cache; part of the address — steps of different subdirectories never collide; empty — the shared root, so equal cache keys are reused across tests.
+    `reporter`: the visibility point — cache events (saved, skipped) go through it; omitted — the hook-less default reporter, so a missing visibility point never fails a save.
+  properties:
+    "root -> str": |
+      The effective cache root; the default is <repo root>/.prettyplay/cache/.
+    "writable -> bool": |
+      Whether the cache directory accepts writes.
+  methods:
+    "load(identity: StepIdentity) -> step: CachedStep | None": |
+      Load the cached step by address.
+
+      Algorithm:
+      1. Resolve the target file by the effective root, the subdirectory and the identity file name
+      2. A missing file returns None
+      3. Read the module, validate the metadata fields, reconstruct `CachedStep`
+    "save(step: CachedStep)": |
+      Store the step atomically, best-effort.
+
+      Algorithm:
+      1. Check writability: a read-only cache skips the write and reports on_cache_skipped with the reason read-only cache
+      2. Serialize the step into the module text: metadata fields, then the code
+      3. Write a temporary file with a unique name in the target directory
+      4. Replace the target file atomically via os.replace
+      5. On Windows, when the target is busy: retry the replace shortly, then skip the write for this step and report on_cache_skipped — the run does not fail
+      6. Report on_cache_saved with the file name on success
+
+      Requirements:
+      - Concurrent writers on one step never corrupt the file: last writer wins
+      - A partially written file never becomes visible: the replace is atomic
+      - The cache is always read, in every environment
+
+"RunBudgets(generation_limit: int, healing_limit: int)":
+  location: budgets.py
+  annotations: |
+    The per-test attempt registry: how many generation and healing attempts each step has left within the test.
+
+    `generation_limit`: the generation attempt budget per step per test.
+    `healing_limit`: the healing attempt budget per step per test.
+
+    Requirements:
+    - The registry lives for the lifetime of one test, owned by the test's runtime: every test starts with full limits — a step reused across tests gets a fresh budget in each test
+    - The identity key is `StepIdentity`
+    - An exhausted budget returns False — the caller turns it into the incurable failure
+
+    Constraints:
+    - No persistence: budgets exist only in the memory of the running process
+  methods:
+    "try_generation(identity: StepIdentity) -> allowed: bool": |
+      Consume one generation attempt for the step; False — the budget is exhausted, the caller reports incurability.
+    "try_healing(identity: StepIdentity) -> allowed: bool": |
+      Consume one healing attempt for the step; False — the budget is exhausted, the caller reports incurability.
+
+---
+
+Author: Goga
+CreatedAt: 07/09/26
+Description: |
+  The step cache of prettyplay: normalization, deterministic addressing, atomic repository storage and the per-test attempt budgets.

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,73 @@
+"""Per-test attempt registry: how many tries a step still has in this test.
+
+One registry lives for the lifetime of one test, owned by the test's runtime
+(see the runtime composition root), so every test starts with full limits —
+a step reused across tests gets a fresh budget in each test. Generation and
+healing draw from separate pools, and each step is accounted by its
+deterministic address.
+"""
+
+from .models import StepIdentity
+
+
+class RunBudgets:
+    """The per-test registry of generation and healing attempts per step.
+
+    Both pools are keyed by ``identity.filename`` — the deterministic digest
+    of the step triple — so accounting survives without hashing the pydantic
+    model. Nothing is persisted: the registry is 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.
+    """
+
+    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] = {}
+
+    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