Add function to match modem channel number with logical channel name

apis/channels.lua

@@ -108,6 +108,28 @@ function Channels.getBoth(name)
   return { entry.current, entry.target }
 end
 
+--- Check whether a modem channel number matches a logical channel name.
+-- In "current" mode, matches only the legacy channel.
+-- In "target" mode, matches only the new channel.
+-- In "dual" mode, matches EITHER legacy or new channel.
+-- Use this in os.pullEvent("modem_message") handlers for dual-mode safety.
+-- @param name string  Logical channel name (e.g. 'remoteturtle.command')
+-- @param ch number    Incoming modem channel number to test
+-- @return boolean     true if ch is an active channel for this name
+function Channels.match(name, ch)
+  local entry = Channels.registry[name]
+  if not entry then
+    error('Unknown channel: ' .. tostring(name), 2)
+  end
+  if Channels.mode == 'dual' then
+    return ch == entry.current or ch == entry.target
+  elseif Channels.mode == 'target' then
+    return ch == entry.target
+  else
+    return ch == entry.current
+  end
+end
+
 --- Set the channel migration mode.
 -- @param mode string  One of: "current", "target", "dual"
 function Channels.setMode(mode)