airflow-pytest-plugin 0.3.0__tar.gz → 0.3.1__tar.gz

{airflow_pytest_plugin-0.3.0 → airflow_pytest_plugin-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airflow-pytest-plugin
-Version: 0.3.0
+Version: 0.3.1
 Summary: View airflow-pytest-operator results in the Airflow 3 web UI.
 Project-URL: Homepage, https://github.com/IKrysanov/airflow-pytest-plugin
 Project-URL: Repository, https://github.com/IKrysanov/airflow-pytest-plugin
@@ -98,9 +98,11 @@ It has two halves that share one on-disk layout:
 ## Screenshots
 
 **Overview** — the run list with the historical chart (per-status legend
-toggles, run numbers, and a carousel beyond 30 runs) beside a **flaky-tests
-panel**, KPI cards (including a clickable **unique tests** count), and Airflow-
-matched colours and font:
+toggles, run numbers, a carousel beyond 30 runs, an optional **pass-rate trend
+line** with a success-threshold gridline, and **tick runs in the list to filter
+the chart to just their trend**) beside a **flaky-tests panel** (with its own
+search and a quarantined-only toggle), KPI cards (including a clickable **unique
+tests** count), and Airflow-matched colours and font:
 
 ![Pytest Reports — overview](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/overview.png)
 
@@ -112,9 +114,10 @@ output on expand:
 ![Pytest Reports — a single run](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/detail.png)
 
 **Flaky tests & comparison** — from a run, *Flaky tests* lists the tests that
-both pass and fail across recent runs (with a recent-outcome strip), and
-*Compare to previous* diffs it against the prior run; expanding a case offers its
-full **history**:
+both pass and fail across recent runs, each with a recent-outcome strip, a
+**flakiness score**, a **trend** arrow, and a **quarantine** badge, over a
+configurable analysis window; *Compare to previous* diffs it against the prior
+run; expanding a case offers its full **history**:
 
 ![Pytest Reports — flaky tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/flaky.png)
 
@@ -229,7 +232,7 @@ runtime. Endpoints (relative to the mount):
 | `GET /api/reports/{report_id}` | one report with per-case rows |
 | `GET /api/failures?dag_id=&run_id=&task_id=` | failed/errored cases across the visible runs |
 | `GET /api/compare?base=&head=` | per-test diff between two runs (newly failed / fixed / …) |
-| `GET /api/flaky?dag_id=&task_id=&window=` | tests that both pass and fail over recent runs |
+| `GET /api/flaky?dag_id=&task_id=&window=` | flaky tests with score, trend, and a quarantine flag |
 | `GET /api/test-history?dag_id=&task_id=&node_id=&limit=` | one test's outcome per run |
 | `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ list when `full`) |
 | `DELETE /api/reports/{report_id}` | delete a report (RBAC-gated) |
@@ -295,6 +298,13 @@ Download them from a report's detail view, or `GET
 | built-in default | `/opt/airflow/pytest-reports` | fallback |
 | `AIRFLOW_PYTEST_PLUGIN_ENABLE` (env) | `True` | reader on/off — see below |
 | `AIRFLOW_PYTEST_SCAN_CACHE_TTL` (env) | `2.0` | seconds a directory scan is reused (`0` disables) |
+| `AIRFLOW_PYTEST_RETENTION_MAX_AGE_DAYS` (env/cfg) | — | delete runs older than N days |
+| `AIRFLOW_PYTEST_RETENTION_MAX_RUNS` (env/cfg) | — | keep at most N newest runs per dag·task |
+| `AIRFLOW_PYTEST_RETENTION_MAX_TOTAL_MB` (env/cfg) | — | total report-tree budget in MB |
+| `AIRFLOW_PYTEST_FLAKY_WINDOW` (env/cfg) | `30` | default recent runs the flaky detector scans |
+| `AIRFLOW_PYTEST_FLAKY_QUARANTINE_SCORE` (env/cfg) | `0.5` | flakiness score (0–1) that flags a test for quarantine |
+| `AIRFLOW_PYTEST_FLAKY_MIN_SCORE` (env/cfg) | `0.1` | flakiness score (0–1) below which a test is not counted as flaky |
+| `AIRFLOW_PYTEST_SUCCESS_THRESHOLD` (env/cfg) | `0.85` | pass-rate (0–1) over executed tests at/above which a run counts as successful (*Passing runs*); `1.0` = strict, zero failures/errors |
 
 **Enable / disable the reader.** Set `AIRFLOW_PYTEST_PLUGIN_ENABLE` to a falsey
 value (`0`, `false`, `no`, `off`) to stop the plugin registering its UI and API
@@ -314,6 +324,34 @@ single scan for `AIRFLOW_PYTEST_SCAN_CACHE_TTL` seconds (default `2.0`; deletes
 invalidate it immediately). New runs therefore appear within a couple of seconds (or
 on **Refresh**); set it to `0` for no caching, or higher on a very large tree.
 
+## Retention (auto-cleanup)
+
+Reports accumulate forever unless you prune them. Set any of the
+`AIRFLOW_PYTEST_RETENTION_*` knobs above (all opt-in; unset = keep everything) and
+schedule `prune_reports` from a maintenance DAG:
+
+```python
+from airflow import DAG
+from airflow.providers.standard.operators.python import PythonOperator
+from airflow_pytest_plugin import prune_reports
+
+with DAG("pytest_reports_retention", schedule="@daily", catchup=False, ...):
+    PythonOperator(task_id="prune", python_callable=prune_reports)
+```
+
+Each knob is a dimension and they combine as a union — a run is deleted if **any**
+applies:
+
+- **age** — older than `…_MAX_AGE_DAYS`;
+- **count** — beyond the newest `…_MAX_RUNS` of its dag·task;
+- **size** — oldest-first until the tree fits `…_MAX_TOTAL_MB`.
+
+The **newest run of each dag·task is always kept**, so a task's latest result never
+disappears. `prune_reports(dry_run=True)` reports what *would* go without deleting
+(its `RetentionResult` carries `deleted`, `freed_bytes`, `scanned`). Cleanup is
+scheduler-driven — the plugin never deletes on its own. For a custom policy, build a
+`RetentionPolicy(...)` and pass it (`prune_reports(policy)`).
+
 ## Architecture (SOLID)
 
 Mirrors the operator's layering — each piece has one reason to change:
@@ -324,6 +362,7 @@ Mirrors the operator's layering — each piece has one reason to change:
 | `producer.ArchivingResultParser` | write JUnit XML + `meta.json` (extends the operator's parser) |
 | `sources.ReportSource` / `FileSystemReportSource` | read/index reports behind an interface (Dependency Inversion) |
 | `web.create_app` | map HTTP onto a `ReportSource` — knows nothing about the filesystem |
+| `retention` | pure `select_expired` decision + a `prune` orchestrator over any `ReportSource` |
 | `plugin.PytestReportsPlugin` | register the app with Airflow |
 | `compat` | the only module that imports Airflow; version differences resolved once |
 | `models` | JSON-serializable view types; the web layer never sees operator types |

{airflow_pytest_plugin-0.3.0 → airflow_pytest_plugin-0.3.1}/README.md

@@ -54,9 +54,11 @@ It has two halves that share one on-disk layout:
 ## Screenshots
 
 **Overview** — the run list with the historical chart (per-status legend
-toggles, run numbers, and a carousel beyond 30 runs) beside a **flaky-tests
-panel**, KPI cards (including a clickable **unique tests** count), and Airflow-
-matched colours and font:
+toggles, run numbers, a carousel beyond 30 runs, an optional **pass-rate trend
+line** with a success-threshold gridline, and **tick runs in the list to filter
+the chart to just their trend**) beside a **flaky-tests panel** (with its own
+search and a quarantined-only toggle), KPI cards (including a clickable **unique
+tests** count), and Airflow-matched colours and font:
 
 ![Pytest Reports — overview](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/overview.png)
 
@@ -68,9 +70,10 @@ output on expand:
 ![Pytest Reports — a single run](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/detail.png)
 
 **Flaky tests & comparison** — from a run, *Flaky tests* lists the tests that
-both pass and fail across recent runs (with a recent-outcome strip), and
-*Compare to previous* diffs it against the prior run; expanding a case offers its
-full **history**:
+both pass and fail across recent runs, each with a recent-outcome strip, a
+**flakiness score**, a **trend** arrow, and a **quarantine** badge, over a
+configurable analysis window; *Compare to previous* diffs it against the prior
+run; expanding a case offers its full **history**:
 
 ![Pytest Reports — flaky tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/flaky.png)
 
@@ -185,7 +188,7 @@ runtime. Endpoints (relative to the mount):
 | `GET /api/reports/{report_id}` | one report with per-case rows |
 | `GET /api/failures?dag_id=&run_id=&task_id=` | failed/errored cases across the visible runs |
 | `GET /api/compare?base=&head=` | per-test diff between two runs (newly failed / fixed / …) |
-| `GET /api/flaky?dag_id=&task_id=&window=` | tests that both pass and fail over recent runs |
+| `GET /api/flaky?dag_id=&task_id=&window=` | flaky tests with score, trend, and a quarantine flag |
 | `GET /api/test-history?dag_id=&task_id=&node_id=&limit=` | one test's outcome per run |
 | `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ list when `full`) |
 | `DELETE /api/reports/{report_id}` | delete a report (RBAC-gated) |
@@ -251,6 +254,13 @@ Download them from a report's detail view, or `GET
 | built-in default | `/opt/airflow/pytest-reports` | fallback |
 | `AIRFLOW_PYTEST_PLUGIN_ENABLE` (env) | `True` | reader on/off — see below |
 | `AIRFLOW_PYTEST_SCAN_CACHE_TTL` (env) | `2.0` | seconds a directory scan is reused (`0` disables) |
+| `AIRFLOW_PYTEST_RETENTION_MAX_AGE_DAYS` (env/cfg) | — | delete runs older than N days |
+| `AIRFLOW_PYTEST_RETENTION_MAX_RUNS` (env/cfg) | — | keep at most N newest runs per dag·task |
+| `AIRFLOW_PYTEST_RETENTION_MAX_TOTAL_MB` (env/cfg) | — | total report-tree budget in MB |
+| `AIRFLOW_PYTEST_FLAKY_WINDOW` (env/cfg) | `30` | default recent runs the flaky detector scans |
+| `AIRFLOW_PYTEST_FLAKY_QUARANTINE_SCORE` (env/cfg) | `0.5` | flakiness score (0–1) that flags a test for quarantine |
+| `AIRFLOW_PYTEST_FLAKY_MIN_SCORE` (env/cfg) | `0.1` | flakiness score (0–1) below which a test is not counted as flaky |
+| `AIRFLOW_PYTEST_SUCCESS_THRESHOLD` (env/cfg) | `0.85` | pass-rate (0–1) over executed tests at/above which a run counts as successful (*Passing runs*); `1.0` = strict, zero failures/errors |
 
 **Enable / disable the reader.** Set `AIRFLOW_PYTEST_PLUGIN_ENABLE` to a falsey
 value (`0`, `false`, `no`, `off`) to stop the plugin registering its UI and API
@@ -270,6 +280,34 @@ single scan for `AIRFLOW_PYTEST_SCAN_CACHE_TTL` seconds (default `2.0`; deletes
 invalidate it immediately). New runs therefore appear within a couple of seconds (or
 on **Refresh**); set it to `0` for no caching, or higher on a very large tree.
 
+## Retention (auto-cleanup)
+
+Reports accumulate forever unless you prune them. Set any of the
+`AIRFLOW_PYTEST_RETENTION_*` knobs above (all opt-in; unset = keep everything) and
+schedule `prune_reports` from a maintenance DAG:
+
+```python
+from airflow import DAG
+from airflow.providers.standard.operators.python import PythonOperator
+from airflow_pytest_plugin import prune_reports
+
+with DAG("pytest_reports_retention", schedule="@daily", catchup=False, ...):
+    PythonOperator(task_id="prune", python_callable=prune_reports)
+```
+
+Each knob is a dimension and they combine as a union — a run is deleted if **any**
+applies:
+
+- **age** — older than `…_MAX_AGE_DAYS`;
+- **count** — beyond the newest `…_MAX_RUNS` of its dag·task;
+- **size** — oldest-first until the tree fits `…_MAX_TOTAL_MB`.
+
+The **newest run of each dag·task is always kept**, so a task's latest result never
+disappears. `prune_reports(dry_run=True)` reports what *would* go without deleting
+(its `RetentionResult` carries `deleted`, `freed_bytes`, `scanned`). Cleanup is
+scheduler-driven — the plugin never deletes on its own. For a custom policy, build a
+`RetentionPolicy(...)` and pass it (`prune_reports(policy)`).
+
 ## Architecture (SOLID)
 
 Mirrors the operator's layering — each piece has one reason to change:
@@ -280,6 +318,7 @@ Mirrors the operator's layering — each piece has one reason to change:
 | `producer.ArchivingResultParser` | write JUnit XML + `meta.json` (extends the operator's parser) |
 | `sources.ReportSource` / `FileSystemReportSource` | read/index reports behind an interface (Dependency Inversion) |
 | `web.create_app` | map HTTP onto a `ReportSource` — knows nothing about the filesystem |
+| `retention` | pure `select_expired` decision + a `prune` orchestrator over any `ReportSource` |
 | `plugin.PytestReportsPlugin` | register the app with Airflow |
 | `compat` | the only module that imports Airflow; version differences resolved once |
 | `models` | JSON-serializable view types; the web layer never sees operator types |

{airflow_pytest_plugin-0.3.0 → airflow_pytest_plugin-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "airflow-pytest-plugin"
-version = "0.3.0"
+version = "0.3.1"
 description = "View airflow-pytest-operator results in the Airflow 3 web UI."
 readme = "README.md"
 requires-python = ">=3.10"

{airflow_pytest_plugin-0.3.0 → airflow_pytest_plugin-0.3.1}/src/airflow_pytest_plugin/__init__.py

@@ -22,6 +22,7 @@ from .config import get_reports_root
 from .layout import ReportLayout
 from .models import CaseView, ReportDetail, ReportRef, ReportSummary
 from .producer import ArchivingResultParser
+from .retention import RetentionPolicy, RetentionResult, prune_reports
 from .sources import FileSystemReportSource, ReportSource
 from .version import __version__ as __version__
 
@@ -38,6 +39,9 @@ __all__ = [
     "ReportDetail",
     "CaseView",
     "ReportLayout",
+    "RetentionPolicy",
+    "RetentionResult",
+    "prune_reports",
     "get_reports_root",
     "create_app",
     "__version__",

airflow_pytest_plugin-0.3.1/src/airflow_pytest_plugin/config.py

@@ -0,0 +1,177 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resolve the report root (env, then Airflow config, then default)."""
+
+from __future__ import annotations
+
+import os
+
+from .compat import get_conf_value
+
+ENV_VAR = "AIRFLOW_PYTEST_REPORTS_ROOT"
+CONF_SECTION = "pytest_reports"
+CONF_KEY = "reports_root"
+DEFAULT_ROOT = "/opt/airflow/pytest-reports"
+
+#: Toggles whether the reader plugin (UI + API) registers with Airflow. Default on.
+ENABLE_ENV_VAR = "AIRFLOW_PYTEST_PLUGIN_ENABLE"
+_FALSEY = frozenset({"0", "false", "no", "off", "n", "f"})
+
+
+def is_plugin_enabled() -> bool:
+    """Whether the reader plugin should register with Airflow.
+
+    Reads ``AIRFLOW_PYTEST_PLUGIN_ENABLE`` -- ``True`` (the default when unset/empty)
+    registers the UI + API; a falsey value (``0``/``false``/``no``/``off``) disables
+    it. Only gates the reader; the producer-side parser is unaffected.
+    """
+    raw = os.environ.get(ENABLE_ENV_VAR)
+    if raw is None or not raw.strip():
+        return True
+    return raw.strip().lower() not in _FALSEY
+
+
+#: How long (seconds) the filesystem source may reuse a directory scan. A short
+#: window lets the several summary-driven endpoints on one page load (list + flaky +
+#: unique-tests, plus filter typing) share one tree walk instead of rescanning each.
+SCAN_TTL_ENV_VAR = "AIRFLOW_PYTEST_SCAN_CACHE_TTL"
+DEFAULT_SCAN_TTL = 2.0
+
+
+def get_scan_cache_ttl() -> float:
+    """Resolve the directory-scan cache TTL in seconds (``0`` disables caching).
+
+    Reads ``AIRFLOW_PYTEST_SCAN_CACHE_TTL``; falls back to ``DEFAULT_SCAN_TTL``.
+    A malformed or negative value falls back to the default.
+    """
+    raw = os.environ.get(SCAN_TTL_ENV_VAR)
+    if raw is None or not raw.strip():
+        return DEFAULT_SCAN_TTL
+    try:
+        ttl = float(raw.strip())
+    except ValueError:
+        return DEFAULT_SCAN_TTL
+    return ttl if ttl >= 0 else DEFAULT_SCAN_TTL
+
+
+#: Retention knobs (all opt-in; unset = keep everything). Each reads its env var,
+#: then the matching ``[pytest_reports]`` cfg key. Non-positive/invalid -> unset.
+RETENTION_MAX_AGE_DAYS_ENV = "AIRFLOW_PYTEST_RETENTION_MAX_AGE_DAYS"
+RETENTION_MAX_RUNS_ENV = "AIRFLOW_PYTEST_RETENTION_MAX_RUNS"
+RETENTION_MAX_TOTAL_MB_ENV = "AIRFLOW_PYTEST_RETENTION_MAX_TOTAL_MB"
+
+
+def _positive_int_setting(env_var: str, conf_key: str) -> int | None:
+    raw = os.environ.get(env_var)
+    if raw is None or not raw.strip():
+        raw = get_conf_value(CONF_SECTION, conf_key)
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        value = int(str(raw).strip())
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def get_retention_max_age_days() -> int | None:
+    """Delete runs older than this many days (``None`` = no age limit)."""
+    return _positive_int_setting(RETENTION_MAX_AGE_DAYS_ENV, "retention_max_age_days")
+
+
+def get_retention_max_runs() -> int | None:
+    """Keep at most this many newest runs per dag·task (``None`` = unlimited)."""
+    return _positive_int_setting(RETENTION_MAX_RUNS_ENV, "retention_max_runs")
+
+
+def get_retention_max_total_mb() -> int | None:
+    """Total report-tree budget in MB (``None`` = unlimited)."""
+    return _positive_int_setting(RETENTION_MAX_TOTAL_MB_ENV, "retention_max_total_mb")
+
+
+#: Flaky-detector defaults (overridable per request via the ``window`` query param).
+FLAKY_WINDOW_ENV = "AIRFLOW_PYTEST_FLAKY_WINDOW"
+DEFAULT_FLAKY_WINDOW = 30
+FLAKY_QUARANTINE_SCORE_ENV = "AIRFLOW_PYTEST_FLAKY_QUARANTINE_SCORE"
+DEFAULT_FLAKY_QUARANTINE_SCORE = 0.5
+#: Flakiness-score floor: below it a test is too steady to count as flaky, so a lone
+#: blip in a long history (a near-zero flip rate) drops off the list.
+FLAKY_MIN_SCORE_ENV = "AIRFLOW_PYTEST_FLAKY_MIN_SCORE"
+DEFAULT_FLAKY_MIN_SCORE = 0.1
+
+
+def get_flaky_window() -> int:
+    """Default number of recent runs the flaky detector looks at per dag·task."""
+    return (
+        _positive_int_setting(FLAKY_WINDOW_ENV, "flaky_window") or DEFAULT_FLAKY_WINDOW
+    )
+
+
+def _unit_float_setting(env_var: str, conf_key: str, default: float) -> float:
+    """A 0–1 float from env, then cfg; default on missing/invalid/out-of-range."""
+    raw = os.environ.get(env_var)
+    if raw is None or not raw.strip():
+        raw = get_conf_value(CONF_SECTION, conf_key)
+    if raw is None or not str(raw).strip():
+        return default
+    try:
+        value = float(str(raw).strip())
+    except ValueError:
+        return default
+    return value if 0.0 <= value <= 1.0 else default
+
+
+def get_flaky_quarantine_score() -> float:
+    """Flakiness score (0–1) at/above which a test is flagged for quarantine."""
+    return _unit_float_setting(
+        FLAKY_QUARANTINE_SCORE_ENV,
+        "flaky_quarantine_score",
+        DEFAULT_FLAKY_QUARANTINE_SCORE,
+    )
+
+
+def get_flaky_min_score() -> float:
+    """Flakiness score (0–1) below which a test is NOT counted as flaky."""
+    return _unit_float_setting(
+        FLAKY_MIN_SCORE_ENV, "flaky_min_score", DEFAULT_FLAKY_MIN_SCORE
+    )
+
+
+#: Pass-rate (0–1) at/above which a run counts as successful ("Passing runs"). The
+#: rate is over executed tests, so a run can carry a few failures and still pass.
+#: At 1.0 a run is successful only with zero failures/errors (the strict default of
+#: older versions). 0.85 is a common "good enough" bar (ISTQB defines no fixed number).
+SUCCESS_THRESHOLD_ENV = "AIRFLOW_PYTEST_SUCCESS_THRESHOLD"
+DEFAULT_SUCCESS_THRESHOLD = 0.85
+
+
+def get_success_threshold() -> float:
+    """Pass-rate (0–1) at/above which a run counts as successful."""
+    return _unit_float_setting(
+        SUCCESS_THRESHOLD_ENV, "success_threshold", DEFAULT_SUCCESS_THRESHOLD
+    )
+
+
+def get_reports_root() -> str:
+    """Resolve the report root directory (absolute path)."""
+    env = os.environ.get(ENV_VAR)
+    if env and env.strip():
+        return os.path.abspath(env.strip())
+
+    conf = get_conf_value(CONF_SECTION, CONF_KEY)
+    if conf and conf.strip():
+        return os.path.abspath(conf.strip())
+
+    return os.path.abspath(DEFAULT_ROOT)

{airflow_pytest_plugin-0.3.0 → airflow_pytest_plugin-0.3.1}/src/airflow_pytest_plugin/models.py

@@ -117,6 +117,19 @@ class ReportSummary:
         }
 
 
+def run_succeeds(passed: int, failed: int, errors: int, threshold: float) -> bool:
+    """Whether a run counts as successful at a given pass-rate ``threshold`` (0–1).
+
+    The rate is over *executed* tests -- ``passed / (passed + failed + errors)`` --
+    so skipped tests neither help nor hurt; a run with nothing executed is a pass.
+    At ``threshold == 1.0`` this is exactly "no failures or errors".
+    """
+    executed = passed + failed + errors
+    if executed <= 0:
+        return True
+    return passed / executed >= threshold
+
+
 @dataclass(frozen=True)
 class CaseView:
     """One test case, flattened for the detail table."""

airflow_pytest_plugin-0.3.1/src/airflow_pytest_plugin/retention.py

@@ -0,0 +1,253 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Retention: choose and delete old archived runs by age / count / size.
+
+Layered so the decision is pure and testable, separate from the I/O:
+
+- ``RetentionPolicy`` — the value object (limits, ``from_config``).
+- ``select_expired`` — pure: given run facts + a policy, which runs to delete.
+- ``prune`` — orchestrator: list + measure via a ``ReportSource``, then delete.
+
+Across every policy the **newest run of each dag·task is always kept**, so a task's
+latest result never disappears.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+from .config import (
+    get_retention_max_age_days,
+    get_retention_max_runs,
+    get_retention_max_total_mb,
+)
+from .models import ReportRef
+
+if TYPE_CHECKING:
+    from .sources import ReportSource
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RetentionPolicy:
+    """Limits for retention; ``None`` on a field means that dimension is unbounded."""
+
+    max_age_days: int | None = None
+    max_runs_per_task: int | None = None
+    max_total_bytes: int | None = None
+
+    def __post_init__(self) -> None:
+        # A non-positive limit is nonsensical and would break the keep-newest
+        # invariant (e.g. max_runs_per_task=0 would mark a group's newest run).
+        for name in ("max_age_days", "max_runs_per_task", "max_total_bytes"):
+            value = getattr(self, name)
+            if value is not None and value <= 0:
+                raise ValueError(
+                    f"{name} must be a positive int or None, got {value!r}"
+                )
+
+    @property
+    def is_active(self) -> bool:
+        """Whether any limit is set (an inactive policy deletes nothing)."""
+        return any(
+            v is not None
+            for v in (self.max_age_days, self.max_runs_per_task, self.max_total_bytes)
+        )
+
+    @property
+    def needs_sizes(self) -> bool:
+        """Whether evaluating it requires measuring report sizes (the size policy)."""
+        return self.max_total_bytes is not None
+
+    @classmethod
+    def from_config(cls) -> RetentionPolicy:
+        """Build from the env vars / Airflow cfg (all opt-in; default = keep all)."""
+        mb = get_retention_max_total_mb()
+        return cls(
+            max_age_days=get_retention_max_age_days(),
+            max_runs_per_task=get_retention_max_runs(),
+            max_total_bytes=mb * 1024 * 1024 if mb is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class RunEntry:
+    """The facts ``select_expired`` needs about one run -- no I/O."""
+
+    ref: ReportRef
+    created_at: str | None  # ISO-8601, as stored in meta.json
+    size: int = 0  # bytes; 0 unless the size policy needs it
+
+
+@dataclass(frozen=True)
+class RetentionResult:
+    """What a prune did (or would do, under ``dry_run``)."""
+
+    deleted: tuple[str, ...]  # tokens of the deleted (or would-be-deleted) runs
+    freed_bytes: int
+    scanned: int
+    dry_run: bool
+
+    @property
+    def deleted_count(self) -> int:
+        return len(self.deleted)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "deleted": list(self.deleted),
+            "deleted_count": self.deleted_count,
+            "freed_bytes": self.freed_bytes,
+            "scanned": self.scanned,
+            "dry_run": self.dry_run,
+        }
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    """Parse an ISO timestamp to an aware datetime (assume UTC if naive), else None."""
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
+def select_expired(
+    entries: list[RunEntry], policy: RetentionPolicy, *, now: datetime
+) -> list[ReportRef]:
+    """Pure decision: which runs to delete under ``policy`` as of ``now``.
+
+    The newest run of each dag·task is never selected. Age and count act per
+    dag·task; size trims oldest-first across all tasks until the tree fits the
+    budget. The dimensions combine as a union.
+    """
+    if not policy.is_active:
+        return []
+
+    groups: dict[tuple[str, str], list[RunEntry]] = {}
+    for entry in entries:
+        groups.setdefault((entry.ref.dag_id, entry.ref.task_id), []).append(entry)
+    for group in groups.values():
+        group.sort(key=lambda e: e.created_at or "", reverse=True)  # newest first
+
+    marked: dict[str, RunEntry] = {}  # token -> entry (dedup, insertion-ordered)
+
+    def mark(entry: RunEntry) -> None:
+        marked.setdefault(entry.ref.token, entry)
+
+    # Count: keep the newest N of each dag·task.
+    if policy.max_runs_per_task is not None:
+        for group in groups.values():
+            for entry in group[policy.max_runs_per_task :]:
+                mark(entry)
+
+    # Age: drop runs older than the cutoff -- but never a group's newest (group[1:]).
+    if policy.max_age_days is not None:
+        cutoff = now - timedelta(days=policy.max_age_days)
+        for group in groups.values():
+            for entry in group[1:]:
+                dt = _parse_dt(entry.created_at)
+                if dt is not None and dt < cutoff:
+                    mark(entry)
+
+    # Size: if the tree still exceeds the budget, delete oldest-first (never a
+    # group's newest) until it fits or only protected runs remain.
+    if policy.max_total_bytes is not None:
+        remaining = sum(e.size for e in entries) - sum(e.size for e in marked.values())
+        if remaining > policy.max_total_bytes:
+            candidates = [e for group in groups.values() for e in group[1:]]
+            candidates.sort(key=lambda e: e.created_at or "")  # oldest first
+            for entry in candidates:
+                if remaining <= policy.max_total_bytes:
+                    break
+                if entry.ref.token in marked:
+                    continue
+                mark(entry)
+                remaining -= entry.size
+
+    return [entry.ref for entry in marked.values()]
+
+
+def prune(
+    source: ReportSource,
+    policy: RetentionPolicy | None = None,
+    *,
+    now: datetime | None = None,
+    dry_run: bool = False,
+) -> RetentionResult:
+    """Apply ``policy`` (default: from config) to ``source``, deleting expired runs.
+
+    With ``dry_run`` nothing is deleted -- the result still lists what would go.
+    Pass ``now`` for deterministic age handling (defaults to the current UTC time).
+    """
+    resolved = policy if policy is not None else RetentionPolicy.from_config()
+    if not resolved.is_active:
+        return RetentionResult(deleted=(), freed_bytes=0, scanned=0, dry_run=dry_run)
+
+    entries = [
+        RunEntry(
+            ref=s.ref,
+            created_at=s.created_at,
+            size=source.report_size(s.ref) if resolved.needs_sizes else 0,
+        )
+        for s in source.list_summaries()
+    ]
+    when = now if now is not None else datetime.now(timezone.utc)
+    to_delete = select_expired(entries, resolved, now=when)
+
+    sizes = {e.ref.token: e.size for e in entries}
+    freed = sum(sizes.get(ref.token, 0) for ref in to_delete)
+    if not dry_run:
+        for ref in to_delete:
+            source.delete(ref)
+
+    _log.info(
+        "retention: %s %d of %d run(s), %d bytes (dry_run=%s)",
+        "would delete" if dry_run else "deleted",
+        len(to_delete),
+        len(entries),
+        freed,
+        dry_run,
+    )
+    return RetentionResult(
+        deleted=tuple(ref.token for ref in to_delete),
+        freed_bytes=freed,
+        scanned=len(entries),
+        dry_run=dry_run,
+    )
+
+
+def prune_reports(
+    policy: RetentionPolicy | None = None,
+    *,
+    source: ReportSource | None = None,
+    dry_run: bool = False,
+    now: datetime | None = None,
+) -> RetentionResult:
+    """Entry point for a scheduled maintenance task (e.g. a ``PythonOperator``).
+
+    Defaults to the filesystem source and the policy from config -- so a bare
+    ``prune_reports`` callable Just Works once the env/cfg limits are set.
+    """
+    if source is None:
+        from .sources import FileSystemReportSource
+
+        source = FileSystemReportSource()
+    return prune(source, policy, now=now, dry_run=dry_run)