repzo 1.0.292 → 1.0.293

package/lib/types/index.d.ts

@@ -3,7 +3,7 @@ import { SalesAnalyticsFieldAccumulators, SalesAnalyticsReportProjectionKey, Sal
 export interface Params {
     [key: string]: any;
 }
-export type ReportType = "sales-analytics" | "retail-execution-gallery" | "from-v2-gallery";
+export type ReportType = "sales-analytics" | "retail-execution-gallery" | "from-v2-gallery" | "object-detection-metrics" | "object-detection-segments";
 export interface Data {
     [key: string]: any;
 }
@@ -20611,6 +20611,4535 @@ export declare namespace Service {
         }
         export {};
     }
+    namespace AiObjectDetectionDataset {
+        interface Data {
+            _id: StringId;
+            /** Unique per namespace (compound unique index on `company_namespace` + `name`). */
+            name: string;
+            /** `ai-object-detection-label` ids that make up the dataset. */
+            dataset_labels: StringId[];
+            /** `ai-object-detection-model` used by default when training/predicting on this dataset. */
+            default_model?: StringId;
+            /** Pinned `ai-object-detection-model-version`. `null`/absent = "latest" → resolved to the model's `current_model_version` at inference time. */
+            default_model_version?: StringId | null;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "dataset_labels" | "default_model" | "default_model_version";
+        /** Populated refs are emitted under `<field>_populated`; the original field keeps the id(s). */
+        interface DataWithPopulatedKeys extends Data {
+            dataset_labels_populated?: AiObjectDetectionLabel.Data[];
+            default_model_populated?: AiObjectDetectionModel.Data | null;
+            default_model_version_populated?: AiObjectDetectionModelVersion.Data | null;
+        }
+        interface CreateBody {
+            name: string;
+            dataset_labels: StringId[];
+            default_model?: StringId;
+            /** Version `_id` to pin, or `"latest"` / `""` / `null` to track the model's `current_model_version` (the sentinel is normalized to `null` server-side, never cast to an ObjectId). */
+            default_model_version?: StringId | "latest" | null;
+            company_namespace?: string[];
+        }
+        interface UpdateBody {
+            name?: string;
+            dataset_labels?: StringId[];
+            default_model?: StringId;
+            /** Send `"latest"` / `""` / `null` to actively CLEAR a previously pinned version. */
+            default_model_version?: StringId | "latest" | null;
+            /** Set `true` to soft-delete. */
+            disabled?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                name?: string | string[];
+                /** Datasets containing any of the given label ids. */
+                dataset_labels?: StringId | StringId[];
+                default_model?: StringId | StringId[];
+                default_model_version?: StringId | StringId[];
+                /** Case-insensitive regex match on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionModel {
+        /** Free-form Ultralytics train args; the HUB endpoint reads `train_settings[0].epochs` / `.imgsz`. */
+        interface TrainSettings {
+            epochs?: number;
+            imgsz?: number;
+            batch?: number;
+            [key: string]: any;
+        }
+        /** Free-form predict args; inference reads `predict_settings[0].conf` / `.iou` / `.agnostic_nms` as defaults. */
+        interface PredictSettings {
+            conf?: number;
+            iou?: number;
+            agnostic_nms?: boolean;
+            [key: string]: any;
+        }
+        interface Data {
+            _id: StringId;
+            /** Must match `^[a-zA-Z_][a-zA-Z0-9_\s]*$`; unique per namespace. */
+            name: string;
+            train_settings?: TrainSettings[];
+            predict_settings?: PredictSettings[];
+            /** Resolution target for every unpinned ("latest") reference. Auto-advanced (forward-only) to the newest version whose weights upload completes. */
+            current_model_version?: StringId;
+            /** Validation split ratio, exclusive range (0.05, 0.4). Default 0.25. */
+            validation_size?: number;
+            /** Test split ratio, exclusive range (0, 0.2). Default 0.05. */
+            test_size?: number;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "current_model_version";
+        /** The version document with its weight / train-data / confusion-matrix media refs populated in place (no `_populated` suffix on the nested keys). */
+        type PopulatedCurrentModelVersion = Omit<AiObjectDetectionModelVersion.Data, "weight_best" | "weight_last" | "train_data" | "confusion_matrix" | "confusion_matrix_normalized"> & {
+            weight_best?: MediaStorage.MediaStorageSchema | null;
+            weight_last?: MediaStorage.MediaStorageSchema | null;
+            train_data?: MediaStorage.MediaStorageSchema | null;
+            confusion_matrix?: MediaStorage.MediaStorageSchema | null;
+            confusion_matrix_normalized?: MediaStorage.MediaStorageSchema | null;
+        };
+        interface DataWithPopulatedKeys extends Data {
+            current_model_version_populated?: PopulatedCurrentModelVersion | null;
+        }
+        interface CreateBody {
+            name: string;
+            train_settings?: TrainSettings[];
+            predict_settings?: PredictSettings[];
+            /** Normally left unset — the server advances it when a version finishes training. */
+            current_model_version?: StringId;
+            validation_size?: number;
+            test_size?: number;
+            company_namespace?: string[];
+        }
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace">>;
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                name?: string | string[];
+                current_model_version?: StringId | StringId[];
+                /** Case-insensitive regex match on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionModelVersion {
+        /** Lifecycle of the async dataset-prep job, then `trained` once `ul-hub` receives the weights. */
+        type Status = "initiated" | "setting_alarm_completed" | "building_folder_in_progress" | "building_folder_failed" | "building_yaml_file_in_progress" | "building_yaml_file_completed" | "stream_tasks_in_progress" | "stream_tasks_failed" | "compress_folder_in_progress" | "compress_folder_failed" | "uploading_zip_to_s3_in_progress" | "uploading_zip_to_s3_failed" | "zip_file_completed" | "trained";
+        /** `smart` = only `manual` / `auto_edited` annotation groups; `all` also includes untouched `auto` groups. */
+        type TaskSelectionMode = "smart" | "all";
+        /** Creator stamp taken from the JWT; only admins create versions. */
+        interface Creator {
+            _id: StringId;
+            type: "admin";
+            admin?: StringId;
+            name?: string;
+        }
+        /** Per-label box count written into the YOLO label files (class balance of the export). */
+        interface AnnotationPerLabel {
+            label_id: StringId;
+            name: string;
+            size?: number;
+        }
+        /** Free-form Ultralytics train args; the HUB endpoint reads `train_settings[0].epochs` / `.imgsz`. */
+        interface TrainSettings {
+            epochs?: number;
+            imgsz?: number;
+            batch?: number;
+            [key: string]: any;
+        }
+        /** Best-epoch (highest mAP50-95, the epoch `best.pt` was saved from) roll-up snapshotted when training completes. */
+        interface Metrics {
+            mAP50?: number;
+            mAP50_95?: number;
+            precision?: number;
+            recall?: number;
+            /** `_index` of the best epoch. */
+            best_epoch?: number;
+            epochs_reported?: number;
+        }
+        /** Architecture cost as Ultralytics reports it. */
+        interface ModelStats {
+            parameters?: number;
+            GFLOPs?: number;
+            speed_PyTorch_ms?: number;
+        }
+        interface Data {
+            _id: StringId;
+            /** Server-assigned, 1-based, increments per model within the namespace. */
+            version_code: number;
+            model: StringId;
+            dataset: StringId[];
+            /** Server-derived: union of the selected datasets' `dataset_labels`. */
+            dataset_labels: StringId[];
+            status?: Status;
+            /** Reserved flag; the split logic currently clamps shortfalls at 0 regardless. Default `false`. */
+            suppress_exceeding_sizes: boolean;
+            /** Media id of the YOLO dataset zip produced by the prep job. */
+            train_data?: StringId;
+            creator: Creator;
+            task_selection_mode: TaskSelectionMode;
+            /** Tasks that produced an image + label file in the zip. */
+            tasks_size?: number;
+            validation_size?: number;
+            test_size?: number;
+            train_settings?: TrainSettings[];
+            /** Sorted by `size` descending. */
+            annotations_per_label?: AnnotationPerLabel[];
+            /** Boxes written into the label files. */
+            annotations_size?: number;
+            /** Training artifacts uploaded after the run (media ids). */
+            confusion_matrix_normalized?: StringId;
+            /** Media id of the run's `args.yaml`. */
+            args?: StringId;
+            confusion_matrix?: StringId;
+            F1_curve?: StringId;
+            labels_correlogram?: StringId;
+            labels?: StringId;
+            P_curve?: StringId;
+            PR_curve?: StringId;
+            R_curve?: StringId;
+            results_csv?: StringId;
+            results?: StringId;
+            val_batch0_labels?: StringId;
+            val_batch0_pred?: StringId;
+            /** Base weights the run starts from (e.g. `yolov8n.pt` or a weights URL). */
+            initial_weight: string;
+            /** Media id of `best.pt` — set by the `ul-hub` weights upload. */
+            weight_best?: StringId;
+            /** Media id of `last.pt`. */
+            weight_last?: StringId;
+            metrics?: Metrics;
+            model_stats?: ModelStats;
+            disabled: boolean;
+            /** Adapted errors pushed by the async prep pipeline. */
+            _errors?: any[];
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "model" | "train_data" | "dataset" | "dataset_labels" | "confusion_matrix_normalized" | "args" | "confusion_matrix" | "F1_curve" | "labels_correlogram" | "labels" | "P_curve" | "PR_curve" | "R_curve" | "results_csv" | "results" | "val_batch0_labels" | "val_batch0_pred" | "weight_best" | "weight_last";
+        /** Populated refs are emitted under `<field>_populated`; the original field keeps the id(s). */
+        interface DataWithPopulatedKeys extends Data {
+            model_populated?: AiObjectDetectionModel.Data | null;
+            dataset_populated?: AiObjectDetectionDataset.Data[];
+            dataset_labels_populated?: AiObjectDetectionLabel.Data[];
+            train_data_populated?: MediaStorage.MediaStorageSchema | null;
+            confusion_matrix_normalized_populated?: MediaStorage.MediaStorageSchema | null;
+            args_populated?: MediaStorage.MediaStorageSchema | null;
+            confusion_matrix_populated?: MediaStorage.MediaStorageSchema | null;
+            F1_curve_populated?: MediaStorage.MediaStorageSchema | null;
+            labels_correlogram_populated?: MediaStorage.MediaStorageSchema | null;
+            labels_populated?: MediaStorage.MediaStorageSchema | null;
+            P_curve_populated?: MediaStorage.MediaStorageSchema | null;
+            PR_curve_populated?: MediaStorage.MediaStorageSchema | null;
+            R_curve_populated?: MediaStorage.MediaStorageSchema | null;
+            results_csv_populated?: MediaStorage.MediaStorageSchema | null;
+            results_populated?: MediaStorage.MediaStorageSchema | null;
+            val_batch0_labels_populated?: MediaStorage.MediaStorageSchema | null;
+            val_batch0_pred_populated?: MediaStorage.MediaStorageSchema | null;
+            weight_best_populated?: MediaStorage.MediaStorageSchema | null;
+            weight_last_populated?: MediaStorage.MediaStorageSchema | null;
+        }
+        interface CreateBody {
+            /** `ai-object-detection-model` id (must exist in the namespace). */
+            model: StringId;
+            /** One or more `ai-object-detection-dataset` ids. */
+            dataset: StringId[];
+            /** Ignored — the server recomputes it as the union of the datasets' `dataset_labels`. */
+            dataset_labels?: StringId[];
+            initial_weight: string;
+            /** Default `all`. */
+            task_selection_mode?: TaskSelectionMode;
+            suppress_exceeding_sizes?: boolean;
+            train_settings?: TrainSettings[];
+            validation_size?: number;
+            test_size?: number;
+            company_namespace?: string[];
+        }
+        /** Label projection returned by `create` (`select: ["name"]`). */
+        interface LabelRef {
+            _id: StringId;
+            name: string;
+        }
+        /** `create` returns the new version with `dataset`, `model` and `dataset_labels` populated in place (status is still `initiated` in the response). */
+        type CreateResult = Omit<Data, "dataset" | "model" | "dataset_labels"> & {
+            dataset: AiObjectDetectionDataset.Data[];
+            model: AiObjectDetectionModel.Data;
+            dataset_labels: LabelRef[];
+        };
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Accepted by the backend but the schema has no `name` field — effectively a no-op. */
+                name?: string | string[];
+                model?: StringId | StringId[];
+                version_code?: number | number[];
+                /** Versions pinning any of the given dataset ids. */
+                dataset?: StringId | StringId[];
+                dataset_labels?: StringId | StringId[];
+                /** Regex on `name` — no-op for this schema (see `name`). */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = CreateResult;
+        }
+        namespace Remove {
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionModelVersionEpoch {
+        /** Ultralytics loss components for one epoch. */
+        interface LossMetrics {
+            /** Bounding-box regression loss. */
+            box_loss?: number;
+            /** Classification loss. */
+            cls_loss?: number;
+            /** Distribution focal loss. */
+            dfl_loss?: number;
+        }
+        /** Validation metrics for one epoch. The `_B` suffix is Ultralytics' own — the Box (detection) task. */
+        interface PerformanceMetrics {
+            precision_B?: number;
+            recall_B?: number;
+            /** mAP at IoU 0.50 — the lenient, headline number. */
+            mAP50_B?: number;
+            /** mAP averaged over IoU 0.50:0.95 — the strict number `best.pt` is selected on. */
+            mAP50_95_B?: number;
+        }
+        /** Architecture cost; Ultralytics reports it only on some epochs. */
+        interface ModelStats {
+            /** Total weight count. */
+            parameters?: number;
+            /** Forward-pass cost per image. */
+            GFLOPs?: number;
+            /** Per-image PyTorch inference latency measured during validation. */
+            speed_PyTorch_ms?: number;
+        }
+        /** One training epoch as ingested by `ul-hub-v1-models` (keys de-slashed: `train/box_loss` → `train_loss_metrics.box_loss`). */
+        interface Data {
+            _id: StringId;
+            /** 0-based epoch number; unique per `model_version`. */
+            _index: number;
+            model_version: StringId;
+            /** Payload kind reported by the trainer. Only `metrics` today. */
+            type: "metrics";
+            train_loss_metrics?: LossMetrics;
+            val_loss_metrics?: LossMetrics;
+            performance_metrics?: PerformanceMetrics;
+            model_stats?: ModelStats;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface PerformanceRollup {
+            mAP50?: number;
+            mAP50_95?: number;
+            precision?: number;
+            recall?: number;
+        }
+        /** Derived on read from the returned series. */
+        interface Summary {
+            /** Epochs reported so far — less than the configured `epochs` while a run is in flight. */
+            epochs_reported: number;
+            /** `_index` of the highest-mAP50-95 epoch — what `best.pt` holds. */
+            best_epoch?: number;
+            best?: PerformanceRollup;
+            /** Last reported epoch — diverges from `best` when the run overfit. */
+            final?: PerformanceRollup;
+            /** Carried on the last epoch that reported it. */
+            model_stats?: ModelStats;
+            /** val − train (box+cls+dfl) at the final epoch; positive and growing = overfitting. */
+            final_generalization_gap?: number;
+        }
+        namespace Find {
+            /** Not paginated — `per_page` / `page` / `sort` are ignored; the whole run is returned in `_index` order. */
+            interface Params {
+                /** Required — 400 without it. */
+                model_version: StringId | StringId[];
+                _id?: StringId | StringId[];
+                /** Filter to specific epoch index(es). */
+                _index?: number | number[];
+                type?: "metrics";
+                disabled?: boolean;
+            }
+            interface Result {
+                /** Every reported epoch, ascending by `_index`. */
+                data: Data[];
+                total_result: number;
+                summary: Summary;
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionModelVersionTrainAgent {
+        interface Step {
+            /** A ready-to-run shell / Python snippet (may span multiple lines). */
+            code_message: string;
+        }
+        /** The bootstrap script for training one model version on a self-hosted agent. */
+        interface Data {
+            /** Ordered: (1) pin-install ultralytics, (2) point the HUB client at Repzo and train, (3) upload the run's plots + `args.yaml`. */
+            steps: Step[];
+            /** The pinned ultralytics release the snippet installs (`8.4.114`, the last one shipping `ultralytics.hub`). */
+            ultralytics_version?: string;
+        }
+        namespace Get {
+            /** The `ai-object-detection-model-version` id to generate the snippet for. */
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionLabel {
+        /** Expected physical front-face size of the labelled item, in centimetres (each axis 0.1–500). */
+        interface PhysicalSize {
+            w_cm?: number;
+            h_cm?: number;
+        }
+        interface Data {
+            _id: StringId;
+            /** Unique per namespace. Must match `^[a-zA-Z_][a-zA-Z0-9_\s]*$`. */
+            name: string;
+            disabled: boolean;
+            /** Reference crop (media-storage id). Linked to the label on create/update so the upload is not treated as orphaned media. */
+            media_photo?: StringId;
+            variants?: StringId[];
+            products?: StringId[];
+            product_categories?: StringId[];
+            product_subcategories?: StringId[];
+            product_brands?: StringId[];
+            product_groups?: StringId[];
+            /** Annotation hot-key: exactly one lower-case letter or digit, excluding `i`, `o` and `_`. */
+            keyboard_shortcut?: string;
+            /** Sibling family for the dims reclassifier — detections are only re-labelled BETWEEN labels sharing a group. */
+            label_group?: StringId;
+            /** Optional; labels without dims are skipped by the reclassifier. Set manually or via the label-report `mode=dims` analyzer. */
+            physical_size?: PhysicalSize;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "label_group" | "media_photo" | "variants" | "products" | "product_categories" | "product_subcategories" | "product_brands" | "product_groups";
+        interface DataWithPopulatedKeys extends Data {
+            label_group_populated?: AiObjectDetectionLabelGroup.Data;
+            media_photo_populated?: MediaStorage.MediaStorageSchema;
+            variants_populated?: Variant.VariantSchema[];
+            products_populated?: Product.ProductSchema[];
+            product_categories_populated?: Category.CategorySchema[];
+            product_subcategories_populated?: SubCategory.SubCategorySchema[];
+            product_brands_populated?: Brand.BrandSchema[];
+            product_groups_populated?: ProductGroup.ProductGroupSchema[];
+        }
+        interface CreateBody {
+            name: string;
+            media_photo?: StringId;
+            variants?: StringId[];
+            products?: StringId[];
+            product_categories?: StringId[];
+            product_subcategories?: StringId[];
+            product_brands?: StringId[];
+            product_groups?: StringId[];
+            keyboard_shortcut?: string;
+            label_group?: StringId;
+            physical_size?: PhysicalSize;
+            company_namespace?: string[];
+        }
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace">>;
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Exact match (single value or list). Use `search` for a substring match. */
+                name?: string | string[];
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                disabled?: boolean;
+                label_group?: StringId | StringId[];
+                variants?: StringId | StringId[];
+                products?: StringId | StringId[];
+                product_categories?: StringId | StringId[];
+                product_subcategories?: StringId | StringId[];
+                product_brands?: StringId | StringId[];
+                product_groups?: StringId | StringId[];
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The label after soft-deletion (`disabled: true`). Rejected while any dataset still lists the label. */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionLabelGroup {
+        /**
+         * A family of sibling labels the detector confuses (size / flavour variants of one
+         * product line). The dims reclassifier only ever moves a detection BETWEEN labels of
+         * one group. Labels join a group through `AiObjectDetectionLabel.Data.label_group`.
+         */
+        interface Data {
+            _id: StringId;
+            /** Unique per namespace among non-deleted groups. */
+            name: string;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface CreateBody {
+            name: string;
+            company_namespace?: string[];
+        }
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace">>;
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Exact match (single value or list). Use `search` for a substring match. */
+                name?: string | string[];
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+            };
+            interface Result extends DefaultPaginationResult {
+                data: Data[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            interface Params {
+                /**
+                 * A group that still has live member labels is rejected (400, with
+                 * `{ assigned_labels, requires_force: true }`) unless `force: true`, which first
+                 * unsets `label_group` on those labels and then soft-deletes the group.
+                 */
+                force?: boolean;
+            }
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionCategory {
+        /**
+         * One AUTO-ANALYSIS recipe: which model / version to run and the full analyze-session
+         * settings. A category with N settings produces N analyses per received session.
+         */
+        interface ModelSetting {
+            /** Sub-document id (server-assigned). */
+            _id?: StringId;
+            /** `ai-object-detection-model` id. Always required — it resolves the "latest" version when `model_version` is unset. */
+            model: StringId;
+            /** Pinned `ai-object-detection-model-version` id. Unset = "latest" → resolved to `model.current_model_version` at analysis time. */
+            model_version?: StringId;
+            /** Analyze-session settings (SceneMathConfig + `conf`/`iou`, walk, `reclassify_*`, `size_gate*`, `build_point_cloud`, ...). Unset keys fall back to scene-math defaults. */
+            config?: {
+                [key: string]: any;
+            };
+        }
+        /** Wire shape accepted on create/update: `model_version` may be the UI sentinel `"latest"`, `""` or `null`, all normalised to unset. */
+        interface ModelSettingBody {
+            _id?: StringId;
+            model: StringId;
+            model_version?: StringId | "latest" | null;
+            config?: {
+                [key: string]: any;
+            };
+        }
+        /**
+         * A detection CATEGORY groups what a capture session is ABOUT: the model settings to
+         * auto-analyze it with, and the labels that matter for the jobs & metrics built on top.
+         * The mobile app picks one before calibration; a session received WITH a category is
+         * auto-analyzed once per `model_settings` item after its upload completes.
+         */
+        interface Data {
+            _id: StringId;
+            /** Unique per namespace among non-deleted categories. */
+            name: string;
+            model_settings: ModelSetting[];
+            /** `ai-object-detection-label` ids this category tracks — inputs for later jobs/metrics. */
+            labels: StringId[];
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "labels" | "model_settings.model" | "model_settings.model_version";
+        /** Nested populations are applied IN PLACE (mongoose `populate` on `model_settings.model[_version]`), not under a `_populated` key. */
+        interface ModelSettingWithPopulatedKeys extends Omit<ModelSetting, "model" | "model_version"> {
+            model: StringId | AiObjectDetectionModel.Data;
+            model_version?: StringId | AiObjectDetectionModelVersion.Data;
+        }
+        interface DataWithPopulatedKeys extends Omit<Data, "model_settings"> {
+            model_settings: ModelSettingWithPopulatedKeys[];
+            labels_populated?: AiObjectDetectionLabel.Data[];
+        }
+        interface CreateBody {
+            name: string;
+            /** Each item must name a `model` (400 otherwise); `model_version` optional (absent = latest). */
+            model_settings?: ModelSettingBody[];
+            labels?: StringId[];
+            company_namespace?: string[];
+        }
+        interface UpdateBody {
+            name?: string;
+            model_settings?: ModelSettingBody[];
+            labels?: StringId[];
+            /** Soft-delete flag — set `true` to disable via update (bypasses the session guard on remove). */
+            disabled?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Exact match (single value or list). Use `search` for a substring match. */
+                name?: string | string[];
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                /** Categories tracking any of the given label id(s). */
+                labels?: StringId | StringId[];
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            interface Params {
+                /**
+                 * A category still referenced by live sessions is rejected (400, with
+                 * `{ assigned_sessions, requires_force: true }`) unless `force: true`, which first
+                 * unsets `category` on those sessions and then soft-deletes the category.
+                 */
+                force?: boolean;
+            }
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionSegment {
+        /**
+         * A SEGMENT is a named label set used by share-of-shelf metrics ("our brand",
+         * "competitor X", "energy drinks"). A metric references segments and may override a
+         * segment's labels for that metric only — the segment stays the reusable default.
+         */
+        interface Data {
+            _id: StringId;
+            /** Unique per namespace among live segments. */
+            name: string;
+            description?: string;
+            /** Member `ai-object-detection-label` ids. Empty = placeholder the metric must override. */
+            labels: StringId[];
+            disabled: boolean;
+            /** Server-stamped from the caller's token on create. */
+            creator?: AdminOrRepOrTenantOrClient;
+            /** Server-stamped from the caller's token on update / remove. */
+            editor?: AdminOrRepOrTenantOrClient;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "labels";
+        interface DataWithPopulatedKeys extends Data {
+            labels_populated?: AiObjectDetectionLabel.Data[];
+        }
+        interface CreateBody {
+            /** Required and must be non-blank (400 otherwise). */
+            name: string;
+            description?: string;
+            labels?: StringId[];
+            company_namespace?: string[];
+        }
+        /** PUT re-validates the body: `name` must be present and non-blank even on a partial change. */
+        interface UpdateBody {
+            name: string;
+            description?: string;
+            labels?: StringId[];
+            disabled?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Exact match (single value or list). Use `search` for a substring match. */
+                name?: string | string[];
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                /** Segments containing any of these label id(s). */
+                labels?: StringId | StringId[];
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** Soft-delete; rejected (400 naming the metrics) while an active share-of-shelf metric still references the segment. */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionLabelReport {
+        /** Dataset subset a task is routed to (`auto` fills train or val at build time; `ignore` is excluded). */
+        type Subset = "train" | "val" | "test" | "auto" | "ignore";
+        /** Annotation-group provenance: model output, human-drawn, or model output edited by a human. */
+        type AnnotationState = "auto" | "manual" | "auto_edited";
+        /** Per-annotation label provenance. */
+        type LabelState = "auto" | "manual";
+        /** Which group states count as training-eligible: `all` = manual|auto|auto_edited (model default), `smart` = manual|auto_edited. */
+        type StateMode = "all" | "smart";
+        /** YOLO-style pixel box on the frame image. */
+        interface Box {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        }
+        interface ItemGroup {
+            usable: boolean;
+            confirmed: boolean;
+            annotation_state?: AnnotationState;
+            /** Detector that produced the group: a trained model version or a zero-shot VLM. */
+            engine?: "trained" | "zero_shot";
+            /** `ai-object-detection-model-version` id when `engine` is `trained`. */
+            model_version?: StringId;
+        }
+        /** One annotation of the requested label inside the requested dataset — the `items[]` row. */
+        interface Data {
+            /** `ai-object-detection-task` id the annotation belongs to. */
+            task_id: StringId;
+            /** Public URL of the task's frame image. */
+            image_url?: string;
+            /** Image width (task `shape[0]`, falling back to the media doc). */
+            image_w?: number;
+            /** Image height (task `shape[1]`, falling back to the media doc). */
+            image_h?: number;
+            /** Subset from THIS dataset's `task_dataset` entry. */
+            subset?: Subset;
+            box: Box;
+            confidence?: number;
+            label_state: LabelState;
+            group: ItemGroup;
+            /** `usable && confirmed && state ∈ mode set` AND subset ∈ {train, auto}. */
+            included_in_training: boolean;
+            /** `usable && confirmed && state ∈ mode set` AND subset ∈ {val, auto}. */
+            included_in_val: boolean;
+            /** Internal eligibility flag (`usable && confirmed && state ∈ mode set`) the pipeline leaves on the row. */
+            _qualifies?: boolean;
+        }
+        /** Distribution of the label's annotations across the WHOLE dataset (not affected by item filters). */
+        interface Summary {
+            annotations_total: number;
+            /** Distinct tasks carrying the label. */
+            tasks_total: number;
+            subset_train: number;
+            subset_val: number;
+            subset_test: number;
+            subset_auto: number;
+            subset_ignore: number;
+            state_manual: number;
+            state_auto: number;
+            state_auto_edited: number;
+            usable_count: number;
+            confirmed_count: number;
+            training_eligible: number;
+            val_eligible: number;
+        }
+        /** Default mode response (`?dataset=&label=`): annotation health summary + paginated, filterable items. */
+        interface ReportResult {
+            summary: Summary;
+            items: Data[];
+            mode: StateMode;
+            /** Count of items after the item filters (the paginated stream). */
+            total_result: number;
+            current_page: number;
+            per_page: number;
+            total_pages: number;
+        }
+        /** One measured annotation considered by the smart dims analyzer. */
+        interface DimsSample {
+            /** `ai-object-detection-task` id. */
+            task: StringId;
+            /** Parent `ai-object-detection-session` id (session frames only). */
+            session?: StringId;
+            frame_id?: number;
+            createdAt: Date;
+            /** Measured physical width (cm). */
+            w_cm: number;
+            /** Measured physical height (cm). */
+            h_cm: number;
+            confidence?: number;
+            /** 0..1 depth confidence of the placement. */
+            depth_confidence?: number;
+            label_state: LabelState;
+            /** Modified z-score of `w_cm` (2 dp); `null` when the MAD is 0 and the value differs from the median. */
+            z_w: number | null;
+            z_h: number | null;
+            /** Kept for the proposal (not an outlier and depth confidence ≥ `min_depth_confidence`). */
+            kept: boolean;
+            reject_reason: "low_depth_confidence" | "outlier" | null;
+        }
+        interface DimsStats {
+            /** Samples collected. */
+            n: number;
+            /** Samples with depth confidence ≥ `min_depth_confidence`. */
+            n_qualified: number;
+            /** Samples kept after outlier rejection. */
+            n_kept: number;
+            /** Median over qualified samples, 1 dp (cm). */
+            median_w_cm: number;
+            median_h_cm: number;
+            /** Median absolute deviation over qualified samples, 2 dp (cm). */
+            mad_w_cm: number;
+            mad_h_cm: number;
+            /** Mean of kept samples (1 dp); `null` when fewer than `min_samples` were kept. */
+            proposed: {
+                w_cm: number;
+                h_cm: number;
+            } | null;
+        }
+        /** `?mode=dims&label=` response — the label screen's SMART DIMS ANALYZER. */
+        interface DimsResult {
+            label: Pick<AiObjectDetectionLabel.Data, "_id" | "name" | "physical_size" | "label_group"> | null;
+            /** Effective parameters after defaults/clamping. */
+            params: {
+                sample: number;
+                z_threshold: number;
+                min_depth_confidence: number;
+                min_samples: number;
+            };
+            stats: DimsStats;
+            samples: DimsSample[];
+        }
+        namespace Find {
+            /** Default mode: per-dataset annotation health for one label. */
+            interface ReportParams {
+                /** Eligibility predicate; defaults to `all`. Any value other than `smart`/`dims` is treated as `all`. */
+                mode?: StateMode;
+                /** `ai-object-detection-dataset` id (required, ObjectId). */
+                dataset: StringId;
+                /** `ai-object-detection-label` id (required, ObjectId). */
+                label: StringId;
+                /** Item filter — one value or a list. */
+                subset?: Subset | Subset[];
+                /** Item filter on `group.annotation_state`. */
+                annotation_state?: AnnotationState | AnnotationState[];
+                /** Item filter on the annotation's `label_state`. */
+                label_state?: LabelState | LabelState[];
+                /** Item filter on `group.usable`. */
+                usable?: boolean;
+                /** Item filter on `group.confirmed`. */
+                confirmed?: boolean;
+                /** Item filter: only rows included in training (`train`) or validation (`val`). */
+                included?: "train" | "val";
+                /** Page size for `items` (capped by the server's pagination max). */
+                per_page?: number;
+                /** 1-based page for `items`. */
+                page?: number;
+            }
+            /** Smart dims analyzer — label-scoped, no dataset. */
+            interface DimsParams {
+                mode: "dims";
+                /** `ai-object-detection-label` id (required, ObjectId). */
+                label: StringId;
+                /** Most recent measured annotations to consider. Default 100, clamped to 1..500. */
+                sample?: number;
+                /** Modified z-score cut-off on either axis. Default 3.5. */
+                z_threshold?: number;
+                /** Minimum depth confidence for a sample to count. Default 0.5. */
+                min_depth_confidence?: number;
+                /** Minimum kept samples before a proposal is made. Default 8. */
+                min_samples?: number;
+            }
+            type Params = ReportParams | DimsParams;
+            /** `ReportResult` for the default mode, `DimsResult` when `mode === "dims"`. */
+            type Result = ReportResult | DimsResult;
+        }
+    }
+    namespace AiObjectDetectionSettings {
+        /**
+         * Free-form bag of ANALYZE knobs (numbers / booleans only). Known keys are the
+         * scene engine's `SceneMathConfig` (see `AiObjectDetectionInference.SceneMathConfig`)
+         * plus a few the analyze endpoint reads directly (e.g. `inference_concurrency`).
+         * The server does NOT filter keys — only values are validated: each knob must be a
+         * finite number or a boolean; `null`/`undefined` knobs are skipped ("fall back to
+         * the engine default"); anything else is rejected with 400. Capped at 200 keys.
+         */
+        type AnalyzeConfig = AiObjectDetectionInference.SceneMathConfig & {
+            /** Parallel per-frame inference calls during a session analysis run. */
+            inference_concurrency?: number;
+            [knob: string]: number | boolean | undefined;
+        };
+        /**
+         * The stored Mongo document (exactly one per namespace, unique index on
+         * `company_namespace`). Never returned as-is — every method answers the projected
+         * `Data` shape below.
+         */
+        interface Document {
+            _id: StringId;
+            company_namespace: string[];
+            disabled: boolean;
+            /** Partial knob bag (see `AnalyzeConfig`). */
+            analyze_config?: AnalyzeConfig;
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        /** Response shape of EVERY method (find / get / create / update / patch / remove). */
+        interface Data {
+            /** `null` while the namespace has never saved defaults. */
+            _id: StringId | null;
+            /** `true` = nothing saved for this namespace; clients fall back to the engine defaults. */
+            is_default: boolean;
+            /** The saved partial knob bag (`{}` when `is_default`). */
+            analyze_config: AnalyzeConfig;
+            /** When the defaults were last saved; `null` when `is_default`. */
+            updatedAt: Date | null;
+        }
+        interface CreateBody {
+            /** Required — the server rejects a missing / non-object bag with 400. */
+            analyze_config: AnalyzeConfig;
+            /**
+             * Optional tenant namespace override for SDK callers. NOTE: this endpoint keys
+             * its single document from the caller's token namespace and does not read the
+             * body's `company_namespace`.
+             */
+            company_namespace?: string[];
+        }
+        /** PUT / PATCH accept exactly the create body — they upsert the same single document. */
+        type UpdateBody = {
+            analyze_config: AnalyzeConfig;
+        };
+        namespace Find {
+            /** NOT paginated — the namespace's single defaults document. Never 404s. */
+            type Result = Data;
+        }
+        namespace Get {
+            /** Ignored — one logical document per namespace (the dashboard sends `defaults`). */
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** The fresh read after the upsert. */
+            type Result = Data;
+        }
+        namespace Update {
+            /** Ignored — the namespace keys the document. */
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Patch {
+            /** Identical to update/create (upsert of the single document; no id, no query). */
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            /** Ignored — any value works (the dashboard sends `defaults`). */
+            type ID = StringId;
+            /** The empty default state: `{ _id: null, is_default: true, analyze_config: {}, updatedAt: null }`. */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionDetectionSettings {
+        /**
+         * Two-tier frame limit. `warn` = guidance shown on the device, frame still usable;
+         * `error` = frame excluded from election (but it still counts toward the coverage
+         * total). `warn` is always the softer bound.
+         */
+        interface WarnError {
+            warn: number;
+            error: number;
+        }
+        type CaptureMode = "stack_elect" | "continuous" | "burst";
+        type CaptureResolution = "medium" | "high" | "max";
+        interface CaptureConfig {
+            /** Default `stack_elect`. */
+            mode: CaptureMode;
+            /** Capture rate, frames per second. Default 4. */
+            rate_hz: number;
+            /** Default `max`. */
+            resolution: CaptureResolution;
+            /** Seconds before a stack-elect capture times out. Default 30. */
+            stack_timeout_s: number;
+            /** Show the sweep guide overlay. Default true. */
+            sweep_guide: boolean;
+            /** Default true. */
+            torch: boolean;
+            /** Default true. */
+            exposure_lock: boolean;
+        }
+        interface FrameConfig {
+            /** Variance-of-Laplacian sharpness floor: `warn` = live-guidance floor, `error` = election hard floor ("blur limit"). Default `{ warn: 200, error: 50 }`. */
+            min_sharpness: WarnError;
+            /** Degrees. Default `{ warn: 18, error: 30 }`. */
+            max_yaw_delta_deg: WarnError;
+            /** Degrees. Default `{ warn: 15, error: 28 }`. */
+            max_pitch_delta_deg: WarnError;
+            /** Degrees. Default `{ warn: 12, error: 25 }`. */
+            max_roll_delta_deg: WarnError;
+            /** Metres. Default `{ warn: 0.8, error: 1.5 }`. */
+            max_depth_variation_m: WarnError;
+            /** Metres — `error` is the NEARER bound (worse). Default `{ warn: 0.5, error: 0.3 }`. */
+            min_distance_m: WarnError;
+            /** Metres — `error` is the FARTHER bound (worse). Default `{ warn: 2.0, error: 3.0 }`. */
+            max_distance_m: WarnError;
+            /** 0..100. Default `{ warn: 60, error: 35 }`. */
+            min_tracking_score: WarnError;
+        }
+        interface ElectionConfig {
+            /** Stop electing at this union coverage (0..1). Default 0.985. */
+            cover_target: number;
+            /** Ignore gains under this fraction of a median footprint. Default 0.02. */
+            sliver_frac: number;
+            /** Redundancy penalty exponent (score = quality · gain^exp). Default 1.5. */
+            gain_exp: number;
+            /** Quality geometric-mean weight — sharpness. Default 0.4. */
+            w_sharp: number;
+            /** Quality geometric-mean weight — depth. Default 0.3. */
+            w_depth: number;
+            /** Quality geometric-mean weight — tracking. Default 0.2. */
+            w_track: number;
+            /** Quality geometric-mean weight — lux. Default 0.1. */
+            w_lux: number;
+        }
+        /** Average-quality verdict bands; below `acceptable` = rejected. Default `{ excellent: 0.8, good: 0.65, acceptable: 0.45 }`. */
+        interface SessionScoreBands {
+            excellent: number;
+            good: number;
+            acceptable: number;
+        }
+        interface SessionConfig {
+            /** Reject when the device-reported covered area (m²) is below this. Default 0.5. */
+            coverage_target_m2: number;
+            /** When false, a spatial jump (after removing error frames) rejects the session. Default false. */
+            allow_jump: boolean;
+            /** Elected-count budget: ceil(total_area / avg_frame_area × allowance); more elected frames than that rejects the session. Default 1.6. */
+            elected_allowance: number;
+            score: SessionScoreBands;
+        }
+        /** The full, MERGED detection config the mobile app pulls on session start (defaults deep-merged with the namespace overrides). */
+        interface DetectionConfig {
+            capture: CaptureConfig;
+            frame: FrameConfig;
+            election: ElectionConfig;
+            session: SessionConfig;
+        }
+        /**
+         * Deep-partial overrides. Objects merge recursively over the engine defaults;
+         * scalars replace. Unknown keys are kept by the merge so the config can grow.
+         */
+        interface DetectionConfigOverrides {
+            capture?: Partial<CaptureConfig>;
+            frame?: {
+                [K in keyof FrameConfig]?: Partial<WarnError>;
+            };
+            election?: Partial<ElectionConfig>;
+            session?: Partial<Omit<SessionConfig, "score">> & {
+                score?: Partial<SessionScoreBands>;
+            };
+        }
+        /**
+         * The stored Mongo document (exactly one per namespace, unique index on
+         * `company_namespace`). Never returned as-is — reads answer the projected `Data`.
+         */
+        interface Document {
+            _id: StringId;
+            company_namespace: string[];
+            disabled: boolean;
+            /** Partial overrides over the engine defaults. */
+            config?: DetectionConfigOverrides;
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        /** Response shape of find / get / create / update / patch. */
+        interface Data {
+            /** `null` while the namespace has never saved overrides. */
+            _id: StringId | null;
+            /** `true` = no overrides saved; `config` is the pure engine default. */
+            is_default: boolean;
+            /** Merged result: namespace overrides deep-merged over the engine defaults. */
+            config: DetectionConfig;
+            /** The raw saved overrides (`{}` when `is_default`). */
+            overrides: DetectionConfigOverrides;
+            /** When the overrides were last saved; `null` when `is_default`. */
+            updatedAt: Date | null;
+        }
+        interface CreateBody {
+            /**
+             * Required (400 when missing / not an object). REPLACES the stored overrides
+             * object wholesale — it is not merged into previously saved overrides — so send
+             * the complete set of overrides you want kept.
+             */
+            config: DetectionConfigOverrides;
+            /**
+             * Optional tenant namespace override for SDK callers. NOTE: this endpoint keys
+             * its single document from the caller's token namespace and does not read the
+             * body's `company_namespace`.
+             */
+            company_namespace?: string[];
+        }
+        /** PUT / PATCH accept exactly the create body — they upsert the same single document. */
+        type UpdateBody = {
+            config: DetectionConfigOverrides;
+        };
+        namespace Find {
+            /** NOT paginated — the namespace's merged config. Never 404s. */
+            type Result = Data;
+        }
+        namespace Get {
+            /** Ignored — one logical document per namespace. */
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** The fresh merged read after the upsert. */
+            type Result = Data;
+        }
+        namespace Update {
+            /** Ignored — the namespace keys the document. */
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Patch {
+            /** Identical to update/create (upsert of the single document; no id, no query). */
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            /** Ignored — any value works. */
+            type ID = StringId;
+            /** Reset acknowledgement: `is_default: true` plus the pure engine defaults. Note: NO `_id` / `overrides` / `updatedAt` in this response. */
+            interface Result {
+                is_default: true;
+                config: DetectionConfig;
+            }
+        }
+    }
+    namespace AiObjectDetectionInference {
+        /** Detector selection on the request. */
+        type Engine = "auto" | "trained" | "zero_shot";
+        /** The detector that actually ran. */
+        type ResolvedEngine = "trained" | "zero_shot";
+        /** Zero-shot VLMs the server accepts (`zero_shot_model`); unknown names are rejected with 400. */
+        type ZeroShotModel = "qwen/qwen3-vl-8b-instruct" | "qwen/qwen3-vl-32b-instruct" | "qwen/qwen3-vl-235b-a22b-instruct" | "qwen/qwen2.5-vl-72b-instruct";
+        type ExplainPart = "class_scores" | "heatmap" | "gradcam" | "feature_maps" | "embeddings" | "confusion_matrix" | "all";
+        type EmbedMethod = "auto" | "umap" | "tsne" | "pca";
+        /** Why a detection could NOT be placed in world coordinates. */
+        type IgnoreReason = "no_pose" | "no_intrinsics" | "no_depth" | "empty_depth_region" | "insufficient_depth_pixels" | "behind_shelf";
+        /**
+         * Every knob of the AR scene engine (`scene-math.ts` SceneMathConfig). All optional;
+         * the engine default is given per field. Inference honours the depth-sampling knobs
+         * (`min_depth_m` … `shelf_tolerance_m`), the dims-reclassifier knobs and the size-gate
+         * knobs; the clustering / plane-merge / shelf / point-cloud knobs are consumed by
+         * `ai-object-detection-session-analysis` and are accepted-but-ignored here. The same
+         * bag is what `ai-object-detection-settings` stores as the namespace analyze defaults.
+         */
+        interface SceneMathConfig {
+            /** Base world distance (m) to merge two detections into one object. Default 0.08. */
+            cluster_eps_m?: number;
+            /** Extra merge radius (m) when labels match. Default 0.02. */
+            class_agree_bonus_m?: number;
+            /** A scene object absorbs at most ONE detection per frame. Default true. */
+            block_same_frame?: boolean;
+            /** Ignore depth samples below this (m). Default 0.05. */
+            min_depth_m?: number;
+            /** Ignore depth samples above this (m). Default 6. */
+            max_depth_m?: number;
+            /** Minimum ARKit depth-confidence (0/1/2) to keep a pixel. Default 1. */
+            conf_threshold?: number;
+            /** Percentile of bbox depths to take — front-biased. Default 30. */
+            front_percentile?: number;
+            /** Depth-gate slack (m) beyond the frame's `distance_to_shelf_m`. Default 0.3. */
+            shelf_tolerance_m?: number;
+            /** Same-label 2D IoU at/above this = duplicate box within one frame. Default 0.92. */
+            same_frame_iou_thresh?: number;
+            /** Same-label world distance (m) below this = same physical spot within one frame. Default 0.02. */
+            same_frame_min_separation_m?: number;
+            /** Drop detections under this detector confidence (0 = off). Default 0. */
+            min_detection_confidence?: number;
+            /** Drop when the front face is smaller than this (cm). Default 0.5. */
+            min_object_size_cm?: number;
+            /** Drop when the front face is larger than this (cm). Default 500. */
+            max_object_size_cm?: number;
+            /** Use plane-projection matching across frames. Default true. */
+            plane_merge?: boolean;
+            /** Min projected-rect IoU to merge. Default 0.1. */
+            plane_merge_iou?: number;
+            /** Max |plane-depth difference| (m) — the "virtual object depth". Default 0.25. */
+            plane_merge_depth_delta_m?: number;
+            /** Dims reclassifier master switch — re-label an auto detection to a sibling label whose expected dims fit its measured size better. Default false. */
+            reclassify_labels?: boolean;
+            /** E(original) ≤ this keeps the detected label outright. Default 0.15. */
+            reclassify_keep_dev?: number;
+            /** A sibling must fit within this to steal the detection. Default 0.15. */
+            reclassify_target_dev?: number;
+            /** Base margin E(orig) − E(best) must exceed. Default 0.06. */
+            reclassify_min_margin?: number;
+            /** Margin × (1 + scale · detector_conf); 0 = ignore confidence. Default 0.5. */
+            reclassify_conf_margin_scale?: number;
+            /** Weight of the SIZE mismatch in the fit score. Default 1.0. */
+            reclassify_weight_scale?: number;
+            /** Weight of the SHAPE (aspect) mismatch in the fit score. Default 0.5. */
+            reclassify_weight_aspect?: number;
+            /** Skip detections whose depth confidence is below this. Default 0.5. */
+            reclassify_min_depth_confidence?: number;
+            /** Post-walk: merge overlapping same-group clusters via the plane test. Default true. */
+            group_consensus_merge?: boolean;
+            /** Size gate master switch — flag detections measuring beyond their label's expected dims. Default true. */
+            size_gate?: boolean;
+            /** Per-axis allowance: reject when measured w or h > (1 + this) × expected. Default 0.35. */
+            size_gate_dims_allowance?: number;
+            /** Area allowance: reject when measured w·h > (1 + this) × expected area. Default 0.35. */
+            size_gate_area_allowance?: number;
+            /** Skip gating detections whose depth confidence is below this. Default 0.5. */
+            size_gate_min_depth_confidence?: number;
+            /** Shelf composition (boards → stacks → objects) master switch. Default true. */
+            shelf_analysis?: boolean;
+            /** Min horizontal overlap ratio (of the narrower) to belong to the same column. Default 0.5. */
+            shelf_support_min_overlap?: number;
+            /** Bottom-density window half-width (m) when finding candidate levels. Default 0.06. */
+            shelf_gap_split_m?: number;
+            /** Min vertical distance (m) between two shelf boards. Default 0.12. */
+            shelf_min_spacing_m?: number;
+            /** Measurement slack (m) for stacked boxes. Default 0.035. */
+            shelf_stack_max_penetration_m?: number;
+            /** Depth gap (m) separating front/back rows within a shelf. Default 0.15. */
+            shelf_row_split_m?: number;
+            /** A level needs at least this many stacks to be a shelf. Default 1. */
+            shelf_min_stacks?: number;
+            /** Build + store the voxel point cloud on analysis runs. Default true. */
+            build_point_cloud?: boolean;
+            /** Depth-grid stride — every Nth pixel. Default 2. */
+            pc_stride?: number;
+            /** Voxel edge (m) for downsampling. Default 0.02. */
+            pc_voxel_size_m?: number;
+            /** RANSAC: planes to peel off at most. Default 4. */
+            ransac_max_planes?: number;
+            /** RANSAC: stop below this inlier share. Default 0.05. */
+            ransac_min_inlier_ratio?: number;
+            /** RANSAC: point-to-plane inlier distance (m). Default 0.02. */
+            ransac_distance_thresh_m?: number;
+        }
+        /** The action request — `POST /ai-object-detection-inference`. */
+        interface CreateBody {
+            /** The `ai-object-detection-task` to infer on (must belong to the caller's namespace and carry `file_media` with a public URL). */
+            task_id: StringId;
+            /** Model version `_id`. When set, resolves the lambda model + label order directly and bypasses the task's dataset / default-model requirement. */
+            model_version?: StringId;
+            /** Object-detection model `_id`. Used directly as the lambda model id when given (its `current_model_version` supplies the label order). */
+            model?: StringId;
+            /** Default `auto`: trained when a model resolves, else falls back to zero-shot (when configured) ONLY on the dataset path; explicit `model`/`model_version` stay strict. */
+            engine?: Engine;
+            /** Zero-shot VLM override. */
+            zero_shot_model?: ZeroShotModel;
+            /** Detection confidence threshold. Defaults to the model's `predict_settings[0].conf`, else 0.25. */
+            conf?: number;
+            /** NMS IoU threshold (0..1). Defaults to the model's `predict_settings[0].iou`, else 0.7. */
+            iou?: number;
+            /** Class-agnostic NMS (trained engine only). Defaults to the model's `predict_settings[0].agnostic_nms`, else false. */
+            agnostic_nms?: boolean;
+            /** Default true — persist the mapped predictions as a fresh `auto` annotation group on the task (replacing only the unconfirmed auto group from the same source). */
+            save?: boolean;
+            /** Explainable-AI opt-in (trained engine only): calls the diagnosis lambda and returns `xai`; when saved, XAI is persisted on the group. Never fails the prediction. */
+            explain?: boolean;
+            /** Subset of XAI parts. Omit / empty / `["all"]` = every part; unknown names are dropped. */
+            explain_parts?: ExplainPart[];
+            /** Candidate classes per detection in `class_scores`. Default 5 (min 1). */
+            explain_topk?: number;
+            /** Top-K cap on per-detection Grad-CAM maps. Default 20; 0 disables them. */
+            explain_gradcam_detections?: number;
+            /** 2D projection for the embeddings scatter. Default `auto`. */
+            explain_embed_method?: EmbedMethod;
+            /** XAI backfill for the EXISTING detections (implies `explain`; trained engine + `save` only): the detector is skipped and XAI is grafted onto the task's saved unconfirmed auto group of the resolved version. Falls through to a full inference when no such group exists. 400 when the resolved engine is zero-shot. */
+            explain_only?: boolean;
+            /** Back-projection / reclassifier / size-gate tuning for AR session frames. Omit for the engine defaults. */
+            config?: SceneMathConfig;
+            /** Optional tenant namespace override for SDK callers. NOTE: the server takes the namespace from the caller's token and does not read this field. */
+            company_namespace?: string[];
+        }
+        /** Raw detector box: pixel corners on the original image plus YOLO-normalized center/size (0..1). */
+        interface PredictionBox {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+            x_center: number;
+            y_center: number;
+            width: number;
+            height: number;
+        }
+        /** One raw detector result (`images[0].results[]` of the Ultralytics lambda; zero-shot replies are normalized to the same shape with `class: -1`). Passed through unchanged. */
+        interface Prediction {
+            name: string;
+            class: number;
+            confidence: number;
+            box: PredictionBox;
+            [key: string]: any;
+        }
+        /** A mapped detection — the same schema as a task annotation (`AiObjectDetectionTask.Annotation`). World fields appear only for placed AR frames; `ignore_reason` names why placement failed. */
+        type Annotation = AiObjectDetectionTask.Annotation;
+        interface XaiBox {
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        }
+        interface XaiCandidate {
+            class: number;
+            name: string;
+            score: number;
+        }
+        /** Per-detection top-k class scores of the pre-NMS anchor that produced the detection. `index` = position in `predictions`. */
+        interface XaiClassScore {
+            index: number;
+            class: number;
+            name: string;
+            confidence: number;
+            /** Detection box in original-image pixels (xyxy). */
+            box: XaiBox;
+            /** Top-k candidate classes of the winning anchor, best first. */
+            candidates: XaiCandidate[];
+            /** IoU between the detection box and the matched pre-NMS anchor box. */
+            match_iou?: number;
+        }
+        /** EigenCAM activation heatmap ("where did the model look"). RGBA PNG, alpha = activation. */
+        interface XaiHeatmap {
+            png_base64: string;
+            method: "eigencam";
+            layers?: string;
+            width: number;
+            height: number;
+        }
+        /** One detection's own Grad-CAM map ("why THIS box, this class"). `index` = position in `predictions`. */
+        interface XaiGradcamDetection {
+            index: number;
+            class: number;
+            name: string;
+            confidence: number;
+            /** Detection box in original-image pixels (xyxy). */
+            box: XaiBox;
+            match_iou?: number;
+            png_base64: string;
+            method?: "gradcam";
+            layers?: string;
+            target?: string;
+            width: number;
+            height: number;
+        }
+        /** TRUE gradient Grad-CAM ("what evidence drove the detections"). RGBA PNG, alpha = activation. */
+        interface XaiGradcam {
+            png_base64: string;
+            method: "gradcam";
+            layers?: string;
+            /** What was backpropagated (the Grad-CAM objective). */
+            target?: string;
+            /** Input size of the gradient pass (capped, default 960). */
+            imgsz?: number;
+            width: number;
+            height: number;
+            per_detection?: XaiGradcamDetection[];
+            /** Present when detections were truncated to the top-K. */
+            per_detection_note?: string;
+        }
+        /** One per-stage feature-map grid (ultralytics visualize=True), downscaled JPEG. */
+        interface XaiFeatureMap {
+            /** Network stage, e.g. `stage12_C2f`. */
+            stage: string;
+            jpg_base64: string;
+        }
+        interface XaiEmbeddingPoint {
+            /** Position of the detection in `predictions`. */
+            index: number;
+            class: number;
+            name: string;
+            confidence: number;
+            /** Projected coordinate, min-max normalized to [0, 1]. */
+            x: number;
+            /** Projected coordinate, min-max normalized to [0, 1]. */
+            y: number;
+        }
+        interface XaiEmbeddings {
+            /** The projection that actually ran (`none` for a single point). */
+            method: "umap" | "tsne" | "pca" | "none";
+            /** What the caller asked for (differs from `method` on fallback). */
+            requested_method?: EmbedMethod;
+            layer?: string;
+            /** Dimensionality of the pooled embedding before projection. */
+            embedding_dim?: number;
+            points: XaiEmbeddingPoint[];
+        }
+        /** Training-time confusion-matrix image URLs of the model version. */
+        interface XaiConfusionMatrix {
+            url: string | null;
+            normalized_url: string | null;
+            source: "training_artifacts";
+        }
+        /**
+         * Raw diagnosis-lambda Explainable-AI payload (passthrough). Any part can be
+         * missing — its failure reason is then appended to `notes`. When the diagnosis
+         * detections do not align with `predictions`, the index-bearing parts
+         * (`class_scores`, `gradcam.per_detection`, `embeddings.points`) are dropped and
+         * a note explains why.
+         */
+        interface Xai {
+            /** The parts that were requested. */
+            parts?: string[];
+            /** YOLO class index (stringified) → class name, from the model weights. */
+            class_names?: {
+                [classIndex: string]: string;
+            };
+            notes?: string[];
+            class_scores?: XaiClassScore[];
+            heatmap?: XaiHeatmap;
+            gradcam?: XaiGradcam;
+            feature_maps?: XaiFeatureMap[];
+            embeddings?: XaiEmbeddings;
+            confusion_matrix?: XaiConfusionMatrix | null;
+        }
+        /** The action response (`Create.Result`). There is no stored document for this service. */
+        interface Data {
+            task_id: StringId;
+            /** The detector that actually ran. */
+            engine: ResolvedEngine;
+            /** The VLM used when `engine` is `zero_shot`, else `null`. */
+            zero_shot_model: ZeroShotModel | null;
+            /** Resolved model `_id`; `null` for zero-shot runs. */
+            model: StringId | null;
+            /** Resolved model version `_id`, or `null`. */
+            model_version: StringId | null;
+            /** Public URL of the task image that was inferred. */
+            image_url: string;
+            /** `[height, width]` of the inferred image (detector-reported). `null` on an `explained_existing` response; may be absent if the detector omits it. */
+            shape?: number[] | null;
+            /** The confidence threshold that was applied. */
+            conf: number;
+            /** Whether the annotation group (or the grafted XAI) was persisted on the task. */
+            saved: boolean;
+            /** Present (true) when `explain_only` grafted XAI onto the existing group — no detector ran: `predictions` is empty, `shape`/`placed_count`/`unplaced_count`/`unmapped` are `null`, and `annotations` echoes the existing group's annotations. */
+            explained_existing?: true;
+            annotations_count: number;
+            /** Annotations placed in world coordinates (0 for non-session tasks). `null` on `explained_existing`. */
+            placed_count: number | null;
+            /** Annotations left 2D-only — each carries an `ignore_reason`. `null` on `explained_existing`. */
+            unplaced_count: number | null;
+            /** Predictions that could not be mapped to a label. `null` on `explained_existing`. */
+            unmapped: number | null;
+            annotations: Annotation[];
+            /** Raw detector predictions (passthrough). */
+            predictions: Prediction[];
+            /** Present only when `explain`/`explain_only` ran on the trained engine and the diagnosis lambda succeeded, else `null`. */
+            xai: Xai | null;
+            /** The saved task document when the group was persisted, else `null`. */
+            task: AiObjectDetectionTask.Data | null;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionTask {
+        type Subset = "train" | "val" | "test" | "auto" | "ignore";
+        /** Provenance of a whole annotation group. */
+        type AnnotationState = "auto" | "manual" | "auto_edited";
+        /** Provenance of a single box. */
+        type LabelState = "auto" | "manual";
+        /** Which detector produced a group: a trained model version (default) or a zero-shot VLM. */
+        type Engine = "trained" | "zero_shot";
+        /** Why a detection could NOT be placed in world coordinates (unset when placed). */
+        type IgnoreReason = "no_pose" | "no_intrinsics" | "no_depth" | "empty_depth_region" | "insufficient_depth_pixels" | "behind_shelf";
+        type ReclassificationReason = "dims_match_sibling" | "group_consensus" | "manual";
+        /**
+         * Mutually-exclusive review status used by the `annotation_status` find filter:
+         * `pending` = not annotated (or no groups); `confirmed` = annotated and the leading
+         * group is confirmed; `manual` / `auto_edited` = annotated, unconfirmed leading group
+         * with that state; `auto` = every remaining annotated, unconfirmed leading group.
+         */
+        type AnnotationStatus = "pending" | "confirmed" | "manual" | "auto_edited" | "auto";
+        /** Normalized box. Inference / the dashboard store YOLO center-size here: `x1` = cx, `y1` = cy, `x2` = w, `y2` = h. */
+        interface Box {
+            x1: number;
+            x2: number;
+            y1: number;
+            y2: number;
+        }
+        /** Back-projected centroid in world coordinates, metres. */
+        interface WorldPosition {
+            x: number;
+            y: number;
+            z: number;
+        }
+        /** Physical front-face size, centimetres (`w` = world-horizontal, `h` = vertical). */
+        interface WorldSize {
+            w: number;
+            h: number;
+        }
+        /** Size-gate provenance — set when the measured size exceeded the label's expected dims beyond the allowance. */
+        interface SizeRejectDetail {
+            exceeded?: "width" | "height" | "area";
+            measured_w_cm?: number;
+            measured_h_cm?: number;
+            expected_w_cm?: number;
+            expected_h_cm?: number;
+            /** measured / (expected × (1 + allowance)) for the tripped check. */
+            ratio?: number;
+        }
+        interface Annotation {
+            _id?: StringId;
+            box: Box;
+            /** Default 0.25. */
+            confidence?: number;
+            /** `ai-object-detection-label` `_id`. */
+            label_id: StringId;
+            label_state: LabelState;
+            /** Snapshot of the box geometry world placement last ran for; a box that no longer matches it is re-placed on the next save. */
+            placed_box?: Box;
+            world_position?: WorldPosition;
+            world_size?: WorldSize;
+            /** Metres — front-biased percentile (default p30) of the depth pixels over the whole bbox. */
+            depth_at_center?: number;
+            /** Normalized 0..1 depth confidence. */
+            depth_confidence?: number;
+            /** detection_conf × depth_conf × tracking, 0..1. */
+            placement_confidence?: number;
+            /** Link to the analysis object (`objects[]._id` on `ai-object-detection-session-analysis`) this detection was clustered into. */
+            cluster_id?: StringId;
+            ignore_reason?: IgnoreReason;
+            /** When the dims reclassifier moved this annotation to a sibling label, the FIRST original label is kept here. */
+            original_label?: StringId;
+            reclassification_reason?: ReclassificationReason;
+            /** Flagged (never deleted) when the measured size exceeded the label's expected dims; cleared when a later run passes it. */
+            size_rejected?: boolean;
+            size_reject_detail?: SizeRejectDetail;
+        }
+        interface XaiBox {
+            x1?: number;
+            y1?: number;
+            x2?: number;
+            y2?: number;
+        }
+        interface XaiCandidate {
+            class?: number;
+            name?: string;
+            score?: number;
+        }
+        /** Per-detection top-k class scores; `index` references the inference `predictions[]`, not `annotations[]`. */
+        interface XaiClassScore {
+            index?: number;
+            class?: number;
+            name?: string;
+            confidence?: number;
+            box?: XaiBox;
+            match_iou?: number;
+            candidates?: XaiCandidate[];
+        }
+        interface XaiEmbeddingPoint {
+            index?: number;
+            class?: number;
+            name?: string;
+            confidence?: number;
+            /** [0, 1] */
+            x?: number;
+            /** [0, 1] */
+            y?: number;
+        }
+        interface XaiFeatureMap {
+            /** Network stage, e.g. `stage12_C2f`. */
+            stage?: string;
+            /** Media ref of the stage grid JPEG. */
+            media?: StringId;
+            /** publicUrl snapshot of `media`. */
+            url?: string;
+        }
+        /** One detection's own Grad-CAM map ("why THIS box, this class"). */
+        interface XaiGradcamDetection {
+            index?: number;
+            class?: number;
+            name?: string;
+            confidence?: number;
+            box?: XaiBox;
+            match_iou?: number;
+            /** Media ref of this detection's RGBA PNG map. */
+            media?: StringId;
+            /** publicUrl snapshot of `media`. */
+            url?: string;
+            width?: number;
+            height?: number;
+        }
+        interface XaiEmbeddings {
+            /** The projection that actually ran. */
+            method?: "umap" | "tsne" | "pca" | "none";
+            /** What the caller asked for. */
+            requested_method?: "auto" | "umap" | "tsne" | "pca";
+            layer?: string;
+            embedding_dim?: number;
+            points?: XaiEmbeddingPoint[];
+        }
+        interface XaiConfusionMatrix {
+            url?: string;
+            normalized_url?: string;
+            source?: "training_artifacts";
+        }
+        /**
+         * Explainable-AI results persisted on a group produced with `explain: true`.
+         * Images live in media storage (refs + `*_url` publicUrl snapshots), never inline.
+         * `computed_at` marks real persisted XAI (withheld when no image could be stored).
+         */
+        interface GroupXai {
+            /** Which XAI parts were requested. */
+            parts?: string[];
+            /** Media ref of the EigenCAM RGBA PNG (alpha = activation). */
+            heatmap_media?: StringId;
+            heatmap_url?: string;
+            /** e.g. `eigencam`. */
+            heatmap_method?: string;
+            heatmap_width?: number;
+            heatmap_height?: number;
+            /** Media ref of the gradient Grad-CAM RGBA PNG. */
+            gradcam_media?: StringId;
+            gradcam_url?: string;
+            gradcam_width?: number;
+            gradcam_height?: number;
+            gradcam_per_detection?: XaiGradcamDetection[];
+            feature_maps?: XaiFeatureMap[];
+            class_scores?: XaiClassScore[];
+            embeddings?: XaiEmbeddings;
+            /** Training-time confusion-matrix image URLs of the model version. */
+            confusion_matrix?: XaiConfusionMatrix;
+            /** Reasons for any XAI part that could not be produced or persisted. */
+            notes?: string[];
+            /** Epoch ms when the XAI results were persisted. */
+            computed_at?: number;
+        }
+        /** Per-group session inference metadata (session inference only). */
+        interface SessionInference {
+            /** Dominant shelf plane this frame contributed to. */
+            plane_normal?: number[];
+            /** This group provided the winning detection. */
+            is_winner_in_cluster?: boolean;
+            cross_frame_overlap_pct?: number;
+        }
+        interface AnnotationGroup {
+            _id?: StringId;
+            /** `ai-object-detection-model-version` `_id`. */
+            model_version?: StringId;
+            engine?: Engine;
+            /** The zero-shot VLM used, e.g. `qwen/qwen3-vl-8b-instruct`. */
+            zero_shot_model?: string;
+            /** Opt-out training flag. Default true. */
+            usable?: boolean;
+            /** Epoch ms — set to now on create when missing. */
+            time?: number;
+            /** Epoch ms — server-stamped on every update. */
+            edit_time?: number;
+            annotation_state?: AnnotationState;
+            /** Default false. Server-set true for `manual` / `auto_edited` groups. */
+            confirmed?: boolean;
+            /** Server-stamped from the JWT when the group is confirmed and does not already carry a valid confirmer. */
+            confirmed_by?: AdminOrRep;
+            /** Server-set to `model_version` for `auto` groups on create. */
+            annotated_by_model_version_code?: StringId;
+            annotations?: Annotation[];
+            /** Link to the session's `inference_runs[]._id` (session inference only). */
+            inference_run?: StringId;
+            session_inference?: SessionInference;
+            xai?: GroupXai;
+        }
+        interface TaskDataset {
+            _id?: StringId;
+            /** `ai-object-detection-dataset` `_id`. */
+            dataset: StringId;
+            subset: Subset;
+        }
+        interface Intrinsics {
+            fx?: number;
+            fy?: number;
+            cx?: number;
+            cy?: number;
+        }
+        interface Distortion {
+            k1?: number;
+            k2?: number;
+            k3?: number;
+            p1?: number;
+            p2?: number;
+        }
+        interface Tracking {
+            state?: "NORMAL" | "LIMITED" | "LOST";
+            score?: number;
+            drift_m?: number;
+            velocity_mps?: number;
+        }
+        interface ImageStats {
+            iso?: number;
+            shutter?: number;
+            lux?: number;
+            /** Variance-of-Laplacian focus measure (higher = sharper). */
+            sharpness?: number;
+        }
+        /** Depth-map presence + confidence fractions (election input). */
+        interface DepthSummary {
+            width?: number;
+            height?: number;
+            conf_high?: number;
+            conf_medium?: number;
+            conf_low?: number;
+        }
+        /** Per-frame AR context, present only on session frames. */
+        interface FrameMeta {
+            /** Session-scoped frame counter. */
+            frame_id?: number;
+            /** Device epoch ms. */
+            ts?: number;
+            /** 16 floats, 4x4 pose matrix, column-major. */
+            pose?: number[];
+            /** 3 floats, degrees. */
+            euler_ypr?: number[];
+            intrinsics?: Intrinsics;
+            distortion?: Distortion;
+            tracking?: Tracking;
+            /** Shelf-distance gate (m) used when back-projecting this frame's detections. */
+            distance_to_shelf_m?: number;
+            /** CW degrees the sensor image was rotated to produce the stored image (0/90/180/270). */
+            image_rotation_deg?: number;
+            image_stats?: ImageStats;
+            depth_summary?: DepthSummary;
+            depth_source?: "lidar" | "estimated" | "none";
+            /** Nearest depth sample, metres. */
+            min_distance_depth?: number;
+            /** Farthest depth sample, metres. */
+            max_distance_depth?: number;
+            /** Depth span (max − min), metres. */
+            depth_variation?: number;
+            /** Camera euler at capture, degrees. */
+            yaw_degree?: number;
+            pitch_degree?: number;
+            roll_degree?: number;
+            /** Variance-of-Laplacian focus measure. */
+            frame_sharpness?: number;
+            /** Device validator verdict for the frame at capture time. */
+            capture_tier?: "good" | "warn" | "error";
+            /** Epoch ms of the app's last successful detection-settings poll. */
+            detection_settings_polled_at?: number;
+            /** App build that captured the frame. */
+            app_version?: string;
+        }
+        interface Data {
+            _id: StringId;
+            /** `media-storage` `_id` of the image. */
+            file_media: StringId;
+            shape?: number[];
+            annotation_groups?: AnnotationGroup[];
+            task_dataset?: TaskDataset[];
+            /** Server-stamped on create. */
+            creator?: AdminOrRep;
+            /** Server-stamped on update. */
+            editor?: AdminOrRep;
+            /** Server-derived: true when any confirmed group has annotations. */
+            annotated: boolean;
+            /** Parent `ai-object-detection-session` `_id` (session frames only). */
+            session?: StringId;
+            frame_meta?: FrameMeta;
+            /** Media `_id` of the raw float32 depth blob (session frames only). */
+            depth_media?: StringId;
+            /** Media `_id` of the raw uint8 confidence blob (session frames only). */
+            confidence_media?: StringId;
+            /** `[width, height]` of the depth blob. */
+            depth_shape?: number[];
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        /**
+         * Accepted `populatedKeys[]`. Top-level refs (`file_media`, `session`, `depth_media`,
+         * `confidence_media`) land under `<field>_populated` while the ref stays an id;
+         * nested paths (everything under `task_dataset.` / `annotation_groups.`) populate
+         * INLINE, replacing the id with the document.
+         */
+        type PopulatedKeys = "file_media" | "task_dataset.dataset" | "annotation_groups.model_version" | "annotation_groups.annotations.label_id" | "annotation_groups.annotations.original_label" | "annotation_groups.annotated_by_model_version_code" | "annotation_groups.xai.heatmap_media" | "annotation_groups.xai.gradcam_media" | "annotation_groups.xai.gradcam_per_detection.media" | "annotation_groups.xai.feature_maps.media" | "session" | "depth_media" | "confidence_media";
+        interface AnnotationPopulated extends Omit<Annotation, "label_id" | "original_label"> {
+            label_id: StringId | AiObjectDetectionLabel.Data;
+            original_label?: StringId | AiObjectDetectionLabel.Data;
+        }
+        interface GroupXaiPopulated extends Omit<GroupXai, "heatmap_media" | "gradcam_media" | "gradcam_per_detection" | "feature_maps"> {
+            heatmap_media?: StringId | MediaStorage.MediaStorageSchema;
+            gradcam_media?: StringId | MediaStorage.MediaStorageSchema;
+            gradcam_per_detection?: (Omit<XaiGradcamDetection, "media"> & {
+                media?: StringId | MediaStorage.MediaStorageSchema;
+            })[];
+            feature_maps?: (Omit<XaiFeatureMap, "media"> & {
+                media?: StringId | MediaStorage.MediaStorageSchema;
+            })[];
+        }
+        interface AnnotationGroupPopulated extends Omit<AnnotationGroup, "model_version" | "annotated_by_model_version_code" | "annotations" | "xai"> {
+            model_version?: StringId | AiObjectDetectionModelVersion.Data;
+            annotated_by_model_version_code?: StringId | AiObjectDetectionModelVersion.Data;
+            annotations?: AnnotationPopulated[];
+            xai?: GroupXaiPopulated;
+        }
+        interface TaskDatasetPopulated extends Omit<TaskDataset, "dataset"> {
+            dataset: StringId | AiObjectDetectionDataset.Data;
+        }
+        /** Find / Get row: `Data` plus the `*_populated` companions and inline-populated nested refs (only when the matching `populatedKeys[]` was requested). */
+        interface DataWithPopulatedKeys extends Omit<Data, "annotation_groups" | "task_dataset"> {
+            annotation_groups?: AnnotationGroupPopulated[];
+            task_dataset?: TaskDatasetPopulated[];
+            file_media_populated?: MediaStorage.MediaStorageSchema;
+            session_populated?: AiObjectDetectionSession.Data;
+            depth_media_populated?: MediaStorage.MediaStorageSchema;
+            confidence_media_populated?: MediaStorage.MediaStorageSchema;
+        }
+        /**
+         * An annotation group as sent on create. `annotation_state` is REQUIRED — a group
+         * without a valid one is rejected with 400 "Invalid annotation state". `manual` /
+         * `auto_edited` are marked `confirmed` (+ `confirmed_by` from the JWT); `auto`
+         * copies `model_version` into `annotated_by_model_version_code`. `time` defaults to now.
+         */
+        interface CreateAnnotationGroup extends Omit<AnnotationGroup, "annotation_state" | "confirmed_by" | "edit_time" | "annotated_by_model_version_code"> {
+            annotation_state: AnnotationState;
+        }
+        interface CreateBody {
+            /** Required — `media-storage` `_id` of the image. */
+            file_media: StringId;
+            shape?: number[];
+            annotation_groups?: CreateAnnotationGroup[];
+            task_dataset?: TaskDataset[];
+            session?: StringId;
+            frame_meta?: FrameMeta;
+            depth_media?: StringId;
+            confidence_media?: StringId;
+            depth_shape?: number[];
+            /** Optional tenant namespace override for SDK callers (otherwise injected from the session). */
+            company_namespace?: string[];
+        }
+        /**
+         * PUT body. `annotation_groups` REPLACES the stored array wholesale — resend every
+         * group to keep (with its `_id`). `editor` is server-stamped, `annotated` re-derived,
+         * `edit_time` restamped per group; a confirmed group keeps its existing `confirmed_by`.
+         * Human (`manual` / `auto_edited`) boxes whose geometry changed are re-placed in
+         * world coordinates on save (session frames), and a real content change schedules
+         * a session re-analysis. Set `disabled: true` to soft-delete.
+         */
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace" | "creator" | "editor" | "annotated">>;
+        /** Filters honoured by find (and by the bulk patch). Date bounds are epoch ms (or date strings). */
+        interface FilterParams {
+            _id?: StringId | StringId[];
+            /** Tasks (frames) belonging to a session `_id`. */
+            session?: StringId | StringId[];
+            /** Session-scoped frame counter. */
+            "frame_meta.frame_id"?: number | number[];
+            /** Tasks belonging to a dataset `_id`. */
+            "task_dataset.dataset"?: StringId | StringId[];
+            /** Whether the task has any confirmed annotations. */
+            annotated?: boolean;
+            /** Omitted / false = active tasks only; true = disabled tasks only. */
+            disabled?: boolean;
+            from_createdAt?: number;
+            to_createdAt?: number;
+            from_updatedAt?: number;
+            to_updatedAt?: number;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & FilterParams & {
+                /** Only tasks with at least one annotation (in any group) referencing the given label id(s) — surfaces candidate crops for a label's reference photo. */
+                annotated_label?: StringId | StringId[];
+                /** Mutually-exclusive review status filter (applied before counting / pagination). Invalid values → 400. */
+                annotation_status?: AnnotationStatus;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            /** 400 (not 404) when the id is unknown in the caller's namespace. */
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Patch {
+            /** Query filters selecting the tasks to bulk-update (e.g. `{ session }` for "approve all auto"). No pagination / population. */
+            type Params = FilterParams;
+            interface WriteQuery {
+                /** Dotted document path, e.g. `annotation_groups.0.confirmed`. */
+                key: string;
+                /** `set` → `$set`; `addToSet` → `$addToSet: { $each: value }`; `pull` → `$pull: { $in: value }`. */
+                command: "set" | "addToSet" | "pull";
+                value: any;
+            }
+            type Body = {
+                writeQuery: WriteQuery[];
+            };
+            interface Result {
+                /** Matched documents. */
+                nFound: number;
+                /** Modified documents. */
+                nModified: number;
+            }
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The task after soft-deletion (`disabled: true`). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionSession {
+        /** Lifecycle FSM. `uploaded` is written by the device's upload-complete marker, `infer_in_progress`/`inferred`/`failed` by analysis runs; `rearbitrating` is reserved/legacy (no writer). */
+        type SessionStatus = "open" | "uploaded" | "infer_in_progress" | "inferred" | "rearbitrating" | "failed";
+        /** Articulated election verdict derived from `session_score` against the namespace detection-settings score bands. */
+        type SessionVerdict = "excellent" | "good" | "acceptable" | "rejected";
+        interface Device {
+            platform?: string;
+            os?: string;
+            model?: string;
+            app_version?: string;
+            ar_engine?: "ARKit" | "ARCore";
+        }
+        interface CaptureSettings {
+            /** AR frame capture rate the app was set to (Hz). */
+            rate_hz?: number;
+            recording_enabled?: boolean;
+            target_distance_m?: number;
+            /** Camera format preference active during capture. */
+            resolution?: "medium" | "high" | "max" | string;
+        }
+        /** Floor lock measured on-device at capture entry; absent when the rep skipped the floor point. Height above floor of any world point = y - y_world. */
+        interface Ground {
+            /** Floor height (world Y), metres. */
+            y_world?: number;
+            /** Gated depth samples behind the median. */
+            samples?: number;
+            /** Interquartile spread of the samples, metres (lock quality). */
+            spread_m?: number;
+            /** Camera height above the floor at lock time, metres. */
+            camera_height_m?: number;
+        }
+        /** A frame excluded from an election because it violated the error-tier limits. */
+        interface ElectionExcluded {
+            task?: StringId;
+            /** e.g. `sharpness`, `tracking`, `too_near`, `too_far`, `yaw_delta`, `pitch_delta`, `roll_delta`. */
+            violations?: string[];
+        }
+        /** Legacy scene plane (from the removed in-session build_scene flow). */
+        interface Plane {
+            _id?: StringId;
+            kind?: "shelf" | "floor" | "wall";
+            /** 3-float plane normal. */
+            normal?: number[];
+            /** Plane equation constant in Ax+By+Cz+d=0. */
+            d?: number;
+            inliers?: number;
+            bounds?: {
+                min?: number[];
+                max?: number[];
+            };
+        }
+        interface PointCloudStats {
+            n_points?: number;
+            voxel_size_m?: number;
+            bbox_min?: number[];
+            bbox_max?: number[];
+        }
+        /** Legacy scene-level outputs; retained for older data, no longer written. */
+        interface Scene {
+            planes?: Plane[];
+            /** `media.mediaStorages` id of the .ply / .npy point cloud. */
+            point_cloud_media?: StringId;
+            point_cloud_stats?: PointCloudStats;
+            /** Coordinate system the world positions are reported in. */
+            world_frame?: "arkit" | "arcore" | "normalized";
+        }
+        /** Legacy cross-frame fused object (fused output now lives on `ai-object-detection-session-analysis`). */
+        interface SessionObject {
+            _id?: StringId;
+            label_id?: StringId;
+            /** How many frames contributed to this object. */
+            cluster_size?: number;
+            world_position?: {
+                x?: number;
+                y?: number;
+                z?: number;
+            };
+            world_orientation?: {
+                yaw?: number;
+                pitch?: number;
+                roll?: number;
+            };
+            bbox_3d?: {
+                min?: number[];
+                max?: number[];
+            };
+            /** Fused 0..1 placement confidence. */
+            placement_confidence?: number;
+            winning_task?: StringId;
+            winning_annotation_id?: StringId;
+            contributing_tasks?: StringId[];
+            /** Weights / tiebreak rationale. */
+            arbitration?: any;
+        }
+        /** Legacy per-run inference record (analysis runs are now their own documents). */
+        interface InferenceRun {
+            _id?: StringId;
+            model_version?: StringId;
+            started_at?: number;
+            finished_at?: number;
+            /** Clustering params, RANSAC config. */
+            config?: any;
+            status?: "pending" | "success" | "failed";
+            triggered_by?: AdminOrRep;
+            notes?: string;
+        }
+        interface Data {
+            _id: StringId;
+            company_namespace: string[];
+            disabled: boolean;
+            /** Device-generated session id (4-char); unique per namespace among active rows. Election clones carry a `-E<n>` suffix. */
+            session_id?: string;
+            /** Provenance: set when this session was materialized from an election over another session's frames. */
+            source_session?: StringId;
+            device?: Device;
+            /** `clients` _id of the scanned store (stamped by the frame intake). */
+            client?: StringId;
+            /** `ai-object-detection-category` _id picked on the device; drives the auto-analysis fired by the upload-complete marker. */
+            category?: StringId;
+            /** `ai-object-detection-mission` _id the session was started FROM ("SCAN THIS MISSION"); attribution anchor for mission results. */
+            mission?: StringId;
+            /** `representatives` _id sent on the frames (defaults to the rep in the token). */
+            rep?: StringId;
+            /** DEVICE visit id (`visits.visit_id`) the scan happened in — stored as-is, never resolved to a server ref. */
+            visit_id?: string;
+            /** `sv.routes` _id of the visit's route. */
+            route?: StringId;
+            /** Business day of the scan, `YYYY-MM-DD` — as sent by the device, else stamped once from the capture time. */
+            business_day?: string;
+            /** IANA timezone of the device at capture. */
+            time_zone?: string;
+            capture_settings?: CaptureSettings;
+            /** Device-computed swept shelf area, m² (includes quality-rejected attempts, so it cannot be recomputed server-side). */
+            coverage_m2?: number;
+            ground?: Ground;
+            /** Camera height above the locked floor while shooting, metres (the rep's standing eye level). Server self-heals it from poses when missing. */
+            eye_level_m?: number;
+            /** The rep tapped Skip on the floor point (deliberate skip vs a lock that never converged). */
+            ground_skipped?: boolean;
+            /** 'gravity' on both ARKit/ARCore — recorded, not assumed. */
+            world_alignment?: string;
+            /** Election evaluation: average frame quality, 0..1. */
+            session_score?: number;
+            session_verdict?: SessionVerdict;
+            /** e.g. `coverage_below_target`, `jump_detected`, `too_many_elected`. */
+            rejection_reasons?: string[];
+            election_excluded?: ElectionExcluded[];
+            status: SessionStatus;
+            _errors?: any[];
+            /** Incremented by the frame intake. */
+            frames_total: number;
+            /** Frames that passed validation (incremented by the frame intake). */
+            frames_accepted: number;
+            /** Frames materialized as tasks (incremented by the frame intake). */
+            tasks_count: number;
+            /** Refreshed on every successful analysis run. */
+            detections_count: number;
+            /** Refreshed on every successful analysis run. */
+            objects_count: number;
+            scene?: Scene;
+            objects?: SessionObject[];
+            inference_runs?: InferenceRun[];
+            /** The rep/admin who scanned (server-stamped on create). */
+            creator?: AdminOrRep;
+            /** Server-stamped on update. */
+            editor?: AdminOrRep;
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "client" | "category" | "inference_runs.model_version" | "objects.label_id" | "scene.point_cloud_media";
+        interface InferenceRunWithPopulatedKeys extends Omit<InferenceRun, "model_version"> {
+            /** Populated in place when `inference_runs.model_version` is requested. */
+            model_version?: StringId | AiObjectDetectionModelVersion.Data;
+        }
+        interface SessionObjectWithPopulatedKeys extends Omit<SessionObject, "label_id"> {
+            /** Populated in place when `objects.label_id` is requested. */
+            label_id?: StringId | AiObjectDetectionLabel.Data;
+        }
+        interface SceneWithPopulatedKeys extends Omit<Scene, "point_cloud_media"> {
+            /** Populated in place when `scene.point_cloud_media` is requested. */
+            point_cloud_media?: StringId | MediaStorage.MediaStorageSchema;
+        }
+        /** `client` / `category` keep their ids and add `<key>_populated`; the nested keys are populated in place. */
+        interface DataWithPopulatedKeys extends Omit<Data, "inference_runs" | "objects" | "scene"> {
+            client_populated?: Client.ClientSchema;
+            category_populated?: AiObjectDetectionCategory.Data;
+            inference_runs?: InferenceRunWithPopulatedKeys[];
+            objects?: SessionObjectWithPopulatedKeys[];
+            scene?: SceneWithPopulatedKeys;
+        }
+        /** Explicit/manual session creation (sessions are normally upserted by the frame intake). `creator` and counters are server-managed. */
+        interface CreateBody {
+            session_id?: string;
+            source_session?: StringId;
+            device?: Device;
+            client?: StringId;
+            category?: StringId;
+            mission?: StringId;
+            rep?: StringId;
+            visit_id?: string;
+            route?: StringId;
+            business_day?: string;
+            time_zone?: string;
+            capture_settings?: CaptureSettings;
+            coverage_m2?: number;
+            ground?: Ground;
+            eye_level_m?: number;
+            ground_skipped?: boolean;
+            world_alignment?: string;
+            /** Defaults to `open`. */
+            status?: SessionStatus;
+            company_namespace?: string[];
+        }
+        /** PUT accepts any stored field; `editor` is server-stamped. Set `disabled: true` to soft-delete. */
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace" | "creator" | "editor">>;
+        /** Filter keys honoured by `find` and by the bulk `patch`. */
+        type FilterParams = {
+            _id?: StringId | StringId[];
+            session_id?: string | string[];
+            status?: SessionStatus | SessionStatus[];
+            client?: StringId | StringId[];
+            category?: StringId | StringId[];
+            rep?: StringId | StringId[];
+            visit_id?: string | string[];
+            route?: StringId | StringId[];
+            "creator._id"?: StringId | StringId[];
+            "inference_runs.model_version"?: StringId | StringId[];
+            from_updatedAt?: number;
+            to_updatedAt?: number;
+            from_createdAt?: number;
+            to_createdAt?: number;
+            /** Regex on `name` — sessions carry no `name`, so this matches nothing; listed only because the shared query helper honours it. */
+            search?: string;
+            /** Include disabled (soft-deleted) sessions. */
+            disabled?: boolean;
+        };
+        interface WriteQuery {
+            key: string;
+            command: "set" | "addToSet" | "pull";
+            value: any;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & FilterParams & {
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        /** Bulk update: `writeQuery[]` is applied to every session matching the query filters. */
+        namespace Patch {
+            type Params = FilterParams;
+            type Body = {
+                writeQuery: WriteQuery[];
+            };
+            type Result = {
+                nFound: number;
+                nModified: number;
+            };
+        }
+        namespace Remove {
+            type ID = StringId;
+            interface Params {
+                /** When `true`, also soft-delete the session's child tasks (default: tasks are kept as training data). */
+                cascade?: boolean;
+            }
+            type Result = Data;
+        }
+    }
+    namespace ActivityAiObjectDetectionSessionFrame {
+        interface Device {
+            platform?: string;
+            os?: string;
+            model?: string;
+            app_version?: string;
+            ar_engine?: "ARKit" | "ARCore";
+        }
+        interface CaptureSettings {
+            rate_hz?: number;
+            recording_enabled?: boolean;
+            target_distance_m?: number;
+            resolution?: "medium" | "high" | "max" | string;
+        }
+        /** Floor lock from the capture entry phase (skippable on the device). */
+        interface Ground {
+            y_world?: number;
+            samples?: number;
+            spread_m?: number;
+            camera_height_m?: number;
+        }
+        /** Per-frame AR metadata carried in `meta_inline` (JSON). Fields map onto the materialized task's `frame_meta`; camelCase device aliases (`trackingScore`, `eulerYPR`, `imageStats`, `driftM`, `velocityMps`, `imageRotationDeg`, `depth.{width,height,minM,maxM,distanceToShelfM,confidence}`) are also tolerated. */
+        interface MetaInline {
+            /** Device-generated session id (4-char). Required here or as the top-level `session_id`. */
+            session_id?: string;
+            /** Fallback `media.mediaStorages` _id of the frame image when not sent top-level. */
+            media_id?: string;
+            /** Session-scoped frame counter. */
+            frame_id?: number;
+            /** Device epoch (ms). */
+            ts?: number;
+            /** 16-float 4x4 pose matrix, column-major. */
+            pose?: number[];
+            /** 3-float yaw/pitch/roll in degrees. */
+            euler_ypr?: number[];
+            intrinsics?: {
+                fx: number;
+                fy: number;
+                cx: number;
+                cy: number;
+            };
+            distortion?: {
+                k1?: number;
+                k2?: number;
+                k3?: number;
+                p1?: number;
+                p2?: number;
+            };
+            tracking?: {
+                state?: "NORMAL" | "LIMITED" | "LOST";
+                /** 0..1 (a 0..100 device value is normalized). */
+                score?: number;
+                drift_m?: number;
+                velocity_mps?: number;
+            };
+            /** Shelf-distance gate (metres) captured at the frame. */
+            distance_to_shelf_m?: number;
+            image_stats?: {
+                iso?: number;
+                shutter?: number;
+                lux?: number;
+                /** Variance-of-Laplacian focus measure; -1 = unmeasured. */
+                sharpness?: number;
+            };
+            /** Depth-map summary from the device (width/height + confidence fractions persist on `frame_meta.depth_summary`). */
+            depth?: {
+                width?: number;
+                height?: number;
+                minM?: number;
+                maxM?: number;
+                distanceToShelfM?: number;
+                confidence?: {
+                    high?: number;
+                    medium?: number;
+                    low?: number;
+                };
+            };
+            depth_source?: "lidar" | "estimated" | "none";
+            /** [width, height] of the depth blob. */
+            depth_shape?: number[];
+            /** [width, height] of the image. */
+            image_shape?: number[];
+            /** Nearest depth sample in the frame, metres (app >= 0.39.0). */
+            min_distance_depth?: number;
+            /** Farthest depth sample in the frame, metres. */
+            max_distance_depth?: number;
+            /** Depth span (max - min), metres. */
+            depth_variation?: number;
+            yaw_degree?: number;
+            pitch_degree?: number;
+            roll_degree?: number;
+            /** Variance-of-Laplacian focus measure (higher = sharper). */
+            frame_sharpness?: number;
+            /** Device validator verdict for the frame at capture time. */
+            capture_tier?: "good" | "warn" | "error";
+            /** Epoch ms of the app's last successful detection-settings poll before this frame. */
+            detection_settings_polled_at?: number;
+            /** Degrees the sensor image was rotated CW to produce the stored image. */
+            image_rotation_deg?: number;
+            /** Applied to the session on first frame; `app_version` is also persisted per frame. */
+            device?: Device;
+            /** Applied to the session on first frame. */
+            capture_settings?: CaptureSettings;
+            /** Device-computed swept shelf area for the whole session so far, m² (upserted onto the session via $max). */
+            coverage_m2?: number;
+            /** 'gravity' on both ARKit and ARCore. */
+            world_alignment?: string;
+            ground?: Ground;
+            /** Camera height above the locked floor while shooting, metres. */
+            eye_level_m?: number;
+            /** True when the rep tapped Skip on the floor point. */
+            ground_skipped?: boolean;
+            /** `ai-object-detection-category` _id picked on the device (non-fatal when it no longer exists). */
+            category?: string;
+            /** `ai-object-detection-mission` _id the session was started FROM (non-fatal when it no longer exists). */
+            mission?: string;
+            /** Alias of the top-level `visit_id` (the top-level field wins). */
+            visit_id?: string;
+            /** Alias of the top-level `route`. */
+            route?: string;
+            /** Alias of the top-level `business_day`. */
+            business_day?: string;
+            /** Alias of the top-level `time_zone`. */
+            time_zone?: string;
+            /** Completion marker — a frameless POST sent once the upload queue drains. */
+            session_complete?: boolean | string;
+        }
+        interface FrameGeoTag {
+            lat: number;
+            lng: number;
+            formatted_address?: string;
+            extra?: any;
+        }
+        /** The stored activity frame document (collection `ai.objectDetectionSessionFrames`). The image, `frame_meta` and depth/confidence media live on the referenced `task`. Not readable through this service — query tasks by `?session=` instead. */
+        interface Data {
+            _id: StringId;
+            company_namespace: string[];
+            /** `clients` _id the captured shelf belongs to. */
+            client: StringId;
+            /** `representatives` _id of the capturing rep. */
+            rep?: StringId;
+            /** Parent `ai-object-detection-session` _id. */
+            session: StringId;
+            /** Device-generated session id. */
+            session_id?: string;
+            /** The materialized `ai-object-detection-task` _id. */
+            task?: StringId;
+            /** DEVICE visit id (`visits.visit_id`), stored as-is. */
+            visit_id?: string;
+            /** `sv.routes` _id. */
+            route?: StringId;
+            /** `YYYY-MM-DD`. */
+            business_day?: string;
+            time_zone?: string;
+            geo_tag?: FrameGeoTag;
+            /** Device epoch ms of the capture. */
+            time?: number;
+            creator?: AdminOrRep;
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        /** JSON-equivalent of the multipart frame intake. For a FRAME post `client`, `media_id` (top-level or in `meta_inline`) and `session_id` (top-level or in `meta_inline`) are required; for the COMPLETION marker only `session_id` + `session_complete: true`. */
+        interface CreateBody {
+            /** `media.mediaStorages` _id of the pre-uploaded RGB frame image (becomes the task's `file_media`). */
+            media_id?: StringId;
+            /** Fallback device session id when not present inside `meta_inline`. */
+            session_id?: string;
+            /** Per-frame AR metadata — JSON string or already-parsed object. */
+            meta_inline?: string | MetaInline;
+            /** Alias for `meta_inline`. */
+            meta?: string | MetaInline;
+            /** `clients` _id the captured shelf belongs to (must exist and not be disabled in the namespace). */
+            client?: StringId;
+            /** `representatives` _id of the capturing rep; defaults to the rep in the token. */
+            rep?: StringId;
+            /** DEVICE visit id (`visits.visit_id`) the scan happened in — stored as-is on the frame and the parent session. */
+            visit_id?: string;
+            /** `sv.routes` _id of the visit's route. */
+            route?: StringId;
+            /** `YYYY-MM-DD` (rejected otherwise). When absent the session is stamped once from the capture time under the rep's stamping context. */
+            business_day?: string;
+            /** IANA timezone of the device at capture. */
+            time_zone?: string;
+            /** `{ lat, lng, formatted_address? }` — JSON string in multipart bodies; `lat`/`lng` must be numeric. */
+            geo_tag?: string | {
+                lat?: number;
+                lng?: number;
+                formatted_address?: string;
+            };
+            /** Device epoch ms of the capture. */
+            time?: number | string;
+            /** Completion-marker mode (alias of `meta_inline.session_complete`). */
+            session_complete?: boolean | string;
+            company_namespace?: string[];
+        }
+        /** Response of a frame post. */
+        interface FrameResult {
+            /** The parent session `_id`. */
+            session: StringId;
+            session_id: string;
+            /** The materialized task `_id`. */
+            task: StringId;
+            /** The activity frame document `_id`. */
+            frame: StringId;
+            frame_id?: number;
+            client: StringId;
+            /** Media id of the frame image (= `media_id`). */
+            file_media: StringId;
+            /** Media id of the uploaded depth blob, if a `depth` file part was sent. */
+            depth_media?: StringId;
+            /** Media id of the uploaded confidence blob, if a `confidence` file part was sent. */
+            confidence_media?: StringId;
+        }
+        /** Whether the category auto-analysis was fired by the completion marker. */
+        interface AutoAnalysisResult {
+            triggered: boolean;
+            /** Present when not triggered: `no_category`, `category_has_no_model_settings`, `session_verdict_rejected`, `error`. */
+            reason?: string;
+            category?: StringId;
+            /** Number of category `model_settings` items queued (run serially in the background). */
+            runs?: number;
+        }
+        /** Response of a `session_complete: true` (frameless) post. */
+        interface SessionCompleteResult {
+            session: StringId;
+            session_id: string;
+            status: "uploaded";
+            auto_analysis: AutoAnalysisResult;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = FrameResult | SessionCompleteResult;
+        }
+    }
+    namespace AiObjectDetectionSessionAnalysis {
+        /** `pending` (opened) → `in_progress` (background job started) → `success` | `failed` (`_errors`). */
+        type AnalysisStatus = "pending" | "in_progress" | "success" | "failed";
+        /** Fusion / composition tuning knobs (`SceneMathConfig`). Every key is optional — omit for the server defaults. */
+        interface SceneMathConfig {
+            /** Run-level alias of the top-level `inference_concurrency` (1..10, default 4); the top-level field wins. */
+            inference_concurrency?: number;
+            /** Base world distance to merge detections into one object (default 0.08 m). */
+            cluster_eps_m?: number;
+            /** Extra merge radius when labels match (default 0.02 m). */
+            class_agree_bonus_m?: number;
+            /** A scene object absorbs at most ONE detection per frame (default true). */
+            block_same_frame?: boolean;
+            /** Ignore depth below this (default 0.05 m). */
+            min_depth_m?: number;
+            /** Ignore depth above this (default 6 m). */
+            max_depth_m?: number;
+            /** Min ARKit depth-confidence to keep a pixel: 0/1/2 (default 1). */
+            conf_threshold?: number;
+            /** Percentile of bbox depths to take, front-biased (default 30). */
+            front_percentile?: number;
+            /** Depth gate slack beyond `distance_to_shelf_m` (default 0.30 m). */
+            shelf_tolerance_m?: number;
+            /** Same-frame gate: same-label 2D IoU at/above this = duplicate box (default 0.92). */
+            same_frame_iou_thresh?: number;
+            /** Same-frame gate: same-label world distance below this = same spot (default 0.02 m). */
+            same_frame_min_separation_m?: number;
+            /** Same-frame gate: drop detections under this detector confidence (default 0 = off). */
+            min_detection_confidence?: number;
+            /** Same-frame gate: drop implausibly small front faces (default 0.5 cm). */
+            min_object_size_cm?: number;
+            /** Same-frame gate: drop implausibly large front faces (default 500 cm). */
+            max_object_size_cm?: number;
+            /** Cross-frame matcher: consensus-plane projection matching (default true). */
+            plane_merge?: boolean;
+            /** Min projected-rect IoU to merge (default 0.1). */
+            plane_merge_iou?: number;
+            /** Max plane-depth difference to merge, metres (default 0.25). */
+            plane_merge_depth_delta_m?: number;
+            /** Dims reclassifier master switch (default false). */
+            reclassify_labels?: boolean;
+            reclassify_keep_dev?: number;
+            reclassify_target_dev?: number;
+            reclassify_min_margin?: number;
+            reclassify_conf_margin_scale?: number;
+            reclassify_weight_scale?: number;
+            reclassify_weight_aspect?: number;
+            reclassify_min_depth_confidence?: number;
+            /** Post-walk merge of overlapping same-group clusters (default true; only with `reclassify_labels`). */
+            group_consensus_merge?: boolean;
+            /** Physical size gate master switch (default true). */
+            size_gate?: boolean;
+            size_gate_dims_allowance?: number;
+            size_gate_area_allowance?: number;
+            size_gate_min_depth_confidence?: number;
+            /** Shelf composition master switch (default true). */
+            shelf_analysis?: boolean;
+            shelf_support_min_overlap?: number;
+            shelf_gap_split_m?: number;
+            shelf_min_spacing_m?: number;
+            shelf_stack_max_penetration_m?: number;
+            shelf_row_split_m?: number;
+            shelf_min_stacks?: number;
+            /** Build + store the voxel point cloud and RANSAC shelf planes (default true). */
+            build_point_cloud?: boolean;
+            pc_stride?: number;
+            pc_voxel_size_m?: number;
+            ransac_max_planes?: number;
+            ransac_min_inlier_ratio?: number;
+            ransac_distance_thresh_m?: number;
+        }
+        interface Vec3 {
+            x?: number;
+            y?: number;
+            z?: number;
+        }
+        /** 2D box (YOLO-normalized cx, cy, w, h as stored by the backend). */
+        interface Box2D {
+            x1?: number;
+            y1?: number;
+            x2?: number;
+            y2?: number;
+        }
+        interface ArbitrationScore {
+            task_id?: StringId;
+            annotation_id?: StringId;
+            frame_id?: number;
+            score?: number;
+            winner?: boolean;
+            /** Six normalized inputs of the weighted view score. */
+            inputs?: {
+                det?: number;
+                depth?: number;
+                track?: number;
+                center?: number;
+                size?: number;
+                agree?: number;
+            };
+        }
+        /** Winner-selection rationale (mixed-type field on the model). */
+        interface Arbitration {
+            strategy?: string;
+            weights?: {
+                [factor: string]: number;
+            };
+            scores?: ArbitrationScore[];
+            [key: string]: any;
+        }
+        /** A concluded object on the shelf (one per cross-frame cluster). */
+        interface AnalysisObject {
+            /** Contributing task annotations carry this id in their `cluster_id` after the run succeeds. */
+            _id: StringId;
+            label_id?: StringId;
+            label_name?: string;
+            /** `kept` = single facing, `merged` = several facings fused. */
+            state?: "kept" | "merged";
+            /** Fused placement confidence, 0..1. */
+            confidence?: number;
+            /** Centroid in world coordinates, metres. */
+            world?: Vec3;
+            /** Physical front-face size, centimetres. */
+            size?: {
+                w?: number;
+                h?: number;
+            };
+            /** Distance from the camera, metres. */
+            depth?: number;
+            /** Metres above the device-locked floor; null when the rep skipped the floor point. */
+            height_above_ground_m?: number | null;
+            /** Facing rotation about world-Y, radians; null when the winning task lacks a pose. */
+            yaw?: number | null;
+            /** How many facings/frames contributed. */
+            cluster_size?: number;
+            bbox_3d?: {
+                min?: number[];
+                max?: number[];
+            };
+            winning_task?: StringId;
+            winning_annotation_id?: StringId;
+            /** Winner's 2D crop region on `winning_image_media`. */
+            winning_box?: Box2D;
+            /** `media.mediaStorages` id of the winning frame image (crop source). */
+            winning_image_media?: StringId;
+            contributing_tasks?: StringId[];
+            arbitration?: Arbitration;
+        }
+        /** Per-label conclusion — detection counts by outcome. */
+        interface ConcludedLabel {
+            _id?: StringId;
+            label_id?: StringId;
+            label_name?: string;
+            /** Detections placed as a single facing. */
+            kept: number;
+            /** Detections fused into multi-facing objects. */
+            merged: number;
+            /** Detections that could not be placed. */
+            ignored: number;
+            /** Detections removed by same-frame quality gates. */
+            dropped: number;
+            /** Detections dropped by the physical-size gate. */
+            size_rejected: number;
+            /** Resulting objects (kept + merged clusters). */
+            object_count: number;
+        }
+        /** A detection that could not be placed in world coordinates. */
+        interface IgnoredDetection {
+            _id?: StringId;
+            task?: StringId;
+            annotation_id?: StringId;
+            label_id?: StringId;
+            frame_id?: number;
+            /** `no_pose`, `no_intrinsics`, `no_depth`, `empty_depth_region`, `insufficient_depth_pixels`, `behind_shelf`, or `not_placed`. */
+            reason?: string;
+        }
+        type LedgerDisposition = "new_object" | "re_observation" | "dropped_same_frame" | "size_rejected" | "unplaced";
+        /** Audit trail of ONE detection through the fusion pipeline — where it went and why. */
+        interface DetectionLedgerEntry {
+            _id?: StringId;
+            task?: StringId;
+            annotation_id?: StringId;
+            label_id?: StringId;
+            label_name?: string;
+            frame_id?: number;
+            disposition?: LedgerDisposition;
+            /** Machine cause: `first_observation`, `re_observation`, `duplicate_box_in_frame`, `same_spot_in_frame`, `below_min_confidence`, `implausible_size`, `size_gate`, or an unplaced reason. */
+            reason?: string;
+            /** Human-readable explanation, ready to render. */
+            detail?: string;
+            /** The `objects[]._id` this detection created or merged into. */
+            object_id?: StringId;
+            /** For same-frame drops — the stronger sibling that was kept. */
+            kept_by_annotation_id?: StringId;
+            /** For re-observations — world distance to the object, metres. */
+            matched_distance_m?: number;
+            world?: Vec3;
+            box?: Box2D;
+            confidence?: number;
+            placement_confidence?: number;
+        }
+        /** Fusion funnel counters — the "where did the detections go" summary. */
+        interface AnalysisFunnel {
+            tasks?: number;
+            /** Frames whose boxes came from a confirmed HUMAN annotation group. */
+            tasks_manual?: number;
+            detections_total?: number;
+            unplaced?: number;
+            size_rejected?: number;
+            frames?: number;
+            detections_placed?: number;
+            dropped_same_frame?: number;
+            re_observations?: number;
+            new_objects?: number;
+            /** After the group-consensus merge. */
+            clusters_final?: number;
+        }
+        /** Which annotation group each frame contributed (human truth first). */
+        interface FrameSource {
+            _id?: StringId;
+            task?: StringId;
+            group_id?: StringId;
+            annotation_state?: "auto" | "manual" | "auto_edited";
+            model_version?: StringId;
+            /** Lets the UI flag analyses older than a frame's latest correction. */
+            edit_time?: number;
+        }
+        /** Per-stage config hashes; staleness is a fingerprint diff. */
+        interface StageFingerprints {
+            detect: string;
+            fuse: string;
+            compose: string;
+        }
+        interface ComposedStack {
+            /** 0 = leftmost as the shopper sees the shelf. */
+            index?: number;
+            u_from?: number;
+            u_to?: number;
+            y_from?: number;
+            y_to?: number;
+            /** Plane depth of the stack (m; larger = closer to the shopper). */
+            s?: number;
+            /** 0 = front row (closest to the shopper). */
+            row?: number;
+            /** Refs into `objects[]._id`, ordered bottom-up. */
+            object_ids?: StringId[];
+        }
+        interface ComposedShelf {
+            /** 0 = the lowest shelf. */
+            index?: number;
+            /** Board level (world Y, metres). */
+            y_world?: number;
+            /** Shelf level above the device-locked floor; null when not locked. */
+            height_above_ground_m?: number | null;
+            u_from?: number;
+            u_to?: number;
+            /** Median plane depth of member stacks (metres). */
+            s?: number;
+            stacks?: ComposedStack[];
+        }
+        /** Planogram structure (shelves → stacks → objects) composed from the fused objects' world geometry. */
+        interface ShelfComposition {
+            /** Orthonormal basis: `n` = horizontal unit normal toward the shopper, `u` = up × n (shopper's right). */
+            plane?: {
+                n?: number[];
+                u?: number[];
+            };
+            orientation?: "shopper" | string;
+            shelves?: ComposedShelf[];
+            /** Objects that didn't land on a shelf level (hook walls, sparse levels). */
+            unshelved?: {
+                object_id?: StringId;
+                reason?: string;
+            }[];
+        }
+        /** Bounded shelf plane peeled off the voxel cloud by RANSAC. */
+        interface ShelfPlane {
+            normal?: number[];
+            /** A point on the plane (inlier centroid), metres. */
+            point?: number[];
+            extent_min?: number[];
+            extent_max?: number[];
+            inlier_count?: number;
+            /** Inliers / cloud points, 0..1. */
+            inlier_ratio?: number;
+        }
+        /** Scene-level outputs — all best-effort (omitted when they can't be computed). */
+        interface AnalysisScene {
+            /** Dominant plane over all placed detections (legacy single plane). */
+            plane?: {
+                normal?: number[];
+                d?: number;
+                centroid?: number[];
+                inliers?: number;
+            };
+            /** RANSAC shelf planes, strongest first. */
+            planes?: ShelfPlane[];
+            /** Voxel point cloud metadata; the packed Float32 `[x,y,z,r,g,b,w]` blob lives in `media` (bin). */
+            point_cloud?: {
+                media?: StringId;
+                num_points?: number;
+                voxel_size_m?: number;
+                aabb_min?: number[];
+                aabb_max?: number[];
+            };
+        }
+        interface Data {
+            _id: StringId;
+            company_namespace: string[];
+            disabled: boolean;
+            /** The analyzed `ai-object-detection-session` _id. */
+            session: StringId;
+            /** `ai-object-detection-model-version` _id used to infer not-yet-placed tasks. */
+            model_version?: StringId;
+            config?: SceneMathConfig;
+            status: AnalysisStatus;
+            /** Epoch ms. */
+            started_at?: number;
+            /** Epoch ms. */
+            finished_at?: number;
+            /** Liveness heartbeat (epoch ms) refreshed by the background run; a pending/in_progress run without one for 15 min is auto-failed by the next create. */
+            heartbeat_at?: number;
+            tasks_total: number;
+            /** Tasks inferred during this run (not previously placed). */
+            tasks_inferred: number;
+            /** Detections kept (single facings). */
+            kept_count: number;
+            /** Detections merged into objects. */
+            merged_count: number;
+            /** Detections that could not be placed. */
+            ignored_count: number;
+            /** Detections dropped by the physical-size gate. */
+            size_rejected_count: number;
+            /** Same-frame quality-gate drops. */
+            dropped_count: number;
+            /** Resulting objects (kept + merged). */
+            objects_count: number;
+            objects?: AnalysisObject[];
+            concluded_labels?: ConcludedLabel[];
+            ignored?: IgnoredDetection[];
+            /** Per-detection fusion audit trail (one entry per analyzed annotation). */
+            detections?: DetectionLedgerEntry[];
+            funnel?: AnalysisFunnel;
+            frame_sources?: FrameSource[];
+            stage_fingerprints?: StageFingerprints;
+            /** Present unless `config.shelf_analysis: false` or nothing was placed (null after a compose recompute that produced nothing). */
+            shelf_composition?: ShelfComposition | null;
+            scene?: AnalysisScene;
+            _errors?: any[];
+            /** Who triggered the run (server-stamped). */
+            creator?: AdminOrRep;
+            editor?: AdminOrRep;
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "session" | "model_version" | "objects.label_id" | "objects.winning_image_media" | "concluded_labels.label_id";
+        interface AnalysisObjectWithPopulatedKeys extends Omit<AnalysisObject, "label_id" | "winning_image_media"> {
+            label_id?: StringId | AiObjectDetectionLabel.Data;
+            winning_image_media?: StringId | MediaStorage.MediaStorageSchema;
+        }
+        interface ConcludedLabelWithPopulatedKeys extends Omit<ConcludedLabel, "label_id"> {
+            label_id?: StringId | AiObjectDetectionLabel.Data;
+        }
+        /** Every population key is applied IN PLACE (the referenced field is replaced by the populated document). */
+        interface DataWithPopulatedKeys extends Omit<Data, "session" | "model_version" | "objects" | "concluded_labels"> {
+            session: StringId | AiObjectDetectionSession.Data;
+            model_version?: StringId | AiObjectDetectionModelVersion.Data;
+            objects?: AnalysisObjectWithPopulatedKeys[];
+            concluded_labels?: ConcludedLabelWithPopulatedKeys[];
+        }
+        /** `create` is the analysis TRIGGER (async) — or, with `recompute: "compose"`, a synchronous compose-only recompute of an existing analysis. */
+        interface CreateBody {
+            /** The session to analyze. Required unless `recompute` is set. */
+            session?: StringId;
+            /** Model version used to infer not-yet-placed tasks; tasks inferred by a different version are re-inferred. */
+            model_version?: StringId;
+            /** Optional object-detection model _id override (resolves `current_model_version` when `model_version` is absent). */
+            model?: StringId;
+            /** Detector for tasks inferred during this run (default `auto`). */
+            engine?: "auto" | "trained" | "zero_shot";
+            /** Zero-shot VLM override, e.g. `qwen/qwen3-vl-8b-instruct`. */
+            zero_shot_model?: string;
+            /** Detector confidence override. */
+            conf?: number;
+            /** Detector NMS IoU override (0..1). */
+            iou?: number;
+            /** Class-agnostic NMS override. */
+            agnostic_nms?: boolean;
+            config?: SceneMathConfig;
+            /** Re-infer EVERY task even if it already has an auto group for this version (stale-provenance escape hatch). */
+            force_reinference?: boolean;
+            /** Parallel inference calls (1..10, default 4); wins over `config.inference_concurrency`. */
+            inference_concurrency?: number;
+            /** `compose` re-runs ONLY the shelf composition of `analysis` with the `shelf_*` keys of `config`, synchronously and in place. */
+            recompute?: "compose";
+            /** The existing analysis _id to recompute (required with `recompute`). */
+            analysis?: StringId;
+            company_namespace?: string[];
+        }
+        /** PUT applies the body as an update; `editor` is server-stamped. Set `disabled: true` to soft-delete. */
+        type UpdateBody = Partial<Omit<Data, "_id" | "createdAt" | "updatedAt" | "company_namespace" | "creator" | "editor">>;
+        /** Filter keys honoured by `find` and by the bulk `patch`. */
+        type FilterParams = {
+            _id?: StringId | StringId[];
+            session?: StringId | StringId[];
+            model_version?: StringId | StringId[];
+            status?: AnalysisStatus | AnalysisStatus[];
+            "creator._id"?: StringId | StringId[];
+            from_updatedAt?: number;
+            to_updatedAt?: number;
+            from_createdAt?: number;
+            to_createdAt?: number;
+            /** Regex on `name` — analyses carry no `name`, so this matches nothing; listed only because the shared query helper honours it. */
+            search?: string;
+            /** Include disabled (soft-deleted) analyses. */
+            disabled?: boolean;
+        };
+        interface WriteQuery {
+            key: string;
+            command: "set" | "addToSet" | "pull";
+            value: any;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & FilterParams & {
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                populatedKeys?: PopulatedKeys[];
+            }
+            type Result = DataWithPopulatedKeys;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** Normal path: the `pending` document plus `message` (work continues in the background — poll until `status` flips). Compose recompute: the updated analysis document (no `message`). */
+            type Result = Data & {
+                message?: string;
+            };
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        /** Bulk update: `writeQuery[]` is applied to every analysis matching the query filters. */
+        namespace Patch {
+            type Params = FilterParams;
+            type Body = {
+                writeQuery: WriteQuery[];
+            };
+            type Result = {
+                nFound: number;
+                nModified: number;
+            };
+        }
+        namespace Remove {
+            type ID = StringId;
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionSessionElection {
+        type SessionVerdict = AiObjectDetectionSession.SessionVerdict;
+        /** A source frame excluded from the election because it violated the namespace detection-settings ERROR tier. */
+        type ElectionExcluded = AiObjectDetectionSession.ElectionExcluded;
+        /** The NEW session materialized by an election. It is a regular `ai-object-detection-session` document (same collection) whose election fields are always set. */
+        interface Data extends AiObjectDetectionSession.Data {
+            /** The source session's `session_id` suffixed `-E<n>` (n = 1 + prior elections of that source). */
+            session_id: string;
+            /** Provenance — the source session `_id`. */
+            source_session: StringId;
+            /** Average frame quality over ALL frames of the source session, 0..1 (rounded to 3 decimals). */
+            session_score: number;
+            /** `rejected` when any rejection reason fired, else banded from `session_score`. */
+            session_verdict: SessionVerdict;
+            /** `coverage_below_target`, `jump_detected`, `too_many_elected`. */
+            rejection_reasons: string[];
+            /** Error-tier frames dropped from the clone (they stay on the source session). */
+            election_excluded: ElectionExcluded[];
+        }
+        interface CreateBody {
+            /** Source `ai-object-detection-session` _id the frames belong to. */
+            session: StringId;
+            /** Task `_id`s (frames of the source session) elected in the playground — 1..500, all must belong to `session`. */
+            task_ids: StringId[];
+            /** Optional playground formula parameters, stored for provenance only (not persisted on the session model). */
+            config_snapshot?: {
+                [key: string]: number | boolean;
+            };
+            company_namespace?: string[];
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** The newly created session document (`toObject()` of the insert). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionSessionInsight {
+        /** Vocabulary kinds a question target / rollup row can refer to. */
+        type TargetKind = "label" | "label_group" | "brand" | "category" | "subcategory" | "product";
+        type QuestionType = "share_of_shelf" | "blocking" | "adjacency";
+        /** Rollup keys of `share_of_shelf` / `blocking`: `by_label` is always present; the others only when the scene's labels link to entities of that kind. */
+        type RollupKey = "by_label" | "by_label_group" | "by_brand" | "by_category" | "by_subcategory" | "by_product";
+        /** All optional on input; invalid values fall back to the defaults (values are clamped). */
+        interface InsightConfig {
+            /** Echoed for contract compatibility (default 0.06) — shelf levels now come from the analysis's stored composition. */
+            min_shelf_gap_m: number;
+            /** Echoed for contract compatibility (default 0.35). */
+            shelf_gap_height_factor: number;
+            /** Fallback facing width (m) when a facing has no measured size (default 0.08). */
+            default_facing_width_m: number;
+            /** Vertical block merge — required axis overlap (m) between adjacent-shelf runs (default 0.03)… */
+            block_min_overlap_m: number;
+            /** …or this fraction of the narrower run's width, whichever is smaller (default 0.5). */
+            block_overlap_frac: number;
+        }
+        interface InsightQuestion {
+            type: QuestionType;
+            /** Resolved by `id` first, then exact name, then substring, then fuzzy tokens. */
+            target: {
+                kind?: TargetKind;
+                id?: StringId;
+                name?: string;
+            };
+        }
+        interface LabelFacings {
+            label_id: StringId;
+            label_name?: string;
+            facings: number;
+        }
+        interface ShareRow {
+            key: string;
+            kind: TargetKind;
+            name: string;
+            facings: number;
+            linear_cm: number;
+            area_cm2: number;
+            /** 0..1 of all detected facings. */
+            facing_share: number;
+            /** 0..1 of the total linear cm. */
+            linear_share: number;
+            /** 0..1 of the total measured area. */
+            area_share: number;
+            shelves: {
+                shelf_index: number;
+                facings: number;
+                linear_cm: number;
+                linear_share_of_shelf: number;
+            }[];
+            labels: LabelFacings[];
+        }
+        interface BlockRun {
+            shelf_index: number;
+            /** Left edge along the shelf axis û (m). */
+            t0: number;
+            t1: number;
+            facings: number;
+            facing_ids: StringId[];
+        }
+        interface Blocking {
+            present: boolean;
+            facings: number;
+            labels_present: LabelFacings[];
+            blocks_count: number;
+            /** True when every facing of the group sits in ONE contiguous block. */
+            is_single_block: boolean;
+            largest_block_facings: number;
+            /** 0..1. */
+            largest_block_share: number;
+            blocks: {
+                shelves: number[];
+                facings: number;
+                runs: BlockRun[];
+            }[];
+            /** Foreign labels breaking the block, ranked by interrupting facings. */
+            interrupters: LabelFacings[];
+            shelves_spanned: number[];
+        }
+        /** A `blocking` rollup row (`Blocking` + identity + narrative). */
+        interface BlockingRow extends Blocking {
+            key: string;
+            name: string;
+            narrative: string;
+        }
+        interface InsightShelf {
+            /** 0 = bottom shelf. */
+            index: number;
+            /** Board level (m, AR world frame). */
+            y_base_m: number;
+            facings: number;
+            linear_cm: number;
+            span_cm: number;
+            /** linear_cm / span_cm — how much of the used span is product (0..1). */
+            utilization: number;
+        }
+        interface PlanogramFacing {
+            id: StringId;
+            label_id: StringId;
+            label_name?: string;
+            /** 1-based position left→right on the shelf. */
+            position: number;
+            /** Re-based to the shelf's left-most facing (cm). */
+            from_cm: number;
+            to_cm: number;
+            w_cm: number;
+            h_cm?: number;
+            confidence?: number;
+        }
+        interface PlanogramShelf {
+            shelf_index: number;
+            facings: PlanogramFacing[];
+        }
+        interface AdjacencyRow {
+            label_id: StringId;
+            label_name?: string;
+            neighbors: {
+                label_id: StringId;
+                label_name?: string;
+                count: number;
+            }[];
+        }
+        interface AnswerTarget {
+            kind: TargetKind;
+            name: string;
+            label_ids: StringId[];
+        }
+        /** One answer per question, in order. Unresolved answers carry `reason` (+ `suggestions`). */
+        interface Answer {
+            question: string | InsightQuestion;
+            type?: QuestionType;
+            resolved: boolean;
+            reason?: string;
+            suggestions?: string[];
+            target?: AnswerTarget;
+            /** `ShareRow` for share_of_shelf, `Blocking` for blocking, `{ neighbors }` or `{ present: false }` for adjacency. */
+            result?: ShareRow | Blocking | {
+                neighbors: {
+                    label_id: StringId;
+                    label_name?: string;
+                    count: number;
+                }[];
+            } | {
+                present: false;
+            };
+            narrative?: string;
+        }
+        /** The insight payload — computed on read, never persisted. */
+        interface Data {
+            session: StringId;
+            /** The analysis the numbers were derived from (latest successful one unless an explicit `analysis` was given). */
+            analysis: StringId;
+            model_version?: StringId;
+            /** Epoch ms of the analysis run's completion. */
+            analysis_finished_at?: number;
+            /** Epoch ms — always freshly computed. */
+            computed_at: number;
+            config_used: InsightConfig;
+            scene: {
+                facings_placed: number;
+                /** Analysis objects not counted as facings (back rows / unshelved). */
+                objects_skipped: number;
+                shelf_count: number;
+                /** Unit shelf-axis direction û in the horizontal plane. */
+                axis: {
+                    dir_x: number;
+                    dir_z: number;
+                };
+            };
+            totals: {
+                facings: number;
+                linear_cm: number;
+                area_cm2: number;
+            };
+            shelves: InsightShelf[];
+            share_of_shelf: Partial<Record<RollupKey, ShareRow[]>>;
+            blocking: Partial<Record<RollupKey, BlockingRow[]>>;
+            /** Only with `include_objects`. */
+            objects?: PlanogramShelf[];
+            /** Only with `include_adjacency`. */
+            adjacency?: AdjacencyRow[];
+            /** Only on `create` (POST) when `questions` were sent. */
+            answers?: Answer[];
+        }
+        /** POST body — compute the insight and answer up to 20 questions. One of `session` / `analysis` is required. */
+        interface CreateBody {
+            /** Session _id — reads its LATEST successful analysis. */
+            session?: StringId;
+            /** Explicit analysis _id (must have `status: success`). */
+            analysis?: StringId;
+            /** Free-text strings and/or structured questions, answered in order (max 20). */
+            questions?: (string | InsightQuestion)[];
+            config?: Partial<InsightConfig>;
+            include_objects?: boolean;
+            include_adjacency?: boolean;
+        }
+        namespace Find {
+            /** One of `session` / `analysis` is required. */
+            type Params = {
+                /** Session _id — reads its LATEST successful analysis. */
+                session?: StringId;
+                /** Explicit analysis _id (must have `status: success`). */
+                analysis?: StringId;
+                /** Add the planogram-style facing dump per shelf. */
+                include_objects?: boolean;
+                /** Add label-level neighbour counts. */
+                include_adjacency?: boolean;
+            };
+            /** A single computed payload — NOT paginated. */
+            type Result = Data;
+        }
+        namespace Get {
+            /** The path id is read as a SESSION id (deep link). */
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** The insight payload plus `answers[]` when questions were sent. */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionMetric {
+        /** Engine registry key — selects the `args` schema, the output family and the evaluator. */
+        type MetricType = "adjacent_block" | "facings_count" | "on_shelf_availability" | "share_of_shelf";
+        /** Output family: fixes what a result's `answer` means and where its 0..1 `score` comes from. */
+        type MetricOutputFamily = "compatibility" | "numerical" | "share_of_shelf";
+        /** width_cm = linear share (occupied shelf length), area_cm2 = front-face areas, facings = unit count. */
+        type ShareOfShelfMeasure = "width_cm" | "area_cm2" | "facings";
+        /** Args for `type: "adjacent_block"` (compatibility family) — "these labels must stand together". */
+        interface AdjacentBlockArgs {
+            /** Label ids that form the block (≥ 1). */
+            labels: StringId[];
+            /** Minimum member facing count (inclusive, ≥ 0). */
+            from: number;
+            /** Maximum member facing count (inclusive, ≥ from). */
+            to: number;
+            /** Judge only the shopper-visible front row. Default true. */
+            front_row_only?: boolean;
+        }
+        /** Args for `type: "facings_count"` (numerical family) — how many facings of the labels does the shopper see. */
+        interface FacingsCountArgs {
+            /** Label ids to count (≥ 1). */
+            labels: StringId[];
+            /** Optional demanded count (integer ≥ 1) — score = answer ÷ target_answer (clamped to 1). Absent: non-zero answer scores 1, zero scores 0. */
+            target_answer?: number;
+            /** Count only the shopper-visible front row. Default true. */
+            front_row_only?: boolean;
+        }
+        /** Args for `type: "on_shelf_availability"` (numerical family) — how much of what SHOULD be on the shelf is. */
+        interface OnShelfAvailabilityArgs {
+            /** The label ids that SHOULD be on the shelf (≥ 1). */
+            labels: StringId[];
+            /** Optional demanded count of AVAILABLE labels (integer ≥ 1, never above labels.length) — score = answer ÷ target_answer. Absent: score = availability ratio. */
+            target_answer?: number;
+            /** Default FALSE — a product in a back row is still available. */
+            front_row_only?: boolean;
+        }
+        /** One segment row of a share-of-shelf metric. */
+        interface ShareOfShelfSegmentArg {
+            /** Segment id (`/ai-object-detection-segment`) — must exist, not be deleted, and appear in only one row. */
+            segment: StringId;
+            /** Optional per-metric label override; empty/absent ⇒ the segment's own labels. */
+            labels?: StringId[];
+            /** The MAIN row the target_ratio is defined for — exactly one per metric (server flags the first row when none is set). */
+            main?: boolean;
+        }
+        /** Args for `type: "share_of_shelf"` (share_of_shelf family). */
+        interface ShareOfShelfArgs {
+            /** Segment rows (≥ 1); exactly one is `main`. */
+            segments: ShareOfShelfSegmentArg[];
+            /** The share the MAIN segment must reach for full score (0.001..1). */
+            target_ratio: number;
+            /** Default "width_cm". */
+            measure?: ShareOfShelfMeasure;
+            /** Measure only the shopper-visible front row. Default true. */
+            front_row_only?: boolean;
+            /** width_cm only (default true): count each vertical pile ONCE (the bottom object books the shelf distance). false = legacy per-unit width sum. */
+            first_in_stack?: boolean;
+        }
+        /** Client-sent args — must match the metric's `type`. Unknown keys are dropped and defaults applied server-side. */
+        type MetricArgs = AdjacentBlockArgs | FacingsCountArgs | OnShelfAvailabilityArgs | ShareOfShelfArgs;
+        /** Stored args: the client shape plus the server-stamped discriminator mirror `type` (clients never send it). */
+        type StoredMetricArgs = MetricArgs & {
+            type?: MetricType;
+        };
+        /** One argument declaration from the type registry (`find({ registry: true })`). */
+        interface MetricArgField {
+            key: string;
+            type: "labels" | "number" | "integer" | "boolean" | "enum" | "segments";
+            required: boolean;
+            /** Numeric bounds (number/integer). */
+            min?: number;
+            max?: number;
+            /** Default applied when an optional arg is absent. */
+            default?: unknown;
+            /** labels / segments: minimum item count. */
+            min_items?: number;
+            /** enum: the allowed values. */
+            options?: string[];
+        }
+        /** One metric TYPE declaration from the registry — lets generic clients render forms without hardcoding. */
+        interface MetricTypeDeclaration {
+            type: MetricType;
+            output: MetricOutputFamily;
+            args: MetricArgField[];
+            /** Result output keys a human may override (`score`/`ratio` are always derived). */
+            overwritable: string[];
+        }
+        interface Data {
+            _id: StringId;
+            name: string;
+            description?: string;
+            type: MetricType;
+            args: StoredMetricArgs;
+            /** false pauses evaluation without losing the definition. Default true. */
+            enabled: boolean;
+            /** Soft-delete flag. */
+            disabled: boolean;
+            /** Server-stamped from the creating token. */
+            creator?: AdminOrRepOrTenantOrClient;
+            /** Server-stamped on update / remove. */
+            editor?: AdminOrRepOrTenantOrClient;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface CreateBody {
+            name: string;
+            description?: string;
+            type: MetricType;
+            /** Validated against `type`'s schema; EVERY violation is reported in one 400. share_of_shelf rows must reference live segments. */
+            args: MetricArgs;
+            enabled?: boolean;
+            company_namespace?: string[];
+        }
+        /** PUT re-validates `type` + `args` (both required — the update is a full re-definition); `_id`, `company_namespace` and `creator` are stripped server-side. */
+        interface UpdateBody {
+            type: MetricType;
+            args: MetricArgs;
+            name?: string;
+            description?: string;
+            enabled?: boolean;
+            /** Set true to soft-delete via update. */
+            disabled?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                /** Exact name match. */
+                name?: string | string[];
+                type?: MetricType | MetricType[];
+                enabled?: boolean;
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                /** true ⇒ the response is a `RegistryResult` (type declarations) instead of a paginated list. */
+                registry?: boolean;
+            };
+            interface PaginatedResult extends DefaultPaginationResult {
+                data: Data[];
+            }
+            /** Returned when `registry: true` is passed. */
+            interface RegistryResult {
+                /** Bumped whenever a type's semantics change; results carry the version they were computed with. */
+                engine_version: number;
+                types: MetricTypeDeclaration[];
+            }
+            type Result = PaginatedResult | RegistryResult;
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The soft-deleted document (`disabled: true`). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionMetricResult {
+        /** Evaluation outcome of one result row. */
+        type Status = "ok" | "error";
+        /** Computed layer for `type: "adjacent_block"` (compatibility family). */
+        interface AdjacentBlockComputed {
+            /** Internal discriminator mirror of the result's `type`. */
+            type?: "adjacent_block";
+            output: "compatibility";
+            /** The verdict — contiguous AND count within [from, to]. */
+            answer: boolean;
+            score: number;
+            member_count: number;
+            cut_count: number;
+            in_range: boolean;
+            /** Contiguous member runs (1-based shelf / stack indices). */
+            blocks: {
+                shelf: number;
+                from_stack: number;
+                to_stack: number;
+                count: number;
+            }[];
+        }
+        /** Computed layer for `type: "facings_count"` (numerical family). */
+        interface FacingsCountComputed {
+            type?: "facings_count";
+            output: "numerical";
+            /** The collected facings count. */
+            answer: number;
+            /** Echo of the metric's optional target — present only when set; score then = answer ÷ target_answer (clamped). */
+            target_answer?: number;
+            score: number;
+            shelves: {
+                shelf: number;
+                count: number;
+            }[];
+        }
+        /** Computed layer for `type: "on_shelf_availability"` (numerical family). */
+        interface OnShelfAvailabilityComputed {
+            type?: "on_shelf_availability";
+            output: "numerical";
+            /** How many of the selected labels are AVAILABLE (≥ 1 facing). */
+            answer: number;
+            /** answer ÷ target_answer when a target is set, else `ratio`. */
+            score: number;
+            /** How many labels were selected (the denominator). */
+            total: number;
+            /** answer / total — availability. */
+            ratio: number;
+            target_answer?: number;
+            /** The out-of-stock labels (names resolved at evaluation time). */
+            missing: {
+                label: StringId;
+                name?: string;
+            }[];
+            /** The available labels with their facing counts. */
+            present: {
+                label: StringId;
+                name?: string;
+                facings: number;
+            }[];
+        }
+        /** One segment row's outcome inside a share-of-shelf evaluation; only the MAIN row carries target/score. */
+        interface SegmentOutput {
+            segment: StringId;
+            name: string;
+            /** false = the segment was deleted after the metric referenced it. */
+            resolved: boolean;
+            /** The row the metric's target is defined for — exactly one per metric. */
+            main: boolean;
+            /** Effective labels used (override or the segment's own). */
+            labels: StringId[];
+            /** Measured quantity in the metric's measure unit. */
+            answer: number;
+            /** CONFIRMED human answer override colocated in the row (effective = overwrite_answer ?? answer); present only while `confirmed_edit`. */
+            overwrite_answer?: number;
+            overwrite_ratio?: number;
+            overwrite_score?: number;
+            /** answer / category total. */
+            ratio: number;
+            /** Main row only. */
+            target_ratio?: number;
+            /** Main row only — target_ratio × total. */
+            target_answer?: number;
+            /** Main row only — min(1, ratio / target_ratio). */
+            score?: number;
+        }
+        /** Computed layer for `type: "share_of_shelf"` — the MAIN segment's numbers at the top level, every row in `segments[]`. */
+        interface ShareOfShelfComputed {
+            type?: "share_of_shelf";
+            output: "share_of_shelf";
+            /** The MAIN segment's measured quantity; null when nothing was measurable. */
+            answer: number | null;
+            /** = the main segment's score. */
+            score: number;
+            /** The considered category: the same measure over facings of ANY of the metric's segments. */
+            total: number;
+            /** answer / total. */
+            ratio: number;
+            target_ratio: number;
+            /** target_ratio × total. */
+            target_answer: number;
+            measure: AiObjectDetectionMetric.ShareOfShelfMeasure;
+            /** Considered facings without a physical size (excluded from both sides). */
+            unmeasured: number;
+            segments: SegmentOutput[];
+        }
+        /** Machine layer — strict per-type engine output. Never editable through the API. */
+        type Computed = AdjacentBlockComputed | FacingsCountComputed | OnShelfAvailabilityComputed | ShareOfShelfComputed;
+        /** Stored human layer for `adjacent_block` (entered values + server-derived `score`). */
+        interface AdjacentBlockOverwrite {
+            type?: "adjacent_block";
+            answer?: boolean;
+            score?: number;
+            member_count?: number;
+            cut_count?: number;
+        }
+        interface FacingsCountOverwrite {
+            type?: "facings_count";
+            answer?: number;
+            score?: number;
+        }
+        interface OnShelfAvailabilityOverwrite {
+            type?: "on_shelf_availability";
+            answer?: number;
+            ratio?: number;
+            score?: number;
+        }
+        interface ShareOfShelfOverwrite {
+            type?: "share_of_shelf";
+            answer?: number;
+            total?: number;
+            ratio?: number;
+            score?: number;
+        }
+        /** Stored human layer — sparse VALUE overrides plus the server-DERIVED `ratio`/`score`. Survives recalculation. */
+        type Overwrite = AdjacentBlockOverwrite | FacingsCountOverwrite | OnShelfAvailabilityOverwrite | ShareOfShelfOverwrite;
+        /** What a client may ENTER as an override: only the type's overwritable VALUE keys. `ratio`/`score` are rejected (derived server-side). Send `{}` to clear. */
+        interface OverwriteInput {
+            /** adjacent_block: boolean verdict; numerical / share_of_shelf types: number. */
+            answer?: boolean | number;
+            /** adjacent_block only. */
+            member_count?: number;
+            /** adjacent_block only. */
+            cut_count?: number;
+            /** share_of_shelf only. */
+            total?: number;
+        }
+        interface Data {
+            _id: StringId;
+            /** The metric definition this result was computed from. */
+            metric: StringId;
+            /** The session analysis it was computed against. */
+            analysis: StringId;
+            session?: StringId;
+            /** Denormalized scan context (stamped by the evaluator): the SCANNING rep — unset for admin-scanned sessions. */
+            user?: StringId | null;
+            user_name?: string | null;
+            client?: StringId | null;
+            client_name?: string | null;
+            /** The scanning rep's team ids at evaluation time. */
+            teams?: StringId[];
+            /** Device visit id the scan happened in (copied from the session). */
+            visit_id?: string;
+            route?: StringId;
+            /** Business day of the scan, `YYYY-MM-DD`. */
+            business_day?: string;
+            /** Metric name snapshot at evaluation time. */
+            name?: string;
+            type: AiObjectDetectionMetric.MetricType;
+            /** The type's output family (denormalized for rendering). */
+            output?: AiObjectDetectionMetric.MetricOutputFamily;
+            /** Metric args snapshot at evaluation time. */
+            args?: AiObjectDetectionMetric.StoredMetricArgs;
+            /** Machine layer; absent when the evaluation errored. */
+            computed?: Computed;
+            /** Human layer (default `{ type }`). */
+            overwrite?: Overwrite;
+            /** Human attention marker. Default false. */
+            flag: boolean;
+            /** Admin review gate — the overwrite only drives the effective values while true. Default false. */
+            confirmed_edit: boolean;
+            /** EFFECTIVE score 0..1 (confirmed `overwrite.score`, else `computed.score`). */
+            score?: number;
+            /** EFFECTIVE answer (boolean verdict or number per family). */
+            answer?: boolean | number | null;
+            /** EFFECTIVE ratio (OSA availability / SOS share); null for types without one. */
+            ratio?: number | null;
+            status: Status;
+            error?: string | null;
+            /** Unix ms of the evaluation. */
+            evaluated_at?: number;
+            engine_version?: number;
+            /** The analysis's stage fingerprints at evaluation time — mismatch vs the analysis's current ones = stale. */
+            source_fingerprints?: {
+                [key: string]: any;
+            };
+            creator?: AdminOrRepOrTenantOrClient;
+            editor?: AdminOrRepOrTenantOrClient;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        type PopulatedKeys = "metric" | "analysis" | "session";
+        /** Populated refs replace the id IN PLACE (the backend's population map has no `new_key`). */
+        type DataWithPopulatedKeys = Omit<Data, "metric" | "analysis" | "session"> & {
+            metric: StringId | AiObjectDetectionMetric.Data;
+            analysis: StringId | AiObjectDetectionSessionAnalysis.Data;
+            session?: StringId | AiObjectDetectionSession.Data;
+        };
+        /** POST = CALCULATE: evaluates the mission-assigned metrics of `analysis` (admin only). */
+        interface CreateBody {
+            /** The SUCCESSFUL analysis to evaluate. */
+            analysis: StringId;
+            /** Optional metric-id subset — can only NARROW the mission-assigned set, never widen it. */
+            metrics?: StringId[];
+        }
+        /** PUT = HUMAN OVERRIDE. Only these keys are writable; `computed` is immutable. */
+        interface UpdateBody {
+            /** Reps may only RAISE it (clearing is an admin review action). */
+            flag?: boolean;
+            /** Sparse value overrides; a rep's override auto-raises `flag`. Any fresh overwrite resets `confirmed_edit` to false unless the same admin request confirms it. */
+            overwrite?: OverwriteInput;
+            /** ADMIN-ONLY review verdict — true makes the standing overwrite effective. */
+            confirmed_edit?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                metric?: StringId | StringId[];
+                analysis?: StringId | StringId[];
+                session?: StringId | StringId[];
+                /** The scanning rep's id. */
+                user?: StringId | StringId[];
+                client?: StringId | StringId[];
+                teams?: StringId | StringId[];
+                type?: AiObjectDetectionMetric.MetricType | AiObjectDetectionMetric.MetricType[];
+                flag?: boolean;
+                status?: Status | Status[];
+                /** Regex on the metric-name snapshot. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                populatedKeys?: PopulatedKeys[];
+            };
+            interface Result extends DefaultPaginationResult {
+                data: DataWithPopulatedKeys[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            /** Evaluation summary + the fresh result documents of the analysis. */
+            interface Result {
+                analysis: string;
+                /** Number of metrics evaluated. */
+                evaluated: number;
+                /** Number of metrics whose evaluation or persistence failed. */
+                errors: number;
+                results: Data[];
+            }
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The soft-deleted document (admin only). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionMission {
+        /** What an assignment rule DEMANDS of a mission at a client (rolled up to the strictest on read). */
+        type RequirementMode = "not_required" | "submission_required" | "completion_required";
+        /** One weighted metric row — the mission's composition. */
+        interface MetricRowInput {
+            metric: StringId;
+            /** Finite number ≥ 0; the mission score is the weighted mean of the metrics' effective result scores. */
+            weight: number;
+        }
+        /** Stored row (Mongoose adds a sub-document `_id`). */
+        interface MetricRow extends MetricRowInput {
+            _id?: StringId;
+        }
+        interface Data {
+            _id: StringId;
+            name: string;
+            description?: string;
+            metrics: MetricRow[];
+            /** Completion threshold 0..1 (default 0 = any NON-ZERO score completes; a zero score never does). */
+            min_score: number;
+            /** Optional detection category a session started FROM this mission carries; null = none. */
+            category?: StringId | null;
+            /** Disabled missions are skipped by evaluation and `scores_for`. Default true. */
+            enabled: boolean;
+            disabled: boolean;
+            creator?: AdminOrRepOrTenantOrClient;
+            editor?: AdminOrRepOrTenantOrClient;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface CreateBody {
+            name: string;
+            description?: string;
+            /** REQUIRED, ≥ 1 row; every violation is listed in one 400. */
+            metrics: MetricRowInput[];
+            /** 0..1; absent/null/"" = default 0. */
+            min_score?: number | null;
+            /** Valid category id, or null/"" to leave unset. */
+            category?: StringId | null;
+            enabled?: boolean;
+            company_namespace?: string[];
+        }
+        /** PUT re-runs the same validation as create — `metrics` (≥ 1 row) is required again. `category: null` explicitly CLEARS it; omitting it leaves the stored value. */
+        interface UpdateBody {
+            metrics: MetricRowInput[];
+            name?: string;
+            description?: string;
+            min_score?: number | null;
+            category?: StringId | null;
+            enabled?: boolean;
+            /** Set true to soft-delete via update. */
+            disabled?: boolean;
+        }
+        /** One metric's contribution inside a `scores_for` row. */
+        interface ScoreMetricRow {
+            metric: string;
+            /** Name snapshot from the metric result (absent when missing). */
+            name?: string;
+            weight: number;
+            /** Effective 0..1 score of the metric's result; absent when `missing`. */
+            score?: number;
+            /** true = the metric has no result on this analysis (counts as 0 in the weighted mean). */
+            missing: boolean;
+        }
+        /** One enabled mission scored against an analysis (`find({ scores_for })`). */
+        interface MissionScoreRow {
+            _id: string;
+            name: string;
+            /** An enabled assignment rule attaches a set containing this mission to the session's client. */
+            assigned: boolean;
+            /** Names of the assigned sets this mission arrived through. */
+            via_sets: string[];
+            /** Strictest demand the matched rules place on it; absent when unassigned. */
+            requirement_mode?: RequirementMode;
+            /** Weighted mean 0..1 of the metrics' effective scores. */
+            score: number;
+            min_score: number;
+            /** NON-ZERO score ≥ min_score — computed at read, never stamped. */
+            completed: boolean;
+            metrics: ScoreMetricRow[];
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                name?: string | string[];
+                enabled?: boolean;
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                /** An analysis `_id` — the response becomes `ScoresResult` (resolved mission scores for that analysis) instead of a paginated list. */
+                scores_for?: StringId;
+            };
+            interface PaginatedResult extends DefaultPaginationResult {
+                data: Data[];
+            }
+            /** Returned when `scores_for` is passed; assigned missions first, then by name. */
+            interface ScoresResult {
+                analysis: string;
+                /** The analysis's session client; null when the session has none. */
+                client: string | null;
+                missions: MissionScoreRow[];
+            }
+            type Result = PaginatedResult | ScoresResult;
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The soft-deleted document (`disabled: true`). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionMissionSet {
+        interface Data {
+            _id: StringId;
+            name: string;
+            description?: string;
+            /** Mission ids in this set — the unit assignment rules target. */
+            missions: StringId[];
+            /** Disabled sets are ignored by assignment resolution. Default true. */
+            enabled: boolean;
+            disabled: boolean;
+            creator?: AdminOrRepOrTenantOrClient;
+            editor?: AdminOrRepOrTenantOrClient;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface CreateBody {
+            name: string;
+            description?: string;
+            /** REQUIRED, ≥ 1 valid mission id; every violation is listed in one 400. */
+            missions: StringId[];
+            enabled?: boolean;
+            company_namespace?: string[];
+        }
+        /** PUT re-runs the same validation as create — `missions` (≥ 1 id) is required again. */
+        interface UpdateBody {
+            missions: StringId[];
+            name?: string;
+            description?: string;
+            enabled?: boolean;
+            /** Set true to soft-delete via update. */
+            disabled?: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                name?: string | string[];
+                enabled?: boolean;
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                disabled?: boolean;
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+            };
+            interface Result extends DefaultPaginationResult {
+                data: Data[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The soft-deleted document (`disabled: true`). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionMissionResults {
+        /** The STORED outcome of one mission execution — exactly one document per (session, mission), written by the metric evaluator. */
+        interface Data {
+            _id: StringId;
+            /** The identity unit: one scan = one execution. */
+            session: StringId;
+            mission: StringId;
+            /** The analysis this result CURRENTLY reflects — re-analysis re-points it (no duplicate rows). */
+            analysis: StringId;
+            /** Denormalized scan context: the SCANNING rep (unset for admin-scanned sessions). */
+            user?: StringId | null;
+            user_name?: string | null;
+            client?: StringId | null;
+            client_name?: string | null;
+            teams?: StringId[];
+            /** Device visit id the scan happened in (copied from the session; absent without a visit). */
+            visit_id?: string;
+            route?: StringId;
+            /** Business day of the scan, `YYYY-MM-DD`. */
+            business_day?: string;
+            /** Analysis time (Unix ms) ≈ the visit. */
+            time?: number;
+            /** The session was STARTED FROM this mission ("SCAN THIS MISSION"). Default false. */
+            scanned: boolean;
+            mission_name?: string;
+            /** Weighted EFFECTIVE metric scores 0..1 (confirmed human overrides folded in; a demanded metric without a result counts 0). */
+            score?: number;
+            /** Mission threshold snapshot (default 0). */
+            min_score: number;
+            /** score reached min_score — a ZERO score never completes. */
+            completed: boolean;
+            /** Mission-set names that assigned it (snapshot at evaluation time; [] when unresolved). */
+            via_sets: string[];
+            /** DERIVED — any of the mission's metric results on `analysis` carries a flag. A fresh flag reopens `resolved`. */
+            flagged: boolean;
+            /** Admin review verdict — the only client-writable field. */
+            resolved: boolean;
+            /** Stamped when resolved; null when un-resolved. */
+            resolver?: AdminOrRepOrTenantOrClient | null;
+            /** Unix ms; null when un-resolved. */
+            resolved_at?: number | null;
+            creator?: AdminOrRepOrTenantOrClient;
+            editor?: AdminOrRepOrTenantOrClient;
+            disabled: boolean;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        /** PUT accepts ONLY the admin review verdict. */
+        interface UpdateBody {
+            /** true stamps `resolver` + `resolved_at`; false clears both. */
+            resolved: boolean;
+        }
+        namespace Find {
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                session?: StringId | StringId[];
+                mission?: StringId | StringId[];
+                analysis?: StringId | StringId[];
+                client?: StringId | StringId[];
+                /** The scanning rep's id (overridden by `rep`; a rep token is always forced to itself). */
+                user?: StringId | StringId[];
+                teams?: StringId | StringId[];
+                /** Device `visits.visit_id`. */
+                visit_id?: string | string[];
+                route?: StringId | StringId[];
+                scanned?: boolean;
+                completed?: boolean;
+                flagged?: boolean;
+                resolved?: boolean;
+                /** Window start on `time` (Unix ms). Default = 30 days before `to_time`. */
+                from_time?: number;
+                /** Window end on `time` (Unix ms). Default = now. */
+                to_time?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                /** Admin only: narrow to one rep (mapped to `user`); ignored unless a valid ObjectId. */
+                rep?: StringId;
+                /** Regex on `name` — this model has no `name`, so it matches nothing; listed only because the shared query layer accepts it. */
+                search?: string;
+                disabled?: boolean;
+            };
+            /** Sorted `time` desc, `_id` desc (the `sort` param is ignored). */
+            interface Result extends DefaultPaginationResult {
+                data: Data[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            interface Params {
+                /** Admin only: the document must belong to this rep (`user`). */
+                rep?: StringId;
+            }
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** The soft-deleted document (admin only). */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionAssignmentRule {
+        /** Client attribute a rule line is checked against. `client_tag` and `area_tag` both match the client's single `tags` array. */
+        type RuleConditionKey = "client" | "client_tag" | "client_channel" | "assigned_to" | "chain" | "area_tag" | "team";
+        /** `in` = any overlap with the client's value(s); `nin` = no overlap (a client missing the attribute passes `nin`, fails `in`). */
+        type RuleConditionOperator = "in" | "nin";
+        /** How often the rule DEMANDS its sets: due on every visit, or `times` completions per business day / week / month / quarter. */
+        type RuleFrequencyInterval = "every_visit" | "day" | "week" | "month" | "quarter";
+        /** What the rule demands of a set's missions at the client. Carried by the backend, enforced by the mobile app when the rep ends the visit. */
+        type RequirementMode = "not_required" | "submission_required" | "completion_required";
+        interface RuleCondition {
+            /** Mongoose subdocument id (server-generated on stored rows). */
+            _id?: StringId;
+            key: RuleConditionKey;
+            operator: RuleConditionOperator;
+            /** Ids matching the key: clients / client-type tags / channels / reps / chain clients (isChain) / area-type tags / teams. At least one. */
+            value: StringId[];
+        }
+        interface RuleFrequency {
+            interval: RuleFrequencyInterval;
+            /** Completions required per interval (integer >= 1). Pinned to 1 for `every_visit`. */
+            times: number;
+        }
+        /** One stored `mission_sets` line. */
+        interface RuleMissionSet {
+            mission_set: StringId;
+            requirement_mode: RequirementMode;
+        }
+        /** One `mission_sets` line as sent on write — `requirement_mode` defaults to `submission_required`. */
+        interface RuleMissionSetInput {
+            mission_set: StringId;
+            requirement_mode?: RequirementMode;
+        }
+        /** Frequency as sent on write — absent => `every_visit`; `times` absent => 1. */
+        interface RuleFrequencyInput {
+            interval?: RuleFrequencyInterval;
+            times?: number;
+        }
+        interface Data {
+            _id: StringId;
+            name: string;
+            /** The mission sets this rule assigns, one line per set (a set appears once). Never empty. */
+            mission_sets: RuleMissionSet[];
+            /** AND-ed lines; empty = applies to every client. */
+            conditions: RuleCondition[];
+            /** Always present on stored rows (normalized on write). */
+            frequency: RuleFrequency;
+            /** Default true. Disabled-but-enabled rules are still skipped by the assignment read. */
+            enabled: boolean;
+            disabled: boolean;
+            /** Server-stamped from the caller's token on create. */
+            creator?: AdminOrRepOrTenantOrClient;
+            /** Server-stamped from the caller's token on update / remove. */
+            editor?: AdminOrRepOrTenantOrClient;
+            company_namespace: string[];
+            createdAt: Date;
+            updatedAt: Date;
+        }
+        interface CreateBody {
+            name: string;
+            /** REQUIRED, at least one line; each set may be listed once. */
+            mission_sets: RuleMissionSetInput[];
+            /** Omit or send `[]` to apply the rule to every client. Every violation is reported in one 400. */
+            conditions?: RuleCondition[];
+            frequency?: RuleFrequencyInput;
+            /** Default true. */
+            enabled?: boolean;
+            company_namespace?: string[];
+        }
+        /** PUT re-runs the full create validation: `mission_sets` is REQUIRED again, an omitted `conditions` resets to `[]` (every client) and an omitted `frequency` resets to `every_visit`. */
+        interface UpdateBody {
+            name?: string;
+            mission_sets: RuleMissionSetInput[];
+            conditions?: RuleCondition[];
+            frequency?: RuleFrequencyInput;
+            enabled?: boolean;
+            disabled?: boolean;
+        }
+        namespace Find {
+            /** Results are always ordered `_id` desc — `sort` / `sortPageOrder` are accepted but not applied. */
+            type Params = DefaultPaginationQueryParams & {
+                _id?: StringId | StringId[];
+                name?: string | string[];
+                enabled?: boolean;
+                /** Rules whose `mission_sets` list this set id. */
+                "mission_sets.mission_set"?: StringId | StringId[];
+                /** Case-insensitive regex on `name`. */
+                search?: string;
+                /** Omit to get active AND soft-deleted rows; `false` = active only. */
+                disabled?: boolean;
+                /** ms epoch (or date string); snapped to the start of that day in the company time zone unless `exact_time`. */
+                from_updatedAt?: number;
+                to_updatedAt?: number;
+                from_createdAt?: number;
+                to_createdAt?: number;
+                /** Use the exact instants of the `from_*`/`to_*` bounds instead of whole days. */
+                exact_time?: boolean;
+            };
+            interface Result extends DefaultPaginationResult {
+                data: Data[];
+            }
+        }
+        namespace Get {
+            type ID = StringId;
+            /** The backend answers 400 (not 404) when the id does not exist. */
+            type Result = Data;
+        }
+        namespace Create {
+            type Body = CreateBody;
+            type Result = Data;
+        }
+        namespace Update {
+            type ID = StringId;
+            type Body = UpdateBody;
+            type Result = Data;
+        }
+        namespace Remove {
+            type ID = StringId;
+            /** Soft-delete: the row comes back with `disabled: true` and `editor` stamped. */
+            type Result = Data;
+        }
+    }
+    namespace AiObjectDetectionAssignedMissions {
+        /** What a rule demands of a set's missions: carried by the backend, enforced by the mobile app when the rep ends the visit. */
+        type RequirementMode = "not_required" | "submission_required" | "completion_required";
+        type RuleFrequencyInterval = "every_visit" | "day" | "week" | "month" | "quarter";
+        type RuleConditionKey = "client" | "client_tag" | "client_channel" | "assigned_to" | "chain" | "area_tag" | "team";
+        type RuleConditionOperator = "in" | "nin";
+        interface RuleFrequency {
+            interval: RuleFrequencyInterval;
+            /** Completions required per interval (1 for `every_visit`). */
+            times: number;
+        }
+        /** One rule line with its verdict against the client — the simulator renders exactly why a rule hit or missed. */
+        interface AssignedRuleCondition {
+            key: RuleConditionKey;
+            operator: RuleConditionOperator;
+            value: StringId[];
+            matched: boolean;
+        }
+        interface AssignedRuleMissionSet {
+            mission_set: StringId;
+            /** Absent when the set is disabled / deleted. */
+            set_name?: string;
+            requirement_mode: RequirementMode;
+        }
+        /** One enabled rule resolved against the client (matched or not). */
+        interface AssignedRule {
+            _id: StringId;
+            name: string;
+            /** The sets the rule assigns, each with its demand. */
+            mission_sets: AssignedRuleMissionSet[];
+            /** The STRICTEST mode across the rule's `mission_sets` lines. */
+            requirement_mode: RequirementMode;
+            /** Every condition line holds (AND). Zero lines => true. */
+            matched: boolean;
+            frequency: RuleFrequency;
+            conditions: AssignedRuleCondition[];
+        }
+        /** One demand a matched rule places on a mission through one of its sets. */
+        interface MissionRequirement {
+            rule: StringId;
+            rule_name: string;
+            set: StringId;
+            set_name?: string;
+            frequency: RuleFrequency;
+            requirement_mode: RequirementMode;
+            /** Start (ms) of the first BUSINESS day of the demand's current window; null for a visit-scoped `every_visit` demand (matched by visit id, not by time). */
+            window_start: number | null;
+            /** Completions whose business day falls inside the window (visit-scoped every_visit: those stamped with the visit id). */
+            completions: number;
+            /** completions >= frequency.times (visit-scoped every_visit: >= 1) — regardless of `requirement_mode`. */
+            satisfied: boolean;
+        }
+        interface AssignedMission {
+            _id: StringId;
+            name: string;
+            /** 0..1 — the weighted mission score a scan must reach to complete it. */
+            min_score: number;
+            /** Optional detection category id — the mobile stamps it on the session it starts FROM this mission so the pipeline auto-analyzes it. */
+            category?: StringId;
+            category_name?: string;
+            /** Names of the matched sets that carry this mission. */
+            via_sets: string[];
+            /** The STRICTEST demand across `requirements[]` — what the mobile enforces when the rep ends the visit. */
+            requirement_mode: RequirementMode;
+            /** One per matching rule x set line. */
+            requirements: MissionRequirement[];
+            /** Every requirement satisfied — mode-agnostic (the mobile combines it with `requirement_mode`). */
+            done: boolean;
+        }
+        /** The assignment read for ONE client — computed on every call from current rules / sets / stored mission results; nothing is stored. */
+        interface Data {
+            client: {
+                _id: StringId;
+                name: string;
+            };
+            /** The `rep` query param echoed back (null when not sent). */
+            rep: StringId | null;
+            /** The context rep's `rep_can_redo_object_detection_missions` permission (default false); always true when no rep is in context (admin simulator). */
+            rep_can_redo: boolean;
+            /** IANA time zone the business day was resolved in. */
+            timezone: string;
+            /** `YYYY-MM-DD` — the CURRENT business day the windows are anchored to (rep stamping context when a rep is in scope, else the company's). */
+            business_day: string;
+            /** The device visit id the read is scoped to — null when `visit` was not sent. */
+            visit_id: string | null;
+            /** Every enabled rule with per-condition verdicts (matched or not). */
+            rules: AssignedRule[];
+            /** The ASSIGNED missions only (via matched rules' sets), sorted by name. */
+            missions: AssignedMission[];
+        }
+        namespace Find {
+            /** Not paginated — `per_page` / `page` are ignored. */
+            interface Params {
+                /** REQUIRED — the client to resolve the rules against (400 when missing / invalid / not found). */
+                client: StringId;
+                /** Count only this rep's completions and use the rep's business-day context + redo permission. Defaults to the rep token's rep, else the company context. */
+                rep?: StringId;
+                /** DEVICE visit id (`visits.visit_id`) the rep is in — scopes `every_visit` demands to that visit. Not looked up (the visit may not have synced yet). */
+                visit?: string;
+            }
+            type Result = Data;
+        }
+        namespace Get {
+            /** The CLIENT id — `GET /:id` is the same read as `GET ?client=:id`. */
+            type ID = StringId;
+            interface Params {
+                rep?: StringId;
+                visit?: string;
+            }
+            type Result = Data;
+        }
+    }
+    namespace ObjectDetectionAnalyticsReport {
+        /** `metrics` = one row per metric result; `segments` = one row per unwound share-of-shelf SegmentOutput. */
+        type View = "metrics" | "segments";
+        type MetricType = "adjacent_block" | "facings_count" | "on_shelf_availability" | "share_of_shelf";
+        /** Output family of a metric type (denormalized on every result). */
+        type MetricOutput = "compatibility" | "numerical" | "share_of_shelf";
+        /** Unit share-of-shelf quantities are measured in. */
+        type Measure = "width_cm" | "area_cm2" | "facings";
+        /** Filter keys — the same names grouped rows emit in `drilldown`, so a drilldown round-trips as a filter. `segment` applies to the segments view only. */
+        type FilterKey = "metric" | "type" | "output" | "flag" | "client" | "channel" | "rep" | "team" | "mission" | "segment";
+        /** Resolved to label ids before matching ("rows whose metric involves these labels"); each key ANDs independently. The operator is ignored (always `in`). */
+        type LabelFilterKey = "label" | "label_group" | "product_brand" | "product_category";
+        /** Both names address the result's `createdAt`. */
+        type TimeKey = "time" | "createdAt";
+        /** Time-bucket drilldowns: `YYYY-MM-DD` / `YYYY-MM` / ISO week `GGGG-Www` — each sets the whole time range. */
+        type BucketKey = "business_day" | "month" | "week";
+        type FilterOperator = "in" | "nin" | "eq" | "ne";
+        /** Time presets the filter UI sends without a value (company time zone). */
+        type TimePreset = "today" | "yesterday" | "last_seven_days" | "last_thirty_days" | "last_month" | "last_three_months" | "last_six_months" | "last_twelve_months";
+        interface FilterCriterion {
+            key: FilterKey;
+            /** Default `in`. */
+            operator?: FilterOperator;
+            /** 24-hex ids (cast to ObjectId) for id keys; strings for `type` / `output`; booleans (or "true") for `flag`. Non-id values on id keys are dropped. */
+            value: (StringId | string | boolean)[] | StringId | string | boolean;
+        }
+        interface LabelCriterion {
+            key: LabelFilterKey;
+            operator?: "in";
+            value: StringId[] | StringId;
+        }
+        interface TimeBetweenCriterion {
+            key: TimeKey;
+            operator: "between";
+            /** `[from_ms, to_ms]`. */
+            value: [number, number];
+        }
+        interface TimeBoundCriterion {
+            key: TimeKey;
+            operator: "gte" | "lte";
+            /** ms epoch. */
+            value: number | [number];
+        }
+        interface TimePresetCriterion {
+            key: TimeKey;
+            operator: TimePreset;
+            value?: never;
+        }
+        interface BucketCriterion {
+            key: BucketKey;
+            operator?: "eq" | "in";
+            /** One bucket string, e.g. `"2026-07-15"`, `"2026-07"`, `"2026-W29"`. */
+            value: string | [string];
+        }
+        type Criterion = FilterCriterion | LabelCriterion | TimeBetweenCriterion | TimeBoundCriterion | TimePresetCriterion | BucketCriterion;
+        /** `type` / `output` are metrics-view only, `segment` is segments-view only — keys not accepted by the current view are dropped silently. */
+        type GroupKey = "metric" | "type" | "output" | "client" | "channel" | "rep" | "mission" | "segment" | "business_day" | "month" | "week";
+        /** Sort keys the query-string `sortBy` accepts. */
+        type SortField = "_id" | "time" | "createdAt" | "score" | "answer" | "metric_name" | "client_name" | "channel_name" | "segment_name" | "segment_ratio" | "segment_answer" | "row_count" | "avg_score" | "avg_ratio" | "avg_answer";
+        interface SortOption {
+            /** `options.sort` fields must exist in the report's sort metadata (`sort_fields` of a previous response); unknown fields fall back to the default sort. */
+            field: SortField | (string & {});
+            type: "asc" | "desc";
+        }
+        interface CreateBody {
+            /** Default `metrics`. */
+            view?: View;
+            /** Only `anyOf[0].criteria` is honoured — one AND-ed group. */
+            anyOf?: {
+                criteria: Criterion[];
+            }[];
+            /** Group keys, e.g. `[{ _id: "channel" }, { _id: "month" }]`. Grouped rows carry `drilldown` + aggregates. */
+            group?: {
+                _id: GroupKey;
+            }[];
+            /** Column keys to show (ungrouped rows only). */
+            projection?: string[];
+            /** Optional column override; defaults come from the report metadata (`object-detection-metrics` / `object-detection-segments`). */
+            columns?: ReportColumn[];
+            options?: {
+                /** Rows per page (the query-string `per_page` is NOT honoured here). */
+                limit?: number;
+                page?: number;
+                /** Default: `row_count` desc when grouped, `time` desc when flat. */
+                sort?: SortOption[];
+                /** Default `none`. */
+                totals_summary?: "all" | "page" | "none";
+            };
+        }
+        /** Filter-compatible ids / buckets of a grouped row — spread it as query params (or criteria) on the next call to get the detail rows. */
+        interface Drilldown {
+            metric?: StringId;
+            type?: MetricType;
+            output?: MetricOutput;
+            client?: StringId;
+            channel?: StringId;
+            rep?: StringId;
+            mission?: StringId;
+            segment?: StringId;
+            business_day?: string;
+            month?: string;
+            week?: string;
+        }
+        /** One report row. Flat rows carry the result fields; grouped rows carry `drilldown`, the aggregates and the grouped identity names / buckets. */
+        interface Data {
+            /** Metric result id — flat rows only. */
+            _id?: StringId;
+            /** Result creation time (ms). */
+            time?: number;
+            /** `YYYY-MM-DD` in the company time zone. */
+            business_day?: string;
+            /** `YYYY-MM-DD HH:mm:ss`. */
+            timestamp?: string;
+            /** `YYYY-MM`. */
+            month?: string;
+            /** ISO week `GGGG-Www`. */
+            week?: string;
+            metric_id?: StringId;
+            metric_name?: string;
+            metric_type?: MetricType;
+            output?: MetricOutput;
+            flag?: boolean;
+            /** 0..1, rounded to 4 decimals. */
+            score?: number;
+            client_id?: StringId;
+            client_name?: string;
+            channel_id?: StringId;
+            channel_name?: string;
+            rep_id?: StringId;
+            rep_name?: string;
+            /** The mission the session was STARTED FROM — absent on generic scans. */
+            mission_id?: StringId;
+            mission_name?: string;
+            teams_ids?: StringId[];
+            session_id?: StringId;
+            analysis_id?: StringId;
+            /** metrics view — effective answer (confirmed human override wins): boolean for compatibility, number otherwise. */
+            answer?: boolean | number | null;
+            /** metrics view — effective ratio (availability / main-segment share). */
+            ratio?: number;
+            /** segments view */
+            segment_id?: StringId;
+            segment_name?: string;
+            /** segments view — `main` = the row the target is defined for, else `context`. */
+            is_main?: "main" | "context";
+            /** segments view — measured quantity in `measure` units (2 decimals). */
+            segment_answer?: number;
+            /** segments view — the segment's share 0..1 (4 decimals). */
+            segment_ratio?: number;
+            /** segments view — main rows only. */
+            target_ratio?: number;
+            target_answer?: number;
+            segment_score?: number;
+            measure?: Measure;
+            /** grouped rows */
+            drilldown?: Drilldown;
+            row_count?: number;
+            avg_score?: number;
+            avg_answer?: number;
+            /** grouped, segments view — average share. */
+            avg_ratio?: number;
+            /** grouped, segments view — rows where the segment is the main one. */
+            main_rows?: number;
+            /** grouped, metrics view — flagged results. */
+            flagged?: number;
+            /** grouped by `type` — the metric-type bucket. */
+            type?: MetricType;
+            [key: string]: any;
+        }
+        /** Visible table columns for the current state (grouped vs flat). */
+        interface AnalyticsKey {
+            key: string;
+            /** Translated column label. */
+            value: string;
+            type: "string" | "number";
+            visible: boolean;
+        }
+        /** Present when `options.totals_summary` is `all` (fills `absolute_total`) or `page` (fills `page_total`). Labels: "Rows", "Average Score" (+ "Average Share" on segments). */
+        interface Totals {
+            absolute_total: {
+                [label: string]: number;
+            };
+            page_total: {
+                [label: string]: number;
+            };
+            labels: {
+                key: string;
+                value: string;
+            }[];
+        }
+        /** Returned INSTEAD of rows when the `export` query param is set — the report is queued and emailed to the caller. */
+        interface ExportResult {
+            _id: StringId;
+            success: boolean;
+            msg: string;
+            isExport: boolean;
+        }
+        /** Query keys honoured next to the POST body (drilldown round-trips + export). `per_page` / `page` are NOT honoured — use `options.limit` / `options.page`. */
+        interface QueryParams {
+            /** Fallback when the body has no `view`. */
+            view?: View;
+            metric?: StringId | StringId[];
+            type?: MetricType | MetricType[];
+            output?: MetricOutput | MetricOutput[];
+            flag?: boolean;
+            client?: StringId | StringId[];
+            channel?: StringId | StringId[];
+            rep?: StringId | StringId[];
+            team?: StringId | StringId[];
+            /** The mission the session was started from. */
+            mission?: StringId | StringId[];
+            /** Segments view only. */
+            segment?: StringId | StringId[];
+            label?: StringId | StringId[];
+            label_group?: StringId | StringId[];
+            product_brand?: StringId | StringId[];
+            product_category?: StringId | StringId[];
+            /** ms epoch — every read is time-bounded; default window = the last 30 days. */
+            from_time?: number;
+            to_time?: number;
+            /** `YYYY-MM-DD` — sets the whole range (overrides from_time / to_time). */
+            business_day?: string;
+            /** `YYYY-MM`. */
+            month?: string;
+            /** ISO week `GGGG-Www`. */
+            week?: string;
+            /** Query-string sort (takes precedence over `options.sort`). */
+            sortBy?: {
+                field: SortField;
+                type: "asc" | "desc";
+            }[];
+            /** `excel` schedules an emailed export instead of returning rows — the response is then an `ExportResult`. */
+            export?: "excel";
+            /** Subject / name of the scheduled export email (default "Detection Analytics"). */
+            emailSubject?: string;
+        }
+        interface PaginatedResult extends DefaultPaginationResult {
+            data: Data[];
+            keys: AnalyticsKey[];
+            /** The report's column metadata (sorted by `position`), or the `columns` override echoed back. */
+            columns: ReportColumn[];
+            totals?: Totals;
+            /** The report's sort metadata rows — the valid `options.sort` fields. */
+            sort_fields: ReportSort.Data[];
+        }
+        namespace Find {
+            /** Legacy GET — a thin adapter onto the POST read (`view` + `group` from the query, filters via the same query keys). */
+            type Params = QueryParams & {
+                /** Group keys — array or comma-separated string. */
+                group?: GroupKey | GroupKey[];
+            };
+            type Result = PaginatedResult;
+        }
+        namespace Create {
+            type Params = QueryParams;
+            type Body = CreateBody;
+            type Result = PaginatedResult;
+        }
+    }
 }
 export type StringId = string;
 export type NameSpaces = string[];