@camstack/types 1.2.40 → 1.2.42

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type InferProvider } from './capability-definition.js';
 import type { ConfigField } from '../interfaces/config-ui.js';
+import { type InferProvider } from './capability-definition.js';
 /**
  * A bounding box in NORMALIZED [0,1] frame coordinates for `getNativeCrop`. The
  * decode worker resolves it against the RETAINED native frame's real pixel dims,
@@ -60,6 +60,27 @@ declare const DetailResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type DetailParent = z.infer<typeof DetailParentSchema>;
 export type DetailResult = z.infer<typeof DetailResultSchema>;
+/**
+ * Why an executing node REFUSED a stateless step run (`runStatelessStep`).
+ *
+ * A refusal is a first-class answer, not an error, because the caller's next
+ * move depends on WHICH one it is — and because "the pass produced nothing"
+ * must never be reachable without a named, counted cause. The two tiers:
+ *
+ * - **node-level** (`unknown-step`, `model-not-servable`) — this node can
+ *   never serve this (step, model) pair. The caller drops it from its rotation
+ *   and retries the same work elsewhere; nothing about the work changes.
+ * - **work-level** (`unreadable-frame`, `execution-failed`) — this node is
+ *   fine, this one request is not. Retrying it on another node would only
+ *   spread the same failure.
+ */
+declare const StatelessStepRefusalSchema: z.ZodEnum<{
+    "unknown-step": "unknown-step";
+    "model-not-servable": "model-not-servable";
+    "unreadable-frame": "unreadable-frame";
+    "execution-failed": "execution-failed";
+}>;
+export type StatelessStepRefusal = z.infer<typeof StatelessStepRefusalSchema>;
 /**
  * Source enum for motion signals fed to the runner. Extensible — add
  * new variants here when new motion-trigger paths are wired in
@@ -533,12 +554,29 @@ export declare const pipelineRunnerCapability: {
          * for a single tracked detection. The per-frame plane (`runPipeline`
          * with `plane: 'frame'`) skips crop children entirely; a track-level
          * caller invokes this per-track, on its own cadence, instead of on
-         * every frame. Takes either a `frameHandle` (shm lease/session —
-         * preferred, zero-copy) or a `cropJpeg` fallback when the lease/
-         * session backing the frame is already gone. `steps` narrows which
-         * configured children to run (default: all configured children for
-         * `parent.className`). Returns `null` when neither frame source is
-         * resolvable (handle evicted and no cropJpeg fallback supplied).
+         * every frame. `steps` narrows which configured children to run
+         * (default: all configured children for `parent.className`).
+         *
+         * ## Three pixel sources, and WHO decides the rectangle
+         *
+         * Tried in this order; the difference between them is not the pixels but
+         * which side derives the crop, and confusing the two is how the CLIP index
+         * ended up holding two incomparable feature spaces:
+         *
+         * 1. `frameHandle` — shm lease/session, preferred and zero-copy. **The
+         *    runner cuts**, applying the cluster crop convention.
+         * 2. `frameJpeg` — a FULL FRAME supplied by the caller (the embedding
+         *    rebuild's stored key frame). **The runner cuts**, applying the same
+         *    convention to the same function, so a rebuilt vector lands in the same
+         *    feature space as a live one.
+         * 3. `cropJpeg` — an ALREADY-CUT tile. **The caller decided the
+         *    rectangle**; the runner applies NO padding and no squaring and feeds
+         *    it to the model verbatim. Only for the lease-miss retry, where the
+         *    caller holds pixels the runner can no longer reach.
+         *
+         * Returns `null` when no source resolves (handle evicted and no fallback
+         * supplied), when the camera is not attached, or when no enabled step
+         * matches — every one of those is logged on the runner with the deviceId.
          */
         readonly runDetailSubtree: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -560,6 +598,7 @@ export declare const pipelineRunnerCapability: {
                 nodeId: z.ZodString;
                 slotCount: z.ZodNumber;
             }, z.core.$strip>>;
+            frameJpeg: z.ZodOptional<z.ZodString>;
             cropJpeg: z.ZodOptional<z.ZodString>;
             parent: z.ZodObject<{
                 bbox: z.ZodObject<{
@@ -588,6 +627,92 @@ export declare const pipelineRunnerCapability: {
                 nativeFaceShortSidePx: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strip>>, "mutation">;
+        /**
+         * Run ONE enrichment step against caller-supplied pixels, with NO camera
+         * session — no attach, no frame handle, no device affinity.
+         *
+         * ## Why this exists next to `runDetailSubtree` and not inside it
+         *
+         * `runDetailSubtree` resolves its step tree from the LIVE ATTACH STATE. That
+         * is correct for it: its reason to exist is a frame HANDLE, and a handle is
+         * only resolvable while a decode session is open. But it makes the method
+         * useless to anything walking history — cameras run `detectionMode:
+         * 'on-motion'` and detach ~30 s after motion stops, so a fleet-wide
+         * embedding rebuild found most cameras detached and rebuilt only whatever
+         * happened to be attached at that second (measured 2026-08-06: 1125 tracks
+         * scanned, 121 rebuilt, 601 refused as "camera is not attached").
+         *
+         * A caller that ships its own pixels needs none of that machinery. So this
+         * method takes the three things a step actually needs — an image, a box, a
+         * step id — resolves the step from the CATALOG rather than from an
+         * attachment, and runs it on whichever node the caller pinned.
+         *
+         * ## What it deliberately keeps
+         *
+         * The crop rectangle is derived by the SAME `deriveDetailCropRect` call the
+         * live detail plane uses, from the same cluster-wide convention
+         * ([D52](../../../docs/decisions/adr-0052.md)). `frameJpeg` is a FULL frame,
+         * never a pre-cut tile, for exactly the reason `runDetailSubtree` documents:
+         * a caller that cuts is a second feature space.
+         *
+         * ## What it deliberately drops
+         *
+         * No device jump and no `deviceKey`: the jump roster comes from the attach
+         * config, which does not exist here. The step runs on the node's default
+         * engine. This is a maintenance path, not a latency-sensitive one.
+         *
+         * ## Routing
+         *
+         * NOT device-bound. `sourceDeviceId` is DIAGNOSTIC — the camera whose track
+         * these pixels came from, so every log line on the executing node can carry
+         * `tags: { deviceId }`. It is deliberately not named `deviceId`: that field
+         * is a routing hint that would send the call to the camera's owning node,
+         * which is the placement constraint this method exists to remove. Callers
+         * choose the node with `nodePin(nodeId)`; unpinned, an unowned call is
+         * served hub-in-process like any other singleton.
+         */
+        readonly runStatelessStep: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            stepId: z.ZodString;
+            modelId: z.ZodString;
+            frameJpeg: z.ZodString;
+            bbox: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>;
+            className: z.ZodString;
+            sourceDeviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"ran">;
+            nodeId: z.ZodString;
+            modelId: z.ZodString;
+            details: z.ZodArray<z.ZodObject<{
+                stepId: z.ZodString;
+                className: z.ZodString;
+                score: z.ZodNumber;
+                bbox: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    w: z.ZodNumber;
+                    h: z.ZodNumber;
+                }, z.core.$strip>>;
+                embedding: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                alignedCropJpeg: z.ZodOptional<z.ZodString>;
+                nativeFaceShortSidePx: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"refused">;
+            nodeId: z.ZodString;
+            reason: z.ZodEnum<{
+                "unknown-step": "unknown-step";
+                "model-not-servable": "model-not-servable";
+                "unreadable-frame": "unreadable-frame";
+                "execution-failed": "execution-failed";
+            }>;
+            detail: z.ZodString;
+        }, z.core.$strip>], "kind">, "mutation">;
     };
 };
 export type IPipelineRunnerProvider = InferProvider<typeof pipelineRunnerCapability>;
@@ -605,4 +730,15 @@ export type IPipelineRunnerProvider = InferProvider<typeof pipelineRunnerCapabil
  */
 export type RunDetailSubtreeInput = Parameters<IPipelineRunnerProvider['runDetailSubtree']>[0];
 export type RunDetailSubtreeResult = NonNullable<Awaited<ReturnType<IPipelineRunnerProvider['runDetailSubtree']>>>;
+/**
+ * Named input/output types for `runStatelessStep`, derived the same way and for
+ * the same reason as the `runDetailSubtree` pair above — the method's input
+ * stays an inline `z.object({…})` literal so `scripts/lib/parse-cap.ts` keeps
+ * classifying it correctly. Here the classification wanted is the OPPOSITE one:
+ * there is no `deviceId: z.number(` in the body, so the method is NOT
+ * device-bound and never lands on `DeviceProxy` — placement is the caller's
+ * `nodePin`, not the camera's owner.
+ */
+export type RunStatelessStepInput = Parameters<IPipelineRunnerProvider['runStatelessStep']>[0];
+export type RunStatelessStepResult = Awaited<ReturnType<IPipelineRunnerProvider['runStatelessStep']>>;
 export { RunnerCameraConfigSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema };

package/dist/capabilities/platform-probe.cap.d.ts

@@ -277,12 +277,12 @@ export declare const platformProbeCapability: {
                 coreml: "coreml";
                 openvino: "openvino";
                 none: "none";
-                tensorrt: "tensorrt";
-                cuda: "cuda";
                 videotoolbox: "videotoolbox";
-                nvdec: "nvdec";
                 vaapi: "vaapi";
                 qsv: "qsv";
+                cuda: "cuda";
+                tensorrt: "tensorrt";
+                nvdec: "nvdec";
                 d3d11va: "d3d11va";
                 dxva2: "dxva2";
                 amf: "amf";

package/dist/capabilities/recording.cap.d.ts

@@ -355,6 +355,7 @@ export declare const recordingCapability: {
                 operator: "operator";
                 retention: "retention";
                 quota: "quota";
+                maintenance: "maintenance";
             }>>;
         }, z.core.$strip>, z.ZodObject<{
             floorMs: z.ZodNullable<z.ZodNumber>;
@@ -393,12 +394,14 @@ export declare const recordingCapability: {
                 rescan: "rescan";
                 "retention-run": "retention-run";
                 relocate: "relocate";
+                "orphan-audit": "orphan-audit";
             }>;
             reason: z.ZodEnum<{
                 manual: "manual";
                 operator: "operator";
                 retention: "retention";
                 quota: "quota";
+                maintenance: "maintenance";
             }>;
             deviceId: z.ZodNullable<z.ZodNumber>;
             nodeId: z.ZodString;

package/dist/capabilities/stream-broker.cap.d.ts

@@ -279,6 +279,179 @@ export declare const RtpSourceSchema: z.ZodObject<{
     pipelineKey: z.ZodString;
 }, z.core.$strip>;
 export type RtpSource = z.infer<typeof RtpSourceSchema>;
+/**
+ * The encode request — **structured and serialisable, with NO raw-flag escape
+ * hatch.** This is deliberate and it is the one lesson taken from
+ * `getStreamWithCodec`: that method's `outputArgs: string[]` is simultaneously
+ * its extensibility mechanism AND part of `pipelineKeyFor`'s sharing key, so
+ * adding a flag silently forks the shared child, and two consumers that mean
+ * the same thing but spell it differently never share. Here every knob is a
+ * NAMED field: a new requirement becomes a schema field (and a codegen run),
+ * never an opaque array.
+ *
+ * `inputArgs` / `outputArgs` are omitted from the profile for the same reason.
+ * The operator-facing derived-stream transform editor still has them — that is
+ * a different surface (`publishCameraStream({ kind: 'derived' })`) with a
+ * different purpose (reshaping a badly-behaved SOURCE), and it is unchanged.
+ */
+export declare const EgressEncodeSchema: z.ZodObject<{
+    audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+        codec: z.ZodEnum<{
+            copy: "copy";
+            opus: "opus";
+            aac: "aac";
+            pcmu: "pcmu";
+            pcma: "pcma";
+        }>;
+        bitrateKbps: z.ZodOptional<z.ZodNumber>;
+        sampleRateHz: z.ZodOptional<z.ZodNumber>;
+        channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    }, z.core.$strip>]>;
+    video: z.ZodObject<{
+        codec: z.ZodEnum<{
+            h264: "h264";
+            h265: "h265";
+            copy: "copy";
+        }>;
+        profile: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            baseline: "baseline";
+            main: "main";
+        }>>;
+        level: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        fps: z.ZodOptional<z.ZodNumber>;
+        bitrateKbps: z.ZodOptional<z.ZodNumber>;
+        gopFrames: z.ZodOptional<z.ZodNumber>;
+        bf: z.ZodOptional<z.ZodNumber>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            fast: "fast";
+            ultrafast: "ultrafast";
+            superfast: "superfast";
+            veryfast: "veryfast";
+            faster: "faster";
+            medium: "medium";
+        }>>;
+        tune: z.ZodOptional<z.ZodEnum<{
+            zerolatency: "zerolatency";
+            film: "film";
+            animation: "animation";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EgressEncode = z.infer<typeof EgressEncodeSchema>;
+/**
+ * How the encoder is bounded. `'tight'` is a one-second VBV window for a
+ * consumer whose budget is enforced per second (HomeKit); `'relaxed'` is two
+ * seconds, letting a keyframe spike borrow from the next second (a browser,
+ * an Echo). Named rather than numeric so the INTENT survives.
+ */
+export declare const EgressRateControlSchema: z.ZodEnum<{
+    tight: "tight";
+    relaxed: "relaxed";
+}>;
+export type EgressRateControl = z.infer<typeof EgressRateControlSchema>;
+export declare const EgressTranscodeRequestSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"profile">;
+        profile: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cam-stream">;
+        camStreamId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    encode: z.ZodObject<{
+        audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+            codec: z.ZodEnum<{
+                copy: "copy";
+                opus: "opus";
+                aac: "aac";
+                pcmu: "pcmu";
+                pcma: "pcma";
+            }>;
+            bitrateKbps: z.ZodOptional<z.ZodNumber>;
+            sampleRateHz: z.ZodOptional<z.ZodNumber>;
+            channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        }, z.core.$strip>]>;
+        video: z.ZodObject<{
+            codec: z.ZodEnum<{
+                h264: "h264";
+                h265: "h265";
+                copy: "copy";
+            }>;
+            profile: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                baseline: "baseline";
+                main: "main";
+            }>>;
+            level: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            fps: z.ZodOptional<z.ZodNumber>;
+            bitrateKbps: z.ZodOptional<z.ZodNumber>;
+            gopFrames: z.ZodOptional<z.ZodNumber>;
+            bf: z.ZodOptional<z.ZodNumber>;
+            preset: z.ZodOptional<z.ZodEnum<{
+                fast: "fast";
+                ultrafast: "ultrafast";
+                superfast: "superfast";
+                veryfast: "veryfast";
+                faster: "faster";
+                medium: "medium";
+            }>>;
+            tune: z.ZodOptional<z.ZodEnum<{
+                zerolatency: "zerolatency";
+                film: "film";
+                animation: "animation";
+            }>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    rateControl: z.ZodOptional<z.ZodEnum<{
+        tight: "tight";
+        relaxed: "relaxed";
+    }>>;
+    bitstreamFilter: z.ZodOptional<z.ZodEnum<{
+        dump_extra: "dump_extra";
+        h264_mp4toannexb: "h264_mp4toannexb";
+        hevc_mp4toannexb: "hevc_mp4toannexb";
+    }>>;
+    pixelFormat: z.ZodOptional<z.ZodEnum<{
+        yuv420p: "yuv420p";
+        nv12: "nv12";
+    }>>;
+    decodeHwAccel: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        auto: "auto";
+        videotoolbox: "videotoolbox";
+        vaapi: "vaapi";
+        qsv: "qsv";
+        cuda: "cuda";
+    }>>;
+    hostname: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EgressTranscodeRequest = z.infer<typeof EgressTranscodeRequestSchema>;
+export declare const EgressTranscodeSchema: z.ZodObject<{
+    url: z.ZodString;
+    pipelineKey: z.ZodString;
+    videoCodec: z.ZodEnum<{
+        H264: "H264";
+        H265: "H265";
+    }>;
+    resolution: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    transcoded: z.ZodBoolean;
+    encoder: z.ZodString;
+    decodeHwAccel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type EgressTranscode = z.infer<typeof EgressTranscodeSchema>;
 export declare const streamBrokerCapability: {
     readonly name: "stream-broker";
     readonly scope: "system";
@@ -321,6 +494,7 @@ export declare const streamBrokerCapability: {
                         baseline: "baseline";
                         main: "main";
                     }>>;
+                    level: z.ZodOptional<z.ZodString>;
                     width: z.ZodOptional<z.ZodNumber>;
                     height: z.ZodOptional<z.ZodNumber>;
                     fps: z.ZodOptional<z.ZodNumber>;
@@ -691,6 +865,132 @@ export declare const streamBrokerCapability: {
             released: z.ZodBoolean;
             refcount: z.ZodNumber;
         }, z.core.$strip>, "mutation">;
+        /**
+         * THE ffmpeg primitive. Acquire an encoded stream matching a structured
+         * encode plan; the broker builds the argv through the ONE builder
+         * (`@camstack/types` `ffmpeg/invocation.ts`), resolves decode hardware from
+         * the DECODER ADDON's per-node ranking, and returns a dialable RTSP url.
+         *
+         * **Refcounted and deduplicated on EXACT match.** Two requesters whose
+         * requests produce the same `egressTranscodeSharingKey` receive the SAME
+         * `pipelineKey` and the same child process. Nearly-identical requests are
+         * NOT merged.
+         *
+         * **The handle is immutable.** There is deliberately no `reconfigure`
+         * method and this one never accepts a `pipelineKey` alongside encode
+         * parameters: a consumer whose requirements change releases and
+         * re-acquires. A mutable shared handle is exactly what made Alexa's old
+         * `derived:alexa-<id>` stream a co-tenant hazard — one consumer's
+         * downgrade dragged every other consumer down with it.
+         *
+         * Placement: unpinned, `classifyCapRoute` serves this hub-in-process
+         * (Priority 1). A caller that wants the transcode elsewhere passes
+         * `nodePin(nodeId)` and a `hostname` it can dial.
+         */
+        readonly acquireEgressTranscode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"profile">;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"cam-stream">;
+                camStreamId: z.ZodString;
+            }, z.core.$strip>], "kind">;
+            encode: z.ZodObject<{
+                audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+                    codec: z.ZodEnum<{
+                        copy: "copy";
+                        opus: "opus";
+                        aac: "aac";
+                        pcmu: "pcmu";
+                        pcma: "pcma";
+                    }>;
+                    bitrateKbps: z.ZodOptional<z.ZodNumber>;
+                    sampleRateHz: z.ZodOptional<z.ZodNumber>;
+                    channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+                }, z.core.$strip>]>;
+                video: z.ZodObject<{
+                    codec: z.ZodEnum<{
+                        h264: "h264";
+                        h265: "h265";
+                        copy: "copy";
+                    }>;
+                    profile: z.ZodOptional<z.ZodEnum<{
+                        high: "high";
+                        baseline: "baseline";
+                        main: "main";
+                    }>>;
+                    level: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    fps: z.ZodOptional<z.ZodNumber>;
+                    bitrateKbps: z.ZodOptional<z.ZodNumber>;
+                    gopFrames: z.ZodOptional<z.ZodNumber>;
+                    bf: z.ZodOptional<z.ZodNumber>;
+                    preset: z.ZodOptional<z.ZodEnum<{
+                        fast: "fast";
+                        ultrafast: "ultrafast";
+                        superfast: "superfast";
+                        veryfast: "veryfast";
+                        faster: "faster";
+                        medium: "medium";
+                    }>>;
+                    tune: z.ZodOptional<z.ZodEnum<{
+                        zerolatency: "zerolatency";
+                        film: "film";
+                        animation: "animation";
+                    }>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            rateControl: z.ZodOptional<z.ZodEnum<{
+                tight: "tight";
+                relaxed: "relaxed";
+            }>>;
+            bitstreamFilter: z.ZodOptional<z.ZodEnum<{
+                dump_extra: "dump_extra";
+                h264_mp4toannexb: "h264_mp4toannexb";
+                hevc_mp4toannexb: "hevc_mp4toannexb";
+            }>>;
+            pixelFormat: z.ZodOptional<z.ZodEnum<{
+                yuv420p: "yuv420p";
+                nv12: "nv12";
+            }>>;
+            decodeHwAccel: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                auto: "auto";
+                videotoolbox: "videotoolbox";
+                vaapi: "vaapi";
+                qsv: "qsv";
+                cuda: "cuda";
+            }>>;
+            hostname: z.ZodOptional<z.ZodString>;
+            tag: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            url: z.ZodString;
+            pipelineKey: z.ZodString;
+            videoCodec: z.ZodEnum<{
+                H264: "H264";
+                H265: "H265";
+            }>;
+            resolution: z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+            transcoded: z.ZodBoolean;
+            encoder: z.ZodString;
+            decodeHwAccel: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
+        /** Drop one reference. The child dies when the last holder releases. */
+        readonly releaseEgressTranscode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            pipelineKey: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            released: z.ZodBoolean;
+            refcount: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
         /**
          * ── Decoded audio-chunk plane (Phase 5 / D9) ──────────────────────
          *

package/dist/encode-profile.d.ts

@@ -22,6 +22,7 @@ export declare const VideoEncodeSchema: z.ZodObject<{
         baseline: "baseline";
         main: "main";
     }>>;
+    level: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     fps: z.ZodOptional<z.ZodNumber>;
@@ -68,6 +69,7 @@ export declare const EncodeProfileSchema: z.ZodObject<{
             baseline: "baseline";
             main: "main";
         }>>;
+        level: z.ZodOptional<z.ZodString>;
         width: z.ZodOptional<z.ZodNumber>;
         height: z.ZodOptional<z.ZodNumber>;
         fps: z.ZodOptional<z.ZodNumber>;

package/dist/ffmpeg/encode-defaults.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The ONE home for live-egress encode constants.
+ *
+ * Before this file there were five sets, in four packages, that nobody could
+ * diff: the WebRTC fallback, Alexa's "fallback", the transcode-down ceiling,
+ * the broker's audio presets, and HomeKit's inline block. Three of them
+ * disagreed about Opus channel count alone. They live here now because the
+ * consumers are separate ADDONS and addons may never import each other —
+ * `@camstack/types` is the only legal shared home.
+ *
+ * ## What changed value, and what kept a deliberate divergence
+ *
+ * KEPT, with the reason:
+ * - **VBV window.** HomeKit uses a ONE-second window; the browser and Alexa
+ *   use TWO. HomeKit's link budget is enforced per second by the controller,
+ *   so a keyframe allowed to borrow from the next second overshoots and the
+ *   iOS client drops the stream. A browser wants the opposite: let a keyframe
+ *   spike, keep the average. Encoded as {@link FfmpegRateControl}, not as two
+ *   copies of a number.
+ * - **`preset`.** HomeKit and the browser use `ultrafast` (the encoder is on
+ *   the interactive path); Alexa uses `veryfast` (Echo tolerates ~200 ms more
+ *   latency and the extra quality is visible on a 10" panel).
+ * - **`-bsf:v dump_extra`** is HomeKit-only on BOTH the copy and encode
+ *   branches: HAP negotiates its own SDP and cannot carry out-of-band
+ *   extradata. Nothing else needs it, and emitting it elsewhere costs bytes.
+ *
+ * CHANGED — the divergences that were accidents:
+ * - **Opus channels.** Was 2 (broker preset), 1 (Alexa), 1 (HomeKit). Now 1
+ *   everywhere: every consumer here is a camera microphone, which is mono at
+ *   the source, and encoding a duplicated second channel spent bitrate on
+ *   nothing. The broker's 2 was the outlier and it is the one that changed.
+ * - **Alexa gained `level: '3.1'`.** Its SDP advertises `profile-level-id=
+ *   42e01f` and its encoder was unconstrained. Now it matches.
+ * - **Alexa GOP.** Was 25 frames at 25 fps (1 s); the browser is 30 at 25 fps
+ *   (1.2 s). Both are now expressed as `gopSeconds` × fps so the intent is
+ *   legible; Alexa's numeric GOP is unchanged, the browser's rounds to 30.
+ */
+import type { EncodeProfile } from '../encode-profile.js';
+import type { FfmpegAudioEncodePlan, FfmpegRateControl } from './invocation.js';
+/**
+ * The shape every live egress starts from: H.264 Baseline 3.1 at 720p25.
+ * Baseline because it is the one profile every consumer in this repo decodes
+ * (Echo, iOS, an old browser); 3.1 because that is what the SDPs advertise.
+ */
+export declare const BASE_LIVE_EGRESS_PROFILE: EncodeProfile;
+/**
+ * The browser WebRTC viewer's transcode profile. Used only when the broker
+ * MUST spawn ffmpeg (source codec ∉ the browser-accepted set — an H.265 source
+ * on an H.264-only browser). Audio is `passthrough` because werift carries the
+ * audio plane out-of-band; putting it in the video pipeline would encode a
+ * track nothing reads.
+ */
+export declare const WEBRTC_EGRESS_PROFILE: EncodeProfile;
+/**
+ * Alexa's egress profile. Alexa's audio ALSO rides the WebRTC session's own
+ * audio plane (out-of-band), so this is `passthrough` exactly like the browser
+ * — see the ADR for why the previous in-band Opus was encoded and discarded.
+ */
+export declare const ALEXA_EGRESS_PROFILE: EncodeProfile;
+/** VBV window for a consumer whose budget is enforced per second (HomeKit). */
+export declare const RATE_CONTROL_TIGHT: FfmpegRateControl;
+/** VBV window for a consumer that tolerates a keyframe spike (browser, Echo). */
+export declare const RATE_CONTROL_RELAXED: FfmpegRateControl;
+/**
+ * Transcode-DOWN ceiling: the shape a remote/unhealthy WebRTC session is
+ * reduced to. 360p / 400 kbps is the `low` rung of the adaptive ladder — a
+ * session steered here is already failing, so the ceiling is chosen to survive
+ * a bad link, not to look good.
+ */
+export declare const TRANSCODE_DOWN_MAX_HEIGHT = 360;
+export declare const TRANSCODE_DOWN_MAX_BITRATE_KBPS = 400;
+/**
+ * Camera-microphone audio, per codec. Defined in `./invocation.js` (an import
+ * cycle otherwise) and re-exported here, which is where to read it.
+ */
+export { AUDIO_PRESETS } from './invocation.js';
+/**
+ * HomeKit's two-way audio leg. `lowdelay` + a short frame duration because the
+ * leg is interactive; `globalHeader` because HAP owns the SDP and ffmpeg must
+ * not put extradata in-band. `sampleRateHz` and `frameDurationMs` are
+ * NEGOTIATED per session — the controller picks them — so they are absent here
+ * and filled in by the caller.
+ */
+export declare const HAP_AUDIO_BITRATE_KBPS = 24;
+export declare const HAP_AUDIO_BASE: FfmpegAudioEncodePlan;
+/** HomeKit's `-bufsize` for the audio plane — four seconds of its 24 kbps. */
+export declare const HAP_AUDIO_VBV_KBITS: number;
+/** Seconds between forced IDRs on a HomeKit transcode. */
+export declare const HAP_KEYFRAME_INTERVAL_SEC = 4;