@camstack/addon-decoder-nodeav 1.2.87 → 1.2.88

package/dist/index.js

@@ -7627,6 +7627,157 @@ var CameraSwitchGroupSchema = object({
 	/** Unix ms when the group was composed server-side. */
 	fetchedAt: number()
 });
+/**
+* What the gate decided about a birth, from the CALLER's point of view.
+*
+* Deliberately not `ConfirmationVerdict`: `undecided` is not a birth decision
+* at all — it is a deferral, and the row is written when the deferral ENDS.
+* The third member is the one the gate's own type cannot express, because
+* exhaustion is a property of how long the caller waited.
+*/
+var BirthDecisionVerdictSchema = _enum([
+	"confirmed",
+	"suppressed",
+	"exhausted-fallback"
+]);
+/** One birth decision, as it is kept. */
+var BirthDecisionRecordSchema = object({
+	id: string(),
+	/** Epoch ms the VERDICT was taken (not the birth instant — see `firstSeen`). */
+	at: number().int(),
+	/** The camera. Required: every question here is asked per-camera. */
+	deviceId: number().int(),
+	/**
+	* The track the decision was about. PROVENANCE, not ownership — a suppressed
+	* birth has no track at all, and a confirmed one is expected to age out long
+	* before this row does. Named `sourceTrackId` so the retention model's
+	* ownership derivation (`collection-classification.ts`, which keys on a
+	* column literally called `trackId`) cannot reach it.
+	*/
+	sourceTrackId: string(),
+	/** The candidate's claimed class. The miss rate is asked per class too. */
+	className: string(),
+	verdict: BirthDecisionVerdictSchema,
+	/**
+	* The gate's own `ConfirmationReason` (`confirmed`, `suppressed`,
+	* `native-pass`, `no-crop`, `timeout`, `carried-inconclusive`, …), or `null`
+	* when the gate is DISABLED and every birth is waved through. `null` is not
+	* "unknown": it says the gate took no measurement because it was off, which
+	* is a different population and must never be averaged in with the rest.
+	*/
+	reason: string().nullable(),
+	/** Deferral attempts this birth used. 0 = decided on its first look. */
+	attempts: number().int(),
+	/** Ms from the FIRST undecided attempt to this verdict. 0 = never deferred. */
+	deferredForMs: number().int(),
+	/**
+	* THE COLUMN THE RE-OFFER DEFECT IS COUNTED IN.
+	*
+	* `true` when the frame the verdict was taken on carried no matched
+	* detection for this track — the tracker was coasting a frozen box and the
+	* subject was not observed. The deferred-birth re-offer pulls the candidate
+	* straight out of `result.tracked` without checking, so this is reachable
+	* today; the question is the RATE, per camera, and whether refusing those
+	* frames would have cost real tracks (cross-read against `verdict` and
+	* `decidedByBirthEvidence`).
+	*/
+	decidedOnCoastedFrame: boolean(),
+	/** Were D379 birth-instant pixels in hand when this candidate was submitted? */
+	birthEvidenceAvailable: boolean(),
+	/**
+	* Did those pixels DECIDE it (`cropSource === 'carried'`)? Available and
+	* deciding are different: the carried crop is confirm-only, so a candidate
+	* can hold evidence, be found inconclusive on it, and be decided by a native
+	* crop of a later instant. A coasted decision backed by carried evidence is
+	* a real observation of the birth instant; one without it is not.
+	*/
+	decidedByBirthEvidence: boolean(),
+	/** Best class-compatible crop score, or `null` when nothing compatible was
+	*  found — deliberately not 0, which would be a measurement that never was. */
+	bestScore: number().nullable(),
+	/** The bar this candidate actually faced (the phantom-cell hook may raise it). */
+	appliedMinConfidence: number().nullable(),
+	/**
+	* The track's own `firstSeen` — the candidate's first frame, which is where
+	* the timeline starts. `null` for a suppressed birth, which has no track.
+	*/
+	firstSeen: number().int().nullable(),
+	/**
+	* The device's most recent motion RISING EDGE at the moment of the decision,
+	* or `null` when there is none, it is older than
+	* {@link MAX_BIRTH_LATENCY_PROXY_MS}, or this runner never saw one.
+	*/
+	motionOnsetAt: number().int().nullable(),
+	/**
+	* `firstSeen − motionOnsetAt` — THE OPERATOR'S COMPLAINT, IN MILLISECONDS,
+	* AND THE WEAKEST NUMBER IN THIS ROW. Read the error bars before quoting it.
+	*
+	* **Why motion onset and not something else.** Two other proxies were
+	* considered and rejected:
+	*  - *the recording/pipeline session start*: for a camera on
+	*    `detectionMode: 'always'` the session opens at process start, hours
+	*    before any subject. It measures nothing.
+	*  - *the first detection on the device in this burst*: CIRCULAR. A track's
+	*    `firstSeen` IS the first detection of that object, so for the track that
+	*    OPENS a burst — the only one the operator is complaining about — the two
+	*    are the same instant and the latency is 0 by construction.
+	* Motion onset is the only in-process signal produced by a DIFFERENT
+	* mechanism from the object detector, so it is the only one that can precede
+	* it. It is also already maintained per-device at frame rate on this very
+	* node (`handleMotionAnalysis` / `handleOnboardMotion`), which is what makes
+	* it free — and, decisively, the frame path and the motion path are gated to
+	* the SAME designated post-processing node, so the mirror is never empty for
+	* a camera whose births land here.
+	*
+	* **Error bars, all of them.**
+	*  1. *Motion has no class.* A burst opened by rain, a headlight sweeping a
+	*     wall or a branch, and only later joined by the person, OVERSTATES the
+	*     latency without bound. Mitigated, never removed, by
+	*     {@link BirthDecisionRecord.birthIndexInBurst}: only index 0 is a
+	*     candidate for "this burst is this subject", and even then it is a
+	*     candidate, not a fact.
+	*  2. *The sign is not guaranteed.* The analyzer needs a pixel-count and
+	*     intensity threshold. A subject entering slowly at the far edge of the
+	*     frame can clear the detector's confidence floor BEFORE it clears the
+	*     motion floor, making this negative. Negatives are stored as-is and
+	*     never clamped — clamping would fabricate the distribution's left tail,
+	*     which is the half that says the proxy is unreliable.
+	*  3. *Onboard motion carries firmware latency of unknown, per-model offset*
+	*     (hundreds of ms), plus camera-vs-hub clock skew on top. Numbers are
+	*     therefore comparable WITHIN a camera and not across cameras of
+	*     different motion sources. The motion source is deliberately not copied
+	*     here — it belongs to the addon that owns the device (D224) and this is
+	*     a write on the frame path — so group by `deviceId`, which is how the
+	*     question is always asked anyway.
+	*  4. *Continuous motion.* On a busy scene the burst never closes and the
+	*     onset is minutes old. Bounded by {@link MAX_BIRTH_LATENCY_PROXY_MS};
+	*     past it this is `null`.
+	*  5. *No motion signal at all* — analyzer off, onboard-only camera not
+	*     reporting, or nothing since boot: `null`. Which is the truth about a
+	*     camera nobody has a reference instant for.
+	*
+	* So this is a per-camera DISTRIBUTION over index-0 births, and it is honest
+	* as such. It is not a per-track fact and must never be shown as one.
+	*/
+	birthLatencyMs: number().int().nullable(),
+	/**
+	* How many births this device has already decided since that motion onset.
+	* 0 = the first, i.e. the only index at which the burst plausibly belongs to
+	* this subject. `null` when there is no usable onset.
+	*/
+	birthIndexInBurst: number().int().nullable()
+});
+/** Query input for `listBirthDecisions` — newest first, one camera or all. */
+var BirthDecisionQueryInputSchema = object({
+	/** Restrict to a single camera; omit for every row. */
+	deviceId: number().int().optional(),
+	/** Only decisions at or after this epoch ms. */
+	since: number().int().optional(),
+	/** Restrict to one verdict — the miss rate is read one population at a time. */
+	verdict: BirthDecisionVerdictSchema.optional(),
+	/** Max rows returned, newest-first. */
+	limit: number().int().min(1).max(5e3).optional()
+});
 /** One archived note — the operator's words plus enough context to find what
 *  they were looking at, after the track itself is gone. */
 var ArchivedDebugNoteSchema = object({
@@ -19881,7 +20032,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	deviceId: number(),
 	trackId: string(),
 	flags: TrackFlagsPatchSchema
-}), TrackFlagsSchema, { kind: "mutation" }), method(ArchivedDebugNoteQueryInputSchema, array(ArchivedDebugNoteSchema).readonly(), { kind: "query" }), method(object({}), EventStoreFootprintSchema, {
+}), TrackFlagsSchema, { kind: "mutation" }), method(ArchivedDebugNoteQueryInputSchema, array(ArchivedDebugNoteSchema).readonly(), { kind: "query" }), method(BirthDecisionQueryInputSchema, array(BirthDecisionRecordSchema).readonly(), { kind: "query" }), method(object({}), EventStoreFootprintSchema, {
 	kind: "query",
 	auth: "admin"
 }), method(object({ deviceId: number().int().optional() }), EventMediaKindBreakdownSchema, {
@@ -33285,6 +33436,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listBirthDecisions": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -37077,6 +37234,11 @@ Object.freeze({
 		form: "single",
 		optional: true
 	}],
+	"pipelineAnalytics.listBirthDecisions": [{
+		name: "deviceId",
+		form: "single",
+		optional: true
+	}],
 	"pipelineAnalytics.listEventKinds": [{
 		name: "deviceId",
 		form: "single",

package/dist/index.mjs

@@ -7623,6 +7623,157 @@ var CameraSwitchGroupSchema = object({
 	/** Unix ms when the group was composed server-side. */
 	fetchedAt: number()
 });
+/**
+* What the gate decided about a birth, from the CALLER's point of view.
+*
+* Deliberately not `ConfirmationVerdict`: `undecided` is not a birth decision
+* at all — it is a deferral, and the row is written when the deferral ENDS.
+* The third member is the one the gate's own type cannot express, because
+* exhaustion is a property of how long the caller waited.
+*/
+var BirthDecisionVerdictSchema = _enum([
+	"confirmed",
+	"suppressed",
+	"exhausted-fallback"
+]);
+/** One birth decision, as it is kept. */
+var BirthDecisionRecordSchema = object({
+	id: string(),
+	/** Epoch ms the VERDICT was taken (not the birth instant — see `firstSeen`). */
+	at: number().int(),
+	/** The camera. Required: every question here is asked per-camera. */
+	deviceId: number().int(),
+	/**
+	* The track the decision was about. PROVENANCE, not ownership — a suppressed
+	* birth has no track at all, and a confirmed one is expected to age out long
+	* before this row does. Named `sourceTrackId` so the retention model's
+	* ownership derivation (`collection-classification.ts`, which keys on a
+	* column literally called `trackId`) cannot reach it.
+	*/
+	sourceTrackId: string(),
+	/** The candidate's claimed class. The miss rate is asked per class too. */
+	className: string(),
+	verdict: BirthDecisionVerdictSchema,
+	/**
+	* The gate's own `ConfirmationReason` (`confirmed`, `suppressed`,
+	* `native-pass`, `no-crop`, `timeout`, `carried-inconclusive`, …), or `null`
+	* when the gate is DISABLED and every birth is waved through. `null` is not
+	* "unknown": it says the gate took no measurement because it was off, which
+	* is a different population and must never be averaged in with the rest.
+	*/
+	reason: string().nullable(),
+	/** Deferral attempts this birth used. 0 = decided on its first look. */
+	attempts: number().int(),
+	/** Ms from the FIRST undecided attempt to this verdict. 0 = never deferred. */
+	deferredForMs: number().int(),
+	/**
+	* THE COLUMN THE RE-OFFER DEFECT IS COUNTED IN.
+	*
+	* `true` when the frame the verdict was taken on carried no matched
+	* detection for this track — the tracker was coasting a frozen box and the
+	* subject was not observed. The deferred-birth re-offer pulls the candidate
+	* straight out of `result.tracked` without checking, so this is reachable
+	* today; the question is the RATE, per camera, and whether refusing those
+	* frames would have cost real tracks (cross-read against `verdict` and
+	* `decidedByBirthEvidence`).
+	*/
+	decidedOnCoastedFrame: boolean(),
+	/** Were D379 birth-instant pixels in hand when this candidate was submitted? */
+	birthEvidenceAvailable: boolean(),
+	/**
+	* Did those pixels DECIDE it (`cropSource === 'carried'`)? Available and
+	* deciding are different: the carried crop is confirm-only, so a candidate
+	* can hold evidence, be found inconclusive on it, and be decided by a native
+	* crop of a later instant. A coasted decision backed by carried evidence is
+	* a real observation of the birth instant; one without it is not.
+	*/
+	decidedByBirthEvidence: boolean(),
+	/** Best class-compatible crop score, or `null` when nothing compatible was
+	*  found — deliberately not 0, which would be a measurement that never was. */
+	bestScore: number().nullable(),
+	/** The bar this candidate actually faced (the phantom-cell hook may raise it). */
+	appliedMinConfidence: number().nullable(),
+	/**
+	* The track's own `firstSeen` — the candidate's first frame, which is where
+	* the timeline starts. `null` for a suppressed birth, which has no track.
+	*/
+	firstSeen: number().int().nullable(),
+	/**
+	* The device's most recent motion RISING EDGE at the moment of the decision,
+	* or `null` when there is none, it is older than
+	* {@link MAX_BIRTH_LATENCY_PROXY_MS}, or this runner never saw one.
+	*/
+	motionOnsetAt: number().int().nullable(),
+	/**
+	* `firstSeen − motionOnsetAt` — THE OPERATOR'S COMPLAINT, IN MILLISECONDS,
+	* AND THE WEAKEST NUMBER IN THIS ROW. Read the error bars before quoting it.
+	*
+	* **Why motion onset and not something else.** Two other proxies were
+	* considered and rejected:
+	*  - *the recording/pipeline session start*: for a camera on
+	*    `detectionMode: 'always'` the session opens at process start, hours
+	*    before any subject. It measures nothing.
+	*  - *the first detection on the device in this burst*: CIRCULAR. A track's
+	*    `firstSeen` IS the first detection of that object, so for the track that
+	*    OPENS a burst — the only one the operator is complaining about — the two
+	*    are the same instant and the latency is 0 by construction.
+	* Motion onset is the only in-process signal produced by a DIFFERENT
+	* mechanism from the object detector, so it is the only one that can precede
+	* it. It is also already maintained per-device at frame rate on this very
+	* node (`handleMotionAnalysis` / `handleOnboardMotion`), which is what makes
+	* it free — and, decisively, the frame path and the motion path are gated to
+	* the SAME designated post-processing node, so the mirror is never empty for
+	* a camera whose births land here.
+	*
+	* **Error bars, all of them.**
+	*  1. *Motion has no class.* A burst opened by rain, a headlight sweeping a
+	*     wall or a branch, and only later joined by the person, OVERSTATES the
+	*     latency without bound. Mitigated, never removed, by
+	*     {@link BirthDecisionRecord.birthIndexInBurst}: only index 0 is a
+	*     candidate for "this burst is this subject", and even then it is a
+	*     candidate, not a fact.
+	*  2. *The sign is not guaranteed.* The analyzer needs a pixel-count and
+	*     intensity threshold. A subject entering slowly at the far edge of the
+	*     frame can clear the detector's confidence floor BEFORE it clears the
+	*     motion floor, making this negative. Negatives are stored as-is and
+	*     never clamped — clamping would fabricate the distribution's left tail,
+	*     which is the half that says the proxy is unreliable.
+	*  3. *Onboard motion carries firmware latency of unknown, per-model offset*
+	*     (hundreds of ms), plus camera-vs-hub clock skew on top. Numbers are
+	*     therefore comparable WITHIN a camera and not across cameras of
+	*     different motion sources. The motion source is deliberately not copied
+	*     here — it belongs to the addon that owns the device (D224) and this is
+	*     a write on the frame path — so group by `deviceId`, which is how the
+	*     question is always asked anyway.
+	*  4. *Continuous motion.* On a busy scene the burst never closes and the
+	*     onset is minutes old. Bounded by {@link MAX_BIRTH_LATENCY_PROXY_MS};
+	*     past it this is `null`.
+	*  5. *No motion signal at all* — analyzer off, onboard-only camera not
+	*     reporting, or nothing since boot: `null`. Which is the truth about a
+	*     camera nobody has a reference instant for.
+	*
+	* So this is a per-camera DISTRIBUTION over index-0 births, and it is honest
+	* as such. It is not a per-track fact and must never be shown as one.
+	*/
+	birthLatencyMs: number().int().nullable(),
+	/**
+	* How many births this device has already decided since that motion onset.
+	* 0 = the first, i.e. the only index at which the burst plausibly belongs to
+	* this subject. `null` when there is no usable onset.
+	*/
+	birthIndexInBurst: number().int().nullable()
+});
+/** Query input for `listBirthDecisions` — newest first, one camera or all. */
+var BirthDecisionQueryInputSchema = object({
+	/** Restrict to a single camera; omit for every row. */
+	deviceId: number().int().optional(),
+	/** Only decisions at or after this epoch ms. */
+	since: number().int().optional(),
+	/** Restrict to one verdict — the miss rate is read one population at a time. */
+	verdict: BirthDecisionVerdictSchema.optional(),
+	/** Max rows returned, newest-first. */
+	limit: number().int().min(1).max(5e3).optional()
+});
 /** One archived note — the operator's words plus enough context to find what
 *  they were looking at, after the track itself is gone. */
 var ArchivedDebugNoteSchema = object({
@@ -19877,7 +20028,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	deviceId: number(),
 	trackId: string(),
 	flags: TrackFlagsPatchSchema
-}), TrackFlagsSchema, { kind: "mutation" }), method(ArchivedDebugNoteQueryInputSchema, array(ArchivedDebugNoteSchema).readonly(), { kind: "query" }), method(object({}), EventStoreFootprintSchema, {
+}), TrackFlagsSchema, { kind: "mutation" }), method(ArchivedDebugNoteQueryInputSchema, array(ArchivedDebugNoteSchema).readonly(), { kind: "query" }), method(BirthDecisionQueryInputSchema, array(BirthDecisionRecordSchema).readonly(), { kind: "query" }), method(object({}), EventStoreFootprintSchema, {
 	kind: "query",
 	auth: "admin"
 }), method(object({ deviceId: number().int().optional() }), EventMediaKindBreakdownSchema, {
@@ -33281,6 +33432,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listBirthDecisions": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -37073,6 +37230,11 @@ Object.freeze({
 		form: "single",
 		optional: true
 	}],
+	"pipelineAnalytics.listBirthDecisions": [{
+		name: "deviceId",
+		form: "single",
+		optional: true
+	}],
 	"pipelineAnalytics.listEventKinds": [{
 		name: "deviceId",
 		form: "single",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-decoder-nodeav",
-  "version": "1.2.87",
+  "version": "1.2.88",
   "description": "Standalone in-process node-av decoder addon for CamStack",
   "keywords": [
     "camstack",