@camstack/addon-matter-broker 0.2.85 → 0.2.87

package/dist/addon.js

@@ -7642,6 +7642,186 @@ var CameraSwitchGroupSchema = object({
 	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$2(),
+	/** 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$2(),
+	/** The candidate's claimed class. The miss rate is asked per class too. */
+	className: string$2(),
+	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$2().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({
+	/** Archive row id. Derived from `(sourceTrackId, note)`, so re-archiving the
+	*  same sentence about the same track lands on the row already there. */
+	id: string$2(),
+	/** The operator's own words, verbatim. */
+	note: string$2(),
+	/** The camera. Required — every question here is asked per-camera. */
+	deviceId: number().int(),
+	/** The track the note was written on. PROVENANCE, not ownership: the track
+	*  is expected to be gone, and this row is not a reference to it. */
+	sourceTrackId: string$2(),
+	/** Epoch ms the note was moved here, i.e. when the operator reviewed it. */
+	archivedAt: number().int(),
+	/** The track's `firstSeen`, when the row still knew it; `null` otherwise. */
+	trackStartedAt: number().int().nullable(),
+	/** The track's detector class (`person`, `car`, …); `null` when unknown. */
+	trackClass: string$2().nullable(),
+	/** The track's display label at review time; `null` when it had none. */
+	trackLabel: string$2().nullable()
+});
+/** Query input for `listArchivedDebugNotes` — newest first, one camera or all. */
+var ArchivedDebugNoteQueryInputSchema = object({
+	/** Restrict to a single camera; omit for every row. */
+	deviceId: number().int().optional(),
+	/** Max rows returned, newest-first. */
+	limit: number().int().min(1).max(1e3).optional()
+});
+/**
 * Ops-log — the durable, append-only operations audit shared by the
 * recordings and events management surfaces.
 *
@@ -20170,7 +20350,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	deviceId: number(),
 	trackId: string$2(),
 	flags: TrackFlagsPatchSchema
-}), TrackFlagsSchema, { kind: "mutation" }), 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, {
@@ -37581,6 +37761,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listArchivedDebugNotes": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listBirthDecisions": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -41368,6 +41560,16 @@ Object.freeze({
 		form: "array",
 		optional: true
 	}],
+	"pipelineAnalytics.listArchivedDebugNotes": [{
+		name: "deviceId",
+		form: "single",
+		optional: true
+	}],
+	"pipelineAnalytics.listBirthDecisions": [{
+		name: "deviceId",
+		form: "single",
+		optional: true
+	}],
 	"pipelineAnalytics.listEventKinds": [{
 		name: "deviceId",
 		form: "single",

package/dist/addon.mjs

@@ -7640,6 +7640,186 @@ var CameraSwitchGroupSchema = object({
 	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$2(),
+	/** 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$2(),
+	/** The candidate's claimed class. The miss rate is asked per class too. */
+	className: string$2(),
+	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$2().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({
+	/** Archive row id. Derived from `(sourceTrackId, note)`, so re-archiving the
+	*  same sentence about the same track lands on the row already there. */
+	id: string$2(),
+	/** The operator's own words, verbatim. */
+	note: string$2(),
+	/** The camera. Required — every question here is asked per-camera. */
+	deviceId: number().int(),
+	/** The track the note was written on. PROVENANCE, not ownership: the track
+	*  is expected to be gone, and this row is not a reference to it. */
+	sourceTrackId: string$2(),
+	/** Epoch ms the note was moved here, i.e. when the operator reviewed it. */
+	archivedAt: number().int(),
+	/** The track's `firstSeen`, when the row still knew it; `null` otherwise. */
+	trackStartedAt: number().int().nullable(),
+	/** The track's detector class (`person`, `car`, …); `null` when unknown. */
+	trackClass: string$2().nullable(),
+	/** The track's display label at review time; `null` when it had none. */
+	trackLabel: string$2().nullable()
+});
+/** Query input for `listArchivedDebugNotes` — newest first, one camera or all. */
+var ArchivedDebugNoteQueryInputSchema = object({
+	/** Restrict to a single camera; omit for every row. */
+	deviceId: number().int().optional(),
+	/** Max rows returned, newest-first. */
+	limit: number().int().min(1).max(1e3).optional()
+});
+/**
 * Ops-log — the durable, append-only operations audit shared by the
 * recordings and events management surfaces.
 *
@@ -20168,7 +20348,7 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	deviceId: number(),
 	trackId: string$2(),
 	flags: TrackFlagsPatchSchema
-}), TrackFlagsSchema, { kind: "mutation" }), 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, {
@@ -37579,6 +37759,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listArchivedDebugNotes": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listBirthDecisions": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -41366,6 +41558,16 @@ Object.freeze({
 		form: "array",
 		optional: true
 	}],
+	"pipelineAnalytics.listArchivedDebugNotes": [{
+		name: "deviceId",
+		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-matter-broker",
-  "version": "0.2.85",
+  "version": "0.2.87",
   "description": "Matter broker addon for CamStack — owns a Matter fabric (commissioning + the long-lived controller) via the matter.js controller and brokers commissioned Matter nodes into CamStack",
   "keywords": [
     "camstack",