kandev/docs/plans/storage-analysis-progress/task-02-progressive-overview-state.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
02-progressive-overview-state	Add progressive overview state	done	2	01-bounded-filesystem-scanner	plan.md	REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002	AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10	../../specs/system-page/system-design/storage-analysis-progress.md

Task 02: Add Progressive Overview State

Summary

Make storage overview reads nonblocking. Add single-flight progress state, stale-while-revalidate snapshots, safe notifications, timing metadata, logs, and metrics.

In scope

• Add progressive source callbacks to storageOverview.
• Extend OverviewCache with nonblocking state reads and generation fencing.
• Extend the storage response with snapshot, progress, and timing fields.
• Publish system.storage.analysis.updated without storage details.
• Add gateway wiring and focused observability.
• Preserve manual Analyze run history and job behavior.

Out of scope

• Frontend rendering and polling.
• Persistent cache storage.
• Cleanup provider changes.

Acceptance

• A blocked cold provider cannot block the initial HTTP response.
• Expired and failed refreshes keep the last successful snapshot unchanged.
• Concurrent reads, Analyze, invalidation, and late progress obey one generation-fenced flight.

Verification

(cd apps/backend && go test -race ./internal/system/storage ./internal/backendapp ./internal/gateway/websocket)

Files likely touched

• apps/backend/internal/system/storage/overview_cache.go
• apps/backend/internal/system/storage/overview_cache_test.go
• apps/backend/internal/system/storage/handler.go
• apps/backend/internal/system/storage/handler_test.go
• apps/backend/internal/system/storage/types.go
• apps/backend/internal/system/storage/operations.go
• apps/backend/internal/backendapp/storage_maintenance.go
• apps/backend/internal/backendapp/storage_maintenance_test.go
• apps/backend/internal/events/types.go
• apps/backend/internal/gateway/websocket/system_notifications.go
• apps/backend/pkg/websocket/actions.go

Dependencies

Task 01 supplies bounded progress callbacks.

Risks

• Manual Analyze can accidentally create a second scan or job.
• Publishing while the cache mutex is locked can deadlock event consumers.
• A late callback can replace current state without generation checks.

Parallelism

sequential

Inputs

• storage-analysis-progress.md sections "Analysis state", "Cache flow", and "Progress delivery".
• ADR 2026-09-05-bounded-progressive-storage-analysis.

Results

Implemented the progressive cache/API contract, generation-fenced single-flight refreshes, WebSocket notifications, structured completion logging, and storage scan metrics. The exact race suite passed: 1,423 tests across storage, backendapp, and gateway/websocket.