@carlonicora/nestjs-neo4jsonapi 2.7.2 → 2.9.0

package/dist/core/llm/interfaces/ai-candidate.interface.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_CONNECTIONS_CHANGED_EVENT = exports.AI_CONNECTION_TYPES = void 0;
+exports.AI_CONNECTION_TYPES = [
+    "ai",
+    "aiLite",
+    "aiLarge",
+    "vision",
+    "audio",
+    "embedder",
+    "transcriber",
+    "documentAi",
+];
+exports.AI_CONNECTIONS_CHANGED_EVENT = "ai-connections.changed";
+//# sourceMappingURL=ai-candidate.interface.js.map

package/dist/core/llm/interfaces/ai-candidate.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-candidate.interface.js","sourceRoot":"","sources":["../../../../src/core/llm/interfaces/ai-candidate.interface.ts"],"names":[],"mappings":";;;AAAa,QAAA,mBAAmB,GAAG;IACjC,IAAI;IACJ,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,OAAO;IACP,UAAU;IACV,aAAa;IACb,YAAY;CACJ,CAAC;AAGE,QAAA,4BAA4B,GAAG,wBAAwB,CAAC"}

package/dist/core/llm/llm.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.module.d.ts","sourceRoot":"","sources":["../../../src/core/llm/llm.module.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;GAaG;AACH,qBAQa,SAAS;CAAG"}
+{"version":3,"file":"llm.module.d.ts","sourceRoot":"","sources":["../../../src/core/llm/llm.module.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;GAaG;AACH,qBAUa,SAAS;CAAG"}

package/dist/core/llm/llm.module.js

@@ -9,7 +9,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LLMModule = void 0;
 const common_1 = require("@nestjs/common");
 const redis_module_1 = require("../redis/redis.module");
+const ai_connection_module_1 = require("../../foundations/ai-connection/ai-connection.module");
 const tokenusage_module_1 = require("../../foundations/tokenusage/tokenusage.module");
+const ai_connection_resolver_service_1 = require("./services/ai-connection-resolver.service");
 const audio_llm_service_1 = require("./services/audio.llm.service");
 const embedder_service_1 = require("./services/embedder.service");
 const embedder_token_bucket_service_1 = require("./services/embedder-token-bucket.service");
@@ -22,6 +24,7 @@ const vision_llm_service_1 = require("./services/vision.llm.service");
 const LLM_SERVICES = [
     llm_service_1.LLMService,
     model_service_1.ModelService,
+    ai_connection_resolver_service_1.AiConnectionResolverService,
     embedder_service_1.EmbedderService,
     embedder_token_bucket_service_1.EmbedderTokenBucketService,
     vision_llm_service_1.VisionLLMService,
@@ -52,7 +55,9 @@ exports.LLMModule = LLMModule = __decorate([
     (0, common_1.Module)({
         // RedisModule provides RedisClientStorageService for EmbedderTokenBucketService's
         // distributed token bucket. RedisModule is NOT @Global, so it must be imported here.
-        imports: [tokenusage_module_1.TokenUsageModule, redis_module_1.RedisModule],
+        // AiConnectionModule provides the repository + encryption service the
+        // AiConnectionResolverService reads its snapshot through.
+        imports: [ai_connection_module_1.AiConnectionModule, tokenusage_module_1.TokenUsageModule, redis_module_1.RedisModule],
         providers: LLM_SERVICES,
         exports: LLM_SERVICES,
     })

package/dist/core/llm/llm.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm.module.js","sourceRoot":"","sources":["../../../src/core/llm/llm.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAgD;AAChD,wDAAoD;AACpD,sFAAkF;AAClF,oEAA+D;AAC/D,kEAA8D;AAC9D,4FAAsF;AACtF,oEAA+D;AAC/D,wEAAmE;AACnE,gFAAmE;AACnE,wDAAoD;AACpD,4DAAwD;AACxD,sEAAiE;AAEjE,MAAM,YAAY,GAAG;IACnB,wBAAU;IACV,4BAAY;IACZ,kCAAe;IACf,0DAA0B;IAC1B,qCAAgB;IAChB,uCAAiB;IACjB,mCAAe;IACf,uCAAa;IACb,mCAAe;CAChB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AASI,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IARrB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,kFAAkF;QAClF,qFAAqF;QACrF,OAAO,EAAE,CAAC,oCAAgB,EAAE,0BAAW,CAAC;QACxC,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,YAAY;KACtB,CAAC;GACW,SAAS,CAAG"}
+{"version":3,"file":"llm.module.js","sourceRoot":"","sources":["../../../src/core/llm/llm.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAgD;AAChD,wDAAoD;AACpD,+FAA0F;AAC1F,sFAAkF;AAClF,8FAAwF;AACxF,oEAA+D;AAC/D,kEAA8D;AAC9D,4FAAsF;AACtF,oEAA+D;AAC/D,wEAAmE;AACnE,gFAAmE;AACnE,wDAAoD;AACpD,4DAAwD;AACxD,sEAAiE;AAEjE,MAAM,YAAY,GAAG;IACnB,wBAAU;IACV,4BAAY;IACZ,4DAA2B;IAC3B,kCAAe;IACf,0DAA0B;IAC1B,qCAAgB;IAChB,uCAAiB;IACjB,mCAAe;IACf,uCAAa;IACb,mCAAe;CAChB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAWI,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAVrB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,kFAAkF;QAClF,qFAAqF;QACrF,sEAAsE;QACtE,0DAA0D;QAC1D,OAAO,EAAE,CAAC,yCAAkB,EAAE,oCAAgB,EAAE,0BAAW,CAAC;QAC5D,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,YAAY;KACtB,CAAC;GACW,SAAS,CAAG"}

package/dist/core/llm/services/ai-connection-resolver.service.d.ts

@@ -0,0 +1,107 @@
+import { OnModuleInit } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { ClsService } from "nestjs-cls";
+import { BaseConfigInterface } from "../../../config/interfaces";
+import type { AiConnection } from "../../../foundations/ai-connection/entities/ai-connection";
+import { AiConnectionRepository } from "../../../foundations/ai-connection/repositories/ai-connection.repository";
+import { AiConnectionEncryptionService } from "../../../foundations/ai-connection/services/ai-connection-encryption.service";
+import { AppLoggingService } from "../../logging/services/logging.service";
+import { AiConnectionType, ResolvedAiCandidate } from "../interfaces/ai-candidate.interface";
+/**
+ * Normalises one `AiConnection` node into the candidate shape `buildChatModel`
+ * (and its embedder/transcriber siblings) already consume.
+ *
+ * Pure on purpose: the decryptor is injected so the caller decides what a
+ * decryption failure means. It THROWS when a stored secret cannot be decrypted —
+ * {@link AiConnectionResolverService.refreshNow} catches that and skips the
+ * connection, so a single unreadable secret never takes the chain down
+ * (spec § 5 "Error handling").
+ */
+export declare function toCandidate(connection: AiConnection, decrypt: (value: string) => string): ResolvedAiCandidate;
+/**
+ * Resolves the ordered fallback chain for an AI connection type.
+ *
+ * Holds an in-memory snapshot of every enabled `AiConnection` node (decrypted,
+ * grouped into chains by `(connectionType, companyId | null)`, ordered by
+ * `position`), refreshed at boot, every 60s, and immediately on any admin write
+ * in this process (`AI_CONNECTIONS_CHANGED_EVENT`).
+ *
+ * The snapshot exists because `ModelService.getLLM()` is synchronous and called
+ * directly by several library services: resolution must stay a pure sync lookup
+ * with no signature ripple (spec § 2).
+ *
+ * Failure ALWAYS degrades toward today's `.env` behaviour, never toward "no AI"
+ * (spec § 5): an empty table, a failed refresh, an undecryptable secret or an
+ * unknown connection type all leave the `.env` candidate in place, and nothing
+ * on the `resolve()` hot path throws.
+ */
+export declare class AiConnectionResolverService implements OnModuleInit {
+    private readonly repository;
+    private readonly encryption;
+    private readonly cls;
+    private readonly configService;
+    private readonly logger?;
+    /** `${connectionType}|${companyId ?? "global"}` → ordered candidates. */
+    private snapshot;
+    /** connectionId → epoch ms before which the candidate is skipped. */
+    private readonly cooldownUntil;
+    private refreshTimer?;
+    constructor(repository: AiConnectionRepository, encryption: AiConnectionEncryptionService, cls: ClsService, configService: ConfigService<BaseConfigInterface>, logger?: AppLoggingService);
+    /**
+     * Loads the first snapshot and starts the periodic refresh. Neither is
+     * awaited and neither can reject: boot must never depend on the database
+     * holding AI connection rows (spec § 5).
+     */
+    onModuleInit(): void;
+    /**
+     * The ordered candidates to try for `type`, best first.
+     *
+     * Per-company chain when the request's company has one, otherwise the global
+     * chain; the `.env` block is ALWAYS appended last. Candidates inside their
+     * cooldown window are dropped — unless that empties the list, in which case
+     * the full chain is returned anyway (fail-open, spec § 2).
+     *
+     * Never throws.
+     */
+    resolve(type: AiConnectionType): ResolvedAiCandidate[];
+    /**
+     * Parks a connection for `ai.connectionCooldownMinutes` after a transient
+     * failure (429 / 5xx / network). The `.env` candidate is tracked under
+     * `env:<type>` like any other, so a dead env fallback cannot block recovery.
+     */
+    markFailure(connectionId: string): void;
+    /**
+     * Rebuilds the snapshot from the database. Also the handler for admin writes
+     * in this process; other processes catch up at the next scheduled refresh.
+     *
+     * A read failure keeps the PREVIOUS snapshot — a database blip must not wipe
+     * working configuration (spec § 5).
+     */
+    refreshNow(): Promise<void>;
+    /**
+     * Reads every connection inside a CLS context: the refresh runs outside any
+     * HTTP request, and the query plumbing reads CLS (`companyId`) unconditionally.
+     */
+    private readConnections;
+    /**
+     * The company of the current request, or undefined when there is none.
+     *
+     * Optional-call plus a silent catch: the resolver is also used by workers and
+     * boot-time code with no CLS context at all, which is an ordinary state and
+     * must not log or throw — it simply means "use the global chain".
+     */
+    private currentCompanyId;
+    private chainKey;
+    private get aiConfig();
+    private get cooldownMinutes();
+    /**
+     * The `.env` block for a type, mapped field-for-field onto a candidate. This
+     * is the final link of every chain and the whole behaviour when the table is
+     * empty — with zero `AiConnection` nodes, resolution is byte-for-byte today's.
+     */
+    private buildEnvCandidate;
+    /** Same block mapping the admin API uses for `meta.envDefaults`. */
+    private envBlockFor;
+    private warn;
+}
+//# sourceMappingURL=ai-connection-resolver.service.d.ts.map

package/dist/core/llm/services/ai-connection-resolver.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-connection-resolver.service.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/services/ai-connection-resolver.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAY,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAqB,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2DAA2D,CAAC;AAC9F,OAAO,EAAE,sBAAsB,EAAE,MAAM,0EAA0E,CAAC;AAClH,OAAO,EAAE,6BAA6B,EAAE,MAAM,8EAA8E,CAAC;AAC7H,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAC3E,OAAO,EAGL,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,sCAAsC,CAAC;AA2B9C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,mBAAmB,CA6B7G;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,2BAA4B,YAAW,YAAY;IAU5D,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAGlB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAftC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAA4C;IAE5D,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAE3D,OAAO,CAAC,YAAY,CAAC,CAAiC;gBAGnC,UAAU,EAAE,sBAAsB,EAClC,UAAU,EAAE,6BAA6B,EACzC,GAAG,EAAE,UAAU,EACf,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAGrC,MAAM,CAAC,EAAE,iBAAiB;IAGzD;;;;OAIG;IACH,YAAY,IAAI,IAAI;IASpB;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,EAAE;IA0BtD;;;;OAIG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;;;OAMG;IAEG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuCjC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,QAAQ;IAIhB,OAAO,KAAK,QAAQ,GAMnB;IAED,OAAO,KAAK,eAAe,GAM1B;IAED;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA8BzB,oEAAoE;IACpE,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,IAAI;CAOb"}

package/dist/core/llm/services/ai-connection-resolver.service.js

@@ -0,0 +1,329 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AiConnectionResolverService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiConnectionResolverService = void 0;
+exports.toCandidate = toCandidate;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const event_emitter_1 = require("@nestjs/event-emitter");
+const nestjs_cls_1 = require("nestjs-cls");
+const ai_connection_repository_1 = require("../../../foundations/ai-connection/repositories/ai-connection.repository");
+const ai_connection_encryption_service_1 = require("../../../foundations/ai-connection/services/ai-connection-encryption.service");
+const logging_service_1 = require("../../logging/services/logging.service");
+const ai_candidate_interface_1 = require("../interfaces/ai-candidate.interface");
+/** How often the in-memory snapshot is rebuilt from the database. */
+const SNAPSHOT_REFRESH_INTERVAL_MS = 60_000;
+/** Cooldown used when `ai.connectionCooldownMinutes` is missing from config. */
+const DEFAULT_COOLDOWN_MINUTES = 5;
+/** Snapshot key for the chain that applies to every company. */
+const GLOBAL_SCOPE = "global";
+const KNOWN_CONNECTION_TYPES = new Set(ai_candidate_interface_1.AI_CONNECTION_TYPES);
+const asString = (value) => typeof value === "string" && value !== "" ? value : undefined;
+const asNumber = (value) => (typeof value === "number" ? value : undefined);
+const asBoolean = (value) => (typeof value === "boolean" ? value : undefined);
+/**
+ * Normalises one `AiConnection` node into the candidate shape `buildChatModel`
+ * (and its embedder/transcriber siblings) already consume.
+ *
+ * Pure on purpose: the decryptor is injected so the caller decides what a
+ * decryption failure means. It THROWS when a stored secret cannot be decrypted —
+ * {@link AiConnectionResolverService.refreshNow} catches that and skips the
+ * connection, so a single unreadable secret never takes the chain down
+ * (spec § 5 "Error handling").
+ */
+function toCandidate(connection, decrypt) {
+    return {
+        source: "db",
+        connectionId: connection.id,
+        connectionType: connection.connectionType,
+        provider: connection.provider,
+        apiKey: connection.apiKey ? decrypt(connection.apiKey) : "",
+        model: connection.model ?? "",
+        url: connection.url ?? "",
+        region: connection.region,
+        instance: connection.instance,
+        apiVersion: connection.apiVersion,
+        googleCredentialsBase64: connection.googleCredentialsBase64
+            ? decrypt(connection.googleCredentialsBase64)
+            : undefined,
+        allowFallbacks: connection.allowFallbacks,
+        reasoningEffort: connection.reasoningEffort,
+        maxOutputTokens: connection.maxOutputTokens,
+        dimensions: connection.dimensions,
+        inputCostPer1MTokens: connection.inputCostPer1MTokens,
+        outputCostPer1MTokens: connection.outputCostPer1MTokens,
+        cachedInputCostPer1MTokens: connection.cachedInputCostPer1MTokens,
+        costPerMinute: connection.costPerMinute,
+        costPerPage: connection.costPerPage,
+        directUrl: connection.directUrl,
+        language: connection.language,
+        directFormat: connection.directFormat,
+        directProvider: connection.directProvider,
+    };
+}
+/**
+ * Resolves the ordered fallback chain for an AI connection type.
+ *
+ * Holds an in-memory snapshot of every enabled `AiConnection` node (decrypted,
+ * grouped into chains by `(connectionType, companyId | null)`, ordered by
+ * `position`), refreshed at boot, every 60s, and immediately on any admin write
+ * in this process (`AI_CONNECTIONS_CHANGED_EVENT`).
+ *
+ * The snapshot exists because `ModelService.getLLM()` is synchronous and called
+ * directly by several library services: resolution must stay a pure sync lookup
+ * with no signature ripple (spec § 2).
+ *
+ * Failure ALWAYS degrades toward today's `.env` behaviour, never toward "no AI"
+ * (spec § 5): an empty table, a failed refresh, an undecryptable secret or an
+ * unknown connection type all leave the `.env` candidate in place, and nothing
+ * on the `resolve()` hot path throws.
+ */
+let AiConnectionResolverService = AiConnectionResolverService_1 = class AiConnectionResolverService {
+    constructor(repository, encryption, cls, configService, logger) {
+        this.repository = repository;
+        this.encryption = encryption;
+        this.cls = cls;
+        this.configService = configService;
+        this.logger = logger;
+        /** `${connectionType}|${companyId ?? "global"}` → ordered candidates. */
+        this.snapshot = new Map();
+        /** connectionId → epoch ms before which the candidate is skipped. */
+        this.cooldownUntil = new Map();
+    }
+    /**
+     * Loads the first snapshot and starts the periodic refresh. Neither is
+     * awaited and neither can reject: boot must never depend on the database
+     * holding AI connection rows (spec § 5).
+     */
+    onModuleInit() {
+        void this.refreshNow().catch((error) => this.warn("initial snapshot load failed", error));
+        this.refreshTimer = setInterval(() => {
+            void this.refreshNow().catch((error) => this.warn("scheduled snapshot refresh failed", error));
+        }, SNAPSHOT_REFRESH_INTERVAL_MS);
+        // Never hold the process open for a cache refresh.
+        this.refreshTimer.unref?.();
+    }
+    /**
+     * The ordered candidates to try for `type`, best first.
+     *
+     * Per-company chain when the request's company has one, otherwise the global
+     * chain; the `.env` block is ALWAYS appended last. Candidates inside their
+     * cooldown window are dropped — unless that empties the list, in which case
+     * the full chain is returned anyway (fail-open, spec § 2).
+     *
+     * Never throws.
+     */
+    resolve(type) {
+        const candidates = [];
+        try {
+            const companyId = this.currentCompanyId();
+            if (companyId) {
+                const scoped = this.snapshot.get(this.chainKey(type, companyId));
+                if (scoped?.length)
+                    candidates.push(...scoped);
+            }
+            if (candidates.length === 0) {
+                const global = this.snapshot.get(this.chainKey(type, undefined));
+                if (global?.length)
+                    candidates.push(...global);
+            }
+        }
+        catch (error) {
+            // A broken CLS/snapshot read degrades to the env candidate alone.
+            this.warn(`chain lookup failed for "${type}"`, error);
+            candidates.length = 0;
+        }
+        candidates.push(this.buildEnvCandidate(type));
+        const now = Date.now();
+        const healthy = candidates.filter((candidate) => (this.cooldownUntil.get(candidate.connectionId) ?? 0) <= now);
+        return healthy.length > 0 ? healthy : candidates;
+    }
+    /**
+     * Parks a connection for `ai.connectionCooldownMinutes` after a transient
+     * failure (429 / 5xx / network). The `.env` candidate is tracked under
+     * `env:<type>` like any other, so a dead env fallback cannot block recovery.
+     */
+    markFailure(connectionId) {
+        if (!connectionId)
+            return;
+        this.cooldownUntil.set(connectionId, Date.now() + this.cooldownMinutes * 60_000);
+    }
+    /**
+     * Rebuilds the snapshot from the database. Also the handler for admin writes
+     * in this process; other processes catch up at the next scheduled refresh.
+     *
+     * A read failure keeps the PREVIOUS snapshot — a database blip must not wipe
+     * working configuration (spec § 5).
+     */
+    async refreshNow() {
+        let connections;
+        try {
+            connections = await this.readConnections();
+        }
+        catch (error) {
+            this.warn("snapshot refresh failed — keeping the previous snapshot", error);
+            return;
+        }
+        const next = new Map();
+        const ordered = [...(connections ?? [])].sort((a, b) => (a?.position ?? 0) - (b?.position ?? 0));
+        for (const connection of ordered) {
+            if (!connection || connection.enabled === false)
+                continue;
+            if (!KNOWN_CONNECTION_TYPES.has(connection.connectionType)) {
+                this.warn(`skipping connection ${connection.id}: unknown connectionType "${connection.connectionType}"`);
+                continue;
+            }
+            let candidate;
+            try {
+                candidate = toCandidate(connection, (value) => this.encryption.decrypt(value));
+            }
+            catch (error) {
+                this.warn(`skipping connection ${connection.id}: stored secret could not be decrypted`, error);
+                continue;
+            }
+            const key = this.chainKey(candidate.connectionType, connection.companyId);
+            const chain = next.get(key);
+            if (chain)
+                chain.push(candidate);
+            else
+                next.set(key, [candidate]);
+        }
+        this.snapshot = next;
+    }
+    // --- internals ----------------------------------------------------------
+    /**
+     * Reads every connection inside a CLS context: the refresh runs outside any
+     * HTTP request, and the query plumbing reads CLS (`companyId`) unconditionally.
+     */
+    readConnections() {
+        if (typeof this.cls?.run === "function") {
+            return this.cls.run(async () => this.repository.findAllForResolver());
+        }
+        return this.repository.findAllForResolver();
+    }
+    /**
+     * The company of the current request, or undefined when there is none.
+     *
+     * Optional-call plus a silent catch: the resolver is also used by workers and
+     * boot-time code with no CLS context at all, which is an ordinary state and
+     * must not log or throw — it simply means "use the global chain".
+     */
+    currentCompanyId() {
+        try {
+            const companyId = this.cls?.get?.("companyId");
+            return typeof companyId === "string" && companyId !== "" ? companyId : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    chainKey(type, companyId) {
+        return `${type}|${companyId ?? GLOBAL_SCOPE}`;
+    }
+    get aiConfig() {
+        try {
+            return this.configService?.get("ai");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    get cooldownMinutes() {
+        // `connectionCooldownMinutes` is added to the `ai` block by the config task;
+        // default defensively so this works even when the read returns undefined.
+        const ai = this.aiConfig;
+        const configured = ai?.connectionCooldownMinutes;
+        return typeof configured === "number" && configured > 0 ? configured : DEFAULT_COOLDOWN_MINUTES;
+    }
+    /**
+     * The `.env` block for a type, mapped field-for-field onto a candidate. This
+     * is the final link of every chain and the whole behaviour when the table is
+     * empty — with zero `AiConnection` nodes, resolution is byte-for-byte today's.
+     */
+    buildEnvCandidate(type) {
+        const block = this.envBlockFor(type);
+        return {
+            source: "env",
+            connectionId: `env:${type}`,
+            connectionType: type,
+            provider: asString(block.provider) ?? "",
+            apiKey: asString(block.apiKey) ?? "",
+            model: asString(block.model) ?? "",
+            url: asString(block.url) ?? "",
+            region: asString(block.region),
+            instance: asString(block.instance),
+            apiVersion: asString(block.apiVersion),
+            googleCredentialsBase64: asString(block.googleCredentialsBase64),
+            allowFallbacks: asBoolean(block.allowFallbacks),
+            reasoningEffort: asString(block.reasoningEffort),
+            maxOutputTokens: asNumber(block.maxOutputTokens),
+            dimensions: asNumber(block.dimensions),
+            inputCostPer1MTokens: asNumber(block.inputCostPer1MTokens),
+            outputCostPer1MTokens: asNumber(block.outputCostPer1MTokens),
+            cachedInputCostPer1MTokens: asNumber(block.cachedInputCostPer1MTokens),
+            costPerMinute: asNumber(block.costPerMinute),
+            costPerPage: asNumber(block.costPerPage),
+            directUrl: asString(block.directUrl),
+            language: asString(block.language),
+            directFormat: asString(block.directFormat),
+            directProvider: asString(block.directProvider),
+        };
+    }
+    /** Same block mapping the admin API uses for `meta.envDefaults`. */
+    envBlockFor(type) {
+        const ai = this.aiConfig;
+        if (!ai)
+            return {};
+        switch (type) {
+            case "aiLite":
+                return (ai.aiLite ?? {});
+            case "aiLarge":
+                return (ai.aiLarge ?? {});
+            case "vision":
+                return (ai.vision ?? {});
+            case "audio":
+                return (ai.audio ?? {});
+            case "embedder":
+                return (ai.embedder ?? {});
+            case "transcriber":
+                return (ai.transcriber ?? {});
+            case "documentAi":
+                return (ai.documentAi ?? {});
+            default:
+                return (ai.ai ?? {});
+        }
+    }
+    warn(message, error) {
+        const detail = error instanceof Error ? error.message : error !== undefined ? String(error) : undefined;
+        this.logger?.warn(detail ? `[AiConnectionResolver] ${message}: ${detail}` : `[AiConnectionResolver] ${message}`, AiConnectionResolverService_1.name);
+    }
+};
+exports.AiConnectionResolverService = AiConnectionResolverService;
+__decorate([
+    (0, event_emitter_1.OnEvent)(ai_candidate_interface_1.AI_CONNECTIONS_CHANGED_EVENT),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], AiConnectionResolverService.prototype, "refreshNow", null);
+exports.AiConnectionResolverService = AiConnectionResolverService = AiConnectionResolverService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(4, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [ai_connection_repository_1.AiConnectionRepository,
+        ai_connection_encryption_service_1.AiConnectionEncryptionService,
+        nestjs_cls_1.ClsService,
+        config_1.ConfigService,
+        logging_service_1.AppLoggingService])
+], AiConnectionResolverService);
+//# sourceMappingURL=ai-connection-resolver.service.js.map

package/dist/core/llm/services/ai-connection-resolver.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-connection-resolver.service.js","sourceRoot":"","sources":["../../../../src/core/llm/services/ai-connection-resolver.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAmDA,kCA6BC;AAhFD,2CAAoE;AACpE,2CAA+C;AAC/C,yDAAgD;AAChD,2CAAwC;AAGxC,uHAAkH;AAClH,mIAA6H;AAC7H,4EAA2E;AAC3E,iFAK8C;AAE9C,qEAAqE;AACrE,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAE5C,gFAAgF;AAChF,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,gEAAgE;AAChE,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAS,4CAAmB,CAAC,CAAC;AASzF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAsB,EAAE,CACtD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAEhE,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAsB,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAEzG,MAAM,SAAS,GAAG,CAAC,KAAc,EAAuB,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAE5G;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,UAAwB,EAAE,OAAkC;IACtF,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,YAAY,EAAE,UAAU,CAAC,EAAE;QAC3B,cAAc,EAAE,UAAU,CAAC,cAAkC;QAC7D,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;QAC3D,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,EAAE;QAC7B,GAAG,EAAE,UAAU,CAAC,GAAG,IAAI,EAAE;QACzB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,uBAAuB,EAAE,UAAU,CAAC,uBAAuB;YACzD,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,uBAAuB,CAAC;YAC7C,CAAC,CAAC,SAAS;QACb,cAAc,EAAE,UAAU,CAAC,cAAc;QACzC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,oBAAoB,EAAE,UAAU,CAAC,oBAAoB;QACrD,qBAAqB,EAAE,UAAU,CAAC,qBAAqB;QACvD,0BAA0B,EAAE,UAAU,CAAC,0BAA0B;QACjE,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,YAAY,EAAE,UAAU,CAAC,YAAY;QACrC,cAAc,EAAE,UAAU,CAAC,cAAc;KAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AAEI,IAAM,2BAA2B,mCAAjC,MAAM,2BAA2B;IAStC,YACmB,UAAkC,EAClC,UAAyC,EACzC,GAAe,EACf,aAAiD,EAGtD,MAA2C;QANtC,eAAU,GAAV,UAAU,CAAwB;QAClC,eAAU,GAAV,UAAU,CAA+B;QACzC,QAAG,GAAH,GAAG,CAAY;QACf,kBAAa,GAAb,aAAa,CAAoC;QAGrC,WAAM,GAAN,MAAM,CAAoB;QAfzD,yEAAyE;QACjE,aAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;QAE5D,qEAAqE;QACpD,kBAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAYxD,CAAC;IAEJ;;;;OAIG;IACH,YAAY;QACV,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC,CAAC;QAC1F,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;YACnC,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC,CAAC;QACjG,CAAC,EAAE,4BAA4B,CAAC,CAAC;QACjC,mDAAmD;QACnD,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAsB;QAC5B,MAAM,UAAU,GAA0B,EAAE,CAAC;QAE7C,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1C,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;gBACjE,IAAI,MAAM,EAAE,MAAM;oBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;YACjD,CAAC;YACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;gBACjE,IAAI,MAAM,EAAE,MAAM;oBAAE,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,kEAAkE;YAClE,IAAI,CAAC,IAAI,CAAC,4BAA4B,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YACtD,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;QAE9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC/G,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,YAAoB;QAC9B,IAAI,CAAC,YAAY;YAAE,OAAO;QAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;OAMG;IAEG,AAAN,KAAK,CAAC,UAAU;QACd,IAAI,WAA2B,CAAC;QAChC,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC,yDAAyD,EAAE,KAAK,CAAC,CAAC;YAC5E,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiC,CAAC;QAEtD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC;QACjG,KAAK,MAAM,UAAU,IAAI,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,OAAO,KAAK,KAAK;gBAAE,SAAS;YAE1D,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC3D,IAAI,CAAC,IAAI,CAAC,uBAAuB,UAAU,CAAC,EAAE,6BAA6B,UAAU,CAAC,cAAc,GAAG,CAAC,CAAC;gBACzG,SAAS;YACX,CAAC;YAED,IAAI,SAA8B,CAAC;YACnC,IAAI,CAAC;gBACH,SAAS,GAAG,WAAW,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YACjF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC,uBAAuB,UAAU,CAAC,EAAE,wCAAwC,EAAE,KAAK,CAAC,CAAC;gBAC/F,SAAS;YACX,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,2EAA2E;IAE3E;;;OAGG;IACK,eAAe;QACrB,IAAI,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,UAAU,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC;IAC9C,CAAC;IAED;;;;;;OAMG;IACK,gBAAgB;QACtB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC;YAC/C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,IAA+B,EAAE,SAA6B;QAC7E,OAAO,GAAG,IAAI,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;IAChD,CAAC;IAED,IAAY,QAAQ;QAClB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,aAAa,EAAE,GAAG,CAAoB,IAAI,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,IAAY,eAAe;QACzB,6EAA6E;QAC7E,0EAA0E;QAC1E,MAAM,EAAE,GAAG,IAAI,CAAC,QAAoF,CAAC;QACrG,MAAM,UAAU,GAAG,EAAE,EAAE,yBAAyB,CAAC;QACjD,OAAO,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,wBAAwB,CAAC;IAClG,CAAC;IAED;;;;OAIG;IACK,iBAAiB,CAAC,IAAsB;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACrC,OAAO;YACL,MAAM,EAAE,KAAK;YACb,YAAY,EAAE,OAAO,IAAI,EAAE;YAC3B,cAAc,EAAE,IAAI;YACpB,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE;YACxC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE;YACpC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE;YAClC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE;YAC9B,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;YAC9B,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;YAClC,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;YACtC,uBAAuB,EAAE,QAAQ,CAAC,KAAK,CAAC,uBAAuB,CAAC;YAChE,cAAc,EAAE,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC;YAC/C,eAAe,EAAE,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;YAChD,eAAe,EAAE,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;YAChD,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;YACtC,oBAAoB,EAAE,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC;YAC1D,qBAAqB,EAAE,QAAQ,CAAC,KAAK,CAAC,qBAAqB,CAAC;YAC5D,0BAA0B,EAAE,QAAQ,CAAC,KAAK,CAAC,0BAA0B,CAAC;YACtE,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;YAC5C,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;YACxC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;YACpC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;YAClC,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;YAC1C,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC;SAC/C,CAAC;IACJ,CAAC;IAED,oEAAoE;IAC5D,WAAW,CAAC,IAAsB;QACxC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzB,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QACnB,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,QAAQ;gBACX,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,EAAE,CAAa,CAAC;YACvC,KAAK,SAAS;gBACZ,OAAO,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAa,CAAC;YACxC,KAAK,QAAQ;gBACX,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,EAAE,CAAa,CAAC;YACvC,KAAK,OAAO;gBACV,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAa,CAAC;YACtC,KAAK,UAAU;gBACb,OAAO,CAAC,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAa,CAAC;YACzC,KAAK,aAAa;gBAChB,OAAO,CAAC,EAAE,CAAC,WAAW,IAAI,EAAE,CAAa,CAAC;YAC5C,KAAK,YAAY;gBACf,OAAO,CAAC,EAAE,CAAC,UAAU,IAAI,EAAE,CAAa,CAAC;YAC3C;gBACE,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAa,CAAC;QACrC,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,OAAe,EAAE,KAAe;QAC3C,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxG,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,MAAM,CAAC,CAAC,CAAC,0BAA0B,OAAO,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,0BAA0B,OAAO,EAAE,EAC7F,6BAA2B,CAAC,IAAI,CACjC,CAAC;IACJ,CAAC;CACF,CAAA;AA/OY,kEAA2B;AAuFhC;IADL,IAAA,uBAAO,EAAC,qDAA4B,CAAC;;;;6DAoCrC;sCA1HU,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAiBR,WAAA,IAAA,iBAAQ,GAAE,CAAA;qCANkB,iDAAsB;QACtB,gEAA6B;QACpC,uBAAU;QACA,sBAAa;QAGP,mCAAiB;GAhB9C,2BAA2B,CA+OvC"}

package/dist/core/llm/services/embedder.service.d.ts

@@ -21,6 +21,27 @@ export declare class EmbedderService {
     private readonly tokenUsageRecorder?;
     private readonly logger;
     constructor(modelService: ModelService, config: ConfigService<BaseConfigInterface>, tokenUsageService?: TokenUsageService, tokenUsageRecorder?: TokenUsageRecorderInterface);
+    /**
+     * Runs ONE embedding invocation, with a single failover retry on a transient
+     * provider failure (429/5xx/socket-level — classified by exactly the rule
+     * `LLMService` uses).
+     *
+     * ONE retry only, and only when there is somewhere to go: the failed
+     * connection is put into cooldown and the embedder is rebuilt, so
+     * `getEmbedder()` resolves the NEXT healthy link of the chain. A chain of one
+     * (no DB-backed embedder connection — just the `.env` block) has nowhere to
+     * fail over to, so the rejection propagates immediately, exactly as it does
+     * today. Everything beyond that single re-resolution belongs to the BullMQ
+     * job retry that owns these calls (spec § 2, "Other modalities").
+     */
+    private withCandidateFailover;
+    /**
+     * Puts the embedder connection currently in service into its cooldown window
+     * and returns it — or undefined when there is nothing to fail over to: no
+     * candidate-aware `ModelService`, a chain of one (`.env` only), or a registry
+     * that threw. Undefined means "behave exactly as before failover existed".
+     */
+    private failCurrentEmbedderCandidate;
     vectoriseText(params: {
         text: string;
         attribution?: EmbedderAttribution;

package/dist/core/llm/services/embedder.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedder.service.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/services/embedder.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAwB,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAqB,MAAM,4BAA4B,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6DAA6D,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD,qBACa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAIX,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACL,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAThF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAGxC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAI9B,iBAAiB,CAAC,EAAE,iBAAiB,EACP,kBAAkB,CAAC,EAAE,2BAA2B;IAGvG,aAAa,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAWxF,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA2B5F;;;;;OAKG;YACW,YAAY;IAO1B;;;;OAIG;YACW,WAAW;IAMzB,OAAO,CAAC,kBAAkB;IAW1B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,qEAAqE;IACrE,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAYhB,0FAA0F;IAC1F,OAAO,CAAC,SAAS,CAA8B;IAE/C;;;;;;;;;OASG;YACW,YAAY;IA4B1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;YACW,qBAAqB;IASnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;OAGG;IACH,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;CAsBpB"}
+{"version":3,"file":"embedder.service.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/services/embedder.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAwB,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAqB,MAAM,4BAA4B,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6DAA6D,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAehE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD,qBACa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAIX,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACL,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAThF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAGxC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAI9B,iBAAiB,CAAC,EAAE,iBAAiB,EACP,kBAAkB,CAAC,EAAE,2BAA2B;IAG7G;;;;;;;;;;;;OAYG;YACW,qBAAqB;IAgBnC;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAc9B,aAAa,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAWxF,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA6B5F;;;;;OAKG;YACW,YAAY;IAO1B;;;;OAIG;YACW,WAAW;IAOzB,OAAO,CAAC,kBAAkB;IAW1B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,qEAAqE;IACrE,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAYhB,0FAA0F;IAC1F,OAAO,CAAC,SAAS,CAA8B;IAE/C;;;;;;;;;OASG;YACW,YAAY;IA4B1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;YACW,qBAAqB;IASnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;OAGG;IACH,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;CAsBpB"}

package/dist/core/llm/services/embedder.service.js

@@ -21,6 +21,7 @@ const tokens_1 = require("../../../common/tokens");
 const tokenusage_type_1 = require("../../../foundations/tokenusage/enums/tokenusage.type");
 const tokenusage_service_1 = require("../../../foundations/tokenusage/services/tokenusage.service");
 const model_service_1 = require("../../llm/services/model.service");
+const llm_service_1 = require("./llm.service");
 /**
  * Ceiling for ONE embedding input. The provider hard cap is 8192 tokens
  * (`400 Invalid 'input[0]': maximum input length is 8192 tokens` from
@@ -39,6 +40,54 @@ let EmbedderService = EmbedderService_1 = class EmbedderService {
         this.tokenUsageRecorder = tokenUsageRecorder;
         this.logger = new common_1.Logger(EmbedderService_1.name);
     }
+    /**
+     * Runs ONE embedding invocation, with a single failover retry on a transient
+     * provider failure (429/5xx/socket-level — classified by exactly the rule
+     * `LLMService` uses).
+     *
+     * ONE retry only, and only when there is somewhere to go: the failed
+     * connection is put into cooldown and the embedder is rebuilt, so
+     * `getEmbedder()` resolves the NEXT healthy link of the chain. A chain of one
+     * (no DB-backed embedder connection — just the `.env` block) has nowhere to
+     * fail over to, so the rejection propagates immediately, exactly as it does
+     * today. Everything beyond that single re-resolution belongs to the BullMQ
+     * job retry that owns these calls (spec § 2, "Other modalities").
+     */
+    async withCandidateFailover(work) {
+        try {
+            return await work(this.modelService.getEmbedder());
+        }
+        catch (error) {
+            if (!(0, llm_service_1.isTransientNetworkError)(error))
+                throw error;
+            const failed = this.failCurrentEmbedderCandidate();
+            if (!failed)
+                throw error;
+            this.logger.warn(`Embedder connection ${failed.connectionId} failed transiently — retrying once on the next candidate: ${String(error)}`);
+            return work(this.modelService.getEmbedder());
+        }
+    }
+    /**
+     * Puts the embedder connection currently in service into its cooldown window
+     * and returns it — or undefined when there is nothing to fail over to: no
+     * candidate-aware `ModelService`, a chain of one (`.env` only), or a registry
+     * that threw. Undefined means "behave exactly as before failover existed".
+     */
+    failCurrentEmbedderCandidate() {
+        const resolver = this.modelService;
+        if (typeof resolver.getCandidatesForType !== "function" || typeof resolver.notifyCandidateFailure !== "function")
+            return undefined;
+        try {
+            const candidates = resolver.getCandidatesForType("embedder") ?? [];
+            if (candidates.length < 2)
+                return undefined;
+            resolver.notifyCandidateFailure(candidates[0]);
+            return candidates[0];
+        }
+        catch {
+            return undefined;
+        }
+    }
     async vectoriseText(params) {
         try {
             const result = await this.embedGuarded(params.text, params.attribution);
@@ -60,7 +109,7 @@ let EmbedderService = EmbedderService_1 = class EmbedderService {
             // The texts that fit still travel as ONE provider batch, in input order —
             // batching is why vectoriseTextBatch exists (chunk.repository.ts:405).
             if (withinBudget.length > 0) {
-                const vectors = await this.modelService.getEmbedder().embedDocuments(withinBudget.map((index) => texts[index]));
+                const vectors = await this.withCandidateFailover((embedder) => embedder.embedDocuments(withinBudget.map((index) => texts[index])));
                 withinBudget.forEach((index, position) => (result[index] = vectors[position]));
             }
             for (const index of oversized) {
@@ -84,7 +133,7 @@ let EmbedderService = EmbedderService_1 = class EmbedderService {
     async embedGuarded(text, attribution) {
         const slices = this.splitByTokenBudget(text);
         if (slices.length === 1)
-            return this.modelService.getEmbedder().embedQuery(text);
+            return this.withCandidateFailover((embedder) => embedder.embedQuery(text));
         this.warnOversizedInput(text, slices.length, attribution);
         return this.meanPool(await this.embedSlices(slices));
     }
@@ -96,7 +145,7 @@ let EmbedderService = EmbedderService_1 = class EmbedderService {
     async embedSlices(slices) {
         const vectors = [];
         for (const slice of slices)
-            vectors.push(await this.modelService.getEmbedder().embedQuery(slice));
+            vectors.push(await this.withCandidateFailover((embedder) => embedder.embedQuery(slice)));
         return vectors;
     }
     warnOversizedInput(text, sliceCount, attribution) {