feat: target groups — named groups with per-group selectors and fallback chains (#373)

## Summary

Replaces the flat `targets` array and single top-level `selector` on
aliases with a structured `target_groups` model. Each group has its own
name and selector strategy; the router works through groups in order,
falling back to the next group if all targets in the current group are
unhealthy.

## Changes

### Database
- New `target_groups` column on alias tables (stores group name +
selector as JSON)
- SQLite migration `0036` and PostgreSQL migration `0043`

### Backend
- Config types updated to parse `target_groups` with per-group
selectors; legacy `targets`/`selector` fields auto-migrated on read
- `ConfigRepository` reads/writes the grouped structure from DB
- `Router` iterates groups in priority order, selecting a target within
each group using that group's selector, falling back on empty healthy
set
- `Target` interface exported from `CooldownManager` for use in tests

### Backend Tests
- `target-groups-migration.test.ts`: round-trip DB read/write of grouped
format
- `target-groups.test.ts`: router fallback behaviour across 2 and 3
groups, health filtering, selector strategies per group

### Frontend
- `AliasTargetGroup` interface added to API types; `Alias.targets` →
`Alias.target_groups`
- New `TargetGroupEditor` component: drag-and-drop reordering of groups
and targets (including cross-group moves)
- `AliasTableRow` renders targets nested under their group with group
name and selector as a header
- `Models.tsx` replaces the old flat target list + selector dropdown
with `TargetGroupEditor`
- `useModels` updated for group-indexed toggle/test handlers and import
logic

### Bug fix (in TargetGroupEditor)
Drag event bubbling caused dropping a single target to move *all*
targets from the source group. Fixed by stopping propagation on
target-level drag events so the parent group handler cannot overwrite
the `dataTransfer` payload, and updating the group drop handler to
accept target drops onto empty group space.

### Docs
- `CONFIGURATION.md` updated with `target_groups` schema
- OpenAPI spec updated for new alias structure

Author: mcowger

Dockerfile

@@ -52,7 +52,6 @@ ENV PORT=4000
 ENV LOG_LEVEL=info
 ENV DATA_DIR=/app/data
 ENV DATABASE_URL=sqlite:///app/data/plexus.db
-ENV CONFIG_FILE=/app/config/plexus.yaml
 ENV APP_VERSION=${APP_VERSION}
 # ADMIN_KEY must be provided at runtime (no default for security)
 

GROUPS.md

@@ -0,0 +1,256 @@
+# Target Groups Implementation Plan
+
+## Goal
+Support named, ordered target groups within a model alias, each with its own selector strategy. The dispatcher exhausts all healthy targets in group N before moving to group N+1.
+
+## Non-Goal
+There is NO backward compatibility in the application runtime. After startup, every alias and every target row is in grouped format. Old flat configs are converted exactly once at startup.
+
+---
+
+## 1. Database Schema (additive columns only)
+
+### `modelAliases` table (SQLite + Postgres)
+Add one column:
+- `targetGroups` — JSON array of `{ name: string, selector: string }` objects defining the groups and their order.
+
+### `modelAliasTargets` table (SQLite + Postgres)
+Add one column:
+- `groupName` — text label of the group this target belongs to (e.g. `'subscription'`, `'payg'`).
+
+No new tables. No dropped columns. Migrations auto-generated by CI.
+
+---
+
+## 2. In-Memory Types (`config.ts`)
+
+```ts
+export interface ModelTargetGroup {
+  name: string;
+  selector: 'random' | 'in_order' | 'cost' | 'latency' | 'usage' | 'performance' | 'e2e_performance';
+  targets: ModelTarget[];
+}
+
+export interface ModelConfig {
+  // ... existing fields ...
+  target_groups: ModelTargetGroup[];
+}
+```
+
+`ModelConfigSchema` is updated to accept `target_groups`.
+
+The Zod schema still tolerates old flat payloads (`selector` + `targets`) at the **API boundary only**, so that a PUT/PATCH with the old shape parses. The shape is immediately normalized to `target_groups` inside `ModelConfigSchema.parse()` so that downstream code never sees the flat format.
+
+---
+
+## 3. Startup Migration (one-time, DB-level)
+
+After `ConfigService.initialize()` loads the cache, a new method `ConfigService.migrateLegacyTargetGroups()` runs **once per startup**.
+
+It operates at raw DB row level (no `rowToModelConfig` involvement):
+
+1. SELECT all aliases WHERE `targetGroups IS NULL`
+2. For each legacy alias:
+   - Read its `selector` (fallback `'random'`)
+   - Read all its targets from `modelAliasTargets`
+   - UPDATE alias row: `targetGroups = JSON.stringify([{ name: 'default', selector }])`
+   - UPDATE all its target rows: `groupName = 'default'`
+3. If any rows were touched, `rebuildCache()`
+
+After this runs, **zero aliases in the DB have `targetGroups IS NULL`**.
+
+This is the **only** place in the codebase that understands the old format.
+
+---
+
+## 4. Config Repository (`config-repository.ts`)
+
+### Read path
+`rowToModelConfig` always assumes `targetGroups` is populated. It:
+1. Parses `targetGroups` JSON into group definitions `[{name, selector}]`
+2. Partitions `targetRows` by `groupName`
+3. Builds `ModelTargetGroup[]` in definition order
+
+If `targetGroups` is somehow null (should never happen post-migration), throw a clear error so we know the migration failed.
+
+### Write path
+`saveAlias` always writes the grouped format:
+- `targetGroups` = JSON of `config.target_groups.map(g => ({ name: g.name, selector: g.selector }))`
+- Each target row gets `groupName` set to its group's name
+- `sortOrder` is the index within the group
+
+---
+
+## 5. Router (`router.ts`)
+
+Both `resolve()` and `resolveCandidates()` iterate `alias.target_groups`.
+
+### `resolveCandidates()`
+```
+for each group in alias.target_groups (in order):
+  1. Filter group.targets through existing health checks (enabled, cooldown, type, api_match)
+  2. If no healthy targets, skip to next group
+  3. Enrich targets with modelConfig
+  4. Order within group using group.selector
+  5. Append ordered results to flat candidate list
+return flat list
+```
+
+The Dispatcher already iterates through this flat list. Because group 1 candidates appear first, the Dispatcher naturally exhausts them before trying group 2.
+
+### `resolve()`
+```
+for each group in alias.target_groups (in order):
+  1. Filter group.targets through health checks
+  2. If no healthy targets, skip to next group
+  3. Select one target using group.selector
+  4. Return it immediately
+```
+
+---
+
+## 6. Management API (`routes/management/config.ts`)
+
+No changes. The existing PUT/PATCH handlers pass the body through `ModelConfigSchema.safeParse()`, which normalizes old flat shapes to grouped at parse time.
+
+---
+
+## 7. Frontend API Layer (`frontend/src/lib/api.ts`)
+
+### Type changes
+```ts
+export interface AliasTargetGroup {
+  name: string;
+  selector: string;
+  targets: Array<{ provider: string; model: string; apiType?: string[]; enabled?: boolean }>;
+}
+
+export interface Alias {
+  // ... existing fields ...
+  target_groups: AliasTargetGroup[];
+}
+```
+
+### Read normalization (`getAliases`)
+- If backend response has `target_groups`, use it directly.
+- If backend response has old flat `selector` + `targets` (only possible during rollout window), normalize immediately:
+  ```ts
+  target_groups: [{ name: 'default', selector: val.selector || 'random', targets }]
+  ```
+- TODO comment on the fallback: remove after one release cycle.
+
+### Write serialization (`saveAlias`)
+Always sends the grouped format to the backend:
+```ts
+body.target_groups = alias.target_groups.map(g => ({
+  name: g.name,
+  selector: g.selector,
+  targets: g.targets.map(t => ({ ... }))
+}))
+```
+
+---
+
+## 8. Frontend UI (`frontend/src/pages/Models.tsx`, `AliasTableRow.tsx`, `useModels.ts`)
+
+### Table display (`AliasTableRow.tsx`)
+Instead of a flat list of targets, render targets grouped by `target_groups.name`:
+```
+subscription  [e2e_performance]
+  neuralwatt → zai-org/GLM-5.1-FP8
+  zenmux-sub → z-ai/glm-5.1
+  ...
+
+payg  [cost]
+  kilocode → z-ai/glm-5.1
+  apertis-payg → glm-5.1
+```
+
+### Edit modal (`Models.tsx`)
+- Selector at top level is **removed** from the main form (it lives inside each group now)
+- Target list editor becomes group-aware:
+  - Add/remove/rename groups
+  - Drag targets between groups or within a group
+  - Per-group selector dropdown
+- Auto-add / import features append targets to a user-selected group (defaulting to the first group)
+
+### Hook (`useModels.ts`)
+- `EMPTY_ALIAS` initializes with one default group:
+  ```ts
+  target_groups: [{ name: 'default', selector: 'random', targets: [] }]
+  ```
+- `handleToggleTarget` finds the target within the correct group
+- Import logic appends to the first group by default
+
+---
+
+## 9. Tests
+
+### Backend
+1. **Startup migration test**: verify legacy alias gets `targetGroups='[{"name":"default","selector":"cost"}]'` and targets get `groupName='default'`
+2. **Router tests**: multi-group ordering; group-specific selectors; empty group skipped
+3. **Dispatcher tests**: verify failover exhausts group 1 before group 2
+4. **Repository round-trip**: save grouped alias → reload → identical `target_groups`
+
+### Frontend
+1. **API normalization test**: old flat payload → `target_groups` with `default` group
+2. **UI tests**: group editor renders; drag-and-drop between groups; group selector respected
+
+---
+
+## 10. TODOs for Cleanup
+
+After the migration has run in production for one release cycle, the following temporary paths can be deleted:
+
+1. `ConfigService.migrateLegacyTargetGroups()` — entire method
+2. `rowToModelConfig` null-check on `targetGroups` — remove the throw, keep the happy path
+3. Frontend `getAliases` flat-format fallback — remove the `else` branch
+4. `ModelConfigSchema` flat-shape tolerance — remove `selector` and `targets` from the schema (keep only `target_groups`)
+
+Each TODO will be marked with `TODO(#target-groups-cleanup): remove after migration period`.
+
+---
+
+## 11. Example Config After Migration
+
+### Database state
+```sql
+SELECT slug, target_groups FROM model_aliases WHERE slug = 'glm-5.1';
+-- glm-5.1 | [{"name":"subscription","selector":"e2e_performance"},{"name":"payg","selector":"cost"},{"name":"backup","selector":"in_order"}]
+
+SELECT provider_slug, model_name, group_name FROM model_alias_targets WHERE alias_id = 42;
+-- neuralwatt    | zai-org/GLM-5.1-FP8 | subscription
+-- zenmux-sub    | z-ai/glm-5.1        | subscription
+-- apertis-sub   | glm-5.1             | subscription
+-- llm-gateway   | glm-5.1             | subscription
+-- kilocode      | z-ai/glm-5.1        | payg
+-- apertis-payg  | glm-5.1             | payg
+-- wisgate       | glm-5.1             | backup
+```
+
+### API payload
+```json
+{
+  "target_groups": [
+    {
+      "name": "subscription",
+      "selector": "e2e_performance",
+      "targets": [
+        { "provider": "neuralwatt", "model": "zai-org/GLM-5.1-FP8" },
+        { "provider": "zenmux-sub", "model": "z-ai/glm-5.1" }
+      ]
+    },
+    {
+      "name": "payg",
+      "selector": "cost",
+      "targets": [
+        { "provider": "kilocode", "model": "z-ai/glm-5.1" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+Ready for review. Let me know if you want any changes before I start implementing.

docker-compose.yml

@@ -7,12 +7,10 @@ services:
     ports:
       - "4000:4000"
     volumes:
-      - ./config:/app/config
       - ./data:/app/data
     environment:
       - ADMIN_KEY=${ADMIN_KEY:?ADMIN_KEY is required}
       - DATABASE_URL=${DATABASE_URL:-sqlite:///app/data/plexus.db}
       - ENCRYPTION_KEY=${ENCRYPTION_KEY:-}
       - LOG_LEVEL=info
       - DATA_DIR=/app/data
-      - CONFIG_FILE=/app/config/plexus.yaml