@camstack/types 1.2.64 → 1.2.66

package/dist/notification/audio-condition.d.ts

@@ -0,0 +1,118 @@
+/**
+ * audio-condition — the authoring logic behind the sustained-sound condition
+ * (`NcConditions.audio`), pure and UI-framework-free.
+ *
+ * WHY IT LIVES HERE
+ * ─────────────────
+ * Same reason as `condition-taxonomy.ts` next door: two editors author this
+ * condition (the admin UI and the viewer), the vocabulary it offers is already
+ * in this package (`AUDIO_MACRO_LABELS`), and a second copy of "what a cleared
+ * threshold writes" is a mirror free to drift. The viewer keeps its own copy
+ * because it is a separate app with its own toolchain; every surface that CAN
+ * import `@camstack/types` uses this one.
+ *
+ * Four behaviours here are not cosmetic:
+ *
+ *  1. **dBFS is negative-going.** `0` is full scale; digital silence reads
+ *     {@link NC_AUDIO_DBFS_FLOOR}. A control that let an operator author `60`
+ *     meaning "loud" would write a threshold no sample can reach, and the rule
+ *     would look broken rather than mis-configured. Every write is clamped.
+ *  2. **Neither filter given = the engine REFUSES.** With no level floor and no
+ *     labels every sample is trivially a hit, so the window would fire on
+ *     silence. {@link audioIsFailClosed} is how an editor says that BEFORE the
+ *     save instead of shipping a rule that never notifies and never says why.
+ *  3. **Both label spellings are the same label.** The hub's taxonomy serves
+ *     `audio-dog`; the macro catalog and an operator both say `dog`, and the
+ *     matcher normalizes the prefix away on both sides. Selection therefore
+ *     compares NORMALIZED ids — a rule authored in the admin UI must not read
+ *     as "nothing selected" on the phone.
+ *  4. **A stored label the build does not know stays visible.** It is offered
+ *     as an explicitly-unknown, removable choice, never silently dropped:
+ *     rewriting the rule the operator is looking at is worse than showing a
+ *     stale id.
+ */
+import { type NcAudioCondition } from '../capabilities/notification-rules.cap.js';
+import type { NcTaxonomy } from '../catalogs/nc-taxonomy.js';
+/** Strip the taxonomy's `audio-` namespace: `audio-dog` and `dog` are one label. */
+export declare function normalizeAudioLabel(value: string): string;
+/** Level bounds, in dBFS. Negative-going: the ceiling is full scale. */
+export declare const NC_AUDIO_DB_MIN = -96;
+export declare const NC_AUDIO_DB_MAX = 0;
+/** Step of the level control — 3 dB is one perceptual notch, not one unit. */
+export declare const NC_AUDIO_DB_STEP = 3;
+/**
+ * Offered when the operator turns the level filter ON. NOT a schema default:
+ * an absent `dbThreshold` means "any level" and stays absent until asked for,
+ * and a stepper seeded at the -96 floor would need thirty taps to reach a
+ * threshold that can actually fire.
+ */
+export declare const NC_AUDIO_DB_OFFERED = -30;
+export declare const NC_AUDIO_HIT_PERCENT_MIN = 1;
+export declare const NC_AUDIO_HIT_PERCENT_MAX = 100;
+export declare const NC_AUDIO_SAMPLING_MIN_SEC = 1;
+export declare const NC_AUDIO_SAMPLING_MAX_SEC = 300;
+/** Schema defaults — an untouched sub-field must author exactly these. */
+export declare const NC_AUDIO_DEFAULTS: NcAudioCondition;
+/** What an editor SHOWS for an unset condition — without authoring it. */
+export declare function audioOrDefaults(value: NcAudioCondition | undefined): NcAudioCondition;
+/**
+ * True when the condition names NEITHER a level floor NOR any label. The engine
+ * refuses such a rule (every sample is a hit, so the window fires on silence) —
+ * an editor warns instead of letting the operator ship a rule that never
+ * notifies and says nothing about why.
+ *
+ * An ABSENT condition is not flagged: a rule with no `audio` key is not an
+ * audio rule at all.
+ */
+export declare function audioIsFailClosed(value: NcAudioCondition | undefined): boolean;
+/**
+ * A patch over the composite condition. A key present with `undefined` CLEARS
+ * the (optional) filter; an absent key leaves it alone.
+ */
+export interface NcAudioPatch {
+    readonly labels?: readonly string[] | undefined;
+    readonly dbThreshold?: number | undefined;
+    readonly hitPercent?: number;
+    readonly samplingSeconds?: number;
+}
+/**
+ * Apply a sub-field edit, seeding from the defaults when nothing is stored yet.
+ * The result is always in-bounds for `NcAudioConditionSchema`, and a cleared
+ * filter is OMITTED rather than written as an explicit `undefined` (which
+ * survives a merge patch as a deliberate erase and reads as authored).
+ */
+export declare function patchAudio(current: NcAudioCondition | undefined, patch: NcAudioPatch): NcAudioCondition;
+/**
+ * One offered label. `unknown` = stored by the rule, offered by neither the hub
+ * nor the local catalog — kept so the operator can SEE it and drop it.
+ */
+export interface NcAudioLabelChoice {
+    readonly value: string;
+    readonly label: string;
+    readonly icon: string;
+    readonly unknown: boolean;
+}
+/**
+ * The label choices: the hub's `audioKinds` when it serves them (its WORDS, the
+ * local EMOJI, keyed by the normalized id), else the local macro catalog — plus
+ * any stored label neither side knows, marked unknown.
+ *
+ * The hub's list wins on membership because it knows which macros this cluster
+ * actually classifies; the icons stay local because the taxonomy carries none.
+ */
+export declare function audioLabelChoices(taxonomy: NcTaxonomy | undefined, selected: readonly string[] | undefined): {
+    readonly choices: readonly NcAudioLabelChoice[];
+    readonly unknownLabels: readonly string[];
+};
+/**
+ * Is this macro id selected? Compares NORMALIZED ids, so a rule authored with
+ * the taxonomy spelling (`audio-dog`) reads as selected here.
+ */
+export declare function isAudioLabelSelected(labels: readonly string[] | undefined, id: string): boolean;
+/**
+ * Toggle one macro id. Removing drops EVERY stored spelling of it; adding
+ * appends the bare macro id. Returns `undefined` when the last label goes — the
+ * field is optional and absent means "any sound", never an empty array (which
+ * `NcAudioConditionSchema` rejects outright).
+ */
+export declare function toggleAudioLabel(labels: readonly string[] | undefined, id: string): readonly string[] | undefined;

package/dist/pipeline/native-lease.d.ts

@@ -1,6 +1,6 @@
 /**
- * THE native-frame **lease** knobs — TTL, RAM budget and demand window for the
- * decode worker's native-resolution frame retention.
+ * THE native-frame **lease** knobs — hold depth, RAM budget, demand window and
+ * subject-tile budget for the decode worker's native-resolution retention.
  *
  * ## Why they live here and not in the addon that reads them
  *
@@ -16,20 +16,25 @@
  * The lease is a per-decode-worker RAM window. Its purpose — the late
  * cross-process native crop landing on a full-resolution frame rather than the
  * ≤640 detection fallback — is a property of the PIPELINE, not of a node's
- * hardware: a per-node TTL would mean the same camera produces different crop
+ * hardware: a per-node window would mean the same camera produces different crop
  * quality depending on which node the balancer placed it on, and nobody could
  * tell that from the stored media. Node-level RAM pressure is already handled
  * by the per-session budget ceiling, which is itself one of these knobs.
  *
  * ## What each knob costs
  *
- * A retained frame is a full NATIVE-resolution copy in system RAM. With the
+ * A HELD frame is a full NATIVE-resolution copy in system RAM. With the
  * default pinned-RGB24 lease path (`CAMSTACK_SESSION_PINNED_RGB_CROP`, on):
  * 4K ≈ 24.9 MB/frame, 1080p ≈ 6.2 MB/frame. On the YUV420P path (flag off, and
  * for software-decoded sessions): 4K ≈ 12.4 MB, 1080p ≈ 3.1 MB. Worst-case
- * resident RAM for ONE busy camera ≈ frameBytes × deliveredFps × ttlSeconds,
- * clamped by the budget ceiling. See `docs/design/decode-path.md` → "Lease
- * admission" for what actually gets admitted.
+ * resident RAM for ONE busy camera is now `frameBytes × holdFrames`, clamped by
+ * the budget ceiling — bounded by a COUNT because a held frame is waiting for
+ * one specific event (its own detection result), not for a clock.
+ *
+ * A TILE is one subject at native resolution, JPEG-encoded: ~60-120 KB on 4K,
+ * and nothing at all on a frame that detected nothing. That is the asymmetry
+ * this whole shape exists for — see
+ * `docs/design/2026-08-13-native-lease-two-tier-redesign.md`.
  */
 import { z } from 'zod';
 import type { HydratedSettingsView } from './detail-crop.js';
@@ -39,10 +44,11 @@ import type { HydratedSettingsView } from './detail-crop.js';
  * the reader can walk every section instead of trusting the section id.
  */
 export declare const NATIVE_LEASE_SECTION_ID = "native-lease";
-export declare const NATIVE_LEASE_TTL_KEY = "nativeLeaseTtlMs";
+export declare const NATIVE_LEASE_HOLD_KEY = "nativeLeaseHoldFrames";
 export declare const NATIVE_LEASE_BUDGET_KEY = "nativeLeaseBudgetMb";
 export declare const NATIVE_LEASE_ACTIVITY_KEY = "nativeLeaseActivityMs";
 export declare const NATIVE_LEASE_ADMISSION_KEY = "nativeLeaseAdmission";
+export declare const NATIVE_LEASE_TILE_BUDGET_KEY = "nativeTileBudgetMb";
 /**
  * WHICH delivered frames the decode worker retains a native copy of.
  *
@@ -72,19 +78,24 @@ export type NativeLeaseAdmission = z.infer<typeof NativeLeaseAdmissionSchema>;
  * junk number would silently become a 0-length or unbounded retention window.
  */
 export declare const NativeLeaseSettingsSchema: z.ZodObject<{
-    ttlMs: z.ZodNumber;
+    holdFrames: z.ZodNumber;
     budgetMb: z.ZodNumber;
     activityMs: z.ZodNumber;
     admission: z.ZodEnum<{
         all: "all";
         inferred: "inferred";
     }>;
+    tileBudgetMb: z.ZodNumber;
 }, z.core.$strip>;
 export type NativeLeaseSettings = z.infer<typeof NativeLeaseSettingsSchema>;
 /**
- * The values in force when the operator has set nothing — byte-for-byte the
- * constants the decode worker shipped with as env-var defaults, so making these
- * settings changed no behaviour on the day it landed.
+ * The values in force when the operator has set nothing.
+ *
+ * `budgetMb` stays at 1024 on the day the hold landed, deliberately: it stopped
+ * being the retention window and became the OOM ceiling, and lowering a ceiling
+ * in the same change that redefines it would make a regression and a retune
+ * indistinguishable. Cut it once `tileHits` / `holdOverflow` have been read on
+ * live traffic.
  */
 export declare const DEFAULT_NATIVE_LEASE_SETTINGS: NativeLeaseSettings;
 /**
@@ -94,10 +105,10 @@ export declare const DEFAULT_NATIVE_LEASE_SETTINGS: NativeLeaseSettings;
  */
 export type NativeLeaseSettingsOverride = Partial<NativeLeaseSettings>;
 /** Slider bounds for the operator-facing knobs (orchestrator settings UI). */
-export declare const NATIVE_LEASE_TTL_FIELD: {
-    readonly min: 250;
-    readonly max: 10000;
-    readonly step: 50;
+export declare const NATIVE_LEASE_HOLD_FIELD: {
+    readonly min: 1;
+    readonly max: 64;
+    readonly step: 1;
     readonly default: number;
 };
 export declare const NATIVE_LEASE_BUDGET_FIELD: {
@@ -112,6 +123,12 @@ export declare const NATIVE_LEASE_ACTIVITY_FIELD: {
     readonly step: 1000;
     readonly default: number;
 };
+export declare const NATIVE_LEASE_TILE_BUDGET_FIELD: {
+    readonly min: 0;
+    readonly max: 1024;
+    readonly step: 16;
+    readonly default: number;
+};
 /** Select options for the admission knob (orchestrator settings UI). */
 export declare const NATIVE_LEASE_ADMISSION_FIELD: {
     readonly options: readonly [{
@@ -123,10 +140,10 @@ export declare const NATIVE_LEASE_ADMISSION_FIELD: {
     }];
     readonly default: "all" | "inferred";
 };
-/** The four knobs, as a key union. */
+/** Every knob, as a key union. */
 export type NativeLeaseKnob = keyof NativeLeaseSettings;
-/** The three knobs whose value is a bounded integer (everything but `admission`). */
-export type NativeLeaseNumberKnob = 'ttlMs' | 'budgetMb' | 'activityMs';
+/** The knobs whose value is a bounded integer (everything but `admission`). */
+export type NativeLeaseNumberKnob = 'holdFrames' | 'budgetMb' | 'activityMs' | 'tileBudgetMb';
 /**
  * Narrow a FLAT settings record to the knobs the operator set.
  *

package/dist/{sleep-BxjBLp3L.mjs → sleep-CSgK0rNX.mjs}

@@ -2004,6 +2004,8 @@ function readNodePin(context) {
 *   4. Addon implements IProvider
 *   5. Registry auto-mounts tRPC router from definition.methods
 */
+/** The default applied to a `runtimeState` cap that declares no `durability`. */
+var DEFAULT_RUNTIME_STATE_DURABILITY = "session";
 /**
 * Resolve the EFFECTIVE mount hint for a cap — the explicit `mount` when
 * present, else the scope/mode/deviceNative-derived default. Single source
@@ -3735,4 +3737,4 @@ function sleepCancellable(ms, signal) {
 	});
 }
 //#endregion
-export { FrameHandleSchema as $, method as A, readinessKey as B, DeviceType as C, collectHydratedFieldEntries as Ct, event as D, DEVICE_STATUS_METHOD as E, resolveHydratedFieldValue as Et, readNodePin as F, CamProfileSchema as G, BrokerStatsSchema as H, toNodeId as I, CameraStreamSchema as J, CamStreamKindSchema as K, ReadinessRegistry as L, systemMethod as M, CAP_NODE_PIN_CONTEXT_KEY as N, expandCapMethods as O, nodePin as P, FrameHandleFormatSchema as Q, ReadinessTimeoutError as R, DeviceRole as S, WELL_KNOWN_TAB_MAP as St, DEVICE_SETTINGS_CONTRIBUTION_METHODS as T, hydrateSchema as Tt, BrokerStatusSchema as U, scopeKey as V, CAM_PROFILE_ORDER as W, DecodedFrameSchema as X, DecodedAudioChunkSchema as Y, EncodedPacketSchema as Z, RawStateResultSchema as _, createDurableState as _t, asJsonObject as a, SubscribeAudioChunksInputSchema as at, ChargingStatus as b, isEvent as bt, parseJsonArray as c, SubscribeFramesResultSchema as ct, DEVICE_SCOPED_CAPS as d, parseProfileBrokerId as dt, ProfileRtspEntrySchema as et, isDeviceScopedCap as f, selectAssignedProfileSlots as ft, createSliceHandle as g, normalizeAddonInitResult as gt, createMirrorSource as h, BaseAddon as ht, asJsonArray as i, StreamSourceSchema as it, resolveCapMount as j, isDeviceConfigCap as k, parseJsonObject as l, makeProfileBrokerId as lt, createLazyTrpcSource as m, DisposerChain as mt, sleepCancellable as n, ProfileSlotStatusSchema as nt, asNumber as o, SubscribeAudioChunksResultSchema as ot, createDeviceProxy as p, DATAPLANE_SECRET_HEADER as pt, CamStreamResolutionSchema as q, asBoolean as r, StreamSourceEntrySchema$1 as rt, asString as s, SubscribeFramesInputSchema as st, sleep as t, ProfileSlotSchema as tt, parseJsonUnknown as u, makeSourceBrokerId as ut, deviceOpsCapability as v, createEvent as vt, adminUiCapability as w, collectHydratedFieldValues as wt, DeviceFeature as x, WELL_KNOWN_TABS as xt, viewerUiCapability as y, emitReadiness as yt, emitDownForOwnedCaps as z };
+export { FrameHandleFormatSchema as $, isDeviceConfigCap as A, emitDownForOwnedCaps as B, DeviceType as C, WELL_KNOWN_TAB_MAP as Ct, DEVICE_STATUS_METHOD as D, resolveHydratedFieldValue as Dt, DEVICE_SETTINGS_CONTRIBUTION_METHODS as E, hydrateSchema as Et, nodePin as F, CAM_PROFILE_ORDER as G, scopeKey as H, readNodePin as I, CamStreamResolutionSchema as J, CamProfileSchema as K, toNodeId as L, resolveCapMount as M, systemMethod as N, event as O, CAP_NODE_PIN_CONTEXT_KEY as P, EncodedPacketSchema as Q, ReadinessRegistry as R, DeviceRole as S, WELL_KNOWN_TABS as St, DEFAULT_RUNTIME_STATE_DURABILITY as T, collectHydratedFieldValues as Tt, BrokerStatsSchema as U, readinessKey as V, BrokerStatusSchema as W, DecodedAudioChunkSchema as X, CameraStreamSchema as Y, DecodedFrameSchema as Z, RawStateResultSchema as _, normalizeAddonInitResult as _t, asJsonObject as a, StreamSourceSchema as at, ChargingStatus as b, emitReadiness as bt, parseJsonArray as c, SubscribeFramesInputSchema as ct, DEVICE_SCOPED_CAPS as d, makeSourceBrokerId as dt, FrameHandleSchema as et, isDeviceScopedCap as f, parseProfileBrokerId as ft, createSliceHandle as g, BaseAddon as gt, createMirrorSource as h, DisposerChain as ht, asJsonArray as i, StreamSourceEntrySchema$1 as it, method as j, expandCapMethods as k, parseJsonObject as l, SubscribeFramesResultSchema as lt, createLazyTrpcSource as m, DATAPLANE_SECRET_HEADER as mt, sleepCancellable as n, ProfileSlotSchema as nt, asNumber as o, SubscribeAudioChunksInputSchema as ot, createDeviceProxy as p, selectAssignedProfileSlots as pt, CamStreamKindSchema as q, asBoolean as r, ProfileSlotStatusSchema as rt, asString as s, SubscribeAudioChunksResultSchema as st, sleep as t, ProfileRtspEntrySchema as tt, parseJsonUnknown as u, makeProfileBrokerId as ut, deviceOpsCapability as v, createDurableState as vt, adminUiCapability as w, collectHydratedFieldEntries as wt, DeviceFeature as x, isEvent as xt, viewerUiCapability as y, createEvent as yt, ReadinessTimeoutError as z };

package/dist/{sleep-BszXLEvP.js → sleep-Dh1EJSqF.js}

@@ -2004,6 +2004,8 @@ function readNodePin(context) {
 *   4. Addon implements IProvider
 *   5. Registry auto-mounts tRPC router from definition.methods
 */
+/** The default applied to a `runtimeState` cap that declares no `durability`. */
+var DEFAULT_RUNTIME_STATE_DURABILITY = "session";
 /**
 * Resolve the EFFECTIVE mount hint for a cap — the explicit `mount` when
 * present, else the scope/mode/deviceNative-derived default. Single source
@@ -3801,6 +3803,12 @@ Object.defineProperty(exports, "DATAPLANE_SECRET_HEADER", {
 		return DATAPLANE_SECRET_HEADER;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_RUNTIME_STATE_DURABILITY", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_RUNTIME_STATE_DURABILITY;
+	}
+});
 Object.defineProperty(exports, "DEVICE_SCOPED_CAPS", {
 	enumerable: true,
 	get: function() {

package/package.json

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