Phase 4A: IndexedDB Sync Metadata + Per-Tab Dirty/Reconcile State

[knightedcodemonkey]

Summary

Implement the Phase 4A foundation for multi-tab GitHub sync in @knighted/develop by extending IndexedDB tab records with sync metadata and introducing deterministic dirty/reconcile state transitions.

This issue is the storage/state prerequisite for Phase 4B/4C and Phase 6 cleanup.

Context

1. Arbitrary Dynamic Editor Tabs (vNext): Named Multi-File Workspace Model for @knighted/develop #53 defines Phase 4 as GitHub PR/file mapping integration for dynamic tabs.
2. Multi-Tab Workspace (Dynamic Tabs, Local IndexedDB Persistence, and Modular Preview Architecture) #62 delivered phases 1-3 local-first multi-tab foundations.
3. We now need a robust per-tab sync state model so mapping UX and push workflows can be implemented safely.

Goals

1. Keep persistence boundaries clear:
2. localStorage for user preferences and lightweight form/config state only.
3. IndexedDB for workspace tab content plus sync metadata.
4. Add per-tab sync metadata needed for multi-file GitHub workflows.
5. Make dirty/clean transitions deterministic and testable.
6. Preserve backward compatibility for existing records.

In Scope

1. IndexedDB schema extension for tab sync metadata.
2. Normalization/migration defaults for older records.
3. Dirty/reconcile state transition logic in tab/workspace state orchestration.
4. Hydration/persistence of new fields across reload/context switches.
5. Status hooks for PR drawer messaging (no app-level toast changes).

Out of Scope

1. Multi-tab mapping UI controls (Phase 4B).
2. Open PR selection/binding UX (Phase 4B).
3. Bulk commit API migration (Phase 4C).
4. AI apply/undo by tab ID (Phase 5).
5. Fixed-assumption cleanup (Phase 6), except minimal compatibility hooks needed for this data model.

Proposed Data Model (tab-level)

1. targetPrFilePath: string | null
2. isDirty: boolean
3. syncedAt: number | null
4. lastSyncedRemoteSha: string | null

Notes:

1. Field names can be finalized in implementation, but semantics must remain equivalent.
2. Defaults for migrated records should be safe and non-breaking.

Dirty/Reconcile Contract

1. Edit tab content after last successful sync -> isDirty = true.
2. Successful push including that tab -> isDirty = false, syncedAt updated, remote marker updated.
3. If remote/reference mismatch is detected during reconcile -> expose warning/conflict state via PR drawer status text.
4. Unmapped tabs may still be dirty locally, but sync-specific indicators should be meaningful for mapped tabs.

Acceptance Criteria

1. Existing workspace records load without data loss after migration.
2. New sync fields persist in IndexedDB and survive reload.
3. Dirty state toggles correctly on edit, save, and successful push reconcile events.
4. Tab hydration restores sync metadata consistently across workspace/context restores.
5. No new global toast behavior is introduced; status remains in PR drawer channel.
6. Lint/build/tests pass.

Implementation Notes

1. Keep implementation modular:
2. storage schema/normalization in storage module.
3. state transitions in tab/workspace state logic.
4. status projection consumed by PR drawer.
5. Avoid coupling this work to UI redesign.
6. Preserve local-first behavior as primary workflow even without GitHub connectivity.

Verification

1. Automated:
2. migration tests for legacy records without sync fields.
3. unit/integration tests for dirty transition rules.
4. Playwright coverage for reload persistence and dirty-state behavior.
5. Manual:
6. edit mapped tab after sync and verify dirty state.
7. simulate successful push reconcile and verify clean state.
8. reload and verify metadata/state integrity.

Dependencies

1. Depends on: Arbitrary Dynamic Editor Tabs (vNext): Named Multi-File Workspace Model for @knighted/develop #53, Multi-Tab Workspace (Dynamic Tabs, Local IndexedDB Persistence, and Modular Preview Architecture) #62.
2. Blocks: Phase 4B/4C issue and Phase 6 cleanup tasks that rely on sync metadata.

Suggested Follow-ups

1. Phase 4B/4C issue: mapping UX + open PR binding + bulk push path.
2. Phase 5 issue: AI apply/undo by tab ID.
3. Phase 6 issue: remove fixed component/styles assumptions and finalize modular cleanup.

[knightedcodemonkey]

Addressed in #78