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.
@.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
Task 1: Add migration and ORM models
backend/migrations/versions/0007_cloud_analysis_cache.py, backend/db/models.py
- backend/migrations/versions/0006_cloud_resource_foundation.py
- backend/db/models.py
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.
- 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.
cd backend && pytest -q tests/test_cloud_cache.py -k "schema or model"
Task 2: Add version-key and settings helpers
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
- backend/services/cloud_items.py
- backend/db/models.py
- .planning/phases/14-selective-analysis-and-byte-cache/14-PATTERNS.md
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.
- 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.
cd backend && pytest -q tests/test_cloud_analysis_contract.py tests/test_cloud_cache.py -k "version_key or settings"
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`
Create .planning/phases/14-selective-analysis-and-byte-cache/14-02-SUMMARY.md when complete.
