@futdevpro/nts-dynamo 1.15.104 → 1.15.107

package/src/_modules/ai/_collections/ai-provider-error.util.ts

@@ -0,0 +1,98 @@
+import { DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
+
+import { DyNTS_AI_ProviderError } from '../_models/interfaces/dynts-ai-provider-error.interface';
+
+/**
+ * Provider-faithful hiba-alakok eloallitasa a FR-048 `settingsSchema` szabalysertesekhez — ugyanaz a
+ * hiba-alak, mint amit a valodi provider adna. A forras-igazsag a `settingsSchema` (SSoT); itt CSAK a
+ * hiba formazasa tortenik, szabaly-duplikatum nincs.
+ *
+ * **Pontossag (D4):** a hiba **strukturaja** (mezok + `code`/`type`) a dokumentalt provider-alak szerint
+ * keszult; a `message` SZOVEGE a valodi capture-ig kozelites. A gepileg fogyasztott resz (`reason`, `code`,
+ * `param`, `httpStatus`) a stabil — a byte-hu message a fixture-capture passzal pontosithato.
+ */
+export class DyNTS_AI_ProviderError_Util {
+
+  /** Az Anthropic provider-azonositoja (a hiba-alak valasztasahoz) — az enumbol, nem beegetett stringkent. */
+  private static readonly anthropicProviderId: string = DyFM_AI_Provider.Anthropic;
+
+  /**
+   * Nem tamogatott parameter → provider-hu HTTP 400 hiba-leiro.
+   * @param set - provider-azonosito + modell-azonosito + a kifogasolt parameter neve
+   */
+  static buildUnsupportedParamError(
+    set: {
+      provider: string,
+      model: string,
+      param: string,
+    }
+  ): DyNTS_AI_ProviderError {
+    if (set.provider === this.anthropicProviderId) {
+      return {
+        httpStatus: 400,
+        providerErrorBody: {
+          type: 'error',
+          error: {
+            type: 'invalid_request_error',
+            message: `${set.param}: Extra inputs are not permitted for model '${set.model}'.`,
+          },
+        },
+        reason: `invalid_request_error:${set.param}`,
+      };
+    }
+
+    return {
+      httpStatus: 400,
+      providerErrorBody: {
+        error: {
+          message: `Unsupported parameter: '${set.param}' is not supported with model '${set.model}'.`,
+          type: 'invalid_request_error',
+          param: set.param,
+          code: 'unsupported_parameter',
+        },
+      },
+      reason: `unsupported_parameter:${set.param}`,
+    };
+  }
+
+  /**
+   * Tamogatott parameter, de ERVENYTELEN ertek (tartomanyon kivul, vagy nem az engedett keszletbol) →
+   * provider-hu HTTP 400. Ez a `settingsSchema.constraints` (min/max/allowed) megsertese.
+   * @param set - provider + modell + parameter-nev + a rovid indoklas (pl. 'out of range 0..2')
+   */
+  static buildInvalidValueError(
+    set: {
+      provider: string,
+      model: string,
+      param: string,
+      detail: string,
+    }
+  ): DyNTS_AI_ProviderError {
+    if (set.provider === this.anthropicProviderId) {
+      return {
+        httpStatus: 400,
+        providerErrorBody: {
+          type: 'error',
+          error: {
+            type: 'invalid_request_error',
+            message: `${set.param}: ${set.detail} (model '${set.model}').`,
+          },
+        },
+        reason: `invalid_request_error:${set.param}`,
+      };
+    }
+
+    return {
+      httpStatus: 400,
+      providerErrorBody: {
+        error: {
+          message: `Invalid value for '${set.param}': ${set.detail} (model '${set.model}').`,
+          type: 'invalid_request_error',
+          param: set.param,
+          code: 'invalid_value',
+        },
+      },
+      reason: `invalid_value:${set.param}`,
+    };
+  }
+}

package/src/_modules/ai/_models/ai-input-interfaces.ts

@@ -1,117 +1,117 @@
-import { DyFM_AI_MessageRole } from '@futdevpro/fsm-dynamo/ai';
-import { DyFM_AI_Message } from '@futdevpro/fsm-dynamo/ai';
-import { DyFM_AI_CallSettings } from '@futdevpro/fsm-dynamo/ai';
-
-export interface DyFM_AI_Base_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> {
-  /* message: string; */
-  issuer: string;
-  settings?: T_AISettings;
-  debugLog?: boolean;
-  replaceThisInLog?: string;
-  getFullResponse?: boolean;
-}
-
-export interface DyFM_AI_Message_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Base_Input<T_AISettings> {
-  message: string;
-  conversation?: DyFM_AI_Message[];
-}
-
-export interface DyFM_AI_ListSelect_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings,
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  selectFrom: string[];
-}
-
-export interface DyFM_AI_GenericSelect_Input<
-  T, 
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  selectFrom: T[];
-}
-
-export interface DyFM_AI_MultiSelect_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  options: string[];
-}
-
-export interface DyFM_AI_GenericMultiSelect_Input<
-  T, 
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  options: T[];
-}
-
-export interface DyFM_AI_JSONKeysDescription_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  keysDescription: string;
-}
-
-export interface DyFM_AI_JSONExactKeys_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Message_Input<T_AISettings> {
-  keys: string[];
-}
-
-/* export interface DyFM_AI_SimpleMessage_Input extends DyFM_AI_Base_Input {
-  message: string;
-} */
-
-export interface DyFM_AI_ConversationBase_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_Base_Input<T_AISettings> {
-  message?: string;
-  conversation: DyFM_AI_Message[];
-  /* replaceThisInLog?: string; */
-}
-
-/* export interface DyFM_AI_ConversationMessage_Input extends DyFM_AI_ConversationBase_Input {
-  message: string;
-} */
-
-export interface DyFM_AI_ConversationSelect_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  selectFrom: string[];
-}
-
-export interface DyFM_AI_ConversationGenericSelect_Input<
-  T, 
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  selectFrom: T[];
-}
-
-export interface DyFM_AI_ConversationMultiSelect_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  options: string[];
-}
-
-export interface DyFM_AI_ConversationGenericMultiSelect_Input<
-  T, 
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  options: T[];
-}
-
-export interface DyFM_AI_ConversationJSONKeysDescription_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  keysDescription: string;
-}
-
-export interface DyFM_AI_ConversationJSONExactKeys_Input<
-  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
-> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
-  keys: string[];
-}
-
-/* export interface DyFM_AI_ConversationGetAnswer_Input extends DyFM_AI_ConversationBase_Input {
-  newMessage?: string;
-} */
+import { DyFM_AI_MessageRole } from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_AI_Message } from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_AI_CallSettings } from '@futdevpro/fsm-dynamo/ai';
+
+export interface DyFM_AI_Base_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> {
+  /* message: string; */
+  issuer: string;
+  settings?: T_AISettings;
+  debugLog?: boolean;
+  replaceThisInLog?: string;
+  getFullResponse?: boolean;
+}
+
+export interface DyFM_AI_Message_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Base_Input<T_AISettings> {
+  message: string;
+  conversation?: DyFM_AI_Message[];
+}
+
+export interface DyFM_AI_ListSelect_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings,
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  selectFrom: string[];
+}
+
+export interface DyFM_AI_GenericSelect_Input<
+  T, 
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  selectFrom: T[];
+}
+
+export interface DyFM_AI_MultiSelect_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  options: string[];
+}
+
+export interface DyFM_AI_GenericMultiSelect_Input<
+  T, 
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  options: T[];
+}
+
+export interface DyFM_AI_JSONKeysDescription_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  keysDescription: string;
+}
+
+export interface DyFM_AI_JSONExactKeys_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Message_Input<T_AISettings> {
+  keys: string[];
+}
+
+/* export interface DyFM_AI_SimpleMessage_Input extends DyFM_AI_Base_Input {
+  message: string;
+} */
+
+export interface DyFM_AI_ConversationBase_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_Base_Input<T_AISettings> {
+  message?: string;
+  conversation: DyFM_AI_Message[];
+  /* replaceThisInLog?: string; */
+}
+
+/* export interface DyFM_AI_ConversationMessage_Input extends DyFM_AI_ConversationBase_Input {
+  message: string;
+} */
+
+export interface DyFM_AI_ConversationSelect_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  selectFrom: string[];
+}
+
+export interface DyFM_AI_ConversationGenericSelect_Input<
+  T, 
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  selectFrom: T[];
+}
+
+export interface DyFM_AI_ConversationMultiSelect_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  options: string[];
+}
+
+export interface DyFM_AI_ConversationGenericMultiSelect_Input<
+  T, 
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  options: T[];
+}
+
+export interface DyFM_AI_ConversationJSONKeysDescription_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  keysDescription: string;
+}
+
+export interface DyFM_AI_ConversationJSONExactKeys_Input<
+  T_AISettings extends DyFM_AI_CallSettings = DyFM_AI_CallSettings
+> extends DyFM_AI_ConversationBase_Input<T_AISettings> {
+  keys: string[];
+}
+
+/* export interface DyFM_AI_ConversationGetAnswer_Input extends DyFM_AI_ConversationBase_Input {
+  newMessage?: string;
+} */

package/src/_modules/ai/_models/ai-test-generation-result.interface.ts

@@ -1,16 +1,16 @@
-/**
- * Teszt generalas eredmenye
- *
- * A provider-specifikus testGeneration() metodus ezt adja vissza,
- * tartalmazva a sikesseg flag-et, a valasz szoveget, a hasznalt modellt es a keses-idejet.
- */
-export interface DyNTS_AI_TestGeneration_Result {
-  /** sikeres volt-e a teszt generalas */
-  success: boolean;
-  /** a provider valasza (sikertelen eseten undefined) */
-  response?: string;
-  /** a hasznalt modell azonosito */
-  model: string;
-  /** a keres-valasz ido milliszekundumban */
-  latencyMs: number;
-}
+/**
+ * Teszt generalas eredmenye
+ *
+ * A provider-specifikus testGeneration() metodus ezt adja vissza,
+ * tartalmazva a sikesseg flag-et, a valasz szoveget, a hasznalt modellt es a keses-idejet.
+ */
+export interface DyNTS_AI_TestGeneration_Result {
+  /** sikeres volt-e a teszt generalas */
+  success: boolean;
+  /** a provider valasza (sikertelen eseten undefined) */
+  response?: string;
+  /** a hasznalt modell azonosito */
+  model: string;
+  /** a keres-valasz ido milliszekundumban */
+  latencyMs: number;
+}

package/src/_modules/ai/_models/interfaces/dynts-ai-provider-error.interface.ts

@@ -0,0 +1,16 @@
+/**
+ * Provider-faithful hiba-leiro — azt irja le, MILYEN hibat adna a valodi provider egy szabalytalan
+ * hivasra (FR-048). A `providerErrorBody` a provider NATIV hiba-JSON-ja (OpenAI:
+ * `{error:{message,type,param,code}}`, Anthropic: `{type:'error',error:{type,message}}`).
+ *
+ * Egy helyen definialva, hogy a Layer A validator (`DyNTS_AI_ModelConfig_Validator`) es a Layer B
+ * mock-fixture-ok UGYANAZT az alakot hasznaljak — nincs parhuzamos hiba-shape (SSoT).
+ */
+export interface DyNTS_AI_ProviderError {
+  /** A reprodukalando HTTP-statusz (pl. 400). */
+  httpStatus: number;
+  /** A provider nativ hiba-body-ja. */
+  providerErrorBody: unknown;
+  /** Rovid, gepi ok-jeloles (pl. 'unsupported_parameter:temperature'). */
+  reason: string;
+}

package/src/_modules/ai/_modules/ai-mock/_collections/aim-default-collection.util.spec.ts

@@ -0,0 +1,72 @@
+import { DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
+
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_ServiceCollection } from '../_models/interfaces/aim-service-collection.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from './aim-fixture-match.util';
+import { getDefaultAiMockServiceCollection } from './aim-default-collection.util';
+
+describe('| getDefaultAiMockServiceCollection (MP-7 SP-7.1)', () => {
+
+  function fixture(modality: DyNTS_AIMock_Modality, input: string): DyNTS_AIMock_Fixture {
+    return {
+      provider: 'open-ai',
+      model: 'gpt-5.4-mini',
+      modality: modality,
+      input: input,
+      inputHash: DyNTS_AIMock_FixtureMatch_Util.buildInputHash(input),
+      output: 'out',
+      capturedAt: '2026-07-21T00:00:00.000Z',
+    };
+  }
+
+  it('| default: mindharom schema-s provider registry-je be van kotve', () => {
+    const collection: DyNTS_AIMock_ServiceCollection = getDefaultAiMockServiceCollection();
+
+    expect(collection.registry.length).toBeGreaterThan(0);
+    expect(collection.registry.some((model) => model.provider === DyFM_AI_Provider.OpenAI)).toBe(true);
+    expect(collection.registry.some((model) => model.provider === DyFM_AI_Provider.Anthropic)).toBe(true);
+    expect(collection.registry.some((model) => model.provider === DyFM_AI_Provider.Google)).toBe(true);
+  });
+
+  it('| providers szukites: csak a kert provider modelljei', () => {
+    const collection: DyNTS_AIMock_ServiceCollection = getDefaultAiMockServiceCollection({
+      providers: [DyFM_AI_Provider.OpenAI],
+    });
+
+    expect(collection.registry.length).toBeGreaterThan(0);
+    expect(collection.registry.every((model) => model.provider === DyFM_AI_Provider.OpenAI)).toBe(true);
+  });
+
+  it('| service + store ossze van drotozva (a store futas kozben bovitheto)', () => {
+    const collection: DyNTS_AIMock_ServiceCollection = getDefaultAiMockServiceCollection();
+
+    expect(collection.store.size).toBe(0);
+
+    collection.store.register([fixture(DyNTS_AIMock_Modality.text, 'ping')]);
+
+    expect(collection.store.size).toBe(1);
+  });
+
+  it('| modalities szukites: csak az adott modalitasu fixture-ok kerulnek a tarba', () => {
+    const collection: DyNTS_AIMock_ServiceCollection = getDefaultAiMockServiceCollection({
+      modalities: [DyNTS_AIMock_Modality.embedding],
+      fixtures: [
+        fixture(DyNTS_AIMock_Modality.text, 'a'),
+        fixture(DyNTS_AIMock_Modality.embedding, 'b'),
+      ],
+    });
+
+    expect(collection.store.size).toBe(1);
+  });
+
+  it('| a bekototett fixture azonnal replay-elheto a service-en at', async () => {
+    const collection: DyNTS_AIMock_ServiceCollection = getDefaultAiMockServiceCollection({
+      fixtures: [fixture(DyNTS_AIMock_Modality.text, 'ping')],
+    });
+
+    await expectAsync(
+      collection.service.chatCompletion({ provider: 'open-ai', model: 'gpt-5.4-mini', input: 'ping' })
+    ).toBeResolvedTo('out');
+  });
+});

package/src/_modules/ai/_modules/ai-mock/_collections/aim-default-collection.util.ts

@@ -0,0 +1,71 @@
+import { DyFM_AI_ModelInfo, DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
+import { DyFM_OAI_Models } from '@futdevpro/fsm-dynamo/ai/open-ai';
+import { DyFM_AAI_Models } from '@futdevpro/fsm-dynamo/ai/anthropic';
+import { DyFM_GAI_Models } from '@futdevpro/fsm-dynamo/ai/google';
+
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_ServiceCollection } from '../_models/interfaces/aim-service-collection.interface';
+import { DyNTS_AIMock_FixtureStore_Service } from '../_services/aim-fixture-store.service';
+import { DyNTS_AIMock_Service } from '../_services/aim-mock.service';
+
+/**
+ * Provider → modell-registry hozzarendeles.
+ *
+ * CSAK azok a providerek szerepelnek, amelyeknek van FR-048 `settingsSchema`-juk — a `local-ai` es az
+ * `fdp-ai` szandekosan schema-mentes (runtime/gateway-fuggo), igy a registry-be emelesuk a validaciohoz
+ * semmit nem adna hozza. L. a fsm registry-fejleceket + `FR-048-LAYER-A.md`.
+ */
+const REGISTRY_BY_PROVIDER: Record<string, DyFM_AI_ModelInfo[]> = {
+  [DyFM_AI_Provider.OpenAI]: DyFM_OAI_Models,
+  [DyFM_AI_Provider.Anthropic]: DyFM_AAI_Models,
+  [DyFM_AI_Provider.Google]: DyFM_GAI_Models,
+};
+
+/** Provider-default: minden schema-val rendelkezo provider. */
+const DEFAULT_PROVIDERS: DyFM_AI_Provider[] = [
+  DyFM_AI_Provider.OpenAI,
+  DyFM_AI_Provider.Anthropic,
+  DyFM_AI_Provider.Google,
+];
+
+/**
+ * **Default-bundle factory** (MP-7 SP-7.1) — egy hivassal osszeallit egy hasznalatra kesz AI-mock keszletet:
+ * fixture-tar + mock-provider + a config-validaciohoz bekototott modell-registry.
+ *
+ * A `fdp-templates` `getApiDefaultSettings`-mintajat koveti: a consumer teszt-modul egyetlen sorral kap egy
+ * mukodo mockot, es DI-vel a valodi provider helyere teheti.
+ *
+ * @param set - opcionalis szukites: mely providerek registry-je legyen bekotve, mely modalitasok
+ *   fixture-oi keruljenek be, es a kezdo fixture-keszlet.
+ */
+export function getDefaultAiMockServiceCollection(
+  set?: {
+    /** Mely providerek registry-je legyen bekotve a config-validaciohoz (default: mind a harom schema-s). */
+    providers?: DyFM_AI_Provider[],
+    /** Ha meg van adva, CSAK az itt felsorolt modalitasu fixture-ok kerulnek a tarba. */
+    modalities?: DyNTS_AIMock_Modality[],
+    /** A kezdo (beegetett) fixture-keszlet. */
+    fixtures?: DyNTS_AIMock_Fixture[],
+  }
+): DyNTS_AIMock_ServiceCollection {
+  const providers: DyFM_AI_Provider[] = set?.providers?.length ? set.providers : DEFAULT_PROVIDERS;
+
+  const registry: DyFM_AI_ModelInfo[] = providers.reduce(
+    (all: DyFM_AI_ModelInfo[], provider: DyFM_AI_Provider) => all.concat(REGISTRY_BY_PROVIDER[provider] ?? []),
+    []
+  );
+
+  const allFixtures: DyNTS_AIMock_Fixture[] = set?.fixtures ?? [];
+  const fixtures: DyNTS_AIMock_Fixture[] = set?.modalities?.length ?
+    allFixtures.filter((fixture: DyNTS_AIMock_Fixture) => set.modalities.includes(fixture.modality)) :
+    allFixtures;
+
+  const store: DyNTS_AIMock_FixtureStore_Service = new DyNTS_AIMock_FixtureStore_Service(fixtures);
+
+  return {
+    store: store,
+    service: new DyNTS_AIMock_Service(store, registry),
+    registry: registry,
+  };
+}

package/src/_modules/ai/_modules/ai-mock/_collections/aim-fixture-match.util.spec.ts

@@ -0,0 +1,57 @@
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from './aim-fixture-match.util';
+
+describe('DyNTS_AIMock_FixtureMatch_Util', () => {
+
+  function req(overrides: Partial<DyNTS_AIMock_Request>): DyNTS_AIMock_Request {
+    return {
+      provider: 'open-ai',
+      model: 'gpt-4o-mini',
+      modality: DyNTS_AIMock_Modality.text,
+      config: { temperature: 0 },
+      input: 'ping',
+      ...overrides,
+    };
+  }
+
+  it('determinisztikus — azonos request kétszer → azonos kulcs', () => {
+    expect(DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({}))).toBe(
+      DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({}))
+    );
+  });
+
+  it('config-kulcs-sorrend független', () => {
+    const a: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ config: { temperature: 0, topP: 1 } }));
+    const b: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ config: { topP: 1, temperature: 0 } }));
+
+    expect(a).toBe(b);
+  });
+
+  it('input-whitespace független', () => {
+    const a: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ input: 'hello   world' }));
+    const b: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ input: '  hello world  ' }));
+
+    expect(a).toBe(b);
+  });
+
+  it('eltérő input → eltérő kulcs', () => {
+    const a: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ input: 'ping' }));
+    const b: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ input: 'pong' }));
+
+    expect(a).not.toBe(b);
+  });
+
+  it('eltérő modalitás → eltérő kulcs (azonos input mellett is)', () => {
+    const a: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ modality: DyNTS_AIMock_Modality.text }));
+    const b: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(req({ modality: DyNTS_AIMock_Modality.embedding }));
+
+    expect(a).not.toBe(b);
+  });
+
+  it('buildInputHash stabil ugyanarra a szövegre', () => {
+    expect(DyNTS_AIMock_FixtureMatch_Util.buildInputHash('alpha')).toBe(
+      DyNTS_AIMock_FixtureMatch_Util.buildInputHash('alpha')
+    );
+  });
+});

package/src/_modules/ai/_modules/ai-mock/_collections/aim-fixture-match.util.ts

@@ -0,0 +1,60 @@
+import * as crypto from 'crypto';
+
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+
+/**
+ * A fixture-match kulcs DETERMINISZTIKUS képzése. Cél: azonos „jelentésű" request → azonos kulcs,
+ * függetlenül a config-kulcsok sorrendjétől és az input whitespace-variánsaitól (különben false
+ * reject-on-unknown, l. HYPERPLAN D3 + MP-3 SP-3.1). NEM végez generálást — tiszta, hálózat-mentes.
+ */
+export class DyNTS_AIMock_FixtureMatch_Util {
+  /**
+   * A teljes match-kulcs: `provider|model|modality|<config-hash>|<input-hash>`.
+   * @param request - a mock-hívás bemenete
+   */
+  static buildMatchKey(request: DyNTS_AIMock_Request): string {
+    const configHash: string = this.hash(this.canonicalizeConfig(request.config ?? {}));
+    const inputHash: string = this.buildInputHash(request.input);
+
+    return `${request.provider}|${request.model}|${request.modality}|${configHash}|${inputHash}`;
+  }
+
+  /**
+   * Csak az input-hash (a `DyNTS_AIMock_Fixture.inputHash`-hez): a kanonizált input SHA-256-ja.
+   * @param input - a modalitás-függő bemenet
+   */
+  static buildInputHash(input: unknown): string {
+    return this.hash(this.canonicalizeInput(input));
+  }
+
+  /**
+   * Kulcs-rendezett, stabil szöveg egy config-objektumból (a config-kulcsok sorrend-függetlenségéhez).
+   * Megjegyzés: a nested-objektum mély-kanonizációja jövőbeli finomítás (a shallow key-sort a config-flat
+   * paramétereket — temperature/dimensions/size — fedi).
+   * @param config - a kanonizálandó config
+   */
+  private static canonicalizeConfig(config: Record<string, unknown>): string {
+    const sortedKeys: string[] = Object.keys(config).sort();
+    const parts: string[] = sortedKeys.map((key: string) => `${key}:${JSON.stringify(config[key])}`);
+
+    return parts.join('|');
+  }
+
+  /**
+   * Input-kanonizáció: string → trim + belső whitespace-összevonás; egyéb (pl. embedding-szöveg-tömb) →
+   * stabil JSON (a sorrend jelentős, pl. batch-embedding).
+   * @param input - a bemenet
+   */
+  private static canonicalizeInput(input: unknown): string {
+    if (typeof input === 'string') {
+      return input.trim().replace(/\s+/g, ' ');
+    }
+
+    return JSON.stringify(input);
+  }
+
+  /** SHA-256 hex az adott szövegből. */
+  private static hash(value: string): string {
+    return crypto.createHash('sha256').update(value).digest('hex');
+  }
+}