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

Phase 14 Patterns

Shared Boundaries

• StorageBrowser.vue remains the only file browser. Analysis actions, aggregate progress, and expandable queue UI belong there.
• CloudFolderView.vue remains a thin data provider. It calls the store/API helpers and refreshes browse state; it does not own browser layout or queue rendering.
• Backend routers translate typed request/response schemas and HTTP status codes only. Service modules own analysis, cache, quota, and idempotency behavior and must not raise HTTPException.
• Cloud provider credentials are decrypted only inside route/task provider boundaries. Celery payloads contain IDs and control flags only.

Status Vocabulary

Durable internal item statuses:

• queued
• downloading
• extracting
• classifying
• indexed
• already_current
• cancelled
• failed
• unsupported
• stale

UI label mapping:

• simple default: waiting, working, done, skipped, failed
• detailed setting: queued, downloading, extracting, classifying, indexed, cancelled, failed

Do not let frontend components invent a second status translation. Put API-to-UI translation in the Pinia store or a shared formatter/helper.

Version Keys

Create one shared helper for cloud analysis version keys. All estimate, enqueue, duplicate-check, cache lookup, and worker paths must call it.

Precedence:

1. version
2. etag
3. metadata fingerprint from provider item id, size, modified time, content type
4. content hash as an additional post-hydration fact, never as a pre-download requirement

Cache Lifecycle

1. Resolve owner and item.
2. Compute version key.
3. Reuse non-evicted matching cache entry if present.
4. Otherwise hydrate provider bytes through the mutable/content adapter boundary.
5. Store bytes under a UUID/private MinIO key.
6. Atomically increment user quota by retained size.
7. Pin for active job or preview.
8. Release pin when finished.
9. Evict inactive LRU entries when the user's configured limit or quota pressure requires it.

Eviction failure must not hide successful analysis. It should surface controlled warning state and leave quota/cache metadata consistent.

Estimate Semantics

Small file jobs may start directly. Folder and connection jobs estimate first when thresholds are crossed, and whole-connection analysis always estimates unless trivially small.

Estimate responses include:

• supported file count
• provider-reported byte total
• unsupported/skipped item count
• whether recursion applies
• whether the estimate is complete or partial

The estimate endpoint must never download bytes.

Error and Control Semantics

• Batch failure behavior defaults to pause_batch.
• continue_item pauses only the failed item and keeps later queued items running.
• Per-item retry restarts the full item.
• Per-item skip/cancel affects that item only.
• Batch cancel cancels queued items and requests cooperative cancellation for running work.
• Typed error bodies use controlled kind and reason fields, matching the Phase 13 mutation response style.

Test Pattern

Each implementation plan starts with focused red tests for its slice, then implementation, then targeted verification.

Required negative coverage by the end of the phase:

• foreign user cannot estimate, enqueue, read status, cancel, retry, or read cache metadata
• admin cannot access cloud analysis/cache routes
• cache object keys and credentials never appear in responses or audit logs
• unchanged etag/version skips duplicate analysis without byte download
• cached bytes count against quota while retained and decrement after eviction
• active jobs/previews are not evicted
• folder/connection analysis does not mutate provider files