kite/.planning/phases/14-selective-analysis-and-byte-cache/14-03-SUMMARY.md

---

phase: "14" plan: "03" subsystem: cloud-analysis tags: [cache, api, security, quota, pinning, settings] status: complete

requires:

• phases/14-selective-analysis-and-byte-cache/14-02

provides:

• services/cloud_cache.py: retain_or_reuse_cache_entry, pin_cache_entry, release_cache_entry, update_cache_access — Phase 14 cache lifecycle orchestration (PATTERNS.md steps 3, 7, 8)
• api/cloud/cache.py: GET /analysis/cache, PATCH /analysis/cache/settings — aggregate cache usage/settings, no object_key or credentials in response
• api/cloud/analysis.py: analysis router aggregator (parent for Phase 14 plans 04-09)
• api/cloud/schemas.py: CacheStatusOut, CacheSettingsUpdateRequest

affects:

• backend/services/cloud_cache.py
• backend/api/cloud/cache.py (new)
• backend/api/cloud/analysis.py (new)
• backend/api/cloud/schemas.py
• backend/api/cloud/__init__.py
• backend/tests/test_cloud_cache.py
• backend/tests/test_cloud_security.py

tech-stack: added: [] patterns: - retain-or-reactivate: unique constraint means evicted entries are reactivated (evicted_at cleared, object_key updated) rather than duplicated — semantically equivalent to "cache miss requires new bytes" - pin_count lifecycle: pin_cache_entry / release_cache_entry with GREATEST(0, ...) clamp for defensive double-release handling - analysis router aggregator: api/cloud/analysis.py is the future-proof parent for all Phase 14 analysis routes (estimates, jobs, controls) - CacheStatusOut allowlist: schema enforces T-14-02/T-14-08 by design — object_key and credentials_enc absent at type level

key-files: created: - backend/api/cloud/cache.py - backend/api/cloud/analysis.py modified: - backend/services/cloud_cache.py - backend/api/cloud/schemas.py - backend/api/cloud/__init__.py - backend/tests/test_cloud_cache.py - backend/tests/test_cloud_security.py

decisions:

• retain_or_reuse_cache_entry reactivates evicted rows (clears evicted_at, updates object_key) rather than inserting a new row — the unique constraint on (user_id, connection_id, cloud_item_id, version_key) makes insertion impossible; reactivation is semantically correct (fresh bytes, same version)
• api/cloud/analysis.py created as the aggregator so tests can from api.cloud.analysis import router as required by Plan 01 RED tests
• CacheStatusOut has no per-entry fields — only aggregate totals — ensuring T-14-02 compliance at schema design level rather than runtime filtering

metrics: duration: "~18 minutes" completed: "2026-06-23" tasks: 2 files: 7

Phase 14 Plan 03: Cache Service and API Summary

One-liner: Cache orchestration functions (retain/reuse, pin, release, touch) and credential-free cache status/settings API with admin block and object_key exclusion.

What Was Built

Task 1: Cache orchestration functions

services/cloud_cache.py — four new Phase 14 orchestration functions added after the Plan 02 primitives:

• retain_or_reuse_cache_entry(session, *, user_id, connection_id, cloud_item_id, provider_item_id, version_key, object_key, ...): PATTERNS.md step 3 implementation. Checks for a non-evicted matching entry first (reuse path). If the only matching entry is evicted, reactivates it (clears evicted_at, updates object_key/size) because the unique constraint prevents inserting a duplicate. Returns (entry, created_new) tuple. Ownership enforced — foreign user always gets a separate row.

• pin_cache_entry(session, *, entry_id, user_id): Increments pin_count to mark an active preview or download lease (PATTERNS.md step 7). Ownership asserted — raises ValueError for foreign entry IDs.

• release_cache_entry(session, *, entry_id, user_id): Decrements pin_count with GREATEST(0, ...) clamp (PATTERNS.md step 8). Ownership asserted.

• update_cache_access(session, *, entry_id, user_id): Touches last_accessed_at after a cache hit to maintain accurate LRU ordering. Ownership asserted.

All four functions raise ValueError only — never HTTPException (CLAUDE.md service-layer rule).

Tests added to tests/test_cloud_cache.py (9 new tests, Task 1):

• retain_or_reuse returns existing active entry
• retain_or_reuse creates new entry when absent
• retain_or_reuse reactivates evicted entry (not duplicate)
• retain_or_reuse isolates foreign users (T-14-06)
• pin increments pin_count
• release decrements pin_count
• release clamps at zero (double-release defense)
• pin raises ValueError on foreign entry (T-14-06)
• update_cache_access refreshes last_accessed_at timestamp

Task 2: Cache settings/status API

api/cloud/cache.py (new):

• GET /analysis/cache — returns CacheStatusOut with aggregate entry_count, total_bytes, cache_limit_bytes, tier_cap_bytes, analysis_progress_detail, analysis_failure_behavior. Calls get_or_create_user_analysis_settings for defaults on first access. Rate-limited at 120/minute. Blocked for admin (get_regular_user).
• PATCH /analysis/cache/settings — accepts CacheSettingsUpdateRequest (three explicit fields only — mass assignment prevention). Service layer validates enums and bounds; route re-raises ValueError as 422. Returns fresh CacheStatusOut. Rate-limited at 30/minute. Blocked for admin.

api/cloud/analysis.py (new):

• Aggregator router for /api/cloud/analysis/* namespace.
• Includes cache_router now; will include estimate/jobs/controls routers in Plans 04-09.
• Importable as api.cloud.analysis so Plan 01 RED tests can import the router.

api/cloud/schemas.py (extended):

• CacheStatusOut: explicit allowlist with 6 fields — no object_key, credentials_enc, or per-entry data possible.
• CacheSettingsUpdateRequest: 3 explicit optional fields with ge=1 constraint on byte limit.

api/cloud/__init__.py (updated):

• Imports and includes analysis_router from api.cloud.analysis.

Security tests added to tests/test_cloud_security.py (7 new tests, Task 2):

• admin blocked from GET /analysis/cache (403)
• admin blocked from PATCH /analysis/cache/settings (403)
• unauthenticated request blocked (401/403)
• response excludes object_key and credentials_enc (T-14-02, T-14-08)
• response includes expected aggregate fields
• invalid enum value returns 422
• cache limit above tier cap returns 422

Test Results

File	Tests	Pass	Notes
test_cloud_cache.py	21	21	All pass including 9 new Task 1 tests
test_cloud_security.py -k cache	8	8	7 new + 1 pre-existing
Overall suite (excl. RED tests)	808	808	Pre-existing RED failures unchanged

Pre-existing RED failures (not Plan 03 scope):

• test_cloud_analysis_api.py: 10 failures — estimate/jobs/controls routes (Plans 04+)
• test_cloud_analysis_contract.py: 14 failures — analysis contract (Plans 04+)
• test_extractor.py::test_extract_docx: pre-existing docx env issue

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Unique constraint prevents duplicate insert for evicted entries

• Found during: Task 1 implementation
• Issue: retain_or_reuse_cache_entry attempted to create a new row for an evicted entry. The unique constraint on (user_id, connection_id, cloud_item_id, version_key) prevents duplicate inserts, raising IntegrityError.
• Fix: When an evicted entry exists for the same version_key, reactivate it (clear evicted_at, update object_key and size_bytes) instead of inserting. This is semantically correct: the bytes needed to be re-hydrated (created_new=True) but the DB row identity is preserved.
• Files modified: backend/services/cloud_cache.py, backend/tests/test_cloud_cache.py (test updated to match corrected semantics)
• Commit: 5bdd23f

Known Stubs

None.

Threat Flags

None — no new network endpoints beyond the intended /analysis/cache routes documented in the plan. Admin block and object_key exclusion enforced at schema and dependency level.

Self-Check: PASSED