@futdevpro/fdp-agent-memory 1.1.130 → 1.1.133

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "1.1.130",
+    "version": "1.1.133",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {

package/build/src/_collections/config-catalog.const.js

@@ -473,6 +473,18 @@ exports.CONFIG_CATALOG = {
             + 'elleni védelem). `0` = még sosem futott. A scheduler írja; kézzel ne állítsd (a `fam config get`-tel '
             + 'olvasható, mikor futott utoljára).',
     },
+    'scan.dupAuditEnabled': {
+        type: 'boolean', default: true, levels: GLOBAL_ONLY,
+        description: 'Heti duplikáció-őrjárat (dup-v2, task #20) be/ki: a HETI re-scan UTÁN egy exact-dup mérés + '
+            + 'coverage-preflight + baseline-delta + új-széles-csoport riasztás fut, a pillanatkép a `fam_dup_audits`-ba '
+            + 'kerül. `false` → nincs automata őrjárat (a `detect_exact_duplication` capability kézzel továbbra is hívható).',
+    },
+    'scan.dupAuditLastRunAt': {
+        type: 'number', default: 0, min: 0, max: 9999999999999, integer: true, levels: GLOBAL_ONLY,
+        description: 'ÁLLAPOT/observability (NEM felhasználói hangoló): a legutóbbi dup-őrjárat TRIGGER epoch-ms-e. A '
+            + 'dup-audit scheduler ezzel dönti el, hogy a legutóbbi heti re-scan után futott-e már audit (markRan-before-run '
+            + '— crash-tűrő idempotencia). `0` = még sosem futott. A scheduler írja; kézzel ne állítsd.',
+    },
     // --- 4.6. Reference / scope (fogyasztó: dsgn-002) ---
     'reference.cacheTtlMs': {
         type: 'number', default: 60000, min: 0, max: 3600000, integer: true, levels: GLOBAL_ONLY,

package/build/src/_collections/error-codes.const.js

@@ -126,6 +126,8 @@ exports.FAM_ERROR_CODES = {
     scanDelta: 'FAM-SCAN-DELTA-001',
     /** 0 fájl matchelt a konfigurált mintára (level=info, NEM error, dsgn-008 §5). */
     scanEmpty: 'FAM-SCAN-EMPTY-001',
+    /** dup-őrjárat (dup-v2, task #20): ÚJ ≥4-projektes exact-dup csoport jelent meg az előző audit óta (level=warning). */
+    scanDupAuditNewGroup: 'FAM-SCAN-DUPAUDIT-001',
     // --- DB (FAM-DB-*) ---
     /** MongoDB connect sikertelen (critical). */
     dbConnect: 'FAM-DB-CONNECT-001',

package/build/src/_collections/fam-db-models.const.js

@@ -5,6 +5,7 @@ const fam_codebase_data_model_1 = require("../_models/data-models/fam-codebase.d
 const fam_coding_patterns_data_model_1 = require("../_models/data-models/fam-coding-patterns.data-model");
 const fam_config_data_model_1 = require("../_models/data-models/fam-config.data-model");
 const fam_documents_data_model_1 = require("../_models/data-models/fam-documents.data-model");
+const fam_dup_audit_data_model_1 = require("../_models/data-models/fam-dup-audit.data-model");
 const fam_error_data_model_1 = require("../_models/data-models/fam-error.data-model");
 const fam_ingest_run_data_model_1 = require("../_models/data-models/fam-ingest-run.data-model");
 const fam_knowledge_data_model_1 = require("../_models/data-models/fam-knowledge.data-model");
@@ -34,6 +35,7 @@ exports.FAM_DB_MODELS = [
     fam_scope_data_model_1.famScope_dataParams, // fam_scopes
     fam_ingest_run_data_model_1.famIngestRun_dataParams, // fam_ingest_runs
     fam_scan_job_data_model_1.famScanJob_dataParams, // fam_scan_jobs (FEAT-008 Phase 4 — durable scan-job + auto-resume)
+    fam_dup_audit_data_model_1.famDupAudit_dataParams, // fam_dup_audits (dup-v2, task #20 — heti dup-őrjárat baseline/trend)
     // Config-réteg (MP-7, dsgn-007): DB-backed scoped config (global<table<scope).
     fam_config_data_model_1.famConfig_dataParams, // fam_config
 ];

package/build/src/_models/data-models/fam-dup-audit.data-model.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.famDupAudit_dataParams = exports.FAM_DupAudit_DataModel = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+/**
+ * `FAM_DupAudit_DataModel` (dup-v2, task #20) — egy heti/manuális duplikáció-őrjárat PERZISZTENS pillanatképe
+ * a `fam_dup_audits` collection-ben. Cél a **baseline/trend**: az egymást követő futások összevethetők (delta-%),
+ * és az ÚJONNAN megjelenő széles (≥4 projektes) csoportok riaszthatók — a duplikáció-terjedés nem néma.
+ * `extends DyFM_Metadata`. A rekord bounded (top-50 csoport + hash-lista), NEM a teljes mérés-dump.
+ */
+class FAM_DupAudit_DataModel extends fsm_dynamo_1.DyFM_Metadata {
+    /** A futás epoch-ms-e. */
+    runAt;
+    /** A vizsgált tár (`FAM_Table` érték stringként). */
+    table;
+    /** A trigger (`weekly` | `manual`). */
+    trigger;
+    /** Az alkalmazott szűrők visszhangja (a delta-összevethetőség kulcsa: csak AZONOS filter-echo hasonlítható). */
+    filters;
+    /** A szűrt halmaz ≥2 példányos csoportjainak száma. */
+    totalGroups;
+    /** A redundáns példányok száma. */
+    redundantCopies;
+    /** A pazarolt karakterek. */
+    wastedChars;
+    /** A top-50 csoport (wasted DESC) — a trend-vizualizáció/riport magja. */
+    topGroups = [];
+    /** MIND a ≥4 projektet átfedő csoport hash-e — az új-széles-csoport diff bemenete. */
+    multiProjectGroupHashes = [];
+    /** A 0-entry-s (a mérésből kimaradó) projektek a futáskor (coverage-preflight). */
+    zeroEntryProjects = [];
+    /** Az elavult-korpuszú projektek száma a futáskor. */
+    staleProjectCount;
+    /** A csoport-szám %-os változása az előző ÖSSZEVETHETŐ futáshoz képest (nincs előzmény → undefined). */
+    deltaGroupsPct;
+    /** A pazarlás %-os változása az előző ÖSSZEVETHETŐ futáshoz képest (nincs előzmény → undefined). */
+    deltaWastedPct;
+    /** True, ha volt előző futás, de MÁS filter-echo-val (a delta ilyenkor nem számolható — nincs hamis trend). */
+    previousIncomparable;
+    constructor(set) {
+        super(set);
+        if (set) {
+            fsm_dynamo_1.DyFM_Object.cleanAssign(this, set);
+        }
+    }
+}
+exports.FAM_DupAudit_DataModel = FAM_DupAudit_DataModel;
+/**
+ * MongoDB data-params a `fam_dup_audits` collection-höz (dup-v2). `addArchive:false` — az audit-pillanatkép
+ * nem user-tartalom, a retention (utolsó N futás) fizikai törléssel bounded (lásd `FAM_DupAudit_DataService`).
+ * A `runAt`/`table`/`trigger` indexelt (a latest-lekérdezés + a trend-szűrés gyors útja).
+ */
+exports.famDupAudit_dataParams = new fsm_dynamo_1.DyFM_DataModel_Params({
+    dataName: 'fam_dup_audits',
+    addArchive: false,
+    properties: {
+        runAt: { type: 'number', index: true },
+        table: { type: 'string', index: true },
+        trigger: { type: 'string', index: true },
+        filters: { type: 'object' },
+        totalGroups: { type: 'number' },
+        redundantCopies: { type: 'number' },
+        wastedChars: { type: 'number' },
+        topGroups: { type: 'array', default: [] },
+        multiProjectGroupHashes: { type: 'string[]', default: [] },
+        zeroEntryProjects: { type: 'string[]', default: [] },
+        staleProjectCount: { type: 'number' },
+        deltaGroupsPct: { type: 'number' },
+        deltaWastedPct: { type: 'number' },
+        previousIncomparable: { type: 'boolean' },
+    },
+});

package/build/src/_modules/embedding/_collections/fam-dup-file-rollup.util.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupFileRollup_Util = void 0;
+/**
+ * `FAM_DupFileRollup_Util` (dup-v2, task #20) — **PURE** fájl-szintű rollup a near-dup clusterekből. A per-chunk
+ * cluster-lista nehezen akcionálható (ugyanaz a fájl 10 clusterben is felbukkanhat); a rollup fájlonként összegzi,
+ * HÁNY chunk duplikált és MELY clusterekben — így a konszolidáció-döntés fájl-szinten hozható („ez a fájl 14
+ * chunkkal érintett 5 projektben → bedrock-jelölt"). Side-effect-mentes → unit-tesztelhető.
+ */
+class FAM_DupFileRollup_Util {
+    /** A visszaadott fájl-sorok cap-je (a legtöbb chunkkal érintett fájlok elöl). */
+    static MAX_FILES = 200;
+    /**
+     * A rollup felépítése a (MÁR cap-elt, visszaadandó) clusterekből. A `clusterRefs` a bemeneti tömb indexei —
+     * ezért a hívó a VÉGSŐ (cap-elt) cluster-listát adja át, hogy a referenciák a riporttal konzisztensek legyenek.
+     * `sourceFilePath` nélküli tag kimarad (nem fájl-eredetű chunk). Tiszta.
+     */
+    static build(clusters) {
+        const byFile = new Map();
+        clusters.forEach((cluster, clusterIndex) => {
+            for (const member of cluster.members) {
+                if (!member.sourceFilePath) {
+                    continue;
+                }
+                const entry = byFile.get(member.sourceFilePath) ?? {
+                    sourceFilePath: member.sourceFilePath, chunkCount: 0, projects: [], clusterRefs: [],
+                };
+                entry.chunkCount++;
+                // A cluster projekt-lefedettsége adja a fájl-sor projektjeit (distinct — lentebb rendezzük).
+                for (const project of cluster.projects) {
+                    if (!entry.projects.includes(project)) {
+                        entry.projects.push(project);
+                    }
+                }
+                if (!entry.clusterRefs.includes(clusterIndex)) {
+                    entry.clusterRefs.push(clusterIndex);
+                }
+                byFile.set(member.sourceFilePath, entry);
+            }
+        });
+        return [...byFile.values()]
+            .map((entry) => ({ ...entry, projects: [...entry.projects].sort() }))
+            .sort((left, right) => right.chunkCount - left.chunkCount
+            || left.sourceFilePath.localeCompare(right.sourceFilePath))
+            .slice(0, FAM_DupFileRollup_Util.MAX_FILES);
+    }
+}
+exports.FAM_DupFileRollup_Util = FAM_DupFileRollup_Util;

package/build/src/_modules/embedding/_collections/fam-dup-fork-pair.util.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupForkPair_Util = void 0;
+/**
+ * `FAM_DupForkPair_Util` (dup-v2, task #20) — **PURE** fork-pár statisztika + szuppresszió. A fleet-mérések
+ * visszatérő zaja a FORK-párok (pl. `ccap` + `ccap-revisioned`): két projekt-scope, ami valójában ugyanaz a
+ * kódbázis — a köztük lévő „duplikáció" nem konszolidáció-jelölt, hanem fork-lenyomat. Ez a util a dup-csoport
+ * pár-gyakoriságából + pazarlás-részarányából + a repo-evidenciából ismeri fel a gyanús párokat, és (opt-in)
+ * szuppresszálja a CSAK e párokra eső csoportokat. Side-effect-mentes → unit-tesztelhető DB nélkül.
+ */
+class FAM_DupForkPair_Util {
+    /** A riportban visszaadott párok cap-je (a legnagyobb wasted elöl). */
+    static MAX_PAIRS = 50;
+    /** A fork-gyanú pazarlás-részarány küszöbe (a teljes pazarlás ≥20%-a egyetlen páron → gyanús). */
+    static SUSPECT_WASTED_SHARE = 0.2;
+    /** A kombinatorikus robbanás elleni per-sor projekt-cap: e fölött a sor pár-bontását kihagyjuk (sok-projektes
+     * csoport nem fork-jel — az széles cross-project duplikáció, a pár-statisztikát csak zajosítaná). */
+    static MAX_PROJECTS_PER_ROW = 8;
+    /**
+     * A pár-riport felépítése a forrás-sorokból. Minden (≤ `MAX_PROJECTS_PER_ROW` projektes) sor összes
+     * rendezetlen projekt-párjára akkumulálja a `groupCount`/`wasted`-et; a `sameRepoEvidence` CSAK a pontosan
+     * 2-projektes, egy-repós sorokból jön (az a valódi fork-lenyomat). Tiszta.
+     */
+    static buildReport(rows, totalWasted) {
+        const byKey = new Map();
+        for (const row of rows) {
+            const projects = [...new Set(row.projects)].sort();
+            if (projects.length < 2 || projects.length > FAM_DupForkPair_Util.MAX_PROJECTS_PER_ROW) {
+                continue;
+            }
+            // A pontosan-2-projektes, egy-repós csoport a fork-evidencia (mindkét „projekt" ugyanabból a repóból).
+            const rowSameRepo = projects.length === 2 && new Set(row.repoNames).size === 1 && row.repoNames.length > 0;
+            for (let i = 0; i < projects.length; i++) {
+                for (let j = i + 1; j < projects.length; j++) {
+                    const key = `${projects[i]}|${projects[j]}`;
+                    const pair = byKey.get(key) ?? {
+                        projects: [projects[i], projects[j]], groupCount: 0, wasted: 0,
+                        wastedShare: 0, sameRepoEvidence: false, suspectedFork: false,
+                    };
+                    pair.groupCount++;
+                    pair.wasted += row.wasted;
+                    pair.sameRepoEvidence = pair.sameRepoEvidence || rowSameRepo;
+                    byKey.set(key, pair);
+                }
+            }
+        }
+        // A részarány + a gyanú-flag számítása (a teljes pazarlás 0-ja ellen védve), majd rendezés + cap.
+        const pairs = [...byKey.values()]
+            .map((pair) => {
+            const wastedShare = totalWasted > 0 ? pair.wasted / totalWasted : 0;
+            return {
+                ...pair,
+                wastedShare: wastedShare,
+                suspectedFork: wastedShare >= FAM_DupForkPair_Util.SUSPECT_WASTED_SHARE || pair.sameRepoEvidence,
+            };
+        })
+            .sort((left, right) => right.wasted - left.wasted)
+            .slice(0, FAM_DupForkPair_Util.MAX_PAIRS);
+        return { pairs: pairs, suspectedForkCount: pairs.filter((pair) => pair.suspectedFork).length };
+    }
+    /**
+     * Szuppresszálandó-e egy csoport a gyanús párok mellett (opt-in `suppressForkPairs`). A szabály:
+     * (a) a csoport PONTOSAN 2 projektet fed és a pár fork-gyanús, VAGY
+     * (b) a csoport projektjei egy gyanús pár UNIÓJÁNAK részhalmaza ÉS a csoport egy-repós (distinct repoName = 1).
+     * Tiszta.
+     */
+    static shouldSuppress(group, suspectedPairs) {
+        const projects = [...new Set(group.projects)].sort();
+        const singleRepo = new Set(group.repoNames).size === 1 && group.repoNames.length > 0;
+        for (const pair of suspectedPairs) {
+            if (!pair.suspectedFork) {
+                continue;
+            }
+            const union = new Set(pair.projects);
+            const isSubset = projects.every((project) => union.has(project));
+            if (projects.length === 2 && isSubset) {
+                return true;
+            }
+            if (isSubset && singleRepo) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+exports.FAM_DupForkPair_Util = FAM_DupForkPair_Util;

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

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupAuditScheduler_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_config_level_type_enum_1 = require("../../../_enums/fam-config-level.type-enum");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_scan_job_control_service_1 = require("../../ingest/_services/fam-scan-job.control-service");
+const fam_dup_audit_control_service_1 = require("./fam-dup-audit.control-service");
+/**
+ * `FAM_DupAuditScheduler_ControlService` (dup-v2, task #20) — a **heti duplikáció-őrjárat** in-process ütemezője
+ * (a `FAM_ScanScheduler_ControlService` minta tükre). NEM saját heti slotot számol: az őrjárat a HETI RE-SCAN
+ * UTÁN esedékes (friss korpuszon mérni) — a kapu: `scan.weeklyRescanLastRunAt > scan.dupAuditLastRunAt` ÉS a
+ * re-scan már NEM fut (`hasActiveJob` single-flight). Így az audit hetente pontosan egyszer, a friss scan után fut.
+ *
+ * **Telepítés (KRITIKUS):** a `boot()` a scheduler-t a lassú boot-karbantartás (hidratálás/resume) ELŐTT telepíti
+ * — a timer BIZTOSAN felkerül az event-loopra (boot-timer TILOS `await` mögé). **markRan-before-run:** a
+ * `lastRunAt` a futás ELŐTT íródik → egy crash mid-audit sem indít restart-stormot (a következő heti slot pótol,
+ * a kiesés warn-logolt). Az audit-hiba best-effort (try/catch) — a tick és a szerver nem bukik el.
+ */
+class FAM_DupAuditScheduler_ControlService {
+    static _instance;
+    timer;
+    ticking = false;
+    running = false;
+    /** A due-ellenőrzés fix pollozási időköze (ms) — 10 perc (a scan-scheduler mintája). */
+    static CHECK_INTERVAL_MS = 600000;
+    static getInstance() {
+        if (!FAM_DupAuditScheduler_ControlService._instance) {
+            FAM_DupAuditScheduler_ControlService._instance = new FAM_DupAuditScheduler_ControlService();
+        }
+        return FAM_DupAuditScheduler_ControlService._instance;
+    }
+    /** Teszt-reset (a singleton + a timer ürítése). */
+    static resetForTest() {
+        FAM_DupAuditScheduler_ControlService._instance?.uninstall();
+        FAM_DupAuditScheduler_ControlService._instance = undefined;
+    }
+    /**
+     * Periodikus tick telepítése + azonnali első tick (boot-catch-up). Idempotens (kétszeri install → egy timer).
+     * A timer `unref`-elt (nem tartja életben a processt önmagában).
+     */
+    install() {
+        if (this.timer) {
+            return;
+        }
+        this.timer = setInterval(() => { void this.tick(Date.now()); }, FAM_DupAuditScheduler_ControlService.CHECK_INTERVAL_MS);
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+        fsm_dynamo_1.DyFM_Log.log(`[FAM dupAuditScheduler] heti dup-őrjárat figyelő telepítve (tick ${FAM_DupAuditScheduler_ControlService.CHECK_INTERVAL_MS / 60000} percenként).`);
+        void this.tick(Date.now());
+    }
+    /** A timer leállítása (teszt / graceful). */
+    uninstall() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Egy ellenőrzési ciklus: DUE-e az őrjárat (a PURE `computeDue` kapuival)? Ha igen → ELŐBB `markRan`
+     * (crash-tűrő idempotencia), MAJD a futás. Best-effort (nem dob). Re-entráns-védett (`ticking`).
+     */
+    async tick(nowMs) {
+        if (this.ticking) {
+            return;
+        }
+        this.ticking = true;
+        try {
+            const config = config_control_service_1.FAM_Config_ControlService.getInstance();
+            const enabled = (await config.resolve('scan.dupAuditEnabled')).value;
+            const weeklyLastRunAt = await this.resolveNum(config, 'scan.weeklyRescanLastRunAt');
+            const dupAuditLastRunAt = await this.resolveNum(config, 'scan.dupAuditLastRunAt');
+            const hasActiveJob = fam_scan_job_control_service_1.FAM_ScanJob_ControlService.getInstance().hasActiveJob();
+            const due = FAM_DupAuditScheduler_ControlService.computeDue({
+                enabled: enabled,
+                weeklyRescanLastRunAt: weeklyLastRunAt,
+                dupAuditLastRunAt: dupAuditLastRunAt,
+                hasActiveJob: hasActiveJob,
+                running: this.running,
+            });
+            if (!due) {
+                return;
+            }
+            // markRan-before-run: crash mid-audit → NEM lesz restart-storm; a következő heti re-scan után pótol
+            // (a kiesett futás a logból látszik — no-silent-failure).
+            fsm_dynamo_1.DyFM_Log.log('[FAM dupAuditScheduler] heti dup-őrjárat ESEDÉKES (a heti re-scan lefutott) — indítás…');
+            await this.markRan(config, nowMs);
+            this.running = true;
+            try {
+                await fam_dup_audit_control_service_1.FAM_DupAudit_ControlService.getInstance().runAudit('weekly');
+            }
+            catch (error) {
+                // Az audit-hiba NEM dönti a ticket/szervert; a kiesett futást a következő heti slot pótolja.
+                fsm_dynamo_1.DyFM_Log.warn(`[FAM dupAuditScheduler] a dup-őrjárat futása sikertelen (best-effort): ${error?.message}`);
+            }
+            finally {
+                this.running = false;
+            }
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM dupAuditScheduler] dup-őrjárat tick sikertelen (best-effort): ${error?.message}`);
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    /**
+     * **PURE** due-döntés (unit-tesztelhető DB nélkül). Kapuk:
+     * (1) `scan.dupAuditEnabled !== false` (default engedélyezett),
+     * (2) volt már heti re-scan (`weeklyRescanLastRunAt > 0` — friss korpusz nélkül nincs mit mérni),
+     * (3) a legutóbbi re-scan ÚJABB, mint a legutóbbi audit (`weekly > dupAudit` — heti max 1 futás),
+     * (4) a re-scan már NEM fut (`!hasActiveJob` — single-flight, ne mérjünk fél-kész korpuszt),
+     * (5) nem fut már audit (`!running` — re-entráns védelem).
+     */
+    static computeDue(set) {
+        return set.enabled !== false
+            && set.weeklyRescanLastRunAt > 0
+            && set.weeklyRescanLastRunAt > set.dupAuditLastRunAt
+            && !set.hasActiveJob
+            && !set.running;
+    }
+    /** A `lastRunAt` állapot perzisztálása a config-store-ba (global szint). Best-effort. */
+    async markRan(config, nowMs) {
+        try {
+            await config.set('scan.dupAuditLastRunAt', nowMs, {
+                level: fam_config_level_type_enum_1.FAM_ConfigLevel.global, setBy: 'system', note: 'weekly dup-audit trigger',
+            });
+        }
+        catch (error) {
+            fsm_dynamo_1.DyFM_Log.warn(`[FAM dupAuditScheduler] lastRunAt perzisztálás sikertelen: ${error?.message}`);
+        }
+    }
+    /** Egy szám-config feloldása (nem-szám → 0). */
+    async resolveNum(config, key) {
+        const value = (await config.resolve(key)).value;
+        return typeof value === 'number' ? value : 0;
+    }
+}
+exports.FAM_DupAuditScheduler_ControlService = FAM_DupAuditScheduler_ControlService;

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

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupAudit_ControlService = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_dup_audit_data_model_1 = require("../../../_models/data-models/fam-dup-audit.data-model");
+const errors_control_service_1 = require("../../../_routes/server/errors/errors.control-service");
+const fam_dup_audit_data_service_1 = require("./fam-dup-audit.data-service");
+const fam_exact_duplication_control_service_1 = require("./fam-exact-duplication.control-service");
+/**
+ * `FAM_DupAudit_ControlService` (dup-v2, task #20) — a **duplikáció-őrjárat** motorja: egy exact dup-mérés a
+ * kanonikus default szűrőkkel + coverage-preflight + baseline-összevetés (delta-%) + az ÚJONNAN megjelenő
+ * széles (≥4 projektes) csoportok riasztása (`DyFM_Log.warn` + persistált warning-hiba). A pillanatkép a
+ * `fam_dup_audits`-ba kerül (bounded retention) — a trend dokumentált, nem csak memória.
+ */
+class FAM_DupAudit_ControlService {
+    static _instance;
+    issuer = 'FAM_DupAudit_ControlService';
+    /** A perzisztált top-csoportok száma (bounded rekord — a trendhez a top-50 bőven elég). */
+    static TOP_GROUPS = 50;
+    /** A kanonikus default szűrők (a heti őrjárat MINDIG ezzel fut → a futások összevethetők). */
+    static DEFAULT_FILTERS = {
+        table: fam_table_type_enum_1.FAM_Table.codebase,
+        minProjects: 1,
+        minContentLength: 200,
+        excludeRootRegex: 'STALE-projects',
+    };
+    static getInstance() {
+        if (!FAM_DupAudit_ControlService._instance) {
+            FAM_DupAudit_ControlService._instance = new FAM_DupAudit_ControlService();
+        }
+        return FAM_DupAudit_ControlService._instance;
+    }
+    /**
+     * Egy teljes őrjárat-futás: exact-mérés (default szűrők + coverage) → delta az előző ÖSSZEVETHETŐ futáshoz →
+     * új-széles-csoport riasztás (első futásnál NINCS warn — nincs baseline) → persist + retention.
+     * A hívó (scheduler) felelőssége a try/catch (az audit-hiba nem döntheti a tick-et).
+     */
+    async runAudit(trigger) {
+        const runAt = Date.now();
+        const filters = {
+            ...FAM_DupAudit_ControlService.DEFAULT_FILTERS,
+            maxGroups: FAM_DupAudit_ControlService.TOP_GROUPS,
+            includeCoverage: true,
+        };
+        const result = await fam_exact_duplication_control_service_1.FAM_ExactDuplication_ControlService.getInstance().run(filters);
+        // Baseline: a legutóbbi audit UGYANERRE a tárra (lazy DS — eager-resolve elkerülés).
+        const dataService = new fam_dup_audit_data_service_1.FAM_DupAudit_DataService({ issuer: this.issuer });
+        const previous = await dataService.findLatest(String(result.table));
+        // Delta CSAK azonos filter-echo-hoz (különben previousIncomparable — nincs hamis trend).
+        const delta = FAM_DupAudit_ControlService.computeDelta({
+            currentFilters: result.filters,
+            currentTotalGroups: result.totals.totalGroups,
+            currentWastedChars: result.totals.wastedChars,
+            previous: previous,
+        });
+        // ÚJ ≥4-projektes csoportok az előző futáshoz képest (a duplikáció-TERJEDÉS jele). Első futásnál nincs warn.
+        const newWideHashes = FAM_DupAudit_ControlService.diffNewMultiProjectHashes(result.multiProjectGroupHashes, previous?.multiProjectGroupHashes);
+        if (previous && newWideHashes.length) {
+            const message = `[FAM dup-audit] ${newWideHashes.length} ÚJ ≥4-projektes exact-dup csoport jelent meg `
+                + `az előző őrjárat óta a '${result.table}' táron (terjedő duplikáció — bedrock-konszolidáció jelölt). `
+                + `Hash-ek (első 10): ${newWideHashes.slice(0, 10).join(', ')}`;
+            fsm_dynamo_1.DyFM_Log.warn(message);
+            await errors_control_service_1.FAM_Error_ControlService.getInstance().emit({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.scanDupAuditNewGroup,
+                message: message,
+                level: fsm_dynamo_1.DyFM_ErrorLevel.warning,
+                context: { operation: 'dup-audit:new-wide-groups' },
+            });
+        }
+        // Persist + retention (bounded history).
+        const audit = new fam_dup_audit_data_model_1.FAM_DupAudit_DataModel({
+            runAt: runAt,
+            table: String(result.table),
+            trigger: trigger,
+            filters: result.filters,
+            totalGroups: result.totals.totalGroups,
+            redundantCopies: result.totals.redundantCopies,
+            wastedChars: result.totals.wastedChars,
+            topGroups: result.groups.slice(0, FAM_DupAudit_ControlService.TOP_GROUPS),
+            multiProjectGroupHashes: result.multiProjectGroupHashes,
+            zeroEntryProjects: result.coverage?.zeroEntryProjects ?? [],
+            staleProjectCount: result.coverage?.staleProjects.length ?? 0,
+            deltaGroupsPct: delta.deltaGroupsPct,
+            deltaWastedPct: delta.deltaWastedPct,
+            previousIncomparable: delta.previousIncomparable,
+        });
+        const saved = await dataService.persistAudit(audit);
+        const purged = await dataService.applyRetention(String(result.table));
+        fsm_dynamo_1.DyFM_Log.log(`[FAM dup-audit] őrjárat KÉSZ (${trigger}): ${result.totals.totalGroups} csoport, `
+            + `${result.totals.wastedChars} wasted char, ${newWideHashes.length} új széles csoport`
+            + `${delta.deltaGroupsPct !== undefined ? `, Δcsoport ${delta.deltaGroupsPct.toFixed(1)}%` : ' (nincs baseline)'}`
+            + `${purged ? `, ${purged} régi audit-rekord törölve (retention)` : ''}.`);
+        return saved;
+    }
+    /**
+     * **PURE** delta-számítás: az előző futáshoz képesti %-os változás — de CSAK azonos filter-echo esetén
+     * (a szűrő-váltás utáni összevetés hamis trendet adna → `previousIncomparable:true` + nincs delta).
+     * Nincs előzmény → nincs delta és nem incomparable (első futás — baseline-építés).
+     */
+    static computeDelta(set) {
+        if (!set.previous) {
+            return { previousIncomparable: false };
+        }
+        const sameFilters = JSON.stringify(FAM_DupAudit_ControlService.normalizeFilters(set.currentFilters))
+            === JSON.stringify(FAM_DupAudit_ControlService.normalizeFilters(set.previous.filters ?? {}));
+        if (!sameFilters) {
+            return { previousIncomparable: true };
+        }
+        return {
+            deltaGroupsPct: FAM_DupAudit_ControlService.pctChange(set.previous.totalGroups ?? 0, set.currentTotalGroups),
+            deltaWastedPct: FAM_DupAudit_ControlService.pctChange(set.previous.wastedChars ?? 0, set.currentWastedChars),
+            previousIncomparable: false,
+        };
+    }
+    /** **PURE** diff: a jelen ≥4-projektes hash-ei MÍNUSZ az előzők (az ÚJONNAN megjelenő széles csoportok). */
+    static diffNewMultiProjectHashes(current, previous) {
+        const previousSet = new Set(previous ?? []);
+        return current.filter((hash) => !previousSet.has(hash));
+    }
+    /** %-os változás (előző 0 → 0, ha a jelen is 0; egyébként 100 — a nulláról-indulás teljes növekedés). */
+    static pctChange(previous, current) {
+        if (previous === 0) {
+            return current === 0 ? 0 : 100;
+        }
+        return ((current - previous) / previous) * 100;
+    }
+    /** A filter-echo determinista (kulcs-rendezett, undefined-mentes) normalizálása az összevetéshez. */
+    static normalizeFilters(filters) {
+        const raw = filters;
+        const normalized = {};
+        for (const key of Object.keys(raw).sort()) {
+            if (raw[key] !== undefined && raw[key] !== null) {
+                normalized[key] = raw[key];
+            }
+        }
+        return normalized;
+    }
+}
+exports.FAM_DupAudit_ControlService = FAM_DupAudit_ControlService;

package/build/src/_modules/embedding/_services/fam-dup-audit.data-service.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_DupAudit_DataService = void 0;
+const tslib_1 = require("tslib");
+const mongoose_1 = tslib_1.__importDefault(require("mongoose"));
+const nts_dynamo_1 = require("@futdevpro/nts-dynamo");
+const fam_dup_audit_data_model_1 = require("../../../_models/data-models/fam-dup-audit.data-model");
+/**
+ * `FAM_DupAudit_DataService` (dup-v2, task #20) — a `fam_dup_audits` collection CRUD-ja. A control-service-ek
+ * NEM tartanak élő példányt mezőként (memory: dynts_dataservice_eager_resolve — a base-ctor eager DB-resolve-ot
+ * hív) — minden művelet előtt lazy `new`.
+ */
+class FAM_DupAudit_DataService extends nts_dynamo_1.DyNTS_DataService {
+    /** A megtartott audit-futások száma tárankint (bounded history — a trend ennyiből bőven látszik). */
+    static RETENTION_COUNT = 20;
+    constructor(set) {
+        super(new fam_dup_audit_data_model_1.FAM_DupAudit_DataModel(), fam_dup_audit_data_model_1.famDupAudit_dataParams, set.issuer);
+    }
+    /** Egy audit-pillanatkép perzisztálása. */
+    async persistAudit(audit) {
+        return this.saveData(audit);
+    }
+    /** A legutóbbi audit egy tárra (`runAt` DESC; nincs → undefined). A baseline/delta-összevetés bemenete. */
+    async findLatest(table) {
+        const collection = this.rawCollection();
+        if (!collection) {
+            return undefined;
+        }
+        const docs = await collection
+            .find({ table: table, _deleted: null })
+            .sort({ runAt: -1 })
+            .limit(1)
+            .toArray();
+        return docs[0];
+    }
+    /**
+     * Retention: tárankint csak az utolsó `RETENTION_COUNT` futás marad — a régebbiek RAW `deleteMany`-vel
+     * FIZIKAILAG törlődnek. **Indoklás (miért raw + hard delete):** az audit-rekord rendszer-generált,
+     * determinisztikusan ÚJRA-előállítható pillanatkép (nem user-tartalom, nem pótolhatatlan) — az
+     * `addArchive:false` + bounded fizikai törlés a helyes költség-profil; a soft-delete/archív itt csak
+     * korlátlanul növekvő junk-ot halmozna. Visszaadja a törölt rekordok számát.
+     */
+    async applyRetention(table) {
+        const collection = this.rawCollection();
+        if (!collection) {
+            return 0;
+        }
+        // A megtartandó legfrissebb N runAt-ja — az N+1-ediktől lefelé minden törölhető.
+        const keep = await collection
+            .find({ table: table }, { projection: { runAt: 1 } })
+            .sort({ runAt: -1 })
+            .limit(FAM_DupAudit_DataService.RETENTION_COUNT)
+            .toArray();
+        if (keep.length < FAM_DupAudit_DataService.RETENTION_COUNT) {
+            return 0;
+        }
+        const cutoff = keep[keep.length - 1]?.runAt ?? 0;
+        const result = await collection.deleteMany({ table: table, runAt: { $lt: cutoff } });
+        return result.deletedCount ?? 0;
+    }
+    /** A regisztrált mongoose-collection (a ctor DS-példányosítása regisztrálja a modellt). */
+    rawCollection() {
+        return mongoose_1.default.models[fam_dup_audit_data_model_1.famDupAudit_dataParams.dataName]?.collection;
+    }
+}
+exports.FAM_DupAudit_DataService = FAM_DupAudit_DataService;