Release YO (v0.51.685): extract session-list cache to its own module (#5004, #1907)

[nesquena-hermes]

Release YO (v0.51.685) — session-list cache module extraction

Ships #5004 (@rodboev) — incremental router-slimming (#1907), the proven #3575 extract-and-re-export pattern.

What it does

Moves the session-list cache cluster (state, locks, single-flight/inflight events, rebuild-thread ownership, invalidation/stamp) out of api/routes.py into api/route_session_list_cache.py, re-exported from api.routes. HTTP entrypoints stay in routes.py. No behavior change.

Gate

• Codex: SAFE TO SHIP + Opus: SHIP IT — verified the classic extraction trap is clean: no stale from ... import of a reassigned cache global anywhere in api/ or tests (shared mutable objects accessed live via routes.__getattr__/module attribute); cross-module invalidation (clear_cli_sessions_cache + stamp-bump) intact; fix(models): make session-index rebuild thread ownership explicit (#3894) #4993 rebuild-ownership + Bound state.db reads for paginated session loads #4920 since_timestamp + fix(#4842): stop lock-held CLI cache rebuild stalls during streaming #4952 single-flight logic moved unchanged; no import cycle (back-import is inside helpers).
• Full suite: 10723 passed, 0 failures. +113 tests incl behavioral cross-module-invalidation coverage.
• Pre-merge head re-check: gated == live (19fc6f4).

From a fork — release branch carries rodboev's commits; #5004 closed as shipped with credit.

[greptile-apps]

Greptile Summary

This release extracts the session-list cache cluster (state, locks, single-flight/inflight events, rebuild-thread ownership, and invalidation stamp logic) from api/routes.py into a new api/route_session_list_cache.py, then re-exports every symbol from api.routes to preserve backward compatibility. No HTTP entrypoints or cache behaviors change.

• New module (api/route_session_list_cache.py): 484 lines containing all cache state, invalidation versioning, source-stamp computation, overlay, and rebuild helpers. Avoids circular imports by using lazy import api.routes as _routes inside function bodies rather than at module scope.
• api/routes.py re-export block: directly binds mutable containers (OrderedDict, RLock, dict) and stable callables by reference; routes _SESSIONS_CACHE_GLOBAL_INVALIDATION_VERSION, _SESSIONS_CACHE_ALL_PROFILES_INVALIDATION_VERSION, and _session_list_cache_settings_write_version through __getattr__ to always forward to the live sub-module values.
• Tests: two new test files add 78 + 34 lines of behavioral coverage, including cross-module identity checks, cache mutation sharing, and a static scan that asserts no module-level import api.routes appears in the new file.

Confidence Score: 5/5

Safe to merge — this is a pure extraction with no behavior changes on any code path.

All cache state and logic is moved verbatim; mutable containers are shared by reference, incrementing integer globals are forwarded through getattr so readers always see the current value, and the back-import (lazy function-body only) pattern avoids circular import risk at load time. The _resolved_source_stamp indirection preserves every existing monkeypatch hook that tests rely on. No new locking, no new I/O, no protocol changes.

No files require special attention. The extraction is mechanically consistent across all 19 re-exported names.

Important Files Changed

Filename	Overview
api/route_session_list_cache.py	New 484-line module owning all session-list cache state and logic. Module-level imports are clean (config, models, profiles only); all back-references to api.routes are lazy function-body imports used exclusively for testability overrides. Logic is a verbatim lift from routes.py with the _resolved_source_stamp indirection added to keep monkeypatching working.
api/routes.py	Cache cluster replaced with 19 direct re-export bindings plus a getattr handler for the two incrementing integer globals and the settings-write-version accessor. All callers inside routes.py continue to use their locally-scoped names, which now alias the sub-module's live objects.
tests/test_route_session_list_cache_extraction.py	New test file verifying the extraction contract: symbol presence, identity (same object), cross-module mutation sharing, dynamic integer propagation via getattr, and a static no-module-level-circular-import assertion.
tests/test_session_sidebar_cache.py	Adds one new behavioral test (test_session_list_cache_source_stamp_tracks_settings_write_version) that monkeypatches config._SETTINGS_WRITE_VERSION and asserts the source stamp reflects the change — covering the new settings-write-version indirection path through the extracted module.
CHANGELOG.md	Release entry added by the release agent for v0.51.685; changelog authoring is owned by the release process in this repo.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph routes["api/routes.py (re-export layer)"]
        R_IMPORT["from api import route_session_list_cache as _route_session_list_cache"]
        R_DIRECT["Direct bindings:\n_SESSIONS_CACHE = slc._SESSIONS_CACHE\n_SESSIONS_CACHE_LOCK = slc._SESSIONS_CACHE_LOCK\n_session_list_cache_get = slc._session_list_cache_get\n... (19 names)"]
        R_GETATTR["__getattr__(name):\n_SESSIONS_CACHE_GLOBAL_INVALIDATION_VERSION\n_SESSIONS_CACHE_ALL_PROFILES_INVALIDATION_VERSION\n_session_list_cache_settings_write_version"]
    end

    subgraph slc["api/route_session_list_cache.py (owner)"]
        SLC_STATE["Module-level state:\n_SESSIONS_CACHE (OrderedDict)\n_SESSIONS_CACHE_LOCK (RLock)\n_SESSIONS_CACHE_INFLIGHT (dict)\n_SESSIONS_CACHE_*_INVALIDATION_VERSION (int)"]
        SLC_FUNCS["Cache functions:\n_session_list_cache_get/set/clear\n_session_list_cache_source_stamp\n_session_list_cache_overlay_runtime_rows\n..."]
        SLC_LAZY["Lazy back-imports (inside function bodies only):\nimport api.routes as _routes\n-> override = getattr(_routes, fn_name, None)\n-> if override is not local_fn: call override\n-> else: call local impl"]
    end

    subgraph deps["api/config, api/models, api/profiles"]
        LOCK_SESSIONS["LOCK, SESSIONS, SESSION_DIR, SETTINGS_FILE"]
        MODELS["_active_state_db_path, _active_stream_ids\n_sqlite_content_fingerprint"]
    end

    R_IMPORT --> SLC_STATE
    R_DIRECT -->|"reference (same object)"| SLC_STATE
    R_DIRECT -->|"reference (same callable)"| SLC_FUNCS
    R_GETATTR -->|"getattr(slc, name) at read time"| SLC_STATE
    SLC_LAZY -->|"monkeypatch hook (tests via routes.*)"| routes
    SLC_FUNCS --> deps
    SLC_STATE -.-> deps

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    subgraph routes["api/routes.py (re-export layer)"]
        R_IMPORT["from api import route_session_list_cache as _route_session_list_cache"]
        R_DIRECT["Direct bindings:\n_SESSIONS_CACHE = slc._SESSIONS_CACHE\n_SESSIONS_CACHE_LOCK = slc._SESSIONS_CACHE_LOCK\n_session_list_cache_get = slc._session_list_cache_get\n... (19 names)"]
        R_GETATTR["__getattr__(name):\n_SESSIONS_CACHE_GLOBAL_INVALIDATION_VERSION\n_SESSIONS_CACHE_ALL_PROFILES_INVALIDATION_VERSION\n_session_list_cache_settings_write_version"]
    end

    subgraph slc["api/route_session_list_cache.py (owner)"]
        SLC_STATE["Module-level state:\n_SESSIONS_CACHE (OrderedDict)\n_SESSIONS_CACHE_LOCK (RLock)\n_SESSIONS_CACHE_INFLIGHT (dict)\n_SESSIONS_CACHE_*_INVALIDATION_VERSION (int)"]
        SLC_FUNCS["Cache functions:\n_session_list_cache_get/set/clear\n_session_list_cache_source_stamp\n_session_list_cache_overlay_runtime_rows\n..."]
        SLC_LAZY["Lazy back-imports (inside function bodies only):\nimport api.routes as _routes\n-> override = getattr(_routes, fn_name, None)\n-> if override is not local_fn: call override\n-> else: call local impl"]
    end

    subgraph deps["api/config, api/models, api/profiles"]
        LOCK_SESSIONS["LOCK, SESSIONS, SESSION_DIR, SETTINGS_FILE"]
        MODELS["_active_state_db_path, _active_stream_ids\n_sqlite_content_fingerprint"]
    end

    R_IMPORT --> SLC_STATE
    R_DIRECT -->|"reference (same object)"| SLC_STATE
    R_DIRECT -->|"reference (same callable)"| SLC_FUNCS
    R_GETATTR -->|"getattr(slc, name) at read time"| SLC_STATE
    SLC_LAZY -->|"monkeypatch hook (tests via routes.*)"| routes
    SLC_FUNCS --> deps
    SLC_STATE -.-> deps

Loading

_{Reviews (1): Last reviewed commit: "Release YO (v0.51.685): extract session-..." | Re-trigger Greptile}