StarPunk/docs/projectplan/v1.1/priority-work.md

StarPunk v1.1.0: Priority Work Items

Overview

This document identifies HIGH PRIORITY work items that MUST be completed for the v1.1.0 release. These items address critical issues discovered in production and architectural improvements required for system stability.

Target Release: v1.1.0 Status: Planning Created: 2025-11-24

Critical Priority Items

These items MUST be completed before v1.1.0 release.

---

1. Database Migration System Redesign - Phase 2

Priority: CRITICAL ADR: ADR-032 Estimated Effort: 4-6 hours Dependencies: None Risk: Low (backward compatible)

Problem

The current database initialization system fails when upgrading existing production databases because SCHEMA_SQL represents the current schema rather than the initial v0.1.0 baseline. This causes indexes to be created on columns that don't exist yet.

Solution

Implement INITIAL_SCHEMA_SQL as designed in ADR-032 to represent the v0.1.0 baseline schema. All schema evolution will happen through migrations.

Implementation Tasks

1. Create INITIAL_SCHEMA_SQL constant (database.py)

   INITIAL_SCHEMA_SQL = """
   -- V0.1.0 baseline schema from commit a68fd57
   -- [Full SQL as documented in ADR-032]
   """
   

2. Modify init_db() function (database.py)

   • Add database existence check
   • Use INITIAL_SCHEMA_SQL for fresh databases
   • Run migrations for all databases
   • See ADR-032 for complete logic

3. Add helper functions (database.py)

   • database_exists_with_tables(): Check if database has existing tables
   • Update imports and error handling

4. Update existing SCHEMA_SQL (database.py)

   • Rename to CURRENT_SCHEMA_SQL
   • Mark as documentation-only (not used for initialization)
   • Add clear comments explaining purpose

Testing Requirements

• Test fresh database initialization (should create v0.1.0 schema then migrate)
• Test upgrade from existing v1.0.0-rc.2 database
• Test upgrade from v0.x.x databases if available
• Verify all indexes created correctly
• Verify no duplicate table/index errors
• Test migration tracking (schema_migrations table)
• Performance test for fresh install (all migrations)

Documentation Updates

• Update database.py docstrings
• Add inline comments explaining dual schema constants
• Update deployment documentation
• Add production upgrade guide
• Update CHANGELOG.md

Success Criteria

• Existing databases upgrade without errors
• Fresh databases initialize correctly
• All migrations run in proper order
• No index creation errors
• Clear upgrade path from any version

---

2. IndieAuth Provider Strategy Implementation

Priority: HIGH ADR: ADR-021 (if exists) Estimated Effort: 8-10 hours Dependencies: Database migration system working correctly Risk: Medium (external service dependencies)

Problem

Current IndieAuth implementation may need updates based on production usage patterns and compliance requirements.

Implementation Notes

• Review existing ADR-021-indieauth-provider-strategy.md
• Implement any pending IndieAuth improvements
• Ensure full spec compliance

---

Medium Priority Items

These items SHOULD be completed for v1.1.0 if time permits.

3. Full-Text Search Implementation

Priority: MEDIUM Reference: v1.1/potential-features.md Estimated Effort: 3-4 hours Dependencies: None Risk: Low

Implementation Approach

• Use SQLite FTS5 extension
• Create shadow FTS table for note content
• Update on note create/update/delete
• Add search_notes() function to notes.py

---

4. Migration System Testing Suite

Priority: MEDIUM Estimated Effort: 4-5 hours Dependencies: Item #1 (Migration redesign) Risk: Low

Test Coverage Needed

• Migration ordering tests
• Rollback simulation tests
• Schema evolution tests
• Performance benchmarks
• CI/CD integration

---

Implementation Order

1. First: Complete Database Migration System Redesign (Critical)
2. Second: Add comprehensive migration tests
3. Third: IndieAuth improvements (if needed)
4. Fourth: Full-text search (if time permits)

Release Checklist

Before releasing v1.1.0:

• All CRITICAL items complete
• All tests passing
• Documentation updated
• CHANGELOG.md updated with all changes
• Version bumped to 1.1.0
• Migration guide written for production systems
• Release notes prepared
• Docker image tested with migrations

Risk Mitigation

Migration System Risks

• Risk: Breaking existing databases
• Mitigation: Comprehensive testing, backward compatibility, clear rollback procedures

Performance Risks

• Risk: Slow fresh installations (running all migrations)
• Mitigation: Migration performance testing, potential migration squashing in future

Deployment Risks

• Risk: Production upgrade failures
• Mitigation: Detailed upgrade guide, test on staging first, backup procedures

Notes for Implementation

For the Developer Implementing Item #1

1. Start with ADR-032 for complete design details
2. Check git history for original schema (commit a68fd57)
3. Test thoroughly - this is critical infrastructure
4. Consider edge cases:
   • Empty database
   • Partially migrated database
   • Corrupted migration tracking
   • Missing migration files

Key Files to Modify

1. /home/phil/Projects/starpunk/starpunk/database.py

   • Add INITIAL_SCHEMA_SQL constant
   • Modify init_db() function
   • Add helper functions

2. /home/phil/Projects/starpunk/tests/test_migrations.py

   • Add new test cases for initial schema
   • Test upgrade paths

3. /home/phil/Projects/starpunk/docs/architecture/database.md

   • Document schema evolution strategy
   • Explain dual schema constants

Success Metrics

• Zero database upgrade failures in production
• Fresh installation time < 1 second
• All tests passing
• Clear documentation for future maintainers
• Positive user feedback on stability

References

• ADR-031: Database Migration System Redesign
• ADR-032: Initial Schema SQL Implementation
• v1.1 Potential Features
• Migration Implementation Reports

---

Last Updated: 2025-11-24 Version: 1.0.0-rc.2 → 1.1.0 (planned)