prismcast 1.10.2 → 1.11.0

package/dist/config/userChannels.js

@@ -4,7 +4,7 @@
  */
 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 { LOG, containsNonPrintable, extractDomain, sanitizeString } from "../utils/index.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";
@@ -46,8 +46,9 @@ 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.
+ * function extracts the channel data and its metadata fields 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 (prepareChannelsForWrite) derives every field of the
+ * on-disk shape from the mutation's data envelope itself, never 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.
@@ -58,7 +59,7 @@ export function getChannelsParseErrorMessage() {
  *       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
+ *       "fox-site" -> "fox-foxone" rename for the FoxOne variant stored under the "fox-site" key. 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;
@@ -79,7 +80,7 @@ function parseChannelsFile(raw) {
     let schemaVersion = 1;
     for (const [key, value] of Object.entries(parsed)) {
         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.
+            // Tolerate bad data by falling back to version 1 - any plausibly-legacy value is fine, since migrations are a no-op when no work is needed.
             if ((typeof value === "number") && Number.isFinite(value) && (value >= 1)) {
                 schemaVersion = Math.floor(value);
             }
@@ -136,18 +137,18 @@ function parseChannelsFile(raw) {
     }
     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.
+/* Array-valued ChannelDelta fields whose equality requires canonical case-insensitive ordering before structural comparison via isDeepStrictEqual. The set
+ * declares which array fields have unordered-set semantics rather than order-significant lists; equality for these fields runs both sides through sortTags 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 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.
+ * that has no such field, and values that match the base exactly. Array-valued fields use isDeepStrictEqual for structural equality, with sortTags applied to
+ * both sides 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.
@@ -183,8 +184,8 @@ function normalizeEntryAgainstBase(stored, base) {
             }
             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.
+        // Values that match the base exactly are redundant. Arrays compare structurally via isDeepStrictEqual; fields in CANONICAL_SORTED_ARRAY_FIELDS are routed
+        // through sortTags 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);
@@ -237,8 +238,8 @@ function classifyEntry(key, stored) {
  * 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.
+ *  - Variant-shaped (kind = variant): allowed fields are DELTA_ELIGIBLE_BINDING_KEYS plus the structural canonicalKey field that marks the kind. 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?".
@@ -297,7 +298,7 @@ function filterToDeltaSurface(key, stored) {
 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.
+    // present - which is the documented guarantee 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.
@@ -350,7 +351,7 @@ function warnDanglingCanonical(variantKey, canonicalKey) {
  */
 function buildResolvedCanonicals(stored) {
     const result = {};
-    const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(stored)]);
+    const allKeys = new Set(Object.keys(PREDEFINED_CHANNELS)).union(new Set(Object.keys(stored)));
     for (const key of allKeys) {
         const classification = classifyEntry(key, stored[key]);
         if (classification.kind === "variant") {
@@ -378,26 +379,216 @@ function buildResolvedCanonicals(stored) {
 function stripNulls(stored) {
     return Object.fromEntries(Object.entries(stored).filter(([, v]) => v !== null));
 }
+/* Module-private partition Sets, derived once from the type-system source of truth. The Sets back the public picker functions below; callers never reference
+ * the Sets directly. Adding or renaming a field in CHANNEL_IDENTITY_KEYS / CHANNEL_BINDING_KEYS automatically updates both Sets at runtime - the partition
+ * lives in types/channels.ts and these are the single derived runtime form.
+ */
+const IDENTITY_FIELDS = new Set(CHANNEL_IDENTITY_KEYS);
+const BINDING_FIELDS = new Set(CHANNEL_BINDING_KEYS);
+/**
+ * Internal: filters a delta to fields in the supplied allowlist. Backs pickIdentityFields and pickBindingFields. Not exported - the public surface is the
+ * named pickers, which hide the partition Sets so consumers never have to know how the partition is enumerated.
+ */
+function filterDeltaFields(delta, allowlist) {
+    const filtered = {};
+    for (const [field, value] of Object.entries(delta)) {
+        if (allowlist.has(field)) {
+            filtered[field] = value;
+        }
+    }
+    return filtered;
+}
+/**
+ * Returns the identity-only subset of a ChannelDelta - the fields enumerated by CHANNEL_IDENTITY_KEYS. Used by the per-field write router (PUT handler) and
+ * the storage normalizer's heal path to split a full delta into identity-only and binding-only halves so each half is routed to the correct stored entry.
+ * @param delta - The delta to project.
+ * @returns A new delta with only identity fields retained.
+ */
+export function pickIdentityFields(delta) {
+    return filterDeltaFields(delta, IDENTITY_FIELDS);
+}
+/**
+ * Returns the binding-only subset of a ChannelDelta - the fields enumerated by CHANNEL_BINDING_KEYS. Peer to pickIdentityFields; together they cover the
+ * delta surface and partition it cleanly.
+ * @param delta - The delta to project.
+ * @returns A new delta with only binding fields retained.
+ */
+export function pickBindingFields(delta) {
+    return filterDeltaFields(delta, BINDING_FIELDS);
+}
+/**
+ * Applies a binding delta to an existing variant entry with replace semantics: any prior binding fields on the existing entry are stripped first, then the
+ * new delta's binding fields are applied. Non-binding fields (notably canonicalKey) on the existing entry are preserved. Returns null when the resulting
+ * entry would be empty.
+ *
+ * Used by the producer (handlePredefinedEdit) when the user submits a form with explicit values - the form values are the authoritative declaration of the
+ * variant's binding state, so any pre-existing binding override on the variant entry is wiped.
+ *
+ * Pair with mergeVariantBinding (preserve-existing semantics) below. The two functions name the precedence rule explicitly so future callers pick the right
+ * semantic for their context.
+ * @param existing - The existing variant entry, if any.
+ * @param delta - The new binding-only delta. The producer is asserting these are the authoritative values.
+ * @returns The merged stored entry, or null when the result would be empty.
+ */
+export function replaceVariantBinding(existing, delta) {
+    const next = { ...existing };
+    // Strip prior binding-field overrides; the new delta is authoritative for this category.
+    for (const field of CHANNEL_BINDING_KEYS) {
+        Reflect.deleteProperty(next, field);
+    }
+    // Apply the new binding-field overrides.
+    Object.assign(next, delta);
+    return (Object.keys(next).length > 0) ? next : null;
+}
+/**
+ * Merges a binding delta into an existing variant entry with preserve-existing semantics: existing variant fields win on conflicts; the delta only fills
+ * fields the variant doesn't already declare. Always returns a non-empty entry (caller is expected to invoke this only when delta has something to contribute).
+ *
+ * Used by the storage normalizer's canonical-binding overlap heal. The heal context is healing legacy data, not recording a new explicit user intent - the
+ * variant's prior customization is more recent or at least equally legitimate as the canonical-side stored binding being moved over, so the variant wins.
+ *
+ * Pair with replaceVariantBinding (replace semantics) above. The two functions name the precedence rule explicitly.
+ * @param existing - The existing variant entry, if any. Existing fields take precedence on conflicts.
+ * @param delta - The binding-only delta whose fields fill any gaps the existing entry doesn't declare.
+ * @returns The merged stored entry. Always non-empty (delta contributes at least the keys the existing didn't have).
+ */
+export function mergeVariantBinding(existing, delta) {
+    const merged = { ...delta };
+    if (existing) {
+        Object.assign(merged, existing);
+    }
+    return merged;
+}
+/**
+ * Intersects a binding delta with a criterion delta by key, returning a new binding-only delta containing fields that appear in BOTH and using values from
+ * the primary delta. Used by the URL-inferred branch of the per-field write router: when a user submits a form with no pre-selected variant but a URL that
+ * implies a sibling, the producer must avoid treating unset form fields as explicit clears against the inferred variant's predefined defaults. Restricting
+ * the variant-relative delta to fields the user actually changed (relative to the canonical) prevents that silent destruction of tuning data.
+ *
+ * Pure function - operates on two deltas independently of any storage state. Generic over the criterion: any binding field present on `criterion` makes
+ * `primary`'s value for that field eligible to land on the result.
+ * @param primary - The delta whose values populate the result.
+ * @param criterion - The delta whose key set restricts which fields propagate.
+ * @returns A new binding-only delta with primary's values for keys present in both, restricted to CHANNEL_BINDING_KEYS.
+ */
+export function intersectBindingDeltas(primary, criterion) {
+    const restricted = {};
+    for (const field of CHANNEL_BINDING_KEYS) {
+        if ((field in criterion) && (field in primary)) {
+            restricted[field] = primary[field];
+        }
+    }
+    return restricted;
+}
+/**
+ * Given a canonical key and a URL, returns the sibling variant key whose effective URL extracts to the same domain. Returns undefined when no sibling matches -
+ * that is the legitimate "Custom URL" case where the user genuinely has a non-predefined URL.
+ *
+ * Used by both the producer (handlePredefinedEdit in routes/config/channels/endpoints/crud.ts) and the storage normalizer (normalizeChannelDeltas) to enforce
+ * the rule that a canonical override's binding fields must not duplicate a sibling variant's domain. When a sibling matches, the user's intent is "default this
+ * channel to the sibling's service" - architecturally expressed via serviceSelections, not via overriding the canonical URL. Both call sites share this single
+ * helper so the inference rule lives in exactly one place.
+ *
+ * Pure function. Walks predefined and user-stored siblings, sorts by key for determinism (multiple variants with the same domain pick the alphabetically-first
+ * one), and returns the first match. Effective URL is the user-stored override (if any string-valued) layered onto the predefined variant URL - same precedence
+ * as resolveVariant.
+ * @param canonicalKey - The canonical channel key whose siblings should be searched.
+ * @param submittedUrl - The URL being matched. Empty/undefined returns undefined.
+ * @param channels - The stored channels map snapshot for finding user-defined sibling variants.
+ * @returns The matching variant key, or undefined when no sibling's URL domain matches.
+ */
+export function inferTargetVariant(canonicalKey, submittedUrl, channels) {
+    if ((submittedUrl === undefined) || (submittedUrl === null) || (submittedUrl === "")) {
+        return undefined;
+    }
+    const userDomain = extractDomain(submittedUrl);
+    // Enumerate sibling variant keys: predefined variants and user-stored variants whose canonicalKey points at this canonical. Excludes the canonical itself.
+    // Dedupe via Set since a key may appear in both maps (user override of a predefined variant).
+    const siblingKeys = new Set();
+    for (const [predefinedKey, predefinedChannel] of Object.entries(PREDEFINED_CHANNELS)) {
+        if ((predefinedKey !== canonicalKey) && (predefinedChannel.canonicalKey === canonicalKey)) {
+            siblingKeys.add(predefinedKey);
+        }
+    }
+    for (const [storedKey, storedChannel] of Object.entries(channels)) {
+        if ((storedKey !== canonicalKey) && (storedChannel.canonicalKey === canonicalKey)) {
+            siblingKeys.add(storedKey);
+        }
+    }
+    // Sort for deterministic pick when multiple siblings share a domain.
+    const sortedKeys = Array.from(siblingKeys).toSorted();
+    for (const siblingKey of sortedKeys) {
+        // Effective URL: user override (when string-valued) takes precedence over the predefined variant's URL. A null delta value clears the field, falling back
+        // to the predefined; an absent field inherits, also falling back. Both collapse to "use the predefined URL."
+        const stored = channels[siblingKey];
+        const predefined = PREDEFINED_CHANNELS[siblingKey];
+        const storedUrl = stored ? stored.url : undefined;
+        const effectiveUrl = (typeof storedUrl === "string") ? storedUrl : predefined?.url;
+        if (!effectiveUrl) {
+            continue;
+        }
+        if (extractDomain(effectiveUrl) === userDomain) {
+            return siblingKey;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detects whether any canonical override in the stored map carries binding whose URL extracts to a sibling variant's domain. Used by initializeUserChannels to
+ * conditionally trigger a one-shot startup heal pass via mutateChannels - the normalizer does the actual work, this probe just decides whether the trigger is
+ * needed so unaffected users incur no boot-time write.
+ *
+ * Cheap walk: classify, check stored URL, call inferTargetVariant. Returns on the first match - we only need to know whether at least one entry needs healing.
+ * @param channels - The stored channels map snapshot to probe.
+ * @returns True when at least one canonical override would be redirected by the normalizer.
+ */
+function hasCanonicalBindingOverlap(channels) {
+    for (const [key, stored] of Object.entries(channels)) {
+        const classification = classifyEntry(key, stored);
+        if (classification.kind !== "canonical") {
+            continue;
+        }
+        const url = stored.url;
+        if (typeof url !== "string") {
+            continue;
+        }
+        if (inferTargetVariant(key, url, channels)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * 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.
+ * stripped. Standalone user channels have no base, so nulls are stripped but everything else is preserved. Mutates the data in place so the caller's reference
+ * (the file store framework's data envelope) reflects normalized state on return - matching the migration `apply` convention so the same shape is used wherever
+ * the framework runs writes.
  *
  * The flow is uniform across kinds:
  *
- * - Canonical (predefined with user override): base is the predefined channel.
+ * - Canonical (predefined with user override): base is the predefined channel. Before delta minimization, any binding fields whose URL extracts to a sibling
+ *   variant's domain are healed by routing them to the matching variant entry and recording a serviceSelections redirect - the same per-field routing the
+ *   producer (handlePredefinedEdit) performs at write time. This makes the rule "canonical overrides only carry canonical-service binding" structurally
+ *   self-healing for any data path that misses the producer (legacy data, hand-edited files, future producers).
  * - 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)) {
+ * @param data - The full channels file data envelope. Channels and serviceSelections are both mutated in place.
+ */
+function normalizeChannelDeltas(data) {
+    const resolvedCanonicals = buildResolvedCanonicals(data.channels);
+    // Snapshot keys before iteration: the canonical-binding heal may write new variant entries to data.channels (heal-created variants when the matched sibling
+    // had no prior user override), and we don't want to re-process those in this pass. Heal-created entries are written in already-minimal delta shape, so
+    // skipping them is correct.
+    const initialKeys = Object.keys(data.channels);
+    for (const key of initialKeys) {
+        const stored = data.channels[key];
+        if (!stored) {
+            continue;
+        }
         // 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.
@@ -409,24 +600,59 @@ function normalizeChannelDeltas(channels) {
         // Step 2: classification-driven delta minimization against the appropriate base.
         const classification = classifyEntry(key, shapeFiltered);
         if (classification.kind === "canonical") {
+            // Step 2a: canonical-binding overlap heal. When the canonical override carries binding whose URL extracts to a sibling variant's domain, the user's
+            // intent is "default this channel to the sibling's service" - architecturally expressed via serviceSelections, not via overriding the canonical URL.
+            // Strip the binding fields from the canonical, propagate any binding that diverges from the matching variant's predefined defaults to the variant
+            // entry via mergeVariantBinding (preserve-existing semantics: the variant's prior user customization wins on field conflicts), and record the
+            // redirect. Distinct from the producer's replaceVariantBinding semantic - the heal is healing legacy data, not recording a new explicit user intent.
+            const canonicalDelta = shapeFiltered;
+            const targetVariantKey = inferTargetVariant(key, canonicalDelta.url, data.channels);
+            if (targetVariantKey) {
+                const targetPredefinedVariant = PREDEFINED_CHANNELS[targetVariantKey];
+                // For predefined siblings, diff the canonical's binding against the predefined variant's binding so only divergent fields land on the variant entry.
+                // For user-only siblings (no predefined entry), the matched variant already has its own binding from when the user created it; the canonical's
+                // binding simply represents redundant duplication and is dropped without modifying the variant entry.
+                if (targetPredefinedVariant) {
+                    const bindingOnly = pickBindingFields(canonicalDelta);
+                    const variantDelta = normalizeEntryAgainstBase(bindingOnly, targetPredefinedVariant);
+                    if (variantDelta) {
+                        data.channels[targetVariantKey] = mergeVariantBinding(data.channels[targetVariantKey], variantDelta);
+                    }
+                }
+                data.serviceSelections[key] = targetVariantKey;
+                LOG.info("Resolved canonical-binding overlap for '%s'; redirected default service to variant '%s'.", key, targetVariantKey);
+                // Continue normalization with the binding-stripped canonical delta. If only identity remains and matches the predefined canonical, the entry collapses.
+                const identityOnly = pickIdentityFields(canonicalDelta);
+                const normalizedIdentity = normalizeEntryAgainstBase(identityOnly, classification.predefined);
+                if (normalizedIdentity) {
+                    data.channels[key] = normalizedIdentity;
+                }
+                else {
+                    Reflect.deleteProperty(data.channels, key);
+                }
+                continue;
+            }
             const normalized = normalizeEntryAgainstBase(shapeFiltered, classification.predefined);
             if (normalized) {
-                filtered[key] = normalized;
+                data.channels[key] = normalized;
+            }
+            else {
+                Reflect.deleteProperty(data.channels, key);
             }
             continue;
         }
         if (classification.kind === "standalone") {
-            filtered[key] = stripNulls(shapeFiltered);
+            data.channels[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
+        // form/table, so the delta records only what differs from that. 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);
+            data.channels[key] = stripNulls(shapeFiltered);
             continue;
         }
         const identityBase = pickIdentity(canonical);
@@ -435,15 +661,18 @@ function normalizeChannelDeltas(channels) {
         const base = classification.predefined ? overlayVariantBinding(identityBase, classification.predefined) : identityBase;
         const normalized = normalizeEntryAgainstBase(shapeFiltered, base);
         if (normalized) {
-            filtered[key] = normalized;
+            data.channels[key] = normalized;
+        }
+        else {
+            Reflect.deleteProperty(data.channels, key);
         }
     }
-    return filtered;
 }
 /**
- * Prepares channels data for writing to disk. Injects metadata from module state (serviceSelections, tagRegistry) into the serializable output. The metadata
- * is always pulled from module state rather than from the file data, because route handlers may have modified metadata in memory since the last file read.
- * Delta normalization is handled by mutateChannels() before the data reaches this hook.
+ * Prepares channels data for writing to disk. This is a pure function of the passed envelope: channels, schemaVersion, migrationsApplied, serviceSelections,
+ * and tagRegistry are all sourced from `data`, never from module-state caches. The framework guarantees `data` is the source of truth at write time, so reading
+ * module state here would be a side channel that breaks correctness when the boot persist runs before module state is populated. Delta normalization is handled
+ * by mutateChannels() before the data reaches this hook.
  * @param data - The compound channels data with already-normalized channels.
  * @returns The serializable output with channels and current metadata.
  */
@@ -491,6 +720,7 @@ const channelsMigrations = {
             // persist that writes the cleaned shape via prepareChannelsForWrite.
             for (const [canonicalKey, selectedVariant] of Object.entries(data.serviceSelections)) {
                 if (selectedVariant.endsWith("-foxcom")) {
+                    // Strip only "foxcom" (6 chars), not the full "-foxcom" guard (7), so the separating hyphen survives into the foxone-suffixed result.
                     data.serviceSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
                 }
                 if ((canonicalKey === "fox") && (selectedVariant === "fox-site")) {
@@ -499,6 +729,7 @@ const channelsMigrations = {
             }
             for (const [key, value] of Object.entries(data.channels)) {
                 if (key.endsWith("-foxcom")) {
+                    // Strip only "foxcom" (6 chars), not the full "-foxcom" guard (7), so the separating hyphen survives into the foxone-suffixed result.
                     data.channels[key.slice(0, -6) + "foxone"] = value;
                     Reflect.deleteProperty(data.channels, key);
                 }
@@ -635,7 +866,8 @@ function detectIdentityFieldLoss(before, after) {
                 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.
+            // and not data loss. Array-valued fields (notably tags) are compared structurally via isDeepStrictEqual since reference equality would always fail
+            // across freshly-deserialized arrays.
             const canonicalValue = canonical ? canonical[field] : undefined;
             if (canonicalValue !== undefined) {
                 const sameValue = (Array.isArray(beforeValue) && Array.isArray(canonicalValue)) ?
@@ -669,8 +901,9 @@ export async function mutateChannels(fn) {
     await channelsStore.mutate((data) => {
         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);
+        // identical. The normalizer mutates data in place (channels and serviceSelections both - the canonical-binding overlap heal touches both), matching the
+        // migration `apply` convention so all in-place writes share one shape.
+        normalizeChannelDeltas(data);
         writtenData = data;
     });
     // Side effects after successful write. The store framework guarantees writtenData reflects exactly what was persisted.
@@ -683,6 +916,28 @@ export async function mutateChannels(fn) {
     userChannelsParseError = false;
     userChannelsParseErrorMessage = undefined;
 }
+/**
+ * Runs the startup channels-file cleanup pass. Combines two boot-time concerns into one atomic write so they share a single disk transaction:
+ *
+ * - Stale service-selections cleanup: any selection whose variant key no longer exists (deleted predefined variant, removed user channel) is removed by
+ *   buildServiceGroups in module state; this pass mirrors that cleanup to disk so the file matches the runtime view across restarts.
+ * - Canonical-binding overlap heal: invoked indirectly by the post-callback normalizer (normalizeChannelDeltas) which runs against the freshly-read data
+ *   inside mutateChannels. Any canonical override carrying binding whose URL extracts to a sibling variant's domain is healed in place - binding stripped
+ *   from the canonical, propagated to the matching variant entry, serviceSelections updated. The normalizer always runs post-callback; the heal happening
+ *   automatically is required for the cleanup to take effect, not the explicit body of this function.
+ *
+ * Existence as a named function is the architectural point: a bare `mutateChannels(() => {})` would correctly trigger the normalizer but obscure the intent
+ * at the call site. The name documents what the pass does so callers see "run startup cleanup" rather than "do nothing inside a mutation."
+ * @param staleSelections - Service-selection keys to delete from data.serviceSelections. Empty array is allowed (heal-only path).
+ * @throws FileStoreParseError if the channels file contains invalid JSON.
+ */
+export async function runStartupChannelsCleanup(staleSelections) {
+    await mutateChannels((data) => {
+        for (const key of staleSelections) {
+            Reflect.deleteProperty(data.serviceSelections, key);
+        }
+    });
+}
 /**
  * Deletes a user channel by key.
  * @param key - The channel key to delete.
@@ -758,7 +1013,7 @@ export async function resetUserChannels() {
  * 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.
+ * Array-valued identity fields (tags) compare via isDeepStrictEqual after sortTags canonicalizes both sides, 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.
  */
@@ -845,12 +1100,15 @@ export async function initializeUserChannels() {
     // 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 mutateChannels((data) => {
-            for (const key of staleSelections) {
-                Reflect.deleteProperty(data.serviceSelections, key);
-            }
-        });
+    /* Canonical-binding overlap heal at startup. Any canonical override whose binding URL extracts to a sibling variant's domain represents the wholesale-
+     * duplication shape from before the per-field PUT routing landed - the user wanted "default this channel to the sibling's service" but the producer
+     * dumped the full delta onto the canonical instead of routing binding to the variant and recording the redirect via serviceSelections. The normalizer
+     * fixes this on every write; this conditional one-shot pass triggers the heal at boot for users on upgrade so they don't have to perform any manual save
+     * action to clean up their data. Combined with the stale-selections cleanup so a single write handles both startup conditions when both apply.
+     */
+    const needsOverlapHeal = hasCanonicalBindingOverlap(loadedUserChannels);
+    if ((staleSelections.length > 0) || needsOverlapHeal) {
+        await runStartupChannelsCleanup(staleSelections);
     }
     // Now that service groups are built, validate the configured service tags. Strip any unrecognized tags and warn.
     if (configuredServices.length > 0) {
@@ -892,7 +1150,7 @@ export async function initializeUserChannels() {
 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.
+// values from Object.entries iteration; the contents are statically-known CustomizableField values via the spread below.
 const DELTA_ALLOWED_FIELDS = new Set([...DELTA_ELIGIBLE_IDENTITY_KEYS, ...DELTA_ELIGIBLE_BINDING_KEYS]);
 /**
  * Extracts the identity-only subset of a channel. Used by resolveVariant and normalizeChannelDeltas to compute the inheritance base for variants: a variant
@@ -942,7 +1200,7 @@ function overlayDelta(base, stored) {
  * 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.
+ * metadata. The kernel exists to keep the two overlays from drifting - both share one control-flow path rather than duplicating it in each call site.
  * @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
@@ -1026,7 +1284,7 @@ export function resolveStoredChannel(key, stored) {
  */
 function getMergedChannelMap() {
     const result = buildResolvedCanonicals(loadedUserChannels);
-    const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
+    const allKeys = new Set(Object.keys(PREDEFINED_CHANNELS)).union(new Set(Object.keys(loadedUserChannels)));
     for (const key of allKeys) {
         const stored = loadedUserChannels[key];
         const classification = classifyEntry(key, stored);
@@ -1079,7 +1337,7 @@ function getMergedChannelMap() {
  * @returns Sorted array of channel listing entries.
  */
 export function getChannelListing() {
-    const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
+    const allKeys = new Set(Object.keys(PREDEFINED_CHANNELS)).union(new Set(Object.keys(loadedUserChannels)));
     const listing = [];
     for (const key of allKeys) {
         // Skip service variants - they're accessed via service selection, not as separate channels.
@@ -1160,7 +1418,7 @@ export function getAllChannels() {
 }
 /**
  * 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.
+ * cross-store consistency rules 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() {
@@ -1513,7 +1771,8 @@ export function getChannelStationId(channelKey) {
         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.
+    // so a hit is structurally a canonical. Narrow via the canonicalKey field that marks the kind: a defined canonicalKey marks a VariantChannel, which has no
+    // stationId.
     const predefined = PREDEFINED_CHANNELS[effectiveKey];
     if (!predefined || (predefined.canonicalKey !== undefined)) {
         return undefined;
@@ -1546,7 +1805,8 @@ export function isUserChannel(key) {
  */
 /**
  * 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.
+ * intent. Property overrides (HDHR toggle, name change, tag edits) stored as deltas in channels.json are independent and do not affect the enabled/disabled
+ * state.
  * @param key - The channel key to check.
  * @returns True if the channel is predefined and disabled.
  */
@@ -1588,14 +1848,15 @@ async function mutateDisabledPredefined(op, keys) {
     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.
+ * Disables one or more predefined channels by adding their keys to the disabledPredefined list in user config. Safe to call again with the same keys.
+ * @param keys - The predefined channel keys to disable. Duplicates within the input array and pre-existing disabled entries are handled without producing
+ * duplicate list entries.
  */
 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.
+ * Enables one or more predefined channels by removing their keys from the disabledPredefined list in user config. Safe to call again with the same keys.
  * @param keys - The predefined channel keys to enable. Entries that aren't in the disabled list are ignored.
  */
 export async function enablePredefinedChannels(keys) {
@@ -1604,7 +1865,7 @@ export async function enablePredefinedChannels(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.
+ * Persists and hydrates the runtime cache in a single call, 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.
  */
@@ -1821,27 +2082,31 @@ export function validateChannelName(name) {
 /**
  * Validates a profile name.
  * @param profile - The profile name to validate (can be empty for autodetect).
- * @param validProfiles - Array of valid profile names.
+ * @param isKnownProfile - Predicate answering whether a profile name exists. Callers test each name against the single builtin lookup plus the user's own
+ * profiles, so that a channel may reference a provider profile as well as a general or user-defined one.
  * @returns Error message if invalid, undefined if valid.
  */
-export function validateChannelProfile(profile, validProfiles) {
+export function validateChannelProfile(profile, isKnownProfile) {
     // Empty profile means autodetect, which is valid.
     if (!profile || (profile.trim() === "")) {
         return undefined;
     }
-    // Check if profile exists.
-    if (!validProfiles.includes(profile)) {
-        return "Unknown profile: " + profile + ". Valid profiles: " + validProfiles.join(", ") + ".";
+    /* Check if profile exists. The message names the rejected value alone. The set of acceptable names includes the provider profiles, which the web UI's profile
+     * picker deliberately omits, so spelling that set out here would offer names the picker will never present. The picker is the discovery surface for a valid
+     * profile name; this message's job is to say which value was not one.
+     */
+    if (!isKnownProfile(profile)) {
+        return "Unknown profile: " + profile + ".";
     }
     return undefined;
 }
 /**
  * Validates an imported channels object for structure and content.
  * @param data - The raw imported data to validate.
- * @param validProfiles - Array of valid profile names.
+ * @param isKnownProfile - Predicate answering whether a referenced profile name exists, passed through to the per-channel profile check.
  * @returns Validation result with errors if invalid.
  */
-export function validateImportedChannels(data, validProfiles) {
+export function validateImportedChannels(data, isKnownProfile) {
     const errors = [];
     // Check that input is an object.
     if ((typeof data !== "object") || (data === null) || Array.isArray(data)) {
@@ -1886,7 +2151,7 @@ export function validateImportedChannels(data, validProfiles) {
         }
         // Validate optional profile field. Sanitize after type check.
         const profile = (typeof channelData["profile"] === "string") ? sanitizeString(channelData["profile"]) : undefined;
-        const profileError = validateChannelProfile(profile, validProfiles);
+        const profileError = validateChannelProfile(profile, isKnownProfile);
         if (profileError) {
             errors.push("Channel '" + key + "': " + profileError);
             continue;
@@ -1947,8 +2212,8 @@ export function validateImportedChannels(data, validProfiles) {
 /**
  * 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.
+ * normalizer depends on that ordering guarantee - it uses sortTags on both sides when comparing a delta's tags against a predefined's tags, making the
+ * isDeepStrictEqual comparison 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.
  */