@futdevpro/fdp-agent-memory 1.1.21 → 1.1.112

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

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScopeMaintenance_Util = void 0;
+/**
+ * `FAM_ScopeMaintenance_Util` (user-FR 2026-06-22) — a **scope rename/merge** Mongo-update-specjeinek
+ * TISZTA (pure) felépítője. A scope-azonosító a denormalizált `scopePath[]`-en (minden RAG-entry) ÉS a
+ * reference `canonicalScopeRef`-jén (egyetlen objektum) szerepel; a rename/merge ezeket írja át bulk-ban.
+ *
+ * **Rename** = a `scopeId`-hez tartozó `canonicalName` átírása (a scopeId marad). **Merge** = a `from`
+ * scopeId minden előfordulása az `into` scope `{scopeId, layer, canonicalName}`-jére cserélve (majd a
+ * hívó soft-delete-eli a `from` scope-ot). A spec-építés determinisztikus + külön tesztelhető; az
+ * alkalmazás (mongoose `updateMany`) a control-service-ben.
+ */
+class FAM_ScopeMaintenance_Util {
+    /** RENAME — entry-collection (`scopePath[]`): a `scopeId`-elem `canonicalName`-jét `newName`-re. */
+    static renameEntryUpdate(scopeId, newName) {
+        return {
+            filter: { 'scopePath.scopeId': scopeId },
+            update: { $set: { 'scopePath.$[el].canonicalName': newName } },
+            arrayFilters: [{ 'el.scopeId': scopeId }],
+        };
+    }
+    /** MERGE — entry-collection (`scopePath[]`): a `fromId`-elemet az `into` ref `{scopeId,layer,canonicalName}`-jére. */
+    static mergeEntryUpdate(fromId, into) {
+        return {
+            filter: { 'scopePath.scopeId': fromId },
+            update: {
+                $set: {
+                    'scopePath.$[el].scopeId': into.scopeId,
+                    'scopePath.$[el].layer': into.layer,
+                    'scopePath.$[el].canonicalName': into.canonicalName,
+                },
+            },
+            arrayFilters: [{ 'el.scopeId': fromId }],
+        };
+    }
+    /** RENAME — reference (`canonicalScopeRef`, egyetlen objektum): a `canonicalName` átírása. */
+    static renameReferenceUpdate(scopeId, newName) {
+        return {
+            filter: { 'canonicalScopeRef.scopeId': scopeId },
+            update: { $set: { 'canonicalScopeRef.canonicalName': newName } },
+        };
+    }
+    /** MERGE — reference (`canonicalScopeRef`): a `from` ref cseréje az `into`-ra. */
+    static mergeReferenceUpdate(fromId, into) {
+        return {
+            filter: { 'canonicalScopeRef.scopeId': fromId },
+            update: {
+                $set: {
+                    'canonicalScopeRef.scopeId': into.scopeId,
+                    'canonicalScopeRef.layer': into.layer,
+                    'canonicalScopeRef.canonicalName': into.canonicalName,
+                },
+            },
+        };
+    }
+    /**
+     * RESET — egy scope (scan-eredetű) entry-jeinek TÖRLÉS-szűrője (PURE, user-FR 2026-06-24 — recovery
+     * egy félre-routolt scan után). A `source.type` default `'scan'` → a manuális/agent/import-SZERZETT
+     * (pótolhatatlan) tartalmat SOHA nem törli (csak az újra-szkennelhető scan-chunkokat). Opcionális
+     * `sourceRootContains` SUBSTRING-szűrés a `source.root`-on (case-insensitive, literál-escape-elve) — a
+     * cross-root szennyezés SEBÉSZI eltávolításához: pl. a `ccap-revisioned` gyökerű entry-k a `ccap-client`
+     * scope-ból, a `ccap` saját entry-jeinek MEGTARTÁSÁVAL. `sourceRootContains` nélkül a scope MINDEN
+     * scan-entry-je (a teljes reset).
+     */
+    static buildResetFilter(set) {
+        const filter = { 'scopePath.scopeId': set.scopeId };
+        const sourceType = (set.sourceType ?? 'scan').trim();
+        if (sourceType) {
+            filter['source.type'] = sourceType;
+        }
+        const needle = (set.sourceRootContains ?? '').trim();
+        if (needle) {
+            filter['source.root'] = { $regex: FAM_ScopeMaintenance_Util.escapeRegex(needle), $options: 'i' };
+        }
+        return filter;
+    }
+    /** Regex-metakarakter escape (PURE): a substring-szűrőt LITERÁLKÉNT illeszti (nincs véletlen regex-tágítás). */
+    static escapeRegex(value) {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * `buildMergeSuggestions(groups)` (scope-prevenció, user-FR 2026-06-22) — TISZTA logika: a detektált
+     * duplikátum-csoportokból konkrét, futtatható `merge_scopes from→into` direktívák. A csoportonkénti `into`
+     * a **kanonikus** (megtartandó) scope: (1) preferáltan a parented (= tipikusan scan-eredetű, org-fán lóg),
+     * (2) azon belül/különben a LEGTÖBB entry-jű (a legtöbb tudást hordozó). A többi tag → `from` (átpontozandó).
+     *
+     * **Prioritás:** a `'repo-key'` csoportok ELŐBB (ez a legbiztosabb identitás — a KÜLÖNBÖZŐ nevű, AZONOS repo
+     * eseteket is elkapja), majd a `'name'` csoportok. Egy `from` scope CSAK EGYSZER javasolt (a már elköltött
+     * scope-okat — akár from, akár egy korábbi into — kihagyjuk → nincs ütköző/körkörös merge). Determinisztikus
+     * (entryCount-, majd scopeId-rendezés). NEM mutál — csak javaslat; az alkalmazás a `mergeScopes` (dryRun).
+     */
+    static buildMergeSuggestions(groups) {
+        const suggestions = [];
+        const consumed = new Set();
+        // A 'repo-key' csoportok előbb (biztosabb identitás), majd a 'name'.
+        const ordered = groups.slice().sort((a, b) => (a.groupKind === b.groupKind ? 0 : (a.groupKind === 'repo-key' ? -1 : 1)));
+        for (const group of ordered) {
+            const available = group.members.filter((member) => !consumed.has(member.scopeId));
+            if (available.length < 2) {
+                continue;
+            }
+            const into = FAM_ScopeMaintenance_Util.chooseMergeInto(available);
+            consumed.add(into.scopeId);
+            for (const member of available) {
+                if (member.scopeId === into.scopeId || consumed.has(member.scopeId)) {
+                    continue;
+                }
+                consumed.add(member.scopeId);
+                suggestions.push({
+                    from: { scopeId: member.scopeId, canonicalName: member.canonicalName },
+                    into: { scopeId: into.scopeId, canonicalName: into.canonicalName },
+                    reason: group.groupKind === 'repo-key'
+                        ? `Azonos kanonikus repo-kulcs ('${group.key}') — különböző nevű scope-ok ugyanarra a repóra mutatnak.`
+                        : `Azonos (layer|név) duplikátum ('${group.key}') — a parented/nagyobb scope a megtartandó.`,
+                    fromEntryCount: member.entryCount,
+                    intoEntryCount: into.entryCount,
+                });
+            }
+        }
+        return suggestions;
+    }
+    /**
+     * A megtartandó (`into`) scope kiválasztása egy duplikátum-csoportból (PURE): preferáltan a parented (van
+     * `parentScopeId` — az org-fán lógó, tipikusan scan-eredetű), azon belül/különben a LEGTÖBB entry-jű; döntetlen
+     * → a kisebb `scopeId` (determinizmus). A csoportnak legalább 1 tagja kell legyen.
+     */
+    static chooseMergeInto(members) {
+        const parented = members.filter((member) => !!member.parentScopeId);
+        const pool = parented.length ? parented : members;
+        return pool.slice().sort((a, b) => (b.entryCount - a.entryCount) || a.scopeId.localeCompare(b.scopeId))[0];
+    }
+}
+exports.FAM_ScopeMaintenance_Util = FAM_ScopeMaintenance_Util;

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

@@ -0,0 +1,423 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ScopeMaintenance_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+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 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");
+const fam_scope_maintenance_util_1 = require("../_collections/fam-scope-maintenance.util");
+/**
+ * `FAM_ScopeMaintenance_ControlService` (user-FR 2026-06-22) — **scope rename + merge** maintenance-engine.
+ * A claude-mem import (és egyéb) rendetlen scope-neveit (pl. `10.3.3` → valójában ccap-revisioned) rendezi:
+ * a `canonicalName`-t a denormalizált `scopePath[]`-en (MINDEN RAG-entry) + a reference `canonicalScopeRef`-jén
+ * + a scope-doc-on bulk-ban átírja (rename), VAGY egy scope-ot egy másikba olvaszt (merge → a forrás-scope
+ * minden entry-je az `into`-ra mutat, majd a forrás-scope soft-delete).
+ *
+ * **dryRun (default true a destruktív-biztonsághoz):** csak az érintett-számokat adja vissza, NEM ír. A
+ * tényleges íráshoz `dryRun:false` explicit. A bulk array-update mongoose `updateMany` + `arrayFilters` (a spec
+ * a tiszta `FAM_ScopeMaintenance_Util`-ból). A LVS-pool a Mongo-ból hidratál → a változás a következő (vagy
+ * scope-scoped) keresésnél él; nagy átírás után szerver-restart ajánlott a pool friss scope-metaadatához.
+ *
+ * **Megjegyzés (dedup):** a merge NEM dedup-ol — ha az `into` és a `from` ugyanazt a tartalmat tartalmazta,
+ * a `deduplicate_entries` (külön capability) felel a content-hash-összevonásért.
+ */
+class FAM_ScopeMaintenance_ControlService {
+    static _instance;
+    issuer = 'FAM_ScopeMaintenance_ControlService';
+    static getInstance() {
+        if (!FAM_ScopeMaintenance_ControlService._instance) {
+            FAM_ScopeMaintenance_ControlService._instance = new FAM_ScopeMaintenance_ControlService();
+        }
+        return FAM_ScopeMaintenance_ControlService._instance;
+    }
+    /**
+     * Egy scope ÁTNEVEZÉSE: a `scopeId` `canonicalName`-jét `newName`-re — a scopeId VÁLTOZATLAN, csak a
+     * denormalizált név (entry-k `scopePath` + reference + scope-doc). `dryRun` → csak az érintett-szám.
+     */
+    async renameScope(set) {
+        const newName = (set.newName ?? '').trim();
+        if (!newName) {
+            throw this.invalid('A `newName` (nem-üres string) KÖTELEZŐ a rename_scope-hoz.', 'rename_scope');
+        }
+        const scope = await this.resolveScope(set);
+        const scopeId = scope._id;
+        const dryRun = set.dryRun !== false;
+        const affected = await this.countAffected(scopeId);
+        if (!dryRun) {
+            const entryUpdate = fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.renameEntryUpdate(scopeId, newName);
+            await this.applyEntryUpdate(entryUpdate);
+            const refUpdate = fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.renameReferenceUpdate(scopeId, newName);
+            await this.referenceCollection().collection.updateMany(refUpdate.filter, refUpdate.update);
+            // A scope-doc canonicalName-je ($set, atomikus — a denormalizált forrás).
+            await new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer })
+                .updateData({ filterBy: { _id: scopeId }, update: { $set: { canonicalName: newName } } });
+        }
+        return {
+            operation: 'rename_scope',
+            dryRun: dryRun,
+            scope: { scopeId: scopeId, layer: scope.layer ?? '', oldName: scope.canonicalName ?? '', newName: newName },
+            affected: affected,
+            totalAffected: affected.reduce((sum, item) => sum + item.count, 0),
+        };
+    }
+    /**
+     * Két scope ÖSSZEOLVASZTÁSA: a `from` scope minden entry-je az `into` scope `{scopeId,layer,canonicalName}`-jére
+     * mutat, majd a `from` scope soft-delete. `dryRun` → csak az érintett-szám. Az `into` MARAD.
+     */
+    async mergeScopes(set) {
+        const from = await this.resolveScope(set.from);
+        const into = await this.resolveScope(set.into);
+        const fromId = from._id;
+        const intoId = into._id;
+        if (fromId === intoId) {
+            throw this.invalid('A `from` és az `into` ugyanaz a scope — nincs mit összeolvasztani.', 'merge_scopes');
+        }
+        const dryRun = set.dryRun !== false;
+        const intoRef = { scopeId: intoId, layer: into.layer ?? '', canonicalName: into.canonicalName ?? '' };
+        const affected = await this.countAffected(fromId);
+        // MERGE-GUARD (2026-06-24 fix): külön projekt-gyökerek (`source.root`) → gyaníthatóan KÜLÖN projektek →
+        // BLOKK (force nélkül). Ez fogja meg a téves repoKey-duplikátum-merge-et (a `ccap-revisioned`→`ccap-speech-
+        // recognition` típusú szennyezést), MIELŐTT 50k fájl átkeveredne. A `force:true` (tudatos user-akció) felülírja.
+        const blockedReason = set.force
+            ? undefined
+            : await this.crossProjectMergeBlock(fromId, intoId, from.canonicalName ?? '', into.canonicalName ?? '');
+        if (blockedReason) {
+            return {
+                operation: 'merge_scopes', dryRun: dryRun, blockedReason: blockedReason,
+                from: { scopeId: fromId, layer: from.layer ?? '', canonicalName: from.canonicalName ?? '' },
+                into: intoRef, affected: affected, totalAffected: affected.reduce((s, i) => s + i.count, 0),
+                fromScopeDeleted: false,
+            };
+        }
+        if (!dryRun) {
+            const entryUpdate = fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.mergeEntryUpdate(fromId, intoRef);
+            await this.applyEntryUpdate(entryUpdate);
+            const refUpdate = fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.mergeReferenceUpdate(fromId, intoRef);
+            await this.referenceCollection().collection.updateMany(refUpdate.filter, refUpdate.update);
+            // A forrás-scope soft-delete (move-to-archive) — már nincs rá hivatkozó entry.
+            await new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer }).deleteData(fromId);
+        }
+        return {
+            operation: 'merge_scopes',
+            dryRun: dryRun,
+            from: { scopeId: fromId, layer: from.layer ?? '', canonicalName: from.canonicalName ?? '' },
+            into: { scopeId: intoId, layer: into.layer ?? '', canonicalName: into.canonicalName ?? '' },
+            affected: affected,
+            totalAffected: affected.reduce((sum, item) => sum + item.count, 0),
+            fromScopeDeleted: !dryRun,
+        };
+    }
+    /**
+     * Egy scope SCAN-eredetű entry-jeinek soft-delete-je (RECOVERY egy félre-routolt scan után, user-FR 2026-06-24).
+     * A `sourceType` default `'scan'` → a manuális/agent/import-SZERZETT (pótolhatatlan) tartalmat SOHA nem törli.
+     * Az opcionális `sourceRootContains` a `source.root`-ot szűri (sebészi cross-root takarítás: pl. a `ccap-revisioned`
+     * gyökerű szennyezés a `ccap-client` scope-ból, a `ccap` saját entry-jeinek megtartásával). `dryRun` (DEFAULT true)
+     * → csak a per-collection szám + a `rootSamples` (verifikáció: jó scope-ot/gyökeret törlünk-e), NEM ír. A tényleges
+     * (soft-delete + LVS-pool-kivétel) az explicit `dryRun:false`. A scan-tartalom ÚJRA-SZKENNELHETŐ → nem destruktív-végleges.
+     */
+    async resetScope(set) {
+        const scope = await this.resolveScope(set);
+        const scopeId = scope._id;
+        const dryRun = set.dryRun !== false;
+        const sourceType = (set.sourceType ?? 'scan').trim();
+        const sourceRootContains = (set.sourceRootContains ?? '').trim() || undefined;
+        const tableName = (set.table ?? '').trim() || undefined;
+        const filter = {
+            ...fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.buildResetFilter({ scopeId: scopeId, sourceType: sourceType, sourceRootContains: sourceRootContains }),
+            _deleted: null, // csak az AKTÍV (nem már soft-deleted) entry-ket (a `_deleted` Date-mező; `null` = aktív/hiányzó).
+        };
+        const targets = tableName
+            ? (embedding_1.FAM_StoreRegistry_Util.getEntry(tableName) ? [embedding_1.FAM_StoreRegistry_Util.getEntry(tableName)] : [])
+            : embedding_1.FAM_STORE_REGISTRY;
+        const affected = [];
+        const rootSamples = new Set();
+        let totalAffected = 0;
+        for (const registryEntry of targets) {
+            // A példányosítás regisztrálja a modellt → a valós collection (a raw find a soft-delete-szemantikát explicit kezeli).
+            new embedding_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+            const collection = mongoose_1.default.models[registryEntry.dataParams.dataName]?.collection;
+            if (!collection) {
+                continue;
+            }
+            const matched = await collection.find(filter, { projection: { 'source.root': 1 } }).toArray();
+            for (const entry of matched) {
+                const root = entry.source?.root;
+                if (root && rootSamples.size < 8) {
+                    rootSamples.add(root);
+                }
+            }
+            if (!dryRun && matched.length) {
+                // BULK soft-delete (DIREKT `_deleted` — NEM `deleteData`): a FAM entry-tárak `addArchive:true`-ok, így a
+                // per-entry `deleteData` minden törölt entry-ből ARCHÍV-másolatot készítene (bloat + lassú 59k-ra). A reset
+                // DISCARD (nem archive) → közvetlen `_deleted` (Date), amit a `_deleted: null` aktív-szűrő kizár; a hívás
+                // utáni restart tiszta (a soft-deletedek nélküli) poolt hidratál. A live pool-coherence: in-memory removeVector.
+                await collection.updateMany(filter, { $set: { _deleted: new Date() } });
+                for (const entry of matched) {
+                    embedding_1.FAM_VectorSearch_ControlService.getInstance().removeVector(registryEntry.table, String(entry._id));
+                }
+            }
+            affected.push({ collection: collection.collectionName, count: matched.length });
+            totalAffected += matched.length;
+        }
+        return {
+            operation: 'reset_scope',
+            dryRun: dryRun,
+            scope: { scopeId: scopeId, layer: scope.layer ?? '', canonicalName: scope.canonicalName ?? '' },
+            sourceType: sourceType,
+            sourceRootContains: sourceRootContains,
+            tableFilter: tableName,
+            affected: affected,
+            totalAffected: totalAffected,
+            rootSamples: [...rootSamples],
+        };
+    }
+    /** Az `entryUpdate` spec alkalmazása MINDEN fő RAG-tár collection-jén (mongoose `updateMany` + arrayFilters). */
+    async applyEntryUpdate(entryUpdate) {
+        for (const named of this.entryCollections()) {
+            await named.collection.updateMany(entryUpdate.filter, entryUpdate.update, { arrayFilters: entryUpdate.arrayFilters });
+        }
+    }
+    /** Egy scope entry-jeinek DISTINCT `source.root` halmaza minden fő tárban (a merge-guard bemenete). Normalizált (lowercase, `/`). */
+    async distinctRootsForScope(scopeId) {
+        const roots = new Set();
+        for (const named of this.entryCollections()) {
+            const values = await named.collection.distinct('source.root', { 'scopePath.scopeId': scopeId, _deleted: { $ne: true } });
+            for (const value of values) {
+                if (typeof value === 'string' && value.trim()) {
+                    roots.add(value.trim().toLowerCase().replace(/\\/g, '/'));
+                }
+            }
+        }
+        return roots;
+    }
+    /**
+     * MERGE-GUARD mag (2026-06-24 fix): blokk-ok-szöveg, ha a `from` és az `into` scope entry-jei KÜLÖNBÖZŐ (disjunkt)
+     * projekt-gyökerekből származnak — vagyis a merge KÜLÖN projekteket keverne. `undefined` (engedélyezve), ha bármelyik
+     * oldalon NINCS root-infó (manuális/importált entry — nem dönthető el), VAGY ha van KÖZÖS gyökér (ugyanaz a projekt,
+     * pl. átnevezés-merge legit). Ez fogja meg a téves repoKey-duplikátum-merge-et a tartalom-átkeveredés ELŐTT.
+     */
+    async crossProjectMergeBlock(fromId, intoId, fromName, intoName) {
+        const [fromRoots, intoRoots] = await Promise.all([this.distinctRootsForScope(fromId), this.distinctRootsForScope(intoId)]);
+        if (!fromRoots.size || !intoRoots.size) {
+            return undefined; // nincs root-infó → nem blokkolunk (nem dönthető el biztosan)
+        }
+        const overlap = [...fromRoots].some((root) => intoRoots.has(root));
+        if (overlap) {
+            return undefined; // van közös projekt-gyökér → ugyanaz a projekt (legit merge)
+        }
+        const sample = (set) => [...set].slice(0, 3).join(', ');
+        return `A(z) '${fromName}' és '${intoName}' scope entry-jei KÜLÖNBÖZŐ projekt-gyökerekből származnak `
+            + `(from: ${sample(fromRoots)} | into: ${sample(intoRoots)}) — gyaníthatóan KÜLÖN projektek, a merge `
+            + `összekeverné a tartalmukat. Blokkolva (a téves repoKey-duplikátum-szennyezés ellen). `
+            + `Ha tényleg össze akarod olvasztani: force:true.`;
+    }
+    /** A `scopeId`-t hivatkozó aktív entry-k száma per-collection (a 6 fő tár + a reference). */
+    /**
+     * Scope-integritás SELF-CHECK (user-FR 2026-06-22 — a rendszer ismerje fel magától a problémás scope-okat):
+     * (a) **árva projekt-scope** (`layer='project'`, de nincs `parentScopeId` — tipikusan import-eredetű lapos scope,
+     * a scan org-parented párja mellett), (b) **duplikátum** (ugyanaz a `(canonicalName, layer)` többször). Mindkettőhöz
+     * az entry-számot is adja (a merge-döntéshez: a parented/nagyobb az `into`). Csak OLVAS — a takarítás `merge_scopes`.
+     */
+    async detectIssues() {
+        const scopes = await this.scopeCollection().collection
+            .find({}, { projection: { canonicalName: 1, layer: 1, parentScopeId: 1, canonicalRepoKey: 1 } })
+            .toArray();
+        // Az entry-számokat EGYSZER számoljuk minden érintett scope-ra (a 3 csoport megosztja — nincs dupla countDocuments).
+        const entryCountCache = new Map();
+        const countFor = async (scopeId) => {
+            if (!entryCountCache.has(scopeId)) {
+                entryCountCache.set(scopeId, await this.totalEntryCount(scopeId));
+            }
+            return entryCountCache.get(scopeId);
+        };
+        const orphanProjectScopes = [];
+        const byNameKey = new Map();
+        const byRepoKey = new Map();
+        const pushTo = (map, key, scope) => {
+            const bucket = map.get(key) ?? [];
+            bucket.push(scope);
+            map.set(key, bucket);
+        };
+        for (const scope of scopes) {
+            pushTo(byNameKey, `${scope.layer ?? ''}|${scope.canonicalName ?? ''}`, scope);
+            const repoKey = (scope.canonicalRepoKey ?? '').trim().toLowerCase();
+            if (repoKey) {
+                pushTo(byRepoKey, repoKey, scope);
+            }
+            if (scope.layer === 'project' && !scope.parentScopeId) {
+                orphanProjectScopes.push({
+                    scopeId: String(scope._id), canonicalName: scope.canonicalName ?? '',
+                    entryCount: await countFor(String(scope._id)),
+                });
+            }
+        }
+        const toMember = async (scope) => ({
+            scopeId: String(scope._id), parentScopeId: scope.parentScopeId,
+            canonicalName: scope.canonicalName ?? '', canonicalRepoKey: scope.canonicalRepoKey,
+            entryCount: await countFor(String(scope._id)),
+        });
+        const duplicateScopes = [];
+        for (const [, group] of byNameKey) {
+            if (group.length <= 1) {
+                continue;
+            }
+            const members = [];
+            for (const scope of group) {
+                members.push(await toMember(scope));
+            }
+            duplicateScopes.push({ canonicalName: group[0].canonicalName ?? '', layer: group[0].layer ?? '', members: members });
+        }
+        const repoKeyDuplicates = [];
+        for (const [repoKey, group] of byRepoKey) {
+            // Egyedi scopeId-k (ugyanaz a scope ne számítson kétszer); ≥2 KÜLÖNBÖZŐ scope = repo-kulcs-duplikátum.
+            const uniqueIds = new Set(group.map((scope) => String(scope._id)));
+            if (uniqueIds.size <= 1) {
+                continue;
+            }
+            const members = [];
+            for (const scope of group) {
+                members.push(await toMember(scope));
+            }
+            repoKeyDuplicates.push({ canonicalRepoKey: repoKey, members: members });
+        }
+        return {
+            scopesScanned: scopes.length,
+            orphanProjectScopes: orphanProjectScopes,
+            duplicateScopes: duplicateScopes,
+            repoKeyDuplicates: repoKeyDuplicates,
+            hasIssues: orphanProjectScopes.length > 0 || duplicateScopes.length > 0 || repoKeyDuplicates.length > 0,
+        };
+    }
+    /**
+     * `suggestMerges()` (scope-prevenció, user-FR 2026-06-22) — a `detectIssues` által felismert duplikátumokból
+     * KONKRÉT, futtatható `merge_scopes from→into` direktívák (pure `buildMergeSuggestions`). A repo-kulcs-csoportok
+     * elsőbbséget élveznek (a legbiztosabb identitás), az `into` a parented/legtöbb-entry-jű scope. NEM mutál — a
+     * tényleges összeolvasztás a `mergeScopes` (dryRun-default). Ez teszi az auto-felismerést AKCIONÁLHATÓVÁ.
+     */
+    async suggestMerges() {
+        const report = await this.detectIssues();
+        const groups = [
+            ...report.repoKeyDuplicates.map((duplicate) => ({
+                groupKind: 'repo-key', key: duplicate.canonicalRepoKey,
+                members: duplicate.members.map((member) => this.toMergeMember(member)),
+            })),
+            ...report.duplicateScopes.map((duplicate) => ({
+                groupKind: 'name', key: `${duplicate.layer}|${duplicate.canonicalName}`,
+                members: duplicate.members.map((member) => this.toMergeMember(member, duplicate.canonicalName, duplicate.layer)),
+            })),
+        ];
+        return { suggestions: fam_scope_maintenance_util_1.FAM_ScopeMaintenance_Util.buildMergeSuggestions(groups), report: report };
+    }
+    /** Egy issue-member → merge-member (a name-csoportban a közös név/layer pótlása, ha a member nem hordozza). */
+    toMergeMember(member, fallbackName, layer) {
+        return {
+            scopeId: member.scopeId,
+            canonicalName: member.canonicalName ?? fallbackName ?? '',
+            layer: layer,
+            parentScopeId: member.parentScopeId,
+            entryCount: member.entryCount,
+            canonicalRepoKey: member.canonicalRepoKey,
+        };
+    }
+    /** Egy scope összes entry-száma a 6 fő tárban (a detekció merge-súlyozásához). */
+    async totalEntryCount(scopeId) {
+        let total = 0;
+        for (const named of this.entryCollections()) {
+            total += await named.collection.countDocuments({ 'scopePath.scopeId': scopeId });
+        }
+        return total;
+    }
+    /** A `fam_scopes` mongoose-collection-je (a DS-példányosítás regisztrálja a modellt). */
+    scopeCollection() {
+        new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const model = mongoose_1.default.models['fam_scopes'];
+        return { name: model?.collection?.collectionName ?? 'fam_scopes', collection: model.collection };
+    }
+    async countAffected(scopeId) {
+        const affected = [];
+        for (const named of this.entryCollections()) {
+            affected.push({ collection: named.name, count: await named.collection.countDocuments({ 'scopePath.scopeId': scopeId }) });
+        }
+        const reference = this.referenceCollection();
+        affected.push({ collection: reference.name, count: await reference.collection.countDocuments({ 'canonicalScopeRef.scopeId': scopeId }) });
+        return affected;
+    }
+    /** A 6 fő RAG-tár mongoose-collection-jei (a DS-példányosítás regisztrálja a modellt, onnan a valós collection). */
+    entryCollections() {
+        const result = [];
+        for (const entry of embedding_1.FAM_STORE_REGISTRY) {
+            new embedding_1.FAM_Entry_DataService({ dataParams: entry.dataParams, issuer: this.issuer });
+            const model = mongoose_1.default.models[entry.dataParams.dataName];
+            if (model?.collection) {
+                result.push({ name: model.collection.collectionName, collection: model.collection });
+            }
+        }
+        return result;
+    }
+    /** A reference helper-tár mongoose-collection-je. */
+    referenceCollection() {
+        new fam_reference_data_service_1.FAM_Reference_DataService({ issuer: this.issuer });
+        const model = mongoose_1.default.models['fam_reference'];
+        return { name: model?.collection?.collectionName ?? 'fam_references', collection: model.collection };
+    }
+    /**
+     * Egy scope feloldása a szelektorból: `scopeId` (közvetlen) VAGY `layer`+`canonicalName` (egyértelmű) VAGY
+     * csak `canonicalName` (minden layer-en, normalizált-egyezés — egyértelmű kell legyen). Nem-talált/kétértelmű → hiba.
+     */
+    async resolveScope(selector) {
+        const dataService = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        if (selector.scopeId) {
+            const scope = await dataService.findScopeById(selector.scopeId);
+            if (scope?._id) {
+                return scope;
+            }
+            throw this.notFound(`scopeId '${selector.scopeId}'`);
+        }
+        if (selector.canonicalName) {
+            const matches = selector.layer
+                ? await dataService.findByCanonical(selector.layer, selector.canonicalName)
+                : await this.findByNameAnyLayer(dataService, selector.canonicalName);
+            if (matches.length === 1) {
+                return matches[0];
+            }
+            if (matches.length > 1) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.refResolveAmbiguous,
+                    message: `A(z) '${selector.canonicalName}' név több scope-ra illeszkedik (${matches.length}) — adj meg `
+                        + '`layer`-t vagy `scopeId`-t az egyértelműsítéshez.',
+                    issuer: this.issuer,
+                    context: { operation: 'scope-maintenance:resolve' },
+                });
+            }
+            throw this.notFound(`'${selector.canonicalName}'${selector.layer ? ` (layer '${selector.layer}')` : ''}`);
+        }
+        throw this.invalid('Add meg a scope-ot: `scopeId` VAGY `canonicalName` (+ opcionális `layer`).', 'resolve-scope');
+    }
+    /** Egy név normalizált-egyezése MINDEN aktív scope-on (layer nélkül; a halmaz kicsi). */
+    async findByNameAnyLayer(dataService, name) {
+        const all = await dataService.findAllActive();
+        const target = fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(name);
+        return all.filter((scope) => fam_scope_normalize_util_1.FAM_ScopeNormalize_Util.normalize(scope.canonicalName ?? '') === target);
+    }
+    notFound(what) {
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.refResolveNoMatch,
+            message: `Nincs aktív scope: ${what}.`,
+            issuer: this.issuer,
+            context: { operation: 'scope-maintenance:resolve' },
+        });
+    }
+    invalid(message, operation) {
+        return fam_error_factory_util_1.FAM_Error_Util.create({
+            errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+            message: message,
+            issuer: this.issuer,
+            context: { operation: `scope-maintenance:${operation}` },
+        });
+    }
+}
+exports.FAM_ScopeMaintenance_ControlService = FAM_ScopeMaintenance_ControlService;

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

@@ -409,7 +409,7 @@ class FAM_ScopeResolver_ControlService {
         }
         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);
+        return Boolean(scope?._id);
     }
     // =========================================================================
     // TRACE (dsgn-002 §4, dsgn-003 §4.2) — a debug-capability (MP-6) fogyasztja
@@ -460,7 +460,7 @@ class FAM_ScopeResolver_ControlService {
     async traceEntityFallback(rawLayer, scopeDataService) {
         const matches = await scopeDataService.findByCanonical(rawLayer.layer, rawLayer.rawName);
         const hit = matches.find((scope) => !!scope._id);
-        if (hit && hit._id) {
+        if (hit?._id) {
             return { matched: true, scopeId: hit._id, canonicalName: hit.canonicalName };
         }
         return { matched: false };

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

@@ -211,5 +211,30 @@ class FAM_Scope_DataService extends nts_dynamo_1.DyNTS_DataService {
     async setAliases(scopeId, aliases) {
         await this.updateData({ filterBy: { _id: scopeId }, update: { $set: { aliases: aliases } } });
     }
+    /**
+     * A scope `canonicalRepoKey` stamp-elése (scope-prevenció, user-FR 2026-06-22; `$set`, atomikus). A SCAN
+     * hívja a project-layer scope-ra a felismert git/package identitásból — erre épül a repo-kulcs alapú
+     * duplikátum-detekció. Csak nem-üres kulcsot ír; idempotens (ugyanaz a kulcs újraírása no-op-szerű).
+     */
+    async setCanonicalRepoKey(scopeId, canonicalRepoKey) {
+        const key = (canonicalRepoKey ?? '').trim();
+        if (!scopeId || !key) {
+            return;
+        }
+        await this.updateData({ filterBy: { _id: scopeId }, update: { $set: { canonicalRepoKey: key } } });
+    }
+    /**
+     * `findByRepoKey(canonicalRepoKey)` (scope-prevenció) — egy kanonikus repo-kulcsra illeszkedő összes aktív
+     * scope (case-insensitive trim-egyezés). ≥2 találat = repo-kulcs-duplikátum (a `detectIssues` merge-jelölt).
+     * A halmaz kicsi → in-memory szűrés.
+     */
+    async findByRepoKey(canonicalRepoKey) {
+        const target = (canonicalRepoKey ?? '').trim().toLowerCase();
+        if (!target) {
+            return [];
+        }
+        const all = await this.findAllActive();
+        return all.filter((scope) => (scope.canonicalRepoKey ?? '').trim().toLowerCase() === target);
+    }
 }
 exports.FAM_Scope_DataService = FAM_Scope_DataService;

package/build/src/_modules/scope-reference/index.js

@@ -9,7 +9,7 @@
  * a fogyasztó-MP-ké. A reference/scope collection-ök MP-1-ben már a `dbModels`-ben vannak.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_FuzzyMatch_Util = exports.FAM_ScopeNormalize_Util = exports.FAM_ScopeResolver_ControlService = exports.FAM_Reference_DataService = exports.FAM_Scope_DataService = void 0;
+exports.FAM_FuzzyMatch_Util = exports.FAM_ScopeNormalize_Util = exports.FAM_ScopeMaintenance_ControlService = exports.FAM_ScopeResolver_ControlService = exports.FAM_Reference_DataService = exports.FAM_Scope_DataService = void 0;
 // SP-3.1 — Scope CRUD + scope-fa traverzál
 var fam_scope_data_service_1 = require("./_services/fam-scope.data-service");
 Object.defineProperty(exports, "FAM_Scope_DataService", { enumerable: true, get: function () { return fam_scope_data_service_1.FAM_Scope_DataService; } });
@@ -19,6 +19,9 @@ Object.defineProperty(exports, "FAM_Reference_DataService", { enumerable: true,
 // SP-3.3/SP-3.4 — a feloldó control-service (write-resolve / read-expand / cache / scopeExists / uncertainty)
 var fam_scope_resolver_control_service_1 = require("./_services/fam-scope-resolver.control-service");
 Object.defineProperty(exports, "FAM_ScopeResolver_ControlService", { enumerable: true, get: function () { return fam_scope_resolver_control_service_1.FAM_ScopeResolver_ControlService; } });
+// user-FR 2026-06-22 — scope rename/merge maintenance (rendetlen claude-mem import scope-nevek rendezése)
+var fam_scope_maintenance_control_service_1 = require("./_services/fam-scope-maintenance.control-service");
+Object.defineProperty(exports, "FAM_ScopeMaintenance_ControlService", { enumerable: true, get: function () { return fam_scope_maintenance_control_service_1.FAM_ScopeMaintenance_ControlService; } });
 // utils (SP-3.1/SP-3.2)
 var fam_scope_normalize_util_1 = require("./_collections/fam-scope-normalize.util");
 Object.defineProperty(exports, "FAM_ScopeNormalize_Util", { enumerable: true, get: function () { return fam_scope_normalize_util_1.FAM_ScopeNormalize_Util; } });