supertable 2.5.4__tar.gz → 2.5.5__tar.gz

{supertable-2.5.4/supertable.egg-info → supertable-2.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supertable
-Version: 2.5.4
+Version: 2.5.5
 Summary: SuperTable — versioned data lake library for SQL analytics on Parquet + Redis.
 Author-email: Levente Kupas <lkupas@kladnasoft.com>
 License-Expression: LicenseRef-FSL-1.1-ALv2

{supertable-2.5.4 → supertable-2.5.5}/pyproject.toml

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

{supertable-2.5.4 → supertable-2.5.5}/supertable/__init__.py

@@ -25,11 +25,48 @@ See the ``supertable.demo`` package for runnable end-to-end demos and the
 project documentation for the full API surface.
 """
 
-__version__ = "2.5.4"
+__version__ = "2.5.5"
 
+import os
 from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
+
+def _bootstrap_island_polars_cpu_limit() -> None:
+    """Apply an explicit Island CPU ceiling before Polars creates Rayon."""
+    raw = os.environ.get("SUPERTABLE_ISLAND_CPU_MAX")
+    if raw is None or not raw.strip():
+        return
+    try:
+        limit = int(raw.strip())
+    except ValueError:
+        raise RuntimeError(
+            "SUPERTABLE_ISLAND_CPU_MAX must be a non-negative integer"
+        ) from None
+    if limit < 0:
+        raise RuntimeError(
+            "SUPERTABLE_ISLAND_CPU_MAX must be a non-negative integer"
+        )
+    if limit == 0:
+        return
+    existing_raw = os.environ.get("POLARS_MAX_THREADS")
+    if existing_raw is not None and existing_raw.strip():
+        try:
+            existing = int(existing_raw.strip())
+        except ValueError:
+            raise RuntimeError(
+                "POLARS_MAX_THREADS must be a positive integer"
+            ) from None
+        if existing <= 0:
+            raise RuntimeError(
+                "POLARS_MAX_THREADS must be a positive integer"
+            )
+        limit = min(limit, existing)
+    os.environ["POLARS_MAX_THREADS"] = str(limit)
+
+
+_bootstrap_island_polars_cpu_limit()
+
 # This public alias predates the ``supertable.engine`` implementation package.
 # Importing the tiny enum after the now-lazy package is initialized ensures
 # later imports of engine submodules cannot replace ``supertable.engine`` with
@@ -37,7 +74,9 @@ from typing import TYPE_CHECKING, Any
 from supertable.engine.engine_enum import Engine as engine
 
 
-# Importing the package is intentionally cheap and side-effect-free.  The
+# Importing the package is intentionally cheap and does not import native data
+# engines. The only bootstrap side effect is the explicit Polars CPU ceiling
+# above, which must exist before Rayon is initialized. The
 # public convenience exports are loaded on first use (PEP 562) so importing
 # ``supertable`` does not import PyArrow/Polars, connect to Redis, probe the
 # filesystem, or initialise an application home.

{supertable-2.5.4 → supertable-2.5.5}/supertable/config/settings.py

@@ -263,7 +263,8 @@ class Settings:
     # Parquet files; selective remote Island scans use the range cache below.
     SUPERTABLE_ISLAND_CACHE_ENABLED: bool = True       # SUPERTABLE_ISLAND_CACHE_ENABLED
     SUPERTABLE_ISLAND_CACHE_DIR: str = ""              # SUPERTABLE_ISLAND_CACHE_DIR
-    SUPERTABLE_ISLAND_CACHE_MAX_BYTES: int = 20 * 1024 * 1024 * 1024  # SUPERTABLE_ISLAND_CACHE_MAX_BYTES
+    # Zero derives a safe share of currently free cache-filesystem capacity.
+    SUPERTABLE_ISLAND_CACHE_MAX_BYTES: int = 0  # SUPERTABLE_ISLAND_CACHE_MAX_BYTES
     # Published Parquet objects are immutable/version-addressed.  Capacity and
     # integrity, rather than age, rotate the local object cache by default.
     # Operators may still opt into an idle TTL with an explicitly positive
@@ -277,7 +278,7 @@ class Settings:
     # for. Every cached interval is sealed to the provider version/ETag.
     SUPERTABLE_ISLAND_RANGE_CACHE_ENABLED: bool = True   # SUPERTABLE_ISLAND_RANGE_CACHE_ENABLED
     SUPERTABLE_ISLAND_RANGE_CACHE_DIR: str = ""          # SUPERTABLE_ISLAND_RANGE_CACHE_DIR
-    SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES: int = 20 * 1024 * 1024 * 1024  # SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES
+    SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES: int = 0  # SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES
     # Immutable, version-sealed ranges rotate on capacity/corruption by default.
     # A positive value explicitly restores idle-TTL eviction.
     SUPERTABLE_ISLAND_RANGE_CACHE_TTL_SEC: int = 0  # SUPERTABLE_ISLAND_RANGE_CACHE_TTL_SEC
@@ -287,10 +288,11 @@ class Settings:
     # quotas are hard; Polars/Arrow scan pools are process-global, so decoded
     # scan-memory estimates are conservative routing/admission guards rather
     # than an in-process per-query allocator cap.
-    SUPERTABLE_ISLAND_MEMORY_FRACTION: float = 0.60       # SUPERTABLE_ISLAND_MEMORY_FRACTION
-    SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION: float = 0.80  # SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION
+    SUPERTABLE_ISLAND_MEMORY_FRACTION: float = 1.0        # SUPERTABLE_ISLAND_MEMORY_FRACTION
+    SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION: float = 1.0  # SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION
     SUPERTABLE_ISLAND_MAX_MEMORY_BYTES: int = 0           # SUPERTABLE_ISLAND_MAX_MEMORY_BYTES
-    SUPERTABLE_ISLAND_MAX_RESULT_BYTES: int = 512 * 1024 * 1024  # SUPERTABLE_ISLAND_MAX_RESULT_BYTES
+    # Zero derives the effective container memory available to this process.
+    SUPERTABLE_ISLAND_MAX_RESULT_BYTES: int = 0  # SUPERTABLE_ISLAND_MAX_RESULT_BYTES
     SUPERTABLE_ISLAND_CPU_MAX: int = 0                    # SUPERTABLE_ISLAND_CPU_MAX
     SUPERTABLE_ISLAND_IO_WORKERS_MAX: int = 16            # SUPERTABLE_ISLAND_IO_WORKERS_MAX
     # Hard wall-clock bound for one admitted IslandDB execution.  The bound is
@@ -637,7 +639,7 @@ def _build_settings() -> Settings:
         SUPERTABLE_ISLAND_CACHE_ENABLED=_env_bool("SUPERTABLE_ISLAND_CACHE_ENABLED", True),
         SUPERTABLE_ISLAND_CACHE_DIR=_env_str("SUPERTABLE_ISLAND_CACHE_DIR"),
         SUPERTABLE_ISLAND_CACHE_MAX_BYTES=_env_int(
-            "SUPERTABLE_ISLAND_CACHE_MAX_BYTES", 20 * 1024 * 1024 * 1024,
+            "SUPERTABLE_ISLAND_CACHE_MAX_BYTES", 0,
         ),
         SUPERTABLE_ISLAND_CACHE_TTL_SEC=_env_int(
             "SUPERTABLE_ISLAND_CACHE_TTL_SEC", 0,
@@ -655,22 +657,22 @@ def _build_settings() -> Settings:
             "SUPERTABLE_ISLAND_RANGE_CACHE_DIR",
         ),
         SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES=_env_int(
-            "SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES", 20 * 1024 * 1024 * 1024,
+            "SUPERTABLE_ISLAND_RANGE_CACHE_MAX_BYTES", 0,
         ),
         SUPERTABLE_ISLAND_RANGE_CACHE_TTL_SEC=_env_int(
             "SUPERTABLE_ISLAND_RANGE_CACHE_TTL_SEC", 0,
         ),
         SUPERTABLE_ISLAND_MEMORY_FRACTION=_env_float(
-            "SUPERTABLE_ISLAND_MEMORY_FRACTION", 0.60,
+            "SUPERTABLE_ISLAND_MEMORY_FRACTION", 1.0,
         ),
         SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION=_env_float(
-            "SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION", 0.80,
+            "SUPERTABLE_ISLAND_GLOBAL_MEMORY_FRACTION", 1.0,
         ),
         SUPERTABLE_ISLAND_MAX_MEMORY_BYTES=_env_int(
             "SUPERTABLE_ISLAND_MAX_MEMORY_BYTES", 0,
         ),
         SUPERTABLE_ISLAND_MAX_RESULT_BYTES=_env_int(
-            "SUPERTABLE_ISLAND_MAX_RESULT_BYTES", 512 * 1024 * 1024,
+            "SUPERTABLE_ISLAND_MAX_RESULT_BYTES", 0,
         ),
         SUPERTABLE_ISLAND_CPU_MAX=_env_int(
             "SUPERTABLE_ISLAND_CPU_MAX", 0,

{supertable-2.5.4 → supertable-2.5.5}/supertable/data_reader.py

@@ -191,6 +191,9 @@ class _MonitoredResultStream:
         self._finalize_complete = False
         self._finalizing_thread: Optional[int] = None
         self._finalize_error: BaseException | None = None
+        add_terminal_callback = getattr(inner, "add_terminal_callback", None)
+        if callable(add_terminal_callback):
+            add_terminal_callback(self._inner_terminal)
 
     def __iter__(self):
         return self
@@ -251,6 +254,29 @@ class _MonitoredResultStream:
         with self._finalize_condition:
             return self._finalized
 
+    def _inner_terminal(self, kind: str) -> None:
+        if kind == "completed":
+            status, message = Status.OK.value, None
+        elif kind == "timed_out":
+            status, message = Status.ERROR.value, "result stream timed out"
+        elif kind == "cancelled":
+            status, message = Status.ERROR.value, "result stream cancelled"
+        elif kind == "failed":
+            status, message = Status.ERROR.value, _QUERY_STREAM_ERROR
+        else:
+            status = Status.ERROR.value
+            message = "result stream closed before exhaustion"
+        try:
+            self._finish(status, message)
+        except BaseException as exc:
+            # A watcher-thread callback cannot raise into the request thread.
+            # _finish retains the error so any later stream operation observes
+            # it; protected failure audit emission has already been attempted.
+            logger.error(
+                "stream terminal monitoring failed; error_type=%s",
+                safe_exception_type(exc),
+            )
+
     def __next__(self):
         try:
             batch = next(self._inner)
@@ -909,6 +935,9 @@ class DataReader:
         actual_engine = str(
             getattr(engine_used, "value", engine_used) or ""
         )[:64]
+        audit_outcome = (
+            Outcome.SUCCESS if outcome == "success" else Outcome.FAILURE
+        )
         emit(
             category=EventCategory.DATA_ACCESS,
             action=Actions.QUERY_EXECUTE,
@@ -930,7 +959,7 @@ class DataReader:
                 "column_count": max(0, int(result_columns)),
                 "outcome": outcome,
             },
-            outcome=Outcome.SUCCESS,
+            outcome=audit_outcome,
         )
 
     def _assert_targets_exist(self, physical_tables) -> None:
@@ -2113,6 +2142,7 @@ class DataReader:
                 })
                 stream_timer.capture_and_reset_timing(event="EXECUTING_QUERY")
                 stream_timer.capture_duration(event="TOTAL_EXECUTE")
+                monitoring_error: Optional[MonitoringPostExecutionError] = None
                 try:
                     extend_execution_plan(
                         query_plan_manager=stream_qpm,
@@ -2130,22 +2160,46 @@ class DataReader:
                     safe_cause = MonitoringDurabilityError(
                         "monitoring durability failure"
                     )
-                    raise MonitoringPostExecutionError(
+                    monitoring_error = MonitoringPostExecutionError(
                         organization=stream_qpm.organization,
                         super_name=stream_qpm.super_name,
                         query_id=str(getattr(stream_qpm, "query_id", "")),
                         status=final_status,
                         cause=safe_cause,
-                    ) from None
+                    )
                 finally:
                     stream_timer.capture_and_reset_timing(event="EXTENDING_PLAN")
-                if final_status == Status.OK.value:
-                    self._emit_successful_query_audit(
-                        role_name=role_name,
-                        engine_used=_engine_used,
-                        result_rows=result_rows,
-                        result_columns=result_columns,
+                audit_engine = _actual_engine_from_plan_stats(
+                    stream_plan_stats,
+                    fallback=_engine_used,
+                )
+                try:
+                    if final_status == Status.OK.value:
+                        self._emit_successful_query_audit(
+                            role_name=role_name,
+                            engine_used=audit_engine,
+                            result_rows=result_rows,
+                            result_columns=result_columns,
+                        )
+                    else:
+                        self._emit_successful_query_audit(
+                            role_name=role_name,
+                            engine_used=audit_engine,
+                            result_rows=result_rows,
+                            result_columns=result_columns,
+                            outcome="failure",
+                        )
+                except Exception:
+                    if final_status == Status.OK.value and monitoring_error is None:
+                        raise
+                    # Preserve the producer/cancellation or monitoring error
+                    # just as the materialized failure path does.
+                    logger.debug(
+                        self._lp("failed to emit query failure audit"),
+                        exc_info=True,
                     )
+                if monitoring_error is not None:
+                    raise monitoring_error
 
             return (
                 _MonitoredResultStream(result_value, _finalize_stream_monitoring),
@@ -2771,6 +2825,32 @@ def _engine_name(value: Any) -> str:
     return str(raw or "").strip().casefold()
 
 
+def _actual_engine_from_plan_stats(plan_stats: Any, *, fallback: Any) -> str:
+    """Resolve a stream's engine only after deferred delivery has finished."""
+    try:
+        stats = tuple(
+            entry for entry in (getattr(plan_stats, "stats", ()) or ())
+            if isinstance(entry, dict)
+        )
+        outcome = _latest_plan_stat(stats, "AUTO_ROUTING_OUTCOME")
+        if isinstance(outcome, dict):
+            actual = _engine_name(outcome.get("actual_engine"))
+            if actual:
+                return actual
+        recorded = _engine_name(_latest_plan_stat(stats, "ENGINE"))
+        if recorded:
+            return recorded
+        for entry in reversed(stats):
+            attempt = entry.get("ENGINE_ATTEMPT")
+            if isinstance(attempt, dict):
+                attempted = _engine_name(attempt.get("engine"))
+                if attempted:
+                    return attempted
+    except Exception:
+        pass
+    return _engine_name(fallback)
+
+
 def _update_query_out(
     reader: DataReader,
     out: Optional[Dict[str, Any]],
@@ -2837,14 +2917,10 @@ def _update_query_out(
     if not selected and isinstance(outcome, dict):
         selected = _engine_name(outcome.get("selected_engine"))
 
-    actual = ""
+    actual = _actual_engine_from_plan_stats(plan_stats, fallback="")
     fallback = False
     if isinstance(outcome, dict):
-        actual = _engine_name(outcome.get("actual_engine"))
         fallback = bool(outcome.get("fallback", False))
-    actual = actual or _engine_name(recorded_engine)
-    if not actual and engine_attempts:
-        actual = _engine_name(engine_attempts[-1].get("engine"))
     selected = selected or actual or requested
     if actual and selected and not isinstance(outcome, dict):
         fallback = actual != selected

{supertable-2.5.4 → supertable-2.5.5}/supertable/engine/adaptive_router.py

@@ -138,6 +138,7 @@ class RoutingFeatures:
     freshness_age_seconds: int = -1
     has_active_tombstone: bool = False
     streaming_result: bool = False
+    island_plan_evaluated: bool = False
     island_advice: str = ""
     island_cpu_workers: int = 0
     island_io_workers: int = 0
@@ -193,6 +194,7 @@ class RoutingFeatures:
             "stream" if self.streaming_result else "materialized",
             "tombstone" if self.has_active_tombstone else "clean",
             "fresh" if self.data_is_fresh else "stable",
+            "island_plan" if self.island_plan_evaluated else "no_island_plan",
             str(self.island_advice or "none"),
             str(self._magnitude_bucket(self.island_cpu_workers)),
             str(self._magnitude_bucket(self.island_io_workers)),
@@ -502,10 +504,23 @@ class AdaptiveEngineRouter:
             )
         if not features.source_bytes_complete:
             rejections[Engine.ISLANDDB].append("source byte estimate incomplete")
-        if features.island_advice not in {"island_in_memory", "island_spill"}:
+        if (
+            features.island_plan_evaluated
+            and features.island_advice not in {
+                "island_in_memory", "island_spill",
+            }
+        ):
             rejections[Engine.ISLANDDB].append(
                 "IslandDB resource plan is not executable"
             )
+        elif (
+            availability.island_enabled
+            and availability.island_supported
+            and not features.island_plan_evaluated
+        ):
+            rejections[Engine.ISLANDDB].append(
+                "IslandDB resource plan is unavailable"
+            )
 
         if not availability.spark_available:
             rejections[Engine.SPARK_SQL].append("no safe fitting Spark cluster")

{supertable-2.5.4 → supertable-2.5.5}/supertable/engine/data_estimator.py

@@ -1684,11 +1684,13 @@ class DataEstimator:
             return 0, False
         widths: List[int] = []
         for name in requested:
-            width = self._decoded_fixed_width(normalized_types.get(name))
+            normalized_type = str(
+                normalized_types.get(name) or ""
+            ).strip().casefold()
+            width = self._decoded_fixed_width(normalized_type)
             if (
                 width is None
-                and str(normalized_types.get(name) or "").strip().casefold()
-                == "binary"
+                and normalized_type in {"binary", "string", "utf8"}
             ):
                 bound = (max_value_bytes or {}).get(name)
                 if (
@@ -1696,9 +1698,12 @@ class DataEstimator:
                     and not isinstance(bound, bool)
                     and bound >= 0
                 ):
-                    # Variable Binary owns a 32-bit offset per value in
-                    # addition to its exactly sealed maximum payload width.
-                    width = int(bound) + 4
+                    # Binary owns a 32-bit offset; Polars' native UTF-8 value
+                    # representation can retain a 16-byte string view.  The
+                    # caller adds validity/alignment slack below.
+                    width = int(bound) + (
+                        4 if normalized_type == "binary" else 16
+                    )
             if width is None:
                 return 0, False
             widths.append(width)
@@ -2511,7 +2516,9 @@ class DataEstimator:
                     for file_key in survivors
                 )
                 for column_name, type_name in schema_types.items()
-                if str(type_name).strip().casefold() == "binary"
+                if str(type_name).strip().casefold() in {
+                    "binary", "string", "utf8",
+                }
                 and survivors
                 and all(
                     isinstance(resource_value_bounds.get(file_key), dict)

supertable-2.5.5/supertable/engine/disk_admission.py

@@ -0,0 +1,168 @@
+"""Cross-process disk admission for caches and IslandDB spill files."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import shutil
+import time
+import uuid
+from pathlib import Path
+
+from supertable.config.homedir import get_app_home
+
+
+_STALE_SECONDS = 24 * 60 * 60
+
+
+class DiskAdmissionUnavailable(RuntimeError):
+    """The shared filesystem reservation cannot be admitted."""
+
+
+def _existing_ancestor(path: str | os.PathLike[str]) -> Path:
+    candidate = Path(path).expanduser().resolve()
+    while not candidate.exists() and candidate != candidate.parent:
+        candidate = candidate.parent
+    return candidate
+
+
+def _reservation_root(path: str | os.PathLike[str]) -> Path:
+    probe = _existing_ancestor(path)
+    try:
+        device = os.stat(probe).st_dev
+    except OSError as exc:
+        raise DiskAdmissionUnavailable("cannot identify cache filesystem") from exc
+    base = Path(get_app_home()) / ".supertable-disk-admission"
+    try:
+        if os.stat(_existing_ancestor(base)).st_dev != device:
+            base = probe / ".supertable-disk-admission"
+    except OSError:
+        base = probe / ".supertable-disk-admission"
+    return base / str(device)
+
+
+def _read_size(path: Path) -> int:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            value = json.load(handle).get("size", 0)
+        return max(0, int(value))
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        return 0
+
+
+def _clean_stale(root: Path) -> None:
+    now = time.time()
+    try:
+        entries = tuple(root.iterdir())
+    except OSError:
+        return
+    for entry in entries:
+        if not entry.name.endswith(".json"):
+            continue
+        try:
+            if now - entry.stat().st_mtime > _STALE_SECONDS:
+                entry.unlink(missing_ok=True)
+                continue
+            with entry.open("r", encoding="utf-8") as handle:
+                payload = json.load(handle)
+            pid = payload.get("pid")
+            if isinstance(pid, int) and pid > 0 and pid != os.getpid():
+                try:
+                    os.kill(pid, 0)
+                except ProcessLookupError:
+                    entry.unlink(missing_ok=True)
+                except PermissionError:
+                    pass
+        except (OSError, ValueError, TypeError, json.JSONDecodeError):
+            try:
+                entry.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+class DiskReservation:
+    """An idempotent shared filesystem reservation."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._released = False
+
+    def release(self) -> None:
+        if self._released:
+            return
+        self._released = True
+        try:
+            self.path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    def __enter__(self) -> "DiskReservation":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+
+
+def reserve_disk(
+    path: str | os.PathLike[str],
+    size: int,
+    *,
+    min_free_bytes: int = 0,
+) -> DiskReservation | None:
+    """Atomically reserve bytes shared by cache and spill users."""
+    size = max(0, int(size))
+    if size == 0:
+        return None
+    root = _reservation_root(path)
+    root.mkdir(parents=True, exist_ok=True)
+    lock_path = root / ".lock"
+    with lock_path.open("a+") as lock:
+        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        _clean_stale(root)
+        try:
+            free = max(0, int(shutil.disk_usage(_existing_ancestor(path)).free))
+        except (OSError, ValueError, TypeError):
+            raise DiskAdmissionUnavailable("cannot inspect free disk space") from None
+        reserved = sum(
+            _read_size(entry)
+            for entry in root.iterdir()
+            if entry.name.endswith(".json")
+        )
+        if free - reserved - size < max(0, int(min_free_bytes)):
+            raise DiskAdmissionUnavailable(
+                "shared filesystem reservation would exhaust the disk reserve"
+            )
+        token = root / f"{os.getpid()}-{uuid.uuid4().hex}.json"
+        temporary = token.with_suffix(".tmp")
+        payload = {
+            "size": size,
+            "pid": os.getpid(),
+            "created_ns": time.time_ns(),
+        }
+        with temporary.open("x", encoding="utf-8") as handle:
+            json.dump(payload, handle, separators=(",", ":"))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, token)
+        fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+    return DiskReservation(token)
+
+
+def release_local_reservation(local_path: str | os.PathLike[str]) -> None:
+    """Release a shared token embedded in a cache reservation record."""
+    try:
+        with Path(local_path).open("r", encoding="utf-8") as handle:
+            token = json.load(handle).get("shared_token")
+        if token:
+            DiskReservation(Path(str(token))).release()
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        pass
+
+
+__all__ = [
+    "DiskAdmissionUnavailable",
+    "DiskReservation",
+    "release_local_reservation",
+    "reserve_disk",
+]