@futdevpro/nts-dynamo 1.15.151 → 1.15.153

package/__documentations/2026-06-01-fr047-p2p3-function-calling.md

@@ -1,81 +1,81 @@
-# FR-047 P2+P3 — Function-calling agent-loop + OpenAI-wire translator (2026-06-01)
-
-**Commits**: `de6f79e` — v01.15.36 → v01.15.37 (agent-loop + OpenAI translator)
-            `514153f` — → v01.15.40 (critical reasoning-model fix; see below)
-**Parent**: `__agent/feature-requests/FR-047-phase-2-agent-loop-service-base.md` + `FR-047-phase-3-openai-fdpai-local.md`
-**Pattern**: `fdp-documentations/guidelines/development/ai-function-calling.md`
-**Depends on**: `@futdevpro/fsm-dynamo` ≥ 1.15.17 (tool vocabulary + registry; bumped to 1.15.18 here)
-
-## What
-
-Implements the provider-agnostic function-calling agent-loop in `DyNTS_AI_LLM_ServiceBase` and the
-first concrete provider translator in `DyNTS_OAI_LLM_ServiceBase`. After this, OpenAI tool calling
-works end-to-end through the strategic agnostic layer.
-
-## Why
-
-FR-047 P1 (fsm) shipped the vocabulary; the execution layer had the explicit TODO comment in
-`getMessageCreateInput` ("'llm-tool-use' categoria a tools bevezetésekor — jövőbeli FR"). This is that FR.
-The proven loop logic is ported from the legacy `FDPNTS_GPT_ControlService.getAnswerWithTools`.
-
-## Design
-
-### Agent-loop in `DyNTS_AI_LLM_ServiceBase` (written ONCE, concrete)
-- `requestWithTools({ conversation, tools, toolHandlers, settings?, issuer, maxIterations? })` — public entry.
-  Tools are a **request parameter** (not on settings). Resolves model → capability pre-check → `runToolLoop`.
-- `runToolLoop` — the loop: `callModelWithTools` → if `toolCalls`, push assistant-tool-call message,
-  run each handler (`runToolCall`), push `role:'tool'` result messages, repeat; exit on no-tool-call
-  final answer or `maxIterations` (default 8 → `DyFM_Error` `DyNTS-AILSB-TL0`).
-- `runToolCall` — **never throws**; missing/throwing handler → `ERROR …` string with `isError:true` (no `[object Object]`).
-- `assertToolsSupported(modelId)` — uses `DyFM_AI_ModelRegistry_Util.modelSupportsTools(getModelRegistry(), id)`;
-  rejects BEFORE any API call if unsupported (critical for Local).
-- `callModelWithTools` + `getModelRegistry` — **non-abstract safe defaults** (throw / `[]`); providers override.
-  Chosen over `abstract` so NO existing concrete subclass breaks (incremental rollout).
-
-### OpenAI translator in `DyNTS_OAI_LLM_ServiceBase`
-- `getModelRegistry()` → `DyFM_OAI_Models`.
-- `callModelWithTools` — builds the native request (system + `toOpenAIMessage`-mapped conversation incl.
-  tool-call/tool-result messages + `toOpenAITool`), calls the SDK, normalizes the response (`toolCalls`
-  from `message.tool_calls`, args JSON-parsed), emits `'llm-tool-use'` cost-event.
-- `toOpenAIMessage` — maps `role:'tool'` → `{role:'tool',tool_call_id,content}`, assistant-with-toolCalls →
-  `{role:'assistant',content|null,tool_calls:[…]}`.
-
-### Refinement vs the FR plan
-The registry lookup util takes the **registry array as a param** (`(models, id)`), not `(provider, id)` —
-so the fsm core never imports a provider submodule. The provider service supplies its own registry.
-
-## CRITICAL fix (`514153f`, v01.15.40) — found in code review
-
-The registry's tool-capable models (gpt-5.5, gpt-5.4-mini, o3-pro) are **reasoning models** that reject
-`temperature`/`top_p`/`frequency_penalty`/`presence_penalty` with HTTP 400. `callModelWithTools` sent them
-unconditionally (default temperature=0) → **every tool call 400'd on the flagship models**. Fix:
-- `isReasoningModel(modelId)` = `/^gpt-5/ || /^o[0-9]/`; reasoning → omit the 4 sampling params.
-- Omit `tools`/`tool_choice` when the tool array is empty (empty `[]` → 400).
-- Clear error when no model is configured.
-This is the local OpenAI-specific application of the FR-048 per-model-settings principle.
-See `[[reference_oai_reasoning_models_reject_sampling_params]]`.
-
-## Spec coverage
-
-`oai-llm.service-base.tools.spec.ts` (mocked OpenAI client, no network) — 6 specs:
-loop converges / never-throw on handler error / capability-reject for embedding model /
-reasoning omits sampling params / non-reasoning sends them / empty-tools omitted.
-`npx jasmine`: **1256/0** (146 pending pre-existing).
-
-## What's NOT in this commit
-
-- Anthropic / Google / FdpAI / Local LLM bases + translators (FR-047 P4/P5).
-- The NON-tool path (`getMessageCreateInput`/`resolveMessage`) still forwards sampling params → reasoning
-  completions would 400 (pre-existing; FR-048 / separate fix).
-- Adventor migration (FR-047 P6).
-- FR-048 general per-model settings reconciler.
-
-## Consumer pattern
-
-See `fdp-documentations/guidelines/development/ai-function-calling.md` ("How to USE it").
-
-## Cross-references
-
-- `fdp-documentations/guidelines/development/ai-function-calling.md` (pattern + provider-translator how-to)
-- `NPM-packages/dynamo-fsm/__documentations/2026-06-01-fr047-p1-function-calling-vocabulary.md` (vocabulary)
-- legacy `NPM-packages/fdp-templates-nts/src/_modules/gpt/_services/gpt-handler.control-service.ts` (logic source)
+# FR-047 P2+P3 — Function-calling agent-loop + OpenAI-wire translator (2026-06-01)
+
+**Commits**: `de6f79e` — v01.15.36 → v01.15.37 (agent-loop + OpenAI translator)
+            `514153f` — → v01.15.40 (critical reasoning-model fix; see below)
+**Parent**: `__agent/feature-requests/FR-047-phase-2-agent-loop-service-base.md` + `FR-047-phase-3-openai-fdpai-local.md`
+**Pattern**: `fdp-documentations/guidelines/development/ai-function-calling.md`
+**Depends on**: `@futdevpro/fsm-dynamo` ≥ 1.15.17 (tool vocabulary + registry; bumped to 1.15.18 here)
+
+## What
+
+Implements the provider-agnostic function-calling agent-loop in `DyNTS_AI_LLM_ServiceBase` and the
+first concrete provider translator in `DyNTS_OAI_LLM_ServiceBase`. After this, OpenAI tool calling
+works end-to-end through the strategic agnostic layer.
+
+## Why
+
+FR-047 P1 (fsm) shipped the vocabulary; the execution layer had the explicit TODO comment in
+`getMessageCreateInput` ("'llm-tool-use' categoria a tools bevezetésekor — jövőbeli FR"). This is that FR.
+The proven loop logic is ported from the legacy `FDPNTS_GPT_ControlService.getAnswerWithTools`.
+
+## Design
+
+### Agent-loop in `DyNTS_AI_LLM_ServiceBase` (written ONCE, concrete)
+- `requestWithTools({ conversation, tools, toolHandlers, settings?, issuer, maxIterations? })` — public entry.
+  Tools are a **request parameter** (not on settings). Resolves model → capability pre-check → `runToolLoop`.
+- `runToolLoop` — the loop: `callModelWithTools` → if `toolCalls`, push assistant-tool-call message,
+  run each handler (`runToolCall`), push `role:'tool'` result messages, repeat; exit on no-tool-call
+  final answer or `maxIterations` (default 8 → `DyFM_Error` `DyNTS-AILSB-TL0`).
+- `runToolCall` — **never throws**; missing/throwing handler → `ERROR …` string with `isError:true` (no `[object Object]`).
+- `assertToolsSupported(modelId)` — uses `DyFM_AI_ModelRegistry_Util.modelSupportsTools(getModelRegistry(), id)`;
+  rejects BEFORE any API call if unsupported (critical for Local).
+- `callModelWithTools` + `getModelRegistry` — **non-abstract safe defaults** (throw / `[]`); providers override.
+  Chosen over `abstract` so NO existing concrete subclass breaks (incremental rollout).
+
+### OpenAI translator in `DyNTS_OAI_LLM_ServiceBase`
+- `getModelRegistry()` → `DyFM_OAI_Models`.
+- `callModelWithTools` — builds the native request (system + `toOpenAIMessage`-mapped conversation incl.
+  tool-call/tool-result messages + `toOpenAITool`), calls the SDK, normalizes the response (`toolCalls`
+  from `message.tool_calls`, args JSON-parsed), emits `'llm-tool-use'` cost-event.
+- `toOpenAIMessage` — maps `role:'tool'` → `{role:'tool',tool_call_id,content}`, assistant-with-toolCalls →
+  `{role:'assistant',content|null,tool_calls:[…]}`.
+
+### Refinement vs the FR plan
+The registry lookup util takes the **registry array as a param** (`(models, id)`), not `(provider, id)` —
+so the fsm core never imports a provider submodule. The provider service supplies its own registry.
+
+## CRITICAL fix (`514153f`, v01.15.40) — found in code review
+
+The registry's tool-capable models (gpt-5.5, gpt-5.4-mini, o3-pro) are **reasoning models** that reject
+`temperature`/`top_p`/`frequency_penalty`/`presence_penalty` with HTTP 400. `callModelWithTools` sent them
+unconditionally (default temperature=0) → **every tool call 400'd on the flagship models**. Fix:
+- `isReasoningModel(modelId)` = `/^gpt-5/ || /^o[0-9]/`; reasoning → omit the 4 sampling params.
+- Omit `tools`/`tool_choice` when the tool array is empty (empty `[]` → 400).
+- Clear error when no model is configured.
+This is the local OpenAI-specific application of the FR-048 per-model-settings principle.
+See `[[reference_oai_reasoning_models_reject_sampling_params]]`.
+
+## Spec coverage
+
+`oai-llm.service-base.tools.spec.ts` (mocked OpenAI client, no network) — 6 specs:
+loop converges / never-throw on handler error / capability-reject for embedding model /
+reasoning omits sampling params / non-reasoning sends them / empty-tools omitted.
+`npx jasmine`: **1256/0** (146 pending pre-existing).
+
+## What's NOT in this commit
+
+- Anthropic / Google / FdpAI / Local LLM bases + translators (FR-047 P4/P5).
+- The NON-tool path (`getMessageCreateInput`/`resolveMessage`) still forwards sampling params → reasoning
+  completions would 400 (pre-existing; FR-048 / separate fix).
+- Adventor migration (FR-047 P6).
+- FR-048 general per-model settings reconciler.
+
+## Consumer pattern
+
+See `fdp-documentations/guidelines/development/ai-function-calling.md` ("How to USE it").
+
+## Cross-references
+
+- `fdp-documentations/guidelines/development/ai-function-calling.md` (pattern + provider-translator how-to)
+- `NPM-packages/dynamo-fsm/__documentations/2026-06-01-fr047-p1-function-calling-vocabulary.md` (vocabulary)
+- legacy `NPM-packages/fdp-templates-nts/src/_modules/gpt/_services/gpt-handler.control-service.ts` (logic source)

package/__documentations/2026-06-15-fr193-memory-guard.md

@@ -1,73 +1,73 @@
-# FR-193 — `DyNTS_MemoryGuard` (bedrock OOM korai-figyelmeztetés)
-
-**Csomag:** `@futdevpro/nts-dynamo` · **Dátum:** 2026-06-15
-
-## Probléma
-
-A Node heap-OOM (`--max-old-space-size` túllépés — pl. egy óriási `JSON.parse`, mint az
-Overseernél a CCAP több-tíz-MB-os `cdpReport`-ja) a process-t **azonnal megöli**. A
-`process.on('uncaughtException')` NEM kapja el — a crash pillanatában már **nincs mód a
-hibát rögzíteni**. Eredmény: a szerver „csak eltűnik", nyom nélkül, és a kézi diagnózis
-nehéz. Az EGYETLEN megbízható idő a rögzítésre a crash **ELŐTT** van.
-
-## Megoldás — `DyNTS_MemoryGuard`
-
-Bedrock, self-installing heap-watchdog **minden nts-szerverhez**. Periodikusan figyeli a
-heap-kihasználtságot, és a `--max-old-space-size` plafonhoz közeledve **tartós rekordot**
-hagy — mielőtt a fatal OOM bekövetkezne.
-
-- **Megfigyel:** `v8.getHeapStatistics().heap_size_limit` (a valódi plafon) vs
-  `process.memoryUsage().heapUsed`, default 10s-enként.
-- **Rögzít:** küszöb-átlépéskor `DyFM_Log` + `DyNTS_GlobalService.globalErrorHandler`
-  (az Errors-rendszer + Discord, ha bekötve). `warning` → `DyFM_ErrorLevel.warning`,
-  `critical` → `.critical`. Plusz egy in-memory ring-buffer (`getHistory()`) +
-  `getStatus()` (állapot + csúcsok) egy esetleges status-endpointhoz.
-- **Hiszterézis:** eseményt CSAK állapot-váltáskor jelez (normal→warning→critical), és a
-  `recoveryMargin`-nyit a warning alá esve jelez `recovered`-et → nincs küszöb-körüli spam.
-- **NEM csinál:** nem állítja le/újraindítja a process-t (az a konténer `restart:` policy
-  dolga), és nem próbálja elkapni a fatal OOM-ot (nem lehet). Tisztán megfigyelés +
-  rögzítés + opcionális `onCritical` hook (amivel a fogyasztó terhet dobhat).
-- **Biztonság:** minden út `try/catch`-elt — egy figyelő-réteg SOHA nem dönthet be egy
-  szervert. A timer `unref()`-elt (nem tartja életben a process-t).
-
-## Használat
-
-**Automatikus (default-on):** a base `App` startup feltelepíti, ha
-`DyNTS_global_settings.memoryGuard.enabled === true` (alapértelmezés szerint igen). Tehát
-**minden nts-szerver megkapja** az nts-dynamo bump után — kód nélkül.
-
-**Explicit / testreszabott:**
-```ts
-import { DyNTS_MemoryGuard } from '@futdevpro/nts-dynamo';
-
-DyNTS_MemoryGuard.getInstance().install({
-  heapWarningThreshold: 80,
-  heapCriticalThreshold: 92,
-  onCritical: (e) => { /* pl. terhelés-dobás / külső riasztás */ },
-});
-```
-
-**Konfiguráció** (`DyNTS_global_settings.memoryGuard`, defaultok):
-| mező | default | jelentés |
-|------|---------|----------|
-| `enabled` | `true` | a base App feltelepíti |
-| `pollIntervalMs` | `10000` | poll-gyakoriság |
-| `heapWarningThreshold` | `85` | warning a heap-plafon %-ában |
-| `heapCriticalThreshold` | `95` | critical % |
-| `recoveryMargin` | `10` | a warning alatti margó a `recovered`-hez |
-| `maxHistoryCount` | `100` | megőrzött események |
-
-## Az OOM-self-healing nagyobb képe
-
-Ez a **„rögzítés" rétege** (record). A **„restart" rétege** a konténer-szintű
-`restart: on-failure:N` + `mem_limit` (compose, fdp-devops) — együtt adják a teljes
-self-healinget: a guard nyomot hagy a near-OOM-ról, a restart-policy auto-helyreállít a
-crash után. A **forrás-prevenció** (a túl nagy payload parse-olásának elkerülése) külön
-réteg (runner-oldali report-cap / body-limit).
-
-## Fájlok
-- `src/_services/core/memory-guard.service.ts` + `.spec.ts` (11 spec)
-- `src/_models/interfaces/global-settings.interface.ts` (`memoryGuard` mező)
-- `src/_collections/global-settings.const.ts` (defaultok, enabled:true)
-- `src/_services/server/app.server.ts` (guarded auto-install a startup-ban)
-- `src/index.ts` (fő-export)
+# FR-193 — `DyNTS_MemoryGuard` (bedrock OOM korai-figyelmeztetés)
+
+**Csomag:** `@futdevpro/nts-dynamo` · **Dátum:** 2026-06-15
+
+## Probléma
+
+A Node heap-OOM (`--max-old-space-size` túllépés — pl. egy óriási `JSON.parse`, mint az
+Overseernél a CCAP több-tíz-MB-os `cdpReport`-ja) a process-t **azonnal megöli**. A
+`process.on('uncaughtException')` NEM kapja el — a crash pillanatában már **nincs mód a
+hibát rögzíteni**. Eredmény: a szerver „csak eltűnik", nyom nélkül, és a kézi diagnózis
+nehéz. Az EGYETLEN megbízható idő a rögzítésre a crash **ELŐTT** van.
+
+## Megoldás — `DyNTS_MemoryGuard`
+
+Bedrock, self-installing heap-watchdog **minden nts-szerverhez**. Periodikusan figyeli a
+heap-kihasználtságot, és a `--max-old-space-size` plafonhoz közeledve **tartós rekordot**
+hagy — mielőtt a fatal OOM bekövetkezne.
+
+- **Megfigyel:** `v8.getHeapStatistics().heap_size_limit` (a valódi plafon) vs
+  `process.memoryUsage().heapUsed`, default 10s-enként.
+- **Rögzít:** küszöb-átlépéskor `DyFM_Log` + `DyNTS_GlobalService.globalErrorHandler`
+  (az Errors-rendszer + Discord, ha bekötve). `warning` → `DyFM_ErrorLevel.warning`,
+  `critical` → `.critical`. Plusz egy in-memory ring-buffer (`getHistory()`) +
+  `getStatus()` (állapot + csúcsok) egy esetleges status-endpointhoz.
+- **Hiszterézis:** eseményt CSAK állapot-váltáskor jelez (normal→warning→critical), és a
+  `recoveryMargin`-nyit a warning alá esve jelez `recovered`-et → nincs küszöb-körüli spam.
+- **NEM csinál:** nem állítja le/újraindítja a process-t (az a konténer `restart:` policy
+  dolga), és nem próbálja elkapni a fatal OOM-ot (nem lehet). Tisztán megfigyelés +
+  rögzítés + opcionális `onCritical` hook (amivel a fogyasztó terhet dobhat).
+- **Biztonság:** minden út `try/catch`-elt — egy figyelő-réteg SOHA nem dönthet be egy
+  szervert. A timer `unref()`-elt (nem tartja életben a process-t).
+
+## Használat
+
+**Automatikus (default-on):** a base `App` startup feltelepíti, ha
+`DyNTS_global_settings.memoryGuard.enabled === true` (alapértelmezés szerint igen). Tehát
+**minden nts-szerver megkapja** az nts-dynamo bump után — kód nélkül.
+
+**Explicit / testreszabott:**
+```ts
+import { DyNTS_MemoryGuard } from '@futdevpro/nts-dynamo';
+
+DyNTS_MemoryGuard.getInstance().install({
+  heapWarningThreshold: 80,
+  heapCriticalThreshold: 92,
+  onCritical: (e) => { /* pl. terhelés-dobás / külső riasztás */ },
+});
+```
+
+**Konfiguráció** (`DyNTS_global_settings.memoryGuard`, defaultok):
+| mező | default | jelentés |
+|------|---------|----------|
+| `enabled` | `true` | a base App feltelepíti |
+| `pollIntervalMs` | `10000` | poll-gyakoriság |
+| `heapWarningThreshold` | `85` | warning a heap-plafon %-ában |
+| `heapCriticalThreshold` | `95` | critical % |
+| `recoveryMargin` | `10` | a warning alatti margó a `recovered`-hez |
+| `maxHistoryCount` | `100` | megőrzött események |
+
+## Az OOM-self-healing nagyobb képe
+
+Ez a **„rögzítés" rétege** (record). A **„restart" rétege** a konténer-szintű
+`restart: on-failure:N` + `mem_limit` (compose, fdp-devops) — együtt adják a teljes
+self-healinget: a guard nyomot hagy a near-OOM-ról, a restart-policy auto-helyreállít a
+crash után. A **forrás-prevenció** (a túl nagy payload parse-olásának elkerülése) külön
+réteg (runner-oldali report-cap / body-limit).
+
+## Fájlok
+- `src/_services/core/memory-guard.service.ts` + `.spec.ts` (11 spec)
+- `src/_models/interfaces/global-settings.interface.ts` (`memoryGuard` mező)
+- `src/_collections/global-settings.const.ts` (defaultok, enabled:true)
+- `src/_services/server/app.server.ts` (guarded auto-install a startup-ban)
+- `src/index.ts` (fő-export)

package/__documentations/2026-08-08-fr292-app-version-header.md

@@ -1,38 +1,38 @@
-# FR-292 (szerver-fél) — a deployolt app-verzió minden válasz headerében
-
-**Dátum:** 2026-08-08 · **Csomag:** `@futdevpro/nts-dynamo`
-
-> A teljes (kliens+szerver) leírás a kliens-oldalon:
-> `NPM-packages/dynamo-ngx/__documentations/2026-08-08-fr292-app-update-watch.md`.
-> Ez a lap csak a szerver-fél szerződését rögzíti.
-
-## Mit csinál
-
-Minden HTTP-válaszra rákerül a deployolt **app-verzió**:
-
-```
-X-App-Version: 01.15.460
-Access-Control-Expose-Headers: Content-Length, Content-Type, X-App-Version
-```
-
-A kliens (ngx-dynamo `DyNX_AppVersion_Interceptor`) ebből veszi észre, hogy a böngészőben
-**betöltött bundle elavult** — anélkül, hogy bárki pollingolna: a jelzés a már menő
-API-forgalmon utazik.
-
-## Szerződés / döntések
-
-- **Default: BEKAPCSOLVA.** Informatív header, se PII, se belső részlet. Kikapcsolás:
-  `DyNTS_global_settings.appVersionHeader = { enabled: false }`.
-- **A verzió hívásonként olvasódik** (getter, nem befagyasztott érték): a `systemVersion` az
-  app-params betöltésekor áll be, ami a middleware felszerelése UTÁN történik. Befagyasztva
-  örökre `unknown-version` maradna — pont a friss deployon hiányozna a jelzés.
-- **`unknown-version` esetén NINCS header.** Egy bizonytalan jelzés hamis „új verzió elérhető"
-  riasztást szülne a kliensen; inkább hallgatunk.
-- **A CORS expose-listához hozzáfűz, nem felülír** (idempotensen). Enélkül a cross-origin
-  kliens JS-e nem olvashatná ki a headert. Ezért a middleware a **CORS-mount UTÁN** települ
-  — `initOpenExpress` és `initSecureExpress` egyaránt.
-
-## Verifikáció
-
-`tsc` ✅ 0 hiba · unit ✅ **1634 spec, 0 failure** (ebből 8 új: expose-lista bővítés/idempotencia,
-ismeretlen verzió → nincs header de a lánc továbbmegy, hívásonkénti verzió-olvasás, egyedi header-név).
+# FR-292 (szerver-fél) — a deployolt app-verzió minden válasz headerében
+
+**Dátum:** 2026-08-08 · **Csomag:** `@futdevpro/nts-dynamo`
+
+> A teljes (kliens+szerver) leírás a kliens-oldalon:
+> `NPM-packages/dynamo-ngx/__documentations/2026-08-08-fr292-app-update-watch.md`.
+> Ez a lap csak a szerver-fél szerződését rögzíti.
+
+## Mit csinál
+
+Minden HTTP-válaszra rákerül a deployolt **app-verzió**:
+
+```
+X-App-Version: 01.15.460
+Access-Control-Expose-Headers: Content-Length, Content-Type, X-App-Version
+```
+
+A kliens (ngx-dynamo `DyNX_AppVersion_Interceptor`) ebből veszi észre, hogy a böngészőben
+**betöltött bundle elavult** — anélkül, hogy bárki pollingolna: a jelzés a már menő
+API-forgalmon utazik.
+
+## Szerződés / döntések
+
+- **Default: BEKAPCSOLVA.** Informatív header, se PII, se belső részlet. Kikapcsolás:
+  `DyNTS_global_settings.appVersionHeader = { enabled: false }`.
+- **A verzió hívásonként olvasódik** (getter, nem befagyasztott érték): a `systemVersion` az
+  app-params betöltésekor áll be, ami a middleware felszerelése UTÁN történik. Befagyasztva
+  örökre `unknown-version` maradna — pont a friss deployon hiányozna a jelzés.
+- **`unknown-version` esetén NINCS header.** Egy bizonytalan jelzés hamis „új verzió elérhető"
+  riasztást szülne a kliensen; inkább hallgatunk.
+- **A CORS expose-listához hozzáfűz, nem felülír** (idempotensen). Enélkül a cross-origin
+  kliens JS-e nem olvashatná ki a headert. Ezért a middleware a **CORS-mount UTÁN** települ
+  — `initOpenExpress` és `initSecureExpress` egyaránt.
+
+## Verifikáció
+
+`tsc` ✅ 0 hiba · unit ✅ **1634 spec, 0 failure** (ebből 8 új: expose-lista bővítés/idempotencia,
+ismeretlen verzió → nincs header de a lánc továbbmegy, hívásonkénti verzió-olvasás, egyedi header-név).

package/__documentations/2026-08-14-field-encryption-mongoose-document-spread.md

@@ -1,124 +1,124 @@
-# 🔴 `DyNTS_FieldEncryption_Util._transform` spread-elte a Mongoose-Documentet — a lista-endpointok burkot adtak vissza
-
-**Dátum:** 2026-08-14 · **Kérő:** `BFR-MASTERPROMPTER-027` · **Súlyosság:** high (funkcionálisan törött lista-UI)
-
----
-
-## 1. A hiba
-
-```ts
-// field-encryption.util.ts — ELŐTTE
-const result: any = Array.isArray(value) ? [ ...(value as any[]) ] : { ...(value as any) };
-```
-
-Egy mongoose-**Document** adatai **nem saját mezők** — a belső `_doc`-ban ülnek. Ezért a `{ ...doc }`
-a **belső burkot** másolja (`$__`, `$isNew`, `_doc`), és az eredmény **már nem Document**, tehát a
-`JSON.stringify` sem hívja a `toJSON()`-ját. A kliens így ezt kapja:
-
-```json
-[{ "$__": {...}, "$isNew": false, "_doc": { "_id": "…", "name": "…" } }]
-```
-
-`_id` a legfelső szinten **nincs** → a fogyasztó minden id-alapú művelete elhasal.
-
-### Élesben mért bizonyíték (`test.master-prompter.hu`, 2026-08-14)
-
-| endpoint | státusz | első elem KULCSAI | `_id` |
-|---|---|---|---|
-| `GET /api/flow/flow/get/:userId/:flowId` (egyedi) | 200 | `_id`, `userId`, `ownerId`, `name`, … | ✅ |
-| `GET /api/flow/flow/get-all-my/:userId` (**lista**) | 200 | **`$__`, `$isNew`, `_doc`** | ❌ **undefined** |
-
-Kliens-oldali tünet: a lista-kártyák linkje `/editor/undefined`, a törlés
-`DyNX_ApiService call "deleteFlow" ERROR: missing pathParam: "flowId"` dialógussal állt meg.
-
----
-
-## 2. Miért CSAK a lista tört el — a mért aszimmetria
-
-A `DyNTS_DBService` **egyedi** olvasásai már ma is `toObject()`-tel adnak vissza sima objektumot
-(`getDataById`, `getDataByDependencyId`, `findByIdAndUpdate`, `findOneAndUpdate`, `createData`).
-A **lista/find metódusok NYERS Documentet** adnak tovább — kimérve **11 db**:
-
-`getDataListByIds` · `getDataListByDependencyId` · `getDataListByDependencyIds` · `getAll` ·
-`getDeletedDataList` · `trueDeleteAllData` · `searchData` · `findOne` · `find` · `findWithPaging` ·
-(`findLeanBatched` — ez `.lean()`-nel már sima objektumot ad)
-
-Titkosítás **nélkül** ez ártalmatlan: a nyers Document a `res.send`-en át a `toJSON()`-nal helyesen
-szerializálódik. `encrypt: true` mező esetén viszont a read-post-processor (`stringifyDataId` →
-`decryptDoc` → `_transform`) **spread-eli** a Documentet, és ezzel elrontja.
-
----
-
-## 3. A javítás
-
-```ts
-// UTÁNA
-const plain: any = this._toPlainIfDocument(value);
-const result: any = Array.isArray(plain) ? [ ...(plain as any[]) ] : { ...(plain as any) };
-```
-
-`_toPlainIfDocument` a `$__` **saját mező** + `toJSON` függvény kettősével azonosít egy Documentet
-(pontosan az, ami a hibás payloadba kiszivárgott — mongoose-import nélküli, pontos diszkriminátor),
-és `toJSON()`-t hív rá.
-
-**Miért itt, és nem a 11 DB-metódusban:**
-1. Ez az **egy pont** mind a 11 utat rendezi.
-2. A 11 metódus visszatérési **típusát** megváltoztatni (Document → sima objektum) **minden modell
-   minden fogyasztóját** érintené. Az itteni javítás viszont **csak az `encrypt: true` modelleket**
-   érinti — ahol a `_transform` amúgy is **már ma is** sima (csak **rossz**) objektumot ad vissza.
-   ⇒ **a változás nem tud elrontani olyat, ami ma működik.**
-3. `toJSON()` (nem `toObject()`): a titkosítás bevezetése ELŐTT a nyers Document a `res.send`-en át a
-   `JSON.stringify` → `toJSON()` úton szerializálódott — ez adja vissza **ugyanazt a kimeneti alakot**
-   (schema-transzformok, virtuals, `__v` együtt).
-
----
-
-## 4. 🔴 BLAST-RADIUS — a flotta érintettsége
-
-A defekt akkor él, ha **mind a három** teljesül: (a) a modellnek van `encrypt: true` mezője ·
-(b) a `FDP_CORE_DBCONTENT_CRYPT_KEY` be van állítva (kulcs nélkül a `decryptDoc` korán visszatér) ·
-(c) az olvasás **lista-metóduson** megy.
-
-| Projekt | Modell | Titkosított mezők | Állapot |
-|---|---|---|---|
-| **master-prompter** | `flow` | `flowSteps.prompt` | 🔴 **élesben igazoltan törött** |
-| **master-prompter** | `flow-run` | `results`, `sourceFlow`, `flowRunValues.value` | 🔴 ugyanaz az osztály |
-| **adventor** | `campaign` | `storyState`, `memory`, `epilogue` | ⚠️ ugyanaz az osztály — élesben nem mérve |
-| **adventor** | `generation` | `content`, `prompt` | ⚠️ ugyanaz az osztály — élesben nem mérve |
-| **fdp-token-service** | `token-purchase` | `requestIp`, `euVatNumber` (PII) | ⚠️ ugyanaz az osztály — élesben nem mérve |
-| **fdp-token-service** | `manual-invoice` | `realID`, `title`, `fullName`, `companyName`, … | ⚠️ ugyanaz az osztály — élesben nem mérve |
-
-⇒ **6 modell, 3 projekt.** A master-prompteren kívül egyik sincs élesben visszamérve — ezeket a
-projektek `nts-dynamo`-bumpja után kell ellenőrizni (a lista-endpointjaik `_id`-t adnak-e).
-A `manual-invoice` és a `token-purchase` külön figyelmet érdemel: számlázási/PII adat.
-
-> **Miért nem tűnt fel eddig:** a szerver **200**-at ad, a válasz JSON-ként **érvényes** — csak épp a
-> burkot tartalmazza. A UI „üresnek"/működésképtelennek látszik, de sehol nincs hibajelzés.
-> Az MP-ben azért derült ki, mert az `e2e-feature` step (a 30m→60m timeout-emelés után) **most futott
-> le először végig**.
-
----
-
-## 5. Kontroll-mérés — VALÓDI mongoose-Documenttel
-
-A regresszió-őr **szándékosan nem mockkal** dolgozik: a hiba pont abból eredt, hogy a Document adatai
-nem saját mezők — egy kézzel gyártott mock ezt a jellemzőt nem hordozza, tehát a mock-alapú teszt
-**akkor is zöld maradna**, ha a hiba visszakerülne. DB-kapcsolat nem kell: a `new Model({...})`
-offline is valódi Documentet ad.
-
-| Eset | A fix nélkül |
-|---|---|
-| a visszafejtett eredmény sima objektum (nincs `$__`/`$isNew`/`_doc`) | ❌ `Expected [ '$__', '_doc' ] not to contain '$__'` |
-| az `_id` megmarad | ❌ `az _id elveszett a transzform során: Expected undefined to be defined` |
-| a JSON-szerializált alak a valódi adatot adja | ❌ `… not to contain '_doc'` |
-| Document-**tömb** (lista-alak) minden eleme sima objektum, `_id`-vel | ❌ `… not to contain '_doc'` |
-| **összesen** | ❌ **4 FAILED** → javítva: ✅ **1644 specs, 0 failures** |
-
-A mezők helyes visszafejtését is asszertáljuk Documenten (top-level + beágyazott tömb-elem).
-
----
-
-## 6. Adopció
-
-`@futdevpro/nts-dynamo` bump minden érintett szerver-projektben (master-prompter, adventor,
-fdp-token-service), majd a lista-endpointok visszamérése (`_id` jelen van-e a válaszban).
+# 🔴 `DyNTS_FieldEncryption_Util._transform` spread-elte a Mongoose-Documentet — a lista-endpointok burkot adtak vissza
+
+**Dátum:** 2026-08-14 · **Kérő:** `BFR-MASTERPROMPTER-027` · **Súlyosság:** high (funkcionálisan törött lista-UI)
+
+---
+
+## 1. A hiba
+
+```ts
+// field-encryption.util.ts — ELŐTTE
+const result: any = Array.isArray(value) ? [ ...(value as any[]) ] : { ...(value as any) };
+```
+
+Egy mongoose-**Document** adatai **nem saját mezők** — a belső `_doc`-ban ülnek. Ezért a `{ ...doc }`
+a **belső burkot** másolja (`$__`, `$isNew`, `_doc`), és az eredmény **már nem Document**, tehát a
+`JSON.stringify` sem hívja a `toJSON()`-ját. A kliens így ezt kapja:
+
+```json
+[{ "$__": {...}, "$isNew": false, "_doc": { "_id": "…", "name": "…" } }]
+```
+
+`_id` a legfelső szinten **nincs** → a fogyasztó minden id-alapú művelete elhasal.
+
+### Élesben mért bizonyíték (`test.master-prompter.hu`, 2026-08-14)
+
+| endpoint | státusz | első elem KULCSAI | `_id` |
+|---|---|---|---|
+| `GET /api/flow/flow/get/:userId/:flowId` (egyedi) | 200 | `_id`, `userId`, `ownerId`, `name`, … | ✅ |
+| `GET /api/flow/flow/get-all-my/:userId` (**lista**) | 200 | **`$__`, `$isNew`, `_doc`** | ❌ **undefined** |
+
+Kliens-oldali tünet: a lista-kártyák linkje `/editor/undefined`, a törlés
+`DyNX_ApiService call "deleteFlow" ERROR: missing pathParam: "flowId"` dialógussal állt meg.
+
+---
+
+## 2. Miért CSAK a lista tört el — a mért aszimmetria
+
+A `DyNTS_DBService` **egyedi** olvasásai már ma is `toObject()`-tel adnak vissza sima objektumot
+(`getDataById`, `getDataByDependencyId`, `findByIdAndUpdate`, `findOneAndUpdate`, `createData`).
+A **lista/find metódusok NYERS Documentet** adnak tovább — kimérve **11 db**:
+
+`getDataListByIds` · `getDataListByDependencyId` · `getDataListByDependencyIds` · `getAll` ·
+`getDeletedDataList` · `trueDeleteAllData` · `searchData` · `findOne` · `find` · `findWithPaging` ·
+(`findLeanBatched` — ez `.lean()`-nel már sima objektumot ad)
+
+Titkosítás **nélkül** ez ártalmatlan: a nyers Document a `res.send`-en át a `toJSON()`-nal helyesen
+szerializálódik. `encrypt: true` mező esetén viszont a read-post-processor (`stringifyDataId` →
+`decryptDoc` → `_transform`) **spread-eli** a Documentet, és ezzel elrontja.
+
+---
+
+## 3. A javítás
+
+```ts
+// UTÁNA
+const plain: any = this._toPlainIfDocument(value);
+const result: any = Array.isArray(plain) ? [ ...(plain as any[]) ] : { ...(plain as any) };
+```
+
+`_toPlainIfDocument` a `$__` **saját mező** + `toJSON` függvény kettősével azonosít egy Documentet
+(pontosan az, ami a hibás payloadba kiszivárgott — mongoose-import nélküli, pontos diszkriminátor),
+és `toJSON()`-t hív rá.
+
+**Miért itt, és nem a 11 DB-metódusban:**
+1. Ez az **egy pont** mind a 11 utat rendezi.
+2. A 11 metódus visszatérési **típusát** megváltoztatni (Document → sima objektum) **minden modell
+   minden fogyasztóját** érintené. Az itteni javítás viszont **csak az `encrypt: true` modelleket**
+   érinti — ahol a `_transform` amúgy is **már ma is** sima (csak **rossz**) objektumot ad vissza.
+   ⇒ **a változás nem tud elrontani olyat, ami ma működik.**
+3. `toJSON()` (nem `toObject()`): a titkosítás bevezetése ELŐTT a nyers Document a `res.send`-en át a
+   `JSON.stringify` → `toJSON()` úton szerializálódott — ez adja vissza **ugyanazt a kimeneti alakot**
+   (schema-transzformok, virtuals, `__v` együtt).
+
+---
+
+## 4. 🔴 BLAST-RADIUS — a flotta érintettsége
+
+A defekt akkor él, ha **mind a három** teljesül: (a) a modellnek van `encrypt: true` mezője ·
+(b) a `FDP_CORE_DBCONTENT_CRYPT_KEY` be van állítva (kulcs nélkül a `decryptDoc` korán visszatér) ·
+(c) az olvasás **lista-metóduson** megy.
+
+| Projekt | Modell | Titkosított mezők | Állapot |
+|---|---|---|---|
+| **master-prompter** | `flow` | `flowSteps.prompt` | 🔴 **élesben igazoltan törött** |
+| **master-prompter** | `flow-run` | `results`, `sourceFlow`, `flowRunValues.value` | 🔴 ugyanaz az osztály |
+| **adventor** | `campaign` | `storyState`, `memory`, `epilogue` | ⚠️ ugyanaz az osztály — élesben nem mérve |
+| **adventor** | `generation` | `content`, `prompt` | ⚠️ ugyanaz az osztály — élesben nem mérve |
+| **fdp-token-service** | `token-purchase` | `requestIp`, `euVatNumber` (PII) | ⚠️ ugyanaz az osztály — élesben nem mérve |
+| **fdp-token-service** | `manual-invoice` | `realID`, `title`, `fullName`, `companyName`, … | ⚠️ ugyanaz az osztály — élesben nem mérve |
+
+⇒ **6 modell, 3 projekt.** A master-prompteren kívül egyik sincs élesben visszamérve — ezeket a
+projektek `nts-dynamo`-bumpja után kell ellenőrizni (a lista-endpointjaik `_id`-t adnak-e).
+A `manual-invoice` és a `token-purchase` külön figyelmet érdemel: számlázási/PII adat.
+
+> **Miért nem tűnt fel eddig:** a szerver **200**-at ad, a válasz JSON-ként **érvényes** — csak épp a
+> burkot tartalmazza. A UI „üresnek"/működésképtelennek látszik, de sehol nincs hibajelzés.
+> Az MP-ben azért derült ki, mert az `e2e-feature` step (a 30m→60m timeout-emelés után) **most futott
+> le először végig**.
+
+---
+
+## 5. Kontroll-mérés — VALÓDI mongoose-Documenttel
+
+A regresszió-őr **szándékosan nem mockkal** dolgozik: a hiba pont abból eredt, hogy a Document adatai
+nem saját mezők — egy kézzel gyártott mock ezt a jellemzőt nem hordozza, tehát a mock-alapú teszt
+**akkor is zöld maradna**, ha a hiba visszakerülne. DB-kapcsolat nem kell: a `new Model({...})`
+offline is valódi Documentet ad.
+
+| Eset | A fix nélkül |
+|---|---|
+| a visszafejtett eredmény sima objektum (nincs `$__`/`$isNew`/`_doc`) | ❌ `Expected [ '$__', '_doc' ] not to contain '$__'` |
+| az `_id` megmarad | ❌ `az _id elveszett a transzform során: Expected undefined to be defined` |
+| a JSON-szerializált alak a valódi adatot adja | ❌ `… not to contain '_doc'` |
+| Document-**tömb** (lista-alak) minden eleme sima objektum, `_id`-vel | ❌ `… not to contain '_doc'` |
+| **összesen** | ❌ **4 FAILED** → javítva: ✅ **1644 specs, 0 failures** |
+
+A mezők helyes visszafejtését is asszertáljuk Documenten (top-level + beágyazott tömb-elem).
+
+---
+
+## 6. Adopció
+
+`@futdevpro/nts-dynamo` bump minden érintett szerver-projektben (master-prompter, adventor,
+fdp-token-service), majd a lista-endpointok visszamérése (`_id` jelen van-e a válaszban).