@futdevpro/fdp-agent-memory 0.1.0

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

@@ -0,0 +1,282 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Retrieval_ControlService = void 0;
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const embedding_1 = require("../../embedding");
+const scope_reference_1 = require("../../scope-reference");
+const fam_retrieval_candidate_data_service_1 = require("./fam-retrieval-candidate.data-service");
+const fam_retrieval_suggestions_util_1 = require("./fam-retrieval-suggestions.util");
+/** A topK / lapozás abszolút plafonja (CCAP MAX_PAGE_SIZE=500; dsgn-005 §6). */
+const MAX_PAGE_SIZE = 500;
+/**
+ * `FAM_Retrieval_ControlService` (MP-5, dsgn-005) — a `read` **egylépcsős** retrieval-pipeline ENGINE-je.
+ * Singleton. Egy hívás több táblát + több query-t kezel; minden query ÖNÁLLÓ, kötött-sorrendű
+ * pipeline-on fut és ÖNÁLLÓ `results[]`-t termel. A `read` MCP-tool / REST (MP-6) ezt hívja, és a
+ * kimenetet a dsgn-003 §2.2 wire-shape-re map-eli (a dsgn-003 az AUTHORITATIV I/O — itt nem
+ * definiáljuk újra, csak kitöltjük).
+ *
+ * **Per-query pipeline (dsgn-005 §2, kötött sorrend):**
+ *   ① scope-prefilter (MP-3 `expandForRead` → subtree scopeId-halmaz) →
+ *   ② tag/kind prefilter + `_deleted`/`rules.isActive` guard (Mongo-szintű, a vektor-keresés ELŐTT) →
+ *   ④ vektor-keresés a szűkített poolon (MP-2 `search({ candidateIds })`, koszinusz) →
+ *   ⑤ weight-szorzó (`finalScore = score × weight`; weight≤0 → kizárt; coding_patterns weight 5) →
+ *   ⑥ minScore-küszöb (a relevantSet alapja) →
+ *   ⑦ rendezés (finalScore desc → recency → _id asc) →
+ *   ⑧ topK-vágás + dense-detektálás (§4 dual-gate + signaling).
+ *
+ * **NINCS LLM chunk-selector (dsgn-005 §7, ADR-009):** a precíziót a vektor-score + weight + minScore
+ * + prefilter adja, nem nyelvi modell. A pipeline egyetlen LLM-hívást sem indít (az embedding NEM
+ * chat-completion — az a query-vektor előállítása). Az opcionális relevance-filter BACKLOG, NEM épül.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt; minden
+ * DB-művelet előtt lazy `new FAM_RetrievalCandidate_DataService`.
+ */
+class FAM_Retrieval_ControlService {
+    static _instance;
+    /** Default issuer a retrieval-műveletekhez (a hibák / cost-event issuer-éhez; dsgn-008). */
+    issuer = 'FAM_Retrieval_ControlService';
+    static getInstance() {
+        if (!FAM_Retrieval_ControlService._instance) {
+            FAM_Retrieval_ControlService._instance = new FAM_Retrieval_ControlService();
+        }
+        return FAM_Retrieval_ControlService._instance;
+    }
+    // =========================================================================
+    // BELÉPŐ (SP-5.1) — egylépcsős, multi-tábla + multi-query
+    // =========================================================================
+    /**
+     * `read(request)` (SP-5.1, dsgn-005 §1) — a single-pass belépő. Minden `queries[]` elemre ÖNÁLLÓ
+     * pipeline (a query-k egymástól függetlenek, párhuzamosíthatók); a query-nkénti `results[]`-t a
+     * bemeneti sorrendben fűzi össze. Az `includeContent` default `true` (azonnal tartalom). A
+     * `globalScopeFilter` minden query-re közös scope-prefilter (a query saját `scopeFilter`-e
+     * felülírja, ha van).
+     */
+    async read(request) {
+        const includeContent = request.includeContent !== false;
+        // Per-query párhuzamosítható pipeline-ok (egymástól függetlenek; dsgn-005 §2).
+        const results = await Promise.all(request.queries.map((query) => this.runQuery(query, includeContent, request.globalScopeFilter)));
+        return { results: results };
+    }
+    /**
+     * Egy query teljes pipeline-ja (dsgn-005 §2). A `reference` tár SOHA nem szerepelhet a `tables`-ben
+     * (helper; dsgn-002/dsgn-005 §1) — a `read`-validáció (MP-6) elutasítja, de itt is kihagyjuk
+     * (defense-in-depth: a `FAM_StoreRegistry_Util` a reference-re undefined-et ad → üres jelölt-halmaz).
+     */
+    async runQuery(query, includeContent, globalScopeFilter) {
+        // ① scope-prefilter (MP-3): a query saját scopeFilter-e VAGY a globalScopeFilter (a query nyer).
+        const rawScopeFilter = query.scopeFilter && query.scopeFilter.length ? query.scopeFilter : globalScopeFilter;
+        const scopeExpand = await scope_reference_1.FAM_ScopeResolver_ControlService.getInstance().expandForRead(rawScopeFilter);
+        // A config-feloldás kontextusa: az ELSŐ cél-tár (a multi-tábla query közös rangsorba kerül; a
+        // limit/dense-küszöbök táblánként eltérhetnek — az első tár konfigja az alap, dsgn-005 §6).
+        const primaryTable = query.tables[0];
+        const config = await this.resolveReadConfig(primaryTable, query);
+        // A query-vektort EGYSZER embeddeljük (a több tár ugyanazt a query-vektort használja).
+        const queryVector = await this.embedQuery(query.query, primaryTable);
+        // ②–④ per-tár: Mongo-prefilter → vektor-keresés a szűkített poolon → hit-row összefűzés.
+        const allHits = [];
+        for (const table of query.tables) {
+            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);
+        // ⑦ 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 });
+    }
+    // =========================================================================
+    // ②–④ PER-TÁR: prefilter → vektor-keresés → hit-row (SP-5.1/SP-5.2)
+    // =========================================================================
+    /**
+     * Egy tár találatai (dsgn-005 §2.1/§2.2/§2.4/§2.5). ① a scope subtree + ② tag/kind Mongo-prefilter
+     * a candidate-ID halmazt adja; ④ a vektor-keresés CSAK a candidate-ID-kon fut (prefilter→vektor,
+     * dsgn-006 §4.3); ⑤ a finalScore = score × weight a candidate-entry weight-jéből (coding_patterns 5).
+     * A vektor-keresés `topK`-ja a relevantSet teljes felvételéhez igazítva (NEM a végső topK — a
+     * 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).
+        const byId = new Map();
+        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 (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),
+        });
+        // ⑤ weight-szorzó: finalScore = score × (weight ?? 1); weight ≤ 0 → kizárt (nem kerül a hits közé).
+        const hits = [];
+        for (const vectorHit of vectorHits) {
+            const entry = byId.get(vectorHit.id);
+            if (!entry) {
+                continue;
+            }
+            const weight = entry.weight ?? 1;
+            if (weight <= 0) {
+                continue;
+            }
+            hits.push(this.toHit({ entry, vectorHit, table: set.table, weight, includeContent: set.includeContent }));
+        }
+        return hits;
+    }
+    /** Egy candidate-entry + a vektor-hit → `FAM_RetrievalHit` (finalScore + denormalizált mezők). */
+    toHit(set) {
+        const lastModified = set.entry.__lastModified;
+        return {
+            id: set.vectorHit.id,
+            table: set.table,
+            score: set.vectorHit.score,
+            weight: set.weight,
+            finalScore: set.vectorHit.score * set.weight,
+            content: set.includeContent ? set.entry.content : undefined,
+            kind: set.entry.kind,
+            tags: set.entry.tags ?? [],
+            scopePath: (set.entry.scopePath ?? []),
+            source: set.entry.source,
+            sourceFilePath: set.entry.sourceFilePath ?? null,
+            lastModifiedMs: lastModified ? new Date(lastModified).getTime() : 0,
+        };
+    }
+    // =========================================================================
+    // ⑦ RENDEZÉS (SP-5.2, dsgn-005 §5)
+    // =========================================================================
+    /**
+     * Kötött rendezés (dsgn-005 §5): finalScore DESC → `__lastModified` DESC (recency) → `_id` ASC
+     * (determinisztikus végső tiebreak — stabil, reprodukálható sorrend). A `scoreOrder` config a fő
+     * kulcsot váltja: `weighted` (default; finalScore), `raw` (nyers koszinusz score), `recency`
+     * (lastModified-elsődleges). A tiebreak-lánc mindkét score-rendnél a recency + `_id`.
+     */
+    sortHits(hits, scoreOrder) {
+        hits.sort((a, b) => {
+            const primary = this.primaryComparator(a, b, scoreOrder);
+            if (primary !== 0) {
+                return primary;
+            }
+            // Recency tiebreak (frissebb előrébb azonos elsődleges kulcsnál).
+            if (b.lastModifiedMs !== a.lastModifiedMs) {
+                return b.lastModifiedMs - a.lastModifiedMs;
+            }
+            // Determinisztikus végső tiebreak (_id ASC) — stabil sorrend (teszt-stabilitás).
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        });
+    }
+    /** Az elsődleges összehasonlító a `scoreOrder` szerint (DESC a score-okra, recency külön ágon). */
+    primaryComparator(a, b, scoreOrder) {
+        if (scoreOrder === 'raw') {
+            return b.score - a.score;
+        }
+        if (scoreOrder === 'recency') {
+            return b.lastModifiedMs - a.lastModifiedMs;
+        }
+        // 'weighted' (default).
+        return b.finalScore - a.finalScore;
+    }
+    // =========================================================================
+    // ⑧ 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).
+     */
+    buildResult(set) {
+        const totalRelevant = set.relevantSet.length;
+        const effectiveTopK = set.config.topK;
+        const returnedHits = set.relevantSet.slice(0, effectiveTopK);
+        const truncated = totalRelevant > effectiveTopK;
+        // Dual-gate dense (§4.2) — csak `truncated:true` mellett lehet `true`.
+        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,
+            hits: returnedHits,
+            denseResults: denseResults,
+            totalRelevant: totalRelevant,
+            truncated: truncated,
+            suggestions: suggestions,
+            uncertaintyNotes: set.scopeExpand.uncertaintyNotes,
+        };
+    }
+    // =========================================================================
+    // CONFIG-FELOLDÁS (SP-5.2, dsgn-005 §6 / dsgn-007 SSOT) + query-embedding (SP-5.2 ④)
+    // =========================================================================
+    /**
+     * A read-pipeline config-rétegének feloldása az ELSŐ cél-tárra (dsgn-005 §6; MP-7 precedencia
+     * global<table<scope). A `read.topK` az effektív `min(query.topK ?? config, MAX_PAGE_SIZE)` (a
+     * query-szintű override nyer a config-default felett); a `read.minScore` szintén query-override-os;
+     * a `read.denseResultRatio` / `read.denseResultAbsMin` / `read.scoreOrder` a config-rétegből
+     * (dsgn-007 birtokolja az értéket, MP-5 csak fogyasztja).
+     */
+    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);
+        const minScore = query.minScore ?? await this.resolveNumber(config, 'read.minScore', ctx, 0);
+        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;
+        const scoreOrder = typeof scoreOrderValue === 'string' ? scoreOrderValue : 'weighted';
+        return {
+            topK: Math.min(topKDefault, MAX_PAGE_SIZE),
+            minScore: minScore,
+            denseResultRatio: denseResultRatio,
+            denseResultAbsMin: denseResultAbsMin,
+            scoreOrder: scoreOrder,
+        };
+    }
+    /** Egy szám-config feloldása a default-tal (a `resolve.value` lehet más típus → fallback). */
+    async resolveNumber(config, key, ctx, fallback) {
+        const value = (await config.resolve(key, ctx)).value;
+        return typeof value === 'number' ? value : fallback;
+    }
+    /**
+     * A query-vektor előállítása (SP-5.2 ④; dsgn-005 §2.4). A provider-agnosztikus
+     * `FAM_Embedding_ControlService.embedOne` (a `table`-re feloldva — per-tár provider/modell
+     * override). Ez NEM LLM chat-completion (dsgn-005 §7) — csak embedding. A multi-tábla query
+     * ugyanazt a query-vektort használja minden tárra (egy embed-hívás).
+     */
+    async embedQuery(query, table) {
+        return embedding_1.FAM_Embedding_ControlService.getInstance().embedOne({
+            text: query,
+            table: table,
+            callType: 'embed-query',
+            issuer: this.issuer,
+        });
+    }
+}
+exports.FAM_Retrieval_ControlService = FAM_Retrieval_ControlService;

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

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * `retrieval` modul barrel (MP-5, dsgn-005) — a `read` egylépcsős retrieval-pipeline ENGINE publikus
+ * felülete. A `read` MCP-tool / REST (MP-6) innen importálja a `FAM_Retrieval_ControlService`-t és a
+ * pipeline I/O-vokabulárt; a kimenetet a dsgn-003 §2.2 wire-shape-re map-eli (a dsgn-003 az
+ * authoritatív MCP-kontraktus — itt nem definiáljuk újra).
+ *
+ * Boundary (dsgn-005 §7, ADR-009): MP-5 = a read-pipeline ENGINE. NINCS core LLM chunk-selector; a
+ * precíziót a vektor-score + weight + minScore + prefilter adja. A `read` tool / REST = MP-6; az
+ * opcionális relevance-filter = BACKLOG (NEM épül).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_RetrievalSuggestions_Util = exports.FAM_RetrievalCandidate_DataService = exports.FAM_Retrieval_ControlService = void 0;
+// SP-5.1/5.2/5.3 — a read-pipeline orchestrátor
+var fam_retrieval_control_service_1 = require("./_services/fam-retrieval.control-service");
+Object.defineProperty(exports, "FAM_Retrieval_ControlService", { enumerable: true, get: function () { return fam_retrieval_control_service_1.FAM_Retrieval_ControlService; } });
+// SP-5.1 ① scope + ② tag/kind Mongo-prefilter (a vektor-keresés ELŐTT)
+var fam_retrieval_candidate_data_service_1 = require("./_services/fam-retrieval-candidate.data-service");
+Object.defineProperty(exports, "FAM_RetrievalCandidate_DataService", { enumerable: true, get: function () { return fam_retrieval_candidate_data_service_1.FAM_RetrievalCandidate_DataService; } });
+// SP-5.3 dense-suggestion generátor (a relevantSet valós statisztikáiból)
+var fam_retrieval_suggestions_util_1 = require("./_services/fam-retrieval-suggestions.util");
+Object.defineProperty(exports, "FAM_RetrievalSuggestions_Util", { enumerable: true, get: function () { return fam_retrieval_suggestions_util_1.FAM_RetrievalSuggestions_Util; } });

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

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_FuzzyMatch_Util = void 0;
+const fam_scope_normalize_util_1 = require("./fam-scope-normalize.util");
+/**
+ * `FAM_FuzzyMatch_Util` (SP-3.2, dsgn-002 §3.1 string-fuzzy ág) — **projekt-lokális workaround**:
+ * a Dynamo-szinten nincs dedikált string-fuzzy, ezért normalizált Levenshtein-távolságon alapuló
+ * typo-toleráns string-similarity. A fonetikus/STT-variánsok eleve az `aliasTerms`-ben élnek (a
+ * dsgn-002 §5 alias-csomagok); a string-fuzzy a KATALOGIZÁLATLAN elírásokat fogja meg
+ * (pl. `"Dyanmo FSM"` → `"Dynamo FSM"`).
+ *
+ * **Hossz-arányos szigorítás (SP-3.2 kockázat):** a similarity score `1 - distance/maxLen`,
+ * de a rövid token false-positive-jának elkerülésére a NYERS score-t adjuk vissza, a küszöbölést
+ * (`reference.fuzzyMinScore`) a hívó (resolver) végzi — a rövid tokennél eleve magasabb relatív
+ * távolság kell a match-hez.
+ */
+class FAM_FuzzyMatch_Util {
+    /**
+     * Normalizált string-similarity score 0..1 (1 = azonos normalizált forma). A két tokent a
+     * `FAM_ScopeNormalize_Util`-on át normalizálja (közös choke-pont), majd a Levenshtein-távolságot
+     * a hosszabb stringre vetíti: `1 - distance/maxLen`. Üres normalizált forma → 0 (nem match-el).
+     */
+    static similarity(a, b) {
+        const normalizedA = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(a);
+        const normalizedB = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(b);
+        if (!normalizedA.length || !normalizedB.length) {
+            return 0;
+        }
+        if (normalizedA === normalizedB) {
+            return 1;
+        }
+        const maxLen = Math.max(normalizedA.length, normalizedB.length);
+        const distance = FAM_FuzzyMatch_Util.levenshtein(normalizedA, normalizedB);
+        const score = 1 - distance / maxLen;
+        return score < 0 ? 0 : score;
+    }
+    /**
+     * A legjobb string-similarity score egy token és egy term-halmaz (canonicalTerm + aliasTerms)
+     * között — a halmaz BÁRMELY tagjával vett legmagasabb similarity. A fonetikus/typo variánsok
+     * elszórtan vannak az `aliasTerms`-ben, ezért a max-aggregálás a helyes (egyetlen alias-egyezés
+     * is felemeli a score-t).
+     */
+    static bestSimilarity(token, terms) {
+        let best = 0;
+        for (const term of terms) {
+            const score = FAM_FuzzyMatch_Util.similarity(token, term);
+            if (score > best) {
+                best = score;
+            }
+        }
+        return best;
+    }
+    /**
+     * Levenshtein-edit-távolság (insert/delete/substitute) két string között — két-soros DP
+     * (memória O(min(n,m))). Determinisztikus, függőség-mentes (a teszt-determinizmushoz).
+     */
+    static levenshtein(a, b) {
+        if (a === b) {
+            return 0;
+        }
+        if (!a.length) {
+            return b.length;
+        }
+        if (!b.length) {
+            return a.length;
+        }
+        // Két-soros DP: a `previous` az előző sor, a `current` az aktuális.
+        let previous = [];
+        for (let j = 0; j <= b.length; j++) {
+            previous[j] = j;
+        }
+        for (let i = 1; i <= a.length; i++) {
+            const current = [i];
+            for (let j = 1; j <= b.length; j++) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                const deletion = previous[j] + 1;
+                const insertion = current[j - 1] + 1;
+                const substitution = previous[j - 1] + cost;
+                current[j] = Math.min(deletion, insertion, substitution);
+            }
+            previous = current;
+        }
+        return previous[b.length];
+    }
+}
+exports.FAM_FuzzyMatch_Util = FAM_FuzzyMatch_Util;

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScopeNormalize_Util = void 0;
+/**
+ * `FAM_ScopeNormalize_Util` (SP-3.1, dsgn-002 §3.1 fast-path) — statikus, **függőség-mentes**
+ * normalizáló util. EGYETLEN choke-pont a de-dup kulcshoz és az exact-match fast-path-hez:
+ * lowercase + ékezet-fold (Unicode NFD diakritika-strip) + whitespace-collapse + trim.
+ *
+ * A tárolt `canonicalName` / `canonicalTerm` az EREDETI (megjelenítéshez); a feloldási / de-dup
+ * KULCS a normalizált forma. Ha a normalizálás nem fedi az ékezet/STT/whitespace-variánsokat,
+ * ugyanaz az entitás két `scopeId`-t kap → a determinizmus-acceptance (dsgn-002 §7.6) bukik;
+ * ezért minden normalizálás ITT fut át (a scope-de-dup és a reference exact-match is).
+ */
+class FAM_ScopeNormalize_Util {
+    /**
+     * A Unicode kombináló-diakritika tartomány (U+0300..U+036F) — NFD-bontás után ezt strip-eljük.
+     * `new RegExp` explicit `\u`-escape-pel (a literál kombináló-karakter encoding-ambiguitás ellen).
+     */
+    static DIACRITICS = new RegExp('[\\u0300-\\u036f]', 'g');
+    /**
+     * 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).
+     */
+    static normalize(raw) {
+        if (!raw) {
+            return '';
+        }
+        return raw
+            .toLowerCase()
+            .normalize('NFD')
+            .replace(FAM_ScopeNormalize_Util.DIACRITICS, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
+    /**
+     * Két nyers token normalizált-egyezése (a fast-path egyenlőség-tesztje). Üres normalizált
+     * forma SOHA nem match-el (egy üres token nem old fel semmire — dsgn-002 §4 nincs-match ág).
+     */
+    static equals(a, b) {
+        const normalizedA = FAM_ScopeNormalize_Util.normalize(a);
+        const normalizedB = FAM_ScopeNormalize_Util.normalize(b);
+        return normalizedA.length > 0 && normalizedA === normalizedB;
+    }
+}
+exports.FAM_ScopeNormalize_Util = FAM_ScopeNormalize_Util;

package/build/src/_modules/scope-reference/_models/interfaces/fam-reference-resolution.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/_modules/scope-reference/_models/interfaces/fam-resolution-trace.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Reference_DataService = void 0;
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_reference_data_model_1 = require("../../../_models/data-models/fam-reference.data-model");
+const fam_fuzzy_match_util_1 = require("../_collections/fam-fuzzy-match.util");
+const fam_scope_normalize_util_1 = require("../_collections/fam-scope-normalize.util");
+/** A reference-alapú string/exact match küszöbök. */
+const VECTOR_TOP_N = 5;
+/**
+ * `FAM_Reference_DataService` (SP-3.2, dsgn-002 §3.1/§6) — a `fam_reference` collection CRUD + a
+ * **kétfázisú fuzzy match**: (a) exact fast-path (`canonicalTerm`/`aliasTerms` normalizált egyezés),
+ * (b) string-fuzzy (`FAM_FuzzyMatch_Util` Levenshtein) ÉS vektor-fuzzy (cosine a `contentVector`-on).
+ * Csak `isActive: true` bejegyzés expand-elődik (dsgn-002 §3.1).
+ *
+ * `extends DyNTS_DataService` (soft-delete = move-to-archive a `getArchiveDataService`-en át). A
+ * vektor-fuzzy az MP-2-re **lágy** dependens: a `vectorMatch` egy KÉSZ query-vektort + a
+ * reference-korpuszt kapja (a resolver embeddeli a tokent), így a string-fuzzy ág MP-2 NÉLKÜL is teljes értékű.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** a base-ctor EAGER `getDBService`-t hív —
+ * a control-service-ek NEM tartanak élő példányt mezőként; minden művelet előtt lazy `new`.
+ */
+class FAM_Reference_DataService extends nts_dynamo_1.DyNTS_DataService {
+    constructor(set) {
+        super(set.data instanceof fam_reference_data_model_1.FAM_Reference_DataModel ? set.data : new fam_reference_data_model_1.FAM_Reference_DataModel(set.data), fam_reference_data_model_1.famReference_dataParams, set.issuer);
+    }
+    /**
+     * A move-to-archive soft-delete (dsgn-001 §8) archív-collection service-e: a base `deleteData`
+     * (addArchive) ezt hívja, hogy a törölt reference-t a `fam_reference_archived` tárba mozgassa. A
+     * `DyNTS_DataService` base default-ja DOB (nincs ökoszisztéma-implementáció) — ezért az explicit
+     * override (a `DyNTS_ArchiveDataService` a `dataParams.addArchive`-ból oldja az archív-nevet).
+     */
+    getArchiveDataService() {
+        return new nts_dynamo_1.DyNTS_ArchiveDataService(new fam_reference_data_model_1.FAM_Reference_DataModel(), this.dataParams, this.issuer);
+    }
+    // =========================================================================
+    // CRUD + active-only (dsgn-002 §3.1)
+    // =========================================================================
+    /** Egy reference `_id` alapján (vagy üres-objektum, ha nincs / törölt). */
+    async findReferenceById(referenceId) {
+        return this.findData({ _id: referenceId }, true);
+    }
+    /**
+     * `findActive()` (dsgn-002 §3.1) — az AKTÍV (`isActive: true`, nem soft-delete-elt) reference-ek.
+     * Az inaktív bejegyzés NEM expand-elődik. A resolver-cache (SP-3.3) ezt snapshot-olja.
+     */
+    async findActive() {
+        return this.findDataList({ isActive: true }, true);
+    }
+    // =========================================================================
+    // EXACT FAST-PATH (dsgn-002 §3.1)
+    // =========================================================================
+    /**
+     * `exactMatch(rawToken, references)` (SP-3.2) — normalizált exact egyezés a `canonicalTerm`
+     * VAGY bármely `aliasTerm` ellen (a `FAM_ScopeNormalize_Util` közös choke-pontján). A korpuszt
+     * a hívó adja (cache-snapshot) — nincs per-hívás DB-kör. Az első egyezés a győztes (a korpusz
+     * de-dup-olt). Üres token / nincs egyezés → `null`.
+     */
+    exactMatch(rawToken, references) {
+        const targetKey = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawToken);
+        if (!targetKey.length) {
+            return null;
+        }
+        for (const reference of references) {
+            if (fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(reference.canonicalTerm) === targetKey) {
+                return reference;
+            }
+            const aliases = reference.aliasTerms ?? [];
+            for (const alias of aliases) {
+                if (fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(alias) === targetKey) {
+                    return reference;
+                }
+            }
+        }
+        return null;
+    }
+    // =========================================================================
+    // STRING-FUZZY (dsgn-002 §3.1, SP-3.2)
+    // =========================================================================
+    /**
+     * `stringFuzzyMatch(rawToken, references)` (SP-3.2) — Levenshtein-alapú string-similarity a
+     * `canonicalTerm` + minden `aliasTerm` ellen (a katalogizálatlan elírásokra, pl. `"Dyanmo FSM"`).
+     * Per-reference a LEGJOBB term-similarity a score; minden reference egy kandidátus. A küszöbölést
+     * (`reference.fuzzyMinScore`) a resolver (SP-3.4) végzi — ITT a NYERS score-os kandidátusok.
+     */
+    stringFuzzyMatch(rawToken, references) {
+        const candidates = [];
+        for (const reference of references) {
+            const terms = [reference.canonicalTerm ?? '', ...(reference.aliasTerms ?? [])].filter((t) => t.length > 0);
+            if (!terms.length) {
+                continue;
+            }
+            const score = fam_fuzzy_match_util_1.FAM_FuzzyMatch_Util.bestSimilarity(rawToken, terms);
+            if (score <= 0) {
+                continue;
+            }
+            candidates.push(this.toCandidate(reference, score, 'string-fuzzy'));
+        }
+        return candidates;
+    }
+    // =========================================================================
+    // VEKTOR-FUZZY (dsgn-002 §3.1, SP-3.2) — SOFT dep MP-2
+    // =========================================================================
+    /**
+     * `vectorMatch(queryVector, references)` (SP-3.2) — koszinusz-similarity a kész query-vektor és
+     * a reference-ek `contentVector`-ja között (a szemantikai közelséget fogja, amit a string-fuzzy
+     * NEM). A query-vektort a resolver embeddeli (MP-2 `FAM_Embedding_ControlService`); ÜRES vektor
+     * (embedding-hiány) → üres lista (graceful degrade — a resolver string-only fallbackra vált + warn).
+     * A dimenzió-eltérésű reference-vektort kihagyja (nem kever eltérő dimenziót). Top-N kandidátus.
+     */
+    vectorMatch(queryVector, references) {
+        if (!queryVector.length) {
+            return [];
+        }
+        const candidates = [];
+        for (const reference of references) {
+            const vector = reference.contentVector ?? [];
+            if (vector.length !== queryVector.length) {
+                continue;
+            }
+            const score = FAM_Reference_DataService.cosineSimilarity(queryVector, vector);
+            if (score <= 0) {
+                continue;
+            }
+            candidates.push(this.toCandidate(reference, score, 'vector-fuzzy'));
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        return candidates.slice(0, VECTOR_TOP_N);
+    }
+    // =========================================================================
+    // helpers
+    // =========================================================================
+    /** A `FAM_FuzzyResolveContext` szűrés alkalmazása egy korpuszra (csak a releváns layer/tár). */
+    filterByContext(references, context) {
+        if (!context || (!context.scopeLayer && !(context.ragScopes && context.ragScopes.length))) {
+            return references;
+        }
+        return references.filter((reference) => {
+            if (context.scopeLayer && reference.scopeLayer && reference.scopeLayer !== context.scopeLayer) {
+                return false;
+            }
+            if (context.ragScopes && context.ragScopes.length) {
+                const refScopes = (reference.ragScopes ?? []);
+                // Üres ragScopes a reference-en = minden tárra alkalmazható (dsgn-001 §5).
+                if (refScopes.length && !refScopes.some((scope) => context.ragScopes?.includes(scope))) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    /** Egy reference → kandidátus map (a canonicalScopeRef / scopeLayer / referenceId átemelése). */
+    toCandidate(reference, score, matchSource) {
+        return {
+            canonicalTerm: reference.canonicalTerm ?? '',
+            score: score,
+            matchSource: matchSource,
+            canonicalScopeRef: reference.canonicalScopeRef,
+            scopeLayer: reference.scopeLayer,
+            referenceId: reference._id,
+        };
+    }
+    /** Koszinusz-similarity két azonos-dimenziójú vektor között (0..1 l2-normalizálással). */
+    static cosineSimilarity(a, b) {
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (!normA || !normB) {
+            return 0;
+        }
+        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+}
+exports.FAM_Reference_DataService = FAM_Reference_DataService;