@futdevpro/nts-dynamo 1.15.139 → 1.15.141

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/2026-08-18-standalone-account-security-and-privacy-bedrock.md

@@ -0,0 +1,131 @@
+# Standalone account security and privacy Bedrock
+
+**Date:** 2026-08-18  
+**Status:** implemented and verified at package-contract level  
+**Packages:** `@futdevpro/nts-dynamo/account-security`, `@futdevpro/nts-dynamo/privacy-lifecycle`
+
+## Purpose and boundary
+
+This capability lets a Dynamo application own its identity and GDPR lifecycle without redirecting to, or
+depending on, a shared Fleet account. It is reusable Bedrock code, not a complete application account system.
+The consuming product remains responsible for typed persistence models, email delivery, organization and
+permission decisions, HTTP transport, secure browser credential handling, rate limiting, audit wiring and each
+product data-domain contributor.
+
+The modules deliberately expose direct Dynamo contracts. They do not add provider-swapping or replacement
+abstractions around Dynamo.
+
+## Account-security contract
+
+### Passwords
+
+`DyNTS_AccountPassword_ControlService` uses the versioned `dyn-scrypt-v1` format with a unique random salt,
+bounded scrypt parameters and timing-safe verification. It supports a SHA-256 common-password denylist and
+returns `needsRehash` when stored parameters differ from current policy. Malformed stored hashes and
+attacker-controlled work factors produce a safe negative result while still performing bounded dummy work.
+Passwords are never copied into errors.
+
+### Email verification and password reset
+
+`DyNTS_AccountChallenge_ControlService` issues opaque 256-bit-or-stronger credentials for two isolated purposes:
+email verification and password reset. Only SHA-256 token hashes enter persistence. Issuing a replacement
+atomically revokes its active predecessor for the same subject and purpose. Consumption must be a single
+compare-and-set operation that validates purpose, active state and expiry before marking the record consumed.
+Raw tokens are returned only once after successful persistence.
+
+Enumeration-neutral register/reset responses are an HTTP-boundary responsibility: the service must not reveal
+whether an email exists. The application must rate-limit issue and consume operations and deliver the raw token
+only through an approved out-of-band channel.
+
+### Sessions
+
+`DyNTS_AccountSession_ControlService` uses opaque random access and refresh credentials; no self-contained JWT is
+required. Only hashes are stored. An access credential resolves through an active server-side session, so
+logout, password change, account restriction and incident response can revoke it immediately.
+
+Refresh credentials are one-time ledger entries. Rotation uses an adapter-provided compare-and-set transaction.
+Reuse of an already consumed credential, including a concurrent rotation race, revokes the entire family. The
+user-safe session projection excludes subject, family and token hashes. The application decides authorization
+before calling individual or subject-wide revocation methods.
+
+The adapter contract is normative: session creation, token replacement and token-state changes must be atomic.
+An in-memory or multi-step production adapter would invalidate replay protection.
+
+## Privacy lifecycle contract
+
+### Data-subject requests
+
+`DyNTS_PrivacyLifecycle_ControlService` creates subject-, organization- and request-type-scoped idempotency
+hashes. The raw idempotency key is never stored. Each request has an explicit policy-supplied deadline and uses
+the following durable state family:
+
+`received → identity-verified → scoped → planned → executing → verifying → completed`
+
+Supported terminal/non-happy states are `partially-completed`, `rejected-with-reason`, `cancelled`,
+`failed-retryable` and `failed-terminal`. The current orchestrator produces `completed` or
+`partially-completed`; policy-specific rejection/cancellation/failure entry points remain consumer-owned until a
+shared cross-product transition contract is justified.
+
+Every registered contributor is ordered deterministically. Its durable `plan`, idempotent `execute` and
+read-only `verify` operations return content-free structured outcomes. Planning finishes and is persisted before
+the request enters `planned`; a planning failure becomes a resumable partial outcome without executing another
+domain against an incomplete plan set. Successful contributors are skipped on resume and failed contributors
+are retried. A retention result is valid only with an explicit matching basis code. Cross-subject reads return
+the same not-found response as an absent request.
+
+The consuming application must register contributors for identity, session, membership, pipelines/projects,
+agent sessions, artifacts, audit, support, subscription/billing and backup where those domains exist. Export
+contributors must generate machine-readable, checksummed, short-lived artifacts; erasure contributors must use
+hard delete by default and anonymize only where a documented retention basis requires it.
+
+### Legal acceptance and consent
+
+`DyNTS_PrivacyLedger_ControlService` keeps legal acceptance separate from optional-purpose consent. Legal records
+bind the subject to an exact document type, version and SHA-256 checksum. Consent is append-only and scoped by
+purpose and policy version; withdrawal creates a new event instead of mutating history. The ledger projection
+returns both full history and the latest decision per purpose.
+
+Adapters must enforce tenant/subject scoping and idempotency uniqueness. Document and privacy-notice content is
+not stored in these event records; the checksum binds the separately versioned canonical document.
+
+## Data-minimization and diagnostics
+
+- No password, bearer credential, challenge credential or raw idempotency key is persisted by these services.
+- Stable error messages contain no email address, token, password, file content, cell content or contributor
+  exception text.
+- Session context is intentionally pre-redacted: device label plus IP and user-agent hashes only.
+- Contributor outcomes carry codes, counts, checksums and retention basis, not exported personal data.
+- User-facing request, consent and legal-acceptance views omit idempotency hashes and request fingerprints;
+  those fields remain server-side persistence metadata.
+- Consumers must preserve this boundary in logs, audits, HTTP errors and analytics snapshots.
+
+## Required production integrations
+
+Before a product can claim production readiness, it must provide and test:
+
+1. transaction-safe MongoDB adapters for challenges, sessions, privacy requests and ledgers;
+2. normalized unique identity records and verified-email privilege gates;
+3. API rate limits for register, login, challenge issue/consume and refresh;
+4. a reviewed browser credential transport/storage threat model;
+5. organization membership and permission checks at every tenant-scoped route;
+6. all applicable DSAR contributors, export delivery expiry and backup restore/re-erasure procedure;
+7. content-redaction snapshots for logs, errors, analytics and audit events;
+8. automated feature and cross-feature user-journey E2E coverage including cleanup.
+
+## Verification
+
+Measured on 2026-08-18:
+
+- account password suite: 7 specs, 0 failures;
+- session suite: 10 specs, 0 failures;
+- one-time challenge suite: 5 specs, 0 failures;
+- privacy lifecycle suite: 7 specs, 0 failures;
+- privacy ledger suite: 5 specs, 0 failures;
+- complete package suite: 1,687 specs, 0 failures, 146 explicitly pending specs;
+- TypeScript build: passed;
+- changed-module ESLint: passed with zero warnings;
+- package import validator: existing baseline, 82 findings in 76 files;
+- package naming validator: existing baseline, 101 findings in 68 files.
+
+The repository-wide convention findings predate this capability and are not represented as fixed. The new
+modules pass their direct compiler, lint and regression gates.

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).