Skip to content

fix(combine): refuse VTTs a run did not finish - #79

Merged
thatsrue merged 5 commits into
mainfrom
fix/review-74
Nov 16, 2026
Merged

thatsrue merged 5 commits into
mainfrom
fix/review-74

Conversation

@thatsrue

@thatsrue thatsrue commented Oct 31, 2026 •

Copy link
Copy Markdown
Collaborator

What changed

combobulator combine <session> (the glob path, with no explicit VTT list) now raises CombineError naming every VTT left by a run that failed or was interrupted, and writes nothing. The new pipeline_cache.is_vtt_unfinished decides from the VTT's folder alone: the track is refused when the folder holds a chunk checkpoint (<stem>_progress.jsonl), or a current-version (3) manifest without a vtt record naming the VTT. A folder with no manifest, or a manifest from an older cache version, predates these records and is combined as before, unchecked. Batch runs are unchanged: they pass the exact VTTs they produced. AGENTS.md (the "Partial transcription is a failure" invariant) says how both kinds of session behave.

A run recorded complete also removes any chunk checkpoint, including one an interrupted run left that this run never read (a silent track after a VAD or audio change), so combine does not refuse its finished VTT.

Why

When some chunks fail, whisper still writes the track's VTT and only process_file raises, after the write. A manual combine, which session-env tells the owner to run after editing labels, globbed every *.vtt and merged that transcript with gaps without an error.

Review follow-up: the first version required a vtt record, so it also refused sessions made before cache version 3 (no manifest, or a version 1 or 2 manifest), which finished but have no such record. Version 3 brought both the per-stage records and the chunk checkpoint (407b74e), and every finished version 3 run writes the vtt record, so those marks tell a failed or interrupted run apart from an old session. No override flag is added: with the old-session case handled, a refused track is one whose run really did not finish, and rerunning it is the fix.

Left out: the stale-sibling scenario (two folders matching one username, e.g. 3-cadderly and 7-cadderly, both match as whole tokens). A manual combine merges both. Refusing that would also refuse a session that really has two tracks for one speaker, which batch runs accept, so it needs a decision on whether two tracks per username are supported. It is not changed here. The check also cannot compare fingerprints with the current config, because a manual combine has no input audio, and a version 3 session folder moved to another path is refused because the record names absolute paths.

Closes #74

How you checked it

  • Merged with main (v0.5.0); scripts/check (lock, pins, ruff, pyrefly, full pytest with slow tests, build) ok at c5e2eb7; test_a_finished_run_clears_a_checkpoint_it_did_not_use fails without the pipeline change

  • test_glob_refuses_a_track_whose_run_did_not_finish (tests/test_combine.py), interrupted and failed-chunk cases: both fail with combine.py from main, pass with the fix.

  • test_glob_combines_a_track_from_before_stage_records, no manifest and a version 2 manifest: both fail on the previous head of this branch, pass now.

  • make lint, make typecheck, make test-fast (300 passed, 9 deselected): exit 0.

  • CI's python -m build not run locally: build is not installed in the venv; the change touches no packaging.

  • Slow inference tests not run: the change is in combine only, outside the audio pipeline.

  • A bug fix comes with a test that fails without it

  • Docs match how it works now

  • No secrets or private information

@thatsrue

Copy link
Copy Markdown
Collaborator Author

Not ready to merge. The fresh review found that combine now refuses sessions with a manifest but no vtt record, including older sessions made before this check. It needs to tell an old session apart from a failed or interrupted run, or offer an explicit override, and AGENTS.md needs to say how old sessions behave.

Refuse a VTT only on the marks a failed or interrupted run leaves: a
chunk checkpoint, or a current-version manifest without a vtt record
naming it. A folder with no manifest, or one from an older cache version,
is combined as before.
A run that completes without chunk inference (a silent track after a VAD or audio change) left an interrupted run's <stem>_progress.jsonl, so combine refused its finished VTT and later runs hit the cache without clearing it. Remove the checkpoint once the completion record is written.
@thatsrue
thatsrue merged commit f44022a into main Nov 16, 2026
4 checks passed
@thatsrue
thatsrue deleted the fix/review-74 branch November 16, 2026 21:12
@thatsrue thatsrue mentioned this pull request Nov 16, 2026
2 of 3 tasks
thatsrue added a commit that referenced this pull request Nov 16, 2026
## What changed

- `pyproject.toml`: version 0.5.1, with `uv.lock` relocked to match. The tag `v0.5.1` goes on this PR's merge commit.

Since v0.5.0:
- `combobulator combine` on the glob path refuses VTTs a failed or interrupted run left, and a run recorded complete clears any chunk checkpoint (#79).
- Docs: torchaudio 2.11 does not cap torch; comments name the current pins (#70).

## Why

The owner asked to release these and move runewright's pin to them. Batch runs pass combine the exact VTTs they produced, so the D&D pipeline's transcripts do not change; it is proven on a real transcription on the Mac's GPU before the pin moves.

No issue: chore

## How you checked it

- `uv sync --locked --extra dev`, then `scripts/check`: 0 (lock, pins, ruff, pyrefly, pytest with real Whisper and VAD inference, build).

- [ ] A bug fix comes with a test that fails without it
- [x] Docs match how it works now
- [x] No secrets or private information
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Manual combine merges partial or stale VTTs without a check

1 participant