@homebridge-plugins/homebridge-eufy-security 5.0.0-beta.35 → 5.0.0-beta.36

package/dist/diagnostics.js

@@ -417,6 +417,10 @@ function boundedText(value, maximumLength) {
         .trim();
     return printable === '' ? undefined : printable;
 }
+/** Whether a value is a plain JSON object, which is the only shape a record crossing a process boundary has. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function fleetPath(storageRoot) {
     return join(storageRoot, DIAGNOSTICS_DIRECTORY, FLEET_FILE);
 }
@@ -443,10 +447,9 @@ function readFleet(storageRoot) {
         if (candidate.version !== 1 || !Array.isArray(candidate.devices)) {
             return undefined;
         }
-        const devices = candidate.devices.flatMap((entry) => {
-            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        const devices = candidate.devices.flatMap((row) => {
+            if (!isRecord(row))
                 return [];
-            const row = entry;
             const accessory = opaqueAccessoryAlias(row.accessory);
             if (accessory === undefined || typeof row.represented !== 'boolean' || typeof row.attached !== 'boolean') {
                 return [];
@@ -532,19 +535,16 @@ function readHostEnvironment(storageRoot) {
  * entire purpose of the record and a redacted one answers nothing. Neither is device or account material: the
  * path is this plugin's own setting or the binary it ships, and the banner is that build's public identity.
  */
-function readFfmpegIdentity(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+function readFfmpegIdentity(recorded) {
+    if (!isRecord(recorded)) {
         return undefined;
     }
-    const recorded = value;
     if (recorded.source !== 'bundled' && recorded.source !== 'configured') {
         return undefined;
     }
     const path = typeof recorded.path === 'string' ? boundedText(recorded.path, MAX_FFMPEG_IDENTITY_LENGTH) : undefined;
     const version = typeof recorded.version === 'string' ? boundedText(recorded.version, MAX_FFMPEG_IDENTITY_LENGTH) : undefined;
-    const encoders = recorded.encoders && typeof recorded.encoders === 'object' && !Array.isArray(recorded.encoders)
-        ? readEncoderQualification(recorded.encoders)
-        : undefined;
+    const encoders = isRecord(recorded.encoders) ? readEncoderQualification(recorded.encoders) : undefined;
     return path === undefined
         ? undefined
         : {
@@ -556,18 +556,23 @@ function readFfmpegIdentity(value) {
 }
 /**
  * The recorded encoder qualification, keeping only encoder names, `profile@level` selections and outcomes this
- * build names, so the record is bounded by those three closed sets.
+ * build names, so the record is bounded by those three closed sets, and a `bytes` outcome's two integers.
  */
 function readEncoderQualification(recorded) {
     return Object.fromEntries(LIVE_VIDEO_ENCODERS.filter((name) => Object.hasOwn(recorded, name)).map((name) => {
-        const outcomes = recorded[name] && typeof recorded[name] === 'object' ? Object.entries(recorded[name]) : [];
+        const outcomes = isRecord(recorded[name]) ? Object.entries(recorded[name]) : [];
         return [
             name,
             Object.fromEntries(outcomes.flatMap(([selection, value]) => {
                 const [profile, level] = selection.split('@');
-                const outcome = allowlistedLabel(value, QUALIFICATION_OUTCOMES);
-                return HOMEKIT_LIVE_VIDEO_PROFILES.has(profile) &&
-                    HOMEKIT_LIVE_VIDEO_LEVELS.has(level) &&
+                const outcome = Array.isArray(value) &&
+                    value.length === 3 &&
+                    value[0] === 'bytes' &&
+                    value.slice(1).every(Number.isSafeInteger)
+                    ? value
+                    : allowlistedLabel(value, QUALIFICATION_OUTCOMES);
+                return allowlistedLabel(profile, HOMEKIT_LIVE_VIDEO_PROFILES) &&
+                    allowlistedLabel(level, HOMEKIT_LIVE_VIDEO_LEVELS) &&
                     selection === `${profile}@${level}` &&
                     outcome
                     ? [[selection, outcome]]
@@ -1231,8 +1236,8 @@ export class GuidedDiagnostics {
         await this.replaceOwnedFile(join(directory, REPRODUCTION_MARKERS_FILE), `${retained}${marker}`);
     }
 }
-function formatMessage(catalog, key, parameters = {}) {
-    const template = catalog[key] ?? EN_MESSAGES[key] ?? key;
+function formatMessage(key, parameters = {}) {
+    const template = EN_MESSAGES[key] ?? key;
     return template
         .replace(/\{([a-zA-Z0-9]+)\}/g, (placeholder, name) => parameters[name] === undefined ? placeholder : String(parameters[name]))
         .replace(/\s+/g, ' ')
@@ -1240,7 +1245,7 @@ function formatMessage(catalog, key, parameters = {}) {
 }
 function localize(target, key, parameters = {}) {
     const translator = target.localize;
-    return translator?.(key, parameters) ?? formatMessage(EN_MESSAGES, key, parameters);
+    return translator?.(key, parameters) ?? formatMessage(key, parameters);
 }
 class JsonLineLog {
     onError;
@@ -1257,11 +1262,8 @@ class JsonLineLog {
         this.directory = join(storageRoot, LOG_DIRECTORY);
         this.path = join(this.directory, LOG_FILE);
     }
-    write(message) {
-        const payload = sanitizeStructuredEvent(message);
-        if (!payload) {
-            return;
-        }
+    /** Queues one record the sanitizer already rebuilt. */
+    write(payload) {
         const record = this.serialize(payload);
         const bytes = Buffer.byteLength(record);
         if (bytes > MAX_LOG_RECORD_BYTES || this.queuedBytes + bytes > MAX_QUEUED_LOG_BYTES) {
@@ -1269,21 +1271,12 @@ class JsonLineLog {
             this.droppedRecords += 1;
             return;
         }
-        const droppedRecords = this.droppedRecords;
-        const droppedAt = this.droppedAt;
-        this.droppedRecords = 0;
-        this.droppedAt = undefined;
+        const dropped = this.drainDropped();
         this.queuedBytes += bytes;
         this.pending = this.pending
             .then(async () => {
-            if (droppedRecords > 0) {
-                await this.append(this.serialize({
-                    scope: 'diagnostics',
-                    level: 'warn',
-                    event: 'records-dropped',
-                    droppedRecords,
-                }, droppedAt));
-            }
+            if (dropped)
+                await this.append(dropped);
             await this.append(record);
         })
             .catch(() => this.onError())
@@ -1292,22 +1285,21 @@ class JsonLineLog {
         });
     }
     flush() {
-        const droppedRecords = this.droppedRecords;
-        const droppedAt = this.droppedAt;
-        this.droppedRecords = 0;
-        this.droppedAt = undefined;
-        if (droppedRecords > 0) {
-            this.pending = this.pending
-                .then(() => this.append(this.serialize({
-                scope: 'diagnostics',
-                level: 'warn',
-                event: 'records-dropped',
-                droppedRecords,
-            }, droppedAt)))
-                .catch(() => this.onError());
+        const dropped = this.drainDropped();
+        if (dropped) {
+            this.pending = this.pending.then(() => this.append(dropped)).catch(() => this.onError());
         }
         return this.pending;
     }
+    /** The `records-dropped` record for what was refused since the last one, resetting the tally, or nothing. */
+    drainDropped() {
+        const { droppedRecords, droppedAt } = this;
+        this.droppedRecords = 0;
+        this.droppedAt = undefined;
+        return droppedRecords === 0
+            ? undefined
+            : this.serialize({ scope: 'diagnostics', level: 'warn', event: 'records-dropped', droppedRecords }, droppedAt);
+    }
     serialize(payload, timestamp = new Date(this.now()).toISOString()) {
         return `${JSON.stringify({ ...payload, timestamp })}\n`;
     }
@@ -1366,12 +1358,12 @@ class JsonLineLog {
  * Routes human messages to Homebridge and structured events to the plugin JSONL log.
  * File writes preserve accepted order; records beyond the bounded pending queue are counted and reported.
  */
-export function createDiagnosticLogger(target, storageRoot, catalog = EN_MESSAGES, now = Date.now) {
+export function createDiagnosticLogger(target, storageRoot, now = Date.now) {
     let fileFailureReported = false;
     const reportFileFailure = () => {
         if (!fileFailureReported) {
             fileFailureReported = true;
-            target.warn(`[diagnostic-log-write-failed] ${formatMessage(catalog, 'log.diagnosticFileFailed')}`);
+            target.warn(`[diagnostic-log-write-failed] ${formatMessage('log.diagnosticFileFailed')}`);
         }
     };
     const file = storageRoot ? new JsonLineLog(storageRoot, reportFileFailure, now) : undefined;
@@ -1385,7 +1377,7 @@ export function createDiagnosticLogger(target, storageRoot, catalog = EN_MESSAGE
             if (verbose && (!session || !DIAGNOSTICS_PROFILES[session.profile].includes(evidenceClassOf(event)))) {
                 return;
             }
-            file.write(JSON.stringify(event));
+            file.write(event);
         }
         : undefined;
     return {
@@ -1393,7 +1385,7 @@ export function createDiagnosticLogger(target, storageRoot, catalog = EN_MESSAGE
         error: (message) => target.error(message),
         flush: () => file?.flush() ?? Promise.resolve(),
         info: (message) => target.info(message),
-        localize: (key, parameters) => formatMessage(catalog, key, parameters),
+        localize: (key, parameters) => formatMessage(key, parameters),
         warn: (message) => target.warn(message),
     };
 }
@@ -1531,6 +1523,7 @@ const LIVE_TRACE_PHASES = {
     'sequence-restart': retainedInteger('dataType', 3),
     'level2-wait': retainedInteger('waitMs', MAX_STARTUP_WINDOW_MS),
     'level2-ready': retainedInteger('cipherId', 65535),
+    'level2-set-payload-only': retainedInteger('cipherId', 65535),
     'session-connect-wait': retainedInteger('waitMs', MAX_STARTUP_WINDOW_MS),
     'session-connected': retainedInteger('waitedMs', MAX_STARTUP_WINDOW_MS),
     'session-unreachable': retainedInteger('waitedMs', MAX_STARTUP_WINDOW_MS),
@@ -1622,16 +1615,22 @@ const LIVE_TRACE_PHASES = {
         const reason = allowlistedLabel(c.reason, ['level2-key', 'address']);
         return reason ? { reason } : undefined;
     },
+    /** `errorName` is an upstream class name, so it stays out of the archive; reason and stage say enough. */
+    'start-failed': (c) => {
+        const reason = allowlistedLabel(c.reason, ['warm-timeout', 'source-error', 'source-ended']);
+        const stage = allowlistedLabel(c.stage, ['awaiting-first-frame', 'audio-only', 'awaiting-keyframe']);
+        const attempts = boundedInteger(c.attempts, 1000);
+        return reason && stage && attempts !== undefined ? { reason, stage, attempts } : undefined;
+    },
     warming: (c) => {
         const retryMs = boundedInteger(c.retryMs, MAX_STARTUP_WINDOW_MS);
         const deadlineMs = boundedInteger(c.deadlineMs, MAX_STARTUP_WINDOW_MS);
         return retryMs === undefined || deadlineMs === undefined ? undefined : { retryMs, deadlineMs };
     },
 };
-function sanitizeSdkLiveStartTrace(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
+function sanitizeSdkLiveStartTrace(candidate) {
+    if (!isRecord(candidate))
         return undefined;
-    const candidate = value;
     const phase = String(candidate.phase);
     if (!Object.hasOwn(LIVE_TRACE_PHASES, phase))
         return undefined;
@@ -1885,7 +1884,7 @@ const HOMEKIT_EVENT_ROUTES = {
     'camera.streaming': new Set(['camera-enabled-changed']),
     'camera.controls': new Set(['camera-enabled-changed']),
 };
-const HOMEKIT_OBSERVATIONS = new Set(['malformed', 'missing', 'valid']);
+const HOMEKIT_OBSERVATIONS = new Set(['malformed', 'missing', 'valid', 'ignored']);
 /**
  * What announced a change, for an adapter that follows more than one announcement for the same state.
  *
@@ -1893,9 +1892,9 @@ const HOMEKIT_OBSERVATIONS = new Set(['malformed', 'missing', 'valid']);
  * field is omitted where an adapter states no announcement and refused where it states one absent from here.
  */
 const HOMEKIT_ANNOUNCEMENTS = new Set(['write', 'poll']);
-const HOMEKIT_LIVE_VIDEO_OPERATIONS = new Set(['start', 'reconfigure']);
-const HOMEKIT_LIVE_VIDEO_PROFILES = new Set(['baseline', 'main', 'high']);
-const HOMEKIT_LIVE_VIDEO_LEVELS = new Set(['3.1', '3.2', '4.0']);
+const HOMEKIT_LIVE_VIDEO_OPERATIONS = ['start', 'reconfigure'];
+const HOMEKIT_LIVE_VIDEO_PROFILES = ['baseline', 'main', 'high'];
+const HOMEKIT_LIVE_VIDEO_LEVELS = ['3.1', '3.2', '4.0'];
 /**
  * The inclusive bounds a controller-selected live geometry and frame rate are retained within.
  *
@@ -1919,13 +1918,13 @@ const MAX_LIVE_VIDEO_MTU = 65_535;
 /** The bit rate ceiling a controller negotiated, in kbps, bounded to the unsigned 16-bit field that carries it. */
 const MAX_LIVE_VIDEO_BIT_RATE = 65_535;
 /** The two address families HomeKit negotiates a destination in. */
-const HOMEKIT_LIVE_ADDRESS_VERSIONS = new Set(['ipv4', 'ipv6']);
-const HOMEKIT_LIVE_SESSION_STAGES = new Set([
+const HOMEKIT_LIVE_ADDRESS_VERSIONS = ['ipv4', 'ipv6'];
+const HOMEKIT_LIVE_SESSION_STAGES = [
     'sdk-source-acquisition',
     'first-source-keyframe',
     'first-adapted-output',
     'controller-rtcp',
-]);
+];
 /** The SDK's own stage and reason for a live warm-up that ended without a keyframe. */
 const SDK_LIVE_START_STAGES = ['awaiting-first-frame', 'audio-only', 'awaiting-keyframe'];
 const SDK_LIVE_START_REASONS = ['warm-timeout', 'source-error', 'source-ended'];
@@ -1935,7 +1934,16 @@ const SDK_LIVE_START_REASONS = ['warm-timeout', 'source-error', 'source-ended'];
  * A superset of what the media domain can report, because the SDK runs FFmpeg of its own for snapshot
  * decoding and WebRTC containers and forwards its output here under the same evidence class.
  */
-const ADAPTATION_ROLES = new Set(['live-video', 'live-audio', 'return-audio', 'recording', 'sdk']);
+const ADAPTATION_ROLES = new Set([
+    'live-video',
+    'live-audio',
+    'return-audio',
+    'recording',
+    'preview-encode',
+    'preview-decode',
+    'preview-raw',
+    'sdk',
+]);
 /** What that process did. `output` is a process reported for what it wrote rather than for how it ended. */
 const ADAPTATION_EVENTS = new Set([
     'started',
@@ -1946,6 +1954,16 @@ const ADAPTATION_EVENTS = new Set([
     'exited-while-streaming',
     'output',
 ]);
+/** How a settings-page live preview ended. */
+const PREVIEW_OUTCOMES = ['picture', 'unplayable', 'no-video', 'stopped'];
+/** The iPhone asks a live preview codes for, and the live video settings it may try. */
+const PREVIEW_ASKS = ['wifi', 'cellular'];
+const PREVIEW_SETTINGS = [
+    'smallVideoPackets',
+    'liveVideoPassthrough',
+    'hardwareVideoEncoder',
+    'ignoreHomeBitRate',
+];
 /**
  * Why a process was started, on the record that reports it starting.
  *
@@ -1964,7 +1982,7 @@ const LIVE_VIDEO_ENCODERS = [
     'h264_vaapi',
     'h264_v4l2m2m',
 ];
-/** What qualifying a hardware encoder for one selection found: `qualified`, or the first check it failed. */
+/** What qualifying a hardware encoder for one selection found, but `bytes`, which is read with its two integers. */
 const QUALIFICATION_OUTCOMES = [
     'qualified',
     'budget',
@@ -1974,7 +1992,6 @@ const QUALIFICATION_OUTCOMES = [
     'level',
     'geometry',
     'frames',
-    'bytes',
 ];
 /** The codec a live video source delivers. */
 const LIVE_VIDEO_SOURCES = ['h264', 'h265', 'av1'];
@@ -2019,74 +2036,32 @@ const ADAPTATION_SIGNALS = new Set([
 const MAX_ADAPTATION_STDERR_LINES = 8;
 const MAX_ADAPTATION_STDERR_LINE_LENGTH = 200;
 /**
- * The media notices this module retains, read by both halves of the path.
+ * The fixed-shape operational notices, each `[level, messageKey, durationMessageKey?]`.
  *
  * Operational rather than verbose, so each is `plugin-log` evidence that every profile declares.
  */
-const MEDIA_NOTICES = {
-    'camera-snapshot-cache-invalid': {
-        level: 'warn',
-        messageKey: 'log.snapshotCacheInvalid',
-    },
-};
 const RUNTIME_NOTICES = {
-    'status-publication-failed': {
-        level: 'warn',
-        messageKey: 'log.notice.statusPublicationFailed',
-    },
-    'ownership-release-not-finalized': {
-        level: 'error',
-        messageKey: 'log.notice.ownershipReleaseNotFinalized',
-    },
-    'ownership-release-failed': {
-        level: 'error',
-        messageKey: 'log.notice.ownershipReleaseFailed',
-    },
-    'shutdown-failed': {
-        level: 'error',
-        messageKey: 'log.notice.shutdownFailed',
-    },
-    'shutdown-timeout': {
-        level: 'warn',
-        messageKey: 'log.notice.shutdownTimeout',
-        durationMessageKey: 'log.notice.shutdownTimeoutWithDuration',
-    },
-    'ownership-acquisition-failed': {
-        level: 'error',
-        messageKey: 'log.notice.ownershipAcquisitionFailed',
-    },
-    'ownership-release-incomplete': {
-        level: 'warn',
-        messageKey: 'log.notice.ownershipReleaseIncomplete',
-    },
-    'registry-subscriber-failed': {
-        level: 'warn',
-        messageKey: 'log.notice.registrySubscriberFailed',
-    },
-    'event-subscriber-failed': {
-        level: 'warn',
-        messageKey: 'log.notice.eventSubscriberFailed',
-    },
-    'state-subscriber-failed': {
-        level: 'warn',
-        messageKey: 'log.notice.stateSubscriberFailed',
-    },
-    'channel-serve-failed': {
-        level: 'warn',
-        messageKey: 'log.notice.channelServeFailed',
-    },
-    'diagnostics-authorization-armed': {
-        level: 'info',
-        messageKey: 'log.notice.diagnosticsAuthorizationArmed',
-    },
-    'stand-down-not-rearmed': {
-        level: 'warn',
-        messageKey: 'log.notice.standDownNotRearmed',
-    },
-    'stand-down-account-replaced': {
-        level: 'warn',
-        messageKey: 'log.notice.standDownAccountReplaced',
-    },
+    'status-publication-failed': ['warn', 'log.notice.statusPublicationFailed'],
+    'ownership-release-not-finalized': ['error', 'log.notice.ownershipReleaseNotFinalized'],
+    'ownership-release-failed': ['error', 'log.notice.ownershipReleaseFailed'],
+    'shutdown-failed': ['error', 'log.notice.shutdownFailed'],
+    'shutdown-timeout': ['warn', 'log.notice.shutdownTimeout', 'log.notice.shutdownTimeoutWithDuration'],
+    'ownership-acquisition-failed': ['error', 'log.notice.ownershipAcquisitionFailed'],
+    'ownership-release-incomplete': ['warn', 'log.notice.ownershipReleaseIncomplete'],
+    'registry-subscriber-failed': ['warn', 'log.notice.registrySubscriberFailed'],
+    'event-subscriber-failed': ['warn', 'log.notice.eventSubscriberFailed'],
+    'state-subscriber-failed': ['warn', 'log.notice.stateSubscriberFailed'],
+    'channel-serve-failed': ['warn', 'log.notice.channelServeFailed'],
+    'diagnostics-authorization-armed': ['info', 'log.notice.diagnosticsAuthorizationArmed'],
+    'stand-down-not-rearmed': ['warn', 'log.notice.standDownNotRearmed'],
+    'stand-down-account-replaced': ['warn', 'log.notice.standDownAccountReplaced'],
+    'camera-snapshot-cache-invalid': ['warn', 'log.snapshotCacheInvalid'],
+    'discarded-v4-settings-unacknowledged': ['warn', 'log.discardedSettings'],
+};
+/** The scope a notice is recorded under where it is not `runtime-notice`. */
+const NOTICE_SCOPES = {
+    'camera-snapshot-cache-invalid': 'media-notice',
+    'discarded-v4-settings-unacknowledged': 'configuration-notice',
 };
 const RUNTIME_CONDITIONS = {
     degraded: {
@@ -2186,7 +2161,7 @@ const HOMEKIT_REASON_ACTIONS = {
 };
 /** Projects a value onto an active condition, or nothing where the catalog does not write that code with those keys. */
 export function knownCondition(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
+    if (!isRecord(value))
         return undefined;
     const { code, summaryKey, actionKey, serials } = value;
     if (typeof code !== 'string')
@@ -2223,14 +2198,13 @@ function homeKitConditionPresentation(code, active, reason) {
 function sanitizeStructuredEvent(message) {
     let value;
     try {
-        const parsed = JSON.parse(message);
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
-            return undefined;
-        value = parsed;
+        value = JSON.parse(message);
     }
     catch {
         return undefined;
     }
+    if (!isRecord(value))
+        return undefined;
     const level = allowlistedLabel(value.level, ['debug', 'info', 'warn', 'error']);
     if (!level || typeof value.scope !== 'string')
         return undefined;
@@ -2253,18 +2227,17 @@ function sanitizeStructuredEvent(message) {
         }
         const details = [];
         for (const detail of Array.isArray(value.details) ? value.details.slice(0, MAX_SDK_DETAILS) : []) {
-            if (!detail || typeof detail !== 'object' || Array.isArray(detail))
+            if (!isRecord(detail))
                 continue;
-            const candidate = detail;
-            const errorType = allowlistedLabel(candidate.errorType, SDK_ERROR_TYPES);
+            const errorType = allowlistedLabel(detail.errorType, SDK_ERROR_TYPES);
             if (errorType) {
                 details.push({ errorType });
                 continue;
             }
-            const type = allowlistedLabel(candidate.type, ['boolean', 'number', 'object', 'string', 'undefined']);
+            const type = allowlistedLabel(detail.type, ['boolean', 'number', 'object', 'string', 'undefined']);
             if (!type)
                 continue;
-            const length = nonNegativeInteger(candidate.length);
+            const length = nonNegativeInteger(detail.length);
             details.push({ type, ...(length === undefined ? {} : { length }) });
         }
         return {
@@ -2276,72 +2249,14 @@ function sanitizeStructuredEvent(message) {
             ...(value.detailsTruncated === true ? { detailsTruncated: true } : {}),
         };
     }
-    if (value.scope === 'runtime-notice') {
+    if (value.scope === 'runtime-notice' || value.scope === 'media-notice' || value.scope === 'configuration-notice') {
         if (typeof value.code !== 'string' || !Object.hasOwn(RUNTIME_NOTICES, value.code))
             return undefined;
-        const notice = RUNTIME_NOTICES[value.code];
-        const durationMs = nonNegativeInteger(value.durationMs);
-        const messageKey = durationMs !== undefined && 'durationMessageKey' in notice ? notice.durationMessageKey : notice.messageKey;
-        return {
-            scope: 'runtime-notice',
-            level: notice.level,
-            code: value.code,
-            messageKey,
-            ...(durationMs === undefined ? {} : { durationMs }),
-        };
-    }
-    if (value.scope === 'configuration-notice') {
-        if (value.code !== 'discarded-v4-settings-unacknowledged')
-            return undefined;
-        return {
-            scope: 'configuration-notice',
-            level: 'warn',
-            code: value.code,
-            messageKey: 'log.discardedSettings',
-        };
-    }
-    if (value.scope === 'media-notice') {
-        if (typeof value.code !== 'string' || !Object.hasOwn(MEDIA_NOTICES, value.code))
-            return undefined;
-        const notice = MEDIA_NOTICES[value.code];
-        return { scope: 'media-notice', level: notice.level, code: value.code, messageKey: notice.messageKey };
+        const notice = runtimeNoticeRecord(value.code, nonNegativeInteger(value.durationMs));
+        return notice.scope === value.scope ? notice : undefined;
     }
     if (value.scope === 'homekit') {
-        if (value.event === 'event-unrouted') {
-            const unrouted = sanitizeUnroutedEvent(value);
-            return unrouted ? { scope: 'homekit', level: 'debug', ...unrouted } : undefined;
-        }
-        if (value.event === 'station-claim') {
-            const claim = sanitizeStationClaim(value);
-            return claim ? { scope: 'homekit', level: 'debug', ...claim } : undefined;
-        }
-        if (value.adapter === 'camera.streaming' && value.event === 'live-video-selected') {
-            const selection = sanitizeLiveVideoSelection(value);
-            return selection ? { scope: 'homekit', level: 'debug', ...selection } : undefined;
-        }
-        if (value.adapter === 'camera.streaming' && HOMEKIT_LIVE_REQUEST_EVENTS.has(String(value.event))) {
-            const lifecycle = sanitizeLiveSessionTrace(value);
-            return lifecycle ? { scope: 'homekit', level: 'debug', ...lifecycle } : undefined;
-        }
-        if (typeof value.adapter !== 'string' ||
-            typeof value.event !== 'string' ||
-            !HOMEKIT_EVENT_ROUTES[value.adapter]?.has(value.event) ||
-            typeof value.observation !== 'string' ||
-            !HOMEKIT_OBSERVATIONS.has(value.observation)) {
-            return undefined;
-        }
-        const alias = opaqueAccessoryAlias(value.accessory);
-        return {
-            scope: 'homekit',
-            level: 'debug',
-            adapter: value.adapter,
-            event: value.event,
-            observation: value.observation,
-            ...(typeof value.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(value.announcedBy)
-                ? { announcedBy: value.announcedBy }
-                : {}),
-            ...(alias === undefined ? {} : { accessory: alias }),
-        };
+        return sanitizeHomeKitEvent(value);
     }
     if (value.scope === 'runtime') {
         const event = allowlistedLabel(value.event, ['ready', 'stopped']);
@@ -2352,6 +2267,10 @@ function sanitizeStructuredEvent(message) {
     if (value.scope === 'ffmpeg') {
         return sanitizeAdaptationNotice(value, level);
     }
+    if (value.scope === 'live-preview') {
+        const preview = sanitizeLivePreview(value);
+        return preview ? { scope: 'live-preview', level: 'info', ...preview } : undefined;
+    }
     if (value.scope === 'diagnostic-condition') {
         const homeKitDefinition = typeof value.code === 'string' && Object.hasOwn(HOMEKIT_CONDITIONS, value.code)
             ? HOMEKIT_CONDITIONS[value.code]
@@ -2386,7 +2305,7 @@ function sanitizeStructuredEvent(message) {
         const affectedAccessoryCount = nonNegativeInteger(value.affectedAccessoryCount);
         const accessoryAliases = Array.isArray(value.accessoryAliases)
             ? value.accessoryAliases
-                .filter((alias) => typeof alias === 'string' && /^accessory-[0-9a-f-]{36}$/.test(alias))
+                .filter((alias) => opaqueAccessoryAlias(alias) !== undefined)
                 .slice(0, MAX_ACCESSORY_ALIASES)
             : [];
         const { level: conditionLevel, actionKey } = homeKitConditionPresentation(value.code, value.active, value.reason);
@@ -2409,19 +2328,22 @@ function sanitizeStructuredEvent(message) {
     }
     return undefined;
 }
-/** Emits one fixed-shape operational notice selected by its allowlisted runtime code. */
-export function reportRuntimeNotice(target, code, fields = {}) {
-    const notice = RUNTIME_NOTICES[code];
-    const durationMs = fields.durationMs === undefined ? undefined : Math.max(0, Math.trunc(fields.durationMs));
-    const messageKey = durationMs !== undefined && 'durationMessageKey' in notice ? notice.durationMessageKey : notice.messageKey;
-    target[notice.level]?.(`[${code}] ${localize(target, messageKey, { durationMs: durationMs ?? 0, finishBy: fields.finishBy ?? '' })}`);
-    target.debug?.(JSON.stringify({
-        scope: 'runtime-notice',
-        level: notice.level,
+/** The record one notice is written as, read by both halves of the path. */
+function runtimeNoticeRecord(code, durationMs) {
+    const [level, messageKey, durationMessageKey] = RUNTIME_NOTICES[code];
+    return {
+        scope: NOTICE_SCOPES[code] ?? 'runtime-notice',
+        level,
         code,
-        messageKey,
+        messageKey: durationMs !== undefined && durationMessageKey ? durationMessageKey : messageKey,
         ...(durationMs === undefined ? {} : { durationMs }),
-    }));
+    };
+}
+/** Emits one fixed-shape operational notice selected by its allowlisted code. */
+export function reportRuntimeNotice(target, code, fields = {}) {
+    const record = runtimeNoticeRecord(code, fields.durationMs === undefined ? undefined : Math.max(0, Math.trunc(fields.durationMs)));
+    target[record.level]?.(`[${code}] ${localize(target, record.messageKey, { durationMs: record.durationMs ?? 0, finishBy: fields.finishBy ?? '' })}`);
+    target.debug?.(JSON.stringify(record));
 }
 /**
  * Picks up an authorization the persisted session file confirms, reporting whether it did.
@@ -2442,18 +2364,6 @@ export function armDiagnosticsAuthorization(target, storageRoot, supportCaseId,
     });
     return true;
 }
-/** Emits the startup notice for discarded settings awaiting acknowledgement. */
-export function reportDiscardedV4Settings(target) {
-    const code = 'discarded-v4-settings-unacknowledged';
-    const messageKey = 'log.discardedSettings';
-    target.warn(`[${code}] ${localize(target, messageKey)}`);
-    target.debug?.(JSON.stringify({
-        scope: 'configuration-notice',
-        level: 'warn',
-        code,
-        messageKey,
-    }));
-}
 /** States once which encoders code live video on this host: every qualified hardware encoder, then `libx264`. */
 export function reportLiveVideoEncoders(target, encoders) {
     const names = [
@@ -2462,19 +2372,6 @@ export function reportLiveVideoEncoders(target, encoders) {
     ];
     target.info(`[live-video-encoders] ${localize(target, 'log.liveVideoEncoders', { encoders: names.join(', ') })}`);
 }
-/** Emits one identity-free warning after an invalid retained camera image is discarded. */
-export function reportInvalidSnapshotCache(target) {
-    const code = 'camera-snapshot-cache-invalid';
-    const { level, messageKey } = MEDIA_NOTICES[code];
-    target[level](`[${code}] ${localize(target, messageKey)}`);
-    target.debug?.(JSON.stringify({ scope: 'media-notice', level, code, messageKey }));
-}
-/**
- * Emits one allowlisted HomeKit event trace only when host debug output is available.
- *
- * `aliasFor` resolves the trace's device identity to the support-case alias the conditions about that accessory
- * already carry. The identity itself never reaches the record: an unresolved one is recorded as no accessory.
- */
 /**
  * Narrows one offered station arbitration decision, or nothing where its own labels do not narrow.
  *
@@ -2515,49 +2412,63 @@ export function reportStationClaim(target, decision) {
         target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...claim }));
     }
 }
-export function reportHomeKitEvent(target, trace, aliasFor) {
-    if (!('adapter' in trace)) {
-        const unrouted = sanitizeUnroutedEvent(trace);
-        if (target.debug && unrouted) {
-            target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...unrouted }));
-        }
-        return;
-    }
-    const alias = typeof trace.serial === 'string' ? aliasFor?.(trace.serial) : undefined;
-    const offered = { ...trace, accessory: alias };
-    const accessory = alias === undefined ? {} : { accessory: alias };
-    if (trace.event === 'live-video-selected') {
-        const selection = sanitizeLiveVideoSelection(offered);
-        if (target.debug && selection) {
-            target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...selection }));
-        }
-        return;
-    }
-    if (HOMEKIT_LIVE_REQUEST_EVENTS.has(trace.event)) {
-        const lifecycle = sanitizeLiveSessionTrace(offered);
-        if (target.debug && lifecycle) {
-            target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...lifecycle }));
-        }
-        return;
-    }
-    if (!target.debug ||
-        !('observation' in trace) ||
-        !HOMEKIT_EVENT_ROUTES[trace.adapter]?.has(trace.event) ||
-        typeof trace.observation !== 'string' ||
-        !HOMEKIT_OBSERVATIONS.has(trace.observation)) {
-        return;
+/**
+ * Narrows one offered HomeKit adapter fact to its `homekit` record, or nothing where its route does not narrow.
+ *
+ * Read by both halves of the path: {@link reportHomeKitEvent} builds the record and the file sink rebuilds it.
+ */
+function sanitizeHomeKitEvent(value) {
+    if (value.event === 'event-unrouted') {
+        const unrouted = sanitizeUnroutedEvent(value);
+        return unrouted ? { scope: 'homekit', level: 'debug', ...unrouted } : undefined;
+    }
+    if (value.event === 'station-claim') {
+        const claim = sanitizeStationClaim(value);
+        return claim ? { scope: 'homekit', level: 'debug', ...claim } : undefined;
+    }
+    if (value.adapter === 'camera.streaming' && value.event === 'live-video-selected') {
+        const selection = sanitizeLiveVideoSelection(value);
+        return selection ? { scope: 'homekit', level: 'debug', ...selection } : undefined;
+    }
+    if (value.adapter === 'camera.streaming' && HOMEKIT_LIVE_REQUEST_EVENTS.has(String(value.event))) {
+        const lifecycle = sanitizeLiveSessionTrace(value);
+        return lifecycle ? { scope: 'homekit', level: 'debug', ...lifecycle } : undefined;
+    }
+    if (typeof value.adapter !== 'string' ||
+        typeof value.event !== 'string' ||
+        !HOMEKIT_EVENT_ROUTES[value.adapter]?.has(value.event) ||
+        typeof value.observation !== 'string' ||
+        !HOMEKIT_OBSERVATIONS.has(value.observation)) {
+        return undefined;
     }
-    target.debug(JSON.stringify({
+    const alias = opaqueAccessoryAlias(value.accessory);
+    return {
         scope: 'homekit',
         level: 'debug',
-        adapter: trace.adapter,
-        event: trace.event,
-        observation: trace.observation,
-        ...(typeof trace.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(trace.announcedBy)
-            ? { announcedBy: trace.announcedBy }
+        adapter: value.adapter,
+        event: value.event,
+        observation: value.observation,
+        ...(typeof value.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(value.announcedBy)
+            ? { announcedBy: value.announcedBy }
             : {}),
-        ...accessory,
-    }));
+        ...(typeof value.code === 'number' && Number.isInteger(value.code) && value.code >= 0 && value.code <= 0xffff
+            ? { code: value.code }
+            : {}),
+        ...(alias === undefined ? {} : { accessory: alias }),
+    };
+}
+/**
+ * Emits one allowlisted HomeKit event trace only when host debug output is available.
+ *
+ * `aliasFor` resolves the trace's device identity to the support-case alias the conditions about that accessory
+ * already carry. The identity itself never reaches the record: an unresolved one is recorded as no accessory.
+ */
+export function reportHomeKitEvent(target, trace, aliasFor) {
+    const alias = 'serial' in trace && typeof trace.serial === 'string' ? aliasFor?.(trace.serial) : undefined;
+    const record = sanitizeHomeKitEvent({ ...trace, accessory: alias });
+    if (target.debug && record) {
+        target.debug(JSON.stringify(record));
+    }
 }
 /**
  * Records one FFmpeg adaptation fact as the `ffmpeg-log` evidence the media support profiles declare.
@@ -2577,19 +2488,8 @@ export function reportAdaptationNotice(target, trace) {
     }
 }
 /**
- * Reduces one FFmpeg stderr line to what a support case may keep, or nothing where nothing is left of it.
- *
- * The line is the only place an encoder-level cause is stated outright, and it is also the only place this
- * plugin's own argument list can be echoed back: the output URL carries base64 SRTP key material, the
- * controller address sits beside it, and an SDK snapshot filename carries a device serial. Each of those is
- * replaced by what it is rather than searched for afterwards, because a redaction that depends on
- * recognising a secret fails on the first message shape nobody predicted.
- *
- * The key material is replaced before the path rules run, and not after. Base64 includes `/`, so a path rule
- * applied first splits a key into sub-runs too short for any length threshold to catch — measured on random
- * 30-byte keys, roughly one line in twenty then kept an eight-character fragment verbatim. The cost of this
- * order is that a long path made only of letters and separators is labelled as redacted rather than as a
- * path, which loses a label and never a secret.
+ * Reduces one FFmpeg stderr line to what a support case may keep, or nothing where nothing is left of it: a
+ * bounded printable line, never a `progress=` one, through {@link redactSensitiveText}.
  */
 function redactAdaptationStderr(line) {
     const printable = boundedText(line, MAX_ADAPTATION_STDERR_LINE_LENGTH);
@@ -2680,6 +2580,57 @@ function sanitizeAdaptationNotice(value, level) {
         ...(stderr.length ? { stderr } : {}),
     };
 }
+/**
+ * Records how one settings-page live preview ended, as a `live-preview` record kept whether or not a support
+ * window is open: it is not one of the {@link VERBOSE_SCOPES}, because it holds only allowlisted labels and
+ * bounded numbers, one per run a user started.
+ */
+export function reportLivePreview(target, trace) {
+    const { level, ...selection } = trace.selection;
+    const preview = sanitizeLivePreview({ ...trace, ...selection, levelName: level });
+    if (preview)
+        target.debug?.(JSON.stringify({ scope: 'live-preview', level: 'info', ...preview }));
+}
+/**
+ * Narrows one offered live preview run, or nothing where its selection or outcome does not narrow.
+ *
+ * Read by both halves of the path, {@link reportLivePreview} and the file sink, so a record only one of them
+ * recognised could not reach a support archive.
+ */
+function sanitizeLivePreview(value) {
+    const selection = sanitizePreviewSelection(value);
+    const outcome = allowlistedLabel(value.outcome, PREVIEW_OUTCOMES);
+    if (!selection || !outcome)
+        return undefined;
+    const encoder = allowlistedLabel(value.encoder, LIVE_VIDEO_ENCODERS);
+    const source = allowlistedLabel(value.source, LIVE_VIDEO_SOURCES);
+    const kbps = boundedInteger(value.kbps, MAX_LIVE_VIDEO_BIT_RATE);
+    const accessory = opaqueAccessoryAlias(value.accessory);
+    const ask = allowlistedLabel(value.ask, PREVIEW_ASKS);
+    const settings = PREVIEW_SETTINGS.filter((setting) => typeof value[setting] === 'boolean');
+    return {
+        ...selection,
+        ...(encoder === undefined ? {} : { encoder }),
+        ...(source === undefined ? {} : { source }),
+        ...(kbps === undefined ? {} : { kbps }),
+        ...(ask === undefined ? {} : { ask }),
+        ...Object.fromEntries(settings.map((setting) => [setting, value[setting]])),
+        outcome,
+        ...(accessory === undefined ? {} : { accessory }),
+    };
+}
+/** A live preview's selection as flat bounded fields, or nothing where any of them falls outside its allowlist. */
+function sanitizePreviewSelection(candidate) {
+    const fields = {
+        profile: allowlistedLabel(candidate.profile, HOMEKIT_LIVE_VIDEO_PROFILES),
+        levelName: allowlistedLabel(candidate.levelName, HOMEKIT_LIVE_VIDEO_LEVELS),
+        width: boundedInteger(candidate.width, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION),
+        height: boundedInteger(candidate.height, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION),
+        fps: boundedInteger(candidate.fps, MAX_LIVE_VIDEO_FRAME_RATE, MIN_LIVE_VIDEO_FRAME_RATE),
+        maxBitRate: boundedInteger(candidate.maxBitRate, MAX_LIVE_VIDEO_BIT_RATE),
+    };
+    return Object.values(fields).includes(undefined) ? undefined : fields;
+}
 function sanitizeLiveSessionTrace(value) {
     if (value.adapter !== 'camera.streaming') {
         return undefined;
@@ -2720,8 +2671,7 @@ function sanitizeLiveSessionTrace(value) {
         value.outcome !== 'failed' ||
         typeof value.reason !== 'string' ||
         !REASONS.has(value.reason) ||
-        typeof value.stage !== 'string' ||
-        !HOMEKIT_LIVE_SESSION_STAGES.has(value.stage)) {
+        !allowlistedLabel(value.stage, HOMEKIT_LIVE_SESSION_STAGES)) {
         return undefined;
     }
     const sourceStage = allowlistedLabel(value.sourceStage, SDK_LIVE_START_STAGES);
@@ -2738,27 +2688,23 @@ function sanitizeLiveSessionTrace(value) {
     };
 }
 function sanitizeLiveVideoSelection(value) {
-    const operation = typeof value.operation === 'string' ? value.operation : undefined;
-    const profile = typeof value.profile === 'string' ? value.profile : undefined;
-    const codecLevel = typeof value.levelName === 'string' ? value.levelName : typeof value.level === 'string' ? value.level : undefined;
+    const operation = allowlistedLabel(value.operation, HOMEKIT_LIVE_VIDEO_OPERATIONS);
+    const profile = allowlistedLabel(value.profile, HOMEKIT_LIVE_VIDEO_PROFILES);
+    const codecLevel = allowlistedLabel(typeof value.levelName === 'string' ? value.levelName : value.level, HOMEKIT_LIVE_VIDEO_LEVELS);
     const width = boundedInteger(value.width, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION);
     const height = boundedInteger(value.height, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION);
     const fps = boundedInteger(value.fps, MAX_LIVE_VIDEO_FRAME_RATE, MIN_LIVE_VIDEO_FRAME_RATE);
     const mtu = boundedInteger(value.mtu, MAX_LIVE_VIDEO_MTU, MIN_LIVE_VIDEO_MTU);
     const maxBitRate = boundedInteger(value.maxBitRate, MAX_LIVE_VIDEO_BIT_RATE, 0);
-    const addressVersion = typeof value.addressVersion === 'string' ? value.addressVersion : undefined;
+    const addressVersion = allowlistedLabel(value.addressVersion, HOMEKIT_LIVE_ADDRESS_VERSIONS);
     if (!operation ||
-        !HOMEKIT_LIVE_VIDEO_OPERATIONS.has(operation) ||
         !profile ||
-        !HOMEKIT_LIVE_VIDEO_PROFILES.has(profile) ||
         !codecLevel ||
-        !HOMEKIT_LIVE_VIDEO_LEVELS.has(codecLevel) ||
         width === undefined ||
         height === undefined ||
         fps === undefined ||
         mtu === undefined ||
-        !addressVersion ||
-        !HOMEKIT_LIVE_ADDRESS_VERSIONS.has(addressVersion)) {
+        !addressVersion) {
         return undefined;
     }
     const alias = opaqueAccessoryAlias(value.accessory);