[Reliability] Add a versioned crash-safe project format, autosave, migration and recovery

[seonghobae]

Parent: #958
Baseline: #968

Buyer-visible gap

A rehearsal project is durable user work: local audio references, role selections, analysis results, user-corrected boundaries, cue decisions, handoff metadata, and future player state. The current 83-PR inventory contains handoff and many UI/security slices, but no live PR is designated as the canonical owner of a versioned crash-safe project format, autosave, atomic publication, migration, backup, and recovery.

A commercial desktop product must prove that a crash, power loss, interrupted write, application upgrade, or rollback does not silently destroy or reinterpret a band's work.

Product outcome

BandScope owns one documented, versioned, and recoverable local project format:

open or create project
→ mutate through typed commands
→ append bounded recovery-safe autosave evidence
→ atomically publish a consistent snapshot
→ migrate a validated copy on upgrade
→ restore or roll back without hidden data loss

Required scope

Canonical project contract

• Define a stable public schema and project_format_version independent of the application package version.
• Separate source references, derived analysis artifacts, user decisions/corrections, portable handoff data, UI preferences, and volatile runtime state.
• Store local audio through app-owned identifiers and bounded file/content evidence; do not leak arbitrary absolute paths into portable artifacts.
• Version analysis engine/backend/model identity and preserve confidence/limitations with each result.
• Publish a machine-verifiable schema and golden fixtures for every supported version.
• Preserve unknown forward-compatible data or fail closed according to an explicit compatibility rule; never silently discard fields.

Atomic persistence

• Stage a complete candidate, flush required data, validate it, atomically replace the previous snapshot, and retain a known-good backup.
• Ensure crash, cancellation, disk-full, and permission failure cannot replace a good project with a partial file.
• Bound file size, collection counts, string lengths, nesting depth, and artifact counts before allocation.
• Defend the actual filesystem boundary against symlink/path traversal and time-of-check/time-of-use failures.
• Use one storage authority and one transaction boundary rather than independent React/localStorage/native writers.

Autosave and recovery

• Debounce/coalesce autosaves without losing the latest accepted mutation.
• Keep a bounded journal or rotating recovery snapshots with integrity hashes and monotonic ordering.
• Detect unclean shutdown or a newer recoverable draft at startup and offer accessible Restore / Compare / Discard choices.
• Support manual save, Save As, export, and safe close while autosave or analysis completion is in flight.
• Never upload recovery content or include private project/audio payloads in diagnostics.

Migration and rollback

• Implement ordered, deterministic, idempotent migrations with source/target version, input/output hash, and result receipt.
• Migrate a copy first; publish only after full validation; retain the pre-migration artifact until the new version opens successfully.
• Provide supported downgrade behavior when compatible and an explicit block/portable-export path otherwise.
• Test clean install, upgrade from every supported fixture, interrupted migration, repeated migration, and application rollback.

Boundary with current handoff work

Live PRs #737 and #740 own versioned outbound/inbound rehearsal handoff slices. They are portable, bounded interchange contracts—not substitutes for the durable local project source of truth.

The project contract must integrate the active rehearsal-player state from #961 only after that public state machine is stable.

Acceptance criteria

• One documented project schema and public command API own every durable project mutation.
• Every supported historical fixture opens or returns an explicit actionable incompatibility result.
• Fault injection proves no partial snapshot replaces the last known-good project during crash, kill, disk-full, permission error, or cancellation.
• Autosave is bounded, preserves the latest accepted edit, and cannot race project close or Save As.
• Recovery choices are usable by keyboard and screen reader and disclose what will be restored without unnecessary path exposure.
• Migrations are deterministic and idempotent and produce version/hash receipts; rollback evidence is retained.
• Unknown fields, malformed data, excessive depth/count/size, duplicate IDs, cycles, and unsupported versions follow the published fail-closed contract.
• A project remains semantically equivalent across supported Windows and macOS path conventions.
• Property, fuzz, filesystem integration, migration, and platform-specific atomicity tests pass on the exact head.
• Repository-owned production statement/branch coverage and public API documentation remain 100%.
• Current-head checks, qualifying independent approval, zero unresolved actionable threads, and branch protection pass without bypass.

Real-world fault cases

• termination between write, flush, validation, and replace;
• disk full after staging but before publication;
• source audio moved, replaced, truncated, or permission-revoked;
• two windows attempt to mutate the same project;
• system clock moves backward;
• hostile project with huge counts, nesting, strings, or duplicate identities;
• migration succeeds but first open of migrated data fails;
• application rollback after opening a newer format;
• autosave fires while analysis, handoff import, or player state changes.

Non-goals

• No mandatory cloud account or remote database.
• No opaque binary format without a documented migration/export story.
• No silent best-effort data dropping.
• No raw project/audio content in ordinary logs or support bundles.