phenotypic.sdk_.record_rejection

phenotypic.sdk_.record_rejection(record: Mapping[str, object], *, work_id: str, dataset: str, image_stem: str) → str | None

Return why record cannot certify this image, or None.

The single implementation of per-image record validity, and the one reason this function exists rather than the check being written twice. _cli_completion.valid_image_success and _run_state’s deep path both ask it, exactly as they both asked marker_rejection() of the marker this record replaces. Splitting them again – after gate finding IMPL-F3 spent a whole increment merging them – would look like progress in a diff and be the same defect returning.

A sentence rather than a bool, because the sentence lands in ImageState.reason and is what makes “which images are missing, and why?” answerable without re-running anything.

Two clauses are worth reading twice:

• The ``work_id`` comparison is skipped for a migrated record (U-10). A pre-markers tree never had a work_id to match, so comparing it unconditionally would reject every migrated image. The relaxation is per-record and read through record_provenance(), so an absent or unrecognized value keeps the fence.

• A record with no artifacts certifies nothing (CAN-23), and after the collapse that is one missing check away from being wrong. A Stage-2 worker writes stages.stage2 and no artifacts into this same file; before the collapse the two facts lived in two trees and mistaking one for the other was impossible.

Parameters:

• record (Mapping[str, object]) – The record mapping, as returned by read_image_record().

• work_id (str) – The identity this image is expected to carry.

• dataset (str) – The dataset the caller is asking about.

• image_stem (str) – The image stem the caller is asking about.

Returns:

A sentence naming the first failed clause, or None when the record may certify this image. Artifact contents are not checked here – that is fenced_artifact_path’s half, kept separate so a caller asking “is this record even about my image?” pays no I/O.

Return type:

str | None