prismcast 1.7.0 → 1.9.0

package/dist/config/userChannels.js

@@ -1,10 +1,15 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * userChannels.ts: User channel file management for PrismCast.
+ */
+import { CHANNEL_IDENTITY_FIELDS, PREDEFINED_CHANNELS, PREDEFINED_TAGS } from "../channels/index.js";
+import { FileStoreParseError, createFileStore } from "./persistence.js";
 import { LOG, containsNonPrintable, sanitizeString } from "../utils/index.js";
-import { buildProviderGroups, getAllProviderTags, getProviderSelections, getResolvedChannel, isChannelAvailableByProvider, isProviderVariant, resolveProviderKey, setEnabledProviders, setProviderSelections } from "./providers.js";
-import { getChannelsFilePath, getDataDir } from "./paths.js";
-import { loadUserConfig, saveUserConfig } from "./userConfig.js";
+import { buildServiceGroups, getAllServiceTags, getResolvedChannel, getServiceSelections, isChannelAvailableByService, isServiceVariant, resolveServiceKey, setEnabledServices, setServiceSelections } from "./services.js";
 import { CONFIG } from "./index.js";
-import { PREDEFINED_CHANNELS } from "../channels/index.js";
 import fs from "node:fs";
+import { getChannelsFilePath } from "./paths.js";
+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.
  */
@@ -22,6 +27,8 @@ export function getUserChannelsFilePath() {
 let loadedUserChannels = {};
 let userChannelsParseError = false;
 let userChannelsParseErrorMessage;
+// Module-level tag registry state. Tracks user-created tags and user-deleted predefined tags. The runtime vocabulary is computed by getActiveTagVocabulary().
+let loadedTagRegistry = { deletedTags: [], tags: [] };
 /**
  * Returns whether the user channels file had a parse error.
  * @returns True if the channels file exists but contains invalid JSON.
@@ -37,67 +44,63 @@ export function getChannelsParseErrorMessage() {
     return userChannelsParseErrorMessage;
 }
 /**
- * Loads user channels from the channels file. Returns an empty map if the file doesn't exist, and sets parseError if the file exists but contains invalid JSON.
- * The file can contain a special `providerSelections` key with user's provider preferences, which is extracted separately from channels.
- * @returns The loaded channels with parse status and provider selections.
+ * 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.
+ * @param raw - The raw JSON string from the file.
+ * @returns The parsed compound data.
  */
-export async function loadUserChannels() {
-    try {
-        const content = await fsPromises.readFile(getChannelsFilePath(), "utf-8");
-        try {
-            const parsed = JSON.parse(content);
-            // Extract providerSelections if present — it's not a channel, it's metadata.
-            const providerSelections = {};
-            const channels = {};
-            for (const [key, value] of Object.entries(parsed)) {
-                if (key === "providerSelections") {
-                    // Copy provider selections if it's an object.
-                    if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
-                        for (const [selKey, selValue] of Object.entries(value)) {
-                            if (typeof selValue === "string") {
-                                providerSelections[selKey] = selValue;
-                            }
-                        }
+function parseChannelsFile(raw) {
+    const parsed = JSON.parse(raw);
+    const channels = {};
+    const serviceSelections = {};
+    const tagRegistry = { deletedTags: [], tags: [] };
+    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 ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
+                for (const [selKey, selValue] of Object.entries(value)) {
+                    if (typeof selValue === "string") {
+                        serviceSelections[selKey] = selValue;
                     }
                 }
-                else if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
-                    // It's a channel definition or delta override.
-                    channels[key] = value;
+            }
+        }
+        else if (key === "tagRegistry") {
+            // 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.deletedTags)) {
+                    tagRegistry.deletedTags = rawRegistry.deletedTags.filter((t) => typeof t === "string").sort();
                 }
             }
-            return { channels, parseError: false, providerSelections };
         }
-        catch (parseError) {
-            const message = (parseError instanceof Error) ? parseError.message : String(parseError);
-            LOG.warn("Invalid JSON in channels file %s: %s. Using predefined channels only.", getChannelsFilePath(), message);
-            return { channels: {}, parseError: true, parseErrorMessage: message, providerSelections: {} };
+        else if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
+            // It's a channel definition or delta override.
+            channels[key] = value;
         }
     }
-    catch (error) {
-        // File doesn't exist - this is normal, use predefined channels only.
-        if (error.code === "ENOENT") {
-            return { channels: {}, parseError: false, providerSelections: {} };
+    // 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.
+    for (const channel of Object.values(channels)) {
+        const legacy = channel;
+        if (("provider" in legacy) && !("service" in legacy)) {
+            legacy.service = legacy.provider;
         }
-        // Other read errors - log and use predefined channels.
-        LOG.warn("Failed to read channels file %s: %s. Using predefined channels only.", getChannelsFilePath(), (error instanceof Error) ? error.message : String(error));
-        return { channels: {}, parseError: false, providerSelections: {} };
+        Reflect.deleteProperty(legacy, "provider");
     }
+    return { channels, serviceSelections, tagRegistry };
 }
 /**
- * Saves user channels to the channels file and updates the in-memory cache. Changes take effect immediately for new stream requests without requiring a server
- * restart. Creates the data directory if it doesn't exist. Provider selections are also saved if any exist. No-op deltas for predefined channel keys are
- * normalized before saving: fields that match the predefined value or null-clear a field the predefined doesn't have are stripped. If the delta becomes empty
- * after normalization, the entry is removed entirely. This ensures that any code path that writes deltas (inline edit, auto-number, browse modal, full edit)
- * produces clean channels.json output without each handler needing to optimize its own delta.
- * @param channels - The channels to save (full definitions or delta overrides).
- * @throws If the file cannot be written.
+ * 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.
  */
-export async function saveUserChannels(channels) {
-    // Ensure data directory exists.
-    await fsPromises.mkdir(getDataDir(), { recursive: true });
-    // Normalize predefined channel deltas by stripping no-op fields. A delta field is a no-op if: (1) its value is null and the predefined doesn't have the
-    // field (clearing a nonexistent field), (2) its value is undefined, or (3) its value matches the predefined's value exactly (redundant copy). After stripping,
-    // deltas with no remaining fields are removed entirely.
+function normalizeChannelDeltas(channels) {
     const filtered = {};
     for (const [key, stored] of Object.entries(channels)) {
         if (key in PREDEFINED_CHANNELS) {
@@ -109,17 +112,21 @@ export async function saveUserChannels(channels) {
                 if (!DELTA_ALLOWED_FIELDS.has(field)) {
                     continue;
                 }
-                // Skip undefined values — they have no effect.
+                // 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.
+                // 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.
-                if ((value !== null) && (predefined[field] === value)) {
-                    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;
+                    }
                 }
                 cleaned[field] = value;
                 hasFields = true;
@@ -136,52 +143,90 @@ export async function saveUserChannels(channels) {
             }
         }
         else {
-            filtered[key] = stored;
+            // 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));
         }
     }
-    // Sort channels by key for consistent output.
-    const sortedChannels = {};
-    const sortedKeys = Object.keys(filtered).sort();
-    for (const key of sortedKeys) {
-        sortedChannels[key] = filtered[key];
-    }
-    // Include provider selections if any exist.
-    const selections = getProviderSelections();
+    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.
+ * @param data - The compound channels data with already-normalized 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) {
-        // Sort provider selections for consistent output.
-        const sortedSelections = {};
-        const selectionKeys = Object.keys(selections).sort();
-        for (const key of selectionKeys) {
-            sortedSelections[key] = selections[key];
-        }
-        sortedChannels.providerSelections = sortedSelections;
-    }
-    // Write channels with pretty formatting for readability.
-    const content = JSON.stringify(sortedChannels, null, 2);
-    await fsPromises.writeFile(getChannelsFilePath(), content + "\n", "utf-8");
-    // Update in-memory cache so changes take effect immediately for new stream requests.
-    loadedUserChannels = { ...filtered };
-    // Refresh provider groups so channelsRef reflects the new channel data. This ensures getResolvedChannel() returns correct data after modifications.
-    buildProviderGroups(getMergedChannelMap());
-    // Clear any previous parse error since we're writing valid data.
+        output.serviceSelections = selections;
+    }
+    if ((loadedTagRegistry.tags.length > 0) || (loadedTagRegistry.deletedTags.length > 0)) {
+        output.tagRegistry = loadedTagRegistry;
+    }
+    return output;
+}
+// Transactional store instance for channels.json.
+const channelsStore = createFileStore({
+    beforeWrite: prepareChannelsForWrite,
+    defaultValue: () => ({ channels: {}, serviceSelections: {}, tagRegistry: { deletedTags: [], tags: [] } }),
+    label: "channels",
+    parse: parseChannelsFile,
+    path: getChannelsFilePath
+});
+/**
+ * Reads the current channels from disk without acquiring the serialization lock. Returns the parsed channels with metadata and parse status. Use this for
+ * read-only access and startup initialization. For modifications, use mutateChannels() instead.
+ * @returns The loaded channels with parse status, service selections, and tag registry.
+ */
+export async function readChannels() {
+    const result = await channelsStore.read();
+    return {
+        channels: result.data.channels,
+        parseError: result.parseError,
+        parseErrorMessage: result.parseErrorMessage,
+        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.
+ */
+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 = {};
+    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.
+        data.channels = normalizeChannelDeltas(data.channels);
+        normalizedChannels = data.channels;
+    });
+    // Side effects after successful write. These only run if the store mutation (including atomic file write) completed without error.
+    loadedUserChannels = { ...normalizedChannels };
+    buildServiceGroups(getMergedChannelMap());
     userChannelsParseError = false;
     userChannelsParseErrorMessage = undefined;
 }
 /**
  * Deletes a user channel by key.
  * @param key - The channel key to delete.
- * @throws If the file cannot be read or written.
+ * @throws FileStoreParseError if the channels file contains invalid JSON.
+ * @throws If the file cannot be written.
  */
 export async function deleteUserChannel(key) {
-    const result = await loadUserChannels();
-    // If parse error, we can't modify - just log a warning.
-    if (result.parseError) {
-        throw new Error("Cannot delete channel: channels file contains invalid JSON.");
-    }
-    // Remove the channel.
-    Reflect.deleteProperty(result.channels, key);
-    // Save the modified channels.
-    await saveUserChannels(result.channels);
+    await mutateChannels((channels) => {
+        Reflect.deleteProperty(channels, key);
+    });
     LOG.info("User channel '%s' deleted.", key);
 }
 /**
@@ -205,61 +250,72 @@ 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.
  */
 /**
- * Initializes user channels by loading them from the file. This should be called once at server startup. Also builds provider groups and loads provider selections.
+ * 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() {
-    const result = await loadUserChannels();
-    // Silent migration: rename "foxcom" provider references to "foxone." Migrates provider selections (channels.json) and user channel variant keys. The
-    // provider filter (config.json) is handled separately below since it's already loaded into CONFIG at this point.
+    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.
+    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.providerSelections)) {
+    for (const [canonicalKey, selectedVariant] of Object.entries(result.serviceSelections)) {
+        // foxcom → foxone: original Fox service slug renamed.
         if (selectedVariant.endsWith("-foxcom")) {
-            result.providerSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
+            result.serviceSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
             channelsMigrated = true;
         }
-    }
-    for (const key of Object.keys(result.channels)) {
-        if (key.endsWith("-foxcom")) {
-            result.channels[key.slice(0, -6) + "foxone"] = result.channels[key];
-            Reflect.deleteProperty(result.channels, key);
+        // 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 provider selections before saving so that saveUserChannels (which persists both channels and selections) captures the migrated values.
-    setProviderSelections(result.providerSelections);
+    // 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 saveUserChannels(result.channels);
-        LOG.info("Migrated Fox provider references from foxcom to foxone.");
+        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.");
     }
-    loadedUserChannels = result.channels;
-    userChannelsParseError = result.parseError;
-    userChannelsParseErrorMessage = result.parseErrorMessage;
-    // Load enabled providers 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 buildProviderGroups() because getAllProviderTags() depends on the groups being built.
-    let configuredProviders = CONFIG.channels.enabledProviders;
-    // Silent migration: rename "foxcom" to "foxone" in the provider filter if present. Persisted to config.json immediately so the stale value doesn't remain.
-    if (configuredProviders.includes("foxcom")) {
-        configuredProviders = configuredProviders.map((tag) => (tag === "foxcom") ? "foxone" : tag);
-        CONFIG.channels.enabledProviders = configuredProviders;
-        const configResult = await loadUserConfig();
-        if (configResult.config.channels?.enabledProviders) {
-            configResult.config.channels.enabledProviders = configuredProviders;
-            await saveUserConfig(configResult.config);
-        }
-        LOG.info("Migrated provider filter from foxcom to foxone.");
-    }
-    // Upgrade inference for setupCompleted: existing users who already have providers or channels configured should not see the first-run setup wizard. If the
+    // 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.");
+    }
+    // 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.
     if (!CONFIG.channels.setupCompleted) {
-        const hasProviders = configuredProviders.length > 0;
+        const hasServices = configuredServices.length > 0;
         const hasUserChannels = Object.keys(loadedUserChannels).length > 0;
-        if (hasProviders || hasUserChannels) {
+        if (hasServices || hasUserChannels) {
             CONFIG.channels.setupCompleted = true;
-            const configResult = await loadUserConfig();
-            configResult.config.channels ??= {};
-            configResult.config.channels.setupCompleted = true;
-            await saveUserConfig(configResult.config);
-            LOG.info("Inferred Provider Setup as completed from existing configuration.");
+            await mutateConfig((config) => {
+                config.channels ??= {};
+                config.channels.setupCompleted = true;
+            });
         }
     }
     // One-time migration: stamp canonicalKey on existing user channel variant entries that were created before explicit variant relationships were introduced.
@@ -276,32 +332,81 @@ export async function initializeUserChannels() {
             continue;
         }
         const prefix = key.substring(0, hyphenIndex);
-        // Only stamp canonicalKey if the prefix exists as a predefined channel. This matches the old buildProviderGroups heuristic exactly.
+        // 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 saveUserChannels(result.channels);
+        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.");
     }
-    // Build the merged channels map and then build provider groups.
+    // 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();
-    buildProviderGroups(mergedChannels);
-    // Now that provider groups are built, validate the configured provider tags. Strip any unrecognized tags and warn.
-    if (configuredProviders.length > 0) {
-        const knownTags = new Set(getAllProviderTags().map((t) => t.tag));
-        const validTags = configuredProviders.filter((tag) => knownTags.has(tag));
-        const invalidTags = configuredProviders.filter((tag) => !knownTags.has(tag));
+    // 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.
+    const staleSelections = buildServiceGroups(mergedChannels);
+    if (staleSelections.length > 0) {
+        await saveServiceSelections();
+    }
+    // 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));
         if (invalidTags.length > 0) {
-            LOG.warn("Ignoring unrecognized provider tags in configuration: %s.", invalidTags.join(", "));
+            LOG.warn("Ignoring unrecognized service tags in configuration: %s.", invalidTags.join(", "));
         }
-        setEnabledProviders(validTags);
-        CONFIG.channels.enabledProviders = validTags;
+        setEnabledServices(validTags);
+        CONFIG.channels.enabledServices = validTags;
     }
     else {
-        setEnabledProviders(configuredProviders);
+        setEnabledServices(configuredServices);
     }
     // 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)) {
@@ -321,9 +426,11 @@ export async function initializeUserChannels() {
         LOG.info("Loaded %d channels.", totalCount);
     }
 }
-// Fields that users are allowed to override via delta. This allowlist prevents hand-edited channels.json from overriding fields like provider that are
-// intentionally not user-editable. Matches the fields in the ChannelDelta interface.
-const DELTA_ALLOWED_FIELDS = new Set(["channelNumber", "channelSelector", "hdhrEnabled", "name", "profile", "stationId", "tvgShift", "url"]);
+// 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]);
 /**
  * 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
@@ -340,7 +447,9 @@ export function resolveStoredChannel(key, stored) {
     if (!predefined) {
         return stored;
     }
-    // Start with a copy of the predefined definition, then overlay allowlisted non-null delta fields.
+    // 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)) {
@@ -355,10 +464,13 @@ export function resolveStoredChannel(key, stored) {
             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.
+    resolved.tags &&= resolved.tags.slice();
     return resolved;
 }
 /**
- * Returns the merged channel map (predefined + user) without filtering by enabled status or provider variants. Used internally for building provider groups.
+ * 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.
  * @returns The complete merged channel map.
  */
@@ -384,12 +496,12 @@ 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.
  *
- * Provider variants (non-canonical keys in provider groups) are filtered out from this listing — they are accessed via the provider 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 provider
- * system (providers.ts) relies on this reference difference to detect user overrides via isUserOverride(). Predefined-only entries preserve the original reference.
+ * 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.
  *
- * The returned channel field is provider-resolved: when a non-default provider is selected for a channel, the entry's channel reflects the selected variant's URL,
+ * The returned channel field is service-resolved: when a non-default service is selected for a channel, the entry's channel reflects the selected variant's URL,
  * channelSelector, stationId, and channelNumber. The entry's key always remains the canonical key.
  * @returns Sorted array of channel listing entries.
  */
@@ -397,8 +509,8 @@ export function getChannelListing() {
     const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
     const listing = [];
     for (const key of allKeys) {
-        // Skip provider variants — they're accessed via provider selection, not as separate channels.
-        if (isProviderVariant(key)) {
+        // Skip service variants — they're accessed via service selection, not as separate channels.
+        if (isServiceVariant(key)) {
             continue;
         }
         const isPredefined = key in PREDEFINED_CHANNELS;
@@ -415,14 +527,14 @@ export function getChannelListing() {
             source = "predefined";
         }
         // 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 providers.ts (reference comparison against PREDEFINED_CHANNELS[key]). Predefined-only entries keep the original reference.
+        // 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];
-        // When a non-default provider is selected, resolve the variant so consumers see the correct URL, channelSelector, stationId, and channelNumber. We skip
+        // 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.
-        const resolvedKey = resolveProviderKey(key);
+        const resolvedKey = resolveServiceKey(key);
         const resolvedChannel = (resolvedKey !== key) ? getResolvedChannel(resolvedKey) : undefined;
         listing.push({
-            availableByProvider: isChannelAvailableByProvider(key),
+            availableByService: isChannelAvailableByService(key),
             channel: resolvedChannel ?? channel,
             enabled: !isPredefinedChannelDisabled(key),
             key,
@@ -434,14 +546,14 @@ export function getChannelListing() {
     return listing;
 }
 /**
- * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded unless they
- * have a user override. Built on top of getChannelListing() to ensure a single merging code path.
+ * 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.
  * @returns The merged channel map with disabled predefined channels filtered out.
  */
 export function getAllChannels() {
     const result = {};
     for (const entry of getChannelListing()) {
-        if (entry.enabled && entry.availableByProvider) {
+        if (entry.enabled && entry.availableByService) {
             result[entry.key] = entry.channel;
         }
     }
@@ -454,6 +566,104 @@ export function getAllChannels() {
 export function getUserChannels() {
     return { ...loadedUserChannels };
 }
+// Tag Registry.
+/**
+ * Returns the current tag registry state.
+ * @returns A copy of the tag registry with user-created tags and deleted predefined tags.
+ */
+export function getTagRegistry() {
+    return { deletedTags: [...loadedTagRegistry.deletedTags], tags: [...loadedTagRegistry.tags] };
+}
+/**
+ * Updates the tag registry state in memory. Call saveTagRegistry() after to persist the change.
+ * @param registry - The new tag registry state.
+ */
+export function setTagRegistry(registry) {
+    loadedTagRegistry = { deletedTags: registry.deletedTags.sort(), tags: registry.tags.sort() };
+}
+/**
+ * Returns the active tag vocabulary: predefined tags minus user-deleted tags, plus user-created tags, sorted alphabetically. This is the single source of truth
+ * for which tags are visible, assignable, and queryable throughout the system. Tags not in this list are invisible to the UI and rejected by the ?tag= query
+ * parameter, even if they exist on channel definitions (vocabulary-as-lens model).
+ * @returns Sorted array of active tag strings.
+ */
+export function getActiveTagVocabulary() {
+    const active = PREDEFINED_TAGS.filter((tag) => !loadedTagRegistry.deletedTags.some((d) => tagsMatch(d, tag)));
+    // Merge user tags, deduplicate case-insensitively (in case a user tag matches a non-deleted predefined tag), and sort. When a predefined and user tag
+    // collide case-insensitively, the predefined form wins since it appears first in the Map.
+    const seen = new Map();
+    for (const tag of [...active, ...loadedTagRegistry.tags]) {
+        const lower = tag.toLowerCase();
+        if (!seen.has(lower)) {
+            seen.set(lower, tag);
+        }
+    }
+    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.
+ * @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.
+ */
+export function getChannelEffectiveTags(channel) {
+    if (!channel.tags || (channel.tags.length === 0)) {
+        return [];
+    }
+    const vocabulary = getActiveTagVocabulary();
+    return channel.tags.filter((tag) => vocabulary.some((v) => tagsMatch(v, tag)));
+}
+/**
+ * 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.
+ * @param a - The first tag.
+ * @param b - The second tag.
+ * @returns True if the tags match case-insensitively.
+ */
+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
+ * 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.
+ * @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.
+ * @returns Object with the affected channel keys and success status. On parse error, returns an error message and empty affected keys.
+ */
+export async function transformChannelTags(filter, transform) {
+    const affectedKeys = [];
+    try {
+        await mutateChannels((channels) => {
+            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())) {
+                    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;
+                affectedKeys.push(entry.key);
+            }
+        });
+    }
+    catch (error) {
+        if (error instanceof FileStoreParseError) {
+            return { affectedKeys: [], error: "Cannot update tags: channels file contains invalid JSON." };
+        }
+        throw error;
+    }
+    return { affectedKeys };
+}
 /**
  * Returns the predefined channel definition for a key.
  * @param key - The channel key to look up.
@@ -554,19 +764,15 @@ 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.
+ * 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.
  */
 export function isPredefinedChannelDisabled(key) {
-    // Only predefined channels can be disabled via this mechanism.
     if (!isPredefinedChannel(key)) {
         return false;
     }
-    // If a user channel overrides this predefined channel, the predefined channel's disabled state is irrelevant.
-    if (isUserChannel(key)) {
-        return false;
-    }
     return CONFIG.channels.disabledPredefined.includes(key);
 }
 /**
@@ -577,14 +783,14 @@ export function getDisabledPredefinedChannels() {
     return [...CONFIG.channels.disabledPredefined];
 }
 /**
- * Returns all predefined channels regardless of disabled state, excluding provider variants. Used by the UI to show all predefined channels including disabled ones.
- * Provider variants are internal implementation details of channel delivery and are not channels themselves.
+ * 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.
  * @returns The predefined channel map with canonical entries only.
  */
 export function getPredefinedChannels() {
     const result = {};
     for (const [key, channel] of Object.entries(PREDEFINED_CHANNELS)) {
-        if (isProviderVariant(key)) {
+        if (isServiceVariant(key)) {
             continue;
         }
         result[key] = channel;
@@ -597,15 +803,15 @@ 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. Provider 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 provider variants — they are internal implementation details, not channels.
-        if (isProviderVariant(key)) {
+        // Skip service variants — they are internal implementation details, not channels.
+        if (isServiceVariant(key)) {
             continue;
         }
         if (side === "pacific") {
@@ -641,14 +847,14 @@ export function getEastWithPacificPredefinedKeys() {
 }
 /**
  * Computes enabled/total counts for all three predefined channel scopes (all, east, pacific) against the current disabled set. Both the enabled count and
- * the total are filtered by provider availability so that the displayed counts match the visible channel table. When no provider filter is active,
+ * the total are filtered by service availability so that the displayed counts match the visible channel table. When no service filter is active,
  * all channels pass and the counts are unaffected. Used by the server-side HTML renderer and both toggle endpoints to provide consistent counts to the client.
  * @returns An object with `all`, `east`, and `pacific` keys, each containing `{ enabled, total }`.
  */
 export function getPredefinedScopeCounts() {
-    const allKeys = Object.keys(getPredefinedChannels()).filter((k) => isChannelAvailableByProvider(k));
-    const eastKeys = getEastWithPacificPredefinedKeys().filter((k) => isChannelAvailableByProvider(k));
-    const pacificKeys = getPacificPredefinedKeys().filter((k) => isChannelAvailableByProvider(k));
+    const allKeys = Object.keys(getPredefinedChannels()).filter((k) => isChannelAvailableByService(k));
+    const eastKeys = getEastWithPacificPredefinedKeys().filter((k) => isChannelAvailableByService(k));
+    const pacificKeys = getPacificPredefinedKeys().filter((k) => isChannelAvailableByService(k));
     const disabled = new Set(CONFIG.channels.disabledPredefined);
     return {
         all: { enabled: allKeys.filter((k) => !disabled.has(k)).length, total: allKeys.length },
@@ -877,15 +1083,25 @@ export function validateImportedChannels(data, validProfiles) {
     }
     return { channels, errors, valid: errors.length === 0 };
 }
-/* Provider selections are stored in the channels.json file alongside user channels. When a selection changes, we save the entire file (channels + selections)
+/* 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 provider selections to the channels file. This triggers a full file save including all user channels.
+ * 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.
+ */
+export async function saveServiceSelections() {
+    // No-op mutation: the beforeWrite hook injects current serviceSelections from module state.
+    await mutateChannels(() => { });
+}
+/**
+ * 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.
  */
-export async function saveProviderSelections() {
-    // Simply save the user channels — the saveUserChannels function includes provider selections automatically.
-    await saveUserChannels(loadedUserChannels);
+export async function saveTagRegistry() {
+    // No-op mutation: the beforeWrite hook injects the current tag registry from module state.
+    await mutateChannels(() => { });
 }
 //# sourceMappingURL=userChannels.js.map