prismcast 1.8.0 → 1.10.0

package/dist/config/userConfig.js

@@ -1,8 +1,8 @@
-import { LOG, stringifySorted } from "../utils/index.js";
-import { getConfigFilePath, getDataDir } from "./paths.js";
-import fs from "node:fs";
+import { createFileStore } from "./persistence.js";
+import { LOG } from "../utils/index.js";
+import { getConfigFilePath } from "./paths.js";
 import { getValidPresetIds } from "./presets.js";
-const { promises: fsPromises } = fs;
+import { isDeepStrictEqual } from "node:util";
 /**
  * Metadata for all configurable settings, organized by category.
  */
@@ -31,16 +31,28 @@ export const CONFIG_METADATA = {
     ],
     channels: [
         {
-            description: "Speed up your first channel tune by loading provider lineups when PrismCast starts. Normally, each provider's lineup is loaded on your " +
-                "first tune, which may add a few extra seconds. Enabling precaching fetches lineups at startup so even your very first tune is fast. Providers not " +
-                "enabled in the Channels tab provider filter are skipped at startup. Ensure you've logged into each provider before enabling.",
+            description: "Speed up your first channel tune by loading service lineups when PrismCast starts. Normally, each service's lineup is loaded on your " +
+                "first tune, which may add a few extra seconds. Enabling precaching fetches lineups at startup so even your very first tune is fast. Services not " +
+                "enabled in the Channels tab service filter are skipped at startup. Ensure you've logged into each service before enabling.",
             envVar: null,
             label: "Channel Lineup Precaching",
             listItemsKey: "providerModules",
-            path: "channels.precacheProviders",
+            path: "channels.precacheServices",
             type: "checkboxList"
         }
     ],
+    channelsDvr: [
+        {
+            description: "TCP port for the user's Channels DVR API. PrismCast polls Channels DVR over HTTP for show-info, device-mapping discovery, and pretune " +
+                "scheduling. Defaults to 8089, which is the canonical Channels DVR port. Override only when the user has changed the DVR's listen port from its default.",
+            envVar: "CHANNELS_DVR_PORT",
+            label: "Channels DVR Port",
+            max: 65535,
+            min: 1,
+            path: "channelsDvr.port",
+            type: "port"
+        }
+    ],
     hdhr: [
         {
             description: "Enable HDHomeRun emulation for Plex integration. When enabled, PrismCast runs a second HTTP server that emulates an HDHomeRun tuner, " +
@@ -467,49 +479,164 @@ export const CONFIG_METADATA = {
     ]
 };
 /* The config file path is resolved via the centralized paths module (config/paths.ts). The data directory is initialized at startup before config loading.
+ * Configuration persistence uses a transactional file store that provides atomic writes, serialized mutations, corruption protection, and backup rotation.
+ * All config modifications go through mutateConfig(), which prevents the class of bugs where a corrupt file gets silently overwritten with nearly-empty data.
+ */
+/* Current schema version for config.json. Migrations are declared in configMigrations below; the framework runs them in order from the file's stored version
+ * up to this constant, stamps the new version after each, and records the audit trail in migrationsApplied.
+ *
+ * Version history:
+ *   1 - Original. Provider-themed channel field names ("enabledProviders", "precacheProviders") and "foxcom" service tag still present.
+ *   2 - Service-themed naming. Renames "enabledProviders" -> "enabledServices", "precacheProviders" -> "precacheServices", and "foxcom" -> "foxone" inside
+ *       the channels.enabledServices array. Companion to channels.json v3 which renames foxcom in channel keys and selections.
+ *   3 - DVR connection namespace. Moves the top-level `dvrHost` field into `channelsDvr.host`, splitting any legacy `host:port` value so the host portion
+ *       lands at `channelsDvr.host` (host-only) and the port portion lands at `channelsDvr.port` only when the user has not already customized the port.
  */
-/* These functions handle reading and writing the config file. All operations are async and handle errors gracefully.
+const CURRENT_CONFIG_SCHEMA_VERSION = 3;
+/* Declarative schema migrations. The file store framework runs these in order from the file's stored schemaVersion up to CURRENT_CONFIG_SCHEMA_VERSION,
+ * stamping the new version and recording the description in migrationsApplied after each application. Apply functions mutate the data in place.
  */
+const configMigrations = {
+    2: {
+        apply: applyChannelsProviderRenameMigration,
+        description: "Rename legacy provider-themed channel field names and foxcom service tag to foxone"
+    },
+    3: {
+        apply: applyDvrHostNamespaceMigration,
+        description: "Move dvrHost into channelsDvr.host (split legacy host:port format)"
+    }
+};
 /**
- * Loads user configuration from the config file. Returns an empty config if the file doesn't exist, and sets parseError if the file exists but contains invalid
- * JSON.
- * @returns The loaded configuration with parse status.
+ * Renames the legacy provider-themed channel fields to their current service-themed names: `enabledProviders` -> `enabledServices`,
+ * `precacheProviders` -> `precacheServices`, and the `"foxcom"` tag -> `"foxone"` inside `enabledServices`. When both legacy and current names coexist on disk
+ * (a rare hand-edited collision), the current name wins and the legacy key is deleted - operator intent on the new name takes precedence over the auto-rename.
+ *
+ * Behavioral contract: this is a pure transformation on the on-disk shape. Configs without a `channels` block are left untouched (early return); configs that
+ * already have the v2 shape (no legacy keys present) are unchanged at the field level (idempotent), though the foxcom-to-foxone map runs unconditionally over
+ * the present `enabledServices` array because that operation is itself a no-op for already-migrated tags.
+ *
+ * Exported for unit-test coverage of the rename cases (each rename, collision wins, foxcom remap, no-channels early return). Production callers reach this
+ * only through the schema migration runner, never directly.
+ *
+ * @param data - The pre-migration UserConfig data, mutated in place.
  */
-export async function loadUserConfig() {
-    try {
-        const content = await fsPromises.readFile(getConfigFilePath(), "utf-8");
-        try {
-            const config = JSON.parse(content);
-            return { config, parseError: false };
-        }
-        catch (parseError) {
-            const message = (parseError instanceof Error) ? parseError.message : String(parseError);
-            LOG.warn("Invalid JSON in configuration file %s: %s. Using defaults.", getConfigFilePath(), message);
-            return { config: {}, parseError: true, parseErrorMessage: message };
+export function applyChannelsProviderRenameMigration(data) {
+    // Cast to a permissive shape because the legacy provider-themed keys are not declared on UserChannelsConfig - they only exist on older on-disk files.
+    const channels = data.channels;
+    if (!channels) {
+        return;
+    }
+    // Rename enabledProviders -> enabledServices. If both are present (rare hand-edited case) the current name wins.
+    if (Array.isArray(channels["enabledProviders"])) {
+        if (!Array.isArray(channels["enabledServices"])) {
+            channels["enabledServices"] = channels["enabledProviders"];
+        }
+        delete channels["enabledProviders"];
+    }
+    // Rename precacheProviders -> precacheServices.
+    if (Array.isArray(channels["precacheProviders"])) {
+        if (!Array.isArray(channels["precacheServices"])) {
+            channels["precacheServices"] = channels["precacheProviders"];
         }
+        delete channels["precacheProviders"];
     }
-    catch (error) {
-        // File doesn't exist - this is normal, use defaults.
-        if (error.code === "ENOENT") {
-            return { config: {}, parseError: false };
-        }
-        // Other read errors - log and use defaults.
-        LOG.warn("Failed to read configuration file %s: %s. Using defaults.", getConfigFilePath(), (error instanceof Error) ? error.message : String(error));
-        return { config: {}, parseError: false };
+    // Rename "foxcom" -> "foxone" inside the enabledServices service-tag filter.
+    if (Array.isArray(channels["enabledServices"])) {
+        channels["enabledServices"] = channels["enabledServices"].map((tag) => (tag === "foxcom") ? "foxone" : tag);
     }
 }
 /**
- * Saves user configuration to the config file. Creates the data directory if it doesn't exist.
- * @param config - The configuration to save.
- * @throws If the file cannot be written.
+ * Splits a legacy `dvrHost` value into the new `channelsDvr.host` / `channelsDvr.port` namespace. The host portion is host-only by invariant; legacy values
+ * carrying an embedded port (e.g., `192.168.1.5:8089`) are split so the host lands at `channelsDvr.host` and the port lands at `channelsDvr.port` IFF the
+ * user has not already customized the port. When both an embedded port and an explicit user-set port exist, the explicit port wins (a warning is logged) and
+ * the embedded port is discarded - the user's deliberate choice takes precedence over implicit legacy data.
+ *
+ * Splits at the LAST colon so bracket-wrapped IPv6 forms like `[::1]:8089` survive (the production setDvrHost invariant rejects bare-colon values, but disk
+ * files may carry hand-edited content the framework cannot vet). When the trailing portion does not parse as a valid port number (1..65535), the entire input
+ * is treated as a host-only value rather than fabricating a bogus port.
+ *
+ * Exported for unit-test coverage of the splitting cases (host-only, host+default-port, host+non-default-port collision). Production callers reach this only
+ * through the schema migration runner, never directly.
+ *
+ * @param data - The pre-migration UserConfig data, mutated in place.
  */
-export async function saveUserConfig(config) {
-    // Ensure data directory exists.
-    await fsPromises.mkdir(getDataDir(), { recursive: true });
-    // Write config with pretty formatting and sorted keys for consistent, diff-friendly output.
-    const content = stringifySorted(config);
-    await fsPromises.writeFile(getConfigFilePath(), content + "\n", "utf-8");
-    LOG.info("Configuration saved to %s.", getConfigFilePath());
+export function applyDvrHostNamespaceMigration(data) {
+    // The legacy field is not declared on the current UserConfig; we read it through a permissive cast to access the on-disk pre-migration shape. After migration
+    // the field is deleted so it cannot leak into the post-migration write path.
+    const legacy = data;
+    const dvrHost = legacy.dvrHost;
+    if (typeof dvrHost !== "string") {
+        return;
+    }
+    let host = dvrHost;
+    let embeddedPort;
+    // Split at the last colon so bracket-wrapped IPv6 (e.g., [::1]:8089) survives. If the trailing portion does not parse as a valid TCP port, treat the whole
+    // input as host-only - avoid fabricating a port from a malformed string.
+    const colonIdx = dvrHost.lastIndexOf(":");
+    if (colonIdx >= 0) {
+        const tail = dvrHost.slice(colonIdx + 1);
+        const parsed = Number(tail);
+        if (Number.isInteger(parsed) && (parsed >= 1) && (parsed <= 65535)) {
+            host = dvrHost.slice(0, colonIdx);
+            embeddedPort = parsed;
+        }
+    }
+    data.channelsDvr ??= {};
+    data.channelsDvr.host = host;
+    // Migrate the embedded port only when the user has not customized the port already. A user-set port reflects an explicit choice that overrides whatever the
+    // legacy host:port string encoded - prefer the explicit value and log the conflict so it is auditable.
+    if (embeddedPort !== undefined) {
+        const userPort = data.channelsDvr.port;
+        if (userPort === undefined) {
+            data.channelsDvr.port = embeddedPort;
+        }
+        else if (userPort !== embeddedPort) {
+            LOG.warn("Schema migration v3: legacy dvrHost \"%s\" carried embedded port %d but channelsDvr.port is already set to %d. " +
+                "Keeping the explicit port; embedded port discarded.", dvrHost, embeddedPort, userPort);
+        }
+    }
+    delete legacy.dvrHost;
+}
+// Transactional store instance for config.json. The beforeWrite hook is the single chokepoint where the persisted shape is normalized: filterDefaults() runs on
+// every save so the file on disk contains only non-default values, regardless of which call site initiated the write. Schema migrations run automatically via
+// the file store framework's migration runner before the data reaches mergeConfiguration.
+const configStore = createFileStore({
+    beforeWrite: (data) => filterDefaults(data),
+    currentSchemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
+    defaultValue: () => ({ schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION }),
+    getSchemaVersion: (data) => data.schemaVersion ?? 1,
+    label: "configuration",
+    migrations: configMigrations,
+    parse: (raw) => JSON.parse(raw),
+    path: getConfigFilePath,
+    recordMigration: (data, description) => {
+        data.migrationsApplied ??= [];
+        data.migrationsApplied.push(description);
+    },
+    setSchemaVersion: (data, version) => { data.schemaVersion = version; }
+});
+/**
+ * Reads the current configuration from disk without acquiring the serialization lock. Returns the parsed (and migrated) config with parse status. Use this for
+ * read-only access (export endpoints, startup initialization). For modifications, use mutateConfig() instead.
+ * @returns The loaded configuration with parse status.
+ */
+export async function readConfig() {
+    const result = await configStore.read();
+    return {
+        config: result.data,
+        parseError: result.parseError,
+        parseErrorMessage: result.parseErrorMessage,
+        recoveredFromBackup: result.recoveredFromBackup
+    };
+}
+/**
+ * Serialized read-modify-write operation on config.json. The mutation function receives the current config (already migrated to the latest schema version) and
+ * modifies it in place. The store handles atomicity, serialization, corruption guard, backup, schema migration, and filterDefaults via the framework.
+ * @param fn - Mutation function. Receives current config. Modify in place; return value is ignored.
+ * @throws FileStoreParseError if config.json contains invalid JSON and no usable backup exists.
+ */
+export async function mutateConfig(fn) {
+    await configStore.mutate(fn);
 }
 /* These functions detect which settings are overridden by environment variables, so the UI can disable those fields and show appropriate warnings.
  */
@@ -543,11 +670,15 @@ export const DEFAULTS = {
         channelSortDirection: "asc",
         channelSortField: "name",
         disabledPredefined: [],
-        enabledProviders: [],
-        precacheProviders: [],
+        enabledServices: [],
+        precacheServices: [],
         setupCompleted: false,
         visibleColumns: []
     },
+    channelsDvr: {
+        host: "",
+        port: 8089
+    },
     hdhr: {
         deviceId: "",
         enabled: true,
@@ -638,7 +769,7 @@ function parseEnvValue(value, type) {
             return value.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
         }
         case "path": {
-            // An empty path env var means "use default" — return null so the downstream code sees the same sentinel as an unset config field.
+            // An empty path env var means "use default" - return null so the downstream code sees the same sentinel as an unset config field.
             return (value.trim() === "") ? null : value;
         }
         default: {
@@ -672,14 +803,11 @@ export function getNestedValue(obj, settingPath) {
 export function setNestedValue(obj, settingPath, value) {
     const parts = settingPath.split(".");
     let current = obj;
-    for (let i = 0; i < (parts.length - 1); i++) {
-        const part = parts[i];
-        if (current[part] === undefined) {
-            current[part] = {};
-        }
+    for (const part of parts.slice(0, -1)) {
+        current[part] ??= {};
         current = current[part];
     }
-    current[parts[parts.length - 1]] = value;
+    current[parts.at(-1) ?? ""] = value;
 }
 /**
  * Merges user configuration with defaults, environment overrides, and CLI overrides to produce the final configuration.
@@ -700,39 +828,18 @@ export function mergeConfiguration(userConfig, cliOverrides) {
             }
         }
     }
-    /* Array and auto-generated string fields require explicit handling here because the standard CONFIG_METADATA loop above assigns by reference. These blocks
-     * apply defensive spread copies to prevent shared references between the user config and runtime config. Fields not in CONFIG_METADATA (disabledPredefined,
-     * enabledProviders) also need their own POST /config carry-forward logic since they are managed by separate endpoints. The precacheProviders field is in
-     * CONFIG_METADATA (as a checkboxList) so the standard loop handles it, but the spread copy here still provides the defensive guarantee.
-     *
-     * When adding a new field here, also add corresponding preservation logic in filterDefaults() below.
+    /* Hydrate fields that live outside CONFIG_METADATA (auto-discovery results like channelsDvr.host, separately-managed lists like channels.disabledPredefined,
+     * the persisted debug filter pattern) and array fields whose CONFIG_METADATA hydration would alias the parsed UserConfig blob into runtime CONFIG. The
+     * registry pairs each path with a predicate (ignored when undefined) and an optional defensive-copy hook. Adding a new field here is one HYDRATED_FIELDS
+     * entry; the drift-check test in userConfig.merge.test.ts asserts that PRESERVED_FIELDS partitions exactly into HYDRATED_FIELDS plus PERSISTENCE_ONLY_FIELDS,
+     * so a future preservation entry cannot be added without an explicit hydration classification. See the section comment above HYDRATED_FIELDS for the full
+     * design intent.
      */
-    if (Array.isArray(userConfig.channels?.disabledPredefined)) {
-        config.channels.disabledPredefined = [...userConfig.channels.disabledPredefined];
-    }
-    if (Array.isArray(userConfig.channels?.enabledProviders)) {
-        config.channels.enabledProviders = [...userConfig.channels.enabledProviders];
-    }
-    if (Array.isArray(userConfig.channels?.precacheProviders)) {
-        config.channels.precacheProviders = [...userConfig.channels.precacheProviders];
-    }
-    if (Array.isArray(userConfig.channels?.visibleColumns)) {
-        config.channels.visibleColumns = [...userConfig.channels.visibleColumns];
-    }
-    if (Array.isArray(userConfig.streaming?.captureCodecs)) {
-        config.streaming.captureCodecs = [...userConfig.streaming.captureCodecs];
-    }
-    if ((typeof userConfig.channels?.channelSortField === "string") && (userConfig.channels.channelSortField.length > 0)) {
-        config.channels.channelSortField = userConfig.channels.channelSortField;
-    }
-    if ((typeof userConfig.channels?.channelSortDirection === "string") && (userConfig.channels.channelSortDirection.length > 0)) {
-        config.channels.channelSortDirection = userConfig.channels.channelSortDirection;
-    }
-    if ((typeof userConfig.hdhr?.deviceId === "string") && (userConfig.hdhr.deviceId.length > 0)) {
-        config.hdhr.deviceId = userConfig.hdhr.deviceId;
-    }
-    if ((typeof userConfig.logging?.debugFilter === "string") && (userConfig.logging.debugFilter.length > 0)) {
-        config.logging.debugFilter = userConfig.logging.debugFilter;
+    for (const field of HYDRATED_FIELDS) {
+        const userValue = getNestedValue(userConfig, field.path);
+        if (field.shouldHydrate(userValue, undefined)) {
+            setNestedValue(config, field.path, field.copy ? field.copy(userValue) : userValue);
+        }
     }
     // Apply environment variable overrides.
     for (const settings of Object.values(CONFIG_METADATA)) {
@@ -773,7 +880,7 @@ const SETTINGS_TAB_SECTIONS = [
     {
         displayName: "Startup",
         id: "startup",
-        paths: ["channels.precacheProviders"]
+        paths: ["channels.precacheServices"]
     },
     {
         displayName: "Capture",
@@ -790,6 +897,7 @@ const SETTINGS_TAB_SECTIONS = [
 /* Display metadata for Advanced tab sections. The category field must match a key in CONFIG_METADATA. Entries are sorted alphabetically by category.
  */
 const ADVANCED_SECTION_META = [
+    { category: "channelsDvr", displayName: "Channels DVR" },
     { category: "hls", displayName: "HLS" },
     { category: "logging", displayName: "Logging" },
     { category: "paths", displayName: "Paths" },
@@ -865,25 +973,20 @@ export function getAdvancedSections() {
     const settingsTabPaths = SETTINGS_TAB_SECTIONS.flatMap((s) => s.paths);
     // Get all paths that belong in Advanced (not in Settings).
     const advancedPaths = getAllSettingPaths().filter((p) => !settingsTabPaths.includes(p));
-    // Group by category (first path segment).
-    const byCategory = new Map();
-    for (const path of advancedPaths) {
-        const category = path.split(".")[0];
-        const setting = getSettingByPath(path);
-        if (setting) {
-            if (!byCategory.has(category)) {
-                byCategory.set(category, []);
-            }
-            byCategory.get(category)?.push(setting);
-        }
-    }
+    // Pair every advanced path with its resolved setting and category prefix, then drop entries whose category is empty or whose setting lookup failed. The
+    // surviving pairs feed Map.groupBy below for the actual grouping.
+    const settingsByPath = advancedPaths
+        .map((path) => ({ category: path.split(".")[0] ?? "", setting: getSettingByPath(path) }))
+        .filter((entry) => Boolean(entry.category && entry.setting));
+    // Group by category (first path segment) using the standard ESNext.Collection grouper.
+    const byCategory = Map.groupBy(settingsByPath, (entry) => entry.category);
     // Return sections in the defined order with display names.
     return ADVANCED_SECTION_META
         .filter((meta) => byCategory.has(meta.category))
         .map((meta) => ({
         displayName: meta.displayName,
         id: meta.category,
-        settings: byCategory.get(meta.category) ?? []
+        settings: byCategory.get(meta.category)?.map((entry) => entry.setting) ?? []
     }));
 }
 /* When saving user configuration, we only want to persist values that differ from defaults. This keeps the config file clean and makes it easy to see what the user has
@@ -929,8 +1032,84 @@ export function isEqualToDefault(value, defaultValue) {
         return false;
     }
     // Compare as strings for consistent comparison across types (handles number/string coercion). Config values are always primitives.
-    return String(value) === String(defaultValue);
+    const primitive = value;
+    const defaultPrimitive = defaultValue;
+    return String(primitive) === String(defaultPrimitive);
 }
+// Predicate: any array, including empty. Used by HYDRATED_FIELDS to mirror the historical mergeConfiguration() inline-block behavior of unconditionally
+// hydrating any array-typed value present on disk; downstream validateConfiguration() normalizes empty-array edge cases (e.g., captureCodecs forces h264).
+const isArrayValue = (value) => Array.isArray(value);
+// Predicate: any non-empty array. Used for fields where the user's empty-array state coincides with the default-empty-array state (disabledPredefined,
+// enabledServices, precacheServices, visibleColumns, migrationsApplied). The defaultValue argument is intentionally unused.
+const isNonEmptyArray = (value) => Array.isArray(value) && (value.length > 0);
+// Predicate: any non-empty string. Used for fields whose default is the empty string and whose presence-on-disk should follow the same rule (hdhr.deviceId,
+// logging.debugFilter, channelsDvr.host).
+const isNonEmptyString = (value) => (typeof value === "string") && (value.length > 0);
+// Predicate: any number. Used for schemaVersion - the framework-managed integer that any non-undefined value must round-trip through filterDefaults.
+// Predicate: any number including NaN. Number.isFinite() would tighten the contract if NaN must be rejected.
+const isNumber = (value) => typeof value === "number";
+// Predicate: a string that differs from the default by simple equality. Used for channelSortField / channelSortDirection - both have meaningful default
+// values ("name", "asc") that should be stripped on save while any other valid string is preserved.
+const differsFromStringDefault = (value, defaultValue) => (typeof value === "string") && (value !== defaultValue);
+// Predicate: an array whose contents differ from the default by SORTED-element comparison. Used for streaming.captureCodecs - the default ["h264", "hevc"]
+// reordered by the user (["hevc", "h264"]) is semantically the same configuration and should not write to disk; only a different SET of codecs counts as a
+// customization worth preserving.
+const differsFromSortedArrayDefault = (value, defaultValue) => {
+    return Array.isArray(value) && Array.isArray(defaultValue) && !isDeepStrictEqual(value.toSorted(), defaultValue.toSorted());
+};
+/**
+ * Allowlist of config paths that filterDefaults() preserves outside the CONFIG_METADATA-driven loop. See the section comment above for the two distinct
+ * reasons a path lives here rather than in CONFIG_METADATA. The list is alphabetized by path so a future maintainer can locate any entry by paging through
+ * the registry; ordering does not affect runtime semantics because each entry's preserve check is independent.
+ */
+export const PRESERVED_FIELDS = [
+    { path: "channels.channelSortDirection", shouldPreserve: differsFromStringDefault },
+    { path: "channels.channelSortField", shouldPreserve: differsFromStringDefault },
+    { path: "channels.disabledPredefined", shouldPreserve: isNonEmptyArray },
+    { path: "channels.enabledServices", shouldPreserve: isNonEmptyArray },
+    { path: "channels.precacheServices", shouldPreserve: isNonEmptyArray },
+    { path: "channels.visibleColumns", shouldPreserve: isNonEmptyArray },
+    { path: "channelsDvr.host", shouldPreserve: isNonEmptyString },
+    { path: "hdhr.deviceId", shouldPreserve: isNonEmptyString },
+    { path: "logging.debugFilter", shouldPreserve: isNonEmptyString },
+    { path: "migrationsApplied", shouldPreserve: isNonEmptyArray },
+    { path: "schemaVersion", shouldPreserve: isNumber },
+    { path: "streaming.captureCodecs", shouldPreserve: differsFromSortedArrayDefault }
+];
+// Defensive spread copy for array fields. Pulled out as a const so the registry below reads as a declarative table.
+const spreadArray = (value) => [...value];
+/**
+ * Allowlist of config paths that mergeConfiguration() hydrates from the persisted UserConfig into the runtime CONFIG outside the CONFIG_METADATA-driven loop.
+ * Each entry corresponds to a PRESERVED_FIELDS entry that lives on the runtime Config type (the persistence-only entries schemaVersion / migrationsApplied are
+ * declared in PERSISTENCE_ONLY_FIELDS instead). The list is alphabetized by path; ordering does not affect runtime semantics. A drift-check test in
+ * userConfig.merge.test.ts asserts that PRESERVED_FIELDS partitions exactly into HYDRATED_FIELDS plus PERSISTENCE_ONLY_FIELDS, so a future preservation entry
+ * cannot be added without explicitly classifying it as runtime-hydrated or persistence-only.
+ */
+export const HYDRATED_FIELDS = [
+    { path: "channels.channelSortDirection", shouldHydrate: isNonEmptyString },
+    { path: "channels.channelSortField", shouldHydrate: isNonEmptyString },
+    { copy: spreadArray, path: "channels.disabledPredefined", shouldHydrate: isArrayValue },
+    { copy: spreadArray, path: "channels.enabledServices", shouldHydrate: isArrayValue },
+    { copy: spreadArray, path: "channels.precacheServices", shouldHydrate: isArrayValue },
+    { copy: spreadArray, path: "channels.visibleColumns", shouldHydrate: isArrayValue },
+    { path: "channelsDvr.host", shouldHydrate: isNonEmptyString },
+    { path: "hdhr.deviceId", shouldHydrate: isNonEmptyString },
+    { path: "logging.debugFilter", shouldHydrate: isNonEmptyString },
+    { copy: spreadArray, path: "streaming.captureCodecs", shouldHydrate: isArrayValue }
+];
+/**
+ * Allowlist of PRESERVED_FIELDS entries that exist only on the persisted UserConfig shape and have NO runtime CONFIG counterpart. These are framework-managed
+ * file-store metadata - the schema-migration runner owns schemaVersion (so the file-store framework can decide whether migrations have run) and migrationsApplied
+ * (the audit trail of which migrations have applied). Neither belongs in runtime CONFIG; both must round-trip through filterDefaults so saves do not strip them.
+ *
+ * The drift-check test consumes this constant to assert that every PRESERVED_FIELDS entry is classified as either runtime-hydrated (HYDRATED_FIELDS) or
+ * persistence-only (here), and that the two sets are disjoint. Adding a new PRESERVED_FIELDS entry without classifying it here or in HYDRATED_FIELDS fails the
+ * drift check at test time, surfacing the architectural intent that every preserved field has a declared destination.
+ */
+export const PERSISTENCE_ONLY_FIELDS = [
+    "migrationsApplied",
+    "schemaVersion"
+];
 /**
  * Filters a user configuration object to remove values that match the defaults. This produces a minimal config file containing only the settings the user has actually
  * customized. Empty nested objects are also removed.
@@ -939,9 +1118,20 @@ export function isEqualToDefault(value, defaultValue) {
  */
 export function filterDefaults(config) {
     const filtered = {};
-    // Iterate over all known settings and check if the value differs from the default.
+    // Build the set of paths owned by PRESERVED_FIELDS so the metadata-driven loop can skip them. The PRESERVED_FIELDS predicate is the sole arbiter for those
+    // paths because String() coercion in isEqualToDefault produces false positives for array-shaped values (e.g., a reordered captureCodecs list coerces to a
+    // different comma-joined string than the default and would survive the loop, even when the predicate would correctly classify it as default-equal).
+    // Skipping the loop for those paths and letting the predicate decide is the only way to make the predicate authoritative without restructuring either
+    // registry. Paths in PRESERVED_FIELDS that are NOT in CONFIG_METADATA (channelsDvr.host, hdhr.deviceId, etc.) are unaffected - the loop never visited them
+    // before either.
+    const preservedPaths = new Set(PRESERVED_FIELDS.map((field) => field.path));
+    // Iterate over all known settings and check if the value differs from the default. Paths managed by PRESERVED_FIELDS are skipped here so the predicate below
+    // has unilateral control over their inclusion.
     for (const settings of Object.values(CONFIG_METADATA)) {
         for (const setting of settings) {
+            if (preservedPaths.has(setting.path)) {
+                continue;
+            }
             const value = getNestedValue(config, setting.path);
             // Skip undefined values (setting not present in config).
             if (value === undefined) {
@@ -954,51 +1144,14 @@ export function filterDefaults(config) {
             }
         }
     }
-    /* Counterpart to the array handling in mergeConfiguration() above. Array fields need explicit preservation here because the standard loop's isEqualToDefault()
-     * uses String() comparison, which works for inequality detection but can produce false positives for arrays with comma-containing strings. The explicit blocks
-     * also ensure non-empty arrays survive the diff even when the standard loop would skip them.
-     */
-    const configChannelsDisabled = getNestedValue(config, "channels.disabledPredefined");
-    if (Array.isArray(configChannelsDisabled) && (configChannelsDisabled.length > 0)) {
-        setNestedValue(filtered, "channels.disabledPredefined", configChannelsDisabled);
-    }
-    const configEnabledProviders = getNestedValue(config, "channels.enabledProviders");
-    if (Array.isArray(configEnabledProviders) && (configEnabledProviders.length > 0)) {
-        setNestedValue(filtered, "channels.enabledProviders", configEnabledProviders);
-    }
-    const configPrecacheProviders = getNestedValue(config, "channels.precacheProviders");
-    if (Array.isArray(configPrecacheProviders) && (configPrecacheProviders.length > 0)) {
-        setNestedValue(filtered, "channels.precacheProviders", configPrecacheProviders);
-    }
-    const configVisibleColumns = getNestedValue(config, "channels.visibleColumns");
-    if (Array.isArray(configVisibleColumns) && (configVisibleColumns.length > 0)) {
-        setNestedValue(filtered, "channels.visibleColumns", configVisibleColumns);
-    }
-    // Preserve captureCodecs when it differs from the default. The default includes all recognized codecs, so a shorter list means the user has disabled one.
-    const configCaptureCodecs = getNestedValue(config, "streaming.captureCodecs");
-    const defaultCaptureCodecs = getNestedValue(DEFAULTS, "streaming.captureCodecs");
-    if (Array.isArray(configCaptureCodecs) && (JSON.stringify(configCaptureCodecs.slice().sort()) !== JSON.stringify(defaultCaptureCodecs.slice().sort()))) {
-        setNestedValue(filtered, "streaming.captureCodecs", configCaptureCodecs);
-    }
-    const configSortField = getNestedValue(config, "channels.channelSortField");
-    if ((typeof configSortField === "string") && (configSortField !== "name")) {
-        setNestedValue(filtered, "channels.channelSortField", configSortField);
-    }
-    const configSortDirection = getNestedValue(config, "channels.channelSortDirection");
-    if ((typeof configSortDirection === "string") && (configSortDirection !== "asc")) {
-        setNestedValue(filtered, "channels.channelSortDirection", configSortDirection);
-    }
-    const configDeviceId = getNestedValue(config, "hdhr.deviceId");
-    if ((typeof configDeviceId === "string") && (configDeviceId.length > 0)) {
-        setNestedValue(filtered, "hdhr.deviceId", configDeviceId);
-    }
-    const configDebugFilter = getNestedValue(config, "logging.debugFilter");
-    if ((typeof configDebugFilter === "string") && (configDebugFilter.length > 0)) {
-        setNestedValue(filtered, "logging.debugFilter", configDebugFilter);
-    }
-    // Preserve the auto-discovered DVR host across settings saves.
-    if ((typeof config.dvrHost === "string") && (config.dvrHost.length > 0)) {
-        filtered.dvrHost = config.dvrHost;
+    // Apply the explicit preservation registry. Each entry is consulted with its current value plus the default-at-path; the predicate decides whether to
+    // write through. See PRESERVED_FIELDS above for the entries and their rationale.
+    for (const field of PRESERVED_FIELDS) {
+        const value = getNestedValue(config, field.path);
+        const defaultValue = getNestedValue(DEFAULTS, field.path);
+        if (field.shouldPreserve(value, defaultValue)) {
+            setNestedValue(filtered, field.path, value);
+        }
     }
     // Remove any empty nested objects that resulted from filtering.
     return removeEmptyObjects(filtered);