@camstack/types 1.2.119 → 1.2.122

package/dist/interfaces/event-bus.d.ts

@@ -7,7 +7,7 @@ import type { PipelineEngineChoice } from '../types/pipeline.js';
 import type { PipelineExecutionTrace, StepCadence } from '../types/pipeline-step.js';
 import type { CameraMetrics } from './api-shared.js';
 import type { FrameHandle } from './frame-handle.js';
-import type { NodeProcess, SystemResourceSnapshot } from './metrics-provider.js';
+import type { ContainerMemorySnapshot, NodeProcess, SystemResourceSnapshot } from './metrics-provider.js';
 import type { RunnerLocalLoad } from './pipeline-runner-capability.js';
 import type { BrokerStats } from './stream-broker.js';
 export interface EventSource {
@@ -1198,6 +1198,16 @@ export interface EventCatalog {
         readonly nodeId: string;
         readonly processes: ReadonlyArray<NodeProcess>;
         readonly timestamp: number;
+        /**
+         * The CONTAINER's memory at the SAME instant as `processes`, or `null`
+         * when this node has no cgroup.
+         *
+         * It rides this event rather than one of its own for a single reason: the
+         * question is a subtraction. The processes above sum to one number and
+         * this is another, and two events would carry two timestamps that never
+         * quite line up. `null` is ABSENT — never a zeroed reading.
+         */
+        readonly containerMemory: ContainerMemorySnapshot | null;
     };
     /**
      * Per-agent hwaccel override changed (set / cleared / re-probed). Payload

package/dist/interfaces/metrics-provider.d.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod';
-import type { CpuBreakdownSchema, MemoryInfoSchema, DiskIoSnapshotSchema, NetworkIoSnapshotSchema, MetricsGpuInfoSchema, ProcessResourceInfoSchema, PressureInfoSchema, SystemResourceSnapshotSchema, DiskSpaceInfoSchema, PidResourceStatsSchema, AddonInstanceSchema, NodeProcessSchema, DumpHeapSnapshotInputSchema, DumpHeapSnapshotResultSchema, LoadPointSchema, LoadFunctionSeriesSchema, NodeLoadSeriesSchema, GetLoadSeriesInputSchema } from '../capabilities/metrics-provider.cap.js';
+import type { CpuBreakdownSchema, MemoryInfoSchema, DiskIoSnapshotSchema, NetworkIoSnapshotSchema, MetricsGpuInfoSchema, ProcessResourceInfoSchema, PressureInfoSchema, SystemResourceSnapshotSchema, DiskSpaceInfoSchema, PidResourceStatsSchema, AddonInstanceSchema, NodeProcessSchema, DumpHeapSnapshotInputSchema, DumpHeapSnapshotResultSchema, LoadPointSchema, LoadFunctionSeriesSchema, ContainerMemorySnapshotSchema, ContainerMemoryPointSchema, NodeLoadSeriesSchema, GetLoadSeriesInputSchema } from '../capabilities/metrics-provider.cap.js';
 export type CpuBreakdown = z.infer<typeof CpuBreakdownSchema>;
 export type MemoryInfo = z.infer<typeof MemoryInfoSchema>;
 export type DiskIoSnapshot = z.infer<typeof DiskIoSnapshotSchema>;
@@ -16,5 +16,7 @@ export type DumpHeapSnapshotInput = z.infer<typeof DumpHeapSnapshotInputSchema>;
 export type DumpHeapSnapshotResult = z.infer<typeof DumpHeapSnapshotResultSchema>;
 export type LoadSeriesPoint = z.infer<typeof LoadPointSchema>;
 export type LoadFunctionSeries = z.infer<typeof LoadFunctionSeriesSchema>;
+export type ContainerMemorySnapshot = z.infer<typeof ContainerMemorySnapshotSchema>;
+export type ContainerMemoryPoint = z.infer<typeof ContainerMemoryPointSchema>;
 export type NodeLoadSeries = z.infer<typeof NodeLoadSeriesSchema>;
 export type GetLoadSeriesInput = z.infer<typeof GetLoadSeriesInputSchema>;

package/dist/interfaces/recording-config.d.ts

@@ -6,11 +6,10 @@ import { type CamProfile } from '../capabilities/schemas/streaming-shared.js';
  * timestamp + postMs]`). Matches the admin-ui clip window (−5s/+10s).
  *
  * Every consumer derives from this ONE constant so event↔footage boundaries
- * agree everywhere (C1):
- *   - the `videoclips` default provider (addon-post-analysis) pads its clip
- *     windows with it;
- *   - the recorder's ephemeral in-RAM `EventMap` markers (addon-pipeline) pad
- *     their `startMs/endMs` with it.
+ * agree everywhere (C1): today that is the `videoclips` default provider
+ * (addon-post-analysis), which pads its clip windows with it. The recorder used
+ * to pad in-RAM playback markers with it too; those markers had no reader
+ * anywhere in the repo and were deleted on 2026-08-29.
  *
  * NOTE: this is a UI/JOIN convention, NOT the `events`-band keep/discard gate —
  * that uses the per-device `preBufferSec`/`postBufferSec` config.

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/package.json

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