Introduce clear transaction boundaries for workspace persistence (hybrid auto-save + explicit commit model)

[knightedcodemonkey]

Summary

Workspace state persistence currently relies heavily on auto-save behavior across content, metadata, and PR context fields. This creates race conditions during workspace switching and active PR context transitions, resulting in state mismatches (for example: tabs/content from one workspace combined with head/prNumber/prTitle from another).

We should move to explicit transaction boundaries for identity-critical state while preserving auto-save convenience for low-risk draft content.

Problem

Auto-save currently persists multiple classes of state with different risk profiles:

• Draft editor content (low risk)
• UI metadata (medium risk)
• Workspace identity and PR context fields (high risk)

When these are saved asynchronously without strict boundaries, load/switch flows can trigger cross-record writes and inconsistent records.

Observed failure modes include:

• Switched-to workspace tabs overwritten by switched-from workspace content
• Active PR workspace fields and tab content becoming semantically mismatched
• Repository-scoped/active-context workspaces more affected than local-only workspaces

Goal

Adopt a hybrid persistence model:

• Keep auto-save for draft content
• Require explicit/transactional commits for identity-critical workspace context
• Ensure workspace load/open actions are read-only and cannot cause writes

Proposed Design

1) Define persistence tiers

• Tier A: Draft content auto-save
  • tab content
  • editor scroll/position
• Tier B: Non-critical UI metadata auto-save
  • non-identity form hints
• Tier C: Identity-critical context (transactional)
  • workspace id/key/scope
  • repo/base/head
  • prContextState/prNumber/prTitle linkage
  • active workspace binding

2) Enforce transaction boundaries

• Workspace open/load must be read-only
• Suspend or reject writes during load transaction
• Apply all loaded state atomically, then re-enable writes
• Drop stale async writes via generation token/version guard

3) Add explicit context commit points

• Introduce explicit action for committing identity-critical context changes
• Keep draft auto-save independent from context commit
• For active PR context, require explicit apply/commit for head/base/pr linkage changes

4) Add write provenance/versioning

• Persist write metadata (writer, generation/version, timestamp)
• Reject writes from stale generation
• Improve diagnostics for dropped/stale writes

Acceptance Criteria

• Switching between repository-scoped workspaces does not mutate the switched-to record with switched-from tab data
• Loading a workspace performs no persistence writes until load transaction completes
• Active PR workspace records cannot end in mixed identity/content state
• Stale async saves are ignored deterministically
• Existing convenience of draft auto-save is preserved
• Regression tests cover:
  • active -> active same-repo switch
  • active -> inactive switch
  • cross-repo switch
  • rapid repeated switching

Non-Goals

• Removing auto-save entirely
• Reworking editor UX flows unrelated to persistence correctness
• Changing GitHub PR APIs or remote sync semantics

Suggested Milestones

1. Persistence tier model + save API separation
2. Load transaction guard + stale-write rejection
3. Explicit context commit flow
4. Regression suite + telemetry/debug traces

Notes

A recent class of bugs suggests correctness risks are concentrated around identity/context writes, not draft content writes. This proposal keeps UX convenience while enforcing correctness boundaries where it matters most.