xtablo-source/.planning/phases/05-files/05-VALIDATION.md

phase	slug	status	nyquist_compliant	wave_0_complete	created
5	files	complete	true	true	2026-05-15

Phase 5 — Validation Strategy

Per-phase validation contract for feedback sampling during execution.

---

Test Infrastructure

Property	Value
Framework	go test
Config file	none — built into Go toolchain
Quick run command	cd backend && go test ./internal/... -run TestFile -timeout 30s
Full suite command	cd backend && go test ./... -timeout 60s
Estimated runtime	~15 seconds

---

Sampling Rate

• After every task commit: Run cd backend && go test ./internal/... -run TestFile -timeout 30s
• After every plan wave: Run cd backend && go test ./... -timeout 60s
• Before /gsd-verify-work: Full suite must be green
• Max feedback latency: 60 seconds

---

Per-Task Verification Map

Task ID	Plan	Wave	Requirement	Threat Ref	Secure Behavior	Test Type	Automated Command	File Exists	Status
05-migration	—	1	FILE-01	—	tablo_files schema correct	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFileUpload -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-s3-client	—	1	FILE-02	—	S3 client connects to MinIO	integration (needs S3)	cd backend && go test ./internal/files/ -run TestNewStore_SkipIfNoEndpoint	✅	⚠️ needs S3_ENDPOINT
05-upload	—	1	FILE-02	—	MaxBytesReader enforced, bytes stored	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFileUpload -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-list	—	1	FILE-03	—	Files listed newest-first	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFilesList -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-download	—	1	FILE-04	—	Signed URL generated, 302 redirect	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFileDownload -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-delete	—	1	FILE-05	—	DB row and S3 object both removed	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFileDelete -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-authz	—	2	FILE-06	—	Non-owner gets 404	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFileOwnership -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-tabs	—	2	FILE-01	—	Tab routes render correct fragment	integration (needs DB)	cd backend && go test ./internal/web/ -run TestFilesTab -timeout 30s	✅	⚠️ needs TEST_DATABASE_URL
05-formatbytes	—	0	FILE-03	—	formatBytes converts byte counts correctly	unit	cd backend && go test ./templates/ -run TestFormatBytes -timeout 30s	✅	✅ green
05-bytecountreader	—	0	FILE-02	—	byteCountReader accumulates bytes correctly	unit	cd backend && go test ./internal/files/ -run TestByteCountReader -timeout 30s	✅	✅ green
05-contenttype-sniff	—	0	FILE-02	—	Content-type sniff uses DetectContentType, handles small files, reconstructs body	unit	cd backend && go test ./internal/files/ -run TestUpload_ContentTypeSniff -timeout 30s	✅	✅ green

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ needs infrastructure

---

Wave 0 Requirements

• backend/internal/files/store_test.go — compile-time interface assertion (TestStoreImplementsFileStorer), skip-if-no-endpoint live test
• backend/internal/files/store_unit_test.go — pure unit tests: byteCountReader behavior, content-type sniff + body reconstruction
• backend/templates/files_helpers_test.go — pure unit tests: formatBytes boundary cases
• backend/internal/web/handlers_files_test.go — integration stubs for FILE-01..FILE-06 (TestFileUpload, TestFilesList, TestFileDownload, TestFileDelete, TestFileOwnership, TestFilesTab)
• MinIO running in compose.yaml — integration tests need the local S3 endpoint

---

Manual-Only Verifications

Behavior	Requirement	Why Manual	Test Instructions
File upload form renders correctly in browser	FILE-01	Visual layout cannot be asserted in go test	Open /tablos/{id}/files, attach a file, verify form submits and file appears in list
Tab navigation updates URL via hx-push-url	FILE-01	Browser URL state not testable in unit tests	Click Tasks tab, verify URL changes to /tablos/{id}/tasks; hit Back, verify Overview tab reactivates
25MB upload size enforcement shows friendly error	FILE-02	Browser file size display is visual	Attempt to upload a >25MB file; verify error message appears above the form
Download opens file correctly via 302 redirect	FILE-04	Actual browser navigation/download	Click download link; verify browser downloads the file within signed URL TTL

---

Validation Sign-Off

• All tasks have <automated> verify or Wave 0 dependencies
• Sampling continuity: no 3 consecutive tasks without automated verify
• Wave 0 covers all MISSING references
• No watch-mode flags
• Feedback latency < 60s
• nyquist_compliant: true set in frontmatter

Approval: complete — unit tests green; integration tests require TEST_DATABASE_URL (skip cleanly without it)