Split routes/entitlement.py: 1.84 MB and 434 routes in one file

ARCHITECTURE.md

@@ -453,7 +453,7 @@ ClawMetry is open-core. `clawmetry/entitlements.py` is the single source of
 truth for what an install may do, and for the runtime and channel catalogues
 that every count in this repo is derived from. `clawmetry/license.py` verifies
 self-hosted license keys offline with Ed25519, using the `cryptography`
-dependency rather than a new one. `routes/entitlement.py` exposes the resolved
+dependency rather than a new one. `routes/entitlement/` (a package: init re-exports flat namespace, shared helpers module, eight endpoint files with 434 handlers) exposes the resolved
 entitlement at `/api/entitlement*`.
 
 The resolver runs in **GRACE** mode until the announced enforce date: every

CLAUDE.md

@@ -21,7 +21,7 @@ See `ARCHITECTURE.md` for the full deep dive, and `docs/MODULE_MAP.md` (generate
 
 `docs/MODULE_MAP.md` is the **generated** inventory: every module, the blueprints it defines, the URL space it owns, and a coarse size band. `scripts/gen_module_map.py` regenerates it and CI fails when it drifts. The tables below are a short curated index of what you reach for most often, deliberately without line counts (they went stale within weeks every time they were written down).
 
-**Five files are big enough to change how you work on them**: `routes/entitlement.py` (~48k lines), `clawmetry/entitlements.py` (~31k), `clawmetry/sync.py` (~26k), `dashboard.py` (~21k), `clawmetry/local_store.py` (~20k). Drift Bot reads only the head of a long file, so anything added deep inside one is reported as "not implemented" forever. Put new capability in a new short module and re-export it, rather than appending 300 lines to a 20k-line file.
+**Five files are big enough to change how you work on them**: `routes/entitlement/` (~48k lines, now a package: a re-export init, a shared helpers module, and eight endpoint files), `clawmetry/entitlements.py` (~31k), `clawmetry/sync.py` (~26k), `dashboard.py` (~21k), `clawmetry/local_store.py` (~20k). Drift Bot reads only the head of a long file, so anything added deep inside one is reported as "not implemented" forever. Put new capability in a new short module and re-export it, rather than appending 300 lines to a 20k-line file.
 
 ### Core
 | File | Purpose |
@@ -50,7 +50,7 @@ All HTTP endpoints live here, organised by feature: 70 modules, 82 blueprints, l
 | `routes/hooks.py` | `bp_hooks` — hook install / status / uninstall per runtime, and the gate's decision log |
 | `routes/infra.py` | `bp_logs` + `bp_memory` + `bp_security` + `bp_config` — logs stream, memory files, security posture, cost-optimizer |
 | `routes/meta.py` | `bp_auth` + `bp_gateway` + `bp_otel` + `bp_version` + `bp_version_impact` + `bp_cloud_relay` + `bp_otlp_traces` — auth, gateway proxy, OTLP ingestion, version meta |
-| `routes/entitlement.py` | `bp_entitlement` — the resolved entitlement plus the preview / diff / batch family at `/api/entitlement*` |
+| `routes/entitlement/` | `bp_entitlement` — the resolved entitlement plus the preview / diff / batch family at `/api/entitlement*` (package: init re-exports flat namespace, shared helpers module, eight endpoint files with 434 handlers) |
 | `routes/alerts.py` | `bp_alerts` + `bp_budget` — alert rules, webhooks, velocity, budget config |
 | `routes/crons.py` | `bp_crons` — cron CRUD + run log + health summary |
 | `routes/signals.py` | `bp_signals` — Behaviour Signals read API: `/api/signals` (rate, count, eligible turns, trend, by model and runtime, coverage, plain-words headline), `/api/signals/<name>/sessions` (sessions, never phrases) |

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`).
 
-239 modules, 81 Flask blueprints. `CLAUDE.md` carries a short curated table of the ones you reach for most often; this is the whole list.
+247 modules, 81 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.
 
@@ -46,7 +46,6 @@ One module per feature, each owning one or more Flask blueprints. New endpoints
 | `routes/delegated.py` | small | `bp_delegated` | `/api/cursor`, `/api/delegated-usage` | Connect a Cursor account from the dashboard, and read delegated usage. |
 | `routes/device.py` | medium | `bp_device` | `/api/device`, `/device-preview` | Device snapshot — a compact, screen-sized JSON for hardware companions. |
 | `routes/dives.py` | medium | `bp_dives` | `/api/dives` | ClawMetry Dives: NL-to-SQL-to-chart over the local DuckDB store. |
-| `routes/entitlement.py` | huge | `bp_entitlement` | `/api/entitlement`, `/api/features`, `/api/license`, `/api/paywall`, `/api/runtimes`, `/api/tiers` | ``bp_entitlement``. |
 | `routes/evals.py` | medium | `bp_evals` | `/api/evals`, `/api/evaluators` | Eval (LLM-as-judge) endpoints. |
 | `routes/extensions.py` | small | `bp_extensions` | `/api/extensions` | diagnostic introspection for the entry-point plugin loader. |
 | `routes/fleet_history.py` | medium | `bp_fleet` | `/api/nodes`, `/fleet` | Multi-node fleet endpoints. |
@@ -97,6 +96,22 @@ One module per feature, each owning one or more Flask blueprints. New endpoints
 | `routes/usage.py` | huge | `bp_usage` | `/api/activity-today`, `/api/anomalies`, `/api/efficiency`, `/api/forward-progress`, `/api/model-attribution`, `/api/nemo-cap-status`, `/api/runtime-summary`, `/api/sessions`, `/api/skill-attribution`, `/api/skills`, `/api/token-attribution`, `/api/token-velocity`, `/api/usage` | Usage / analytics / anomaly / attribution endpoints. |
 | `routes/workspaces.py` | small | `bp_workspaces` | `/api/workspaces` | Multi-profile OpenClaw workspace discovery + switcher. |
 
+## Entitlement route package (`routes/entitlement/`)
+
+The entitlement API surface, split from a single 47k-line file into a package: a shared helpers module holds the blueprint and helpers; eight endpoint files hold the 434 route handlers.
+
+| Module | Size | Blueprints | Serves | Purpose |
+|---|---|---|---|---|
+| `routes/entitlement/_endpoints_01.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement .. |
+| `routes/entitlement/_endpoints_02.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement_missing_features_at_path .. |
+| `routes/entitlement/_endpoints_03.py` | large |  | `/api/entitlement`, `/api/features`, `/api/license`, `/api/runtimes`, `/api/tiers` | endpoint handlers api_entitlement_min_tier .. |
+| `routes/entitlement/_endpoints_04.py` | large |  | `/api/entitlement`, `/api/license`, `/api/paywall` | endpoint handlers api_license_state_at .. |
+| `routes/entitlement/_endpoints_05.py` | large |  | `/api/entitlement` | endpoint handlers api_entitlement_next_tier_spec .. |
+| `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/_shared.py` | huge | `bp_entitlement` |  | imports, constants, the blueprint and every non-handler helper the endpoint modules call. |
+
 ## Shared helpers (`helpers/`)
 
 Helpers extracted out of `dashboard.py`. Route modules still reach the ones that have not moved yet via a late `import dashboard as _d`.

docs/ci_test_coverage_baseline.json

@@ -8,6 +8,6 @@
     "Related: issue #5813"
   ],
   "total": 1143,
-  "listed": 212,
-  "unlisted_max": 931
+  "listed": 213,
+  "unlisted_max": 930
 }