@ceralive/cerastream 2026.7.2 → 2026.7.4

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 seven 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

@@ -1,9 +1,10 @@
 import { CONTROL_SOCKET_PATH, PROTOCOL_VERSION } from "./constants.js";
 import { helloResultSchema, rpcErrorSchema, rpcResponseSchema, } from "./envelope.js";
+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,
@@ -49,7 +50,7 @@ class ClientImpl {
             });
         }
         catch (err) {
-            throw new CerastreamConnectionError(`failed to connect to cerastream control socket at ${this.socketPath}`, err);
+            throw new CerastreamConnectionError(`failed to connect to cerastream control socket at ${this.socketPath}`, err, classifyConnectError(err, this.socketPath));
         }
         this.socket = socket;
     }
@@ -81,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);
     }
@@ -101,7 +105,7 @@ class ClientImpl {
         this.intentionalClose = true;
         for (const sub of this.subscriptions)
             sub.close();
-        const conn = new CerastreamConnectionError("client closed");
+        const conn = new CerastreamConnectionError("client closed", undefined, "closed");
         this.rejectAllPending(conn);
         this.socket?.close();
         this.socket = undefined;
@@ -117,7 +121,7 @@ class ClientImpl {
     rawRequest(method, params) {
         const socket = this.socket;
         if (!socket) {
-            return Promise.reject(new CerastreamConnectionError("control connection is not open"));
+            return Promise.reject(new CerastreamConnectionError("control connection is not open", undefined, "closed"));
         }
         const id = this.nextId++;
         const envelope = {
@@ -139,7 +143,7 @@ class ClientImpl {
             catch (err) {
                 clearTimeout(timer);
                 this.pending.delete(id);
-                reject(new CerastreamConnectionError("failed to write request", err));
+                reject(new CerastreamConnectionError("failed to write request", err, "lost"));
             }
         });
     }
@@ -206,7 +210,7 @@ class ClientImpl {
         this.socket = undefined;
         if (this.intentionalClose)
             return;
-        const conn = new CerastreamConnectionError("control connection lost", err);
+        const conn = new CerastreamConnectionError("control connection lost", err, "lost");
         this.rejectAllPending(conn);
         if (this.autoReconnect)
             void this.reconnectLoop();
@@ -263,6 +267,20 @@ function safeControlSocketPath() {
 function isObject(value) {
     return typeof value === "object" && value !== null;
 }
+// Classify a connect-time transport failure into a stable machine code. Bun's
+// `connect` collapses several distinct errors onto ENOENT and does not reliably
+// surface ECONNREFUSED for a stale AF_UNIX socket, so an explicit errno is
+// honored when present, then the socket file's presence disambiguates: a path
+// that is gone is `absent` (engine not up yet), a path that still exists but
+// won't accept is `refused` (a crashed/stale listener).
+function classifyConnectError(err, socketPath) {
+    const raw = isObject(err) ? err.code : undefined;
+    if (raw === "ECONNREFUSED")
+        return "refused";
+    if (raw === "EACCES" || raw === "EPERM")
+        return "unreachable";
+    return existsSync(socketPath) ? "refused" : "absent";
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

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.4.0";
+export declare const SCHEMA_VERSION: "0.10.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}. */
@@ -56,6 +56,14 @@ export declare const SUPPORTED_PROFILES: readonly ["balanced", "low-latency", "r
  * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
  */
 export declare const PROFILE_CATALOG_VERSION: "1.0.0";
+/**
+ * Named engine features `get-capabilities` advertises in `features`. This is the
+ * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
+ * when its feature is listed, so an engine that predates a feature (and silently
+ * ignores the field) never applies a semantic the caller assumed. Mirrors the
+ * Rust `ENGINE_FEATURES`.
+ */
+export declare const ENGINE_FEATURES: readonly ["video-passthrough"];
 /** 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.4.0";
+export const SCHEMA_VERSION = "0.10.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}. */
@@ -65,6 +65,14 @@ export const SUPPORTED_PROFILES = [
  * set or any preset's meaning changes. Mirrors the Rust `PROFILE_CATALOG_VERSION`.
  */
 export const PROFILE_CATALOG_VERSION = "1.0.0";
+/**
+ * Named engine features `get-capabilities` advertises in `features`. This is the
+ * fail-closed negotiation contract: CeraUI sends a new out-of-schema field ONLY
+ * when its feature is listed, so an engine that predates a feature (and silently
+ * ignores the field) never applies a semantic the caller assumed. Mirrors the
+ * Rust `ENGINE_FEATURES`.
+ */
+export const ENGINE_FEATURES = ["video-passthrough"];
 /** 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

@@ -22,15 +22,41 @@ export declare class CerastreamRpcError extends Error {
     readonly requestId: number | string | null;
     constructor(code: number, message: string, dataCode: string | undefined, requestId: number | string | null);
 }
+/**
+ * Machine-readable classification of a {@link CerastreamConnectionError}, stable
+ * across releases so CeraUI's start-failure taxonomy can branch on it without
+ * parsing messages. Distinguishes the three connect-phase failure shapes the
+ * engine's systemd lifecycle produces (an absent socket during boot, a stale
+ * socket left by a crashed instance, an otherwise-unreachable socket) from a
+ * mid-session drop or an intentional client close:
+ *
+ * - `absent`      — the control socket path does not exist (ENOENT): the engine
+ *                   is not running yet, or systemd has torn the old socket down
+ *                   during a restart. Maps to `engine_unavailable`/`engine_restarting`.
+ * - `refused`     — the socket path exists but the connection was refused
+ *                   (ECONNREFUSED): a stale socket a crashed/`SIGKILL`ed engine
+ *                   left behind, or one mid-`bind` on restart. Maps to
+ *                   `engine_restarting`/`engine_unavailable`.
+ * - `unreachable` — any other connect-time transport failure (e.g. EACCES).
+ * - `lost`        — an established connection dropped (socket closed/errored) or
+ *                   a write failed while a request was in flight.
+ * - `closed`      — the client was closed, or a request was issued on a
+ *                   not-open connection.
+ */
+export declare const CERASTREAM_CONNECT_ERROR_CODES: readonly ["absent", "refused", "unreachable", "lost", "closed"];
+export type CerastreamConnectErrorCode = (typeof CERASTREAM_CONNECT_ERROR_CODES)[number];
 /**
  * Thrown when the control connection is lost (socket closed/errored) while a
  * request was in flight, or when {@link connect} cannot reach the engine and
- * auto-reconnect is disabled.
+ * auto-reconnect is disabled. The {@link code} field classifies the failure —
+ * absent vs refused vs unreachable vs lost vs closed — for machine routing.
  */
 export declare class CerastreamConnectionError extends Error {
+    /** Stable machine-readable classification of the connection failure. */
+    readonly code: CerastreamConnectErrorCode;
     /** The underlying transport error, when there was one. */
     readonly cause: unknown;
-    constructor(message: string, cause?: unknown);
+    constructor(message: string, cause?: unknown, code?: CerastreamConnectErrorCode);
 }
 /** Thrown when a request exceeds the configured per-request timeout. */
 export declare class CerastreamTimeoutError extends Error {

package/dist/errors.js

@@ -31,17 +31,49 @@ export class CerastreamRpcError extends Error {
         this.requestId = requestId;
     }
 }
+/**
+ * Machine-readable classification of a {@link CerastreamConnectionError}, stable
+ * across releases so CeraUI's start-failure taxonomy can branch on it without
+ * parsing messages. Distinguishes the three connect-phase failure shapes the
+ * engine's systemd lifecycle produces (an absent socket during boot, a stale
+ * socket left by a crashed instance, an otherwise-unreachable socket) from a
+ * mid-session drop or an intentional client close:
+ *
+ * - `absent`      — the control socket path does not exist (ENOENT): the engine
+ *                   is not running yet, or systemd has torn the old socket down
+ *                   during a restart. Maps to `engine_unavailable`/`engine_restarting`.
+ * - `refused`     — the socket path exists but the connection was refused
+ *                   (ECONNREFUSED): a stale socket a crashed/`SIGKILL`ed engine
+ *                   left behind, or one mid-`bind` on restart. Maps to
+ *                   `engine_restarting`/`engine_unavailable`.
+ * - `unreachable` — any other connect-time transport failure (e.g. EACCES).
+ * - `lost`        — an established connection dropped (socket closed/errored) or
+ *                   a write failed while a request was in flight.
+ * - `closed`      — the client was closed, or a request was issued on a
+ *                   not-open connection.
+ */
+export const CERASTREAM_CONNECT_ERROR_CODES = [
+    "absent",
+    "refused",
+    "unreachable",
+    "lost",
+    "closed",
+];
 /**
  * Thrown when the control connection is lost (socket closed/errored) while a
  * request was in flight, or when {@link connect} cannot reach the engine and
- * auto-reconnect is disabled.
+ * auto-reconnect is disabled. The {@link code} field classifies the failure —
+ * absent vs refused vs unreachable vs lost vs closed — for machine routing.
  */
 export class CerastreamConnectionError extends Error {
+    /** Stable machine-readable classification of the connection failure. */
+    code;
     /** The underlying transport error, when there was one. */
     cause;
-    constructor(message, cause) {
+    constructor(message, cause, code = "unreachable") {
         super(message);
         this.name = "CerastreamConnectionError";
+        this.code = code;
         this.cause = cause;
     }
 }

package/dist/events.d.ts

@@ -13,6 +13,11 @@ export declare const activeEncodeSchema: z.ZodObject<{
     active_input: z.ZodOptional<z.ZodString>;
     decoder: z.ZodOptional<z.ZodString>;
     input_codec: z.ZodOptional<z.ZodString>;
+    passthrough: z.ZodOptional<z.ZodBoolean>;
+    gop_probe_outcome: z.ZodOptional<z.ZodString>;
+    gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+    frames_emitted: z.ZodOptional<z.ZodNumber>;
+    pipeline_playing: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ActiveEncode = z.infer<typeof activeEncodeSchema>;
 /**
@@ -48,6 +53,11 @@ export declare const statusEventSchema: z.ZodObject<{
         active_input: z.ZodOptional<z.ZodString>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
+        passthrough: z.ZodOptional<z.ZodBoolean>;
+        gop_probe_outcome: z.ZodOptional<z.ZodString>;
+        gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+        frames_emitted: z.ZodOptional<z.ZodNumber>;
+        pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Payload of a {@link statusEventSchema} event. */
@@ -106,6 +116,16 @@ export declare const deviceEventSchema: z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            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,6 +182,62 @@ export declare const previewEventSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Payload of a {@link previewEventSchema} event. */
 export type PreviewEvent = z.infer<typeof previewEventSchema>;
+/**
+ * `audio-level` event — the always-on audio level meter (ADR-0007, additive Todo
+ * 21). Either a real per-channel level from the current owner (the idle
+ * `sidecar` or the `streaming` audio leg), or `unavailable: true` + `reason` for
+ * a handoff gap or a degenerate `audio.mode` — never a fabricated level. A level
+ * carries `source`/`channels`/`rms_db`/`peak_db`/`floor_db`; an unavailable event
+ * carries `unavailable`/`reason` and omits the level fields. `floor_db` (`-1e6`)
+ * is the sentinel a consumer maps back to "silence" (JSON has no `-Infinity`).
+ * Independent of the preview-scoped `audio-level` WebSocket frame.
+ */
+export declare const audioLevelEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"audio-level">;
+    seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodString>;
+        owner: z.ZodEnum<{
+            streaming: "streaming";
+            sidecar: "sidecar";
+        }>;
+    }, z.core.$strip>>;
+    channels: z.ZodOptional<z.ZodNumber>;
+    rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    floor_db: z.ZodOptional<z.ZodNumber>;
+    unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        no_device: "no_device";
+        mode_none: "mode_none";
+        handoff: "handoff";
+    }>>;
+}, 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">;
@@ -186,6 +262,11 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         active_input: z.ZodOptional<z.ZodString>;
         decoder: z.ZodOptional<z.ZodString>;
         input_codec: z.ZodOptional<z.ZodString>;
+        passthrough: z.ZodOptional<z.ZodBoolean>;
+        gop_probe_outcome: z.ZodOptional<z.ZodString>;
+        gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+        frames_emitted: z.ZodOptional<z.ZodNumber>;
+        pipeline_playing: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"switch">;
@@ -232,6 +313,16 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            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">;
@@ -266,6 +357,38 @@ export declare const eventParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     seq: z.ZodNumber;
     session_id: z.ZodString;
     phase: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"audio-level">;
+    seq: z.ZodNumber;
+    source: z.ZodOptional<z.ZodObject<{
+        identity: z.ZodOptional<z.ZodString>;
+        owner: z.ZodEnum<{
+            streaming: "streaming";
+            sidecar: "sidecar";
+        }>;
+    }, z.core.$strip>>;
+    channels: z.ZodOptional<z.ZodNumber>;
+    rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    floor_db: z.ZodOptional<z.ZodNumber>;
+    unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        device_busy: "device_busy";
+        no_device: "no_device";
+        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. */
@@ -295,6 +418,11 @@ export declare const cerastreamEventSchema: z.ZodObject<{
             active_input: z.ZodOptional<z.ZodString>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
+            passthrough: z.ZodOptional<z.ZodBoolean>;
+            gop_probe_outcome: z.ZodOptional<z.ZodString>;
+            gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+            frames_emitted: z.ZodOptional<z.ZodNumber>;
+            pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"switch">;
@@ -341,6 +469,16 @@ export declare const cerastreamEventSchema: z.ZodObject<{
                 network: "network";
             }>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
+            product_name: z.ZodOptional<z.ZodString>;
+            transport: z.ZodOptional<z.ZodEnum<{
+                hdmi: "hdmi";
+                usb: "usb";
+                bluetooth: "bluetooth";
+                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">;
@@ -375,11 +513,45 @@ export declare const cerastreamEventSchema: z.ZodObject<{
         seq: z.ZodNumber;
         session_id: z.ZodString;
         phase: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"audio-level">;
+        seq: z.ZodNumber;
+        source: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodOptional<z.ZodString>;
+            owner: z.ZodEnum<{
+                streaming: "streaming";
+                sidecar: "sidecar";
+            }>;
+        }, z.core.$strip>>;
+        channels: z.ZodOptional<z.ZodNumber>;
+        rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        floor_db: z.ZodOptional<z.ZodNumber>;
+        unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            no_device: "no_device";
+            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 seven event topics (schema.md "Events" table) — count-assertion source. */
-export declare const EVENT_TOPICS: readonly ["status", "switch", "device", "bitrate", "srt-stats", "error", "preview"];
+/** 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: {
@@ -406,6 +578,11 @@ export declare const eventSchemas: {
             active_input: z.ZodOptional<z.ZodString>;
             decoder: z.ZodOptional<z.ZodString>;
             input_codec: z.ZodOptional<z.ZodString>;
+            passthrough: z.ZodOptional<z.ZodBoolean>;
+            gop_probe_outcome: z.ZodOptional<z.ZodString>;
+            gop_probe_ms: z.ZodOptional<z.ZodNumber>;
+            frames_emitted: z.ZodOptional<z.ZodNumber>;
+            pipeline_playing: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     readonly switch: z.ZodObject<{
@@ -454,6 +631,16 @@ export declare const eventSchemas: {
                 network: "network";
             }>>;
             alsa_card_id: z.ZodOptional<z.ZodString>;
+            product_name: z.ZodOptional<z.ZodString>;
+            transport: z.ZodOptional<z.ZodEnum<{
+                hdmi: "hdmi";
+                usb: "usb";
+                bluetooth: "bluetooth";
+                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<{
@@ -493,4 +680,38 @@ export declare const eventSchemas: {
         session_id: z.ZodString;
         phase: z.ZodString;
     }, z.core.$strip>;
+    readonly "audio-level": z.ZodObject<{
+        type: z.ZodLiteral<"audio-level">;
+        seq: z.ZodNumber;
+        source: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodOptional<z.ZodString>;
+            owner: z.ZodEnum<{
+                streaming: "streaming";
+                sidecar: "sidecar";
+            }>;
+        }, z.core.$strip>>;
+        channels: z.ZodOptional<z.ZodNumber>;
+        rms_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        peak_db: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        floor_db: z.ZodOptional<z.ZodNumber>;
+        unavailable: z.ZodOptional<z.ZodLiteral<true>>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            device_busy: "device_busy";
+            no_device: "no_device";
+            mode_none: "mode_none";
+            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.
@@ -19,6 +19,11 @@ export const activeEncodeSchema = z.object({
     active_input: z.string().optional(), // active input id feeding the encode
     decoder: z.string().optional(), // runtime-selected decode element when transcoding
     input_codec: z.string().optional(), // incoming pre-decode codec token: "h264"/"h265"/"mjpeg"
+    passthrough: z.boolean().optional(), // 0.5.0: true when a same-codec passthrough graph is live (no decode/re-encode)
+    gop_probe_outcome: z.string().optional(), // 0.5.0: GOP preflight outcome: "eligible"|"ineligible"|"unknown"|"skipped"
+    gop_probe_ms: z.number().int().nonnegative().optional(), // 0.5.0: GOP preflight duration in ms when a probe ran
+    frames_emitted: z.number().int().nonnegative().optional(), // 0.7.0: monotonic egress-buffer counter; advances across status heartbeats while frames flow
+    pipeline_playing: z.boolean().optional(), // 0.7.0: pipeline is in GStreamer PLAYING (false during an in-process reconnect)
 });
 /**
  * `status` event — stream state change + heartbeat. The trailing fields are
@@ -96,6 +101,47 @@ export const previewEventSchema = z.object({
     session_id: z.string(),
     phase: z.string(),
 });
+/**
+ * `audio-level` event — the always-on audio level meter (ADR-0007, additive Todo
+ * 21). Either a real per-channel level from the current owner (the idle
+ * `sidecar` or the `streaming` audio leg), or `unavailable: true` + `reason` for
+ * a handoff gap or a degenerate `audio.mode` — never a fabricated level. A level
+ * carries `source`/`channels`/`rms_db`/`peak_db`/`floor_db`; an unavailable event
+ * carries `unavailable`/`reason` and omits the level fields. `floor_db` (`-1e6`)
+ * is the sentinel a consumer maps back to "silence" (JSON has no `-Infinity`).
+ * Independent of the preview-scoped `audio-level` WebSocket frame.
+ */
+export const audioLevelEventSchema = z.object({
+    type: z.literal("audio-level"),
+    seq,
+    source: z
+        .object({
+        identity: z.string().optional(), // reboot-stable device id (Todo 20 stable_id)
+        owner: z.enum(["sidecar", "streaming"]),
+    })
+        .optional(),
+    channels: z.number().int().nonnegative().optional(),
+    rms_db: z.array(z.number()).optional(),
+    peak_db: z.array(z.number()).optional(),
+    floor_db: z.number().optional(),
+    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,
@@ -105,6 +151,8 @@ export const eventParamsSchema = z.discriminatedUnion("type", [
     srtStatsEventSchema,
     runtimeErrorEventSchema,
     previewEventSchema,
+    audioLevelEventSchema,
+    configChangeEventSchema,
 ]);
 /** Full event envelope: { jsonrpc, method:"event", params } with typed params. */
 export const cerastreamEventSchema = z.object({
@@ -112,7 +160,9 @@ export const cerastreamEventSchema = z.object({
     method: z.literal("event"),
     params: eventParamsSchema,
 });
-/** The seven event topics (schema.md "Events" table) — count-assertion source. */
+/** 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",
@@ -121,6 +171,8 @@ export const EVENT_TOPICS = [
     "srt-stats",
     "error",
     "preview",
+    "audio-level",
+    "config-change",
 ];
 /** topic → payload Zod schema. Tests assert every topic is represented here. */
 export const eventSchemas = {
@@ -131,4 +183,6 @@ export const eventSchemas = {
     "srt-stats": srtStatsEventSchema,
     error: runtimeErrorEventSchema,
     preview: previewEventSchema,
+    "audio-level": audioLevelEventSchema,
+    "config-change": configChangeEventSchema,
 };

package/dist/messages.d.ts

@@ -28,10 +28,20 @@ export declare const startParamsSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+            device: "device";
+        }>>;
         device: z.ZodOptional<z.ZodString>;
         codec: z.ZodOptional<z.ZodString>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    video_passthrough: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        force: "force";
+        off: "off";
+    }>>;
 }, z.core.$strip>;
 export type StartParams = z.infer<typeof startParamsSchema>;
 export declare const startResultSchema: z.ZodObject<{
@@ -73,6 +83,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>;
@@ -93,8 +104,14 @@ 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<{
+        encoder: "encoder";
+        "source-fixed": "source-fixed";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ReloadConfigResult = z.infer<typeof reloadConfigResultSchema>;
 export declare const setBitrateParamsSchema: z.ZodObject<{
@@ -105,6 +122,11 @@ export declare const setBitrateResultSchema: z.ZodObject<{
     applied: z.ZodObject<{
         max_bitrate: z.ZodNumber;
     }, z.core.$strip>;
+    bitrate_control: z.ZodOptional<z.ZodEnum<{
+        encoder: "encoder";
+        "source-fixed": "source-fixed";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SetBitrateResult = z.infer<typeof setBitrateResultSchema>;
 export declare const switchInputParamsSchema: z.ZodObject<{
@@ -172,6 +194,16 @@ export declare const listDevicesResultSchema: z.ZodObject<{
             network: "network";
         }>>;
         alsa_card_id: z.ZodOptional<z.ZodString>;
+        product_name: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            hdmi: "hdmi";
+            usb: "usb";
+            bluetooth: "bluetooth";
+            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>;
@@ -183,6 +215,8 @@ export declare const eventTopicSchema: z.ZodEnum<{
     switch: "switch";
     "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<{
@@ -194,6 +228,8 @@ export declare const subscribeEventsParamsSchema: z.ZodObject<{
         switch: "switch";
         "srt-stats": "srt-stats";
         preview: "preview";
+        "audio-level": "audio-level";
+        "config-change": "config-change";
     }>>>;
 }, z.core.$strip>;
 export type SubscribeEventsParams = z.infer<typeof subscribeEventsParamsSchema>;
@@ -206,6 +242,8 @@ export declare const subscribeEventsResultSchema: z.ZodObject<{
         switch: "switch";
         "srt-stats": "srt-stats";
         preview: "preview";
+        "audio-level": "audio-level";
+        "config-change": "config-change";
     }>>;
 }, z.core.$strip>;
 export type SubscribeEventsResult = z.infer<typeof subscribeEventsResultSchema>;
@@ -274,6 +312,16 @@ export declare const platformCapsSchema: z.ZodObject<{
     supports_h265: z.ZodBoolean;
     hardware_accelerated: z.ZodBoolean;
     max_resolution: z.ZodString;
+    hardware_kind: z.ZodOptional<z.ZodEnum<{
+        rk3588: "rk3588";
+        jetson: "jetson";
+        n100: "n100";
+        generic: "generic";
+    }>>;
+    source: z.ZodOptional<z.ZodEnum<{
+        detected: "detected";
+        override: "override";
+    }>>;
 }, z.core.$strip>;
 export type PlatformCaps = z.infer<typeof platformCapsSchema>;
 export declare const previewAvailabilitySchema: z.ZodObject<{
@@ -287,6 +335,16 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         supports_h265: z.ZodBoolean;
         hardware_accelerated: z.ZodBoolean;
         max_resolution: z.ZodString;
+        hardware_kind: z.ZodOptional<z.ZodEnum<{
+            rk3588: "rk3588";
+            jetson: "jetson";
+            n100: "n100";
+            generic: "generic";
+        }>>;
+        source: z.ZodOptional<z.ZodEnum<{
+            detected: "detected";
+            override: "override";
+        }>>;
     }, z.core.$strip>;
     encoder: z.ZodObject<{
         codecs: z.ZodArray<z.ZodString>;
@@ -319,8 +377,45 @@ export declare const getCapabilitiesResultSchema: z.ZodObject<{
         bound: z.ZodBoolean;
     }, z.core.$strip>>;
     network_embedded_audio: z.ZodOptional<z.ZodBoolean>;
+    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>;
+}, 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];
@@ -371,10 +466,20 @@ export declare const requestSchemas: {
             resolution: z.ZodOptional<z.ZodString>;
             framerate: z.ZodOptional<z.ZodNumber>;
             audio: z.ZodOptional<z.ZodObject<{
+                mode: z.ZodOptional<z.ZodEnum<{
+                    default: "default";
+                    none: "none";
+                    device: "device";
+                }>>;
                 device: z.ZodOptional<z.ZodString>;
                 codec: z.ZodOptional<z.ZodString>;
                 delay_ms: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
+            video_passthrough: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                force: "force";
+                off: "off";
+            }>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
             session_id: z.ZodString;
@@ -416,6 +521,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<{
@@ -435,8 +541,14 @@ 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<{
+                encoder: "encoder";
+                "source-fixed": "source-fixed";
+            }>>;
+            reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
     readonly "set-bitrate": {
@@ -447,6 +559,11 @@ export declare const requestSchemas: {
             applied: z.ZodObject<{
                 max_bitrate: z.ZodNumber;
             }, z.core.$strip>;
+            bitrate_control: z.ZodOptional<z.ZodEnum<{
+                encoder: "encoder";
+                "source-fixed": "source-fixed";
+            }>>;
+            reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
     readonly "switch-input": {
@@ -498,6 +615,16 @@ export declare const requestSchemas: {
                     network: "network";
                 }>>;
                 alsa_card_id: z.ZodOptional<z.ZodString>;
+                product_name: z.ZodOptional<z.ZodString>;
+                transport: z.ZodOptional<z.ZodEnum<{
+                    hdmi: "hdmi";
+                    usb: "usb";
+                    bluetooth: "bluetooth";
+                    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>;
     };
@@ -511,6 +638,8 @@ export declare const requestSchemas: {
                 switch: "switch";
                 "srt-stats": "srt-stats";
                 preview: "preview";
+                "audio-level": "audio-level";
+                "config-change": "config-change";
             }>>>;
         }, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -522,6 +651,8 @@ export declare const requestSchemas: {
                 switch: "switch";
                 "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, captureDeviceSchema, cerastreamConfigSchema, inputModeSchema, mediaClassSchema, previewTierSchema, streamStateSchema, } from "./types.js";
+import { balancerAlgorithmSchema, bitrateControlSchema, 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,11 +39,19 @@ 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(),
 });
 export const reloadConfigResultSchema = z.object({
     applied: reloadConfigParamsSchema, // post-clamp values actually applied
+    // additive (0.5.0): a bitrate-bearing reload during passthrough is NOT applied —
+    // "source-fixed" + reason "passthrough" report that. Absent on a transcode reload.
+    bitrate_control: bitrateControlSchema.optional(),
+    reason: z.string().optional(),
 });
 // ---- 4. set-bitrate ----
 export const setBitrateParamsSchema = z.object({
@@ -51,6 +59,10 @@ export const setBitrateParamsSchema = z.object({
 });
 export const setBitrateResultSchema = z.object({
     applied: z.object({ max_bitrate: z.number().int() }),
+    // additive (0.5.0). On passthrough there is no encoder to drive, so a request is
+    // NOT applied: "source-fixed" with reason "passthrough". Absent/"encoder" ⇒ applied.
+    bitrate_control: bitrateControlSchema.optional(),
+    reason: z.string().optional(),
 });
 // ---- 5. switch-input ----
 export const switchInputParamsSchema = z.object({
@@ -91,6 +103,8 @@ export const eventTopicSchema = z.enum([
     "srt-stats",
     "error",
     "preview",
+    "audio-level",
+    "config-change",
 ]);
 export const subscribeEventsParamsSchema = z.object({
     topics: z.array(eventTopicSchema).optional(), // default: all topics
@@ -154,6 +168,10 @@ export const platformCapsSchema = z.object({
     supports_h265: z.boolean(),
     hardware_accelerated: z.boolean(),
     max_resolution: z.string(),
+    // additive: the engine's resolved hardware kind and how it was resolved.
+    // Optional so a pre-field engine (which omits both) still parses.
+    hardware_kind: z.enum(["rk3588", "jetson", "n100", "generic"]).optional(),
+    source: z.enum(["detected", "override"]).optional(),
 });
 // Preview-server availability (0.4.0, additive). Lets the UI tell an unbound /
 // port-conflicted preview (enabled:true, bound:false) from a down engine.
@@ -173,7 +191,44 @@ export const getCapabilitiesResultSchema = z.object({
     profile_catalog_version: z.string().optional(), // semver of the supported_profiles catalog
     preview: previewAvailabilitySchema.optional(), // preview-server availability (unbound vs down)
     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(),
+})
+    .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

@@ -32,6 +32,17 @@ export declare const videoCodecSchema: z.ZodEnum<{
     h265: "h265";
 }>;
 export type VideoCodec = z.infer<typeof videoCodecSchema>;
+export declare const videoPassthroughSchema: z.ZodEnum<{
+    auto: "auto";
+    force: "force";
+    off: "off";
+}>;
+export type VideoPassthrough = z.infer<typeof videoPassthroughSchema>;
+export declare const bitrateControlSchema: z.ZodEnum<{
+    encoder: "encoder";
+    "source-fixed": "source-fixed";
+}>;
+export type BitrateControl = z.infer<typeof bitrateControlSchema>;
 export declare const captureDeviceKindSchema: z.ZodEnum<{
     audio: "audio";
     hdmi: "hdmi";
@@ -43,6 +54,20 @@ export declare const captureDeviceKindSchema: z.ZodEnum<{
     network: "network";
 }>;
 export type CaptureDeviceKind = z.infer<typeof captureDeviceKindSchema>;
+export declare const deviceTransportSchema: z.ZodEnum<{
+    hdmi: "hdmi";
+    usb: "usb";
+    bluetooth: "bluetooth";
+    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;
@@ -73,7 +98,18 @@ export type BitrateConfig = z.infer<typeof bitrateConfigSchema>;
  * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
  * never rejected — so the schema does NOT bound it.
  */
+export declare const audioModeSchema: z.ZodEnum<{
+    default: "default";
+    none: "none";
+    device: "device";
+}>;
+export type AudioMode = z.infer<typeof audioModeSchema>;
 export declare const audioConfigSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        none: "none";
+        device: "device";
+    }>>;
     device: z.ZodOptional<z.ZodString>;
     codec: z.ZodOptional<z.ZodString>;
     delay_ms: z.ZodOptional<z.ZodNumber>;
@@ -114,10 +150,20 @@ export declare const cerastreamConfigSchema: z.ZodObject<{
     resolution: z.ZodOptional<z.ZodString>;
     framerate: z.ZodOptional<z.ZodNumber>;
     audio: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+            device: "device";
+        }>>;
         device: z.ZodOptional<z.ZodString>;
         codec: z.ZodOptional<z.ZodString>;
         delay_ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    video_passthrough: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        force: "force";
+        off: "off";
+    }>>;
 }, z.core.$strip>;
 export type CerastreamConfig = z.infer<typeof cerastreamConfigSchema>;
 export type PartialCerastreamConfig = z.input<typeof cerastreamConfigSchema>;
@@ -159,6 +205,16 @@ export declare const captureDeviceSchema: z.ZodObject<{
         network: "network";
     }>>;
     alsa_card_id: z.ZodOptional<z.ZodString>;
+    product_name: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        hdmi: "hdmi";
+        usb: "usb";
+        bluetooth: "bluetooth";
+        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

@@ -18,6 +18,16 @@ export const previewTierSchema = z.enum(["webcodecs", "webrtc"]);
 // platform default. Wire values are the codec id strings the encoder caps also
 // advertise ("h264"/"h265") — never an encoder element name.
 export const videoCodecSchema = z.enum(["h264", "h265"]);
+// Same-codec passthrough policy (0.5.0, additive). Absent ⇒ "auto". "auto" =
+// passthrough only when adaptive bitrate is inactive and eligibility holds;
+// "force" = passthrough whenever eligible (typed start failure otherwise);
+// "off" = always transcode. See schema.md and the engine's layer-C matrix.
+export const videoPassthroughSchema = z.enum(["auto", "force", "off"]);
+// Which surface owns the running bitrate, reported additively on a set-bitrate /
+// reload-config response (0.5.0). "encoder" = applied; "source-fixed" = a
+// passthrough graph fixes the bitrate at the source, so the request was NOT
+// applied (paired with reason "passthrough").
+export const bitrateControlSchema = z.enum(["encoder", "source-fixed"]);
 // Engine-typed capture-device family (0.4.0, additive). CeraUI groups a device
 // by the engine's resolved kind (a UVC/USB dongle is uvc_h264/mjpeg, never
 // mislabeled HDMI). Absent ⇒ CeraUI falls back to a bus/name heuristic.
@@ -31,6 +41,29 @@ export const captureDeviceKindSchema = z.enum([
     "test",
     "network",
 ]);
+// How a capture device is physically attached (Todo 20, additive). The transport
+// tag CeraUI renders beside the product name (e.g. "RØDE NT-USB · USB"). Distinct
+// from captureDeviceKind: an HDMI-to-USB dongle is kind:uvc_h264 but transport:usb,
+// while the SoC's dedicated HDMI-RX port is transport:hdmi. Absent on a legacy
+// producer or when no hint identifies a transport.
+export const deviceTransportSchema = z.enum([
+    "usb",
+    "hdmi",
+    "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({
@@ -67,7 +100,15 @@ export const bitrateConfigSchema = z
  * later, negative = earlier); it is clamped to ±AUDIO_DELAY_MAX_MS when applied,
  * never rejected — so the schema does NOT bound it.
  */
+// How the program audio is sourced (0.6.0, additive). "none" = no audio branch
+// (video-only TS); "default" = embedded audio for a network source, the selected
+// device or a silent track for a capture source; "device" = the selected ALSA
+// leg (requires `device`). Absent ⇒ legacy inference from `device`/source kind,
+// so a pre-0.6.0 caller keeps working. Replaces leaking pseudo-source strings
+// (e.g. "No audio") into `device`.
+export const audioModeSchema = z.enum(["none", "default", "device"]);
 export const audioConfigSchema = z.object({
+    mode: audioModeSchema.optional(),
     device: z.string().optional(), // ALSA capture device id; absent ⇒ test-tone fallback
     codec: z.string().optional(), // audio encoder codec id (e.g. "aac", "opus")
     delay_ms: z.number().int().optional(), // signed A/V-sync delay (clamped at apply)
@@ -87,6 +128,7 @@ export const cerastreamConfigSchema = z.object({
     resolution: z.string().optional(), // additive (0.4.0): "WxH" pixel form (never a UI token)
     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
 });
 // convenience defaults for building a config client-side
 export const DEFAULT_BITRATE_CONFIG = {
@@ -110,6 +152,11 @@ export const captureDeviceSchema = z.object({
     caps: z.array(captureCapSchema).optional(),
     kind: captureDeviceKindSchema.optional(), // additive (0.4.0): engine-typed device family; absent on legacy producers
     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.2",
+  "version": "2026.7.4",
   "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",