@futdevpro/fdp-agent-memory 1.1.122 → 1.1.133

package/build/src/_modules/embedding/_services/fam-dup-coverage.control-service.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupCoverage_ControlService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_scope_data_service_1 = require("../../scope-reference/_services/fam-scope.data-service");
+const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_entry_data_service_1 = require("./fam-entry.data-service");
+/**
+ * `FAM_DupCoverage_ControlService` (dup-v2, task #20) — a duplikáció-mérés **lefedettség-preflight**-je. A
+ * dup-eredmény csak akkor értelmezhető flotta-szinten, ha tudjuk, MELY projektek korpusza hiányzik (0 entry)
+ * vagy elavult (régen szkennelt) — különben a „nincs duplikáció X-szel" néma hamis-negatív. A riport a scope-fa
+ * project-layer listáját veti össze a tár per-projekt entry-számával + a legfrissebb entry korával. Read-only.
+ */
+class FAM_DupCoverage_ControlService {
+    static _instance;
+    issuer = 'FAM_DupCoverage_ControlService';
+    /** Az elavultság-küszöb napban: a heti re-scan (7 nap) + 1 nap türelem. */
+    static STALE_WARN_DAYS = 8;
+    static getInstance() {
+        if (!FAM_DupCoverage_ControlService._instance) {
+            FAM_DupCoverage_ControlService._instance = new FAM_DupCoverage_ControlService();
+        }
+        return FAM_DupCoverage_ControlService._instance;
+    }
+    /**
+     * A lefedettség-riport egy tárra (default `codebase`). A scope-fa project-layer listája + egy per-projekt
+     * `$group` aggregáció (aktív entry-szám + max lastModified), majd a PURE `joinCoverage` join. Üres tár /
+     * üres scope-fa → deskriptív riport (nem dob).
+     */
+    async report(table = fam_table_type_enum_1.FAM_Table.codebase) {
+        const registryEntry = fam_store_registry_const_1.FAM_StoreRegistry_Util.getEntry(table);
+        // A scope-fa project-layer canonical nevei (a „mit KELLENE lefedni" referencia-lista).
+        const scope_DS = new fam_scope_data_service_1.FAM_Scope_DataService({ issuer: this.issuer });
+        const scopes = await scope_DS.findAllActive();
+        const projectNames = [...new Set(scopes
+                .filter((scope) => scope.layer === 'project' && scope.canonicalName)
+                .map((scope) => scope.canonicalName))].sort();
+        // Per-projekt aggregáció a RAW collection-ön (aktív = `_deleted:null`; a lastModified a `__lastModified`
+        // vagy fallback a `__created`). A contentVector SOHA nem kerül a pipeline-ba (memória-védelem).
+        let rows = [];
+        if (registryEntry) {
+            const collection = this.entryCollection(registryEntry);
+            rows = await collection.aggregate([
+                { $match: { _deleted: null } },
+                {
+                    $project: {
+                        project: {
+                            $arrayElemAt: [{
+                                    $map: {
+                                        input: {
+                                            $filter: {
+                                                input: { $ifNull: ['$scopePath', []] },
+                                                as: 'ref',
+                                                cond: { $eq: ['$$ref.layer', 'project'] },
+                                            },
+                                        },
+                                        as: 'ref',
+                                        in: '$$ref.canonicalName',
+                                    },
+                                }, 0],
+                        },
+                        lm: { $ifNull: ['$__lastModified', '$__created'] },
+                    },
+                },
+                { $group: { _id: '$project', entryCount: { $sum: 1 }, lastModified: { $max: '$lm' } } },
+            ], { allowDiskUse: true }).toArray();
+        }
+        return FAM_DupCoverage_ControlService.joinCoverage({
+            table: table, projectNames: projectNames, rows: rows, nowMs: Date.now(),
+        });
+    }
+    /**
+     * **PURE** join: a scope-fa projekt-listája × a per-projekt aggregáció-sorok → lefedettség-riport
+     * (zero-entry + stale jelzésekkel + warnings). Determinista → unit-tesztelhető DB nélkül.
+     */
+    static joinCoverage(set) {
+        const staleThresholdMs = FAM_DupCoverage_ControlService.STALE_WARN_DAYS * 24 * 3600000;
+        const byProject = new Map();
+        for (const row of set.rows) {
+            if (row._id) {
+                byProject.set(row._id, row);
+            }
+        }
+        const projects = set.projectNames.map((project) => {
+            const row = byProject.get(project);
+            const lastModifiedMs = row?.lastModified ? new Date(row.lastModified).getTime() : 0;
+            return {
+                project: project,
+                entryCount: row?.entryCount ?? 0,
+                lastModifiedMs: lastModifiedMs,
+                stale: Boolean(row?.entryCount) && (set.nowMs - lastModifiedMs) > staleThresholdMs,
+            };
+        }).sort((left, right) => right.entryCount - left.entryCount || left.project.localeCompare(right.project));
+        const zeroEntryProjects = projects.filter((row) => !row.entryCount).map((row) => row.project);
+        const staleProjects = projects.filter((row) => row.stale).map((row) => row.project);
+        const warnings = [];
+        if (zeroEntryProjects.length) {
+            warnings.push(`${zeroEntryProjects.length} projekt 0 entry-vel a '${set.table}' tárban — ezek a dup-mérésből `
+                + `NÉMÁN kimaradnak (futtass scant): ${zeroEntryProjects.join(', ')}`);
+        }
+        if (staleProjects.length) {
+            warnings.push(`${staleProjects.length} projekt korpusza elavult (> ${FAM_DupCoverage_ControlService.STALE_WARN_DAYS} `
+                + `nap): ${staleProjects.join(', ')}`);
+        }
+        return {
+            table: set.table,
+            generatedAt: set.nowMs,
+            projectsTotal: set.projectNames.length,
+            zeroEntryProjects: zeroEntryProjects,
+            staleProjects: staleProjects,
+            projects: projects,
+            warnings: warnings,
+        };
+    }
+    /** Egy fő RAG-tár mongoose-collection-je (a DS-példányosítás regisztrálja a modellt; onnan a valós collection). */
+    entryCollection(registryEntry) {
+        new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[registryEntry.dataParams.dataName].collection;
+    }
+}
+exports.FAM_DupCoverage_ControlService = FAM_DupCoverage_ControlService;

package/build/src/_modules/embedding/_services/fam-duplicate-scan.control-service.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_DuplicateScan_ControlService = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_dup_fork_pair_util_1 = require("../_collections/fam-dup-fork-pair.util");
+const fam_dup_file_rollup_util_1 = require("../_collections/fam-dup-file-rollup.util");
 const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_dup_coverage_control_service_1 = require("./fam-dup-coverage.control-service");
 const fam_entry_data_service_1 = require("./fam-entry.data-service");
 const fam_vector_search_control_service_1 = require("./fam-vector-search.control-service");
 /**
@@ -44,12 +47,15 @@ class FAM_DuplicateScan_ControlService {
         const search = fam_vector_search_control_service_1.FAM_VectorSearch_ControlService.getInstance();
         const totalInPool = registryEntry ? search.getPoolSize(input.table) : 0;
         const filtered = FAM_DuplicateScan_ControlService.hasCandidateFilter(input);
-        const empty = {
-            table: input.table, threshold: threshold, totalInPool: totalInPool, scanned: 0,
-            capped: false, filtered: filtered, clusterCount: 0, duplicateEntryCount: 0, clusters: [],
-        };
         if (!registryEntry || !totalInPool) {
-            return empty;
+            // Üres pool → üres eredmény, DE a coverage-preflight ITT IS beágyazva (a „miért üres?" — pl. 0-entry
+            // projektek — ne legyen néma; dup-v2 edge-case).
+            return {
+                table: input.table, threshold: threshold, totalInPool: totalInPool, scanned: 0,
+                capped: false, filtered: filtered, clusterCount: 0, duplicateEntryCount: 0, clusters: [],
+                fileRollup: [], forkPairs: { pairs: [], suspectedForkCount: 0 }, suppressedClusters: 0,
+                coverage: registryEntry ? await this.maybeCoverage(input) : undefined,
+            };
         }
         // 1. A (capolt) (id, vektor) halmaz lean-streamelése (NEM a teljes content — csak a vektorok).
         // A szűrő-mezők Mongo-prefilterként MÁR ITT szűkítik a jelölt-halmazt (célzott scan a nagy táron).
@@ -95,7 +101,7 @@ class FAM_DuplicateScan_ControlService {
             }
         }
         const metaById = await this.fetchMeta(dataService, clusteredIds);
-        // 5. Cluster-ek építése (tag-dúsítás + projekt-lefedettség) + a `minProjects` cross-project szűrő +
+        // 5. Cluster-ek építése (tag-dúsítás + projekt-/repo-lefedettség) + a `minProjects` cross-project szűrő +
         // rendezés (legszélesebb projekt-lefedettség, majd méret, majd score elöl) + output-cap.
         const minProjects = input.minProjects ?? 0;
         const clusters = components
@@ -106,6 +112,7 @@ class FAM_DuplicateScan_ControlService {
                 snippet: metaById.get(id)?.snippet,
                 sourceFilePath: metaById.get(id)?.sourceFilePath,
                 project: metaById.get(id)?.project,
+                repoName: metaById.get(id)?.repoName,
             }));
             const projects = FAM_DuplicateScan_ControlService.distinctProjects(members);
             return {
@@ -114,6 +121,7 @@ class FAM_DuplicateScan_ControlService {
                 minScore: component.minScore,
                 projects: projects,
                 projectCount: projects.length,
+                repoNames: FAM_DuplicateScan_ControlService.distinctRepoNames(members),
                 members: members,
             };
         })
@@ -121,7 +129,24 @@ class FAM_DuplicateScan_ControlService {
             .sort((left, right) => right.projectCount - left.projectCount
             || right.size - left.size
             || right.maxScore - left.maxScore);
-        const duplicateEntryCount = clusters.reduce((sum, cluster) => sum + cluster.size, 0);
+        // 6. Fork-pár statisztika (dup-v2): a súly itt a cluster-MÉRET (a near-scannek nincs wasted-char fogalma —
+        // a `wastedShare` így méret-részarány; a JSDoc-olt szemantika a FAM_DupForkPair_Util-ban). Opt-in
+        // szuppresszió: CSAK a kimeneti cluster-listát szűri (a felderítés ténye nem vész el — `suppressedClusters`).
+        const forkRows = clusters.map((cluster) => ({
+            projects: cluster.projects, wasted: cluster.size, repoNames: cluster.repoNames,
+        }));
+        const totalWeight = clusters.reduce((sum, cluster) => sum + cluster.size, 0);
+        const forkPairs = fam_dup_fork_pair_util_1.FAM_DupForkPair_Util.buildReport(forkRows, totalWeight);
+        let finalClusters = clusters;
+        let suppressedClusters = 0;
+        if (input.suppressForkPairs) {
+            const suspected = forkPairs.pairs.filter((pair) => pair.suspectedFork);
+            finalClusters = clusters.filter((cluster) => !fam_dup_fork_pair_util_1.FAM_DupForkPair_Util.shouldSuppress({ projects: cluster.projects, repoNames: cluster.repoNames }, suspected));
+            suppressedClusters = clusters.length - finalClusters.length;
+        }
+        const duplicateEntryCount = finalClusters.reduce((sum, cluster) => sum + cluster.size, 0);
+        // 7. Output-cap + fájl-rollup a CAP-ELT (visszaadott) clusterekből (a clusterRefs indexei konzisztensek).
+        const cappedClusters = finalClusters.slice(0, maxClusters);
         return {
             table: input.table,
             threshold: threshold,
@@ -129,15 +154,33 @@ class FAM_DuplicateScan_ControlService {
             scanned: scanned,
             capped: capped,
             filtered: filtered,
-            clusterCount: clusters.length,
+            clusterCount: finalClusters.length,
             duplicateEntryCount: duplicateEntryCount,
-            clusters: clusters.slice(0, maxClusters),
+            clusters: cappedClusters,
+            fileRollup: fam_dup_file_rollup_util_1.FAM_DupFileRollup_Util.build(cappedClusters),
+            forkPairs: forkPairs,
+            suppressedClusters: suppressedClusters,
+            coverage: await this.maybeCoverage(input),
         };
     }
+    /** A coverage-preflight beágyazása (`includeCoverage !== false`); a coverage-hiba NEM dönti a scant (best-effort). */
+    async maybeCoverage(input) {
+        if (input.includeCoverage === false) {
+            return undefined;
+        }
+        try {
+            return await fam_dup_coverage_control_service_1.FAM_DupCoverage_ControlService.getInstance().report(input.table);
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM dup-scan] coverage-preflight sikertelen (best-effort): ${error?.message}`);
+            return undefined;
+        }
+    }
     /** Van-e AKTÍV jelölt-szűrő az inputban (→ Mongo-prefilter + candidateIds-szűkített keresés)? Tiszta. */
     static hasCandidateFilter(input) {
         return Boolean(input.pathRegex || input.excludePathRegex || input.excludeRootRegex
-            || input.projects?.length || input.excludeProjects?.length);
+            || input.projects?.length || input.excludeProjects?.length
+            || (input.minContentLength ?? 0) > 0);
     }
     /**
      * A jelölt-halmaz Mongo-prefilterének összeállítása az input szűrő-mezőiből. Tiszta (side-effect-mentes) →
@@ -160,6 +203,11 @@ class FAM_DuplicateScan_ControlService {
         if (input.excludeProjects?.length) {
             conditions.push({ scopePath: { $not: { $elemMatch: { layer: 'project', canonicalName: { $in: input.excludeProjects } } } } });
         }
+        if ((input.minContentLength ?? 0) > 0) {
+            // Rövid boilerplate-zaj kizárása MÁR a prefilterben (dup-v2): a content karakter-hossza (`$strLenCP`)
+            // legalább `minContentLength` legyen (hiányzó content → 0 hossz → kiesik).
+            conditions.push({ $expr: { $gte: [{ $strLenCP: { $ifNull: ['$content', ''] } }, input.minContentLength] } });
+        }
         return (conditions.length === 1 ? conditions[0] : { $and: conditions });
     }
     /** Egy entry projekt-neve a scopePath project-layer eleméből (nincs → undefined). Tiszta. */
@@ -170,6 +218,10 @@ class FAM_DuplicateScan_ControlService {
     static distinctProjects(members) {
         return [...new Set(members.map((member) => member.project).filter((project) => Boolean(project)))].sort();
     }
+    /** A cluster-tagok KÜLÖNBÖZŐ (nem-üres) repo-nevei rendezve (fork-pár evidencia — dup-v2). Tiszta. */
+    static distinctRepoNames(members) {
+        return [...new Set(members.map((member) => member.repoName).filter((repo) => Boolean(repo)))].sort();
+    }
     /**
      * **Tiszta union-find**: a hasonlóság-élekből összefüggő komponensek (méret ≥ 2). Minden komponens id-i
      * rendezve + a komponens score-tartománya (min/max él-score). Determinista (azonos input → azonos output).
@@ -252,6 +304,7 @@ class FAM_DuplicateScan_ControlService {
                 snippet: content.replace(/\s+/g, ' ').trim().slice(0, FAM_DuplicateScan_ControlService.SNIPPET_LENGTH),
                 sourceFilePath: entry.sourceFilePath,
                 project: FAM_DuplicateScan_ControlService.projectOf(entry.scopePath),
+                repoName: entry.source?.repoName,
             });
         }
         return metaById;

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FAM_EmbeddingBootstrap_ControlService = void 0;
 const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
 const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_dup_audit_scheduler_control_service_1 = require("./fam-dup-audit-scheduler.control-service");
 const fam_hydration_coordinator_control_service_1 = require("./fam-hydration-coordinator.control-service");
 const fam_vector_search_control_service_1 = require("./fam-vector-search.control-service");
 const fam_scope_maintenance_control_service_1 = require("../../scope-reference/_services/fam-scope-maintenance.control-service");
@@ -56,6 +57,14 @@ class FAM_EmbeddingBootstrap_ControlService {
         catch (error) {
             fsm_dynamo_1.DyFM_Log.warn(`[FAM bootstrap] heti re-scan scheduler telepítése sikertelen: ${error?.message}`);
         }
+        // HETI DUP-ŐRJÁRAT (dup-v2, task #20): a scheduler telepítése UGYANITT, a hydrateAll await ELŐTT (boot-timer
+        // TILOS await mögé!) — a tick maga kapuzza magát (a heti re-scan lefutása + single-flight + enabled-flag).
+        try {
+            fam_dup_audit_scheduler_control_service_1.FAM_DupAuditScheduler_ControlService.getInstance().install();
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM bootstrap] dup-őrjárat scheduler telepítése sikertelen: ${error?.message}`);
+        }
         // A readiness-coordinator hidratálás-bevárás time-outja a `read.hydrationWaitMs` config-ból (a hidratálás
         // ELŐTT, hogy a `beginBoot` után érkező read-ek már a helyes időkorláttal várjanak). Best-effort (default 180s).
         try {

package/build/src/_modules/embedding/_services/fam-exact-duplication.control-service.js

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ExactDuplication_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 fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_dup_fork_pair_util_1 = require("../_collections/fam-dup-fork-pair.util");
+const fam_store_registry_const_1 = require("../_collections/fam-store-registry.const");
+const fam_dup_coverage_control_service_1 = require("./fam-dup-coverage.control-service");
+const fam_duplicate_scan_control_service_1 = require("./fam-duplicate-scan.control-service");
+const fam_entry_data_service_1 = require("./fam-entry.data-service");
+/**
+ * `FAM_ExactDuplication_ControlService` (dup-v2, task #20) — **EXACT (contentHash-azonos) duplikáció-mérő**
+ * capability-motor. A near-dup scannel (`FAM_DuplicateScan_ControlService`) szemben NEM vektor-alapú: egyetlen
+ * Mongo-aggregáció (`$group` by contentHash) a TELJES szűrt halmazon → a 300k-s codebase táron is fut, cap
+ * nélkül, memória-robbanás nélkül (`allowDiskUse` + korai `$project`; a `contentVector` SOSEM kerül a
+ * pipeline-ba). Read-only — csak felderít, nem töröl.
+ *
+ * **Szűrő-konzisztencia:** a user-szűrők (path/root/projekt) a near-dup `buildScanFilter`-rel AZONOS feltételek
+ * (REUSE — a két capability ugyanazt a halmazt érti a szűrő alatt, beleértve az `embeddingStatus:'completed'`
+ * feltételt is: a mért korpusz = a retrieval-képes korpusz).
+ *
+ * **16MB-jegyzet (`$addToSet files`):** egy csoport fájl-listája elvileg nőhet nagyra, de a reális eloszlásnál
+ * (egy hash tipikusan < pár száz fájl) a 16MB dokumentum-limit messze van; a top-ágon a `$slice` cap-el, a
+ * pairSource/multiProject ág nem viszi a `files`-t.
+ */
+class FAM_ExactDuplication_ControlService {
+    static _instance;
+    issuer = 'FAM_ExactDuplication_ControlService';
+    /** Default visszaadott csoport-szám. */
+    static DEFAULT_MAX_GROUPS = 100;
+    /** A visszaadott csoport-szám hard cap-je (context-védelem). */
+    static HARD_MAX_GROUPS = 500;
+    /** Default per-csoport fájl-cap. */
+    static DEFAULT_MAX_FILES_PER_GROUP = 20;
+    /** A pár-forrás facet sor-cap-je (a pár-statisztika bounded marad extrém dup-eloszlásnál is). */
+    static PAIR_SOURCE_LIMIT = 50000;
+    static getInstance() {
+        if (!FAM_ExactDuplication_ControlService._instance) {
+            FAM_ExactDuplication_ControlService._instance = new FAM_ExactDuplication_ControlService();
+        }
+        return FAM_ExactDuplication_ControlService._instance;
+    }
+    /**
+     * Az exact dup-mérés futtatása (read-only). Üres tábla / 0 csoport → 0-default totals (nem dob).
+     * Érvénytelen user-regex → deskriptív FAM_Error (nem Mongo-mélyhiba).
+     */
+    async run(input) {
+        const normalized = FAM_ExactDuplication_ControlService.normalize(input);
+        this.assertValidRegexes(normalized);
+        const registryEntry = fam_store_registry_const_1.FAM_StoreRegistry_Util.getEntry(normalized.table);
+        if (!registryEntry) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: `A 'detect_exact_duplication' csak fő RAG-táron fut — a(z) '${normalized.table}' nem az `
+                    + '(a `reference` helper nem vektorizált fő tár).',
+                issuer: this.issuer,
+                context: { operation: 'capability-invoke:detect_exact_duplication' },
+            });
+        }
+        // Egyetlen aggregáció a RAW collection-ön (allowDiskUse a nagy $group/$sort miatt).
+        const collection = this.entryCollection(registryEntry);
+        const pipeline = FAM_ExactDuplication_ControlService.buildPipeline(normalized);
+        const facetRows = await collection
+            .aggregate(pipeline, { allowDiskUse: true }).toArray();
+        // Coverage-preflight beágyazás (a hiányzó/elavult projekt-korpusz NE legyen néma hamis-negatív).
+        const coverage = normalized.includeCoverage
+            ? await fam_dup_coverage_control_service_1.FAM_DupCoverage_ControlService.getInstance().report(normalized.table)
+            : undefined;
+        return FAM_ExactDuplication_ControlService.toResult(facetRows[0], normalized, coverage);
+    }
+    /** A nyers input default-olása + cap-elése. Tiszta. */
+    static normalize(input) {
+        const maxGroups = Math.min(Math.max(input.maxGroups ?? FAM_ExactDuplication_ControlService.DEFAULT_MAX_GROUPS, 1), FAM_ExactDuplication_ControlService.HARD_MAX_GROUPS);
+        return {
+            table: input.table ?? fam_table_type_enum_1.FAM_Table.codebase,
+            pathRegex: input.pathRegex,
+            excludePathRegex: input.excludePathRegex,
+            excludeRootRegex: input.excludeRootRegex,
+            projects: input.projects?.length ? input.projects : undefined,
+            excludeProjects: input.excludeProjects?.length ? input.excludeProjects : undefined,
+            minProjects: Math.max(input.minProjects ?? 1, 0),
+            minContentLength: Math.max(input.minContentLength ?? 0, 0),
+            maxGroups: maxGroups,
+            maxFilesPerGroup: Math.max(input.maxFilesPerGroup ?? FAM_ExactDuplication_ControlService.DEFAULT_MAX_FILES_PER_GROUP, 1),
+            suppressForkPairs: input.suppressForkPairs === true,
+            includeCoverage: input.includeCoverage !== false,
+        };
+    }
+    /**
+     * A `$match` stage összeállítása: explicit `_deleted:null` (raw-path aktív-szűrő) + `contentHash` string +
+     * a near-dup `buildScanFilter`-rel AZONOS user-szűrő feltételek (REUSE) + opcionális `$strLenCP` hossz-kapu.
+     * Tiszta.
+     */
+    static buildMatchStage(input) {
+        const conditions = [
+            // RAW collection-t olvasunk (nem a Dynamo DataService-t) → a soft-delete kizárás EXPLICIT kötelező.
+            { _deleted: null },
+            { contentHash: { $type: 'string', $ne: '' } },
+        ];
+        // A user-szűrők a near-dup scan-nel AZONOS feltétel-készletből (REUSE — nincs drift a két capability közt).
+        const scanFilter = fam_duplicate_scan_control_service_1.FAM_DuplicateScan_ControlService.buildScanFilter({
+            table: input.table,
+            pathRegex: input.pathRegex,
+            excludePathRegex: input.excludePathRegex,
+            excludeRootRegex: input.excludeRootRegex,
+            projects: input.projects,
+            excludeProjects: input.excludeProjects,
+        });
+        const scanConditions = Array.isArray(scanFilter.$and)
+            ? scanFilter.$and
+            : [scanFilter];
+        conditions.push(...scanConditions);
+        if (input.minContentLength > 0) {
+            conditions.push({ $expr: { $gte: [{ $strLenCP: { $ifNull: ['$content', ''] } }, input.minContentLength] } });
+        }
+        return { $and: conditions };
+    }
+    /**
+     * A teljes aggregáció-pipeline (korai `$project` — a `contentVector` és a `content` szöveg NEM utazik a
+     * `$group`-ba, csak a hossz) + `$facet` a 4 kimeneti ággal (totals / top / pairSource / multiProject). Tiszta.
+     */
+    static buildPipeline(input) {
+        return [
+            { $match: FAM_ExactDuplication_ControlService.buildMatchStage(input) },
+            // Korai projekció: csak a csoportosításhoz szükséges skalárok (hossz + projekt + repo + fájl-út).
+            {
+                $project: {
+                    contentHash: 1,
+                    sourceFilePath: 1,
+                    len: { $strLenCP: { $ifNull: ['$content', ''] } },
+                    project: {
+                        $arrayElemAt: [{
+                                $map: {
+                                    input: {
+                                        $filter: {
+                                            input: { $ifNull: ['$scopePath', []] },
+                                            as: 'ref',
+                                            cond: { $eq: ['$$ref.layer', 'project'] },
+                                        },
+                                    },
+                                    as: 'ref',
+                                    in: '$$ref.canonicalName',
+                                },
+                            }, 0],
+                    },
+                    repoName: '$source.repoName',
+                },
+            },
+            {
+                $group: {
+                    _id: '$contentHash',
+                    copies: { $sum: 1 },
+                    contentLen: { $first: '$len' },
+                    projects: { $addToSet: '$project' },
+                    repoNames: { $addToSet: '$repoName' },
+                    files: { $addToSet: '$sourceFilePath' },
+                },
+            },
+            { $match: { copies: { $gte: 2 } } },
+            // A project-layer nélküli entry-k null-ja kikerül a halmazokból (a copies/wasted számít, a lefedettség nem).
+            {
+                $addFields: {
+                    projects: { $setDifference: ['$projects', [null]] },
+                    repoNames: { $setDifference: ['$repoNames', [null]] },
+                },
+            },
+            { $match: { $expr: { $gte: [{ $size: '$projects' }, input.minProjects] } } },
+            {
+                $addFields: {
+                    wasted: { $multiply: ['$contentLen', { $subtract: ['$copies', 1] }] },
+                    projectCount: { $size: '$projects' },
+                },
+            },
+            { $sort: { wasted: -1 } },
+            {
+                $facet: {
+                    totals: [{
+                            $group: {
+                                _id: null,
+                                totalGroups: { $sum: 1 },
+                                redundantCopies: { $sum: { $subtract: ['$copies', 1] } },
+                                wastedChars: { $sum: '$wasted' },
+                            },
+                        }],
+                    top: [
+                        { $limit: input.maxGroups },
+                        {
+                            $project: {
+                                _id: 0,
+                                contentHash: '$_id',
+                                copies: 1,
+                                projects: 1,
+                                projectCount: 1,
+                                repoNames: 1,
+                                files: { $slice: ['$files', input.maxFilesPerGroup] },
+                                filesTruncated: { $gt: [{ $size: '$files' }, input.maxFilesPerGroup] },
+                                contentLen: 1,
+                                wasted: 1,
+                            },
+                        },
+                    ],
+                    pairSource: [
+                        { $match: { projectCount: { $gte: 2 } } },
+                        { $project: { _id: 0, projects: 1, wasted: 1, repoNames: 1 } },
+                        { $limit: FAM_ExactDuplication_ControlService.PAIR_SOURCE_LIMIT },
+                    ],
+                    multiProject: [
+                        { $match: { projectCount: { $gte: 4 } } },
+                        { $project: { _id: 1 } },
+                    ],
+                },
+            },
+        ];
+    }
+    /**
+     * A `$facet` nyers kimenete → strukturált eredmény: 0-default totals (üres tábla nem dob), rendezett
+     * projekt-/repo-listák, fork-pár riport + (opt-in) csoport-szuppresszió. Tiszta.
+     */
+    static toResult(facetRow, input, coverage) {
+        const totalsRow = facetRow?.totals?.[0];
+        const totals = {
+            totalGroups: totalsRow?.totalGroups ?? 0,
+            redundantCopies: totalsRow?.redundantCopies ?? 0,
+            wastedChars: totalsRow?.wastedChars ?? 0,
+        };
+        // Fork-pár statisztika a pár-forrás ágból (a wastedShare nevezője a TELJES pazarlás).
+        const pairSource = (facetRow?.pairSource ?? []).map((row) => ({
+            projects: row.projects ?? [], wasted: row.wasted ?? 0, repoNames: row.repoNames ?? [],
+        }));
+        const forkPairs = fam_dup_fork_pair_util_1.FAM_DupForkPair_Util.buildReport(pairSource, totals.wastedChars);
+        // A top-csoportok normalizálása (distinct/null-mentes/rendezett projektek — a $setDifference után a
+        // null már kint van, itt csak a determinista rendezés a dolgunk).
+        let groups = (facetRow?.top ?? []).map((row) => ({
+            contentHash: row.contentHash,
+            copies: row.copies,
+            projects: (row.projects ?? []).filter((project) => Boolean(project)).sort(),
+            projectCount: row.projectCount ?? 0,
+            repoNames: (row.repoNames ?? []).filter((repo) => Boolean(repo)).sort(),
+            // Az explicit `sourceFilePath:null` entry null-t adhat a halmazba — a riportban nem hordoz információt.
+            files: (row.files ?? []).filter((file) => Boolean(file)),
+            filesTruncated: Boolean(row.filesTruncated),
+            contentLen: row.contentLen ?? 0,
+            wasted: row.wasted ?? 0,
+        }));
+        // Opt-in fork-pár szuppresszió: CSAK a visszaadott csoport-listát szűri (a totals a mért valóság marad —
+        // a szuppresszió láthatóság-kontroll, nem mérés-hamisítás).
+        let suppressedGroups = 0;
+        if (input.suppressForkPairs) {
+            const suspected = forkPairs.pairs.filter((pair) => pair.suspectedFork);
+            const kept = groups.filter((group) => !fam_dup_fork_pair_util_1.FAM_DupForkPair_Util.shouldSuppress({ projects: group.projects, repoNames: group.repoNames }, suspected));
+            suppressedGroups = groups.length - kept.length;
+            groups = kept;
+        }
+        return {
+            table: input.table,
+            filters: {
+                pathRegex: input.pathRegex,
+                excludePathRegex: input.excludePathRegex,
+                excludeRootRegex: input.excludeRootRegex,
+                projects: input.projects,
+                excludeProjects: input.excludeProjects,
+                minProjects: input.minProjects,
+                minContentLength: input.minContentLength,
+            },
+            totals: totals,
+            truncated: totals.totalGroups > input.maxGroups,
+            groups: groups,
+            suppressedGroups: suppressedGroups,
+            forkPairs: forkPairs,
+            multiProjectGroupHashes: (facetRow?.multiProject ?? []).map((row) => String(row._id)),
+            coverage: coverage,
+        };
+    }
+    /** Az user-regexek elő-validálása (érvénytelen minta → deskriptív hiba, nem Mongo-mélyhiba). */
+    assertValidRegexes(input) {
+        const candidates = [
+            { name: 'pathRegex', pattern: input.pathRegex },
+            { name: 'excludePathRegex', pattern: input.excludePathRegex },
+            { name: 'excludeRootRegex', pattern: input.excludeRootRegex },
+        ];
+        for (const candidate of candidates) {
+            if (!candidate.pattern) {
+                continue;
+            }
+            try {
+                new RegExp(candidate.pattern);
+            }
+            catch (error) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                    message: `A 'detect_exact_duplication' '${candidate.name}' regexe érvénytelen: `
+                        + `'${candidate.pattern}' — ${error?.message}`,
+                    issuer: this.issuer,
+                    cause: error,
+                    context: { operation: 'capability-invoke:detect_exact_duplication' },
+                });
+            }
+        }
+    }
+    /** Egy fő RAG-tár mongoose-collection-je (a DS-példányosítás regisztrálja a modellt; onnan a valós collection). */
+    entryCollection(registryEntry) {
+        new fam_entry_data_service_1.FAM_Entry_DataService({ dataParams: registryEntry.dataParams, issuer: this.issuer });
+        return mongoose_1.default.models[registryEntry.dataParams.dataName].collection;
+    }
+}
+exports.FAM_ExactDuplication_ControlService = FAM_ExactDuplication_ControlService;

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

@@ -8,7 +8,7 @@
  * (BFR-AM-002/008); a bedrock-csere (MP-15) a `FAM_EmbeddingProvider` interfész mögött non-breaking.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FAM_EmbeddingBootstrap_ControlService = exports.FAM_DuplicateScan_ControlService = exports.FAM_EmbeddingCost_ControlService = exports.FAM_EmbeddingPipeline_ControlService = exports.FAM_EmbeddingPreset_ControlService = exports.FAM_StoreRegistry_Util = exports.FAM_STORE_REGISTRY = exports.FAM_DedupWarn_ControlService = exports.FAM_Entry_DataService = exports.FAM_HydrationCoordinator_ControlService = exports.FAM_VectorSearch_ControlService = exports.FAM_MOCK_EMBEDDING_DIMS = exports.FAM_Mock_EmbeddingProvider = exports.FAM_LMStudio_EmbeddingProvider = exports.FAM_OpenAI_EmbeddingProvider = exports.FAM_Embedding_ControlService = void 0;
+exports.FAM_EmbeddingBootstrap_ControlService = exports.FAM_DupAuditScheduler_ControlService = exports.FAM_DupAudit_DataService = exports.FAM_DupAudit_ControlService = exports.FAM_DupFileRollup_Util = exports.FAM_DupForkPair_Util = exports.FAM_DupCoverage_ControlService = exports.FAM_ExactDuplication_ControlService = exports.FAM_DuplicateScan_ControlService = exports.FAM_EmbeddingCost_ControlService = exports.FAM_EmbeddingPipeline_ControlService = exports.FAM_EmbeddingPreset_ControlService = exports.FAM_StoreRegistry_Util = exports.FAM_STORE_REGISTRY = exports.FAM_DedupWarn_ControlService = exports.FAM_Entry_DataService = exports.FAM_HydrationCoordinator_ControlService = exports.FAM_VectorSearch_ControlService = exports.FAM_MOCK_EMBEDDING_DIMS = exports.FAM_Mock_EmbeddingProvider = exports.FAM_LMStudio_EmbeddingProvider = exports.FAM_OpenAI_EmbeddingProvider = exports.FAM_Embedding_ControlService = void 0;
 // SP-2.1 — provider-dispatch kapu + providerek
 var fam_embedding_control_service_1 = require("./_services/fam-embedding.control-service");
 Object.defineProperty(exports, "FAM_Embedding_ControlService", { enumerable: true, get: function () { return fam_embedding_control_service_1.FAM_Embedding_ControlService; } });
@@ -42,6 +42,21 @@ Object.defineProperty(exports, "FAM_EmbeddingCost_ControlService", { enumerable:
 // near-duplikátum FELDERÍTŐ (read-only; user-direktíva 2026-06-21)
 var fam_duplicate_scan_control_service_1 = require("./_services/fam-duplicate-scan.control-service");
 Object.defineProperty(exports, "FAM_DuplicateScan_ControlService", { enumerable: true, get: function () { return fam_duplicate_scan_control_service_1.FAM_DuplicateScan_ControlService; } });
+// dup-v2 (task #20): exact-duplikáció + coverage-preflight + fork-pár + fájl-rollup + heti dup-őrjárat
+var fam_exact_duplication_control_service_1 = require("./_services/fam-exact-duplication.control-service");
+Object.defineProperty(exports, "FAM_ExactDuplication_ControlService", { enumerable: true, get: function () { return fam_exact_duplication_control_service_1.FAM_ExactDuplication_ControlService; } });
+var fam_dup_coverage_control_service_1 = require("./_services/fam-dup-coverage.control-service");
+Object.defineProperty(exports, "FAM_DupCoverage_ControlService", { enumerable: true, get: function () { return fam_dup_coverage_control_service_1.FAM_DupCoverage_ControlService; } });
+var fam_dup_fork_pair_util_1 = require("./_collections/fam-dup-fork-pair.util");
+Object.defineProperty(exports, "FAM_DupForkPair_Util", { enumerable: true, get: function () { return fam_dup_fork_pair_util_1.FAM_DupForkPair_Util; } });
+var fam_dup_file_rollup_util_1 = require("./_collections/fam-dup-file-rollup.util");
+Object.defineProperty(exports, "FAM_DupFileRollup_Util", { enumerable: true, get: function () { return fam_dup_file_rollup_util_1.FAM_DupFileRollup_Util; } });
+var fam_dup_audit_control_service_1 = require("./_services/fam-dup-audit.control-service");
+Object.defineProperty(exports, "FAM_DupAudit_ControlService", { enumerable: true, get: function () { return fam_dup_audit_control_service_1.FAM_DupAudit_ControlService; } });
+var fam_dup_audit_data_service_1 = require("./_services/fam-dup-audit.data-service");
+Object.defineProperty(exports, "FAM_DupAudit_DataService", { enumerable: true, get: function () { return fam_dup_audit_data_service_1.FAM_DupAudit_DataService; } });
+var fam_dup_audit_scheduler_control_service_1 = require("./_services/fam-dup-audit-scheduler.control-service");
+Object.defineProperty(exports, "FAM_DupAuditScheduler_ControlService", { enumerable: true, get: function () { return fam_dup_audit_scheduler_control_service_1.FAM_DupAuditScheduler_ControlService; } });
 // boot-hook (App.postProcess)
 var fam_embedding_bootstrap_control_service_1 = require("./_services/fam-embedding-bootstrap.control-service");
 Object.defineProperty(exports, "FAM_EmbeddingBootstrap_ControlService", { enumerable: true, get: function () { return fam_embedding_bootstrap_control_service_1.FAM_EmbeddingBootstrap_ControlService; } });