supertable 2.1.0__tar.gz → 2.2.0__tar.gz

{supertable-2.1.0/supertable.egg-info → supertable-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supertable
-Version: 2.1.0
+Version: 2.2.0
 Summary: SuperTable — versioned data lake library for SQL analytics on Parquet + Redis.
 Author: Levente Kupas
 Author-email: Levente Kupas <lkupas@kladnasoft.com>

{supertable-2.1.0 → supertable-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "supertable"
-version = "2.1.0"
+version = "2.2.0"
 description = "SuperTable — versioned data lake library for SQL analytics on Parquet + Redis."
 readme = "README.md"
 requires-python = ">=3.10"

{supertable-2.1.0 → supertable-2.2.0}/setup.py

@@ -19,7 +19,7 @@ long_description = readme.read_text(encoding="utf-8") if readme.exists() else ""
 
 setup(
     name="supertable",
-    version="2.1.0",
+    version="2.2.0",
     description="SuperTable — versioned data lake library for SQL analytics on Parquet + Redis.",
     long_description=long_description,
     long_description_content_type="text/markdown",

{supertable-2.1.0 → supertable-2.2.0}/supertable/__init__.py

@@ -25,7 +25,7 @@ See the ``supertable.demo`` package for runnable end-to-end demos and the
 project documentation for the full API surface.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 # Re-export the core public surface so users can do ``from supertable import …``
 # instead of remembering submodule paths.
@@ -39,6 +39,11 @@ from supertable.super_pipe import SuperPipe
 from supertable.redis_catalog import RedisCatalog
 from supertable.rbac.role_manager import RoleManager
 from supertable.rbac.user_manager import UserManager
+from supertable.errors import (
+    SupertableLookupError,
+    SuperTableNotFoundError,
+    TableNotFoundError,
+)
 
 __all__ = [
     "__version__",
@@ -55,4 +60,7 @@ __all__ = [
     "RedisCatalog",
     "RoleManager",
     "UserManager",
+    "SupertableLookupError",
+    "SuperTableNotFoundError",
+    "TableNotFoundError",
 ]

{supertable-2.1.0 → supertable-2.2.0}/supertable/audit/writer_redis.py

@@ -50,9 +50,24 @@ class RedisAuditWriter:
         self._instance_id = instance_id
         self._maxlen = maxlen
         self._stream = RK.audit_stream(org)
-        self._chain_key = RK.audit_chain_head(org, instance_id)
+        # The chain-head key is lazy: read-only callers (e.g. the
+        # audit reader) instantiate this class purely to use
+        # ``query()`` and pass instance_id="". Building the
+        # chain-head key with an empty instance_id would fail v2's
+        # segment validator, so defer construction until a method
+        # that actually needs it is called.
         self._ensure_stream()
 
+    @property
+    def _chain_key(self) -> str:
+        if not self._instance_id:
+            raise RuntimeError(
+                "RedisAuditWriter._chain_key requires a non-empty "
+                "instance_id; this writer was instantiated for "
+                "read-only use (query) and cannot save/load chain head."
+            )
+        return RK.audit_chain_head(self._org, self._instance_id)
+
     def _ensure_stream(self) -> None:
         """Create the stream and archival consumer group if they don't exist."""
         try:

{supertable-2.1.0 → supertable-2.2.0}/supertable/config/settings.py

@@ -282,6 +282,21 @@ class Settings:
     SUPERTABLE_SHARE_PRESIGN_TTL: int = 14400                # SUPERTABLE_SHARE_PRESIGN_TTL (seconds, default 4h)
     SUPERTABLE_SHARE_REFRESH_BUFFER: int = 600               # SUPERTABLE_SHARE_REFRESH_BUFFER (seconds, refresh 10min before expiry)
 
+    # ── Storage GC (deferred deletion of sunset parquets + old snapshot JSONs) ──
+    # Sunset parquet files and old snapshot JSONs are never deleted by the
+    # writer directly. When either flag is enabled, the writer XADDs paths
+    # to a per-table Redis STREAM after a successful leaf-CAS. A separate
+    # cleaner daemon (``python -m supertable.gc.cleaner``) drains entries
+    # older than ``SUPERTABLE_GC_DELAY_SEC`` and calls ``storage.delete()``.
+    # The delay window avoids the race where an in-flight reader's
+    # ``parquet_scan([...])`` resolves a file path right before the writer
+    # deletes it. Defaults below preserve today's behaviour (off, unlimited).
+    SUPERTABLE_SNAPSHOT_RETENTION: int = 0                   # SUPERTABLE_SNAPSHOT_RETENTION (0 = keep all snapshot JSONs)
+    SUPERTABLE_SUNSET_GC_ENABLED: bool = False               # SUPERTABLE_SUNSET_GC_ENABLED (delete sunset parquets via queue)
+    SUPERTABLE_GC_DELAY_SEC: int = 1800                      # SUPERTABLE_GC_DELAY_SEC (min age before cleaner deletes)
+    SUPERTABLE_GC_SLEEP_SEC: int = 60                        # SUPERTABLE_GC_SLEEP_SEC (cleaner loop sleep)
+    SUPERTABLE_GC_BATCH_SIZE: int = 500                      # SUPERTABLE_GC_BATCH_SIZE (max entries processed per table per tick)
+
 
     # ── Convenience properties ───────────────────────────────────────
 
@@ -528,6 +543,13 @@ def _build_settings() -> Settings:
         # Data Sharing
         SUPERTABLE_SHARE_PRESIGN_TTL=_env_int("SUPERTABLE_SHARE_PRESIGN_TTL", 14400),
         SUPERTABLE_SHARE_REFRESH_BUFFER=_env_int("SUPERTABLE_SHARE_REFRESH_BUFFER", 600),
+
+        # ── Storage GC ───────────────────────────────────────────────
+        SUPERTABLE_SNAPSHOT_RETENTION=_env_int("SUPERTABLE_SNAPSHOT_RETENTION", 0),
+        SUPERTABLE_SUNSET_GC_ENABLED=_env_bool("SUPERTABLE_SUNSET_GC_ENABLED", False),
+        SUPERTABLE_GC_DELAY_SEC=_env_int("SUPERTABLE_GC_DELAY_SEC", 1800),
+        SUPERTABLE_GC_SLEEP_SEC=_env_int("SUPERTABLE_GC_SLEEP_SEC", 60),
+        SUPERTABLE_GC_BATCH_SIZE=_env_int("SUPERTABLE_GC_BATCH_SIZE", 500),
     )
 
 

{supertable-2.1.0 → supertable-2.2.0}/supertable/data_reader.py

@@ -10,6 +10,7 @@ from typing import Optional, Tuple, Any, List, Dict
 import pandas as pd
 
 from supertable.config.defaults import logger
+from supertable.errors import SuperTableNotFoundError, TableNotFoundError
 from supertable.storage.storage_factory import get_storage
 from supertable.storage.storage_interface import StorageInterface
 from supertable.utils.timer import Timer
@@ -59,6 +60,44 @@ class DataReader:
     def _lp(self, msg: str) -> str:
         return f"{self._log_ctx}{msg}"
 
+    def _assert_targets_exist(self, physical_tables) -> None:
+        """Fail fast if any referenced (super, simple) is missing in Redis.
+
+        The read path must never create catalog entries as a side effect
+        of resolving a query. ``SuperTable`` / ``SimpleTable``
+        constructors used to do exactly that for callers that didn't pass
+        ``create_if_missing=False`` — this guard is the SDK-level
+        invariant that says "reads cannot mint tables".
+
+        Raises:
+            SuperTableNotFoundError: when the supertable's
+                ``meta:root`` pointer is missing.
+            TableNotFoundError: when the simple table's
+                ``meta:leaf:doc:{simple}`` pointer is missing.
+        """
+        if not physical_tables:
+            return
+        # One catalog handle for the whole loop — cheaper than letting
+        # each .exists() call open a fresh connection.
+        catalog = RedisCatalog()
+        # Dedup by (super, simple) — SQL may mention the same table
+        # multiple times via different aliases.
+        seen = set()
+        for td in physical_tables:
+            super_name = td.super_name
+            simple_name = td.simple_name
+            if not super_name or not simple_name:
+                continue
+            key = (super_name, simple_name)
+            if key in seen:
+                continue
+            seen.add(key)
+            if not catalog.root_exists(self.organization, super_name):
+                raise SuperTableNotFoundError(self.organization, super_name)
+            if not catalog.leaf_exists(self.organization, super_name, simple_name):
+                raise TableNotFoundError(
+                    self.organization, super_name, simple_name
+                )
 
     def execute(
         self,
@@ -90,6 +129,16 @@ class DataReader:
         )
 
         try:
+            # Read-path policy: reads never create. Verify every
+            # referenced (super, simple) exists in the Redis catalog
+            # *before* the estimator / executor get a chance to
+            # side-effect-bootstrap them via SuperTable constructor
+            # calls. On a miss this raises SuperTableNotFoundError /
+            # TableNotFoundError, which the surrounding ``except`` turns
+            # into the same (empty_df, Status.ERROR, message) tuple as
+            # every other read failure — no state is touched.
+            self._assert_targets_exist(physical_tables)
+
             # Make executor aware of storage for presign retry
             executor = Executor(storage=self.storage, organization=self.organization)
 

{supertable-2.1.0 → supertable-2.2.0}/supertable/data_writer.py

@@ -11,6 +11,9 @@ import polars
 from polars import DataFrame
 
 from supertable.config.defaults import logger
+from supertable.config.settings import settings
+from supertable.gc.queue import collect_old_snapshot_paths, enqueue_deletions
+from supertable.monitoring.partitions import MONITORING_SINK_TABLES
 from supertable.monitoring_writer import MonitoringWriter  # async monitoring
 from supertable.super_table import SuperTable
 from supertable import redis_keys as RK
@@ -442,6 +445,46 @@ class DataWriter:
                 self.catalog.bump_root(self.super_table.organization, self.super_table.super_name, now_ms=now_ms)
                 mark("bump_root")
 
+                # --- Enqueue deferred deletions (post-CAS, post-bump) ----------
+                # Strict ordering matters: leaf-CAS + root-bump have committed
+                # the new snapshot as the authoritative state. Only NOW is it
+                # safe to schedule physical deletion of files that the old
+                # snapshot still references — any reader that loaded the
+                # previous leaf payload will finish before the cleaner's delay
+                # window expires.
+                #
+                # Both blocks are best-effort: enqueue_deletions and
+                # collect_old_snapshot_paths swallow Redis/storage errors and
+                # log a warning. A GC failure must never fail the write.
+                try:
+                    _org = self.super_table.organization
+                    _sup = self.super_table.super_name
+                    if settings.SUPERTABLE_SUNSET_GC_ENABLED and sunset_files:
+                        enqueue_deletions(
+                            self.catalog,
+                            _org, _sup, simple_name,
+                            "parquet",
+                            list(sunset_files),
+                            write_id=qid,
+                        )
+                    if settings.SUPERTABLE_SNAPSHOT_RETENTION > 0:
+                        old_paths = collect_old_snapshot_paths(
+                            new_snapshot_dict,
+                            self.super_table.storage,
+                            settings.SUPERTABLE_SNAPSHOT_RETENTION,
+                        )
+                        if old_paths:
+                            enqueue_deletions(
+                                self.catalog,
+                                _org, _sup, simple_name,
+                                "snapshot",
+                                old_paths,
+                                write_id=qid,
+                            )
+                except Exception as e:
+                    logger.warning(lp(f"GC enqueue failed (write still succeeded): {e}"))
+                mark("gc_enqueue")
+
                 # --- Store schema + table name in Redis (permanent, not cache) ---
                 try:
                     schema_raw = new_snapshot_dict.get("schema", {})
@@ -533,8 +576,14 @@ class DataWriter:
         # Monitoring enqueue + flush is fully outside any data locks.
         # MonitoringWriter.__exit__ calls request_flush() so the metric is
         # guaranteed to reach Redis before this scope closes.
+        #
+        # Loop guard: writes targeted at a monitoring sink table
+        # (``__writes__``/``__reads__``/``__mcp__``/``__plans__``)
+        # are deliberately not measured — the external orchestrator
+        # that drained the partition is *writing back* the metric,
+        # and re-emitting it would create a 1:1 amplification cycle.
         try:
-            if stats_payload is not None:
+            if stats_payload is not None and simple_name not in MONITORING_SINK_TABLES:
                 # Monitoring is org-wide as of SDK 2.2.0 — record the
                 # touched supertable in the payload's ``supertables``
                 # field. A DataWriter only touches one supertable, but

{supertable-2.1.0 → supertable-2.2.0}/supertable/demo/quickstart/defaults.py

@@ -20,7 +20,7 @@ defaults.default.IS_SHOW_TIMING = True
 
 # --- Identity ---------------------------------------------------------------
 organization = "kladna-soft"
-super_name = "example"
+super_name = "demo"
 simple_name = "facts"
 
 # --- Roles (must match those created in 1.2. create_roles.py) ---------------

{supertable-2.1.0 → supertable-2.2.0}/supertable/engine/data_estimator.py

@@ -306,7 +306,15 @@ class DataEstimator:
 
             for simple_name in tables:
                 snapshots = self._filter_snapshots(super_name, simple_name, all_snapshots)
-                super_table = SuperTable(super_name, self.organization)
+                # Defence in depth: the read path must never bootstrap a
+                # missing supertable. ``DataReader._assert_targets_exist``
+                # is the primary guard at the entry point; this kwarg
+                # ensures any other caller of ``DataEstimator`` (or any
+                # future code path) cannot accidentally side-effect a
+                # creation through the SuperTable constructor.
+                super_table = SuperTable(
+                    super_name, self.organization, create_if_missing=False,
+                )
 
                 parquet_files: List[str] = []
                 schema: Set[str] = set()

supertable-2.2.0/supertable/errors.py

@@ -0,0 +1,75 @@
+# route: supertable.errors
+"""
+Public exception hierarchy for SuperTable.
+
+The exceptions defined here are part of the SDK's stable public surface
+and are raised at well-known boundaries (read-path pre-flight checks,
+constructor opt-outs, etc.). API layers wrap them into HTTP responses;
+CLI layers print their messages directly.
+
+Hierarchy
+---------
+
+    LookupError                                 (stdlib)
+      └── SupertableLookupError                 (this module)
+            ├── SuperTableNotFoundError
+            └── TableNotFoundError
+
+Inheriting from the stdlib ``LookupError`` means existing
+``except LookupError`` / ``except KeyError`` callers keep working — every
+SuperTable lookup failure is a "key not found" at heart.
+"""
+from __future__ import annotations
+
+
+class SupertableLookupError(LookupError):
+    """Base for catalog lookup failures on read paths.
+
+    Carries the ``organization`` it was raised against so API/CLI layers
+    can format the error without re-parsing the message.
+    """
+
+    def __init__(self, message: str, organization: str):
+        super().__init__(message)
+        self.organization = organization
+
+
+class SuperTableNotFoundError(SupertableLookupError):
+    """Raised when a SuperTable name is referenced but no Redis ``meta:root``
+    pointer exists for it.
+
+    Read-side code (``DataReader``, ``MetaReader``, ``DataEstimator``)
+    raises this instead of silently bootstrapping a new supertable as a
+    side effect of constructing the Python object.
+    """
+
+    def __init__(self, organization: str, super_name: str):
+        super().__init__(
+            f"SuperTable not found: {organization}/{super_name}",
+            organization=organization,
+        )
+        self.super_name = super_name
+
+
+class TableNotFoundError(SupertableLookupError):
+    """Raised when a SimpleTable (``super.simple``) is referenced but no
+    Redis ``meta:leaf:doc:{simple}`` pointer exists for it.
+
+    Read-side code raises this instead of silently bootstrapping a new
+    empty table as a side effect of constructing the Python object.
+    """
+
+    def __init__(self, organization: str, super_name: str, simple_name: str):
+        super().__init__(
+            f"Table not found: {organization}/{super_name}/{simple_name}",
+            organization=organization,
+        )
+        self.super_name = super_name
+        self.simple_name = simple_name
+
+
+__all__ = [
+    "SupertableLookupError",
+    "SuperTableNotFoundError",
+    "TableNotFoundError",
+]

supertable-2.2.0/supertable/gc/__init__.py

@@ -0,0 +1,26 @@
+# route: supertable.gc
+"""
+Deferred-deletion garbage collection for SuperTable storage.
+
+The data writer never deletes files inline. When the GC flags are enabled
+(``SUPERTABLE_SUNSET_GC_ENABLED`` / ``SUPERTABLE_SNAPSHOT_RETENTION``) the
+writer XADDs paths to a per-table Redis STREAM after a successful leaf-CAS.
+A long-running ``GCCleaner`` daemon (one per org) drains entries older than
+``SUPERTABLE_GC_DELAY_SEC`` and calls ``storage.delete()`` on each path.
+
+The delay window is what makes deletion safe under concurrent reads: a
+query that resolved the leaf payload right before the writer committed
+finishes long before the cleaner touches the file.
+"""
+
+from supertable.gc.queue import (
+    collect_old_snapshot_paths,
+    enqueue_deletions,
+    nuke_stream,
+)
+
+__all__ = [
+    "collect_old_snapshot_paths",
+    "enqueue_deletions",
+    "nuke_stream",
+]

supertable-2.2.0/supertable/gc/cleaner.py

@@ -0,0 +1,258 @@
+# route: supertable.gc.cleaner
+"""
+GC orchestration primitives — the **library** surface.
+
+This module exposes :class:`GCCleaner`, a pure orchestration object
+whose only state-modifying operation is :meth:`GCCleaner.tick`. One
+``tick()`` is one full pass over the org's per-table GC streams: drain
+entries older than the configured delay, ``storage.delete()`` each
+referenced path, ``XDEL`` the processed entries, return a stats dict.
+
+The expected usage pattern is **caller-owned scheduling** — your
+service decides when to call ``tick()``:
+
+    cleaner = GCCleaner(org="acme", catalog=catalog, storage=storage,
+                       delay_sec=1800, batch_size=500)
+    while not service.shutdown_requested:
+        stats = cleaner.tick()
+        service.publish_metrics(stats)
+        service.sleep(60)
+
+For deployments that don't already have a scheduler, the convenience
+daemon in :mod:`supertable.gc.daemon` wraps this class with a
+``run_forever`` loop and a CLI entrypoint. **Most deployments should
+prefer calling ``tick()`` directly from their own scheduler** —
+running ``run_forever`` is just here so that single-node installs
+have a one-command setup path.
+
+The delay window (``SUPERTABLE_GC_DELAY_SEC``) is the safety
+guarantee: by the time the cleaner touches a file, any in-flight
+reader that resolved the leaf payload before the writer committed has
+long since finished. We never delete a file that's still reachable
+from any reader's plan.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from supertable import redis_keys as RK
+from supertable.config.settings import settings
+
+logger = logging.getLogger(__name__)
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _decode(v: Any) -> str:
+    """Decode a redis-py value (bytes or str) to str."""
+    if isinstance(v, bytes):
+        try:
+            return v.decode("utf-8")
+        except UnicodeDecodeError:
+            return v.decode("utf-8", errors="replace")
+    return v
+
+
+def _decode_fields(fields: Dict[Any, Any]) -> Dict[str, str]:
+    """Decode a redis-py stream-entry field dict to {str: str}."""
+    return {_decode(k): _decode(v) for k, v in (fields or {}).items()}
+
+
+class GCCleaner:
+    """Per-org cleaner — orchestration primitive.
+
+    Calling :meth:`tick` performs one full pass over the org's GC
+    streams. It is intentionally **pure orchestration**: no loops, no
+    threads, no signal handlers. The caller's service is expected to
+    own scheduling, retries, and shutdown.
+
+    For deployments that don't have an external scheduler, the
+    convenience wrapper in :mod:`supertable.gc.daemon` adds a
+    ``run_forever`` loop and a CLI entrypoint on top of this class.
+
+    Parameters
+    ----------
+    org:
+        Organisation name this cleaner is responsible for.
+    catalog:
+        ``RedisCatalog`` (or any object with a ``.r`` redis-py client).
+    storage:
+        ``StorageInterface`` instance used to delete files.
+    delay_sec, sleep_sec, batch_size:
+        Override the corresponding ``settings.*`` defaults. Useful for
+        tests; production code should leave these as ``None`` and pick
+        up the env-driven settings. ``sleep_sec`` is only consulted by
+        the daemon wrapper and has no effect on ``tick()`` itself.
+    """
+
+    def __init__(
+        self,
+        org: str,
+        catalog: Any,
+        storage: Any,
+        *,
+        delay_sec: Optional[int] = None,
+        sleep_sec: Optional[int] = None,
+        batch_size: Optional[int] = None,
+    ) -> None:
+        if not org:
+            raise ValueError("GCCleaner: org is required")
+        self.org = org
+        self.catalog = catalog
+        self.storage = storage
+        self.delay_sec = int(delay_sec if delay_sec is not None else settings.SUPERTABLE_GC_DELAY_SEC)
+        self.sleep_sec = int(sleep_sec if sleep_sec is not None else settings.SUPERTABLE_GC_SLEEP_SEC)
+        self.batch_size = int(batch_size if batch_size is not None else settings.SUPERTABLE_GC_BATCH_SIZE)
+        if self.delay_sec < 0:
+            self.delay_sec = 0
+        if self.sleep_sec < 1:
+            self.sleep_sec = 1
+        if self.batch_size < 1:
+            self.batch_size = 1
+
+        # ``_stop`` is consulted by :meth:`tick` between streams so the
+        # daemon wrapper (or a test) can interrupt a long-running tick.
+        # The library surface itself never touches it after init.
+        self._stop = threading.Event()
+
+    # ── Lifecycle ────────────────────────────────────────────────────
+
+    def stop(self) -> None:
+        """Signal an in-progress :meth:`tick` to bail early.
+
+        Used by the daemon wrapper and tests. After calling ``stop()``,
+        a subsequent ``tick()`` returns as soon as the current stream
+        finishes. The stop flag is not auto-reset — to re-use the
+        cleaner after a stop, instantiate a new one (cheap; no
+        persistent state).
+        """
+        self._stop.set()
+
+    # ── One pass ─────────────────────────────────────────────────────
+
+    def tick(self) -> Dict[str, int]:
+        """Process every per-table stream once. Returns stats dict.
+
+        Stats keys: ``streams_processed``, ``deleted``,
+        ``deleted_parquet``, ``deleted_snapshot``, ``errors``.
+
+        Idempotent: re-calling produces the same effect if no new
+        entries appeared. Safe to call concurrently from multiple
+        processes — the worst case is two cleaners XDEL-ing the same
+        entry (Redis tolerates this) and double-attempting a
+        ``storage.delete`` (also idempotent via ``FileNotFoundError``).
+        """
+        stats = {
+            "streams_processed": 0,
+            "deleted": 0,
+            "deleted_parquet": 0,
+            "deleted_snapshot": 0,
+            "errors": 0,
+        }
+
+        cutoff_ms = _now_ms() - self.delay_sec * 1000
+        if cutoff_ms < 0:
+            cutoff_ms = 0
+        cutoff_id = f"{cutoff_ms}-0"
+
+        for stream_key in self._discover_streams():
+            if self._stop.is_set():
+                break
+            try:
+                processed, by_kind = self._drain_stream(stream_key, cutoff_id)
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "[gc-cleaner] org=%s stream=%s drain failed: %s",
+                    self.org, stream_key, e,
+                )
+                stats["errors"] += 1
+                continue
+            stats["streams_processed"] += 1
+            stats["deleted"] += processed
+            stats["deleted_parquet"] += by_kind.get("parquet", 0)
+            stats["deleted_snapshot"] += by_kind.get("snapshot", 0)
+
+        return stats
+
+    # ── Internals ────────────────────────────────────────────────────
+
+    def _discover_streams(self) -> Iterable[str]:
+        """SCAN the org's GC streams and yield each key as a str."""
+        r = getattr(self.catalog, "r", None)
+        if r is None:
+            return []
+        pattern = RK.gc_pending_pattern_for_org(self.org)
+        try:
+            return [_decode(k) for k in r.scan_iter(match=pattern, count=512)]
+        except Exception as e:  # noqa: BLE001
+            logger.warning("[gc-cleaner] org=%s SCAN failed: %s", self.org, e)
+            return []
+
+    def _drain_stream(
+        self, stream_key: str, cutoff_id: str
+    ) -> Tuple[int, Dict[str, int]]:
+        """XRANGE one stream up to cutoff, delete files, XDEL entries.
+
+        Returns ``(processed_count, by_kind)`` where ``by_kind`` maps
+        ``"parquet"|"snapshot"`` → count. Re-raises Redis errors so the
+        caller's per-stream error budget tracks them.
+        """
+        r = self.catalog.r
+        # Inclusive bounds: "-" = the very first id, "<cutoff_ms>-0" =
+        # the smallest id at the cutoff millisecond. Anything strictly
+        # after the cutoff is not returned.
+        entries = r.xrange(stream_key, min="-", max=cutoff_id, count=self.batch_size)
+        if not entries:
+            return 0, {}
+
+        deleted = 0
+        by_kind: Dict[str, int] = {"parquet": 0, "snapshot": 0}
+        to_xdel: List[bytes] = []
+
+        for entry_id, raw_fields in entries:
+            if self._stop.is_set():
+                break
+            fields = _decode_fields(raw_fields)
+            kind = fields.get("kind", "")
+            path = fields.get("path", "")
+            if not path or kind not in ("parquet", "snapshot"):
+                # Malformed entry — XDEL it so it doesn't block progress
+                to_xdel.append(entry_id)
+                continue
+
+            try:
+                self.storage.delete(path)
+                deleted += 1
+                by_kind[kind] = by_kind.get(kind, 0) + 1
+            except FileNotFoundError:
+                # Idempotent: already gone (another cleaner, manual
+                # removal, etc.) — still XDEL the entry.
+                pass
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "[gc-cleaner] storage.delete failed for %s (kind=%s): %s",
+                    path, kind, e,
+                )
+                # Leave entry on the stream so we retry next tick.
+                continue
+
+            to_xdel.append(entry_id)
+
+        if to_xdel:
+            try:
+                r.xdel(stream_key, *to_xdel)
+            except Exception as e:  # noqa: BLE001
+                logger.warning(
+                    "[gc-cleaner] XDEL failed on %s for %d entries: %s",
+                    stream_key, len(to_xdel), e,
+                )
+
+        return deleted, by_kind
+
+
+__all__ = ["GCCleaner"]