@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

package/build/src/_routes/server/api/api.controller.js

@@ -1,16 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Api_Controller = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const nts_dynamo_2 = require("@futdevpro/nts-dynamo");
 const fam_version_const_1 = require("../../../_collections/fam-version.const");
-const fam_heap_guard_control_service_1 = require("../../../_collections/fam-heap-guard.control-service");
 const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const fam_config_level_type_enum_1 = require("../../../_enums/fam-config-level.type-enum");
+const fam_operation_queue_service_1 = require("../../../_collections/fam-operation-queue.service");
+const fam_scan_job_control_service_1 = require("../../../_modules/ingest/_services/fam-scan-job.control-service");
+const fam_vector_search_control_service_1 = require("../../../_modules/embedding/_services/fam-vector-search.control-service");
 const config_control_service_1 = require("../config/config.control-service");
+const errors_control_service_1 = require("../errors/errors.control-service");
+const fam_error_data_model_1 = require("../../../_models/data-models/fam-error.data-model");
 const embedding_1 = require("../../../_modules/embedding");
 const ingest_1 = require("../../../_modules/ingest");
 const mcp_1 = require("../../../_modules/mcp");
+const fam_doctor_control_service_1 = require("./fam-doctor.control-service");
+const retrieval_1 = require("../../../_modules/retrieval");
+const fam_request_origin_util_1 = require("../../../_collections/fam-request-origin.util");
 /** A UI/CLI lapozás CCAP-örökség konstansai (dsgn-010/dsgn-011 §4.1). */
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 500;
@@ -51,6 +61,9 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             this.writeEndpoint(),
             this.capabilitiesEndpoint(),
             this.healthEndpoint(),
+            this.doctorEndpoint(),
+            this.rulesInjectEndpoint(),
+            this.rulesPropagateEndpoint(),
             this.itemsEndpoint(),
             this.statsEndpoint(),
             this.statsTableEndpoint(),
@@ -58,6 +71,12 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             this.duplicatesEndpoint(),
             this.configGetEndpoint(),
             this.configSetEndpoint(),
+            this.scanStartEndpoint(),
+            this.scanStatusEndpoint(),
+            this.scanJobsEndpoint(),
+            this.scanCancelEndpoint(),
+            this.errorsSummaryEndpoint(),
+            this.errorsEndpoint(),
         ];
     }
     // =========================================================================
@@ -108,6 +127,14 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
                         // Heap-load-shed (OOM-hibakezelés): a NEHÉZ write-eket (scan/import/re-embed) critical
                         // memória-nyomásnál elutasítjuk (503), MIELŐTT egy nagy allokáció átlökné a plafont.
                         this.assertHeapCapacity(String(input.operation));
+                        // FEAT-008 (user-FR 2026-06-22): a NEHÉZ write-ek SZERVER-OLDALI QUEUE-n mennek át → a szerver
+                        // szerializálja őket (egyszerre egy), így több agent egyidejű write-jai sorba rakódnak, és nincs
+                        // párhuzamos scan-feldolgozás (a war-factory/warbots átfedés gyökér-megoldása). A könnyű ops
+                        // (create/update/delete) bypass-olják a queue-t. Lásd `FAM_OperationQueue_Service`.
+                        if (Api_Controller.HEAVY_WRITE_OPERATIONS.includes(String(input.operation))) {
+                            return fam_operation_queue_service_1.FAM_OperationQueue_Service.getInstance()
+                                .enqueue(() => mcp_1.FAM_WriteTool_Service.getInstance().handle(input));
+                        }
                         return mcp_1.FAM_WriteTool_Service.getInstance().handle(input);
                     });
                 },
@@ -130,9 +157,235 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             ],
         });
     }
+    /**
+     * `POST /scan/start` (FEAT-008) — szerver-oldali multi-projekt scan-job INDÍTÁSA. Body: explicit `projects` VAGY
+     * `root` (felderítés a SZERVEREN) + opcionális cooldown-override. AZONNAL visszaad `{ jobId, total }` (a hosszú
+     * feldolgozás háttérben fut → nincs Node-requestTimeout). A progress a `GET /scan/status/:jobId`-on.
+     */
+    scanStartEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'scanStart',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/scan/start',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        // Aláírás-feloldás (user-FR 2026-06-25): a `X-FAM-*` header VAGY a body `origin` → KI indította
+                        // a scant (több egyidejű workspace-session beazonosítható). A job-on + a lista-nézetben látszik.
+                        input.origin = fam_request_origin_util_1.FAM_RequestOrigin_Util.fromRequest(req, input.origin);
+                        return fam_scan_job_control_service_1.FAM_ScanJob_ControlService.getInstance().start(input);
+                    });
+                },
+            ],
+        });
+    }
+    /** `GET /scan/status/:jobId` (FEAT-008) — egy scan-job állapota (progress + per-projekt eredmények). 404, ha ismeretlen. */
+    scanStatusEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'scanStatus',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/scan/status/:jobId',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const job = fam_scan_job_control_service_1.FAM_ScanJob_ControlService.getInstance().getStatus(String(req.params.jobId));
+                        if (!job) {
+                            throw new fsm_dynamo_1.DyFM_Error({
+                                errorCode: 'FAM-SCAN-JOB-404',
+                                message: `Ismeretlen scan-job: '${String(req.params.jobId)}' (lehet, hogy a szerver `
+                                    + 'újraindult — a job-ok in-memory tárolódnak).',
+                                issuer: this.issuer,
+                            });
+                        }
+                        return job;
+                    });
+                },
+            ],
+        });
+    }
+    /**
+     * `GET /scan/jobs` (FEAT-008 Phase 5 — „jobb job kezelés") — AZ ÖSSZES (futó + befejezett) scan-job KOMPAKT listája,
+     * legfrissebb elöl. Egy elárvult/futó job a `jobId` ISMERETE NÉLKÜL is felfedezhető (+ a stall-jelzés is látszik).
+     */
+    scanJobsEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'scanJobs',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/scan/jobs',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => ({ jobs: fam_scan_job_control_service_1.FAM_ScanJob_ControlService.getInstance().listJobs() }));
+                },
+            ],
+        });
+    }
+    /**
+     * `POST /scan/cancel/:jobId` (FEAT-008 Phase 5) — egy FUTÓ scan-job megszakítás-kérése (a processor a következő projekt
+     * ELŐTT ellenőrzi). `{ cancelled: true }`, ha a job létezett + futott; `false`, ha ismeretlen/már terminál.
+     */
+    scanCancelEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'scanCancel',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/scan/cancel/:jobId',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => ({
+                        cancelled: fam_scan_job_control_service_1.FAM_ScanJob_ControlService.getInstance().cancel(String(req.params.jobId)),
+                    }));
+                },
+            ],
+        });
+    }
+    /**
+     * `GET /errors` (→ `/api/errors`, user-FR 2026-06-24: „kéne legyenek végpontok, amivel le tudjuk érni az errorokat")
+     * — a `fam_errors` rekordok KOMPAKT, FAM-natív nézete a `/api` felületen (a built-in `/api/server/errors` nyers/bő
+     * Dynamo-objektumai helyett). Query: `code` (errorCode-részlet, case-insensitive), `unhandledOnly` (`true` → csak nem
+     * kezeltek), `limit` (default 50, max 500). Sorrend: occurrence DESC, majd recency. A `contextSnapshot` (benne a
+     * `failedSample` + provider/table/operation) is kijön — így az LM-Studio-omlasztó tartalom-séma diagnosztizálható.
+     */
+    errorsEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'errorsList',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/errors',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const unhandledOnly = req.query.unhandledOnly === 'true';
+                        const codeFilter = req.query.code ? String(req.query.code).toLowerCase() : '';
+                        const limit = Math.min(500, Math.max(1, Number(req.query.limit) || 50));
+                        const all = await errors_control_service_1.FAM_Error_ControlService.getInstance()
+                            .listErrors(unhandledOnly ? { handled: false } : undefined);
+                        const filtered = all
+                            .filter((r) => !codeFilter || (r.errorCode ?? '').toLowerCase().includes(codeFilter))
+                            .sort((a, b) => fam_error_data_model_1.FAM_Error_DataModel.occurrenceCount(b) - fam_error_data_model_1.FAM_Error_DataModel.occurrenceCount(a)
+                            || String(b._id ?? '').localeCompare(String(a._id ?? '')));
+                        return {
+                            total: filtered.length,
+                            returned: Math.min(limit, filtered.length),
+                            errors: filtered.slice(0, limit).map((r) => this.mapErrorCompact(r)),
+                        };
+                    });
+                },
+            ],
+        });
+    }
+    /**
+     * `GET /errors/summary` (→ `/api/errors/summary`) — errorCode szerint CSOPORTOSÍTOTT triage-nézet: kódonként az
+     * occurrence-összeg + distinct rekordszám + utolsó üzenet + egy reprezentatív `failedSample`. Gyors „mi omlik a
+     * legtöbbet" áttekintés (pl. melyik `FAM-EMB-PROVIDER-002` séma viszi el az LM Studio-t).
+     */
+    errorsSummaryEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'errorsSummary',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/errors/summary',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const all = await errors_control_service_1.FAM_Error_ControlService.getInstance().listErrors();
+                        const groups = {};
+                        for (const r of all) {
+                            const code = r.errorCode ?? '(no-code)';
+                            const group = groups[code] ?? { errorCode: code, occurrences: 0, records: 0 };
+                            group.occurrences += fam_error_data_model_1.FAM_Error_DataModel.occurrenceCount(r);
+                            group.records += 1;
+                            group.lastMessage = r.message ?? group.lastMessage;
+                            const sample = r.contextSnapshot?.failedSample;
+                            if (sample && !group.sampleFailedSample) {
+                                group.sampleFailedSample = String(sample).slice(0, 400);
+                            }
+                            groups[code] = group;
+                        }
+                        return {
+                            groups: Object.values(groups).sort((a, b) => b.occurrences - a.occurrences),
+                        };
+                    });
+                },
+            ],
+        });
+    }
+    /** Egy `fam_errors` rekord → KOMPAKT, FAM-natív hiba-nézet (a nyers Dynamo-mezők/óriás-stack helyett a diagnózishoz kell). */
+    mapErrorCompact(record) {
+        return {
+            id: String(record._id ?? ''),
+            errorCode: record.errorCode,
+            level: typeof Reflect.get(record, 'level') === 'string' ? String(Reflect.get(record, 'level')) : undefined,
+            message: record.message,
+            occurrenceCount: fam_error_data_model_1.FAM_Error_DataModel.occurrenceCount(record),
+            handled: record.handled ?? false,
+            issuer: record.issuer,
+            context: record.contextSnapshot,
+        };
+    }
     // =========================================================================
     // /health — CLI remote reachability-check (dsgn-010 §9)
     // =========================================================================
+    /**
+     * `GET /doctor` (#2 diagnosztikai végpont, user-FR 2026-06-24) — SZERVER-OLDALI aggregált health-report
+     * (env/mongodb/config/embedding/vector/collections + scope-integritás), a `fam doctor` REST-tükre (ADR-015
+     * server-centric: a CLI/kliens/UI/külső eszköz EZT hívja, nem 6 külön capability-t). Opcionális `?skip=embedding,vector`.
+     */
+    doctorEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'doctor',
+            type: fsm_dynamo_1.DyFM_HttpCallType.get,
+            endpoint: '/doctor',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const skipRaw = typeof req.query.skip === 'string' ? req.query.skip : '';
+                        const skip = skipRaw.split(',').map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+                        return fam_doctor_control_service_1.FAM_Doctor_ControlService.getInstance().runDoctor({ skip: skip });
+                    });
+                },
+            ],
+        });
+    }
+    /**
+     * `POST /rules/inject` (Rules-Management MP-2) — a SessionStart-hook (+ a `read`-reflex) szerver-oldali rule-assembly-je:
+     * a `cwd`-ből (vagy explicit felülírásból) detektált tier-kontextusra `importance`-rangsorolt, char-budgetbe illesztett
+     * always-apply rule-blokk a „(…and N more)" záró sorral. A hook DUMB marad (csak `additionalContext`-be teszi a `block`-ot).
+     * Body: `{ cwd?, isFdp?, inProject?, projectType?, topics?, budgetChars? }`.
+     */
+    rulesInjectEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'rulesInject',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/rules/inject',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        return retrieval_1.FAM_RuleInjection_ControlService.getInstance().assembleInjection(input);
+                    });
+                },
+            ],
+        });
+    }
+    /**
+     * `POST /rules/propagate` (Rules-Management MP-5) — a kontextusra érvényes szabályok GENERÁLT, marker-keretezett
+     * `CLAUDE.md`-blokkja (propagáció a FAM-NÉLKÜLI projekt-agenteknek). Budget nélkül (minden alkalmazható szabály),
+     * dedup `ruleId`/`derivedFrom` szerint. A hívó (sync-tool/CLI) a `block`-ot a projekt-`CLAUDE.md` markerei közé illeszti.
+     * Body: `{ cwd?, isFdp?, inProject?, projectType?, topics? }`.
+     */
+    rulesPropagateEndpoint() {
+        return new nts_dynamo_1.DyNTS_Endpoint_Params({
+            name: 'rulesPropagate',
+            type: fsm_dynamo_1.DyFM_HttpCallType.post,
+            endpoint: '/rules/propagate',
+            tasks: [
+                async (req, res) => {
+                    await this.run(res, async () => {
+                        const input = (req.body ?? {});
+                        return retrieval_1.FAM_RuleInjection_ControlService.getInstance().assemblePropagation(input);
+                    });
+                },
+            ],
+        });
+    }
     /** `GET /health` — a CLI `--server-url` elérhetőség-próbája (dsgn-010 §9). */
     healthEndpoint() {
         return new nts_dynamo_1.DyNTS_Endpoint_Params({
@@ -141,12 +394,19 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             endpoint: '/health',
             tasks: [
                 async (req, res) => {
-                    // A heap-nyomás IS kimegy a health-en (observability — a CLI/UI/agent látja a memória-állapotot).
-                    const memory = fam_heap_guard_control_service_1.FAM_HeapGuard_ControlService.getInstance().pressure();
+                    // A heap-nyomás IS kimegy a health-en (observability) — a BEDROCK DyNTS_MemoryGuard pressure-éből.
+                    const memory = nts_dynamo_2.DyNTS_MemoryGuard.getInstance().pressure();
+                    // Hidratálás-állapot (user-FR 2026-06-22): a boot-hidratálás időbe telik → a hívó lássa, kész-e.
+                    const hydration = fam_vector_search_control_service_1.FAM_VectorSearch_ControlService.getInstance().hydrationSummary();
+                    // Readiness-coordinator per-tár állapot (pending/hydrating/ready/failed) — a read-queue diagnosztikája.
+                    const readiness = embedding_1.FAM_HydrationCoordinator_ControlService.getInstance().snapshot();
                     res.send({
                         ok: true, service: 'fdp-agent-memory', version: fam_version_const_1.FAM_VERSION, uptime: process.uptime(),
-                        memory: { level: memory.level, usedMb: memory.usedMb, limitMb: memory.limitMb,
-                            ratio: Math.round(memory.ratio * 100) / 100, gcFraction: Math.round(memory.gcFraction * 100) / 100 },
+                        ready: hydration.complete,
+                        memory: { level: memory.level, heapUsedMb: memory.heapUsedMb, heapLimitMb: memory.heapLimitMb,
+                            heapPct: memory.heapPct, rssMb: memory.rssMb, gcFraction: memory.gcFraction },
+                        hydration: hydration,
+                        readiness: readiness,
                     });
                 },
             ],
@@ -193,13 +453,27 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
         if (req.query.ingestRunId) {
             filter.ingestRunId = String(req.query.ingestRunId);
         }
-        const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
-        const all = await dataService.findHydratableList(filter);
         const pageSize = Math.min(this.parseNumber(req.query.pageSize, DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE);
         const page = Math.max(this.parseNumber(req.query.page, 1), 1);
         const start = (page - 1) * pageSize;
-        const items = all.slice(start, start + pageSize);
-        return { table: table, total: all.length, page: page, pageSize: pageSize, items: items };
+        // FIX (OOM): DB-OLDALI lapozás + `contentVector` projekció-kizárás. KORÁBBAN `findHydratableList({})` a TELJES
+        // tárat (126k+ teljes doc + 2560-dim vektor) memóriába töltötte ÉS memóriában szeletelt → a UI-polling többször
+        // GB-okat allokált → OOM + Mongo-flapping. Most: `countDocuments` + `skip/limit` + a nagy vektor-mező kihagyva.
+        const collection = this.entryCollection(registryEntry);
+        const total = await collection.countDocuments(filter);
+        const items = await collection
+            .find(filter, { projection: { contentVector: 0 } })
+            .sort({ __lastModified: -1 })
+            .skip(start)
+            .limit(pageSize)
+            .toArray();
+        return { table: table, total: total, page: page, pageSize: pageSize, items: items };
+    }
+    /** Egy fő RAG-tár mongoose-collection-je (a DS-példányosítás regisztrálja a modellt; onnan a valós collection). */
+    entryCollection(registryEntry) {
+        new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        const model = mongoose_1.default.models[registryEntry.dataParams.dataName];
+        return model.collection;
     }
     // =========================================================================
     // /stats · /stats/:table — high-level stats aggregátum (dsgn-011 §3/§4.4)
@@ -234,7 +508,11 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             ],
         });
     }
-    /** A tár-stats aggregátum (aktív elem-szám + embedding-státusz + utolsó ingest) — dsgn-011 §3/§4.4. */
+    /**
+     * A tár-stats aggregátum (aktív elem-szám + embedding-státusz + utolsó ingest) — dsgn-011 §3/§4.4.
+     * FIX (OOM): `countDocuments` + `$group`-aggregáció + 1-doc last-modified projekció — KORÁBBAN `findHydratableList({})`
+     * a TELJES tárat memóriába töltötte (a UI stats-pollingja → ismételt GB-allokáció → OOM). Most semmit nem hidratál.
+     */
     async collectTableStats(tables) {
         const result = [];
         for (const table of tables) {
@@ -242,24 +520,35 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
             if (!registryEntry) {
                 continue;
             }
-            const dataService = new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
-            const entries = await dataService.findHydratableList({});
+            const collection = this.entryCollection(registryEntry);
+            const count = await collection.countDocuments({});
+            // Embedding-státusz bontás Mongo-aggregációval ($group), NEM a doc-ok memóriába töltésével.
             const byStatus = { pending: 0, completed: 0, error: 0 };
-            let lastModifiedMs = 0;
-            for (const entry of entries) {
-                const status = entry.embeddingStatus ?? 'pending';
-                byStatus[status] = (byStatus[status] ?? 0) + 1;
-                const modified = entry.__lastModified ? new Date(entry.__lastModified).getTime() : 0;
-                if (modified > lastModifiedMs) {
-                    lastModifiedMs = modified;
+            const grouped = await collection
+                .aggregate([{ $group: { _id: '$embeddingStatus', n: { $sum: 1 } } }])
+                .toArray();
+            for (const group of grouped) {
+                const status = group._id ?? 'pending';
+                if (status in byStatus) {
+                    byStatus[status] += group.n;
+                }
+                else {
+                    byStatus.pending += group.n;
                 }
             }
+            // Utolsó módosítás: EGYETLEN doc (a legfrissebb), csak az időbélyeg-mezőre projektálva.
+            const newest = await collection
+                .find({}, { projection: { __lastModified: 1 } })
+                .sort({ __lastModified: -1 })
+                .limit(1)
+                .toArray();
+            const lastModifiedMs = newest[0]?.__lastModified ? new Date(newest[0].__lastModified).getTime() : 0;
             result.push({
                 table: table,
-                count: entries.length,
+                count: count,
                 embeddingStatus: byStatus,
                 lastModified: lastModifiedMs ? new Date(lastModifiedMs).toISOString() : null,
-                status: entries.length ? 'ok' : 'empty',
+                status: count ? 'ok' : 'empty',
             });
         }
         return result;
@@ -313,12 +602,24 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
                 async (req, res) => {
                     await this.run(res, async () => {
                         const table = this.parseTable(req.params.table);
+                        // A vessző-szeparált lista-paraméterek (projects/excludeProjects) tömbbé bontása.
+                        const parseList = (value) => (typeof value === 'string' && value.length
+                            ? value.split(',').map((item) => item.trim()).filter((item) => item.length > 0)
+                            : undefined);
                         return embedding_1.FAM_DuplicateScan_ControlService.getInstance().scan({
                             table: table,
                             threshold: req.query.threshold !== undefined ? Number(req.query.threshold) : undefined,
                             neighbors: req.query.neighbors !== undefined ? this.parseNumber(req.query.neighbors, 10) : undefined,
                             maxEntries: req.query.maxEntries !== undefined ? this.parseNumber(req.query.maxEntries, 3000) : undefined,
                             maxClusters: req.query.maxClusters !== undefined ? this.parseNumber(req.query.maxClusters, 100) : undefined,
+                            pathRegex: typeof req.query.pathRegex === 'string' && req.query.pathRegex.length ? req.query.pathRegex : undefined,
+                            excludePathRegex: typeof req.query.excludePathRegex === 'string' && req.query.excludePathRegex.length
+                                ? req.query.excludePathRegex : undefined,
+                            excludeRootRegex: typeof req.query.excludeRootRegex === 'string' && req.query.excludeRootRegex.length
+                                ? req.query.excludeRootRegex : undefined,
+                            projects: parseList(req.query.projects),
+                            excludeProjects: parseList(req.query.excludeProjects),
+                            minProjects: req.query.minProjects !== undefined ? this.parseNumber(req.query.minProjects, 0) : undefined,
                         });
                     });
                 },
@@ -434,14 +735,14 @@ class Api_Controller extends nts_dynamo_1.DyNTS_Controller {
         if (!Api_Controller.HEAVY_WRITE_OPERATIONS.includes(operation)) {
             return;
         }
-        const guard = fam_heap_guard_control_service_1.FAM_HeapGuard_ControlService.getInstance();
+        const guard = nts_dynamo_2.DyNTS_MemoryGuard.getInstance();
         if (!guard.shouldShedLoad()) {
             return;
         }
         const pressure = guard.pressure();
         throw new fsm_dynamo_1.DyFM_Error({
             errorCode: 'FAM-MEM-SHED-001',
-            message: `Memória-nyomás (${pressure.usedMb}/${pressure.limitMb} MB, ${Math.round(pressure.ratio * 100)}%, `
+            message: `Memória-nyomás (${pressure.heapUsedMb}/${pressure.heapLimitMb} MB, ${pressure.heapPct}%, `
                 + `GC ${Math.round(pressure.gcFraction * 100)}%) — a nehéz '${operation}' művelet ideiglenesen elutasítva `
                 + '(load-shed). Próbáld újra, amikor a nyomás enyhül (lásd /api/logs), vagy szakaszold a scant (cooldown).',
             issuer: this.issuer,

package/build/src/_routes/server/api/fam-doctor.control-service.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Doctor_ControlService = void 0;
+const mcp_1 = require("../../../_modules/mcp");
+const scope_reference_1 = require("../../../_modules/scope-reference");
+/** A 6 doctor al-check ↔ capability-eszköz mátrix (dsgn-010 §5.2; a `fam doctor` CLI-mátrixával egyező). */
+const CHECK_MATRIX = [
+    { name: 'env', capability: 'validate_environment', fixHint: 'Hiányzó env (pl. MONGODB_URI) → `fam init` vagy állítsd be a `.env`-ben.' },
+    { name: 'mongodb', capability: 'test_mongodb_connection', fixHint: 'Mongo nem elérhető → indítsd a Mongo-t, ellenőrizd a portot / MONGODB_URI-t.' },
+    { name: 'config', capability: 'get_config_status', fixHint: 'Nincs fam_config global rekord → `fam init` vagy `fam config set …`.' },
+    { name: 'embedding', capability: 'test_embedding_provider', fixHint: 'OpenAI 401 → ellenőrizd OPENAI_API_KEY-t; LM Studio: indítsd a szervert + tölts be modellt.' },
+    { name: 'vector', capability: 'test_vector_search', fixHint: 'Vektor-pool üres/nem-hidratált → `fam write … re-embed` vagy ellenőrizd a Mongo-persist réteget.' },
+    { name: 'collections', capability: 'get_table_stats', fixHint: 'Hiányzó collection → indítsd a szervert egyszer (auto-create), majd `fam doctor`.' },
+];
+/**
+ * `FAM_Doctor_ControlService` (#2 diagnosztikai végpont, user-FR 2026-06-24) — a `fam doctor` aggregátorának
+ * **SZERVER-OLDALI** változata (server-centric / thin-CLI, ADR-015). A 6 capability-diagnosztikát IN-PROCESS futtatja
+ * (`FAM_CapabilitiesTool_Service.handle`, nem HTTP-round-trip), és aggregált health-report-ot ad (+ best-effort
+ * scope-integritás). A `/api/doctor` ezt szolgálja ki; a CLI/kliens/UI/külső eszköz ezt hívhatja (nem 6 külön
+ * capability-hívást). Az `interpret` PURE (a capability szemantikus hiba-jelzéseit — `available/reachable/ok:false`,
+ * `missing[]` — fail-ként ismeri fel, nem csak a throw-t; a CLI csak a throw-t fogta).
+ */
+class FAM_Doctor_ControlService {
+    static _instance;
+    static getInstance() {
+        if (!FAM_Doctor_ControlService._instance) {
+            FAM_Doctor_ControlService._instance = new FAM_Doctor_ControlService();
+        }
+        return FAM_Doctor_ControlService._instance;
+    }
+    /**
+     * A capability-eredmény SZEMANTIKUS hiba-jelzése (PURE, tesztelhető): a technikailag sikeres hívás is jelezhet
+     * hibát (`available:false` = embedding down; `reachable:false` = Mongo down; `ok:false`; `missing[]` = hiányzó env).
+     * A wrapper-réteget (`data`/`result`) is megnézi. `true` = egészségtelen (→ FAIL).
+     */
+    static interpretUnhealthy(result) {
+        const root = (result && typeof result === 'object') ? result : {};
+        const inner = root.data ?? root.result ?? root;
+        const flat = (inner && typeof inner === 'object') ? inner : root;
+        return flat.available === false
+            || flat.reachable === false
+            || flat.ok === false
+            || (Array.isArray(flat.missing) && flat.missing.length > 0);
+    }
+    /** A teljes (vagy `skip`-elt) check-szett lefuttatása + aggregált health-report. */
+    async runDoctor(set) {
+        const skip = set?.skip ?? [];
+        const checks = [];
+        for (const descriptor of CHECK_MATRIX) {
+            if (skip.includes(descriptor.name)) {
+                continue;
+            }
+            checks.push(await this.runCheck(descriptor));
+        }
+        const summary = { ok: 0, warn: 0, fail: 0 };
+        for (const check of checks) {
+            summary[check.status] += 1;
+        }
+        const health = summary.fail ? 'fail' : summary.warn ? 'warn' : 'ok';
+        return {
+            health: health,
+            checks: checks,
+            summary: summary,
+            scopeIntegrity: await this.scopeIntegrity(),
+            database: await this.databaseInfo(),
+        };
+    }
+    /**
+     * Best-effort DB-diagnosztika (user-FR 2026-06-24): a 6 fő tár elem-számai + embedding-státusza (get_table_stats)
+     * + a helper-collection-ök mérete + az összes aktív doc (get_storage_usage). A hiba NEM buktatja a report-ot.
+     */
+    async databaseInfo() {
+        try {
+            const statsRaw = await mcp_1.FAM_CapabilitiesTool_Service.getInstance().handle({ action: 'invoke', name: 'get_table_stats' });
+            const storageRaw = await mcp_1.FAM_CapabilitiesTool_Service.getInstance().handle({ action: 'invoke', name: 'get_storage_usage' });
+            const statsList = FAM_Doctor_ControlService.unwrapArray(statsRaw);
+            const storage = FAM_Doctor_ControlService.unwrapRecord(storageRaw);
+            const tables = (Array.isArray(statsList) ? statsList : []).map((raw) => {
+                const item = (raw && typeof raw === 'object') ? raw : {};
+                const es = (item.embeddingStatus && typeof item.embeddingStatus === 'object')
+                    ? item.embeddingStatus : {};
+                return {
+                    table: String(item.table ?? ''),
+                    count: Number(item.count) || 0,
+                    completed: Number(es.completed) || 0,
+                    pending: Number(es.pending) || 0,
+                    error: Number(es.error) || 0,
+                };
+            });
+            const mainCollections = /^fam_(rules|documents|codebases|knowledges|coding_patterns|memories)$/;
+            const collectionsRaw = storage.collections;
+            const helperCollections = (Array.isArray(collectionsRaw) ? collectionsRaw : [])
+                .map((raw) => {
+                const item = (raw && typeof raw === 'object') ? raw : {};
+                return { collection: String(item.collection ?? ''), activeDocs: Number(item.activeDocs) || 0 };
+            })
+                .filter((entry) => entry.collection && !mainCollections.test(entry.collection));
+            return {
+                tables: tables,
+                totalActiveDocs: typeof storage.totalActiveDocs === 'number' ? storage.totalActiveDocs : undefined,
+                helperCollections: helperCollections,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** A capability-eredmény tömb-payloadja (a `this.ok` wrapper-réteget is megnézve). */
+    static unwrapArray(result) {
+        if (Array.isArray(result)) {
+            return result;
+        }
+        const root = (result && typeof result === 'object') ? result : {};
+        const inner = root.data ?? root.result ?? root;
+        return Array.isArray(inner) ? inner : [];
+    }
+    /** A capability-eredmény objektum-payloadja (a `this.ok` wrapper-réteget is megnézve). */
+    static unwrapRecord(result) {
+        const root = (result && typeof result === 'object') ? result : {};
+        const inner = root.data ?? root.result ?? root;
+        return (inner && typeof inner === 'object') ? inner : root;
+    }
+    /** Egy capability-check IN-PROCESS futtatása → `FAM_DoctorCheck` (throw → FAIL/WARN; szemantikus hiba → FAIL). */
+    async runCheck(descriptor) {
+        try {
+            const result = await mcp_1.FAM_CapabilitiesTool_Service.getInstance()
+                .handle({ action: 'invoke', name: descriptor.capability });
+            if (FAM_Doctor_ControlService.interpretUnhealthy(result)) {
+                return { name: descriptor.name, status: 'fail', detail: JSON.stringify(result).slice(0, 240), fixHint: descriptor.fixHint };
+            }
+            return { name: descriptor.name, status: 'ok' };
+        }
+        catch (error) {
+            const message = error?.message ?? 'ismeretlen hiba';
+            // A late-bind eszközök clear "pending MP-X" hibája → WARN (nem FAIL, nem néma).
+            const isPending = message.toLowerCase().includes('pending');
+            return { name: descriptor.name, status: isPending ? 'warn' : 'fail', detail: message, fixHint: descriptor.fixHint };
+        }
+    }
+    /** Best-effort scope-integritás-összegzés (a detect_scope_issues hibája NEM buktatja a doctor-report-ot). */
+    async scopeIntegrity() {
+        try {
+            const issues = await scope_reference_1.FAM_ScopeMaintenance_ControlService.getInstance().detectIssues();
+            return {
+                hasIssues: issues.hasIssues,
+                orphanScopes: issues.orphanProjectScopes.length,
+                duplicateScopes: issues.duplicateScopes.length,
+                repoKeyDuplicates: issues.repoKeyDuplicates.length,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.FAM_Doctor_ControlService = FAM_Doctor_ControlService;

package/build/src/_routes/server/config/config.control-service.js

@@ -163,7 +163,7 @@ class FAM_Config_ControlService {
         const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: options.issuer ?? this.issuer });
         // Régi aktív rekord (ha van) → soft-delete (archív; history-megőrzés, dsgn-007 §7.2).
         const existing = await dataService.findActive(filter);
-        if (existing && existing._id) {
+        if (existing?._id) {
             await dataService.deleteData(existing._id);
         }
         // Új aktív rekord — a `value` Mixed; a saveData $set-tel ír (Mongoose Mixed silent-drop ellen).
@@ -435,7 +435,7 @@ class FAM_Config_ControlService {
     async seedGlobalIfMissing(key, value) {
         const dataService = new config_data_service_1.FAM_Config_DataService({ issuer: this.issuer });
         const existing = await dataService.findActive({ level: fam_config_level_type_enum_1.FAM_ConfigLevel.global, key: key });
-        if (existing && existing._id) {
+        if (existing?._id) {
             return;
         }
         await this.set(key, value, { level: fam_config_level_type_enum_1.FAM_ConfigLevel.global, setBy: 'env-seed', issuer: this.issuer });