@futdevpro/fdp-agent-memory 0.1.0 → 1.1.14

package/build/src/_modules/retrieval/_services/fam-retrieval.control-service.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_Retrieval_ControlService = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_reference_code_util_1 = require("../../../_collections/fam-reference-code.util");
 const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
 const embedding_1 = require("../../embedding");
 const scope_reference_1 = require("../../scope-reference");
@@ -78,12 +80,110 @@ class FAM_Retrieval_ControlService {
             const tableHits = await this.searchTable({ table, query, queryVector, scopeExpand, config, includeContent });
             allHits.push(...tableHits);
         }
-        // ⑤ weight-szorzó MÁR a searchTable-ben (finalScore). ⑥ minScore-küszöb → relevantSet.
-        const relevantSet = allHits.filter((hit) => hit.finalScore >= config.minScore);
+        // ④b FEAT-003 — determinisztikus kód-expanzió: ha a query azonosító-kódot tartalmaz, az ÖSSZES
+        // citáló elem maximális score-ral (exact citation) a vektor-zaj fölé kerül. Always-on, strictly
+        // additive (kód-mentes query-n no-op); a merge id szerint dedup-ol (vektor+kód ugyanazon elemen → felülemel).
+        const detectedCodes = fam_reference_code_util_1.FAM_ReferenceCode_Util.extract(query.query);
+        const mergedHits = await this.applyCodeExpansion({ query, detectedCodes, scopeExpand, vectorHits: allHits, includeContent });
+        // FEAT-006 context-injection deduper: a hívó által MÁR injektált `_id`-k kizárása (a minScore/topK ELŐTT,
+        // hogy ne foglaljanak helyet) — egy session ne kapja vissza ugyanazt a kontextust kétszer. A kizárás a
+        // kód-exact-re IS vonatkozik (ha a session már birtokolja, nem kell újra, F3-1 ellenére sem).
+        const visibleHits = this.excludeSeen(mergedHits, query.excludeIds);
+        // ⑤ weight-szorzó MÁR a hit-eken (finalScore). ⑥ minScore-küszöb → relevantSet — DE F3-2: a kód-exact
+        // citáció (`matchedCodes` nem-üres) BYPASS-olja a minScore-t (a determinisztikusan citált kód eleme
+        // releváns a score-tól függetlenül; a `weight≤0` továbbra is kizárt, mert az már a merge ELŐTT kiesik).
+        const relevantSet = visibleHits.filter((hit) => this.codeExactRank(hit) > 0 || hit.finalScore >= config.minScore);
         // ⑦ rendezés (finalScore desc → recency → _id asc).
         this.sortHits(relevantSet, config.scoreOrder);
         // ⑧ topK-vágás + dense-detektálás + suggestions.
-        return this.buildResult({ query, relevantSet, config, scopeExpand });
+        return this.buildResult({ query, relevantSet, config, scopeExpand, detectedCodes });
+    }
+    // =========================================================================
+    // ④b KÓD-EXPANZIÓ (FEAT-003) — determinisztikus link-retrieval a vektor MELLÉ
+    // =========================================================================
+    /**
+     * A determinisztikus kód-expanzió (FEAT-003). A `detectedCodes` (a query-ből `FAM_ReferenceCode_Util`-lal
+     * felismert kódok) MINDEN cél-tárban `find({ referenceCodes: $in })`-nel behúzza az ÖSSZES citáló elemet
+     * (az AZONOS scope/tag/kind/active prefilterrel), `embeddingStatus`-tól FÜGGETLENÜL. A vektor-találatokkal
+     * id szerint merge-el (dedup): ha egy elem vektor-hit IS, a kód-citáció felülemeli a score-ját (exact >
+     * hasonlóság) + jelöli `matchedCodes`-szal. Kód-mentes query → a vektor-találatok változatlanul.
+     */
+    async applyCodeExpansion(set) {
+        if (!set.detectedCodes.length) {
+            return set.vectorHits;
+        }
+        // id→hit index a dedup-merge-hez (a vektor-találatok elsőként kerülnek be).
+        const byId = new Map();
+        for (const hit of set.vectorHits) {
+            byId.set(hit.id, hit);
+        }
+        for (const table of set.query.tables) {
+            const codeEntries = await new fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService().loadByReferenceCodes({
+                table: table,
+                scopeIdSet: set.scopeExpand.scopeIdSet,
+                tagFilter: set.query.tagFilter,
+                kindFilter: set.query.kindFilter,
+            }, set.detectedCodes);
+            for (const entry of codeEntries) {
+                this.mergeCodeHit({ byId, entry, table, detectedCodes: set.detectedCodes, includeContent: set.includeContent });
+            }
+        }
+        return Array.from(byId.values());
+    }
+    /**
+     * Egy kód-citáló entry beolvasztása a hit-halmazba (FEAT-003). `score=1.0` (exact citation = maximális
+     * relevancia), `finalScore=1.0×weight` (a meglévő weight-modellbe illesztve). `weight≤0` → kizárt
+     * (konzisztens a vektor-ággal). Ha az elem MÁR vektor-hit → a meglévő hit-et frissítjük (`matchedCodes`
+     * + a magasabb score felülír), egyébként új code-hit-et szúrunk.
+     */
+    mergeCodeHit(set) {
+        const id = set.entry._id;
+        if (!id) {
+            return;
+        }
+        const weight = set.entry.weight ?? 1;
+        if (weight <= 0) {
+            return;
+        }
+        const matched = (set.entry.referenceCodes ?? []).filter((code) => set.detectedCodes.includes(code));
+        if (!matched.length) {
+            return;
+        }
+        const codeFinalScore = 1.0 * weight;
+        const existing = set.byId.get(id);
+        if (existing) {
+            existing.matchedCodes = matched;
+            if (codeFinalScore > existing.finalScore) {
+                existing.score = 1.0;
+                existing.finalScore = codeFinalScore;
+            }
+            return;
+        }
+        set.byId.set(id, this.toCodeHit({ entry: set.entry, id, table: set.table, weight, matched, includeContent: set.includeContent }));
+    }
+    /** Egy kód-citáló entry → `FAM_RetrievalHit` (exact citation: `score=1.0`, `matchedCodes` kitöltve). */
+    toCodeHit(set) {
+        const lastModified = set.entry.__lastModified;
+        return {
+            id: set.id,
+            table: set.table,
+            score: 1.0,
+            weight: set.weight,
+            finalScore: 1.0 * set.weight,
+            content: set.includeContent ? set.entry.content : undefined,
+            kind: set.entry.kind,
+            tags: set.entry.tags ?? [],
+            ...this.ruleMeta(set.entry, set.table),
+            scopePath: (set.entry.scopePath ?? []),
+            source: set.entry.source,
+            sourceFilePath: set.entry.sourceFilePath ?? null,
+            absolutePath: set.entry.source?.absolutePath ?? null,
+            chunkType: set.entry.chunkType,
+            headingPath: set.entry.headingPath ?? [],
+            position: set.entry.position,
+            matchedCodes: set.matched,
+            lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
+        };
     }
     // =========================================================================
     // ②–④ PER-TÁR: prefilter → vektor-keresés → hit-row (SP-5.1/SP-5.2)
@@ -96,33 +196,65 @@ class FAM_Retrieval_ControlService {
      * dense-detektálás a topK ELŐTTI halmazon számol; dsgn-005 §4.1 / SP-5.2 feladat).
      */
     async searchTable(set) {
-        // ①–② Mongo-prefilter → jelölt-entry-k (a soft-delete + rules.isActive guard beépített).
-        const candidates = await new fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService().loadCandidates({
-            table: set.table,
-            scopeIdSet: set.scopeExpand.scopeIdSet,
-            tagFilter: set.query.tagFilter,
-            kindFilter: set.query.kindFilter,
-        });
-        if (!candidates.length) {
-            return [];
-        }
-        // A candidate-entry-k id→entry indexe (a hit-row + weight + recency összefűzéséhez).
+        // ①–② A jelölt-betöltés + ④ vektor-keresés — két út AZONOS EREDMÉNNYEL (a `byId` index a hit-row +
+        // weight + recency összefűzéséhez):
+        //  • UNSCOPED (nincs scope/tag/kind szűrő, nem `rules`): a prefilter a TELJES tárat adná, ezért fölösleges
+        //    mind a ~23k jelöltet betölteni — a candidateId-k = a teljes pool. Helyette közvetlenül a (hidratált)
+        //    main-poolon keresünk (top-`MAX_PAGE_SIZE`), és CSAK a hit-ek metaadatát töltjük (`loadByIds`) → a
+        //    Mongo-munka ~242×-ére csökken (mért: 727ms → 3ms). A pool = az összes aktív, completed jelölt, a
+        //    weight a hit-en alkalmazva → BIT-AZONOS rangsor a régi (teljes-prefilter) úttal (`min(23k,500)=500`).
+        //  • SCOPED (scope/tag/kind/`rules`): a Mongo-prefilter szűkít → candidateId-halmaz → szűkített keresés.
+        const isUnscoped = !set.scopeExpand.scopeIdSet
+            && !(set.query.tagFilter && set.query.tagFilter.length)
+            && !set.query.kindFilter
+            && set.table !== fam_table_type_enum_1.FAM_Table.rules;
         const byId = new Map();
-        const candidateIds = [];
-        for (const entry of candidates) {
-            if (entry._id) {
-                byId.set(entry._id, entry);
-                candidateIds.push(entry._id);
+        let vectorHits;
+        if (isUnscoped) {
+            // ④ vektor-keresés a TELJES poolon (a vektor-réteg `limit`-je = `MAX_PAGE_SIZE` relevantSet a
+            // dense-detektáláshoz — NEM a végső topK).
+            vectorHits = await embedding_1.FAM_VectorSearch_ControlService.getInstance().search({
+                table: set.table,
+                queryVector: set.queryVector,
+                topK: MAX_PAGE_SIZE,
+            });
+            if (!vectorHits.length) {
+                return [];
+            }
+            const hitEntries = await new fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService()
+                .loadByIds(set.table, vectorHits.map((hit) => hit.id));
+            for (const entry of hitEntries) {
+                if (entry._id) {
+                    byId.set(entry._id, entry);
+                }
             }
         }
-        // ④ vektor-keresés a szűkített poolon (koszinusz; a vektor-réteg `limit`-je = a teljes
-        // jelölt-halmaz, hogy a teljes relevantSet meglegyen a dense-detektáláshoz — NEM a végső topK).
-        const vectorHits = await embedding_1.FAM_VectorSearch_ControlService.getInstance().search({
-            table: set.table,
-            queryVector: set.queryVector,
-            candidateIds: candidateIds,
-            topK: Math.min(candidateIds.length, MAX_PAGE_SIZE),
-        });
+        else {
+            // ①–② Mongo-prefilter → jelölt-entry-k (a soft-delete + rules.isActive guard beépített).
+            const candidates = await new fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService().loadCandidates({
+                table: set.table,
+                scopeIdSet: set.scopeExpand.scopeIdSet,
+                tagFilter: set.query.tagFilter,
+                kindFilter: set.query.kindFilter,
+            });
+            if (!candidates.length) {
+                return [];
+            }
+            const candidateIds = [];
+            for (const entry of candidates) {
+                if (entry._id) {
+                    byId.set(entry._id, entry);
+                    candidateIds.push(entry._id);
+                }
+            }
+            // ④ vektor-keresés a szűkített poolon (a relevantSet a dense-detektáláshoz, NEM a végső topK).
+            vectorHits = await embedding_1.FAM_VectorSearch_ControlService.getInstance().search({
+                table: set.table,
+                queryVector: set.queryVector,
+                candidateIds: candidateIds,
+                topK: Math.min(candidateIds.length, MAX_PAGE_SIZE),
+            });
+        }
         // ⑤ weight-szorzó: finalScore = score × (weight ?? 1); weight ≤ 0 → kizárt (nem kerül a hits közé).
         const hits = [];
         for (const vectorHit of vectorHits) {
@@ -134,28 +266,66 @@ class FAM_Retrieval_ControlService {
             if (weight <= 0) {
                 continue;
             }
-            hits.push(this.toHit({ entry, vectorHit, table: set.table, weight, includeContent: set.includeContent }));
+            hits.push(this.toHit({
+                entry, vectorHit, table: set.table, weight,
+                importChunkWeight: set.config.importChunkWeight, includeContent: set.includeContent,
+            }));
         }
         return hits;
     }
+    /**
+     * Az import-only chunkok (`chunkType:"imports"`) read-idejű rangsor-szorzója (FAM-REV-060). Egy import-sor
+     * (`import { X } from "./y"`) magas cosine-t kap egy szimbólum-név query-re, de alacsony az ÉRTÉKe (csak
+     * import, nem definíció) → `importChunkWeight` (<1) a definíció-chunkok ALÁ rangsorolja. Minden más chunkType
+     * (class/function/interface/generic/…) érintetlen (×1). READ-time, a nyers `score` (relevancia) változatlan.
+     */
+    chunkTypeFactor(chunkType, importChunkWeight) {
+        return chunkType === 'imports' ? importChunkWeight : 1;
+    }
     /** Egy candidate-entry + a vektor-hit → `FAM_RetrievalHit` (finalScore + denormalizált mezők). */
     toHit(set) {
         const lastModified = set.entry.__lastModified;
+        // ⑤ weight-szorzó + FAM-REV-060 import-chunk read-faktor: finalScore = score × weight × chunkTypeFactor.
+        const chunkFactor = this.chunkTypeFactor(set.entry.chunkType, set.importChunkWeight);
         return {
             id: set.vectorHit.id,
             table: set.table,
             score: set.vectorHit.score,
             weight: set.weight,
-            finalScore: set.vectorHit.score * set.weight,
+            finalScore: set.vectorHit.score * set.weight * chunkFactor,
             content: set.includeContent ? set.entry.content : undefined,
             kind: set.entry.kind,
             tags: set.entry.tags ?? [],
+            ...this.ruleMeta(set.entry, set.table),
             scopePath: (set.entry.scopePath ?? []),
             source: set.entry.source,
             sourceFilePath: set.entry.sourceFilePath ?? null,
+            absolutePath: set.entry.source?.absolutePath ?? null,
+            // Location-infó (FAM-REV-049): chunk-típus + symbol-lánc + sor/char-pozíció — hogy keresésből
+            // rögtön „melyik fájl / melyik symbol / hányadik sor" legyen, ne csak a fájlnév.
+            chunkType: set.entry.chunkType,
+            headingPath: set.entry.headingPath ?? [],
+            position: set.entry.position,
             lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
         };
     }
+    /**
+     * A `rules` tár per-tár metaadatai a hit-en (`category`/`isActive`/`applicableScopes`) — FEAT-005/006 P1:
+     * a zóna-alapú aktív-rule kezelés alapja, hogy a hívó/hook a keresési hit-ből is lássa, MI aktív + mely
+     * zónában. MÁS táraknál üres objektum (e mezők a `FAM_Entry` bázison nincsenek; a `rules`-doc-on igen —
+     * a loose `Partial<FAM_Rules_DataModel>` view a meglévő `as`-konvenció szerint, mint a `source`/`scopePath`).
+     */
+    ruleMeta(entry, table) {
+        if (table !== fam_table_type_enum_1.FAM_Table.rules) {
+            return {};
+        }
+        const rule = entry;
+        return {
+            category: rule.category,
+            isActive: rule.isActive,
+            applicableScopes: (rule.applicableScopes ?? []),
+        };
+    }
     // =========================================================================
     // ⑦ RENDEZÉS (SP-5.2, dsgn-005 §5)
     // =========================================================================
@@ -167,6 +337,14 @@ class FAM_Retrieval_ControlService {
      */
     sortHits(hits, scoreOrder) {
         hits.sort((a, b) => {
+            // F3-1 (garantált kód-exact inclusion): a determinisztikus kód-citáció (`matchedCodes` nem-üres) a
+            // legkülső rendezési kulcs — a fuzzy vektor-hasonlóság ELÉ rangsorol (decisiveness). Az
+            // `effectiveTopK = max(topK, #codeExact)`-kal együtt ez GARANTÁLJA, hogy a citált kód MINDEN eleme
+            // visszakerül (a topK sosem vágja le). Kód-mentes query-n nincs code-exact hit → változatlan rangsor.
+            const codePriority = this.codeExactRank(b) - this.codeExactRank(a);
+            if (codePriority !== 0) {
+                return codePriority;
+            }
             const primary = this.primaryComparator(a, b, scoreOrder);
             if (primary !== 0) {
                 return primary;
@@ -190,36 +368,58 @@ class FAM_Retrieval_ControlService {
         // 'weighted' (default).
         return b.finalScore - a.finalScore;
     }
+    /**
+     * F3-1: egy hit **kód-exact**-e (van legalább egy `matchedCodes` determinisztikus citáció)? Rendezési kulcs
+     * (1 = kód-exact → előre, 0 = pusztán vektor-hit) és a garantált-inclusion `effectiveTopK` számlálója.
+     */
+    codeExactRank(hit) {
+        return hit.matchedCodes && hit.matchedCodes.length ? 1 : 0;
+    }
+    /**
+     * FEAT-006 context-injection deduper: a hívó által MÁR injektált (`excludeIds`) bejegyzések kizárása a
+     * találatokból. Üres/hiányzó lista → változatlan halmaz (nincs fölös allokáció). Állapotmentes: a
+     * „már látott" halmazt a hívó (session/hook) tartja.
+     */
+    excludeSeen(hits, excludeIds) {
+        if (!excludeIds || !excludeIds.length) {
+            return hits;
+        }
+        const seen = new Set(excludeIds);
+        return hits.filter((hit) => !seen.has(hit.id));
+    }
     // =========================================================================
     // ⑧ topK-vágás + DENSE-DETEKTÁLÁS + signaling (SP-5.3, dsgn-005 §4)
     // =========================================================================
     /**
-     * A rendezett relevantSet → `FAM_RetrievalResult` (dsgn-005 §4). `totalRelevant = relevantSet.length`;
-     * `returnedHits` = az első topK; `truncated = totalRelevant > topK`. Dense dual-gate (§4.2):
-     * `(totalRelevant >= ratio × topK) || (totalRelevant >= absMin)`, DE csak `truncated:true` mellett
-     * (a kötés: vágás nélkül nincs elrejtett releváns tömeg). A suggestions a relevantSet valós
-     * statisztikáiból (§4.4). Az `uncertaintyNotes` a scope-prefilter jegyzetei (dsgn-002 §4).
+     * A rendezett relevantSet → `FAM_RetrievalResult` (dsgn-005 §4) — **confidence-padlóval** (FAM-REV-054,
+     * 2026-06-20 dogfood). A relevancia-JELZÉSEK (`totalRelevant`/`denseResults`/`truncated`/`suggestions`)
+     * a MAGABIZTOSAN releváns halmazból (`score >= relevanceFloor`, nyers cosine-on, hogy a weight ne torzítson)
+     * számolnak — NEM a `minScore=0` melletti teljes poolból (ami minden cosine>0 elemet „relevánsnak" vett,
+     * így minden query-n hamis „dense + N=pool" + „emeld a topK-t a pool-ra" jött). A `returnedHits` viszont
+     * best-effort marad (recall): a hívó megkapja a topK legjobbat, DE ha egyik sem magabiztos, a jelek
+     * ŐSZINTÉN mutatják (north-star: „ha valami hiányzik, MEGMONDJA" — `confidentSet` üres → low-confidence note).
+     * Dense dual-gate (§4.2): `(N >= ratio×topK) || (N >= absMin)`, csak `truncated:true` mellett. Az
+     * `uncertaintyNotes` a scope-prefilter jegyzetei (dsgn-002 §4). **Spec-drift:** dsgn-005 §4.1 jelenleg
+     * `totalRelevant = relevantSet.length`-et ír; ez a confidence-floor-os finomítás (a katalógus + REVIEW-FINDINGS jelöli).
      */
     buildResult(set) {
-        const totalRelevant = set.relevantSet.length;
-        const effectiveTopK = set.config.topK;
+        // F3-1 (garantált kód-exact inclusion): az effektív topK a kért `topK` ÉS a kód-exact citációk
+        // száma közül a nagyobb — így a determinisztikusan citált kód MINDEN eleme visszakerül, akkor is, ha
+        // többen vannak, mint a kért `topK` (a `sortHits` ezeket a halmaz elejére rendezte). Kód-mentes
+        // query-n `#codeExact = 0` → `effectiveTopK = topK` (változatlan viselkedés).
+        const codeExactCount = set.relevantSet.filter((hit) => this.codeExactRank(hit)).length;
+        const effectiveTopK = Math.max(set.config.topK, codeExactCount);
         const returnedHits = set.relevantSet.slice(0, effectiveTopK);
+        // Magabiztosan releváns halmaz: a nyers cosine `score` (NEM finalScore — a weight ranking-boost, nem
+        // relevancia) a `relevanceFloor` felett. A relevantSet rendezett, ezért a confidentSet is.
+        const confidentSet = set.relevantSet.filter((hit) => hit.score >= set.config.relevanceFloor);
+        const totalRelevant = confidentSet.length;
         const truncated = totalRelevant > effectiveTopK;
-        // Dual-gate dense (§4.2) — csak `truncated:true` mellett lehet `true`.
+        // Dual-gate dense (§4.2) — a CONFIDENT halmazon, csak `truncated:true` mellett.
         const densenessRatio = totalRelevant / effectiveTopK;
         const denseByRatio = densenessRatio >= set.config.denseResultRatio;
         const denseByAbs = totalRelevant >= set.config.denseResultAbsMin;
         const denseResults = truncated && (denseByRatio || denseByAbs);
-        // Suggestions (§4.4) — a relevantSet valós statisztikáiból + a query paramétereiből.
-        const suggestions = (denseResults || truncated)
-            ? fam_retrieval_suggestions_util_1.FAM_RetrievalSuggestions_Util.generate({
-                relevantSet: set.relevantSet,
-                query: set.query,
-                effectiveTopK: effectiveTopK,
-                truncated: truncated,
-                maxPageSize: MAX_PAGE_SIZE,
-            })
-            : [];
         return {
             query: set.query.query,
             tables: set.query.tables,
@@ -227,10 +427,45 @@ class FAM_Retrieval_ControlService {
             denseResults: denseResults,
             totalRelevant: totalRelevant,
             truncated: truncated,
-            suggestions: suggestions,
+            suggestions: this.buildSuggestions({
+                relevantSet: set.relevantSet,
+                confidentSet: confidentSet,
+                query: set.query,
+                effectiveTopK: effectiveTopK,
+                truncated: truncated,
+                relevanceFloor: set.config.relevanceFloor,
+            }),
             uncertaintyNotes: set.scopeExpand.uncertaintyNotes,
+            detectedCodes: set.detectedCodes,
         };
     }
+    /**
+     * A suggestions-lista (FAM-REV-054). HA nincs magabiztos találat, de adtunk vissza best-effort hit-et →
+     * ŐSZINTE low-confidence jelzés (north-star: „megmondja, ha valószínűleg nincs lefedve") a nyers top-score-ral.
+     * Egyébként a szűkítési javaslatok a CONFIDENT halmaz statisztikáiból (nem a teljes zaj-poolból), és csak
+     * ha `truncated` (van a topK-n túli magabiztos elem). Kód-citáció (`score=1.0`) mindig magabiztos.
+     */
+    buildSuggestions(set) {
+        if (!set.confidentSet.length) {
+            if (!set.relevantSet.length) {
+                return [];
+            }
+            const topScore = set.relevantSet[0].score;
+            return [`⚠️ nincs magabiztosan releváns találat (a legjobb score ${topScore.toFixed(2)} < `
+                    + `relevanceFloor ${set.relevanceFloor.toFixed(2)}) — lehet, hogy ez nincs lefedve; `
+                    + `fogalmazd át a query-t, vagy tágítsd/váltsd a scope-ot/tárat`];
+        }
+        if (!set.truncated) {
+            return [];
+        }
+        return fam_retrieval_suggestions_util_1.FAM_RetrievalSuggestions_Util.generate({
+            relevantSet: set.confidentSet,
+            query: set.query,
+            effectiveTopK: set.effectiveTopK,
+            truncated: set.truncated,
+            maxPageSize: MAX_PAGE_SIZE,
+        });
+    }
     // =========================================================================
     // CONFIG-FELOLDÁS (SP-5.2, dsgn-005 §6 / dsgn-007 SSOT) + query-embedding (SP-5.2 ④)
     // =========================================================================
@@ -244,9 +479,15 @@ class FAM_Retrieval_ControlService {
     async resolveReadConfig(table, query) {
         const config = config_control_service_1.FAM_Config_ControlService.getInstance();
         const ctx = { table: table };
-        // query.topK / query.minScore felülírja a config-default-ot (dsgn-003 §2.1 query-opció).
-        const topKDefault = query.topK ?? await this.resolveNumber(config, 'read.topK', ctx, 5);
+        // query.topK / query.minScore felülírja a config-default-ot (dsgn-003 §2.1 query-opció). A `depth:'deep'`
+        // (mély feltárás) az alap-topK-t a `read.deepTopK`-ra emeli (sokkal több chunk) — az explicit `topK` nyer.
+        const isDeep = query.depth === 'deep';
+        const topKDefault = query.topK ?? (isDeep
+            ? await this.resolveNumber(config, 'read.deepTopK', ctx, 25)
+            : await this.resolveNumber(config, 'read.topK', ctx, 5));
         const minScore = query.minScore ?? await this.resolveNumber(config, 'read.minScore', ctx, 0);
+        const relevanceFloor = await this.resolveNumber(config, 'read.relevanceFloor', ctx, 0.5);
+        const importChunkWeight = await this.resolveNumber(config, 'read.importChunkWeight', ctx, 0.4);
         const denseResultRatio = await this.resolveNumber(config, 'read.denseResultRatio', ctx, 2.0);
         const denseResultAbsMin = await this.resolveNumber(config, 'read.denseResultAbsMin', ctx, 25);
         const scoreOrderValue = (await config.resolve('read.scoreOrder', ctx)).value;
@@ -254,6 +495,8 @@ class FAM_Retrieval_ControlService {
         return {
             topK: Math.min(topKDefault, MAX_PAGE_SIZE),
             minScore: minScore,
+            relevanceFloor: relevanceFloor,
+            importChunkWeight: importChunkWeight,
             denseResultRatio: denseResultRatio,
             denseResultAbsMin: denseResultAbsMin,
             scoreOrder: scoreOrder,

package/build/src/_modules/scope-reference/_collections/fam-scope-normalize.util.js

@@ -20,8 +20,11 @@ class FAM_ScopeNormalize_Util {
     /**
      * Egy nyers token normalizálása a de-dup / exact-match kulcshoz (dsgn-002 §3.1). A lépések:
      * (1) lowercase (Unicode-aware), (2) ékezet-fold (NFD + diakritika-strip — `"Adventör"` →
-     * `"adventor"`), (3) belső whitespace-collapse egyetlen szóközre, (4) trim. Üres/nem-string
-     * bemenet → üres string (a hívó dönti el, hogy az üres kulcs match-elhet-e).
+     * `"adventor"`), (3) **szeparátor-egységesítés** (FAM-REV-042): minden whitespace / `-` / `_`
+     * futam egyetlen szóközre — így `"auth-service"` ≡ `"auth service"` ≡ `"auth_service"` (a
+     * kötőjel-vs-alulvonás-vs-szóköz variánsok NEM hoznak létre dupla scope-ot), (4) trim. Üres/nem-string
+     * bemenet → üres string (a hívó dönti el, hogy az üres kulcs match-elhet-e). A tárolt `canonicalName`
+     * az EREDETI marad — a match futásidőben mindkét oldalt normalizálja, így nincs adatmigráció.
      */
     static normalize(raw) {
         if (!raw) {
@@ -31,7 +34,7 @@ class FAM_ScopeNormalize_Util {
             .toLowerCase()
             .normalize('NFD')
             .replace(FAM_ScopeNormalize_Util.DIACRITICS, '')
-            .replace(/\s+/g, ' ')
+            .replace(/[\s_-]+/g, ' ')
             .trim();
     }
     /**

package/build/src/_modules/scope-reference/_services/fam-reference.data-service.js

@@ -62,6 +62,10 @@ class FAM_Reference_DataService extends nts_dynamo_1.DyNTS_DataService {
             return null;
         }
         for (const reference of references) {
+            // Negatív-alias veto (disambiguáció): ez a reference EXPLICIT nem oldja fel a tokent → kihagyjuk.
+            if (FAM_Reference_DataService.vetoesToken(targetKey, reference)) {
+                continue;
+            }
             if (fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(reference.canonicalTerm) === targetKey) {
                 return reference;
             }
@@ -74,6 +78,20 @@ class FAM_Reference_DataService extends nts_dynamo_1.DyNTS_DataService {
         }
         return null;
     }
+    /**
+     * Veto-zza-e a reference a tokent (negatív-alias, „ne keverjünk dolgokat"): a token (normalizáltan) egyezik-e
+     * a reference bármely `negativeAliases`-ével. A tokent MAGA normalizálja (a `FAM_ScopeNormalize_Util` choke-
+     * ponton — idempotens, ha a hívó már normalizált adott át) → szeparátor-/ékezet-/kis-nagybetű-robusztus. Ha
+     * igen, ez a reference NEM kandidátus a tokenre (exact + fuzzy + vektor egyaránt). Üres negatív-lista → false.
+     */
+    static vetoesToken(token, reference) {
+        const target = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(token);
+        if (!target.length) {
+            return false;
+        }
+        return (reference.negativeAliases ?? [])
+            .some((negative) => fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(negative) === target);
+    }
     // =========================================================================
     // STRING-FUZZY (dsgn-002 §3.1, SP-3.2)
     // =========================================================================