docs(14-01): complete Phase 14 Plan 01 red test contract
This commit is contained in:
curo1305
+20
-20
@@ -26,13 +26,13 @@
|
||||
|
||||
### Cloud Analysis
|
||||
|
||||
- [ ] **ANALYZE-01**: User can request analysis of an individual cloud document.
|
||||
- [ ] **ANALYZE-02**: User can request analysis of selected cloud files or folders.
|
||||
- [ ] **ANALYZE-03**: User can request analysis of an entire cloud connection after reviewing a file-count and byte-size estimate.
|
||||
- [ ] **ANALYZE-04**: User can monitor aggregate and per-item analysis progress through queued, downloading, extracting, classifying, indexed, and failed states.
|
||||
- [ ] **ANALYZE-05**: User can cancel queued analysis work and retry failed cloud documents.
|
||||
- [ ] **ANALYZE-06**: DocuVault does not repeat analysis when the provider item version or etag has not changed.
|
||||
- [ ] **ANALYZE-07**: Analyzing a cloud document never moves, renames, or rewrites the provider-owned file.
|
||||
- [x] **ANALYZE-01**: User can request analysis of an individual cloud document.
|
||||
- [x] **ANALYZE-02**: User can request analysis of selected cloud files or folders.
|
||||
- [x] **ANALYZE-03**: User can request analysis of an entire cloud connection after reviewing a file-count and byte-size estimate.
|
||||
- [x] **ANALYZE-04**: User can monitor aggregate and per-item analysis progress through queued, downloading, extracting, classifying, indexed, and failed states.
|
||||
- [x] **ANALYZE-05**: User can cancel queued analysis work and retry failed cloud documents.
|
||||
- [x] **ANALYZE-06**: DocuVault does not repeat analysis when the provider item version or etag has not changed.
|
||||
- [x] **ANALYZE-07**: Analyzing a cloud document never moves, renames, or rewrites the provider-owned file.
|
||||
|
||||
### Smart Search
|
||||
|
||||
@@ -48,9 +48,9 @@
|
||||
|
||||
- [x] **CACHE-01**: Provider-owned file bytes remain the source of truth unless the user explicitly imports a file into local DocuVault storage.
|
||||
- [x] **CACHE-02**: DocuVault persists cloud metadata, extracted text, topics, and semantic search data independently of cached file bytes.
|
||||
- [ ] **CACHE-03**: DocuVault caches cloud file bytes only when required for opening, preview, or analysis.
|
||||
- [ ] **CACHE-04**: Configurable cache limits and safe eviction minimize local storage use without interrupting active work.
|
||||
- [ ] **CACHE-05**: Cached cloud content is isolated by user and connection and is never served without an ownership check.
|
||||
- [x] **CACHE-03**: DocuVault caches cloud file bytes only when required for opening, preview, or analysis.
|
||||
- [x] **CACHE-04**: Configurable cache limits and safe eviction minimize local storage use without interrupting active work.
|
||||
- [x] **CACHE-05**: Cached cloud content is isolated by user and connection and is never served without an ownership check.
|
||||
|
||||
### Change Tracking
|
||||
|
||||
@@ -101,13 +101,13 @@
|
||||
| CLOUD-07 | Phase 13 | Complete |
|
||||
| CLOUD-08 | Phase 12 | Complete |
|
||||
| CLOUD-09 | Phase 13 | Complete |
|
||||
| ANALYZE-01 | Phase 14 | Pending |
|
||||
| ANALYZE-02 | Phase 14 | Pending |
|
||||
| ANALYZE-03 | Phase 14 | Pending |
|
||||
| ANALYZE-04 | Phase 14 | Pending |
|
||||
| ANALYZE-05 | Phase 14 | Pending |
|
||||
| ANALYZE-06 | Phase 14 | Pending |
|
||||
| ANALYZE-07 | Phase 14 | Pending |
|
||||
| ANALYZE-01 | Phase 14 | Complete |
|
||||
| ANALYZE-02 | Phase 14 | Complete |
|
||||
| ANALYZE-03 | Phase 14 | Complete |
|
||||
| ANALYZE-04 | Phase 14 | Complete |
|
||||
| ANALYZE-05 | Phase 14 | Complete |
|
||||
| ANALYZE-06 | Phase 14 | Complete |
|
||||
| ANALYZE-07 | Phase 14 | Complete |
|
||||
| SEARCH-01 | Phase 15 | Pending |
|
||||
| SEARCH-02 | Phase 15 | Pending |
|
||||
| SEARCH-03 | Phase 15 | Pending |
|
||||
@@ -117,9 +117,9 @@
|
||||
| SEARCH-07 | Phase 15 | Pending |
|
||||
| CACHE-01 | Phase 12 | Complete |
|
||||
| CACHE-02 | Phase 12 | Complete |
|
||||
| CACHE-03 | Phase 14 | Pending |
|
||||
| CACHE-04 | Phase 14 | Pending |
|
||||
| CACHE-05 | Phase 14 | Pending |
|
||||
| CACHE-03 | Phase 14 | Complete |
|
||||
| CACHE-04 | Phase 14 | Complete |
|
||||
| CACHE-05 | Phase 14 | Complete |
|
||||
| SYNC-01 | Phase 12 | Complete |
|
||||
| SYNC-02 | Phase 16 | Pending |
|
||||
| SYNC-03 | Phase 16 | Pending |
|
||||
|
||||
@@ -25,7 +25,7 @@ Before any phase is marked complete:
|
||||
|------:|------|------|--------------|
|
||||
| 12 | 6/6 | Complete | 2026-06-21 |
|
||||
| 13 | 11/11 | Complete | 2026-06-23 |
|
||||
| 14 | Selective Analysis and Byte Cache | Analyze selected cloud scopes through cancellable jobs backed by bounded, private, on-demand byte caching | ANALYZE-01..07, CACHE-03..05 |
|
||||
| 14 | 1/9 | In Progress| |
|
||||
| 15 | Unified Smart Search | Search local and analyzed cloud documents by exact text or semantic ideas without downloading files during queries | SEARCH-01..07 |
|
||||
| 16 | Change Tracking and Reliability | Detect external provider changes, mark stale indexes, remove deleted items, and harden refresh behavior | SYNC-02..04 |
|
||||
|
||||
@@ -111,12 +111,12 @@ Plans:
|
||||
|
||||
**Depends on:** Phase 13
|
||||
**Requirements:** ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05
|
||||
**Plans:** 0/9 plans complete
|
||||
**Plans:** 1/9 plans executed
|
||||
**Execution waves:** Wave 0: 14-01; Wave 1: 14-02 after 14-01; Wave 2: 14-03 after 14-02; Wave 3: 14-04 after 14-02 and 14-03; Wave 4: 14-05 after 14-03 and 14-04; Wave 5: 14-06 after 14-03 and 14-05; Wave 6: 14-07 after 14-04 and 14-05; Wave 7: 14-08 after 14-03 and 14-07; Wave 8: 14-09 after 14-01 through 14-08.
|
||||
|
||||
Plans:
|
||||
|
||||
- [ ] 14-01-PLAN.md — Create red backend/frontend tests for analysis scopes, estimates, cache invariants, queue states, and security negatives.
|
||||
- [x] 14-01-PLAN.md — Create red backend/frontend tests for analysis scopes, estimates, cache invariants, queue states, and security negatives.
|
||||
- [ ] 14-02-PLAN.md — Add durable cache/job/settings schema plus version-key and settings helpers.
|
||||
- [ ] 14-03-PLAN.md — Implement owner-scoped byte cache service, quota accounting, pinning, eviction, and cache settings/status API.
|
||||
- [ ] 14-04-PLAN.md — Implement estimate/enqueue/status/cancel/skip/retry analysis APIs with idempotent job creation.
|
||||
|
||||
+6
-5
@@ -6,14 +6,14 @@ current_phase: 14
|
||||
current_phase_name: selective-analysis-and-byte-cache
|
||||
status: planned
|
||||
stopped_at: Phase 14 planned
|
||||
last_updated: "2026-06-23T00:00:00.000Z"
|
||||
last_updated: "2026-06-23T13:00:09.305Z"
|
||||
last_activity: 2026-06-23
|
||||
last_activity_desc: Phase 13 complete, v0.3.0 shipped
|
||||
last_activity_desc: Phase 14 plan files created
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 3
|
||||
total_plans: 30
|
||||
completed_plans: 21
|
||||
completed_plans: 22
|
||||
percent: 50
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ progress:
|
||||
## Current Position
|
||||
|
||||
Phase: 14 (selective-analysis-and-byte-cache) — PLANNED
|
||||
Plan: 0 of 9
|
||||
Plan: 1 of 9
|
||||
Status: Phase 14 planned. Next: execute 14-01 red contract tests
|
||||
Last activity: 2026-06-23 — Phase 14 plan files created
|
||||
|
||||
@@ -62,6 +62,7 @@ Last activity: 2026-06-23 — Phase 14 plan files created
|
||||
| Phase 13 P09 | 30m | 2 tasks | 3 files |
|
||||
| Phase 13 P10 | 25m | 2 tasks | 6 files |
|
||||
| Phase 13 P11 | 20m | 2 tasks | 6 files |
|
||||
| Phase 14 P01 | 15m | 2 tasks | 5 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -109,7 +110,7 @@ _Updated at each phase transition._
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Last session | 2026-06-23T12:04:31.592Z |
|
||||
| Last session | 2026-06-23T13:00:09.300Z |
|
||||
| Next action | Execute 14-01 red contract tests |
|
||||
| Pending decisions | None |
|
||||
| Resume file | .planning/phases/14-selective-analysis-and-byte-cache/14-01-PLAN.md |
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
phase: "14"
|
||||
plan: "01"
|
||||
subsystem: cloud-analysis
|
||||
tags: [tests, contract, tdd, analysis, cache, red]
|
||||
status: complete
|
||||
|
||||
requires:
|
||||
- phases/13-virtual-local-cloud-operations
|
||||
provides:
|
||||
- test contract for Phase 14 analysis and cache implementation
|
||||
affects:
|
||||
- backend/tests/test_cloud_analysis_contract.py
|
||||
- backend/tests/test_cloud_cache.py
|
||||
- backend/tests/test_cloud_analysis_api.py
|
||||
- frontend/src/components/storage/__tests__/StorageBrowser.analysis-queue.test.js
|
||||
- frontend/src/stores/__tests__/cloudConnections.analysis.test.js
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- FakeCloudAdapter counter pattern for T-14-03/T-14-04 mutation/byte-download guards
|
||||
- version-key precedence helper (version > etag > fingerprint > content hash)
|
||||
- Dynamic import avoidance in Vitest (Vite resolves imports at transform time)
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- backend/tests/test_cloud_analysis_contract.py
|
||||
- backend/tests/test_cloud_cache.py
|
||||
- backend/tests/test_cloud_analysis_api.py
|
||||
- frontend/src/components/storage/__tests__/StorageBrowser.analysis-queue.test.js
|
||||
- frontend/src/stores/__tests__/cloudConnections.analysis.test.js
|
||||
modified: []
|
||||
|
||||
decisions:
|
||||
- D-06: translateAnalysisStatus must be a single-source function in the store — components never translate statuses independently (same pattern as D-12 health state map)
|
||||
- D-11: Default failure_behavior is pause_batch — tests assert the default and verify continue_item can be set
|
||||
- T-14-04: estimate and already-current checks must never call get_object — FakeCloudAdapter byte_call_count remains zero in all analysis paths
|
||||
- Vite dynamic import resolution: cloudAnalysis.js companion store tested via cloudConnections store directly (dynamic import of non-existent file fails at transform time even in try/catch)
|
||||
|
||||
metrics:
|
||||
duration: "~15 minutes"
|
||||
completed: "2026-06-23"
|
||||
tasks: 2
|
||||
files: 5
|
||||
---
|
||||
|
||||
# Phase 14 Plan 01: Red Test Contract Summary
|
||||
|
||||
One-liner: RED backend and frontend test contract establishing analysis scope selection, estimates without byte downloads, duplicate-version skips, cache ownership/quota semantics, cancellation/retry controls, and shared-browser queue surface.
|
||||
|
||||
## What Was Built
|
||||
|
||||
This plan creates the executable test contract for Phase 14 before any implementation begins. All tests are intentionally RED — they fail because Phase 14 modules do not yet exist. They define the implementation contract that subsequent plans must satisfy.
|
||||
|
||||
### Backend Tests (3 files, 42 tests)
|
||||
|
||||
**test_cloud_analysis_contract.py** (16 tests):
|
||||
- ANALYZE-01: single-file estimate returns supported_count + total_provider_bytes, zero byte_call_count
|
||||
- ANALYZE-02: selection estimate aggregates multiple files, reports unsupported count
|
||||
- ANALYZE-03: whole-connection estimate always returns recursive response; folder scope accepts recursion flag
|
||||
- ANALYZE-06: already-indexed item with unchanged etag marked already_current without get_object call; changed etag triggers requeue
|
||||
- ANALYZE-07: analysis job never calls any provider mutation method (FakeCloudAdapter.mutation_call_count stays zero)
|
||||
- T-14-01: foreign user cannot estimate/enqueue/read-status/cancel — 403/404
|
||||
- T-14-01: admin cannot enqueue another user's analysis job
|
||||
- T-14-02: job status response excludes credentials_enc, access_token, refresh_token, object_key
|
||||
- ANALYZE-05: cancel transitions to "cancelled"/"cancelling"; retry transitions to "queued"
|
||||
|
||||
**test_cloud_cache.py** (12 tests):
|
||||
- CACHE-03: cache entry created during analysis; browse never creates cache entries
|
||||
- CACHE-04: eviction skips pinned entries (pin_count > 0 protected, D-16); LRU evicts oldest unpinned first
|
||||
- T-14-05: quota increment/decrement seam — increment_quota_for_cache and decrement_quota_for_cache function signatures verified
|
||||
- CACHE-05 / T-14-01: list_cache_entries is owner-scoped — foreign user sees zero entries
|
||||
- T-14-02: cache API response never includes object_key; admin blocked from cache status endpoint
|
||||
- ANALYZE-06 / D-19: compute_version_key precedence: version > etag > metadata fingerprint; content_hash=None accepted without byte-fetch fallback; deterministic output
|
||||
|
||||
**test_cloud_analysis_api.py** (14 tests):
|
||||
- Route registration gates for estimate/jobs/status/cancel endpoints (RED: 404 until router wired)
|
||||
- ANALYZE-04 / D-06: job status includes simplified aggregate counts (default) and detailed per-stage counts (detail=true)
|
||||
- ANALYZE-05: skip item transitions to skipped status
|
||||
- Security: unauthenticated requests blocked (401/403/404)
|
||||
- T-14-02: enqueue response excludes sensitive fields
|
||||
- D-13: check_scan_quota function signature exists (scan quota seam distinct from storage quota)
|
||||
- D-11: failure_behavior="continue_item" accepted; invalid failure_behavior rejected
|
||||
|
||||
### Frontend Tests (2 files, 41 tests)
|
||||
|
||||
**StorageBrowser.analysis-queue.test.js** (22 tests, 21 RED):
|
||||
- D-01: each cloud file row has [data-test="analyze-file"] button; click emits analyze-file with item payload
|
||||
- D-01: Analyze row action absent in local mode
|
||||
- D-01: toolbar [data-test="analyze-selection"] present when files selected; emits analyze-selection with array
|
||||
- D-01/ANALYZE-03: toolbar [data-test="analyze-connection"] present; emits analyze-connection with connection id
|
||||
- D-01/ANALYZE-02: [data-test="analyze-folder"] present when inside a folder
|
||||
- D-02/D-03: analysisEstimate prop triggers [data-test="analysis-estimate-modal"]; modal shows supported/unsupported counts and [data-test="estimate-start"]; clicking Start emits analysis-confirmed
|
||||
- D-05/D-07: analysisQueue prop accepted; [data-test="analysis-aggregate-progress"] rendered; simplified labels shown by default; expandable [data-test="analysis-queue-item-list"] with per-item rows
|
||||
- D-08: detailed mode shows stage indicators (download/extracting/classifying)
|
||||
- D-09: [data-test="analysis-item-cancel"] per row; click emits analysis-item-cancel with item_id
|
||||
- D-10: failed items show [data-test="analysis-item-retry"] and [data-test="analysis-item-skip"]
|
||||
- D-09: [data-test="analysis-cancel-all"] present; click emits analysis-cancel-all with job_id
|
||||
- Architecture: StorageBrowser renders cloud files (no parallel grid motivation)
|
||||
|
||||
**cloudConnections.analysis.test.js** (17 tests, 15 RED):
|
||||
- Analysis state (analysisJobs/activeAnalysisJob/analysisQueue) exposed from store
|
||||
- translateAnalysisStatus: simplified mode maps 10 internal statuses to 5 labels; detailed mode maps 1:1
|
||||
- requestEstimate calls api.estimateAnalysis without credential fields
|
||||
- enqueueAnalysis, cancelJob, retryItem, skipItem call correct API functions
|
||||
- Default failureBehavior is "pause_batch"; can be changed to "continue_item"
|
||||
- detailedAnalysisProgress defaults falsy; can be set to true
|
||||
- localStorage spy confirms no credential values written during analysis actions
|
||||
- fetchJobStatus: analysisQueue items contain no credentials or object_key
|
||||
- Cache limit exposed with positive default; updateCacheSettings calls API
|
||||
|
||||
## Threat Coverage
|
||||
|
||||
| Threat | Tests |
|
||||
|--------|-------|
|
||||
| T-14-01 IDOR | 6 backend negative tests (estimate/enqueue/status/cancel foreign + admin) |
|
||||
| T-14-02 Credential/key disclosure | 4 backend tests; 1 frontend credential-storage guard |
|
||||
| T-14-03 Hidden provider mutation | FakeCloudAdapter.mutation_call_count == 0 in 3 tests |
|
||||
| T-14-04 Hidden byte download | FakeCloudAdapter.byte_call_count == 0 in 5 tests (estimate + already-current) |
|
||||
| T-14-05 Cache quota corruption | increment_quota_for_cache + decrement_quota_for_cache seam tests |
|
||||
|
||||
## RED Failure Modes
|
||||
|
||||
All failures are due to missing Phase 14 modules — not syntax/import errors in the tests themselves:
|
||||
|
||||
**Backend:**
|
||||
- `ModuleNotFoundError: No module named 'api.cloud.analysis'`
|
||||
- `ImportError: cannot import name 'create_cache_entry' from 'services.cloud_cache'`
|
||||
- `ImportError: cannot import name 'CloudByteCacheEntry' from 'db.models'`
|
||||
- `ImportError: cannot import name 'compute_version_key' from 'services.cloud_cache'`
|
||||
- `ImportError: cannot import name 'check_scan_quota' from 'services.cloud_analysis'`
|
||||
|
||||
**Frontend:**
|
||||
- Missing `analysisQueue` prop on StorageBrowser (Vue prop validation)
|
||||
- Missing `[data-test="analyze-file"]` in file rows
|
||||
- Missing `[data-test="analysis-aggregate-progress"]` container
|
||||
- Missing `translateAnalysisStatus`, `requestEstimate`, `cancelJob`, `retryItem`, `skipItem` on cloudConnections store
|
||||
- Missing `failureBehavior` / `detailedAnalysisProgress` store state
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
**[Rule 3 - Blocking Fix] Dynamic import issue in Vitest store tests**
|
||||
- **Found during:** Task 2 frontend test implementation
|
||||
- **Issue:** `cloudConnections.analysis.test.js` originally used dynamic `import('../cloudAnalysis.js')` inside try/catch to allow for a companion store. Vite resolves dynamic imports statically at transform time; even with try/catch, a non-existent module path causes the whole test file to fail at import-resolution (before any tests run).
|
||||
- **Fix:** Rewrote all store tests to use the synchronous `useCloudConnectionsStore()` import directly. Missing properties/methods produce the expected RED failures without import errors. If Phase 14 uses a companion store, it must re-export from cloudConnections.js.
|
||||
- **Files modified:** `frontend/src/stores/__tests__/cloudConnections.analysis.test.js`
|
||||
- **Commit:** 7f2f570
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — this plan creates only tests; no production code stubs exist.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None — this plan adds test files only. No new network endpoints, auth paths, or schema changes.
|
||||
|
||||
## Self-Check: PASSED
|
||||
Reference in New Issue
Block a user