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,87 @@
+---
+phase: "14"
+plan: "02"
+type: execute
+wave: 1
+depends_on:
+  - "14-01"
+files_modified:
+  - backend/migrations/versions/0007_cloud_analysis_cache.py
+  - backend/db/models.py
+  - backend/services/cloud_analysis_versioning.py
+  - backend/services/cloud_analysis_settings.py
+  - backend/tests/test_cloud_analysis_contract.py
+  - backend/tests/test_cloud_cache.py
+autonomous: true
+requirements:
+  - ANALYZE-04
+  - ANALYZE-06
+  - CACHE-04
+  - CACHE-05
+---
+
+<objective>
+Add durable Phase 14 schema and shared helpers for cache entries, analysis jobs, per-item status, version-key idempotency, and user/tier-ready analysis settings.
+
+Scope fence: no provider byte download, Celery processing, or frontend UI in this plan.
+</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/db/models.py
+@backend/migrations/versions/0006_cloud_resource_foundation.py
+@backend/services/cloud_items.py
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add migration and ORM models</name>
+  <files>backend/migrations/versions/0007_cloud_analysis_cache.py, backend/db/models.py</files>
+  <read_first>
+    - backend/migrations/versions/0006_cloud_resource_foundation.py
+    - backend/db/models.py
+  </read_first>
+  <action>
+    Create the next Alembic revision for `cloud_byte_cache_entries`, `cloud_analysis_jobs`, `cloud_analysis_job_items`, and either owner-scoped analysis settings or extensions to the existing settings model. Include strict user/connection/item foreign keys, unique cache version key constraints, LRU eviction indexes, status fields, controlled error fields, aggregate counters, and reversible downgrade. Models must mirror the migration and preserve the existing `CloudItem` identity model.
+  </action>
+  <acceptance_criteria>
+    - Cache entries are scoped by user, connection, cloud item, and version key.
+    - Job and job-item rows can represent file, selection, folder, and connection analysis.
+    - Settings support progress detail, failure behavior, and tier-capped cache limit preference.
+    - Downgrade drops only Phase 14 objects.
+  </acceptance_criteria>
+  <verify><automated>cd backend && pytest -q tests/test_cloud_cache.py -k "schema or model"</automated></verify>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add version-key and settings helpers</name>
+  <files>backend/services/cloud_analysis_versioning.py, backend/services/cloud_analysis_settings.py, backend/tests/test_cloud_analysis_contract.py, backend/tests/test_cloud_cache.py</files>
+  <read_first>
+    - backend/services/cloud_items.py
+    - backend/db/models.py
+    - .planning/phases/14-selective-analysis-and-byte-cache/14-PATTERNS.md
+  </read_first>
+  <action>
+    Implement one shared version-key helper using version, etag, fallback metadata fingerprint, and optional post-hydration content hash. Implement settings helpers that return defaults, validate enum values, enforce cache limit bounds, and leave a clean tier/admin maximum seam. Services raise `ValueError` or domain exceptions only.
+  </action>
+  <acceptance_criteria>
+    - Duplicate-current and cache lookup code can consume one canonical version key.
+    - Content hash is never required before bytes are hydrated.
+    - Invalid setting values are rejected by service validation.
+    - `rg "HTTPException" backend/services/cloud_analysis_versioning.py backend/services/cloud_analysis_settings.py` returns no matches.
+  </acceptance_criteria>
+  <verify><automated>cd backend && pytest -q tests/test_cloud_analysis_contract.py tests/test_cloud_cache.py -k "version_key or settings"</automated></verify>
+</task>
+
+</tasks>
+
+<verification>
+1. `cd backend && pytest -q tests/test_cloud_analysis_contract.py tests/test_cloud_cache.py`
+2. Run migration upgrade/downgrade against the PostgreSQL integration environment.
+3. `rg "HTTPException" backend/services/cloud_analysis_versioning.py backend/services/cloud_analysis_settings.py`
+</verification>
+
+<output>Create `.planning/phases/14-selective-analysis-and-byte-cache/14-02-SUMMARY.md` when complete.</output>
+