Ops Prelabel Review and Publish

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

Generate prelabel runs

Ball and player detection are the default prelabel capabilities. If a new run is started without explicitly selecting capabilities, Ops requests only ball and player outputs.

jersey_recognition is explicit opt-in. When the backend exposes it in the run capability options, the run form shows a Jersey checkbox. Select it only when you want jersey review artifacts for that media.

Jersey availability is controlled by the backend kill switch JERSEY_PRELABEL_ENABLED, which defaults to true. If it is disabled, jersey run and retry controls are hidden or unavailable even if the operator would otherwise have access to Ops prelabels.

Legacy jersey packs may expose jersey_predictions_uri, a frame-level prediction artifact handle. The renewed Jersey review flow uses jersey_tracklet_prelabel_review instead: one proposed jersey number per source tracklet plus bounded supporting, ambiguous, and not-visible crop evidence. Both are separate from match/session runtime artifacts.

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, player_detection, or an eligible jersey_recognition pack.

Jersey prelabel runs may appear in the run list when enabled. Renewed Jersey review is tracklet-centric: review the proposed jersey number for a tracklet, inspect the supporting crop evidence, and mark crop-level verdicts such as usable, wrong crop, wrong player, or bad geometry. Tracklet decisions and crop verdicts are saved as draft/review state. They do not mutate the source tracklet artifact or an approved label pack until a later publish step maps them into training truth.

Routing behavior is deterministic for currently routed review artifacts:

• If an active draft exists for (workspace, media, capability), Ops opens that draft.
• Otherwise, Ops creates a draft and opens it.
• Renewed Jersey review opens only from the generated jersey_tracklet_prelabel_review artifact.
• Legacy frame-level Jersey routes and jersey_predictions draft payloads are unsupported in the renewed flow and show a bounded legacy-unsupported state.
• If Jersey tracklet review generation is disabled or unavailable, Jersey review is withheld with a bounded unavailable state. Ball and player review entries remain available from their detection artifacts in the same run.

2) Edit in the review viewer

• Ball detection: point + training bbox tool (add/move/delete point, resize bbox).
• 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 center,
  • drag bbox corners to resize the training box when the size is wrong,
  • delete fake extra ball points,
  • add a missing ball point when the ball is clearly visible.
  • the point and training bbox stay coupled: moving the point recenters the bbox, and resizing the bbox recenters the point.
• Player detection
  • move or resize obviously wrong boxes,
  • delete clear false positives,
  • add clearly missing player boxes.
• Jersey recognition
  • accept a clear proposed jersey number for the selected tracklet,
  • correct the tracklet number when the evidence supports a different number,
  • mark no-readable-crop or ambiguous tracklets as unknown,
  • reject wrong-player, wrong-crop, or bad-geometry tracklets.
  • mark individual crops as usable, exclude, wrong crop, wrong player, or bad geometry.
  • crop geometry is display-only; mark bad geometry instead of editing it.
  • if more than five crops are marked usable/relevant, a later publish step selects the top five evidence crops and sets evidence_truncated=true.

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 creates a validated scoped label pack from the reviewed draft; approve that scoped pack before reusing it later from the dropdown.

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 a validated label pack, leave the selector as-is.
7. Click Publish.
8. If Publish created a new scoped pack, use Scoped label packs to approve it before expecting it to appear as a reusable publish candidate.

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 in validated state and then publishes the immutable revision.
• A newly created validated pack is not immediately reusable from the Publish pack dropdown; approve it first.
• 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.
• Jersey tracklet publish maps accepted/corrected tracklets to jersey_labels_json_v1.labels[] and maps unknown/rejected tracklets to review_decisions[]. The label-pack format keeps at most five evidence crops per label or review decision; if more eligible evidence exists, publish sets evidence_truncated=true. Extra crop verdict detail remains in review draft history rather than the immutable v1 pack.
• If the exact same content was already published, publish returns a deterministic no-op instead of creating a duplicate revision.
• When publish validation fails, the inline error may include frame and annotation context when the backend returns it.
• 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

Jersey label-pack stats expose bounded aggregate counts for operational checks: labels, geometry labels, review decisions, unknown/rejected decisions, evidence items, and evidence truncation. They do not include crop IDs or storage handles.

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: Scope shows the media name alongside compact workspace/media IDs, and 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.