Re-run detection on an existing file (first-class re-analyze)

[martsokha]

Summary

Let a user deliberately re-run the detection step on a file that has already been analyzed — e.g. after the pipeline's policies/labels change, after an engine/model upgrade, or when the first run failed — and get a fresh run without deleting and re-uploading the file.

Current state

• It's already technically possible, just not first-class. create_pipeline_run (crates/nvisy-server/src/handler/pipeline_runs.rs) mints a new run each call for a given { pipeline, file_id }; there is no uniqueness constraint preventing multiple runs per file. Calling it again does start a new detection.
• Idempotency-Key replays — a repeated key returns the existing run instead of analyzing again (lines ~87-97). So the safety valve against accidental dupes exists, but there is no explicit "re-run" intent.
• Run statuses: Running, Analyzed, Completed, Failed, Cancelled (pipeline_run_status.rs). A file can therefore accumulate multiple runs over time.

So the gap is UX/semantics, not raw capability: re-running is an implicit consequence of hitting the endpoint again, not a named, intentional action, and there's no clear model for how prior runs relate to a re-run.

Proposal

Make re-analyze an explicit, discoverable action:

1. Endpoint/affordance — a clear "re-run detection" on a file (or on a prior run), that starts a new detection run against the chosen pipeline reusing the existing create_pipeline_run path.
2. Run history — treat runs as a versioned history per (file, pipeline): list prior runs, mark the latest, keep older analyses (or prune per retention). The analysis blobs already live in the intermediates bucket keyed per run.
3. Clarity on what's reused vs recomputed — a re-run re-detects from the source file (does NOT reuse the prior Audit), so it picks up current policies/labels and engine version.

Open questions

• Trigger shape — re-run keyed off the file (pick pipeline again) or off a prior run (re-use its pipeline)? Possibly both.
• Superseding — does a new run supersede the prior one (latest wins for redact), or can multiple analyzed runs coexist and the user picks which to redact from? Affects the redact lookup.
• In-flight guard — block starting a re-run while a Running run for the same (file, pipeline) is in progress? (Cheap conflict check vs. allowing concurrent runs.)
• Idempotency — re-run is intentionally NOT idempotent with the prior run; make sure the affordance doesn't send a stale Idempotency-Key that would replay the old run instead of starting a new one.
• Cost/telemetry — re-runs re-incur detection cost; emit an activity event and surface who triggered it.
• Interaction with detect-on-upload (Start detection on upload: optionally select a pipeline to run immediately #197) and per-run webhook events (pipeline:run.*) — a re-run should emit the same lifecycle events.

Out of scope

• Diffing two runs' findings (worth a separate issue if wanted).

🤖 Generated with Claude Code