@camstack/addon-osd-manager 0.1.30 → 0.1.32

package/dist/index.js

@@ -5919,6 +5919,40 @@ var BaseAddon = class {
 	deviceSettingsSchema() {
 		return null;
 	}
+	/**
+	* INTEGRATION-LEVEL SETTINGS — declare which of this addon's global sections
+	* ARE the configuration of its integration.
+	*
+	* Return the `ConfigSection.id`s, from {@link globalSettingsSchema}, that an
+	* operator should find on the addon's integration page (System →
+	* Integrations → <name>) rather than only in the cluster-wide list of every
+	* addon. Empty (the default) means the addon has no integration-level
+	* settings and no such surface is offered — this is opt-in, because whether
+	* an addon's configuration IS its integration's configuration depends on the
+	* nature of the integration.
+	*
+	* WHAT THIS IS NOT. It is not a scope. The selected sections keep living in
+	* the ONE global schema, in the ONE addon store, written by the ONE
+	* `updateGlobalSettings` path. There is deliberately no
+	* `updateIntegrationSettings`: a second write path is how a surface acquires
+	* a second store key, and this repo has shipped that twice (`btmPath@hub`,
+	* D266). Selecting sections cannot introduce a key that selecting cannot.
+	*
+	* WHY IT IS A LIST OF SECTION IDS AND NOT A MARKER ON THE SECTION.
+	* `ConfigFieldBase` used to carry `scope?: 'device' | 'global'` and it was
+	* removed with the reason recorded at
+	* `packages/types/src/interfaces/config-ui.ts:249` — *"a field's scope is
+	* determined by WHICH schema it lives in, not by a field-level marker."* A
+	* marker sprinkled across sections also has to borrow a field that already
+	* means something else; borrowing `section.tab` put the literal word
+	* "integration" into an operator-facing tab bar, because `tab` means "how to
+	* GROUP this visually" and cannot also mean "where this lives" (D269
+	* supersedes D268). One declaration, in one place, next to the schema whose
+	* ids it names.
+	*/
+	integrationSettingSections() {
+		return [];
+	}
 	async getGlobalSettings(overlay, cap, nodeId) {
 		const schema = this.globalSettingsSchema(cap);
 		if (!schema) return { sections: [] };
@@ -5929,6 +5963,55 @@ var BaseAddon = class {
 		} : projected);
 	}
 	/**
+	* The integration-level view of this addon's settings: exactly the sections
+	* named by {@link integrationSettingSections}, hydrated from the SAME store
+	* `getGlobalSettings` reads, and narrowed to cluster-scoped fields.
+	*
+	* Returns `null` when the addon declared nothing — an addon that opts out has
+	* no integration settings surface at all, rather than an empty one that reads
+	* as a failed load.
+	*
+	* Three properties hold BY CONSTRUCTION, which is why they are here in core
+	* and not in whichever UI happens to render this:
+	*
+	*  1. **One key.** The payload is a SUBSET of the global schema, so a field
+	*     shown here is the same field, with the same bare key, that the addon's
+	*     own page shows. There is no integration-specific writer — callers save
+	*     through `updateGlobalSettings` — so a second store key is unreachable,
+	*     not merely discouraged.
+	*  2. **No node scope.** `perNode: true` fields are DROPPED. Their store key
+	*     is `<key>@<nodeId>` and an integration is not a node; whichever node
+	*     such a field silently picked would be a wrong answer for the operator
+	*     who opened the page (D266).
+	*  3. **No silent typo.** A declared id that names no section throws. The
+	*     alternative — skip it — turns a rename into a surface that quietly
+	*     empties, which looks exactly like an addon with nothing to configure.
+	*/
+	async getIntegrationSettings(nodeId) {
+		const declared = this.integrationSettingSections();
+		if (declared.length === 0) return null;
+		const schema = this.globalSettingsSchema();
+		if (!schema) throw new Error(`${this.constructor.name}: integrationSettingSections() names [${declared.join(", ")}] but globalSettingsSchema() returns null.`);
+		const byId = new Map(schema.sections.map((section) => [section.id, section]));
+		const sections = [];
+		for (const id of declared) {
+			const section = byId.get(id);
+			if (!section) throw new Error(`${this.constructor.name}: integrationSettingSections() names unknown section "${id}". Known sections: [${[...byId.keys()].join(", ")}].`);
+			const fields = dropPerNodeFields(section.fields);
+			if (fields.length === 0) continue;
+			sections.push({
+				...section,
+				fields
+			});
+		}
+		if (sections.length === 0) return null;
+		const projected = await this.resolveGlobalStore(nodeId);
+		return hydrateSchema({
+			...schema,
+			sections
+		}, projected);
+	}
+	/**
 	* The raw addon store PROJECTED onto the target node's bare per-node keys:
 	* every `perNode: true` field carries THAT node's scoped value on its bare
 	* key (absent scoped key ⇒ key absent, so the schema `default` wins — no
@@ -6232,6 +6315,41 @@ var BaseAddon = class {
 * `hydrateSchema` does. Valueless structural fields (separator/info/…)
 * don't declare `perNode` and are excluded by the `in` narrowing.
 */
+/**
+* The same fields with every `perNode: true` one removed, recursing into layout
+* containers exactly as {@link collectPerNodeFieldKeys} does. A container left
+* with no child is dropped rather than rendered empty.
+*
+* Used by `getIntegrationSettings`: an integration is not a node, so a field
+* whose store key is `<key>@<nodeId>` has no node to belong to there.
+*/
+function dropPerNodeFields(fields) {
+	const kept = [];
+	for (const field of fields) {
+		if (field.type === "group") {
+			const inner = dropPerNodeFields(field.fields);
+			if (inner.length > 0) kept.push({
+				...field,
+				fields: inner
+			});
+			continue;
+		}
+		if (field.type === "sub-tabs") {
+			const tabs = field.tabs.map((tab) => ({
+				...tab,
+				fields: dropPerNodeFields(tab.fields)
+			})).filter((tab) => tab.fields.length > 0);
+			if (tabs.length > 0) kept.push({
+				...field,
+				tabs
+			});
+			continue;
+		}
+		if ("perNode" in field && field.perNode === true) continue;
+		kept.push(field);
+	}
+	return kept;
+}
 function collectPerNodeFieldKeys(fields) {
 	const collected = [];
 	for (const field of fields) {
@@ -9571,6 +9689,10 @@ var addonSettingsCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		getIntegrationSettings: method(object({
+			addonId: string(),
+			nodeId: string().optional()
+		}), SettingsSchemaWithValuesSchema.nullable()),
 		getDeviceSettings: method(object({
 			addonId: string(),
 			deviceId: number(),
@@ -15001,6 +15123,133 @@ var logDestinationCapability = {
 	/** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
 	mount: { kind: "skip" }
 };
+/**
+* `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()
+});
+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: method(_void(), array(FailureContributionSchema).readonly()) },
+	/** In-process only — enumerated through `addons.listCapabilityProviders`. */
+	mount: { kind: "skip" }
+};
 var LoadContributionSchema = object({
 	role: _enum([
 		"decode",
@@ -20527,6 +20776,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
 });
@@ -34042,6 +34305,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(),
 	/**
@@ -34160,6 +34430,28 @@ var systemCapability = {
 		*/
 		getLoadContributions: method(_void(), 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: method(_void(), array(ReportedFailureContributionSchema).readonly(), { auth: "admin" }),
+		/**
 		* The logging settings document — levels and armed diagnostics — resolved
 		* for `nodeId`, or for the cluster when `nodeId` is absent.
 		*
@@ -35394,6 +35686,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
 	eventEmitterCapability,
 	eventsCapability,
 	faceGalleryCapability,
+	failureContributionCapability,
 	fanControlCapability,
 	featureProbeCapability,
 	filesystemBrowseCapability,
@@ -35730,6 +36023,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"addonSettings.getIntegrationSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"addonSettings.updateDeviceSettings": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -37392,6 +37691,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",
@@ -40698,6 +41003,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getFailureContributions": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getLoadContributions": {
 		capName: "system",
 		capScope: "system",