@camstack/addon-decoder-nodeav 1.2.37 → 1.2.39

package/dist/index.js

@@ -13333,6 +13333,114 @@ method(LogEntrySchema, _void(), { kind: "mutation" }), method(object({
 	limit: number().optional(),
 	tags: record(string(), string()).optional()
 }), array(LogEntrySchema).readonly());
+/**
+* `failure-contribution` — the capability an addon reports its OWN losses
+* through, per camera, with the denominator attached. It stores nothing.
+*
+* ## The twin of `load-contribution`, and why it is a twin and not a field
+*
+* `load-contribution` answers *what did this camera COST*. This answers *what
+* did this camera LOSE*. The reporting discipline is identical and deliberately
+* copied: the contributor reports what it already knows, hub-main adds only
+* `addonId`, nothing needs global knowledge, and there is no central list for
+* somebody to forget to edit.
+*
+* They are not merged, because their invariants are opposites:
+*
+*  - a `load-contribution` measurement is **absent, never zero** — a zero would
+*    claim a camera cost nothing, which is a measurement nobody made;
+*  - a `failure-contribution` zero is the **most valuable value on the
+*    surface** — `attempts: 400, succeeded: 400` is the proof a fix landed,
+*    and it is exactly what an absent entry cannot say.
+*
+* Putting a loss counter on a cost entry would also break the reconciliation
+* that gives `load-contribution` its point: contributions are subtracted from
+* `metrics.node-processes-snapshot` to find processes nobody claims. A failure
+* has no process.
+*
+* ## Why not a log line, since the counters already exist
+*
+* Several of these paths already counted themselves — `CaptureScheduler`'s
+* per-device window, `KeyFrameCaptureLog`, `bumpCropMetric`. Every one of them
+* ends in a log line, and a log line is the thing the operator asked to stop
+* needing: *"possiamo armare questi errori intanto? Così al prossimo giro
+* ricontrolliamo tutti questi punti"*. Reading them meant grepping Loki and
+* hand-correlating timestamps, which is how a 22% thumbnail gap and a 3-hour
+* media blackout were both diagnosed. The counters stay; this is where they can
+* be READ.
+*
+* ## The rate is served with its denominator or not at all
+*
+* Every entry carries `attempts` and `succeeded`. A miss count alone is
+* unreadable: on 2026-08-28 the enrichment-crop miss count read as "35x worse
+* than yesterday" and was **flat across twelve hours** once divided by the
+* successes on the same path. A surface that publishes only the numerator
+* reproduces that mistake on every read.
+*
+* ## Shape
+*
+* Copied from `load-contribution.cap.ts` (`mode: 'collection'`,
+* `internal: true`, `mount: { kind: 'skip' }`): no tRPC route of its own and no
+* generated hooks, while `addons.listCapabilityProviders` still enumerates it
+* and the hub's `CapabilityRegistry` still holds an RPC proxy per provider — so
+* a forked runner's entries reach hub-main over transport that already exists.
+* No new UDS message, no second registry (D3). The operator reads the assembled
+* result through `system.getFailureContributions`.
+*/
+var FailureReasonCountSchema = object({
+	/**
+	* Why the attempt did not land, in the contributor's own vocabulary —
+	* `worker-lease-gone`, `queue-overflow`, `timeout`, `empty-read`. The same
+	* strings that already appear in this repo's logs and, where one exists, the
+	* same string the per-track `previewMissReason` records (D276): a second
+	* vocabulary for the same loss would make the row and the counter
+	* un-joinable.
+	*/
+	reason: string(),
+	count: number().int().nonnegative()
+});
+var FailureContributionSchema = object({
+	/**
+	* The failing path — `enrichment-crop`, `inference`, `plate-ocr`,
+	* `person-over-vehicle`. Free text, for the reason `load-contribution` keeps
+	* `unit` free: the families are owned by different addons and a shared enum
+	* is a central list that rots invisibly.
+	*/
+	family: string(),
+	/**
+	* The NUMERIC device id — the same value every log line carries as
+	* `tags.deviceId`. Never nullable and never absent: a contributor that
+	* cannot name the camera must not emit the entry, because a fleet total
+	* cannot answer the only question anybody asks of this surface.
+	*/
+	deviceId: number().int().positive(),
+	/**
+	* A second dimension inside the family: the model / step id for an inference
+	* timeout, so "which camera AND which model" is one read. Absent when the
+	* family has a single variant.
+	*/
+	variant: string().optional(),
+	/**
+	* Epoch ms this counter started — the INCARNATION MARKER. A consumer
+	* differencing two reads must drop the interval when it changes, because the
+	* counter restarted from zero in a respawned runner. Same discipline as
+	* `LoadContribution.startedAtMs`.
+	*/
+	sinceMs: number(),
+	/** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
+	atMs: number(),
+	/**
+	* THE DENOMINATOR — every attempt on this path for this camera in the
+	* window. A failure count published without it is the mistake this schema
+	* exists to make impossible.
+	*/
+	attempts: number().int().nonnegative(),
+	/** Attempts that landed. `attempts - succeeded` is the loss. */
+	succeeded: number().int().nonnegative(),
+	/** The loss, partitioned. Sums to `attempts - succeeded`. */
+	reasons: array(FailureReasonCountSchema).readonly()
+});
+method(_void(), array(FailureContributionSchema).readonly());
 var LoadContributionSchema = object({
 	role: _enum([
 		"decode",
@@ -17845,6 +17953,20 @@ var TrackSchema = object({
 	* `=== true` and render nothing otherwise — never infer "no rider".
 	*/
 	hasRider: boolean().optional(),
+	/**
+	* WHY this track ended without a NATIVE best-shot tile
+	* ([D276](../decisions/adr-0276-a-stand-in-tile-is-provisional-and-a-close-says-why.md)) —
+	* a composed token line (`no-key-frame capture=keyframe:native-missx4`,
+	* `derive-returned-null tile=standin`, …) written at close and CLEARED by
+	* the late-keyFrame upgrade when a native tile lands after all. The
+	* operator-facing answer to "perché manca l'immagine?" on a track whose
+	* tile is a face/plate stand-in, a raster crop, or an icon.
+	*
+	* **Absent ≠ "missed silently"**: a row written before the column, a hub
+	* that predates the field, and every track whose tile landed native all
+	* omit it. Render nothing when absent.
+	*/
+	previewMissReason: string().optional(),
 	...TrackFlagFields,
 	...TrackRetrainFields
 });
@@ -27071,6 +27193,13 @@ var LoggingSettingsPatchSchema = object({
 * anyone but its owner.
 */
 var ReportedLoadContributionSchema = LoadContributionSchema.extend({ addonId: string() });
+/**
+* One per-camera failure counter, plus WHO reported it.
+*
+* Same rule as {@link ReportedLoadContributionSchema}: `addonId` is stamped by
+* the hub as it enumerates providers, never by the contributor.
+*/
+var ReportedFailureContributionSchema = FailureContributionSchema.extend({ addonId: string() });
 var GetLoggingSettingsInputSchema = object({
 	scopeNodeId: string().optional(),
 	/**
@@ -27129,7 +27258,7 @@ method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), met
 }), method(_void(), SiteLocationStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
+}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(_void(), array(ReportedFailureContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
 	kind: "mutation",
 	auth: "admin"
 });
@@ -29711,6 +29840,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"failureContribution.list": {
+		capName: "failure-contribution",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"fanControl.setDirection": {
 		capName: "fan-control",
 		capScope: "device",
@@ -33017,6 +33152,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getFailureContributions": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getLoadContributions": {
 		capName: "system",
 		capScope: "system",
@@ -37249,7 +37390,19 @@ function resolveAudioCodecAlias(codec) {
 /**
 * Supported codec matrix. `aac_latm` / `mpeg4-generic` are decode-only (they
 * exist only as camera-side inbound streams; the intercom back-channel encodes
-* plain `aac`). Kept byte-for-byte in step with the ffmpeg addon's catalogue.
+* plain `aac`). Kept byte-for-byte in step with the ffmpeg addon's catalogue —
+* `scripts/check-audio-codec-catalog-parity.ts` refuses a commit that drifts
+* one without the other.
+*
+* `pcm_s16le` / `pcm_f32le` are LINEAR PCM, and they are here for exactly one
+* reason: a `{pcm_s16le, 22050 → 8000, s16le}` DECODE session is a pure
+* libswresample rate conversion, which is what an intercom provider needs when
+* a HomeKit / Alexa / TTS caller pushes raw PCM at a rate the camera does not
+* speak. Without them the provider had nothing to call and dropped the frame
+* (D281). They are ENCODE-capable too so the pairing stays symmetric: an
+* encode session whose codec is linear PCM is the same swr pass with the
+* codec stage as a no-op, and a half-populated matrix is how the two backends
+* come to disagree about what `canHandle` means.
 */
 var CODEC_CATALOG = [
 	{
@@ -37264,6 +37417,18 @@ var CODEC_CATALOG = [
 		canEncode: true,
 		label: "PCM A-law (G.711)"
 	},
+	{
+		codec: "pcm_s16le",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM signed 16-bit LE"
+	},
+	{
+		codec: "pcm_f32le",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM float 32-bit LE"
+	},
 	{
 		codec: "g722",
 		canDecode: true,
@@ -37319,6 +37484,8 @@ function resolveCodecKey(codec) {
 		case "opus": return "opus";
 		case "pcm_alaw": return "pcm_alaw";
 		case "pcm_mulaw": return "pcm_mulaw";
+		case "pcm_s16le": return "pcm_s16le";
+		case "pcm_f32le": return "pcm_f32le";
 		case "g722": return "g722";
 		default: return null;
 	}
@@ -37328,7 +37495,9 @@ function resolveCodecKey(codec) {
 /**
 * Resolve a codec name to its branded libav `AVCodecID` using the real
 * constants. Returns `null` for names outside this addon's matrix. G.722 maps
-* to `AV_CODEC_ID_ADPCM_G722` (there is no plain `AV_CODEC_ID_G722`).
+* to `AV_CODEC_ID_ADPCM_G722` (there is no plain `AV_CODEC_ID_G722`); linear
+* PCM has no naming oddity — `AV_CODEC_ID_PCM_S16LE` / `AV_CODEC_ID_PCM_F32LE`
+* exist on node-av's constants object under exactly those names.
 */
 function resolveAvCodecId(codec, consts) {
 	switch (resolveCodecKey(codec)) {
@@ -37337,6 +37506,8 @@ function resolveAvCodecId(codec, consts) {
 		case "opus": return consts.AV_CODEC_ID_OPUS;
 		case "pcm_alaw": return consts.AV_CODEC_ID_PCM_ALAW;
 		case "pcm_mulaw": return consts.AV_CODEC_ID_PCM_MULAW;
+		case "pcm_s16le": return consts.AV_CODEC_ID_PCM_S16LE;
+		case "pcm_f32le": return consts.AV_CODEC_ID_PCM_F32LE;
 		case "g722": return consts.AV_CODEC_ID_ADPCM_G722;
 		case null: return null;
 	}

package/dist/index.mjs

@@ -13329,6 +13329,114 @@ method(LogEntrySchema, _void(), { kind: "mutation" }), method(object({
 	limit: number().optional(),
 	tags: record(string(), string()).optional()
 }), array(LogEntrySchema).readonly());
+/**
+* `failure-contribution` — the capability an addon reports its OWN losses
+* through, per camera, with the denominator attached. It stores nothing.
+*
+* ## The twin of `load-contribution`, and why it is a twin and not a field
+*
+* `load-contribution` answers *what did this camera COST*. This answers *what
+* did this camera LOSE*. The reporting discipline is identical and deliberately
+* copied: the contributor reports what it already knows, hub-main adds only
+* `addonId`, nothing needs global knowledge, and there is no central list for
+* somebody to forget to edit.
+*
+* They are not merged, because their invariants are opposites:
+*
+*  - a `load-contribution` measurement is **absent, never zero** — a zero would
+*    claim a camera cost nothing, which is a measurement nobody made;
+*  - a `failure-contribution` zero is the **most valuable value on the
+*    surface** — `attempts: 400, succeeded: 400` is the proof a fix landed,
+*    and it is exactly what an absent entry cannot say.
+*
+* Putting a loss counter on a cost entry would also break the reconciliation
+* that gives `load-contribution` its point: contributions are subtracted from
+* `metrics.node-processes-snapshot` to find processes nobody claims. A failure
+* has no process.
+*
+* ## Why not a log line, since the counters already exist
+*
+* Several of these paths already counted themselves — `CaptureScheduler`'s
+* per-device window, `KeyFrameCaptureLog`, `bumpCropMetric`. Every one of them
+* ends in a log line, and a log line is the thing the operator asked to stop
+* needing: *"possiamo armare questi errori intanto? Così al prossimo giro
+* ricontrolliamo tutti questi punti"*. Reading them meant grepping Loki and
+* hand-correlating timestamps, which is how a 22% thumbnail gap and a 3-hour
+* media blackout were both diagnosed. The counters stay; this is where they can
+* be READ.
+*
+* ## The rate is served with its denominator or not at all
+*
+* Every entry carries `attempts` and `succeeded`. A miss count alone is
+* unreadable: on 2026-08-28 the enrichment-crop miss count read as "35x worse
+* than yesterday" and was **flat across twelve hours** once divided by the
+* successes on the same path. A surface that publishes only the numerator
+* reproduces that mistake on every read.
+*
+* ## Shape
+*
+* Copied from `load-contribution.cap.ts` (`mode: 'collection'`,
+* `internal: true`, `mount: { kind: 'skip' }`): no tRPC route of its own and no
+* generated hooks, while `addons.listCapabilityProviders` still enumerates it
+* and the hub's `CapabilityRegistry` still holds an RPC proxy per provider — so
+* a forked runner's entries reach hub-main over transport that already exists.
+* No new UDS message, no second registry (D3). The operator reads the assembled
+* result through `system.getFailureContributions`.
+*/
+var FailureReasonCountSchema = object({
+	/**
+	* Why the attempt did not land, in the contributor's own vocabulary —
+	* `worker-lease-gone`, `queue-overflow`, `timeout`, `empty-read`. The same
+	* strings that already appear in this repo's logs and, where one exists, the
+	* same string the per-track `previewMissReason` records (D276): a second
+	* vocabulary for the same loss would make the row and the counter
+	* un-joinable.
+	*/
+	reason: string(),
+	count: number().int().nonnegative()
+});
+var FailureContributionSchema = object({
+	/**
+	* The failing path — `enrichment-crop`, `inference`, `plate-ocr`,
+	* `person-over-vehicle`. Free text, for the reason `load-contribution` keeps
+	* `unit` free: the families are owned by different addons and a shared enum
+	* is a central list that rots invisibly.
+	*/
+	family: string(),
+	/**
+	* The NUMERIC device id — the same value every log line carries as
+	* `tags.deviceId`. Never nullable and never absent: a contributor that
+	* cannot name the camera must not emit the entry, because a fleet total
+	* cannot answer the only question anybody asks of this surface.
+	*/
+	deviceId: number().int().positive(),
+	/**
+	* A second dimension inside the family: the model / step id for an inference
+	* timeout, so "which camera AND which model" is one read. Absent when the
+	* family has a single variant.
+	*/
+	variant: string().optional(),
+	/**
+	* Epoch ms this counter started — the INCARNATION MARKER. A consumer
+	* differencing two reads must drop the interval when it changes, because the
+	* counter restarted from zero in a respawned runner. Same discipline as
+	* `LoadContribution.startedAtMs`.
+	*/
+	sinceMs: number(),
+	/** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
+	atMs: number(),
+	/**
+	* THE DENOMINATOR — every attempt on this path for this camera in the
+	* window. A failure count published without it is the mistake this schema
+	* exists to make impossible.
+	*/
+	attempts: number().int().nonnegative(),
+	/** Attempts that landed. `attempts - succeeded` is the loss. */
+	succeeded: number().int().nonnegative(),
+	/** The loss, partitioned. Sums to `attempts - succeeded`. */
+	reasons: array(FailureReasonCountSchema).readonly()
+});
+method(_void(), array(FailureContributionSchema).readonly());
 var LoadContributionSchema = object({
 	role: _enum([
 		"decode",
@@ -17841,6 +17949,20 @@ var TrackSchema = object({
 	* `=== true` and render nothing otherwise — never infer "no rider".
 	*/
 	hasRider: boolean().optional(),
+	/**
+	* WHY this track ended without a NATIVE best-shot tile
+	* ([D276](../decisions/adr-0276-a-stand-in-tile-is-provisional-and-a-close-says-why.md)) —
+	* a composed token line (`no-key-frame capture=keyframe:native-missx4`,
+	* `derive-returned-null tile=standin`, …) written at close and CLEARED by
+	* the late-keyFrame upgrade when a native tile lands after all. The
+	* operator-facing answer to "perché manca l'immagine?" on a track whose
+	* tile is a face/plate stand-in, a raster crop, or an icon.
+	*
+	* **Absent ≠ "missed silently"**: a row written before the column, a hub
+	* that predates the field, and every track whose tile landed native all
+	* omit it. Render nothing when absent.
+	*/
+	previewMissReason: string().optional(),
 	...TrackFlagFields,
 	...TrackRetrainFields
 });
@@ -27067,6 +27189,13 @@ var LoggingSettingsPatchSchema = object({
 * anyone but its owner.
 */
 var ReportedLoadContributionSchema = LoadContributionSchema.extend({ addonId: string() });
+/**
+* One per-camera failure counter, plus WHO reported it.
+*
+* Same rule as {@link ReportedLoadContributionSchema}: `addonId` is stamped by
+* the hub as it enumerates providers, never by the contributor.
+*/
+var ReportedFailureContributionSchema = FailureContributionSchema.extend({ addonId: string() });
 var GetLoggingSettingsInputSchema = object({
 	scopeNodeId: string().optional(),
 	/**
@@ -27125,7 +27254,7 @@ method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), met
 }), method(_void(), SiteLocationStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
+}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(_void(), array(ReportedFailureContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
 	kind: "mutation",
 	auth: "admin"
 });
@@ -29707,6 +29836,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"failureContribution.list": {
+		capName: "failure-contribution",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"fanControl.setDirection": {
 		capName: "fan-control",
 		capScope: "device",
@@ -33013,6 +33148,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getFailureContributions": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getLoadContributions": {
 		capName: "system",
 		capScope: "system",
@@ -37245,7 +37386,19 @@ function resolveAudioCodecAlias(codec) {
 /**
 * Supported codec matrix. `aac_latm` / `mpeg4-generic` are decode-only (they
 * exist only as camera-side inbound streams; the intercom back-channel encodes
-* plain `aac`). Kept byte-for-byte in step with the ffmpeg addon's catalogue.
+* plain `aac`). Kept byte-for-byte in step with the ffmpeg addon's catalogue —
+* `scripts/check-audio-codec-catalog-parity.ts` refuses a commit that drifts
+* one without the other.
+*
+* `pcm_s16le` / `pcm_f32le` are LINEAR PCM, and they are here for exactly one
+* reason: a `{pcm_s16le, 22050 → 8000, s16le}` DECODE session is a pure
+* libswresample rate conversion, which is what an intercom provider needs when
+* a HomeKit / Alexa / TTS caller pushes raw PCM at a rate the camera does not
+* speak. Without them the provider had nothing to call and dropped the frame
+* (D281). They are ENCODE-capable too so the pairing stays symmetric: an
+* encode session whose codec is linear PCM is the same swr pass with the
+* codec stage as a no-op, and a half-populated matrix is how the two backends
+* come to disagree about what `canHandle` means.
 */
 var CODEC_CATALOG = [
 	{
@@ -37260,6 +37413,18 @@ var CODEC_CATALOG = [
 		canEncode: true,
 		label: "PCM A-law (G.711)"
 	},
+	{
+		codec: "pcm_s16le",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM signed 16-bit LE"
+	},
+	{
+		codec: "pcm_f32le",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM float 32-bit LE"
+	},
 	{
 		codec: "g722",
 		canDecode: true,
@@ -37315,6 +37480,8 @@ function resolveCodecKey(codec) {
 		case "opus": return "opus";
 		case "pcm_alaw": return "pcm_alaw";
 		case "pcm_mulaw": return "pcm_mulaw";
+		case "pcm_s16le": return "pcm_s16le";
+		case "pcm_f32le": return "pcm_f32le";
 		case "g722": return "g722";
 		default: return null;
 	}
@@ -37324,7 +37491,9 @@ function resolveCodecKey(codec) {
 /**
 * Resolve a codec name to its branded libav `AVCodecID` using the real
 * constants. Returns `null` for names outside this addon's matrix. G.722 maps
-* to `AV_CODEC_ID_ADPCM_G722` (there is no plain `AV_CODEC_ID_G722`).
+* to `AV_CODEC_ID_ADPCM_G722` (there is no plain `AV_CODEC_ID_G722`); linear
+* PCM has no naming oddity — `AV_CODEC_ID_PCM_S16LE` / `AV_CODEC_ID_PCM_F32LE`
+* exist on node-av's constants object under exactly those names.
 */
 function resolveAvCodecId(codec, consts) {
 	switch (resolveCodecKey(codec)) {
@@ -37333,6 +37502,8 @@ function resolveAvCodecId(codec, consts) {
 		case "opus": return consts.AV_CODEC_ID_OPUS;
 		case "pcm_alaw": return consts.AV_CODEC_ID_PCM_ALAW;
 		case "pcm_mulaw": return consts.AV_CODEC_ID_PCM_MULAW;
+		case "pcm_s16le": return consts.AV_CODEC_ID_PCM_S16LE;
+		case "pcm_f32le": return consts.AV_CODEC_ID_PCM_F32LE;
 		case "g722": return consts.AV_CODEC_ID_ADPCM_G722;
 		case null: return null;
 	}

package/package.json

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