refactor: unify channel config matching and gating

Co-authored-by: thewilloftheshadow <thewilloftheshadow@users.noreply.github.com>

src/channels/channel-config.ts

@@ -1,11 +1,22 @@
+export type ChannelMatchSource = "direct" | "parent" | "wildcard";
+
+export function buildChannelKeyCandidates(
+  ...keys: Array<string | undefined | null>
+): string[] {
 export type ChannelEntryMatch<T> = {
   entry?: T;
   key?: string;
   wildcardEntry?: T;
   wildcardKey?: string;
+  parentEntry?: T;
+  parentKey?: string;
+  matchKey?: string;
+  matchSource?: ChannelMatchSource;
 };
 
-export function buildChannelKeyCandidates(...keys: Array<string | undefined | null>): string[] {
+export function buildChannelKeyCandidates(
+  ...keys: Array<string | undefined | null>
+): string[] {
   const seen = new Set<string>();
   const candidates: string[] = [];
   for (const key of keys) {
@@ -37,3 +48,48 @@ export function resolveChannelEntryMatch<T>(params: {
   }
   return match;
 }
+
+export function resolveChannelEntryMatchWithFallback<T>(params: {
+  entries?: Record<string, T>;
+  keys: string[];
+  parentKeys?: string[];
+  wildcardKey?: string;
+}): ChannelEntryMatch<T> {
+  const direct = resolveChannelEntryMatch({
+    entries: params.entries,
+    keys: params.keys,
+    wildcardKey: params.wildcardKey,
+  });
+
+  if (direct.entry && direct.key) {
+    return { ...direct, matchKey: direct.key, matchSource: "direct" };
+  }
+
+  const parentKeys = params.parentKeys ?? [];
+  if (parentKeys.length > 0) {
+    const parent = resolveChannelEntryMatch({ entries: params.entries, keys: parentKeys });
+    if (parent.entry && parent.key) {
+      return {
+        ...direct,
+        entry: parent.entry,
+        key: parent.key,
+        parentEntry: parent.entry,
+        parentKey: parent.key,
+        matchKey: parent.key,
+        matchSource: "parent",
+      };
+    }
+  }
+
+  if (direct.wildcardEntry && direct.wildcardKey) {
+    return {
+      ...direct,
+      entry: direct.wildcardEntry,
+      key: direct.wildcardKey,
+      matchKey: direct.wildcardKey,
+      matchSource: "wildcard",
+    };
+  }
+
+  return direct;
+}