@futdevpro/fdp-agent-memory 1.1.30 → 1.1.113

package/build/src/_modules/embedding/_services/fam-hydration-coordinator.control-service.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_HydrationCoordinator_ControlService = void 0;
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+/**
+ * `FAM_HydrationCoordinator_ControlService` (Singleton SSOT, user-FR 2026-06-22) — a vektor-pool **hidratálás-
+ * készenlét** EGYETLEN koordinátora: a `read`/`search` kérések **MEGVÁRJÁK** egy tár (kezdő VAGY újra-) hidratálását
+ * ahelyett, hogy `FAM-VEC-SEARCH-001 pool ÜRES`-t kapnának, amíg a hidratálás folyamatban van.
+ *
+ * **Probléma (amit megold):** a `/api/health` ELŐBB zöldül, mint ahogy a tárankénti pool-hidratálás (codebase 152k a
+ * legnagyobb) befejeződik → közvetlenül boot/auto-start után a `read` `pool ÜRES`-t dobott. A koordinátor **sorba
+ * állítja** (queue) a kéréseket: minden várakozó UGYANARRA a per-tár promise-ra vár (nincs polling, nincs thundering-
+ * herd) — a hidratálás végén MIND egyszerre továbbenged.
+ *
+ * **Process-koordináció (SSOT):** a `hydrateAll` boot-kor `beginBoot`-tal ELŐRE `hydrating`-re jelöl MINDEN
+ * regisztrált tárat (így a korán beérkező read is vár, akkor is, ha az ő tárának `hydrateTable`-je még nem futott).
+ * Minden `hydrateTable` (boot ÉS standalone re-hidratálás egyaránt) `markHydrating`→`markReady`/`markFailed`-et jelez —
+ * ezért a **re-hidratálás is fedett**: ha egy `ready` tár újra-hidratál (a pool törlődik + újratölt), a `markHydrating`
+ * friss deferred-et nyit → a közben érkező read VÁR, nem lát fél-üres pool-t.
+ *
+ * **Determinizmus:** a `markReady`/`markFailed` idempotens (ugyanazt a deferred-et nem oldja kétszer); az `awaitReady`
+ * a `ready`/`failed` állapotnál azonnal tér vissza/dob, csak a `hydrating` ágon vár (időkorláttal — a time-out tiszta
+ * „még hidratál, próbáld újra" hiba, NEM végtelen blokk).
+ */
+class FAM_HydrationCoordinator_ControlService {
+    static _instance;
+    issuer = 'FAM_HydrationCoordinator_ControlService';
+    /** Per-tár állapot + deferred (a SSOT). */
+    entries = new Map();
+    /** A hidratálás-bevárás default felső korlátja ms-ban (env/config felülírható; lásd `configureWaitMs`). */
+    waitTimeoutMs = Number(process.env.FAM_HYDRATION_WAIT_MS) || 180000;
+    static getInstance() {
+        if (!FAM_HydrationCoordinator_ControlService._instance) {
+            FAM_HydrationCoordinator_ControlService._instance = new FAM_HydrationCoordinator_ControlService();
+        }
+        return FAM_HydrationCoordinator_ControlService._instance;
+    }
+    /** A hidratálás-bevárás default time-outjának beállítása (a bootstrap a `read.hydrationWaitMs` config-ból hívja). */
+    configureWaitMs(waitTimeoutMs) {
+        if (Number.isFinite(waitTimeoutMs) && waitTimeoutMs >= 0) {
+            this.waitTimeoutMs = Math.floor(waitTimeoutMs);
+        }
+    }
+    /** Az aktuális default time-out (diag / teszt). */
+    getWaitTimeoutMs() {
+        return this.waitTimeoutMs;
+    }
+    /**
+     * Boot-jelzés (`hydrateAll` hívja a tár-iteráció ELŐTT): MINDEN megadott tárat `hydrating`-re jelöl (friss
+     * deferred), hogy a korán beérkező read VÁRJON, akkor is, ha az ő tárának `hydrateTable`-je a soros boot-ban
+     * még nem futott le. Idempotens: a már `hydrating` tárat nem nyitja újra.
+     */
+    beginBoot(tables) {
+        for (const table of tables) {
+            this.markHydrating(table);
+        }
+    }
+    /**
+     * Egy tár hidratálásának KEZDETE (a `hydrateTable` hívja a pool-törlés ELŐTT — boot ÉS re-hidratálás). Ha a tár még
+     * nem `hydrating`, friss deferred-et nyit (a `ready`→`hydrating` átmenet a re-hidratálás kulcsa: az addigi várók a
+     * RÉGI, már-feloldott promise-on már átmentek, az újak az ÚJ deferred-re várnak). Ha már `hydrating`, no-op (a
+     * `beginBoot`+`hydrateTable` dupla-hívás nem nyit két deferred-et).
+     */
+    markHydrating(table) {
+        const existing = this.entries.get(table);
+        if (existing && existing.state === 'hydrating') {
+            return;
+        }
+        let resolve = () => undefined;
+        const promise = new Promise((resolver) => {
+            resolve = resolver;
+        });
+        this.entries.set(table, { state: 'hydrating', promise: promise, resolve: resolve });
+    }
+    /** Egy tár hidratálása SIKERES (a `hydrateTable` hívja a végén): `ready` + a várók továbbengedése. */
+    markReady(table) {
+        this.settle(table, 'ready', true);
+    }
+    /** Egy tár hidratálása MEGBUKOTT (a `hydrateTable` catch-ágában): `failed` + a várók elengedése (hiba felé). */
+    markFailed(table) {
+        this.settle(table, 'failed', false);
+    }
+    /**
+     * Egy tár készenlétének BEVÁRÁSA a `search`/`read` ELŐTT (a queue-mag). `ready` → azonnal vissza; `failed` →
+     * tiszta hidratálás-bukás hiba; `hydrating` → a per-tár promise bevárása time-outtal (a time-out NEM végtelen
+     * blokk, hanem „még hidratál, próbáld újra"); `pending`/ismeretlen → azonnal vissza (a `search` poolSize-checkje
+     * dönt — genuinely üres tár vs. nem-konfigurált). Az időkorlát a `timeoutMs` VAGY a config-default.
+     */
+    async awaitReady(table, timeoutMs) {
+        const entry = this.entries.get(table);
+        if (!entry || entry.state === 'pending') {
+            return;
+        }
+        if (entry.state === 'ready') {
+            return;
+        }
+        if (entry.state === 'failed') {
+            throw this.hydrationError(table, 'A tár hidratálása MEGBUKOTT (a pool nem elérhető). '
+                + 'Nézd a szerver-logot (`FAM hydrate` sorok) + az embedding-konfigurációt; majd `re_embed_table`/restart.');
+        }
+        // state === 'hydrating': a per-tár promise bevárása time-outtal.
+        const limitMs = timeoutMs ?? this.waitTimeoutMs;
+        const ready = await this.raceWithTimeout(entry.promise, limitMs);
+        if (!ready) {
+            throw this.hydrationError(table, `A tár hidratálása ${Math.round(limitMs / 1000)}s alatt nem fejeződött be `
+                + '(a pool-hidratálás folyamatban — boot-kor a nagy tárak percekig tarthatnak). Próbáld újra pár '
+                + 'másodperc múlva; a következő hívás már a kész poolt találja.');
+        }
+    }
+    /** Egy tár aktuális állapota (diag / health / teszt). */
+    getState(table) {
+        return this.entries.get(table)?.state ?? 'pending';
+    }
+    /** Pillanatkép minden ismert tár állapotáról (a `/health` + diag bővítéséhez). */
+    snapshot() {
+        return Array.from(this.entries.entries()).map(([table, entry]) => ({ table: String(table), state: entry.state }));
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /** Az állapot véglegesítése (`ready`/`failed`) + a deferred egyszeri feloldása (idempotens). */
+    settle(table, state, ready) {
+        const entry = this.entries.get(table);
+        if (!entry) {
+            // Nem volt `markHydrating` (pl. közvetlen markReady) — rögzítjük a végállapotot egy már-feloldott deferred-del.
+            this.entries.set(table, { state: state, promise: Promise.resolve(ready), resolve: () => undefined });
+            return;
+        }
+        if (entry.state === state) {
+            return;
+        }
+        entry.state = state;
+        entry.resolve(ready);
+    }
+    /** A promise bevárása felső időkorláttal: a time-out `false`-t ad (NEM dob) — a hívó dönt a hibáról. */
+    raceWithTimeout(promise, timeoutMs) {
+        if (timeoutMs <= 0) {
+            return Promise.resolve(false);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), timeoutMs);
+            void promise.then((ready) => {
+                clearTimeout(timer);
+                resolve(ready);
+            });
+        });
+    }
+    /** A hidratálás-bevárás strukturált hibája (`FAM-VEC-HYDRATE-002`). */
+    hydrationError(table, detail) {
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.vecHydrateWait,
+            message: `A(z) '${table}' tár nem áll készen a kereséshez. ${detail}`,
+            issuer: this.issuer,
+            context: { operation: 'await-hydration', table: table },
+        });
+    }
+}
+exports.FAM_HydrationCoordinator_ControlService = FAM_HydrationCoordinator_ControlService;

package/build/src/_modules/embedding/_services/fam-lmstudio-embedding.provider.js

@@ -14,18 +14,26 @@ exports.FAM_LMStudio_EmbeddingProvider = void 0;
 class FAM_LMStudio_EmbeddingProvider {
     baseUrl;
     apiKey;
+    timeoutMs;
     providerId = 'lmstudio';
+    /** A request-timeout default (ms), ha a hívó nem ad explicitet — 2 perc (a nagy batch-eknek elég, de BOUNDED). */
+    static DEFAULT_TIMEOUT_MS = 120000;
     /**
      * @param baseUrl OpenAI-kompatibilis lokális endpoint (pl. `http://localhost:1234/v1`).
      * @param apiKey opcionális Bearer token (LM Studio default-ban nem kér).
+     * @param timeoutMs request-timeout (ms) — egy NEM-VÁLASZOLÓ LM Studio (a modell crash-elt a kérés közben:
+     *   „bekap egy feladatot, aztán nem csinál semmit") ne fagyassza be a teljes scant. `0`/negatív → nincs timeout
+     *   (a régi viselkedés). A timeout AbortError-rá fordul → a `FAM_Embedding_ControlService` retry-zza, majd
+     *   `FAM-EMB-PROVIDER-002`-ként tárolja (user-FR 2026-06-24).
      */
-    constructor(baseUrl, apiKey) {
+    constructor(baseUrl, apiKey, timeoutMs = FAM_LMStudio_EmbeddingProvider.DEFAULT_TIMEOUT_MS) {
         this.baseUrl = baseUrl;
         this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
     }
     /**
      * Batch-embedding az OpenAI-kompatibilis `/embeddings` végpontra. A `texts` sorrendje == a
-     * visszaadott `number[][]` sorrendje. HTTP-/parse-hiba deskriptív üzenettel dobódik (a
+     * visszaadott `number[][]` sorrendje. HTTP-/parse-/timeout-hiba deskriptív üzenettel dobódik (a
      * `FAM_Embedding_ControlService` `FAM-EMB-PROVIDER-002`-vé alakítja — dsgn-008).
      */
     async embedTexts(set) {
@@ -34,11 +42,11 @@ class FAM_LMStudio_EmbeddingProvider {
         if (this.apiKey && this.apiKey.trim().length) {
             headers.Authorization = `Bearer ${this.apiKey.trim()}`;
         }
-        const response = await fetch(url, {
+        const response = await this.fetchWithTimeout(url, {
             method: 'POST',
             headers: headers,
             body: JSON.stringify({ model: set.model, input: set.texts }),
-        });
+        }, set.model);
         const rawText = await response.text();
         if (!response.ok) {
             throw new Error(`LM Studio (OpenAI-compatible) embeddings HTTP ${response.status} | url=${url} | `
@@ -68,6 +76,35 @@ class FAM_LMStudio_EmbeddingProvider {
             return false;
         }
     }
+    /**
+     * `fetch` request-timeout-tal (AbortController) — a KULCS-robusztosság (user-FR 2026-06-24): ha az LM Studio
+     * elfogadja a kérést, de SOHA nem válaszol (a modell crash-elt menet közben), a natív `fetch` a végtelenségig
+     * függne → a scan-job örökre beragad. A timeout abortálja a kérést → deskriptív hiba, amit a hívó retry-zhat +
+     * `FAM-EMB-PROVIDER-002`-ként tárolhat. `timeoutMs<=0` → nincs timeout (régi viselkedés). A timer minden ágon
+     * törlődik (a `finally`-ben), hogy ne tartsa életben az event-loop-ot.
+     */
+    async fetchWithTimeout(url, init, model) {
+        if (this.timeoutMs <= 0) {
+            return fetch(url, init);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (error) {
+            // Az AbortController-abort → deskriptív timeout-hiba (a generikus `fetch failed`/`AbortError` helyett),
+            // hogy a tárolt rekord egyértelmű legyen: az LM Studio elfogadta, de nem válaszolt időben.
+            if (controller.signal.aborted) {
+                throw new Error(`LM Studio embeddings: NINCS válasz ${this.timeoutMs}ms alatt (timeout) — a modell valószínűleg `
+                    + `crash-elt/lefagyott a kérés közben | url=${url} | model=${model}`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     /** Trailing `/`-ek levágása (kettős slash elkerülése a `/embeddings` join-nál). */
     trimTrailingSlashes(value) {
         return value.replace(/\/+$/, '');

package/build/src/_modules/embedding/_services/fam-vector-search.control-service.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_VectorSearch_ControlService = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const local_vector_search_1 = require("@futdevpro/nts-dynamo/local-vector-search");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
 const error_codes_const_1 = require("../../../_collections/error-codes.const");
 const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
 const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_hydration_coordinator_control_service_1 = require("./fam-hydration-coordinator.control-service");
 const fam_embedding_control_service_1 = require("./fam-embedding.control-service");
 const fam_entry_data_service_1 = require("./fam-entry.data-service");
 /**
@@ -48,9 +50,16 @@ class FAM_VectorSearch_ControlService {
      * de a többi tár hidratálása FOLYTATÓDIK (egy tár bukása nem dönti le az egészet).
      */
     async hydrateAll() {
+        const startedAt = Date.now();
+        let totalVectors = 0;
+        // Readiness-koordinátor (user-FR 2026-06-22): MINDEN tárat ELŐRE `hydrating`-re jelölünk a soros boot-iteráció
+        // ELŐTT, így a korán beérkező read VÁR (a per-tár promise-on), nem kap `pool ÜRES`-t, akkor sem, ha az ő
+        // tárának `hydrateTable`-je a sorban még nem futott le.
+        fam_hydration_coordinator_control_service_1.FAM_HydrationCoordinator_ControlService.getInstance()
+            .beginBoot(fam_store_registry_const_1.FAM_STORE_REGISTRY.map((entry) => entry.table));
         for (const entry of fam_store_registry_const_1.FAM_STORE_REGISTRY) {
             try {
-                await this.hydrateTable(entry.table);
+                totalVectors += await this.hydrateTable(entry.table);
             }
             catch (error) {
                 // No-silent-failure: a hidratálás-hiba persistált (a global handler kapja), de a többi
@@ -58,6 +67,11 @@ class FAM_VectorSearch_ControlService {
                 fsm_dynamo_1.DyFM_Log.warn(`[FAM hydrate] '${entry.table}' tár hidratálása sikertelen: ${error?.message}`);
             }
         }
+        // Összesítő (user-FR 2026-06-22): a boot-memória-lábnyom egy ránézésre — összes vektor + idő + heap/RSS.
+        const mem = process.memoryUsage();
+        fsm_dynamo_1.DyFM_Log.log(`[FAM hydrate] ÖSSZESEN ${totalVectors} vektor ${fam_store_registry_const_1.FAM_STORE_REGISTRY.length} táron, `
+            + `${Math.round((Date.now() - startedAt) / 1000)}s alatt — heap ${Math.round(mem.heapUsed / 1048576)} MB / `
+            + `RSS ${Math.round(mem.rss / 1048576)} MB.`);
     }
     /**
      * Egy tár pool-jának hidratálása (dsgn-006 §4.1). A `completed`-státuszú, nem-üres-vektorú entry-ket
@@ -67,13 +81,24 @@ class FAM_VectorSearch_ControlService {
     async hydrateTable(table) {
         const registryEntry = fam_store_registry_const_1.FAM_StoreRegistry_Util.getEntry(table);
         if (!registryEntry) {
-            return;
+            return 0;
         }
+        // Readiness-koordinátor: a hidratálás KEZDETE (a pool-törlés ELŐTT) — boot ÉS re-hidratálás egyaránt. A
+        // `ready`→`hydrating` átmenet a re-hidratálás kulcsa: a `pool.clearPool()` alatt a beérkező read VÁR (friss
+        // deferred), nem lát fél-üres pool-t.
+        const coordinator = fam_hydration_coordinator_control_service_1.FAM_HydrationCoordinator_ControlService.getInstance();
+        coordinator.markHydrating(table);
         const pool = this.getOrCreatePool(table);
         pool.clearPool();
         this.poolDims.set(table, null);
         const dataService = new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
         const filter = { embeddingStatus: 'completed' };
+        // dsgn-013 §5.2 (MAM F3) — az ALVÓ (`dormant`) memóriák NEM hidratálódnak a hot LVS-poolba (RAM-/boot-spórolás);
+        // cold (Mongo) kereséssel elérhetők + megtaláláskor reaktiválódnak. A flag CSAK a memory táron létezik; ha a
+        // dormancy ki van kapcsolva, nincs `dormant:true` entry → a szűrő no-op (zéró hatás a többi tárra + a mai bootra).
+        if (table === fam_table_type_enum_1.FAM_Table.memory) {
+            filter.dormant = { $ne: true };
+        }
         let loaded = 0;
         try {
             // PERF: lean + {_id, contentVector}-projekció + STREAMING (cursor) — a hidratálás CSAK ezt a két
@@ -87,6 +112,8 @@ class FAM_VectorSearch_ControlService {
             });
         }
         catch (error) {
+            // Readiness-koordinátor: a hidratálás MEGBUKOTT → a várók tiszta hibát kapnak (nem végtelen blokk).
+            coordinator.markFailed(table);
             throw fam_error_factory_util_1.FAM_Error_Util.create({
                 errorCode: error_codes_const_1.FAM_ERROR_CODES.vecHydrate,
                 message: `A(z) '${table}' tár vektor-hidratálása sikertelen a Mongo-olvasásnál.`,
@@ -96,7 +123,16 @@ class FAM_VectorSearch_ControlService {
             });
         }
         this.hydrated.set(table, true);
-        fsm_dynamo_1.DyFM_Log.log(`[FAM hydrate] '${table}' tár: ${loaded} vektor betöltve az in-memory pool-ba.`);
+        // Readiness-koordinátor: a tár KÉSZ → a várakozó read-ek továbbengedése (mind egyszerre, a per-tár promise-on).
+        coordinator.markReady(table);
+        // Memória-info táranként (user-FR 2026-06-22): dim + becsült pool-méret (loaded × dim × 8 byte / number[])
+        // + a process heap/RSS — boot-kor azonnal látszik a per-tár memória-lábnyom.
+        const mem = process.memoryUsage();
+        const dim = this.poolDims.get(table) ?? 0;
+        const poolMb = Math.round((loaded * dim * 8) / 1048576);
+        fsm_dynamo_1.DyFM_Log.log(`[FAM hydrate] '${table}' tár: ${loaded} vektor (dim ${dim}, ~${poolMb} MB pool) — `
+            + `heap ${Math.round(mem.heapUsed / 1048576)} MB / RSS ${Math.round(mem.rss / 1048576)} MB.`);
+        return loaded;
     }
     // =========================================================================
     // PERSIST-ON-WRITE upsert (dsgn-006 §3) — a write/scan path hívja mentés után
@@ -130,6 +166,9 @@ class FAM_VectorSearch_ControlService {
      * koszinusz (BFR-AM-007). Üres pool / hiányzó embedding → `FAM-VEC-SEARCH-001` (bootstrap-skip jelzés).
      */
     async search(input) {
+        // Readiness-gate (user-FR 2026-06-22): ha a tár pool-ja épp (kezdő VAGY újra-) hidratál, MEGVÁRJUK a végét a
+        // queue-mag promise-án (NEM `pool ÜRES`-t dobunk). Time-out / hidratálás-bukás → tiszta `FAM-VEC-HYDRATE-002`.
+        await fam_hydration_coordinator_control_service_1.FAM_HydrationCoordinator_ControlService.getInstance().awaitReady(input.table);
         const queryVector = await this.resolveQueryVector(input);
         if (!queryVector.length) {
             throw fam_error_factory_util_1.FAM_Error_Util.create({
@@ -143,15 +182,16 @@ class FAM_VectorSearch_ControlService {
         const pool = this.getOrCreatePool(input.table);
         const poolSize = pool.size();
         if (!poolSize) {
-            // Bootstrap-skip jelzés (dsgn-006 §4.1): üres pool (embedding nincs konfigurálva / nincs
-            // completed entry). NEM néma — a capability + UI piros banner ezt jelzi (dsgn-008/dsgn-011).
-            throw fam_error_factory_util_1.FAM_Error_Util.create({
-                errorCode: error_codes_const_1.FAM_ERROR_CODES.vecSearch,
-                message: `A(z) '${input.table}' tár vektor-pool-ja ÜRES (bootstrap-skip): nincs hidratált, `
-                    + `completed-embeddingű vektor. Ellenőrizd az embedding-konfigurációt (test_embedding_provider).`,
-                issuer: this.issuer,
-                context: { operation: 'search', table: input.table },
-            });
+            // Ide a readiness-gate UTÁN jutunk: a tár hidratálása BEFEJEZŐDÖTT, mégis üres a pool → a tár GENUINELY
+            // üres (friss telepítés / még nincs embeddelt tartalom). Ez LEGITIM állapot, a keresés eredménye
+            // triviálisan 0 találat — dsgn-002/dsgn-003: „0-találat → üres hits, NEM hiba". (Korábban itt
+            // FAM-VEC-SEARCH-001 dobódott → a `read` HTTP 500-at adott MINDEN üres tárra — friss DB-ben a
+            // multi-query/edge read-ek és a UI-search borultak; 2026-07-24 e2e-gyökérok-fix.) A hidratálás-BUKÁS
+            // esete ettől FÜGGETLENÜL fedett: azt az awaitReady dobja (FAM-VEC-HYDRATE-002). NEM néma: warn-log +
+            // a doctor/`test_vector_search` capability továbbra is explicit `empty-pool` státuszt jelez.
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM vectorSearch] '${input.table}' tár: üres pool a hidratálás után (0 completed vektor) `
+                + `→ 0 találat (üres tár = legitim állapot, nem hiba).`);
+            return [];
         }
         // Prefilter→vektor (dsgn-006 §4.3): ha van candidate-szűkítés, a koszinusz CSAK a szűkített
         // halmazon fut (a teljes pool helyett egy ideiglenes szűkített pool-on) — kisebb számítás.
@@ -178,6 +218,21 @@ class FAM_VectorSearch_ControlService {
     isHydrated(table) {
         return this.hydrated.get(table) ?? false;
     }
+    /**
+     * Hidratálás-összegző (user-FR 2026-06-22): a `/health`-en kiadva, hogy a hívó lássa, kész-e a boot-hidratálás
+     * (indításkor időbe telik mind a tárat betölteni). `complete` csak ha MINDEN regisztrált tár pool-ja hidratált.
+     */
+    hydrationSummary() {
+        const pending = fam_store_registry_const_1.FAM_STORE_REGISTRY
+            .filter((entry) => !this.isHydrated(entry.table))
+            .map((entry) => String(entry.table));
+        return {
+            complete: pending.length === 0,
+            hydratedTables: fam_store_registry_const_1.FAM_STORE_REGISTRY.length - pending.length,
+            totalTables: fam_store_registry_const_1.FAM_STORE_REGISTRY.length,
+            pendingTables: pending,
+        };
+    }
     // =========================================================================
     // helpers
     // =========================================================================

package/build/src/_modules/embedding/index.js

@@ -8,7 +8,7 @@
  * (BFR-AM-002/008); a bedrock-csere (MP-15) a `FAM_EmbeddingProvider` interfész mögött non-breaking.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_EmbeddingBootstrap_ControlService = exports.FAM_DuplicateScan_ControlService = exports.FAM_EmbeddingCost_ControlService = exports.FAM_EmbeddingPipeline_ControlService = exports.FAM_EmbeddingPreset_ControlService = exports.FAM_StoreRegistry_Util = exports.FAM_STORE_REGISTRY = exports.FAM_Entry_DataService = exports.FAM_VectorSearch_ControlService = exports.FAM_MOCK_EMBEDDING_DIMS = exports.FAM_Mock_EmbeddingProvider = exports.FAM_LMStudio_EmbeddingProvider = exports.FAM_OpenAI_EmbeddingProvider = exports.FAM_Embedding_ControlService = void 0;
+exports.FAM_EmbeddingBootstrap_ControlService = exports.FAM_DuplicateScan_ControlService = exports.FAM_EmbeddingCost_ControlService = exports.FAM_EmbeddingPipeline_ControlService = exports.FAM_EmbeddingPreset_ControlService = exports.FAM_StoreRegistry_Util = exports.FAM_STORE_REGISTRY = exports.FAM_DedupWarn_ControlService = exports.FAM_Entry_DataService = exports.FAM_HydrationCoordinator_ControlService = exports.FAM_VectorSearch_ControlService = exports.FAM_MOCK_EMBEDDING_DIMS = exports.FAM_Mock_EmbeddingProvider = exports.FAM_LMStudio_EmbeddingProvider = exports.FAM_OpenAI_EmbeddingProvider = exports.FAM_Embedding_ControlService = void 0;
 // SP-2.1 — provider-dispatch kapu + providerek
 var fam_embedding_control_service_1 = require("./_services/fam-embedding.control-service");
 Object.defineProperty(exports, "FAM_Embedding_ControlService", { enumerable: true, get: function () { return fam_embedding_control_service_1.FAM_Embedding_ControlService; } });
@@ -22,8 +22,12 @@ Object.defineProperty(exports, "FAM_MOCK_EMBEDDING_DIMS", { enumerable: true, ge
 // SP-2.2 — Memory Vector Search (Mongo-persist + LVS hidratálás)
 var fam_vector_search_control_service_1 = require("./_services/fam-vector-search.control-service");
 Object.defineProperty(exports, "FAM_VectorSearch_ControlService", { enumerable: true, get: function () { return fam_vector_search_control_service_1.FAM_VectorSearch_ControlService; } });
+var fam_hydration_coordinator_control_service_1 = require("./_services/fam-hydration-coordinator.control-service");
+Object.defineProperty(exports, "FAM_HydrationCoordinator_ControlService", { enumerable: true, get: function () { return fam_hydration_coordinator_control_service_1.FAM_HydrationCoordinator_ControlService; } });
 var fam_entry_data_service_1 = require("./_services/fam-entry.data-service");
 Object.defineProperty(exports, "FAM_Entry_DataService", { enumerable: true, get: function () { return fam_entry_data_service_1.FAM_Entry_DataService; } });
+var fam_dedup_warn_control_service_1 = require("./_services/fam-dedup-warn.control-service");
+Object.defineProperty(exports, "FAM_DedupWarn_ControlService", { enumerable: true, get: function () { return fam_dedup_warn_control_service_1.FAM_DedupWarn_ControlService; } });
 var fam_store_registry_const_1 = require("./_collections/fam-store-registry.const");
 Object.defineProperty(exports, "FAM_STORE_REGISTRY", { enumerable: true, get: function () { return fam_store_registry_const_1.FAM_STORE_REGISTRY; } });
 Object.defineProperty(exports, "FAM_StoreRegistry_Util", { enumerable: true, get: function () { return fam_store_registry_const_1.FAM_StoreRegistry_Util; } });

package/build/src/_modules/ingest/_collections/fam-file-routing.util.js

@@ -58,6 +58,12 @@ class FAM_FileRouting_Util {
         if (FAM_FileRouting_Util.isGeneratedNoise(fileName)) {
             return 'skip';
         }
+        // R3 (FAM-REV 2026-06-22, eval-lelet): a `.cursor/rules/*` (és `.cursor/.../rules/*`) KONVENCIÓ-fájlok a
+        // `rules` tárba — ezek SZABÁLYOK (naming/import/struktúra/tilalmak), nem általános dokumentumok. Korábban
+        // `.mdc`→`documents`-be estek → a `rules`-only query az agent-feedback felé húzott (tool-comparison lelet).
+        if (FAM_FileRouting_Util.isCursorRule(relativePath)) {
+            return fam_table_type_enum_1.FAM_Table.rules;
+        }
         if (FAM_FileRouting_Util.DOCUMENT_EXTENSIONS.includes(extension)) {
             return fam_table_type_enum_1.FAM_Table.documents;
         }
@@ -68,6 +74,10 @@ class FAM_FileRouting_Util {
         // codebase. A bináris-tartalmú álcázott fájlt a scanner null-byte tartalom-ellenőrzése szűri.
         return fam_table_type_enum_1.FAM_Table.codebase;
     }
+    /** `.cursor/rules/` alatti konvenció-fájl-e (R3 — a `rules` tárba routing). Normalizált `/`, case-insensitive. */
+    static isCursorRule(relativePath) {
+        return relativePath.replace(/\\/g, '/').toLowerCase().includes('.cursor/rules/');
+    }
     /**
      * Generált / zaj fájl-e (FAM-REV-064): a lock-fájlok (pnpm-lock.yaml / package-lock.json / yarn.lock /
      * `*.lock`), a minifikált bundle-k (`.min.js`/`.min.css`) — ezek hatalmasak + generáltak, NEM info-

package/build/src/_modules/ingest/_collections/fam-frontmatter.util.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Frontmatter_Util = void 0;
+/**
+ * `FAM_Frontmatter_Util` (MP-3 / F-A) — **pure** fájl-fej `---`-frontmatter parser. Ha a tartalom egy `---` sorral
+ * KEZDŐDIK és van záró `---` (a `MAX_HEADER_LINES`-on belül), a köztes `key: value` sorokat ismert irányítókká
+ * olvassa, a törzset a záró fence UTÁNról adja vissza. Egyébként NO-OP (`hasFrontmatter:false`, `body===content`) —
+ * így a kód-/dok-fájlok (amik nem `---`-rel kezdődnek) viselkedése BYTE-AZONOS marad (zero behavior change).
+ *
+ * Szándékosan MINIMÁL (nem teljes YAML): skalár `string`/`number`/`boolean` + lista (`[a, b]` flow VAGY vesszős).
+ * A `#` komment-sor + üres sor kihagyva. Ismeretlen kulcs → ignorált. Defenzív: záró fence nélkül → nincs frontmatter.
+ */
+class FAM_Frontmatter_Util {
+    /** A záró fence-t eddig a sorig keressük (egy `---`-rel kezdődő, de nem-frontmatter fájl ne nyelje el a törzset). */
+    static MAX_HEADER_LINES = 200;
+    /** Az ISMERT irányító-kulcsok (a többi ignorált). */
+    static KNOWN_KEYS = new Set([
+        'table', 'splitMode', 'importance', 'userApproved', 'ruleScope', 'ruleScopeTopic',
+        'ruleId', 'derivedFrom', 'globalRule', 'category', 'tags',
+    ]);
+    /** A fájl-fej frontmatter parse-je (pure). */
+    static parse(content) {
+        const empty = { directives: {}, body: content, hasFrontmatter: false };
+        if (!content) {
+            return empty;
+        }
+        const lines = content.split(/\r?\n/);
+        // A nyitó fence: az ELSŐ sor pontosan `---` (BOM-toleráns).
+        const first = lines[0].replace(/^/, '').trim();
+        if (first !== '---') {
+            return empty;
+        }
+        const closeIdx = FAM_Frontmatter_Util.findCloseFence(lines);
+        if (closeIdx < 0) {
+            return empty; // nincs záró fence → nem frontmatter (defenzív; pl. `---` thematic-break a tetején)
+        }
+        const directives = {};
+        for (let i = 1; i < closeIdx; i++) {
+            FAM_Frontmatter_Util.applyLine(lines[i], directives);
+        }
+        // CSAK akkor DIREKTÍVA-blokk (+ vágjuk a törzset), ha ≥1 ISMERT ingest-irányítót tartalmaz. Egy TISZTA
+        // metaadat-blokk (pl. a `memory`-fájlok `name`/`description`/`metadata` feje) NEM FAM-direktíva → a content
+        // ÉRINTETLEN marad (különben a re-scan elvágná a summary-t az embeddelt tartalomból → rontaná a retrievalt).
+        if (!Object.keys(directives).length) {
+            return empty;
+        }
+        // A törzs a záró fence UTÁNi soroktól (a vezető üres sorok levágva).
+        const body = lines.slice(closeIdx + 1).join('\n').replace(/^\n+/, '');
+        return { directives: directives, body: body, hasFrontmatter: true };
+    }
+    /** A záró `---` fence sor-indexe (1..MAX_HEADER_LINES), vagy -1. */
+    static findCloseFence(lines) {
+        const limit = Math.min(lines.length, FAM_Frontmatter_Util.MAX_HEADER_LINES);
+        for (let i = 1; i < limit; i++) {
+            if (lines[i].trim() === '---') {
+                return i;
+            }
+        }
+        return -1;
+    }
+    /** Egy `key: value` sor feldolgozása (ismert kulcs → típusos érték a `directives`-be). */
+    static applyLine(line, directives) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            return;
+        }
+        const sep = trimmed.indexOf(':');
+        if (sep < 0) {
+            return;
+        }
+        const key = trimmed.slice(0, sep).trim();
+        if (!FAM_Frontmatter_Util.KNOWN_KEYS.has(key)) {
+            return;
+        }
+        const rawValue = FAM_Frontmatter_Util.stripQuotes(trimmed.slice(sep + 1).trim());
+        switch (key) {
+            case 'table':
+            case 'ruleScope':
+            case 'ruleScopeTopic':
+            case 'ruleId':
+            case 'derivedFrom':
+            case 'category':
+                if (rawValue) {
+                    directives[key] = rawValue;
+                }
+                return;
+            case 'importance': {
+                const num = Number(rawValue);
+                if (Number.isFinite(num)) {
+                    directives.importance = num;
+                }
+                return;
+            }
+            case 'userApproved':
+                directives.userApproved = FAM_Frontmatter_Util.toBool(rawValue);
+                return;
+            case 'globalRule':
+                directives.globalRule = FAM_Frontmatter_Util.toBool(rawValue);
+                return;
+            case 'splitMode':
+                directives.splitMode = FAM_Frontmatter_Util.toSplitMode(rawValue);
+                return;
+            case 'tags':
+                directives.tags = FAM_Frontmatter_Util.toList(rawValue);
+                return;
+        }
+    }
+    /** Idéző-jelek levágása (`"x"` / `'x'` → `x`). */
+    static stripQuotes(value) {
+        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\'')))) {
+            return value.slice(1, -1);
+        }
+        return value;
+    }
+    /** `'true'`/`'yes'`/`'1'` → `true`; minden más → `false`. */
+    static toBool(value) {
+        const lower = value.toLowerCase();
+        return lower === 'true' || lower === 'yes' || lower === '1';
+    }
+    /** `'heading'`/`'list-item'` → az adott mód; `true`/`'true'`/`'yes'` → `'heading'`; egyébként `false`. */
+    static toSplitMode(value) {
+        const lower = value.toLowerCase();
+        if (lower === 'heading' || lower === 'list-item') {
+            return lower;
+        }
+        return FAM_Frontmatter_Util.toBool(value) ? 'heading' : false;
+    }
+    /** `[a, b]` flow VAGY `a, b` vesszős → string-lista (üresek kiszűrve). */
+    static toList(value) {
+        const inner = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value;
+        return inner.split(',').map((entry) => FAM_Frontmatter_Util.stripQuotes(entry.trim())).filter((entry) => entry.length > 0);
+    }
+}
+exports.FAM_Frontmatter_Util = FAM_Frontmatter_Util;

package/build/src/_modules/ingest/_collections/fam-project-identity.util.js

@@ -95,6 +95,36 @@ class FAM_ProjectIdentity_Util {
     static hasIdentity(identity) {
         return Boolean(identity.packageName || identity.isGit);
     }
+    /**
+     * `canonicalRepoKey(identity, projectDirName?)` (scope-prevenció, user-FR 2026-06-22; **path-aware fix
+     * 2026-06-24**) — a STABIL projekt-identitás-kulcs, amit a SCAN a project-scope-ra stamp-el
+     * (`FAM_Scope.canonicalRepoKey`), és amire a duplikátum-detekció épül.
+     *
+     * **KRITIKUS path-aware fix:** a régi forma CSAK a git `org/repo`-t használta → MONOREPO sub-projektek ÉS
+     * forkok (egy git-repóban élő, jogosan KÜLÖNBÖZŐ projektek) UGYANAZT a kulcsot kapták → a duplikátum-detekció
+     * tévesen jelezte őket egynek → egy téves `merge_scopes` ÖSSZEKEVERTE a tartalmukat (pl. `ccap-revisioned`
+     * 42k fájlja a `ccap-speech-recognition` scope-ba). A javítás: a kulcs `${repo}::${diszkriminátor}`, ahol a
+     * diszkriminátor a projekt-azonosító A REPÓN BELÜL (package-név bare alak VAGY a projekt-mappa neve). Így két
+     * külön projekt EGY repóban is külön kulcsot kap, miközben UGYANANNAK a projektnek az import-/scan-változata
+     * (azonos package-név) továbbra is egy kulcsra esik (a dedup eredeti célja megmarad).
+     *
+     * Prioritás: (1) git `org/repo` van → `${repo}::${pkgBare || dir}` (path-aware), különben csak `repo`;
+     * (2) nincs git → a package-név bare alakja VAGY a mappanév. Minden LOWERCASE + trim. Nincs semmi → `undefined`.
+     * PURE — IO nélkül tesztelhető.
+     */
+    static canonicalRepoKey(identity, projectDirName) {
+        const repo = identity.gitRepo?.trim().toLowerCase();
+        const pkgBare = identity.packageName
+            ? identity.packageName.replace(/^@[^/]+\//, '').trim().toLowerCase()
+            : undefined;
+        const dir = projectDirName?.trim().toLowerCase() || undefined;
+        const discriminator = pkgBare || dir;
+        if (repo) {
+            // path-aware: a repón belüli projekt-azonosító (ha van) → a monorepo/fork sub-projektek külön kulcsot kapnak.
+            return discriminator ? `${repo}::${discriminator}` : repo;
+        }
+        return discriminator || undefined;
+    }
     /** A kereshető `knowledge` „project-identity" entry szövege (PURE). */
     static buildContent(identity, scopeLabel, root) {
         const lines = [];

package/build/src/_modules/ingest/_collections/fam-scan-progress.util.js

@@ -40,7 +40,7 @@ class FAM_ScanProgress_Util {
     /**
      * Egy futás-közbeni progress-sor: `processed/total` fájl + %, chunk-szám, verdikt-bontás, eltelt idő + ETA.
      * Az ETA a MÉRT sebességből (`processed / elapsed`) → a hátralévő fájlok ideje (csak ha van haladás + maradék).
-     * `[famIngest]` prefix → az activity-monitor allowlistjén keresztül megjelenik a konzol-ablakban.
+     * `[famIngest]` prefix → a szerver látható konzol-ablakában (és a `FAM_LOG_FILE`-ban) megjelenik.
      */
     static progressLine(set) {
         const pct = set.total ? Math.round((set.processed / set.total) * 100) : 100;
@@ -49,7 +49,10 @@ class FAM_ScanProgress_Util {
         const eta = rate > 0 && remaining > 0
             ? `, ETA ~${FAM_ScanProgress_Util.formatDuration(remaining / rate)}`
             : '';
-        return `[famIngest] feldolgozás ${set.processed}/${set.total} fájl (${pct}%), ${set.chunkCount} chunk, `
+        // A projekt-/scope-név a sor elejére (user-FR 2026-06-22) — multi-projekt scan-nél a sor magában
+        // is megmondja, MELYIK projektnél tart (nem csak a külön project-identity/summary sor).
+        const scope = set.scopeLabel ? `[${set.scopeLabel}] ` : '';
+        return `[famIngest] ${scope}feldolgozás ${set.processed}/${set.total} fájl (${pct}%), ${set.chunkCount} chunk, `
             + `${set.verdicts.new} új / ${set.verdicts.modified} mód / ${set.verdicts.equal} vált., `
             + `eltelt ${FAM_ScanProgress_Util.formatDuration(set.elapsedSeconds)}${eta}`;
     }