ContextualWisdomLab · seonghobae · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026 · Sep 6, 2026
@@ -0,0 +1,83 @@
+name: project-persistence-macos
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    paths:
+      - "apps/desktop/core/Cargo.toml"
+      - "apps/desktop/core/src/root.rs"
+      - "apps/desktop/core/src/lib.rs"
+      - "apps/desktop/core/src/crate_root.rs"
+      - "apps/desktop/core/src/project_format.rs"
+      - "apps/desktop/core/tests/project_persistence*.rs"
+      - "apps/desktop/core/tests/project_format*.rs"
+      - "apps/desktop/core/testdata/project-*.json"
+      - "apps/desktop/src-tauri/Cargo.toml"
+      - "apps/desktop/src-tauri/Cargo.lock"
+      - "apps/desktop/src-tauri/src/main.rs"
+      - "apps/desktop/src-tauri/src/project_load.rs"
+      - "apps/desktop/src-tauri/src/project_persistence.rs"
+      - "apps/desktop/src-tauri/src/project_persistence_engine.rs"
+      - "apps/desktop/src-tauri/src/project_root.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.case"
+      - "apps/desktop/src-tauri/tests/project_root_existing_authority.rs"
+      - "docs/traceability/project-persistence-native-ci.md"
+      - ".github/workflows/project-persistence-macos.yml"
+      - "services/analysis-engine/tests/test_project_persistence_workflow_policy.py"
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - "apps/desktop/core/Cargo.toml"
+      - "apps/desktop/core/src/root.rs"
+      - "apps/desktop/core/src/lib.rs"
+      - "apps/desktop/core/src/crate_root.rs"
+      - "apps/desktop/core/src/project_format.rs"
+      - "apps/desktop/core/tests/project_persistence*.rs"
+      - "apps/desktop/core/tests/project_format*.rs"
+      - "apps/desktop/core/testdata/project-*.json"
+      - "apps/desktop/src-tauri/Cargo.toml"
+      - "apps/desktop/src-tauri/Cargo.lock"
+      - "apps/desktop/src-tauri/src/main.rs"
+      - "apps/desktop/src-tauri/src/project_load.rs"
+      - "apps/desktop/src-tauri/src/project_persistence.rs"
+      - "apps/desktop/src-tauri/src/project_persistence_engine.rs"
+      - "apps/desktop/src-tauri/src/project_root.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.case"
+      - "apps/desktop/src-tauri/tests/project_root_existing_authority.rs"
+      - "docs/traceability/project-persistence-native-ci.md"
+      - ".github/workflows/project-persistence-macos.yml"
+      - "services/analysis-engine/tests/test_project_persistence_workflow_policy.py"
+
+permissions:
+  contents: read
+
+env:
+  GIT_CONFIG_COUNT: "1"
+  GIT_CONFIG_KEY_0: init.defaultBranch
+  GIT_CONFIG_VALUE_0: develop
+
+jobs:
+  macos-recovery-cleanup:
+    name: test / project-persistence / macos
+    runs-on: macos-15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Install Rust 1.97.1
+        run: rustup toolchain install 1.97.1 --profile minimal
+      - name: Prepare compile-only frontendDist fixture
+        run: |
+          mkdir -p apps/desktop/dist
+          printf '%s' '<!doctype html><title>BandScope test fixture</title>' > apps/desktop/dist/index.html
+      - name: Run macOS recovery-cleanup regression
+        run: cargo +1.97.1 test --manifest-path apps/desktop/src-tauri/Cargo.toml --no-default-features --features persistence_warning_gate --tests
@@ -0,0 +1,84 @@
+name: project-persistence-windows-native
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    paths:
+      - "apps/desktop/core/Cargo.toml"
+      - "apps/desktop/core/src/root.rs"
+      - "apps/desktop/core/src/lib.rs"
+      - "apps/desktop/core/src/crate_root.rs"
+      - "apps/desktop/core/src/project_format.rs"
+      - "apps/desktop/core/tests/project_persistence*.rs"
+      - "apps/desktop/core/tests/project_format*.rs"
+      - "apps/desktop/core/testdata/project-*.json"
+      - "apps/desktop/src-tauri/Cargo.toml"
+      - "apps/desktop/src-tauri/Cargo.lock"
+      - "apps/desktop/src-tauri/src/main.rs"
+      - "apps/desktop/src-tauri/src/project_load.rs"
+      - "apps/desktop/src-tauri/src/project_persistence.rs"
+      - "apps/desktop/src-tauri/src/project_persistence_engine.rs"
+      - "apps/desktop/src-tauri/src/project_root.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.case"
+      - "apps/desktop/src-tauri/tests/project_root_existing_authority.rs"
+      - "docs/traceability/project-persistence-native-ci.md"
+      - ".github/workflows/project-persistence-windows-native.yml"
+      - "services/analysis-engine/tests/test_project_persistence_workflow_policy.py"
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - "apps/desktop/core/Cargo.toml"
+      - "apps/desktop/core/src/root.rs"
+      - "apps/desktop/core/src/lib.rs"
+      - "apps/desktop/core/src/crate_root.rs"
+      - "apps/desktop/core/src/project_format.rs"
+      - "apps/desktop/core/tests/project_persistence*.rs"
+      - "apps/desktop/core/tests/project_format*.rs"
+      - "apps/desktop/core/testdata/project-*.json"
+      - "apps/desktop/src-tauri/Cargo.toml"
+      - "apps/desktop/src-tauri/Cargo.lock"
+      - "apps/desktop/src-tauri/src/main.rs"
+      - "apps/desktop/src-tauri/src/project_load.rs"
+      - "apps/desktop/src-tauri/src/project_persistence.rs"
+      - "apps/desktop/src-tauri/src/project_persistence_engine.rs"
+      - "apps/desktop/src-tauri/src/project_root.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.rs"
+      - "apps/desktop/src-tauri/tests/project_persistence*.case"
+      - "apps/desktop/src-tauri/tests/project_root_existing_authority.rs"
+      - "docs/traceability/project-persistence-native-ci.md"
+      - ".github/workflows/project-persistence-windows-native.yml"
+      - "services/analysis-engine/tests/test_project_persistence_workflow_policy.py"
+
+permissions:
+  contents: read
+
+env:
+  GIT_CONFIG_COUNT: "1"
+  GIT_CONFIG_KEY_0: init.defaultBranch
+  GIT_CONFIG_VALUE_0: develop
+
+jobs:
+  windows-recovery-cleanup:
+    name: test / project-persistence / windows
+    runs-on: windows-2025
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Install Rust 1.97.1
+        run: rustup toolchain install 1.97.1 --profile minimal
+      - name: Prepare compile-only frontendDist fixture
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force apps/desktop/dist | Out-Null
+          Set-Content -Path apps/desktop/dist/index.html -Value '<!doctype html><title>BandScope test fixture</title>' -NoNewline
+      - name: Run Windows recovery-cleanup regression
+        run: cargo +1.97.1 test --manifest-path apps/desktop/src-tauri/Cargo.toml --no-default-features --features persistence_warning_gate --tests
@@ -1,6 +1,6 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-09-06
 
 ## Brand source
 
@@ -111,8 +111,9 @@ Last updated: 2026-03-11
 - Shared contracts live in `packages/shared-types` so the UI can evolve without importing Python internals.
 - Shared contracts should ultimately model section, role, cue, confidence, and export artifacts explicitly enough that desktop UI and analysis outputs do not invent their own parallel schemas.
 - The current shared-types baseline includes a rehearsal-domain fixture that exercises section, role, cue, confidence, provenance, and export-summary fields in the desktop shell before the full analysis pipeline lands.
+- Current Project Persistence writes a strict `projectFormatVersion: 3` envelope around the validated rehearsal song, closed Active Player preference, and optional path-free app-owned audio `sourceReference`; legacy raw-song, v1, and v2 inputs remain readable through ordered migration. Resource Admission materializes the admitted local source as the fixed app-owned `source.<extension>` artifact, verifies publication byte identity, and retains a path-free native identity. Project Persistence injects that identity into Save and re-admits the exact size and SHA-256 on restart; production analysis revalidates the retained identity and decodes a verified private byte snapshot. Source/derived/decision/handoff expansion, autosave/recovery UX, and fresh Active Player audible authority remain follow-up work under #962/#961 rather than parallel stores.
 - Local analysis orchestration uses typed Tauri IPC commands and a Python subprocess over stdin/stdout rather than a loopback HTTP listener.
-- Local audio intake bootstraps a project by validating a user-selected file in Rust, creating app-owned temp/cache/project roots, and referencing the original source file rather than copying it in this phase.
+- Local audio intake validates an OS-selected source in Rust, enforces the canonical resource policy, publishes a no-clobber app-owned `source.<extension>` copy under the minted project aggregate, verifies the published bytes, and exposes only bounded bootstrap/path-free identity evidence to downstream Project Persistence and analysis consumers.
 - Those bootstrap roots should resolve from app-owned Tauri data/cache paths instead of the shared system temp namespace.
 - Product and UX decisions should prefer rehearsal-first simplicity while still maintaining high analytical accuracy.
 - Security decisions should prefer allowlisted narrow capabilities over generic convenience APIs.

@@ -7,6 +7,7 @@
 - Name tonight's first playable range on the ready rehearsal map and tell the player to check that span on their instrument before the section.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
+- Evolve local project writes to `projectFormatVersion: 3`: retain deterministic legacy/v1/v2 migration, persist the closed Active Player source preference, and optionally store a path-free app-owned audio `sourceReference` with bounded byte evidence and canonical SHA-256 content identity for process-restart re-admission.
 
 ### Changed
 
@@ -15,7 +16,27 @@
 
 ### Fixed
 
+- Preserve a reopened v3 project's native source selector and stored playback-source preference across an Open Project → Save Project round trip, so resaving cannot silently drop `sourceReference` or reset a non-default stem intent to Full mix.
+- Enforce one canonical local-audio resource policy across native local-file/YouTube bootstrap intake, the desktop bridge, Python request preflight, temporal decoding, and stem separation so oversized, overlong, malformed, wrong-rate, or non-finite input fails before bootstrap storage or expensive analysis/model work.
+- Preflight source-container duration, sample rate, and channel count from the already-open audio handle before temporal, stem, or bass-transcription decoders resample, downmix, or truncate it; successful metadata probes rewind the handle and malformed probes fail closed.
+- Bound the admitted canonical decoded mono buffer to 317,520,000 bytes as well as the existing 39,690,000-sample ceiling, so decoder dtype expansion cannot stay within the sample count while exceeding the explicit in-memory audio budget.
+- Fail closed on malformed known YouTube duration metadata before `download=True`; Boolean, non-numeric, non-finite, zero, negative, and non-canonical numeric-subtype duration evidence can no longer authorize a media download through Python numeric coercion or subclass semantics.
+- Align YouTube download admission with that same 100 MiB encoded-byte ceiling: abort in-flight with yt-dlp `max_filesize` and a progress hook, reject announced oversize before `download=True`, delete owned `.part` / `.ytdl` / `-Frag*` siblings from that import directory on abort, reject a completed path that resolves outside the current import cache before post-download validation, cleanup, or success, and delete owned post-download artifacts that still exceed the policy. A 60 MiB import that the old 50 MB check rejected is now accepted; a file one byte over 100 MiB is not.
+- Bound native stored-score PDF reads to the 25 MiB product limit before heap allocation and revalidate PDF magic on the same opened descriptor, preventing an attached score that later grows from bypassing the local resource boundary.
+- Treat every zero-element NumPy layout as empty chord input, including shapes whose first dimension is non-zero, before feature extraction.
 - Upgraded the local score PDF parser to `pdfjs-dist` 6.2.108, pinned Undici 7.29.0 across the workspace, and constrained PDF loading to copied in-memory bytes with a same-origin bundled worker and npm-generated lock provenance.
+- Stage and sync new project saves before non-clobbering publication, and enforce the existing 5 MiB project limit during the file read itself so a selected project cannot grow past a metadata preflight into an unbounded load allocation.
+- Reject directly selected project symlinks before reading so a chosen `.bscope` path cannot silently redirect the loader to different file content.
+- Reject a symlinked/reparse-point save parent before staging so a selected project path cannot redirect new project publication into a different directory.
+- Fail closed when a selected `.bscope` path changes file identity between preflight and handle acquisition; Windows opens reparse points without following them and compares native volume serial plus file-index identity across the acquisition boundary.
+- Refuse last-component symlink following during Linux/macOS project handle acquisition and make that acquisition non-blocking so a preflight-to-open path swap cannot redirect the loader or stall it on a special file.
+- Preserve first-save crash safety on filesystems without hard-link support by publishing the fully synced staging file with an OS-native atomic no-replace rename, so a crash cannot leave an empty reserved final path.
+- Reject a stale existing-project replacement when the selected target changes file identity while replacement bytes are staged; native exchange/backup publication restores the competing target instead of clobbering it.
+- Recover an interrupted existing-project replacement from a bounded, same-directory identity journal when the target is selected again, while leaving mismatched files untouched.
+- Keep renderer project admission passive and path-free: custom prototypes, enumeration/descriptor traps, accessors, runtime playback authorities, unknown fields, invalid app-owned source references, unsafe byte-size values, and missing/non-canonical SHA-256 source identity fail closed before persistence IPC.
+- Keep local Demucs loading offline and bounded by resolving a private snapshot copied from the verified cache descriptor through `LocalRepo`; reject missing, modified, empty, non-regular, over-128-MiB, or descriptor-size-racing checkpoint state before model deserialization so mutable cache replacement, post-preflight growth/shrink, and oversized local artifacts cannot alter or exhaust one analysis load.
+- Bound PyTorch 2.6+ weights-only checkpoint incompatibility at the admitted local-model boundary instead of leaking serialized class details or silently enabling legacy pickle loading; incompatible technical cache state now returns the existing local-model-unavailable diagnostic and remains a Distribution serialization/provenance decision.
+- Reject PyTorch runtime-environment widening at the local Demucs boundary: `TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD` cannot turn the upstream implicit checkpoint load back into unrestricted pickle deserialization, and `TORCH_DEVICE_BACKEND_AUTOLOAD=1` cannot auto-import out-of-tree backend extensions before model admission.
 
 ## [0.1.3] - 2026-04-29
 
@@ -75,4 +96,4 @@
 
 - `ChordsFeature` (코드 분석) 화면에서 각 파트(Role)의 `transpositionPlan`(이조/조옮김 계획)을 표시하는 기능을 추가했습니다.
 - `RangesFeature` (음역대 분석) 화면에서 겹침 경고(Overlap warning) 외에 해당 파트의 채보(Transcription) 가능 노드 수를 요약하여 보여주는 기능을 추가했습니다.
-- 신규 UI 요소에 대한 단위 테스트를 추가했습니다 (`apps/desktop/src/features/chords/index.test.tsx`, `apps/desktop/src/features/ranges/index.test.tsx`).
+- 신규 UI 요소에 대한 단위 테스트를 추가했습니다 (`apps/desktop/src/features/chords/index.test.tsx`, `apps/desktop/src/features/ranges/index.test.tsx`).
@@ -7,7 +7,11 @@ publish = false
 
 [lib]
 name = "bandscope_desktop_core"
-path = "src/lib.rs"
+path = "src/root.rs"
+
+[features]
+default = []
+persistence_warning_gate = []
 
 [lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage)'] }