@ceralive/cerastream 2026.7.3 → 2026.7.5

package/README.md

@@ -6,12 +6,14 @@ engine's JSON-RPC 2.0 / NDJSON control plane over a Unix domain socket.
 
 - JSON-RPC 2.0 envelope + `hello` handshake schemas
 - The eight v1 control methods (Zod params + result schemas + inferred types)
-- The eight server-push event payloads (discriminated union)
+- The nine server-push event payloads (discriminated union)
 - Two-tier error codes (RPC + runtime)
 - A unified engine config schema (= `start` params)
 - A `CerastreamClient` interface + `connect()` factory (UDS transport)
 - Additive `client.getCapabilities()` discovery for platform, source, encoder, and
   local preview availability
+- Additive `client.changeConfig()` — reconfigure the live session (resolution,
+  framerate, codec, pipeline, source) as one transaction with typed rollback
 
 The Zod schemas, types, and constants are the frozen wire contract; `connect()`
 drives that contract over an NDJSON/UDS transport with no native dependencies.

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type HelloResult } from "./envelope.js";
 import { type EventParams } from "./events.js";
-import { type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from "./messages.js";
+import { type ChangeConfigParams, type ChangeConfigResult, type GetCapabilitiesResult, type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from "./messages.js";
 /** Options for {@link connect}. All optional — `connect({})` is valid. */
 export interface ConnectOptions {
     /** Control socket path override. Defaults to the resolved /run/cerastream/control.sock. */
@@ -82,6 +82,20 @@ export interface CerastreamClient {
      * availability. This request intentionally sits outside the frozen v1 map.
      */
     getCapabilities(): Promise<GetCapabilitiesResult>;
+    /**
+     * Reconfigure the LIVE session as one transaction (resolution, framerate,
+     * codec, pipeline, source). Also sits outside the frozen v1 map.
+     *
+     * Resolves for every phase the transaction reached — including
+     * `rollback_failed`, an honest terminal outcome. Callers must branch on
+     * `result.phase`, not on whether the promise settled. The engine's declared
+     * worst-case transaction bound is 65 000 ms, so size any caller-side deadline
+     * from that, not from the default per-request timeout.
+     * @param params A delta of the live config; absent field ⇒ keep live value.
+     * @throws {CerastreamRpcError} ONLY when the transaction never started (not
+     * streaming, a concurrent change, or an empty/invalid delta).
+     */
+    changeConfig(params: ChangeConfigParams): Promise<ChangeConfigResult>;
     /**
      * Subscribe to the live event stream; `handler` fires for each pushed event.
      * @param params The topics to subscribe to (absent ⇒ all topics).

package/dist/client.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import { CerastreamConnectionError, CerastreamRpcError, CerastreamTimeoutError, } from "./errors.js";
 import { eventParamsSchema } from "./events.js";
 import { controlSocketPath } from "./paths.js";
-import { getCapabilitiesResultSchema, requestSchemas, } from "./messages.js";
+import { changeConfigParamsSchema, changeConfigResultSchema, getCapabilitiesResultSchema, requestSchemas, } from "./messages.js";
 import { LineSocket } from "./transport.js";
 const DEFAULTS = {
     requestTimeoutMs: 10_000,
@@ -82,6 +82,9 @@ class ClientImpl {
     async getCapabilities() {
         return getCapabilitiesResultSchema.parse(await this.rawRequest("get-capabilities", undefined));
     }
+    async changeConfig(params) {
+        return changeConfigResultSchema.parse(await this.rawRequest("change-config", changeConfigParamsSchema.parse(params)));
+    }
     previewSession(params) {
         return this.call("preview-session", params);
     }

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ export declare const PROTOCOL_VERSION: "cerastream-ipc/1";
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export declare const SCHEMA_VERSION: "0.8.0";
+export declare const SCHEMA_VERSION: "0.11.0";
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export declare const DEFAULT_IPC_DIR: "/run/cerastream";
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
@@ -63,7 +63,7 @@ export declare const PROFILE_CATALOG_VERSION: "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export declare const ENGINE_FEATURES: readonly ["video-passthrough"];
+export declare const ENGINE_FEATURES: readonly ["video-passthrough", "input-mode"];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export declare const CERASTREAM_BIN: "cerastream";
 export declare const DEFAULT_MIN_BITRATE = 300;

package/dist/constants.js

@@ -11,7 +11,7 @@ export const PROTOCOL_VERSION = "cerastream-ipc/1";
  * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
  * only moves when the wire schema itself does, in lockstep across both languages.
  */
-export const SCHEMA_VERSION = "0.8.0";
+export const SCHEMA_VERSION = "0.11.0";
 /** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
 export const DEFAULT_IPC_DIR = "/run/cerastream";
 /** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
@@ -72,7 +72,7 @@ export const PROFILE_CATALOG_VERSION = "1.0.0";
  * ignores the field) never applies a semantic the caller assumed. Mirrors the
  * Rust `ENGINE_FEATURES`.
  */
-export const ENGINE_FEATURES = ["video-passthrough"];
+export const ENGINE_FEATURES = ["video-passthrough", "input-mode"];
 /** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
 export const CERASTREAM_BIN = "cerastream";
 // ---- config defaults (mirror ceracoder, the engine being replaced) ----

package/dist/errors.d.ts

@@ -88,8 +88,21 @@ export declare const processErrorCodeSchema: z.ZodEnum<{
     pipeline_stall: "pipeline_stall";
     srt_connect_failed: "srt_connect_failed";
     srt_connection_lost: "srt_connection_lost";
+    capture_unrecoverable: "capture_unrecoverable";
 }>;
 export type ProcessErrorCode = z.infer<typeof processErrorCodeSchema>;
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export declare const captureUnrecoverableReasonSchema: z.ZodEnum<{
+    node_absent_reprobe_disabled: "node_absent_reprobe_disabled";
+    reprobe_no_reenumeration: "reprobe_no_reenumeration";
+    reprobe_identity_changed: "reprobe_identity_changed";
+    reprobe_node_still_absent: "reprobe_node_still_absent";
+    reprobe_unavailable: "reprobe_unavailable";
+}>;
+export type CaptureUnrecoverableReason = z.infer<typeof captureUnrecoverableReasonSchema>;
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export declare const processErrorSourceSchema: z.ZodEnum<{
     srtla: "srtla";

package/dist/errors.js

@@ -124,6 +124,21 @@ export const processErrorCodeSchema = z.enum([
     "pipeline_stall",
     "srt_connect_failed",
     "srt_connection_lost",
+    // TERMINAL, unlike capture_video_error: the device is still on the bus but the
+    // engine has exhausted recovery, so a UI that keeps showing "reconnecting"
+    // would be lying. Always carries a captureUnrecoverableReasonSchema `reason`.
+    "capture_unrecoverable",
+]);
+/**
+ * Why a capture device became `capture_unrecoverable` — the `reason` field of the
+ * `error` event. Mirrors the Rust `CaptureUnrecoverableReason`.
+ */
+export const captureUnrecoverableReasonSchema = z.enum([
+    "node_absent_reprobe_disabled",
+    "reprobe_no_reenumeration",
+    "reprobe_identity_changed",
+    "reprobe_node_still_absent",
+    "reprobe_unavailable",
 ]);
 /** Origin of a Tier 2 runtime error (the notification channel CeraUI routes on). */
 export const processErrorSourceSchema = z.enum(["srtla", "engine"]);

package/dist/events.d.ts

@@ -115,6 +115,25 @@ export declare const deviceEventSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -124,6 +143,8 @@ export declare const deviceEventSchema: z.ZodObject<{
             onboard: "onboard";
         }>>;
         stable_id: z.ZodOptional<z.ZodString>;
+        physical_group_id: z.ZodOptional<z.ZodString>;
+        hardware_serial: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 /** Payload of a {@link deviceEventSchema} event. */
@@ -162,12 +183,14 @@ export declare const runtimeErrorEventSchema: z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Payload of a {@link runtimeErrorEventSchema} event. */
 export type RuntimeErrorEvent = z.infer<typeof runtimeErrorEventSchema>;
@@ -214,6 +237,28 @@ export declare const audioLevelEventSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Payload of a {@link audioLevelEventSchema} event. */
 export type AudioLevelEvent = z.infer<typeof audioLevelEventSchema>;
+/**
+ * `config-change` event — one phase of a `change-config` transaction (0.10.0,
+ * additive Todo 9). Exactly one `applying` at entry, then exactly ONE terminal
+ * phase for the same `attempt_id` (which the RPC result also echoes, so a caller
+ * that missed an event can still correlate). A terminal phase is published only
+ * after the outcome gate resolved, so `applied` means "PLAYING **and** frames
+ * actually advancing", never merely "PLAYING".
+ */
+export declare const configChangeEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"config-change">;
+    seq: z.ZodNumber;
+    attempt_id: z.ZodString;
+    phase: z.ZodEnum<{
+        applying: "applying";
+        applied: "applied";
+        reverted: "reverted";
+        rollback_failed: "rollback_failed";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Payload of a {@link configChangeEventSchema} event. */
+export type ConfigChangeEvent = z.infer<typeof configChangeEventSchema>;
 /** Discriminated union of every v1 event payload (the inner `params`). */
 export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"status">;
@@ -288,6 +333,25 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -297,6 +361,8 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             onboard: "onboard";
         }>>;
         stable_id: z.ZodOptional<z.ZodString>;
+        physical_group_id: z.ZodOptional<z.ZodString>;
+        hardware_serial: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"bitrate">;
@@ -320,12 +386,14 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         pipeline_stall: "pipeline_stall";
         srt_connect_failed: "srt_connect_failed";
         srt_connection_lost: "srt_connection_lost";
+        capture_unrecoverable: "capture_unrecoverable";
     }>;
     source: z.ZodEnum<{
         srtla: "srtla";
         engine: "engine";
     }>;
     reason: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"preview">;
     seq: z.ZodNumber;
@@ -352,6 +420,17 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         mode_none: "mode_none";
         handoff: "handoff";
     }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"config-change">;
+    seq: z.ZodNumber;
+    attempt_id: z.ZodString;
+    phase: z.ZodEnum<{
+        applying: "applying";
+        applied: "applied";
+        reverted: "reverted";
+        rollback_failed: "rollback_failed";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
 export type EventParams = z.infer<typeof eventParamsSchema>;
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
@@ -431,6 +510,25 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -440,6 +538,8 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 onboard: "onboard";
             }>>;
             stable_id: z.ZodOptional<z.ZodString>;
+            physical_group_id: z.ZodOptional<z.ZodString>;
+            hardware_serial: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"bitrate">;
@@ -463,12 +563,14 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"preview">;
         seq: z.ZodNumber;
@@ -495,12 +597,24 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             mode_none: "mode_none";
             handoff: "handoff";
         }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"config-change">;
+        seq: z.ZodNumber;
+        attempt_id: z.ZodString;
+        phase: z.ZodEnum<{
+            applying: "applying";
+            applied: "applied";
+            reverted: "reverted";
+            rollback_failed: "rollback_failed";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "type">;
 }, z.core.$strip>;
 export type CerastreamEvent = z.infer<typeof cerastreamEventSchema>;
-/** The eight event topics (schema.md "Events" table) — count-assertion source.
- * `audio-level` is additive (Todo 21) and appended last, preserving order. */
-export declare const EVENT_TOPICS: readonly ["status", "switch", "device", "bitrate", "srt-stats", "error", "preview", "audio-level"];
+/** The nine event topics (schema.md "Events" table) — count-assertion source.
+ * `audio-level` (Todo 21) and `config-change` (Todo 9) are additive and appended
+ * last, preserving the order of every prior topic. */
+export declare const EVENT_TOPICS: readonly ["status", "switch", "device", "bitrate", "srt-stats", "error", "preview", "audio-level", "config-change"];
 export type EventTopicName = (typeof EVENT_TOPICS)[number];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export declare const eventSchemas: {
@@ -579,6 +693,25 @@ export declare const eventSchemas: {
                 test: "test";
                 network: "network";
             }>>;
+            modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                media_type: z.ZodString;
+                pipeline_kind: z.ZodEnum<{
+                    audio: "audio";
+                    hdmi: "hdmi";
+                    uvc_h264: "uvc_h264";
+                    uvc_h265: "uvc_h265";
+                    mjpeg: "mjpeg";
+                    camlink: "camlink";
+                    test: "test";
+                    network: "network";
+                }>;
+                caps: z.ZodArray<z.ZodObject<{
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    framerate: z.ZodOptional<z.ZodString>;
+                    media_type: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
             product_name: z.ZodOptional<z.ZodString>;
             transport: z.ZodOptional<z.ZodEnum<{
@@ -588,6 +721,8 @@ export declare const eventSchemas: {
                 onboard: "onboard";
             }>>;
             stable_id: z.ZodOptional<z.ZodString>;
+            physical_group_id: z.ZodOptional<z.ZodString>;
+            hardware_serial: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
     readonly bitrate: z.ZodObject<{
@@ -614,12 +749,14 @@ export declare const eventSchemas: {
             pipeline_stall: "pipeline_stall";
             srt_connect_failed: "srt_connect_failed";
             srt_connection_lost: "srt_connection_lost";
+            capture_unrecoverable: "capture_unrecoverable";
         }>;
         source: z.ZodEnum<{
             srtla: "srtla";
             engine: "engine";
         }>;
         reason: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     readonly preview: z.ZodObject<{
         type: z.ZodLiteral<"preview">;
@@ -649,4 +786,16 @@ export declare const eventSchemas: {
             handoff: "handoff";
         }>>;
     }, z.core.$strip>;
+    readonly "config-change": z.ZodObject<{
+        type: z.ZodLiteral<"config-change">;
+        seq: z.ZodNumber;
+        attempt_id: z.ZodString;
+        phase: z.ZodEnum<{
+            applying: "applying";
+            applied: "applied";
+            reverted: "reverted";
+            rollback_failed: "rollback_failed";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
 };

package/dist/events.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { processErrorCodeSchema, processErrorSourceSchema, } from "./errors.js";
-import { captureDeviceSchema, inputModeSchema, mediaClassSchema, streamStateSchema, } from "./types.js";
+import { captureDeviceSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, streamStateSchema, } from "./types.js";
 // Server → client `event` notifications, delivered after `subscribe-events`
 // (schema.md "Events"). Each event is the inner `params` of an rpcEventSchema:
 // { type, seq, … }. `type` discriminates; `seq` is a per-type monotonic counter.
@@ -93,6 +93,7 @@ export const runtimeErrorEventSchema = z.object({
     code: processErrorCodeSchema, // Tier 2 (errors.ts)
     source: processErrorSourceSchema,
     reason: z.string().optional(), // structured replacement for the stderr <reason>
+    selected: z.boolean().optional(), // additive (0.11.0): the degraded input is the operator's OWN selection, so the stream will not move itself and only they can pick another — a materially different operator response than a degraded non-selected input, and one to branch on rather than string-match. Absent ⇒ false
 });
 /** `preview` event — a preview-session lifecycle/phase change. */
 export const previewEventSchema = z.object({
@@ -127,6 +128,21 @@ export const audioLevelEventSchema = z.object({
     unavailable: z.literal(true).optional(),
     reason: z.enum(["device_busy", "no_device", "mode_none", "handoff"]).optional(),
 });
+/**
+ * `config-change` event — one phase of a `change-config` transaction (0.10.0,
+ * additive Todo 9). Exactly one `applying` at entry, then exactly ONE terminal
+ * phase for the same `attempt_id` (which the RPC result also echoes, so a caller
+ * that missed an event can still correlate). A terminal phase is published only
+ * after the outcome gate resolved, so `applied` means "PLAYING **and** frames
+ * actually advancing", never merely "PLAYING".
+ */
+export const configChangeEventSchema = z.object({
+    type: z.literal("config-change"),
+    seq,
+    attempt_id: z.string(),
+    phase: configChangePhaseSchema,
+    reason: z.string().optional(), // absent on applying/applied; "teardown_timeout" marks the supervisor escalation
+});
 /** Discriminated union of every v1 event payload (the inner `params`). */
 export const eventParamsSchema = z.discriminatedUnion("type", [
     statusEventSchema,
@@ -137,6 +153,7 @@ export const eventParamsSchema = z.discriminatedUnion("type", [
     runtimeErrorEventSchema,
     previewEventSchema,
     audioLevelEventSchema,
+    configChangeEventSchema,
 ]);
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
 export const cerastreamEventSchema = z.object({
@@ -144,8 +161,9 @@ export const cerastreamEventSchema = z.object({
     method: z.literal("event"),
     params: eventParamsSchema,
 });
-/** The eight event topics (schema.md "Events" table) — count-assertion source.
- * `audio-level` is additive (Todo 21) and appended last, preserving order. */
+/** The nine event topics (schema.md "Events" table) — count-assertion source.
+ * `audio-level` (Todo 21) and `config-change` (Todo 9) are additive and appended
+ * last, preserving the order of every prior topic. */
 export const EVENT_TOPICS = [
     "status",
     "switch",
@@ -155,6 +173,7 @@ export const EVENT_TOPICS = [
     "error",
     "preview",
     "audio-level",
+    "config-change",
 ];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export const eventSchemas = {
@@ -166,4 +185,5 @@ export const eventSchemas = {
     error: runtimeErrorEventSchema,
     preview: previewEventSchema,
     "audio-level": audioLevelEventSchema,
+    "config-change": configChangeEventSchema,
 };

package/dist/messages.d.ts

@@ -42,6 +42,16 @@ export declare const startParamsSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -83,6 +93,7 @@ export declare const reloadConfigParamsSchema: z.ZodObject<{
     audio: z.ZodOptional<z.ZodObject<{
         delay_ms: z.ZodOptional<z.ZodNumber>;
         delay_ms_signed: z.ZodOptional<z.ZodNumber>;
+        meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ReloadConfigParams = z.infer<typeof reloadConfigParamsSchema>;
@@ -103,6 +114,7 @@ export declare const reloadConfigResultSchema: z.ZodObject<{
         audio: z.ZodOptional<z.ZodObject<{
             delay_ms: z.ZodOptional<z.ZodNumber>;
             delay_ms_signed: z.ZodOptional<z.ZodNumber>;
+            meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     bitrate_control: z.ZodOptional<z.ZodEnum<{
@@ -191,6 +203,25 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             test: "test";
             network: "network";
         }>>;
+        modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            media_type: z.ZodString;
+            pipeline_kind: z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>;
+            caps: z.ZodArray<z.ZodObject<{
+                width: z.ZodOptional<z.ZodNumber>;
+                height: z.ZodOptional<z.ZodNumber>;
+                framerate: z.ZodOptional<z.ZodString>;
+                media_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
         product_name: z.ZodOptional<z.ZodString>;
         transport: z.ZodOptional<z.ZodEnum<{
@@ -200,6 +231,8 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             onboard: "onboard";
         }>>;
         stable_id: z.ZodOptional<z.ZodString>;
+        physical_group_id: z.ZodOptional<z.ZodString>;
+        hardware_serial: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ListDevicesResult = z.infer<typeof listDevicesResultSchema>;
@@ -212,6 +245,7 @@ export declare const eventTopicSchema: z.ZodEnum<{
     "srt-stats": "srt-stats";
     preview: "preview";
     "audio-level": "audio-level";
+    "config-change": "config-change";
 }>;
 export type EventTopic = z.infer<typeof eventTopicSchema>;
 export declare const subscribeEventsParamsSchema: z.ZodObject<{
@@ -224,6 +258,7 @@ export declare const subscribeEventsParamsSchema: z.ZodObject<{
         "srt-stats": "srt-stats";
         preview: "preview";
         "audio-level": "audio-level";
+        "config-change": "config-change";
     }>>>;
 }, z.core.$strip>;
 export type SubscribeEventsParams = z.infer<typeof subscribeEventsParamsSchema>;
@@ -237,6 +272,7 @@ export declare const subscribeEventsResultSchema: z.ZodObject<{
         "srt-stats": "srt-stats";
         preview: "preview";
         "audio-level": "audio-level";
+        "config-change": "config-change";
     }>>;
 }, z.core.$strip>;
 export type SubscribeEventsResult = z.infer<typeof subscribeEventsResultSchema>;
@@ -373,6 +409,52 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
     features: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type GetCapabilitiesResult = z.infer<typeof getCapabilitiesResultSchema>;
+export declare const changeConfigParamsSchema: z.ZodObject<{
+    pipeline: z.ZodOptional<z.ZodString>;
+    resolution: z.ZodOptional<z.ZodString>;
+    framerate: z.ZodOptional<z.ZodNumber>;
+    codec: z.ZodOptional<z.ZodEnum<{
+        h264: "h264";
+        h265: "h265";
+    }>>;
+    input_id: z.ZodOptional<z.ZodString>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
+}, z.core.$strip>;
+export type ChangeConfigParams = z.infer<typeof changeConfigParamsSchema>;
+export declare const changeConfigResultSchema: z.ZodObject<{
+    attempt_id: z.ZodString;
+    phase: z.ZodEnum<{
+        applying: "applying";
+        applied: "applied";
+        reverted: "reverted";
+        rollback_failed: "rollback_failed";
+    }>;
+    state: z.ZodEnum<{
+        idle: "idle";
+        starting: "starting";
+        streaming: "streaming";
+        stopping: "stopping";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChangeConfigResult = z.infer<typeof changeConfigResultSchema>;
+/**
+ * The `reason` a `rollback_failed` carries when a teardown deadline overran.
+ * A TERMINAL supervisor escalation, not an ordinary failure: the engine could not
+ * prove the old session released its capture devices within the bound, so it
+ * refuses to build a second session that would race it. Mirrors the Rust
+ * `REASON_TEARDOWN_TIMEOUT`; consumers render it distinctly.
+ */
+export declare const REASON_TEARDOWN_TIMEOUT: "teardown_timeout";
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
 export declare const V1_METHODS: readonly ["start", "stop", "reload-config", "set-bitrate", "switch-input", "list-devices", "subscribe-events", "preview-session"];
 export type V1Method = (typeof V1_METHODS)[number];
@@ -437,6 +519,16 @@ export declare const requestSchemas: {
                 force: "force";
                 off: "off";
             }>>;
+            input_mode: z.ZodOptional<z.ZodEnum<{
+                audio: "audio";
+                hdmi: "hdmi";
+                uvc_h264: "uvc_h264";
+                uvc_h265: "uvc_h265";
+                mjpeg: "mjpeg";
+                camlink: "camlink";
+                test: "test";
+                network: "network";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -478,6 +570,7 @@ export declare const requestSchemas: {
             audio: z.ZodOptional<z.ZodObject<{
                 delay_ms: z.ZodOptional<z.ZodNumber>;
                 delay_ms_signed: z.ZodOptional<z.ZodNumber>;
+                meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -497,6 +590,7 @@ export declare const requestSchemas: {
                 audio: z.ZodOptional<z.ZodObject<{
                     delay_ms: z.ZodOptional<z.ZodNumber>;
                     delay_ms_signed: z.ZodOptional<z.ZodNumber>;
+                    meter_device: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>;
             bitrate_control: z.ZodOptional<z.ZodEnum<{
@@ -569,6 +663,25 @@ export declare const requestSchemas: {
                     test: "test";
                     network: "network";
                 }>>;
+                modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    media_type: z.ZodString;
+                    pipeline_kind: z.ZodEnum<{
+                        audio: "audio";
+                        hdmi: "hdmi";
+                        uvc_h264: "uvc_h264";
+                        uvc_h265: "uvc_h265";
+                        mjpeg: "mjpeg";
+                        camlink: "camlink";
+                        test: "test";
+                        network: "network";
+                    }>;
+                    caps: z.ZodArray<z.ZodObject<{
+                        width: z.ZodOptional<z.ZodNumber>;
+                        height: z.ZodOptional<z.ZodNumber>;
+                        framerate: z.ZodOptional<z.ZodString>;
+                        media_type: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
                 alsa_card_id: z.ZodOptional<z.ZodString>;
                 product_name: z.ZodOptional<z.ZodString>;
                 transport: z.ZodOptional<z.ZodEnum<{
@@ -578,6 +691,8 @@ export declare const requestSchemas: {
                     onboard: "onboard";
                 }>>;
                 stable_id: z.ZodOptional<z.ZodString>;
+                physical_group_id: z.ZodOptional<z.ZodString>;
+                hardware_serial: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>;
     };
@@ -592,6 +707,7 @@ export declare const requestSchemas: {
                 "srt-stats": "srt-stats";
                 preview: "preview";
                 "audio-level": "audio-level";
+                "config-change": "config-change";
             }>>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -604,6 +720,7 @@ export declare const requestSchemas: {
                 "srt-stats": "srt-stats";
                 preview: "preview";
                 "audio-level": "audio-level";
+                "config-change": "config-change";
             }>>;
         }, z.core.$strip>;
     };

package/dist/messages.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AUDIO_DELAY_MAX_MS } from "./constants.js";
 import { helloParamsSchema, helloResultSchema, } from "./envelope.js";
-import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceSchema, cerastreamConfigSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, } from "./types.js";
+import { balancerAlgorithmSchema, bitrateControlSchema, captureDeviceKindSchema, captureDeviceSchema, cerastreamConfigSchema, configChangePhaseSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, videoCodecSchema, } from "./types.js";
 // The eight v1 control methods (schema.md "v1 messages"). Each is matched
 // byte-for-byte to schema.md: the JSON shape on the wire is the contract.
 // ---- 1. start ----
@@ -39,6 +39,10 @@ export const reloadConfigParamsSchema = z.object({
         .object({
         delay_ms: z.number().int().min(0).max(AUDIO_DELAY_MAX_MS).optional(), // legacy unsigned; kept for 0.3.0 callers
         delay_ms_signed: z.number().int().optional(), // signed sibling; clamped at apply, so unbounded
+        // additive (0.9.0): idle-meter card preference — absent leaves it unchanged,
+        // `null` restores the engine's auto-pick, `hw:CARD=…` prefers that card
+        // (a preference, not a pin: a card that never delivers is still demoted)
+        meter_device: z.string().nullable().optional(),
     })
         .optional(),
 });
@@ -100,6 +104,7 @@ export const eventTopicSchema = z.enum([
     "error",
     "preview",
     "audio-level",
+    "config-change",
 ]);
 export const subscribeEventsParamsSchema = z.object({
     topics: z.array(eventTopicSchema).optional(), // default: all topics
@@ -188,6 +193,49 @@ export const getCapabilitiesResultSchema = z.object({
     network_embedded_audio: z.boolean().optional(), // engine routes network-ingest embedded audio to the mux
     features: z.array(z.string()).optional(), // named engine features (e.g. "video-passthrough") for fail-closed negotiation
 });
+// ---- 10. change-config (0.10.0, additive) ----
+// Deliberately absent from V1_METHODS / requestSchemas, like get-capabilities and
+// switch-audio, so the frozen eight-method contract count stays eight. Params are
+// a DELTA of startParamsSchema: absent ⇒ keep the live value. An empty delta is
+// refused with `cerastream.params.invalid` — a no-op that restarted the pipeline
+// would be the worst possible outcome. `input_id` rides the transaction, so a
+// source change renegotiates caps instead of going through `switch-input`.
+export const changeConfigParamsSchema = z
+    .object({
+    pipeline: z.string().optional(),
+    resolution: z.string().optional(), // "WxH" pixels, e.g. "3840x2160"
+    framerate: z.number().optional(),
+    codec: videoCodecSchema.optional(),
+    input_id: z.string().optional(),
+    // Switching a LIVE device between a libuvc family (uvc_h264/uvc_h265) and
+    // the v4l2 mjpeg family is NOT a plain rebuild: libuvc detaches uvcvideo, so
+    // the /dev/videoN node the mjpeg leg needs does not exist until the hold is
+    // released — and it then returns asynchronously, possibly renumbered. The
+    // engine runs a release → re-enumeration-barrier → open transaction and
+    // rolls back honestly (reason: mode_barrier_timeout) if the barrier expires.
+    input_mode: captureDeviceKindSchema.optional(),
+})
+    .refine((delta) => Object.keys(delta).length > 0, {
+    message: "change-config delta must carry at least one field",
+});
+// `Ok` for every phase the transaction actually reached — INCLUDING
+// `rollback_failed`, an honest terminal outcome rather than an RPC fault. A
+// Tier-1 error means the transaction never started, so a caller can tell
+// "nothing happened" from "something happened and here is what".
+export const changeConfigResultSchema = z.object({
+    attempt_id: z.string(), // correlates with every config-change event of the attempt
+    phase: configChangePhaseSchema, // the TERMINAL phase reached
+    state: streamStateSchema, // streaming for applied/reverted, idle for rollback_failed
+    reason: z.string().optional(), // machine-stable cause on a non-applied phase
+});
+/**
+ * The `reason` a `rollback_failed` carries when a teardown deadline overran.
+ * A TERMINAL supervisor escalation, not an ordinary failure: the engine could not
+ * prove the old session released its capture devices within the bound, so it
+ * refuses to build a second session that would race it. Mirrors the Rust
+ * `REASON_TEARDOWN_TIMEOUT`; consumers render it distinctly.
+ */
+export const REASON_TEARDOWN_TIMEOUT = "teardown_timeout";
 // ---- method registry (count-assertion source of truth) ----
 /** The eight v1 control methods (the literal JSON-RPC `method` strings). */
 export const V1_METHODS = [

package/dist/types.d.ts

@@ -61,6 +61,13 @@ export declare const deviceTransportSchema: z.ZodEnum<{
     onboard: "onboard";
 }>;
 export type DeviceTransport = z.infer<typeof deviceTransportSchema>;
+export declare const configChangePhaseSchema: z.ZodEnum<{
+    applying: "applying";
+    applied: "applied";
+    reverted: "reverted";
+    rollback_failed: "rollback_failed";
+}>;
+export type ConfigChangePhase = z.infer<typeof configChangePhaseSchema>;
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export declare const srtConfigSchema: z.ZodObject<{
     host: z.ZodString;
@@ -157,6 +164,16 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
         force: "force";
         off: "off";
     }>>;
+    input_mode: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -173,6 +190,26 @@ export declare const captureCapSchema: z.ZodObject<{
     media_type: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureCap = z.infer<typeof captureCapSchema>;
+export declare const captureModeSchema: z.ZodObject<{
+    media_type: z.ZodString;
+    pipeline_kind: z.ZodEnum<{
+        audio: "audio";
+        hdmi: "hdmi";
+        uvc_h264: "uvc_h264";
+        uvc_h265: "uvc_h265";
+        mjpeg: "mjpeg";
+        camlink: "camlink";
+        test: "test";
+        network: "network";
+    }>;
+    caps: z.ZodArray<z.ZodObject<{
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        framerate: z.ZodOptional<z.ZodString>;
+        media_type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CaptureMode = z.infer<typeof captureModeSchema>;
 export declare const captureDeviceSchema: z.ZodObject<{
     input_id: z.ZodString;
     device_path: z.ZodString;
@@ -197,6 +234,25 @@ export declare const captureDeviceSchema: z.ZodObject<{
         test: "test";
         network: "network";
     }>>;
+    modes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        media_type: z.ZodString;
+        pipeline_kind: z.ZodEnum<{
+            audio: "audio";
+            hdmi: "hdmi";
+            uvc_h264: "uvc_h264";
+            uvc_h265: "uvc_h265";
+            mjpeg: "mjpeg";
+            camlink: "camlink";
+            test: "test";
+            network: "network";
+        }>;
+        caps: z.ZodArray<z.ZodObject<{
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            framerate: z.ZodOptional<z.ZodString>;
+            media_type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     alsa_card_id: z.ZodOptional<z.ZodString>;
     product_name: z.ZodOptional<z.ZodString>;
     transport: z.ZodOptional<z.ZodEnum<{
@@ -206,6 +262,8 @@ export declare const captureDeviceSchema: z.ZodObject<{
         onboard: "onboard";
     }>>;
     stable_id: z.ZodOptional<z.ZodString>;
+    physical_group_id: z.ZodOptional<z.ZodString>;
+    hardware_serial: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CaptureDevice = z.infer<typeof captureDeviceSchema>;
 export declare const srtStatsSchema: z.ZodObject<{

package/dist/types.js

@@ -52,6 +52,18 @@ export const deviceTransportSchema = z.enum([
     "bluetooth",
     "onboard",
 ]);
+// Phase of one `change-config` transaction (0.10.0, additive). `applying` is
+// published once at entry, then exactly ONE terminal phase for the same
+// attempt_id: `applied` (the new config satisfied the outcome gate),
+// `reverted` (it did not and the single known-good rollback attempt did), or
+// `rollback_failed` (no rollback was possible, or the one attempt also failed —
+// the engine is idle, which is the truthful terminal state).
+export const configChangePhaseSchema = z.enum([
+    "applying",
+    "applied",
+    "reverted",
+    "rollback_failed",
+]);
 // ---- config sub-schemas (canonical; reused by `start` + the unified config) ----
 /** SRT transport config. Mirrors schema.md `start.srt` exactly. */
 export const srtConfigSchema = z.object({
@@ -117,6 +129,7 @@ export const cerastreamConfigSchema = z.object({
     framerate: z.number().optional(), // additive (0.4.0): fps as a number, e.g. 29.97
     audio: audioConfigSchema.optional(), // additive (0.4.0): audio device/codec/signed delay
     video_passthrough: videoPassthroughSchema.optional(), // additive (0.5.0): auto|force|off; absent ⇒ auto
+    input_mode: captureDeviceKindSchema.optional(), // additive (0.11.0): which MODE family of the selected device to capture in, naming a list-devices modes[].pipeline_kind. Absent ⇒ the engine's precedence pick (h265 → h264 → mjpeg → raw). The ONLY way to reach the non-precedence family of a dual-format camera; a family the device does not expose is a typed cerastream.params.invalid, never a silent fallback
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -132,17 +145,39 @@ export const captureCapSchema = z.object({
     framerate: z.string().optional(), // e.g. "30/1"
     media_type: z.string().optional(), // e.g. "video/x-h265"; additive, absent on legacy producers
 });
+// One startable capture MODE family of a device (0.11.0, additive).
+//
+// A capture device is not necessarily one format family: the DJI Osmo Pocket 3
+// exposes H.264 AND MJPEG on the SAME /dev/video1 node (selection is a
+// VIDIOC_S_FMT pixelformat choice, not a different node). The scalar
+// captureDevice.kind can only name ONE family, so before this contract a
+// dual-format camera was classified uvc_h264 by precedence and its MJPEG ladder
+// was unreachable — visible, but impossible to start.
+//
+// pipeline_kind is exactly what a caller echoes back as start.input_mode to drive
+// the device in this family. caps is the ladder for THIS family ALONE, never the
+// device-wide union: on the Osmo, H.264 offers 4K at 60/50/48 fps while MJPEG
+// tops out at 30, so a merged list would advertise 4K60 MJPEG — a mode the device
+// cannot deliver.
+export const captureModeSchema = z.object({
+    media_type: z.string(), // e.g. "image/jpeg"
+    pipeline_kind: captureDeviceKindSchema, // the value start.input_mode takes to select this mode
+    caps: z.array(captureCapSchema), // the {w × h × framerate} ladder for THIS media type only
+});
 export const captureDeviceSchema = z.object({
     input_id: z.string(), // stable id used by switch-input
     device_path: z.string(), // e.g. /dev/video0 (dedup key)
     display_name: z.string(),
     media_class: mediaClassSchema,
     caps: z.array(captureCapSchema).optional(),
-    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers
+    kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers. A dual-format device reports its HIGHEST-PRECEDENCE family here; the full set is `modes`
+    modes: z.array(captureModeSchema).optional(), // additive (0.11.0): every startable mode family, each with its OWN caps ladder; absent on legacy producers, on audio rows, and on a device with no probed caps. When present it ALWAYS contains the family named by `kind`, first
     alsa_card_id: z.string().optional(), // additive: ALSA card id for media_class:audio devices only; absent on video + legacy producers
     product_name: z.string().optional(), // additive (Todo 20): real product name, deduped with a #N suffix when shared; absent ⇒ use display_name
     transport: deviceTransportSchema.optional(), // additive (Todo 20): how the device is attached; absent on legacy producers
     stable_id: z.string().optional(), // additive (Todo 20): reboot-stable hardware identity, distinct from input_id/device_path
+    physical_group_id: z.string().optional(), // additive (0.10.0, ADR-0008): `usb:<topology-token>` shared by one physical device's rows; absent on non-USB + legacy producers, and an absent group NEVER matches
+    hardware_serial: z.string().optional(), // additive (0.10.0, ADR-0008): USB serial, DIAGNOSTIC ONLY — vendors ship placeholder serials, so never match/group/select on it
 });
 // ---- transport telemetry (srt-stats event payload) ----
 export const srtStatsSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceralive/cerastream",
-  "version": "2026.7.3",
+  "version": "2026.7.5",
   "description": "Type-safe TypeScript schema + IPC client for the cerastream streaming engine (JSON-RPC 2.0 / NDJSON over a Unix domain socket).",
   "type": "module",
   "main": "dist/index.js",