Ops Prelabel Review and Publish

This guide covers the Ops flow from prelabel run selection to immutable published revisions.

1) Open the run and start review

1. Go to Ops > Prelabels.
2. Filter by workspace, media, status, and capability.
3. Click Review for ball_detection or player_detection.

Routing behavior is deterministic:

• If an active draft exists for (workspace, media, capability), Ops opens that draft.
• Otherwise, Ops creates a draft and opens it.

2) Edit in the review viewer

• Ball detection: point tool (add/move/delete).
• Player detection: bbox tool (add/move/resize/delete).
• Frame flags (v1):
  • bad_frame
  • needs_human_review
  • false_positive_heavy
  • false_negative_suspected

If a frame thumbnail is missing, the viewer shows a deterministic placeholder and disables overlay editing for that frame.

3) Autosave and conflict handling

• Edits autosave as full draft payloads.
• If the draft version is stale (for example, another tab saved newer changes), save fails with:
  • 409 DRAFT_VERSION_CONFLICT

When this happens, reload the latest draft before continuing.

4) Frame review playbook

Use this simple rule:

• If the correct annotation is clear, edit it.
• If the frame is still risky or ambiguous after editing, add one or more frame flags.

When to edit:

• Ball detection
  • move the point to the real ball,
  • delete fake extra ball points,
  • add a missing ball point when the ball is clearly visible.
• Player detection
  • move or resize obviously wrong boxes,
  • delete clear false positives,
  • add clearly missing player boxes.

When to use frame flags:

• bad_frame
  • The frame itself is poor quality: blur, motion smear, occlusion, broken frame, or unusable camera cut.
• needs_human_review
  • You are still uncertain after your best effort and want explicit follow-up.
• false_positive_heavy
  • The model produced many extra detections that are not real objects of interest.
• false_negative_suspected
  • Real objects appear to be missing from the predictions.

Use both edit + flag when needed:

• fix what is obvious,
• then add a flag if the frame still carries quality or review risk.

5) Manually approve a scoped label pack

In review mode, the Scoped label packs table shows packs for the current (workspace, media, capability) scope.

Use Approve when:

• validation_status = passed
• review_status != approved

Approval requires a non-empty reason in the confirmation modal.

After approval succeeds:

• the scoped row updates to approved
• publish candidates refresh automatically
• the newly approved pack is selectable in the Publish pack dropdown without reloading the page

If approval fails, the viewer remains open and shows a deterministic inline error code/message.

6) Publish a reviewed pack

Publish creates an immutable approved revision for the current review target.

Before publishing:

• make sure the draft reflects the review you want,
• wait for autosave to return to a healthy state (prefer Autosave: saved),
• if an approved scoped label pack already exists, select the one you want to publish,
• if no publish candidates exist yet, first publish will create the initial scoped label pack from the reviewed draft automatically.

Publish flow:

1. Open the review modal for a capability.
2. Finish edits and optional frame flags.
3. Confirm autosave is healthy.
4. If needed, use Scoped label packs to approve an existing validation-passed pack.
5. If Publish pack shows approved candidates, select the one you want to publish.
6. If Publish pack shows that first publish will create the initial label pack, leave the selector as-is.
7. Click Publish.

Notes:

• Publish uses the reviewed draft content as the source of truth.
• If you selected an approved scoped pack, Publish uses that pack.
• If no approved scoped pack exists yet, Publish creates the first scoped pack from the reviewed draft and then publishes the immutable revision.
• Ball first publish uses self-contained draft geometry. Existing reviewed ball points keep their stored size metadata, and newly added ball points use a deterministic system default size when no inherited size exists.
• If the exact same content was already published, publish returns a deterministic no-op instead of creating a duplicate revision.
• If autosave is stale or failed, resolve that before publishing.

Common publish outcomes:

• PUBLISH_SUCCESS
  • a new immutable revision was created
• NO_OP_ALREADY_PUBLISHED
  • the same content already exists as the latest approved revision
• STALE_DRAFT_VERSION
  • the draft changed before publish completed
• VALIDATION_HARD_FAIL
  • blocking validation errors must be fixed first
• RESET_DRAFT_REQUIRED
  • older incompatible ball draft must be reset and rebuilt from the current source prelabel pack
• WARNINGS_REQUIRE_OVERRIDE
  • publish warnings require explicit override
• OVERRIDE_FORBIDDEN
  • the current user cannot override publish warnings
• PUBLISH_LOCK_CONFLICT
  • another publish happened concurrently

If publish shows a reset-required error for ball review:

1. Click Reset draft in the inline error banner.
2. Wait for the viewer to reload from the current source prelabel pack for that capability.
3. Re-apply the review edits you still want.
4. Wait for autosave to complete, then publish again.

Reset affects only the current review draft for that (workspace, media, capability) scope.

7) Publish outcomes

Publish creates immutable approved revisions.

Deterministic outcomes:

• PUBLISH_SUCCESS: a new revision was created.
• NO_OP_ALREADY_PUBLISHED: identical content already exists for the same review target.

Deterministic publish failure codes include:

• STALE_DRAFT_VERSION
• PUBLISH_LOCK_CONFLICT
• VALIDATION_HARD_FAIL
• WARNINGS_REQUIRE_OVERRIDE
• OVERRIDE_FORBIDDEN
• AUDIT_PERSIST_FAILED
• STORAGE_READ_FAILED
• STORAGE_WRITE_FAILED

8) Revision history

After publish, use revision history to inspect:

• revision number and timestamp
• content hash
• validation/provenance metadata
• revision diff summary
• dataset eligibility state

Revision History layout:

• Revision
  • immutable revision number
• Diff
  • deterministic added/removed/modified summary
• Provenance
  • published timestamp
  • actor / published-by user
  • pack SHA
  • source lineage
  • draft/version metadata
  • validation and artifact metadata
• Dataset eligibility
  • Reviewed
  • Approved
  • Revoked

Dataset eligibility actions:

• Approve for dataset
  • available only when the published revision's label pack is lifecycle-approved and validation-passed
• Revoke
  • available only for currently dataset-approved revisions
  • revocation requires a non-empty reason

Conflict handling:

• If another operator changes dataset eligibility first, the history view shows a deterministic conflict message and refreshes to the latest state.
• Retry only after the refreshed row shows the latest eligibility status and version.

9) Source lineage in runs and review

Ops prelabel screens also show where a draft or revision came from.

Where lineage appears:

• Ops Prelabels (runs list): Outcome lines show lineage per capability.
• Label Review Series: Active draft rows show active draft source lineage.
• Revision History: Each published revision shows source lineage in provenance.

Lineage values:

• Pack-id: <id>
  • The draft/revision is seeded from a prelabel pack.
  • IDs are compact by default, full ID is available on hover, and copy action is available.
• Manual
  • The draft/revision came from a manual or edit-first path, not from a prelabel pack.
• Legacy/Unknown
  • Historical record where deterministic lineage was not captured at creation time.

How to verify consistency:

1. Open a run in /ops/prelabels.
2. Note lineage shown in Outcome for a capability.
3. Open Label Review Series and Revision History for the same capability.
4. Confirm lineage label (Pack-id / Manual / Legacy/Unknown) matches across views.

If lineage is unexpectedly missing for an active draft, reopen the review entry from the run page to re-seed lineage from that run capability.