kandev/docs/plans/database-selection-continuity/task-02-adopt-legacy-databases-safely.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-adopt-legacy-databases-safely	Adopt legacy databases safely	done	2	01-preserve-database-path-provenance	plan.md	REQ-PLATFORM-STARTUP-CONFIGURATION-PARITY-002	AC-PLATFORM-STARTUP-CONFIGURATION-PARITY-002.1 AC-PLATFORM-STARTUP-CONFIGURATION-PARITY-002.2 AC-PLATFORM-STARTUP-CONFIGURATION-PARITY-002.3 AC-PLATFORM-STARTUP-CONFIGURATION-PARITY-002.4	../../specs/platform/system-design/startup-database-selection-continuity.md

Task 02: Adopt Legacy Databases Safely

Summary

Resolve default SQLite candidates before writable open, adopt a sole legacy database through a validated staged snapshot, and fail without mutation on an empty-history conflict. Prove the complete launcher-to-persistence regression and document recovery behavior.

In scope

• Add source-aware default SQLite target selection and read-only candidate inspection.
• Replace legacy rename with staged snapshot, validation, atomic installation, and source retention.
• Detect the current-zero-task versus legacy-task-history conflict before repository startup.
• Add selection diagnostics, integration tests, failure-path tests, and public recovery guidance.

Out of scope

• Switching or merging when both databases contain task history.
• Arbitrary custom-path discovery.
• PostgreSQL, backup retention, restore, UI, and self-update changes.

Acceptance

• A default launch with only a WAL-backed legacy database exposes its task data from the current target and leaves the legacy files intact.
• A current default with no tasks and a legacy default with tasks causes a non-destructive startup error naming both candidates.
• Explicit paths bypass legacy discovery, and every staged-adoption failure leaves the source and prior target state unchanged.

Verification

cd apps/backend && go test ./internal/persistence ./internal/launcher -run '^(Test.*(Legacy|DatabaseContinuity|DatabaseConflict|DatabasePath))' -count=1
cd apps/backend && go test ./internal/persistence ./internal/launcher -count=1
cd apps/backend && go build ./cmd/kandev
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs

Files likely touched

• apps/backend/internal/persistence/provider.go
• apps/backend/internal/persistence/sqlite_selection.go
• apps/backend/internal/persistence/provider_legacy_test.go
• apps/backend/internal/launcher/database_handoff_integration_test.go
• docs/public/configuration.md
• docs/public/operations.md

Dependencies

• Task 01 must preserve default source provenance across child startup.

Risks

• Snapshot validation and atomic installation must work across macOS, Linux, and Windows filesystem semantics.
• Candidate inspection must tolerate historical schemas that have tasks but no kandev_meta table.
• Tests must prove committed WAL data is present in the adopted snapshot.

Parallelism

sequential

Inputs

• REQ-PLATFORM-STARTUP-CONFIGURATION-PARITY-002
• docs/specs/platform/system-design/startup-database-selection-continuity.md
• ADR 2026-08-27-preserve-legacy-sqlite-before-default-initialization
• Existing persistence.SnapshotSQLite and backup/restore validation patterns

Results

• Added source-aware SQLite selection before writable database open.
• Replaced destructive legacy rename with a WAL-safe VACUUM INTO snapshot, integrity and task-count validation, owner-only staged permissions, atomic installation, and source plus sidecar retention.
• Added launcher-to-persistence, WAL adoption, invalid-candidate, empty-current conflict, explicit-path, established-current, and failed installation coverage.
• Hardened installation with an atomic no-replace target operation and made established-current inspection use a lightweight task-history probe.
• Updated Docker and Kubernetes upgrade guidance and marked the implemented system design as current.
• Updated the public configuration and operations guides with continuity and recovery behavior.
• Verification passed:
  • go test ./internal/persistence ./internal/launcher -run '^(Test.*(Legacy|DatabaseContinuity|DatabaseConflict|DatabasePath))' -count=1
  • sanitized full package tests with KANDEV_INTERNAL_CONFIG_FILE, KANDEV_DATABASE_PATH, and KANDEV_DATABASE_DRIVER unset
  • targeted race tests for the persistence and launcher packages
  • go build ./cmd/kandev
  • make -C apps/backend lint
  • node --test scripts/validate-public-docs.test.mjs
  • node scripts/validate-public-docs.mjs