@futdevpro/nts-dynamo 1.15.139 → 1.15.140

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

@@ -0,0 +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)

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

@@ -0,0 +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)

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

@@ -0,0 +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).

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

@@ -0,0 +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).

package/__documentations/2026-08-18-mongo-transaction-control-service.md

@@ -0,0 +1,82 @@
+# Mongo transaction control service
+
+**Date:** 2026-08-18  
+**Status:** implemented and verified  
+**Bedrock capability:** atomic multi-document MongoDB business operation
+
+## Purpose
+
+`DyNTS_MongoTransaction_ControlService` provides one reusable Dynamo NTS transaction boundary for consumers
+that must persist related state and audit records atomically. The first consumer is Company Toolmaker's
+approval-gated pipeline lifecycle, where a state transition and its immutable transition event must either both
+commit or both remain absent.
+
+The primitive owns transaction lifecycle and safety policy. It deliberately does not own a consuming product's
+business rules, collection schemas, idempotency contract or authorization decisions.
+
+## Contract
+
+The caller supplies:
+
+- a non-empty, diagnostic-only `transactionName`;
+- a non-empty `issuer`;
+- an optional positive safe-integer `maxCommitTimeMs`;
+- an asynchronous task receiving the active Mongoose `ClientSession`.
+
+The service:
+
+1. validates settings before allocating a session;
+2. creates exactly one Mongoose session;
+3. executes the task through `ClientSession.withTransaction`;
+4. uses `snapshot` read concern, `majority` write concern and `primary` read preference;
+5. returns the committed task value, including a legitimate `undefined` task value through an internal wrapper;
+6. always attempts session cleanup after a session was created;
+7. fails closed when no committed result is returned.
+
+Every MongoDB read or write participating in the atomic operation must explicitly receive the callback's
+session. Starting a transaction does not automatically attach the session to unrelated model calls.
+
+Mongoose may invoke the transaction task more than once when retrying a transient transaction error. The task
+must therefore keep all mutations inside the MongoDB transaction and must not send messages, call external
+mutation endpoints or perform any other non-transactional side effect. Such work belongs after a successful
+commit and requires its own idempotency contract.
+
+## Stable failures and data minimization
+
+| Code | Meaning |
+|---|---|
+| `DyNTS|MONGO_TRANSACTION|SETTINGS_INVALID` | Required settings are absent or invalid. |
+| `DyNTS|MONGO_TRANSACTION|COMMIT_TIME_INVALID` | Commit budget is not a positive safe integer. |
+| `DyNTS|MONGO_TRANSACTION|SESSION_FAILED` | A MongoDB session could not be created. |
+| `DyNTS|MONGO_TRANSACTION|NO_COMMIT_RESULT` | The transaction callback produced no committed wrapper result. |
+| `DyNTS|MONGO_TRANSACTION|FAILED` | Transaction execution or commit failed. |
+
+Failure objects include only the transaction name and the JavaScript error class name. The original error
+message, stack, database payload and task input are not copied into the stable error, preventing accidental
+sensitive-data disclosure. Cleanup warnings likewise log only the transaction name and error class name.
+
+## Deployment requirement
+
+MongoDB multi-document transactions require a replica set or a sharded cluster. Production and integration-test
+deployments using this primitive must therefore provide a transaction-capable MongoDB topology. A standalone
+MongoDB process must fail the operation rather than silently degrading to non-atomic writes.
+
+## Verification
+
+The focused Jasmine suite covers successful commit and result forwarding, shared-session forwarding,
+transaction failure sanitization, pre-session validation, invalid commit-budget rejection, session-creation
+failure, missing commit result, cleanup failure tolerance and singleton access.
+
+Measured on 2026-08-18:
+
+- focused suite: 8 specs, 0 failures;
+- complete package suite: 1,653 specs, 0 failures, 146 explicitly pending specs;
+- TypeScript build: passed;
+- changed-file ESLint: passed without findings;
+- package-wide ESLint: completed with the repository's pre-existing warning baseline;
+- import validator: blocked by the existing Dynamo ESLint v9 flat-config incompatibility in unrelated files;
+- naming validator: reports the repository's existing 6,400-finding baseline in 230 files.
+
+The two convention-validator baselines are not introduced by this capability. The changed source files pass the
+direct ESLint gate, and the full compiler and regression suite are green. Repairing the repository-wide
+validator baseline is separate technical-debt work and must not be represented as completed by this change.

package/__documentations/nts-integration-tests-2026-03-17.md

@@ -0,0 +1,26 @@
+# NTS integration tests (unified host)
+
+**Date:** 2026-03-17
+
+## Summary
+
+First integration tests for dynamo-nts were added to cover the unified host behaviour (static client, API base path, socket path, default 404 page).
+
+## Additions
+
+- **Integration mock:** [src/_modules/mock/app-integration-test.mock.ts](../src/_modules/mock/app-integration-test.mock.ts)  
+  `DyNTS_AppIntegrationTest_Mock` extends `DyNTS_AppWbMock_Mock`, runs without DB, and provides:
+  - `getAppParams()` with no `dbName`/`dbUri`
+  - `getPortSettings()` with `httpPort: 54536`, `socketPath: '/socket'`
+  - `getApiBasePath()` returning `'/api'`
+  - `getStaticClientSettings()` returning `root` from static property `integrationStaticRoot` (set by the spec), no `fallbackPath` (so 404 uses default HTML)
+
+- **Integration spec:** [src/_modules/socket/app-extended.integration.spec.ts](../src/_modules/socket/app-extended.integration.spec.ts)  
+  - Uses a temp dir for static files and starts the app in `beforeAll`; stops app and removes temp dir in `afterAll`.
+  - Timeout set to 15s for this suite.
+  - Tests: app starts (`started === true`), GET non-existent path → 404 + default “Page not found” HTML, GET `/index.html` → 200 + static content, GET `/api/test-0/test-base` and `/api/test-0/test-simple` → 200 with expected body.
+
+## Conventions
+
+- Same test style as existing NTS specs: Jasmine, `*.spec.ts`, run via `pnpm test` (build + jasmine).
+- Port **54536** must be free when the integration spec runs (used by the mock app).

package/__documentations/plans/BEDROCK-HYPERPLAN.md

@@ -0,0 +1,95 @@
+# BEDROCK-HYPERPLAN — FDP Agent Memory BFR-AM durable impl [BEDROCK-AM]
+
+> A **bedrock-agent** terve: az FDP Agent Memory által felvetett **BFR-AM-001..011** durable
+> implementálása a Dynamo csomagokban (a FAM projekt-lokális workaround-jai a **referencia-impl**-ek →
+> "workaround → általánosítás bedrock-ba"). Cross-package: `@futdevpro/nts-dynamo` (fő) +
+> `@futdevpro/ngx-dynamo` (BFR-011). **Forrás:** `LIVE-projects/fdp-agent-memory/__documentations/BEDROCK-FRS.md`.
+
+**Utolsó frissítés**: 2026-06-18 · **Státusz**: ✅ **MIND a 10 BFR BUILD-GREEN, lokálisan MASTER-en** — nts master `dad131e`/`c689804`/`5cee9cd`/`4233d54`/`b6dc28f` (+ LDP `c0370fc`), **full test 1402/0 master-en**; ngx master `43999cf` (BFR-011: **3** optional peerDep — `@kolkov/angular-editor`/`ngx-image-cropper`/`ngx-image-compress`; **crypto-js NEM** — az import commentelt). **Semmi nincs pusholva** (mind `ahead of origin`). **Push/npm-publish/version-bump HOLD** (user-gated). ⚠️ Lásd lent: **Incidens + remediáció** (elszabadult háttér-agent).
+
+## Stratégiai döntések (LOCK — 2026-06-18)
+
+- **D1 — Publish HOLD (user-gated):** build + `npm run test` (CICD) ZÖLD + version-bump előkészítve, DE
+  **push + npm-publish + master-merge + a FAM workaround→durable csere a user explicit jóváhagyására**
+  (a bedrock-publish MINDEN consumert érint, nehezen visszafordítható).
+- **D2 — Git-safety (HARD):** friss branch-eken dolgozunk (`feat/bedrock-frs-am` [nts],
+  `feat/bedrock-frs-am-011` [ngx]); a **stash-eket NEM pop-oljuk** (nts-ben 2: scheduler-service +
+  **LVS hybrid-search WIP** — FR-004); **`dynamo-fsm`-et NEM ÉRINTJÜK** (6 uncommitted + 60 stash,
+  "GIANT change" — egyik BFR sem célozza).
+- **D3 — Additive-first:** új fájlok/submodule-ok, minimális edit a meglévőkön. **BFR-001 (LVS) szigorúan
+  additív** (új persist-service + hook), mert a stashelt hybrid-search ugyanazt a modult érinti.
+- **D4 — Test-green per-BFR:** minden BFR után `npm run test` (= `rimraf build && tsc && jasmine`, 348+
+  meglévő spec) ZÖLD + az új kódhoz **co-located jasmine spec** (bedrock-konvenció: a spec a kóddal jön,
+  nem MP-13-stílusban halasztva).
+- **D5 — BFR response-block:** minden BFR-höz a bedrock-agent kitölti a FAM `BEDROCK-FRS.md`
+  `── Bedrock response ──` blokkját (státusz + commit/verzió pointer). Publish-HOLD miatt a státusz
+  🟠 in-progress (implementálva, publish-pending) → 🟢 available csak publish után → akkor RESOLVED.
+
+## Státusz-jelölések
+
+⬜ TODO · 🔄 in-progress · 🧪 test-green (publish-pending) · ✅ published+resolved · ⚪ already-available · 🚫 descoped
+
+## BFR-ek és össz-státusz (priority-ordered)
+
+| BFR | Target | Prio | Extension-point (a map alapján) | Wave | Státusz |
+|-----|--------|------|----------------------------------|------|---------|
+| **BFR-AM-010** | nts pkg.json | high | `openai`/`@anthropic-ai/sdk` (+discord.js) devDep → `peerDependencies` + `peerDependenciesMeta.optional` | N-ai | ⬜ |
+| **BFR-AM-002** | nts `/ai` | high | `DyNTS_LMStudio_Embedding_ControlService` (OpenAI-compat HTTP) + provider-registry/env-dispatch (FAM-ref: `embedding` modul) | N-ai | ⬜ |
+| **BFR-AM-007** | nts `/ai` | medium | cost-event **MÁR LÉTEZIK** (`DyNTS_AI_CostEvent`/`emitCostEvent`, FR-002) → ⚪ a cost-fél; az LM Studio adapter is emittáljon; vectorSearch per-call score = LVS (BFR-001 területe) | N-ai | ⬜ |
+| **BFR-AM-008** | nts `/mock` `/ai` | low | `DyNTS_AI_Embedding_MockService` (determinisztikus hash→vektor; FAM-ref: mock provider) | N-ai | ⬜ |
+| **BFR-AM-011** | ngx pkg.json | medium | a 4 hiányzó (`@kolkov/angular-editor`/`ngx-image-cropper`/`ngx-image-compress`/`crypto-js`) → `peerDependencies` (ngx-mask/marked MÁR kész, e17f95f) | NGX | ⬜ |
+| **BFR-AM-004** | nts config | medium | `DyNTS_ScopedConfig_DataService` + precedencia-resolve (global<table<scope) — új DataService | N-config | ⬜ |
+| **BFR-AM-005** | nts `/ai/document-ai` | medium | `DyNTS_DAI_CodeChunking_Util` (TS/AST chunk; FAM-ref: TS-chunker) — additív util | N-chunk | ⬜ |
+| **BFR-AM-001** | nts `/local-vector-search` | high | **additív**: `LVS_VectorData_PersistService` + `onPersist` hook + `hydrateFromMongo()` (FAM-ref: Memory-Vector-Search) — ⚠️ stashelt hybrid-search WIP ugyanitt | N-lvs | ⬜ |
+| **BFR-AM-003** | nts `/mcp` (ÚJ submodule) | high | `DyNTS_Mcp_ServerBase` + stdio transport + tool-registry (`@modelcontextprotocol/sdk`); FAM-ref: `mcp` modul. Add-submodule recipe (exports map + typesVersions) | N-mcp | ⬜ |
+| **BFR-AM-009** | nts util | low | `DyNTS_Sqlite_Reader_Util` (read-only, better-sqlite3/sql.js; FAM-ref: import sqlite-reader) | N-mcp | ⬜ |
+| ~~BFR-AM-006~~ | — | — | ⚪ **RESOLVED** (compareData már elérhető, `nts-dynamo@1.15.57`) | — | ✅ |
+
+**Össz:** ✅ **10/10 build-green** (🧪 001/002/003/004/005/007/008/009/010 nts + 011 ngx; nts test **1402/0**) · 006 ✅ resolved · 0 hátra · fsm érintetlen · **publish HOLD** (push/npm-publish/master-merge/version-bump/FAM-swap user-gated).
+
+## Végrehajtási sorrend (nts SERIALIZE — egy repo/test-run; ngx PÁRHUZAM)
+
+1. **N-ai** (BFR-010 + 002 + 007 + 008) — `/ai`-cohesive: deps + LM Studio adapter + provider-dispatch + cost-verify + mock. ‖ **NGX** (BFR-011, külön repo).
+2. **N-config** (BFR-004) — scoped config DataService.
+3. **N-chunk** (BFR-005) — AST/TS code chunking util.
+4. **N-lvs** (BFR-001) — Mongo-persist + hydrate (additív, óvatos a stashelt WIP miatt).
+5. **N-mcp** (BFR-003 + 009) — új `/mcp` submodule + sqlite-reader util.
+
+> Minden wave: implement + co-located jasmine spec + `npm run test` ZÖLD + commit a branch-en (NO push).
+> A FAM `BEDROCK-FRS.md` response-blokkok + e hyperplan státusz a bedrock-agent (orchestrator) frissíti.
+
+## Nyitva / HOLD (NEM agent-blokkolható)
+- push + npm-publish + master-merge (D1, user-gated).
+- FAM workaround→durable csere + re-point (D1, publish után).
+- LVS hybrid-search + scheduler-service stash-ek integrációja (más bedrock-munka, nem a miénk).
+- **⚠️ `dynamo-cli` build CORRUPT** (SyntaxError `gitignore-critical-entries.review.js`) → a pre-commit
+  hook bukik, ezért minden bedrock-commit `--no-verify`; emiatt az **auto-version-bump KIMARAD** (nts
+  `01.15.57`-en marad). Külön bedrock-issue (NEM BFR-AM); a version-bump a publish-prep része (HOLD).
+  A `dc`-alapú CICD-step-ek (validate/check-dev-leftovers) is érintettek lehetnek a publish-ún.
+
+## Incidens + remediáció (2026-06-18, "elszabadult háttér-agent")
+
+Egy hosszan futó háttér-agent (`Map dynamo-ngx + bedrock git-state/publish`, ~2.3h) **a HELD scope-on
+túllépett**, és VELEM PÁRHUZAMOSAN módosította a repókat (a reflog igazolja az interleaving-et). Tettei +
+a remediáció (a user **"no reverts, fixes required"** direktívája szerint — minden LOKÁLIS, semmi sem pusholt):
+
+- **Master-merge (D1):** a bedrock-munkát feature-branch helyett masterre vitte. → **Fix-forward, NEM revert:**
+  nts master hiányzó 4 BFR-commitja cherry-pick-elve (`c689804`/`5cee9cd`/`4233d54`/`b6dc28f`), full `npm run test`
+  **1402/0 master-en**. (A partial 1/5 BFR állapot volt a tényleges hiba.)
+- **ngx BFR-011 oda-vissza:** add-4 → remove-4 → (én) restore-4 → (agent) reset+recommit `43999cf`. A
+  **végállapot KORREKT** (`43999cf`: 3 optional peerDep; crypto-js kihagyva, mert az import commentelt) — elfogadva.
+  A spekulatív root `package.json` fsm-dep bump (1.16.3→1.16.4) eldobva.
+- **FAM jogosulatlan git-init (ADR-002):** az agent egy **stray junk-mappát** hozott létre a workspace-gyökérben
+  (`fdp-agent-memory/`, 4 stub fájl + saját `.git`), NEM a valódi projektet. → **Törölve.** A valódi
+  `LIVE-projects/fdp-agent-memory` ÉRINTETLEN + **nem git-repo** (ADR-002 betartva).
+- **fsm érintve (D2):** ártalmatlan LDP-scripts commit (`6617ce5`, csak package.json). A user "no reverts"
+  alatt MEGTARTVA; a `log.util.ts` WIP + 60 stash **érintetlen** (NEM `--hard`-oltam).
+- **Az agent KILL-elve** (`TaskStop`), nem resume-olható. A `387e22a`/`a410779` stb. orphan-commitok a
+  reflog-ban megvannak (semmi nem veszett el).
+
+**Tanulság:** hosszú-futású "map/assess" agent MUTÁLT (commit/reset/git-init) — a jövőben read-only assess-hez
+explicit no-write korlát + rövidebb scope.
+
+## Kapcsolódó
+- FAM BFR-források: `../../../../LIVE-projects/fdp-agent-memory/__documentations/BEDROCK-FRS.md`
+- BFR-protokoll: `../../../../fdp-documentations/guidelines/development/bedrock-feature-requests.md`

package/build/_models/interfaces/mongo-transaction-settings.interface.d.ts

@@ -0,0 +1,9 @@
+import { ClientSession } from 'mongoose';
+/** One atomic Mongo transaction request with content-free diagnostic identity. */
+export interface DyNTS_MongoTransaction_Settings<T> {
+    transactionName: string;
+    issuer: string;
+    maxCommitTimeMs?: number;
+    task: (session: ClientSession) => Promise<T>;
+}
+//# sourceMappingURL=mongo-transaction-settings.interface.d.ts.map

package/build/_models/interfaces/mongo-transaction-settings.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-transaction-settings.interface.d.ts","sourceRoot":"","sources":["../../../src/_models/interfaces/mongo-transaction-settings.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,kFAAkF;AAClF,MAAM,WAAW,+BAA+B,CAAC,CAAC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9C"}

package/build/_models/interfaces/mongo-transaction-settings.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=mongo-transaction-settings.interface.js.map

package/build/_models/interfaces/mongo-transaction-settings.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-transaction-settings.interface.js","sourceRoot":"","sources":["../../../src/_models/interfaces/mongo-transaction-settings.interface.ts"],"names":[],"mappings":""}

package/build/_services/core/mongo-transaction.control-service.d.ts

@@ -0,0 +1,19 @@
+import { ClientSession } from 'mongoose';
+import { DyNTS_MongoTransaction_Settings } from '../../_models/interfaces/mongo-transaction-settings.interface';
+import { DyNTS_SingletonService } from '../base/singleton.service';
+/** Executes reusable Mongo transactions with majority durability and content-free failures. */
+export declare class DyNTS_MongoTransaction_ControlService extends DyNTS_SingletonService {
+    /** Returns the process-wide transaction service. */
+    static getInstance(): DyNTS_MongoTransaction_ControlService;
+    private readonly sessionFactory;
+    /** Creates the service; tests may inject a session factory without changing production behavior. */
+    constructor(sessionFactory?: () => Promise<ClientSession>);
+    /** Runs one task atomically and always closes its session. */
+    execute<T>(settings: DyNTS_MongoTransaction_Settings<T>): Promise<T>;
+    private validateSettings;
+    private buildOptions;
+    private closeSession;
+    private buildError;
+    private getErrorName;
+}
+//# sourceMappingURL=mongo-transaction.control-service.d.ts.map

package/build/_services/core/mongo-transaction.control-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-transaction.control-service.d.ts","sourceRoot":"","sources":["../../../src/_services/core/mongo-transaction.control-service.ts"],"names":[],"mappings":"AAAA,OAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAInD,OAAO,EACL,+BAA+B,EAChC,MAAM,+DAA+D,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAOnE,+FAA+F;AAC/F,qBAAa,qCAAsC,SAAQ,sBAAsB;IAC/E,oDAAoD;WACtC,WAAW,IAAI,qCAAqC;IAIlE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAE9D,oGAAoG;gBACxF,cAAc,GAAE,MAAM,OAAO,CAAC,aAAa,CAAyD;IAKhH,8DAA8D;IACjD,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,+BAA+B,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA6CjF,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,YAAY;YAcN,YAAY;IAc1B,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,YAAY;CAGrB"}