@trillboards/edge-sdk 0.2.95 → 0.2.98

package/dist/DetectorFieldProducer.js

@@ -0,0 +1,691 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetectorFieldProducer = exports.DETECTOR_MODEL_JOIN = exports.CONCEPT_KEY_RE = exports.toDetectorClassName = exports.DEFAULT_PRODUCE_DEADLINE_MS = exports.DEFAULT_PRODUCER_TIMEOUT_MS = exports.DEFAULT_PRODUCER_MIN_CONFIDENCE = exports.PRODUCER_WITHHOLD_REASONS = void 0;
+exports.classifyProducerField = classifyProducerField;
+exports.countsForClasses = countsForClasses;
+exports.toFieldValues = toFieldValues;
+/**
+ * DetectorFieldProducer — the connector's detector→declared-field producer.
+ *
+ * ── THE GAP THIS CLOSES ────────────────────────────────────────────────────
+ *
+ * The Android agent has had one of these for a year: `QueueEstimationProcessor`
+ * turns EfficientDet detections into `pedestrian_count` / `queue_length` /
+ * `queue_detected`, keyed under the model that produced them
+ * (`AudienceSensingService.kt:3090` — `model_outputs.efficientdet.{…}`), and
+ * those are exactly the fields `efficientdet` declares in its registry
+ * `outputs_schema`.
+ *
+ * The connector has had none. It runs a real detector on 127.0.0.1:9380 at
+ * 15–90 ms a frame, and the only thing that consumes the result is
+ * `DetectorShadowProbe`, which collapses the whole detection set to a
+ * three-valued enum and discards the boxes. So "how many people are there" —
+ * a question the detector answers in milliseconds, with boxes — was answered by
+ * asking a language model in prose at ~5,645 ms, at ~9% precision on specifics
+ * (docs/runbooks/sensing-catch-rate.md §4a).
+ *
+ * ── ONE FIELD, ONE PRODUCER ────────────────────────────────────────────────
+ *
+ * The input is the `producer` half of `modelClassLiveness.partitionProfileFields`
+ * — `{field, modelId, type}` per entry, where `modelId` is the model whose
+ * registry row DECLARES that field as an output. Ownership is data; this file is
+ * only the resolution. Nothing here decides which model answers a field, and it
+ * must never acquire that opinion: a second place that can decide is how one
+ * fact ends up with two producers, which is the defect the partition exists to
+ * remove.
+ *
+ * The output is TOTAL: `produced.length + withheld.length === fields.length`,
+ * always, on every path including the ones where the detector never answered.
+ * Same contract, and the same reason, as the partition's own
+ * `producer ∪ vlm ∪ withheld === fields`: two independent filters that must
+ * agree is precisely how a field goes missing with nothing to point at.
+ *
+ * This is also why the input is the PARTITION and not the profile's raw
+ * `fields[]`. `person_count` is already in `localInferenceSchema`'s
+ * `PRESENCE_PRIMITIVE_ORDER`, so every profile asks the language model for it
+ * today; a producer handed the raw list would answer it as well and the reading
+ * an operator saw would depend on which component wrote last. The partition is
+ * what takes a produced field OUT of the prompt, and a producer that could not
+ * be told which fields those are could not be correct.
+ *
+ * ── A GRANTED MODEL WHOSE BYTES NEVER LANDED YIELDS A *MISSING* FIELD ──────
+ *
+ * A model can be granted by the profile and still be absent from the box: the
+ * grant comes from `GET /v2/earner/cameras/sensing-profile` and the artifact
+ * arrives separately over `/v1/federated/models`, which was 404 for sixteen days
+ * in August.
+ *
+ * THAT HAS TWO DOORS, and only the first one looks like a failure:
+ *
+ *   the class is unknown to the box — no resident model can emit it, so the
+ *     service answers **400 before inference** (`server.py::_detect`,
+ *     deliberately, on ANY unknown class) and `LocalDetectorClient` raises
+ *     `DetectorUnavailableError`.
+ *
+ *   the class is owned by SOMEBODY ELSE — a different resident model declares
+ *     it, so the call **succeeds with a 200** and a perfectly good answer from
+ *     the wrong instrument. Overlap is the norm: `hardhat` is declared by both
+ *     `ppe_vyra_14cls_v8m` and `ppe_construction_17cls_v8n`, `person` by those
+ *     two plus `rfdetr_medium`. The attribution check in `produce()` is the only
+ *     thing that closes this one — see the long note at its call site before
+ *     deciding it is redundant with the 400.
+ *
+ * In BOTH the field is then ABSENT. Not `false`, not `0`, and — the important
+ * one — NOT handed to the language model instead.
+ * `routeEvaluatorService.js:1272` already gets this right one layer up: a
+ * focused route reads only its mapped field and yields `no_field` rather than
+ * falling back. Substituting a different producer
+ * mid-flight is the split-brain again, in TIME instead of space: the same
+ * question, answered by two different instruments on two different frames, with
+ * nothing on the reading saying which.
+ *
+ * ── `unavailable` NEVER COLLAPSES INTO `empty` ─────────────────────────────
+ *
+ * Structural, not a convention: a value is written in exactly one place in this
+ * file, from a count derived from a parsed 2xx. There is no path from a caught
+ * error to a `false` or a `0`. Every failure — transport, 400, 503, a 2xx whose
+ * envelope is not the contract, the budget running out — lands in `withheld`.
+ *
+ * `LocalDetectorClient` and `DetectorShadowProbe` both carry this distinction in
+ * their own headers, and it is the same one: a cascade that reads "detector
+ * down" as "nobody there" suppresses every alert while `postCount`,
+ * `sensingState:'active'` and the portal's "AI active" tile all stay green
+ * (docs/runbooks/cctv-connector-runtime-edge-cases.md).
+ *
+ * ── ONE CALL PER MODEL, NOT ONE CALL PER FRAME ─────────────────────────────
+ *
+ * The service refuses a request naming ANY class it cannot resolve — it does not
+ * answer the part it recognises — and its own comment says why: "Refusing costs
+ * the `person` detections too; that is the right trade." That is correct for ONE
+ * question. A frame's declared fields are N INDEPENDENT questions, and unioning
+ * them into a single call would make them share a fate they do not share: one
+ * specialist whose bytes never landed would take `person_count` down with it.
+ *
+ * So the classes are grouped by the `modelId` the partition already supplies,
+ * one call per model, each carrying the union of the classes THAT model's fields
+ * need. A model that cannot answer loses its own fields and no others.
+ *
+ * This is not the connector holding a class→model catalogue. It cannot and must
+ * not: `docs/runbooks/sensing-model-library.md` is explicit that the service
+ * owns class→model routing because it is the only component that knows what is
+ * resident, and the wire carries `classes` and no model selector. The grouping
+ * here is FAILURE ISOLATION over an ownership fact the server sent us.
+ *
+ * Calls run SEQUENTIALLY. The box has one inference slot; issuing them in
+ * parallel queues them inside the service and spends the budget on scheduling.
+ *
+ * @reuse-audit
+ *   considered: services/regression/detectorCorpusEndpoint.js
+ *     - reused, as the SEMANTICS this file is a second implementation of: the
+ *       `<concept>_present` / `<concept>_count` key shape, `toDetectorClassName`
+ *       byte-for-byte, and the "trim each class at its own threshold, throw on a
+ *       label nobody asked for" rule, comments included. NOT imported: that is
+ *       CommonJS inside the API image and this is the connector's TypeScript
+ *       bundle; the API does not ship edge-sdk and edge-sdk does not ship the
+ *       API. What keeps them from drifting is that they answer the same corpus —
+ *       the six live `expected_output` keys (`person_count`, `person_present`,
+ *       `forklift_present`, `hardhat_present`, `excavators_present`,
+ *       `fire_extinguisher_present`) ARE the field names, and
+ *       `__tests__/DetectorFieldProducer.test.ts` pins this side onto the classes
+ *       those models declare in `coco_classes`.
+ *     - ONE DELIBERATE DIVERGENCE, marked at `countsForClasses`: its single-class
+ *       branch returns `detections.length` unread, and this one reads the label
+ *       on every branch. That is not a port that drifted — it is the same
+ *       principle under a different consumer. See the note there before
+ *       "restoring" it.
+ *   considered: trillboard-ctv/.../audience/QueueEstimationProcessor.kt
+ *     - reused: its SHAPE. A processor that turns one frame's detection set into
+ *       a map keyed by registry-canonical snake_case field names, with the
+ *       producing model's id travelling ON the values (`model_outputs.<modelId>`)
+ *       so a reading can be attributed. `toJson`'s note — "keys use
+ *       registry-canonical snake_case so `chipPersistence.sanitizeFieldKey` is
+ *       idempotent on canonical input" — is why `produced[].field` is the
+ *       DECLARED name verbatim and is never re-spelled here.
+ *     - deliberately NOT ported: its temporal half — `serviceRatePerMinute`,
+ *       `estimatedWaitTimeMinutes`, `trend`, and the 30-snapshot history they
+ *       are derived from. Nothing in any producer half declares those fields, so
+ *       emitting them would advertise a capability no registry row owns — the
+ *       `yolov8_nano` shape, where a model was offered to ~97 of 114 profile
+ *       authors while every device hardcoded it unloadable. When a model DOES
+ *       declare `queue_length`, that is a field with an owner and it arrives
+ *       here as an ordinary producer entry.
+ *   considered: edge-sensing/src/processors/FaceDetector.ts — `nonMaxSuppression`
+ *     + `iou` (the kernel `LocalDetectorClient`'s header names as the one to use)
+ *     - deliberately NOT used, and this is the one worth reading twice. The
+ *       SERVICE already ran NMS: `deploy/detector/trillboards_detector/decode.py`
+ *       does class-offset greedy NMS at `NMS_IOU_THRESHOLD = 0.7` on the anchor
+ *       branch, transcribed from ultralytics, and deliberately runs NONE on the
+ *       DETR branch because "running NMS over these rows would be a second
+ *       suppression the model was neither trained nor scored with". A pass here
+ *       would be exactly that second suppression, on both branches, and it would
+ *       move the counts away from the ones the committed score cards fitted their
+ *       thresholds against. The kernel is fine; a fourth suppression is not.
+ *   considered: edge-core `CentroidTracker` (the shared nearest-centroid tracker)
+ *     - deliberately NOT used: no field in any producer half needs cross-frame
+ *       identity. `<concept>_present` and `<concept>_count` are both properties
+ *       of ONE frame — which is also how the Android processor computes
+ *       `estimatedQueueLength` (`current.faceCount`, the latest snapshot). Wiring
+ *       a tracker in for fields that do not ask for one would add per-feed state
+ *       with no consumer. When dwell or a unique count lands, that tracker is the
+ *       one to call — it is already the consolidation of three, and a fourth is
+ *       what its own header exists to prevent.
+ *   considered: this package's `zoneContainment.countInZone`
+ *     - not used HERE: it takes a frame size and a normalized rect, and with a
+ *       null rect it IS `boxes.length`. A field focused to an operator's drawn
+ *       region is the natural next consumer of both files at once — the count
+ *       becomes `countInZone(boxes, frame, rect)` and nothing else changes — but
+ *       a producer entry carries no region today and inventing one would be a
+ *       second home for a fact `sensing_route_screens` already owns.
+ *   considered: `DetectorShadowProbe`
+ *     - not extended, and not called: it is a MEASUREMENT that must change
+ *       nothing, with a backoff and a 15 s per-feed cadence bound tuned to that
+ *       job. A producer answering an operator's declared field is a PRODUCT path
+ *       with the opposite cadence obligation.
+ *   considered: edge-core `ModelManager.hasModel(modelId)` — the connector's own
+ *     "is this artifact on disk" check (`fs.existsSync` over the registered path)
+ *     - deliberately NOT used as the arrival gate. It answers about the
+ *       CONNECTOR's download directory; what decides whether a class can be
+ *       answered is the SERVICE's `ClassIndex`, which `labels.py` builds only
+ *       over models whose artifact is on the box. Those are two opinions about
+ *       one fact and they can disagree — a file present but the wrong graph
+ *       (`ModelContractError`), or resident in a service started before the
+ *       download. Pre-checking here would also mean a `hasModel` that returned
+ *       true still has to handle the 400, so the check would be advisory at best
+ *       and a second catalogue at worst. The 400 IS the arrival check, from the
+ *       only component that knows.
+ */
+const LocalDetectorClient_1 = require("./LocalDetectorClient");
+/** Why a declared field has no reading this frame. */
+exports.PRODUCER_WITHHOLD_REASONS = {
+    /**
+     * The field name is not `<concept>_present` / `<concept>_count`, so no
+     * detector class can be derived from it.
+     *
+     * WITHHELD RATHER THAN DROPPED. A registry row may declare `queue_length` or
+     * `vehicle_trend` — `efficientdet` declares both — and a detection set answers
+     * neither. Guessing a class out of `trend` is how a bus gets counted as a
+     * person; silently dropping it is how a field goes missing with nothing to
+     * point at.
+     */
+    UNMAPPED: 'unmapped',
+    /**
+     * The declared type contradicts what the name asks for — a `_present` field
+     * declared `counter`, say.
+     *
+     * The suffix decides the COMPUTATION and the type is the published contract;
+     * when they disagree the row is defective and either answer is wrong. Refusing
+     * names the defect instead of writing a boolean into a slot rendered as a
+     * number.
+     */
+    TYPE_CONTRADICTS_NAME: 'type_contradicts_name',
+    /**
+     * The detector did not answer for this field's model.
+     *
+     * Transport, 400 (a class no resident model can emit — i.e. a granted model
+     * whose bytes never landed), 503, a 2xx whose envelope is not the contract, a
+     * response labelled with a class nobody asked for, or the budget running out.
+     * All of them mean the same thing to a consumer: there is NO READING. None of
+     * them may become a value.
+     */
+    DETECTOR_UNAVAILABLE: 'detector_unavailable',
+    /**
+     * The entry names no model.
+     *
+     * Its own reason rather than `unmapped`, because it is a defect in a different
+     * place: the NAME was readable and it is the OWNERSHIP that is missing. The
+     * partition cannot emit such an entry — it only puts a field in `producer[]`
+     * once it has found an owner — so this is a claim about a caller, and saying
+     * "no class follows from that name" about it would send the reader to the
+     * registry's `outputs_schema` when the fault is upstream of it.
+     *
+     * It is refused rather than answered anonymously. The class list would resolve
+     * fine and the count would be correct; what would be lost is attribution, and
+     * "a detection whose producer cannot be named is a detection that cannot be
+     * attributed when a specialist later turns out to be wrong"
+     * (`deploy/detector/trillboards_detector/detections.py`).
+     */
+    UNOWNED: 'unowned',
+    /**
+     * The same field name appeared twice in the producer half.
+     *
+     * The first occurrence is answered and the rest are withheld, so the total
+     * contract holds over the input array exactly. A repeated field is the "one
+     * fact, two answers" defect at its smallest scale and it is worth a name.
+     */
+    DUPLICATE: 'duplicate',
+};
+/**
+ * The device's operating point when a model measured none of its own. 0.25.
+ *
+ * `LocalDetectorClient`'s default, and a FALLBACK rather than an answer — the
+ * same constant and the same caveat as
+ * `detectorCorpusEndpoint.DEFAULT_MIN_CONFIDENCE`. A model whose score card
+ * SELECTED a threshold must be counted at THAT threshold or the field is
+ * produced by a classifier no committed measurement describes: `gh_forklift_combine`
+ * fits 0.7435 and `rfdetr_medium`'s person gate 0.2939, and at 0.25 the
+ * published precision/recall simply do not apply to what shipped.
+ */
+exports.DEFAULT_PRODUCER_MIN_CONFIDENCE = 0.25;
+/**
+ * Per-call transport timeout. 1000 ms, matching `DEFAULT_SHADOW_TIMEOUT_MS`.
+ *
+ * NOT `LocalDetectorClient`'s own 5 s default: this runs on the path to an
+ * analysis, and the detector's measured cost is ~63 ms p50 / ~79 ms p95, so
+ * 1000 ms is >12x headroom for the slowest plausible answer.
+ */
+exports.DEFAULT_PRODUCER_TIMEOUT_MS = 1000;
+/**
+ * TOTAL budget across every model call for one frame. 1500 ms.
+ *
+ * A total and not a per-call bound, because the question it answers is "how long
+ * may producing this frame's fields hold the tick", and that is a property of
+ * the frame, not of one model. At the measured p95 a four-model portfolio costs
+ * ~316 ms, so this is ~4.7x headroom and cannot bind on a healthy box.
+ *
+ * When it DOES bind, the models that never got their call are withheld
+ * `detector_unavailable` — a missing field, which is the same discipline the
+ * 400 case gets and for the same reason. A budget that returned a value it did
+ * not measure would be worse than one that stalls.
+ *
+ * It bounds the number of calls STARTED and, via the per-call timeout below,
+ * how long each may sit idle. It does not close the one hole
+ * `LocalDetectorClient`'s header names — a server dribbling bytes slowly under a
+ * large Content-Length keeps the socket busy so the inactivity timer never fires
+ * — because that hole is in the transport and belongs to every client in this
+ * package; two call-site races for it already exist and a third is not the fix.
+ */
+exports.DEFAULT_PRODUCE_DEADLINE_MS = 1500;
+/**
+ * The detector's canonical wire spelling.
+ *
+ * `normalize_class_name` in
+ * `deploy/detector/trillboards_detector/labels.py` is
+ * `name.strip().lower().replace("_", " ").replace("-", " ")`, and `labels.py`
+ * REFUSES to import a vocabulary whose names are not already folded — so this is
+ * the only spelling `/detect` resolves. A field carries its concept in the
+ * spelling a JSON key can hold (`fire_extinguisher`); the service is asked in
+ * the spelling it demands (`fire extinguisher`). One fold, one place.
+ *
+ * Byte-identical to `detectorCorpusEndpoint.toDetectorClassName`, deliberately:
+ * the corpus that GATES a model's rollout and the producer that READS it in the
+ * field must ask for the same class, or the thing measured is not the thing that
+ * ships.
+ */
+const toDetectorClassName = (name) => String(name).trim().toLowerCase().replace(/[_-]+/g, ' ');
+exports.toDetectorClassName = toDetectorClassName;
+/** The producible key shape: `<concept>_present`, `<concept>_count`. */
+exports.CONCEPT_KEY_RE = /^(.+)_(present|count)$/;
+/**
+ * How the service joins the names of the models that answered one frame.
+ *
+ * `MODEL_JOIN` in `deploy/detector/trillboards_detector/server.py`, where
+ * `model` is `MODEL_JOIN.join(batch.models)` — one name on a single-model box, N
+ * for a request the registry split across several. Held here because the
+ * attribution check below has to take that string apart again, and a wrong
+ * separator would silently make every merged answer look unattributed.
+ */
+exports.DETECTOR_MODEL_JOIN = '+';
+/** Declared types a `<concept>_count` field may carry. */
+const COUNT_TYPES = new Set(['counter', 'gauge']);
+/** Declared types a `<concept>_present` field may carry. */
+const PRESENT_TYPES = new Set(['boolean']);
+/**
+ * Read a declared field name, or say why it cannot be read.
+ *
+ * The SUFFIX decides the computation — that is the vocabulary the corpus is
+ * written in and the only self-describing signal on the entry. The declared type
+ * is then checked AGAINST it rather than consulted instead of it: a null type is
+ * fine (plenty of registry rows carry none), and a type that contradicts the
+ * name is a defective row rather than an instruction.
+ */
+function classifyProducerField(entry) {
+    const field = typeof entry?.field === 'string' ? entry.field.trim() : '';
+    const match = exports.CONCEPT_KEY_RE.exec(field);
+    if (!match) {
+        return {
+            reason: exports.PRODUCER_WITHHOLD_REASONS.UNMAPPED,
+            detail: `'${field}' is neither <concept>_present nor <concept>_count, so no detector class follows from it`,
+        };
+    }
+    const [, concept, suffix] = match;
+    const kind = suffix === 'present' ? 'present' : 'count';
+    const declared = typeof entry.type === 'string' ? entry.type.trim().toLowerCase() : '';
+    if (declared) {
+        const allowed = kind === 'present' ? PRESENT_TYPES : COUNT_TYPES;
+        if (!allowed.has(declared)) {
+            return {
+                reason: exports.PRODUCER_WITHHOLD_REASONS.TYPE_CONTRADICTS_NAME,
+                detail: `'${field}' is a _${suffix} field but its owning row declares type '${declared}'; `
+                    + `expected one of [${[...allowed].join(', ')}]`,
+            };
+        }
+    }
+    return {
+        ...entry,
+        field,
+        concept,
+        className: (0, exports.toDetectorClassName)(concept),
+        kind,
+    };
+}
+/**
+ * How many instances of each asked class this answer contains.
+ *
+ * Ported decision-for-decision from `detectorCorpusEndpoint.countsForConcepts`,
+ * because the corpus that gates a rollout and the producer that reads the model
+ * in the field must count the same way.
+ *
+ * @throws when the service returned a label nobody asked for — see below.
+ */
+function countsForClasses(classes, detections, classThresholds) {
+    // ONE PATH, INCLUDING FOR A SINGLE ASKED CLASS — and this is the one place
+    // this file deliberately DIVERGES from `countsForConcepts`, which returns
+    // `detections.length` unread on the single-class branch.
+    //
+    // That branch is right THERE and wrong HERE, because the two consumers make a
+    // miscount loud in different ways. The corpus endpoint compares its answer
+    // against a fixture's `expected_output`, so a service that ignored `classes`
+    // produces a wrong count that FAILS the corpus — counting blindly is what
+    // makes the defect visible. In production nothing compares anything: a
+    // `forklift_count` of 2 from one `forklift` and one `forklift_partial` is a
+    // plausible number that ships and is believed.
+    //
+    // So the PRINCIPLE ports and the code does not. "Never quietly correct a
+    // broken class filter" becomes "refuse the group", which is this consumer's
+    // form of loud. Reading the label costs nothing and the service already
+    // narrows the response to the asked set (`ClassIndex.assign` routes each class
+    // to exactly one owner and `_to_wire` filters to the wanted set), so a label
+    // outside that set means the filter did not happen.
+    const counts = new Map(classes.map((className) => [className, 0]));
+    const unrequested = new Set();
+    for (const det of detections) {
+        const label = (0, exports.toDetectorClassName)(det?.label);
+        if (!counts.has(label)) {
+            unrequested.add(String(det?.label));
+            continue;
+        }
+        // The wire carried the MINIMUM threshold across the asked classes, because
+        // `min_confidence` is one scalar and the service applies it to all of them.
+        // So a class with a higher operating point is still holding detections below
+        // its own, and counting them here would score it at somebody else's
+        // threshold. Trim per class, at its own number.
+        //
+        // A class with NO entry is counted at whatever the service already applied.
+        // `DetectorFieldProducer` never leaves one out — it passes an EFFECTIVE map
+        // with an entry per asked class, `configured ?? fallback` — because without
+        // that, one fitted 0.05 class in the group drags the request minimum down
+        // and every unmeasured class beside it silently counts detections its own
+        // documented 0.25 fallback would have rejected.
+        //
+        // The unrequested-label check above stays FIRST and unconditional: a
+        // detection the service should never have returned is a broken class filter
+        // and must throw, whatever its confidence. Dropping it quietly for being
+        // low-confidence would hide exactly the defect that check exists for.
+        const floor = classThresholds?.get(label);
+        if (Number.isFinite(floor) && Number.isFinite(det?.confidence) && det.confidence < floor)
+            continue;
+        counts.set(label, counts.get(label) + 1);
+    }
+    if (unrequested.size) {
+        throw new Error('detector returned detections labelled '
+            + `[${[...unrequested].sort().join(', ')}] after being asked for [${classes.join(', ')}] `
+            + '— the service did not apply the class filter, so these counts cannot be attributed');
+    }
+    return counts;
+}
+class DetectorFieldProducer {
+    constructor(options = {}, clientFactory) {
+        this.baseUrl = options.baseUrl;
+        this.timeoutMs = Math.max(1, Math.trunc(options.timeoutMs ?? exports.DEFAULT_PRODUCER_TIMEOUT_MS));
+        this.deadlineMs = Math.max(0, Math.trunc(options.deadlineMs ?? exports.DEFAULT_PRODUCE_DEADLINE_MS));
+        this.classThresholds = options.classThresholds instanceof Map ? options.classThresholds : new Map();
+        this.minConfidence = Number.isFinite(options.minConfidence)
+            ? options.minConfidence
+            : exports.DEFAULT_PRODUCER_MIN_CONFIDENCE;
+        this.now = options.now ?? Date.now;
+        this.clientFor =
+            clientFactory
+                ?? ((opts) => new LocalDetectorClient_1.LocalDetectorClient({
+                    ...(this.baseUrl ? { baseUrl: this.baseUrl } : {}),
+                    classes: opts.classes,
+                    minConfidence: opts.minConfidence,
+                    timeoutMs: opts.timeoutMs,
+                }));
+    }
+    /**
+     * Produce this frame's declared fields.
+     *
+     * NEVER THROWS and never returns a promise that rejects: it would sit on the
+     * path to the only thing that produces alerts, and a producer that can fail a
+     * capture tick is worse than one that reports it has no reading.
+     *
+     * @param jpeg   the frame's bytes
+     * @param fields the `producer` half of this profile's field partition
+     */
+    async produce(jpeg, fields) {
+        const produced = [];
+        const withheld = [];
+        const entries = Array.isArray(fields) ? fields : [];
+        if (entries.length === 0)
+            return { produced, withheld };
+        // ── Read every name first, so nothing is asked for that cannot be used ──
+        const mapped = [];
+        const seen = new Set();
+        for (const entry of entries) {
+            const modelId = typeof entry?.modelId === 'string' ? entry.modelId : '';
+            const read = classifyProducerField(entry);
+            if ('reason' in read) {
+                withheld.push({ field: String(entry?.field ?? ''), modelId, reason: read.reason, detail: read.detail });
+                continue;
+            }
+            // OWNERSHIP BEFORE COLLISION. Both checks can fire on one entry, and this
+            // order gives the more useful diagnosis: "this entry names no model" is a
+            // fault in the entry itself, while "already answered" is only meaningful
+            // between two entries that are otherwise well formed. Reporting the
+            // collision first would send the reader looking for a duplicate field when
+            // what is actually broken is that neither copy has an owner.
+            if (!modelId) {
+                // No owner means no group to ask in, and inventing one would be this
+                // file deciding ownership — the one thing it must never do.
+                withheld.push({
+                    field: read.field,
+                    modelId,
+                    reason: exports.PRODUCER_WITHHOLD_REASONS.UNOWNED,
+                    detail: `'${read.field}' carries no modelId, so no model owns it`,
+                });
+                continue;
+            }
+            if (seen.has(read.field)) {
+                withheld.push({
+                    field: read.field,
+                    modelId,
+                    reason: exports.PRODUCER_WITHHOLD_REASONS.DUPLICATE,
+                    detail: `'${read.field}' was already answered in this partition`,
+                });
+                continue;
+            }
+            seen.add(read.field);
+            mapped.push({ ...read, modelId });
+        }
+        if (mapped.length === 0)
+            return { produced, withheld };
+        // ── Group by owning model. Insertion-ordered, so the answer is stable. ──
+        const groups = new Map();
+        for (const m of mapped) {
+            const bucket = groups.get(m.modelId);
+            if (bucket)
+                bucket.push(m);
+            else
+                groups.set(m.modelId, [m]);
+        }
+        const startedAtMs = this.now();
+        for (const [modelId, groupFields] of groups) {
+            const classes = [...new Set(groupFields.map((f) => f.className))];
+            // The budget, checked BEFORE the call rather than raced against it. A call
+            // never started cannot be half-answered.
+            const remainingMs = this.deadlineMs > 0
+                ? this.deadlineMs - (this.now() - startedAtMs)
+                : Number.POSITIVE_INFINITY;
+            if (remainingMs <= 0) {
+                this.withholdGroup(withheld, groupFields, modelId, 'deadline', `frame budget of ${this.deadlineMs}ms was spent before ${modelId} was asked`);
+                continue;
+            }
+            // EVERY asked class gets an operating point — its own fitted one, or the
+            // device fallback. Not "the fitted ones, if any": with a 0.05 fitted class
+            // beside an unmeasured one, the request goes out at 0.05 and the trim below
+            // would skip the unmeasured class entirely, counting detections between
+            // 0.05 and its documented 0.25 fallback. The fallback has to be a real
+            // number in the map or it is not applied at all.
+            const effectiveThresholds = new Map(classes.map((className) => [
+                className,
+                this.classThresholds.get(className) ?? this.minConfidence,
+            ]));
+            // The threshold this REQUEST is made at. `min_confidence` is one scalar for
+            // the whole call, so with more than one class asked it has to be the LOWEST
+            // of their operating points or the service would suppress a class below its
+            // own gate before we ever see it; `countsForClasses` then trims each class
+            // back to its own number. With one class asked this IS that class's
+            // threshold and the service applies it exactly.
+            const minConfidence = Math.min(...effectiveThresholds.values());
+            const client = this.clientFor({
+                classes,
+                minConfidence,
+                timeoutMs: Math.max(1, Math.min(this.timeoutMs, Math.trunc(remainingMs))),
+            });
+            let counts;
+            let detectorModel;
+            try {
+                const result = await client.detect(jpeg);
+                // THROWS on an unattributable label; caught right here and booked as
+                // unavailable, because "the service did not apply the class filter" is a
+                // reading we do not have, not a reading of zero.
+                counts = countsForClasses(classes, result.detections, effectiveThresholds);
+                detectorModel = result.model;
+                // The invariant, ASSERTED rather than defaulted. `classes` is built from
+                // these very fields and `countsForClasses` keys its answer on `classes`,
+                // so a lookup below cannot miss — but writing `?? 0` at the read would
+                // turn any future violation into a manufactured measurement: a count of
+                // things in a frame nobody counted, indistinguishable from a genuinely
+                // empty one. That is the single answer this file exists to never
+                // produce, so the impossible case is routed to `unavailable` like every
+                // other way of not having a reading.
+                for (const f of groupFields) {
+                    if (!counts.has(f.className)) {
+                        throw new Error(`detector answer carries no count for '${f.className}' after asking for [${classes.join(', ')}]`);
+                    }
+                }
+            }
+            catch (err) {
+                this.withholdGroup(withheld, groupFields, modelId, classifyDetectorFailure(err), messageOf(err));
+                continue;
+            }
+            // ── ATTRIBUTION: did the model the PARTITION named actually answer? ────
+            //
+            // The service resolves a class against the models RESIDENT ON THIS BOX —
+            // `ClassIndex._owner` gives each class exactly one owner, chosen by
+            // residency and catalogue order — and that owner need not be the one the
+            // registry says declares this field. Overlap is the norm, not an edge
+            // case: `hardhat` is declared by BOTH `ppe_vyra_14cls_v8m` and
+            // `ppe_construction_17cls_v8n`, and `person` by those two plus
+            // `rfdetr_medium`.
+            //
+            // So the failure this whole file is written against has a second door.
+            // With Vyra's artifact never delivered and Construction resident, asking
+            // for `hardhat` does NOT 400 — it succeeds, answered by Construction, and
+            // without this check `hardhat_present` would ship stamped `modelId:
+            // 'ppe_vyra_14cls_v8m'`. A granted-but-not-arrived model would have
+            // produced a value after all, from a different instrument with different
+            // fitted thresholds and a different precision, wearing the absent model's
+            // name.
+            //
+            // A reading from the wrong instrument is NOT a reading. It is withheld,
+            // exactly like the 400 — same promise, same outcome, different door — and
+            // the cause names the substitute so a registry-owner/service-owner
+            // disagreement is diagnosable instead of invisible.
+            //
+            // The wire cannot be asked to prevent this: it carries `classes` and no
+            // model selector, deliberately, because the service is the only component
+            // that knows what is resident. Reading back who answered is the only
+            // check available, and the service guarantees it is answerable — an
+            // unattributed batch is a 500 on its side, never a 200.
+            const answeredBy = detectorModel === null
+                ? []
+                : detectorModel.split(exports.DETECTOR_MODEL_JOIN).map((m) => m.trim()).filter(Boolean);
+            if (!answeredBy.includes(modelId)) {
+                this.withholdGroup(withheld, groupFields, modelId, detectorModel === null ? 'unattributed_answer' : 'answered_by_other_model', detectorModel === null
+                    ? 'the service named no model, so this reading cannot be attributed'
+                    : `asked for ${modelId}'s classes and '${detectorModel}' answered — `
+                        + `the granted model is not the one resident for these classes`);
+                continue;
+            }
+            // ── The ONLY place in this file that writes a value. ───────────────────
+            for (const f of groupFields) {
+                const n = counts.get(f.className);
+                produced.push({
+                    field: f.field,
+                    value: f.kind === 'present' ? n > 0 : n,
+                    modelId,
+                    className: f.className,
+                    minConfidence: effectiveThresholds.get(f.className),
+                    detectorModel,
+                });
+            }
+        }
+        return { produced, withheld };
+    }
+    /**
+     * Every field of one model, withheld together.
+     *
+     * A model that did not answer did not answer for ANY of its fields. Booking
+     * them one at a time would invite a partial group, which is the collapse this
+     * whole file is written against.
+     */
+    withholdGroup(withheld, groupFields, modelId, cause, detail) {
+        for (const f of groupFields) {
+            withheld.push({
+                field: f.field,
+                modelId,
+                reason: exports.PRODUCER_WITHHOLD_REASONS.DETECTOR_UNAVAILABLE,
+                detail: `${cause}: ${detail}`,
+            });
+        }
+    }
+}
+exports.DetectorFieldProducer = DetectorFieldProducer;
+/** Flatten an answer to the `{field: value}` map a payload carries. */
+function toFieldValues(produced) {
+    const out = {};
+    for (const p of produced)
+        out[p.field] = p.value;
+    return out;
+}
+/**
+ * A short, stable cause for the local health surface.
+ *
+ * Same buckets and the same STRUCTURAL derivation as
+ * `DetectorShadowProbe.classifyUnavailable`: a thrown TYPE first, never prose,
+ * and what is left after the three matched shapes IS the envelope class.
+ * `filter_not_applied` is this file's own — it is thrown here, not by the
+ * client, and it is the one cause that means the service answered fine and its
+ * answer still cannot be used.
+ */
+function classifyDetectorFailure(err) {
+    if (!(err instanceof LocalDetectorClient_1.DetectorUnavailableError)) {
+        const message = messageOf(err);
+        if (/did not apply the class filter/i.test(message))
+            return 'filter_not_applied';
+        return /timed out/i.test(message) ? 'timeout' : 'unknown';
+    }
+    const message = err.message;
+    if (/timed out/i.test(message))
+        return 'timeout';
+    if (/HTTP \d{3}/.test(message))
+        return 'http_error';
+    if (/transport failed/i.test(message))
+        return 'transport_failed';
+    return 'bad_envelope';
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=DetectorFieldProducer.js.map