docs/SUPERVISED_EXPORT_AND_FORCE_ONSET.md

# Supervised export and force-onset workflow

Last updated: 2026-05-12

## Purpose

The batch extraction manifest is immutable. Interactive edits are stored in `supervision_state.json`. This pass adds the missing rendering step that turns those semantic edits into new downloadable artifacts without rerunning Demucs or onset detection.

```text
manifest.json + review/hits/*.wav + supervision_state.json
→ supervised/manifest.json
→ supervised/samples/*.wav
→ supervised/reconstruction.mid
→ supervised/target_reconstruction.wav
→ supervised/reconstruction.wav
→ supervised/sample-pack.zip
```

## Implemented features

| Feature | Status | Files |
|---|---:|---|
| Edited-state export | Implemented | `supervised_export.py`, `POST /api/jobs/{job_id}/export` |
| Suppressed-hit exclusion | Implemented | Export ignores hits with `suppressed=true`. |
| Favorite/pinned representative export | Implemented | Export honors `representative_hit_id` / favorite hits before quality scoring. |
| Force-onset from existing stem audio | Implemented | `POST /api/jobs/{job_id}/hits/force-onset` |
| Forced-hit review WAV writing | Implemented | `review/hits/hit_NNNNN_<label>_forced.wav` |
| Suppressed-hit restore | Implemented | `POST /api/jobs/{job_id}/hits/{hit_id}/restore` |
| Exact suggestion diff preview | Implemented | `suggestion.diff` in state responses and UI diff button. |
| UI add-onset mode | Implemented | Toggle in supervision header; waveform clicks add forced hits. |
| UI edited export downloads | Implemented | Edited ZIP/MIDI/target-reconstruction/full-context-reproduction links render after export. |

## Export behavior

The supervised export builds clusters from current semantic state:

1. Skip suppressed hits.
2. Load hit audio from each hit's `file` path under the job output directory.
3. Sanitize cluster labels for output filenames.
4. Preserve forced hits and moved/pulled hits through current cluster membership.
5. Pick representatives from semantic `representative_hit_id` or favorite hits first.
6. Quality-score representatives only for unpinned clusters.
7. Write edited samples, MIDI, target reconstruction WAV, full-context reproduction WAV, ZIP, and `supervised/manifest.json`.
8. Append a `supervised.exported` event and `latest_export` entry to `supervision_state.json`.

The original `manifest.json`, original `sample-pack.zip`, and original `samples/*.wav` are not modified.

## Force-onset behavior

`POST /api/jobs/{job_id}/hits/force-onset` requires a completed run with `stem.wav`.

Body:

```json
{
  "onset_sec": 0.123,
  "duration_ms": 160,
  "target_cluster_id": "cluster:0",
  "label": "snare"
}
```

Rules:

- `onset_sec` is required.
- `duration_ms` is optional. If omitted, the system slices until the next active onset or a bounded default duration.
- `target_cluster_id` is optional. If omitted, a new user cluster is created.
- `label` is optional. If omitted, the current rule-based classifier labels the slice.
- A short fade-out is applied to avoid clicks.
- The forced hit is marked `source="forced"`, `explicit=true`, and `review_status="accepted"`.

## Suggestion diffs

Open suggestions now include exact previews:

```json
{
  "type": "move-hits",
  "affected_hit_count": 3,
  "hits": [
    {
      "hit_id": "hit:00007",
      "from_cluster_label": "bright_1",
      "to_cluster_label": "snare_user_1",
      "before_suppressed": false,
      "after_suppressed": false
    }
  ],
  "clusters_before": {},
  "clusters_after": {}
}
```

The frontend exposes this through the `Diff` button in the suggestion inbox.

## Validation

Covered by:

```bash
python3 scripts/test_supervised_export_and_force_onset.py
```

This test verifies:

- suppression and restore,
- forced-hit creation and download,
- suggestion diff presence when suggestions exist,
- supervised export creation,
- artifact download URLs for edited ZIP/MIDI/reconstruction,
- latest export state metadata.


## Reproduced-audio update

Supervised export now mirrors the batch export audio model:

- `supervised/target_reconstruction.wav` is the edited sample-triggered target layer.
- `supervised/reconstruction.wav` is the edited full-context reproduced mix.
- The full-context mix reuses the original run’s `context_bed.wav`, then adds the edited target reconstruction.

This keeps the original batch artifacts immutable while making edited exports useful for listening inside the whole track context.