@camstack/types 1.2.119 → 1.2.120

package/dist/index.js

@@ -2906,6 +2906,190 @@ function reducePoints(points, bucketMs, origin) {
 	return [...buckets.values()].toSorted((a, b) => a.atMs - b.atMs);
 }
 //#endregion
+//#region src/metrics/failure-counters.ts
+/**
+* `FailureCounters` — the per-camera counter every "how often does this camera
+* lose work, and why" question is answered from.
+*
+* ## Why a primitive and not four counters
+*
+* Four open failure modes were being triaged on 2026-08-28 and every one of
+* them was measured the same way: grep a log line, count it, and then guess at
+* the denominator. The guess is the defect. `enrichment crop native miss` read
+* as "35x worse than yesterday" and turned out to be **flat all day** the
+* moment it was divided by the successes on the same path — 0.25 misses per
+* landed capture, 0.08–0.33 across twelve hours, no trend. The count moved
+* because the traffic moved.
+*
+* So the unit here is not a counter. It is a **ratio with its denominator
+* attached**: {@link FailureCounterSample.attempts} is incremented on every
+* try, {@link FailureCounterSample.succeeded} on the ones that landed, and the
+* reasons partition the rest. A consumer can always divide; it can never
+* un-divide a bare count.
+*
+* ## Per camera, always
+*
+* The key is the numeric `deviceId` — the same value every log line in this
+* repo carries as `tags.deviceId`. There is no fleet-total mode and no
+* device-less bucket, because the question is always "why is 617 worse than
+* 615?" and a fleet total cannot answer it. A caller that cannot name the
+* camera must not note anything: an unnamed per-camera count is
+* indistinguishable from a shared one, which is how one camera's failures
+* quietly become everybody's.
+*
+* ## Cumulative, never drained
+*
+* A read NEVER resets anything. `load-contribution.cap.ts` already argued this
+* for CPU seconds and the argument carries over verbatim: *"a rate needs a
+* window, a window needs a sampler, and a new per-node sampler is the defect
+* half of `docs/architecture/load-ledger.md` documents. A counter can be
+* differenced by whoever already keeps a history; a rate cannot be
+* un-averaged."* A draining read has a second failure this surface cannot
+* afford — two consumers polling it would each destroy half of the other's
+* numbers, silently.
+*
+* {@link FailureCounterSample.sinceMs} is the incarnation marker: it is when
+* this counter started, and a consumer differencing two reads must drop the
+* interval when it changes, because the counter restarted from zero in a new
+* process.
+*
+* ## Bounded, and the bound is the point
+*
+* This lives in the memory of a process that is already the subject of an RSS
+* budget, so both dimensions are capped: {@link MAX_KEYS} counters and
+* {@link MAX_REASONS_PER_KEY} distinct reasons within one. Past the reason cap
+* the counts are folded into {@link OVERFLOW_REASON} rather than dropped —
+* losing them would make `attempts - succeeded` stop equalling the reason
+* total, and the ratio the whole surface exists to publish would quietly stop
+* adding up. Past the key cap a new key is refused and
+* {@link FailureCounters.keysRefused} says so, so the omission is visible
+* instead of silent.
+*
+* ## No timers, no IO, no logging
+*
+* Pure. It is read on whatever beat the caller already has. A telemetry
+* primitive that schedules its own work is a second sampler, and this repo has
+* paid for one of those already (`docs/architecture/load-ledger.md`).
+*/
+/** Distinct reason strings kept per counter before folding. */
+var MAX_REASONS_PER_KEY = 16;
+/**
+* Distinct (device, family, variant) counters one instance will hold.
+*
+* A large fleet x the handful of families any single addon reports, with
+* slack. At ~200 B per counter this is a ~100 KB ceiling on a process that
+* already declares an RSS budget in the gigabytes.
+*/
+var MAX_KEYS = 1024;
+/**
+* Where reasons past {@link MAX_REASONS_PER_KEY} go.
+*
+* They are FOLDED, never dropped: `attempts - succeeded` must always equal the
+* sum of the reason counts, or the ratio stops adding up.
+*/
+var OVERFLOW_REASON = "other";
+/** `deviceId` + `family` + optional `variant`, flattened into the map key. */
+function counterKey(deviceId, family, variant) {
+	return variant === void 0 ? `${deviceId}${family}` : `${deviceId}${family}${variant}`;
+}
+/**
+* A bounded set of per-camera, cumulative failure counters.
+*
+* One instance per contributing subsystem. `note` is O(1) and allocation-free
+* on the steady path; `snapshot` reads without mutating anything.
+*/
+var FailureCounters = class {
+	maxKeys;
+	maxReasons;
+	counters = /* @__PURE__ */ new Map();
+	refused = 0;
+	constructor(maxKeys = MAX_KEYS, maxReasons = 16) {
+		this.maxKeys = maxKeys;
+		this.maxReasons = maxReasons;
+	}
+	/**
+	* Counters refused because {@link MAX_KEYS} was already held.
+	*
+	* Cumulative for the life of the instance: a bound that bit is a fact about
+	* the deployment, and a surface that hid it would under-report a fleet
+	* precisely when the fleet got large enough to matter.
+	*/
+	get keysRefused() {
+		return this.refused;
+	}
+	/** Counters currently held. */
+	get size() {
+		return this.counters.size;
+	}
+	/**
+	* Fold one observation in.
+	*
+	* A non-positive or non-integer `deviceId` is REFUSED rather than bucketed:
+	* see the module docblock — an entry that cannot name its camera is worse
+	* than no entry.
+	*/
+	note(observation, nowMs) {
+		if (!Number.isInteger(observation.deviceId) || observation.deviceId <= 0) return;
+		const key = counterKey(observation.deviceId, observation.family, observation.variant);
+		let counter = this.counters.get(key);
+		if (counter === void 0) {
+			if (this.counters.size >= this.maxKeys) {
+				this.refused += 1;
+				return;
+			}
+			counter = {
+				deviceId: observation.deviceId,
+				family: observation.family,
+				variant: observation.variant,
+				sinceMs: nowMs,
+				attempts: 0,
+				succeeded: 0,
+				reasons: /* @__PURE__ */ new Map()
+			};
+			this.counters.set(key, counter);
+		}
+		counter.attempts += 1;
+		if (observation.reason === void 0) {
+			counter.succeeded += 1;
+			return;
+		}
+		const reason = counter.reasons.has(observation.reason) || counter.reasons.size < this.maxReasons ? observation.reason : OVERFLOW_REASON;
+		counter.reasons.set(reason, (counter.reasons.get(reason) ?? 0) + 1);
+	}
+	/** Read every counter. Never mutates — see the module docblock. */
+	snapshot(nowMs) {
+		const out = [];
+		for (const counter of this.counters.values()) out.push({
+			deviceId: counter.deviceId,
+			family: counter.family,
+			...counter.variant !== void 0 ? { variant: counter.variant } : {},
+			sinceMs: counter.sinceMs,
+			atMs: nowMs,
+			attempts: counter.attempts,
+			succeeded: counter.succeeded,
+			reasons: [...counter.reasons.entries()].map(([reason, count]) => ({
+				reason,
+				count
+			})).toSorted((a, b) => b.count - a.count)
+		});
+		return out;
+	}
+	/** Drop everything (host disposal). */
+	clear() {
+		this.counters.clear();
+	}
+};
+/**
+* Losses per attempt, as a ratio — the number the operator actually reads.
+*
+* `null` when there were no attempts: a camera nobody asked anything of has no
+* failure rate, and reporting 0 would say it was perfect.
+*/
+function failureRate(sample) {
+	if (sample.attempts <= 0) return null;
+	return (sample.attempts - sample.succeeded) / sample.attempts;
+}
+//#endregion
 //#region src/types/model-variant-groups.ts
 var FORMAT_KEYS = [
 	"onnx",
@@ -11149,6 +11333,135 @@ var logDestinationCapability = {
 	mount: { kind: "skip" }
 };
 //#endregion
+//#region src/capabilities/failure-contribution.cap.ts
+/**
+* `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 = zod.z.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: zod.z.string(),
+	count: zod.z.number().int().nonnegative()
+});
+var FailureContributionSchema = zod.z.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: zod.z.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: zod.z.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: zod.z.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: zod.z.number(),
+	/** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
+	atMs: zod.z.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: zod.z.number().int().nonnegative(),
+	/** Attempts that landed. `attempts - succeeded` is the loss. */
+	succeeded: zod.z.number().int().nonnegative(),
+	/** The loss, partitioned. Sums to `attempts - succeeded`. */
+	reasons: zod.z.array(FailureReasonCountSchema).readonly()
+});
+var failureContributionCapability = {
+	name: "failure-contribution",
+	scope: "system",
+	mode: "collection",
+	internal: true,
+	methods: { 
+	/**
+	* This addon's per-camera failure counters, read live from bounded in-RAM
+	* state it already keeps. Inert: no persistence, no sampling, no timer.
+	*
+	* READING NEVER RESETS. The counters are CUMULATIVE since `sinceMs`, and a
+	* consumer that wants a rate differences two reads. A draining read would
+	* make two operators with the page open each destroy half of the other's
+	* numbers, and `load-contribution` already settled the same question the
+	* same way for `cpuSeconds`.
+	*/
+list: require_sleep.method(zod.z.void(), zod.z.array(FailureContributionSchema).readonly()) },
+	/** In-process only — enumerated through `addons.listCapabilityProviders`. */
+	mount: { kind: "skip" }
+};
+//#endregion
 //#region src/capabilities/load-contribution.cap.ts
 /**
 * `load-contribution` — the capability an addon reports its OWN cost through,
@@ -17295,6 +17608,20 @@ var TrackSchema = zod.z.object({
 	* `=== true` and render nothing otherwise — never infer "no rider".
 	*/
 	hasRider: zod.z.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: zod.z.string().optional(),
 	...TrackFlagFields,
 	...TrackRetrainFields
 });
@@ -31829,6 +32156,13 @@ var LoggingSettingsPatchSchema = zod.z.object({
 * anyone but its owner.
 */
 var ReportedLoadContributionSchema = LoadContributionSchema.extend({ addonId: zod.z.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: zod.z.string() });
 var GetLoggingSettingsInputSchema = zod.z.object({
 	scopeNodeId: zod.z.string().optional(),
 	/**
@@ -31947,6 +32281,28 @@ var systemCapability = {
 		*/
 		getLoadContributions: require_sleep.method(zod.z.void(), zod.z.array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }),
 		/**
+		* Every `failure-contribution` an addon on this cluster reports — per
+		* camera, per reason, **with the denominator attached**.
+		*
+		* This is the surface the operator asked for on 2026-08-28 (*"possiamo
+		* armare questi errori intanto? Così al prossimo giro ricontrolliamo tutti
+		* questi punti"*). Before it, four live failure modes could only be counted
+		* by grepping Loki and hand-correlating timestamps, which is exactly how a
+		* 22% thumbnail gap and a 3-hour media blackout were diagnosed — twice.
+		*
+		* Read it as a RATIO, never as a count. `attempts` is on every entry
+		* because the count on its own lies: `enrichment crop native miss` read as
+		* "35x worse than yesterday" and was flat across twelve hours once divided
+		* by the successes on the same path.
+		*
+		* The counters are CUMULATIVE since each entry's `sinceMs`. Reading does
+		* not reset them, and `sinceMs` changing means the reporting runner
+		* respawned — a consumer differencing two reads drops that interval.
+		*
+		* Admin-only: the rows name cameras and the paths that fail on them.
+		*/
+		getFailureContributions: require_sleep.method(zod.z.void(), zod.z.array(ReportedFailureContributionSchema).readonly(), { auth: "admin" }),
+		/**
 		* The logging settings document — levels and armed diagnostics — resolved
 		* for `nodeId`, or for the cluster when `nodeId` is absent.
 		*
@@ -36281,6 +36637,7 @@ var CAPABILITY_NAMES = {
 	eventEmitter: "event-emitter",
 	events: "events",
 	faceGallery: "face-gallery",
+	failureContribution: "failure-contribution",
 	fanControl: "fan-control",
 	featureProbe: "feature-probe",
 	filesystemBrowse: "filesystem-browse",
@@ -36606,6 +36963,10 @@ var CAPABILITY_ROUTER_KEYS = [
 		key: "faceGallery",
 		name: "face-gallery"
 	},
+	{
+		key: "failureContribution",
+		name: "failure-contribution"
+	},
 	{
 		key: "fanControl",
 		name: "fan-control"
@@ -37050,6 +37411,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
 	eventEmitterCapability,
 	eventsCapability,
 	faceGalleryCapability,
+	failureContributionCapability,
 	fanControlCapability,
 	featureProbeCapability,
 	filesystemBrowseCapability,
@@ -39056,6 +39418,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"failureContribution.list": {
+		capName: "failure-contribution",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"fanControl.setDirection": {
 		capName: "fan-control",
 		capScope: "device",
@@ -42362,6 +42730,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getFailureContributions": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getLoadContributions": {
 		capName: "system",
 		capScope: "system",
@@ -43052,6 +43426,7 @@ var KNOWN_CAP_NAMES = [
 	"embedding-encoder",
 	"events",
 	"face-gallery",
+	"failure-contribution",
 	"fan-control",
 	"filesystem-browse",
 	"humidifier",
@@ -43218,6 +43593,7 @@ var SYSTEM_CAP_NAMES = [
 	"device-state",
 	"embedding-encoder",
 	"face-gallery",
+	"failure-contribution",
 	"filesystem-browse",
 	"integrations",
 	"llm",
@@ -46166,6 +46542,7 @@ function createSystemProxy(api) {
 			detectSiteLocation: (input) => dispatch("system", "detectSiteLocation", "mutation", input),
 			getRequestCensus: (input) => dispatch("system", "getRequestCensus", "query", input),
 			getLoadContributions: (input) => dispatch("system", "getLoadContributions", "query", input),
+			getFailureContributions: (input) => dispatch("system", "getFailureContributions", "query", input),
 			getLoggingSettings: (input) => dispatch("system", "getLoggingSettings", "query", input),
 			setLoggingSettings: (input) => dispatch("system", "setLoggingSettings", "mutation", input)
 		},
@@ -50498,6 +50875,9 @@ exports.ExpressionParseError = ExpressionParseError;
 exports.ExpressionSourceSchema = ExpressionSourceSchema;
 exports.FIRST_LEVEL_MACRO_CLASSES = FIRST_LEVEL_MACRO_CLASSES;
 exports.FULL_IMAGE_BBOX = FULL_IMAGE_BBOX;
+exports.FailureContributionSchema = FailureContributionSchema;
+exports.FailureCounters = FailureCounters;
+exports.FailureReasonCountSchema = FailureReasonCountSchema;
 exports.FanControlStatusSchema = FanControlStatusSchema;
 exports.FanDirectionSchema = FanDirectionSchema;
 exports.FeatureManifestSchema = FeatureManifestSchema;
@@ -50613,6 +50993,8 @@ exports.MAX_EXPRESSION_BINDINGS = MAX_EXPRESSION_BINDINGS;
 exports.MAX_EXPRESSION_CALL_ARGS = MAX_EXPRESSION_CALL_ARGS;
 exports.MAX_EXPRESSION_EVAL_STEPS = MAX_EXPRESSION_EVAL_STEPS;
 exports.MAX_EXPRESSION_SOURCE_LENGTH = MAX_EXPRESSION_SOURCE_LENGTH;
+exports.MAX_KEYS = MAX_KEYS;
+exports.MAX_REASONS_PER_KEY = MAX_REASONS_PER_KEY;
 exports.MAX_SENSOR_TRIGGER_DEVICES = MAX_SENSOR_TRIGGER_DEVICES;
 exports.METHOD_ACCESS_MAP = METHOD_ACCESS_MAP;
 exports.METHOD_DEVICE_SELECTORS = METHOD_DEVICE_SELECTORS;
@@ -50783,6 +51165,7 @@ exports.NumericSensorStatusSchema = NumericSensorStatusSchema;
 exports.OPERATOR_WRITTEN_STALE_MS = OPERATOR_WRITTEN_STALE_MS;
 exports.OPS_LOG_DEFAULT_LIMIT = OPS_LOG_DEFAULT_LIMIT;
 exports.OPS_LOG_RING_DEFAULT_MAX = OPS_LOG_RING_DEFAULT_MAX;
+exports.OVERFLOW_REASON = OVERFLOW_REASON;
 exports.OauthIntegrationDescriptorSchema = OauthIntegrationDescriptorSchema;
 exports.ObjectEventSchema = ObjectEventSchema;
 exports.OpsLogDomainSchema = OpsLogDomainSchema;
@@ -50904,6 +51287,7 @@ exports.RelocateJobStateSchema = RelocateJobStateSchema;
 exports.RelocateMediaInputSchema = RelocateMediaInputSchema;
 exports.RenderedAsSchema = RenderedAsSchema;
 exports.ReportMotionInputSchema = ReportMotionInputSchema;
+exports.ReportedFailureContributionSchema = ReportedFailureContributionSchema;
 exports.ReportedLoadContributionSchema = ReportedLoadContributionSchema;
 exports.RequestCensusGroupSchema = RequestCensusGroupSchema;
 exports.RequestCensusProcedureSchema = RequestCensusProcedureSchema;
@@ -51302,6 +51686,8 @@ exports.expandCapMethods = require_sleep.expandCapMethods;
 exports.extractNestedAddonId = extractNestedAddonId;
 exports.extractSourceInfoFromMetadata = extractSourceInfoFromMetadata;
 exports.faceGalleryCapability = faceGalleryCapability;
+exports.failureContributionCapability = failureContributionCapability;
+exports.failureRate = failureRate;
 exports.fanControlCapability = fanControlCapability;
 exports.featureProbeCapability = featureProbeCapability;
 exports.filesystemBrowseCapability = filesystemBrowseCapability;