feat(routing): routing_rules schema + types — M4-001/002/003 (#315)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/db/drizzle/0004_bumpy_miracleman.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "routing_rules" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"priority" integer NOT NULL,
+	"scope" text DEFAULT 'system' NOT NULL,
+	"user_id" text,
+	"conditions" jsonb NOT NULL,
+	"action" jsonb NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "routing_rules" ADD CONSTRAINT "routing_rules_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "routing_rules_scope_priority_idx" ON "routing_rules" USING btree ("scope","priority");--> statement-breakpoint
+CREATE INDEX "routing_rules_user_id_idx" ON "routing_rules" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "routing_rules_enabled_idx" ON "routing_rules" USING btree ("enabled");

packages/db/drizzle/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1773887085247,
       "tag": "0003_p8003_perf_indexes",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1774224004898,
+      "tag": "0004_bumpy_miracleman",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -479,6 +479,66 @@ export const skills = pgTable(
   (t) => [index('skills_enabled_idx').on(t.enabled)],
 );
 
+// ─── Routing Rules ──────────────────────────────────────────────────────────
+
+export const routingRules = pgTable(
+  'routing_rules',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    /** Human-readable rule name */
+    name: text('name').notNull(),
+    /** Lower number = higher priority; unique per scope */
+    priority: integer('priority').notNull(),
+    /** 'system' rules apply globally; 'user' rules are scoped to a specific user */
+    scope: text('scope', { enum: ['system', 'user'] })
+      .notNull()
+      .default('system'),
+    /** Null for system-scoped rules; FK to users.id for user-scoped rules */
+    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }),
+    /** Array of condition objects that must all match for the rule to fire */
+    conditions: jsonb('conditions').notNull().$type<Record<string, unknown>[]>(),
+    /** Routing action to take when all conditions are satisfied */
+    action: jsonb('action').notNull().$type<Record<string, unknown>>(),
+    /** Whether this rule is active */
+    enabled: boolean('enabled').notNull().default(true),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    // Lookup by scope + priority for ordered rule evaluation
+    index('routing_rules_scope_priority_idx').on(t.scope, t.priority),
+    // User-scoped rules lookup
+    index('routing_rules_user_id_idx').on(t.userId),
+    // Filter enabled rules efficiently
+    index('routing_rules_enabled_idx').on(t.enabled),
+  ],
+);
+
+// ─── Provider Credentials ────────────────────────────────────────────────────
+
+export const providerCredentials = pgTable(
+  'provider_credentials',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    provider: text('provider').notNull(),
+    credentialType: text('credential_type', { enum: ['api_key', 'oauth_token'] }).notNull(),
+    encryptedValue: text('encrypted_value').notNull(),
+    refreshToken: text('refresh_token'),
+    expiresAt: timestamp('expires_at', { withTimezone: true }),
+    metadata: jsonb('metadata'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    // Unique constraint: one credential entry per user per provider
+    uniqueIndex('provider_credentials_user_provider_idx').on(t.userId, t.provider),
+    index('provider_credentials_user_id_idx').on(t.userId),
+  ],
+);
+
 // ─── Summarization Jobs ─────────────────────────────────────────────────────
 
 export const summarizationJobs = pgTable(

packages/types/src/routing/index.ts

@@ -1,10 +1,15 @@
-/** Cost tier for model selection */
-export type CostTier = 'cheap' | 'standard' | 'premium';
+// ─── Legacy simple-routing types (kept for backward compatibility) ────────────
 
-/** Task type hint for routing */
-export type TaskType = 'chat' | 'coding' | 'analysis' | 'summarization' | 'general';
+/** Result of a simple scoring-based routing decision */
+export interface RoutingResult {
+  provider: string;
+  modelId: string;
+  modelName: string;
+  score: number;
+  reasoning: string;
+}
 
-/** Routing criteria for model selection */
+/** Routing criteria for score-based model selection */
 export interface RoutingCriteria {
   taskType?: TaskType;
   costTier?: CostTier;
@@ -15,11 +20,115 @@ export interface RoutingCriteria {
   preferredModel?: string;
 }
 
-/** Result of a routing decision */
-export interface RoutingResult {
-  provider: string;
-  modelId: string;
-  modelName: string;
-  score: number;
-  reasoning: string;
+// ─── Classification primitives (M4-002) ──────────────────────────────────────
+
+/** Category of work the agent is being asked to perform */
+export type TaskType =
+  | 'chat'
+  | 'coding'
+  | 'research'
+  | 'summarization'
+  | 'conversation'
+  | 'analysis'
+  | 'creative'
+  | 'general';
+
+/** Estimated complexity of the task, used to bias toward cheaper or more capable models */
+export type Complexity = 'simple' | 'moderate' | 'complex';
+
+/** Primary knowledge domain of the task */
+export type Domain = 'frontend' | 'backend' | 'devops' | 'docs' | 'general';
+
+/**
+ * Cost tier for model selection.
+ * `local` targets self-hosted/on-premises models.
+ */
+export type CostTier = 'cheap' | 'standard' | 'premium' | 'local';
+
+/** Special model capability required by the task */
+export type Capability = 'tools' | 'vision' | 'long-context' | 'reasoning' | 'embedding';
+
+// ─── Condition types (M4-002) ─────────────────────────────────────────────────
+
+/**
+ * A single predicate that must be satisfied for a routing rule to match.
+ *
+ * - `eq`       — scalar equality: `field === value`
+ * - `in`       — set membership: `value` (array) contains `field`
+ * - `includes` — array containment: `field` (array) includes `value`
+ */
+export interface RoutingCondition {
+  /** The task-classification field to test */
+  field: 'taskType' | 'complexity' | 'domain' | 'costTier' | 'requiredCapabilities';
+  /** Comparison operator */
+  operator: 'eq' | 'in' | 'includes';
+  /** Expected value or set of values */
+  value: string | string[];
+}
+
+// ─── Action types (M4-003) ────────────────────────────────────────────────────
+
+/**
+ * The routing action to execute when all conditions in a rule are satisfied.
+ */
+export interface RoutingAction {
+  /** LLM provider identifier, e.g. `'anthropic'`, `'openai'`, `'ollama'` */
+  provider: string;
+  /** Model identifier, e.g. `'claude-opus-4-6'`, `'gpt-4o'` */
+  model: string;
+  /** Optional: use a specific pre-configured agent config from the agent registry */
+  agentConfigId?: string;
+  /** Optional: override the agent's default system prompt for this route */
+  systemPromptOverride?: string;
+  /** Optional: restrict the tool set available to the agent for this route */
+  toolAllowlist?: string[];
+}
+
+/**
+ * Full routing rule as stored in the database and used at runtime.
+ */
+export interface RoutingRule {
+  /** UUID primary key */
+  id: string;
+  /** Human-readable rule name */
+  name: string;
+  /** Lower number = evaluated first; unique per scope */
+  priority: number;
+  /** `'system'` rules apply globally; `'user'` rules override for a specific user */
+  scope: 'system' | 'user';
+  /** Present only for `'user'`-scoped rules */
+  userId?: string;
+  /** All conditions must match for the rule to fire */
+  conditions: RoutingCondition[];
+  /** Action to take when all conditions are met */
+  action: RoutingAction;
+  /** Whether this rule is active */
+  enabled: boolean;
+}
+
+/**
+ * Structured representation of what an agent has been asked to do,
+ * produced by the task classifier and consumed by the routing engine.
+ */
+export interface TaskClassification {
+  taskType: TaskType;
+  complexity: Complexity;
+  domain: Domain;
+  requiredCapabilities: Capability[];
+}
+
+/**
+ * Output of the routing engine — which model to use and why.
+ */
+export interface RoutingDecision {
+  /** LLM provider identifier */
+  provider: string;
+  /** Model identifier */
+  model: string;
+  /** Optional agent config to apply */
+  agentConfigId?: string;
+  /** Name of the rule that matched, for observability */
+  ruleName: string;
+  /** Human-readable explanation of why this rule was selected */
+  reason: string;
 }