Content trigger (not one directory). Load when a diff does any of:
-
Coordinate frames stay consistent. Every geometry channel of a detection — xyxy, mask, data[POLYGON_KEY_IN_SV_DETECTIONS], keypoints_xy — is transformed together by the same shift/scale. sv_detections_to_root_coordinates and scale_sv_detections in common/utils.py are the canonical seam: both apply the shift/scale to POLYGON_KEY_IN_SV_DETECTIONS after xyxy/mask (polygon shift in root recovery #2473; polygon scale #1268). Failure mode: masks/polygons drawn or uploaded at the wrong location, invisible to a test that only checks xyxy.
-
Response shape is a contract. Block outputs match the manifest's declared keys on every branch, including empty/zero-area. Guard len(detections) == 0 before any index-0 ([0]) access into metadata arrays. (dynamic_crop's early return emitted {"crops": None} but omitted "predictions" — #2346.)
-
Serialization round-trips the promised representation. serialise_sv_detections/serialise_rle_sv_detections/mask_to_polygon in common/serializers.py are the response-shape contract: masks emit the polygon/RLE the schema promises with int rounding (.astype(float).round().astype(int).tolist(), #1236) and prefer a stored POLYGON_KEY_IN_SV_DETECTIONS over regenerating via mask_to_polygon; keypoints emit class, class_id, confidence, x, y per point. RLE ↔ dense mask abstraction lives in inference_models/models/base/instance_segmentation.py (supported_mask_formats, coco_rle_masks_to_numpy_mask); the enforce_dense_masks_in_inference_models toggle is a manifest bool field on the instance-segmentation v1/v2 blocks (core_steps/models/roboflow/instance_segmentation/{v1,v2}.py), threaded into the request — not an adapter function (#2384, #2260, #2484).
-
Reference-backend parity. ONNX / TRT / TorchScript paths and legacy-inference vs inference_models paths produce the same predictions within numerical tolerance. When one backend's post-processing changes, every sibling changes too — e.g. the keypoint slice offset fix touched yolov8_key_points_detection_onnx.py, _trt.py, _torch_script.py together (#1626). Failure mode: a model "works" but boxes/scores subtly differ per backend.
-
Threshold / activation / index conventions justified against the reference. New default threshold, sigmoid vs raw logits, background/class index offset, or tensor column slice must match the reference implementation and be config-gated if it shifts scores. The keypoint slice is fixed at image_detections[:, 6:] in run_nms_for_key_points_detection (inference_models/models/common/roboflow/post_processing.py) — not 5 + num_classes (#1626). The YOLO-ultralytics mask default mask_binarization_threshold was set to 0.5 via env const INFERENCE_MODELS_YOLO_ULTRALYTICS_DEFAULT_MASK_BINARIZATION_THRESHOLD (#2212, #2217); note align_instance_segmentation_results's own binarization_threshold parameter default stays 0.0. Class remapping / background-index off-by-one bit RF-DETR seg (#2075, #1619, #1920, #1590). Perspective anchor/extension math (#1234, #1287, #1310, #972). Preprocessing must not silently swap BGR/RGB or introduce PIL-vs-CV2 resize drift.
-
Array shape/dtype discipline in sv.Detections. Ragged object-dtype arrays break supervision's indexing/comparison. add_inference_keypoints_to_sv_detections in common/utils.py pads keypoints to fixed-shape numeric arrays (padded_xy/padded_conf/padded_class_id, uniform max length) rather than dtype=object (#2170).
-
supervision bumps are load-bearing. On any version change, verify annotators, mask_to_polygons, keypoint edge maps, and indexing still behave (#2467, #1725, #1424/#1425 pin history).
-
Flag parity & native-metadata integrity (#2357). Four checks whenever a diff touches tensor-native prediction handling:
- Flag-off equals pre-tensor
main, byte for byte. Any numpy-path behavior edit riding a tensor PR — even a genuine bug fix — is a finding: it must ship as its own change, not as a silent flag-off divergence (semantic-seg confidence-mask relocation lesson: reverted and re-landed separately).
- Cross-flag payload parity. The same workflow serialized under both flag directions should produce the same shape; kind-order divergence between siblings flips mask encodings (
points vs rle_mask) per deployment flag. When a payload difference is a deliberate contract, it must be a documented decision, not a manifest accident.
- Class-name integrity in native metadata. Native detections carry a per-image
class_id→name map in image_metadata plus per-box name overrides in bboxes_metadata; merging/concatenating detections from models with COLLIDING class ids is last-wins on the map — rows silently adopt another model's class name and downstream class-based logic acts on wrong names (consensus/rollup lesson; a raise_on_class_name_conflict knob exists but defaults to override-with-warning). Review any metadata-merge path for this.
- Golden-response tolerances are GPU-generation-sensitive. Expected-response fixtures with sub-pixel
atol (0.1 px) recorded on one GPU generation fail on another with SYSTEMATIC sub-pixel drift across every test — before calling a regression, check detection counts, row ordering, and classes first; matching structure + consistent tiny deltas = numerics, not a product bug (and a runner-hardware upgrade will require golden/tolerance refresh).
