prismcast 1.9.0 → 1.10.0

package/dist/config/userChannels.js

@@ -2,13 +2,15 @@
  *
  * userChannels.ts: User channel file management for PrismCast.
  */
-import { CHANNEL_IDENTITY_FIELDS, PREDEFINED_CHANNELS, PREDEFINED_TAGS } from "../channels/index.js";
+import { CHANNEL_BINDING_KEYS, CHANNEL_IDENTITY_KEYS, DELTA_ELIGIBLE_BINDING_KEYS, DELTA_ELIGIBLE_IDENTITY_KEYS } from "../types/index.js";
 import { FileStoreParseError, createFileStore } from "./persistence.js";
 import { LOG, containsNonPrintable, sanitizeString } from "../utils/index.js";
-import { buildServiceGroups, getAllServiceTags, getResolvedChannel, getServiceSelections, isChannelAvailableByService, isServiceVariant, resolveServiceKey, setEnabledServices, setServiceSelections } from "./services.js";
+import { PREDEFINED_CHANNELS, PREDEFINED_TAGS } from "../channels/index.js";
+import { buildServiceGroups, getAllServiceTags, getResolvedChannel, isChannelAvailableByService, isServiceVariant, resolveServiceKey, setEnabledServices, setServiceSelections } from "./services.js";
 import { CONFIG } from "./index.js";
 import fs from "node:fs";
 import { getChannelsFilePath } from "./paths.js";
+import { isDeepStrictEqual } from "node:util";
 import { mutateConfig } from "./userConfig.js";
 const { promises: fsPromises } = fs;
 /* The channels file path is resolved via the centralized paths module (config/paths.ts). The data directory is initialized at startup before channel loading.
@@ -43,9 +45,27 @@ export function hasChannelsParseError() {
 export function getChannelsParseErrorMessage() {
     return userChannelsParseErrorMessage;
 }
+/* Transactional store for channels.json. The store uses a compound type that carries channel data alongside metadata (serviceSelections, tagRegistry). The parse
+ * function extracts all three from the JSON file. The mutateChannels() wrapper normalizes predefined channel deltas before the write and adapts the compound
+ * type so callers work directly with StoredChannelMap. The beforeWrite hook injects metadata from module state.
+ */
+/* Current schema version for channels.json. Migrations are declared in channelsMigrations 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 - Pre-delta-model user variants. Identity fields stored redundantly on variants and stripped eagerly at load time.
+ *   2 - Delta-model user variants. Variants store only fields that differ from their canonical. The v1 -> v2 migration converts legacy-shaped variants by
+ *       stamping canonicalKey on entries whose identity fields match the canonical (shape-compatible with a legitimate variant) and skipping entries whose
+ *       fields differ (user standalones that happened to share a hyphenated key with a predefined canonical).
+ *   3 - Foxone-era service naming. The v2 -> v3 migration renames "foxcom" -> "foxone" in service selections and channel keys, and the special-case
+ *       "fox-site" -> "fox-foxone" rename for the FoxOne variant briefly mis-keyed in v1.8.0. Bumping this version also flushes parser-side legacy field
+ *       cleanups (provider -> service field, providerSelections -> serviceSelections key) to disk on the same write that lands the foxone rename.
+ */
+const CURRENT_CHANNELS_SCHEMA_VERSION = 3;
 /**
- * Parses raw channels.json content into the compound data type. Extracts channel entries, service selections, and tag registry from the top-level JSON object.
- * Also applies the legacy "provider" to "service" field migration.
+ * Parses raw channels.json content into the compound data type. Extracts channel entries, service selections, tag registry, and framework metadata
+ * (schemaVersion, migrationsApplied) from the top-level JSON object. Also performs structural normalization for legacy field/key naming so consumer code only
+ * sees the current shape; the schemaVersion progression governs when the cleanup is persisted to disk via the migration framework.
  * @param raw - The raw JSON string from the file.
  * @returns The parsed compound data.
  */
@@ -54,9 +74,29 @@ function parseChannelsFile(raw) {
     const channels = {};
     const serviceSelections = {};
     const tagRegistry = { deletedTags: [], tags: [] };
+    const migrationsApplied = [];
+    // Files predating the schemaVersion field are treated as version 1. The migration runner in the file store framework upgrades them to the current version.
+    let schemaVersion = 1;
     for (const [key, value] of Object.entries(parsed)) {
-        if ((key === "serviceSelections") || (key === "providerSelections")) {
-            // Copy service selections if it's an object. Accepts the legacy "providerSelections" key for backward compatibility.
+        if (key === "schemaVersion") {
+            // Tolerate bad data by falling back to version 1 - any plausibly-legacy value is fine, since migrations are idempotent when no work is needed.
+            if ((typeof value === "number") && Number.isFinite(value) && (value >= 1)) {
+                schemaVersion = Math.floor(value);
+            }
+        }
+        else if (key === "migrationsApplied") {
+            // Audit trail of migrations that have already been applied to this file. Strings only; non-string entries are dropped silently.
+            if (Array.isArray(value)) {
+                for (const entry of value) {
+                    if (typeof entry === "string") {
+                        migrationsApplied.push(entry);
+                    }
+                }
+            }
+        }
+        else if ((key === "serviceSelections") || (key === "providerSelections")) {
+            // Copy service selections if it is an object. Accepts the legacy "providerSelections" key for structural compatibility - the v2 -> v3 schema migration
+            // ensures the file is rewritten under the current key on next persist.
             if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
                 for (const [selKey, selValue] of Object.entries(value)) {
                     if (typeof selValue === "string") {
@@ -69,84 +109,333 @@ function parseChannelsFile(raw) {
             // Extract tag registry with defensive validation. String array fields (tags, deletedTags) drop non-string elements silently.
             if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
                 const rawRegistry = value;
-                if (Array.isArray(rawRegistry.tags)) {
-                    tagRegistry.tags = rawRegistry.tags.filter((t) => typeof t === "string").sort();
+                if (Array.isArray(rawRegistry["tags"])) {
+                    tagRegistry.tags = rawRegistry["tags"].filter((t) => typeof t === "string").sort();
                 }
-                if (Array.isArray(rawRegistry.deletedTags)) {
-                    tagRegistry.deletedTags = rawRegistry.deletedTags.filter((t) => typeof t === "string").sort();
+                if (Array.isArray(rawRegistry["deletedTags"])) {
+                    tagRegistry.deletedTags = rawRegistry["deletedTags"].filter((t) => typeof t === "string").sort();
                 }
             }
         }
         else if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
-            // It's a channel definition or delta override.
+            // It is a channel definition or delta override.
             channels[key] = value;
         }
     }
-    // Silent migration: rename legacy "provider" field to "service" on channel entries. The old field was used as a display name override for the service selection
-    // dropdown. New installs always write "service". This migration ensures existing channels.json files are upgraded transparently.
+    // Structural normalization: rename legacy "provider" field to "service" on channel entries. The old field was used as a display name override for the
+    // service selection dropdown; new installs always write "service". The schema migration to v3 stamps the version after this normalization is in memory,
+    // ensuring the persist on next write drops the legacy field from disk.
     for (const channel of Object.values(channels)) {
         const legacy = channel;
-        if (("provider" in legacy) && !("service" in legacy)) {
-            legacy.service = legacy.provider;
+        if ("provider" in legacy) {
+            if (!("service" in legacy)) {
+                legacy["service"] = legacy["provider"];
+            }
+            Reflect.deleteProperty(legacy, "provider");
         }
-        Reflect.deleteProperty(legacy, "provider");
     }
-    return { channels, serviceSelections, tagRegistry };
+    return { channels, migrationsApplied, schemaVersion, serviceSelections, tagRegistry };
 }
+/* Array-valued ChannelDelta fields whose equality requires canonical case-insensitive ordering before JSON.stringify. The set declares which array fields are
+ * unordered-set semantics rather than order-significant lists; equality for these fields canonical-sorts both sides so authoring-order or case differences do
+ * not defeat the match. Tags are the only such field today, but the property-based framing is the architectural truth: any unordered-set array field belongs in
+ * this set. The `satisfies` constraint keeps the list in sync with ChannelDelta's actual keys at compile time - renaming or removing a field forces this tuple
+ * to be updated.
+ */
+const CANONICAL_SORTED_ARRAY_FIELDS = new Set(["tags"]);
 /**
- * Normalizes predefined channel deltas by stripping no-op fields and strips null fields from user channels. A delta field is a no-op if: (1) its value is null
- * and the predefined doesn't have the field, (2) its value is undefined, or (3) its value matches the predefined's value exactly. After stripping, deltas with
- * no remaining fields are removed entirely.
- * @param channels - The raw channel entries to normalize.
- * @returns The normalized channel map.
+ * Normalizes a single stored entry as a delta against a base channel. Delta fields are dropped when they are no-ops: undefined values, nulls against a base
+ * that has no such field, and values that match the base exactly. Array-valued fields use JSON.stringify for equality with case-insensitive canonical sorting
+ * for the fields listed in CANONICAL_SORTED_ARRAY_FIELDS so authoring-order differences do not defeat the match. Non-delta fields (e.g., canonicalKey) pass
+ * through unchanged so the stored entry retains its relationship metadata.
+ * @param stored - The raw stored entry.
+ * @param base - The base Channel to diff against (predefined definition for overrides, resolved canonical for variants).
+ * @returns The normalized entry, or null when every field is a no-op and the entry would carry no information.
  */
-function normalizeChannelDeltas(channels) {
-    const filtered = {};
-    for (const [key, stored] of Object.entries(channels)) {
-        if (key in PREDEFINED_CHANNELS) {
-            const predefined = PREDEFINED_CHANNELS[key];
-            const cleaned = {};
-            let hasFields = false;
-            for (const [field, value] of Object.entries(stored)) {
-                // Skip non-delta fields (like canonicalKey) that aren't in the allowlist.
-                if (!DELTA_ALLOWED_FIELDS.has(field)) {
-                    continue;
-                }
-                // Skip undefined values - they have no effect.
-                if (value === undefined) {
-                    continue;
-                }
-                // Skip null values when the predefined doesn't have the field - clearing a nonexistent field is a no-op.
-                if ((value === null) && !(field in predefined)) {
-                    continue;
-                }
-                // Skip values that match the predefined exactly - redundant copies. Array fields (like tags) use JSON.stringify for comparison since reference equality
-                // always fails for arrays. Tags arrays are always sorted and lowercase, making JSON.stringify deterministic.
-                if (value !== null) {
-                    const predefinedValue = predefined[field];
-                    if (Array.isArray(value) ? (JSON.stringify(value) === JSON.stringify(predefinedValue)) : (predefinedValue === value)) {
-                        continue;
-                    }
-                }
+function normalizeEntryAgainstBase(stored, base) {
+    const cleaned = {};
+    let hasFields = false;
+    for (const [field, value] of Object.entries(stored)) {
+        // Non-delta fields (like canonicalKey) pass through so the stored entry keeps its relationship metadata - except when the base already declares the same
+        // value. For example, a user override of a predefined variant doesn't need to store canonicalKey because the predefined variant entry already declares it;
+        // stripping the redundant copy keeps the stored record minimal and lets an empty override collapse to nothing.
+        if (!DELTA_ALLOWED_FIELDS.has(field)) {
+            if (value === undefined) {
+                continue;
+            }
+            const baseValue = base[field];
+            if (baseValue !== value) {
                 cleaned[field] = value;
                 hasFields = true;
             }
-            // Preserve non-delta fields (like canonicalKey) that were on the stored entry.
-            for (const [field, value] of Object.entries(stored)) {
-                if (!DELTA_ALLOWED_FIELDS.has(field) && (value !== undefined)) {
-                    cleaned[field] = value;
-                    hasFields = true;
-                }
+            continue;
+        }
+        // Undefined delta values are no-ops.
+        if (value === undefined) {
+            continue;
+        }
+        // Null means "clear this field on the base." When the base does not have the field, the clear is a no-op and gets dropped. Otherwise null is preserved so
+        // the clear survives.
+        if (value === null) {
+            if (field in base) {
+                cleaned[field] = null;
+                hasFields = true;
             }
-            if (hasFields) {
-                filtered[key] = cleaned;
+            continue;
+        }
+        // Values that match the base exactly are redundant. Arrays compare by JSON.stringify; fields in CANONICAL_SORTED_ARRAY_FIELDS are sorted on both sides
+        // first so the equality check is order-independent.
+        const baseValue = base[field];
+        if (Array.isArray(value)) {
+            const canonical = CANONICAL_SORTED_ARRAY_FIELDS.has(field);
+            const left = canonical ? sortTags(value) : value;
+            const right = canonical ? sortTags((baseValue ?? [])) : baseValue;
+            if (isDeepStrictEqual(left, right)) {
+                continue;
             }
         }
+        else if (baseValue === value) {
+            continue;
+        }
+        cleaned[field] = value;
+        hasFields = true;
+    }
+    return hasFields ? (cleaned) : null;
+}
+/**
+ * Classifies a channel entry by consulting both the predefined catalog and the user's stored map. The kind determines how the entry is resolved, normalized, and
+ * displayed.
+ *
+ * Precondition: at least one of the predefined catalog or the stored map must have the key. Callers iterate over the union of key sets and therefore always
+ * satisfy this. Violating the precondition throws rather than returning a nullable - the alternative is a defensive undefined check at every call site for a
+ * case that never occurs, which is both dead code and a misleading contract.
+ * @param key - The channel key.
+ * @param stored - The stored entry from the user's channels map (if any).
+ * @returns The classification. Never undefined; see the precondition.
+ * @throws Error when neither PREDEFINED_CHANNELS nor the caller's stored map contains the key.
+ */
+function classifyEntry(key, stored) {
+    const predefined = PREDEFINED_CHANNELS[key];
+    const userCanonicalKey = stored ? stored.canonicalKey : undefined;
+    const canonicalKey = userCanonicalKey ?? predefined?.canonicalKey;
+    // Variant: either source declares canonicalKey pointing at a different entry.
+    if (canonicalKey && (canonicalKey !== key)) {
+        return { canonicalKey, kind: "variant", predefined, stored };
+    }
+    // Canonical: a predefined entry exists (optionally with a user override on top).
+    if (predefined) {
+        return { kind: "canonical", predefined, stored };
+    }
+    // Standalone: user-only entry. Stored must be defined here; predefined is falsy (else canonical branch caught) and the neither-side-present state violates
+    // the precondition.
+    if (stored) {
+        return { kind: "standalone", stored };
+    }
+    throw new Error("classifyEntry called with key '" + key + "' that exists in neither PREDEFINED_CHANNELS nor the stored map.");
+}
+/**
+ * Computes the field-name allowlist for a stored entry's expected shape. Stored entries fall into two structural shapes determined by classification:
+ *
+ *  - Canonical-shaped (kind = canonical or standalone): allowed fields are DELTA_ELIGIBLE_IDENTITY_KEYS ∪ DELTA_ELIGIBLE_BINDING_KEYS. The full delta surface.
+ *  - Variant-shaped (kind = variant): allowed fields are DELTA_ELIGIBLE_BINDING_KEYS plus the structural canonicalKey discriminator. Identity inherits from the
+ *    canonical and must not appear on variants per the architectural principle.
+ *
+ * Single source of truth for the shape rule. Used by filterToDeltaSurface (normalizer pre-strip) and by the customization accessor's per-pass walks. Routes
+ * shape determination through classifyEntry so any caller automatically picks up classifier improvements - no parallel logic for "is this a variant?".
+ * @param key - The channel key for classification.
+ * @param stored - The stored entry for classification.
+ * @returns The set of field names allowed for this entry's shape.
+ */
+function getAllowedFieldsForShape(key, stored) {
+    const isVariant = classifyEntry(key, stored).kind === "variant";
+    if (isVariant) {
+        return new Set([...DELTA_ELIGIBLE_BINDING_KEYS, "canonicalKey"]);
+    }
+    return new Set([...DELTA_ELIGIBLE_IDENTITY_KEYS, ...DELTA_ELIGIBLE_BINDING_KEYS]);
+}
+/**
+ * Filters a stored entry to its expected delta surface, stripping any field outside the allowed shape. Returns both the filtered entry and the names of any
+ * fields that were stripped, so callers can surface diagnostics.
+ *
+ * The shape rule is enforced here at storage-write time (called from normalizeChannelDeltas) so legacy data with orphan fields - non-delta-eligible identity
+ * (pacificStationId), non-delta-eligible binding (DOM hooks), or identity-on-variants - cleans up automatically on next save. The `stripped` array lets the
+ * caller log a warning when cleanup happens, giving operators visibility into the violation.
+ * @param key - The channel key for shape classification.
+ * @param stored - The stored entry to filter.
+ * @returns The filtered entry plus the list of stripped field names.
+ */
+function filterToDeltaSurface(key, stored) {
+    const allowed = getAllowedFieldsForShape(key, stored);
+    const filtered = {};
+    const stripped = [];
+    for (const [field, value] of Object.entries(stored)) {
+        if (allowed.has(field)) {
+            filtered[field] = value;
+        }
         else {
-            // User channels: strip null fields. Null is a delta convention for predefined channels ("clear this field") and has no meaning on full Channel
-            // definitions...the Channel type uses T | undefined, never T | null. This allows callers to uniformly use null for "empty/clear" without needing to
-            // know the storage convention.
-            filtered[key] = Object.fromEntries(Object.entries(stored).filter(([, v]) => v !== null));
+            stripped.push(field);
+        }
+    }
+    return { filtered, stripped };
+}
+/**
+ * Resolves a variant by layering canonical identity, the predefined variant entry (service binding), and the user delta in order. The canonical contributes
+ * ONLY identity (name, stationId, channelNumber, tags, etc.) - its service binding is for the canonical service and would be structurally wrong for any other
+ * service variant. The variant's binding is supplied by the predefined variant entry (typically: discovery-driven channelSelector, service-specific URL,
+ * profile overrides) and the user's stored delta.
+ *
+ * Fields propagate through the delta-overlay kernel so null-means-clear and undefined-means-inherit semantics apply uniformly at every layer.
+ *
+ * Precondition: at least one of predefined or stored must be defined. A variant with no binding source has nothing to resolve; the result would have no URL
+ * and no selector, and downstream consumers would fail at the consumption site. classifyEntry only returns a "variant" classification when at least one
+ * source carries canonicalKey, so the precondition is satisfied by the only in-tree caller (getMergedChannelMap). Other callers must guarantee the same.
+ * @param canonical - The resolved canonical channel. Variant identity inherits from here; canonical binding is intentionally stripped via pickIdentity.
+ * @param predefined - The predefined variant entry, if the key has one. Contributes service-binding fields and any per-variant channelNumber override.
+ * @param stored - The user's stored delta for this variant, if any. Applied last so user edits win over predefined variant fields.
+ * @returns The fully resolved variant.
+ */
+function resolveVariant(canonical, predefined, stored) {
+    // Identity-only base. The url field (required on ResolvedChannel) is supplied by the predefined variant or stored delta below; the cast acknowledges that
+    // intermediate state. After the chain completes, the result has url populated when at least one of the binding-bearing layers (predefined or stored) is
+    // present - which is the documented invariant for any well-formed variant entry.
+    let resolved = pickIdentity(canonical);
+    // Variant overlays apply binding fields only - identity stays from the canonical per the architectural principle that variants are pure tuning data. Both
+    // the predefined variant and the user's stored variant entry use the same binding-only overlay.
+    if (predefined) {
+        resolved = overlayVariantBinding(resolved, predefined);
+    }
+    if (stored) {
+        resolved = overlayVariantBinding(resolved, stored);
+    }
+    return resolved;
+}
+/* Dangling-canonical warning dedup. When a variant's canonicalKey points at a missing canonical, getMergedChannelMap preserves the variant as best it can but
+ * the user deserves a diagnostic - their data references something that is not there, and silently carrying on would hide a real data-integrity issue. We log
+ * once per (variant, canonical) pair to surface the problem without spamming the log on every mutation. When the canonical later reappears (user re-creates
+ * it, predefined gets restored), the pair is cleared from the set so a future regression re-warns.
+ */
+const warnedDanglingVariants = new Set();
+/**
+ * Composes a stable token identifying a dangling-variant relationship for the warning dedup set.
+ * @param variantKey - The variant channel key.
+ * @param canonicalKey - The canonical key the variant references.
+ * @returns The composite token.
+ */
+function danglingToken(variantKey, canonicalKey) {
+    return variantKey + " -> " + canonicalKey;
+}
+/**
+ * Emits a dangling-canonical warning at most once per (variant, canonical) pair for the lifetime of this process. Called from getMergedChannelMap whenever a
+ * variant references a canonical that is not present in the resolved map.
+ * @param variantKey - The variant key whose canonicalKey points at a missing canonical.
+ * @param canonicalKey - The missing canonical key.
+ */
+function warnDanglingCanonical(variantKey, canonicalKey) {
+    const token = danglingToken(variantKey, canonicalKey);
+    if (warnedDanglingVariants.has(token)) {
+        return;
+    }
+    warnedDanglingVariants.add(token);
+    LOG.warn("Channel variant '%s' references missing canonical '%s'. Preserving the variant as-is; restore the canonical or remove the variant to clear this.", variantKey, canonicalKey);
+}
+/**
+ * Builds the Pass 1 resolved-canonical map for a given stored map. Iterates every key present in either the predefined catalog or the stored map, resolves
+ * non-variant entries (canonicals and standalones), and returns the resulting ChannelMap. Variants are deliberately skipped - they depend on this map and are
+ * resolved in Pass 2 by the caller.
+ *
+ * This is shared by getMergedChannelMap (which uses the map directly as the starting point for its full resolution) and normalizeChannelDeltas (which uses the
+ * map as a source of bases for diffing variant deltas).
+ * @param stored - The stored channels map.
+ * @returns The resolved-canonical map, keyed by channel key.
+ */
+function buildResolvedCanonicals(stored) {
+    const result = {};
+    const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(stored)]);
+    for (const key of allKeys) {
+        const classification = classifyEntry(key, stored[key]);
+        if (classification.kind === "variant") {
+            continue;
+        }
+        if (classification.kind === "canonical") {
+            result[key] = classification.stored ? overlayDelta(classification.predefined, classification.stored) : classification.predefined;
+            continue;
+        }
+        // Standalone: defensive copy so downstream mutation cannot leak back into loadedUserChannels. A standalone is structurally equivalent to a CanonicalChannel
+        // (identity + binding, no canonicalKey).
+        const copy = { ...classification.stored };
+        copy.tags &&= copy.tags.slice();
+        result[key] = copy;
+    }
+    return result;
+}
+/**
+ * Strips null fields from a stored entry. Null is a delta-only convention meaning "clear this field on the base"; without a base to clear against, nulls
+ * have no meaning and get dropped. Used by normalizeChannelDeltas for standalone user channels and for dangling-canonical variants that fall back to
+ * standalone-style normalization.
+ * @param stored - The raw stored entry.
+ * @returns The entry with null-valued fields removed.
+ */
+function stripNulls(stored) {
+    return Object.fromEntries(Object.entries(stored).filter(([, v]) => v !== null));
+}
+/**
+ * Normalizes the stored channels map to its minimal delta form. Each entry is classified, diffed against its applicable base, and any no-op fields are
+ * stripped. Standalone user channels have no base, so nulls are stripped but everything else is preserved.
+ *
+ * The flow is uniform across kinds:
+ *
+ * - Canonical (predefined with user override): base is the predefined channel.
+ * - Variant: base is the resolved canonical layered with the predefined variant's service fields (the view the user sees in the form/table, so the delta
+ *   records only what differs from that).
+ * - Standalone: no base, null values are stripped as a storage convention.
+ *
+ * Entries whose normalized delta is empty collapse to nothing and get dropped - a redundant override carries no information, and resolution falls through to
+ * the default.
+ * @param channels - The raw channel entries to normalize.
+ * @returns The normalized channel map.
+ */
+function normalizeChannelDeltas(channels) {
+    const filtered = {};
+    const resolvedCanonicals = buildResolvedCanonicals(channels);
+    for (const [key, stored] of Object.entries(channels)) {
+        // Step 1: enforce the expected stored shape via filterToDeltaSurface. Strips orphan fields (non-delta-eligible identity, non-delta-eligible binding,
+        // identity-on-variants) before any diff computation. When fields are stripped, log a warning so operators see when their data is being cleaned. The shape
+        // rule is the same regardless of classification kind - canonicalKey-discriminated through filterToDeltaSurface internally.
+        const { filtered: shapeFiltered, stripped } = filterToDeltaSurface(key, stored);
+        if (stripped.length > 0) {
+            const isVariant = classifyEntry(key, stored).kind === "variant";
+            LOG.warn("Channel '%s' (%s-shaped) carried fields outside the delta surface: [%s]. Stripped during normalization.", key, isVariant ? "variant" : "canonical", stripped.join(", "));
+        }
+        // Step 2: classification-driven delta minimization against the appropriate base.
+        const classification = classifyEntry(key, shapeFiltered);
+        if (classification.kind === "canonical") {
+            const normalized = normalizeEntryAgainstBase(shapeFiltered, classification.predefined);
+            if (normalized) {
+                filtered[key] = normalized;
+            }
+            continue;
+        }
+        if (classification.kind === "standalone") {
+            filtered[key] = stripNulls(shapeFiltered);
+            continue;
+        }
+        // Variant. The normalization base is identity-from-canonical layered with the predefined variant's binding (if any) - the same shape the user sees in the
+        // form/table, so the delta records only what differs from that. Critically, this matches the inheritance shape used by resolveVariant: identity from
+        // canonical, binding from variant. Without the pickIdentity strip, the canonical service's binding would leak into the normalization base and stored
+        // overrides matching the canonical's binding would be incorrectly stripped as no-ops. A dangling canonical falls back to standalone-style normalization so
+        // the user does not silently lose data.
+        const canonical = resolvedCanonicals[classification.canonicalKey];
+        if (!canonical) {
+            filtered[key] = stripNulls(shapeFiltered);
+            continue;
+        }
+        const identityBase = pickIdentity(canonical);
+        // Mirror the resolveVariant chain: predefined-variant overlay applies binding fields only. The base computed here is what a stored variant entry should
+        // be diffed against - using a category-aware overlay keeps normalization symmetric with resolution.
+        const base = classification.predefined ? overlayVariantBinding(identityBase, classification.predefined) : identityBase;
+        const normalized = normalizeEntryAgainstBase(shapeFiltered, base);
+        if (normalized) {
+            filtered[key] = normalized;
         }
     }
     return filtered;
@@ -159,24 +448,133 @@ function normalizeChannelDeltas(channels) {
  * @returns The serializable output with channels and current metadata.
  */
 function prepareChannelsForWrite(data) {
-    // Build the serializable output with metadata from module state.
-    const output = { ...data.channels };
-    const selections = getServiceSelections();
-    if (Object.keys(selections).length > 0) {
-        output.serviceSelections = selections;
+    // Pure function of data. The framework guarantees data is the source of truth at write time - serviceSelections and tagRegistry come from data, never from
+    // module state. Module-state caches in services.ts and userChannels.ts are downstream of this writer (hydrated post-mutate from the same data), so reading
+    // them here would be a side channel that breaks correctness when the boot persist runs before module state is populated.
+    const output = { schemaVersion: data.schemaVersion, ...data.channels };
+    if (data.migrationsApplied.length > 0) {
+        output["migrationsApplied"] = data.migrationsApplied;
     }
-    if ((loadedTagRegistry.tags.length > 0) || (loadedTagRegistry.deletedTags.length > 0)) {
-        output.tagRegistry = loadedTagRegistry;
+    if (Object.keys(data.serviceSelections).length > 0) {
+        output["serviceSelections"] = data.serviceSelections;
+    }
+    if ((data.tagRegistry.tags.length > 0) || (data.tagRegistry.deletedTags.length > 0)) {
+        output["tagRegistry"] = data.tagRegistry;
     }
     return output;
 }
+/* Declarative schema migrations. The file store framework runs these in order from the file's stored schemaVersion up to CURRENT_CHANNELS_SCHEMA_VERSION,
+ * stamping the new version and recording the description in migrationsApplied after each application. Apply functions mutate the data in place. Any new
+ * migration is a single entry below; the framework wires the rest.
+ */
+const channelsMigrations = {
+    2: {
+        apply: (data) => {
+            // Stamp canonicalKey on hyphenated user channel entries whose identity matches a predefined canonical (shape-compatible variants). Conservative
+            // classifier - entries whose identity diverges are treated as user standalones and left alone.
+            const stampedKeys = collectLegacyVariantStamps(data.channels);
+            for (const key of stampedKeys) {
+                const channel = data.channels[key];
+                if (!channel) {
+                    continue;
+                }
+                const hyphenIndex = key.indexOf("-");
+                channel.canonicalKey = key.substring(0, hyphenIndex);
+            }
+        },
+        description: "Stamp canonicalKey on legacy user channel variant entries"
+    },
+    3: {
+        apply: (data) => {
+            // Rename foxcom -> foxone in service selections, the special-case fox-site -> fox-foxone, and corresponding channel keys. Bumping to v3 also flushes
+            // any parser-side legacy field cleanups (provider -> service field, providerSelections -> serviceSelections key) since the migration runner triggers a
+            // persist that writes the cleaned shape via prepareChannelsForWrite.
+            for (const [canonicalKey, selectedVariant] of Object.entries(data.serviceSelections)) {
+                if (selectedVariant.endsWith("-foxcom")) {
+                    data.serviceSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
+                }
+                if ((canonicalKey === "fox") && (selectedVariant === "fox-site")) {
+                    data.serviceSelections[canonicalKey] = "fox-foxone";
+                }
+            }
+            for (const [key, value] of Object.entries(data.channels)) {
+                if (key.endsWith("-foxcom")) {
+                    data.channels[key.slice(0, -6) + "foxone"] = value;
+                    Reflect.deleteProperty(data.channels, key);
+                }
+            }
+        },
+        description: "Rename foxcom service references to foxone and persist legacy field name cleanup"
+    }
+};
+/**
+ * Pre-write integrity validator for the channels store. Detects two classes of suspicious mutations:
+ *
+ *   1. Identity-field loss: a stored channel's identity field went from set to undefined without canonical fallback. Catches code that
+ *      accidentally drops user-authored channel data while normalizing or transforming entries.
+ *   2. Metadata wholesale clear: a top-level metadata collection (serviceSelections, tagRegistry.tags, tagRegistry.deletedTags) went from non-empty to empty
+ *      in a single mutation. Catches code that accidentally drops the entire collection (the original bug class - if a future writer or fn regression empties
+ *      one of these, this guard logs loudly even though the change is structurally allowed).
+ *
+ * Both checks are log-only - issues surface as warnings without blocking the write. Genuine wholesale clears (operator clears all selections via UI) are the
+ * rare false-positive case here; in practice those happen via per-entry mutations rather than a single empty assignment.
+ * @param prev - Pre-mutation snapshot of the file data.
+ * @param next - Post-mutation, post-normalize file data.
+ * @returns Issues found, or empty array.
+ */
+function validateChannelsIntegrity(prev, next) {
+    const issues = [];
+    for (const loss of detectIdentityFieldLoss(prev.channels, next.channels)) {
+        issues.push({
+            category: "identity-field-loss",
+            description: loss + " would be silently cleared without canonical fallback",
+            severity: "warning"
+        });
+    }
+    // Metadata wholesale-clear detection. Checks each top-level collection independently. Empty -> empty is a no-op (no issue); non-empty -> non-empty (any
+    // size) is a normal mutation; only non-empty -> empty is flagged.
+    if ((Object.keys(prev.serviceSelections).length > 0) && (Object.keys(next.serviceSelections).length === 0)) {
+        issues.push({
+            category: "metadata-wholesale-clear",
+            description: "serviceSelections went from " + String(Object.keys(prev.serviceSelections).length) + " entries to empty in a single mutation",
+            severity: "warning"
+        });
+    }
+    if ((prev.tagRegistry.tags.length > 0) && (next.tagRegistry.tags.length === 0)) {
+        issues.push({
+            category: "metadata-wholesale-clear",
+            description: "tagRegistry.tags went from " + String(prev.tagRegistry.tags.length) + " entries to empty in a single mutation",
+            severity: "warning"
+        });
+    }
+    if ((prev.tagRegistry.deletedTags.length > 0) && (next.tagRegistry.deletedTags.length === 0)) {
+        issues.push({
+            category: "metadata-wholesale-clear",
+            description: "tagRegistry.deletedTags went from " + String(prev.tagRegistry.deletedTags.length) + " entries to empty in a single mutation",
+            severity: "warning"
+        });
+    }
+    return issues;
+}
 // Transactional store instance for channels.json.
 const channelsStore = createFileStore({
     beforeWrite: prepareChannelsForWrite,
-    defaultValue: () => ({ channels: {}, serviceSelections: {}, tagRegistry: { deletedTags: [], tags: [] } }),
+    currentSchemaVersion: CURRENT_CHANNELS_SCHEMA_VERSION,
+    defaultValue: () => ({
+        channels: {},
+        migrationsApplied: [],
+        schemaVersion: CURRENT_CHANNELS_SCHEMA_VERSION,
+        serviceSelections: {},
+        tagRegistry: { deletedTags: [], tags: [] }
+    }),
+    getSchemaVersion: (data) => data.schemaVersion,
     label: "channels",
+    migrations: channelsMigrations,
     parse: parseChannelsFile,
-    path: getChannelsFilePath
+    path: getChannelsFilePath,
+    recordMigration: (data, description) => { data.migrationsApplied.push(description); },
+    setSchemaVersion: (data, version) => { data.schemaVersion = version; },
+    validate: validateChannelsIntegrity
 });
 /**
  * Reads the current channels from disk without acquiring the serialization lock. Returns the parsed channels with metadata and parse status. Use this for
@@ -189,30 +587,98 @@ export async function readChannels() {
         channels: result.data.channels,
         parseError: result.parseError,
         parseErrorMessage: result.parseErrorMessage,
+        recoveredFromBackup: result.recoveredFromBackup,
         serviceSelections: result.data.serviceSelections,
         tagRegistry: result.data.tagRegistry
     };
 }
 /**
- * Serialized read-modify-write operation on channels.json. The mutation function receives the current StoredChannelMap and modifies it in place. The store
- * handles atomicity, serialization, corruption guard, backup, and metadata injection. Delta normalization is applied after the caller's mutation and before the
- * file write so that the normalized result is available for the post-write cache update.
- * @param fn - Mutation function. Receives current channels. Modify in place; return value is ignored.
- * @throws FileStoreParseError if channels.json contains invalid JSON.
+ * Pre-write integrity guard. Compares the channels map captured immediately after parse against the channels map about to be written, and reports identity
+ * fields that have been silently dropped without a canonical fallback.
+ *
+ * Allowed transitions for any identity field:
+ *   - value -> same value  (no change)
+ *   - value -> different value (legitimate update)
+ *   - value -> null (explicit clear; null is the codebase-wide "clear this field" signal)
+ *   - field absent -> any value (new data)
+ *
+ * Forbidden transition (what this guard catches):
+ *   - value -> undefined / missing  WHERE the canonical (for variants and predefined-overrides) does not provide the same value
+ *
+ * Variant inheritance is honored: stripping a stored field that matches the canonical's value is delta minimization, not data loss, and is allowed. The check
+ * is non-blocking: it surfaces suspicious patterns for operator review without aborting legitimate code paths.
+ * @param before - The channels map captured immediately after parse, before the caller's mutation ran.
+ * @param after - The channels map after the caller's mutation and delta normalization.
+ * @returns A list of "key.field" strings naming each detected silent drop. Empty list means no losses.
+ */
+function detectIdentityFieldLoss(before, after) {
+    const losses = [];
+    for (const [key, beforeEntry] of Object.entries(before)) {
+        const afterEntry = after[key];
+        // Whole entry removed - this is intentional deletion (deleteUserChannel etc.), not a silent drop.
+        if (!afterEntry) {
+            continue;
+        }
+        // Determine the canonical fallback. For variants the canonicalKey field points at it; for overrides of predefined channels the entry's key is the
+        // canonical. For standalones (no predefined match, no canonicalKey) there is no fallback - any drop is a loss.
+        const canonicalKey = afterEntry.canonicalKey ?? key;
+        const canonical = PREDEFINED_CHANNELS[canonicalKey];
+        for (const field of CHANNEL_IDENTITY_KEYS) {
+            const beforeValue = beforeEntry[field];
+            const afterValue = afterEntry[field];
+            // Field was not set before - any post state is fine.
+            if ((beforeValue === undefined) || (beforeValue === null)) {
+                continue;
+            }
+            // Field is still present after (with any value, including null which means explicit clear) - allowed.
+            if (afterValue !== undefined) {
+                continue;
+            }
+            // Field went value -> undefined. Check whether the canonical provides the same value, in which case this is variant inheritance / delta minimization
+            // and not data loss. Array-valued fields (notably tags) are compared via JSON.stringify since reference equality would always fail.
+            const canonicalValue = canonical ? canonical[field] : undefined;
+            if (canonicalValue !== undefined) {
+                const sameValue = (Array.isArray(beforeValue) && Array.isArray(canonicalValue)) ?
+                    isDeepStrictEqual(beforeValue, canonicalValue) :
+                    (beforeValue === canonicalValue);
+                if (sameValue) {
+                    continue;
+                }
+            }
+            losses.push(key + "." + field);
+        }
+    }
+    return losses;
+}
+/**
+ * Serialized read-modify-write operation on channels.json. The mutation function receives the full file data (channels + serviceSelections + tagRegistry +
+ * framework metadata) and modifies it in place. The store handles atomicity, serialization, corruption guard, backup, schema migrations, and pre-write
+ * integrity validation. Delta normalization is applied to data.channels after the caller's mutation and before the file write so that the normalized result is
+ * available for the post-write cache hydration.
+ *
+ * After a successful write, the in-memory caches that mirror persisted state (loadedUserChannels, loadedTagRegistry, services.ts serviceSelections Map,
+ * runtime service groups) are hydrated from the just-written normalized data. This is the single direction caches flow: data is the source of truth, caches
+ * are derived. Callers must never poke caches directly and rely on a later save to pick up the change - all mutations go through this function.
+ * @param fn - Mutation function. Receives the full file data. Modify in place; return value is ignored.
+ * @throws FileStoreParseError if channels.json contains invalid JSON and the .bak rotation is also unparseable.
  */
 export async function mutateChannels(fn) {
-    // Normalized channels captured from inside the mutation callback for post-write cache update. Normalization runs inside the callback (under the
-    // serialization lock) so the same normalized data is written to disk and assigned to the cache.
-    let normalizedChannels = {};
+    // Captured from inside the callback so the post-write cache hydration sees the same normalized data the framework wrote to disk. Captured before the await
+    // returns, but the assignments below only run if the store mutation (including atomic file write) completed without error.
+    let writtenData;
     await channelsStore.mutate((data) => {
-        fn(data.channels);
-        // Normalize deltas before the beforeWrite hook serializes the data. This ensures the in-memory cache and the on-disk representation are identical.
-        // The beforeWrite hook (prepareChannelsForWrite) handles metadata injection only.
+        fn(data);
+        // Normalize channel deltas before the beforeWrite hook serializes the data. This ensures the in-memory cache and the on-disk representation are
+        // identical. Other top-level fields (serviceSelections, tagRegistry, framework metadata) are not delta-shaped and pass through unchanged.
         data.channels = normalizeChannelDeltas(data.channels);
-        normalizedChannels = data.channels;
+        writtenData = data;
     });
-    // Side effects after successful write. These only run if the store mutation (including atomic file write) completed without error.
-    loadedUserChannels = { ...normalizedChannels };
+    // Side effects after successful write. The store framework guarantees writtenData reflects exactly what was persisted.
+    if (writtenData) {
+        loadedUserChannels = { ...writtenData.channels };
+        loadedTagRegistry = writtenData.tagRegistry;
+        setServiceSelections(writtenData.serviceSelections);
+    }
     buildServiceGroups(getMergedChannelMap());
     userChannelsParseError = false;
     userChannelsParseErrorMessage = undefined;
@@ -224,11 +690,48 @@ export async function mutateChannels(fn) {
  * @throws If the file cannot be written.
  */
 export async function deleteUserChannel(key) {
-    await mutateChannels((channels) => {
-        Reflect.deleteProperty(channels, key);
+    await mutateChannels((data) => {
+        Reflect.deleteProperty(data.channels, key);
     });
     LOG.info("User channel '%s' deleted.", key);
 }
+/**
+ * Removes all user override entries for a canonical channel - both the canonical-stored entry and the active service variant's stored entry (when one resolves
+ * via explicit selection or service-filter fallback). Returns the stored entry that was deleted (canonical takes precedence; falls back to the variant entry
+ * when canonical is absent) so callers can compute downstream effects like the playlist reload hint without duplicating the lookup.
+ *
+ * Callers wrap the call in mutateChannels() and pass the resulting StoredChannelMap. The helper operates on the map directly; it does not own the mutation
+ * lifecycle, allowing callers to combine the dual-delete with other operations (e.g., setting serviceSelections) in the same atomic write.
+ * @param channels - The stored channels map to mutate in place.
+ * @param canonicalKey - The canonical channel key. The active variant is resolved internally via resolveServiceKey.
+ * @returns The stored entry that existed pre-deletion (canonical first, variant fallback). Undefined when neither entry existed.
+ */
+export function clearChannelOverrides(channels, canonicalKey) {
+    const resolvedKey = resolveServiceKey(canonicalKey);
+    const activeVariantKey = (resolvedKey === canonicalKey) ? undefined : resolvedKey;
+    // Canonical takes precedence for the returned entry because the canonical entry is the editing target; the variant entry is secondary cleanup. Falls back
+    // to the variant entry only when canonical is absent so callers still see a non-undefined result for variant-only revert cases.
+    const stored = channels[canonicalKey] ?? (activeVariantKey ? channels[activeVariantKey] : undefined);
+    Reflect.deleteProperty(channels, canonicalKey);
+    if (activeVariantKey) {
+        Reflect.deleteProperty(channels, activeVariantKey);
+    }
+    return stored;
+}
+/**
+ * Merges a partial ChannelDelta into a stored entry. Returns a new entry with the existing fields preserved and the delta's fields layered on top. Used by
+ * bulk operations that update one or more delta fields across many channels - the helper handles both the "no entry exists yet" case (uses an empty record)
+ * and the "entry exists with prior overrides" case (preserves them) without forcing each call site to write the spread + assign manually.
+ *
+ * The merged entry is returned in StoredChannel shape; callers assign it back to data.channels[key]. The post-mutation normalizer (filterToDeltaSurface +
+ * normalizeEntryAgainstBase) handles delta minimization and shape enforcement, so callers can pass arbitrary ChannelDelta keys without pre-validating them.
+ * @param stored - The existing stored entry, or undefined when the channel has no prior overrides.
+ * @param delta - Fields to assign onto the entry. Null values flow through unchanged for the delta-clear semantic.
+ * @returns The merged stored entry.
+ */
+export function applyChannelDelta(stored, delta) {
+    return { ...stored, ...delta };
+}
 /**
  * Resets all user channels by deleting the channels file.
  * @throws If the file exists but cannot be deleted.
@@ -249,64 +752,81 @@ export async function resetUserChannels() {
 }
 /* User channels are loaded at server startup and stored in module-level state. This avoids repeated file reads during request handling.
  */
+/**
+ * Classifies which stored entries are legitimate legacy variants eligible for canonicalKey stamping. A legitimate legacy variant has a hyphenated key whose
+ * prefix matches a predefined canonical AND every stored identity field either is absent or matches the canonical's value. Entries with diverging identity
+ * are user-created standalones that happen to share the hyphenated key shape (e.g., "abc-kabc" as a local affiliate with its own channel number and station
+ * ID) and must be left alone - stamping them would mark them for delta normalization and silently destroy the user's custom identity.
+ *
+ * Array-valued identity fields (tags) compare via JSON.stringify with case-insensitive canonical sorting so historical write order does not defeat the match.
+ * @param channels - The raw stored channel entries.
+ * @returns Keys that should receive a canonicalKey stamp. Empty when nothing needs migrating.
+ */
+function collectLegacyVariantStamps(channels) {
+    const stamps = [];
+    for (const [key, stored] of Object.entries(channels)) {
+        // Entries that already declare canonicalKey are already on the new model - skip.
+        if (stored.canonicalKey) {
+            continue;
+        }
+        const hyphenIndex = key.indexOf("-");
+        if (hyphenIndex === -1) {
+            continue;
+        }
+        const prefix = key.substring(0, hyphenIndex);
+        const canonical = PREDEFINED_CHANNELS[prefix];
+        if (!canonical) {
+            continue;
+        }
+        // Safe classifier: stamp only when every stored identity field is either absent or matches the canonical exactly. Any divergence signals a user-created
+        // standalone that happens to share the variant-shaped key; stamping would trigger delta normalization and destroy the user's custom identity.
+        let shapeCompatible = true;
+        for (const field of CHANNEL_IDENTITY_KEYS) {
+            const storedValue = stored[field];
+            if (storedValue === undefined) {
+                continue;
+            }
+            const canonicalValue = canonical[field];
+            if (Array.isArray(storedValue) && Array.isArray(canonicalValue)) {
+                if (!isDeepStrictEqual(sortTags(storedValue), sortTags(canonicalValue))) {
+                    shapeCompatible = false;
+                    break;
+                }
+                continue;
+            }
+            if (storedValue !== canonicalValue) {
+                shapeCompatible = false;
+                break;
+            }
+        }
+        if (shapeCompatible) {
+            stamps.push(key);
+        }
+    }
+    return stamps;
+}
 /**
  * Initializes user channels by loading them from the file. This should be called once at server startup. Also builds service groups and loads service selections.
  */
 export async function initializeUserChannels() {
+    // Read the file. Schema migrations (canonicalKey stamping, foxcom -> foxone rename, etc.) run automatically inside the file store framework via the
+    // declarative channelsMigrations registry; ensureMigrated (called by the release boot coordinator at startup) persists any upgrades to disk before this
+    // function runs. The data returned here is always at CURRENT_CHANNELS_SCHEMA_VERSION.
     const result = await readChannels();
-    // Populate module-level state from the loaded file. Migrations below may call mutateChannels(), which updates loadedUserChannels via its side effects
-    // with normalized data. Setting the initial state here ensures the cache is populated even when no migrations run.
+    // Populate module-level state from the loaded (and already-migrated) data.
     loadedUserChannels = result.channels;
     loadedTagRegistry = result.tagRegistry;
     userChannelsParseError = result.parseError;
     userChannelsParseErrorMessage = result.parseErrorMessage;
-    // Silent migrations: rename stale service keys to their current equivalents. Migrates service selections (channels.json) and user channel variant keys.
-    // The service filter (config.json) is handled separately below since it's already loaded into CONFIG at this point.
-    let channelsMigrated = false;
-    for (const [canonicalKey, selectedVariant] of Object.entries(result.serviceSelections)) {
-        // foxcom → foxone: original Fox service slug renamed.
-        if (selectedVariant.endsWith("-foxcom")) {
-            result.serviceSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
-            channelsMigrated = true;
-        }
-        // fox-site → fox-foxone: the "fox" channel's FoxOne variant was briefly keyed as "site" in v1.8.0 instead of "foxone" like every other Fox channel.
-        if ((canonicalKey === "fox") && (selectedVariant === "fox-site")) {
-            result.serviceSelections[canonicalKey] = "fox-foxone";
-            channelsMigrated = true;
-        }
-    }
-    // Load service selections before saving so that mutateChannels (which persists both channels and selections via the beforeWrite hook) captures the
-    // migrated values from module state.
-    setServiceSelections(result.serviceSelections);
-    if (channelsMigrated) {
-        await mutateChannels((channels) => {
-            // Apply the foxcom → foxone channel key migration. The mutation reads fresh from disk, so we replay the transform rather than passing the in-memory
-            // result. The fox-site selection migration is selection-only (no channel keys to rename).
-            for (const key of Object.keys(channels)) {
-                if (key.endsWith("-foxcom")) {
-                    channels[key.slice(0, -6) + "foxone"] = channels[key];
-                    Reflect.deleteProperty(channels, key);
-                }
-            }
-        });
-        LOG.info("Migrated stale Fox service references.");
-    }
-    // Load enabled services from the configuration, validating that each tag is recognized. Invalid tags (e.g., from hand-edited config.json typos) are stripped
-    // silently after logging a warning. Validation must happen after buildServiceGroups() because getAllServiceTags() depends on the groups being built.
-    let configuredServices = CONFIG.channels.enabledServices;
-    // Silent migration: rename "foxcom" to "foxone" in the service filter if present. Persisted to config.json immediately so the stale value doesn't remain.
-    if (configuredServices.includes("foxcom")) {
-        configuredServices = configuredServices.map((tag) => (tag === "foxcom") ? "foxone" : tag);
-        CONFIG.channels.enabledServices = configuredServices;
-        await mutateConfig((config) => {
-            if (config.channels?.enabledServices) {
-                config.channels.enabledServices = configuredServices;
-            }
-        });
-        LOG.info("Migrated service filter from foxcom to foxone.");
+    if (result.recoveredFromBackup) {
+        LOG.info("Channels were recovered from backup after a corrupt main file.");
     }
-    // Upgrade inference for setupCompleted: existing users who already have services or channels configured should not see the first-run setup wizard. If the
-    // flag is not set in the config file and evidence of prior configuration exists, infer true and persist.
+    // Load service selections so prepareChannelsForWrite captures them on subsequent writes.
+    setServiceSelections(result.serviceSelections);
+    // Inference for setupCompleted: existing users who already have services or channels configured should not see the first-run setup wizard. This is runtime
+    // inference (not a schema migration) because it depends on observed state from two stores (channels and config) and never changes the file shape - only
+    // sets a flag based on what exists. Lives here at the cross-store boundary where both stores are loaded.
+    const configuredServices = CONFIG.channels.enabledServices;
     if (!CONFIG.channels.setupCompleted) {
         const hasServices = configuredServices.length > 0;
         const hasUserChannels = Object.keys(loadedUserChannels).length > 0;
@@ -318,97 +838,35 @@ export async function initializeUserChannels() {
             });
         }
     }
-    // One-time migration: stamp canonicalKey on existing user channel variant entries that were created before explicit variant relationships were introduced.
-    // These entries have hyphenated keys where the prefix is a known predefined canonical (e.g., "espn-hulu" where "espn" exists). The heuristic runs once —
-    // new entries get canonicalKey written at creation time by the browse modal.
-    let canonicalKeyMigrated = false;
-    for (const [key, channel] of Object.entries(result.channels)) {
-        // Skip entries that already have canonicalKey.
-        if (channel.canonicalKey) {
-            continue;
-        }
-        const hyphenIndex = key.indexOf("-");
-        if (hyphenIndex === -1) {
-            continue;
-        }
-        const prefix = key.substring(0, hyphenIndex);
-        // Only stamp canonicalKey if the prefix exists as a predefined channel. This matches the old buildServiceGroups heuristic exactly.
-        if (prefix in PREDEFINED_CHANNELS) {
-            channel.canonicalKey = prefix;
-            canonicalKeyMigrated = true;
-        }
-    }
-    if (canonicalKeyMigrated) {
-        await mutateChannels((channels) => {
-            for (const [key, channel] of Object.entries(channels)) {
-                if (channel.canonicalKey) {
-                    continue;
-                }
-                const hyphenIndex = key.indexOf("-");
-                if (hyphenIndex === -1) {
-                    continue;
-                }
-                const prefix = key.substring(0, hyphenIndex);
-                if (prefix in PREDEFINED_CHANNELS) {
-                    channel.canonicalKey = prefix;
-                }
-            }
-        });
-        LOG.info("Migrated user channel variant entries with explicit canonical key declarations.");
-    }
-    // One-time migration: strip identity fields from user channel variant entries. Identity fields (name, stationId, tags, etc.) are resolved from the canonical
-    // at runtime via applyVariantInheritance, so storing them on variants is redundant. Older versions wrote these fields on variant creation. This migration
-    // cleans them up so channels.json only contains service-specific fields on variant entries.
-    let variantFieldsMigrated = false;
-    for (const channel of Object.values(result.channels)) {
-        if (!channel.canonicalKey) {
-            continue;
-        }
-        for (const field of CHANNEL_IDENTITY_FIELDS) {
-            if (field in channel) {
-                Reflect.deleteProperty(channel, field);
-                variantFieldsMigrated = true;
-            }
-        }
-    }
-    if (variantFieldsMigrated) {
-        await mutateChannels((channels) => {
-            for (const channel of Object.values(channels)) {
-                if (!channel.canonicalKey) {
-                    continue;
-                }
-                for (const field of CHANNEL_IDENTITY_FIELDS) {
-                    if (field in channel) {
-                        Reflect.deleteProperty(channel, field);
-                    }
-                }
-            }
-        });
-        LOG.info("Stripped redundant identity fields from user channel variant entries.");
-    }
     // Build the merged channels map and then build service groups.
     const mergedChannels = getMergedChannelMap();
-    // buildServiceGroups validates stored service selections against the rebuilt variant structure and reverts any that are stale. If any were cleaned, persist
-    // once so the cleanup survives restarts. At runtime (via mutateChannels), the in-memory cleanup is sufficient and persists naturally on the next write.
+    // buildServiceGroups validates stored service selections against the rebuilt variant structure and reverts any that are stale (cleared from module state).
+    // If any were cleaned, persist the same cleanup to disk so the file matches the runtime state and the cleanup survives restarts. mutateChannels operates on
+    // the freshly-read on-disk data; explicitly deleting the stale keys from data.serviceSelections is the data-side equivalent of the module-side cleanup
+    // buildServiceGroups already performed.
     const staleSelections = buildServiceGroups(mergedChannels);
     if (staleSelections.length > 0) {
-        await saveServiceSelections();
+        await mutateChannels((data) => {
+            for (const key of staleSelections) {
+                Reflect.deleteProperty(data.serviceSelections, key);
+            }
+        });
     }
     // Now that service groups are built, validate the configured service tags. Strip any unrecognized tags and warn.
     if (configuredServices.length > 0) {
         const knownTags = new Set(getAllServiceTags().map((t) => t.tag));
-        const validTags = configuredServices.filter((tag) => knownTags.has(tag));
-        const invalidTags = configuredServices.filter((tag) => !knownTags.has(tag));
+        const configuredSet = new Set(configuredServices);
+        const validTags = [...configuredSet.intersection(knownTags)];
+        const invalidTags = [...configuredSet.difference(knownTags)];
         if (invalidTags.length > 0) {
             LOG.warn("Ignoring unrecognized service tags in configuration: %s.", invalidTags.join(", "));
         }
         setEnabledServices(validTags);
-        CONFIG.channels.enabledServices = validTags;
     }
     else {
         setEnabledServices(configuredServices);
     }
-    // Check for non-printable characters in loaded channel string values. These warnings are informational — loaded data is not modified.
+    // Check for non-printable characters in loaded channel string values. These warnings are informational - loaded data is not modified.
     for (const [channelKey, stored] of Object.entries(loadedUserChannels)) {
         for (const [field, value] of Object.entries(stored)) {
             if ((typeof value === "string") && containsNonPrintable(value)) {
@@ -426,58 +884,173 @@ export async function initializeUserChannels() {
         LOG.info("Loaded %d channels.", totalCount);
     }
 }
-// User-editable fields for predefined channel delta overrides. Derived from CHANNEL_IDENTITY_FIELDS (identity fields like name, stationId, tags) plus the
-// service-specific fields exposed in the edit form (channelSelector, profile, url). This derivation ensures that adding a new identity field to
-// CHANNEL_IDENTITY_FIELDS automatically includes it in the delta allowlist.
-const SERVICE_SPECIFIC_EDITABLE_FIELDS = ["channelSelector", "profile", "url"];
-const DELTA_ALLOWED_FIELDS = new Set([...CHANNEL_IDENTITY_FIELDS, ...SERVICE_SPECIFIC_EDITABLE_FIELDS]);
+// Variant overlay allowlist used by the resolver (overlayVariantBinding). The resolver runs against catalog data merged with user storage, and predefined
+// variants legitimately carry DOM-hook binding fields (dismissSelector, scrollSelector, etc.) set by the catalog flattener. So the resolver's allowlist is the
+// FULL binding partition, NOT the delta-eligible subset - this is correct domain asymmetry: the resolver accepts catalog-domain data, while storage filtering
+// (filterToDeltaSurface) restricts to user-domain data. Identity fields encountered in a variant entry are silently dropped here - canonical's identity always
+// wins by construction.
+const VARIANT_OVERLAY_ALLOWED_FIELDS = new Set(CHANNEL_BINDING_KEYS);
+// The runtime delta surface: every field that may legitimately appear in a stored ChannelDelta override. Derived from the partition arrays in types/channels.ts
+// so adding or removing a delta-eligible field in one place propagates everywhere. Typed as Set<string> for ergonomics at .has() call sites that take string-keyed
+// values from Object.entries iteration; the contents are statically-known CustomizableField values via the spread above.
+const DELTA_ALLOWED_FIELDS = new Set([...DELTA_ELIGIBLE_IDENTITY_KEYS, ...DELTA_ELIGIBLE_BINDING_KEYS]);
 /**
- * Resolves a stored channel entry (full definition or delta) into a fully resolved Channel. For user-defined channels with no predefined equivalent, the stored
- * entry is returned as-is (it must be a full Channel). For overrides of predefined channels, the predefined definition is used as a base and only allowlisted
- * delta fields are overlaid. Fields set to null in the delta are removed from the result. Fields not in the allowlist are silently ignored.
- * @param key - The channel key.
- * @param stored - The stored channel data (full definition or delta).
- * @returns A fully resolved Channel with all fields populated.
+ * Extracts the identity-only subset of a channel. Used by resolveVariant and normalizeChannelDeltas to compute the inheritance base for variants: a variant
+ * inherits identity from its canonical but must contribute its own service binding (URL, channelSelector, profile, etc.) - the canonical's binding is for the
+ * canonical service and is structurally wrong for any other service.
+ *
+ * The fields copied are exactly those listed in CHANNEL_IDENTITY_KEYS, the single source of truth for the identity partition. Array-valued fields are shallow-
+ * copied so downstream mutation cannot leak back into the source.
+ * @param channel - The channel to extract identity from. Typed as ResolvedChannel because that is the shape after canonical resolution; CanonicalChannel is
+ *   structurally compatible.
+ * @returns A new ChannelIdentity object with just the identity fields populated.
  */
-export function resolveStoredChannel(key, stored) {
-    const predefined = PREDEFINED_CHANNELS[key];
-    // No predefined equivalent — this is a user-defined channel, return as-is. The caller is responsible for ensuring it has a url field.
-    // Runtime check needed — TypeScript thinks Record indexing always returns a value, but the key may not exist.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!predefined) {
-        return stored;
-    }
-    // Start with a copy of the predefined definition, then overlay allowlisted non-null delta fields. The spread creates a shallow copy — reference-type fields
-    // (like tags) share the same array instance as PREDEFINED_CHANNELS. The defensive copy below ensures the returned Channel is fully independent so callers can
-    // safely modify it without corrupting the predefined source of truth.
-    const resolved = { ...predefined };
-    for (const [field, value] of Object.entries(stored)) {
-        if (!DELTA_ALLOWED_FIELDS.has(field)) {
+export function pickIdentity(channel) {
+    const identity = {};
+    for (const field of CHANNEL_IDENTITY_KEYS) {
+        const value = channel[field];
+        if (value === undefined) {
             continue;
         }
-        if (value === null) {
-            // Explicit null means "clear this field" — delete it from the resolved object.
-            Reflect.deleteProperty(resolved, field);
+        identity[field] = value;
+    }
+    identity.tags &&= identity.tags.slice();
+    return identity;
+}
+/**
+ * Overlays a stored channel (full definition or delta) onto a base. Allowlisted delta fields in the stored entry override the base: a null value clears the
+ * field from the resolved object, a defined value replaces it, and missing fields inherit from the base. Non-delta fields on the stored entry (e.g.,
+ * canonicalKey) pass through so the resolved channel retains its relationship metadata. The returned object is a fresh reference with a defensive copy of any
+ * array-valued fields, so callers can mutate it without corrupting the base.
+ *
+ * This is the single delta-overlay kernel used by both predefined overrides and user variants. The base may be:
+ *
+ * - A predefined CanonicalChannel for canonical-override resolution.
+ * - A ChannelIdentity-only intermediate during variant resolution (URL is supplied by the variant binding overlay).
+ * - A fully resolved canonical for variant base computation.
+ *
+ * Internally typed as ResolvedChannel for the input shape; intermediate variant-resolution states pass through a cast because url is required on
+ * ResolvedChannel but is supplied by the next overlay. The contract is: after the full resolveVariant chain, the result has every required field populated.
+ * @param base - The base channel to inherit from.
+ * @param stored - The stored entry (delta) to overlay.
+ * @returns A new ResolvedChannel with the base's fields and the stored entry's overrides applied.
+ */
+function overlayDelta(base, stored) {
+    return applyOverlayKernel(base, stored, { allowedFields: DELTA_ALLOWED_FIELDS, passThroughOthers: true });
+}
+/**
+ * Shared overlay kernel used by overlayDelta and overlayVariantBinding. Walks the stored entry's fields and applies them to a clone of base under three rules:
+ * fields in allowedFields apply with delta semantics (null clears, undefined skips, value overrides); non-allowed fields either pass through (delta) or are
+ * silently dropped (variant overlay) per passThroughOthers; canonicalKey is always allowed regardless of the gate so resolved variants retain their relationship
+ * metadata. The kernel exists to keep the two overlays from drifting - identical control flow lived in both call sites before this consolidation.
+ * @param base - The base channel to clone and overlay onto.
+ * @param stored - The stored entry whose fields override the base.
+ * @param options - allowedFields selects which fields apply with delta semantics; passThroughOthers controls whether non-allowed fields flow through or are
+ *   dropped. canonicalKey is always passed through.
+ * @returns A new ResolvedChannel with overlay applied.
+ */
+function applyOverlayKernel(base, stored, options) {
+    const resolved = { ...base };
+    for (const [field, value] of Object.entries(stored)) {
+        if (options.allowedFields.has(field)) {
+            if (value === null) {
+                // Explicit null means "clear this field" - delete it from the resolved object.
+                Reflect.deleteProperty(resolved, field);
+            }
+            else if (value !== undefined) {
+                // Non-null, non-undefined - override the base value.
+                resolved[field] = value;
+            }
+            continue;
         }
-        else if (value !== undefined) {
-            // Non-null, non-undefined — override the predefined value.
+        // Non-allowed fields: pass through under delta semantics, or always pass canonicalKey as relationship metadata. Undefined values skipped per the
+        // standard "undefined inherits" rule.
+        if ((options.passThroughOthers || (field === "canonicalKey")) && (value !== undefined)) {
             resolved[field] = value;
         }
     }
-    // Defensive copy of reference-type fields to break shared references with PREDEFINED_CHANNELS. The delta overlay above may have replaced tags entirely (if
-    // the delta included a tags array), but when no delta is present for tags, the spread leaves the predefined's array reference on the resolved object.
+    // Defensive copy of reference-type fields to break shared references with the base. The overlay above may have replaced tags entirely (if the stored
+    // entry included a tags array), but when no delta is present for tags, the spread leaves the base's array reference on the resolved object.
     resolved.tags &&= resolved.tags.slice();
     return resolved;
 }
+/**
+ * Variant-binding-only overlay. Like overlayDelta but applies only fields in CHANNEL_BINDING_KEYS - identity fields on the variant entry are silently dropped
+ * during resolution. This enforces the architectural principle that variants are pure tuning data: how to reach the channel via this service. Identity
+ * (channelNumber, hdhrEnabled, tags, name, etc.) is a property of the channel as a whole and lives only on the canonical entry.
+ *
+ * Used by resolveVariant for both predefined-variant and stored-variant overlays. Legacy data, hand-edited files, or future migrations that put identity
+ * fields on variant entries are inert at resolution time - canonical's identity always wins. canonicalKey passes through as relationship metadata so the
+ * resolved variant can still be identified as a variant.
+ *
+ * Null/undefined semantics match overlayDelta: null clears the field; undefined inherits.
+ * @param base - The base channel (typically canonical identity from pickIdentity).
+ * @param stored - The variant entry (predefined or user-stored).
+ * @returns A new ResolvedChannel with binding fields applied from the variant.
+ */
+function overlayVariantBinding(base, stored) {
+    return applyOverlayKernel(base, stored, { allowedFields: VARIANT_OVERLAY_ALLOWED_FIELDS, passThroughOthers: false });
+}
+/**
+ * Resolves a stored channel entry into a fully populated ResolvedChannel. Handles the two non-variant cases:
+ *
+ * 1. Predefined override (key matches a predefined entry): the stored entry is a delta over the predefined canonical definition.
+ * 2. Standalone user channel (no predefined equivalent): the stored entry is already a full channel; a defensive copy is returned so downstream mutations
+ *    cannot leak into loadedUserChannels.
+ *
+ * Variants are resolved by getMergedChannelMap via the layered overlay (canonical identity -> predefined variant binding -> user delta). Callers that need a
+ * resolved variant should read from channelsRef (via getResolvedChannel) rather than calling this function with a variant key.
+ * @param key - The channel key (must not be a variant key).
+ * @param stored - The stored channel data.
+ * @returns A fully resolved channel with identity and binding both populated.
+ */
+export function resolveStoredChannel(key, stored) {
+    const predefined = PREDEFINED_CHANNELS[key];
+    if (predefined) {
+        return overlayDelta(predefined, stored);
+    }
+    // Standalone: defensive copy so callers can mutate the result without corrupting loadedUserChannels. A standalone is structurally a CanonicalChannel
+    // (identity + binding, no canonicalKey) and therefore satisfies ResolvedChannel.
+    const standalone = { ...stored };
+    standalone.tags &&= standalone.tags.slice();
+    return standalone;
+}
 /**
  * Returns the merged channel map (predefined + user) without filtering by enabled status or service variants. Used internally for building service groups.
- * Resolves any delta overrides into full Channel objects so the result contains only complete definitions.
+ * Resolves deltas into fully populated channels.
+ *
+ * Built from buildResolvedCanonicals (Pass 1: canonicals and standalones) plus a variant pass (Pass 2: layered canonical identity -> predefined variant
+ * binding -> user delta). The dangling-canonical path preserves whatever data exists so the user does not silently lose anything when a canonicalKey points
+ * at a missing entry.
  * @returns The complete merged channel map.
  */
 function getMergedChannelMap() {
-    const result = { ...PREDEFINED_CHANNELS };
-    for (const [key, stored] of Object.entries(loadedUserChannels)) {
-        result[key] = resolveStoredChannel(key, stored);
+    const result = buildResolvedCanonicals(loadedUserChannels);
+    const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
+    for (const key of allKeys) {
+        const stored = loadedUserChannels[key];
+        const classification = classifyEntry(key, stored);
+        if (classification.kind !== "variant") {
+            continue;
+        }
+        const canonical = result[classification.canonicalKey];
+        if (canonical) {
+            result[key] = resolveVariant(canonical, classification.predefined, classification.stored);
+            // Clear the dangling-warning dedup entry if one was recorded earlier: a previously-missing canonical is now present, so a future regression should
+            // re-warn rather than staying silent because we already warned once.
+            warnedDanglingVariants.delete(danglingToken(key, classification.canonicalKey));
+            continue;
+        }
+        // Dangling canonical: the variant references a canonical that is not present. Warn once per (variant, canonical) pair, then preserve the variant as best
+        // we can so the user does not silently lose data. When a stored entry exists, funnel through resolveStoredChannel - it already overlays onto the
+        // predefined definition (if any) or returns a standalone copy. When only the predefined entry exists, use it directly.
+        warnDanglingCanonical(key, classification.canonicalKey);
+        if (classification.stored) {
+            result[key] = resolveStoredChannel(key, classification.stored);
+        }
+        else if (classification.predefined) {
+            result[key] = classification.predefined;
+        }
     }
     return result;
 }
@@ -485,7 +1058,7 @@ function getMergedChannelMap() {
  * classification and enabled status. All other channel retrieval functions that need merged data build on top of it.
  */
 /**
- * Returns the full channel listing with source classification and enabled status. This is the authoritative merge point for predefined and user channels — all
+ * Returns the full channel listing with source classification and enabled status. This is the authoritative merge point for predefined and user channels - all
  * code that needs a merged view of channels should use this function (or getAllChannels() which delegates to it).
  *
  * For each channel key, the source is classified as:
@@ -496,7 +1069,7 @@ function getMergedChannelMap() {
  * The enabled field reflects whether the channel is available for streaming. Predefined-only channels can be disabled via configuration; user and override
  * channels are always enabled.
  *
- * Service variants (non-canonical keys in service groups) are filtered out from this listing — they are accessed via the service selection mechanism instead.
+ * Service variants (non-canonical keys in service groups) are filtered out from this listing - they are accessed via the service selection mechanism instead.
  *
  * Override entries produce a new resolved Channel object (via resolveStoredChannel()), which is a different reference from PREDEFINED_CHANNELS[key]. The service
  * system (services.ts) relies on this reference difference to detect user overrides via isUserOverride(). Predefined-only entries preserve the original reference.
@@ -509,7 +1082,7 @@ export function getChannelListing() {
     const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
     const listing = [];
     for (const key of allKeys) {
-        // Skip service variants — they're accessed via service selection, not as separate channels.
+        // Skip service variants - they're accessed via service selection, not as separate channels.
         if (isServiceVariant(key)) {
             continue;
         }
@@ -528,9 +1101,19 @@ export function getChannelListing() {
         }
         // For user entries (including overrides), resolve the stored delta/definition into a full Channel. The resolved object is a new reference, which preserves
         // the isUserOverride() contract in services.ts (reference comparison against PREDEFINED_CHANNELS[key]). Predefined-only entries keep the original reference.
-        const channel = isUser ? resolveStoredChannel(key, loadedUserChannels[key]) : PREDEFINED_CHANNELS[key];
+        const userEntry = loadedUserChannels[key];
+        const predefinedEntry = PREDEFINED_CHANNELS[key];
+        const resolvedBase = isUser && userEntry ? resolveStoredChannel(key, userEntry) : predefinedEntry;
+        if (!resolvedBase) {
+            // Defensive: the entry exists in at least one source per the allKeys construction, so this branch is unreachable.
+            continue;
+        }
+        // Variants are filtered out at the top of this loop via isServiceVariant, so resolvedBase reaching here is structurally canonical-shaped (a CanonicalChannel
+        // from the catalog or a fully-resolved stored entry). Type as ResolvedChannel so the boundary rule in types/channels.ts holds: post-resolution values are
+        // typed ResolvedChannel.
+        const channel = resolvedBase;
         // When a non-default service is selected, resolve the variant so consumers see the correct URL, channelSelector, stationId, and channelNumber. We skip
-        // resolution when the resolved key matches the canonical key — the channel object is already correct and preserving its reference avoids a redundant lookup.
+        // resolution when the resolved key matches the canonical key - the channel object is already correct and preserving its reference avoids a redundant lookup.
         const resolvedKey = resolveServiceKey(key);
         const resolvedChannel = (resolvedKey !== key) ? getResolvedChannel(resolvedKey) : undefined;
         listing.push({
@@ -545,6 +1128,24 @@ export function getChannelListing() {
     listing.sort((a, b) => a.key.localeCompare(b.key));
     return listing;
 }
+/**
+ * Predicate for "visible" channels - entries that are both enabled and available under the current service filter. This is the single source of truth for what
+ * "visible" means across bulk operations, the playlist, and the merged channel map. Every site that filters the listing by visibility routes through this
+ * predicate so the definition lives in exactly one place.
+ * @param entry - The listing entry to test.
+ * @returns True when the channel is enabled and passes the service filter.
+ */
+export function isVisibleChannel(entry) {
+    return entry.enabled && entry.availableByService;
+}
+/**
+ * Returns the subset of getChannelListing() that is enabled and available under the current service filter. Built on top of isVisibleChannel so the visibility
+ * predicate lives in one place.
+ * @returns Listing entries that pass the visibility predicate.
+ */
+export function getVisibleChannels() {
+    return getChannelListing().filter(isVisibleChannel);
+}
 /**
  * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded. Built on
  * top of getChannelListing() to ensure a single merging code path.
@@ -552,13 +1153,122 @@ export function getChannelListing() {
  */
 export function getAllChannels() {
     const result = {};
-    for (const entry of getChannelListing()) {
-        if (entry.enabled && entry.availableByService) {
-            result[entry.key] = entry.channel;
-        }
+    for (const entry of getVisibleChannels()) {
+        result[entry.key] = entry.channel;
     }
     return result;
 }
+/**
+ * Returns a copy of the raw stored user channels map - the unresolved entries as they exist in channels.json. Used by the consistency probe to check
+ * cross-store invariants without applying delta resolution. Callers should not rely on the shape for anything beyond key/canonicalKey inspection.
+ * @returns Shallow copy of the loaded user channels.
+ */
+export function getStoredUserChannels() {
+    return { ...loadedUserChannels };
+}
+/**
+ * Computes the per-field reset value for a customized field. The reset value is what the field would resolve to in the user's effective view if the override
+ * were removed - so it must apply the same effective-view rules consumers see (vocabulary-filtered tags, implicit-true hdhrEnabled). Field-specific dispatch
+ * routes through the existing single-source helpers (getChannelEffectiveTags, getEffectiveHdhrEnabled) so the rules live in exactly one place.
+ *
+ * For canonical-stored fields, the reset value reads from the predefined canonical. For variant-stored fields, it reads from the predefined variant first,
+ * falling back to the predefined canonical when the variant doesn't carry the field (variant-inheritance fallback). Returns undefined when no predefined
+ * source has the field - a reset would clear the input.
+ * @param field - The customized field name.
+ * @param storedIn - Where the override is stored (canonical or variant).
+ * @param predefinedCanonical - The predefined canonical entry (raw catalog read).
+ * @param predefinedVariant - The predefined variant entry, if applicable (raw catalog read).
+ * @returns The effective reset value, or undefined.
+ */
+function computeResetValue(field, storedIn, predefinedCanonical, predefinedVariant) {
+    // Pick the right predefined source for this storage location. Variant-stored fields prefer the predefined variant; fall back to canonical when the variant
+    // doesn't carry the field (e.g., a variant that inherits profile from canonical's URL-based detection).
+    let source;
+    if (storedIn === "canonical") {
+        source = predefinedCanonical;
+    }
+    else if (predefinedVariant && (predefinedVariant[field] !== undefined)) {
+        source = predefinedVariant;
+    }
+    else {
+        source = predefinedCanonical;
+    }
+    if (!source) {
+        return undefined;
+    }
+    // Delegate to the effective-view helpers for fields with view semantics. Channel structurally satisfies ResolvedChannel here (CanonicalChannel and
+    // VariantChannel both assign), so no cast is needed at the boundary.
+    switch (field) {
+        case "tags": {
+            return getChannelEffectiveTags(source);
+        }
+        case "hdhrEnabled": {
+            return getEffectiveHdhrEnabled(source);
+        }
+        default: {
+            return source[field];
+        }
+    }
+}
+/**
+ * Returns the customization provenance for the given canonical channel. The form layer uses this as the single source of truth for which fields are
+ * customized (instead of comparing resolved values to predefined values, which produces false positives when a non-canonical service is active and the
+ * resolved value legitimately differs from the canonical's predefined value).
+ *
+ * Resolution: for each field present in the user's canonical-stored entry, mark customized with storedIn="canonical" and resetValue from computeResetValue.
+ * For each field present in the active variant's stored entry, mark customized with storedIn="variant" and resetValue from computeResetValue (which handles
+ * variant-inheritance fallback). Variant entries override canonical entries on the same field name because variant resolution overlays the variant's value
+ * last.
+ *
+ * Pass 2 (variant-stored fields) restricts the walked field set via getAllowedFieldsForShape so identity fields encountered on a variant entry are silently
+ * dropped from the customization map, matching the resolver's behavior. The "canonicalKey" field is similarly excluded from both passes - structural metadata,
+ * not user-customizable.
+ * @param canonicalKey - The canonical channel key.
+ * @returns The customization provenance map and the active variant key (when applicable).
+ */
+export function getChannelCustomizations(canonicalKey) {
+    const customizations = new Map();
+    const predefinedCanonical = PREDEFINED_CHANNELS[canonicalKey];
+    // Determine the active variant via the service resolver. resolveServiceKey returns the canonical key itself when the canonical service is selected (no
+    // override is needed) and the variant key otherwise (whether via stored selection or filter fallback).
+    const resolvedKey = resolveServiceKey(canonicalKey);
+    const activeVariantKey = (resolvedKey === canonicalKey) ? undefined : resolvedKey;
+    // Walk a stored entry against its shape's allowed-field set, recording each customized field. The shape rule is computed via getAllowedFieldsForShape so
+    // canonical-stored entries see the full delta surface and variant-stored entries see only the variant binding-only subset (identity-on-variants is dropped).
+    const recordCustomizations = (storedKey, stored, storedIn, predefinedVariant) => {
+        const allowed = getAllowedFieldsForShape(storedKey, stored);
+        for (const [field, value] of Object.entries(stored)) {
+            // canonicalKey is structural metadata, not a customization. Other non-allowed fields (e.g., orphan identity on a variant) are silently ignored here -
+            // the normalizer's filterToDeltaSurface will strip them on next save with a warning.
+            if (!allowed.has(field) || (field === "canonicalKey")) {
+                continue;
+            }
+            if (value === undefined) {
+                continue;
+            }
+            // Cast acknowledges that field is one of the allowed customizable names per the allowlist check above.
+            customizations.set(field, {
+                resetValue: computeResetValue(field, storedIn, predefinedCanonical, predefinedVariant),
+                storedIn
+            });
+        }
+    };
+    // Pass 1: canonical-stored customizations. The canonical entry's allowed shape is the full delta surface (identity + binding delta-eligible).
+    const canonicalStored = loadedUserChannels[canonicalKey];
+    if (canonicalStored) {
+        recordCustomizations(canonicalKey, canonicalStored, "canonical", undefined);
+    }
+    // Pass 2: variant-stored customizations. The variant entry's allowed shape is binding-only. Variant entries override canonical entries on the same field
+    // name (last-overlay-wins matches resolution semantics).
+    if (activeVariantKey) {
+        const variantStored = loadedUserChannels[activeVariantKey];
+        if (variantStored) {
+            const predefinedVariant = PREDEFINED_CHANNELS[activeVariantKey];
+            recordCustomizations(activeVariantKey, variantStored, "variant", predefinedVariant);
+        }
+    }
+    return { activeVariantKey, customizations };
+}
 /**
  * Returns the raw stored channel data (without predefined channels). Entries may be full Channel definitions or ChannelDelta overrides.
  * @returns The stored channel map.
@@ -575,11 +1285,17 @@ export function getTagRegistry() {
     return { deletedTags: [...loadedTagRegistry.deletedTags], tags: [...loadedTagRegistry.tags] };
 }
 /**
- * Updates the tag registry state in memory. Call saveTagRegistry() after to persist the change.
+ * Persists a new tag registry state. Goes through mutateChannels so the file write, integrity validation, and post-mutate cache hydration all run uniformly -
+ * after the call returns, both disk and module-state cache reflect the new value. The caller's input arrays are not mutated; both are sorted non-destructively
+ * via sortTags so storage shares one canonical ordering.
  * @param registry - The new tag registry state.
+ * @throws FileStoreParseError if channels.json contains invalid JSON and the .bak rotation is also unparseable.
  */
-export function setTagRegistry(registry) {
-    loadedTagRegistry = { deletedTags: registry.deletedTags.sort(), tags: registry.tags.sort() };
+export async function setTagRegistry(registry) {
+    const sorted = { deletedTags: sortTags(registry.deletedTags), tags: sortTags(registry.tags) };
+    await mutateChannels((data) => {
+        data.tagRegistry = sorted;
+    });
 }
 /**
  * Returns the active tag vocabulary: predefined tags minus user-deleted tags, plus user-created tags, sorted alphabetically. This is the single source of truth
@@ -601,10 +1317,11 @@ export function getActiveTagVocabulary() {
     return [...seen.values()].toSorted((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
 }
 /**
- * Returns a channel's effective tags — the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
- * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses.
+ * Returns a channel's effective tags - the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
+ * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses. Output preserves the source
+ * order of channel.tags; every write path (sortTags) keeps that source order canonical, so in practice the returned array is sorted.
  * @param channel - The channel to get effective tags for.
- * @returns Sorted array of effective tag strings, or empty array if the channel has no tags or none are in the active vocabulary.
+ * @returns Effective tag strings in source order, or empty array if the channel has no tags or none are in the active vocabulary.
  */
 export function getChannelEffectiveTags(channel) {
     if (!channel.tags || (channel.tags.length === 0)) {
@@ -613,9 +1330,20 @@ export function getChannelEffectiveTags(channel) {
     const vocabulary = getActiveTagVocabulary();
     return channel.tags.filter((tag) => vocabulary.some((v) => tagsMatch(v, tag)));
 }
+/**
+ * Returns whether a channel is effectively included in the HDHomeRun lineup. Codifies the sparse-storage convention that absent or true means included, and only
+ * an explicit `false` means excluded. This is the single source of truth for the convention - every site that needs to ask "is HDHR enabled for this channel?"
+ * routes through this helper rather than reaching for the inline `channel.hdhrEnabled !== false` pattern. Storage-shape inspections that ask a different
+ * question ("did the client send literal false?", "did the user override?") stay inline because they are not asking about effective state.
+ * @param channel - The channel to evaluate.
+ * @returns True when the channel is effectively included in the HDHR lineup.
+ */
+export function getEffectiveHdhrEnabled(channel) {
+    return channel.hdhrEnabled !== false;
+}
 /**
  * Case-insensitive tag comparison. Tags are freeform strings with preserved casing, but all matching throughout the system is case-insensitive. This function
- * is the single source of truth for that policy — all tag identity checks should use it rather than inline toLowerCase() calls.
+ * is the single source of truth for that policy - all tag identity checks should use it rather than inline toLowerCase() calls.
  * @param a - The first tag.
  * @param b - The second tag.
  * @returns True if the tags match case-insensitively.
@@ -624,10 +1352,20 @@ export function tagsMatch(a, b) {
     return a.toLowerCase() === b.toLowerCase();
 }
 /**
- * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations — delete, rename, and bulk
+ * Checks whether a tag is present in the active vocabulary under case-insensitive identity. This is the single source of truth for "does this tag exist?"
+ * questions - tag endpoints (create/rename collision, bulk-tags vocabulary check) route through this instead of ad-hoc Set+toLowerCase comparisons so the
+ * case-insensitive policy lives in exactly one place (tagsMatch), not in parallel implementations.
+ * @param tag - The tag to check.
+ * @returns True if the active vocabulary contains a tag matching case-insensitively.
+ */
+export function isInVocabulary(tag) {
+    return getActiveTagVocabulary().some((v) => tagsMatch(v, tag));
+}
+/**
+ * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations - delete, rename, and bulk
  * toggle all route through this function. The caller provides a filter (which channels to transform) and a transform (how to modify each channel's tags). This
  * function handles loading stored channel data, applying the transform, and saving. Delta normalization in mutateChannels() handles predefined channel
- * delta computation automatically — callers do not need to reason about deltas vs. full definitions.
+ * delta computation automatically - callers do not need to reason about deltas vs. full definitions.
  * @param filter - Predicate selecting which listing entries to transform. Receives each ChannelListingEntry from getChannelListing().
  * @param transform - Pure function mapping a channel's current resolved tags to its new tags. Receives the channel's current tags array (may be empty, ordering
  *   not guaranteed). Must return the desired tags array (may be empty to clear all tags). The returned array is sorted before storage.
@@ -636,22 +1374,24 @@ export function tagsMatch(a, b) {
 export async function transformChannelTags(filter, transform) {
     const affectedKeys = [];
     try {
-        await mutateChannels((channels) => {
+        await mutateChannels((data) => {
             for (const entry of getChannelListing()) {
                 if (!filter(entry)) {
                     continue;
                 }
                 const currentTags = entry.channel.tags ?? [];
-                const newTags = transform(currentTags).sort();
-                // Skip channels where the transform produced no change.
-                if (JSON.stringify(newTags) === JSON.stringify(currentTags.toSorted())) {
+                // Route both the transform result and the "no change" comparison through sortTags so tag storage shares one canonical ordering with the rest of the
+                // system. sortTags is non-mutating, which matters here because for predefined-only listing entries, entry.channel is the PREDEFINED_CHANNELS reference
+                // directly - a raw .sort() on entry.channel.tags would rearrange the predefined array in process memory.
+                const newTags = sortTags(transform(currentTags));
+                if (isDeepStrictEqual(newTags, sortTags(currentTags))) {
                     continue;
                 }
                 // Set the new tags on the stored entry. Callers use null uniformly for "clear/empty" - the normalizer in mutateChannels() handles the storage
                 // conventions: delta normalization for predefined channels (comparing against raw definitions), null-stripping for user channels.
-                const existing = channels[entry.key] ?? {};
-                existing.tags = (newTags.length > 0) ? newTags : null;
-                channels[entry.key] = existing;
+                const existing = data.channels[entry.key] ?? {};
+                existing["tags"] = (newTags.length > 0) ? newTags : null;
+                data.channels[entry.key] = existing;
                 affectedKeys.push(entry.key);
             }
         });
@@ -664,13 +1404,48 @@ export async function transformChannelTags(filter, transform) {
     }
     return { affectedKeys };
 }
+/* Dangling-canonical warning dedup for getPredefinedChannel. The catalog flattener should make a missing canonical structurally impossible, so observing one
+ * indicates real data corruption that an operator needs to know about. We log once per variant key for the lifetime of this process - a tight loop calling
+ * getPredefinedChannel on the corrupt entry would otherwise spam the log on every form render.
+ */
+const warnedMissingCanonicalForPredefined = new Set();
 /**
- * Returns the predefined channel definition for a key.
+ * Returns the predefined channel definition for a key as a fully-resolved view. For predefined variant entries (which carry only service-specific fields plus
+ * canonicalKey), overlays the variant's binding onto its predefined canonical so callers receive the resolved view - canonical identity inherited onto the
+ * variant. This matches what the user sees in the form/table and is the correct base for delta-from-predefined computations in crud.ts and channelForm.ts.
+ *
+ * Always returns ResolvedChannel-shaped data: identity fields (name, tags, hdhrEnabled, etc.) are always available, sourced from the canonical when this key is
+ * a variant. CanonicalChannel and VariantChannel both assign structurally to ResolvedChannel since the identity fields are optional in both types.
+ *
+ * Returns undefined when the key is not predefined OR when the catalog is internally inconsistent (variant references a missing canonical). The latter case is
+ * structurally impossible by construction of the flattener, so observing it is a real corruption indicator: the function logs once per offending key and
+ * returns undefined rather than fabricating a half-resolved view that would lie about its identity fields.
  * @param key - The channel key to look up.
- * @returns The predefined channel, or undefined if the key is not predefined.
+ * @returns The resolved predefined channel, or undefined if the key is not predefined or the catalog is inconsistent.
  */
 export function getPredefinedChannel(key) {
-    return PREDEFINED_CHANNELS[key];
+    const entry = PREDEFINED_CHANNELS[key];
+    if (!entry) {
+        return undefined;
+    }
+    // Canonical entries have full identity already; return as-is. CanonicalChannel assigns to ResolvedChannel structurally (canonicalKey: never is assignable to
+    // canonicalKey?: string).
+    if (!entry.canonicalKey || (entry.canonicalKey === key)) {
+        return entry;
+    }
+    // Predefined variant: overlay its binding fields onto the canonical so callers see the resolved view with canonical identity. Variant overlays apply
+    // binding fields only per the architectural principle - matches resolveVariant's behavior so callers get the same view regardless of which path produced it.
+    const canonical = PREDEFINED_CHANNELS[entry.canonicalKey];
+    if (!canonical) {
+        // Catalog inconsistency. Log once per offending key, then return undefined. Returning a half-resolved view (the variant typed as ResolvedChannel) would
+        // lie about which identity fields are reachable and silently hide the corruption from consumers.
+        if (!warnedMissingCanonicalForPredefined.has(key)) {
+            warnedMissingCanonicalForPredefined.add(key);
+            LOG.warn("Catalog inconsistency: predefined variant '%s' references missing canonical '%s'. Returning undefined; the flattener should make this impossible.", key, entry.canonicalKey);
+        }
+        return undefined;
+    }
+    return overlayVariantBinding(canonical, entry);
 }
 /**
  * Checks if a channel key exists in the predefined channels.
@@ -733,11 +1508,17 @@ export function getChannelStationId(channelKey) {
     // Pacific channels are regional feeds of the same brand as their east counterparts, so we resolve to the east variant's station ID for logo purposes.
     const effectiveKey = getEastCanonicalKey(channelKey) ?? channelKey;
     // User channels take precedence - resolveStoredChannel merges deltas with the predefined base, so overrides that change the stationId are reflected here.
-    return (effectiveKey in loadedUserChannels) ?
-        resolveStoredChannel(effectiveKey, loadedUserChannels[effectiveKey]).stationId :
-        // Runtime check needed - TypeScript thinks Record indexing always returns a value, but the key may not exist.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        PREDEFINED_CHANNELS[effectiveKey]?.stationId;
+    const userEntry = loadedUserChannels[effectiveKey];
+    if (userEntry) {
+        return resolveStoredChannel(effectiveKey, userEntry).stationId;
+    }
+    // PREDEFINED_CHANNELS is a discriminated union; only canonicals carry stationId. The lookup here is by canonical-equivalent key (Pacific resolved to East),
+    // so a hit is structurally a canonical. Narrow via the canonicalKey discriminator: a defined canonicalKey marks a VariantChannel, which has no stationId.
+    const predefined = PREDEFINED_CHANNELS[effectiveKey];
+    if (!predefined || (predefined.canonicalKey !== undefined)) {
+        return undefined;
+    }
+    return predefined.stationId;
 }
 /**
  * Returns the logo URL for a channel from the cache. Pacific channels (e.g., "bravop") are resolved to their east counterpart automatically. The cache is
@@ -764,7 +1545,7 @@ export function isUserChannel(key) {
  * re-enable. This is useful for users who don't want certain predefined channels cluttering their channel list.
  */
 /**
- * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config — the user's explicit visibility
+ * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config - the user's explicit visibility
  * intent. Property overrides (HDHR toggle, name change, tag edits) stored as deltas in channels.json are orthogonal and do not affect the enabled/disabled state.
  * @param key - The channel key to check.
  * @returns True if the channel is predefined and disabled.
@@ -782,6 +1563,84 @@ export function isPredefinedChannelDisabled(key) {
 export function getDisabledPredefinedChannels() {
     return [...CONFIG.channels.disabledPredefined];
 }
+/**
+ * Applies a set operation (add or delete) to the disabledPredefined list in user config. Persists the change to config.json and syncs the runtime CONFIG object
+ * so subsequent reads see the updated state immediately. This is the internal implementation shared by disablePredefinedChannels and enablePredefinedChannels so
+ * the mutateConfig scaffolding, sort, and CONFIG sync live in exactly one place.
+ * @param op - "add" to insert keys into the disabled list, "delete" to remove them.
+ * @param keys - The predefined channel keys to apply the operation to.
+ */
+async function mutateDisabledPredefined(op, keys) {
+    if (keys.length === 0) {
+        return;
+    }
+    let updatedList = [];
+    await mutateConfig((config) => {
+        config.channels ??= {};
+        config.channels.disabledPredefined ??= [];
+        const disabledSet = new Set(config.channels.disabledPredefined);
+        for (const key of keys) {
+            disabledSet[op](key);
+        }
+        config.channels.disabledPredefined = [...disabledSet].toSorted();
+        updatedList = config.channels.disabledPredefined;
+    });
+    CONFIG.channels.disabledPredefined = updatedList;
+}
+/**
+ * Disables one or more predefined channels by adding their keys to the disabledPredefined list in user config. Idempotent.
+ * @param keys - The predefined channel keys to disable. Duplicates within the input array and pre-existing disabled entries are handled idempotently.
+ */
+export async function disablePredefinedChannels(keys) {
+    await mutateDisabledPredefined("add", keys);
+}
+/**
+ * Enables one or more predefined channels by removing their keys from the disabledPredefined list in user config. Idempotent.
+ * @param keys - The predefined channel keys to enable. Entries that aren't in the disabled list are ignored.
+ */
+export async function enablePredefinedChannels(keys) {
+    await mutateDisabledPredefined("delete", keys);
+}
+/**
+ * Persists a partial update of channel-table display preferences (sort field, sort direction, visible columns) to config.json. Only fields present in `prefs`
+ * are written; absent fields are left untouched. The mutate fn copies the new values into data and the runtime CONFIG cache is updated post-write to match.
+ * Single-call replacement for the prior set-then-save pattern, consistent with mutateServiceSelections, mutateEnabledServices, and setTagRegistry.
+ * @param prefs - Subset of display preferences to update.
+ * @throws FileStoreParseError if config.json contains invalid JSON and the .bak rotation is also unparseable.
+ */
+export async function mutateChannelDisplayPrefs(prefs) {
+    const next = {
+        channelSortDirection: prefs.channelSortDirection ?? CONFIG.channels.channelSortDirection,
+        channelSortField: prefs.channelSortField ?? CONFIG.channels.channelSortField,
+        visibleColumns: prefs.visibleColumns ? [...prefs.visibleColumns] : [...CONFIG.channels.visibleColumns]
+    };
+    await mutateConfig((config) => {
+        config.channels ??= {};
+        config.channels.channelSortDirection = next.channelSortDirection;
+        config.channels.channelSortField = next.channelSortField;
+        config.channels.visibleColumns = next.visibleColumns;
+    });
+    // Hydrate the runtime CONFIG cache from the values just written.
+    CONFIG.channels.channelSortDirection = next.channelSortDirection;
+    CONFIG.channels.channelSortField = next.channelSortField;
+    CONFIG.channels.visibleColumns = next.visibleColumns;
+}
+/**
+ * Marks the first-run Service Setup wizard as completed. Writes the flag to runtime CONFIG and persists to config.json in one call - the operation is a single
+ * one-way transition (setupCompleted goes from false/absent to true once, never back), so splitting into set+save would be ceremony without benefit.
+ *
+ * Persistence note: setupCompleted is intentionally absent from CONFIG_METADATA and PRESERVED_FIELDS in userConfig.ts, so filterDefaults strips it from the
+ * on-disk shape during the write below. This is by design - the flag is observably derived from "has the user configured any services or channels" and
+ * initializeUserChannels() re-infers it at startup from that observable state. The mutateConfig call here is a no-op on the file but keeps the runtime
+ * mutation pathway uniform with every other CONFIG.channels writer; the flag survives across restarts via inference, not persistence.
+ */
+export async function markSetupCompleted() {
+    CONFIG.channels.setupCompleted = true;
+    await mutateConfig((config) => {
+        config.channels ??= {};
+        config.channels.setupCompleted = true;
+    });
+}
 /**
  * Returns all predefined channels regardless of disabled state, excluding service variants. Used by the UI to show all predefined channels including disabled ones.
  * Service variants are internal implementation details of channel delivery and are not channels themselves.
@@ -803,14 +1662,14 @@ export function getPredefinedChannels() {
 /**
  * Filters predefined channel keys by their relationship to the Pacific timezone naming convention. For "pacific" mode, returns keys that end in "p" and
  * whose East counterpart (key minus trailing "p") exists. For "east" mode, returns keys that do NOT end in "p" and whose Pacific counterpart (key plus "p")
- * exists. Service variants are excluded — only canonical keys are returned.
+ * exists. Service variants are excluded - only canonical keys are returned.
  * @param side - Which side of the East/Pacific pair to select.
  * @returns Sorted array of matching canonical predefined channel keys.
  */
 function filterPredefinedKeysByTimezone(side) {
     const keys = [];
     for (const key of Object.keys(PREDEFINED_CHANNELS)) {
-        // Skip service variants — they are internal implementation details, not channels.
+        // Skip service variants - they are internal implementation details, not channels.
         if (isServiceVariant(key)) {
             continue;
         }
@@ -1004,29 +1863,29 @@ export function validateImportedChannels(data, validProfiles) {
         }
         const channelData = value;
         // Validate required name field. Sanitize after type check to strip non-printable characters from imported data.
-        if ((typeof channelData.name !== "string") || (channelData.name.trim() === "")) {
+        if ((typeof channelData["name"] !== "string") || (channelData["name"].trim() === "")) {
             errors.push("Channel '" + key + "': name is required.");
             continue;
         }
-        const cleanName = sanitizeString(channelData.name);
+        const cleanName = sanitizeString(channelData["name"]);
         const nameError = validateChannelName(cleanName);
         if (nameError) {
             errors.push("Channel '" + key + "': " + nameError);
             continue;
         }
         // Validate required url field. Sanitize after type check.
-        if ((typeof channelData.url !== "string") || (channelData.url.trim() === "")) {
+        if ((typeof channelData["url"] !== "string") || (channelData["url"].trim() === "")) {
             errors.push("Channel '" + key + "': url is required.");
             continue;
         }
-        const cleanUrl = sanitizeString(channelData.url);
+        const cleanUrl = sanitizeString(channelData["url"]);
         const urlError = validateChannelUrl(cleanUrl);
         if (urlError) {
             errors.push("Channel '" + key + "': " + urlError);
             continue;
         }
         // Validate optional profile field. Sanitize after type check.
-        const profile = (typeof channelData.profile === "string") ? sanitizeString(channelData.profile) : undefined;
+        const profile = (typeof channelData["profile"] === "string") ? sanitizeString(channelData["profile"]) : undefined;
         const profileError = validateChannelProfile(profile, validProfiles);
         if (profileError) {
             errors.push("Channel '" + key + "': " + profileError);
@@ -1041,15 +1900,15 @@ export function validateImportedChannels(data, validProfiles) {
             channel.profile = profile;
         }
         // Include optional fields if present. Sanitize string values to strip non-printable characters.
-        if (typeof channelData.stationId === "string") {
-            channel.stationId = sanitizeString(channelData.stationId);
+        if (typeof channelData["stationId"] === "string") {
+            channel.stationId = sanitizeString(channelData["stationId"]);
         }
-        if (typeof channelData.channelSelector === "string") {
-            channel.channelSelector = sanitizeString(channelData.channelSelector);
+        if (typeof channelData["channelSelector"] === "string") {
+            channel.channelSelector = sanitizeString(channelData["channelSelector"]);
         }
         // Validate optional channelNumber field (range and type).
-        if (channelData.channelNumber !== undefined) {
-            const num = Number(channelData.channelNumber);
+        if (channelData["channelNumber"] !== undefined) {
+            const num = Number(channelData["channelNumber"]);
             if (!Number.isInteger(num) || (num < 1) || (num > 99999)) {
                 errors.push("Channel '" + key + "': channelNumber must be an integer between 1 and 99999.");
                 continue;
@@ -1057,8 +1916,8 @@ export function validateImportedChannels(data, validProfiles) {
             channel.channelNumber = num;
         }
         // Validate optional tvgShift field (must be a finite number). Negative values are valid (e.g., a West Coast feed viewed from the East).
-        if (channelData.tvgShift !== undefined) {
-            const shift = Number(channelData.tvgShift);
+        if (channelData["tvgShift"] !== undefined) {
+            const shift = Number(channelData["tvgShift"]);
             if (!Number.isFinite(shift)) {
                 errors.push("Channel '" + key + "': tvgShift must be a finite number.");
                 continue;
@@ -1067,10 +1926,12 @@ export function validateImportedChannels(data, validProfiles) {
         }
         channels[key] = channel;
     }
-    // Validate channelNumber uniqueness across all imported channels. We check after building the full map so that all duplicates are reported.
+    // Validate channelNumber uniqueness across all imported channels. We check after building the full map so that all duplicates are reported. channelNumber
+    // is identity (canonical-only by architectural principle); the validator above only constructs canonical-shaped entries, but the StoredChannelMap is typed
+    // as the union, so we narrow with an in-check before reading.
     const numberToKey = new Map();
     for (const [key, channel] of Object.entries(channels)) {
-        if (channel.channelNumber === undefined) {
+        if (!("channelNumber" in channel) || (channel.channelNumber === undefined)) {
             continue;
         }
         const existing = numberToKey.get(channel.channelNumber);
@@ -1083,25 +1944,53 @@ export function validateImportedChannels(data, validProfiles) {
     }
     return { channels, errors, valid: errors.length === 0 };
 }
-/* Service selections are stored in the channels.json file alongside user channels. When a selection changes, we save the entire file (channels + selections)
- * to persist the change.
- */
 /**
- * Saves the current service selections to the channels file. The no-op mutation triggers a write that picks up current serviceSelections from module state via the
- * beforeWrite hook.
- * @throws If the file cannot be written.
+ * Sorts tags case-insensitively using locale-aware comparison. This is the single source of truth for tag ordering. Every write path (parseTagInput, PATCH
+ * handlers, computePredefinedDelta, transformChannelTags, setTagRegistry) routes through this so stored tag arrays share one canonical ordering. The channels
+ * normalizer is a READER of that invariant - it uses sortTags on both sides when comparing a delta's tags against a predefined's tags, making the JSON.stringify
+ * equality check canonical regardless of how either side was originally populated.
+ * @param tags - Any iterable of tag strings (array, Set, generator). Not mutated.
+ * @returns A new array with the same elements in canonical case-insensitive order.
  */
-export async function saveServiceSelections() {
-    // No-op mutation: the beforeWrite hook injects current serviceSelections from module state.
-    await mutateChannels(() => { });
+export function sortTags(tags) {
+    return Array.from(tags).toSorted((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
 }
 /**
- * Saves the current tag registry to the channels file. The no-op mutation triggers a write that picks up the current tag registry from module state via the
- * beforeWrite hook.
- * @throws If the file cannot be written.
+ * Parses a comma-separated tag input string into a normalized tag array. Trims whitespace, drops empty entries, deduplicates case-sensitively via Set (so
+ * distinct casings survive as distinct tags), then sorts via sortTags so every caller produces identical normalized arrays.
+ * @param raw - The comma-separated tag input from a form field or inline editor. An empty or whitespace-only string returns an empty array.
+ * @returns Sorted, case-sensitively-deduplicated array of trimmed tag strings.
  */
-export async function saveTagRegistry() {
-    // No-op mutation: the beforeWrite hook injects the current tag registry from module state.
-    await mutateChannels(() => { });
+export function parseTagInput(raw) {
+    if (!raw) {
+        return [];
+    }
+    return sortTags(new Set(raw.split(",").map((t) => t.trim()).filter((t) => t.length > 0)));
 }
+/* Test-only export barrel. The helpers below are intentionally file-private for production code - the resolver, normalizer, and migration classifier are
+ * internal building blocks, and exposing them as public API would invite misuse from routes and streaming code that should be going through the higher-level
+ * functions above. Unit tests need direct access to exercise each building block in isolation, so they reach in through this named export. Production code
+ * must not import from this barrel; its shape is not stable and its presence in the module carries no API guarantee.
+ */
+export const __internalForTests = {
+    applyOverlayKernel,
+    buildResolvedCanonicals,
+    channelsMigrations,
+    classifyEntry,
+    collectLegacyVariantStamps,
+    detectIdentityFieldLoss,
+    filterToDeltaSurface,
+    getAllowedFieldsForShape,
+    getMergedChannelMap,
+    normalizeChannelDeltas,
+    normalizeEntryAgainstBase,
+    overlayDelta,
+    overlayVariantBinding,
+    parseChannelsFile,
+    prepareChannelsForWrite,
+    resolveVariant,
+    stripNulls,
+    validateChannelsIntegrity,
+    warnDanglingCanonical
+};
 //# sourceMappingURL=userChannels.js.map