From 1a4ee622537697d636e6528fe28ee1d8d619d5fa Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:11:42 +0900
Subject: [PATCH 01/14] docs(adr): define playable stem delivery boundary

---
 ...001-playable-stem-delivery-and-audition.md | 203 +++++++++++++
 docs/adr/README.md                            |  18 ++
 .../2026-09-04-playable-stem-audition.md      | 266 ++++++++++++++++++
 3 files changed, 487 insertions(+)
 create mode 100644 docs/adr/0001-playable-stem-delivery-and-audition.md
 create mode 100644 docs/adr/README.md
 create mode 100644 docs/superpowers/plans/2026-09-04-playable-stem-audition.md

diff --git a/docs/adr/0001-playable-stem-delivery-and-audition.md b/docs/adr/0001-playable-stem-delivery-and-audition.md
new file mode 100644
index 000000000..ac78a8d9f
--- /dev/null
+++ b/docs/adr/0001-playable-stem-delivery-and-audition.md
@@ -0,0 +1,203 @@
+# ADR-0001: Deliver playable stems through revocable native authority
+
+- **Status:** Proposed
+- **Date:** 2026-09-04
+- **Decision owners:** Source Separation, Active Player, Desktop Security
+- **Related work:** Issue #961, PR #971, Issue #770, PR #828, Issue #781, PR #866
+- **Supersedes:** None
+
+## Context
+
+BandScope already separates admitted local audio into the canonical Demucs sources `vocals`, `bass`, `drums`, and `other`. The analysis pipeline persists NumPy feature arrays for internal reuse, but those arrays are not a renderer-safe media contract. The canonical Active Player in PR #971 can play the admitted full mix through the revocable `bandscope-playback` protocol, yet its stem actions remain unavailable because no real stem source reaches that protocol.
+
+The buyer-visible gap is therefore not another source-separation model. It is a missing product boundary:
+
+```text
+successful local separation
+→ durable-enough session artifact
+→ native validation and authority registration
+→ opaque renderer handle
+→ the existing Active Player transport
+→ audible, truthful stem audition
+```
+
+The first implementation must not imply that `other` is a separately identified guitar or keyboard. It must not claim perceptual separation quality merely because an artifact can be played. It must also avoid creating a second transport store beside PR #971.
+
+## Decision
+
+### 1. Materialize a versioned playable-stem artifact set
+
+After successful separation, the analysis engine will materialize the four aligned mono sources as PCM16 WAV files under the current project's app-owned temporary workspace. A single shared gain is applied to the whole set when needed to prevent clipping while preserving inter-stem level relationships.
+
+The internal native manifest is versioned and contains, at minimum:
+
+```text
+artifact_set_id
+format_version
+sample_rate
+channel_count
+sample_count
+duration_seconds
+applied_gain
+stem_artifacts[]
+  artifact_id
+  stem_kind
+  native_file_path
+  file_size_bytes
+  content_hash_sha256
+  media_type
+```
+
+The engine may disclose the native path only to the trusted Tauri process over the existing bounded JSONL subprocess boundary. It must never enter renderer state, UI copy, logs, exported handoffs, or persisted project JSON.
+
+### 2. Extend the existing revocable playback authority
+
+The Tauri layer will validate each artifact against the current project's app-owned root before registering it. Registration requires:
+
+- one artifact for each canonical stem and no unknown stem;
+- a regular, non-symlink WAV file under the expected project artifact directory;
+- bounded nonzero size;
+- manifest/file identity agreement;
+- common sample rate, sample count, channel count, and duration;
+- no duplicate artifact identifier or stem kind.
+
+The renderer receives only a strict opaque authority such as:
+
+```text
+bandscope-project://project-…/stem-vocals
+```
+
+The existing `bandscope-playback` protocol remains the only media-serving boundary. Source replacement or project replacement revokes both the full mix and every stem authority together.
+
+### 3. Ship single-source audition before multitrack mixing
+
+The first buyer-visible increment adds a source selector to the existing Active Player:
+
+```text
+Full mix | Vocals | Bass | Drums | Other instruments
+```
+
+Only sources present in a validated artifact set are enabled. Choosing a source re-arms the current loop on the same transport state machine. The selected source can then use the existing play, pause, stop, seek, count-in, playback-rate, loop-boundary, cue-navigation, and keyboard behavior.
+
+This is genuine isolated-source audition: selecting one stem makes that one generated source audible. It is not yet a multitrack gain mixer. The UI will not show per-stem volume sliders, simultaneous mute combinations, or a synchronization claim until the later multitrack acceptance work is complete.
+
+### 4. Add a synchronized mixer only after measurable timing evidence
+
+A later successor may use one `AudioContext`, one authoritative clock, and per-source gain nodes to support simultaneous stem mixing. It must first prove:
+
+- common decoded duration and sample alignment;
+- bounded start and loop-restart skew;
+- bounded accumulated drift over a long run;
+- deterministic solo, mute, and gain transitions;
+- safe device loss, suspension, cancellation, and project close;
+- no unbounded decode or full-track duplication beyond the registered resource budget.
+
+Multiple independently controlled `HTMLAudioElement` instances are not an acceptable synchronization architecture.
+
+### 5. Keep capability evidence separate from quality evidence
+
+Artifact creation proves that an output exists and can be played. It does not prove perceptual quality, instrument identity beyond the canonical model outputs, or genre-wide accuracy. Source-separation accuracy and rights-cleared listening evidence remain owned by Issue #770 and PR #828. Resource admission and decode bounds remain owned by Issue #781 and its canonical PR #866.
+
+## Domain ownership
+
+| Responsibility | Owner |
+| --- | --- |
+| Decode and separation computation | `services/analysis-engine` Source Separation |
+| PCM artifact materialization | `services/analysis-engine` Playback Artifact adapter |
+| Native path, identity, revocation, and byte-range serving | `apps/desktop/src-tauri` Playback Authority |
+| Public status and opaque source contracts | `packages/shared-types` |
+| Loop, count-in, seek, rate, and source selection | `apps/desktop` Active Player |
+| MIR accuracy and claim boundaries | Issue #770 / PR #828 |
+| Resource admission and decode policy | Issue #781 / PR #866 |
+| Reopened-project persistence and cleanup recovery | Issue #962 |
+
+The playback artifact adapter does not become a second source-separation owner, and the renderer does not gain filesystem authority.
+
+## Security and privacy
+
+### Attack surface
+
+- model-produced floating-point arrays;
+- app-owned cache and temporary directories;
+- Python-to-Rust manifest fields;
+- custom-protocol paths and byte-range requests;
+- renderer source-selection events.
+
+### Trust boundaries
+
+- analysis arrays are untrusted numeric output until shape, finiteness, cardinality, and alignment validation succeeds;
+- native paths are untrusted subprocess output until Tauri validates app-owned containment and file identity;
+- renderer handles are identifiers only and never paths;
+- selecting a source grants no new filesystem, network, export, or generic execution capability.
+
+### Safe failure
+
+Malformed, incomplete, stale, replaced, oversized, unaligned, or non-finite stem sets produce no renderer authority. The full mix remains usable when it is still valid; the UI states that stems are unavailable rather than fabricating successful separation.
+
+### Data handling
+
+Separated audio is sensitive derived media. It remains local, is excluded from logs and ordinary exports, and is scoped to an app-owned project workspace. Session revocation is mandatory in this slice. Durable cleanup, recovery after abnormal termination, and reopened-project retention policy remain explicit Issue #962 follow-up work rather than an implied guarantee.
+
+## Alternatives considered
+
+### A. Put NumPy arrays directly into the renderer
+
+Rejected. `.npz` is an analysis cache format, not a bounded browser media contract. This would expand IPC payloads, expose derived audio to renderer memory, and duplicate decode logic.
+
+### B. Create four independent media elements and keep them aligned with timers
+
+Rejected. Independent media clocks and asynchronous seeks create avoidable drift and race conditions. It would also create a second transport authority beside PR #971.
+
+### C. Wait until the complete multitrack mixer is finished
+
+Rejected. A single-source audition slice closes a real buyer gap, reuses the current transport, and establishes the security contract required by the later mixer without advertising unfinished gain controls.
+
+### D. Export stem files and require users to open another player
+
+Rejected. It breaks the rehearsal loop, exposes filesystem concerns to the user, and does not connect isolated listening to BandScope's sections, cues, and role guidance.
+
+### E. Label `other` as guitar or keys based on the selected role
+
+Rejected. The current canonical model does not establish that identity. The shipped label is `Other instruments` until independently validated model capability says otherwise.
+
+## Consequences
+
+### Positive
+
+- Real separation becomes an audible product capability instead of an internal analysis detail.
+- The renderer continues to receive opaque, revocable authority rather than native paths.
+- The existing Active Player remains the single transport state machine.
+- The design creates a measurable path to a later synchronized mixer without prematurely shipping fake controls.
+- Cache hits and fresh separation can converge on the same versioned artifact contract.
+
+### Costs and constraints
+
+- Derived WAV files consume temporary disk space and require explicit lifecycle management.
+- The Python/Rust status boundary needs a trusted-internal manifest and a sanitized renderer projection.
+- The first slice auditions one source at a time; it does not satisfy the complete multitrack mixing expectation.
+- Changes touch Python, Rust, TypeScript, Tauri permissions, CSP/protocol tests, UI, and documentation, so cross-platform exact-head evidence is mandatory.
+
+## Acceptance criteria for `Accepted`
+
+This ADR remains `Proposed` until one unchanged exact head proves all of the following:
+
+1. successful local separation produces exactly four aligned, finite, playable WAV artifacts;
+2. a feature-cache hit can recreate or reuse the same artifact contract without rerunning the model;
+3. Tauri rejects paths outside the current app-owned project root, symlinks, replacements, stale projects, unknown stems, duplicates, and metadata mismatch;
+4. renderer-visible status contains no native path;
+5. the source selector exposes only `Full mix`, `Vocals`, `Bass`, `Drums`, and `Other instruments` when actually available;
+6. selecting a stem produces observable audio playback through the same section loop and transport controls as the full mix;
+7. source replacement, app project replacement, playback error, and project close fail safely;
+8. keyboard-only and screen-reader journeys can identify and select the active source;
+9. normal, loading, unavailable, error, and partial/fail-closed states have executable component evidence;
+10. macOS and Windows production desktop tests use rights-cleared audio and confirm the audible source change;
+11. repository-owned production statement and branch coverage and public documentation remain 100%;
+12. current-head CI, security, SAST, dependency, SBOM, package, release, review-thread, and independent-approval gates pass without bypass.
+
+## References
+
+Défossez, A. (2021). Hybrid spectrogram and waveform source separation. *Proceedings of the ISMIR 2021 Workshop on Music Source Separation*.
+
+WHATWG. (2026). *HTML Standard: Media elements*. https://html.spec.whatwg.org/multipage/media.html
+
+World Wide Web Consortium. (2024). *Web Audio API 1.1* (First Public Working Draft). https://www.w3.org/TR/webaudio-1.1/
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 000000000..8e1f642b9
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,18 @@
+# Architecture decision records
+
+BandScope records durable architecture decisions in this directory.
+
+## Status lifecycle
+
+- `Proposed`: the decision is under implementation or still lacks exact-head production evidence.
+- `Accepted`: the implementation, contracts, tests, security review, and production evidence all match the decision.
+- `Superseded`: a later ADR replaces the decision without rewriting its history.
+- `Rejected`: the decision was considered and deliberately not adopted.
+
+A pull request, prototype, Storybook story, or passing unit test does not by itself make an ADR `Accepted`. The owning PR must satisfy the repository's protected current-head merge gate and preserve the stated decision in the shipped product.
+
+## Index
+
+| ADR | Status | Decision |
+| --- | --- | --- |
+| [0001](0001-playable-stem-delivery-and-audition.md) | Proposed | Deliver locally generated stems through revocable native authority and add single-source audition before a synchronized multitrack mixer. |
diff --git a/docs/superpowers/plans/2026-09-04-playable-stem-audition.md b/docs/superpowers/plans/2026-09-04-playable-stem-audition.md
new file mode 100644
index 000000000..4bb3b1ab1
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-04-playable-stem-audition.md
@@ -0,0 +1,266 @@
+# Playable stem audition implementation plan
+
+> **Execution rule:** Apply test-driven development. Keep this work stacked on canonical Active Player PR #971. Do not create a second transport store, duplicate Issue #781 resource policy, or claim MIR quality from transport tests.
+
+**Goal:** Turn BandScope's already-generated four source-separation outputs into revocable, renderer-safe media sources that the existing Active Player can actually audition one at a time.
+
+**Architecture:** The analysis engine materializes an aligned PCM16 WAV artifact set. Tauri validates and registers the native files under the current project, rewrites the internal manifest to opaque `bandscope-project://…/stem-*` authorities, and emits only that sanitized projection. The React Active Player keeps one media element and one transport state machine while switching between the full mix and one validated stem. A synchronized Web Audio gain mixer is a later successor after timing evidence.
+
+**Stack:** Python 3.12+ (`numpy`, standard-library `wave`), Rust 1.97.1, Tauri 2, React 19, TypeScript, Vitest, pytest, cargo test.
+
+**Base identity at plan creation:** `feat/rehearsal-player-first-section-loop@803019e092376383500c0a4f8c2f52c68eb7232f`.
+
+---
+
+## Task 1: Establish the decision and traceability baseline
+
+**Files**
+
+- Create: `docs/adr/README.md`
+- Create: `docs/adr/0001-playable-stem-delivery-and-audition.md`
+- Create: `docs/superpowers/plans/2026-09-04-playable-stem-audition.md`
+
+**Steps**
+
+1. Record ADR-0001 as `Proposed`.
+2. Bind the work to #961/#971 while preserving #770/#828, #781/#866, and #962 ownership.
+3. Record the rejected independent-media-clock design and the later synchronized mixer gate.
+4. Commit the documentation before implementation so reviewers can reconstruct the intended boundary.
+
+## Task 2: Materialize aligned native WAV artifacts
+
+**Files**
+
+- Create: `services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py`
+- Create: `services/analysis-engine/tests/test_playback_artifacts.py`
+- Modify later: `services/analysis-engine/src/bandscope_analysis/separation/__init__.py`
+
+**RED tests**
+
+- exact canonical stem set required;
+- nonempty, one-dimensional, finite arrays required;
+- every stem has the same sample count;
+- sample rate is a bounded positive integer and not Boolean;
+- invalid artifact-set identifiers fail closed;
+- symlink or non-directory artifact roots fail closed;
+- one shared gain prevents clipping without per-stem normalization;
+- generated files are mono PCM16 WAV with exact sample count/rate;
+- hash and byte-size metadata match on-disk bytes;
+- rerunning the same artifact set is deterministic and leaves no temporary files;
+- failed publication removes partial temporary files.
+
+**GREEN implementation**
+
+1. Validate all arrays before creating output.
+2. Derive one shared gain from the set-wide peak.
+3. Write each file to a same-directory temporary file.
+4. flush/fsync, atomically replace the deterministic target, then hash the published bytes.
+5. Return a JSON-serializable internal native manifest.
+6. Run focused pytest with branch coverage, Ruff, and mypy.
+
+## Task 3: Attach artifact production to fresh and cached analysis
+
+**Files**
+
+- Modify: `services/analysis-engine/src/bandscope_analysis/api.py`
+- Modify: `services/analysis-engine/tests/test_api.py`
+- Modify: `services/analysis-engine/tests/test_branch_coverage_contract.py`
+
+**RED tests**
+
+- successful separation emits a native artifact set in the terminal status;
+- cached features emit the same artifact contract without invoking Demucs;
+- a final-result cache hit attempts bounded feature reuse and omits stems honestly when no feature set exists;
+- fallback or separation failure never emits a success-shaped stem set;
+- native paths do not enter cached rehearsal-song JSON;
+- artifact generation failure keeps the analysis result usable but reports stems unavailable.
+
+**GREEN implementation**
+
+1. Derive a deterministic artifact-set identifier from the versioned source/analysis identity.
+2. Materialize artifacts after fresh separation and after feature-cache load.
+3. Add an internal optional native artifact field to the analysis JSONL status.
+4. Keep the final `RehearsalSong` contract free of filesystem metadata.
+5. Preserve #781 resource bounds; do not add a second decoder.
+
+## Task 4: Define and validate native/public contracts
+
+**Files**
+
+- Modify: `apps/desktop/core/src/lib.rs`
+- Modify: `apps/desktop/core/tests/analysis_job_status.rs` or the current owning status-contract test
+- Modify: `packages/shared-types/src/index.ts`
+- Modify: `packages/shared-types/test/index.test.ts`
+
+**RED tests**
+
+- native manifest denies unknown fields and malformed values;
+- public artifact source accepts only the four canonical stem kinds and opaque BandScope authorities;
+- native path is rejected by the public parser;
+- unknown stems, duplicates, misalignment, nonfinite duration, zero size, bad hashes, and invalid media type fail closed;
+- optional absence remains compatible with old results.
+
+**GREEN implementation**
+
+1. Add a trusted-internal native status shape for subprocess ingestion.
+2. Add a separate renderer-safe projection shape.
+3. Use semantic multiword names and translate only at the IPC boundary.
+4. Keep all existing analysis-job fields backward compatible.
+
+## Task 5: Register stems with revocable Tauri playback authority
+
+**Files**
+
+- Modify: `apps/desktop/src-tauri/src/playback_protocol.rs`
+- Modify: `apps/desktop/src-tauri/src/main.rs`
+- Modify: `apps/desktop/src-tauri/build.rs` only if a command surface changes
+- Modify: `apps/desktop/src-tauri/tauri.conf.json` only if CSP needs an explicit path update
+- Modify: existing Rust protocol and native integration tests
+
+**RED tests**
+
+- mix compatibility URI remains valid;
+- exact stem URIs resolve only for the active project;
+- old project and old artifact-set handles are revoked;
+- only GET/HEAD and one bounded byte range are accepted;
+- native artifact path must be under the current project temp artifact directory;
+- symlinks, file replacement, wrong size/hash/type, duplicate kind, unknown kind, and cross-project registration fail;
+- a status emitted to the renderer contains opaque authorities and no native path;
+- a malformed internal manifest cannot partially register a set.
+
+**GREEN implementation**
+
+1. Refactor the authority from one source into one current project containing a full mix plus an atomic stem-source map.
+2. Preserve `/project-id` for the full mix and add strict `/project-id/stem-*` paths.
+3. Register the complete validated set in one operation.
+4. Rewrite or remove native fields before status storage and event emission.
+5. Hold revocation protection through each bounded serve operation.
+
+## Task 6: Connect the sanitized status to the mounted workspace
+
+**Files**
+
+- Modify: `apps/desktop/src/lib/analysis.ts`
+- Modify: `apps/desktop/src/App.tsx`
+- Modify: `apps/desktop/src/App.test.tsx`
+- Modify: `apps/desktop/src/features/workspace/Workspace.tsx`
+- Modify: `apps/desktop/src/features/workspace/Workspace.test.tsx`
+
+**RED tests**
+
+- current job and current project identity must match before stems become available;
+- stale job completion cannot attach stems to a replacement song;
+- no stem set leaves the existing unavailable controls enabled;
+- `other` is presented as `Other instruments`, not inferred guitar or keys;
+- renderer state and error copy contain no path.
+
+**GREEN implementation**
+
+1. Parse the public artifact set on every bridge/event boundary.
+2. Store it beside the current successful job, not inside the song.
+3. Clear it on source replacement, job replacement, failed analysis, and project load without matching authority.
+4. Pass the sanitized set into the Active Player.
+
+## Task 7: Add real single-source audition to Active Player
+
+**Files**
+
+- Modify: `apps/desktop/src/features/workspace/RehearsalPlayer.tsx`
+- Modify: `apps/desktop/src/features/workspace/RehearsalPlayer.test.tsx`
+- Create if useful: `apps/desktop/src/features/workspace/rehearsalPlaybackSource.ts`
+- Create if useful: `apps/desktop/src/features/workspace/rehearsalPlaybackSource.test.ts`
+
+**RED tests**
+
+- `Full mix` remains the default source;
+- only validated available stems render as source choices;
+- choosing a stem changes the actual `<audio>` source;
+- changing source during count-in/looping stops or re-arms deterministically and never leaves two sources playing;
+- current section, loop boundaries, rate, and role filter remain coherent;
+- a failed stem load returns to a truthful unavailable/error state without silently reporting playback;
+- keyboard and assistive technology expose source name, selected state, and availability.
+
+**GREEN implementation**
+
+1. Add one source-selection value to the existing player state boundary.
+2. Keep one media element and the existing transport reducer.
+3. On source change, invalidate stale play promises, stop playback, load metadata, revalidate the selected loop, and re-arm it.
+4. Replace the disabled `Play stem`/`Solo or mute others` affordance with the real source selector; do not add gain sliders.
+5. Keep `Other instruments` explicit and localized.
+
+## Task 8: Localize and isolate component states
+
+**Files**
+
+- Modify: `apps/desktop/src/i18n/en/common.json`
+- Modify: `apps/desktop/src/i18n/ko/common.json`
+- Modify: all other supported locale resources or keep the feature behind a locale-completeness gate
+- Modify/Create: Active Player Storybook stories in the current Storybook owner
+- Modify: `docs/design-system/component-contract.md`
+
+**States**
+
+- full mix only;
+- four stems ready;
+- separation unavailable;
+- partial manifest rejected;
+- stem media load error;
+- source switch while armed;
+- source switch while looping;
+- narrow viewport and text expansion;
+- keyboard-only and reduced motion.
+
+Do not invent a Figma node identifier. Record the canonical Figma file and mark the node as pending live verification until an actual node exists.
+
+## Task 9: Production QA and evidence
+
+**Files**
+
+- Modify: `ARCHITECTURE.md`
+- Modify: `AGENTS.md`
+- Modify: `CLAUDE.md`
+- Modify: `CHANGELOG.md`
+- Create: `docs/doctoring/playable-stem-audition.md`
+- Coordinate, do not concurrently edit: `docs/product-technical-gap-baseline.md` owner PR
+
+**Verification commands**
+
+```bash
+uv run --project services/analysis-engine pytest \
+  services/analysis-engine/tests/test_playback_artifacts.py \
+  services/analysis-engine/tests/test_api.py \
+  --cov=services/analysis-engine/src/bandscope_analysis \
+  --cov-branch --cov-report=term-missing --cov-fail-under=100
+
+uv run --project services/analysis-engine ruff check services/analysis-engine/src services/analysis-engine/tests
+uv run --project services/analysis-engine ruff format --check services/analysis-engine/src services/analysis-engine/tests
+uv run --project services/analysis-engine mypy services/analysis-engine/src
+
+npm run lint --workspace @bandscope/shared-types
+npm run typecheck --workspace @bandscope/shared-types
+npm run test --workspace @bandscope/shared-types
+npm run lint --workspace @bandscope/desktop
+npm run typecheck --workspace @bandscope/desktop
+npm run test --workspace @bandscope/desktop
+
+cargo +1.97.1 fmt --manifest-path apps/desktop/core/Cargo.toml --check
+cargo +1.97.1 test --manifest-path apps/desktop/core/Cargo.toml --locked
+cargo +1.97.1 test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked
+
+./scripts/harness/quickcheck.sh
+```
+
+**Rendered QA flow**
+
+```text
+local or authorized YouTube source
+→ successful analysis
+→ four real stem sources become available
+→ select Bass
+→ start the current section loop
+→ hear the isolated bass source
+→ switch to Full mix
+→ same section remains selected and only the full mix is audible
+```
+
+Validate the production Tauri build on macOS and Windows with rights-cleared fixtures. Browser-only mocks and Storybook do not prove audio behavior. Record source-selection state, native protocol requests, audio output observation, console health, screenshots, keyboard flow, and failure cases. Update ADR-0001 to `Accepted` only after the unchanged exact head satisfies every protected gate and the production evidence above.

From b743f498f9683f4295dda6e1ee8fb9d62cc14bf2 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:13:47 +0900
Subject: [PATCH 02/14] test(separation): require playable stem artifact
 materialization

---
 .../tests/test_playback_artifacts.py          | 325 ++++++++++++++++++
 1 file changed, 325 insertions(+)
 create mode 100644 services/analysis-engine/tests/test_playback_artifacts.py

diff --git a/services/analysis-engine/tests/test_playback_artifacts.py b/services/analysis-engine/tests/test_playback_artifacts.py
new file mode 100644
index 000000000..0c9a37066
--- /dev/null
+++ b/services/analysis-engine/tests/test_playback_artifacts.py
@@ -0,0 +1,325 @@
+"""Behavioral contract for local playable-stem artifact materialization."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import wave
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from bandscope_analysis.separation.playback_artifacts import (
+    CANONICAL_PLAYBACK_STEM_KINDS,
+    materialize_playable_stem_artifact_set,
+)
+
+
+ARTIFACT_SET_ID = "a" * 64
+SAMPLE_RATE_HZ = 8_000
+
+
+def sample_stem_arrays(*, sample_peak: float = 0.5) -> dict[str, np.ndarray]:
+    """Return four aligned floating-point sources with distinguishable levels."""
+    sample_axis = np.linspace(-sample_peak, sample_peak, 16, dtype=np.float32)
+    return {
+        "vocals": sample_axis,
+        "bass": sample_axis * np.float32(0.5),
+        "drums": sample_axis * np.float32(0.25),
+        "other": sample_axis * np.float32(0.125),
+    }
+
+
+def read_wave_samples(file_path: Path) -> tuple[int, int, int, np.ndarray]:
+    """Read the generated mono PCM16 file for exact contract assertions."""
+    with wave.open(str(file_path), "rb") as wave_reader:
+        channel_count = wave_reader.getnchannels()
+        sample_width_bytes = wave_reader.getsampwidth()
+        sample_rate_hz = wave_reader.getframerate()
+        frame_bytes = wave_reader.readframes(wave_reader.getnframes())
+    sample_values = np.frombuffer(frame_bytes, dtype="<i2")
+    return channel_count, sample_width_bytes, sample_rate_hz, sample_values
+
+
+def test_materializer_writes_exact_aligned_pcm16_artifact_set(tmp_path: Path) -> None:
+    """All four canonical sources become aligned mono PCM16 WAV artifacts."""
+    artifact_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+
+    assert artifact_result["artifactSetId"] == ARTIFACT_SET_ID
+    assert artifact_result["formatVersion"] == 1
+    assert artifact_result["sampleRate"] == SAMPLE_RATE_HZ
+    assert artifact_result["channelCount"] == 1
+    assert artifact_result["sampleCount"] == 16
+    assert artifact_result["durationSeconds"] == pytest.approx(16 / SAMPLE_RATE_HZ)
+    assert artifact_result["appliedGain"] == pytest.approx(1.0)
+    assert [
+        stem_artifact["stemKind"] for stem_artifact in artifact_result["stemArtifacts"]
+    ] == list(CANONICAL_PLAYBACK_STEM_KINDS)
+
+    for stem_artifact in artifact_result["stemArtifacts"]:
+        artifact_path = Path(stem_artifact["nativeFilePath"])
+        assert artifact_path.is_relative_to(tmp_path.resolve())
+        assert artifact_path.name == f'{stem_artifact["stemKind"]}.wav'
+        assert stem_artifact["artifactId"] == f'stem-{stem_artifact["stemKind"]}'
+        assert stem_artifact["mediaType"] == "audio/wav"
+        assert stem_artifact["fileSizeBytes"] == artifact_path.stat().st_size
+        assert stem_artifact["contentHashSha256"] == hashlib.sha256(
+            artifact_path.read_bytes()
+        ).hexdigest()
+        assert stem_artifact["sampleRate"] == SAMPLE_RATE_HZ
+        assert stem_artifact["channelCount"] == 1
+        assert stem_artifact["sampleCount"] == 16
+        assert stem_artifact["durationSeconds"] == pytest.approx(16 / SAMPLE_RATE_HZ)
+        channel_count, sample_width_bytes, sample_rate_hz, sample_values = read_wave_samples(
+            artifact_path
+        )
+        assert channel_count == 1
+        assert sample_width_bytes == 2
+        assert sample_rate_hz == SAMPLE_RATE_HZ
+        assert sample_values.size == 16
+
+
+def test_materializer_uses_one_set_wide_gain_without_per_stem_normalization(
+    tmp_path: Path,
+) -> None:
+    """Peak protection preserves the relative amplitude between different stems."""
+    stem_arrays = sample_stem_arrays(sample_peak=2.0)
+    artifact_result = materialize_playable_stem_artifact_set(
+        stem_arrays=stem_arrays,
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+
+    assert 0.0 < artifact_result["appliedGain"] < 0.5
+    stem_artifacts = {
+        stem_artifact["stemKind"]: stem_artifact
+        for stem_artifact in artifact_result["stemArtifacts"]
+    }
+    _, _, _, vocal_samples = read_wave_samples(
+        Path(stem_artifacts["vocals"]["nativeFilePath"])
+    )
+    _, _, _, bass_samples = read_wave_samples(
+        Path(stem_artifacts["bass"]["nativeFilePath"])
+    )
+    vocal_peak = int(np.max(np.abs(vocal_samples.astype(np.int32))))
+    bass_peak = int(np.max(np.abs(bass_samples.astype(np.int32))))
+    assert vocal_peak <= 32_767
+    assert bass_peak / vocal_peak == pytest.approx(0.5, abs=2 / 32_767)
+
+
+@pytest.mark.parametrize(
+    ("invalid_sample_rate", "expected_message"),
+    [
+        (True, "sample rate"),
+        (7_999, "sample rate"),
+        (192_001, "sample rate"),
+        (8_000.0, "sample rate"),
+    ],
+)
+def test_materializer_rejects_invalid_sample_rate(
+    tmp_path: Path,
+    invalid_sample_rate: object,
+    expected_message: str,
+) -> None:
+    """Only bounded integer sample rates may become media metadata."""
+    with pytest.raises(ValueError, match=expected_message):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=invalid_sample_rate,  # type: ignore[arg-type]
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+@pytest.mark.parametrize(
+    "invalid_artifact_set_id",
+    ["", "A" * 64, "a" * 63, "a" * 65, "../" + "a" * 61],
+)
+def test_materializer_rejects_invalid_artifact_set_identity(
+    tmp_path: Path,
+    invalid_artifact_set_id: str,
+) -> None:
+    """Artifact directories are selected only by a lowercase SHA-256 identity."""
+    with pytest.raises(ValueError, match="artifact set"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=invalid_artifact_set_id,
+        )
+
+
+@pytest.mark.parametrize("missing_stem_kind", CANONICAL_PLAYBACK_STEM_KINDS)
+def test_materializer_rejects_missing_canonical_stem(
+    tmp_path: Path,
+    missing_stem_kind: str,
+) -> None:
+    """A partial separation result cannot become a success-shaped artifact set."""
+    stem_arrays = sample_stem_arrays()
+    del stem_arrays[missing_stem_kind]
+    with pytest.raises(ValueError, match="canonical stems"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=stem_arrays,
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_rejects_unknown_stem(tmp_path: Path) -> None:
+    """Model-specific unknown sources cannot silently expand the public contract."""
+    stem_arrays = sample_stem_arrays()
+    stem_arrays["guitar"] = np.zeros(16, dtype=np.float32)
+    with pytest.raises(ValueError, match="canonical stems"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=stem_arrays,
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+@pytest.mark.parametrize(
+    ("invalid_stem_array", "expected_message"),
+    [
+        (np.zeros((2, 8), dtype=np.float32), "one-dimensional"),
+        (np.array([], dtype=np.float32), "non-empty"),
+        (np.arange(16, dtype=np.int16), "floating-point"),
+        (np.array([0.0, np.nan] + [0.0] * 14, dtype=np.float32), "finite"),
+        (np.array([0.0, np.inf] + [0.0] * 14, dtype=np.float32), "finite"),
+    ],
+)
+def test_materializer_rejects_malformed_stem_arrays(
+    tmp_path: Path,
+    invalid_stem_array: np.ndarray,
+    expected_message: str,
+) -> None:
+    """Malformed model output never reaches WAV encoding or native registration."""
+    stem_arrays = sample_stem_arrays()
+    stem_arrays["vocals"] = invalid_stem_array
+    with pytest.raises(ValueError, match=expected_message):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=stem_arrays,
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_rejects_unaligned_stem_lengths(tmp_path: Path) -> None:
+    """Sources with unequal sample counts cannot be represented as synchronized stems."""
+    stem_arrays = sample_stem_arrays()
+    stem_arrays["drums"] = np.zeros(15, dtype=np.float32)
+    with pytest.raises(ValueError, match="aligned"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=stem_arrays,
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_rejects_non_directory_artifact_root(tmp_path: Path) -> None:
+    """A caller cannot redirect artifact publication through a regular file."""
+    artifact_root = tmp_path / "artifact-root"
+    artifact_root.write_text("not a directory", encoding="utf-8")
+    with pytest.raises(ValueError, match="artifact root"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=artifact_root,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symbolic links are unavailable")
+def test_materializer_rejects_symbolic_link_artifact_root(tmp_path: Path) -> None:
+    """An app-owned artifact root may not be redirected through a symbolic link."""
+    actual_root = tmp_path / "actual-root"
+    actual_root.mkdir()
+    artifact_root = tmp_path / "artifact-root"
+    artifact_root.symlink_to(actual_root, target_is_directory=True)
+    with pytest.raises(ValueError, match="artifact root"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=artifact_root,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_reuses_identical_existing_artifact_set(tmp_path: Path) -> None:
+    """Idempotent regeneration reuses identical bytes and leaves no staging directory."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    second_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+
+    assert second_result == first_result
+    version_directory = tmp_path / "playable-stems-v1"
+    assert [child_path.name for child_path in version_directory.iterdir()] == [ARTIFACT_SET_ID]
+
+
+def test_materializer_rejects_existing_identity_with_different_content(tmp_path: Path) -> None:
+    """An artifact-set identity collision never overwrites the previously published bytes."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    vocal_path = Path(first_result["stemArtifacts"][0]["nativeFilePath"])
+    vocal_path.write_bytes(b"changed")
+
+    with pytest.raises(ValueError, match="identity collision"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+    assert vocal_path.read_bytes() == b"changed"
+    version_directory = tmp_path / "playable-stems-v1"
+    assert [child_path.name for child_path in version_directory.iterdir()] == [ARTIFACT_SET_ID]
+
+
+def test_materializer_removes_staging_directory_when_publication_fails(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A failed atomic directory publication leaves neither partial targets nor temp data."""
+    original_replace = os.replace
+
+    def failing_directory_replace(source_path: str | bytes, target_path: str | bytes) -> None:
+        """Fail only the final artifact-directory publication operation."""
+        source_candidate = Path(source_path)
+        if source_candidate.is_dir():
+            raise OSError("injected publication failure")
+        original_replace(source_path, target_path)
+
+    monkeypatch.setattr(os, "replace", failing_directory_replace)
+    with pytest.raises(ValueError, match="publish playable stem artifacts"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+    version_directory = tmp_path / "playable-stems-v1"
+    assert list(version_directory.iterdir()) == []

From 16b525f70eac69afd28b2d800e69dabcb1142520 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:18:33 +0900
Subject: [PATCH 03/14] feat(separation): materialize aligned playable stem
 artifacts

---
 .../separation/playback_artifacts.py          | 371 ++++++++++++++++++
 1 file changed, 371 insertions(+)
 create mode 100644 services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py

diff --git a/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py b/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py
new file mode 100644
index 000000000..0b5876174
--- /dev/null
+++ b/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py
@@ -0,0 +1,371 @@
+"""Materialize separated sources as revocable native playback artifacts.
+
+The module converts one complete, aligned Demucs source set into deterministic
+mono PCM16 WAV files below an app-owned temporary root. It returns an internal
+native manifest for the trusted Tauri boundary; renderer-safe projection and
+revocation remain native responsibilities.
+
+Security Notes:
+- Model arrays are untrusted until their kind, dtype, rank, size, alignment, and
+  finiteness are validated.
+- The artifact-set identity is a lowercase SHA-256 token and cannot select an
+  arbitrary path.
+- Publication uses a same-filesystem staging directory and one directory rename,
+  so a failed write does not expose a partial target set.
+- Existing artifact identities are reused only when every expected byte hash
+  matches; collisions fail closed without replacing prior data.
+- The returned native paths must be stripped or rewritten before renderer IPC.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import stat
+import tempfile
+import wave
+from pathlib import Path
+from typing import Any, Final, Literal, Mapping, TypedDict, cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+PlaybackStemKind = Literal["vocals", "bass", "drums", "other"]
+PlaybackStemArray = NDArray[np.floating[Any]]
+
+CANONICAL_PLAYBACK_STEM_KINDS: Final[tuple[PlaybackStemKind, ...]] = (
+    "vocals",
+    "bass",
+    "drums",
+    "other",
+)
+PLAYABLE_STEM_ARTIFACT_VERSION: Final[Literal[1]] = 1
+PLAYABLE_STEM_MEDIA_TYPE: Final[Literal["audio/wav"]] = "audio/wav"
+MIN_PLAYBACK_SAMPLE_RATE_HZ: Final = 8_000
+MAX_PLAYBACK_SAMPLE_RATE_HZ: Final = 192_000
+PCM16_MAXIMUM_SAMPLE: Final = 32_767.0
+PCM16_NORMALIZED_PEAK: Final = PCM16_MAXIMUM_SAMPLE / 32_768.0
+ARTIFACT_SET_ID_PATTERN: Final = re.compile(r"[0-9a-f]{64}\Z")
+HASH_READ_CHUNK_BYTES: Final = 1024 * 1024
+
+
+class NativePlayableStemArtifact(TypedDict):
+    """Trusted-process metadata for one generated stem media file."""
+
+    artifactId: str
+    stemKind: PlaybackStemKind
+    nativeFilePath: str
+    fileSizeBytes: int
+    contentHashSha256: str
+    mediaType: Literal["audio/wav"]
+    sampleRate: int
+    channelCount: Literal[1]
+    sampleCount: int
+    durationSeconds: float
+
+
+class NativePlayableStemArtifactSet(TypedDict):
+    """Trusted-process manifest for one complete aligned playback source set."""
+
+    artifactSetId: str
+    formatVersion: Literal[1]
+    sampleRate: int
+    channelCount: Literal[1]
+    sampleCount: int
+    durationSeconds: float
+    appliedGain: float
+    stemArtifacts: list[NativePlayableStemArtifact]
+
+
+def materialize_playable_stem_artifact_set(
+    *,
+    stem_arrays: Mapping[str, object],
+    sample_rate_hz: object,
+    artifact_root: str | Path,
+    artifact_set_id: str,
+) -> NativePlayableStemArtifactSet:
+    """Validate and atomically publish one complete PCM16 stem artifact set.
+
+    ``artifact_root`` must already belong to the current BandScope project. The
+    function adds only the fixed ``playable-stems-v1/<sha256>`` suffix and never
+    accepts a caller-provided filename. It intentionally returns native paths
+    for the trusted Tauri process; those paths are not a renderer contract.
+    """
+    validated_sample_rate = _validate_sample_rate(sample_rate_hz)
+    validated_artifact_set_id = _validate_artifact_set_id(artifact_set_id)
+    validated_stem_arrays, sample_count, applied_gain = _validate_stem_arrays(stem_arrays)
+    version_directory = _prepare_version_directory(Path(artifact_root))
+    artifact_directory = version_directory / validated_artifact_set_id
+    staging_directory: Path | None = Path(
+        tempfile.mkdtemp(prefix=f".{validated_artifact_set_id}.", dir=version_directory)
+    )
+
+    try:
+        assert staging_directory is not None
+        staging_artifacts = _write_staging_artifacts(
+            stem_arrays=validated_stem_arrays,
+            sample_rate_hz=validated_sample_rate,
+            sample_count=sample_count,
+            applied_gain=applied_gain,
+            staging_directory=staging_directory,
+        )
+        published_directory = _publish_artifact_directory(
+            staging_directory=staging_directory,
+            artifact_directory=artifact_directory,
+            staging_artifacts=staging_artifacts,
+        )
+        staging_directory = None
+        stem_artifacts = _project_artifacts_to_directory(
+            source_artifacts=staging_artifacts,
+            artifact_directory=published_directory,
+        )
+    finally:
+        if staging_directory is not None and staging_directory.exists():
+            shutil.rmtree(staging_directory, ignore_errors=True)
+
+    return {
+        "artifactSetId": validated_artifact_set_id,
+        "formatVersion": PLAYABLE_STEM_ARTIFACT_VERSION,
+        "sampleRate": validated_sample_rate,
+        "channelCount": 1,
+        "sampleCount": sample_count,
+        "durationSeconds": sample_count / validated_sample_rate,
+        "appliedGain": applied_gain,
+        "stemArtifacts": stem_artifacts,
+    }
+
+
+def _validate_sample_rate(sample_rate_hz: object) -> int:
+    """Return a bounded integer media sample rate or fail closed."""
+    if (
+        isinstance(sample_rate_hz, bool)
+        or not isinstance(sample_rate_hz, int)
+        or not MIN_PLAYBACK_SAMPLE_RATE_HZ
+        <= sample_rate_hz
+        <= MAX_PLAYBACK_SAMPLE_RATE_HZ
+    ):
+        raise ValueError("Invalid playable stem sample rate.")
+    return sample_rate_hz
+
+
+def _validate_artifact_set_id(artifact_set_id: object) -> str:
+    """Return a lowercase SHA-256 artifact-set identifier or fail closed."""
+    if not isinstance(artifact_set_id, str) or not ARTIFACT_SET_ID_PATTERN.fullmatch(
+        artifact_set_id
+    ):
+        raise ValueError("Invalid playable stem artifact set identity.")
+    return artifact_set_id
+
+
+def _validate_stem_arrays(
+    stem_arrays: Mapping[str, object],
+) -> tuple[dict[PlaybackStemKind, PlaybackStemArray], int, float]:
+    """Snapshot and validate a complete aligned floating-point source set."""
+    if set(stem_arrays) != set(CANONICAL_PLAYBACK_STEM_KINDS):
+        raise ValueError("Playable artifacts require the exact canonical stems.")
+
+    validated_stem_arrays: dict[PlaybackStemKind, PlaybackStemArray] = {}
+    aligned_sample_count: int | None = None
+    maximum_absolute_sample = 0.0
+    for stem_kind in CANONICAL_PLAYBACK_STEM_KINDS:
+        stem_array = stem_arrays[stem_kind]
+        if not isinstance(stem_array, np.ndarray) or not np.issubdtype(
+            stem_array.dtype, np.floating
+        ):
+            raise ValueError(f"Playable stem {stem_kind} must be a floating-point array.")
+        if stem_array.ndim != 1:
+            raise ValueError(f"Playable stem {stem_kind} must be one-dimensional.")
+        if stem_array.size == 0:
+            raise ValueError(f"Playable stem {stem_kind} must be non-empty.")
+        if not bool(np.isfinite(stem_array).all()):
+            raise ValueError(f"Playable stem {stem_kind} must contain only finite samples.")
+
+        current_sample_count = int(stem_array.size)
+        if aligned_sample_count is None:
+            aligned_sample_count = current_sample_count
+        elif current_sample_count != aligned_sample_count:
+            raise ValueError("Playable stems must have aligned sample counts.")
+
+        stem_snapshot = cast(PlaybackStemArray, np.asarray(stem_array, dtype=np.float32).copy())
+        validated_stem_arrays[stem_kind] = stem_snapshot
+        maximum_absolute_sample = max(
+            maximum_absolute_sample,
+            float(np.max(np.abs(stem_snapshot))),
+        )
+
+    assert aligned_sample_count is not None
+    applied_gain = (
+        1.0
+        if maximum_absolute_sample <= PCM16_NORMALIZED_PEAK
+        else PCM16_NORMALIZED_PEAK / maximum_absolute_sample
+    )
+    return validated_stem_arrays, aligned_sample_count, applied_gain
+
+
+def _prepare_version_directory(artifact_root: Path) -> Path:
+    """Create and validate the fixed app-owned artifact version directory."""
+    try:
+        artifact_root.mkdir(parents=True, exist_ok=True)
+    except OSError as root_error:
+        raise ValueError("Invalid playable stem artifact root.") from root_error
+    _require_plain_directory(artifact_root, "artifact root")
+
+    version_directory = artifact_root / "playable-stems-v1"
+    try:
+        version_directory.mkdir(exist_ok=True)
+    except OSError as version_error:
+        raise ValueError("Invalid playable stem artifact root.") from version_error
+    _require_plain_directory(version_directory, "artifact root")
+
+    return version_directory.resolve(strict=True)
+
+
+def _require_plain_directory(directory_path: Path, field_name: str) -> None:
+    """Reject symbolic links and non-directory entries at owned path components."""
+    try:
+        directory_status = directory_path.lstat()
+    except OSError as status_error:
+        raise ValueError(f"Invalid playable stem {field_name}.") from status_error
+    if directory_path.is_symlink() or not stat.S_ISDIR(directory_status.st_mode):
+        raise ValueError(f"Invalid playable stem {field_name}.")
+
+
+def _write_staging_artifacts(
+    *,
+    stem_arrays: Mapping[PlaybackStemKind, PlaybackStemArray],
+    sample_rate_hz: int,
+    sample_count: int,
+    applied_gain: float,
+    staging_directory: Path,
+) -> list[NativePlayableStemArtifact]:
+    """Write and hash every source inside an unpublished staging directory."""
+    staging_artifacts: list[NativePlayableStemArtifact] = []
+    try:
+        for stem_kind in CANONICAL_PLAYBACK_STEM_KINDS:
+            staging_path = staging_directory / f"{stem_kind}.wav"
+            pcm_samples = np.rint(
+                stem_arrays[stem_kind] * np.float32(applied_gain * PCM16_MAXIMUM_SAMPLE)
+            ).astype("<i2")
+            with wave.open(str(staging_path), "wb") as wave_writer:
+                wave_writer.setnchannels(1)
+                wave_writer.setsampwidth(2)
+                wave_writer.setframerate(sample_rate_hz)
+                wave_writer.writeframes(pcm_samples.tobytes())
+            with staging_path.open("rb+") as artifact_file:
+                artifact_file.flush()
+                os.fsync(artifact_file.fileno())
+            file_size_bytes = staging_path.stat().st_size
+            staging_artifacts.append(
+                {
+                    "artifactId": f"stem-{stem_kind}",
+                    "stemKind": stem_kind,
+                    "nativeFilePath": str(staging_path),
+                    "fileSizeBytes": file_size_bytes,
+                    "contentHashSha256": _calculate_file_sha256(staging_path),
+                    "mediaType": PLAYABLE_STEM_MEDIA_TYPE,
+                    "sampleRate": sample_rate_hz,
+                    "channelCount": 1,
+                    "sampleCount": sample_count,
+                    "durationSeconds": sample_count / sample_rate_hz,
+                }
+            )
+    except (OSError, wave.Error, ValueError) as write_error:
+        raise ValueError("Could not create playable stem artifacts.") from write_error
+    return staging_artifacts
+
+
+def _publish_artifact_directory(
+    *,
+    staging_directory: Path,
+    artifact_directory: Path,
+    staging_artifacts: list[NativePlayableStemArtifact],
+) -> Path:
+    """Publish a new set atomically or reuse an identical existing set."""
+    if artifact_directory.exists() or artifact_directory.is_symlink():
+        if _existing_artifacts_match(
+            artifact_directory=artifact_directory,
+            staging_artifacts=staging_artifacts,
+        ):
+            shutil.rmtree(staging_directory)
+            return artifact_directory
+        raise ValueError("Playable stem artifact identity collision.")
+
+    try:
+        os.replace(staging_directory, artifact_directory)
+    except OSError as publish_error:
+        if artifact_directory.exists() and _existing_artifacts_match(
+            artifact_directory=artifact_directory,
+            staging_artifacts=staging_artifacts,
+        ):
+            shutil.rmtree(staging_directory)
+            return artifact_directory
+        raise ValueError("Could not publish playable stem artifacts.") from publish_error
+    return artifact_directory
+
+
+def _existing_artifacts_match(
+    *,
+    artifact_directory: Path,
+    staging_artifacts: list[NativePlayableStemArtifact],
+) -> bool:
+    """Return whether an existing plain directory exactly matches staged bytes."""
+    try:
+        _require_plain_directory(artifact_directory, "artifact directory")
+        expected_names = {f"{stem_kind}.wav" for stem_kind in CANONICAL_PLAYBACK_STEM_KINDS}
+        actual_entries = list(artifact_directory.iterdir())
+        if {entry_path.name for entry_path in actual_entries} != expected_names:
+            return False
+        staged_by_kind = {
+            staged_artifact["stemKind"]: staged_artifact
+            for staged_artifact in staging_artifacts
+        }
+        for stem_kind in CANONICAL_PLAYBACK_STEM_KINDS:
+            existing_path = artifact_directory / f"{stem_kind}.wav"
+            existing_status = existing_path.lstat()
+            if existing_path.is_symlink() or not stat.S_ISREG(existing_status.st_mode):
+                return False
+            staged_artifact = staged_by_kind[stem_kind]
+            if existing_status.st_size != staged_artifact["fileSizeBytes"]:
+                return False
+            if _calculate_file_sha256(existing_path) != staged_artifact["contentHashSha256"]:
+                return False
+    except (OSError, ValueError):
+        return False
+    return True
+
+
+def _project_artifacts_to_directory(
+    *,
+    source_artifacts: list[NativePlayableStemArtifact],
+    artifact_directory: Path,
+) -> list[NativePlayableStemArtifact]:
+    """Replace staging paths with paths in the atomically published directory."""
+    return [
+        {
+            "artifactId": source_artifact["artifactId"],
+            "stemKind": source_artifact["stemKind"],
+            "nativeFilePath": str(
+                artifact_directory / f'{source_artifact["stemKind"]}.wav'
+            ),
+            "fileSizeBytes": source_artifact["fileSizeBytes"],
+            "contentHashSha256": source_artifact["contentHashSha256"],
+            "mediaType": source_artifact["mediaType"],
+            "sampleRate": source_artifact["sampleRate"],
+            "channelCount": source_artifact["channelCount"],
+            "sampleCount": source_artifact["sampleCount"],
+            "durationSeconds": source_artifact["durationSeconds"],
+        }
+        for source_artifact in source_artifacts
+    ]
+
+
+def _calculate_file_sha256(file_path: Path) -> str:
+    """Calculate a SHA-256 digest without loading a complete media file in memory."""
+    file_digest = hashlib.sha256()
+    with file_path.open("rb") as artifact_file:
+        while file_chunk := artifact_file.read(HASH_READ_CHUNK_BYTES):
+            file_digest.update(file_chunk)
+    return file_digest.hexdigest()

From 5d4a2f57837e8d4838500eb4f99defc859d6b522 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:19:30 +0900
Subject: [PATCH 04/14] test(separation): cover playable artifact failure
 boundaries

---
 .../tests/test_playback_artifacts.py          | 175 +++++++++++++++++-
 1 file changed, 174 insertions(+), 1 deletion(-)

diff --git a/services/analysis-engine/tests/test_playback_artifacts.py b/services/analysis-engine/tests/test_playback_artifacts.py
index 0c9a37066..9b6092c1f 100644
--- a/services/analysis-engine/tests/test_playback_artifacts.py
+++ b/services/analysis-engine/tests/test_playback_artifacts.py
@@ -132,7 +132,7 @@ def test_materializer_rejects_invalid_sample_rate(
     with pytest.raises(ValueError, match=expected_message):
         materialize_playable_stem_artifact_set(
             stem_arrays=sample_stem_arrays(),
-            sample_rate_hz=invalid_sample_rate,  # type: ignore[arg-type]
+            sample_rate_hz=invalid_sample_rate,
             artifact_root=tmp_path,
             artifact_set_id=ARTIFACT_SET_ID,
         )
@@ -323,3 +323,176 @@ def failing_directory_replace(source_path: str | bytes, target_path: str | bytes
 
     version_directory = tmp_path / "playable-stems-v1"
     assert list(version_directory.iterdir()) == []
+
+
+def test_materializer_rejects_version_path_that_is_not_a_directory(tmp_path: Path) -> None:
+    """The fixed version component cannot be pre-created as a regular file."""
+    version_path = tmp_path / "playable-stems-v1"
+    version_path.write_text("not a directory", encoding="utf-8")
+    with pytest.raises(ValueError, match="artifact root"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_contains_artifact_root_status_failure(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Filesystem status failures stay behind the stable artifact-root error."""
+    artifact_root = tmp_path / "artifact-root"
+    original_lstat = Path.lstat
+
+    def failing_root_lstat(directory_path: Path) -> os.stat_result:
+        """Inject one status failure for the requested root only."""
+        if directory_path == artifact_root:
+            raise OSError("injected status failure")
+        return original_lstat(directory_path)
+
+    monkeypatch.setattr(Path, "lstat", failing_root_lstat)
+    with pytest.raises(ValueError, match="artifact root"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=artifact_root,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_contains_wave_encoding_failure(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """WAV encoder failures remove the staging directory and publish no set."""
+    from bandscope_analysis.separation import playback_artifacts
+
+    def failing_wave_open(*_arguments: object, **_keywords: object) -> None:
+        """Inject a stable encoding failure before a target is published."""
+        raise wave.Error("injected encoding failure")
+
+    monkeypatch.setattr(playback_artifacts.wave, "open", failing_wave_open)
+    with pytest.raises(ValueError, match="create playable stem artifacts"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+    assert list((tmp_path / "playable-stems-v1").iterdir()) == []
+
+
+def test_materializer_accepts_matching_publish_race(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A concurrent identical publication is reused after the local rename loses."""
+    import shutil
+
+    original_replace = os.replace
+
+    def racing_directory_replace(source_path: str | bytes, target_path: str | bytes) -> None:
+        """Publish an identical competing directory and report the local race as lost."""
+        source_candidate = Path(source_path)
+        target_candidate = Path(target_path)
+        if source_candidate.is_dir():
+            shutil.copytree(source_candidate, target_candidate)
+            raise OSError("injected publication race")
+        original_replace(source_path, target_path)
+
+    monkeypatch.setattr(os, "replace", racing_directory_replace)
+    artifact_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    assert len(artifact_result["stemArtifacts"]) == 4
+    version_directory = tmp_path / "playable-stems-v1"
+    assert [child_path.name for child_path in version_directory.iterdir()] == [ARTIFACT_SET_ID]
+
+
+def test_materializer_rejects_existing_set_with_unexpected_entry(tmp_path: Path) -> None:
+    """An existing set with an extra file cannot be reused as canonical evidence."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    artifact_directory = Path(first_result["stemArtifacts"][0]["nativeFilePath"]).parent
+    (artifact_directory / "unexpected.wav").write_bytes(b"unexpected")
+    with pytest.raises(ValueError, match="identity collision"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_rejects_existing_set_with_non_regular_stem(tmp_path: Path) -> None:
+    """Every expected artifact must remain a regular non-symlink file."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    vocal_path = Path(first_result["stemArtifacts"][0]["nativeFilePath"])
+    vocal_path.unlink()
+    vocal_path.mkdir()
+    with pytest.raises(ValueError, match="identity collision"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+def test_materializer_rejects_existing_set_with_same_size_hash_mismatch(
+    tmp_path: Path,
+) -> None:
+    """Equal byte length is not accepted when the published content hash differs."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    vocal_path = Path(first_result["stemArtifacts"][0]["nativeFilePath"])
+    original_bytes = bytearray(vocal_path.read_bytes())
+    original_bytes[-1] ^= 0x01
+    vocal_path.write_bytes(original_bytes)
+    with pytest.raises(ValueError, match="identity collision"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )
+
+
+@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symbolic links are unavailable")
+def test_materializer_rejects_existing_artifact_directory_symlink(tmp_path: Path) -> None:
+    """A previously published identity cannot be redirected to another directory."""
+    first_result = materialize_playable_stem_artifact_set(
+        stem_arrays=sample_stem_arrays(),
+        sample_rate_hz=SAMPLE_RATE_HZ,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    artifact_directory = Path(first_result["stemArtifacts"][0]["nativeFilePath"]).parent
+    relocated_directory = tmp_path / "relocated-artifacts"
+    artifact_directory.rename(relocated_directory)
+    artifact_directory.symlink_to(relocated_directory, target_is_directory=True)
+    with pytest.raises(ValueError, match="identity collision"):
+        materialize_playable_stem_artifact_set(
+            stem_arrays=sample_stem_arrays(),
+            sample_rate_hz=SAMPLE_RATE_HZ,
+            artifact_root=tmp_path,
+            artifact_set_id=ARTIFACT_SET_ID,
+        )

From 319cdd99b83988159f729602cd2fdedb75b4f2a9 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:22:11 +0900
Subject: [PATCH 05/14] test(separation): require playable artifact package
 exports

---
 .../tests/test_playback_artifact_exports.py   | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 services/analysis-engine/tests/test_playback_artifact_exports.py

diff --git a/services/analysis-engine/tests/test_playback_artifact_exports.py b/services/analysis-engine/tests/test_playback_artifact_exports.py
new file mode 100644
index 000000000..839db9150
--- /dev/null
+++ b/services/analysis-engine/tests/test_playback_artifact_exports.py
@@ -0,0 +1,22 @@
+"""Public export contract for playable stem artifact materialization."""
+
+from __future__ import annotations
+
+from bandscope_analysis.separation.playback_artifacts import (
+    materialize_playable_stem_artifact_set,
+)
+
+
+def test_separation_package_exports_playable_artifact_contract() -> None:
+    """The separation package exposes the artifact API to orchestration code."""
+    from bandscope_analysis.separation import (
+        NativePlayableStemArtifact,
+        NativePlayableStemArtifactSet,
+        PlaybackStemKind,
+        materialize_playable_stem_artifact_set as exported_materializer,
+    )
+
+    assert NativePlayableStemArtifact.__name__ == "NativePlayableStemArtifact"
+    assert NativePlayableStemArtifactSet.__name__ == "NativePlayableStemArtifactSet"
+    assert PlaybackStemKind is not None
+    assert exported_materializer is materialize_playable_stem_artifact_set

From 17b1746a24c18b37f3a437d482f250ff27e78f7f Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:23:31 +0900
Subject: [PATCH 06/14] feat(separation): export playable artifact contract

---
 .../src/bandscope_analysis/separation/__init__.py    | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/services/analysis-engine/src/bandscope_analysis/separation/__init__.py b/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
index 5e812203e..b3fd5d9c9 100644
--- a/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
+++ b/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
@@ -11,6 +11,13 @@
     StemDescriptor,
     StemRoleTypeMap,
 )
+from .playback_artifacts import (
+    CANONICAL_PLAYBACK_STEM_KINDS,
+    NativePlayableStemArtifact,
+    NativePlayableStemArtifactSet,
+    PlaybackStemKind,
+    materialize_playable_stem_artifact_set,
+)
 from .separator import StemSeparator
 
 __all__ = [
@@ -19,10 +26,15 @@
     "AudioStemArray",
     "AudioStemName",
     "AudioStemPayload",
+    "CANONICAL_PLAYBACK_STEM_KINDS",
+    "NativePlayableStemArtifact",
+    "NativePlayableStemArtifactSet",
+    "PlaybackStemKind",
     "StemRoleTypeMap",
     "AudioStemSeparator",
     "StemSeparator",
     "StemCategory",
     "StemDescriptor",
     "SeparationResult",
+    "materialize_playable_stem_artifact_set",
 ]

From 46629bf3959b01a85d0c7ec236675b529599600a Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:29:19 +0900
Subject: [PATCH 07/14] test(separation): require path-free stem artifact
 status projection

---
 .../tests/test_playback_artifact_reference.py | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 services/analysis-engine/tests/test_playback_artifact_reference.py

diff --git a/services/analysis-engine/tests/test_playback_artifact_reference.py b/services/analysis-engine/tests/test_playback_artifact_reference.py
new file mode 100644
index 000000000..1e1590670
--- /dev/null
+++ b/services/analysis-engine/tests/test_playback_artifact_reference.py
@@ -0,0 +1,124 @@
+"""Path-free status projection contract for playable stem artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from bandscope_analysis.separation import (
+    build_playable_stem_artifact_set_reference,
+    materialize_playable_stem_artifact_set,
+)
+
+
+ARTIFACT_SET_ID = "b" * 64
+
+
+def _contains_native_path(value: object) -> bool:
+    """Return whether a nested status value contains a native path field."""
+    if isinstance(value, dict):
+        return any(
+            "path" in str(field_name).lower() or _contains_native_path(field_value)
+            for field_name, field_value in value.items()
+        )
+    if isinstance(value, list):
+        return any(_contains_native_path(item_value) for item_value in value)
+    return False
+
+
+def test_reference_projection_removes_every_native_path(tmp_path: Path) -> None:
+    """The status projection is safe to send across the Python-to-native boundary."""
+    sample_axis = np.linspace(-0.5, 0.5, 32, dtype=np.float32)
+    native_artifact_set = materialize_playable_stem_artifact_set(
+        stem_arrays={
+            "vocals": sample_axis,
+            "bass": sample_axis * np.float32(0.5),
+            "drums": sample_axis * np.float32(0.25),
+            "other": sample_axis * np.float32(0.125),
+        },
+        sample_rate_hz=16_000,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+
+    artifact_reference = build_playable_stem_artifact_set_reference(native_artifact_set)
+
+    assert artifact_reference == {
+        "artifactSetId": ARTIFACT_SET_ID,
+        "formatVersion": 1,
+        "sampleRate": 16_000,
+        "channelCount": 1,
+        "sampleCount": 32,
+        "durationSeconds": 32 / 16_000,
+        "appliedGain": 1.0,
+        "stemArtifacts": [
+            {
+                "artifactId": f"stem-{stem_kind}",
+                "stemKind": stem_kind,
+                "fileSizeBytes": native_artifact_set["stemArtifacts"][artifact_index][
+                    "fileSizeBytes"
+                ],
+                "contentHashSha256": native_artifact_set["stemArtifacts"][artifact_index][
+                    "contentHashSha256"
+                ],
+                "mediaType": "audio/wav",
+                "sampleRate": 16_000,
+                "channelCount": 1,
+                "sampleCount": 32,
+                "durationSeconds": 32 / 16_000,
+            }
+            for artifact_index, stem_kind in enumerate(("vocals", "bass", "drums", "other"))
+        ],
+    }
+    assert not _contains_native_path(artifact_reference)
+
+
+def test_reference_projection_is_detached_from_native_manifest(tmp_path: Path) -> None:
+    """Mutating trusted native metadata cannot alter an already-projected status value."""
+    sample_axis = np.zeros(8, dtype=np.float32)
+    native_artifact_set = materialize_playable_stem_artifact_set(
+        stem_arrays={stem_kind: sample_axis for stem_kind in ("vocals", "bass", "drums", "other")},
+        sample_rate_hz=8_000,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    artifact_reference = build_playable_stem_artifact_set_reference(native_artifact_set)
+
+    native_artifact_set["artifactSetId"] = "c" * 64
+    native_artifact_set["stemArtifacts"][0]["artifactId"] = "changed"
+    native_artifact_set["stemArtifacts"].reverse()
+
+    assert artifact_reference["artifactSetId"] == ARTIFACT_SET_ID
+    assert [
+        stem_artifact["stemKind"] for stem_artifact in artifact_reference["stemArtifacts"]
+    ] == ["vocals", "bass", "drums", "other"]
+    assert artifact_reference["stemArtifacts"][0]["artifactId"] == "stem-vocals"
+
+
+def test_reference_projection_preserves_json_scalar_types(tmp_path: Path) -> None:
+    """The projection contains only dictionaries, lists, strings, integers, and floats."""
+    sample_axis = np.zeros(8, dtype=np.float32)
+    native_artifact_set = materialize_playable_stem_artifact_set(
+        stem_arrays={stem_kind: sample_axis for stem_kind in ("vocals", "bass", "drums", "other")},
+        sample_rate_hz=8_000,
+        artifact_root=tmp_path,
+        artifact_set_id=ARTIFACT_SET_ID,
+    )
+    artifact_reference = build_playable_stem_artifact_set_reference(native_artifact_set)
+
+    def assert_json_value(value: Any) -> None:
+        """Recursively require the bounded JSON value family used by status emission."""
+        if isinstance(value, dict):
+            assert all(isinstance(field_name, str) for field_name in value)
+            for field_value in value.values():
+                assert_json_value(field_value)
+            return
+        if isinstance(value, list):
+            for item_value in value:
+                assert_json_value(item_value)
+            return
+        assert isinstance(value, (str, int, float)) and not isinstance(value, bool)
+
+    assert_json_value(artifact_reference)

From f87395949ecc5e60061d6b64f493bb55e569d1b0 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:31:20 +0900
Subject: [PATCH 08/14] feat(separation): project path-free stem artifact
 references

---
 .../separation/playback_artifacts.py          | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py b/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py
index 0b5876174..5cd35e888 100644
--- a/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py
+++ b/services/analysis-engine/src/bandscope_analysis/separation/playback_artifacts.py
@@ -80,6 +80,33 @@ class NativePlayableStemArtifactSet(TypedDict):
     stemArtifacts: list[NativePlayableStemArtifact]
 
 
+class PlayableStemArtifactReference(TypedDict):
+    """Path-free metadata for one generated stem at a native registration boundary."""
+
+    artifactId: str
+    stemKind: PlaybackStemKind
+    fileSizeBytes: int
+    contentHashSha256: str
+    mediaType: Literal["audio/wav"]
+    sampleRate: int
+    channelCount: Literal[1]
+    sampleCount: int
+    durationSeconds: float
+
+
+class PlayableStemArtifactSetReference(TypedDict):
+    """Path-free reference to one complete aligned playback source set."""
+
+    artifactSetId: str
+    formatVersion: Literal[1]
+    sampleRate: int
+    channelCount: Literal[1]
+    sampleCount: int
+    durationSeconds: float
+    appliedGain: float
+    stemArtifacts: list[PlayableStemArtifactReference]
+
+
 def materialize_playable_stem_artifact_set(
     *,
     stem_arrays: Mapping[str, object],
@@ -138,6 +165,35 @@ def materialize_playable_stem_artifact_set(
     }
 
 
+def build_playable_stem_artifact_set_reference(
+    native_artifact_set: NativePlayableStemArtifactSet,
+) -> PlayableStemArtifactSetReference:
+    """Project trusted native metadata into a detached path-free status value."""
+    return {
+        "artifactSetId": native_artifact_set["artifactSetId"],
+        "formatVersion": native_artifact_set["formatVersion"],
+        "sampleRate": native_artifact_set["sampleRate"],
+        "channelCount": native_artifact_set["channelCount"],
+        "sampleCount": native_artifact_set["sampleCount"],
+        "durationSeconds": native_artifact_set["durationSeconds"],
+        "appliedGain": native_artifact_set["appliedGain"],
+        "stemArtifacts": [
+            {
+                "artifactId": native_artifact["artifactId"],
+                "stemKind": native_artifact["stemKind"],
+                "fileSizeBytes": native_artifact["fileSizeBytes"],
+                "contentHashSha256": native_artifact["contentHashSha256"],
+                "mediaType": native_artifact["mediaType"],
+                "sampleRate": native_artifact["sampleRate"],
+                "channelCount": native_artifact["channelCount"],
+                "sampleCount": native_artifact["sampleCount"],
+                "durationSeconds": native_artifact["durationSeconds"],
+            }
+            for native_artifact in native_artifact_set["stemArtifacts"]
+        ],
+    }
+
+
 def _validate_sample_rate(sample_rate_hz: object) -> int:
     """Return a bounded integer media sample rate or fail closed."""
     if (

From edfe1676d207d74eccbd991eb30ea16c04dc52eb Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:31:39 +0900
Subject: [PATCH 09/14] feat(separation): export path-free artifact reference
 contract

---
 .../src/bandscope_analysis/separation/__init__.py           | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/services/analysis-engine/src/bandscope_analysis/separation/__init__.py b/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
index b3fd5d9c9..943cb9ed5 100644
--- a/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
+++ b/services/analysis-engine/src/bandscope_analysis/separation/__init__.py
@@ -16,6 +16,9 @@
     NativePlayableStemArtifact,
     NativePlayableStemArtifactSet,
     PlaybackStemKind,
+    PlayableStemArtifactReference,
+    PlayableStemArtifactSetReference,
+    build_playable_stem_artifact_set_reference,
     materialize_playable_stem_artifact_set,
 )
 from .separator import StemSeparator
@@ -30,11 +33,14 @@
     "NativePlayableStemArtifact",
     "NativePlayableStemArtifactSet",
     "PlaybackStemKind",
+    "PlayableStemArtifactReference",
+    "PlayableStemArtifactSetReference",
     "StemRoleTypeMap",
     "AudioStemSeparator",
     "StemSeparator",
     "StemCategory",
     "StemDescriptor",
     "SeparationResult",
+    "build_playable_stem_artifact_set_reference",
     "materialize_playable_stem_artifact_set",
 ]

From f6a0f13f89555b00a1e5c88e74cac6ace9718132 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:32:36 +0900
Subject: [PATCH 10/14] docs(adr): narrow playable stem process authority

---
 ...001-playable-stem-delivery-and-audition.md | 55 +++++++++++++------
 1 file changed, 38 insertions(+), 17 deletions(-)

diff --git a/docs/adr/0001-playable-stem-delivery-and-audition.md b/docs/adr/0001-playable-stem-delivery-and-audition.md
index ac78a8d9f..935841922 100644
--- a/docs/adr/0001-playable-stem-delivery-and-audition.md
+++ b/docs/adr/0001-playable-stem-delivery-and-audition.md
@@ -29,7 +29,7 @@ The first implementation must not imply that `other` is a separately identified
 
 After successful separation, the analysis engine will materialize the four aligned mono sources as PCM16 WAV files under the current project's app-owned temporary workspace. A single shared gain is applied to the whole set when needed to prevent clipping while preserving inter-stem level relationships.
 
-The internal native manifest is versioned and contains, at minimum:
+The Python playback-artifact adapter may use an in-process native manifest while it publishes and verifies the files:
 
 ```text
 artifact_set_id
@@ -48,7 +48,13 @@ stem_artifacts[]
   media_type
 ```
 
-The engine may disclose the native path only to the trusted Tauri process over the existing bounded JSONL subprocess boundary. It must never enter renderer state, UI copy, logs, exported handoffs, or persisted project JSON.
+The native path does **not** cross the analysis JSONL boundary. Before status emission, the adapter creates a detached path-free reference containing only artifact identity, canonical stem kind, media metadata, size, and content hash. Tauri already owns the project temporary root and reconstructs the only permitted location from the fixed suffix:
+
+```text
+{project_temp_root}/playable-stems-v1/{artifact_set_id}/{stem_kind}.wav
+```
+
+This avoids granting a Python-returned path filesystem authority. Native paths must never enter renderer state, UI copy, logs, exported handoffs, or persisted project JSON.
 
 ### 2. Extend the existing revocable playback authority
 
@@ -57,7 +63,7 @@ The Tauri layer will validate each artifact against the current project's app-ow
 - one artifact for each canonical stem and no unknown stem;
 - a regular, non-symlink WAV file under the expected project artifact directory;
 - bounded nonzero size;
-- manifest/file identity agreement;
+- path-free reference and file identity agreement;
 - common sample rate, sample count, channel count, and duration;
 - no duplicate artifact identifier or stem kind.
 
@@ -98,13 +104,20 @@ Multiple independently controlled `HTMLAudioElement` instances are not an accept
 
 Artifact creation proves that an output exists and can be played. It does not prove perceptual quality, instrument identity beyond the canonical model outputs, or genre-wide accuracy. Source-separation accuracy and rights-cleared listening evidence remain owned by Issue #770 and PR #828. Resource admission and decode bounds remain owned by Issue #781 and its canonical PR #866.
 
+### 6. Keep the Python implementation outside the numerical hot path
+
+The first artifact adapter is implemented in Python because Demucs currently yields NumPy arrays inside the existing analysis process, and the adapter performs bounded validation, PCM16 encoding, hashing, and atomic publication without introducing another array copy across a language boundary. It does not estimate, separate, resample, align, or score audio.
+
+This is an explicit adapter exception rather than a precedent for Python-owned production DSP. The source-separation and timing hot paths remain subject to the repository's Rust-first policy. Move PCM encoding or hashing into a Rust-owned native service if profiling shows this adapter materially affects latency, memory, concurrency, or attack-surface goals; preserve the same versioned artifact contract and tests when doing so.
+
 ## Domain ownership
 
 | Responsibility | Owner |
 | --- | --- |
 | Decode and separation computation | `services/analysis-engine` Source Separation |
 | PCM artifact materialization | `services/analysis-engine` Playback Artifact adapter |
-| Native path, identity, revocation, and byte-range serving | `apps/desktop/src-tauri` Playback Authority |
+| Path-free artifact reference | `services/analysis-engine` Playback Artifact adapter |
+| Native location derivation, identity, revocation, and byte-range serving | `apps/desktop/src-tauri` Playback Authority |
 | Public status and opaque source contracts | `packages/shared-types` |
 | Loop, count-in, seek, rate, and source selection | `apps/desktop` Active Player |
 | MIR accuracy and claim boundaries | Issue #770 / PR #828 |
@@ -119,14 +132,16 @@ The playback artifact adapter does not become a second source-separation owner,
 
 - model-produced floating-point arrays;
 - app-owned cache and temporary directories;
-- Python-to-Rust manifest fields;
+- path-free Python-to-Rust artifact-reference fields;
 - custom-protocol paths and byte-range requests;
 - renderer source-selection events.
 
 ### Trust boundaries
 
 - analysis arrays are untrusted numeric output until shape, finiteness, cardinality, and alignment validation succeeds;
-- native paths are untrusted subprocess output until Tauri validates app-owned containment and file identity;
+- the analysis process emits no native path as authority;
+- Tauri derives the fixed artifact location from its own project root and a strict lowercase SHA-256 artifact-set identifier;
+- every derived file is revalidated by native identity, size, hash, media structure, and alignment before registration;
 - renderer handles are identifiers only and never paths;
 - selecting a source grants no new filesystem, network, export, or generic execution capability.
 
@@ -160,11 +175,16 @@ Rejected. It breaks the rehearsal loop, exposes filesystem concerns to the user,
 
 Rejected. The current canonical model does not establish that identity. The shipped label is `Other instruments` until independently validated model capability says otherwise.
 
+### F. Send native artifact paths to Tauri in the analysis status
+
+Rejected. Although Tauri is trusted, accepting a subprocess-returned path would unnecessarily widen the authority parser. A path-free artifact reference plus a fixed location derived from the already-authorized project root provides a narrower and more reviewable boundary.
+
 ## Consequences
 
 ### Positive
 
 - Real separation becomes an audible product capability instead of an internal analysis detail.
+- No native artifact path crosses the process or renderer status contract.
 - The renderer continues to receive opaque, revocable authority rather than native paths.
 - The existing Active Player remains the single transport state machine.
 - The design creates a measurable path to a later synchronized mixer without prematurely shipping fake controls.
@@ -173,7 +193,7 @@ Rejected. The current canonical model does not establish that identity. The ship
 ### Costs and constraints
 
 - Derived WAV files consume temporary disk space and require explicit lifecycle management.
-- The Python/Rust status boundary needs a trusted-internal manifest and a sanitized renderer projection.
+- Python and Rust must implement the same versioned path-free reference validation and location derivation contract.
 - The first slice auditions one source at a time; it does not satisfy the complete multitrack mixing expectation.
 - Changes touch Python, Rust, TypeScript, Tauri permissions, CSP/protocol tests, UI, and documentation, so cross-platform exact-head evidence is mandatory.
 
@@ -183,16 +203,17 @@ This ADR remains `Proposed` until one unchanged exact head proves all of the fol
 
 1. successful local separation produces exactly four aligned, finite, playable WAV artifacts;
 2. a feature-cache hit can recreate or reuse the same artifact contract without rerunning the model;
-3. Tauri rejects paths outside the current app-owned project root, symlinks, replacements, stale projects, unknown stems, duplicates, and metadata mismatch;
-4. renderer-visible status contains no native path;
-5. the source selector exposes only `Full mix`, `Vocals`, `Bass`, `Drums`, and `Other instruments` when actually available;
-6. selecting a stem produces observable audio playback through the same section loop and transport controls as the full mix;
-7. source replacement, app project replacement, playback error, and project close fail safely;
-8. keyboard-only and screen-reader journeys can identify and select the active source;
-9. normal, loading, unavailable, error, and partial/fail-closed states have executable component evidence;
-10. macOS and Windows production desktop tests use rights-cleared audio and confirm the audible source change;
-11. repository-owned production statement and branch coverage and public documentation remain 100%;
-12. current-head CI, security, SAST, dependency, SBOM, package, release, review-thread, and independent-approval gates pass without bypass.
+3. the emitted analysis reference contains no native path and is detached from the in-process native manifest;
+4. Tauri rejects artifact references or files with paths outside the current app-owned project root, symlinks, replacements, stale projects, unknown stems, duplicates, or metadata mismatch;
+5. renderer-visible status contains no native path, file hash, or internal storage location;
+6. the source selector exposes only `Full mix`, `Vocals`, `Bass`, `Drums`, and `Other instruments` when actually available;
+7. selecting a stem produces observable audio playback through the same section loop and transport controls as the full mix;
+8. source replacement, app project replacement, playback error, and project close fail safely;
+9. keyboard-only and screen-reader journeys can identify and select the active source;
+10. normal, loading, unavailable, error, and partial/fail-closed states have executable component evidence;
+11. macOS and Windows production desktop tests use rights-cleared audio and confirm the audible source change;
+12. repository-owned production statement and branch coverage and public documentation remain 100%;
+13. current-head CI, security, SAST, dependency, SBOM, package, release, review-thread, and independent-approval gates pass without bypass.
 
 ## References
 

From 6c29f64f8aaa433961244eda7f7f27a8c2646aa1 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:34:32 +0900
Subject: [PATCH 11/14] test(api): require path-free playable stem status
 evidence

---
 .../tests/test_playback_artifact_status.py    | 247 ++++++++++++++++++
 1 file changed, 247 insertions(+)
 create mode 100644 services/analysis-engine/tests/test_playback_artifact_status.py

diff --git a/services/analysis-engine/tests/test_playback_artifact_status.py b/services/analysis-engine/tests/test_playback_artifact_status.py
new file mode 100644
index 000000000..154dffad9
--- /dev/null
+++ b/services/analysis-engine/tests/test_playback_artifact_status.py
@@ -0,0 +1,247 @@
+"""Analysis-status integration contract for path-free playable stem artifacts."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from unittest.mock import patch
+
+import numpy as np
+
+from bandscope_analysis.api import (
+    _materialize_playable_stem_artifact_reference,
+    run_analysis_job_updates,
+    validate_analysis_job_request,
+)
+
+
+def _local_request(tmp_path: Path, *, cache_enabled: bool = False) -> dict[str, object]:
+    """Return one validated local-audio request rooted in the test workspace."""
+    request: dict[str, object] = {
+        "sourceKind": "local_audio",
+        "projectId": "project-playable-stems",
+        "sourceLabel": "rights-cleared.wav",
+        "roleFocus": ["bass-guitar"],
+        "localSource": {
+            "sourcePath": str(tmp_path / "rights-cleared.wav"),
+            "fileName": "rights-cleared.wav",
+            "extension": "wav",
+            "fileSizeBytes": 4096,
+        },
+        "tempRoot": str(tmp_path / "temp"),
+    }
+    if cache_enabled:
+        request["cacheRoot"] = str(tmp_path / "cache")
+    return validate_analysis_job_request(request)
+
+
+def _audio_features() -> dict[str, object]:
+    """Return four aligned canonical sources without running a separation model."""
+    sample_axis = np.linspace(-0.5, 0.5, 64, dtype=np.float32)
+    return {
+        "stems": {
+            "vocals": sample_axis,
+            "bass": sample_axis * np.float32(0.5),
+            "drums": sample_axis * np.float32(0.25),
+            "other": sample_axis * np.float32(0.125),
+        },
+        "sr": 8_000,
+        "stem_role_types": {
+            "vocals": "vocal",
+            "bass": "instrument",
+            "drums": "instrument",
+            "other": "instrument",
+        },
+        "separation": {
+            "duration_seconds": 64 / 8_000,
+            "chunk_count": 1,
+            "notes": "Rights-cleared deterministic fixture.",
+        },
+    }
+
+
+def _minimal_song() -> dict[str, object]:
+    """Return a bounded rehearsal result so tests isolate artifact status behavior."""
+    return {
+        "id": "analyzed-song",
+        "title": "Rights-cleared fixture",
+        "sections": [
+            {
+                "id": "verse-1",
+                "label": "verse",
+                "groove": "Straight eighths",
+                "timeRange": {"start": 0, "end": 1},
+                "confidence": {
+                    "level": "high",
+                    "source": "fixture",
+                    "notes": "Deterministic test result.",
+                },
+                "roles": [],
+                "partGraph": [],
+            }
+        ],
+        "exportSummary": {
+            "format": "cue-sheet",
+            "headline": "Check the first section.",
+            "focusSections": ["verse"],
+        },
+    }
+
+
+def _assert_no_path_key(value: object) -> None:
+    """Reject a nested status value that contains any path-bearing field name."""
+    if isinstance(value, dict):
+        for field_name, field_value in value.items():
+            assert "path" not in str(field_name).lower()
+            _assert_no_path_key(field_value)
+    elif isinstance(value, list):
+        for item_value in value:
+            _assert_no_path_key(item_value)
+
+
+def test_materialize_reference_uses_request_owned_temp_root(tmp_path: Path) -> None:
+    """Artifact identity and location derive from the validated analysis request."""
+    request = _local_request(tmp_path)
+    artifact_reference = _materialize_playable_stem_artifact_reference(
+        request,
+        _audio_features(),
+    )
+
+    assert artifact_reference is not None
+    assert len(artifact_reference["artifactSetId"]) == 64
+    assert artifact_reference["formatVersion"] == 1
+    assert [
+        stem_artifact["stemKind"] for stem_artifact in artifact_reference["stemArtifacts"]
+    ] == ["vocals", "bass", "drums", "other"]
+    artifact_directory = (
+        tmp_path
+        / "temp"
+        / "playable-stems-v1"
+        / artifact_reference["artifactSetId"]
+    )
+    assert sorted(artifact_path.name for artifact_path in artifact_directory.iterdir()) == [
+        "bass.wav",
+        "drums.wav",
+        "other.wav",
+        "vocals.wav",
+    ]
+    _assert_no_path_key(artifact_reference)
+    json.dumps(artifact_reference)
+
+
+def test_materialize_reference_omits_inapplicable_or_malformed_features(
+    tmp_path: Path,
+) -> None:
+    """Only local requests with temp authority and complete sources produce references."""
+    demo_request = validate_analysis_job_request(
+        {
+            "sourceKind": "demo",
+            "sourceLabel": "Late Night Set",
+            "roleFocus": [],
+        }
+    )
+    request_without_temp = _local_request(tmp_path)
+    request_without_temp.pop("tempRoot")
+    invalid_features = _audio_features()
+    invalid_features["stems"] = {"bass": np.zeros(4, dtype=np.float32)}
+
+    assert _materialize_playable_stem_artifact_reference(demo_request, _audio_features()) is None
+    assert (
+        _materialize_playable_stem_artifact_reference(
+            request_without_temp,
+            _audio_features(),
+        )
+        is None
+    )
+    with patch("bandscope_analysis.api.logger") as logger:
+        assert (
+            _materialize_playable_stem_artifact_reference(
+                _local_request(tmp_path),
+                invalid_features,
+            )
+            is None
+        )
+    logger.warning.assert_called_once_with(
+        "Playable stem artifact publication failed; stems remain unavailable."
+    )
+
+
+def test_success_status_includes_path_free_artifact_reference(tmp_path: Path) -> None:
+    """Fresh separation attaches playable-source evidence only to terminal status."""
+    request = _local_request(tmp_path)
+    with (
+        patch("bandscope_analysis.api._build_local_audio_features", return_value=_audio_features()),
+        patch("bandscope_analysis.api.build_demo_rehearsal_song", return_value=_minimal_song()),
+    ):
+        updates = run_analysis_job_updates("job-playable", request, "2026-09-04T00:00:00Z")
+
+    assert all("playableStemArtifactSet" not in update for update in updates[:-1])
+    final_status = updates[-1]
+    assert final_status["state"] == "succeeded"
+    artifact_reference = final_status["playableStemArtifactSet"]
+    assert artifact_reference["artifactSetId"]
+    _assert_no_path_key(artifact_reference)
+
+
+def test_artifact_publication_failure_does_not_fabricate_or_fail_analysis(
+    tmp_path: Path,
+) -> None:
+    """A media-publication failure preserves analysis and omits stem availability."""
+    request = _local_request(tmp_path)
+    with (
+        patch("bandscope_analysis.api._build_local_audio_features", return_value=_audio_features()),
+        patch("bandscope_analysis.api.build_demo_rehearsal_song", return_value=_minimal_song()),
+        patch(
+            "bandscope_analysis.api.materialize_playable_stem_artifact_set",
+            side_effect=ValueError("payload-controlled detail"),
+        ),
+        patch("bandscope_analysis.api.logger") as logger,
+    ):
+        final_status = run_analysis_job_updates(
+            "job-unavailable",
+            request,
+            "2026-09-04T00:00:00Z",
+        )[-1]
+
+    assert final_status["state"] == "succeeded"
+    assert "playableStemArtifactSet" not in final_status
+    logger.warning.assert_called_once_with(
+        "Playable stem artifact publication failed; stems remain unavailable."
+    )
+    assert "payload-controlled" not in str(logger.mock_calls)
+
+
+def test_final_result_cache_hit_rebuilds_artifacts_from_feature_cache(tmp_path: Path) -> None:
+    """Cached analysis can restore stem playback without invoking separation again."""
+    request = _local_request(tmp_path, cache_enabled=True)
+    with (
+        patch("bandscope_analysis.api._build_local_audio_features", return_value=_audio_features()),
+        patch("bandscope_analysis.api.build_demo_rehearsal_song", return_value=_minimal_song()),
+    ):
+        first_status = run_analysis_job_updates(
+            "job-first",
+            request,
+            "2026-09-04T00:00:00Z",
+        )[-1]
+    first_reference = first_status["playableStemArtifactSet"]
+    shutil.rmtree(tmp_path / "temp" / "playable-stems-v1")
+
+    with patch("bandscope_analysis.api._build_local_audio_features") as separator:
+        cached_updates = run_analysis_job_updates(
+            "job-cached",
+            request,
+            "2026-09-04T00:01:00Z",
+        )
+
+    separator.assert_not_called()
+    cached_status = cached_updates[-1]
+    assert cached_status["cacheStatus"] == "hit"
+    assert cached_status["playableStemArtifactSet"] == first_reference
+    rebuilt_directory = (
+        tmp_path
+        / "temp"
+        / "playable-stems-v1"
+        / first_reference["artifactSetId"]
+    )
+    assert rebuilt_directory.is_dir()

From 5da57dfedf699fc158f98588d9e54306e992f8ea Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 09:36:53 +0900
Subject: [PATCH 12/14] chore(repair): verify playable stem status integration

---
 .../workflows/playable-stem-status-repair.yml |  82 +++++++
 scripts/repairs/apply_playable_stem_status.py | 200 ++++++++++++++++++
 2 files changed, 282 insertions(+)
 create mode 100644 .github/workflows/playable-stem-status-repair.yml
 create mode 100755 scripts/repairs/apply_playable_stem_status.py

diff --git a/.github/workflows/playable-stem-status-repair.yml b/.github/workflows/playable-stem-status-repair.yml
new file mode 100644
index 000000000..60cf1d2e6
--- /dev/null
+++ b/.github/workflows/playable-stem-status-repair.yml
@@ -0,0 +1,82 @@
+name: playable-stem-status-repair
+
+on:
+  push:
+    branches:
+      - feat/playable-stem-audition-961
+    paths:
+      - scripts/repairs/apply_playable_stem_status.py
+      - .github/workflows/playable-stem-status-repair.yml
+
+permissions:
+  contents: write
+
+concurrency:
+  group: playable-stem-status-repair-${{ github.repository }}-1159
+  cancel-in-progress: true
+
+jobs:
+  repair-and-verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.8.6"
+          enable-cache: false
+      - name: Verify exact branch identity
+        shell: bash
+        run: |
+          test "$GITHUB_REF_NAME" = "feat/playable-stem-audition-961"
+          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+      - name: Apply exact source repair
+        run: python scripts/repairs/apply_playable_stem_status.py
+      - name: Sync locked Python environment
+        run: uv sync --project services/analysis-engine --group dev --frozen
+      - name: Run focused playable-stem tests
+        run: |
+          uv run --project services/analysis-engine pytest \
+            services/analysis-engine/tests/test_playback_artifacts.py \
+            services/analysis-engine/tests/test_playback_artifact_exports.py \
+            services/analysis-engine/tests/test_playback_artifact_reference.py \
+            services/analysis-engine/tests/test_playback_artifact_status.py \
+            -q
+      - name: Run complete analysis-engine coverage
+        run: |
+          uv run --project services/analysis-engine pytest \
+            services/analysis-engine/tests \
+            --cov=services/analysis-engine/src/bandscope_analysis \
+            --cov-branch \
+            --cov-report=term-missing \
+            --cov-fail-under=100
+      - name: Run Python quality gates
+        run: |
+          uv run --project services/analysis-engine ruff check \
+            services/analysis-engine/src services/analysis-engine/tests
+          uv run --project services/analysis-engine ruff format --check \
+            services/analysis-engine/src services/analysis-engine/tests
+          uv run --project services/analysis-engine mypy \
+            services/analysis-engine/src
+          python -m compileall -q services/analysis-engine/src services/analysis-engine/tests
+          git diff --check
+      - name: Remove completed repair machinery
+        run: |
+          rm scripts/repairs/apply_playable_stem_status.py
+          rm .github/workflows/playable-stem-status-repair.yml
+      - name: Commit verified source repair
+        shell: bash
+        run: |
+          git config user.name "bandscope-repair-bot"
+          git config user.email "bandscope-repair-bot@users.noreply.github.com"
+          git add \
+            services/analysis-engine/src/bandscope_analysis/api.py \
+            services/analysis-engine/tests/test_playback_artifact_status.py \
+            scripts/repairs/apply_playable_stem_status.py \
+            .github/workflows/playable-stem-status-repair.yml
+          git diff --cached --quiet && { echo "No verified repair delta was produced." >&2; exit 1; }
+          git commit -m "feat(api): attach path-free playable stem status"
+          git push origin HEAD:feat/playable-stem-audition-961
diff --git a/scripts/repairs/apply_playable_stem_status.py b/scripts/repairs/apply_playable_stem_status.py
new file mode 100755
index 000000000..cd31d3de2
--- /dev/null
+++ b/scripts/repairs/apply_playable_stem_status.py
@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Apply the reviewed path-free playable-stem status integration exactly once.
+
+The script exists only to make a large-file source repair reviewable while the
+GitHub connector cannot apply a unified patch. It fails closed when any expected
+source marker has moved and is deleted by its owning workflow after verification.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+API_PATH = Path("services/analysis-engine/src/bandscope_analysis/api.py")
+
+
+def replace_once(source_text: str, old_text: str, new_text: str, label: str) -> str:
+    """Replace one exact source fragment or fail before mutating the file."""
+    occurrence_count = source_text.count(old_text)
+    if occurrence_count != 1:
+        raise RuntimeError(
+            f"Expected exactly one {label} source fragment, found {occurrence_count}."
+        )
+    return source_text.replace(old_text, new_text, 1)
+
+
+def main() -> None:
+    """Patch the analysis status boundary without changing unrelated source."""
+    api_text = API_PATH.read_text(encoding="utf-8")
+
+    api_text = replace_once(
+        api_text,
+        "from bandscope_analysis.separation import AudioStemSeparator\n",
+        "from bandscope_analysis.separation import (\n"
+        "    AudioStemSeparator,\n"
+        "    PlayableStemArtifactSetReference,\n"
+        "    build_playable_stem_artifact_set_reference,\n"
+        "    materialize_playable_stem_artifact_set,\n"
+        ")\n",
+        "source-separation import",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    result: NotRequired[RehearsalSong]\n"
+        "    error: NotRequired[AnalysisJobError]\n",
+        "    result: NotRequired[RehearsalSong]\n"
+        "    error: NotRequired[AnalysisJobError]\n"
+        "    playableStemArtifactSet: NotRequired[PlayableStemArtifactSetReference]\n",
+        "analysis status contract",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    result: RehearsalSong | None = None,\n"
+        "    error: AnalysisJobError | None = None,\n"
+        ") -> AnalysisJobStatus:\n",
+        "    result: RehearsalSong | None = None,\n"
+        "    error: AnalysisJobError | None = None,\n"
+        "    playable_stem_artifact_set: PlayableStemArtifactSetReference | None = None,\n"
+        ") -> AnalysisJobStatus:\n",
+        "job-status builder signature",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    if error is not None:\n"
+        "        status[\"error\"] = error\n"
+        "    return status\n",
+        "    if error is not None:\n"
+        "        status[\"error\"] = error\n"
+        "    if playable_stem_artifact_set is not None:\n"
+        "        status[\"playableStemArtifactSet\"] = playable_stem_artifact_set\n"
+        "    return status\n",
+        "job-status artifact projection",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    return Path(temp_root) / \"stem-work-v1\" / f\"{digest}.npz\"\n\n\n"
+        "def _load_cached_analysis(path: Path) -> RehearsalSong | None:\n",
+        "    return Path(temp_root) / \"stem-work-v1\" / f\"{digest}.npz\"\n\n\n"
+        "def _materialize_playable_stem_artifact_reference(\n"
+        "    request: AnalysisJobRequest,\n"
+        "    audio_features: dict[str, Any] | None,\n"
+        ") -> PlayableStemArtifactSetReference | None:\n"
+        "    \"\"\"Publish aligned stem media and return only path-free status metadata.\"\"\"\n"
+        "    if request[\"sourceKind\"] != \"local_audio\" or audio_features is None:\n"
+        "        return None\n"
+        "    temp_root = request.get(\"tempRoot\")\n"
+        "    stem_work_path = _stem_work_arrays_path(request)\n"
+        "    stem_arrays = audio_features.get(\"stems\")\n"
+        "    if not temp_root or stem_work_path is None or not isinstance(stem_arrays, dict):\n"
+        "        return None\n"
+        "    try:\n"
+        "        native_artifact_set = materialize_playable_stem_artifact_set(\n"
+        "            stem_arrays=stem_arrays,\n"
+        "            sample_rate_hz=audio_features.get(\"sr\"),\n"
+        "            artifact_root=Path(temp_root),\n"
+        "            artifact_set_id=stem_work_path.stem,\n"
+        "        )\n"
+        "    except (OSError, ValueError):\n"
+        "        logger.warning(\n"
+        "            \"Playable stem artifact publication failed; stems remain unavailable.\"\n"
+        "        )\n"
+        "        return None\n"
+        "    return build_playable_stem_artifact_set_reference(native_artifact_set)\n\n\n"
+        "def _load_cached_analysis(path: Path) -> RehearsalSong | None:\n",
+        "playable artifact helper",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    cache_path = _analysis_cache_path(request)\n"
+        "    cache_status: AnalysisCacheStatus = \"disabled\" if cache_path is None else \"miss\"\n"
+        "    if cache_path is not None:\n"
+        "        cached_result = _load_cached_analysis(cache_path)\n"
+        "        if cached_result is not None:\n"
+        "            return [\n",
+        "    cache_path = _analysis_cache_path(request)\n"
+        "    feature_cache_paths = _feature_cache_paths(request)\n"
+        "    cache_status: AnalysisCacheStatus = \"disabled\" if cache_path is None else \"miss\"\n"
+        "    if cache_path is not None:\n"
+        "        cached_result = _load_cached_analysis(cache_path)\n"
+        "        if cached_result is not None:\n"
+        "            cached_artifact_reference = None\n"
+        "            if feature_cache_paths is not None:\n"
+        "                cached_features = _load_cached_local_audio_features(*feature_cache_paths)\n"
+        "                cached_artifact_reference = _materialize_playable_stem_artifact_reference(\n"
+        "                    request, cached_features\n"
+        "                )\n"
+        "            return [\n",
+        "analysis cache artifact restoration",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "                    cache_status=\"hit\",\n"
+        "                    result=cached_result,\n"
+        "                ),\n"
+        "            ]\n\n"
+        "    decode_label = (\n",
+        "                    cache_status=\"hit\",\n"
+        "                    result=cached_result,\n"
+        "                    playable_stem_artifact_set=cached_artifact_reference,\n"
+        "                ),\n"
+        "            ]\n\n"
+        "    decode_label = (\n",
+        "cached terminal artifact status",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "    feature_cache_paths = _feature_cache_paths(request)\n"
+        "    updates = [\n",
+        "    updates = [\n",
+        "duplicate feature-cache initialization",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "            return updates\n\n"
+        "    updates.append(\n"
+        "        _build_job_status(\n"
+        "            job_id=job_id,\n"
+        "            state=\"running\",\n"
+        "            requested_at=requested_at,\n"
+        "            progress_label=\"Building rehearsal cues\",\n",
+        "            return updates\n\n"
+        "    playable_stem_artifact_set = _materialize_playable_stem_artifact_reference(\n"
+        "        request, audio_features\n"
+        "    )\n\n"
+        "    updates.append(\n"
+        "        _build_job_status(\n"
+        "            job_id=job_id,\n"
+        "            state=\"running\",\n"
+        "            requested_at=requested_at,\n"
+        "            progress_label=\"Building rehearsal cues\",\n",
+        "fresh terminal artifact materialization",
+    )
+
+    api_text = replace_once(
+        api_text,
+        "            cache_status=final_cache_status,\n"
+        "            result=result,\n"
+        "        )\n"
+        "    )\n",
+        "            cache_status=final_cache_status,\n"
+        "            result=result,\n"
+        "            playable_stem_artifact_set=playable_stem_artifact_set,\n"
+        "        )\n"
+        "    )\n",
+        "fresh terminal artifact status",
+    )
+
+    API_PATH.write_text(api_text, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

From 8bfe72b0e25b4edd56a1b58474531adefb92adc0 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 10:34:16 +0900
Subject: [PATCH 13/14] chore(ci): remove self-modifying playable stem status
 repair

---
 .../workflows/playable-stem-status-repair.yml |  82 -------
 scripts/repairs/apply_playable_stem_status.py | 200 ------------------
 2 files changed, 282 deletions(-)
 delete mode 100644 .github/workflows/playable-stem-status-repair.yml
 delete mode 100755 scripts/repairs/apply_playable_stem_status.py

diff --git a/.github/workflows/playable-stem-status-repair.yml b/.github/workflows/playable-stem-status-repair.yml
deleted file mode 100644
index 60cf1d2e6..000000000
--- a/.github/workflows/playable-stem-status-repair.yml
+++ /dev/null
@@ -1,82 +0,0 @@
-name: playable-stem-status-repair
-
-on:
-  push:
-    branches:
-      - feat/playable-stem-audition-961
-    paths:
-      - scripts/repairs/apply_playable_stem_status.py
-      - .github/workflows/playable-stem-status-repair.yml
-
-permissions:
-  contents: write
-
-concurrency:
-  group: playable-stem-status-repair-${{ github.repository }}-1159
-  cancel-in-progress: true
-
-jobs:
-  repair-and-verify:
-    runs-on: ubuntu-latest
-    timeout-minutes: 45
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: true
-          fetch-depth: 0
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
-        with:
-          version: "0.8.6"
-          enable-cache: false
-      - name: Verify exact branch identity
-        shell: bash
-        run: |
-          test "$GITHUB_REF_NAME" = "feat/playable-stem-audition-961"
-          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
-      - name: Apply exact source repair
-        run: python scripts/repairs/apply_playable_stem_status.py
-      - name: Sync locked Python environment
-        run: uv sync --project services/analysis-engine --group dev --frozen
-      - name: Run focused playable-stem tests
-        run: |
-          uv run --project services/analysis-engine pytest \
-            services/analysis-engine/tests/test_playback_artifacts.py \
-            services/analysis-engine/tests/test_playback_artifact_exports.py \
-            services/analysis-engine/tests/test_playback_artifact_reference.py \
-            services/analysis-engine/tests/test_playback_artifact_status.py \
-            -q
-      - name: Run complete analysis-engine coverage
-        run: |
-          uv run --project services/analysis-engine pytest \
-            services/analysis-engine/tests \
-            --cov=services/analysis-engine/src/bandscope_analysis \
-            --cov-branch \
-            --cov-report=term-missing \
-            --cov-fail-under=100
-      - name: Run Python quality gates
-        run: |
-          uv run --project services/analysis-engine ruff check \
-            services/analysis-engine/src services/analysis-engine/tests
-          uv run --project services/analysis-engine ruff format --check \
-            services/analysis-engine/src services/analysis-engine/tests
-          uv run --project services/analysis-engine mypy \
-            services/analysis-engine/src
-          python -m compileall -q services/analysis-engine/src services/analysis-engine/tests
-          git diff --check
-      - name: Remove completed repair machinery
-        run: |
-          rm scripts/repairs/apply_playable_stem_status.py
-          rm .github/workflows/playable-stem-status-repair.yml
-      - name: Commit verified source repair
-        shell: bash
-        run: |
-          git config user.name "bandscope-repair-bot"
-          git config user.email "bandscope-repair-bot@users.noreply.github.com"
-          git add \
-            services/analysis-engine/src/bandscope_analysis/api.py \
-            services/analysis-engine/tests/test_playback_artifact_status.py \
-            scripts/repairs/apply_playable_stem_status.py \
-            .github/workflows/playable-stem-status-repair.yml
-          git diff --cached --quiet && { echo "No verified repair delta was produced." >&2; exit 1; }
-          git commit -m "feat(api): attach path-free playable stem status"
-          git push origin HEAD:feat/playable-stem-audition-961
diff --git a/scripts/repairs/apply_playable_stem_status.py b/scripts/repairs/apply_playable_stem_status.py
deleted file mode 100755
index cd31d3de2..000000000
--- a/scripts/repairs/apply_playable_stem_status.py
+++ /dev/null
@@ -1,200 +0,0 @@
-#!/usr/bin/env python3
-"""Apply the reviewed path-free playable-stem status integration exactly once.
-
-The script exists only to make a large-file source repair reviewable while the
-GitHub connector cannot apply a unified patch. It fails closed when any expected
-source marker has moved and is deleted by its owning workflow after verification.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-
-API_PATH = Path("services/analysis-engine/src/bandscope_analysis/api.py")
-
-
-def replace_once(source_text: str, old_text: str, new_text: str, label: str) -> str:
-    """Replace one exact source fragment or fail before mutating the file."""
-    occurrence_count = source_text.count(old_text)
-    if occurrence_count != 1:
-        raise RuntimeError(
-            f"Expected exactly one {label} source fragment, found {occurrence_count}."
-        )
-    return source_text.replace(old_text, new_text, 1)
-
-
-def main() -> None:
-    """Patch the analysis status boundary without changing unrelated source."""
-    api_text = API_PATH.read_text(encoding="utf-8")
-
-    api_text = replace_once(
-        api_text,
-        "from bandscope_analysis.separation import AudioStemSeparator\n",
-        "from bandscope_analysis.separation import (\n"
-        "    AudioStemSeparator,\n"
-        "    PlayableStemArtifactSetReference,\n"
-        "    build_playable_stem_artifact_set_reference,\n"
-        "    materialize_playable_stem_artifact_set,\n"
-        ")\n",
-        "source-separation import",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    result: NotRequired[RehearsalSong]\n"
-        "    error: NotRequired[AnalysisJobError]\n",
-        "    result: NotRequired[RehearsalSong]\n"
-        "    error: NotRequired[AnalysisJobError]\n"
-        "    playableStemArtifactSet: NotRequired[PlayableStemArtifactSetReference]\n",
-        "analysis status contract",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    result: RehearsalSong | None = None,\n"
-        "    error: AnalysisJobError | None = None,\n"
-        ") -> AnalysisJobStatus:\n",
-        "    result: RehearsalSong | None = None,\n"
-        "    error: AnalysisJobError | None = None,\n"
-        "    playable_stem_artifact_set: PlayableStemArtifactSetReference | None = None,\n"
-        ") -> AnalysisJobStatus:\n",
-        "job-status builder signature",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    if error is not None:\n"
-        "        status[\"error\"] = error\n"
-        "    return status\n",
-        "    if error is not None:\n"
-        "        status[\"error\"] = error\n"
-        "    if playable_stem_artifact_set is not None:\n"
-        "        status[\"playableStemArtifactSet\"] = playable_stem_artifact_set\n"
-        "    return status\n",
-        "job-status artifact projection",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    return Path(temp_root) / \"stem-work-v1\" / f\"{digest}.npz\"\n\n\n"
-        "def _load_cached_analysis(path: Path) -> RehearsalSong | None:\n",
-        "    return Path(temp_root) / \"stem-work-v1\" / f\"{digest}.npz\"\n\n\n"
-        "def _materialize_playable_stem_artifact_reference(\n"
-        "    request: AnalysisJobRequest,\n"
-        "    audio_features: dict[str, Any] | None,\n"
-        ") -> PlayableStemArtifactSetReference | None:\n"
-        "    \"\"\"Publish aligned stem media and return only path-free status metadata.\"\"\"\n"
-        "    if request[\"sourceKind\"] != \"local_audio\" or audio_features is None:\n"
-        "        return None\n"
-        "    temp_root = request.get(\"tempRoot\")\n"
-        "    stem_work_path = _stem_work_arrays_path(request)\n"
-        "    stem_arrays = audio_features.get(\"stems\")\n"
-        "    if not temp_root or stem_work_path is None or not isinstance(stem_arrays, dict):\n"
-        "        return None\n"
-        "    try:\n"
-        "        native_artifact_set = materialize_playable_stem_artifact_set(\n"
-        "            stem_arrays=stem_arrays,\n"
-        "            sample_rate_hz=audio_features.get(\"sr\"),\n"
-        "            artifact_root=Path(temp_root),\n"
-        "            artifact_set_id=stem_work_path.stem,\n"
-        "        )\n"
-        "    except (OSError, ValueError):\n"
-        "        logger.warning(\n"
-        "            \"Playable stem artifact publication failed; stems remain unavailable.\"\n"
-        "        )\n"
-        "        return None\n"
-        "    return build_playable_stem_artifact_set_reference(native_artifact_set)\n\n\n"
-        "def _load_cached_analysis(path: Path) -> RehearsalSong | None:\n",
-        "playable artifact helper",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    cache_path = _analysis_cache_path(request)\n"
-        "    cache_status: AnalysisCacheStatus = \"disabled\" if cache_path is None else \"miss\"\n"
-        "    if cache_path is not None:\n"
-        "        cached_result = _load_cached_analysis(cache_path)\n"
-        "        if cached_result is not None:\n"
-        "            return [\n",
-        "    cache_path = _analysis_cache_path(request)\n"
-        "    feature_cache_paths = _feature_cache_paths(request)\n"
-        "    cache_status: AnalysisCacheStatus = \"disabled\" if cache_path is None else \"miss\"\n"
-        "    if cache_path is not None:\n"
-        "        cached_result = _load_cached_analysis(cache_path)\n"
-        "        if cached_result is not None:\n"
-        "            cached_artifact_reference = None\n"
-        "            if feature_cache_paths is not None:\n"
-        "                cached_features = _load_cached_local_audio_features(*feature_cache_paths)\n"
-        "                cached_artifact_reference = _materialize_playable_stem_artifact_reference(\n"
-        "                    request, cached_features\n"
-        "                )\n"
-        "            return [\n",
-        "analysis cache artifact restoration",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "                    cache_status=\"hit\",\n"
-        "                    result=cached_result,\n"
-        "                ),\n"
-        "            ]\n\n"
-        "    decode_label = (\n",
-        "                    cache_status=\"hit\",\n"
-        "                    result=cached_result,\n"
-        "                    playable_stem_artifact_set=cached_artifact_reference,\n"
-        "                ),\n"
-        "            ]\n\n"
-        "    decode_label = (\n",
-        "cached terminal artifact status",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "    feature_cache_paths = _feature_cache_paths(request)\n"
-        "    updates = [\n",
-        "    updates = [\n",
-        "duplicate feature-cache initialization",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "            return updates\n\n"
-        "    updates.append(\n"
-        "        _build_job_status(\n"
-        "            job_id=job_id,\n"
-        "            state=\"running\",\n"
-        "            requested_at=requested_at,\n"
-        "            progress_label=\"Building rehearsal cues\",\n",
-        "            return updates\n\n"
-        "    playable_stem_artifact_set = _materialize_playable_stem_artifact_reference(\n"
-        "        request, audio_features\n"
-        "    )\n\n"
-        "    updates.append(\n"
-        "        _build_job_status(\n"
-        "            job_id=job_id,\n"
-        "            state=\"running\",\n"
-        "            requested_at=requested_at,\n"
-        "            progress_label=\"Building rehearsal cues\",\n",
-        "fresh terminal artifact materialization",
-    )
-
-    api_text = replace_once(
-        api_text,
-        "            cache_status=final_cache_status,\n"
-        "            result=result,\n"
-        "        )\n"
-        "    )\n",
-        "            cache_status=final_cache_status,\n"
-        "            result=result,\n"
-        "            playable_stem_artifact_set=playable_stem_artifact_set,\n"
-        "        )\n"
-        "    )\n",
-        "fresh terminal artifact status",
-    )
-
-    API_PATH.write_text(api_text, encoding="utf-8")
-
-
-if __name__ == "__main__":
-    main()

From 460cb9f1e4fa881b2c4df1a5f54f6453914f9172 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Fri, 4 Sep 2026 15:10:00 +0900
Subject: [PATCH 14/14] fix(separation): wire playable stem status artifacts

---
 .../src/bandscope_analysis/api.py             | 135 ++++++++++++++----
 1 file changed, 111 insertions(+), 24 deletions(-)

diff --git a/services/analysis-engine/src/bandscope_analysis/api.py b/services/analysis-engine/src/bandscope_analysis/api.py
index b376de293..6472ee23c 100644
--- a/services/analysis-engine/src/bandscope_analysis/api.py
+++ b/services/analysis-engine/src/bandscope_analysis/api.py
@@ -18,7 +18,13 @@
 from bandscope_analysis.roles import RoleExtractor
 from bandscope_analysis.sections import extract_sections
 from bandscope_analysis.sections.segmenter import segment_with_boundaries
-from bandscope_analysis.separation import AudioStemSeparator
+from bandscope_analysis.separation import (
+    CANONICAL_PLAYBACK_STEM_KINDS,
+    AudioStemSeparator,
+    PlayableStemArtifactSetReference,
+    build_playable_stem_artifact_set_reference,
+    materialize_playable_stem_artifact_set,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -86,7 +92,7 @@ class RangePayload(TypedDict):
 
 
 class HarmonyPayload(TypedDict):
-    """Typed harmony payload nested inside rehearsal results."""
+    """Typed harmony payload nested inside rehearsal roles."""
 
     chord: str
     functionLabel: str
@@ -128,7 +134,7 @@ class PartGraphNodePayload(TypedDict):
 
 
 class SectionTimeRangePayload(TypedDict):
-    """Typed timing range payload nested inside rehearsal sections."""
+    """Typed timing payload nested inside rehearsal sections."""
 
     start: int
     end: int
@@ -177,6 +183,7 @@ class AnalysisJobStatus(TypedDict):
     cacheStatus: NotRequired[AnalysisCacheStatus]
     result: NotRequired[RehearsalSong]
     error: NotRequired[AnalysisJobError]
+    playableStemArtifactSet: NotRequired[PlayableStemArtifactSetReference]
 
 
 class CachedAnalysisPayload(TypedDict):
@@ -1039,6 +1046,79 @@ def _build_local_audio_features(request: AnalysisJobRequest) -> dict[str, Any] |
     }
 
 
+def _playable_stem_artifact_set_id(
+    request: AnalysisJobRequest,
+    audio_features: dict[str, Any],
+) -> str:
+    """Derive a deterministic identity from project scope and exact separated samples."""
+    stems = audio_features.get("stems")
+    sample_rate = audio_features.get("sr")
+    project_id = request.get("projectId")
+    if not isinstance(stems, dict):
+        raise ValueError("Invalid playable stem features.")
+    if not isinstance(sample_rate, int) or isinstance(sample_rate, bool):
+        raise ValueError("Invalid playable stem features.")
+    if not isinstance(project_id, str) or not project_id:
+        raise ValueError("Invalid playable stem project identity.")
+
+    digest = hashlib.sha256()
+    digest.update(b"bandscope-playable-stems-v1\0")
+    digest.update(project_id.encode("utf-8"))
+    digest.update(b"\0")
+    digest.update(str(sample_rate).encode("ascii"))
+    for stem_kind in CANONICAL_PLAYBACK_STEM_KINDS:
+        stem_array = stems.get(stem_kind)
+        if not isinstance(stem_array, np.ndarray):
+            raise ValueError("Invalid playable stem features.")
+        contiguous_stem = np.ascontiguousarray(stem_array)
+        digest.update(b"\0")
+        digest.update(stem_kind.encode("ascii"))
+        digest.update(b"\0")
+        digest.update(contiguous_stem.dtype.str.encode("ascii"))
+        digest.update(b"\0")
+        digest.update(str(contiguous_stem.shape).encode("ascii"))
+        digest.update(b"\0")
+        digest.update(contiguous_stem.tobytes(order="C"))
+    return digest.hexdigest()
+
+
+def _materialize_playable_stem_artifact_reference(
+    request: AnalysisJobRequest,
+    audio_features: dict[str, Any],
+) -> PlayableStemArtifactSetReference | None:
+    """Publish local stem media and return only path-free status metadata."""
+    if request["sourceKind"] != "local_audio":
+        return None
+    temp_root = request.get("tempRoot")
+    if not temp_root:
+        return None
+
+    try:
+        native_artifact_set = materialize_playable_stem_artifact_set(
+            stem_arrays=audio_features.get("stems", {}),
+            sample_rate_hz=audio_features.get("sr"),
+            artifact_root=temp_root,
+            artifact_set_id=_playable_stem_artifact_set_id(request, audio_features),
+        )
+    except (KeyError, OSError, TypeError, ValueError):
+        logger.warning("Playable stem artifact publication failed; stems remain unavailable.")
+        return None
+    return build_playable_stem_artifact_set_reference(native_artifact_set)
+
+
+def _load_cached_playable_stem_artifact_reference(
+    request: AnalysisJobRequest,
+) -> PlayableStemArtifactSetReference | None:
+    """Rebuild playable media from reusable feature cache without rerunning separation."""
+    feature_cache_paths = _feature_cache_paths(request)
+    if feature_cache_paths is None:
+        return None
+    cached_features = _load_cached_local_audio_features(*feature_cache_paths)
+    if cached_features is None:
+        return None
+    return _materialize_playable_stem_artifact_reference(request, cached_features)
+
+
 def run_analysis_job_updates(
     job_id: str,
     payload: object,
@@ -1065,6 +1145,19 @@ def run_analysis_job_updates(
     if cache_path is not None:
         cached_result = _load_cached_analysis(cache_path)
         if cached_result is not None:
+            cached_final_status = _build_job_status(
+                job_id=job_id,
+                state="succeeded",
+                requested_at=requested_at,
+                progress_label=f"Analysis ready for {request['sourceLabel']}",
+                progress_stage="ready",
+                progress_percent=100,
+                cache_status="hit",
+                result=cached_result,
+            )
+            cached_artifact_reference = _load_cached_playable_stem_artifact_reference(request)
+            if cached_artifact_reference is not None:
+                cached_final_status["playableStemArtifactSet"] = cached_artifact_reference
             return [
                 _build_job_status(
                     job_id=job_id,
@@ -1075,16 +1168,7 @@ def run_analysis_job_updates(
                     progress_percent=95,
                     cache_status="hit",
                 ),
-                _build_job_status(
-                    job_id=job_id,
-                    state="succeeded",
-                    requested_at=requested_at,
-                    progress_label=f"Analysis ready for {request['sourceLabel']}",
-                    progress_stage="ready",
-                    progress_percent=100,
-                    cache_status="hit",
-                    result=cached_result,
-                ),
+                cached_final_status,
             ]
 
     decode_label = (
@@ -1213,18 +1297,21 @@ def run_analysis_job_updates(
         final_cache_status = (
             "stored" if _store_cached_analysis(cache_path, request, result) else "miss"
         )
-    updates.append(
-        _build_job_status(
-            job_id=job_id,
-            state="succeeded",
-            requested_at=requested_at,
-            progress_label=f"Analysis ready for {request['sourceLabel']}",
-            progress_stage="ready",
-            progress_percent=100,
-            cache_status=final_cache_status,
-            result=result,
-        )
+    final_status = _build_job_status(
+        job_id=job_id,
+        state="succeeded",
+        requested_at=requested_at,
+        progress_label=f"Analysis ready for {request['sourceLabel']}",
+        progress_stage="ready",
+        progress_percent=100,
+        cache_status=final_cache_status,
+        result=result,
     )
+    if audio_features is not None:
+        artifact_reference = _materialize_playable_stem_artifact_reference(request, audio_features)
+        if artifact_reference is not None:
+            final_status["playableStemArtifactSet"] = artifact_reference
+    updates.append(final_status)
     return updates