@camstack/types 1.2.114 → 1.2.115

package/dist/interfaces/logging.d.ts

@@ -56,6 +56,21 @@ export interface LogTags {
      * emitting code can reuse whatever handle the addon already has.
      */
     readonly sessionId?: string;
+    /**
+     * The per-component log CHANNEL this line was emitted on (e.g.
+     * `stream-broker.webrtc`). Set by {@link LogChannelGate.log} and by nothing
+     * else, so `| json | logChannel="stream-broker.webrtc"` selects exactly the
+     * lines an armed channel produced — without matching on message text, which
+     * is what makes a channel readable a day later.
+     *
+     * Deliberately NOT `channel`: that tag is already taken and means something
+     * else entirely — the NVR sub-channel index a Reolink hub camera sits on
+     * (`accessories/siren.ts`, `accessories/floodlight.ts`), and it is a NUMBER.
+     * One tag key meaning both `2` and `stream-broker.rtp` would make every
+     * LogQL selector over it ambiguous, which is the same "two things under one
+     * name" defect this mechanism exists to remove.
+     */
+    readonly logChannel?: string;
     /** Arbitrary extra tags */
     readonly [key: string]: string | number | undefined;
 }

package/dist/interfaces/storage.d.ts

@@ -114,6 +114,30 @@ export interface SettingsIsEmptyInput {
     readonly namespace?: string;
     readonly collection: SettingsCollection;
 }
+/**
+ * One scalar an {@link ISettingsBackend.aggregate} call asks for. `as` names the
+ * result slot, so `MIN(startMs)` and `MAX(startMs)` can be asked in one call.
+ */
+export interface SettingsAggregateField {
+    readonly as: string;
+    readonly field: string;
+    readonly op: 'sum' | 'min' | 'max';
+}
+export interface SettingsAggregateInput {
+    readonly namespace?: string;
+    readonly collection: SettingsCollection;
+    readonly fields: readonly SettingsAggregateField[];
+    readonly filter?: QueryFilter;
+}
+/**
+ * `COUNT(*)` plus one value per requested field. A value is `null` when no row
+ * matched — never 0, because "nothing is there" and "the sum is zero" are
+ * different facts about a disk.
+ */
+export interface SettingsAggregateResult {
+    readonly count: number;
+    readonly values: Readonly<Record<string, number | null>>;
+}
 export interface SettingsHistogramInput {
     readonly namespace?: string;
     readonly collection: SettingsCollection;
@@ -147,6 +171,8 @@ export interface ISettingsBackend {
     delete(input: SettingsDeleteInput): Promise<void>;
     /** Count entries in a collection */
     count(input: SettingsCountInput): Promise<number>;
+    /** COUNT(*) plus one SUM/MIN/MAX per field, in one statement. */
+    aggregate(input: SettingsAggregateInput): Promise<SettingsAggregateResult>;
     /** Grouped counts: COUNT(*) per ((field - origin) / bucketSize) bucket. */
     histogram(input: SettingsHistogramInput): Promise<readonly HistogramBucket[]>;
     /** Check if a collection is empty (used for first-boot detection) */

package/dist/logging/log-channel-provider.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The one-liner an addon registers to join the channel mechanism.
+ *
+ * ```ts
+ * context.registerProvider('log-channels', createLogChannelsProvider(this.ctx.logger))
+ * ```
+ *
+ * Everything it does is bookkeeping over the process-wide
+ * {@link LogChannelRegistry}: enumerate the declarations, and push the
+ * document's armed set into the mirror. It holds no value of its own, so a
+ * second provider in another addon of the same process cannot disagree with
+ * this one — they share the registry.
+ *
+ * ## Why the ticker lives here
+ *
+ * A window is a deadline, and something has to notice the deadline passing.
+ * It must not be the log path: a diagnostic that adds a `Date.now()` to the
+ * path it is measuring measures itself. So the provider owns a coarse
+ * interval that calls {@link LogChannelRegistry.tick} and writes ONE line per
+ * closed channel — because a channel going quiet with no line reads as "that
+ * branch was never taken", which is the wrong conclusion and an expensive one.
+ */
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { LogChannelWindow } from './log-channel.js';
+/**
+ * How often expiry is noticed. Coarse on purpose: the cost of a channel
+ * running a few seconds past its deadline is a few extra lines, and the cost
+ * of a tight timer in every addon process is paid forever.
+ */
+export declare const LOG_CHANNEL_TICK_MS = 5000;
+export interface LogChannelsProviderHandle {
+    readonly list: () => readonly LogChannelDescriptorOut[];
+    readonly apply: (input: LogChannelApplyInput) => LogChannelApplyOut;
+    /** Stop the expiry ticker. Call from the addon's `shutdown()`. */
+    readonly stop: () => void;
+}
+export interface LogChannelApplyInput {
+    readonly windows: readonly LogChannelWindow[];
+}
+export interface LogChannelApplyOut {
+    readonly armed: number;
+    readonly unknown: readonly string[];
+}
+interface LogChannelDescriptorOut {
+    readonly name: string;
+    readonly description: string;
+    readonly defaultLevel: 'info' | 'warn' | 'error';
+    readonly perDevice: boolean;
+}
+export interface LogChannelsProviderOptions {
+    /** Injected so a spec can drive expiry without waiting. */
+    readonly now?: () => number;
+    readonly tickMs?: number;
+}
+/**
+ * Build the `log-channels` provider for this process.
+ *
+ * `logger` is used ONLY off the hot path — for the arm/expiry lines — so a
+ * channel that is never armed costs this module nothing but a timer.
+ */
+export declare function createLogChannelsProvider(logger: IScopedLogger, options?: LogChannelsProviderOptions): LogChannelsProviderHandle;
+export {};

package/dist/logging/log-channel.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Per-component log CHANNELS — the gate a hot path consults, and the registry
+ * an addon declares its channels in.
+ *
+ * ## Two axes, deliberately separated
+ *
+ * - **DECLARATION** — which channels exist. Only the addon knows:
+ *   `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
+ *   baichuan/handshake. A hand-wired central list rots at the first addition,
+ *   and rots silently. So a channel is declared where it is consulted, and the
+ *   `log-channels` capability enumerates the declarations.
+ * - **VALUE** — at which level, for which scope, until when. That stays ONE
+ *   thing: the logging settings document on the `system` cap. Two authorities
+ *   over the values is the exact defect
+ *   `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
+ *   remove; re-introducing it from the cure side would be grotesque.
+ *
+ * Nothing in this file reads a clock, an env var or a store. The registry is
+ * a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
+ * the hot path with a value somebody actually read, and by
+ * {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
+ * never reaches here, so it can neither disarm an armed channel nor arm a
+ * disarmed one (D49).
+ *
+ * ## The canonical call shape
+ *
+ * ```ts
+ * if (CH_RTP.on && CH_RTP.wants(deviceId)) {
+ *   CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
+ * }
+ * ```
+ *
+ * `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
+ * read. Disarmed, a call site costs one load and one branch, and the `extras`
+ * object literal is never constructed because it lives inside the branch. It
+ * is the same shape already proven in production at `stream-broker.ts:1650`,
+ * and the same discipline `LoggingGate.allowsDestination` uses for the
+ * destination floor (measured at 1.93 ns/call when off).
+ *
+ * ## Why a channel emits at `info`
+ *
+ * `loki-logging.addon.ts` pins the destination default at `info` and
+ * `loki-destination.ts` drops everything below it, so a line emitted at
+ * `debug` never reaches Loki and the hub's in-memory ring only holds ~35
+ * minutes. A diagnostic that cannot be read an hour later is worse than no
+ * diagnostic, because it looks done. {@link LogChannelGate.log} therefore
+ * emits at the channel's declared level, whose schema floor is `info`.
+ */
+import { z } from 'zod';
+import type { IScopedLogger, LogExtras } from '../interfaces/logging.js';
+/**
+ * The level a channel writes at once armed.
+ *
+ * `debug` is absent ON PURPOSE and not by omission: below `info` the line does
+ * not leave the process for Loki, and the whole point of arming a channel is
+ * to read it later.
+ */
+export declare const LogChannelLevelSchema: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warn: "warn";
+}>;
+/**
+ * What an addon declares about one channel. No value, no state — a
+ * declaration is inert.
+ */
+export declare const LogChannelDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    defaultLevel: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+    }>;
+    perDevice: z.ZodBoolean;
+}, z.core.$strip>;
+export type LogChannelDescriptor = z.infer<typeof LogChannelDescriptorSchema>;
+/**
+ * An armed window over one channel, as the document hands it to a mirror.
+ *
+ * A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
+ * expires by itself, which is the one failure a boolean cannot avoid.
+ */
+export declare const LogChannelWindowSchema: z.ZodObject<{
+    channel: z.ZodString;
+    armedUntilMs: z.ZodNumber;
+    deviceIds: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodNumber>>>;
+}, z.core.$strip>;
+export type LogChannelWindow = z.infer<typeof LogChannelWindowSchema>;
+/**
+ * The gate a hot path holds.
+ *
+ * Obtain it ONCE — at module scope or in a constructor — and keep the
+ * reference. Looking a channel up by name per line would put a Map lookup on
+ * the path this class exists to keep free.
+ */
+export declare class LogChannelGate {
+    readonly descriptor: LogChannelDescriptor;
+    /**
+     * HOT PATH GUARD. A plain data FIELD, and it must stay one.
+     *
+     * `log-channel.spec.ts` asserts the property descriptor has no getter and
+     * booby-traps the device set, so turning this into an accessor — or reading
+     * anything before it — fails the spec instead of taxing every line the
+     * process emits.
+     */
+    on: boolean;
+    /** `null` while armed for every camera. Never read while `on` is false. */
+    private devices;
+    private level;
+    private closesAtMs;
+    constructor(descriptor: LogChannelDescriptor);
+    /** Epoch ms this channel disarms itself at. 0 when disarmed. */
+    get armedUntilMs(): number;
+    /**
+     * Does this channel want a line about `deviceId`?
+     *
+     * Call it only behind `gate.on &&`. On its own it is still correct — the
+     * guard is repeated inside — but the point of the prefix is that a disarmed
+     * channel must not pay the call at all.
+     */
+    wants(deviceId: number): boolean;
+    /**
+     * Emit one line on this channel, at the channel's declared level.
+     *
+     * The channel name is added as `tags.logChannel` so LogQL can select the
+     * channel without matching on the message text, and whatever `tags` the
+     * caller passed — `deviceId` above all — is preserved.
+     */
+    log(logger: IScopedLogger, message: string, extras: LogExtras): void;
+    /**
+     * Arm (or RE-arm, restarting) this channel. Off the hot path only.
+     *
+     * An empty `deviceIds` list is treated as "every camera" rather than "no
+     * camera": a window that matches nothing is indistinguishable from a
+     * disarmed one, and the operator who asked for it would wait for lines that
+     * can never come.
+     */
+    arm(window: LogChannelWindow): void;
+    /** Disarm. Off the hot path only. */
+    disarm(): void;
+}
+/**
+ * Every channel this PROCESS declares, and the mirror of what is armed on it.
+ *
+ * One per process. A forked runner has its own, and it is refreshed through
+ * the `log-channels` capability by the hub that owns the document — the
+ * registry never reaches for a value itself.
+ */
+export declare class LogChannelRegistry {
+    private readonly gates;
+    /**
+     * Declare a channel and get its gate.
+     *
+     * A duplicate name throws. Two declarations of one name is a programming
+     * error, not a merge: the operator would arm one and the other would stay
+     * dark, which is the dead-knob shape (D62) with an extra step.
+     */
+    declare(descriptor: LogChannelDescriptor): LogChannelGate;
+    /** The declarations, sorted by name so a list is stable to read and diff. */
+    list(): readonly LogChannelDescriptor[];
+    /** The gate for a declared channel, or `undefined`. */
+    gate(name: string): LogChannelGate | undefined;
+    /**
+     * Apply the FULL set of armed windows. Off the hot path.
+     *
+     * Full, not incremental, and that is the whole design: the document is the
+     * authority, so a channel the document does not name is disarmed here. An
+     * incremental apply would let a disarm get lost in transit and leave a
+     * channel running that nobody can see is running.
+     *
+     * A window already past its deadline is ignored rather than armed — a
+     * restore that re-armed an expired window would make a forgotten diagnostic
+     * immortal across restarts.
+     *
+     * Returns the names it could not place, so the caller can log them: a
+     * channel named in the document that this process does not declare is
+     * either a typo or an addon that has not booted yet, and both deserve a
+     * line rather than silence.
+     */
+    apply(windows: readonly LogChannelWindow[], nowMs: number): readonly string[];
+    /**
+     * Disarm whatever has run out. Called on a timer, NEVER from a log path — a
+     * diagnostic that adds a `Date.now()` to the path it is measuring measures
+     * itself.
+     *
+     * Returns the names it closed, so the caller can write the one line that
+     * says a window ended and stops "it went quiet" from reading as "the branch
+     * was not taken".
+     */
+    tick(nowMs: number): readonly string[];
+    /** The channels armed right now, as the document would describe them. */
+    armed(): readonly LogChannelWindow[];
+}

package/dist/logging/log-channel.singleton.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-wide holder for the {@link LogChannelRegistry}.
+ *
+ * Three call sites that never meet need the SAME instance: the hot paths that
+ * declare a gate at module scope, the `log-channels` provider that enumerates
+ * the declarations for the hub, and the same provider applying the windows the
+ * document hands down. A registry built inside any one of them would be
+ * refreshed and collected — the shape of a knob that never does anything.
+ *
+ * Same idiom as `logging-gate.singleton.ts` and
+ * `http-request-census.singleton.ts`.
+ */
+import { LogChannelRegistry, type LogChannelDescriptor, type LogChannelGate } from './log-channel.js';
+/** The process-wide log channel registry. Created empty on first use. */
+export declare function getLogChannelRegistry(): LogChannelRegistry;
+/**
+ * Declare a channel on the process-wide registry and get its gate.
+ *
+ * The one call an addon makes. Keep the returned gate in a module-scope
+ * `const`: looking a channel up by name per line would put a Map lookup on
+ * exactly the path this mechanism exists to keep free.
+ *
+ * `scripts/check-log-channel-gated.ts` reads these call sites. It pairs the
+ * declared name with the binding it is assigned to and refuses to let a
+ * channel ship that no `<binding>.on` anywhere consults — a declared channel
+ * nobody reads is a knob the operator turns with nothing happening, forever,
+ * and without a line. That is D62, and this repo has now shipped it three
+ * times (`audioThresholdDbfs`, the HA entities with no source, the second
+ * per-camera switch that wrote a store nobody read).
+ */
+export declare function declareLogChannel(descriptor: LogChannelDescriptor): LogChannelGate;
+/** Test-only: drop the instance so a spec starts from an empty registry. */
+export declare function __resetLogChannelRegistryForTests(): void;

package/package.json

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