docs(phase-14): plan selective analysis and byte cache

2026-06-23 14:24:43 +02:00
parent 3514fdcf3a
commit b528b51881
13 changed files with 1117 additions and 16 deletions
@@ -0,0 +1,99 @@
+---
+phase: "14"
+plan: "03"
+type: execute
+wave: 2
+depends_on:
+  - "14-02"
+files_modified:
+  - backend/services/cloud_byte_cache.py
+  - backend/api/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
+autonomous: true
+requirements:
+  - CACHE-03
+  - CACHE-04
+  - CACHE-05
+---
+
+<objective>
+Implement the owner-scoped byte cache service and read/control API: cache lookup, retain, pin/release, per-user LRU eviction, quota accounting, settings update, and metadata-safe cache status responses.
+
+Scope fence: do not wire analysis workers or open/preview hydration yet. This plan builds the cache primitive those paths will call.
+</objective>
+
+<context>
+@.planning/phases/14-selective-analysis-and-byte-cache/14-RESEARCH.md
+@.planning/phases/14-selective-analysis-and-byte-cache/14-PATTERNS.md
+@backend/storage/minio_backend.py
+@backend/services/cloud_items.py
+@backend/db/models.py
+@backend/api/cloud/schemas.py
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Build cache service with quota and pinning semantics</name>
+  <files>backend/services/cloud_byte_cache.py, backend/tests/test_cloud_cache.py</files>
+  <read_first>
+    - backend/storage/minio_backend.py
+    - backend/services/quota.py
+    - backend/db/models.py
+    - backend/tests/test_quota.py
+  </read_first>
+  <action>
+    Add cache service functions to resolve owned cache entries, reserve quota atomically before retaining bytes, store bytes using UUID/private object keys, record metadata, reuse matching non-evicted version entries, pin/release active job or preview use, update last access, evict inactive LRU entries per user limit, decrement quota when retained bytes are evicted, and delete MinIO objects best-effort after DB state is consistent. Protect entries with `pin_count > 0` or `active_job_count > 0`.
+  </action>
+  <acceptance_criteria>
+    - Cache retention increments quota and eviction decrements quota with atomic quota helpers.
+    - Eviction never selects another user's entry and never evicts pinned/active entries.
+    - Object keys are generated UUID/private keys and never include provider filenames.
+    - Service functions raise domain errors or `ValueError`, never `HTTPException`.
+  </acceptance_criteria>
+  <verify><automated>cd backend && pytest -q tests/test_cloud_cache.py</automated></verify>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add cache settings/status API</name>
+  <files>backend/api/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</files>
+  <read_first>
+    - backend/api/cloud/connections.py
+    - backend/api/cloud/operations.py
+    - backend/api/cloud/schemas.py
+    - backend/tests/test_cloud_security.py
+  </read_first>
+  <action>
+    Add credential-free endpoints for current cache usage/settings and updating the user's preferred cache limit/progress/failure settings. Use explicit Pydantic fields only. Return aggregate bytes/counts and tier cap, not object keys. Enforce `get_regular_user`, owner scope, and rate limiting consistent with existing cloud routes.
+  </action>
+  <acceptance_criteria>
+    - Admin users are blocked.
+    - Responses contain no `object_key`, credentials, raw provider URLs, or extracted text.
+    - Invalid cache limits above the tier/admin cap return a controlled validation response.
+    - Security tests cover foreign user and admin-negative cases.
+  </acceptance_criteria>
+  <verify><automated>cd backend && pytest -q tests/test_cloud_cache.py tests/test_cloud_security.py -k "cache"</automated></verify>
+</task>
+
+</tasks>
+
+<threat_model>
+| Threat ID | Threat | Mitigation |
+|-----------|--------|------------|
+| T-14-06 | Cross-user cache access | All cache entry queries include user_id and connection_id; negative tests |
+| T-14-07 | Quota race | Existing atomic quota update helpers required for retain/evict deltas |
+| T-14-08 | Object key leakage | API schemas omit object_key and tests assert absence |
+| T-14-09 | Active work eviction | Pin/active counters in selection predicate and regression tests |
+</threat_model>
+
+<verification>
+1. `cd backend && pytest -q tests/test_cloud_cache.py`
+2. `cd backend && pytest -q tests/test_cloud_security.py -k "cache"`
+3. `rg "object_key|credentials_enc" backend/api/cloud/cache.py backend/api/cloud/schemas.py`
+</verification>
+
+<output>Create `.planning/phases/14-selective-analysis-and-byte-cache/14-03-SUMMARY.md` when complete.</output>
+