@camstack/types 1.2.118 → 1.2.120

package/dist/interfaces/addon.d.ts

@@ -790,6 +790,17 @@ export interface ICamstackAddon {
      *  persisted store. */
     getGlobalSettings?(overlay?: Record<string, unknown>, cap?: string, nodeId?: string): Promise<ConfigUISchemaWithValues | null>;
     updateGlobalSettings?(patch: Record<string, unknown>, nodeId?: string): Promise<void>;
+    /**
+     * Integration-level settings — the subset of the global schema the addon
+     * declared as its INTEGRATION's configuration (`BaseAddon.
+     * integrationSettingSections`). `null` ⇒ none declared, so the surface is
+     * not offered.
+     *
+     * There is no matching updater on purpose: the payload is a subset of the
+     * global schema, so `updateGlobalSettings` is the writer and the store key
+     * stays the one bare key. See `addon-settings.cap.ts`.
+     */
+    getIntegrationSettings?(nodeId?: string): Promise<ConfigUISchemaWithValues | null>;
     /** Level 2 — per-device settings (schema + values). Appears in
      *  Device Overrides. */
     getDeviceSettings?(deviceId: number): Promise<ConfigUISchemaWithValues>;

package/dist/metrics/failure-counters.d.ts

@@ -0,0 +1,173 @@
+/**
+ * `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. */
+export declare const 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.
+ */
+export declare const 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.
+ */
+export declare const OVERFLOW_REASON = "other";
+/** One reason and how many times it was the reason. */
+export interface FailureReasonCount {
+    readonly reason: string;
+    readonly count: number;
+}
+/** One (device, family[, variant]) counter, read. */
+export interface FailureCounterSample {
+    readonly deviceId: number;
+    /**
+     * The failing path, in the contributor's own vocabulary — `enrichment-crop`,
+     * `inference`, `plate-ocr`. Free-form because the families are owned by
+     * different addons and a shared enum would be a central list that rots
+     * invisibly the first time somebody adds a path (the argument
+     * `load-contribution.cap.ts` makes about pid maps, applied to reasons).
+     */
+    readonly family: string;
+    /**
+     * An optional second dimension WITHIN the family — the model or step id for
+     * an inference timeout, so "which camera AND which model" is answerable
+     * without a second surface. Absent when the family has only one variant.
+     */
+    readonly variant?: string;
+    /**
+     * Epoch ms this counter started — the incarnation marker. A consumer
+     * differencing two reads drops the interval when it changes, because the
+     * counter restarted from zero in a new process.
+     */
+    readonly sinceMs: number;
+    /** Epoch ms it was read. `atMs - sinceMs` is the interval it covers. */
+    readonly atMs: number;
+    /** THE DENOMINATOR. Every try, landed or not. */
+    readonly attempts: number;
+    /** Tries that landed. `attempts - succeeded` is the loss. */
+    readonly succeeded: number;
+    /** Why the rest did not, partitioned. Sums to `attempts - succeeded`. */
+    readonly reasons: readonly FailureReasonCount[];
+}
+/** What one observation says. */
+export interface FailureObservation {
+    readonly deviceId: number;
+    readonly family: string;
+    readonly variant?: string;
+    /**
+     * `undefined` = the attempt LANDED. A string = it did not, and this is why.
+     * There is no third state: a call that cannot say which it was must not be
+     * noted, because an attempt with no outcome moves the denominator without
+     * moving anything else and silently improves the ratio.
+     */
+    readonly reason?: string;
+}
+/**
+ * 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.
+ */
+export declare class FailureCounters {
+    private readonly maxKeys;
+    private readonly maxReasons;
+    private readonly counters;
+    private refused;
+    constructor(maxKeys?: number, maxReasons?: number);
+    /**
+     * 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(): number;
+    /** Counters currently held. */
+    get size(): number;
+    /**
+     * 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: FailureObservation, nowMs: number): void;
+    /** Read every counter. Never mutates — see the module docblock. */
+    snapshot(nowMs: number): readonly FailureCounterSample[];
+    /** Drop everything (host disposal). */
+    clear(): void;
+}
+/**
+ * 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.
+ */
+export declare function failureRate(sample: FailureCounterSample): number | null;

package/dist/{sleep-Dolp38qx.mjs → sleep-C9C8EoK8.mjs}

@@ -685,6 +685,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: [] };
@@ -695,6 +729,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
@@ -998,6 +1081,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) {

package/dist/{sleep-9d8tJRbO.js → sleep-DUxF5DdC.js}

@@ -685,6 +685,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: [] };
@@ -695,6 +729,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
@@ -998,6 +1081,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.118",
+  "version": "1.2.120",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",