@futdevpro/nts-dynamo 1.15.139 → 1.15.140

package/README.md

@@ -235,6 +235,39 @@ Data services provide a structured way to interact with MongoDB, simplifying Mon
 
 Instead of manually creating Mongoose schemas and models, you define data models through `DyFM_DataModel_Params` (from FSM), and Dynamo-NTS handles schema generation, model creation, and connection management automatically. Data services handle CRUD operations, data validation, dependency tracking, and provide methods for searching, filtering, and managing data relationships.
 
+### Atomic MongoDB transactions
+
+`DyNTS_MongoTransaction_ControlService` is the shared Bedrock entry point for business operations that must
+commit several MongoDB writes as one unit. The callback receives the same Mongoose `ClientSession` that must
+be attached to every participating query or write:
+
+```typescript
+import { ClientSession } from 'mongoose';
+
+import { DyNTS_MongoTransaction_ControlService } from '@futdevpro/nts-dynamo';
+
+const transactionService: DyNTS_MongoTransaction_ControlService =
+  DyNTS_MongoTransaction_ControlService.getInstance();
+
+const pipelineId: string = await transactionService.execute<string>({
+  transactionName: 'publish-pipeline-version',
+  issuer: 'pipeline-persistence-service',
+  maxCommitTimeMs: 3_000,
+  task: async (session: ClientSession): Promise<string> => {
+    // Every MongoDB operation in this callback must use `session`.
+    // Example: await model.updateOne(filter, update, { session: session });
+    // Example: await auditModel.create([ event ], { session: session });
+    return 'pipeline-id';
+  },
+});
+```
+
+The service uses snapshot reads, majority writes and primary routing, always closes the session, and emits
+stable content-free error codes. MongoDB transactions require a replica set or sharded deployment; a standalone
+MongoDB instance is intentionally not treated as transaction-capable. Mongoose may retry the callback after a
+transient transaction error, so the callback must not perform non-transactional side effects such as sending
+messages or mutating external systems.
+
 ### Routing System
 
 The routing system provides a structured approach to defining RESTful API endpoints, simplifying Express router configuration:

package/SKILLS.md

@@ -0,0 +1,75 @@
+# SKILLS.md — `dynamo-nts` tooling
+
+Ez a fájl a projektben **ténylegesen használt** CLI-ket és eszközöket írja le, hogy a coding agent
+(Codex / Claude Code) tudja, **mit mivel** kell futtatni. Kísérő fájlok: `CLAUDE.md` / `AGENTS.md`
+(szabályok + architektúra). Rule: `core-agent-file-sync`.
+
+> A `SKILLS:AUTO:BEGIN` … `SKILLS:AUTO:END` markerek közti rész **GENERÁLT** (forrás:
+> `__agent/scripts/skills-md-generate.ps1`; adat: a projekt `package.json`-jai, config-fájljai,
+> `__agent/scripts/` tartalma) — újrafuttatáskor **felülíródik**.
+> Az azon **kívüli** rész kézi és megőrződik: oda írd a projekt-specifikus jegyzeteket.
+
+<!-- SKILLS:AUTO:BEGIN -->
+## 1. Flotta-szintű CLI-k (mindenhol elérhetők)
+
+| CLI | Csomag | Mire való | Tipikus hívás |
+|---|---|---|---|
+| `dc` / `dyn-cli` | `@futdevpro/cli-dynamo` | Dynamo fejlesztői CLI: projekt-/kód-generálás, pipeline-futtatás, review, konvenció-validálás | `dc im` (interaktív), `dc cdp`, `dc ldp`, `dc rev --json` |
+| `fdp` / `fdp-cli` | `@futdevpro/fdp-cli` | DevOps + Overseer lekérdezés: deploy, runner, build-report, logok, errorok | `fdp build-detail --project <p>`, `fdp errors --range 24h`, `fdp deploy-service --services <n>` |
+| `dye2e` | `@futdevpro/dynamo-e2e` | E2E generátor + Visual-QA review-bundle | `dye2e generate-review-bundle`, `dye2e validate-manifest` |
+| `fam` | `fdp-agent-memory` (MCP `:39265`) | Tudás-keresés / recall / szabály-lekérés — **MINDEN feladat elején** (rule: `fam-use-preferentially`) | MCP `read` a `rules` / `documents` / `codebase` táron |
+| `pnpm` | — | **Az egyetlen** csomagkezelő a flottában (npm-kompatibilis) | `pnpm run prep`, `pnpm test` |
+
+**Alap-szabályok a CLI-kre** (kanonikus: `fdp-documentations/rules/fdp-global/`):
+- `fdp-use-existing-tooling` — a meglévő scriptet/CLI-t használd, ne írj sajátot mellé.
+- `fdp-cli-only` — a DevOps-műveletek az `fdp` CLI-n mennek, nem kézi docker/ssh parancsokon.
+- **Az NPM-scripteket ne bontsd szét** — a `pnpm test` már tartalmazza a build-lépést is.
+
+**Pipeline-ok:**
+- `dc ldp` — Live Dev Pipeline: felhúzza a LOKÁL instance-t és az ellen futtat (`pipeline.config.json`);
+  státusz: `server/logs/live-dev-pipeline/status.json`.
+- `dc cdp` — CI/CD Pipeline: a **deployolt test-szerver** ellen fut (`pipeline.cicd.config.json`).
+  A CI-t az **Overseer** vezérli, nem a GitHub Actions (az csak webhook-trigger).
+
+## 2. Ebben a projektben — MÉRT adatok
+
+> Forrás: a projekt `package.json`-jai, config-fájljai és `__agent/scripts/` tartalma, beolvasva a generáláskor.
+
+### 2.1 gyökér — `@futdevpro/nts-dynamo`
+
+
+| Script | Parancs |
+|---|---|
+| `pnpm run audit:eslintrc` | `dynamo-eslintrc-audit` |
+| `pnpm run build` | `npm run build-base && jasmine && npm publish` |
+| `pnpm run build-base` | `rimraf ./build && npx tsc` |
+| `pnpm run build-tgz` | `npm run build-base && jasmine && npm pack && move ./*.tgz ../tgz-collection/dynamo-nts` |
+| `pnpm run deploy` | `npm run build` |
+| `pnpm run ldp` | `dc ldp` |
+| `pnpm run lint` | `eslint src --ext .ts` |
+| `pnpm run lint:fix` | `eslint src --ext .ts --fix` |
+| `pnpm run prep` | `npm i -g pnpm rimraf nodemon && pnpm i` |
+| `pnpm run start` | `npm run prep && nodemon` |
+| `pnpm run start-clean` | `npm run clean && npm run start` |
+| `pnpm run test` | `npm run build-base && jasmine` |
+| `pnpm run test:coverage` | `npx c8 --reporter=html --reporter=text --reporter=lcov node scripts/run-coverage-tests.js` |
+| `pnpm run validate:imports` | `dynamo-validate-imports` |
+| `pnpm run validate:naming` | `dynamo-validate-naming` |
+
+**További scriptek (csak név):** `build-all` · `build-clean` · `build-n-test` · `build-simple` · `build-tgz-cheap` · `clean` · `clean-deploy` · `fix` · `fix:return-types` · `ldp:clear` · `ldp:status` · `ldp:stop` · `nodemon-run` · `prepare` · `preprep-setup-safechain-linux` · `preprep-setup-safechain-windows` · `start-first` · `test-clean`
+
+**Felismert eszközök a dependency-kből:** Dynamo ESLint konfiguráció (`@futdevpro/dynamo-eslint`) · ESLint (`eslint`) · Jasmine (unit teszt) (`jasmine`) · Socket.IO (`socket.io`) · TypeScript (`tsc`) (`typescript`)
+
+### Konfigurációk és belépési pontok (jelenlévő fájlok)
+
+- `.dynamo` — Dynamo CLI projekt-konfiguráció
+- `.github/workflows` — GitHub Actions (Overseer-migrált projektnél csak webhook-trigger)
+- `.husky` — Git hookok (pre-commit gate)
+- `__documentations` — Projekt-dokumentáció (ARCHITECTURE / DECISIONS / BEDROCK-FRS / CHANGELOG)
+<!-- SKILLS:AUTO:END -->
+
+## 3. Projekt-specifikus jegyzetek (KÉZI — a generátor nem írja felül)
+
+_Ide jön minden, amit mérésből nem lehet kiolvasni: buktatók, kötelező sorrendek, környezeti előfeltételek,
+credential-lelőhely, „ezt sose futtasd" figyelmeztetések. Ha itt üres, az annyit jelent: még nincs feljegyezve —
+NEM azt, hogy nincs ilyen (`core-no-guessing`)._

package/__documentations/2026-04-28-logs-module.md

@@ -0,0 +1,49 @@
+# 2026-04-28 — NTS Logs Module
+
+## Összefoglaló
+
+Beépített `/logs` endpoint modul az NTS framework-be. Bármelyik NTS-alapú szerver bekapcsolhatja.
+Verzió: v01.15.14+
+
+## Használat
+
+```typescript
+import { DyNTS_Logs_Service, DyNTS_getLogsRoutingModule } from '@futdevpro/nts-dynamo/logs';
+
+// 1. App startup-nál: log buffer install
+DyNTS_Logs_Service.getInstance().install();
+
+// 2. Log settings-ben: enable
+DyNTS_global_settings.log_settings.logs_endpoint = { enabled: true, maxEntries: 2000 };
+
+// 3. Routing module-ok közé: endpoint regisztráció
+getRoutingModules() {
+  return [
+    ...
+    DyNTS_getLogsRoutingModule(),                              // auth nélkül
+    DyNTS_getLogsRoutingModule({ authPreProcess: myAuth }),     // auth-tal
+  ];
+}
+```
+
+## Endpoint-ok
+
+- `GET /logs/get?tail=200` — utolsó N sor a bufferből (max 2000)
+- `DELETE /logs/clear` — buffer ürítés
+
+## Architektura
+
+- `DyNTS_Logs_Service` — singleton, in-memory ring buffer (console.log/error/warn intercept)
+- `DyNTS_Logs_Controller` — GET /get + DELETE /clear endpoint-ok
+- `DyNTS_getLogsRoutingModule(config?)` — factory, opcionális authPreProcess
+- Ha `logs_endpoint.enabled === false` → 503 response
+- Ha `install()` nem volt meghívva → 503 response
+
+## Fájlok
+
+- `src/_modules/logs/logs.service.ts`
+- `src/_modules/logs/logs.controller.ts`
+- `src/_modules/logs/get-logs-routing-module.util.ts`
+- `src/_modules/logs/index.ts`
+- `src/_models/interfaces/global-log-settings.interface.ts` — `logs_endpoint` setting
+- `src/_collections/global-settings.const.ts` — default values

package/__documentations/2026-05-17-oai-compatible-providers.md

@@ -0,0 +1,229 @@
+# 2026-05-17 — Using OpenAI-compatible providers with Dynamo-NTS
+
+**Spec:** `__agent/feature-requests/FR-005-oai-compat-docs.md` (workspace root)
+**Scope:** docs-only, LOW priority. Semmilyen TS-változás. NEM kell npm publish.
+
+---
+
+## Mire jó
+
+A Dynamo-NTS OAI service-ek — `DyNTS_OAI_LLM_ServiceBase`, `DyNTS_OAI_LLMChat_ServiceBase`, `DyNTS_OAI_Embedding_ControlService` — az `openai` npm SDK-t használják, és **out-of-the-box bármely OpenAI-API-kompatibilis endpoint-tal működnek** a `baseURL` override-on keresztül. Ez **MÁR MŰKÖDIK** (zéró kód-változás kell), csak eddig nem volt dokumentálva.
+
+A `baseURL` mező a `@futdevpro/fsm-dynamo/ai/open-ai` package `DyFM_OAI_ClientOptions` interface-en él. Bővebben a fsm-dynamo-szintű részletekért: [`@futdevpro/fsm-dynamo/__documentations/2026-05-17-oai-compatible-providers-howto.md`](../../dynamo-fsm/__documentations/2026-05-17-oai-compatible-providers-howto.md).
+
+Tipikus use-case-ek:
+- **Lokál fejlesztés** OpenAI-credits nélkül (LM Studio, Ollama)
+- **Self-hosted production** infrastruktúra (vLLM, LocalAI klaszter)
+- **Cost control** — nyílt-súlyú modellek drága cloud API helyett
+
+---
+
+## A pattern
+
+```typescript
+import { DyFM_OAI_Settings, DyFM_OAI_CallSettings } from '@futdevpro/fsm-dynamo/ai/open-ai';
+import { DyNTS_OAI_LLMChat_ServiceBase } from '@futdevpro/nts-dynamo/ai/open-ai';
+
+const settings: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://<provider-host>:<port>/v1',
+    apiKey: '<placeholder-or-real>',
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: '<provider-specific-model-id>',
+  }),
+});
+
+class MyChat extends DyNTS_OAI_LLMChat_ServiceBase {}
+const chat: MyChat = new MyChat(settings);
+```
+
+Csak `config.baseURL` + `config.apiKey` + `defaultSettings.useModel` kell. A többi (organization, project) lokál providereknél figyelmen kívül marad.
+
+A `DyNTS_OAI_Embedding_ControlService` és más OAI alapú service-ek ugyanezt a `DyFM_OAI_Settings`-t fogadják — egy konfig, minden service.
+
+---
+
+## Provider-specifikus minták
+
+### LM Studio (port 1234)
+
+Desktop GUI (Mac/Windows/Linux), beépített OAI-compat szerverrel. Lépések:
+1. Töltsd be a modellt a UI-ben (pl. embedding-hez `nomic-embed-text-v1.5`, chat-hez `llama-3.2-3b-instruct`)
+2. **Local Server** tab → **Start Server**
+
+```typescript
+const lmStudio: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localhost:1234/v1',
+    apiKey: 'lm-studio',  // bármilyen non-empty placeholder
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'nomic-embed-text-v1.5',  // ahogy a Local Server tab megjeleníti
+  }),
+});
+
+// Embedding-hez
+class Knowledge_DataService extends DyNTS_OAI_VectorDataService<Knowledge> {
+  constructor() { super(/* args */); }
+}
+```
+
+### Ollama (port 11434, OAI-compat layer ≥ v0.1.14)
+
+CLI-driven, multi-modell runner.
+
+```bash
+ollama pull llama3.2:3b
+ollama pull nomic-embed-text
+ollama serve
+```
+
+```typescript
+const ollama: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localhost:11434/v1',
+    apiKey: 'ollama',  // szintén placeholder
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'nomic-embed-text',  // `ollama list` mutatja
+  }),
+});
+```
+
+### vLLM (port 8000, production GPU)
+
+Python-alapú batched + PagedAttention inference. OAI-compat REST endpoint beépítve.
+
+```bash
+pip install vllm
+python -m vllm.entrypoints.openai.api_server \
+  --model meta-llama/Meta-Llama-3-8B-Instruct \
+  --port 8000 \
+  --api-key local-secret-token
+```
+
+```typescript
+const vllm: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://gpu-server:8000/v1',
+    apiKey: process.env.VLLM_API_KEY ?? 'local-secret-token',
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'meta-llama/Meta-Llama-3-8B-Instruct',  // a `--model` érték
+  }),
+});
+```
+
+### LocalAI (port 8080, REST multi-model)
+
+Go-alapú, multi-backend (llama.cpp + whisper.cpp + stable-diffusion).
+
+```bash
+docker run -p 8080:8080 \
+  -v $PWD/models:/build/models \
+  localai/localai:latest
+```
+
+```typescript
+const localai: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: {
+    baseURL: 'http://localai:8080/v1',
+    apiKey: 'sk-local',  // placeholder
+  },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: 'gpt-4',  // LocalAI alias — `models.yaml`-ban mapped
+  }),
+});
+```
+
+---
+
+## Dev → cloud quick recipe
+
+```typescript
+const isDev: boolean = process.env.NODE_ENV === 'development';
+
+export const aiSettings: DyFM_OAI_Settings = new DyFM_OAI_Settings({
+  config: isDev
+    ? {
+        baseURL: 'http://localhost:11434/v1',  // Ollama lokálban
+        apiKey: 'dev',
+      }
+    : {
+        apiKey: process.env.OPENAI_API_KEY,
+        organization: process.env.OPENAI_ORG_ID,
+      },
+  defaultSettings: new DyFM_OAI_CallSettings({
+    useModel: isDev ? 'llama3.2:3b' : 'gpt-4o',
+  }),
+});
+
+// Az összes Dynamo-NTS OAI service ugyanazt a settings-t fogyasztja:
+class ProdChat extends DyNTS_OAI_LLMChat_ServiceBase {}
+const chat: ProdChat = new ProdChat(aiSettings);
+```
+
+---
+
+## Caveats — service-szintű
+
+### Tool/function calling
+A `DyNTS_OAI_LLMChat_ServiceBase` tool-calling support csak akkor működik a lokál provider-eknél, ha:
+- **Ollama**: tool-aware modell (Llama-3.1+, Mistral újabb verziók)
+- **vLLM**: v0.6+ + megfelelő chat-template
+- **LM Studio**: model-függő, gyakran részleges
+- **LocalAI**: function-call backend kell konfigolni
+
+Production OpenAI-mintával írt service-ek **lokál providerre váltáskor** előbb tesztelni kell, hogy a tool-callok valóban triggerelnek-e.
+
+### Streaming chat
+A `DyNTS_OAI_LLMChat_ServiceBase` streaming (SSE) működik mindenhol, **de**:
+- Ollama < v0.1.20 streaming-stabilitás kérdéses
+- LocalAI streaming-rate alacsonyabb mint az emit-rate
+- vLLM/LM Studio: rendszeresen frissül, érdemes a provider-changelogot követni
+
+### Embedding-modellek
+A `DyNTS_OAI_Embedding_ControlService` `useModel`-je a provider-specifikus dedikált embedding modell **pontos ID**-ja:
+
+| Provider | Embedding model ID |
+|---|---|
+| OpenAI (cloud) | `text-embedding-3-small` / `text-embedding-3-large` |
+| LM Studio | `nomic-embed-text-v1.5` / `BAAI/bge-large-en-v1.5` |
+| Ollama | `nomic-embed-text` / `mxbai-embed-large` |
+| vLLM | csak ha az indítási `--model` embedding-képes (pl. `intfloat/e5-mistral-7b-instruct`) |
+| LocalAI | `text-embedding-ada-002` alias (vagy egyéb a `models.yaml`-ban) |
+
+### Context window / max-tokens
+A `DyFM_OAI_CallSettings.maxTokens` provider-szintű limit alá kell esnie, különben 400/422 jön vissza:
+
+| Provider | Default context-window | Override |
+|---|---|---|
+| OpenAI gpt-4o | 128K | API tier |
+| LM Studio | a betöltött modell native context | UI slider |
+| Ollama | **2048 (legacy default!)** | `OLLAMA_NUM_CTX` env / Modelfile `PARAMETER num_ctx` |
+| vLLM | a modell native context | `--max-model-len` flag |
+| LocalAI | `models.yaml` `context_size` | per-model konfig |
+
+### Error-handling
+- OpenAI cloud: standard 4xx/5xx + structured error body
+- Lokál providerek: 404 a modell-name-re (rossz ID), timeout első call-on (modell load), OOM vLLM-en
+- Ollama-specifikus: ha a modell még nem `pull`-olt, csendben várakozik a pull-ig — látszólag hang
+
+---
+
+## Reference
+
+| Fájl | Mit ad |
+|---|---|
+| `fsm-dynamo/.../oai-client-options.interface.ts` | `DyFM_OAI_ClientOptions.baseURL` — a kapcsoló mező |
+| `fsm-dynamo/.../oai-settings.control-model.ts` | `DyFM_OAI_Settings` — settings wrapper |
+| `dynamo-nts/.../oai-llm.service-base.ts` | `DyNTS_OAI_LLM_ServiceBase` — base LLM client (`openai` SDK instantiation) |
+| `dynamo-nts/.../oai-llm-chat.service-base.ts` | `DyNTS_OAI_LLMChat_ServiceBase` — chat service |
+| `dynamo-nts/.../oai-embedding.control-service.ts` | `DyNTS_OAI_Embedding_ControlService` — embedding service |
+
+További (fsm-szintű) részletek, ugyanezzel a 4 provider-mintázattal: [`dynamo-fsm/__documentations/2026-05-17-oai-compatible-providers-howto.md`](../../dynamo-fsm/__documentations/2026-05-17-oai-compatible-providers-howto.md).
+
+## Backward compatibility
+
+Docs-only. `baseURL` mindig is létezett az OpenAI SDK-ban, a Dynamo-NTS csak átadja a config-ot (`oai-llm.service-base.ts:91-98`). Ez a doc csak tisztázza a használati mintázatot — semmilyen TS-változás nincs.

package/__documentations/2026-05-17-static-client-serving-howto.md

@@ -0,0 +1,144 @@
+# Static client serving — how-to
+
+**Date:** 2026-05-17
+**Backlog:** [BL-20260417-001](../_specifications/BACKLOG.md) — DyNTS-kliens kiszolgálás képesség
+**Status:** ✅ done (audit + docs)
+
+## TL;DR
+
+A `DyNTS_App_Server` MÁR most ki tudja szolgálni a klienst (SPA-kat, statikus
+oldalakat) az API route-ok mellett ugyanazon a hoszton. Az implementáció
+2026-03-30 óta (commit `8ffe535`) része a frameworknek; a BL-20260417-001
+backlog entry post-dated a fejlesztést. Ez a how-to a meglévő capability-t
+dokumentálja.
+
+## Konfigurációs felület
+
+A static client serving akkor aktiválódik, ha a `DyNTS_App_Server`
+subclass-od `getStaticClientSettings()`-et override-olja és egy
+[`DyNTS_StaticClient_Settings`](../src/_models/interfaces/static-client-settings.interface.ts)
+objektumot ad vissza:
+
+```ts
+import { DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
+
+export interface DyNTS_StaticClient_Settings {
+  root: string;                  // a static fájlok mappája (abszolút v. cwd-relatív)
+  fallbackPath?: string;          // SPA fallback (pl. 'index.html')
+  assetCacheMaxAge?: number;      // asset Cache-Control max-age (sec)
+  assetCacheImmutable?: boolean;  // 'immutable' direktíva (Angular hashed fájlokra)
+  fallbackCacheMaxAge?: number;   // fallback file Cache-Control max-age (sec)
+}
+```
+
+## Példa subclass (Angular SPA)
+
+```ts
+import path from 'path';
+import { DyNTS_App_Server, DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
+
+export class MyApp_Server extends DyNTS_App_Server {
+  // ... egyéb override-ok (getAppParams, getPortSettings, getApiBasePath, stb.) ...
+
+  override getStaticClientSettings(): DyNTS_StaticClient_Settings | undefined {
+    return {
+      // Az Angular `dist/<app-name>` mappa abszolút path-ja
+      root: path.resolve(__dirname, '../../client/dist/my-app'),
+
+      // SPA — minden ismeretlen route a kliens-routerre megy
+      fallbackPath: 'index.html',
+
+      // Hashed assetek (Angular alapból ad nekik hash-et) — 1 év, immutable
+      assetCacheMaxAge: 31_536_000,
+      assetCacheImmutable: true,
+
+      // index.html-t SOHA ne cache-elje a böngésző (deploy után friss kell)
+      fallbackCacheMaxAge: 0,
+    };
+  }
+}
+```
+
+## Mit csinál a framework a háttérben
+
+A `DyNTS_App_Server.mountStaticClient()` ([app.server.ts ~1421-1484](../src/_services/server/app.server.ts))
+ezt automatikusan beállítja az API route-ok regisztrációja UTÁN:
+
+1. **`Express.static(root)` middleware** mount a `/` alatt. Ha `assetCacheMaxAge`
+   meg van adva, `setHeaders` callback-en keresztül beállítja a `Cache-Control:
+   max-age=<N>[, immutable]` header-t.
+2. **SPA fallback** (ha `fallbackPath` adott): minden ismeretlen GET kérésre
+   `res.sendFile(fallbackPath)` + `Cache-Control: max-age=<fallbackCacheMaxAge>`.
+3. **Default 404** (ha `fallbackPath` hiányzik): a beépített
+   [`DyNTS_defaultNotFoundPageHtml`](../src/_collections/default-not-found-page.const.ts)
+   kerül kiszolgálásra `status: 404` + `Content-Type: text/html`.
+4. **HTTP + HTTPS** mindkettő: a flow azonos a `this.openExpress` és
+   `this.secureExpress` instance-ekhez (ha mindkettő be van állítva).
+
+## Config matrix — mikor melyik mezőt használd
+
+| Use case | `root` | `fallbackPath` | `assetCacheMaxAge` | `assetCacheImmutable` | `fallbackCacheMaxAge` |
+|---|---|---|---|---|---|
+| **SPA** (Angular, React) hashed assetekkel | ✅ kötelező | `'index.html'` | `31_536_000` (1 év) | `true` | `0` (mindig friss) |
+| **SPA** dev mode (rebuild gyakori) | ✅ | `'index.html'` | `0` | `false` | `0` |
+| **Statikus oldal** (nincs SPA-router) | ✅ | hagyd ki | `3600` (1 óra) vagy ahogy jó | `false` | n/a |
+| **Csak API** (nincs frontend) | NE override-old a `getStaticClientSettings()`-et — akkor `undefined`-ot ad vissza és a `mountStaticClient` early-return-öl | | | | |
+
+## Asset + fallback cache stratégia (SPA)
+
+A két mező együttes használata az **alapja az Angular/React deploy-friendly caching**-nek:
+
+- **Hashed assetek** (`main.<hash>.js`, `styles.<hash>.css`, stb.) ÉLETBEN nem
+  változnak — biztonságosan `immutable` + 1 év max-age. A böngésző sose kérdezi
+  meg újra a szerverről, amíg a HTML egy új hash-elt nevet nem hivatkozik be.
+- **`index.html`** a "katalógus" ami a hashed assetekre mutat. Deploy után
+  AZONNAL friss kell legyen, különben a kliens régi assetekre hivatkozó régi
+  index.html-t kap → 404-ek a már nem létező hashed nevekre.
+  → `fallbackCacheMaxAge: 0` (no-cache).
+
+Az `assetCacheMaxAge` undefined-ja default (Express.static alapértelmezett) cache
+viselkedést hagy meg — production deploy-okra mindig explicit állítsd be.
+
+## Integration test minta
+
+A meglévő integration test fixture ([`DyNTS_AppIntegrationTest_Mock`](../src/_modules/mock/app-integration-test.mock.ts)) +
+spec ([app-extended.integration.spec.ts](../src/_modules/socket/app-extended.integration.spec.ts))
+mutatja a teljes flow-t:
+
+- A spec `beforeAll`-ban létrehoz egy temp dir-t, kitölti pár static fájllal,
+  beállítja a mock `integrationStaticRoot` static property-jét, majd elindítja
+  az appot.
+- A spec asszertálja:
+  - `started === true` (az app HTTP listenert kapott)
+  - GET nemlétező path → `404` + a default not-found HTML kiszolgálva
+  - GET `/index.html` → `200` + a temp dir-ben található static content
+  - GET `/api/test-0/test-base`, `/api/test-0/test-simple` → API kiszolgálva (az API
+    route-ok ELŐBB regisztráltak, mint a static fallback)
+- `afterAll`-ban leállítja az appot és kitakarítja a temp dir-t.
+
+## Edge case-ek + gotchák
+
+- **Mounting sorrend:** a `mountStaticClient` az `_routingModules` regisztráció
+  UTÁN fut, így az API route-ok prioritást élveznek. Tehát a `/api/...` mindig
+  az API-hoz megy, akkor is, ha a static root-ban véletlenül lenne `api/`
+  almappa.
+- **`fallbackPath` relatív** a `root`-hoz képest (`sendFile(fallbackPath, { root })`).
+- **Default 404 HTML:** szándékosan minimalista (`DyNTS_defaultNotFoundPageHtml`),
+  hogy ne ütközzön a kliens stílusával. Ha custom 404-et akarsz, add meg a
+  `fallbackPath`-t (az SPA-router majd kezelje belül a "page not found"-ot).
+- **CSP / security header-ek:** a `mountStaticClient` NEM állít be CSP-t —
+  ha kell, használj `helmet` middleware-t az API route-ok elé.
+
+## Releváns kód- és test-fájlok
+
+- [`src/_services/server/app.server.ts`](../src/_services/server/app.server.ts) — `mountStaticClient()` private + `getStaticClientSettings?()` opt-in override
+- [`src/_models/interfaces/static-client-settings.interface.ts`](../src/_models/interfaces/static-client-settings.interface.ts) — config interface
+- [`src/_collections/default-fallback-cache-max-age.const.ts`](../src/_collections/default-fallback-cache-max-age.const.ts) — default `0` (no-cache)
+- [`src/_collections/default-not-found-page.const.ts`](../src/_collections/default-not-found-page.const.ts) — default 404 HTML
+- [`src/_modules/mock/app-integration-test.mock.ts`](../src/_modules/mock/app-integration-test.mock.ts) — integration test fixture mintaként
+- [`__documentations/nts-integration-tests-2026-03-17.md`](./nts-integration-tests-2026-03-17.md) — első integration test bevezetése a unified host behavior-ra
+
+## Kapcsolódó backlog entry-k
+
+- **BL-20260420-001..004** (dynamo-nts) — `DyNTS_FileLog_Service` + admin endpoints. Mind ✅ done.
+- BL-20260417-001 (ez) — a kliens kiszolgálási képesség. ✅ done — implementáció már része a frameworknek; ez a doc a hivatkozás.

package/__documentations/2026-06-01-fr041-cors-middleware.md

@@ -0,0 +1,96 @@
+# FR-041 — CORS middleware infrastructure (2026-06-01)
+
+**Commit**: `3d16d69` — v01.15.35 → v01.15.36
+**Parent**: `__agent/feature-requests/FR-041-subdomain-per-service-architecture.md`
+**Pattern**: `fdp-documentations/guidelines/development/cors-and-subdomain-architecture.md`
+
+## What
+
+Adds CORS middleware infrastructure to `DyNTS_AppServer`. After this commit, any subclass that wants to be reachable cross-origin overrides `getCorsSettings()` and returns a `DyNTS_Cors_Settings` object.
+
+## Why
+
+Pre-FR-041: every cross-service call was same-origin via gateway nginx proxy (e.g. `<app>.futdevpro.hu/auth-api/*` → `fdp-auth-service:39005/api/*`). No CORS needed because same-origin.
+
+Post-FR-041: each sister service exposed at its own subdomain (`auth.futdevpro.hu`, `social.futdevpro.hu`, etc.). Cross-origin requires CORS allowlist.
+
+Audit pre-FR-041: ZERO existing CORS implementation in the entire FDP stack (`grep -rn "cors\|Access-Control" dynamo-nts/src` returned 0 hits). Greenfield work.
+
+## Design
+
+### `DyNTS_Cors_Settings` interface
+
+`src/_models/interfaces/cors-settings.interface.ts`:
+
+```typescript
+export interface DyNTS_Cors_Settings {
+  allowedOrigins: string[] | ((origin: string) => boolean) | '*';
+  allowCredentials?: boolean;        // default true
+  allowedMethods?: string[];          // default GET/POST/PUT/DELETE/PATCH/OPTIONS
+  allowedHeaders?: string[];          // default Authorization/Content-Type/X-Admin-Key/X-Requested-With
+  exposedHeaders?: string[];          // default Content-Length/Content-Type
+  maxAgeSeconds?: number;             // default 86400 (24h preflight cache)
+}
+```
+
+### `mountCors(express)` protected method
+
+`src/_services/server/app.server.ts` (~line 1422):
+
+- Reads `this.getCorsSettings?.()` ONCE at mount time. Undefined → returns immediately (no CORS headers, back-compat).
+- Express middleware: for each request, checks Origin against allowlist. Match → echoes the origin (NOT wildcard, because credentials require an exact origin echo) + sets Methods/Headers/Expose/MaxAge/Vary.
+- OPTIONS preflight short-circuits with 204.
+
+### `getCorsSettings?()` optional override
+
+Added to the class as `getCorsSettings?(): DyNTS_Cors_Settings | undefined;`. Subclasses opt in by implementing it.
+
+## Mount-points
+
+`initOpenExpress()` + `initSecureExpress()` both call `mountCors(this.<express>)` after BodyParser, BEFORE route mounting. CORS preflight always intercepts before any route handler can interfere.
+
+Timing verified: `asyncConstruct` line 410 `getAppParams()` (sets env via `FDPNTS_setEnvBase`) → line 1018 `initOpenExpress()` (calls `mountCors`). Env is always set by the time `getCorsSettings()` runs.
+
+## Why hand-rolled (no `cors` npm dep)
+
+- ~30 lines, zero new dependency
+- Full control over Vary/credentials/preflight semantics
+- Aligns with FDP "no unnecessary deps" philosophy
+
+## Spec coverage
+
+`src/_models/interfaces/cors-settings.interface.spec.ts` — 5 specs covering all `allowedOrigins` shapes (array, predicate, wildcard) + credential defaults + custom headers.
+
+`npx jasmine` post-change: **1250/0** (146 pending pre-existing, all 5 new specs green).
+
+## Consumer pattern
+
+```typescript
+import { DyNTS_Cors_Settings } from '@futdevpro/nts-dynamo';
+import { FDPNTS_buildCorsSettings } from '@futdevpro/nts-fdp-templates';
+
+export class App extends DyNTS_App {
+  override getCorsSettings(): DyNTS_Cors_Settings | undefined {
+    return FDPNTS_buildCorsSettings();   // env-aware allowlist from FDP-templates
+  }
+}
+```
+
+First consumer: `LIVE-projects/fdp-auth-service` commit `1319368`.
+
+## What's NOT in this commit
+
+- Per-env allowlist source (lives in `fdp-templates v01.15.38`, commit `0f793c4`)
+- Helper for FDPNTS apps to bind that allowlist (lives in `fdp-templates-nts v01.15.45`, commit `6e748ee`)
+
+## Wave-3 cleanup candidates
+
+- Once every app overrides `getCorsSettings()`, consider making it abstract (no more optional `?`).
+- OPTIONS-without-origin-match returns 204 + no CORS headers (functional: browser denies). Could be improved to 403 for clearer security audit.
+
+## Cross-references
+
+- `fdp-documentations/guidelines/development/cors-and-subdomain-architecture.md`
+- `NPM-packages/fdp-templates/src/_constants/environment/fdp-cors-origins.const.ts` — allowlist
+- `NPM-packages/fdp-templates-nts/src/_collections/cors-settings.util.ts` — consumer helper
+- `LIVE-projects/fdp-auth-service/src/app.server.ts` — first consumer