Restart API params can be destructive verify worker source
Forcing a partial pipeline stage in a self-hosted multi-stage processing tool, then trying to resume from the previous stage without losing the partial state
Self-hosted pipeline tools commonly expose a restart parameter on their process endpoint (e.g. POST /api/.../process?restart=sync|transcription|full) that LOOKS like just rewinding the state machine but often has destructive side effects the API surface does not advertise. In storyteller specifically, restart=transcription does not mean resume at the transcription stage — it means delete all existing transcription JSONs THEN restart at the transcription stage. After successfully forcing a partial sync via a DB hack (UPDATE readaloud SET current_stage=SYNC_CHAPTERS to bypass the API guard that prevents jumping back from a less-completed stage), the natural next call to resume the remaining work via restart=transcription wiped the 2 transcriptions we had just used for the partial sync. The aligned epub survived because it is written to a separate output path, but the source transcripts were deleted, forcing a full re-transcribe from scratch. The clean alternative is to update current_stage back manually in the DB AND trigger the worker without any restart parameter at all — the worker will just continue from whatever current_stage is set to and respect skip-if-exists logic for already-completed work.
Before calling any restart=<value> param on a long-running pipeline API, grep the worker source for delete_, rm, or unlink operations gated on that restart value. If found, the param erases artifacts as a side effect — use a DB update to set state directly and call the API without the restart param to avoid the erase. This rule applies broadly: restart often means delete+restart in pipeline tools, not just rewind.