fix(project): stage saves before atomic publication

[seonghobae]

Advances #962 on the existing Project Persistence owner. This remains the canonical storage/format/desktop-bridge dependency-root slice; descendants consolidate here without force-push or loss of unique tests/contracts.

Exact current identity

• Protected develop authority last observed: 314ddeae7b775a4957594b599358c8255617eb2e.
• Canonical Resource Admission prerequisite: fix(audio): establish canonical local-audio resource policy #866 841e1c9b7329dba6d0ff16daecc009a2c3face0c (fix/audio-resource-policy-781).
• Exact fix(project): stage saves before atomic publication #970 head: 8893a9251c6b448a059e72d7b4d175b1956a47b8.
• fix(project): stage saves before atomic publication #970 is open, Draft, and targets the fix(audio): establish canonical local-audio resource policy #866 branch. 841e1c... -> 8893a92... is now ahead, behind_by=0, with merge base exactly 841e1c...; predecessor checks/reviews/approvals do not transfer.

Ordinary Resource Admission adoption

Retargeting #970 onto #866 correctly exposed a dirty stack instead of treating the prerequisite as inherited GREEN. The overlap was repaired without force-push or destructive rebase:

• 7b2ade1370bda67e28372a090264abd708c5dc14 moves desktop-core back to the canonical src/root.rs crate root selected by fix(audio): establish canonical local-audio resource policy #866.
• ce81744e49f3f8ff56d848708f9b0232cbfce245 integrates Project Persistence project_format exports into that one crate root.
• 548c46e9f3716229cda3c55318049939fa960760 removes the duplicate crate_root.rs wrapper.
• 2a27d308994f2b49af8e4f384eed21898ece4f18 reconciles the five overlapping files. Resource Admission keeps the real app-owned audio materialization/publication/size+SHA-256 verification/native identity state; Project Persistence keeps staged crash-safe project publication/recovery and v3 document admission. The desktop bridge keeps fix(audio): establish canonical local-audio resource policy #866's encoded-byte policy and fix(project): stage saves before atomic publication #970's renderer error-redaction/project-document contract.
• 8893a9251c6b448a059e72d7b4d175b1956a47b8 is a non-force two-parent adoption commit with parents fix(project): stage saves before atomic publication #970 and exact fix(audio): establish canonical local-audio resource policy #866. Its tree starts from fix(audio): establish canonical local-audio resource policy #866 and overlays the reconciled Project Persistence delta, so fix(audio): establish canonical local-audio resource policy #866-only files/tests/contracts are not silently dropped.

Project Persistence truth

Draft/unreleased format v3 retains preferences.selectedPlaybackSource = full_mix | vocals | bass | drums | other and an optional path-free sourceReference with a BandScope project id, fixed app-owned artifact name, admitted extension, bounded byte length and canonical lowercase SHA-256. No user filesystem path or revocable playback capability is durable project truth. Legacy/v1/v2 migration remains deterministic and never invents source evidence.

Persisted .bscope v3 input may contain a sourceReference, but renderer IPC may not author one. Native RED 37ea9a5a68a7c140d13689c552e61849ebe5a6c6 / fix 01c09cf96b3e3eb71e57ec1f2193283af76a4149 and renderer RED 4ea8c2a69088682da581c8ca125626d077f0044a / fix 0268568eb56e33f5dafb26c98b10a61eab9e86b0 keep that trust boundary fail closed.

Resource Admission handoff now present in ancestry

#866 production code owns bounded local-audio staging, app-owned source.<extension> publication, same-publication size+SHA-256 verification, LocalAudioPublicationIdentity, and native retention keyed by the BandScope-minted project id. #970 consumes that foundation rather than copying hashing or materialization logic.

The next causal Project Persistence slice is no longer ancestry adoption. It is a native save adapter with an explicit ephemeral project-aggregate selector: renderer may identify the already-minted project aggregate for a Save action, but may not submit a path, digest, artifact name, byte count, or sourceReference. Native code must look up the retained #866 identity for that project id and inject the typed v3 sourceReference inside the native boundary immediately before project_content_for_document. A global last selected project shortcut is not acceptable because multiple project aggregates can coexist.

Restart then resolves only that app-owned artifact, re-establishes regular/no-link containment and bounded size/SHA-256 plus applicable decode/admission, reconstructs a fresh bootstrap, and only then lets #1160 resolve persisted selectedPlaybackSource against fresh stem availability. A missing preferred stem fails closed to Full mix.

Existing Project Persistence controls

The branch retains staged/synchronized 5 MiB project publication and recovery, no-follow/final-component identity controls, Windows file-identity checks, replacement journals, migration fixtures, passive renderer record/accessor/trap admission, and Security Notes governance. Known residual work includes descriptor-bound parent authority, global startup recovery, autosave/known-good backup UX, downgrade/application-rollback policy, and exhaustive crash/kill/disk-full/power-loss fault injection.

Verification / merge gate

8893a925... is a new exact head. Fresh hosted workflows/check-runs must materialize and reach terminal success on this SHA before any GREEN claim. Keep Draft. Ready/merge additionally requires Windows/macOS persistence/build/security evidence, zero valid unresolved findings, qualifying independent non-author last-push approval, a satisfiable protected-context contract, the native source-reference save/reopen handoff where required for the advertised v3 source persistence, and an explicit downgrade/application-rollback decision. No self-approval, bypass, force-push, destructive rebase, gate weakening, finding suppression, or predecessor evidence transfer.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

프로젝트 저장 형식을 projectFormatVersion: 3으로 확장했습니다. 레거시·v1·v2 입력을 마이그레이션하고, 안정적인 재생 소스와 경로 없는 앱 소유 sourceReference를 검증합니다. 저장·로드는 안전한 파일 읽기, 원자적 게시, 저널 복구를 사용합니다.

Changes

프로젝트 형식과 IPC 계약

Layer / File(s)	Summary
v3 문서 계약과 마이그레이션 apps/desktop/core/src/lib.rs, apps/desktop/core/src/project_format.rs, apps/desktop/core/testdata/*, apps/desktop/core/tests/*	공유 페이로드를 타입화하고 projectFormatVersion: 3 문서를 추가했습니다. 레거시·v1·v2 입력을 순차 변환하며, 재생 소스와 sourceReference를 제한된 값으로 검증합니다.
렌더러 문서 검증과 저장·로드 연결 apps/desktop/src/lib/projectDocument.ts, apps/desktop/src/lib/analysis.ts, apps/desktop/src/lib/*.test.ts, apps/desktop/src-tauri/src/main.rs	plain record, own data property, 허용 필드와 SHA-256 형식을 검사합니다. saveProjectDocument와 loadProjectDocument를 Tauri 명령에 연결하고 기존 API를 호환 래퍼로 유지합니다.
계약 및 보안 추적 문서 ARCHITECTURE.md, CHANGELOG.md, docs/engineering/local-project-format.md, docs/traceability/*, scripts/checks/verify_security_notes.py	v3 형식, IPC 경계, 소스 참조 제약, 보안 노트 검증 대상을 문서화했습니다.

안전한 파일 영속성

Layer / File(s)	Summary
안전한 읽기와 게시 apps/desktop/src-tauri/src/project_persistence.rs, apps/desktop/src-tauri/tests/*	no-follow 파일 열기, 부모 경로 검사, 파일 신원 비교, 5 MiB 제한, 권한 처리, 원자적 교체와 no-replace 게시를 추가했습니다. 경쟁 생성, 심볼릭 링크, Windows 파일 신원, 디렉터리 동기화를 검증합니다.
게시 저널과 복구 apps/desktop/src-tauri/src/project_persistence.rs, apps/desktop/src-tauri/tests/project_persistence_recovery_cleanup.rs	prepared·published 저널을 기록합니다. 중단된 게시, case alias, 완료된 롤백 상태를 파일 신원과 경로 비교로 복구하거나 정리합니다.
Windows 회귀 검증 .github/workflows/project-persistence-windows.yml, services/analysis-engine/tests/test_project_persistence_workflow_policy.py	Windows recovery-cleanup 테스트를 실행하는 워크플로를 추가하고, 필수 계약 입력 경로가 워크플로에 포함되는지 검사합니다.

Estimated code review effort: 5 (Critical) | ~120 minutes

Merge Risk: 🟡 Moderate · up to 0e9e8

A concurrent replacement during an existing-project save can cause another file to be deleted during rollback. Resolve the identity-safe cleanup path before merge.

Sequence Diagram(s)

sequenceDiagram
  participant Renderer as Renderer
  participant Tauri as Tauri 명령
  participant Format as ProjectDocument 검증기
  participant Persistence as project_persistence
  participant FileSystem as 파일 시스템
  participant Journal as 게시 저널

  Renderer->>Tauri: save_project 또는 load_project 요청
  Tauri->>Format: 프로젝트 문서 검증 또는 파싱
  Format-->>Tauri: 검증된 ProjectDocument
  Tauri->>Persistence: 저장·로드 요청
  Persistence->>Journal: 기존 게시 상태 복구
  alt 저장
    Persistence->>FileSystem: stage 작성 및 동기화
    Persistence->>Journal: prepared 저널 기록
    Persistence->>FileSystem: 원자적 교체 또는 no-replace 게시
    Persistence->>Journal: published 저널 정리
  else 로드
    Persistence->>FileSystem: no-follow 방식으로 읽기
    FileSystem-->>Persistence: 제한된 UTF-8 내용
    Persistence->>Format: 버전 문서와 소스 참조 검증
    Format-->>Renderer: ProjectDocument 반환
  end

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.98% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 168 functions across 24 files. (10 skippe…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 저장 파일을 원자적으로 게시하기 전에 스테이징하는 핵심 변경을 정확히 설명합니다. PR의 주요 영속성 변경과 직접 관련되며 간결합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 77.98% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 168 functions across 24 files. (10 skipped: 10 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/project-save-atomic-publication-962

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@opencode-agent Please perform the required independent review on exact current head 53280f84d53bf7e434817c4bb777481e71135351 only. Apply current repository/central guidance and superpowers:using-superpowers; verify the bounded staged publication, no-follow handle acquisition on Linux/macOS, Windows reparse-point boundary, current live develop@749511c3ad4000090048718f685c6bee6b3d2c25, and the #962 scope exclusions. Do not transfer predecessor-head evidence. Post a formal current-head APPROVED or CHANGES_REQUESTED verdict; if changes are required, identify the first causal production boundary and smallest realistic regression. Do not mutate the branch as part of the independent review.