@ceralive/cerastream 2026.7.3 → 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 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.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}. */

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.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}. */

package/dist/events.d.ts

@@ -124,6 +124,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. */
@@ -214,6 +216,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">;
@@ -297,6 +321,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">;
@@ -352,6 +378,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. */
@@ -440,6 +477,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">;
@@ -495,12 +534,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: {
@@ -588,6 +639,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<{
@@ -649,4 +702,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.
@@ -127,6 +127,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 +152,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 +160,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 +172,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 +184,5 @@ export const eventSchemas = {
     error: runtimeErrorEventSchema,
     preview: previewEventSchema,
     "audio-level": audioLevelEventSchema,
+    "config-change": configChangeEventSchema,
 };

package/dist/messages.d.ts

@@ -83,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>;
@@ -103,6 +104,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<{
@@ -200,6 +202,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 +216,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 +229,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 +243,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 +380,42 @@ 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>;
+}, 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];
@@ -478,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<{
@@ -497,6 +541,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<{
@@ -578,6 +623,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 +639,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 +652,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, 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,42 @@ 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(),
+})
+    .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;
@@ -206,6 +213,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({
@@ -143,6 +155,8 @@ export const captureDeviceSchema = z.object({
     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.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",