ChatMaestro · Scenarios · Experiment lifecycle

Clear a Run

Experimenter / Admin  Reclaim space from a finished run, from its row or its detail page: Cleanup keeps the scorecard, Purge removes everything (admin only), and the archive comes first unless you say otherwise.
Screens  Experiments — runs pane experiments-home.htmlRun detail run-detail.htmlConfirm confirm-cleanup-run.html · confirm-purge-run.html
Deletes  the heavy data chat_round · chat_round_candidate · message · run_enrollment(purge only) experiment_run · run_result
Writes  the archive object storage · key in audit_logwho did what, and whether an archive was taken audit_log
Key fields  the guard experiment_run.statewho may launched_by / experiment.created_bykept record run_result

1 · Given / When / Then

Human wording first; the exact table/field in mono.
Given
A run has finished: state is done or aborted. The person is an admin, or the experimenter who composed the study (experiment.created_by) or launched the run (launched_by).
When
They reach the run one of two ways: on the Experiments Screen, selecting the study lists its runs in the pane below, and each finished run's row carries Clean up and Purge beside the eye that opens it; or they open the Run-detail Screen, which has the same two buttons. Either way the same confirmation appears. It offers Archive first, ticked by default: the transcripts, every candidate answer, the scorecard and the run's conditions are written to storage as xlsx, csv, or json before anything is deleted. They may untick it to clear a botched run without an archive; that is a warned choice, and the acknowledgment changes to say the data cannot be recovered. Then they confirm the mode: Cleanup (reclaim the bulk, keep the record) or Purge (remove the run entirely, which only an admin can do).
Then
Cleanup deletes the heavy produced data: enrollments, exchanges and their candidate answers, operator messages, context-file links, and the run's audit entries. It keeps the experiment_run row and its run_result scorecard, so the analytics still work. Purge additionally removes the run itself, which cascades the scorecard away too. Neither touches the reusable definitions (the study, the model set-up, the group, the documents). One audit_log row records the mode, whether an archive was taken or declined, and the archive's object key.
deletes heavy children, and on purge, experiment_run and run_result  writes the archive, audit_log
Variations and exceptions
If…Then…
The run is running or pausedBoth actions are disabled on the row and refused by the server; finish or abort it first.
The archive write failsNothing is deleted. The dialog says why and offers Retry; the operator may instead untick Archive first and clear without one. An archive that was asked for and failed is never treated as consent to delete.
They untick Archive firstAllowed, so a botched run does not force an archive nobody wants. The acknowledgment changes to say the data cannot be recovered in any form, and the audit_log row records that no archive was taken.
An experimenter, not an admin, reaches for PurgeIt is disabled for them; an owning experimenter may Clean up but cannot remove the run and its scorecard.
The run was cleaned up alreadyClean up is disabled with a “cleaned up · scorecard kept” note — there is nothing left to reclaim; Purge stays available.
Acceptance test — Given a done run, When an owning experimenter clicks Clean up on its row in the Experiments Screen's runs pane and confirms with Archive first ticked, Then the archive exists in storage and its key is in the audit_log row, the exchanges, candidates, messages, and enrollments are gone, and experiment_run and run_result still exist so the comparison still renders; and When the archive write fails, Then no row was deleted and the dialog offers Retry; and When they untick Archive first and confirm the recovery warning, Then the delete proceeds and the audit_log row says no archive was taken; and attempting any of this on a running run is refused.

2 · The Journey, Screen by Screen

Two ways in, two guards, an archive that is a default rather than a wall, then a Cleanup-or-Purge choice.
Pick a finished run Experiments · runs pane, or Run detail Still running or paused? Blocked — finish it first (guard) Archive first? Confirm: cannot be recovered a warned choice · logged Write the archive to storage xlsx / csv / json · complete, every round Written? Nothing is deleted you are told why Cleanup or purge? Cleanup — keep the record run + scorecard survive Purge — admin only run + scorecard removed analytics still work gone for good yes no yes · the default no no retry yes proceed without one cleanup purge

3 · Behind the Scenes

The archive, the delete that depends on the mode, and the audit entry that records both.
Experimenter (or admin) Web app (confirm) Server (fly.io) Database (Postgres · RLS) Object storage (the archive) clear this finished run — from its row, or from Run detail (cleanup / purge) clear(run, mode, archive = yes | no, format) guard — state in (done, aborted)? · may this person do this mode? ok — else refused archive first — the default; declining it is a warned choice, and either way the audit entry says which read every round and candidate, the scorecard, and the run's conditions write the archive (xlsx / csv / json) written — the object key goes into the audit entry if the write FAILS: nothing is deleted; the operator is told, and may retry or clear without an archive delete heavy children (chat_round + candidates, message, run_enrollment, audit) purge only — remove experiment_run → cascades run_result · nulls issue.run_id INSERT audit_log — mode, archive taken or declined, object key done — space reclaimed
A dashed line is a reply. A failed archive deletes nothing and hands the decision back to the operator: retry, or clear without one. Purge adds the experiment_run removal that cascades the scorecard.

4 · In Plain English

Studies generate a lot of data: every exchange, every candidate answer from every model on every pass. Eventually you want that space back without losing what you learned.

You do not have to open a run to clear it. Pick the study on the Experiments screen, and its runs appear below with the clearing actions on each finished row; the run's own detail page has the same buttons for when you are already there.

Clearing a run comes in two strengths. Cleanup throws away the bulky raw material but keeps the run and its scorecard, which means your charts and comparisons keep working. That is the one most people want. Purge removes the run altogether, and only an admin can do it.

There are two safety rails. You cannot clear something that is still live. And by default ChatMaestro writes an archive first; if that write fails, nothing is deleted, and you are told and can try again. The archive is a default rather than a wall: a run that went wrong and holds nothing worth keeping can be cleared without one, after a plain warning that it will not be recoverable, and the record shows that you chose that.

Clearing a run only ever removes output. The study, the model set-up, the group, and your documents are reusable designs, and they survive untouched.

Fits the schema cleanly. The guard is experiment_run.state; the two modes differ only in whether experiment_run itself is deleted (which cascades run_result); the archive choice and the object key live in the audit_log row rather than in a column of their own. Clearing never touches a definition — the study, the model set-up, the cohort, the documents — and purging the last run that references one is what unlocks it for editing or deletion.