fix: give RedisCacheLayer an event-loop ownership contract

[groupthinking]

Canonical issue

Closes #1162

Outcome

RedisCacheLayer and its redis.asyncio.ConnectionPool are now owned by exactly one event loop, enforced at every pool call site, so cross-loop misuse fails loudly (CacheLoopOwnershipError) instead of surfacing as a silent cache miss. This matters because the module builds the IntelligentCacheSystem singleton at import time, outside any loop, so one layer instance is reachable from several loops in a process.

The contract (option 1 from the issue, plus an explicit handoff):

• Owning loop → allowed. First touch of an existing pool claims ownership.
• Second live loop → CacheLoopOwnershipError, raised before each method's except Exception so it can't be swallowed into a None/False/0 fallback.
• Owner loop closed → the pool is unusable by anyone; it is discarded with a WARNING and the next loop may connect() again (this is the per-loop construction story for pytest's fresh-loop-per-test).
• New disconnect() / IntelligentCacheSystem.shutdown() are the clean handoff.

This supersedes draft #1179 and resolves its three unreviewed-defect findings:

1. Ownership races — transitions are serialized on a threading.Lock, and connect() claims ownership before building the pool, so two loops connecting simultaneously resolve to one winner instead of both building pools and leaking the loser's. Reconnecting on the owner loop also closes the previous pool rather than abandoning it.
2. disconnect() lifecycle — state is released only after pool.disconnect() succeeds; teardown failures propagate, so a failed disconnect can be retried instead of silently leaking a live pool.
3. warm_cache() — re-raises CacheLoopOwnershipError instead of letting gather(return_exceptions=True) fold it into the success count.

Scope

• Included: the contract and its enforcement in src/youtube_extension/backend/services/intelligent_cache.py (connect/disconnect/get/set/delete/clear/invalidate_by_tags), the new disconnect()/shutdown(), and regression tests.
• Explicitly excluded: caching semantics, key layout, serialization, TTL handling, the L1 layer, and the tag-write fan-out from perf: issue Redis tag-set writes concurrently on cache set #1152. No signature changes to existing methods.

Risk

• Risk level: low
• Failure mode: code that today silently uses the pool from a foreign live loop now raises instead of degrading to a cache miss — intended, but loud. Single-loop use is unchanged apart from an identity check.
• Rollback: revert the single commit; no config, schema, or dependency changes.

Verification

At head 46ca0a6:

• Focused tests — pytest tests/unit/test_intelligent_cache.py: 200 passed (183 baseline + 17 new, zero regressions). New coverage: rejection from a real second live loop (background thread) parametrized across all 7 call sites; error not swallowed by the layer, the facade, or warm_cache(); serialized simultaneous first connect() (loser rejected mid-build, winner's pool kept); reconnect closing the previous pool; disconnect failure propagating with state intact then succeeding on retry; closed-owner discard incl. its WARNING; the import-time singleton honouring the contract; shutdown() handoff.
• Non-vacuity — with _require_pool_loop neutered, 16 tests fail; source restored and re-verified green.
• Lint — ruff check clean on the source file; the test file's single I001 is pre-existing.
• Required CI
• Review threads resolved

One existing test updated: test_tag_write_semaphore_is_replaced_after_its_loop_closes now reconnects on the second loop, as the contract requires; its assertion is unchanged.

Production evidence

Not applicable: backend correctness fix with no user-facing surface, and the failure mode is unobservable on main by construction (every affected method swallows it into a miss-shaped return). The raised error and the closed-owner WARNING are the first observability this failure mode has had.

Agent handoff

• One canonical issue is linked
• No competing PR implements the same issue — fix: give RedisCacheLayer an event-loop ownership contract (#1162) #1179 is a stale draft on an orphaned pre-history-rewrite base with unresolved review findings; this PR replaces it
• Acceptance criteria are satisfied — one contract chosen and documented on the class, enforced at all call sites, regression tests incl. the import-time singleton, suite green
• Required checks pass on the current head
• Human decision is requested only where warranted — none needed; the closed-owner discard behaviour follows the option-1 contract plus the recovery story the issue's acceptance criteria require

Agent provenance

[linear-code]

GRV-212

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-uvai	Canceled	v0	Aug 4, 2026 6:13am

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• [‘architecture-gap’, ‘bug’, ‘ci-cd’, ‘ci/cd’, ‘copilot-rabbit’, ‘documentation’, ‘duplicate’, ‘enhancement’, ‘frontend’, ‘github_actions’, ‘good first issue’, ‘help wanted’, ‘high-priority’, ‘invalid’, ‘javascript’, ‘ml-model’, ‘needs-triage’, ‘pipeline-critical’, ‘placeholder-code’, ‘priority:high’, ‘python’, ‘python:uv’, ‘question’, ‘styling’, ‘tests’, ‘v0’]

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 63a5942b-72f2-4538-9378-3c1fe7b6cb8f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 PR Validation

⚠️ Large PR detected (679 lines changed)

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 46ca0a6.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[github-actions]

Agent Completion Truth Gate: BLOCKED

Reasons: invalid_payload

Machine-readable verdict

{
  "details": {
    "collection_errors": [
      "linked_issue_not_agent_task",
      "missing_intent_snapshot",
      "missing_agent_run_id",
      "missing_agent_login"
    ],
    "invalid_fields": [
      "policy.agent_login",
      "policy.run_id"
    ]
  },
  "reasons": [
    "invalid_payload"
  ],
  "verdict": "blocked"
}

Workflow evidence

[Copilot]

Pull request overview

Adds event-loop ownership enforcement and lifecycle handoff for Redis caching.

Changes:

• Rejects cross-loop pool access with CacheLoopOwnershipError.
• Adds disconnect() and system-level shutdown().
• Adds ownership, race, recovery, and propagation tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/youtube_extension/backend/services/intelligent_cache.py	Implements pool ownership and lifecycle handling.
tests/unit/test_intelligent_cache.py	Adds regression coverage for loop ownership.