refactor(channels): extract channel bindings from configs into dedicated channels table

New `channels` table with explicit fields (type, account_id, user_id,
agent_id, bot_token, base_url, etc.) replacing the overloaded configs
rows where kind='channel'. UNIQUE(type, account_id) enforces one-bot-
one-agent at the DB level.

Strategy: dual-write + fallback-read for zero-downtime migration.
- All writes go to both tables (configs + channels)
- Reads prefer channels table, fall back to configs
- Auto-migration copies existing configs channel rows on startup
- Old configs rows preserved for rollback safety

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: idoubi

cmd/fastclaw/main.go

@@ -71,6 +71,11 @@ func (a *apiResolver) RegisterChannelFromConfig(rec store.ConfigRecord) error {
 	return a.gw.RegisterChannelFromConfig(rec)
 }
 
+// RegisterChannel hot-starts a freshly-saved ChannelRecord.
+func (a *apiResolver) RegisterChannel(rec store.ChannelRecord) error {
+	return a.gw.RegisterChannel(rec)
+}
+
 func (a *apiResolver) UnregisterChannel(channelType, accountID string) {
 	a.gw.UnregisterChannel(channelType, accountID)
 }

internal/gateway/channels.go

@@ -59,6 +59,62 @@ func registerChannelInstance(rec store.ConfigRecord, mb *bus.MessageBus, chanMgr
 	return nil
 }
 
+// registerChannelFromRecord starts a channel adapter from a ChannelRecord.
+// This is the new-table equivalent of registerChannelInstance.
+func registerChannelFromRecord(rec store.ChannelRecord, mb *bus.MessageBus, chanMgr *channels.Manager, st store.Store, hot bool) error {
+	cc := decodeChannelFromRecord(rec)
+	switch rec.Type {
+	case "telegram":
+		return registerTelegramChannels(cc, mb, chanMgr, hot)
+	case "discord":
+		return registerDiscordChannels(cc, mb, chanMgr, hot)
+	case "slack":
+		return registerSlackChannels(cc, mb, chanMgr, hot)
+	case "line":
+		return registerLINEChannels(cc, mb, chanMgr, hot)
+	case "wechat":
+		cfgRec := channelRecordToConfigRecord(rec)
+		return registerWeChatChannels(cfgRec, cc, mb, chanMgr, st, hot)
+	case "feishu":
+		return registerFeishuChannels(cc, mb, chanMgr, hot)
+	}
+	return nil
+}
+
+// channelRecordToConfigRecord builds a ConfigRecord from a ChannelRecord
+// for backward compatibility with registerWeChatChannels which needs
+// the ConfigRecord shape for its on-expired callback.
+func channelRecordToConfigRecord(ch store.ChannelRecord) store.ConfigRecord {
+	return store.ConfigRecord{
+		ID:            ch.ID,
+		Kind:          store.KindChannel,
+		UserID:        ch.UserID,
+		AgentID:       ch.AgentID,
+		Name:          ch.Type,
+		Enabled:       ch.Enabled,
+		CredentialKey: ch.AccountID,
+		Data:          ch.Data,
+		CreatedAt:     ch.CreatedAt,
+		UpdatedAt:     ch.UpdatedAt,
+	}
+}
+
+// decodeChannelFromRecord converts a ChannelRecord into a ChannelConfig.
+// It reads from both the top-level fields and the Data JSON blob.
+func decodeChannelFromRecord(rec store.ChannelRecord) config.ChannelConfig {
+	cc := config.ChannelConfig{Enabled: rec.Enabled}
+	// First, decode from the Data blob (preserves the Accounts map, etc.)
+	if blob, err := json.Marshal(rec.Data); err == nil && len(blob) > 0 {
+		_ = json.Unmarshal(blob, &cc)
+	}
+	cc.Enabled = rec.Enabled
+	// Override BotToken from top-level field when present.
+	if rec.BotToken != "" {
+		cc.BotToken = rec.BotToken
+	}
+	return cc
+}
+
 // register adds an adapter to the manager via the appropriate path
 // (boot-time Register vs hot RegisterAndStart). Keeps the per-channel
 // case branches tidy.

internal/gateway/gateway.go

@@ -744,14 +744,34 @@ const (
 	NSBindings       = "bindings"
 )
 
-// registerChannelsFromStore loads every enabled kind="channel" row from
-// configs and starts a channel adapter for each, regardless of
-// scope. The owner is captured per-row and resolved at message receipt
-// time via LookupChannelByCredential.
+// registerChannelsFromStore loads every enabled channel from the
+// channels table and starts a channel adapter for each. Falls back
+// to configs (kind='channel') when the channels table is empty (pre-
+// migration installs). The owner is captured per-row and resolved at
+// message receipt time via LookupChannel / LookupChannelByCredential.
 func registerChannelsFromStore(st store.Store, mb *bus.MessageBus, chanMgr *channels.Manager) error {
 	if st == nil {
 		return nil
 	}
+	// Try the new channels table first.
+	chRows, err := st.ListAllChannels(context.Background())
+	if err != nil {
+		slog.Warn("ListAllChannels failed, falling back to configs", "error", err)
+		chRows = nil
+	}
+	if len(chRows) > 0 {
+		for _, r := range chRows {
+			if !r.Enabled {
+				continue
+			}
+			if err := registerChannelFromRecord(r, mb, chanMgr, st, false); err != nil {
+				slog.Warn("register channel failed",
+					"type", r.Type, "user_id", r.UserID, "agent_id", r.AgentID, "error", err)
+			}
+		}
+		return nil
+	}
+	// Fallback: read from configs for pre-migration installs.
 	rows, err := allChannelRows(st)
 	if err != nil {
 		return err

internal/gateway/reload.go

@@ -73,6 +73,15 @@ func (g *Gateway) RegisterChannelFromConfig(rec store.ConfigRecord) error {
 	return registerChannelInstance(rec, g.bus, g.chanMgr, g.store, true)
 }
 
+// RegisterChannel hot-starts a channel adapter from a ChannelRecord.
+// New-table equivalent of RegisterChannelFromConfig.
+func (g *Gateway) RegisterChannel(rec store.ChannelRecord) error {
+	if g.chanMgr == nil || g.bus == nil {
+		return nil
+	}
+	return registerChannelFromRecord(rec, g.bus, g.chanMgr, g.store, true)
+}
+
 // UnregisterChannel removes a channel from the routing table. Note:
 // the bot's polling goroutine is left to die when the root ctx ends —
 // see channels.Manager.Unregister for why. Inbound messages stop

internal/gateway/routing.go

@@ -92,18 +92,32 @@ func (g *Gateway) resolveChannelOwner(ctx context.Context, msg bus.InboundMessag
 	if g.store == nil {
 		return ""
 	}
+	// Try the new channels table first.
+	if ch, err := g.store.LookupChannel(ctx, msg.Channel, msg.AccountID); err == nil && ch != nil {
+		if ch.UserID != "" {
+			return ch.UserID
+		}
+		if ch.AgentID != "" {
+			all, err := g.store.ListAllAgents(ctx)
+			if err != nil {
+				return ""
+			}
+			for _, ar := range all {
+				if ar.ID == ch.AgentID {
+					return ar.UserID
+				}
+			}
+		}
+		return ""
+	}
+	// Fallback: legacy configs table lookup.
 	rec, err := g.store.LookupChannelByCredential(ctx, msg.Channel, msg.AccountID)
 	if err != nil {
 		if !errors.Is(err, store.ErrNotFound) {
 			slog.Warn("channel lookup failed", "channel", msg.Channel, "error", err)
 		}
 		return ""
 	}
-	// channel rows now carry user_id directly — the binder, not the
-	// agent owner indirection. The previous "scope=agent → look up
-	// agent.user_id" branch is gone because every channel row written
-	// by handleConnect* persists the resolved user_id (owner or
-	// non-owner) at insert time.
 	if rec.UserID != "" {
 		return rec.UserID
 	}

internal/gateway/userspace.go

@@ -1097,8 +1097,41 @@ func bindingsFromChannelRows(ctx context.Context, st store.Store, userID string,
 	}
 	var out []config.Binding
 	covered := make(map[string]bool, len(agents))
+
+	// Try the new channels table first — build bindings from ChannelRecords.
+	hasNewRows := false
 	for _, ar := range agents {
 		covered[ar.ID] = true
+		if chRows, err := st.ListChannels(ctx, "", ar.ID); err == nil && len(chRows) > 0 {
+			hasNewRows = true
+			out = append(out, expandChannelRecordBindings(chRows, ar.ID)...)
+		}
+		if userID != "" {
+			if chRows, err := st.ListChannels(ctx, userID, ar.ID); err == nil && len(chRows) > 0 {
+				hasNewRows = true
+				out = append(out, expandChannelRecordBindings(chRows, ar.ID)...)
+			}
+		}
+	}
+	// Reverse-lookup from the new table: any channel this user bound
+	// to an agent they don't own.
+	if userID != "" {
+		if allUserCh, err := st.ListAllChannels(ctx); err == nil {
+			for _, ch := range allUserCh {
+				if ch.UserID != userID || ch.AgentID == "" || covered[ch.AgentID] {
+					continue
+				}
+				hasNewRows = true
+				out = append(out, expandChannelRecordBindings([]store.ChannelRecord{ch}, ch.AgentID)...)
+			}
+		}
+	}
+	if hasNewRows {
+		return out
+	}
+
+	// Fallback: read from configs for pre-migration installs.
+	for _, ar := range agents {
 		rows, err := st.ListConfigs(ctx, store.KindChannel, "", ar.ID)
 		if err == nil {
 			out = append(out, expandChannelBindings(rows, ar.ID)...)
@@ -1127,6 +1160,37 @@ func bindingsFromChannelRows(ctx context.Context, st store.Store, userID string,
 	return out
 }
 
+// expandChannelRecordBindings builds Binding entries from ChannelRecord rows.
+func expandChannelRecordBindings(rows []store.ChannelRecord, agentID string) []config.Binding {
+	var out []config.Binding
+	for _, r := range rows {
+		if !r.Enabled {
+			continue
+		}
+		cc := config.ChannelConfig{}
+		if blob, err := json.Marshal(r.Data); err == nil {
+			_ = json.Unmarshal(blob, &cc)
+		}
+		// Each ChannelRecord is one (type, account_id) — but the Data
+		// blob may still carry an Accounts map from the migration. Use
+		// the top-level AccountID as the primary binding key.
+		if len(cc.Accounts) == 0 {
+			out = append(out, config.Binding{
+				AgentID: agentID,
+				Match:   config.Match{Channel: r.Type, AccountID: r.AccountID},
+			})
+			continue
+		}
+		for accountID := range cc.Accounts {
+			out = append(out, config.Binding{
+				AgentID: agentID,
+				Match:   config.Match{Channel: r.Type, AccountID: accountID},
+			})
+		}
+	}
+	return out
+}
+
 func expandChannelBindings(rows []store.ConfigRecord, agentID string) []config.Binding {
 	var out []config.Binding
 	for _, r := range rows {