@lenne.tech/nest-server 11.27.6 → 11.28.0

package/src/core/common/helpers/input.helper.ts

@@ -1,18 +1,27 @@
-import { BadRequestException, UnauthorizedException } from '@nestjs/common';
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 import { ValidatorOptions } from 'class-validator/types/validation/ValidatorOptions';
 import { Kind } from 'graphql/index';
-import * as inspector from 'inspector';
-import _ = require('lodash');
-import rfdc = require('rfdc');
-import * as util from 'util';
 
 import { checkRestricted } from '../decorators/restricted.decorator';
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
+import { ErrorCode } from '../../modules/error-code/error-codes';
+import { clone } from './clone.helper';
 import { merge } from './config.helper';
-import { equalIds } from './db.helper';
+import { equalIds } from './id.helper';
+
+/**
+ * `clone` and `deepFreeze` moved to `./clone.helper` and are re-exported here so every existing
+ * import path keeps working. They were extracted because `config.service` needs `clone`/`deepFreeze`,
+ * and pulling them from HERE put it on a runtime import cycle
+ * (restricted.decorator → core-tenant.helpers → config.service → input.helper → restricted.decorator)
+ * that is one top-level line away from an SWC temporal-dead-zone crash. `clone.helper` imports no
+ * framework code, so it can never be part of a cycle. Do NOT move them back.
+ */
+export { clone, deepFreeze } from './clone.helper';
 
 /**
  * Helper class for inputs
@@ -241,9 +250,11 @@ export async function check(
     }
     let valid = false;
 
-    // Prevent access for everyone, including administrators
+    // Prevent access for everyone, including administrators. Always 403, never 401: the resource is
+    // locked permanently, so authenticating can never grant access and telling an anonymous
+    // requester to "authenticate and retry" (401) would be a lie. Both role guards do the same.
     if (roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException('No access');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Check access
@@ -269,7 +280,8 @@ export async function check(
       valid = true;
     }
     if (!valid) {
-      throw new UnauthorizedException('Missing rights');
+      // 403 when authenticated, 401 otherwise — policy documented in accessDeniedException
+      throw accessDeniedException(user);
     }
   }
 
@@ -341,68 +353,6 @@ export function checkAndGetDate(input: any): Date {
   return date;
 }
 
-/**
- * Clone object
- * @param object Any object
- * @param options Finetuning of rfdc cloning
- * @param options.checkResult Whether to compare object and cloned object via JSON.stringify and try alternative cloning
- *                            methods if they are not equal
- * @param options.circles Keeping track of circular references will slow down performance with an additional 25% overhead.
- *                        Even if an object doesn't have any circular references, the tracking overhead is the cost.
- *                        By default if an object with a circular reference is passed to rfdc, it will throw
- *                        (similar to how JSON.stringify would throw). Use the circles option to detect and preserve
- *                        circular references in the object. If performance is important, try removing the circular
- *                        reference from the object (set to undefined) and then add it back manually after cloning
- *                        instead of using this option.
- * @param options.debug Whether to shoe console.debug messages
- * @param options.proto Copy prototype properties as well as own properties into the new object.
- *                      It's marginally faster to allow enumerable properties on the prototype to be copied into the
- *                      cloned object (not onto it's prototype, directly onto the object).
- */
-export function clone(object: any, options?: { checkResult?: boolean; circles?: boolean; proto?: boolean }) {
-  const config = {
-    checkResult: true,
-    circles: true,
-    debug: inspector.url() !== undefined,
-    proto: false,
-    ...options,
-  };
-
-  try {
-    const cloned = rfdc(config)(object);
-    if (config.checkResult && !util.isDeepStrictEqual(object, cloned)) {
-      throw new Error('Cloned object differs from original object');
-    }
-    return cloned;
-  } catch (e) {
-    if (!config.circles) {
-      if (config.debug) {
-        console.debug(e, config, object, 'automatic try to use rfdc with circles');
-      }
-      try {
-        const clonedWithCircles = rfdc({
-          ...config,
-          circles: true,
-        })(object);
-        if (config.checkResult && !util.isDeepStrictEqual(object, clonedWithCircles)) {
-          throw new Error('Cloned object differs from original object', { cause: e });
-        }
-        return clonedWithCircles;
-      } catch (innerError) {
-        if (config.debug) {
-          console.debug(innerError, 'rfcd with circles did not work => automatic use of _.clone!');
-        }
-        return _.cloneDeep(object);
-      }
-    } else {
-      if (config.debug) {
-        console.debug(e, config, object, 'automatic try to use _.clone instead rfdc');
-      }
-      return _.cloneDeep(object);
-    }
-  }
-}
-
 /**
  * Combines objects to a new single plain object and ignores undefined
  */
@@ -410,23 +360,6 @@ export function combinePlain(...args: Record<any, any>[]): any {
   return assignPlain({}, ...args);
 }
 
-/**
- * Get deep frozen object
- */
-export function deepFreeze(object: any, visited: WeakSet<object> = new WeakSet()) {
-  if (!object || typeof object !== 'object') {
-    return object;
-  }
-  if (visited.has(object)) {
-    return object;
-  }
-  visited.add(object);
-  for (const [key, value] of Object.entries(object)) {
-    object[key] = deepFreeze(value, visited);
-  }
-  return Object.freeze(object);
-}
-
 /**
  * Standard error function
  */

package/src/core/common/helpers/service.helper.ts

@@ -1,10 +1,10 @@
-import { UnauthorizedException } from '@nestjs/common';
 import bcrypt = require('bcrypt');
 import { sha256 } from 'js-sha256';
 import _ = require('lodash');
 import { Types } from 'mongoose';
 
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
 import { PrepareInputOptions } from '../interfaces/prepare-input-options.interface';
 import { PrepareOutputOptions } from '../interfaces/prepare-output-options.interface';
 import { ResolveSelector } from '../interfaces/resolve-selector.interface';
@@ -151,15 +151,17 @@ export async function prepareInput<T = any>(
     value === undefined && delete input[key];
   }
 
-  // Process roles
+  // Process roles — 403 when authenticated, 401 otherwise (see accessDeniedException). The rejected
+  // roles are logged rather than returned: the client gets the translatable ErrorCode the guards use.
   if (config.checkRoles && (input as Record<string, any>).roles && !currentUser?.hasRole?.(RoleEnum.ADMIN)) {
     if (!(currentUser as any)?.roles) {
-      throw new UnauthorizedException('Missing roles of current user');
+      throw accessDeniedException(currentUser);
     } else {
       const allowedRoles = _.intersection((input as Record<string, any>).roles, (currentUser as any).roles);
       if (allowedRoles.length !== (input as Record<string, any>).roles.length) {
         const missingRoles = _.difference((input as Record<string, any>).roles, (currentUser as any).roles);
-        throw new UnauthorizedException(`Current user not allowed setting roles: ${missingRoles}`);
+        console.debug(`Current user not allowed setting roles: ${missingRoles}`);
+        throw accessDeniedException(currentUser);
       }
       (input as Record<string, any>).roles = allowedRoles;
     }

package/src/core/common/inputs/combined-filter.input.ts

@@ -1,57 +1,10 @@
-import { InputType } from '@nestjs/graphql';
-
-import { Restricted } from '../decorators/restricted.decorator';
-import { UnifiedField } from '../decorators/unified-field.decorator';
-import { LogicalOperatorEnum } from '../enums/logical-operator.enum';
-import { RoleEnum } from '../enums/role.enum';
-import { maps } from '../helpers/model.helper';
-import { CoreInput } from './core-input.input';
-import { FilterInput } from './filter.input';
-
-@InputType({
-  description: 'Combination of multiple filters via logical operator',
-})
-@Restricted(RoleEnum.S_EVERYONE)
-export class CombinedFilterInput extends CoreInput {
-  /**
-   * Logical Operator to combine filters
-   */
-  @UnifiedField({
-    description: 'Logical Operator to combine filters',
-    enum: LogicalOperatorEnum,
-    roles: RoleEnum.S_EVERYONE,
-  })
-  logicalOperator: LogicalOperatorEnum = undefined;
-
-  /**
-   * Filters to combine via logical operator
-   */
-  @UnifiedField({
-    description: 'Filters to combine via logical operator',
-    isOptional: true,
-    roles: RoleEnum.S_EVERYONE,
-    type: () => FilterInput,
-  })
-  filters: FilterInput[] = undefined;
-
-  // ===================================================================================================================
-  // Methods
-  // ===================================================================================================================
-
-  /**
-   * Mapping for Subtypes
-   */
-  override map(
-    data: Partial<this> | Record<string, any>,
-    options: {
-      cloneDeep?: boolean;
-      funcAllowed?: boolean;
-      mapId?: boolean;
-    } = {},
-  ): this {
-    super.map(data, options);
-    this.filters = maps(data.filters, FilterInput, options.cloneDeep);
-    Object.keys(this).forEach((key) => this[key] === undefined && delete this[key]);
-    return this;
-  }
-}
+/**
+ * `CombinedFilterInput` is declared in `./filter.input` — the two classes are mutually recursive
+ * and must live in one module, or the cycle between them crashes SWC-compiled builds with
+ * `ReferenceError: Cannot access 'CombinedFilterInput' before initialization`. See the docblock in
+ * `./filter.input` for the full analysis.
+ *
+ * This file remains only so existing deep imports of `.../inputs/combined-filter.input` keep
+ * resolving. Do NOT move the class back here.
+ */
+export { CombinedFilterInput } from './filter.input';

package/src/core/common/inputs/filter.input.ts

@@ -1,12 +1,103 @@
+/**
+ * Filter inputs.
+ *
+ * `CombinedFilterInput` and `FilterInput` are mutually recursive: a filter may contain a combined
+ * filter, and a combined filter contains a list of filters. They therefore live in ONE module, and
+ * `CombinedFilterInput` is declared FIRST — that ordering is load-bearing, not cosmetic.
+ *
+ * They used to sit in two files that imported each other. `FilterInput` referenced
+ * `CombinedFilterInput` EAGERLY — in a decorator argument (`type: CombinedFilterInput`) and in the
+ * `design:type` metadata `emitDecoratorMetadata` emits for `combinedFilter?: CombinedFilterInput`.
+ * Decorator arguments and that metadata are evaluated at CLASS-DEFINITION time, i.e. while the
+ * module is still initializing. On a cycle that reads a class binding still in its temporal dead
+ * zone, and under SWC → CommonJS it threw:
+ *
+ *   ReferenceError: Cannot access 'CombinedFilterInput' before initialization
+ *
+ * That was not hypothetical — `require('.../combined-filter.input.js')` crashed. It only stayed
+ * hidden because the package barrel happens to pull `filter.input` in first via other importers
+ * (`filter.args`, `filter.helper`), so entering through the barrel masked it. A deep import, a unit
+ * test importing the input directly, or a reordering of `src/index.ts` would all have detonated it.
+ *
+ * Making the reference lazy does NOT fix it: `type: () => CombinedFilterInput` still leaves the
+ * eager `design:type` metadata behind, and SWC's `typeof` guard does not protect the member
+ * expression it compiles to. The only real fix is to remove the import edge — hence one module.
+ *
+ * Within a single module the problem disappears: `FilterInput` reads `CombinedFilterInput` at
+ * definition time, and by then it is already initialized. The reverse direction is safe because
+ * `CombinedFilterInput` only reaches `FilterInput` lazily (a `() => FilterInput` thunk and a method
+ * body), never at definition time.
+ *
+ * `combined-filter.input.ts` remains as a re-export so existing deep imports keep working.
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)" for the general rule.
+ */
 import { InputType } from '@nestjs/graphql';
 
 import { Restricted } from '../decorators/restricted.decorator';
 import { UnifiedField } from '../decorators/unified-field.decorator';
+import { LogicalOperatorEnum } from '../enums/logical-operator.enum';
 import { RoleEnum } from '../enums/role.enum';
-import { CombinedFilterInput } from './combined-filter.input';
+import { maps } from '../helpers/model.helper';
 import { CoreInput } from './core-input.input';
 import { SingleFilterInput } from './single-filter.input';
 
+/**
+ * Combination of multiple filters via logical operator.
+ *
+ * Declared BEFORE `FilterInput` on purpose — `FilterInput` dereferences this class at
+ * class-definition time, so it must already be initialized. See the module docblock.
+ */
+@InputType({
+  description: 'Combination of multiple filters via logical operator',
+})
+@Restricted(RoleEnum.S_EVERYONE)
+export class CombinedFilterInput extends CoreInput {
+  /**
+   * Logical Operator to combine filters
+   */
+  @UnifiedField({
+    description: 'Logical Operator to combine filters',
+    enum: LogicalOperatorEnum,
+    roles: RoleEnum.S_EVERYONE,
+  })
+  logicalOperator: LogicalOperatorEnum = undefined;
+
+  /**
+   * Filters to combine via logical operator
+   *
+   * The `() => FilterInput` thunk is required: `FilterInput` is declared below, so an eager
+   * reference here would read it before initialization.
+   */
+  @UnifiedField({
+    description: 'Filters to combine via logical operator',
+    isOptional: true,
+    roles: RoleEnum.S_EVERYONE,
+    type: () => FilterInput,
+  })
+  filters: FilterInput[] = undefined;
+
+  // ===================================================================================================================
+  // Methods
+  // ===================================================================================================================
+
+  /**
+   * Mapping for Subtypes
+   */
+  override map(
+    data: Partial<this> | Record<string, any>,
+    options: {
+      cloneDeep?: boolean;
+      funcAllowed?: boolean;
+      mapId?: boolean;
+    } = {},
+  ): this {
+    super.map(data, options);
+    this.filters = maps(data.filters, FilterInput, options.cloneDeep);
+    Object.keys(this).forEach((key) => this[key] === undefined && delete this[key]);
+    return this;
+  }
+}
+
 /**
  * Input for filtering. The `singleFilter` will be ignored if the `combinedFilter` is set.
  */

package/src/core/common/services/config.service.ts

@@ -4,7 +4,10 @@ import { BehaviorSubject, firstValueFrom } from 'rxjs';
 import { filter, map } from 'rxjs/operators';
 
 import { merge } from '../helpers/config.helper';
-import { clone, deepFreeze } from '../helpers/input.helper';
+// Import from the clone.helper LEAF, never from input.helper: input.helper imports
+// restricted.decorator, which reaches back here via core-tenant.helpers — that cycle is what the
+// extraction removed. See clone.helper's docblock.
+import { clone, deepFreeze } from '../helpers/clone.helper';
 import { IServerOptions } from '../interfaces/server-options.interface';
 
 /**

package/src/core/modules/ai/core-ai.constants.ts

@@ -0,0 +1,92 @@
+/**
+ * Dependency-injection tokens of the AI module.
+ *
+ * They live in a dedicated, import-free leaf file — never in a service or in `core-ai.module.ts` —
+ * so that no file needing a token has to import the file that declares it, and no import cycle can
+ * form around one.
+ *
+ * On a cycle, a token read at MODULE-EVALUATION time — inside an `@Inject()` decorator argument, in
+ * the `design:paramtypes` metadata `emitDecoratorMetadata` emits, or in a static field initializer —
+ * reads a `const` still in its temporal dead zone, and SWC-compiled builds (`nest start -b swc`) die
+ * at startup with:
+ *
+ *   ReferenceError: Cannot access 'AI_CONNECTION_MODEL' before initialization
+ *
+ * These tokens were previously declared across eleven `*.service.ts` files, every one of which is
+ * imported by `core-ai.module.ts` and injects tokens through constructor decorators. Nothing had
+ * crashed — the graph happened to be acyclic — but a single back-import from any of those services
+ * would have armed it, and `tsc`, `pnpm test` and `oxlint` are ALL blind to that. Only
+ * `pnpm run check:swc-tdz` sees it.
+ *
+ * A file that imports nothing can never be mid-evaluation when someone imports it, in any module
+ * system, under any compiler. Keep this file import-free.
+ *
+ * The old locations re-export their tokens, so every existing import path still resolves.
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+
+// ---- budget ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_BUDGET_LIMIT_CLASS = 'AI_BUDGET_LIMIT_CLASS';
+/** Mongoose injection token. */
+export const AI_BUDGET_LIMIT_MODEL = 'AiBudgetLimit';
+
+// ---- connection-preference ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_CONNECTION_PREFERENCE_CLASS = 'AI_CONNECTION_PREFERENCE_CLASS';
+/** Mongoose injection token. */
+export const AI_CONNECTION_PREFERENCE_MODEL = 'AiConnectionPreference';
+
+// ---- connection ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_CONNECTION_CLASS = 'AI_CONNECTION_CLASS';
+/** Mongoose injection token. */
+export const AI_CONNECTION_MODEL = 'AiConnection';
+
+// ---- conversation ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_CONVERSATION_CLASS = 'AI_CONVERSATION_CLASS';
+/** Mongoose injection token. */
+export const AI_CONVERSATION_MODEL = 'AiConversation';
+
+// ---- interaction ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_INTERACTION_CLASS = 'AI_INTERACTION_CLASS';
+/** Mongoose injection token. */
+export const AI_INTERACTION_MODEL = 'AiInteraction';
+
+// ---- mode ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_MODE_CLASS = 'AI_MODE_CLASS';
+/** Mongoose injection token. */
+export const AI_MODE_MODEL = 'AiMode';
+
+// ---- prompt-hint ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_PROMPT_HINT_CLASS = 'AI_PROMPT_HINT_CLASS';
+/** Mongoose injection token. */
+export const AI_PROMPT_HINT_MODEL = 'AiPromptHint';
+
+// ---- prompt ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_PROMPT_CLASS = 'AI_PROMPT_CLASS';
+/** Mongoose injection token. */
+export const AI_PROMPT_MODEL = 'AiPrompt';
+
+// ---- slot ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_SLOT_CLASS = 'AI_SLOT_CLASS';
+/** Mongoose injection token. */
+export const AI_SLOT_MODEL = 'AiSlot';
+
+// ---- tool-grant ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_TOOL_GRANT_CLASS = 'AI_TOOL_GRANT_CLASS';
+/** Mongoose injection token. */
+export const AI_TOOL_GRANT_MODEL = 'AiToolGrant';
+
+// ---- tool-policy ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_TOOL_POLICY_CLASS = 'AI_TOOL_POLICY_CLASS';
+/** Mongoose injection token. */
+export const AI_TOOL_POLICY_MODEL = 'AiToolPolicy';

package/src/core/modules/ai/index.ts

@@ -20,6 +20,7 @@ export * from './inputs/core-ai-slot-update.input';
 export * from './inputs/core-ai-prompt.input';
 export * from './hooks/ai-hook.base';
 export * from './hooks/ai-hook.registry';
+export * from './interfaces/ai-interaction-record.interface';
 export * from './interfaces/ai-hook.interface';
 export * from './interfaces/ai-placeholder.interface';
 export * from './interfaces/ai-tool.interface';

package/src/core/modules/ai/interfaces/ai-interaction-record.interface.ts

@@ -0,0 +1,34 @@
+/**
+ * The record passed to `CoreAiService.audit()` for each prompt run.
+ *
+ * It lives here, in an import-free leaf, rather than in `core-ai.service.ts` — and that is
+ * load-bearing, not tidiness.
+ *
+ * `core-ai.service` imports `core-ai-interaction.service` (it needs the class), and
+ * `core-ai-interaction.service` needs this type back. Declared in the service, that pair forms an
+ * import cycle. It never crashed for exactly one reason: the type was pulled in with `import type`,
+ * which both tsc and SWC erase, so no `require()` was emitted and the cycle was never real at
+ * runtime.
+ *
+ * That is a single keyword of protection, on a file where `core-ai.service` has a constructor
+ * `@Inject`, so `emitDecoratorMetadata` emits `design:paramtypes` at module-evaluation time — the
+ * exact eval-time dereference that turns a cycle fatal. An IDE "organize imports" or a lint autofix
+ * widening `import type` to a plain `import` would have armed it silently, and `tsc`, `pnpm test`
+ * and `oxlint` are ALL blind to that (vitest runs SWC through Vite's cycle-tolerant module runner).
+ * Only `pnpm run check:swc-tdz` would have caught it — after the fact.
+ *
+ * Moving the type out removes the edge entirely, so the cycle no longer exists rather than merely
+ * being disarmed. `core-ai.service` re-exports it, so every existing import path still resolves.
+ *
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+export interface AiInteractionRecord {
+  actions: { name: string; success: boolean }[];
+  connectionId: string;
+  iterations: number;
+  prompt: string;
+  responseText: string;
+  tenantId?: string;
+  usage?: { completionTokens?: number; promptTokens?: number; totalTokens?: number };
+  userId?: string;
+}

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

@@ -11,10 +11,14 @@ 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';
+import { AI_BUDGET_LIMIT_CLASS, AI_BUDGET_LIMIT_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_BUDGET_LIMIT_CLASS, AI_BUDGET_LIMIT_MODEL } from '../core-ai.constants';
 
 /** Resolved effective limit for a scope. */
 export interface ResolvedAiBudgetLimit {

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

@@ -10,10 +10,14 @@ import {
   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';
+import { AI_CONNECTION_PREFERENCE_CLASS, AI_CONNECTION_PREFERENCE_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_CONNECTION_PREFERENCE_CLASS, AI_CONNECTION_PREFERENCE_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD + lookup for {@link CoreAiConnectionPreference} (tenant/user connection

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

@@ -23,15 +23,14 @@ import { LlmProviderFactory } from '../providers/llm-provider.factory';
 import { AiCryptoService } from './ai-crypto.service';
 import { CoreAiConnectionPreferenceService } from './core-ai-connection-preference.service';
 
-/**
- * Mongoose injection token for the AI connection model.
- */
-export const AI_CONNECTION_MODEL = 'AiConnection';
+import { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI connection model constructor (used by CrudService mapping).
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
  */
-export const AI_CONNECTION_CLASS = 'AI_CONNECTION_CLASS';
+export { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD service for {@link CoreAiConnection} — the database-backed LLM

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

@@ -8,15 +8,14 @@ import { CoreAiConversationCreateInput } from '../inputs/core-ai-conversation-cr
 import { CoreAiConversationInput } from '../inputs/core-ai-conversation.input';
 import { AiConversationDocument, CoreAiConversation } from '../models/core-ai-conversation.model';
 
-/**
- * Mongoose injection token for the AI conversation model.
- */
-export const AI_CONVERSATION_MODEL = 'AiConversation';
+import { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI conversation model constructor.
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
  */
-export const AI_CONVERSATION_CLASS = 'AI_CONVERSATION_CLASS';
+export { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD service for multi-turn {@link CoreAiConversation}s.

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

@@ -5,17 +5,16 @@ import { Model } from 'mongoose';
 import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiInteractionDocument, CoreAiInteraction } from '../models/core-ai-interaction.model';
-import type { AiInteractionRecord } from './core-ai.service';
+import type { AiInteractionRecord } from '../interfaces/ai-interaction-record.interface';
 
-/**
- * Mongoose injection token for the AI interaction model.
- */
-export const AI_INTERACTION_MODEL = 'AiInteraction';
+import { AI_INTERACTION_CLASS, AI_INTERACTION_MODEL } from '../core-ai.constants';
 
 /**
- * DI token for the AI interaction model constructor.
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
  */
-export const AI_INTERACTION_CLASS = 'AI_INTERACTION_CLASS';
+export { AI_INTERACTION_CLASS, AI_INTERACTION_MODEL } from '../core-ai.constants';
 
 /**
  * CRUD + write service for {@link CoreAiInteraction} audit records.

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

@@ -6,8 +6,14 @@ import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { AiModeDocument, CoreAiMode } from '../models/core-ai-mode.model';
 
-export const AI_MODE_MODEL = 'AiMode';
-export const AI_MODE_CLASS = 'AI_MODE_CLASS';
+import { AI_MODE_CLASS, AI_MODE_MODEL } from '../core-ai.constants';
+
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_MODE_CLASS, AI_MODE_MODEL } from '../core-ai.constants';
 
 /**
  * Named-mode store. See {@link CoreAiMode}. Override via

package/src/core/modules/ai/services/core-ai-prompt-hint.service.ts

@@ -9,11 +9,14 @@ import { CoreAiPromptHintCreateInput } from '../inputs/core-ai-prompt-hint-creat
 import { CoreAiPromptHintInput } from '../inputs/core-ai-prompt-hint.input';
 import { AiPromptHintDocument, CoreAiPromptHint } from '../models/core-ai-prompt-hint.model';
 
-/** Mongoose injection token for the prompt-hint model. */
-export const AI_PROMPT_HINT_MODEL = 'AiPromptHint';
+import { AI_PROMPT_HINT_CLASS, AI_PROMPT_HINT_MODEL } from '../core-ai.constants';
 
-/** DI token for the prompt-hint model constructor. */
-export const AI_PROMPT_HINT_CLASS = 'AI_PROMPT_HINT_CLASS';
+/**
+ * @deprecated Import from `../core-ai.constants` instead. Re-exported only so existing deep imports
+ * keep working; the tokens are declared in an import-free leaf so no cycle can form around them
+ * (SWC-safe — see core-ai.constants.ts).
+ */
+export { AI_PROMPT_HINT_CLASS, AI_PROMPT_HINT_MODEL } from '../core-ai.constants';
 
 /** A failure signal recorded by the orchestrator for the learning loop. */
 export interface AiPromptFeedbackSignal {