kandev/docs/plans/storage-analysis-progress/task-01-bounded-filesystem-scanner.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
01-bounded-filesystem-scanner	Build bounded filesystem scanner	done	1		plan.md	REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002	AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10	../../specs/system-page/system-design/storage-analysis-progress.md

Task 01: Build Bounded Filesystem Scanner

Summary

Add a shared read-only scanner with four active directory partitions. Migrate the three filesystem analysis providers without changing cleanup behavior or byte semantics.

In scope

• Add internal/system/storage/filescan with indexed multi-root results.
• Preserve symlink, marker, warning, cancellation, and missing-root behavior.
• Migrate workspace, Go-cache, and temporary-artifact analysis.
• Publish partition and root progress through a callback.
• Add deterministic concurrency tests and a comparison benchmark.

Out of scope

• Cache, HTTP, WebSocket, or React changes.
• Destructive cleanup paths.
• Operator configuration for concurrency.

Acceptance

• No more than four directory partitions execute at once across one overview scan.
• Two independent partitions can enter before either finishes, without timing assertions.
• Serial and bounded implementations return the same bytes, warnings, and symlink outcomes.

Verification

(cd apps/backend && go test -race ./internal/system/storage/filescan ./internal/system/storage/workspaces ./internal/system/storage/gocache ./internal/system/storage/tempartifacts ./internal/backendapp)
(cd apps/backend && go test ./internal/system/storage/filescan -run '^$' -bench 'BenchmarkMeasureTrees' -benchmem)

Files likely touched

• apps/backend/internal/system/storage/filescan/*.go
• apps/backend/internal/system/storage/filescan/*_test.go
• apps/backend/internal/system/storage/workspaces/provider.go
• apps/backend/internal/system/storage/workspaces/provider_test.go
• apps/backend/internal/system/storage/gocache/provider.go
• apps/backend/internal/system/storage/gocache/provider_test.go
• apps/backend/internal/system/storage/tempartifacts/provider.go
• apps/backend/internal/system/storage/tempartifacts/provider_test.go
• apps/backend/internal/backendapp/storage_maintenance.go

Dependencies

None.

Risks

• Root partitioning can double-count direct files or overlapping paths.
• A shared limiter can deadlock if a worker acquires another slot recursively.
• Provider warning order can become nondeterministic.

Parallelism

sequential

Inputs

• storage-analysis-progress.md sections "Bounded filesystem scanner" and "Filesystem scan".
• Existing directorySizeNoFollow implementations and provider tests.

Results

• Added the shared four-partition limiter and context-aware indexed scanner.
• Migrated workspace, Go-cache, and temporary-artifact analysis to the scanner while leaving cleanup traversal serial.
• Verified with go test -race ./internal/system/storage/filescan ./internal/system/storage/workspaces ./internal/system/storage/gocache ./internal/system/storage/tempartifacts ./internal/backendapp (853 tests passed).
• Verified BenchmarkMeasureTrees with go test ./internal/system/storage/filescan -run '^$' -bench 'BenchmarkMeasureTrees' -benchmem (81,604 ns/op, 11,367 B/op).