---
phase: "14"
plan: "02"
subsystem: cloud-analysis
tags: [schema, migration, services, cache, versioning, settings]
status: complete

requires:
  - phases/14-selective-analysis-and-byte-cache/14-01

provides:
  - Alembic migration 0007: cloud_byte_cache_entries, cloud_analysis_jobs,
    cloud_analysis_job_items, user_analysis_settings
  - ORM models: CloudByteCacheEntry, CloudAnalysisJob, CloudAnalysisJobItem,
    UserAnalysisSettings
  - services/cloud_analysis_versioning.py: compute_version_key, compute_fingerprint
  - services/cloud_analysis_settings.py: get_or_create_user_analysis_settings,
    update_user_analysis_settings, build_default_settings
  - services/cloud_cache.py: Phase 14 durable cache functions (create_cache_entry,
    list_cache_entries, evict_lru_entries, increment_quota_for_cache,
    decrement_quota_for_cache) + re-export of compute_version_key

affects:
  - 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/services/cloud_cache.py

tech-stack:
  added: []
  patterns:
    - version-key precedence (version > etag > metadata fingerprint > content hash)
    - LRU eviction with pin_count/active_job_count guards
    - atomic quota UPDATE pattern for cache retain/release
    - upsert-on-first-access for user settings row
    - re-export pattern to unify import sites for compute_version_key

key-files:
  created:
    - backend/migrations/versions/0007_cloud_analysis_cache.py
    - backend/services/cloud_analysis_versioning.py
    - backend/services/cloud_analysis_settings.py
  modified:
    - backend/db/models.py
    - backend/services/cloud_cache.py

decisions:
  - compute_version_key defined in cloud_analysis_versioning.py and re-exported
    from cloud_cache.py so tests have one canonical import site
  - content_hash accepted as optional post-hydration supplement — never required
    as a pre-download precondition (D-20)
  - user_analysis_settings is distinct from system_settings — single settings
    authority for per-user analysis preferences
  - evict_lru_entries stamps evicted_at only — caller is responsible for MinIO
    object deletion and quota decrement (separation of concerns)
  - increment_quota_for_cache uses atomic UPDATE…RETURNING pattern (same as
    upload quota enforcement) — raises CacheQuotaExceeded on overflow

metrics:
  duration: "~12 minutes"
  completed: "2026-06-23"
  tasks: 2
  files: 5
---

# Phase 14 Plan 02: Schema and Service Helpers Summary

One-liner: Alembic migration 0007 adds four Phase 14 tables (byte cache, analysis jobs, job items, user settings) with ORM models, version-key precedence helper, tier-seamed settings service, and LRU eviction cache functions.

## What Was Built

### Task 1: Migration and ORM Models

**migration 0007_cloud_analysis_cache.py:**
- `cloud_byte_cache_entries`: owner-scoped durable byte cache backed by MinIO.
  Unique on (user_id, connection_id, cloud_item_id, version_key).  Fields include
  pin_count, active_job_count, last_accessed_at, evicted_at.  Two LRU eviction
  indexes (ix_cache_entries_user_evicted_accessed, ix_cache_entries_user_active).
- `cloud_analysis_jobs`: user-visible batch rows with scope_kind (file/selection/
  folder/connection), 11 aggregate item counters, provider_bytes_estimate, status,
  and failure_behavior.
- `cloud_analysis_job_items`: per-item idempotency rows with the full status
  vocabulary (queued/downloading/extracting/classifying/indexed/already_current/
  cancelled/failed/unsupported/stale), controlled error fields, cache_entry_id FK,
  fingerprint snapshot, and retry_count.  Unique on (job_id, cloud_item_id).
  Fast duplicate-current index: (user_id, cloud_item_id, version_key).
- `user_analysis_settings`: per-user preferences (analysis_progress_detail,
  analysis_failure_behavior, cloud_cache_limit_bytes).  Separate from system_settings.
- Reversible downgrade drops Phase 14 tables only in reverse-creation order.

**db/models.py additions:**
- CloudByteCacheEntry, CloudAnalysisJob, CloudAnalysisJobItem, UserAnalysisSettings
  ORM models mirror the migration exactly.

### Task 2: Service Helpers

**services/cloud_analysis_versioning.py** (new):
- `compute_version_key(provider_item_id, version, etag, size, modified_at, content_type, content_hash=None)`: canonical version-key helper with v:/e:/fp:/ch: prefix tags.
  Precedence: provider version → etag → SHA-256 metadata fingerprint → optional
  post-hydration content hash suffix.  Deterministic and raises ValueError only.
- `compute_fingerprint(...)`: public entry point for metadata-only fingerprint.
- No HTTPException import or raise (CLAUDE.md service-layer rule).

**services/cloud_analysis_settings.py** (new):
- `get_or_create_user_analysis_settings(session, user_id)`: upsert on first access.
- `update_user_analysis_settings(session, user_id, ...)`: validates enum fields
  (VALID_PROGRESS_DETAIL, VALID_FAILURE_BEHAVIOR) and bounds-checks cache limit
  against MIN_CACHE_LIMIT_BYTES and caller-supplied max_cache_limit_bytes.
- `build_default_settings()`: returns defaults dict without touching the DB.
- Tier/admin maximum is an explicit parameter seam (not hardcoded in the service).
- No HTTPException import or raise.

**services/cloud_cache.py** (extended):
- Phase 14 functions added after the existing Phase 12 in-memory TTL cache code:
  `create_cache_entry`, `list_cache_entries` (owner-scoped, excludes evicted),
  `evict_lru_entries` (LRU, skips pin_count>0 or active_job_count>0),
  `increment_quota_for_cache` (atomic UPDATE…RETURNING, raises CacheQuotaExceeded),
  `decrement_quota_for_cache` (GREATEST(0, used_bytes - delta)).
- Re-exports `compute_version_key` from cloud_analysis_versioning.py so test/caller
  import sites are unified.
- Phase 12 get_cloud_folders_cached / invalidate_provider_cache unchanged.

## Test Results

| File | Pass | Fail | Notes |
|------|------|------|-------|
| test_cloud_cache.py | 10 | 2 | 2 failures require api.cloud.analysis (future plan) |
| test_cloud_analysis_contract.py | 0 | 16 | All require api.cloud.analysis (future plan) |
| Overall suite (excl. Phase 14 RED) | 610+ | 1 pre-existing | test_extractor.py docx env issue — pre-existing |

## Deviations from Plan

None — plan executed exactly as written.

## Known Stubs

None.

## Threat Flags

None — this plan adds schema, migration, and service layer only.  No new network
endpoints, auth paths, or file access patterns.

## Self-Check: PASSED