@camstack/types 1.2.63 → 1.2.65

package/dist/interfaces/addon.d.ts

@@ -1141,6 +1141,27 @@ export interface AddonExecution {
      * former hard-coded addon-name list in `process-service.ts`.
      */
     readonly heapProfile?: AddonHeapProfile;
+    /**
+     * `@camstack/system` builtin ONLY: run this builtin in its OWN forked runner
+     * instead of in-process on the hub root.
+     *
+     * The hub drops `@camstack/system` builtins from the runner plan because the
+     * infrastructure ones (storage, settings, logging, device-manager) must be
+     * resident in the process every runner depends on. That is a reason to keep
+     * THOSE in-process — not a property of the package. A builtin that owns
+     * capture, transcode and byte caches (`snapshot`) charges all of it to the
+     * event loop that also answers the tRPC API.
+     *
+     * Declaring `isolate: true` opts a single builtin out of that blanket rule:
+     * it is planned, spawned, restarted and route-mounted exactly like any other
+     * forked addon, and `resolveRunnerId` still owns its runner id (D2 — one
+     * addon, one process). Nothing else changes: the manifest entry keeps its
+     * `entry` path inside the `@camstack/system` closure, and the runner loads it
+     * from there.
+     *
+     * Ignored for non-system packages — they already fork.
+     */
+    readonly isolate?: boolean;
 }
 export type AddonHeapProfile = 'light' | 'heavy';
 export declare const DEFAULT_ADDON_PLACEMENT: AddonPlacement;
@@ -1184,6 +1205,17 @@ export declare function resolveAddonGroup(decl: Pick<AddonDeclaration, 'executio
 export declare function resolveRunnerId(decl: Pick<AddonDeclaration, 'execution'>, addonId: string): string;
 /** Convenience accessor — the resolved placement (defaults to `hub-only`). */
 export declare function resolveAddonPlacement(decl: Pick<AddonDeclaration, 'execution'>): AddonPlacement;
+/**
+ * True when a `@camstack/system` builtin opted out of the in-process rule and
+ * must be planned as a forked runner (`execution.isolate`).
+ *
+ * ONE predicate, because the hub asks this question in three places that must
+ * agree: the runner plan (`buildAddonGroupPlan`), the "does this boot
+ * in-process" filter, and `isForkedAddonEntry` (which decides route mounts,
+ * data-plane mounts, restart and uninstall). They diverged once before for
+ * `auth-oidc` and the addon's routes were mounted against an async UDS proxy.
+ */
+export declare function isIsolatedBuiltin(decl: Pick<AddonDeclaration, 'execution'>): boolean;
 /**
  * One entry of a `RunnerPlan` — an addon assigned to a runner, paired
  * with the on-disk directory the runner subprocess loads it from.

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

@@ -526,6 +526,29 @@ export interface TopologyNode {
         readonly version: string;
     } | null;
 }
+/**
+ * Why a broker's stream health flipped — the discriminator that separates an
+ * OUTAGE from an intentional state change.
+ *
+ * A `stream.offline` on its own says nothing about whether anything is wrong:
+ * the same event is fired when a camera stops sending video AND when the last
+ * consumer left and the broker suspended its dial on purpose. A consumer that
+ * reads only the category cannot tell them apart, and the Notification Center
+ * shipped exactly that bug — an operator notified that a stream went down
+ * every time nobody was watching it.
+ *
+ *  - `stale-timeout`    — no video packet for the broker's stale window
+ *    (120 s). The ONLY outage. This is what a notification may act on.
+ *  - `recovered`        — packets resumed after a `stale-timeout`. The
+ *    matching end of an outage.
+ *  - `first-packet`     — a broker's first ever packet. A stream coming up, not
+ *    a recovery: there was no outage before it.
+ *  - `suspended`        — the lazy-dial idle suspend (no demand). Deliberate.
+ *  - `resumed`          — demand returned and the dial came back. The matching
+ *    end of a `suspended`, and equally deliberate.
+ *  - `broker-destroyed` — the stream was unpublished/released. Deliberate.
+ */
+export type StreamHealthReason = 'stale-timeout' | 'recovered' | 'first-packet' | 'suspended' | 'resumed' | 'broker-destroyed';
 /** All known event categories with their typed payloads */
 export interface EventCatalog {
     'system.boot': {
@@ -1011,7 +1034,7 @@ export interface EventCatalog {
             readonly engine: PipelineEngineChoice;
             readonly modelsLoaded: readonly string[];
             readonly inUseByCameras: readonly number[];
-            readonly kind: 'runtime' | 'warm-override';
+            readonly kind: 'runtime' | 'warm-override' | 'device-pool';
             readonly poolPid: number | null;
             readonly idleMs: number | null;
             readonly idleTtlMs: number | null;
@@ -1159,6 +1182,9 @@ export interface EventCatalog {
      * (every broker is keyed by its cam stream now); `profile` is the
      * profile slot currently bound to it (or `null` if the broker is
      * only kept alive by a manual activation).
+     *
+     * `reason` is the discriminator a consumer MUST read before treating a flip
+     * as an outage — see {@link StreamHealthReason}.
      */
     'stream.online': {
         readonly deviceId: number;
@@ -1167,7 +1193,7 @@ export interface EventCatalog {
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
-        readonly reason?: string;
+        readonly reason?: StreamHealthReason;
     };
     'stream.offline': {
         readonly deviceId: number;
@@ -1176,7 +1202,7 @@ export interface EventCatalog {
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
-        readonly reason?: string;
+        readonly reason?: StreamHealthReason;
     };
     'retention.cleanup': {
         readonly deletedEvents?: number;

package/dist/interfaces/relocate.d.ts

@@ -8,7 +8,15 @@ import { z } from 'zod';
  * Each completed/failed run also lands one durable ops-log row on its owning
  * addon surface.
  */
+/**
+ * `queued` exists because the recorder mover is SINGLE-FLIGHT and an operator
+ * rebalance enqueues one job per (camera, profile). Refusing the second job —
+ * what the engine did before — turned a fifteen-camera rebalance into fifteen
+ * manual retries. Queued jobs run FIFO; a queued job that is cancelled never
+ * runs at all.
+ */
 export declare const RelocateJobStateSchema: z.ZodEnum<{
+    queued: "queued";
     done: "done";
     failed: "failed";
     running: "running";
@@ -18,6 +26,7 @@ export type RelocateJobState = z.infer<typeof RelocateJobStateSchema>;
 export declare const RelocateJobSchema: z.ZodObject<{
     jobId: z.ZodString;
     state: z.ZodEnum<{
+        queued: "queued";
         done: "done";
         failed: "failed";
         running: "running";
@@ -52,6 +61,8 @@ export declare const RelocateFootageInputSchema: z.ZodObject<{
         recordings: "recordings";
         recordingsLow: "recordingsLow";
     }>>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     throttleMbps: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RelocateFootageInput = z.infer<typeof RelocateFootageInputSchema>;
@@ -72,6 +83,8 @@ export declare const StorageMigrationFootageMoveInputSchema: z.ZodObject<{
         recordings: "recordings";
         recordingsLow: "recordingsLow";
     }>>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     throttleMbps: z.ZodOptional<z.ZodNumber>;
     leaseId: z.ZodString;
 }, z.core.$strip>;
@@ -147,6 +160,7 @@ export declare const StorageMigrationMoveSchema: z.ZodObject<{
     toLocationId: z.ZodString;
     moverJobId: z.ZodNullable<z.ZodString>;
     state: z.ZodNullable<z.ZodEnum<{
+        queued: "queued";
         done: "done";
         failed: "failed";
         running: "running";
@@ -185,6 +199,7 @@ export declare const StorageMigrationJobSchema: z.ZodObject<{
         toLocationId: z.ZodString;
         moverJobId: z.ZodNullable<z.ZodString>;
         state: z.ZodNullable<z.ZodEnum<{
+            queued: "queued";
             done: "done";
             failed: "failed";
             running: "running";

package/dist/interfaces/stream-broker.d.ts

@@ -265,6 +265,20 @@ export interface IStreamBroker {
      * `H265Repacketizer` once the camera's first RTP+SDP arrive.
      */
     onSdpParameterSets(callback: (ps: ReadonlyArray<Buffer>) => void): Unsubscribe;
+    /**
+     * Subscribe to SOURCE RESTARTS — every dial after the first, carrying a
+     * short reason (`dial#2`, …). The WebRTC server subscribes for EVERY
+     * session shape (RTP passthrough, AnnexB, transcode): each holds parameter
+     * sets and a bootstrap latch belonging to the connection that ended, so a
+     * re-dial must re-sync them rather than leave the session decoding against
+     * a dead mapping.
+     *
+     * Fires on the DIAL, not on the first packet: a restart that never delivers
+     * must still be observable rather than silently indistinguishable from a
+     * healthy stream. The returned function detaches ONE subscriber (a broker
+     * fans out to many live sessions).
+     */
+    onSourceRestart(observer: (reason: string) => void): Unsubscribe;
     /**
      * Source type as configured at `start()` — see `StreamSourceType`
      * for the supported values. `null` before `start()` resolves.

package/dist/notification/timelapse-rule.d.ts

@@ -28,6 +28,35 @@ export declare const TimelapseTemplateSchema: z.ZodObject<{
     body: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TimelapseTemplate = z.infer<typeof TimelapseTemplateSchema>;
+/**
+ * Floor on any dense cadence, seconds — the recording's own frame interval.
+ *
+ * Declared here because it bounds BOTH the rule field and the renderer's
+ * derivation, and two copies of a floor are two floors that can drift.
+ */
+export declare const TIMELAPSE_DENSE_FLOOR_SEC = 0.1;
+/**
+ * Whether the notification's preview is a STILL or a short animation.
+ *
+ * The operator's ask, verbatim: *"inviato come gif o video (come per le altre
+ * rule)"* — his Scrypted advanced-notifier has a `gifRule`, and a ten-hour
+ * night reads better as three seconds of motion than as one frame of it. Both
+ * modes get the SAME treatment (blurred frame, large centred title); `'gif'`
+ * simply applies it to a dozen frames sampled across the render and assembles
+ * them.
+ *
+ * `'image'` is the default and stays the default: a GIF costs a dozen ffmpeg
+ * seeks and a palette pass, and no rule that never asked for one should start
+ * paying that on the deploy that shipped it.
+ *
+ * A GIF that cannot be assembled DEGRADES to the still — never to nothing.
+ */
+declare const PreviewModeField: z.ZodEnum<{
+    image: "image";
+    gif: "gif";
+}>;
+/** Still or animation — the rule field, as a type the renderer can take. */
+export type TimelapsePreviewMode = z.infer<typeof PreviewModeField>;
 /**
  * Client-supplied timelapse-rule fields. The server stamps id / createdBy /
  * createdAt / updatedAt / ownerUserId / lastGeneratedAt — none of them appear
@@ -48,6 +77,8 @@ export declare const TimelapseRuleInputSchema: z.ZodObject<{
     }, z.core.$strip>;
     cadenceSec: z.ZodDefault<z.ZodNumber>;
     framerate: z.ZodDefault<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -56,9 +87,23 @@ export declare const TimelapseRuleInputSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type TimelapseRuleInput = z.infer<typeof TimelapseRuleInputSchema>;
+/**
+ * The caption a rule that never set one gets.
+ *
+ * Rendered through the ordinary `{{var}}` pass at delivery, so a rule created
+ * before this field existed still reads "Timelapse Videocamera ingresso" and
+ * not the literal braces.
+ */
+export declare const DEFAULT_TIMELAPSE_PREVIEW_TEXT = "Timelapse {{camera}}";
 /**
  * Partial patch for an update — any subset of the INPUT fields, with NO
  * defaults (an absent key means "leave unchanged", never "reset to default").
@@ -90,6 +135,8 @@ export declare const TimelapseRulePatchSchema: z.ZodObject<{
     }, z.core.$strip>>;
     cadenceSec: z.ZodOptional<z.ZodNumber>;
     framerate: z.ZodOptional<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -98,6 +145,12 @@ export declare const TimelapseRulePatchSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type TimelapseRulePatch = z.infer<typeof TimelapseRulePatchSchema>;
@@ -117,6 +170,8 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
     }, z.core.$strip>;
     cadenceSec: z.ZodDefault<z.ZodNumber>;
     framerate: z.ZodDefault<z.ZodNumber>;
+    denseCadenceSec: z.ZodOptional<z.ZodNumber>;
+    minDwellSec: z.ZodOptional<z.ZodNumber>;
     targets: z.ZodArray<z.ZodObject<{
         targetId: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -125,6 +180,12 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         body: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    previewText: z.ZodOptional<z.ZodString>;
+    previewMode: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        gif: "gif";
+    }>>;
+    reportClasses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     priority: z.ZodDefault<z.ZodNumber>;
     id: z.ZodString;
     ownerUserId: z.ZodOptional<z.ZodString>;
@@ -135,6 +196,27 @@ export declare const TimelapseRuleSchema: z.ZodObject<{
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type TimelapseRule = z.infer<typeof TimelapseRuleSchema>;
+/** The cadence pair a rule must satisfy — the guard's whole input. */
+export interface TimelapseCadencePair {
+    readonly cadenceSec: number;
+    readonly denseCadenceSec?: number;
+}
+/**
+ * Refuse a dense cadence that is not denser than the base.
+ *
+ * Called at UPSERT, on the MERGED rule — a patch that lowers `cadenceSec`
+ * alone can invalidate a `denseCadenceSec` set months earlier, so checking the
+ * patch in isolation would let the bad pair through.
+ *
+ * Refusing here and not at render time is the whole point: `ExportTimelapseSchema`
+ * also rejects the pair, but it does so when the window has already closed and
+ * the footage is being cut — the operator learns at 06:05 that last night was
+ * never going to render, and a closed window does not come back. This turns
+ * that into a failed edit he can see and correct.
+ *
+ * @throws Error naming both numbers, so the message is actionable in a toast.
+ */
+export declare function assertTimelapseCadences(pair: TimelapseCadencePair): void;
 /**
  * The last successful generation for ONE camera of a rule, epoch-ms.
  *
@@ -148,3 +230,4 @@ export type TimelapseRule = z.infer<typeof TimelapseRuleSchema>;
  * entire rule set once.
  */
 export declare function readTimelapseGeneratedAt(rule: Pick<TimelapseRule, 'lastGeneratedAt' | 'generatedByDevice'>, deviceId: number): number;
+export {};

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

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