@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/services/core-ai-budget.service.ts

@@ -0,0 +1,297 @@
+import { HttpException, HttpStatus, Inject, Injectable } from '@nestjs/common';
+import { InjectConnection, InjectModel } from '@nestjs/mongoose';
+import { Connection, Model } from 'mongoose';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { ErrorCode } from '../../error-code';
+import { CoreAiBudgetLimitCreateInput } from '../inputs/core-ai-budget-limit-create.input';
+import { CoreAiBudgetLimitInput } from '../inputs/core-ai-budget-limit.input';
+import { AiBudgetLimitDocument, CoreAiBudgetLimit } from '../models/core-ai-budget-limit.model';
+import { CoreAiBudgetSummary, CoreAiUsageInfo, CoreAiUsageScope } from '../models/core-ai-usage-info.model';
+
+/** Mongoose injection token for the budget-limit model. */
+export const AI_BUDGET_LIMIT_MODEL = 'AiBudgetLimit';
+/** DI token for the budget-limit model constructor. */
+export const AI_BUDGET_LIMIT_CLASS = 'AI_BUDGET_LIMIT_CLASS';
+
+/** Resolved effective limit for a scope. */
+export interface ResolvedAiBudgetLimit {
+  maxPrompts?: number;
+  maxTokens?: number;
+  period: string;
+}
+
+/** Usage counters for a scope in the current period. */
+export interface AiBudgetUsage {
+  resetAt: Date | null;
+  usedPrompts: number;
+  usedTokens: number;
+}
+
+/**
+ * Token/prompt budget service.
+ *
+ * - Admin CRUD of per-user / per-tenant limit overrides (`aiBudgetLimits`).
+ * - {@link resolveLimit}: override → config default (`ai.budget.user|tenant`) → unlimited.
+ * - {@link getUsage}: period usage via a read-only native count over `aiInteractions`.
+ * - {@link assertWithinBudget}: blocks a run (HTTP 429) when a finite limit is hit.
+ * - {@link getUsageInfo} / {@link buildSummary}: usage reporting for clients.
+ *
+ * All internal limits are optional — a missing/0 limit means unlimited (only the
+ * LLM's own limit then applies).
+ */
+@Injectable()
+export class CoreAiBudgetService extends CrudService<
+  CoreAiBudgetLimit,
+  CoreAiBudgetLimitCreateInput,
+  CoreAiBudgetLimitInput
+> {
+  /** Collection holding per-run usage records (written by the audit service). */
+  protected readonly interactionsCollection = 'aiInteractions';
+
+  constructor(
+    @InjectConnection() protected readonly connection: Connection,
+    @InjectModel(AI_BUDGET_LIMIT_MODEL) protected override readonly mainDbModel: Model<AiBudgetLimitDocument>,
+    @Inject(AI_BUDGET_LIMIT_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiBudgetLimit>,
+  ) {
+    super();
+  }
+
+  /**
+   * Resolve the effective limit for a scope: persisted override, else config default.
+   */
+  async resolveLimit(scope: 'tenant' | 'user', refId: string): Promise<ResolvedAiBudgetLimit> {
+    const override = await this.mainDbModel.findOne({ refId, scope }).lean().exec();
+    const cfg = ConfigService.get<{
+      period?: string;
+      tenant?: { maxPrompts?: number; maxTokens?: number };
+      user?: { maxPrompts?: number; maxTokens?: number };
+    }>('ai.budget');
+    const defaults = scope === 'tenant' ? cfg?.tenant : cfg?.user;
+    return {
+      maxPrompts: override?.maxPrompts ?? defaults?.maxPrompts,
+      maxTokens: override?.maxTokens ?? defaults?.maxTokens,
+      period: override?.period || cfg?.period || 'day',
+    };
+  }
+
+  /**
+   * Count usage (prompts + tokens) for a scope in the current period.
+   * Read-only native count over `aiInteractions` (allowed; bypasses tenant auto-scope
+   * so explicit user/tenant filters are honored).
+   */
+  async getUsage(filter: { tenantId?: string; userId?: string }, period: string): Promise<AiBudgetUsage> {
+    const periodStart = this.periodStart(period);
+    const match: Record<string, any> = { createdAt: { $gte: periodStart } };
+    if (filter.userId) {
+      match.userId = filter.userId;
+    }
+    if (filter.tenantId) {
+      match.tenantId = filter.tenantId;
+    }
+    const db = this.connection.db;
+    if (!db) {
+      return { resetAt: this.nextReset(period), usedPrompts: 0, usedTokens: 0 };
+    }
+    // Sum prompts + tokens server-side via aggregation so only the aggregate crosses
+    // the wire (a per-prompt `.find().toArray()` would load every interaction doc into
+    // the Node heap). Backed by the `{ userId|tenantId, createdAt }` compound indexes.
+    const [agg] = await db
+      .collection(this.interactionsCollection)
+      .aggregate<{ usedPrompts: number; usedTokens: number }>([
+        { $match: match },
+        { $group: { _id: null, usedPrompts: { $sum: 1 }, usedTokens: { $sum: { $ifNull: ['$totalTokens', 0] } } } },
+      ])
+      .toArray();
+    return { resetAt: this.nextReset(period), usedPrompts: agg?.usedPrompts ?? 0, usedTokens: agg?.usedTokens ?? 0 };
+  }
+
+  /**
+   * Block the run with HTTP 429 if the user OR tenant has hit a finite limit.
+   *
+   * @param language Deprecated and unused — the error-code translation layer now
+   *   localizes the 429 message. Kept for call-site backward compatibility.
+   */
+  async assertWithinBudget(userId?: string, tenantId?: string, language?: string): Promise<void> {
+    for (const [scope, refId] of [
+      ['user', userId],
+      ['tenant', tenantId],
+    ] as const) {
+      if (!refId) {
+        continue;
+      }
+      const limit = await this.resolveLimit(scope, refId);
+      if (!this.finite(limit.maxTokens) && !this.finite(limit.maxPrompts)) {
+        continue; // unlimited
+      }
+      const usage = await this.getUsage(scope === 'user' ? { userId: refId } : { tenantId: refId }, limit.period);
+      if (this.exceeded(usage, limit)) {
+        // Message is translated (de/en) by the error-code translation layer.
+        void language;
+        throw new HttpException(ErrorCode.AI_BUDGET_EXCEEDED, HttpStatus.TOO_MANY_REQUESTS);
+      }
+    }
+  }
+
+  /**
+   * Full usage info for the current user (and tenant when present).
+   */
+  async getUsageInfo(userId?: string, tenantId?: string): Promise<CoreAiUsageInfo> {
+    const info = new CoreAiUsageInfo();
+    if (userId) {
+      info.user = await this.buildScope('user', userId);
+    }
+    if (tenantId) {
+      info.tenant = await this.buildScope('tenant', tenantId);
+    }
+    return info;
+  }
+
+  /**
+   * Compact per-response summary for the user scope.
+   */
+  async buildSummary(
+    userId: string | undefined,
+    tenantId: string | undefined,
+    promptTokens: number,
+    llmContextWindow?: number,
+    providerQuota?: { maxTokens?: number; period?: string },
+  ): Promise<CoreAiBudgetSummary> {
+    const summary = new CoreAiBudgetSummary();
+    summary.promptTokens = promptTokens;
+    if (!userId) {
+      // No user → only the LLM context window can be reported as a coarse signal.
+      if (this.finite(llmContextWindow)) {
+        summary.maxTokens = llmContextWindow;
+        summary.scope = 'llm';
+      }
+      return summary;
+    }
+
+    // 1) User-scope hard limit (DB override → config default).
+    const userLimit = await this.resolveLimit('user', userId);
+    if (this.finite(userLimit.maxTokens) || this.finite(userLimit.maxPrompts)) {
+      const usage = await this.getUsage({ userId }, userLimit.period);
+      summary.usedTokens = usage.usedTokens;
+      summary.remainingTokens = this.finite(userLimit.maxTokens)
+        ? Math.max(0, (userLimit.maxTokens as number) - usage.usedTokens)
+        : undefined;
+      summary.resetAt = usage.resetAt ?? undefined;
+      if (this.finite(userLimit.maxTokens)) {
+        summary.maxTokens = userLimit.maxTokens;
+        summary.scope = 'user';
+      }
+      return summary;
+    }
+
+    // 2) Tenant-scope hard limit.
+    if (tenantId) {
+      const tenantLimit = await this.resolveLimit('tenant', tenantId);
+      if (this.finite(tenantLimit.maxTokens)) {
+        const usage = await this.getUsage({ tenantId }, tenantLimit.period);
+        summary.usedTokens = usage.usedTokens;
+        summary.remainingTokens = Math.max(0, (tenantLimit.maxTokens as number) - usage.usedTokens);
+        summary.resetAt = usage.resetAt ?? undefined;
+        summary.maxTokens = tenantLimit.maxTokens;
+        summary.scope = 'tenant';
+        return summary;
+      }
+    }
+
+    // No hard limit configured for this user / tenant. Still report the running
+    // CUMULATIVE user usage over the default period so the UI can show a
+    // running counter (and a soft bar when a fallback maxTokens exists).
+    const period = providerQuota?.period || userLimit.period;
+    const usage = await this.getUsage({ userId }, period);
+    summary.usedTokens = usage.usedTokens;
+    summary.resetAt = usage.resetAt ?? undefined;
+
+    // 3) Provider-quota soft default — auto-derived from the active connection
+    // (the admin pins it per connection; the bar shows it as scope='llm'
+    // because it's a provider hint, not a per-user hard limit).
+    if (this.finite(providerQuota?.maxTokens)) {
+      summary.maxTokens = providerQuota!.maxTokens;
+      summary.remainingTokens = Math.max(0, (providerQuota!.maxTokens as number) - usage.usedTokens);
+      summary.scope = 'llm';
+      return summary;
+    }
+
+    // 4) Last-resort soft default — the LLM context window. Coarse but
+    // better than rendering nothing.
+    if (this.finite(llmContextWindow)) {
+      summary.maxTokens = llmContextWindow;
+      summary.scope = 'llm';
+    }
+    return summary;
+  }
+
+  // ===================================================================================================================
+  // Helpers
+  // ===================================================================================================================
+
+  protected async buildScope(scope: 'tenant' | 'user', refId: string): Promise<CoreAiUsageScope> {
+    const limit = await this.resolveLimit(scope, refId);
+    const usage = await this.getUsage(scope === 'user' ? { userId: refId } : { tenantId: refId }, limit.period);
+    const result = new CoreAiUsageScope();
+    result.maxPrompts = this.finite(limit.maxPrompts) ? limit.maxPrompts : undefined;
+    result.maxTokens = this.finite(limit.maxTokens) ? limit.maxTokens : undefined;
+    result.period = limit.period;
+    result.refId = refId;
+    result.remainingPrompts = this.finite(limit.maxPrompts)
+      ? Math.max(0, (limit.maxPrompts as number) - usage.usedPrompts)
+      : undefined;
+    result.remainingTokens = this.finite(limit.maxTokens)
+      ? Math.max(0, (limit.maxTokens as number) - usage.usedTokens)
+      : undefined;
+    result.resetAt = usage.resetAt ?? undefined;
+    result.scope = scope;
+    result.usedPrompts = usage.usedPrompts;
+    result.usedTokens = usage.usedTokens;
+    return result;
+  }
+
+  /** A limit value is "finite" (enforced) only when it is a positive number. */
+  protected finite(value?: number): boolean {
+    return typeof value === 'number' && value > 0;
+  }
+
+  protected exceeded(usage: AiBudgetUsage, limit: ResolvedAiBudgetLimit): boolean {
+    return (
+      (this.finite(limit.maxTokens) && usage.usedTokens >= (limit.maxTokens as number)) ||
+      (this.finite(limit.maxPrompts) && usage.usedPrompts >= (limit.maxPrompts as number))
+    );
+  }
+
+  /** Start of the current period. */
+  protected periodStart(period: string): Date {
+    const now = new Date();
+    if (period === 'month') {
+      return new Date(now.getFullYear(), now.getMonth(), 1, 0, 0, 0, 0);
+    }
+    if (period === 'none') {
+      return new Date(0);
+    }
+    // 'day' (default)
+    const start = new Date(now);
+    start.setHours(0, 0, 0, 0);
+    return start;
+  }
+
+  /** Next reset boundary (null for 'none'). */
+  protected nextReset(period: string): Date | null {
+    const now = new Date();
+    if (period === 'month') {
+      return new Date(now.getFullYear(), now.getMonth() + 1, 1, 0, 0, 0, 0);
+    }
+    if (period === 'none') {
+      return null;
+    }
+    const next = new Date(now);
+    next.setHours(0, 0, 0, 0);
+    next.setDate(next.getDate() + 1);
+    return next;
+  }
+}

package/src/core/modules/ai/services/core-ai-connection-preference.service.ts

@@ -0,0 +1,74 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { CoreAiConnectionPreferenceInput } from '../inputs/core-ai-connection-preference.input';
+import {
+  AiConnectionPreferenceDocument,
+  CoreAiConnectionPreference,
+} from '../models/core-ai-connection-preference.model';
+
+/** Mongoose injection token for the connection-preference model. */
+export const AI_CONNECTION_PREFERENCE_MODEL = 'AiConnectionPreference';
+/** DI token for the connection-preference model constructor. */
+export const AI_CONNECTION_PREFERENCE_CLASS = 'AI_CONNECTION_PREFERENCE_CLASS';
+
+/**
+ * CRUD + lookup for {@link CoreAiConnectionPreference} (tenant/user connection
+ * defaults + tenant-enforced). Used by the resolution chain.
+ */
+@Injectable()
+export class CoreAiConnectionPreferenceService extends CrudService<
+  CoreAiConnectionPreference,
+  CoreAiConnectionPreferenceInput,
+  CoreAiConnectionPreferenceInput
+> {
+  constructor(
+    @InjectModel(AI_CONNECTION_PREFERENCE_MODEL)
+    protected override readonly mainDbModel: Model<AiConnectionPreferenceDocument>,
+    @Inject(AI_CONNECTION_PREFERENCE_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiConnectionPreference>,
+  ) {
+    super();
+  }
+
+  /**
+   * Read a preference for a scope/ref (system-internal lean read).
+   */
+  async getPreference(
+    scope: 'tenant' | 'user',
+    refId: string,
+  ): Promise<{ connectionId: string; enforced?: boolean } | null> {
+    const doc = await this.mainDbModel.findOne({ refId, scope }).lean().exec();
+    return doc ? { connectionId: doc.connectionId, enforced: doc.enforced } : null;
+  }
+
+  /**
+   * Delete all preferences pointing to a connection (used when a connection is
+   * removed, to avoid dangling tenant/user preferences). Returns the deleted count.
+   */
+  async deleteByConnectionId(connectionId: string): Promise<number> {
+    const result = await this.mainDbModel.deleteMany({ connectionId }).exec();
+    return result.deletedCount ?? 0;
+  }
+
+  /**
+   * Upsert a preference (one per scope/ref). System-internal; callers must
+   * authorize the scope/ref (e.g. a user may only set their own user preference).
+   * Returns the persisted preference as a mapped model.
+   */
+  async upsertPreference(
+    scope: 'tenant' | 'user',
+    refId: string,
+    connectionId: string,
+    enforced = false,
+  ): Promise<CoreAiConnectionPreference> {
+    const doc = await this.mainDbModel
+      .findOneAndUpdate({ refId, scope }, { $set: { connectionId, enforced } }, { new: true, upsert: true })
+      .lean()
+      .exec();
+    return this.mainModelConstructor.map(doc);
+  }
+}

package/src/core/modules/ai/services/core-ai-connection-resolver.service.ts

@@ -0,0 +1,308 @@
+import { ForbiddenException, Injectable, Logger, NotFoundException, Optional } from '@nestjs/common';
+
+import { ErrorCode } from '../../error-code';
+import { ResolvedAiConnection } from '../interfaces/resolved-ai-connection.interface';
+import { CoreAiAvailableConnection } from '../models/core-ai-available-connection.model';
+import { CoreAiConnectionPreference } from '../models/core-ai-connection-preference.model';
+import { CoreAiConnectionPreferenceService } from './core-ai-connection-preference.service';
+import { CoreAiConnectionService } from './core-ai-connection.service';
+
+/**
+ * Lightweight connection shape used during resolution (no secrets). `model` and
+ * `name` are display-only and not used by the resolution logic itself.
+ */
+export interface AiResolvableConnection {
+  enforced?: boolean;
+  enforcedTenantIds?: string[];
+  id: string;
+  isDefault?: boolean;
+  model?: string;
+  name?: string;
+  tenantIds?: string[];
+}
+
+/**
+ * Inputs for resolving which connection to use for a prompt.
+ */
+export interface AiConnectionResolveContext {
+  /** Connection explicitly pinned by a module/service/function (highest priority). */
+  codeOverride?: string;
+  /** Connection requested by the client (`input.connectionId`). */
+  requested?: string;
+  /** Current tenant id (multi-tenancy), if any. */
+  tenantId?: string;
+  /** Current user id, if any. */
+  userId?: string;
+}
+
+/**
+ * Resolves WHICH database connection a prompt uses, via a prioritized, fully
+ * overridable chain. Connections live in the DB and can be restricted per tenant
+ * (`tenantIds`). If there are no usable connections, AI handling is effectively
+ * disabled (resolution returns `undefined`). If nothing is explicitly selected,
+ * the first available connection is used (so exactly one connection is the
+ * implicit default, and multiple connections never produce a dead state).
+ *
+ * Resolution order (ascending priority — a later layer overrides an earlier one).
+ * "Soft" layers (1–4) must pick a connection from the tenant's available set;
+ * "hard"/mandatory layers (5–8) are authoritative and win regardless:
+ *
+ * 1. Global default (`isDefault`)
+ * 2. Tenant default (preference, not enforced)
+ * 3. User default (preference)
+ * 4. Client request (`requested`)
+ * 5. Tenant-enforced (preference, enforced)
+ * 6. Admin-enforced global (`enforced`)
+ * 7. Admin-enforced for tenant (`enforcedTenantIds`)
+ * 8. Explicit code override (`codeOverride`) — deliberate, trusted; document that it
+ *    bypasses mandates (projects that need mandates to be absolute can reorder).
+ *
+ * Each layer is an overridable `protected` method, and the whole chain
+ * ({@link resolutionLayers}) can be reordered/extended/replaced. Pass a custom
+ * subclass via `CoreModule.forRoot(env, { ai: { connectionResolver } })`.
+ */
+@Injectable()
+export class CoreAiConnectionResolverService {
+  protected readonly logger = new Logger(CoreAiConnectionResolverService.name);
+
+  /** Per-resolution memo for the tenant preference (one DB read per `ctx`). */
+  private readonly tenantPrefCache = new WeakMap<
+    AiConnectionResolveContext,
+    Promise<{ connectionId: string; enforced?: boolean } | null>
+  >();
+
+  constructor(
+    protected readonly connectionService: CoreAiConnectionService,
+    @Optional() protected readonly preferenceService?: CoreAiConnectionPreferenceService,
+  ) {}
+
+  /**
+   * Resolve and load the connection to use (with decrypted key), or `undefined`
+   * when AI is effectively disabled (no usable connection).
+   */
+  async resolveConnection(ctx: AiConnectionResolveContext): Promise<ResolvedAiConnection | undefined> {
+    const id = await this.resolveConnectionId(ctx);
+    return id ? this.connectionService.resolve(id) : undefined;
+  }
+
+  /**
+   * Resolve the connection id via the prioritized chain.
+   */
+  async resolveConnectionId(ctx: AiConnectionResolveContext): Promise<string | undefined> {
+    const connections = await this.connectionService.listUsable();
+    return (await this.resolveFrom(connections, ctx)).selected;
+  }
+
+  /**
+   * List the connections available to the caller (non-sensitive), marking the
+   * currently resolved one (`selected`) and whether the selection is locked by a
+   * mandatory layer. Empty when AI handling is disabled (no usable connections).
+   */
+  async listAvailable(ctx: AiConnectionResolveContext): Promise<CoreAiAvailableConnection[]> {
+    const connections = await this.connectionService.listUsable();
+    if (!connections.length) {
+      return [];
+    }
+    const available = this.availableConnections(connections, ctx.tenantId);
+    const { locked, selected } = await this.resolveFrom(connections, ctx);
+    return available.map((c) => {
+      const item = new CoreAiAvailableConnection();
+      item.id = c.id;
+      item.isDefault = !!c.isDefault;
+      item.locked = locked;
+      item.model = c.model;
+      item.name = c.name;
+      item.selected = c.id === selected;
+      return item;
+    });
+  }
+
+  /**
+   * Set the caller's own user-default connection. Validates that the connection is
+   * available to the caller's tenant before storing the preference. Throws when no
+   * preference service is wired or the connection is not available.
+   */
+  async setUserConnection(userId: string, connectionId: string, tenantId?: string): Promise<void> {
+    if (!this.preferenceService) {
+      throw new ForbiddenException(ErrorCode.AI_PREFERENCES_UNAVAILABLE);
+    }
+    const connections = await this.connectionService.listUsable();
+    const available = this.availableConnections(connections, tenantId);
+    if (!available.some((c) => c.id === connectionId)) {
+      throw new ForbiddenException(ErrorCode.AI_CONNECTION_NOT_AVAILABLE);
+    }
+    await this.preferenceService.upsertPreference('user', userId, connectionId);
+  }
+
+  /**
+   * Set a tenant/user connection preference (admin self-service). Validates that the
+   * connection exists and is usable before persisting, so an admin gets immediate
+   * feedback instead of creating a dangling preference. Returns the stored preference.
+   */
+  async setPreference(
+    scope: 'tenant' | 'user',
+    refId: string,
+    connectionId: string,
+    enforced = false,
+  ): Promise<CoreAiConnectionPreference> {
+    if (!this.preferenceService) {
+      throw new ForbiddenException(ErrorCode.AI_PREFERENCES_UNAVAILABLE);
+    }
+    await this.assertConnectionUsable(connectionId);
+    return this.preferenceService.upsertPreference(scope, refId, connectionId, enforced);
+  }
+
+  /**
+   * Throw {@link NotFoundException} when the connection id does not exist or is disabled.
+   */
+  protected async assertConnectionUsable(connectionId: string): Promise<void> {
+    const connections = await this.connectionService.listUsable();
+    if (!connections.some((c) => c.id === connectionId)) {
+      throw new NotFoundException(ErrorCode.AI_CONNECTION_NOT_FOUND);
+    }
+  }
+
+  /**
+   * Run the resolution chain against a pre-fetched connection list, returning the
+   * selected id and whether the selection came from a mandatory (hard) layer.
+   */
+  protected async resolveFrom(
+    connections: AiResolvableConnection[],
+    ctx: AiConnectionResolveContext,
+  ): Promise<{ locked: boolean; selected?: string }> {
+    if (!connections.length) {
+      return { locked: false }; // no connections → AI disabled
+    }
+    const available = this.availableConnections(connections, ctx.tenantId);
+    const availableIds = new Set(available.map((c) => c.id));
+    const allIds = new Set(connections.map((c) => c.id));
+
+    let locked = false;
+    let selected: string | undefined;
+    for (const layer of this.resolutionLayers()) {
+      const candidate = await layer.resolve(connections, available, ctx);
+      if (!candidate) {
+        continue;
+      }
+      // Soft layers may only pick a connection available to the tenant.
+      if (layer.soft && !availableIds.has(candidate)) {
+        continue;
+      }
+      selected = candidate;
+      // A mandatory (hard) layer dictates the selection — the user cannot override it.
+      locked = !layer.soft;
+    }
+
+    // Robustness: hard layers (enforced preferences, code override) and externally
+    // sourced ids are not pre-filtered by availability, so they can point to a
+    // connection that no longer exists or has been disabled. Drop such a stale
+    // reference and degrade gracefully instead of returning a dead id that would make
+    // `connectionService.resolve()` throw mid-prompt.
+    if (selected && !allIds.has(selected)) {
+      this.logger.warn(
+        `AI connection "${selected}" selected by the resolution chain no longer exists or is disabled; falling back.`,
+      );
+      locked = false;
+      selected = undefined;
+    }
+
+    // Nothing explicitly selected → fall back to the first available connection.
+    // This covers the "exactly one connection = implicit default" rule and avoids a
+    // dead state when multiple connections exist without a default/preference/selection.
+    if (!selected && available.length) {
+      selected = available[0].id;
+    }
+    return { locked, selected };
+  }
+
+  /**
+   * The ordered resolution layers (ascending priority). Override to reorder,
+   * extend or replace the chain.
+   */
+  protected resolutionLayers(): {
+    resolve: (
+      all: AiResolvableConnection[],
+      available: AiResolvableConnection[],
+      ctx: AiConnectionResolveContext,
+    ) => Promise<string | undefined> | string | undefined;
+    soft: boolean;
+  }[] {
+    return [
+      { resolve: (_all, available) => this.globalDefault(available), soft: true },
+      { resolve: (_all, _available, ctx) => this.tenantDefault(ctx), soft: true },
+      { resolve: (_all, _available, ctx) => this.userDefault(ctx), soft: true },
+      { resolve: (_all, _available, ctx) => this.clientSelection(ctx), soft: true },
+      { resolve: (_all, _available, ctx) => this.tenantEnforced(ctx), soft: false },
+      { resolve: (all) => this.adminEnforcedGlobal(all), soft: false },
+      { resolve: (all, _available, ctx) => this.adminEnforcedForTenant(all, ctx), soft: false },
+      { resolve: (_all, _available, ctx) => this.codeOverride(ctx), soft: false },
+    ];
+  }
+
+  // ===================================================================================================================
+  // Layers (overridable)
+  // ===================================================================================================================
+
+  /** Connections available to the tenant (empty `tenantIds` = available to all). */
+  protected availableConnections(connections: AiResolvableConnection[], tenantId?: string): AiResolvableConnection[] {
+    return connections.filter((c) => !c.tenantIds?.length || (tenantId ? c.tenantIds.includes(tenantId) : false));
+  }
+
+  protected globalDefault(available: AiResolvableConnection[]): string | undefined {
+    return available.find((c) => c.isDefault)?.id;
+  }
+
+  protected async tenantDefault(ctx: AiConnectionResolveContext): Promise<string | undefined> {
+    const pref = await this.loadTenantPreference(ctx);
+    return pref && !pref.enforced ? pref.connectionId : undefined;
+  }
+
+  protected async userDefault(ctx: AiConnectionResolveContext): Promise<string | undefined> {
+    if (!ctx.userId || !this.preferenceService) {
+      return undefined;
+    }
+    return (await this.preferenceService.getPreference('user', ctx.userId))?.connectionId;
+  }
+
+  protected clientSelection(ctx: AiConnectionResolveContext): string | undefined {
+    return ctx.requested;
+  }
+
+  protected async tenantEnforced(ctx: AiConnectionResolveContext): Promise<string | undefined> {
+    const pref = await this.loadTenantPreference(ctx);
+    return pref?.enforced ? pref.connectionId : undefined;
+  }
+
+  /**
+   * Load the tenant preference once per resolution (`tenantDefault` + `tenantEnforced`
+   * both need it). Memoized on the `ctx` object so a single prompt triggers one DB read.
+   */
+  protected loadTenantPreference(
+    ctx: AiConnectionResolveContext,
+  ): Promise<{ connectionId: string; enforced?: boolean } | null> {
+    if (!ctx.tenantId || !this.preferenceService) {
+      return Promise.resolve(null);
+    }
+    let cached = this.tenantPrefCache.get(ctx);
+    if (!cached) {
+      cached = this.preferenceService.getPreference('tenant', ctx.tenantId);
+      this.tenantPrefCache.set(ctx, cached);
+    }
+    return cached;
+  }
+
+  protected adminEnforcedGlobal(all: AiResolvableConnection[]): string | undefined {
+    return all.find((c) => c.enforced)?.id;
+  }
+
+  protected adminEnforcedForTenant(all: AiResolvableConnection[], ctx: AiConnectionResolveContext): string | undefined {
+    if (!ctx.tenantId) {
+      return undefined;
+    }
+    return all.find((c) => c.enforcedTenantIds?.includes(ctx.tenantId as string))?.id;
+  }
+
+  protected codeOverride(ctx: AiConnectionResolveContext): string | undefined {
+    return ctx.codeOverride;
+  }
+}