@camstack/types 1.2.43 → 1.2.44

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

@@ -247,6 +247,31 @@ export declare const TrackSourceSchema: z.ZodEnum<{
     pipeline: "pipeline";
 }>;
 export type TrackSource = z.infer<typeof TrackSourceSchema>;
+/**
+ * Where a track sits in the RETRAIN lifecycle (D81).
+ *
+ *  - `none` — never marked, or un-marked. Evictable.
+ *  - `staging` — the operator wants this track as training material and has not
+ *    finished with it. **This is the only state retention holds**: the track and
+ *    everything it owns (object events, crops, keyframes, CLIP vector) survive
+ *    the device's age window.
+ *  - `trained` — the retrain page has taken what it needed. The frames it chose
+ *    were COPIED into the retrain dataset at selection time, so the dataset no
+ *    longer depends on the track's media and the track becomes EVICTABLE again.
+ *    Terminal for the plain `markForTrain` toggle: returning it to `staging` is
+ *    a deliberate action of the retrain page, not a side effect of a checkbox.
+ *
+ * There is no `null`. The state is stored `TEXT NOT NULL DEFAULT 'none'` because
+ * the store's filter language has only positive equality and `whereIn` — no
+ * negation, no IS NULL — so a NULL would be unselectable by ANY predicate and
+ * would make the entire pre-column history immortal in one deploy.
+ */
+export declare const RetrainStatusSchema: z.ZodEnum<{
+    none: "none";
+    staging: "staging";
+    trained: "trained";
+}>;
+export type RetrainStatus = z.infer<typeof RetrainStatusSchema>;
 /**
  * The write half: a PARTIAL patch. An omitted key is left untouched, so setting
  * one flag can never clear the other — the toggles are independent and are
@@ -266,9 +291,45 @@ export declare const TrackFlagsSchema: z.ZodObject<{
     trackId: z.ZodString;
     markForTrain: z.ZodBoolean;
     debug: z.ZodBoolean;
+    retrainStatus: z.ZodEnum<{
+        none: "none";
+        staging: "staging";
+        trained: "trained";
+    }>;
 }, z.core.$strip>;
 export type TrackFlags = z.infer<typeof TrackFlagsSchema>;
+/** Per-camera slice of a training-export estimate. */
+export declare const TrainingExportDeviceTotalsSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    tracks: z.ZodNumber;
+    files: z.ZodNumber;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export type TrainingExportDeviceTotals = z.infer<typeof TrainingExportDeviceTotalsSchema>;
+/**
+ * What a training export WOULD contain. Computed from media index rows only —
+ * no blob is read to produce this.
+ */
+export declare const TrainingExportSummarySchema: z.ZodObject<{
+    generatedAt: z.ZodNumber;
+    trackCount: z.ZodNumber;
+    fileCount: z.ZodNumber;
+    byteCount: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        tracks: z.ZodNumber;
+        files: z.ZodNumber;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type TrainingExportSummary = z.infer<typeof TrainingExportSummarySchema>;
 declare const TrackSchema: z.ZodObject<{
+    retrainStatus: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        staging: "staging";
+        trained: "trained";
+    }>>;
     markForTrain: z.ZodOptional<z.ZodBoolean>;
     debug: z.ZodOptional<z.ZodBoolean>;
     trackId: z.ZodString;
@@ -550,6 +611,11 @@ declare const RecentTracksQueryInput: z.ZodObject<{
 export type RecentTracksQuery = z.infer<typeof RecentTracksQueryInput>;
 declare const RecentTracksPageSchema: z.ZodObject<{
     tracks: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        retrainStatus: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            staging: "staging";
+            trained: "trained";
+        }>>;
         markForTrain: z.ZodOptional<z.ZodBoolean>;
         debug: z.ZodOptional<z.ZodBoolean>;
         trackId: z.ZodString;
@@ -622,6 +688,11 @@ declare const RecentTracksPageSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type RecentTracksPage = z.infer<typeof RecentTracksPageSchema>;
 declare const KeyEventSchema: z.ZodObject<{
+    retrainStatus: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        staging: "staging";
+        trained: "trained";
+    }>>;
     markForTrain: z.ZodOptional<z.ZodBoolean>;
     debug: z.ZodOptional<z.ZodBoolean>;
     id: z.ZodString;
@@ -744,6 +815,11 @@ export declare const pipelineAnalyticsCapability: {
         readonly getActiveTracks: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            retrainStatus: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                staging: "staging";
+                trained: "trained";
+            }>>;
             markForTrain: z.ZodOptional<z.ZodBoolean>;
             debug: z.ZodOptional<z.ZodBoolean>;
             trackId: z.ZodString;
@@ -816,6 +892,11 @@ export declare const pipelineAnalyticsCapability: {
             deviceId: z.ZodNumber;
             trackId: z.ZodString;
         }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            retrainStatus: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                staging: "staging";
+                trained: "trained";
+            }>>;
             markForTrain: z.ZodOptional<z.ZodBoolean>;
             debug: z.ZodOptional<z.ZodBoolean>;
             trackId: z.ZodString;
@@ -910,6 +991,11 @@ export declare const pipelineAnalyticsCapability: {
                 slim: "slim";
             }>>;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            retrainStatus: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                staging: "staging";
+                trained: "trained";
+            }>>;
             markForTrain: z.ZodOptional<z.ZodBoolean>;
             debug: z.ZodOptional<z.ZodBoolean>;
             trackId: z.ZodString;
@@ -1000,6 +1086,11 @@ export declare const pipelineAnalyticsCapability: {
             }>>;
         }, z.core.$strip>, z.ZodObject<{
             tracks: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                retrainStatus: z.ZodOptional<z.ZodEnum<{
+                    none: "none";
+                    staging: "staging";
+                    trained: "trained";
+                }>>;
                 markForTrain: z.ZodOptional<z.ZodBoolean>;
                 debug: z.ZodOptional<z.ZodBoolean>;
                 trackId: z.ZodString;
@@ -1323,6 +1414,11 @@ export declare const pipelineAnalyticsCapability: {
             minImportance: z.ZodOptional<z.ZodNumber>;
             classFilter: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            retrainStatus: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                staging: "staging";
+                trained: "trained";
+            }>>;
             markForTrain: z.ZodOptional<z.ZodBoolean>;
             debug: z.ZodOptional<z.ZodBoolean>;
             id: z.ZodString;
@@ -1434,11 +1530,29 @@ export declare const pipelineAnalyticsCapability: {
          *
          * `auth: 'protected'` (the default), NOT `admin`: the viewer is an
          * authenticated non-admin surface and two of the three call sites are
-         * there. Revisit if a flag ever gains an effect that costs storage —
-         * `deleteTracks` next door is admin for exactly that reason.
+         * there. The note that used to sit here said to revisit this the day a flag
+         * gained an effect that costs storage, and D81 is that day — `markForTrain`
+         * now pins. It STAYS protected, and the reason is that the alternative
+         * makes the feature pointless: marking a track is something you do while
+         * looking at it, on the surface you were already looking at it on, and that
+         * surface is the viewer. What the storage cost gets instead is a BOUND — a
+         * per-device pin budget enforced in the body, refusing a new pin past the
+         * limit while always allowing un-marking. `deleteTracks` next door is still
+         * admin, because destroying evidence and preserving it are not symmetric.
          *
-         * Returns the RESOLVED state of both flags (absent → `false`) so a caller
-         * can drive its toggle without a re-fetch. Rejects an unknown track.
+         * `markForTrain` writes the retrain LIFECYCLE, not a boolean column: `true`
+         * is `none → staging`, `false` is `staging → none`. A track already
+         * `trained` refuses BOTH — its frames are copies inside the retrain dataset
+         * and re-staging it from a generic toggle is how the same material gets
+         * annotated twice under two ground truths. Returning a trained track to
+         * staging is a deliberate action of the retrain page, which is also the only
+         * thing that produces `trained` in the first place.
+         *
+         * Returns the RESOLVED state of both flags (absent → `false`) plus the
+         * `retrainStatus` they were derived from, so a caller can drive its toggle
+         * — and render a `trained` badge — without a re-fetch. Rejects an unknown
+         * track, a new staging mark on a device already holding its full budget, and
+         * any `markForTrain` write against a trained track.
          */
         readonly setTrackFlags: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
@@ -1451,6 +1565,11 @@ export declare const pipelineAnalyticsCapability: {
             trackId: z.ZodString;
             markForTrain: z.ZodBoolean;
             debug: z.ZodBoolean;
+            retrainStatus: z.ZodEnum<{
+                none: "none";
+                staging: "staging";
+                trained: "trained";
+            }>;
         }, z.core.$strip>, "mutation">;
         /**
          * Durable event-store footprint for the management UI: event rows
@@ -1570,6 +1689,54 @@ export declare const pipelineAnalyticsCapability: {
             detail: z.ZodNullable<z.ZodString>;
             actor: z.ZodString;
         }, z.core.$strip>>>, "query">;
+        /**
+         * The CHEAP QUESTION, asked before any media moves: how big is the dataset
+         * the marked (`markForTrain`) tracks would produce?
+         *
+         * Answered from media INDEX rows only — key, kind, size, timestamp — so it
+         * costs ~2 KB of reads per track and no blob reads at all. The measured harm
+         * behind D56 was a bulk pass that read and base64'd every blob a track owned
+         * before deciding anything, taking hub-main to 82 s busy out of 120; an
+         * export is that same I/O shape, so it inherits the same discipline: know
+         * the size, then decide.
+         *
+         * `truncated` reports that more marked tracks exist than one pass carries.
+         * Empty `deviceIds` ⇒ every device that has marked tracks.
+         */
+        readonly getTrainingExportSummary: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodObject<{
+            generatedAt: z.ZodNumber;
+            trackCount: z.ZodNumber;
+            fileCount: z.ZodNumber;
+            byteCount: z.ZodNumber;
+            truncated: z.ZodBoolean;
+            devices: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                tracks: z.ZodNumber;
+                files: z.ZodNumber;
+                bytes: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>, "query">;
+        /**
+         * Where to download the dataset archive.
+         *
+         * The BYTES do not come back through this cap — they come from the returned
+         * data-plane URL, which streams a tar built entry by entry. A multi-gigabyte
+         * archive base64'd through a unary RPC envelope would be held whole in
+         * memory twice on a hub this repo has already OOM'd once (D9/D18 are the
+         * same lesson about frames). `getDownloadUrl` on `recordingExport` is the
+         * precedent, and this follows it deliberately.
+         *
+         * The archive contains a `manifest.json` FIRST, then the stored media
+         * VERBATIM under `tracks/<deviceId>/<trackId>/…`. No crop is derived and no
+         * model is run: a training set's pixels must be the pixels the pipeline saw.
+         */
+        readonly getTrainingExportUrl: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>, "query">;
         readonly getEventMedia: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             eventId: z.ZodString;
             kind: z.ZodOptional<z.ZodEnum<{

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

@@ -449,6 +449,7 @@ declare const CameraStatusSchema: z.ZodObject<{
         notifications: "notifications";
         "object-detection": "object-detection";
         "device-audio": "device-audio";
+        "broker-audio": "broker-audio";
     }>>>;
     fetchedAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -1099,6 +1100,7 @@ export declare const pipelineOrchestratorCapability: {
                     notifications: "notifications";
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
+                    "broker-audio": "broker-audio";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1124,6 +1126,8 @@ export declare const pipelineOrchestratorCapability: {
                 }, z.core.$strip>, z.ZodObject<{
                     kind: z.ZodLiteral<"camera-mask">;
                     capName: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"broker-audio-mute">;
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>>;
             fetchedAt: z.ZodNumber;
@@ -1151,6 +1155,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>;
             enabled: z.ZodBoolean;
         }, z.core.$strip>, z.ZodObject<{
@@ -1164,6 +1169,7 @@ export declare const pipelineOrchestratorCapability: {
                     notifications: "notifications";
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
+                    "broker-audio": "broker-audio";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1189,6 +1195,8 @@ export declare const pipelineOrchestratorCapability: {
                 }, z.core.$strip>, z.ZodObject<{
                     kind: z.ZodLiteral<"camera-mask">;
                     capName: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"broker-audio-mute">;
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>>;
             fetchedAt: z.ZodNumber;
@@ -1310,6 +1318,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>>>;
             fetchedAt: z.ZodNumber;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
@@ -1429,6 +1438,7 @@ export declare const pipelineOrchestratorCapability: {
                 notifications: "notifications";
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
+                "broker-audio": "broker-audio";
             }>>>;
             fetchedAt: z.ZodNumber;
         }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;

package/dist/capabilities/schemas/streaming-shared.d.ts

@@ -317,6 +317,8 @@ export declare const BrokerStatsSchema: z.ZodObject<{
         channels: z.ZodNumber;
         supported: z.ZodBoolean;
     }, z.core.$strip>>>;
+    audioMuted: z.ZodOptional<z.ZodBoolean>;
+    audioMutedDropped: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /**
  * Exporter-facing "profile restream" entry. Returned by

package/dist/capabilities/server-management.cap.d.ts

@@ -50,8 +50,8 @@ declare const ServerBootModeSchema: z.ZodEnum<{
  */
 declare const ServerUpdateStateSchema: z.ZodEnum<{
     idle: "idle";
-    checking: "checking";
     staging: "staging";
+    checking: "checking";
     "pending-restart": "pending-restart";
     "awaiting-confirmation": "awaiting-confirmation";
 }>;
@@ -123,8 +123,8 @@ declare const ServerPackageStatusSchema: z.ZodObject<{
     }>;
     updateState: z.ZodEnum<{
         idle: "idle";
-        checking: "checking";
         staging: "staging";
+        checking: "checking";
         "pending-restart": "pending-restart";
         "awaiting-confirmation": "awaiting-confirmation";
     }>;
@@ -189,8 +189,8 @@ export declare const serverManagementCapability: {
             }>;
             updateState: z.ZodEnum<{
                 idle: "idle";
-                checking: "checking";
                 staging: "staging";
+                checking: "checking";
                 "pending-restart": "pending-restart";
                 "awaiting-confirmation": "awaiting-confirmation";
             }>;

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

@@ -689,6 +689,8 @@ export declare const streamBrokerCapability: {
                 channels: z.ZodNumber;
                 supported: z.ZodBoolean;
             }, z.core.$strip>>>;
+            audioMuted: z.ZodOptional<z.ZodBoolean>;
+            audioMutedDropped: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Force a one-shot probe of a single source stream: transiently dial the
@@ -1151,6 +1153,36 @@ export declare const streamBrokerCapability: {
         readonly isRtspEnabled: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             brokerId: z.ZodString;
         }, z.core.$strip>, z.ZodBoolean, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * ── Per-device audio-plane policy (D83) ───────────────────────────
+         *
+         * The BROKER-side mute: while `muted`, this node distributes none of
+         * the device's audio, on any plane it serves — live (WebRTC / encoded
+         * subscribers) AND recording (the RTSP restreamer the recorder pulls,
+         * which additionally serves the video-only SDP so the recorder's ffmpeg
+         * never declares an audio stream it will not receive).
+         *
+         * Keyed by `deviceId`, not `brokerId`: every one of a camera's streams
+         * carries the same microphone, and a per-stream answer would let main
+         * and sub disagree about whether the camera is silent.
+         *
+         * The state lives in the broker's existing `DeviceOverride` blob — no
+         * new store — and the mute is applied to a fresh broker at creation, so
+         * a restart, a re-dial or a catalog republish never un-mutes a camera.
+         */
+        readonly getDeviceAudioMute: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            muted: z.ZodBoolean;
+            appliedBrokers: z.ZodNumber;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        readonly setDeviceAudioMute: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            muted: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            muted: z.ZodBoolean;
+            appliedBrokers: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
     };
     readonly events: {
         readonly onCamStreamDemand: import("./capability-definition.js").CapabilityEventSchema<z.ZodObject<{

package/dist/ffmpeg/fmp4-box-splitter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Fmp4BoxSplitter — cut an ffmpeg fragmented-MP4 byte stream into the units a
+ * consumer of fragments actually needs: ONE initialisation segment
+ * (`ftyp`+`moov`) followed by one unit per `moof`+`mdat` pair.
+ *
+ * This is the shape HomeKit Secure Video's `CameraRecordingDelegate` yields
+ * (`RecordingPacket` #0 is the initialisation, the rest are media fragments),
+ * and it is the same shape a CamStack clip source wants — which is the point.
+ * One fragmenter, two consumers ([roadmap 4b](../../../../../docs/roadmap.md)).
+ * The splitter therefore knows about NEITHER of them: it emits units, and
+ * {@link import('./fmp4-fragment-plane.js').Fmp4FragmentPlane} decides who gets
+ * them.
+ *
+ * ## Pure, streaming, bounded
+ *
+ * No I/O, no timers, no ffmpeg. `push` takes whatever bytes arrived and returns
+ * whatever units completed — a caller may hand it one byte at a time or a
+ * megabyte, and the units are identical either way (asserted). Memory is
+ * bounded by {@link Fmp4SplitterOptions.maxUnitBytes}: the splitter holds at
+ * most one in-progress unit plus a partial box, and a stream that exceeds the
+ * bound FAULTS rather than growing, because the alternative on a live 24/7
+ * source is the broker's heap.
+ *
+ * ## The box rules, from ISO/IEC 14496-12
+ *
+ * A box header is `size:uint32` + `type:4 chars`. `size == 1` means the real
+ * size is a `uint64` in the next 8 bytes; `size == 0` means "to end of file".
+ * A size-0 box is a FAULT here and not a special case: it cannot be cut into
+ * fragments at all, and pretending otherwise would produce one enormous unit
+ * whose bytes never arrive.
+ *
+ * ## What it does NOT do
+ *
+ * It never inspects `tfdt`/`trun` and never computes a fragment's duration. The
+ * fragment length is decided upstream by the muxer (`-min_frag_duration` plus a
+ * key-frame grid, see `@camstack/types` `ffmpeg/invocation.ts`), and a duration
+ * parsed here would be a SECOND opinion about the same fact — the failure mode
+ * D67 exists to prevent. A consumer that must verify conformance measures the
+ * arrival cadence, which is the thing it actually cares about.
+ */
+/** `init` is the `ftyp`+`moov` head; `fragment` is one `moof`+`mdat` pair. */
+export type Fmp4UnitKind = 'init' | 'fragment';
+export interface Fmp4Unit {
+    readonly kind: Fmp4UnitKind;
+    /** A standalone copy — the splitter never hands out a view into its buffer. */
+    readonly data: Uint8Array;
+    /** `0` for the initialisation segment, then `1, 2, 3…` per fragment. */
+    readonly sequence: number;
+}
+export interface Fmp4SplitterOptions {
+    /**
+     * The most bytes one unit may reach before the stream is declared unusable.
+     * A 4-second 1080p fragment is a few hundred KB; the default leaves three
+     * orders of magnitude of headroom and still bounds a source that is not
+     * really fMP4 (a plain MP4 with a trailing `moov`, say, whose single `mdat`
+     * is the entire recording).
+     */
+    readonly maxUnitBytes?: number;
+}
+export declare class Fmp4BoxSplitter {
+    private readonly maxUnitBytes;
+    /** Bytes of the CURRENT unit plus any partial box after it. */
+    private buffer;
+    /** Where the current unit starts inside {@link buffer}. */
+    private unitStart;
+    /** Where the box scanner has reached inside {@link buffer}. */
+    private cursor;
+    private state;
+    private nextSequence;
+    private faultReason;
+    private readonly interstitial;
+    constructor(options?: Fmp4SplitterOptions);
+    /**
+     * Non-null once the stream cannot be split. The splitter emits nothing
+     * further, so a caller polls this to kill the child rather than watching a
+     * silent stall — a fragmenter that quietly stops producing looks exactly like
+     * a camera with no motion.
+     */
+    get fault(): string | null;
+    /** Bytes currently held. The memory bound, observable rather than asserted. */
+    get pendingBytes(): number;
+    /**
+     * Top-level box types seen BETWEEN fragments and discarded — `mfra`, `free`,
+     * a stray `sidx`. Reported rather than dropped in silence: they are legal and
+     * useless to a fragment consumer, but a type nobody expected showing up here
+     * is the first symptom of a muxer that is not writing what we think it is.
+     */
+    get discardedInterstitialTypes(): readonly string[];
+    /**
+     * Feed bytes; get back whatever units completed. Returns `[]` once faulted.
+     */
+    push(chunk: Uint8Array): readonly Fmp4Unit[];
+    private append;
+    /** Consume every COMPLETE top-level box now in the buffer. */
+    private drainBoxes;
+    /**
+     * Apply one box to the state machine. Returns a unit when this box CLOSED
+     * one, `null` otherwise.
+     */
+    private consumeBox;
+    /**
+     * Parse the header at {@link cursor}, or `null` when too few bytes have
+     * arrived to know. Faults on a size the splitter cannot honour.
+     */
+    private readHeader;
+    private emit;
+    /**
+     * Drop everything already emitted or discarded. Without this the buffer is
+     * the whole stream and the process dies in hours, not minutes.
+     */
+    private compact;
+    private fail;
+}

package/dist/ffmpeg/fmp4-fragment-child.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Fmp4FragmentChild — one ffmpeg writing a fragmented MP4 to stdout, split into
+ * units and fanned out on a {@link Fmp4FragmentPlane}.
+ *
+ * ## Why this lives in the PRIMITIVE and not in the broker
+ *
+ * It was written as the stream-broker's third egress transport, on the premise
+ * ([D80](../../../../docs/decisions/adr-0080.md)) that its consumers would be
+ * in-process with the broker and could hold a live plane object. **They are
+ * not.** `addon-export-hap` — the HKSV recording delegate, the first real
+ * consumer — is a `hub-only` addon in its OWN runner ([D2](../../../../docs/decisions/adr-0002.md)),
+ * and a plane cannot cross a process boundary. The choice was a second copy of
+ * the splitter in the exporter, or one copy here beside the sink that produces
+ * the bytes. The sink, the splitter, the plane and this child are one primitive
+ * ([D84](../../../../docs/decisions/adr-0084.md)); `EgressTranscodeManager`
+ * keeps only what is broker business — sharing key, refcount, release grace.
+ *
+ * It is deliberately the same shape as `TranscodeEgress` (the dial transport)
+ * and `createPushChild` (the push one), because the three failures that cost
+ * sessions on those paths are the same three here:
+ *
+ *  - **It resolves on the first UNIT, never on the first byte.** A child whose
+ *    bytes do not parse as fMP4 is a child that will never produce a fragment,
+ *    and resolving on bytes hands the caller a handle nothing feeds.
+ *  - **It retries once in SOFTWARE.** `-hwaccel vaapi` fails to create a device
+ *    inside the stream-broker runner on the live hub (`code=244`), and the push
+ *    transport was dark for exactly as long as it lacked this retry.
+ *  - **A child that dies AFTER going live says so.** Silence reads as "it is
+ *    running"; the plane must be ended so a consumer's generator completes
+ *    rather than hanging on a producer that no longer exists.
+ *
+ * Two consumers: `EgressTranscodeManager.acquireFragments` (the broker, for a
+ * future CamStack clip source — roadmap 4b half 2) and `HksvFragmentSource` in
+ * `addon-export-hap`. It stays unreachable from `acquireEgressTranscode`'s
+ * request schema on purpose (see `egressTransportFromRequest`): a plane is a
+ * live object, so an off-node caller could not use one anyway.
+ */
+import type { spawn as nodeSpawn } from 'node:child_process';
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { FfmpegInvocation } from './invocation.js';
+import type { Fmp4FragmentPlane } from './fmp4-fragment-plane.js';
+export interface Fmp4FragmentChildDeps {
+    readonly logger: IScopedLogger;
+    readonly ffmpegBinaryPath: string;
+    readonly spawnFn: typeof nodeSpawn;
+    /** How long the child may produce no UNIT before it is declared dead. */
+    readonly firstUnitTimeoutMs?: number;
+    /** The child exited, or its output stopped parsing, AFTER it went live. */
+    readonly onChildExit?: (error: Error) => void;
+}
+export interface Fmp4FragmentChildArgs {
+    readonly sourceId: string;
+    /** Every line about this child is grouped per camera, without exception. */
+    readonly deviceId: number;
+    /** The negotiated fragment length — argv only; the splitter never reads it. */
+    readonly fragmentMs: number;
+    /** The invocation minus the sink, which this child owns. */
+    readonly invocation: Omit<FfmpegInvocation, 'sink' | 'audioSidecar'>;
+    /** Where the units go. Owned by the caller, ended by this child. */
+    readonly plane: Fmp4FragmentPlane;
+}
+export declare class Fmp4FragmentChild {
+    private readonly deps;
+    private readonly args;
+    private child;
+    private splitter;
+    private stopped;
+    private unitsOut;
+    private activeHwAccel;
+    constructor(deps: Fmp4FragmentChildDeps, args: Fmp4FragmentChildArgs);
+    /** Spawn, and resolve once the INIT segment has been cut out of stdout. */
+    start(): Promise<void>;
+    /** The backend the child ACTUALLY ran with — `null` for software. */
+    activeDecodeHwAccel(): string | null;
+    /** Kill ffmpeg and end the plane. Idempotent. */
+    stop(): Promise<void>;
+    private spawnAttempt;
+    /**
+     * The byte stream stopped being splittable. Not recoverable — the splitter
+     * cannot resynchronise mid-box — so the child is a corpse and every consumer
+     * has to be told, loudly, with the reason.
+     */
+    private onFault;
+    private killChild;
+}