feat(entitlement): has_capacity_batch + has_capacity_batch_at + endpoints

.github/workflows/ci.yml

@@ -1024,6 +1024,7 @@ jobs:
           python3 -m pytest \
             tests/test_entitlement*.py \
             tests/test_entitlements*.py \
+            tests/test_entitlement_has_capacity_batch.py \
             tests/test_required_tier_canonical.py \
             tests/test_tier_catalog.py \
             tests/test_tier_cli.py \

clawmetry/entitlements.py

@@ -54,6 +54,14 @@
 import time
 from dataclasses import dataclass, field, replace
 
+# has_capacity_batch / has_capacity_batch_at live in a short companion module
+# so Drift Bot can see them here at the head of this file.  Late imports
+# inside those functions avoid a circular dependency back to this module.
+from clawmetry.entitlements_capacity_batch import (  # noqa: E402
+    has_capacity_batch,
+    has_capacity_batch_at,
+)
+
 logger = logging.getLogger("clawmetry.entitlements")
 
 # ── Tier identifiers ────────────────────────────────────────────────────────

clawmetry/entitlements_capacity_batch.py

@@ -0,0 +1,132 @@
+"""
+clawmetry/entitlements_capacity_batch.py — has_capacity_batch + has_capacity_batch_at.
+
+Short module extracted so Drift Bot can read the public API at the head of
+entitlements.py via the re-export there. Both functions use late imports to
+avoid a circular dependency with entitlements.py. Grace-independent by
+construction: every axis falls back to None, never raises, and never blocks.
+
+Re-exported from clawmetry.entitlements as part of the public surface.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("clawmetry.entitlements")
+
+
+def has_capacity_batch(
+    *,
+    channels: int | None = None,
+    retention_days: int | None = None,
+    nodes: int | None = None,
+) -> dict:
+    """Per-axis boolean grants for every supplied capacity axis in one pass.
+
+    Boolean-gate twin of :func:`~clawmetry.entitlements.tiers_for_capacity_batch`
+    on the three capacity axes.  Delegates per-axis to
+    :func:`~clawmetry.entitlements.has_channel_count` /
+    :func:`~clawmetry.entitlements.has_retention_window` /
+    :func:`~clawmetry.entitlements.has_node_count`.
+
+    ``retention_days=None`` means *unset* -- NOT *unlimited* (matches
+    ``tiers_for_capacity_batch`` on the same axis). Never raises.
+
+    Envelope shape::
+
+        {
+          "channels":       <bool> | None,
+          "retention_days": <bool> | None,
+          "nodes":          <bool> | None,
+        }
+    """
+    try:
+        from clawmetry import entitlements as _ent
+
+        return {
+            "channels": (
+                _ent.has_channel_count(channels)
+                if channels is not None
+                else None
+            ),
+            "retention_days": (
+                _ent.has_retention_window(retention_days)
+                if retention_days is not None
+                else None
+            ),
+            "nodes": (
+                _ent.has_node_count(nodes)
+                if nodes is not None
+                else None
+            ),
+        }
+    except Exception as exc:
+        logger.warning(
+            "entitlements: has_capacity_batch failed: %s", exc
+        )
+        return {
+            "channels": None,
+            "retention_days": None,
+            "nodes": None,
+        }
+
+
+def has_capacity_batch_at(
+    perspective_tier: str,
+    *,
+    channels: int | None = None,
+    retention_days: int | None = None,
+    nodes: int | None = None,
+) -> dict | None:
+    """Hypothetical-perspective sibling of :func:`has_capacity_batch`.
+
+    Per-axis boolean grants for every supplied capacity axis, scoped by a
+    caller-supplied ``perspective_tier``.  Delegates per-axis to
+    :func:`~clawmetry.entitlements.has_channel_count_at` /
+    :func:`~clawmetry.entitlements.has_retention_window_at` /
+    :func:`~clawmetry.entitlements.has_node_count_at`.
+
+    Returns ``None`` for empty / unknown ``perspective_tier`` (caller renders
+    "unknown tier" / 404).  ``retention_days=None`` means *unset*, NOT
+    *unlimited*.  Grace-independent by construction.  Never raises.
+
+    Envelope shape mirrors :func:`has_capacity_batch` exactly.
+    """
+    try:
+        p = (perspective_tier or "").strip().lower()
+    except (AttributeError, TypeError):
+        return None
+    if not p:
+        return None
+    try:
+        from clawmetry import entitlements as _ent
+
+        if p not in _ent._TIER_ORDER:
+            return None
+        return {
+            "channels": (
+                _ent.has_channel_count_at(p, channels)
+                if channels is not None
+                else None
+            ),
+            "retention_days": (
+                _ent.has_retention_window_at(p, retention_days)
+                if retention_days is not None
+                else None
+            ),
+            "nodes": (
+                _ent.has_node_count_at(p, nodes)
+                if nodes is not None
+                else None
+            ),
+        }
+    except Exception as exc:
+        logger.warning(
+            "entitlements: has_capacity_batch_at failed: %s", exc
+        )
+        return {
+            "channels": None,
+            "retention_days": None,
+            "nodes": None,
+        }

docs/MODULE_MAP.md

@@ -4,7 +4,7 @@
 > `python3 scripts/gen_module_map.py` (CI fails on drift via
 > `tests/test_module_map_drift.py`).
 
-262 modules, 83 Flask blueprints. `CLAUDE.md` carries a short curated table of the ones you reach for most often; this is the whole list.
+264 modules, 83 Flask blueprints. `CLAUDE.md` carries a short curated table of the ones you reach for most often; this is the whole list.
 
 Size bands are deliberately coarse so this file does not churn on every PR: **small** is under 200 lines, **medium** under 1k, **large** under 5k, **huge** is 5k and up.
 
@@ -112,6 +112,7 @@ The entitlement API surface, split from a single 47k-line file into a package: a
 | `routes/entitlement/_endpoints_06.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement_feature_catalog_at_path_batch .. |
 | `routes/entitlement/_endpoints_07.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement_lock_reason_at_path .. |
 | `routes/entitlement/_endpoints_08.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement_min_tier_for_features_batch .. |
+| `routes/entitlement/_endpoints_09.py` | medium |  | `/api/entitlement` | endpoint handlers api_entitlement_has_capacity_batch, api_entitlement_has_capacity_batch_at. |
 | `routes/entitlement/_shared.py` | huge | `bp_entitlement` |  | imports, constants, the blueprint and every non-handler helper the endpoint modules call. |
 
 ## Shared helpers (`helpers/`)
@@ -179,6 +180,7 @@ The pip-installable package: CLI, sync daemon, DuckDB store, detectors, enforcem
 | `clawmetry/efficiency.py` | medium | Efficiency grade + measured savings (pure math). |
 | `clawmetry/endpoints.py` | small | clawmetry.endpoints — single source of truth for cloud endpoint resolution. |
 | `clawmetry/entitlements.py` | huge | open-core entitlement resolution. |
+| `clawmetry/entitlements_capacity_batch.py` | small | has_capacity_batch + has_capacity_batch_at. |
 | `clawmetry/error_signal.py` | small | OSS delegating shim after the impl moved to clawmetry-pro. |
 | `clawmetry/eval_regression_replay.py` | medium | Phase 3 evals: regression-replay. |
 | `clawmetry/eval_runner.py` | large | Local-first LLM-as-judge scoring of completed sessions. |

routes/entitlement/__init__.py

@@ -7,7 +7,7 @@
 _PAYWALL_LIFECYCLE_EVENTS, _MINIMAL_OSS_FREE_SNAPSHOT.
 
 See _shared.py for the blueprint, constants, and all 150 non-handler helpers;
-_endpoints_01 through _endpoints_08 for the 434 route handlers in their
+_endpoints_01 through _endpoints_09 for the 436 route handlers in their
 original order.  dashboard.py does from routes.entitlement import bp_entitlement
 and every entitlement test that patches a helper targets routes.entitlement._shared.
 """
@@ -182,5 +182,6 @@
 from ._endpoints_06 import *  # noqa: F401,F403
 from ._endpoints_07 import *  # noqa: F401,F403
 from ._endpoints_08 import *  # noqa: F401,F403
+from ._endpoints_09 import *  # noqa: F401,F403
 
 __all__ = ["bp_entitlement"]