@futdevpro/fdp-agent-memory 0.1.0

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

@@ -0,0 +1,473 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScopeResolver_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const embedding_1 = require("../../embedding");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_reference_data_service_1 = require("./fam-reference.data-service");
+const fam_scope_data_service_1 = require("./fam-scope.data-service");
+const fam_scope_normalize_util_1 = require("../_collections/fam-scope-normalize.util");
+/** A `confident` és a `ambiguous-multi` szétválasztó score-gap (a győztes és a 2. közti különbség). */
+const AMBIGUITY_SCORE_GAP = 0.05;
+/**
+ * `FAM_ScopeResolver_ControlService` (SP-3.3/SP-3.4, dsgn-002 §3/§4) — a scope/reference feloldás
+ * EGYETLEN control-service-e. Singleton. Felelősségek:
+ *
+ * - **write-resolve** (`resolveWrite`, dsgn-002 §3.2): raw scopePath layerenként → reference-resolve
+ *   → canonical scopeId-lánc → hiányzó scope auto-regiszt (`createdBy='agent-write'`) → mentésre kész
+ *   `scopePath`. Bizonytalan layer → `FAM-REF-RESOLVE-*` hiba (SP-3.4), NEM auto-regiszt.
+ * - **read-expand** (`expandForRead`, dsgn-002 §3.3): raw scopeFilter → reference-expand → canonical
+ *   subtree-prefilter scopeId-halmaz (subtree-szemantika). Filter nélkül → `null` (teljes tár, NEM hiba).
+ * - **reference-cache** (TTL `reference.cacheTtlMs`, default 60000): a `findActive()` korpusz in-memory
+ *   snapshot-ja; `rebuildReferenceIndex()` azonnal invalidál + újratölt.
+ * - **`scopeExists`** (MP-7 deferred `FAM-CONFIG-SET-006`-hoz): egy `scopeId` aktív-e a fán.
+ *
+ * **Bizonytalanság (SP-3.4, dsgn-002 §4):** nincs-match + bizonytalan → részletes hiba; van-match +
+ * bizonytalan → eredmény + `uncertaintyNotes[]` (NEM hiba). Egyik ág sem néma.
+ *
+ * **FIGYELEM (memory: dynts_dataservice_eager_resolve):** NEM tartunk élő DataService mezőt; minden
+ * DB-művelet előtt lazy `new FAM_Scope_DataService` / `new FAM_Reference_DataService`.
+ */
+class FAM_ScopeResolver_ControlService {
+    static _instance;
+    /** Default issuer a feloldás-műveletekhez (a hibák / cost-event issuer-éhez). */
+    issuer = 'FAM_ScopeResolver_ControlService';
+    /** A reference-korpusz in-memory snapshot-ja (`null` = még nincs / invalidált — újratölt). */
+    referenceCache = null;
+    static getInstance() {
+        if (!FAM_ScopeResolver_ControlService._instance) {
+            FAM_ScopeResolver_ControlService._instance = new FAM_ScopeResolver_ControlService();
+        }
+        return FAM_ScopeResolver_ControlService._instance;
+    }
+    // =========================================================================
+    // REFERENCE-CACHE (dsgn-002 §3.1, SP-3.3)
+    // =========================================================================
+    /**
+     * Az aktív reference-korpusz a TTL-cache-ből (dsgn-002 §3.1). Ha a snapshot frissebb a
+     * `reference.cacheTtlMs`-nél, a cache-elt listát adja (NINCS DB-kör); egyébként `findActive()` +
+     * cache-frissítés. A `rebuildReferenceIndex()` azonnal invalidálja.
+     */
+    async getActiveReferences() {
+        const ttlMs = await this.resolveCacheTtlMs();
+        const now = Date.now();
+        if (this.referenceCache && (now - this.referenceCache.loadedAt) < ttlMs) {
+            return this.referenceCache.references;
+        }
+        const reference_DS = new fam_reference_data_service_1.FAM_Reference_DataService({ issuer: this.issuer });
+        const references = await reference_DS.findActive();
+        this.referenceCache = { references: references, loadedAt: now };
+        return references;
+    }
+    /**
+     * `rebuildReferenceIndex()` (dsgn-002 §3.1, a `rebuild_reference_index` capability — MP-6 hívja).
+     * Azonnal invalidál + újratölt: a frissen felvett reference azonnal látszik (a TTL bevárása
+     * nélkül). Hiba esetén `FAM-REF-INDEX-001` + a régi cache-szel DEGRADÁLVA tovább-működés (NEM
+     * dob el mindent — dsgn-008 §3 index-rebuild ág), `warn` surfacing.
+     */
+    async rebuildReferenceIndex() {
+        try {
+            const reference_DS = new fam_reference_data_service_1.FAM_Reference_DataService({ issuer: this.issuer });
+            const references = await reference_DS.findActive();
+            this.referenceCache = { references: references, loadedAt: Date.now() };
+            return { count: references.length, stale: false };
+        }
+        catch (error) {
+            // Degradált tovább-működés: a régi cache marad (ha van), NEM teljes resolver-leállás.
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM reference-index] rebuild sikertelen, a régi cache marad: ${error?.message}`);
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.refIndexRebuild,
+                message: 'A reference-index újraépítése sikertelen — a feloldó a korábbi (esetleg elavult) '
+                    + 'cache-szel működik tovább. A friss reference-bejegyzések a következő sikeres rebuildig nem látszanak.',
+                issuer: this.issuer,
+                context: { operation: 'rebuild-reference-index' },
+                cause: error,
+            });
+        }
+    }
+    /** A reference-cache TTL feloldása a config-ból (`reference.cacheTtlMs`, default 60000). */
+    async resolveCacheTtlMs() {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('reference.cacheTtlMs');
+        return typeof resolved.value === 'number' ? resolved.value : 60000;
+    }
+    /** A fuzzy-match konfidencia-küszöb a config-ból (`reference.fuzzyMinScore`, default 0.75). */
+    async resolveFuzzyMinScore() {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('reference.fuzzyMinScore');
+        return typeof resolved.value === 'number' ? resolved.value : 0.75;
+    }
+    /** Az auto-create-scope kapcsoló a config-ból (`reference.autoCreateScope`, default true). */
+    async resolveAutoCreateScope() {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('reference.autoCreateScope');
+        return typeof resolved.value === 'boolean' ? resolved.value : true;
+    }
+    // =========================================================================
+    // FUZZY-RESOLVE (dsgn-002 §3.1, SP-3.2 fúzió) — exact → string-fuzzy → vektor-fuzzy
+    // =========================================================================
+    /**
+     * `fuzzyResolve(rawToken, context)` (SP-3.2) — egyesíti az exact + string-fuzzy + vektor-fuzzy
+     * kandidátusokat EGY rendezett, pontszámos listába (dsgn-002 §3.1). Score-fúzió: exact=1.0;
+     * a string- és vektor-kandidátusok a saját score-jukkal; per-canonical a LEGJOBB score nyer
+     * (dedup canonicalTerm szerint). A `context` (scopeLayer/ragScopes) a nem-releváns kandidátusokat
+     * kizárja. A vektor-ág graceful: embedding-hiány → string-only + warn (NEM crash).
+     */
+    async fuzzyResolve(rawToken, context) {
+        const reference_DS = new fam_reference_data_service_1.FAM_Reference_DataService({ issuer: this.issuer });
+        const allReferences = await this.getActiveReferences();
+        const references = reference_DS.filterByContext(allReferences, context);
+        const candidates = [];
+        // (1) Exact fast-path (score 1.0).
+        const exact = reference_DS.exactMatch(rawToken, references);
+        if (exact) {
+            candidates.push({
+                canonicalTerm: exact.canonicalTerm ?? '',
+                score: 1.0,
+                matchSource: 'exact',
+                canonicalScopeRef: exact.canonicalScopeRef,
+                scopeLayer: exact.scopeLayer,
+                referenceId: exact._id,
+            });
+        }
+        // (2) String-fuzzy (Levenshtein) — a katalogizálatlan elírásokra.
+        candidates.push(...reference_DS.stringFuzzyMatch(rawToken, references));
+        // (3) Vektor-fuzzy (cosine) — soft dep MP-2; graceful degrade embedding-hiányra.
+        const queryVector = await this.embedTokenSafe(rawToken);
+        if (queryVector.length) {
+            candidates.push(...reference_DS.vectorMatch(queryVector, references));
+        }
+        return this.dedupAndSort(candidates);
+    }
+    /**
+     * A token embeddelése a vektor-fuzzy-hoz (MP-2 `FAM_Embedding_ControlService`). Bármilyen hiba /
+     * üres pool / nincs provider → üres vektor + `warn` (graceful degrade — a string-fuzzy ág teljes
+     * értékű marad MP-2 nélkül; dsgn-002 §3.1 SP-3.2 kockázat). NEM dob, NEM néma (warn-log).
+     */
+    async embedTokenSafe(rawToken) {
+        try {
+            const vector = await embedding_1.FAM_Embedding_ControlService.getInstance().embedOne({
+                text: rawToken,
+                callType: 'embed-query',
+                issuer: this.issuer,
+            });
+            return vector;
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM reference vektor-fuzzy] embedding nem elérhető a('${rawToken}') tokenre → string-only fallback: `
+                + `${error?.message}`);
+            return [];
+        }
+    }
+    /** Kandidátus-dedup canonicalTerm szerint (a legjobb score nyer) + csökkenő rendezés. */
+    dedupAndSort(candidates) {
+        const bestByCanonical = new Map();
+        for (const candidate of candidates) {
+            const key = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(candidate.canonicalTerm);
+            const existing = bestByCanonical.get(key);
+            if (!existing || candidate.score > existing.score) {
+                bestByCanonical.set(key, candidate);
+            }
+        }
+        return Array.from(bestByCanonical.values()).sort((a, b) => b.score - a.score);
+    }
+    // =========================================================================
+    // BIZONYTALANSÁG-ELDÖNTÉS (dsgn-002 §4, SP-3.4)
+    // =========================================================================
+    /**
+     * `classifyResolution(candidates, minScore)` (SP-3.4) — küszöb-alapú feloldás-osztály:
+     * - `no-match`: a legjobb score < `minScore` (vagy nincs kandidátus),
+     * - `ambiguous-multi`: a top-2 mindkettő >= `minScore` ÉS a score-gap < `AMBIGUITY_SCORE_GAP`,
+     * - `confident`: 1 magas-konfidenciájú, jól-elkülönülő kandidátus.
+     */
+    classifyResolution(candidates, minScore) {
+        if (!candidates.length || candidates[0].score < minScore) {
+            return 'no-match';
+        }
+        if (candidates.length >= 2 && candidates[1].score >= minScore
+            && (candidates[0].score - candidates[1].score) < AMBIGUITY_SCORE_GAP) {
+            return 'ambiguous-multi';
+        }
+        return 'confident';
+    }
+    // =========================================================================
+    // WRITE-RESOLVE (dsgn-002 §3.2, SP-3.3) — scope KÖTELEZŐ
+    // =========================================================================
+    /**
+     * `resolveForWrite(rawScopePath)` (dsgn-002 §3.2). A scope a write-on KÖTELEZŐ: üres/hiányzó
+     * rawScopePath → `FAM-SCOPE-WRITE-001` (NEM csendes default). Layerenként:
+     * (1) `fuzzyResolve` (scopeLayer-szűkítve) → `classifyResolution`;
+     * (2) `confident` + scope-match → annak a `scopeId`-ja (a parent az előző layer feloldott scopeId-ja);
+     * (3) `confident` reference-match scope-ref NÉLKÜL VAGY `no-match` → ha `autoCreateScope` → a
+     *     canonical névvel auto-regiszt (`createdBy='agent-write'`); ha `ambiguous-multi` → SP-3.4
+     *     `FAM-REF-RESOLVE-002` hiba.
+     * Visszatérés: canonical `scopePath` (root→leaf) + layer-meta + `uncertaintyNotes[]` (kötelező mező).
+     */
+    async resolveForWrite(rawScopePath) {
+        if (!rawScopePath || !rawScopePath.length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scopeWriteRequired,
+                message: 'A scope KÖTELEZŐ minden tartalom-műveletnél (create/scan/import) — üres scopePath nem fogadható el. '
+                    + 'Adj meg legalább egy layert (pl. organization/project).',
+                issuer: this.issuer,
+                context: { operation: 'resolve-for-write' },
+            });
+        }
+        const minScore = await this.resolveFuzzyMinScore();
+        const autoCreate = await this.resolveAutoCreateScope();
+        const scope_DS = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const layers = [];
+        const uncertaintyNotes = [];
+        let parentScopeId = undefined;
+        for (const rawLayer of rawScopePath) {
+            const candidates = await this.fuzzyResolve(rawLayer.rawName, { scopeLayer: rawLayer.layer });
+            const classification = this.classifyResolution(candidates, minScore);
+            if (classification === 'ambiguous-multi') {
+                throw this.ambiguousError(rawLayer, candidates, minScore);
+            }
+            const resolved = await this.resolveOneWriteLayer({
+                rawLayer: rawLayer,
+                candidates: candidates,
+                classification: classification,
+                parentScopeId: parentScopeId,
+                autoCreate: autoCreate,
+                scopeDataService: scope_DS,
+            });
+            layers.push(resolved);
+            parentScopeId = resolved.scopeRef.scopeId;
+            // Van-match-bizonytalan: confident, de fuzzy (NEM exact) volt → uncertaintyNote (NEM hiba).
+            if (classification === 'confident' && candidates.length && candidates[0].matchSource !== 'exact') {
+                uncertaintyNotes.push(this.toUncertaintyNote(rawLayer.rawName, candidates));
+            }
+        }
+        return {
+            scopePath: layers.map((layer) => layer.scopeRef),
+            layers: layers,
+            uncertaintyNotes: uncertaintyNotes,
+        };
+    }
+    /**
+     * Egy write-layer feloldása (a `resolveForWrite` belső lépése). `confident` + scope-match → a
+     * meglévő scope; egyébként (confident-de-csak-fogalmi-alias VAGY no-match) → auto-regiszt
+     * (ha `autoCreate`), KÜLÖNBEN `FAM-REF-RESOLVE-001` (nincs match + nincs auto-create).
+     */
+    async resolveOneWriteLayer(set) {
+        // (a) confident reference-match, ami EGY konkrét scope-entitásra mutat → annak a scopeId-ja.
+        if (set.classification === 'confident' && set.candidates.length && set.candidates[0].canonicalScopeRef?.scopeId) {
+            const ref = set.candidates[0].canonicalScopeRef;
+            return { scopeRef: ref, created: false };
+        }
+        // (b) confident, de csak fogalmi alias (nincs scope-ref): a canonical néven find-or-create.
+        // (c) no-match: a nyers néven find-or-create — DE csak ha autoCreate; egyébként hiba.
+        const isConfident = set.classification === 'confident' && set.candidates.length > 0;
+        const canonicalName = isConfident ? set.candidates[0].canonicalTerm : set.rawLayer.rawName;
+        // Determinisztikus de-dup: a (normalizált név + layer + parent) hármasra már létezik-e?
+        const existing = await set.scopeDataService.findByCanonical(set.rawLayer.layer, canonicalName, set.parentScopeId);
+        if (existing.length && existing[0]._id) {
+            return { scopeRef: this.toScopeRef(existing[0]), created: false };
+        }
+        if (!set.autoCreate) {
+            throw this.noMatchError(set.rawLayer, set.candidates, await this.resolveFuzzyMinScore());
+        }
+        // Auto-regiszt (createdBy='agent-write', parent = az előző layer scopeId-ja).
+        const created = await set.scopeDataService.findOrCreateScope({
+            layer: set.rawLayer.layer,
+            canonicalName: canonicalName,
+            parentScopeId: set.parentScopeId,
+            createdBy: 'agent-write',
+        });
+        return { scopeRef: this.toScopeRef(created.scope), created: created.created };
+    }
+    // =========================================================================
+    // READ-EXPAND (dsgn-002 §3.3, SP-3.3) — scope OPCIONÁLIS prefilter
+    // =========================================================================
+    /**
+     * `expandForRead(rawScopeFilter?)` (dsgn-002 §3.3). Filter NÉLKÜL → `scopeIdSet: null` (teljes
+     * táron keresés — NEM hiba). Filterrel: layerenként feloldás → a feloldott scope-ok
+     * `getSubtreeScopeIds` UNIÓJA = canonical prefilter scopeId-halmaz (subtree-szemantika: a megadott
+     * layer + alatta minden leszármazott). Részleges filter (csak felső layer) → tág subtree (DESIGN).
+     * Van-match-bizonytalan → `uncertaintyNotes[]` (NEM hiba). Nincs-match egy layeren → `FAM-REF-RESOLVE-001`.
+     */
+    async expandForRead(rawScopeFilter) {
+        if (!rawScopeFilter || !rawScopeFilter.length) {
+            return { scopeIdSet: null, uncertaintyNotes: [] };
+        }
+        const minScore = await this.resolveFuzzyMinScore();
+        const scope_DS = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const scopeIdSet = new Set();
+        const uncertaintyNotes = [];
+        for (const rawLayer of rawScopeFilter) {
+            const candidates = await this.fuzzyResolve(rawLayer.rawName, { scopeLayer: rawLayer.layer });
+            const classification = this.classifyResolution(candidates, minScore);
+            const scopeIds = await this.resolveReadLayerScopeIds({
+                rawLayer: rawLayer,
+                candidates: candidates,
+                classification: classification,
+                minScore: minScore,
+                scopeDataService: scope_DS,
+            });
+            for (const scopeId of scopeIds) {
+                scopeIdSet.add(scopeId);
+            }
+            if (classification === 'confident' && candidates.length && candidates[0].matchSource !== 'exact') {
+                uncertaintyNotes.push(this.toUncertaintyNote(rawLayer.rawName, candidates));
+            }
+        }
+        return { scopeIdSet: Array.from(scopeIdSet), uncertaintyNotes: uncertaintyNotes };
+    }
+    /**
+     * Egy read-filter-layer → subtree scopeId-halmaz. A feloldott scope (reference scope-ref VAGY
+     * canonical-név-match a fán) subtree-ját adja (`getSubtreeScopeIds`). `ambiguous-multi` → minden
+     * közeli kandidátus subtree-ja bekerül (a read tág, NEM dob — a bizonytalanság uncertaintyNote).
+     * `no-match` → `FAM-REF-RESOLVE-001` (a read-filter feloldhatatlan, nincs csendes üres-prefilter).
+     */
+    async resolveReadLayerScopeIds(set) {
+        if (set.classification === 'no-match') {
+            throw this.noMatchError(set.rawLayer, set.candidates, set.minScore);
+        }
+        // A confident (top-1) + az ambiguous-multi (a >= minScore közeli kandidátusok) scope-jai.
+        const accepted = set.classification === 'ambiguous-multi'
+            ? set.candidates.filter((candidate) => candidate.score >= set.minScore)
+            : [set.candidates[0]];
+        const result = [];
+        for (const candidate of accepted) {
+            const rootScopeId = await this.candidateToScopeId({
+                rawLayer: set.rawLayer,
+                candidate: candidate,
+                scopeDataService: set.scopeDataService,
+            });
+            if (!rootScopeId) {
+                continue;
+            }
+            const subtree = await set.scopeDataService.getSubtreeScopeIds(rootScopeId);
+            result.push(...subtree);
+        }
+        return result;
+    }
+    /**
+     * Egy kandidátus → a fán létező scopeId (read-expand). Ha a kandidátus konkrét scope-ref-et hordoz
+     * → annak az scopeId-ja; egyébként a canonical néven keresünk a layerben (a read NEM hoz létre
+     * scope-ot — csak prefilter). Nincs a fán → undefined (nincs subtree).
+     */
+    async candidateToScopeId(set) {
+        if (set.candidate.canonicalScopeRef?.scopeId) {
+            return set.candidate.canonicalScopeRef.scopeId;
+        }
+        const matches = await set.scopeDataService.findByCanonical(set.rawLayer.layer, set.candidate.canonicalTerm);
+        return matches.length ? matches[0]._id : undefined;
+    }
+    // =========================================================================
+    // scopeExists (MP-7 deferred FAM-CONFIG-SET-006, SP-3.3)
+    // =========================================================================
+    /**
+     * `scopeExists(scopeId)` (SP-3.3) — egy `scopeId` AKTÍV-e a scope-fán. Az MP-7 config-set
+     * scope-szintű validációja (`FAM-CONFIG-SET-006`) ezt a lookup-ot halasztotta MP-3-ra: a
+     * `set('x', v, { level: scope, scopeId })` ezzel ellenőrizheti a tényleges scope-létet.
+     */
+    async scopeExists(scopeId) {
+        if (!scopeId) {
+            return false;
+        }
+        const scope_DS = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const scope = await scope_DS.findScopeById(scopeId);
+        return Boolean(scope && scope._id);
+    }
+    // =========================================================================
+    // TRACE (dsgn-002 §4, dsgn-003 §4.2) — a debug-capability (MP-6) fogyasztja
+    // =========================================================================
+    /**
+     * `traceResolution(rawTokens, mode)` (SP-3.3) — a feloldás lépés-naplója (token → normalizált →
+     * kandidátusok+score → döntés). A `trace_scope_resolution` / `trace_reference_expansion`
+     * debug-capability (MP-6) ezt adja ki. Nem mutál (nem hoz létre scope-ot) — csak feloldás-trace.
+     */
+    async traceResolution(rawTokens, mode) {
+        const minScore = await this.resolveFuzzyMinScore();
+        const queryVectorAvailable = (await this.embedTokenSafe(rawTokens[0]?.rawName ?? '')).length > 0;
+        const steps = [];
+        for (const rawLayer of rawTokens) {
+            const context = mode === 'query-expand' ? undefined : { scopeLayer: rawLayer.layer };
+            const candidates = await this.fuzzyResolve(rawLayer.rawName, context);
+            const classification = this.classifyResolution(candidates, minScore);
+            const decided = classification === 'confident' ? candidates[0] : undefined;
+            steps.push({
+                rawToken: rawLayer.rawName,
+                normalizedForm: fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawLayer.rawName),
+                layer: mode === 'query-expand' ? undefined : rawLayer.layer,
+                candidates: candidates,
+                classification: classification,
+                decidedMatchSource: decided?.matchSource,
+                decidedCanonical: decided?.canonicalTerm,
+            });
+        }
+        const cacheAge = this.referenceCache ? Date.now() - this.referenceCache.loadedAt : 0;
+        return {
+            mode: mode,
+            steps: steps,
+            vectorAvailable: queryVectorAvailable,
+            referenceCacheAgeMs: cacheAge,
+        };
+    }
+    // =========================================================================
+    // UNCERTAINTY + hiba-építés (dsgn-002 §4, SP-3.4)
+    // =========================================================================
+    /** Egy győztes kandidátus + alternatívák → `uncertaintyNote` (van-match-bizonytalan, NEM hiba). */
+    toUncertaintyNote(rawToken, candidates) {
+        const winner = candidates[0];
+        return {
+            rawToken: rawToken,
+            normalizedForm: fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawToken),
+            resolvedTo: winner.canonicalTerm,
+            confidence: winner.score,
+            matchSource: winner.matchSource,
+            alternatives: candidates.slice(1, 4).map((candidate) => ({ term: candidate.canonicalTerm, score: candidate.score })),
+        };
+    }
+    /**
+     * Nincs-match + bizonytalan → `FAM-REF-RESOLVE-001` (dsgn-002 §4, level=user). DESKRIPTÍV
+     * payload: feloldatlan token, normalizált forma, legközelebbi kandidátusok (term+score),
+     * vizsgált layer, konkrét javaslat. Üres `[]` SOSEM helyettesíti a hibát (no-silent-failure).
+     */
+    noMatchError(rawLayer, candidates, minScore) {
+        const normalized = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawLayer.rawName);
+        const nearest = candidates.length
+            ? candidates.slice(0, 3).map((candidate) => `${candidate.canonicalTerm} (${candidate.score.toFixed(2)})`).join(', ')
+            : 'nincs egyetlen kandidátus sem';
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.refResolveNoMatch,
+            message: `A(z) '${rawLayer.layer}' layer '${rawLayer.rawName}' tokenje nem oldható fel `
+                + `(normalizált: '${normalized}'). Legközelebbi kandidátusok: ${nearest} — egyik sem éri el a `
+                + `${minScore} konfidencia-küszöböt. Javaslat: hozz létre reference-bejegyzést erre a névre, `
+                + 'vagy adj meg egy explicit, létező scope nevet.',
+            issuer: this.issuer,
+            context: { operation: 'resolve-no-match', scopePath: [rawLayer.layer], query: rawLayer.rawName },
+        });
+    }
+    /**
+     * Több magas-konfidenciájú kandidátus (nem egyértelmű) → `FAM-REF-RESOLVE-002` (dsgn-002 §4).
+     * DESKRIPTÍV: a token, a normalizált forma, a versengő kandidátusok + score, javaslat.
+     */
+    ambiguousError(rawLayer, candidates, minScore) {
+        const normalized = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(rawLayer.rawName);
+        const competing = candidates
+            .filter((candidate) => candidate.score >= minScore)
+            .slice(0, 4)
+            .map((candidate) => `${candidate.canonicalTerm} (${candidate.score.toFixed(2)})`)
+            .join(', ');
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.refResolveAmbiguous,
+            message: `A(z) '${rawLayer.layer}' layer '${rawLayer.rawName}' tokenje (normalizált: '${normalized}') `
+                + `több, közel azonos konfidenciájú scope-ra is illeszkedik: ${competing}. A feloldás nem egyértelmű. `
+                + 'Javaslat: adj meg egy pontosabb / explicit nevet, vagy egészítsd ki a scope-láncot a fölérendelt layerrel.',
+            issuer: this.issuer,
+            context: { operation: 'resolve-ambiguous', scopePath: [rawLayer.layer], query: rawLayer.rawName },
+        });
+    }
+    /** Egy `FAM_Scope_DataModel` → `FAM_ScopeRef` map. */
+    toScopeRef(scope) {
+        return {
+            scopeId: scope._id ?? '',
+            layer: scope.layer ?? '',
+            canonicalName: scope.canonicalName ?? '',
+        };
+    }
+}
+exports.FAM_ScopeResolver_ControlService = FAM_ScopeResolver_ControlService;