prismcast 1.9.0 → 1.10.0

package/dist/config/userChannels.d.ts

@@ -1,4 +1,5 @@
-import type { Channel, ChannelListingEntry, ChannelMap, StoredChannel, StoredChannelMap } from "../types/index.js";
+import type { Channel, ChannelDelta, ChannelIdentity, ChannelListingEntry, ChannelMap, ChannelSortField, CustomizableField, ResolvedChannel, ResolvedChannelMap, SortDirection, StoredChannel, StoredChannelMap } from "../types/index.ts";
+import { type Migration, type ValidationIssue } from "./persistence.ts";
 /**
  * User-defined channel with all channel properties.
  */
@@ -22,6 +23,7 @@ export interface UserChannelsLoadResult {
     channels: StoredChannelMap;
     parseError: boolean;
     parseErrorMessage?: string;
+    recoveredFromBackup: boolean;
     serviceSelections: Record<string, string>;
     tagRegistry: TagRegistry;
 }
@@ -40,6 +42,178 @@ export declare function hasChannelsParseError(): boolean;
  * @returns The error message or undefined.
  */
 export declare function getChannelsParseErrorMessage(): string | undefined;
+/**
+ * Compound data type for the channels file store. Carries channel entries alongside the metadata keys that are stored in the same JSON file. The framework
+ * uses schemaVersion and migrationsApplied for migration tracking; everything else is application-owned.
+ */
+interface ChannelsFileData {
+    channels: StoredChannelMap;
+    migrationsApplied: string[];
+    schemaVersion: number;
+    serviceSelections: Record<string, string>;
+    tagRegistry: TagRegistry;
+}
+/**
+ * Parses raw channels.json content into the compound data type. Extracts channel entries, service selections, tag registry, and framework metadata
+ * (schemaVersion, migrationsApplied) from the top-level JSON object. Also performs structural normalization for legacy field/key naming so consumer code only
+ * sees the current shape; the schemaVersion progression governs when the cleanup is persisted to disk via the migration framework.
+ * @param raw - The raw JSON string from the file.
+ * @returns The parsed compound data.
+ */
+declare function parseChannelsFile(raw: string): ChannelsFileData;
+/**
+ * Normalizes a single stored entry as a delta against a base channel. Delta fields are dropped when they are no-ops: undefined values, nulls against a base
+ * that has no such field, and values that match the base exactly. Array-valued fields use JSON.stringify for equality with case-insensitive canonical sorting
+ * for the fields listed in CANONICAL_SORTED_ARRAY_FIELDS so authoring-order differences do not defeat the match. Non-delta fields (e.g., canonicalKey) pass
+ * through unchanged so the stored entry retains its relationship metadata.
+ * @param stored - The raw stored entry.
+ * @param base - The base Channel to diff against (predefined definition for overrides, resolved canonical for variants).
+ * @returns The normalized entry, or null when every field is a no-op and the entry would carry no information.
+ */
+declare function normalizeEntryAgainstBase(stored: StoredChannel, base: Channel): StoredChannel | null;
+/**
+ * Classification of a channel entry. Canonical and variant cases carry enough context (predefined entry, stored entry, canonicalKey for variants) that callers
+ * do not need to re-read the source maps.
+ */
+type EntryClassification = {
+    kind: "canonical";
+    predefined: Channel;
+    stored: StoredChannel | undefined;
+} | {
+    kind: "variant";
+    canonicalKey: string;
+    predefined: Channel | undefined;
+    stored: StoredChannel | undefined;
+} | {
+    kind: "standalone";
+    stored: StoredChannel;
+};
+/**
+ * Classifies a channel entry by consulting both the predefined catalog and the user's stored map. The kind determines how the entry is resolved, normalized, and
+ * displayed.
+ *
+ * Precondition: at least one of the predefined catalog or the stored map must have the key. Callers iterate over the union of key sets and therefore always
+ * satisfy this. Violating the precondition throws rather than returning a nullable - the alternative is a defensive undefined check at every call site for a
+ * case that never occurs, which is both dead code and a misleading contract.
+ * @param key - The channel key.
+ * @param stored - The stored entry from the user's channels map (if any).
+ * @returns The classification. Never undefined; see the precondition.
+ * @throws Error when neither PREDEFINED_CHANNELS nor the caller's stored map contains the key.
+ */
+declare function classifyEntry(key: string, stored: StoredChannel | undefined): EntryClassification;
+/**
+ * Computes the field-name allowlist for a stored entry's expected shape. Stored entries fall into two structural shapes determined by classification:
+ *
+ *  - Canonical-shaped (kind = canonical or standalone): allowed fields are DELTA_ELIGIBLE_IDENTITY_KEYS ∪ DELTA_ELIGIBLE_BINDING_KEYS. The full delta surface.
+ *  - Variant-shaped (kind = variant): allowed fields are DELTA_ELIGIBLE_BINDING_KEYS plus the structural canonicalKey discriminator. Identity inherits from the
+ *    canonical and must not appear on variants per the architectural principle.
+ *
+ * Single source of truth for the shape rule. Used by filterToDeltaSurface (normalizer pre-strip) and by the customization accessor's per-pass walks. Routes
+ * shape determination through classifyEntry so any caller automatically picks up classifier improvements - no parallel logic for "is this a variant?".
+ * @param key - The channel key for classification.
+ * @param stored - The stored entry for classification.
+ * @returns The set of field names allowed for this entry's shape.
+ */
+declare function getAllowedFieldsForShape(key: string, stored: StoredChannel): ReadonlySet<string>;
+/**
+ * Filters a stored entry to its expected delta surface, stripping any field outside the allowed shape. Returns both the filtered entry and the names of any
+ * fields that were stripped, so callers can surface diagnostics.
+ *
+ * The shape rule is enforced here at storage-write time (called from normalizeChannelDeltas) so legacy data with orphan fields - non-delta-eligible identity
+ * (pacificStationId), non-delta-eligible binding (DOM hooks), or identity-on-variants - cleans up automatically on next save. The `stripped` array lets the
+ * caller log a warning when cleanup happens, giving operators visibility into the violation.
+ * @param key - The channel key for shape classification.
+ * @param stored - The stored entry to filter.
+ * @returns The filtered entry plus the list of stripped field names.
+ */
+declare function filterToDeltaSurface(key: string, stored: StoredChannel): {
+    filtered: StoredChannel;
+    stripped: readonly string[];
+};
+/**
+ * Resolves a variant by layering canonical identity, the predefined variant entry (service binding), and the user delta in order. The canonical contributes
+ * ONLY identity (name, stationId, channelNumber, tags, etc.) - its service binding is for the canonical service and would be structurally wrong for any other
+ * service variant. The variant's binding is supplied by the predefined variant entry (typically: discovery-driven channelSelector, service-specific URL,
+ * profile overrides) and the user's stored delta.
+ *
+ * Fields propagate through the delta-overlay kernel so null-means-clear and undefined-means-inherit semantics apply uniformly at every layer.
+ *
+ * Precondition: at least one of predefined or stored must be defined. A variant with no binding source has nothing to resolve; the result would have no URL
+ * and no selector, and downstream consumers would fail at the consumption site. classifyEntry only returns a "variant" classification when at least one
+ * source carries canonicalKey, so the precondition is satisfied by the only in-tree caller (getMergedChannelMap). Other callers must guarantee the same.
+ * @param canonical - The resolved canonical channel. Variant identity inherits from here; canonical binding is intentionally stripped via pickIdentity.
+ * @param predefined - The predefined variant entry, if the key has one. Contributes service-binding fields and any per-variant channelNumber override.
+ * @param stored - The user's stored delta for this variant, if any. Applied last so user edits win over predefined variant fields.
+ * @returns The fully resolved variant.
+ */
+declare function resolveVariant(canonical: ResolvedChannel, predefined: Channel | undefined, stored: StoredChannel | undefined): ResolvedChannel;
+/**
+ * Emits a dangling-canonical warning at most once per (variant, canonical) pair for the lifetime of this process. Called from getMergedChannelMap whenever a
+ * variant references a canonical that is not present in the resolved map.
+ * @param variantKey - The variant key whose canonicalKey points at a missing canonical.
+ * @param canonicalKey - The missing canonical key.
+ */
+declare function warnDanglingCanonical(variantKey: string, canonicalKey: string): void;
+/**
+ * Builds the Pass 1 resolved-canonical map for a given stored map. Iterates every key present in either the predefined catalog or the stored map, resolves
+ * non-variant entries (canonicals and standalones), and returns the resulting ChannelMap. Variants are deliberately skipped - they depend on this map and are
+ * resolved in Pass 2 by the caller.
+ *
+ * This is shared by getMergedChannelMap (which uses the map directly as the starting point for its full resolution) and normalizeChannelDeltas (which uses the
+ * map as a source of bases for diffing variant deltas).
+ * @param stored - The stored channels map.
+ * @returns The resolved-canonical map, keyed by channel key.
+ */
+declare function buildResolvedCanonicals(stored: StoredChannelMap): ResolvedChannelMap;
+/**
+ * Strips null fields from a stored entry. Null is a delta-only convention meaning "clear this field on the base"; without a base to clear against, nulls
+ * have no meaning and get dropped. Used by normalizeChannelDeltas for standalone user channels and for dangling-canonical variants that fall back to
+ * standalone-style normalization.
+ * @param stored - The raw stored entry.
+ * @returns The entry with null-valued fields removed.
+ */
+declare function stripNulls(stored: StoredChannel): StoredChannel;
+/**
+ * Normalizes the stored channels map to its minimal delta form. Each entry is classified, diffed against its applicable base, and any no-op fields are
+ * stripped. Standalone user channels have no base, so nulls are stripped but everything else is preserved.
+ *
+ * The flow is uniform across kinds:
+ *
+ * - Canonical (predefined with user override): base is the predefined channel.
+ * - Variant: base is the resolved canonical layered with the predefined variant's service fields (the view the user sees in the form/table, so the delta
+ *   records only what differs from that).
+ * - Standalone: no base, null values are stripped as a storage convention.
+ *
+ * Entries whose normalized delta is empty collapse to nothing and get dropped - a redundant override carries no information, and resolution falls through to
+ * the default.
+ * @param channels - The raw channel entries to normalize.
+ * @returns The normalized channel map.
+ */
+declare function normalizeChannelDeltas(channels: StoredChannelMap): StoredChannelMap;
+/**
+ * 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.
+ */
+declare function prepareChannelsForWrite(data: ChannelsFileData): unknown;
+/**
+ * Pre-write integrity validator for the channels store. Detects two classes of suspicious mutations:
+ *
+ *   1. Identity-field loss: a stored channel's identity field went from set to undefined without canonical fallback. Catches code that
+ *      accidentally drops user-authored channel data while normalizing or transforming entries.
+ *   2. Metadata wholesale clear: a top-level metadata collection (serviceSelections, tagRegistry.tags, tagRegistry.deletedTags) went from non-empty to empty
+ *      in a single mutation. Catches code that accidentally drops the entire collection (the original bug class - if a future writer or fn regression empties
+ *      one of these, this guard logs loudly even though the change is structurally allowed).
+ *
+ * Both checks are log-only - issues surface as warnings without blocking the write. Genuine wholesale clears (operator clears all selections via UI) are the
+ * rare false-positive case here; in practice those happen via per-entry mutations rather than a single empty assignment.
+ * @param prev - Pre-mutation snapshot of the file data.
+ * @param next - Post-mutation, post-normalize file data.
+ * @returns Issues found, or empty array.
+ */
+declare function validateChannelsIntegrity(prev: ChannelsFileData, next: ChannelsFileData): ValidationIssue[];
 /**
  * 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.
@@ -47,13 +221,38 @@ export declare function getChannelsParseErrorMessage(): string | undefined;
  */
 export declare function readChannels(): Promise<UserChannelsLoadResult>;
 /**
- * Serialized read-modify-write operation on channels.json. The mutation function receives the current StoredChannelMap and modifies it in place. The store
- * handles atomicity, serialization, corruption guard, backup, and metadata injection. Delta normalization is applied after the caller's mutation and before the
- * file write so that the normalized result is available for the post-write cache update.
- * @param fn - Mutation function. Receives current channels. Modify in place; return value is ignored.
- * @throws FileStoreParseError if channels.json contains invalid JSON.
+ * Pre-write integrity guard. Compares the channels map captured immediately after parse against the channels map about to be written, and reports identity
+ * fields that have been silently dropped without a canonical fallback.
+ *
+ * Allowed transitions for any identity field:
+ *   - value -> same value  (no change)
+ *   - value -> different value (legitimate update)
+ *   - value -> null (explicit clear; null is the codebase-wide "clear this field" signal)
+ *   - field absent -> any value (new data)
+ *
+ * Forbidden transition (what this guard catches):
+ *   - value -> undefined / missing  WHERE the canonical (for variants and predefined-overrides) does not provide the same value
+ *
+ * Variant inheritance is honored: stripping a stored field that matches the canonical's value is delta minimization, not data loss, and is allowed. The check
+ * is non-blocking: it surfaces suspicious patterns for operator review without aborting legitimate code paths.
+ * @param before - The channels map captured immediately after parse, before the caller's mutation ran.
+ * @param after - The channels map after the caller's mutation and delta normalization.
+ * @returns A list of "key.field" strings naming each detected silent drop. Empty list means no losses.
+ */
+declare function detectIdentityFieldLoss(before: StoredChannelMap, after: StoredChannelMap): string[];
+/**
+ * Serialized read-modify-write operation on channels.json. The mutation function receives the full file data (channels + serviceSelections + tagRegistry +
+ * framework metadata) and modifies it in place. The store handles atomicity, serialization, corruption guard, backup, schema migrations, and pre-write
+ * integrity validation. Delta normalization is applied to data.channels after the caller's mutation and before the file write so that the normalized result is
+ * available for the post-write cache hydration.
+ *
+ * After a successful write, the in-memory caches that mirror persisted state (loadedUserChannels, loadedTagRegistry, services.ts serviceSelections Map,
+ * runtime service groups) are hydrated from the just-written normalized data. This is the single direction caches flow: data is the source of truth, caches
+ * are derived. Callers must never poke caches directly and rely on a later save to pick up the change - all mutations go through this function.
+ * @param fn - Mutation function. Receives the full file data. Modify in place; return value is ignored.
+ * @throws FileStoreParseError if channels.json contains invalid JSON and the .bak rotation is also unparseable.
  */
-export declare function mutateChannels(fn: (channels: StoredChannelMap) => void): Promise<void>;
+export declare function mutateChannels(fn: (data: ChannelsFileData) => void): Promise<void>;
 /**
  * Deletes a user channel by key.
  * @param key - The channel key to delete.
@@ -61,26 +260,137 @@ export declare function mutateChannels(fn: (channels: StoredChannelMap) => void)
  * @throws If the file cannot be written.
  */
 export declare function deleteUserChannel(key: string): Promise<void>;
+/**
+ * Removes all user override entries for a canonical channel - both the canonical-stored entry and the active service variant's stored entry (when one resolves
+ * via explicit selection or service-filter fallback). Returns the stored entry that was deleted (canonical takes precedence; falls back to the variant entry
+ * when canonical is absent) so callers can compute downstream effects like the playlist reload hint without duplicating the lookup.
+ *
+ * Callers wrap the call in mutateChannels() and pass the resulting StoredChannelMap. The helper operates on the map directly; it does not own the mutation
+ * lifecycle, allowing callers to combine the dual-delete with other operations (e.g., setting serviceSelections) in the same atomic write.
+ * @param channels - The stored channels map to mutate in place.
+ * @param canonicalKey - The canonical channel key. The active variant is resolved internally via resolveServiceKey.
+ * @returns The stored entry that existed pre-deletion (canonical first, variant fallback). Undefined when neither entry existed.
+ */
+export declare function clearChannelOverrides(channels: StoredChannelMap, canonicalKey: string): StoredChannel | undefined;
+/**
+ * Merges a partial ChannelDelta into a stored entry. Returns a new entry with the existing fields preserved and the delta's fields layered on top. Used by
+ * bulk operations that update one or more delta fields across many channels - the helper handles both the "no entry exists yet" case (uses an empty record)
+ * and the "entry exists with prior overrides" case (preserves them) without forcing each call site to write the spread + assign manually.
+ *
+ * The merged entry is returned in StoredChannel shape; callers assign it back to data.channels[key]. The post-mutation normalizer (filterToDeltaSurface +
+ * normalizeEntryAgainstBase) handles delta minimization and shape enforcement, so callers can pass arbitrary ChannelDelta keys without pre-validating them.
+ * @param stored - The existing stored entry, or undefined when the channel has no prior overrides.
+ * @param delta - Fields to assign onto the entry. Null values flow through unchanged for the delta-clear semantic.
+ * @returns The merged stored entry.
+ */
+export declare function applyChannelDelta(stored: StoredChannel | undefined, delta: ChannelDelta): StoredChannel;
 /**
  * Resets all user channels by deleting the channels file.
  * @throws If the file exists but cannot be deleted.
  */
 export declare function resetUserChannels(): Promise<void>;
+/**
+ * Classifies which stored entries are legitimate legacy variants eligible for canonicalKey stamping. A legitimate legacy variant has a hyphenated key whose
+ * prefix matches a predefined canonical AND every stored identity field either is absent or matches the canonical's value. Entries with diverging identity
+ * are user-created standalones that happen to share the hyphenated key shape (e.g., "abc-kabc" as a local affiliate with its own channel number and station
+ * ID) and must be left alone - stamping them would mark them for delta normalization and silently destroy the user's custom identity.
+ *
+ * Array-valued identity fields (tags) compare via JSON.stringify with case-insensitive canonical sorting so historical write order does not defeat the match.
+ * @param channels - The raw stored channel entries.
+ * @returns Keys that should receive a canonicalKey stamp. Empty when nothing needs migrating.
+ */
+declare function collectLegacyVariantStamps(channels: StoredChannelMap): string[];
 /**
  * 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 declare function initializeUserChannels(): Promise<void>;
 /**
- * Resolves a stored channel entry (full definition or delta) into a fully resolved Channel. For user-defined channels with no predefined equivalent, the stored
- * entry is returned as-is (it must be a full Channel). For overrides of predefined channels, the predefined definition is used as a base and only allowlisted
- * delta fields are overlaid. Fields set to null in the delta are removed from the result. Fields not in the allowlist are silently ignored.
- * @param key - The channel key.
- * @param stored - The stored channel data (full definition or delta).
- * @returns A fully resolved Channel with all fields populated.
+ * Extracts the identity-only subset of a channel. Used by resolveVariant and normalizeChannelDeltas to compute the inheritance base for variants: a variant
+ * inherits identity from its canonical but must contribute its own service binding (URL, channelSelector, profile, etc.) - the canonical's binding is for the
+ * canonical service and is structurally wrong for any other service.
+ *
+ * The fields copied are exactly those listed in CHANNEL_IDENTITY_KEYS, the single source of truth for the identity partition. Array-valued fields are shallow-
+ * copied so downstream mutation cannot leak back into the source.
+ * @param channel - The channel to extract identity from. Typed as ResolvedChannel because that is the shape after canonical resolution; CanonicalChannel is
+ *   structurally compatible.
+ * @returns A new ChannelIdentity object with just the identity fields populated.
+ */
+export declare function pickIdentity(channel: ResolvedChannel): ChannelIdentity;
+/**
+ * Overlays a stored channel (full definition or delta) onto a base. Allowlisted delta fields in the stored entry override the base: a null value clears the
+ * field from the resolved object, a defined value replaces it, and missing fields inherit from the base. Non-delta fields on the stored entry (e.g.,
+ * canonicalKey) pass through so the resolved channel retains its relationship metadata. The returned object is a fresh reference with a defensive copy of any
+ * array-valued fields, so callers can mutate it without corrupting the base.
+ *
+ * This is the single delta-overlay kernel used by both predefined overrides and user variants. The base may be:
+ *
+ * - A predefined CanonicalChannel for canonical-override resolution.
+ * - A ChannelIdentity-only intermediate during variant resolution (URL is supplied by the variant binding overlay).
+ * - A fully resolved canonical for variant base computation.
+ *
+ * Internally typed as ResolvedChannel for the input shape; intermediate variant-resolution states pass through a cast because url is required on
+ * ResolvedChannel but is supplied by the next overlay. The contract is: after the full resolveVariant chain, the result has every required field populated.
+ * @param base - The base channel to inherit from.
+ * @param stored - The stored entry (delta) to overlay.
+ * @returns A new ResolvedChannel with the base's fields and the stored entry's overrides applied.
+ */
+declare function overlayDelta(base: ResolvedChannel, stored: StoredChannel): ResolvedChannel;
+/**
+ * Shared overlay kernel used by overlayDelta and overlayVariantBinding. Walks the stored entry's fields and applies them to a clone of base under three rules:
+ * fields in allowedFields apply with delta semantics (null clears, undefined skips, value overrides); non-allowed fields either pass through (delta) or are
+ * silently dropped (variant overlay) per passThroughOthers; canonicalKey is always allowed regardless of the gate so resolved variants retain their relationship
+ * metadata. The kernel exists to keep the two overlays from drifting - identical control flow lived in both call sites before this consolidation.
+ * @param base - The base channel to clone and overlay onto.
+ * @param stored - The stored entry whose fields override the base.
+ * @param options - allowedFields selects which fields apply with delta semantics; passThroughOthers controls whether non-allowed fields flow through or are
+ *   dropped. canonicalKey is always passed through.
+ * @returns A new ResolvedChannel with overlay applied.
+ */
+declare function applyOverlayKernel(base: ResolvedChannel, stored: StoredChannel, options: {
+    allowedFields: ReadonlySet<string>;
+    passThroughOthers: boolean;
+}): ResolvedChannel;
+/**
+ * Variant-binding-only overlay. Like overlayDelta but applies only fields in CHANNEL_BINDING_KEYS - identity fields on the variant entry are silently dropped
+ * during resolution. This enforces the architectural principle that variants are pure tuning data: how to reach the channel via this service. Identity
+ * (channelNumber, hdhrEnabled, tags, name, etc.) is a property of the channel as a whole and lives only on the canonical entry.
+ *
+ * Used by resolveVariant for both predefined-variant and stored-variant overlays. Legacy data, hand-edited files, or future migrations that put identity
+ * fields on variant entries are inert at resolution time - canonical's identity always wins. canonicalKey passes through as relationship metadata so the
+ * resolved variant can still be identified as a variant.
+ *
+ * Null/undefined semantics match overlayDelta: null clears the field; undefined inherits.
+ * @param base - The base channel (typically canonical identity from pickIdentity).
+ * @param stored - The variant entry (predefined or user-stored).
+ * @returns A new ResolvedChannel with binding fields applied from the variant.
  */
-export declare function resolveStoredChannel(key: string, stored: StoredChannel): Channel;
+declare function overlayVariantBinding(base: ResolvedChannel, stored: StoredChannel): ResolvedChannel;
 /**
- * Returns the full channel listing with source classification and enabled status. This is the authoritative merge point for predefined and user channels — all
+ * Resolves a stored channel entry into a fully populated ResolvedChannel. Handles the two non-variant cases:
+ *
+ * 1. Predefined override (key matches a predefined entry): the stored entry is a delta over the predefined canonical definition.
+ * 2. Standalone user channel (no predefined equivalent): the stored entry is already a full channel; a defensive copy is returned so downstream mutations
+ *    cannot leak into loadedUserChannels.
+ *
+ * Variants are resolved by getMergedChannelMap via the layered overlay (canonical identity -> predefined variant binding -> user delta). Callers that need a
+ * resolved variant should read from channelsRef (via getResolvedChannel) rather than calling this function with a variant key.
+ * @param key - The channel key (must not be a variant key).
+ * @param stored - The stored channel data.
+ * @returns A fully resolved channel with identity and binding both populated.
+ */
+export declare function resolveStoredChannel(key: string, stored: StoredChannel): ResolvedChannel;
+/**
+ * Returns the merged channel map (predefined + user) without filtering by enabled status or service variants. Used internally for building service groups.
+ * Resolves deltas into fully populated channels.
+ *
+ * Built from buildResolvedCanonicals (Pass 1: canonicals and standalones) plus a variant pass (Pass 2: layered canonical identity -> predefined variant
+ * binding -> user delta). The dangling-canonical path preserves whatever data exists so the user does not silently lose anything when a canonicalKey points
+ * at a missing entry.
+ * @returns The complete merged channel map.
+ */
+declare function getMergedChannelMap(): ResolvedChannelMap;
+/**
+ * Returns the full channel listing with source classification and enabled status. This is the authoritative merge point for predefined and user channels - all
  * code that needs a merged view of channels should use this function (or getAllChannels() which delegates to it).
  *
  * For each channel key, the source is classified as:
@@ -91,7 +401,7 @@ export declare function resolveStoredChannel(key: string, stored: StoredChannel)
  * The enabled field reflects whether the channel is available for streaming. Predefined-only channels can be disabled via configuration; user and override
  * channels are always enabled.
  *
- * Service variants (non-canonical keys in service groups) are filtered out from this listing — they are accessed via the service selection mechanism instead.
+ * Service variants (non-canonical keys in service groups) are filtered out from this listing - they are accessed via the service selection mechanism instead.
  *
  * Override entries produce a new resolved Channel object (via resolveStoredChannel()), which is a different reference from PREDEFINED_CHANNELS[key]. The service
  * system (services.ts) relies on this reference difference to detect user overrides via isUserOverride(). Predefined-only entries preserve the original reference.
@@ -101,12 +411,73 @@ export declare function resolveStoredChannel(key: string, stored: StoredChannel)
  * @returns Sorted array of channel listing entries.
  */
 export declare function getChannelListing(): ChannelListingEntry[];
+/**
+ * Predicate for "visible" channels - entries that are both enabled and available under the current service filter. This is the single source of truth for what
+ * "visible" means across bulk operations, the playlist, and the merged channel map. Every site that filters the listing by visibility routes through this
+ * predicate so the definition lives in exactly one place.
+ * @param entry - The listing entry to test.
+ * @returns True when the channel is enabled and passes the service filter.
+ */
+export declare function isVisibleChannel(entry: ChannelListingEntry): boolean;
+/**
+ * Returns the subset of getChannelListing() that is enabled and available under the current service filter. Built on top of isVisibleChannel so the visibility
+ * predicate lives in one place.
+ * @returns Listing entries that pass the visibility predicate.
+ */
+export declare function getVisibleChannels(): ChannelListingEntry[];
 /**
  * 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 declare function getAllChannels(): ChannelMap;
+export declare function getAllChannels(): ResolvedChannelMap;
+/**
+ * Returns a copy of the raw stored user channels map - the unresolved entries as they exist in channels.json. Used by the consistency probe to check
+ * cross-store invariants without applying delta resolution. Callers should not rely on the shape for anything beyond key/canonicalKey inspection.
+ * @returns Shallow copy of the loaded user channels.
+ */
+export declare function getStoredUserChannels(): StoredChannelMap;
+/**
+ * Where a customized field's override lives in storage. "canonical" means the override is on the canonical channel's stored entry (typically identity fields
+ * like name, stationId, tags). "variant" means the override is on the active service variant's stored entry (typically binding fields like url,
+ * channelSelector). The form's save handler uses this to route changes to the correct entry; the per-field reset uses it to compute the resetValue from the
+ * matching predefined source.
+ */
+export type CustomizationStoredIn = "canonical" | "variant";
+/**
+ * Per-field customization metadata: where the override is stored and what the field would resolve to if the override were removed (the per-field "reset to
+ * default" value).
+ */
+export interface ChannelCustomizationEntry {
+    resetValue: unknown;
+    storedIn: CustomizationStoredIn;
+}
+/**
+ * Result of getChannelCustomizations. Carries the per-field provenance map and identifies the active service variant (if a non-canonical service is resolved
+ * via explicit selection or service-filter fallback). Callers - the channel edit form's render and save paths - rely on both pieces to display the right
+ * "modified from default" indicators and to route saves to the correct entry.
+ */
+export interface ChannelCustomizations {
+    activeVariantKey: string | undefined;
+    customizations: Map<CustomizableField, ChannelCustomizationEntry>;
+}
+/**
+ * Returns the customization provenance for the given canonical channel. The form layer uses this as the single source of truth for which fields are
+ * customized (instead of comparing resolved values to predefined values, which produces false positives when a non-canonical service is active and the
+ * resolved value legitimately differs from the canonical's predefined value).
+ *
+ * Resolution: for each field present in the user's canonical-stored entry, mark customized with storedIn="canonical" and resetValue from computeResetValue.
+ * For each field present in the active variant's stored entry, mark customized with storedIn="variant" and resetValue from computeResetValue (which handles
+ * variant-inheritance fallback). Variant entries override canonical entries on the same field name because variant resolution overlays the variant's value
+ * last.
+ *
+ * Pass 2 (variant-stored fields) restricts the walked field set via getAllowedFieldsForShape so identity fields encountered on a variant entry are silently
+ * dropped from the customization map, matching the resolver's behavior. The "canonicalKey" field is similarly excluded from both passes - structural metadata,
+ * not user-customizable.
+ * @param canonicalKey - The canonical channel key.
+ * @returns The customization provenance map and the active variant key (when applicable).
+ */
+export declare function getChannelCustomizations(canonicalKey: string): ChannelCustomizations;
 /**
  * Returns the raw stored channel data (without predefined channels). Entries may be full Channel definitions or ChannelDelta overrides.
  * @returns The stored channel map.
@@ -118,10 +489,13 @@ export declare function getUserChannels(): StoredChannelMap;
  */
 export declare function getTagRegistry(): TagRegistry;
 /**
- * Updates the tag registry state in memory. Call saveTagRegistry() after to persist the change.
+ * Persists a new tag registry state. Goes through mutateChannels so the file write, integrity validation, and post-mutate cache hydration all run uniformly -
+ * after the call returns, both disk and module-state cache reflect the new value. The caller's input arrays are not mutated; both are sorted non-destructively
+ * via sortTags so storage shares one canonical ordering.
  * @param registry - The new tag registry state.
+ * @throws FileStoreParseError if channels.json contains invalid JSON and the .bak rotation is also unparseable.
  */
-export declare function setTagRegistry(registry: TagRegistry): void;
+export declare function setTagRegistry(registry: TagRegistry): Promise<void>;
 /**
  * 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
@@ -130,25 +504,43 @@ export declare function setTagRegistry(registry: TagRegistry): void;
  */
 export declare function getActiveTagVocabulary(): string[];
 /**
- * Returns a channel's effective tags — the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
- * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses.
+ * Returns a channel's effective tags - the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
+ * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses. Output preserves the source
+ * order of channel.tags; every write path (sortTags) keeps that source order canonical, so in practice the returned array is sorted.
  * @param channel - The channel to get effective tags for.
- * @returns Sorted array of effective tag strings, or empty array if the channel has no tags or none are in the active vocabulary.
+ * @returns Effective tag strings in source order, or empty array if the channel has no tags or none are in the active vocabulary.
  */
-export declare function getChannelEffectiveTags(channel: Channel): string[];
+export declare function getChannelEffectiveTags(channel: ResolvedChannel): string[];
+/**
+ * Returns whether a channel is effectively included in the HDHomeRun lineup. Codifies the sparse-storage convention that absent or true means included, and only
+ * an explicit `false` means excluded. This is the single source of truth for the convention - every site that needs to ask "is HDHR enabled for this channel?"
+ * routes through this helper rather than reaching for the inline `channel.hdhrEnabled !== false` pattern. Storage-shape inspections that ask a different
+ * question ("did the client send literal false?", "did the user override?") stay inline because they are not asking about effective state.
+ * @param channel - The channel to evaluate.
+ * @returns True when the channel is effectively included in the HDHR lineup.
+ */
+export declare function getEffectiveHdhrEnabled(channel: ResolvedChannel): boolean;
 /**
  * Case-insensitive tag comparison. Tags are freeform strings with preserved casing, but all matching throughout the system is case-insensitive. This function
- * is the single source of truth for that policy — all tag identity checks should use it rather than inline toLowerCase() calls.
+ * is the single source of truth for that policy - all tag identity checks should use it rather than inline toLowerCase() calls.
  * @param a - The first tag.
  * @param b - The second tag.
  * @returns True if the tags match case-insensitively.
  */
 export declare function tagsMatch(a: string, b: string): boolean;
 /**
- * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations — delete, rename, and bulk
+ * Checks whether a tag is present in the active vocabulary under case-insensitive identity. This is the single source of truth for "does this tag exist?"
+ * questions - tag endpoints (create/rename collision, bulk-tags vocabulary check) route through this instead of ad-hoc Set+toLowerCase comparisons so the
+ * case-insensitive policy lives in exactly one place (tagsMatch), not in parallel implementations.
+ * @param tag - The tag to check.
+ * @returns True if the active vocabulary contains a tag matching case-insensitively.
+ */
+export declare function isInVocabulary(tag: string): boolean;
+/**
+ * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations - delete, rename, and bulk
  * toggle all route through this function. The caller provides a filter (which channels to transform) and a transform (how to modify each channel's tags). This
  * function handles loading stored channel data, applying the transform, and saving. Delta normalization in mutateChannels() handles predefined channel
- * delta computation automatically — callers do not need to reason about deltas vs. full definitions.
+ * delta computation automatically - callers do not need to reason about deltas vs. full definitions.
  * @param filter - Predicate selecting which listing entries to transform. Receives each ChannelListingEntry from getChannelListing().
  * @param transform - Pure function mapping a channel's current resolved tags to its new tags. Receives the channel's current tags array (may be empty, ordering
  *   not guaranteed). Must return the desired tags array (may be empty to clear all tags). The returned array is sorted before storage.
@@ -159,11 +551,20 @@ export declare function transformChannelTags(filter: (entry: ChannelListingEntry
     error?: string;
 }>;
 /**
- * Returns the predefined channel definition for a key.
+ * Returns the predefined channel definition for a key as a fully-resolved view. For predefined variant entries (which carry only service-specific fields plus
+ * canonicalKey), overlays the variant's binding onto its predefined canonical so callers receive the resolved view - canonical identity inherited onto the
+ * variant. This matches what the user sees in the form/table and is the correct base for delta-from-predefined computations in crud.ts and channelForm.ts.
+ *
+ * Always returns ResolvedChannel-shaped data: identity fields (name, tags, hdhrEnabled, etc.) are always available, sourced from the canonical when this key is
+ * a variant. CanonicalChannel and VariantChannel both assign structurally to ResolvedChannel since the identity fields are optional in both types.
+ *
+ * Returns undefined when the key is not predefined OR when the catalog is internally inconsistent (variant references a missing canonical). The latter case is
+ * structurally impossible by construction of the flattener, so observing it is a real corruption indicator: the function logs once per offending key and
+ * returns undefined rather than fabricating a half-resolved view that would lie about its identity fields.
  * @param key - The channel key to look up.
- * @returns The predefined channel, or undefined if the key is not predefined.
+ * @returns The resolved predefined channel, or undefined if the key is not predefined or the catalog is inconsistent.
  */
-export declare function getPredefinedChannel(key: string): Channel | undefined;
+export declare function getPredefinedChannel(key: string): ResolvedChannel | undefined;
 /**
  * Checks if a channel key exists in the predefined channels.
  * @param key - The channel key to check.
@@ -215,7 +616,7 @@ export declare function getChannelLogo(channelKey: string): string | undefined;
  */
 export declare function isUserChannel(key: string): boolean;
 /**
- * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config — the user's explicit visibility
+ * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config - the user's explicit visibility
  * intent. Property overrides (HDHR toggle, name change, tag edits) stored as deltas in channels.json are orthogonal and do not affect the enabled/disabled state.
  * @param key - The channel key to check.
  * @returns True if the channel is predefined and disabled.
@@ -226,6 +627,38 @@ export declare function isPredefinedChannelDisabled(key: string): boolean;
  * @returns Array of disabled channel keys.
  */
 export declare function getDisabledPredefinedChannels(): string[];
+/**
+ * Disables one or more predefined channels by adding their keys to the disabledPredefined list in user config. Idempotent.
+ * @param keys - The predefined channel keys to disable. Duplicates within the input array and pre-existing disabled entries are handled idempotently.
+ */
+export declare function disablePredefinedChannels(keys: readonly string[]): Promise<void>;
+/**
+ * Enables one or more predefined channels by removing their keys from the disabledPredefined list in user config. Idempotent.
+ * @param keys - The predefined channel keys to enable. Entries that aren't in the disabled list are ignored.
+ */
+export declare function enablePredefinedChannels(keys: readonly string[]): Promise<void>;
+/**
+ * Persists a partial update of channel-table display preferences (sort field, sort direction, visible columns) to config.json. Only fields present in `prefs`
+ * are written; absent fields are left untouched. The mutate fn copies the new values into data and the runtime CONFIG cache is updated post-write to match.
+ * Single-call replacement for the prior set-then-save pattern, consistent with mutateServiceSelections, mutateEnabledServices, and setTagRegistry.
+ * @param prefs - Subset of display preferences to update.
+ * @throws FileStoreParseError if config.json contains invalid JSON and the .bak rotation is also unparseable.
+ */
+export declare function mutateChannelDisplayPrefs(prefs: {
+    channelSortDirection?: SortDirection;
+    channelSortField?: ChannelSortField;
+    visibleColumns?: readonly string[];
+}): Promise<void>;
+/**
+ * Marks the first-run Service Setup wizard as completed. Writes the flag to runtime CONFIG and persists to config.json in one call - the operation is a single
+ * one-way transition (setupCompleted goes from false/absent to true once, never back), so splitting into set+save would be ceremony without benefit.
+ *
+ * Persistence note: setupCompleted is intentionally absent from CONFIG_METADATA and PRESERVED_FIELDS in userConfig.ts, so filterDefaults strips it from the
+ * on-disk shape during the write below. This is by design - the flag is observably derived from "has the user configured any services or channels" and
+ * initializeUserChannels() re-infers it at startup from that observable state. The mutateConfig call here is a no-op on the file but keeps the runtime
+ * mutation pathway uniform with every other CONFIG.channels writer; the flag survives across restarts via inference, not persistence.
+ */
+export declare function markSetupCompleted(): Promise<void>;
 /**
  * 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.
@@ -321,14 +754,40 @@ export interface ChannelsValidationResult {
  */
 export declare function validateImportedChannels(data: unknown, validProfiles: string[]): ChannelsValidationResult;
 /**
- * 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 declare function saveServiceSelections(): Promise<void>;
-/**
- * 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 declare function saveTagRegistry(): Promise<void>;
+ * Sorts tags case-insensitively using locale-aware comparison. This is the single source of truth for tag ordering. Every write path (parseTagInput, PATCH
+ * handlers, computePredefinedDelta, transformChannelTags, setTagRegistry) routes through this so stored tag arrays share one canonical ordering. The channels
+ * normalizer is a READER of that invariant - it uses sortTags on both sides when comparing a delta's tags against a predefined's tags, making the JSON.stringify
+ * equality check canonical regardless of how either side was originally populated.
+ * @param tags - Any iterable of tag strings (array, Set, generator). Not mutated.
+ * @returns A new array with the same elements in canonical case-insensitive order.
+ */
+export declare function sortTags(tags: Iterable<string>): string[];
+/**
+ * Parses a comma-separated tag input string into a normalized tag array. Trims whitespace, drops empty entries, deduplicates case-sensitively via Set (so
+ * distinct casings survive as distinct tags), then sorts via sortTags so every caller produces identical normalized arrays.
+ * @param raw - The comma-separated tag input from a form field or inline editor. An empty or whitespace-only string returns an empty array.
+ * @returns Sorted, case-sensitively-deduplicated array of trimmed tag strings.
+ */
+export declare function parseTagInput(raw: string): string[];
+export declare const __internalForTests: {
+    applyOverlayKernel: typeof applyOverlayKernel;
+    buildResolvedCanonicals: typeof buildResolvedCanonicals;
+    channelsMigrations: Record<number, Migration<ChannelsFileData>>;
+    classifyEntry: typeof classifyEntry;
+    collectLegacyVariantStamps: typeof collectLegacyVariantStamps;
+    detectIdentityFieldLoss: typeof detectIdentityFieldLoss;
+    filterToDeltaSurface: typeof filterToDeltaSurface;
+    getAllowedFieldsForShape: typeof getAllowedFieldsForShape;
+    getMergedChannelMap: typeof getMergedChannelMap;
+    normalizeChannelDeltas: typeof normalizeChannelDeltas;
+    normalizeEntryAgainstBase: typeof normalizeEntryAgainstBase;
+    overlayDelta: typeof overlayDelta;
+    overlayVariantBinding: typeof overlayVariantBinding;
+    parseChannelsFile: typeof parseChannelsFile;
+    prepareChannelsForWrite: typeof prepareChannelsForWrite;
+    resolveVariant: typeof resolveVariant;
+    stripNulls: typeof stripNulls;
+    validateChannelsIntegrity: typeof validateChannelsIntegrity;
+    warnDanglingCanonical: typeof warnDanglingCanonical;
+};
+export {};