@futdevpro/nts-dynamo 1.15.104 → 1.15.107

package/src/_modules/ai/_modules/ai-mock/_services/aim-fixture-harness.service.ts

@@ -0,0 +1,127 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+import { DyFM_AI_ModelInfo, DyFM_AI_ModelRegistry_Util } from '@futdevpro/fsm-dynamo/ai';
+
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from '../_collections/aim-fixture-match.util';
+
+/**
+ * A D2 kolseg-cap altal TILTOTT modell-tier-ek (kisbetusen hasonlitva).
+ *
+ * Forras — a FR (`USER-INPUT.md`, 2026-06-22): „nem megyunk el a legmagasabb szintu modellekig, illetve nem
+ * megyunk el peldaul OpenAI Pro modellekig, de az alap, default es mini mikro modelleket szeretnem".
+ * Ezert tiltott: `pro` (gpt-5.5-pro / o3-pro / gemini-pro), `opus` (claude-opus), `flagship` (a legmagasabb
+ * szintu alap-modell). Engedett: mini / nano / legacy / flash / flash-lite / sonnet / haiku.
+ */
+const D2_BLOCKED_TIERS: string[] = [ 'pro', 'opus', 'flagship' ];
+
+/**
+ * **Fixture-generalo harness** (MP-3 SP-3.2) — VALODI provider-valaszbol keszit beegetheto fixture-t.
+ *
+ * **Ket egymastol fuggetlen biztonsagi zar, mert ez az egyetlen pont, ahol valodi PENZ folyhat el:**
+ * 1. **Spend-guard** — az `allowRealSpend` alapertelmezese `false`. Amig nincs EXPLICIT bekapcsolva, a harness
+ *    **el sem hivja** az injektalt generatort. Igy meg egy veletlenul bekototott valodi generator sem tud
+ *    hivast inditani. (G1 kapu: a bekapcsolas user-jovahagyashoz kotott.)
+ * 2. **D2 tier-cap** — a Pro / Opus / flagship tier-u modelleket elutasitja MEG a generator hivasa elott.
+ *
+ * A generator INJEKTALT (`(request) => Promise<unknown>`), ezert a harness maga soha nem fuggo halozattol —
+ * a tesztek stub-generatorral futnak, valodi hivas nelkul.
+ */
+export class DyNTS_AIMock_FixtureHarness_Service {
+
+  /** A valodi (vagy stub) generalo fuggveny — a harness NEM tud halozatot hivni sajat maga. */
+  private readonly generator: (request: DyNTS_AIMock_Request) => Promise<unknown>;
+
+  /** Modell-registry a tier-cap ellenorzeshez. */
+  private readonly registry: DyFM_AI_ModelInfo[];
+
+  /** Spend-guard: amig `false`, a generator NEM hivodik meg. Default: `false`. */
+  private readonly allowRealSpend: boolean;
+
+  /** Tiltott tier-ek (default: a D2 keszlet). */
+  private readonly blockedTiers: string[];
+
+  /** ISO-timestamp forras (injektalhato a determinisztikus tesztekhez). */
+  private readonly nowIso: () => string;
+
+  /**
+   * @param set - generator + registry + a ket biztonsagi zar beallitasa.
+   */
+  constructor(
+    set: {
+      generator: (request: DyNTS_AIMock_Request) => Promise<unknown>,
+      registry?: DyFM_AI_ModelInfo[],
+      /** CSAK explicit `true` eseten hivodik meg a generator (G1). Default: `false`. */
+      allowRealSpend?: boolean,
+      blockedTiers?: string[],
+      nowIso?: () => string,
+    }
+  ) {
+    this.generator = set.generator;
+    this.registry = set.registry ?? [];
+    this.allowRealSpend = set.allowRealSpend === true;
+    this.blockedTiers = set.blockedTiers ?? D2_BLOCKED_TIERS;
+    this.nowIso = set.nowIso ?? ((): string => new Date().toISOString());
+  }
+
+  /**
+   * Egy fixture rogzitese valodi generalasbol. A ket zar sorrendje: spend-guard → tier-cap → generator.
+   * @param request - a rogzitendo hivas (provider + model + modality + config + input)
+   */
+  async capture(request: DyNTS_AIMock_Request): Promise<DyNTS_AIMock_Fixture> {
+    this.assertSpendAllowed(request);
+    this.assertTierAllowed(request);
+
+    const output: unknown = await this.generator(request);
+
+    return {
+      provider: request.provider,
+      model: request.model,
+      modality: request.modality,
+      config: request.config,
+      input: request.input,
+      inputHash: DyNTS_AIMock_FixtureMatch_Util.buildInputHash(request.input),
+      output: output,
+      capturedAt: this.nowIso(),
+      sourceModel: request.model,
+    };
+  }
+
+  /** 1. zar — a spend-guard. */
+  private assertSpendAllowed(request: DyNTS_AIMock_Request): void {
+    if (this.allowRealSpend) {
+      return;
+    }
+
+    throw new DyFM_Error({
+      message: `[ai-mock] real generation is DISABLED (spend-guard). Model '${request.provider}:${request.model}'. ` +
+        'Set allowRealSpend=true only with explicit approval (G1 gate).',
+      userMessage: 'Real AI generation is disabled.',
+      errorCode: 'DyNTS-AIMOCK-SPEND',
+    });
+  }
+
+  /** 2. zar — a D2 tier-cap. Ismeretlen modell (nincs registry-ben) → NEM engedjuk (honesty). */
+  private assertTierAllowed(request: DyNTS_AIMock_Request): void {
+    const modelInfo: DyFM_AI_ModelInfo = DyFM_AI_ModelRegistry_Util.findModelInfo(this.registry, request.model);
+    const tier: string = (modelInfo?.tier ?? '').toLowerCase();
+
+    if (!modelInfo) {
+      throw new DyFM_Error({
+        message: `[ai-mock] model '${request.model}' is not in the registry — tier cannot be verified, ` +
+          'refusing to generate (D2 cost-cap, honesty).',
+        userMessage: 'Unknown AI model for fixture generation.',
+        errorCode: 'DyNTS-AIMOCK-TIER',
+      });
+    }
+
+    if (this.blockedTiers.includes(tier)) {
+      throw new DyFM_Error({
+        message: `[ai-mock] model '${request.model}' has blocked tier '${modelInfo.tier}' (D2 cost-cap: ` +
+          `${this.blockedTiers.join(', ')}). Use a mini/nano/flash tier model for fixtures.`,
+        userMessage: 'This AI model tier is not allowed for fixture generation.',
+        errorCode: 'DyNTS-AIMOCK-TIER',
+      });
+    }
+  }
+}

package/src/_modules/ai/_modules/ai-mock/_services/aim-fixture-pipeline.spec.ts

@@ -0,0 +1,105 @@
+import { DyFM_AI_ModelInfo, DyFM_AI_ModelType, DyFM_AI_Provider } from '@futdevpro/fsm-dynamo/ai';
+
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_FixtureSerializer_Util } from '../_collections/aim-fixture-serializer.util';
+import { DyNTS_AIMock_FixtureHarness_Service } from './aim-fixture-harness.service';
+import { DyNTS_AIMock_FixtureStore_Service } from './aim-fixture-store.service';
+import { DyNTS_AIMock_Service } from './aim-mock.service';
+
+/**
+ * **End-to-end pipeline-bizonyitas (MP-3 + MP-4), NULLA koltessel.**
+ *
+ * A teljes fixture-eletciklust vegigviszi egyetlen teszben:
+ *   `harness.capture()` (stub-generator) → `serializer.toConstantFile()` (beegetett konstans) →
+ *   visszaolvasas (a generalt tomb-literal ERVENYES JSON) → `store.register()` → `service.chatCompletion()`.
+ *
+ * Ez azt igazolja, hogy a beegetett artefaktum **hianytalanul visszaallithato mukodo fixture-re** — vagyis a
+ * G1 (fizetos generalas) jovahagyasakor a gepezet mar bizonyitottan mukodik, csak valodi generatort kap.
+ */
+describe('| ai-mock fixture-pipeline (end-to-end, stub-generatorral)', () => {
+
+  const registry: DyFM_AI_ModelInfo[] = [
+    {
+      id: 'cheap-mini',
+      provider: DyFM_AI_Provider.OpenAI,
+      modelType: DyFM_AI_ModelType.Chat,
+      tier: 'mini',
+      capabilities: {} as any,
+    },
+  ];
+
+  const request: DyNTS_AIMock_Request = {
+    provider: 'open-ai',
+    model: 'cheap-mini',
+    modality: DyNTS_AIMock_Modality.text,
+    config: { maxTokens: 32 },
+    input: 'Mi a fovarosa Magyarorszagnak?',
+  };
+
+  /** A beegetett konstans-fajlbol visszaolvassa a fixture-tombot (a tomb-literal ervenyes JSON). */
+  function parseBack(source: string): DyNTS_AIMock_Fixture[] {
+    const start: number = source.indexOf('= [') + 2;
+    const end: number = source.lastIndexOf('];') + 1;
+
+    return JSON.parse(source.slice(start, end));
+  }
+
+  it('| capture → serialize → parse-back → store → replay: a beegetett ertek jon vissza', async () => {
+    // 1) GENERALAS — stub-generator, NULLA valodi hivas. A spend-guard explicit engedelyezve CSAK a stubhoz.
+    const harness: DyNTS_AIMock_FixtureHarness_Service = new DyNTS_AIMock_FixtureHarness_Service({
+      generator: async (): Promise<unknown> => 'Budapest.',
+      registry: registry,
+      allowRealSpend: true,
+      nowIso: (): string => '2026-07-21T00:00:00.000Z',
+    });
+
+    const captured: DyNTS_AIMock_Fixture = await harness.capture(request);
+
+    // 2) BEEGETES — determinisztikus TS-konstans fajl tartalma
+    const fileSource: string = DyNTS_AIMock_FixtureSerializer_Util.toConstantFile({
+      constName: 'DyNTS_AIMock_PipelineFixtures',
+      fixtures: [ captured ],
+    });
+
+    expect(fileSource).toContain('export const DyNTS_AIMock_PipelineFixtures');
+
+    // 3) VISSZAOLVASAS — a beegetett artefaktumbol ujra fixture-objektum
+    const reloaded: DyNTS_AIMock_Fixture[] = parseBack(fileSource);
+
+    expect(reloaded.length).toBe(1);
+    expect(reloaded[0].inputHash).toBe(captured.inputHash);
+
+    // 4) REPLAY — a visszaolvasott fixture-t a store-ba tolve a mock ugyanazt adja vissza
+    const store: DyNTS_AIMock_FixtureStore_Service = new DyNTS_AIMock_FixtureStore_Service(reloaded);
+    const service: DyNTS_AIMock_Service = new DyNTS_AIMock_Service(store, registry);
+
+    await expectAsync(
+      service.chatCompletion({
+        provider: 'open-ai',
+        model: 'cheap-mini',
+        config: { maxTokens: 32 },
+        input: 'Mi a fovarosa Magyarorszagnak?',
+      })
+    ).toBeResolvedTo('Budapest.');
+  });
+
+  it('| a beegetes/visszaolvasas kortje IDEMPOTENS (ketszer szerializalva azonos fajl)', async () => {
+    const harness: DyNTS_AIMock_FixtureHarness_Service = new DyNTS_AIMock_FixtureHarness_Service({
+      generator: async (): Promise<unknown> => 'Budapest.',
+      registry: registry,
+      allowRealSpend: true,
+      nowIso: (): string => '2026-07-21T00:00:00.000Z',
+    });
+
+    const captured: DyNTS_AIMock_Fixture = await harness.capture(request);
+    const first: string = DyNTS_AIMock_FixtureSerializer_Util.toConstantFile({ constName: 'X', fixtures: [ captured ] });
+    const second: string = DyNTS_AIMock_FixtureSerializer_Util.toConstantFile({
+      constName: 'X',
+      fixtures: parseBack(first),
+    });
+
+    expect(second).toBe(first);
+  });
+});

package/src/_modules/ai/_modules/ai-mock/_services/aim-fixture-store.service.spec.ts

@@ -0,0 +1,50 @@
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from '../_collections/aim-fixture-match.util';
+import { DyNTS_AIMock_FixtureStore_Service } from './aim-fixture-store.service';
+
+describe('DyNTS_AIMock_FixtureStore_Service', () => {
+
+  const fixture: DyNTS_AIMock_Fixture = {
+    provider: 'open-ai',
+    model: 'gpt-4o-mini',
+    modality: DyNTS_AIMock_Modality.text,
+    config: { temperature: 0 },
+    input: 'ping',
+    inputHash: DyNTS_AIMock_FixtureMatch_Util.buildInputHash('ping'),
+    output: 'pong',
+    capturedAt: '2026-07-21T00:00:00.000Z',
+  };
+
+  const hitRequest: DyNTS_AIMock_Request = {
+    provider: 'open-ai',
+    model: 'gpt-4o-mini',
+    modality: DyNTS_AIMock_Modality.text,
+    config: { temperature: 0 },
+    input: 'ping',
+  };
+
+  it('register + resolve hit → a fixture', () => {
+    const store: DyNTS_AIMock_FixtureStore_Service = new DyNTS_AIMock_FixtureStore_Service([fixture]);
+
+    expect(store.resolve(hitRequest)).toBe(fixture);
+    expect(store.has(hitRequest)).toBe(true);
+    expect(store.size).toBe(1);
+  });
+
+  it('resolve miss → undefined + has false', () => {
+    const store: DyNTS_AIMock_FixtureStore_Service = new DyNTS_AIMock_FixtureStore_Service([fixture]);
+    const miss: DyNTS_AIMock_Request = { ...hitRequest, input: 'unknown' };
+
+    expect(store.resolve(miss)).toBeUndefined();
+    expect(store.has(miss)).toBe(false);
+  });
+
+  it('resolve config-sorrend-független hit', () => {
+    const store: DyNTS_AIMock_FixtureStore_Service = new DyNTS_AIMock_FixtureStore_Service([fixture]);
+    const reordered: DyNTS_AIMock_Request = { ...hitRequest, config: { temperature: 0 } };
+
+    expect(store.resolve(reordered)).toBe(fixture);
+  });
+});

package/src/_modules/ai/_modules/ai-mock/_services/aim-fixture-store.service.ts

@@ -0,0 +1,65 @@
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from '../_collections/aim-fixture-match.util';
+
+/**
+ * A beégetett fixture-ök tára — match-kulcs → fixture Map (lazy-cache; a Map MAGA a cache). A fixture-öket
+ * konstans-blob-fájlokból (D6, git-tracked) importáljuk és `register`-rel adjuk be; a runtime-feloldás a
+ * `DyNTS_AIMock_FixtureMatch_Util.buildMatchKey`-en megy (config-sorrend- + input-whitespace-független).
+ * A reject-on-unknown (D3) NEM itt dől el — a `resolve` `undefined`-et ad, a hívó (`DyNTS_AIMock_Service`)
+ * dob strukturált „no-fixture" hibát. Ez a réteg tiszta, hálózat-mentes — NEM generál (SP-3.2 = G1 gate).
+ */
+export class DyNTS_AIMock_FixtureStore_Service {
+
+  /** match-kulcs → fixture. */
+  private readonly fixturesByKey: Map<string, DyNTS_AIMock_Fixture> = new Map();
+
+  /** @param fixtures opcionális kezdő-készlet (konstans-blob-okból). */
+  constructor(fixtures?: DyNTS_AIMock_Fixture[]) {
+    if (fixtures?.length) {
+      this.register(fixtures);
+    }
+  }
+
+  /**
+   * Fixture-ök beindexelése (match-kulcs szerint). Azonos kulcsú fixture felülírja a korábbit (last-wins).
+   * @param fixtures - a beégetett fixture-rekordok
+   */
+  register(fixtures: DyNTS_AIMock_Fixture[]): void {
+    for (const fixture of fixtures) {
+      this.fixturesByKey.set(this.keyOf(fixture), fixture);
+    }
+  }
+
+  /**
+   * Input-match feloldás: hit → fixture; miss → `undefined` (a reject-on-unknown a hívó dolga).
+   * @param request - a mock-hívás bemenete
+   */
+  resolve(request: DyNTS_AIMock_Request): DyNTS_AIMock_Fixture | undefined {
+    return this.fixturesByKey.get(DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(request));
+  }
+
+  /**
+   * Van-e fixture az adott request-re.
+   * @param request - a mock-hívás bemenete
+   */
+  has(request: DyNTS_AIMock_Request): boolean {
+    return this.fixturesByKey.has(DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(request));
+  }
+
+  /** A beindexelt fixture-ök száma. */
+  get size(): number {
+    return this.fixturesByKey.size;
+  }
+
+  /** A fixture match-kulcsa a saját nyers mezőiből (a `resolve`-val szimmetrikusan képezve). */
+  private keyOf(fixture: DyNTS_AIMock_Fixture): string {
+    return DyNTS_AIMock_FixtureMatch_Util.buildMatchKey({
+      provider: fixture.provider,
+      model: fixture.model,
+      modality: fixture.modality,
+      config: fixture.config,
+      input: fixture.input,
+    });
+  }
+}

package/src/_modules/ai/_modules/ai-mock/_services/aim-mock.service.spec.ts

@@ -0,0 +1,112 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+import { DyFM_AI_ModelInfo, DyFM_AI_ModelType, 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_FixtureMatch_Util } from '../_collections/aim-fixture-match.util';
+import { DyNTS_AIMock_FixtureStore_Service } from './aim-fixture-store.service';
+import { DyNTS_AIMock_Service } from './aim-mock.service';
+
+describe('DyNTS_AIMock_Service', () => {
+
+  const okFixture: DyNTS_AIMock_Fixture = {
+    provider: 'open-ai',
+    model: 'gpt-4o-mini',
+    modality: DyNTS_AIMock_Modality.text,
+    config: { temperature: 0 },
+    input: 'ping',
+    inputHash: DyNTS_AIMock_FixtureMatch_Util.buildInputHash('ping'),
+    output: 'pong',
+    capturedAt: '2026-07-21T00:00:00.000Z',
+  };
+
+  const errFixture: DyNTS_AIMock_Fixture = {
+    provider: 'open-ai',
+    model: 'gpt-4o-mini',
+    modality: DyNTS_AIMock_Modality.text,
+    config: { temperature: 0.5 },
+    input: 'bad',
+    inputHash: DyNTS_AIMock_FixtureMatch_Util.buildInputHash('bad'),
+    error: {
+      httpStatus: 400,
+      providerErrorBody: { error: { type: 'invalid_request_error', param: 'temperature', code: 'unsupported_parameter' } },
+      reason: 'unsupported_parameter:temperature',
+    },
+    capturedAt: '2026-07-21T00:00:00.000Z',
+  };
+
+  function makeService(fixtures: DyNTS_AIMock_Fixture[]): DyNTS_AIMock_Service {
+    return new DyNTS_AIMock_Service(new DyNTS_AIMock_FixtureStore_Service(fixtures));
+  }
+
+  it('replay hit → a beégetett output', async () => {
+    const service: DyNTS_AIMock_Service = makeService([okFixture]);
+
+    await expectAsync(
+      service.chatCompletion({ provider: 'open-ai', model: 'gpt-4o-mini', config: { temperature: 0 }, input: 'ping' })
+    ).toBeResolvedTo('pong');
+  });
+
+  it('miss → reject-on-unknown (DyNTS-AIMOCK-NOFIX), NEM silent', async () => {
+    const service: DyNTS_AIMock_Service = makeService([okFixture]);
+
+    try {
+      await service.chatCompletion({ provider: 'open-ai', model: 'gpt-4o-mini', input: 'unknown' });
+      fail('reject-on-unknown vártunk');
+    } catch (error) {
+      expect(error instanceof DyFM_Error).toBe(true);
+      if (error instanceof DyFM_Error) {
+        expect(error.message).toContain('no fixture');
+      }
+    }
+  });
+
+  it('FR-048 config-check: NEM támogatott param → provider-faithful 400, MÉG fixture-lookup előtt', async () => {
+    const registry: DyFM_AI_ModelInfo[] = [
+      {
+        id: 'gpt-4o-mini',
+        provider: DyFM_AI_Provider.OpenAI,
+        modelType: DyFM_AI_ModelType.Chat,
+        capabilities: {} as any,
+        settingsSchema: { unsupported: ['temperature'] },
+      },
+    ];
+    // A store URES → ha a config-check NEM futna, 'no fixture' jonne; igy bizonyitjuk a sorrendet.
+    const service: DyNTS_AIMock_Service = new DyNTS_AIMock_Service(
+      new DyNTS_AIMock_FixtureStore_Service([]),
+      registry
+    );
+
+    try {
+      await service.chatCompletion({ provider: 'open-ai', model: 'gpt-4o-mini', config: { temperature: 0.5 }, input: 'x' });
+      fail('provider-faithful 400-at vártunk');
+    } catch (error) {
+      expect(error instanceof DyFM_Error).toBe(true);
+      if (error instanceof DyFM_Error) {
+        expect(error.message).toContain('unsupported_parameter:temperature');
+      }
+    }
+  });
+
+  it('FR-048 config-check: registry nélkül permisszív (nem találgat) → a fixture-replay dönt', async () => {
+    const service: DyNTS_AIMock_Service = makeService([okFixture]);
+
+    await expectAsync(
+      service.chatCompletion({ provider: 'open-ai', model: 'gpt-4o-mini', config: { temperature: 0 }, input: 'ping' })
+    ).toBeResolvedTo('pong');
+  });
+
+  it('beégetett error → provider-faithful hiba (DyNTS-AIMOCK-PERR)', async () => {
+    const service: DyNTS_AIMock_Service = makeService([errFixture]);
+
+    try {
+      await service.chatCompletion({ provider: 'open-ai', model: 'gpt-4o-mini', config: { temperature: 0.5 }, input: 'bad' });
+      fail('provider-faithful hibát vártunk');
+    } catch (error) {
+      expect(error instanceof DyFM_Error).toBe(true);
+      if (error instanceof DyFM_Error) {
+        expect(error.message).toContain('provider-faithful error');
+      }
+    }
+  });
+});

package/src/_modules/ai/_modules/ai-mock/_services/aim-mock.service.ts

@@ -0,0 +1,142 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+import { DyFM_AI_ModelInfo } from '@futdevpro/fsm-dynamo/ai';
+
+import { DyNTS_AIMock_Modality } from '../_enums/aim-modality.enum';
+import { DyNTS_AI_ModelConfig_Validator } from '../../../_collections/ai-model-config-validator.util';
+import { DyNTS_AIMock_Request } from '../_models/interfaces/aim-request.interface';
+import { DyNTS_AIMock_Fixture } from '../_models/interfaces/aim-fixture.interface';
+import { DyNTS_AIMock_Error } from '../_models/interfaces/aim-error.interface';
+import { DyNTS_AIMock_CallInput } from '../_models/interfaces/aim-call-input.interface';
+import { DyNTS_AIMock_FixtureMatch_Util } from '../_collections/aim-fixture-match.util';
+import { DyNTS_AIMock_FixtureStore_Service } from './aim-fixture-store.service';
+
+/**
+ * A mock provider-surface (MP-4 SP-4.1) — a valódi AI-hívás kiváltása beégetett fixture-ökkel, outbound
+ * hívás NÉLKÜL. Négy modalitás-metódus (`chatCompletion`/`embed`/`generateImage`/`generateAudio`), mind a
+ * `DyNTS_AIMock_FixtureStore`-ból replay-el: hit → a beégetett kimenet; miss → strukturált reject-on-unknown
+ * (D3, NEM silent-fallback, NEM outbound); beégetett provider-faithful hiba → ugyanaz a hiba, mint a valódi
+ * providernél. A config-validáció (FR-048 reconciler validate-mode) a `settingsSchema` populálása UTÁN
+ * kötendő be (G4) — l. a `replay` TODO-ját; addig SZÁNDÉKOSAN nem validálunk (nem fake-elünk provider-error-t).
+ */
+export class DyNTS_AIMock_Service {
+
+  /** A fixture-tár, amiből a replay megy. */
+  private readonly store: DyNTS_AIMock_FixtureStore_Service;
+
+  /**
+   * A modell-registry a config-validaciohoz (FR-048 `settingsSchema`). Ures registry → NINCS
+   * config-validacio (permisszi­v), csak fixture-replay — igy a mock a schema kikerulese elott is hasznalhato.
+   */
+  private readonly modelRegistry: DyFM_AI_ModelInfo[];
+
+  /**
+   * @param store a beégetett fixture-ök tára.
+   * @param modelRegistry opcionális modell-registry (pl. `DyFM_OAI_Models`) a FR-048 config-validációhoz.
+   */
+  constructor(store: DyNTS_AIMock_FixtureStore_Service, modelRegistry?: DyFM_AI_ModelInfo[]) {
+    this.store = store;
+    this.modelRegistry = modelRegistry ?? [];
+  }
+
+  /**
+   * Chat/completion replay a beégetett fixture-ből.
+   * @param set - provider + model + opcionális config + prompt-input
+   */
+  async chatCompletion(set: DyNTS_AIMock_CallInput): Promise<unknown> {
+    return this.replay(this.toRequest(set, DyNTS_AIMock_Modality.text));
+  }
+
+  /**
+   * Embedding replay a beégetett fixture-ből.
+   * @param set - provider + model + opcionális config + szöveg(ek)-input
+   */
+  async embed(set: DyNTS_AIMock_CallInput): Promise<unknown> {
+    return this.replay(this.toRequest(set, DyNTS_AIMock_Modality.embedding));
+  }
+
+  /**
+   * Kép-generálás replay a beégetett fixture-ből.
+   * @param set - provider + model + opcionális config + kép-prompt-input
+   */
+  async generateImage(set: DyNTS_AIMock_CallInput): Promise<unknown> {
+    return this.replay(this.toRequest(set, DyNTS_AIMock_Modality.image));
+  }
+
+  /**
+   * Hang (transcription / TTS) replay a beégetett fixture-ből.
+   * @param set - provider + model + opcionális config + audio/szöveg-input
+   */
+  async generateAudio(set: DyNTS_AIMock_CallInput): Promise<unknown> {
+    return this.replay(this.toRequest(set, DyNTS_AIMock_Modality.audio));
+  }
+
+  /** A modalitás-metódus bemenetéből teljes `DyNTS_AIMock_Request`. */
+  private toRequest(set: DyNTS_AIMock_CallInput, modality: DyNTS_AIMock_Modality): DyNTS_AIMock_Request {
+    return {
+      provider: set.provider,
+      model: set.model,
+      modality: modality,
+      config: set.config,
+      input: set.input,
+    };
+  }
+
+  /** A közös replay/reject-mag. */
+  private replay(request: DyNTS_AIMock_Request): unknown {
+    // FR-048: a config-validáció a modell `settingsSchema.unsupported`-ja alapján — MÉG a fixture-lookup
+    // ELŐTT, ahogy a valódi providernél is a szerver utasítja el a rossz paramétert.
+    this.validateConfig(request);
+
+    const fixture: DyNTS_AIMock_Fixture | undefined = this.store.resolve(request);
+
+    if (!fixture) {
+      throw this.rejectOnUnknown(request);
+    }
+
+    if (fixture.error) {
+      throw this.toProviderFaithfulError(fixture.error);
+    }
+
+    return fixture.output;
+  }
+
+  /**
+   * FR-048 config-validáció — **delegál** a modul-szintű `DyNTS_AI_ModelConfig_Validator`-ra, hogy EGY
+   * validációs út legyen (SSoT): ugyanaz a kód dönt a production pre-validációnál és a mockban.
+   * Üres registry / schema-mentes modell → permisszív (nem találgatunk).
+   */
+  private validateConfig(request: DyNTS_AIMock_Request): void {
+    const error: DyFM_Error = DyNTS_AI_ModelConfig_Validator.validate({
+      provider: request.provider,
+      model: request.model,
+      config: request.config,
+      registry: this.modelRegistry,
+    });
+
+    if (error) {
+      throw error;
+    }
+  }
+
+  /** Egy `DyNTS_AIMock_Error` leíróból a dobandó `DyFM_Error`. */
+  private toProviderFaithfulError(error: DyNTS_AIMock_Error): DyFM_Error {
+    return new DyFM_Error({
+      message: `[ai-mock] provider-faithful error (HTTP ${error.httpStatus}): ${error.reason}`,
+      userMessage: 'AI request rejected (mock).',
+      errorCode: 'DyNTS-AIMOCK-PERR',
+      additionalContent: { providerErrorBody: error.providerErrorBody },
+    });
+  }
+
+  /** Strukturált „no-fixture" hiba (D3) — beszédes, a hiányzó kulccsal + az extend-recepttel (MP-6). */
+  private rejectOnUnknown(request: DyNTS_AIMock_Request): DyFM_Error {
+    const matchKey: string = DyNTS_AIMock_FixtureMatch_Util.buildMatchKey(request);
+
+    return new DyFM_Error({
+      message: `[ai-mock] no fixture for '${request.provider}:${request.model}' (${request.modality}). ` +
+        `Match-key: ${matchKey}. Beégetés: 'dc ai-mock-extend' (MP-6).`,
+      userMessage: 'No mock fixture is registered for this AI request.',
+      errorCode: 'DyNTS-AIMOCK-NOFIX',
+    });
+  }
+}

package/src/_modules/ai/_modules/ai-mock/index.ts

@@ -0,0 +1,44 @@
+//
+// ai-mock module (@futdevpro/nts-dynamo/ai/ai-mock)
+//
+// AI Mocking System — provider-faithful mock-service + fixture-store (Layer B) a valódi AI-hívások
+// kiváltására teszt/CI/lokál-fejlesztésben. A Layer A (per-model config-registry + validátor) a FR-048
+// (`DyFM_AI_ModelSettingsSchema` + reconciler) — az ai-mock azt FOGYASZTJA a provider-faithful
+// error-reprodukcióhoz. Terv: `documentations/plans/ai-mocking-system/HYPERPLAN.md`.
+//
+// SCAFFOLD (Cikl. 2, 2026-07-21): a modul-váz + a meglévő determinisztikus embedding-mock re-exportja.
+// A további szolgáltatások (fixture-store, mock-service, coverage) MP-3..MP-6 során kerülnek ide;
+// almappák (_collections/_enums/_models/_services) csak 3-5+ elemnél jönnek létre (FDP folder-rule).
+//
+
+// Layer B embedding-mag: a determinisztikus embedding-mock (BFR-AM-008) — MP-5 SP-5.1 során FIZIKAILAG
+// ide költözött (`_services/ai-embedding-mock.service.ts`). A régi `@futdevpro/nts-dynamo/ai` útvonal
+// backward-compat re-exportként tovább él, így a FAM-consumer nem törik.
+export * from './_services/ai-embedding-mock.service';
+
+// ENUMS
+export * from './_enums/aim-modality.enum';
+
+// MODELS / INTERFACES — fixture-shape (MP-3 SP-3.1)
+export * from './_models/interfaces/aim-request.interface';
+export * from './_models/interfaces/aim-error.interface';
+export * from './_models/interfaces/aim-fixture.interface';
+export * from './_models/interfaces/aim-call-input.interface';
+export * from './_models/interfaces/aim-service-collection.interface';
+
+// COLLECTIONS — input-match normalizáció (MP-3 SP-3.1).
+// A provider-faithful hiba-alak + a validate-mode a MODUL-SZINTŰ `ai/` alatt él (SSoT), mert production
+// pre-validációra is kell — nem az ai-mock-ból importálandó: `@futdevpro/nts-dynamo/ai`.
+export * from './_collections/aim-fixture-match.util';
+
+// DEFAULT-BUNDLE factory (MP-7 SP-7.1) — egy hívással álló mock-készlet.
+export * from './_collections/aim-default-collection.util';
+
+// FIXTURE-SERIALIZER (MP-3 SP-3.1) — determinisztikus, diff-barát konstans-fájl generálás.
+export * from './_collections/aim-fixture-serializer.util';
+
+// SERVICES — fixture-store (MP-3) + mock-service surface (MP-4 SP-4.1) + generáló harness (MP-3 SP-3.2).
+// A harness KÉT biztonsági zárral véd a véletlen pénzköltés ellen (spend-guard default OFF + D2 tier-cap).
+export * from './_services/aim-fixture-store.service';
+export * from './_services/aim-mock.service';
+export * from './_services/aim-fixture-harness.service';