Feature/routing flagship implementation

apps/claw-routing-service/src/modules/cost-budget/constants/budget.constants.ts

@@ -0,0 +1,9 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+export const BUDGET_DEFAULT_WARN_AT_PERCENT = 80;
+export const BUDGET_DEFAULT_RESET_INTERVAL_DAYS = 30;
+
+export const BUDGET_MESSAGE_KEY_NEAR_LIMIT = 'BUDGET_NEAR_LIMIT';
+export const BUDGET_MESSAGE_KEY_EXCEEDED_FORCED_LOCAL = 'BUDGET_EXCEEDED_FORCED_LOCAL';
+export const BUDGET_MESSAGE_KEY_EXCEEDED_OVERRIDDEN = 'BUDGET_EXCEEDED_OVERRIDDEN';
+export const BUDGET_MESSAGE_KEY_UNKNOWN_COST_BLOCKED = 'BUDGET_UNKNOWN_COST_BLOCKED';

apps/claw-routing-service/src/modules/cost-budget/controllers/cost-budget.controller.ts

@@ -0,0 +1,45 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { Body, Controller, Get, Param, Patch, Post } from '@nestjs/common';
+
+import { CostBudgetService } from '../services/cost-budget.service';
+
+@Controller('routing/cost-budget')
+export class CostBudgetController {
+  constructor(private readonly service: CostBudgetService) {}
+
+  @Get('me')
+  async getMine(): Promise<unknown> {
+    return this.service.getMine();
+  }
+
+  @Get('me/forecast')
+  async getMineForecast(): Promise<unknown> {
+    return this.service.getMineForecast();
+  }
+
+  @Patch('me')
+  async updateMine(@Body() body: unknown): Promise<unknown> {
+    return this.service.updateMine(body);
+  }
+
+  @Get()
+  async listAll(): Promise<unknown> {
+    return this.service.listAll();
+  }
+
+  @Post()
+  async create(@Body() body: unknown): Promise<unknown> {
+    return this.service.create(body);
+  }
+
+  @Patch(':id')
+  async update(@Param('id') id: string, @Body() body: unknown): Promise<unknown> {
+    return this.service.update(id, body);
+  }
+
+  @Post('check')
+  async check(@Body() body: unknown): Promise<unknown> {
+    return this.service.check(body);
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/cost-budget.module.ts

@@ -0,0 +1,26 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+// NEW module — NOT yet registered in app.module.ts.
+
+import { Module } from '@nestjs/common';
+
+import { CostBudgetController } from './controllers/cost-budget.controller';
+import { BudgetGateManager } from './managers/budget-gate.manager';
+import { BudgetResetManager } from './managers/budget-reset.manager';
+import { BudgetWarningManager } from './managers/budget-warning.manager';
+import { SpendTrackerManager } from './managers/spend-tracker.manager';
+import { UserCostBudgetRepository } from './repositories/user-cost-budget.repository';
+import { CostBudgetService } from './services/cost-budget.service';
+
+@Module({
+  controllers: [CostBudgetController],
+  providers: [
+    CostBudgetService,
+    BudgetGateManager,
+    SpendTrackerManager,
+    BudgetWarningManager,
+    BudgetResetManager,
+    UserCostBudgetRepository,
+  ],
+  exports: [CostBudgetService, BudgetGateManager, SpendTrackerManager],
+})
+export class CostBudgetModule {}

apps/claw-routing-service/src/modules/cost-budget/dto/check-budget.dto.ts

@@ -0,0 +1,11 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { z } from 'zod';
+
+export const checkBudgetSchema = z.object({
+  userId: z.string().min(1).max(200),
+  orgId: z.string().max(200).optional(),
+  estimatedCostUsd: z.number().nonnegative().max(10_000),
+});
+
+export type CheckBudgetDto = z.infer<typeof checkBudgetSchema>;

apps/claw-routing-service/src/modules/cost-budget/dto/create-budget.dto.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { z } from 'zod';
+
+export const createBudgetSchema = z.object({
+  scope: z.enum(['USER', 'ORG']),
+  ownerId: z.string().min(1).max(200),
+  monthlyCapUsd: z.number().positive().max(1_000_000),
+  warnAtPercent: z.number().int().min(1).max(100).default(80),
+  overrideAllowed: z.boolean().default(false),
+});
+
+export type CreateBudgetDto = z.infer<typeof createBudgetSchema>;

apps/claw-routing-service/src/modules/cost-budget/dto/update-budget.dto.ts

@@ -0,0 +1,11 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { z } from 'zod';
+
+export const updateBudgetSchema = z.object({
+  monthlyCapUsd: z.number().positive().max(1_000_000).optional(),
+  warnAtPercent: z.number().int().min(1).max(100).optional(),
+  overrideAllowed: z.boolean().optional(),
+});
+
+export type UpdateBudgetDto = z.infer<typeof updateBudgetSchema>;

apps/claw-routing-service/src/modules/cost-budget/managers/budget-gate.manager.ts

@@ -0,0 +1,18 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+// Pre-routing budget check.
+
+import { Injectable, Logger } from '@nestjs/common';
+
+import type { BudgetCheckInput, BudgetCheckResult } from '../types/budget.types';
+
+@Injectable()
+export class BudgetGateManager {
+  private readonly logger = new Logger(BudgetGateManager.name);
+
+  async check(_input: BudgetCheckInput): Promise<BudgetCheckResult> {
+    this.logger.warn('BudgetGateManager.check: SCAFFOLD only');
+    throw new Error(
+      'SCAFFOLD-R4 — BudgetGateManager.check not implemented; see docs/15-ai-context/routing-flagship-streams/05-r4-cost-budget-intelligence.md',
+    );
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/managers/budget-reset.manager.ts

@@ -0,0 +1,16 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+// Monthly cron — resets every UserCostBudget where resetAt <= now.
+
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+
+@Injectable()
+export class BudgetResetManager {
+  private readonly logger = new Logger(BudgetResetManager.name);
+
+  @Cron(CronExpression.EVERY_HOUR)
+  async tick(): Promise<void> {
+    this.logger.warn('BudgetResetManager.tick: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R4 — BudgetResetManager.tick not implemented');
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/managers/budget-warning.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class BudgetWarningManager {
+  private readonly logger = new Logger(BudgetWarningManager.name);
+
+  async checkAndEmitWarning(_budgetId: string, _currentSpendUsd: number, _capUsd: number): Promise<void> {
+    this.logger.warn('BudgetWarningManager.checkAndEmitWarning: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — BudgetWarningManager.checkAndEmitWarning not implemented');
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/managers/spend-tracker.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class SpendTrackerManager {
+  private readonly logger = new Logger(SpendTrackerManager.name);
+
+  async incrementSpend(_userId: string, _orgId: string | undefined, _amountUsd: number): Promise<void> {
+    this.logger.warn('SpendTrackerManager.incrementSpend: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — SpendTrackerManager.incrementSpend not implemented');
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/repositories/user-cost-budget.repository.ts

@@ -0,0 +1,30 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+// Pure data access — uses PrismaService once UserCostBudget model is added.
+// Per repository rule: NO throws. Return null/empty until implemented.
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class UserCostBudgetRepository {
+  private readonly logger = new Logger(UserCostBudgetRepository.name);
+
+  async findActiveForOwner(_scope: string, _ownerId: string): Promise<unknown | null> {
+    this.logger.warn('UserCostBudgetRepository.findActiveForOwner: SCAFFOLD-R4 returns null');
+    return null;
+  }
+
+  async create(_input: unknown): Promise<unknown | null> {
+    this.logger.warn('UserCostBudgetRepository.create: SCAFFOLD-R4 returns null');
+    return null;
+  }
+
+  async update(_id: string, _input: unknown): Promise<unknown | null> {
+    this.logger.warn('UserCostBudgetRepository.update: SCAFFOLD-R4 returns null');
+    return null;
+  }
+
+  async findExpired(_now: Date): Promise<unknown[]> {
+    this.logger.warn('UserCostBudgetRepository.findExpired: SCAFFOLD-R4 returns empty');
+    return [];
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/services/cost-budget.service.ts

@@ -0,0 +1,37 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class CostBudgetService {
+  private readonly logger = new Logger(CostBudgetService.name);
+
+  async getMine(): Promise<unknown> {
+    this.logger.warn('CostBudgetService.getMine: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.getMine not implemented');
+  }
+  async getMineForecast(): Promise<unknown> {
+    this.logger.warn('CostBudgetService.getMineForecast: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.getMineForecast not implemented');
+  }
+  async updateMine(_body: unknown): Promise<unknown> {
+    this.logger.warn('CostBudgetService.updateMine: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.updateMine not implemented');
+  }
+  async listAll(): Promise<unknown> {
+    this.logger.warn('CostBudgetService.listAll: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.listAll not implemented');
+  }
+  async create(_body: unknown): Promise<unknown> {
+    this.logger.warn('CostBudgetService.create: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.create not implemented');
+  }
+  async update(_id: string, _body: unknown): Promise<unknown> {
+    this.logger.warn('CostBudgetService.update: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.update not implemented');
+  }
+  async check(_body: unknown): Promise<unknown> {
+    this.logger.warn('CostBudgetService.check: SCAFFOLD-R4 only');
+    throw new Error('SCAFFOLD-R4 — CostBudgetService.check not implemented');
+  }
+}

apps/claw-routing-service/src/modules/cost-budget/types/budget.types.ts

@@ -0,0 +1,18 @@
+// SCAFFOLD: stream R.4 (05-r4-cost-budget-intelligence)
+
+export type BudgetScope = 'USER' | 'ORG';
+export type BudgetStatus = 'OK' | 'WARN' | 'EXCEEDED';
+
+export type BudgetCheckInput = {
+  userId: string;
+  orgId?: string;
+  estimatedCostUsd: number;
+};
+
+export type BudgetCheckResult = {
+  status: BudgetStatus;
+  remainingUsd: number;
+  percentOfCap: number;
+  overrideAllowed: boolean;
+  blockingScope?: BudgetScope;
+};

apps/claw-routing-service/src/modules/intelligence/constants/intelligence.constants.ts

@@ -0,0 +1,10 @@
+// SCAFFOLD: stream R.8 (09-r8-advanced-intelligence)
+
+export const PROMPT_LENGTH_HEADROOM_FACTOR = 1.2;
+export const LATENCY_CIRCUIT_ROLLING_WINDOW_MS = 5 * 60 * 1000;
+export const LATENCY_CIRCUIT_MIN_SAMPLES = 20;
+export const MID_STREAM_KILL_GRACE_MS = 500;
+export const CONSENSUS_MIN_MODELS = 3;
+export const CONSENSUS_AGREEMENT_THRESHOLD = 0.7;
+export const COST_QUALITY_SLIDER_DEFAULT = 0.5;
+export const FINE_TUNE_BIAS_WEIGHT_MAX = 0.3;

apps/claw-routing-service/src/modules/intelligence/intelligence.module.ts

@@ -0,0 +1,40 @@
+// SCAFFOLD: stream R.8 (09-r8-advanced-intelligence)
+// Umbrella module for 9 independent sub-features. NOT yet registered.
+
+import { Module } from '@nestjs/common';
+
+import { ConsensusModeManager } from './managers/consensus-mode.manager';
+import { CostQualitySliderManager } from './managers/cost-quality-slider.manager';
+import { EmbeddingRouterManager } from './managers/embedding-router.manager';
+import { FineTunePreferenceManager } from './managers/fine-tune-preference.manager';
+import { LatencyCircuitBreakerManager } from './managers/latency-circuit-breaker.manager';
+import { MidStreamSwitcherManager } from './managers/mid-stream-switcher.manager';
+import { MultiIntentSplitterManager } from './managers/multi-intent-splitter.manager';
+import { PromptLengthGuardManager } from './managers/prompt-length-guard.manager';
+import { RegionRouterManager } from './managers/region-router.manager';
+
+@Module({
+  providers: [
+    PromptLengthGuardManager,
+    LatencyCircuitBreakerManager,
+    MidStreamSwitcherManager,
+    FineTunePreferenceManager,
+    RegionRouterManager,
+    MultiIntentSplitterManager,
+    EmbeddingRouterManager,
+    ConsensusModeManager,
+    CostQualitySliderManager,
+  ],
+  exports: [
+    PromptLengthGuardManager,
+    LatencyCircuitBreakerManager,
+    MidStreamSwitcherManager,
+    FineTunePreferenceManager,
+    RegionRouterManager,
+    MultiIntentSplitterManager,
+    EmbeddingRouterManager,
+    ConsensusModeManager,
+    CostQualitySliderManager,
+  ],
+})
+export class IntelligenceModule {}

apps/claw-routing-service/src/modules/intelligence/managers/consensus-mode.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.8.9.8 (09-r8-advanced-intelligence) — fire 3 models, score agreement
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class ConsensusModeManager {
+  private readonly logger = new Logger(ConsensusModeManager.name);
+
+  apply(_input: unknown): unknown {
+    this.logger.warn('ConsensusModeManager.apply: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R8.9.8 — ConsensusModeManager.apply not implemented; see docs/15-ai-context/routing-flagship-streams/09-r8-advanced-intelligence.md');
+  }
+}

apps/claw-routing-service/src/modules/intelligence/managers/cost-quality-slider.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.8.9.9 (09-r8-advanced-intelligence) — apply user cost/quality slider to scoring weight
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class CostQualitySliderManager {
+  private readonly logger = new Logger(CostQualitySliderManager.name);
+
+  apply(_input: unknown): unknown {
+    this.logger.warn('CostQualitySliderManager.apply: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R8.9.9 — CostQualitySliderManager.apply not implemented; see docs/15-ai-context/routing-flagship-streams/09-r8-advanced-intelligence.md');
+  }
+}

apps/claw-routing-service/src/modules/intelligence/managers/embedding-router.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.8.9.7 (09-r8-advanced-intelligence) — pick embedding-specific model
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class EmbeddingRouterManager {
+  private readonly logger = new Logger(EmbeddingRouterManager.name);
+
+  apply(_input: unknown): unknown {
+    this.logger.warn('EmbeddingRouterManager.apply: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R8.9.7 — EmbeddingRouterManager.apply not implemented; see docs/15-ai-context/routing-flagship-streams/09-r8-advanced-intelligence.md');
+  }
+}

apps/claw-routing-service/src/modules/intelligence/managers/fine-tune-preference.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.8.9.4 (09-r8-advanced-intelligence) — boost user fine-tunes for their domain
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class FineTunePreferenceManager {
+  private readonly logger = new Logger(FineTunePreferenceManager.name);
+
+  apply(_input: unknown): unknown {
+    this.logger.warn('FineTunePreferenceManager.apply: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R8.9.4 — FineTunePreferenceManager.apply not implemented; see docs/15-ai-context/routing-flagship-streams/09-r8-advanced-intelligence.md');
+  }
+}

apps/claw-routing-service/src/modules/intelligence/managers/latency-circuit-breaker.manager.ts

@@ -0,0 +1,13 @@
+// SCAFFOLD: stream R.8.9.2 (09-r8-advanced-intelligence) — open circuit when p95 latency exceeds threshold
+
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class LatencyCircuitBreakerManager {
+  private readonly logger = new Logger(LatencyCircuitBreakerManager.name);
+
+  apply(_input: unknown): unknown {
+    this.logger.warn('LatencyCircuitBreakerManager.apply: SCAFFOLD only');
+    throw new Error('SCAFFOLD-R8.9.2 — LatencyCircuitBreakerManager.apply not implemented; see docs/15-ai-context/routing-flagship-streams/09-r8-advanced-intelligence.md');
+  }
+}