docs(06-01): complete track_metadata VIEW consolidation plan
- SUMMARY.md: 2 tasks, 4 files, 2min duration - STATE.md: advance to Phase 6 plan 1/3 - ROADMAP.md: update progress for phases 3-6 - REQUIREMENTS.md: mark QUAL-01 complete
This commit is contained in:
@@ -21,8 +21,8 @@ Requirements for the consolidation milestone. Each maps to roadmap phases.
|
||||
|
||||
### Code Quality
|
||||
|
||||
- [ ] **QUAL-01**: Duplicated FTS5 JOIN pattern (5+ copies) is consolidated into a single SQLite VIEW (track_metadata or similar)
|
||||
- [ ] **QUAL-02**: Event name constants are generated from Go source (backend/events/events.go) to TypeScript (frontend/src/events.ts) via codegen, wired into go generate and pre-commit hook
|
||||
- [x] **QUAL-01**: Duplicated FTS5 JOIN pattern (5+ copies) is consolidated into a single SQLite VIEW (track_metadata or similar)
|
||||
- [x] **QUAL-02**: Event name constants are generated from Go source (backend/events/events.go) to TypeScript (frontend/src/events.ts) via codegen, wired into go generate and pre-commit hook
|
||||
- [ ] **QUAL-03**: Queue batch lookups in persistence.go use sqlc.slice() instead of fmt.Sprintf placeholder construction where feasible
|
||||
- [ ] **QUAL-04**: Intentional hand-crafted SQL exceptions (batch INSERT, dynamic IN clauses) are documented with // SAFETY: comments explaining why they bypass sqlc
|
||||
|
||||
@@ -98,8 +98,8 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| CORR-07 | Phase 2: Backend Correctness | Complete |
|
||||
| CORR-08 | Phase 2: Backend Correctness | Complete |
|
||||
| CORR-09 | Phase 2: Backend Correctness | Complete |
|
||||
| QUAL-01 | Phase 6: SQL Consolidation & Code Quality | Pending |
|
||||
| QUAL-02 | Phase 6: SQL Consolidation & Code Quality | Pending |
|
||||
| QUAL-01 | Phase 6: SQL Consolidation & Code Quality | Complete |
|
||||
| QUAL-02 | Phase 6: SQL Consolidation & Code Quality | Complete |
|
||||
| QUAL-03 | Phase 6: SQL Consolidation & Code Quality | Pending |
|
||||
| QUAL-04 | Phase 6: SQL Consolidation & Code Quality | Pending |
|
||||
| PERF-01 | Phase 7: Backend Performance | Pending |
|
||||
|
||||
+12
-12
@@ -57,7 +57,7 @@ Plans:
|
||||
4. Tests using `NewTestDB` pass with `-race` flag enabled
|
||||
**Plans:** 1 plan
|
||||
Plans:
|
||||
- [ ] 03-01-PLAN.md — Extract shared applyPRAGMAs, add production PRAGMAs, and create NewTestDB helper
|
||||
- [x] 03-01-PLAN.md — Extract shared applyPRAGMAs, add production PRAGMAs, and create NewTestDB helper
|
||||
|
||||
### Phase 4: Queue, Config & Player Tests
|
||||
**Goal:** The queue, config, and player packages have comprehensive unit tests that characterize current behavior and serve as a safety net for later refactoring
|
||||
@@ -70,8 +70,8 @@ Plans:
|
||||
4. All tests in this phase pass with `-race` flag enabled
|
||||
**Plans:** 2 plans
|
||||
Plans:
|
||||
- [ ] 04-01-PLAN.md — Queue package unit tests (core operations, navigation, persistence roundtrip)
|
||||
- [ ] 04-02-PLAN.md — Config + Player tests (sub-config validators, load/save roundtrip, volume conversion, state mapping)
|
||||
- [x] 04-01-PLAN.md — Queue package unit tests (core operations, navigation, persistence roundtrip)
|
||||
- [x] 04-02-PLAN.md — Config + Player tests (sub-config validators, load/save roundtrip, volume conversion, state mapping)
|
||||
|
||||
### Phase 5: Database & Library Tests
|
||||
**Goal:** Database queries (especially FTS5 search) and library scan logic have unit tests that lock down current behavior before SQL consolidation and performance optimization
|
||||
@@ -84,8 +84,8 @@ Plans:
|
||||
4. All tests in this phase pass with `-race` flag enabled
|
||||
**Plans:** 2 plans
|
||||
Plans:
|
||||
- [ ] 05-01-PLAN.md — FTS5 search tests, pure helper tests, search index operations, migration verification
|
||||
- [ ] 05-02-PLAN.md — Entity cache tests, library pure helpers, orphan cleanup tests
|
||||
- [x] 05-01-PLAN.md — FTS5 search tests, pure helper tests, search index operations, migration verification
|
||||
- [x] 05-02-PLAN.md — Entity cache tests, library pure helpers, orphan cleanup tests
|
||||
|
||||
### Phase 6: SQL Consolidation & Code Quality
|
||||
**Goal:** Duplicated SQL patterns are eliminated, event names are provably synchronized between Go and TypeScript, and intentional SQL exceptions are documented
|
||||
@@ -98,8 +98,8 @@ Plans:
|
||||
4. Every hand-crafted SQL statement that intentionally bypasses sqlc has a `// SAFETY:` comment explaining why (batch INSERT, dynamic IN clauses, etc.)
|
||||
**Plans:** 3 plans
|
||||
Plans:
|
||||
- [ ] 06-01-PLAN.md — Create track_metadata VIEW and consolidate search queries
|
||||
- [ ] 06-02-PLAN.md — Event codegen tool (Go→TypeScript) and pre-commit hook wiring
|
||||
- [x] 06-01-PLAN.md — Create track_metadata VIEW and consolidate search queries
|
||||
- [x] 06-02-PLAN.md — Event codegen tool (Go→TypeScript) and pre-commit hook wiring
|
||||
- [ ] 06-03-PLAN.md — Migrate lookupChunk to sqlc.slice() and add SAFETY comments to all hand-crafted SQL
|
||||
|
||||
### Phase 7: Backend Performance
|
||||
@@ -129,13 +129,13 @@ Plans:
|
||||
|-------|----------------|--------|-----------|
|
||||
| 1. Concurrency Race Fixes | 1/1 | Complete | 2026-02-28 |
|
||||
| 2. Backend Correctness | 2/2 | Complete | 2026-03-03 |
|
||||
| 3. Test Infrastructure | 0/1 | Planned | — |
|
||||
| 4. Queue, Config & Player Tests | 0/2 | Planned | — |
|
||||
| 5. Database & Library Tests | 0/2 | Planned | — |
|
||||
| 6. SQL Consolidation & Code Quality | 0/3 | Planned | — |
|
||||
| 3. Test Infrastructure | 1/1 | Complete | 2026-03-04 |
|
||||
| 4. Queue, Config & Player Tests | 2/2 | Complete | 2026-03-04 |
|
||||
| 5. Database & Library Tests | 2/2 | Complete | 2026-03-04 |
|
||||
| 6. SQL Consolidation & Code Quality | 2/3 | In Progress | — |
|
||||
| 7. Backend Performance | 0/? | Not started | — |
|
||||
| 8. Frontend Performance & UX | 0/? | Not started | — |
|
||||
|
||||
---
|
||||
*Roadmap created: 2026-02-27*
|
||||
*Last updated: 2026-03-02*
|
||||
*Last updated: 2026-03-05*
|
||||
|
||||
+26
-23
@@ -2,13 +2,13 @@
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: milestone
|
||||
status: completed
|
||||
last_updated: "2026-03-04T21:49:00.903Z"
|
||||
status: in-progress
|
||||
last_updated: "2026-03-05T00:23:19Z"
|
||||
progress:
|
||||
total_phases: 5
|
||||
total_phases: 8
|
||||
completed_phases: 5
|
||||
total_plans: 8
|
||||
completed_plans: 8
|
||||
total_plans: 11
|
||||
completed_plans: 10
|
||||
---
|
||||
|
||||
# YellowJacket — Consolidation Milestone State
|
||||
@@ -16,17 +16,17 @@ progress:
|
||||
## Project Reference
|
||||
|
||||
**Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.
|
||||
**Current focus:** Phase 5 complete — 15 database search tests + 13 library scan tests all passing with -race.
|
||||
**Current focus:** Phase 6 in progress — track_metadata VIEW + event codegen complete, 1 plan remaining (SAFETY comments).
|
||||
**Milestone:** Consolidation (correctness, performance, code quality, UX polish, test coverage)
|
||||
|
||||
## Current Position
|
||||
|
||||
**Phase:** 05-database-library-tests (complete)
|
||||
**Plan:** 2/2 (complete)
|
||||
**Status:** Milestone complete
|
||||
**Phase:** 06-sql-consolidation-code-quality (in progress)
|
||||
**Plan:** 2/3 (06-01, 06-02 complete)
|
||||
**Status:** In progress
|
||||
|
||||
```
|
||||
Phase Progress: [#####...] 5/8 phases complete
|
||||
Phase Progress: [######..] 6/8 phases — Phase 6: 2/3 plans complete
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
@@ -48,6 +48,8 @@ Phase Progress: [#####...] 5/8 phases complete
|
||||
| 05-02 duration | 4 min |
|
||||
| Phase 05 P01 | 9 min | 2 tasks | 1 files |
|
||||
| Phase 05 P02 | 4 min | 2 tasks | 1 files |
|
||||
| Phase 06 P01 | 2 min | 2 tasks | 4 files |
|
||||
| Phase 06 P02 | 2 min | 2 tasks | 3 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -72,6 +74,8 @@ Phase Progress: [#####...] 5/8 phases complete
|
||||
| Volume roundtrip ±1 tolerance | ToUserVolume uses int truncation not rounding, causing up to 1 unit drift | Phase 4 |
|
||||
| Direct Library construction in tests | Bypasses Config.Validate os.Stat; entity cache functions only need ctx + db | Phase 5 |
|
||||
| Contentless FTS5 DELETE limitation | DeleteSearchIndex errors on content='' tables; production logs warning, stale entries are harmless | Phase 5 |
|
||||
| SQLite VIEW for JOIN dedup | track_metadata VIEW consolidates 5-table JOIN; migration2 keeps inline JOIN for upgrade path | Phase 6 |
|
||||
| AST-based event codegen | Iterate f.Decls directly for deterministic declaration-order output; atomic writes via temp+rename | Phase 6 |
|
||||
|
||||
### TODOs
|
||||
|
||||
@@ -82,7 +86,7 @@ Phase Progress: [#####...] 5/8 phases complete
|
||||
- [x] Execute Phase 2 Plan 02 (complete)
|
||||
- [x] Plan Phase 3 (complete)
|
||||
- [x] Execute Phase 3 Plan 01 (complete)
|
||||
- [ ] Validate sqlc + SQLite VIEW + FTS5 compatibility during Phase 6 planning (research flag)
|
||||
- [x] Validate sqlc + SQLite VIEW + FTS5 compatibility during Phase 6 planning (validated — sqlc generates TrackMetadatum model, all tests pass)
|
||||
- [x] Design queue test architecture during Phase 4 planning (complete)
|
||||
- [x] Determine library scan test fixture strategy during Phase 5 planning (complete — inline construction, setupTestLibrary helper)
|
||||
- [ ] Measure startup time with large library before Phase 7 lazy loading work
|
||||
@@ -114,21 +118,20 @@ None currently.
|
||||
|
||||
### Last Session
|
||||
|
||||
**Date:** 2026-03-04
|
||||
**What happened:** Executed Phase 5 Plan 01 — FTS5 search tests (pure helpers, search queries, index ops, migrations)
|
||||
**Where we stopped:** Completed 05-01-PLAN.md (all 2 tasks, verification passed). Phase 5 fully complete.
|
||||
**Next action:** `/gsd-plan-phase 6` to plan SQL consolidation
|
||||
**Date:** 2026-03-05
|
||||
**What happened:** Executed Phase 6 Plan 02 — Go→TypeScript event codegen tool with go/ast, fixing LibraryConfigChanged gap
|
||||
**Where we stopped:** Completed 06-02-PLAN.md (2 tasks, all verification passed). Phase 6 plan 2/3 done.
|
||||
**Next action:** `/gsd-execute-phase 06` to continue with 06-03-PLAN.md
|
||||
|
||||
### Context for Next Session
|
||||
|
||||
- Phase 5 complete: TEST-03 (15 database tests) + TEST-06 (13 library tests) requirements delivered
|
||||
- 84 tests total: 29 queue + 27 config/player + 15 database search + 13 library scan, all passing with `-race`
|
||||
- Contentless FTS5 limitation documented — DELETE fails on content='' tables
|
||||
- QueryContext rows must be closed before next ExecContext on single-connection SQLite
|
||||
- `codegen-check` lefthook pre-commit hook hangs — use `LEFTHOOK=0` for commits
|
||||
- Ready for Phase 6 (SQL consolidation)
|
||||
- Event codegen tool at backend/events/cmd/genevents/main.go
|
||||
- LibraryConfigChanged gap automatically fixed by codegen
|
||||
- `go generate ./...` completes in ~1.8s, codegen-check hook works end-to-end
|
||||
- `codegen-check` pre-commit hook no longer hangs — can use LEFTHOOK=1 for commits
|
||||
- Phase 6: 2/3 plans complete, SAFETY comments plan remaining
|
||||
|
||||
---
|
||||
*State initialized: 2026-02-27*
|
||||
Last activity: 2026-03-04 - Completed 05-01: FTS5 search tests (helpers, queries, index ops, migrations)
|
||||
*Last updated: 2026-03-04*
|
||||
Last activity: 2026-03-05 - Completed 06-02: Go→TypeScript event codegen with go/ast and pre-commit hook
|
||||
*Last updated: 2026-03-05*
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
phase: 06-sql-consolidation-code-quality
|
||||
plan: 01
|
||||
subsystem: database
|
||||
tags: [sqlite, view, fts5, sql-consolidation, sqlc]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 05-database-library-tests
|
||||
provides: "15 FTS5 search tests as safety net for VIEW consolidation"
|
||||
provides:
|
||||
- "track_metadata VIEW consolidating 5-table metadata JOIN"
|
||||
- "Migration 4 for existing databases"
|
||||
- "sqlc schema awareness of track_metadata VIEW"
|
||||
affects: [07-performance-startup-optimization, 08-frontend-polish-accessibility]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: ["SQLite VIEW for JOIN deduplication", "migration-backed VIEW creation"]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- "backend/database/sql/schemas/track_metadata_view.sql"
|
||||
modified:
|
||||
- "backend/database/database.go"
|
||||
- "backend/database/search.go"
|
||||
- "backend/database/sql/sqlcgen/models.go"
|
||||
|
||||
key-decisions:
|
||||
- "VIEW uses CREATE VIEW IF NOT EXISTS for idempotent schema application"
|
||||
- "migration2 inline JOIN preserved — runs before migration 4 for upgrade path"
|
||||
|
||||
patterns-established:
|
||||
- "SQLite VIEW as single source of truth for complex multi-table JOINs"
|
||||
|
||||
requirements-completed: [QUAL-01]
|
||||
|
||||
# Metrics
|
||||
duration: 2min
|
||||
completed: 2026-03-05
|
||||
---
|
||||
|
||||
# Phase 6 Plan 1: SQL Consolidation — track_metadata VIEW Summary
|
||||
|
||||
**Consolidated 4 duplicated 5-table FTS5 JOINs into a single `track_metadata` SQLite VIEW with migration 4 and sqlc schema awareness**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 2 min
|
||||
- **Started:** 2026-03-05T00:20:53Z
|
||||
- **Completed:** 2026-03-05T00:23:19Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 4
|
||||
|
||||
## Accomplishments
|
||||
- Created `track_metadata` VIEW consolidating the 5-table audio metadata JOIN pattern
|
||||
- Added migration 4 to create the VIEW for existing databases (user_version 3→4)
|
||||
- Replaced all 4 inline JOINs in search.go (SearchFTS, SearchFTSByFilename, SearchFTSTracks, RebuildSearchIndex) with VIEW references
|
||||
- All 15 existing FTS5 search tests pass unchanged with `-race`
|
||||
- Net reduction: 60 lines of duplicated SQL eliminated
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Create track_metadata VIEW schema and migration** - `9c7e5a9` (feat)
|
||||
2. **Task 2: Consolidate search queries to use track_metadata VIEW** - `9159b40` (refactor)
|
||||
|
||||
## Files Created/Modified
|
||||
- `backend/database/sql/schemas/track_metadata_view.sql` - VIEW definition for sqlc schema awareness
|
||||
- `backend/database/database.go` - Migration 4 (track_metadata VIEW creation for existing databases)
|
||||
- `backend/database/search.go` - All 4 search functions now use `JOIN track_metadata` instead of inline JOINs
|
||||
- `backend/database/sql/sqlcgen/models.go` - sqlc-generated TrackMetadatum model from VIEW
|
||||
|
||||
## Decisions Made
|
||||
- VIEW uses `CREATE VIEW IF NOT EXISTS` for idempotent schema application (safe for both fresh and migrated databases)
|
||||
- migration2 inline JOIN intentionally preserved — it runs at user_version=1→2 before the VIEW exists at version=3→4
|
||||
- TrackMetadatum sqlc model generated automatically but not used in Go code yet (available for future sqlc queries against the VIEW)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
None
|
||||
|
||||
## User Setup Required
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- VIEW consolidation complete, search.go has zero duplicated JOINs
|
||||
- Ready for remaining Phase 6 plans (code quality improvements)
|
||||
- Track metadata VIEW available for future sqlc queries
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
All created files exist on disk. All commit hashes verified in git log.
|
||||
|
||||
---
|
||||
*Phase: 06-sql-consolidation-code-quality*
|
||||
*Completed: 2026-03-05*
|
||||
Reference in New Issue
Block a user